draftgo-cli 3.0.56 → 4.0.22

package/resources/skill/references/diagnostics.md

@@ -0,0 +1,51 @@
+---
+read_when: 运行失败、MCP/API 调用异常、远端状态不一致或需要查询运行日志时
+---
+
+# 运行诊断
+
+## 最短诊断链
+
+```bash
+draftgo status --output json
+draftgo mcp status
+draftgo mcp test
+draftgo map --type pages --summary --output json
+draftgo check --remote --output json
+```
+
+`draftgo status` 的 `connection.health` 报告 `healthy`、`unhealthy` 或 `not_configured`，并输出当前 `platform`/`space` TokenScope；space 上下文同时带 `workspace_id` 与 `space_id`。只执行与故障层级有关的命令：连接失败看 `mcp test`；已知页面可用 `map --type pages --route <path>` 或 `--title <title>` 精确检查，未知资源先看 `map --summary`；checkout、哈希或版本异常看 `check --remote`。需要浏览时用 `--limit <1-100>`（默认 20）和单一类型的 `--cursor`，不运行默认全量 map。命令失败仍保留其非零退出码和脱敏输出。
+
+API 运行失败时，用原 operation 生成结构化诊断：
+
+```bash
+draftgo api describe <operation_id>
+draftgo api call <operation_id> --input request.json --output json
+draftgo api search "AI run logs"
+```
+
+记录 `operation_id`、`status_code`、`server_code`、`request_id`，再通过实时日志 operation 查询对应 run。AI 调用按入口 Agent/模型和 request ID 定位；子 Agent 链路从 span 查，不把一次入口请求误算成多条主 run。自定义服务再按 `custom-services.md` 执行 validate/test，页面运行时再读 `runtime.md`。
+
+## 权限与范围诊断
+
+| 结果 | 最短定位 |
+|---|---|
+| 400 | 重新 `draftgo api describe <operation_id>`，核对当前 registry revision、`path/query/body/multipart` 容器、必填字段和 `scope_type/space_id` 组合。不要靠修改字段名试探契约。 |
+| 401 | 运行 `draftgo status`；检查项目是否连接、当前用户 API Key 是否缺失、过期或已撤销。重新连接或轮换后再试一次，不把密钥放进输入、宿主配置或日志。 |
+| 403 | 从结构化错误读取 `error_code`、`permission` 和 `scope_type`；核对 operation 所需 permission、API Key TokenScope、持久化 ResourceOwnership、有效 AccessGrant 和 DataRange。管理员身份与工作区成员关系都不是授权来源。 |
+| space 跨根拒绝 | 这是预期边界。确认目标资源保存的 workspace root 与 Grant 所属 root；改用同根 self/subtree Grant 或合法迁移流程。只有实时契约支持且明确需要跨空间管理时，才检查显式 permission 的 platform Grant。不要篡改 workspace/space ID 或 header 重试。 |
+
+解释 Grant 来源时先用实时契约，不从角色名或 UI 状态推测：
+
+```bash
+draftgo grant list --input request.json
+draftgo api search "access grant explain"
+draftgo api describe <explain_operation_id>
+draftgo api call <explain_operation_id> --input request.json --output json
+```
+
+按解释结果核对直接用户 Grant 与用户组 Grant 的并集、Role 中的精确 permission、space 的 self/subtree 覆盖、Grant/Role/成员/组的启用状态和有效期，以及最终 `matched_grant_ids` / DataRange。没有匹配来源时保持拒绝，不临时授予更大的 platform 权限来验证。
+
+不要在 issue、工作日志、命令参数或诊断文件中写 API Key、服务凭据、Authorization、完整请求头或上游服务地址。非幂等写入失败后先回读状态，不自动重试。
+
+完成条件：故障已定位到连接、契约、权限、资源版本、Runner 或业务运行中的一层，并保留可关联的 request ID/run 证据；无法定位时明确缺少哪项服务端证据。