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/ 或类似项目副本。遗留目录须先确认没有运行进程和唯一证据，再按精确路径清理。
• 端口冲突通过停止已知旧进程或指定其他端口解决，不得复制项目。普通验证应直接覆盖当前未提交修改，不为获得“干净目录”绕开真实变更。

本机重型检查与多对话限流

• Windows 本机的测试、类型检查、构建、依赖安装和 Maven 命令统一经 baiyue-firstleg/scripts/local-check.ps1（PowerShell 7）执行。两个锁位于当前用户 %LOCALAPPDATA%/Chongchong/LocalChecks/，与工作目录和对话无关；同一用户下最多同时执行 2 项，两槽都占用时才排队，每 15 秒提示占用。首槽沿用 heavy.lock，在途旧入口继续计入首槽；第二槽为 heavy-2.lock。已启动的旧版等待者仍只等待首槽，新调用自动选择可用槽；不终止或接管现有任务。入口不拦截绕过入口的命令。
• 在工作区根使用：& ./baiyue-firstleg/scripts/local-check.ps1 -WorkingDirectory ./apps/admin-web -Label 'Admin typecheck' -Command @('pnpm', 'typecheck')。定向 Vitest 示例：-Command @('pnpm', 'exec', 'vitest', 'run', 'src/目标.test.ts')；后端示例：-WorkingDirectory ./baiyue-firstleg -Command @('mvn', '-pl', '目标模块', '-am', 'test-compile')。参数使用数组，不拼接命令字符串。
• 查看占用：& ./baiyue-firstleg/scripts/local-check.ps1 -Status。默认最多排队 900 秒（-WaitSeconds），执行最多 1200 秒（-TimeoutSeconds）。排队超时退出 75 且不启动检查；执行超时退出 124 并回收本次进程树；其他情况透传命令退出码。锁由操作系统文件句柄维护，不删除锁文件抢占。正常结束、超时和包装器强制退出均由 Windows Job Object 回收本次后代；不按 Node/Java 进程名清理其他任务。
• 子进程默认设置 Vitest 最多 2 个 worker；Node 单进程堆上限 2048MB；Java 单进程堆上限 1536MB、可见处理器 2 个。直接运行 node --test 时自动补 --test-concurrency=2；直接运行 Maven 时补 -T 1 -DforkCount=1 -DreuseForks=true，拒绝重复指定这些并发参数。嵌套 shell/自定义脚本不得另行提高并发、覆盖限制或并发启动重型任务；经包管理器间接调用 Node 内置测试时，在该测试命令中显式保留 --test-concurrency=2。这些是每进程限制，并非整个进程树的总内存限额。
• 前后端全量入口 backend-full-regression.ps1、frontend-full-regression.ps1 执行时整批占一个名额，DryRun 不占用。已在入口保护下的批次执行原始命令，不重复申请锁；入口会拒绝嵌套调用，避免互相等待。
• 每个任务先完成必要的定向检查；批次收尾再统一执行应用要求的全量门禁，不因排队取消必要验证。复用结果前核对命令、目录、相关源码/依赖/配置均相同；验证期间相关输入变化则作废重跑。入口仅保存最近一次执行摘要，不自动计算代码快照、不自动跳过测试，也不保证先来先执行。
• 本机每槽独立保存占用者与最近结果：首槽 owner.json、last-result.json，第二槽 owner-2.json、last-result-2.json。只保存检查名称、目录、工具、PID、槽号、时间和退出码，不保存命令参数、凭据或测试输出；名称不得包含秘密。-Status 分别展示两槽及总占用，摘要不是业务/部署事实来源。无需凭据，不访问网络、数据库或部署环境；被包装命令原有的网络/写入能力及授权要求不变。
• 只读检索和互不冲突的编辑可并行；开发服务按应用复用已有实例，不纳入短任务队列，也不通过本入口启动常驻服务。已有运行任务由所属对话收尾；本入口不自动终止它们。
• 免排队范围仅限离线只读的静态合同：baiyue-firstleg/scripts/agents-index-contract.ps1、scripts/mapper-scan-contract.mjs 等直接扫描文件的 PowerShell/MJS 脚本；node --test 形式的合同测试文件仍属测试。任何 pnpm test、pnpm typecheck、pnpm build、node --test 和 mvn 命令必须经 local-check.ps1，不得以“离线合同”为由绕过。

当前开发阶段

• 项目尚未上线，没有需要兼容的生产存量数据、线上客户端或已发布接口版本；所有代码与契约直接收敛到当前确认目标，用户确认上线或存在不可变外部契约后才重新建立版本兼容和升级规则。
• 收敛范围包括源码结构、接口与 DTO、字段、状态机、权限、配置键、OpenAPI、数据库结构与初始化 SQL、事件、路由、页面、前端消费者、Mock/Fixture、测试和脚本；旧实现冲突时同步修改全部生产者与消费者并直接删除旧实现。
• 禁止为旧代码、旧调用或开发环境存量保留旧接口/旧字段别名、兼容分支、双协议、双写、灰度、回滚版本、降级解析、旧行为回退、临时适配层、迁移脚本、回填脚本、清理补偿或新旧版本并行；不得以“稳妥”“兼容历史数据”或“先保留以后删除”为由延迟收敛。
• 开发环境数据库记录、上传文件、缓存、会话、消息、搜索索引和其他运行状态均可丢弃；正常验证方式是更新最新初始化基线、重新造数或上传，并直接运行受影响回归，不模拟生产迁移。已有历史 SQL 只用于开发追溯，不构成兼容依据。
• 后端位于独立 Git 仓库 ../baiyue-firstleg/，执行 Git 命令前确认当前工作目录。“无需兼容、直接修复”不授权自动重置数据库、删除数据/文件、执行 SQL、部署或修改环境。测试环境授权只读 独立任务协作登记.md，开发全流程授权只读 开发环境独立任务协作登记.md；未登记任务和生产环境仍需用户在当前轮明确授权。

联调、部署与数据库

• 默认只准备代码、验证结果和人工部署步骤，不触发 Jenkins、不启动本地 Java/Nacos/数据库。开发全流程总控可按 开发环境独立任务协作登记.md 的授权操作开发数据库、部署开发环境并执行开发环境真实 HTTP；登记专项可按 独立任务协作登记.md 的持续授权查询和修改用户指定的测试数据库。两类授权不得跨环境复用，也不得自动扩大到 Jenkins 或生产环境。
• 只有用户在当前轮明确授权指定环境、服务和提交时，才可部署或执行 HTTP 验收；同一环境和服务的非破坏性写入可复用本轮授权，删除、重置、执行 SQL、部署或发布仍逐项授权。测试数据库的读写例外仅适用于登记表中已持续授权的总控与专项，并遵守其中的职责和破坏性操作门禁。
• 环境地址、凭据和 Token 不写入源码或 AGENTS.md。接口不可用或契约不一致时记录路径、状态、错误码、requestId/traceId 和阻断原因，不回退到模拟成功。
• 测试环境联调、部署和验收命令读取 测试环境Jenkins部署指南.md；开发全流程只按 开发环境独立任务协作登记.md 的授权与目标项目指引执行，不把测试 Jenkins 流程当作开发部署入口。

通用工程与质量门禁

• 对外 API 新增、改名、删除或访问域变化，以“调用端实际路径（含 API Base）→ 对应区域 Gateway → Controller → OpenAPI → 权限”作为一个交付单元；不能只在修改网关文件时才检查注册。已被正确通配路由覆盖时无需重复添加路由，内部服务令牌接口不得为通过检查而公开。

• 提交前运行 node --test scripts/gateway-route-contract.test.mjs 及受影响服务/调用端的定向测试；路由合同失败不得提交或声称完成。该离线合同检查源码映射、目标服务及内部路径隔离，不代替权限、HTTP 方法、运行时 Nacos 或真实 HTTP 验收；前端 Mock 测试、类型检查及服务单测通过也不证明网关可达。

• 交付列明变更接口、路由是否复用或新增、验证结果及部署单元；Gateway 配置变化必须包含对应网关，Nacos 配置变化单独说明发布项。没有环境授权时只交付代码和待验收说明，不自动部署、发布配置或调用真实 HTTP。

• 保持变更小而聚焦，遵循目标项目现有命名、分层和格式，不顺手重构无关代码。

• 优先复用现有依赖和公共能力；新增或升级依赖前说明必要性、影响范围和替代方案。

• 不提交依赖目录、构建产物、运行日志、编辑器缓存或本地临时文件；不写入密钥、令牌、真实客户数据或环境特定地址。

• 用户可见文案保持清晰一致；代码标识符使用英文，业务说明和文档可使用中文。

• 仅运行目标项目实际声明的安装、检查、测试和构建命令。每次变更至少验证直接受影响的项目，跨项目变更还要验证对应消费者。

• 修改方法、构造器、组件 Props、函数、接口、DTO 或请求/响应参数时，定向检索全部生产调用、测试调用、Mock、Fixture、契约测试和脚本引用，并同步修改。

• 参数或类型签名变化必须运行会编译测试源码的最小检查；无法验证时明确列出未验证范围。

• 修复缺陷优先增加复现测试；没有现成测试设施时不为小改动引入整套框架，应记录验证步骤和剩余风险。

• UI 变更按受影响范围检查加载、空态、错误态、权限、目标视口和可访问性；Admin/Client 视觉细则查 Admin-Client前端原型还原验收规则.md 和目标应用指引。

• 需求、技术栈或接口未确认时停在可逆设计阶段，不自行作出高成本平台决策。

独立任务与多任务协作

• 跨环境调度必须先核对保存项目 projectId、任务 cwd 与环境登记表三项一致；任一不一致不得下发或执行。禁止把测试环境任务通过绝对路径提示临时改作开发环境任务，反向同样禁止。

• 开发环境全流程任务只使用 开发环境独立任务协作登记.md；测试环境任务只使用 独立任务协作登记.md。两套任务不互相复用，不在两个目录之间复制未提交文件、生成补丁、自动合并或 cherry-pick。

• 普通任务不读取协作登记。只有用户明确指定当前对话为总控，或要求检索历史任务、独立任务或跨对话通信时，才按当前保存项目与 cwd 读取唯一匹配的登记表：开发全流程读 开发环境独立任务协作登记.md，测试环境读 独立任务协作登记.md；不得同时加载两表后混合选取任务。

• 总控在接收任务时必须先做时长评估；预计单一执行链超过 15 分钟时，不得继续由一个任务从定位包办到验收，必须立即拆成可并行的“根因/契约核对、实现修复、回归验收”等独立工作包，并明确每包文件写权限和交付物。优先复用登记表中的长期专项；一次性工作使用内部子代理。该规则不自动授权创建新的用户可见任务。

• 实际执行超过 15 分钟仍未形成可验证交付时，总控必须主动重新拆分或缩小范围，向用户报告当前阻断与并行安排，不得静默等待、继续扩展设计或把非必要兼容、迁移、补偿工作并入主修复链。

• 用户按业务流程逐节点进行人工验收时，总控必须以“当前验收节点”为调度和完成单位，而不是以代码模块或单个 Bug 为单位。收到该节点首个问题后，应立即并行检查前端交互、后端状态与契约、数据/权限前置和自动化验收覆盖；同一节点后续问题统一并入该批次，不得连续串行追加给一个长期专项。

• 节点开发批次至少包含一个唯一实现写入者；跨端时分别下发前端、后端工作包，日常不默认下发节点全链验收专项。只有用户当轮明确通知开始验收、准备部署或执行验收时，才启动验收脚本工作包。能够提前发现的问题由各实现专项在自身定向测试中收口，尽量减少“部署一次、人工发现一个、再部署一次”的循环。

• 当前节点只有在代码门禁通过、相关自动化场景补齐、部署清单明确，并由用户完成真实环境人工验收后才关闭；关闭后再进入下一业务节点。总控需持续维护当前节点的阻断项、已修项和待部署项，不把其他节点的优化混入当前发布批次。

• 检索历史任务只使用本机 ~/.codex/session_index.jsonl、~/.codex/state_5.sqlite、~/.codex/sessions/ 和已知本地任务，不依赖聚合本地、远程主机或云端对话的列表接口。

• 被指定为总控只授权规划、拆解、协调和复用已登记任务，不授权创建新的用户可见独立任务；临时并行默认使用当前对话或内部子代理。

• 创建用户可见独立任务必须由用户在当前轮明确要求，并确认精确数量、稳定职责和所属总控；历史授权以及“继续处理”“拆分”“安排”“并行”等表述不构成创建授权。

• 创建前必须查询登记表并优先复用职责匹配的 task_id；一次性缺陷、排障、部署、临时验收和只为提速的并行工作不得登记为长期任务。

• 创建成功后先登记稳定 task_id、所属总控和唯一长期职责，再下发工作；不自动创建替代任务或归档、解档、恢复、迁移任务。

• 并行前明确文件归属和共享契约。共享导航、根路由、权限初始化和统一 SQL 由已登记的对应总控统一集成；发生重叠时保留现有改动并跨任务协调。