deepseek-harness/scripts/snapshots/translation-prompt-v4/request-response.expected.json

{
  "request": {
    "targetFilename": "snapshot-note.zh.md",
    "messages": [
      {
        "role": "system",
        "content": "# Translation Prompt\n\nYou are a senior technical translator specializing in LLM and agent development documentation. Your task is to translate the complete source document from English to Chinese, producing natural, professional technical prose.\n\nRead each complete semantic unit, understand it, and restate it as a native technical author would write it in the target language. Do not mechanically preserve source-language syntax. Then verify the translation against the source clause by clause: preserve every proposition and add none. Fluency never justifies losing or altering meaning, and completeness never justifies unnatural word-for-word prose.\n\n## Priority\n\nApply these authorities in order:\n\n1. Preserve the source meaning and the required document structure, protected content, and formatting.\n2. Follow the injected terminology table exactly.\n3. Use the injected whole-document gold pairs to calibrate target-language voice and phrasing.\n4. Apply the general writing guidance and illustrative examples in this prompt.\n\nA lower-priority rule may refine but never override a higher-priority requirement. Gold pairs calibrate voice; they are not a translation memory. No style preference, gold-pair phrasing, or embedded example may override source meaning, required structure, protected content, or the terminology table.\n\n## Quality Requirements\n\n### Structure and Format Preservation\n- Output a complete translated document that maintains the same document frame as the source: heading hierarchy and order, list kinds and item counts, ordered-list starts, table rows and columns, link targets, and code blocks.\n- Paragraph boundaries may change within the same structural unit when the target language needs different semantic grouping. Do not merge or move content across headings, list items, table cells, or other independent structural units.\n- Keep each prose paragraph on one physical line. Use paragraph breaks, not hard-wrapped lines inside a paragraph.\n- Fenced code blocks must be byte-identical to the source, including info strings, whitespace, and ALL comments inside them. Do NOT translate or reformat any content inside code blocks. This is a hard rule with no exceptions.\n- Inline code spans must be kept verbatim. This includes commands, flags, paths, identifiers, API and event names, config keys, protocol values, version numbers, and other machine-readable tokens. Never translate or reformat them.\n- Every relative link must point to the same target as in the source. Translate link text; do not change link targets.\n- Language switcher line: when an English source contains `English | [中文](source-filename.zh.md)`, write `[English](source-filename.md) | 中文`. When a Chinese source contains `[English](source-filename.md) | 中文`, write `English | [中文](source-filename.zh.md)`. Do NOT copy the source switcher unchanged. If the source has no switcher, do not invent a filename or switcher; the pipeline inserts the canonical target switcher after parsing `<final>`.\n- Preserve emphasis marker types and the semantic spans they cover. Do not add, remove, move, or change bold and italic markers.\n\n### Faithfulness\n- Preserve every proposition in the source and add none. Every sentence, list item, note, FIXME, warning, example, caveat, prerequisite, and guarantee must have an equivalent in the translation. Count list items on both sides.\n- Preserve actors, objects, conditions, exceptions, negation, modality, causal relationships, and distinctions between concepts.\n- Preserve the exact strength and orientation of contracts. Completion and lifecycle conditions, failure behavior, directions and data flow, normal and exceptional result channels, ownership changes, and quantitative bounds must not be weakened, strengthened, reversed, or merged.\n- Translate ideas rather than source-language idioms, but never use fluency as a reason to omit or alter meaning.\n\n### Tone and Style\n- The translation must read as if originally written in the target language by a native technical author. I
      },
      {
        "role": "user",
        "content": "# DeepSeek Harness\n\nEnglish | [中文](README.zh.md)\n\nDeepSeek Harness (`dsh`) is an open-source coding agent built on the DeepSeek Harness SDK.\n\nIt uses an architecture where **everything is a plugin**.\n\n## Internal testing notice\n\nDeepSeek Harness is under internal testing. Features and interfaces may change.\n\nThe internal build uploads all Session Logs by default to help diagnose reported problems. Set `DSH_TELEMETRY_DISABLED=1` to disable telemetry. Send feedback through the internal WeChat group.\n\n## Run from source\n\nClone this repo, complete the [dependency and API-key setup](docs/user/guide/quickstart.md#step-1-install-and-configure-the-api-key), then run:\n\n```sh\npnpm dsh web\n```\n\n## Use DeepSeek Harness\n\n### Web UI\n\nStart the recommended local interface from the repository root:\n\n```sh\npnpm dsh web\n```\n\nThe command builds the repository before starting the Web UI, which is served at `http://127.0.0.1:3080` by default.\n\n### Profiles\n\nThe source CLI boots profiles — ordered stacks of plugin-bundle patch layers under your own overrides in `$DSH_HOME/profiles/<name>`:\n\n```sh\npnpm dsh --profile web                       # the browser UI\npnpm dsh plugin --profile tui add <package>  # install a plugin into a custom profile\npnpm dsh --profile tui                       # boot it\n```\n\nThe [CLI reference](apps/cli/README.md#profiles) describes profile layout, layer semantics, and config dump commands.\n\n### Headless\n\nRun one task, print the final answer, and exit:\n\n```sh\npnpm dsh --profile headless \"summarize this workspace\"\n```\n\n### Automation and SDKs\n\nFrom a source checkout with `DEEPSEEK_API_KEY` in the environment or its root `.env`, start the ACP automation server:\n\n```sh\npnpm run demo:acp\n```\n\nThe [Python SDK](python/README.md) drives a bundled JSON-RPC runtime. The [examples](examples/README.md) cover the runnable headless, ACP, JSON-RPC, Code Mode, and self-referential compositions.\n\n## Why DeepSeek Harness\n\nBuilt-in capabilities cover file reading, editing, and search; shell and persistent PTY execution; reusable skills; task tracking, goals, plans, todos, and background tasks; subagents and workflows; sandboxing and approvals; settings and credentials; persistent, resumable, forkable, and queryable sessions; LSP and web access; context compaction; and telemetry. Each composition selects the subset appropriate to its surface. The Web UI includes Plan Mode.\n\n- **Everything is a plugin.** Models, tools, policies, storage, context management, and interfaces are composable [Cordis plugins](docs/user/develop/basic/index.md), so deployments can extend or replace behavior without forking the agent loop. See the [architecture](docs/architecture.md) for the underlying design.\n- **Runs are reconstructable.** Anything visible to the model is logged in the authoritative session stream; persistence, resume/fork/query, replay, telemetry, and UIs derive from the same events. See the [session-log architecture](docs/architecture.md#session-log).\n- **Code Mode (opt-in).** It exposes a `run_code` tool and a generated TypeScript SDK; only program output re-enters model context. See [Code Mode](packages/core/tools/README.md#code-mode).\n- **Self-referential Cordis tools are opt-in.** They let the agent inspect its live runtime and mount or unmount plugins while it runs. See the [Cordis tools](packages/self-modification/tool-cordis/README.md).\n\n## Community\n\nFollow <a href=\"https://x.com/Deepseekharness\">DeepSeek Harness on Twitter</a> for project updates.\n\n## Development\n\nStart with the [development guide](docs/development.md) and read the [architecture](docs/architecture.md) before changing packages.\n\nFor agents, follow [AGENTS.md](AGENTS.md).\n\nDeepSeek Harness is currently in internal testing.\n\n## License\n\n[BSD 3-Clause](LICENSE)\n\nThird-party dependencies and their licenses are disclosed in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).\n"
      },
      {
        "role": "assistant",
        "content": "# DeepSeek Harness\n\n[English](README.md) | 中文\n\nDeepSeek Harness（`dsh`）是一款基于 DeepSeek Harness SDK 构建的开� coding agent（智能体）。\n\n它采用了**一切皆�件**的架构。\n\n## 内测声明\n\nDeepSeek Harness 正处于内部测试阶段，功能和接��能�生�化。\n\n为帮助诊断上报的问题，内测版本默认上传所有会�日志。设置 `DSH_TELEMETRY_DISABLED=1` �关闭�测。请通过内部�业微信群�馈问题和建议。\n\n## 从���行\n\n克隆本仓库，完�[�赖安装和 API 密钥�置](docs/user/guide/quickstart.md#step-1-install-and-configure-the-api-key)，然��行：\n\n```sh\npnpm dsh web\n```\n\n## 使用 DeepSeek Harness\n\n### Web UI\n\n请从仓库根目录�动推�的本地界�：\n\n```sh\npnpm dsh web\n```\n\n该命令会先构建仓库，��动 Web UI。Web UI 默认通过 `http://127.0.0.1:3080` �供�务。\n\n### Profile\n\n�� CLI（命令行界�）会�动 profile：按��放的�件组�包 patch 层，之上��加你在 `$DSH_HOME/profiles/<name>` 中的自有覆盖层：\n\n```sh\npnpm dsh --profile web                       # the browser UI\npnpm dsh plugin --profile tui add <package>  # install a plugin into a custom profile\npnpm dsh --profile tui                       # boot it\n```\n\nprofile 布局�层语义与�置输出命令详� [CLI（命令行界�）�考](apps/cli/README.md#profiles)。\n\n### Headless\n\n�行一项任务，打�最终答案�退出：\n\n```sh\npnpm dsh --profile headless \"summarize this workspace\"\n```\n\n### 自动化与 SDK\n\n在��检出中通过环境��或根目录 `.env` 设置 `DEEPSEEK_API_KEY`，然��动 ACP（Agent Client Protocol）自动化�务器：\n\n```sh\npnpm run demo:acp\n```\n\n[Python SDK](python/README.md) 驱动�附的 JSON-RPC �行时。[示例](examples/README.md)涵盖��行的 headless�ACP�JSON-RPC�Code Mode 和自指组�。\n\n## 为什么选择 DeepSeek Harness\n\n内置功能涵盖文件读��编辑与�索�shell 和�久 PTY 执行���用 skill（技能）�任务跟踪�目标�计划�待办事项与��任务�subagent 与工作��沙箱与审批�设置与凭����久化����fork 与查询的会��LSP 与 Web 访问�上下文压缩（context compaction），以��测。�个组��选用适�其使用方�的能力�集。Web UI 包� Plan Mode。\n\n- **一切皆�件。** 模型�工具�策略�存储�上下文管�和界��为�组�的 [Cordis �件](docs/user/develop/basic/index.md)，部署方无需 fork agent loop（智能体循环）��扩展或替�行为。底层设计�[架构文档](docs/architecture.md)。\n- **�行��建。** 凡是模型��的内容，都会记录在��会��中；�久化����fork�查询�回放��测和 UI �从�一组事件派生。��[会�日志架构](docs/architecture.md#session-log)。\n- **Code Mode（需显��用）。** 它会�供 `run_code` 工具和生�的 TypeScript SDK，�有程�输出会�新进入模型上下文。�� [Code Mode](packages/core/tools/README.md#code-mode)。\n- **自指 Cordis 工具需显��用。** 这些工具�让 agent 检查自身的实时�行时，并在�行中挂载或�载�件。�� [Cordis 工具](packages/self-modification/tool-cordis/README.md)。\n\n## 社区\n\n扫�二维�，或打开 <a href=\"https://wj.qq.com/s2/27234598/03eb/\">DeepSeek Harness 微信社区申请页�</a> 申请加入。\n\n<p>\n  <img src=\"assets/community-wecom-survey.png\" alt=\"DeepSeek Harness 微信社区二维�\" width=\"240\">\n</p>\n\n## 开�\n\n请先阅读[开�指�](docs/development.md)；修改包之�，请阅读[架构文档](docs/architecture.md)。\n\n�� agent：�循 [AGENTS.md](AGENTS.md)。\n\nDeepSeek Harness 目�处于内测阶段。\n\n## 许��\n\n[BSD 3-Clause](LICENSE)\n\n第三方�赖�其许��在 [THIRD_PARTY_NO
      },
      {
        "role": "user",
        "content": "# Development guide\n\nEnglish | [中文](development.zh.md)\n\nThe setup tutorial takes a new contributor from prerequisites to a checked checkout. The contributor reference that follows covers repository layout, daily workflow, and CI organization. Design rationale and implementation details belong to the linked Agent Notes and scripts.\n\n## Setup tutorial\n\n### Prerequisites\n\n- Node.js supports 22.19+ and 24+. CI covers 22.19, 24, and 26; see the [Node engine floor Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md).\n- Corepack-enabled pnpm. The repo pins `pnpm@11.7.0` in `package.json`; run `corepack enable` if `pnpm --version` does not resolve through Corepack.\n- Git 2.26 or newer; hook setup enables Git's worktree-specific configuration extension.\n- Optional: a DeepSeek API key for the Web, headless, and ACP automation demos and real-API e2e tests.\n\n### First-time setup\n\nInstall dependencies from the repo root:\n\n```sh\npnpm install\n```\n\nThe install also configures worktree-local Lefthook hooks and the `dsh-translation-pairing` Git merge driver through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the hook-path safety contract; the [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the merge driver.\n\nIf either integration is missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\nIf the wrapper rejects existing Git configuration or reports a stale lock, follow its diagnostic and the linked Agent Note rather than editing worktree metadata speculatively. After moving a checkout, rerun the wrapper to regenerate the owned path.\n\nRun typecheck once after a fresh clone:\n\n```sh\npnpm run typecheck\n```\n\nSetup is complete when `pnpm run typecheck` exits successfully.\n\n## Contributor reference\n\n### TypeScript project layout\n\nThe repository uses isolated Host and Client aggregates. An ordinary package is registered in exactly one aggregate: Host packages in `tsconfig.host.json` and Client packages in `tsconfig.client.json`.\n\n| File | Role | Forms a program? |\n|---|---|---|\n| `tsconfig.json` | Solution root: `extends` base, `files: []`, and references to the two aggregates. It is the tsserver discovery entry and the entry for explicitly running the complete Project Reference graph; through the inherited `paths`, it is also the resolution config for tsx running `examples/` and `scripts/`. | No |\n| `tsconfig.host.json` | Host aggregate: Host packages, examples, tests, scripts, website, and the exceptional Host project of `api/remotes`. | Yes |\n| `tsconfig.client.json` | Client aggregate: `packages/client/*` packages and their tests, `apps/web`, and the exceptional Client project of `api/remotes`. | Yes |\n| `tsconfig.base.json` | Shared compilerOptions and the source `paths` map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no `include`, so its `paths` apply to every importer. | No |\n| `tsconfig.base.client.json` | Browser compiler settings (`jsx`, DOM libs, `types: []`) extended by the Client aggregate and every `packages/client/*` package. | No |\n\nHost and Client stay two aggregate programs because both sides declaration-merge the cordis `Context` interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a `ts.Program` — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Three disciplines follow:\n\n- `tsconfig.base.json` never gains `include` or `files`: they would leak into every extending package project and narrow the facade's match-all scope.\n- A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` ex
      },
      {
        "role": "assistant",
        "content": "# 开�指�\n\n[English](development.md) | 中文\n\n�建教程引导新贡献者从准备�置�件开始，直到检出通过检查。��的贡献者�考介�仓库布局�日常工作�和 CI 组织方�。设计��与实现细节属于链接的 Agent Note 和脚本。\n\n## �建教程\n\n### �置�件\n\n- Node.js 支� 22.19+ 与 24+。CI 覆盖 22.19�24 和 26；� [Node 引擎下� Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- �用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解�，请先�行 `corepack enable`。\n- Git 2.26 或更高版本；钩�设置会�用 Git 的 worktree 专属�置扩展。\n- �选：一个 DeepSeek API key，用于 Web�headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以�真实 API 的 e2e 测试。\n\n### 首次�建\n\n在仓库根目录安装�赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` �置 worktree 本地的 Lefthook 钩�和 `dsh-translation-pairing` Git �并驱动。[worktree 本地钩� Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩�路径的安全约定；[自动�对�并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责�并驱动。\n\n如果�赖是从缓存��或 `postinstall` 被跳过而导致任一集�缺失，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒�现有 Git �置或报告陈旧�，请�循其诊断和所链接的 Agent Note，��凭猜测编辑 worktree 元数�。移动检出目录�，请�新�行包装脚本以�新生�自有路径。\n\n新克隆�请先�行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` �功退出�表示�建完�。\n\n## 贡献者�考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通 package �登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是�构� program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base�`files: []`�引用两个 aggregate。它是 tsserver �现入�，也是显�执行整张 Project Reference 图时的入�；�继承的 `paths` 充当 tsx �行 `examples/` 与 `scripts/` 时的解��置。 | � |\n| `tsconfig.host.json` | Host aggregate：Host package�示例�测试�脚本和 website，以� `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` package �其测试�`apps/web`，以� `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与�� `paths` 映射。�时是� vitest �置让 vite-tsconfig-paths 指�的解�门�：它没有 `include`，因此其 `paths` 适用于任何 importer。 | � |\n| `tsconfig.base.client.json` | �览器编译设置（`jsx`�DOM lib�`types: []`），由 Client aggregate 和�个 `packages/client/*` package extends。 | � |\n\nHost 与 Client ��两个 aggregate program，是因为两侧在相�键下以���务对 cordis `Context` 接��声明�并；�一 program �时看到两份�并会报冲�。这�冲��存在于 `ts.Program` 内部——模�解�永远�会触�它——所以 solution �以�时引用两个 aggregate，一个 paths 门�也�以横跨两侧。由此推出三�纪律：\n\n- `tsconfig.base.json` 永�添加 `include` 或 `files`：它们会泄�进�个 extends 它的包项目，并收窄门�的全匹�范围。\n- 构造全仓 `ts.Program` 的脚本显��� `tsconfig.host.json` 或 `tsconfig.client.json`——永���根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` �并冲�
      },
      {
        "role": "user",
        "content": "# Bilingual documentation\n\nEnglish | [中文](README.zh.md)\n\nThis repo's documentation is read by people and agents both inside and outside the company, so every document in scope is maintained in English and Simplified Chinese. This page defines the pairing contract, checks, scope, and exclusions; [translation-rules.md](translation-rules.md) defines how to translate; [terminology.md](terminology.md) is the terminology source of truth. Routine agent work follows the lightweight path in [docs/AGENTS.md](../AGENTS.md); the extended [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) workflow is available only through explicit user invocation.\n\n## The pairing contract\n\n- **Both languages carry equal authority.** A document may be authored and reviewed in either language first — a Chinese-first Agent Note is as legitimate as an English-first one — and the counterpart is translated from it. Neither file outranks the other; what binds them is that they must say the same thing.\n- **A pair is three sibling files.** The English `foo.md`, the Chinese `foo.zh.md`, and a consistency record `foo.i18n.yaml`, all in the same directory. No locale directories, no separate translation repo, no interleaved bilingual files. Pairs merge whole: a PR never lands one language without the other two files.\n- **The consistency record.** `foo.i18n.yaml` holds the full git blob hash of each side as of the last time the two were confirmed to say the same thing:\n\n  ```yaml\n  foo.md: 3f786850e387550fdab836ed7e6dc881de23001b\n  foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b\n  ```\n\n  Blob hashes, not commit hashes, so the record is computable for files edited in the same PR (`git hash-object foo.md`) and consistency is a pure content comparison. `--write` stores those snapshots in the local Git object database before recording them, including uncommitted working-tree contents, and pins every distinct stored blob under a content-addressed `refs/dsh/translation-pairing/snapshots/` ref so garbage collection cannot invalidate a recorded recovery pointer. The recorded hashes therefore recover the exact last-confirmed text of either side, so an out-of-sync pair is updated by patching the counterpart minimally against the edited side's diff — never by re-translating whole files. Routine work makes that patch directly; when the user explicitly invokes the extended workflow, `pnpm run gen-translation-brief <pair>` can instead assemble the update at the narrowest safely aligned granularity and `--apply` can splice a code-fence-only change after structural validation ([briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)). After bringing the pair back in line, `pnpm run verify-translation-pairing --write <pair>` re-records both hashes; that yaml diff is the reviewable act of confirming consistency, which is why `--write` requires naming the pairs you confirmed (`--write --all` is the explicit corpus-wide form).\n\n  When two branches contain valid confirmations of the same pair, the installed `dsh-translation-pairing` Git merge driver composes a new record only if Git's default text merge succeeds for both recorded owner-blob triplets and the merged pair retains its required switchers and structural signature. The Chinese file must retain its English backlink; an authored English source must retain its Chinese link, while a listed generated English source is exempt. Any structure the driver cannot verify remains an ordinary conflict; `pnpm run resolve-translation-pairing-conflicts` applies the same fail-closed operation to a merge that has already stopped, stages every safe pairing record, and exits unsuccessfully when other pairing conflicts remain. The [automatic pairing merges Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the mechanism and alternatives.\n- **Language switcher.** The Chinese file always links back immediately after its H1 heading with `[En
      },
      {
        "role": "assistant",
        "content": "# �语文档\n\n[English](README.md) | 中文\n\n本仓库的文档会被公�内外的人和 agent（智能体）阅读，因此范围内的�篇文档都以英文和简体中文维护。本页定义�对约定�检查�范围与排除规则；[translation-rules.md](translation-rules.md) 定义如何翻译；[terminology.md](terminology.md) 是术语真�。agent 的日常工作�循 [docs/AGENTS.md](../AGENTS.md) 中的轻�路径；扩展版 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) 工作�仅在用户显�调用时�用。\n\n## �对约定\n\n- **两�语言��。** 一篇文档�以先用任一语言撰写和评审（先写中文的 Agent Note 与先写英文的一样正当），�一侧由它翻译而�。两个文件�也�高于�；约�它们的是二者必须说�样的�。\n- **一对文档是三个�目录文件。** 英文 `foo.md`�中文 `foo.zh.md`，加一份一致性记录 `foo.i18n.yaml`，都在�一目录。�用语言目录，�用独立翻译仓库，�用中英混排的�文件。�对必须整体�并：PR（Pull Request）永远�会�带一�语言而缺其余两个文件。\n- **一致性记录。**`foo.i18n.yaml` �存两侧文件在上一次被确认「说�样的��时�自的完整 git blob hash：\n\n  ```yaml\n  foo.md: 3f786850e387550fdab836ed7e6dc881de23001b\n  foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b\n  ```\n\n  用 blob hash 而�是 commit hash，这样�一个 PR 里改动的文件也能算出记录（`git hash-object foo.md`），一致性是纯内容比较。`--write` 会先把这些快照存入本地 Git 对象库�写下记录，未�交的工作树内容也�例外；它还会在内容寻�的 `refs/dsh/translation-pairing/snapshots/` ref 下固定�个��的已存 blob，使垃圾回收无法让已记录的��指针失效。因此记录的 hash 能还原任一侧上次确认时的确切文本，所以失去�步的�对是「按被改一侧的 diff 最�化地修补�一侧�，从�整篇�译。日常工作会直接完�这份修补；用户显�调用扩展工作�时，�改由 `pnpm run gen-translation-brief <pair>` 以能安全对�的最窄粒度汇集这次更新，并由 `--apply` 在结构校验�拼接仅涉�围�代��的改动（[briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)）。两侧对��，`pnpm run verify-translation-pairing --write <pair>` �新记录两个 hash；那份 yaml diff 就是「确认一致�这个动作本身，�以被评审，也正因如此，`--write` �求点�你确认过的�对（`--write --all` 是显�的全语料形�）。\n\n  当两个分支都包��一�对的有效确认时，已安装的 `dsh-translation-pairing` Git �并驱动�会在 Git 默认文本�并能分别干净�并记录所指�的英文三方 blob 与中文三方 blob，且�并�的�对��留必需的语言切�行和结构签�时，组�出一份新记录。中文文件必须�留指�英文的��链接；普通撰写的英文�必须�留指�中文的链接，而清�内的生�英文��作此�求。任何�并驱动无法验�的结构都�留为普通冲�；`pnpm run resolve-translation-pairing-conflicts` 会对已��止的�并执行�一套�错��留冲�的�作，暂存�份�安全生�的�对记录，并在还有其他�对冲�时以�零状�退出。[自动�对�并 Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责记录该机制与备选方案。\n- **语言切�行。** 中文文件一律在 H1 标题�立�以 `[English](foo.md) | 中文` 链回英文。普通撰写的英文文件在�一�置以 `English | [中文](foo.zh.md)` 互链；清�内的生�英文��略此行，以便与生�器输出�字节一致。\n- **结构与�一侧一一对应。** 标题深度与顺�
      },
      {
        "role": "user",
        "content": "# Translation rules\n\nEnglish | [中文](translation-rules.zh.md)\n\nHow to translate between the two sides of a documentation pair in this repo. Both languages carry equal authority ([README.md](README.md)): a change is authored in either language, and that side is the source for that update — these rules govern producing or updating the counterpart. They bind humans and agents equally. Routine agent work translates the changed content directly in one terminology-guided pass; the extended [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) workflow runs only when the user explicitly invokes it. Rule levels follow RFC 2119 usage: **MUST** / **MUST NOT** are gate- or review-blocking; **SHOULD** needs a stated reason to deviate; **MAY** is discretionary.\n\n## Faithfulness\n\n- The counterpart *MUST* say what the authored side says — no added behavior, prerequisites, warnings, version claims, or examples, and no dropped ones. If the pair disagrees on substance, neither language wins by default: fix the side that is wrong, then bring the other along in the same change.\n- The counterpart *SHOULD* read as natural technical writing in its own language, not word-by-word gloss. Translate meaning, restructure sentences where the target grammar wants it, and keep the author's register — terse stays terse.\n- Do not translate the untranslatable: if a sentence resists natural rendering because it leans on an idiom of the source language, translate the idea, not the idiom.\n\n## Voice\n\n- The register is calibrated by [style-samples.md](style-samples.md) — human-approved gold pairs, one per document genre. The counterpart MUST match the target-language side of the nearest sample; where its voice and a prose voice rule disagree, the sample wins. Chinese targets use institutional technical Chinese; English targets use concise professional developer prose.\n- Write as a native technical author restating the content, not as a translator transposing sentences, while preserving every source clause: nothing added, nothing dropped — fluency never justifies losing a clause.\n- Give sentences an explicit actor when the target language would otherwise obscure it; for Chinese, replace vague passives or abstract subjects with the actual actor (系统ã€�é—¨ç¦�ã€�评审人).\n- Prefer established target-language engineering idiom over calques (误报ï¼�æ¼�检 for false positive/negative, 执行红线 for enforcement frontier); localize metaphors instead of transplanting them, and unpack noun chains where the target language requires it.\n- Split long paragraphs by semantic unit — one idea per paragraph. Paragraph boundaries MAY differ from the source; the structural signature does not count paragraphs.\n- When translating into Chinese, category nouns use Chinese with a first-mention English annotation (实æ“�æ���‹å†Œï¼ˆcookbook）); when translating into English, use the conventional English category name. Literal directory or file references stay code-formatted English.\n\n## Structure preservation\n\nThe pairing gate checks heading depths, fenced code blocks, table row and column counts, list kinds, ordered-list starts, list item counts, and link targets. Preserve the rest of the frame manually; the paired files MUST match one to one in:\n\n- heading hierarchy (same levels, same order — heading TEXT is translated),\n- list shape and numbering,\n- tables (same columns, same row order; header cells translated per terminology),\n- fenced code blocks — **byte-identical, including comments**; the pairing signature compares their info strings and contents, and ` ```ts ` blocks compile under `doc-typecheck`,\n- inline code spans (commands, flags, config keys, file paths, event names, API names, version numbers) — verbatim, never translated or reformatted,\n- links and anchors: every relative link MUST point at the same target in both files — by convention the `.md` path, not the `.zh.md` sibling — so links never dangle when one pair lands before its neighbors. The ONLY zh-spec
      },
      {
        "role": "assistant",
        "content": "# 翻译规则\n\n[English](translation-rules.md) | 中文\n\n本文规定：如何在本仓库文档é…�对的中英文两ç§�语言之间进行翻译。两ç§�语言å�Œæ�ƒï¼ˆè§� [README.md](README.md)）：æ¯�次å�˜æ›´å�¯ä»¥ç”¨ä»»ä¸€è¯­è¨€æ’°å†™ï¼Œè¢«ç¼–辑的一侧å�³ä¸ºæœ¬æ¬¡æ›´æ–°çš„æº�；本文的规则约æ�Ÿå¦‚何产出或更新对侧文件。这些规则对人类和 agent（智能体）å�Œç­‰ç”Ÿæ•ˆã€‚日常工作中，agent 会在术语指导下直接一次完æˆ�有改动内容的翻译；扩展版 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) 工作æµ�仅在用户显å¼�调用时è¿�行。规则级别沿用 RFC 2119 的用法：**必须（MUST）** ï¼� **ç¦�止（MUST NOT）** 会å�¡é—¨ç¦�或评审；**应当（SHOULD）** å��离时è¦�说明ç�†ç”±ï¼›**å�¯ä»¥ï¼ˆMAY）** 自行è£�é‡�。\n\n## 忠实性\n\n- 对侧文件*å¿…é¡»*传达与撰写侧相å�Œçš„内容：ä¸�添加行为ã€�å‰�ç½®æ�¡ä»¶ã€�警告ã€�版本声明或示例，也ä¸�æ¼�掉任何一项。如果两侧在实质内容上ä¸�一致，没有哪ç§�语言默认获胜；请修正错误的一侧，并在å�Œä¸€ä¸ªå�˜æ›´é‡Œå�Œæ­¥æ›´æ–°å�¦ä¸€ä¾§ã€‚\n- 对侧文件读起æ�¥*应当*是其语言自然的技术文字，而é�žé€�è¯�对照的译文。请根æ�®è¯­ä¹‰ç¿»è¯‘，在目标语言语法需è¦�æ—¶é‡�组å�¥å­�，并ä¿�æŒ�原作者的语域（比如：简练的ä¿�æŒ�简练）。\n- ä¸�è¦�翻译ä¸�å�¯è¯‘的内容：如果一å�¥è¯�ä¾�èµ–æº�语言的习语ã€�无法自然转æ�¢ï¼Œè¯·ç¿»è¯‘它的æ„�æ€�，而é�žä¹ è¯­æœ¬èº«ã€‚\n\n## 行文\n\n- 语体以 [style-samples.md](style-samples.md) 为校准锚点。人工定稿的金标样例按文体å�„一组，译文必须å�‚照文体最接近的样例，采用其中目标语言一侧的语体；如果样例与本文的行文规则冲çª�，以样例为准。译æˆ�中文时，采用规范的技术制度文；译æˆ�英文时，采用简æ´�ã€�专业的开å�‘者文档语体。\n- 以æ¯�语技术作者的身份é‡�述内容，而ä¸�是以译者身份é€�å�¥è½¬å†™ï¼Œå�Œæ—¶ä¿�留原文的æ¯�个语义æˆ�分：ä¸�添加ã€�ä¸�é�—æ¼�——æµ�畅永远ä¸�是丢掉语义æˆ�分的ç�†ç”±ã€‚\n- 如果直译会让执行主体å�«ç³Šï¼Œè¯·æ˜Žç¡®å†™å‡ºå®žé™…执行者；译æˆ�中文时，应由「系统ã€�é—¨ç¦�ã€�评审人ã€�等实际执行者作主语，é�¿å…�å�«ç³Šçš„被动å�¥æˆ–抽象主语。\n- 优先采用目标语言中通行的工程表达，é�¿å…�生硬直译（false positive/negative→误报ï¼�æ¼�检ã€�enforcement frontier→执行红线）；éš�喻应自然改写，å��è¯�链则按目标语言的习惯拆开。\n- 长段按语义å�•å…ƒæ‹†åˆ†ï¼Œä¸€æ®µä¸€ä»¶äº‹ã€‚段è�½è¾¹ç•Œå�¯ä»¥ä¸ŽåŽŸæ–‡ä¸�å�Œï¼›ç»“æž„ç­¾å��ä¸�比对段è�½æ•°ã€‚\n- 翻译为中文时，类别å��è¯�使用中文并在首现括注英文（实æ“�手册（cookbook））；翻译为英文时，使用通行的英文类别å��。指目录或文件本身时ä¿�留代ç �体英文。\n\n## 结构ä¿�æŒ�\n\né…�对门ç¦�会检查标题深度ã€�å›´æ �代ç �å�—ã€�表格行列数ã€�列表类型ã€�有åº�列表起始编å�·ã€�列表项数é‡�与链接目标；门ç¦�未覆盖的结构ä»�需人工核对。两个é…�对文件必须在以下方é�¢ä¸€ä¸€å¯¹åº”：\n\n- 标题层级（相å�Œçº§åˆ«ã€�相å�Œé¡ºåº�；标题的**文字**è¦�翻译）；\n- 列表形æ€�与编å�·ï¼›\n- 表格（相å�Œçš„列ã€�相å�Œçš„è¡Œåº�；表头å�•å…ƒæ ¼æŒ‰æœ¯è¯­è¡¨ç¿»è¯‘）；\n- å›´æ �代ç �å�—：**é€�字节一致，包括注释**。é…�对签å��比对信æ�¯å­—符串与内容，` ```ts ` å�—还è¦�通过 `doc-typecheck` 编译；\n- 行内代ç �（命令ã€�flagã€�é…�置键ã€�文件路径ã€�事件å��ã€�API å��ã€�版本å�·ï¼‰ï¼šåŽŸæ ·ä¿�留，从ä¸�翻译或é‡�排；\n- 链接与锚点：æ¯�个相对链接在两个文件中必须指å�‘相å�Œçš„目标（按约定是 `.md` 路径而é�ž `.zh.md` 兄弟文件），这样å�³ä½¿æŸ�对文档先于相邻文件è�½åœ°ï¼Œé“¾æŽ¥ä¹Ÿä¸�会悬空。唯一的 zh 特有链接是语言切æ�¢è¡Œã€‚链接**文字**翻译；链接目标ä¸�翻。\n\n本仓库的 Markdown 约定对 `.zh.md` 文件原样生效：一个段è�½ä¸€ä¸ªç‰©ç�
      },
      {
        "role": "user",
        "content": "# Agent Note: Bilingual documentation via paired sibling files and a pairing gate\n\nStatus: implemented\n\nEnglish | [中文](2026-07-02-bilingual-docs-and-pairing-gate.zh.md)\n\n## Problem\n\nThis repo's documentation corpus is read by people and agents inside and outside the company, in both English and Chinese. Maintaining a second language by hand, with no mechanism, is how translations rot: one side moves on, the other silently lies, and no gate notices. The repo's standing answer to invariants of this kind is to encode them as a mechanical check (see [quality gates](2026-06-11-quality-gates.md) and [doc-sync enforcement](../../archived/process/2026-06-11-doc-sync-enforcement.md)), so the bilingual policy ships with one.\n\n## Decision\n\n- **Paired sibling files with equal authority.** A documentation pair is three sibling files: English `foo.md`, Chinese `foo.zh.md`, and a consistency record `foo.i18n.yaml`. Neither language is canonical — a document may be authored and reviewed Chinese-first and translated to English afterwards, or the reverse; what binds the pair is that both sides must say the same thing, and pairs merge whole (both languages plus the record, never one alone). Policy: [docs/i18n/README.md](../../../../docs/i18n/README.md); translation rules: [docs/i18n/translation-rules.md](../../../../docs/i18n/translation-rules.md); terminology source of truth: [docs/i18n/terminology.md](../../../../docs/i18n/terminology.md).\n- **A sidecar record of both blob hashes makes consistency checkable.** `foo.i18n.yaml` holds the full git blob hash of each side as of the last confirmed-consistent state. An edit to either side without re-confirming the pair is then mechanically detectable as a pure content comparison — no history lookup — and the hashes are computable for files edited in the same PR, which a commit-hash record is not. Re-recording (`verify-translation-pairing --write <pair>`, which requires naming the confirmed pairs — bulk re-record is an explicit `--write --all`) produces a reviewable yaml diff: confirming consistency is an explicit, visible act in the PR.\n- **`verify-translation-pairing` joins `doc-sync`.** The gate ([scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)) enforces: every discovered, non-excluded source has a complete pair; every existing pair is complete (all three files) and consistent (both hashes match, the Chinese side and every authored English source carry their switchers while listed generated English sources are exempt, structural signatures identical); and excluded generated, instruction, or bilingual-by-construction files stay unpaired. [scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) contains only explicit exclusions, so no requirement can bypass discovery and receive a weaker check. Source-oriented code gates consume a `.zh.md` fence sequence as a derivative only when its unsuffixed sibling has the same tracked fences in the same order with byte-identical bodies; an incomplete, reordered, reclassified, or changed sequence stays independent, so the owning code gate or pairing gate reports the mismatch.\n- **One corpus-wide requirement.** Every document in scope requires a complete pair from creation; the policy has no per-file rollout state, date cutoff, or README-specific class. README discovery covers every case-insensitive README basename outside vendored, dependency, and ignored build-output trees, including future top-level directories. A site-published pair uses `pairedPages()` so the root locale projects `.zh.md` and `/en/` projects `.md`; creating a counterpart alone does not publish it.\n- **Pairing records are metadata, not Cordis Loader configuration.** Cordis configuration discovery accepts actual `.cordis.yml` and `.cordis.yaml` files while excluding `*.i18n.yaml`, even when the document name contains `cordis`. This preserves validation of executable Loader entries without parsing translation hashes as configuration.\n- **Translation is agent
      },
      {
        "role": "assistant",
        "content": "# Agent Note: 通过�对兄弟文件与�对门�实现�语文档\n\nStatus: implemented\n\n[English](2026-07-02-bilingual-docs-and-pairing-gate.md) | 中文\n\n## 问题\n\n本仓库的文档语料会被公�内外的人和 agent（智能体）以中英两�语言阅读。在没有机制的情况下纯�手工维护第二语言，正是译文�烂的根�：一侧�续演进，�一侧默默失实，而没有门�会注�到。对于这类���，本仓库一贯的�法是将其编�为机械检查（�[质�门�](2026-06-11-quality-gates.md)与 [doc-sync 强制](../../archived/process/2026-06-11-doc-sync-enforcement.md)），因此�语政策�附一�门�一起交付。\n\n## 决策\n\n- **�对兄弟文件，两�语言��。** 一对文档由三个兄弟文件组�：英文 `foo.md`�中文 `foo.zh.md`，以�一份一致性记录 `foo.i18n.yaml`。没有哪�语言是正典：一篇文档�以先用中文撰写和评审�之��译�英文，�之亦�；约��对的是：两侧必须表达相�的内容，且�对整体�并（两�语言加记录，���独�一侧）。政策� [docs/i18n/README.md](../../../../docs/i18n/README.md)；翻译规则� [docs/i18n/translation-rules.md](../../../../docs/i18n/translation-rules.md)；术语真�� [docs/i18n/terminology.md](../../../../docs/i18n/terminology.md)。\n- **伴�记录�存两侧 blob hash，使一致性�检查。** `foo.i18n.yaml` �存两侧文件在上一次确认一致时�自的完整 git blob hash。此�修改了任一侧而未�新确认�对，都能被机械检测出�（纯内容比较，无需查询历�），而且�一个 PR（Pull Request）内改动的文件也能计算出 hash，commit hash �的记录��到这一点。�新记录（`verify-translation-pairing --write <pair>`，�求点�所确认的�对；批��新记录是显�的 `--write --all`）会产生一份�评审的 yaml diff：确认一致在 PR 中是一个显����的动作。\n- **`verify-translation-pairing` 加入 `doc-sync`。** 门�（[scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)）强制执行以下规则：�个已�现且未排除的�文档都有完整�对；�个现有�对都完整（三个文件�全）且一致（两个 hash 匹��中文侧和所有普通撰写的英文�都带切�行而清�内的生�英文�除外�结构签�一致）；被排除的生�文档�指令文档或本身��语的文档�得�对。[scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) �包�显�排除项，因此任何�求都无法绕过�现�程而接�较弱的检查。�有当 `.zh.md` 围��列与其无�缀兄弟文件拥有顺�相��正文按字节一致的�一组�跟踪围�时，����的代�门��会将其作为派生内容消费；�完整�顺��更��分类或已改动的�列�会独立�检，因此由其所属的代�门�或�对门�报告�匹�。\n- **全语料统一�求。** 范围内的�篇文档从创建起就必须有完整�对；政策没有�文件推进状��日期分界或 README 专用类别。README �现会覆盖 vendor ����赖目录与被忽略的构建产物目录之外所有文件��区分大�写匹� README 的文件，包括今�新增的顶层目录。�布到文档站的�对使用 `pairedPages()`，由根 locale 投影 `.zh.md`，由 `/en/` 投影 `.md`；仅创建对侧文件并�会�布它。\n- **�对记录是元数�，而�是 Cordis Loader �置。** Cordis �置�现会接�实际的 `.cordis.yml` 和 `.cordis.yaml` 文件，�时排除 `*.i18n.yaml`，�使文档�中包� `cordis` 也�例外。这样既能继续校验�执行的 Loader �置项，��会把翻译 hash 当作�置�解�。\n- **翻译是 agent 的工作，由人评审。** 常规改动采用由[轻�翻译决策](2026-08-08-lightweight-
      },
      {
        "role": "user",
        "content": "---\nlayout: doc\n---\n\n# Snapshot note\n\nThe agent performs one step.\n"
      }
    ]
  },
  "response": {
    "translation": "---\nlayout: doc\n---\n\n# 快照说明\n\nagent（智能体）执行一个步骤。",
    "review": "- 无修正",
    "final": "---\nlayout: doc\n---\n\n# 快照说明\n\n[English](snapshot-note.md) | 中文\n\nagent（智能体）执行一个步骤。\n"
  }
}