sdpy-kit 0.6.5__tar.gz → 0.6.7__tar.gz

{sdpy_kit-0.6.5 → sdpy_kit-0.6.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sdpy-kit
-Version: 0.6.5
+Version: 0.6.7
 Summary: SDPY Kit——统一数据库访问层（PG/MySQL/SQLite）与 AI/Redis/文件/文档/向量工具集
 Author-email: Clark <changhongyuan@126.com>
 License-Expression: MIT
@@ -783,9 +783,9 @@ shutdown()                                                     # 应用退出前
 
 | 分组 | 方法 | 说明 |
 |------|------|------|
-| chat | `chat_complete(prompt, *, max_tokens=None) -> str` | 单轮对话（仅 user 消息） |
-| chat | `chat_ask(messages, *, max_tokens=None) -> str` | 多轮对话，`messages` 为 `[{"role": "user", "content": "..."}]` |
-| chat | `chat_stream(messages, *, max_tokens=None) -> Iterator[str]` | 同步流式逐 token 迭代器（建议 `with` 使用）；结束后可读 `reasoning_chars` / `content_chars` / `finish_reason` / `truncated` |
+| chat | `chat_complete(prompt, *, max_tokens=None, thinking=None) -> str` | 单轮对话（仅 user 消息） |
+| chat | `chat_ask(messages, *, max_tokens=None, thinking=None) -> str` | 多轮对话，`messages` 为 `[{"role": "user", "content": "..."}]` |
+| chat | `chat_stream(messages, *, max_tokens=None, thinking=None) -> Iterator[str]` | 同步流式逐 token 迭代器（建议 `with` 使用）；结束后可读 `reasoning_chars` / `content_chars` / `finish_reason` / `truncated` / `thinking_applied` |
 | embedding | `embed_text(text) -> list[float]` | 单文本向量化 |
 | embedding | `embed_texts(texts) -> list[list[float]]` | 批量向量化 |
 | rerank | `rerank(query, documents, top_n=None) -> list[tuple[int, float]]` | 返回 `[(原索引, 相关分)]` 降序列表 |
@@ -804,8 +804,8 @@ with AI.chat_stream([{"role": "user", "content": "写一首短诗"}]) as stream:
 
 #### 流式收尾统计（思考型模型必备）
 
-迭代器在流结束后可读四个只读属性（`reasoning_chars` / `content_chars` / `finish_reason` /
-`truncated`），用于区分「模型真的没返回」与「输出预算被思考吃光」——思考型模型的推理
+迭代器在流结束后可读五个只读属性（`reasoning_chars` / `content_chars` / `finish_reason` /
+`truncated` / `thinking_applied`），用于区分「模型真的没返回」与「输出预算被思考吃光」——思考型模型的推理
 token 计入 `max_tokens`，长上下文 + 小预算时常出现「返回 200 但正文为空」：
 
 ```python
@@ -814,20 +814,49 @@ with AI.chat_stream(messages, max_tokens=450) as stream:
 if not body and stream.truncated and stream.reasoning_chars:
     raise ValueError(
         f"输出预算被思考消耗（推理 {stream.reasoning_chars} 字符），"
-        "请调大 max_tokens 或改用关闭思考的档案"
+        "请调大 max_tokens 或对该调用传 thinking=False"
     )
 ```
 
 - 推理字段兼容 `delta.reasoning_content`（GLM / DeepSeek / Qwen）与 `delta.reasoning`（sensenova）：只计数不产出；
+- 推理字段名是 kit 内部白名单（当前就是上面两种）：新 provider 若用别的字段名，`reasoning_chars` 会恒为 0——此时仍可用 `truncated` 判定是否被截断；
 - 正文为空且（被截断或发生过思考）时 kit 自行打 `WARNING`，含模型与 `max_tokens`；
 - `truncated` 覆盖 `finish_reason` 为 `length` 或 `max_tokens` 两种口径；
 - **字符数 ≠ token 数**（实测中文约 2~2.5 字符/token，各家口径不一），不要用 `reasoning_chars` 反推还差多少预算；
 - provider 不返回 `finish_reason` 时 `finish_reason is None`、`truncated is False`；
 - 流式过程中读到的是尽力而为的中间值，**结束后才是最终值**；提前 `break` 时为截至中断的累计值。
 
+#### 逐调用思考开关（0.6.7）
+
+同一档案下按调用点切换思考（入库抽取关、章节生成开），不必复制档案：
+
+```python
+AI.chat_ask(messages, thinking=False)   # 关闭思考
+AI.chat_ask(messages, thinking=True)    # 开启思考
+AI.chat_ask(messages)                   # None：不干预（按档案 thinking.default；未配置则请求体逐字节不变）
+```
+
+kit 不认识任何厂商字段名，请求体字段由档案 `thinking` 声明翻译（见「ai_models.json 可选字段」）。
+三条局限：
+
+- **未声明即忽略**：档案没有 `thinking` 声明时，逐调用 `thinking` 被忽略并打 `WARNING`（不报错、不触发冷却），调用照常成功；
+- **跨候选降级**：候选链切到未声明的备胎时，本次调用退回厂商默认（通常是开），只在日志与 `thinking_applied` 中体现；
+- **不提供档位**：只有开/关；`low` / `medium` / `high` 这类分级本轮不支持（可用 `on` 直接给厂商取值）。
+
+`thinking_applied`（流式迭代器属性 / `StreamStats` 字段）：`None` 未要求干预 / `True` 已按声明注入 / `False` 要求了但被忽略。
+
+> 这是对 0.6.5「不新增 thinking / reasoning_effort 具名字段、只用 `extra_body`」结论的**有意修订**：
+> 当时的否决理由（候选链跨厂商，备胎收到未知字段会 400 → 冷却）已由「档案能力声明」机制解除——
+> 字段只发给声明了它的候选，未声明者不注入。思考**档位**（`low/medium/high`）仍然不做。
+
 > 首帧等待语义：每候选 60 秒内**一帧都没有**（含推理帧）才切下一候选；思考阶段的
 > 推理帧算活动并重置窗口，不会误判健康模型失败、也不会重放整段 prompt。
 
+> **非流式（`ask` / `complete`）的同款诊断**：provider 在截断时可能完全不返回 `content` 键，
+> 此时 kit 抛 `AIResponseError`，消息里带 `finish_reason` 与推理字符数（不再只报「content
+> 类型异常」，可直接判断是否被思考吃光）；正文为空串时返回 `""` 并打 `WARNING`。
+> 返回类型（`str`）与异常类型均未改变。
+
 > 门面仅面向**同步上下文**；若调用点本身在 async 函数内，请直接 `await` 原生异步服务，避免阻塞事件循环线程。
 > 模块级另有 `kit.ai.runner.reload_config(...)`、`run_sync(coro_factory, *, timeout=120.0)`、`shutdown()`。
 
@@ -847,7 +876,7 @@ await service.close()
 
 | 类 | 方法 |
 |----|------|
-| `ChatService` | `ask(messages, *, temperature=None, max_tokens=None, deadline=None) -> str`、`complete(prompt, *, ...) -> str`、`stream(messages, *, ..., stats: StreamStats | None = None) -> AsyncIterator[str]`（传 `StreamStats()` 即可读收尾统计） |
+| `ChatService` | `ask(messages, *, temperature=None, max_tokens=None, thinking=None, deadline=None) -> str`、`complete(prompt, *, ...) -> str`、`stream(messages, *, ..., thinking=None, stats: StreamStats | None = None) -> AsyncIterator[str]`（传 `StreamStats()` 即可读收尾统计）；`thinking` 语义与门面一致 |
 | `EmbeddingService` | `embed_text(text) -> list[float]`、`embed_texts(texts, *, batch_size=None, concurrency=4) -> list[list[float]]`、`dimension` 属性（**目标维度**，见下） |
 | `RerankService` | `rerank(query, documents, *, top_n=None) -> list[RerankHit]`（已按 score 降序） |
 | `ImageService` | `generate(prompt, *, size=None, n=1, return_base64=False, ratio=None) -> str` |
@@ -1380,9 +1409,26 @@ AI 功能需要在项目根目录提供 `config/ai_models.json`（chat / embeddi
 | 档案级 | `timeout` | 请求超时秒数（默认 60） |
 | 档案级 | `max_tokens` | 输出上限（chat 用）；`AI.chat_ask/chat_complete/chat_stream` 也可按调用点传参，逐级回落：调用点 → 档案 → provider 默认 |
 | 档案级 | `retries` | 5xx 重试次数（默认 2；超时不重试，候选链切换才是有效重试） |
-| 档案级 | `extra_body` | 厂商专有请求体字段透传（如 GLM/Qwen 关闭思考的 `{"thinking": {"type": "disabled"}}`、`{"reasoning_effort": "low"}`）；与服务构造的同名键冲突时**以服务的值为准**，故 `model` / `messages` / `stream` 等保留键不可覆盖；改名类需求（如 OpenAI o 系列的 `max_completion_tokens`）无法用它实现。改文件后需 `reload_config(reload_file=True)` 生效 |
+| 档案级 | `extra_body` | 厂商专有请求体字段透传（如 GLM/Qwen 关闭思考的 `{"thinking": {"type": "disabled"}}`、`{"reasoning_effort": "low"}`）；与服务构造的同名键冲突时**以服务的值为准**，故 `model` / `messages` / `stream` 等保留键不可覆盖；改名类需求（如 OpenAI o 系列的 `max_completion_tokens`）无法用它实现。逐调用 `thinking` 与之同键时**以逐调用为准**并打 `WARNING`。改文件后需 `reload_config(reload_file=True)` 生效 |
+| 档案级 | `thinking` | 思考开关的注入声明（0.6.7）：`{"arg": "thinking", "off": {"type": "disabled"}, "on": {"type": "enabled"}, "default": false}`。`arg` 是请求体顶层键名（不得占用 `model` / `messages` / `stream` / `max_tokens` / `temperature` 等保留键，配置期与运行期双重校验）；`off` / `on` 可为**任意 JSON 值**（双方都是 dict 时浅合并，否则整键替换）；`on` 缺省表示不能显式开启；`default` 为档案默认三态（`null` 不干预 / `false` 默认关 / `true` 默认开）。**未声明 = 不支持按调用切换**：逐调用 `thinking` 被忽略并告警（不报错、不影响候选链冷却）。kit 只做翻译，不含任何厂商名 |
 | 类型级 | `chain_timeout` | 整链预算秒数（与 `default_profile` 同级）；门面同步等待上限。未配置时按 `sum(候选 timeout) + 10s` 自适应，也可用环境变量 `KIT_AI_CHAIN_TIMEOUT` 全局覆盖 |
 
+`thinking` 声明两种实测形态（按平台各自写入档案）：
+
+```json
+"thinking": {"arg": "thinking", "off": {"type": "disabled"}}
+"thinking": {"arg": "chat_template_kwargs", "off": {"enable_thinking": false}}
+```
+
+- **未知字段的厂商反应不一致**：有的返回 400、有的**静默忽略**（仍照常思考）。所以 kit 只按声明下发，绝不猜厂商默认值；
+- **强制思考模型**（如只接受 `low/high/max` 的平台）不写 `thinking` 声明，逐调用开关会被忽略并告警；
+- 声明写错（`arg` 拼错、值形态不符）由厂商判定，可能 400 → 冷却；语义正确性由使用方的模型能力清单保证。
+
+> **`extra_body` 的用法边界**：`extra_body` 是**档案级**的固有配置，无法按调用点切换。需要
+> 「同一模型，长文开思考、短文关思考」并存时用档案 `thinking` 声明 + 逐调用 `thinking=False/True`
+> （0.6.7 起）；仅在无法用开关表达时才考虑复制档案 + `ModelBuilder.build_chat("<档案名>")`
+> （门面侧 `AI.use("chat", "<档案名>")` 是进程级切换，非并发安全）。
+
 ### 候选链切换语义（两类，勿混淆）
 
 - **跨调用切换**：`AI.use()` 与其它请求产生的失败冷却均只影响**下一次**请求——每次调用的候选计划在开始时定格；

{sdpy_kit-0.6.5 → sdpy_kit-0.6.7}/README.md

@@ -707,9 +707,9 @@ shutdown()                                                     # 应用退出前
 
 | 分组 | 方法 | 说明 |
 |------|------|------|
-| chat | `chat_complete(prompt, *, max_tokens=None) -> str` | 单轮对话（仅 user 消息） |
-| chat | `chat_ask(messages, *, max_tokens=None) -> str` | 多轮对话，`messages` 为 `[{"role": "user", "content": "..."}]` |
-| chat | `chat_stream(messages, *, max_tokens=None) -> Iterator[str]` | 同步流式逐 token 迭代器（建议 `with` 使用）；结束后可读 `reasoning_chars` / `content_chars` / `finish_reason` / `truncated` |
+| chat | `chat_complete(prompt, *, max_tokens=None, thinking=None) -> str` | 单轮对话（仅 user 消息） |
+| chat | `chat_ask(messages, *, max_tokens=None, thinking=None) -> str` | 多轮对话，`messages` 为 `[{"role": "user", "content": "..."}]` |
+| chat | `chat_stream(messages, *, max_tokens=None, thinking=None) -> Iterator[str]` | 同步流式逐 token 迭代器（建议 `with` 使用）；结束后可读 `reasoning_chars` / `content_chars` / `finish_reason` / `truncated` / `thinking_applied` |
 | embedding | `embed_text(text) -> list[float]` | 单文本向量化 |
 | embedding | `embed_texts(texts) -> list[list[float]]` | 批量向量化 |
 | rerank | `rerank(query, documents, top_n=None) -> list[tuple[int, float]]` | 返回 `[(原索引, 相关分)]` 降序列表 |
@@ -728,8 +728,8 @@ with AI.chat_stream([{"role": "user", "content": "写一首短诗"}]) as stream:
 
 #### 流式收尾统计（思考型模型必备）
 
-迭代器在流结束后可读四个只读属性（`reasoning_chars` / `content_chars` / `finish_reason` /
-`truncated`），用于区分「模型真的没返回」与「输出预算被思考吃光」——思考型模型的推理
+迭代器在流结束后可读五个只读属性（`reasoning_chars` / `content_chars` / `finish_reason` /
+`truncated` / `thinking_applied`），用于区分「模型真的没返回」与「输出预算被思考吃光」——思考型模型的推理
 token 计入 `max_tokens`，长上下文 + 小预算时常出现「返回 200 但正文为空」：
 
 ```python
@@ -738,20 +738,49 @@ with AI.chat_stream(messages, max_tokens=450) as stream:
 if not body and stream.truncated and stream.reasoning_chars:
     raise ValueError(
         f"输出预算被思考消耗（推理 {stream.reasoning_chars} 字符），"
-        "请调大 max_tokens 或改用关闭思考的档案"
+        "请调大 max_tokens 或对该调用传 thinking=False"
     )
 ```
 
 - 推理字段兼容 `delta.reasoning_content`（GLM / DeepSeek / Qwen）与 `delta.reasoning`（sensenova）：只计数不产出；
+- 推理字段名是 kit 内部白名单（当前就是上面两种）：新 provider 若用别的字段名，`reasoning_chars` 会恒为 0——此时仍可用 `truncated` 判定是否被截断；
 - 正文为空且（被截断或发生过思考）时 kit 自行打 `WARNING`，含模型与 `max_tokens`；
 - `truncated` 覆盖 `finish_reason` 为 `length` 或 `max_tokens` 两种口径；
 - **字符数 ≠ token 数**（实测中文约 2~2.5 字符/token，各家口径不一），不要用 `reasoning_chars` 反推还差多少预算；
 - provider 不返回 `finish_reason` 时 `finish_reason is None`、`truncated is False`；
 - 流式过程中读到的是尽力而为的中间值，**结束后才是最终值**；提前 `break` 时为截至中断的累计值。
 
+#### 逐调用思考开关（0.6.7）
+
+同一档案下按调用点切换思考（入库抽取关、章节生成开），不必复制档案：
+
+```python
+AI.chat_ask(messages, thinking=False)   # 关闭思考
+AI.chat_ask(messages, thinking=True)    # 开启思考
+AI.chat_ask(messages)                   # None：不干预（按档案 thinking.default；未配置则请求体逐字节不变）
+```
+
+kit 不认识任何厂商字段名，请求体字段由档案 `thinking` 声明翻译（见「ai_models.json 可选字段」）。
+三条局限：
+
+- **未声明即忽略**：档案没有 `thinking` 声明时，逐调用 `thinking` 被忽略并打 `WARNING`（不报错、不触发冷却），调用照常成功；
+- **跨候选降级**：候选链切到未声明的备胎时，本次调用退回厂商默认（通常是开），只在日志与 `thinking_applied` 中体现；
+- **不提供档位**：只有开/关；`low` / `medium` / `high` 这类分级本轮不支持（可用 `on` 直接给厂商取值）。
+
+`thinking_applied`（流式迭代器属性 / `StreamStats` 字段）：`None` 未要求干预 / `True` 已按声明注入 / `False` 要求了但被忽略。
+
+> 这是对 0.6.5「不新增 thinking / reasoning_effort 具名字段、只用 `extra_body`」结论的**有意修订**：
+> 当时的否决理由（候选链跨厂商，备胎收到未知字段会 400 → 冷却）已由「档案能力声明」机制解除——
+> 字段只发给声明了它的候选，未声明者不注入。思考**档位**（`low/medium/high`）仍然不做。
+
 > 首帧等待语义：每候选 60 秒内**一帧都没有**（含推理帧）才切下一候选；思考阶段的
 > 推理帧算活动并重置窗口，不会误判健康模型失败、也不会重放整段 prompt。
 
+> **非流式（`ask` / `complete`）的同款诊断**：provider 在截断时可能完全不返回 `content` 键，
+> 此时 kit 抛 `AIResponseError`，消息里带 `finish_reason` 与推理字符数（不再只报「content
+> 类型异常」，可直接判断是否被思考吃光）；正文为空串时返回 `""` 并打 `WARNING`。
+> 返回类型（`str`）与异常类型均未改变。
+
 > 门面仅面向**同步上下文**；若调用点本身在 async 函数内，请直接 `await` 原生异步服务，避免阻塞事件循环线程。
 > 模块级另有 `kit.ai.runner.reload_config(...)`、`run_sync(coro_factory, *, timeout=120.0)`、`shutdown()`。
 
@@ -771,7 +800,7 @@ await service.close()
 
 | 类 | 方法 |
 |----|------|
-| `ChatService` | `ask(messages, *, temperature=None, max_tokens=None, deadline=None) -> str`、`complete(prompt, *, ...) -> str`、`stream(messages, *, ..., stats: StreamStats | None = None) -> AsyncIterator[str]`（传 `StreamStats()` 即可读收尾统计） |
+| `ChatService` | `ask(messages, *, temperature=None, max_tokens=None, thinking=None, deadline=None) -> str`、`complete(prompt, *, ...) -> str`、`stream(messages, *, ..., thinking=None, stats: StreamStats | None = None) -> AsyncIterator[str]`（传 `StreamStats()` 即可读收尾统计）；`thinking` 语义与门面一致 |
 | `EmbeddingService` | `embed_text(text) -> list[float]`、`embed_texts(texts, *, batch_size=None, concurrency=4) -> list[list[float]]`、`dimension` 属性（**目标维度**，见下） |
 | `RerankService` | `rerank(query, documents, *, top_n=None) -> list[RerankHit]`（已按 score 降序） |
 | `ImageService` | `generate(prompt, *, size=None, n=1, return_base64=False, ratio=None) -> str` |
@@ -1304,9 +1333,26 @@ AI 功能需要在项目根目录提供 `config/ai_models.json`（chat / embeddi
 | 档案级 | `timeout` | 请求超时秒数（默认 60） |
 | 档案级 | `max_tokens` | 输出上限（chat 用）；`AI.chat_ask/chat_complete/chat_stream` 也可按调用点传参，逐级回落：调用点 → 档案 → provider 默认 |
 | 档案级 | `retries` | 5xx 重试次数（默认 2；超时不重试，候选链切换才是有效重试） |
-| 档案级 | `extra_body` | 厂商专有请求体字段透传（如 GLM/Qwen 关闭思考的 `{"thinking": {"type": "disabled"}}`、`{"reasoning_effort": "low"}`）；与服务构造的同名键冲突时**以服务的值为准**，故 `model` / `messages` / `stream` 等保留键不可覆盖；改名类需求（如 OpenAI o 系列的 `max_completion_tokens`）无法用它实现。改文件后需 `reload_config(reload_file=True)` 生效 |
+| 档案级 | `extra_body` | 厂商专有请求体字段透传（如 GLM/Qwen 关闭思考的 `{"thinking": {"type": "disabled"}}`、`{"reasoning_effort": "low"}`）；与服务构造的同名键冲突时**以服务的值为准**，故 `model` / `messages` / `stream` 等保留键不可覆盖；改名类需求（如 OpenAI o 系列的 `max_completion_tokens`）无法用它实现。逐调用 `thinking` 与之同键时**以逐调用为准**并打 `WARNING`。改文件后需 `reload_config(reload_file=True)` 生效 |
+| 档案级 | `thinking` | 思考开关的注入声明（0.6.7）：`{"arg": "thinking", "off": {"type": "disabled"}, "on": {"type": "enabled"}, "default": false}`。`arg` 是请求体顶层键名（不得占用 `model` / `messages` / `stream` / `max_tokens` / `temperature` 等保留键，配置期与运行期双重校验）；`off` / `on` 可为**任意 JSON 值**（双方都是 dict 时浅合并，否则整键替换）；`on` 缺省表示不能显式开启；`default` 为档案默认三态（`null` 不干预 / `false` 默认关 / `true` 默认开）。**未声明 = 不支持按调用切换**：逐调用 `thinking` 被忽略并告警（不报错、不影响候选链冷却）。kit 只做翻译，不含任何厂商名 |
 | 类型级 | `chain_timeout` | 整链预算秒数（与 `default_profile` 同级）；门面同步等待上限。未配置时按 `sum(候选 timeout) + 10s` 自适应，也可用环境变量 `KIT_AI_CHAIN_TIMEOUT` 全局覆盖 |
 
+`thinking` 声明两种实测形态（按平台各自写入档案）：
+
+```json
+"thinking": {"arg": "thinking", "off": {"type": "disabled"}}
+"thinking": {"arg": "chat_template_kwargs", "off": {"enable_thinking": false}}
+```
+
+- **未知字段的厂商反应不一致**：有的返回 400、有的**静默忽略**（仍照常思考）。所以 kit 只按声明下发，绝不猜厂商默认值；
+- **强制思考模型**（如只接受 `low/high/max` 的平台）不写 `thinking` 声明，逐调用开关会被忽略并告警；
+- 声明写错（`arg` 拼错、值形态不符）由厂商判定，可能 400 → 冷却；语义正确性由使用方的模型能力清单保证。
+
+> **`extra_body` 的用法边界**：`extra_body` 是**档案级**的固有配置，无法按调用点切换。需要
+> 「同一模型，长文开思考、短文关思考」并存时用档案 `thinking` 声明 + 逐调用 `thinking=False/True`
+> （0.6.7 起）；仅在无法用开关表达时才考虑复制档案 + `ModelBuilder.build_chat("<档案名>")`
+> （门面侧 `AI.use("chat", "<档案名>")` 是进程级切换，非并发安全）。
+
 ### 候选链切换语义（两类，勿混淆）
 
 - **跨调用切换**：`AI.use()` 与其它请求产生的失败冷却均只影响**下一次**请求——每次调用的候选计划在开始时定格；

{sdpy_kit-0.6.5 → sdpy_kit-0.6.7}/kit/__init__.py

@@ -23,7 +23,7 @@ Author: Clark Chang
 数据库访问通过 kit.db 子包提供（基于 SQLModel）。
 """
 
-__version__ = "0.6.5"
+__version__ = "0.6.7"
 
 from kit.db import (
     MYSQL,

{sdpy_kit-0.6.5 → sdpy_kit-0.6.7}/kit/ai/base_service.py

@@ -115,6 +115,9 @@ class BaseAIService[RequestT, ResponseT](ABC):
         同名键以服务构造的值为准——``model`` / ``messages`` / ``stream`` /
         ``input`` / ``prompt`` 等保留键**不可被档案覆盖**，故无需白名单；
         未配置时原样返回（请求体逐字节不变）。
+
+        优先级：本方法之后还会执行 :meth:`_apply_request_extras`（逐调用
+        增强），故同一键若被逐调用显式覆盖，以逐调用为准（更具体者优先）。
         """
         extra = self._profile.extra_body
         if not extra:
@@ -122,6 +125,17 @@ class BaseAIService[RequestT, ResponseT](ABC):
         merged: dict[str, object] = {**extra, **payload}
         return cast(JSONObject, merged)
 
+    def _apply_request_extras(
+        self, payload: JSONObject, request: RequestT
+    ) -> JSONObject:
+        """逐调用请求增强钩子（默认无操作：请求体逐字节不变）。
+
+        在 :meth:`_apply_extra_body` 之后执行，用于按本次调用参数改写请求体
+        （如 ``ChatService`` 的思考开关）。子类按需覆写；覆写方须自行保证
+        不覆盖 ``_build_payload`` 产出的保留键。
+        """
+        return payload
+
     @abstractmethod
     def _parse_response(self, data: JSONObject) -> ResponseT:
         """将 JSON 响应体解析为业务结果。"""
@@ -137,7 +151,9 @@ class BaseAIService[RequestT, ResponseT](ABC):
                 ``post_json`` 的重试预算检查；None 表示不限制
         """
         desc = self._log_desc()
-        payload = self._apply_extra_body(self._build_payload(request))
+        payload = self._apply_request_extras(
+            self._apply_extra_body(self._build_payload(request)), request
+        )
         params = _truncate(
             json.dumps(_clip(payload), ensure_ascii=False), _LOG_PAYLOAD_LIMIT
         )

{sdpy_kit-0.6.5 → sdpy_kit-0.6.7}/kit/ai/chat_service.py

@@ -18,10 +18,11 @@ Author: Clark Chang
 """
 
 import json
+import threading
 import time
 from collections.abc import AsyncIterator
 from dataclasses import dataclass
-from typing import ClassVar, Final, cast, override
+from typing import Any, ClassVar, Final, cast, override
 
 from kit.ai.base_service import (
     _LOG_PAYLOAD_LIMIT,
@@ -31,6 +32,7 @@ from kit.ai.base_service import (
     safe_get,
 )
 from kit.ai.exceptions import AIError, AIResponseError
+from kit.ai.profiles import _RESERVED_PAYLOAD_KEYS, ModelProfile
 from kit.ai.types import JSONObject
 from kit.config.log_config import get_default_logger
 
@@ -47,6 +49,46 @@ _REASONING_KEYS: Final[tuple[str, ...]] = ("reasoning_content", "reasoning")
 # 截断判定：OpenAI 系给 length，部分兼容端点给 max_tokens
 _TRUNCATED_REASONS: Final[frozenset[str]] = frozenset({"length", "max_tokens"})
 
+# 「无注入值」哨兵：区分「不注入」与「注入值为 None」
+_UNSET: Final[object] = object()
+
+# 思考开关告警去重：同一档案同一原因进程内只报一次（批处理会高频调用）
+_WARNED: set[tuple[str, str]] = set()
+_WARNED_LOCK: Final[threading.Lock] = threading.Lock()
+
+
+def _warn_once(profile_name: str, reason: str) -> None:
+    """线程安全的告警去重：``(档案名, 原因)`` 只报一次。"""
+    key = (profile_name, reason)
+    with _WARNED_LOCK:
+        if key in _WARNED:
+            return
+        _WARNED.add(key)
+    logger.warning(f"思考开关：{reason}（档案 {profile_name}）")
+
+
+def _resolve_thinking(
+    profile: ModelProfile, thinking: bool | None
+) -> tuple[object, bool | None, str | None]:
+    """解析本次调用的思考开关。
+
+    逐调用 ``thinking`` 优先，未传时回落档案 ``thinking.default``（三态）。
+
+    Returns:
+        ``(注入值 | _UNSET, 是否生效, 告警原因)``。是否生效为 None 表示
+        本次未要求干预（请求体不变）；False 表示要求了但档案不支持
+        （不注入、不报错、不影响候选链冷却）。
+    """
+    spec = profile.thinking
+    mode = thinking if thinking is not None else (spec.default if spec else None)
+    if mode is None:
+        return _UNSET, None, None
+    if spec is None:
+        return _UNSET, False, "档案未声明思考开关，本次请求被忽略"
+    if mode and spec.on is None:
+        return _UNSET, False, "档案未声明开启取值，本次请求被忽略"
+    return (spec.off if mode is False else spec.on), True, None
+
 
 @dataclass
 class StreamStats:
@@ -64,11 +106,14 @@ class StreamStats:
         content_chars: 已产出正文字符数（等于调用方收到的字符数）
         finish_reason: 结束原因（stop / length / content_filter / …）；
             provider 未给出时为 None
+        thinking_applied: 思考开关是否生效——None 本次未要求干预 /
+            True 已按档案声明注入 / False 要求了但档案不支持（已忽略）
     """
 
     reasoning_chars: int = 0
     content_chars: int = 0
     finish_reason: str | None = None
+    thinking_applied: bool | None = None
 
     @property
     def truncated(self) -> bool:
@@ -80,6 +125,7 @@ class StreamStats:
         self.reasoning_chars = 0
         self.content_chars = 0
         self.finish_reason = None
+        self.thinking_applied = None
 
 
 @dataclass(frozen=True)
@@ -90,6 +136,8 @@ class ChatRequest:
     temperature: float | None = None
     max_tokens: int | None = None
     stream: bool = False
+    # 思考开关：None 不干预（请求体逐字节不变）/ True 开 / False 关
+    thinking: bool | None = None
 
 
 class ChatService(BaseAIService[ChatRequest, str]):
@@ -116,6 +164,47 @@ class ChatService(BaseAIService[ChatRequest, str]):
             payload["max_tokens"] = max_tokens
         return cast(JSONObject, payload)
 
+    @override
+    def _apply_request_extras(
+        self, payload: JSONObject, request: ChatRequest
+    ) -> JSONObject:
+        """按档案 ``thinking`` 声明注入逐调用思考开关。
+
+        优先级：逐调用 > 档案 ``extra_body``（同键且值不同时告警）。
+        未声明 / 不可显式开启 → 不注入 + 告警（不报错、不触发冷却）。
+        ``_build_payload`` 产出的保留键在运行期兜底拒绝覆盖。
+        """
+        value, applied, reason = _resolve_thinking(self._profile, request.thinking)
+        if applied is False and reason is not None:
+            _warn_once(self._profile.name, reason)
+        if value is _UNSET:
+            return payload
+        spec = self._profile.thinking
+        if spec is None:  # 类型收窄：applied 为 True 时 spec 必非 None
+            return payload
+        if spec.arg in _RESERVED_PAYLOAD_KEYS or spec.arg in self._build_payload(
+            request
+        ):
+            _warn_once(
+                self._profile.name,
+                f"思考开关键 {spec.arg!r} 与请求体保留键冲突，已忽略",
+            )
+            return payload
+        current = payload.get(spec.arg)
+        merged: Any = (
+            {**current, **value}
+            if isinstance(current, dict) and isinstance(value, dict)
+            else value
+        )
+        extra = self._profile.extra_body or {}
+        if spec.arg in extra and extra[spec.arg] != merged:
+            _warn_once(
+                self._profile.name,
+                f"已覆盖档案 extra_body 的同名字段 {spec.arg!r}",
+            )
+        payload[spec.arg] = merged
+        return payload
+
     @override
     def _parse_response(self, data: JSONObject) -> str:
         choice = safe_get(data, "choices", 0)
@@ -137,14 +226,14 @@ class ChatService(BaseAIService[ChatRequest, str]):
                 raise AIResponseError(
                     f"输出预算被思考耗尽：finish_reason={finish}，"
                     f"推理 {reasoning} 字符、正文为空"
-                    "（请调大 max_tokens 或在档案 extra_body 中关闭思考）"
+                    "（请调大 max_tokens，或对该调用传 thinking=False 关闭思考）"
                 )
             raise AIResponseError(f"content 类型异常: {type(content).__name__}")
         if finish in _TRUNCATED_REASONS and (reasoning or not content):
             logger.warning(
                 f"{self._log_desc()} 输出被长度截断（finish_reason={finish}）："
                 f"推理 {reasoning} 字符 / 正文 {len(content)} 字符"
-                "（可调大 max_tokens 或在档案 extra_body 中关闭思考）"
+                "（可调大 max_tokens，或对该调用传 thinking=False 关闭思考）"
             )
         return content
 
@@ -154,15 +243,24 @@ class ChatService(BaseAIService[ChatRequest, str]):
         *,
         temperature: float | None = None,
         max_tokens: int | None = None,
+        thinking: bool | None = None,
         deadline: float | None = None,
     ) -> str:
         """多轮对话，返回模型回答文本。
 
         Args:
+            thinking: 思考开关；None 不干预（按档案 ``thinking.default``，
+                仍未配置则请求体不变）/ True 开 / False 关。档案无声明时
+                忽略并告警（不报错、不触发冷却）
             deadline: 整链预算截止时刻（``time.monotonic()`` 秒），约束
                 5xx 重试预算；None 表示不限制
         """
-        request = ChatRequest(messages, temperature=temperature, max_tokens=max_tokens)
+        request = ChatRequest(
+            messages,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            thinking=thinking,
+        )
         return await self._call(request, deadline=deadline)
 
     async def complete(
@@ -171,11 +269,16 @@ class ChatService(BaseAIService[ChatRequest, str]):
         *,
         temperature: float | None = None,
         max_tokens: int | None = None,
+        thinking: bool | None = None,
         deadline: float | None = None,
     ) -> str:
         messages: list[Message] = [{"role": "user", "content": prompt}]
         return await self.ask(
-            messages, temperature=temperature, max_tokens=max_tokens, deadline=deadline
+            messages,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            thinking=thinking,
+            deadline=deadline,
         )
 
     async def stream(
@@ -184,11 +287,15 @@ class ChatService(BaseAIService[ChatRequest, str]):
         *,
         temperature: float | None = None,
         max_tokens: int | None = None,
+        thinking: bool | None = None,
         stats: StreamStats | None = None,
     ) -> AsyncIterator[str]:
         """流式对话，逐 token 产出正文。
 
         Args:
+            thinking: 思考开关（语义同 :meth:`ask`）；是否真正生效记在
+                ``stats.thinking_applied``（None 未干预 / True 已注入 /
+                False 被忽略）
             stats: 收尾统计累加器（可选）；None 时内部创建后丢弃——需要
                 ``reasoning_chars`` / ``finish_reason`` / ``truncated`` 时
                 由调用方传入一个实例
@@ -197,14 +304,21 @@ class ChatService(BaseAIService[ChatRequest, str]):
         不产出；正文为空且被截断（或发生过思考）时输出 warning。
         """
         request = ChatRequest(
-            messages, temperature=temperature, max_tokens=max_tokens, stream=True
+            messages,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            stream=True,
+            thinking=thinking,
+        )
+        payload = self._apply_request_extras(
+            self._apply_extra_body(self._build_payload(request)), request
         )
-        payload = self._apply_extra_body(self._build_payload(request))
         desc = self._log_desc()
         params = _truncate(
             json.dumps(_clip(payload), ensure_ascii=False), _LOG_PAYLOAD_LIMIT
         )
         stats = stats if stats is not None else StreamStats()
+        stats.thinking_applied = _resolve_thinking(self._profile, request.thinking)[1]
         # 惰性 Start：异步生成器体在首次 __anext__ 前不执行，不消费不打日志
         logger.info(f"********** {desc} ********** Start")
         logger.info(f"请求参数: {params}")
@@ -262,5 +376,5 @@ class ChatService(BaseAIService[ChatRequest, str]):
             f"{self._log_desc()} 输出预算疑被思考耗尽：max_tokens={max_tokens}，"
             f"finish_reason={stats.finish_reason}，"
             f"推理 {stats.reasoning_chars} 字符 / 正文 0 字符"
-            "（可调大 max_tokens 或在档案 extra_body 中关闭思考）"
+            "（可调大 max_tokens，或对该调用传 thinking=False 关闭思考）"
         )

{sdpy_kit-0.6.5 → sdpy_kit-0.6.7}/kit/ai/failover.py

@@ -164,15 +164,21 @@ class FailoverChatService(_FailoverBase):
         *,
         temperature: float | None = None,
         max_tokens: int | None = None,
+        thinking: bool | None = None,
         deadline: float | None = None,
     ) -> str:
-        """多轮对话，返回模型回答文本（链式故障切换）。"""
+        """多轮对话，返回模型回答文本（链式故障切换）。
+
+        ``thinking`` 原样下传：注入发生在 ``ChatService`` 内部，按**当前候选
+        自己**的档案声明组装；无声明时该候选忽略该开关（不因此切候选）。
+        """
 
         async def _run(service: Service) -> str:
             return await cast(ChatService, service).ask(
                 messages,
                 temperature=temperature,
                 max_tokens=max_tokens,
+                thinking=thinking,
                 deadline=deadline,
             )
 
@@ -184,6 +190,7 @@ class FailoverChatService(_FailoverBase):
         *,
         temperature: float | None = None,
         max_tokens: int | None = None,
+        thinking: bool | None = None,
         deadline: float | None = None,
     ) -> str:
         """单轮对话，返回模型回答文本（链式故障切换）。"""
@@ -193,6 +200,7 @@ class FailoverChatService(_FailoverBase):
                 prompt,
                 temperature=temperature,
                 max_tokens=max_tokens,
+                thinking=thinking,
                 deadline=deadline,
             )
 
@@ -204,6 +212,7 @@ class FailoverChatService(_FailoverBase):
         *,
         temperature: float | None = None,
         max_tokens: int | None = None,
+        thinking: bool | None = None,
         first_frame_timeout: float | None = None,
         deadline: float | None = None,
         stats: StreamStats | None = None,
@@ -211,6 +220,7 @@ class FailoverChatService(_FailoverBase):
         """流式对话：首帧前失败自动换档案重试；首帧后失败直接抛出。
 
         Args:
+            thinking: 思考开关；按当前候选自己的档案声明组装，无声明则忽略
             first_frame_timeout: 单候选首帧等待上限（秒）；窗口内**一帧都没有**
                 （含推理帧）才按失败处理切下一候选；None 不限制
             deadline: 整链预算截止时刻；每个候选发起前检查
@@ -232,6 +242,7 @@ class FailoverChatService(_FailoverBase):
                     messages,
                     temperature=temperature,
                     max_tokens=max_tokens,
+                    thinking=thinking,
                     stats=stats,
                 ),
             )

{sdpy_kit-0.6.5 → sdpy_kit-0.6.7}/kit/ai/pool.py

@@ -391,6 +391,7 @@ class AIServicePool:
                     current=name == current,
                     last_error=entry.last_error,
                     last_ok_at=entry.last_ok_at,
+                    thinking_switchable=entry.profile.thinking is not None,
                 )
                 for name, entry in chain.entries.items()
             ]
@@ -406,6 +407,7 @@ class AIServicePool:
                         model=config.model,
                         state=ProfileState.UNCONFIGURED,
                         current=False,
+                        thinking_switchable=config.thinking is not None,
                     )
                 )
         return rows

{sdpy_kit-0.6.5 → sdpy_kit-0.6.7}/kit/ai/profiles.py

@@ -34,10 +34,10 @@ import os
 from dataclasses import dataclass, replace
 from functools import lru_cache
 from pathlib import Path
-from typing import Any, Final
+from typing import Any, Final, Self
 
 from dotenv import load_dotenv
-from pydantic import BaseModel, Field, ValidationError
+from pydantic import BaseModel, Field, ValidationError, field_validator, model_validator
 
 from kit.ai.exceptions import AIConfigError
 from kit.config.kit_config import get_settings
@@ -56,6 +56,34 @@ _MINIMAL_MODELS_JSON: Final[str] = (
 )
 
 
+# 请求体保留键：思考开关声明（档案 thinking.arg）不得占用，配置期与运行期双重校验
+_RESERVED_PAYLOAD_KEYS: Final[frozenset[str]] = frozenset(
+    {"model", "messages", "stream", "input", "prompt", "max_tokens", "temperature"}
+)
+
+
+@dataclass(frozen=True)
+class ThinkingSwitchSpec:
+    """厂商思考开关的注入方式（档案声明；缺失即「不支持切换」）。
+
+    kit 不认识任何厂商字段名，只按本声明组装请求体：
+
+    Attributes:
+        arg: 请求体顶层键名（如 ``thinking`` / ``chat_template_kwargs`` /
+            ``enable_thinking``）；保留键（``model`` / ``messages`` 等）禁用
+        off: 关闭思考时该键的取值，任意 JSON 值。与请求体中同键**都是 dict**
+            时浅合并（保留其它子键），否则整键替换
+        on: 开启思考时的取值；``None`` 表示不能显式开启（如强制思考模型）
+        default: 档案默认策略——``None`` 不干预 / ``False`` 默认关 /
+            ``True`` 默认开。仅在逐调用未传 ``thinking`` 时生效
+    """
+
+    arg: str
+    off: Any
+    on: Any = None
+    default: bool | None = None
+
+
 @dataclass(frozen=True)
 class ModelProfile:
     """单个模型档案（运行时已解析密钥）。
@@ -78,6 +106,8 @@ class ModelProfile:
         extra_body: 档案级额外请求体字段（厂商专有参数透传，如 GLM/Qwen 的
             ``{"thinking": {"type": "disabled"}}``）；与服务构造的同名键
             冲突时**以服务的值为准**（不可覆盖 model / messages / stream 等保留键）
+        thinking: 思考开关的注入声明（逐调用 ``thinking=`` 据此翻译成厂商字段）；
+            None 表示该档案不支持按调用切换思考
     """
 
     name: str
@@ -93,6 +123,7 @@ class ModelProfile:
     dimension: int | None = None
     batch_size: int = 32
     extra_body: dict[str, Any] | None = None
+    thinking: ThinkingSwitchSpec | None = None
 
     @property
     def url(self) -> str:
@@ -122,6 +153,7 @@ class ProfileStatus:
         current: 是否为该类型当前使用项（链头）
         last_error: 最近一次失败原因（无失败为 None）
         last_ok_at: 最近一次成功/探测通过时刻（Unix 秒；从未成功为 None）
+        thinking_switchable: 该档案是否声明了思考开关（可逐调用关/开思考）
     """
 
     name: str
@@ -130,6 +162,49 @@ class ProfileStatus:
     current: bool = False
     last_error: str | None = None
     last_ok_at: float | None = None
+    thinking_switchable: bool = False
+
+
+class ThinkingSwitchSpecModel(BaseModel):
+    """档案 ``thinking`` 字段的原始声明（结构校验，厂商无关）。
+
+    只校验外形（``arg`` 非空且非保留键、``off`` 必须给出），语义正确性
+    由应用侧预设库保证——kit 不认识任何厂商字段名。
+    """
+
+    arg: str = Field(min_length=1)
+    off: Any = None
+    on: Any = None
+    default: bool | None = None
+
+    @field_validator("arg")
+    @classmethod
+    def _validate_arg(cls, value: str) -> str:
+        """``arg`` 不得占用请求体保留键（否则写坏请求骨架）。"""
+        if value in _RESERVED_PAYLOAD_KEYS:
+            raise ValueError(
+                f"thinking.arg 不得使用请求体保留键: {value}"
+                f"（禁用: {', '.join(sorted(_RESERVED_PAYLOAD_KEYS))}）"
+            )
+        return value
+
+    @model_validator(mode="after")
+    def _validate_off(self) -> Self:
+        """``off`` 必须给出关闭取值（缺省与显式 null 都拒绝）。"""
+        if self.off is None:
+            raise ValueError("thinking.off 不得为空（须给出关闭思考时的取值）")
+        return self
+
+
+def _build_thinking_spec(
+    config: ThinkingSwitchSpecModel | None,
+) -> ThinkingSwitchSpec | None:
+    """静态声明 → 运行时 spec（未声明返回 None，表示不支持按调用切换）。"""
+    if config is None:
+        return None
+    return ThinkingSwitchSpec(
+        arg=config.arg, off=config.off, on=config.on, default=config.default
+    )
 
 
 class ProfileConfig(BaseModel):
@@ -151,6 +226,8 @@ class ProfileConfig(BaseModel):
     # 厂商专有请求字段透传（如 {"thinking": {"type": "disabled"}}）；
     # 与服务构造的同名键冲突时以服务的值为准，故保留键无法被覆盖
     extra_body: dict[str, Any] | None = None
+    # 思考开关注入声明：逐调用 thinking= 据此翻译为厂商字段（未声明 = 不支持切换）
+    thinking: ThinkingSwitchSpecModel | None = None
 
 
 class TypeConfig(BaseModel):
@@ -285,6 +362,7 @@ class ModelRegistry:
             dimension=config.dimension,
             batch_size=config.batch_size,
             extra_body=config.extra_body,
+            thinking=_build_thinking_spec(config.thinking),
         )
 
     def get_profile(self, model_type: str, profile: str | None = None) -> ProfileConfig:

{sdpy_kit-0.6.5 → sdpy_kit-0.6.7}/kit/ai/runner.py

@@ -319,11 +319,14 @@ class _BackgroundLoop:
         q: queue.Queue[object],
         *,
         max_tokens: int | None = None,
+        thinking: bool | None = None,
         stats: StreamStats,
     ) -> concurrent.futures.Future[None]:
         """投递流式收集任务：后台拉取链式 ``stream`` 帧写入线程安全队列。
 
         Args:
+            thinking: 思考开关（None 不干预）；
+                结果记在 ``stats.thinking_applied``
             stats: 收尾统计累加器（由同步侧持有并读取）
 
         返回的 future 可取消，用于同步侧中断时停止后台拉取。
@@ -338,6 +341,7 @@ class _BackgroundLoop:
                 async for delta in service.stream(
                     messages,
                     max_tokens=max_tokens,
+                    thinking=thinking,
                     first_frame_timeout=_STREAM_FIRST_FRAME_TIMEOUT,
                     stats=stats,
                 ):
@@ -472,21 +476,30 @@ async def _chat_ask(
     messages: list[dict[str, str]],
     *,
     max_tokens: int | None = None,
+    thinking: bool | None = None,
     deadline: float | None = None,
 ) -> str:
     service: FailoverChatService = cast(
         FailoverChatService, await _background._get_service(_CHAT)  # noqa: SLF001
     )
-    return await service.ask(messages, max_tokens=max_tokens, deadline=deadline)
+    return await service.ask(
+        messages, max_tokens=max_tokens, thinking=thinking, deadline=deadline
+    )
 
 
 async def _chat_complete(
-    prompt: str, *, max_tokens: int | None = None, deadline: float | None = None
+    prompt: str,
+    *,
+    max_tokens: int | None = None,
+    thinking: bool | None = None,
+    deadline: float | None = None,
 ) -> str:
     service: FailoverChatService = cast(
         FailoverChatService, await _background._get_service(_CHAT)  # noqa: SLF001
     )
-    return await service.complete(prompt, max_tokens=max_tokens, deadline=deadline)
+    return await service.complete(
+        prompt, max_tokens=max_tokens, thinking=thinking, deadline=deadline
+    )
 
 
 async def _embed_texts(
@@ -534,34 +547,47 @@ class AI:
     """kit/ai 同步门面：在同步上下文调用异步 AI 服务（候选链故障切换）。"""
 
     @staticmethod
-    def chat_complete(prompt: str, *, max_tokens: int | None = None) -> str:
+    def chat_complete(
+        prompt: str, *, max_tokens: int | None = None, thinking: bool | None = None
+    ) -> str:
         """单轮对话（仅 user 消息），返回模型回答文本。
 
         Args:
             max_tokens: 输出上限；None 时回落档案 ``max_tokens`` 配置，
                 仍未配置则由 provider 默认值决定
+            thinking: 思考开关；None 不干预（按档案 ``thinking.default``，
+                未配置则请求体不变）/ True 开 / False 关。档案未声明该能力时
+                忽略并告警（不报错、不影响故障切换）
         """
         timeout = _facade_timeout(_CHAT)
         deadline = time.monotonic() + timeout
         return _background.run(
-            lambda: _chat_complete(prompt, max_tokens=max_tokens, deadline=deadline),
+            lambda: _chat_complete(
+                prompt, max_tokens=max_tokens, thinking=thinking, deadline=deadline
+            ),
             timeout=timeout,
         )
 
     @staticmethod
     def chat_ask(
-        messages: list[dict[str, str]], *, max_tokens: int | None = None
+        messages: list[dict[str, str]],
+        *,
+        max_tokens: int | None = None,
+        thinking: bool | None = None,
     ) -> str:
         """多轮对话（自组装 messages），返回模型回答文本。
 
         Args:
             max_tokens: 输出上限；None 时回落档案 ``max_tokens`` 配置，
                 仍未配置则由 provider 默认值决定
+            thinking: 思考开关；语义同 :meth:`chat_complete`
         """
         timeout = _facade_timeout(_CHAT)
         deadline = time.monotonic() + timeout
         return _background.run(
-            lambda: _chat_ask(messages, max_tokens=max_tokens, deadline=deadline),
+            lambda: _chat_ask(
+                messages, max_tokens=max_tokens, thinking=thinking, deadline=deadline
+            ),
             timeout=timeout,
         )
 
@@ -667,11 +693,19 @@ class AI:
         messages: list[dict[str, str]],
         *,
         max_tokens: int | None = None,
+        thinking: bool | None = None,
     ) -> Iterator[str]:
         """多轮对话（流式），返回逐 token 迭代器（同步）。
 
         在同步线程内逐帧消费，适合流式输出；内部在后台 loop 持续拉取
-        并放入线程安全队列。超时保护：
+        并放入线程安全队列。
+
+        Args:
+            thinking: 思考开关；None 不干预（按档案 ``thinking.default``）/
+                True 开 / False 关。是否真正生效读 ``stream.thinking_applied``
+                （None 未干预 / True 已注入 / False 被忽略）
+
+        超时保护：
             - 首帧前：每候选 ``_STREAM_FIRST_FRAME_TIMEOUT``（60s）内**一帧
               都没有**（含推理帧）则切下一候选，全部候选耗尽抛
               ``AITimeoutError``；思考型模型的推理帧算活动、会重置窗口；
@@ -687,14 +721,15 @@ class AI:
                         break
 
         流结束后可读 ``reasoning_chars`` / ``content_chars`` / ``finish_reason`` /
-        ``truncated``，用于区分「模型没返回内容」与「输出预算被思考吃光」::
+        ``truncated`` / ``thinking_applied``，用于区分「模型没返回内容」与
+        「输出预算被思考吃光」，以及确认思考开关是否真的生效::
 
             with AI.chat_stream(messages, max_tokens=450) as stream:
                 body = "".join(stream)
             if not body and stream.truncated and stream.reasoning_chars:
-                ...  # 推理吃光预算：调大 max_tokens 或关闭思考
+                ...  # 推理吃光预算：调大 max_tokens 或传 thinking=False
         """
-        return _StreamIterator(messages, max_tokens=max_tokens)
+        return _StreamIterator(messages, max_tokens=max_tokens, thinking=thinking)
 
 
 class _StreamIterator:
@@ -710,15 +745,21 @@ class _StreamIterator:
     兜底取消后台 producer，避免任务残留。
 
     流结束后可读 ``reasoning_chars`` / ``content_chars`` / ``finish_reason`` /
-    ``truncated`` 四个只读属性（跨线程共享同一累加器：结束后为最终值，
-    流式过程中为尽力而为的中间值；提前 ``break`` 时为截至中断的累计值）。
+    ``truncated`` / ``thinking_applied`` 五个只读属性（跨线程共享同一累加器：
+    结束后为最终值，流式过程中为尽力而为的中间值；提前 ``break`` 时为截至
+    中断的累计值）。
     """
 
     def __init__(
-        self, messages: list[dict[str, str]], *, max_tokens: int | None = None
+        self,
+        messages: list[dict[str, str]],
+        *,
+        max_tokens: int | None = None,
+        thinking: bool | None = None,
     ) -> None:
         self._messages: list[dict[str, str]] = messages
         self._max_tokens: int | None = max_tokens
+        self._thinking: bool | None = thinking
         self._q: queue.Queue[object] = queue.Queue()
         self._stats: StreamStats = StreamStats()
         self._started = False
@@ -736,6 +777,7 @@ class _StreamIterator:
                 self._messages,
                 self._q,
                 max_tokens=self._max_tokens,
+                thinking=self._thinking,
                 stats=self._stats,
             )
 
@@ -811,6 +853,11 @@ class _StreamIterator:
         """是否因输出长度上限被截断（``finish_reason`` 为 length / max_tokens）。"""
         return self._stats.truncated
 
+    @property
+    def thinking_applied(self) -> bool | None:
+        """思考开关是否生效：None 未要求干预 / True 已注入 / False 被忽略。"""
+        return self._stats.thinking_applied
+
 
 async def _delayed_close(services: list[Service]) -> None:
     """延迟回收旧 service：给在途调用留宽限期，到期统一关闭（须在 loop 内）。"""