smartmate/backend/agent/通用能力接入文档.md

agent 通用能力接入文档

1. 文档目的

本文用于说明 backend/agent 目录下“通用能力”的职责边界、放置位置和接入约束，避免后续继续出现“同一类能力复制三份、四份”的情况。

这里的“通用能力”特指：

1. 会被两个及以上能力域复用，或者已经明确会继续扩散的基础能力。
2. 与具体业务语义弱耦合，抽出来后不会把某个 skill 的 prompt、状态字段、业务规则污染到其它模块。
3. 抽出后能显著减少样板代码、降低迁移成本，或者统一链路行为。

本文不负责描述某个具体 skill 的业务流程。业务流程、状态机、prompt 细节，仍应放在对应能力域自己的文件中。

2. 当前目录分层

backend/agent/
  entrance.go
  chat/
  graph/
  llm/
  model/
  node/
  prompt/
  router/
  shared/
  stream/

2.1 entrance.go

职责：

1. 作为 agent 模块对上层 service 的统一入口。
2. 负责装配路由器与各能力 handler。
3. 不负责具体 graph 逻辑、不负责直接调模型、不负责工具执行。

2.2 router/

职责：

1. 负责一级分流，把请求映射到具体能力链路。
2. 维护统一的请求/响应结构和 action 定义。
3. 不承载具体 skill 的业务判断细节。

适合放入这里的能力：

1. 路由请求结构。
2. action 解析与分发。
3. 对上层稳定暴露的最小门面。

2.3 graph/

职责：

1. 只负责组图、连线和节点编排。
2. 文件里应尽量只出现节点挂载、分支和边定义。
3. 不直接写复杂业务逻辑、不直接调 DAO、不直接拼 prompt。

2.4 node/

职责：

1. 承接能力域的核心业务节点实现。
2. 按“节点逻辑文件 + 工具文件”的双文件格局组织复杂能力域。
3. 在确实存在多节点复用时，可下沉少量带业务语义的 node 内部公共 helper。

当前约定：

1. schedule_plan.go / schedule_plan_tool.go 为一组。
2. schedule_refine.go / schedule_refine_tool.go 为一组。
3. quicknote.go / quicknote_tool.go、taskquery.go / taskquery_tool.go 同理。

补充说明：

1. node/tool_common.go 是 node 层内部通用工具聚合点。
2. 这里只放“被两个及以上节点复用、但仍带一点节点上下文语义”的 helper。
3. 如果某个能力已经弱化到与业务无关，应继续下沉到 shared/，而不是长期堆在 tool_common.go。

2.5 llm/

职责：

1. 统一封装模型调用、JSON 解析、推理参数和模型侧协议。
2. 让上层节点尽量只关心“要什么结果”，不重复实现 SDK 样板代码。
3. 不承载具体业务状态流转。

2.6 model/

职责：

1. 统一放置 agent 内部状态结构、输入输出 DTO、默认预算等模型无关定义。
2. 不在这里写业务执行逻辑。

2.7 prompt/

职责：

1. 维护系统提示词、结构化输出模板、路由提示词等文本资产。
2. 不在 prompt 文件中写节点控制流和工具编排。

2.8 stream/

职责：

1. 统一承接 SSE chunk 包装、阶段推送、OpenAI/Ark 流式适配。
2. 保证上层 service 不需要重复拼装流协议。

2.9 shared/

职责：

1. 放置跨能力域复用的纯工具能力，例如时间、重试、深拷贝等。
2. 要求业务语义尽量弱、依赖尽量少。
3. 一旦某类逻辑已经被第二处复用，必须优先评估是否放到这里。

3. 什么该抽成通用能力

满足以下任一条件时，必须优先评估抽公共层：

1. 同类逻辑已经出现第二份实现。
2. 不同 skill 的实现只有参数不同，控制流基本一致。
3. 上层 service 已经开始出现重复胶水代码。
4. 继续复制会增加迁移、测试或回归排查成本。

常见应优先考虑抽取的方向：

1. 模型调用门面。
2. JSON 容错解析。
3. SSE 阶段推送与 chunk 包装。
4. 深拷贝与快照转换。
5. 缓存快照读写辅助逻辑。

4. 什么不该抽成通用能力

以下内容默认不应抽到公共层：

1. 某个 skill 独有的 prompt 片段。
2. 只服务单一业务的状态字段映射。
3. 带强业务语义的 ReAct 决策规则。
4. 只在一个节点里短期使用、且没有第二处复用证据的 helper。

判断原则：

1. 若抽出来后名字仍然需要带明显业务词，通常说明它还不够通用。
2. 若抽出来会让其它模块被迫理解某个 skill 的内部规则，说明抽取层级过早。

5. 新增能力时的落点规则

1. 纯工具、弱业务语义、跨域复用：优先放 shared/。
2. 只在路由阶段复用：放 router/。
3. 只与模型协议相关：放 llm/。
4. 只与流式输出相关：放 stream/。
5. 只在 node 层内被多个节点复用，且带少量业务上下文：放 node/tool_common.go 或同层 helper。
6. 仍然明显属于某个能力域：留在对应 node/、prompt/、model/ 文件中，不要硬抽。

6. 变更要求

后续若在 backend/agent 中新增、下沉、替换任何通用能力，必须同步完成以下动作：

1. 更新本文档，说明新能力放在哪一层、为什么放这里。
2. 说明是否替代了旧实现，旧实现是否已经删除。
3. 检查是否还残留第三份及以上重复实现。
4. 若本轮只是暂时无法抽公共层，必须在代码注释或文档里写明原因。

7. 当前结构结论

截至当前版本，backend/agent 已是唯一正式实现目录，backend/service/agentsvc 也已与历史旧路径完全解耦。

后续重构优先级建议：

1. 继续收口 node 层内部重复的查询/校验/移动辅助逻辑。
2. 持续把 service 层里可复用的旁路读写逻辑下沉到更稳定的公共层。
3. 保持 graph 只做编排、node 只做业务、shared 只做弱语义公共能力，避免重新堆回大杂烩结构。