git:20260823.ae9e1ce to git:20261027.3e9d064

- # ReachAI AI Coding Rules

-

- 进入本仓库后，先读根目录 `AGENTS.md`。它是 Codex、Cursor 和其他 AI 编程工具共享的最高优先级项目规则。

-

- ## Must Follow

-

- - 以当前仓库为事实源。先查真实代码、SQL、接口、前端页面和文档，再下结论。

- - 可以修改前端、后端、SQL、文档和构建配置，但改动必须聚焦当前任务。

- - 默认不考虑旧数据兼容；当前正确设计优先。

- - 数据库变化必须先检查并修改 `sql/initV2.sql`；如当前任务需要升级已有开发/测试库，再新增 `sql/upgrade-YYYYMMDD-short-name.sql`。

- - 不要使用 service 目录下的历史 SQL 作为活跃迁移入口。

- - 不要回滚、格式化或重写与任务无关的用户改动。

- - 中文文件统一按 UTF-8 读写。

-

- ## Project Memory

-

- 给 AI 的项目记忆在 `docs/ai-memory/`：

-

- - `PROJECT-MEMORY.md`: 产品定位、模块地图和当前事实。

- - `WORKING-RULES.md`: 开发、SQL、验证和协作规则。

- - `DECISIONS.md`: 架构和命名决策。

- - `KNOWN-PITFALLS.md`: 以前踩过的坑和诊断顺序。

- - `VERIFICATION.md`: 常用验证命令。

- - `AI-TOOLS.md`: Playwright 浏览器调试和 DBHub MySQL 只读查询约定。

-

- ## Core Architecture

-

- - ReachAI 是面向 Java 企业系统的 AI 能力中台，不只是 Workflow Builder。

- - 主线是 `reachai-spring-boot2-starter`、`reachai-capability-sdk`、`@ReachCapability` / `@ReachParam` 注册项目、实例、能力和 SDK 图，平台治理后进入能力资产目录、Workflow Studio 和 Runtime。

- - 当前后端主路径是 `reachai-control-service`、`reachai-runtime-service`、`reachai-capability-service`、`reachai-knowledge-service`、`reachai-model-service`；旧 `ai-agent-service` 不再作为 Maven、IDEA、本地启动或部署单元存在。

- - `GraphSpec` 是运行语义，`canvas_json` 只是画布布局。

- - `AgentRuntimeAdapter` 是运行时统一执行契约。

- - `Capability / 能力` 是产品默认命名。ReachAI 禁止重新引入自创的 Skill 业务资产模型。Skill 仅用于标准 Agent Skill 包或外部协议字段；Capability 是业务资产，Tool 是调用协议，Workflow 是 GraphSpec 编排。

-

- ## Validation

-

- - 后端改动跑相关 Maven 模块测试或编译。

- - 前端改动在 `ai-admin-front` 跑 `npm run build`，必要时跑 `npx vue-tsc --noEmit`。

- - SQL 改动检查 `sql/initV2.sql`，以及当前任务新增的 upgrade SQL 是否覆盖目标变更。

- - 文档/规则改动至少跑 `git diff --check`。

-

- ## MCP Tools

-

- - 需要浏览器调试、截图、DOM 快照、console 或 network 观察时，优先使用 Playwright MCP。

- - 需要查看实时 MySQL schema 或少量只读数据时，优先使用 `dbhub_ai_mysql`。

- - `dbhub_ai_mysql` 只能用于只读诊断，不执行 DDL/DML，不导出批量数据，不读取密钥或无关业务隐私。

- - `.cursor/mcp.json` 和 `.cursor/dbhub-ai-mysql.toml` 属于本机 MCP 配置，默认不提交；真实数据库密码必须来自本机环境变量，不要写入仓库。