# ReachAI Agent Rules 本文件是给 Codex、Cursor、Claude Code、Copilot CLI 等 AI 编程工具看的项目级规则。进入本仓库后，智能体必须先读本文件，再执行代码、SQL 或文档修改。 ## 工作原则 - 以当前仓库为事实源。先查真实代码、SQL、接口、前端页面和文档，再下结论。 - 可以修改前端、后端、SQL、文档和构建配置，但改动必须聚焦当前任务。 - 不要为了兼容旧数据而牺牲当前正确设计。本项目默认处于快速迭代阶段，schema 和种子数据可以按当前目标直接演进。 - 不要回滚、格式化或重写与任务无关的用户改动。 - Windows PowerShell 是常见执行环境；中文文件统一按 UTF-8 读写，避免 GBK/mojibake。 - 使用 `rg` / `rg --files` 优先查找文件和文本。 ## Windows PowerShell 与原生程序 UTF-8 硬约束 - 含中文的 Python、Node、JSON、SQL 或请求体，禁止直接通过 Windows PowerShell 默认管道传给原生程序，例如 `@'...中文...'@ | python -`。 - 优先使用 `apply_patch` 创建 UTF-8 临时脚本或 JSON 文件，再执行对应程序。 - 如果必须通过 PowerShell 管道传递中文，执行前必须设置： ```powershell $utf8 = [System.Text.UTF8Encoding]::new($false) $OutputEncoding = $utf8 [Console]::InputEncoding = $utf8 [Console]::OutputEncoding = $utf8 ``` - 向数据库或 API 写入中文后，必须回读验证；如果中文变成连续 `?`，视为执行失败，不得继续后续验收。 ## 项目定位 ReachAI 是面向 Java 企业系统的 AI 能力中台，不只是 Workflow Builder，也不只是扫描历史项目生成 Tool。 当前主线是： 1. 业务系统通过 `reachai-spring-boot2-starter`、`reachai-capability-sdk`、`@ReachCapability`、`@ReachParam` 主动注册项目、实例、能力和 SDK 图。 2. 平台侧形成能力快照、字段级 diff、评审 apply/ignore，并沉淀到能力资产目录。 3. Workflow Studio 使用 `GraphSpec` 编排 Workflow（表：`runtime_workflow`）；Agent（表：`runtime_agent`）通过已发布配置版本和 Workflow-as-Tool 白名单，由 Supervisor 按用户意图选择零个、一个或多个 Workflow。AI 生成、局部修改、调试、发布和回放均在 Workflow Studio 闭环。 4. Runtime 通过 `SupervisorRuntimeAdapter` 承载 AgentScope 的理解、规划、选择与有限重规划，通过 `AgentRuntimeAdapter` / GraphSpec executor 承载 Workflow 执行，并为未来运行时保留适配边界。 5. RunOps、Trace、Tool ACL、Guard、Gateway、MCP、A2A、嵌入式对话和企业身份共同组成生产治理边界。 当前后端重塑已进入物理服务拆分后的旧结构退场阶段。目标拓扑是 `reachai-control-service`、`reachai-runtime-service`、`reachai-capability-service`、`reachai-knowledge-service`、`reachai-model-service`。第一阶段保持同一个 MySQL 库，不拆库；公共入口由 `reachai-control-service` 保持 `/api/**`、`/embed/**` 和 SDK 注册入口兼容。旧 `ai-agent-service` module 已从仓库主路径删除，不再作为 Maven、IDEA、本地启动或部署单元存在。任何新增代码必须遵守服务表所有权和服务间 API 边界，不允许为了快速编译跨服务直接写对方表。 ## 关键目录 - `ai-admin-front/`: Vue 3 + Element Plus 管理端。 - `reachai-control-service/`: 当前 Platform Control / public API BFF 主入口，保持 `/api/**`、`/embed/**` 和 SDK 注册公开入口。 - `reachai-runtime-service/`: 当前 Runtime Host 部署单元，承接 Agent、Workflow、GraphSpec、Trace、RunOps、调试和运行时内部 API。 - `reachai-capability-service/`: 当前 Capability Catalog 部署单元，承接 SDK 注册、能力快照、diff/review/apply、扫描目录和能力资产 API。 - `reachai-knowledge-service/`: 当前 Knowledge / Retrieval 部署单元；包括知识库、文件、chunk、RAG、业务索引、向量检索和历史扫描器实现。不要再把它描述成“技能服务”。 - `reachai-model-service/`: 当前 Model Gateway 部署单元；包括模型中心 V2（`model_template` + `model_instance`）、Chat、Embedding、Rerank。不再提供未使用的 `/model/openai-proxy` 入口。 - `reachai-capability-sdk/`: JDK8 兼容的业务能力声明 SDK 契约。 - `reachai-spring-boot2-starter/`: Spring Boot 2 业务系统接入、扫描、注册和 SDK 图同步。 - `ai-runtime-contract/`: 中台内部业务记忆引用契约。 - `sql/initV2.sql`: 当前新库 SQL 基线入口；第一阶段仍是同一个 MySQL 库，不拆库。 - `sql/upgrade-*.sql`: 仅用于当次数据库变更升级已有开发/测试库；当前新库基线不要求兼容旧数据。 - `docs/`: 当前权威知识库。 - `docs/ai-memory/`: 给 AI 编程工具看的项目记忆。 ## SQL 规则 - 任何 schema、索引、种子数据、字段语义相关改动，都必须检查 `sql/initV2.sql`。 - 如果改动需要数据库变化，必须至少修改 `sql/initV2.sql`，让全新环境直接可用。 - 如果该数据库变化还需要落到已有开发/测试库，必须新增一份 `sql/upgrade-YYYYMMDD-short-name.sql`，写清升级影响，并更新 `sql/README.md` 或相关文档中的执行说明。 - 不再使用 `ai-agent-service/sql`、`ai-model-service/sql`、`ai-skills-service/sql` 作为活跃迁移目录。 - 默认不为旧数据做复杂兼容迁移；如果必须清理、重建、重命名或丢弃旧字段，直接在升级 SQL 和变更说明里写清楚。 - MySQL 5.7/8 兼容性要看 `sql/initV2.sql` 已有写法，优先沿用现有 `information_schema` 判空和幂等模式。 - 同库阶段仍必须维护 `docs/architecture/service-table-ownership.md`；`sql/initV2.sql` 中每张 `CREATE TABLE` 表都必须有唯一 owning service。 - 跨服务直接读写表默认违规，扫描范围包括 `@TableName`、MyBatis 注解 SQL、MyBatis XML SQL 和 JdbcTemplate SQL。确有历史兼容需要时，只能作为临时例外写入 `Additional direct access`，并说明访问服务和原因。 - 服务协作优先通过 owning service 的 internal API、显式 client 或服务自有 read model，不允许为了快速编译跨服务复用对方 Mapper、Entity 或直接 SQL。 - 当前表名按 owner service / domain 前缀收口，例如 `runtime_workflow`、`runtime_agent`、`capability_tool_definition`、`runtime_interaction_session`、`control_page_registry`、`runtime_tool_call_log`、`knowledge_base`。本项目当前按新库重建，不要求兼容旧表名或旧数据迁移。 ## GraphSpec 与 Runtime - `GraphSpec` 是运行语义，归属 Workflow；`canvas_json` 只是画布布局。 - 后端类型以当前主路径服务中的 `com.enterprise.ai.agent.graph.GraphSpec` 为准；`reachai-runtime-service` 是 Runtime 执行主路径，后续再评估 shared-kernel 抽取。 - 前端 Workflow 图语义类型以 `ai-admin-front/src/types/workflow.ts` 为准（Studio 状态、Workflow 定义等；共享节点/边结构仍可见于 `agent.ts` 的 `AgentGraphSpec`）。 - DB 字段：`runtime_workflow.graph_spec_json`（运行语义）、`runtime_workflow.canvas_json`（画布布局）。 - 发布校验由 `WorkflowReleaseValidationService` 负责；Agent 执行主线由 AgentScope Supervisor 解析已发布配置版本和 Workflow-as-Tool 白名单，单个 Workflow 由 `LangGraph4jRuntimeAdapter` / `RuntimeGraphSpecExecutor` 执行。 - 新增 Workflow Studio 节点、AI 编辑能力或 Runtime 行为时，必须把可执行语义写入 Workflow `GraphSpec`，不能只改前端画布表现。 - AI 生成 Proposal 走 `/api/workflows/studio/proposals/generate`；Workflow Studio 设计期自然语言编辑 Proposal 走 `/api/workflows/studio/proposals/edit`，由 `WorkflowAuthoringAgentAdapter`（AgentScope）经受约束工具修改内存候选，再由确定性 GraphSpec mutation / validation 校验。旧 `generate-draft`、`edit-draft` 路由不再提供。 ## 命名规则 - 产品和文档默认使用 `Capability / 能力`。 - ReachAI 禁止重新引入自创的 Skill 业务资产模型。Skill 仅用于标准 Agent Skill 包或外部协议字段；Capability 是业务资产，Tool 是调用协议，Workflow 是 GraphSpec 编排。 - 通用 `Tool` 不作为独立产品资产、顶级菜单或人工维护目录。`capability_tool_definition`、`/api/tools/**`、Tool ACL、Tool Call、MCP Tool 与 Workflow-as-Tool 属于运行时投影、协议或兼容技术身份；产品页面应回到其 owning object，分别使用能力目录、API、可调用 Workflow、MCP 暴露和调用权限等名称。 - 未来若建设注解方法的独立模块，产品名使用“代码工具 / Code Tools”，语义限定为 Methods as Tools；在该模型正式落地前，不得把当前通用 Tool 目录改名冒充代码工具，也不得使用 `FunctionToolCallback` 等框架类名作为业务模块名。 - 合法 Skill 仅包括 `ai-assist/skills/**` 中的 `SKILL.md` 包、`/api/ai-assist/skills/**` 下载入口、A2A 标准 `skills` 字段，以及对已退役 `ai-skills-service` 的否定性记录。不要把旧 Skill 目录、GraphSpec `CAPABILITY` 节点或 `kind=SKILL` 行包装成 AgentScope Skill。 - `eaf.*`、`X-EAF-*`、`Eaf*` 类名、Maven artifactId、运行时路径属于技术身份，品牌文案改成 ReachAI 时不要顺手改这些兼容敏感标识。 ## 前端规则 - 管理端是工作台型产品，优先信息密度、扫描效率和可重复操作体验。 - 主题色、暗色/亮色适配优先使用现有 CSS 变量和主题文件，不要在页面里散落硬编码颜色。 - 涉及页面布局时，先确认路由、`MainLayout.vue`、共享组件和状态管理，不要在单页里做难以复用的局部 hack。 - Workflow Studio 变更要验证画布、配置面板、预览/应用、发布校验、Agent Workflow-as-Tool 配置和调试链路是否仍然一致。 ## 验证规则 - 后端优先跑相关 Maven 模块测试；小改动至少跑对应模块编译或目标测试。 - 前端改动优先在 `ai-admin-front` 下跑 `npm run build`，必要时先跑 `npx vue-tsc --noEmit`。 - 文档和规则改动至少跑 `git diff --check`，并检查链接/路径是否指向真实文件。 - SQL 改动至少检查 `sql/initV2.sql`；如果当前任务新增 upgrade SQL，还要确认 upgrade SQL 包含目标表/列/索引。有 MySQL 环境时再执行验证。 - 如果用户报告具体错误，必须复现或对照同一错误签名后再声明修复完成。 ## AI 记忆入口 更长的项目记忆在 `docs/ai-memory/`： - `README.md`: 记忆区说明。 - `PROJECT-MEMORY.md`: 产品定位、模块地图和当前事实。 - `WORKING-RULES.md`: 开发、SQL、验证和协作规则。 - `DECISIONS.md`: 已形成的架构和命名决策。 - `KNOWN-PITFALLS.md`: 以前踩过的坑和诊断顺序。 - `VERIFICATION.md`: 常用验证命令。 - `AI-TOOLS.md`: Playwright 浏览器调试和 DBHub MySQL 只读查询约定。