archie-hq

# Archie 总部 自主响应和协作的超级智能员工 [](https://github.com/sweatco/archie-hq/actions/workflows/ci.yml) [](LICENSE) [](https://docs.anthropic.com/en/docs/claude-code/sdk) [](CONTRIBUTING.md) **Archie 是一个 AI 员工** — 你可以将实际工作委托给它在 Slack 中，就像对待同事一样，它可以完成工程、营销、分析、运营或任何你配置的领域。 在后台，它不是一个聊天机器人，而是一个完整的团队：一个 PM 代理接收你的请求，带来合适的专业代理，让它们协作并报告。 它是基于 [Claude Agent SDK](https://docs.anthropic.com/en/docs/claude-code/sdk) 构建，具有插件架构 — 通过添加插件目录来增加新技能或部门，无需更改核心代码。 ## 目录 - [为什么是团队，而不是单个代理？](#为什么是团队，而不是单个代理？) - [在单个服务器上运行整个团队](#在单个服务器上运行整个团队) - [工作原理](#工作原理) - [快速入门（无 Slack，无 GitHub - 只需 API 密钥）](#快速入门（无-slack，无-github-只需-api-密钥）) - [插件](#插件) - [架构](#架构) - [安全](#安全) - [文档](#文档) - [技术栈](#技术栈) - [贡献](#贡献) - [许可证](#许可证) ## 为什么是团队，而不是单个代理？ 单个代理可以调用子代理，那么为什么要模拟整个团队？有三个原因： - **上下文保持聚焦。** 一个代理处理一个长期任务会迅速填满其上下文窗口，并开始失去线索。 将工作分配给多个代理可以保持每个代理的上下文小、相关且清晰。 - **专家胜过通才。** 具有明确角色的代理 — 由同行支持和达成一致 — 比单个通用代理单独推理产生的工作更好。协作和分歧是功能，而不是开销。 - **协调员委托；领导者囤积。** 给一个“领导”代理一些子代理，它往往会自己做整个工作 — 它认为自己是工作的负责人。 Archie 的 PM 在设计上是一个协调员：它的工作是委托和综合，而不是做工作。 这种结构选择实际上是将工作分配给合适的专家，而不是一个模型试图成为一切。 这也是为什么 Archie 被视为**员工**，而不是工具：它有同事、经理、工作场所（Slack）和人类批准门户，然后再进行任何操作。 你可以通过插件添加新能力，而不是分叉。 ## 在单个服务器上运行整个团队 Archie 是一个生产系统，而不是演示 — 而且它的运行成本故意很低： - **大规模并行，单机。** 每个任务都是一个轻量级、隔离的运行时，因此许多任务可以在一台服务器上并行运行。 在生产中，单个实例为整个 ~100 人公司提供服务，运行并行任务，无资源压力。 - **近乎零基础设施。** 无数据库，无消息代理，无外部状态存储 — 只是磁盘上的文件和 git。 所有运行时状态都生活在一个工作目录下，这使得部署、备份和恢复变得微不足道。 崩溃恢复已内置：任务检查磁盘并在重启后恢复。 ## 工作原理 ``` Slack / CLI → PM 代理 → 领域代理 ↕ ↕ 共享知识日志 / MCP 工具 / Git / API ``` 1. 用户在 Slack 中发送消息（或通过 CLI） 2. **PM 代理** 读取请求，加载相关领域技能，并委托给正确的代理 3. **领域代理** 完成实际工作 — 调查代码，查询数据库，草拟副本，分析数据，调用外部 API — 根据其领域要求 4. PM 综合结果并响应用户 5. 对于需要代码更改的工程任务，用户批准 **编辑模式** — 代理然后创建分支，编写代码，并打开 PR 每个代理都隔离：文件系统访问仅限于其工作空间，Bash 网络被阻止，代码更改需要人类批准。 ## 快速入门（无 Slack，无 GitHub - 只需 API 密钥） Archie 附带一个小型**示例插件集**（一个 PM 加一个通用助理代理），因此新的克隆立即执行某些操作。 此路径只需要一个 Anthropic API 密钥 — 无需 Slack 应用，无需 GitHub 应用，无需 SSH 密钥。 ```bash # 1. 克隆并安装 git clone https://github.com/sweatco/archie-hq.git && cd archie-hq npm install # 2. 配置 — 唯一需要的值是您的 Anthropic API 密钥 cp .env.example .env # 编辑 .env 并设置 ANTHROPIC_API_KEY=sk-ant-... # 3. 使用捆绑的示例插件（symlinks examples/plugins -> workdir/plugins） npm run example:setup # 4. 在 CLI 模式下启动服务器（不需要 Slack/GitHub） npm run dev # 或：npm run docker:dev （在 OS 沙盒中运行） # 5. 在第二个终端中，通过交互式 CLI 与 Archie 聊天 npm run cli ``` 询问类似 *"总结一下：<粘贴几个段落>"* — PM 将委托给示例助理代理并返回结构化摘要。 **进一步：** - **您自己的插件** — 将 `ARCHIE_PLUGINS` 指向 git URL，或用您自己的检出替换 `workdir/plugins`。 阅读捆绑的 **`writing-plugins`** 技能，位于 [`examples/plugins/.claude/skills/writing-plugins/SKILL.md`](examples/plugins/.claude/skills/writing-plugins/SKILL.md) 和 [插件系统](docs/architecture/plugin-system.md) 文档。 - **Slack** — 添加 `SLACK_BOT_TOKEN` + `SLACK_SIGNING_SECRET` 以进行 HTTP Webhook 模式，或 `SLACK_APP_TOKEN` （`xapp-...`）以进行 Socket 模式（不需要公共 URL）。 参见 [本地开发](docs/guides/local-development.md)。 - **GitHub / 仓库代理** — 仅当代码编写代理打开 PR 时需要。 参见 [GitHub 应用设置指南](docs/guides/github-setup.md)，了解应用、权限、事件和环境变量。 插件中声明的仓库在启动时自动克隆。 ## 插件 Archie 完全通过**插件**配置 — 符合 [Claude Code 插件结构](https://docs.anthropic.com/en/docs/claude-code/plugins) 的目录，具有 Archie 特定的扩展。 插件定义： - **代理** (`agents/*.md`) — 具有角色、专业知识、仓库绑定和工具配置的领域代理 - **PM 扩展** (`agents/pm.md`) — 用特定于领域的上下文和 MCP 工具扩展 PM 代理 - **MCP 服务器** (`.mcp.json`) — 外部工具集成（Jira、Firebase、BigQuery 等） - **技能** (`skills/`) — PM 代理可以按需加载的特定领域工作流 - **钩子** (`hooks/`) — Claude Code 钩子，用于成本防护、验证等 示例插件结构： ``` plugins/ ├── pm/ # PM 扩展 │ ├── .claude-plugin/ │ │ └── plugin.json │ ├── agents/ │ │ └── pm.md # 用特定于领域的上下文和 MCP 工具扩展 PM │ └── skills/ │ └── engineering/SKILL.md # PM 加载的按需工作流 ├── engineering/ # 工程领域（仓库代理） │ ├── .claude-plugin/ │ │ └── plugin.json │ └── agents/ │ └── mobile.md # 仓库代理 — 具有 metadata.archie.repo 绑定 ├── marketing/ # 营销领域（插件代理） │ ├── .claude-plugin/ │ │ └── plugin.json │ ├── agents/ │ │ └── copywriter.md # 插件代理 — 工作空间 + 工具，无仓库 │ ├── skills/ │ │ └── marketing/SKILL.md # PM 加载的领域工作流 │ └── hooks/ │ └── hooks.json # Claude Code 钩子（成本防护、验证等） └── .mcp.json # 共享的 MCP 服务器配置（firebase、jira 等） ``` **仓库代理** 需要在其 frontmatter 中包含 `metadata.archie.repo` 块以绑定到 GitHub 仓库： ```yaml --- role: 高级 React Native 工程师 metadata: archie: repo: github: org/mobile-app baseBranch: main mcpServers: - firebase - bugsnag --- ``` **插件代理** 只需要 `role` 和可选的 `mcpServers` — 无仓库绑定，它们获得工作空间和工具。 要添加新领域：创建插件目录，定义 markdown 前面部分中的代理，然后重启。 无需更改核心代码。 ## 架构 Archie 有三种代理类型，均通过插件配置： | 代理 | 示例 | 它做什么 | | ----------------- | ------------------------ | ----------------------------------------------------------------- | | **PM 代理** | 每个任务一个 | 协调代理，与用户交谈，按需加载领域技能 | | **仓库代理** | 后端，移动端 | 完全的代码库访问，git，PR，CI 工具 — 每个仓库一个 | | **插件代理** | 撰稿人，分析师，运维 | 任何领域 — 获得工作空间，MCP 工具和读写访问 | 仓库代理用于工程工作（代码 + git + GitHub）。插件代理用于其他所有领域 — 它们获得工作空间、任何 MCP 工具和对其领域的读写访问。PM 代理通过特殊的 `pm` 插件扩展，该插件添加领域上下文、MCP 工具和技能。 **关键功能：** - 代理到代理通过消息队列进行通信 - 用于查找和审计跟踪的共享知识日志 - 用于隔离的并行任务执行的 Git 共享克隆（仓库代理） - 用于任何外部服务的 MCP 工具集成（插件代理） - 代码更改的人工批准门户（只读 → 编辑模式） - 自动 PR 创建和合并编排 - 用于文件系统和网络隔离的操作系统级沙盒（bubblewrap） - 具有结构化输出和注入防御的网络研究管道 - 每个任务的资源预算（研究请求，时钟超时） ## 安全 代理在具有纵深防御的沙盒环境中运行： - **文件系统隔离** — 每个代理只能通过 bubblewrap（Bash）和 PreToolUse 钩子（读取/写入/编辑）访问其自己的工作空间 - **网络拒绝所有** — Bash 无法访问互联网；仅通过受控的研究管道访问网络 - **工具拒绝列表** — 所有代理上的 WebSearch/WebFetch 被阻止；只读模式下的 Write/Edit 被阻止 - **人工门户** — 编辑模式需要 Slack 批准；PR 需要审查后合并 - **Git 安全** — 服务器端分支保护；不强制推送；Bash 中阻止 git 推送（无网络） 参见 [安全架构](docs/architecture/security.md)，了解完整的威胁模型、执行层和部署要求。 ## 文档 **架构：** - [概述](docs/architecture/overview.md) — 系统设计和概念 - [代理](docs/architecture/agents.md) — 代理类型、提示、通信 - [编排](docs/architecture/orchestration.md) — 任务生命周期、消息路由 - [安全](docs/architecture/security.md) — 沙盒、威胁模型、防御层、部署 - [插件系统](docs/architecture/plugin-system.md) — 插件结构和代理注册 - [编辑模式](docs/architecture/edit-mode.md) — 批准流程、共享克隆、git 工作流程 - [持久性](docs/architecture/persistence.md) — 会话存储和恢复 - [Slack 集成](docs/architecture/slack-integration.md) — UX 层 - [GitHub 集成](docs/architecture/github-integration.md) — PR 工作流程 - [网络研究](docs/architecture/web-research.md) — 多代理研究管道 **指南：** - [本地开发](docs/guides/local-development.md) — 使用 Slack、GitHub 应用、ngrok 完成完整设置 - [GitHub 应用设置](docs/guides/github-setup.md) — 创建应用、所需权限和 Webhook 事件、环境变量 - [插件系统](docs/architecture/plugin-system.md) — 插件的结构和加载方式（以及 `examples/plugins/.claude/skills/` 下的捆绑 `writing-plugins` 技能） - [Docker 设置](DOCKER.md) — 容器配置和故障排除 - [部署](docs/guides/deployment.md) — 生产部署和运维 **项目：** - [贡献](CONTRIBUTING.md) — 如何设置、开发循环和 PR 期望 - [安全策略](SECURITY.md) — 如何报告漏洞 - [行为准则](CODE_OF_CONDUCT.md) — 社区标准 - [变更日志](CHANGELOG.md) — 按版本划分的显著更改 ## 技术栈 - **运行时：** Node.js 和 TypeScript - **AI：** [Claude Agent SDK](https://docs.anthropic.com/en/docs/claude-code/sdk) - **集成：** Slack API（Bolt）、GitHub 应用（Octokit）、MCP 服务器 - **沙盒：** Bubblewrap（Linux）、sandbox-exec（macOS） - **存储：** `ARCHIE_WORKDIR` 下的文件会话 ## 许可证 根据 **GNU Affero General Public License v3.0 或更高版本**（AGPL-3.0-or-later）许可。参见 [LICENSE](LICENSE)。 用通俗的话来说：您可以自由使用、研究、修改和自我托管 Archie，包括在您自己的组织内，无需限制。 AGPL 的网络共用条件意味着，如果您运行一个**修改**版本作为服务提供给他人（例如托管服务），您必须使您的修改源代码可用于相同的许可证。 这让改进流回社区。 该软件按“原样”提供，不保证任何明示或暗示的任何类型的保证。 有关完整条款，请参见 LICENSE。