企业官网建设流程全解析

• AI 插件
• 开发工具
• 插件系统

导读

本文讲解 claude-plugins-official 仓库中 Playground 插件的 document-critique 模板：如何构建一个用于审阅 SKILL.md、README、规格说明（spec）、提案（proposal）等文本的交互式 HTML 工具——左侧带行号与高亮的文档面板，右侧可筛选的批注卡片，底部根据「通过/拒绝/评论」状态实时生成可复制的 Prompt。读完本文，你将掌握该模板的布局、状态结构、行号匹配、文档渲染、Prompt 生成与高亮样式的完整实现思路，并能在 Playground 插件框架下将其落地为自包含单文件 HTML。

模板定位：Playground 家族的文档审阅成员

在 plugins/playground 插件中，playground 被定义为"自包含的单文件 HTML 探索器"：一侧是交互控件，另一侧是实时预览，底部是可复制 Prompt 的输出区。用户调整控件、可视化探索后，把生成的 Prompt 复制回 Claude 继续执行。

SKILL.md 列出了六种内置模板，其中 document-critique 专门负责文档审阅场景：

• templates/document-critique.md— 文档审阅（带 approve/reject/comment 工作流的建议）
• templates/design-playground.md— 视觉设计决策
• templates/data-explorer.md— 数据与查询构建
• templates/concept-map.md— 概念图谱学习
• templates/diff-review.md— 代码 diff 逐行评论
• templates/code-map.md— 代码库架构可视化

该模板的适用对象非常明确：SKILL.md 文件、README、规格说明、提案，以及"任何需要结构化反馈（approve/reject/comment 工作流）的文本"。与 diff-review 面向代码、code-map 面向架构不同，document-critique 的核心是把文档行作为批注锚点，让审阅意见落到具体行号上。

整体布局：三栏结构的审阅工作台

模板给出如下布局示意：

+---------------------------+--------------------+ | | | | Document content | Suggestions panel | | with line numbers | (filterable list) | | and suggestion | • Approve | | highlighting | • Reject | | | • Comment | | | | +---------------------------+--------------------+ | Prompt output (approved + commented items) | | [ Copy Prompt ] | +------------------------------------------------+

三个区域各司其职：

• 左侧文档面板：展示完整文档并带行号，有建议的行通过左侧彩色边框高亮，状态色区分 pending（琥珀色）、approved（绿色）、rejected（红色半透明）；点击建议卡片可滚动定位到对应行。
• 右侧建议面板：提供 All / Pending / Approved / Rejected 四个筛选 Tab，头部显示各状态统计数；每张建议卡片包含行引用（如 "Line 3" 或 "Lines 17-24"）、建议文本、Approve / Reject / Comment（已决策时显示 Reset）按钮，以及可选的用户评论输入框。
• 底部 Prompt 输出：仅从「已通过的建议 + 用户评论」生成 Prompt，按 Approved Improvements、Additional Feedback、Rejected（作为上下文）分组，提供带 "Copied!" 反馈的复制按钮。

这与 SKILL.md 定义的 playground 通用形态（控件 + 实时预览 + 底部 Prompt 输出 + 复制按钮）完全一致——document-critique 的特殊之处在于"控件"被替换为建议卡片列表，"预览"被替换为带行号高亮的文档渲染。

状态结构：单一 state 对象驱动一切

模板给出建议项与全局状态的数据结构：

const suggestions = [ { id: 1, lineRef: "Line 3", targetText: "description: Creates interactive...", suggestion: "The description is too long. Consider shortening.", category: "clarity", // clarity, completeness, performance, accessibility, ux status: "pending", // pending, approved, rejected userComment: "" }, // ... more suggestions ]; let state = { suggestions: [...], activeFilter: "all", activeSuggestionId: null };

几个关键设计点：

• category 枚举固定为五类：clarity（清晰度）、completeness（完整性）、performance（性能）、accessibility（无障碍）、ux（用户体验）。类别标签让批量审阅可以按问题类型归并分析。
• status 三态流转：pending→approved/rejected，已决策后按钮变为 Reset，允许撤销决策重新审阅。
• 单一 state 对象：activeFilter控制右侧列表筛选，activeSuggestionId记录当前聚焦的建议，用于左侧文档滚动联动。

这与 SKILL.md 强调的"状态管理模式"一脉相承：保持单一 state 对象，每个控件写入它，每次渲染读取它。对于 document-critique，写入 state 的事件来自 Approve/Reject/Comment 按钮与用户评论 textarea，渲染则包括文档高亮、建议列表统计与 Prompt 输出三处。

建议到行号的匹配：模糊就近解析

由于文档内容可能被编辑、行号可能微移，模板采用"解析 lineRef + 模糊匹配"的策略：

const suggestion = state.suggestions.find(s => { const match = s.lineRef.match(/Line[s]?\s*(\d+)/); if (match) { const targetLine = parseInt(match[1]); return Math.abs(targetLine - lineNum) <= 2; // fuzzy match nearby lines } return false; });

实现要点：

• 用正则/Line[s]?\s*(\d+)/同时兼容 "Line 3" 与 "Lines 17-24" 两种行引用写法；
• 取第一个数字作为锚点行号；
• 允许 ±2 行的误差窗口，容忍文档小幅改动造成的行号漂移；
• 匹配结果用于决定该行是否渲染建议高亮边框。

这段代码体现了 document-critique 与 diff-review 的差异：diff 审阅的行号是 git 语义上固定的，而文档审阅中行号是软性的，因此需要容错匹配。

文档渲染：内联 Markdown 的轻量处理

模板要求文档面板支持 Markdown 风格的内联格式化渲染，并正确处理代码块边界：

// Skip ``` lines, wrap content in code-block-wrapper if (line.startsWith('```')) { inCodeBlock = !inCodeBlock; // Open or close wrapper div } // Headers if (line.startsWith('# ')) renderedLine = `<h1>...</h1>`; if (line.startsWith('## ')) renderedLine = `<h2>...</h2>`; // Inline formatting (outside code blocks) renderedLine = renderedLine.replace(/`([^`]+)`/g, '<code>$1</code>'); renderedLine = renderedLine.replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>');

处理逻辑的关键细节：

• 代码块状态机：以```行切换inCodeBlock，进入代码块后用 wrapper div 包裹，避免其中内容被误当作 Markdown 解析；
• 标题：#渲染为<h1>，##渲染为<h2>，为文档提供层级视觉；
• 行内代码：反引号包裹的内容转为<code>；
• 加粗：**...**转为<strong>。

需要说明的是，这是内联渲染而非完整 Markdown 引擎——模板只覆盖了标题、代码、加粗等最小子集。对于审阅场景，这已经足够让读者看清文档结构与关键术语，同时保证单文件 HTML 零外部依赖（对应 SKILL.md 中"内联所有 CSS 与 JS、无外部依赖"的核心要求）。

Prompt 输出生成：只收录可执行项

模板的核心原则是"仅包含可执行项"——未通过、无评论的建议不进入 Prompt，避免噪音：

function updatePrompt() { const approved = state.suggestions.filter(s => s.status === 'approved'); const withComments = state.suggestions.filter(s => s.userComment?.trim()); if (approved.length === 0 && withComments.length === 0) { // Show placeholder return; } let prompt = 'Please update [DOCUMENT] with the following changes:\n\n'; if (approved.length > 0) { prompt += '## Approved Improvements\n\n'; for (const s of approved) { prompt += `**${s.lineRef}:** ${s.suggestion}`; if (s.userComment?.trim()) { prompt += `\n → User note: ${s.userComment.trim()}`; } prompt += '\n\n'; } } // Additional feedback from non-approved items with comments // Rejected items listed for context only }

该函数的输出策略可拆解为：

1. 空态占位：无已通过建议且无带评论项时，显示占位提示而非空 Prompt；
2. 主输出格式：以 "Please update [DOCUMENT] with the following changes:" 开头，[DOCUMENT]是待替换的目标文档占位符；每条建议以**行引用:** 建议文本呈现；
3. 用户评论并入：已通过的建议若附带用户笔记，以→ User note:追加在建议下方；
4. 补充反馈：未通过但带评论的条目进入 Additional Feedback 分组；
5. 拒绝项：仅作为上下文列出，供接收方了解被否决的意见。

对照 SKILL.md 的 Prompt 输出模式（自然语言而非数值倾倒、只提及非默认选择、包含足够上下文使其脱离 playground 也能执行），document-critique 的 Prompt 同样遵循"可独立行动"原则——接收方拿到 Prompt 即可对原文档实施修改。

状态高亮样式：三态色板

文档行的高亮通过左侧边框 + 半透明背景色实现，模板给出三态配色：

.doc-line.has-suggestion { border-left: 3px solid #bf8700; /* amber for pending */ background: rgba(191, 135, 0, 0.08); } .doc-line.approved { border-left-color: #1a7f37; /* green */ background: rgba(26, 127, 55, 0.08); } .doc-line.rejected { border-left-color: #cf222e; /* red */ background: rgba(207, 34, 46, 0.08); opacity: 0.6; }

三态语义一目了然：

其中 rejected 额外叠加 0.6 透明度，让被否决的行在视觉上"退后"，与 approved 的醒目形成对比。配色采用 GitHub 风格的语义色（绿=通过、红=拒绝、琥珀=待定），用户无需文字说明即可快速读取审阅状态。

预填充建议：构建具体文档的审阅 playground

当为一个具体文档构建审阅 playground 时，模板给出三步流程：

1. 读取文档内容（Read the document content）
2. 分析并生成建议，每条建议包含：
   • 具体的行引用（specific line references）
   • 清晰、可执行的建议文本（clear, actionable suggestion text）
   • 类别标签（category tags：clarity、completeness、performance、accessibility、ux）
3. 将文档内容与建议数组一起嵌入 HTML（Embed both the document content and suggestions array in the HTML）

这意味着建议数组是预生成而非运行时由 AI 实时产出——构建者（Claude 或开发者）先分析目标文档，把结构化建议硬编码进单文件 HTML，用户在浏览器中只需做决策（Approve/Reject/Comment），无需联网即可完成审阅闭环。结合 SKILL.md 的使用流程，完整落地路径是：识别 playground 类型 → 加载对应模板 → 按模板构建 HTML → 用open <filename>.html在浏览器中打开。

典型应用场景

模板列举了五类最契合的场景，均围绕"文本审阅 + 结构化决策"展开：

• SKILL.md 审阅：评估技能定义的质量、完整性、清晰度——直接服务于本仓库中大量 SKILL.md 的质量把关；
• README 批判性审阅：文档质量、缺失章节、表述不清之处；
• 规格说明（spec）审阅：需求清晰度、缺失边界情况、歧义；
• 提案反馈：结构、论证、缺失背景；
• 代码注释审阅：docstring 质量、行内注释的实用性。

这些场景的共同特征是：目标文本有明确的行结构，且需要"接受/拒绝/补充说明"的明确决策，而非开放式讨论——这正是 approve/reject/comment 工作流优于普通批注的地方。

落地要点：与 Playground 通用规范的协同

将 document-critique 模板用于真实项目时，应同时满足 SKILL.md 对每个 playground 的通用要求：

• 单 HTML 文件：内联全部 CSS/JS，无外部依赖（CDN 不可用时 playground 不失效）；
• 实时预览：每次状态变更（Approve/Reject/Comment）立即触发文档高亮、统计数字与 Prompt 输出刷新，无 "Apply" 按钮；
• 自然语言 Prompt：输出是可执行的修改指令而非数值转储，且包含足够上下文（文档名、行引用、建议文本），脱离 playground 也能独立执行；
• 复制按钮：剪贴板复制并带 "Copied!" 反馈；
• 合理的默认值与预置：首次加载即有可用的审阅内容（预填充建议），3-5 个命名预置可一键切换建议组合视图；
• 深色主题：UI 使用系统字体，代码/数值使用等宽字体，最小化界面装饰。

最后提醒两个常见误区（对应 SKILL.md 的 "Common mistakes"）：一是 Prompt 输出退化为建议文本的"数值倾倒"——务必按 Approved/Additional/Rejected 分组并只收录可执行项；二是建议过多导致界面失控——通过筛选 Tab、状态统计与点击滚动联动，把决策负担降到最低。

小结

document-critique 模板给出了一个完整的"文档审阅 playground"实现蓝图：三栏布局明确交互分区，单一 state 对象统一管理建议决策，模糊行号匹配容忍文档漂移，内联 Markdown 渲染保持零依赖，三态高亮让审阅状态一目了然，Prompt 输出只沉淀可执行决策。结合 Playground 插件 与 SKILL.md 的通用规范，你可以在半小时内为一个 SKILL.md 或 README 构建出可复制、可交付的审阅工具——这正是 Playground 生态"把结构性探索变成可复用的单文件交互工具"的设计初衷。

• AI 插件
• 开发工具
• 插件系统