18trees-AI-writing-skill

项目是什么

18trees-AI-writing-skill 是一个中文口播稿整理 skill：把“作者已经想明白、但口播表达较乱”的原稿，整理成一篇仍然明显像作者本人写的文章。

它要处理的是语音输入留下的那一坨——口水词、断句乱、专名错、一整块不分段——以及随后更麻烦的一步。直接丢给 AI 整理，文章会变干净，但读起来不像你了：它会替你升华结论、把观点写软、塞进“不是……而是……”、拆成一堆 bullet list、加粗到发光。

所以这个 skill 反过来做：整理优先于润色，保真优先于稳健。事实和口播污染可以修，作者的观点、语气和锋利度不动。它面向用语音输入写自己稿子的人，落地方式有三种：装进 Claude Code、装进 Codex，或者把合订版粘给任意一个 AI 聊天工具。CONTRIBUTING.md 里也写明了边界：不接受批量洗稿和伪原创他人内容的用法。

具体结构

整个仓库只有一条主线：规则写在 skills/ 里，由脚本合成合订版，再交付到不同的工具。图里最下方的那组节点不在这条数据流上，它们是这个仓库自证与自我约束的部分。

规则源。 规则只维护在一个地方：skills/voice-preserving-essay-editor/。SKILL.md 是入口，写任务本质、六条编辑优先级、事实与观点的边界、AI 味红线和段落硬约束；细则按主题拆成六个文件放进 references/，用到哪条读哪条。入口保持精简，是为了让 skill 在 Claude Code 和 Codex 里都跑得好；目录里另有一份 agents/openai.yaml，只提供 Codex 的界面元数据。

生成物。 拆分版和单文件版不能各自维护，手抄必然走样。scripts/build-dist.sh 从 SKILL.md 里读出 version，剥掉 frontmatter 和只对拆分版有意义的路由表，把入口与六份细则拼成 dist/voice-preserving-essay-editor.md——一份所有规则都在里面、不依赖任何外部文件、插件或 API 的合订版。改规则只改 skills/，改完跑一次脚本重新生成。

交付。 拆分版整份装进工具：Claude Code 走插件市场安装，Codex 复制到 skills 目录。没有 skill 机制的工具则收到合订版全文，粘贴即可，不需要安装任何东西。

自证与约束。 examples/ 放着一份真实的口播转写原稿和整理后的成稿：原稿 620 字，保留了 ASR 错误、口水词和半截句，成稿逐条标注了每处改动对应哪条规则。CONTRIBUTING.md 定义了这个仓库的核心约束——这是累计式 skill，只增量优化不回退——并列出 10 条不得弱化的规则。

优秀设计

整理 > 润色 > 改写。 这是写进任务定义的一句排序：如果“更漂亮”与“更像作者原文”冲突，优先后者。围绕它的六条编辑优先级里，最后一条才是“稳健、中性、更容易被普遍接受”；作者允许激进、片面、强硬，也允许写下一个以后可能被自己推翻的判断。

事实可以纠正，判断不自动中和。 人名、作品名、明确的数据和年份、ASR 专名错误，属于可以检索并修正的部分；而对社会结构的理解、价值判断和“我认为”的个人立场，不会因为缺少证据就被降格成“可能”“也许”。检索只负责纠正事实，不负责给作者降调。

AI 味句式被点名封禁。 “不是……而是……”被列为最高风险的句式：原文没有就不主动制造，原文已有也要判断是否必要，同一章节出现多次必须逐一检查。同类句式、把文章改造成大量 bullet list、擅自升华结论、频繁使用“首先/其次/综上所述”，都在禁止清单里。默认原则是“能直接说是什么，就直接说”。

段落节奏是硬约束，而且规则本身可以演进。 随笔的基本单位是完整段落，默认 2～5 句；独立短句通常每 4～6 个自然段最多 1 个；禁止用空行制造“高级感”“电影感”。这套规则还保留了版本演进：v0.6 把段落完整性升级成硬约束，v0.7 改成以中等长度段落为主——后一代修正前一代，但不推翻。

改规则只改一个地方。 规则的源文件只有 skills/，dist/ 是生成物，两边内容必须一致。AGENTS.md 把验证方法也写死了：改完重跑一次生成脚本，git diff 应该没有任何输出。

只增量，不回退。 CONTRIBUTING.md 的核心约束只有一条：新规则只能增加、修正或细化，不得删除已经验证有效的旧规则；觉得旧规则有问题，正确做法是提出一条新规则来细化或限定它。其中 10 条被维护者确认为不可回退。

解决了什么问题

• 转写留下的 ASR 错误、错别字、专名和事实错误会被修正，口水词、断句污染和半截句会被删掉。
• 观点不会被写软：强判断不会变成“可能”，原文没有的“不是……而是……”不会被塞进来。
• 排版会被重排——小标题、加粗、段落切分——但结构化程度由内容决定，随笔不会被改成公众号鸡汤或咨询报告。
• 一套规则在三种工具里生效：Claude Code 和 Codex 装拆分版，任意 AI 聊天工具粘合订版，后者不需要安装任何东西。
• 每次改规则都能自我验证：重跑生成脚本、确认 git diff 为空，再对照 examples/ 走一遍，确认示例仍然符合规则。
• 输出前的最后一道自检只有一个问题：我是在整理作者，还是在替作者写作？