Zed brand-writer 语音校准文档 voice-examples.md 深度解析：十组 Before/After 转化范例、事实保留规则与技能加载机制

本文围绕 voice-examples.md 展开，完整讲解这份“品牌语音转化范例”文档的十组 Before/After 改写样本、[FACT] 事实保留规则与验证流程，并结合 Zed 仓库中 brand-writer 技能的调用管线与 Agent Skills 加载机制，说明这份校准文档在实际写作与评审流程中是如何被消费的。读完本篇，你可以直接复用这套“诊断—重建—校验”方法论来改写技术文案，并理解 Zed 编辑器内置 Agent 如何把技能参考文件自动注入模型上下文。

1. 文档定位：brand-writer 技能的校准基准

voice-examples.md 位于 docs/.conventions/brand-writer/ 目录，开篇即声明其用途：

Ten before/after transformations demonstrating Zed's brand voice. Use these as calibration for diagnosis and reconstruction. （十组 Before/After 转化范例，展示 Zed 的品牌语音。将其用作诊断与重建的校准基准。）

从 CONVENTIONS.md 的目录索引可以看到，brand-writer 目录由四个文件组成：

• SKILL.md — 核心语音原则与工作流
• rubric.md — 八项打分标准
• taboo-phrases.md — 需要消除的模式与短语
• voice-examples.md — Before/After 转化范例（即本文主角）

在 SKILL.md 定义的 Phase 2（Gather Context）中，voice-examples.md 与 rubric.md、taboo-phrases.md 一起作为参考文件被加载；在 Review Mode 里，若任一分项低于 4 分，规范要求“Apply transformation patterns from voice-examples.md”——也就是说，这份文档既是范例集，也是重写时的操作手册。十组范例覆盖了 Zed 文案中最常出问题的场景：性能宣传、协作功能、AI 补全、版本公告、社交媒体文案、产品哲学陈述等，每组都带有诊断分数（对照 rubric.md 的八项标准打分）与逐条转化说明，构成一套可直接对照执行的校准集。

2. 十组 Before/After 转化范例全解

以下按原文档顺序完整继承全部十组范例，并保留原文档给出的诊断分数与转化说明。

2.1 Hype to Specifics（营销腔转具体指标）

Before（评分：Technical Grounding 2/5）

Zed delivers blazingly fast performance that will revolutionize your coding experience. Our cutting-edge technology ensures you never wait again.

After（评分：5/5）

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" → 换成真实技术栈
• "never wait again" → 可度量的表述

值得注意的是，范例中的具体事实点均能在仓库中找到对应实现：GPU 渲染对应 crates/gpui_wgpu 与 crates/gpui，这正是原文档要求把模糊形容词替换为“可验证事实”的原因。

2.2 Marketing to Technical（营销腔转技术说明）

Before（评分：Developer Respect 2/5）

Don't worry about the complicated stuff — Zed handles it all for you! Just focus on what you do best: writing amazing code.

After（评分：5/5）

Zed runs language servers in separate processes with automatic crash recovery. If a language server fails, you keep editing while it restarts.

转化说明：

• 删除居高临下语气（"don't worry"）
• 删除无意义的热情（"amazing"）
• 补充技术机制
• 把读者当作有能力理解技术细节的人

这条范例示范了 rubric 中 Developer Respect 维度的核心：把读者当同行而非待说服的消费者，用“语言服务器独立进程 + 崩溃自动恢复”这一真实机制替代安抚性话术。

2.3 Abstract to Concrete（抽象转具体）

Before（评分：Specificity 2/5）

Zed provides a seamless collaborative experience that brings your team together in powerful new ways.

After（评分：5/5）

Share your workspace with cmd+shift+c. Collaborators see your cursor, selections, and edits in real time. Voice chat is built in — no separate call needed.

转化说明：

• "seamless" → 真实交互流程
• "powerful new ways" → 具体功能
• 补充键盘快捷键（具体的操作入口）
• 描述协作实际呈现的样子

2.4 Em Dash Chains to Natural Flow（破折号链转自然句流）

Before（评分：Natural Syntax 2/5）

Zed is fast — really fast — and built for the way developers actually work — not how tools think they should work.

After（评分：5/5）

Zed is built for speed. We optimized for the workflows developers actually use: jumping between files, searching across projects, editing multiple cursors at once.

转化说明：

• 删除全部破折号
• 拆成两个清晰句子
• 抽象断言 → 具体示例
• "really fast" → 删除（用事实展示，而非口头宣称）

2.5 Enthusiasm to Confidence（狂热转沉稳自信）

Before（评分：Quiet Confidence 1/5）

We're thrilled to announce Zed 1.0! After years of hard work, we can't wait for you to experience what we've built. You're going to love it!

After（评分：5/5）

Zed 1.0 is available today. This release includes GPU text rendering, multi-buffer editing, and native collaboration. Download it at zed.dev.

转化说明：

• 删除全部情绪化语言
• "thrilled" → 删除
• "can't wait" → 删除
• "You're going to love it" → 删除
• 用实质内容替代情绪

2.6 "It's Not X, It's Y" Fix（否定句式修正）

Before（评分：Natural Syntax 2/5）

Zed isn't just an editor — it's a complete development environment. It's not about features — it's about flow. And it's not slow — it's instant.

After（评分：5/5）

Zed combines editing, debugging, collaboration, and AI assistance in one application. Everything runs in the same process, so switching between tasks has no context-switch overhead.

转化说明：

• 消除所有 "it's not X, it's Y" 结构
• 用正向陈述替代否定
• 补充技术理由
• 三个碎片句合并为一个清晰句子

2.7 Vague Benefits to Specific Outcomes（模糊收益转具体结果）

Before（评分：Specificity 2/5）

Zed's AI integration enhances your productivity and streamlines your workflow, helping you code smarter and ship faster.

After（评分：5/5）

Zed runs AI completions inline as you type. Suggestions appear in 200ms. Accept with Tab, reject by continuing to type. The model runs locally or connects to your preferred API.

转化说明：

• "enhances productivity" → 具体交互体验
• "streamlines workflow" → 真实的交互模型
• "code smarter" → 删除（无意义）
• 补充技术选项（本地模型 vs API）

2.8 Social Media Cleanup（社交媒体文案清理）

Before（评分：多项标准 1/5）

🚀 Big news! Zed just dropped MASSIVE updates! Multi-file editing, insane AI features, and SO much more. This is a game-changer, folks! Try it now! 🔥

After（评分：4/5）

Zed 0.150: Multi-buffer editing is here. Edit across files in a single view. AI completions now stream inline. Full changelog at zed.dev/releases.

转化说明：

• 删除全部 emoji
• 删除感叹号
• "MASSIVE" → 具体功能列表
• "game-changer" → 删除
• "SO much more" → 链接到 changelog
• 补充版本号以增强精确性

这是十组中唯一给出 4/5 而非满分的结果，原文档借此提示：即使是清理后的社交媒体文案，也保留“信息优先、不煽动”的基本标准，细节可略有弹性。

2.9 Feature Announcement（功能公告）

Before（评分：Information Priority 2/5）

We've been listening to your feedback, and after months of development, our incredible team has built something truly special. Today, we're excited to finally share our new terminal integration!

After（评分：5/5）

Zed now includes a built-in terminal. Open it with `ctrl+``. Terminals run in splits alongside your editor panes and share the same working directory as your project.

转化说明：

• 以功能本身开头，而非背景故事
• 删除情绪铺垫
• 补充键盘快捷键
• 描述真实行为

2.10 Philosophy Statement（产品哲学陈述）

Before（评分：Quiet Confidence 3/5）

At Zed, we believe that developers deserve better tools. We're passionate about creating the best possible coding experience because we know how frustrating slow, bloated editors can be.

After（评分：5/5）

Developer tools should be fast, understandable, and collaborative. We built Zed to meet that standard. It's open source so you can verify our work and extend it.

转化说明：

• "We believe" → 直接陈述
• "passionate about" → 删除
• "best possible" → 具体标准
• "frustrating, slow, bloated" → 删除对比性贬低
• 补充具体证据点（开源，可验证可扩展）

3. 转化模式总结表

原文档末尾将十组范例提炼为一张“问题—对策”速查表，这是诊断阶段的快速决策依据：

Problem	Solution
Hype words（营销热词）	Replace with measurements（用度量数据替换）
Em dash chains（破折号链）	Split into sentences（拆分为独立句子）
"It's not X, it's Y"	State positively what it is（正向陈述它是什么）
Enthusiasm（狂热情绪）	Delete; add substance（删除并补充实质内容）
Vague benefits（模糊收益）	Name specific features（点名具体功能）
Buried lede（导语埋没）	Lead with the news（新闻先行）
Rhetorical questions（反问句）	Make declarative statements（改为陈述句）
Abstract claims（抽象断言）	Add mechanism or measurement（补充机制或度量）

这张表与 taboo-phrases.md 的“Detection Checklist”配合使用：先扫描最高级、绝对化用词、模糊限定词，再按本表选择对应的解法。

4. 事实保留规则（Fact Preservation Rules）

重写文案时，声音可以变，事实不能丢。原文档定义了三层机制：[FACT] 标记、不可修改清单、重建后校验。

4.1 诊断阶段：用 [FACT] 标记事实断言

Zed is written in [FACT: Rust] with [FACT: GPU-accelerated rendering].
It was built by [FACT: the team behind Atom and Tree-sitter].

4.2 永不修改清单（Never Change）

原文档以表格列出八类必须在改写中原样存活的要素：

Category	Examples
Technical specs	"120fps", "8ms latency", "Rust"
Proper nouns	"Tree-sitter", "Anthropic", "Claude"
Version numbers	"Zed 1.0", "v0.150"
Keyboard shortcuts	"cmd+shift+c", "ctrl+`"
URLs	"zed.dev/releases"
Attribution	"built by the team behind Atom"
Dates	"available today", "released January 2024"
Quotes	Any attributed quotation

4.3 重建后的验证步骤

1. 列出原文中所有事实
2. 确认每一条都出现在终稿中
3. 若某条事实被移除，必须说明理由（例如“与新范围无关”）
4. 若某条事实被改写，标记为错误

4.4 验证示例

带标记的原文：

Zed is [FACT: written in Rust] with [FACT: GPU-accelerated rendering at 120fps]. Built by [FACT: the team behind Atom and Tree-sitter].

重建稿：

Zed renders every frame on the GPU at 120fps. The Rust codebase prioritizes memory safety without garbage collection pauses. The same engineers who built Atom and Tree-sitter lead development.

逐项校验：

• ✅ "Rust" 保留
• ✅ "GPU-accelerated" 保留
• ✅ "120fps" 保留
• ✅ "team behind Atom and Tree-sitter" 保留
• 结论：Pass

该示例同时示范了“声音可以重写、事实必须守恒”的边界：重建稿对 Rust 内存安全的展开是新增的解释性内容，而所有原始事实点全部原样存活。

5. 纵深扩展：这份文档在 Zed Agent 技能管线中的位置

理解了文档本身之后，再回答一个关键问题：当 Zed 用户或 Agent 真正调用 brand-writer 技能时，voice-examples.md 是如何进入上下文的？

5.1 brand-writer 技能的工作流消费它

SKILL.md 采用两遍草稿系统：Pass 1 先产出带 [FACT] 标记的初稿；Pass 2 按 rubric.md 的八项标准打分（Technical Grounding、Natural Syntax、Quiet Confidence、Developer Respect、Information Priority、Specificity、Voice Consistency、Earned Claims，每项 1–5 分，全部 4 分以上即总分不低于 32/40 才通过）；Pass 3 重建时，对任何低于 4 分的维度或命中的禁忌短语，“验证 [FACT] 标记是否存活”是明确步骤。Review Mode 则直接要求对低分文案“Apply transformation patterns from voice-examples.md”——即第 2 节的十组范例就是重写的操作模板，第 3 节的模式表是快速索引，第 4 节的事实规则是终稿放行条件。

5.2 Agent Skills 的加载机制保证参考文件可达

Zed 的 Agent 通过 crates/agent_skills 定义的 Agent Skills 机制加载技能：技能是包含 SKILL.md 与可选参考文件的目录，模型通过 skill 工具按需加载技能正文，相对路径引用（如 rubric.md、voice-examples.md）以技能目录为基准解析。crates/agent_skills/README.md 中给出的 <available_skills> 目录与 <skill_content> 信封，恰好以 brand-writer 作为示例（见 README 中 Activation 一节）：

<skill_content name="brand-writer">
<source>global</source>
<directory>/abs/path/to/skill</directory>
Relative paths in this skill resolve against <directory>.
...the body of SKILL.md, with all `<`, `>`, `&`, `"`, `'` escaped...
</skill_content>

几个与本文档直接相关的实现事实（均可在 README 与 crates/agent/src/tools/skill_tool.rs 中核对）：

• 渐进式披露：模型系统提示词中只出现技能的 name + description 目录，voice-examples.md 这类参考文件的正文在模型需要时才被读取，因此十组范例不会白白占用默认上下文；
• 目录基准解析：信封中的 <directory> 字段让模型能把 voice-examples.md 这样的相对引用解析为绝对路径，再经 read_file 读取；
• 严格校验：技能 frontmatter 的 name 必须匹配 [a-z0-9-]{1,64}、description 需为 1–1024 字符，不满足直接拒绝加载；SKILL.md 顶部的 name: brand-writer 与 description 正是通过这一校验才被纳入目录的；
• 目录预算：全部技能的 name + description 总量上限为 50KB，超限技能会被丢弃并给出加载错误。

从源码结构看，docs/.conventions/brand-writer/ 这套文件就是被 CONVENTIONS.md 指向、被 Agent Skills 机制按目录加载的“项目内技能参考集”：SKILL.md 是入口，rubric.md 与 taboo-phrases.md 提供打分与红线，而 voice-examples.md 提供可执行的改写范例与事实守恒校验——三者缺一不可。

6. 实战要点：如何把这套方法用于你自己的文案

结合原文档内容与仓库管线，可以归纳出可操作的工作流：

1. 先标记后改写：对初稿中所有技术规格、专有名词、版本号、快捷键、URL、署名、日期、引用逐条打 [FACT] 标记；
2. 对照十组范例诊断：逐条检查文案是否落入第 2 节覆盖的十类问题（热词、破折号链、否定句式、情绪铺垫、模糊收益、埋没导语、反问开头等），并按第 3 节模式表选择解法；
3. 按八项标准打分：使用 rubric.md 的评分表，任何一项低于 4 分即重建对应段落，总分低于 32/40 或出现 taboo-phrases.md 中列出的自动失败项（感叹号、"We're excited"、"revolutionary"、单段两个以上破折号、"It's not X, it's Y"）则整段重写；
4. 终稿跑事实校验：按 4.3 的验证步骤逐条比对 [FACT] 标记，事实被改写即判为错误；
5. 过 Litmus Test：SKILL.md 给出的最终自检——资深开发者是否会尊重这段文字？它是否读起来像 zed.dev 的内容？朗读是否通顺？解释是否多于推销？

这套“范例校准 + 量化评分 + 事实守恒”的组合，其价值在于把主观的“写得专业”拆解为可检查的步骤：十组 Before/After 解决“往哪个方向改”，八项评分解决“改到多够好”，[FACT] 规则解决“改的时候不能丢什么”。无论是给 Zed 官方写文档，还是把同样的方法迁移到其他开源项目的技术传播，这三层都可以直接复用。