← 返回 AI Native 能力指南

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 时上下文大小的精准控制。

Agent 组织架构模式（Alook 2026-07 新增）：把 Agent 编成真正的组织架构图——每个 Agent 分配角色 + 汇报线 + 通信通道。核心规则：

• 单点接触人：CEO Agent 是人唯一的接触点，人不直接指挥工程师 Agent
• 层级路由：Agent 只走 Manager 不互聊——避免"所有 Agent 在群里喊话，上下文互相污染"
• 邮件/消息协调：Agent 之间通过消息通信，全部留痕可回溯
• 真实运行时：每个 Agent 是真实 Claude Code/OpenCode session，不是模拟

与 Oh My KB 的差异：Oh My KB 当前是单 Agent 多技能，Agent Harness 上线后多 Agent 场景需要协调层。Alook 的"Agent 只走 Manager 不互聊"规则可以直接用于 Melo 多 Agent 团队——蔡武鑫的备货 Co-Pilot 之前"变话痨"就是因为 Agent 之间没有路由规则。

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

速选指南

• 新建 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 或工具）

Oh My KB 三层记忆 + Matt Gunnin 四层架构（2026-07 新增，生产验证 6 个月）：

核心原则：全部纯 Markdown，可打开可编辑可调试。Agent 记忆是基础设施问题，不是 prompt 问题。

跨 Agent 同步不变式：每条日志 agent_name | channel | kind | summary，纯追加永不编辑他人条目。6 个月仅 1 次冲突。

Oh My KB 三层记忆实现：

启动加载顺序（按优先级，非全量）：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 + 20 模式（Rahul 2026-07，334K 浏览）

核心公式：Agent = 工人（做一次）。Loop = 工人进步机制。Generate → Evaluate → Learn → Improve。所有模式共享一个底层结构：Act → Observe → Evaluate → Adjust。

五大类 20 模式速选：

Oh My KB 已落地：Pattern 6（L4 FAIL→patterns.md）+ Pattern 7（22:00 extract）+ Pattern 8（ERROR Library 事前查询，7/4 新加）+ Pattern 9（PASS 每周聚合）+ Pattern 10（≥3 次升级永久规则）+ Pattern 1（Critic 体系）+ Pattern 15（Critic 全 PASS 才输出）。

实操工具： - /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：目标/范围/非目标/工具权限/停止条件/证据/升级/预算。验证永远是瓶颈。

十、成本控制：Harness 比模型更决定性能

核心数据（Anthropic 实测）：同一个 Claude 模型，Claude Code 里跑 78%，换成另一个 Agent 框架只剩 42%。36 个百分点的差距全由 Harness（基础设施）产生，模型没变。

这就是为什么要投资 Harness Engineering（NeilXbt 2026-07，六份免费资源路线图）：

Context Engineering 四原语（Anthropic，Harness 的核心操作）： - Write：Agent 为自己创建持久化产物（memory 文件/scratchpad/进度日志），不依赖单窗口 - Select：按需检索特定信息，不全量 dump 进上下文 - Compress：上下文窗口接近 85-95% 时压缩总结 - Isolate：子 Agent = 上下文隔离原语，非并行原语——派子 Agent 的本质是把昂贵上下文窗口留给决策而非资料检索

Fable 5 指挥官模式（老白 2026-07）：Fable 只负责拿主意（拆子任务/定顺序/验收），Composer/便宜模型干执行（读文件/改补丁/跑检查）。拆不清就别拆——设计决策、刁钻 bug、紧密耦合方案让一个 Agent 干到底。

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

• 前 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 — 三层记忆 + 蒸馏四路并行 - memory-four-layer-reference.md — 新增：Matt Gunnin 四层记忆架构对照 + Oh My KB 改进方向 - loop-engineering-20-patterns.md — 新增：Rahul 20 Loop 模式速查 + Oh My KB 落地对照 + 优先级排序

外部文章（raw/，按时间倒序） - Rahul《20 Loop Design Patterns Every AI Engineer Should Know》(2026-07-01) — 五大类 20 模式 + Act→Observe→Evaluate→Adjust - Matt Gunnin《The 4-layer memory architecture》(2026-07-02) — L1-L4 + live-context + 全部纯 Markdown - Machina《How to build a second brain with Fable 5》(2026-07-03) — raw→entities→concepts→INDEX 四件套 + 省钱核心 - Akshay《How to Build Your Own AI Company》(2026-07-03) — Agent 组织架构 + 层级路由 + 0 员工公司 - NeilXbt《The $0 Harness Engineering Course》(2026-07-03) — 六份免费资源 + 78% vs 42% Harness 差距 + Context Engineering 四原语 - 老白《Fable 5 回归 Cursor》(2026-07-03) — 指挥官模式 + 拆不清就别拆 - Addy Osmani《Agentic Autonomy Levels》— 双轴六层 + 验证瓶颈 + 四反模式 - 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 时按需取用，不必照搬全量。