EnterpriseAgentFramework AGENTS.md

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 管道传递中文，执行前必须设置：

  $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 编程工具看的项目记忆。