tech-article

把一个技术问题讲透：作者写完更深一层，读者看完能拿走一个东西；同时留下可复用资产，而不是只留下一篇公众号。

适用边界

本技能只处理两类文章：

1. 技术讲解 technical_explainer：解释一个模型、协议、框架、产品能力或工程机制怎样工作，帮助读者形成准确心智模型并作出技术选择。
2. 实操抄作业 hands_on_playbook：从真实目标、阻力、失败、修复、验证和优化出发，交付读者可以复现的实施路径。

主题核心是公司业务模式、产业竞争、资本预期或业务投资判断时，使用business-article。主题核心是三十五岁以后的人生经历与认知时，使用midlife-article。一般非技术公众号文章使用wechat-article。

问题驱动认知模型

禁止默认写成「背景 → 原理 → 实现 → 总结」。全文终点不是“把技术讲清楚了”，而是：

因为写这篇文章，对这个问题的理解比写之前深了一层；读者也跟着完成了一次认知升级。

研究与成文在脑子里固定跑通这条链：

真实问题 → 原有认知 → 认知冲突 → 原理拆解 → 外部方案 → 亲手实验 → 结果与证据 → 认知修正 → 可复用原则 → 下一步问题

成文时完成 6 次认知推进（章节可合并，但推进不可省略）：

四类强制资产

一篇文章写完，除公众号定稿外，必须在article/assets_ledger.json留下：

1. 知识资产：真正弄懂了什么（机制、边界、版本事实）。
2. 实践资产：代码、Demo、Benchmark、配置、架构图或可观察实验记录。
3. 认知资产：以前怎么认为 → 现在怎么认为 → 何种情况直接复用。
4. 复用资产：Skill、Checklist、模板、组件、代码库入口或设计原则中至少一项可带走的东西。

没有四资产，不算完整交付。长期目标是研究次数、实践次数、认知体系和可复用工具一起增长，而不只是文章篇数增长。

核心标准

1. 先确定读者任务：文章必须回答“读者想完成什么、现在卡在哪里、读完后能多做成什么”。
2. 问题驱动，不悬空：开场必须有场景、痛点与冲突；原理只服务于前面的问题。
3. 机制先于术语：从输入、处理、状态、输出、边界和失败条件解释技术，不用名词堆砌代替理解。
4. 证据接近源头：优先官方文档、规范、源码、仓库、论文、发布说明和可复现实验；二手文章只用于发现线索。
5. 版本必须钉住：涉及接口、配置、命令、行为或性能时，记录版本、日期、平台和前置条件。
6. 实操必须闭环：每个小目标都走“想做什么 → 卡在哪 → 怎么解决 → 如何验证 → 后续怎么优化”。
7. 代码必须诚实：可运行代码与伪代码明确区分；不得虚构API、参数、输出、性能数字或兼容性。
8. 失败路径不可省略：至少说明一个高概率错误、识别信号、原因和修复办法。
9. 外部对比围着同一问题：比较方案A/B/C时，必须共享同一个读者问题，并写清取舍；禁止产品巡礼。
10. 认知变化必须真实：判断变化只能由材料或实验推动；禁止先制造假误解再用反转句制造洞察。
11. 作者带路：文章像懂技术的人陪读者一起做，不像说明书、研究报告、发布会复述或AI拼接稿。
12. 帮助必须兑现：标题、导读、正文和结尾都自然落到读者能够获得的判断、能力、效率或风险规避。
13. 后台有来源，前台无脚手架：最终文章不放脚注、引用编号、资料清单和内部标记；确需引用原话时直接使用准确中文。
14. 视觉保持高上下文：正文图上部约三分之一呈现读者正在操作或观察的真实技术场景，下部约三分之二使用白色材质微3D信息块解释机制、步骤和故障路径；封面左半呈现真实技术场景，右半呈现白色微3D核心信息图。上下或左右两层都必须通过共同主体、色彩、光线和透视自然连接，每条最终提示词必须超过700个非空白字符。
15. 声音来自真实取舍：活人感来自作者实际掌握的材料、验证过程、判断变化和不确定边界，不靠口头禅、粗口、假装亲测或固定反转句式。
16. 资产必须落盘：四类资产写入assets_ledger.json，并与正文认知弧、实验与Spark一致。

阶段纪律

严格按阶段执行。开始任何阶段前，必须完整读取该阶段参考文件和references/author.md，不得凭记忆补写。阶段产物通过校验后才能进入下一阶段。

用户要求“完整公众号文章”时，必须依次完成S0至S6；用户已经明确主题时可跳过S0。S7仅在用户明确需要逐图视频旁白或配套语音时执行。用户在定稿后提出疑问或修改建议时，回到相关阶段补充研究或重做推理，再重新执行受影响阶段的校验，不得只做表面润色。

工作目录

所有正式产物只能写入操作系统当前登录用户的：

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

S0临时扫描写入：

/Users/<login-user>/wechat_articles/tech_scans/[scan_id]/

禁止写入沙盒目录、项目仓库、字面量~/目录或topics/_stage*。使用scripts/path_utils.py解析真实用户目录。

阶段事务

每个阶段执行：

1. 读取前序回执并确认未过期；
2. 读取本阶段参考文件；
3. 完成研究、推理或写作；
4. 写入约定产物；
5. 运行python skills/tech-article/scripts/validate_stage.py --stage N --topic-dir /absolute/topic/path；
6. 只有看到PASS和新回执后才宣布阶段完成。

S0使用--scan-dir。校验脚本只负责结构、路径、证据链、版本边界、复现链、认知弧字段和资产台账完整性；文章洞察、语言魅力与标题点击力必须由模型按参考文件审读。

研究与工具

• 检索入口优先Google，再进入官方原始链接；对登录页、动态页和需要浏览器渲染的页面，使用随技能提供的CDP脚本。
• CDP端点由Beneva环境变量或脚本默认的127.0.0.1:19222发现，不在提示词和业务脚本中另写浏览器端口。
• S1至S3都可以继续搜索和补抓页面，不能把S1误认为唯一研究阶段。
• 抓取页面保存到当前主题的research/raw_pages/，并在证据包中列出实际选用文件。
• S4的final_article_copy.html只能由scripts/markdown_to_wechat_html.py从final_article.md生成，禁止LLM手写HTML或另造模板。
• S5和S6只生成配图提示词，不生成真实图片。

完成定义

完整交付至少包含：

• research/tech_blueprint.json
• research/source_pack.json
• research/raw_pages/
• article/technical_mindmap.md
• article/final_article.md
• article/final_article_copy.html
• article/final_article_digest.txt
• article/assets_ledger.json
• assets/image_prompts.jsonl
• assets/title_cover_package.json
• assets/video_cover_prompts.jsonl
• S1至S6阶段回执

执行S7时额外交付：

• video/narration_segments.jsonl
• video/images/，预留给用户放入同编号正文图片
• video/audio/section_1.mp3至section_N.mp3
• video/audio_manifest.json
• S7阶段回执

S7通过后，用户只需把S5生成的正文图片按对应ID放入video/images/。随后整个video/目录可由narrated-video直接消费；本技能不合成MP4。

最终向用户报告时，说明文章模式、读者获得的实际帮助、验证过的技术环境、六次认知推进如何落地、四类资产各是什么、各阶段状态和最终HTML绝对路径。