everything-agent

Imported from z114880/everything-agent (AGENTS.md). Install upstream with npx skills add z114880/everything-agent. Copyright stays with the author.

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/。
• 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%。覆盖率不是替代行为断言的目标。

常用命令：

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/：个人助理固定数据集回归；Langfuse 数据集版本、当前 Agent 隔离运行、确定性检查、平台自动裁判与评估结论。行为测试位于 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 回退成真实外部工具调用；只有显式开启 terminal 的用例可在受控沙箱内真实执行。评分失败、同步失败或未完成运行不得自动判定通过；费用与用量只作观察指标，不作为质量硬门槛。