Oh My KB — Agent & Skill 设计理念（团队参考）

Oh My KB — Agent & Skill 设计理念

这是 Oh My KB（无重的私人助理 + 知识库 Agent）运行大半年的设计沉淀。不是理论，是每天 11 个 cron + 21 个 skill + 3 个子 Agent 在跑的实战体系。给团队参考，落地 Harness 时按需取用。

一、设计哲学：五条铁律

1. Thin Harness, Fat Skills（瘦驾驶舱，胖技能）

驾驶舱（CLAUDE.md）只放原则 + 路由 + 高频输出规范，约 200 行。所有领域细节放 skill 文件，按需加载。

为什么：驾驶舱每次会话全量进上下文。塞细节 = 每条对话都付 token + 模型注意力被稀释。瘦驾驶舱 = 低固定成本 + 高信号噪声比。

反面：把"飞书 API 字段说明""投资评分公式"写进 CLAUDE.md → 每次会话烧 token，且改一处要动全局。

2. 渐进式披露（Progressive Disclosure）

信息按"需要时才读"分层：metadata → SKILL.md → references/codemap/checklist。

• metadata（frontmatter description）：路由判断用，~1 行
• SKILL.md：控制流（触发→步骤→指针），不堆细节
• references/：模板/规范/配置，具体阶段才读
• codemap.md：复杂 skill 的"读哪个文件"触发机制

实测数据（SkillJuror 论文）：精准按需加载让每次任务触及的引用文件从 1.18 → 3.85（+226%）。

铁律：references 触发条件必须三步式——{什么内容} → {哪个文件} → {什么时候读}。禁止"详情见 references/xxx.md"这种等于没写的指针。

3. 模型 vs 脚本分工

凡是看了不满意会让你重做的东西，用脚本锁死。凡是换一种说法也行的事情，交给模型。

判断标准：这一步产出你看了会不会不满意到要求重做？会 → 脚本。换一种措辞也能接受 → 模型。

新 skill 创建前必填一张表：步骤 → 执行者 → 要求 → Know-how。表有了，写 SKILL.md 和脚本只是执行。

4. 知识 vs 编排分离（Anthropic L4）

• Skill = 被动的领域知识，"教怎么做"（如何建 DCF、如何写总结），不含流程/时序
• Agent = 工作流编排者，有身份、交付物清单、编号步骤、护栏，消费 Skill 如 PM 消费专家知识
• MCP 连接器 = 集中式数据访问层，一处定义多处消费，换数据源只改一处

核心原则：Skill 不含流程逻辑——流程属于 Agent。定义交付物而非目标（防范围蔓延）。声明负面空间（每个 Agent 写清"永远不做什么"）。Deny-by-default 工具（从全禁起步，只显式开需要的）。

5. 修问题即加规则

每次踩坑修复后，必须在对应 SKILL.md / CLAUDE.md / rules 加约束。不沉淀的修复等于没修——下次还会犯。

进阶：L4 持续学习闭环——Critic FAIL 逐条记 patterns.md，≥3 次同类 FAIL 升级为永久规则进 optimizations.md；单次严重 FAIL（数据丢失/推送失败/持仓漏查）立即升级不等 ≥3 次。

二、架构分层：三层 + 内容五分法

三层架构：Hooks → Skills → Agents

Hooks（确定性执行，PreToolUse/UserPromptSubmit）
   ↓
Skills（领域知识 + 执行流程 + 脚本，按需加载）
   ↓
Agents（工作流编排，路由器启动子 Agent，独立上下文）

• Hooks：硬护栏靠它（raw 只读、隐私数据保护、关键词路由注入）
• Skills：21 个主 Agent 技能 + 8 个子 Agent 持有技能，同目录逻辑隔离
• Agents：3 个路由器（finance/memory/knowledge）→ 3 个子 Agent

内容五分法：东西放哪

铁律：所有 rule 必须带 paths frontmatter——无 paths 的 rule 是分散版 CLAUDE.md，启动即加载全程占 token，违反 Thin Harness。

三、Skill 设计规范

三层文件结构

简单（路由器）：   SKILL.md
中等（工具类）：   SKILL.md + codemap.md
复杂（领域子技能）： SKILL.md + codemap.md + checklist.md + procedures/ + references/

SKILL.md vs references 边界

一条铁律：SKILL.md = 控制流，references = 数据/细节。

判断标准：需不需要每次执行都读？ 每次必走 → SKILL.md。按需或异常才读 → references。

命名规范

kb-{type}-{domain/action}，前缀定角色：

命名决策：先问"谁执行"→ 再问"什么域"→ 选前缀。

codemap 设计模式

codemap 是渐进式披露的触发机制，解决"Agent 面对 5+ 文件不知道读哪个"。三列表：

原则：每个文件一行写清"什么时候才需要读"；不列 scripts/（不读，直接执行）；按执行顺序排；SKILL.md 必须有指针"首次或不确定时读 codemap.md"。

四、Agent 设计规范

路由器 + 子 Agent 模式

主 Agent 不直接调用子 Agent 的技能——走路由器：

cron / 用户触发 → 主 Agent 匹配路由 skill（kb-route-*）
   → Agent 工具启动子 Agent
   → 子 Agent 预加载完整 SKILL.md（frontmatter skills 声明）
   → 逐步执行（含存档 + 日志）→ 返回蒸馏结果

逻辑隔离而非物理隔离：子 Agent 持有的技能物理上和主 Agent 技能同目录，靠 agent 定义文件的 skills: frontmatter 声明预加载。

Anthropic L4 Agent 模板

每个 Agent 定义包含：

1. 身份：是谁、消费哪些 Skill
2. 交付物清单：具体产出物（防范围蔓延）
3. 编号步骤工作流：1→2→3，含存档路径 + 日志格式
4. 护栏：永远不做什么（声明负面空间）
5. Deny-by-default 工具：从全禁起步，只显式开需要的
6. 隔离不受信内容：读外部文档的 Agent 不碰工具和系统

子 Agent 上下文隔离

子 Agent 用 context: default 独立上下文，返回 JSON/蒸馏结果，父 Agent 只收结论不收原始过程。多 Agent 成败在 handoff 时上下文大小的精准控制。

五、编排模式速选（四层体系）

速选指南

• 新建 Skill：先 L3 工具包装器；输出固定格式 → L3 生成器；多步骤 → L3 流水线
• 新建 Agent：先 L2 单智能体（从简单开始）；多步质量控制 → L2 审核评判；动态路由多专家 → L2 协调器
• 多 Agent 协作：可并行 → L2 并行；顺序依赖 → L2 顺序；开放式复杂 → L2 分层分解；多专家辩论 → L2 集群
• 改进现有：输出不稳 → L1 反思 + L2 迭代优化；需更多上下文再行动 → L3 倒置；检查逻辑与业务耦合 → L3 审阅者（检查清单独立化）

Oh My KB 已覆盖

• L1 反思 = Critic 子 Agent；L1 工具使用 = 所有 fetch/tools skill；L1 规划 = research 流程；L1 多智能体 = 3 路由器+子 Agent
• L2 单智能体 = 非路由器 skill；L2 并行 = research 四路并行；L2 顺序 = 编译/记忆管道；L2 协调器 = 三个路由器；L2 审核评判 = Critic
• L3 工具包装器 = 所有 references/；L3 生成器 = qa 模板；L3 审阅者 = Critic（部分，标准待独立化）；L3 倒置 = 缺失；L3 流水线 = 部分（顺序有，显式门控缺）
• L4 = CC 三层架构（Hooks→Skills→Agents）

六、记忆与验证：两条复利护城河

记忆层（moat 是记忆，不是 prompt 或工具）

三层记忆架构：

启动加载顺序（按优先级，非全量）：recent.md → cron 日志近 2 天 → user_profile → mayfair-status(14d) → feedback → stable 按需 → family 按话题触发。

关键原则：Access ≠ Awareness。不在上下文里的东西对模型来说不存在。所以启动加载要按话题路由，不是全塞。

蒸馏四路并行：会话摘要 / 飞书摘要 / 聊天记录 / 财务数据源 → 子 Agent 各自逐篇 Read → 合并 → Critic 审查 → 写入 → stable 主动审计 → 归档。

验证层（Task→Output→Verify→Fix→Done）

每个产出的 skill 都内嵌验证：抓取类有四源交叉 + 自检 9 项；蒸馏有 Critic 4 项审查；投资有 Critic 4 维度。

L4 持续学习闭环：

Critic FAIL → 逐条记 patterns.md
   → ≥3 次同类 FAIL 升级 optimizations.md（永久规则）
   → 标 ⏳ 验证中，下次蒸馏检查复发
   → 无复发 ✅ 已验证 / 复发 ❌ 回滚或加强

质量趋势预警：PASS 饱满度连续 2 周下降 ≥0.5 → ⚠️ 恶化；连续 3 周下降 → 🔴 人工介入。

七、Cron / Loop 设计原则

Cron prompt 只写触发短语

✅ "执行投资早盘分析"
❌ "拉取富途行情+雪球讨论+计算信号+存档到 outputs/投资分析/2026-07-03.md"

全部业务逻辑（执行步骤+存档路径+日志格式）必须在对应 SKILL.md 中自包含。触发路径：cron → 主 Agent 匹配路由 skill → 子 Agent Read 完整 SKILL.md → 逐步执行。

为什么：prompt 嵌步骤 = 改流程要改 cron 配置 = 多一处维护。逻辑在 SKILL.md = 一处真值 + 可被人工触发复用。

Loop Engineering

• /goal [task] until [可测终态] without [约束] — 目标驱动
• /loop [prompt] --interval 30m --expires 8h — 定时重跑
• 外环（人定方向）→ 内环（agent 规划+执行+验证）→ 修正环（Critic）

关键：停止条件必须可程序化测量。模糊目标（"改善体验"）→ 不如定（"time-to-interactive < 1s"）。

八、护栏与可观测

护栏四层纵深

硬约束靠 hook，解释靠 path-scoped rule。raw 只读、wiki 由编译维护、隐私数据禁部署——这三条有 PreToolUse hook 拦截 + rules/ 文件解释。

可观测

• Traces：cron 日志（每日 .md）+ session 摘要 + L4 patterns.md
• Metrics：健康检查六维 20+ 指标，趋势对比，A~C 评级
• A/B Testing：❌ 待补

九、自治层级定位（Addy 框架）

按 Addy Osmani 双轴六层（agency × orchestration，L0–L5）：

整体卡在 L2→L4 爬升段，6/26 Harness 是奔 L5 的路线图。

核心论点（Addy）：自治天花板不是任务名，是风险+可逆性+验证。每次跑 agent 前签 contract：目标/范围/非目标/工具权限/停止条件/证据/升级/预算。验证永远是瓶颈。

十、成本控制：10-80-10 模型路由

Fable 5 是 Opus 4.8 的 2 倍价且过度思考。用 Anthropic 工程师自用的 10-80-10：

• 前 10% 规划：Fable 做架构/成功标准/约束
• 中 80% 执行：Opus 4.8 / Haiku / DeepSeek（便宜模型）
• 末 10% 审查：Fable 复核对齐计划（审查成品比从零生成省 token）

Oh My KB 已在用模型路由（主 Agent / 子 Agent / Critic）+ DeepSeek 缓存（命中率 98%+）做这件事。7/7 Fable 转按量后，cron 执行层必须显式切便宜模型，Fable 只留规划 + Critic 两段。

十一、四大反模式（必须避免）

十二、1990 年代基本功（立党提醒，agent 时代依然成立）

让 AI Agent 写好代码的秘诀全在 1990 年代教材里：

1. 踏踏实实写 test，拉高 coverage
2. 认真做 CI/CD，千方百计防 messed up
3. 新项目 top-down spec-driven（从 feature/requirement 出发设计 architecture 和 interface）
4. 快速增长项目先切文件→切 module→拆 service，提前解耦
5. 一类功能提前做 design pattern，减重复增复用
6. codebase 够大就提高 test coverage 增量修，或保 spec+test+interface 推倒重写——"永远重写"

外部化约束是 Agent 可靠运行的必要条件（Code Review/Unit Testing/CI/CD/灰度拦截 AI Agent）。agent 越强，越要把这套基本功捡回来——不是新魔法。

十三、团队上手清单

新建 Skill 时

1. 拆步骤：从触发到输出分几步？
2. 标执行者：每步过"模型还是脚本"铁律
3. 填表：步骤 → 执行者 → 要求 → Know-how
4. 搭三层：需要 scripts/ 吗？references/ 吗？
5. 写 SKILL.md：只放路由+步骤+触发条件，代码进 scripts/
6. 验证：最可能幻觉的那步——脚本锁死了吗？

新建 Agent 时

1. 先 L2 单智能体（从简单开始），别一上来就多 Agent
2. 定义：身份 / 交付物清单 / 编号步骤 / 护栏（永远不做什么）
3. Deny-by-default：工具从全禁起步，只显式开需要的
4. 子 Agent 独立上下文，返回蒸馏结果不返原始过程
5. 高准确率场景加 Critic（L2 审核评判）

设计流程时

1. cron prompt 只写触发短语，逻辑进 SKILL.md
2. 停止条件必须可程序化测量
3. 每步产出加验证（Task→Output→Verify→Fix→Done）
4. 踩坑后立即在 SKILL.md/CLAUDE.md/rules 加约束
5. Critic FAIL 进 L4 闭环：patterns → ≥3 次升级 optimizations

取舍原则

• Haiku + 好指令 > Opus + 烂指令。AI 生成的指令反加噪声，人写的才有效
• 简单任务不要为了 Skill 而 Skill。触发→执行→完成没精确计算/格式/查询 → 一个 SKILL.md 够
• 能单 Agent 解决就别多 Agent。多 Agent 增加开销（路由 LLM 调用 + handoff 上下文丢失），只在工具过载（>10 重叠工具）或任务域明显分离时拆

附：核心参考

内部规范（kb-docs/）

• agent-design-patterns.md — L1-L4 四层模式体系（Andrew Ng 4 + Google Cloud 12 + Google 5 + Anthropic 3）
• skill-creation-guide.md — 模型 vs 脚本分工 + 三步拆解 + 命名规范
• agentic-engineering-concepts.md — 六层 30 概念 + Oh My KB 自检（综合 A-，26/30）
• claude-directory-architecture.md — 内容五分法决策流程
• memory-architecture.md — 三层记忆 + 蒸馏四路并行

外部文章（raw/）

• Addy Osmani《Agentic Autonomy Levels》— 双轴六层 + 验证瓶颈 + 四反模式
• Rahul《How To Build a One-Person Company With Claude Fable 5》— company brain + 记忆层是 moat + 验证层
• Miles Deutscher《How to Use Claude Fable 5 Without Going Bankrupt》— 10-80-10 模型路由
• Phil Chen《Career advice in the age of AI》— 选问题 + 配资源 > 解题
• lidang 立党《让 AI Agent 好好写代码的秘诀都在 1990 年代教材里》— test/CI/spec/解耦/重写

这套体系不是一次设计出来的，是每天 11 个 cron 跑出来、踩坑修出来的。修问题即加规则——任何不沉淀的修复等于没修。落地 Harness 时按需取用，不必照搬全量。