sdpy-kit 0.7.0__tar.gz → 0.7.2__tar.gz

{sdpy_kit-0.7.0 → sdpy_kit-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sdpy-kit
-Version: 0.7.0
+Version: 0.7.2
 Summary: SDPY Kit——统一数据库访问层（PG/MySQL/SQLite）与 AI/Redis/文件/文档/向量工具集
 Author-email: Clark <changhongyuan@126.com>
 License-Expression: MIT
@@ -86,7 +86,7 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 
 - **统一数据库访问层**：PostgreSQL / MySQL / SQLite，三个 Kit API 完全一致，切换数据库只改一行 import；内置审计字段自动填充（`created_*` / `updated_*` / `deleted`）与软删除查询过滤；
 - **AI 多模型服务池**：chat / embedding / rerank / image 四类能力，多厂商候选链 + 故障自动转移；
-- **工具集**：Redis / 文件 / 雪花 ID / 离线授权签发与校验 / 文档互转 / Word 模板填充 / MinerU 解析 / Marker 本地解析（PDF + 图片 → md + images/） / 离线 docx 解析（md + images/） / Laya 类型化决策 / Decima 决策模型（选项乱序不变、置信度可门控） / 微信公众号文章抓取存储 / 通用网页文章抓取存储 / DeepSeek 搜索与抓取。
+- **工具集**：Redis / 文件 / 雪花 ID / 离线授权签发与校验 / 文档互转 / Word 模板填充 / MinerU 解析 / Marker 本地解析（0.7.0 起暂停发布，需要请用 `sdpy-kit==0.6.10`） / 离线 docx 解析（md + images/） / Laya 类型化决策 / Decima 决策模型（选项乱序不变、置信度可门控） / 微信公众号文章抓取存储 / 通用网页文章抓取存储 / DeepSeek 搜索与抓取。
 
 > 要求 Python 3.13+
 
@@ -809,7 +809,7 @@ page = qb.paginate(page=1, per_page=20)            # {"items", "total", ...}
 
 安装：`pip install "sdpy-kit[ai]"`
 
-传输（0.6.11）：chat / embedding / image 走 `openai` SDK（`>=3.44,<4`，
+传输：chat / embedding / image 走 `openai` SDK（`>=3.44,<4`，
 自带 `httpx2`），rerank 走 httpx 自研传输（SDK 无 `/rerank` 资源）。
 档案里的 `endpoint` **对前三类不再生效**——SDK 固定拼 `/chat/completions`、
 `/embeddings`、`/images/generations`，仅 rerank 与探活仍使用该字段。
@@ -835,14 +835,29 @@ shutdown()                                                     # 应用退出前
 |------|------|------|
 | chat | `chat_complete(prompt, *, max_tokens=None, thinking=None, json_mode=None, response_format=None, stats=None) -> str` | 单轮对话（仅 user 消息） |
 | chat | `chat_ask(messages, *, max_tokens=None, thinking=None, json_mode=None, response_format=None, stats=None) -> str` | 多轮对话，`messages` 为 `[{"role": "user", "content": "..."}]` |
-| chat | `chat_stream(messages, *, max_tokens=None, thinking=None, json_mode=None, response_format=None) -> Iterator[str]` | 同步流式逐 token 迭代器（建议 `with` 使用）；结束后可读 `reasoning_chars` / `content_chars` / `finish_reason` / `truncated` / `thinking_applied` / `json_mode_applied` |
+| chat | `chat_stream(messages, *, max_tokens=None, thinking=None, json_mode=None, response_format=None) -> Iterator[str]` | 同步流式逐 token 迭代器（建议 `with` 使用）；结束后可读 `reasoning_chars` / `content_chars` / `finish_reason` / `requested_max_tokens` / `truncated` / `empty_kind` / `thinking_applied` / `json_mode_applied` |
 | embedding | `embed_text(text) -> list[float]` | 单文本向量化 |
 | embedding | `embed_texts(texts) -> list[list[float]]` | 批量向量化 |
-| rerank | `rerank(query, documents, top_n=None) -> list[RerankHit]` | 返回 `RerankHit`（`index` / `score` / `document`）降序列表 |
+| rerank | `rerank(query, documents, top_n=None) -> list[RerankHit]` | 返回 `RerankHit`（`index` / `score` / `document`）降序列表；**`top_n` 是返回条数上限，由 kit 本地裁剪**（服务端返回超量也按分数截断），`top_n=None` 返回全部命中 |
 | image | `generate_image(prompt, *, size=None, n=1, return_base64=False, ratio=None) -> ImageResult` | 文生图，返回 `ImageResult`（`url` / `b64` 至少一个非空） |
 | 管理 | `use(model_type, profile) -> None` | 切换该类型当前档案（`chat` / `embedding` / `rerank` / `image`） |
-| 管理 | `available(model_type) -> list[ProfileStatus]` | 各档案状态快照（含未配置与被剔除者） |
-| 管理 | `reload_config(*, model_type=None, reload_file=False, probe=True, immediate=False) -> ReloadResult` | 配置热重载，改密钥 / 档案后无需重启 |
+| 管理 | `available(model_type) -> list[ProfileStatus]` | 各档案状态快照（含未配置密钥与被剔除者）；**类型未在 `ai_models.json` 中配置时返回 `[]`**（不再抛异常），类型名非法仍抛 `AIConfigError` |
+| 管理 | `reload_config(*, model_type=None, reload_file=False, probe=True, immediate=False) -> ReloadResult` | 配置热重载，改密钥 / 档案后无需重启；同时清空思考/结构化输出的告警去重表（修正档案后同一原因会重新提示） |
+
+**可用性查询（`available`）**：`available` 返回的是**状态快照**，不是「可用档案列表」。
+判断某类型是否已配置用 `if not AI.available(t)`，不要靠捕获异常：
+
+```python
+from kit.ai.runner import AI
+
+profiles = AI.available("image")   # ai_models.json 无 image 段 → []
+if not profiles:
+    raise RuntimeError("尚未配置图像生成模型")
+current = next((p for p in profiles if p.current), None)
+```
+
+> 旧写法 `try: AI.available(t) except AIConfigError: ...` 仍可用（异常分支不再触发）；
+> `AI.available(t)[0]` 在类型未配置时会抛 `IndexError`，请改用上面的判空写法。
 
 ```python
 from kit.ai.runner import AI
@@ -854,30 +869,47 @@ with AI.chat_stream([{"role": "user", "content": "写一首短诗"}]) as stream:
 
 #### 流式收尾统计（思考型模型必备）
 
-迭代器在流结束后可读六个只读属性（`reasoning_chars` / `content_chars` / `finish_reason` /
-`truncated` / `thinking_applied` / `json_mode_applied`），用于区分「模型真的没返回」与「输出预算被思考吃光」——思考型模型的推理
-token 计入 `max_tokens`，长上下文 + 小预算时常出现「返回 200 但正文为空」（同一套字段也可用于非流式 `ask` / `complete`，
-见下文「结构化输出」）：
+迭代器在流结束后可读八个字段（`reasoning_chars` / `content_chars` / `finish_reason` /
+`requested_max_tokens` / `truncated` / `empty_kind` / `thinking_applied` / `json_mode_applied`），
+其中 `truncated` 与 `empty_kind` 是只读派生属性。用于区分「模型真的没返回」与「输出预算被思考吃光」——
+思考型模型的推理 token 计入 `max_tokens`，长上下文 + 小预算时常出现「返回 200 但正文为空」
+（同一套字段也可用于非流式 `ask` / `complete`，见下文「结构化输出」）。
+
+`empty_kind` 把「正文为空」分成五类，不再一律归因为预算耗尽：
+
+| 取值 | 判定 | 建议处置 |
+|---|---|---|
+| `budget_exhausted` | 被长度截断且有推理 | 调大 `max_tokens`，或对该调用传 `thinking=False` |
+| `truncated_empty` | 被长度截断且无推理 | 调大 `max_tokens`；若模型支持独立推理预算，确认推理是否计入输出配额 |
+| `reasoning_only` | 有推理、`finish_reason=stop`、正文 0 | 提高预算或换模型 |
+| `no_finish` | 结束原因缺失或非 `stop`（端点未发送 `finish_reason`） | 可原样重试；连续出现检查端点 |
+| `stopped_empty` | 无推理、`finish_reason=stop`、正文 0 | 检查提示词与模型输出 |
+
+正文非空时 `empty_kind is None`。判定只用「是否截断 + 是否有推理 + 结束原因」，不依赖 token 数（kit 目前不采集 `usage`）：
 
 ```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 或对该调用传 thinking=False"
-    )
+if not body:
+    match stream.empty_kind:
+        case "budget_exhausted" | "truncated_empty":
+            ...  # 调大 max_tokens（或配独立推理预算）
+        case "no_finish":
+            ...  # 原样重试
 ```
 
+`requested_max_tokens` 是本次**实际下发**的输出上限（调用方传值优先，否则取档案 `max_tokens`；都没有为 `None`），
+在发请求前写入，失败/中断时也可读——业务可据此判断「预算是否真的设够了」。
+
 - 推理字段兼容 `delta.reasoning_content`（GLM / DeepSeek / Qwen）与 `delta.reasoning`（sensenova）：只计数不产出；
-- 推理字段名是 kit 内部白名单（当前就是上面两种）：新 provider 若用别的字段名，`reasoning_chars` 会恒为 0——此时仍可用 `truncated` 判定是否被截断；
-- 正文为空且（被截断或发生过思考）时 kit 自行打 `WARNING`，含模型与 `max_tokens`；
+- 推理字段名是 kit 内部白名单（当前就是上面两种）：新 provider 若用别的字段名，`reasoning_chars` 会恒为 0——此时仍可用 `truncated` / `empty_kind` 判定；
+- 正文为空时 kit 按 `empty_kind` 分级打 `WARNING`（含模型、`max_tokens`、`finish_reason` 与推荐处置），不再统一归因「预算被思考耗尽」；
 - `truncated` 覆盖 `finish_reason` 为 `length` 或 `max_tokens` 两种口径；
 - **字符数 ≠ token 数**（实测中文约 2~2.5 字符/token，各家口径不一），不要用 `reasoning_chars` 反推还差多少预算；
-- provider 不返回 `finish_reason` 时 `finish_reason is None`、`truncated is False`；
+- provider 不返回 `finish_reason` 时 `finish_reason is None`、`truncated is False`；正文为空则归为 `no_finish`（可原样重试）；
 - 流式过程中读到的是尽力而为的中间值，**结束后才是最终值**；提前 `break` 时为截至中断的累计值。
 
-#### 逐调用思考开关（0.6.7）
+#### 逐调用思考开关
 
 同一档案下按调用点切换思考（入库抽取关、章节生成开），不必复制档案：
 
@@ -896,14 +928,14 @@ kit 不认识任何厂商字段名，请求体字段由档案 `thinking` 声明
 
 `thinking_applied`（流式迭代器属性 / `StreamStats` 字段）：`None` 未要求干预 / `True` 已按声明注入 / `False` 要求了但被忽略。
 
-> 这是对 0.6.5「不新增 thinking / reasoning_effort 具名字段、只用 `extra_body`」结论的**有意修订**：
-> 当时的否决理由（候选链跨厂商，备胎收到未知字段会 400 → 冷却）已由「档案能力声明」机制解除——
+> 设计说明：曾否决「新增 thinking / reasoning_effort 具名字段、只用 `extra_body`」，
+> 该否决理由（候选链跨厂商，备胎收到未知字段会 400 → 冷却）已由「档案能力声明」机制解除——
 > 字段只发给声明了它的候选，未声明者不注入。思考**档位**（`low/medium/high`）仍然不做。
 
 > 首帧等待语义：每候选 60 秒内**一帧都没有**（含推理帧）才切下一候选；思考阶段的
 > 推理帧算活动并重置窗口，不会误判健康模型失败、也不会重放整段 prompt。
 
-#### 结构化输出（JSON 模式，0.6.8）
+#### 结构化输出（JSON 模式）
 
 只要「合法 JSON 对象」用 `json_mode=True`；要约束字段用协议的 `response_format` 原样透传：
 
@@ -1228,7 +1260,7 @@ 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_docx(src_path, dest_path=None, *, generate_toc=False, mainfont="宋体") -> 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（实验性，内部使用；图片等比限宽居中） |
 
@@ -1611,13 +1643,13 @@ AI 功能需要在项目根目录提供 `config/ai_models.json`（chat / embeddi
 
 | 层级 | 字段 | 说明 |
 |------|------|------|
-| 档案级 | `endpoint` | 请求路径。**0.6.10 起仅 rerank 生效**：chat / embedding / image 由 openai SDK 固定拼路径，本字段被忽略（保留仅为兼容旧配置，不报错） |
+| 档案级 | `endpoint` | 请求路径。**仅 rerank 生效**：chat / embedding / image 由 openai SDK 固定拼路径，本字段被忽略（保留仅为兼容旧配置，不报错） |
 | 档案级 | `timeout` | 请求超时秒数（默认 60）；SDK 侧为单次调用总超时 |
 | 档案级 | `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`）无法用它实现。逐调用 `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 只做翻译，不含任何厂商名 |
-| 档案级 | `structured_output` | 结构化输出的注入声明（0.6.8）：`{"arg": "response_format", "json_mode": {"type": "json_object"}}`。`arg` 是请求体顶层键名（不得占用保留键）；`json_mode` 是 `json_mode=True` 时写入该键的取值。**未声明 = 用内置 OpenAI 兼容默认**（`response_format: {"type":"json_object"}`，开箱即用）；`"structured_output": false` 表示该档案不支持（`json_mode=True` 被忽略 + 告警，不发任何字段）。逐调用 `response_format` 原样透传优先于本声明。kit 只做翻译，不含任何厂商名 |
+| 档案级 | `thinking` | 思考开关的注入声明：`{"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 只做翻译，不含任何厂商名 |
+| 档案级 | `structured_output` | 结构化输出的注入声明：`{"arg": "response_format", "json_mode": {"type": "json_object"}}`。`arg` 是请求体顶层键名（不得占用保留键）；`json_mode` 是 `json_mode=True` 时写入该键的取值。**未声明 = 用内置 OpenAI 兼容默认**（`response_format: {"type":"json_object"}`，开箱即用）；`"structured_output": false` 表示该档案不支持（`json_mode=True` 被忽略 + 告警，不发任何字段）。逐调用 `response_format` 原样透传优先于本声明。kit 只做翻译，不含任何厂商名 |
 | 类型级 | `chain_timeout` | 整链预算秒数（与 `default_profile` 同级）；门面同步等待上限。未配置时按 `sum(候选 timeout) + 10s` 自适应，也可用环境变量 `KIT_AI_CHAIN_TIMEOUT` 全局覆盖 |
 
 `thinking` 声明两种实测形态（按平台各自写入档案）：
@@ -1639,11 +1671,11 @@ AI 功能需要在项目根目录提供 `config/ai_models.json`（chat / embeddi
 ```
 
 > **`extra_body` 的用法边界**：`extra_body` 是**档案级**的固有配置，无法按调用点切换。需要
-> 「同一模型，长文开思考、短文关思考」并存时用档案 `thinking` 声明 + 逐调用 `thinking=False/True`
-> （0.6.7 起）；仅在无法用开关表达时才考虑复制档案 + `ModelBuilder.build_chat("<档案名>")`
+> 「同一模型，长文开思考、短文关思考」并存时用档案 `thinking` 声明 + 逐调用 `thinking=False/True`；
+> 仅在无法用开关表达时才考虑复制档案 + `ModelBuilder.build_chat("<档案名>")`
 > （门面侧 `AI.use("chat", "<档案名>")` 是进程级切换，非并发安全）。
 > 结构化输出同理：档案声明只给 `json_mode=True` 提供取值，按调用点变化的 schema 一律走
-> 逐调用 `response_format`（0.6.8 起）。
+> 逐调用 `response_format`。
 
 ### 候选链切换语义（两类，勿混淆）
 

{sdpy_kit-0.7.0 → sdpy_kit-0.7.2}/README.md

@@ -4,7 +4,7 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 
 - **统一数据库访问层**：PostgreSQL / MySQL / SQLite，三个 Kit API 完全一致，切换数据库只改一行 import；内置审计字段自动填充（`created_*` / `updated_*` / `deleted`）与软删除查询过滤；
 - **AI 多模型服务池**：chat / embedding / rerank / image 四类能力，多厂商候选链 + 故障自动转移；
-- **工具集**：Redis / 文件 / 雪花 ID / 离线授权签发与校验 / 文档互转 / Word 模板填充 / MinerU 解析 / Marker 本地解析（PDF + 图片 → md + images/） / 离线 docx 解析（md + images/） / Laya 类型化决策 / Decima 决策模型（选项乱序不变、置信度可门控） / 微信公众号文章抓取存储 / 通用网页文章抓取存储 / DeepSeek 搜索与抓取。
+- **工具集**：Redis / 文件 / 雪花 ID / 离线授权签发与校验 / 文档互转 / Word 模板填充 / MinerU 解析 / Marker 本地解析（0.7.0 起暂停发布，需要请用 `sdpy-kit==0.6.10`） / 离线 docx 解析（md + images/） / Laya 类型化决策 / Decima 决策模型（选项乱序不变、置信度可门控） / 微信公众号文章抓取存储 / 通用网页文章抓取存储 / DeepSeek 搜索与抓取。
 
 > 要求 Python 3.13+
 
@@ -727,7 +727,7 @@ page = qb.paginate(page=1, per_page=20)            # {"items", "total", ...}
 
 安装：`pip install "sdpy-kit[ai]"`
 
-传输（0.6.11）：chat / embedding / image 走 `openai` SDK（`>=3.44,<4`，
+传输：chat / embedding / image 走 `openai` SDK（`>=3.44,<4`，
 自带 `httpx2`），rerank 走 httpx 自研传输（SDK 无 `/rerank` 资源）。
 档案里的 `endpoint` **对前三类不再生效**——SDK 固定拼 `/chat/completions`、
 `/embeddings`、`/images/generations`，仅 rerank 与探活仍使用该字段。
@@ -753,14 +753,29 @@ shutdown()                                                     # 应用退出前
 |------|------|------|
 | chat | `chat_complete(prompt, *, max_tokens=None, thinking=None, json_mode=None, response_format=None, stats=None) -> str` | 单轮对话（仅 user 消息） |
 | chat | `chat_ask(messages, *, max_tokens=None, thinking=None, json_mode=None, response_format=None, stats=None) -> str` | 多轮对话，`messages` 为 `[{"role": "user", "content": "..."}]` |
-| chat | `chat_stream(messages, *, max_tokens=None, thinking=None, json_mode=None, response_format=None) -> Iterator[str]` | 同步流式逐 token 迭代器（建议 `with` 使用）；结束后可读 `reasoning_chars` / `content_chars` / `finish_reason` / `truncated` / `thinking_applied` / `json_mode_applied` |
+| chat | `chat_stream(messages, *, max_tokens=None, thinking=None, json_mode=None, response_format=None) -> Iterator[str]` | 同步流式逐 token 迭代器（建议 `with` 使用）；结束后可读 `reasoning_chars` / `content_chars` / `finish_reason` / `requested_max_tokens` / `truncated` / `empty_kind` / `thinking_applied` / `json_mode_applied` |
 | embedding | `embed_text(text) -> list[float]` | 单文本向量化 |
 | embedding | `embed_texts(texts) -> list[list[float]]` | 批量向量化 |
-| rerank | `rerank(query, documents, top_n=None) -> list[RerankHit]` | 返回 `RerankHit`（`index` / `score` / `document`）降序列表 |
+| rerank | `rerank(query, documents, top_n=None) -> list[RerankHit]` | 返回 `RerankHit`（`index` / `score` / `document`）降序列表；**`top_n` 是返回条数上限，由 kit 本地裁剪**（服务端返回超量也按分数截断），`top_n=None` 返回全部命中 |
 | image | `generate_image(prompt, *, size=None, n=1, return_base64=False, ratio=None) -> ImageResult` | 文生图，返回 `ImageResult`（`url` / `b64` 至少一个非空） |
 | 管理 | `use(model_type, profile) -> None` | 切换该类型当前档案（`chat` / `embedding` / `rerank` / `image`） |
-| 管理 | `available(model_type) -> list[ProfileStatus]` | 各档案状态快照（含未配置与被剔除者） |
-| 管理 | `reload_config(*, model_type=None, reload_file=False, probe=True, immediate=False) -> ReloadResult` | 配置热重载，改密钥 / 档案后无需重启 |
+| 管理 | `available(model_type) -> list[ProfileStatus]` | 各档案状态快照（含未配置密钥与被剔除者）；**类型未在 `ai_models.json` 中配置时返回 `[]`**（不再抛异常），类型名非法仍抛 `AIConfigError` |
+| 管理 | `reload_config(*, model_type=None, reload_file=False, probe=True, immediate=False) -> ReloadResult` | 配置热重载，改密钥 / 档案后无需重启；同时清空思考/结构化输出的告警去重表（修正档案后同一原因会重新提示） |
+
+**可用性查询（`available`）**：`available` 返回的是**状态快照**，不是「可用档案列表」。
+判断某类型是否已配置用 `if not AI.available(t)`，不要靠捕获异常：
+
+```python
+from kit.ai.runner import AI
+
+profiles = AI.available("image")   # ai_models.json 无 image 段 → []
+if not profiles:
+    raise RuntimeError("尚未配置图像生成模型")
+current = next((p for p in profiles if p.current), None)
+```
+
+> 旧写法 `try: AI.available(t) except AIConfigError: ...` 仍可用（异常分支不再触发）；
+> `AI.available(t)[0]` 在类型未配置时会抛 `IndexError`，请改用上面的判空写法。
 
 ```python
 from kit.ai.runner import AI
@@ -772,30 +787,47 @@ with AI.chat_stream([{"role": "user", "content": "写一首短诗"}]) as stream:
 
 #### 流式收尾统计（思考型模型必备）
 
-迭代器在流结束后可读六个只读属性（`reasoning_chars` / `content_chars` / `finish_reason` /
-`truncated` / `thinking_applied` / `json_mode_applied`），用于区分「模型真的没返回」与「输出预算被思考吃光」——思考型模型的推理
-token 计入 `max_tokens`，长上下文 + 小预算时常出现「返回 200 但正文为空」（同一套字段也可用于非流式 `ask` / `complete`，
-见下文「结构化输出」）：
+迭代器在流结束后可读八个字段（`reasoning_chars` / `content_chars` / `finish_reason` /
+`requested_max_tokens` / `truncated` / `empty_kind` / `thinking_applied` / `json_mode_applied`），
+其中 `truncated` 与 `empty_kind` 是只读派生属性。用于区分「模型真的没返回」与「输出预算被思考吃光」——
+思考型模型的推理 token 计入 `max_tokens`，长上下文 + 小预算时常出现「返回 200 但正文为空」
+（同一套字段也可用于非流式 `ask` / `complete`，见下文「结构化输出」）。
+
+`empty_kind` 把「正文为空」分成五类，不再一律归因为预算耗尽：
+
+| 取值 | 判定 | 建议处置 |
+|---|---|---|
+| `budget_exhausted` | 被长度截断且有推理 | 调大 `max_tokens`，或对该调用传 `thinking=False` |
+| `truncated_empty` | 被长度截断且无推理 | 调大 `max_tokens`；若模型支持独立推理预算，确认推理是否计入输出配额 |
+| `reasoning_only` | 有推理、`finish_reason=stop`、正文 0 | 提高预算或换模型 |
+| `no_finish` | 结束原因缺失或非 `stop`（端点未发送 `finish_reason`） | 可原样重试；连续出现检查端点 |
+| `stopped_empty` | 无推理、`finish_reason=stop`、正文 0 | 检查提示词与模型输出 |
+
+正文非空时 `empty_kind is None`。判定只用「是否截断 + 是否有推理 + 结束原因」，不依赖 token 数（kit 目前不采集 `usage`）：
 
 ```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 或对该调用传 thinking=False"
-    )
+if not body:
+    match stream.empty_kind:
+        case "budget_exhausted" | "truncated_empty":
+            ...  # 调大 max_tokens（或配独立推理预算）
+        case "no_finish":
+            ...  # 原样重试
 ```
 
+`requested_max_tokens` 是本次**实际下发**的输出上限（调用方传值优先，否则取档案 `max_tokens`；都没有为 `None`），
+在发请求前写入，失败/中断时也可读——业务可据此判断「预算是否真的设够了」。
+
 - 推理字段兼容 `delta.reasoning_content`（GLM / DeepSeek / Qwen）与 `delta.reasoning`（sensenova）：只计数不产出；
-- 推理字段名是 kit 内部白名单（当前就是上面两种）：新 provider 若用别的字段名，`reasoning_chars` 会恒为 0——此时仍可用 `truncated` 判定是否被截断；
-- 正文为空且（被截断或发生过思考）时 kit 自行打 `WARNING`，含模型与 `max_tokens`；
+- 推理字段名是 kit 内部白名单（当前就是上面两种）：新 provider 若用别的字段名，`reasoning_chars` 会恒为 0——此时仍可用 `truncated` / `empty_kind` 判定；
+- 正文为空时 kit 按 `empty_kind` 分级打 `WARNING`（含模型、`max_tokens`、`finish_reason` 与推荐处置），不再统一归因「预算被思考耗尽」；
 - `truncated` 覆盖 `finish_reason` 为 `length` 或 `max_tokens` 两种口径；
 - **字符数 ≠ token 数**（实测中文约 2~2.5 字符/token，各家口径不一），不要用 `reasoning_chars` 反推还差多少预算；
-- provider 不返回 `finish_reason` 时 `finish_reason is None`、`truncated is False`；
+- provider 不返回 `finish_reason` 时 `finish_reason is None`、`truncated is False`；正文为空则归为 `no_finish`（可原样重试）；
 - 流式过程中读到的是尽力而为的中间值，**结束后才是最终值**；提前 `break` 时为截至中断的累计值。
 
-#### 逐调用思考开关（0.6.7）
+#### 逐调用思考开关
 
 同一档案下按调用点切换思考（入库抽取关、章节生成开），不必复制档案：
 
@@ -814,14 +846,14 @@ kit 不认识任何厂商字段名，请求体字段由档案 `thinking` 声明
 
 `thinking_applied`（流式迭代器属性 / `StreamStats` 字段）：`None` 未要求干预 / `True` 已按声明注入 / `False` 要求了但被忽略。
 
-> 这是对 0.6.5「不新增 thinking / reasoning_effort 具名字段、只用 `extra_body`」结论的**有意修订**：
-> 当时的否决理由（候选链跨厂商，备胎收到未知字段会 400 → 冷却）已由「档案能力声明」机制解除——
+> 设计说明：曾否决「新增 thinking / reasoning_effort 具名字段、只用 `extra_body`」，
+> 该否决理由（候选链跨厂商，备胎收到未知字段会 400 → 冷却）已由「档案能力声明」机制解除——
 > 字段只发给声明了它的候选，未声明者不注入。思考**档位**（`low/medium/high`）仍然不做。
 
 > 首帧等待语义：每候选 60 秒内**一帧都没有**（含推理帧）才切下一候选；思考阶段的
 > 推理帧算活动并重置窗口，不会误判健康模型失败、也不会重放整段 prompt。
 
-#### 结构化输出（JSON 模式，0.6.8）
+#### 结构化输出（JSON 模式）
 
 只要「合法 JSON 对象」用 `json_mode=True`；要约束字段用协议的 `response_format` 原样透传：
 
@@ -1146,7 +1178,7 @@ 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_docx(src_path, dest_path=None, *, generate_toc=False, mainfont="宋体") -> 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（实验性，内部使用；图片等比限宽居中） |
 
@@ -1529,13 +1561,13 @@ AI 功能需要在项目根目录提供 `config/ai_models.json`（chat / embeddi
 
 | 层级 | 字段 | 说明 |
 |------|------|------|
-| 档案级 | `endpoint` | 请求路径。**0.6.10 起仅 rerank 生效**：chat / embedding / image 由 openai SDK 固定拼路径，本字段被忽略（保留仅为兼容旧配置，不报错） |
+| 档案级 | `endpoint` | 请求路径。**仅 rerank 生效**：chat / embedding / image 由 openai SDK 固定拼路径，本字段被忽略（保留仅为兼容旧配置，不报错） |
 | 档案级 | `timeout` | 请求超时秒数（默认 60）；SDK 侧为单次调用总超时 |
 | 档案级 | `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`）无法用它实现。逐调用 `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 只做翻译，不含任何厂商名 |
-| 档案级 | `structured_output` | 结构化输出的注入声明（0.6.8）：`{"arg": "response_format", "json_mode": {"type": "json_object"}}`。`arg` 是请求体顶层键名（不得占用保留键）；`json_mode` 是 `json_mode=True` 时写入该键的取值。**未声明 = 用内置 OpenAI 兼容默认**（`response_format: {"type":"json_object"}`，开箱即用）；`"structured_output": false` 表示该档案不支持（`json_mode=True` 被忽略 + 告警，不发任何字段）。逐调用 `response_format` 原样透传优先于本声明。kit 只做翻译，不含任何厂商名 |
+| 档案级 | `thinking` | 思考开关的注入声明：`{"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 只做翻译，不含任何厂商名 |
+| 档案级 | `structured_output` | 结构化输出的注入声明：`{"arg": "response_format", "json_mode": {"type": "json_object"}}`。`arg` 是请求体顶层键名（不得占用保留键）；`json_mode` 是 `json_mode=True` 时写入该键的取值。**未声明 = 用内置 OpenAI 兼容默认**（`response_format: {"type":"json_object"}`，开箱即用）；`"structured_output": false` 表示该档案不支持（`json_mode=True` 被忽略 + 告警，不发任何字段）。逐调用 `response_format` 原样透传优先于本声明。kit 只做翻译，不含任何厂商名 |
 | 类型级 | `chain_timeout` | 整链预算秒数（与 `default_profile` 同级）；门面同步等待上限。未配置时按 `sum(候选 timeout) + 10s` 自适应，也可用环境变量 `KIT_AI_CHAIN_TIMEOUT` 全局覆盖 |
 
 `thinking` 声明两种实测形态（按平台各自写入档案）：
@@ -1557,11 +1589,11 @@ AI 功能需要在项目根目录提供 `config/ai_models.json`（chat / embeddi
 ```
 
 > **`extra_body` 的用法边界**：`extra_body` 是**档案级**的固有配置，无法按调用点切换。需要
-> 「同一模型，长文开思考、短文关思考」并存时用档案 `thinking` 声明 + 逐调用 `thinking=False/True`
-> （0.6.7 起）；仅在无法用开关表达时才考虑复制档案 + `ModelBuilder.build_chat("<档案名>")`
+> 「同一模型，长文开思考、短文关思考」并存时用档案 `thinking` 声明 + 逐调用 `thinking=False/True`；
+> 仅在无法用开关表达时才考虑复制档案 + `ModelBuilder.build_chat("<档案名>")`
 > （门面侧 `AI.use("chat", "<档案名>")` 是进程级切换，非并发安全）。
 > 结构化输出同理：档案声明只给 `json_mode=True` 提供取值，按调用点变化的 schema 一律走
-> 逐调用 `response_format`（0.6.8 起）。
+> 逐调用 `response_format`。
 
 ### 候选链切换语义（两类，勿混淆）
 

{sdpy_kit-0.7.0 → sdpy_kit-0.7.2}/kit/__init__.py

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

{sdpy_kit-0.7.0 → sdpy_kit-0.7.2}/kit/ai/chat_service.py

@@ -29,7 +29,11 @@ from dataclasses import dataclass
 from typing import Any, ClassVar, Final, cast
 
 from kit.ai.exceptions import AIError, AIResponseError
-from kit.ai.profiles import _RESERVED_PAYLOAD_KEYS, ModelProfile
+from kit.ai.profiles import (
+    _RESERVED_PAYLOAD_KEYS,
+    ModelProfile,
+    resolve_max_tokens,
+)
 from kit.ai.sdk_client import SdkServiceBase
 from kit.ai.types import JSONObject
 from kit.config.log_config import get_default_logger
@@ -47,6 +51,50 @@ _REASONING_KEYS: Final[tuple[str, ...]] = ("reasoning_content", "reasoning")
 # 截断判定：OpenAI 系给 length，部分兼容端点给 max_tokens
 _TRUNCATED_REASONS: Final[frozenset[str]] = frozenset({"length", "max_tokens"})
 
+# 空正文诊断分级 → 告警文案（正文为 0 时才有分级，见 _classify_empty）
+_EMPTY_HINTS: Final[dict[str, str]] = {
+    "budget_exhausted": "输出预算疑被思考耗尽（长度截断）",
+    "truncated_empty": "输出被长度截断、正文为空（无推理）",
+    "reasoning_only": "只产出推理、正文为空（finish=stop）",
+    "no_finish": "正文为空且未收到正常结束原因",
+    "stopped_empty": "无正文输出（finish=stop）",
+}
+
+_EMPTY_ACTIONS: Final[dict[str, str]] = {
+    "budget_exhausted": "（可调大 max_tokens，或对该调用传 thinking=False 关闭思考）",
+    "truncated_empty": "（调大 max_tokens；若模型支持独立推理预算，确认推理是否计入输出配额）",
+    "reasoning_only": "（推理未触顶但正文为空，可提高预算或换模型）",
+    "no_finish": "（端点未发送 finish_reason 或异常结束，可原样重试）",
+    "stopped_empty": "（检查提示词与模型输出）",
+}
+
+
+def _classify_empty(
+    *,
+    content_chars: int,
+    reasoning_chars: int,
+    finish_reason: str | None,
+    truncated: bool,
+) -> str | None:
+    """空正文诊断分级；正文非空返回 None。
+
+    - ``budget_exhausted``：被截断且有推理（预算被思考吃满）
+    - ``truncated_empty``：被截断且无推理（一个正文字符都没出）
+    - ``reasoning_only``：有推理、``finish_reason=stop``
+    - ``no_finish``：结束原因缺失或非 stop（无论有无推理）
+    - ``stopped_empty``：无推理、``finish_reason=stop``
+    """
+    if content_chars:
+        return None
+    if truncated:
+        return "budget_exhausted" if reasoning_chars else "truncated_empty"
+    if reasoning_chars:
+        return "reasoning_only" if finish_reason == "stop" else "no_finish"
+    if finish_reason == "stop":
+        return "stopped_empty"
+    return "no_finish"
+
+
 # 「无注入值」哨兵：区分「不注入」与「注入值为 None」
 _UNSET: Final[object] = object()
 
@@ -71,6 +119,15 @@ def _warn_once(
     logger.log(level, f"{kind}：{reason}（档案 {profile_name}）")
 
 
+def reset_warned() -> None:
+    """清空告警去重表（配置热重载后重新提示，避免旧原因被永久压制）。
+
+    供 :func:`kit.ai.runner.reload_config` 调用；线程安全。
+    """
+    with _WARNED_LOCK:
+        _WARNED.clear()
+
+
 def _resolve_thinking(
     profile: ModelProfile, thinking: bool | None
 ) -> tuple[object, bool | None, str | None, int]:
@@ -125,6 +182,13 @@ class StreamStats:
             True 已按档案声明注入 / False 要求了但档案完全没有 thinking 声明
         json_mode_applied: 结构化输出是否生效——None 本次未要求注入 /
             True 已注入 / False 要求了但档案声明不支持（已忽略）
+        requested_max_tokens: 本次实际下发的输出上限（调用方 → 档案回落）；
+            None 表示未下发、由 provider 默认值决定。在发出请求前写入，
+            失败/中断时也可读
+
+    只读派生属性：``truncated``（是否截断）、``empty_kind``（正文为空时的
+    诊断分级：``budget_exhausted`` / ``truncated_empty`` / ``reasoning_only`` /
+    ``no_finish`` / ``stopped_empty``；正文非空为 None）。
     """
 
     reasoning_chars: int = 0
@@ -132,12 +196,29 @@ class StreamStats:
     finish_reason: str | None = None
     thinking_applied: bool | None = None
     json_mode_applied: bool | None = None
+    requested_max_tokens: int | None = None
 
     @property
     def truncated(self) -> bool:
         """是否因输出长度上限被截断。"""
         return self.finish_reason in _TRUNCATED_REASONS
 
+    @property
+    def empty_kind(self) -> str | None:
+        """正文为空时的诊断分级；正文非空返回 None。
+
+        取值：``budget_exhausted`` / ``truncated_empty`` / ``reasoning_only`` /
+        ``no_finish`` / ``stopped_empty``。不依赖 token 数量，用「是否截断 +
+        是否有推理 + 结束原因」区分「预算吃满」「截断且无正文」「只推理」
+        「未正常收尾」「正常停住」。
+        """
+        return _classify_empty(
+            content_chars=self.content_chars,
+            reasoning_chars=self.reasoning_chars,
+            finish_reason=self.finish_reason,
+            truncated=self.truncated,
+        )
+
     def reset(self) -> None:
         """清零（候选链切换到下一个档案前调用）。"""
         self.reasoning_chars = 0
@@ -145,6 +226,7 @@ class StreamStats:
         self.finish_reason = None
         self.thinking_applied = None
         self.json_mode_applied = None
+        self.requested_max_tokens = None
 
 
 @dataclass(frozen=True)
@@ -317,7 +399,8 @@ class ChatService(SdkServiceBase):
             response_format: 协议级原样透传（含 ``json_schema`` 严格模式）；
                 与 ``json_mode`` 互斥，schema 由调用方负责
             stats: 收尾统计累加器（可选）；传入后可读 ``finish_reason`` /
-                ``truncated`` / ``reasoning_chars`` / ``json_mode_applied``
+                ``truncated`` / ``empty_kind`` / ``requested_max_tokens`` /
+                ``reasoning_chars`` / ``json_mode_applied``
             deadline: 整链预算截止时刻（``time.monotonic()`` 秒），约束
                 5xx 重试预算；None 表示不限制
         """
@@ -331,6 +414,9 @@ class ChatService(SdkServiceBase):
             stats=stats,
         )
         extra_body, response_format_arg = self._build_injection(request)
+        effective_max_tokens = resolve_max_tokens(self._profile, request.max_tokens)
+        if stats is not None:
+            stats.requested_max_tokens = effective_max_tokens
         self._debug_payload(
             {
                 "model": self._profile.model,
@@ -361,7 +447,21 @@ class ChatService(SdkServiceBase):
                     "（请调大 max_tokens，或对该调用传 thinking=False 关闭思考）"
                 )
             raise AIResponseError(f"content 类型异常: {type(content).__name__}")
-        if finish in _TRUNCATED_REASONS and (reasoning or not content):
+        truncated = finish in _TRUNCATED_REASONS
+        kind = _classify_empty(
+            content_chars=len(content),
+            reasoning_chars=len(reasoning),
+            finish_reason=finish,
+            truncated=truncated,
+        )
+        if kind is not None:
+            self._log_empty(
+                kind=kind,
+                max_tokens=effective_max_tokens,
+                finish=finish,
+                reasoning_chars=len(reasoning),
+            )
+        elif truncated:
             logger.warning(
                 f"{self._log_desc()} 输出被长度截断（finish_reason={finish}）："
                 f"推理 {len(reasoning)} 字符 / 正文 {len(content)} 字符"
@@ -420,11 +520,12 @@ class ChatService(SdkServiceBase):
                 kit 不做增量解析
             response_format: 协议级原样透传（与 ``json_mode`` 互斥）
             stats: 收尾统计累加器（可选）；None 时内部创建后丢弃——需要
-                ``reasoning_chars`` / ``finish_reason`` / ``truncated`` 时
-                由调用方传入一个实例
+                ``reasoning_chars`` / ``finish_reason`` / ``truncated`` /
+                ``empty_kind`` / ``requested_max_tokens`` 时由调用方传入
 
         推理内容（``delta.reasoning_content`` / ``delta.reasoning``）只计数
-        不产出；正文为空且被截断（或发生过思考）时输出 warning。
+        不产出；正文为空时按 ``empty_kind`` 分级输出 warning（不依赖是否有
+        推理或是否截断）。
         """
         stats = stats if stats is not None else StreamStats()
         request = ChatRequest(
@@ -438,6 +539,8 @@ class ChatService(SdkServiceBase):
             stats=stats,
         )
         extra_body, response_format_arg = self._build_injection(request)
+        effective_max_tokens = resolve_max_tokens(self._profile, request.max_tokens)
+        stats.requested_max_tokens = effective_max_tokens
         desc = self._log_desc()
         # 惰性 Start：异步生成器体在首次 __anext__ 前不执行，不消费不打日志
         logger.info(f"********** {desc} ********** Start")
@@ -476,12 +579,7 @@ class ChatService(SdkServiceBase):
             note = "（中断）"
             raise
         else:
-            effective_max_tokens = (
-                request.max_tokens
-                if request.max_tokens is not None
-                else self._profile.max_tokens
-            )
-            self._warn_if_budget_eaten(stats, effective_max_tokens)
+            self._warn_if_empty(stats, effective_max_tokens)
         finally:
             log = logger.error if failed else logger.info
             log(
@@ -489,15 +587,29 @@ class ChatService(SdkServiceBase):
                 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):
+    def _warn_if_empty(self, stats: StreamStats, max_tokens: int | None) -> None:
+        """正文为空时按诊断分级告警（不再一律归因为「预算被思考耗尽」）。"""
+        kind = stats.empty_kind
+        if kind is None:
             return
+        self._log_empty(
+            kind=kind,
+            max_tokens=max_tokens,
+            finish=stats.finish_reason,
+            reasoning_chars=stats.reasoning_chars,
+        )
+
+    def _log_empty(
+        self,
+        *,
+        kind: str,
+        max_tokens: int | None,
+        finish: str | None,
+        reasoning_chars: int,
+    ) -> None:
+        """输出空正文诊断日志（``ask`` / ``stream`` 共用同一套文案）。"""
         logger.warning(
-            f"{self._log_desc()} 输出预算疑被思考耗尽：max_tokens={max_tokens}，"
-            f"finish_reason={stats.finish_reason}，"
-            f"推理 {stats.reasoning_chars} 字符 / 正文 0 字符"
-            "（可调大 max_tokens，或对该调用传 thinking=False 关闭思考）"
+            f"{self._log_desc()} {_EMPTY_HINTS[kind]}：max_tokens={max_tokens}，"
+            f"finish_reason={finish}，推理 {reasoning_chars} 字符 / 正文 0 字符"
+            f"{_EMPTY_ACTIONS[kind]}"
         )

{sdpy_kit-0.7.0 → sdpy_kit-0.7.2}/kit/ai/exceptions.py

@@ -23,6 +23,7 @@ Author: Clark Chang
 继承链：
     AIError                基类
     ├── AIConfigError      档案文件缺失/非法、档案不存在、密钥未配置、必填字段缺失
+    │   └── AIModelTypeNotConfiguredError  类型名合法但档案未配置该类型段
     ├── AIRequestError     网络异常、HTTP >= 400
     │   ├── AITimeoutError   请求超时（可用于重试策略）
     │   └── AIAggregateError 候选链聚合异常（全部候选失败或整链预算耗尽）
@@ -38,6 +39,15 @@ class AIConfigError(AIError):
     """模型档案配置异常（文件缺失/非法、档案不存在、密钥未配置、必填字段缺失）"""
 
 
+class AIModelTypeNotConfiguredError(AIConfigError):
+    """类型名合法但 ``ai_models.json`` 未配置该类型段（可预期的空态）。
+
+    ``AI.available(type)`` 对这种情况返回空列表；其余 ``AIConfigError``
+    （类型名非法、文件缺失、注册表未加载）仍照常抛出。继承 ``AIConfigError``
+    使既有 ``except AIConfigError`` 捕获点零改动。
+    """
+
+
 class AIRequestError(AIError):
     """模型服务请求异常（网络异常、HTTP >= 400）。
 

{sdpy_kit-0.7.0 → sdpy_kit-0.7.2}/kit/ai/model_builder.py

@@ -20,14 +20,16 @@ Author: Clark Chang
 from kit.ai.chat_service import ChatService
 from kit.ai.embedding_service import EmbeddingService
 from kit.ai.image_service import ImageService
-from kit.ai.profiles import ModelProfile, get_model_registry, with_api_key
+from kit.ai.profiles import (
+    MODEL_TYPES,
+    ModelProfile,
+    get_model_registry,
+    with_api_key,
+)
 from kit.ai.rerank_service import RerankService
 
 __all__ = ["ModelBuilder"]
 
-# 支持的模型类型
-_MODEL_TYPES: tuple[str, ...] = ("chat", "embedding", "rerank", "image")
-
 Service = ChatService | EmbeddingService | RerankService | ImageService
 
 
@@ -87,7 +89,7 @@ class ModelBuilder:
                 return ImageService(profile)
             case _:
                 raise ValueError(
-                    f"未知模型类型: {model_type}，支持: {', '.join(_MODEL_TYPES)}"
+                    f"未知模型类型: {model_type}，支持: {', '.join(MODEL_TYPES)}"
                 )
 
     @classmethod

{sdpy_kit-0.7.0 → sdpy_kit-0.7.2}/kit/ai/model_client.py

@@ -18,18 +18,17 @@ Author: Clark Chang
 """
 
 # date: 2026-11-04
-"""模型档案轻探测客户端（0.7.0 起更名 ``ProbeClient``）。
+"""模型档案轻探测客户端（``ProbeClient``）。
 
 破坏性变更：``post_json`` / ``stream_json`` 已删除——请求发送改由
 :class:`kit.ai.sdk_client.SdkClient` 承担，rerank 走
 :class:`kit.ai.rerank_transport.RerankTransport`。本类只保留
 ``list_models()`` / ``close()``，供业务侧做「密钥是否有效」的连通性测试。
 
-``ModelClient`` 作为弃用别名保留一个版本（访问时触发 ``DeprecationWarning``）。
+0.7.0 由 ``ModelClient`` 改名；0.7.1 起**弃用别名已删除**，旧名不可导入
+（``from kit.ai.model_client import ModelClient`` 抛 ``ImportError``）。
 """
 
-import warnings
-
 from kit.ai.profiles import ModelProfile
 from kit.ai.sdk_client import SdkClient
 from kit.ai.types import JSONObject
@@ -40,18 +39,14 @@ __all__ = ["ProbeClient"]
 class ProbeClient:
     """单档案连通性探测客户端（全异步）。
 
-    0.7.0 起由 ``ModelClient`` 改名：它只做 ``list_models`` 探活，
-    真正的传输在 :class:`kit.ai.sdk_client.SdkClient`。
+    它只做 ``list_models`` 探活，真正的传输在
+    :class:`kit.ai.sdk_client.SdkClient`。
     """
 
     def __init__(self, profile: ModelProfile) -> None:
         self._profile: ModelProfile = profile
         self._client: SdkClient = SdkClient(profile)
 
-    @property
-    def model(self) -> str:
-        return self._profile.model
-
     async def list_models(self) -> JSONObject:
         """``GET {base_url}/models`` 轻探测（独立 10 秒超时）。
 
@@ -65,15 +60,3 @@ class ProbeClient:
 
     async def close(self) -> None:
         await self._client.close()
-
-
-def __getattr__(name: str) -> object:
-    """0.7.0 起 ``ModelClient`` 更名为 ``ProbeClient``：保留别名并告警。"""
-    if name == "ModelClient":
-        warnings.warn(
-            "ModelClient 已更名为 ProbeClient（0.7.0），请改用 ProbeClient",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        return ProbeClient
-    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

{sdpy_kit-0.7.0 → sdpy_kit-0.7.2}/kit/ai/pool.py

@@ -42,7 +42,12 @@ from typing import Final
 
 from kit.ai.chat_service import ChatService
 from kit.ai.embedding_service import EmbeddingService
-from kit.ai.exceptions import AIConfigError, AIError, AIRequestError
+from kit.ai.exceptions import (
+    AIConfigError,
+    AIError,
+    AIModelTypeNotConfiguredError,
+    AIRequestError,
+)
 from kit.ai.image_service import ImageService
 from kit.ai.model_builder import Service
 from kit.ai.model_client import ProbeClient
@@ -369,8 +374,16 @@ class AIServicePool:
         logger.info(f"已切换 {model_type} 当前使用档案: {profile}")
 
     def available(self, model_type: str) -> list[ProfileStatus]:
-        """该类型全部档案状态快照（含未配置与被剔除者），链头标记 current。"""
-        chain = self._ensure_chain(model_type)
+        """该类型全部档案状态快照（含未配置密钥与被剔除者），链头标记 current。
+
+        类型名合法但 ``ai_models.json`` 未配置该段时返回空列表（可预期空态）；
+        类型名非法、注册表未加载等真正的配置错误仍抛 ``AIConfigError``。
+        """
+        try:
+            chain = self._ensure_chain(model_type)
+        except AIModelTypeNotConfiguredError as exc:
+            logger.debug(f"{model_type} 状态快照为空: {exc}")
+            return []
         now = time.monotonic()
         with self._lock:
             preferred = self._preferred.get(model_type)

{sdpy_kit-0.7.0 → sdpy_kit-0.7.2}/kit/ai/profiles.py

@@ -39,14 +39,14 @@ from typing import Any, Final, Literal, Self
 from dotenv import load_dotenv
 from pydantic import BaseModel, Field, ValidationError, field_validator, model_validator
 
-from kit.ai.exceptions import AIConfigError
+from kit.ai.exceptions import AIConfigError, AIModelTypeNotConfiguredError
 from kit.config.kit_config import get_settings
 from kit.config.log_config import get_default_logger
 
 logger = get_default_logger(__name__)
 
 # 支持的模型类型
-_MODEL_TYPES: Final[tuple[str, ...]] = ("chat", "embedding", "rerank", "image")
+MODEL_TYPES: Final[tuple[str, ...]] = ("chat", "embedding", "rerank", "image")
 
 # 文件缺失报错时附带的最小可用模板（api_key 为环境变量名，密钥配置在 .env）
 _MINIMAL_MODELS_JSON: Final[str] = (
@@ -152,11 +152,6 @@ class ModelProfile:
     thinking: ThinkingSwitchSpec | None = None
     structured_output: StructuredOutputSpec | None = None
 
-    @property
-    def url(self) -> str:
-        """拼接完整请求 URL（base_url 去尾斜杠 + endpoint）"""
-        return self.base_url.rstrip("/") + self.endpoint
-
 
 class ProfileState(enum.Enum):
     """档案运行时状态（候选链与状态快照使用）。"""
@@ -171,7 +166,7 @@ class ProfileState(enum.Enum):
 
 @dataclass(frozen=True)
 class ProfileStatus:
-    """档案状态快照行（``ModelRegistry.available`` / ``AI.available`` 返回）。
+    """档案状态快照行（``AIServicePool.available`` / ``AI.available`` 返回）。
 
     Attributes:
         name: 档案名
@@ -319,6 +314,16 @@ class TypeConfig(BaseModel):
     chain_timeout: int | None = Field(default=None, gt=0)
     profiles: dict[str, ProfileConfig]
 
+    @model_validator(mode="after")
+    def _validate_default_profile(self) -> Self:
+        """默认档案必须在该类型的 profiles 中（加载期即报，避免运行期 KeyError）。"""
+        if self.default_profile not in self.profiles:
+            raise ValueError(
+                f"default_profile 未在 profiles 中定义: {self.default_profile}"
+                f"（已知档案: {', '.join(sorted(self.profiles)) or '无'}）"
+            )
+        return self
+
 
 class RegistryConfig(BaseModel):
     """模型档案文件整体结构（顶层对象）"""
@@ -329,10 +334,22 @@ class RegistryConfig(BaseModel):
     image: TypeConfig | None = None
 
     def type_config(self, model_type: str) -> TypeConfig:
-        config = getattr(self, model_type, None)
-        if not isinstance(config, TypeConfig):
-            available = ", ".join(_MODEL_TYPES)
+        """取某类型的档案集合，区分「类型名非法」与「类型未配置」两种情况。
+
+        Raises:
+            AIConfigError: 类型名不在四类之内（调用方写错）。
+            AIModelTypeNotConfiguredError: 类型名合法但 JSON 缺该段（可预期空态，
+                ``AI.available`` 据此返回空列表）。
+        """
+        if model_type not in MODEL_TYPES:
+            available = ", ".join(MODEL_TYPES)
             raise AIConfigError(f"模型类型不存在: {model_type}，可用类型: {available}")
+        config = getattr(self, model_type)
+        if config is None:
+            raise AIModelTypeNotConfiguredError(
+                f"模型类型未配置: {model_type}"
+                f"（ai_models.json 缺少 {model_type} 段）"
+            )
         return config
 
 
@@ -384,7 +401,7 @@ class ModelRegistry:
         except (OSError, ValidationError) as exc:
             raise AIConfigError(f"模型档案文件解析失败: {config_path}: {exc}") from exc
 
-        loaded_types = [t for t in _MODEL_TYPES if getattr(self._config, t) is not None]
+        loaded_types = [t for t in MODEL_TYPES if getattr(self._config, t) is not None]
         logger.info(
             f"AI 模型档案已加载: {config_path}，类型: {', '.join(loaded_types) or '无'}"
         )
@@ -519,6 +536,15 @@ def with_api_key(profile: ModelProfile, api_key: str) -> ModelProfile:
     return replace(profile, api_key=api_key)
 
 
+def resolve_max_tokens(profile: ModelProfile, max_tokens: int | None) -> int | None:
+    """解析本次实际下发的输出上限：调用方 → 档案 → ``None``（provider 默认）。
+
+    单一数据源：``ChatService``（写入 ``StreamStats`` 与日志）与
+    ``SdkClient._chat_params``（构造请求体）共用，避免两处回落逻辑漂移。
+    """
+    return max_tokens if max_tokens is not None else profile.max_tokens
+
+
 @lru_cache(maxsize=1)
 def get_model_registry() -> ModelRegistry:
     """获取全局单例 ModelRegistry（首次调用自动 load 默认档案文件）。"""

{sdpy_kit-0.7.0 → sdpy_kit-0.7.2}/kit/ai/rerank_service.py

@@ -113,15 +113,21 @@ class RerankService(LoggingServiceBase):
         """对候选文档重排序，返回按分数降序的命中列表。
 
         Args:
+            top_n: 返回条数上限。kit 在本地保证（服务端返回超量也按分数
+                截断到 ``top_n``）；``None`` 返回服务端全部命中。``top_n <= 0``
+                直接返回空列表，不发请求
             deadline: 整链预算截止时刻（``time.monotonic()`` 秒），约束
                 5xx 重试预算；None 表示不限制
         """
         if not documents:
             return []
+        if top_n is not None and top_n <= 0:
+            return []
         payload = self._build_payload(RerankRequest(query, documents, top_n=top_n))
         with self._log_call():
             data = await self._client.post_json(payload, deadline=deadline)
-        return self._parse_response(data, documents)
+        hits = self._parse_response(data, documents)
+        return hits[:top_n] if top_n is not None else hits
 
     async def close(self) -> None:
         await self._client.close()

{sdpy_kit-0.7.0 → sdpy_kit-0.7.2}/kit/ai/rerank_transport.py

@@ -22,7 +22,7 @@ Author: Clark Chang
 
 `openai` SDK 不提供 ``/rerank`` 资源，故 rerank 保留自研传输：单次 JSON
 POST、5xx 指数退避重试、429 ``Retry-After`` 解析。语义与 0.6.9 的
-``ModelClient`` 完全一致。
+通用传输实现完全一致。
 """
 
 import asyncio

{sdpy_kit-0.7.0 → sdpy_kit-0.7.2}/kit/ai/runner.py

@@ -70,7 +70,7 @@ from collections.abc import Callable, Coroutine, Iterable, Iterator
 from dataclasses import dataclass
 from typing import Any, Final, TypeVar, cast
 
-from kit.ai.chat_service import StreamStats
+from kit.ai.chat_service import StreamStats, reset_warned
 from kit.ai.exceptions import AIConfigError, AITimeoutError
 from kit.ai.failover import (
     FailoverChatService,
@@ -80,7 +80,7 @@ from kit.ai.failover import (
 )
 from kit.ai.model_builder import Service
 from kit.ai.pool import AIServicePool
-from kit.ai.profiles import ProfileStatus, get_model_registry
+from kit.ai.profiles import MODEL_TYPES, ProfileStatus, get_model_registry
 from kit.ai.image_service import ImageResult
 from kit.ai.rerank_service import RerankHit
 from kit.config.kit_config import get_settings
@@ -96,8 +96,8 @@ _EMBEDDING = "embedding"
 _RERANK = "rerank"
 _IMAGE = "image"
 
-# 支持的模型类型集合（use/available 校验与错误提示用）
-_SERVICE_TYPES: Final[frozenset[str]] = frozenset({_CHAT, _EMBEDDING, _RERANK, _IMAGE})
+# 支持的模型类型集合（use/available 校验与错误提示用，单一数据源见 profiles）
+_SERVICE_TYPES: Final[frozenset[str]] = frozenset(MODEL_TYPES)
 
 # 常驻链式服务联合类型（按模型类型缓存于后台线程）
 FailoverService = (
@@ -279,7 +279,10 @@ class _BackgroundLoop:
         self._get_pool().prefer(model_type, profile)
 
     def available(self, model_type: str) -> list[ProfileStatus]:
-        """返回该类型全部档案状态快照（含未配置者），链头标记 current。"""
+        """返回该类型全部档案状态快照（含未配置密钥者），链头标记 current。
+
+        类型未在 ``ai_models.json`` 中配置时返回空列表。
+        """
         return self._get_pool().available(model_type)
 
     # ---------- 投递 ----------
@@ -681,7 +684,11 @@ class AI:
     def rerank(
         query: str, documents: list[str], top_n: int | None = None
     ) -> list[RerankHit]:
-        """对候选文档重排序，返回 ``RerankHit`` 降序列表（原索引、分数、原文）。"""
+        """对候选文档重排序，返回 ``RerankHit`` 降序列表（原索引、分数、原文）。
+
+        ``top_n`` 是返回条数上限，由 kit 本地保证（服务端返回超量也按分数
+        截断）；``None`` 返回服务端全部命中。
+        """
         timeout = _facade_timeout(_RERANK)
         deadline = time.monotonic() + timeout
         return _background.run(
@@ -737,17 +744,18 @@ class AI:
 
     @staticmethod
     def available(model_type: str) -> list[ProfileStatus]:
-        """返回某类型全部档案状态快照（含未配置与被剔除者），链头标 current。
+        """返回某类型全部档案状态快照（含未配置密钥与被剔除者），链头标 current。
 
         Args:
             model_type: 模型类型（chat / embedding / rerank / image）
 
         Returns:
             ``ProfileStatus`` 列表（name/model/state/current/last_error/
-            last_ok_at），供业务展示与切换决策。
+            last_ok_at），供业务展示与切换决策。**类型在 ``ai_models.json``
+            中未配置时返回空列表**（可预期空态，供界面显示「未配置」）。
 
         Raises:
-            AIConfigError: 类型不存在或注册表未加载。
+            AIConfigError: 类型名非法（不在四类之内）或注册表未加载。
         """
         return _background.available(model_type)
 
@@ -1064,6 +1072,8 @@ def reload_config(
     # 4. 后台 loop 内摘链、清常驻服务并调度旧 service 关闭
     types = sorted(_SERVICE_TYPES) if model_type is None else [model_type]
     _background.invalidate(frozenset(types), probe=probe, immediate=immediate)
+    # 4.1 重置告警去重：修正档案后同一原因应能再次提示（去重键不含配置指纹）
+    reset_warned()
     # 5. 快照新 embedding，判定变更（model 或 dimension 任一变化即告警）
     current = _embedding_snapshot()
     changed = previous is not None and current is not None and previous != current

{sdpy_kit-0.7.0 → sdpy_kit-0.7.2}/kit/ai/sdk_client.py

@@ -54,7 +54,7 @@ from kit.ai.exceptions import (
     AIResponseError,
     AITimeoutError,
 )
-from kit.ai.profiles import ModelProfile
+from kit.ai.profiles import ModelProfile, resolve_max_tokens
 from kit.ai.types import JSONObject
 from kit.config.log_config import get_default_logger
 
@@ -193,9 +193,7 @@ class SdkClient:
         }
         if temperature is not None:
             params["temperature"] = temperature
-        effective_max_tokens = (
-            max_tokens if max_tokens is not None else self._profile.max_tokens
-        )
+        effective_max_tokens = resolve_max_tokens(self._profile, max_tokens)
         if effective_max_tokens is not None:
             params["max_tokens"] = effective_max_tokens
         if response_format is not None:

{sdpy_kit-0.7.0 → sdpy_kit-0.7.2}/kit/docs/md2doc_kit.py

@@ -1724,7 +1724,6 @@ class Md2DocKit:
         *,
         generate_toc: bool = False,
         mainfont: str = "宋体",
-        reference_doc: str | Path | None = None,
     ) -> str:
         """将 Markdown 文件转换为 Word（.docx）文件（基于 PiMD）
 
@@ -1732,9 +1731,7 @@ class Md2DocKit:
         生成 docx，支持标题、列表、表格（表头深蓝底加粗）、代码块、链接
         等语法；可通过 generate_toc 在文档开头插入目录。
         全文字体统一为 mainfont（默认宋体）：转换后改写 docDefaults 与
-        主题字体（正文/标题/表格全部生效），代码块保持等宽字体；
-        reference_doc 参数仅保留签名兼容（PiMD 的 md_to_docx 不接收参考
-        模板，传入不生效）。
+        主题字体（正文/标题/表格全部生效），代码块保持等宽字体。
 
         图片（`![alt](相对路径)`）以内嵌图片段落回填：PiMD 会把行内图片
         降级为「alt 文本 + 超链接」，此处按占位标记替换为真实图片并居中，
@@ -1751,7 +1748,6 @@ class Md2DocKit:
             dest_path: 目标 Word 文件路径；None 时使用源文件名同目录加 .docx 后缀
             generate_toc: 是否在文档开头插入目录
             mainfont: 文档全局字体名（Word 字体名，如 "宋体"/"黑体"），默认宋体
-            reference_doc: 仅保留签名兼容；PiMD 不接收参考模板，传入不生效
 
         Returns:
             str: 实际写入的 Word 文件绝对路径
@@ -1769,11 +1765,6 @@ class Md2DocKit:
         """
         src, dest = _resolve_md_paths(src_path, dest_path, ".docx")
         logger.info(f"开始转换 Markdown 为 Word: {src.name}")
-        if reference_doc is not None:
-            # 保留签名兼容：PiMD 的 md_to_docx 不接收参考模板，传入不生效
-            logger.warning(
-                "reference_doc 参数已废弃（PiMD 不支持参考模板），传入不生效"
-            )
 
         # CJK 加粗预处理；临时 md 与源文件同目录，保证相对图片路径仍然可用
         processed = _normalize_cjk_bold(src.read_text(encoding="utf-8"))