tech-doc-to-wechat

把一份已经正确但难读的技术文档，重构成读者愿意点开、读完、收藏和转发的公众号文章。传播性来自问题选择、信息顺序、认知冲突和表达密度，不来自夸张或删减技术事实。

双重契约

每次转换同时满足两条硬约束：

1. 技术保真：源文档中的有效技术细节必须先进入事实台账，再映射到正文。接口名、参数、状态、时序、权限、数字、版本、失败条件与边界不得悄悄丢失、改义或合并成模糊表述。
2. 传播重构：最终稿必须围绕一个读者真正关心的问题推进，把说明书顺序改造成“现场问题 → 原有理解为何不够 → 关键机制 → 取舍与失败 → 完整路径 → 可复用判断”。

标题可以扩大好奇心，不能扩大事实。开场可以制造张力，不能虚构事故、用户误解、亲测经历、性能收益或对手缺陷。

适用边界

只处理已有技术源文档的载体转换。允许为核对当前版本读取源码、官方文档和提交记录，但不得在没有用户授权时把任务扩张成完整外部研究。

• 源文档已经过时、内部矛盾或事实明显不足：先报告问题，标为 source_gap，不能替作者静默修正。
• 用户要求“尽量保留所有细节”：默认所有已登记技术事实都必须在正文、表格、代码块或技术附录中出现。
• 文档很长：可以分篇，但必须先给出分篇覆盖表；不得借“公众号篇幅”删除细节。
• 需要从零形成证据包、运行 Demo 或 Benchmark：转用 tech-article。

完整流程

用户明确提供了源文档时，跳过选题扫描，严格执行 S0 至 S4。开始每一阶段前，完整读取 references/author.md 和该阶段参考文件；前一阶段校验 PASS 后才能继续。

事实台账纪律

S0 必须给每条技术事实稳定编号。至少识别以下类型：

• architecture：层次、职责、依赖、所有权；
• flow：输入、状态转换、时序、终止条件；
• interface：API、工具、命令、参数、字段；
• constraint：版本、权限、预算、并发、路径、前置条件；
• failure：错误信号、原因、影响、修复；
• comparison：方案差异、取舍、适用边界；
• example：代码、配置、调用样例、完整任务路径。

原文目录标题和重复解释不是事实；会改变实现、运维、排障或选型判断的信息才是事实。不要为了提高覆盖率把一段内容粗暴登记成一条大事实。

每条事实必须保留原文锚点和精确标识符。S1 为每条事实指定正文去向；S2 的 coverage_map.json 必须给出正文中的精确可搜索锚点。正文不展示内部事实编号。

传播性规则

“爆款潜力”按可审核能力定义，不按情绪强度定义：

1. 标题命中具体读者和真实问题，并承诺正文确实交付的判断或能力。
2. 第一屏让陌生读者说清谁遇到了什么问题、代价是什么、为什么常见理解不够。
3. 全文只保留一条主问题；部件清单必须被问题驱动，不能轮流介绍产品功能。
4. 每一节都至少完成一个动作：解释原因、暴露边界、解决冲突或带读者走完路径。
5. 技术细节采用“先讲作用与后果，再给精确名称”的双层表达；表格和附录承担密度，不承担叙事推进。
6. 至少保留一条真实失败路径和一项工程取舍。
7. 结尾交付可迁移的判断或检查表，不写空泛总结。

禁止标题党词库驱动作文。诸如“颠覆、炸裂、封神、秒杀、终于有人讲清楚”只有源材料足以支持且语境自然时才可出现；默认不用。

路径与阶段事务

正式产物写入当前登录用户的：

/Users/<login-user>/wechat_articles/topics/[topic_id]/

每阶段执行：

1. 读取前序回执并确认未过期；
2. 读取本阶段参考文件与 references/author.md；
3. 生成约定产物；
4. 运行 python scripts/validate_stage.py --stage N --topic-dir /absolute/topic/path；
5. 只有看到 PASS 才进入下一阶段。

S4 的 HTML 必须由 scripts/markdown_to_wechat_html.py 从最终 Markdown 生成。校验脚本验证结构、哈希、事实覆盖、标题证据和审校闭环；语言吸引力仍需人工式审读。

完成交付

至少包含：

• source/source_document.*：不可变源文档快照；
• research/source_inventory.json：结构与技术事实台账；
• research/transformation_plan.json：读者任务、认知主线与全量安置计划；
• article/final_article.md：公众号定稿；
• article/coverage_map.json：源事实到正文锚点的映射；
• article/fidelity_audit.json 与 article/engagement_audit.json；
• article/final_article_copy.html 与 article/final_article_digest.txt；
• article/assets_ledger.json；
• assets/title_cover_package.json；
• S0 至 S4 回执。

最终报告必须说明源文档、事实总数与覆盖率、明确保留的关键细节、没有验证的边界、传播性改造发生在哪里，以及 HTML 的绝对路径。