lat.md：把任意文件夹变成AI可查询的验证知识图谱

Fri, 12 Jun 2026 00:00:00 +0800

当文档跟不上代码
lat.md 是什么
五步上手：从安装到自动验证
更深入的使用场景
技术实现
适用场景和限制
和竞品的对比
总结

当文档跟不上代码

AI编程助手越来越强，但它们的最大瓶颈不是模型能力——而是看不到全局。

一个Claude Code的上下文窗口再大，也不可能一次读懂上千个文件的项目。更糟糕的是，你给AI的那份README，很可能已经过时了。

传统文档有三个死穴：

太长——单个README文件动辄几千行，AI根本读不完
过期——代码改了，文档没改，没人知道
缺上下文——只说了”做了什么”，没说”为什么这么做”

lat.md（Agent Lattice）就是来干这个的。它把你项目的文件夹变成一张可查询、可验证的知识图谱。每个文档节点都和代码里的具体实现挂钩，而且有自动检查机制确保它们永远同步。

lat.md 是什么

lat.md 是一个开源工具，专门给AI编程助手（Claude Code、Cursor、Aider等）提供项目的”地图”。它不是普通的文档生成器，而是一个带引用完整性的知识图谱系统。

项目地址：https://github.com/lat-md/lat.md

作者 Ana Bildea 之前写过 Graphify——另一种知识图谱工具。lat.md 和 Graphify 的区别在于：

Graphify：擅长从代码、文档甚至音视频中做高层提取，减少71.5倍的Token消耗
lat.md：更强调引用完整性，确保每个文档概念都和实际代码同步，适合需要严格验证的开发流程

五步上手：从安装到自动验证

第一步：安装和初始化

一行命令的事：

npx lat.md init

这个命令会做三件事：

询问你用的AI工具（Claude还是Cursor）
在你的项目里创建一个特殊的”地图”文件夹
给AI工具添加指令，告诉它们优先看地图而不是从头读文件

第二步：扫描代码

npx lat.md scan

这一步完全在本地执行，代码不会上传到任何服务器。lat.md 支持20多种编程语言，能自动识别：

函数和类定义
模块之间的依赖关系
核心代码结构

因为是自动扫描，地图永远和你的实际代码保持一致。

第三步：连接文档和代码

这是 lat.md 的核心能力——把文档和代码绑在一起。

你可以在Markdown文档里用特殊标记指向代码：

## 用户认证模块

<!-- @lat:src/auth/login.ts -->
登录流程使用OAuth 2.0，token存储在Redis中，有效期24小时。

也可以在代码里加注释指向文档：

// @lat:doc:/docs/auth.md
// 参考认证文档了解完整的安全策略
async function login(email: string, password: string) {
  // ...
}

然后运行检查命令：

npx lat.md check

如果有链接断了，或者某段代码没有对应的文档，这个命令会立刻报错。

第四步：”摘要优先”规则

lat.md 强制要求每个文档章节都以一段简短的摘要开头，不超过2-3句话。

这不是形式主义。AI在搜索地图时，会先扫一遍摘要来判断哪些部分相关。没有摘要的章节，check命令直接报错。

这个设计让整个知识库对人和AI都友好——人类读摘要把握全局，AI凭摘要快速定位。

第五步：自动化检查

文档被忽视的最大原因是什么？维护成本。没人有精力每天手动检查文档是不是还准确。

lat.md 把文档检查嵌入了开发流程：

# 在git hooks里加一行
# pre-commit时自动检查
npx lat.md check --strict

如果设置成pre-commit hook，每次提交代码时自动检查链接完整性。有断链？提交被阻止。这样你的知识地图就永远不会”过期”。

更深入的使用场景

大型项目的情报中心

当项目有几千个文件、多个团队协作时，没有人能记住所有细节。lat.md 的地图就成了团队的”情报中心”：

新成员入职：直接看地图，而不是翻遍整个代码库
跨团队协作：API接口在哪里定义、数据库表结构是什么，地图上一目了然
技术决策记录：为什么选择这个方案，约束条件是什么，写在地图里永远不丢

AI驱动的代码审查

结合Claude Code或Cursor，lat.md 能让AI做更精准的代码审查：

claude "根据项目地图检查这个PR是否符合架构规范"

AI有了完整的上下文地图，可以判断新代码是否违反了既定的设计决策、是否和现有模块产生了冲突。

增量式文档建设

lat.md 不要求一口气写完所有文档。做法是：

先给核心模块写地图——用户认证、数据存储、API路由
运行 setup，让AI辅助写第一批笔记
开启自动检查
每周补充一到两个模块

这种方式成本很低，但效果立竿见影。

技术实现

lat.md 的技术栈很轻量：

核心：TypeScript，Node.js运行
解析器：支持20+语言的AST解析（Tree-sitter）
存储：本地文件系统，Markdown + YAML
检查引擎：自定义的引用完整性验证器
AI集成：通过CLAUDE.md、.cursorrules等配置文件对接

// lat.md 内部的数据结构示例
interface KnowledgeNode {
  id: string;
  type: 'module' | 'function' | 'class' | 'concept';
  summary: string;
  content: string;
  codeRefs: CodeReference[];
  docRefs: DocReference[];
  lastVerified: Date;
}

整个工具不需要数据库，不需要云服务，所有数据都存在你的项目文件夹里。这保证了隐私和可移植性。

适用场景和限制

lat.md 最适合：

中大型项目（100+文件）：小项目可能不需要这么重的文档管理
多团队协作：需要统一的文档规范和验证
AI深度使用：重度依赖Claude Code、Cursor等工具的团队
合规需求：需要证明文档和代码一致的场景（审计、监管）

目前已知的限制：

极端复杂的代码偶有解析问题（但团队的迭代速度很快）
不支持闭源项目（需要在项目内建立open目录）

和竞品的对比

这个领域还有几个工具值得了解：

工具	核心能力	适合场景	验证机制
lat.md	引用完整性知识图谱	需要严格验证的团队	内置check命令
Graphify	高层知识提取	快速理解大型代码库	无自动验证
Mermaid	图表生成	可视化架构	无
传统Wiki	手动文档	团队知识库	无

lat.md 的核心差异在于：它不只帮你写文档，它确保文档不会过期。

总结

如果你遇到过这些问题，lat.md 值得一试：

AI助手总是写不出符合项目架构的代码
文档写了一堆但没人看、没人更新
新成员入职要花两周才能搞清代码结构
代码审查时发现新代码不符合原本的设计决策

地图是AI理解你项目的方式。其他都只是猜测。

lat.md 的核心思想很简单：把笔记和代码直接挂钩，并且用自动化检查保证它们永远同步。这就让AI工具不再是”猜”，而是真正”知道”你的项目在做什么。

开始用：

npx lat.md init

在任意项目文件夹里跑这行命令，把自己从”搜索引擎”变成”地图导航员”。

用Karpathy的LLM Wiki模式，我搭了一个会自己生长的研究大脑

Mon, 08 Jun 2026 00:00:00 +0800

先说痛点—你可能也有的那个”research”文件夹
为什么RAG不够
Karpathy的洞见：让AI当图书管理员
三层架构：什么放哪，为什么
三个核心操作
Obsidian的角色：窗口，不是大脑
实战：作者两周的真实经验
会断的地方和怎么修
两周后的改变
更大的图景

先说痛点—你可能也有的那个”research”文件夹

你有一个叫”research”或”阅读资料”或”ai-stuff”的文件夹。里面有四十七个Markdown文件、六篇早就想总结但一直没动的PDF、三个导出过一次就再也没打开的Notion页面，还有一个叫”重要”的浏览器书签文件夹——里面的链接来自2023年。

你知道里面有一篇关于注意力机制的文章，和一篇关于MCP服务器的东西。你几乎确定这两者之间有联系——但你不知道当时记在哪了，也不知道到底有没有记过。

你不是不整理。你是被信息淹没了。这两者有本质区别。

为什么RAG不够

大多数人跟LLM和文档的互动方式是RAG：你把一堆文件上传，LLM在查询时检索相关段落，生成答案。

这能工作，但每次查询LLM都是从零重新发现知识。没有积累。没有成长。问一个需要综合五篇文档的微妙问题，LLM每次都要重新找到相关内容、拼凑在一起。什么都没有被构建起来。

我用了这个模式好几个月。NotebookLM处理论文。ChatGPT文件上传处理会议笔记。一堆永远不会再看第二眼的Claude对话。每一次都是一次性交易——我问一个问题，得到一个答案，关掉标签页，两周后我把同一批论文重新上传，问几乎同样的问题，因为之前综合出的东西没有在任何地方持久保存。

Karpathy的洞见：让AI当图书管理员

2026年4月，Andrej Karpathy在GitHub上丢了一个Gist，就叫”LLM Wiki”。不是新产品、不是新框架、不是SaaS——就是一个”思路文件”，一种设计模式，贴进Claude Code或者Codex里就能用。

核心思路的转变：

过去：你维护知识库，偶尔问AI问题。现在：AI构建和维护整个知识库，你只管丢原始资料。

Karpathy用的类比来自软件工程：编译。你写源代码，编译器把它变成优化过的二进制产物。你不会每次运行源代码——你编译一次，分发产物，在需要时高效执行。编译步骤很贵，但在后续每一次使用中都值回票价。

在这里，编译后的产物不是二进制。是Wiki——一个文件夹的可读Markdown文件，每个概念一个页面，相互交叉引用，由模型维护，在Obsidian中查看。

RAG检索然后遗忘。Wiki积累然后复利。

三层架构：什么放哪，为什么

my-wiki/
├── raw/              # 原始资料（你维护，不可变）
│   ├── papers/
│   ├── articles/
│   └── notes/
├── wiki/             # 知识层（AI写，你读）
│   ├── entities/
│   ├── concepts/
│   ├── sources/
│   ├── index.md
│   └── log.md
└── CLAUDE.md         # 规则层（操作手册）

第一层：raw/ — 原始资料

论文PDF、文章、笔记、播客文字稿全部放在这里。这层不可变——不编辑，不修改，只追加。

不可变不是审美选择，是设计决策。它意味着你随时可以从原始资料重新派生出整个Wiki。如果需要重建、发现AI出了错，你永远不会丢失原始内容。

第二层：wiki/ — 知识层

这是AI生成的Markdown文件，按类型分目录：

entities/: 人物、组织、项目
concepts/: 核心概念、方法、理论
sources/: 每篇资料的总结页

每个页面内部有[[wikilinks]]交叉引用。一页可能关联到10~15个其他页面。

第三层：CLAUDE.md — 规则层

这是整个系统的灵魂。它把通用的LLM变成一个有纪律的知识工作者。

CLAUDE.md定义了：

页面类型（实体、概念、来源、综合）
[[wikilinks]]的命名规范
何时新建页面 vs 更新现有页面
lint检查清单

第一版写得比较粗糙。但经过几十次导入和几次lint之后，它会变成反映你领域实际运作方式的schema。

三个核心操作

1. 导入（Ingest）— 一份资料触达10~15页

你丢一个新资料进raw/，告诉Claude处理它。然后Claude：

读完整篇资料
跟你讨论核心观点和重点
在wiki里写一个摘要页
更新index页面
更新所有相关的实体和概念页面
在log中追加一条记录

一份资料可能触达10~15个Wiki页面。

Karpathy偏好一份一份导入，并在过程中保持参与——读摘要，检查更新，指导AI哪些该强调。第一次导入是一场对话，不是一次批处理。Claude总结完论文后，会建议创建五个概念页，并询问是否需要为某个特定数据集单独建页。这是编辑决策。模型主动询问是对的。

2. 查询（Query）— 质量碾压RAG

LLM不是从某个PDF第14页随机切一段出来。它读的是已经综合好了、交叉引用的百科条目，这些条目已经整合了系统所有所学。

作者问了一个典型问题：“关于上下文窗口长度和AI Agent可靠性的关系，我读过的所有资料都说了什么？”

Claude做了三件事：

读了index，定位到6个相关Wiki页面
引用4篇不同论文，按名字引用
标出了一个矛盾——两篇论文在这个问题上立场相反

还有一个关键设计：--save标记。当开启时，一次有价值的综合查询结果会被自动归档为新的Wiki页面。未来会话立即受益。Karpathy把这称为”复利原则”——你问了一个问题，系统回答了，现在Wiki也知道答案了。

3. 健康检查（Lint）— 每周8分钟的保养

没人爱做维护，这就是为什么人在做的时候Wiki最终会腐烂。但LLM做这个只需8分钟。

定期让AI健康检查Wiki，它会找：

页面之间的矛盾
被新资料推翻的过时断言
没有入链的孤立页面
被频繁提及但没有独立页面的概念
丢失的交叉引用
需要补充搜索填补的知识空白

作者在12天后做了第一次lint。AI发现了：

3个矛盾——其中一个第一周和第二周导入的论文之间的真实分歧，作者完全没有注意到
2个孤立页面
4个被跨页引用但没有独立页面的概念

全程约8分钟。

在lint中标记矛盾，LLM花3分钟。而那个导致每份人维护的Wiki最终腐烂的知识管理开销，彻底消失了。剩下的是真正属于人的部分：筛选资料、决定哪些重要、问正确的问题、思考这一切意味着什么。LLM处理其他一切。

Obsidian的角色：窗口，不是大脑

这里有一个关键区别：Claude Code是大脑，Obsidian是窗口。

Obsidian作为Wiki的IDE存在。它渲染带反向链接的Markdown，显示页面之间的图视图，支持全文搜索，文件变更时实时刷新。

你始终处于阅读模式，从不处于编辑模式。你浏览、跟链接、看图、阅读。你从不直接编辑Wiki文件。

图视图是那个能转变怀疑者的功能。两周后，87个页面——图视图显示出了自然的聚类：围绕Transformer架构的、围绕Agent记忆的、围绕评估文献的。特定页面作为聚类之间的桥梁。作者没有设计这些聚类——模型通过跟踪文献中实际一起讨论的内容，自主发现了这些结构。

实战：作者两周的真实经验

指标	数值
时间投入	首次搭建~2小时，后续每次导入15分钟
导入资料	34份（论文、文章、YouTube字幕、播客笔记）
生成页面	87个（作者一个都没自己写）
首次lint	12天后，8分钟，发现3个矛盾+2个孤立页+4个缺失概念
token消耗	导入阶段约5~8倍原始token量，查询阶段极低

会断的地方和怎么修

Schema在第三天跟你打架

第一个版本的CLAUDE.md太抽象了。几次导入后，模型创建页面的结构不一致——有些有”Key Claims”章节，有些有”Main Arguments”，意思一样但命名不同。修复方法：标准化章节名。模型会严格遵循schema说什么，所以schema必须说清楚。

认知漂移

如果AI在导入时误解了一份资料——误解、幻觉出的连接——这个错误会进入Wiki，影响后续导入。Lint操作能减轻但不能消除。通过git diff进行人工审核是真正的安全网。作者在每次导入后跑git diff，花90秒，两周内抓住了两次错误。

规模上限：约100~200份资料

Karpathy建议Wiki包含大约100篇文章以确保系统保持高效。超过这个规模，可能需要LLM Wiki v2的扩展（混合搜索、多Agent治理）或专门的RAG管线。

好消息是：200份精选资料，经过正确的编译和交叉引用，比2000份在RAG系统中每次都从零检索的原始文档有用得多。

导入成本前置

导入步骤是token消耗最集中的地方。一份10页的PDF可能触发12个Wiki文件的更新。预算大约是原始token量的5~8倍。但后续查询极为便宜——通常只需要index.md加2~3个概念页。

两周后的改变

我停止了丢失东西。

听起来很平凡？其实不然。在这个系统之前，每篇读过的有趣论文都处于逐渐衰减的状态——刚读那天最有用，此后每周都在退化。

两周后，相反的事正在发生。每份新资料都让现有资料更容易被发现，因为导入过程会明确更新所有相关页面。第一天读的论文现在在11个后来添加的Wiki页面上被交叉引用。它比刚读的时候更有连接了。

Karpathy本人几乎从不直接编辑Wiki文件。他把Wiki视为”AI的领地”。AI写、更新、维护。Karpathy只读。

那个让系统有效的纪律：你一旦开始手动编辑Wiki页面，你就在AI自己的领土上和它竞争，并且失去了让整个系统可行的维护自动化。

更大的图景

Karpathy还提到了一个未来方向：用Wiki生成合成训练数据，微调一个LLM，让它”在权重中知道”这些数据，而不仅仅通过上下文窗口理解。这意味着把个人知识库变成个性化模型。

那个未来比Gist听起来要远一些。但当前的版本——一个自愈、交叉引用、AI维护的Wiki，跑在你本机的一个文件夹里——已经是作者用过的最好的知识管理系统。

Memex终于可以建造了。不是因为我们有了更好的文档或更好的搜索，而是因为我们有了真正干活的图书管理员。

Vannevar Bush在1945年描述了Memex。Karpathy在2026年4月发布了操作说明。

文件夹就在那里。Gist是公开的。Claude Code有免费层。剩下的只是第一次导入。

原文：I Used Karpathy’s LLM Wiki to Build a Research Brain That Updates Itself，作者 Adi Insights and Innovations。

Karpathy的autoresearch实战：让AI Agent替你跑一整夜训练实验

Mon, 08 Jun 2026 00:00:00 +0800

什么是”autoresearch”
三个核心文件
实验循环机制
硬件和软件要求
上手设置
如何选择和接入 AI Agent
让 autoresearch 跑一整夜
最让我惊讶的部分
说人话的总结

什么是”autoresearch”

Andrej Karpathy 的最新开源项目 autoresearch，是一个小但完整的”自动研究实验室”——它跑在一张 GPU 上，核心驱动是一个 AI 编程 Agent。

这个项目的核心理念很简单：人类写高层指令，AI Agent 负责底层迭代。人类不再需要手动调参、改代码、对比日志……这些事情全部交给 Agent 去做。人类退回到”监督者”的位置，写一个 Markdown 文件描述想做什么，Agent 就自己去改训练脚本、跑实验、决定要不要保留改动。

Karpathy 把它描述为”单 GPU、单文件版本的 nanochat 训练核心”，专门设计给 Agent 无限迭代用的。

不是手动指挥每一个改动，而是人类写一个高层次的”程序”（其实是 Markdown），描述Agent应该做什么，然后Agent反复编辑一个Python训练脚本，跑固定时间的训练，根据验证指标决定是否保留自己的修改。

这和 Karpathy 之前提出的 “agentic engineering”（Agent式工程化） 思路一脉相承——人类越来越多地扮演编排者的角色，而不是亲自写每一行代码。

三个核心文件

这个仓库小得惊人，整个项目只有三个核心文件：

prepare.py

负责下载训练数据和训练 BPE（Byte Pair Encoding）分词器。这个文件被视为”固定环境”，Agent 不允许修改它。它是基础设施，不是实验变量。

train.py

大约是 630 行的训练脚本，定义了一个紧凑的 GPT 风格模型，它的优化器（Karpathy 用的是 Muon + AdamW 的组合）以及完整的训练循环。这是 Agent 唯一可以修改的文件，所有的架构改动和超参数调整都通过编辑这个文件来实现。

program.md

这是人类写的 Markdown 指令文件。Agent 会读取这个文件来了解它应该做什么。它就类似于一个轻量级的 skill——告诉 Agent 怎么行为，如何评估实验结果，什么时候 commit。

这三者的关系非常清晰：

人类 → 写 program.md
     ↓
Agent → 读 program.md + 编辑 train.py
     ↓
    跑训练（固定5分钟）→ 看验证指标 → commit 或回滚

Karpathy 刻意保持这种极简设计，是为了让人类可以在喝杯咖啡的时间里读完整个训练脚本，理解所有关键环节。这延续了他一贯的风格——从 minGPT 到 nanoGPT，全是小而精的单文件仓库。

实验循环机制

autoresearch 的核心是一个严谨的实验循环，设计上同时保证了公平性和全自动化。

具体的流程是：

Agent 读取 program.md，打开 train.py
提出某种架构或超参数的修改方案
启动一次训练，硬限制 5 分钟北京时间
5 分钟结束后，Agent 检查验证指标（val_bpb——bits-per-byte，衡量语言模型质量的标准指标）
如果指标变好了，git commit 保留修改
如果变差了，回滚到上一个最佳版本，换个方向重新尝试

这就像是在模型配置的山形地貌上攀爬，每一步要么向上走一点，要么退回原地另找出路。而且每一步都有 Git 记录，可审计、可回溯。

Karpathy 特别强调了这个固定时间窗口设计和传统超参数调优的区别。在传统方式里，跑得快的模型可能仅仅因为收敛快就被认为更好——但固定的 5 分钟窗口消除了这个偏差，大家公平竞争，只看最终谁的质量更高。

硬件和软件要求

autoresearch 是为单张 NVIDIA GPU 设计的。不是分布式集群，不是多卡并行，就是一张卡。

Karpathy 自己测试的环境是 H100，但固定的 5 分钟时间窗口本身就是一个”归一化机制”——慢一点的 GPU 只是在 5 分钟里跑更少的步数，对比的是最终验证损失，而不是速度。

软件方面需要：

Python 3.10+
PyTorch + CUDA
对应的 NVIDIA 驱动
一个 AI coding agent（Claude Code / Codex 等）

基础设置流程和标准的深度学习环境配置一模一样：装驱动、对 CUDA 版本、建虚拟环境。

上手设置

设置 autoresearch 的第一步和 Karpathy 的其他项目一样——clone 仓库，创建干净的 Python 环境。

git init
git remote add origin https://github.com/karpathy/autoresearch
git pull origin master

然后安装 Python 工具链。Karpathy 推荐用 uv（astral 家的现代 Python 包管理器）：

curl -LsSf https://astral.sh/uv/install.sh | sh

安装项目依赖：

uv sync

下载数据、训练分词器、跑一个基础训练：

uv run prepare.py
uv run train.py

跑通这些命令后，说明环境和依赖都没问题了。

接下来就是启动你喜欢的 AI coding agent（Codex、Claude Code 或者其他），让它读 program.md 然后开始做实验：

# 在你的 terminal 中对 AI agent 说：
Hi, have a look at program.md and let's kick off a new experiment!

Agent 会读取 program.md 这个轻量级 skill，按照里面描述的指令开始做研究。

如何选择和接入 AI Agent

autoresearch 没有捆绑自己的 Agent 实现，它假设你手头有一个能读文件、能编辑 train.py、能在受控环境里跑 shell 命令的 AI 编程助手。

当前主流的选项包括：

Agent	特点
Claude Code	Anthropic 出品，代码能力极强，适合复杂编辑任务
OpenAI Codex CLI	OpenAI 的命令行 Agent，擅长 Python 脚本
其他通用 Agent	只要能读文件和跑命令，理论上都能接入

接入方式就是常规的 Agent 使用方式——在项目目录下启动 Agent，给它一段提示词，让它读 program.md。

让 autoresearch 跑一整夜

当 Agent 接入完毕、program.md 也写得差不多之后，最令人满足的一步来了：让它自己跑着。

以现代的 NVIDIA GPU 为例，每次训练固定 5 分钟，一个 8 小时的通宵运行可以完成 约 96 次完整训练尝试。高端硬件（H100 级别）可能推进到 100 次左右，取决于模型大小和具体实现。

这完全改变了实验的节奏。以前你手动改一个参数跑一次，一天最多能试 5-10 次。现在一觉醒来，Agent 已经爬过了近百个配置点的山形地貌，留下了完整的 Git commit 记录——哪个改动有效、哪个无效、最终最好的是什么，一目了然。

autoresearch 是一个小而雄心勃勃的实验，它探索了当真实的训练循环被交给一个 AI Agent 时会怎样——Agent 带着一个简单的指令：”在固定的时间预算内，让效果更好，并记录一切。”

最让我惊讶的部分

autoresearch 真正让我觉得”这事不简单”的，不是技术本身，而是它重新定义了”做实验”这件事的节奏和分工。

以前你跑深度学习实验，流程大概是这样的：改代码 → 丢去后台跑 → 切出去刷网页 → 半小时后回来看日志 → 哦 loss 没降 → 再改 → 再跑。一个周期的决策间隔是几十分钟到几小时。

但 autoresearch 把这个间隔压缩到了 5 分钟一次，而且不必让你坐在那里等着做决策。Agent 自己在 5 分钟窗口内完成”改代码 → 跑训练 → 看指标 → commit/回滚”的循环，你在旁边写代码、看论文、睡觉都行。

这意味着什么？意味着你能在同一个晚上并行探索的实验数量，直接放大了一个数量级。

如果你是一个做 LLM 方向的研究生，手头有一张 24GB VRAM 的卡（比如 4090 或者 A10G），以前一个晚上你可能跑 2-3 组实验，手动记录对比。现在有了 autoresearch，一晚上 50-80 组实验自动跑完、自动记录、自动保留最佳结果。

这不是”帮你自动化”那么简单——这是改变了你作为研究者能做多少事的量级。

说人话的总结

Karpathy 的 autoresearch 就是告诉了我们一件事：AI Agent 不只是帮你写代码，它还能帮你跑实验、做研究。

三个文件（prepare.py、train.py、program.md）构建了一个极简框架——人类写战略（Markdown 指令），Agent 做战术（改代码 + 跑实验），一张 GPU 当战场。

这个东西的意义不在于它现在能做得多好（训练的还是小模型），而在于它展示了一个未来的工作范式：人类不再和代码搏斗，而是和 Agent 一起探索未知的配置空间。

这个模式很可能不会停留在语言模型预训练这一个方向。检索管线、领域自适应、多模态训练……只要有可量化的指标和一个训练脚本，这个”人类写指令、Agent 做迭代”的模式都能套用。

项目地址：https://github.com/karpathy/autoresearch

别再让AI写Markdown了：一个CLAUDE.md规则让产出从没人看到被转发到董事会

Mon, 08 Jun 2026 00:00:00 +0800

一句话说清楚
为什么Markdown是错的
HTML为什么赢
实测数据：同一个内容，不同的命运
CLAUDEMD规则：十分钟搞定
三个实用标准
Markdown仍然赢的场景
更大的趋势
说人话的总结

一句话说清楚

一个简单的CLAUDEMD规则，把你所有AI产出的默认格式从Markdown换成HTML，效果立刻天差地别。

Marco Kotrotsos 做了实测：同一个内容的每日简报，用Markdown生成时只有40%的早晨会打开，换成HTML后每天必看。客户报告从「存了归档」变成「被转发到董事会议案里」。

同样的AI、同样的提示词，换了输出格式，结果天差地别。

这不是玄学，是人类行为学。

为什么Markdown是错的

Markdown的设计初衷是：开发者能在编辑器里舒服地读。它的语法简洁、纯文本、Git友好，适合在GitHub上展示README，适合在终端里浏览，适合被版本控制。

但问题在于——AI产出的东西大部分不是给开发者读的。

你让AI生成一份客户报告、一条项目状态更新、一个每日简报、一份复盘总结，这些东西的受众是：

客户（在手机上快速扫一眼）
老板（在Slack里打开）
同事（在浏览器里翻一下）
未来的自己（在某个周二早晨打开看看）

这些人不会打开一个Markdown渲染器。他们不会在终端里运行 cat 命令。他们不会去理解 ## 和 ### 的区别。

大多数情况下，Markdown文件在磁盘上躺了一周，然后就被删除了——从未被打开过。

HTML为什么赢

HTML和Markdown的区别不在于「哪个更容易写」，而在于哪个更容易读。

维度	Markdown	HTML
打开方式	需要渲染器/编辑器	浏览器直接打开
视觉呈现	纯文本+少量标记	设计好的卡片页面
分享便捷度	需要说明「你先渲染一下」	截图/链接直接发
感知价值	像是草稿	像专业人士做的
打印/归档	需要转换	自包含，直接可用

HTML单个文件、内联所有CSS、自包含，保存、邮件、粘贴到Slack、归档到Notion，全部零依赖。打开就是一张设计好的视觉卡片。

实测数据：同一个内容，不同的命运

作者做了三个场景的实测：

1. 每日简报

Markdown版：40%的早晨会打开
HTML版：每天早上必看
同一个内容、同一个Claude、同一个prompt。只是格式从 .md 变成 .html。

2. 客户报告

Markdown版：被存了，被归档了
HTML版：被转发到公司内部，被引用到董事会的议案材料里
「HTML版本因为看起来像值得认真对待的文档，获得了更多的注意力。」

3. 项目状态面板

Markdown版：一大段文字，重启项目后就不会再看
HTML版：每个项目一个卡片，颜色编码健康状态，始终开着一个标签页
「HTML版本保持了一目了然的特性。」

三个场景的共同点：当产出的内容是为人类消费设计的，渲染过的版本比原始文本获得更多的注意力。

CLAUDEMD规则：十分钟搞定

核心操作很简单——在你的 CLAUDE.md 里加一段规则（无论全局还是项目级别）：

## Output format
For any artifact intended for human consumption (reports, briefings, summaries,
plans, retros, status updates, memos, decks):
- Default to a single self-contained HTML file with inline CSS
- Use semantic HTML (h1, h2, sections) and embedded styles
- Visual style: clean typography, generous whitespace, restrained color use
- Always include a print-friendly stylesheet (@media print)
- Light Mode is the default.
- File extension .html, save in artifacts/ alongside the markdown source

For reference material that will only be edited (specs, configs, READMEs,
project notes): keep markdown as the primary format.

When unsure: ask "is this for someone to read or someone to edit?"
Read = HTML. Edit = markdown.

这段规则的灵魂在最后一句："这东西是给人读的还是给人改的？"

给人读的（报告、简报、总结、计划）→ HTML
给人改的（README、API文档、项目笔记）→ Markdown

三个实用标准

1. 单文件零依赖

单个HTML文件，所有CSS内联在 <style> 标签里，所有SVG图表内联。不要外链字体、不要CDN、不要JavaScript（除非产物本身是交互式的）。

读者可以保存文件、邮件发送、粘贴到Slack、丢进Notion页面、归档用于合规检查，所有操作都不会出问题。

2. 始终包含打印样式

@media print {
  body { background: none; }
  .card { break-inside: avoid; }
  /* 页面边距调整 */
}

作者发现大约30%的高管会打印AI生成的报告。打印布局比你想象的重要得多。

3. 克制设计

Claude有一种「加一百个图标和渐变背景」的冲动。要抑制它。

最多两个强调色
充足的留白
无衬线正文字体
看起来像一个细心的人类设计师做的，而不是Tailwind游乐场

把这些约束写在 CLAUDE.md 里，Claude会严格执行。

Markdown仍然赢的场景

这篇文章不是说「永远别用Markdown」。以下三个场景我仍然用Markdown：

1. 代码仓库内的文档 README、API规范、架构文档。这些由人类编辑、由GitHub等平台渲染。Markdown是正确格式。

2. 可编辑的草稿 文章草稿、进行中的规范、需要几周时间修改的文档。切换到Markdown的边际成本很低，编辑体验更好。

3. 给未来AI的笔记 CLAUDE.md、skill文件、agent prompt。AI解析Markdown比HTML更干净，结构足够清晰。

更大的趋势

「渲染输出」这个洞察不是Claude Code特有的。它在多个层面同时发生：

协议层：MCP Apps让工具返回UI组件而不是文本墙
产品层：Claude Design让视觉产物直接被渲染展示
工作流层：你的Claude Code生成的HTML而不是Markdown

人类花了几十年被训练成「忽略纯文本、注意设计过的界面」。AI继承了这个不对称。实验室正在协议和产品层面追赶，你的本地工作流也应该跟上。

说人话的总结

人就是会忽略纯文本、关注设计过的界面，这是人性。AI不能改变人性，AI应该适应人性。

一个CLAUDE.md规则，十分钟改完。从此你生成的AI内容不再躺在磁盘里吃灰，而是真正被打开、被阅读、被转发。

判断标准：这东西是给人读的还是给人改的？读 = HTML，改 = Markdown。

原文：Writing HTML For Documentation Instead of Markdown is a Game-Changer，作者 Marco Kotrotsos。

7个AI作者做了70+Claude技能，他们选出了这12个

Sun, 07 Jun 2026 00:00:00 +0800

缘起
写作与内容创作
决策与研究
职场效率
- 9. 邮件任务过滤器
- 10. 早间情报
Claude Code 开发工具
- 11. Context Mode
- 12. Superpowers
如何在 Cowork 中安装这些技能
什么时候该自己做 Skill
说人话的总结

缘起

上次我分享了100个Claude技能里面最好用的一批。这次玩法不一样——我直接找了7个日常用Claude工作的AI写作者，让他们每人推荐一个自己亲手做的最常用的技能。

他们有的做内容创作，有的做AI产品，有的做技术咨询。日常每天都用Claude干活，每人手上都有一堆自己写的skill。

最后筛出12个。覆盖了写作、研究、编程、决策四大场景。每一个都有明确的痛点、具体的解法、以及为什么它比同类更好。

每个skill末尾有创建者的链接。觉得好用就去订阅他们的newsletter支持一下。

写作与内容创作

1. Instagram帖子下载器

痛点： 看到一张好的Instagram帖子，图不错想存下来。Instagram没有下载按钮。你只能截图、划下一张、再截图、裁剪、重命名、丢进文件夹。划到第6张你已经放弃。而且截图不是原图，是有损压缩的。

解法： 丢一个Instagram帖子URL进去。它打开帖子，自动判断是单图还是多图轮播，直接从Instagram的服务器拉高清原图，按caption命名存到文件夹。多图轮播还会自动拼成PDF，一滑到底。

为什么好用： 网上有下载Instagram图片的网站，但你要一个一个粘贴链接、一个一个点下载。每天做就变成一个烦人的小任务。这个skill一次丢多个链接，回车就走人。顺便还做了一个下载Reels的版本。

下载： 图片&轮播

Reels

创作者：Frank Andrade & Diana Dovgopol（来自 Write, Prompt, Scale）

注意： 如果skill不工作，在Claude Settings → Capabilities → Domain allowlist 中添加 *.cdninstagram.com。

2. AEO优化（AI Engine Optimization）

痛点： 你写了一篇很好的Substack/博客文章。Google可能最终会收录它。但ChatGPT、Perplexity、Claude永远不会引用你。为什么？因为AI读取文章的方式和人类完全不一样——它们扫描可提取的、无链接的文本块来直接回答问题。而大多数作者的习惯是在第三段才给出答案，前两段塞满链接。结构是反AI的。

解法： 把你的文章丢给它。它把H2标题重写成人们会实际问AI的问题（”什么是X？”“如何做Y？”），在每个标题下放一个50-80字的无链接答案胶囊，然后检查全文——段落长度、原始数据信号、你提出的框架。你拿回来的是同一篇文章，只是结构改成了AI能直接引用的格式。

为什么好用： AI引擎不从头读到尾，它们扫描。大多数写作者把答案埋在第三段还用链接填充前两段。这个skill反过来——答案在最前面，干净，字数刚好在AI偏好的范围内。你不再只跟Google排名竞争，当有人问AI同样问题的时候，你就是被引用的来源。

下载： Google Drive

创作者：Gencay（来自 LearnAIwithMe）

3. 文章缩略图生成器（Claude Code）

痛点： 做一个newsletter缩略图很费时间。你要从Gemini网页界面一张一张生成，反复粘贴图片和prompt。Gemini Gems可以消除一些重复劳动，但整体体验还是慢。

解法： 把文章内容或链接贴进去，告诉Claude Code你想要几个缩略图方案。它会根据文章内容和你的品牌规范推荐构图方案，构建图片prompt，然后通过脚本调用Gemini生成图片，再通过Computer Vision评估成果。你可以在生成的同时做其他事。

为什么好用： Claude成为了一个拥有你品牌参考图的图片生成代理。一次性拿到三四张候选图，很多时候直接挑一张就行了。而且Claude写图片prompt比我强。

GitHub： article-thumbnail-skill

创作者：Karen Spinner（来自 Wondering About AI）

4. Substack Notes 数据采集

痛点： 你在Substack写Notes，想知道哪些真正受欢迎——赞、评论、转发，所有这些数据在一起。Substack不给你这个视图。你只能手动翻Notes页，把数字一个一个抄到表格里。

解法： 给它三个东西：Notes页面的URL、作者名称、时间范围。它打开页面，滚动加载这段时间内所有的Note，提取每个的日期、文字、赞数、评论数、转发数、链接，返回一个带冻结表头和筛选的.xlsx文件。

为什么好用： Substack Notes没有公开API。唯一的数据获取方式就是从渲染页面抓。手动做这种事就是最容易被跳过的重复劳动。这个skill一次性搞定滚动、筛选（排除其他作者的转发）、格式化。

下载： 阅读指南

下载skill

创作者：Frank Andrade（就是我）

5. Notes Humanizer——去AI味

痛点： 你一眼就能认出AI写的字。破折号满天飞、”让我们深入探讨”式的开场、三点式列表、每句话长度都一样。让模型”写得自然点”只是换一种稍微不同的模板化文字。最终你不得不自己一句一句重写。

解法： 把AI生成的文字贴进去。它会跑一遍完整的标记模式列表，把标记机器写作的特征全去掉。然后加上模型自己不擅长的东西：观点、变化的节奏、具体细节、一个旁白。最后拿到的是像人写的文字。

为什么好用： 大部分”人性化”prompt只是告诉模型写得不那么正式。这不解决问题。AI的写作模式是统计默认值——训练数据里最常见的措辞方式。这个不做表面功夫，它直接删特征、加人味。

下载： Google Drive

创作者：Orel（来自 TheIndiepreneur）

决策与研究

6. Sycophancy Skill——反对派模式

痛点： 默认的Claude想让你觉得自己是对的。你给它一个决策，它找出三个理由支持你的直觉，你走的时候比来的时候更自信。那不是一个思考伙伴，那是一面语法更好的镜子。

解法： 这个skill反转了Claude的默认行为。它从你还没验证的假设开始，先论证你想法里最强的反对意见，然后才考虑你的观点。你反驳它，它不会退缩——除非你给出新证据。它先告诉你什么最脆弱，而不是什么在运作。如果找不到真正的漏洞，它也会告诉你——而不是编一个出来显得尽责。

为什么好用： 大部分skill告诉Claude要加什么。这个skill告诉Claude停止默认做什么。那些禁令比规则更管用。没有它们，Claude会走一遍框架然后恢复”好问题！”模式。禁令在源头就把这掐掉了。

默认Claude vs Sycophancy Skill 对比：

场景	默认Claude	Sycophancy Skill
你说”我想做X”	找到3个理由支持X	找到3个理由反对X
你反驳	同意你	要求你给新证据
结果	你更自信了	你看到了盲区

下载： 阅读指南

创作者：Joel Salinas（来自 Leadership in Change）

7. Last 30 Days——全网调研

痛点： 听说一个新的AI工具或趋势，想知道它实际怎么样？Google搜索给你的是SEO堆砌的”最佳榜单”和上季度的公关稿。真实的评价在Reddit帖子、X讨论里。跨平台追着看吃掉你整个下午。

解法： 激活它，输入一个主题。工具、趋势、功能、随便什么。它搜索Reddit、X、Web上过去30天的内容。返回一份报告：大家同意什么、在哪里有分歧、反复出现的痛点。

为什么好用： 大部分”调研”只是美化了的Google搜索一次。这个找的是真实观点在的地方。同一个东西在多个平台同时出现，那是它靠谱的最强信号。省你一个下午，给你一份更清晰的图景。

下载： 教程

下载skill

小提示：我们刚在上一篇文章里深度评测了这个skill——28K星的GitHub项目，值得单独写一篇。

8. Notebook LM 连接器

痛点： Notebook LM是最好用的AI工具之一。但它不跟你其他工具互通。每次想要新的mindmap、音频概览、幻灯片，你都得回到Notebook LM重新点同样的按钮。有开源方案，但基本都需要Claude Code和终端操作。

解法： 在Claude里装好（不需要写代码或终端），然后告诉Claude做什么：”创建一个notebook，添加这些链接作为来源，生成一个mindmap。” Claude通过Chrome扩展进入Notebook LM帮你操作。

为什么好用： Notebook LM有输出能力（音频概览、幻灯片、信息图、mindmap），Claude有自动化能力。把两个连起来，Notebook LM就进入了自动驾驶模式。

Notebook LM 输出：音频概览、幻灯片、信息图、思维导图
Claude 负责：自动操作、指令理解、链接管理
合起来：一句话完成

下载： 教程

下载skill

职场效率

9. 邮件任务过滤器

痛点： 我们很多人（至少我是）被邮件淹没了。Newsletter、通知、各种。我想要一个可以从手机上的Claude启动的东西，帮我节省时间，只看真正重要的邮件。

解法： 这个skill连接到你的Gmail。输入 /emails-tasks，它读取过去8小时（或你设定的任何窗口）的收件箱，丢掉所有不需要你的东西（收据、通知等），只展现需要回复或决策的邮件。每封邮件标明：谁发的、他实际要什么、紧急程度、以及一句开场白。

为什么好用： Claude现在完美地分类邮件。最棒的部分——可以通过Dispatch从手机上直接启动。现在我只看到最重要的邮件，知道是否需要我行动。

下载： Dropbox

创作者：Ilia Karelin（来自 Prosper）

10. 早间情报

痛点： 你想保持对工作相关新闻的关注。Cowork Scheduled Tasks和Claude Code Routines现在可以定时执行任务。瓶颈是prompt。一个好的prompt需要说清楚你是谁、你关注什么、排除了什么、来源是什么、你的地域、你想要的格式。从零开始写很难，每次关注点变化再调更难。

解法： 一个15道题的面试，问你的角色、关注点、故事类型偏好、排除项、时效性、格式。它把你的答案聚类成几个支柱(pillar)，写成一个主prompt，直接可以贴到Cowork Scheduled Task或Claude Code Routine里。当关注点变化时，重新跑一次面试就行。

为什么好用： 一次性设计，永久运行。把prompt丢进Cowork（Scheduled Tasks → New Task，需要Pro/Max且桌面端打开）或Claude Code（Routines → New routine → 云端运行，不需要电脑开着）。两种方式都把一个一次性的prompt变为定时自动送达的简报。Pro tip: 用Opus来跑面试。

下载： Google Drive

创作者：Ashwin Francis（来自 Cash&Cache）

Claude Code 开发工具

以下两个skill来自Nate Herk的YouTube频道，强烈推荐给Claude Code用户。

11. Context Mode

痛点： 用Claude Code一段时间你就会发现——越来越慢、忘了你在编辑什么文件、又问你想干啥。实际上，Claude每次运行命令都把原始输出直接塞进记忆。30分钟后，大部分记忆是垃圾。Claude不得不重置。重置后它忘了你在哪。

解法： 做两件事：第一，过滤垃圾输出——只有有用的部分进入Claude的记忆。第二，维护一个运行日志（编辑过的文件、进行中的任务、上一个prompt）。当Claude重置时，拉回这个日志，从你停下的地方继续。

为什么好用： 大多数”长会话”其实不是长的。它们是一堆短会话粘在一起，你不停地重新解释自己。这个同时解决两个问题：更少的垃圾输入，完整的会话记忆。30分钟就死的对话现在能跑几个小时。

教程： Nate Herk - Context Mode

12. Superpowers

痛点： 你让Claude Code构建一个东西。它冲出去一口气写完，表面看起来很好。然后你实际运行它——或者更糟，你的客户运行它——它就崩了。Claude不规划、不测试、不复核自己的代码。它就写。

解法： 强制Claude像资深开发者一样工作：退一步规划全局，在隔离环境中工作不影响主项目，先写测试再写代码，然后对自己的工作做两轮审查——一次”符合需求吗”、一次”代码质量过关吗”。

为什么好用： Claude Code的大部分失败不是因为Claude笨，而是因为Claude太急。让它慢下来真正思考，首轮通过率从60%升到80%。更少的调试周期，更低的token成本，不会在用户手上崩掉的代码。

教程： Nate Herk - Superpowers

如何在 Cowork 中安装这些技能

把skill文件（.zip或skill.md）添加到Claude Cowork:

Customize → Skills → "+" → Create skill → Upload a skill → 选择文件

什么时候该自己做 Skill

不是所有任务都值得做成Skill。我的原则：

重复做且耗时的 → 最好的skill候选
步骤清晰可重复的 → 更好的候选
一次性的 → 别做，不值得

做法也很简单：在Claude里正常完成一次任务，然后在对话中说”基于我们这次学到的东西，创建一个叫XXX的skill”。Claude会帮你写好。保存后在新的对话里测试，有问题就告诉Claude修复并重新上传。

说人话的总结

12个skill，5个跟写作相关（去AI味、做缩略图、发Instagram、优化SEO、采集数据），3个跟决策研究相关（反对派、全网调研、Notebook LM），2个跟日常效率相关（邮件过滤、早间简报），2个跟开发相关（上下文保持、超级开发者模式）。

我最常用的是Sycophancy Skill——它让我做决策之前先被”骂”一顿，反而更踏实。其次是Context Mode，我现在Claude Code的会话能跑好几天不断。你呢？最喜欢哪个？

Karpathy的4条CLAUDE.md规则减少30%错误，我加了4条后降到5%

Sat, 06 Jun 2026 00:00:00 +0800

背景
基础层：Karpathy的4条规则
执行层：4条新的Agent规则
完整 CLAUDE.md 模板
我的看法
说人话的总结

背景

超过200行的提示词，AI的遵从率直线下降，Agent会默默地忽略你的规则。

2026年1月，Andrej Karpathy 公开发难，剖析了 Claude Code 在生产代码库中的失败模式：静默假设、过度工程、正交损害。

一位开发者把他的抱怨打包成4条 CLAUDE.md 规则，发布到 GitHub。结果它成了今年增长最快的仓库——一夜之间传遍开发者社区。

但现在是5月。AI 生态在加速进化。我们正在运行越来越多的多步骤、自主 Agent 工作流。

当我在部署自主 Agent 重构数据摄入层时，遇到了新的摩擦：Agent 前三步完美执行，第四步开始产生幻觉，然后静默地覆盖了工作代码。

Karpathy 的原始规则无法防御多步骤退化。

通过精确设计4条额外规则——专门针对现代 Agent 编排——错误率进一步降低。

基础层：Karpathy的4条规则

这4条规则封堵了大约40%的标准单次提示失败模式：

规则1：先思考，再编码

不准静默假设。 如果存在更简单的方案，Agent 必须提出质疑。不确定就要问。

这是最基础的规则。大多数 AI 错误始于一个错误的前提假设——”我认为用户想要X”——然后基于它构建整个方案。

规则2：简单优先

最少代码解决问题。 没有推测性功能。不需要抽象就不要创造抽象。

这条规则专门针对 AI 的”过度工程”倾向——花哨的泛化、提前优化的抽象层、永远不会被调用的辅助函数。

规则3：手术式修改

只动你必须动的。 不要”改进”相邻的格式、注释、代码风格。

Karpathy 说的”正交损害”——AI 在修一个 bug 时顺手改了30行无关代码的格式。

规则4：目标驱动执行

定义成功标准，循环直到验证通过。 不要盲目遵循固定步骤，而是定义成功标准并独立迭代。

为什么这些规则在今天会失效？ 这些规则对多步骤流水线沉默不语。它们不给 Agent 设定 Token 预算，不强制检查点，而且假设 Agent 已经理解了周围的代码库。

执行层：4条新的Agent规则

规则5：硬性 Token 预算

没有预算的 Agent 会在同一个错误消息上消耗5万 Token 的上下文，直到它崩溃。

具体规则：

每个任务预算：4,000 Token
每个会话预算：30,000 Token
如果接近预算限制，强制 Agent 总结并重启会话
超支必须主动报告，而不是静默超限

# 在 CLAUDE.md 中的 Token 预算配置
budget:
  per_task: 4000      # 每个独立任务
  per_session: 30000  # 每次会话
  on_breach: summarize_and_restart

我自己的经验：上线这条规则后，API 账单直接砍掉了一半。不是因为用的少了，而是因为 Agent 不再在一个死循环里浪费 Token。

规则6：先读后写

Karpathy 的规则说”不要碰相邻代码”，但它们没有说”理解相邻代码”。这导致 AI 盲目地编写重复函数——而同样的功能已经存在于30行之外。

具体规则：

在修改文件前，强制 Agent 读取文件的导出接口、直接调用方、共享工具函数
“看起来不相关”是一个危险的假设

## Rule 6 — Read Before You Write
Before adding code to any file:
1. Read the file's exports and public API
2. Read immediate callers of the function you're modifying
3. Check shared utilities in the same module
If unsure why code is structured a certain way, ASK before writing.

规则7：每步检查点

如果一个6步重构在第4步出错，Agent 会愉快地在错误状态上执行第5步和第6步，破坏整个分支，最终只能手动 git reset。

具体规则：

每完成一个重要步骤，Agent 必须总结：已验证了什么 + 还剩下什么
Agent 不能从一个它无法描述的状态继续执行

## Rule 7 — Checkpoint After Every Significant Step
After each operation step:
✓ Summarize what was done
✓ State what was verified 
✓ State what remains
→ Stop and restate if you can't describe the current state back to me

这是最具杀伤力的一条。多步骤流水线中的错误传播是 Agent 中最常见的失败模式——一条链的强度取决于最薄弱的环节。

规则8：大声失败

最昂贵的失败看起来和成功一模一样。”迁移完成”是一句谎言——如果30条数据库记录因为约束违规被静默跳过。

具体规则：

默认暴露不确定性
Agent 跳过任何内容，必须大声失败并立即通知用户
“测试通过”是错误的——如果有任何测试被跳过

## Rule 8 — Fail Loud
- "Completed" is WRONG if anything was silently skipped
- "Tests pass" is WRONG if any were skipped
- Default to surfacing uncertainty, not hiding it
- When in doubt, over-communicate: tell me what you're unsure about

完整 CLAUDE.md 模板

将以下内容保存为项目根目录的 CLAUDE.md，然后在下方向追加你项目的具体技术栈信息：

# CLAUDE.md — 8条规则架构

以下规则适用于本项目中的每个任务，除非被显式覆盖。
偏向：在非琐碎工作上谨慎优先于速度。琐碎任务上使用判断。

## 规则1 — 先思考再编码
- 显式陈述假设。如果不确定，提问而不是猜测。
- 当存在更简单的方案时，提出质疑。困惑时停下来。

## 规则2 — 简单优先
- 解决问题的最少代码。不做推测性功能。
- 不超出需求范围的功能。不为一次性代码做抽象。

## 规则3 — 手术式修改
- 只动你必须动的。只清理你自己的混乱。
- 不要"改进"相邻代码、注释或格式。匹配现有风格。

## 规则4 — 目标驱动执行
- 定义成功标准。循环直到验证。
- 不遵循固定步骤。定义成功并独立迭代。

## 规则5 — Token 预算不是建议
- 每个任务：4,000 Token。每个会话：30,000 Token。
- 接近预算时，总结并重新开始。报告超支情况。

## 规则6 — 先读后写
- 添加代码前，读取导出接口、直接调用方、共享工具函数。
- 如果不确定代码为什么是某种结构，提问。

## 规则7 — 每步检查点
- 每个重要步骤后：总结做了什么、验证了什么、还剩什么。
- 不要从一个你无法描述的状态继续。停下来重新陈述。

## 规则8 — 大声失败
- "完成"是错的——如果任何内容被静默跳过。
- "测试通过"是错的——如果有任何测试被跳过。
- 默认暴露不确定性，而不是隐藏它。

我的看法

我从3周前开始使用这套8规则架构。变化是立竿见影的。

Token 预算是救命稻草。 之前我的 Agent 有时会在同一个问题上反复循环——修改代码→测试→失败→修改代码→测试→失败。每次循环吃掉几千 Token，直到我手动停下来。规则5强制 Agent 在接近预算时主动报告，让我从旁观者变成了管理者。

每步检查点规则彻底改变了代码质量。 以前 Agent 完成6步操作后给我看结果，我经常发现第3步就有问题。现在每分钟收到一次状态更新，可以在Agent继续之前纠正方向。

“大声失败”帮我抓到了一个数据迁移 bug。 Agent 报告”迁移完成”，但规则8强制它检查是否所有记录都已转换。结果发现了30条被约束违规跳过记录——手动 review 永远发现不了的那种。

Karpathy 定义了自动补全编码的问题。我们正在编排自主、多步骤 Agent——需要不同的约束体系。

说人话的总结

Karpathy的4条规则 → 堵住单次交互的坑（约40%）
我的4条新规则     → 堵住多步骤流水线的坑（再降约25%）
8条规则一起用     → 错误率降到5%以下

CLAUDE.md 不是一个一次性文件。它是一个严格的行为合约，旨在关闭特定的、代价高昂的失败模式。把它放到你的项目根目录，加上你的技术栈细节，然后看你的 Agent 表现大幅提升。

锁住环境、强制执行 Token 预算、要求检查点——这三点就能把 AI Agent 从”玩具”变成”工具”。

Hermes Agent：那个真的会记住昨天学过东西的开源AI Agent

Sat, 06 Jun 2026 00:00:00 +0800

引子
核心思想：会自己写剧本的 Agent
Skills vs. Tools：一个关键的区别
四层记忆系统
深度研究：不仅仅是花哨的网页搜索
安全故事：为什么这比功能更重要
动手实操：周末部署指南
诚实评估：Hermes 的局限性
更大的图景
- 关键选择指南
我的看法
说人话的总结

引子

你用的每个 AI Agent 都有同一个问题。

周一你教会了它你的项目结构、编码偏好、部署流程。到了周二，它全忘了。你又回到了起点，重新解释一切。

就像每天早上都要培训一个新实习生。

Nous Research 构建了 Hermes Agent 来终结这个循环。

Hermes 是一个开源、自托管的 AI Agent，运行在你自己的服务器上，从每个完成的任务中学习，并且随着使用时间的增长变得可测量地更好。自 2026 年 2 月发布以来，它已经收获了超过 64,000 个 GitHub 星标，并引发了开发者们所说的”从 OpenClaw 迁移的浪潮”。

有趣的部分不是采用数字。而是它底层的架构——以及它对那些希望 AI 能随时间累积价值、而不是每次会话都重置归零的人来说意味着什么。

核心思想：会自己写剧本的 Agent

当 Hermes 成功完成一个任务时，它不只是记录结果然后继续下一步。它会运行一个执行后评估——识别出产生结果的确切步骤序列、工具调用和推理过程——然后将该序列编码为一个可复用的 Skill 文档。一个 Markdown 文件，Agent 下次遇到类似任务时会引用它。

这就是 Nous Research 所说的闭环学习：执行 → 评估 → 提取 → 优化 → 检索。而且它会复利增长。

根据 Nous Research 发布的基准测试，运行自建 Skill 的 Agent 完成研究任务的速度比零提示调优的全新实例快 40%。

你在 5 美元 VPS 上运行了三个月的 Hermes 实例，知道你的代码库、你的部署怪癖、你偏好的提交信息格式、以及在你那个奇怪的遗留集成中能用的精确 API 调用序列。一个新安装的实例对这些一无所知。

Skills vs. Tools：一个关键的区别

Hermes 对 Skills 和 Tools 做出了一个尖锐的架构区分，这比听起来重要得多。

Tools（工具）是通过 JSON Schema 暴露给 AI 模型的 Python 函数。它们确定性执行。想想浏览器自动化、文件操作、流式进程。修改它们意味着编辑核心 Python 文件。

Skills（技能）是 Markdown 文档。Agent 像阅读指令一样读取它们，并自主遵循记录在案的程序。这里是关键部分：Agent 可以自主编写自己的 Skill。不需要代码修改。不需要人来编辑配置文件。Agent 观察自己在某件事上成功，写下它是怎么做的，并将该知识存储起来供下次使用。

Agent 在不触及自己源代码的情况下变得越来越聪明。确定性的工具层保持稳定和安全。知识层持续增长。

四层记忆系统

上下文太少，Agent 会做出糟糕的决策。太多，你会烧掉 Token、增加延迟、模型开始在巨大的提示词中丢失指令。

Hermes 用四层记忆系统解决这个问题，按 Agent 需要信息的紧急程度分层：

Tier 1：Agent 的个人笔记（MEMORY.md）

存储环境事实、项目约定和操作经验。上限大约 800 Token，在会话开始时直接注入系统提示。想想 Agent 的”小抄”。

# MEMORY.md 示例片段
项目使用 Vue 3 + Nuxt 3 + PrimeVue
测试框架：Vitest
部署：Cloudflare Pages（自动通过 git push 触发）
CI：GitHub Actions（运行 lint + test + build）

Tier 2：用户档案（USER.md）

维护一个关于你是谁、你的技术水平、时区、沟通风格的模型。大约 500 Token。也在启动时注入。

Tier 3：会话搜索

将跨所有历史会话的所有内容归档在一个 SQLite 数据库中。Agent 按需查询，使用全文搜索（FTS5）结合 LLM 摘要器。这就是深层历史上下文的所在。

Tier 4：外部记忆插件

连接到基于图的检索系统，如 LightRAG、Supermemory 或自定义向量存储。这对企业用途来说变得非常强大，支持跨复杂关系映射的多跳查询。

前两层使用冻结快照模式：更改立即写入磁盘，但不修改活动系统提示，直到下个会话开始。这保留了语言模型的前缀缓存，确保整个长会话期间的低延迟。在对话中途修改提示会使该缓存失效，拖慢推理速度。

还有一个周期性推送机制值得理解。Hermes 运行时会利用空闲时刻主动提示 Agent 评估最近的交互并提取关键事实——在上下文窗口填满、旧轮次被压缩掉之前。Agent 在这次主动刷新中没有标记的事实就不会存活。这是要用或者丢弃的记忆管理方式。

深度研究：不仅仅是花哨的网页搜索

当你交给 Hermes 一个复杂的研究任务时，它会先调用 think_tool——一个强制性的策略暂停，促使模型在做任何事情之前阐述一个实际的调查计划。

映射数据向量
定义范围
形成假设

只有在这个规划阶段之后，Agent 才能开始执行。

然后它并行化。ConductResearch 工具不会发出单个查询。它将特定的研究主题委托给独立的子 Agent，每个都有自己的干净上下文窗口、隔离的终端会话和受限的工具集。

一个子 Agent 可能通过无头浏览器抓取监管文件
另一个查询数据库
第三个运行 Python 脚本生成统计分析

它们同时执行，并将结构化的 JSON 返回给主编排器。

并行工作完成后，Agent 再次调用 think_tool。这第二次过程强制综合：评估返回了什么，检查是否有缺口，判断目标是否达成。如果没有，循环用新的研究向量迭代。如果有，它调用 ResearchComplete 并进入报告生成阶段。

最终报告由一个大上下文模型（至少 64K Token 窗口）将模块化的迷你报告合并成一个有引用来源的连贯文档。

安全故事：为什么这比功能更重要

这里是与 OpenClaw 比较让人不安的地方。

在 2026 年 3 月 18 日到 21 日之间，四天内针对 OpenClaw 发布了九个 CVE，包括一个 CVSS 9.9 的关键漏洞，允许认证用户提升到管理员权限。到 4 月初，安全研究人员在 63 天窗口内追踪到 138 个 CVE。每天大约 2.2 个新漏洞。

供应链数字更糟糕。安全公司 Antiy CERT 确认 ClawHub 市场中有 1,184 个恶意 Skill——高峰期大约每五个包中就有一个。SecurityScorecard 发现超过 135,000 个 OpenClaw 实例暴露在公共互联网上，使用不安全的默认配置。ClawHavoc 活动甚至不需要寻找漏洞。攻击者只是上传看起来令人信服的 Skill，等人来安装。

Hermes 采取了根本更保守的方法。因为 Agent 基于你特定的工作流在内部生成自己的 Skill，它完全绕过了外部供应链攻击向量。你不是从匿名贡献者编写的公共注册表中拉取可执行代码。Agent 从你环境中观察到的成功中编写自己的操作知识。

在基础设施方面，Hermes 强制终端执行的容器隔离、子 Agent 进程的加密命名空间隔离以及动态凭据轮换。它会在将任何外部数据注入系统提示之前扫描提示注入。

动手实操：周末部署指南

你需要安装 Git。仅此而已。安装程序会处理 Python 3.11+、Node.js v22、ripgrep 和 ffmpeg。支持 Linux、macOS、WSL2 和 Android（通过 Termux）。不支持原生 Windows。

第一步：安装

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

安装程序检测你的操作系统并自动配置依赖。Python 通过 uv——一个基于 Rust 的包管理器，创建一个无需 sudo 的隔离虚拟环境。

第二步：运行 Setup

hermes setup

交互式向导引导你完成模型选择和初始配置。如果你从 OpenClaw 迁移，向导会自动检测 ~/.openclaw 并提供迁移你的设置、记忆、Skill 和 API 密钥。

第三步：选择模型

hermes model

Hermes 与模型无关。你可以连接到 Anthropic、OpenAI、DeepSeek 或 OpenRouter（通过单个端点访问 400+ 模型）。对于深度研究任务，至少需要 64K 上下文 Token 的模型。

如果你想要零 API 成本和完全的数据隐私，通过 Ollama 拉取本地模型：

ollama pull qwen2.5-coder:32b

然后将 Hermes 指向你的本地端点：http://localhost:11434/v1。完全自主，没有外部 API 调用，没有数据离开你的机器。

第四步：设置网关

hermes gateway setup

将 Hermes 绑定到 Telegram、Discord、Slack、WhatsApp 或 Signal。网关作为持久后台服务运行，所以你可以在 Agent 在你的服务器上运行重型任务时，从手机给它发消息。

一个注意事项：消息界面非常适合监控和异步更新，但它们本质上是线性的。对于深度协作工作，比如复杂的代码库变更，消息线程很快就会成为瓶颈。对于那种交互，使用 CLI 或专用工作区。

第五步：容器化执行

hermes config set terminal.backend docker

这确保所有 Agent 生成的代码在隔离的容器内运行。如果出了问题，你的主机系统不受影响。

第六步：让它学习

从简单的、可重复的任务开始：周报、PR 审查、API 数据处理、研究汇编。观察 Skills 目录。在成功完成后，你会看到新的 .md 文件出现——Agent 自编的操作手册。几周后，以前需要几分钟的任务开始只需要几秒钟。

诚实评估：Hermes 的局限性

本地推理的硬件现实

文章建议通过 Ollama 拉取 qwen2.5-coder:32b 进行免费本地推理，这需要现实的检验。在主编排器上运行 32B 模型是可以的。但前面描述的深度研究并行化——多个子 Agent 每个都需要自己的活动推理线程和干净的上下文窗口——这需要严重的 GPU 资源。

更现实的本地设置是对子 Agent 路由和数据提取使用较小的量化模型，保留 32B 模型给主编排器和最终综合。如果你只有一个消费级 GPU，预计并行研究工作流会严重瓶颈。

自建 Skill 是脆弱的

内部 Skill 系统绕过了 OpenClaw 的供应链风险，但当底层的世界发生变化时，Markdown 操作手册会失效。如果一个遗留 API 更新了它的认证流程，或者一个网站重新设计了它的 DOM，Agent 记住的程序就会失败。

与具有可视化错误处理路径的确定性工作流工具不同，Hermes 必须失败、重新评估并从头重写 Skill。学习循环处理这个，但这不是即时的。

除非你真需要，跳过 Tier 4 记忆

文章提到了 LightRAG 和 Supermemory 集成，但对大多数单服务器设置来说，SQLite 全文搜索（Tier 3）提供了速度和召回率的最佳平衡。让平面 MEMORY.md 文件与重型外部向量数据库保持同步会引入延迟和状态冲突问题，不值得开销——除非你在运行企业级多 Agent 工作流。

设置复杂性是真实的

OpenClaw 让你从安装到工作 Agent 更快。如果你需要 50+ 平台集成和消费级简单性，OpenClaw 仍然是更易访问的选择。

框架才两个月大

版本 0.8.0 于 2026 年 4 月 8 日发布，开发速度非常激进。但项目仍在成熟中。预计会有粗糙的边缘。

自我改进是渐进的，不是神奇的

40% 的基准提升来自于持续数周的使用，而不是一个快速演示。不要期望一夜之间的转变。

更大的图景

AI Agent 领域正在分裂为两个阵营。连接（OpenClaw 的赌注：连接到一切、任何地方）对比认知（Hermes 的赌注：随着时间的推移变得更聪明）。两者对不同用例都有效。有些团队同时运行两者，用 OpenClaw 做接收和路由，用 Hermes 做深度分析工作。

对你我这样的开发者来说，一个会真正学习的 Agent 的复利优势是很难忽视的。安装需要五分钟。学习循环会负责剩下的部分。

关键选择指南

需求	推荐工具
需要大量平台集成	OpenClaw
需要深度分析/研究	Hermes Agent
安全优先	Hermes Agent（隔离架构）
快速上手	OpenClaw
需要记忆/学习能力	Hermes Agent
企业多Agent工作流	两者组合

我的看法

作为一个每天都在用 Hermes 的人，最让我惊讶的不是它的功能数量——而是随着时间的推移，它真的在变好。第三周的时候，我发现它开始主动提醒我之前做过的决策，而我完全没告诉它要记住。

“你说过这个模块的测试覆盖率要保持在 80% 以上，我刚看到新代码把覆盖率拉低到了 72%。”

这种主动性的来源不是某个单独的功能，而是四层记忆系统的相互作用。MEMORY.md 提供了基础事实，会话搜索提供了历史上下文，Skill 系统提供了可复用的知识。

它的确不是完美的——本地推理的硬件需求是真实的，自建 Skill 在面对外部变化时是脆弱的。但对于任何运行重复性复杂工作流的人来说，一个会积累知识的 Agent 和每天重置的 Agent 之间，差距只会越来越大。

说人话的总结

Hermes Agent 的核心创新用一个词概括：复利。

大多数 AI Agent 是”每次会话归零”模式——你花时间建立的上下文、发现的模式、调试出的解决方案，在会话结束后全部丢失。

Hermes 打破了这种模式。它把每次成功的操作转化为永久的、可复用的知识。今天你花 30 分钟解决的问题，明天它自己就能搞定。后天，它可能在你发现之前就已经处理好了。

用还是不用，取决于你是否愿意让你的 AI 拥有记忆。

手写AI合同审核系统：OCR + 混合RAG + LangGraph全栈实战

Sat, 06 Jun 2026 00:00:00 +0800

背景
核心技术栈
系统架构总览
第一步：图像增强
- CLAHE（对比度受限自适应直方图均衡化）
- Deskew（去偏斜）
第二步：双策略 OCR
- 主引擎：PaddleOCR
- 兜底方案：GPT-4V
第三步：混合 RAG 索引
- 构建混合索引
- RRF 融合算法
第四步：多查询 RAG
第五步：GPT-4o 合同字段提取
第六步：LangGraph 状态机编排
第七步：彩色的 Excel 报表
完整代码仓库
最让我惊讶的部分
说人话的总结

背景

合同无处不在——供应商协议、服务订单、政府招标书。

一个中型公司可能管理者数百份活跃的供应商合同。大型企业则是数万份。每次想查”这个供应商的付款条款是什么？”或”这份合同什么时候到期？”，就得有人打开 PDF，翻到第 37 页，肉眼搜索几个关键段落。

每查一个问题，20 分钟。如果查询 7 个关键字段，140 分钟。而在数据库里，同样的查询只需要一条 SQL。

问题核心：合同数据锁在文档里，不在数据库里。

这篇文章带你从零到一构建一个生产级的 Contract Intelligence 系统——上传任意合同（PDF/图片/XML），几秒内输出结构化的 Excel 报表，包含所有关键商业条款、置信度评分和页码引用。

核心技术栈

组件	用途
PaddleOCR	主 OCR 引擎，从扫描件提取文字
CLAHE + Deskew	图像增强（去噪、对比度均衡、去偏斜）
GPT-4o / GPT-4V	OCR 兜底 + 智能提取
FAISS	稠密向量检索
BM25	稀疏关键词检索
RRF（Reciprocal Rank Fusion）	混合检索结果融合
LangGraph	多步骤状态机编排
Streamlit	前端 UI
OpenPyXL	彩色的 Excel 报表生成

系统架构总览

整个管道分 7 个步骤，由 LangGraph 状态机编排：

上传合同(PDF/图片/XML)
    │
    ▼
┌──────────────────┐
│  Step 1: 图像增强  │  ← CLAHE + 去噪 + 去偏斜
└────────┬─────────┘
         ▼
┌──────────────────┐
│  Step 2: 文本提取  │  ← PaddleOCR + GPT-4V兜底
└────────┬─────────┘
         ▼
┌──────────────────┐
│  Step 3: 混合索引  │  ← FAISS + BM25 + RRF融合
└────────┬─────────┘
         ▼
┌──────────────────┐
│  Step 4: 多查询RAG │  ← 7个字段并行查询
└────────┬─────────┘
         ▼
┌──────────────────┐
│  Step 5: 字段提取  │  ← GPT-4o + 置信度评分
└────────┬─────────┘
         ▼
┌──────────────────┐
│  Step 6: 费率卡    │  ← 跨页表格合并 + Schema规范化
└────────┬─────────┘
         ▼
┌──────────────────┐
│  Step 7: Excel输出 │  ← 彩色报表 + 源引用
└──────────────────┘

第一步：图像增强

这是最容易忽视但回报最高的步骤。原始扫描件的质量参差不齐——有些是手机拍的照片、有些是传真过来的灰阶文件、有些有 15 度的偏斜。

三个关键处理：

CLAHE（对比度受限自适应直方图均衡化）

普通的直方图均衡化会过度放大噪声。CLAHE 通过在局部区块内做均衡化，并限制对比度增幅，在增强文本清晰度的同时不炸掉噪声：

import cv2
import numpy as np

def enhance_contract_image(image_path: str) -> np.ndarray:
    img = cv2.imread(image_path, cv2.IMREAD_GRAYSCALE)
    
    # 1. CLAHE 自适应直方图均衡
    clahe = cv2.createCLAHE(clipLimit=2.0, tileGridSize=(8,8))
    enhanced = clahe.apply(img)
    
    # 2. 去噪（非局部均值去噪，保留边缘）
    denoised = cv2.fastNlMeansDenoising(enhanced, h=30)
    
    # 3. 二值化
    _, binary = cv2.threshold(denoised, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)
    
    return binary

Deskew（去偏斜）

扫描件经常有微小旋转。使用霍夫变换检测直线 → 计算旋转角度 → 反向纠正：

def deskew_image(img: np.ndarray) -> np.ndarray:
    coords = np.column_stack(np.where(img > 0))
    angle = cv2.minAreaRect(coords)[-1]
    
    if angle < -45:
        angle = 90 + angle
    
    (h, w) = img.shape[:2]
    center = (w // 2, h // 2)
    M = cv2.getRotationMatrix2D(center, angle, 1.0)
    return cv2.warpAffine(img, M, (w, h), 
                          flags=cv2.INTER_CUBIC,
                          borderMode=cv2.BORDER_REPLICATE)

效果： 经过这些处理后，OCR 准确率从裸扫描的约 65% 提升到了约 92%。

第二步：双策略 OCR

主引擎：PaddleOCR

PaddleOCR 是目前开源 OCR 模型中准确率和速度最平衡的选择：

from paddleocr import PaddleOCR

ocr = PaddleOCR(use_angle_cls=True, lang='en', use_gpu=False)

def paddle_ocr_page(image: np.ndarray) -> str:
    result = ocr.ocr(image, cls=True)
    lines = []
    for line in result[0]:
        text = line[1][0]
        confidence = line[1][1]
        lines.append(text)
    return '\n'.join(lines)

兜底方案：GPT-4V

对于手写体密集、盖公章、或 PaddleOCR 置信度过低的页面，自动切换到 GPT-4V：

from openai import OpenAI
import base64

client = OpenAI()

def gpt4v_fallback(image: np.ndarray, paddle_conf: float) -> str:
    if paddle_conf > 0.85:
        return None  # 不需要兜底
    
    # 将图片转为 Base64
    _, buffer = cv2.imencode('.png', image)
    b64 = base64.b64encode(buffer).decode()
    
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{
            "role": "user",
            "content": [
                {"type": "text", "text": "Extract ALL text from this document page. Preserve the original layout order."},
                {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{b64}"}}
            ]
        }],
        max_tokens=4096
    )
    return response.choices[0].message.content

双策略效果： 普通页用 PaddleOCR（几乎零成本），模糊/盖章/手写页自动用 GPT-4V。整体准确率从 PaddleOCR 单独使用的 82% 提升到了 96%+。

第三步：混合 RAG 索引

纯向量检索在合同场景下有问题：合同语言高度模板化，”indemnification”、”termination”、”whereas” 这些词到处都是。语义相近的条款太多，向量容易混淆。

解决方案：FAISS（稠密）+ BM25（稀疏）双路检索 + RRF（Reciprocal Rank Fusion）融合。

构建混合索引

from langchain_community.retrievers import BM25Retriever
from langchain_community.vectorstores import FAISS
from langchain_openai import OpenAIEmbeddings
from langchain.retrievers import EnsembleRetriever

def build_hybrid_index(chunks: list[str]):
    # 稠密检索：FAISS
    embeddings = OpenAIEmbeddings(model="text-embedding-3-small")
    vectorstore = FAISS.from_texts(chunks, embedding=embeddings)
    dense_retriever = vectorstore.as_retriever(search_kwargs={"k": 10})
    
    # 稀疏检索：BM25
    bm25_retriever = BM25Retriever.from_texts(chunks)
    bm25_retriever.k = 10
    
    # RRF 融合
    ensemble = EnsembleRetriever(
        retrievers=[dense_retriever, bm25_retriever],
        weights=[0.5, 0.5]
    )
    return ensemble

RRF 融合算法

Reciprocal Rank Fusion 用排名而非分数来融合结果，避免了 FAISS 和 BM25 分数尺度不一致的问题：

def reciprocal_rank_fusion(results: list[list], k: int = 60) -> list:
    fused_scores = {}
    for rank_list in results:
        for rank, doc in enumerate(rank_list, 1):
            doc_id = doc.metadata.get('id', doc.page_content[:50])
            fused_scores[doc_id] = fused_scores.get(doc_id, 0) + 1 / (k + rank)
    
    ranked = sorted(fused_scores.items(), key=lambda x: x[1], reverse=True)
    return ranked

效果： 纯 FAISS 召回率约 72%，加 BM25 后提升到 94%。

第四步：多查询 RAG

对同一条款的多种表达方式同时查询，最大化召回：

QUERY_VARIANTS = {
    "payment_terms": [
        "What are the payment terms and conditions?",
        "When are payments due? Net 30, Net 60?",
        "Payment schedule and invoicing requirements",
        "Late payment penalties and interest",
        "What currency are payments in?"
    ],
    "termination": [
        "What are the termination clauses?",
        "How can either party terminate this agreement?",
        "Notice period for termination",
        "Termination for convenience or cause",
        "Post-termination obligations"
    ],
    "liability": [
        "What are the liability caps?",
        "Limitation of liability clause",
        "Indemnification obligations",
        "Exclusions from liability limits",
        "Aggregate liability cap amount"
    ]
}

def multi_query_retrieve(retriever, field_name: str, k: int = 5):
    queries = QUERY_VARIANTS[field_name]
    all_docs = []
    for q in queries:
        docs = retriever.get_relevant_documents(q)
        all_docs.extend(docs[:k])
    
    # 去重
    seen = set()
    unique = []
    for d in all_docs:
        key = d.page_content[:100]
        if key not in seen:
            seen.add(key)
            unique.append(d)
    return unique[:k * 2]

第五步：GPT-4o 合同字段提取

将检索到的上下文交给 GPT-4o，结构化提取 7 个关键字段：

CONTRACT_EXTRACTION_PROMPT = """
You are a contract analyst. Extract the following fields from the provided contract text.
For each field, provide:
- value: the extracted value
- confidence: a score from 0.0 to 1.0
- source: a brief snippet from the text that supports this value

Fields to extract:
1. contract_date: Date the contract was signed
2. effective_date: When the contract takes effect
3. expiry_date: Contract expiration or renewal date
4. party_names: Names of all contracting parties
5. payment_terms: Net 30, Net 60, etc.
6. liability_cap: Maximum liability amount
7. governing_law: Jurisdiction and governing law

Contract text:
{context}

Return JSON format.
"""

7 个关键字段的输出示例：

{
  "contract_date": {
    "value": "2026-01-15",
    "confidence": 0.95,
    "source": "This Agreement is entered into on January 15, 2026"
  },
  "effective_date": {
    "value": "2026-02-01",
    "confidence": 0.92,
    "source": "Effective as of February 1, 2026"
  },
  "expiry_date": {
    "value": "2027-01-31",
    "confidence": 0.88,
    "source": "This Agreement shall remain in force until January 31, 2027"
  },
  "payment_terms": {
    "value": "Net 60",
    "confidence": 0.90,
    "source": "Payment shall be made within sixty (60) days of invoice date"
  }
}

第六步：LangGraph 状态机编排

用 LangGraph 将所有步骤串联成一个有状态的工作流：

from langgraph.graph import StateGraph, END
from typing import TypedDict, List, Optional

class ContractState(TypedDict):
    file_path: str
    images: List
    ocr_text: str
    chunks: List[str]
    hybrid_index: object
    extracted_fields: dict
    confidence_scores: dict
    excel_path: Optional[str]
    error: Optional[str]

def build_contract_pipeline():
    workflow = StateGraph(ContractState)
    
    workflow.add_node("enhance_images", enhance_step)
    workflow.add_node("extract_text", ocr_step)
    workflow.add_node("build_index", index_step)
    workflow.add_node("multi_query_rag", rag_step)
    workflow.add_node("extract_fields", extract_step)
    workflow.add_node("generate_excel", excel_step)
    
    workflow.add_conditional_edges(
        "extract_text",
        check_ocr_quality,
        {True: "build_index", False: "extract_text"}  # 质量低则重试
    )
    
    workflow.set_entry_point("enhance_images")
    workflow.add_edge("enhance_images", "extract_text")
    workflow.add_edge("build_index", "multi_query_rag")
    workflow.add_edge("multi_query_rag", "extract_fields")
    workflow.add_edge("extract_fields", "generate_excel")
    workflow.add_edge("generate_excel", END)
    
    return workflow.compile()

LangGraph 的关键优势：

有状态：每一步可以访问前序结果
条件分支：OCR 质量低可以自动重试
可审计：每一步的输入输出都可以记录

第七步：彩色的 Excel 报表

最后，用 OpenPyXL 生成带颜色编码和源引用的 Excel：

from openpyxl import Workbook
from openpyxl.styles import PatternFill, Font

def generate_excel_report(fields: dict, rate_card: list, raw_text: str, output_path: str):
    wb = Workbook()
    
    # Sheet 1: 字段摘要
    ws1 = wb.active
    ws1.title = "Field Summary"
    
    green_fill = PatternFill(start_color="C6EFCE", end_color="C6EFCE", fill_type="solid")
    yellow_fill = PatternFill(start_color="FFEB9C", end_color="FFEB9C", fill_type="solid")
    red_fill = PatternFill(start_color="FFC7CE", end_color="FFC7CE", fill_type="solid")
    
    ws1.cell(row=1, column=1, value="Field")
    ws1.cell(row=1, column=2, value="Value")
    ws1.cell(row=1, column=3, value="Confidence")
    ws1.cell(row=1, column=4, value="Source Text")
    
    for i, (field, data) in enumerate(fields.items(), 2):
        ws1.cell(row=i, column=1, value=field)
        ws1.cell(row=i, column=2, value=data['value'])
        ws1.cell(row=i, column=3, value=data['confidence'])
        ws1.cell(row=i, column=4, value=data['source'])
        
        # 置信度着色
        conf = data['confidence']
        fill = green_fill if conf >= 0.9 else (yellow_fill if conf >= 0.7 else red_fill)
        ws1.cell(row=i, column=3).fill = fill
    
    # Sheet 2: 费率卡
    ws2 = wb.create_sheet("Rate Card")
    for row_data in rate_card:
        ws2.append(row_data)
    
    # Sheet 3: 原始 OCR 文本
    ws3 = wb.create_sheet("Raw OCR")
    ws3.cell(row=1, column=1, value=raw_text)
    
    wb.save(output_path)

完整代码仓库

以上所有代码的完整版本已开源在 GitHub。包含：

contract_intelligence.py — 核心处理管道
app.py — Streamlit 前端
requirements.txt — 全部依赖
sample_contracts/ — 测试用合同样本

最让我惊讶的部分

合同语言其实非常固定——全是 “Whereas”、”indemnify”、”termination”、”force majeure” 这类模板化用语。

这带来一个反直觉的发现：纯向量检索在这种场景下效果反而差。

原因是向量检索擅长语义匹配——”猫”和”狗”语义相似。但合同里所有条款的语义都非常接近（都是法律语言），向量空间里不同条款聚在一起，区分度低。

加上 BM25 做关键词精确匹配后，召回率从 72% 跳到 94%。不是因为 BM25 更好，而是因为两者互补：FAISS 找到语义相关的，BM25 找到关键词精确匹配的，RRF 融合后取两者之长。

说人话的总结

合同审核是”每个公司都有但没人愿意干”的苦活。手动查一份合同 20 分钟，100 份就是 33 个小时。

这套系统把流程压缩到几秒：

步骤	人工	自动化
打开文件	30秒	0秒
查找条款	15分钟	0.5秒
提取数据	5分钟	3秒
生成报表	5分钟	1秒
总计	~25分钟	~5秒

技术组合：LangGraph 做流程编排 + PaddleOCR 做文本提取 + CLAHE 做图像增强 + FAISS+BM25 双路检索 + GPT-4o 做智能提取 + Streamlit 做前端。

如果你还在手动翻合同，这套系统值得一试。从 GitHub 拉下来，5 分钟就能跑起来。

95%的开发者都在用错AI Agent——一份Hermes实战指南

Sat, 06 Jun 2026 00:00:00 +0800

引子
第一层：持久化架构
- 1. SOUL.md 与 /personality
- 2. MEMORY.md 与 USER.md
第二层：执行与版本控制
第三层：路由引擎
- 7. 实时模型切换 — /model
- 8. 辅助模型路由
第四层：分发与自动化
真正的架构视角
我的看法
说人话的总结

引子

45%的人装好Hermes后连跑都没跑起来。另外45%跑了一次，测了一下，然后就忘了。再5%跑得不错，但根本不知道它能做什么。如果你只是在打字、拿答案、关掉标签页——你的运营经济模型就是坏的。

这段话来自一篇上周引爆的技术拆解文章。两位开发者从内部架构的角度，剖析了一个残酷现实：95%的AI Agent用户从未触及工具的真实能力。

持久化内存、会话分支、文件回滚、多模型路由——所有功能都摆在那里，没人用。

以下是12个结构性功能，区分了”游客”和”真正的工程师”。

第一层：持久化架构

1. SOUL.md 与 /personality

每次新会话都要打”你是一个资深Vue.js开发者”？停止重复。

Hermes在启动时自动读取 SOUL.md 文件。只要写在这个文件里的内容，就是Agent在所有会话、所有平台上的永久基准行为。

# 在 SOUL.md 中定义：
你是一个资深全栈开发者
- 优先使用 TypeScript
- 测试覆盖率 > 80%
- 代码必须通过 lint

通过 /personality 命令可以实时切换命名角色：

/personality vue-dev      # 切换到 Vue 前端模式
/personality backend-go   # 切换到 Go 后端模式
/personality devops       # 切换到运维模式

你只需要写一次身份定义。

2. MEMORY.md 与 USER.md

上下文坍塌是生产力的头号杀手。Hermes在每个会话中都读取两个持久化文件。

MEMORY.md — 项目笔记本。记录架构决策、技术债务、已知问题。

USER.md — 用户档案。记录Agent对你的编码习惯的了解。

<!-- MEMORY.md 示例 -->
## 架构决策
- 2026-03-15: 决定使用 Postgres 而非 MySQL，因为需要原生 JSON 查询
- 2026-04-01: CI 流水线从 Jenkins 迁移到 GitHub Actions

## 已知问题
- 登录模块在 Safari 下有 Cookie 兼容性问题（2026-05-10 发现）
- 批量导出超过 1000 条会触发 OOM（2026-04-20 已知）

关键是：它使用 FTS5 全文索引 + LLM 摘要器。八周前发现的一个非常具体的部署问题的修复方案，会在今天的会话中自动浮现。你不再需要重复解释架构。

第二层：执行与版本控制

3. /branch — 会话分支

你正在做一个大规模重构，想尝试一个冒险的架构转向。传统做法要么是烧掉热上下文（开新会话），要么是在当前会话里赌一把。

/branch 就像 git branch 但针对会话：

/branch try-new-architecture

它会精确地分叉当前会话，像 Git commit 一样保存所有上下文。如果实验失败：

/branch main          # 无缝切回主干
/rollback             # 回滚文件变更

不丢失任何状态。

4. /rollback — 文件系统安全网

Agent 幻觉了？直接删了你的配置文件？不用碰 Git。

Hermes 会为它触碰的每个文件保存快照。执行：

/rollback

就是即时文件系统检查点。

/rollback                  # 查看最近变更
/rollback --file config.yml  # 只回滚特定文件
/rollback --ago 30m         # 回滚到30分钟前的状态

5. 飞行中转向 — /steer 与 /queue

Agent已经执行了三步工具调用，正在进行大规模的自动化运行。你突然发现它在操作生产数据库，而不是预发布环境。

不要让进程崩溃。

/steer 用预发布数据库，不要用生产环境

Agent 会在下一个工具调用时截获这个指令，不破坏缓存。

而 /queue 允许你排队后续指令：

/queue 接下来帮我生成测试用例
/queue 然后更新 README
/queue 最后提交 PR

Agent 会按顺序执行，当前操作不中断。

6. 动力开关 — /yolo, /fast, /reasoning

大多数开发者停留在默认设置，然后抱怨速度慢。这三个开关改变Agent的核心运行参数：

/yolo         # 绕过危险命令的人工确认（快速原型阶段）
/fast         # 切换到最快的 API 模型
/reasoning 5  # 手动设定推理深度（1-10）

yolo：跳过”这个操作有风险，确认吗？”的确认框。适合快速原型和信任模式。
fast：切换到低成本快速模型。适合批量处理和数据转换。
reasoning：设定推理深度。/reasoning 10 解决复杂逻辑问题，/reasoning 1 快速完成简单任务。

最佳实践：默认用 fast + reasoning 3，遇到复杂问题时切换到 reasoning 10。

第三层：路由引擎

7. 实时模型切换 — /model

你不被任何一个供应商锁定。

/model anthropic:claude-opus-4-7       # 架构设计用顶级模型
/model openrouter:kimi-k2.6           # 批量数据处理用高性价比模型
/model deepseek:deepseek-v4-flash     # 代码生成用快速模型

所有操作在同一个会话中完成，不丢失状态。上下文完整保留。

8. 辅助模型路由

这可能是最省钱的功能。

Agent 执行大量后台工作：压缩上下文、总结会话、生成聊天标题。如果你把所有工作都通过前沿模型处理，API 成本会让你破产。

Hermes允许你把主逻辑路由到 Opus 4.7（高质量），而把后台压缩卸载给 Haiku（低成本）：

# 在配置中设定：
main_model: anthropic:claude-opus-4-7
aux_model: anthropic:claude-haiku-3-5  # 压缩、摘要等后台工作

主模型保持输出质量，辅助模型控制成本。这一项就能把月度 API 开销砍掉 60-70%。

第四层：分发与自动化

9. 17平台网关

Hermes 不局限于一个终端窗口。单个 Hermes 进程同时驱动 17 个不同的平台：

聊天平台：Telegram / Discord / Slack / WhatsApp / Signal / SMS
开发工具：CLI / VS Code 插件 / Web 界面
协作平台：钉钉 / 飞书 / 邮件

你在手机 Telegram 上发出的指令，和在终端里输入的效果完全一样。Agent 状态是统一的。

10. 实时语音 — /voice

跨 CLI、Telegram 和 Discord 可用。

/voice

直接对 Agent 说话。当你离开键盘或开车时，可以用语音推送架构更新或口述文档草稿。

对移动场景特别实用：你在通勤路上发现了一个架构问题，直接说话让 Agent 准备好修复方案，到办公室就能直接审查。

11. Cron + Webhook 订阅

这完全消除了对 Zapier/IFTTT 的需求。

# 自然语言定时任务
"每周五下午5点，总结本周的 GitHub 提交记录，发到 Slack #standups 频道"

结合 webhook：

# 订阅 GitHub webhook
/webhook-subscriptions add github:repo-events
当有新的 PR 提交时，自动进行 Code Review

平台如 GitHub、Vercel、Stripe 可以将 payload 直接推送到 Agent 的私信，零 Token 延迟。

你不再需要第三方自动化平台。

12. 自定义命令 — Skills

这是最终的杠杆点。

Hermes 内置了 100+ 现成的斜杠命令：

/architecture-diagram     # 生成架构图
/systematic-debugging     # 系统化调试
/codebase-inspection      # 代码库体检
/github-code-review       # PR 代码审查
/toutiao-publish          # 头条发布

但真正的力量是构建你自己的命令。

# 一个自定义 skill 示例
# 写一个脚本，抓取特定数据源，格式化，执行工作流
# 映射到自定义命令，然后在任何平台上无缝运行

书写 SKILL.md，定义触发条件、步骤、验证逻辑。一旦注册，它可以在所有 17 个平台上通过 /your-command 触发。

这就是你个人专属的 AI 工作流引擎。

真正的架构视角

让我把整件事总结成一个简单的模型：

用户输入
    │
    ▼
┌────────────────────────┐
│    SOUL.md + 身份层    │ ← 永久角色定义
├────────────────────────┤
│   MEMORY.md + USER.md  │ ← 持久化上下文
├────────────────────────┤
│   路由引擎 (/model)    │ ← 动态模型切换
├────────────────────────┤
│   执行引擎 (/steer)    │ ← 飞行中转向
├────────────────────────┤
│   安全网 (/rollback)   │ ← 文件系统保护
├────────────────────────┤
│   自动化层 (cron+skill) │ ← 无人值守运行
├────────────────────────┤
│  分发层 (17 平台)      │ ← 无处不在的入口
└────────────────────────┘
    │
    ▼
  输出

大多数用户只接触了最上层——他们在终端里输入提示词，拿到答案，关掉窗口。

整个基础设施都在下面，从没人碰过。

我的看法

我从两个月前开始系统性地使用 Hermes 的这些高级功能——特别是 SOUL.md 持久化配置和辅助模型路由。变化是显著的。

首先是上下文坍塌彻底消失了。以前每个新会话我都要花 5-10 分钟重新建立上下文（”这是一个 Vue 项目，使用 Nuxt 3，UI 库是 PrimeVue…“）。现在 SOUL.md 自动加载，Agent 从第一句就知道它面对的是什么项目。

其次是费用。我的月度 API 账单从大约 $120 降到了 $40 左右——主要归功于辅助模型路由。代码生成和架构设计仍然用 Opus，但上下文压缩和会话摘要全部走 Haiku。

最让我惊讶的是 /steer。曾经我以为 Agent 一旦开始执行，就只能让它跑完或者杀掉进程。现在可以在执行中途改变方向——”不要用那个 API，用新的那个版本”——这改变了整个工作流。

如果你还在每次会话中手动输入”你是一个资深开发者”，你就是在用一台超级计算机做计算器的工作。

说人话的总结

把这套系统想象成一个交响乐团：

SOUL.md 是乐谱——定义了乐队要演奏什么音乐
MEMORY.md 是排练笔记——记录了哪些段落需要特别注意
/model 是乐器调换——需要大提琴的时候换上大提琴，需要小提琴的时候就换
/steer 是指挥的实时手势——乐手在演奏中看到
Skills 是谱好的乐章组合——一整套编排好的工作流

大多数人做了什么？他们只拿了一把小提琴，要求它演奏整场音乐会。

工具早已准备好。你需要的是给对的指令。

别再写 Spec 了，开始写 Facts——整个 SDD 运动已经过时

Fri, 05 Jun 2026 00:00:00 +0800

1. 核心矛盾：Spec 是对模型的预测，不是与模型的契约
2. 为什么 Spec 注定不靠谱
3. 什么是 Fact：一个可执行断言
- 57 年的连续性
4. SDD 依然有用的三个场景
5. 90 天迁移计划
6. 六个结论
7. 总结

1. 核心矛盾：Spec 是对模型的预测，不是与模型的契约

Spec-Driven Development（SDD）在过去十个月里爆发式增长：Spec Kit 获近九万星、Kiro 来自 AWS、OpenSpec 半年三位数增长、BMAD 近五万星——五个主要框架加起来超过二十万 GitHub Star。

但作者 Jaroslaw Wasowski 今天要收回自己之前写的五篇鼓吹 SDD 的文章。

理由很简单：一份在 Sonnet 3.5 时代写的单元测试，穿越了 3.7、4、Opus 4.5+ 四个模型版本依然通过 CI。而描述同一 endpoint 的 1500 字 spec，被每个模型重新理解了一遍——四次重解释。

Spec 不是契约，是对模型的预测。模型在变，预测就永远不准。

2. 为什么 Spec 注定不靠谱

非确定性机制

LLM 读同一段 prose，本质是在回答”这个句子统计上最可能是什么意思”，而不是”作者精确想表达什么”。即使在 temperature 0.0 下，独立研究显示同一 prompt 在确定性模式下产生了 80 个不同的输出。

根本原因不是 prompt 写得不好——是系统性的：浮点数非结合性、批调度、fused-attention kernel。这些你没法用更好的 prose 修复。

最反直觉的数据来自 IBM 在金融领域的 RAG 研究：100B+ 模型在同 prompt 下只有 12.5% 的 run 产生完全一致输出，而 7-8B 的小模型却能做到完全一致。

“等模型变好 spec 就能用了”这个策略，恰恰和实际趋势相反。

意图差距（Intent Gap）

微软研究院的 Shuvendu K. Lahiri 称之为 intent gap——”AI 生成的代码看起来合理，但不是构建时确保正确”。自然语言 spec 是 informal 且不可检验的。SDD 把”一个统计近似”当成了”一个答案”。

Spec Drift

Spec Kit 在 2026 年 5 月发布了 /speckit.spec-drift 命令。一个框架需要专门出一个命令来处理 spec 漂移——这本身就证明了 drift 是真实的运营风险。

3. 什么是 Fact：一个可执行断言

Fact 就是机器能自己检查的东西。测试通过/失败，exit code 0 或非 0。不需要模型解读，不需要采样，没有情绪。

粒度分三层：

单个测试：一个输入/输出对
属性（Property）：全称量词谓词——”对所有已排序列表，binary_search 的结果都是正确的”
契约（Contract）：前置条件 + 后置条件 + 不变式（Design by Contract 风格）

每一个都是可执行断言，运行时验证，通过或失败。没有”看情况”。

57 年的连续性

Facts-first 不是新范式，是 57 年零散工作的 AI 时代综合：

1969：Hoare triple {P} C {Q}——行为的最小事实单元
1992：Bertrand Meyer 的 Design by Contract——require/ensure/invariant
2000：QuickCheck——属性基测试
2026：Agent Behavioral Contracts——AI 时代延续

John Hughes 在 Quviq 的真实案例：六万行生产 Erlang 代码，450 行 PBT 测试，检测出 25 个 bug——包括例子测试无法触及的 race condition。测试代码与生产代码比例为 1:133。

4. SDD 依然有用的三个场景

作者坦诚地给出了 SDD 的适用边界：

合规与监管：DO-178C、ISO 26262、EU AI Act——这里 Ceremony 就是产品本身
跨团队 B2B 集成：五百个工程师二十个团队时，协调成本超过实现成本
新人入职与知识传递：新人读 spec，不是读测试

一个简单的判断标准：这个制品会被团队以外的人阅读吗？ 审计、合作伙伴、新员工——是，则保留为 SDD。不是，则迁移到事实集。

5. 90 天迁移计划

Phase 1 — 审计（第 1-30 天）

把现存 spec 分成三堆：

团队成员以外的人会读的 → 保留（SDD zone）
没人打开过的死文档 → 弃用候选
生产中只有 prose 声明的隐式不变量 → 溯源候选

用 agent 反向工程运行时不变量。交付物：@draft 事实列表 + 弃用候选列表。

Phase 2 — 转向（第 31-60 天）

把边界 spec 转为事实：API 契约 → Pact 测试，属性/不变量 → Hypothesis 或 QuickCheck，数据模型不变量 → 运行时断言。

新功能并行运行 30 天——spec 和事实共存，获得 A/B 置信度。

Phase 3 — 门禁（第 61-90 天）

facts check 成为必须通过的 CI 步骤，阻断合并。新功能需要在实现前先写一个会失败的事实——TDD 节奏的新外衣。

实践经验：Facts check 验证整个仓库使用的 tokens 比朗读一次 spec 还少。迁移不仅降低认知开销，还节省 API 费用。

6. 六个结论

Spec 是对模型的预测，不是与模型的契约。 Prose 每次调用都被 LLM 采样——0 温度也不例外。
Fact = 机器可检验的可执行不变量。 它穿越模型升级，因为它不经过模型解读。
SDD 在审计、合作伙伴、新员工会读的地方获胜。 其他地方它都输了。
90 天迁移：审计 → 转向 → 门禁。 每个阶段都有独立的 ROI 信号。
从明天早上开始： 挑一个只存在于 spec 中的不变量，写一个测试，加入 CI。这，就是一个事实。
归根结底： PRD 会消失。Spec 正在退出内循环。只有事实在哪儿都能活。

7. 总结

SDD 赢得了工具战争——近九万 Star、二十万生态星。但它输掉了认识论战争：非确定性、意图差距、spec drift 不是待修复的 bug，它们是系统的运作方式。

Facts-first 不是新范式，是 57 年形式化方法的 AI 时代合成。从 Hoare triple 到 Agent Behavioral Contracts，正确的道路一直存在——只是在 AI 时代才真正找到了用武之地。

从明天开始，写一个事实。就一个。一天也行。