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-07-30 03:48:07 +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 i s u n d e r i n t e r n a l t e s t i n g . F e a t u r e s a n d i n t e r f a c e s m a y c h a n g e . \ n \ n T h e i n t e r n a l b u i l d u p l o a d s a l l S e s s i o n L o g s b y d e f a u l t t o h e l p d i a g n o s e r e p o r t e d p r o b l e m s . S e t ` D S H _ T E L E M E T R Y _ D I S A B L E D = 1 ` t o d i s a b l e t e l e m e t r y . S e n d f e e d b a c k t h r o u g h t h e i n t e r n a l W e C h a t g r o u p . \ 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 d e f a u l t a c t i v e c h e c k o u t i s ` ~ / . d s h / s o u r c e / c u r r e n t ` , a n d t h e l a u n c h e r i s l i n k e d i n t o ` ~ / . l o c a l / b i n ` . R e - r u n t h e i n s t a l l e r t o u p d a t 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 ) o w n s a l t e r n a t e l o c a t i o n s , u p d a t e m e c h a n i c s , a n d r e c o v e r y 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### Profiles\n\n`dsh` boots profiles — ordered stacks of plugin-bundle patch layers under your own overrides in `$DSH_HOME/profiles/<name>`:\n\n```sh\ndsh --profile web # the browser UI (same as: dsh web)\ndsh plugin --profile tui add <package> # install a plugin into a custom profile\ndsh --profile tui # boot it\n```\n\nThe [CLI contract](apps/cli/README.md#profiles) describes profile layout, layer semantics, and config dump commands.\n\n### Headless\n\nRun one task, print the final answer, and exit:\n\n```sh\ndsh run \"summarize this workspace\"\n```\n\n### Automation and SDKs\n\nFrom a source checkout with `DEEPSEEK_API_KEY` in the environment or its root `.env`, start the ACP automation server:\n\n```sh\npnpm run demo:acp\n```\n\nThe [Python SDK](python/README.md) drives a bundled JSON-RPC runtime. The [examples](examples/README.md) cover the runnable headless, ACP, JSON-RPC, Code Mode, and self-referential compositions.\n\n## Why DeepSeek Harness\n\nBuilt-in capabilities cover file reading, editing, and search; shell and persistent PTY execution; reusable skills; task tracking, goals, plans, todos, and background tasks; subagents and workflows; sandboxing and approvals; settings and credentials; persistent, resumable, forkable, and queryable sessions; LSP and web access; context compaction; and telemetry. Each composition selects the subset appropriate to its surface. The Web UI includes Plan Mode.\n\n- **Everything is a plugin.** Models, tools, policies, storage, context management, and interfaces are composable [Cordis plugins](docs/user/develop/basic/index.md), so deployments can extend or replace behavior without forking the agent loop. See the [architecture](docs/architecture.md) for the underlying design.\n- **Runs are reconstructable.** Anything visible to the model is logged in the authoritative session stream; persistence, resume/fork/query, replay, telemetry, and UIs derive from the same events. See the [session-log architecture](docs/architecture.md#session-log).\n- **Code Mode (opt-in).** It exposes a `run_code` tool and a generated TypeScript SDK; only program output re-enters model context. See [Code Mode](packages/core/tools/README.md#code-mode).\n- **Self-referential Cordis tools are opt-in.** They let the agent inspect its live runtime and mount or unmount plugins while it r
2026-07-23 22:41:53 +08:00
} ,
{
"role" : "assistant" ,
2026-07-30 03:48:07 +08:00
"content" : "# DeepSeek Harness\n\n[English](README.md) | ä¸æ–‡\n\nDeepSeek Harness（`dsh`）是一款基于 DeepSeek Harness SDK 构建的开æº� coding agent（编程智能体）。\n\n它采用了**一切皆æ� ’件**的架构。\n\n## 内测声明\n\nDeepSeek Harness æ£å¤„于内部测试阶段，功能和接å� £å� ¯èƒ½å� ‘生å� ˜åŒ–。\n\n为帮助诊æ–ä¸ŠæŠ¥çš„é—®é¢˜ï¼Œå†…æµ‹ç‰ˆæœ¬é»˜è®¤ä¸Šä¼ æ‰€æœ‰ä¼šè¯� 日志。设置 `DSH_TELEMETRY_DISABLED=1` å� ¯å…³é—é� ¥æµ‹ã€‚请通过内部ä¼� 业微信群å� � 馈问题和建议。\n\n## 安装\n\n克隆仓库，然å� Žè¿� 行安装器：\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/current`，å� ¯åŠ¨å™¨é“¾æŽ¥åˆ° `~/.local/bin`。å†� 次è¿� 行安装器å� ³å� ¯æ›´æ–°ã€‚其他ä½� ç½®ã€� 更新机制和æ� ¢å¤� 选项由 [`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### Profile\n\n`dsh` å� ¯åŠ¨ profile：按åº� å� 放的æ� ’件组å� ˆåŒ… patch 层，之上å†� å� åŠ ä½ åœ¨ `$DSH_HOME/profiles/<name>` ä¸çš„自有覆盖层：\n\n```sh\ndsh --profile web # the browser UI (same as: dsh web)\ndsh plugin --profile tui add <package> # install a plugin into a custom profile\ndsh --profile tui # boot it\n```\n\nprofile 布局ã€� 层è¯ä¹‰ä¸Žé…� 置输出命令详è§� [CLI（命令行界é� ¢ï¼‰å¥‘约](apps/cli/README.md#profiles)。\n\n### Headless\n\nè¿� 行一项任务，打å� °æœ€ç»ˆç”案å� Žé€€å‡ºï¼š\n\n```sh\ndsh run \"summarize this workspace\"\n```\n\n### 自动化与 SDK\n\n在æº� ç � 检出ä¸é€šè¿‡çŽ¯å¢ƒå� ˜é‡� æˆ–æ ¹ç›®å½• `.env` 设置 `DEEPSEEK_API_KEY`，然å� Žå� ¯åŠ¨ ACP（Agent Client Protocol）自动化æœ� 务器：\n\n```sh\npnpm run demo:acp\n```\n\n[Python SDK](python/README.md) 驱动éš� 附的 JSON-RPC è¿� 行时。[示例](examples/README.md)涵盖å� ¯è¿� 行的 headlessã€� ACPã€� JSON-RPCã€� Code Mode 和自指组å� ˆã€‚\n\n## 为什么选择 DeepSeek Harness\n\n内置功能涵盖文件读å� –ã€� 编辑与æ� œç´¢ã€� shell å’ŒæŒ� ä¹… PTY 执行ã€� å� ¯å¤� 用 skill（技能）ã€� 任务跟踪ã€� ç›®æ ‡ã€� 计划ã€� 待办事项与å� Žå� °ä»»åŠ¡ã€� subagent 与工作æµ� ã€� 沙箱与审批ã€� 设置与å‡æ� ®ã€� å� ¯æŒ� 久化ã€� æ� ¢å¤� ã€� fork 与查询的会è¯� ã€� LSP 与 Web 访问ã€� 上下文压缩（context compaction），以å� Šé� ¥æµ‹ã€‚æ¯� 个组å� ˆå� ªé€‰ç”¨é€‚å� ˆå…¶ä½¿ç”¨æ–¹å¼� 的能力å� 集。Web UI 包å� « Plan Mode。\n\n- **一切皆æ� ’件。** 模型ã€� 工具ã€� ç–ç•¥ã€� å˜å‚¨ã€� 上下文管ç� †å’Œç•Œé� ¢å� ‡å� ¯ç»„å� ˆä¸º [Cordis æ� ’件](docs/user/develop/basic/index.md)ï¼Œéƒ¨ç½²æ–¹æ— éœ€ fork agent loop（智能体循环）å� ³å� ¯æ‰©å±•æˆ–替æ� ¢è¡Œä¸ºã€‚底层设计è§� [架构文档](docs/architecture.md)。\n- **è¿� è¡Œå� ¯é‡� 建。** 凡是模型å� ¯è§� 的内容，都会记录在æ� ƒå¨� 会è¯� æµ� ä¸ï¼›æŒ� 久化ã€� æ� ¢å¤� ï¼� forkï¼� 查询ã€� 回放ã€� é� ¥æµ‹å’Œ UI å� ‡ä»Žå� Œä¸€ç»„事件派生。å� ‚è§� [会è¯� 日志架构](docs/architecture.md#session-log)。\n- **Code Mode（需显å¼� å� ¯ç”¨ï¼‰ã€‚** 它会æ� � ä¾› `run_code` 工具和生æˆ� çš„ TypeScript SDK，å� ªæœ‰ç¨‹åº� 输出会é‡� 新进入模型上下文。å� ‚è§� [Code Mode](packages/core/tools/README.md#code-mode)。\n- **自指 Cordis 工具需显å¼� å� ¯ç”¨ã€‚** 这些工具å� ¯è®© agent 检查自身的实时è¿� 行时，并在è¿� è¡Œä¸æŒ‚载或å� ¸è½½æ� ’件。å� ‚è§� [Cordis 工具](packages/s
2026-07-23 22:41:53 +08:00
},
{
" r o l e ": " u s e r ",
2026-07-28 18:06:07 +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 e s e t u p t u t o r i a l t a k e s a n e w c o n t r i b u t o r f r o m p r e r e q u i s i t e s t o a c h e c k e d c h e c k o u t . T h e c o n t r i b u t o r r e f e r e n c e t h a t f o l l o w s c o v e r s r e p o s i t o r y l a y o u t , d a i l y w o r k f l o w , a n d C I s h a p e . D e s i g n r a t i o n a l e a n d i m p l e m e n t a t i o n d e t a i l s b e l o n g t o t h e l i n k e d A g e n t N o t e s a n d s c r i p t s . \ n \ n # # S e t u p t u t o r i a l \ 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 c o n f i g u r e s w o r k t r e e - l o c a l L e f t h o o k h o o k s a n d t h e ` d s h - t r a n s l a t i o n - p a i r i n g ` G i t m e r g e d r i v e r 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 ` . 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 h o o k - p a t h s a f e t y c o n t r a c t ; t h e [ a u t o m a t i c p a i r i n g m e r g 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 8 - 0 8 - a u t o m a t i c - t r a n s l a t i o n - p a i r i n g - m e r g e s . m d ) o w n s t h e m e r g e d r i v e r . \ n \ n I f e i t h e r i n t e g r a t i o n i s 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 I f t h e w r a p p e r r e j e c t s e x i s t i n g G i t c o n f i g u r a t i o n o r r e p o r t s a s t a l e l o c k , f o l l o w i t s d i a g n o s t i c a n d t h e l i n k e d A g e n t N o t e r a t h e r t h a n e d i t i n g w o r k t r e e m e t a d a t a s p e c u l a t i v e l y . 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 g e n e r a t e t h e o w n e d p a t h . \ 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 S e t u p i s c o m p l e t e w h e n ` p n p m r u n t y p e c h e c k ` e x i t s s u c c e s s f u l l y . \ n \ n # # C o n t r i b u t o r r e f e r e n c e \ 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 u s e s i s o l a t e d H o s t a n d C l i e n t a g g r e g a t e s . A n o r d i n a r y p a c k a g e i s r e g i s t e r e d i n e x a c t l y o n e a g g r e g a t e : H o s t p a c k a g e s i n ` t s c o n f i g . h o s t . j s o n ` a n d C l i e n t p a c k a g e s i n ` t s c o n f i g . c l i e n t . j s o n ` . \ 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 : [ ] ` , a n d 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 . I t i s 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 e e n t r y f o r e x p l i c i t l y r u n n i n g t h e c o m p l e t e P r o j e c t R e f e r e n c e g r a p h ; t h r o u g h t h e i n h e r i t e d ` p a t h s ` , i t i s a l s o 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 / ` . | 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 p a c k a g 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 , a n d t h e e x c e p t i o n a l H o s t p r o j e c t o f ` a p i / r e m o t e s ` . | 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 ` , a n d t h e e x c e p t i o n a l C l i e n t p r o j e c t o f ` a p i / r e m o t e s ` . | Y e s | \ n | ` t s c o n f i g . b a s e . j s o n ` | S h a r e d c o m p i l e r O p t i o n s a n d t h e s o u r c e ` p a t h s ` m a p . A l s o t h e r e s o l u t i o n f a c a d e t h e v i t e s t c o n f i g s p o i n t v i t e - t s c o n f i g - p a t h s a t : i t h a s n o ` i n c l u d e ` , s o i t s ` p a t h s ` a p p l y t o e v e r y i m p o r t e r . | N o | \ n | ` t s c o n f i g . b a s e . c l i e n t . j s o n ` | B r o w s e r c o m p i l e r s h a p e ( ` j s x ` , D O M l i b s , ` t y p e s : [ ] ` ) e x t e n d e d b y t h e C l i e n t a g g r e g a t e a n d e v e r y ` p a c k a g e s / c l i e n t / * ` p a c k a g e . | N o | \ n \ n H o s t a n d C l i e n t s t a y t w o a g g r e g a t e p r o g r a m s b e c a u s e b o t h s i d e s d e c l a r a t i o n - m e r g e t h e c o r d i s ` C o n t e x t ` i n t e r f a c e u n d e r t h e s a m e k e y s w i t h d i f f e r e n t s e r v i c e s ; o n e p r o g r a m s e e i n g b o t h m e r g e s r e p o r t s a c o l l i s i o n . T h e c o l l i s i o n e x i s t s o n l y i n s i d e a ` t s . P r o g r a m ` â € ” m o d u l e r e s o l u t i o n n e v e r t r i g g e r s i t â € ” w h i c h i s w h y t h e s o l u t i o n m a y r e f e r e n c e b o t h a g g r e g a t e s a n d o n e p a t h s f a c a d e m a y s p a n b o t h s i d e s . T h r e e d i s c i p l i n e s f o l l o w : \ n \ n - ` t s c o n f i g . b a s e . j s o n ` n e v e r g a i n s ` i n c l u d e ` o r ` f i l e s ` : t h e y w o u l d l e a k i n t o e v e r y e x t e n d i n g p a c k a g e p r o j e c t a n d n a r r o w t h e f a c a d e ' s m a t c h - a l l s c o p e . \ n - A s c r i p t t h a t b u i l d s a r e p o - w i d e ` t s . P r o g r a m ` s e e d s ` t s c o n f i g . h o s t . j s o n ` o r ` t s c o n f i g . c l i e n t . j s o n ` e x p l i c i t l y â
2026-07-23 22:41:53 +08:00
} ,
{
"role" : "assistant" ,
2026-07-28 18:06:07 +08:00
"content" : "# å¼€å� ‘指å� —\n\n[English](development.md) | ä¸æ–‡\n\næ� 建教程引导新贡献者从准备å‰� ç½®æ� ¡ä»¶å¼€å§‹ï¼Œç›´åˆ°æ£€å‡ºé€šè¿‡æ£€æŸ¥ã€‚å� Žé� ¢çš„贡献者å� ‚考介ç»� 仓库布局ã€� 日常工作æµ� å’Œ CI å½¢æ€� 。设计ä¾� æ� ®ä¸Žå®žçŽ°ç»†èŠ‚属于链接的 Agent Note 和脚本。\n\n## æ� 建教程\n\n### å‰� ç½®æ� ¡ä»¶\n\n- Node.js 支æŒ� 22.19+ 与 24+。CI 覆盖 22.19ã€� 24 å’Œ 26ï¼›è§� [Node 引擎下é™� Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- å� ¯ç”¨äº† Corepack çš„ pnpm。仓库在 `package.json` ä¸å›ºå®šä½¿ç”¨ `pnpm@11.7.0`；如果 `pnpm --version` æ— æ³•é€šè¿‡ Corepack 解æž� ，请先è¿� è¡Œ `corepack enable`。\n- Git 2.26 或更高版本；钩å� 设置会å� ¯ç”¨ Git çš„ worktree 专属é…� 置扩展。\n- å� ¯é€‰ï¼šä¸€ä¸ª DeepSeek API key，用于 Webã€� headless å’Œ ACP（Agent Client Protocol）自动化 agent（智能体）演示以å� ŠçœŸå®ž API çš„ e2e 测试。\n\n### 首次æ� 建\n\nåœ¨ä»“åº“æ ¹ç›®å½•å®‰è£…ä¾� 赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` é…� ç½® worktree 本地的 Lefthook é’©å� å’Œ `dsh-translation-pairing` Git å� ˆå¹¶é©±åŠ¨ã€‚[worktree 本地钩å� Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩å� 路径的安全契约；[自动é…� 对å� ˆå¹¶ Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) è´Ÿè´£å� ˆå¹¶é©±åŠ¨ã€‚\n\n如果ä¾� 赖是从缓å˜æ� ¢å¤� 或 `postinstall` 被跳过而导致任一集æˆ� 缺失，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒ç»� 现有 Git é…� 置或报告陈旧é”� ，请é� µå¾ªå…¶è¯Šæ–和所链接的 Agent Note，ä¸� è¦� å‡çŒœæµ‹ç¼–辑 worktree 元数æ� ®ã€‚移动检出目录å� Žï¼Œè¯·é‡� æ–°è¿� 行包装脚本以é‡� 新生æˆ� 自有路径。\n\n新克隆å� Žè¯·å…ˆè¿� 行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` æˆ� 功退出å� ³è¡¨ç¤ºæ� 建完æˆ� 。\n\n## 贡献者å� ‚考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通 package å� ªç™»è®°è¿›å…¶ä¸ä¸€ä¸ª aggregateï¼›Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是å� ¦æž„æˆ� program？ |\n|---|---|---|\n| `tsconfig.json` | solution æ ¹ï¼š`extends` baseã€� `files: []`ã€� 引用两个 aggregate。它是 tsserver å� ‘现入å� £ï¼Œä¹Ÿæ˜¯æ˜¾å¼� æ‰§è¡Œæ•´å¼ Project Reference 图时的入å� £ï¼›ç»� 继承的 `paths` 充当 tsx è¿� è¡Œ `examples/` 与 `scripts/` 时的解æž� é…� 置。 | å� ¦ |\n| `tsconfig.host.json` | Host aggregate：Host packageã€� 示例ã€� 测试ã€� 脚本和 website，以å� Š `api/remotes` çš„ Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` package å� Šå…¶æµ‹è¯•ã€� `apps/web`，以å� Š `api/remotes` çš„ Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与æº� ç � `paths` æ˜ å°„ã€‚å� Œæ—¶æ˜¯å� „ vitest é…� 置让 vite-tsconfig-paths 指å� ‘的解æž� é—¨é� ¢ï¼šå®ƒæ²¡æœ‰ `include`ï¼Œå› æ¤å…¶ `paths` 适用于任何 importer。 | å� ¦ |\n| `tsconfig.base.client.json` | æµ� 览器编译形状（`jsx`ã€� DOM libã€� `types: []`），由 Client aggregate å’Œæ¯� 个 `packages/client/*` package extends。 | å� ¦ |\n\nHost 与 Client ä¿� æŒ� 两个 aggregate programï¼Œæ˜¯å› ä¸ºä¸¤ä¾§åœ¨ç›¸å� Œé”®ä¸‹ä»¥ä¸� å� Œæœ� 务对 cordis `Context` 接å� £å� šå£°æ˜Žå� ˆå¹¶ï¼›å� •ä¸€ program å� Œæ—¶çœ‹åˆ°ä¸¤ä»½å� ˆå¹¶ä¼šæŠ¥å†²çª� 。这ç§� 冲çª� å� ªå˜åœ¨äºŽ `ts.Program` 内部——模å� —解æž� 永远ä¸� 会触å� ‘它——所以 solution å� ¯ä»¥å� Œæ—¶å¼•ç”¨ä¸¤ä¸ª aggregate，一个 paths é—¨é� ¢ä¹Ÿå� ¯ä»¥æ¨ªè·¨ä¸¤ä¾§ã€‚ç”±æ¤æŽ¨å‡ºä¸‰æ� ¡çºªå¾‹ï¼š\n\n- `tsconfig.base.json` æ°¸ä¸� æ·»åŠ `include` 或 `files`：它们会泄æ¼� è¿›æ¯� 个 extends 它的包项目，并收窄门é� ¢çš„全匹é…� 范围。\n- æž„é€ å…¨ä»“ `ts.Program` 的脚本显å¼� ç§� å� `tsconfig.host.json` 或 `tsconfig.client.json`——永ä¸� ç§� å� æ ¹ solutionï¼Œå› ä¸ºæŠŠä¸¤ä¸ª aggregate 展平进一个 program 会撞上 `Context` å� ˆå¹¶å†²çª� 。\n-
2026-07-23 22:41:53 +08:00
},
{
" r o l e ": " u s e r ",
2026-08-08 21:49:23 +08: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 \ n W h e n t w o b r a n c h e s c o n t a i n v a l i d c o n f i r m a t i o n s o f t h e s a m e p a i r , t h e i n s t a l l e d ` d s h - t r a n s l a t i o n - p a i r i n g ` G i t m e r g e d r i v e r c o m p o s e s a n e w r e c o r d o n l y i f G i t ' s d e f a u l t t e x t m e r g e s u c c e e d s f o r b o t h r e c o r d e d o w n e r - b l o b t r i p l e t s a n d t h e m e r g e d p a i r r e t a i n s i t s s w i t c h e r s a n d s t r u c t u r a l s i g n a t u r e . A n y u n c e r t a i n s h a p e r e m a i n s a n o r d i n a r y c o n f l i c t ; ` p n p m r u n r e s o l v e - t r a n s l a t i o n - p a i r i n g - c o n f l i c t s ` a p p l i e s t h e s a m e f a i l - c l o s e d o p e r a t i o n t o a m e r g e t h a t h a s a l r e a d y s t o p p e d , s t a g e s e v e r y s a f e p a i r i n g r e c o r d , a n d e x i t s u n s u c c e s s f u l l y w h e n o t h e r p a i r i n g c o n f l i c t s r e m a i n . T h e [ a u t o m a t i c p a i r i n g m e r g 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 8 - 0 8 - a u t o m a t i c - t r a n s l a t i o n - p a i r i n g - m e r g e s . m d ) o w n s t h e m e c h a n i s m a n d a l t e r n a t i v e s . \ 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
2026-07-23 22:41:53 +08:00
} ,
{
"role" : "assistant" ,
2026-08-08 21:49:23 +08: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\n 当两个分支都包å� «å� Œä¸€é…� 对的有效确认时，已安装的 `dsh-translation-pairing` Git å� ˆå¹¶é©±åŠ¨å� ªä¼šåœ¨ Git 默认文本å� ˆå¹¶èƒ½åˆ†åˆ«å¹²å‡€å� ˆå¹¶è®°å½•æ‰€æŒ‡å� ‘的英文三方 blob 与ä¸æ–‡ä¸‰æ–¹ blob，且å� ˆå¹¶å� Žçš„é…� 对ä»� ä¿� 留两侧的è¯è¨€åˆ‡æ� ¢è¡Œå’Œç»“æž„ç¾å� � 时，组å� ˆå‡ºä¸€ä»½æ–°è®°å½•ã€‚ä»»ä½•æ— æ³•ç¡®å®šçš„æƒ…å½¢éƒ½ä¿� 留为普通冲çª� ï¼›`pnpm run resolve-translation-pairing-conflicts` 会对已ç»� å� œæ¢çš„å� ˆå¹¶æ‰§è¡Œå� Œä¸€å¥—é� ‡é”™å� ³ä¿� 留冲çª� çš„æ“� 作，暂å˜æ¯� 份å� ¯å®‰å…¨ç”Ÿæˆ� çš„é…� 对记录，并在还有其他é…� 对冲çª� 时以é� žé›¶çŠ¶æ€� 退出。[自动é…� 对å� ˆå¹¶ Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责记录该机制与备选方案。\n- **è¯è¨€åˆ‡æ� ¢è¡Œã€‚** 两个文件在å� „自 H1 æ ‡é¢˜ä¹‹å� Žç«‹å� ³äº’链：英文文件带 `English | [ä¸æ–‡](foo.zh.md)`，ä¸æ–‡æ–‡ä»¶å¸¦ `[English](foo.md) | ä¸æ–‡`。\n- **结构与å� ¦ä¸€ä¾§ä¸€ä¸€å¯¹åº”。** æ ‡é¢˜æ·±åº¦ä¸Žé¡ºåº� ã€� 列表类型ã€� 有åº� 列表起始编å� ·ã€� 列表项数é‡� ã€� è¡¨æ ¼è¡Œåˆ—æ•°ã€� é“¾æŽ¥ç›®æ ‡ä¸Žé€� å—节一致的代ç � å� —在é…� 对两
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
}
}
