material-intake

name	material-intake
description	存量资料的盘点、分流与结构推荐。扫描给定路径产出资料台账（形态 × 数量 × 覆盖率），按资料形态判定每一批的去向（migrate-to-modules / requirement-archiving / code-to-doc / 手动放置），并从资料聚类推荐 basic/sub 模块树。只出计划不做搬运，重型执行交给对应 skill。
when_to_use	接入存量项目、需要先摸清「手上这些资料该怎么进来」时； 项目内后续又攒了一批新资料（导出的文档、历史需求包、别人给的目录）需要判定去向时； 拿不准某批资料该走 migrate-to-modules 还是 requirement-archiving 时。 不适用：单篇新文档写作（走 prd-writer）、已确定去向的批量搬运（直接调对应执行 skill）。
user-invocable	true
allowed-tools	["Read","Write","Glob","Grep","Bash","AskUserQuestion"]

存量资料入库分流

前置依赖

调用前需读 skill: document-norms §1（归属矩阵）——分流判定的落点依据以其为准，本 skill 不另立一套归属规则。

定位

面对一堆来源混杂、形态不一的存量资料，先摸清楚、再定去向、最后才动手。本 skill 只做前两件事加一个结构提议，不搬运、不改写、不归档。

三段能力：

段	做什么	产出
盘点	扫描给定路径，按形态分类计数，标出无法解析的项	资料台账
分流	按形态逐批判定去向	分流计划（每批 → 哪个 skill）
结构推荐	从资料聚类推荐 basic/sub 模块树	模块树初稿 + 证据

两个调用场景

场景	谁调	执行深度
接入 / 新建时（含 A 路径引参考资料）	workframe-launcher 的 setup skill（读本 SOP 照做）	本 skill 产出计划（盘点 + 分流 + 结构提议 + 处置方案）进结构闸；确认后的执行层层递进：结构闸拍树 → launcher 建树 → 逐模块深读后确认并当场安置，整理归档按节奏闸拍板
接入之后项目内补料	用户直接调用	同样只出计划；用户确认后调对应执行 skill 当场执行

本 skill 始终只出计划——执行是调用方的事。装机会话的执行能力由 module_init.py （确定性建树）+ 磁盘可读的各执行 skill SOP 保障，不再有「接入阶段撞上半成品环境」的限制。

Phase 1 盘点

1.0 两级盘点（2026-08-11 起，防「一次深读全部」拖垮体验）

级	深度	何时	供给
粗扫	形态计数 + 标题级抽样（md 读 H1/H2、docx 读标题与首段、xlsx 读表头），不逐字读全文	接入 / 新建流程的分析阶段	台账 + 模块树提议（结构闸）
深读	逐份读懂内容	建树后逐模块进行	该模块的安置 + 处置方案（逐模块小闸）

台账在粗扫级即须 100% 全覆盖（每份文件有一行——覆盖指「登记过」，不指「读完了」）； 深读按模块分批推进，不要求一次读完全部。

1.1 收料冻结

先划定范围并冻结：列出所有待盘点路径，之后新增的资料算下一批，不中途扩范围。范围内的每一份文件都必须在台账里有一行——不许因为「看着不重要」就跳过，判定为「不入库」也要写明理由。

每条路径必须标注在项目内还是项目外（内 / 外）——这一位决定下游是「搬」还是「拷」，见 §2.1。

1.2 按形态分类

形态	识别方式
规范 / 半规范 md	.md，有 H1、章节结构或 frontmatter
零散 md / txt	.md / .txt，无结构
异构原料	.docx / .xls(x) / .pdf / 截图 / 原型文件
在线文档链接	正文里的飞书 / Notion / 网页 URL，本地无副本
源码	按脚手架识别（package.json / pom.xml / requirements.txt 等）
无法解析	二进制、加密、损坏，或缺解析库

1.3 台账

资料台账（范围：<冻结的路径清单>，冻结于 <时间>）

| # | 路径 | 源位置 | 形态 | 数量 | 备注 |
|---|---|---|---|---|---|
| 1 | docs/ | 内 | 规范 md | 43 | 有 frontmatter 的 12 份 |
| 2 | 需求归档/ | 内 | 异构原料 | 31 | docx 18 / xls 7 / 截图 6 |
| 3 | D:/老项目/specs/ | 外 | 规范 md | 20 | 跨项目导入，只拷不删 |
...

覆盖率：已分类 <N> / 总数 <M>；无法解析 <K>（原因逐条列出）

缺解析库不中断盘点：对应文件在台账标注「缺哪个库、怎么装」，装完重跑即可。

Phase 2 分流

2.1 搬还是拷（先定这一位，再谈去向）

去向按资料形态判（下表）；动作按源位置判：

源位置	动作	对源目录
项目内	搬（迁完源即消失）	可删，按各执行 skill 自己的删源 SOP
项目外	拷（源原封不动保留）	只读——禁止任何写、移动、删除

跨项目导入（典型场景：用户走 A 路径新建项目，把老项目的资料喂进来分析）必须走「拷」： 那是用户仍在使用的仓库，动它一个字都是越界。分流计划里逐批写明动作，下游 skill 照此执行。

2.2 去向判定

按资料形态判定，与源位置无关：

资料形态	去向	说明
已是规范 / 半规范 md（项目内或外部文件夹皆可）	migrate-to-modules	AI 聚类推荐模块树 + dry-run review + frontmatter 自动补全；杂项可留 specs/plans/ 或 _legacy/
docx / xls / PDF / 截图 / 原型等异构原料	requirement-archiving	需求资产专用，产出现状基线 PRD；需 6 个 Python 解析库
在线文档（飞书 / Notion / 网页）	先导出再分流	文档导出 md/docx；网页可用 Obsidian Web Clipper 零 API 存 md。导出后按上两行判定
单篇 / 零散、非需求类知识	手动放置，按 document-norms §1 定归属	不硬套 PRD 形态；量大时先聚类再决定是否值得建模块
源码	code-to-doc	配 submodule.yaml.code_paths 后反解出 current-state/
判定为不入库	—	台账写明理由（过期 / 重复 / 与本项目无关）

边界：migrate-to-modules 是搬家（结构重整），requirement-archiving 是知识工程（异构原料重建为现状基线），两者不重复。拿不准时看原料形态：已经是成文档的走搬家，需要人读懂再重写的走归档。

什么时候不必先过本 skill：资料形态单一且用户已经明确要做什么（「这批 docx 归档入库」「把 docs/ 收编进 modules」）——直接调对应执行 skill，本 skill 是为「混杂、拿不准」准备的，不做无谓拦路。

原件处置：给选项，不替用户决定

分流计划要连原件怎么办一起给。基础三档：归档到合适位置 / 留原位不动 / 删除。

同样三个词对两类资料含义不同——这是判断起点，不是模板：

• 已是成品的 md：归档 = 移动。文件本身就是产物，没有"源文件 vs 产出"之分
• 异构原料：归档 = 读懂后整理成正式文档（整理归档）。整理归档与原件处置是两件独立的事——整理完才轮到问原件归 <sub>/others/、留着、还是删

所以异构原料天然比 md 多一档（整理归档完成、原件处置押后）。按批给选项，该加档就加，别硬凑三选一。

五条边界，其余自由发挥：

1. 默认「留原位」——opt-in。用户没细看就点过去，代价该是"什么都没发生"
2. 删除单独成步、双确认，不与移动打包进同一选项。前置是"内容已被别处完全承载 + 引用清零"，不是"看着没用"（走 requirement-archiving Phase 8）
3. 不确定就不删：留原位 + 记待办，永远是安全出口
4. "整理归档后保留原件"必须定主次：原件标注「原始资料，不再维护」，事实源指向产出物。否则两份内容早晚漂开，没人知道该信哪份
5. 移动后收口引用：frontmatter related、正文 wikilink、相对路径资源引用（图片最常断）

时机：接入 / 新建流程里层层递进、当场执行（module_init.py 使装机建树可行后， 「问了执行不了」的前提不再成立）——结构闸只拍模块树（粗扫支撑）；安置与原件处置在 建树后的逐模块小闸深读后逐模块确认、当场执行；整理归档按用户在节奏闸拍的节奏 （当场连续做 / 接力 / 暂不做）。推迟的批次由接入方调 project_scaffold.mark_pending_work() 记录（含 pace），重启后 SessionStart 按 pace 接力或静默，doctor 的 init_completeness 常驻可见。项目内后续补料（第二种调用场景） 处置同样当场问——执行 skill 全部可用。

A 路径外部资料的档位变体：外部源只拷不动，「留原位」无意义，三档变为 拷入 + 整理归档 / 拷入存档不整理 / 不拷入（放弃项在台账写明理由）。

原料安置落点（整理归档前的物理位置，遵循既有约定不发明新位置）：单 sub 的原料 → <sub>/others/原始资料/<批次>/（分组进目录，避开「others/ 黑洞」反模式）；跨 sub 共用 → <basic>/shared/assets/原始资料/。整理归档完成后原件处置按上方五条边界执行。

Phase 3 结构推荐

从资料聚类推荐 basic / sub 模块树：

1. 读全部 md 的 H1 + frontmatter module / tags / area；有源码时并入目录结构信号
2. 聚类成候选 basic（产品线 / 大功能域）与其下 sub（相对独立的子系统）
3. 每个节点标出证据：哪些文件、哪段目录支撑这个切分——没有证据的节点不进推荐
4. 用业务语言命名，不用框架术语；框架概念首次出现必须带用户自己业务的例子

推荐是初稿不是定稿：交给用户确认与改名，不自行落盘。

产出物

一份计划，含三块：台账（Phase 1）+ 分流计划（Phase 2）+ 模块树初稿（Phase 3）。

• 被 launcher 调用时：三块进方案确认页，不写文件
• 项目内调用时：可写入 tmp/ 供后续执行参考，不写进 projects/

与其他 skill 的边界

skill	关系
migrate-to-modules	本 skill 判定「哪些走它」；它负责实际搬运（含自己的 dry-run 纪律）
requirement-archiving	本 skill 判定「哪些走它」；它负责九段归档（Phase 0-8）。本 skill 的收料冻结与全覆盖对账纪律借自它
code-to-doc	本 skill 判定「哪些源码值得反解」；它负责生成 current-state/
module-init	结构推荐经用户确认后，由它建实际骨架
document-norms	归属判定的事实源，本 skill 不另立规则

质量自检

• 范围已冻结，中途新增资料留作下一批
• 台账覆盖率 100%——范围内每份文件都有一行，判定不入库的也写了理由
• 无法解析项逐条列出原因（含缺库时的安装指引）
• 每批资料的去向都落到具体 skill，没有「再看看」这类悬空项
• 每批资料标了源位置与动作（内=搬 / 外=拷），项目外的批次已写明源目录只读
• 模块树每个节点都有证据支撑，命名用业务语言
• 全程只出计划，未搬运 / 未改写 / 未归档任何文件

反模式

• ❌ 抽样盘点——只看几个目录就下结论，剩下的「应该差不多」。覆盖率不到 100% 的台账等于没盘
• ❌ 按来源分流（项目内的走 A、外部的走 B）——判据是资料形态，不是它现在放在哪
• ❌ 顺手就搬——盘点时看到明显该搬的就动手，绕过用户确认与对应 skill 的 dry-run 纪律
• ❌ 无证据的模块树——凭产品类型套一棵漂亮的树，与手上资料对不上