# dsh-tool-ths 故障排查

按现象排查；错误码均可在工具报错信息中看到（形如 `ThsError [CODE]: 消息`）。

## 1. 插件没有加载

**现象**：设置 → 插件页看不到 `tool-ths`；会话里没有 `ths_*` 工具。

排查顺序：

1. 确认加载项已写入 profile 补丁层：
   ```bash
   dsh --profile web --dump-config | grep -A12 tool-ths
   ```
   若无输出，检查 `~/.dsh/profiles/web/cordis.patch.yml` 是否被覆盖/删除。
2. 确认插件文件存在：`ls ~/.dsh/profiles/web/plugins/dsh-tool-ths/`。
3. 确认 `name` 路径正确：补丁在 `~/.dsh/profiles/web/cordis.patch.yml`，
   则 `name: ./plugins/dsh-tool-ths/index.js`；若补丁文件在别处，路径要相应
   调整（相对补丁所在 profile 根目录）。
4. HMR 是否生效：修改补丁后，GUI 日志（启动它的终端）应出现 loader 相关
   输出；若无变化，重启 GUI（`dsh --profile web`）。修改补丁本身不影响
   已保存的其他配置。
5. 插件加载失败会打印在 GUI 启动终端：`failed to import loader entry tool-ths
   (...): Cannot find module ...` 通常是路径问题；`service "X" has been
   registered` 之类是依赖冲突，把报错发我。

## 2. 工具报错 THS_NEED_IFIND

`ths_basic / ths_trade_dates / ths_announcement / ths_code` 仅支持 ifind 通道。

解决：把 `channel` 改为 `ifind` 并配置 `refreshToken`（GUI 设置 → 插件 →
dsh-tool-ths，或 patch 的 `config.refreshToken`），然后 `ths_status` 确认
「已登录: 是」。

## 3. IFIND_NO_TOKEN / 登录失败

- `IFIND_NO_TOKEN`：refreshToken 为空 → 按 `ths_status` 提示获取并填写。
- `iFinD 登录失败 (-1301/-1302)`：refresh_token 无效或已过期 → 重新在
  iFinD 超级命令客户端/网页版账号详情获取新 refresh_token，并更新配置。
  注意：**更新 refresh_token 会使所有旧 token 失效**，旧配置立即作废。
- `iFinD 登录失败 (-1005)`：用户验证错误 → 账号密码/权限问题，联系同花顺
  （热线 952555）。
- `-1303 Device exceed limit`：access_token 绑定 IP 超 20 个 → 用
  `update_access_token` 重置绑定（会让旧 token 失效，谨慎操作）。

## 4. 行情返回异常

| 现象 | 原因 | 处理 |
| --- | --- | --- |
| public 通道偶发失败/超时 | 公开接口 502/限流 | 插件自动重试（`retries` 次）；仍失败稍后重试，或换 ifind |
| `THS_PUBLIC_BAD_RESPONSE/JSON` | 接口返回非 JSONP | 检查网络代理是否拦截 HTTP；稍后重试 |
| 代码报 `THS_BAD_CODE` | 格式不支持 | 用 `600519` / `600519.SH` / `sh600519` 格式；4/8 开头自动按北交所 |
| 沪市指数查不到 | public 通道不支持 | 换 ifind 通道 |
| `-4206 含有错误的同花顺代码` | 代码市场推断错误 | 显式加后缀（如 `000001.SZ`），或用 `ths_code` 转换 |
| 涨跌幅与预期不符 | public 通道由相邻收盘价/昨收计算 | 复权数据请用 ifind 的 `adjust` 参数 |
| K线缺当天 | 日线接口收盘后才落库（public） | 盘中实时数据用 `ths_quote`；K线等收盘后 |

## 5. 数据量/区间限制（ifind）

| 错误码 | 含义 | 处理 |
| --- | --- | --- |
| -4301/-4302/-4303 | 本周基础/行情/EDB 数据量超限 | 等下周额度或升级账号 |
| -4305/-4306/-4312/-4319/-4321/-4322 | 单条命令数据量过大 | 减少代码数、指标数或日期范围 |
| -4308~-4316 | 起止时间跨度超限（3月/6月/1年/3年） | 缩小 `startDate~endDate` 区间，分多次查询 |
| -4400 | 每分钟超过 600 条请求 | 降低调用频率 |

## 6. 设置页不生效

- 设置 → 插件 → dsh-tool-ths 修改后：`channel`、`refreshToken` 等立即生效
  （`ThsGateway` 按配置变更重建客户端）；若改的是 `timeoutMs/retries`，需要
  重建 iFinD 客户端——同样即时生效。
- 设置页保存的值优先级高于 patch 文件里的 `config`；想回到文件值，可在设置页
  清空/重置该段。
- 若设置页找不到 dsh-tool-ths 段，说明插件未加载（见第 1 节）。

## 7. 调试技巧

```bash
# 通道冒烟测试（免登录）
cd ~/Deepseek_Harness/dsh-tool-ths && node scripts/smoke.mjs 600519

# 含 ifind 通道
IFIND_REFRESH_TOKEN=<你的token> node scripts/smoke.mjs 600519

# stub 注册表加载插件并逐个调用所有工具
node scripts/harness.mjs 600519

# 真实 Cordis Loader 激活测试（需要工作区 node_modules 已软链 DSH 包）
node scripts/loader-activation-test.mjs
```

- 查看 GUI 启动终端里的 loader 日志：插件加载/激活/失败都会打印。
- `ths_status` 会显示最近一次调用错误（含错误码），先跑它再贴结果。