reachai-project

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 配置，默认不提交；真实数据库密码必须来自本机环境变量，不要写入仓库。