john
d3239ff292
Ensure page sync runs via pageSyncService in remote mode, fall back to workspace HTML when storage assets are missing, and prevent production Portal from linking to loopback Plaza URLs baked in at build time. Co-authored-by: Cursor <cursoragent@cursor.com>
74 lines
3.4 KiB
Markdown
74 lines
3.4 KiB
Markdown
# Agent 协作说明（Codex / Cloud / Cursor / Claude / 其它 AI 工具通用）
|
||
|
||
本文件供所有在仓库内工作的 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`。
|
||
2. 分支代码必须先合并进 `main`，确认 `main` 正常后，才允许发布。
|
||
3. 发布只能从完整 `main` 打整包，禁止从功能分支、单个 commit、单个修复或局部差异单包发布。
|
||
4. 发布前必须确认 CI 已通过，且没有未合并的关键变更。
|
||
5. 发布前必须重新检查当前分支是否落后 `origin/main`。
|
||
6. 发布来源必须是干净、可追溯的 Git commit。
|
||
7. 禁止从脏工作区、detached HEAD、落后主线的分支发布。
|
||
8. 发布前必须执行：
|
||
|
||
```bash
|
||
bash scripts/check-release-ready.sh
|
||
```
|
||
|
||
## 必读：已验证回归守卫（勿轻易覆盖）
|
||
|
||
下列行为经过长时间调试验证。删改相关代码前必须先读文档并跑 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) |
|
||
|
||
索引：[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
|
||
```
|
||
|
||
发版脚本（`scripts/release-portal-runtime-prod.sh`）在未 `--skip-tests` 时也会执行相关 verify。
|
||
|
||
### 受保护的关键路径
|
||
|
||
- `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
|
||
|
||
代码内搜索 `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)）
|
||
- 生产隔离：[docs/service-isolation-runbook.md](docs/service-isolation-runbook.md)
|
||
- 发版须 Git commit，禁止本机直 `rsync` 到 `103/105`
|