@graychennpm/codebridge 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.1.0 — 2026-10-10
+
+First npm distribution release.
+
+- Ships the Bridge, host Runner, internal modules and Workbench static assets in one installable package.
+- Adds interactive initialization with credential verification, Telegram allowlists, keychain references and safe cancellation.
+- Generates a private config with a random Runner token for non-interactive setup, without replacing an existing file.
+- Preserves secret references during config updates and redacts credentials from Feishu SDK logs.
+- Adds configurable context/idle session rotation and scopes deployment instructions to CodeBridge maintenance tasks.
+- Provides a shared package-derived version, version consistency checks and isolated package-install verification.
+
+Runtime requirements: Node.js 22.19 or newer. macOS is the supported host setup; this candidate does not add Linux service management. Agent CLI installation and provider authentication remain separate setup steps.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CodeBridge contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,218 @@
-# Temporary Holding Version
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="apps/web/public/brand/agent-logo-carbon.svg" />
+    <img alt="AGENT · CodeBridge" src="apps/web/public/brand/agent-logo.svg" width="320" />
+  </picture>
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# CodeBridge
+
+Self-hosted, multi-channel [Agent Client Protocol (ACP)](https://agentclientprotocol.com) gateway for coding agents.
+
+Control local **Cursor**, **Claude Code**, **Codex**, and optionally **Pi** from Feishu or Telegram while your source code, Git credentials, MCP tools, and agent sessions stay on your own Mac/Linux host.
+
+[简体中文](README.zh-CN.md)
+
+## What it does
+
+```text
+Feishu WebSocket ─┐
+                  ├─ Bridge ── authenticated HTTP/SSE + token ── Runner ── ACP agents ── local files
+Telegram polling ─┘
+```
+
+| Component | Responsibility |
+|-----------|----------------|
+| **Bridge** | Channel connections, access policy, slash commands, session routing, and reply presentation |
+| **Runner** | Host-side ACP sessions, agent processes, file/Git access, and permission handling |
+| **Agent adapters** | Cursor, Claude Code, and Codex ACP adapters plus the native Pi Node SDK adapter |
+
+The Bridge and Runner are intentionally separate: the Bridge can be remote or containerized, but the Runner stays next to the CLIs and files it needs to access.
+
+## Install with npm
+
+Requires Node.js 22.19 or newer. Install with `npm install -g @graychennpm/codebridge@0.1.0`, then run `codebridge init`. Start `codebridge-runner` and `codebridge start` in separate terminals. The package includes the Bridge, host Runner and Workbench assets; no source build is needed.
+
+You can also run `npx @graychennpm/codebridge@0.1.0 init`. For local distribution, `pnpm package:release` produces a tarball in `dist/`; `pnpm test:package` verifies a clean installation. See the [release guide](docs/zh-CN/npm-release.md).
+
+## Highlights
+
+- Feishu long connection with streaming cards and optional custom menu
+- Telegram Bot API long polling, including a native command menu
+- Scoped native mentions on Feishu and Telegram for the requester or participants explicitly mentioned in a task
+- One ACP path for `cursor`, `claude`, and `codex`; the legacy direct-CLI transport is gone
+- Resume local sessions with `/resume`, `/resume last`, or `/resume all`
+- Live adapter capabilities through `/model`, `/effort`, `/permission`, and `/config`
+- Named workspaces, additional directories, `/clone`, `/pull`, and file delivery
+- macOS TCC-aware `/root add` flow with an immediate “waiting for system permission” status
+- launchd KeepAlive on macOS, or the built-in watchdog for manual background mode
+
+## Quick start
+
+### Requirements
+
+- macOS or Linux
+- Node.js ≥ 22.19, pnpm, and curl. The WorkItem Event Store uses Node's built-in `node:sqlite`; the optional Pi SDK adapter follows Pi's Node runtime requirement.
+- At least one local agent CLI: `cursor-agent`, `claude`, or `codex`
+- A Feishu custom app with a bot, or a Telegram bot token
+
+### Install and start
+
+```bash
+git clone https://github.com/Chenkeliang/CodeBridge.git
+cd CodeBridge
+
+# Installs dependencies, builds, creates config, and checks local CLIs.
+./scripts/start.sh setup
+
+# If setup did not start the service, start Runner + Bridge in the background.
+./scripts/start.sh start
+```
+
+The setup wizard (also available as `codebridge init`) writes `~/.codebridge/config.yaml`. It verifies Feishu / Telegram credentials on the spot, generates a Runner token, and picks the project root and default agent. Secrets go to the OS keychain; the file only holds `keychain:` references. Existing settings and comments are preserved unless explicitly changed in the wizard; YAML formatting may change. Telegram requires a user or chat allowlist. Automatic user detection uses a one-time code sent to the bot in a private chat.
+
+With `codebridge init --defaults` or no TTY, only a missing config is created. A random Runner token is stored in plaintext in a mode-600 file (or as an environment reference when `RUNNER_TOKEN` is set). This path does not access the keychain or verify channel credentials. Run `codebridge secrets migrate` afterward to move plaintext secrets to the keychain.
+
+Verify the installation:
+
+```bash
+./scripts/start.sh status
+./scripts/start.sh doctor
+```
+
+On macOS, use launchd for boot-time startup and KeepAlive. Choose one process manager; do not mix launchd with manual `start.sh` mode:
+
+```bash
+./scripts/start.sh install-launchd all
+./scripts/start.sh restart
+```
+
+When upgrading from the former `feishu-code-bridge` name, `restart` or `install-launchd` migrates the default data directory from `~/.feishu-code-bridge` to `~/.codebridge` and replaces the old launchd jobs. Existing files in `~/.codebridge` are never overwritten, and an explicitly configured `DATA_DIR` is never moved. If you used the former `Feishu Code Runner.app`, run `./scripts/start.sh install-macos-runner` and approve protected folders again: macOS does not transfer TCC grants to the new Bundle ID.
+
+Useful lifecycle commands:
+
+```bash
+./scripts/start.sh status
+./scripts/start.sh restart
+./scripts/start.sh stop
+./scripts/start.sh fg       # foreground Bridge debugging
+```
+
+### Configure a channel
+
+For Feishu, create an enterprise custom app, enable the bot, and subscribe to the long-connection events described in [Feishu app setup](docs/zh-CN/feishu-app-setup.md).
+
+Telegram is optional. It can run alongside Feishu or in Telegram-only mode:
+
+```yaml
+telegram:
+  botToken: "123456:replace-with-bot-token"
+  allowedUsers: ["123456789"]          # optional allowlist
+  allowedChats: ["-1001234567890"]     # optional allowlist
+  pollingTimeoutSec: 25
+```
+
+See [examples/config.full.yaml](examples/config.full.yaml) for the complete configuration shape.
+
+## Phone-first commands
+
+`/menu` and `/help` intentionally return a short list for small screens. Use `/help full` for the grouped reference.
+
+| Command | Use |
+|---------|-----|
+| `/status` | Check backend, project directory, model, permission, and active-task state |
+| `/resume last` | Continue the most recent local session in the current directory |
+| `/new` | Start a clean ACP session |
+| `/stop` | Stop the current task and clear queued Feishu prompts |
+| `/backend claude` | Switch the current chat to Cursor, Claude, or Codex |
+| `/model` | List live models; `/model <name>` switches one |
+| `/permission` | List live modes; `/permission <mode>` switches one |
+| `/ws list` | Show saved workspaces |
+
+Other useful commands:
+
+```text
+/resume [N|last|all]
+/effort [list|level|default]
+/config [id value|default]
+/root add|remove|rm /absolute/path
+/send /absolute/path/to/file
+/clone <git-url> [directory-name]
+/pull
+/approve  /deny  /steer <instruction>
+```
+
+The exact model, effort, permission, and boolean config values come from the connected ACP adapter, so `/model list`, `/effort list`, `/permission list`, and `/config` are the source of truth.
+
+To request a real channel notification, say “mention me when it finishes” or explicitly mention a participant in the task. The Agent uses `fcb mention` internally; ordinary replies do not create extra notifications.
+
+## Sessions, directories, and permissions
+
+- Session bindings are isolated by channel chat, topic, backend, and working directory; session metadata is persisted under the configured data directory.
+- `/cd` changes the current project. `/ws save|use` gives frequently used directories short names.
+- `/root add /absolute/path` adds an ACP `additionalDirectories` entry. On macOS, Runner touches the directory first so the normal TCC prompt can appear. The chat reports that it is waiting for system authorization, but the command does not silently grant macOS access.
+- `runnerHost.acpPermissionPolicy` controls agent permission requests:
+
+  | Policy | Behavior |
+  |--------|----------|
+  | `auto_allow` | Runner approves ACP permission requests automatically (default for trusted local use) |
+  | `prompt_feishu` | Pause and wait for `/approve` or `/deny` in the chat; timeout rejects |
+  | `prompt_deny` | Reject permission requests automatically |
+
+- On macOS, `./scripts/start.sh install-macos-runner` creates the optional fixed-identity helper. Ad-hoc signing is free and local; TCC still requires the user’s approval.
+
+Read [SECURITY.md](SECURITY.md) before exposing anything beyond localhost.
+
+## Concurrency and known boundaries
+
+- Different chats can run in parallel up to `runnerHost.maxConcurrentRuns` (default `4`).
+- A Feishu `chatId + topic` has one active task. Later messages queue up to five; `/stop` cancels the task and clears that queue.
+- A group shares one backend, directory, model, and session binding. Use separate chats for independent projects or agents.
+- Agent notifications are limited to the current sender and participants explicitly mentioned in the current task. CodeBridge does not search the organization directory, mention everyone, or accept arbitrary user IDs from the Agent.
+- `/transport` remains only as a compatibility response; ACP is the only transport.
+
+## ACP backends
+
+| Backend | ACP command |
+|---------|-------------|
+| Cursor | `cursor-agent acp` |
+| Claude Code | `npx -y @agentclientprotocol/claude-agent-acp@0.81.1` |
+| Codex | `npx -y @agentclientprotocol/codex-acp@1.13.1` |
+
+Resume semantics depend on the adapter: Claude/Codex use `session/resume`; Cursor uses `session/load`.
+
+Probe adapters without starting the Bridge:
+
+```bash
+node scripts/acp-probe.mjs
+node scripts/acp-probe.mjs --backend codex
+RUNNER_TOKEN=... node scripts/test-acp-live.mjs --backend cursor
+```
+
+## Documentation
+
+| Topic | Link |
+|-------|------|
+| Feishu app and permissions | [docs/zh-CN/feishu-app-setup.md](docs/zh-CN/feishu-app-setup.md) |
+| Feishu custom menu | [docs/zh-CN/feishu-bot-menu.md](docs/zh-CN/feishu-bot-menu.md) |
+| Manual / Docker quick start | [docs/zh-CN/quickstart.md](docs/zh-CN/quickstart.md) |
+| Model, effort, and permission | [docs/zh-CN/model-effort.md](docs/zh-CN/model-effort.md) |
+| Docker Bridge + host Runner | [docs/zh-CN/deploy/docker-host-runner.md](docs/zh-CN/deploy/docker-host-runner.md) |
+| Multi-project Agent workbench baseline | [docs/orchestration/README.md](docs/orchestration/README.md) |
+| Full config example | [examples/config.full.yaml](examples/config.full.yaml) |
+| Security policy | [SECURITY.md](SECURITY.md) |
+
+## Development
+
+```bash
+pnpm install
+pnpm run lint
+pnpm run build
+pnpm test
+```
+
+The monorepo contains `core`, `backends`, `work-items`, `policy`, `run-executor`, `project-catalog`, `runner-host`, `runner-client`, `router`, `channel-feishu`, `channel-telegram`, and `apps/bridge`.
+
+## License
+
+[MIT](LICENSE)

package/README.zh-CN.md

@@ -0,0 +1,222 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="apps/web/public/brand/agent-logo-carbon.svg" />
+    <img alt="AGENT · CodeBridge" src="apps/web/public/brand/agent-logo.svg" width="320" />
+  </picture>
+</p>
+
+# CodeBridge（码桥）
+
+一个自托管的多通道 [Agent Client Protocol（ACP）](https://agentclientprotocol.com) 网关。
+
+通过飞书或 Telegram 远程驱动本机 **Cursor、Claude Code、Codex**，代码、Git 凭据、MCP 工具和 Agent session 都留在自己的 Mac/Linux 上。
+
+[English README](README.md)
+
+## 它解决什么问题
+
+你不需要把项目复制到云端，也不需要重新配置本机的 Git、SSH、MCP 和开发环境；在手机聊天里发任务，码桥让本机 Agent 执行并把结果带回聊天。
+
+```text
+飞书 WebSocket ─┐
+                ├─ Bridge ── 带 token 的 HTTP/SSE ── Runner ── ACP Agent ── 本地文件
+Telegram 长轮询 ─┘
+```
+
+| 组件 | 职责 |
+|------|------|
+| **Bridge** | 连接聊天通道、访问策略、斜杠命令、session 路由和消息展示 |
+| **Runner** | 在宿主机启动 ACP session/Agent，访问本地文件和 Git，并处理权限请求 |
+| **ACP adapter** | Cursor、Claude Code、Codex 的协议适配 |
+
+Bridge 与 Runner 分开设计：Bridge 可以放在 Docker 或远程机器，Runner 必须靠近 CLI、代码和凭据所在的宿主机。
+
+## npm 安装
+
+需要 Node.js 22.19 或更高版本。运行 `npm install -g @graychennpm/codebridge@0.1.0` 安装，然后运行 `codebridge init` 完成初始化。在两个终端分别运行 `codebridge-runner` 和 `codebridge start`。安装包包含 Bridge、宿主机 Runner 和 Web 静态资源，无需构建源码。
+
+也可以使用 `npx @graychennpm/codebridge@0.1.0 init`。源码仓库仍支持 `pnpm package:release` 生成本地 tarball，安装、隔离验收和维护步骤见 [npm 交付说明](docs/zh-CN/npm-release.md)。
+
+## 主要能力
+
+- 飞书长连接流式卡片，可配置机器人自定义菜单
+- Telegram Bot API 长轮询，并自动注册原生命令菜单
+- 飞书和 Telegram 原生 @ 通知，可提醒当前发送者或任务中明确 @ 的参与者
+- 统一 ACP 通道：`cursor`、`claude`、`codex`；旧版直接 CLI transport 已移除
+- `/resume`、`/resume last`、`/resume all` 恢复本机会话
+- `/model`、`/effort`、`/permission`、`/config` 实时读取当前 adapter 能力
+- 命名工作区、ACP 附加目录、`/clone`、`/pull`、文件发送
+- `/root add` 感知 macOS TCC 授权，并即时提示“正在等待系统权限”
+- macOS launchd KeepAlive，或手动后台模式 watchdog
+
+## 快速开始
+
+### 环境要求
+
+- macOS 或 Linux
+- Node.js ≥ 22.5、pnpm、curl。WorkItem Event Store 使用 Node 内置的 `node:sqlite`。
+- 本机至少安装一个 CLI：`cursor-agent`、`claude` 或 `codex`
+- 一个已开启机器人的飞书企业自建应用，或一个 Telegram Bot token
+
+### 安装与启动
+
+```bash
+git clone https://github.com/Chenkeliang/CodeBridge.git
+cd CodeBridge
+
+# 安装依赖、构建、生成配置、检查本机 CLI
+./scripts/start.sh setup
+
+# 如果引导时没有启动服务，再手动启动
+./scripts/start.sh start
+```
+
+引导配置保存在 `~/.codebridge/config.yaml`。初始化向导（也可单独运行 `codebridge init`）会当场校验飞书 / Telegram 凭据、生成 Runner token、选择项目目录和默认 Agent；密钥存入系统钥匙串，配置文件里只写 `keychain:` 引用。已有设置和注释保留，只修改向导中确认的项目；YAML 排版可能调整。Telegram 必须有用户或聊天白名单，自动识别用户时需私聊机器人发送一次性验证码。
+
+`codebridge init --defaults` 或无终端运行时，仅新建不存在的配置；随机 Runner token 以明文写入权限 `600` 的文件（已有 `RUNNER_TOKEN` 环境变量时保存引用），不访问钥匙串、不校验通道凭据。之后可运行 `codebridge secrets migrate` 迁入钥匙串。
+
+检查状态：
+
+```bash
+./scripts/start.sh status
+./scripts/start.sh doctor
+```
+
+macOS 开机自启推荐使用 launchd。手动后台模式和 launchd 二选一，不要混用：
+
+```bash
+./scripts/start.sh install-launchd all
+./scripts/start.sh restart
+```
+
+从旧名称 `feishu-code-bridge` 升级时，执行 `restart` 或 `install-launchd` 会把默认数据目录从 `~/.feishu-code-bridge` 迁移到 `~/.codebridge`，并替换旧 launchd 任务；已存在于 `~/.codebridge` 的文件不会被覆盖，显式设置的 `DATA_DIR` 也不会被移动。如果以前安装过 `Feishu Code Runner.app`，请执行 `./scripts/start.sh install-macos-runner` 并重新授权受保护目录；macOS 不会把 TCC 权限迁移到新的 Bundle ID。
+
+常用生命周期命令：
+
+```bash
+./scripts/start.sh status
+./scripts/start.sh restart
+./scripts/start.sh stop
+./scripts/start.sh fg       # 前台调试 Bridge
+```
+
+### 配置通道
+
+飞书需要创建企业自建应用、开启机器人，并按[飞书应用配置指南](docs/zh-CN/feishu-app-setup.md)订阅长连接事件。
+
+Telegram 可与飞书同时启用，也可以只配置 Telegram：
+
+```yaml
+telegram:
+  botToken: "123456:replace-with-bot-token"
+  allowedUsers: ["123456789"]          # 可选白名单
+  allowedChats: ["-1001234567890"]     # 可选白名单
+  pollingTimeoutSec: 25
+```
+
+完整配置见 [examples/config.full.yaml](examples/config.full.yaml)。
+
+### Web Workbench
+
+Bridge 启动后可在本机打开 `http://127.0.0.1:19790/workbench/`。它和飞书、Telegram 共用 WorkItem、Run 和事件流：像普通 Agent 工作台一样直接输入目标，输入框周边的 Agent、模式和工作空间用于配置当前会话，任务由选定 Agent 处理。页面只绑定本地 Bridge，不把代码或凭据上传到云端。
+
+## 手机优先的命令
+
+`/menu` 和 `/help` 默认只返回短菜单，适合手机；发送 `/help full` 查看分组完整帮助。
+
+| 命令 | 用途 |
+|------|------|
+| `/status` | 查看 backend、目录、模型、权限和任务状态 |
+| `/resume last` | 继续当前目录最近一次本机会话 |
+| `/new` | 新建 ACP session |
+| `/stop` | 停止当前任务，并清空飞书排队消息 |
+| `/backend claude` | 在 Cursor、Claude、Codex 之间切换 |
+| `/model` | 拉取实时模型；`/model <名称>` 切换 |
+| `/permission` | 拉取实时权限模式；`/permission <模式>` 切换 |
+| `/ws list` | 查看已保存工作区 |
+
+其他常用命令：
+
+```text
+/resume [N|last|all]
+/effort [list|级别|default]
+/config [id value|default]
+/root add|remove|rm /absolute/path
+/send /absolute/path/to/file
+/clone <git-url> [目录名]
+/pull
+/approve  /deny  /steer <指令>
+```
+
+模型、effort、permission 和 boolean config 的准确选项以当前 ACP adapter 为准；可用 `/model list`、`/effort list`、`/permission list`、`/config` 查看。
+
+需要真实通知时，可以在任务里说“完成后 @ 我”，或者直接 @ 需要通知的参与者。Agent 会在确有必要时调用内部的 `fcb mention`；普通回复不会额外提醒。
+
+## Session、目录与权限
+
+- session 绑定按聊天、话题、backend 和工作目录隔离，元数据持久化在数据目录。
+- `/cd` 切换项目；`/ws save|use` 给常用目录起短名称。
+- `/root add /absolute/path` 添加 ACP `additionalDirectories`。macOS 上 Runner 会先实际访问目录，触发正常 TCC 弹窗；聊天会即时提示正在等待系统授权，但不会静默获得系统权限。
+- `runnerHost.acpPermissionPolicy`：
+
+  | 策略 | 行为 |
+  |------|------|
+  | `auto_allow` | 自动批准 ACP 权限请求（默认，适合可信本机） |
+  | `prompt_feishu` | 在聊天等待 `/approve` 或 `/deny`，超时自动拒绝 |
+  | `prompt_deny` | 自动拒绝权限请求 |
+
+- macOS 可执行 `./scripts/start.sh install-macos-runner` 安装固定身份 helper。默认 ad-hoc 签名免费且只适合本机；TCC 仍需用户确认。
+
+安全边界详见 [SECURITY.md](SECURITY.md)。
+
+## 并发与限制
+
+- 不同聊天可并行运行，默认上限为 `runnerHost.maxConcurrentRuns: 4`。
+- 飞书同一 `chatId + topic` 同时只有一个任务；后续消息最多排队 5 条，`/stop` 会取消任务并清空队列。
+- 同一个群共享 backend、目录、模型和 session 绑定；要并行处理不同项目，请使用不同聊天。
+- Agent 只能通知本轮发送者和本轮任务中明确 @ 的参与者；不会扫描组织通讯录、@ 所有人，也不能自行构造任意用户 ID。
+- `/transport` 仅保留兼容回复，实际只支持 ACP。
+
+## ACP 后端
+
+| Backend | ACP 启动命令 |
+|---------|--------------|
+| Cursor | `cursor-agent acp` |
+| Claude Code | `npx -y @agentclientprotocol/claude-agent-acp@0.78.0` |
+| Codex | `npx -y @agentclientprotocol/codex-acp@1.12.0` |
+
+续聊语义取决于 adapter：Claude/Codex 使用 `session/resume`，Cursor 使用 `session/load`。
+
+```bash
+node scripts/acp-probe.mjs
+node scripts/acp-probe.mjs --backend codex
+RUNNER_TOKEN=... node scripts/test-acp-live.mjs --backend cursor
+```
+
+## 文档
+
+| 主题 | 文档 |
+|------|------|
+| 飞书应用与权限 | [docs/zh-CN/feishu-app-setup.md](docs/zh-CN/feishu-app-setup.md) |
+| 飞书机器人自定义菜单 | [docs/zh-CN/feishu-bot-menu.md](docs/zh-CN/feishu-bot-menu.md) |
+| 手动 / Docker 快速开始 | [docs/zh-CN/quickstart.md](docs/zh-CN/quickstart.md) |
+| Model、Effort、Permission | [docs/zh-CN/model-effort.md](docs/zh-CN/model-effort.md) |
+| Docker Bridge + 宿主机 Runner | [docs/zh-CN/deploy/docker-host-runner.md](docs/zh-CN/deploy/docker-host-runner.md) |
+| 多项目 Agent 工作台设计基线 | [docs/orchestration/README.md](docs/orchestration/README.md) |
+| 完整配置 | [examples/config.full.yaml](examples/config.full.yaml) |
+| 安全策略 | [SECURITY.md](SECURITY.md) |
+
+## 开发
+
+```bash
+pnpm install
+pnpm run lint
+pnpm run build
+pnpm test
+```
+
+这是一个 pnpm monorepo，包含 `core`、`backends`、`work-items`、`policy`、`run-executor`、`project-catalog`、`runner-host`、`runner-client`、`router`、`channel-feishu`、`channel-telegram` 和 `apps/bridge`。
+
+## License
+
+[MIT](LICENSE)

package/apps/web/public/brand/agent-logo-carbon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 2440 700" role="img" aria-label="AGENT"><g transform="translate(0 75)"><path fill="#FF683D" d="M0 0h550v550H0z"/><path fill="#211610" d="M68.75 68.75h412.5v412.5H68.75z"/><path fill="#FF683D" d="M275 137.5h68.75v68.75H275zM275 206.25h137.5v68.75H275zM275 275h137.5v68.75H275zM275 343.75h68.75v68.75H275z"/></g><g fill="#F1F2EA"><path transform="translate(690 550) scale(1 -1)" d="M50 300V0H100V150H250V0H300V300H250V200H100V300ZM150 400V350H200V400ZM100 350V300H150V350ZM200 350V300H250V350Z"/><path transform="translate(1040 550) scale(1 -1)" d="M50 350V50H100V350ZM100 50V0H250V50ZM250 150V50H300V200H200V150ZM100 400V350H250V400ZM250 350V300H300V350Z"/><path transform="translate(1390 550) scale(1 -1)" d="M50 400V0H300V50H100V200H250V250H100V350H300V400Z"/><path transform="translate(1740 550) scale(1 -1)" d="M50 400V0H100V250H150V300H100V400ZM250 150V0H300V400H250V200H200V150ZM200 200V250H150V200Z"/><path transform="translate(2090 550) scale(1 -1)" d="M50 400V350H150V0H200V350H300V400Z"/></g></svg>

package/apps/web/public/brand/agent-logo.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 2440 700" role="img" aria-label="AGENT"><g transform="translate(0 75)"><path fill="#CCFF00" d="M0 0h550v550H0z"/><path fill="#171A11" d="M68.75 68.75h412.5v412.5H68.75z"/><path fill="#CCFF00" d="M275 137.5h68.75v68.75H275zM275 206.25h137.5v68.75H275zM275 275h137.5v68.75H275zM275 343.75h68.75v68.75H275z"/></g><g fill="#171A11"><path transform="translate(690 550) scale(1 -1)" d="M50 300V0H100V150H250V0H300V300H250V200H100V300ZM150 400V350H200V400ZM100 350V300H150V350ZM200 350V300H250V350Z"/><path transform="translate(1040 550) scale(1 -1)" d="M50 350V50H100V350ZM100 50V0H250V50ZM250 150V50H300V200H200V150ZM100 400V350H250V400ZM250 350V300H300V350Z"/><path transform="translate(1390 550) scale(1 -1)" d="M50 400V0H300V50H100V200H250V250H100V350H300V400Z"/><path transform="translate(1740 550) scale(1 -1)" d="M50 400V0H100V250H150V300H100V400ZM250 150V0H300V400H250V200H200V150ZM200 200V250H150V200Z"/><path transform="translate(2090 550) scale(1 -1)" d="M50 400V350H150V0H200V350H300V400Z"/></g></svg>

package/docs/zh-CN/npm-release.md

@@ -0,0 +1,77 @@
+# npm 安装与发布
+
+发行版本为 `@graychennpm/codebridge@0.1.0`，可从 npm 安装，也可使用本地 tarball。macOS 是本阶段支持的宿主机；不新增 Linux 服务管理。
+
+## 安装
+
+需要 Node.js 22.19 或更高版本，无需源码、TypeScript 或 pnpm：
+
+```bash
+npm install -g @graychennpm/codebridge@0.1.0
+codebridge --version
+codebridge-runner --version
+codebridge init
+```
+
+也可以使用 `npm install -g /absolute/path/graychennpm-codebridge-0.1.0.tgz` 安装已下载的 tarball。
+
+完成向导后，在两个终端分别执行：
+
+```bash
+codebridge-runner
+```
+
+```bash
+codebridge start
+```
+
+检查连接：`codebridge doctor`。需要 Web 工作台时，设置配置中的 `web.enabled: true`，然后访问启动日志中的 `/workbench/` 地址。Agent CLI 的安装、登录和模型提供方认证仍需按各工具要求完成；安装此 npm 包不会替你创建外部账号或发送消息。
+
+`codebridge init --defaults` 只生成权限 `600` 的默认配置和随机 Runner token，不校验通道；非交互初始化行为与源码安装一致。首次交互向导优先存入系统钥匙串。npm 安装不包含源码仓库的 `scripts/start.sh` 或宿主机部署器，因此源码安装的后台管理和受控部署流程保持独立；此安装方式提供前台 CLI 运行方式。
+
+## 构建与安装验收
+
+在源码仓库运行：
+
+```bash
+pnpm install --frozen-lockfile
+pnpm version:check
+pnpm package:release
+pnpm test:package
+```
+
+输出位于 `dist/graychennpm-codebridge-0.1.0.tgz`。`package:release` 先完整构建，再调用 npm 原生 `pack`。脚本仅暂存内部包的编译输出和 Web 静态资源，去掉测试、源码映射、开发脚本及开发依赖；不复制用户配置、凭据、源代码或工具目录。
+
+17 个内部包通过 `bundleDependencies` 随 tarball 分发，不需要单独发布 `@codebridge/*`。第三方依赖同时声明在发行包顶层，并固定为源码工作区本次安装实际解析到的版本；发现同一依赖在工作区有不同解析版本时拒绝打包，要求先核对 lockfile。第三方依赖的安装仍需要 npm 网络访问，tarball 并非完整离线安装包。
+
+`test:package` 在临时目录安装 tarball，使用临时 HOME / DATA_DIR 和本地空闲端口：检查两个 bin 的版本和帮助、初始化权限与幂等、内部模块导入、Runner 鉴权与健康版本、Workbench 页面和 JavaScript 静态资源。测试不连接真实机器人，不提交 Agent 任务，最后只关闭自己创建的进程并删除临时目录。
+
+## 版本与变更记录
+
+根 `package.json` 是版本源；内部 workspace 包通过同步脚本保持一致。运行时 `VERSION` 从 core 包自己的 `package.json` 读取，CLI 和 Runner `/health` 不再各自维护版本字符串。
+
+```bash
+npm version patch --no-git-tag-version
+pnpm version:check
+```
+
+`npm version` 的 version 生命周期调用同步脚本，更新所有 workspace 元数据，不自动创建提交或 tag。若手动改根版本，运行 `pnpm version:sync`。同步后更新 `CHANGELOG.md`，重新构建并跑全部检查。
+
+## 公开发布门槛
+
+1. 审查最终 diff，完成 build、lint、全量测试和 `test:package`。
+2. 核实 npm 包名及账号权限。正式包名为 `@graychennpm/codebridge`；npm 拒绝无前缀名称 `codebridge`，因为它与已有包 `homebridge` 太相似。若以后改名，需先修改根包名并重新打包验收。
+3. 取得对具体包名、版本及外部发布动作的授权。发布凭据由发布者保管，本地构建无需读取 token。
+4. 发布者运行下列命令。仅对已验收的 tarball 发布，源码仓库仍保留 `private: true`，防止误把整个仓库上传。
+
+```bash
+npm publish /absolute/path/graychennpm-codebridge-0.1.0.tgz --access public
+```
+
+Git tag、GitHub Release、推送和本机线上部署是独立动作，不能因为本地打包通过就视为已完成或已授权。每次发布后都应核对 registry 版本和 tarball 完整性，再更新 README 的安装版本。
+
+## 验收状态
+
+见 `docs/plans/2026-10-10-npm-delivery.md` 的 Surface Matrix 与本次交付记录。安装包验收覆盖本地安装与隔离启动；真实通道、真实 Agent 任务、全局安装及后台常驻部署均未在本次测试中操作。
+
+依据：[npm bundleDependencies](https://docs.npmjs.com/cli/v11/configuring-npm/package-json/#bundledependencies)。

package/node_modules/@codebridge/agent-registry/dist/index.d.ts

@@ -0,0 +1,32 @@
+import type { AgentProfile, AgentSetupState } from "@codebridge/session-catalog";
+export type AgentAdapter = {
+    agentId: string;
+    kind: AgentProfile["adapter"];
+    health(): Promise<AgentSetupState["runtime"]> | AgentSetupState["runtime"];
+};
+export interface AgentHealthRecord {
+    agentId: string;
+    status: AgentProfile["status"];
+    checkedAt: string | null;
+    error: string | null;
+}
+export interface AgentRegistryOptions {
+    databasePath?: string;
+}
+export declare class AgentRegistry {
+    private readonly profiles;
+    private readonly database;
+    constructor(options?: AgentRegistryOptions);
+    register(profile: AgentProfile): AgentProfile;
+    refresh(adapter: AgentAdapter): Promise<AgentProfile | undefined>;
+    updateSetup(agentId: string, setup: Omit<AgentSetupState, "canSelectDefault" | "canCreateSession">): AgentProfile | undefined;
+    getHealth(agentId: string): AgentHealthRecord | undefined;
+    startHealthChecks(adapters: AgentAdapter[], intervalMs?: number): () => void;
+    get(agentId: string): AgentProfile | undefined;
+    list(): AgentProfile[];
+    close(): void;
+    private persistHealth;
+}
+export { cloneSetupManifest, cloneSetupState, getSupportedAgentSetupManifest, projectAgentStatus, projectSetupState, supportedAgentSetupManifestMap, supportedAgentSetupManifests, } from "./setup.js";
+export type { AgentDiagnostic, AgentInstallStrategy, AgentSetupConfiguration, AgentSetupInstallation, AgentSetupManifest, AgentSetupRuntime, AgentSetupStage, AgentSetupState, } from "@codebridge/session-catalog";
+//# sourceMappingURL=index.d.ts.map