requirement-archiving

name	requirement-archiving
description	历史需求资产归档入库：把项目外的原始需求资料（TAPD 单 / 飞书导出 docx / xls 清单 / 截图原型等异构收料）重整为 modules/ 体系下的现状基线 PRD + shared 事实源 + 溯源台账。九段流水线（Phase 0-8）：收料冻结 → 通读建模 → 方案拍板 → 骨架与 shared → PRD 回填 → 反向对账 → 原型校准 → 关联收口 → 审查清源。
when_to_use	- 用户提供一批历史需求原始资料（本地文件夹 / 网盘导出），要求「归档 / 入库 / 整理成 PRD」时； - 为已上线的生产功能补建 modules/ 需求事实源（现状基线形态）时； - 新建 basic / sub 模块并批量回填历史需求时。 边界：项目内已有 specs/ 下 md 的一次性搬迁 → migrate-to-modules；写全新需求 → prd-writer； 从代码反解实现现状 → code-to-doc。本 skill 只管「外部异构原始资料 → 需求事实源」。
user-invocable	true
allowed-tools	["Read","Write","Edit","Glob","Grep","Bash","AskUserQuestion"]

Requirement Archiving 历史需求归档 Skill

前置依赖

• skill: document-norms §1（归属矩阵）/ §2（frontmatter 与时间戳）/ §3（overview 三段制）/ §11（写作纪律 + 交付前自查）
• 项目 PRD 框架 .claude/skills/prd-style/SKILL.md（章节结构 / 各章写法 / 标注习惯的项目层事实源，装机放入；缺失时 fallback 读 core templates/project-skills/prd-style/SKILL.md——与 prd-writer 同机制）+ prd-writer writing-guide.md（通用写作纪律）
• skill: module-init（建骨架）与 module-index-refresh（索引刷新）——作为被调用件，不重复其职责
• skill: html-demo（Phase 6 原型校准的执行引擎，有 UI 的需求才需加载）
• projects/specs/_meta/taxonomy.md（tags 受控词表，如项目维护；缺失时 check_archive 自动跳过词表检查）
• 环境依赖（仅 Phase 0 收料脚本）：docx / PDF / xls 解析需 6 个 Python 库，一次安装： pip install python-docx pdfplumber pypdfium2 openpyxl xlrd Pillow 缺库不中断收料——对应格式文件在 inventory 备注标「缺哪个库怎么装」，装完重跑即可

定位

外部异构原始资料 → modules/ 需求事实源 的唯一工作流。三个近亲的分工：

skill	输入	本 skill 的关系
migrate-to-modules	项目内已有的 specs/ md	不重叠——那是搬迁，这是重建
prd-writer	新需求共识	复用其写作规范；工作流不同（归档无「澄清需求」阶段，只有「对账原文」）
code-to-doc	代码仓	互补——本 skill 建意图基线，code-to-doc 建实现现状

核心形态约定：已上线需求写成现状基线（frontmatter status: shipped、验收标准章改为「现状口径（回归参照）」checkbox）；未开发需求写成规划稿（draft）。PRD 正文只写当前生效的规格——废弃方案不进正文，过程性中间记录用完即删。

九段工作流（Phase 0-8）

0 收料冻结 → 1 通读建模 → 2 方案拍板 → 3 骨架与shared → 4 PRD回填 → 5 反向对账 → 6 原型校准 → 7 关联收口 → 8 审查清源

每阶段有门禁，过不了不进下一阶段。

Phase 0 收料冻结

• 跑 scripts/extract_assets.py <源目录> <工作目录> 产出：文件清单、模态矩阵（文字/图片/表格/外链/二进制）、逐文件正文、全部内嵌图片（无损）、外链清单
• <工作目录> = 项目临时加工区 tmp/req-archive-<slug>/（不进 git）。它只是中转：Phase 4 回填时把选用图片从工作目录归位到资产包 assets/，Phase 8 审查清源后随任务清理工作目录
• 识别不可转写资产（.rp 原型、二进制模板等）与源内容已丢失项（如「点击图片查看完整表格」占位但无图）
• 门禁：丢失内容与可补外链第一时间问用户能否补源；原件处置方案（哪些归档哪些可删）此时初判，不在模态盘点前拍板删除

Phase 1 通读建模

• 通读全部正文提取；重建需求树（父子单、空壳单）与时间线
• 信源质量分级：同一内容多信源（如 TAPD PDF 压缩图 vs 原 docx 高清图）时登记配对，取最高质量源，低清版只做佐证
• 识别横切字典类内容（编码表 / 状态映射 / 语言口径）→ 预定为 shared 事实源
• 门禁：每份文件读过；高低清信源配对完成

Phase 2 方案拍板

• basic/sub 定位：对照常见 4 种切分范式（按能力面 / 按系统运行环节 / 与生产子系统 1:1 / 按能力链分层）选型
• 产出「文档 → 落点」映射表，每份原文标三类处理之一：整合出 PRD / 并入所属 PRD 变更历史（小优化单）/ 拆分并入多处（跨落点单）
• 汇总第一批口径冲突清单（新旧版本打架、图文不一致）
• PRD 框架依据一并进集中拍板：产出 PRD 默认按项目 prd-style；项目存量 PRD 风格趋同（≥3 份）而 prd-style 仍是出厂默认版时，提议先走 prd-writer §风格定制与萃取再回填
• 门禁：映射表 + 原件处置方案 + 冲突清单经 AskUserQuestion 集中拍板；不散落在写作过程中零碎问

Phase 3 骨架与 shared

• 走 module-init 建 basic / sub / 需求资产包（批量时可自写简单循环调用——框架不提供现成批量脚本；占位符替换与 meta 状态必须逐一落实）
• shared 事实源先行：编码字典 / 全局认知 / 需求台账（含 TAPD ID × 上线版本 × 归档落点的溯源表）——PRD 引用它们，不重复枚举
• 填各层 overview 人写段与 frontmatter description，调 module-index-refresh
• 门禁：占位符零残留；索引连跑两次幂等；description ≤200 字

Phase 4 PRD 回填

• 分批（按 sub，体量大的先），每批落盘后跑 scripts/check_archive.py <模块路径> 自查
• 图片按质量分级归位进各需求包 assets/，图中规格必须转写进正文（图是证据，不是正文的替代）
• 拍板结论直接写为需求事实；被覆盖的旧口径进「变更与决策记录」表
• 门禁：自查零异常（frontmatter / tags 词表 / 禁用标签 / 断链断图 / AI 病灶）

Phase 5 反向对账（最容易被省略、也最容易翻车的一步）

• 源→目标覆盖矩阵：源文档每一章节、每一张图逐条判定「已转写 / 并入变更史 / 弃用+理由」，不允许存在无落点也无弃用理由的源内容
• 图片评估必须 100% 留痕——看过多少张就是多少张，不许在记录里写「全量」实际抽样
• 外链清单逐条判定覆盖性（已覆盖 / 未覆盖需导出 / 放弃），未覆盖项写进台账「删源前知情项」
• 对账中暴露的新冲突 → 二次拍板 → 按变更三步融入正文
• 门禁：覆盖矩阵无空洞；新冲突全部拍板闭环

Phase 6 原型校准（有 UI 的需求必做）

归档产物是「文档说应该怎样」，线上是「实际怎样」。用截图建仿真 demo 是把两者对上的唯一有效手段——某次 16 份 PRD 的归档实战中，这一步校准出 30 处偏差：既有文档写了但线上没做的（已停用页签的专属列），也有线上做了但文档全无记载的（列表刷新入口、步骤区可折叠、已关闭项仍可启用）。

• 按页面单元分批，一次一个单元：列清单要图 → 收图 → 出差异清单 → 建 demo → 用户确认 → 归档 prototypes/ + 同步 PRD。不要攒到最后一起做，差异会淹没在批量里
• 要图清单要写明「怎么截」和「验证什么」，并明确要求悬浮态、展开态、空态；线上取不到的状态（如无命中数据）改用 demo 的模拟开关按 PRD 补齐
• demo 走 html-demo skill 口径：自包含单文件、复刻截图视觉、全状态可达、落 tmp/ 就地迭代、拍板后归档 prototypes/index.html 并删 tmp 原件
• 差异三分类：① 线上口径明确的 → 直接改 PRD；② 图文冲突 → AskUserQuestion 拍板；③ 疑似线上缺陷 → 先问用户确认是不是缺陷，再决定 demo 复刻现状还是呈现合理行为
• 一份 demo 可被多份 PRD 共用（如同一配置区页面同时覆盖 4 份 PRD），在各 PRD 关联资产互相指明
• PRD 补一句分工声明：视觉与控件行为以原型为准，正文只写影响开发逻辑的规则
• 门禁：每个单元的差异清单都经用户确认；原型已归档且 PRD 关联资产已指向

Phase 7 关联收口

• 跨模块双向回写：本模块 module.yaml 声明依赖之外，被依赖方的 module.yaml / overview 也要反向登记（遵循 scope 最小化，仅回写直接相关方）
• 代码在外部仓的模块：submodule.yaml sync_method: dev-paste + 注释说明，避免 stale 巡检误报
• 跑 doc-graph-health 全库巡检，确认本模块零断链零孤儿
• 写 projects/changelog.md；遗留待确认项建 board task（走 task-management 口径）
• 门禁：巡检通过；changelog 与 board 落账

Phase 8 审查清源

• 收料来自当前项目之外时，本阶段整段不适用——源目录只读，不删不动不写。典型场景：用户 新建项目后把老项目 / 网盘导出目录喂进来分析，那是他仍在使用的资料，动它一个字都是越界。 这种情况下台账即交付物，Phase 8 只做「确认产出完整」不做清源
• 用户审查全部产出后，单独二次确认才删原件
• 删除前：grep 引用清零 + 不可替代资产复核（已归档 shared/assets/原始资料/）+ 台账「外链知情项」再提示一次
• 删除后：台账成为唯一溯源
• 原件不是只有删/不删两态——第三态是「保留但不再维护」（归 <sub>/others/ 或留原位）。 选它必须当场定主次：原件标注「原始资料，不再维护，事实源见 <产出路径>」，台账同步记一行。 不标的话就是两份同主题内容并存，半年后漂开了没人知道该信哪份——比删错更难查

脚本

脚本	用法（插件根从 plugin-root.txt 取，不依赖 PATH）	产出
scripts/extract_assets.py	python "$(cat .claude/workframe-state/plugin-root.txt)/skills/requirement-archiving/scripts/extract_assets.py" <源目录> <工作目录>	inventory.md 模态矩阵 / text/ 逐文件正文 / images/ 无损图片 / links.md 外链清单
scripts/check_archive.py	python "$(cat .claude/workframe-state/plugin-root.txt)/skills/requirement-archiving/scripts/check_archive.py" <projects/modules/<basic>>	终端报告：frontmatter、tags 词表（无 taxonomy 自动跳过）、禁用标签、AI 病灶、wikilink 与图片断链、孤儿图、AUTO-INDEX 配对

索引刷新不在本 skill 脚本内——调 core module-index-refresh，避免双实现。

质量自检

• Phase 0 模态矩阵先于任何删除决策
• 同内容多信源取最高质量版（PDF 内嵌图用原始位图提取，禁「渲染页面放大裁切」——插值放大只会更糊）
• 低清图不作为改动原文口径的依据（硬约束）：从压缩截图读出的数字 / 字段名 / 按钮文案与原始需求文档不一致时，默认原文正确，只在「待确认项」标存疑；仅当拿到高清源或用户口头确认后才可改写正文
• 已上线需求 = 现状基线形态；正文无废弃方案、无归档过程元记录
• 小优化单并入变更历史，不单独建包；「跨页面改动集合」不是功能模块，拆分并入
• Phase 5 覆盖矩阵含全部图片的逐张判定记录
• 外链清单已产出且未覆盖项经用户知情
• 跨模块关联为双向
• 删源走 Phase 8 双确认，不可转写资产已实体归档

反模式（实战实证）

• ❌ 只提取文字就开写 PRD——归档实战首轮 145 张图零评估，阈值表、关闭原因枚举、分期规划全在图里，靠用户质疑才补
• ❌ 渲染放大代替原始位图提取——700px 源图放大到 1206px 反而更糊，且导致把「7 天」误读成「30 天」、虚报了一条图文冲突
• ❌ 拿低清图当权威去改事实源——归档实战三次踩中：「7 天」被误读成「30 天」；带前缀的术语被误删前缀（「XX服务器」→「服务器」）；按钮文案的全角加号被误改（「＋添加XX比例」→「+ 添加比例」），三处高清截图证实需求文档原文全对。低清图只能提出存疑，不能改写口径
• ❌ 删除决策先于模态盘点——先拍「原件全删」，后发现 .rp 原型不可转写又推翻重议
• ❌ 只有正向映射、没有反向对账——主文档 §2.4 评审问题记录（8 条）无任何落点，Phase 5 缺失导致的真实遗漏
• ❌ 跨模块关联只写单向——本模块声明了依赖，被依赖方无反向登记，知识网成了单行道
• ❌ 过程记录混进事实源——归档期的口径对账表遗留在 shared 文档里（用户明确要求：中间记录用完即删）
• ❌ 覆盖记录夸大——changelog 写「145 张逐张评估」实际约 35 张；看了多少写多少
• ❌ 外链内容不清点就删源——链接背后的技术文档可能是唯一事实源

与其他 skill 的衔接

• module-init / module-index-refresh：Phase 3 的建骨架与索引（必调）
• 项目 prd-style + prd-writer writing-guide：Phase 4 的写作口径（前置加载）
• document-norms §11.4：每批 PRD 落盘前自查（脚本覆盖不了的语义项）
• html-demo：Phase 6 仿真 demo 的生成与归档规范（本 skill 只管什么时候做、按什么单元切、差异怎么分类）
• doc-graph-health：Phase 7 收口巡检
• task-management：遗留待确认项落 board
• code-to-doc：归档完成后按需反解 current-state（外部仓走 dev-paste）