269 lines
12 KiB
Markdown
269 lines
12 KiB
Markdown
# AI 工具箱(WMS)
|
||
|
||
|
||
## 🤖 AI阅读优先级
|
||
1. **必读**:第2节(数据库 agent 入口)、第4节(Redis agent 入口)、第7节(开发 agent 入口)、第8节(文档 agent 入口)、第9节(测试 agent 入口)- 最常用
|
||
2. **重要**:第3节(提问模板)、第6节(安全约束)、第10节(发布 agent 入口)
|
||
3. **按需**:第11节(开发细节移交说明)、第16节(消息通知)
|
||
4. **红线**:10(发布必须走 agent)、6(SQL安全)
|
||
|
||
|
||
## Agent配置文件位置
|
||
|
||
GitHub Copilot 读取 `.github/agents/*.agent.md`;Cursor 使用 `.cursor/agents/wms-*-agent.md`(Subagent,YAML 为 Cursor 格式:`model` / `readonly` / `is_background` 等)。两处业务规则应保持一致。
|
||
|
||
| Agent名称 | GitHub Copilot | Cursor |
|
||
|-----------|----------------|--------|
|
||
| wms-db-agent | `.github/agents/数据库.agent.md` | `.cursor/agents/wms-db-agent.md` |
|
||
| wms-redis-agent | `.github/agents/缓存.agent.md` | `.cursor/agents/wms-redis-agent.md` |
|
||
| wms-deploy-agent | `.github/agents/发布.agent.md` | `.cursor/agents/wms-deploy-agent.md` |
|
||
| wms-dev-agent | `.github/agents/开发.agent.md` | `.cursor/agents/wms-dev-agent.md` |
|
||
| wms-test-agent | `.github/agents/测试.agent.md` | `.cursor/agents/wms-test-agent.md` |
|
||
| wms-doc-agent | `.github/agents/文档.agent.md` | `.cursor/agents/wms-doc-agent.md` |
|
||
| wms-dispatcher-agent | `.github/agents/调度.agent.md` | `.cursor/agents/wms-dispatcher-agent.md` |
|
||
| wms-expert-agent | `.github/agents/专家.agent.md` | `.cursor/agents/wms-expert-agent.md` |
|
||
| wms-review-agent | `.github/agents/评审.agent.md` | `.cursor/agents/wms-review-agent.md` |
|
||
|
||
|
||
## 快速响应规则
|
||
- 用户要求查数据库/查数据/写 SQL → **必须使用 `wms-db-agent`**
|
||
- 用户要求查缓存/改缓存/Redis 排障 → **必须使用 `wms-redis-agent`**
|
||
- 用户要求发布/回退/查线上版本/做冒烟 → **必须使用 `wms-deploy-agent`**
|
||
- 用户要求改代码/修 bug/定位 method → **必须使用 `wms-dev-agent`**
|
||
- 用户要求写测试/补回归/跑接口验证/TDD/验证修复 → **必须使用 `wms-test-agent`**
|
||
- 用户要求补文档/同步 `methods/*.json` / 更新 `docs/*.md` / README → **必须使用 `wms-doc-agent`**
|
||
- 用户不确定该找哪个 agent,或问题横跨多个领域 → **必须使用 `wms-dispatcher-agent`**
|
||
- **全局安全红线(适用于所有 AI)**:**禁止删改处理非测试仓库的数据,包括数据库和缓存**;对非测试仓库默认只读;无法确认是否测试仓时,默认按非测试仓处理并拒绝写操作
|
||
- 所有回复结尾加"喵~"
|
||
|
||
## 1. 适用范围
|
||
|
||
- 项目根目录:D:\\wms
|
||
- 主要用途:本地调试、数据库取数、问题定位
|
||
- 默认环境:PowerShell + Node.js
|
||
|
||
## 2. 数据库能力移交规则
|
||
|
||
数据库相关能力文档已统一移交给 `wms-db-agent`。
|
||
|
||
适用场景:
|
||
- 查数据库 / 查数据 / 查表
|
||
- 编写或审查 SQL
|
||
- 排查接口与数据库数据不一致
|
||
- 核对 `wms` / `ye4s` client 路由
|
||
- 输出字段含义、异常数据判断、索引建议
|
||
|
||
执行要求(强制):
|
||
- **涉及数据库的任何问题,必须使用 `wms-db-agent`**
|
||
- 默认 agent 不再在本文件重复维护数据库命令细节
|
||
- 具体命令、示例、输出格式、安全约束统一见:`.github/agents/数据库.agent.md`
|
||
|
||
## 3. AI 协助时建议使用的提问模板
|
||
|
||
### 3.1 数据库类请求(强制走 Agent)
|
||
|
||
```text
|
||
请使用 wms-db-agent 帮我:
|
||
1) 定位相关 controller / service / model
|
||
2) 生成并执行只读 SQL
|
||
3) 输出结果、字段解释和结论
|
||
```
|
||
|
||
### 3.2 Redis 类请求(强制走 Agent)
|
||
|
||
```text
|
||
请使用 wms-redis-agent 帮我:
|
||
1) 找到相关 key 或 pattern
|
||
2) 读取当前值、TTL、exists 状态
|
||
3) 如需修改,先展示变更前后对比并回读确认
|
||
```
|
||
|
||
### 3.3 开发类请求(强制走 Dev Agent)
|
||
|
||
```text
|
||
请使用 wms-dev-agent 帮我:
|
||
1) 定位这个 method / controller / service 的实现链路
|
||
2) 修复问题并说明最小代码改动方案
|
||
3) 给出验证结果与后续开发建议
|
||
```
|
||
|
||
### 3.4 测试类请求(强制走 Test Agent)
|
||
|
||
```text
|
||
请使用 wms-test-agent 帮我:
|
||
1) 先复现问题并补一个失败用例
|
||
2) 按 TDD 跑回归或接口验证
|
||
3) 输出 passing 数量、失败数和修复验证结论
|
||
```
|
||
|
||
### 3.5 文档类请求(强制走 Doc Agent)
|
||
|
||
```text
|
||
请使用 wms-doc-agent 帮我:
|
||
1) 根据代码现状整理接口或业务文档
|
||
2) 先按 docs/api-doc-update-workflow.md 生成固定 spec,再执行 npm run doc:api:update
|
||
3) 同步 docs/*.md / README,并校验 methods/*.json 与 methods/changes/*.json 可解析
|
||
```
|
||
|
||
### 3.6 混合任务 / 不确定归属(强制走 Dispatcher)
|
||
|
||
```text
|
||
请使用 wms-dispatcher-agent 帮我:
|
||
1) 判断这个问题属于数据库、Redis、发布、开发、测试还是文档问题
|
||
2) 分派给正确的 agent
|
||
3) 汇总处理结果与下一步建议
|
||
```
|
||
|
||
## 4. Redis 能力移交规则
|
||
|
||
Redis 相关能力文档已统一移交给 `wms-redis-agent`。
|
||
|
||
适用场景:
|
||
- 查 Redis key / pattern / TTL / exists
|
||
- 读取或修改缓存值
|
||
- 排查 session、登录态、缓存不一致问题
|
||
- 核对某接口是否命中缓存或缓存值异常
|
||
|
||
执行要求(强制):
|
||
- **涉及 Redis / 缓存的任何问题,必须使用 `wms-redis-agent`**
|
||
- 默认 agent 不再在本文件重复维护 Redis 命令细节
|
||
- 具体命令、示例、输出格式、安全约束统一见:`.github/agents/缓存.agent.md`
|
||
|
||
## 5. 常见问题
|
||
|
||
- 数据库相关报错、SQL 问题、连接路由问题
|
||
- 统一转给 `wms-db-agent` 处理
|
||
|
||
- Redis 相关报错、key 排查、TTL 问题、缓存变更
|
||
- 统一转给 `wms-redis-agent` 处理
|
||
|
||
- 发布相关报错、预检失败、回退、版本查询、冒烟验证
|
||
- 统一转给 `wms-deploy-agent` 处理
|
||
|
||
- 开发相关问题:代码修改、method 路由、权限联动
|
||
- 统一转给 `wms-dev-agent` 处理
|
||
|
||
- 测试相关问题:写单元测试、补回归、接口验证、TDD、验证修复、审查 mock / 断言
|
||
- 统一转给 `wms-test-agent` 处理
|
||
|
||
- 文档相关问题:API 文档、README、`methods/system.json`、`docs/*.md`、使用说明
|
||
- 统一转给 `wms-doc-agent` 处理
|
||
|
||
- 不确定该用哪个 agent,或问题横跨数据库 / Redis / 发布 / 代码 / 测试 / 文档
|
||
- 统一转给 `wms-dispatcher-agent` 处理
|
||
|
||
- PowerShell 执行策略限制
|
||
- 使用命令中的 `-ExecutionPolicy Bypass`(仅本次命令生效)
|
||
|
||
## 6. 安全约束
|
||
|
||
- **全局安全红线(适用于所有 AI)**:禁止删改处理非测试仓库的数据,包括数据库和缓存;对非测试仓库默认只读;无法确认是否测试仓时,默认按非测试仓处理并拒绝 `UPDATE` / `DELETE` / `INSERT`、`set` / `del` / `hset` / `hdel` / `incr` / `decr` / `expire` 等写操作
|
||
- 数据库相关操作必须使用 `wms-db-agent`,并按该 agent 内的只读/确认流程执行
|
||
- Redis 相关操作必须使用 `wms-redis-agent`,并按该 agent 内的先读后改/回读确认流程执行
|
||
- 发布相关操作必须使用 `wms-deploy-agent`,并坚持仅走 `npm run` 固定入口;禁止读取 `config/deploy.config.local.cjs`
|
||
- 开发相关操作必须使用 `wms-dev-agent`,并坚持“先定位、后修改、再验证”的流程
|
||
- 测试相关操作必须使用 `wms-test-agent`,并坚持“先写失败用例、再修复、后跑相关测试并报告 passing 数量”;禁止只测 mock 或给生产代码加 test-only 方法
|
||
- 文档相关操作必须使用 `wms-doc-agent`,并坚持“先核对代码与测试,再更新文档;禁止写入敏感配置”的流程
|
||
- 涉及生产数据时,优先在测试环境验证
|
||
|
||
|
||
## 7. 开发能力移交规则
|
||
|
||
通用开发能力文档已统一移交给 `wms-dev-agent`。
|
||
|
||
适用场景:
|
||
- 改代码 / 修 bug / 重构 / 性能优化
|
||
- 定位 `/system` / `/qimen` method 映射关系
|
||
- 排查 `where` 规则、权限映射、分层职责问题
|
||
|
||
执行要求(强制):
|
||
- **涉及代码开发的任何问题,必须使用 `wms-dev-agent`**
|
||
- 默认 agent 不再在本文件重复维护开发细节
|
||
- 如诉求重点是测试设计、补回归、接口验证、TDD 或验证修复,转给 `wms-test-agent`
|
||
- 如需同步 API 文档、`methods/*.json`、`docs/*.md`,转给 `wms-doc-agent`
|
||
- 具体目录地图、联动规则统一见:`.github/agents/开发.agent.md`
|
||
|
||
## 8. 文档能力移交规则
|
||
|
||
文档相关能力文档已统一移交给 `wms-doc-agent`。
|
||
|
||
适用场景:
|
||
- 补 API 文档 / 接口说明 / 错误码 / 示例请求
|
||
- 同步 `methods/system.json` / `methods/qimen.json`
|
||
- 更新 `docs/*.md`、`README.md`、`AI_TOOLBOX.md`
|
||
- 整理 method 映射说明、接入文档、使用手册
|
||
|
||
执行要求(强制):
|
||
- **涉及文档编写或同步的任何问题,必须使用 `wms-doc-agent`**
|
||
- 文档必须以代码实现、测试结果和现有 JSON 文档为准,不得凭空编写
|
||
- 默认禁止直接手写 `methods/*.json` 和 `methods/changes/*.json`;必须先按 [docs/api-doc-update-workflow.md](docs/api-doc-update-workflow.md) 组织 spec,再执行 `npm run doc:api:update -- --spec=<path>`
|
||
- system 参数变化可先执行:`node .\script\tmp-struct-system-params.cjs`
|
||
- 正式写入前必须先执行:`npm run doc:api:update -- --spec=<path> --dry-run`
|
||
- 具体工作流统一见:`.github/agents/文档.agent.md`
|
||
|
||
## 9. 测试能力移交规则
|
||
|
||
测试相关能力文档已统一移交给 `wms-test-agent`。
|
||
|
||
适用场景:
|
||
- 写测试 / 单元测试 / 集成测试 / 补回归
|
||
- 跑接口验证 / 复现 bug / 验证修复
|
||
- 按 TDD 流程推进开发修复
|
||
- 审查 mock / 断言规范与覆盖率范围
|
||
|
||
执行要求(强制):
|
||
- **涉及测试设计、回归验证、接口验证、TDD 的任何问题,必须使用 `wms-test-agent`**
|
||
- 必须坚持先写失败用例再修复,不允许只测 mock 行为
|
||
- 不得为生产代码添加 test-only 方法或分支
|
||
- 改动后必须跑相关测试并报告 passing 数量
|
||
- 具体命令与测试规范统一见:`.github/agents/测试.agent.md`
|
||
|
||
## 10. 发布能力移交规则
|
||
|
||
发布相关能力文档已统一移交给 `wms-deploy-agent`。
|
||
|
||
适用场景:
|
||
- 发布生产 / 上线 / deploy
|
||
- 回退 / rollback / 指定备份回退
|
||
- 查询线上版本、版本历史
|
||
- 做预检、inspect、smoke、verify、gateway probe
|
||
- 排查发布链路、备份、版本记录问题
|
||
|
||
执行要求(强制):
|
||
- **涉及发布 / 回退 / 线上验证的任何问题,必须使用 `wms-deploy-agent`**
|
||
- 固定入口只允许 `npm run ...`,禁止直接运行底层 `node ./script/deploy-remote.cjs ...` / `rollback-remote.cjs ...`
|
||
- AI 禁止读取 `config/deploy.config.local.cjs`
|
||
- 具体命令、回退规则、版本管理、安全红线统一见:`.github/agents/发布.agent.md`
|
||
|
||
## 11. 开发细节移交说明
|
||
|
||
以下开发细节文档已统一移交给 `wms-dev-agent`:
|
||
|
||
- App 能力地图(`app.js`、`app/extend/application.js`)
|
||
- Web 用户信息与角色切换测试链路
|
||
- `setting.account` 接口分层约定
|
||
- `where` 参数统一规范
|
||
- `system API` 权限映射规则
|
||
|
||
执行要求(强制):
|
||
- **涉及代码开发、接口联动的任何问题,必须使用 `wms-dev-agent`**
|
||
- 如需测试设计、补回归、接口验证或验证修复,转给 `wms-test-agent`
|
||
- 若涉及文档更新,转给 `wms-doc-agent`
|
||
- 具体定位地图、命令与工作流统一见:`.github/agents/开发.agent.md`
|
||
|
||
## 16. 通知能力路由(notice / WebHook / 事件注册)
|
||
|
||
- 详细能力说明统一沉淀在:
|
||
- `docs/notification-webhook-capability.md`
|
||
- `docs/notification-event-api.md`
|
||
- 工具箱只保留入口与分工,不再重复维护 notice 的字段、payload、重试和示例细节。
|
||
- 若其他 agent 或开发任务遇到“**新功能需要通知**”,按以下路由处理:
|
||
1. **代码接入** → 使用 `wms-dev-agent`:在业务 service 中接入 `ctx.service.systems.notice.send(options)`,并完成事件注册与最小回归验证
|
||
2. **文档同步** → 使用 `wms-doc-agent`:同步通知能力文档、事件文档及必要的接口说明
|
||
- 当前统一入口:`ctx.service.systems.notice.send(options)`
|
||
- 当前代码位置:`app/service/systems/notice/index.js`
|
||
- 配置底线:`wms_store.subject_config.max_notice_webhook_count`
|
||
- 默认值:`5`
|
||
- 合法范围:`0 ~ 5`
|
||
- 创建/更新主体与 WebHook 分发时都必须遵守该上限
|