docs(i18n): address ds-review-bot round-2 — switcher placeholders, regex anchor, contract completeness

新增 {{source_filename}}/{{source_filename_zh}} 占位符:切换行指令
可执行化,新配对(源文件尚无切换行)也必须生成(critical)。加粗
后空格规则限定于拉丁字母/数字,不再与全角标点规则冲突。日期匹配
锚定 basename 开头,release-notes-2026-* 类文件不再误判。金标
development.zh 补回 RFC 指引句与 agent 首现括注、pre-push 描述改
为 check:pre-push 调度器实况。术语表补回单文件可执行 RFC 配对在用
的 5 行(VFS/deploy root/peer dependency/serving surface/wheel)。
双语 README 的门禁清单补第 4 条(日期分界强制配对)。
This commit is contained in:
Ziya
2026-07-13 20:37:21 -07:00
parent 7756ed0869
commit 1d288f1bca
7 changed files with 16 additions and 8 deletions

View File

@@ -3,4 +3,4 @@
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write
development.md: ea5f2e5d08acbaf1dfce4661530218dbf1a051b9
development.zh.md: d7263d63ce2d3b851d38e633641c0324c9fb0460
development.zh.md: 9c0cc23373b0f4feba8538fcbd25b38a483e0ba0

View File

@@ -2,14 +2,14 @@
[English](development.md) | 中文
本指南覆盖参与 DeepSeek Harness 开发所需的本地环境搭建,并帮助你了解本地钩子、日常检查与 CI 门禁
本指南覆盖参与 DeepSeek Harness 开发所需的本地环境搭建、日常工作流与 CI 流程;设计动机与技术权衡请查阅相应 RFC
## 前置条件
- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26见 [Node 引擎下限 RFC](rfc/implemented/process/2026-07-06-node-engine-floor.md)。
- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`;如果 `pnpm --version` 无法通过 Corepack 解析,请先运行 `corepack enable`
- Git。
- 可选:一个 DeepSeek API key用于 REPL/ACP agent 演示和真实 API 的 e2e 测试。
- 可选:一个 DeepSeek API key用于 REPL/ACP agent(智能体)演示和真实 API 的 e2e 测试。
## 首次搭建
@@ -59,7 +59,7 @@ DEEPSEEK_BASE_URL=https://... # optional
lefthook 在 `lefthook.yml` 中配置,作为评审前的本地早期检查点:
- `pre-commit` 运行对暂存文件的 ESLint 修复、`pnpm run typecheck` 和 vendor manifest 守卫;
- `pre-push` 运行 `pnpm run test``pnpm run test:snapshot``pnpm run hygiene``pnpm run doc-sync` `pnpm run verify-module-graph`
- `pre-push` 运行 `pnpm run check:pre-push`其调度器并发运行单元测试、快照测试、构建、module-graph 新鲜度,以及 `pnpm run hygiene``pnpm run doc-sync` 的各成员门禁
vendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`

View File

@@ -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
README.md: 30b9e53383ef591898505375662ec94d732de304
README.md: d600773af2be156f52746c5bbd1853ff2ab46c14
README.zh.md: eac836e7c310945ec345db9974be9f1deaae4c60

View File

@@ -26,6 +26,7 @@ This repo's documentation is read by people and agents both inside and outside t
1. Every file listed as `required` in [scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) has a complete pair.
2. Every pair that exists at all — required or not — is complete and consistent: all three files present, each side's current blob hash equals the recorded one (editing either side without re-confirming the pair goes red), both sides carry the language switcher, and the structural signatures match in order — heading depths, verbatim code blocks (info string and content), table column counts, list kinds, and every link target apart from the switcher.
3. Files listed as `excluded` have no `.zh.md` and no `.i18n.yaml` at all.
4. Every date-named document (`yyyy-mm-dd-*.md`) dated on or after the manifest's `requiredSince` cutoff has a complete pair — new documents merge bilingual from birth.
`pnpm run verify-translation-pairing --list` prints the current pairing state of every document in scope — missing, out-of-sync, or ok — and is the work list for translation batches. It never fails; it reports.

View File

@@ -63,6 +63,7 @@
| thinking | thinking | | | API 字段保留英文;描述模型模式时译为`思考` |
| transcript | transcript | transcript文本记录 | | 指会话渲染给用户或编辑器的完整文本,区别于事件日志 |
| waterfall | waterfall | waterfall瀑布式事件 | | |
| wheel | wheel 包 | | | Python 打包格式 |
| worktree | worktree | | | git 工作区概念 |
## 双语类(中英文文本各自使用中英文)
@@ -92,6 +93,7 @@
| contract | 契约 | | | 如:`pairing contract``配对契约` |
| coverage | 覆盖率 | | | |
| crash recovery | 崩溃恢复 | | | |
| deploy root | 部署根目录 | | | |
| durability | 持久性 | | | |
| enforcement frontier | 执行红线 | | 强制边界 | i18n 配对机制用语manifest `required` 清单所划的门禁生效范围与金标样例style-samples ⑦)一致 |
| event | 事件 | | | |
@@ -124,6 +126,7 @@
| orphan | 遗留 | | 孤儿、孤立 | 指英文源已不存在的 `.zh.md`(如「遗留译文」);进程语境按 OS 惯用语译「孤儿进程」 |
| orphan branch | 孤立分支 | | 孤儿分支 | 沿用 git 官方中文翻译 |
| pairing | 配对 | | | |
| peer dependency | 对等依赖 | 对等依赖peer dependency | | |
| permission | 权限 | | | |
| persistence | 持久化 | | | |
| pipeline | 流水线 | | | |
@@ -140,6 +143,7 @@
| runtime | 运行时 | | | |
| sandbox | 沙箱 | | | |
| service | 服务 | | | |
| serving surface | 对外服务接口 | | | |
| session | 会话 | | | |
| session event | 会话事件 | | | |
| sidecar record | 伴随记录 | | 旁挂记录 | 指与文档同目录的伴随记录文件 |
@@ -162,6 +166,7 @@
| tool schema | 工具 schema | | | |
| toolkit | 工具包 | | | |
| turn | 轮次 | | | |
| VFS | VFS | 虚拟文件系统VFS | | |
| typecheck | 类型检查 | | | |
| vocabulary | 词汇 | | | |
| wire format | 协议格式 | 协议格式wire format | | |

View File

@@ -11,6 +11,8 @@
| `{{source_lang}}` | 源语言名(`English` / `Chinese` | 由改动侧文件推断:`.zh.md` 被改则为 `Chinese` |
| `{{target_lang}}` | 目标语言名(`Chinese` / `English` | 与 `{{source_lang}}` 相对 |
| `{{terminology}}` | [terminology.md](terminology.md) 的完整表格Markdown 原文) | 渲染时读取仓库当前版本,不缓存 |
| `{{source_filename}}` | 源文档的 basename`foo.md` | 由流水线从待译文件路径取得 |
| `{{source_filename_zh}}` | 中文侧 basename`foo.zh.md` | 由 `{{source_filename}}` 派生 |
历史模板的 `{{to}}``{{title_prompt}}``{{summary_prompt}}``{{terms_prompt}}``{{imt_style_guide}}` 占位符与 `%%` 分段协议已废弃:本模板按整文档翻译(非分段),输出协议为下方三段 XML。
@@ -40,8 +42,8 @@ You are a senior technical translator specializing in LLM and agent development
- Fenced code blocks must be byte-identical to the source, including ALL comments inside them. Do NOT translate comments inside code blocks. This is a hard rule with no exceptions.
- Inline code spans (commands, flags, paths, API names, version numbers) must be kept verbatim. Never translate or reformat them.
- Every relative link must point to the same target as in the source. Link text is translated; link targets are not.
- Language switcher line: when translating into Chinese, write `[English](source-filename.md) | 中文`. When translating into English, write `English | [中文](source-filename.zh.md)`. Do NOT copy the switcher line from the source file unchanged — you must flip the link direction.
- After a closing bold marker `**`, always insert a space before the next character.
- Language switcher line: the source document's filename is `{{source_filename}}`. When translating into Chinese, write `[English]({{source_filename}}) | 中文` immediately after the H1 heading. When translating into English, write `English | [中文]({{source_filename_zh}})` immediately after the H1. Emit this line even when the source file has no switcher yet (a brand-new pair); when the source does have one, flip the link direction — never copy it unchanged.
- After a closing bold marker `**`, insert a space before the next character when that character is a Latin letter or digit. Never insert a space before full-width (Chinese) punctuation.
### Tone and Style
- The translation must read as if originally written in the target language by a native speaker. If an expression sounds like a word-for-word rendering from the source language, rephrase it.

View File

@@ -257,7 +257,7 @@ for (const req of manifest.required) {
// 2. Date-named documents (RFCs) dated on/after the requiredSince cutoff merge
// bilingual: a new RFC lands with its pair or not at all. Deterministic from
// the filename alone — no git history, so it holds on shallow CI checkouts.
const DATED = /(\d{4}-\d{2}-\d{2})-[^/]*\.md$/
const DATED = /(?:^|\/)(\d{4}-\d{2}-\d{2})-[^/]*\.md$/
for (const source of sources) {
if (isExcluded(source)) continue
const dated = DATED.exec(source)