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

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

## 必读：分支与发布闸门

生产 `103` 发布还必须完整遵守 [docs/production-release-guardian.md](docs/production-release-guardian.md)。该文档定义 160 个场景族、合法 `not_applicable` 条件、Gate report 和发布硬阻断规则；自动守门员尚未完整落地前，不得声称已满足新发布条件。

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

```bash
bash scripts/check-release-ready.sh
```

12. `check-release-ready.sh` 只是源码闸门，不代表业务场景闸门通过；生产发布还必须取得与同一 commit、同一 runtime artifact 绑定的完整 Gate report。

## 必读：历史分支处置登记

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

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

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

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

索引：[docs/regression-guards/README.md](docs/regression-guards/README.md)

### 改相关文件前必跑

```bash
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-public-finish-sync.test.mjs`
- `chat-finish-sync.test.mjs`
- `conversation-display.test.mjs`

### 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](README.md)）
- Page Data API：见 [docs/page-data-api-usage.md](docs/page-data-api-usage.md)；改动相关路径后执行 `npm run verify:page-data`
- 生产隔离：[docs/service-isolation-runbook.md](docs/service-isolation-runbook.md)
- 发版须 Git commit，禁止本机直 `rsync` 到 `103/105`