stackbone-cli

Stackbone CLI 技能

本技能将告诉你如何使用 stackbone CLI：操作顺序、每条命令都遵循的约定，以及需要运行的循环。这里不包含标志表：每个标志、输出格式和退出代码都在文档中，每条命令对应一个页面。

文档所在位置

文档通过 MCP 由 stackbone-docs 服务提供（https://docs.stackbone.ai/mcp，公开，工具为 search_docs、get_doc、list_docs）。stackbone docs 会打印连接详情。

• 通过 list_docs（区域为 cli）开始会话。 它会返回该章节下的所有 CLI 页面，并附上一行说明。下文的如何查找页面会说明任务需要哪个页面；从列表中获取其路径，然后用 get_doc 获取。切勿凭记忆输入路径：页面会移动，标题不会变。
• 运行带有本次会话中尚未确认的标志的命令前，先阅读对应页面。
• 不知道哪个命令能完成某项操作时，用通俗语言提出问题，并将 area: "cli" 传给 search_docs。
• stackbone <command> --help 是已安装版本的本地准确信息。如果文档与二进制文件不一致，以二进制文件为准。

会话中没有 stackbone-docs 工具？ 获取 https://docs.stackbone.ai/llms.txt：这是相同的索引，每个页面占一行，包含标题、说明和原始 Markdown 链接。按标题找到页面并获取该链接。https://docs.stackbone.ai/llms-full.txt 包含所有页面，合并在一个文件中（约 700 KB）。

如何调用 CLI

• 二进制文件为 stackbone（无需安装时使用 pnpm dlx @stackbone/cli <command>，也可以全局安装 pnpm add -g @stackbone/cli）。如果 stackbone --help 执行失败，则说明 CLI 未安装。
• 作为调用方时，每次调用都传入 --json：标准输出会有一行 { "schema_version": 1, … }，或者标准错误会有 { "error": { "code", "message", "suggestion" } }。
• 对任何有破坏性的动词都传入 --yes（retry、cancel、remove、rollback、approve、reject）。不传时，该动词会在发出任何网络请求前以退出代码 5 退出。
• --json、--yes 和 CI=1 都会关闭提示交互。 原本会要求输入值、选择选项或确认的命令会直接报错，而不会一直等待，因此请将所有必需值作为标志传入。
• 根据退出代码分支处理： 0 表示成功，1 表示通用错误，2 表示未通过身份验证（stackbone login），3 表示没有项目或 stackbone dev 未运行，4 表示未找到或没有已注册的部署，5 表示权限被拒绝。封装中的 error.code 信息更具体（dev_not_running、runtime_not_configured 等）。
• 命令失败时，使用 --json 重新运行并读取 error.suggestion：它会给出下一条建议尝试的命令。然后可将 STACKBONE_LOG_LEVEL=debug 设为 CLI 自身的标准错误日志级别；若 dev 启动阶段卡住，再使用 --verbose。

会话开始

先运行以下命令，再进行其他操作，并根据退出代码采取相应措施：

stackbone whoami --json     # exit 2 → stackbone login (device flow; --no-browser when headless)
stackbone metadata --json   # auth + linked project + agents in one payload; exit 3 → init or link

工作循环

新建工作区。 stackbone login → stackbone init <dir> [--with agent|workflow|workflow-agent] [--name <ws>] → cd <dir> → stackbone dev。init 会将工作区关联到组织，并写入 .stackbone/project.json，因此需要已登录的会话。它会为你安装工作区依赖，所以不要自行添加安装步骤；需要跳过安装或从中恢复时，请阅读该命令的页面。在 TTY 中，它会询问要设置哪些编码 Agent（技能 + 文档 MCP 服务）；非交互运行时不会设置任何 Agent，除非传入 --agents claude-code,cursor,…。

扩展工作区。 stackbone add agent <name> / add workflow <name> [--calls <agent>] / add workflow-agent <name>。离线运行，无需登录，只写入新文件，绝不修改现有 TypeScript；如果名称冲突则会失败，除非使用 --force。必须在工作区内运行（否则退出码为 3）。然后使用 stackbone 技能编写代码。

开发循环。 stackbone dev 会启动 Postgres + Redis + MinIO，编译工作区并通过 http://127.0.0.1:4242 提供服务，支持热重载，还会打开隧道，让云端 Studio 可以访问它。在全新机器上首次运行时，会暂停，直到配置好模型提供方（会打印一个 Studio 链接；也可以在启动前导出 MODEL_PROVIDER_BASE_URL + MODEL_PROVIDER_API_KEY）。然后：

stackbone workflows list --json
stackbone workflows start <name> --input '{"…"}' --json   # validates against the declared schema → { runId }
stackbone runs get <runId> --json
stackbone logs tail --run <runId> --json                   # the per-step frames; --follow for a live run

通过 Studio 的 Playground 与 Agent 聊天，或向 POST http://127.0.0.1:4242/openai/v1/chat/completions 发送请求，并设置 "model": "<agent-name>" 和任意非空 bearer（Getting started（CLI › Guides））。

更改架构。 编辑 src/schema.ts → stackbone db migrate create <name> → 阅读 .stackbone/migrations/ 下生成的 SQL → stackbone db migrate up → stackbone db migrate status。绝不要编辑已应用的迁移；应创建一个新的迁移。迁移文件中不要使用 BEGIN / COMMIT。

运维安装实例。 不带 --agent 的动词会针对本地开发安装实例，并且需要正在运行的 stackbone dev（否则为 dev_not_running，退出码为 3）。stackbone agents list --json 会列出安装实例 ID；每次调用时传入 --agent <id>，即可针对已部署的安装实例。审批：stackbone hitl list --status pending --json → stackbone hitl approve|reject <id> --yes --json。

发布。 没有发布命令。stackbone package 会写入一个部署目录（编译后的工作区 + Dockerfile + compose + .env + README），供他人运行 docker compose up -d；stackbone build 只会写入供你自行构建镜像的 bundle。然后注册正在运行的实例：stackbone link --agent <slug> --installation <id> --url <public-url> --secret <hmac-secret> --tag <image-tag>（tag 就是版本；每次部署都要重新运行 link）。一个实例只响应一个安装实例，因此 --installation 必须是该 Agent 在 stackbone agents list --json 中对应的 cloud 行的 ID；link 不会创建安装实例，所以要先安装 Agent。首次运行 link 前，请阅读 link（CLI › Reference）：其中说明了密钥的来源。

发布后，交由三个技能接手。 如果没人为实例接线，它就无法访问任何内容，也无法测量任何指标；以下技能各自涵盖 CLI 无法触及的一个侧边栏分组：stackbone-integrations 用于连接提供方、启用触发器以便 Agent 自动接收内容，并将它写出的内容发送到某处；stackbone-guardrails 用于限制正在运行的 Agent——阻止一轮对话、屏蔽数据，或将其暂存以供人工处理；stackbone-evals 可将手动 Playground 测试转为可在 CI 中运行的套件。

CI / 无头模式。 登录仅支持设备流（没有 token 环境变量）：在可使用浏览器的地方运行一次 stackbone login，然后将 ~/.stackbone/credentials.json（chmod 600）带入 CI。之后，所有命令都使用 --json，破坏性动词使用 --yes；如果需要设置编码 Agent，则在 init / link 时使用 --agents <list>。

适用于所有情况的规则

• 切勿提交 .stackbone/（init 会将其加入 gitignore）。在不含此目录的克隆中运行 stackbone dev，它会询问此项目使用哪个 Agent，然后写入该文件。link 无法完成这项工作：它需要一个已部署的 box（--installation --url --secret --tag），而且没有项目文件记录 installation id 时，它会拒绝操作。
• 分页列表使用 --limit + --cursor，并返回 items + nextCursor；将 nextCursor 传回即可继续翻页。logs tail 则会进行流式传输。
• 永远不会打印密钥：secrets list 会隐藏值，而且没有用于显示密钥的命令。不要尝试通过 CLI 读取密钥。
• db query 只接受单条只读 SELECT；架构变更应通过 db migrate create 进行。RAG 架构由平台预先配置；切勿手动迁移。
• init 不接受 --starter / --template；传入其中任何一个都会以非零状态退出，并显示迁移消息。单项模板由 add 使用（stackbone add workflow <name> --template <t>）。
• 你可能会在旧资料中看到已弃用的命令：publish、openrouter、connectors。这些命令已不存在；请改用 build / package + link、Gateway（Home › Features）以及 Studio 的集成页面。
• 交互式提示用于保护输入 ! stackbone … 的用户。作为调用方时，默认使用 --json --yes。

如何查找页面

• 某个命令的标志、动词、输出格式或退出码：查看 CLI › Reference 下以命令名称命名的页面（login / logout 共用“登录和退出”；whoami / current / list / organization use / metadata 共用“帐户和组织”）。
• 每条命令都遵循的规则（动词如何选择目标、JSON 信封格式、分页、--yes 门控、退出码）：查看“命令约定”；全局标志、环境变量和磁盘状态请查看“配置参考”（两者均位于 CLI › Reference 下）。
• dev 启动中止，或某个命令拒绝指定目标：查看 CLI › Guides 下的“故障排除”（或 stackbone-debug skill）。
• 其他内容（HTTP 线路协议、发布、手动设置编码 Agent）：使用 search_docs，以普通措辞提出问题并选择 cli 区域；部署和设置页面则选择 home 区域。

其他 skills

• stackbone：工作区内的代码（defineDeepAgent、'use workflow'、环境中的 stackbone 客户端）。
• stackbone-debug：查找错误、失败或卡住的运行、搁置的审批的原因。
• stackbone-coder：通过访谈，从一句话的想法开始创建新组件。