★ FEATURED ARTICLE 后端前端CMS【免费下载链接】talebook一个简单好用的个人书库项目地址https://gitcode.com/gh_mirrors/ta/talebook点击查看免费下载写作审查writing review是 talebook 前端体验工程中用于评估界面文案质量的标准流程而其最终报告必须遵守.agents/skills/better-writing/review-output.md定义的统一输出格式。本文将逐条拆解该规范中的 Findings 表格四项必填列、HIGH/MEDIUM/LOW 严重级别、Verification 验证步骤与 Block / Needs changes / Approve 三级裁决逻辑并结合仓库内的技能编排、锁定与测试实现说明这一格式如何在真实项目中落地。读完本文你将能独立产出符合规范、可被团队直接裁决的写作审查报告。一、为什么写作审查需要一份固定的输出格式1.1 review-output.md 在技能体系中的位置在 talebook 的.agents/skills/目录下better-writing技能负责UX writing 与界面文案从按钮与链接文案、表单报错、占位符、设置项标签到引导流程、通知与空状态见 SKILL.md 的描述区。而 review-output.md 是该技能唯一的独立写作审查standalone writing review输出规范。规范开头就划清了职责边界当better-interface编排整个审查流程时格式、严重级别、合并规则、条数上限与最终裁决均由它掌控而better-writing只负责提供领域证据与发现domain evidence and findings。也就是说review-output.md 是给被审查方看的交付物模板而不是审查逻辑本身——这保证了任何一次审查的结论都能被机器化地合并、去重与裁决。1.2 仓库中的落地证据这份规范不是孤立的文档它在当前仓库中被真实引用与校验skills-lock.json 将better-writing锁定为jakubkrehel/skills源并记录其计算哈希4f860b739a2f4d8877225272297b1fbfb1848954fc3903058d1386d535e0b460保证技能内容可追溯、不可漂移tests/test_project_instructions.py 中的test_interface_review_skill_and_domain_dependencies_are_installed断言better-writing等技能必须已安装且每个技能目录下的SKILL.md都包含name: better-writing头interface-review/SKILL.md 明确将审查移交给 better-interface由其路由到各领域技能、应用严重级别、执行合并与裁决——而领域技能如 better-writing的输出格式正是 review-output.md。从源码结构可以推断talebook 将界面质量审查拆成了三层——interface-review负责界定变更范围与问题状态better-*领域技能负责给出文案/布局/无障碍等专业判断better-interface负责汇总裁决。review-output.md 就是这一流水线在写作这一领域侧的交付契约。二、Findings 表四项必填列的语义与写法独立审查报告分为两大部分第一部分是 Findings发现第二部分是 Verification and Verdict验证与裁决。所有已确认的发现必须按原则分组并使用包含Severity、Location、Before、After、Why五列的 Markdown 表格呈现。2.1 Severity严重级别三档级别定义原文继承典型场景HIGH误导用户、掩盖后果或阻碍用户恢复删除确认按钮的OK、报错文案不给出恢复路径、文案让用户误解操作结果MEDIUM使用户更难理解任务动词缺失、术语前后不一致、文案与上下文冲突LOW孤立的语气或一致性打磨个别大小写不一致、语气偏轻浮但不影响理解严重级别决定裁决走向见第四节因此定级时要自问这条文案会不会让用户做错事HIGH、多想一步MEDIUM还是只是观感瑕疵LOW。规范特别强调Never use separate Before: / After: lines——严禁把 Before 和 After 拆成独立的行必须作为同一行的两列呈现否则表格的对照语义就丢失了。2.2 Location精确定位到行有源文件时一律写成path/to/file:line格式如src/PasswordField.tsx:36无源文件如纯界面稿时改为引用确切的屏幕与组件仓库的 interface-review/scope-resolution.md 进一步补充引用必须针对 head ref 给出path/to/file:line并在作用域块中声明该 ref 及其 SHA因为来自被 fetch ref 的行号不一定与工作区一致——这让每条 Location 都是可解析、可复核的。2.3 Before / After引用原文与完整替换两列分别承载当前文案与完整替换文案。Before 必须逐字引用现状After 必须是完整的替换内容而不是缩写或方向性描述这样评审者无需回到源码就能直接评估改动。结合 better-writing/SKILL.md 的原则 10错误要说明如何修复且紧邻出错的字段典型的 After 写法是把密码太短改写为请设置至少 8 个字符的密码把Oops! Something went wrong.改写为无法保存请检查网络连接后重试。2.4 Why点名被违反的原则Why 列必须写明违反的原则以及理解或信任成本。例如违反 原则 5动词优先按钮 的OK按钮其信任成本是破坏性操作未重复后果用户无法不读正文就回答对话框违反 原则 10错误要说明如何修复 的通用报错其理解成本是既无法定位失败原因也没有恢复路径。2.5 合并规则与分组同一个系统性问题在多个位置反复出现时合并为一行并在 Location 或描述中列出所有受影响位置没有发现的原则不出现Omit principles with no findings——报告只谈证据不做原则巡礼所有发现按原则分组组内再按严重级别排序便于裁决者快速聚焦 HIGH 项。三、示例解析错误信息与按钮文案两张表规范自带两张可直接复用的示例表完整继承如下并补充逐条解读。3.1 错误信息必须给出修复方法SeverityLocationBeforeAfterWhyMEDIUMsrc/PasswordField.tsx:36Invalid passwordChoose a password with at least 8 charactersThe error must say how to fix the problemHIGHsrc/Editor.tsx:81We couldnt process your request toastInline Unable to save. Check your connection and try again.The current message neither locates the failure nor offers recovery解读第一条是 MEDIUMInvalid password没有撒谎但用户不知道下一步该做什么属于使任务更难理解第二条是 HIGHtoast 既不指出失败环节也不提供恢复动作用户无法从错误中走出来符合 HIGH 中obscures a consequence, or prevents recovery的定义注意 After 用 Unable to save 而非 We couldnt process...——这正是 原则 3直接称呼读者、避免我们推诿 的体现用客观状态陈述代替第一人称的模糊归因。3.2 破坏性按钮必须重复后果SeverityLocationBeforeAfterWhyHIGHsrc/DeleteDialog.tsx:29OK on the delete confirmationDelete projectA consequential action must repeat the consequenceMEDIUMsrc/Signup.tsx:54Lets go!Create accountThe label must name the action解读删除确认对话框里的OK是 HIGH用户可以不读正文就点确认属于consequential action未重复后果Lets go!是 MEDIUM它不指向任何具体动作读者需要从上下文猜按钮做什么这两个 After 都遵守 原则 5 的动词优先以动词开头、点名具体动作Delete / Create并让确认按钮重复后果从而无需读正文即可作答。四、Verification and Verdict收尾三步Findings 之后必须依次完成以下内容4.1 Verification列出实际执行的检查逐条列出实际执行过的检查及其观察结果适用时覆盖完整流程complete flow、变量插值variable interpolation、复数化pluralization、窄宽换行narrow-width wrapping。例如完整流程登录 → 输入短密码 → 确认报错出现在字段下方而非页面顶部变量插值You have {n} new messages在 n1 时渲染为单数形式复数化确认文案使用完整模板串而非You have n messages拼接对应 原则 4窄宽换行在最小支持的视口宽度下确认 After 文案不折行破坏语义。如果某项检查没有执行必须如实说明仍有待验证state what still needs verification——规范不允许用已全面验证掩盖未覆盖项。4.2 Verdict三级裁决规则裁决触发条件Block仍存在任意一个未解决的HIGH发现Needs changes仅剩MEDIUM或LOW发现Approve不存在任何可行动的actionable发现裁决完全由发现驱动有一个 HIGH 就阻塞全清才放行。这与仓库中 tests/test_project_instructions.py 断言的流程纪律一致——interface-review场景下HIGH或MEDIUM问题未解决时不得将方案转为 ACTIVE修复后必须重新执行审查。4.3 无发现时的路径当没有任何发现时省略所有表格直接声明 No actionable writing findings照常报告验证情况最后以Approve收尾。这一分支保证了没有问题同样是一个可审计、可留痕的结论而不是一份空报告。4.4 与 interface-review 的衔接在变更级审查中问题状态的分类Introduced/Regression/Pre-existing由 interface-review/SKILL.md 负责状态由 diff 触及的代码决定而非所在文件确认回归可先用git blame -L line,line $BASE -- path/to/file对照基线。随后所有发现带着状态上交给better-interface由其套用条数上限与裁决规则——review-output.md 本身不重造这些规则interface-review/SKILL.mdDo not invent a severity scale, a cap, or a verdict。同时 interface-review/SKILL.md 要求 Verification 中列出每条写入.git的命令fetch、deepen、set-head、worktree使仓库只读声明可审计。五、实战检查清单与常见误区映射better-writing/SKILL.md 的 Common Mistakes 表 是写作侧最易触发的错误清单它们进入报告时通常的定级与列填写方式如下常见错误典型 SeverityWhy 引用的原则局部改写无视产品既有术语/语气MEDIUM原则 1先侦察既有语态教学性文案写 the userLOW/MEDIUM原则 3直接称呼 youOK/Yes确认破坏性对话框HIGH原则 5动词优先步骤 2 用 Continue、步骤 3 用 NextMEDIUM原则 6统一流程词汇Click here 或光秃秃的 Learn moreMEDIUM原则 7链接描述目的地Save Changes 与 Discard changes 混排大小写LOW原则 8单一大小写策略开关写成 Dont send read receiptsMEDIUM原则 9描述开启态You have n messages拼接MEDIUM/HIGH原则 4完整模板串复数化空状态只有 No results.MEDIUM原则 11空状态指明方向与下一步占位符兼任字段标签MEDIUM原则 12占位符只是格式示例一个最小完整流水线示例从发现到裁决审查登录页发现删除对话框按钮文案为OK→ 记为一条 HIGHLocation 填src/DeleteDialog.tsx:29Before 填OK on the delete confirmationAfter 填Delete projectWhy 填 A consequential action must repeat the consequenceVerification 记录已在对话框弹层、键盘导航、窄屏三种状态下确认替换文案的显示与换行因存在未解决的 HIGH → 裁决Block修复后复检 → 无剩余发现 → 声明 No actionable writing findings →Approve。六、在 talebook 仓库中的进一步探索如果你想深入理解这套格式的工程化保障推荐按以下路径阅读当前仓库review-output.md本文主体规范原文better-writing/SKILL.md12 条写作核心原则与常见错误表是 Why 列的原则来源interface-review/SKILL.md变更范围解析与问题状态分类了解 HIGH/MEDIUM 发现如何被上交裁决interface-review/scope-resolution.mdLocation 引用的 ref/SHA 规范skills-lock.json 与 tests/test_project_instructions.py技能锁定哈希与安装断言验证这套技能体系的完整性同目录下的姊妹技能输出规范如 better-typography/review-output.md、better-ui/review-output.md、better-accessibility/review-output.md可对照理解每个领域技能共享同一套报告骨架的设计。综上所述review-output.md 用一份五列表格加上三级裁决规则把界面文案审查从主观评价变成了可合并、可追溯、可自动裁决的工程流程HIGH 阻塞、MEDIUM/LOW 要求修改、全清即批准而每一项结论都必须附上精确定位、完整替换文案与被违反的原则。这正是 talebook 将设计审查流程化的核心契约之一也是任何希望建立文案质量门禁的团队可以直接复用的范式。赞分享后端前端CMS【免费下载链接】talebook一个简单好用的个人书库项目地址https://gitcode.com/gh_mirrors/ta/talebook点击查看免费下载相关推荐talebook UI 润色审查输出规范Findings 表格、验证清单与 Block/Approve 裁决流程talebook UI 润色审查输出规范Findings 表格、验证清单与 Block/Approve 裁决流程 导读 本篇围绕 talebook 仓库中 .后端前端CMSTalebook 前端色彩审查报告规范基于 OKLCH 的 Findings 表、验证清单与裁决机制Talebook 前端色彩审查报告规范基于 OKLCH 的 Findings 表、验证清单与裁决机制 本文档是 talebook 仓库内嵌的前端设计审查技能后端前端CMS无障碍评审输出规范基于 talebook 前端实践的可访问性审查报告Findings / Verification / Verdict写作指南无障碍评审输出规范基于 talebook 前端实践的可访问性审查报告Findings / Verification / Verdict写作指南 本篇指南围后端前端CMS上一篇cAdvisor API Clients 实战指南使用官方 Go 客户端对接容器监控 REST API下一篇终极极简主义深度学习框架tinygrad如何用1000行代码实现PyTorch核心功能创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
