第 14 章 实战：排查与第一次安全定制

全书的方法论收进这一章，两个实战场景：把你从「不生效就重启」的循环里解救出来的五步排查法，和一次完整的定制流程。所有命令在声明环境（macOS、WorkBuddy 5.3.13）实测过，全部只读或可逆。

读完本章，你应能独立完成一次完整的「症状 → 定位 → 修复 → 验证」闭环，并对自己的 WorkBuddy 做一次有据可依的定制。

14.1 五步排查法

「不生效」是 WorkBuddy 用户的高频抱怨：改了身份没变化、装的技能没反应、规则不起作用、插件行为怪异。抱怨背后的真实原因分布很散，但几乎全部落进同一条因果链——你的意图要变成行为，必须经过「文件 → 拼装 → 请求」三站，任何一站断掉都表现为「不生效」。五步排查就是沿这条链走一遍。

第一步：查层级——你改的东西在哪个作用域？ 技能有用户级与项目级两层，插件作用域有层概念，规则文件只对所在项目生效。「我在 A 项目里改的，怎么 B 项目不生效」——这不是故障，是层级设计（第 9 章）。命令：

ls ~/.workbuddy/skills/ | grep <名字>
ls <项目>/.workbuddy/skills/ 2>/dev/null | grep <名字>

第二步：查开关——它通电了吗？ 装了不等于启用。插件看 settings.json 的 enabledPlugins，专家看专家中心状态，技能看文件是否在正确目录、frontmatter 是否完整。最常见的烂数据是 SKILL.md 的 frontmatter 格式错误——三个横线没闭合，整个技能就静默失效。

grep '"<插件名>' ~/.workbuddy/settings.json
head -5 <技能>/SKILL.md

第三步：查拼装——它在这次请求的清单里吗？ 通电的内容不一定进请求。专家对话时身份文件让位（WorkBuddy 4.8.1 版本修复，见第 6 章）；记忆内容要匹配层级；技能要等 description 匹配的任务才加载。验证方法就是第 10 章的会话取证：新开一个会话触发一次，然后看会话文件里有没有对应痕迹（专家的 system-reminder、技能的读取事件）。

第四步：查缓存与同步——新内容被旧状态压住了吗？ 云端记忆画像会覆盖本地手改（第 4 章）；市场自动更新可能改掉你修改过的模板文件（第 5 章，另一个理由别改主模板）；客户端对部分配置有加载时机，改完配置重启应用是低成本的对照实验。这一步的判定动作：改完 → 重启 → 重试 → 会话取证对比。

第五步：查版本——机制变了吗？ 产品平均两天一版。排查前先确认版本号，对不上的行为差异去更新日志找条目（官方文档站可查）。本书机制冻结在 5.3.13，你手上的版本更新时，以第 3 章的地图重新对位。

五步走完，「不生效」基本现形。附录 B 是这五步的打印版排查卡。真正的闭环还要加一步验证：修复后重开新会话测试——旧会话的上下文是拼装好的历史，不反映你的修复。

图 14-1：五步排查卡。

14.2 第一次安全定制：完整流程

场景：你想让 WorkBuddy 在你的项目里始终遵守一套交付规范（比如所有产出文档用固定结构、命名规范、存到固定子目录）。这是规则+技能组合的典型需求，走一遍完整流程。

规划（先想后做）：按第 9 章的分工判断——「始终遵守」的部分进规则文件，「怎么做好某类交付」的部分进技能。预估改动面：项目目录新增两三个文件，零系统改动，全程可逆。

动手：

cd <你的项目>
mkdir -p .workbuddy/skills/delivery-style

项目根建规则文件（WORKBUDDY.md），写入硬约束：

# 项目规则

- 所有交付文档存入 deliverables/ 子目录
- 文件命名：日期-主题-版本，如 2026-08-15-周报-v2.md
- 交付前必须列出将修改的文件清单并等待确认

技能文件 .workbuddy/skills/delivery-style/SKILL.md 写方法：

---
name: delivery-style
description: 本项目交付文档的结构规范。当用户要求产出文档、报告、周报、方案时使用。不用于代码文件。
---

# 交付结构

三段式：结论先行（不超过 5 条）→ 支撑细节（数据带来源）→ 待办与风险。
中文撰写，术语首次出现附英文。交付时同时生成一份纯文本摘要。

验证：在 WorkBuddy 里打开这个项目（新建任务选该文件夹），要求「写一份项目周报」。预期行为：先列文件清单待确认（规则生效）、产出落在 deliverables/ 且命名合规（规则生效）、结构三段式（技能生效）。任何一环没中，回五步排查法对应步骤。

收尾：把这次定制的「意图 → 文件 → 验证结果」记入项目的工作区记忆（对话里说一句「记住这个项目的交付规范已配置」），下次会话模型自带上下文。

14.3 排查案例走一遍

用一个综合案例把五步串起来。症状：用户给 WorkBuddy 装了一个「周报助手」技能，说「写周报」却总是不按技能里的模板出稿。

第一步查层级：ls ~/.workbuddy/skills/ | grep weekly 有结果，用户级存在；ls /.workbuddy/skills/ 空——技能装对了层。第二步查开关：技能不走 enabledPlugins（那是插件的开关），看的是文件本身——head -5 检查 frontmatter，发现三横线闭合正常，name 与目录名一致。第三步查拼装：新开会话说「写周报」，然后到会话文件里 grep 技能名——没有任何读取事件。技能根本没被唤醒。回过头细看 SKILL.md 的 description，写的是「当用户需要生成周报文档时使用」，而用户的措辞习惯是「整理一下这周的工作」——description 的触发词与用户真实措辞不匹配，模型判断不适用。修复：description 改成「当用户要求写周报、整理本周工作、总结一周进展时使用」，再测，触发。第四五步（缓存与版本）此案例用不上——不是所有排查都要走满五步，链条在哪一环断了，后面就只是确认。

这个案例的普适教训：技能的 description 是写给模型看的路由表，不是写给人看的简介。措辞覆盖度决定触发率，这是技能开发里性价比最高的一处投入。

14.4 高阶组合：三个实用模式

模式一：干净环境跑敏感任务。 敏感数据任务前，关掉非必要插件、断开外部连接（第 12 章清单），用默认权限模式。任务完成后恢复。把「环境洁净度」当作与「模型选择」同级的任务参数。

模式二：专家+技能的组合拳。 需要稳定复用的工作流：装或写一个匹配的专家（人格与强制规则），配一个技能（方法步骤），用专家对话跑流程。比单纯堆技能可靠——专家的注入优先级高（第 6、7 章），行为一致性好。

模式三：团队规范的三层分发。 组织级：规则文件进代码仓库（人人同规范）、技能进项目目录（随仓库分发）、身份偏好各自维护（尊重个体）。三层正好对应第 9 章的层级设计，版本管理与知识分发的成熟方案直接复用。

14.5 维护节奏

定制不是一次性动作。建议的维护节奏：每月一次十分钟自查（第 12 章七条清单的轻量版）；每次产品大版本更新后重跑一遍你的核心定制验证（用 14.2 的流程）；每季度整理一次技能库——删掉 description 再也想不起用途的技能，技能库和衣柜一样，常穿的就那几件。

全书的方法到本章收束：机制给你地图（前十三章），排查法和定制流程给你驾驶技术（本章）。最后一章是给要讲课的人的——这套材料怎么变成课堂。

14.6 本章边界

五步法与定制流程的命令在声明环境（macOS、5.3.13）实测走查（走查记录见附录 D 的取证方法）；grep 里的双引号格式适配本机会话文件的实际写法，版本更新可能改变字段格式；技能优先级与规则文件行为随版本演进，以你机器上的受控实验结果为准；14.2 的交付规范示例是教学样例，按你的团队标准替换。