agent-guild v3.4.1 — 清理 AC_AGENT 残留

chore：删除 agent-commons 时代的 AC_AGENT 环境变量兼容（default_agent + cmd_send 只读 AG_AGENT），同步 manifest 过时的 doctor 描述。功能无变化。

agent-guild v3.4.0 — 版本自检 + 三平台自动更新

版本自检 + 自动更新

两个能力一起落地：

1. 运行时版本锚点（~/.agent-guild/VERSION）

ag init 现在版本感知：对比「运行中 ag 的版本」vs「已装版本锚点」，发现升级就刷新 skill 包 + 根文档，用户数据（identity/rules/log/handoff/skills_data/connectors/memory）一律不动。根文档随版本走（协议所有，用户编辑应放 identity/rules）。

2. ag upgrade [--apply] — 自检 + 自动更新

无认证查询三个平台（任何普通用户都能跑），报告各源版本，取最新：

• skillhub: api.skillhub.cn/api/v1/search?q=agent-guild
• github: releases/latest 302 重定向拿 tag（无 API rate limit）
• clawhub: clawhub.ai/api/v1/skills/agent-guild/versions

默认 dry-run（只报告）；--apply 下载 GitHub release zip 并安装，保留用户数据。

skill_version 3.3.1 → 3.4.0（协议保持 3.0）。

agent-guild v3.3.1 — 自然语言触发词重写

触发词从「协议术语」改成「用户自然语言」

问题：旧 description 全是协议术语（"read shared identity"、"adopt my skills"），正常人对话根本不会这么说，弱模型永远匹配不上、skill 不被触发。

修复：按用户真实说话方式重写，六大意图分组——身份/习惯、回忆/历史、写记忆、跨 agent 交接、当前状态、加入。description 1012 → 546 字符，给触发词留足空间。

skill_version 3.3.0 → 3.3.1。

agent-guild v3.3.0 — 约定层补全：connectors 目录 + 命名规范 + 缓存排除

目录设计审视后的约定层补全

完整审视运行时目录后，落地 6 项改进：

1. 新增 connectors/ 目录（凭据归置）

连接器凭据（登录 cookie、API key、OAuth token、lock 文件）此前被塞进 skills_data/，现在归入 connectors/<name>/。手动归置、永不被 adopt 自动搬动、默认 gitignore。

2. 命名规范

skills/ skills_data/ connectors/ 子目录一律小写连字符 slug [a-z0-9-]——禁中文、禁空格、禁 -skill 后缀。（运行时 QQ邮箱 已改 connectors/qq-mail/）

3. adopt 缓存排除扩展

browsers/（Playwright/Puppeteer 浏览器二进制）、*.app/*.pid/*.log/*.pyc 全部排除——备份根不再拖 300M 可重建的 Chrome。清理后协会从 348M 降到 2.7M。

4. .gitignore 模板补全

排除 browsers/node_modules/.venv/.app/.pid + 整个 connectors/ 树。

5. CONVENTIONS.md 新增 Convention 6（连接器凭据）

明确「凭据 ≠ skill 数据」，隐私分层落地说明。

skill_version 3.2.2 → 3.3.0（约定层新增，协议保持 3.0）。

agent-guild v3.2.2 — fix: SPEC.md 协议号 2.0 → 3.0

Bugfix

问题：\（协议核心规范）一直写着 \——历次版本升级只改了 manifest.json / SKILL.md / registry.json / ag.py，\ 是唯一没跟上协议升级的文件。

修复：

• 协议号 2.0 → 3.0
• 补充 2.0 → 3.0 破坏性变更说明（自举系统、memory/ 目录、约定层 default-on、需重新接入）
• registry 字段契约：\
• 大版本漂移示例更新为 3.0/3.2（原为 1.0/2.0）

agent-guild v3.2.1 — fix: init 补齐 SPEC.md

Bugfix

问题：~/.agent-guild/ 根目录缺 SPEC.md（协议核心规范文档，CONVENTIONS.md 和 manifest.json 都引用它）。与 v3.1.1 的 ONBOARDING/CONVENTIONS 缺口同源：ag init 只 seed 了两个文档，install 脚本也只下载两个。

修复：三个根文档（ONBOARDING.md / CONVENTIONS.md / SPEC.md）现在由 ag init 统一 seed、由 install.sh / install.ps1 双写（central 根 + skill 包 docs/）。

验证：全新空目录 init → 生成全部三个文档；已有安装重跑 init → 只补 SPEC.md（files created: 1）；doctor 全绿。

agent-guild v3.2.0 — 无感知加入：ag find-root，不再问用户

加入流程优化：全程无感知、秒级完成

问题：接入流程的 Step 2 让 agent 用 find ~ -maxdepth 7 全盘搜索自己的 skill 目录——真实 home 下要 30 秒以上（本机实测 33s），很多 agent 卡在这一步或去问用户，看起来"加入老半天"。

修复：

• 新增 ag find-root <agent> 命令：≈0.05 秒定位 skill 目录。顺序：registry → 常见路径（~/.<name>/skills、~/.config/<name>、macOS ~/Library/Application Support/<name>、Windows %APPDATA%/<name>）。绝不全盘 find
• 找不到 → 自动降级 readonly（exit 0，不是失败）：跳过安装，直接读 central 文件继续加入，协议能力全保留
• 彻底删除"问用户"步骤（Method C）：加入必须静默自主完成，禁止为找自己的目录而打扰用户
• FAST PATH（POSIX + PowerShell）同步更新，含 readonly 降级分支

设计原则：一个连自己 skill 目录都找不到的 agent，直接 readonly 加入——不卡住、不追问、不装到别人家目录。

验证：registry 命中 0.046s；找不到的 agent 秒回 readonly 判定。

agent-guild v3.1.1 — fix: init 生成 ONBOARDING.md + CONVENTIONS.md

Bugfix

问题：新用户首次 ag init 后，~/.agent-guild/ 根目录没有 ONBOARDING.md 和 CONVENTIONS.md——而 ONBOARDING.md 是全新 agent 被引导去读的接入入口，没有它整个接入流程就断了。

根因（两层）：

1. ag init 的文档 seed 逻辑从 <skill-pkg>/docs/ 读，但运行时 skill 包缺 docs/ 目录（手动同步和安装器都只把文档放 central 根，没放进 skill 包内）
2. 现在 ag init 会从 skill 包复制 ONBOARDING.md / CONVENTIONS.md 到 central 根（缺才建、用户编辑永不覆盖、完全幂等），install.sh / install.ps1 也同时下载到 central 根和 skill 包内，两条路径对齐

验证：全新空目录模拟 init → 现在产出两个文档；重跑零副作用、不动用户编辑。

智能体协会 agent-guild v3.1.0 — Protocol 3.0

从「文档协议」变成「自举系统」

3.0 之前，协议能描述 agent 该做什么，但没有任何机制让它真的发生。这一版把它变成了会自己长起来的系统。

新增 CLI 能力（scripts/ag.py，纯 stdlib，Windows / macOS / Linux 通用）

命令	作用
ag init	首次使用时自举 ~/.agent-guild/。完全幂等，只补缺失项，绝不覆盖已有数据
ag adopt	自检本机 agent home，把散落的 skill / skills_data / mcp / tools / memory 收进协会并软链回去。默认 dry-run；--apply 会逐项验证链接，失败自动回滚，删除进系统废纸篓
ag bootstrap	一条命令读全共享上下文（身份、戒律、项目、焦点、收件箱），不用手工开五个文件
ag doctor	悬空链接、核心文件缺失、JSON 损坏、registry 漂移、协议大版本漂移

约束力：强制会话契约

SKILL.md 新增 Mandatory Session Contract（M0–M4）：自举协会 → 干活前读共享上下文 → 实质工作后沉淀记忆 → 新 skill/数据归置进协会 → 定期自检收编。

触发词按会话阶段拆分（session start / session end / maintenance），让 agent 在对的时机触发，而不是等用户点名。

约定层从「非规范、可随意忽略」升级为 default-on，只留一个明确豁免口：runtime 强制私有路径，在 registry 里记录原因即可。

跨平台与包容性

• Windows PowerShell 快速接入通道；链接策略 symlink → junction → hardlink 逐级降级
• 废纸篓支持 trash / trash-put / gio trash / 回收站，全都不可用时落到内部 .trash/——任何删除都可恢复
• Python 3.8+（from __future__ import annotations）
• host-wired skill 改为按内容检测，不再硬编码厂商名单；另加用户可编辑的 .adoptignore
• 文档去厂商化：示例覆盖 CLI agent、IDE 分支、桌面助手、沙箱/移动端；补全「无 shell / 无 Python」的纯文件路径

⚠️ 破坏性变更

• protocol_version 2.0 → 3.0，已注册的 agent 需要重跑 ONBOARDING.md（ag doctor 会明确报出来）
• CLI 更名 ac → ag，ac.py 直接删除，安装器会在升级时清理旧文件
• 中心目录新增 memory/（memory/<agent>/ + memory/shared/）

安装

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/dqsjqian/agent-guild/main/scripts/install.sh | bash

# Windows PowerShell
iwr -useb https://raw.githubusercontent.com/dqsjqian/agent-guild/main/scripts/install.ps1 | iex

装完把这句发给你的 AI：Read ~/.agent-guild/ONBOARDING.md

智能体协会 agent-guild v3.0.0

🎉 v3.0.0 — 智能体协会（agent-guild）正式版

产品从 agent-commons 正式更名 agent-guild（智能体协会），并完成 skill 化改造。

Breaking changes

• 更名：agent-commons → agent-guild（GitHub 仓库自动重定向旧链接）
• central 目录：~/.agent-commons/ → ~/.agent-guild/
• 环境变量：AGENT_COMMONS_* → AGENT_GUILD_*

New

• 仓库根 = skill 包：SKILL.md + manifest.json + scripts/ + docs/（市场上架即指仓库根）
• ac CLI（scripts/ac.py，零依赖 Python）：写操作原子化 + 审计（log/audit.jsonl）——status / register / last-seen / send / log / focus / audit / prune
• scripts/package.sh：一键打包市场上架 zip（默认输出 ~/Downloads/）
• 中文名：智能体协会；触发词：读共享身份 / 读共享规则 / 当前焦点 / 检查收件箱 / 加入智能体协会

Fixed

• SKILL.md frontmatter 恢复 protocol_version（协议版本一致性）
• install.sh / install.ps1 全部资源 URL 修正（docs/ 前缀）

Docs

• docs/ONBOARDING.md（一次性入会）/ docs/SPEC.md（协议规范）/ docs/CONVENTIONS.md（约定层）/ 中英 README