研发技术文档
OPC 调用与独立交接
独立调用使用用户材料和显式输出位置，不依赖 iLoop，也不自动查找其目录。用户明确进入 OPC 时，复用已确认的 PRD、设计和约束，由适配器控制目录、审批及下一节点；不重开产品澄清。需要信封封装、校验或打包时读 references/handoff.md，相对引用的材料一并交付。
这是技术文档的唯一入口。它既负责把上下文收齐、与用户对齐，也负责技术判断、正文、图示和验收。
默认直接推进，不要求用户先选择工作流。只有信息不足、方案存在真实分歧，或用户明确希望边聊边写时，才进入分段共创。
默认交付可搬运的 Markdown、可编辑图源和经过验证的预览。飞书画板、MindAI 及其他绘图 Skill 都是可选工具；没有账号或外部 Skill 时，按包内方法完成本地交付。没有渲染能力时明确标注视觉未验收。
使用边界
使用本技能：
- 新建或更新技术方案、系统设计、RFC、ADR、重构、迁移和性能方案。
- 把代码、接口、运行证据、讨论记录和用户说明整理成可评审文档。
- 与用户逐步对齐技术决定并修改已有技术文档。
- 评审方案是否可信、可实施、可验证和可回退。
- 为文档选择并生成必要的架构图、流程图、时序图、状态图、数据图和排期图。
- 把同一套技术判断映射到团队模板。
不使用本技能：
- 普通非技术提案、纪要和内容共创。
- 只做措辞、语气或中文润色。
- 教程、操作手册、API 参数全集。
- 只想调研或搞懂技术，还没有形成工程决定。
- 技术观点文章和未来推演。
按需读取
- 所有任务：
references/decision-model.md - 用户要边聊边写、上下文不完整，或正在更新已有文档：
references/collaboration-workflow.md - 涉及边界、运行、状态、数据或排期：
references/diagram-guidance.md；它继续路由图型画法、视觉设计和成图样例 - 用数字论证性能、容量、稳定性或成本：
references/data-charts.md - 确认交付载体、跨平台搬运或工具缺失：
references/portable-delivery.md - 高风险方案、正式评审、可实施性判断：
references/quality-gates.md - 使用团队模板：
references/template-adaptation.md - 需要机器校验或状态流转：
scripts/engineering_docs.py
相对路径均以本技能目录为根。不要把所有参考文件默认读一遍。
核心原则
- 先证据，后结论。 关键事实要能回到代码、配置、接口、运行结果、有效文档或用户确认。
- 问题先于方案。 “引入某技术”不是问题描述。
- 分清事实、推导、假设、决定和待确认项。 正文不用逐句贴标签，但不能把推断写成事实。
- 有真实选择才比较。 方案唯一时说明哪些约束排除了其他路径，不凑陪跑方案。
- 决定要写代价。 同时说明什么条件变化后需要重审。
- 风险决定深度。 局部改动保持轻量；资金、鉴权、数据写入、隐私和核心稳定性使用严格验证。
- 图也是规格。 图中的元素、方向、状态和排期必须与正文和事实一致。
- 正文只保留最少的充分信息。 代码、接口全集和原始调研放附录或权威链接。
- 内部过程不外露。 证据账本、门禁编号、共创步骤、评测文件和生成过程默认不进入正文。
- 技能不替人批准决定。 决定责任人接受方案，事实源负责人关闭事实争议。
统一工作流
先确认任务
在内部确认：
谁要读，读完要作出什么决定或完成什么动作，本文依据什么，覆盖什么范围。
同时判断当前模式：
| 模式 | 处理方式 |
|---|---|
| 新建 | 从上下文和证据形成文档 |
| 更新 | 通读全文和图表，再按新事实修正受影响部分 |
| 评审 | 对照事实、取舍、风险和交付条件指出问题 |
| 模板适配 | 先形成技术判断，再映射团队模板 |
收集上下文
先读取用户已经给出的文件、链接、代码、配置、接口、日志和历史决定。能自行确认的内容不要再问用户。
只追问会改变核心决定的缺口，一次问最少的问题，并给出候选或当前默认假设，方便用户短答。
缺少会改变工程取舍的外部依据时可复用 outside-view；当前材料足够时直接执行。
用户希望共创，或背景复杂、方案分歧较大时，按 collaboration-workflow.md 逐步推进。上下文已经充分时直接起草，不先举行一轮固定问答。
建立工程判断
用下面的顺序检查完整性：
text事实与现状 → 问题 → 目标、边界和约束 → 候选方案 → 决定与代价 → 落地设计 → 影响与风险 → 验证、发布和回退 → 未决问题
这只是内部判断顺序，不是正文目录。完整模型和生命周期见 decision-model.md。
关键事实冲突时不自行挑选。缺口会改变核心链路、数据归属、方案选择、安全边界或上线方式时，文档保持草案；其他缺口可以作为假设继续，但要写清影响。
选择协作深度
- 默认直写：上下文足够，直接完成全文并交用户评审。
- 轻量对齐：只有一两个决定不清时，先问最少问题再写。
- 分段共创：用户明确希望共同推敲，或核心决定尚未收敛时，从未知最多的部分开始逐段迭代。
不要默认要求用户选择模式，也不要每节固定脑暴 5 至 20 个选项。真实存在方案空间时才给候选。
组织正文
先列读者真正会问的问题，再决定章节。常见阅读顺序是：
text建议做什么，为什么 当前问题和关键约束 具体怎么做 主要影响、风险和依赖 怎么验证、发布和回退 仍需谁确认什么
不是每一项都要单独成节：
- 目标或验收口径需要评审时才单列。
- 边界容易误解时写清，但不默认创建“非目标”章节。
- 有真实候选时才展开方案比较。
- 高风险时展开控制措施；低风险改动只保留必要影响和验证。
- 没有待确认项就删除该节。
标题直接表达判断或对象，不使用可套在任何文档上的空标题。摘要让读者在三十秒内知道建议、依据、代价和阻塞项。
更新已有文档
先通读全文、图表和附录，概括每节承担的判断，再确定新事实影响哪些结论和下游章节。
只改必要部分，但收口前回看全文：
- 是否出现前后矛盾或旧结论残留。
- 图、正文、接口和术语是否仍一致。
- 是否重复解释同一事实。
- 已决定或已实施的内容是否需要进入待复核，而不是静默覆盖。
设计必要的图
只有文字或小表格难以稳定表达关系、时间或数据差异时才画图。先确定问题和载体，再建立语义或数据映射。图型和验收见 references/diagram-guidance.md；正式成图读取 references/visual-design.md，按需参考 references/diagram-recipes.md 与 assets/visual-examples/README.md。复杂控制流程再读 references/process-modeling.md。
每张图都要：
- 回答一个明确问题，保持一个抽象层和一种状态。
- 使用有事实依据的实体、关系和方向。
- 放在对应判断附近，图前说明问题，图后给出结论。
- 保留可编辑图源，参考图和模板只借布局，不能改变技术关系。
- 在实际交付载体渲染，检查文字、箭头、连线、裁切与可读性；修改已有图后复核关系是否丢失。
- 定量图用标准绘图库计算位置与比例，附数据口径；示例数字不得冒充真实证据。
本地可用 Mermaid、PlantUML、SVG 等开放格式完成。可用的 MindAI 或其他绘图器接收同一份语义；在线画板只在需要时承担发布与协作，不能成为成文和画图的前置门槛。工具选择、权限失败和兼容性处理见 portable-delivery.md。
做质量检查
轻量和普通草案先检查：
- 关键事实是否可信。
- 建议和代价是否讲得通。
- 实施边界是否清楚。
- 必要关系是否需要图。
- 验证和回退是否足够。
- 正文是否重复或泄漏内部过程。
高风险方案、正式评审或“可实施”状态再执行 quality-gates.md 的完整门禁。完整门禁是严格模式，不是每次写文档的默认流程。
做独立读者测试
把文档交给没有参与讨论的人或干净上下文，只提供文档，让他回答：
- 问题和关键证据是什么。
- 建议做什么，为什么。
- 边界和接受的代价是什么。
- 具体改哪里，风险和依赖是什么。
- 如何验收，失败后如何恢复。
五项都能从文档中准确回答才算可理解。读者测试不替代技术事实核验。
最后清洗和交付
锁定事实、术语、数字、关系和决定后，再做中文清洗。不得为了顺口改变技术含义和判断强度。
默认交付：
- 技术文档正文。
- 当前状态。
- 会影响实施的待确认项。
- 必要的证据、图源、预览和适用版本；附件使用相对引用随正文交付。
只有用户明确要求审计、严格验收或排查技能行为时，才展开结构化决策记录和完整门禁报告。
可执行工具
scripts/engineering_docs.py 提供：
init：生成正文支架和结构化决策记录。validate：检查结构、状态、风险控制、图示登记和读者测试。transition：在草案、待评审、已决定、可实施、已实施、待复核、未采纳和被取代之间合法流转。
这些工具是严格模式的可选能力。普通技术文档无需先创建 JSON，也无需为了使用技能而运行脚本。
