Beautiful Article

背景原则

AI 生成内容越复杂，输出媒介越重要。HTML 的价值在于同时提升信息密度、视觉清晰度、分享便利性和交互能力：表格、SVG、CSS、代码片段、可调控件、复制与导出按钮，可以让读者不只是“看完”，而是能比较、定位、调整、复查和继续使用。Beautiful Article 的目的，是把原本枯燥、线性、难以消化的文字材料，转换成视觉体验更漂亮、阅读节奏更清晰、也更容易审阅和分享的单文件网页文章。

边界（先判断要不要进这个 Skill）

• 最终主产物是 single HTML 文章，不是网页应用。
• 文章可以有 Raw 自由层（任意 HTML / CSS / JS / React：交互、布局排版、动效、小工具、 按需的 SVG / canvas 图解），但必须服务阅读、解释、论证、节奏或审美。
• 不生成：后台、表单、拖拽工作台、完整 dashboard、产品原型、通用 Web App。
• 信息密度由用户确认；默认保留 100% 信息，生成长文式网页文章。

如果用户要的是应用而不是文章，停下来澄清，不要进入本 Skill。

---

工作流总览

Phase 0  Intake            判断是否进入本 Skill + 初步文章类型
   ▼
Phase 1  Source → Markdown URL/PDF/DOCX/MD/文本 → source.md + extraction-notes.md
         └ 主 Agent 内联 5 条 checklist 自查（仅复杂/低置信源升级 SubAgent）
   ▼
Phase 2  Editorial Planning 一份 plan.md（Brief / Outline / Theme / Assets 四段）
         └ 主 Agent 内联自查（无 SubAgent、无 review 文件）
   ▼
Phase 3  Plan Checkpoint   ★Checkpoint 1 必须停。逐项确认 5 件事：文章类型（含标配保留比例）/ 主题 / 版式 / 配图模式 / 封面
   ▼
Phase 4  First Spread      首屏 + 第一节 + 一个代表性视觉块（脚手架在此创建）
         └ First Spread Reviewer SubAgent（写 review/first-spread-review.md）
         └ ★Checkpoint 2 必须停。逐项确认 2 件事：验收结论 / 开发模式 A/B
   ▼
Phase 5  Full Article Build 生成完整网页文章（默认单 Agent，超长可按 Section 隔离）
         └ Section Reviewer SubAgent（以消息返回 pass/fail，无须写 review 文件）
   ▼
Phase 6  Final Review      Editorial / Visual / Technical 三视角终审（写 review/final-review.md）
   ▼
Phase 7  Repair            最小切片修复，有修复才写 repair-log.md
   ▼
Phase 8  Delivery          ★Checkpoint 3 必须停。逐项确认交付决策 → 交付 article.html + 简短编辑说明

工作区结构（脚手架创建；这些文件是 Skill 的长期记忆，不要只依赖聊天上下文记决策）：

<workspace>/
  source/   original.*  source.md  source.<lang>.md(需翻译时)  extraction-notes.md
  plan/     plan.md                                    # 单一规划文件：Brief / Outline / Theme / Assets 四段
  article/  Cover.tsx(默认)  Article.tsx  sections/  raw-blocks/  assets/  article.html(产物)
  review/   first-spread-review.md  final-review.md   # 仅这两份是常规产物
            source-review.md(仅复杂源)  repair-log.md(仅有修复时)
  index.html  package.json  vite.config.ts  tsconfig*.json   (构建工装)

---

硬性质检协议（贯穿整个 Skill）

质检方式按节点区分 —— 不是所有质检都要开 SubAgent，也不是所有质检都要写文件。 误开 SubAgent / 误写文件是首要性能问题，按下表严格执行：

节点	质检方式	产物	为什么
Phase 1 Source（默认）	主 Agent 内联 5 条 checklist	无文件	主 Agent 反正要通读 source.md
Phase 1 Source（仅复杂/低置信源）	Source Reviewer SubAgent（对照 original.* diff）	review/source-review.md	静默丢失只能 diff 抓到
Phase 2 Plan / Checkpoint 1 前	主 Agent 内联自查（禁止开 SubAgent）	无文件	plan 是文字决策且 200-400 行，上下文是热的，SubAgent 冷启反而更慢
Phase 4 First Spread / Checkpoint 2 前	First Spread Reviewer SubAgent	review/first-spread-review.md	首屏定调，多一道独立眼睛更稳
Phase 5 每个 Section	Section Reviewer SubAgent	以消息返回 pass/fail + 修复点（不写文件）	一篇可能 5-15 节，N 份 review 文件无人再读
Phase 6 终审 / Checkpoint 3 前	Editorial + Visual + Technical Reviewer SubAgent	review/final-review.md	交付物的一部分，留档有价值

铁律：

1. Plan Checkpoint（Phase 2 → Checkpoint 1）严禁开 SubAgent 做质检。主 Agent 写完 plan.md 后就地对照 5 条清单（见 references/review-checklist.md 的 Plan 自查段）核查、按结论 改完 plan/plan.md，不要写任何 review 文件，然后进入 Checkpoint 1。
2. First Spread / Final 必须用 SubAgent（这两个节点 SubAgent 价值 > 开销）；只有探测不到 SubAgent 环境才由主 Agent 兜底，并在文件首注明"无 SubAgent 环境，主 Agent 兜底"。
3. Section Reviewer 用 SubAgent，但返回值是消息（pass / fail + 修复点）；fail 项主 Agent 收到后直接修，不要让 SubAgent 写 review/section-NN-review.md 文件。
4. 拿到任何质检结论 —— 先按 fail 项把产出改完，再汇报"做完了 + 自检结论 + 改了什么"。 直接拿原始结论汇报但不修复 = 违规。
5. 决策收集铁律 · 禁止静默替用户选择：在每个 Checkpoint（1 / 2 / 3），所有需要用户确认的 决策项必须每项独立列出 + 等用户答复。Agent 可以推荐（"我推荐 X，因为 …"），但 不能"已经替你定了 X，如果不对再说" —— 这等于剥夺选择机会。
   • 优先：如果环境有 AskQuestion 工具，每个决策项作为一个独立 question（一次调用可 传多个 question），用户能用选择卡逐项确认。
   • 否则：停下来在消息里把所有问题编号列出（每个问题独占一段、写清推荐项 + 理由 + 备选项），明确说"我等你逐项答复后再继续"，不要继续做任何后续工作。
   • 绝不：把多项决策打包成一个"全选我推荐的 / 全部 OK 吗？"yes/no 问题；也不要在 "推荐一句话"后默认直接进下一步。

各节点的 checklist 与 SubAgent prompt 模板见 references/review-checklist.md。

---

各阶段文件读取指南（渐进加载，别一次全读）

阶段	必读	按需查
Phase 0 Intake	references/harness.md	——
Phase 1 Source→MD	references/source-to-markdown.md	scripts/source-to-markdown-markitdown.py · scripts/source-to-markdown.py
Phase 2 Planning	references/article-types.md · references/information-density.md · references/plan-template.md · references/theme-selection.md · references/layout.md · references/asset-policy.md · references/cover.md（封面构图想法）	references/article-types/<type>.md · theme-profiles/*.md
Phase 4 First Spread / Phase 5 Build（每节回看）	references/section-build.md · references/component-policy.md · references/raw-policy.md · 选定主题 theme-profiles/<id>.md · 封面：references/cover.md	references/scaffold.md（建项目时一次）· references/html-output.md
Phase 6/7 Review & Repair	references/review-checklist.md · references/repair-policy.md	——
Phase 8 Delivery	references/html-output.md	references/pdf-output.md（仅当用户选 PDF 导出）

长会话里 agent 容易遗忘原则 —— Phase 5 会重复实现 N 个 Section，每次开工 前回看 component-policy.md + raw-policy.md + 当前主题 theme-profiles/<id>.md。

---

Phase 0 —— Intake

判断是否进入本 Skill，给出初步文章类型与输出模式（默认 single HTML）。

用户给的东西	该做的
一个或多个素材（URL/PDF/DOCX/MD/文本/截图）	进入 Phase 1
只说"帮我做篇 X 文章"但没素材	反问：先要素材或大纲。Skill 不替用户凭空构思内容
明显要的是应用 / 工具 / dashboard	停下来澄清，不进入本 Skill

捕获目标语言：开场就记录用户期望的最终文章语言（如用户提到"用中文/做成英文版"等）。

• 用户指定了语言 → 记进 plan/plan.md Brief 段的"目标语言"。若与源材料语言不一致，Phase 1 需先产出一份地道翻译版源文，后续基于翻译版编写（见 Phase 1）。
• 用户未指定 → 默认最终文章语言跟随源材料语言，不做翻译。

自检：用户要的是文章还是网页应用？是否需要完整信息？是否要先索取更多素材？ 用户有没有指定最终语言？与源语言是否一致？

---

Phase 1 —— Source → Markdown

把任意输入统一成 source/source.md，把不确定项写进 source/extraction-notes.md。 规则与各类输入处理见 references/source-to-markdown.md；可借助 MarkItDown 主路径或轻量 fallback 脚本做 PDF/DOCX/HTML 抽取。

落盘后由主 Agent 内联自查（references/source-to-markdown.md 的 5 条 checklist），按结论修复 再进入 Phase 2；仅当 extraction-notes.md 标记低置信 / 复杂源时，才升级为独立 Source Reviewer SubAgent 并对照 original.* 做 diff 式核查（写 review/source-review.md）。

语言处理（紧接抽取之后）：判断 source.md 的语言。

• 用户未指定目标语言，或目标语言与源一致 → 不翻译，后续直接基于 source.md 编写， 最终文章语言 = 源语言。
• 用户指定了目标语言且与源不一致 → 先产出地道翻译版 source/source.<lang>.md （如 source.zh.md / source.en.md），作为后续 Phase 2+ 的事实底座；原文 source.md 保留 备查。翻译要求：用地道的目标语言、去除翻译腔（按目标语言的表达习惯重组句子，不逐字直译， 不留生硬的外语语序 / 被动堆叠 / 异国标点），术语 / 数字 / 代码 / 公式 / 引用保持准确，结构与 信息保留比例不变。翻译说明写进 extraction-notes.md。

---

Phase 2 —— Editorial Planning

形成编辑方案，不直接写 HTML。只产出一份 plan/plan.md（四段：Brief / Outline / Theme / Assets），模板见 references/plan-template.md：

• Brief：目标读者 / 文章类型 / 信息保留比例 / 必须保留 / 可删减 / 语气 / 主要观点 / 阅读目标 / 目标语言 / 版式宽度 / TOC / 配图策略。
• Outline：Hero / Lead / Summary / Section 列表 / 每节保留哪些信息 / 每节是否需要 Raw·Table·CodeBlock·Formula·Image / 结尾方式。
• Theme：选定主题 + 理由 + 冲突说明（见 references/theme-selection.md）。
• Assets：配图策略与逐图计划（见 references/asset-policy.md；none 模式下本段 写一句话即可）。

文章类型路由见 references/article-types.md；信息密度与组件比例见 references/information-density.md。

自检方式 · 强约束：写完 plan/plan.md 后由主 Agent 内联对照 5 条 Plan 自查清单核查 （见 references/review-checklist.md 的 Plan 自查段），按结论改完 plan/plan.md，直接进入 Checkpoint 1，禁止开 SubAgent，禁止写 review/plan-review.md。

---

Phase 3 —— Plan Checkpoint（★硬节点 · Checkpoint 1，必须停）

铁律：禁止静默替用户选择。每个决策项必须独立列出、独立等用户答复。

可以推荐（"我推荐 X，因为 …"），不能说"已经替你定了 X，如果不对告诉我"——后者等于把 默认值偷渡过去、剥夺选择机会。

收集方式（按环境二选一）：

• 优先 AskQuestion 工具：每项作为一个独立 question 传入（一次调用可传多个 question）， 用户用选择卡逐项确认。
• 无 AskQuestion 工具：停下来在消息里把每个问题**编号列出 + 独占一段 + 写清推荐项 + 理由
  • 备选项**，明确说"我等你逐项答复后再继续"，不要继续做任何后续工作。

无论哪种方式：每个独立决策对应一个独立问题，不要打包成"全部 OK 吗？" yes/no。

必须独立确认的 5 项（缺一不可）：

#	决策项	选项（语义化标签 · 含标配信息保留比例）	备注
1	文章类型（信息保留比例打包在内）	完整长文 / 归档 longform · ~100% ／ 研究报告 / 正式分析 full-report · ~80% ／ 教学步骤 / 上手指南 `tutoria