git:20260911.9de413b to git:20260913.6df439d

# Everything Agent 的 Claude Code 工作规则

本文件是 Claude Code 在本仓库工作的入口约定。**项目规则的唯一事实来源是根目录 [`AGENTS.md`](AGENTS.md)**：开始任何实现任务前先读它，本文件只做重点提要与 Claude Code 侧的补充，两者冲突时以 `AGENTS.md` 为准。

## 必须先读

- `AGENTS.md`：语言要求、项目目标、架构约束、目录规则、编码规范、测试与文档要求、完成标准。

- `README.md`：项目目标、总体架构、当前进度与路线图。

- 涉及具体模块时，读该模块的 `README.md`（`src/engine/`、`src/agent-loop/`、`src/agent-graph/`）。

## 沟通与写作

- 永远使用中文与用户沟通。

- 代码注释、文档、测试名称、错误信息优先使用中文；标识符使用清晰英文，禁止拼音命名。

- 公共类和函数需要简洁的中文 JSDoc，说明接口约定与重要错误模式。

## 项目方向

构建**个人助理 Agent**，核心是「个人助理」与「执行过程透明」两个目标。不要把项目演变成通用工作流平台，也不要把路线图写成已实现能力。

## 最容易违反的几条硬规则

1. **包管理只用 `pnpm`**：依赖安装/添加/更新/删除、脚本运行、包命令一律 `pnpm` / `pnpm exec` / `pnpm dlx`，禁止 `npm`、`npx`、`yarn`；文档命令示例同步使用 `pnpm`。

2. **不考虑兼容性**：需求开发阶段，新需求与旧实现冲突时直接删除旧代码与旧数据，不写适配器、兼容参数、遗留表或迁移回填逻辑。**这是已授权规则，不要再就旧代码/旧接口/旧数据的处理方式询问用户或提供兼容方案选项。**

3. **测试与实现分离**：测试一律放在被测模块同级的 `test/` 目录，命名为 `*.test.ts` / `*.test.tsx`，不与实现文件混放。

4. **测试 seam 是公开接口**：只测 `src/index.ts` 或模块公开入口导出的接口，不测私有字段与内部辅助实现。

5. **前端样式改动禁止浏览器验证**：不调用任何浏览器工具，不截图，不做视觉回归检查。

6. **提交信息中禁止任何 AI 协助署名**：标题、正文、尾注都不得出现 AI/Codex/助手生成声明，也不得添加此类 `Co-authored-by` 尾注；使用仓库现有 Git 作者配置。

7. **保留用户已有改动**：不修改与当前任务无关的文件，不恢复用户主动删除的代码。

8. **不提交敏感物**：密钥、`.env`、个人数据、模型原始敏感输入、`node_modules`、覆盖率产物一律不提交。

## 架构红线（详见 `AGENTS.md` 的「架构约束」）

- Engine 与模型、工具、数据库、UI 无关，核心调度不直接初始化这些依赖；Engine 核心保持零运行时依赖。

- State 是共享黑板：节点读快照、返回增量，不原地修改输入状态；并行节点写同一键必须显式报错。

- 路由由普通代码执行并验证标签；模型只能产生候选值。

- 所有循环同时受节点级 `maxVisits` 与运行级 `maxSteps` 保护。

- `Graph.describe()` 是静态拓扑唯一事实来源，`runGraph` 的 observer 事件是执行过程唯一事实来源；前端不得手工复制拓扑或猜测执行路径。

- 事件与状态展示必须支持敏感字段脱敏，默认不记录密钥、令牌或完整私人内容。

- Agent 遵循 `observe → reason → act → repeat`，带迭代上限、超时与取消；外部写操作需区分于读取并保留确认与审计。

- 记忆必须支持来源、时间、范围与删除，不把完整聊天记录无条件写入长期记忆。

## 常用命令

```bash

pnpm install

pnpm run typecheck

pnpm test

pnpm run test:coverage

pnpm run build

pnpm run example

```

## 交付前自查

对照 `AGENTS.md` 的「完成标准」逐条确认：

1. 功能通过公开接口可用，方向符合个人助理 Agent。

2. 中文注释与相关文档（`README.md` 及模块 README）已在同一任务内同步更新。

3. Vitest 测试通过，覆盖率不低于语句/函数/行 85%、分支 80%。

4. 示例仍可运行，包仍能被 Node.js 正常加载。

5. 新执行能力可通过 `describe()` 或 observer 事件被可视化层观察。

6. 未提交依赖目录、生成物、密钥或个人数据。

完成任务并通过必要检查后可自行 `git commit`（提交信息用简洁中文，可一并全量提交用户已有改动，但必须保留其内容）。