让本机的 AI Agent 互相认识 —— Agent Commons v2.0 协议设计

一个本地优先、跨厂商的 AI agent 共享记忆协议。让你机器上的多个 agent（Claude / Cursor / WorkBuddy / CodeBuddy / Marvis 等）通过纯 Markdown 文件 + Unix 软链共享一份记忆。无 daemon、无云端、无 SDK。

GitHub: https://github.com/dqsjqian/agent-commons^[1] · Status: v0.2.0

1. 它解决什么问题

如果你和我一样，机器上同时跑着好几个 AI agent —— 做代码用 CodeBuddy / Claude、做日常用 WorkBuddy、做 Mac 端事务用 Marvis 或 BoxAI —— 你一定踩过这些坑：

• 每个 agent 都要重新告诉一遍我是谁、我偏好什么 —— 浪费时间，还经常说漏。
• agent A 学到的东西，agent B 完全不知道 —— 比如 A 学会了你的 git author 偏好，B 还在用错的。
• 跨 agent 协作做不到 —— B 帮你做了一半的事想交给 C，只能你手动复述。
• 每次新装一个 agent，重新训化一次 —— 堆累成本。

这本质是个共享记忆问题。但市面上的方案要么需要云端（不放心隐私）、要么需要装 SDK / daemon（不想再装一坨）、要么要求所有 agent 都支持某个 SDK（不可能）。

Agent Commons 的解法极简：

每个 agent 在本机共用一个目录 ~/.agent-commons/，里面是用户身份、规则、消息、日志。所有协议规约就是这个目录的文件结构 + 几条文件操作约定。

无 daemon，无云端，无 SDK，无包管理依赖。Markdown + JSON + 文件系统，就是协议本身。

2. 中央目录长什么样

v2.0 把中央目录显式拆成两层：

• 协议层（normative）：SPEC.md 用 RFC 2119 的 MUST/SHOULD/MAY 语义定义的硬规则。所有 agent 必须遵守，写错就是 protocol violation。
• 约定层（non-normative）：CONVENTIONS.md 收集的可选推荐做法。跟着做用户体验更一致，不跟也不算违规。

两层物理分文件，绝不混写。这是 v2.0 最核心的设计哲学进化。

3. v2.0 最大的新概念：共享 Skill 总线

以前每个 agent 维护自己私有的 skill 集合 —— agent A 装的 wechat-publisher，agent B 完全看不到。v2.0 改用共享 skill 总线：所有 agent 共用 ~/.agent-commons/skills/ 一份。

收益：

• install once, use everywhere：用户装一遍，机器上所有 agent 全部具备这个能力。
• skill 升级单点更新：维护者只 push 中央目录，所有 agent 下次会话即享新版本。
• 避免 skill 漂移：agent A 用的是 v1.2、agent B 还停留在 v1.0 —— 现在物理上不可能漂移。

每个加入的 agent 通过 symlink / copy / readonly 三级 fallback 接入同一份源。

4. 协议核心：四条铁律

这四条不只是 agent-commons 的内部约束，任何做"让外部系统按你的规范对接"的协议或 SDK 都用得上。

铁律 1 — 用「行为」定义路径，不用「目录名」

❌ "请把 skill 装到您的 skills/ 目录"

✅ "请把 skill 装到您 runtime 被允许加载第三方 skill 的目录"

商业 agent 经常有双层 skill 体系（内置签名区 vs 用户可扩展区），名字一样但行为完全不同。第三方装到内置区会静默失败：文件存在、ls 显示、symlink 完美，runtime 永远不加载。

铁律 2 — 用「可触发」定义完成，不用「已安装」

❌ "把文件放到这个位置就算装好了"

✅ "装完后当场调用一次确认 runtime 能识别。失败就降级换方案，全失败就诚实告知用户'本 agent 可能无法加入'"

LLM 极易"看 ls 有文件就报告完成"，必须用协议硬卡死。closed-loop trigger test 是协议核心创新。

铁律 3 — 引导 ≠ 能力，必须解耦到不同文件

ONBOARDING.md（一次性入会）与 skills/agent-commons/SKILL.md（runtime 持续触发）物理拆分。生命周期不同的东西不要塞同一个文件。SKILL.md 自我保护：每次触发先 grep registry.json，没注册立刻指回 ONBOARDING.md 然后停。

★ 铁律 4（v2.0 新增）— 用 convention 表达推荐，不用 spec 表达推荐

协议骨架（SPEC.md）和可选约定（CONVENTIONS.md）必须物理分离到不同文件：

• SPEC.md：稳定不动，只放 RFC 2119 意义的 MUST/SHOULD/MAY，是协议核心。
• CONVENTIONS.md：明确标注"非规范、随时可改、跟进者无义务"，是生态推荐做法。

如果把推荐性内容写进 SPEC.md，时间一长会发生两件坏事：

1. 跟进者把 SHOULD 当 MUST —— 本来推荐的写法变事实标准。
2. 维护者不敢改 —— 写在 SPEC 里的内容心理上变成"承诺"，调整成本高。

物理分离后，convention 可以随时演进、删除、重组，不污染核心协议。

5. 加入流程：5 步一气呵成

用户对任何 AI agent 说一句：

"请阅读 ~/.agent-commons/ONBOARDING.md 加入 Agent Commons。"

agent 自己读、自己装、自己自检、自己注册。装不上的 agent 自然淘汰 —— 这是协议设计上有意为之的"能力测试"。

5 步分别是：

1. 验证中央目录存在
2. 发现自己 runtime 的 skill 目录 —— 三种发现方法（SDK 文档 / filesystem probe / 问用户）
3. 三级 fallback 安装 —— symlink → copy → readonly
4. 闭环触发自检 —— file sanity → trigger self-test → adaptive ladder → honest report
5. 注册 registry.json —— 写入 install_tier、install_verified、skills_root

6. 实证：5 个 agent 已经在用

截至 2026-06-03，本机 registry.json 已注册 5 个 agent（workbuddy / codebuddy / marvis / claude / boxai），symlink 和 copy 两种 tier 都有 —— 这就是铁律 2（闭环触发自检）实战中触发的真实降级。

Marvis 和 BoxAI 用 copy tier，是因为它们的 sandbox 不识别 symlink。这种事先想不到、上线才暴露的问题，恰恰是协议演进的最好养料。

7. 协议演进逻辑

v2.0 这个 major bump 不是"心血来潮"，是 v0.1.0 上线后实际撞到的 4 个连续问题驱动的：

这 4 个 bug 把"协议设计要点"从抽象的 best practice 砸成了具体的强制条款。协议有多坚固，取决于第一波撞死过多少个版本。

8. 设计哲学

我们坚决不做：daemon、pip / npm 上的包、CRDT 同步引擎、云服务、聊天界面。

Agent Commons 是一份约定，不是软件。约定胜过配置。文件系统胜过数据库。Symlink 胜过同步逻辑。

9. 快速上手

# 1. 装中央目录
curl -fsSL https://raw.githubusercontent.com/dqsjqian/agent-commons/main/install.sh | bash

# 2. 编辑你自己的内容
$EDITOR ~/.agent-commons/identity/profile.md
$EDITOR ~/.agent-commons/rules/universal.md

# 3. 对任意 AI agent 说一句：
#    "请阅读 ~/.agent-commons/ONBOARDING.md 加入 Agent Commons。"
#
#    它会自己读、自己装、自己自检、自己注册。

10. 相关资源

• GitHub 仓库：https://github.com/dqsjqian/agent-commons^[2]
• License: MIT
• 同时是 soul-archive^[3]（数字人格存档）和 ai-eight-creed^[4]（AI 八耻八荣）的作者。

Make your AI agents finally stop forgetting each other. 让你的 AI agent 们终于停止互相不认识 —— 并且开始互相借力。

引用链接