# skill 建设与维护工作流(ops-workflow)

> 本仓库自身的维护纪律,方法论源:Loong Workflow
> (provider-neutral corpus + drift guards),经实战校准。适用于本仓库以及你按本模式自建的一切 skill。

## 铁律:没有失败基线,就没有行为塑造型 skill

写 skill 就是给流程文档做 TDD:

1. **RED 基线**——先看真实失败。最好的人肉素材是你自己踩过的事故:逐字记录当时怎么错的、用了什么借口、什么压力触发的。禁止对着想象中的失败写规则。
2. **GREEN 最小化**——只针对观察到的问题写内容。
3. **REFACTOR**——实测发现新绕过方式,补条目,循环到堵住。

## 分类决定投入

| 类型 | 例 | 基线要求 |
|---|---|---|
| 行为塑造型(压力下必须守住闸门) | "发送前必须核验窗口标题" | 必须有失败基线 |
| 技术/方法型 | 截图→识别→动作→验证 闭环 | 场景验证即可 |
| 参考/机械型 | 命令速查、依赖清单 | 保真检查+守卫 |
| 实战移植 | 本仓库的踩坑实录 | 对照事故记录保真 |

## 形式匹配失败类型(选错形式会适得其反)

| 基线失败 | 正确形式 | 错误形式 |
|---|---|---|
| 压力下违反规则 | 禁令+借口对照表+红旗清单 | 软 guidance("建议/尽量") |
| 输出形状不对 | 配方:说清输出是什么、按什么顺序 | 禁令清单 |
| 漏了必做步骤 | 模板里的必填槽位 | 模板旁边的散文提醒 |
| 行为依赖条件 | 绑定可观察谓词的条件式 | 无条件规则+豁免条款 |

**关键推论:能固化进代码的闸门,绝不放在散文里。** 代码不会在截止日期压力下和你讨价还价——本仓库的"发送前核验标题"最终是 `agent.py` 里的 `header_matches()` 函数,不是 SKILL.md 里的一行字。

## 守卫(guards):漂移靠工具不靠记忆

skill 建好后会存在于多处(源目录/安装目录/部署实例/分发包),漂移是常态。`scripts/check-skill.sh` 检查:

结构完整、引用文件存在、凭证泄露(HARD)、私密信息(SOFT)、未证实断言、编码健康、脚本语法、CHANGELOG、分发包一致性。

```bash
bash scripts/check-skill.sh <skill目录> [--bundle <tar.gz>]
```

已踩过的守卫设计坑:守卫自身的检测模式会被当成命中(模式样本伪装命中)——扫描前剥离行内代码段、排除 guards/ 目录;规则文档里合法引用的违例词,靠"剥离代码段后重测"区分。

## 三方同步纪律

```
源目录(唯一编辑点) → 安装目录 → 分发包(永远重新打包,禁止改包)
部署实例(如服务器 /opt/xxx)的改动必须先回填源目录,再走发布
```

记忆/文档只存指针(源在哪、包在哪、版本号),不复述内容——复述必然过时。

## 证据分级表述

写"实战验证"前先回答:证据是什么?

- ✅ "已验证:File Transfer 心跳链路端到端送达(截图确认)"
- ✅ "未验证:私聊自动回复的实际送达(审计截图缺失,待人工确认)"
- ❌ "已跑通,消息真实送达"(含糊,且当时并未眼见确认)

## 复盘(事故后必做,无指责)

DATA(每条失误附证据)→ ANAL(归因流程/工具/信息缺口,不归因个人)→ ACT(≤5条,每条有文件路径和完成判据)→ LOOP(素材文件真的改了)→ SAFE(不指责任何人,含自己)。

## 本仓库的应用实例

v0.2.0 整合 Linux 服务器 Agent 时,以上流程实际这样走:

1. **基线**:三天实战中的真实事故(私聊消息发错群、空标题核验漏洞、二维码被自愈循环刷新)就是 RED 数据
2. **GREEN**:每条事故固化为 pitfalls 一条 + 可能的话固化为 agent.py 的闸门函数
3. **守卫**:check-skill.sh 在发布前抓出分发模板里的真实联系人名和未证实断言(也抓出守卫自身的假阳性,遂加"剥离代码段"规则)
4. **同步**:服务器 /opt/wechat-agent 的 agent.py 与仓库 scripts/agent.py 做了 diff 一致性确认