# dsh-tool-ths 工具与配置参考

本文档是插件配置项与全部工具参数的权威参考。参数校验、默认值、渲染行为均以
`index.js` 中的 `Config` 与各 `defineTool` 定义为准。

## 1. 配置项（Config）

| 配置项 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `channel` | `"public" \| "ifind"` | `"public"` | 数据通道。`public` 免登录；`ifind` 需 `refreshToken` |
| `refreshToken` | string（secret） | `""` | iFinD 账号 refresh_token，`channel: ifind` 时必填 |
| `baseUrl` | string | `https://quantapi.51ifind.com/api/v1` | iFinD HTTP API 根地址（一般无需改） |
| `timeoutMs` | number | `30000` | 单次 HTTP 请求超时（毫秒），须为正整数 |
| `retries` | number | `2` | 网络层重试次数（不含 token 失效重登），须为非负整数 |
| `maxCodes` | number | `20` | 单次调用最多证券代码数，超出截断 |
| `maxRows` | number | `120` | K线等长序列渲染给模型的最大行数，超出截断并注明 |

配置入口（任一即可，设置页优先）：

1. GUI：**设置 → 插件 → dsh-tool-ths**（channel 下拉、refreshToken 密码框）；
2. 文件：profile 的 `cordis.patch.yml` 中 `tool-ths` 行的 `config`。

## 2. 证券代码格式

所有工具接受以下形式（大小写不敏感，逗号/空格分隔）：

| 输入 | 归一化 | 说明 |
| --- | --- | --- |
| `600519` | `600519.SH` | 裸代码按首位推断市场 |
| `600519.SH` / `sh600519` | `600519.SH` | 显式沪市 |
| `000001` / `000001.SZ` / `sz000001` | `000001.SZ` | 深市（含 3 开头创业板） |
| `300750` | `300750.SZ` | 创业板 |
| `830799` / `920002` / `bj830799` | `830799.BJ` | 北交所（4/8 开头裸代码自动识别） |
| `399001` / `399006` | `399001.SZ` | 深市指数（深证成指/创业板指） |

推断规则：首位 `6/5/9` → 沪（hs）；`0/1/2/3` → 深（sz）；`4/8` → 北（bj）。

⚠️ public 通道暂不支持沪市指数（如上证指数）；如需可切换 ifind 通道或先用
`ths_code` 转换。

## 3. 工具参考

所有工具的输出均为 Markdown 表格文本（渲染给模型）；执行失败抛出带错误码的
异常，错误码见《故障排查》。

### 3.1 ths_status — 连接状态

无参数。返回：

- 通道（public/ifind 及中文名）；
- 是否已登录、iFinD access_token 有效期；
- refresh_token 是否已配置（未配置时附带获取指引）；
- 最近一次调用错误（label/code/message）；
- public 通道连通性探测结果（拉取 600519 分时验证）。

### 3.2 ths_quote — 实时行情

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `codes` | ✅ | 证券代码列表，逗号分隔，上限 `maxCodes` |
| `indicators` | — | 仅 ifind：指标列表（逗号分隔）。缺省用 `DEFAULT_QUOTE_INDICATORS` |

**public 通道**固定返回列：代码 | 名称 | 最新价 | 涨跌 | 涨跌幅 | 今开 | 最高 |
最低 | 昨收 | 均价 | 成交量(股) | 成交额(元) | 状态 | 时间/日期。

**ifind 通道**默认指标：`tradeDate, tradeTime, preClose, open, high, low,
latest, change, changeRatio, totalCapital, mv, pe_ttm, pb, swing, vol_ratio,
suspensionFlag, tradeStatus`，按请求顺序输出「代码 + 各指标」列。完整指标名与
中文标签见 `lib/ifind.js` 的 `QUOTE_INDICATOR_LABELS`（如 `avgPrice` 均价、
`lastest_price` 最新成交价、`committee` 委比、`commission_diff` 委差、
`riseDayCount` 连涨天数、`af_backward` 后复权因子等）。

⚠️ 注意：iFinD 的 `real_time_quotation` **不提供** volume/amount/turnoverRatio
（成交量/成交额/换手率），需要这些字段请用 `ths_kline`。

### 3.3 ths_kline — 历史K线

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `codes` | ✅ | 证券代码列表 |
| `period` | — | `D`（默认）/`W`/`M`；ifind 另支持 `Q`/`S`/`Y` |
| `startDate` | — | `YYYY-MM-DD`；ifind 默认一年前；public 忽略（返回最近窗口） |
| `endDate` | — | `YYYY-MM-DD`；默认今天 |
| `adjust` | — | 仅 ifind：`none`（默认，不复权）/ `qfq`（前复权）/ `hfq`（后复权），或 1-7 |
| `indicators` | — | 仅 ifind：指标列表，缺省 `open,high,low,close,changeRatio,volume,amount,turnoverRatio` |

**public 通道**：日线约 140 根、周/月线约 1260 根窗口（服务端固定），返回列：
代码 | 日期 | 开盘 | 最高 | 最低 | 收盘 | 涨跌幅 | 成交量(股) | 成交额(元) |
换手率。涨跌幅由相邻收盘价计算。

**ifind 通道**：`functionpara` 为 `{Interval, CPS}`（CPS 由 `adjust` 映射，
详见《协议与数据格式》）。注意 iFinD 对单次区间有数据量/时间跨度限制
（如免费账号单条 ≤5 万条、部分区间 ≤3 年/1 年/6 个月等，错误码见故障排查）。

### 3.4 ths_basic — 基础财务数据（仅 ifind）

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `codes` | ✅ | 证券代码列表 |
| `indicators` | ✅ | 字符串数组，每项 `指标名[:参数1[:参数2...]]`，如 `["ths_roe_stock:20241231", "ths_total_equity_atoopc_stock"]` |

输出「代码 | 指标 | 值」长表。指标名与参数用 iFinD 超级命令客户端生成/核对
（如 `ths_roe_stock` 净资产收益率、`ths_regular_report_actual_dd_stock` 定期
报告实际披露日期）。

### 3.5 ths_trade_dates — 交易日历（仅 ifind）

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `startDate` | ✅ | `YYYY-MM-DD` |
| `endDate` | ✅ | `YYYY-MM-DD` |
| `market` | — | `sh`（默认）/`sz`/`hk`/`cffex`/`shfe`/`dce`/`czce`/`nyse`/`nasdaq`，或直接传数字 marketcode |
| `dateType` | — | `0` 交易日（默认）/ `1` 日历日 |
| `period` | — | `D`（默认）/`W`/`M`/`Q`/`S`/`Y` |

### 3.6 ths_announcement — 公告查询（仅 ifind）

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `codes` | ✅ | 证券代码列表 |
| `startDate` | ✅ | 公告开始日期 |
| `endDate` | ✅ | 公告截止日期 |
| `keyWord` | — | 标题关键词筛选（如 `半年度报告`） |
| `reportType` | — | 类型编码，默认 `903`（全部）；如 `901002004`（上市公告书） |

输出列：公告日期 | 代码 | 简称 | 发布时间 | 标题 | PDF链接 | seq。最多显示
50 条（超出提示缩小范围）。

### 3.7 ths_code — 代码/简称转换（仅 ifind）

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `keyword` | ✅ | 行情代码（纯数字 → `seccode` 模式）或证券简称（→ `secname` 模式） |
| `isExact` | — | 是否精确匹配，默认 false（模糊） |

输出「同花顺代码 | 详情」表。当 `-4206 含有错误的同花顺代码` 时可用本工具
先确认正确代码。

## 4. 工具超时与并发

- 每个工具声明 `timeoutMs`（取配置值），由 DSH 的 tool-call-timeout 策略
  强制执行（协作式超时）；
- 只读工具（全部 ths_*）声明 `isConcurrencySafe: true`，可并行调用；
- `ths_quote`（public）内部对多代码并发拉取分时+日线；网络层 502 自动重试
  （`retries` 次，指数退避 250ms×n）。