Prechádzať zdrojové kódy

add 使用说明 README.md

gongluzhen 8 hodín pred
rodič
commit
7ac07a30c7
1 zmenil súbory, kde vykonal 242 pridanie a 0 odobranie
  1. 242 0
      README.md

+ 242 - 0
README.md

@@ -0,0 +1,242 @@
+# 交付 AI 技能包 · 使用说明
+
+> 仓库:`https://code.sapit.com.cn/sapit-skills/skills.git`
+> 用途:把《标准交付流程 V2.0》装进 WorkBuddy,让 AI 按咱们的规范干活
+
+---
+
+## 一、这是什么
+
+四个岗位各一个技能包,装进 WorkBuddy 后,AI 在对应场景会自动按规范办事——该拒绝的拒绝(材料不全不硬写),该停的停(先出骨架等人确认),该标来源的标来源。
+
+| 技能包 | 谁用 | 干什么 |
+|---|---|---|
+| `sapit-req-example` | 需求分析师 | 写需求说明书、出功能清单、估人天 |
+| `sapit-dev-example` | 开发工程师 | 表结构设计、编码、代码审查 |
+| `sapit-qa-example` | 测试工程师 | 写测试用例、缺陷根因分析 |
+| `sapit-ops-example` | 实施工程师 | 部署方案、部署脚本、环境排查 |
+
+**跟以前模板的区别**:以前是 Word/Excel 模板,你不填它不会说话;现在是 AI 的作业手册,你不按规范来它会提醒你。
+
+---
+
+## 二、装(三分钟)
+
+### 前置
+
+- 已安装 WorkBuddy 桌面版
+- 能访问内网 `code.sapit.com.cn`
+
+### 第一步:克隆仓库到任意位置
+
+**Git Bash / macOS / Linux**
+
+```bash
+git clone https://code.sapit.com.cn/sapit-skills/skills.git ~/sapit-skills
+```
+
+**PowerShell**
+
+```powershell
+git clone https://code.sapit.com.cn/sapit-skills/skills.git $env:USERPROFILE\sapit-skills
+```
+
+> 注意:**不要直接 clone 到 `~/.workbuddy/skills/` 里**,原因见第五节。
+
+### 第二步:复制到 WorkBuddy 技能目录
+
+**Git Bash**
+
+```bash
+mkdir -p ~/.workbuddy/skills
+cp -r ~/sapit-skills/*/sapit-*-example ~/.workbuddy/skills/
+```
+
+**PowerShell**
+
+```powershell
+New-Item -ItemType Directory -Force "$env:USERPROFILE\.workbuddy\skills" | Out-Null
+Get-ChildItem "$env:USERPROFILE\sapit-skills\*\sapit-*-example" -Directory |
+  Copy-Item -Destination "$env:USERPROFILE\.workbuddy\skills" -Recurse -Force
+```
+
+### 第三步:重启 WorkBuddy
+
+关掉重开。技能是启动时加载的,不重启不生效。
+
+### 第四步:验证
+
+随便开个对话,问一句:
+
+> 你现在能用哪些交付技能?
+
+能说出四个技能名就装好了。
+
+---
+
+## 三、装完长什么样
+
+```
+C:\Users\你的用户名\.workbuddy\skills\
+├── sapit-req-example\
+│   ├── SKILL.md
+│   └── references\
+│       ├── 模板-需求说明书.md
+│       ├── 模板-功能清单.md
+│       ├── 模板-成本预估.md
+│       ├── 分段提示词.md
+│       └── 复核清单.md
+├── sapit-dev-example\
+├── sapit-qa-example\
+└── sapit-ops-example\
+```
+
+**必须是这个层级**:`skills/` 下面直接就是技能目录,技能目录里直接就是 `SKILL.md`。多一层或少一层都加载不到。
+
+---
+
+## 四、怎么用
+
+### 不用记命令,说人话就行
+
+技能靠描述匹配自动触发,你正常提需求即可:
+
+| 你说 | 触发 |
+|---|---|
+| "帮我写需求说明书,材料在附件里" | `sapit-req` |
+| "按 F-003 设计请假模块的表结构" | `sapit-dev` |
+| "根据 F-003 写测试用例" | `sapit-qa` |
+| "出一份 v1.2.0 的部署方案" | `sapit-ops` |
+
+### 它会怎么反应
+
+**正常情况**,AI 不会直接开写,而是先做三件事:
+
+1. **检查材料够不够**。缺客户原话、缺技术栈版本、缺验收标准,它会停下来告诉你缺什么,而不是猜着写。
+2. **先出骨架**。需求先出功能清单、开发先出 ER 图、测试先出覆盖矩阵——等你确认再往下。
+3. **交付前自证**。不说"做完了",而是告诉你验证了什么、什么没验证。
+
+**如果它没这么做**,直接说"按规范来",或者点名:"用 sapit-req 写"。
+
+### 一个实际例子
+
+> 你:按 F-003 设计请假模块的表结构,技术栈 Spring Boot 3.2 + MySQL 8.0
+
+它会先输出:ER 图 + 建库 SQL + 与现有表的冲突点,然后问你要不要继续写代码。
+
+而不是上来就给你一堆 Java 类。
+
+---
+
+## 五、为什么不能直接 clone 进 skills 目录
+
+仓库按岗位分了两层目录(`requirements/` `development/` `test/` `implementation/`),方便以后同一岗位放多个技能。
+
+但 WorkBuddy 只认一层:`skills/<技能名>/SKILL.md`。
+
+如果直接 `git clone` 到 `~/.workbuddy/skills/`,会变成:
+
+```
+~/.workbuddy/skills/skills/requirements/sapit-req-example/SKILL.md
+```
+
+四层,AI 找不到。
+
+所以要 clone 到别处,再把技能目录**平铺复制**进去。
+
+---
+
+## 六、更新
+
+技能包会持续改(补模板、调阈值、加场景)。
+
+```bash
+cd ~/sapit-skills
+git pull
+cp -r */sapit-*-example ~/.workbuddy/skills/
+```
+
+复制时选"覆盖"即可。然后重启 WorkBuddy。
+
+> 如果提示文件被占用,先关掉 WorkBuddy 再复制。
+
+---
+
+## 七、改与提
+
+### 改了发现更好用,欢迎提交
+
+```bash
+cd ~/sapit-skills
+git checkout -b fix/需求模板补充导出按钮
+# 改文件
+git add .
+git commit -m "fix: 需求模板补充导出按钮的跨业务影响说明"
+git push origin fix/需求模板补充导出按钮
+```
+
+然后在 GitLab 上提合并请求。
+
+### 改哪里
+
+| 想改的东西 | 改哪个文件 |
+|---|---|
+| AI 的判断流程、拒绝条件 | `<技能>/SKILL.md` |
+| 文档模板、格式 | `<技能>/references/模板-xxx.md` |
+| 检查项、红线 | `<技能>/references/复核清单.md` |
+| 提示词 | `<技能>/references/分段提示词.md` 或 `模板与提示词.md` |
+
+**注意**:改完 `SKILL.md` 后,如果里面提到 `references/` 的文件名,路径要对得上,否则 AI 读不到。
+
+### 提交前自查
+
+- [ ] 改动是通用的,不是只适用于某个具体客户
+- [ ] 没有写死公司名、客户名、项目名
+- [ ] 没有把内部地址、账号、密码写进文件
+- [ ] 改完后自己装上试过一次
+
+---
+
+## 八、常见问题
+
+**装了没反应**
+
+1. 检查路径:`~/.workbuddy/skills/sapit-req-example/SKILL.md` 这个文件存不存在
+2. 检查文件名:必须是 `SKILL.md`,大小写也要对
+3. 有没有重启 WorkBuddy
+4. 对话里直接说"用 sapit-req",强制点名
+
+**提示找不到 references 里的文件**
+
+复制时漏了 `references` 目录。重新复制:
+
+```bash
+rm -rf ~/.workbuddy/skills/sapit-req-example
+cp -r ~/sapit-skills/requirements/sapit-req-example ~/.workbuddy/skills/
+```
+
+**只想装一个岗位的**
+
+```bash
+cp -r ~/sapit-skills/test/sapit-qa-example ~/.workbuddy/skills/
+```
+
+**装了会不会让 AI 变啰嗦**
+
+不会。技能只在匹配场景加载,写代码时不会突然跟你讲需求模板。
+
+**团队里每个人都要装吗**
+
+各自装各自的。技能是本地文件,不共享状态。
+
+---
+
+## 九、两个提醒
+
+**1. 这是示例版(-example)。** 里面的阈值(需求推断占比 ≤30%、用例覆盖率 ≥80%)是按经验拍的,还没经过一线数据校准。用的时候如果觉得卡得太死或太松,直接改,改完提交上来。
+
+**2. 技能管不了的事。** 它能让 AI 按规范产出文档,但管不了"客户口头答应下周给材料结果拖了一个月"这种事。流程是底线,项目还是人做的。
+
+---
+
+有问题在群里问,或者直接提 issue。