AI 协作

这里是“李寒的小窝”里给 AI 用的那一层。

整个站点只分两层：

• 生活档案层：随想、旅行、生活、阶段总结，按原来的节奏写，AI 不去动。
• AI 知识层：把可复用的经验做成 卡片（card），让任何项目里的 AI 都能拿来用。

下面只讲第二层。它现在以一个跨工具的 lihan-cards 入口 skill 为核心，对齐社区 Agent Skills（SKILL.md）+ AGENTS.md 开放标准。日常执行是 local-skill-first：本地 skills/lihan-cards/ 负责 consult / capture / classify 和模式路由；博客卡片主要是 display/sync/bootstrap 表面。这里讲清五件事：系统结构、有哪些卡片、怎么用、卡片长什么样、调用信号。

系统结构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

ai/cards/<id>.md         手写卡片：display/sync/bootstrap + verify + 工程/科研笔记
        │ 生成
static/ai/registry.json  公网索引（展示、同步、bootstrap 发现用）
static/ai/stats.json     调用信号（consulted / helped / no_effect）
        │ Hugo 渲染
/ai/cards/<id>.md        原始卡片正文（展示/兜底）     /ai/  中文清单页（人看）

skills/lihan-cards/      唯一安装的入口 skill（consult / capture / classify + 模式路由）
  └ references/*.md       modes / research / science-* 等重内容按需加载（渐进披露）
agents/user-AGENTS.md    用户级配置 + principle 精要 → 软链到 ~/.claude、~/.codex
agents/user-repo-modes.yaml       每仓库粘性 mode lock（工程 / 科研 / 通用）
agents/user-research-profile.yaml 非密科研运行时 profile（路径 / 主机 / 端口 / env 名）
scripts/install.sh       一键软链同步（6 条软链，跨工具 / 跨设备；密钥永不同步）

• 核心是那个入口 skill，不是某一张卡：它教 AI 怎么查 / 写 / 分类和选择工程/科研/通用模式，只在用到时才加载重内容（这就是消除"协议税"的渐进披露）。
• 模式是按仓库粘住的（sticky mode lock）：每个仓库的工程 / 科研 / 通用模式记在 agents/user-repo-modes.yaml，AI 不在每次会话重新猜；只有我明确说"切模式"才改。科研模式折叠了原先的五个 science skill，按任务只加载 science-notes / science-compute / science-claims 之一；固定但会变的私有事实（工作区路径、GPU 主机、下载策略、judge API）放进非密 research profile，密钥只留在本地 env 文件。
• 卡片是被 registry 索引的数据，不逐张安装成 skill，所以发现层不会随卡数膨胀。
• 两个自研差异化（社区标准没有、我们刻意保留）：每张卡的 verify（可机器复验，对抗记忆过期）+ 公网 registry.json（任意机器免安装 bootstrap）。
• public registry is a bootstrap fallback：没装本地 skill、换新机器、跨设备同步或人工浏览时用；日常 consult 不把公网正文当 routine runtime。
• 格式骑社区标准，CI 接入 skills-ref + skill-validator 校验，跟随上游演进而非自研维护。

卡片清单

按四类（principle 哲学·原则 / engineering 工程 / research 科研 / environment 环境事实）分组。每行点标题里的 id 就能打开那张卡片的机器友好原文（/ai/cards/<id>.md，与 registry 的 public_url 同一个地址）。这张清单直接读卡片源文件生成，不会和正文漂移。

两个入口

1. 本地 skill（首选）：装过 lihan-cards 的工具（Claude Code / Codex / Cursor）直接触发它，按 skills/lihan-cards/ 的 consult / capture / classify 协议和 mode routing 走。装一次：bash scripts/install.sh。
2. 公网 registry（展示/同步/兜底）：任何项目、任何机器、没装 skill 也能直接看这个 URL——

1

https://lihan3238.github.io/ai/registry.json

日常 consult 不再把公网 registry 当主运行时。正常路径是：本地入口 skill 先按仓库的粘性 mode lock 路由工程 / 科研 / 通用模式（没有 lock 才推断一次，并直接以 inferred: true 写入 lock 文件，改一行即可纠正），再按 modes.md 的 context budget（原则 essence、环境 preflight、任务最小 bundle、调试窄诊断、治理 gate 全查）选择要加载的本地 reference 或少量已验证卡片。公网 registry 和卡片正文仍是静态文件，没有数据库、没有 API、没有鉴权；它们负责展示、同步、跨设备存储和新机器 bootstrap。

三种使用模式

一、主动查经验

让 AI 在做任务前先加载本地 lihan-cards，选择模式，再按 context budget 查有没有相关经验。原则 / 环境 preflight 可以加载多个精简资产；调试保持窄加载和 verify。没命中就照常，不能脑补。

二、主动写卡片

做完一件事，觉得这个经验下次还能用，就让 AI 起草一张卡片。capture 现在分两段：草稿段免确认——过了 recurring trigger + meaningful verify 边界测试后，AI 直接把 v3 格式的草稿卡写进本地待审队列 ~/.config/lihan-cards/drafts/（平凡可逆，删文件即撤销，永不入库），consult 时顺带检索，未发布的经验立即可复用；发布段保留全部质量门——go 的语义是"允许发布"而不是"允许开始"，一次 go 之后 card-only PR 在绿色 CI 后自动合并，非卡片变更仍然由你手动合并。

三、AI 自己写草稿

任务完成的瞬间，如果同时满足四件事——已验证完成、经验本身不平凡、可以推广、这个会话还没写过——AI 不再询问，直接把草稿写进本地队列并报告一行（草稿本来就平凡可逆，问一句反而比写一张草稿更贵；不会因此发 PR，发布永远要等我的 go）。想丢弃就说一声，删掉草稿文件即撤销，同一条经验该会话内不会重写。

这三种模式都由那个跨工具的 lihan-cards 入口 skill 承载，暴露给本机的 AI 工具（Claude Code、Codex、Cursor 等）。bash scripts/install.sh 装一次即可。它不只是个指针——skill 正文就是 consult / capture / classify 协议本身，重内容按需加载（渐进披露）；registry URL 是没装 skill 时的免安装兜底。

卡片格式

一张卡片就是一个 markdown 文件，YAML frontmatter + 紧凑正文。frontmatter 采用社区 Agent Skills（SKILL.md）的形状：顶层只放 name 和 description，其余字段塞进字符串值的 metadata: map，这样卡片对上游工具 100% 合规。

Frontmatter（必填）

verify_command 可以是 shell 命令、“按这步骤目测一下"的描述句，或一次状态烟测——三种都算，principle / environment 卡常用后两种，不强求自动可执行。

正文必填段

1
2
3

## Trigger        什么场景下加载这张
## Fix            具体怎么做
## Reuse Rule     加载条件 / 不加载条件

可选段（按需）：## Symptoms、## Diagnosis、## Pre-requisites、## Related 等等。

正文是写给机器看的：bullet、表格、key-value，不写多段人类散文。

完整契约：specs/006-card-type-taxonomy/contracts/card-schema.md。

卡片的状态流转

valid → stale → retired。

不按时间表去扫——只在我真的发现某张卡片对不上现实时，编辑它的 status 并 bump last_verified。被 retired 的卡片仍然留在 registry，agent 读到 retired 就跳过；历史保留，不删除。

调用信号（闭环）

每张卡在 static/ai/stats.json 里记三个数：consulted（被查过几次）、helped（确实帮上）、no_effect（没起作用）。

• consulted 由 scripts/ai/stats_miner.py 按需扫本机已存在的 Claude / Codex 会话日志、按 session 去重得到——只读、只数、不落地任何 transcript 内容，无常驻服务。
• helped / no_effect 由 AI 只在高把握时写（客观锚点：卡的 verify 通过 / 任务确实成了），拿不准就弃权；人审 PR 时一并确认。
• 用 helped − no_effect 给卡排序、据证据退役低价值卡。这是 ACE「会进化的 playbook」的轻量版，但守住"无常驻基础设施"的底线。

这里没有的东西

这些不是"还没做”，是"故意没做"。如果未来真的需要其中一项，会先经过宪法（.specify/memory/constitution.md）的"1-day MVP"和"no-agent-sprawl"两道闸口。

给 agent 的一句话总结

想找经验：先加载本地 skills/lihan-cards/，选 mode 和 context budget；公网 registry 只做 display/sync/bootstrap fallback。 想写经验：先过 recurring trigger + meaningful verify；card-only PR 按既有校验和发布 lane 走。 自觉想提示捕获：任务收尾时 AND-of-four 全过才说话，被拒了就闭嘴。

剩下的细节都在那个跨工具的 lihan-cards skill 里——它折叠了原先的 agent-card-protocol，是这条 consult / capture / classify 协议的源代码。