docs(system-prompt): sync first-party order references

2026-08-29 04:26:38 +00:00 · 2026-08-25 12:05:38 +08:00
parent 0f7b28ad31
commit 8020f6386d
26 changed files with 42 additions and 43 deletions
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-30-source-checkout-workdir-distinction.md
-2026-07-30-source-checkout-workdir-distinction.md: ba6d9dd12b55a54d4ae8d2e91ad83ac3c1dc47fd
-2026-07-30-source-checkout-workdir-distinction.zh.md: 06b09f82f294a70795090a9aec1b2220bd6e7512
+2026-07-30-source-checkout-workdir-distinction.md: 407d11bd2d0bb27bf1953f1a3a84848480e03328
+2026-07-30-source-checkout-workdir-distinction.zh.md: 91251aa040226d72cf431101aa0d064ba107823e
@@ -14,7 +14,7 @@ A blanket statement that the checkout is not the working directory would also be

 The section identifies the path as the “DeepSeek Harness implementation checkout.” It says that the checkout location and current working directory are separate values that may differ, forbids inferring the working directory from the checkout path, directs the model to use `pwd`, and limits the checkout's purpose to inspecting or extending DSH itself.

-The path derivation, global `harness:source` ownership, and `-99` ordering remain unchanged. Describing the values as conceptually separate rather than always unequal keeps the instruction accurate in both ordinary project sessions and `dsh meta`.
+The path derivation and global `harness:source` ownership remain unchanged. The section uses first-party order −900, immediately after `harness:identity`. Describing the values as conceptually separate rather than always unequal keeps the instruction accurate in both ordinary project sessions and `dsh meta`.

 ## Verification

@@ -14,7 +14,7 @@ Status: implemented

 该提示词段将路径标识为「DeepSeek Harness implementation checkout」。它说明 checkout 位置与当前工作目录是两个可能不同的值，禁止从 checkout 路径推断工作目录，指示模型使用 `pwd`，并限定该 checkout 只用于检查或扩展 DSH 自身。

-路径推导方式、全局 `harness:source` 所有权和 `-99` 顺序均保持不变。将两者描述为概念上独立、而不是始终不相等，使这条指令在普通项目会话和 `dsh meta` 中都准确。
+路径推导方式与全局 `harness:source` 所有权保持不变。该段使用 first-party 顺序 −900，紧随 `harness:identity`。将两者描述为概念上独立、而不是始终不相等，使这条指令在普通项目会话和 `dsh meta` 中都准确。

 ## 验证

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md
-2026-07-22-plan-specific-collaboration-state.md: c2b882bd6f686662a2369d1b76d6e1611caee9b9
-2026-07-22-plan-specific-collaboration-state.zh.md: 1fdb4b260853be7480f1575d6ded86d036b7d746
+2026-07-22-plan-specific-collaboration-state.md: 20c363d00cfe2bcc2f01af101370f5214c948361
+2026-07-22-plan-specific-collaboration-state.zh.md: 63157b1959236e728e94a38d7ca6397a975595ef
@@ -26,7 +26,7 @@ Sandbox mode and approval policy remain separate enforcement axes. Plan mode nei

 `plan/mode` is log-only and non-surface, so resume, fork, and compaction recover the state without a live mirror. A spawned agent begins inactive because there is no creation-time plan option. Pending user selections flush before the affected request assembly at initial or continuation pre-step, or on a request-recovery retry; a failed durable append leaves the intent pending for a later boundary.

-The active state contributes the deployment's section at prompt order 50. Inactive state contributes no section, while `exit_plan_mode` remains registered in both states, so a transition changes the logged request header but not native tool schemas or the Code Mode SDK. A user-driven transition appends one plugin-sourced notice only when the last request header described the opposite state; a pre-first-request or net-zero selection adds none, and an approved tool exit relies on its tool result instead of a second notice.
+The active state contributes the deployment's section at first-party prompt order 500. Inactive state contributes no section, while `exit_plan_mode` remains registered in both states, so a transition changes the logged request header but not native tool schemas or the Code Mode SDK. A user-driven transition appends one plugin-sourced notice only when the last request header described the opposite state; a pre-first-request or net-zero selection adds none, and an approved tool exit relies on its tool result instead of a second notice.

 ### Reviewed exit

@@ -68,4 +68,4 @@ The tool renders the submitted plan as a generic card titled by its first headin

 The implementation has one vocabulary for one shipped feature. Adding another collaboration stance is an explicit design decision instead of a config entry, and automation clients do not acquire human mode controls through ACP. The migration intentionally rejects old `mode/set` logs and old `modes.plan.section` configuration under the repository's pre-release format policy.

-Plan state remains reconstructable and tool schemas remain stable, but an idle pending selection is lost if the process exits before the next boundary. Entering or leaving plan mode changes the prompt from order 50 onward, and a model that ignores the guidance can still mutate unless the deployment independently configures sandbox, approval, or filesystem policy.
+Plan state remains reconstructable and tool schemas remain stable, but an idle pending selection is lost if the process exits before the next boundary. Entering or leaving plan mode changes the prompt from first-party order 500 onward, and a model that ignores the guidance can still mutate unless the deployment independently configures sandbox, approval, or filesystem policy.
@@ -26,7 +26,7 @@ Plan mode 拥有一个 plan 专用产品包：位于 `packages/plan/plan-mode/`

 `plan/mode` 仅记录到日志且不进入表层，因此恢复、fork 和压缩（compaction）都能恢复该状态，无需实时镜像。spawn 出的 agent（智能体）初始处于未激活状态，因为创建时没有 plan 选项。待生效的用户选择会在初始或续步 pre-step 时，或在请求恢复重试时，于受影响的请求组装前写入日志；持久追加失败会让意图保持待定，留到后续边界处理。

-激活状态在提示词顺序 50 处贡献部署提供的区段。未激活状态不贡献区段，但 `exit_plan_mode` 在两种状态下都保持注册，因此状态转换会改变已记录的请求头，却不改变原生工具 schema 或 Code Mode SDK。用户发起的转换只会在上一条请求头描述相反状态时追加一条来源为插件的通知；第一次请求前的选择或最终状态未变化的选择不会追加通知，经批准的工具退出则依赖其工具结果，不再追加第二条通知。
+激活状态在 first-party 提示词顺序 500 处贡献部署提供的区段。未激活状态不贡献区段，但 `exit_plan_mode` 在两种状态下都保持注册，因此状态转换会改变已记录的请求头，却不改变原生工具 schema 或 Code Mode SDK。用户发起的转换只会在上一条请求头描述相反状态时追加一条来源为插件的通知；第一次请求前的选择或最终状态未变化的选择不会追加通知，经批准的工具退出则依赖其工具结果，不再追加第二条通知。

 ### 经评审的退出

@@ -68,4 +68,4 @@ Plan mode 拥有一个 plan 专用产品包：位于 `packages/plan/plan-mode/`

 该实现只用一套词汇描述一项已交付功能。若要添加另一种协作方式，必须显式作出设计决策，而不能只增加配置项；自动化客户端不会通过 ACP 获得面向人类的模式控制。根据仓库的预发布格式策略，本次迁移有意拒绝旧的 `mode/set` 日志与 `modes.plan.section` 配置。

-Plan 状态仍可重建，工具 schema 仍保持稳定，但如果进程在下一边界前退出，空闲状态下待生效的选择会丢失。进入或离开 plan mode 会改变提示词顺序 50 处及其后的内容；如果模型忽略引导，仍可能执行修改，除非部署另行配置沙箱、审批或文件系统策略。
+Plan 状态仍可重建，工具 schema 仍保持稳定，但如果进程在下一边界前退出，空闲状态下待生效的选择会丢失。进入或离开 plan mode 会改变 first-party 提示词顺序 500 处及其后的内容；如果模型忽略引导，仍可能执行修改，除非部署另行配置沙箱、审批或文件系统策略。
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/plan.md
-plan.md: a4332ba97667f125b0996f305e7e2a2a36005ddf
-plan.zh.md: e8536d873e92f9afa0482a1268a66e5379f65453
+plan.md: a1e29982507940f58d458e48789dc3259bee3a2e
+plan.zh.md: 8df3f5f48ba2813b8c35e362324a71eb8cad763b
@@ -26,7 +26,7 @@ interface PlanModeConfig {
 }
 ```

-A missing, blank, or non-string `section` and any unknown key fail at plugin load rather than being ignored. While plan mode is active, the exact `section` text renders as the `plan:policy` [system-prompt section](system-prompt.md) at order 50; inactive plan mode contributes no text.
+A missing, blank, or non-string `section` and any unknown key fail at plugin load rather than being ignored. While plan mode is active, the exact `section` text renders as the `plan:policy` [system-prompt section](system-prompt.md) at first-party order 500; inactive plan mode contributes no text.

 ## The exit tool and the `/plan` command

@@ -26,7 +26,7 @@ interface PlanModeConfig {
 }
 ```

-`section` 缺失、为空白或不是字符串，以及任何未知键，都会在插件加载时失败，而不是被忽略。计划模式激活期间，确切的 `section` 文本以 order 50 渲染为 `plan:policy` [系统提示词段落](system-prompt.zh.md)；未激活的计划模式不贡献任何文本。
+`section` 缺失、为空白或不是字符串，以及任何未知键，都会在插件加载时失败，而不是被忽略。计划模式激活期间，确切的 `section` 文本以 first-party 顺序 500 渲染为 `plan:policy` [系统提示词段落](system-prompt.zh.md)；未激活的计划模式不贡献任何文本。

 ## 退出工具与 `/plan` 命令

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/bundle/web-app/README.md
-README.md: 4092cf4fd2985027f3c7e59909f58a5dc1ef4244
-README.zh.md: 5c0f3a109b8d5261ab2a5e2ae0219cb06d493c04
+README.md: c428bbd352f7f58fe4b76cd078e2c1a1993b422a
+README.zh.md: 0d5a33fe356d749fa619ad980ab9ee13ed9ba3fc
@@ -16,7 +16,7 @@ Web uses the shared bounded normal default of five eligible retries after the in

 #### What the model sees

-When `surfaceContext` is true, the `harness:source` section identifies the on-disk Harness implementation without claiming it is the working directory, and the `app:web-surface` global section (order −98) orients the model to the GUI: the canonical local URL, the "this page" referent, the update contract (the reload receiver is always on; no-refresh reloads additionally need the `pnpm run dev:web` watcher), and the instruction not to start replacement servers. `DSH_WEB_URL` additionally appears in the managed bash environment with its description, resolved per invocation from the live server. When it is false, neither section nor the variable is registered.
+When `surfaceContext` is true, the `harness:source` section identifies the on-disk Harness implementation without claiming it is the working directory, and the `app:web-surface` global section (first-party order −800) orients the model to the GUI: the canonical local URL, the "this page" referent, the update contract (the reload receiver is always on; no-refresh reloads additionally need the `pnpm run dev:web` watcher), and the instruction not to start replacement servers. `DSH_WEB_URL` additionally appears in the managed bash environment with its description, resolved per invocation from the live server. When it is false, neither section nor the variable is registered.

 #### Token effect

@@ -16,7 +16,7 @@ Web 使用共享的有界 normal 默认值，在首次请求后最多再重试

 #### 模型看到的内容

-当 `surfaceContext` 为 true 时，`harness:source` 段落标明磁盘上的 Harness 实现，但不会声称它就是工作目录；全局段落 `app:web-surface`（顺序 −98）则向模型说明 GUI：规范的本地 URL、「this page」指代什么、更新约定（重载接收端始终开启；无刷新重载还需要 `pnpm run dev:web` watcher），以及不要启动替代服务器的指令。`DSH_WEB_URL` 还会连同描述出现在受管 bash 环境中，每次调用时从运行中的服务器解析。当它为 false 时，这两个段落和该变量都不会注册。
+当 `surfaceContext` 为 true 时，`harness:source` 段落标明磁盘上的 Harness 实现，但不会声称它就是工作目录；全局段落 `app:web-surface`（first-party 顺序 −800）则向模型说明 GUI：规范的本地 URL、「this page」指代什么、更新约定（重载接收端始终开启；无刷新重载还需要 `pnpm run dev:web` watcher），以及不要启动替代服务器的指令。`DSH_WEB_URL` 还会连同描述出现在受管 bash 环境中，每次调用时从运行中的服务器解析。当它为 false 时，这两个段落和该变量都不会注册。

 #### Token 影响

@@ -122,8 +122,8 @@ export interface PromptAssembly {
 /**
 * Sparse integer placements for repository-owned prompt sections.
 *
- * Adjacent values differ by at least ten so a new first-party section can be
- * inserted without renumbering the surrounding sequence.
+ * Adjacent values differ by at least ten to keep the first-party groups sparse
+ * and make accidental collisions mechanically detectable.
 * External plugins may use any finite order; equal orders are deterministic by
 * section name.
 */
@@ -843,11 +843,10 @@ export class ToolRuntime extends Service {
   *
   * Every tool contributes its own guidance section naming its tool, none of
   * them qualify how that tool is reached, and they all render before the SDK.
-   * Without this the model
-   * reads a catalog of tools it is told to use and no statement that only
-   * `run_code` may be called, so it emits a native call, receives
-   * `UNKNOWN_TOOL` for a tool the prompt just declared, and concludes the
-   * deployment is inconsistent. {@link COLLAPSE_SECTION_ORDER} places the rule
+   * Without this the model reads a catalog of tools it is told to use and no
+   * statement that only `run_code` may be called, so it emits a native call,
+   * receives `UNKNOWN_TOOL` for a tool the prompt just declared, and concludes
+   * the deployment is inconsistent. {@link COLLAPSE_SECTION_ORDER} places the rule
   * before that guidance rather than after it.
   *
   * `both` renders empty: native calls do execute there, so the rule is false.
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/lsp/tool-lsp/README.md
-README.md: e0fd5738cf114314a8483125d20142d5f1ffac40
-README.zh.md: 71d6a4b5479b2da187b78a388d617afe7214e78c
+README.md: 84ca94863758c2ee5bb23a458053cb5d4fefb777
+README.zh.md: 48eacc553337a852c4722931761590d84f44554d
@@ -26,7 +26,7 @@ The tool requires the workspace root from the session `header.cwd`, with no fall

 #### What the model sees

-One system-prompt section (order 112) positions LSP as a precision aid with the following text:
+One system-prompt section (first-party order 2200) positions LSP as a precision aid with the following text:

 ##### Verbatim guidance

@@ -26,7 +26,7 @@ Namespace 插件（`name`／`inject`／`Config`／`apply`，无默认导出）

 #### 模型看到的内容

-一个系统提示词区段（顺序 112）将 LSP 定位为精确辅助工具，文本如下：
+一个系统提示词区段（first-party 顺序 2200）将 LSP 定位为精确辅助工具，文本如下：

 ##### 逐字指引

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/plan/plan-mode/README.md
-README.md: 3eabe2cb3f04b434b7f908f7beca869f1022a59e
-README.zh.md: b3548da880af5d0cacfebba4486294d9d5085626
+README.md: cc518d9854609362ad5e932dc1e819e9757ee5d6
+README.zh.md: cd17f216e914bbd37251cda22a1068e2b0c0ac9c
@@ -45,7 +45,7 @@ Design: [plan-specific collaboration state](../../../.agents/notes/implemented/s

 #### What the model sees

-While plan mode is active, the model sees the deployment's exact `section` text at prompt order 50; inactive mode contributes no text.
+While plan mode is active, the model sees the deployment's exact `section` text at first-party prompt order 500; inactive mode contributes no text.

 ##### Configuration example

@@ -59,7 +59,7 @@ Inactive mode adds no tokens; active mode adds the configured section to every r

 #### KV Cache effect

-The section is stable within plan mode, but entering or leaving changes the system prompt from order 50 onward.
+The section is stable within plan mode, but entering or leaving changes the system prompt from first-party order 500 onward.

 ### Human command

@@ -47,7 +47,7 @@ Web 客户端使用该插件提供的 `/plan` 命令；其他入口可以直接

 #### 模型所见内容

-Plan mode 激活时，模型会在提示词顺序 50 处看到部署方提供的原样 `section` 文本；未激活 mode 不贡献文本。
+Plan mode 激活时，模型会在 first-party 提示词顺序 500 处看到部署方提供的原样 `section` 文本；未激活 mode 不贡献文本。

 ##### 配置示例

@@ -61,7 +61,7 @@ You are in plan mode. Explore and design before presenting the complete plan thr

 #### KV Cache 影响

-该段在 plan mode 内稳定，但进入或退出会从顺序 50 开始改变系统提示词。
+该段在 plan mode 内稳定，但进入或退出会从 first-party 顺序 500 开始改变系统提示词。

 ### 人类命令

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/shell/tool-bash/README.md
-README.md: 21749bf0a1cd3cdc46257fb2a02ba6b4ab1f5ee6
-README.zh.md: 860db1a4c347d1aefe04f70e14a65e4b511ff7f6
+README.md: c684508ea50b80ff6f98b25cd4cd7ca0fd6012a5
+README.zh.md: 3459ed64964bf40b3b72530d7614ca27e45cafc6
@@ -8,7 +8,7 @@ Requires a loaded executor Service Provider (e.g. `@deepseek-ai/dsh-bash-local`)

 The package root exposes only the Cordis plugin contract (`name`, `inject`, `Config`, `apply`); result rendering and background-process adaptation remain package-internal.

-The plugin also contributes the `tool:bash` prompt section (order 105): check the `[exit code: N]` marker on every result and investigate failures before moving on.
+The plugin also contributes the `tool:bash` prompt section (first-party order 1000): check the `[exit code: N]` marker on every result and investigate failures before moving on.

 ## Tools

@@ -8,7 +8,7 @@

 包根只公开 Cordis 插件约定（`name`、`inject`、`Config`、`apply`）；结果渲染和后台进程适配仍保留在包内部。

-插件还会提供 `tool:bash` 提示词段落（顺序 105）：检查每个结果中的 `[exit code: N]` 标记，发现失败时先调查原因再继续。
+插件还会提供 `tool:bash` 提示词段落（first-party 顺序 1000）：检查每个结果中的 `[exit code: N]` 标记，发现失败时先调查原因再继续。

 ## 工具

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/shell/tool-pwsh/README.md
-README.md: e862fcf0ca85d0ecb0a5fe6cff3ee3c7a8153716
-README.zh.md: 0a66b119ac2bf0386c0686e9e22ddfe1c3bb87b1
+README.md: 70827f42566f670ffedb37b20111ec13aab09582
+README.zh.md: eec0a9782a2afdd610a09a6851107f94dc6eecc4
@@ -8,7 +8,7 @@ Requires a loaded executor implementation and the `shell-env` plugin; the tool s

 The package root exposes only the Cordis plugin contract (`name`, `inject`, `Config`, `apply`); result rendering (`src/render.ts`) and background-job adaptation (`src/background.ts`) mirror the bash tool's structure and stay reachable through the package's `./src/*` export.

-The plugin also contributes the `tool:pwsh` prompt section (order 105): non-zero exits are reported as `[exit code: N]` markers, and Windows interruption settles as exit 1 without a signal marker.
+The plugin also contributes the `tool:pwsh` prompt section (first-party order 1010): non-zero exits are reported as `[exit code: N]` markers, and Windows interruption settles as exit 1 without a signal marker.

 ## Tools

@@ -8,7 +8,7 @@

 包根只导出 Cordis 插件约定（`name`、`inject`、`Config`、`apply`）；结果渲染（`src/render.ts`）与后台任务适配（`src/background.ts`）镜像 bash 工具的结构，并可通过包的 `./src/*` 导出访问。

-插件还贡献 `tool:pwsh` 提示词段落（order 105）：非零退出以 `[exit code: N]` marker 报告，Windows 上的中断以无 signal 的 exit 1 结算。
+插件还贡献 `tool:pwsh` 提示词段落（first-party 顺序 1010）：非零退出以 `[exit code: N]` marker 报告，Windows 上的中断以无 signal 的 exit 1 结算。

 ## 工具