2026-07-23 22:41:53 +08:00
{
"request" : {
"targetFilename" : "snapshot-note.zh.md" ,
"messages" : [
{
"role" : "system" ,
2026-08-04 17:36:14 +08:00
"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
2026-07-23 22:41:53 +08:00
},
{
" r o l e ": " u s e r ",
2026-08-04 10:07:17 +08:00
" c o n t e n t ": " # D e e p S e e k H a r n e s s \ n \ n E n g l i s h | [ ä ¸ æ – ‡ ] ( R E A D M E . z h . m d ) \ n \ n D e e p S e e k H a r n e s s ( ` d s h ` ) i s a n o p e n - s o u r c e c o d i n g a g e n t b u i l t o n t h e D e e p S e e k H a r n e s s S D K . \ n \ n I t u s e s a n a r c h i t e c t u r e w h e r e * * e v e r y t h i n g i s a p l u g i n * * . \ n \ n # # I n t e r n a l t e s t i n g n o t i c e \ n \ n æ „ Ÿ è ° ¢ æ ‚ ¨ æ „ ¿ æ „ � æ ‹ ¨ å † — è ¯ • ç ” ¨ D e e p S e e k H a r n e s s ã € ‚ å ½ “ å ‰ � ç ‰ ˆ æ œ ¬ ä » � å ¤ „ ä º Ž å † … é ƒ ¨ æ µ ‹ è ¯ • é ˜ ¶ æ ® µ ï ¼ Œ å Š Ÿ è ƒ ½ ä » � å ¾ … å ® Œ å – „ ï ¼ Œ ä ½ “ é ª Œ é š ¾ å … � æ œ ‰ ä º › ç ² — ç ³ ™ ã € ‚ \ n \ n â € œ å ¦ ‚ å ˆ ‡ å ¦ ‚ ç £ ‹ ï ¼ Œ å ¦ ‚ ç � ¢ å ¦ ‚ ç £ ¨ ã € ‚ â € � ä º § å “ � ç š „ æ ˆ � é • ¿ ï ¼ Œ ç ¦ » ä ¸ � å ¼ € ä ¸ € æ ¬ ¡ æ ¬ ¡ ç œ Ÿ å ® ž ç š „ ç ¢ ° æ ’ ž ä ¸ Ž å � ¦ è ¯ š ç š „ å � � é ¦ ˆ ã € ‚ æ ‚ ¨ å œ ¨ ç œ Ÿ å ® ž ä ½ ¿ ç ” ¨ ä ¸ å � ‘ ç Ž ° ç š „ é — ® é ¢ ˜ ï ¼ Œ ä ¹ Ÿ å � ¯ è ƒ ½ ä ¿ ƒ ä ½ ¿ æ ˆ ‘ ä » ¬ é ‡ � æ – ° å ® ¡ è § † ï ¼ Œ ç ” š è ‡ ³ æ Ž ¨ ç ¿ » å · ² æ œ ‰ ç š „ è ® ¾ è ® ¡ ã € ‚ \ n \ n ä ¸ º ä º † å ¸ ® å Š © æ ˆ ‘ ä » ¬ æ › ´ å ‡ † ç ¡ ® å œ ° è ¿ ˜ å Ž Ÿ æ ‚ ¨ ç œ Ÿ å ® ž ä ½ ¿ ç ” ¨ ä ¸ ç š „ é — ® é ¢ ˜ ï ¼ Œ å † … æ µ ‹ ç ‰ ˆ æ œ ¬ é » ˜ è ® ¤ ä ¼ š ä ¸ Š ä ¼ æ ‰ € æ œ ‰ S e s s i o n L o g ï ¼ › å ¦ ‚ é œ € å … ³ é — ï ¼ Œ å � ¯ ä » ¥ è ® ¾ ç ½ ® ç Ž ¯ å ¢ ƒ å � ˜ é ‡ � ` D S H _ T E L E M E T R Y _ D I S A B L E D = 1 ` ã € ‚ å � ¦ å ¤ – ï ¼ Œ å ¦ ‚ æ ž œ æ ‚ ¨ æ œ ‰ ä » » ä ½ • å � � é ¦ ˆ ä ¸ Ž å » º è ® ® ï ¼ Œ è ¯ · å œ ¨ ä ¼ � ä ¸ š å ¾ ® ä ¿ ¡ ç ¾ ¤ ä ¸ ç • ™ è ¨ € å ‘ Š è ¯ ‰ æ ˆ ‘ ä » ¬ ã € ‚ æ ¯ � ä ¸ € æ � ¡ å � � é ¦ ˆ ï ¼ Œ é ƒ ½ ä ¼ š å ¸ ® å Š © æ ˆ ‘ ä » ¬ æ Š Š å ® ƒ æ ‰ “ ç £ ¨ å ¾ — æ › ´ å ¥ ½ ã € ‚ \ n \ n # # I n s t a l l \ n \ n C l o n e t h e r e p o s i t o r y , t h e n r u n t h e i n s t a l l e r : \ n \ n ` ` ` s h \ n g i t c l o n e < r e p o - u r l > \ n c d d e e p s e e k - h a r n e s s \ n s c r i p t s / i n s t a l l . s h \ n ` ` ` \ n \ n T h e i n s t a l l e r r e q u i r e s ` g i t ` a n d N o d e ` ^ 2 2 . 1 9 | | > = 2 4 ` , o f f e r s t o i n s t a l l ` p n p m ` w h e n i t i s m i s s i n g , p r o m p t s f o r a D e e p S e e k A P I k e y , b u i l d s t h e r e q u i r e d r e p o s i t o r y a r t i f a c t s , a n d l a u n c h e s t h e W e b U I . \ n \ n T h e i n s t a l l e r k e e p s e v e r y c h e c k o u t u n d e r ` ~ / . d s h / s o u r c e ` : t h e m a s t e r c l o n e a t ` ~ / . d s h / s o u r c e / m a s t e r ` a n d e a c h i n s t a l l ' s s t a g i n g c h e c k o u t a s a g i t w o r k t r e e ` ~ / . d s h / s o u r c e / s t a g i n g - < t i m e s t a m p > ` . T h e s t a b l e s y m l i n k ` ~ / . d s h / s o u r c e / c u r r e n t ` p o i n t s a t t h e a c t i v e s t a g i n g w o r k t r e e , a n d ` d s h ` i n ` ~ / . l o c a l / b i n ` l i n k s t o ` c u r r e n t / b i n / d s h ` , s o a n u p g r a d e r e p o i n t s o n e s y m l i n k a n d t h e ` d s h ` o n P A T H n e v e r m o v e s . R e - r u n n i n g t h e c o m m a n d a d d s a f r e s h s t a g i n g w o r k t r e e f r o m a n u p d a t e d m a s t e r a n d r e p o i n t s ` c u r r e n t ` a t i t . S e e [ ` s c r i p t s / i n s t a l l . s h ` ] ( s c r i p t s / i n s t a l l . s h ) f o r a l t e r n a t e i n s t a l l l o c a t i o n s a n d o t h e r o p t i o n s . \ n \ n # # U s e D e e p S e e k H a r n e s s \ n \ n # # # W e b U I \ n \ n F o r t h e r e c o m m e n d e d l o c a l i n t e r f a c e , c h o o s e W e b U I w h e n t h e i n s t a l l e r f i n i s h e s . T o s t a r t i t l a t e r , o r a f t e r u p d a t i n g t h e a c t i v e c h e c k o u t , b u i l d t h e r e p o s i t o r y a n d r u n : \ n \ n ` ` ` s h \ n ( c d ~ / . d s h / s o u r c e / c u r r e n t & & p n p m r u n b u i l d ) \ n d s h w e b \ n ` ` ` \ n \ n T h e p a t h a b o v e i s t h e i n s t a l l e r ' s d e f a u l t . I f y o u s e t ` D S H _ S O U R C E ` o r ` D S H _ C U R R E N T ` , o r r e u s e d a n e x i s t i n g c h e c k o u t , r e p l a c e ` ~ / . d s h / s o u r c e / c u r r e n t ` w i t h t h a t c h e c k o u t p a t h ; s e e [ ` s c r i p t s / i n s t a l l . s h ` ] ( s c r i p t s / i n s t a l l . s h ) f o r d e t a i l s . T h e W e b U I i s s e r v e d a t ` h t t p : //127.0.0.1:3080` by default.\n\n### Configured runtime\n\nRaw `dsh` requires a patch-list configuration applied over the shipped base:\n\n```sh\ndsh --config ./app.cordis.yml\n```\n\nThe [CLI contract](apps/cli/README.md#raw-config) describes the base, overlay semantics, and config dump commands.\n\n### Headless\n\nRun one task, print the final answer, and exit:\n\n```sh\ndsh -p \"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.** Anyt
2026-07-23 22:41:53 +08:00
} ,
{
"role" : "assistant" ,
2026-08-04 10:07:17 +08:00
"content" : "# DeepSeek Harness\n\n[English](README.md) | ä¸æ–‡\n\nDeepSeek Harness（`dsh`）是一款基于 DeepSeek Harness SDK 构建的开æº� coding agent（编程智能体）。\n\n它采用了**一切皆æ� ’件**的架构。\n\n## 内测声明\n\n感谢您愿æ„� 拨冗试用 DeepSeek Harness。当å‰� 版本ä»� 处于内部测试阶段，功能ä»� 待完善，体验难å…� 有些粗糙。\n\n“如切如磋，如ç� ¢å¦‚磨。â€� 产å“� çš„æˆ� 长，离ä¸� 开一次次真实的碰撞与å� ¦è¯šçš„å� � 馈。您在真实使用ä¸å� ‘现的问题，也å� ¯èƒ½ä¿ƒä½¿æˆ‘们é‡� 新审视，甚至推翻已有的设计。\n\n为了帮助我们更准确地还原您真实使用ä¸çš„é—®é¢˜ï¼Œå†…æµ‹ç‰ˆæœ¬é»˜è®¤ä¼šä¸Šä¼ æ‰€æœ‰ Session Log；如需关é—，å� ¯ä»¥è®¾ç½®çŽ¯å¢ƒå� ˜é‡� `DSH_TELEMETRY_DISABLED=1`。å� ¦å¤–，如果您有任何å� � 馈与建议，请在ä¼� 业微信群ä¸ç•™è¨€å‘Šè¯‰æˆ‘们。æ¯� 一æ� ¡å� � 馈，都会帮助我们把它打磨得更好。\n\n## 安装\n\n克隆仓库，然å� Žè¿� 行安装器：\n\n```sh\ngit clone <repo-url>\ncd deepseek-harness\nscripts/install.sh\n```\n\n安装器è¦� 求系统已安装 `git` å’Œ Node `^22.19 || >=24`，缺少 `pnpm` æ—¶å� ¯ä»£ä¸ºå®‰è£…，并会æ� � 示输入 DeepSeek API 密钥，然å� Žæž„建所需的仓库产物并å� ¯åŠ¨ Web UI。\n\n安装器会把所有检出都放在 `~/.dsh/source` 下：master 克隆ä½� 于 `~/.dsh/source/master`，æ¯� 次安装的 staging 检出是一个 git worktree `~/.dsh/source/staging-<时间戳>`。稳定符å� ·é“¾æŽ¥ `~/.dsh/source/current` 指å� ‘当å‰� 生效的 staging worktree，`~/.local/bin` ä¸çš„ `dsh` 链接到 `current/bin/dsh`ï¼Œå› æ¤å� ‡çº§å� ªéœ€é‡� 指一个符å� ·é“¾æŽ¥ï¼ŒPATH 上的 `dsh` 从ä¸� 移动。å†� 次è¿� 行该命令会基于更新å� Žçš„ master 新增一个 staging worktree，并把 `current` é‡� 指到它。其他安装ä½� 置和选项è§� [`scripts/install.sh`](scripts/install.sh)。\n\n## 使用 DeepSeek Harness\n\n### Web UI\n\n推è� � 在本地使用 Web UI；安装结æ� Ÿæ—¶ï¼Œé€‰æ‹© Web UI å� ³å� ¯ã€‚以å� Žéœ€è¦� å� ¯åŠ¨æ—¶ï¼Œæˆ–更新当å‰� 生效的检出å� Žï¼Œè¯·æž„建仓库并è¿� 行：\n\n```sh\n(cd ~/.dsh/source/current && pnpm run build)\ndsh web\n```\n\n上述路径是安装器的默认ä½� ç½®ã€‚å¦‚æžœä½ è®¾ç½®è¿‡ `DSH_SOURCE` 或 `DSH_CURRENT`，或者å¤� 用了已有检出，请把 `~/.dsh/source/current` æ� ¢æˆ� 该检出路径；详情è§� [`scripts/install.sh`](scripts/install.sh)。Web UI 默认通过 `http://127.0.0.1:3080` æ� � ä¾›æœ� 务。\n\n### 自定义è¿� 行时\n\n原始 `dsh` è¦� æ±‚ä¼ å…¥ä¸€ä»½ patch 列表é…� 置，并将其å� åŠ åœ¨éš� 附 base 之上：\n\n```sh\ndsh --config ./app.cordis.yml\n```\n\nbaseã€� overlay è¯ä¹‰ä¸Žé…� 置输出命令详è§� [CLI（命令行界é� ¢ï¼‰å¥‘约](apps/cli/README.md#raw-config)。\n\n### Headless\n\nè¿� 行一项任务，打å� °æœ€ç»ˆç”案å� Žé€€å‡ºï¼š\n\n```sh\ndsh -p \"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- **è¿� è¡Œå� ¯é‡� 建。** 凡是模型å� ¯è§� 的内容ï
2026-07-23 22:41:53 +08:00
},
{
" r o l e ": " u s e r ",
2026-08-04 10:07:17 +08:00
" c o n t e n t ": " # D e v e l o p m e n t g u i d e \ n \ n E n g l i s h | [ ä ¸ æ – ‡ ] ( d e v e l o p m e n t . z h . m d ) \ n \ n T h i s o n b o a r d i n g g u i d e h e l p s p r o j e c t c o n t r i b u t o r s g e t s t a r t e d w i t h t h e l o c a l e n v i r o n m e n t , d a i l y w o r k f l o w , a n d C I f l o w ; s e e t h e A g e n t N o t e s f o r d e s i g n r a t i o n a l e a n d t e c h n i c a l t r a d e - o f f s . \ n \ n # # P r e r e q u i s i t e s \ n \ n - N o d e . j s s u p p o r t s 2 2 . 1 9 + a n d 2 4 + . C I c o v e r s 2 2 . 1 9 , 2 4 , a n d 2 6 ; s e e t h e [ N o d e e n g i n e f l o o r A g e n t N o t e ] ( . . / . a g e n t s / n o t e s / i m p l e m e n t e d / p r o c e s s / 2 0 2 6 - 0 7 - 0 6 - n o d e - e n g i n e - f l o o r . m d ) . \ n - C o r e p a c k - e n a b l e d p n p m . T h e r e p o p i n s ` p n p m @ 1 1 . 7 . 0 ` i n ` p a c k a g e . j s o n ` ; r u n ` c o r e p a c k e n a b l e ` i f ` p n p m - - v e r s i o n ` d o e s n o t r e s o l v e t h r o u g h C o r e p a c k . \ n - G i t 2 . 2 6 o r n e w e r ; h o o k s e t u p e n a b l e s G i t ' s w o r k t r e e - s p e c i f i c c o n f i g u r a t i o n e x t e n s i o n . \ n - O p t i o n a l : a D e e p S e e k A P I k e y f o r t h e W e b , h e a d l e s s , a n d A C P a u t o m a t i o n d e m o s a n d r e a l - A P I e 2 e t e s t s . \ n \ n # # F i r s t - t i m e s e t u p \ n \ n I n s t a l l d e p e n d e n c i e s f r o m t h e r e p o r o o t : \ n \ n ` ` ` s h \ n p n p m i n s t a l l \ n ` ` ` \ n \ n T h e i n s t a l l a l s o r u n s t h e r o o t ` p o s t i n s t a l l ` s c r i p t , w h i c h i n s t a l l s l e f t h o o k f r o m t h e r e p o d e v d e p e n d e n c y t h r o u g h ` s c r i p t s / i n s t a l l - l e f t h o o k . m j s ` . W i t h ` C I = t r u e ` o r ` G I T H U B _ A C T I O N S = t r u e ` , t h e w r a p p e r r e t u r n s b e f o r e G i t d i s c o v e r y b e c a u s e a u t o m a t e d j o b s d o n o t c o n s u m e c o n t r i b u t o r h o o k s . O t h e r w i s e , i t r e q u i r e s G i t 2 . 2 6 o r n e w e r a n d g i v e s t h e c u r r e n t w o r k t r e e a n e x p l i c i t h o o k d i r e c t o r y u n d e r i t s o w n G i t d i r e c t o r y ; l i n k e d w o r k t r e e s t h e r e f o r e u s e t h e i r o w n l e f t h o o k b i n a r y a n d c o n f i g u r a t i o n i n s t e a d o f r e w r i t i n g c o m m o n h o o k s . T h e f i r s t i n s t a l l e n a b l e s G i t ' s w o r k t r e e - s p e c i f i c c o n f i g u r a t i o n e x t e n s i o n a n d r e p o s i t o r y f o r m a t 1 ; s e e t h e [ w o r k t r e e - l o c a l h o o k s A g e n t N o t e ] ( . . / . a g e n t s / n o t e s / i m p l e m e n t e d / p r o c e s s / 2 0 2 6 - 0 7 - 2 7 - w o r k t r e e - l o c a l - l e f t h o o k . m d ) . \ n \ n I f h o o k s a r e m i s s i n g b e c a u s e d e p e n d e n c i e s w e r e r e s t o r e d f r o m c a c h e o r ` p o s t i n s t a l l ` w a s s k i p p e d , i n s t a l l t h e m m a n u a l l y : \ n \ n ` ` ` s h \ n n o d e s c r i p t s / i n s t a l l - l e f t h o o k . m j s \ n ` ` ` \ n \ n T h e w r a p p e r r e f u s e s u s e r - o w n e d ` c o r e . h o o k s P a t h ` v a l u e s . A n i n h e r i t e d s y s t e m , g l o b a l , o r c o m m o n - r e p o s i t o r y p a t h r e q u i r e s ` D S H _ L E F T H O O K _ A L L O W _ H O O K S _ P A T H _ O V E R R I D E = 1 ` . W h e n G i t s e e d s a n e w w o r k t r e e w i t h a n o t h e r r e g i s t e r e d w o r k t r e e ' s m a r k e r - b a c k e d h o o k p a t h , t h e w r a p p e r r e p l a c e s t h a t c o p i e d v a l u e w i t h t h e n e w w o r k t r e e ' s o w n p a t h ; c o m m a n d - s c o p e d a n d o t h e r w o r k t r e e - s c o p e d p a t h s m u s t b e i n t e g r a t e d o r r e m o v e d e x p l i c i t l y . \ n \ n B e f o r e e n a b l i n g w o r k t r e e c o n f i g , m i g r a t e d i r e c t ` e x t e n s i o n s . * ` i n a f o r m a t - 0 c o m m o n c o n f i g , d i r e c t ` c o r e . w o r k t r e e ` o r ` c o r e . b a r e = t r u e ` , a n d a n y n o n - e m p t y d o r m a n t ` c o n f i g . w o r k t r e e ` . T h e c o m m o n c o n f i g a n d e v e r y w o r k t r e e c o n f i g m u s t b e r e g u l a r f i l e s , w h i l e t h e o w n e d h o o k d i r e c t o r y m a y c o n t a i n o n l y u n a l i a s e d r e g u l a r f i l e s . \ n \ n A f t e r m o v i n g a c h e c k o u t , r e r u n t h e w r a p p e r t o r e l o c a t e i t s o w n e d p a t h a n d r e g e n e r a t e h o o k s . F o r a s t a l e o r i n v a l i d i n s t a l l e r l o c k , f i r s t c o n f i r m n o i n s t a l l e r i s r u n n i n g , t h e n r e m o v e t h e r e p o r t e d l o c k a n d r e t r y . I f i n s t a l l a t i o n a n d h o o k - p a t h r o l l b a c k b o t h f a i l , i n s p e c t t h e r e p o r t e d w o r k t r e e c o n f i g b e f o r e r e t r y i n g . T h e [ w o r k t r e e - l o c a l h o o k s A g e n t N o t e ] ( . . / . a g e n t s / n o t e s / i m p l e m e n t e d / p r o c e s s / 2 0 2 6 - 0 7 - 2 7 - w o r k t r e e - l o c a l - l e f t h o o k . m d ) o w n s t h e f u l l s a f e t y c o n t r a c t . \ n \ n R u n t y p e c h e c k o n c e a f t e r a f r e s h c l o n e : \ n \ n ` ` ` s h \ n p n p m r u n t y p e c h e c k \ n ` ` ` \ n \ n T h a t f i r s t t y p e c h e c k r u n s t h e w h o l e - r e p o ` t s c - b ` g r a p h : i t e m i t s e v e r y p a c k a g e / v e n d o r ` l i b / t y p e s ` a n d c h e c k s e x a m p l e s , t e s t s , a n d s c r i p t s t h r o u g h t h e t w o n o - e m i t a g g r e g a t e s d e s c r i b e d b e l o w . \ n \ n # # T y p e S c r i p t p r o j e c t l a y o u t \ n \ n T h e r e p o s i t o r y ' s T y p e S c r i p t c o n f i g u r a t i o n h a s e x a c t l y t h r e e r o l e s ; e v e r y t s c o n f i g f i l e p l a y s o n e o f t h e m . \ n \ n | F i l e | R o l e | F o r m s a p r o g r a m ? | \ n | - - - | - - - | - - - | \ n | ` t s c o n f i g . j s o n ` | S o l u t i o n r o o t : ` e x t e n d s ` b a s e , ` f i l e s : [ ] ` , r e f e r e n c e s t o t h e t w o a g g r e g a t e s . T h e w h o l e - r e p o ` t s c - b t s c o n f i g . j s o n ` g r a p h , t h e t s s e r v e r d i s c o v e r y e n t r y , a n d â € ” t h r o u g h t h e i n h e r i t e d ` p a t h s ` â € ” t h e r e s o l u t i o n c o n f i g f o r t s x r u n n i n g ` e x a m p l e s / ` a n d ` s c r i p t s / ` ( t h e i r n e a r e s t t s c o n f i g i s t h i s f i l e ) . | N o | \ n | ` t s c o n f i g . h o s t . j s o n ` | H o s t a g g r e g a t e : h o s t - s i d e p a c k a g e s ( v i a r e f e r e n c e s ) , e x a m p l e s , t e s t s , s c r i p t s , w e b s i t e . E x c l u d e s ` p a c k a g e s / c l i e n t ` . | Y e s | \ n | ` t s c o n f i g . c l i e n t . j s o n ` | C l i e n t a g g r e g a t e : ` p a c k a g e s / c l i e n t / * ` p a c k a g e s a n d t h e i r t e s t s , ` a p p s / w e b ` . | Y e s | \ n | ` t s c o n f i g . b
2026-07-23 22:41:53 +08:00
} ,
{
"role" : "assistant" ,
2026-08-04 10:07:17 +08:00
"content" : "# å¼€å� ‘指å� —\n\n[English](development.md) | ä¸æ–‡\n\n本指å� —覆盖å� ‚与 DeepSeek Harness å¼€å� ‘所需的本地环境æ� 建ã€� 日常工作æµ� 与 CI æµ� 程；设计动机与技术æ� ƒè¡¡è¯·æŸ¥é˜…相应 Agent Note。\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安装过程å� Œæ—¶ä¼šè¿� è¡Œæ ¹ç›®å½•çš„ `postinstall` 脚本，该脚本通过 `scripts/install-lefthook.mjs` 从仓库 dev ä¾� 赖安装 lefthook。当 `CI=true` 或 `GITHUB_ACTIONS=true` 时，该脚本会在探测 Git å‰� è¿”å›žï¼Œå› ä¸ºè‡ªåŠ¨åŒ–ä»»åŠ¡ä¸� 会使用贡献者钩å� 。å� ¦åˆ™ï¼ŒåŒ…装脚本è¦� 求使用 Git 2.26 或更高版本，并会为当å‰� worktree 在其自身的 Git 目录下设置显å¼� é’©å� ç›®å½•ï¼›å› æ¤ï¼Œå…³è� ” worktree 会使用å� „自的 lefthook 二进制文件和é…� 置，而ä¸� 会改写共用钩å� 。首次安装会å� ¯ç”¨ Git çš„ worktree 专属é…� ç½®æ‰©å±•å’Œä»“åº“æ ¼å¼� 1ï¼›è§� [worktree 本地钩å� Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md)。\n\n如果ä¾� 赖是从缓å˜æ� ¢å¤� 或 `postinstall` 被跳过而导致缺少钩å� ，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n包装层会拒ç»� 用户自有的 `core.hooksPath` 值。继承自系统ã€� 全局或共用仓库é…� 置的路径必须设置 `DSH_LEFTHOOK_ALLOW_HOOKS_PATH_OVERRIDE=1`。当 Git 使用å� ¦ä¸€ä¸ªå·²æ³¨å†Œ worktree ä¸ç”±æ‰€æœ‰æ� ƒæ ‡è®°ä½� è¯� çš„é’©å� 路径åˆ� 始化新 worktree 时，包装层会将这个å¤� 制值替æ� ¢ä¸ºæ–° worktree 自有的路径；命令作用域和其他 worktree 作用域的路径必须显å¼� 集æˆ� 或移除。\n\nå� ¯ç”¨ worktree é…� 置之å‰� ，请è¿� ç§»æ ¼å¼� 0 共用é…� ç½®ä¸ç›´æŽ¥è®¾ç½®çš„ `extensions.*`，并è¿� 移直接设置的 `core.worktree` 或 `core.bare=true`，以å� Šä»»ä½•é� žç©ºä¸”尚未生效的 `config.worktree`。共用é…� 置和æ¯� 个 worktree é…� 置都必须是常规文件，而自有钩å� 目录å� ªèƒ½åŒ…å� «ä¸� 带别å� � 的常规文件。\n\n检出目录移动å� Žï¼Œè¯·é‡� æ–°è¿� 行包装层，使其é‡� 新定ä½� 自有路径并é‡� 新生æˆ� é’©å� ã€‚å¯¹äºŽé™ˆæ—§æˆ–æ— æ•ˆçš„å®‰è£…ç¨‹åº� é”� ，请先确认没有安装程åº� æ£åœ¨è¿� 行，å†� 移除报告的é”� 并é‡� 试。若安装和钩å� 路径回滚都失败，请在é‡� 试å‰� 检查报告的 worktree é…� 置。完整安全契约由 [worktree 本地钩å� Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 统一定义。\n\n新克隆å� Žè¯·å…ˆè¿� 行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n首次类型检查会执行全仓 `tsc -b tsconfig.json` 图：å� ‘å°„æ¯� 个 package/vendor çš„ `lib/types`，并通过下述两个 no-emit è� šå� ˆæ£€æŸ¥ç¤ºä¾‹ã€� 测试和脚本。\n\n## TypeScript 项目布局\n\n仓库的 TypeScript é…� ç½®å� ªæœ‰ä¸‰ç§� 角色；æ¯� 个 tsconfig 文件æ� °å¥½æ‰®æ¼”å…¶ä¸ä¸€ç§� 。\n\n| 文件 | 角色 | 是å� ¦æž„æˆ� program？ |\n|---|---|---|\n| `tsconfig.json` | solution æ ¹ï¼š`extends` baseã€� `files: []`ã€� 引用两个è� šå� ˆã€‚全仓 `tsc -b tsconfig.json` 图ã€� tsserver å� ‘现入å� £ï¼Œå¹¶ç»� 继承的 `paths` 充当 tsx è¿� è¡Œ `examples/` 与 `scripts/` 时的解æž� é…� 置（它们最近的 tsconfig 就是æ¤æ–‡ä»¶ï¼‰ã€‚ | å� ¦ |\n| `tsconfig.host.json` | host è� šå� ˆï¼šhost 侧å� „包（ç»� references）ã€� 示例ã€� 测试ã€� 脚本ã€� website。排除 `packages/client`。 | 是 |\n| `tsconfig.client.json` | client è� šå� ˆï¼š`packages/client/*` å� „包å� Šå…¶æµ‹è¯•ã€� `apps/web`。 |
2026-07-23 22:41:53 +08:00
},
{
" r o l e ": " u s e r ",
2026-07-28 10:41:48 -07:00
" c o n t e n t ": " # B i l i n g u a l d o c u m e n t a t i o n \ n \ n E n g l i s h | [ ä ¸ æ – ‡ ] ( R E A D M E . z h . m d ) \ n \ n T h i s r e p o ' s d o c u m e n t a t i o n i s r e a d b y p e o p l e a n d a g e n t s b o t h i n s i d e a n d o u t s i d e t h e c o m p a n y , s o e v e r y d o c u m e n t i n s c o p e i s m a i n t a i n e d i n E n g l i s h a n d S i m p l i f i e d C h i n e s e . T h i s p a g e d e f i n e s t h e p a i r i n g c o n t r a c t , e n f o r c e m e n t g a t e , s c o p e , a n d e x c l u s i o n s ; [ t r a n s l a t i o n - r u l e s . m d ] ( t r a n s l a t i o n - r u l e s . m d ) d e f i n e s h o w t o t r a n s l a t e ; [ t e r m i n o l o g y . m d ] ( t e r m i n o l o g y . m d ) i s t h e t e r m i n o l o g y s o u r c e o f t r u t h . T h e c o m m i t t e d a g e n t w o r k f l o w l i v e s i n [ . a g e n t s / s k i l l s / d s h - t r a n s l a t e - d o c s ] ( . . / . . / . a g e n t s / s k i l l s / d s h - t r a n s l a t e - d o c s / S K I L L . m d ) . \ n \ n # # T h e p a i r i n g c o n t r a c t \ n \ n - * * B o t h l a n g u a g e s c a r r y e q u a l a u t h o r i t y . * * A d o c u m e n t m a y b e a u t h o r e d a n d r e v i e w e d i n e i t h e r l a n g u a g e f i r s t â € ” a C h i n e s e - f i r s t A g e n t N o t e i s a s l e g i t i m a t e a s a n E n g l i s h - f i r s t o n e â € ” a n d t h e c o u n t e r p a r t i s t r a n s l a t e d f r o m i t . N e i t h e r f i l e o u t r a n k s t h e o t h e r ; w h a t b i n d s t h e m i s t h a t t h e y m u s t s a y t h e s a m e t h i n g . \ n - * * A p a i r i s t h r e e s i b l i n g f i l e s . * * T h e E n g l i s h ` f o o . m d ` , t h e C h i n e s e ` f o o . z h . m d ` , a n d a c o n s i s t e n c y r e c o r d ` f o o . i 1 8 n . y a m l ` , a l l i n t h e s a m e d i r e c t o r y . N o l o c a l e d i r e c t o r i e s , n o s e p a r a t e t r a n s l a t i o n r e p o , n o i n t e r l e a v e d b i l i n g u a l f i l e s . P a i r s m e r g e w h o l e : a P R n e v e r l a n d s o n e l a n g u a g e w i t h o u t t h e o t h e r t w o f i l e s . \ n - * * T h e c o n s i s t e n c y r e c o r d . * * ` f o o . i 1 8 n . y a m l ` h o l d s t h e f u l l g i t b l o b h a s h o f e a c h s i d e a s o f t h e l a s t t i m e t h e t w o w e r e c o n f i r m e d t o s a y t h e s a m e t h i n g : \ n \ n ` ` ` y a m l \ n f o o . m d : 3 f 7 8 6 8 5 0 e 3 8 7 5 5 0 f d a b 8 3 6 e d 7 e 6 d c 8 8 1 d e 2 3 0 0 1 b \ n f o o . z h . m d : 8 9 e 6 c 9 8 d 9 2 8 8 7 9 1 3 c a d f 0 6 b 2 a d b 9 7 f 2 6 c d e 4 8 4 9 b \ n ` ` ` \ n \ n B l o b h a s h e s , n o t c o m m i t h a s h e s , s o t h e r e c o r d i s c o m p u t a b l e f o r f i l e s e d i t e d i n t h e s a m e P R ( ` g i t h a s h - o b j e c t f o o . m d ` ) a n d c o n s i s t e n c y i s a p u r e c o n t e n t c o m p a r i s o n . ` - - w r i t e ` s t o r e s t h o s e s n a p s h o t s i n t h e l o c a l G i t o b j e c t d a t a b a s e b e f o r e r e c o r d i n g t h e m , i n c l u d i n g u n c o m m i t t e d w o r k i n g - t r e e c o n t e n t s , a n d p i n s e v e r y d i s t i n c t s t o r e d b l o b u n d e r a c o n t e n t - a d d r e s s e d ` r e f s / d s h / t r a n s l a t i o n - p a i r i n g / s n a p s h o t s / ` r e f s o g a r b a g e c o l l e c t i o n c a n n o t i n v a l i d a t e a r e c o r d e d r e c o v e r y p o i n t e r . T h e r e c o r d e d h a s h e s t h e r e f o r e r e c o v e r t h e e x a c t l a s t - c o n f i r m e d t e x t o f e i t h e r s i d e , s o a n o u t - o f - s y n c p a i r i s u p d a t e d b y p a t c h i n g t h e c o u n t e r p a r t m i n i m a l l y a g a i n s t t h e e d i t e d s i d e ' s d i f f â € ” n e v e r b y r e - t r a n s l a t i n g w h o l e f i l e s . ` p n p m r u n g e n - t r a n s l a t i o n - b r i e f < p a i r > ` a s s e m b l e s t h a t u p d a t e ' s w o r k i n g s e t m e c h a n i c a l l y a t t h e n a r r o w e s t s a f e l y a l i g n e d g r a n u l a r i t y â € ” c h a n g e d M a r k d o w n u n i t s , t h e n h e a d i n g s e c t i o n s , t h e n w h o l e d o c u m e n t â € ” w i t h t h e e d i t e d s i d e ' s d i f f s i n c e l a s t c o n f i r m a t i o n , e a c h c h a n g e d s p a n ' s t h r e e - w a y t e x t , t h e t e r m i n o l o g y r o w s t h e c h a n g e t o u c h e s , a n d t h e b i n d i n g u p d a t e r u l e s ; a c h a n g e c o n f i n e d t o t h e p a i r ' s b y t e - i d e n t i c a l c o d e f e n c e s i s c o m p u t e d o u t r i g h t , a n d ` - - a p p l y ` s p l i c e s i t i n t o t h e c o u n t e r p a r t a f t e r s t r u c t u r a l v a l i d a t i o n ( [ b r i e f e d - u p d a t e s A g e n t N o t e ] ( . . / . . / . a g e n t s / n o t e s / i m p l e m e n t e d / p r o c e s s / 2 0 2 6 - 0 7 - 2 6 - b r i e f e d - m i n i m a l - t r a n s l a t i o n - u p d a t e s . m d ) ) . A f t e r b r i n g i n g t h e p a i r b a c k i n l i n e , ` p n p m r u n v e r i f y - t r a n s l a t i o n - p a i r i n g - - w r i t e < p a i r > ` r e - r e c o r d s b o t h h a s h e s ; t h a t y a m l d i f f i s t h e r e v i e w a b l e a c t o f c o n f i r m i n g c o n s i s t e n c y , w h i c h i s w h y ` - - w r i t e ` r e q u i r e s n a m i n g t h e p a i r s y o u c o n f i r m e d ( ` - - w r i t e - - a l l ` i s t h e e x p l i c i t c o r p u s - w i d e f o r m ) . \ n - * * L a n g u a g e s w i t c h e r . * * B o t h f i l e s l i n k t o e a c h o t h e r i m m e d i a t e l y a f t e r t h e i r H 1 h e a d i n g : t h e E n g l i s h f i l e c a r r i e s ` E n g l i s h | [ ä ¸ æ – ‡ ] ( f o o . z h . m d ) ` a n d t h e C h i n e s e f i l e c a r r i e s ` [ E n g l i s h ] ( f o o . m d ) | ä ¸ æ – ‡ ` . \ n - * * S t r u c t u r e m i r r o r s t h e c o u n t e r p a r t . * * H e a d i n g d e p t h s a n d o r d e r , l i s t k i n d s , o r d e r e d - l i s t s t a r t s , l i s t i t e m c o u n t s , t a b l e r o w a n d c o l u m n c o u n t s , l i n k t a r g e t s , a n d v e r b a t i m c o d e b l o c k s m a t c h o n e t o o n e a c r o s s t h e p a i r â € ” s e e [ t r a n s l a t i o n - r u l e s . m d ] ( t r a n s l a t i o n - r u l e s . m d ) f o r t h e f u l l p r e s e r v a t i o n r u l e s . E x i s t i n g M a r k d o w n g a t e s a p p l y t o ` . z h . m d ` f i l e s u n c h a n g e d ( ` v e r i f y - m d - w r a p ` , ` v e r i f y - m d - l i n k s ` ) . \ n \ n # # T h e g a t e : v e r i f y - t r a n s l a t i o n - p a i r i n g \ n \ n ` p n p m r u n v e r i f y - t r a n s l a t i o n - p a i r i n g ` ( p a r t o f ` d o c - s y n c ` , w h i c h c o n t r i b u t o r s r u n l o c a l l y f o r d o c u m e n t a t i o n c h a n g e s a n d C I r u n s e x h a u s t i v e l y ) e n f o r c e s t h e c o n t r a c t m e c h a n i c a l l y : \ n \ n 1 . E v e r y d o c u m e n t i n s c o p e h a s a c o m p l e t e p a i r . R E A D M E d i s c o v e r y
2026-07-23 22:41:53 +08:00
} ,
{
"role" : "assistant" ,
2026-07-28 10:41:48 -07:00
"content" : "# å� Œè¯æ–‡æ¡£\n\n[English](README.md) | ä¸æ–‡\n\n本仓库的文档会被公å� ¸å†…外的人和 agentï¼ˆæ™ºèƒ½ä½“ï¼‰é˜…è¯»ï¼Œå› æ¤èŒƒå›´å†…çš„æ¯� 篇文档都以英文和简体ä¸æ–‡ç»´æŠ¤ã€‚本页定义é…� 对契约ã€� 强制门ç¦� ã€� 范围与排除规则；[translation-rules.md](translation-rules.md) 定义如何翻译；[terminology.md](terminology.md) 是术è¯çœŸæº� 。仓库内置的 agent 工作æµ� è§� [.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>` 会以能安全对é½� 的最窄粒度——先是有改动的 Markdown å� •å…ƒï¼Œå†� æ˜¯æ ‡é¢˜å°� 节，最å� Žæ˜¯æ•´ç¯‡æ–‡æ¡£â€”—机械地汇集这次更新的工作集：被改一侧自上次确认以æ� ¥çš„ diffã€� æ¯� 个改动å� —的三方文本ã€� 改动触å� Šçš„术è¯è¡¨è¡Œï¼Œä»¥å� Šæœ‰çº¦æ� ŸåŠ›çš„更新规则；仅è� ½åœ¨é…� 对ä¸é€� å—节一致的围æ � 代ç � å� —内的改动å� ¯ä»¥ç›´æŽ¥ç®—出，`--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- **è¯è¨€åˆ‡æ� ¢è¡Œã€‚** 两个文件在å� „自 H1 æ ‡é¢˜ä¹‹å� Žç«‹å� ³äº’链：英文文件带 `English | [ä¸æ–‡](foo.zh.md)`，ä¸æ–‡æ–‡ä»¶å¸¦ `[English](foo.md) | ä¸æ–‡`。\n- **结构与å� ¦ä¸€ä¾§ä¸€ä¸€å¯¹åº”。** æ ‡é¢˜æ·±åº¦ä¸Žé¡ºåº� ã€� 列表类型ã€� 有åº� 列表起始编å� ·ã€� 列表项数é‡� ã€� è¡¨æ ¼è¡Œåˆ—æ•°ã€� é“¾æŽ¥ç›®æ ‡ä¸Žé€� å—节一致的代ç � å� —在é…� 对两侧一一对应；完整ä¿� æŒ� 规则è§� [translation-rules.md](translation-rules.md)。既有 Markdown é—¨ç¦� 对 `.zh.md` æ–‡ä»¶åŽŸæ ·ç”Ÿæ•ˆï¼ˆ`verify-md-wrap`ã€� `verify-md-links`）。\n\n## é—¨ç¦� ：verify-translation-pairing\n\n`pnpm run verify-translation-pairing`（`doc-sync`（文档å� Œæ¥é—¨ç¦� ）的一环，贡献者会针对文档å� ˜æ›´åœ¨æœ¬åœ°è¿� 行，CI 则会完整è¿� 行）机械地强制执行这份契约：\n\n1. 范围内的æ¯� 篇文档都有完整é…� 对。å� ‘现 README 时，basename ä¸� 区分大å°� å†™ï¼Œå› æ¤ `missions/readme.md` ä¸Žå…¶ä»–æ–‡æ¡£æ ¹ä¸€æ ·å±žäºŽèŒƒå›´ã€‚\n2. 任何已å˜åœ¨çš„é…� 对产物都完整且一致：三个文件é½� å…¨ã€� æ¯� 一侧的当å‰� blob hash ç‰äºŽè®°å½•å€¼ï¼ˆæ”¹äº†ä»»ä¸€ä¾§è€Œæ²¡é‡� 新确认é…� 对就å� ˜çº¢ï¼‰ã€� å� Œ
2026-07-23 22:41:53 +08:00
},
{
" r o l e ": " u s e r ",
" c o n t e n t ": " # T r a n s l a t i o n r u l e s \ n \ n E n g l i s h | [ ä ¸ æ – ‡ ] ( t r a n s l a t i o n - r u l e s . z h . m d ) \ n \ n H o w t o t r a n s l a t e b e t w e e n t h e t w o s i d e s o f a d o c u m e n t a t i o n p a i r i n t h i s r e p o . B o t h l a n g u a g e s c a r r y e q u a l a u t h o r i t y ( [ R E A D M E . m d ] ( R E A D M E . m d ) ) : a c h a n g e i s a u t h o r e d i n e i t h e r l a n g u a g e , a n d t h a t s i d e i s t h e s o u r c e f o r t h a t u p d a t e â € ” t h e s e r u l e s g o v e r n p r o d u c i n g o r u p d a t i n g t h e c o u n t e r p a r t . T h e y b i n d h u m a n s a n d a g e n t s e q u a l l y ; t h e c o m m i t t e d a g e n t w o r k f l o w t h a t a p p l i e s t h e m i s [ . a g e n t s / s k i l l s / d s h - t r a n s l a t e - d o c s ] ( . . / . . / . a g e n t s / s k i l l s / d s h - t r a n s l a t e - d o c s / S K I L L . m d ) . R u l e l e v e l s f o l l o w R F C 2 1 1 9 u s a g e : * * M U S T * * / * * M U S T N O T * * a r e g a t e - o r r e v i e w - b l o c k i n g ; * * S H O U L D * * n e e d s a s t a t e d r e a s o n t o d e v i a t e ; * * M A Y * * i s d i s c r e t i o n a r y . \ n \ n # # F a i t h f u l n e s s \ n \ n - T h e c o u n t e r p a r t * M U S T * s a y w h a t t h e a u t h o r e d s i d e s a y s â € ” n o a d d e d b e h a v i o r , p r e r e q u i s i t e s , w a r n i n g s , v e r s i o n c l a i m s , o r e x a m p l e s , a n d n o d r o p p e d o n e s . I f t h e p a i r d i s a g r e e s o n s u b s t a n c e , n e i t h e r l a n g u a g e w i n s b y d e f a u l t : f i x t h e s i d e t h a t i s w r o n g , t h e n b r i n g t h e o t h e r a l o n g i n t h e s a m e c h a n g e . \ n - T h e c o u n t e r p a r t * S H O U L D * r e a d a s n a t u r a l t e c h n i c a l w r i t i n g i n i t s o w n l a n g u a g e , n o t w o r d - b y - w o r d g l o s s . T r a n s l a t e m e a n i n g , r e s t r u c t u r e s e n t e n c e s w h e r e t h e t a r g e t g r a m m a r w a n t s i t , a n d k e e p t h e a u t h o r ' s r e g i s t e r â € ” t e r s e s t a y s t e r s e . \ n - D o n o t t r a n s l a t e t h e u n t r a n s l a t a b l e : i f a s e n t e n c e r e s i s t s n a t u r a l r e n d e r i n g b e c a u s e i t l e a n s o n a n i d i o m o f t h e s o u r c e l a n g u a g e , t r a n s l a t e t h e i d e a , n o t t h e i d i o m . \ n \ n # # V o i c e \ n \ n - T h e r e g i s t e r i s c a l i b r a t e d b y [ s t y l e - s a m p l e s . m d ] ( s t y l e - s a m p l e s . m d ) â € ” h u m a n - a p p r o v e d g o l d p a i r s , o n e p e r d o c u m e n t g e n r e . T h e c o u n t e r p a r t M U S T m a t c h t h e t a r g e t - l a n g u a g e s i d e o f t h e n e a r e s t s a m p l e ; w h e r e i t s v o i c e a n d a p r o s e v o i c e r u l e d i s a g r e e , t h e s a m p l e w i n s . C h i n e s e t a r g e t s u s e i n s t i t u t i o n a l t e c h n i c a l C h i n e s e ; E n g l i s h t a r g e t s u s e c o n c i s e p r o f e s s i o n a l d e v e l o p e r p r o s e . \ n - W r i t e a s a n a t i v e t e c h n i c a l a u t h o r r e s t a t i n g t h e c o n t e n t , n o t a s a t r a n s l a t o r t r a n s p o s i n g s e n t e n c e s . T h e n v e r i f y a g a i n s t t h e s o u r c e c l a u s e b y c l a u s e : n o t h i n g a d d e d , n o t h i n g d r o p p e d â € ” f l u e n c y n e v e r j u s t i f i e s l o s i n g a c l a u s e . \ n - G i v e s e n t e n c e s a n e x p l i c i t a c t o r w h e n t h e t a r g e t l a n g u a g e w o u l d o t h e r w i s e o b s c u r e i t ; f o r C h i n e s e , r e p l a c e v a g u e p a s s i v e s o r a b s t r a c t s u b j e c t s w i t h t h e a c t u a l a c t o r ( ç ³ » ç » Ÿ ã € � é — ¨ ç ¦ � ã € � è ¯ „ å ® ¡ ä º º ) . \ n - P r e f e r e s t a b l i s h e d t a r g e t - l a n g u a g e e n g i n e e r i n g i d i o m o v e r c a l q u e s ( è ¯ ¯ æ Š ¥ ï ¼ � æ ¼ � æ £ € f o r f a l s e p o s i t i v e / n e g a t i v e , æ ‰ § è ¡ Œ ç º ¢ ç º ¿ f o r e n f o r c e m e n t f r o n t i e r ) ; l o c a l i z e m e t a p h o r s i n s t e a d o f t r a n s p l a n t i n g t h e m , a n d u n p a c k n o u n c h a i n s w h e r e t h e t a r g e t l a n g u a g e r e q u i r e s i t . \ n - S p l i t l o n g p a r a g r a p h s b y s e m a n t i c u n i t â € ” o n e i d e a p e r p a r a g r a p h . P a r a g r a p h b o u n d a r i e s M A Y d i f f e r f r o m t h e s o u r c e ; t h e s t r u c t u r a l s i g n a t u r e d o e s n o t c o u n t p a r a g r a p h s . \ n - W h e n t r a n s l a t i n g i n t o C h i n e s e , c a t e g o r y n o u n s u s e C h i n e s e w i t h a f i r s t - m e n t i o n E n g l i s h a n n o t a t i o n ( å ® ž æ “ � æ ‰ ‹ å † Œ ï ¼ ˆ c o o k b o o k ï ¼ ‰ ) ; w h e n t r a n s l a t i n g i n t o E n g l i s h , u s e t h e c o n v e n t i o n a l E n g l i s h c a t e g o r y n a m e . L i t e r a l d i r e c t o r y o r f i l e r e f e r e n c e s s t a y c o d e - f o r m a t t e d E n g l i s h . \ n \ n # # S t r u c t u r e p r e s e r v a t i o n \ n \ n T h e p a i r i n g g a t e c h e c k s h e a d i n g d e p t h s , f e n c e d c o d e b l o c k s , t a b l e r o w a n d c o l u m n c o u n t s , l i s t k i n d s , o r d e r e d - l i s t s t a r t s , l i s t i t e m c o u n t s , a n d l i n k t a r g e t s . P r e s e r v e t h e r e s t o f t h e f r a m e m a n u a l l y ; t h e p a i r e d f i l e s M U S T m a t c h o n e t o o n e i n : \ n \ n - h e a d i n g h i e r a r c h y ( s a m e l e v e l s , s a m e o r d e r â € ” h e a d i n g T E X T i s t r a n s l a t e d ) , \ n - l i s t s h a p e a n d n u m b e r i n g , \ n - t a b l e s ( s a m e c o l u m n s , s a m e r o w o r d e r ; h e a d e r c e l l s t r a n s l a t e d p e r t e r m i n o l o g y ) , \ n - f e n c e d c o d e b l o c k s â € ” * * b y t e - i d e n t i c a l , i n c l u d i n g c o m m e n t s * * ; t h e p a i r i n g s i g n a t u r e c o m p a r e s t h e i r i n f o s t r i n g s a n d c o n t e n t s , a n d ` ` ` ` t s ` b l o c k s c o m p i l e u n d e r ` d o c - t y p e c h e c k ` , \ n - i n l i n e c o d e s p a n s ( c o m m a n d s , f l a g s , c o n f i g k e y s , f i l e p a t h s , e v e n t n a m e s , A P I n a m e s , v e r s i o n n u m b e r s ) â € ” v e r b a t i m , n e v e r t r a n s l a t e d o r r e f o r m a t t e d , \ n - l i n k s a n d a n c h o r s : e v e r y r e l a t i v e l i n k M U S T p o i n t a t t h e s a m e t a r g e t i n b o t h f i l e s â € ” b y c o n v e n t i o n t h e ` . m d ` p a t h , n o t t h e ` . z h . m d ` s i b l i n g â € ” s o l i n k s n e v e r d a n g l e w h e n o n e p a i r l a n d s b e f o r e i t s n e i g h b o r s . T h e O N L Y z h - s p e c i f i c l i n k i s t h e l a n g u a g e s w i t c h e r . L i n k T E X T i s t r a n s l a t e d ; t h e t a r g e t i s n o t . \ n \ n T h e r e p o ' s M a r k
} ,
{
"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` æ–‡ä»¶åŽŸæ ·ç”Ÿæ•ˆï¼šä¸€ä¸ªæ®µè� ½ä¸€ä¸ªç‰©ç� †è¡Œï¼ˆ`verify-md-wrap`）ã€� 相对链接必须å� ¯è§£æž� （`verify-md-links`）ã€� 文件末尾æ� °å¥½ä¸
},
{
" r o l e ": " u s e r ",
2026-07-27 10:04:53 +08:00
" c o n t e n t ": " # A g e n t N o t e : B i l i n g u a l d o c u m e n t a t i o n v i a p a i r e d s i b l i n g f i l e s a n d a p a i r i n g g a t e \ n \ n S t a t u s : i m p l e m e n t e d \ n \ n E n g l i s h | [ ä ¸ æ – ‡ ] ( 2026 -0 7 -0 2 - b i l i n g u a l - d o c s - a n d - p a i r i n g - g a t e . z h . m d ) \ n \ n # # P r o b l e m \ n \ n T h i s r e p o ' s d o c u m e n t a t i o n c o r p u s i s r e a d b y p e o p l e a n d a g e n t s i n s i d e a n d o u t s i d e t h e c o m p a n y , i n b o t h E n g l i s h a n d C h i n e s e . M a i n t a i n i n g a s e c o n d l a n g u a g e b y h a n d , w i t h n o m e c h a n i s m , i s h o w t r a n s l a t i o n s r o t : o n e s i d e m o v e s o n , t h e o t h e r s i l e n t l y l i e s , a n d n o g a t e n o t i c e s . T h e r e p o ' s s t a n d i n g a n s w e r t o i n v a r i a n t s o f t h i s k i n d i s t o e n c o d e t h e m a s a m e c h a n i c a l c h e c k ( s e e [ q u a l i t y g a t e s ] ( 2 0 2 6 - 0 6 - 1 1 - q u a l i t y - g a t e s . m d ) a n d [ d o c - s y n c e n f o r c e m e n t ] ( . . / . . / a r c h i v e d / p r o c e s s / 2 0 2 6 - 0 6 - 1 1 - d o c - s y n c - e n f o r c e m e n t . m d ) ) , s o t h e b i l i n g u a l p o l i c y s h i p s w i t h o n e . \ n \ n # # D e c i s i o n \ n \ n - * * P a i r e d s i b l i n g f i l e s w i t h e q u a l a u t h o r i t y . * * A d o c u m e n t a t i o n p a i r i s t h r e e s i b l i n g f i l e s : E n g l i s h ` f o o . m d ` , C h i n e s e ` f o o . z h . m d ` , a n d a c o n s i s t e n c y r e c o r d ` f o o . i 1 8 n . y a m l ` . N e i t h e r l a n g u a g e i s c a n o n i c a l â € ” a d o c u m e n t m a y b e a u t h o r e d a n d r e v i e w e d C h i n e s e - f i r s t a n d t r a n s l a t e d t o E n g l i s h a f t e r w a r d s , o r t h e r e v e r s e ; w h a t b i n d s t h e p a i r i s t h a t b o t h s i d e s m u s t s a y t h e s a m e t h i n g , a n d p a i r s m e r g e w h o l e ( b o t h l a n g u a g e s p l u s t h e r e c o r d , n e v e r o n e a l o n e ) . P o l i c y : [ d o c s / i 1 8 n / R E A D M E . m d ] ( . . / . . / . . / . . / d o c s / i 1 8 n / R E A D M E . m d ) ; t r a n s l a t i o n r u l e s : [ d o c s / i 1 8 n / t r a n s l a t i o n - r u l e s . m d ] ( . . / . . / . . / . . / d o c s / i 1 8 n / t r a n s l a t i o n - r u l e s . m d ) ; t e r m i n o l o g y s o u r c e o f t r u t h : [ d o c s / i 1 8 n / t e r m i n o l o g y . m d ] ( . . / . . / . . / . . / d o c s / i 1 8 n / t e r m i n o l o g y . m d ) . \ n - * * A s i d e c a r r e c o r d o f b o t h b l o b h a s h e s m a k e s c o n s i s t e n c y c h e c k a b l e . * * ` f o o . i 1 8 n . y a m l ` h o l d s t h e f u l l g i t b l o b h a s h o f e a c h s i d e a s o f t h e l a s t c o n f i r m e d - c o n s i s t e n t s t a t e . A n e d i t t o e i t h e r s i d e w i t h o u t r e - c o n f i r m i n g t h e p a i r i s t h e n m e c h a n i c a l l y d e t e c t a b l e a s a p u r e c o n t e n t c o m p a r i s o n â € ” n o h i s t o r y l o o k u p â € ” a n d t h e h a s h e s a r e c o m p u t a b l e f o r f i l e s e d i t e d i n t h e s a m e P R , w h i c h a c o m m i t - h a s h r e c o r d i s n o t . R e - r e c o r d i n g ( ` v e r i f y - t r a n s l a t i o n - p a i r i n g - - w r i t e < p a i r > ` , w h i c h r e q u i r e s n a m i n g t h e c o n f i r m e d p a i r s â € ” b u l k r e - r e c o r d i s a n e x p l i c i t ` - - w r i t e - - a l l ` ) p r o d u c e s a r e v i e w a b l e y a m l d i f f : c o n f i r m i n g c o n s i s t e n c y i s a n e x p l i c i t , v i s i b l e a c t i n t h e P R . \ n - * * ` v e r i f y - t r a n s l a t i o n - p a i r i n g ` j o i n s ` d o c - s y n c ` . * * T h e g a t e ( [ s c r i p t s / v e r i f y - t r a n s l a t i o n - p a i r i n g . t s ] ( . . / . . / . . / . . / s c r i p t s / v e r i f y - t r a n s l a t i o n - p a i r i n g . t s ) ) e n f o r c e s : e v e r y d i s c o v e r e d , n o n - e x c l u d e d s o u r c e h a s a c o m p l e t e p a i r ; e v e r y e x i s t i n g p a i r i s c o m p l e t e ( a l l t h r e e f i l e s ) a n d c o n s i s t e n t ( b o t h h a s h e s m a t c h , s w i t c h e r l i n k s b o t h w a y s , s t r u c t u r a l s i g n a t u r e s i d e n t i c a l ) ; a n d e x c l u d e d g e n e r a t e d , i n s t r u c t i o n , o r b i l i n g u a l - b y - c o n s t r u c t i o n f i l e s s t a y u n p a i r e d . [ s c r i p t s / t r a n s l a t i o n - p a i r i n g . m a n i f e s t . j s o n ] ( . . / . . / . . / . . / s c r i p t s / t r a n s l a t i o n - p a i r i n g . m a n i f e s t . j s o n ) c o n t a i n s o n l y e x p l i c i t e x c l u s i o n s , s o n o r e q u i r e m e n t c a n b y p a s s d i s c o v e r y a n d r e c e i v e a w e a k e r c h e c k . S o u r c e - o r i e n t e d c o d e g a t e s c o n s u m e a ` . z h . m d ` f e n c e s e q u e n c e a s a d e r i v a t i v e o n l y w h e n i t s u n s u f f i x e d s i b l i n g h a s t h e s a m e t r a c k e d f e n c e s i n t h e s a m e o r d e r w i t h b y t e - i d e n t i c a l b o d i e s ; a n i n c o m p l e t e , r e o r d e r e d , r e c l a s s i f i e d , o r c h a n g e d s e q u e n c e s t a y s i n d e p e n d e n t , s o t h e o w n i n g c o d e g a t e o r p a i r i n g g a t e r e p o r t s t h e m i s m a t c h . \ n - * * O n e c o r p u s - w i d e r e q u i r e m e n t . * * E v e r y d o c u m e n t i n s c o p e r e q u i r e s a c o m p l e t e p a i r f r o m c r e a t i o n ; t h e p o l i c y h a s n o p e r - f i l e r o l l o u t s t a t e , d a t e c u t o f f , o r R E A D M E - s p e c i f i c c l a s s . R E A D M E d i s c o v e r y c o v e r s e v e r y c a s e - i n s e n s i t i v e R E A D M E b a s e n a m e o u t s i d e v e n d o r e d , d e p e n d e n c y , a n d i g n o r e d b u i l d - o u t p u t t r e e s , i n c l u d i n g f u t u r e t o p - l e v e l d i r e c t o r i e s . A s i t e - p u b l i s h e d p a i r u s e s ` p a i r e d P a g e s ( ) ` s o t h e r o o t l o c a l e p r o j e c t s ` . z h . m d ` a n d ` / e n / ` p r o j e c t s ` . m d ` ; c r e a t i n g a c o u n t e r p a r t a l o n e d o e s n o t p u b l i s h i t . \ n - * * P a i r i n g r e c o r d s a r e m e t a d a t a , n o t C o r d i s L o a d e r c o n f i g u r a t i o n . * * C o r d i s c o n f i g u r a t i o n d i s c o v e r y a c c e p t s a c t u a l ` . c o r d i s . y m l ` a n d ` . c o r d i s . y a m l ` f i l e s w h i l e e x c l u d i n g ` * . i 1 8 n . y a m l ` , e v e n w h e n t h e d o c u m e n t n a m e c o n t a i n s ` c o r d i s ` . T h i s p r e s e r v e s v a l i d a t i o n o f e x e c u t a b l e L o a d e r e n t r i e s w i t h o u t p a r s i n g t r a n s l a t i o n h a s h e s a s c o n f i g u r a t i o n . \ n - * * T r a n s l a t i o n i s a g e n t w o r k w i t h h u m a n r e v i e w . * * T h e c o m m i t t e d w o r k f l o w i s [ . a g e n t s / s k i l l s / d s h - t r a n s l a t e - d o c s ] ( . . / . . / . . /
2026-07-23 22:41:53 +08:00
} ,
{
"role" : "assistant" ,
2026-08-04 17:36:14 +08:00
"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 的工作，由人评审。** 仓库内置的工作æµ� 是 [.agents/skills/dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md)，与 [dsh-code-review](../.
2026-07-23 22:41:53 +08:00
},
{
" r o l e ": " u s e r ",
2026-07-23 23:12:56 +08:00
" c o n t e n t ": " - - - \ n l a y o u t : d o c \ n - - - \ n \ n # S n a p s h o t n o t e \ n \ n T h e a g e n t p e r f o r m s o n e s t e p . \ n "
2026-07-23 22:41:53 +08:00
}
]
},
" r e s p o n s e ": {
2026-07-23 23:12:56 +08:00
" t r a n s l a t i o n ": " - - - \ n l a y o u t : d o c \ n - - - \ n \ n # å ¿ « ç … § è ¯ ´ æ ˜ Ž \ n \ n a g e n t ï ¼ ˆ æ ™ º è ƒ ½ ä ½ “ ï ¼ ‰ æ ‰ § è ¡ Œ ä ¸ € ä ¸ ª æ ¥ é ª ¤ ã € ‚ ",
2026-07-23 22:41:53 +08:00
" r e v i e w ": " - æ — ä ¿ ® æ £ ",
2026-07-23 23:12:56 +08:00
" f i n a l ": " - - - \ n l a y o u t : d o c \ n - - - \ n \ n # å ¿ « ç … § è ¯ ´ æ ˜ Ž \ n \ n [ E n g l i s h ] ( s n a p s h o t - n o t e . m d ) | ä ¸ æ – ‡ \ n \ n a g e n t ï ¼ ˆ æ ™ º è ƒ ½ ä ½ “ ï ¼ ‰ æ ‰ § è ¡ Œ ä ¸ € ä ¸ ª æ ¥ é ª ¤ ã € ‚ \ n "
2026-07-23 22:41:53 +08:00
}
}
