三个优化让知识库流水线更聪明

总这文档讲什么?

今天我们把整个知识库流水线大改了一遍,跑通了。但跑的过程中暴露了 3 个值得修的问题。这文档把这 3 个问题用大白话讲清楚,让任何人(不需要懂代码)都能看懂为什么要改、改了能省什么。

1summarize_skill.py 增量模式

每次更新目录,系统都要重写所有 98 本书的简介,但实际只有 13 本书改了内容。

问题:浪费 86% 的力气

$ python3 scripts/summarize_skill.py --all --parallel 3
# 结果:5.5 分钟,跑了 98 次 LLM 调用

当前代码长什么样

现在 summarize_skill.py 只有两种模式:

# 模式 1:跑单个 skill
python3 scripts/summarize_skill.py cpmiao-main

# 模式 2:跑全部 98 个 skill
python3 scripts/summarize_skill.py --all --parallel 3

没有"只跑变更过的"这个模式,所以每次 merge 完只能用 --all,导致 85 次浪费的 LLM 调用。

改进方案:加一个 --changed-from 参数

# 新增第三种模式
python3 scripts/summarize_skill.py \
    --changed-from changelog.md \
    --update-in-place GLOBAL_INDEX.md

# 系统行为:
# 1. 解析 changelog.md,提取出受影响的 skill 名(比如 13 个)
# 2. 只对这 13 个 skill 跑 LLM
# 3. 读现有 GLOBAL_INDEX.md,把这 13 行覆盖,其他 85 行保留
# 4. 写回 GLOBAL_INDEX.md

核心代码示意

def changed_skills_from_changelog(path):
    """从 changelog 解析出受影响的 skill 名"""
    affected = set()
    pattern = re.compile(r'^### .+ \[(?:ADD|UPDATE|DELETE|NEW_SKILL)\] (\S+) →', re.M)
    for m in pattern.finditer(open(path).read()):
        affected.add(m.group(1))
    return affected

# changelog 解析示例:
# ### 2026-04-16T20:34 [UPDATE] cpmiao-main → § 用户注册流程
# ### 2026-04-16T20:35 [ADD] knotchat-paypal → § 退款接口
# 解析结果:{cpmiao-main, knotchat-paypal} 这 2 个 skill

收益对比

边界情况处理

2merge.sh 删 Step 4,改调 summarize_skill

现在系统里有两套更新目录的逻辑,它们写出来的目录格式不一样,长期会打架。

问题:两个人在改同一本目录,规则还不一样

更深层的问题:两套规则打架

现在系统里有两套更新目录的逻辑:

问题来了:每次 cron 跑完 merge.sh,目录被路径 A 改成"小变化版";然后我手动跑路径 B,又改成"v2 详细版"。两个版本反复覆盖,目录里最终长什么样取决于谁最后跑。

当前流程图

改进方案:删 Step 4,改成 Step 5 调用 summarize_skill

把 merge.sh 里 L450-577 整个 Step 4(用 opus Edit 改 INDEX 的逻辑)删掉,换成:

# merge.sh 末尾新增 Step 5
echo "[$(date +%H:%M:%S)] === Step 5: 增量更新 INDEX § 1 ===" >> "$LOG"

python3 "$BASE/scripts/summarize_skill.py" \
    --changed-from "$CHANGELOG" \
    --update-in-place "$BASE/GLOBAL_INDEX.md" 2>>"$LOG"

if [[ $? -eq 0 ]]; then
    echo "[$(date +%H:%M:%S)] INDEX § 1 已更新" >> "$LOG"
else
    echo "[$(date +%H:%M:%S)] WARN: INDEX § 1 更新失败,保留旧版" >> "$LOG"
fi

改进后流程图

不再有第二条手动路径,只有一个统一入口。

为什么这个方案靠谱?

• 确定性:summarize_skill 是脚本,4 步固定流程 + 单点 LLM 提取定义,不会"偷懒"
• 规范统一:输出永远是 v2 规范的 7 列详细表,不会有时是 6 列有时是 7 列
• 速度快:增量模式 ~1 分钟 vs Step 4 用 opus Edit ~2 分钟
• 可观测:summarize_skill 输出每个 skill 的耗时和结果,Step 4 是黑盒

风险与防御

收益

3失败 skill 自动重试队列

某个 skill 三级退化全失败时,内容会随 changelog 清空而永久丢失。

问题:数据可能悄悄丢失

[20:37:12] 合并 port-monitor...
[20:37:45] WARN: claude-p opus 失败 rc=1
[20:38:21] WARN: cursor-agent claude-4.6-opus 失败 rc=3
[20:38:55] ERROR: OpenRouter 失败 (Remote end closed connection)
[20:38:55] ERROR: port-monitor 失败(认证/限流)

当前代码在哪里崩

merge.sh Step 2 失败分支(简化版):

# 当前
if [[ failed ]]; then
    echo "[$(date)] ERROR: $skill 失败" >> "$LOG"
    # 啥都不做,直接放弃
fi

# Step 6 后续
> "$CHANGELOG"  # 清空 changelog,失败 skill 的内容也一起没了

改进方案:三件套

(1) retry queue 目录结构

~/Desktop/skill-knowledge-base/tmp/retry_queue/
  ├── port-monitor_2026-04-16T20-37.changelog
  ├── cpmiao-main_2026-04-16T20-39.changelog
  └── _index.json
      # {
      #   "port-monitor": {
      #     "retry_count": 1,
      #     "last_attempt": "2026-04-16T20:37",
      #     "original_ts": "2026-04-16T20:37"
      #   }
      # }

(2) merge.sh Step 2 失败时:切片暂存

if [[ failed ]]; then
    # 从 changelog 切出该 skill 的段落
    skill_changelog=$(python3 -c "
import re
content = open('$CHANGELOG').read()
matches = re.findall(
    r'(### [^\n]+ → § ' + '$skill' + r'.+?)(?=\n### |\Z)',
    content, re.S
)
print('\n'.join(matches))
")

    if [[ -n "$skill_changelog" ]]; then
        retry_file="$BASE/tmp/retry_queue/${skill}_$(date +%Y-%m-%dT%H-%M).changelog"
        echo "$skill_changelog" > "$retry_file"
        echo "[$(date)] $skill 内容已暂存 retry_queue" >> "$LOG"
    fi

    echo "[$(date)] ERROR: $skill 失败(已存 retry_queue)" >> "$LOG"
fi

(3) merge.sh 入口加 Step 0:消化 retry queue

# Step 0(在 Step 1 之前)
if ls "$BASE/tmp/retry_queue/"*.changelog 2>/dev/null; then
    echo "[$(date)] === Step 0: 处理 retry_queue ===" >> "$LOG"
    cat "$BASE/tmp/retry_queue/"*.changelog >> "$CHANGELOG"
    mv "$BASE/tmp/retry_queue" "$BASE/tmp/retry_queue.processing"
fi

# 末尾(commit 成功后)
if [[ -d "$BASE/tmp/retry_queue.processing" ]]; then
    for f in "$BASE/tmp/retry_queue.processing/"*.changelog; do
        skill=$(basename "$f" | cut -d_ -f1)
        if grep -q "$skill 完成" "$LOG"; then
            rm -f "$f"  # 这次成功了,从队列移除
        else
            mv "$f" "$BASE/tmp/retry_queue/"  # 仍失败,放回队列
        fi
    done
    rm -rf "$BASE/tmp/retry_queue.processing"
fi

完整流程示意

边界 case

收益

合三项一起做的最终架构

三项独立都有价值,但整合后会形成一个完整的、自愈的、可观测的流水线。

对比:今天 vs P0 实施后

今天的流水线

P0 实施后的流水线

整体收益对比

施实施建议

总工作量约 2 小时,可以拆 3 步独立实施,每步 commit 可单独 revert。

执行方式

不做的代价

做完之后的下一步(P1 项)

如果 P0 三项都做完了,P1 还有这些可以考虑:

• Hub fallback + 关联 LLM 提取:把 INDEX 完整度从 70% → 90%(今天发现 Hub 缺 54%)
• merge.sh OR 兜底 prompt 切片:大 skill 不超 OR 16K token 限制
• cron 失败告警:extract.log 有 ERROR 触发企业微信通知