reachai-project git:20260823.ae9e1ceA

Immutable. This exact content never changes and is served at /api/v1/blob/faa35043deb7f17e.

---
description: ReachAI project rules for AI coding agents
alwaysApply: true
---

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