Agent 协作说明（Codex / Cloud / Cursor / Claude / 其它 AI 工具通用）

本文件供所有在仓库内工作的 AI 编码助手阅读。仓库级开发、测试、发布规范以 ENGINEERING_WORKFLOW_RULES.md 为准；生产发布规范以 PRODUCTION_RELEASE_RULES.md 为准。

必读：单一开发分支硬闸门

以下规则适用于 Codex、Cursor、Cloud、Claude、人工操作及其它任何自动化工具，不得绕过：

除 main 外，同一时间只允许存在一个尚未闭环的本地开发分支；同时只允许一个开发 worktree。已有开发分支或开发 worktree 时，严禁通过 git switch -c、git checkout -b、git worktree add、IDE、云端任务或脚本再创建第二个分支/worktree。
当前开发分支未完成全部改动、仍有未提交文件、仍有未推送提交、尚未并入 main、其提交尚未进入 origin/main，或该分支/worktree 尚未删除时，Codex、Cursor 及其它 Agent 一律不得创建新分支。不得以并行开发、临时修复、试验、续作、PR、冲突处理或“先开分支再说”等理由例外处理。
一个开发分支必须完整闭环后才能开始下一分支，顺序固定为：完成开发 → 执行对应测试/verify → 提交全部应交付改动 → 取得规则要求的明确批准 → 合并进本地 main → 推送并确认远端 origin/main 已包含该分支提交 → 删除开发 worktree（如有）→ 删除本地开发分支 → 删除同名远端开发分支（如曾创建）。
新建分支前必须先执行只读检查，确认工作区干净、当前位于已同步的 main、不存在其它本地开发分支、不存在其它开发 worktree，且上一分支的 HEAD 已是 origin/main 的祖先。任一检查不满足，必须停止并继续完成或清理上一分支，禁止创建新分支。
分支闭环中的 push、合并 main、删除分支等动作仍分别受本文的测试、明确批准和发布闸门约束；本节只增加“未闭环不得开新分支”的硬阻断，不构成对这些动作的预先授权。

必读：分支与发布闸门

生产 103 发布还必须完整遵守 docs/production-release-guardian.md。该文档维护 187 个完整回归场景族；常规发布执行 16 项核心场景加自动影响域场景，高风险或无法识别影响范围时自动升级为全量 Gate。不得手工删减选择结果或绕过 Gate report 硬阻断。

新建分支前必须先同步远端主线，推荐执行 bash scripts/new-branch.sh feature/xxx。
在“修复 bug / 开发中”阶段，默认只允许本地修改、本地运行、本地测试；没有用户明确批准，不允许 git push、不允许生成或发布任何 103 相关 runtime/artifact、不允许合并或并入 main、不允许触发任何生产动作。
“明确批准”必须是针对下一步动作本身的直接确认，不能把“继续处理”“先看看结果”之类表述解释成 push、发版、合并 main 的授权。
即使代码已经改完，也必须先完成与本次改动对应的测试或 verify，并在测试后再次确认，才能决定是否进入 push、合并 main、103 构建或发布等下一步。
分支代码必须先合并进 main，确认 main 正常后，才允许发布。
发布只能从完整 main 打整包，禁止从功能分支、单个 commit、单个修复或局部差异单包发布。
发布前必须确认 CI 已通过，且没有未合并的关键变更。
发布前必须重新检查当前分支是否落后 origin/main。
发布来源必须是干净、可追溯的 Git commit。
禁止从脏工作区、detached HEAD、落后主线的分支发布。
发布前必须执行：

bash scripts/check-release-ready.sh

check-release-ready.sh 只是源码闸门，不代表业务场景闸门通过；生产发布还必须取得与同一 commit、同一 runtime artifact 绑定、且可从 Git diff 重现选择结果的风险分层或全量 Gate report。

必读：历史分支处置登记

复用、合并、cherry-pick 或清理任何旧本地分支/worktree 前，必须先检查 docs/branch-disposition.md。登记为“禁止再次引用”的分支只能用于只读追溯，不得作为开发基线、合并来源、cherry-pick 来源或发布来源；必须以最新 origin/main 为准。

必读：已验证回归守卫（勿轻易覆盖）

下列行为经过长时间调试验证。删改相关代码前必须先读文档并跑 verify：

主题	文档
MindSpace 公开页 `edit_file` 落盘 + 聊天 Finish 不丢消息	docs/regression-guards/mindspace-publish-and-chat-finish.md
MindSpace remote 页面 sync + storage 缺失缩略图 fallback	docs/regression-guards/mindspace-remote-page-sync-and-thumbnail.md
Page Data 数据集注册、绑定与交付验收	docs/regression-guards/page-data-delivery-contract.md
H5 SSE 断线续播、Portal/Goose 游标映射与 Finish 终态恢复	docs/regression-guards/h5-session-stream-replay.md
Memory V2 候选表初始化与生命周期灰度作用域	docs/regression-guards/memory-v2-candidate-and-lifecycle.md

索引：docs/regression-guards/README.md

改相关文件前必跑

npm run verify:mindspace-publish-guards
npm run verify:mindspace-publish-guards:full
npm run verify:mindspace-page-sync-guards
npm run verify:h5-session-patches

发版脚本（scripts/release-portal-runtime-prod.sh）当前在不跳过测试时会执行相关 verify；生产 103 发布禁止使用 --skip-tests，并且仍须通过完整生产发布守门员。

受保护的关键路径

mindspace-public-finish-sync.mjs - edit_file 必须 materialize 到 public/*.html
chat-finish-sync.mjs - Finish / UpdateConversation 必须 merge，禁止盲覆盖
conversation-display.mjs + src/utils/message.ts - 用户消息不得展示 routing/skill 内部前缀
src/hooks/useTKMindChat.ts - syncSessionMessages merge + 重试
server.mjs - session snapshot 需 hint_mc 且 hint_ua 才走缓存
mindspace-pages.mjs - storage 缺失时 HTML 页回退读 workspace relative_path
mindspace-page-sync-service.mjs + server.mjs - remote 模式也必须 sync public HTML
session-stream.mjs + session-stream-store.mjs + tkmind-proxy.mjs - Portal replay ID 不得直接作为 Goose Last-Event-ID

代码内搜索 REGRESSION GUARD 可定位所有内联说明。

MindSpace page sync + thumbnail

mindspace-page-sync-service.test.mjs
mindspace-pages.test.mjs

Cursor 专用规则（其它工具请读上文文档）

Cursor 额外加载：.cursor/rules/mindspace-publish-chat-finish-guards.mdc
内容与 docs/regression-guards/mindspace-publish-and-chat-finish.md 一致，仅为 Cursor 在编辑相关文件时自动提示。

仓库惯例

本地开发：pnpm dev（见 README.md）
Page Data API：见 docs/page-data-api-usage.md；改动相关路径后执行 npm run verify:page-data
生产隔离：docs/service-isolation-runbook.md
发版须 Git commit，禁止本机直 rsync 到 103/105

7.7 KiB Raw Blame History Unescape Escape