Guild
让多个 AI 编码代理共享持久记忆、项目原则与任务看板，跨会话、跨编辑器延续同一份状态。
- Star 数
- ★ 302
- 最近更新
- 3 天前
- License
- Apache-2.0
- 主语言
- Go
- FA 评分
- 50/100 · 缺口较多
30 秒速览
- 运行形态
- 可在哪里用
- 通用 · 跨平台Codex · Claude Code
- 费用
- 免费，无需付费服务
- 上手难度
- 低 · 几分钟可跑通
- 开始前需要
- 典型场景
- 在同一仓库上用 Claude Code 与 Codex 交替工作的开发者，希望第二个会话直接读到上一个会话留下的 brief 与任务状态。
- 不适合
- 需要 Windows 上语义检索的团队（仅 BM25 关键词搜索）
- 要求数据绝不发送到任何外部端点、且启用 Ollama 嵌入的用户
- 不使用 MCP 客户端的纯手工工作流
- 源码审查
- 50/100 · 缺口较多
这个 Agent 能做什么，适合哪些场景？
Guild 是一个用 Go 编写的单二进制工具，内置一等公民的 MCP 服务器和嵌入式 SQLite，为 AI 编码代理提供跨会话的共享上下文。它把状态抽象为四个原语：带优先级、依赖和原子认领的 Quest（任务）、带 kind 分类的 Lore（知识条目）、由 kind=principle 组成的 Oath（原则）以及 Brief（交接便条）。检索在 BM25 关键词与向量余弦之间做排序融合，本地默认嵌入后端在机器上运行，可选 Ollama 后端会把嵌入文本发往配置的端点。任何 MCP 客户端（Claude Code、Codex、Cursor）都可以作为入口接入同一份状态，代理通过原子认领避免并行冲突，完成任务时自动解阻塞依赖它的任务。状态默认存放在 ~/.guild/ 下，切换客户端无需导出或迁移；命令行还提供 quest、lore 等动词，并支持 --agent 输出稳定 JSON 信封。
会话开始时代理调用 guild_session_start 一次性取回 oath、最近一份 brief 和优先级最高的 quest 及可并行候选；随后用 guild quest accept QUEST-42 --owner agent-a 以原子锁认领任务。行动前用 guild lore appraise "token refresh" --all-projects 做混合检索（BM25 加可用向量），再用 guild lore inscribe 写入带 kind（observation、decision、research、principle、idea）与 topic 的条目，用 guild quest journal 记录本任务内的过程。结束时用 guild quest brief 写给下一次会话的交接，用 guild quest fulfill QUEST-42 --report 清空任务，清空会级联解锁被它阻塞的任务。除 MCP 工具外，同一批动词可在 CLI 上以 --agent、GUILD_AGENT=1 或检测 CLAUDECODE/CODEX_SANDBOX/CURSOR_AGENT 环境变量启用，每次调用在 stdout 输出一个 JSON 信封（ok、command、output/error、可选 hint），退出码保持成功为零。guild hooks install 可把简报、压缩前捕获和按提示注入写入 Claude Code 的 .claude/settings.json 或 Codex 的 .codex/hooks.json，仅重写命令以 guild 开头的 hook 组。
- 在同一仓库上用 Claude Code 与 Codex 交替工作的开发者，希望第二个会话直接读到上一个会话留下的 brief 与任务状态。
- 并行运行多个代理会话的团队，需要用原子认领把同一批任务分给不同代理而不发生重复劳动。
- 长期维护的项目希望把研究结论、决策和原则沉淀为可检索的 Lore，而不是在每次上下文压缩后丢失。
- 希望完全本地化存储、不依赖账号或 API 密钥的个人开发者，把 SQLite 状态放在 ~/.guild/ 下。
- 偏好用 shell 调用而非 MCP 工具模式的代理框架，需要每次调用返回结构固定的 JSON 信封。
- 需要在容器中隔离运行代理状态的团队，用 Docker 命名卷挂载 /home/guild/.guild 持久化。
- 需要容器隔离运行状态、用命名卷挂载 /home/guild/.guild 的团队。
如何安装或部署这个 Agent？
macOS/Linux 推荐安装带语义检索的预构建二进制：
curl -fsSL https://github.com/mathomhaus/guild/releases/latest/download/install.sh | sh
guild --version或用 Homebrew：
brew install mathomhaus/tap/guildWindows 使用 PowerShell 安装脚本（关键词检索，暂无向量检索）：
irm https://github.com/mathomhaus/guild/releases/latest/download/install.ps1 | iex
guild --version从源码构建完整版本（含 ONNX 嵌入资源）：
make install仅关键词检索的快速开发构建：
make install-fast通过模块代理安装（仅 BM25）：
go install github.com/mathomhaus/guild/cmd/guild@latestDocker 方式：
make docker-build
docker run --rm -v guild-state:/home/guild/.guild guild:latest --version如何使用这个 Agent？
在项目目录初始化，它会注册项目、写入 AGENTS.md 块并询问是否为检测到的 MCP 客户端注册 guild：
cd ~/projects/myapp
guild init然后在编辑器中让代理开始会话（例如对代理说“start a guild session for myapp”）。代理侧的典型三步：
guild quest accept QUEST-42 --owner agent-a
guild lore appraise "token refresh" --all-projects
guild lore inscribe "token refresh window" --kind observation --summary "tokens expire at 1h; refresh by 55m to avoid race" --topic auth
guild quest journal QUEST-42 "switched to exponential backoff after mock-clock test"
guild quest brief "shipped retry in commit abc1234; QUEST-43 ready to start"
guild quest fulfill QUEST-42 --report "done, shipped in abc1234"可选安装生命周期 hook，让上下文主动进入会话：
guild hooks install
guild hooks list
guild hooks syncCLI 的代理模式可显式开启，输出单一 JSON 信封：
guild quest post "wire the cache layer" --agent
guild quest accept QUEST-99 --agent这个 Agent 有哪些优点和局限？
- 状态是真正跨会话、跨客户端共享的：同一份 SQLite 数据在 Claude Code、Codex、Cursor 之间无需导出或迁移。
- 任务认领是原子的，README 明确说明两个并行会话不会抢到同一个 quest，适合并行代理。
- 检索是 BM25 与向量余弦的排序融合，任一来源的强匹配都不会被稀释，并提供 appraise 先检索后研究的流程。
- 安装路径简洁：预构建二进制或 Homebrew 一条命令，无需账号或 API 密钥，默认嵌入后端在本机运行。
- CLI 代理模式提供 append-only 的最小 JSON 信封契约，便于不消耗工具 schema token 的 harness 调用。
- Windows 上语义检索被禁用（onnxruntime-purego 缺少 Dlopen 支持），只能走 BM25 关键词检索。
- 语义检索完整功能依赖 -tags=withembed 的构建；go install @latest 路径无法嵌入资源，只有关键词检索。
- 启用可选 Ollama 后端时嵌入文本会发往配置的端点，不再是纯本地数据流。
- README 中的能力多为文字描述与演示 GIF，缺少第三方基准；检索质量需自行评估。
这个 Agent 与同类方案有什么区别？
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| Guild 当前 | 50 · 缺口较多 | 命令行工具免费 | ★ 302 | 3 天前 | Go | Codex · Claude Code |
| myc 本地代理记忆与任务层 | 87 · 表现良好 | 命令行工具免费 | ★ 14 | 11 天前 | TypeScript | Codex · Claude Code |
| Mnemo Cortex | 75 · 表现良好 | 自托管服务免费 | ★ 159 | 4 天前 | Python | Codex · Claude Code · Claude.ai |
| Caura | 70 · 存在缺口 | 自托管服务免费版 + 付费版 | ★ 541 | 1 天前 | Python | Codex · Claude Code · Claude.ai |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
README 明确说明本地优先、默认嵌入在本机运行、可选 Ollama 会把嵌入文本发往配置端点，数据流透明度较好（2）。但 least_privilege 仅得 1：`guild hooks install` 会改写编辑器 settings 文件并注入生命周期钩子，虽声称只重写以 guild 开头的命令组，但这是对用户配置的写入权限，且未见权限最小化的显式约束。user_confirmation 得 1：init 有引导式提示，但 hooks 安装与自动注册 MCP 客户端的确认边界描述含糊。sensitive_data_handling 得 1：SECURITY.md 指向 README 的 Privacy 段，但该段未在证据中出现，usage.log 内容与退出机制无法核实。external_effects 得 1：存在对 settings 文件、PATH、~/.guild 状态的写入，回滚仅以链接形式提及（docs/runtime-and-upgrades.md 未提供）。rollback 得 1：仅声称有回滚文档，无具体机制证据。dependency_security 得 1：go.mod 依赖版本较新但无锁定校验、无 SBOM、无依赖审计证据；onnxruntime-purego 为伪版本提交。source_attribution 得 2：LICENSE 含版权署名，模型构建工作流生成 MANIFEST 记录 BAAI 来源与工具版本，但发布者身份未经验证。
README 内部基本一致：安装路径、检索降级、Windows 限制描述相互吻合（2）。dependency_availability 得 1：依赖 Go 1.26.9 这一非常规版本，且 onnxruntime-purego 为未打标签的伪版本，可用性存在风险；无 vendor 或校验和说明。failure_messages 得 2：agent 模式定义 ok/error/hint 信封与退出码，嵌入器失败时降级并报告原因，错误信息设计较清晰，但无实际输出样例验证。
面向多 MCP 客户端（Claude Code、Codex、Cursor）的编码代理，场景描述具体（2）。capability_boundaries 得 2：明确区分 journal/lore/brief 三种写入面，说明 Windows 无语义检索、go install 无嵌入等边界。trigger_precision 得 1：会话启动依赖代理自行理解自然语言指令，hooks 触发依赖环境变量探测，精确性依赖外部 harness 行为，证据不足。environment_fit 得 2：覆盖 macOS/Linux/Windows/Docker，但 Windows 功能受限、Go 版本要求苛刻，扣分。
README 结构清晰，分节合理，指向 docs/ 与 examples/（2）。install_notes 得 3：安装方式详尽，含 curl、brew、PowerShell、make、go install、Docker 及各自取舍。naming_stability 得 1：产品使用大量自造术语（quest/lore/oath/brief/guildmaster），且 agent 模式信封声称 append-only 但无版本号，稳定性证据薄弱。examples_and_faq 得 1：仅链接 examples/ 目录，未在证据中展示内容，无 FAQ。known_limitations 得 2：明确列出 Windows 无语义检索、go install 限制、Codex 无压缩生命周期等。license 得 3：完整 Apache-2.0 文本含版权行。versioning_changelog 得 1：SECURITY.md 称 pre-1.0，无 CHANGELOG，无版本策略细节。maintenance_responsibility 得 1：发布者未经验证，仅 SECURITY.md 提及响应时限，维护责任归属不明。
agent 模式输出为单 JSON 信封，字段明确，便于程序消费（2）。marginal_value 得 2：跨代理共享上下文与原子任务认领确有价值，但同类 MCP 记忆方案众多，差异化证据有限。cost_benefit 得 1：需嵌入 ONNX 运行时、约 127MB 模型下载、特定 Go 版本，部署成本较高，收益未量化。
README 声称 CI 徽章、Docker 测试、检索评估文档，但证据中仅见工作流文件，无测试结果或评估数据（1）。cross_source_corroboration 得 1：README 与 SECURITY.md、go.mod 部分吻合，但 Privacy 段缺失、examples 与 docs 内容未提供，交叉印证有限。fact_inference_separation 得 1：文档混合了事实描述与神话叙事，性能与检索质量声明缺乏数据支撑，事实与推断界限模糊。
- `guild hooks install` 会改写编辑器 settings 文件并注入钩子，安装前应审查其写入范围与回滚方式。
- SECURITY.md 引用的 README Privacy 段在证据中缺失，usage.log 内容与退出机制无法核实。
- 依赖 Go 1.26.9 与未打标签的 onnxruntime-purego 伪版本，构建可复现性与依赖可用性存在风险。
- 发布者身份未经验证，维护责任与更新路径不明确。
- 语义检索需下载约 127MB 模型，Windows 不支持语义检索，部署成本与平台差异需评估。