WMS_MAIN/AI_TOOLBOX.md

269 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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`(已库表化:`wms_api_method_doc` + `script/method-doc-*.cjs` 维护并导出回写)、`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 分发时都必须遵守该上限