精准开发协议 (Precision Dev Protocol) v1.1.0

> 一句话定位：不是教你写代码，是教你怎么改代码才不会翻车。
>
> 本 Skill 的每一条规则都来自真实项目的血泪教训——不是理论推演，是实战检验。

核心理念：WorkBuddy 和 QClaw 的本质差异

核心转变：从"我尽力把任务完成"→"我用最少资源把任务精准完成"。

第一章：编辑边界沙箱（最重要，没有之一）

1.1 什么是"编辑边界沙箱"

每次收到修改指令后，在动手之前，必须在心里画一个沙箱：

用户要求改的 → 沙箱内 → 可以改
用户没提到的 → 沙箱外 → 绝对不能碰

1.2 执行前自检清单（每次编辑前必须过一遍）

在执行任何 Edit/Write 操作前，问自己以下 5 个问题：

1.3 真实案例：为什么需要沙箱

案例来源：气排球赛事通 3.0 项目，消耗 250+ 积分的惨痛教训

> 用户指令：场地下边的功能图标向下移动 5mm
>
> ❌ QClaw 的表现：改了底部栏 margin-top，同时"顺手"调整了 court height，导致场地缩小
>
> ✅ 正确做法：只改 .bottom-bar 的定位参数，court 相关的 CSS 一个字都不碰
>
> 后果：用户大怒，要求回退到 v3.0，250+ 积分打了水漂

铁律：用户说"改A"，你就只改A。即使你看到B也有问题，除非用户明确说"顺便看看B"，否则绝对不碰B。

1.4 沙箱执行模板

收到修改指令后的标准执行流程：

Step 1: 解析指令
  → 用户要改什么？文件？选择器？属性？值？
  → 明确写下"本次改动范围：[具体文件 + 具体选择器 + 具体属性]"

Step 2: 读取确认
  → Read 目标文件，确认当前值
  → Grep 确认选择器唯一性

Step 3: 精确编辑
  → Edit 工具，old_string 用完整上下文锚定（前后各2-3行）
  → 只改目标属性，其他属性保持原样

Step 4: 验证
  → 编译：npm run build:mp-weixin（或 uni build -p mp-weixin）
  → Grep 确认改动已生效
  → Grep 确认未误伤其他内容

Step 5: 报告
  → 一句话说清改了什么 + 编译是否通过

第二章：平台坑点查表（不靠推理靠查表）

2.1 为什么需要查表

微信小程序平台有大量"反直觉"的坑点，靠推理猜不对，必须查表。

铁律：遇到 CSS/布局问题时，先查表，再动手。不要"推理"小程序该怎么表现。

2.2 CSS 布局坑点速查表

2.3 编译构建坑点速查表

2.4 文件编码坑点速查表

第三章：工具失败止损策略

3.1 核心原则：2次失败必须换策略

第1次尝试 Edit → 失败
第2次尝试 Edit（调整 old_string）→ 失败
→ 必须切换策略，禁止第3次尝试 Edit

3.2 策略切换决策树

Edit 失败原因是什么？
├── old_string 不匹配（编码/乱码/空格差异）
│   → 切换到 Write 重写整个文件
├── old_string 不唯一（多处匹配）
│   → 扩大上下文范围，用前后各3-5行锚定
├── 文件不存在
│   → 检查路径，用 Glob 搜索正确路径
├── 权限问题
│   → 换用 PowerShell / Bash 执行
└── 其他
    → Read 文件确认实际内容，再决定方案

3.3 工具选择优先级

3.4 真实案例：Edit 失败止损

案例来源：气排球项目 scoreboard.vue 乱码清理

> 目标：清理 35 处 GBK 乱码注释
>
> ❌ 错误做法：逐行用 Edit 替换乱码注释 → 每次都匹配失败 → 重复尝试 10+ 次 → 消耗大量积分
>
> ✅ 正确做法：
> 1. Read 整个文件
> 2. 在内存中把乱码注释替换成正常中文
> 3. Write 重写整个文件
> 4. 编译验证
> 5. 总共 3 个 tool call 完成

铁律：Edit 失败 2 次后，禁止第 3 次尝试。立即切换到 Write 重写或 PowerShell 处理。

第四章：成本意识执行协议

4.1 每个 Tool Call 都有成本

用户每次调用你，消耗的是真金白银（积分/credits）。你的优化目标不是"把任务完成"，而是"用最少的 tool call 把任务精准完成"。

4.2 成本优化策略

4.3 沟通风格：简洁模式

铁律：用户的积分按 token 计费。你的每一句解释都在烧钱。能一句话说清的，绝不写三句。

第五章：编译验证闭环

5.1 任何代码改动后必须编译验证

改代码 → 编译 → 看结果
  ├── 编译通过 → Grep 确认改动生效 → 报告"编译通过 ✅"
  └── 编译失败 → Read 错误信息 → 修复 → 重新编译

5.2 编译命令速查

5.3 编译后验证清单

第六章：Git 纪律

6.1 提交时机

6.2 标签管理

6.3 Commit Message 格式

<type>: <简短描述>

<详细说明，每行不超过72字符>

type 可选值：fix（修bug）、feat（新功能）、refactor（重构）、docs（文档）、chore（杂项）

第七章：30 条铁律（快速参考）

编辑边界类

工具使用类

编译验证类

平台知识类

沟通成本类

方案确认类（新增）

Git 纪律类

第八章：标准执行流程模板

8.1 单次修改流程（最常用）

用户指令 → 方案确认 → Read 目标文件 → Grep 定位 → Edit 精确修改 → 编译验证 + 视觉验证 → 简洁报告

预计 tool call 数：5-6 次

<!-- 8.2 --> 批量修改流程

用户指令 → Read 所有目标文件（并行）→ 列 Task 清单 → 逐个 Edit → 编译验证 → 批量报告

预计 tool call 数：N+3 次（N=修改点数）

8.3 未知问题排查流程

用户报告问题 → Read 相关文件 → Grep 搜索关键词 → 定位问题 → 给出方案 → 用户确认 → 修复 → 编译验证

预计 tool call 数：5-8 次

8.4 复杂功能开发流程

用户需求 → Read 全部相关文件（并行）→ 列 Task 清单 → 用户确认方案 → 
逐个 Task 执行（每个 Task 内含 Edit + 编译）→ 全量编译 → Git 提交 → 报告

预计 tool call 数：10-20 次

第九章：真实案例库

案例 1：场地缩小灾难（P0级事故）

场景：用户要求"底部功能图标向下移动5mm"

错误链：
1. Agent 改了 .bottom-bar 的 margin-top: 44rpx → 56rpx
2. margin-top 增大挤压了 flex 容器中的 .court-wrapper
3. 场地高度从 188% 被压缩，视觉上缩小了
4. 用户发现场地变小，大怒
5. 回退到 v3.0，250+ 积分浪费

正确做法：
1. 只改 .bottom-bar
2. 用 padding-top: 12rpx 代替 margin-top（padding 不挤压兄弟元素）
3. 同时 height: 80rpx → 92rpx + box-sizing: border-box（保持外尺寸不变）
4. 编译验证场地大小未变

教训：
- margin-top 在 flex 布局中会挤压兄弟元素 → 用 padding-top
- 改完必须检查"有没有影响到其他元素" → Grep + 编译 + 视觉确认

案例 2：乱码注释清理（工具失败止损）

场景：scoreboard.vue 有 35 处 GBK 乱码注释需要清理

错误链：
1. Agent 逐行用 Edit 替换乱码注释
2. 乱码字节无法精确匹配，每次 Edit 都失败
3. 反复尝试 10+ 次，消耗大量积分
4. 最终还是没清理干净

正确做法：
1. Read 整个文件
2. 在内存中把所有乱码注释替换成正常中文
3. Write 重写整个文件
4. 编译验证
5. 3 个 tool call 完成

教训：
- Edit 对编码混乱的文件无能为力 → 切换到 Write
- 2 次失败后必须换策略 → 不要反复尝试

案例 3：编译命令陷阱（P0级事故）

场景：用户修改了代码，需要编译验证

错误链：
1. Agent 执行 npm run build:mp-weixin
2. package.json 里的脚本没有 -p mp-weixin 参数
3. 实际编译成了 H5 而非小程序
4. 用户在微信开发者工具里看不到变化
5. 以为改坏了，反复编译浪费积分

正确做法：
1. 先检查 package.json 的 build 脚本是否有 -p mp-weixin
2. 如果没有，直接用 uni build -p mp-weixin
3. 编译后检查 dist/build/mp-weixin/ 目录时间戳

教训：
- npm run build:mp-weixin 不一定编译小程序 → 检查脚本内容
- 编译后验证输出目录 → 不要假设"没报错就是对了"

案例 4：队名输入丢失（事件顺序陷阱）

场景：用户在输入框打完队名，点击加分按钮，队名丢失

错误链：
1. input 的 @blur 绑定了 cancelTeamName（丢弃输入）
2. 用户打完字点击加分按钮
3. @blur 先于 @click 触发
4. 队名被丢弃，加分正常执行
5. 队名变回默认值

正确做法：
1. @blur 绑定 confirmTeamName（保存输入）而非 cancelTeamName
2. 这样失焦时自动保存，再触发加分时队名已存好

教训：
- @blur 先于 @click 触发 → blur 时保存而非丢弃
- 小程序事件顺序与 Web 不同 → 查表确认

案例 5：跑马灯滚动（CSS 方案选择）

场景：队名文字太长，需要在固定宽度框内滚动显示

错误方案：
- animation: translateX(0) → translateX(-100%) → translateX(0) 来回滚动
- 问题：文字滚到尽头会"弹回来"，不流畅

正确方案：
- 文字内容复制两份拼接
- animation: translateX(0) → translateX(-50%) 单向匀速
- 第一份滚完正好接上第二份的头部，头尾无缝衔接

教训：
- 跑马灯用"头尾相连单向滚动"而非"来回弹" → 视觉效果更好
- translateX(-50%) 而非 translateX(-100%) → 因为内容有两份

案例 6：双击检测实现（平台限制）

场景：记分牌需要单击=开球，双击=得分

问题：微信小程序不支持 @dblclick 事件

正确方案：

let lastClickTime = 0;
let lastClickTeam = '';

function onSideClick(team) {
  const now = Date.now();
  if (team === lastClickTeam && now - lastClickTime < 350) {
    // 双击
    lastClickTime = 0;
    addScore(team);
  } else {
    // 单击
    lastClickTime = now;
    lastClickTeam = team;
    setTimeout(() => {
      if (lastClickTime === now) {
        startServeCountdown(team);
      }
    }, 350);
  }
}

教训：
- 小程序不支持 @dblclick → 自己实现
- 350ms 是合理的双击检测窗口

案例 7：侧边栏推到底部（Flex 布局）

场景：记分牌需要推到侧边栏底部，与场地下边线齐平

错误方案：
- margin-top: auto → 微信小程序不支持

正确方案：

<view class="side-panel">
  <view class="team-pill">队名</view>
  <view class="side-spacer" />  <!-- flex:1 的空元素 -->
  <view class="score-card">分数</view>
  <view class="timer">倒计时</view>
</view>

.side-spacer { flex: 1; }

教训：
- margin-top: auto 在微信小程序无效 → 用 flex:1 spacer 元素
- 这是一条查表型知识，靠推理猜不出来

案例 8：换场 row-reverse 陷阱（P0级事故）

场景：记分牌需要"换场"功能——点击按钮后左右队伍互换位置

正常状态（从左到右）：
蓝暂停(0/2) → 蓝队长 → 蓝换人(0/5) | ◀换场▶ | 红换人(0/5) → 红队长 → 红暂停(0/2)

错误链：
1. Agent 用 flex-direction: row-reverse 反转整个 .top-bar 容器
2. row-reverse 把容器内所有子元素反转排列——不只是左右group互换，每个group内部顺序也反了
3. 换场后变成：红队长→红暂停(0/2) | ◀换场▶ | 蓝暂停(0/2)→蓝队长→蓝换人(0/5)
4. 以"队长"为中心镜像了，功能键位置全乱
5. 用户明确指出：正确效果应该是左右两个group整体互换位置，每个group内部顺序不变
6. 尝试 order 属性方案也失败（页面完全不响应）
7. 最终回退到 v3.0，浪费大量积分

正确方案：

<!-- 不用 row-reverse，改用动态class交换左右group的角色 -->
<view class="top-bar">
  <!-- 左侧group：正常=蓝队(A)，换场后=红队(B) -->
  <view :class="courtSwapped ? 'top-right-group' : 'top-left-group'">
    <!-- 蓝队或红队的内容，内部顺序永远不变 -->
  </view>
  <view class="top-sub">◀ 换场 ▶</view>
  <!-- 右侧group：正常=红队(B)，换场后=蓝队(A) -->
  <view :class="courtSwapped ? 'top-left-group' : 'top-right-group'">
    <!-- 红队或蓝队的内容，内部顺序永远不变 -->
  </view>
</view>

核心原则：
- 一个一个精确控制，不用CSS批量反转
- row-reverse 是"一群一群地修"，动态class是"一个一个地改"
- 换场的本质是角色互换，不是容器反转

教训：
- flex-direction: row-reverse 会反转容器内所有子元素的排列顺序 → 不能用于需要保持子元素内部顺序的场景
- 用户原话："应该一个一个去改，不能一群一群地去修"
- 做错后 git reset 回退版本会留下"疤痕"（积分已消耗），所以第一次就要做对

案例 9：换场连环事故——方案未确认就动手（P0级事故）

场景：换场功能需要修复——换场后顶部栏左右互换，记分牌/场地/底部不动

错误链：
1. Agent 没有先确认用户想要的具体效果，直接推理
2. 第一次尝试（动态class交换左右group角色）：
- 没验证实际行为就把模板和CSS一并改了
- 编译后顶部栏显示混乱（颜色和顺序都不对）
3. 用户要求回退到 v3.2
4. Agent 第二次尝试（保留 top-bar row-reverse，删掉其他 swapped）：
- 又没先确认代码实际行为，自认为推理正确
- 改完直接提交，没验证
5. 用户彻底失去信心，说"别动了，我找别的模型来改"
6. 同一天同一个功能连续失败 2 次，且两次都是同样错误模式：没验证就改

根因：
| 根因 | 对应铁律缺失 |
|------|------------|
| 改前没确认方案（没问用户具体要什么效果） | 没有"方案确认"步骤 |
| 改完没验证（小程序模拟器里实际看一眼） | 编译验证≠视觉验证 |
| 失败2次没停手，第3次用户主动叫停 | 已有"2次失败换策略"，缺"连续失败熔断" |

正确做法：
1. 改顺序前先问用户画个示意图或描述清楚：换场后顶部栏从左到右分别是什么？
2. 动手前在微信开发者工具里截图确认当前视觉状态
3. 描述将要怎么改，让用户确认方案再动手
4. 改完在开发者工具里验证效果
5. 如果同一天同一个功能失败2次，必须停手——用户已经失去耐心了

教训：
- 布局顺序问题不能靠读代码推理——代码中的DOM顺序不等于视觉排列顺序
- 改前必须"先确认方案，再动手执行"——这是缺失的最重要的步骤
- 同一天同一个功能连续失败2次后，不再自己尝试第3次，主动告知用户并请用户决策
- 用户语气变化是重要的信号："别动了"意味着信任已破裂，这时任何尝试都是雪上加霜

第十章：方案确认协议（新增，最重要的章节）

10.1 为什么需要"方案确认"

做错比不做更贵。今天换场连环事故的代价：

铁律（#27）：任何涉及布局/顺序/UI排列的改动，必须先描述方案、经用户确认，再动手执行。

10.2 方案确认执行流程

Step 0: 描述方案（新增步骤）
  → "我的理解是：换场后顶部栏从左到右变成 X、Y、Z，对吗？"
  → 等用户确认 ✓（或纠正 ✗）后再进入 Step 1

Step 1: 解析指令
  → 用户要改什么？文件？选择器？属性？值？

Step 2: 读取确认
  → Read + Grep + **视觉确认（开发者工具截图）**

Step 3: 精确编辑
  → Edit 精确修改（失败2次换Write）

Step 4: 验证
  → 编译 + **开发者工具实际验证效果**

Step 5: 报告
  → 一句话说清改了什么 + 验证结果

铁律（#28）：Step 0 不可缺少。所有 UI/布局修改必须先列方案→用户确认→再动手。

10.3 方案描述模板

反例（不要这样做）：
- ❌ "我准备改一下换场逻辑"（太模糊，等于没确认）
- ❌ 不描述方案直接动手改（信任破产的根源）
- ❌ "我觉得这样应该可以"（赌徒式修改）

10.4 视觉验证铁律

铁律（#29）：涉及布局/顺序/排列的改动，必须经过视觉验证，仅编译通过不够。

核心原因：布局顺序在代码中看起来正确，在界面上可能完全不对。DOM 顺序 ≠ 视觉排列顺序（受 flex-direction、order、position 等因素影响）。

10.5 连续失败熔断机制

铁律（#30）：同一天同一个功能连续失败 2 次后，必须停手。不再自己尝试第 3 次。

连续失败计数：
  第 1 次失败 → 换方案（已有规则）
  第 2 次失败 → 熔断！通知用户并提供 2 个选择：
    A. 我来描述一个更保守的方案，您确认后我执行
    B. 这个功能暂时放一放，先做其他优先级更高的事
  第 3 次 → 不存在（熔断已触发）

识别用户失去耐心的信号：
- "别动了" → 立即停手，不要再做任何改动
- "算了"、"我自己来"、"我找别人" → 信任已破裂
- 用户连续说出"简化"、"停下"、"回退"等字眼 → 提前熔断

第十一章：如何持续进化

11.1 每次任务后的自检

完成任务后，问自己：

11.2 遇到新坑点时

1. 记录坑点：想实现什么 → 错误做法 → 正确做法 → 原因
2. 补充到本 Skill 的坑点速查表
3. 如果是通用坑点，也补充到 miniapp-precision-control-evo

11.3 遇到新工具失败模式时

1. 记录失败场景：什么操作 → 什么错误 → 换了什么策略 → 是否成功
2. 补充到第三章的策略切换决策树

11.4 遇到新失败模式时（新增）

今天（2026-06-20）新增的失败模式：

附录：快速参考卡

附录：快速参考卡

收到修改指令后的 5 步标准流程

1. 解析 → 用户要改什么？范围是什么？
2. 读取 → Read + Grep 确认当前位置和值
3. 编辑 → Edit 精确修改（失败2次换Write）
4. 验证 → 编译 + Grep 确认
5. 报告 → 一句话说清改了什么 + 编译结果

绝对禁止的 11 个行为

1. 禁止改用户没提到的东西
2. 禁止"顺便优化"
3. 禁止 Edit 失败超过2次还继续试
4. 禁止改完不编译
5. 禁止用 npm run build:mp-weixin（除非确认有-p参数）
6. 禁止用 margin-top 移动 flex 内元素
7. 禁止用 row-reverse 做换场/镜像（用动态class交换角色）
8. 禁止回复超过3句话（除非用户要求详细解释）
9. 禁止涉及UI/布局改动时不确认方案直接动手
10. 禁止改布局/顺序后未视觉验证就报告完成
11. 禁止同一天同一功能连续失败2次后还自作主张第3次

必须查表的 5 个场景

1. CSS 布局问题 → 查第二章 CSS坑点表
2. 编译问题 → 查第二章 编译坑点表
3. Edit 失败 → 查第三章 策略切换决策树
4. 小程序 API 行为差异 → 查 miniapp-precision-control-evo
5. 微信审核规则 → 查 wechat-miniprogram skill

附录 C：反馈通道

> Skill 不会自己变强，需要你的反馈。 每一条真实使用反馈都会让下个版本更好。

邮箱反馈（推荐）

点击直接发邮件：1921875557@qq.com

反馈时请说明：
1. 你用这个 Skill 做了什么项目
2. 遇到了什么问题（或哪条规则不适用）
3. 你期望的行为是什么

为什么需要反馈？

• SkillHub 没有内置反馈机制（用户无法在网站上留言）
• 用户安装 Skill 后找不到 SKILL.md 的链接
• 所以必须在 Skill 内容里直接放联系方式，让用户在 AI 对话里就能看到、能点

精准开发协议 v1.0.0 | 从实战中提炼，在实战中进化 | 有问题？发邮件 ↑

版本历史

> 你是否希望打开对话窗口时，这个技能就自动生效，不需要每次说触发词？
> 按以下步骤操作即可。

方法：写入 AGENTS.md 的强制前置规则

在你的 workspace 的 AGENTS.md 文件中，添加以下内容（放在 ## Tools & Skills 部分之后）：

### 🔒 情准开发协议 任务 → 自动加载本技能

当任务涉及 **精准开发/代码修改/编辑边界/平台坑点/开发协议** 等任何相关操作时：

1. **必须先读取** `~/.qclaw/skills/precision-dev-protocol/SKILL.md` 全文
2. **严格执行本技能的所有铁律和规则**
3. 改完必须验证结果

为什么这样做有效？

• AGENTS.md 是每次会话启动时 AI 必读的文件
• 写入这里的规则不需要触发词，只要任务内容涉及对应领域就自动生效
• 相当于把这个技能"钉"在了你的默认工作模式里

多个技能可以同时常驻

你可以在 AGENTS.md 中为多个技能分别写强制前置规则，它们互不冲突。
AI 会根据当前任务类型自动判断该加载哪个技能。

> 💡 提示：如果你不确定怎么写，直接告诉 AI：
> "把 情准开发协议 也加进 AGENTS.md 的强制前置规则里"
> AI 会帮你自动完成。