智能体开发

本页说明了 InnoClaw 中与智能体相关功能、工具调用流程以及 deep-research 编排有关的贡献者要求。

主要代码区域

智能体与研究执行相关的行为分布在几个核心区域中：

• src/app/api/agent/ 与 src/app/api/deep-research/ 负责 HTTP 入口

• src/lib/ai/ 负责 provider 选择、prompts、运行时能力检查以及工具注册

• src/lib/ai/tools/ 负责具体工具实现与共享工具类型

• src/lib/agent/ 负责流式生命周期与持久化行为

• src/lib/deep-research/ 负责 doctrine 加载、角色定义、编排、工作流策略与执行辅助逻辑

• src/lib/skills/ 负责技能导入以及以仓库为后端的技能工作流

• src/components/agent/ 与 src/components/deep-research/ 负责暴露智能体状态与工作流进度的 UI 界面

架构规则

• 保持 route handler 足够轻薄。它们只负责解析输入、校验上下文、选择正确的编排路径，并将非简单逻辑下放到 src/lib/。

• 将 prompts 放在 prompt 模块或 doctrine/role 文件中，不要把大段 prompt 文本直接嵌入 route handler 或 React 组件里。

• 将 provider、model 与运行时能力逻辑集中在 src/lib/ai/ 中，以保证各个智能体入口行为一致。

• 将 src/lib/ai/tool-names.ts 视为工具标识与权限分层的公开契约。

智能体变更流程

        flowchart LR
    Start["Plan an agent change"] --> Type{"What changed?"}
    Type -- "Prompt or role" --> Prompt["Review prompt files, doctrine, parsers, and UI labels"]
    Type -- "Tool or privilege" --> Tool["Review tool names, gates, selectors, and allow/deny tests"]
    Type -- "Streaming or session" --> Stream["Review route, stream manager, persistence, and resume UI"]
    Type -- "Deep-research workflow" --> Research["Review doctrine, roles, workflow policy, routes, and UI states"]
    Prompt --> Verify["Add tests and update docs if contributor-facing"]
    Tool --> Verify
    Stream --> Verify
    Research --> Verify
    Verify --> Audit{"High-risk execution path?"}
    Audit -- "Yes" --> Approval["Confirm approval gates and audit trail remain intact"]
    Audit -- "No" --> Ship["Prepare handoff with changed contracts and validation"]
    Approval --> Ship
    

        flowchart LR
    Start["规划一次智能体变更"] --> Type{"变更类型是什么?"}
    Type -- "Prompt 或角色" --> Prompt["联查 prompt 文件、doctrine、解析器与 UI 标签"]
    Type -- "工具或权限" --> Tool["联查工具名称、门控、选择器与 allow/deny 测试"]
    Type -- "流式输出或会话" --> Stream["联查路由、stream manager、持久化与恢复 UI"]
    Type -- "Deep-research 工作流" --> Research["联查 doctrine、角色、工作流策略、路由与 UI 状态"]
    Prompt --> Verify["补充测试，并在影响贡献者时更新文档"]
    Tool --> Verify
    Stream --> Verify
    Research --> Verify
    Verify --> Audit{"是否涉及高风险执行路径?"}
    Audit -- "是" --> Approval["确认审批门控与审计链路仍然完整"]
    Audit -- "否" --> Ship["准备交接说明，并列出变更契约与验证"]
    Approval --> Ship
    

在为智能体相关变更提交 PR 之前，请先使用这套流程。它能快速帮您识别最常见的跨层回归。

变更矩阵

当您修改以下任一面向智能体的契约时，请一并检查对应的联动面：

• Prompt、doctrine 或角色文本变更：同时检查 prompt 模块、doctrine 文件、角色注册表、依赖它们的解析器，以及依赖这些名称或指令的 UI 文案与状态标签。

• 新增工具或工具重命名：同时检查 src/lib/ai/tool-names.ts、工具实现、allow/deny 逻辑、相关选择器 UI，以及描述该能力的贡献者文档。

• 权限层级或审批流程变更：同时检查工具门控、运行时能力检查、UI 交互提示，以及允许/拒绝两条路径的测试。

• 流式输出或会话持久化变更：同时检查 route 入口、src/lib/agent/agent-stream-manager.ts、持久化辅助逻辑，以及负责恢复或展示进行中状态的 UI 组件。

• Deep-research 工作流变更：同时检查 doctrine 加载、角色注册表、工作流策略、artifact/status 类型、API 路由，以及依赖这些步骤或状态存在的 UI 组件。

工具与权限边界

• 将新工具实现添加到 src/lib/ai/tools/ 下。

• 优先复用共享的工具上下文与校验辅助逻辑，不要临时引入零散的文件系统或 shell 访问。

• 新工具默认遵循最小权限原则。如果某项能力可能修改基础设施或触发远程执行，就应像现有高权限工具集一样进行门控。

• 除非您明确在做契约迁移，否则应保持工具名称稳定。重命名需要同步更新测试、文档以及所有相关的 UI 选择器界面。

• 不要让 prompt 文本成为高风险能力的唯一防线。真正的权限边界应体现在带类型的运行时检查与工具注册中。

流式输出、会话与 UI 状态

• 如果您修改了智能体流式输出的生成或消费方式，请一并检查 src/lib/agent/agent-stream-manager.ts 以及已挂载 UI 的行为。

• 当面板卸载、标签切换或后台任务继续运行时，必须保持恢复与持久化语义不变。

• 谨慎处理由 localStorage 支撑的键与会话标识符。应将它们视为 route、runtime 与 UI 各层之间的共享契约。

• 优先使用显式的状态迁移与可见错误，而不是静默 fallback；静默 fallback 容易掩盖事件丢失、工具不受支持或恢复失败。

Deep-Research 与多角色流程

• 让 researcher-doctrine.ts、role-registry.ts 与 workflow-policy.ts 之间的 doctrine 加载、角色定义与工作流策略保持一致。

• 当修改角色 prompts 或协作行为时，请检查依赖这些 artifact、步骤或状态存在的 API 路由与 UI 组件。

• 高风险执行路径必须继续保持审批驱动，并且可审计。

• 当新增角色、artifact 类型或工作流状态时，请验证它在持久化、导出/报告路径以及面向操作者的评审界面中是如何呈现的。

失败处理与可观测性

• 在客户端或操作员需要做出不同处理时，应返回显式、带类型的失败状态。

• 记录足够的 request、session、provider 或 tool 上下文，以便在无需从头复现的情况下定位编排失败。

• 除非用户体验明确告知了被跳过的能力，否则应避免静默 provider fallback 或静默抑制工具。

• 在修改远程执行、集群操作或其他高风险流程时，必须保持审批检查点与审计链路完整。

测试要求

请根据您修改的层级选择测试：

• 路由行为：src/app/api/**/route.test.ts

• Provider 或模型选择行为：src/lib/ai/ 下的测试

• 工具契约或解析行为：src/lib/ai/ 或 src/lib/skills/ 下的测试

• 流式/会话持久化行为：src/lib/agent/ 附近或受影响 UI 辅助逻辑附近的测试

• Deep-research 工作流逻辑：src/lib/deep-research/ 下的测试

至少，新引入的面向智能体行为应覆盖以下方面：

• 校验与错误路径

• 权限或工具访问边界

• 在行为不同处的 provider/runtime 分支

• 任何持久化的会话或工作流状态变化

智能体贡献者检查清单

在为智能体相关工作请求评审前，请确认：

• 变更矩阵中相关的契约联动面已被一并检查

• 测试同时覆盖成功路径与失败/拒绝路径

• 如果其他贡献者或操作员需要理解这项新能力，文档已经同步更新

• 交接说明已经明确指出变化的工具名称、审批边界、持久化键、工作流状态或环境要求

文档要求

当智能体相关变更影响以下内容时，请更新贡献者文档：

• 安装配置或必需环境变量

• 可用工具、权限边界或执行门控

• 贡献者在测试、调试或本地开发中的工作流

• 其他开发者很可能会继续扩展的路由或工作流契约

如果某项变更主要是内部实现，但引入了新的开发者扩展点，请在这里或最相关的开发文档页中记录该扩展点。