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/ 到临时目录。依赖缺失或锁文件变化时，在目标项目执行其声明的安装命令。
• 当前开发阶段不得因小功能、缺陷修复、联调、测试、构建、端口冲突、未提交修改或希望获得“干净目录”而创建 wk/Git worktree、临时分支或项目副本；统一直接在当前工作区、当前分支修改和验证，不得自行创建或切换分支。
• 只有用户在当前轮明确要求隔离分支或 worktree 时才可例外。例外时必须先说明原因、精确位置和清理条件，放在目标项目之外；任务结束且无进程占用后立即清理。
• 禁止在 apps/*/、baiyue-firstleg/ 及业务模块内部新增 .codex-temp/、.codex-tmp/、worktree/ 或类似项目副本。遗留目录须先确认没有运行进程和唯一证据，再按精确路径清理。
• 端口冲突通过停止已知旧进程或指定其他端口解决，不得复制项目。普通验证应直接覆盖当前未提交修改，不为获得“干净目录”绕开真实变更。

当前开发阶段

• 项目尚未上线，没有需要兼容的生产存量数据、线上客户端或已发布接口版本；所有代码与契约直接收敛到当前确认目标，用户确认上线或存在不可变外部契约后才重新建立版本兼容和升级规则。
• 收敛范围包括源码结构、接口与 DTO、字段、状态机、权限、配置键、OpenAPI、数据库结构与初始化 SQL、事件、路由、页面、前端消费者、Mock/Fixture、测试和脚本；旧实现冲突时同步修改全部生产者与消费者并直接删除旧实现。
• 禁止为旧代码、旧调用或开发环境存量保留旧接口/旧字段别名、兼容分支、双协议、双写、灰度、回滚版本、降级解析、旧行为回退、临时适配层、迁移脚本、回填脚本、清理补偿或新旧版本并行；不得以“稳妥”“兼容历史数据”或“先保留以后删除”为由延迟收敛。
• 开发环境数据库记录、上传文件、缓存、会话、消息、搜索索引和其他运行状态均可丢弃；正常验证方式是更新最新初始化基线、重新造数或上传，并直接运行受影响回归，不模拟生产迁移。已有历史 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。
• 总控在接收任务时必须先做时长评估；预计单一执行链超过 15 分钟时，不得继续由一个任务从定位包办到验收，必须立即拆成可并行的“根因/契约核对、实现修复、回归验收”等独立工作包，并明确每包文件写权限和交付物。优先复用登记表中的长期专项；一次性工作使用内部子代理。该规则不自动授权创建新的用户可见任务。
• 实际执行超过 15 分钟仍未形成可验证交付时，总控必须主动重新拆分或缩小范围，向用户报告当前阻断与并行安排，不得静默等待、继续扩展设计或把非必要兼容、迁移、补偿工作并入主修复链。
• 用户按业务流程逐节点进行人工验收时，总控必须以“当前验收节点”为调度和完成单位，而不是以代码模块或单个 Bug 为单位。收到该节点首个问题后，应立即并行检查前端交互、后端状态与契约、数据/权限前置和自动化验收覆盖；同一节点后续问题统一并入该批次，不得连续串行追加给一个长期专项。
• 节点验收批次至少包含一个唯一实现写入者和独立的只读诊断/回归工作包；跨端时分别下发前端、后端和验收脚本工作包。能够提前发现的问题应在本次部署前一次收口，尽量减少“部署一次、人工发现一个、再部署一次”的循环。
• 当前节点只有在代码门禁通过、相关自动化场景补齐、部署清单明确，并由用户完成真实环境人工验收后才关闭；关闭后再进入下一业务节点。总控需持续维护当前节点的阻断项、已修项和待部署项，不把其他节点的优化混入当前发布批次。
• 检索历史任务只使用本机 ~/.codex/session_index.jsonl、~/.codex/state_5.sqlite、~/.codex/sessions/ 和已知本地任务，不依赖聚合本地、远程主机或云端对话的列表接口。
• 被指定为总控只授权规划、拆解、协调和复用已登记任务，不授权创建新的用户可见独立任务；临时并行默认使用当前对话或内部子代理。
• 创建用户可见独立任务必须由用户在当前轮明确要求，并确认精确数量、稳定职责和所属总控；历史授权以及“继续处理”“拆分”“安排”“并行”等表述不构成创建授权。
• 创建前必须查询登记表并优先复用职责匹配的 task_id；一次性缺陷、排障、部署、临时验收和只为提速的并行工作不得登记为长期任务。
• 创建成功后先登记稳定 task_id、所属总控和唯一长期职责，再下发工作；不自动创建替代任务或归档、解档、恢复、迁移任务。
• 并行前明确文件归属和共享契约。共享导航、根路由、权限初始化和统一 SQL 由已登记的对应总控统一集成；发生重叠时保留现有改动并跨任务协调。