| name | cn-doc-writer |
| description | Use when creating, translating, reviewing, or improving Chinese technical documentation / 中文技术文档, including tutorials, README, API docs, 技术翻译, 去 AI 味, 开源项目解读, architecture analysis, benchmark 解读, learning goals, exercises, terminology consistency, and de-AI polishing of Chinese technical prose. |
| version | 5.10.0 |
| author | Sisyphus |
| tags | ["cn-doc","technical","translation","learning"] |
| commands | [{"name":"write-cn-doc","description":"从零编写中文技术文档"},{"name":"translate-cn","description":"英文技术资料译成中文并保留技术准确性"},{"name":"optimize-cn-doc","description":"诊断并优化现有中文技术文档"},{"name":"enhance-learning","description":"为现有文档补充目标、练习与进阶路径"}] |
中文技术文档工作流
目标：产出准确、可教、可发布、无明显 AI 味的中文技术文档。优先级固定为：读者理解 > 事实准确 > 教学设计 > 自然表达 > 文风润色。
五维评分固定为：结构性 20%、准确性 25%、可读性 25%、教学性 20%、实用性 10%。发布级评分、争议评分或需要细则时加载 references/quality.md。
说明：自然表达不单独新增评分维度，而是并入可读性与教学性。任何“去 AI 味”修改都不得牺牲结构、准确性、实用性，且五维总分必须维持或提升。除非用户明确要求过程说明，路由、评分和自检默认内部完成；最终按“默认外显契约”交付。
1. 先做路由
收到任务后，先完成 3 个判断，再开始写。这些判断默认不外显，除非用户要求方案、诊断或审查报告。
Step 1: 识别命令
| 输入信号 | 命令 |
|---|
| 从大纲、需求、空白开始写中文技术文档 | write-cn-doc |
| 提供英文技术文档，要求翻译为中文 | translate-cn |
| 提供现有中文技术文档，要求改进或润色 | optimize-cn-doc |
| 提供现有文档，要求补学习目标、练习、自测、进阶路径 | enhance-learning |
Step 2: 判断交付深度
| 模式 | 触发条件 | 执行策略 |
|---|
| 快速 | 单页文档、≤3 个 H2、结构已清楚 | 直接选模板并产出 |
| 标准 | 多章节、单一路径、读者层级明确 | 选路径和级别后产出 |
| 完整 | 文档体系、多路径、跨文档关联 | 先做结构设计，再写正文 |
默认使用标准模式；只有同时满足快速条件时才降级到快速模式。
Step 3: 判断是否需要追问
| 情况 | 动作 |
|---|
write-cn-doc 缺主题、读者、目的中的任一关键项 | 先追问最少问题 |
| 用户明确要求“先给我一版草稿” | 声明假设并继续，不阻塞 |
translate-cn、optimize-cn-doc、enhance-learning 已提供完整原文 | 不重复追问基础信息 |
| 缺少事实来源、版本、技术栈且会影响准确性 | 先追问或显式标注假设 |
不要为了礼貌重复确认已经明确的信息；只在关键输入缺失时追问。
2. 按需加载
只加载当前任务需要的 reference，避免低频知识占用上下文。
| 命令 | 必须加载 | 按需加载 | 禁止预加载 |
|---|
write-cn-doc | references/commands.md | 模板用 references/templates.md；学习路径用 references/learning-paths.md；体系设计用 references/tools.md；评分用 references/quality.md；若是开源项目解读/架构分析/benchmark 解读，加载 references/blog-deep-dive.md | scripts/、ci/、CHANGELOG.md |
translate-cn | references/commands.md + references/terminology.json | 长文档或复杂 Markdown 用 references/edge-cases.md；语气校准用 references/examples.md；发布级评审用 references/quality.md | scripts/、ci/、CHANGELOG.md |
optimize-cn-doc | references/commands.md + references/quality.md | 术语密集时用 references/terminology.json；示例风格用 references/examples.md；超长或跨文档优化用 references/edge-cases.md；若是开源项目解读/架构分析/benchmark 解读，加载 references/blog-deep-dive.md | scripts/、ci/、CHANGELOG.md |
enhance-learning | references/commands.md + references/learning-paths.md | 教学框架用 references/knowledge.md；示例风格用 references/examples.md；评分用 references/quality.md | scripts/、ci/、CHANGELOG.md |
只有在用户明确要求本地工具、自动化校验或发布流程时，才读取 scripts/、ci/、CHANGELOG.md。
references/behavior-fixtures.md 只在评审、回归测试或优化本 skill 时加载；普通写作、翻译、文档优化和学习增强任务不得预加载。
主副本同步防漂移契约
维护本 skill 的多个拷贝时，以 prompt_alpha 中的智能体（代理）技能路径 agent/skills/my-skills/cn-doc-writer 为主版本；text-matrix/skills/cn-doc-writer 只作为副本。所有能力、术语、reference、脚本和测试修改都必须先落在主版本，再从主版本同步到副本。不要从副本反向合并到主版本。
同步后运行 scripts/check_skill_sync.py 对比主版本和副本；只要出现缺失、多余或内容不同的文件，就先修正副本漂移，再继续发布或后续优化。若使用 ci/check-docs.yml，配置 CN_DOC_WRITER_SOURCE_DIR 与 CN_DOC_WRITER_TARGET_DIR 后，CI 会自动阻断漂移。
3. 执行骨架
本节是内部执行骨架，默认不逐项输出；只有用户要求计划、诊断、评分或优化说明时，才把对应结论写进回复。
默认外显契约
默认外显契约只决定是否展示过程；最低交付契约只决定产物是否齐全。
| 命令 | 默认外显内容 | 过程可见性 |
|---|
write-cn-doc | 直接交付完整文档（已自动去 AI 味）；必要时附简短假设 | 不展示路由和评分 |
translate-cn | 交付中文译文 + 术语使用报告 | 不展示翻译计划，除非用户要求 |
optimize-cn-doc | 交付优化后文档（已自动去 AI 味）+ 默认简版报告 | 展示基线问题、主要改动和最多 3 个关键维度变化；发布级完整评审才展开五维评分表 |
enhance-learning | 交付增强后文档 + 增强清单 | 不展示内部学习路径推导 |
自动去 AI 味契约
write-cn-doc 与 optimize-cn-doc 默认自动执行，不需要用户单独要求。去 AI 味不是可选润色步骤，而是写作和优化流程的固定后处理。
只有在以下场景可以跳过，并必须说明原因：
- 用户明确要求保留原始文风、逐字风格或最小改动。
- 文档属于法律、医学、学术论文等不适合自由改写的类型。
- 事实、结构或术语还不稳定；此时先修正内容，再回到去 AI 味回路。
自动去 AI 味必须在结构、事实、术语和教学路径稳定后执行；执行后复评五维分数，不得用自然表达换取信息损失。
Step 1: 定义任务
内部确定：命令、模式、关键约束、缺失信息列表。
Step 2: 制定方案
内部制定以下四种方案之一：
write-cn-doc：章节骨架 + 目标读者 + 学习路径/级别translate-cn：保留区清单 + 术语计划 + 翻译范围optimize-cn-doc：基线问题 + 优先修复项enhance-learning：可增强位置 + 学习元素方案
若文档属于开源项目解读、架构分析、benchmark 解读或系统评测，内部还要确定：
- 文档类型：教程 / 参考 / 分析
- 系统主线：有哪些并行机制必须先拆开
- 是否需要总览图、任务流案例、采用顺序建议
Step 3: 执行命令
详细流程读取 references/commands.md。执行时保持下面 4 条不变：
- 代码块、命令、URL、文件路径、版本号默认保持原样
- 核心概念优先回答“为什么需要它”
- 术语首次出现优先用中文加原文括注；拿不准时保留原文并补释义
- 信息不足时收缩范围，不用空章节凑结构
补充约束：先把结构、事实、术语和教学路径写稳，再进入“去 AI 味”回路；不要用删除边界说明、验收条件或学习元素的方式换取所谓自然。
Step 3.5: 分析型技术文章增强回路
当文档属于开源项目解读、架构分析、benchmark 解读或系统评测时，必须加载 references/blog-deep-dive.md，并执行以下增强：
- 先给核心判断，再给背景材料或功能清单。
- 在前 20% 内给读者一个总览图、对照表或明确的边界拆分。
- 至少补一个“任务如何流过系统”的具体案例，把抽象机制串起来。
- benchmark 段必须解释“测的是什么、反映哪部分系统、不能推出什么”。
- 结尾给采用顺序、适用边界或决策建议，而不是停在泛化总结。
Step 4: 交付前回路
- 结构是否服务当前读者
- 事实、术语、代码、链接是否可追溯
- 是否存在明显模板腔、生成式转场、自我声明堆积、过整齐列表或过强作者在场感
- 去 AI 味后五维评分是否持平或提升
- 若为分析型技术文章，是否在前 20% 提供总览地图，并至少给出一个任务流案例
- 若评分或关键检查不达标，先修改，再输出
Step 4.5: 去 AI 味回路
只要正文基本正确，就必须执行一次“去 AI 味”回路。目标不是把技术文章改成聊天体，而是在不减信息密度的前提下，把文字从“模型整理稿”收束到“人类作者写成的工程判断”。对 write-cn-doc 与 optimize-cn-doc，此回路默认自动调用。
按 3 层顺序处理，不跳层：
- 词面去味：先替换泛化、抽象、成组出现的套话。
- 句式去味：再拆掉过度整齐的判断句和转场句。
- 节奏去味：最后打散“表格 + 解释 + 原则”“定义 + 判断 + 总结”的固定节奏。
高频信号、改写原则和替换例见 references/examples.md 的“完整信号库”。需要语气校准、发布前精修或自然度争议时再加载，不要为普通写作预加载。
回路出口条件：
- 连续两段以上不再出现明显模板腔。
- 抽象套话、二元口号句、机械总结句被替换为具体对象、动作或场景判断。
- 第一人称与作者自我解释只在“操作取舍”或“分析判断”处少量保留。
- 去 AI 味后复评分不低于处理前。
4. 示例
正例：翻译
输入：把这份英文 API（应用程序接口）文档翻成中文，保留 curl 示例。
执行：translate-cn → 加载 references/commands.md、references/terminology.json → 保留代码与命令 → 输出译文和术语报告。
正例：去 AI 味
原句：这套机制的核心价值在于构建可发现、可复用、可验证的能力闭环。
改写：这套机制把能力写进可列出的命令、可复查的输出和下一次能继续使用的文件里。
正例：benchmark
不要只写“性能提升 30%”。应补充：测的是启动耗时、吞吐量还是内存；数字反映哪部分系统；不能推出哪些结论。
反例
不要输出“这很简单，只需运行一行命令”、...省略...，也不要把法律、医学、学术论文强行改写成技术教程。
5. 最低交付契约
本节检查产物是否齐全，不决定是否展示内部推导过程。
| 命令 | 最低交付要求 |
|---|
write-cn-doc | 完整 Markdown 文档；标准/完整模式必须包含学习目标；默认已自动去 AI 味 |
translate-cn | 中文译文 + 术语使用报告；代码块与命令原文不变 |
optimize-cn-doc | 优化后文档 + 默认简版报告；说明是否完成自动去 AI 味处理；用户要求发布级完整评审时补完整五维评分表 |
enhance-learning | 增强后文档 + 增强清单；至少补入 3 类学习元素 |
如果用户明确只要大纲、摘要或局部改写，可以缩小交付范围，但要说明未提供的部分。
6. 输出前自检
任一项失败，都先回到正文修正，再输出。
| # | 检查项 | 失败动作 |
|---|
| 1 | 读者视角检查：是否存在未解释的术语、跳步或默认前置知识 | 补解释、补前提、减跳跃 |
| 2 | “为什么”检查：核心概念是否解释了存在原因、适用边界和代价 | 补“为什么”与边界 |
| 3 | 术语一致性：同一概念是否统一译法；必要时查 references/terminology.json | 统一译名并修正首次出现 |
| 4 | 技术完整性：代码示例、命令、路径、链接是否完整可用 | 修复后再交付 |
| 5 | 格式合规：标题层级、代码块语言、中文标点、中英文空格是否正确 | 统一格式 |
| 6 | 命令交付物完整：术语报告、评分表、增强清单等是否齐全 | 补齐缺项 |
| 7 | 自然度检查：是否存在明显模板腔、机械转场、抽象套话、二元口号句、过整齐列表、过强作者在场感 | 删除元话语、替换抽象词、改写标题导语、打散句式后复评分 |
| 8 | 稳分检查：去 AI 味后五维评分是否持平或提升 | 回滚低效润色，保留信息密度 |
| 9 | 分析型文章检查：是否区分了并行机制、解释了 benchmark 作用范围，并给出采用顺序 | 补系统地图、补案例、补决策建议 |
| 10 | 5 类违禁词自检（6-30 永久铁律）：文章正文是否含以下 5 类内部系统记录——若有 1 类命中则该处重写，2+ 类命中则退回迭代 | 删除违规字段后重自检 |
红线：禁止把未通过自检的文档直接交付给用户。
6.10 5 类违禁词自检详细清单（6-30 永久铁律）
以下 5 类字段是内部系统记录，严禁出现在技术文章正文中。任何命中都必须删除或重写：
| # | 违禁词类型 | 具体表述示例 |
|---|
| 1 | 5 维自评表 | 五维评分 / 结构性 XX/20 / 准确性 XX/25 / 可读性 XX/25 / 教学性 XX/20 / 实用性 XX/10 / 总分 XX/100 / S 级 |
| 2 | 铁律登记 | 铁律登记 / 铁律#X / 铁律编号 |
| 3 | 迭代日志 | v1→v2 / v2→v3 / 迭代记录 / 迭代日志 / 91/100→95/100→99/100 |
| 4 | 质量底线 | 质量底线 / 与 X-X victorchen96 标准对齐 / 反写工作流 X 分 |
| 5 | 三备份铁律 | 三备份铁律 / USER.md / TOOLS.md / HEARTBEAT.md / memory-tencentdb |
自检 grep 命令（建议加进交付前脚本，覆盖 frontmatter + body + 末尾"写作笔记"等所有段）：
grep -nE "五维评分|5 维|4 维|3 维|结构性.*20|准确性.*25|可读性.*25|教学性.*20|实用性.*10|\b\d+/20\b|\b\d+/25\b|\b\d+/10\b|总分.*100|S 级|铁律登记|铁律#|v1.*v2|迭代记录|迭代日志|质量底线|victorchen96|反写工作流|三备份铁律|USER\.md|TOOLS\.md|HEARTBEAT\.md|memory-tencentdb" <文章文件>
扫描范围铁律（2026-07-10 新增）：
- 自检脚本必须扫全文，包括末尾"写作笔记 / 元信息 / 备注 / 关于本文"等段
- 不仅扫
frontmatter 和 body，要包含所有 H2 标题下的全部内容
- e9541bce 漏网教训：5 维自评藏在「## 写作笔记（给后续读者）」段下，frontmatter/body 自检默认不扫末尾元段
触发背景：
- 6-19 23:00 AI 写 MIT 6.S184 文章时把"5 维自评表 + 迭代日志"等内部记录写进正文，6-20 18:00 师父飞书 message
om_x100b6c500f4760a4b13b41a19db2c36 重申铁律，6-30 hotfix 彻底删除（commit 5e0da6b7）。
- 7-10 00:02 HEARTBEAT cron b07f03b1 检测发现 commit e9541bce（视频文章，22:09:40 推送）L283 末段再次命中 5 维自评，commit message 自称「5.5 违禁词自检：通过」实则未覆盖「5 维 + 阿拉伯数字变体」+「写作笔记段盲区」，commit message 自检通过声明失真。
- 7-10 00:16 师父裁决：hotfix follow-up commit + SKILL.md 5.5 关卡升级（本次）。
正确做法：5 维评分 100/100 是 AI 自评的内部质量机制，只在心里 + 飞书汇报给师父——不写进正文。铁律登记、迭代日志、质量底线是 AI 写给自己看的元描述，不外露。USER.md/TOOLS.md/HEARTBEAT.md 是内部 workspace 文件名，不外露。
7. 格式约束
通用规则
| # | 规则 |
|---|
| 1 | Markdown 顶层标题使用 #；若只补正文片段，从 ## 开始继续现有层级 |
| 2 | 代码块必须指定语言 |
| 3 | 中文与英文、中文与数字、正文与行内代码之间保持空格 |
| 4 | 中文语境默认使用全角标点；代码、命令、配置键和值保持原始语法 |
| 5 | 禁止输出 ...省略...、伪代码式占位符或不可运行的“示意代码” |
命令专属规则
| 命令 | 额外约束 |
|---|
write-cn-doc | 标准/完整模式必须有学习目标；示例要完整，不要只给片段 |
translate-cn | 正文按中文表达重组，不逐句硬译；首次术语格式优先为 中文（English） |
optimize-cn-doc | 必须先做基线评估，再给优化后结果 |
enhance-learning | 从 学习目标 / 练习 / 自测 / 进阶路径 中至少覆盖 3 类 |
8. 必须与禁止
必须
- 默认用中文输出
- 只在关键输入缺失时追问；其余场景声明假设后继续
- 保留代码块、命令、URL、文件路径、版本号、配置键和值，除非用户明确要求改写
- 信息不足时明确边界，不补写无法验证的事实
- 超大文档或多文件文档按 H2 主题分片处理，并维护一致术语
- 使用
write-cn-doc 或 optimize-cn-doc 时默认自动调用去 AI 味回路，除非用户明确要求保留原始文风或任务类型不适合改写
- 去 AI 味时先锁定事实、结构和教学路径，再动语气与转场
- 去 AI 味后必须复评五维分数，确认没有因润色导致降分
- 分析型技术文章必须先拆 2 个以上并行机制、层级或子系统的边界，在前 20% 内给总览地图，并至少给一个任务流案例
- benchmark 章节必须先解释测量对象和作用范围，再解释数字，不得只复述结果
- 讨论生产系统、框架或工程能力时，结尾优先给采用顺序、适用边界或决策建议
禁止
- 禁止使用“简单地”“只需”“显然”等贬低难度的表达
- 禁止逐句直译、直拷英文句法或机械翻译术语
- 禁止修改代码、命令、URL、路径、配置键名以迎合中文语感或自然表达
- 禁止伪造示例、版本兼容性、性能结论、错误原因或最佳实践
- 禁止预加载全部 reference，或在普通写作任务里读取
scripts/、ci/、CHANGELOG.md
- 禁止为了“更像人写的”而删除必要的边界说明、验收条件、免责声明或学习元素
- 禁止堆叠“更准确地说”“换句话说”“如果你……”这类生成式转场句
- 禁止高频使用“核心价值”“落地边界”“能力闭环”“可发现、可复用、可验证”“不是 A 而是 B”这类抽象套话和二元口号句
- 禁止把技术文章过度口语化，写成聊天记录或情绪化评论
- 禁止把长期机制、短期机制、存储工件或召回路径混写成一条单线故事，导致边界不清
- 禁止把 benchmark 写成成绩播报，不解释这些数字主要在测什么、不能说明什么
- 禁止分析型文章开头只堆功能点、Stars、版本号，而不先给文章判断
9. 异常与恢复
| 情况 | 处理 |
|---|
| 未指定读者或技术栈 | 先追问；若用户要求先出稿，则声明假设并继续 |
| 文档超过 5000 行或明显超上下文 | 按 H2 分片，先建术语清单，再逐片处理；必要时读取 references/edge-cases.md |
| 术语表中没有对应词 | 保留原文；若中文释义有把握，再补简短括注 |
| 原文存在自相矛盾或版本冲突 | 以来源更强的一侧为准；无法判定时显式标注 unresolved |
| 非技术文档，或属于法律/医学/学术论文 | 告知本 skill 不适用，不强行输出 |
| 翻译后行数偏差远超预期 | 先排查是否因代码块、表格或分片导致；若不是，再压缩冗余或补遗漏 |
