2026-09-30 03:48:33 +00:00
2 changed files with 22 additions and 0 deletions
@@ -0,0 +1,11 @@
+# 经验：Go nil 切片序列化为 JSON null 导致前端 .map 白屏
+
+- 状态：validated（2026-09-30，Agent-System 0.1.0+多租户链）
+- 触发条件/检索词：白屏 / Cannot read properties of null (reading 'map') / 空列表 / 新建项目后页面空 / conversations null / Go nil slice json
+- 根因与来源：backend store 层 `var out []T` 空结果为 nil 切片，encoding/json 编码为 `null`；前端契约声明 `T[]` 并直接 `.map`。2026-09-30 新建项目实测 GET /api/projects/{id}/conversations 返回 `null`。修复提交见 Agent-System-Backend fix/empty-list-json（PR#2）。
+- 下次应做的检查：新增任何列表出口时问一句"空结果返回什么"——对空集合先写回归断言 `json.Marshal(empty) == "[]"`；code review 对 store 层 `var out []` 模式保持警觉。
+- 验证方法与防护：已落实 TestEmptyListsSerializeAsEmptyArrays（store 回归）；修复后实测新项目 conversations/artifacts 均返回 `[]`。建议：前端对网络数据保留 `?? []` 兜底（未落实）。
+- 适用与不适用：适用 Go 后端 + 任何把 JSON 反序列化结果当数组用的前端；不适用已显式区分 null/[] 语义的接口设计。
+- 尚缺证据/防护：前端全局兜底未加；无 CI 级契约测试。
+- 复核人、日期、版本：weichen，2026-09-30，组合 main 36d1393+
+- 替代/退役条件：若引入契约级生成（OpenAPI/TS 类型 + 服务端校验）可吸收本检查，届时退役。
@@ -0,0 +1,11 @@
+# 经验：共享检出的并行现场冲突与 gitlink 钉未推送提交
+
+- 状态：validated（2026-09-30，Agent-System 组合）
+- 触发条件/检索词：工作树有他人未提交改动 / submodule detached HEAD / 父仓 gitlink 指向远端不存在的提交 / upload-pack not our ref / 无法物化 / precheck BUSY
+- 根因与来源：两起同源流程缺陷——1) 多会话共用同一检出与子仓，后到者默认"检出归我"，与在途任务 24 文件 1:1 重叠（侥幸未写）；2) 多租户交付在 detached HEAD 子仓推进父仓 gitlink，9 条链从未推送远端，任何第三方 clone 无法物化（multi-repo"依赖必须可从远端获取"硬规则被违反）。
+- 下次应做的检查：任务首次写前跑 make precheck（BUSY/SYNC 不得写）；看到子仓 detached HEAD 视为他人现场或未建分支；推进 gitlink 前核对该提交已推送到组件远端（ls-remote 可见）。
+- 验证方法与防护：已落实——precheck（含子仓脏/未初始化检测）、zcode PreToolUse 写路径守卫（拦截集成分支/detached/坏分支名）、git pre-commit/commit-msg、Gitea 11 仓分支保护（禁直推+拒绝陈旧候选，负例：直推 pre-receive declined）；正负例证据见 policy/adoption.md 与两份 tool-adaptation 矩阵。
+- 适用与不适用：适用本组合与任何"父仓 gitlink + 组件远端"的多仓开发；不适用单仓单人且无共享检出的场景。
+- 尚缺证据/防护：合入需独立审批人未配置（单人仓库，required_approvals=0 如实登记）；hook 对用户手改 IDE 文件不生效（仅拦 agent 工具调用与 git 操作）。
+- 复核人、日期、版本：weichen，2026-09-30，组合 main 8f7cf2d
+- 替代/退役条件：若迁移到平台级工作区隔离（每任务独立环境）可退役 precheck/写守卫部分；分支保护保留。