2026-07-01 10:50:48 +08:00
|
|
|
|
# Agent 协作说明（Codex / Cloud / Cursor / Claude / 其它 AI 工具通用）
|
2026-06-30 00:27:15 +08:00
|
|
|
|
|
2026-07-01 10:50:48 +08:00
|
|
|
|
本文件供所有在仓库内工作的 AI 编码助手阅读。仓库级开发、测试、发布规范以 [ENGINEERING_WORKFLOW_RULES.md](ENGINEERING_WORKFLOW_RULES.md) 为准；生产发布规范以 [PRODUCTION_RELEASE_RULES.md](PRODUCTION_RELEASE_RULES.md) 为准。
|
|
|
|
|
|
|
|
|
|
|
|
## 必读：分支与发布闸门
|
|
|
|
|
|
|
|
|
|
|
|
1. 新建分支前必须先同步远端主线，推荐执行 `bash scripts/new-branch.sh feature/xxx`。
|
2026-07-01 23:35:55 +08:00
|
|
|
|
2. 分支代码必须先合并进 `main`，确认 `main` 正常后，才允许发布。
|
|
|
|
|
|
3. 发布只能从完整 `main` 打整包，禁止从功能分支、单个 commit、单个修复或局部差异单包发布。
|
|
|
|
|
|
4. 发布前必须确认 CI 已通过，且没有未合并的关键变更。
|
|
|
|
|
|
5. 发布前必须重新检查当前分支是否落后 `origin/main`。
|
|
|
|
|
|
6. 发布来源必须是干净、可追溯的 Git commit。
|
|
|
|
|
|
7. 禁止从脏工作区、detached HEAD、落后主线的分支发布。
|
|
|
|
|
|
8. 发布前必须执行：
|
2026-07-01 10:50:48 +08:00
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
bash scripts/check-release-ready.sh
|
|
|
|
|
|
```
|
2026-06-30 00:27:15 +08:00
|
|
|
|
|
|
|
|
|
|
## 必读：已验证回归守卫（勿轻易覆盖）
|
|
|
|
|
|
|
2026-07-01 10:50:48 +08:00
|
|
|
|
下列行为经过长时间调试验证。删改相关代码前必须先读文档并跑 verify：
|
2026-06-30 00:27:15 +08:00
|
|
|
|
|
|
|
|
|
|
| 主题 | 文档 |
|
|
|
|
|
|
|------|------|
|
|
|
|
|
|
| MindSpace 公开页 `edit_file` 落盘 + 聊天 Finish 不丢消息 | [docs/regression-guards/mindspace-publish-and-chat-finish.md](docs/regression-guards/mindspace-publish-and-chat-finish.md) |
|
2026-07-05 07:57:04 +08:00
|
|
|
|
| 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) |
|
2026-06-30 00:27:15 +08:00
|
|
|
|
|
|
|
|
|
|
索引：[docs/regression-guards/README.md](docs/regression-guards/README.md)
|
|
|
|
|
|
|
|
|
|
|
|
### 改相关文件前必跑
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
npm run verify:mindspace-publish-guards
|
|
|
|
|
|
npm run verify:mindspace-publish-guards:full
|
2026-07-05 07:57:04 +08:00
|
|
|
|
npm run verify:mindspace-page-sync-guards
|
2026-06-30 00:27:15 +08:00
|
|
|
|
```
|
|
|
|
|
|
|
2026-07-01 10:50:48 +08:00
|
|
|
|
发版脚本（`scripts/release-portal-runtime-prod.sh`）在未 `--skip-tests` 时也会执行相关 verify。
|
2026-06-30 00:27:15 +08:00
|
|
|
|
|
|
|
|
|
|
### 受保护的关键路径
|
|
|
|
|
|
|
2026-07-01 10:50:48 +08:00
|
|
|
|
- `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` 才走缓存
|
2026-07-05 07:57:04 +08:00
|
|
|
|
- `mindspace-pages.mjs` - storage 缺失时 HTML 页回退读 workspace `relative_path`
|
|
|
|
|
|
- `mindspace-page-sync-service.mjs` + `server.mjs` - remote 模式也必须 sync public HTML
|
2026-06-30 00:27:15 +08:00
|
|
|
|
|
|
|
|
|
|
代码内搜索 `REGRESSION GUARD` 可定位所有内联说明。
|
|
|
|
|
|
|
2026-07-01 10:50:48 +08:00
|
|
|
|
### 相关单测
|
2026-06-30 00:27:15 +08:00
|
|
|
|
|
|
|
|
|
|
- `mindspace-public-finish-sync.test.mjs`
|
|
|
|
|
|
- `chat-finish-sync.test.mjs`
|
|
|
|
|
|
- `conversation-display.test.mjs`
|
|
|
|
|
|
|
2026-07-05 07:57:04 +08:00
|
|
|
|
### MindSpace page sync + thumbnail
|
|
|
|
|
|
|
|
|
|
|
|
- `mindspace-page-sync-service.test.mjs`
|
|
|
|
|
|
- `mindspace-pages.test.mjs`
|
|
|
|
|
|
|
2026-06-30 00:27:15 +08:00
|
|
|
|
## 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)）
|
|
|
|
|
|
- 生产隔离：[docs/service-isolation-runbook.md](docs/service-isolation-runbook.md)
|
2026-07-01 10:50:48 +08:00
|
|
|
|
- 发版须 Git commit，禁止本机直 `rsync` 到 `103/105`
|
