WMS_MAIN/AI_TOOLBOX.md
liufumingren 16803e8cc2 1
2026-04-11 17:07:16 +08:00

12 KiB
Raw Blame History

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)

请使用 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 / /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 文档为准,不得凭空编写
  • 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.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 分发时都必须遵守该上限