Zed brand-writer 技能解析：用八维评分量表与事实标记约束 AI 生成品牌文案的 Agent Skill 体系

本文基于 Zed 仓库内的 brand-writer 技能定义 展开，系统讲解这套为 AI Agent 编写的品牌文案技能如何运作：从语气规范、八维评分量表、禁忌短语检测，到 [FACT] 事实标记与两轮诊断重构流程。读完你可以掌握一套可直接复用的"用量化评分约束 LLM 写作质量"的工程化方法，并理解 Zed 如何把产品文案与其 Rust 代码库中的真实技术事实（GPU 渲染、协作架构、Tree-sitter 解析）绑定起来。

一、技能定位：把品牌语气写成可执行的 Agent 指令

Zed 仓库在 .factory/skills/ 目录下维护了一组面向 AI Agent 的写作技能。SKILL.md 的 frontmatter 声明了它的基本元数据：

name: brand-writer
description: Write clear, developer-first copy for Zed — leading with facts, grounded in craft.
allowed-tools: Read, Write, Edit, Glob, Grep, AskUserQuestion, WebFetch
user-invocable: true

几个字段值得注意：

• user-invocable: true 表示用户可以显式调用该技能，文档中给出的调用形式包括启动写作会话（/brand-writer）、指定写作主题（/brand-writer "homepage hero copy"）以及对既有文案做品牌适配审查（/brand-writer --review "paste copy"）三种；
• allowed-tools 限定技能只能使用读取、写入、编辑、检索类工具加 WebFetch，保证写作过程中的事实来源可控；
• 技能本体不是散文式的"风格建议"，而是一套带评分阈值、检测清单和固定工作流的验证系统，这是它能被 Agent 稳定执行的关键。

该技能的语气基准被描述为"thoughtful, technically grounded, and quietly confident"——像一位为开发者造工具的资深开发者在说话，"说清事实、解释机制、让读者自己下结论"，绝不试图推销。文档明确要求避免碎片化短句、节奏性营销句式、滥用破折号以及 "it's not X, it's Y" 这类对偶构造。

二、核心信息支柱：文案必须围绕哪些事实

SKILL.md 定义了五条核心信息（Core Messages），所有文案都应从这五条中取材：

1. Code as craft（代码即工艺）：从零构建，一切特性都有明确目的；
2. Made for multiplayer（为多人协作而生）：代码是协作的，团队与 AI Agent 在同一个空间实时工作；
3. Performance you can feel（可感知的性能）：用 Rust 编写，每一帧都由 GPU 加速，打字和移动光标时像素即时响应；
4. Always shipping（持续发布）：面向当下构建，每周改进；
5. A true passion project（真正的热情项目）：开源、公开构建，来自 Atom 与 Tree-sitter 背后的团队。

这五条信息不是口号，每一条都能在当前仓库中找到实现证据，这正是该技能强调的"earned claims（可挣得的声明）"原则：

• "用 Rust 编写"——仓库本身就是纯 Rust 工作区，根 Cargo.toml 组织了一百多个 crate；
• "GPU 加速每一帧"——crates/gpui/Cargo.toml 中自述为 "Zed's GPU-accelerated UI framework"，其 README 进一步说明 GPUI 是混合立即/保留模式的 GPU 加速 UI 框架；
• "团队与 AI 在同一个空间实时工作"——协作能力由 crates/call 等 crate 实现，依赖 livekit_client 提供音视频与实时通道；
• "来自 Atom 与 Tree-sitter 背后的团队"——README.md 开篇即声明 Zed 是 "a high-performance, multiplayer code editor from the creators of Atom and Tree-sitter"，仓库内另有 crates/grammars 下的 130 余个 Tree-sitter 查询文件（.scm）支撑增量解析与语法高亮。

从源码结构看，品牌文档中的每条主张都可以映射到一个具体 crate 或目录，这种"文案—代码"的一一对应关系是整套评分体系的落点。

三、八维评分量表（Rubric）：通过线是所有维度 4 分以上

rubric.md 定义了 8 个评分维度，每个维度 1–5 分，所有维度都必须达到 4 分及以上才算通过（总分门槛 32/40）：

维度	考察点	5 分标准
Technical Grounding（技术落地）	是否做出具体、可验证的技术声明	精确到规格、架构、可测量结果
Natural Syntax（自然语法）	读起来是否像一位深思熟虑的开发者在说话	句式多变、朗读顺畅
Quiet Confidence（安静的自信）	是否不带炒作地陈述事实	事实自己说话，读者自己下结论
Developer Respect（对开发者的尊重）	是否把读者当同行而非潜在客户	平等对话，默认读者有技术能力
Information Priority（信息优先级）	最重要的信息是否在最前	关键事实或变更领起，背景随后
Specificity（具体性）	声明是否具体、可测量	每个声明都具体且可验证
Voice Consistency（语气一致性）	全文语气是否统一	从头到尾单一连贯的声音
Earned Claims（可挣得的声明）	断言是否有支撑	每个声明都可以演示或验证

每个维度都配有正反例。例如 Technical Grounding 的 5 分示例是 "Written in Rust with GPU-accelerated rendering at 120fps"，1 分反例是 "Blazingly fast performance that will transform your workflow"；Information Priority 的 5 分示例是 "Inline completions now stream token-by-token. Previously, you waited for the full response."——先说变更本身，不铺垫情怀。

量表的决策规则同样量化：

• 全部 4 分及以上：文案通过，可做轻微打磨；
• 任一维度 3 分：重写被标记的段落并重新评分；
• 任一维度 2 分或以下：需要整体重构；
• 多个维度失败：推倒重来，换新思路。

这种"维度级门槛 + 总分门槛"双保险的判定方式，比单纯看总分更能防止"用某维度的高分掩盖另一维度的硬伤"。

四、禁忌短语表：AI 腔与营销腔的可检测模式

taboo-phrases.md 把"哪些写法会暴露 AI 生成或营销过重"做成了一张可直接扫描的检测表，分为几大类：

1. 炒作词（Hype Words）：revolutionary、game-changing、cutting-edge、blazingly fast、seamless、frictionless、powerful、robust 等二十余词，每条都注明失效原因（"未挣得的最高级""含义模糊的buzzword""几乎从不成立"）。

2. AI 结构模式：带改写示例的构造级检测，包括：

❌ "Zed is fast — really fast — and it shows in every interaction."
✅ "Zed is fast. You'll feel it in every interaction."   （破折号链）

❌ "It's not just an editor — it's a complete development environment."
✅ "Zed combines editing, collaboration, and AI assistance in one workspace."（否定对偶）

❌ "Fast. Focused. Collaborative."
✅ "Zed is built for speed and collaboration."            （三连排比）

❌ "What if your editor could keep up with your thinking?"
✅ "Zed renders every keystroke instantly."              （修辞性问句开头）

3. 空洞热情（Empty Enthusiasm）："We're excited to announce..."、"You'll love..."、"The wait is over" 等模式全部要求删除。

4. 模糊收益（Vague Benefits）：给出"替换提问"映射，例如遇到 "enhanced productivity" 就问"How much faster? At what task?"，遇到 "optimized performance" 就问"What metric improved?"

5. 禁用标点：零感叹号、无戏剧性省略号、不用全大写强调、修辞性问句不得作开头、每段破折号最多一个。

6. 检测清单（Detection Checklist） 要求最终扫描五类残留：最高级（best/most/fastest/only）、绝对词（always/never/every）、模糊限定（might/potentially）、强化副词（very/really/extremely）、模糊量词（many/numerous/significant）。规则一句话总结：If you can't prove it or measure it, rewrite it.

文档还定义了"自动失败"红线：出现任何感叹号、"We're excited/thrilled"、"revolutionary/game-changing"、同段两个以上破折号、"It's not X, it's Y" 构造，直接不通过。

五、转换示例与事实保留规则（voice-examples.md）

voice-examples.md 提供了十个完整的"前/后"转换案例，每个案例标注了原文的失分维度，并附转换说明。选几个代表：

炒作到具体（Technical Grounding 从 2/5 到 5/5）：

Before: "Zed delivers blazingly fast performance that will revolutionize your coding experience." After: "Zed is written in Rust with GPU-accelerated rendering. Keystrokes register in under 8ms. Scrolling stays at 120fps even in large files."

转换说明逐条列明："blazingly fast" 换成具体延迟数字，"revolutionize" 直接删除，"cutting-edge technology" 换成真实技术栈。

营销腔到技术陈述（Developer Respect 从 2/5 到 5/5）：

Before: "Don't worry about the complicated stuff — Zed handles it all for you!" After: "Zed runs language servers in separate processes with automatic crash recovery. If a language server fails, you keep editing while it restarts."

社交媒体清理（多维 1/5 到 4/5）：把带 emoji、全大写和感叹号的发布文案，改写成带版本号、具体特性和 changelog 位置的克制版本。

除转换案例外，该文件定义了事实保留规则，这是整套流程中防止"重写丢事实"的核心机制：

诊断阶段打标记：把所有事实性声明打上 [FACT] 标签，包括技术规格（"120fps"、"8ms latency"）、专有名词（"Tree-sitter"）、版本号（"Zed 1.0"）、键盘快捷键（"cmd+shift+c"）、URL、归属声明、日期和引语。

重构后逐条核对：列出原文全部 [FACT]，确认每条都出现在终稿中；被删除的事实必须说明理由（如与新篇幅无关），被改动的事实标记为错误。文件给出了一份通过示例：原文标注的 Rust、GPU 加速、120fps、Atom/Tree-sitter 团队归属四条事实，在重构后的表述中全部保留，判定 Pass。

六、五阶段工作流：从理解需求到评分卡交付

SKILL.md 定义了完整的执行工作流：

Phase 1 理解需求：先澄清四问——用途是什么（首页、发布说明、文档、社交、产品页）、受众是谁、核心信息或特性是什么、有无具体约束（字数、格式）。

Phase 2 收集上下文：自动加载技能文件夹内的三个参考文件（rubric.md、taboo-phrases.md、voice-examples.md），需要时再检索既有文案和文档/代码中的技术细节。

Phase 3 双轮（实为三轮）起草：

• Pass 1 初稿：写出初稿并为所有事实声明打 [FACT] 标签，标签范围覆盖技术规格、专有名词、版本与日期、快捷键与 URL、归属与引语；
• Pass 2 诊断：按八维量表逐项打分并记录问题，再扫描全部禁忌短语并逐条给出行号引用；
• Pass 3 重构：对任何低于 4 分的维度或命中的禁忌短语，定位具体问题、重写对应段落、验证 [FACT] 标记是否存活、对重写段落重新评分，循环直到所有维度 4 分以上。

Phase 4 人性化复核（推荐用于高风险内容）：首页、发布公告、产品页等高风险文案，建议再交给仓库内另一个技能 humanizer 处理。humanizer 基于维基百科 "Signs of AI writing" 指南整理的 24 种 AI 写作模式（显著性膨胀、copula 回避、否定对偶、三连排比、破折号滥用、聊天机器人残留语等）做二次扫描，并要求追问"这段文字还剩下什么明显是 AI 生成的"，补上 brand-writer 流程筛不掉的 AI 痕迹。两个技能形成分工：brand-writer 管品牌语气与事实保真，humanizer 管 AI 腔的最后一道清洗。

Phase 5 验证交付：输出终稿 + 评分卡 + 事实核验清单：

## Final Copy
[The copy here]

## Scorecard
| Criterion           | Score |
|---------------------|-------|
| Technical Grounding |   5   |
| ...                 |       |
| **TOTAL**           | 37/40 |

✅ All criteria 4+
✅ Zero taboo phrases
✅ All facts preserved

## Facts Verified
- [FACT: Rust] ✓
- [FACT: GPU-accelerated] ✓

文档还按发布场景给出了输出格式约定：首页用 H1 + H2 + 支撑段落；产品页用带解释文案的小节标题；发布说明按"改了什么、怎么工作的、为什么重要"组织；文档简介讲清"这是什么、什么时候用"；社交内容简短、不带话题标签、附进一步了解的链接。

七、Review 模式：对既有文案做品牌适配审计

用 --review 调用时，技能退化为审计器而非生成器，流程为：

1. 加载三个参考文件；
2. 对给定文案按八维量表打分；
3. 扫描禁忌短语，逐条列出并附行号（如 Line 2: "revolutionary" (hype word)、Line 5: "—" used 3 times (em dash overuse)）;
4. 给出诊断结论，示例输出格式为 "❌ Does not pass (3 criteria below threshold)";
5. 只要任一维度低于 4 分，即提供重写：套用 voice-examples.md 的转换模式、保留原文全部事实、附上新版本与新评分。

八、这套方法的工程价值

把 SKILL.md 与其三个参考文件合起来看，它示范了一种可迁移的"LLM 输出质量控制"范式：

• 把软标准做成硬量表：八维 1–5 分加"全维度 4 分门槛"，让"写得像不像"变成可复算的判定；
• 把风格禁忌做成可扫描模式：破折号链、否定对偶、三连排比、感叹号都给出了可机械检测的形态和自动失败红线；
• 用事实标记把重写与失真解耦：[FACT] 标签加重构后的逐条 diff，保证风格可以推翻重来、事实不可丢失；
• 用仓库事实锚定品牌声明：文案中"Rust 编写、GPU 每帧加速、实时协作、Atom 与 Tree-sitter 团队"这些主张，分别能在 README.md、crates/gpui/Cargo.toml、crates/call/Cargo.toml 和 crates/grammars 中找到实现对应——"earned claims"不只是修辞要求，而是仓库结构本身支撑的写作纪律；
• 双技能串联清洗 AI 腔：brand-writer 之后接 humanizer 的 24 模式扫描，构成品牌层与语言层两道独立闸门。

对于需要在产品文案、发布说明、文档中持续输出"事实优先、可验证、去 AI 腔"内容的团队，这套评分卡 + 禁忌表 + 事实标记的组合是一个可以直接照抄到自家 Agent 工作流中的模板。