visant-copy

Visant Copy

这里有两件事：Visant 文案的语气（适用于任何代码库），以及文案的操作方式，具体取决于文本所在的位置。下面的语气规则适用于巴西葡萄牙语；英文文案请阅读 english.md。 检查器会对每项输入运行一套葡萄牙语规则和一套英语规则。

• 代码库使用 Visant 的流水线（根目录下有 copy*.json，且 package.json 中有 copy:build/copy:check 脚本）：JSON 是 SSoT，HTML 是生成的视图，因此绝不要直接编辑 .html 中的文案。请参阅“如果代码库使用 Visant 的流水线”。
• 其他任何代码库（文案位于组件中、.md 文件或导出的 CMS 中）：组件是 SSoT，风险在于重复，同一句话出现在四个文件里。

动手修改文本前，先确认属于哪种情况：

ls copy*.json 2>/dev/null; grep -nE '"copy:(lint|build|check)"' package.json

无论哪种情况，都绝不要在未遵守以下禁令的情况下撰写 Visant 文案。

规则零：只提建议，绝不直接修改

只有检查器指出的问题才可以写入文件。 标题、导语或句子只要通过检查，就保持原样，即使你觉得它听起来平淡。

风格优化应作为报告中的建议表格（键、修改前、修改后）提出，由用户逐行选择。重写原本已经不错的内容会损害信任，还会让用户不得不审查审查者。

例外情况是用户明确提出要求。“Essa copy tá confusa, tem que ser na pegada X”是工作指令，不是讨论邀请：直接修改，展示修改前后对照表，并在末尾提供一到两个单行备选方案，这样替换只需一次 Edit，无需再来一轮。用户已经明确提出方向时，如果只给出选项，就是把工作又推回给用户。

禁令

绝对禁止。适用于标题、正文、CTA、FAQ、邮件、说明文字、替代文本、错误消息和元描述。没有“但这次管用”的例外。

1. 绝不使用破折号（— 或 –）。 使用句号、逗号、冒号或括号。
2. 绝不使用分隔点（·，alt+7）。 元数据列表中不能用，带价格的 CTA 中不能用，阶段标签中不能用，社交卡片中也不能用。列表中改用句号和逗号（“34 páginas. 9 etapas, 1 case inteiro”），标签中改用冒号（“Fase 1: A Estratégia”），CTA 中改用介词（“Quero o e-book por R$ 47”）。
3. 绝不使用“Não é X, é Y”。 不能拆成两个句子（“Não é uma lista. É uma cascata.”），也不能用否定句来定义（“Não é slogan.”）。
4. 绝不使用“É sobre X”。 这句话没有表达任何内容。换成描述事物作用的动词。
5. 绝不使用“Não é apenas X, é X e Y”。 “mais que apenas”“menos X e mais Y”“não se trata de”也不行。
6. 句末绝不悬着否定表达。 “Feito pra ler, não pra arquivar.” 删除后半句，句子会更有力。
7. 绝不使用表情符号。绝不使用分号。（©、®、™ 是商标，应保留。）
8. 绝不使用导师式开场。 “Imagine que”“E se eu te dissesse”“Prepare-se pra”“Chegou a hora de”。从事实或场景写起。
9. 绝不使用老套的紧迫感表达。 “Últimas vagas”“corre que acaba”“por tempo limitado”。稀缺性必须可计数：说出数量（“este lote tem 30 vagas”“a cota sobe a cada compra”）。
10. 每页最多使用一次可信度背书词。 “real”“de verdade”“na prática”“de fato”“genuíno”“autêntico”。出现一次没问题。出现两次，读者就会数出来并发截图（“trajetória real, projeto real, técnica real, processo real”）。形容词不能证明什么，数字和场景才可以。 Sete anos de projeto real → Sete anos entregando marca

解决第 3 至第 6 条的规则：删掉否定部分。 剩下的句子几乎总是正确的。如果对比确实是论点，就展示结果，而不是使用否定表达：不要写“não é falta de talento, é falta de ordem”，改写为“Talento você já tem. O que falta é ordem.”

检查器

交付文案前必须运行。使用纯 Node，无依赖，可在任何仓库中运行：

L=~/.claude/skills/visant-copy/scripts/copy-lint.mjs
node $L copy.json                       # copy JSON
node $L hero.tsx page.tsx og.tsx        # components, passed TOGETHER
node $L README.md docs/landing.md       # markdown or plain text
npm run copy:lint                       # if the repo uses Visant's pipeline

具体检查内容如下：

输入	检查方式	报告位置
.json（任意结构，但必须是有效 JSON）	所有层级的每个字符串值	点分隔的键（hero.title）
代码（.js .jsx .ts .tsx .mjs .cjs .vue .svelte .astro）	逐行检查，并屏蔽注释	L<n>
其他文本（.md、.html、.txt）	逐行检查，不屏蔽内容	L<n>

• 文件或文件夹，可指定一个或多个。文件夹会遍历上述类型的文件，并跳过 node_modules、.git、.next、dist、build、out、coverage 和点开头的文件夹。
• JSON 无效或路径不存在时，会输出一行错误并以退出码 1 结束。
• 每个文件都会检查 Emoji。分号和竖线分隔符仅检查 .json（在 .md 中，竖线用于表格；在代码中，; 是语法的一部分）。
• 标志：--quiet（仅返回退出码，适用于 CI）、--include-comments（也检查代码注释）、--self-test（触发每条 PT 和 EN 规则，并通过无问题的句子）。
• ID 使用英文：语言专属规则使用 pt-/en- 前缀（pt-not-x-but-y、en-hype），标点规则使用无前缀 ID（em-dash、bullet-separator、semicolon）。旧版 PT ID（travessao、bolinha）仍可在配置中使用。EN hype 规则需要营销对象：“Unlock account”可通过，“unlock your potential”则无法通过。

遇到问题时，以退出码 1 结束，并提供键、摘录和修复建议。还有两种警告不会影响退出码，因为文案不应因细节问题而无法通过：

• 按行类型限制长度（标题 60、CTA 28、导语 180、正文 280、SEO 标题 60、元描述 160），仅适用于 .json，根据键的后缀推断；如果标题在移动设备上被拆成三行，就会触发警告；
• 重复内容：同一句话出现在本次调用传入的两个文件中时触发。这就是为什么要将文件一起传入，而不是逐个传入。

有意不检查代码文件中的注释：JSDoc 不是文案。

重复次数限额按 PIECE 计算，而文件不一定就是一个 PIECE

credibility-seal（限额为 1，PT 和 EN 词语共用限额）按 PIECE 计数：在 JSON 中按第一个键段（onboarding.*）计数，在组件中按文件计数。金钱金额（R$ 47）不算 seal；其余内容按语义判断，因此请在 file:line 处确认。原因。

语气

风格取自 Visant 的电子书落地页。按重要程度排序：

1. 适度使用巴西口语。 使用 “pra”、“a gente”、“tá”。不要用 “cê”、“mano”、 “tá ligado”。祈使句要简短：“读完再判断”、“留意一件事”。
2. 短句接短句。 平均每句 12 个词。不带动词的片段是一种修辞手法，总是接在长句后面，起强调作用：“……而且品牌三个月后表现得又不一样了。每次都是。”
3. 描绘场景，不用形容词。 永远不要写“品牌不一致”。写出看到的情况：“一篇帖子说一套，客服说另一套，网站看起来像另一家公司做的。”
4. 先从自己身上找原因。 指责别人之前先坦白：“我们一开始也从 Logo 入手。就这样浪费了好几周，直到我们调换了顺序。”只有坦白之后，才可以直接指责读者（如果确有必要）：“你从 Logo 入手，是因为那部分做起来有趣。”
5. 写出准确数字，不要为了显得厉害而取整。 R$450k、160+ lives、 34 páginas、7 dias。
6. 承认局限。 “有些东西对我们没用，我们会明明白白写出来。”这是文风与 AI 文本最显著的区别。
7. 用幽默挖苦行业，冷面表达，不做提示。 “没有长达 40 小时、教你怎么把矩形居中的课程。”针对做法，不针对个人。
8. 每页最多轻微爆粗一次，而且只能用在论证最有力的地方：“烂事”、“搞砸了”。CTA 和主标题里绝不使用。
9. 用读者自己的口吻写异议。 FAQ 写的是读者心里想的，用他们自己的话表达：“我做品牌好多年了。还能学到新东西吗？”回答一上来就直接作答（“能。”“是。”），绝不要说“好问题”。

逐行细节、词汇、英语借词、金额、CTA 以及前后对照表，见：references/voice.md。撰写新内容或重写整个章节前，请先阅读。

首屏要说清楚要做的任务，而不是描述现状

适用于 H1、<title> 和社交卡片。这是代价最高的错误，因为它能通过所有代码检查。

描述现状的文案只讲读者的处境，让他们自己琢磨能得到什么：“你硬盘里存着几百个没用上的样机。”这话没错，也戳中了真实痛点，但没有提出任何要求。描述任务的文案则说出读者想要做的事：“不用打开 PSD，就能找到合适的样机。”

只问一个问题：**读者会在 Google 上输入什么动词？**如果标题里没有这个动词，那它说的就是现状。也要当心写错任务：动笔前，先确认究竟哪个步骤最让人头疼（见 references/cases.md 中的示例）。

如果需要呈现痛点（有时确实需要），就把它放在下一节，用来引出解决机制。首屏只有 5 秒，五秒全用来描述问题，就浪费了表达机会。

品牌词汇表（仅适用于 Visant 自有文案）

客户文案使用客户品牌的词汇表，而不是这份词汇表。

术语	含义	使用位置
Visionário®	终身计划，一次性付款	套餐等级、CTA、FAQ、套餐副标题
Visantista	月度订阅者，也是社群成员的称呼	月度套餐、社群
Visantismo	这场运动及落地页品牌	Logo、导航栏、页脚
Visant	代理机构／公司	正文、作者署名
Fundador	**已弃用。**它曾是 Visionário 的一个宽泛同义词，导致同一个套餐有两个品牌名称	不要使用

如果仓库使用 Visant 的流水线（copy.json）

文案存放在 JSON 中。HTML 和 Markdown 是生成的视图。 编辑 .html 中的文本始终是错误的：下次构建会覆盖它，检查也会因此导致 部署失败。流程：编辑 JSON，运行 npm run copy:lint、npm run copy:build， 然后将 json、html 和 md 一并提交（门禁中的 copy:check 会检查是否存在差异）。 SEO（meta.title、meta.description、meta.og_*）也存放在 JSON 中，通过 data-copy-attr="content" 注入。

完整机制（添加新键、新页面、data-copy-attr、将 \n 转换为 <br>、孤立 键错误、在新仓库中设置）：references/pipeline.md。

没有 copy.json 时（任何其他仓库）

在这类流水线之外，组件是唯一事实来源（SSoT）。不要在文案任务中途设置 copy.json：用户要的是文案，不是新的架构。

风险的表现形式有所不同。没有构建来同步视图，因此同一句话会在三四处重复， 只改 <h1> 会让其余内容仍在兜售上个月的承诺。修改标题后，要查找所有重复内容 （社交卡片和 <title> 最容易被漏掉）：

rg -n "trecho da frase antiga" src   # and repeat with 4 or 5 words from the middle

这些内容可能出现的位置，按最容易被忘记的顺序排列：

位置	常见文件
<h1> 和引导文案	components/**/hero.tsx
链接卡片	app/**/opengraph-image.tsx，以及其中导出的 alt
<title> 和描述	app/**/page.tsx（以及同一对象的 twitter/openGraph）
截图的 alt 和 figcaption	同一个 hero
重复表达论点的板块	同一文件夹中的 components/**/

最后，在 TS 仓库中运行 npx tsc --noEmit：JSX 中丢失逗号会导致构建失败。 <title> 是唯一需要改变语气的地方：它面向搜索，因此要包含人们搜索的名词 （“mockups”）；而 <h1> 则使用动词。

“审阅/撰写文案”工作顺序

1. 修改任何键之前，先通读页面的整个 JSON（或整个组件）。 包括注释：注释说明了当前文案的缘由；如果文案与其中记录的决策相矛盾，就得返工。
2. 运行 copy-lint，查看习惯用语的清单。
3. 只修正习惯用语，并按用户要求的方向重写。其他内容都整理成表格中的提议。
4. 对照事实来源核对每个数字（服务端价格、客户端数量、成员数量）。此技能不会保存这些值，这是刻意为之：它们会过时。如有疑问，先在发布前询问。
5. 查找旧句子的重复内容（使用 rg，或将相关文件一并传给代码检查器，查看其重复内容警告），并更新社交卡片、<title>、描述和 alt。
6. 如果修改了代码注释，也要更新注释所解释的内容：为旧文案辩护的注释会误导下一位开发者。
7. 再次运行 copy-lint。使用 Visant 的流水线时，还要运行 copy:build 和 copy:check。在 React/TS 仓库中，运行 tsc --noEmit。
8. 报告修改行的修改前后内容。用户通过阅读文案来审批文本，而不是通过阅读文案摘要来审批。