stackbone-debug

Stackbone 调试技能

本技能介绍如何定位 Stackbone 工作区中的故障原因。它不包含错误目录：每个代码、状态和消息的含义都在文档中，拿到代码后可从文档中查阅。

信息所在位置

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

• 使用 list_docs 开始会话。 它会返回其区域和分区下的所有页面。下方的如何找到对应页面说明了代码或症状对应哪个页面；从列表中找到页面路径，然后用 get_doc 获取该页面。切勿凭记忆输入路径：页面会移动，标题不会变。
• 拿到错误代码后，阅读对应页面：其中的错误部分会说明代码的含义以及接下来要检查的内容。
• 拿到没有代码的消息后，先用原样消息调用 search_docs 搜索，再用简单词语描述症状进行搜索。
• 不要凭记忆解释代码。代码是稳定的，但其成因和后续命令会随版本变化。

会话中没有 stackbone-docs 工具？ 获取 https://docs.stackbone.ai/llms.txt：其中包含相同的索引，每个页面占一行，列出标题、描述和原始 Markdown 链接。按标题选择页面并获取该链接。https://docs.stackbone.ai/llms-full.txt 是包含所有页面的单个文件（约 700 KB）。

如何使用本技能

1. 逐字记录症状：错误消息、HTTP 状态、运行 ID、准确命令。绝不要转述。
2. 获取代码。 使用 --json 重新运行 CLI 命令，并读取 error.code + error.suggestion；读取 SDK 调用中的 result.error.code；读取 HTTP 响应的状态和正文；读取运行的日志帧。
3. 按原样运行下方表格中的首个诊断命令。 此处所有命令均为只读操作。变更操作（retry、cancel、approve、reject）会标记为 ⚠️，运行前必须先向用户提出。
4. 阅读对应页面（如何找到对应页面），了解代码含义以及接下来要检查的内容。
5. 报告发现并附上准确的命令输出，然后交接：代码更改交给 stackbone 技能，命令或迁移交给 stackbone-cli 技能。

定位失败的运行

每个 Agent 回合和每次工作流运行都是持久化运行，具有状态（running / done / failed / interrupted）和日志。默认目标是本地开发安装，并且需要运行 stackbone dev；对于已部署的 Agent，请传入 --agent <id>（来自 stackbone agents list --json）。

stackbone runs list --status failed --json          # find the run id
stackbone runs get <runId> --json                   # header: status, trigger, timing
stackbone logs tail --run <runId> --json            # the per-step frames: each 'use step', its retries, the error that failed it
stackbone logs tail --level error --json --follow   # watch a live installation

没有 runs steps 这个子命令：步骤瀑布图位于日志帧中。Studio 的 Runs 选项卡会显示相同的时间线。

症状 → 首个诊断

症状	首要诊断
stackbone 命令失败	使用 --json 重新运行；查看 error.code 和 error.suggestion；使用 STACKBONE_LOG_LEVEL=debug 升级排查，然后针对启动阶段添加 --verbose
退出码 3，没有项目 / dev_not_running	运行 stackbone metadata --json；检查 .stackbone/project.json 是否存在，以及 stackbone dev 是否正在运行
针对 --agent 出现退出码 4 runtime_not_configured	运行 stackbone agents get <slug> --json：该工作区尚未注册部署
stackbone dev 停止运行，或没有任何内容启动	查看启动横幅；首次运行会等待模型提供商（会打印 Studio 链接）
工作流启动遭拒，未创建运行（HTTP 400）	运行 stackbone workflows schema <name> --json；将请求正文与 400 响应中的 issues[] 对比
出现 workflow_not_found / workflows list 没有任何内容	检查是否存在 workflows/<name>.workflow.ts；检查 dev 是否正在提供该工作流
某个步骤重试后运行失败	运行 stackbone logs tail --run <runId> --json：查看反复出现的 error.cause；检查该步骤是否幂等
运行卡在 running 状态且没有进展	运行暂停在 requestApproval() 闸门：运行 stackbone hitl list --status pending --json
运行已暂停，但收件箱为空	运行 stackbone logs tail --run <runId> --json，检查是否有 approval_persist_failed；或者暂停已超时，且已触发 fallback
Agent 在受闸门限制的工具上执行轮次时状态为 interrupted；新消息遭拒	在作出决定前，这是预期行为：运行 stackbone hitl list --status pending --json → ⚠️ stackbone hitl approve <id> --yes --json
Agent 忘记了对话	检查客户端是否发送了 x-stackbone-session；检查工作区是否有 checkpointer peer（启动日志会警告一次）
运行成功，但没有输出	请求正文返回了 undefined，而不是与 outputSchema 匹配的对象
定时任务从不触发或重复触发	运行 stackbone workflows list --json；从步骤中调用 stackbone.workflows.listSchedules()
stackbone.connection(id) 抛出异常	查看 err.code：connector_installation_required → 操作员尚未在 Studio 中安装该连接器；credential_error / no_token → 检查其凭据。该 id 是连接器原样的 id，并非每个连接各自的 id
刚上传的键出现存储 404；签名 URL 出现 403	检查是否检查了上传操作的 error；URL 的 TTL 是否已过期；本地 MinIO 是否正在运行
查询缓慢、pgvector 排序错误、tsvector 搜索结果为空	运行 stackbone db schemas --json、stackbone db query "<single SELECT>" --json；EXPLAIN 需要在 STACKBONE_POSTGRES_URL 上使用 psql
stackbone build / package 中止	查看错误信息中提到的原生依赖或第二份 SDK 副本（嵌套的 node_modules 或针对每个 Agent 单独固定的版本）
stackbone.secrets.get 返回 secrets_not_found / _decrypt_failed	运行 stackbone secrets list --json（仅显示名称，值已隐藏）
模型调用没有返回结果、429 或 402	查看 result.error.code（ai_*）；检查 Studio 网关页面上的模型提供商

如何查找所有者页面

• SDK 错误代码（result.error.code 中的 <prefix>_<reason>）：使用 search_docs 在 sdk 区域中原样搜索该代码。所有者页面会在错误表中列出该代码，因此排名最高的结果就是对应页面。前缀表示所属界面（ai_* → stackbone.ai、rag_* → stackbone.rag、secrets_* → stackbone.secrets，……）；但有两个例外：s3_* 属于 stackbone.storage，approval_* 属于 Human-in-the-loop。contract_* 和 capability_unavailable 在 @stackbone/sdk overview（SDK › Reference）中说明。
• ConnectorCallError 错误代码（connector_installation_required、credential_error、invalid_args，……）：查看 stackbone.connection（SDK › Platform），其中列出了完整代码清单。匹配 err.code，切勿使用 instanceof。
• CLI 的 error.code（dev_not_running、runtime_not_configured、no_project，……）或退出代码：先查看 Troubleshooting（CLI › Guides），再查看 Configuration reference（CLI › Reference）中的退出代码表。
• 来自 box 或控制平面的 HTTP 状态码：使用 search_docs 搜索状态码和路由（400 workflow_input_invalid、404 workflow_not_found）；工作流路由位于 CLI › Agent protocol 下。402 响应正文（tier_quota_exceeded、*_cap_reached）不是 SdkError，也不可重试：原样显示其消息；组织所有者可以升级。
• 想事后查看某次运行：查看 Logging & observability（SDK › Platform）；box 无法注册或响应：查看 Home › Deploy 下的 Troubleshooting。

需要牢记的三点

• 只有三个界面会抛出错误，其余都会返回 { data, error }。 stackbone.database 会抛出 Drizzle/Postgres 错误；callDeepAgent / streamDeepAgent 会抛出错误并导致外层步骤失败；stackbone.connection(id) 会抛出 ConnectorCallError（匹配 err.code，切勿使用 instanceof）。其他所有内容都会将代码放在 result.error.code 中，并提供 meta 和 cause 作为结构化处理途径。
• 402 是控制平面响应正文，不是 SDK 错误代码。 SDK 端与积分包用尽相对应的错误是 ai_credits_exhausted。
• --agent <id> 对其他组织返回 404 属于预期行为。 Studio 也会使用相同的 404，以避免泄露该对象是否存在。

本技能不涵盖的内容

运行时性能调优（冷启动、规格配置）、402 响应正文以外的成本分析，以及自定义 OTel 管道。目前，Studio 的 Logs 和 Costs 选项卡是这些任务的受支持界面。

其他技能

• stackbone：修复代码问题，例如 defineDeepAgent、步骤或环境调用。
• stackbone-cli：修复命令、迁移或部署步骤。
• stackbone-coder：通过访谈，从一句话的想法开始创建新内容。