Oh My KB 三层架构改造方案

基于 Anthropic Claude Code 官方设计模式 · 2026.06

一句话

Hooks 管"什么不能做"→ Skills 管"怎么做"→ Agents 管"谁来做"。三层协作，各司其职。

一、目标架构总览

🔧 Hooks
自动护栏
→
📦 Skills
知识注入
渐进加载
→
🤖 Agents
隔离执行
层数量位置角色
Hooks3 个.claude/settings.json自动触发，无需 Agent 判断
Skills35 个（主 Agent）.claude/skills/知识注入，渐进加载
Agents3 个子 Agent.claude/agents/隔离执行，并行处理

二、Hooks 层（3 个）

不依赖 Agent 判断，事件驱动自动执行。

Hook事件做什么理由
PostToolUse:Write 写入 raw 文件后 检查文件命名是否含全宽标点/特殊字符 → 告警 文件名编码问题是 69% 断裂链接的根因
PreToolUse:Bash(rm *) 删除文件前 拦截对 原始素材 (raw)/ 的删除操作 raw 只读只追加的硬约束
SessionStart 新会话启动 加载 memory/ 文件（recent/user_profile/feedback/mayfair-status） 替换手动加载，自动化

三、Skills 层（35 个，渐进加载）

CC 官方的渐进加载：metadata（~100 词）→ SKILL.md 正文（≤500 行）→ resources/（无限制）。主 Agent 始终只载入 35 个技能的 metadata，总共约 4000 词 ≈ 5000 token。触发时才加载完整 SKILL.md。

主 Agent 直管 28 个

高频操作 · 需主 Agent 上下文连贯

类别技能
摄入 (10)kb-fetch-wx / x / github / github-trending / web / reddit / feishu / futu / xueqiu / trendradar
编译 (3)kb-compile / kb-compile-health / kb-research
投资 (6)kb-invest-report / signal / risk / normalize / review / kb-report-finance
记忆 (4)kb-memory-extract / kb-memory-distill / kb-report-daily / kb-qa
工具 (5)kb-deploy-pages / kb-tools-logo / kb-search-github / kb-publish / kb-backup

子 Agent 专属 7 个

低频无交互 · 独立上下文即可

归属技能
invest-agentsignal / risk / normalize / report
distill-agentmemory-distill + extract
health-agentcompile-health

注：子 Agent 只持有它需要的技能，不加载其他

SKILL.md 规范（每个文件必须遵守）

---
name: kb-fetch-wx
description: "Use when user pastes a WeChat public account URL (mp.weixin.qq.com). Triggers on any mp.weixin.qq.com URL."
disable-model-invocation: false
allowed-tools: Bash Read Write WebFetch
context: default
---

# kb-fetch-wx — 微信公众号抓取

## 触发条件
- 用户发送 mp.weixin.qq.com URL
- 用户说「抓取公众号」「剪藏微信文章」

## 执行流程
1. 重复检测（grep source URL）
2. 检查 Cookie 配置
3. 运行 wx_fetcher.py
4. Read 生成文件，输出结构化总结

## Gotchas
- Cookie 过期 → 提示用户更新
- 正文为空 → 文章可能是付费/受限内容
- 文件名含特殊字符 → 需人工修正

## 参考（加载时展开）
→ references/wx-fetcher-details.md

四、Agents 层（3 个子 Agent）

每个子 Agent 是 isolated context，不继承主 Agent 对话历史。主 Agent 通过 Task 描述传递所有需要的信息。

Agent触发工具模型典型耗时
kb-invest-agent 用户说「盘前/盘后分析」「投资分析」 WebSearch WebFetch Read Write Bash Sonnet ~20s
kb-distill-agent 「蒸馏记忆」「Task 2」 Read Write Bash Glob Opus ~60s
kb-health-agent 「健康检查」「health check」 Read Bash Glob Sonnet ~30s

Agent 定义示例

# .claude/agents/kb-invest-agent.md

你是 Oh My KB 的投资分析子 Agent。独立上下文，不继承主对话。

## 可用工具
WebSearch, WebFetch, Read, Write, Bash

## 工作流
1. WebSearch 获取行情数据（美股/港股/A股/大宗商品）
2. Read 关注列表 → 匹配当前持仓
3. 生成早盘/盘后简报
4. Write 到 输出 (outputs)/投资分析/

## 约束
- 不修改 raw/ 下任何文件
- 所有 wikilink 必须 ls 确认文件名
- 输出 <= 200 字，30 秒可读完

五、文件结构

.claude/
├── settings.json          # Hooks + Permissions
├── settings.local.json    # 个人覆盖（gitignored）
├── agents/
│   ├── kb-invest-agent.md
│   ├── kb-distill-agent.md
│   └── kb-health-agent.md
└── skills/
    ├── kb-fetch-wx/SKILL.md      # metadata ~80词
    ├── kb-fetch-wx/references/   # 详细文档
    ├── kb-fetch-x/SKILL.md
    ├── kb-fetch-github/SKILL.md
    ├── kb-compile/SKILL.md
    ├── kb-invest-report/SKILL.md
    ├── kb-deploy-pages/SKILL.md
    └── ...（共 35 个 skill 目录）

六、改造前后对比

维度改造前改造后
主 Agent skill 数50+28（-44%）
主 Agent prompt tokens~8KB~4KB（-50%）
投资分析主 Agent 直管子 Agent 隔离
自动护栏依赖 Agent 判断Hooks 自动执行
文件保护CLAUDE.md 文字约束Hook 硬拦截
技能加载全量加载渐进加载
扩展成本加一个改 CLAUDE.md加文件夹即加技能

七、实施路线

Phase内容时间风险
1 创建 3 个 Hooks（PostToolUse + PreToolUse + SessionStart） 10min 低
2 创建 3 个子 Agent 定义文件 15min 低
3 为 28 个主 Agent 技能补全 SKILL.md frontmatter（description + allowed-tools） 40min 中 — 大部分已有 SKILL.md，补 metadata 即可
4 更新 CLAUDE.md → 改为三层架构 + 路由规则 20min 中
5 测试：fetch → compile → invest → distill → health 全链路 30min 中 — 子 Agent 的 prompt 需要调优

Oh My KB · 基于 Anthropic Claude Code 官方三层架构