2026-05-10 学习日志

今日主题

skill 里让 AI 执行多步细碎操作（读 JSON、拼字符串、手动写文件、git commit）会导致每步都需要授权，摩擦极高；正确做法是把所有 IO 操作收进一个脚本，AI 只调一条命令。
环境前置检查（变量是否设置、路径是否存在且是目录）应在脚本内完成并报友好错误，不能依赖 AI 自己去跑 bash 判断，也不能自动创建目录——目录应由用户明确创建。

一个入口脚本（facade）如果同时承担参数解析、IO、业务逻辑、外部命令调用，会又臭又长难以维护；正确做法是按职责拆到 lib/ 下各模块（args、env、date、inbox、markdown、git），facade 只做调度，每个模块只做一件事。

AGENTS.md 不会被 harness 运行时加载到上下文。MemoryFile 类型只有 User/Project/Local/Managed/AutoMem/TeamMem，没有 AgentsMd 类型。AGENTS.md 只在 /init 命令的 prompt 中出现，作为生成 CLAUDE.md 的素材来源。要让 AGENTS.md 生效需通过软链接指向 CLAUDE.md 或用 @include 指令引用。
.claude/rules/*.md 的发现逻辑：fs.readdir 递归所有子目录，仅过滤 .md 后缀，无数量上限、无排序。Managed/User/Project 各有自己的 rules 目录且路径规则不同，Local 类型没有 rules 目录。
rules/.md 的 frontmatter 只解析一个字段 paths。它接受 glob 控制该 rule 是无条件加载（未写 paths 或 paths 只有 *）还是条件加载（写了具体 glob，仅在当前操作文件路径匹配时才注入）。没有 enabled/alwaysApply/description 等字段。Frontmatter 块解析后会被剥离，只发送 body 给模型。

Skill 的正文（SKILL.md）应只保留执行时直接用的内容——硬约束、生成流程、速查索引；查阅型的细节（词库、模式库、详细画像）下沉到 references/ 文件，按需读取。这样 SKILL.md 保持 < 500 行，运行时 token 消耗可控。
判断哪些内容应下沉的标准：生成草稿时是否需要逐字对照？是 → 留在正文；只是偶尔查阅 → 放 references/。硬约束（13条规则）和生成流程（Step1-5）必须留在正文，因为每次生成都要逐条检查。

description 字段只描述触发条件（Use when...），绝不总结 Skill 内部的执行流程。原因：Claude 读到 description 后可能直接按描述执行而跳过正文，导致只做了一步而非完整流程。测试验证：将 description 改成只说触发条件后，Claude 才正确读取正文并执行完整的两阶段流程。

为博客写作 Skill 提炼风格画像时，只读前100行 vs 完整阅读的差距极大。完整阅读才能发现：【方括号】是全文体标志（不是偶尔用的修辞）、引用块 > 有特殊用法（标注源码路径/八股文提示）、酱紫是标志性口癖而非错别字、类比 mysql 是整体写作策略而非单纯词汇。这些细节在开头100行根本看不到。

Skill 写完后必须做删改审查，不只是加内容。常见问题：同一条规则在两个章节重复说（冗余）；例句引用的实际位置与标注的不符（如把开头的句子标成结尾）；从未在原文出现过的词汇被臆造成「高频词」（如「嗡嗡的」「头大」）；同一个概念描述有逻辑矛盾（如「然而」出现两次）。删掉不准确的比加新内容更重要。

飞书云文档整体架构分两个正交维度：内容创作工具（文件格式）和存储管理工具（容器）。内容创作工具包括文档(Doc)、表格(Sheet)、多维表格(Base)、幻灯片(Slides)、思维笔记；存储管理工具包括知识库(Wiki,组织级目录树+成员管理)、我的文档库(个人级)、云盘(Drive,传统文件夹+上传下载)。知识库节点本质是某种文档格式，Wiki API管结构，Doc API管内容。
"云文档"一词三用是概念混乱根源：既是产品线品牌名、又指具体文件格式(文档)、还是开放平台API分类名(Docs API)。云盘Drive API权力最大，能跨容器管理文件，所以lark-drive和lark-wiki权限有交叉。实用原则：不确定在哪的文件先用lark-doc的search搜名字；读知识库文档要先wiki拿token再doc读内容。

无参数 /review 通过 git merge-base 找分叉点作为审查基准，不是 diff --root 审查所有变更。基准分支查找顺序：origin/HEAD symref → origin/main → origin/master → 硬编码 'main'
/review 分两种模式 — 带 PR 号走 GitHub API（gh pr view/diff，不依赖本地分支），无参数走本地 git diff（必须存在基准分支）。无基准分支时 merge-base 失败直接报错，没有任何兜底策略（不回退到 --root、diff staged、空树对比等）

git merge-base A B 返回两个分支的最近公共祖先 commit，不是分支创建点。这个 commit 用来圈定 '从何处分叉之后改了什么'。如果两个分支完全没有共同历史（各自有独立 root commit），merge-base 一定会失败，因为不存在任何公共祖先

"我的空间"和"共享空间"不是独立产品，而是云盘(Drive)下面的两个子文件夹——个人文件夹和共享文件夹的旧称/俗称。飞书在不同版本中换过名字，导致三个词混用。官方产品页明确：云盘支持多级目录，通过"个人文件夹"和"共享文件夹"分类整理。实际只需要记住三个顶层容器：知识库、我的文档库、云盘，后者的内部就是个人文件夹+共享文件夹。官方FAQ也确认"我的文档库"和"云盘"是两个独立模块。

飞书云文档体系的演进顺序大概率是：最早只有云盘(Drive)，内部用个人文件夹和共享文件夹区分私密和协作文件。后来团队知识管理需求增长，从共享文件夹中分化出知识库(Wiki)——独立的产品形态，有目录树和成员权限管理。最近期加入"我的文档库"，本质是个人版知识库，功能同Wiki但私密。证据：老用户仍把云盘称为"共享空间"；知乎上有人问"知识库和共享空间有什么不同"说明两概念并存期长；官方FAQ特意强调"我的文档库和云盘是两个独立模块"。当前命名混乱的根因是产品演进中新概念叠加旧名字，而非一次性的清晰重构。