git:20260913.ae1c00a to git:20260913.3783e3d

# 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-name>/SKILL.md` 的按需过程知识存取；行为测试放在 `src/skills/test/`。

- `src/tracing/`：classic Agent Loop 与 Memory 的 JSONL 运行记录；行为测试放在 `src/tracing/test/`。

- `src/workflows/`：与 Engine、Agent 同级的本地工作流；行为测试放在 `src/workflows/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. 没有提交依赖目录、生成物、密钥或个人数据。