# 涉诉 / 涉税风控会话

独立风控 Agent，**不是**豆包联网问答 `POST /v1/agent/chat/completions`。

先查已开通的 **9** 个公开数据维度（涉诉 `sifa` 6 + 涉税 `sat` 3），规则评分后再由整理模型写 Markdown。
鉴权：`Authorization: Bearer tr-...`。上游 `authCode` 由平台渠道配置，**调用方不得传入**。
响应头含 `X-Request-Id: tr-req-...`。

`messages` 必填，至少一条 `user`。本期只接受字符串 `content`（图文 / 文件 → 400）。
客户端须自行回传历史；**网关只使用最近 10 条**（含本轮 user）。
不接受 `conversation_id`（传入忽略）。`bot_id` 传入忽略。

企业识别：规则抽取全称（含「公司 / 集团 / 有限 / 厂 / 事务所」）或 **18 位**统一社会信用代码。
信用代码走工商 siac `keywordType=02`，全称走 `01`；siac 成功则回显全称与代码。
抽不出 → HTTP 400，`error.code=missing_company`。

**覆盖清单（未列入类型不查询、不出现在卡片或摘要，不承诺立案 / 纳税信用 / 重大税收违法）：**

涉诉 `sifa`（本期）：

| dataType | 中文 | source_type |
| --- | --- | --- |
| cpws | 裁判文书 | 裁判文书公开 |
| zxgg | 执行公告 | 执行信息公开 |
| shixin | 失信公告 | 失信被执行人公开 |
| ktgg | 开庭公告 | 开庭公告 |
| fygg | 法院公告 | 法院公告 |
| sifacdk | 司法查冻扣 | 司法查控公开 |

涉税 `sat`（本期）：

| dataType | 中文 | source_type |
| --- | --- | --- |
| satparty_qs | 欠税公告 | 欠税公告 |
| satparty_chufa | 涉税处罚 | 税务处罚公开 |
| satparty_fzc | 税务非正常户 | 税务非正常户公开 |

空结果：涉诉六类均成功且 0 命中 →「未查询到公开涉诉信息」；涉税三类同理 →「未查询到公开涉税信息」。
任一侧有失败维 → 该侧写「查询失败，不能确认无记录」，**禁止**用「未查询到」冒充。
全部 9 维失败 → HTTP 502，不返回空报告。部分失败 → HTTP 200 + `warnings` + `coverage.failed`。

`report.score` / `rating` 只来自规则，模型不得改数。
`cards` 由 `company` + `report` 服务端派生：`risk_summary` + 每维一张 `risk_dimension`。
样本必填 `entry_id`、`title`、`date`、`source_type`；案号等摘不出则为 `null` 并列入 `fields_missing`，禁止模型补全。
失败维 `status=failed`，`hit_count` 为 null，禁止当成 0 条。

兼容别名：`POST /v1/agent/risk/chat/completion`。

## POST /v1/agent/risk/chat/completions

> 涉诉 / 涉税风控会话

独立风控 Agent，**不是**豆包联网问答 `POST /v1/agent/chat/completions`。

先查已开通的 **9** 个公开数据维度（涉诉 `sifa` 6 + 涉税 `sat` 3），规则评分后再由整理模型写 Markdown。
鉴权：`Authorization: Bearer tr-...`。上游 `authCode` 由平台渠道配置，**调用方不得传入**。
响应头含 `X-Request-Id: tr-req-...`。

`messages` 必填，至少一条 `user`。本期只接受字符串 `content`（图文 / 文件 → 400）。
客户端须自行回传历史；**网关只使用最近 10 条**（含本轮 user）。
不接受 `conversation_id`（传入忽略）。`bot_id` 传入忽略。

企业识别：规则抽取全称（含「公司 / 集团 / 有限 / 厂 / 事务所」）或 **18 位**统一社会信用代码。
信用代码走工商 siac `keywordType=02`，全称走 `01`；siac 成功则回显全称与代码。
抽不出 → HTTP 400，`error.code=missing_company`。

**覆盖清单（未列入类型不查询、不出现在卡片或摘要，不承诺立案 / 纳税信用 / 重大税收违法）：**

涉诉 `sifa`（本期）：

| dataType | 中文 | source_type |
| --- | --- | --- |
| cpws | 裁判文书 | 裁判文书公开 |
| zxgg | 执行公告 | 执行信息公开 |
| shixin | 失信公告 | 失信被执行人公开 |
| ktgg | 开庭公告 | 开庭公告 |
| fygg | 法院公告 | 法院公告 |
| sifacdk | 司法查冻扣 | 司法查控公开 |

涉税 `sat`（本期）：

| dataType | 中文 | source_type |
| --- | --- | --- |
| satparty_qs | 欠税公告 | 欠税公告 |
| satparty_chufa | 涉税处罚 | 税务处罚公开 |
| satparty_fzc | 税务非正常户 | 税务非正常户公开 |

空结果：涉诉六类均成功且 0 命中 →「未查询到公开涉诉信息」；涉税三类同理 →「未查询到公开涉税信息」。
任一侧有失败维 → 该侧写「查询失败，不能确认无记录」，**禁止**用「未查询到」冒充。
全部 9 维失败 → HTTP 502，不返回空报告。部分失败 → HTTP 200 + `warnings` + `coverage.failed`。

`report.score` / `rating` 只来自规则，模型不得改数。
`cards` 由 `company` + `report` 服务端派生：`risk_summary` + 每维一张 `risk_dimension`。
样本必填 `entry_id`、`title`、`date`、`source_type`；案号等摘不出则为 `null` 并列入 `fields_missing`，禁止模型补全。
失败维 `status=failed`，`hit_count` 为 null，禁止当成 0 条。

兼容别名：`POST /v1/agent/risk/chat/completion`。

### Authentication

`Authorization: Bearer tr-xxx`

### Request Body

Content-Type: `application/json`

- **messages** `object[]` **(required)**  
  OpenAI 形态消息。至少一条 `user`。支持 `system` / `user` / `assistant`。
- **messages[].role** ``system` | `user` | `assistant`` **(required)**  
  
- **messages[].content** `string` **(required)**  
  
- **stream** `boolean` (default: `false`)  
  为 `true` 时返回 SSE（`text/event-stream`）
- **identify** `boolean` (default: `false`)  
  为 `true` 时仅工商锁定企业，不查询涉诉 / 涉税 9 维，不扣上游按次费

### Response

- **id** `string` **(required)**  
  与响应头 `X-Request-Id` 相同（`tr-req-...`）
- **object** `string` **(required)**  
  
- **model** `string` **(required)**  
  
- **company** `object` **(required)**  
  
- **company.keyword** `string`  
  从 user 文本抽出的原关键词（全称或 18 位信用代码）
- **company.resolved_name** `string`  
  siac 成功时回显的企业全称；失败时为空，上游改用 `keyword` 查询
- **company.credit_code** `string`  
  siac 成功时回显的统一社会信用代码
- **company.status** `string`  
  经营状态（如「存续」），siac 失败时为空
- **report** `object` **(required)**  
  
- **report.rating** ``red` | `amber` | `green``  
  规则评级。`red` ≥ 50；`amber` ≥ 20；0 命中为 `green`（有失败且 0 命中仍为 green，但 `warnings` 含覆盖不足）
- **report.score** `integer`  
  规则评分，模型不得改数
- **report.summary** `string`  
  
- **report.fetched_at** `integer`  
  报告生成时间（Unix 毫秒）
- **report.coverage** `object`  
  
- **report.warnings** `string[]`  
  覆盖不足、`new_company` 等提示。部分失败时非空
- **report.sifa_note** `string`  
  涉诉侧规则文案（空结果或失败提示）
- **report.sat_note** `string`  
  涉税侧规则文案（空结果或失败提示）
- **report.dimensions** `object[]`  
  
- **choices** `object[]` **(required)**  
  
- **choices[].index** `integer`  
  
- **choices[].message** `object`  
  
- **choices[].finish_reason** `string`  
  
- **cards** `object[]` **(required)**  
  由 `company` + `report` 派生，便于直接渲染，不要解析 Markdown
- **cards[].card_type** ``risk_summary` | `risk_dimension`` **(required)**  
  
- **cards[].rating** ``red` | `amber` | `green``  
  
- **cards[].score** `integer`  
  
- **cards[].title** `string`  
  「risk_summary」企业全称（无解析结果时用原关键词）
- **cards[].subtitle** `string`  
  「risk_summary」存续状态或信用代码
- **cards[].summary** `string`  
  
- **cards[].domain** ``sifa` | `sat``  
  
- **cards[].data_type** `string`  
  
- **cards[].label** `string`  
  
- **cards[].status** ``ok` | `failed``  
  
- **cards[].hit_count** `integer,null`  
  
- **cards[].source_type** `string`  
  
- **cards[].samples** `object[]`  
  
- **usage** `object` **(required)**  
  
- **usage.query_calls** `integer` **(required)**  
  本轮成功的查询 / 导出次数（工商 siac 不计次）。缓存命中为 0
- **usage.query_cached** `boolean` **(required)**  
  本轮未打出查询调用（企业维 24h 缓存命中且无详情 export）
- **usage.prompt_tokens** `integer`  
  
- **usage.completion_tokens** `integer`  
  
- **usage.total_tokens** `integer`  
  

### Error Codes

- `400`: 请求无效。常见 `error.code`：
- `missing_company`：抽不出企业全称或 18 位统一社会信用代码
- `invalid_request`：非 JSON、无 user 消息、`content` 非字符串

- `401`: 
- `402`: 
- `502`: 上游 9 维全部失败（不返回空报告装无风险），或整理模型 / 渠道未配置。
常见 `error.code`：`query_unavailable`、`query_permission`、`writer_failed`、`missing_model`。
全维失败时 body 含 `request_id`。