这是 Oh My KB(无重的私人助理 + 知识库 Agent)运行大半年的设计沉淀。不是理论,是每天 11 个 cron + 21 个 skill + 3 个子 Agent 在跑的实战体系。给团队参考,落地 Harness 时按需取用。
驾驶舱(CLAUDE.md)只放原则 + 路由 + 高频输出规范,约 200 行。所有领域细节放 skill 文件,按需加载。
为什么:驾驶舱每次会话全量进上下文。塞细节 = 每条对话都付 token + 模型注意力被稀释。瘦驾驶舱 = 低固定成本 + 高信号噪声比。
反面:把"飞书 API 字段说明""投资评分公式"写进 CLAUDE.md → 每次会话烧 token,且改一处要动全局。
信息按"需要时才读"分层:metadata → SKILL.md → references/codemap/checklist。
实测数据(SkillJuror 论文):精准按需加载让每次任务触及的引用文件从 1.18 → 3.85(+226%)。
铁律:references 触发条件必须三步式——{什么内容} → {哪个文件} → {什么时候读}。禁止"详情见 references/xxx.md"这种等于没写的指针。
凡是看了不满意会让你重做的东西,用脚本锁死。凡是换一种说法也行的事情,交给模型。
| 模型擅长 | 模型搞不定(→ 脚本锁死) |
|---|---|
| 理解自然语言、归纳总结 | 精确计算(价格、比例、增长率) |
| 写通顺文字、判断异常 | 格式一致性(色号、字体、图表样式) |
| 应对边界情况 | 结构化数据查询(SQL、API 调用) |
| 对照清单逐条检查 | 品牌/公司规范 |
判断标准:这一步产出你看了会不会不满意到要求重做?会 → 脚本。换一种措辞也能接受 → 模型。
新 skill 创建前必填一张表:步骤 → 执行者 → 要求 → Know-how。表有了,写 SKILL.md 和脚本只是执行。
核心原则:Skill 不含流程逻辑——流程属于 Agent。定义交付物而非目标(防范围蔓延)。声明负面空间(每个 Agent 写清"永远不做什么")。Deny-by-default 工具(从全禁起步,只显式开需要的)。
每次踩坑修复后,必须在对应 SKILL.md / CLAUDE.md / rules 加约束。不沉淀的修复等于没修——下次还会犯。
进阶:L4 持续学习闭环——Critic FAIL 逐条记 patterns.md,≥3 次同类 FAIL 升级为永久规则进 optimizations.md;单次严重 FAIL(数据丢失/推送失败/持仓漏查)立即升级不等 ≥3 次。
Hooks(确定性执行,PreToolUse/UserPromptSubmit)
↓
Skills(领域知识 + 执行流程 + 脚本,按需加载)
↓
Agents(工作流编排,路由器启动子 Agent,独立上下文)
| 容器 | 放什么 | 判断标准 | 加载时机 |
|---|---|---|---|
| 根 CLAUDE.md | 原则 + 全局路由 + 输出规范 | "每次会话都需要知道?" | 启动全量 |
{dir}/CLAUDE.md | 该目录操作约定 + 结构规范 | "只在这目录工作时需要?" | 进目录追加 |
.claude/rules/ | 碰特定路径的硬约束 | "操作时必须强制执行?" | paths 匹配时注入 |
skills/ | 领域知识 + 执行流程 + 脚本 | "只在执行特定任务时需要?" | Skill 调用按需 Read |
kb-docs/ | 跨 skill 共享规范 | "多个 skill 都要参考?" | 按需 Read |
铁律:所有 rule 必须带 paths frontmatter——无 paths 的 rule 是分散版 CLAUDE.md,启动即加载全程占 token,违反 Thin Harness。
简单(路由器): SKILL.md
中等(工具类): SKILL.md + codemap.md
复杂(领域子技能): SKILL.md + codemap.md + checklist.md + procedures/ + references/
| 文件 | 内容 | 何时需要 |
|---|---|---|
SKILL.md | 入口、控制流、输出路径 | 必选 |
codemap.md | 目录结构 + 何时读哪个文件 | 目录或 references ≥ 3 个 |
checklist.md | 分阶段执行确认清单 | 多阶段流程、有先后依赖 |
scripts/ | Python/shell,可独立运行 | 有精确计算/格式渲染/数据拉取 |
references/ | 模板/规范/配置 | 有按需加载的细节 |
procedures/ | 分阶段操作指南 | 有多阶段执行流程 |
一条铁律:SKILL.md = 控制流,references = 数据/细节。
| 放 SKILL.md | 放 references/ |
|---|---|
| 路由逻辑(怎么触发、去哪) | 配置参考(cookie 路径、API 格式) |
| 执行步骤(1→2→3) | 模板(带占位符) |
| 关键判断点("≥3 FAIL 则重写") | 详细规范(字数表、自检清单) |
| 指针("Read references/xxx") | 故障排查、长规则集 |
判断标准:需不需要每次执行都读? 每次必走 → SKILL.md。按需或异常才读 → references。
kb-{type}-{domain/action},前缀定角色:
| 前缀 | 角色 | 示例 |
|---|---|---|
kb-core- | 主 Agent 核心能力,直接执行 | kb-core-qa, kb-core-research |
kb-fetch- | 抓取→总结,主 Agent 直接执行 | kb-fetch-compose |
kb-route- | 路由器,匹配触发词→启动子 Agent | kb-route-memory, kb-route-finance |
kb-tools- | 工具调用,主 Agent 直接执行 | kb-tools-futu, kb-tools-github-trending |
kb-{agent}- | 子 Agent 持有技能 | kb-memory-daily, kb-finance-invest |
命名决策:先问"谁执行"→ 再问"什么域"→ 选前缀。
codemap 是渐进式披露的触发机制,解决"Agent 面对 5+ 文件不知道读哪个"。三列表:
| 文件 | 内容 | 读它的条件 |
|---|---|---|
SKILL.md | 入口、流程、输出路径 | 每次触发 |
procedures/preflight.md | 前置检查、拉取命令 | 执行前 |
references/xxx.md | 模板/规则 | 具体阶段触发 |
原则:每个文件一行写清"什么时候才需要读";不列 scripts/(不读,直接执行);按执行顺序排;SKILL.md 必须有指针"首次或不确定时读 codemap.md"。
主 Agent 不直接调用子 Agent 的技能——走路由器:
cron / 用户触发 → 主 Agent 匹配路由 skill(kb-route-*)
→ Agent 工具启动子 Agent
→ 子 Agent 预加载完整 SKILL.md(frontmatter skills 声明)
→ 逐步执行(含存档 + 日志)→ 返回蒸馏结果
逻辑隔离而非物理隔离:子 Agent 持有的技能物理上和主 Agent 技能同目录,靠 agent 定义文件的 skills: frontmatter 声明预加载。
每个 Agent 定义包含:
子 Agent 用 context: default 独立上下文,返回 JSON/蒸馏结果,父 Agent 只收结论不收原始过程。多 Agent 成败在 handoff 时上下文大小的精准控制。
Agent 组织架构模式(Alook 2026-07 新增):把 Agent 编成真正的组织架构图——每个 Agent 分配角色 + 汇报线 + 通信通道。核心规则:
与 Oh My KB 的差异:Oh My KB 当前是单 Agent 多技能,Agent Harness 上线后多 Agent 场景需要协调层。Alook 的"Agent 只走 Manager 不互聊"规则可以直接用于 Melo 多 Agent 团队——蔡武鑫的备货 Co-Pilot 之前"变话痨"就是因为 Agent 之间没有路由规则。
| 层级 | 来源 | 关注点 |
|---|---|---|
| L1 工作流范式 | Andrew Ng | Agent 怎么思考行动(反思/工具/规划/多智能体) |
| L2 编排架构 | Google Cloud 12 种 | 多 Agent 怎么组织协作 |
| L3 Skill 微观 | Google 5 种 + Anthropic | 单个 Skill 文件怎么结构化 |
| L4 系统架构 | Anthropic | Agent→Skill→MCP 三层分离 |
Oh My KB 三层记忆 + Matt Gunnin 四层架构(2026-07 新增,生产验证 6 个月):
| Matt L | 职责 | Oh My KB 实现 | 关键机制 |
|---|---|---|---|
| L1 会话内 | Agent 启动即知自己是谁 | CLAUDE.md + MEMORY.md 索引 | 身份文件 + 记忆索引常驻,一事实一文件按需追读 |
| L2 会话后 | 会话结束自动提取关键事实 | kb-memory-extract(22:00)+ recent.md | 决策/教训/偏好自动推送,人工审核晋升为索引条目 |
| L3 共享状态 | 多 Agent 不互相矛盾 | 待建(Agent Harness 多 Agent 场景需要) | Live-context 日志,纯追加,Agent 签名,每次回复前必读 |
| L4 搜索知识 | 语义搜索已编译知识 | QMD(12 集合 + lex/vec/hyde 三路) | 编译 wiki + 语义搜索 + 来源溯源,按需检索不扫全库 |
核心原则:全部纯 Markdown,可打开可编辑可调试。Agent 记忆是基础设施问题,不是 prompt 问题。
跨 Agent 同步不变式:每条日志 agent_name | channel | kind | summary,纯追加永不编辑他人条目。6 个月仅 1 次冲突。
Oh My KB 三层记忆实现:
| Layer | 内容 | 维护 | TTL |
|---|---|---|---|
| JSONL 原始 | ~/.claude/projects/*.jsonl | 自动只读 | 永久 |
| 飞书/会话 raw | mem-raw/ 下各档 | 每日 cron | 永久 |
| 结构化记忆 | memory/ 下 9 文件 | 每周日蒸馏 | 见 TTL 表 |
启动加载顺序(按优先级,非全量):recent.md → cron 日志近 2 天 → user_profile → mayfair-status(14d) → feedback → stable 按需 → family 按话题触发。
关键原则:Access ≠ Awareness。不在上下文里的东西对模型来说不存在。所以启动加载要按话题路由,不是全塞。
蒸馏四路并行:会话摘要 / 飞书摘要 / 聊天记录 / 财务数据源 → 子 Agent 各自逐篇 Read → 合并 → Critic 审查 → 写入 → stable 主动审计 → 归档。
每个产出的 skill 都内嵌验证:抓取类有四源交叉 + 自检 9 项;蒸馏有 Critic 4 项审查;投资有 Critic 4 维度。
L4 持续学习闭环:
Critic FAIL → 逐条记 patterns.md
→ ≥3 次同类 FAIL 升级 optimizations.md(永久规则)
→ 标 ⏳ 验证中,下次蒸馏检查复发
→ 无复发 ✅ 已验证 / 复发 ❌ 回滚或加强
质量趋势预警:PASS 饱满度连续 2 周下降 ≥0.5 → ⚠️ 恶化;连续 3 周下降 → 🔴 人工介入。
✅ "执行投资早盘分析"
❌ "拉取富途行情+雪球讨论+计算信号+存档到 outputs/投资分析/2026-07-03.md"
全部业务逻辑(执行步骤+存档路径+日志格式)必须在对应 SKILL.md 中自包含。触发路径:cron → 主 Agent 匹配路由 skill → 子 Agent Read 完整 SKILL.md → 逐步执行。
为什么:prompt 嵌步骤 = 改流程要改 cron 配置 = 多一处维护。逻辑在 SKILL.md = 一处真值 + 可被人工触发复用。
核心公式:Agent = 工人(做一次)。Loop = 工人进步机制。Generate → Evaluate → Learn → Improve。所有模式共享一个底层结构:Act → Observe → Evaluate → Adjust。
五大类 20 模式速选:
| 类别 | 最优先落地 | 一句话 |
|---|---|---|
| 质量循环(5) | Pattern 1 Generate→Critique→Rewrite | 生成和审查必须角色分离,不能自己审自己 |
| 质量循环 | Pattern 3 Multi-Critic | 正确性/风格/安全/领域四维度独立审 |
| 记忆循环(5) | Pattern 6 Reflexion | 失败→分析根因→存教训→带教训重试("只失败一次") |
| 记忆循环 | Pattern 8 Error Library | 失败库,新任务前先查——Oh My KB 刚落地 |
| 规划循环(5) | Pattern 11 Plan→Execute→Replan | 非瀑布,螺旋上升,每步后修正计划 |
| 规划循环 | Pattern 14 Progress Evaluation | 长任务每 N 步自查"离目标是否更近" |
| 系统优化(2) | Pattern 20 Workflow Optimization | 系统自测 latency/cost/quality → 自调结构——最大未开发领域 |
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 — 定时重跑关键:停止条件必须可程序化测量。模糊目标("改善体验")→ 不如定("time-to-interactive < 1s")。
| 层 | 机制 | 现状 |
|---|---|---|
| Sandbox | ubuntu-cc 容器隔离不挂载 | ✅ |
| Permissions | allowed-tools + 路径权限 + auto 模式 | ✅ |
| Hooks | PreToolUse(raw 只读/隐私数据)+ UserPromptSubmit(关键词路由) | ✅ |
| Injection Defense | 抓取内容不信任 + 审查层 | ❌ P0 待补 |
硬约束靠 hook,解释靠 path-scoped rule。raw 只读、wiki 由编译维护、隐私数据禁部署——这三条有 PreToolUse hook 拦截 + rules/ 文件解释。
按 Addy Osmani 双轴六层(agency × orchestration,L0–L5):
| 系统 | 层级 | 依据 |
|---|---|---|
| Oh My KB | L4 + L5 萌芽 | 3 路由器+子 Agent、11 cron 触发、Critic 独立审查(=Auto-review)、NO_REPLY 异常管理、PreToolUse gate、沙箱;缺连续工厂和规模 |
| 备货 Co-Pilot | L1–L2 | 监督执行+受限委派,验证靠人;读侧 monitor 到 L4 雏形 |
| 小思平台 | L1–L2 基线,L4–L5 图纸 | 基础设施在建,Harness 是目标态 |
整体卡在 L2→L4 爬升段,6/26 Harness 是奔 L5 的路线图。
核心论点(Addy):自治天花板不是任务名,是风险+可逆性+验证。每次跑 agent 前签 contract:目标/范围/非目标/工具权限/停止条件/证据/升级/预算。验证永远是瓶颈。
核心数据(Anthropic 实测):同一个 Claude 模型,Claude Code 里跑 78%,换成另一个 Agent 框架只剩 42%。36 个百分点的差距全由 Harness(基础设施)产生,模型没变。
这就是为什么要投资 Harness Engineering(NeilXbt 2026-07,六份免费资源路线图):
Context Engineering 四原语(Anthropic,Harness 的核心操作):
Fable 5 指挥官模式(老白 2026-07):Fable 只负责拿主意(拆子任务/定顺序/验收),Composer/便宜模型干执行(读文件/改补丁/跑检查)。拆不清就别拆——设计决策、刁钻 bug、紧密耦合方案让一个 Agent 干到底。
10-80-10 模型路由:Fable 5 是 Opus 4.8 的 2 倍价且过度思考。用 Anthropic 工程师自用的:
Oh My KB 已在用模型路由(主 Agent / 子 Agent / Critic)+ DeepSeek 缓存(命中率 98%+)做这件事。7/7 Fable 转按量后,cron 执行层必须显式切便宜模型,Fable 只留规划 + Critic 两段。
| 反模式 | 表现 | 修复 |
|---|---|---|
| 自治当身份徽章 | 高自治=能力证明而非安全证明,agent 跑得比验证支持还热 | 表扬选对层级的人,严控越级 |
| 许可洗钱 | 审批疲劳导致给 AI 远超必要的权限 | 沙箱 profile + scoped writable roots + allowlist + hooks + Auto-review |
| 摘要替代审查 | agent 的工作摘要当作审查 | bundle 同手动审查的证据包(diff/tests/logs/screenshots/reviewer findings) |
| Fleet cosplay | 几十 agent 并行但人还在手编排每个依赖 | 共享状态+所有权规则+依赖追踪;WIP 限制强制把协调步骤编码 |
让 AI Agent 写好代码的秘诀全在 1990 年代教材里:
外部化约束是 Agent 可靠运行的必要条件(Code Review/Unit Testing/CI/CD/灰度拦截 AI Agent)。agent 越强,越要把这套基本功捡回来——不是新魔法。
1. 拆步骤:从触发到输出分几步?
2. 标执行者:每步过"模型还是脚本"铁律
3. 填表:步骤 → 执行者 → 要求 → Know-how
4. 搭三层:需要 scripts/ 吗?references/ 吗?
5. 写 SKILL.md:只放路由+步骤+触发条件,代码进 scripts/
6. 验证:最可能幻觉的那步——脚本锁死了吗?
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
内部规范(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/,按时间倒序)
这套体系不是一次设计出来的,是每天 11 个 cron 跑出来、踩坑修出来的。修问题即加规则——任何不沉淀的修复等于没修。落地 Harness 时按需取用,不必照搬全量。