智能体认证与工作队列 v2.15.0

§ 1 Agent 身份（一等公民）

agent-center 将 agent 视为一等公民身份（first-class identity）。每个 AgentInstance 拥有独立的持久身份、配置和状态机，而不仅仅是一个"类型枚举"。

身份标识

系统中存在两类 identity 前缀：

user-xxx — 人类用户身份
agent-xxx — Agent 身份（AgentInstance）

每个 AgentInstance 有全局唯一的 name（如 supervisor、coder-1）和 ULID 主键 id。

AgentInstance 状态机

状态	含义	跃迁
`idle`	就绪，无活跃执行	→ `active`（有 execution 开始） → `sleeping`（所属 worker offline） → `archived`（用户软删）
`active`	有 ≥1 个活跃 execution	→ `idle`（最后一个 execution 结束） → `sleeping`（所属 worker offline）
`sleeping`	所属 worker 离线，非终态	→ `idle`（worker 重连）
`archived`	终态，不可逆	—

状态跟 Worker 联动：worker offline 时该 worker 上所有 idle/active agent 自动 → sleeping；worker online 时 sleeping agent 自动 → idle。

Built-in AgentInstance

系统默认有一个 built-in agent：supervisor（is_builtin=true）。它运行在 center 进程上（worker_id=NULL），不允许 archive。用户可通过 Web Console 配置其 MCP config 和 instructions，但不能删除。

AgentInstance 数据模型

字段	类型	说明
`id`	ULID	主键
`name`	string	全局唯一，用户起名 / built-in 由系统保留
`agent_cli`	enum	Agent CLI 类型：`claude-code`、`codex`、`opencode` 等
`worker_id`	FK	所属 worker（built-in 为 NULL）；创建后不可变
`config`	JSON	包含 instructions_ref、mcp_config、skills 等
`max_concurrent`	int?	并发上限；null = 不另设上限，受 Worker 层兜底
`state`	enum	`idle` \| `active` \| `sleeping` \| `archived`
`is_builtin`	bool	系统 provisioned（如 supervisor）；archive 拒绝
`version`	int	乐观锁

§ 2 Bootstrap 与注册

Bootstrap Token 流程

Worker 接入 center 采用 bootstrap token 机制（一次性令牌）：

管理员在 center 侧签发 bootstrap token（admin token create 或 Web Console）
将 token 传递给 worker 机器
Worker 机器执行 agent-center worker enroll <token>
Center 校验 token 有效性 → 兑换为长期 session token → Worker 入库
Session token 落盘到 ~/.agent-center/credentials（mode 0600）

Bootstrap Token 状态机

状态	含义
`active`	已签发，待兑换
`used`	已成功兑换为 session token（不可 reissue）
`expired`	TTL 到期（默认 30 分钟）
`revoked`	管理员手动撤销

DB 中只存 value_hash，明文 token 仅在签发时返回一次。Reissue 时旧 active token 同事务标 revoked + 新 token 入库。

Admin Token 作用域

Admin bearer token 用于 CLI 与 center admin endpoint 的认证。Token 解析优先级：

AGENT_CENTER_ADMIN_TOKEN 环境变量
~/.agent-center/admin_token 文件
<sqlite_dir>/bootstrap_token 文件（单机部署 fallback）

管理命令：admin token create、admin token list、admin token revoke。

§ 3 工作队列（Work Queue）

AgentWorkItem 生命周期

任务通过 AgentWorkItem 分配给 agent 执行。工作项的生命周期：

状态	含义	跃迁
`queued`	已入队，等待 agent 认领	→ `active`（agent 认领）
`active`	agent 正在执行	→ `done`（执行完成）
`done`	终态，执行已完成	—

任务分配机制

Supervisor（built-in agent）负责决定将 task 分配给哪个 agent。分配时需通过校验链：

Agent 状态 — agent_instance.state 必须为 idle 或 active
能力匹配 — agent_instance.agent_cli 必须在 worker 的 capabilities[detected & enabled] 中
并发上限 — 当前活跃 execution 数 < min(worker.concurrency.per_agent_type, agent_instance.max_concurrent ?? Infinity)

全部校验通过后，创建新的 execution + work item 下发给 worker daemon。

Claim from Pool

Worker daemon 收到 work item 后，在本地 agent pool 中找到对应的 AgentInstance，spawn shim 进程执行。同一 agent 可并行处理多个 execution（受 max_concurrent 限制），各 execution 拥有独立的 worktree（临时沙箱）和 trace。

§ 4 MCP 工具注入

Per-agent MCP 配置

每个 AgentInstance 可配置专属的 MCP server 列表，存储在 config.mcp_config 字段中（JSON，遵循 MCP 标准 schema）。

配置文件

Agent 的 home directory 下有两个 MCP 相关文件：

文件	说明
`mcp_config.json`	用户配置的 MCP schema + SecretRef（无明文 secret）
`mcp_config.runtime.json`	Worker daemon 在派单时 just-in-time 生成（含已解析的明文 secret，mode 0600）；execution 结束后 unlink

Secret 解析

MCP 配置中的 secret 使用 SecretRef 引用（指向 SecretManagement BC 管理的加密 secret），不存明文。Worker daemon 在 execution 启动前解析 SecretRef → 从 center 拉取明文 → 写入 mcp_config.runtime.json → 注入给 agent 进程 → execution 结束后立即删除运行时文件。

MCP Host 进程

worker mcp-host 是 daemon 内部 spawn 的 per-agent stdio MCP server 进程，为 agent 提供工具调用通道。Agent 通过此通道访问 center 提供的所有 MCP 工具（任务管理、消息发送、文件操作等）。

§ 5 Skill 文件挂载

Per-agent Skill 目录

每个 AgentInstance 的 home directory 下有 skills/ 子目录，用于存放用户自配的 skill 文件（遵循 Anthropic Skills 标准）：

~/.agent-center-worker/agents/<agent_instance_id>/
   skills/
     <skill-name>/SKILL.md

Built-in supervisor 同样支持 skill 文件：

~/.agent-center/agents/supervisor/
   skills/
     <skill-name>/SKILL.md

加载机制

Worker daemon 在 prompt-assembly 阶段将 home_dir/skills/ 下的 SKILL.md 文件内容叠加进 agent 的 prompt 层次。Skill 文件在 execution 期间对 agent 进程只读，更新只能在 between-execution 窗口进行。

Home Directory 完整结构

路径	说明	读写
`instructions.md`	Agent-level system prompt 片段	Execution 期间只读
`mcp_config.json`	MCP 配置（含 SecretRef，无明文）	Execution 期间只读
`mcp_config.runtime.json`	运行时 MCP 配置（含明文 secret，mode 0600）	Daemon just-in-time 生成 / execution 后 unlink
`skills/`	用户自配 skill 文件	Execution 期间只读
`notes/`	用户随意使用	Execution 期间只读

Worker AgentInstance 的 home directory 位于 ~/.agent-center-worker/agents/<id>/；built-in supervisor 位于 ~/.agent-center/agents/supervisor/（用 name 而非 id 保证路径稳定可读）。