用户手册 v2.7.1

1. 安装

agent-center 是单个二进制 agent-center，以不同模式运行（center server、worker 守护进程、MCP host、agent-supervisor）。安装通过随发行包一起分发的 ./install 脚本完成：一条命令装 center，一条命令装 worker。

默认端口

安装 center（发行包方式）

cd agent-center-v2.7.x-<os>-<arch>/
./install center
# v2.7 默认前台：install center 只落地二进制 + 配置，不注册后台服务。
# 它会打印出运行命令：
agent-center server --config=<prefix>/etc/config.yaml    # 日志输出到 stdout
# 然后打开 http://127.0.0.1:7100 —— 首次设置会在浏览器里铸出 bootstrap admin token。

• 默认前台运行（v2.7）：install center 不注册后台服务。需要开机自启的托管服务时加 --service（macOS 用 LaunchAgent，Linux 用 systemd）。
• 幂等且支持升级。默认前缀 ~/.agent-center（macOS / Linux 用户模式）或 /opt/agent-center（Linux 系统模式）；用 --prefix=<dir> 覆盖。

install center 常用标志：

安装 worker

推荐从 Web Console 的 Fleet → + Add Worker 获取完整命令（已带 bootstrap URL、一次性 enroll token、固定指纹、唯一 --worker-id）：

./install worker \
  --bootstrap=tcp://HOST:7300 \
  --server-fingerprint=sha256:... \
  --worker-id=worker-f3c04c1d \
  --worker-name='test-1' \
  --token=acat_xxxxxxxxx

• 默认前台运行；加 --service 注册托管 LaunchAgent / systemd 单元。
• v2.7.1：install worker 会把所有接入字段写入 <prefix>/etc/config.yaml（权限 0600），随后打印的启动命令简化为 agent-center worker run --config=<prefix>/etc/config.yaml，命令行上不再带任何密钥。
• --worker-id 必填（无主机名默认值）；当 --bootstrap 为 tcp:// 时 --server-fingerprint 必填。
• 同机多 worker：每个落在 <prefix>/workers/<worker-id>/ 下；用 --service 时每个得到标签 com.agent-center.worker.<worker-id>。

从源码安装（引导脚本 install.sh）

仓库根目录的 install.sh 是一个薄引导器：克隆 / 拉取一份托管源码到 ~/.agent-center/src/agent-center，解析 ref，构建后交给同样的 ./install center|worker 路径。

# 交互式向导：
curl -fsSL https://raw.githubusercontent.com/oopslink/agent-center/main/install.sh | bash

# 固定 tag 安装 center：
curl -fsSL https://raw.githubusercontent.com/oopslink/agent-center/main/install.sh \
  | bash -s -- center --version v2.7.1

# worker（注意：install.sh 用 --center，不是 --bootstrap）：
curl -fsSL https://raw.githubusercontent.com/oopslink/agent-center/main/install.sh \
  | bash -s -- worker \
    --version v2.7.1 \
    --center tcp://HOST:7300 \
    --server-fingerprint sha256:... \
    --token enroll_... \
    --worker-name my-box

# 仅预览，不改动任何东西：
curl -fsSL https://raw.githubusercontent.com/oopslink/agent-center/main/install.sh \
  | bash -s -- center --dry-run

• 模式：center / worker / dev。
• ref 解析：--version 优先；否则 --channel stable|main|dev（stable = 最高 vX.Y.Z tag，main = 不稳定默认）。可选 --expected-commit 做完整性校验。
• worker 模式标志：--center <url>、--server-fingerprint、--token、--worker-name。密钥（--token / --server-fingerprint）只转发、不打印；--dry-run 不改动任何东西。

升级

# center（源码检出方式）：
git pull && make build              # 产出 ./bin/agent-center
./bin/agent-center upgrade center

# worker（指定子树）：
./bin/agent-center upgrade worker --worker-id=worker-f3c04c1d

• 从 release 包升级：直接重跑 ./install center（会检测到已有安装，走同一条原子 symlink 交换路径）。
• upgrade center 若前缀下没有现有安装会拒绝执行；升级过程保留配置。原子交换 current → 新版本，跑健康探针，探针失败自动回滚（5s 超时）；旧版本保留在 <prefix>/versions/<old>/。

智能体认证

• worker 拉起智能体的 CLI（claude）；智能体复用 worker 用户自己的 Claude Code 所用的同一凭据 —— 无需单独 API key。
• 订阅 /login 开箱即用（macOS keychain）；ANTHROPIC_API_KEY 同样可用。
• 智能体以 --setting-sources user,project 和 --strict-mcp-config 运行 claude（只加载它自己的 agent-center MCP）。

从源码构建（开发）

前置：Go 1.22+、Node 20+（含 pnpm）、macOS 或 Linux。

make build                  # 前端（vite）+ 后端（go），产出 ./bin/agent-center
VERSION=v2.7.1 make build   # 指定版本
pnpm --dir web run dev      # SPA 开发服务器 http://localhost:5173，代理 → 127.0.0.1:7100

2. 部署

单机部署

把 center server + worker 守护进程 + Web Console 跑在同一台机器上。当前推荐流程只需两条命令：

./install center                 # 单机默认 --tcp-listen=""，worker 走本地 unix socket
./install worker --worker-id=... --bootstrap=... --token=... --server-fingerprint=...

• 单机只需默认 --tcp-listen=""：worker 通过本地 unix socket 连 center，无需开放 TCP。
• center 安装示例输出：前缀 ~/.agent-center、web 端口 7100、DB 在 ~/.agent-center/var/agent-center.db、bootstrap token 在 ~/.agent-center/var/bootstrap_token、Web Console 在 http://127.0.0.1:7100。

多机部署（TCP + TLS，指纹固定）

架构：center（主机 A）←TCP+TLS→ worker（主机 B），采用 SSH 风格的指纹固定（fingerprint pinning），无 CA、无 mTLS。

1. center 端开放 admin TCP：

# 安装时开放跨机接入端口：
./install center --tcp-listen=0.0.0.0:7300

# 等价的配置键：
# server:
#   admin_tcp_listen: "0.0.0.0:7300"

• TLS 证书 admin-tls.{crt,key,fingerprint} 在首次启动时自动生成。
• 从 <prefix>/var/admin-tls.fingerprint 读取指纹（worker 接入时需要）。
• 从 worker 主机方向放通 TCP 7300。

2. worker 端接入并固定指纹：

./install worker \
  --bootstrap=tcp://host-a.example.com:7300 \
  --server-fingerprint='sha256:HH:HH:...' \
  --worker-id=worker-... \
  --token=acat_... \
  --worker-name='remote-1'

远程 worker 在私有绑定后面时：设置 server.bootstrap_public_url，或安装时 install center --bootstrap-public-url=center.example.com:7300。

卸载

agent-center uninstall center [--prefix=...] [--purge] [--yes] [--dry-run]
agent-center uninstall worker --worker-id=<id> [--prefix=...] [--purge] [--yes]

默认保留 <prefix>/var/（sqlite + master.key + tokens）与 logs/。--purge 清除一切（除非加 --yes，否则会提示确认）。

安装目录结构

~/.agent-center/
├── current → versions/v2.7.1/
├── versions/v2.7.1/{bin/, ...}
├── etc/config.yaml
├── var/{agent-center.db, admin.sock, bootstrap_token, admin-tls.{crt,key,fingerprint}}
├── logs/{stdout.log, stderr.log}
└── workers/<worker-id>/{current, var/{worker.db, worker-token}, logs/}

3. CLI 命令参考

v2.7 的 CLI 刻意收窄到 安装 / 升级 / 卸载 / 运行 + 运维命令。数据管理类子命令（task create、issue open、ps、inspect 等）已全部退役 —— 日常工作在 Web Console 里完成。下表以代码 internal/cli/build.go 中的实际注册为准。

退出码：OK 0、BusinessError 1、Usage 2、VersionConflict 16、NotFound 17、InvalidTransition 18、InvariantViolation 19、NotImplemented 64、SIGINT 130。
全局标志：--config / -c（也读 AGENT_CENTER_CONFIG 环境变量），在子命令解析前被剥离。

4. worker run --config

agent-center worker run --config=<prefix>/etc/config.yaml

自 v2.7.1 起，配置文件是接入身份（worker_id / name / bootstrap / token / server_fingerprint）的单一可信来源 —— 安装后打印的启动命令不需要在 CLI 上带任何密钥。守护进程只通过 admin 端点与 center 通信，从不直接打开 SQLite。

标志（每个都是「标志优先、配置兜底」）：

• 友好标志（--bootstrap / --token）与遗留别名（--admin-target / --admin-token）同时设置时，友好标志胜出 —— 因为那是你从 UI 复制来的那条。
• 裸跑 worker run --worker-id=X（不带 --config）会自动发现 ~/.agent-center/workers/<X>/etc/config.yaml。
• 缺少 worker_id 会以 ExitUsage 硬失败。

5. MCP 工具

MCP server 标识：agent-center-mcp-host v0.1.0。智能体的 claude 进程通过它访问 agent-center 的工具集。所有工具均限定在调用方智能体自身的作用域（own-scope）。下表按用途分组（描述取自代码）。

任务 / 议题（Task / Issue）

消息（Messaging）

文件（Files）

发现（Discovery）

输入请求（Input）

6. Web Console 使用

Web Console 嵌在 agent-center server 进程里（同一个二进制，go:embed 的 SPA），用独立端口暴露。

页面 / 路由

UX 约定

• 实体选择 = 下拉 + 搜索过滤，绝不手敲自由文本（禁止 type agent:<id> 这种）。
• 处处显示展示名；身份引用（user:<id> / agent:<id> / T123）藏在 hover / Copy ID 后面。
• DM 渲染对方的名字，而不是 DM 自己的 ID。
• 不做误导性可点项 —— 只展示真正能用的（当前仅 claude-code 真正执行）。
• 不静默失败，状态变化必须可见（toast / pill / 系统消息）；表单校验返回干净的 4xx，而非 5xx。

7. 约定

T<n> / I<n> —— 组织作用域的展示引用

• 任务得到展示引用 T<n>，议题得到 I<n> —— 一个组织作用域的连续序号（org_ref，v2.7.1 #245）。未分配时省略。
• 它们是面向人的身份引用，可出现在 hover / Copy ID 处，但绝不作为主标签（见 UX 约定）。

面包屑（breadcrumb）格式

• 规则：每个详情页都有面包屑 / 页面身份头，指明 (a) 是什么类型的东西、(b) 它在层级里的位置。
• 格式：[Project name] › Tasks › [task title]。对没有天然父级的页面（Fleet / Environment / Settings）退化为单段标签，如 Environment。
• 使用展示名解析 —— 面包屑本身绝不出现原始 ID。

channel / 实体 URL 约定

• channel 以名字寻址：/channels/:name。
• 议题 / 任务 / DM / 智能体以 id 或 name 寻址：/issues/:id、/tasks/:id、/tasks/:id/trace、/dms/:id、/agents/:name。