CapOwn — 用户指南¶

配置¶

所有 CapOwn 组件使用统一的 TOML 格式。单个 TOML 文件既可以作为部署注册配置（传给 deploy.py install worker <source> 或 deploy.py install client <source>），也可以作为组件启动时读取的运行时配置，无需格式转换步骤。Worker 和 Client 的 config 命令也可以获取临时注册 URL，并将返回的 TOML 保存到本地运行时配置中。

每个配置文件以 role 键开头（"master"、"worker" 或 "client"）。公共键——token、URL、节点标识——位于顶层。组件专用设置位于以角色命名的配置段下（[master]、[worker]、[client]）。仅部署使用的设置（镜像、工作空间预设）位于 [deploy] 下，运行时会被静默忽略。

解析器是一个最小化的内置 TOML 子集——任何组件（包括 Client）都不需要第三方依赖。

加载顺序：

环境变量 > 配置文件 > 默认值

统一格式参考¶

顶层键	环境变量覆盖	使用方	说明
`role`	—	全部	`"master"`、`"worker"` 或 `"client"`
`enrollment_token`	`ENROLLMENT_TOKEN`	Master、Worker	用于基于 Ed25519 的 Worker 注册的一次性 token
`client_token`	`CLIENT_TOKEN`	Master、Client	用于 Client/Agent 认证的 token
`master_url`	`MASTER_URL`	Worker、Client	Master API 基础 URL
`worker_name`	`WORKER_NAME`	Worker	此 Worker 的唯一标识符

Master (`master/config.toml`)¶

role = "master"

[master]
host = "0.0.0.0"
port = 9210
heartbeat_timeout = 60
db_path = "/app/data/registry.db"

部署后，用户 token 和注册凭据在 Master 主机上通过 capown-master 命令管理—— 参见多用户模型章节。

`[master]` 键	环境变量覆盖	默认值	说明
`host`	`MASTER_HOST`	`0.0.0.0`	绑定地址
`port`	`MASTER_PORT`	`9210`	监听端口
`heartbeat_timeout`	`HEARTBEAT_TIMEOUT`	`60`	标记节点离线前的等待秒数
`db_path`	`MASTER_DB`	`/app/data/registry.db`	SQLite 数据库路径（容器侧）

Master 容器在运行时读取 /etc/capown/master.toml。Compose 文件将宿主机配置目录 ~/.capown/master/ 挂载到容器内。

Worker (`worker/config.toml`)¶

role = "worker"
master_url = "https://<master-domain>:9210"
worker_name = "<unique-worker-name>"
enrollment_token = "cown_enroll_xxx"

[worker]
execution_mode = "container"
container_name = "capown-worker-exec"
workspace = "/workspace"
max_runtime = 86400
idle_timeout = 600
max_output_size = 200000
max_input_size = 200000
reconnect_interval = 5
store_command_history = true
command_preview_size = 300
max_command_history_size = 65536

`[worker]` 键	环境变量覆盖	默认值	说明
`execution_mode`	`EXECUTION_MODE`	`container`	任务执行后端：`"host"` 或 `"container"`
`workspace`	`WORKSPACE_DIR`	`/workspace`	工作空间路径（容器模式：`/workspace`；宿主机模式：`~/.capown/workspace`）
`container_name`	`CONTAINER_NAME`	`capown-worker-exec`	执行容器名称
`max_runtime`	`MAX_RUNTIME`	`86400`	任务最大挂钟时间（秒）
`idle_timeout`	`IDLE_TIMEOUT`	`600`	无输出时终止任务的等待秒数
`max_output_size`	`MAX_OUTPUT_SIZE`	`200000`	结果输出最大字节数，超出则截断
`max_input_size`	`MAX_INPUT_SIZE`	`200000`	接受的输入内容最大字节数
`reconnect_interval`	`RECONNECT_INTERVAL`	`5`	重连尝试间隔（秒）
`store_command_history`	`STORE_COMMAND_HISTORY`	`true`	启用 Shell 命令历史存储
`command_preview_size`	`COMMAND_PREVIEW_SIZE`	`300`	任务摘要中命令预览的最大 UTF-8 字节数
`max_command_history_size`	`MAX_COMMAND_HISTORY_SIZE`	`65536`	存储的完整命令文本的最大 UTF-8 字节数

配置文件位置（按优先级顺序查找）：

$CAPOWN_CONFIG 或 $CAPOWN_WORKER_CONFIG 环境变量
~/.capown/worker/config.toml
/etc/capown/worker.toml
worker/config.toml（开发模式回退）

Worker 控制进程始终作为原生 OS 服务在宿主机上运行，与执行模式无关。在使用容器执行后端时，部署脚本还会额外创建一个托管的 Docker 执行容器。Worker 守护进程内部使用 docker exec 在该容器中运行任务。在宿主机执行后端模式下，任务直接在宿主机上运行。

部署脚本会在 ~/.capown/worker/app 下安装一个稳定的应用副本，并通过 uv 管理的虚拟环境在 ~/.capown/worker/venv 中使用 Python 3.12 运行。

Client (`client/config.toml`)¶

role = "client"
master_url = "https://<your-domain>/v1"
client_token = "<your-client-token>"

[client]
soft_timeout = 30

`[client]` 键	环境变量覆盖	默认值	说明
`soft_timeout`	`CLIENT_SOFT_TIMEOUT`	`30`	同步任务软超时时间（秒）

Client 故意不设置默认 Worker。请先运行 capown workers，然后在所有 Worker 操作中传入 <worker>。

Client 配置发现顺序：

$CAPOWN_CLIENT_CONFIG 环境变量
client/config.toml（脚本所在目录）
./client/config.toml（当前工作目录）
~/.config/capown/client.toml
~/.capown/client/config.ini（旧版 INI 回退）

Client 解析器是一个最小化的内置 TOML 实现——不需要 tomllib 或 tomli 依赖。旧版 config.ini 文件仍被接受以保持向后兼容。

配置驱动部署¶

curl 四步安装路径见快速开始。

CapOwn 支持通过配置文件进行非交互式部署。由于运行时格式和部署格式相同，Master 操作员可以生成一个 TOML 配置文件或一个临时注册 URL，交给目标机器操作员后直接使用，无需任何格式转换。

生成注册凭据¶

注册凭据在 Master 安装后在其主机上生成。首次安装 Master 时，部署脚本会自动创建 starter 用户 chiral 和一个 bundle enrollment token。生成的安装命令会显示在部署输出中。

最简单的手动流程使用已配置的 public_url，并在用户尚不存在时自动创建：

# 快速默认 bundle enrollment（使用已配置的 public_url）
capown-master tokens create alice

如果尚未设置 public URL，或需要显式覆盖：

capown-master tokens create alice --type bundle --master-url https://master.example.com

默认的 tokens create <username> 相当于 tokens create <username> --type bundle，在不传 --master-url 时使用 Master 配置中的 public_url。

tokens create --type bundle 会输出可直接运行的安装命令：

Worker: python3 deploy.py install worker https://master.example.com/api/enroll/cown_tmp_xxxxx
Client: python3 deploy.py install client https://master.example.com/api/enroll/cown_tmp_xxxxx
Files: ~/.capown/master/enrollments/alice

当软件已安装时，同一个临时 URL 也可被 capown-worker config 和 capown config 使用；CLI 会向 Master 报告其角色并接收匹配的 TOML。无需 --role 标志。

默认情况下，tokens create --type bundle 还会将 Worker 和 Client TOML 文件写入 ~/.capown/master/enrollments/<username>/ 目录下，用于基于文件的部署工作流。使用 --url-only 可跳过文件生成。

有用的 bundle 选项：

capown-master tokens create alice --type bundle --master-url https://master.example.com --ttl 86400
capown-master tokens create alice --type bundle --master-url https://master.example.com --client-uses 1 --worker-uses 3
capown-master tokens create alice --type bundle --master-url https://master.example.com --max-uses 2
capown-master tokens list alice --type enrollment
capown-master tokens revoke <token-id>

请将临时 URL 和生成的 TOML 文件视为机密信息，因为它们包含或授予持有者凭据。

完整的用户管理工作流参见多用户模型章节。

从配置源部署¶

deploy.py install 命令接受一个统一的 <source> 参数，可以是本地 TOML 文件、 TOML URL 或 bundle enrollment URL：

# 从 bundle enrollment URL 一键部署（推荐）
python3 deploy.py install worker https://master.example.com/api/enroll/cown_tmp_xxxxx
python3 deploy.py install client https://master.example.com/api/enroll/cown_tmp_xxxxx

# 从本地 TOML 文件部署
python3 deploy.py install worker capown-worker.toml
python3 deploy.py install worker capown-worker.toml --mirror-cn   # 中国镜像

# 从 TOML URL 部署
python3 deploy.py install worker https://master.example.com/enrollments/alice-worker.toml

如果 CapOwn 已安装，只需要重新配置身份信息，可使用 config 子命令的两步流程：

# 已安装——仅重新配置身份
capown-worker config https://master.example.com/api/enroll/cown_tmp_xxxxx
capown config https://master.example.com/api/enroll/cown_tmp_xxxxx

# 或从本地 TOML 文件
capown-worker config capown-worker.toml
capown config capown-client.toml

同一个 bundle URL 可用于两种角色；CLI 会向 Master 报告其角色并接收匹配的 TOML。无需 --role 标志。

当 install 配合配置源使用时，部署是全自动的：

从配置中读取 role 字段——无角色选择提示。
使用配置文件中的镜像、--mirror-cn 标志，或默认使用国际镜像——无镜像提示。
解析本地默认值（例如 workspace_preset = "user_home" 解析为 $HOME/.capown/workspace）。
显示参数审查面板，然后直接执行，无需确认。
自动停止任何正在运行的服务——无停止/重启提示。

重新运行不带配置源的 install 命令会更新软件并保留现有本地配置。运行 deploy.py install worker <source> 或 deploy.py install client <source> 会显式应用该配置源并替换本地身份信息。使用 capown-worker config <source> 或 capown config <source> 当软件已安装且只需要替换身份信息时。仅当需要移除配置和数据时使用 deploy.py uninstall <component> --purge。

Agent 接口¶

CapOwn 支持两种面向 Agent 的接口，共享相同的 Master 和 Worker 控制平面：

MCP Streamable HTTP 端点 /mcp，适用于支持 MCP 的 Agent 宿主。它使用现有 Client bearer token，暴露 Worker、Shell、文件、系统和任务工具。
capown CLI 配合 Agent skill，适用于不支持 MCP 的宿主、脚本编写，以及在受限网络下更倾向于短 HTTPS 请求和仅用标准库 Client 的场景。

两种接口强制执行相同的用户所有权和 Worker 工作空间规则。MCP 配置请参见 MCP 指南，CLI 工作流请参见 skills/capown-client/SKILL.md。

CLI 使用¶

capown CLI 是推荐的接口。它由 deploy.py 安装到 ~/.capown/bin/，也可通过 python -m client.cli 直接运行。

结构化结果使用 JSON。原始命令和文件输出保持原始格式。CapOwn 层错误使用 error[code]: message 格式。

# 列出已注册的 Worker
capown workers

# 运行 Shell 命令（同步，等待结果）
capown run worker-1 "uname -a"

# 读取文件
capown read worker-1 /etc/hostname

# 写入文件（从标准输入读取内容）
printf '%s' "hello world" | capown write worker-1 /workspace/hello.txt --stdin

# 写入文件（从本地文件读取内容）
capown write worker-1 /workspace/hello.txt --file local.txt

# 编辑文件（从本地文件读取新旧文本）
capown edit worker-1 /workspace/file.txt --old-file old.txt --new-file new.txt

# 编辑文件（通过标准输入传入 JSON 格式的新旧文本）
printf '{"old": "foo", "new": "bar"}' | capown edit worker-1 /workspace/file.txt --json-stdin

# 列出目录内容
capown ls worker-1 /tmp

# 列出目录内容并限制数量
capown ls worker-1 /tmp --limit 20

# 按 Glob 模式查找文件
capown find worker-1 "*.log"
capown find worker-1 "**/*.py"

# 搜索文件内容（可选 --regex）
capown search worker-1 "TODO"
capown search worker-1 "error_\w+" --regex

# 获取系统信息
capown info worker-1

# 派发长时间运行的命令（异步，返回 task_id）
capown dispatch worker-1 "sleep 30 && echo done"

# 按 task_id 检查任务状态（Worker 本地 ID）
capown task <worker> <task_id>

# 等待任务完成
capown wait worker-1 <task_id>

# 获取已完成 Shell 任务的完整命令文本
capown task-command worker-1 <task_id>

# 列出最近的 Shell 命令预览（默认：最近 10 个 Shell 任务）
capown history worker-1
capown history worker-1 --limit 20
capown history worker-1 --all-statuses --preview-bytes 500

# 取消正在运行的任务
capown cancel worker-1 <task_id>

# 列出所有 Worker 上的待处理/运行中任务
capown pending
capown pending --worker worker-1

基于脚本的调用方式 python client/capown_client.py 仍可用于向后兼容，但新部署推荐使用 capown 命令。

直接 API 使用¶

任务也可以通过 curl 直接派发：

# 通过 Nginx 代理（外部客户端）：
curl -X POST https://<master-domain>/v1/api/tasks/dispatch \
  -H "Authorization: Bearer <client-token>" \
  -H "Content-Type: application/json" \
  -d '{"target_worker": "worker-1", "payload": {"task_type": "shell", "params": {"command": "uname -a"}}}'

# 或直接访问 Master 端口（本地）：
curl -X POST http://127.0.0.1:9210/api/tasks/dispatch \
  -H "Authorization: Bearer <client-token>" \
  -H "Content-Type: application/json" \
  -d '{"target_worker": "worker-1", "payload": {"task_type": "shell", "params": {"command": "uname -a"}}}'

所有 Master HTTP 端点及其请求/响应格式、认证方式和错误码的完整列表，请参见 Master API 参考。

Worker 标识¶

每个 Worker 安装有两个身份：

身份	范围	说明
`worker_name`	面向用户，可重命名	在 `capown` 命令中用于寻址 Worker 的名称
`worker_id`	内部使用，稳定不变	格式 `wrk_` 后跟 12 个十六进制字符，每次安装生成一次

worker_name 规则： - 仅限 ASCII 小写字母 - 3 到 48 个字符 - 必须以小写字母或数字开头和结尾 - 可包含小写字母、数字、点号（.）、连字符（-）、下划线（_） - 不得以 wrk_ 开头（保留给 worker_id） - 不得为保留字（master、admin、all、none 等） - 每个所属用户下必须唯一

注册配置中不包含 worker_id。Worker 在守护进程注册/登记期间获取其身份，然后将 worker_id 存储在 ~/.capown/worker/identity.toml 中，使其在重新部署后仍然保持不变。当 Worker 的 worker_name 被更改时，Master 通过 worker_id 识别出这是同一个 Worker，并更新注册表条目，而不是创建一个重复的离线节点。

capown workers 列表始终显示当前的 worker_name。worker_id 在 API 响应中可见，用于诊断目的。

请勿手动编辑 identity.toml 文件。删除它会导致生成新的 worker_id，使 Worker 在 Master 看来像是一个新节点。

Worker 重命名流程¶

Worker 可以在部署后重命名。重命名会保留 worker_id 并记录之前的名称以供审计。

# 从 Worker 主机执行（验证名称并更新 Master + 本地文件）：
capown-worker rename <new-worker-name>

# 从 Master 主机执行（直接数据库访问）：
capown-master workers rename <worker_id> <new-worker-name>

重命名要求： - 新名称必须遵循 worker_name 验证规则 - 该名称不能被同一用户所拥有的其他 Worker 使用 - 重命名不会导致任务中断——用于内部路由的 worker_id 保持稳定

重启时元数据刷新¶

当 Worker 守护进程重启时，它会在重新认证后自动向 Master 报告当前的运行时元数据。这包括：

主机名：机器的网络名称（platform.node()）
操作系统：例如 linux、windows、darwin
执行模式：container 或 host
启用的能力：Worker 支持的任务类型集合
工作空间路径：文件操作发生的目录

无需 CLI 操作——元数据作为守护进程启动序列的一部分自动刷新。如果重连调用暂时失败， Worker 会在下一个连接周期重试。

Worker 本地管理¶

capown-worker 命令用于本地管理 Worker 服务。它在部署时由 deploy.py 安装到 ~/.capown/bin/。

状态与诊断¶

capown-worker status         # 显示 Worker 状态、身份和路径
capown-worker doctor         # 运行轻量级健康检查

status 显示 Worker 服务状态、已配置的身份、执行模式、工作空间路径以及容器状态（容器模式下）。

工作空间管理¶

capown-worker workspace show                      # 显示当前工作空间
capown-worker workspace set /srv/new-project       # 更改工作空间（需确认）
capown-worker workspace set /srv/new-project --yes # 更改工作空间（非交互式）

workspace set 验证路径是否为绝对路径且已作为目录存在，显示当前和新设置，请求确认（除非指定 --yes），更新配置文件，并自动重启 Worker 服务。

在容器模式下，workspace set 更新宿主机侧的挂载路径，并以新的 -v host:container 挂载重新创建执行容器，使工作空间更改立即生效。容器侧的工作空间路径（/workspace）保持不变。

服务生命周期¶

capown-worker start     # 验证配置后启动服务
capown-worker stop      # 停止服务
capown-worker restart   # 验证配置后重启服务
capown-worker logs [-f] # 查看服务日志

start 和 restart 会在更改运行中服务之前验证 Worker 配置。如果配置无效或缺失，操作会被中止并显示可操作错误信息。stop 故意不验证配置，以便在配置文件损坏时仍能停止本地 Worker。

验证检查包括：有效的 execution_mode（host/container）、绝对路径的 workspace、容器模式下 Docker 是否可用，以及执行容器是否就绪。身份警告会被打印但不会阻止生命周期操作。

在容器模式下，执行容器会被重新创建（docker rm -f + docker run）而不是简单重启，因此当你运行 capown-worker restart 时，挂载路径或其他容器定义更改会生效。

配置¶

capown-worker config                            # 显示配置位置和脱敏 token
capown-worker config <source>                    # 从配置源注册或重新配置

Master 管理 CLI¶

capown-master 命令用于从宿主机管理 Master 服务。它在部署时由 deploy.py 安装到 ~/.capown/bin/，随 Master 部署一同完成。

# 显示容器状态和已配置的路径
capown-master status

# 启动 / 停止 / 重启 Master 服务
capown-master start
capown-master stop
capown-master restart

# 查看容器日志（加 -f 跟踪；加 --tail <n> 查看最后 N 行）
capown-master logs
capown-master logs -f
capown-master logs --tail 50

# 检查 Master 健康端点
capown-master health

# 显示配置和数据位置
capown-master config

# 设置 Master 公共 URL（默认 bundle enrollment 需要）
capown-master config set public-url https://master.example.com

# 显示版本信息
capown-master version

# --- 多用户管理 ---

# 明确创建用户（当需要在发放 token 前管理用户时使用）。
# 否则，tokens create <username> 会自动创建不存在的用户。
capown-master users add alice
capown-master users add bob

# 按稳定 uid 重命名用户
capown-master users rename <uid> alice-new

# 为用户设置密码（可选，用于未来仪表板登录）
capown-master users set-password <uid>

# 创建后更改用户角色
capown-master users set-role <uid> admin

# 列出和查看用户
capown-master users list
capown-master users show alice

# 禁用 / 重新启用用户
capown-master users disable alice
capown-master users enable alice

# 默认 bundle enrollment（使用已配置的 public_url）
capown-master tokens create alice

# 带有显式 URL 覆盖
capown-master tokens create alice --type bundle --master-url https://master.example.com

# 列出和吊销 token
capown-master tokens list alice
capown-master tokens revoke <token-id>

# 仅 Worker 或仅 Client 注册
capown-master tokens create alice --type worker --master-url https://master.example.com
capown-master tokens create alice --type client --master-url https://master.example.com

# Admin token（仅当前 API，遗留功能；已被未来仪表板认证取代）
capown-master tokens create alice --type admin

capown-master tokens list alice --type enrollment
capown-master tokens show <token-id>
capown-master tokens revoke <token-id>

capown-master 命令与 Master Docker 容器通信，需要在宿主机上安装 Docker。

用户管理和注册命令直接访问宿主机上的 Master SQLite 数据库，不需要 Docker 容器正在运行。

多用户模型¶

Master 支持多用户，每个用户拥有独立的 token 和节点所有权。这使得单个 Master 实例可以服务于一个受信任的小型团队，每个成员有自己的 Worker。

概念¶

用户：Master 上的命名账户。每个用户有自己的 Client 和 Worker token。
Token：绑定到特定用户的持有者凭据。Token 以 SHA-256 哈希形式存储——明文值仅在创建时显示一次。
所有权：当 Worker 使用某个用户的 Worker token 注册时，该 Worker 归该用户所有。用户的 Client token 只能向其拥有的 Worker 派发任务。

工作流¶

Master 操作员在安装时通过 deploy.py install master --public-url <url> 或之后通过 capown-master config set public-url <url> 设置 Master 公共 URL。
首次安装时，deploy.py 会自动创建 starter 用户 chiral 和一个 bundle enrollment token。要创建更多用户：capown-master tokens create <username>。不存在的用户会自动创建。
Worker 和 Client 安装命令会打印出来。将临时 URL 或生成的文件安全地分发给每个用户。
每个用户安装其 Worker/Client，并运行 capown-worker config <source> 或 capown config <source>，或使用 deploy.py install worker <source> 或 deploy.py install client <source> 配合注册配置源。
Worker 使用其每用户 Worker token 注册，并绑定到该用户。
Client 使用其每用户 Client token 派发任务，且只能操作自己的 Worker。

注册 URL 与文件¶

capown-master tokens create --type bundle 生成一个短期有效的 URL，并且默认还会在 ~/.capown/master/enrollments/<username>/ 下生成本地 TOML 文件。每个用户只允许一个活跃的 bundle URL——生成新的 bundle 会自动吊销该用户之前的活跃 bundle URL。请将两种形式均视为机密：

通过安全渠道传输。
使用 capown-master tokens revoke <token-id> 吊销不再使用的临时 URL。
分发后从 Master 宿主机删除生成的 TOML 文件（如果不再需要）。
不要将其提交到版本控制系统。

临时 bundle URL 由 capown-worker config <source> 和 capown config <source> 消费。生成的 TOML 文件与 deploy.py install worker <source> 或 deploy.py install client <source> 兼容。

数据保留¶

任务状态查询通过 dispatch_sync 转发到目标 Worker。Master 不持久化任务历史——它只路由任务和跟踪节点存活状态。使用 capown task <worker> <task_id> 从 Worker 查询状态。

Shell 命令历史仅存储在 Worker 上，保存在内存中（TTL 86400 秒，最多 1000 条记录）。 Master 不持久化命令历史。使用 capown history <worker> 列出最近的 Shell 命令预览，或 capown task-command <worker> <task_id> 获取特定任务的完整 Shell 命令文本。命令历史可通过 store_command_history 配置选项按 Worker 单独禁用。

结构化错误码¶

任务结果包含机器可读的错误码（worker_offline、auth_denied、schema_invalid 等）。权威列表定义在 shared/protocol.py 中。任务成功时 error_code 字段为 null/空。当输出因大小限制被截断时，truncated 布尔标志为 true。

能力词汇表¶

Worker 将其能力表示为紧凑的字符串（例如 shell.run、file.read、task.status）。能力到任务类型的权威映射定义在 shared/protocol.py 中。

能力显示在 capown workers 列表中，Agent 使用它们为任务选择合适的 Worker。