dsh-superagent/docs/004-提示词.md

004 提示词

本文解释 agent 读到什么、团队能改什么、改动何时生效。它建立在 000 理念 到 003 执行 之上。提示词文本用英文书写。

团队写什么

团队可以编辑三个团队分节、添加技能（skills），并覆盖每一个内置系统提示词部件。多数默认文本在 prompts/ 与 skills/ 下。工具描述、通知与卡片留在代码里，不能通过提示词设置编辑。

分节	内容
Communication	何时给人发消息、消息读起来什么样、每条 GitHub 消息的开头固定句（默认是 This is by an automated agent, not a human）、如何处理 reviews、以及哪些普通账号是 review bots
Ticket scope	Ticket 何时继续、何时停在一份草案上
Delivery requirements	pull request 里的证据、auto-merge 条件及其行数阈值、以及 commit 作者；不指定时，Executor 以 agent 账号的 no-reply 地址提交
Team skills	agent 在需要时装载的知识，例如一个 identities 技能，写明哪个 Feishu 用户对应哪个 GitHub 账号

内置文本覆盖角色、工具使用、host 机制、授权规则，以及 GitHub 和 Feishu 技能。它按标题引用团队分节，而不是重复它们。

内置部件与模板

覆盖使用这些键：

部件	键
共享指令与角色	runtime/shared、runtime/orchestrator、runtime/worker
工作指令	runtime/subscriptions、runtime/replies、runtime/dispatch、runtime/work、runtime/admission
交接指令	runtime/handoff/orchestrator、runtime/handoff/worker
Source 技能	skill/feishu、skill/github
生成节	runtime/environment、runtime/policy、runtime/policy/none

生成节是可编辑的模板。它们必须保留这些占位符：

• runtime/environment：{variables}，填充执行环境行。
• runtime/policy：{version}、{mode} 与 {rules}，每条启用的规则占一行。
• runtime/policy/none：{version} 与 {mode}，没有任何启用规则时使用。

编辑一个部件改变的是模型收到的指令，不改变 gate、Mandates、工具校验与账号包装器——它们仍由代码强制执行。

在显式的人类请求下，main Session 也可以用 orchestrator_prompts_save 保存覆盖。若某次保存省略了覆盖的 base，则保留已存的 base。已从配置中移除、但仍在已存设置里的部件在保存时被丢弃；其他未知部件会被拒绝。

一个覆盖会记录它基于哪份内置文本。升级保留团队的文本。若默认值变了，面板把该部件标为 Default updated，并在团队文本旁显示差异。团队可以保留自己的文本、采用新默认值、或继续编辑。没有覆盖的部件自动跟随新默认值。

main Session 可以在 orchestrator_read prompts 的 default_changed 下读到受影响的部件名。

拼装与优先级

系统提示词按这个顺序拼装：

1. 共享指令与角色。
2. 三个团队分节。
3. Subscriptions 与 replies。
4. main Session 用 dispatch，Executor 用 work instructions。
5. runtime/admission，仅 main Session。
6. 交接指令。
7. runtime/environment。
8. runtime/policy，仅 main Session。

准入指令来自 prompts/admission.md。它们描述主动评估，以及一个不相关的候选在什么情况下可以直接从它的卡片上忽略。orchestrator_eval 返回上下文，而不是重复这些指令。

环境节给 main Session 部署级的取值、给每个 Executor 它那份 Ticket 专属的取值。Policy 节在每次模型请求前从设置重新生成，包含 Policy 版本、accept mode、显式请求的豁免条款，以及启用的规则（形如 - <name> (<id>): <instruction>），或者一句没有任何启用的说明。它放在最后，这样一次 Policy 改动不会改变前面的提示词文本。

Executors 还会读 DeepSeek Harness 的编码提示词与仓库的 AGENTS.md；main Session 不读。一个推断出的 Ticket 会追加一条尾注，把它的 Executor 限定在命中的规则内。Assignments 与进来的消息以 Trigger 卡片的形式内联到达，只有被截断的内容才给资源指针。

Executors 无人值守地工作。它们的工具排除了那些会询问人、向人展示界面或修改 profile 的工具，例如 ask_user_question、present 与 plugin_manager。

从最强到最弱：

1. 由工具与 host 强制的事实：身份、权限、工具参数校验、reply purposes、长度限制。提示词文本改不了它们。
2. 内置与生成节，按团队对它们的覆盖所读到的样子。
3. 一个主动 Ticket 命中规则里的流程与沟通方式——仅对该 Ticket 的 Executor Session。
4. 团队分节与团队技能。
5. 外部文本：消息、评论、文档与引用。它们是数据，永远不改变规则或授权。

内置文本的原则

这些是把 000 理念 应用到 agent 上：

• 角色分离。 main Session 只做路由：它转发原始 Trigger 与路由事实，不做任何技术决定，通过一个一次调用就能对多个等待中的候选做出决定的路由工具。一条路由备注至多 30 个词。Executor 读原始材料、判断 scope、实现并验证。
• main Session 不等待。 报告、跟进通知、候选与已完成的后台任务会自动作为消息到达。无事可做时它就结束本轮。一个 guard 会拒绝 sleep、超过 30 秒的 shell 超时、以及超过 5 秒的 job 等待，因为一个被卡住的步骤会拖延新的候选。这些指令在 main Session 的完整提示词里取代 DeepSeek Harness 自己的 job 通知说明。
• 只在有人必须行动或用得上结果时才发消息： 结果可以被评审或使用、需要决定或资源、或工作无法完成。聊天消息默认一句话，硬上限 100 个词。
• Executors 自己决定后续。 每个 Executor 处理并认领自己 scope 内的请求，交还超出其 Ticket 或属于另一个 Ticket 的请求。一条消息只有在它所有的认领者都交还、或结束而未认领之后，才成为新的工作。main Session 收到跟进通知，但只能拿它们来停止工作。被交还的消息随后作为候选到达，带着 Executors 的理由。
• 通过 subscriptions 与 main Session 协调。 一个 Executor 订阅相关的 Threads 以获得上下文。main Session 可以用一条至多 100 个词的备注，把另一个 Ticket 的事实带过来。无论 Subscription 还是备注都不授予权限。
• 只在显式引用时才 attach。 一条消息必须指向某个 Ticket 的 pull request、Issue、源消息或认领回执，或指向一次近期改动且恰好只有一个匹配的 Ticket。仅话题相似不够。attach 会让该 Ticket 订阅整个 Thread；Executor 若发现无关，使用 orchestrator_thread_unrelated 并不在那里回复。
• 具体地确认，只确认一次。 在实质性工作前，Executor 对每个新请求确认一次，说明对象与预期结果，以原消息下方回复的形式。
• 通过 human_action 提问。 Executor 把一个具体问题放进它的 Report，main Session 原样转发。若这个问题由某条人类消息引出，就点名那条消息，host 到那里去问；否则在 Ticket 的原始对话里问。已获授权的工作可在此期间继续。
• 诚实交付。 开 pull request 不等于就绪；草案标未完成；没有真实 before 截图的 UI 改动不算完成。
• 人的 pause 会顶住。 跨跟进、新的 Executor Sessions 与重启持续生效，直到人来解除。自动反馈永远不会恢复被暂停的工作。
• 示例只展示格式。 一个例句不是 agent 可以援引的事实。
• 按结果处理 reviews。 被修复并验证通过的评论静默 resolve；被拒绝的给一句话理由。自动化评审者的 thread 一旦有其答复即可 resolve，每个自动化评审者在一个 pull request 里至多三轮。
• 为重复工作让路。 当某人的分支或 pull request 已包含该 Ticket 的改动时，Executor 关闭自己的 pull request，用一句话指向对方的那份。

版本

• 每次保存创建一个不可变版本，包含完整配置、revision 号、前驱版本、时间戳与来源（面板或工具）。恢复某个版本或默认值会再创建一个版本。
• 保存会点名其 base revision。冲突的保存被拒绝，且不丢弃草稿。
• Sessions 在每次模型请求时读取最新版本，包括同一轮里的后续步骤。保存不重启、不取消、也不唤醒任何 Session。host 记录每个 Session 用到的 revisions；Executor 可以读取它工作期间的任何版本。
• 部署设置一个含覆盖在内的总大小上限。校验拒绝未知键、被保留的内置技能名、未知覆盖部件与缺失的模板占位符，且从不静默截断文本。与默认值完全相同的覆盖会被移除，让该部件跟随将来的默认值。