跳转至

2026-05-10 周报

自然周：2026-05-04 至 2026-05-10

本周主线

这一周的核心是把“工具怎么工作”拆成更底层的结构：目录规范如何区分用户资产和运行状态，Claude Code 与 skill 体系如何加载规则、触发流程和降低授权摩擦，Git 如何通过对象重写和公共祖先确定历史边界。表面上是几个不同工具，实质上都是在追问“状态放在哪里、入口在哪里、边界由谁决定”。

第二条线是 AI 协作资产的工程化。无论是 agent notes 的脚本模块化、skill 的 progressive disclosure、description 的触发语义，还是 Superpowers 的 brainstorming → writing-plans → executing-plans 流水线，都在说明：给 AI 用的规则不能只写得完整，还要写得可触发、可分层、可执行，并把高摩擦 IO 封装进脚本。

第三条线是平台概念澄清。飞书云文档、知识库、我的文档库、云盘这些名称混乱，不是单纯记忆问题，而是产品演进叠加 API 权限边界后的结果。对这类平台，必须把内容格式、存储容器和开放 API 管辖范围拆开看。

主题一：本机目录、配置和运行状态的边界

核心脉络

  • 问题起点：从 XDG 与 macOS 目录映射开始，问题是配置、缓存、用户资产和运行痕迹应该放在哪里，以及丢失后的语义差异是什么。
  • 推进关系：随后延伸到 macOS /private 软链接、Claude Code 的两套配置系统、harness 对 AGENTS.md 和 rules 的加载方式。路径不只是文件位置，背后还绑定了兼容性、权限边界、加载时机和生命周期。
  • 最终判断：判断配置和状态归属时，不要先背目录名，而要问三个问题：删掉后用户是否丢资产、运行时是否能自动重建、当前工具到底会不会加载它。路径规范、软链接和配置文件都只是这些语义的外显。

沉淀认知

  • DATA/STATE 判断：XDG_DATA_HOME 存用户资产，XDG_STATE_HOME 存运行痕迹；核心判断不是文件类型，而是删除后用户会不会觉得“我的东西没了”。
  • macOS 不等于 XDG：macOS 原生体系主要使用 ~/Library/Application Support、~/Library/Caches、~/Library/Preferences；许多 CLI 工具在 macOS 上仍会按 XDG 默认路径回退，但这不是系统级遵循 XDG。
  • 只读根卷兼容：Catalina 之后只读的是根系统卷，/etc、/tmp、/var 软链接到 /private 是为了兼容 UNIX 传统硬编码路径，同时把可写数据放到数据卷侧。
  • 配置系统会叠层：Claude Code 同时存在早期 ~/.claude.json 和后来的 .claude/settings.json 分层系统；分析配置生效时要区分扁平全局字段和 local/project/user 的合并优先级。
  • 规则文件不是自动全能：Claude Code harness 记录里，AGENTS.md 本身不会作为运行时 MemoryFile 类型加载；要让内容对 Claude Code 生效，需要软链接到 CLAUDE.md 或通过 include 机制进入实际加载链路。
  • Frontmatter 只看有效字段：.claude/rules/*.md 的 frontmatter 只解析 paths，用于决定无条件加载还是按当前操作文件路径条件注入；不要臆造 enabled、alwaysApply、description 等不存在的控制字段。

适用边界

这组结论适用于排查本机 CLI 工具配置、跨平台目录规范、Claude Code/harness 规则加载和 macOS 系统路径问题。不要把它泛化为“所有工具都应该用 XDG”或“AGENTS.md 永远无效”：不同 agent/harness 的加载规则不同，最终仍要回到当前工具源码或运行时状态验证。

来源

  • 2026-05-07：XDG 规范与 macOS 目录映射
  • 2026-05-07：XDG DATA 与 STATE 边界
  • 2026-05-07：macOS /private 软链接设计原理
  • 2026-05-07：macOS 与 XDG 规范
  • 2026-05-07：Claude Code 配置系统架构
  • 2026-05-10：Claude Code harness 配置加载

主题二：Skill 与 AI 工作流的工程化

核心脉络

  • 问题起点：先从 agent notes 脚本模块化和减少 AI 授权摩擦入手，发现如果 skill 让 AI 手工执行大量 IO 步骤，流程会被权限确认切碎，执行质量也难稳定。
  • 推进关系：随后对 skill 内容分层、description 写法、素材分析方式和质量审查做了系统校准；Superpowers 流水线则提供了更完整的从想法到 spec、计划、执行的阶段化模型。
  • 最终判断：skill 不是“把流程写进 Markdown”这么简单。好的 skill 要把高频硬约束留在正文，把查阅型细节下沉到 references，把 IO 收进脚本，把 description 限定为触发条件，并在写完后做删改审查。

沉淀认知

  • Facade 要薄：入口脚本应只做调度，把参数解析、环境检查、日期、Markdown 渲染、git 操作等拆到 lib/ 模块；这样脚本既可读，也方便独立测试。
  • IO 应脚本化：skill 中多步读写文件、拼路径、提交 git 的操作会显著增加授权摩擦；把这些 IO 封装成一条脚本命令，AI 只负责传入清晰参数，流程更稳定。
  • 前置检查内聚：环境变量是否设置、目标路径是否存在且为目录，应由脚本检查并给友好错误；不应依赖 AI 临场写 bash，也不应擅自自动创建用户未确认的目录。
  • 正文承载硬约束：SKILL.md 应保留每次执行都要对照的硬约束、生成流程和速查索引；词库、模式库、画像等偶尔查阅的材料应进入 references/，按需读取。
  • Description 只管触发：skill description 字段如果总结内部流程，模型可能只按描述执行而跳过正文；它应该只描述“什么时候使用”，不承载执行步骤。
  • 素材先读完再提炼：为写作 skill 提炼风格画像时，局部读取容易把标志性结构误判成偶然现象；完整阅读后再抽象，才能识别真正稳定的风格约束。
  • 删改也是质量审查：skill 审查不只是补内容，更要删除重复、错引、臆造高频词和逻辑矛盾；对 AI 规则资产来说，不准确的规则比缺少规则更危险。
  • 流水线分阶段：Superpowers 把 brainstorming、writing-plans、executing-plans 串成阶段流，每一步产物都成为下一步输入；这比在一个大 prompt 里混合需求、方案和执行更可控。

适用边界

这组结论适用于创建、重构和审查 AI skills、agent 工作流脚本、写作画像和自动化笔记工具。它不意味着所有项目都要拆成复杂框架；当脚本很短且没有复用需求时，过度模块化反而会增加理解成本。判断标准仍是职责是否混杂、授权摩擦是否高、规则是否会反复执行。

来源

  • 2026-05-07：Superpowers 技能流水线
  • 2026-05-10：模块化重构
  • 2026-05-10：skill 设计：减少 AI 授权摩擦
  • 2026-05-10：Node.js 模块化：facade + lib 分层
  • 2026-05-10：Skill 内容分层：总分结构与 Progressive Disclosure
  • 2026-05-10：Skill description 的反面教材：不要总结流程
  • 2026-05-10：Skill 分析素材的正确方法：先读完再提炼
  • 2026-05-10：Skill 内容的质量审查：删比加更重要

主题三：Git 历史边界与审查基准

核心脉络

  • 问题起点：Git commit 时间重写先暴露出一个事实：时间戳是 commit object 内容的一部分，改时间不是改 metadata，而是生成新对象。
  • 推进关系：git rebase -i edit、JGit CommitBuilder、/review 的 merge-base 基准选择进一步说明，Git 的很多高级行为都建立在对象不可变和 DAG 公共祖先上。
  • 最终判断：分析 Git 行为时要回到底层对象模型。commit ID 由内容寻址决定，rebase 是一串 cherry-pick，review 基准来自公共祖先；理解这些后，hash 重生、环境变量作用域和无基准分支时报错都变得可解释。

沉淀认知

  • 时间戳属于对象：author date 和 committer date 都写在 commit object 内；完整重写时间必须同时处理 author 和 committer，否则 git log 视角和实际提交者时间会不一致。
  • 改祖先会重生子孙：rebase edit 模式本质是 cherry-pick 链，amend 某个 commit 会生成新 object ID，后续 commit 以新 ID 为 parent 继续重放，因此子孙 hash 必然全部变化。
  • 环境变量有进程边界：GIT_COMMITTER_DATE 只对当前 shell 及其子进程生效；在 rebase exec 行里设时间不可靠时，应该在 edit 暂停点手工设置环境变量并执行 git commit --amend。
  • JGit 同样是重建对象：用 RevWalk 解析旧 commit，再用 CommitBuilder 保持 tree、parent、message 不变，仅替换 PersonIdent 时间，最后 insert 新对象；这和 CLI amend 的本质一致。
  • Review 基准靠 merge-base：无参数 /review 不是审查全部历史，而是找基准分支与当前分支的最近公共祖先，再审查分叉后的 diff。
  • 没有公共祖先就失败：git merge-base A B 找的是最近公共祖先，不是“分支创建点”；完全独立历史没有公共祖先时，没有可靠 diff 基准，命令失败是合理结果。

适用边界

这些结论适用于解释本地 Git 历史重写、JGit 提交对象构造、PR 前审查基准和 /review 命令行为。不要把时间重写当成普通修补操作：一旦 commit 已推送或被他人基于其开发，重写会改变共享历史，需要先确认协作影响。

来源

  • 2026-05-09：Git commit 时间重写原理
  • 2026-05-10：Claude Code /review 命令机制
  • 2026-05-10：git merge-base 原理

主题四：飞书云文档的产品与 API 分层

核心脉络

  • 问题起点：飞书里“云文档”“知识库”“云盘”“我的空间/共享空间”“我的文档库”经常混用，导致不知道该用哪个 lark skill 或 API。
  • 推进关系：通过把内容创作工具和存储管理工具拆成两个正交维度，再结合云盘旧称和产品演进历史，命名混乱可以被解释为新产品形态叠加旧概念，而不是用户记错。
  • 最终判断：处理飞书文档问题时，要先判断对象是内容格式还是容器位置。Wiki API 管结构，Doc API 管内容，Drive API 管跨容器文件管理；不确定位置时先搜索，再按 token 和容器类型切换到对应能力。

沉淀认知

  • 两维拆分：飞书云文档体系可拆成内容创作工具和存储管理工具。前者包括 Doc、Sheet、Base、Slides 等文件格式，后者包括 Wiki、我的文档库、云盘等容器。
  • Wiki 节点不是内容本身：知识库节点本质上指向某种文档格式；Wiki API 更偏目录树、节点和成员管理，真正读写正文还要回到 Doc/Sheet/Base 等内容 API。
  • 云文档一词三用：“云文档”既是产品线品牌，又会被口语化指具体文档格式，还出现在开放平台 Docs API 分类中；不拆语境就会误判 API 边界。
  • 云盘权力更大：Drive API 能跨容器做文件级管理，因此和 wiki/doc 权限存在交叉；实际操作时应按任务目标选择，不是看到文档就只用 Doc API。
  • 旧名解释混乱：“我的空间”“共享空间”更像云盘下个人文件夹和共享文件夹的旧称或俗称，不是独立产品；当前更稳的顶层容器理解是知识库、我的文档库、云盘。
  • 演进导致叠名：云盘、知识库、我的文档库大概率是随协作和个人知识管理需求逐步分化出来的产品形态；老名称保留和新模块加入共同造成了今天的概念重叠。

适用边界

这组认知适用于飞书文档读取、权限判断、API/skill 路由和产品概念解释。由于飞书产品和开放平台命名会演进，涉及当前 API 能力、权限 scope 或具体入口时，仍应以当前文档或实际 CLI/API 返回为准。

来源

  • 2026-05-10：飞书云文档体系架构
  • 2026-05-10：飞书云盘内部结构澄清
  • 2026-05-10：飞书云文档产品演进历史

主题五：系统设计名词和自我反馈的边界

核心脉络

  • 问题起点：缓存穿透、击穿、雪崩三个中文名非常接近，容易让学习者把精力放在背名词上，而不是理解它们分别怎样保护 DB。
  • 推进关系：同一天的“反思与自我怀疑边界”把问题从技术记忆扩展到学习方法：忘了再查并不可怕，真正需要避免的是把具体知识缺口滑向人格否定。
  • 最终判断：技术学习里要区分“问题机制”和“自我评价”。系统设计能力来自识别请求如何绕过缓存、热点如何集中打到 DB、整体缓存层如何失效；反思只需要推进到改进方法，不需要继续滑向自我消耗。

沉淀认知

  • 穿透是不存在：缓存穿透指请求的数据本来不存在，缓存无法挡住它，请求反复打到 DB；常见处理是布隆过滤器提前拦截，或缓存空值。
  • 击穿是热点过期：缓存击穿指热点 key 过期瞬间大量请求集中访问 DB；处理重点是让一个请求回源重建，其他请求等待，或对热点 key 采用逻辑不过期等策略。
  • 雪崩是整体失守：缓存雪崩是大量 key 同时过期或 Redis 整体不可用，导致后端系统承压；处理方向是过期时间随机化、集群高可用、限流和降级。
  • 名词不是能力本身：这三个词在中文技术圈很工整，但英文社区未必有一一对应的常用术语；记不住名词不是关键，能识别“怎么保护 DB”才是系统设计能力。
  • 反思应有停止点：反思指向具体改进，找到方法就停；自我怀疑会从问题滑向“我这个人不行”，它不产生行动方案，只消耗注意力。

适用边界

缓存三分法适合面试、系统设计讨论和排查缓存层保护失效问题，但真实线上事故可能同时包含穿透、击穿和雪崩，不要为了套名词而忽略实际流量、key 分布和降级策略。反思边界适用于学习和复盘，不等于回避错误；错误仍要被定位、修复和验证。

来源

  • 2026-05-06：缓存雪崩 vs 击穿 vs 穿透
  • 2026-05-06：反思与自我怀疑的边界

其他杂项

  • 输入法卸载路径：macOS 输入法列表里删除按钮灰色时，可以从 /Library/Input Methods/ 删除对应源文件后重启来完成卸载。这个点更像具体操作经验，不足以独立成章，但适合作为 macOS 系统路径认知的补充。来源：2026-05-07，XDG 规范与 macOS 目录映射。
  • skills CLI update 不是内容 diff：skills update 通过 GitHub Trees API 获取 skill 文件夹 tree SHA，并和 ~/.agents/.skill-lock.json 里的 skillFolderHash 比较；local/git/well-known 等 source 类型可能被跳过。排查 skill 未更新时，应先确认 source 类型和 lock 文件记录。来源：2026-05-09，skills CLI 内部机制。
  • skills remove 可能残留锁记录：正常 remove 会清理 lock 条目，但手动删目录、旧 bug 或中断可能留下脏数据；目前没有内置 check/clean，只能手动对比 lock JSON 和 ~/.agents/skills/。来源：2026-05-09，skills CLI 内部机制。
  • 安装目录名来自 frontmatter：skills add 的目录名优先来自 SKILL.md frontmatter 的 name，再经过 sanitize；只有 name 为空才回退到路径 basename。不要默认认为仓库目录名就是安装后的 skill 名。来源：2026-05-09，skills CLI 内部机制。

修正报告

  • 无