demetere/pi-hive

# pi-hive  ## 这是什么 大多数 agent 框架交给你的是一个固定的集群和一个黑盒。`pi-hive` 则 截然相反：**它是 config-first（配置优先）的，并且你拥有整个树。** 在 *你*描述好团队之前，什么都不会运行。 - **Config-first —— 你拥有一切。** 在项目包含 `.pi/hive/hive-config.yaml` 之前，该扩展不会执行任何操作。 那一个文件既是 opt-in（选择启用）触发器，*也是*团队定义：你需要声明 agent、它们的模型、它们的 工具、它们的文件系统域以及它们的嵌套关系。角色不是魔法出来的 —— 如果一个节点拥有成员，它就是 **lead**；如果没有，它就是 **member**，而 agent 只能 **委派给其直接下属**。你通过嵌套来表达权限， 而不是编写策略。每个 agent 的 prompt、知识和技能都以纯文本文件的形式存放在你仓库的 `.pi/hive/` 下，并随你的代码一起进行版本控制。请参阅 **[SETUP.md](./SETUP.md)** 获取完整的编写指南。 - **真正的层级结构，而不是扁平的集群。** 可见的会话是一个 *orchestrator*（编排器）， 它负责路由但从不过行编辑。它将任务委派给团队 **lead**，每个 lead 将工作分发给其 **member**，并且每个 agent 都作为其自身独立的 `pi` 子进程运行，带有受限的工具白名单和 **强制执行的写入域** —— 一个 worker 在物理层面绝对无法编辑其 lead 授权范围之外的文件。嵌套可以 任意深入。 - **先规划，后执行 —— 两个独立的团队。** 会话在三种 模式之一运行（`normal → plan → hive`，通过 `Ctrl+Alt+T` 循环切换）。**Plan 模式** 激活一个 `planning:` 团队，它会生成完整的 spec 并且*不编写任何代码*。 **Hive 模式**激活一个独立的 `hive:` 团队，负责执行已批准的 spec。它们在你的 config 中是独立的树，因此项目永远不会在不知情的情况下针对其编码树运行规划。 - **Spec 驱动，由 OpenSpec 支持。** 非简单的工作会通过固定的关卡 — `proposal → requirements → design → tasks` — 存储在 `.pi/hive/plans//` 下。[OpenSpec](https://github.com/Fission-AI/OpenSpec) （一个 CLI 依赖项）是存储和验证器：它管理着 artifact 依赖 图，并报告每个 artifact 的就绪状态。执行是硬性限制的 —— `/hive-execute` 在 `tasks.md` 存在且其关卡被批准之前拒绝运行。 - **Human-in-the-loop（人工介入）计划审查，自托管。** `pi-hive` 将 [Plannotator](https://github.com/backnotprop/plannotator) 审查界面**直接嵌入到其自己的 仪表板中** —— 无需为每个审查启动服务器。你可以在浏览器中对每个计划 artifact 进行标注、批准或拒绝；批准操作会解除对规划器的阻碍，拒绝操作会将你的 反馈路由回去并阻止该关卡。判决结果会持久化保存到本地 SQLite。 - **本地、私密的遥测。** 每个会话都会将其专属的定制事件日志流式传输到 `.pi/hive/sessions/`，并且 `/hive-observe` 会打开一个本地 Solid + Vite 仪表板 （`127.0.0.1:43191`），显示每个项目和会话的实时拓扑、委派生命周期、token 以及 成本。不会向任何第三方发送任何内容。 ## 安装位置与激活 推荐使用 `pi install` 从 GitHub 安装： ``` pi install git:github.com/demetere/pi-hive # latest main pi install git:github.com/demetere/pi-hive@v0.1.0 # pin a tag/commit ``` `pi install` 也接受完整的 HTTPS 或 SSH URL，例如 `pi install https://github.com/demetere/pi-hive` 或 `pi install ssh://git@github.com/demetere/pi-hive`。Pi 会为该包运行 `npm install`， 因此扩展的运行时依赖项 （[OpenSpec](https://github.com/Fission-AI/OpenSpec)）会自动获取；Pi 主机 包被声明为 peer dependencies（对等依赖项），并在加载时由 Pi 提供。 你也可以在 Pi 的 `settings.json` 中以声明式的方式添加它： ``` { "packages": ["git:github.com/demetere/pi-hive"] } ``` 对于本地开发，可以在不安装的情况下临时加载检出代码： ``` pi -e . # from the repository root ``` 安装后，Pi 会为**每个**项目自动发现该包。 对于仓库优先的开发，请使用 `just` 作为唯一的命令事实来源： ``` just pi-dev # run this checkout temporarily with pi -e . just pi-reload-dry-run # preview copying this checkout to ~/.pi/agent/extensions/pi-hive just pi-reload # update the user-level extension from this checkout ``` 运行 `just pi-reload` 之后，在 Pi 中执行 `/reload`。 - **仅在项目包含 `.pi/hive/hive-config.yaml` 时激活。** 如果没有该文件，扩展不会注册任何内容 —— 没有工具，没有命令，也没有 hooks —— 因此非 hive 项目完全不受影响。 ## 快速开始 1. 安装扩展（见上文），以便 Pi 为每个项目发现它。 2. 在你想要运行 hive 的项目中，创建 `.pi/hive/hive-config.yaml`。此文件是 opt-in（选择启用）触发器并定义团队树 —— 编写它的最快方法是将一个 agent 指向 [SETUP.md](./SETUP.md)，让它来采访你（参见下方的[在新项目中构建 hive](#build-a-hive-in-a-new-project)）。 3. 在该项目中启动 Pi 并按 `Ctrl+Alt+T`（或运行 `/hive`）进入 hive 模式；可见的会话将成为一个 Lead，将其任务委派给其团队。 4. 运行 `/hive-observe` 以在 `http://127.0.0.1:43191` 打开实时遥测仪表板。 如果发现任何异常，`/hive-doctor` 将运行只读的诊断。 ## 环境要求 - **Bun ≥ 1.1** —— 遥测仪表板服务器（`src/observability/server/index.ts`）在 Bun 下运行并使用 `bun:sqlite`。如果缺少 Bun，`/hive-observe` 命令会通知你。 - Pi 主机在加载时提供 `@earendil-works/pi-coding-agent` 和 `@earendil-works/pi-tui`（声明为 peer deps）。 ## 打包与分发 此扩展是自包含的，并以两种方式发布： - **Git** —— 克隆或作为 submodule 放入 `~/.pi/agent/extensions/`。预构建的仪表板（`ui/web/dist/`）已提交，因此**在安装时没有构建步骤**。依赖文件夹被 gitignore 忽略。 - **Tarball/package** —— `just pack-dry-run` 预览已发布的包内容。根目录的 `package.json` 的 `files` 白名单仅发布运行时代码 + 预构建的 `dist/`；依赖文件夹永远不会发布。包的 prepack hook 委托给 `just prepack`，因此发布的包永远不会包含过期的 UI。 在编辑了 `ui/web/src/` 下的任何内容后，重新构建已提交的 bundle： ``` just dashboard-build # Vite build + stamp dist/.build-hash ``` 防止发布过期的 UI（可接入 pre-commit hook 或 CI）： ``` just dashboard-verify # fails if dist/ is out of date with src/ ``` ## 在新项目中构建 hive 将一个 agent 指向构建指南，让它来采访你： **[SETUP.md](./SETUP.md)** 是权威的、独立的操作手册：包含 config + frontmatter schema、用于 orchestrator/lead/member 的可直接复制的模板、访谈问题、约定（工具、域、distiller）以及验证检查表。 ## 模式与命令（仅在配置了 hive 时才会注册） `pi-hive` 具有三种硬编码的会话模式：`normal` → `plan` → `hive` → `normal`。循环顺序是不可配置的。 - `normal` —— 普通 Pi 聊天。没有 hive 工具或 hive 强制执行机制。 - `plan` —— `planning:` 团队处于活动状态。可见的主会话应为 `agent-type: planner`；plan 关卡在 `.pi/hive/plans//` 下按 `proposal → requirements → design → tasks` 的顺序运行。 - `hive` —— `hive:` 团队处于活动状态。可见的主会话应为 `agent-type: lead`；执行 agent 构建已批准的 `tasks.md`。 命令： - `/hive-normal`、`/hive-plan-mode`、`/hive` —— 切换到特定模式。 - `/hive-toggle` 或 `Ctrl+Alt+T` —— 循环切换 `normal → plan → hive → normal`。 - `/hive-execute ` —— 验证 change 是否存在、是否有 `tasks.md` 并且 tasks 关卡是否已批准，然后切换到 hive 模式并驱动执行。 - `/hive-plan [change-id]` —— 列出计划 change 或选择/显示其中一个。 - `/hive-status` —— 打开实时层级视图（每个 agent 的状态、token、成本）。 - `/hive-doctor` —— 对 opt-in 配置、已加载的 agent、仪表板资源、Bun 可用性、SDD 状态和遥测路径运行只读诊断。 - `/hive-observe` —— 重启/打开本地浏览器仪表板以查看全局 hive 遥测（默认为 `http://127.0.0.1:43191`）。 - `/hive-observe-stop` —— 停止配置端口上的遥测仪表板。 hive 工具集在代码中受到模式/类型的范围限制，用户不可配置：plan 模式向符合条件的 planner/reviewer 暴露 planning/store/review 工具，hive 模式向符合条件的执行 agent 暴露 delegation/status/review 工具，而 normal 模式不暴露任何工具。仪表板的 host/port 默认为 `127.0.0.1:43191`，并且只能使用 `HIVE_TELEMETRY_HOST` / `HIVE_TELEMETRY_PORT` 进行更改。 SDD/OpenSpec 是用于非简单 hive 工作的默认操作模式。Agent 的 `skills:` 路径通过 `--no-skills` 加上重复的 `--skill ` 显式传递给 worker Pi 进程，因此 Hive 重用了 Pi 原生的 skill 系统，且不会发生自动发现的泄露。 ## 已配置项目的布局 ``` .pi/hive/ hive-config.yaml # the team tree + global settings (also the activation trigger) agents/ # one folder per agent, mirroring the tree; each holds .md + -mental-model.yaml knowledge/ # always-inlined context/reference files skills/ # Pi Agent Skills explicitly granted to agents sessions/ # runtime transcripts + hive-events.jsonl telemetry (gitignore this) ``` 完整的目录契约请参见 SETUP.md §4。 ## Hive 遥测 `pi-hive` 为每个 hive 会话将其自身定制的遥测流写入 `.pi/hive/sessions//hive-events.jsonl`，并将实时可变状态快照写入 `.pi/hive/sessions//hive-state.json`。顶层会话也会注册在位于 `~/.pi/agent/hive/telemetry-sessions.jsonl` 的全局索引中，因此一个 `/hive-observe` 仪表板可以显示来自多个项目的 hive 以及许多同时运行的会话。 仪表板 UI 是一个位于 `ui/web/` 下的预构建 Solid + Vite 单页应用。服务器（`src/observability/server/index.ts`）从 `ui/web/dist/` 提供已构建的 bundle，该目录已提交，因此最终用户无需构建步骤。如果你更改了 `ui/web/src/` 下的任何内容，请重新构建它： ``` just dashboard-install # first time only just dashboard-build # rebuild dist/ — the server picks it up on next page load ``` 在发布或打开 release PR 之前，运行与 CI 相同的关卡： ``` just ci ``` 在 UI 开发期间，你可以运行 `just dashboard-dev`（在端口 43192 上运行 Vite HMR），并在 `HIVE_TELEMETRY_PORT` 上运行遥测服务器；开发服务器将 `/events`、`/states`、`/stream` 和 `/health` 端点代理到该遥测服务器。 这并未连接到第三方的可观测性服务器。运行时的旋钮是专门针对 hive 的： - `HIVE_TELEMETRY_PORT` —— 仪表板端口，默认为 `43191` - `HIVE_TELEMETRY_HOST` —— 仪表板主机，默认为 `127.0.0.1` - `HIVE_TELEMETRY_NO_OPEN=1` —— 启动服务器但不打开浏览器 - `HIVE_TELEMETRY_REGISTRY` —— 覆盖全局会话注册表路径 - `HIVE_TELEMETRY_DB` —— 覆盖本地 SQLite 数据库路径

标签：自动化攻击