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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sdpy-kit
-Version: 0.6.3
+Version: 0.6.5
 Summary: SDPY Kit——统一数据库访问层（PG/MySQL/SQLite）与 AI/Redis/文件/文档/向量工具集
 Author-email: Clark <changhongyuan@126.com>
 License-Expression: MIT
@@ -98,7 +98,7 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 | `kit.docs.anydoc_kit` | `AnyDocKit` | docx / pdf / xlsx 等 → Markdown | `anydoc` |
 | `kit.docs.docx_kit` | `DocxKit` | Word 模板动态填充（章节 / 列表 / 表格） | `docx` |
 | `kit.docs.rc_docparser_kit` | `RcDocParserKit` | 离线 docx → Markdown + Images（无模型） | `docx-parse` |
-| `kit.docs.md2doc_kit` | `Md2DocKit` | Markdown → Word / PDF / HTML | `md2doc` |
+| `kit.docs.md2doc_kit` | `Md2DocKit` | Markdown → Word / PDF / HTML（含图片） | `md2doc` |
 | `kit.docs.mineru_kit` | `MinerUKit` | MinerU 文档解析（精准 + Agent 轻量） | `mineru` |
 | `kit.docs.marker_kit` | `MarkerKit` | 本地解析（PDF / 图片 → Markdown + Images） | `marker` |
 | `kit.laya_kit` | `LayaKit` | 类型化决策：choice / score / noul，返回判断结果 + 置信度 | `laya` |
@@ -125,7 +125,7 @@ uv add sdpy-kit
 | `sqliteai` | SQLiteKit 向量方法（numpy / sqliteai-vector，SQLite 向量扩展） | `pip install "sdpy-kit[sqliteai]"` |
 | `redis` | RedisKit | `pip install "sdpy-kit[redis]"` |
 | `ai` | AI 服务池（httpx + python-dotenv） | `pip install "sdpy-kit[ai]"` |
-| `md2doc` | Md2DocKit：Markdown → Word / PDF / HTML（pimd / fpdf2） | `pip install "sdpy-kit[md2doc]"` |
+| `md2doc` | Md2DocKit：Markdown → Word / PDF / HTML（pimd / fpdf2，含图片） | `pip install "sdpy-kit[md2doc]"` |
 | `anydoc` | AnyDocKit 文档转 Markdown（firecrawl-anydoc + pikepdf） | `pip install "sdpy-kit[anydoc]"` |
 | `docx` | DocxKit 模板动态填充（docxtpl） | `pip install "sdpy-kit[docx]"` |
 | `docx-parse` | RcDocParserKit 离线 docx 解析（rc-docparser → Markdown + images/） | `pip install "sdpy-kit[docx-parse]"` |
@@ -785,7 +785,7 @@ 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` 使用） |
+| chat | `chat_stream(messages, *, max_tokens=None) -> Iterator[str]` | 同步流式逐 token 迭代器（建议 `with` 使用）；结束后可读 `reasoning_chars` / `content_chars` / `finish_reason` / `truncated` |
 | embedding | `embed_text(text) -> list[float]` | 单文本向量化 |
 | embedding | `embed_texts(texts) -> list[list[float]]` | 批量向量化 |
 | rerank | `rerank(query, documents, top_n=None) -> list[tuple[int, float]]` | 返回 `[(原索引, 相关分)]` 降序列表 |
@@ -802,6 +802,32 @@ with AI.chat_stream([{"role": "user", "content": "写一首短诗"}]) as stream:
         print(token, end="", flush=True)
 ```
 
+#### 流式收尾统计（思考型模型必备）
+
+迭代器在流结束后可读四个只读属性（`reasoning_chars` / `content_chars` / `finish_reason` /
+`truncated`），用于区分「模型真的没返回」与「输出预算被思考吃光」——思考型模型的推理
+token 计入 `max_tokens`，长上下文 + 小预算时常出现「返回 200 但正文为空」：
+
+```python
+with AI.chat_stream(messages, max_tokens=450) as stream:
+    body = "".join(stream)
+if not body and stream.truncated and stream.reasoning_chars:
+    raise ValueError(
+        f"输出预算被思考消耗（推理 {stream.reasoning_chars} 字符），"
+        "请调大 max_tokens 或改用关闭思考的档案"
+    )
+```
+
+- 推理字段兼容 `delta.reasoning_content`（GLM / DeepSeek / Qwen）与 `delta.reasoning`（sensenova）：只计数不产出；
+- 正文为空且（被截断或发生过思考）时 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` 时为截至中断的累计值。
+
+> 首帧等待语义：每候选 60 秒内**一帧都没有**（含推理帧）才切下一候选；思考阶段的
+> 推理帧算活动并重置窗口，不会误判健康模型失败、也不会重放整段 prompt。
+
 > 门面仅面向**同步上下文**；若调用点本身在 async 函数内，请直接 `await` 原生异步服务，避免阻塞事件循环线程。
 > 模块级另有 `kit.ai.runner.reload_config(...)`、`run_sync(coro_factory, *, timeout=120.0)`、`shutdown()`。
 
@@ -811,7 +837,7 @@ with AI.chat_stream([{"role": "user", "content": "写一首短诗"}]) as stream:
 from kit.ai import (
     ChatService, EmbeddingService, RerankService, ImageService,   # 服务类
     ChatRequest, EmbeddingRequest, RerankRequest, ImageRequest,   # 请求模型
-    RerankHit, ModelBuilder,                                      # 结果类型 / 构建器
+    RerankHit, StreamStats, ModelBuilder,                         # 结果类型 / 构建器
 )
 
 service = ModelBuilder.build_chat()                 # 老按类型构建：build_chat / build_embedding / build_rerank / build_image
@@ -821,7 +847,7 @@ await service.close()
 
 | 类 | 方法 |
 |----|------|
-| `ChatService` | `ask(messages, *, temperature=None, max_tokens=None, deadline=None) -> str`、`complete(prompt, *, ...) -> str`、`stream(messages, *, ...) -> AsyncIterator[str]` |
+| `ChatService` | `ask(messages, *, temperature=None, max_tokens=None, deadline=None) -> str`、`complete(prompt, *, ...) -> str`、`stream(messages, *, ..., stats: StreamStats | None = None) -> AsyncIterator[str]`（传 `StreamStats()` 即可读收尾统计） |
 | `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` |
@@ -1076,12 +1102,18 @@ Md2DocKit.convert_md_to_pdf("report.md", mainfont="KaiTi")
 
 | 方法 | 说明 |
 |------|------|
-| `convert_md_to_docx(src_path, dest_path=None, *, generate_toc=False, mainfont="宋体", reference_doc=None) -> str` | Markdown → Word（可插目录、统一字体） |
-| `convert_md_to_html(src_path, dest_path=None, *, title=None) -> str` | Markdown → 独立 HTML5 文件 |
-| `convert_md_to_pdf(src_path, dest_path=None, *, mainfont="SimSun") -> str` | Markdown → PDF（实验性，内部使用） |
+| `convert_md_to_docx(src_path, dest_path=None, *, generate_toc=False, mainfont="宋体", reference_doc=None) -> str` | Markdown → Word（可插目录、统一字体、图片内嵌） |
+| `convert_md_to_html(src_path, dest_path=None, *, title=None) -> str` | Markdown → 独立 HTML5 文件（图片输出 `<figure><img>`） |
+| `convert_md_to_pdf(src_path, dest_path=None, *, mainfont="SimSun") -> str` | Markdown → PDF（实验性，内部使用；图片等比限宽居中） |
 
 > `dest_path=None` 时输出到源文件同目录；同一源文件不支持并发转换。
 
+**图片**：`![alt](相对路径)` 以 Markdown 源文件所在目录为基准解析，宽度等比限幅
+（96dpi 还原自然尺寸、不放大），超高先分页/按版心收紧；缺图、越界路径、非图片
+格式一律回落 `alt` 文本，不抛异常。远程地址在 PDF / Word 中不下载（回落 alt），
+在 HTML 中直出 `<img src="https://…">` 交给浏览器。HTML 输出保留相对路径，需与
+`images/` 目录保持同层级才能在浏览器中显示。
+
 ---
 
 ## kit.docs.mineru_kit —— MinerU 文档解析
@@ -1348,6 +1380,7 @@ 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)` 生效 |
 | 类型级 | `chain_timeout` | 整链预算秒数（与 `default_profile` 同级）；门面同步等待上限。未配置时按 `sum(候选 timeout) + 10s` 自适应，也可用环境变量 `KIT_AI_CHAIN_TIMEOUT` 全局覆盖 |
 
 ### 候选链切换语义（两类，勿混淆）

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

@@ -22,7 +22,7 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 | `kit.docs.anydoc_kit` | `AnyDocKit` | docx / pdf / xlsx 等 → Markdown | `anydoc` |
 | `kit.docs.docx_kit` | `DocxKit` | Word 模板动态填充（章节 / 列表 / 表格） | `docx` |
 | `kit.docs.rc_docparser_kit` | `RcDocParserKit` | 离线 docx → Markdown + Images（无模型） | `docx-parse` |
-| `kit.docs.md2doc_kit` | `Md2DocKit` | Markdown → Word / PDF / HTML | `md2doc` |
+| `kit.docs.md2doc_kit` | `Md2DocKit` | Markdown → Word / PDF / HTML（含图片） | `md2doc` |
 | `kit.docs.mineru_kit` | `MinerUKit` | MinerU 文档解析（精准 + Agent 轻量） | `mineru` |
 | `kit.docs.marker_kit` | `MarkerKit` | 本地解析（PDF / 图片 → Markdown + Images） | `marker` |
 | `kit.laya_kit` | `LayaKit` | 类型化决策：choice / score / noul，返回判断结果 + 置信度 | `laya` |
@@ -49,7 +49,7 @@ uv add sdpy-kit
 | `sqliteai` | SQLiteKit 向量方法（numpy / sqliteai-vector，SQLite 向量扩展） | `pip install "sdpy-kit[sqliteai]"` |
 | `redis` | RedisKit | `pip install "sdpy-kit[redis]"` |
 | `ai` | AI 服务池（httpx + python-dotenv） | `pip install "sdpy-kit[ai]"` |
-| `md2doc` | Md2DocKit：Markdown → Word / PDF / HTML（pimd / fpdf2） | `pip install "sdpy-kit[md2doc]"` |
+| `md2doc` | Md2DocKit：Markdown → Word / PDF / HTML（pimd / fpdf2，含图片） | `pip install "sdpy-kit[md2doc]"` |
 | `anydoc` | AnyDocKit 文档转 Markdown（firecrawl-anydoc + pikepdf） | `pip install "sdpy-kit[anydoc]"` |
 | `docx` | DocxKit 模板动态填充（docxtpl） | `pip install "sdpy-kit[docx]"` |
 | `docx-parse` | RcDocParserKit 离线 docx 解析（rc-docparser → Markdown + images/） | `pip install "sdpy-kit[docx-parse]"` |
@@ -709,7 +709,7 @@ 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` 使用） |
+| chat | `chat_stream(messages, *, max_tokens=None) -> Iterator[str]` | 同步流式逐 token 迭代器（建议 `with` 使用）；结束后可读 `reasoning_chars` / `content_chars` / `finish_reason` / `truncated` |
 | embedding | `embed_text(text) -> list[float]` | 单文本向量化 |
 | embedding | `embed_texts(texts) -> list[list[float]]` | 批量向量化 |
 | rerank | `rerank(query, documents, top_n=None) -> list[tuple[int, float]]` | 返回 `[(原索引, 相关分)]` 降序列表 |
@@ -726,6 +726,32 @@ with AI.chat_stream([{"role": "user", "content": "写一首短诗"}]) as stream:
         print(token, end="", flush=True)
 ```
 
+#### 流式收尾统计（思考型模型必备）
+
+迭代器在流结束后可读四个只读属性（`reasoning_chars` / `content_chars` / `finish_reason` /
+`truncated`），用于区分「模型真的没返回」与「输出预算被思考吃光」——思考型模型的推理
+token 计入 `max_tokens`，长上下文 + 小预算时常出现「返回 200 但正文为空」：
+
+```python
+with AI.chat_stream(messages, max_tokens=450) as stream:
+    body = "".join(stream)
+if not body and stream.truncated and stream.reasoning_chars:
+    raise ValueError(
+        f"输出预算被思考消耗（推理 {stream.reasoning_chars} 字符），"
+        "请调大 max_tokens 或改用关闭思考的档案"
+    )
+```
+
+- 推理字段兼容 `delta.reasoning_content`（GLM / DeepSeek / Qwen）与 `delta.reasoning`（sensenova）：只计数不产出；
+- 正文为空且（被截断或发生过思考）时 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` 时为截至中断的累计值。
+
+> 首帧等待语义：每候选 60 秒内**一帧都没有**（含推理帧）才切下一候选；思考阶段的
+> 推理帧算活动并重置窗口，不会误判健康模型失败、也不会重放整段 prompt。
+
 > 门面仅面向**同步上下文**；若调用点本身在 async 函数内，请直接 `await` 原生异步服务，避免阻塞事件循环线程。
 > 模块级另有 `kit.ai.runner.reload_config(...)`、`run_sync(coro_factory, *, timeout=120.0)`、`shutdown()`。
 
@@ -735,7 +761,7 @@ with AI.chat_stream([{"role": "user", "content": "写一首短诗"}]) as stream:
 from kit.ai import (
     ChatService, EmbeddingService, RerankService, ImageService,   # 服务类
     ChatRequest, EmbeddingRequest, RerankRequest, ImageRequest,   # 请求模型
-    RerankHit, ModelBuilder,                                      # 结果类型 / 构建器
+    RerankHit, StreamStats, ModelBuilder,                         # 结果类型 / 构建器
 )
 
 service = ModelBuilder.build_chat()                 # 老按类型构建：build_chat / build_embedding / build_rerank / build_image
@@ -745,7 +771,7 @@ await service.close()
 
 | 类 | 方法 |
 |----|------|
-| `ChatService` | `ask(messages, *, temperature=None, max_tokens=None, deadline=None) -> str`、`complete(prompt, *, ...) -> str`、`stream(messages, *, ...) -> AsyncIterator[str]` |
+| `ChatService` | `ask(messages, *, temperature=None, max_tokens=None, deadline=None) -> str`、`complete(prompt, *, ...) -> str`、`stream(messages, *, ..., stats: StreamStats | None = None) -> AsyncIterator[str]`（传 `StreamStats()` 即可读收尾统计） |
 | `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` |
@@ -1000,12 +1026,18 @@ Md2DocKit.convert_md_to_pdf("report.md", mainfont="KaiTi")
 
 | 方法 | 说明 |
 |------|------|
-| `convert_md_to_docx(src_path, dest_path=None, *, generate_toc=False, mainfont="宋体", reference_doc=None) -> str` | Markdown → Word（可插目录、统一字体） |
-| `convert_md_to_html(src_path, dest_path=None, *, title=None) -> str` | Markdown → 独立 HTML5 文件 |
-| `convert_md_to_pdf(src_path, dest_path=None, *, mainfont="SimSun") -> str` | Markdown → PDF（实验性，内部使用） |
+| `convert_md_to_docx(src_path, dest_path=None, *, generate_toc=False, mainfont="宋体", reference_doc=None) -> str` | Markdown → Word（可插目录、统一字体、图片内嵌） |
+| `convert_md_to_html(src_path, dest_path=None, *, title=None) -> str` | Markdown → 独立 HTML5 文件（图片输出 `<figure><img>`） |
+| `convert_md_to_pdf(src_path, dest_path=None, *, mainfont="SimSun") -> str` | Markdown → PDF（实验性，内部使用；图片等比限宽居中） |
 
 > `dest_path=None` 时输出到源文件同目录；同一源文件不支持并发转换。
 
+**图片**：`![alt](相对路径)` 以 Markdown 源文件所在目录为基准解析，宽度等比限幅
+（96dpi 还原自然尺寸、不放大），超高先分页/按版心收紧；缺图、越界路径、非图片
+格式一律回落 `alt` 文本，不抛异常。远程地址在 PDF / Word 中不下载（回落 alt），
+在 HTML 中直出 `<img src="https://…">` 交给浏览器。HTML 输出保留相对路径，需与
+`images/` 目录保持同层级才能在浏览器中显示。
+
 ---
 
 ## kit.docs.mineru_kit —— MinerU 文档解析
@@ -1272,6 +1304,7 @@ 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)` 生效 |
 | 类型级 | `chain_timeout` | 整链预算秒数（与 `default_profile` 同级）；门面同步等待上限。未配置时按 `sum(候选 timeout) + 10s` 自适应，也可用环境变量 `KIT_AI_CHAIN_TIMEOUT` 全局覆盖 |
 
 ### 候选链切换语义（两类，勿混淆）

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

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

{sdpy_kit-0.6.3 → sdpy_kit-0.6.5}/kit/ai/__init__.py

@@ -27,7 +27,7 @@ Author: Clark Chang
 - ImageService: 文生图
 """
 
-from kit.ai.chat_service import ChatRequest, ChatService
+from kit.ai.chat_service import ChatRequest, ChatService, StreamStats
 from kit.ai.embedding_service import EmbeddingRequest, EmbeddingService
 from kit.ai.image_service import ImageRequest, ImageService
 from kit.ai.model_builder import ModelBuilder
@@ -44,4 +44,5 @@ __all__ = [
     "RerankHit",
     "RerankRequest",
     "RerankService",
+    "StreamStats",
 ]

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

@@ -20,7 +20,7 @@ Author: Clark Chang
 import json
 import time
 from abc import ABC, abstractmethod
-from typing import ClassVar, Final, Self, override
+from typing import ClassVar, Final, Self, cast, override
 
 from kit.ai.exceptions import AIError, AIResponseError
 from kit.ai.model_client import ModelClient
@@ -109,6 +109,19 @@ class BaseAIService[RequestT, ResponseT](ABC):
     def _build_payload(self, request: RequestT) -> JSONObject:
         """将请求模型构造为 JSON 请求体。"""
 
+    def _apply_extra_body(self, payload: JSONObject) -> JSONObject:
+        """合并档案级 ``extra_body``（厂商专有请求字段透传）。
+
+        同名键以服务构造的值为准——``model`` / ``messages`` / ``stream`` /
+        ``input`` / ``prompt`` 等保留键**不可被档案覆盖**，故无需白名单；
+        未配置时原样返回（请求体逐字节不变）。
+        """
+        extra = self._profile.extra_body
+        if not extra:
+            return payload
+        merged: dict[str, object] = {**extra, **payload}
+        return cast(JSONObject, merged)
+
     @abstractmethod
     def _parse_response(self, data: JSONObject) -> ResponseT:
         """将 JSON 响应体解析为业务结果。"""
@@ -124,7 +137,7 @@ class BaseAIService[RequestT, ResponseT](ABC):
                 ``post_json`` 的重试预算检查；None 表示不限制
         """
         desc = self._log_desc()
-        payload = self._build_payload(request)
+        payload = self._apply_extra_body(self._build_payload(request))
         params = _truncate(
             json.dumps(_clip(payload), ensure_ascii=False), _LOG_PAYLOAD_LIMIT
         )

sdpy_kit-0.6.5/kit/ai/chat_service.py

@@ -0,0 +1,266 @@
+"""
+Copyright (c) 2021-2026 Clark Chang. All Rights Reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+Project: sdpy
+Author: Clark Chang
+"""
+
+import json
+import time
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+from typing import ClassVar, Final, cast, override
+
+from kit.ai.base_service import (
+    _LOG_PAYLOAD_LIMIT,
+    BaseAIService,
+    _clip,
+    _truncate,
+    safe_get,
+)
+from kit.ai.exceptions import AIError, AIResponseError
+from kit.ai.types import JSONObject
+from kit.config.log_config import get_default_logger
+
+__all__ = ["ChatRequest", "ChatService", "StreamStats"]
+
+logger = get_default_logger(__name__)
+
+Message = dict[str, str]
+
+# 推理（思考）内容可能的字段名：GLM / DeepSeek / Qwen 用 reasoning_content，
+# sensenova 用 reasoning（流式为 delta.*，非流式为 message.*）
+_REASONING_KEYS: Final[tuple[str, ...]] = ("reasoning_content", "reasoning")
+
+# 截断判定：OpenAI 系给 length，部分兼容端点给 max_tokens
+_TRUNCATED_REASONS: Final[frozenset[str]] = frozenset({"length", "max_tokens"})
+
+
+@dataclass
+class StreamStats:
+    """对话收尾统计（可变累加器：调用方传入，kit 累加）。
+
+    跨线程共享（后台事件循环写、业务线程读）：**流结束后为最终值**，
+    流式过程中读到的是尽力而为的中间值。
+
+    ``reasoning_chars`` / ``content_chars`` 均为**字符数**，与 ``max_tokens``
+    （token）不可换算（实测中文约 2~2.5 字符/token，且各 provider 口径不一），
+    仅用于「是否发生思考 / 是否被长度截断」的判定。
+
+    Attributes:
+        reasoning_chars: 推理（思考）内容字符数；非思考模型恒为 0
+        content_chars: 已产出正文字符数（等于调用方收到的字符数）
+        finish_reason: 结束原因（stop / length / content_filter / …）；
+            provider 未给出时为 None
+    """
+
+    reasoning_chars: int = 0
+    content_chars: int = 0
+    finish_reason: str | None = None
+
+    @property
+    def truncated(self) -> bool:
+        """是否因输出长度上限被截断。"""
+        return self.finish_reason in _TRUNCATED_REASONS
+
+    def reset(self) -> None:
+        """清零（候选链切换到下一个档案前调用）。"""
+        self.reasoning_chars = 0
+        self.content_chars = 0
+        self.finish_reason = None
+
+
+@dataclass(frozen=True)
+class ChatRequest:
+    """对话请求模型。"""
+
+    messages: list[Message]
+    temperature: float | None = None
+    max_tokens: int | None = None
+    stream: bool = False
+
+
+class ChatService(BaseAIService[ChatRequest, str]):
+    """对话类模型服务（全异步）。"""
+
+    _LABEL: ClassVar[str] = "对话模型"
+
+    @override
+    def _build_payload(self, request: ChatRequest) -> JSONObject:
+        payload: dict[str, object] = {
+            "model": self._profile.model,
+            "messages": request.messages,
+            "stream": request.stream,
+        }
+        if request.temperature is not None:
+            payload["temperature"] = request.temperature
+        # max_tokens 逐级回落：调用点显式传入 → 档案配置 → 不写（provider 默认）
+        max_tokens = (
+            request.max_tokens
+            if request.max_tokens is not None
+            else self._profile.max_tokens
+        )
+        if max_tokens is not None:
+            payload["max_tokens"] = max_tokens
+        return cast(JSONObject, payload)
+
+    @override
+    def _parse_response(self, data: JSONObject) -> str:
+        choice = safe_get(data, "choices", 0)
+        if not isinstance(choice, dict):
+            raise AIResponseError(f"choices[0] 类型异常: {type(choice).__name__}")
+        message = choice.get("message")
+        content = message.get("content") if isinstance(message, dict) else None
+        finish = choice.get("finish_reason")
+        reasoning = 0
+        if isinstance(message, dict):
+            for key in _REASONING_KEYS:
+                part = message.get(key)
+                if isinstance(part, str) and part:
+                    reasoning = len(part)
+                    break
+        if not isinstance(content, str):
+            if finish in _TRUNCATED_REASONS and reasoning:
+                # 思考型模型截断时可能完全不返回 content 键（实测 sensenova）
+                raise AIResponseError(
+                    f"输出预算被思考耗尽：finish_reason={finish}，"
+                    f"推理 {reasoning} 字符、正文为空"
+                    "（请调大 max_tokens 或在档案 extra_body 中关闭思考）"
+                )
+            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 中关闭思考）"
+            )
+        return content
+
+    async def ask(
+        self,
+        messages: list[Message],
+        *,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+        deadline: float | None = None,
+    ) -> str:
+        """多轮对话，返回模型回答文本。
+
+        Args:
+            deadline: 整链预算截止时刻（``time.monotonic()`` 秒），约束
+                5xx 重试预算；None 表示不限制
+        """
+        request = ChatRequest(messages, temperature=temperature, max_tokens=max_tokens)
+        return await self._call(request, deadline=deadline)
+
+    async def complete(
+        self,
+        prompt: str,
+        *,
+        temperature: float | None = None,
+        max_tokens: int | 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
+        )
+
+    async def stream(
+        self,
+        messages: list[Message],
+        *,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+        stats: StreamStats | None = None,
+    ) -> AsyncIterator[str]:
+        """流式对话，逐 token 产出正文。
+
+        Args:
+            stats: 收尾统计累加器（可选）；None 时内部创建后丢弃——需要
+                ``reasoning_chars`` / ``finish_reason`` / ``truncated`` 时
+                由调用方传入一个实例
+
+        推理内容（``delta.reasoning_content`` / ``delta.reasoning``）只计数
+        不产出；正文为空且被截断（或发生过思考）时输出 warning。
+        """
+        request = ChatRequest(
+            messages, temperature=temperature, max_tokens=max_tokens, stream=True
+        )
+        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()
+        # 惰性 Start：异步生成器体在首次 __anext__ 前不执行，不消费不打日志
+        logger.info(f"********** {desc} ********** Start")
+        logger.info(f"请求参数: {params}")
+        start = time.perf_counter()
+        note = ""
+        failed = False
+        try:
+            async for parsed in self._client.stream_json(payload):
+                if parsed is None:
+                    continue
+                choices = parsed.get("choices")
+                if not isinstance(choices, list) or not choices:
+                    continue
+                choice = choices[0]
+                if not isinstance(choice, dict):
+                    continue
+                finish = choice.get("finish_reason")
+                if isinstance(finish, str) and finish:
+                    stats.finish_reason = finish
+                delta = choice.get("delta")
+                if not isinstance(delta, dict):
+                    continue
+                for key in _REASONING_KEYS:
+                    part = delta.get(key)
+                    if isinstance(part, str) and part:
+                        stats.reasoning_chars += len(part)
+                        break
+                content = delta.get("content")
+                if isinstance(content, str) and content:
+                    stats.content_chars += len(content)
+                    yield content
+        except AIError as exc:
+            note = f"（失败：{exc}）"
+            failed = True
+            raise
+        except BaseException:  # noqa: BLE001 - 中断路径（提前 break/取消）也需收尾日志
+            note = "（中断）"
+            raise
+        else:
+            self._warn_if_budget_eaten(stats, payload.get("max_tokens"))
+        finally:
+            log = logger.error if failed else logger.info
+            log(
+                f"********** {desc} ********** "
+                f"耗时 {time.perf_counter() - start:.1f}秒{note}"
+            )
+
+    def _warn_if_budget_eaten(
+        self, stats: StreamStats, max_tokens: object
+    ) -> None:
+        """正文为空且（被截断或有推理）时告警：讲清「预算被思考吃掉」。"""
+        if stats.content_chars or not (stats.truncated or stats.reasoning_chars):
+            return
+        logger.warning(
+            f"{self._log_desc()} 输出预算疑被思考耗尽：max_tokens={max_tokens}，"
+            f"finish_reason={stats.finish_reason}，"
+            f"推理 {stats.reasoning_chars} 字符 / 正文 0 字符"
+            "（可调大 max_tokens 或在档案 extra_body 中关闭思考）"
+        )