关注点分离（Separation of Concerns）示例（AI Agent 架构、流程编排、数据契约、提示词工程）

Agent 功能的架构约定图放 services/agent/graphs/，必须定义显式 TypedDict 输入/输出 state schema；prompt 一律放 services/agent/prompts/，不许内联在图代码里。

为什么要这么设计？

这套 Agent 架构约定的设计意图

你描述的这条规范本质上是在做关注点分离（Separation of Concerns），把 Agent 系统拆成了三个正交的维度：流程编排、数据契约、提示词工程。下面逐条拆解为什么要这么做。

1. Graph 放services/agent/graphs/+ 显式 TypedDict State Schema

为什么不直接用dict或TypedDict内联在函数签名里？

# ❌ 松散做法 — 上下游节点靠"默契"传字段defnode_a(state:dict)->dict:state["foo"]="bar"returnstate# ✅ 规范做法 — 显式契约classAgentState(TypedDict):messages:list[BaseMessage]plan:strtool_results:list[dict]is_complete:bool

2. Prompt 放services/agent/prompts/，禁止内联

这是整条规范里最实用的一条，原因至少有四层：

① 角色分离：写 Prompt 的 ≠ 写 Graph 的

Prompt 工程师 / 产品人员 → 改 prompts/xxx.txt 后端工程师 → 改 graphs/xxx.py

Prompt 调优是高频迭代，如果 prompt 写在 Python 代码里，每次改个措辞都要触碰业务代码、跑完整 CI、有合并冲突风险。

② 版本管理 & A/B 实验

prompts/ planner_v1.txt planner_v2.txt ← 灰度实验，直接切文件 tool_router.txt summarizer.txt

放在独立文件里，可以：

• 用 Git 对 prompt 单独做 diff / blame / 回滚
• 按版本命名做 A/B test
• 未来迁移到 Prompt 管理平台（LangSmith、Helicone 等）零成本

③ 可观测性 & 成本追踪

集中管理后，很容易加一层统一的 loader，顺带做：

• Token 计数 / 成本预估
• Prompt 注入检测
• 变量注入审计（哪些{variable}被填充了什么值）

如果 prompt 散落在各个.py文件里，这些横切逻辑就没地方挂。

④ 防止 Prompt 与逻辑耦合

# ❌ 内联 — prompt 和流程控制混在一起，改 prompt 可能误改逻辑defplanner_node(state):response=llm.invoke(f"""你是一个规划助手。 用户的请求是:{state['input']}如果涉及代码，请调用 code_tool... # ← 这是 prompt 还是业务规则？ """)...# ✅ 分离 — 各管各的# prompts/planner.txt# graphs/planner.pydefplanner_node(state:PlannerInput)->PlannerOutput:prompt=load_prompt("planner",input=state["input"])response=llm.invoke(prompt)...

3. 整体目录结构的意图

services/agent/ ├── graphs/ ← 流程编排（"怎么走"） │ ├── main_agent.py │ └── sub_graphs/ ├── prompts/ ← 提示词（"怎么说"） │ ├── planner.txt │ └── tool_router.txt ├── tools/ ← 工具实现（"用什么做"） └── schemas.py ← TypedDict 定义（"数据长什么样"）

这四个目录对应了 Agent 系统的四个独立变化频率：

变化频率不同的东西不应该放在同一个文件里——这是软件设计里最朴素也最重要的原则之一。

一句话总结

这套约定的核心目的是：让 prompt 调优、图编排、数据契约三件事可以独立演进、独立测试、独立 review，互不拖累。在 Agent 系统这种 prompt 改动频率远高于代码的系统里，这种分离不是洁癖，而是生存需要。