XingfenD/teamai-test

Fork 0

Files

T

XingfenD 65c04def51 [teamai] Push 87 resource(s) from XingfenD

2026-09-10 16:10:45 +08:00

23 KiB

Raw Blame History

Beautiful Article Skill —— 把任意素材编辑成一篇精美的文章

一个面向 AI Agent 的 Skill：把任意素材（URL / PDF / DOCX / Markdown / 纯文本 / 截图 / 粘贴材料）编辑、设计成一篇比原文更易读、更便于分享和归档的精美文章。

English · 返回集合首页

由 ReActicle 驱动

beautiful-article 是编辑型 harness（方法论、checkpoint、主题选型、sub-agent reviewer）；reacticle 是 Skill 在运行时调用的底层组件协议 —— prose-first 的 React 语义组件 + 基于主题 token 的 Raw 自由层，统一接到同一套主题系统上。

beautiful-article  （本 Skill · 方法论 + harness）
        │  调用
        ▼
reacticle          （npm 包 · 组件 / 主题 / Raw / 导出）

层级	负责什么	仓库 / 文档
`beautiful-article`（本 Skill）	怎么让 Agent 从任意素材出发，规划、撰写、审阅、交付一篇文章 —— 6 阶段流程、3 个硬 checkpoint、主题选型、sub-agent reviewer	当前目录
`reacticle`	Skill 实际拼装出的组件词表 + 11 套 authoring 主题 —— `Article` / `Hero` / `Lead` / `Section` / `Quote` / `Image` / `Formula` / `CodeBlock` / `Raw` …，每套主题 = 一份 `.css` token 包 + 一份 `.md` authoring profile	`ConardLi/reacticle` · npm `reacticle` · 文档站

二者搭配最佳但相互独立：Skill 因为有 ReActicle 这个稳定目标层才能跑通；ReActicle 单独作为 React 组件库使用也完全立得住。

文章实例 —— 用 `beautiful-article` + ReActicle 写出来的真实文章

每一篇都是 AI Agent 用本 Skill 调用 reacticle 组件协议端到端写完的真实长文。点封面即可在线打开单文件 HTML 版本。

Agent Tools 设计的最佳实践 _{Theme · Freddie · 长文 · 21 min} ^{Anthropic 工程团队关于 Tools 的五条原则，与一套评测驱动的方法。}	Agent Skill 是如何进化的？ _{Theme · Freddie · 解释文 · 8 min} ^{把 Skill 文档当成被训练的对象，而不是被复制粘贴的 prompt。}
Agent Harness 的解剖图 _{Theme · Vignelli · 长文 · 12 min} ^{智能在模型里；让智能变得有用的，是它周围的那套系统。}	提示词缓存对 Agent 有多重要？ _{Theme · Bayer · 长文 · 15 min} ^{缓存命中率是 Agent 的 SLO，Claude Code 团队的反直觉经验。}
面向 Agent 的高效上下文工程 _{Theme · Tufte · 长文 · 16 min} ^{本文探讨如何高效地筛选与管理驱动 AI Agent 运转的上下文。}	Attention Is All You Need _{Theme · Tufte · 长文 · 30 min} ^{一篇重塑现代 AI 的论文，逐层拆给你看。}
把 AI Agent 的评测讲清楚 _{Theme · Tufte · 长文 · 25 min} ^{让 Agent 有用的那些能力，恰恰让它难以评测 —— 来自 Anthropic 的指南。}	Codex 的 Agent Loop 是怎么做的？ _{Theme · Sottsass · 长文 · 18 min} ^{OpenAI 官方分享：在 Responses API 之上，一条对话是如何被反复"展开"的。}

主题概览 —— 每套主题一篇样品文章

11 套主题已上架。每套主题的完整契约（.css token 包 + .md authoring profile、anti-patterns、code/media style）见 Theming。

每套主题都附一篇样品长文，从字体到摄影、代码、公式、Raw 块通通走一遍。点封面在线阅读，点主题名跳到该主题在文档站的章节。

Tufte · Data-Ink _{咖啡因与睡眠 · 数据笔记} ^{Edward Tufte 数据墨水，证据优先，发丝级图表与最朴素的版式。}	Press · 书卷 _{活字之后 · 随笔} ^{Stripe Press 式书卷长读物：会落定的标题、氧化血红首字母、纯正文之美。}	Shannon · 工程暗色 _{连接池耗尽 · 故障复盘} ^{贝尔实验室技术论文血统，暗底黄金信号、回压依赖、夜间作战气质。}
Vignelli · 瑞士网格 _{Orbit 设计系统规格 · 规格} ^{Massimo Vignelli 网格至上、grotesque 字族、瑞士红只承载结构。}	Knuth · 学术 _{线性化自注意力 · 预印本} ^{Donald Knuth / Computer Modern，编号小节、命题与证明、arXiv 草稿气质。}	Freddie · 暖黄 _{第一封 Newsletter · 上手指南} ^{Mailchimp Freddie 黑字荧光，亲和插画 + 不端着的产品上手语气。}
Andy · 静谧 _{把呼吸放慢 · 练习} ^{柔软圆润、呼吸-神经跷跷板，让人慢下来的练习气质。}	Bodoni · 报刊 _{头版的消亡 · 特稿} ^{高对比 Didone 报刊气质，黑白大报、对折线之上的分量。}	Bayer · 包豪斯 _{形、色、网格 · 教学} ^{Herbert Bayer 包豪斯三原色几何，形有性格、色有重量。}
Fuller · 蓝图 _{限流器设计规格 · 系统设计} ^{Buckminster Fuller 工程蓝图，方格纸拓扑、令牌桶模拟，可照着实现。}	Sottsass · 孟菲斯 _{撞色不翻车 · 设计随笔} ^{Memphis 80s 撞色，黑描边、硬投影、轻微旋转的不正经语法。}

完整的 11 套主题样品（含主题切换、搜索与筛选）在线 gallery：https://rearticle.mmh1.top/#/gallery。

这个 Skill 干什么

beautiful-article 把原本枯燥、线性、难以消化的文字材料变成视觉体验更漂亮、阅读节奏更清晰、也更便于审阅和分享的文章。它不是网页应用生成器 —— 注意力永远在"文章"本身：更好的阅读、更好的节奏、更好的美学。最终交付物是一份自包含、可离线打开的文件（可选随附 PDF），但那是交付细节、不是目标。

适合的场景：

把一篇长 URL / PDF / DOCX / Markdown 编辑成一篇网页长文
决策摘要 briefing、概念解释 explainer、教学步骤 tutorial、复盘 review、方案分析
视觉随笔 visual essay、对话 / 访谈 / 播客转写、交互式学习解释器
任何时候你希望比 Markdown 更好的阅读载体 —— 表格、SVG、代码、公式、复制 / 导出按钮一条龙

Skill 本质上是一个方法论 + 协作 harness。它附带一个 Vite + React + TypeScript 脚手架，基于 reacticle 组件协议 —— Agent 不手写裸 HTML / CSS，而是用 prose-first 的语义组件 + 主题约束的 Raw 自由层来组合。

核心思想

首先是一篇文章，不是应用 —— 注意力永远在文章。Raw 自由层、SVG、小工具必须服务阅读 / 解释 / 节奏 / 审美，不能喧宾夺主。
Source → Plan → Build → Review 小型 harness —— 每个项目走 6 个有编号的 phase，中间有 3 个硬 checkpoint。
reacticle 组件协议 —— 语义化的 prose 组件（Hero / Lead / Section / Quote / Callout / Image / Formula / CodeBlock / Table …）+ 一个必须用主题 token（--ra-*）的 Raw 自由层。
主题驱动设计 —— 内置 11 套 authoring profile（tufte / press / bayer / bodoni / vignelli / sottsass / freddie / andy / fuller / knuth / shannon），每套是给 Agent 看的 Markdown 契约，不是 CSS 文件。
默认 100% 信息保留 —— 文章类型自带推荐保留比例（longform ~100% / briefing ~50% / visual-essay ~40% …），用户可一句话覆盖。
硬协作 checkpoint —— Plan、首屏样张、最终交付前 Agent 必须停下来；每个决策必须逐项独立确认，不允许打包一个"全部 OK 吗"。
默认带封面 —— 一个 3:4 书封式题图位于 TOC 之上，外壳锁死、只能用主题 token、不允许远程图片。
PDF 导出可选 —— 主交付物是一份自包含的 HTML 文件；PDF 只在用户在 Checkpoint 3 主动选择时通过零依赖的 html-to-pdf.sh 生成。

工作流

Phase 0  Intake
   │
Phase 1  Source → Markdown      （URL / PDF / DOCX / MD / 文本 → source.md）
   │
Phase 2  Editorial Planning     （一份 plan.md：Brief / Outline / Theme / Assets）
   │
★ Checkpoint 1  Plan            （5 个独立决策逐项确认）
   │
Phase 4  First Spread           （封面 + Hero + 第一节 + 一个代表性视觉块）
   │
★ Checkpoint 2  First Spread    （验收 + 后续开发模式 A/B）
   │
Phase 5  Full Article Build     （单 Agent 顺序 / 多 Agent 并行）
   │
Phase 6  Final Review           （Editorial / Visual / Technical 三视角）
   │
Phase 7  Repair                 （只允许最小切片修复）
   │
★ Checkpoint 3  Delivery        （HTML，或 HTML + PDF，或暂停修订）
   │
Phase 8  Delivery               （article.html，可选 article.pdf）

每个项目都有自己的工作区目录，作为 Agent 的长期记忆：

<workspace>/
  source/   original.*   source.md   source.<lang>.md（需翻译时）   extraction-notes.md
  plan/     plan.md
  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 目录结构

skills/beautiful-article/
├── SKILL.md                            主 Skill 文件（frontmatter name: beautiful-article）
├── manifest.json                       发布清单
├── README.md  /  README.zh-CN.md       本文档
├── references/
│   ├── article-types.md                文章类型路由
│   ├── article-types/                  briefing / dialogue / essay / explainer / full-report
│   │                                    interactive-explainer / longform / review / tutorial / visual-essay
│   ├── information-density.md          保留比例与组件 / 视觉比例的关系
│   ├── plan-template.md                单一 plan.md 模板（Brief / Outline / Theme / Assets）
│   ├── theme-selection.md              主题选择，density 与 theme 解耦
│   ├── layout.md                       版式宽度、TOC 默认值
│   ├── cover.md                        3:4 书封封面指南（5 条自检 + 5 个构图模板）
│   ├── asset-policy.md                 配图策略（none / user-assets / placeholders / ai-generated）
│   ├── component-policy.md             Reacticle 组件契约、prose-first
│   ├── raw-policy.md                   Raw 允许 / 禁止表、token 驱动、自检
│   ├── section-build.md                一节一文件铁律、subagent prompt 模板
│   ├── source-to-markdown.md           各类输入抽取规则 + 5 条自检
│   ├── scaffold.md                     脚手架行为、工作区结构
│   ├── html-output.md                  dev / build / 单文件 HTML 命令
│   ├── pdf-output.md                   html-to-pdf.sh 用法 + print CSS 覆盖
│   ├── review-checklist.md             各阶段 reviewer 清单与 sub-agent prompt
│   ├── repair-policy.md                最小切片修复对照表
│   └── harness.md                      Skill-as-harness 视角
├── theme-profiles/
│   ├── index.json                      主题注册表
│   └── andy / bayer / bodoni / freddie / fuller / knuth / press / shannon / sottsass / tufte / vignelli
├── scripts/
│   ├── scaffold.sh                     一键创建工作区
│   ├── html-to-pdf.sh                  可选 HTML → PDF（headless 浏览器，零 npm 依赖）
│   ├── pdf-print-overrides.css         注入 HTML 的 @media print 覆盖
│   ├── source-to-markdown-markitdown.py  主路径抽取（PDF / DOCX / HTML）
│   └── source-to-markdown.py           轻量 fallback（Markdown / TXT / 简单 HTML）
└── assets/
    └── scaffold-template/              脚手架脚本拷贝的 Vite + React + TS 模板

它是怎么工作的（要点）

1. 各节点的质检协议

不同 phase 用不同的质检方式 —— 滥开 SubAgent、滥写 review 文件是首要性能问题，所以 Skill 把规则写明：

节点	怎么检	产物
Phase 1 Source（默认）	主 Agent 内联 5 条 checklist	无文件
Phase 1 Source（仅复杂 / 低置信源）	Source Reviewer SubAgent（对照 `original.*` diff）	`review/source-review.md`
Phase 2 Plan / Checkpoint 1 前	主 Agent 内联自查（禁开 SubAgent、禁写文件）	无文件
Phase 4 First Spread / Checkpoint 2 前	First Spread Reviewer SubAgent	`review/first-spread-review.md`
Phase 5 每个 Section	Section Reviewer SubAgent —— 以消息返回 pass/fail	无（不写每节文件）
Phase 6 终审 / Checkpoint 3 前	Editorial + Visual + Technical Reviewer SubAgent	`review/final-review.md`

2. 禁止静默替用户选择

每个 Checkpoint 的每一项决策必须独立问 —— Agent 可以推荐，但不能"我已经替你定了 X，不对再说"。Plan Checkpoint 5 项独立决策：文章类型（含推荐保留比例）/ 主题 / 版式宽度 / 配图模式 / 封面开关。

3. 文章类型 → 保留比例打包

10 种文章类型都自带推荐保留比例：longform · ~100% / tutorial · ~90% / full-report · ~80% / explainer · ~80% / dialogue · ~80% / review · ~70% / essay · ~70% / briefing · ~50% / visual-essay · ~40% / interactive-explainer · ~25% 摘录 + 75% AI 重构。用户可一句话覆盖。

4. 一节一文件铁律

每个 Section 都是 article/sections/NN-*.tsx 单文件组件。Article.tsx 只是 assembler —— 由主 Agent 拥有，负责 import 与排序、跑 typecheck / build、解决主题漂移。这是后续多 Agent 并行的前提。

5. 全程主题 token

Raw 块必须只用 --ra-* 主题 token —— 不允许野生颜色 / 字体。换主题时所有 Raw 块一处生效。每个主题都有一份 Markdown authoring profile，告诉 Agent 在该主题下怎么写、怎么排版。

创建一个项目

Skill 不预先创建工作区 —— 每个项目自己开。来自 Phase 4 的命令：

# 默认开封面
bash <path-to-skill>/scripts/scaffold.sh ./my-article --theme=tufte

# 关闭封面
bash <path-to-skill>/scripts/scaffold.sh ./my-article --theme=press --no-cover

# 查看可用主题
bash <path-to-skill>/scripts/scaffold.sh --list-themes

脚手架会拉起 Vite + React + TS 工作区，从 npm 装最新 reacticle，并放好 source/ plan/ review/ 三个目录 + article/Article.tsx / article/Cover.tsx / article/sections/01-opening.tsx 三份起点文件。

Phase 5 完成后 Agent 跑构建产出单文件 HTML：

npm run build           # → article/article.html（CSS + JS 全内联）

可选 PDF 导出（仅当 Checkpoint 3 用户选了 HTML + PDF）：

bash <path-to-skill>/scripts/html-to-pdf.sh

最佳实践

避免

❌ 把 Skill 当成"帮我做个 HTML 页面" —— 交付物是文章。
❌ 把多个 Checkpoint 决策打包成一个 yes/no。
❌ Raw 块自带颜色 / 字体（主题漂移）。
❌ 把所有 Section 都写进 Article.tsx（杀死 sub-agent 并行）。
❌ 删除 colophon / 封面外壳（这些是契约的一部分）。

常见问题

Q1：什么时候不应该用这个 Skill？ 当用户其实想要的是网页应用 / dashboard / 表单 / 原型 / 通用 landing page —— 这些去找 web-design-engineer，不是这里。不确定时 Skill 会停下来澄清，而不是默默生成错的产物。

Q2：是不是总是 100% 信息保留？ 不是 —— 那只是 longform 类型的默认值。文章类型决定推荐比例，用户可以在 Checkpoint 1 覆盖。

Q3：文章语言可以与源材料不同吗？ 可以。如果用户指定的目标语言与源不一致，Phase 1 会先产出地道翻译版 source/source.<lang>.md，Phase 2+ 据此编写。

Q4：如果 Agent 运行时没有 SubAgent / Task 工具怎么办？ Skill 显式照顾了这种情况：主 Agent 兜底承担 SubAgent 的工作，并在 review 文件首注明"无 SubAgent 环境，主 Agent 兜底"。

Q5：为什么用 React + Vite + reacticle 而不是裸 HTML？ 因为 Agent 需要一个稳定的、prose-first 的组件契约 —— 它要扛住多 Section 并行写作、主题切换、Raw 自由层这些场景。npm run build 时所有依赖会全部内联回单文件 HTML 交付。

工具要求

Skill 假设 Agent 运行时可以：

启动 shell 命令（用于 scaffold.sh / html-to-pdf.sh / npm 构建）
在工作区读写文件
（可选）开启 sub-agent 来跑 First Spread / Section / Final review
（可选）调用 MarkItDown（Python）做高保真 PDF / DOCX / HTML 抽取；不可用时由轻量 fallback 脚本处理 Markdown / TXT / 简单 HTML

许可证

MIT

23 KiB Raw Blame History Unescape Escape