企业官网建设流程全解析

• 人工智能
• AI Agent
• Agent 框架
• DeepSeek

导读

DeepSeek Harness 仓库采用英文与简体中文双语文档维护策略，每对文档（foo.md↔foo.zh.md）必须保持内容一致。本 Agent Note 记录了一项已落地（Status: implemented）的关键流程决策：把"日常小改动引发的翻译"从一套昂贵的多阶段工作流，收敛为当前 agent 在同一轮次内直接完成的一次性单遍翻译——加载术语表、翻译改动内容、必要时移动术语首现括注、保留未触及的对侧行文、重新记录配对，全程不调用翻译 skill、不生成简报、不委派 subagent。读者读完本文将掌握：轻量路径与手动扩展工作流的分界如何划分、两个 AI 产品（Claude Code 与 Codex）的 skill 调用元数据契约如何通过符号链接与门禁保持对齐、以及一次完整的双语配对更新应该如何操作与验证。

问题：一次小改动为何要支付"工作流级"成本

在引入轻量化路径之前，日常的双语编辑会自动选用完整的翻译 skill（dsh-translate-docs）。即使此前已经实现了"基于简报的最小更新优化"（见 2026-07-26-briefed-minimal-translation-updates.md），一次很小的文档改动仍可能触发以下整套编排：

1. 加载专用翻译工作流（skill）；
2. 生成一份翻译简报（briefing）；
3. 把行文翻译委派给 subagent；
4. 另行执行一轮核验（verification pass）。

该 Agent Note 指出，这套编排所耗费的时间、上下文窗口和模型 token，比直接翻译改动文本本身还要多；同时，skill 的自动发现机制还会在普通文档处理轮次中暴露这个重工作流——即便当前任务只是一两行的措辞调整，模型上下文里也会被塞入整套工作流的说明。

从配套的基准测试看（见前序 Agent Note 的 Benchmark 一节），一次 1～64 行的小改动在旧路径上的典型开销中位数是约 59.5 万相对 token 成本单位、32 轮对话，而简报路径约为 27.6 万 token 成本单位、14 轮，节省约三分之二——这还只是简报路径，轻量化路径的成本进一步降为"改动源文本 + 局部对侧上下文 + 术语表"三者之和。

核心决策：日常翻译一次性完成、只处理一遍

本 Agent Note 的第一条决策定义了轻量路径的全部行为，可概括为one-shot（一次性）与 one-pass（单遍）：

• 加载术语表：当前 agent 先加载 docs/i18n/terminology.md。术语表是"小但具有约束力"的输入，是防止全仓库术语漂移（term drift）的关键；该决策明确拒绝"连术语表也不加载"的选项，因为那等于用产品语言的不一致换取 token 节省。
• 只翻译改动内容：直接翻译本次发生改动的部分，不做整篇重译。
• 首现括注随编辑边界移动：如果某术语在整个文档中的"首次出现"位置跨过了编辑边界，则把该术语的中文括注（如agent（智能体））从被改动的片段移到新的实际首现处。
• 保留未触及的对侧行文：改动之外、已经经过评审的对侧文件措辞保持不变，避免重译造成的评审结果丢失。
• 不调用 skill、不生成简报、不启动单独的评审轮次、不委派 subagent：全部工作由当前 agent 直接完成。
• 重新记录配对：翻译完成后重新记录该文档对的配对一致性状态。

这套默认行为被固化在仓库的文档标准中：docs/AGENTS.md 第 43 行的常驻指令明确写道："Pairs update together: Terminology-guided, single-pass active-agent work repositions first-use annotations, preserves untouched prose, and re-records;dsh-translate-docsremains user-invoked"。也就是说，轻量默认不是某个 skill 的临时策略，而是根级与文档级指令的一部分。

扩展工作流：仅限手动调用

第二条决策把完整的扩展工作流（dsh-translate-docs）限定为仅手动调用。该 skill 保留的能力包括：

• 生成简报（briefing）；
• 行文翻译委派给 subagent；
• 整篇文档翻译路径（新配对）；
• 按范围核验（scoped verification）路径。

两个产品的调用元数据契约

技能目录 .agents/skills/dsh-translate-docs/SKILL.md 的 YAML frontmatter 中写着：

name: dsh-translate-docs description: Manually run the extended DeepSeek Harness bilingual-document workflow, including generated briefings, delegated prose translation, whole-document translation, and scoped pairing verification. disable-model-invocation: true user-invocable: true

• Claude Code读取SKILL.mdfrontmatter 中的disable-model-invocation: true与user-invocable: true：模型不得自动调用，但用户仍可显式调用；
• Codex读取同一 skill 目录下agents/openai.yaml中的policy.allow_implicit_invocation: false：同样禁止隐式调用。

仓库根目录的.claude/skills是指向../.agents/skills的符号链接（已验证存在），因此两个产品共享同一份提交到仓库的 skill 工作流，同时各自执行各自的调用元数据契约——单一来源，双份策略。

门禁如何保证两份策略不漂移

scripts/verify-skill-invocation-metadata.ts 是doc-sync（文档同步门禁）的组成部分，它对.agents/skills下每个带 Codex 产品元数据的 skill 目录做三项检查：

1. 解析SKILL.mdfrontmatter，校验disable-model-invocation与user-invocable必须是布尔值；
2. 解析agents/openai.yaml，校验policy.allow_implicit_invocation必须是布尔值；
3. 交叉比对：Claude Code 侧"仅手动"（disable-model-invocation === true）与 Codex 侧"仅手动"（allow_implicit_invocation === false）必须一致；且仅手动的 skill 必须保持user-invocable: true。

也就是说，如果某项 skill 只在一个产品中变成仅手动、或在 Claude Code 中对用户和模型都不可用，门禁都会直接报错拒绝（如Claude Code manual-only=true but Codex manual-only=false）。

用户如何显式调用

扩展工作流仅在用户显式点名时运行：

• Claude Code：/dsh-translate-docs；
• Codex：$dsh-translate-docs。

SKILL.md 的 Invocation boundary 一节对此有硬性约束："Run this extended workflow only when the user explicitly invokesdsh-translate-docsby name. Never select or load it for ordinary documentation work, from another skill, or from an inferred translation need"，并明确日常翻译遵循 docs/AGENTS.md 中的一次性单遍规则。

自动工作流不会串联进手动 skill

第三条决策处理的是"自动机制与手动 skill 的耦合"：自动工作流不得链式加载仅限手动调用的 skill。

• 轻量默认行为由根级指令（仓库根AGENTS.md）和文档指令（docs/AGENTS.md）定义；
• 文档、网站同步、行文与代码评审类 skill 会链接这些指令或 i18n 契约（docs/i18n/README.md），而不是因为"推断到了一次双语改动"就去加载dsh-translate-docs；
• 该决策在 docs/i18n/README.md 的 Division of labor 一节被进一步固化："Routine counterparts are updated directly by the working agent in one pass after it loads terminology.md; it does not invoke a translation skill, generate a briefing, run a separate translation-review pass, or delegate to a subagent. The extended dsh-translate-docs workflow retains those heavier mechanisms for explicit user invocation."

配对契约与评审契约保持不变

第四条决策强调：轻量化改变的是"执行方式"，不改变任何既有契约：

• 两种语言文件始终一并更新：foo.md与foo.zh.md以及一致性记录foo.i18n.yaml组成完整三件套，PR 不会只落单侧语言；
• 未触及的对侧措辞保持稳定：只打补丁，不重译；
• 术语约束仍然有效：翻译必须遵循 docs/i18n/terminology.md 的表格，双向绑定；
• 确认后才重写一致性记录：只有当前 agent 确认配对内容一致后，才通过verify-translation-pairing --write <pair>重写两侧的 blob hash 记录；
• doc-sync继续执行全语料机械检查：配对完整性、结构签名（标题层级、代码块、表格行列数、列表类型等）、语言切换行、链接 locale 等；
• 语义翻译质量仍由人工评审负责：门禁只能验证"两侧在这份精确内容上被确认过一致"，无法判断措辞是否地道、术语是否准确——这是评审者的一半契约。

一次标准的最小更新操作序列

综合 docs/i18n/README.md 与 SKILL.md，日常（轻量路径）更新一对文档的完整操作是：

1. 修改源语言一侧（假设为foo.md）；
2. 加载 docs/i18n/terminology.md，直接翻译改动内容到foo.zh.md，首现括注随编辑边界移动，未触及行文保持原样；
3. 记录配对：pnpm run verify-translation-pairing --write <pair>（重新计算并记录两侧 blob hash 到foo.i18n.yaml，该命令必须显式点名配对，裸--write会被拒绝，全量重录必须显式--write --all）；
4. 按范围验证：pnpm run verify-translation-pairing <pair>；
5. PR 层面运行pnpm run doc-sync（包含全语料配对检查与verify-md-wrap/verify-md-links）。

当用户显式调用扩展工作流时，更新路径则变为"简报驱动"：pnpm run gen-translation-brief <pair>生成简报（无参数时为所有失配配对生成），纯机械改动（改动全部位于两侧逐字节相同的代码围栏内）可直接pnpm run gen-translation-brief --apply <pair>拼接写入；行文改动则把简报作为 subagent 的完整工作集进行委派翻译；相关实现见 scripts/gen-translation-brief.ts 与 scripts/translation-brief.ts。

曾考虑的替代方案：为什么被拒绝

该决策记录了四个被评估后否决的替代方案，理解它们有助于把握边界：

其中第三条尤其重要：该决策刻意把"规模判断"从自动机制中移除，改为"用户显式选择"——agent 永远不做"这次改动够大所以自动用重工作流"的推断，避免隐藏策略带来的不可预期成本。

后果：成本结构与责任边界

成本结构的变化

普通开发的语言维护成本从"简报 + subagent 上下文"降为三者之和：

1. 发生改动的源文本；
2. 其局部对侧文件上下文；
3. 术语表。

轻量路径有意放弃扩展工作流提供的三样东西：自动生成的对齐信息（简报）、委派带来的隔离性、以及单独的行文核验轮次。作为交换，它获得了最低的 token 与上下文占用——前序简报决策的基准测试表明，对简报路径而言小模型与大模型已可同水平完成更新任务，轻量路径在此基础上进一步压缩。

责任与质量边界

• 当前 agent 在同一轮次内对日常翻译的最终结果负责：没有 subagent 的隔离，也没有第二遍核验兜底，一次性单遍意味着质量责任落在"翻译 + 按句对照验证"这一个 pass 里（SKILL.md 的 Pass 2 规则：fidelity 是在这里检查出来的，而不是写出来的）；
• 门禁的两个独立产品契约：Claude Code frontmatter 与 Codex 策略文件彼此独立，doc-sync负责在两者间做一致性校验；
• 人工评审仍然拥有语义翻译质量的最终裁决权：门禁输出绿不意味着措辞优秀，只意味着"这份精确内容被确认过一致"。

相关实现与进一步阅读

• 决策正文：.agents/notes/implemented/process/2026-08-08-lightweight-routine-documentation-translation.md（含中文对侧文件）
• 常驻指令：docs/AGENTS.md 第 43 行 "Pairs update together" 条款
• 配对契约与分工：docs/i18n/README.md
• 术语真源：docs/i18n/terminology.md
• 手动扩展工作流：.agents/skills/dsh-translate-docs/SKILL.md（.claude/skills符号链接指向同一目录）
• 调用元数据门禁实现：scripts/verify-skill-invocation-metadata.ts 及其测试 scripts/verify-skill-invocation-metadata.spec.ts
• 简报路径与基准数据：.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md
• 简报生成与配对校验脚本：scripts/gen-translation-brief.ts、scripts/translation-brief.ts、scripts/translation-pairing.spec.ts

这一流程设计揭示的核心原则可复用到任何"双语或双格式内容需要保持同步"的工程场景：默认路径要足够便宜，让"顺手更新对侧"成为无痛动作；昂贵路径保留但必须由用户显式选择；契约（术语、配对、评审）不因执行路径变轻而放松。

• 人工智能
• AI Agent
• Agent 框架
• DeepSeek