12 KiB
12 KiB
AI 工具箱(WMS)
🤖 AI阅读优先级
- 必读:第2节(数据库 agent 入口)、第4节(Redis agent 入口)、第7节(开发 agent 入口)、第8节(文档 agent 入口)、第9节(测试 agent 入口)- 最常用
- 重要:第3节(提问模板)、第6节(安全约束)、第10节(发布 agent 入口)
- 按需:第11节(开发细节移交说明)、第16节(消息通知)
- 红线: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/ye4sclient 路由 - 输出字段含义、异常数据判断、索引建议
执行要求(强制):
- 涉及数据库的任何问题,必须使用
wms-db-agent - 默认 agent 不再在本文件重复维护数据库命令细节
- 具体命令、示例、输出格式、安全约束统一见:
.github/agents/数据库.agent.md
3. AI 协助时建议使用的提问模板
3.1 数据库类请求(强制走 Agent)
请使用 wms-db-agent 帮我:
1) 定位相关 controller / service / model
2) 生成并执行只读 SQL
3) 输出结果、字段解释和结论
3.2 Redis 类请求(强制走 Agent)
请使用 wms-redis-agent 帮我:
1) 找到相关 key 或 pattern
2) 读取当前值、TTL、exists 状态
3) 如需修改,先展示变更前后对比并回读确认
3.3 开发类请求(强制走 Dev Agent)
请使用 wms-dev-agent 帮我:
1) 定位这个 method / controller / service 的实现链路
2) 修复问题并说明最小代码改动方案
3) 给出验证结果与后续开发建议
3.4 测试类请求(强制走 Test Agent)
请使用 wms-test-agent 帮我:
1) 先复现问题并补一个失败用例
2) 按 TDD 跑回归或接口验证
3) 输出 passing 数量、失败数和修复验证结论
3.5 文档类请求(强制走 Doc Agent)
请使用 wms-doc-agent 帮我:
1) 根据代码现状整理接口或业务文档
2) 同步 methods/*.json / docs/*.md / README
3) 校验文档与实现一致
3.6 混合任务 / 不确定归属(强制走 Dispatcher)
请使用 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//qimenmethod 映射关系 - 排查
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 文档为准,不得凭空编写
- system 参数变化可执行:
node .\script\tmp-struct-system-params.cjs - 具体工作流统一见:
.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.mddocs/notification-event-api.md
- 工具箱只保留入口与分工,不再重复维护 notice 的字段、payload、重试和示例细节。
- 若其他 agent 或开发任务遇到“新功能需要通知”,按以下路由处理:
- 代码接入 → 使用
wms-dev-agent:在业务 service 中接入ctx.service.systems.notice.send(options),并完成事件注册与最小回归验证 - 文档同步 → 使用
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 分发时都必须遵守该上限
- 默认值: