EnterpriseAgentFramework: Instructions file for Codex

ReachAI Agent Rules

进入仓库先读本文件，再从文档入口选择当前任务相关主题。人和 AI 共用一套文档，不另存项目记忆、历史方案或执行提示词。

工作边界

• 以当前代码、SQL、配置、接口与实际运行结果为事实源；文档中的目标不等于已实现或已验收。
• 只修改当前任务相关内容，保留其他未提交工作；常规实现自主推进，改变已确认产品边界时先明确方案与影响。
• 产品、用户和核心对象以产品说明为准。Capability 是业务资产统称，Tool 是调用投影，Workflow 是 GraphSpec；Skill 仅指标准包或协议字段。
• 不把文档、旧会话或未启动待办当作执行授权。不因整理代码或文档自动提交、推送、部署、改库或调用真实写业务。
• 开发库向开源库同步遵守开源同步规则：官网仅保留在开发库，使用过滤快照生成开源改动，不直接合并开发库历史。
• 搜索优先 rg / rg --files，中文文件使用 UTF-8。
• 帮用户部署、升级或排障 ReachAI 时，以用户指定的方式和现网结构为准，参考部署与运维手册选择操作，不限定于手册命令或 reachai.env。已明确授权的范围内自主推进，不因采用宝塔 MCP、独立 JAR/systemd 等现网方式重复确认；改库前按实际部署方式备份，保留无关服务和数据。

架构与数据

• reachai-control-service 是公共 API、身份与治理入口；reachai-runtime-service 执行 Agent / Workflow。
• reachai-capability-service 拥有项目来源、业务方法/API；reachai-knowledge-service 拥有知识与检索投影；reachai-model-service 统一模型调用。
• 同库不共享表所有权。跨服务通过 internal API、显式 client 或服务自有 read model，不访问对方 Mapper、Entity 或 SQL 表。
• schema、索引、种子和字段语义变更同步 sql/initV2.sql；已有环境需要时新增 upgrade SQL 并更新 sql/README.md，执行后回读验证。
• 精确依据：架构、表归属、内部 API、公共路由。

产品实现

• 业务能力改动同时服务 Java 开发者与 Agent / Workflow 实施人员，按U1–U4 验收关联具体任务。
• GraphSpec 保存执行语义，Canvas 只保存布局；Handler、发布校验、Studio 与 AI mutation 保持一致。
• 调用身份只能来自受验证链路；ACL、来源契约、版本 pin 与副作用保护不由浏览器或模型字段绕过。
• 前端先核对路由、MainLayout、共享组件和状态管理；复用公共 liquid-glass 入口与主题 token，规则见DESIGN。
• eaf.*、X-EAF-*、Java/Maven/协议技术身份不随品牌文案顺手改名。
• 随产品分发的内置 Skill 内容变更必须升级版本和摘要，见Skill 版本规则。

Windows 与 UTF-8

含中文的 Python、Node、JSON、SQL 或请求体优先写入 UTF-8 文件再执行。通过 PowerShell 管道传给原生程序时先设置：

$utf8 = [System.Text.UTF8Encoding]::new($false)
$OutputEncoding = $utf8
[Console]::InputEncoding = $utf8
[Console]::OutputEncoding = $utf8

API 或数据库写入中文后必须回读；出现连续 ? 视为失败，不继续验收。

验证与文档

• 后端运行相关模块的目标测试或编译；前端运行相关行为测试与 npm run build，需要时验证真实浏览器。
• 具体错误须复现或对照同一错误签名后才能声明修复。夹具、构建、制品、运行与业务验收分别说明边界。
• 文档只保留当前核心内容；同一事实维护一次，重复、过时和历史记录直接删除，不留归档。必要的未验条件统一写入 status。
• 移动、合并或删除文档同步引用和检查器，运行 node scripts/check-documentation.mjs、相关检查器测试与 git diff --check。