ai-agent-deep-dive/docs/01-system-prompt-and-orchestration.md

01. 系统提示词与 Agent 编排需求文档

1. 系统提示词为什么不是一段固定文案

从源码结构可以反推，这个产品要求系统提示词具备“动态拼装”能力，而不是固定模板。

需求原因

用户环境、工具集、语言、输出风格、会话状态、MCP 连接状态都可能变化。如果系统提示词不能动态组装，就会出现：

• 规则不匹配当前会话
• 工具说明失效
• 记忆无法注入
• token 成本失控

2. 系统提示词层的核心需求

2.1 基础身份定义

系统需要明确告诉模型：

• 你是执行型协作者
• 你的主要任务是软件工程支持
• 你的输出直接给用户看

2.2 做任务规范

系统需要内建一套工程行为规范，例如：

• 不要乱加功能
• 不要过度抽象
• 不要假装验证过
• 先读代码再改代码
• 不要随意创建文件

这不是“风格偏好”，而是稳定性需求。

2.3 风险动作规范

系统需要明确哪些操作有 blast radius，需要额外确认。例如：

• 删除
• 推送
• 外部可见动作
• 修改共享状态

2.4 工具使用语法

系统不仅要告诉模型“有什么工具”，还要告诉它：

• 什么时候读文件
• 什么时候搜索
• 什么时候编辑
• 什么时候用 shell
• 什么时候并行调用

3. 动态区块需求

系统提示词至少需要支持以下动态区块：

1. 环境信息
2. 当前语言偏好
3. 输出风格
4. 会话局部规则
5. 记忆内容
6. MCP 指令
7. scratchpad / 临时工作区规则
8. token budget 提示

4. 为什么要有 Prompt cache boundary

如果每次请求都完全重造提示词，会带来两个问题：

• 成本上升
• 缓存命中下降

因此产品需要把系统提示词分成：

• 稳定前缀
• 动态后缀

这样才能兼顾灵活性与成本控制。

5. Agent 编排的需求本质

系统需要支持把复杂任务拆给不同角色，而不是只依赖一个万能主 agent。

必须支持的角色至少包括

• 通用执行角色
• 探索角色
• 规划角色
• 验证角色

需求原因

不同任务阶段对行为模式要求不同：

• 探索需要只读
• 规划需要结构化输出
• 实施需要可执行
• 验证需要对抗性检查

如果用一个 agent 混合承担所有角色，稳定性会下降。

6. 子 Agent 设计需求

6.1 fork 子任务

系统需要支持：

• 子任务继承上下文
• 子任务尽量共享缓存前缀
• 子任务减少主线程污染

6.2 background 子任务

系统需要支持：

• 后台执行
• 进度跟踪
• 结果通知
• 可恢复输出

6.3 isolation 子任务

系统需要支持：

• worktree 隔离
• remote 隔离（如果启用）

7. Prompt 写给子 Agent 的需求

主 agent 必须能够给子 agent 交接充分背景，不能只丢一个模糊命令。产品层面要明确要求：

• 写清任务目标
• 写清已知背景
• 写清约束
• 写清期望输出

8. 伪代码表达

class SystemPromptBuilder:
    def build(self, env, tools, memory, output_style, language, mcp_info):
        static_sections = [
            intro(),
            system_rules(),
            task_rules(),
            action_safety(),
            tool_usage_rules(),
        ]
        dynamic_sections = [
            env_section(env),
            language_section(language),
            output_style_section(output_style),
            memory_section(memory),
            mcp_section(mcp_info),
        ]
        return static_sections + dynamic_sections

9. 产品经理视角下的总需求句

系统提示词层的核心需求，是把产品规则、工具语法、会话状态和环境约束组装成一套可动态生成、可缓存优化、可支持多角色协作的运行时控制平面。