# 📦 知识库构建模块

> 从属于 AHKB-CPS 统一系统。从文档构建基于 Obsidian 格式的知识库。交互菜单驱动，无需记忆参数。
> 🔴 **交互规则**：所有选项必须用数字编号展示，用户输入数字选择，**严禁使用 AskUserQuestion 工具**。
> 🔴🔴 **进度透明规则**：处理文档时每处理完一个文件必须在对话中报告进度（如 `[3/7] 处理完成：xxx.pptx`），让用户知道当前走到哪一步。**禁止静默处理，禁止连续处理多个文件后一次性报告。**
>
> 🔴🔴 **进入即展示菜单（★ 铁律）**：加载完本模块后，必须立即完整输出下方的「知识库构建模块菜单」，**禁止跳过菜单直接询问用户要做什么**。用户看到菜单后再选择。
>

## 模块概述

从文档构建基于 Obsidian 格式的知识库。交互菜单驱动，无需记忆参数。

### 📋 总体流程

1. **第一步：拆解文档** — 扫描**整个工作空间**中的所有文档，逐个提取知识元和资源
2. **第二步：链接成网** — 在各个知识元之间以及各种资源中建立交叉链接
3. **第三步：生成地图** — 生成知识地图（包括 Obsidian 格式和 HTML 版）

### 核心设计原则

1. **原子性**：每个知识元只包含一个独立概念/观点/定义/事实
2. **资源附属**：图片/视频/音频是知识元的附属资源，通过 `.ctx` 文件关联
3. **双向关联**：`.ctx` ↔ 知识元确定性挂接；知识元之间 `[[链接]]` 语义关联
4. **全局统一（★ 核心）**：同一概念在不同文档中只创建一个知识元
5. **🔴🔴 两阶段隔离（★ 最高优先级强制规则）**：Phase 1 只生产知识元，Phase 2 只做关联。**两个阶段之间有一道不可逾越的墙**
6. **🔴 全部处理原则（★ 强制）**：所有原始文件必须逐个处理完毕
7. **🔴🔴 自动审查原则（★ 强制）**：D.5 `verify-units` + F `mark-processed` 硬关卡双重保险，AI 读取 JSON 自动决策"通过/补做/回头"，**无需用户干预**。阈值随 `cGranularity` 参数自动调整。

### 🔴 绝对禁止规则

- **禁止将 skill 安装目录作为知识库工作空间**
- **禁止在 A→F 流程中生成 `[[链接]]`**
- **禁止将资源文件当知识元**
- **🔴 禁止在 skill 安装目录、工作空间根目录、用户目录下存放临时文件**（必须放 `临时工作文件/`，用完立即删除）
- **🔴 批次处理必须完成所有批次**
- **🔴 重建知识库时必须重新处理全部原始文件**
- **🔴🔴 严禁提前执行 crosslink / maintain**
- **🔴🔴 互动添加（菜单 3）严禁自动执行 maintain / crosslink**：用户选择这个菜单就是为了一步一步手工操作。每完成一批 A→F 后，只能询问用户"是否继续添加其他文档？"，**绝对禁止自动触发 maintain**。即使用户一次性添加了所有未处理文档，也必须等用户通过菜单 6 或 7 手动启动后续关联。

### 工作空间结构

```
<工作空间根目录>/
├── 原始文件/               ← 📥 已处理文档归档目录
├── 知识元/                 ← 生成的 .md 知识单元
├── 图片及其他资源/{images,videos,audios,others}/
├── chunks/                 ← 原始文档分块存储 + index.json
├── 临时工作文件/           ← 临时脚本、中间文件
├── 产品成果/               ← AI 生成的产品成果文件
├── <知识库名称>.md         ← 🏆 总纲根节点
├── <知识库名称>-知识地图.html
└── 系统设置/               ← project_settings.json 等
```

### 快速参考

```bash
python {skill_dir}/kb/scripts/ahkb.py <command> [--workspace <vault-path>]

# 常用命令：
#   scan                  扫描新文档
#   maintain --detached   启动知识链关联（detached 模式）
#   check-maintain-status 查询 maintain 状态（LLM 轮询专用）
#   build-graph           构建根节点
#   build-kg-html         生成 HTML 知识地图
```

> 🔴 **路径约定**：本文中所有路径均相对于 AHKB-CPS 技能目录（即 `{skill_dir}`），而非工作空间。

---

## 首次运行流程

### Step 1 — 检查初始化状态

```bash
python {skill_dir}/kb/scripts/ahkb.py find-root
```

- `found: false` → **首次运行**，先执行下方「Step 1.5 — 文档导入检测」
- `found: true` → **已有知识库**，直接进入主菜单

### Step 1.5 — 文档导入检测

1. **递归检查工作空间下所有文档**（子目录中的文档也会被检测到，排除 `.obsidian`、`.claude` 等隐藏目录）
2. **有文档** → 告知用户"检测到工作空间下有文档（含子目录）。这些文档会留在原位置，由后续菜单 0 扫描时逐个处理。"
3. **无文档** → 告知用户"当前工作空间没有可处理的文档。请把你的原始文档拷贝到当前目录或子目录下，然后重新运行菜单 0。"

### Step 2 — 设置权限

```bash
python {skill_dir}/kb/scripts/ahkb.py setup-permissions
```

### Step 3 — 初始化工作空间

首次运行时请用户选择（输入数字 1 或 2）：

1. ✅ 是，初始化工作空间
2. ➡️ 否，跳过

> ⚠️ **🔴 关键：选择创建后，必须直接问用户「请输入知识库名称」**

```bash
python {skill_dir}/kb/scripts/ahkb.py init --name <用户输入的知识库名称>
```

### Step 4 — 创建根节点

在工作空间根目录创建根节点 .md 文件，文件名 = `{{知识库名称}}(根).md`（如"大系统观知识库(根).md"）。

> 🔴 `build-graph` 已自动创建/更新根节点 .md，AI 无需手工操作。步骤 1 完成后根节点即就绪。

---

## 主菜单

### 📋 总体流程说明

每次显示主菜单前，先展示三步流程说明：

```
═══════════════════════════════════════════════════════
📋 本模块总体流程：
   第一步：拆解文档  → 扫描文档，提取知识元和资源
   第二步：链接成网  → 建立交叉链接，形成知识链网
   第三步：生成地图  → 生成 Obsidian + HTML 知识地图
═══════════════════════════════════════════════════════
```

### 📋 菜单

```
═══════════════════════════════════════════════════════
        AHKB-CPS：知识库构建模块菜单
═══════════════════════════════════════════════════════
  0. 🚀 从0开始全自动构建知识库与知识地图    — 建议初次使用时选择
  1. 🔨 全自动完全重建知识库       — 清除全部知识元和资源，重新构建
  2. 📦 全自动批量添加新文档         — 处理全部新增文档
  3. 📋 互动扫描添加新文档         — 手工模式：逐步挑选文档、逐个处理，不自动关联
  4. 🔄 重新重点处理某一文档       — 觉得AI处理某文档不够好时重新处理
  5. 🖐 手动维护知识库资源         — 启动图形界面管理，手工标记提高准确性
  6. 🛠 自动整理知识库并更新知识链  — 修复错误格式并刷新关联
  7. 🏗 重建知识地图+HTML          — 更新根节点、生成知识地图
  8. 🌐 生成HTML版知识地图         — 从现有根节点md文件生成
  9. 📊 知识库统计                — 查看统计数据
  s. ⚙ 设置                       — 调整颗粒度、链接权重等
  e. ↩️ 返回主菜单                — 返回 AHKB-CPS 统一主菜单
═══════════════════════════════════════════════════════
请回复数字 0~9、s 或 e 选择操作：
```

### 🔴 菜单循环规则

1. **只有用户选择「返回主菜单」才能返回统一主菜单**
2. **每完成一项操作后自动重新显示模块主菜单**
3. 每次返回模块主菜单时提醒用户：
   > 💡 AHKB-CPS 还提供以下模块：
   >   · 技能向导 — 帮你找到该用的模块
   >   · 文章生成 — 生成结构化文章
   >   · 幻灯片生成 — 基于知识库生成专业演示文稿
   >   · 全息脑图生成 — 生成阿色全息脑图
4. 🔴 **每一次轮询都必须向用户展示原始结果**（如 `⏳ [5/12] 关键词匹配，已用时 2min`），不得只写"正在处理"。用户看到进度才不焦虑。

---

## 文档处理核心流程（两阶段法）

### 📂 文档处理优先级

`.md` → `.pdf` → `.docx` → `.pptx` → `.xlsx` → `.html/htm` → `.txt` → 其他格式

### 第一阶段：批量处理所有文档（A→F，🔴 严格禁止做任何关联）

#### 📌 大文档分批策略

超大数据时：按照 **20~30 个 chunk/批** 的规模分批处理。

**🔴 顺序单线程处理（强制）：**
- 第一批：亲自分析 chunk 1~25 → 创建知识元 → 执行 `update-concept-index`
- 第二批：亲自分析 chunk 26~50 → 加载最新索引 → 去重后创建
- **全部批次亲自完成，不得使用子代理或并行任务。**

### ⛔ Phase 1 / Phase 2 分界线

```
┌─────────────────────────────────────────────────────────┐
│  🔴🔴 警告：此处是第一阶段和第二阶段之间不可逾越的墙 🔴🔴 │
│                                                         │
│  第二阶段必须在【所有 N 个文件全部完成 A→F +            │
│  mark-processed】后才能执行。                            │
│                                                         │
│  进入第二阶段前，强制自检：                                │
│  □ 所有文件都 mark-processed 了吗？（是 / 否）            │
│  □ 待处理文件数 = 0 吗？（是 / 否）                       │
│  □ 所有文件的 D.5 verify-units 已通过？（是 / 否）        │
│  → 三项全部为"是"才允许进入第二阶段                       │
│                                                         │
│  🔴🔴 脚本级硬关卡：maintain 命令内置了 Phase 1 完成度   │
│  检查。如果还有未处理文件，maintain 会直接拒绝执行并     │
│  返回 status: "phase1_incomplete"。不可绕过。             │
└─────────────────────────────────────────────────────────┘
```

### 第二阶段：统一关联（全部生成后再做）

**前置条件：全部 N 个文件已完成 A→F（含 D.5 verify-units 验证通过）并 mark-processed。**

通过 `maintain` 命令完成三类关联：
- **知识元↔知识元** `[[链接]]`
- **知识元↔原始文件** 关联
- **知识元↔资源**双向挂接

> ⚠️ maintain **必须弹出图形窗口（tkinter GUI）**，绝不允许隐藏或后台运行。
> 🔴 **严禁**任何绕过 GUI 的行为。

---

### A. 提取内容 + 自动归档

```bash
python {skill_dir}/kb/scripts/ahkb.py extract <相对路径> [--category <分类名>]
```

**此命令同时完成两件事：**
1. **提取内容** — 输出 JSON 包含 `chunks` 和 `resources_flat`
2. **自动归档** — 将原文件移入 `原始文件/` 目录

### C. 分析并生成知识元（★ 决定知识库质量的核心环节）

**🎯 cGranularity 三档模式：**

| 值 | 模式 | 拆分策略 | 字数底线 |
|:--:|------|----------|:--------:|
| 0 | **精细模式** | 概念有独立性即拆分 | ≥50字 |
| 0.5 | **均衡模式**（默认） | 有明确概念边界才独立 | ≥60字 |
| 1 | **粗粒模式** | 只按大主题拆分 | ≥120字 |

**🎯 cTextAmount 三档模式：**

| 值 | 模式 | 每个知识元的展开深度 |
|:--:|------|-------------------|
| 0 | **摘要模式** | 只写定义加 2~3 个核心要点 |
| 0.5 | **适中模式**（默认） | 一个完整段落 |
| 1 | **详细模式** | 充分展开，含定义、说明、论证 |

**🔴🔴 严肃抽取铁律（★ 最高优先级）**
- **严禁因文档篇幅大而偷懒。** 文档越大越要逐段分析，该拆的知识元一个不能少。
- **严禁将整篇文档不经认真分析就当做一个知识元标记为已处理。** 每个段落、每个概念都必须独立判断是否成元。
- **严格按照 `cGranularity` 和 `cTextAmount` 参数执行：** 该细就细（精细模式概念有独立性即拆）、该粗就粗（粗粒模式只按大主题拆）、该详就详（详细模式充分展开）、该略就略（摘要模式只写要点）。
- **每批完成后必须自查**：检查本次产出的知识元数量和预期是否匹配——数量太少说明可能偷懒了。
- **🔴🔴 禁止跳过任何原始文档（★ 铁律）。** 只要被判定为原始文档，**每一篇都必须完整解析抽取，即使存在相似或同名的文件也绝不能跳过**。处理清单上列出的所有 N 个文件，必须逐个处理完毕，少一个也不行。绝对禁止以"这个文件看起来和之前处理过的类似"为理由跳过。
- **🔴 自动审查机制已启用（双重保险）：**
  1. **D.5 `verify-units`** — 每篇文档的知识元产出会被自动验证，按当前 `cGranularity` 参数判断产出是否合理
  2. **F `mark-processed` 硬关卡** — 零匹配的知识元时直接拒绝标记
  - **不要试图绕过这些检查，它们是为了帮你拦截错误。** 如果脚本拒绝了标记，说明你确实跳过了 C/D 步骤，回去补做即可。
- **🔴 所有文档必须重新从头处理，禁止使用对话历史中上一轮的产出作为参考。** 重建的目的是得到不同的知识库，上一轮的结果作废。

**⚠️ 护城河原则（任何时候不违反）：**
- **所有内容必须有原文依据**，禁止编造、推测
- **🔴 正文不得为空**
- **🔴 字数底线**：正文不足该档位最低字数的知识元，合入上级
- **🔴 连续短节合并**
- **🔴 低温模式**：事实准确性为最高标准

**🔴 绝对禁止使用子代理（★ 强制 ★）**

**🔴 批次一致性自查（强制）：**
每批完成后检查本批产出的总数——如果与预期数量偏差超过 2 倍，暂停检查原因。

#### 跨文档统一处理规则

分析文档前先加载已有知识元/资源/处理清单。**完全重建时跳过**。

#### ⚡ 原子性拆分规则

**核心原则：** 一个知识元 = 一个独立概念/观点/定义/事实/人物/原理/方法。

**🔴 强制独立（任何参数下不得合并）：**
- **人物** — 任何人物名必须独立成元
- **定义** — 任何概念定义必须独立成元

**原子性检查清单（创建每个知识元前自查）：**
```
□ 候选名称与已有知识元高度相似？ → 🔴 不新建，追加关联
□ 是否脱离父级后含义仍完整？ → 不独立，合入父级
□ 是否包含超过一个独立概念？ → 拆
□ 是否含有人物名？ → 人物必须独立
□ 正文是否满足该档位数底线？
□ 正文是否为空？ → 🔴 不得为空！
□ 详细程度是否符合 guidance 指令？
□ 原文回溯：这一句原文中有对应文字吗？
□ 同一层级是否有连续短节可以合并？
```

#### 🧩 知识元关联规则

**第一阶段 AI 禁止写入任何 `[[链接]]`。**

#### 🏷️ 标签规则

**顺序约定：** `[领域标签, 概念标签, ..., 类型标签]`
- **最后一个标签必须是类型标签**（如 `概念`、`方法论`、`人物`、`定义`、`原理`）
- **知识元名称本身不得作为标签**

#### 📛 知识元命名规则

**🔴 知识元名称必须是合理、规范的概念或术语，严禁出现以下形式：**

- ❌ 章节编号：`1.1 概述`、`第3章 方法论`、`§2.3`
- ❌ 符号式字符：`→→→`、`★核心★`、`【要点】`、`===分割线===`
- ❌ 字符画/装饰：`╔══╗`、`~~~~`、`●●●`
- ❌ 编号前缀：`KD-001-xxx`、`A-耦合度`
- ❌ 纯数字：`123`、`2024`
- ❌ 过长的句子：超过 12 个字

- ✅ 正确示例：`耦合度定理`、`系统边界`、`熵增原理`、`全息有机系统论`、`卢春阳`

**文件名（不含 `.md`）必须等于 H1 标题，一字不差。**
- 简短（1-12字），尽量短

### D. 写入知识元文件

**AI 在 Phase 1 写入的内容：**

```markdown
---
tags: [系统论, 耦合, 概念]
source: "原始文件/管理哲学/源文件.pptx"
unit_id: KD-YYYYMMDD-NNN
created: YYYY-MM-DD
updated: YYYY-MM-DD
summary: 耦合度是指系统要素之间的相互依存程度
related_files:
  - file: "原始文件/管理哲学/源文件.pptx"
    score: 1.0
---

# 耦合度定义

正文内容...
```

**强制规范：**
1. **Phase 1 字段顺序**：tags → source → unit_id → created → updated → summary
2. **Phase 1 禁止写入** resources、关联知识元、关联资源、关联原始文件

### D.5 🔴 自动验证知识元产出（新增）

> 🤖 **全自动执行**：无需用户确认，AI 读取 JSON 结果自行决策。

每批知识元写入后，**必须自动**执行 `verify-units` 进行参数感知检查：

```bash
python {skill_dir}/kb/scripts/ahkb.py verify-units "<原始文件/相对路径>"
```

AI 根据返回的 `status` 字段自动决策：

| 返回 status | 含义 | AI 行动 |
|:----------:|------|---------|
| `"pass"` | ✅ 产出合理，符合当前 cGranularity 档位 | 继续下一步 |
| `"warning"` | ⚠️ 覆盖率偏低，但未完全跳过 | 检查 `warnings` 列表，补做遗漏 chunk 对应的知识元 |
| `"fail"` | ❌ 知识元数为 0 或严重不足 | 必须回到 [C] 重新逐段分析，不得进入下一步 |

> 🔴 检查阈值**自动随 `project_settings.json` 中 `cGranularity` 调整**：

| 检查项 | 精细模式 | 均衡模式 | 粗粒模式 |
|--------|:--------:|:--------:|:--------:|
| cGranularity 值 | ≤ 0.25 | 0.26~0.74 | ≥ 0.75 |
| 每文档最少知识元 | ≥ 3 | ≥ 2 | ≥ 1 |
| chunk/知识元建议比 | ≤ 3:1 | ≤ 5:1 | ≤ 8:1 |
| 每知识元最少字数 | ≥ 50 | ≥ 60 | ≥ 120 |
| 全库单元数/文档数 | ≥ 5 | ≥ 3 | ≥ 1.5 |

### E. 处理资源 .ctx 文件

提取器已自动生成初始 `.ctx`。**你的任务：** 填写 `belongs_to` 指向所属知识元。

### E.5 更新概念索引

```bash
python {skill_dir}/kb/scripts/ahkb.py update-concept-index
```

### F. 🔴 标记已处理（自动硬关卡检查）

> 🔴 **自动硬关卡**：`mark-processed` 会自动检查 `知识元/` 中是否存在 source 匹配该文件的知识元。
> **零匹配且无 `--force` → 拒绝标记**，AI 检测到 error 后自动回头执行 [C] 分析。
> `--force` 仅用于极少数特殊情况（如文档确实无法产生知识元），不得常规使用。

```bash
python {skill_dir}/kb/scripts/ahkb.py mark-processed "<原始文件/文件名>"
```

AI 读取返回的 JSON，按以下逻辑处理：

```
收到 mark-processed 的 JSON →
  ├─ "ok": true → ✅ 标记成功，继续处理下一个文件
  └─ "warning": true, type:"no_knowledge_units" →
       ❌ 知识元完整性检查未通过
       → 回到 [C] 重新分析该文档的 chunks 并创建知识元
       → 再次执行 mark-processed
```

| 返回特征 | 含义 | AI 行动 |
|:--------:|------|---------|
| `"ok": true` | ✅ 完整性检查通过，已标记 | 继续处理下一个文件 |
| `"warning": true, type:"no_knowledge_units"` | ❌ 在知识元中未找到该文件的产出 | 回到 [C] 重新分析 chunks 并创建知识元，然后再次执行 mark-processed |

> 🔴 **执行 `mark-processed` 前必须已执行过 D.5 `verify-units` 且状态为 `pass` 或已处理警告。**

### G. 质量审核

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

---

## 各菜单简要流程

### 菜单 0 — 🚀 从0开始全自动构建知识库与知识地图

> 🔴🔴 **全自动不中断（★ 铁律）**：Step 0（清除旧记录）和 Step 1（扫描）自动执行。**Step 1.5 是唯一允许的交互断点**——用户在此选择处理顺序。用户选择完毕后，从 Step 2 开始恢复全自动不中断：逐个文档 A→F、maintain 轮询、build-graph、HTML 生成、浏览器打开——全程无中断，一气呵成。

#### Step 0 — 清除旧处理记录

> 🔴 **从零开始必须清除旧记录**，否则已处理文件会被跳过。

```bash
python {skill_dir}/kb/scripts/ahkb.py clear-manifest
```

#### Step 1 — 扫描所有文档

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

> 🔴 **必须将 `estimated_minutes` 的估算时间用文字明确告知用户，不允许隐藏或仅放在代码块中。必须在自然语言消息中直接说"预计 X ~ Y 分钟"。**
> ```
> 📊 发现 N 个文档待处理，预计需要 X ~ Y 分钟
> ```

> 如有 `pending_files`（已提取 chunks 但未完成关联），优先处理：直接 mark-processed，跳过 A→F 提取阶段。

#### Step 1.5 — 选择处理顺序

scan 已返回每个文件的 `ext`（文件类型）、`text_chars`（有效文字量估算）和 `size`（文件大小），向用户展示处理顺序选择：

```
📊 发现 N 个文档待处理（含 M 个已有 chunks），预计 X ~ Y 分钟

📂 文件类型分布：
  · pptx: X 个  · docx: X 个  · pdf: X 个  · md: X 个  · xlsx: X 个  · html: X 个  · txt: X 个

请选择处理顺序：
1. 🔼 文字量从多到少 — 优先处理内容丰富的文档，先建知识库骨架
2. 🔽 文字量从少到多 — 优先处理短小文档，再集中精力处理长篇
3. 📁 按文件类型分组 — 同类型文档集中处理（按类型优先级：pptx→docx→pdf→md→xlsx→html→txt，组内文字量从多到少）
4. 🏷️ 指定文件类型优先 — 你指定哪些类型先处理，其余类型后处理
5. ⏭ 按原有顺序 — 不做排序，按扫描发现顺序处理
6. ✏️ 自定义顺序 — 你告诉我怎么排

你的选择（输入数字 1~6）：
```

> 🔴 **必须等待用户选择**，不得默认执行，不得替用户决策。
> 🔴 AI 严禁预设或推荐任何选项为默认值——用户必须明确选择。
> - 选 1 或 2：按 `text_chars` 排序
> - 选 3：按扩展名分组，组内按 `text_chars` 降序
> - 选 4：询问用户"你想优先处理哪些文件类型？（如 pptx、docx、pdf 等）"，用户指定后将该类型排在前面，其余类型按原有顺序排后
> - 选 5：保持 scan 返回的顺序
> - 选 6：询问用户"请按你想要的顺序列出文件（每行一个，或输入编号列表）"
>
> 排序时 pending_files 始终排在同类最前面。用户选择后，AI 按指定顺序逐个执行 A→F。

#### Step 2 — 按选定顺序逐个处理（A→F 循环）

> 🔴 先列全所有待处理文件，得到总数 N。循环 i = 1 到 N。N 个全部处理完才允许进入下一步。
> 🔴 `pending_files` 中的文件已有 chunks，但需注意：`mark-processed` 会自动检查对应知识元是否存在。
> - 已有知识元 → 正常通过
> - **无知识元 → 被拒绝**，必须先完成 [C][D] 步骤再标记

#### Step 3 — 关联所有知识元（⚠️ 仅此一次）

1. **更新概念索引**（可选，maintain 已自动执行）：`python {skill_dir}/kb/scripts/ahkb.py update-concept-index`
2. **关联所有知识元**：

   ```bash
   python {skill_dir}/kb/scripts/ahkb.py maintain --detached --workspace <工作空间绝对路径>
   ```
   > 此命令 1 秒内返回，GUI 窗口在独立进程中运行。

   🔴🔴 **LLM 必须执行轮询（不得跳过，不得直接进入 Step 4）。每回合运行以下命令检查一次：**

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

   🔴🔴 **收到 phase1_incomplete 状态时的处理（新增）：**
   - 输出含 `"status": "phase1_incomplete"` → **立即停止**，回到 Phase 1 完成剩余文档的 A→F 流水线！禁止强行继续。

   返回的 JSON 中 `_display` 字段包含人类可读的状态摘要，可直接展示给用户。

   - `status: "complete"` → 汇总后进入 Step 4
   - `status: "cancelled"` → 返回主菜单
   - `status: "running"` / `"starting"` → 把 `_display` 原文展示给用户，等约 10 秒后再次轮询
   - `status: "error"` / `"stale"` → 汇总异常信息，返回主菜单
   - 🔴🔴 **其他任何状态 → 把 `_display` 原文展示给用户，等约 10 秒后再次轮询。禁止只内部检查不输出。**

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

#### Step 4 — 构建根节点并重建知识地图

1. `python {skill_dir}/kb/scripts/ahkb.py build-graph`
2. `python {skill_dir}/kb/scripts/ahkb.py build-kg-html`
3. `python {skill_dir}/kb/scripts/ahkb.py set-graph-colors`
4. **自动打开知识地图**：`python -c "import webbrowser; webbrowser.open('<知识库名称>-知识地图.html')"`

### 菜单 1 — 🔨 全自动完全重建知识库

> 清除全部知识元和资源，从零重新处理所有文档，保留已设定的知识库名称。
>
> 🔴🔴 **全自动不中断（★ 铁律）**：Step 1（确认）和 Step 4.5（选择处理顺序）是**仅有的两个交互断点**。确认重建并选定处理顺序后，从 Step 5 开始到 Step 7 全部子步骤——**全程无中断，严禁中途停下询问用户或等待确认**。
>
> 🔴🔴🔴 **重建必须从头开始，严禁任何形式的简化处理（★ 铁律中的铁律）**
> - **重建 = 推倒重来**：`purge-kb` 后旧知识库已不存在——你的任务是重新构建一套全新知识库，不是"修复"或"补充"。
> - **🔴 严禁简化处理**：不得以"内容太多""时间太长"为由跳过任何文档的逐段分析。11 个文档必须产出 11 份完整分析。
> - **🔴 严禁敷衍**：重建的产出必须与首次构建同等质量——该拆的知识元一个不能少，该写的正文一个字不能省。不允许出现"重建后知识元数反而比之前少很多"的情况。
> - **🔴 全程遵循 A→F 流水线**：每个文件必须完整走完 extract → 归档 → 逐段分析 → 写入知识元 → verify-units → mark-processed，**不得跳步、不得简化、不得合并处理**。

#### Step 1 — 双重确认

**先提醒用户手动备份**，然后向用户展示确认选项：

> 🔴 **全自动重建需要智能体具有完全访问权限（Full Access）**，用于删除旧的根节点文件、知识地图、知识元等。如果权限不足，旧数据无法清除，新知识库无法重建。请确认智能体已授予**完全访问权限**。

**⚠️ 此操作将清除全部知识元、资源和关联数据（`原始文件/` 中的文档本身不受影响）。是否继续？**

1. ✅ 确认重建 — 清除全部数据，从零开始
2. ➡️ 取消 — 返回模块主菜单

#### Step 2 — 清除知识库

> 🔴 **优先批量删除，失败则由 AI 手动逐个清理。**

先执行批量删除：

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

检查输出中的 `deleted` 字段。如果发现残留文件（如报错或删除计数为 0 但实际有旧文件），**AI 必须手动将残留文件移入回收站**：

```bash
python -c "import os, datetime
ws='<工作空间>'; ts=datetime.datetime.now().strftime('%Y%m%d_%H%M%S'); t=os.path.join(ws,'回收站'); os.makedirs(t,exist_ok=True)
for d in ['知识元','图片及其他资源','chunks']:
    p=os.path.join(ws,d)
    if os.path.isdir(p): os.rename(p,os.path.join(t,d+'_'+ts)); os.makedirs(p,exist_ok=True)
for f in ['<根节点名称>(根).md','<根节点名称>-知识地图.html']:
    p=os.path.join(ws,f)
    if os.path.isfile(p): os.rename(p,os.path.join(t,f+'_'+ts))"
python -c "import os, datetime
ws='<工作空间>'; ts=datetime.datetime.now().strftime('%Y%m%d_%H%M%S'); t=os.path.join(ws,'回收站'); os.makedirs(t,exist_ok=True)
p=os.path.join(ws,'原始文件','_processed_docs.json')
if os.path.isfile(p): os.rename(p,os.path.join(t,'_processed_docs.json_'+ts))"

> 🔴 **必须确保所有旧文件全部清除后才能进入下一步。** 如有残留，后续扫描会复用旧数据，导致重建失败。
>
> **如果 AI 也无法删除残留文件**（权限不足、文件被占用等），**必须提示用户手动删除**，告知用户具体路径：
> ```
> ⚠️ 以下文件无法自动删除，请手动删除后再继续：
>   C:\Users\xxx\Workspace\知识元\
>   C:\Users\xxx\Workspace\大系统观知识库.md
> ```
> 用户手动删除后，AI 再继续后续流程。

#### Step 3 — 🔴 设定知识库名称

先读取 `project_settings.json` 中的旧名称（`get_kb_name` 或直接看文件内容），然后向用户展示两个选项：

**知识库名称设置：**

1. ✅ 继续使用旧名称「{{旧名称}}」
2. ✏️ 输入新的名称

> 也可以直接说其他要求或选项

用户选 1 则直接用旧名称，选 2 则等待用户输入后执行：

```bash
python {skill_dir}/kb/scripts/ahkb.py set-kb-name "<用户输入的名称>"
```

#### Step 3.5 — 创建根节点知识元

> 知识库名称已就绪，立即创建根节点 `.md` 文件（后续 maintain 完成后再填充完整数据）。

```bash
python {skill_dir}/kb/scripts/ahkb.py create-root-node
```

> 🔴 此步骤不可缺少——后续所有操作（扫描、A→F 处理、maintain、build-graph）均依赖根节点文件的存在。
>
> 🔴 `create-root-node` 创建空的根节点框架。后续 maintain 完成后，`build-graph`（Step 7）会自动填充完整的知识元列表和统计数据。

#### Step 4 — 扫描所有文档

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

> 🔴 **必须将 `estimated_minutes` 的估算时间用文字明确告知用户，不允许隐藏或仅放在代码块中。必须在自然语言消息中直接说"预计 X ~ Y 分钟"。**
> ```
> 📊 发现 N 个文档待处理，预计需要 X ~ Y 分钟
> ```

> `_processed_docs.json` 已清空，全部文档均为待处理。得到总数 N。

#### Step 4.5 — 选择处理顺序

scan 已返回每个文件的 `ext`（文件类型）、`text_chars`（有效文字量估算）和 `size`（文件大小），向用户展示**完整的「选择处理顺序」**菜单（与菜单 0 Step 1.5 完全一致，含 6 个选项 + 文件类型分布），不再重复列出。
> 🔴 **必须等待用户选择**，不得默认执行。选项 1~6 的行为同菜单 0 Step 1.5。

#### Step 5 — 逐个处理（A→F 循环）

对全部 N 个文档按 Step 4.5 选定的顺序逐个执行 A→F，显示 `[i/N]` 进度。

> 🔴🔴 **最高优先级：严禁恢复旧数据（★ 铁律）**
> 🔴 `purge-kb` 已彻底清除旧知识元、chunks、资源。此轮重建必须**全部从原始文件重新提取**，每一步 AI 分析都是全新的。
> 🔴 **严禁**从对话记忆中恢复上一轮的知识元内容、名称、标签、摘要等任何数据。
> 🔴 **严禁**引用 chunks/ 或知识元/ 中残留的任何文件（即使有残留也不能用）。
> 🔴 每一篇文档的处理结果必须只基于该文档的原始内容 + 当前 `cGranularity`/`cTextAmount` 参数——不参考上一轮的产出。
> 🔴 全部 N 个完成前禁止 maintain。

#### Step 6 — 关联所有知识元（⚠️ 仅此一次）

1. `python {skill_dir}/kb/scripts/ahkb.py update-concept-index`（可选，maintain 已自动执行）
2. 关联所有知识元：

   ```bash
   python {skill_dir}/kb/scripts/ahkb.py maintain --detached --workspace <工作空间绝对路径>
   ```
   > 此命令 1 秒内返回，GUI 窗口在独立进程中运行。

   🔴🔴 **LLM 必须执行轮询（不得跳过，不得直接进入 Step 7）。每回合运行以下命令检查一次：**

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

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

   返回 JSON 中 `_display` 字段可直接展示给用户。

   - `status: "complete"` → 汇总后进入 Step 7
   - `status: "cancelled"` → 返回主菜单
   - `status: "running"` / `"starting"` → 展示 `_display` 原文，约 10 秒后再次轮询
   - 🔴🔴 **其他状态 → 展示 `_display` 原文，等约 10 秒后再次轮询。禁止只内部检查不输出。**

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

#### Step 7 — 构建根节点并重建知识地图

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

完成后返回模块主菜单。

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

> 🔴🔴 **全自动不中断（★ 铁律）**：Step 1（扫描）自动执行。**Step 1.5 是唯一允许的交互断点**——用户在此选择处理顺序。用户选择完毕后，从 Step 2 开始恢复全自动不中断：逐个处理→maintain 轮询→重建地图，一气呵成。

#### 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.5 — 选择处理顺序

scan 已返回每个文件的 `ext`、`text_chars` 和 `size`。向用户展示**与菜单 0 Step 1.5 完全一致**的处理顺序菜单（含 6 个选项 + 文件类型分布）。每项选择的行为同菜单 0 Step 1.5。

> 🔴 **必须等待用户选择**，不得默认执行。

#### Step 2 — 逐个处理（A→F 循环）

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

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

> 🔴 每处理完一个文件：`python {skill_dir}/kb/scripts/ahkb.py mark-processed "原始文件/分类/文件名"`
> 🔴 N 个全部完成前禁止 maintain。
> 🔴 大文档分批：20~30 chunk/批，全部批次由主 AI 亲自完成。

#### Step 3 — 自检

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

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

#### Step 4 — 关联所有知识元（⚠️ 仅此一次）

```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 — 重建根节点

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

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

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

#### Step 6 — 生成 HTML 知识地图并自动打开

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

完成后返回模块主菜单。

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

> 🔴🔴 **手工驱动模式（★ 铁律）**：此菜单全程由用户手动操作——用户选文件、用户确认处理、用户决定是否继续整理。**严禁在任何环节自动触发 maintain / crosslink / build-graph。** 即使用户一次性添加了全部未处理文档，A→F 全部完成后也只能回到"是否继续添加其他文档？"的询问。maintain 必须由用户通过菜单 6 或 7 手动启动。
>
> 🔍 扫描范围：递归扫描整个工作空间（跳过 AHKB 系统目录/隐藏目录/备份目录，排除根节点 .md 和知识地图 .html）。

#### 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 3 — 逐个处理选中文件

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

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

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

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

是否需要继续添加其他文档？
1. ✅ 是 — 回到 Step 1 重新扫描，继续挑选要添加的文档
2. ➡️ 否 — 返回模块主菜单

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

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

### 菜单 4 — 🔄 重新重点处理某一文档

> 用户觉得某个文档 AI 处理得不够好时，单独深入重新处理，弥补遗漏。
> 🔴 **只选一个文档**，聚焦精力重点处理。

#### Step 1 — 展示已处理文档列表

```bash
python {skill_dir}/kb/scripts/ahkb.py list-processed
```

展示所有已处理文档及其当前知识元数、chunk 数：

```
📋 知识库中已有以下文档：
  1. xxx.pptx → 原始文件/分类/  知识元: 15个
  2. yyy.docx → 原始文件/分类/  知识元: 3个
  ...
  0. ↩️ 返回主菜单

请选择要重点处理的文档（输入数字，只能选一个）：
```

> 🔴 **必须等待用户选择**，不可默认选第一个。

#### Step 1.5 — 询问用户嘱咐

用户选择文档后，**主动询问用户有没有什么嘱咐**：

```
你选择了：xxx.pptx
对于这个文档，你有没有什么想说的或要嘱咐的？
比如：
  - 上次漏掉了某个章节请重点看
  - 某个概念需要单独成元
  - 这次处理要更精细/更粗略
  - 其他任何要求

如果没有特别嘱咐，直接回复"没有"即可开始重新处理。
```

> 🔴 用户说了什么，AI 必须在重新分析时严格遵守。
> 🔴 如果用户没有特别嘱咐，按当前正常参数处理。

#### Step 2 — 清除旧知识元（保留 chunks 和资源）

```bash
python {skill_dir}/kb/scripts/ahkb.py clear-units-for-file "<相对路径>"
```

此命令仅做三件事：
1. 删除 `知识元/` 中 `source` 匹配该文件的所有 `.md` 知识元文件
2. 从 `_processed_docs.json` 中移除该文件的已处理标记
3. **不动** `chunks/` 下已有的分块数据和 `图片及其他资源/` 下的 .ctx/媒体文件

#### Step 3 — AI 重新分析（重点处理）

AI **读取已有的 chunks**（不再重复 extract），结合用户的嘱咐**逐段深入分析**：

```
🔄 正在重点处理：xxx.pptx
  使用已有的 N 个 chunks（复用提取结果），逐段重新分析...

  [1/M] 分析 chunk 1~25 → 生成知识元...
  [2/M] 分析 chunk 26~50 → 加载概念索引 → 去重后创建...
  ...
✅ 共生成 X 个知识元（上次仅 Y 个）
```

> 🔴 **逐段分析，不许跳过任何 chunk。** 分析前先加载概念索引，避免与已有知识元重复。
> 🔴 所有批次由主 AI 亲自完成，**禁止使用子代理**。
> 🔴 严格遵守用户的嘱咐。

遵循当前的 `cGranularity`/`cTextAmount` 参数设定，按正常标准生成知识元。

#### Step 4 — 验证、更新索引、标记

```bash
python {skill_dir}/kb/scripts/ahkb.py verify-units "<相对路径>"
python {skill_dir}/kb/scripts/ahkb.py update-concept-index
python {skill_dir}/kb/scripts/ahkb.py mark-processed "<相对路径>"
```

> 🔴 因旧知识元已清除、新知识元已写入，`mark-processed` 硬关卡可通过。

#### Step 5 — 询问是否刷新关联

```
文档已重新重点处理完成。是否刷新知识关联（知识元链接、资源挂接）？
1. ✅ 是，立即运行 maintain（推荐）
2. ➡️ 否，稍后通过菜单 6 自行处理
```

选 1 则执行：

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

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

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

完成后返回模块主菜单。

### 菜单 5 — 🖐 手动维护知识库资源

向用户简要说明后，**直接执行以下命令打开资源管理器 GUI（★ 禁止告诉用户手动执行）**：

```bash
python {skill_dir}/kb/scripts/ahkb.py manage-resources --workspace "<Vault路径>"
```

> 🔴 此命令 1 秒内返回 `"status": "detached"`，GUI 窗口已在独立进程中运行。
> 🔴🔴 **除非遇到 sandbox 拦截，否则 LLM 不得输出任何"请用户在终端中手动执行"之类的提示。直接跑。**

GUI 打开后，LLM 每回合轮询状态文件（必须使用绝对路径）：

```bash
python -c "
import json; from pathlib import Path
rf = Path('<工作空间>/临时工作文件/_resource_manager_result.json')
if rf.exists():
    r = json.loads(rf.read_text(encoding='utf-8'))
    if r.get('status') == 'closed':
        print(f'[关闭] 资源管理完成，初始 {r[\"initial_resources\"]} 个资源，最终 {r[\"final_resources\"]} 个资源')
    else:
        print('[等待]')
else:
    print('[等待] 窗口仍在运行中...')
"
```

> 🔴 **输出含 `[关闭]` → 汇总报告**
> 🔴 **其他输出 → 约 10 秒后再次轮询，不要重新启动资源管理器**

从维护界面退出后，提示用户：要想让维护生效，需依次执行菜单 6「自动整理知识库并更新知识链」、菜单 7「重建知识地图+HTML版」。

完成后返回模块主菜单。

### 菜单 6 — 🛠 自动整理知识库并更新知识链

运行 `maintain`，一次性完成三类关联（知识元↔知识元 `[[链接]]` + 知识元↔原始文件 + 知识元↔资源挂接）。

> 🔴🔴 **必须弹出 tkinter GUI 图形窗口**，让用户看到运行进度。严禁使用无头模式。
>
> ✅ **使用方式**（LLM 专用，解决超时截断问题）：
> ```bash
> python {skill_dir}/kb/scripts/ahkb.py maintain --detached --workspace <工作空间绝对路径>
> ```
> 此命令 1 秒内返回，GUI 窗口在独立进程中运行，不会被 LLM shell 超时截断。LLM 通过轮询临时文件获取进度。

**LLM 执行步骤：**

1. 执行上述命令，接收 JSON 返回
2. 若 `status` 为 `"already_running"`：
   - 告知用户："⚠️ 知识链构建任务已在运行中（PID: xxx），请等待当前任务完成，或手动关闭窗口后重试。"
   - 返回模块主菜单
3. 若 `status` 为 `"started"`：
   - 告知用户："✅ 知识链构建已启动（PID: xxx），独立窗口已打开。"
   - **每回合运行以下命令检查一次，直到 `status: "complete"`：**

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

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

   - `status: "complete"` → 汇总报告，继续菜单 7
   - `status: "cancelled"` → 返回主菜单
   - `status: "running"` / `"starting"` → 展示 `_display` 原文，约 10 秒后再次轮询
   - 🔴🔴 **其他状态 → 展示 `_display` 原文，等约 10 秒后再次轮询。禁止只内部检查不输出。**

> 🔴 `--detached` 模式下，GUI 窗口在独立进程中运行，LLM 命令 1 秒返回，不会被超时截断。
> 🔴 若返回 `status: "cancelled"`，说明用户手动关闭了窗口——不要重试，直接返回主菜单。
> 🔴 轮询期间不要阻塞对话——用户仍可发起其他操作。任务完成后继续菜单 7。

`maintain` 完成后自动执行菜单 7（重建知识地图 + HTML + 自动打开浏览器）。

完成后返回模块主菜单。

### 菜单 7 — 🏗 重建知识地图 + HTML

1. `python {skill_dir}/kb/scripts/ahkb.py build-graph`
2. `python {skill_dir}/kb/scripts/ahkb.py build-kg-html`
3. `python {skill_dir}/kb/scripts/ahkb.py set-graph-colors`
4. **自动打开知识地图**：`python -c "import webbrowser; webbrowser.open('<知识库名称>-知识地图.html')"`

> 🔴 `build-graph` 已自动将全部知识元写入根节点 `.md`，无需 AI 手工操作。第 1 步输出 JSON 供查阅，第 2 步 `build-kg-html` 直接读根节点生成 HTML。

#### 🔴 根节点 .md 规范（参考）

`build-graph` 已自动生成根节点 .md，包含以下内容（无需 AI 手工操作）：

```markdown
---
tags: [{{从units中统计的标签}}, 知识库, 根节点]
root_node: true
created: {{创建日期}}
updated: {{当前日期}}
---

# {{知识库名称}} 知识库

> 基于 AHKB-CPS v0.1.0 构建的全息知识库

## 📖 知识库概述

{{根据知识元内容总结，2~3句话描述知识库主题和涵盖领域}}

## 📊 统计信息

| 项目 | 数量 |
|------|:----:|
| 原始文件 | {{_processed_docs.json中的文件数}} 个 |
| 知识元 | {{units.length}} 个 |
| 资源文件 | {{统计 图片及其他资源/ 下非.ctx文件数}} 个 |
| 最后更新 | {{当前日期}} |

## 🗺️ 知识地图

> [打开交互式知识地图]({{知识库名称}}-知识地图.html)

## 📋 知识元列表（{{units.length}} 个，全量列出）

| 知识元 | 标签 | 来源 |
|--------|------|------|
{{遍历 units 每一个，逐行生成，禁止省略：}}| [[{{unit.name}}]] | {{unit.tags.join(', ')}} | {{unit.source}} |
{{以上 N 行对应 N 个知识元，N 必须等于统计信息中的知识元数}}

## 📋 处理清单

| 文件 | 状态 | 知识元数 |
|------|:----:|:--------:|
{{遍历 _processed_docs.json：}}| {{文件名}} | ✅ 已处理 | {{关联的知识元数}} |

## 🔗 关联模块

- 📊 [[幻灯片生成]] — 基于知识库生成演示文稿
- ✍️ [[文章生成]] — 生成结构化文章
- 🧠 [[全息脑图生成]] — 生成阿色全息脑图
```

> 🔴 **必须使用 `build-graph` 返回的真实数据**，不得编造或使用"待生成"/"—"等占位符。
> 🔴 **统计信息中的数字必须与 `units.length` 和实际文件数一致**。
> 🔴 **知识元数量为 0 时，知识元列表可省略，但统计信息中必须如实写 0**。

### 菜单 8 — 🌐 生成HTML版知识地图

```bash
python {skill_dir}/kb/scripts/ahkb.py build-kg-html
# 生成后自动在浏览器中打开
python -c "import webbrowser; webbrowser.open('<知识库名称>-知识地图.html')"
```

### 菜单 9 — 📊 知识库统计

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

展示统计结果（知识元数量、资源数量、标签分布等）。完成后提示用户下一步可以做什么（如打开Obsidian查看、执行其他菜单等）。

完成后返回模块主菜单。

### 菜单 s — ⚙ 设置

打开图形界面调整知识库参数（颗粒度、链接权重等）。

```bash
python {skill_dir}/kb/scripts/ahkb_set_project.py --workspace "<Vault路径>"
```

所有权重保存在 `系统设置/project_settings.json`。

完成后提示用户：如果参数有修改，它们要在下次生成知识元或整理知识库时才生效。

完成后返回模块主菜单。

---

## 参考：参数说明

**链接权重（影响知识元↔资源匹配）：**

| 参数 | 最高分 | 说明 |
|------|-------|------|
| `cContext` | 100 | 上下文描述相关性 |
| `cTags` | 100 | 关键词标签相关性 |
| `cStars` | 10 | 资源重要性 |
| `cEdited` | 2 | 用户手动编辑过 |

**总体参数（影响知识库构建行为）：**

| 参数 | 说明 |
|------|------|
| `cGranularity` | 颗粒度：0→精细 / 0.5→均衡(默认) / 1→粗粒 |
| `cTextAmount` | 详细程度：0→摘要 / 0.5→适中(默认) / 1→详细 |
| `cLinksDensity` | 值越大每个知识元链接越多 |
| `cLinksNum` | 值越大单个知识元链接上限越高 |

---

## 错误处理

### 文件提取失败
`ahkb.py extract` 返回 `error` 时，展示错误信息，询问用户重试或跳过。

### 知识元数量过多
单个文档超过 10 个知识元时，分批次处理（每批 5 个）。**🔴 必须循环处理所有批次直至全部完成。所有批次必须由主 AI 亲自顺序完成，禁止使用子代理。**

---

# 返回

**用户选择 `e` 时：返回 AHKB-CPS 统一主菜单。**


