sdpy-kit 0.6.11__tar.gz → 0.7.1__tar.gz

{sdpy_kit-0.6.11 → sdpy_kit-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sdpy-kit
-Version: 0.6.11
+Version: 0.7.1
 Summary: SDPY Kit——统一数据库访问层（PG/MySQL/SQLite）与 AI/Redis/文件/文档/向量工具集
 Author-email: Clark <changhongyuan@126.com>
 License-Expression: MIT
@@ -26,27 +26,6 @@ Provides-Extra: ai
 Requires-Dist: httpx>=0.28.1; extra == 'ai'
 Requires-Dist: openai<4,>=3.44; extra == 'ai'
 Requires-Dist: python-dotenv>=1.2.4; extra == 'ai'
-Provides-Extra: all
-Requires-Dist: decima-ai>=2.5.1; extra == 'all'
-Requires-Dist: docxtpl>=0.20.2; extra == 'all'
-Requires-Dist: firecrawl-anydoc>=0.2.4; extra == 'all'
-Requires-Dist: httpx>=0.28.1; extra == 'all'
-Requires-Dist: huggingface-hub<2,>=1.5; extra == 'all'
-Requires-Dist: laya>=0.4.22; extra == 'all'
-Requires-Dist: markdown-it-py>=4.2.0; extra == 'all'
-Requires-Dist: numpy>=2.5.4; extra == 'all'
-Requires-Dist: onnxruntime>=1.18; extra == 'all'
-Requires-Dist: openai<4,>=3.44; extra == 'all'
-Requires-Dist: pikepdf>=10.17.0; extra == 'all'
-Requires-Dist: pimd[pdfa]>=2.2.5; extra == 'all'
-Requires-Dist: psycopg2-binary>=2.9.13; extra == 'all'
-Requires-Dist: pymysql>=1.2.3; extra == 'all'
-Requires-Dist: python-dotenv>=1.2.4; extra == 'all'
-Requires-Dist: rc-docparser>=0.2.2; extra == 'all'
-Requires-Dist: redis>=8.1.0; extra == 'all'
-Requires-Dist: requests>=2.34.2; extra == 'all'
-Requires-Dist: sqliteai-vector>=1.2.0; extra == 'all'
-Requires-Dist: trafilatura>=2.3.1; extra == 'all'
 Provides-Extra: anydoc
 Requires-Dist: firecrawl-anydoc>=0.2.4; extra == 'anydoc'
 Requires-Dist: pikepdf>=10.17.0; extra == 'anydoc'
@@ -61,10 +40,9 @@ Requires-Dist: rc-docparser>=0.2.2; extra == 'docx-parse'
 Provides-Extra: laya
 Requires-Dist: huggingface-hub<2,>=1.5; extra == 'laya'
 Requires-Dist: laya>=0.4.22; extra == 'laya'
-Provides-Extra: marker
-Requires-Dist: marker-pdf>=2.0.0; extra == 'marker'
 Provides-Extra: md2doc
 Requires-Dist: markdown-it-py>=4.2.0; extra == 'md2doc'
+Requires-Dist: pillow>=13.0.0; extra == 'md2doc'
 Requires-Dist: pimd[pdfa]>=2.2.5; extra == 'md2doc'
 Provides-Extra: mineru
 Requires-Dist: requests>=2.34.2; extra == 'mineru'
@@ -72,6 +50,27 @@ Provides-Extra: mysql
 Requires-Dist: pymysql>=1.2.3; extra == 'mysql'
 Provides-Extra: pg
 Requires-Dist: psycopg2-binary>=2.9.13; extra == 'pg'
+Provides-Extra: recommended
+Requires-Dist: decima-ai>=2.5.1; extra == 'recommended'
+Requires-Dist: docxtpl>=0.20.2; extra == 'recommended'
+Requires-Dist: firecrawl-anydoc>=0.2.4; extra == 'recommended'
+Requires-Dist: httpx>=0.28.1; extra == 'recommended'
+Requires-Dist: huggingface-hub<2,>=1.5; extra == 'recommended'
+Requires-Dist: laya>=0.4.22; extra == 'recommended'
+Requires-Dist: markdown-it-py>=4.2.0; extra == 'recommended'
+Requires-Dist: numpy>=2.5.4; extra == 'recommended'
+Requires-Dist: onnxruntime>=1.18; extra == 'recommended'
+Requires-Dist: openai<4,>=3.44; extra == 'recommended'
+Requires-Dist: pikepdf>=10.17.0; extra == 'recommended'
+Requires-Dist: pimd[pdfa]>=2.2.5; extra == 'recommended'
+Requires-Dist: psycopg2-binary>=2.9.13; extra == 'recommended'
+Requires-Dist: pymysql>=1.2.3; extra == 'recommended'
+Requires-Dist: python-dotenv>=1.2.4; extra == 'recommended'
+Requires-Dist: rc-docparser>=0.2.2; extra == 'recommended'
+Requires-Dist: redis>=8.1.0; extra == 'recommended'
+Requires-Dist: requests>=2.34.2; extra == 'recommended'
+Requires-Dist: sqliteai-vector>=1.2.0; extra == 'recommended'
+Requires-Dist: trafilatura>=2.3.1; extra == 'recommended'
 Provides-Extra: redis
 Requires-Dist: redis>=8.1.0; extra == 'redis'
 Provides-Extra: sqliteai
@@ -87,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+
 
@@ -107,7 +106,7 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 | `kit.docs.rc_docparser_kit` | `RcDocParserKit` | 离线 docx → Markdown + Images（无模型） | `docx-parse` |
 | `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.docs.marker_kit` | `MarkerKit` | 本地解析（PDF / 图片 → Markdown + Images）；**0.7.0 起暂停发布**，需要请用 `sdpy-kit==0.6.10` | — |
 | `kit.laya_kit` | `LayaKit` | 类型化决策：choice / multi_choice 多选 / score / noul，另含 decide 多字段 / decide_batch 批量 / predict_long 长文本 | `laya` |
 | `kit.decima_kit` | `DecimaKit` | 决策模型：choice / score / noul / multi_choice（原生 rank）；选项乱序不变、置信度可门控；另含 predict / predict_long / brief / choice_batch（方法名与 `LayaKit` 对齐） | `decima` |
 | `kit.crawl.article_models` | `ArticleInfo` / `ArticleResult` / `SavedOutput` 等 | 文章抓取通用模型（三个 `*ArticleKit` 共用，含 `reason` 分类与非致命 `warnings`） | 无 |
@@ -138,11 +137,10 @@ uv add sdpy-kit
 | `docx` | DocxKit 模板动态填充（docxtpl） | `pip install "sdpy-kit[docx]"` |
 | `docx-parse` | RcDocParserKit 离线 docx 解析（rc-docparser → Markdown + images/） | `pip install "sdpy-kit[docx-parse]"` |
 | `mineru` | MinerUKit 解析 API（精准解析 + Agent 轻量解析） | `pip install "sdpy-kit[mineru]"` |
-| `marker` | MarkerKit 本地解析（marker-pdf → Markdown + Images；PDF + 图片，依赖体积大）。**与 `[ai]` 互斥**：marker-pdf 锁 `openai<3`，不能与 `openai>=3.44` 同环境安装 | `pip install "sdpy-kit[marker]"` |
 | `laya` | LayaKit 类型化决策（laya + torch，本地小模型 choice / multi_choice / score / noul；支持多字段 / 批量 / 长文本） | `pip install "sdpy-kit[laya]"` |
 | `decima` | DecimaKit 决策模型（decima-ai + onnxruntime，**无 torch**；选项乱序不变、置信度可门控；磁盘约 137 MB） | `pip install "sdpy-kit[decima]"` |
 | `web-article` | WebArticleKit 通用网页文章抓取转存（trafilatura，纯 HTTP 无浏览器） | `pip install "sdpy-kit[web-article]"` |
-| `all` | 常用能力集合，**不含 `marker`**（0.6.11 起，避免与 `[ai]` 的 openai 约束冲突）；需要 Marker 请单独装 `[marker]` | `pip install "sdpy-kit[all]"` |
+| `recommended` | 常用能力集合（DB / 缓存 / AI / 文档 / 抓取）；不含重依赖（laya / decima）与 Marker（0.7.0 起暂停发布） | `pip install "sdpy-kit[recommended]"` |
 
 ## 配置（.env）
 
@@ -811,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 与探活仍使用该字段。
@@ -837,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` / `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[tuple[int, float]]` | 返回 `[(原索引, 相关分)]` 降序列表 |
-| image | `generate_image(prompt, *, size=None, n=1) -> str` | 文生图，返回图片 URL |
+| 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
@@ -856,30 +869,42 @@ with AI.chat_stream([{"role": "user", "content": "写一首短诗"}]) as stream:
 
 #### 流式收尾统计（思考型模型必备）
 
-迭代器在流结束后可读六个只读属性（`reasoning_chars` / `content_chars` / `finish_reason` /
-`truncated` / `thinking_applied` / `json_mode_applied`），用于区分「模型真的没返回」与「输出预算被思考吃光」——思考型模型的推理
+迭代器在流结束后可读七个只读属性（`reasoning_chars` / `content_chars` / `finish_reason` /
+`truncated` / `empty_kind` / `thinking_applied` / `json_mode_applied`），用于区分「模型真的没返回」与「输出预算被思考吃光」——思考型模型的推理
 token 计入 `max_tokens`，长上下文 + 小预算时常出现「返回 200 但正文为空」（同一套字段也可用于非流式 `ask` / `complete`，
-见下文「结构化输出」）：
+见下文「结构化输出」）。
+
+`empty_kind` 把「正文为空」分成四类，不再一律归因为预算耗尽：
+
+| 取值 | 判定 | 建议处置 |
+|---|---|---|
+| `budget_exhausted` | 被长度截断且有推理 | 调大 `max_tokens`，或对该调用传 `thinking=False` |
+| `reasoning_only` | 有推理、`finish_reason=stop`、正文 0 | 提高预算或换模型 |
+| `no_finish` | 有推理但没收到结束原因（链路中断 / 端点未收尾） | 优先重试，连续出现检查端点/代理超时 |
+| `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":
+            ...  # 调大 max_tokens 或 thinking=False
+        case "no_finish":
+            ...  # 优先重试
 ```
 
 - 推理字段兼容 `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`；
 - 流式过程中读到的是尽力而为的中间值，**结束后才是最终值**；提前 `break` 时为截至中断的累计值。
 
-#### 逐调用思考开关（0.6.7）
+#### 逐调用思考开关
 
 同一档案下按调用点切换思考（入库抽取关、章节生成开），不必复制档案：
 
@@ -898,14 +923,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` 原样透传：
 
@@ -965,7 +990,7 @@ if stats.truncated:          # finish_reason 为 length / max_tokens
 from kit.ai import (
     ChatService, EmbeddingService, RerankService, ImageService,   # 服务类
     ChatRequest, EmbeddingRequest, RerankRequest, ImageRequest,   # 请求模型
-    RerankHit, StreamStats, ModelBuilder,                         # 结果类型 / 构建器
+    RerankHit, ImageResult, StreamStats, ModelBuilder,            # 结果类型 / 构建器
 )
 
 service = ModelBuilder.build_chat()                 # 老按类型构建：build_chat / build_embedding / build_rerank / build_image
@@ -978,7 +1003,7 @@ await service.close()
 | `ChatService` | `ask(messages, *, temperature=None, max_tokens=None, thinking=None, json_mode=None, response_format=None, stats: StreamStats \| None = None, deadline=None) -> str`、`complete(prompt, *, ...) -> str`、`stream(messages, *, ..., stats: StreamStats \| None = None) -> AsyncIterator[str]`（传 `StreamStats()` 即可读收尾统计）；`thinking` / `json_mode` / `response_format` 语义与门面一致 |
 | `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` |
+| `ImageService` | `generate(prompt, *, size=None, n=1, return_base64=False, ratio=None) -> ImageResult` |
 | `ModelBuilder` | `build(model_type, model=None, *, api_key=None)` 及各类型专用 `build_chat / build_embedding / build_rerank / build_image` |
 | `BaseAIService` | `profile` 属性、`await close()`、支持 `async with` |
 
@@ -1230,7 +1255,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（实验性，内部使用；图片等比限宽居中） |
 
@@ -1278,7 +1303,11 @@ if r.state == "done":
 
 ## kit.docs.marker_kit —— 本地解析：PDF + 图片 → Markdown + Images
 
-安装：`pip install "sdpy-kit[marker]"`（依赖 `marker-pdf`，含 torch 等 80+ 包，体积较大；不含 `[full]`）
+> ⚠ **0.7.0 起暂停发布**：`marker-pdf` 仍锁 `openai<3`，与 `ai` extra 冲突。本包**不包含**该模块，
+> 也不提供 `marker` extra。需要此能力请用 `pip install "sdpy-kit[marker]==0.6.10"`。
+> 以下接口说明仅作参考。
+
+0.6.10 的安装方式：`pip install "sdpy-kit[marker]"`（依赖 `marker-pdf`，含 torch 等 80+ 包，体积较大）
 
 支持面：`.pdf`、`.png`、`.jpg`、`.jpeg`、`.webp`、`.gif`、`.bmp`。docx/pptx/xlsx/html/epub 不在支持面
 （marker 侧实现依赖 weasyprint/GTK），传入会抛 `ValueError`。
@@ -1609,13 +1638,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` 声明两种实测形态（按平台各自写入档案）：
@@ -1637,11 +1666,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.6.11 → sdpy_kit-0.7.1}/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+
 
@@ -24,7 +24,7 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 | `kit.docs.rc_docparser_kit` | `RcDocParserKit` | 离线 docx → Markdown + Images（无模型） | `docx-parse` |
 | `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.docs.marker_kit` | `MarkerKit` | 本地解析（PDF / 图片 → Markdown + Images）；**0.7.0 起暂停发布**，需要请用 `sdpy-kit==0.6.10` | — |
 | `kit.laya_kit` | `LayaKit` | 类型化决策：choice / multi_choice 多选 / score / noul，另含 decide 多字段 / decide_batch 批量 / predict_long 长文本 | `laya` |
 | `kit.decima_kit` | `DecimaKit` | 决策模型：choice / score / noul / multi_choice（原生 rank）；选项乱序不变、置信度可门控；另含 predict / predict_long / brief / choice_batch（方法名与 `LayaKit` 对齐） | `decima` |
 | `kit.crawl.article_models` | `ArticleInfo` / `ArticleResult` / `SavedOutput` 等 | 文章抓取通用模型（三个 `*ArticleKit` 共用，含 `reason` 分类与非致命 `warnings`） | 无 |
@@ -55,11 +55,10 @@ uv add sdpy-kit
 | `docx` | DocxKit 模板动态填充（docxtpl） | `pip install "sdpy-kit[docx]"` |
 | `docx-parse` | RcDocParserKit 离线 docx 解析（rc-docparser → Markdown + images/） | `pip install "sdpy-kit[docx-parse]"` |
 | `mineru` | MinerUKit 解析 API（精准解析 + Agent 轻量解析） | `pip install "sdpy-kit[mineru]"` |
-| `marker` | MarkerKit 本地解析（marker-pdf → Markdown + Images；PDF + 图片，依赖体积大）。**与 `[ai]` 互斥**：marker-pdf 锁 `openai<3`，不能与 `openai>=3.44` 同环境安装 | `pip install "sdpy-kit[marker]"` |
 | `laya` | LayaKit 类型化决策（laya + torch，本地小模型 choice / multi_choice / score / noul；支持多字段 / 批量 / 长文本） | `pip install "sdpy-kit[laya]"` |
 | `decima` | DecimaKit 决策模型（decima-ai + onnxruntime，**无 torch**；选项乱序不变、置信度可门控；磁盘约 137 MB） | `pip install "sdpy-kit[decima]"` |
 | `web-article` | WebArticleKit 通用网页文章抓取转存（trafilatura，纯 HTTP 无浏览器） | `pip install "sdpy-kit[web-article]"` |
-| `all` | 常用能力集合，**不含 `marker`**（0.6.11 起，避免与 `[ai]` 的 openai 约束冲突）；需要 Marker 请单独装 `[marker]` | `pip install "sdpy-kit[all]"` |
+| `recommended` | 常用能力集合（DB / 缓存 / AI / 文档 / 抓取）；不含重依赖（laya / decima）与 Marker（0.7.0 起暂停发布） | `pip install "sdpy-kit[recommended]"` |
 
 ## 配置（.env）
 
@@ -728,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 与探活仍使用该字段。
@@ -754,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` / `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[tuple[int, float]]` | 返回 `[(原索引, 相关分)]` 降序列表 |
-| image | `generate_image(prompt, *, size=None, n=1) -> str` | 文生图，返回图片 URL |
+| 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
@@ -773,30 +787,42 @@ with AI.chat_stream([{"role": "user", "content": "写一首短诗"}]) as stream:
 
 #### 流式收尾统计（思考型模型必备）
 
-迭代器在流结束后可读六个只读属性（`reasoning_chars` / `content_chars` / `finish_reason` /
-`truncated` / `thinking_applied` / `json_mode_applied`），用于区分「模型真的没返回」与「输出预算被思考吃光」——思考型模型的推理
+迭代器在流结束后可读七个只读属性（`reasoning_chars` / `content_chars` / `finish_reason` /
+`truncated` / `empty_kind` / `thinking_applied` / `json_mode_applied`），用于区分「模型真的没返回」与「输出预算被思考吃光」——思考型模型的推理
 token 计入 `max_tokens`，长上下文 + 小预算时常出现「返回 200 但正文为空」（同一套字段也可用于非流式 `ask` / `complete`，
-见下文「结构化输出」）：
+见下文「结构化输出」）。
+
+`empty_kind` 把「正文为空」分成四类，不再一律归因为预算耗尽：
+
+| 取值 | 判定 | 建议处置 |
+|---|---|---|
+| `budget_exhausted` | 被长度截断且有推理 | 调大 `max_tokens`，或对该调用传 `thinking=False` |
+| `reasoning_only` | 有推理、`finish_reason=stop`、正文 0 | 提高预算或换模型 |
+| `no_finish` | 有推理但没收到结束原因（链路中断 / 端点未收尾） | 优先重试，连续出现检查端点/代理超时 |
+| `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":
+            ...  # 调大 max_tokens 或 thinking=False
+        case "no_finish":
+            ...  # 优先重试
 ```
 
 - 推理字段兼容 `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`；
 - 流式过程中读到的是尽力而为的中间值，**结束后才是最终值**；提前 `break` 时为截至中断的累计值。
 
-#### 逐调用思考开关（0.6.7）
+#### 逐调用思考开关
 
 同一档案下按调用点切换思考（入库抽取关、章节生成开），不必复制档案：
 
@@ -815,14 +841,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` 原样透传：
 
@@ -882,7 +908,7 @@ if stats.truncated:          # finish_reason 为 length / max_tokens
 from kit.ai import (
     ChatService, EmbeddingService, RerankService, ImageService,   # 服务类
     ChatRequest, EmbeddingRequest, RerankRequest, ImageRequest,   # 请求模型
-    RerankHit, StreamStats, ModelBuilder,                         # 结果类型 / 构建器
+    RerankHit, ImageResult, StreamStats, ModelBuilder,            # 结果类型 / 构建器
 )
 
 service = ModelBuilder.build_chat()                 # 老按类型构建：build_chat / build_embedding / build_rerank / build_image
@@ -895,7 +921,7 @@ await service.close()
 | `ChatService` | `ask(messages, *, temperature=None, max_tokens=None, thinking=None, json_mode=None, response_format=None, stats: StreamStats \| None = None, deadline=None) -> str`、`complete(prompt, *, ...) -> str`、`stream(messages, *, ..., stats: StreamStats \| None = None) -> AsyncIterator[str]`（传 `StreamStats()` 即可读收尾统计）；`thinking` / `json_mode` / `response_format` 语义与门面一致 |
 | `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` |
+| `ImageService` | `generate(prompt, *, size=None, n=1, return_base64=False, ratio=None) -> ImageResult` |
 | `ModelBuilder` | `build(model_type, model=None, *, api_key=None)` 及各类型专用 `build_chat / build_embedding / build_rerank / build_image` |
 | `BaseAIService` | `profile` 属性、`await close()`、支持 `async with` |
 
@@ -1147,7 +1173,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（实验性，内部使用；图片等比限宽居中） |
 
@@ -1195,7 +1221,11 @@ if r.state == "done":
 
 ## kit.docs.marker_kit —— 本地解析：PDF + 图片 → Markdown + Images
 
-安装：`pip install "sdpy-kit[marker]"`（依赖 `marker-pdf`，含 torch 等 80+ 包，体积较大；不含 `[full]`）
+> ⚠ **0.7.0 起暂停发布**：`marker-pdf` 仍锁 `openai<3`，与 `ai` extra 冲突。本包**不包含**该模块，
+> 也不提供 `marker` extra。需要此能力请用 `pip install "sdpy-kit[marker]==0.6.10"`。
+> 以下接口说明仅作参考。
+
+0.6.10 的安装方式：`pip install "sdpy-kit[marker]"`（依赖 `marker-pdf`，含 torch 等 80+ 包，体积较大）
 
 支持面：`.pdf`、`.png`、`.jpg`、`.jpeg`、`.webp`、`.gif`、`.bmp`。docx/pptx/xlsx/html/epub 不在支持面
 （marker 侧实现依赖 weasyprint/GTK），传入会抛 `ValueError`。
@@ -1526,13 +1556,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` 声明两种实测形态（按平台各自写入档案）：
@@ -1554,11 +1584,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.6.11 → sdpy_kit-0.7.1}/kit/__init__.py

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

{sdpy_kit-0.6.11 → sdpy_kit-0.7.1}/kit/ai/__init__.py

@@ -29,7 +29,7 @@ Author: Clark Chang
 
 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.image_service import ImageRequest, ImageResult, ImageService
 from kit.ai.model_builder import ModelBuilder
 from kit.ai.rerank_service import RerankHit, RerankRequest, RerankService
 
@@ -39,6 +39,7 @@ __all__ = [
     "EmbeddingRequest",
     "EmbeddingService",
     "ImageRequest",
+    "ImageResult",
     "ImageService",
     "ModelBuilder",
     "RerankHit",