19 · CLI、配置与部署形态¶

paperclipaiOnboard / DoctorContext ProfilesDeployment ModesStorage

一句话结论： paperclipai 既是本地实例 supervisor，又是控制面 API client；配置由共享 schema 约束，部署把身份模式与网络 bind 分离，目标是让本地零配置和 authenticated/private/public 生产形态共享同一控制平面。

1. CLI 的两张脸¶

flowchart TB
  CLI["paperclipai"] --> SETUP["Setup plane\ninstall / onboard / doctor / configure / run"]
  CLI --> CLIENT["Control plane client\ncompany / issue / agent / approval / ..."]
  SETUP --> LOCAL["instance config + DB + service manager"]
  CLIENT --> HTTP["Paperclip REST API"]
  HTTP --> SERVER["Server control plane"]

Setup 命令可以管理本地实例生命周期；控制面命令不直接操作数据库，遵循 Server route/service 的授权和活动日志。

2. `paperclipai run`¶

run 的本地 bootstrap 逻辑大致是：

解析 data-dir/instance/config；
若缺配置，进入 onboard/default；
doctor + optional repair；
启动 server/service manager；
等待 health/listen；
打开浏览器或打印 URL。

--force、--instance、--data-dir 让多实例开发和故障恢复可控，不把所有状态固定在一个全局目录。

3. Onboard 的 Quickstart 与 Advanced¶

Quickstart 默认：

embedded PostgreSQL；
local disk storage；
local encrypted secrets；
loopback/local trusted；
可先不配置 LLM provider。

Advanced setup 让操作者选择数据库、网络、auth、storage、secret、logging、LLM 等配置。

Onboard 是幂等的：已有配置不会被 --yes 静默覆盖。要改变已存在实例，用 configure。

4. Doctor 是可执行诊断¶

Doctor 检查：

config schema 与陌生/疑似拼写错误 key；
DB process/connectivity/migration；
secrets provider/key file；
storage；
LLM/adapter 环境；
ports/allowed hostnames；
service health；
deployment auth safety。

--repair 可修复有限问题，但不应把“无法确认安全”自动改成“通过”。修复操作要保持可预测并输出诊断。

5. Context Profiles¶

CLI control-plane 命令可以从 context profile 读取：

API base；
Company ID；
API key 或 env var 名；
default profile。

paperclipai context set --api-base http://localhost:3100 --company-id <id>
paperclipai context show
paperclipai context use default

Context 文件保存引用/配置，不建议直接存长期 secret；--api-key-env-var-name 让 token 从环境变量读取。

6. Control-plane parity¶

CLI 注册的资源命令覆盖：

company / issue / agent / project / goal
approval / activity / dashboard / cost
routine / pipeline / skill / skills / team
workspace / access / secrets / plugin / adapter

“parity”不是 UI 每个像素都要有 CLI，而是关键业务 mutation 走同一 API 与授权语义，避免命令行成为隐式 admin bypass。

7. Heartbeat CLI¶

paperclipai heartbeat run \
  --agent-id <agent-id> \
  --source on_demand \
  --trigger manual \
  --debug

它调用控制面 wake/run API 并流式展示 adapter event；不直接复制 Server 的 Heartbeat service。这样 CLI 手动运行也能进入 durable request/run、预算、权限和 activity。

8. 配置分层¶

CLI flags
  > environment variables
  > instance config file
  > schema defaults
  > derived paths/hosts
  > cross-field validation

主要 config group：

database + backup；
server/deployment/bind；
auth/public URL；
storage local/S3；
secrets provider/strict/key；
logging/telemetry；
LLM/adapter；
heartbeat scheduler。

passthrough 的 config schema 会保留扩展 key，同时生成陌生 key warning，兼顾插件扩展与 typo 发现。

9. 三种部署形态¶

形态	人类认证	网络	适用
`local_trusted`	本地 Board implicit	loopback/private	单人本地开发
`authenticated + private`	Better Auth	LAN/Tailscale/VPN	私有团队网络
`authenticated + public`	Better Auth	公网/反向代理	Cloud/互联网

deploymentMode 和 exposure 分离：authenticated private/public 共享身份系统，但 host trust、public URL 和 doctor 规则不同。

10. Board Claim Flow¶

从 local trusted 迁移到 authenticated 时，启动可能打印一次性 board claim URL：

已登录用户打开 claim；
晋升为 instance admin；
降级自动 local board admin；
补齐 Company membership；
使旧 local actor 不再拥有默认控制权。

这是身份迁移协议，不是普通邀请链接。

11. Bind 与 Hostname Guard¶

Bind 可为 loopback、lan、tailnet、custom。Private hostname guard 对 authenticated/private 校验允许 host；public deployment 要求 explicit public URL 并检查 proxy/hostname。

网络可达性不等于 auth：即使 bind 到 LAN，仍需 session/API key；即使 loopback，也不应给任意本机进程无限工具/secret。

12. 数据目录与存储¶

默认 instance root 下分开保存：

config.json
db/                         # embedded Postgres data
logs/
data/storage/               # local assets
secrets/master.key
backups/
hot-restart-intent/report

--data-dir 为测试、worktree 和多实例提供隔离。Storage provider 可切到 S3，但 secrets key、DB backup 和外部 provider 仍需独立管理。

13. Docker 与生产部署¶

Docker 负责打包 Server/UI/CLI runtime；数据库可以是容器内 embedded 或 external PostgreSQL。生产通常：

reverse proxy / TLS
        ↓
Paperclip authenticated server
        ↓
external Postgres + durable object storage
        ↓
adapter/sandbox/provider runtimes

公开部署还要考虑：

explicit base URL；
signup policy；
secure cookies/proxy headers；
secret provider；
DB/storage backup；
worker/runtime host 的网络与 filesystem；
WebSocket upgrade 代理支持。

14. Service Manager 与持久化主机假设¶

CLI 可安装 background service，服务管理器负责重启/日志/instance id。Paperclip 的 plugin worker、local adapter、runtime service、embedded Postgres 和 WebSocket 都偏向长驻主机。

把 Server 放到纯 serverless 环境时，至少要重新设计：

heartbeat queue ownership；
local process execution；
worker/plugin lifecycle；
WebSocket；
hot restart；
workspace/local filesystem。

15. Secrets 部署选择¶

本地 encrypted provider 依赖 master key file；authenticated/private/public 更适合外部 vault/provider 和 strict mode。部署 config 只保存 provider/ref，Agent run 通过 projection 获取短期值。

CLI secrets doctor、provider config discovery 和 inline-env migration 用于发现遗留明文/不可用 vault。

16. 可复用经验¶

Setup CLI 与控制面 CLI 共享一个命令，但职责和信任边界分开。
配置 schema 既校验运行值，也校验跨字段安全组合。
本地 quickstart 与生产 authenticated mode 共享业务服务，不要维护两套 API。
网络 bind 与身份认证正交设计。
一次性 claim flow 用于从隐式本地管理员迁移到明确人类身份。
--data-dir 和 instance ID 是隔离测试/运维的基础能力。
评估部署可行性时，把持久进程、WebSocket、workspace 和 plugin worker 一起考虑。

源码入口¶

cli/src/index.ts
cli/src/commands/onboard.ts、run.ts、doctor.ts、configure.ts
cli/src/client/context.ts、http.ts
cli/src/config/
packages/shared/src/config-schema.ts
server/src/config.ts
docs/cli/、docs/deploy/
Dockerfile、scripts/docker-entrypoint.sh

运行系统最难的是失败收敛：20 · 可靠性、恢复与可观测性。