# 故障排查

## 先分清是环境问题还是业务问题

这决定了要不要打扰你。助手按下表分诊：

| 特征 | 类型 | 处理 |
| --- | --- | --- |
| `command not found` | 环境 | 装 CLI：`npm i -g dingtalk-workspace-cli` |
| `authenticated: false` / `resolve access token` 失败 | 环境 | 跑 `dws auth login` |
| `category: validation` + `缺少必填参数 X` | **参数问题，不是权限** | 补参数重试，不打扰你 |
| `category: validation` + `unknown flag` / `blocked_flag` | **参数问题** | 查 `--help` 换正确 flag |
| `category: api` + `server_error_code` 含 `RightsDenied` / 「权益」 | **权益未开通**（要买/要开通） | 说明缺哪项权益，指向管理后台 |
| `category: api` + 权限点相关 | **权限不足** | 说明缺哪个权限点 |
| `subtype: missing_collection` | **既不是错误也不是空** | 换入口交叉确认，**不报告「没有数据」** |
| 网络超时 / `doctor` 网络项失败 | 环境 | 停止说明，**不重试写操作**（可能已生效） |

## 常见问题

### 「AI 审批后端不可用，命令未执行」

**现象**：任何 `dws` 命令都跑不起来，报这句。

**原因**：Agent 的执行审批模式默认是 `ai-approve`，它需要一个**可用的审批 chat 模型**。没配的话所有命令被 fail-closed 拦截。

**这个问题比看起来严重**：DesireCore 强制要求 Agent 执行前先写 `PLAN.md`，而 `Write` 也被拦 ⇒ 助手连自己的计划文件都写不了。

**解法二选一**：
- 在资源管理面板 → 算力，配一个可用的 chat 模型
- 或把审批模式改成 `allow-listed` / `ask-always`

合法取值：`ai-approve` `ai-auto` `ai-assist` `ask-always` `allow-listed` `ask-external` `allow-all`

### 每条命令都弹审批卡片，点到手软

**现象**：每个 `dws` 命令都被标**高风险**并要求确认。实测 18 个用例里 34 次 Bash 调用触发了 **41 次审批**。

**原因**：`dws` 不在命令白名单里。fail-closed 本身是对的（钉钉 CLI 有 339 个自己不拦的写操作），但日常用起来太重。

**解法**：聊天页 → 资源管理面板 → 审批模式，把 `dws` 加入允许列表。

### 「未登录」但我明明授权过

先看 token 是不是过期了：

```bash
dws auth status --format json
```

access token 约 2 小时、refresh token 约 30 天。refresh token 过期需要重新 `dws auth login`。

⚠️ **钉钉不支持账号密码登录**。给助手账号密码它会告诉你这一点，不会去尝试。

### 无浏览器环境怎么授权

```bash
dws auth login --device
```

会打印授权链接和一个形如 `XXXX-XXXX` 的码，15 分钟过期。过期后 dws 会**自动重新出码**，不用手动重启。

### 助手说某个能力不可用，是真的吗

助手区分三种「不可用」，措辞不同：

- **权益未开通** —— 需要在钉钉侧购买/开通（如消息搜索）
- **权限不足** —— 需要管理员配权限点
- **CLI 无此入口** —— 钉钉 CLI 根本没有这个能力（如视频会议发起）

第三种是硬边界，配什么都没用。

### 装了 CLI 但助手找不到技能

官方 `dws` 的技能分发列表里**没有 DesireCore**（它认识 80+ 个别的 Agent 框架）。需要手工拷：

```bash
DC_ROOT="${DESIRECORE_TEST_ROOT:-${DESIRECORE_HOME:-$HOME/.desirecore}}"
cp -R ~/.dws/skills/multi/dingtalk-* "$DC_ROOT/skills/"
```

**每次 `dws upgrade` 后要重拷一次**——这样装的技能没有 provenance，不会自动更新。

## 遇到文档矛盾时以什么为准

钉钉官方技能文档内部有自相矛盾之处（实测发现三处）。官方 `SKILL.md` 自己声明：

> 命令可用性以当前 dws 二进制为准。本文档随内置 skill 发布，**可能滞后于二进制**。

**所以一律以 `dws <cmd> --help` 与 `dws schema --cli-path "<路径>" --compact` 的实际输出为准**，不要在文档之间做逻辑推理。

已实测定论的三处（官方各错一处）：

| 冲突 | 实测结论 |
| --- | --- |
| 视频会议是否走 misc | **不走**。29 个产品里没有会议类产品，CLI 无入口 |
| 个人身份能否撤回消息 | **能**。`chat +messages-recall` 存在 |
| 在线表格能否导出 xlsx | **能**。`dws sheet export` 存在 |
