KM Pipeline 全流程文档 Knowledge Management · 知识图谱自动管理闭环

版本: v3 (2026-04-16) · 位置: ~/Desktop/skill-knowledge-base/ · git 仓库已就绪

1. 系统概览

目标：把 Claude Code 的日常对话自动萃取成结构化知识，合并进 88 个 skill 的 *_knowledge.md，越用越聪明。

核心理念

• 增量触发：每次跑 run.sh 只处理 last_ts.txt 之后的新对话
• 三阶段过滤：S0 规则删噪 → S1 语义过滤 → S2 结构化萃取
• 按 session 分批：以对话 session 为自然边界切分，每批 ≤15KB（规避 Cloudflare WAF）
• 三级退化：OpenRouter 挂了走 claude -p 本地
• 一键闭环：extract → merge → validate → commit，失败可回滚

架构图

2. 核心组件

3. 数据流 · 三阶段管线

规则：
1. 删除：闲聊、确认（"好的""继续"）、调试中间过程、重复描述
2. 保留：bug 发现/修复、配置变更、架构决策、新功能实现、踩坑记录
3. 保留原文！不要摘要、不要改写。加段落标注 --- [skill] [ADD/UPDATE] 标题 ---
4. 删除元讨论（知识库系统本身的讨论）
5. 保留时间戳 [2026-xx-xxTxx:xx:xx.xxxZ]
6. 不使用任何工具 · 直接输出纯文本

### 2026-04-16 skill-name ADD
- 变更描述（含硬数据）
- 源: session_xxx

### 2026-04-16 skill-name UPDATE
- 变更描述
- 源: session_xxx

4. 模型选择依据（6 Agent 实测）

2026-04-16 并行起 6 个 subagent，在 3 个代表性 session（6K/27K/48K chars）上测 7 个 OpenRouter 模型。

5. 关键参数

6. 三级退化链路

S1 调用流程
  ├─ 主路径:    OpenRouter anthropic/claude-haiku-4.5:nitro  × retry=2
  │               ├─ 成功 → 进入 S2
  │               └─ 失败
  ├─ 兜底 1:    OpenRouter deepseek/deepseek-v3.2-exp:nitro × retry=2
  │               ├─ 成功 → 进入 S2
  │               └─ 失败
  └─ 兜底 2:    claude -p --model sonnet (本地)
                  └─ 成功 → 进入 S2（~100-200s/批）

S2 调用流程
  ├─ 主路径:    claude -p --model opus (本地)
  └─ 兜底:      OpenRouter anthropic/claude-opus-4-6

7. 已知问题与外部约束

7.1 OpenRouter / Cloudflare WAF 限制

7.2 Message 结构敏感

把 prompt + 对话拼在单个 user message 里，OpenRouter WAF 命中 "超长 user message" 规则。拆成 system(prompt) + user(对话) 可绕过。

已抽出 call_openrouter_split(model, system_prompt, user_content, ...) 函数。

7.3 本地路由器 Clash fake-IP

路由器 192.168.31.1 跑 OpenWrt + Clash TUN 模式，openrouter.ai 被劫持解析到 198.18.13.4（TEST-NET-2 段）。TLS 握手 + 证书都 OK，但路由器代理对大 body 缓冲不够会断连。根本解: 路由器 Clash 加规则 openrouter.ai → DIRECT。

7.4 claude -p SDK 慢

sonnet 直调 OpenRouter 9s 完成，同样请求经 claude -p 545s。瓶颈在 SDK / tool loop / stdin 处理，非模型本身。但 claude -p 是退化链路最后一环，慢但 100% 不走代理层。

7.5 minimax 输出在 reasoning 字段

推理模型 CoT bug: content="" 但 reasoning 有内容。call_openrouter_split 已 fallback 到 reasoning。

8. 已修复的 3 个硬 Bug commit 125eb39

未修复（判断不该修）

• #2 S1 慢: 当时以为 claude -p 545s 是 bug，后发现是 SDK 本身慢，网络代理/模型都 OK
• #5 4 FAIL 未阻断: 都是历史遗留空章节，阻断反而误杀
• #6 Step 4 冗余: 设计是对的（merge 已 commit，Step 4 本应空）

9. 性能与成本

9.1 一轮典型运行（2026-04-16 12:12 commit a81ae95）

9.2 S0 压缩效果（3 样本实测）

9.3 成本（单次 S1 过滤，估算）

10. 运行方式

一键全流程

cd ~/Desktop/skill-knowledge-base
bash scripts/run.sh

# 等 run.log 出现 "===== 完成 (1135s, 12 条知识) ====="

独立步骤

# 只跑 extract
bash scripts/extract.sh

# 只跑 merge (MERGE_MODEL=sonnet 或 opus)
MERGE_MODEL=sonnet bash scripts/merge.sh

# 只跑 validate
bash scripts/validate.sh

重置状态（调试用）

# 清空日志和 changelog, 把 last_ts 回退 2 小时
> changelog.md
> scripts/extract.log
python3 -c "from datetime import datetime, timedelta, timezone
ts = datetime.now(timezone.utc) - timedelta(hours=2)
print(ts.strftime('%Y-%m-%dT%H:%M:%S.000Z'))" > last_ts.txt

观察

• git 历史浏览（klaus）: localhost:3023
• S1 过滤前后对比: localhost:3024
• 本文档: localhost:3025

11. 后续优化方向

1. 路由器 Clash 规则: 把 openrouter.ai / api.anthropic.com 加入 DIRECT，治本而非治标
2. S0 tool 参数精简扩展: 当前覆盖 Read/Bash/Grep/Edit/Write/TaskCreate，可加更多工具
3. S1 内容脱敏兜底: 敏感词（wx.config/sk-xxx/URL）触发 WAF 时做 placeholder 替换（仅异常路径）
4. batch 并发: 目前 20 个 batch 串行跑，可并发 3 路让小 batch 填空档
5. 增量游标粒度: 当前基于文件 mtime 的 last_ts，可改为 JSONL line cursor，更精确
6. 知识图谱可视化: shared_schema 已定义 17 实体+14 关系，下游可构建查询 UI
7. validate 自动修 WARN: 空章节类 WARN 可由 AI 自动补全（引用 skill.md）

附录：重要提交历史