# Everything Agent 开发说明 ## 语言要求 - 永远使用中文与用户沟通。 - 代码注释、文档、测试名称和错误信息优先使用中文。 - 标识符使用清晰的英文名称；不要使用拼音命名变量、函数或类。 ## 项目目标 本项目的目标是构建一个个人助理 Agent。它需要能够： 1. 理解用户输入并维护会话上下文。 2. 通过模型推理和受控工具完成任务。 3. 管理可检索、可更新、可删除的个人记忆。 4. 可视化展示节点、路由、状态变化、模型调用、工具调用、耗时和错误。 5. 对外部写操作、敏感数据和循环执行提供清晰的安全边界。 不要把项目演变成通用工作流平台。设计决策应优先服务于“个人助理”和“执行过程透明”这两个核心目标。 ## 当前状态 - `src/engine/` 是当前 Node.js 基础引擎，实现了 State、Node、Graph、Describe 和 runGraph。 - `src/agent-loop/` 已实现基础 Agent Loop，`src/agent-graph/` 提供 Harness 拓扑，`src/tools/` 提供本地 Tool Registry；`src/model/` 已实现真实 LLM 协议适配，`src/memory/` 已实现本地 Session、SQLite 长期记忆、FTS5 检索与 consolidation。 - 文档必须明确区分已经实现的能力和规划能力，不得把路线图描述成现成功能。 ## 开发阶段兼容策略 - 项目目前处于需求开发阶段，一律不考虑旧代码、旧接口或旧数据的兼容性。 - 新需求与旧实现冲突时，直接删除冲突的旧代码和旧数据，按新需求实现；不要增加过渡适配器、兼容参数、遗留数据表，或为保留旧数据编写迁移、回填和旧索引重建逻辑。 - 这是已明确授权的开发规则，不要在方案讨论、访谈或实施中再次询问用户如何处理旧代码、旧接口或旧数据，也不要提出兼容方案供用户选择。 - 该策略不授权修改无关用户改动，也不放宽密钥、个人数据、依赖目录和生成物的保护要求。 ## 架构约束 ### Engine - Engine 保持模型、工具、数据库和 UI 无关，不在核心调度代码中直接初始化这些依赖。 - State 是共享黑板。节点读取状态快照并返回增量，不应原地修改输入状态。 - 同一 wave 的节点可以并行，但状态合并、路径和事件顺序必须确定且可重复。 - 并行节点写入相同键必须显式报错，不能使用最后写入者覆盖前者。 - 路由由普通代码执行。模型可以产生路由候选值，但代码必须验证标签后再改变控制流。 - 节点异常应转换为可观察的状态和事件；失败节点不能继续触发依赖其正常输出的普通边。 - 所有循环必须同时受到节点级 `maxVisits` 和运行级 `maxSteps` 保护。 ### 可视化与可观测性 - `Graph.describe()` 是静态拓扑的唯一事实来源。不要在前端手工复制节点和边。 - `runGraph` 的 observer 事件是动态执行过程的事实来源。UI 不应通过猜测最终状态还原执行路径。 - 新增执行能力时，需要同步考虑它应产生哪些事件，以及事件如何被回放和展示。 - 事件字段应可序列化，字段含义应明确；事件协议变更遵循开发阶段兼容策略，同步更新生产方、消费方、测试和文档，不保留旧协议兼容逻辑。 - 事件和状态展示必须支持敏感字段脱敏，禁止默认记录密钥、令牌或完整私人内容。 - 未来的事件至少应能关联 run、node、wave 和时间顺序，但在实现前不要伪造文档中的完成状态。 ### Agent Runtime - Agent 执行过程遵循 `observe → reason → act → repeat`，并设置迭代次数、超时和取消机制。 - 工具通过独立注册模块注入；模型不能自行创建任意工具或绕过参数验证。 - 读取操作与外部写操作需要区分。发送消息、修改日历、删除文件等操作必须保留确认策略和审计信息。 - 记忆模块必须支持来源、时间、范围和删除；不要把完整聊天记录无条件写入长期记忆。 ## 目录与模块规则 - `src/engine/src/state.ts`：状态容器、合并规则和状态冲突。 - `src/engine/src/node.ts`：节点接口及节点元数据。 - `src/engine/src/graph.ts`：拓扑声明和 describe。 - `src/engine/src/run-graph.ts`：调度、并发、路由、错误和生命周期事件。 - `src/engine/src/index.ts`：Engine 的公开接口。 - `src/engine/test/`：只通过公开接口验证可观察行为。 - `src/agent-loop/agent-loop.ts`：模型与工具无关的 Agent 回合循环；行为测试放在 `src/agent-loop/test/`。 - `src/agent-graph/`：Agent Harness 拓扑；行为测试放在 `src/agent-graph/test/`。 - `src/tools/`：本地工具注册表；行为测试放在 `src/tools/test/`。 - `src/model/model-client.ts`：独立于 Agent Runtime 的真实模型协议适配与配置接口；行为测试放在 `src/model/test/`。 - `src/memory/`：本地 Session、SQLite、FTS5 检索与 consolidation；行为测试放在 `src/memory/test/`。 - `src/agent-runtime/`：组合 Agent Loop、模型客户端、工具注册表、Memory 与 Tracer 的本地个人助理运行时；内部辅助模块（`configuration/`、`integrations/`、`events/`）不从 `index.ts` 导出，行为测试放在 `src/agent-runtime/test/`。 - `src/skills/`：基于 `.everything/skills//SKILL.md` 的按需过程知识存取；行为测试放在 `src/skills/test/`。 - `src/tracing/`：classic Agent Loop 与 Memory 的 JSONL 运行记录；行为测试放在 `src/tracing/test/`。 - `src/workflows/`：与 Engine、Agent 同级的本地工作流；行为测试放在 `src/workflows/test/`。 - `mock-data/`：与 `src`、`web` 同级的模拟数据工具；`datasets/` 存放数据集 JSON，其余为写入脚本，用本地模拟模型驱动真实 Runtime 把数据合并进现有数据目录，不参与产品运行；行为测试放在 `mock-data/test/`。 - `web/test/`：Web 模块的行为测试。 - `src/index.ts`：包的统一公开接口。 所有测试代码必须放在被测模块同级的 `test/` 目录中，不得与实现文件混放；测试文件统一使用 `*.test.ts` 或 `*.test.tsx` 命名。 新增模块时应保持接口小而稳定，把调度或集成复杂度封装在模块内部。除非确实存在两个实现，不要提前增加抽象层或适配器接口。 ## 编码规范 - 涉及 Node.js 包管理的操作一律使用 `pnpm`，包括依赖安装、添加、更新、删除、脚本运行和包命令执行；使用 `pnpm exec` 或 `pnpm dlx` 执行工具，不使用 `npm`、`npx`、`yarn` 或其他包管理器。文档和命令示例同步使用 `pnpm`，锁文件统一使用 `pnpm-lock.yaml`。 - 当前 Engine 使用 Node.js 24.12+、ESM 和严格模式 TypeScript；后端由 Node.js 原生类型擦除直接运行，不生成 JavaScript 构建目录。 - Engine 核心保持零运行时依赖；其他后端模块可以为明确的产品能力引入必要依赖，但应控制依赖范围，避免为简单功能增加大型框架或未经使用的间接层。测试和开发工具可以作为 `devDependencies`。 - 公共类和函数需要简洁的中文 JSDoc，解释接口约定和重要错误模式。 - 注释解释设计原因、执行语义或容易误解的约束，不逐行复述代码。 - 修改现有代码时尽量保留有价值的注释；只有在注释已过时、与实现冲突或明显冗余时才删除，并在行为变更后同步更新相关注释。 - 优先使用明确的数据结构和返回值，避免隐式全局状态。 - 不吞掉异常。要么抛出调用方可处理的错误，要么记录到运行状态并发送事件。 - 不提交密钥、`.env`、个人数据、模型原始敏感输入、`node_modules` 或覆盖率产物。 - 保留用户已有改动。不要修改与当前任务无关的文件，也不要恢复用户主动删除的旧代码。 ## Git 提交规范 - 完成当前任务并通过必要检查后，可以自行执行 `git commit`，无需再次确认；允许将用户此前已有的改动一并全量提交，但必须保留其内容，不擅自覆盖或撤销。 - 提交信息使用简洁的中文，准确描述实际变更及其目的。 - 提交标题、正文和尾注中不得添加 AI、Codex 或其他智能助手协助开发、生成代码的声明或署名，也不得添加此类助手的 `Co-authored-by` 尾注。 - 使用仓库现有的 Git 作者配置，不擅自修改提交身份。 ## 测试要求 - 修改前端样式时，不得调用浏览器进行验证，包括 Codex 内置浏览器及其他浏览器工具；不需要进行视觉验证，也不要截图或执行视觉回归检查。 - 测试框架使用 Vitest，配置位于根目录 `vitest.config.ts`。 - 测试 seam 是 `src/index.ts` 或对应模块公开入口导出的接口，不测试私有字段或内部辅助实现。 - 每个行为变更都需要测试；修复缺陷时先添加能够复现问题的失败测试。 - 并发测试不能依赖不稳定的固定延时，应使用可控 Promise、fake timer 或明确同步点。 - 新增 observer 事件时，测试事件名称、关键字段和相对顺序。 - 新增 Graph 能力时，同时测试 `describe()` 与实际执行，确保拓扑和运行语义一致。 - 最低覆盖率：语句、函数和行 85%，分支 80%。覆盖率不是替代行为断言的目标。 常用命令： ```bash pnpm install pnpm run typecheck pnpm run build pnpm test pnpm run test:coverage pnpm run example ``` ## 文档要求 - 根目录 `README.md` 描述项目目标、总体架构、当前进度和路线图。 - `src/engine/README.md` 描述 Engine 的公开接口、执行语义和示例。 - `src/agent-loop/README.md` 描述 Agent Loop 的依赖接口、执行语义和事件。 - `src/agent-graph/README.md` 描述 Agent Harness 的静态拓扑与可视化边界。 - 行为、事件或命令发生变化时，在同一个任务内同步更新相关文档。 - Mermaid 或架构图必须从真实模块关系出发，并明确标记尚未实现的部分。 ## 完成标准 一个实现任务只有在满足以下条件时才算完成： 1. 功能通过公开接口可用，并符合个人助理 Agent 的项目方向。 2. 必要的中文注释和文档已经更新。 3. 相关 Vitest 测试通过，覆盖率门槛没有下降。 4. 示例仍可运行，包仍可被 Node.js 正常加载。 5. 新的执行过程能够通过 describe 或 observer 被可视化层观察。 6. 没有提交依赖目录、生成物、密钥或个人数据。 ## Evaluation 模块 - `src/evaluation/`：独立离线回归评估；固定测试集、隔离运行、DeepEval TypeScript 评分、比较与发布门槛。行为测试位于 `src/evaluation/test/`，使用说明位于 `src/evaluation/README.md`。 - `.evaluations/`：评估运行数据，不能提交；与 `.everything/` 分离。 - `web/server/evaluation-service.ts`、`web/src/evaluation-api.ts`、`web/src/pages/evaluation/`：Evaluation 页面与服务接入。 - 评估不得将未匹配的 fixture 回退成真实外部工具调用，不得因评分失败、缺失用量或未完成运行而自动判定发布通过。