cn-doc-writer

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: 交付前回路

1. 结构是否服务当前读者
2. 事实、术语、代码、链接是否可追溯
3. 是否存在明显模板腔、生成式转场、自我声明堆积、过整齐列表或过强作者在场感
4. 去 AI 味后五维评分是否持平或提升
5. 若为分析型技术文章，是否在前 20% 提供总览地图，并至少给出一个任务流案例
6. 若评分或关键检查不达标，先修改，再输出

Step 4.5: 去 AI 味回路

只要正文基本正确，就必须执行一次“去 AI 味”回路。目标不是把技术文章改成聊天体，而是在不减信息密度的前提下，把文字从“模型整理稿”收束到“人类作者写成的工程判断”。对 write-cn-doc 与 optimize-cn-doc，此回路默认自动调用。

按 3 层顺序处理，不跳层：

1. 词面去味：先替换泛化、抽象、成组出现的套话。
2. 句式去味：再拆掉过度整齐的判断句和转场句。
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 + 末尾"写作笔记"等所有段）：

# v2.1 升级（2026-07-10 00:16 落地）：加入阿拉伯数字变体「5 维」「4 维」「3 维」
# 触发根因：commit e9541bce L283 命中「5 维自评（v2 修订）：结构 20/20」
# 原 grep 只匹配「五维」/「结构性」/「准确性」全名 — 漏掉「5 维」+ 阿拉伯分数
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 不适用，不强行输出
翻译后行数偏差远超预期	先排查是否因代码块、表格或分片导致；若不是，再压缩冗余或补遗漏