Files

T

john d3239ff292 fix: MindSpace remote sync, thumbnail fallback, and Plaza URL guards

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>

2026-07-05 07:57:04 +08:00

3.4 KiB

Raw Blame History

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

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

必读：分支与发布闸门

新建分支前必须先同步远端主线，推荐执行 bash scripts/new-branch.sh feature/xxx。
分支代码必须先合并进 main，确认 main 正常后，才允许发布。
发布只能从完整 main 打整包，禁止从功能分支、单个 commit、单个修复或局部差异单包发布。
发布前必须确认 CI 已通过，且没有未合并的关键变更。
发布前必须重新检查当前分支是否落后 origin/main。
发布来源必须是干净、可追溯的 Git commit。
禁止从脏工作区、detached HEAD、落后主线的分支发布。
发布前必须执行：

bash scripts/check-release-ready.sh

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

下列行为经过长时间调试验证。删改相关代码前必须先读文档并跑 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

索引：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

发版脚本（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 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）
生产隔离：docs/service-isolation-runbook.md
发版须 Git commit，禁止本机直 rsync 到 103/105

3.4 KiB Raw Blame History Unescape Escape