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 纪律
- ❌ **无证据的模块树**——凭产品类型套一棵漂亮的树，与手上资料对不上