oss-workflow：路由层（唯一入口）v3
0. 触发自检与四层分型
你在处理任何涉及 GitHub 协作的任务之前，必须已完成本节自检。
自检三问：
1. 这个任务会往 GitHub 推送任何东西吗？（PR/commit/push/issue 回复）
2. 这个任务会修改仓库的任何文档吗？（README/CHANGELOG/CONTRIBUTING/docs）
3. 这个任务涉及开源仓的任何协作动作吗？（fork/star/comment/review）
任何一个「是」→ 你现在正在读的应该是 oss-workflow，而不是自己动手。
如果你已经动手了 → 停下，从 §1 开始。
为什么强制：S2 实战教训（dsh-market#755, 2026-09-28）——agent 绕过 skill 直接干活，导致：AI 标识加错、正文语言错、markdown 被 PowerShell 反引号吃掉、未审直推。四错全部因为「会修 issue」的模式匹配优先了「该读 skill」的规则查找。skill 躺在目录里不会自己跑——本 skill 的职责就是把它们摊开在你面前。
四层分型（v3 重组契约，诊断依据见套件 corpus/org-sweep/drafts/ARCH-AUDIT.md）：
| 层 | 成员 | 职责 |
|---|---|---|
| 路由层 | oss-workflow（本 skill） | 唯一入口；唯一持有场景触发词；生成并追踪 CHECKLIST |
| 管线层 | oss-contribution（唯一管线 owner）+ oss-dev（P4–P6 实现段规则附件） | P0–P9 流程、门禁、证据 ID |
| 规则层 | oss-voice（文档风格，§7 多语言管理——原 oss-i18n）、oss-persona（声纹库；lyingbug 全卡为 references 参照数据） | 领域规则与声纹数据 |
| 独立层 | penguin-oss-ops、oss-security、oss-scaffold | 方法论/安全/建仓，各自独立触发、自带负向边界 |
场景触发词只在路由层；其余层被调度时才读。原 oss-i18n、lyingbug 两个独立 skill 已分别并入 oss-voice §7 与 oss-persona references（v0.2.1 重组）。
1. 场景识别与清单生成
识别任务属于哪个场景，然后立即生成任务清单：
| 场景 | 触发信号 | 清单模板 |
|---|---|---|
| S1 梳理 | 「帮我梳理这个仓库」「看看这个项目」 | references/checklists/s1.md |
| S2 提 PR / 修 bug | 「处理 issue」「提 PR」「修 bug」「fix」 | references/checklists/s2.md |
| S3 文档维护 | 「更新 README」「改 CHANGELOG」「文档整理」 | references/checklists/s3.md |
| S4 长期协作 | 「同步 fork」「跟进上游」「定期维护」 | references/checklists/s4.md |
| S5 建仓 | 「从 0 建仓」「新项目」「scaffold」「初始化」 | references/checklists/s5.md |
清单生成动作（确定性，非可选）：
1. 在工作区创建 .oss-task/<任务ID>/CHECKLIST.md（任务ID = issue 号或日期+关键词）
2. 从对应模板复制 + 填入任务特定信息（目标仓 URL、issue 号、分支名）
3. 清单文件创建后，本 skill 的工作就是追踪它——每完成一步打勾，每步的 gate 不过就停
**时序与证据约束（2026-09-29 #752 实战教训）**：
- 清单必须在**首个业务动作之前**实例化——先有清单再干活，不是干完活补清单
- 每步打勾必须带证据指针（命令输出摘要 / 文件路径 / PR 链接），无证据不打勾
- 一次落盘全部 [x] = 事后补勾 = 违规交付，等同跳步
- 勾了没做 = 比晚勾更重的违规（2026-09-29 三场实测：勾「读 oss-dev §4」但全程零读取）——真实性优先于时序
2. 执行规则
2.1 主 agent 执行（简单任务）
- 逐项执行 checklist，每步先读该步标注的 skill 文件路径的相关章节（不是全文，按需读）
- 打勾：把
- [ ]改为- [x]，同轮写入 - Gate 步骤（标有 🛑 的）必须停下来等作者确认，不能自行通过
2.2 子代理执行（复杂任务）
委派子代理时，prompt 只包含三样东西：
1. 任务描述（一段话）
2. Checklist 路径（.oss-task/<ID>/CHECKLIST.md）
3. 指令：「按 checklist 逐步执行。每步标注的 skill 文件路径必须实际读取相关章节再行动。每步完成后打勾。Gate 步骤（🛑）停下来在返回中说明等待确认。」
禁止：主 agent 把 skill 规则摘要后塞进子代理 prompt——转述会丢细节（#755 的 AI 标识就是这么丢的）。子代理自己读一手规则。
2.3 完成判定
Checklist 全部打勾 → 交付报告（含 checklist 文件路径供审计）。 有任何未打勾项 → 列出哪步卡住 + 原因，不算完成。
3. 依赖（分级账本：核心缺失硬停，推荐缺失警告继续）
3.1 分级原则
- 核心必装：缺失 → 硬停，先安装再启动任务，不降级。
- 流程必装：对应场景缺失 → 该场景硬停；其他场景不受影响。
- 推荐：缺失 → 警告并继续，交付物标注降级（如「未过 humanizer 润色」），与 oss-contribution「降级不是惩罚，是准确交付」的口径对齐。oss-contribution 侧红线（R13/R15/R16）与其 §8.2 强制降级表仍按其管线裁决。
- 可选：缺失正常继续，用到对应场景时再提示。
3.2 依赖账本
| 依赖 | 级别 | 用途 | 需要 API Key | 检查方式 |
|---|---|---|---|---|
| superpowers（systematic-debugging 等） | 核心必装 | P4–P6 代码侧工程门禁 | 不需要 | skill 目录存在 |
| ocr CLI | 核心必装 | P7 确定性缺陷检测 | 需要：OPENAI_API_KEY 或 ANTHROPIC_API_KEY | ocr --version + 环境变量在位 |
| github-contributor | 流程必装（S2 非中文/非自有仓） | 英文仓 PR 交付接管 | 不需要 | skill 目录存在 |
| khazix-writer | 流程必装（S2 提 PR） | R15：PR 正文必须过其复审（必选 ≠ 必须采用其文风） | 不需要 | skill 目录存在 |
| humanizer + zh-tech-writing | 文档推荐（S3/S5；对应 R13/R16） | 润色链：去 AI 腔 + 中文句式定稿 | 不需要 | skill 目录存在 |
| vitepress | 建仓推荐（S5 重档文档站） | 文档站生成 | 不需要 | skill 目录存在 |
| firecrawl 系列 | 可选（调研/抓取场景） | 联网调研、语料抓取 | 可选：FIRECRAWL_API_KEY（无 key 走免费额度） | skill 目录存在 |
3.3 搜索引擎能力矩阵（本机实测 2026-09-28，13 引擎全通）
| 引擎 | 本机状态 | 适用场景 | 需要环境变量 |
|---|---|---|---|
| bing（默认） | ✅ 免费 | 通用搜索、快速事实核查 | 不需要 |
| exa | ✅ 付费 | 语义搜索（找相似内容/代码） | EXA_API_KEY |
| tavily | ✅ 付费 | AI 优化搜索（综述/调研） | TAVILY_API_KEY |
| keenable | ✅ 付费 | 精准网页检索 | KEENABLE_API_KEY |
| firecrawl | ✅ 付费 | 网页正文提取/站点抓取 | FIRECRAWL_API_KEY |
| deepseek-official | ✅ 付费 | 中文技术搜索 | DEEPSEEK_API_KEY |
| baidu | ✅ 付费 | 中文搜索（国内生态覆盖强） | BAIDU_API_KEY |
| kimi | ✅ 付费 | 长上下文搜索 | MOONSHOT_API_KEY |
| aliyun | ✅ 付费 | 通义生态搜索 | DASHSCOPE_API_KEY |
| ddg / ddg-lite | ✅ 免费 | 隐私搜索、国际内容 | 不需要 |
| anysearch / parallel | ✅ 免费 | 聚合搜索 | 不需要 |
场景 → 引擎选型：
| 场景 | 首选引擎 | 理由 |
|---|---|---|
| S1 梳理（仓库调研） | multi_search（exa + tavily + bing） | 跨源验证仓库信息 |
| S2 修 bug（上游复现搜索） | deepseek-official + bing | 中文技术报错搜索最强 |
| S3 文档（API/规范查证） | keenable + exa | 精准技术文档检索 |
| 生态对标（oz-skills 类） | multi_search（tavily + baidu + bing） | 国内外开源生态双覆盖 |
| 语料补抓（readme-real 类） | firecrawl | 网页正文提取+批量 |
| GitHub 代码/仓库搜索 | platform_search(github) | 专用通道非通用搜索 |
引擎不可用时自动降级到免费引擎（bing/ddg），搜索层永不硬停。
4. 各场景调度关系
| 场景 | 调用的实质 skill | 各管什么 |
|---|---|---|
| S1 | oss-contribution §P0 探针 + oss-voice §1 语言分布 + archify（代码地图） | 仓库解剖五件套（功能价值/archify 代码地图/请求生命周期/核心抽象/真实执行跟踪，2026-09-29 用户定标） |
| S2 | oss-contribution 全管线 P0–P9（P4–P6 实现段用 oss-dev）+ oss-dev §3-4 + oss-security §2 + khazix-writer（R15） | PR 交付（本 skill 只管调度和清单） |
| S3 | oss-voice 全部（§7 多语言同步）+ humanizer/zh-tech-writing | 文档产出 |
| S4 | oss-contribution §P9 + oss-persona 声纹（WeKnora 侧加 references/lyingbug-voiceprint.md） | 维护者侧回应 |
| S5 | oss-scaffold 全部 + oss-voice（含 §7 多语言命名）+ oss-persona | 建仓全组件 |
调度 ≠ 摘要：本 skill 只告诉每步去读哪个文件的哪一节，不复制其内容；checklist 条目同样只留步骤 + 指针，规则语义一律活在规则源（单一真相，防双源冲突）。子代理/主 agent 到那步就去读。
5. 审计
每个任务的 CHECKLIST.md 留在 .oss-task/ 目录，事后可审计：
- 哪些步骤被跳过（未打勾）
- Gate 步骤的确认记录
- 交付与清单的对照
这是套件从「知识文档」变成「执行系统」的证据链。