dsh-plugin-dev-kb 1.0.0

package/kb/extra/i18n/terminology.md

@@ -0,0 +1,214 @@
+# Terminology
+
+本表约定本仓库的中英术语统一译法。
+
+**通用规则：**
+- "中文"列为中文译文的正文默认用词。若该列为英文，则中文译文的正文中保留英文不翻译。
+- 首次出现按"首次出现"列书写（带括号注释）；后续出现只写括号前的部分（可能为中文，也可能为英文），不出现括号内的注释。
+- "不要译作"列为严格禁止的译法。
+- 如果某术语已经作为另一个术语的组成部分被括注过（如 `agent loop（智能体循环）` 中已包含 `agent` 的括注），则该术语后续单独出现时无需再次括注。
+
+## 缩写类（中英文文本中均使用缩写）
+
+| English | 中文 | 首次出现 | 不要译作 | 备注 |
+|---|---|---|---|---|
+| ACP | ACP | ACP（Agent Client Protocol） | | |
+| AI | AI | AI（人工智能） | | |
+| API | API | | | |
+| CI | CI | | | |
+| CLI | CLI | CLI（命令行界面） | | |
+| e2e | e2e | | | |
+| HMR | HMR | HMR（热模块替换） | | |
+| JSON Schema | JSON Schema | | | |
+| JSONL | JSONL | | | |
+| LLM | LLM | LLM（大语言模型） | | |
+| MCP | MCP | | | |
+| PR | PR | PR（Pull Request） | | |
+| RAG | RAG | RAG（检索增强生成） | | |
+| SDK | SDK | | | 只指受支持的 Python 与 TypeScript SDK 所使用的 JSON-RPC 客户端／服务器协议；DeepSeek Harness 项目本身不是 SDK |
+| SSE | SSE | SSE（Server-Sent Events） | | |
+
+## 英文类（中英文文本中均使用英文）
+
+| English | 中文 | 首次出现 | 不要译作 | 备注 |
+|---|---|---|---|---|
+| agent | agent | agent（智能体） | | |
+| Agent Note | Agent Note | | 智能体注记、智能体笔记 | 仓库定义的文档类型，涵盖提案、已实现决策和被否决提案；中文对侧 H1 保持固定前缀 `# Agent Note: `，标题中不加术语括注 |
+| agent harness | agent harness | agent harness（智能体框架） | | agent 组合词（agent harness/workflow/loop/skill 等）整体保留英文；未括注过 agent 时首现按对应组合词或 agent 行处理 |
+| agent loop | agent loop | agent loop（智能体循环） | | |
+| blob hash | blob hash | | | `git hash-object` 的结果 |
+| coding agent | coding agent | coding agent（编程智能体） | | agent 组合词，正文保留英文 |
+| Cordis | Cordis | | | |
+| dispose | dispose | dispose（资源释放） | | |
+| doc-sync | doc-sync | doc-sync（文档同步门禁） | | |
+| fiber | fiber | | | |
+| fixture | fixture | fixture（测试前置数据） | | |
+| fork | fork | | | |
+| Function Calling | Function Calling | Function Calling（函数调用） | | |
+| harness | harness | | | |
+| harness engineering | harness engineering | | | |
+| KV Cache | KV Cache | | | 专有技术名称，保持大小写与空格 |
+| lint | lint | | | |
+| mock | mock | | | 保留英文；指测试替身 |
+| loader | loader | | | |
+| manifest | manifest | manifest（元数据清单） | | |
+| monorepo | monorepo | | | |
+| Round | Round | | 回合、目标回合、Ralph 回合 | 外层策略使用 Round 时，领域层级为 Session > Round > Turn（轮次） > Step（步骤）；Round 是可选的外层策略迭代，并非每个会话轮次都具有的通用层级。Goal Round 与 Ralph Round 均保留英文。一个 Round 承载一个轮次，步骤隶属于该轮次；明确的零步骤轮次仍保持原义。 |
+| schema | schema | | | |
+| schema DSL | schema DSL | | | |
+| seam | seam | | 接缝 | 一个可替换能力的整体，包含 Service Definition / Service Provider / Consumer 三种角色；角色需要独立演化时才拆包，也可由同一包承担多个角色。以 `packages/shell` 为范例；Service Definition 是 Cordis `Service`（抽象类或具体 registry 服务），不是 TypeScript interface。任何单一角色、普通边界或扩展点都不能称为 seam。本仓库正文保留英文；与 `extension point` 是不同概念 |
+| Service Provider | Service Provider | | Service provider | 能力 seam 的命名角色；单数固定写作 Service Provider，复数写作 Service Providers。泛指提供服务的 provider 不适用本词条 |
+| skill | skill | skill（技能） | | |
+| slot | slot | | 坑位、孔位 | 客户端架构中的具名可注册位置，保留英文 |
+| spill | spill | | | 工具输出超限落盘机制；组合词写 `spill 文件`、`spill 路径` |
+| spawn | spawn | | | |
+| steering | steering | steering（中途引导） | | |
+| job id | job id | | 任务 id | 保留英文 |
+| subagent | subagent | | | |
+| transcript | transcript | transcript（文本记录） | | 指会话渲染给用户或编辑器的完整文本，区别于事件日志 |
+| Typert | Typert | | TypeRT、typeRT、Type RT | DeepSeek Harness 类型图、生成器、loader 与运行时 registry 的产品拼写 |
+| waterfall | waterfall | waterfall（瀑布式事件） | | |
+| wheel | wheel 包 | | | Python 打包格式 |
+| worktree | worktree | | | git 工作区概念 |
+| Zstandard | Zstandard | | | RFC 8878 compression format; `zstd` remains a code value. |
+
+## 双语类（中英文文本各自使用中英文）
+
+| English | 中文 | 首次出现 | 不要译作 | 备注 |
+|---|---|---|---|---|
+| adapter | 适配器 | | | |
+| adapter contract | 适配器约定 | 适配器约定（adapter contract） | | |
+| append-only | 仅追加 | | | |
+| artifact | 产物 | | 制品 | |
+| backend | 后端 | | | |
+| binder | 绑定器 | | | 命名角色：把已声明接口绑定到调用方 context 或生命周期 |
+| config | 配置 | | | 命名角色：一个已解析配置值或边界严格的配置记录 |
+| controller | 控制器 | | | 命名角色：接受意图并改变一项既有领域或展示状态 |
+| directory | 目录 | | | 命名角色：暴露供发现或选择的条目及元数据 |
+| engine | 引擎 | | | 命名角色：实现领域算法或有状态执行模型 |
+| gateway | 网关 | | | 命名角色：适配进程、网络、RPC 或 API 边界 |
+| handle | 句柄 | | | 命名角色：引用并控制或观察一个实时资源 |
+| policy | 策略 | | | 命名角色：决定允许、选择、限制或观察什么 |
+| presenter | 展示转换器 | | | 命名角色：把领域值纯转换为渲染意图 |
+| resolver | 解析器 | | | 命名角色：根据输入计算或定位一个答案 |
+| store | 存储 | | | 命名角色：拥有一组数据并主要提供数据操作 |
+| background job | 后台任务 | | | |
+| block | 块 | | | |
+| build target | 构建目标 | | | |
+| cancel | 取消 | | | |
+| canary test | canary 测试 | | 金丝雀测试 | 本仓库保留 `canary` |
+| capability | 能力 | | | 必须与 `feature` → `功能` 区分 |
+| capability seam | 能力 seam | | 功能 seam、能力接缝 | 本仓库 Service Definition、Service Provider 与 Consumer 三种角色组成完整可替换能力的命名架构概念；普通 `seam` 仍按其词条处理 |
+| feature | 功能 | | 能力 | SDK 产品与工程模型中的可管理产品单元 |
+| feature option | 功能选项 | | variant | 一项 SDK 功能内有限、可选择的实现或配置 |
+| checkpoint | 检查点 | | | |
+| chunk | 分片 | | | |
+| compaction | 压缩 | 压缩（compaction） | | |
+| companion tool | 配套工具 | | | |
+| composition bundle | 组合包 | | | 只约束应用或插件的组合语境，不约束所有 `bundle` |
+| Cordis plugin config | Cordis 插件配置 | | | Cordis 插件公开的 `Config` 对象或配置结构 |
+| config key | 配置键 | | | Cordis 插件配置中的单个字段 |
+| consumer | 消费方 | | 消费者 | |
+| content block | 内容块 | | | |
+| Cookbook | 实操手册 | | | 文档标题用语 |
+| context | 上下文 | | | |
+| counterpart | 对侧文件 | | 对应物、配对物 | 双语配对语境；泛指"另一侧"时可写「另一侧」 |
+| configurable-provider directory | 可配置提供方目录 | | | llm seam 中 `registerConfigurableProviders()` 维护的目录；沿用 Service Catalog →「服务目录」先例 |
+| context compaction | 上下文压缩 | 上下文压缩（context compaction） | | |
+| contract | 约定 | | | 如：`pairing contract` →`配对约定` |
+| Cordis config entry | Cordis 配置项 | | | 指 `cordis.yml` 插件列表中的一项；插件实现本身写`Cordis 插件` |
+| Cordis plugin | Cordis 插件 | | | Cordis 加载的插件实现，不指 `cordis.yml` 中的一项配置 |
+| crash recovery | 崩溃恢复 | | | |
+| deploy root | 部署根目录 | | | |
+| dormant | 休眠 | | 睡眠、蛰伏 | 指已声明可配置但当前未注册路由的提供方 |
+| durability | 持久性 | | | |
+| feature requirement | 功能依赖 | | | 功能或功能选项通过 `requires` 声明的关系 |
+| event | 事件 | | | |
+| event log | 事件日志 | | | |
+| event stream | 事件流 | | | |
+| event-sourced | 事件溯源 | | | 沿用 DDD 社区通行译法 |
+| Executive summary | 摘要 | | | 事故复盘标题用语 |
+| executor | 执行器 | | | |
+| expected output | 预期输出 | | 金标 | 指 snapshot 比较产物；翻译语料的人工校准样例不在此列 |
+| extension | 扩展 | | | |
+| extension point | 扩展点 | | | 注意与 `seam` 区分 |
+| fail-fast | 快速失败 | | | |
+| fenced code block | 围栏代码块 | | | 沿用 MDN 中文翻译 |
+| fingerprint | 指纹 | | | 通用内容指纹；双语配对机制使用 sidecar record 记录两侧 blob hash |
+| finish reason | 结束原因 | | | |
+| fold | 折叠区 | | | 配置界面语境：默认收起的字段分区（collapsed →「收起」）|
+| foreground run | 前台运行 | | | |
+| freshness | 新鲜度 | | | 沿用 MDN 中文翻译；在本项目中指译文相对源文的同步状态 |
+| hook | 钩子 | | | |
+| implementation | 实现 | | | |
+| inference | 推理 | 推理（inference） | | 需要和 `reasoning` 区分时保留英文括注 |
+| info string | 信息字符串 | | | 沿用 CommonMark 中文翻译；指代码围栏 ``` 之后的语言标注 |
+| injection | 注入 | | | |
+| integration | 集成 | | | |
+| interface | 接口 | | | |
+| language switcher | 语言切换行 | | | i18n 配对机制用语：双语配对文件顶部的互链行 |
+| merge | 合并 | | | |
+| message | 消息 | | | |
+| mod | 模组 | | | |
+| model provider | 模型提供方 | | | |
+| model selection | 模型选择 | | 模型目标 | 面向 Agent 的提供方、模型和可选推理强度选择。 |
+| module | 模块 | | | |
+| non-escalation | 非升权 | | 非升级、不可升级 | 仅用于安全与权限语境，指主体不得获得超出既有授权的权限；普通升级不适用此行 |
+| npm dependency | NPM 依赖 | | | `package.json` 中的包关系；`dependencies`、`devDependencies` 等字段保持原样 |
+| opt-out ratio | opt-out 比例 | | 退出检查比例 | |
+| orphan | 遗留 | | 孤儿、孤立 | 指英文源已不存在的 `.zh.md`（如「遗留译文」）；进程语境按 OS 惯用语译「孤儿进程」 |
+| orphan branch | 孤立分支 | | 孤儿分支 | 沿用 git 官方中文翻译 |
+| package | 包 | | | 指 npm 包（`@deepseek-ai/dsh-*`）；`package.json` 等代码标识保持原样 |
+| pairing | 配对 | | | |
+| parent-subset grants | 父级子集授权 | | 父集合授权 | 指授权范围仅限于父级所持授权的子集 |
+| peer dependency | 对等依赖 | 对等依赖（peer dependency） | | |
+| permission | 权限 | | | |
+| persistence | 持久化 | | | |
+| pipeline | 流水线 | | | |
+| plugin | 插件 | | | |
+| postmortem | 事故复盘 | 事故复盘（postmortem） | 事后分析、事故记录 | 事故记录与分析文档；目录或路径中的 `postmortem` 保持代码形式 |
+| prompt | 提示词 | | | |
+| provider | 提供方 | | | |
+| provider-neutral | 提供方无关 | | 提供方中立 | |
+| quality gate | 质量门禁 | | | |
+| quiescence | 完全停稳 | | 静默、静止状态 | 指生命周期工作全部结算后的状态 |
+| reasoning | 推理 | 推理（reasoning） | | 需要和 `inference` 区分时保留英文括注 |
+| reasoning_content | 思考内容 | | | |
+| registry | 注册表 | | | |
+| replay | 回放 | | | |
+| resume | 恢复 | | | |
+| runtime | 运行时 | | | |
+| same-world subprocess | 与宿主共享文件系统和内核的子进程 | | 同世界子进程 | |
+| sandbox | 沙箱 | | | |
+| service | 服务 | | | |
+| serving interface | 对外服务接口 | | | |
+| session | 会话 | | | |
+| session event | 会话事件 | | | |
+| setup card | 设置卡片 | | | 首次运行时代替行卡直接展开的配置卡 |
+| sidecar file | 伴随文件 | | | 指与文档同目录的普通伴随文件 |
+| sidecar record | 伴随记录 | | 旁挂记录 | 指与文档同目录的伴随记录文件 |
+| smoke test | 冒烟测试 | | | |
+| snapshot | 快照 | | | |
+| source of truth | 真源 | | 事实来源、唯一来源 | |
+| spine | 主干 | | | |
+| stale | 陈旧 | | 过期 | 与 `fresh`（`新鲜`）成对；门禁输出中保留英文 `stale` 不翻译；`expired` 才译为`过期` |
+| step | 步骤 | | | |
+| stream | 流 | | | |
+| structural signature | 结构签名 | | | i18n 配对机制用语：门禁比对两侧文件时提取的有序结构序列（标题层级、代码块、列表等） |
+| Summary | 概述 | | | 事故复盘标题用语 |
+| system prompt | 系统提示词 | | | |
+| taxonomy | 分类体系 | | | |
+| token usage | token 用量 | | | |
+| tool | 工具 | | | |
+| tool call | 工具调用 | | | |
+| tool result | 工具结果 | | | |
+| tool schema | 工具 schema | | | |
+| toolkit | 工具包 | | | |
+| turn | 轮次 | | | |
+| VFS | VFS | 虚拟文件系统（VFS） | | |
+| typecheck | 类型检查 | | | |
+| vocabulary | 词汇 | | | |
+| wire format | 协议格式 | 协议格式（wire format） | | |
+| workflow | 工作流 | | | |
+| wrapper | 包装层 | | | 软件层或 SDK 包装层 |
+| wrapper script | 包装脚本 | | | 可执行脚本包装层 |

package/kb/extra/i18n/translation-prompt.md

@@ -0,0 +1,263 @@
+# Translation prompt (pipeline asset)
+
+本文件是自动翻译流水线的 prompt 模板；从 `# Translation Prompt` 开始的正文会逐字进入模型请求，因此本文件不参与双语配对（见 [README.md](README.md) 排除清单）。模板正文与内嵌 few-shot 正误例由 jingtingxiang 基于对存量译文的质量评审撰写，是流水线行为的拍板基线。渲染时把 [terminology.md](terminology.md) 整表填入 `{{terminology}}`；除此之外不注入任何其他仓库文件（translation-rules.md 约束人和 agent 的翻译工作，不注入本模板）。[style-samples.md](style-samples.md) 定义文体，模板中的 Examples 只用于说明典型问题，两者冲突时以文体样例为准。本模板遵循 [提示词 v4 约定 Agent Note](../../.agents/notes/implemented/process/2026-07-23-translation-prompt-v4-contract.md) 记录的兼容协议。修改本文件会改变翻译行为，需正常经过 PR 评审。
+
+## 占位符约定
+
+流水线渲染模板时替换以下占位符，除此之外不改写系统消息：
+
+| 占位符 | 填入内容 | 来源 |
+|---|---|---|
+| `{{source_lang}}` | 源语言名（`English` / `Chinese`） | 由改动侧文件推断：`.zh.md` 被改则为 `Chinese` |
+| `{{target_lang}}` | 目标语言名（`Chinese` / `English`） | 与 `{{source_lang}}` 相对 |
+| `{{terminology}}` | [terminology.md](terminology.md) 的完整表格（Markdown 原文） | 渲染时读取仓库当前版本，不缓存 |
+
+流水线只识别上表中的占位符，并且一次翻译整篇文档。它不支持 `{{to}}`、`{{title_prompt}}`、`{{summary_prompt}}`、`{{terms_prompt}}`、`{{imt_style_guide}}`、`{{translation_rules}}` 或 `%%` 分段协议；输出采用模板正文规定的三段 XML，流水线解析取 `<final>` 段。
+
+语言切换行：已有配对的源文件自带切换行，模型按模板规则翻转即可。全新配对的源文件没有切换行，模型也无从得知文件名——此时由流水线在解析 `<final>` 后按目标文件名插入或校正切换行（机械后处理，配对门禁兜底校验）。
+
+## Few-shot 金标
+
+流水线使用**整篇文档**的中英对照作为 few-shot，不是模板内嵌的句子级正误例。以下 5 组配对文档均经过人工评审，以仓库当前版本为准、随仓库更新：
+
+- `README.md` ↔ `README.zh.md`
+- `docs/development.md` ↔ `docs/development.zh.md`
+- `docs/i18n/README.md` ↔ `docs/i18n/README.zh.md`
+- `docs/i18n/translation-rules.md` ↔ `docs/i18n/translation-rules.zh.md`
+- `.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md` ↔ 对应 `.zh.md`
+
+注入方式：在系统消息（本模板）之后、待译文档之前，每组作为一轮示例对话——user 消息为源文档全文，assistant 消息为定稿译文全文（裸文本，不带三段 XML 包装；只有真实请求要求三段输出）。上下文不足时按上列顺序从后往前删减组数。这 5 组也是评审校准锚点（见 [style-samples.md](style-samples.md)），改动任何一组即改变流水线行为。
+
+## 模板正文
+
+````text
+# Translation Prompt
+
+You are a senior technical translator specializing in LLM and agent development documentation. Your task is to translate the complete source document from {{source_lang}} to {{target_lang}}, producing natural, professional technical prose.
+
+Read 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.
+
+## Priority
+
+Apply these authorities in order:
+
+1. Preserve the source meaning and the required document structure, protected content, and formatting.
+2. Follow the injected terminology table exactly.
+3. Use the injected whole-document gold pairs to calibrate target-language voice and phrasing.
+4. Apply the general writing guidance and illustrative examples in this prompt.
+
+A 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.
+
+## Quality Requirements
+
+### Structure and Format Preservation
+- 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.
+- 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.
+- Keep each prose paragraph on one physical line. Use paragraph breaks, not hard-wrapped lines inside a paragraph.
+- 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.
+- 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.
+- Every relative link must point to the same target as in the source. Translate link text; do not change link targets.
+- 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>`.
+- Preserve emphasis marker types and the semantic spans they cover. Do not add, remove, move, or change bold and italic markers.
+
+### Faithfulness
+- 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.
+- Preserve actors, objects, conditions, exceptions, negation, modality, causal relationships, and distinctions between concepts.
+- 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.
+- Translate ideas rather than source-language idioms, but never use fluency as a reason to omit or alter meaning.
+
+### Tone and Style
+- The translation must read as if originally written in the target language by a native technical author. If an expression sounds like a word-for-word rendering from the source language, rephrase it.
+- Write in a professional, formal tone appropriate for developer documentation. Never use colloquial or casual expressions.
+- Name an actor when the target language would otherwise obscure an actor that the source states or unambiguously implies. Never invent responsibility merely to avoid a passive construction.
+- Prefer established target-language engineering terms over literal renderings. Replace metaphors with direct descriptions that preserve the source meaning.
+- Use polite imperative forms where the text instructs the reader to do something. In Chinese, address the reader as `你`, not `您`.
+- Keep the author's register: concise stays concise, detailed stays detailed.
+
+### Sentence Structure
+- Break long sentences where the target language needs a pause. Avoid run-on sentences.
+- Use active voice when it improves clarity without changing or inventing the actor. Retain passive voice when the actor is unknown, irrelevant, or intentionally omitted.
+- Restructure source-language syntax into clear target-language syntax. Preserve the logical scope of conditions, concessions, negation, coordination, and modifiers.
+- Split or combine clauses when needed for readability, provided every source relationship remains explicit.
+- Translate meaning, not words. Do not invent words or expressions that a native technical author would not use.
+
+### Word Choice
+- Prefer precise, formal vocabulary over casual or colloquial alternatives.
+- When multiple synonyms exist, choose the one most commonly used in professional technical documentation of the target language.
+- Translate ordinary prose when an established target-language expression is clear. Preserve proper nouns, canonical product names, code identifiers, APIs, paths, package names, and terms that the terminology table requires to remain in the source language.
+- Use context to resolve polysemous words. A familiar word does not have one fixed rendering in every technical domain.
+- Avoid slang, internal jargon, or overly literal translations that would not be recognized by the general developer audience.
+- Do not use the same word to translate distinct source-language concepts when their distinction matters.
+- Avoid repeating the same ordinary verb in close proximity when a natural equivalent preserves the exact meaning. Never vary a terminology-table form, defined concept, or contract verb merely for stylistic variety.
+
+#### When translating into Chinese
+- When a number modifies a noun, include a natural Chinese classifier or measure word when Chinese grammar requires one. For example: "three-role capability seam" → "包含三种角色的能力 seam", not "三角色 seam". Do not add classifiers to code, identifiers, versions, units, or fixed names.
+
+### Punctuation
+
+#### When translating into Chinese
+- Use full-width Chinese punctuation in Chinese prose: `，。：；？！（）「」`. Keep half-width punctuation inside code spans, numbers, and complete verbatim English text.
+- Prefer colons, periods, commas, or parentheses over em dashes when they make the sentence clearer or more natural. Keep an em dash when it is the clearest natural punctuation.
+- Use enumeration commas (、) between parallel Chinese items, not regular commas.
+- Keep list-item endings consistent with their grammar. Complete sentences may end with periods or other grammatically required punctuation; do not end list items with commas.
+- Put one half-width space between Chinese text and Latin words or numerals. Do not add a space next to full-width punctuation, and do not leave a meaningless half-width space between two Chinese characters.
+- Markdown emphasis markers do not create a word boundary. Determine spacing from the rendered adjacent characters: Chinese next to Chinese takes no space, while Chinese next to a Latin word or numeral takes one half-width space.
+- Use half-width digits and Latin letters, never full-width forms.
+- For RFC 2119 keywords (MUST, MUST NOT, SHOULD, MAY), translate to the corresponding Chinese term (必须、禁止、应当、可以), preserve the SOURCE emphasis span exactly, and do not weaken its normative strength: plain source stays plain (必须), italic source stays italic (*必须*), and bold source stays bold (**必须**).
+
+#### When translating into English
+- Use half-width English punctuation and standard English spacing. Preserve full-width punctuation only in verbatim Chinese text.
+- Convert enumeration commas (、) to English commas and Chinese prose quotation marks to English double quotes.
+- Convert Chinese topic-comment sentences and omitted-subject constructions into clear English subjects when the actor is stated or unambiguously implied. Do not invent an actor.
+- Use concise professional developer prose and established English technical terms. Do not transliterate Chinese engineering idioms literally.
+- Use the terminology table's English column exactly and do not carry Chinese first-occurrence glosses into English prose.
+
+## Terminology
+
+A terminology table is provided below. Follow it strictly:
+- Render every listed term exactly as specified.
+- When the target language is Chinese, use the "中文" column. On the document's first prose occurrence, write the "首次出现" value when one is specified; on later occurrences, write only the part before the parenthetical gloss.
+- When the target language is English, use the "English" column without a Chinese gloss; do not copy the "中文" or "首次出现" value into English prose.
+- If a term has already been glossed as part of a compound term, do not gloss it again when it appears alone later.
+- NEVER use translations listed in the "不要译作" column.
+- Code spans and other protected tokens remain verbatim even when their text resembles a listed term.
+- For an unlisted technical term, use an established target-language technical term when its meaning is unambiguous in context. For a Chinese target, use an established Chinese rendering from a major Chinese-language OSS or vendor source; if you cannot reliably determine such a rendering, preserve the source term and record `[Terminology: pending]` in `<review>` with a tentative rendering for human review. For an English target, use the established English technical term; if the source term has no unambiguous established equivalent, preserve it with the shortest English gloss needed to make it intelligible and record `[Terminology: pending]` in `<review>`. A tentative rendering may appear in `<review>` but must not be silently adopted in `<translation>` or `<final>`, and you must not invent or claim a specific external precedent. This rule applies to terminology only; for general prose, freely restructure and paraphrase for natural expression.
+
+{{terminology}}
+
+## Output Format
+
+Return exactly three raw XML sections in the order shown below. Do not wrap the response in a Markdown code fence and do not add analysis or text before, between, or after the sections. The fence below only displays the required format; do not reproduce the fence.
+
+The outer section tags are framing. If Markdown inside any section body contains a line consisting only of `<translation>`, `</translation>`, `<review>`, `</review>`, `<final>`, or `</final>`, prefix that line with `\`. If the original line already has one or more backslashes immediately before the tag, add one more. The parser removes exactly one framing escape; tags mentioned inline need no escaping.
+
+```xml
+<translation>
+(First pass: the complete translation, written as natural target-language technical prose)
+</translation>
+
+<review>
+(Second pass: actual corrections only, one correction per line with a category tag, e.g.)
+- [Tone] "旁挂记录" → "伴随记录"（生造词）
+- [Sentence] 第 3 段补充逗号断句
+- [Punctuation] 两处破折号替换为冒号
+- [Terminology: pending] source term → tentative rendering
+- 无修正
+</review>
+
+<final>
+(Complete final translation after corrections)
+</final>
+```
+
+## Self-Review Instructions
+
+After writing `<translation>`, verify it in two directions. First re-read it in the target language only without comparing it with the source; this makes awkward phrasing easier to notice. Then compare it against the source clause by clause for completeness and exact meaning. Resolve doubts before writing `<review>`; do not include reasoning transcripts, checks that passed, tentative suggestions, retractions, or no-op corrections.
+
+**Structure**
+- Are the heading hierarchy and order, list kind and item count, ordered-list start, table dimensions, and code block content identical to the source?
+- Are ALL comments and info strings inside code blocks left untranslated and byte-identical to the source?
+- Are inline code spans and machine-readable tokens verbatim?
+- Is an existing language switcher correctly flipped, and is no switcher or filename invented when the source lacks one?
+- Are link targets and emphasis spans preserved?
+- Does spacing across emphasis boundaries follow the same Chinese/Latin/numeral rule as ordinary prose?
+- Are wrapper-tag lines inside section bodies escaped with one additional backslash?
+
+**Faithfulness**
+- Clause by clause, is anything added, dropped, weakened, strengthened, reversed, merged, or re-bounded? Are list item counts identical on both sides?
+- Do actors, objects, conditions, exceptions, negation, modality, causal relationships, guarantees, contract directions, result channels, ownership changes, and quantities survive exactly?
+
+**Tone & Style**
+- Does every sentence read as if originally written by a native technical author?
+- Is there any colloquial, casual, overly informal, promotional, or metaphorical phrasing?
+- Are actors explicit where the target language needs them, without inventing responsibility?
+
+**Sentence Structure**
+- Are there run-on sentences that need breaking?
+- Are there stiff passive constructions that can safely become active, or active constructions that invent an actor?
+- Are conditions, concessions, negation, coordination, and modifiers scoped clearly?
+
+**Word Choice**
+- Are there overly literal translations that sound unnatural?
+- Are ordinary prose words left untranslated despite an established target-language expression?
+- Does each polysemous word fit its local context?
+- Is the same target-language word used for distinct source concepts, or is a defined term varied merely to avoid repetition?
+- Is any slang or internal jargon present?
+
+**Terminology**
+- For a Chinese target, are first-occurrence glosses correctly applied to the true first prose occurrence, neither missing nor repeated? For an English target, are Chinese glosses absent?
+- Are any "不要译作" forbidden translations present?
+- Do protected tokens remain untouched even when they resemble terminology entries?
+- For an unlisted term, does a Chinese target use an established Chinese rendering or preserve the source term as pending when no reliable rendering is known, and does an English target use the established English technical term or preserve only an ambiguous source term with the shortest necessary gloss and a pending notice?
+
+**Punctuation** (when target is Chinese)
+- Are punctuation, mixed-script spacing, quotation marks, Latin letters, and digits in their required forms?
+- Are there em dashes that make the sentence less clear and should be replaced, while natural em dashes remain intact?
+- Are list-item endings grammatically consistent, with none ending in commas?
+- Do RFC 2119 keywords preserve the source emphasis span and normative strength exactly?
+
+Record actual corrections in `<review>`, then output the corrected complete document in `<final>`. If no correction or pending terminology notice is needed, write exactly `- 无修正` in `<review>` and copy `<translation>` unchanged into `<final>`. If `<review>` contains only pending terminology notices, copy `<translation>` unchanged into `<final>`.
+
+## Examples
+
+Below are representative examples of common problems and their corrections. Follow the "Good" versions within the rule each example illustrates; examples do not override source context or higher-priority requirements.
+
+### Colloquial verb → Professional verb
+- Source: `The repo pins pnpm@11.7.0 in package.json`
+- Bad: `仓库在 package.json 中钉住 pnpm@11.7.0`
+- Good: `该仓库在 package.json 中固定使用 pnpm@11.7.0`
+
+### Run-on sentence → Natural phrasing with pause
+- Source: `Read docs/architecture.md before changing anything under packages/.`
+- Bad: `改动 packages/ 下的任何东西之前先读 docs/architecture.md。`
+- Good: `在修改 packages/ 目录下的任何内容之前，请先阅读 docs/architecture.md。`
+
+### Stiff passive voice → Active and natural
+- Source: `a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound.`
+- Bad: `门禁绿意味着这对文档曾在当前内容上被确认一致，不意味着这次确认本身是对的。`
+- Good: `门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。`
+
+### Invented word → Natural expression
+- Source: `A sidecar record of both blob hashes makes consistency checkable`
+- Bad: `旁挂记录两侧 blob hash，使一致性可检查`
+- Good: `伴随记录保存两侧 blob hash，使一致性可检查`
+
+### Em-dash → Colon/period
+- Source: `FIXME — an issue that should block a new release. A release should not ship with an open FIXME unless reviewers explicitly agree the change can be merged anyway.`
+- Bad: `FIXME——应当阻塞新版本发布的问题。除非评审者明确同意可以照常合入，发布不应带着未解决的 FIXME 出门。`
+- Good: `FIXME：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 FIXME。`
+
+### Overly literal → Meaningful rendering
+- Source: `awkward phrasing is easier to notice when you read the translation without comparing it with the source`
+- Bad: `不把译文和原文比较时，尴尬的措辞更容易被注意`
+- Good: `不对照原文阅读译文时，更容易察觉别扭的表达`
+
+### Terminology — do not translate what should be kept in English
+- Source: `typed service seams, and explicit extension points`
+- Bad: `类型化的服务 seam（扩展点）与显式扩展点`
+- Good: `类型化的服务 seam 与显式扩展点`
+
+### Slang/jargon → Professional phrasing
+- Source: `The committed agent workflow lives in .agents/skills/dsh-translate-docs`
+- Bad: `进仓的 agent 工作流见 .agents/skills/dsh-translate-docs`
+- Good: `仓库内置的 agent 工作流见 .agents/skills/dsh-translate-docs`
+
+### "For humans" — translate the intent, not the word
+- Source: `For humans, start with the development guide`
+- Bad: `对于人工读者，请先从开发指南开始`（"人工读者"生硬）
+- Good: `面向开发者：请先阅读开发指南`（"开发者"自然，且中文里冒号在此处更自然）
+
+### Code block comments — NEVER translate
+- Source code block contains: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)`
+- Bad: `# 全屏 TUI coding agent（需要 DEEPSEEK_API_KEY）`
+- Good: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)` (keep exactly as-is, byte-for-byte)
+
+### Language switcher — flip direction
+- Source file (English) has: `English | [中文](README.zh.md)`
+- Bad (copying source unchanged): `English | [中文](README.zh.md)`
+- Good (flipped for Chinese file): `[English](README.md) | 中文`
+
+---
+
+Now translate the following document:
+````

package/kb/extra/i18n/translation-rules.md

@@ -0,0 +1,69 @@
+# Translation rules
+
+English | [中文](translation-rules.zh.md)
+
+How 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.
+
+## Faithfulness
+
+- 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.
+- 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.
+- 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.
+
+## Voice
+
+- 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.
+- 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.
+- 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 (系统、门禁、评审人).
+- 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.
+- Split long paragraphs by semantic unit — one idea per paragraph. Paragraph boundaries MAY differ from the source; the structural signature does not count paragraphs.
+- 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.
+
+## Structure preservation
+
+The 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:
+
+- heading hierarchy (same levels, same order — heading TEXT is translated),
+- list shape and numbering,
+- tables (same columns, same row order; header cells translated per terminology),
+- fenced code blocks — **byte-identical, including comments**; the pairing signature compares their info strings and contents, and ` ```ts ` blocks compile under `doc-typecheck`,
+- inline code spans (commands, flags, config keys, file paths, event names, API names, version numbers) — verbatim, never translated or reformatted,
+- 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-specific link is the language switcher. A README rendered outside GitHub MAY use the canonical public repository URL to its exact counterpart as documented in [README.md](README.md). Link TEXT is translated; the target is not.
+
+The repo's Markdown conventions apply to `.zh.md` files unchanged: one physical line per paragraph (`verify-md-wrap`), resolving relative links (`verify-md-links`), exactly one trailing newline.
+
+## Terminology
+
+- [terminology.md](terminology.md) is the source of truth in both directions. Before translating, load it; every listed term MUST follow its row and its "不要译作" prohibitions. A Chinese target uses the "中文" column and its "首次出现" annotation; an English target uses the "English" column without adding a Chinese gloss.
+- For a Chinese target, an unlisted technical term MAY use an established rendering from a major Chinese-language OSS or vendor source (K8s/Vue/MDN Chinese docs, 微软简中风格指南, big-tech project docs), cited in the PR. Without such precedent it MUST stay in English and be listed under 「待定术语」(pending terms) with a suggested rendering.
+- For an English target, use the established English technical term. If the source term has no unambiguous established equivalent, preserve it with a short explanatory gloss and list it under pending terms. Neither direction may invent a rendering inline; a decided term enters [terminology.md](terminology.md) in the same PR or a follow-up.
+
+## Typography
+
+These rules govern the Chinese side; the English side follows the repo's normal Markdown conventions (root `AGENTS.md`). The mixed-script rules below follow the cross-project consensus of the [MDN Simplified Chinese translation guide](https://github.com/mdn/translated-content/blob/main/docs/zh-cn/translation-guide.md), the [Kubernetes zh-cn localization guide](https://kubernetes.io/zh-cn/docs/contribute/localization_zh/), the [Vue.js Chinese translation conventions](https://github.com/vuejs-translations/docs-zh-cn/wiki/%E7%BF%BB%E8%AF%91%E9%A1%BB%E7%9F%A5), and [中文文案排版指北](https://github.com/sparanoid/chinese-copywriting-guidelines), which in turn ground in [W3C clreq](https://www.w3.org/TR/clreq/) and GB/T 15834—2011:
+
+- MUST put one half-width space between Chinese text and Latin words, and between Chinese text and numerals: `每个 plugin 注册 3 个 tool`。No space between a full-width punctuation mark and anything.
+- MUST use full-width (Chinese) punctuation in Chinese prose: `，。：；？！（）「」`. Half-width punctuation stays inside code spans, inside complete English sentences quoted as-is, and in numbers (`3.5`, `1,024`).
+- Chinese prose *SHOULD* prefer colons, periods, commas, or parentheses over em dashes. Keep an em dash only when no other punctuation preserves the sentence naturally.
+- Enumeration commas: a Chinese list of parallel items uses 顿号（、）, not commas.
+- MUST NOT use full-width digits or full-width Latin letters — `１２３` never, `123` always.
+- Proper nouns keep their canonical casing: GitHub, TypeScript, DeepSeek — never `github`/`Github` unless quoting code.
+- Second person is 你, not 您 (matches the Vue and Kubernetes Chinese conventions and this repo's direct voice).
+- Emphasis markers (`**bold**`, `*italic*`) stay on the same spans as the source; Chinese has no italics, so the rendered emphasis may look identical — do not substitute quotation marks or other decoration.
+
+## Quality bar
+
+- A pair is done when a bilingual engineer reading either file alone gets everything a reader of the other gets — same facts, same caveats, same tone — and nothing extra.
+- Run `pnpm run verify-translation-pairing` and the rest of `doc-sync` for records, switchers, heading depths, code blocks, table row and column counts, list kinds, ordered-list starts, list item counts, links, and repository Markdown rules. Human review owns list and table order, noncanonical list numbering, inline code, emphasis, meaning, terminology, and tone.
+
+## References
+
+Authorities cited by these rules, for humans and agents who want the underlying reasoning:
+
+- [中文文案排版指北](https://github.com/sparanoid/chinese-copywriting-guidelines) — the de-facto community standard for mixed CJK/Latin spacing and punctuation.
+- [MDN zh-CN translation guide](https://github.com/mdn/translated-content/blob/main/docs/zh-cn/translation-guide.md) — an in-repo translation-rules file of the same shape as this one; spacing, punctuation, and glossary practice.
+- [Kubernetes zh-cn localization guide](https://kubernetes.io/zh-cn/docs/contribute/localization_zh/) — terminology-first-occurrence and punctuation practice from the largest zh localization team.
+- [Vue.js docs-zh-cn 翻译须知](https://github.com/vuejs-translations/docs-zh-cn/wiki/%E7%BF%BB%E8%AF%91%E9%A1%BB%E7%9F%A5) — per-term translate/keep decisions and tone.
+- [zh-style-guide](https://zh-style-guide.readthedocs.io) — a community Chinese technical-writing style guide whose rule-level taxonomy (and RFC 2119 keyword levels) this file borrows; aggregates GB/T 15834/15835, clreq, and vendor guides.
+- [W3C clreq](https://www.w3.org/TR/clreq/) and the [Microsoft Simplified Chinese style guide](https://learn.microsoft.com/en-us/globalization/reference/microsoft-style-guides) — the formal typographic and vendor-localization baselines.
+- GB/T 19682-2005《翻译服务译文质量要求》 — the national standard whose three base requirements (忠实原文、术语统一、行文通顺) this file's Faithfulness and Terminology sections operationalize.