[teamai] Push 87 resource(s) from XingfenD

2026-09-10 16:10:45 +08:00
parent 425c9c078a
commit 65c04def51
1314 changed files with 211681 additions and 0 deletions
@@ -0,0 +1,118 @@
+# Source → Markdown
+
+无论输入是什么，Phase 1 都先转成统一的 `source/source.md`，并把风险写进
+`source/extraction-notes.md`。
+
+## 产物
+
+`source.md` 要包含：标题 · 来源 · 作者 / 时间 / 链接（若可得）· 正文 · 表格 ·
+图片占位 · 代码块 · 引用 · 附录 / 脚注。
+
+`extraction-notes.md` 要记录：输入类型 · 提取方式 · 可能丢失的信息 · PDF/DOCX 中
+无法可靠还原的版式 · 图片 / 表格 / 脚注 / 代码是否完整 · 需要用户补充的素材或上下文 ·
+**源语言、是否需要翻译、目标语言、翻译版文件名与翻译说明**。
+
+## 语言与翻译
+
+抽取后判断 `source.md` 的语言，并按 Phase 0 记录的目标语言决定：
+
+- 未指定目标语言，或目标语言与源一致 → **不翻译**，最终文章语言 = 源语言。
+- 指定了目标语言且与源不一致 → 产出 `source/source.<lang>.md`（如 `source.zh.md` / `source.en.md`），
+  作为 Phase 2+ 的**事实底座**；原 `source.md` 保留备查。
+  - 翻译要求：**地道、去翻译腔** —— 按目标语言的表达习惯重组句子，不逐字直译，不留生硬外语语序 /
+    被动堆叠 / 异国标点；术语 / 数字 / 代码 / 公式 / 引用保持准确；标题层级、结构、信息保留比例不变。
+  - 翻译只在源文层做一次；后续编辑、改写语气、组件化都基于翻译版进行。
+
+## 不同输入的处理原则
+
+| 输入 | 处理方式 | 自检重点 |
+|---|---|---|
+| URL | 抓网页正文，清理导航 / 广告 / 推荐 | 是否抓到主体，链接和图片是否保留 |
+| PDF | 提取文本 / 章节 / 表格 / 图片占位 | 断行错乱、页眉页脚混入、表格丢失 |
+| DOCX | 提取标题层级 / 段落 / 表格 / 图片占位 | 样式不重要，结构和内容完整性重要 |
+| Markdown | 保持原有标题 / 代码块 / 表格 | 不要过度改写源文 |
+| 纯文本 | 识别结构并标注不确定处 | 不要擅自编造层级 |
+| 截图 / 图片 | 转成图片占位 + 说明，记录用途 | 记录到 extraction-notes，等用户确认 |
+
+## 抽取脚本选择
+
+Skill 提供两条抽取路径：MarkItDown 主路径 + 轻量 fallback。Agent 应在 Phase 1 先判断
+输入类型、信息保留要求和本机环境，再选择脚本。
+
+### 1. MarkItDown 主路径
+
+对 PDF / DOCX / PPTX / HTML / 复杂文档，尤其是用户要求 80-100% 信息保留时，优先使用
+`scripts/source-to-markdown-markitdown.py`：
+
+```bash
+python3.10 <path-to-beautiful-article>/scripts/source-to-markdown-markitdown.py <input> -o source/source.md
+```
+
+MarkItDown 需要 Python 3.10+。它是可选增强依赖，不随组件库或脚手架强制安装。
+若未安装，按需提示用户安装：
+
+```bash
+python3.10 -m pip install "markitdown[pdf,docx]"
+```
+
+如果本机没有 `python3.10` 命令但有 `uv`，可临时拉起带 MarkItDown 的环境：
+
+```bash
+uv run --python 3.12 --with "markitdown[pdf,docx]" python \
+  <path-to-beautiful-article>/scripts/source-to-markdown-markitdown.py <input> -o source/source.md
+```
+
+不要默认安装 `markitdown[all]`，除非用户明确需要 PPTX / XLSX / 音频 / YouTube / Azure 等
+额外格式。全量安装更重，也更容易引入环境问题。
+
+### 2. 轻量 fallback
+
+如果 MarkItDown 不可用、Python 版本不足、转换失败，或输入只是 Markdown / TXT / 简单 HTML，
+使用 `scripts/source-to-markdown.py`：
+
+```bash
+python3 <path-to-beautiful-article>/scripts/source-to-markdown.py <input> -o source/source.md
+```
+
+脚本会探测可用的解析库（pdfminer / pdfplumber / python-docx / BeautifulSoup），缺库时
+打印安装建议并优雅降级。脚本只做**机械抽取**；正文清理、占位标注、风险记录仍由 agent 完成。
+URL 也可直接用 agent 的网页抓取能力获取正文，再清理。
+
+### 3. Agent 决策规则
+
+- PDF / DOCX / PPTX / 复杂 HTML：先尝试 MarkItDown。
+- Markdown / TXT：直接用 fallback，保持原文结构，不要过度处理。
+- URL：可先用 Agent 的网页抓取能力获取正文；若已保存为 HTML 文件，再按复杂度选择
+  MarkItDown 或 fallback。
+- 100% 信息保留：抽取后必须更严格自检，必要时同时跑 MarkItDown 与 fallback，对比是否
+  有表格、代码、脚注、图片占位遗漏。
+- 任一脚本产物都只是 `source.md` 草稿；Agent 必须继续清理噪音、补图片占位，并写
+  `source/extraction-notes.md`。
+
+## Source Phase 自检（主 Agent 内联 · 5 条 checklist）
+
+源材料质检**不是硬性 SubAgent 质检点**。主 Agent 进 Phase 2 前反正要通读 `source.md`，
+就地按这 5 条核查、按结论修复即可（无需单独的 review 文件）：
+
+1. **完整性**：是否被截断？体量是否和原文相称（长 PDF / 长文没有只抽到一半 / 只抓到首屏）？
+2. **结构**：标题层级是否保留？还是被压平成一片正文（后面没法分章）？
+3. **关键载体**：表格 / 代码 / 公式 / 引用 / 脚注是否保留且没损坏（表格没挤成一行、代码缩进还在、
+   公式没变乱字符）？
+4. **噪声**：是否误把导航 / 广告 / Cookie 横幅 / 推荐阅读 / 页眉页脚页码写进正文？编码有没有伤
+   （乱码、连字 `ﬁ`、软连字符断词、两栏 PDF 阅读顺序错乱）？
+5. **不确定项**：图片是否以占位标注？拿不准的都写进 `extraction-notes.md` 了吗？
+
+> ⚠️ 上面 1/4 能孤读 markdown 抓到，但 **2/3 里"静默丢失"的表/段**（被悄悄删掉、吞掉）
+> 光看 markdown 看不出来——必须对照 `original.*`。
+
+## 升级为独立 Source Reviewer（仅限复杂/低置信源）
+
+**只有**当 `extraction-notes.md` 标记了"低置信 / 复杂 PDF/DOCX / 转换吃不准 / 要求 100% 保留的关键源"
+时，才升级为独立 SubAgent，并**强制对照原件做 diff 式核查**，写 `review/source-review.md`：
+
+```text
+请作为 Source Reviewer。同时读取 source/original.*（原件）和 source/source.md（转换产物）。
+逐项做 diff 式核查：对照原件，source.md 是否漏掉了表格 / 段落 / 脚注 / 代码 / 图，
+是否混入噪音，是否有结构塌陷或编码损坏。
+只输出"按出现顺序的差异清单 + 必须修复项"，不评价文章好不好看，不要替我改文件。
+```