docs/AI工程执行与协作约束.md

AI 工程执行与协作约束

读取条件

• 运行、构建、依赖、临时目录、工作树、部署、数据库、跨模块改动或独立任务协作时读取本文件。
• 普通代码定位仍先按根 AGENTS.md 的项目和业务路由进入最近的项目/模块指引；本文件不替代业务索引。

根目录、临时目录与依赖复用

• 根目录只保留 apps/ 前端应用、baiyue-firstleg/ 后端独立仓库、docs/ 产品与契约文档三类业务事实来源；新增业务源码或服务不得直接放在根目录。
• .vscode/、.impeccable/、.superpowers/ 和根 .codex-temp/ 属于本地工具或缓存，不作为业务入口；根 .codex-temp/ 不得存放项目副本。
• output/、outputs/、dist/、target/、日志和临时文件属于生成物，不纳入索引；空的临时产物目录应及时清理。
• 启动服务、测试、类型检查和构建默认直接在目标项目目录执行，并复用现有 node_modules/、Maven 本地仓库及其他依赖缓存；不得仅为运行或验证创建 .codex-temp/<task>、.codex-tmp/<task> 或完整项目副本。
• 不得复制、移动或手工链接现有 node_modules/ 到临时目录。依赖缺失或锁文件变化时，在目标项目执行其声明的安装命令。
• 只有验证干净基线、隔离不同分支，或隔离破坏性生成器时才可创建临时工作树；优先使用 Git worktree 或系统临时目录并放在目标项目之外，创建前说明原因、位置和清理条件，结束且无进程占用后立即清理。
• 禁止在 apps/*/、baiyue-firstleg/ 及业务模块内部新增 .codex-temp/、.codex-tmp/、worktree/ 或类似项目副本。遗留目录须先确认没有运行进程和唯一证据，再按精确路径清理。
• 端口冲突通过停止已知旧进程或指定其他端口解决，不得复制项目。普通验证应直接覆盖当前未提交修改，不为获得“干净目录”绕开真实变更。

当前开发阶段

• 项目尚未上线，没有需要兼容的生产存量数据、线上客户端或已发布接口版本；用户确认上线后应重新建立版本兼容和升级规则。
• 对已确认目标直接收敛实现、接口、状态、权限、OpenAPI、前端消费者和初始化 SQL；旧实现冲突时直接修改或移除，不默认保留旧字段、接口、权限、状态或行为的兼容分支。
• 当前不设计数据迁移、双写、灰度、回滚版本、旧客户端兼容或新旧协议并行，也不为历史开发数据新增迁移脚本；数据库结构以最新完整初始化 SQL 为准。
• 已有历史 SQL 只用于开发追溯，不构成兼容依据；后端位于独立 Git 仓库 ../baiyue-firstleg/，执行 Git 命令前确认当前工作目录。
• “无需兼容和迁移”不授权自动重置数据库、删除数据、执行 SQL 或部署环境。

联调、部署与数据库

• 默认只准备代码、验证结果和人工部署步骤，不触发 Jenkins、不启动本地 Java/Nacos/数据库，也不修改测试环境数据。
• 只有用户在当前轮明确授权指定环境、服务和提交时，才可部署或执行 HTTP 验收；测试环境数据库默认只读。
• 环境地址、凭据和 Token 不写入源码或 AGENTS.md。接口不可用或契约不一致时记录路径、状态、错误码、requestId/traceId 和阻断原因，不回退到模拟成功。
• 具体联调脚本、服务启动和验收命令以目标项目指引及 测试环境Jenkins部署指南.md 为准。

通用工程与质量门禁

• 保持变更小而聚焦，遵循目标项目现有命名、分层和格式，不顺手重构无关代码。
• 优先复用现有依赖和公共能力；新增或升级依赖前说明必要性、影响范围和替代方案。
• 不提交依赖目录、构建产物、运行日志、编辑器缓存或本地临时文件；不写入密钥、令牌、真实客户数据或环境特定地址。
• 用户可见文案保持清晰一致；代码标识符使用英文，业务说明和文档可使用中文。
• 仅运行目标项目实际声明的安装、检查、测试和构建命令。每次变更至少验证直接受影响的项目，跨项目变更还要验证对应消费者。
• 修改方法、构造器、组件 Props、函数、接口、DTO 或请求/响应参数时，定向检索全部生产调用、测试调用、Mock、Fixture、契约测试和脚本引用，并同步修改。
• 参数或类型签名变化必须运行会编译测试源码的最小检查；无法验证时明确列出未验证范围。
• 修复缺陷优先增加复现测试；没有现成测试设施时不为小改动引入整套框架，应记录验证步骤和剩余风险。
• UI 变更按受影响范围检查加载、空态、错误态、权限、目标视口和可访问性；Admin/Client 视觉细则查 Admin-Client前端原型还原验收规则.md 和目标应用指引。
• 需求、技术栈或接口未确认时停在可逆设计阶段，不自行作出高成本平台决策。

独立任务与多任务协作

• 普通任务不读取协作登记。只有用户明确指定当前对话为总控，或要求检索历史任务、独立任务或跨对话通信时，才读取 独立任务协作登记.md。
• 检索历史任务只使用本机 ~/.codex/session_index.jsonl、~/.codex/state_5.sqlite、~/.codex/sessions/ 和已知本地任务，不依赖聚合本地、远程主机或云端对话的列表接口。
• 被指定为总控只授权规划、拆解、协调和复用已登记任务，不授权创建新的用户可见独立任务；临时并行默认使用当前对话或内部子代理。
• 创建用户可见独立任务必须由用户在当前轮明确要求，并确认精确数量、稳定职责和所属总控；历史授权以及“继续处理”“拆分”“安排”“并行”等表述不构成创建授权。
• 创建前必须查询登记表并优先复用职责匹配的 task_id；一次性缺陷、排障、部署、临时验收和只为提速的并行工作不得登记为长期任务。
• 创建成功后先登记稳定 task_id、所属总控和唯一长期职责，再下发工作；不自动创建替代任务或归档、解档、恢复、迁移任务。
• 并行前明确文件归属和共享契约。共享导航、根路由、权限初始化和统一 SQL 由已登记的对应总控统一集成；发生重叠时保留现有改动并跨任务协调。