# 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=` - system 参数变化可先执行:`node .\script\tmp-struct-system-params.cjs` - 正式写入前必须先执行:`npm run doc:api:update -- --spec= --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 分发时都必须遵守该上限