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

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

### 菜单 2 — 📦 全自动批量添加新文档

> 🔴🔴 **loop 驱动（★ 2026-08-13 起）**：本菜单的全自动阶段由 `kb.md`「🔴 全自动流水线 loop 执行」统一驱动——
> 阶段间自动衔接、失败自动重试（≤5 次）、中断自动续跑，**全程不向用户下指令**。
> - **进入判定**：先运行 `python {skill_dir}/kb/scripts/ahkb.py pipeline-status --workspace <工作空间绝对路径>`：
>   - 返回 `next_action` ∈ phase1/phase2/phase3（上次批量添加未完成）→ **自动续跑**：告知用户后直接进入「Step 2 全自动流水线 loop 执行」，跳过拷贝提示与 B0/顺序交互（mode 复用）；
>   - 返回 `done` / `error` / 无状态文件 → 全新添加，正常走 Step 0 拷贝提示 → Step 1 扫描 → B0 → loop。
> - **全新开始时的交互**：Step 0（拷贝提示）、Step 1（扫描）、Step 1.4（B0）、Step 1.5（处理顺序）仅在全新开始执行；B0 选择通过 `pipeline-mark start --mode <sequential|parallel>` 记录。
> - 🔴 **并行模式跳过 Step 1.5**（均衡分组自动排序）；顺序模式保留。

#### 📥 Step 0 — 提示用户拷贝新文档（🔴 仅全新开始执行；续跑时跳过）

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

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

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

#### Step 1 — 扫描新文档

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

获取待处理文件列表。如有 `pending_files`（已提取 chunks 但未完成关联），直接纳入处理（跳过 A→F，直接 mark-processed）。记录待处理总数 N。

> 🔴 **必须将 `estimated_minutes` 的估算时间用文字明确告知用户，不允许隐藏。必须在自然语言中直接说"预计 X ~ Y 分钟"。**

```
检测到 N 个文档待处理（含 M 个已有 chunks），预计 X ~ Y 分钟，开始全自动处理…
```

#### Step 1.4 — 抽取模式选择（B0 必选，🔴 仅全新开始执行；续跑时复用状态文件记录的 mode）

> 🔴 必须等待用户选择，不得默认执行。此即 `kb.md` 的 **B0. 抽取模式选择**：进入 Phase 1 前必须向用户提问二选一，不可自行默认。用户选定后记入 `pipeline-mark start --mode <sequential|parallel>`。

请选择抽取模式（🔴 必须输入数字 1 或 2，严禁使用图形/卡片式选择菜单，包括 AskUserQuestion 工具）：

1. 顺序单线程（推荐） — 逐文件 / 逐批由主 agent 亲自顺序处理；跨批一致性最好（概念索引顺序去重天然稳），速度不变。
2. 并行子代理抽取 — 先用 `phase1-group` 按预估工作量**均衡分组（默认上限 4 组）**：大文件独占一组、小文件打包给同一子代理顺序处理；每组由一个子代理并发处理，速度近似线性提升；靠「🔴 写前查盘合并（★ 强制）」规则在落盘前合并同名知识元，无需事后全库去重。

你的选择（输入数字 1 或 2）：

> 🔴 用户选定后：选 1 → 由主 agent 亲自顺序处理（每批分析 chunk → 创建知识元 → 执行 `update-concept-index`）；选 2 → 各文件并发交由子代理处理，主代理按其「🔴 并行模式完成门控」`phase1-wait` 脚本等待 + `phase1-peek` 轻量播报驱动。两种模式均须在所有文件完成 A→F + mark-processed 后才进入 Phase 2 关联。

#### Step 1.5 — 选择处理顺序（🔴 仅全新开始 + 顺序模式执行；并行模式跳过）

> 🔴 并行模式（Step 1.4 选 2）**跳过本步骤**：`phase1-group` 均衡分组已自动按工作量降序决定组内处理顺序。
> 🔴 顺序模式（选 1）必须等待用户选择，不得默认执行。向用户展示**与菜单 0 Step 1.5 完全一致**的处理顺序菜单（含 6 个选项 + 文件类型分布）。每项选择的行为同菜单 0 Step 1.5。

> 🔴🔴 **进入全自动阶段提示（★ 必说，缺一不可）**：用户在 Step 1.4 选定抽取模式、Step 1.5 选定处理顺序、即将进入 Step 2 全自动处理前，**必须在本条回复中用自然语言明确告知用户以下四点**（不得省略、不得只放在代码块里）：
> 1. **耗时长**：接下来进入全自动添加阶段，基于 scan 的 `estimated_minutes`，**预计需要 X ~ Y 分钟**才能完成；
> 2. **无需值守**：只要不出现意外，全程**不需要用户做任何操作**，请勿在屏幕前干等或反复确认；
> 3. **可以离开**：用户**可以离开一会儿**去处理别的事，预计 **X ~ Y 分钟后** 回来即可看到新增知识元与更新后的知识地图；
> 4. **异常才打扰**：仅当中途出现必须人工介入的真问题（如 stuck 自动重派失败等）时，智能体才会主动提示用户。
>
> 示例措辞："✅ 处理顺序已确定，开始全自动添加。整个流程预计需要 X ~ Y 分钟，期间无需您任何操作，您可以离开一会儿，稍后回来即可看到更新后的知识库与知识地图。除非遇到必须人工处理的问题，我不会打扰您。"

#### Step 1.6 — 抽取要求确认（★ 2026-08-14 新增，可跳过；位于开始抽取 chunk 之前）

> 🔴 **选择抽取模式（1.4）与处理顺序（1.5，顺序模式）之后、开始抽取 chunk 之前，必须询问用户对抽取是否还有其他要求**（并行模式跳过 1.5 时，本环节紧随 1.4 之后）。用户的要求将注入抽取指导与子代理提示词，**优先级最高**。

**① 询问**（🔴 自由文本输入，不是数字选项；严禁图形/卡片式选择菜单）：
```
📋 知识元抽取要求确认（可跳过）
除默认参数（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` 已追加用户要求）；
- 并行模式：派发子代理时把 `系统设置/project_settings.json` 的 `extraction_requirements` 填入子代理提示词模板的 `<抽取要求>` 占位符（无则写「无」）。

#### Step 2 — 全自动流水线 loop 执行（★ 2026-08-13 起统一驱动，取代原"Step 2→6 顺序推进"）

> 🔴🔴 **本步骤即 `kb.md`「🔴 全自动流水线 loop 执行」**：进入循环后由 `pipeline-status` 判定
> `next_action`，按 phase1 → phase2 → phase3 自动推进、自动衔接；每阶段成功 →
> `pipeline-mark done --phase <阶段>`，失败 → `pipeline-mark fail --phase <阶段> --reason "<原因>"`
> （自动重试，≤5 次，无需用户确认）；全部完成 → 报告 + `pipeline-mark finish`。**循环期间不向用户下任何指令。**
> - 全新开始时先执行：`python {skill_dir}/kb/scripts/ahkb.py pipeline-mark start --pipeline menu2 --mode <sequential|parallel> --workspace <工作空间绝对路径>`
> - 自动续跑时跳过（状态文件已存在，mode 自动复用）。
> - 下方 Step 3 / Step 4 / Step 5-6 是 loop 中 phase1 收尾 / phase2 / phase3 的执行细节。

**loop 中 phase1（抽取）的执行细节**（`next_action=phase1` 时执行；完成后 `pipeline-status` 确认 `phase1_complete:true` → `pipeline-mark done --phase phase1`）：

对全部 N 个待处理文件，**逐个**执行 A→F，显示进度：

```
[i/N] 正在处理：文件名.pptx ← 提取 → 归档 → 分析 → 写入 → 资源 → 标记
```

> 🔴 每处理完一个文件：`python {skill_dir}/kb/scripts/ahkb.py mark-processed "原始文件/分类/文件名"`
> 🔴 N 个全部完成前禁止进入下一阶段。
> 🔴 大文档分批：20~30 chunk/批，全部批次由主 AI 亲自完成。
> 🔴 **抽取模式**：顺序模式（mode=sequential）由主 agent 亲自逐文件顺序执行 A→F；并行模式（mode=parallel）按 `kb.md`「🔴 并行模式（选项 2）的核心契约与完成门控」**先 `phase1-group` 分组 → `phase1-dispatch --auto-wait` 建锚点并自动拉起 wait（★ 2026-08-14 标准姿势，防"派发后空转"）→ 派发子代理 → 由已启动的 wait 脚本等待驱动**（详见 kb.md ③），确保全部 mark-processed 才完成本阶段。**并行模式下主代理等待期间每 2~3 分钟运行一次 `phase1-peek` 把 `_display` 轻量播报给用户，收到 `complete`/`stuck`/`timeout` 终态立即处置（详见 kb.md ④），避免用户因屏幕长时间无输出误以为卡死。**
>
> 🔴🔴 **派发即等待（★ 2026-08-14 铁律，loop 最强化）**：并行模式下，`phase1-dispatch --auto-wait` 之后**主代理唯一合法动作就是进入 phase1-peek 播报循环**。**严禁**派发后结束回合、**严禁**空等"后台 agent 完成通知"、**严禁**派发后不启动 wait 就推进其他步骤。若 `pipeline-status` 返回 `next_action: "phase1_wait_required"`（wait 守卫触发），**必须立即补执行 `phase1-wait` 再继续**，不得忽略。

#### Step 3 — loop 中 phase1 收尾：自检（`next_action=phase1` 完成前执行）

全部文件 mark-processed 后，确认扫描返回待处理文件数 = 0，然后：

```bash
# maintain 会自动更新概念索引，此步骤可选但推荐保留作为安全检查
python {skill_dir}/kb/scripts/ahkb.py update-concept-index
```

> 🔴 确认 `pipeline-status` 的 `phase1_complete:true` 后执行 `pipeline-mark done --phase phase1`，进入 phase2。

#### Step 4 — loop 中 phase2（maintain 关联）的执行细节（`next_action=phase2` 时执行；完成后 `pipeline-mark done --phase phase2`）

```bash
python {skill_dir}/kb/scripts/ahkb.py maintain --detached --workspace <工作空间绝对路径>
   ```
   > 此命令 1 秒内返回，GUI 窗口在独立进程中运行。
   🔴🔴 **LLM 每回合运行以下命令检查一次，直到 `status: "complete"` 才能继续第 5 步：**

   ```bash
   python {skill_dir}/kb/scripts/ahkb.py check-maintain-status --workspace <工作空间绝对路径>
   ```

   🔴🔴 **收到 phase1_incomplete 状态时的处理：**
   - 输出含 `"status": "phase1_incomplete"` → **立即停止**，回到 Phase 1 完成剩余文档！

   🔴🔴 **每轮检查后必须把 `_display` 原文输出展示给用户：**
   - `status: "complete"` → 汇总后进入硬阻断线以下
   - `status: "cancelled"` → 返回主菜单
   - `status: "running"` / `"starting"` → 展示 `_display` 原文，约 10 秒后再次轮询
   - 🔴🔴 **其他状态 → 展示 `_display` 原文，等约 10 秒后再次轮询。禁止只内部检查不输出。**

```
🔴🔴 ═══════════════════════════════════════════════════
🔴🔴  硬阻断：必须轮询确认 maintain [完成] 后才能越过此线
🔴🔴  严禁在关联未完成时执行 build-graph 或 build-kg-html
🔴🔴 ═══════════════════════════════════════════════════
```

#### Step 5 — loop 中 phase3 细节①：重建根节点（`next_action=phase3` 时执行）

```bash
python {skill_dir}/kb/scripts/ahkb.py build-graph
```

> 🔴 `build-graph` 已自动写入根节点 .md，无需 AI 手工操作。完成后继续 Step 6 生成 HTML。

> 🔴 根节点 .md **必须先写入完成**，才能执行第6步。

#### Step 6 — loop 中 phase3 细节②：生成 HTML 知识地图并自动打开（完成后 `pipeline-status` 确认 `phase3_complete:true` → `pipeline-mark done --phase phase3` → loop 判定 done → `pipeline-mark finish`）

```bash
python {skill_dir}/kb/scripts/ahkb.py build-kg-html
python -c "import webbrowser; webbrowser.open('<知识库名称>-知识地图.html')"
```

完成后返回模块主菜单。

