> 完整主菜单与全局铁律见 `kb/kb.md`。以下为本菜单的执行细节（按需加载）。

> 📌 本菜单涉及文档抽取（A–F 循环），执行前请先读取 `kb/extraction.md` 获取 A–F 具体操作。

### 菜单 3 — 📋 互动扫描添加新文档

> 🔴🔴 **手工驱动模式（★ 铁律）**：此菜单全程由用户手动操作——用户选文件、用户确认处理、用户决定是否继续整理。**严禁在任何环节自动触发 maintain / crosslink / build-graph。** 即使用户一次性添加了全部未处理文档，A→F 全部完成后也只能回到"是否继续添加其他文档？"的询问。maintain 必须由用户通过菜单 6 或 7 手动启动。
>
> 🔴🔴 **抽取模式（B0）不适用本菜单（★ 设计性豁免）**：B0「顺序 vs 并行」二选一仅面向批量自动处理场景。本菜单为手工驱动模式，Step 3 明确「逐个执行 A→F」、天生顺序单线程；且「严禁自动 maintain」与并行子代理的「派发锚点 + 轮询门控」后台范式根本冲突。因此本菜单**锁定为顺序单线程、不向用户呈现 B0 二选一**——这是有明确理由的设计豁免，并非遗漏。若日后将本菜单扩展为"一次选多文件后无人值守批量处理"，则必须补回 B0 提问并改走菜单 2 流程。
>
> 🔍 扫描范围：递归扫描整个工作空间（跳过 AHKB 系统目录/隐藏目录/备份目录，排除根节点 .md 和知识地图 .html）。

#### 📥 Step 0 — 提示用户拷贝新文档（扫描前必做）

> 🔴 进入本菜单后、执行 `scan` **之前**，必须先用自然语言提示用户把新文档手工拷贝到工作目录：

> 📥 请先把要新增的文档**手工拷贝到当前知识库工作目录**（即 `scan` 扫描的根目录）里。拷贝完成后系统执行 `scan` 会**自动扫描到**这些新文件，**无需你手动指定路径**。放好后告诉我，我再扫描并列出让你挑选。

- 提示中应**明确给出当前工作目录的绝对路径**（通过 `get_workspace()` 解析后展示给用户），避免用户拷错位置。
- 若用户已完成拷贝、直接要求开始，则无需等待，立即进入 Step 1。

#### Step 1 — 扫描并列出新文档

```bash
python {skill_dir}/kb/scripts/ahkb.py scan
```

扫描结果包含三类文件：
- `new_files`（待处理）：全新未处理的文档
- `pending_files`（待定）：已提取 chunks 但未完成关联的文档（status: `chunked_not_finalized` / `extracted_not_processed`）
- `processed_files`（已完成）：已完全处理完毕的文档

同时从 `estimated_minutes` 读取并告知用户预计处理时间（`X ~ Y 分钟`）。

#### Step 2 — 🔴 用户选择要处理的文档（不可跳过）

**必须向用户展示所有待处理文件，等待用户选择后再处理。**

如有 `pending_files`，先展示：

```
⚠️ 检测到 M 个已提取但未完成关联的文件（chunks已生成，可直接执行关联）：
  P1. 📄 文档名.pptx — 原始文件/子目录/
  ...
  对这些文件，推荐选择「跳过重新提取，直接执行后续整理」。
```

再展示新文档：

```
检测到 N 个新文档：
  1. 📄 文档名.pptx（pptx · XXX KB）— 子目录名/
  2. 📄 文档名.docx（docx · XXX KB）— 子目录名/
  ...

请选择要处理的文档（可多选，逗号分隔如 1,3,P1；输入 a 全选；输入 0 跳过）：
```

> 🔴 **必须等待用户输入。不得在用户确认前处理任何文件。**
> 🔴 对于 `pending_files` 中的文件，默认跳过 A→F 提取（已有 chunks），直接 mark-processed 后进入关联阶段。
> ⚠️ 注意：`mark-processed` 有自动硬关卡检查——如该文件无对应知识元会被拒绝，此时需先执行 [C][D] 步骤。

#### Step 2.5 — 抽取要求确认（★ 2026-08-14 新增，可跳过；用户选中文档之后、开始抽取 chunk 之前）

> 🔴 **用户选定要处理的文档之后、开始逐个抽取 chunk 之前，必须询问用户对抽取是否还有其他要求**。用户的要求将注入抽取指导，**优先级最高**。

**① 询问**（🔴 自由文本输入，不是数字选项；严禁图形/卡片式选择菜单）：
```
📋 知识元抽取要求确认（可跳过）
除默认参数（cGranularity / cTextAmount）外，你对本次知识元抽取还有其他要求吗？
可说明（任选或全部）：
  · 抽取原则 —— 如"宁缺毋滥，只抽真正独立的概念"、"人物一律单独成元"
  · 颗粒度 —— 如"偏粗，按章节主题合并"、"偏细，把每个定义都拆开"
  · 总体数量 —— 如"全库控制在 200 个左右"、"这一批不超过 50 个"
  · 知识元内部文字数量 —— 如"每个知识元正文 100~200 字"、"只写要点"
  · 其他任何对抽取的要求

没有额外要求请直接回复 0；有则直接输入你的要求：
```

**② 处理用户回复：**
- 用户输入了具体要求 → 执行：
  ```bash
  python {skill_dir}/kb/scripts/ahkb.py set-extraction-requirements "<用户输入的要求>" --workspace <工作空间绝对路径>
  ```
- 用户回复 0 / "没有" / "无" → 执行清空（保证上次遗留要求不误用）：
  ```bash
  python {skill_dir}/kb/scripts/ahkb.py set-extraction-requirements 0 --workspace <工作空间绝对路径>
  ```

**③ 生效方式（★ 用户要求优先级最高）**：主代理在本菜单 A→F 的 C 步分析 chunk 时严格遵守（`extract` 返回的 `guidance.instruction` 已追加用户要求）。

#### Step 3 — 逐个处理选中文件

对用户选中的文件，逐个执行 A→F 流水线。

#### Step 4 — 询问是否继续添加（🔴 不是"是否整理"，是"是否继续添加"）

当前批次的 A→F 完成后，**只能问用户一件事**：是否还有更多文档要添加。

```
✅ [i/N] 处理完成：文件名.pptx

是否需要继续添加其他文档？（🔴 输入数字 1 或 2，严禁图形/卡片式选择菜单，包括 AskUserQuestion 工具）
1. ✅ 是 — 回到 Step 1 重新扫描，继续挑选要添加的文档
2. ➡️ 否 — 返回模块主菜单

💡 稍后需要整理知识链时，可随时通过菜单 6「自动整理知识库并更新知识链」或菜单 7「重建知识地图+HTML」完成。
```

> 🔴🔴 **铁律**：此步骤**绝对、永远、无论如何都不得**出现以下任何行为：
> - ❌ 自动执行 `maintain --detached`
> - ❌ 自动执行 `cross-link`
> - ❌ 自动执行 `build-graph` 或 `build-kg-html`
> - ❌ 自动执行 `update-concept-index`
> - ❌ 在对话中输出"继续整理"选项（只能问"继续添加"）
> - ❌ 以"已经把所有文档都添加完了"为理由跳过询问直接启动 maintain
>
> 🔴 用户选择此菜单就是为了手动控制每一步。尊重用户的选择。

