Agent Guild

让多个本地 AI 助手复用同一份偏好、项目约定和工作交接。

English | 中文

Agent Guild 面向同一用户使用的多个、受信任且能够读写本地文件的 AI 助手。 它把共享上下文放进 ~/.agent-guild/ 的 Markdown / JSON 文件：你能查看、修改、备份， 切换助手时也能继续使用。运行时 skill 提供读写约定，Python CLI 处理并发写入、检索和归档。

先验证一次：A 记住，B 找到

安装并让两个助手接入后，用一条没有敏感内容的演示约定测试：

1. 对助手 A 说：

   请记住这条长期演示约定：演示项目的交付说明必须包含验证结果。 保存到协会的 memory/shared/demo.md，登记到 memory/shared/INDEX.md，并告诉我保存路径。

2. 切换到助手 B，说：

   在协会里查找“演示项目”的交付约定，复述内容并引用来源文件。

3. 确认 B 找到同一条内容和文件。测试结束后，可以删除这条演示约定及其索引项。

这才是共享记忆的验收结果；磁盘上出现 skill 文件只是接入的第一步。 长期偏好和项目约定放在身份、规则或共享记忆中；log/daily/ 记录会话经过，不代替长期记忆。 助手仍需按协议读取相关上下文，Agent Guild 不会自动把所有历史塞进每一次回答。

适合谁，有哪些边界

它不提供多人权限隔离、自动跨设备同步或后台任务执行。没有本地文件访问能力的助手， 不能直接使用这个目录；有文件访问能力但不能加载自定义 skill 的助手，可以手动读取协议， 不过需要在会话中提醒它使用，不等同于自动触发。

核心取舍是：少量基础设施、可检查的文件，换取助手遵守读写约定和用户管理文件访问范围。 CLI 需要 Python 3.9+，只使用标准库；没有服务端或常驻进程。

安装与接入

1. 建立中央目录

macOS / Linux / WSL / Git Bash（需要 Bash 和 curl）：

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

Windows（PowerShell 5.1+）：

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

安装器下载协议和 CLI、初始化模板，并打印接入口令。它不修改助手自己的目录。 要先检查源码，也可以下载并阅读安装脚本后再运行。

2. 让每个助手接入

初次试用建议只接入共享记忆，对助手说：

请读 ~/.agent-guild/ONBOARDING.md，仅接入共享记忆，保留现有 skills 和工具目录。

需要统一管理更多资产时，可以明确选择完整共享中心：

请读 ~/.agent-guild/ONBOARDING.md，按完整共享中心模式接入，报告迁移的目录和使用的安装方式。

完整模式会把可迁移资产放进协会，并尝试用目录链接连接助手的 skills 目录；不兼容时使用 逐 skill 链接、拷贝或手动读取。详情见 接入流程。 接入后运行上面的两助手验证，确认记忆能被实际找到。

从源码安装

将项目源码与私人协会数据分开放置。在你选择的源码工作目录运行：

git clone https://github.com/dqsjqian/agent-guild agent-guild-source
python3 agent-guild-source/scripts/ag.py init demo-agent

demo-agent 可换成你的助手名称；Windows 若使用 python 命令，相应替换 python3。 init 会在 ~/.agent-guild/ 创建运行目录并安装 skill，然后按上面的口令让助手接入。 不要把源码仓库直接克隆到私人数据目录。

你能控制什么

• 记忆内容：身份、规则和项目文件由用户控制。助手只记录任务所需的摘要；不要把密码、token 等凭据写进共享记忆。
• 网络与更新：安装需要下载文件。运行时默认在 bootstrap 后按设备最多每 24 小时检查一次三个公开版本源，不上传记忆内容。UPGRADE.md 中 mode = check 只提示，mode = apply 会下载并安装新版本，mode = off 关闭自动检查；手动 upgrade 仍可使用。
• 只查看上下文：bootstrap <agent> --no-maintenance 跳过本次自动整理和升级检查，不改变已有策略。
• 自动归档：bootstrap 默认按设备每 24 小时尝试一次 groom，将过期日志、焦点及已解决台账搬到归档，轮转审计；未读消息只报告。先用 groom --dry-run 看计划，保留期限在 RETENTION.md 调整。归档不等于删除，也不会缩小整个目录的历史总量。
• 共享范围：memory/<agent>/ 和 private/ 是组织约定，不是权限或加密边界。能访问这些文件的程序仍可能读取它们；加入的助手应当是你信任的。
• 模型与备份：数据文件由 Agent Guild 保存在本机。助手读取后是否发送给模型服务，取决于该助手的运行方式；你选择的同步、备份工具也有自己的数据处理行为。

这些边界适用于 Agent Guild 本身；共享目录中的其他 skills / 工具有各自的权限和行为。 详见 安全与能力说明。

日常维护与升级

可以直接对已接入的助手说：“记住这个项目约定”“查一下上次的决定”“更新当前焦点”或“整理协会”。 完整命令见 能力参考。CLI 的写入和检查都发生在调用时，不在后台运行。

检查、应用本项目的版本更新：

python3 "$HOME/.agent-guild/skills/agent-guild/scripts/ag.py" upgrade
python3 "$HOME/.agent-guild/skills/agent-guild/scripts/ag.py" upgrade --apply

Windows 使用 python 和 $env:USERPROFILE 对应路径。也可以重跑安装器。 更新作用于 Agent Guild 自身的协议文件，不覆盖身份、规则和项目内容；链接安装随中央版本更新， 拷贝安装还需同步助手内的副本，见 更新流程。

文件结构与多设备

~/.agent-guild/
├── identity/ rules/ projects/     用户身份、约定、项目状态
├── memory/shared/                跨助手的长期事实及 INDEX.md
├── memory/<agent>/               按助手组织的记忆
├── handoff/                      当前焦点、收件箱、归档
├── log/ learnings/               会话日志、纠正与经验台账
├── hosts/<host-id>/              本机路径、平台和安装状态
├── skills/agent-guild/           Agent Guild 运行时 skill
├── RETENTION.md UPGRADE.md       保留与自动检查策略
└── registry.json                接入记录

完整共享中心还使用 skills/、skills_data/、mcp/、plugins/、tools/。 共享事实留在常规目录；只对一个 OS / 架构成立的工具用平台声明；只对本机成立的路径放在 hosts/<host-id>/。本机文件锁不能替代多设备文件同步的冲突处理。

搬迁时，用你选择的方式复制所需目录，在新设备执行 init 和 port 体检，再处理缺失的平台工具。 备份前检查包含的个人资料和凭据，不要把私人协会数据提交到公开仓库。 详见 跨设备与备份。

项目与文档

Agent Guild 是本地文件协议及其参考实现。它支持跨平台检测和多种链接降级方式； 实际能否加载 skill，取决于助手运行时的文件权限和扩展能力，接入时需要验证。

• 运行时 skill · 完整规范 · 约定
• 接入流程 · 能力参考 · 机器可读 manifest
• 贡献接入指南

许可证：MIT。作者：@dqsjqian。