Peter 的技术笔记

AGENTS.md 怎么写：Matt Pocock 指南要点

Fri, 16 Oct 2026 00:00:00 GMT

来源：Matt Pocock，A Complete Guide To AGENTS.md；以及他的 Dictionary of AI Coding · AGENTS.md 词条。

AGENTS.md 是什么

一个提交进 Git 的 Markdown 文件，用来定制 AI 编码 agent 在仓库里的行为。它被放在对话历史的最前面、紧挨着 system prompt。Claude Code 读的是 CLAUDE.md，可以用软链让各工具共用一份：

Terminal window

ln -s AGENTS.md CLAUDE.md

核心问题：它每次请求都会加载

每个 token 在每次请求里都要付费，不管和当前任务有没有关系。
指令预算有限：前沿推理模型大约只能稳定遵循 150–200 条指令，小模型更少。指令越多，任何一条被遵守的概率越低。
过时文档会“毒化”上下文：人看到旧文档会怀疑，agent 会照着错路径自信地去找。尤其别写具体文件路径，改写“能力和项目形状”；领域概念比路径稳定，但也要轻写。

文件变大的典型循环：agent 做了你不喜欢的事 → 加一条规则 → 重复几个月 → 变成一团“泥球”。

不要用初始化脚本自动生成 AGENTS.md——生成的内容追求面面俱到，而这些本该渐进披露。

根目录只放最少的东西

一句话项目描述（相当于角色提示），例如：This is a React component library for accessible data visualization.
包管理器（如果不是 npm），例如：This project uses pnpm workspaces.（也可以用 corepack 让系统自己报警，省预算）
非标准的构建 / 类型检查命令

就这些，其余都放到别处。

渐进披露（Progressive Disclosure）

把语言规范、测试约定等拆成单独文件，根文件里只轻轻引用一句：

For TypeScript conventions, see docs/TYPESCRIPT.md

不用 “ALWAYS”、不用全大写强调。好处：只有写 TypeScript 时才加载这些规则，其他任务不浪费 token。文档之间还可以继续嵌套引用（TYPESCRIPT.md → TESTING.md → 具体测试工具），也可以链到外部官方文档。Agent Skills 是另一种渐进披露形式（参见 Hermes × Agent Skills 笔记）。

Monorepo：嵌套 AGENTS.md

子目录里的 AGENTS.md 会和根目录合并：

层级	内容
根目录	monorepo 的用途、如何在包之间导航、共享工具（如 pnpm workspaces）
包目录	该包的用途、技术栈、包内约定

每一层都别塞满——agent 会同时看到所有合并后的文件。

一键瘦身 Prompt（意译）

让 agent 按渐进披露重构现有 AGENTS.md：

找矛盾：列出互相冲突的指令，逐条问我保留哪个；
提取必要项：一句话描述、包管理器、非标准构建命令、真正每个任务都相关的内容；
分组其余内容：按 TypeScript 约定、测试、API 设计、Git 流程等分类，各建一个文件；
输出结构：最小化的根 AGENTS.md（带链接）+ 各分文件 + 建议的 docs/ 目录；
标记删除：冗余的（agent 本来就知道）、太模糊无法执行的、过于显然的（如“写干净的代码”）。

原文英文 prompt 见原文末尾。

词条补充：什么时候该加一行

Matt 的 AI Coding 词典对 AGENTS.md 的定义：harness 在会话开始时载入上下文窗口的文件，是项目给 agent 的“常驻简报”。

模型是无状态的，上一个会话里的纠正下一个会话就没了。同一件事纠正过 agent 两次，它就是 AGENTS.md 的候选行。
适合写的是 agent 从代码里推不出来的东西：构建/测试命令、代码里看不出的约定、硬约束（如“永远不要改生成的 client”）。简短、陈述式——它是简报，不是文档。
避免：把本该渐进披露的内容（如整份风格指南）塞进来；那应该放到 skill 或上下文指针后面。

放在哪：决策表

位置	什么时候用
根 AGENTS.md	和仓库里每一个任务都相关
单独文件	只和某个领域相关（TypeScript、测试等）
嵌套文档树	可以分层组织的内容

理想的 AGENTS.md：小、聚焦、指向别处。

让 LLM 把东西讲明白：Karpathy 的输出格式阶梯与 LLM 使用技巧

Fri, 16 Oct 2026 00:00:00 GMT

来源：Andrej Karpathy 2026-10-02 的 X 帖子（全文整理见 Way Into AI）；ASD-STE100 规则引自官方 ASD-STE100 Issue 9；日常技巧来自他 2025-02-27 发布的视频 How I use LLMs。

说明：标注“【个人补充】”的内容是我的理解与实践建议，不是 Karpathy 原话。

为什么要关心“怎么让 LLM 讲明白”

Karpathy 帖子的出发点是：我们会花越来越多的时间去理解语言模型的输出。

模型在做越来越多的“体力活”。写代码、查资料、跑分析，越来越多由 agent 自主完成；人的工作会“沿着抽象层往上走”，变成 监督（oversight）与理解（understanding）。
瓶颈从“产出”变成“读懂”。Agent 一晚上能产出几千行 diff、几十页报告，人能不能快速、准确地看懂，决定了监督是否有效。
好在 LLM 本身也能帮忙。智能和代码越来越廉价，你可以要“大型、定制、用完即弃”的软件制品——一个只为解释这一次改动的交互网页、一段只给你自己看的讲解视频。以前这种东西做起来太贵，根本不值得；现在值得了。

他给出的办法是一个逐级升级的输出格式阶梯，每一级都“But even better”：

图 1 · 输出格式阶梯（每升一级都 “But even better”）

① 写作ASD-STE100 受控英语② 图表 / 图片③ HTML 交互网页④ 定制讲解视频3b1b 风格 + 配音

← 成本最低、最易审阅表达力最强、制作成本最高 →

阶梯一：写作 → 用 ASD-STE100

原文要点

让 LLM 用 ASD-STE100 解释东西。它是一套受控语言规范，最初为航空维修文档开发。Karpathy 说 LLM 很熟悉这套规范，而它对“干净的写作风格”有很重的约束，读起来往往更易懂。规范太严时可以放松：要求 “80% of the way to ASD-STE100”。

ASD-STE100 到底约束了什么

ASD-STE100（Simplified Technical English，简化技术英语）由 ASD（欧洲航空航天与防务工业协会）维护，当前为 Issue 9。以下规则摘自官方规范原文：

类别	规则（官方条款）
词汇	只用词典批准的词（Rule 1.1）；一般来说每个词只有一个含义、一个词性——例如 fall 只表示“受重力向下移动”，不表示“下降/减少”；同义词只保留一个，如只用 start，不用 begin / commence / initiate
语态	使用主动语态；描述性文字中只有在不知道动作发出者时才可用被动（Rule 3.6）
过程性句子（操作步骤）	每句最多 20 词（Rule 5.1）；每句只写一条指令，除非多个动作同时发生（Rule 5.2）
描述性句子	每句最多 25 词（Rule 6.3）；逐步给出信息（Rule 6.1）；用关键词组织逻辑结构（Rule 6.2）
段落	每段只讲一个主题（Rule 6.5）；每段不超过六句（Rule 6.6）
衔接	用连接词把相关主题的句子连起来（Rule 4.4）

注：常见的“一句一个主题”说法，在官方规范里对应的是“过程性句子一句一条指令”和“段落一个主题”；严格说并没有单独的“一句一个主题”条款。

为什么它对“读懂 LLM 输出”有效【个人补充】：

短句 = 低工作记忆负担。20/25 词上限迫使模型把长难句拆开，每句只承载一个信息点。
一词一义 = 消除歧义。LLM 平时爱用同义词换着说，读者会怀疑“这两个词是不是两回事”；受控词汇把这种噪音砍掉。
主动语态 = 谁做了什么一目了然。“配置被加载”变成“服务加载配置”，责任主体清楚。
逐步给信息 = 天然的结构。先结论、再细节，正好适合审阅。
难以藏住“空话”。在严格的格式下，含糊、绕弯的表述很难伪装成内容。

改写示例（Before / After）

Before（典型的 LLM 风格）：

The caching layer, which was introduced in order to mitigate the latency issues that were being experienced by users during peak traffic periods, leverages a write-through strategy that ensures data consistency is maintained between the cache and the underlying database, although it should be noted that cache invalidation may occasionally be delayed under certain conditions.

一句 60 多个词，三处被动，leverage / mitigate 这类非批准词，还把“为什么引入、怎么工作、有什么问题”塞进同一句。

After（接近 ASD-STE100）：

The cache decreases latency during peak traffic. It uses a write-through strategy. Each write goes to the cache and to the database at the same time. Thus, the data in the cache and the data in the database stay the same. Sometimes the system removes old cache data late. This can occur when the load is high.

每句一个信息点、主动语态、都在 25 词以内。【个人补充】最后一句的“when the load is high”是改写时补上的具体条件——原文只写了 “under certain conditions”。这正是风险点：改写会让模型倾向于把模糊表述“具体化”，你必须核对它补的条件是否真实（见下文“注意事项”）。

Prompt 模板

English：

Explain the following in ASD-STE100 Simplified Technical English
(about 80% of the way to strict STE: keep technical terms, allow common words if needed).
Rules: active voice; max 20 words per instruction, max 25 words per descriptive sentence;
one instruction per sentence; one topic per paragraph, max 6 sentences;
use one word for one meaning and keep it consistent.
Do not add facts, numbers, or conditions that are not in the source.
Keep all technical terms, identifiers, and code unchanged.

<content>

中文（适合中文读者的“受控中文”变体）【个人补充】：

请用接近 ASD-STE100 的风格解释下面的内容，输出中文：
- 用主动语态，明确“谁做了什么”；
- 操作步骤一步一句、每句只有一个动作；说明性句子尽量短（约 40 字以内）；
- 每段只讲一个主题，不超过 6 句；
- 同一个概念始终用同一个词，不要换同义词；
- 技术术语、标识符、代码、数字和条件原样保留，不要补充原文没有的事实。

<内容>

阶梯二：图表 / 图片

原文要点

别要文字，让 LLM 画图。图更容易处理、解析和理解。

为什么有效【个人补充】

结构外显：依赖关系、时序、状态转换这类信息，本来就是“图形状”的；用文字表达等于让读者在脑子里重建图。
一眼发现异常：环形依赖、孤立节点、缺失的分支，在图上非常显眼，在文字里很容易被略过。
可审阅、可 diff：让模型输出 Mermaid / Graphviz / PlantUML 这类“图即代码”，既能渲染，又能放进 Git 跟踪变化；也可以直接让它输出纯 HTML/CSS 或 SVG 图（本文的图就是纯 HTML/CSS，不依赖 JS）。

Prompt 模板

Draw a diagram that explains <topic>. Output Mermaid code only.
Pick the best diagram type (flowchart / sequenceDiagram / stateDiagram / classDiagram).
Max 15 nodes. Label every edge with the action or data that flows.
Mark anything you are unsure about with "?" in the label.

用一张图解释 <主题>，只输出 Mermaid 代码。
自行选择最合适的类型（流程图 / 时序图 / 状态图 / 类图）；
节点不超过 15 个；每条边标注发生的动作或流动的数据；
不确定的地方在标签里加“?”。

阶梯三：HTML 网页

原文要点

要求输出 “in HTML”，得到漂亮、可交互的网页。LLM 的前端能力越来越强，能做出漂亮的体验和动画。

为什么有效【个人补充】

交互 = 让读者自己探索：滑块调参数、折叠细节、悬停看定义，读者按自己的节奏理解，而不是被动读一长段。
单文件、零依赖、可丢弃：一个 HTML 文件双击就能打开；看完就扔，不需要“维护”。
多种表达组合：一页里可以同时有文字摘要、图、表格、可运行的小例子。

Prompt 模板

Create a single self-contained HTML file (inline CSS/JS, no external requests)
that explains <topic> interactively.
Include: a 3-sentence summary at the top, one interactive element
(slider / toggle / step-through) that shows how <key variable> changes the result,
and a "Sources & assumptions" section listing what is from the input vs. what you assumed.

做一个单文件 HTML（CSS/JS 内联，不请求任何外部资源），交互式讲解 <主题>：
- 顶部 3 句话摘要；
- 至少一个交互元素（滑块 / 开关 / 分步播放），展示 <关键变量> 如何影响结果；
- 底部“来源与假设”区，区分哪些来自输入、哪些是你的假设。

安全提示【个人补充】：打开前先看一眼代码，确认没有外部请求或可疑脚本；要求“no external requests”也能顺便保护隐私。

阶梯四：定制讲解视频

原文要点

Karpathy 最看好的输出形式：针对任意主题完全定制的讲解视频。可以试：

Create a 3b1b style video explainer on X. Use my ElevenLabs API key for audio narration.

配音需要 API Key；也可以让 LLM 帮你找能用本地算力的免费替代方案。他说这“真的开始能用了”。

为什么有效【个人补充】

时间维度：动画能一步步展示过程（算法的每一步、数据怎么流动），这是静态图做不到的。
双通道：画面 + 旁白同时进入，适合抽象、数学化的概念（3Blue1Brown 风格正是以此著称）。
门槛在快速下降：模型能写动画代码（例如 3b1b 开源的 Manim 库），再调用 TTS 合成配音、拼成视频。

Prompt 模板

Create a 3Blue1Brown-style explainer video on <topic>, about 2–3 minutes.
1. Write a narration script first (short sentences) and show it to me for approval.
2. Then write Manim (Python) code for the animation, one scene per script section.
3. For narration, use <ElevenLabs with my API key | a free local TTS model you recommend>.
4. Combine audio and video with ffmpeg. Give me the exact commands to run.

为 <主题> 做一个 3Blue1Brown 风格的讲解视频，约 2–3 分钟：
1. 先写旁白脚本（短句），给我确认；
2. 再用 Manim（Python）写动画，每段脚本对应一个场景；
3. 配音使用 <我的 ElevenLabs API Key | 你推荐的本地免费 TTS>；
4. 用 ffmpeg 合成音视频，并给出可直接运行的命令。

怎么选：按内容类型挑输出格式【个人补充】

阶梯是“越往上越好”，但不是每次都要爬到顶。成本、审阅速度和内容形状都要考虑：

图 2 · 按内容类型选择输出格式

要理解的内容

是操作步骤 / 结论 / 规格？是① ASD-STE100 风格文字

否

核心是结构 / 依赖 / 时序？是② Mermaid / 图

否

需要调参数、对比或探索？是③ 单文件 HTML

否

是抽象过程，且值得反复看或分享？是④ 讲解视频

否

都不是① 文字即可

无论选哪种：保留原文对照，核对关键结论

注意事项【个人补充】

保留原文对照。改写、画图、做网页都是“有损翻译”；把原始输出（日志、diff、原文）放在旁边，遇到疑问回到原文。
术语和条件不能丢。简化最容易误伤的是限定条件（“仅在……时”“除非……”）和专有术语；在 prompt 里明确要求原样保留。
承重结论必须核实。任何你要据此做决定的数字、因果、结论，回到源头验证；模型会为了“讲清楚”而补全它并不知道的细节（见上面的 Before/After 例子）。
隐私与托管 TTS。把内部代码、文档的讲解稿发给 ElevenLabs 这类托管服务，等于把内容交给第三方；敏感材料用本地 TTS，API Key 不要写进脚本或提交进仓库。
用完即弃，别维护。这些制品的价值在“这一次理解”；需要长期留存的，再整理成正式文档。

背后的“为什么”：监督循环

把上面串起来，就是 Karpathy 所说的“人的工作上移到监督与理解”的一个具体闭环：

图 3 · 监督循环

Agent 完成工作代码、分析、报告人请求可读制品摘要、图、网页、视频人审阅对照原文、核对结论符合预期？是接受 / 合并

否 → 人给出具体纠正 → 回到「Agent 完成工作」

关键在 B：不是去读 agent 的原始产出，而是让它为你生成一个“专门用来理解”的制品——而这种制品现在已经便宜到可以每次都做一个。

How I use LLMs：Karpathy 的日常工作流

视频 How I use LLMs（2025-02-27）是一份面向大众的实用指南。以下要点均能在视频中找到对应内容：

图 4 · Karpathy 的日常 LLM 工作流

新话题 / 新问题

开一个新对话清空上下文

按任务难度选模型

快速模型简单问答、写作Thinking 推理模型数学、代码、复杂推理

需要外部信息或计算？

联网搜索 / Deep Research最新信息代码解释器（Python）计算、数据分析上传原文文档、论文、书直接回答不需要工具

核对读代码、看来源、查关键数字

是重要决定吗？是LLM Council：问多个模型对照

否

完成

1. 一个话题开一个新对话

上下文窗口是模型的“工作记忆”。换话题时开新对话，把 token 清零。原因有二：大量无关 token 会分散模型注意力、降低准确度；token 越多，生成也越慢、越贵。

实践【个人补充】：长任务做到一半感觉模型“变笨”，先让它总结当前进度，再把总结贴进新对话继续。

2. 按任务选模型，并知道自己在用哪个

不同档位、不同厂商的模型能力差别很大（他特别提醒免费档往往是更小的模型）。简单问题用普通模型，数学、代码、复杂推理用 thinking 模型——它们会“想”更久，难题上更准；简单问题则没必要。

3. 用工具，而不是让模型“心算”

模型本身只是“一个 zip 文件”，没有计算器、没有浏览器。所以：

需要最新信息时，用带搜索的模型或 Deep Research，并去看引用来源；
需要计算 / 数据分析时，让它写代码并在解释器里运行。

视频里有个例子：他让 ChatGPT 拟合估值趋势外推到 2030 年，模型嘴上说约 1.7 万亿，但代码里实际算出来的变量约 20 万亿——两者不一致。他的结论是：一定要读它写的代码、核对结果。

4. 把上下文直接给它

读论文、读书时，把原文上传进上下文，再一起读、让它解释、回答问题，而不是指望模型凭训练记忆回答。

5. 记忆与自定义指令

ChatGPT 等产品可以在对话间记住关于你的信息（memory），也可以在设置里写 custom instructions（例如希望的语气、你的背景），对所有对话全局生效，省去每次重复说明。

6. LLM Council：多个模型一起问

他会订阅多家模型，把同一个问题问所有模型，称之为自己的“LLM Council”（例如决定去哪度假时）。后来他把这个思路做成了开源项目 llm-council：多个模型分别作答、互相评审，再由一个“主席”模型汇总。

7. 其他他提到的用法（简列）

语音输入与原生语音对话（Advanced Voice Mode）、NotebookLM 把资料生成播客、在 Cursor 这类编辑器里写代码、用 Claude Artifacts 生成小应用（如抽认卡）。

小结

问题：agent 产出越来越多，人的瓶颈变成“读懂与监督”。
方法：让 LLM 用更易懂的形式输出——受控英语 → 图 → 网页 → 视频，按内容挑选。
底线：保留原文、保住术语和条件、核实承重结论、注意隐私。
日常：新话题新对话、按任务选模型、用工具不心算、给足上下文、善用记忆、重要问题开“议会”。

AI 中转站到底在干什么？我读了 Sub2API、AIClient2API、OneAPI 和 NewAPI 的源码

Tue, 08 Sep 2026 00:00:00 GMT

TL;DR 这几个中转站对外长得一模一样，都是 OpenAI 兼容接口。差别在上游。OneAPI 和 NewAPI 拿的是厂商发的 API Key，Sub2API 拿的是订阅账号的登录态，AIClient2API 干脆把请求伪装成官方客户端发出去。风险几乎都出在凭据放在哪、出站请求由谁发、有没有闭源插件和指纹伪装。我要是自建，骨架照 OneAPI 来，另外两个项目当调度和协议转换的参考书读。

中转站这东西，用大模型的人多半碰过。对方给你一个 sk-xxx 和一个 Base URL，接口跟 OpenAI 一样，价格便宜一截，Claude 和 Gemini 也能调。

我一直不太放心。prompt 和代码都要从它那里过，钱也押在它那里。它的上游能力从哪来，凭据怎么存，哪天出了问题会不会悄悄换一个别人的号给我用，这些我都不知道。

想自己搭一个之前，我先把几个主流开源实现读了一遍。主角是 Sub2API 和 AIClient2API（下文简称 A2），对照组是老牌的 OneAPI 和它的增强分支 NewAPI。这篇只聊架构和风险，盗号、绕过订阅条款、倒卖额度这些不碰。

先交代两个词。中转站就是一个 HTTP 服务，对下游露出跟 OpenAI 一样的接口，比如 /v1/chat/completions，再把请求转给真正提供模型的那一方，也就是上游。上游凭据是中转站拿去调上游用的东西，可能是厂商发的 API Key，也可能是某个账号的登录 token 或 cookie。几个项目性质上的差别，基本都落在这一项上。

一个中转站大致分六层

四个项目拆开来，层次差不多。

图 1 · 中转站的六层，从下游请求进来到上游返回

接入面露出 /v1/chat/completions 这类兼容接口，支持 SSE 流式返回

下游鉴权校验用户带来的 API Key 或 Bearer token

调度这次请求用上游哪个 Key、哪个账号，涉及粘性、权重、健康检查和失败切换

协议适配在 OpenAI、Claude、Gemini 和厂商私有协议之间互转

计量统计 token，先预扣再实扣，按倍率计费

管理面后台里的账号、分组、用户、支付和看板

上面两层和下面两层，各家写法大同小异。决定一个项目是什么性质的，是调度那一层手里攥着什么，也就是上游凭据的来路。

同样的外壳，三种上游

读完代码，我觉得全文最要紧的就是下面这张图。

图 2 · 同一个 OpenAI 兼容外壳，三种上游

① Key 转发OneAPI 和 NewAPI上游拿的是厂商或代理商发的 API Key改一改 URL、请求头和请求体，调用公开的 HTTP API风险最低，走的都是官方写进文档的接口

② 订阅账号池Sub2API上游拿的是订阅账号的 OAuth 登录态在一池账号里挑一个，用它的身份去打上游可能违反上游服务条款，手里攥的凭据也多

③ 客户端模拟AIClient2API上游拿的是 CLI、IDE 或浏览器里的登录态把请求拼得像官方客户端，连 TLS 指纹都仿风险最高，项目本来就是冲着模拟去的

网上聊中转站，常把这几个项目放在一起比。它们要解决的事各不相同，风险也差着量级。自建的话，我会先定用哪种模式，再去挑模块抄，三种混成一个模板只会越改越乱。

Sub2API，一套完整的订阅账号池网关

Sub2API 的定位写得很明白。平台给用户发 Key，自己拿一池订阅账号去调上游。它的 README 也自己承认了，这么做可能违反上游的服务条款，仅供学习。

技术栈是写后端的人很熟的那一套。Go 和 Gin 处理 HTTP，Ent 做 ORM，Wire 做依赖注入，PostgreSQL 存数据，Redis 记会话粘性，前端用 Vue 3。支付是内置的，易支付、支付宝、微信、Stripe 都接了。插件系统基于 HashiCorp 的 go-plugin。

一次请求怎么走

拿 POST /v1/chat/completions 举例。网关路由先看这把 API Key 属于哪个分组，再按分组的平台分流。走 OpenAI 兼容这条路时，顺序是这样的。

图 3 · Sub2API 处理一次 chat/completions 请求

客户端API Key 鉴权HandlerServiceRedis上游账号

客户端 → 鉴权带着 Bearer sk-xxx 请求 chat/completions

鉴权加载 Key、用户和分组，检查余额够不够

鉴权 → Handler检查模型白名单，组合分组按模型路由到具体平台

Handler → Service算出会话 hash，后面靠它做粘性

Service → Redis同一个会话尽量落到同一个账号上

Service按优先级、RPM、时间窗口和利润控制挑账号

Service → 上游账号用账号身份转发，流式返回

上游 → 客户端SSE 数据块原样流回去

Service异步记用量，扣配额

调度写得很扎实。粘性会话、分组白名单、按模型解析的组合分组、流式过程里的失败切换，结构都清楚，我会拿来学。

读完不放心的几处

上游凭据是明文 JSON。 账号表里有一个 PostgreSQL 的 jsonb 字段叫 credentials，API Key、OAuth token、cookie 都塞在里面。接口返回时会脱敏，可我在表结构和存储层都没找到落盘加密。数据库备份一旦泄露，所有上游账号会一起泄露。
插件可以是闭源二进制。 插件走 go-plugin 加 gRPC，打包格式允许夹带编译好的程序。主进程手里有真实的上游 Authorization，插件也没有关进操作系统级的沙箱。
支付是内置的，资金和更多密钥也跟着进了攻击面。
代码里有一个专门的 TLS 指纹库，用途是让出站流量更像官方客户端，合规和封号的风险都在这里。
它的部署文档专门提醒过，信任转发 IP 的那个开关配错了，IP 白名单可以被伪造。

这些问题都是订阅账号池这个产品目标带出来的，我不觉得代码写得差。它是一个功能很全的商业中转样本，同时也是信任面最大的那一个。

AIClient2API，把只能在官方客户端里用的通道搬到本地

A2 走的是另一条路。有些模型能力只能在官方 CLI、IDE 插件或网页里用，A2 把这些客户端的请求方式模拟出来，在本机露出 OpenAI、Claude、Gemini 兼容的接口。

它用纯 Node.js 写，没上 Express，直接 http.createServer。架构里有几块值得单独说说。

Adapter。每个上游一个适配器，生成内容、流式输出、列模型、刷新 token 这些动作都统一起来。
Strategy 和 Converter。先按下游协议取出模型名、判断是不是流式，再在 OpenAI、Claude、Gemini 三种格式之间转换请求、响应和流式数据块。
凭据池。给每个节点打分，看健康程度、最近有没有用过、当前并发多少，出错就换一个。
TLS sidecar。一个 Go 写的小服务，用 utls 库把 TLS 握手伪装成 Chrome，默认监听 9090 端口。

图 4 · AIClient2API 怎样把一次请求变成像官方客户端的流量

OpenAI 格式请求按路径首段选上游校验入站 Key凭据池打分选节点协议转换拼客户端请求头和 OAuth经 TLS sidecar 发出转回 OpenAI 的 SSE

出错时把节点标成不健康，换一个凭据重试。认证错误默认最多换 5 次，累计 10 次错误就标记为不健康

协议转换和凭据池是我觉得 A2 最值得读的两块。分层干净，接一个新上游只需要补一个 Adapter 和对应的实现。

弱点和风险

登录态直接落盘，OAuth token 和 cookie 存在配置目录和用户家目录里。
源码里写死了公开的 OAuth client 身份。 已安装的客户端应用这么干很常见，但它终归是一个写死的固定身份。
它的设计目标就是模拟客户端，调用的也不是写进文档的公开 API。服务条款和封号风险跟着设计来，配置改不掉。
默认管理密码是 admin123。 部署时不改，等于没设。
TLS sidecar 对 Node 主进程来说，是一条看不太清的出站通道。

四个项目放一起比

表 · 四个开源中转项目对比，窄屏可以左右滑动

	OneAPI	NewAPI	Sub2API	AIClient2API
定位	API Key 聚合转发	OneAPI 增强版，网关加资产管理	订阅账号配额分发	把客户端通道变成本地兼容 API
许可证	MIT	AGPL-3.0	LGPL-3.0	GPL-3.0
技术栈	Go 和 Gin	Go 和 Gin	Go、Gin、Ent、Vue	Node.js 原生 http
上游凭据	厂商 API Key	API Key，部分渠道支持 OAuth	订阅账号 OAuth	CLI、IDE、浏览器登录态
适配方式	统一的 Adaptor 接口	渠道加跨协议转换	账号调度加协议转换	Adapter、Strategy、Converter
计费	额度乘倍率	钱包、套餐、阶梯、缓存计费	账号配额切分，用户余额和支付	偏个人用，多租户弱
怎么选上游	分组、模型、渠道三者匹配	更复杂的亲和与插件过滤	粘性、负载、RPM、利润	凭据池打分加失败切换

OneAPI 的核心是一个 Adaptor 接口，里面就是拼请求地址、设请求头、转换请求体、发请求、解析响应这几个方法，每个厂商一个目录去实现。这是我读到的最老实的设计，上游是谁、请求怎么改，打开就能看懂。

还有两个地方容易搞混。NewAPI 里说的订阅计费，指的是用户买套餐，跟 Sub2API 那种上游订阅账号池没关系。NewAPI 甚至专门做了一个 Sub2API 渠道，可以把 Sub2API 当成一种上游接进来。Key 网关和订阅池能一层套一层，你调用的中转背后，可能还是一个中转。

要是我自己搭

我要的是自己信得过、能审计的东西，所以内核刻意做小。

图 5 · 自建可信中转，做哪些，不做哪些

要做只用 ① Key 转发模式OpenAI 兼容接口加流式，行为能测下游 Key 自己签，不留弱默认值，支持 IP 白名单上游 Key 落盘加密，或者交给系统密钥链每个厂商一个 Adaptor 文件，不动态加载闭源代码日志结构化并脱敏，每个请求带 trace id，用量落库超时写死，重试有上限，绝不悄悄换到别人的账号

先不做订阅 OAuth 池、cookie 池、TLS 指纹伪装多租户充值、支付、拼车分账让插件执行用户代码自动模拟最新版官方客户端开放注册

从这几个项目里挑东西，我的取舍是这样的。

项目	学什么	别照搬什么
OneAPI 和 NewAPI	Adaptor 接口、选渠道、先预扣再结算的计费	把整站直接拿去当商用中转运营
Sub2API	粘性会话、分组白名单、组合分组路由、流式失败切换	明文凭据、闭源插件、内置支付、客户端指纹
AIClient2API	Strategy 和 Converter 的分层、凭据池打分与切换	TLS 伪装、写死的客户端身份、默认弱口令

接下来我打算先画一页 Key 转发最小内核的架构图，只接一个合规上游，把流式跑通。协议转换和多 Key 负载均衡留到第二步。

还没弄清楚的

Sub2API 有没有我没搜到的字段级加密或 KMS 方案。
Sub2API 官方的 Docker 镜像里，会不会默认带着没开源的插件。
我读的那一版 A2 里，Gemini CLI 适配器的注册被注释掉了，原因我没查到。README 里写的支持情况，用之前最好自己试一下。
NewAPI 的插件执行那部分，我没有按安全审计的标准去读。

最后几句

只是用中转站的话，先问清楚它属于哪种模式。Key 转发之外的两种，意味着你的请求跑在别人的账号上，稳定性和合规都没人担保。

想自建的话，从 OneAPI 的 Adaptor 骨架起步，只接官方 Key，先把凭据存储和日志脱敏做对。Sub2API 和 A2 很值得读，拿它们学调度和协议转换就好，原样上线我不建议。

核心很小，能力挂在边上。我读 Hermes Agent 和 Agent Skills 规范的笔记

Tue, 08 Sep 2026 00:00:00 GMT

TL;DR Hermes Agent 的核心就一个对话循环，命令行、终端界面、聊天机器人网关和定时任务都调它。新能力尽量做成技能、插件或 MCP 挂在外面，核心不动。Agent Skills 这个开放规范简单得有点意外，一个文件夹加一个 SKILL.md，启动时只加载名字和描述，用到了才读全文。Hermes 在上面多做了一层，让 Agent 自己写技能，后台再自动整理。这个想法我觉得很有意思，用的话要打开审批。另外，它的终端隔离和审批都算不上安全边界。

为什么要读这个

我在自己的环境里跑 Hermes Agent，把它接进了元宝群当机器人。接入时踩过一个坑，机器人能被 @ 到，就是不回话。最后查下来是群访问策略和多 profile 下的密钥作用域问题。

修好之后，我还有两件事想弄明白。

一条群消息从进来到交给模型，中间到底过了哪些环节？
Hermes 说自己支持 Agent Skills，还能自己写技能。这里的技能是什么东西，跟 Claude Code、Cursor 里的 skills 是一回事吗？

于是我把 Hermes Agent 的源码和 Agent Skills 的规范对着读了一遍。

先说清楚几个词。Agent 指能多轮调用工具来完成任务的大模型程序，工具包括读文件、跑命令、搜索这些。对话循环是 Agent 的主流程，先调模型，模型要用工具就去执行，把结果塞回对话再调模型，一直转到模型给出最终回答。Skill 也叫技能，是一份写给 Agent 看的操作说明，告诉它某类任务怎么做，可以附带脚本。

一、Hermes 长什么样

Hermes 仓库根目录有一份给开发者看的设计说明，里面有两条原则。整个项目为什么长成现在这样，从这两条差不多都能推出来。

按会话的 prompt cache 不能乱动。 长对话会复用缓存，中途重建 system prompt 会让缓存失效，成本成倍往上涨。技能、工具、记忆这些会改 system prompt 的东西，都得照顾缓存。
核心做成窄腰，能力放在边上。 新渠道、新模型、新能力，优先做成边缘扩展，尽量不往核心循环里塞。

图 1 · Hermes 的窄腰，入口很多，核心一个，能力在边上

命令行 CLI终端界面 TUI消息网关定时任务桌面端

都调用同一个

AIAgent 对话循环

按需调用

Skills 技能工具注册表插件和 MCP记忆终端后端7 种

这个形状我很认同。反面的例子大家都见过，每接一个新渠道就在核心里加一堆 if，最后谁都不敢碰。Hermes 把入口和能力都推到了边上，中间只留一个循环。

技术栈方面，Python 支持 3.11 到 3.13，依赖用 uv 管。终端界面是 React 加 Ink 写的，配置用 YAML，密钥放在 .env。

二、在命令行里问一句话，后面发生了什么

图 2 · 命令行里一轮对话的完整路径

用户HermesCLIAIAgent对话循环工具执行模型

用户 → CLI输入一句话或斜杠命令

CLI → AIAgent把这句话交给 AIAgent 开始一轮对话

AIAgent → 循环先拿到本轮的执行租约 turn lease

↻ 在预算内反复

循环 → 模型发送对话历史

循环 → 工具模型要用工具，就去执行对应的工具调用

工具 → 循环工具结果追加进对话，再问模型

循环 → CLI模型不再调工具，返回最终回答，可以流式输出

终端界面走的也是这条路。前端通过 JSON-RPC 连到后端，后端还是同一个 AIAgent，消息网关和定时任务同样如此。窄腰落到代码里就是这个样子，不管从哪个入口进来，最后都进这一个循环。

三、一条群消息怎么走到模型

这部分我最关心。通用的消息平台，比如 Telegram，是以插件形式接进来的，收到消息后交给网关统一处理，依次过前置钩子、鉴权、配对和媒体处理，再进对话循环。

元宝是内置平台里中间件最完整的一个。一条消息要按顺序过下面这些中间件。

图 3 · 元宝入站中间件管线，标红的两步决定机器人回不回话

解码提取字段撤回检查去重跳过自己会话路由访问控制 AccessGuard提取内容主人命令构建来源群 @ 检查 GroupAtGuard发言人标注媒体解析分发给 Agent

标红的两步，我当时查问题时盯得最久。

访问控制。 私聊和群聊各有一套策略，可选白名单、配对、开放或禁用。想设成开放，还得额外配一个环境变量，比如 YUANBAO_ALLOW_ALL_USERS。条件不满足，消息会被静默丢弃，不报任何错。
群 @ 检查。 群里没有 @ 机器人的消息只会被观察，记进上下文，不会触发回复。日志里能看到 Group message observed (no @bot)。

这套管线我很喜欢。每一步只做一件事，每一步都能打日志。机器人不回话的时候，看日志停在哪一步，基本就知道问题在哪。

四、一个进程里跑多个机器人

Hermes 有 profile 的概念。每个 profile 是一个独立目录，默认放在 ~/.hermes/profiles/<name>/ 下面，有自己的配置、.env、技能和会话数据库，彼此不继承。

网关打开 multiplex_profiles 之后，一个进程可以同时服务多个 profile，比如在一个群里挂好几个不同人设的机器人。

这里有个坑。多路复用时，进程的环境变量通常属于默认 profile，副 profile 的白名单、允许所有人这类配置，要靠专门的密钥作用域模块按 profile 去读。这个模块是 fail-closed 的，读不到就直接失败，不会退回去借默认 profile 的配置。

这个选择我觉得对。宁可不回话，也不能把 A 机器人的权限借给 B。代价是配置一旦写错，表现就是静默不工作，只能翻日志排查。

五、终端隔离别当成安全边界

Hermes 支持 7 种终端后端，分别是 local、docker、singularity、modal、daytona、vercel_sandbox 和 ssh。默认的 local 直接在本机执行，没有任何操作系统级的边界。

项目的安全说明写得很坦白。终端后端只管得住 shell 和文件类工具，进程内的代码执行、MCP 子进程、插件、技能里的 import 都不归它管。审批门控也只是启发式判断，算不上安全边界。要隔离，得把整个 Hermes 进程放进容器。

Hermes 一旦接进群聊这种别人也能发消息的地方，这一条就得认真对待。

六、Agent Skills，一个简单得有点意外的规范

Agent Skills 是一个开放规范，Claude Code、Cursor、Hermes 都兼容。一个技能由这几样东西组成。

一个文件夹
文件夹里必须有一个 SKILL.md，开头是 YAML 头部，后面是 Markdown 正文
可选的 scripts/、references/、assets/ 目录

头部只有两个必填字段。

字段	要求
`name`	最多 64 个字符，小写字母加连字符，最好和文件夹同名
`description`	最多 1024 个字符，写清楚做什么、什么时候用

可选字段有 license、compatibility、metadata，还有一个实验性的 allowed-tools，用来预先批准技能可以用哪些工具。

我觉得它设计得最巧的一点是渐进披露，英文叫 progressive disclosure。

图 4 · 渐进披露，需要时才把内容放进上下文

① 目录启动时只加载 name 和 description，每个技能几十个 token② 激活任务匹配上了，才读完整的 SKILL.md③ 资源需要时再读脚本和参考文档

所以装几十个技能，平时也几乎不占上下文，跟前面那条别乱动 prompt cache 的原则也对得上。

技能放在哪，规范没有硬性规定，由各个产品自己约定。想跨工具共用，项目级的放 .agents/skills/，用户级的放 ~/.agents/skills/，同名时项目级优先。来自不信任仓库的技能，先审一遍再加载。

表 · Claude Code、Cursor、Hermes 的技能实现，窄屏可以左右滑动

	Claude Code	Cursor	Hermes
技能目录	`~/.claude/skills/`、`.claude/skills/`	`.agents/` 或 `.cursor/skills/`，也会扫描 `.claude`、`.codex`	`~/.hermes/skills/`，项目目录要先信任，另有技能 Hub
扩展字段	`context: fork`、`allowed-tools`、动态命令等	`paths` 等	`platforms`、`metadata.hermes.*`
特点	以人写为主，产品扩展多	monorepo 里可以按子目录生效	Agent 能自己写技能，后台自动整理
调用方式	Skill 工具或 `/技能名`	自动匹配或 `/`	`skills_list` 再 `skill_view`，或者斜杠命令

规范里的六个字段可以跨产品用。各家的私有字段，换个产品可能被忽略，也可能报错。想写一份到处都能用的技能，就只用规范字段，私有的放进 metadata 下面自己的命名空间。

七、Hermes 的特别之处是 Agent 自己写技能

Hermes 跟另外两家最不一样的地方在这里。

加载。 技能靠 skills_list 和 skill_view 两个工具渐进加载。用斜杠命令调用技能时，技能内容作为一条用户消息插进对话，system prompt 不动，还是为了保住缓存。
自己写。 做完一个复杂任务，Agent 可以用 skill_manage 把这次的做法存成新技能。配置里有个 skills.write_approval，打开后写技能之前要你点头。
Curator 整理器。 Agent 空闲时它会自动跑，按使用记录把技能在活跃、过期、归档三种状态之间挪，也可能合并或修补技能。它守几条硬规矩。只碰归它管的技能，内置技能默认也算在内，从 Hub 装的从不清理。它从不删除，只归档，归档的还能恢复。被固定（pin）的技能它完全不碰。
护栏。 有一个 Skills Guard 做启发式检查，从 Hub 安装的技能会先进隔离区。

让 Agent 自己写技能，好处坏处我都看得到。

图 5 · 人写的技能和 Agent 自己写的技能

人写、可移植能审计，能进 git，Cursor、Claude、Hermes 都能用短处是更新慢，要有人维护适合核心操作流程，以及要发给别人用的技能

Agent 自写从真正做成过的事情里长出来，贴合个人习惯短处是容易重复，半成品多。技能里既有指令又有脚本，等于多了一条供应链风险适合当个人的过程记忆用，记得打开 write_approval

还有一个伴生项目叫 SkillClaw。任务进行中由 Hermes 写技能，任务结束后交给一个进化服务去重、提质，格式仍然是 SKILL.md。它跟 Hermes 自带的 curator 同时开着时怎么分工，我还没实际验证过。

装任何技能之前，我会按顺序过一遍。先看来源和 hash，再通读 SKILL.md，检查 scripts/ 里有什么，看它要哪些权限、allowed-tools 写了什么，确认项目已经被信任，最后先在沙箱里跑一次。这方面有一篇文章写得很好，Install agent skills without getting owned。

八、风险汇总

方面	风险	怎么控制
凭据	`.env` 里的机器人 token 和模型 Key	`.env` 只放密钥，多路复用时用密钥作用域，子进程清理环境变量
插件	和 Agent 进程权限相同	安装前人工审
网关	陌生人远程驱动你的 Agent	每个平台配白名单，缺白名单时默认拒绝
技能	import 和脚本可以执行任意代码	Skills Guard、隔离区、写入审批，curator 只归档不删
终端	`local` 后端没有系统边界	换成 docker 等后端，要可靠隔离就把整个进程放进沙箱
审批	启发式判断	别当安全边界用

我还不确定的

curator 默认多久触发一次、阈值是多少，取决于配置，默认值我没逐项核对。
其他消息平台插件的中间件是不是跟元宝同一套结构。Telegram 那条路明显薄很多。
规范里实验性的 allowed-tools，各家客户端支持得参差不齐。

谁该关心，下一步做什么

自己在跑 Agent，尤其是接进了群聊的，先确认终端后端不是裸的 local，再确认每个平台都配了白名单。这两件事比任何提示词技巧都要紧。

在写技能的话，只用规范里的字段，放进 .agents/skills/，Cursor、Claude Code、Hermes 都能用。描述字段里写清楚什么时候该用它，能不能被正确触发就看这一句。

在设计自己的 Agent 系统，Hermes 有几处做法值得照着学。一个核心循环挂多个入口。网关用中间件管线表达策略，每一层都能观测。多租户的密钥按作用域读，读不到就失败。

我自己的下一步，是把手上的运维操作流程整理成几个人写的 .agents/skills/ 技能，让不同工具共用一份。

Java 后端复习：GitHub 高星中文资料精选

Tue, 08 Sep 2026 00:00:00 GMT

用途：面试突击 + 体系复习 + 中高级
主战场：Java/JVM/并发 · MySQL/Redis · Spring+源码 · 分布式/DDD
原则：中文仓为主；英文高星只附中文导读，不整仓翻译
整理日期：2026-09-08 · star 量为当时公开页量级，会变动

建议学习顺序

① Java/JVM/并发（底座）
    → ② MySQL + Redis（数据面）
        → ③ Spring 全家桶 + 源码（框架面）
            → ④ 分布式 / 系统设计 / DDD（架构面）

每天可用「八股过一遍 + 一章原理/源码」；场景题放到 ④ 与项目经历对齐。

一、Java / JVM / 并发

仓库	Star 量级	类型	怎么用
Snailclimb/JavaGuide	~157k	合集型 · 持续维护	主阵地。先啃 `docs/java/concurrent/`（并发上中下）+ `docs/java/jvm/`（内存区域、GC、类加载）。站点：https://javaguide.cn
CyC2018/CS-Notes	~186k	合集型 · 偏笔记	用来对照查漏：Java / 操作系统 / 网络。内容偏精炼，适合二轮速览，勿当唯一来源（部分章节偏旧，以 JavaGuide 为准核对）
itwanger/toBeBetterJavaer	~17k	体系教程型	并发 + JVM 讲得口语化，适合「听懂再背」。配合 JavaGuide 的面试题清单效果好
doocs/jvm	专题型（doocs 系）	JVM 专题	若 JVM 要加深，专啃这一本式整理；与《深入理解 Java 虚拟机》对照

中高级重点（别只背题）：
JMM / volatile / synchronized / AQS / 线程池参数与拒绝策略 / GC 选型与排查工具 / 类加载与双亲委派例外。

二、MySQL + Redis

仓库	Star 量级	类型	怎么用
Snailclimb/JavaGuide 数据库/缓存章节	（同上仓）	合集内专题	MySQL + Redis 面试主线：索引、事务隔离、锁、日志、主从；缓存穿透/击穿/雪崩、一致性。从站点目录进「数据库」「Redis」
doocs/advanced-java	~79k	进阶扫盲 · 中高级向	强烈推荐「已熟练」后再拔高：高并发下的缓存、分布式锁、秒杀、消息、ES 等场景串起来。站点：https://java.doocs.org
黑马点评 / 秒杀类实战仓（如社区常推的 hmdp 系、java-up-up/damai ~1k+）	数百～1k+	实战型	用来把 Redis 从「会命令」变成「会方案」：Lua 扣减、分布式锁、缓存一致性。挑 1 个跟完即可，不必多开

中高级重点：
Explain / 覆盖索引 / 间隙锁；Buffer Pool；Redis 单线程与 IO 多路；持久化 RDB/AOF；集群与哨兵；与 DB 双写一致性策略。

三、Spring 全家桶 + 源码

仓库	Star 量级	类型	怎么用
Snailclimb/JavaGuide Spring 专题	（同上）	八股 + 原理	IoC/AOP、事务传播与失效、循环依赖三级缓存、Boot 自动装配。入口：https://javaguide.cn/system-design/framework/spring/
yudaocode/SpringBoot-Labs（芋道）	~20k	源码/专栏实验型	源码主阵地：按 lab 跑通 Boot 启动、自动配置、MVC；第二波再碰同仓里的 Cloud / 事务 / MQ 专栏
Snailclimb/JavaGuide-Interview	~3k	突击压缩版	面试前 1–2 周速刷 Spring/Boot 问答，细节回主仓

中高级重点：
Bean 生命周期、三级缓存解决循环依赖、@Transactional 失效场景、Boot 2.x spring.factories vs 3.x AutoConfiguration.imports、Starter 条件装配。

四、分布式 / 系统设计 / DDD

仓库	Star 量级	类型	怎么用
doocs/advanced-java	~79k	分布式进阶	主线：分布式锁、事务、限流熔断、高可用、海量数据。适合「熟悉分布式开发」后查缺
nageoffer/congomall	商城 DDD 实战（质量向）	DDD 落地型	对照订单/商品/优惠券边界，学「不是空谈分层」；配合自己项目的设计文档讲故事
Admol/SystemDesign	~3k	中文书译	Alex Xu《系统设计面试》中文：场景题骨架（短链、限流、聊天、Feed…）
donnemartin/system-design-primer	英文高星（全球头部）	系统设计	见下方「英文附录」——用简体中文 README 学，不必啃英文正文

中高级重点：
CAP/BASE、幂等、分布式事务（本地消息表 / TCC / Seata 概念）、限流降级、一致性哈希；DDD 战略设计 vs 战术（聚合、领域事件）能结合项目说清楚即可。

英文高星附录（只给中文导读，不全文翻译）

system-design-primer

仓：https://github.com/donnemartin/system-design-primer
直接看：仓库内 README-zh-Hans.md（已有简体中文）
建议读的章节：
1. 如何答系统设计面试（框架）
2. 短网址 / ID 生成 / 限流 / Key-Value（分布式基础件）
3. 任选 1 个业务场景（聊天 or Feed）练口述
不必：把所有 solutions 英文代码逐文件翻译；对照 Admol 中译书 + 自己画图即可。

待补方向（第二波预告）

第一波刻意没深挖，需要时再说一声：

方向	说明
Spring Cloud	可继续挖芋道 Labs 的 Cloud / Alibaba 专栏 + JavaGuide 微服务章节
RocketMQ / ES / Activiti	官方文档 + advanced-java 消息/搜索章节；Activiti 完整面试仓较少，偏官方 User Guide + 自己的项目
前端 Vue/React	维持「了解」即可，不必高星八股仓
AI / Agent / MCP	见 Hermes × Agent Skills 笔记；Java 侧可后续补 Spring AI 类中文项目

两周冲刺示例（可改）

天数	内容
D1–3	JavaGuide 并发三篇 + JVM 内存/GC/类加载；用 jstack/jmap 口述一遍
D4–6	MySQL 索引事务锁 + Redis 五类问题；advanced-java 里缓存/锁 2–3 篇
D7–10	Spring 事务/循环依赖/自动装配；SpringBoot-Labs 跑 1–2 个启动/装配 lab
D11–14	advanced-java 分布式专题 + SystemDesign 2 个场景口述；congomall 看一个限界上下文

使用注意

Star ≠ 全对：以原理能否讲清为准；过旧章节用官网/新版源码核对。
合集仓重复多：JavaGuide 作主干，CS-Notes / 二哥作辅，避免三份同时精读。
实战仓：跟 1 个吃透，胜过 star 崇拜式收藏。

第二波（Cloud / MQ / ES / Activiti）后续再补。