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. 伪代码表达

```python
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. 产品经理视角下的总需求句

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