2026-05-17 周报

自然周：2026-05-11 至 2026-05-17

本周主线

这一周的主线不是单一项目推进，而是围绕“工具真实行为如何被建模”展开：Git 的对象模型、worktree/submodule 元数据、merge 线性化、revision 术语，最终都指向同一个结论：不要只按命令表象理解工具，要回到对象、指针、元数据目录和 hash 输入这些底层事实。

第二条主线是 AI Agent 的指令与上下文机制。OpenAI、Anthropic、Claude Code、Codex、skills CLI 分别在指令层级、传输结构、上下文注入、运行环境检测上采用了不同策略。它们看似都在解决“让 Agent 正确服从指令”，实际分成了权限裁决、物理隔离、缓存稳定性和非交互自动化几个问题。

第三条主线是工程排障中的构建边界意识。微前端和 code split 的生产异常说明，“本地 dev 正常”不能证明模块实例、加载边界和请求守卫在生产里也一致。排障时要先区分请求失败、请求未发出、状态实例分裂这几类完全不同的问题。

最后，HTML 作为 AI 协作交付格式补充了一个表达层面的判断：当目标是帮助人快速理解复杂信息时，交付物不一定应停留在 Markdown。自包含 HTML 能把布局、视觉编码和轻量交互都纳入单文件交付，适合 AI 生成可直接打开的高信息密度工具。

主题一：Git 的对象模型、元数据边界与历史线性化

核心脉络

问题起点：最初是在理解 submodule、subtree、worktree、merge、rev 这些 Git 概念时，发现很多术语表面相近，但底层对象模型完全不同。
推进关系：submodule 和 subtree 的区别，从“都是把外部代码放进来”推进到“gitlink 外键 vs 普通 tree 内容”；worktree 和 submodule 都使用 gitfile，但一个依赖 commondir 共享对象库，一个把仓库数据放在 .git/modules/ 下独立管理；merge 线性化则进一步把视角转到 commit DAG 和 parent 指针。
最终判断：Git 的高层命令只有回到对象、tree entry、parent、gitdir、commondir、index 和 refs 才能解释清楚。生成文档或做历史改写时，不能凭命令名称类比推断，尤其是 worktree 命名、分支互斥、merge commit 是否含内容这类细节，必须用实际命令验证。

沉淀认知

gitlink 外键：submodule 在父仓库 tree 中是 mode 160000 的 gitlink，存的是另一个仓库的 commit SHA，所以 Git/JGit 都需要特殊处理；subtree 只是把外部仓库内容展开成普通 blob/tree，历史整合靠脚本组合完成，不引入特殊对象类型。
元数据分层：.git、gitdir、commondir 不是同一概念；.git 是工作树入口，gitdir 指向独占元数据目录，commondir 再指向共享数据目录。worktree 需要共享 objects/refs/config，但 HEAD、index、ORIG_HEAD、MERGE_HEAD、reflog 等操作上下文必须独占。
submodule 解耦：submodule 把真实 Git 数据放进父仓库 .git/modules/，工作树中的 .git 只是 gitdir 指针。这样父仓库切换分支、deinit/init 或重建子模块工作树时，不会把子模块仓库数据一起删掉。
双层配置：.gitmodules 是版本受控的项目声明，.git/config 是本地激活状态。git submodule init 只是把声明复制到本地配置，不做网络下载；真正 clone 和 checkout 发生在 git submodule update。
worktree 命名：worktree 元数据 id 来自目标路径 basename，不是分支名；同一分支不能同时绑定多个 worktree。路径名冲突才会触发递增后缀，分支名重复不会进入“自动改名”流程，因为 Git 会先拒绝。
线性化原则：merge commit 通常只是 DAG 合流节点，本身没有额外代码 diff；线性化历史时可以 cherry-pick 两侧实际内容 commit，跳过无冲突解决内容的 merge commit。cherry-pick 后 hash 变化，是因为 commit hash 输入包含 parent SHA，而不是 tree 内容一定变了。
revision 语义：Git 的 rev 是 revision，指 commit 级代码快照；version 更偏用户可见的发布版本。中文日常写“版本”通常已经够用，只有需要强调 VCS 粒度时再写“修订版本”。

适用边界

这些结论适用于解释 Git 对象模型、编写实现文档、设计历史线性化流程和排查 worktree/submodule 元数据问题。不能把“merge commit 可跳过”泛化到所有 merge：如果 merge commit 包含冲突解决或手工改动，它就有独立内容，不能直接忽略。也不能把 subtree 当成 Git 核心对象类型，它只是普通文件树和历史的脚本化整合。

来源

2026-05-11：Git Submodule 与 Subtree 的对象模型差异
2026-05-11：Git Worktree 的 id 命名与分支互斥
2026-05-11：Git Submodule 内部机制
2026-05-13：Git merge 线性化原理
2026-05-13：Git revision 术语理解

主题二：Agent 指令层级、上下文注入与非交互 CLI

核心脉络

问题起点：这一组认知都在回答同一个问题：Agent 怎么知道哪些指令更高优先级、哪些上下文应该稳定保留、什么时候应该自动跳过交互。
推进关系：OpenAI 的 developer/root/system/guideline 讨论的是指令冲突裁决；Anthropic 的 Constitution 和 Claude API 结构更强调主体判断与传输层隔离；Claude Code 与 Codex 的上下文注入则落到具体实现：缓存、prepend、thread_id、compaction 和文件变更通知。
最终判断：Agent 可靠性不是只靠“写好 prompt”。它同时依赖指令层级语义、API 消息结构、上下文缓存策略、工具 schema 稳定性，以及 CLI 对非 TTY/Agent 环境的自动识别。

沉淀认知

developer 分层：OpenAI 的 developer role 主要解决语义归属和冲突优先级，不是推理能力升级。拆分后平台指令、开发者指令和用户指令可以按 Root/System/Developer/User/Guideline 层级裁决。
Root/System 区分：Root 更像不可覆盖的基础约束，System 是 OpenAI 按产品表面和用户特征动态注入的指令。这个拆分让“普适禁止”和“场景配置”不再挤在同一层。
Guideline 轻约束：Guideline 可以被上下文隐式覆盖，所以适合放偏好和默认风格，不适合承载安全边界或业务硬约束。
Anthropic 路径：Claude 的 system prompt 是顶层参数，不混在 messages 数组里；这从传输结构上减少用户输入伪装成系统指令的空间。Anthropic 的 Constitutional AI 更偏整体判断，不是 OpenAI 那种严格权限链模型。
CLAUDE.md 缓存：Claude Code 首轮通过 memoize 读取 CLAUDE.md，后续轮次不会重新读盘；文件变化通过 edited_text_file attachment 通知模型，但不会立即替换已缓存的系统上下文。真正刷新要等 compaction 或 /clear 同时清两层缓存。
上下文注入差异：Claude Code 把用户上下文 prepend 到消息头部，并用内容冻结和 thread_id cache key 保持缓存稳定；Codex 的实现路径不同，但共同目标都是让同一会话的前缀尽量稳定。
CLI 自动静默：-y/--yes 可以从 Agent 检测和非 TTY 环境中推导出来，但仍应保留显式 flag，作为脚本可读性、未识别 Agent 容错和社区约定兼容的入口。

适用边界

这些判断适用于设计 Agent CLI、排查项目指令不生效、解释 prompt injection 防御和分析上下文缓存。不要把 OpenAI 与 Anthropic 的模型简化成“谁更高级”：两者解决的是不同层面的约束建模。也不要把文件变更通知误认为热更新系统指令；在 Claude Code 里，通知只是新增上下文，缓存的 memory 内容不会原地替换。

来源

2026-05-11：CLI --yes 标志可从运行环境推导
2026-05-11：skills CLI 的 Agent 检测与非交互安装机制
2026-05-12：OpenAI Model Spec 指令层级
2026-05-12：Anthropic vs OpenAI 指令层级哲学差异
2026-05-12：cc 的 CLAUDE.md 缓存与热更新机制
2026-05-12：cc 与 Codex 的上下文注入方式对比

主题三：生产构建排障中的模块边界意识

核心脉络

问题起点：问题表现为本地 dev 正常、生产环境异常，且某些 hook 能感知状态变化，另一些 hook 一直停留在旧状态。
推进关系：排查从网络和接口转向“请求是否真的发出”，再从 ready/enabled 守卫转向模块实例是否一致。最终线索落在 Vite dev 与 build 的差异：dev 中模块通常在单上下文执行，build 后 lazy 路由会被拆成独立动态 chunk。
最终判断：生产异常不能只沿着接口、权限、网络排查。只要存在 React.lazy()、微前端、动态 import 或模块级 store，就必须把 code split 造成的模块顶层重复执行、单例分裂和状态不同步纳入第一轮假设。

沉淀认知

lazy 破坏单例：模块级 createStore() 如果被主 bundle 和 lazy chunk 分别执行，就会产生两个独立 store。主布局看到的状态变化不会自动同步到 lazy 页面。
定位信号：同一状态在 AppLayout 和 lazy 页面里读到不同值，比接口错误更直接地指向模块边界问题；这说明不是“数据没回来”，而是“读数据的实例不是同一个”。
先判请求状态：Network 面板完全没有请求，代表 JS 层 ready/enabled 守卫拦截；这时要拆开每个守卫条件打 log，而不是继续查 4xx/5xx、网关或认证。
根治优先级：如果页面代码很小、性能瓶颈在 vendor 包，去掉 lazy 静态 import 比 window 注册表补丁更干净。补丁能救急，但不能消除 code split 触发的模块边界风险。

适用边界

这个模式适用于 Vite、React.lazy、微前端、动态 import 和模块级单例混用的前端项目。它不意味着所有生产异常都是 code split，也不意味着禁止 lazy；当页面体积大、状态不依赖模块级单例或单例被提升到稳定共享层时，lazy 仍然合理。关键是先确认状态实例是否跨 chunk 保持同一引用。

来源

2026-05-12：微前端+code split 模块级单例陷阱
2026-05-12：dev 正常生产异常的排查思路

主题四：HTML 作为 AI 协作的高密度交付格式

核心脉络

问题起点：在与 AI Agent 协作时，Markdown 虽然方便，但对复杂信息的表达仍是线性文字流，难以承载并排比较、视觉层级和交互探索。
推进关系：HTML 的优势不只是“更好看”，而是能把空间布局、颜色、大小、状态和交互都变成信息编码方式。自包含 HTML 又降低了 AI 生成和用户打开的工程门槛。
最终判断：当交付目标是帮助人更快理解复杂方案、流程、配置或对比关系时，自包含 HTML 可以比 Markdown 更适合作为最终产物。它把“说明某种表达方式有效”变成“直接让读者体验这种表达方式有效”。

沉淀认知

信息密度：HTML 能用布局和视觉编码表达结构关系，读者不用只靠段落顺序还原上下文；这对方案对比、设计系统、流程图和配置编辑器尤其有效。
自包含模式：单个 .html 内嵌 CSS/JS，浏览器直接打开，避免依赖安装、构建配置和运行环境漂移，正好匹配 AI 生成交付物的可靠性边界。
自证表达：交互式页面可以先让读者体验信息消费效率，再解释论点。这是技术写作里 “show, don't tell” 的强形式。

适用边界

HTML 适合高信息密度、需要视觉比较或轻交互的交付物；不适合所有记录场景。需要长期 diff、纯文本检索、版本审阅或被 MkDocs/静态站直接纳入知识库的内容，Markdown 仍然更稳。自包含 HTML 也不应扩展到复杂应用，一旦需要多模块状态、构建链路或后端接口，就应回到正常工程结构。

来源

2026-05-13：HTML 作为 AI 协作交付格式

其他杂项

无。本周所有日报 topic 都可以自然并入上述四个主题，没有需要单独放入杂项的残余内容。

修正报告

worktree 命名纠偏：日报中已经记录了对早前文档的修正：worktree 元数据 id 不是取分支 basename，而是取目标路径 basename；同一分支也不能创建多个 worktree。周报正文采用修正后的说法。涉及来源：2026-05-11「Git Worktree 的 id 命名与分支互斥」。