yimo-kit 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (70) hide show
  1. yimo/__init__.py +26 -0
  2. yimo/kit/__init__.py +98 -0
  3. yimo/kit/ai/__init__.py +110 -0
  4. yimo/kit/ai/_internal/__init__.py +27 -0
  5. yimo/kit/ai/_internal/failover.py +535 -0
  6. yimo/kit/ai/_internal/pool.py +526 -0
  7. yimo/kit/ai/_internal/rerank_transport.py +137 -0
  8. yimo/kit/ai/_internal/retry_after.py +51 -0
  9. yimo/kit/ai/_internal/sdk_client.py +463 -0
  10. yimo/kit/ai/_internal/service_base.py +115 -0
  11. yimo/kit/ai/_internal/types.py +28 -0
  12. yimo/kit/ai/agent/__init__.py +127 -0
  13. yimo/kit/ai/agent/approval.py +66 -0
  14. yimo/kit/ai/agent/errors.py +128 -0
  15. yimo/kit/ai/agent/loop.py +643 -0
  16. yimo/kit/ai/agent/mcp.py +278 -0
  17. yimo/kit/ai/agent/registry.py +203 -0
  18. yimo/kit/ai/agent/session.py +150 -0
  19. yimo/kit/ai/agent/skill.py +370 -0
  20. yimo/kit/ai/agent/types.py +161 -0
  21. yimo/kit/ai/chat_service.py +724 -0
  22. yimo/kit/ai/decision/__init__.py +57 -0
  23. yimo/kit/ai/decision/decima.py +853 -0
  24. yimo/kit/ai/decision/laya.py +552 -0
  25. yimo/kit/ai/embedding_service.py +198 -0
  26. yimo/kit/ai/exceptions.py +109 -0
  27. yimo/kit/ai/image_service.py +84 -0
  28. yimo/kit/ai/messages.py +105 -0
  29. yimo/kit/ai/model_builder.py +121 -0
  30. yimo/kit/ai/model_client.py +62 -0
  31. yimo/kit/ai/profiles.py +577 -0
  32. yimo/kit/ai/rerank_service.py +136 -0
  33. yimo/kit/ai/runner.py +1127 -0
  34. yimo/kit/common_kit.py +221 -0
  35. yimo/kit/config/__init__.py +44 -0
  36. yimo/kit/config/kit_config.py +210 -0
  37. yimo/kit/config/log_config.py +171 -0
  38. yimo/kit/crawl/__init__.py +71 -0
  39. yimo/kit/crawl/article_io.py +325 -0
  40. yimo/kit/crawl/article_models.py +172 -0
  41. yimo/kit/crawl/deepseek_kit.py +673 -0
  42. yimo/kit/crawl/web_article_kit.py +638 -0
  43. yimo/kit/crawl/wx_article_kit.py +692 -0
  44. yimo/kit/db/__init__.py +101 -0
  45. yimo/kit/db/audit.py +625 -0
  46. yimo/kit/db/base_db_kit.py +1265 -0
  47. yimo/kit/db/crud.py +423 -0
  48. yimo/kit/db/engine.py +235 -0
  49. yimo/kit/db/exceptions.py +45 -0
  50. yimo/kit/db/models/__init__.py +33 -0
  51. yimo/kit/db/models/base.py +56 -0
  52. yimo/kit/db/mysql_kit.py +348 -0
  53. yimo/kit/db/pg_kit.py +442 -0
  54. yimo/kit/db/query.py +338 -0
  55. yimo/kit/db/session.py +85 -0
  56. yimo/kit/db/sqlite_kit.py +462 -0
  57. yimo/kit/db/transaction.py +109 -0
  58. yimo/kit/docs/__init__.py +34 -0
  59. yimo/kit/docs/anydoc_kit.py +490 -0
  60. yimo/kit/docs/docx_kit.py +895 -0
  61. yimo/kit/docs/md2doc_kit.py +1801 -0
  62. yimo/kit/docs/mineru_kit.py +1497 -0
  63. yimo/kit/docs/rc_docparser_kit.py +654 -0
  64. yimo/kit/file_kit.py +518 -0
  65. yimo/kit/license_kit.py +533 -0
  66. yimo/kit/redis_kit.py +392 -0
  67. yimo_kit-0.1.0.dist-info/METADATA +1673 -0
  68. yimo_kit-0.1.0.dist-info/RECORD +70 -0
  69. yimo_kit-0.1.0.dist-info/WHEEL +4 -0
  70. yimo_kit-0.1.0.dist-info/licenses/LICENSE +201 -0
@@ -0,0 +1,71 @@
1
+ """
2
+ Copyright (c) 2021-2026 溢墨修心(Yimo). All Rights Reserved.
3
+
4
+ Licensed under the Apache License, Version 2.0 (the "License");
5
+ you may not use this file except in compliance with the License.
6
+ You may obtain a copy of the License at
7
+
8
+ http://www.apache.org/licenses/LICENSE-2.0
9
+
10
+ Unless required by applicable law or agreed to in writing, software
11
+ distributed under the License is distributed on an "AS IS" BASIS,
12
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
+ See the License for the specific language governing permissions and
14
+ limitations under the License.
15
+
16
+ Project: yimo
17
+ Author: 溢墨修心(Yimo)
18
+ """
19
+
20
+ # date: 2026-10-14
21
+ """文章爬取工具包(与 `yimo.kit.ai` / `yimo.kit.db` 平级的子包)
22
+
23
+ 收纳文章抓取相关模块:
24
+
25
+ - `yimo.kit.crawl.article_models`:平台中立的通用模型(零依赖,三个 Kit 共用);
26
+ - `yimo.kit.crawl.article_io`:落盘公共层(md + images/ + meta.json,三个 Kit 共用);
27
+ - `yimo.kit.crawl.wx_article_kit`:`WxArticleKit`,微信公众号文章抓取存储(零依赖);
28
+ - `yimo.kit.crawl.web_article_kit`:`WebArticleKit`,通用网页抓取(extra `web-article`);
29
+ - `yimo.kit.crawl.deepseek_kit`:`DeepSeekKit`,DeepSeek Search / Fetch(需 API Key)。
30
+
31
+ 本模块**只导出零依赖的模型符号**;三个 Kit 保持按需 import(`from yimo.kit.crawl.xxx_kit
32
+ import ...`),以免基础安装即要求 `trafilatura` 等可选依赖。
33
+ """
34
+
35
+ from yimo.kit.crawl.article_models import (
36
+ REASON_AUTH_FAILED,
37
+ REASON_CONFIG_MISSING,
38
+ REASON_FETCH_BLOCKED,
39
+ REASON_FETCH_FAILED,
40
+ REASON_NO_CONTENT,
41
+ REASON_RATE_LIMITED,
42
+ REASON_RISK_CONTROL,
43
+ REASON_UNSUPPORTED_SOURCE,
44
+ REASONS,
45
+ ArticleImage,
46
+ ArticleInfo,
47
+ ArticleLink,
48
+ ArticleResult,
49
+ CodeBlock,
50
+ SavedOutput,
51
+ )
52
+
53
+ __all__ = [
54
+ # 模型
55
+ "ArticleImage",
56
+ "ArticleInfo",
57
+ "ArticleLink",
58
+ "ArticleResult",
59
+ "CodeBlock",
60
+ "SavedOutput",
61
+ # 失败原因取值
62
+ "REASONS",
63
+ "REASON_UNSUPPORTED_SOURCE",
64
+ "REASON_FETCH_BLOCKED",
65
+ "REASON_FETCH_FAILED",
66
+ "REASON_NO_CONTENT",
67
+ "REASON_RISK_CONTROL",
68
+ "REASON_AUTH_FAILED",
69
+ "REASON_RATE_LIMITED",
70
+ "REASON_CONFIG_MISSING",
71
+ ]
@@ -0,0 +1,325 @@
1
+ """
2
+ Copyright (c) 2021-2026 溢墨修心(Yimo). All Rights Reserved.
3
+
4
+ Licensed under the Apache License, Version 2.0 (the "License");
5
+ you may not use this file except in compliance with the License.
6
+ You may obtain a copy of the License at
7
+
8
+ http://www.apache.org/licenses/LICENSE-2.0
9
+
10
+ Unless required by applicable law or agreed to in writing, software
11
+ distributed under the License is distributed on an "AS IS" BASIS,
12
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
+ See the License for the specific language governing permissions and
14
+ limitations under the License.
15
+
16
+ Project: yimo
17
+ Author: 溢墨修心(Yimo)
18
+ """
19
+
20
+ # date: 2026-10-21
21
+ """文章落盘公共层(三个 `*ArticleKit` 共用,零第三方依赖)
22
+
23
+ `WxArticleKit` / `WebArticleKit` / `DeepSeekKit` 的 `save()` 只负责"取回正文",
24
+ 落盘统一走本模块,避免三份逐行复制的实现各自漂移。
25
+
26
+ 产物契约(三家完全一致):
27
+
28
+ ```
29
+ <output_dir>/<stem>/
30
+ ├── <stem>.md # YAML 头:title / author / publish_time / source / source_url
31
+ ├── images/ # 正文含图则 NNN.ext;无图时为空目录
32
+ └── meta.json # 默认产出;写 meta.json=False 时省略
33
+ ```
34
+
35
+ 命名规则:
36
+
37
+ - `stem` 显式传入 → 原样使用(去尾部 `.md`),**同名目录直接复用**(覆盖语义);
38
+ - `stem` 未传 → 本地时间 `%y%m%d%H%M%S`;同秒目录已存在时依次追加 `-2`…`-99`。
39
+
40
+ **本模块不得引入第三方依赖**:`web_article_kit` 顶层 import trafilatura,
41
+ 若公共层被它传染,基础安装下 `WxArticleKit` / `DeepSeekKit` 将无法导入。
42
+
43
+ 使用方式(仅供三个 Kit 内部调用):
44
+
45
+ from yimo.kit.crawl import article_io
46
+
47
+ stem = article_io.resolve_stem(file_name, output_dir)
48
+ result = cls.fetch(url)
49
+ return article_io.save_article(result, output_dir, stem, label="网页文章")
50
+ """
51
+
52
+ import json
53
+ import socket
54
+ import urllib.error
55
+ import urllib.parse
56
+ import urllib.request
57
+ from collections.abc import Callable
58
+ from datetime import datetime, timedelta, timezone
59
+ from pathlib import Path
60
+
61
+ from yimo.kit.config.log_config import get_default_logger
62
+ from yimo.kit.crawl.article_models import (
63
+ REASON_NO_CONTENT,
64
+ ArticleImage,
65
+ ArticleInfo,
66
+ ArticleResult,
67
+ SavedOutput,
68
+ )
69
+
70
+ logger = get_default_logger(__name__)
71
+
72
+ # 图片扩展名推断函数:url -> 扩展名(空串表示未推断出,交由后续兜底)
73
+ ImageExtResolver = Callable[[str], str]
74
+
75
+ # Asia/Shanghai(东八区,无夏令时)固定偏移
76
+ _TZ_SHANGHAI = timezone(timedelta(hours=8))
77
+
78
+ # 自动命名格式:年月日时分秒(12 位)
79
+ _TS_FORMAT = "%y%m%d%H%M%S"
80
+
81
+ # 同秒碰撞的最大尝试后缀(-2 … -99)
82
+ _MAX_COLLISION_SUFFIX = 99
83
+
84
+ # 默认图片下载超时(秒)
85
+ DEFAULT_TIMEOUT = 20.0
86
+
87
+ # 允许的图片扩展名
88
+ _IMG_EXTS = frozenset({"png", "jpg", "jpeg", "gif", "webp", "bmp"})
89
+
90
+ # 图片响应 Content-Type → 扩展名(URL 无扩展名时的兜底,如带签名的 CDN 图片)
91
+ _CT_EXTS = {
92
+ "image/jpeg": "jpg",
93
+ "image/jpg": "jpg",
94
+ "image/png": "png",
95
+ "image/gif": "gif",
96
+ "image/webp": "webp",
97
+ "image/bmp": "bmp",
98
+ }
99
+
100
+ # 图片下载 UA(部分 CDN 对空 UA 返回 403)
101
+ _DEFAULT_UA = (
102
+ "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
103
+ "(KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36"
104
+ )
105
+
106
+
107
+ def normalize_image_ext(raw: str) -> str:
108
+ """把候选扩展名规整为受支持集合内的值(`jpeg` → `jpg`,非法返回空串)
109
+
110
+ 供各 Kit 的 `ext_resolver` 使用(如微信从 `wx_fmt=` 参数取值)。
111
+ """
112
+ ext = (raw or "").strip().lstrip(".").lower()
113
+ if ext == "jpeg":
114
+ return "jpg"
115
+ return ext if ext in _IMG_EXTS else ""
116
+
117
+
118
+ def resolve_stem(file_name: str | None, output_dir: str | Path) -> str:
119
+ """解析产物目录名与 Markdown 文件名主干
120
+
121
+ Args:
122
+ file_name: 显式主干;`None` 表示按本地时间自动命名
123
+ output_dir: 输出根目录(自动命名时用于碰撞检测)
124
+
125
+ Returns:
126
+ str: 目录名主干(同时也是 `<stem>.md` 的文件名主干)
127
+
128
+ Raises:
129
+ ValueError: 显式主干为空,或自动命名的后缀已用尽
130
+ """
131
+ if file_name is None:
132
+ base = datetime.now(_TZ_SHANGHAI).strftime(_TS_FORMAT)
133
+ root = Path(output_dir)
134
+ if not (root / base).exists():
135
+ return base
136
+ for suffix in range(2, _MAX_COLLISION_SUFFIX + 1):
137
+ candidate = f"{base}-{suffix}"
138
+ if not (root / candidate).exists():
139
+ return candidate
140
+ raise ValueError(
141
+ f"自动命名目录已用尽({base} ~ {base}-{_MAX_COLLISION_SUFFIX}),"
142
+ "请显式传入 file_name"
143
+ )
144
+
145
+ stem = file_name.strip()
146
+ if stem.lower().endswith(".md"):
147
+ stem = stem[:-3].strip()
148
+ if not stem:
149
+ raise ValueError("file_name 不能为空")
150
+ return stem
151
+
152
+
153
+ def prepare_dirs(output_dir: str | Path, stem: str) -> tuple[Path, Path]:
154
+ """创建 `<output_dir>/<stem>/` 与 `images/`,返回两者路径"""
155
+ target_dir = Path(output_dir) / stem
156
+ target_dir.mkdir(parents=True, exist_ok=True)
157
+ images_dir = target_dir / "images"
158
+ images_dir.mkdir(exist_ok=True)
159
+ return target_dir, images_dir
160
+
161
+
162
+ def download_one(
163
+ url: str,
164
+ images_dir: Path,
165
+ seq: int,
166
+ timeout: float = DEFAULT_TIMEOUT,
167
+ ext_resolver: ImageExtResolver | None = None,
168
+ ) -> str:
169
+ """下载单张图片,成功返回相对路径(`images/NNN.ext`),失败返回空串
170
+
171
+ 扩展名优先级:`ext_resolver`(站点规则)→ URL 路径后缀 →
172
+ 响应 Content-Type(无扩展名的签名图片 URL,占位扩展名可能与真实格式不符)→ `png`。
173
+ """
174
+ request = urllib.request.Request(url, headers={"User-Agent": _DEFAULT_UA})
175
+ try:
176
+ with urllib.request.urlopen(request, timeout=timeout) as resp:
177
+ raw = resp.read()
178
+ content_type = (resp.headers.get("Content-Type") or "").split(";")[0]
179
+ except (urllib.error.URLError, socket.timeout, TimeoutError, OSError) as exc:
180
+ logger.warning(f"图片下载失败: {url}({exc})")
181
+ return ""
182
+ if not raw:
183
+ logger.warning(f"图片下载返回空内容: {url}")
184
+ return ""
185
+
186
+ ext = ext_resolver(url) if ext_resolver is not None else ""
187
+ ext = normalize_image_ext(ext) or _ext_from_url(url)
188
+ if not ext:
189
+ ext = _CT_EXTS.get(content_type.strip().lower(), "") or "png"
190
+
191
+ filename = f"{seq:03d}.{ext}"
192
+ (images_dir / filename).write_bytes(raw)
193
+ return f"images/{filename}"
194
+
195
+
196
+ def localize_images(
197
+ images: list[ArticleImage],
198
+ images_dir: Path,
199
+ timeout: float,
200
+ markdown: str,
201
+ ext_resolver: ImageExtResolver | None = None,
202
+ ) -> tuple[str, list[ArticleImage], int]:
203
+ """下载图片清单到 `images_dir`,并把 md 中的引用改为本地相对路径
204
+
205
+ 同一 URL 只下载一次;单张失败不中断,md 中保留原远程 URL。
206
+
207
+ Returns:
208
+ (替换后的 markdown, 更新后的 images 清单(含 local), 成功张数)
209
+ """
210
+ url_to_local: dict[str, str] = {}
211
+ updated: list[ArticleImage] = []
212
+ saved_count = 0
213
+ seq = 0
214
+ for image in images:
215
+ if not image.src:
216
+ updated.append(image)
217
+ continue
218
+
219
+ local = url_to_local.get(image.src, "")
220
+ if not local:
221
+ seq += 1
222
+ local = download_one(image.src, images_dir, seq, timeout, ext_resolver)
223
+ if local:
224
+ url_to_local[image.src] = local
225
+ saved_count += 1
226
+
227
+ updated.append(image._replace(local=local))
228
+ if local:
229
+ markdown = markdown.replace(image.src, local)
230
+ return markdown, updated, saved_count
231
+
232
+
233
+ def format_cn_date(publish_time: str) -> str:
234
+ """ISO 8601 / `YYYY-MM-DD` → 中文日期(`2026年8月4日`);不可解析时原样返回"""
235
+ if not publish_time:
236
+ return ""
237
+ try:
238
+ stamp = datetime.fromisoformat(publish_time)
239
+ except ValueError:
240
+ return publish_time
241
+ return f"{stamp.year}年{stamp.month}月{stamp.day}日"
242
+
243
+
244
+ def with_front_matter(markdown: str, info: ArticleInfo) -> str:
245
+ """在 Markdown 顶部插入 YAML 风格元信息头(三家字段一致)
246
+
247
+ `publish_time` 渲染为中文日期;`ArticleInfo.publish_time` 本身仍保持 ISO 8601,
248
+ 供程序化使用与 `meta.json` 序列化。
249
+ """
250
+ return "\n".join(
251
+ [
252
+ "---",
253
+ f"title: {info.title}",
254
+ f"author: {info.author}",
255
+ f"publish_time: {format_cn_date(info.publish_time)}",
256
+ f"source: {info.source}",
257
+ f"source_url: {info.url}",
258
+ "---",
259
+ "",
260
+ markdown,
261
+ ]
262
+ )
263
+
264
+
265
+ def save_article(
266
+ result: ArticleResult,
267
+ output_dir: str | Path,
268
+ stem: str,
269
+ write_meta: bool = True,
270
+ ext_resolver: ImageExtResolver | None = None,
271
+ label: str = "文章",
272
+ timeout: float = DEFAULT_TIMEOUT,
273
+ ) -> SavedOutput:
274
+ """把 `fetch()` 的结果按统一契约落盘
275
+
276
+ Args:
277
+ result: `fetch()` 的返回(`ok=True` 且 `info` 非空)
278
+ output_dir: 输出根目录
279
+ stem: 已解析的目录/文件名主干(由 `resolve_stem` 产出)
280
+ write_meta: 是否产出 `meta.json`(默认 True)
281
+ ext_resolver: 图片扩展名推断函数(站点规则,可选)
282
+ label: 日志前缀(如「微信文章」「网页文章」)
283
+ timeout: 图片下载超时(秒)
284
+
285
+ Returns:
286
+ SavedOutput:成功时含实际落盘路径与图片张数;`info` 缺失时返回失败
287
+ """
288
+ info = result.info
289
+ if info is None:
290
+ return SavedOutput(
291
+ False, "结果缺少文章元信息(info 为空)", reason=REASON_NO_CONTENT
292
+ )
293
+
294
+ target_dir, images_dir = prepare_dirs(output_dir, stem)
295
+
296
+ # 先本地化图片(meta.json 里的 images[].local 才是实际落盘路径)
297
+ body, info.images, images_saved = localize_images(
298
+ info.images, images_dir, timeout, result.markdown, ext_resolver
299
+ )
300
+
301
+ md_path = target_dir / f"{stem}.md"
302
+ md_path.write_text(with_front_matter(body, info), encoding="utf-8")
303
+
304
+ if write_meta:
305
+ (target_dir / "meta.json").write_text(
306
+ json.dumps(info.to_dict(), ensure_ascii=False, indent=2),
307
+ encoding="utf-8",
308
+ )
309
+
310
+ logger.info(f"{label}已存储: {md_path}")
311
+ return SavedOutput(
312
+ ok=True,
313
+ output_dir=str(target_dir),
314
+ md_path=str(md_path),
315
+ images_dir=str(images_dir),
316
+ title=info.title,
317
+ images_saved=images_saved,
318
+ warnings=result.warnings,
319
+ )
320
+
321
+
322
+ def _ext_from_url(url: str) -> str:
323
+ """从 URL 路径后缀推断图片扩展名(推断不出返回空串)"""
324
+ path = urllib.parse.urlparse(url).path
325
+ return normalize_image_ext(Path(path).suffix)
@@ -0,0 +1,172 @@
1
+ """
2
+ Copyright (c) 2021-2026 溢墨修心(Yimo). All Rights Reserved.
3
+
4
+ Licensed under the Apache License, Version 2.0 (the "License");
5
+ you may not use this file except in compliance with the License.
6
+ You may obtain a copy of the License at
7
+
8
+ http://www.apache.org/licenses/LICENSE-2.0
9
+
10
+ Unless required by applicable law or agreed to in writing, software
11
+ distributed under the License is distributed on an "AS IS" BASIS,
12
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
+ See the License for the specific language governing permissions and
14
+ limitations under the License.
15
+
16
+ Project: yimo
17
+ Author: 溢墨修心(Yimo)
18
+ """
19
+
20
+ # date: 2026-10-14
21
+ """文章抓取通用模型(多平台共用,零第三方依赖)
22
+
23
+ `yimo.kit.crawl.wx_article_kit.WxArticleKit`(微信公众号)与 `yimo.kit.crawl.web_article_kit.WebArticleKit`
24
+ (通用网页)共用同一套模型,便于**多平台抓取后写入同一张表**:
25
+
26
+ - `ArticleImage` / `ArticleLink` / `CodeBlock`:正文清单条目;
27
+ - `ArticleInfo`:平台中立的通用字段集(`publish_time` 保持 ISO 8601,
28
+ 仅落盘 YAML 头渲染为中文日期);
29
+ - `ArticleResult`:`fetch()` 的非落盘结果;
30
+ - `SavedOutput`:`save()` 的落盘结果。
31
+
32
+ 失败原因(`ArticleResult.reason` / `SavedOutput.reason`)取值:
33
+
34
+ | 取值 | 含义 |
35
+ |---|---|
36
+ | `""` | 成功 |
37
+ | `unsupported_source` | 该来源有专属工具类(如微信 → `WxArticleKit`) |
38
+ | `fetch_blocked` | 抓取被站点拒绝(403 等):正文通常依赖 JavaScript 渲染或需登录态 |
39
+ | `fetch_failed` | 网络/超时等抓取失败 |
40
+ | `no_content` | 抓到页面但无法识别正文(非文章页或正文由 JavaScript 动态渲染) |
41
+ | `risk_control` | 命中站点风控特征(访问过于频繁/环境异常) |
42
+ | `auth_failed` | 凭据无效或额度不足(API 401 / 402) |
43
+ | `rate_limited` | 触发服务端限流(API 429) |
44
+ | `config_missing` | 缺少调用所需的配置(如 API Key) |
45
+
46
+ `warnings` 为**非致命**自检提示(如「页面含图片但产物无图」「正文疑似过短」),
47
+ **不改变 `ok` 语义**:抓取成功一律 `ok=True`,提示仅供调用方判断质量。
48
+
49
+ 使用方式(按需 import,无需经 kit 包顶层导出):
50
+
51
+ from yimo.kit.crawl.article_models import ArticleInfo, ArticleResult
52
+ """
53
+
54
+ from dataclasses import dataclass, field
55
+ from typing import Any, NamedTuple
56
+
57
+ # 失败原因取值(字符串常量,便于业务侧分支判断;成功为空串)
58
+ REASON_UNSUPPORTED_SOURCE = "unsupported_source"
59
+ REASON_FETCH_BLOCKED = "fetch_blocked"
60
+ REASON_FETCH_FAILED = "fetch_failed"
61
+ REASON_NO_CONTENT = "no_content"
62
+ REASON_RISK_CONTROL = "risk_control"
63
+ # 以下三项为 DsKit 引入的平台中立取值(0.6.0):凭据/限流/配置缺失
64
+ REASON_AUTH_FAILED = "auth_failed"
65
+ REASON_RATE_LIMITED = "rate_limited"
66
+ REASON_CONFIG_MISSING = "config_missing"
67
+
68
+ # 全部合法取值(便于校验收敛)
69
+ REASONS: tuple[str, ...] = (
70
+ "",
71
+ REASON_UNSUPPORTED_SOURCE,
72
+ REASON_FETCH_BLOCKED,
73
+ REASON_FETCH_FAILED,
74
+ REASON_NO_CONTENT,
75
+ REASON_RISK_CONTROL,
76
+ REASON_AUTH_FAILED,
77
+ REASON_RATE_LIMITED,
78
+ REASON_CONFIG_MISSING,
79
+ )
80
+
81
+
82
+ class ArticleImage(NamedTuple):
83
+ """图片条目(转存后地址 + 原始地址 + alt + 本地相对路径)"""
84
+
85
+ src: str
86
+ original: str
87
+ alt: str = ""
88
+ local: str = "" # 转存后的本地相对路径(如 images/001.png),失败为空
89
+
90
+
91
+ class ArticleLink(NamedTuple):
92
+ """正文链接条目"""
93
+
94
+ text: str
95
+ href: str
96
+
97
+
98
+ class CodeBlock(NamedTuple):
99
+ """代码块条目"""
100
+
101
+ language: str
102
+ code: str
103
+
104
+
105
+ @dataclass
106
+ class ArticleInfo:
107
+ """文章元信息(平台中立的通用字段集,`to_dict()` 可 JSON 化后自行持久化)
108
+
109
+ 字段说明:
110
+
111
+ - `url`:原文链接;
112
+ - `title` / `author` / `summary`:标题 / 作者 / 摘要,取不到时为空串;
113
+ - `publish_time`:ISO 8601(精度不足时退化为 `YYYY-MM-DD`),
114
+ 落盘 YAML 头渲染中文日期;
115
+ - `source`:来源平台名(如「今日头条」「CSDN博客」「微信公众平台」);
116
+ - `site_host`:站点域名(DB 归类/去重辅助);
117
+ - `images` / `links` / `code_blocks`:正文清单(图片 `local` 在落盘阶段填充)。
118
+ """
119
+
120
+ url: str
121
+ title: str
122
+ author: str = ""
123
+ publish_time: str = ""
124
+ source: str = ""
125
+ site_host: str = ""
126
+ summary: str = ""
127
+ images: list[ArticleImage] = field(default_factory=list)
128
+ links: list[ArticleLink] = field(default_factory=list)
129
+ code_blocks: list[CodeBlock] = field(default_factory=list)
130
+
131
+ def to_dict(self) -> dict[str, Any]:
132
+ """序列化为可 JSON 化的 dict"""
133
+ return {
134
+ "url": self.url,
135
+ "title": self.title,
136
+ "author": self.author,
137
+ "publish_time": self.publish_time,
138
+ "source": self.source,
139
+ "site_host": self.site_host,
140
+ "summary": self.summary,
141
+ "images": [img._asdict() for img in self.images],
142
+ "links": [link._asdict() for link in self.links],
143
+ "code_blocks": [code._asdict() for code in self.code_blocks],
144
+ }
145
+
146
+
147
+ class ArticleResult(NamedTuple):
148
+ """fetch() 的非落盘结果
149
+
150
+ `reason` 见模块 docstring;`warnings` 为非致命自检提示(不可变元组)。
151
+ """
152
+
153
+ ok: bool
154
+ error: str = ""
155
+ info: ArticleInfo | None = None
156
+ markdown: str = ""
157
+ reason: str = ""
158
+ warnings: tuple[str, ...] = ()
159
+
160
+
161
+ class SavedOutput(NamedTuple):
162
+ """save() 的落盘结果"""
163
+
164
+ ok: bool
165
+ error: str = ""
166
+ output_dir: str = "" # 实际写入的文章子目录(<output_dir>/<file_name>)
167
+ md_path: str = ""
168
+ images_dir: str = ""
169
+ title: str = ""
170
+ images_saved: int = 0 # 成功转存的图片张数
171
+ reason: str = ""
172
+ warnings: tuple[str, ...] = ()