### 错误代码

#### FILE_NOT_FOUND

**描述：** 文件不存在。

**原因：**

- 文件路径错误
- 文件已被删除
- 权限不足

**解决方案：**

- 检查文件路径是否正确
- 使用 `list_dir` 查看目录结构
- 检查文件权限

#### INVALID_FORMAT

**描述：** `read_file` 输入疑似混入了工具调用文本，或使用了其它不支持的格式。

**原因：**

- 把函数工具调用文本粘进了 `path` 或 `range`
- 把多个工具调用合并进了一次 `read_file`

**解决方案：**

- 将每个工具调用拆成独立函数调用
- 只传入结构化的 `read_file({ path, range, max_lines, show_linenos })` 参数

#### ACCESS_DENIED

**描述：** 访问 rtws 保留路径被硬拒绝。

**原因：**

- `.minds/**` 是团队配置、记忆与资产的保留路径
- rtws 根目录下的 `.dialogs/**` 是对话/运行时持久化保留路径
- `*.tsk/` 是封装的差遣牒路径

**解决方案：**

- 对 `.minds/**`，在团队配置了对应工具集时使用 `team_mgmt_*` 工具
- 排查 Dominds 对话时，在嵌套 rtws 下复现，例如 `ux-rtws/.dialogs/**`
- 不要通过通用 ws_read 工具读取或搜索 `*.tsk/` 包

#### SEARCH_FAILED

**描述：** 搜索失败。

**原因：**

- 搜索模式语法错误
- 搜索路径不存在

**解决方案：**

- 检查搜索模式是否正确
- 检查搜索路径是否存在

#### DISALLOWED_ARG

**描述：** 原始 ripgrep 参数不被允许。

**原因：**

- 该参数会绕过工具安全策略
- 当前封装的 `ripgrep_*` 工具不支持该参数

**解决方案：**

- 移除不被允许的原始参数
- 改用结构化工具参数（`pattern`、`globs`、`path` 等）

#### FAILED

**描述：** 读/搜索操作通过校验后仍执行失败。

**原因：**

- 底层文件系统或 ripgrep 执行失败
- 操作系统级权限阻止了读/搜索操作
- 路径或搜索配置在运行时变为无效

**解决方案：**

- 重新读取或列出目标路径
- 缩小搜索路径/模式后重试
- 当错误正文指向权限失败时，修复文件系统权限
- 若重复失败，汇报精确工具输出与路径/模式

### 常见问题

#### Q: 为什么无法读取文件？

A: 可能原因：

1. 文件路径错误
2. 文件不存在
3. 文件系统权限或其它运行时失败

#### Q: 为什么搜索不到结果？

A: 可能原因：

1. 搜索模式错误
2. 搜索路径不正确
3. 没有匹配的内容

#### Q: 可以读取 rtws 以外的文件吗？

A: 不能，ws_read 只能读取 rtws（运行时工作区）内的文件。

#### Q: 为什么 list_dir 返回空？

A: 可能原因：

1. 目录为空
2. 目录不存在
3. 文件系统权限或其它运行时失败

#### Q: 如何搜索特定类型的文件？

A: 使用 `globs` 参数指定文件类型，例如：

```typescript
ripgrep_files({
  pattern: 'TODO',
  globs: ['*.ts', '*.tsx'],
});
```
