From 37765b3754250d74a172cfab7ac5b64ceb34fcf7 Mon Sep 17 00:00:00 2001 From: bigduu Date: Mon, 31 Aug 2026 00:38:06 +0800 Subject: [PATCH] docs: align install and config guidance (#16) --- ARCHITECTURE.md | 36 +++++++++++++++++++++++++----------- README.md | 46 +++++++++++++++++++++++++++++++++------------- 2 files changed, 58 insertions(+), 24 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 19bf30e..90b119f 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -1,13 +1,26 @@ # Magpie (鹊) — architecture -Magpie is the standalone IM connector for Bamboo (extraction of bamboo-server's -in-process `connect/` module, per bamboo epic #477). Named after 鹊桥 — the -magpie bridge that spans between worlds. +Magpie is the standalone IM connector for +[Bamboo](https://github.com/bigduu/Bamboo-agent) (extraction of bamboo-server's +in-process `connect/` module, per +[Bamboo #477](https://github.com/bigduu/Bamboo-agent/issues/477)). Named after +鹊桥 — the magpie bridge that spans between worlds. It drives Bamboo agent sessions from IM platforms (Telegram, Feishu/Lark) exclusively over **Bamboo's public API** — never in-process internals — and ships as a Bamboo **service plugin** (bamboo-plugin `services` artifact kind, -bamboo #479): bamboo-server installs, spawns, supervises, and restarts it. +[Bamboo #479](https://github.com/bigduu/Bamboo-agent/issues/479)): bamboo-server +installs, spawns, supervises, and restarts it. + +## Distribution boundary + +Each GitHub release contains a `magpie-plugin-v.tar.gz` bundle for +`bamboo plugin install` and separate `magpie-v-.*` +standalone archives. Installing the plugin bundle delegates platform-binary +selection and process lifecycle to Bamboo; running a standalone binary leaves +both with the operator. The committed `plugin/plugin.json` is only the +`0.0.0`/checksum template consumed by release CI, not an installable release +manifest. ## Layout @@ -36,7 +49,10 @@ plugin/ artifacts, sha256 filled by release CI) ``` -## Key mappings from the in-proc module (bamboo #480 gap analysis) +## Key mappings from the in-proc module + +These are the seams shipped by +[Bamboo #480](https://github.com/bigduu/Bamboo-agent/issues/480): | in-proc dependency | Magpie replacement | |---|---| @@ -55,7 +71,7 @@ plugin/ ```json { - "bamboo": { "base_url": "http://127.0.0.1:9560", "device_id": "…", "token": "…" }, + "bamboo": { "base_url": "http://127.0.0.1:9562", "device_id": "…", "token": "…" }, "platforms": [ { "type": "telegram", "token": "…", "allow_from": ["…"] }, { "type": "feishu", "app_id": "…", "app_secret": "…", "domain": "feishu", "allow_from": ["…"] } @@ -63,9 +79,8 @@ plugin/ } ``` -v1 keeps secrets plaintext in the file (0600 perms enforced at load, warn -otherwise) — bamboo's encrypted round-trip is coupled to bamboo's key store -and does not extract; revisit post-v1. +Magpie keeps secrets plaintext in the file. On Unix, group- or world-readable +permissions produce a startup warning; Magpie does not rewrite the file mode. ## Invariants carried over from bamboo connect/ @@ -80,5 +95,4 @@ and does not extract; revisit post-v1. - WS resubscribe replays critical events + last budget only — a mid-run reconnect misses tokens (terminal event still lands; next edit repaints). -- Two round trips per message (chat then execute) until/unless bamboo grows - a combined /turn endpoint. +- Each message uses two requests: `/chat`, then `/execute`. diff --git a/README.md b/README.md index 6d1beb0..26cc39b 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Magpie (鹊) -Magpie is the standalone IM connector for [Bamboo](https://github.com/bigduu/bamboo). It +Magpie is the standalone IM connector for [Bamboo](https://github.com/bigduu/Bamboo-agent). It drives Bamboo agent sessions from IM platforms (Telegram, Feishu/Lark) exclusively over Bamboo's public HTTP/WS API — never in-process internals — and ships as a Bamboo **service plugin**: bamboo-server installs, spawns, supervises, and restarts it. @@ -9,17 +9,37 @@ Named after 鹊桥 (_què qiáo_, "magpie bridge") — the bridge of magpies tha River in the Qixi legend, connecting two separated worlds. Magpie spans the same gap between a chat platform and a running Bamboo agent. -This repository is bamboo epic #477's extraction of bamboo-server's in-process `connect/` -module into a standalone binary. See [`ARCHITECTURE.md`](./ARCHITECTURE.md) for the full -design, the Bamboo API surface Magpie depends on, and the layout of `src/`. +This repository is [Bamboo #477](https://github.com/bigduu/Bamboo-agent/issues/477)'s +extraction of bamboo-server's in-process `connect/` module into a standalone binary. See +[`ARCHITECTURE.md`](./ARCHITECTURE.md) for the full design, the Bamboo API surface Magpie +depends on, and the layout of `src/`. -## Quickstart +## Install -```bash -cargo build --release -./target/release/magpie --config ./magpie.json --check # smoke-test auth + connectivity -./target/release/magpie --config ./magpie.json # run -``` +[Magpie releases](https://github.com/bigduu/Magpie/releases/latest) publish two different +artifacts: + +- `magpie-plugin-v.tar.gz` is the Bamboo service-plugin bundle. With `bamboo serve` + running, replace `` with the latest numeric release version (without the leading + `v`) and install it with: + + ```bash + bamboo plugin install https://github.com/bigduu/Magpie/releases/download/v/magpie-plugin-v.tar.gz + ``` + + Bamboo verifies the signed release's `.sig` sidecar with the Magpie key in its default + trust store, so no trust-bypass flags are needed. Bamboo then selects the platform binary + and owns the service lifecycle. Put `magpie.json` at + `/plugin_service_config/magpie/config.json` (normally + `~/.bamboo/plugin_service_config/magpie/config.json`); Bamboo passes that path to Magpie. +- `magpie-v-.*` contains a standalone binary. Use it when another process + manager owns Magpie, or build the same binary from source: + + ```bash + cargo build --release + ./target/release/magpie --config ./magpie.json --check # smoke-test auth + connectivity + ./target/release/magpie --config ./magpie.json # run + ``` `--check` calls `GET /api/v1/execute/defaults` against the configured Bamboo instance and prints the resolved model, then exits — use it to confirm the device token and base URL are @@ -28,14 +48,14 @@ correct before wiring up a platform. ## Config Magpie reads `magpie.json` from (in priority order): the `--config` flag, then -`$BAMBOO_PLUGIN_SERVICE_CONFIG`, then `./magpie.json`. On unix, a config file that is +`$BAMBOO_PLUGIN_SERVICE_CONFIG`, then `./magpie.json`. On Unix, a config file that is group- or world-readable triggers a startup warning (it carries the bamboo device token and -platform bot secrets in plaintext — v1 scope, see `ARCHITECTURE.md`). +platform bot secrets in plaintext; see `ARCHITECTURE.md`). ```json { "bamboo": { - "base_url": "http://127.0.0.1:9560", + "base_url": "http://127.0.0.1:9562", "device_id": "bamboo_abc123", "token": "bd1_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" },