# AgentHub 多 Agent 协作控制面:把**本地进程、Docker 容器、云端实例**里的各种 Agent 统一纳管起来, 用一条 Gateway 通信,用一套 Playbook 编排协作。nanobot 是第一个被纳管的 Agent,但不是唯一一个 ——DeepSeek Harness、codex / claude / WorkBuddy 这类无头 CLI、OpenClaw、任何 OpenAI 兼容服务都能接进来。 规划文档见 [`docs/PLAN.md`](docs/PLAN.md);跨 Agent 类型的注册与身份规范见 [`docs/AGENT_REGISTRATION.md`](docs/AGENT_REGISTRATION.md)。`soucecode/`(nanobot、agent-town 的参考 clone) 已 .gitignore,不参与构建。 ``` 浏览器 ── ▶ 控制台 (Next.js, :3100) │ REST + WebSocket/SSE(API Key) ▼ AgentHub Hub (FastAPI, :8100) ├ Registry 登记 / 身份 / 能力 / 凭证 ├ Gateway Frame 协议 + 事件总线 + 帧审计 ├ Tasks 单 Agent 任务(流式事件) ├ Collab 团队 / Playbook / Run / 黑板 / 交接 └ Deploy 接入片段渲染 + 签发存档 │ 唯一一条通道:Gateway 的 Frame 协议(JSON 帧 + 流式事件) ┌──────────────┴──────────────┐ ▼ 外拨(push) ▼ 直拨(direct) Agent 自己连 hub hub 拨 Agent 的 HTTP/WS nanobot 渠道 / dsh 插件 / 桥接 nanobot serve / OpenAI 兼容 / OpenClaw ``` **只有 Gateway 一个通信进程**:建档、派活、流式事件、心跳、探测、取消、指令全走同一套 Frame 协议, 两种形态的差别只在「谁发起这条连接」。帧类型: `agent.hello/hub.hello/heartbeat/ping/probe/event/command/describe/deregister/changed`、 `task.run/cancel/changed`、`run.changed`、`hub.event(s)`、`frame.audit`。 Agent 侧走 `WS /api/v1/gateway/ws?agent_token=ag_…`,控制台事件流走 `WS /api/v1/stream`。 | 形态 | `connection_mode` | 谁发起连接 | Agent 侧改动 | 什么时候用 | | --- | --- | --- | --- | --- | | **外拨**(推荐) | `embedded` / `connector` | Agent 进程里的接入件往外拨 WS | 装接入件 + 写一段 config | 能改 Agent 的镜像 / 依赖;NAT 后、只有出网权限的容器和云主机 | | **直拨** | `direct` | hub 直接拨 Agent 的 HTTP/WS | 0 改动 | hub 能直达 Agent。**「接入」向导不提供这一类**,只能手工登记 | `driver_for()` 对 `connection_mode in ("connector", "embedded")` 一律返回 `connector` 驱动: `embedded` 和 `connector` 在 hub 侧是同一条通道,`driver` 只说明背后跑的是什么。 ## 快速开始 ```bash ./scripts/dev.sh # 一键起 hub + 控制台,缺依赖自动补装 ./scripts/dev.sh --seed # 顺便灌一份演示 Agent / 团队 ./scripts/dev.sh --reload # 后端带 --reload HUB_PORT=8200 CONSOLE_PORT=3200 ./scripts/dev.sh ``` 脚本会检查端口占用(被 launchd 托管时说明为什么杀不掉),并把控制台用的 API Key 打在终端上。 Ctrl-C 一起停两个进程。容器版在 `deploy/docker-compose.yml`。 手工两步: ```bash # 1) 后端(Python 3.11+) cd backend && python -m venv .venv && source .venv/bin/activate pip install -e . # 国内可加 -i https://pypi.tuna.tsinghua.edu.cn/simple agenthub init # 建表 + 生成 /hub-credentials.json agenthub serve # http://127.0.0.1:8100 ,API 文档 /docs # 2) 前端(Node 20+,pnpm) cd frontend && pnpm install && pnpm dev # http://127.0.0.1:3100 ``` 控制台右上角「配置 API KEY」粘贴 hub 的 API Key(首次启动写在 `data/hub-credentials.json`),Key 只存浏览器 localStorage。 ## 接入:三步向导 只有两类接入:**插件 / 渠道**(Agent 里本来就有可以装东西的地方)和**桥接**(Agent 只有一套 CLI, 旁边跑一个进程替它拨 hub)。向导就三步,按钮只有**下一步 / 上一步 / 完成**: | 步骤 | 内容 | | --- | --- | | ① 选择类型 | 插件 / 渠道 · 桥接 | | ② 选择 Agent | DeepSeek Harness、nanobot、OpenClaw / codex、claude、WorkBuddy;填「Agent 名字」。只有桥接多问两个:**工作目录** + **权限**(`readonly` / `write`) | | ③ 生成凭证 | **走到这一步就已经签好了**:直接显示 `ag_…` 明文和那段配置原文,各自带 COPY。想换一把点右侧小号「重新签发」;点「完成」回到第 ① 步 | 页面顶部只有一行 `Hub 地址 ` + COPY —— Agent 侧那一格 `server` 就抄它。 名字已在册时不报错拦人:hub 返回 409 时向导自动改成给原来那一行**换一把新凭证**(同一台 Agent 重新接一次就是这个场景)。 签发一次实际发三个请求: ``` POST /api/v1/agents { …建档, issue_credential: true } → ag_… POST /api/v1/agents/{name}/credentials (仅同名 409 时) POST /api/v1/deploy/plan { kinds:[kind], agent_ref, agent, agent_token, record: true } ``` ### 四种片段 `POST /deploy/plan` 返回 `{ agent, hub_url, files:[{kind, filename, content}], next_steps, note }`; `KINDS = ("bridge","nanobot","dsh","claw")`,文件名分别是 `bridge.sh`、`nanobot-config.json`、 `cordis.patch.yml`、`openclaw-agenthub.json`。不管哪一类,Agent 侧要填的都只有两格: **哪个 hub**(`server`)+ **我是谁**(`agent_token`)。没有 hub id、也没有 agent id 可抄—— 凭证就是身份,socket 起来之后 hub 把自己的那份 id 告诉 Agent。 ```yaml # cordis.patch.yml(dsh)——接进 ~/.dsh/profiles//cordis.patch.yml 顶层数组 - insert: - id: dsh-agenthub name: '@nex/dsh-agenthub' config: server: http://127.0.0.1:8100 name: dsh-web displayName: dsh-web agentToken: ag_xxxxxxxx ``` ```jsonc // nanobot-config.json → ~/.nanobot/config.json 的 channels.agenthub { "channels": { "agenthub": { "enabled": true, "server": "http://127.0.0.1:8100", "name": "alpha", "display_name": "alpha", "agent_token": "ag_xxxxxxxx" } } } // openclaw-agenthub.json → OpenClaw 的 agenthub 渠道配置 { "agenthub": { "enabled": true, "server": "http://127.0.0.1:8100", "name": "claw-1", "display_name": "claw-1", "agent_token": "ag_xxxxxxxx" } } ``` ```bash # bridge.sh —— 在有这套 CLI 的机器上跑,它自己往外拨 hub python3 <本仓库>/deploy/cli-bridge/bridge.py --hub http://127.0.0.1:8100 --token ag_xxxxxxxx \ --name codex-1 --cli codex --workdir ~/code/目标仓库 --mode readonly ``` 桥接的工作目录与权限存在这一行的 `config` 里(`_LANDED_KEYS = ("profile","cli","workdir","mode")`), 所以按 `agent_ref` 重新生成片段时能还原出当时贴出去的那条命令。DSH 的 profile 后端仍支持, 但**向导已不再问这一格**:给已在册的 DSH 重生成 `next_steps` 时回落 `web` profile。 ### 签发记录 向导下面的「签发记录」面板是**每次签发的存档本身**,不是连入的 Agent 列表: 一行一次签发,平时只看到「签给谁 + 类型 + 时间」,点开才是当时那把 token(明文)和那段配置原文。 同一 Agent 的旧记录标 `已失效`。 | 项 | 实现 | | --- | --- | | 表 | `credential_issuances`(`id/agent_id/agent_name/kind/hub_url/payload_cipher/active/created_at`) | | 落盘 | `security.seal(secret_key, {agent_token, files})`,读时 unseal;换过 `secret_key` 解不开就给空,不猜内容 | | 读 | `GET /api/v1/deploy/issuances?limit=50`(token 是明文) | | 写 | `POST /deploy/plan` 带 `record: true`,**要求 admin key**(read key → 403)。向导走的就是这条,所以存档和贴出去的片段不可能漂移 | ### 凭证回看与轮换 签过的凭证随时能查回来,不必为看一眼明文而轮换: - 控制台:Agents 详情页的「凭证」面板(状态 / 查看凭证 / 签发或轮换凭证 / 轮换宽限秒数),或接入页的「签发记录」。 - API:`GET /api/v1/agents/{ref}/credentials`(管理员 key;库里为此另存一份 seal 的可读副本 `token_cipher`,认证仍只读哈希)。 - CLI:`agenthub config --name X --kind bridge|nanobot|dsh|claw`(已在册的直接印真值,未建档留 `` 占位)。 签在「可回看」之前的老凭证读不回明文(库里只有哈希),点「重新签发」换一把之后就能反复查看。 命令行等价(绕开向导时用): ```bash agenthub agent add --name codex-1 --connection connector --driver connector --show-token agenthub agent rotate codex-1 # 立即失效;API 侧还能给 grace_seconds ``` ## 接入件 **接入件随 Agent 走**:每种 Agent 一个专门的接入件,hub 不替它们做部署。协议同一套,所以凭证可以互相替换。 ### 内嵌 SDK:把 Gateway 客户端塞进 Agent 进程 `deploy/nanobot-gateway/channel/agenthub/agenthub_client.py` 是那个单文件客户端(标准库 + websockets)。 接自己的 Agent 就 import 它写十几行: ```python import os from agenthub_client import GatewayClient, GatewayConfig async def on_task(task, emit) -> str: # task 里有 prompt / session_key / context async with my_agent.turn(task["prompt"]) as turn: async for chunk in turn: await emit("delta", text=chunk) # status / delta / reasoning / tool / log return turn.answer async def describe() -> dict: # 可选:能力自述,控制台会显示 return {"streaming": True, "runtime": "my-agent"} client = GatewayClient( GatewayConfig( hub_url="http://127.0.0.1:8100", agent_token=os.environ["AGENTHUB_AGENT_TOKEN"], # 密钥只从环境读,不进代码也不进镜像 name="my-agent", deployment_kind="docker", ), on_task, describe=describe, ) await client.run() # 断线重连 + 心跳 + 取消,都在里面 ``` 身份**不落盘**:配置里那一把 `agent_token` 就是它的全部身份,进程重建之后填的还是同一把,`agent_id` 自然不变。 `delta / reasoning / status / tool / completed` 原样回到 hub 的事件流。取消也是真的: 客户端收到 `task.cancel` 调 `runner.cancel()`,事件流以 `cancelled` 收场(DSH 插件走 `agent.cancel`)。 ### nanobot 渠道 `deploy/nanobot-gateway/channel/agenthub/` 是一个 nanobot channel 包。nanobot 只扫 `nanobot.channels.__path__`,没有外部插件目录,所以装一次进安装树: ```bash cp -R deploy/nanobot-gateway/channel/agenthub \ "$(python -c 'import nanobot.channels as p; print(list(p.__path__)[0])')/agenthub" ``` ```jsonc // ~/.nanobot/config.json —— 和 telegram、websocket 同级的普通渠道 { "channels": { "agenthub": { "enabled": true, "server": "http://127.0.0.1:8100", "name": "alpha", "display_name": "阿尔法", "agent_token": "ag_xxxxxxxx" // 只有这一格是凭证 }}} ``` ```bash nanobot gateway --foreground # 渠道拨上 hub 就上线,nanobot 的代码和启动方式都不改 ``` - 字段全在 `channels.agenthub` 下:`enabled/server/name/display_name/description/agent_token/deploymentKind/labels`; 只有 `AGENTHUB_AGENT_TOKEN` 这一把 env 优先级最高(compose 注入用),其余 env 只在没写配置文件时兜底; 旧字段名(`hubUrl` 等)一个版本内仍可读。 - `describe()` 回 `{streaming, model, runtime:"nanobot"}`,模型由 Agent 自省上报,不在渠道配置里配。 - 现成容器:`cd deploy/nanobot-gateway && ./bootstrap.sh` → 写 `.env`(`AGENT_TOKEN_ALPHA` / `AGENT_TOKEN_BETA`、 `DASHSCOPE_API_KEY`、`NANOBOT_MODEL`,模型 key 默认从 `~/.nanobot/config.json` 取)→ build `nanobot:agenthub` → 起 `agenthub-gw-alpha` / `agenthub-gw-beta`(阿尔法 / 贝塔,role writer/editor)。 - 那份 compose **没有任何 ports**,healthcheck 打容器内 `127.0.0.1:18790`(nanobot 自己的健康端点)。 hub 地址用 `HUB_URL` 覆盖(默认 `http://host.docker.internal:8100`;host 网络下写 `127.0.0.1`, 同网络写 `http://hub:8100`),落到渠道的 `AGENTHUB_SERVER`(旧名 `AGENTHUB_HUB_URL` 仍可读), 再加 `AGENTHUB_NAME/DISPLAY_NAME/AGENT_TOKEN/DEPLOYMENT_KIND/DEPLOYMENT_REF/LABELS/DESCRIPTION`。 ### DeepSeek Harness 插件(`plugins/dsh-agenthub`) DSH 是「一切皆插件」的 Harness,所以接入方式是给它写一个插件,而不是让 hub 去理解它内部: 插件与 DSH 同进程,往 hub 拨一条出站 socket。 ``` hub ◀── 出站 WS ── @nex/dsh-agenthub(DSH 插件,Host 半) ├ task.run → ctx.agents.resume/create + agent.followup(createUserMessage) ├ 过程事件 ← agent/assistant-stream + session/event(tool/call, turn/end) ├ task.cancel → agent.cancel({kind:'user'}) └ 设置面板 ← POST /api/agenthub/status(Client 半:身份 / 连接 / 最近任务) ``` ```bash # 装插件必须用 dsh 自己的命令(手改 profile 的 package.json 不算装) dsh plugin --profile web add -w link:/绝对路径/nex_agenthub/plugins/dsh-agenthub # 离线自检:打桩 hub + 伪 Cordis ctx,不需要 DSH 运行时,也不需要真 hub node plugins/dsh-agenthub/selfcheck.mjs ``` 两个真机坑:profile 必须是 **web 模板**建的(默认只有 `dsh-base`,跑一条任务就退出,没有常驻进程去拨 hub); `cordis.patch.yml` 里要**先删掉占位的 `[]`** 再接片段(两个根节点,YAML 直接解析失败)。 web profile 是 `patchReload: live`,改 config 存盘即生效,**改插件代码要重启 `dsh web`**(Node ESM 缓存模块); 热重载会把同一 entry 应用两遍,插件内按进程做了单例。配置项与会话语义见 [`plugins/dsh-agenthub/README.md`](plugins/dsh-agenthub/README.md)。 ### 无头 CLI:桥接(codex / claude / WorkBuddy) 不动 CLI 一行代码,在它所在机器上跑一个桥接进程(`bridge.py` 只需要 Python 3,不装任何依赖; 旁边 `adapters/` 里一个 CLI 一个适配器,新增一家就加一个文件)。 ```bash agenthub agent add --name codex-1 --connection connector --driver connector --show-token python3 deploy/cli-bridge/bridge.py --hub http://127.0.0.1:8100 --token ag_… \ --name codex-1 --cli codex --workdir ~/code/目标仓库 --mode readonly ``` | 能力 | codex | claude | workbuddy | | --- | --- | --- | --- | | 派活 / 事件流 / 续话 / 取消 / describe | ✅ | ✅ | ✅ | | `agent.command`(会话内下达指令) | ✅ `codex queue` | ❌ 明确回 `delivered:false` | ❌ 同左 | 参数:`--hub --token --name --cli --workdir --mode --max-concurrency --verbose --state`, 分别可用 `AGENTHUB_URL`、`AGENTHUB_TOKEN`、`AGENTHUB_AGENT`、`AGENTHUB_CLI`、`AGENTHUB_WORKDIR`、 `AGENTHUB_MODE`、`AGENTHUB_STATE` 兜底;state 默认 `~/.agenthub/cli-bridge-.json`。 细节与两个真机坑(claude/workbuddy 的 `--add-dir` 是变长参数)见 [`deploy/cli-bridge/README.md`](deploy/cli-bridge/README.md)。 派完活想回到那套 CLI 的原生会话里接着看: ```bash ./scripts/attach.sh tsk_8b4337cc… # 本机直接进;跨机器自动走 ssh ./scripts/attach.sh -n tsk_xxx # 只打印命令不执行 HUB_URL=http://10.0.0.5:8100 HUB_KEY=agp_xxx ./scripts/attach.sh tsk_xxx ``` 会话记录存在 Agent 那台机器的磁盘上(`~/.codex/sessions/`、`~/.claude/projects//`…)且按工作目录归档,hub 只有事件流。 ## 直拨(`direct`) hub 拨 Agent,Agent 零改动、零凭证。向导不提供这一类,手工登记: ```bash agenthub agent add --name nanobot-1 --driver nanobot --connection direct \ --base-url http://127.0.0.1:8900/v1 # 需要鉴权就配 auth agenthub agent add --name local-llm --driver openai_compatible --connection direct --base-url … ``` AgentHub 的 `nanobot` driver 按真实实现对齐,并且有一组互测直接跑上游 `create_app()` (`backend/tests/test_interop_nanobot.py`)保证没有跑偏: | nanobot 的约定 | 真实行为 | AgentHub 的处理 | | --- | --- | --- | | 启动 | `nanobot serve --host 0.0.0.0 --port 8900`;绑定非本机地址时 `~/.nanobot/config.json` 必须有 `{"api":{"api_key":"…"}}`,否则拒绝启动 | 接入时填 Bearer Key | | 健康 | `GET /health` → `{"status":"ok"}`,**不鉴权** | probe 与在线状态走它 | | 模型 | `GET /v1/models` 只列它自己配的那一个;请求里的 `model` 不匹配就 400 | driver 先探测并缓存,探不到就不传 `model`;控制台显示的模型一律由 Agent 自省上报(心跳里的 `capabilities.model`) | | 消息 | `messages` 只允许**一条 user 消息**,多条直接 400 | 协作指令和队友上下文折叠进同一条 user 消息,prompt 放最后 | | 会话 | `session_id` 对应服务端会话 `api:` | 任务的 `session_key` 原样传下去,同一轮协作复用 nanobot 自己的记忆 | ```bash curl -X POST http://127.0.0.1:8100/api/v1/tasks -H "X-API-Key: $KEY" -H 'content-type: application/json' \ -d '{"agent_id":"nanobot-1","prompt":"只回一句话:你好","session_key":"demo-1"}' ``` 真实 nanobot 互测(可选;没有 nanobot 环境时整组自动 skip,也可用 `AGENTHUB_NANOBOT_PYTHON=/path/to/python` 指向任何能 `import nanobot` 的解释器):自备一份 nanobot 源码 → `NANOBOT_SKIP_WEBUI_BUILD=1 uv pip install --python .nanobot-venv/bin/python "/tmp/nanobot-build[api]"` → `cd backend && .venv/bin/python -m pytest tests/test_interop_nanobot.py -q`。 ### `nanobot_ws`:走 WebUI 那条 WebSocket `nanobot gateway` 自带一条 WebSocket 渠道(默认 `127.0.0.1:8765`),**官方 WebUI 只是它的一个客户端**: 一条 socket 多会话,派活是一个 `{"type":"message","chat_id":…,"content":…}` 信封,回复按 `delta` / `stream_end` / `reasoning_delta` / `message(kind=tool_hint)` / `file_edit` / `turn_end` 流回来。 `nanobot_ws` driver 复用的就是这条通道,没有第二套协议。 ```bash nanobot gateway # ws://127.0.0.1:8765/ ;要 token 就配 channels.websocket.token curl -X POST http://127.0.0.1:8100/api/v1/agents -H "X-API-Key: $KEY" -H 'content-type: application/json' \ -d '{"name":"nano-ws","driver":"nanobot_ws","agent_type":"nanobot","connection_mode":"direct", "base_url":"http://127.0.0.1:8765","auth":{"token":"wyc-secret"}}' ``` - `base_url` 写成 `http://host:8900/v1` 也认得,默认端口按 8765 推;路径不同给 `config.path`,TLS/反代给 `config.ws_url`。 - **`session_key` 就是 nanobot 会话**:driver 把它换成 `agenthub-` 形态的 `chat_id`(非法字符或超长取哈希), 同一个 key 永远落进同一个 session,「工作台」里连续追问能续上上下文。 - 轮次终点认 `turn_end`(带 usage / outcome),不是「一段时间没消息」;`outcome=failed` 让任务失败并带回 `failure_message`。 - nanobot 的渠道协议**没有中止信封**,所以 `nanobot`(HTTP)和 `nanobot_ws` 的 `cancel()` 老实返回 false: 控制台取消会把任务停在 `cancelled`,但不会假装已打断 Agent 那一轮。外拨接入件才有真取消。 ## Agent 类型与像素小人 `agent_type` 和 `driver`(怎么通信)、`deployment_kind`(跑在哪)是三个正交维度。办公室里的像素小人按它取配色和头饰: | 类型 | 值 | 形象 | 典型 driver | | --- | --- | --- | --- | | nanobot | `nanobot` | 金色工装 + 头顶天线 | `nanobot`(HTTP)、`nanobot_ws`(WebSocket) | | DeepSeek Harness | `deepseek_harness` | 靛蓝工装 + 青色护目镜 | DSH 插件(`connection_mode=embedded`) | | OpenClaw | `openclaw` | 钢蓝工装 + 鸭舌帽 | `openclaw`(gateway 帧 RPC,实验) | | Hermes | `hermes` | 琥珀工装 + 羽翼头环 | 待接入(先占类型与形象) | | 其它 | `custom` | 沿用按 driver 取色的老规则 | `mock` / `openai_compatible` / `connector` | 留空=跟随 driver,换 driver 类型自动跟着变;显式选了钉住不动。`GET /api/v1/agents?agent_type=hermes` 按类型过滤。 老库升级不用手工迁移:启动/`agenthub init` 时自动增量 `ALTER TABLE`。 ## 控制台 `Next 16.1.6 / React 19.2.3 / Tailwind 4` + lucide-react + @tanstack/react-virtual(全在 devDependencies)。 脚本:`dev`(`next dev -p 3100`)/ `build` / `start` / `lint` / `typecheck` / `format` / `format:check`。 | 页面 | 用途 | | --- | --- | | 总览 | Agent/任务状态分布、最近 Run、Presence 判定来源、最后一帧 | | 办公室 | 像素办公室:一 Agent 一工位,屏幕写正在跑的 prompt,走位对应状态,墙上一块看板(左在岗状态、右任务队列),机柜告警闪红灯。**产出只在右边控制台,画面里不重复**;点工位可直接下指令。画布按「显示宽度 × devicePixelRatio」渲染,布局 `lib/office-layout.ts`、配色 `lib/office-palette.ts` | | 工作台 | 通用派活面板:左边全部 Agent(本地/容器/远端一视同仁),右边一条按 `session_key` 延续的对话,reasoning / 工具调用 / 产出同一条 SSE,在跑的能取消 | | Agents | 只管管理:搜索 `name/driver/host`、按状态与接入方式筛选、主动探测、删除登记、逐行详情。**没有登记入口**——建档与签发都在「接入」页 | | Agent 详情 | 凭证(查看 / 签发 / 轮换 + 宽限秒数)、指令 command、probe、describe、这个 Agent 的任务列表 | | 任务 | 单 Agent 任务列表与流式事件(`delta / reasoning / tool / log`) | | 团队 | 成员与角色、Playbook、Run 时间线、共享黑板、Agent 间消息;`/runs/{id}` 是 Run 详情 | | 接入 | 顶部一行 `Hub 地址` + COPY;三步向导;下面「签发记录」 | | 设置 | Hub、Gateway、API 密钥(控制台面)+吊销、Gateway 帧窗口、审计日志、最近帧原始 JSON | 暗 / 亮主题在右上角(默认暗色),记在 `localStorage`,首帧由 `app/layout.tsx` 内联脚本写好 `data-theme`,刷新不闪。 四种 Playbook:`sequential`(A→B→C)、`parallel`(并行后汇总)、`round_robin`(N 轮讨论)、 `handoff`(Agent 输出交接块决定下一步交给谁)。Agent 侧零改造:hub 把 hub 地址、run id、 短期 run grant、「你是这队伍里的哪一个」写进 prompt,Agent 想协作时按提示 curl 一下 `/collab/*` 即可。 交给自己的交接块会被忽略并结束本次 Run,避免原地打转。 ### 控件规格 - **尺寸只有两档**:`md` = 32px(页面/卡片主操作、表单行),`sm` = 26px(工具条、表格行内动作、chip)。 边框 2px、圆角 6px、ArkPixel 字体(11px / 10px)、焦点环 2px 金色;token 在 `app/globals.css` 的 `--ctl-*`。 - **页面只用原语**:`Panel PixelButton LinkButton Dot Badge Input Select Textarea SearchInput Field Tabs Chip Modal Empty ErrorNote CopyButton JsonBlock Spinner KV usePaged/Pager`(都在 `components/ui.tsx`), 没有裸 `