job-yang/jobyang-ai-skills/engineering-docs

研发技术文档

读者先看到结论和全貌，再按需进入细节；图让人一眼看出重点，并且以后能直接改。下面先说交付物长什么样，再说怎么做。

触发与归属：只要在技术文档里画工程图，就是本技能

不需要用户点名“用 engineering-docs 画图”。命中下面任一情况，走本技能的内容判断与绘图桥接，哪怕当前任务只是“更新文档、回评论、补一张图”。原生能力适合时优先 Archify；它缺少而旧后端明确支持的专用图型用旧能力兜底。维护 `.py` 图源仍用 `diagram_kit`。

• 在技术方案/系统设计/RFC/ADR/设计评审/迁移方案里新增、修改、重画一张图。
• 图里出现的是服务、模块、组件、容器、节点、角色、阶段、状态、表实体、数据存储、上下游及其调用/数据/时序关系。
• 已经有一张 mermaid 流程图、或在飞书画板上手摆的结构图，需要改、替换、统一风格。

归属优先级（高到低）：

1. 工程结构图/流程图/泳道/时序/状态/数据流/ER/部署/里程碑 → 本技能组织事实和关系，由 scripts/archify_bridge.py 按能力与输入族选择：原生适用时走 Archify，旧专用layout明确支持时走改良旧模板。能力缺口可以兜底，输入／生成／检查错误不能自动换图。
2. 统计数据图表（折线、柱状、散点、分布、漏斗等，表达的是数字而不是工程关系）→ 才用通用可视化能力（ECharts 等）。
3. 飞书画板 / 其他平台 → 只是发布适配器，把已生成、已检查的成品写进去，不负责从零构图。

判据是“图表达的是工程关系还是纯数字”：表达工程关系一律归本技能，不要因为任务标题里没有“写文档”三个字就改用通用画图或直接手写 mermaid。

别的写作技能只借图或阅读增强，不抢正文：feynman-explainer（调研稿）、talk-smith（分享稿）需要严谨工程图时复用本技能的 Archify 桥接。用户要一页式讲解、分享速读页时，可用 Explainer 将已核对正文做成图表联动页面；内容与叙事仍归原文体技能，不因借图或网页交付改成工程方案。

绘图边界：内容归本技能，绘制归后端，平台只发布

• 先判能力：读取 references/diagram-capabilities.md，必要时运行桥接的 capabilities。图义、关键特性和交付格式能由原生完整承载时优先使用；不能只看同名图型是否存在。
• 原生图：按 references/archify-bridge.md 读取所选Schema与作者规范，明确主路径、分组、边界和条件，保留Archify原生视觉，不覆盖为旧灰框。
• 专用兜底／旧图：旧JSON的 layout 字符串交改良的 render_templates；已有 .py 图源仍用 diagram_kit。源文件保留，报告后端和兜底原因。两种Schema不强行互转，旧静态图不冒充原生交互页。
• 检查后交付：新图桥接完成生成与来源检查后，必须用独立 Playwright 实际渲染，核对入口、主路径、归属、标签和交互。桥接报告 browser_verified=false 表示它没有做浏览器验收；不能只凭退出码报“画得清楚”。旧 SVG 仍运行 diagram_check。
• 平台只做承载：不手写 mermaid 充结构／流程图，不在飞书画板 DSL 中从零摆节点。发布到哪里不决定内容方法，也不保证 HTML 能在该平台直接运行；需要静态图时从成品导出 PNG／SVG。
• 可修改源：新图保留 JSON，一页式讲解保留 .archify.md；旧图保留 .py。draw.io 原生节点编辑沿用旧后端，不能把 Archify SVG 导出直接等同于原生绑定。

交付物

正文：三层

只读首屏、H2 和每章第一段，读者就能说出：做什么、为什么现在、主干怎么做、代价和风险、要他决定什么。写法、预算和改写示例见 references/writing-contract.md。

正文格式：结构优先，段落是例外

读者是扫读的。大段文字是本技能最常见的失败，必须主动避免：

• 先判形状再落笔：对比/风险/多对象多属性 → 表格；步骤 → 有序列表；并列要点、属性 → 无序列表（- **标签**：内容）；结论、待拍板、前提、默认值 → > 引用块加粗标签（飞书发布为高亮块）；只有因果推理才写短段落。
• 硬线：段落 ≤ 120 字；纯段落不连排超过 2 段；超过 300 字的章节至少一个表格或列表；加粗只加粗关键词或数字（≤ 16 字）。
• 写完每章自查：只看加粗、表头、列表标签和引用块，能否读出本章要点？ 不能就重排格式。

形状对照表、强调层级和改写示例见 references/formatting.md（写正文前必读）。本技能是所有写作技能共用版式底线（haohao-shuohua/references/reader-layout.md）里密度最高的一档。

图：先选图型，再画

卡片图不是默认图型。 最常见的失败是每张图都画成「分区 + 白卡片 + 折线 + 结论卡」。画之前先认关系的形状：

• 先明确读者要回答的问题，再定主路径、归属、条件与图型。不要用卡片数量、流程步数硬判图型。
• 图文互补：图要表达文字或表格没有直接呈现的关系；对象名称相同不算重复，逐项重排而没有理解增益才算重复。
• 完整选择规则见 references/diagram-selection.md，新旧差集与兜底见 references/diagram-capabilities.md；执行与输入路径见 references/archify-bridge.md。

图与阅读页的交付

新图保持 Archify 原生的角色色面、轻分组和路径编码；旧图使用本技能浅色面／轻轮廓主题，分类色与状态色分开，不自动按编号换色。完整规则见 references/visual-design.md。

额外阅读能力按需用：技术方案的速读页、机制讲解、分享稿可以借用 Explainer 的一页图文组合、步骤定位、来源和代码片段、面板局部修订。它不替作者取证，不改变原文体，也不把所有正文强制改成网页；说明见 references/archify-reading.md。

平台无关交付见 references/portable-delivery.md，飞书发布读 references/lark-publish.md。静态图与正文默认分发，交互页按平台能力作独立附件或链接。

维护历史图时读 references/diagram-system.md，旧脚本示例为 assets/examples/personal-harness/arch.py；这些不是新图默认入口。

工作流

1. 确认任务（新建或更新技术方案）：谁读，读完做什么决定或动作，依据什么，覆盖什么范围。模式：新建 / 更新已有文档（先通读全文和图）/ 评审 / 模板适配。
2. 收集上下文，默认直接推进：先读用户给的文件、链接、代码、配置、日志、历史决定；涉及仓库、源码、论文或技术机制调研时，在检索与分析前读取 feynman-explainer 及其范例，研究清楚再回到本技能形成工程方案；已有核实结果直接复用。上下文已经充分时直接起草，不搞固定问答；只追问会改变核心决定的缺口。读取材料所需的平台技能可以先加载，但不能代替内容方法；写入前完成内容检查与中文收尾。边聊边写见 references/collaboration-workflow.md。
3. 建立工程判断：现状事实、问题、目标约束、候选、决定与代价、落地设计、风险、验证发布回退、未决问题。这是检查顺序不是目录。完整模型见 references/decision-model.md。
4. 先写速读层：标题、首屏、总览图草稿；全部 H2/H3 + 每章第一段。标题写短关键词、模块或方向（“聚合校验”“发布与回退”“数据采集”），像目录一样写宽一点，不写成一句话、不写具体作用域或结论、不编号（不写“第 N 步/1./一、”），结论和作用域放进第一段；正文不写“老板/同学问”“你让我”等对话来源和手机号/邮箱/姓名称谓（doc_check 会报错拦截）。跑 python3 scripts/doc_check.py doc.md --skim --source <材料>，只读速读层确认五问答得上。
5. 填细节：每段问"删掉它，评审结论、职责、失败处理或验收会不会变"，会变的留章节，只影响实现的进附录，都不影响的删。留下的内容按 references/formatting.md 的形状表选格式，默认表格/列表/引用块，不默认写段落。
6. 设计必要的图：先按选择规则定问题、主路径、归属与条件，查询能力差集后准备原生Schema或完整旧layout输入，再运行桥接。适用的原生图优先，专用能力缺口由旧后端兜底；输入错误或执行失败不偷偷换图。实际用独立Playwright看图，核对关键事实、格式、后端和可读性。维护旧 .py 仍用 diagram_kit 与 diagram_check。
7. 检查与交付：再跑两个 check，处理提醒或说明保留理由；锁定事实后过一遍 haohao-shuohua 洗 AI 味（技术文档成文的必经收尾，只改语言不改技术含义与判断强度；不得把表格、列表、引用块改回段落，格式结构归本技能）；高风险/正式评审做独立读者测试，走 references/quality-gates.md 全检 + references/human-reading.md（总览、主线、随机章节、全文四层）。先交付平台无关文件（正文＋JSON／.archify.md 与 HTML；旧图为 .py／SVG／draw.io，静态图按需导出），再按用户指定平台发布；平台（lark-doc/飞书等）只承载成文，不决定结构；平台不可用或没权限不阻塞，写明哪步没发、需要谁做什么。

复杂流程读 references/process-modeling.md，数据图读 references/data-charts.md，图型内容要求读 references/diagram-guidance.md，团队模板读 references/template-adaptation.md。

依赖原则：核心零依赖，可选自动补

• diagram_kit／diagram_check／doc_check 仍只靠 Python 标准库，旧图维护不需要平台账号。默认新图的 Archify 需要 Node.js 18+，后端随包固定版本，不自动安装或升级；缺运行时就明确报告，不偷偷换旧画法。
• 数据图要 matplotlib/numpy：脚本已接 scripts/bootstrap.py，首次运行自动装到技能内 .deps/（pip install --target，不写系统环境、不要 sudo）；装不上时把脚本给出的手动命令转给用户，不允许说成"画图不可用"。
• 旧SVG的PNG预览仍可用 rsvg-convert → Node resvg → whiteboard-cli。新Archify静态图从原生浏览器导出PNG；其SVG含CSS样式，不默认走旧转换器。飞书连线绑定只在旧图与发布时按目标环境验证。

使用边界

使用：技术方案、系统设计、RFC、ADR、重构、迁移、性能方案；把代码、接口、运行证据和讨论整理成可评审文档；评审方案是否可信、可实施、可验证、可回退；画各类技术图；映射团队模板。

不用：非技术提案、纪要、纯润色、教程、API 全集、未形成工程决定的调研、技术观点文章；面向读者的技术分享文/talk/slides（讲一个技术或项目、不形成评审决策文档）走 talk-smith，本技能只接其中需要评审/拍板的方案与配套架构图。

与 content-infographic 的分工（相辅相成、不互斥）：本技能出严谨图——精确框线、真实模块/接口/时序、可编辑可评审的工程结构；content-infographic 出直观图——面向读者、帮记忆的步骤链/对比/概念比喻（可含文生图场景）。同一机制在对外分享里可两张成对：直观图帮读者记住、结构图供工程评审，谁也不替代谁。拿不准归属时问一句：这张图要"经得起评审、能照着实现"（本技能），还是要"读者一眼记住这个道理"（content-infographic）。

OPC 独立交接：复用用户材料和指定输出位置，不依赖 iLoop；需要信封封装或打包时读 references/handoff.md。