鉴于目前Agent的生态还比较凌乱，大家各干各的，skill的存放目录也自己定自己的。

比如 Cursor 放在 ~/.cursor/skills，Claude Code 放在 ~/.claude/skills，Trae 放在 ~/.trae/skills，OpenCode 放在 ~/.config/opencode/skills，还有 Windsurf、Qoder、Hermes 等等，每家都有自己的路径约定。

社区也在试图定义通用的.agents/skill这样目录，有点作用，但不大。

当然，skill管理的问题，也不全是使用多Agent带来的。因为skill这种东西，天然就就有非常大的适用范围区别。有的skill是适用于公司的项目的，有的是适用于自己的项目的，有的适用范围还更窄一点，只适用于若干范围内的几个项目，还有的skill, 比如汇总新闻的，我想只配在某个agent里。

你要是问，不对skill做这些精细化的管理，行不行？那确实也没什么大问题，无非就是agent每次检索技能，多花点token. 但做技术的强迫症，还是希望把这些东西管的细一些，在不需要agent调起的地方，就压根别让agent能看到这些skill.

基于此，设计了pks这个工具。核心思路是在一个集中的地方管理所有的skill, 然后，按照需求，将skill写入agent的skill目录或者项目目录下。

具体来说，支持以下功能

全局管理：所有 skill 集中存放在 ~/.local/share/pks/skills/ 下，用 pks list 查看，用 pks new 创建新 skill。

项目级安装：在项目目录下执行 pks init 初始化后，可以用 pks install 把全局 skill 安装到当前项目的 .skills/ 目录。

Agent 级安装：用 pks install-to <agent> <skill> 把 skill 直接装到指定 agent 的 skill 目录（比如 ~/.cursor/skills/）。

双向同步：在项目里改了 skill 文件，用 pks push 把改动推回全局库。

实际使用上，我大概有这么些使用场景：

有一些skill是小范围适用的，比如相关的几个有限的工程，这时候，我不会将skill放到agent的配置里，而是会放到项目中，使用pks install命令，可以把本地技能库中的skill, 放到工程目录下。然后可以在AGENTS.md文件中指引agent去skill目录下找技能，对于支持项目内技能的agent, 也可以使用pks link命令，将agent对应的项目内技能目录，比如.opencode/skills, 软链到skills目录下；

有些skill, 比如收集新闻的skill, 我只想让它在部分agent中出现，这样就执行pks install-to命令, 将其装到agent的skill目录下。

有时候skill文件需要修改，我会先在某个项目下进行修改，然后执行pks push, 将命令写回技能库。

这样，对于skill, 就有了一个比较妥善合理的处理流程。

项目地址在： https://github.com/lcy362/personal-skills-manager ， 欢迎试用。 大家有什么其他关于skill管理的经验，也欢迎提出。

“解决的办法不是压制 AI，而是让它变成一种更平权的能力，让每个人都知道如何借 AI 创造更多。这也是我们公司很重要的愿景，让世界级的 AI 属于每一个人。”

这是 Agnes AI 创始人 Bruce Yang 接受采访时说的一段话。

现在很多国内的AI厂商，无论deepseek还是智谱，都在把AI的价格往下压。坦率的讲，像文字、代码的处理价格，确实已经被压到了一个相当低的价格。但视频不一样，现在做AI视频，门槛确实高得离谱——国外的 Runway、Pika 按月订阅几十美元，国内的即梦、可灵免费额度用完就按秒计费，想本地跑开源模型？一张能跑视频的显卡轻松上万。

客观来讲，视频的生成，现阶段确实成本较高，让工业级的视频生成能力属于每一个人，确实不现实。但普通人也应该有一些途径能更多的去尝试、去创作，感谢Agnes开放自己的视频模型，让大家有这个机会。而这个项目只是想为了这个做一些微不足道的贡献。 Agnes Video Generator（官网）。说白了就是一个免费的AI视频生成器，不是那种”免费试用3次”的套路，是从写文案到出片、配音、上字幕，全程不花一分钱。只需要去 Agnes AI 注册个免费API Key就行。

Agnes的视频模型，目前确实称不上完美，但我想用这么一个项目，和Agnes一起成长，为AI平权，贡献上一点微不足道的力量。

多种玩法

给它一句话描述，它还你一条视频。分几种类型：

简单视频。 纯粹对API的封装，用来测试效果的，接口的各种参数，基本都做成了配置。

创意视频。 你写一个故事创意，比如”暗黑版青蛙王子”，AI全包：扩展故事→生成角色参考图→拆分场景→写分镜提示→逐段生成视频→配音→上字幕→拼接成片。全程10步自动跑完，你只需要等着看成片。通过预生成尾帧，可以最大限度的保障场景间视频的连贯性。

文稿视频、数字人口播。 贴一篇长文章进去，自动按语音时长分段，每段生成画面，或者放一个数字人在那里念稿。用一条完整的TTS旁白和字幕串起来。做知识区内容的可以试试。

各模式的详细参数和玩法，可以到官网上看，这里就不展开了。

跑起来很简单

1
2
3

git clone https://github.com/lcy362/agnes-video-generator.git
cd agnes-video-generator
./start.sh

就这三步。start.sh 会自动帮你建虚拟环境、装依赖、启动服务。

启动后打开 http://localhost:8765，在页面顶部填上你的 Agnes AI API Key，选个模式，写你的创意，点生成，然后耐心等结果就行。

用 Cursor 或者 Claude 这些AI Agent的话更方便，我专门为Agent做了使用说明，直接让你的Agent读项目里的Agents.md文件，它自己就能把环境搞好、把服务跑起来。

看看效果

做了几个demo,可以看看效果：

• 暗黑版《青蛙王子》无旁白版 — 5个场景用关键帧衔接，全自动生成
• 同一个故事加了旁白字幕 — AI配音 + 自动字幕，可以看看字幕的效果
• 文稿视频 — 贴了篇长文进去自动分段，每段配不同画面

最后

回到开头 Bruce Yang 说的那句话——「让世界级的 AI 属于每一个人」。

这个项目不是什么宏大的事业，就是想让 AI 视频创作这道门开着。不用订阅、不用好显卡、不用花一分钱，你只需要一个免费的 API Key 和一台能跑 Python 的电脑。

代码在 GitHub，官网在 video.lichuanyang.top。欢迎提bug。

原文地址：https://lichuanyang.top/posts/22470/

这话说了之后，有人问我：道理都懂，但文档具体怎么管？总不能每个项目都复制粘贴一遍吧？

确实不能。

我后来写了个工具来解决这事——pks（Personal Skills Manager），408行纯bash，零依赖。它干的事很简单：把你的AI工作流文档打包成skill，按需装到项目里，不绑定任何Agent平台。

什么是skill

如果你用过OpenCode、Cursor或者其他Agent平台，大概率见过”skill”这个概念。不同平台叫法不一样——有的叫skill，有的叫rules，有的叫custom instructions——但说的都是同一件事：你给Agent的结构化指令，告诉它怎么处理特定类型的任务。

比如”调用我们的API网关时，参数必须平铺在body顶层，不要嵌套在params里”，这是一条skill。”commit消息必须用中文，格式是type(scope):描述”，这也是。”数据库表名用snake_case，字段必须有注释”，还是。

Agent的底层模型提供了通用推理能力——它知道怎么写代码、怎么调API。但你的API网关有什么坑、你们团队的命名习惯是什么、你们项目为什么选了这个架构——这些知识模型不知道，得你告诉它。skill就是你告诉Agent这些东西的方式。

各平台管理skill的方式各不相同。OpenCode用.opencode/skills/目录，Cursor用.cursorrules，Claude Code读CLAUDE.md。格式不同，机制不同，但本质没区别：都是一份文档，Agent读到就按里面的规则干活。

skill本身不依赖任何平台。一个用Markdown写好的skill文件夹，丢进任何项目里，任何Agent找到了都会读、都会用。纯Markdown，谁来都能读。

问题出在哪

skill是个好东西，但问题来了：你手上有好几个项目。

一份团队编码规范，项目A要用，项目B要用，项目C也要用。你怎么管？

常见的做法是，把这些配进agent本身的配置里，也就是常规的“安装skill”操作，比如给opencode装个微信读书skill, 这样，所有的项目用opencode打开，就都能用上。

这本来是没啥问题的，除非你看了我上一篇文章..

在我们想打造agent无关的工作流的情况下，这么干问题就大了。哪天你看到有个新agent在送免费token, 下来一用，发现一堆skill都得自己迁移，这不就傻了吗。

所以我开发pks的初衷，就是把这一层抽出来，解套。让对这些不通用skill的管理，独立于所有的agent和项目，单独成一个体系。

pks怎么解决

pks最适合管理那些非通用的、项目或团队特有的指令：你的编码风格偏好和commit规范、团队的代码规范和CI/CD流程、项目的架构决策记录和API设计约束等。

pks要解决的就是一件事：在一个地方管理所有skill，按需装到任何项目里。

然后，所有skill集中存在一个全局仓库里。项目需要哪些，装哪些。

全局操作就三个核心命令：

1
2
3

pks new my-skill       # 基于模板创建skill骨架
pks list               # 看看你有哪些skill
pks delete my-skill    # 删掉不要的

项目操作也很简单：

1
2
3
4
5

cd your-project
pks init                        # 初始化（只执行一次）
pks install my-skill            # 装一个skill进来
pks status                      # 看看装了哪些
pks uninstall my-skill          # 不想要了就卸掉

装好之后，skill会被复制到项目的.skills/目录：

1
2
3
4
5
6

your-project/
├── .skills/
│   ├── INDEX.md              # 自动生成的索引
│   └── my-skill/
│       └── SKILL.md           # 你的skill内容
└── ...

Agent怎么发现这些skill

这其实是个很自然的流程。

每次install或uninstall，pks会自动重建.skills/INDEX.md。这个索引文件列出所有已安装的skill，附带描述和版本，并且包含一句话：

Agents: read the SKILL.md file in each skill directory below for relevant instructions.

任何Agent进到项目都会看到这个目录，读INDEX.md，然后按需加载具体的SKILL.md。

最多你就在项目的AGENTS.md里再加一句去skill目录下找技能。按我的经验，对大部分agent来说，都没这个必要，它们都很自然的就找到这些技能了。

什么时候会用到

说个最常见的场景：你负责一个项目，新人要加入开发。

传统做法是什么？甩一份README，口头交代几句”我们commit要这么写”、”那个内部库要那么调”、”数据库字段别随便改”。剩下的全靠悟。

用Agent辅助也差不多——你把规则塞进CLAUDE.md或AGENTS.md，Agent每次对话都吃一遍，不管这次任务跟这些规则有没有关系。

换个思路。把这些知识拆成几个skill：

1
2
3
4
5
6
7
8
9
10
11

skills/
├── team-coding-style/     # 团队编码规范、命名约定、commit格式
│   └── SKILL.md
├── internal-api-gateway/  # 内部API网关：参数平铺、鉴权方式、踩坑记录
│   ├── SKILL.md
│   ├── pitfalls.md        # 常见坑点（比如参数不能嵌套在params里）
│   └── fields.md          # 回包字段含义速查
├── project-architecture/  # 架构决策：模块划分、目录结构、为什么这么设计
│   └── SKILL.md
└── db-conventions/        # 数据库规范：命名、索引策略、迁移流程
    └── SKILL.md

新人入职？pks init，pks install team-coding-style，pks install project-architecture，几分钟装好。Agent读到这些skill，立刻知道这个项目的规矩。换一个人、换一台机器、换一个Agent平台，同样的skill装上去，效果一样。

而且只有装了才消耗token。一个纯前端项目不需要装数据库规范的skill，一个老项目不需要装新人引导的skill。相比把所有规则塞进一个巨大的配置文件让Agent每次对话都吃一遍，按需安装能省下不少无用token——这本身就是在薅自己的token。

这种非通用类的指令才是pks的主场。通用能力Agent自己就有，但你的团队规范、你的项目约定、你踩过的坑——这些东西只对你有用，也只该在需要的时候才出现。

为什么是纯bash

pks整个CLI是408行bash脚本。不用Python，不用Node.js，不用任何运行时。git clone下来就能跑。

为什么这么极端？因为skill管理工具本身不应该引入任何负担。你的工作流已经够复杂了，管理它的工具应该尽可能简单——简单到不会因为某个运行时版本升级而挂掉。

bash在macOS和Linux上开箱即用，十年前的脚本今天还能跑。这就是零依赖的好处：你的工作流文档比任何框架都长寿。

设计上的几个小心思

pks有几个设计细节值得提一嘴。

语义化版本：每个skill的YAML front matter里有version字段。skill迭代了，版本号跟着涨，项目里装了哪个版本一目了然。

全局管理，按需安装：所有skill集中在一个仓库里维护，项目里只装需要的。

模板保护：以_开头的skill（比如_template）不会出现在列表里，也不能被删除。pks new创建新skill时自动基于模板生成骨架，不用从零写起。

路径无关：pks通过符号链接解析和相对路径定位，在任何位置调用都能正确找到skills目录。不管你从哪个路径执行命令，它都知道自己的家在哪。

回到那句话

上篇说”Agent只是工具，文档才是核心”。这篇把它往前推了一步：文档化的工作流，是可以被管理的。

pks不是什么高深的东西，408行bash而已。但它代表了一个态度：你的工作流是你的资产，不是任何平台的附属品。

该薅token薅token，该管skill管skill。钱要省，活要干好，这两件事不矛盾。

原文地址：https://lichuanyang.top/posts/26061/

常见问题

Q: Skills 管理和 Agent 管理有什么区别？

Skills 管理是独立于 Agent 平台的，你把所有 skill 统一放在一个全局仓库里，项目需要什么就装什么。Agent 管理则是把 skill 配进某个 Agent 的内部配置中（如 OpenCode 的 .opencode/skills/ 或 Cursor 的 .cursorrules），绑定到具体平台。前者的好处是换平台时不需要迁移任何 skill，后者虽然集成度高，但一旦切 Agent 就需要重新配置。

Q: 跨平台兼容性怎么保证？

关键是 纯 Markdown。pks 安装 skill 后生成的都是 .md 文件，放在项目的 .skills/ 目录下，附带一个自动维护的 INDEX.md 索引文件。任何 Agent 扫描项目目录时都会发现这个结构，读 INDEX.md 就知道有哪些 skill，再按需加载具体的 SKILL.md。不需要特定格式，不需要平台 SDK，纯 Markdown 是最大的公约数。

Q: pks 和直接在 Agent 里配置 skill 有什么不同？

直接配在 Agent 里方便，但 skill 会”绑定”到那个 Agent。pks 的做法是从 Agent 中解耦 skill 管理——skill 存在全局仓库，按需安装到任何项目中。最大的实际好处：按需安装意味着只有装了的 skill 才消耗 token。一个纯前端项目不需要装数据库规范的 skill，一个老项目不需要装新人引导的 skill。相比把所有规则塞进一个大配置文件让 Agent 每次对话都吃一遍，pks 能省下大量无用 token。

Q: 为什么用 bash 而不是 Python 或 Node.js？

零依赖。skill 管理工具本身不应该引入任何运行时负担——你的工作流已经够复杂了。408 行 bash 脚本在 macOS 和 Linux 上开箱即用，不需要安装解释器、不需要管理虚拟环境、不会因为某个运行时版本升级而挂掉。bash 十年前的脚本今天还能跑，这保证了你的工作流文档比任何框架都长寿。

原文地址：https://lichuanyang.top/posts/26061/

无论是Claude、CodeX、Cursor，还是qoder或是mimo、minimax，基础套餐基本都要奔着20刀以上去，这还得省着用，很多时候用以来会很不爽。要想量大管饱，那就会更贵。

而同时，很多平台会有试用装，或是常规的免费模型。比如OpenCode里的deepseek flash长期免费。

我们怎么才能好好的薅一下这些免费模型呢？

我长期在各种不同的项目用Agent，有代码，有个人博客，有笔记知识库，有小说，还有我和AI完的小游戏。用着用着发现一个事：Agent的所有操作，本质上是：读你文档 → 拼prompt → 发给模型 → 按结果改文件。

文档在哪里，智能就在哪里。你自己拼prompt，跟平台帮你拼，其实没差那么多。

所以我后来干脆不再纠结用哪个Agent平台了。文档维护好，哪里有免费token就去哪薅。

Agent到底干了什么

不管哪家Agent，流程都差不多：

1

用户说需求 → Agent看项目文档 → 读相关文件 → 拼prompt → 问模型 → 处理返回 → 改文件 → 循环上述流程

比如让它帮你修个bug，它：

1. 先读你项目里的 AGENTS.md、README.md，知道这项目是啥、目录在哪
2. 再找到bug涉及的几个文件，读源码
3. 把”项目上下文 + 相关代码 + bug描述 + 修改要求”拼成一个prompt
4. 发给大模型
5. 把返回的结果写成代码修改

这些步骤，agent硬有差别，能有多大差别？

别误会，这里不是要全盘否定一些公认的好Agent。好的Agent在上下文管理、流程控制、工具集成上确实做得顺手，不然也不会流行。但，“人的智能”，完全可以补上这些差距。

比如上下文管理，Agent能定位到”这个bug涉及用户认证模块，需要读这三个文件”——可前提是它已经看过了你的AGENTS.md。那些文件路径、模块职责、约定俗成的写法，本来就是你自己写进去的。

文档不好的时候，好的agent能有效率更高的方式找到需要的信息。但在文档完备的情况下，agent的差距就微乎其微了。

总之，好的Agent在某些场景下，确实是方便，但是，不值这个价格。省下的那点维护文档、切窗口的时间，换每个月几十上百刀订阅费，性价比太低了。

对我个人来说，维护一份完备的agent指南，性价比高多了。何况，这些指南文档，也完全可以让AI自己写。

文档才是关键

想明白上面那段之后，你还得接受一个反直觉的事实：真正值钱的，不是Agent平台，甚至不是模型，而是你自己的工作流。

大模型谁都能调，Agent平台也大多只是编排层，功能都差不多。但你的项目文档和你对项目流程的管理，是唯一的，里面记着项目结构、设计决策、踩过的坑、你偏好的写法。

同样的文档换个Agent平台，效果基本没差；可文档写得垃圾的话，放哪个平台都救不回来。

我在代码项目里是这么维护的：

• 项目概述文档：技术栈、目录结构、关键模块说明
• 工作流文档：”新增功能怎么走”、”修bug步骤”、”发布流程”
• 规则文档：命名规范、注释要求、踩坑记录

同一个项目目录，用不同的agent打开，效果几乎没区别。

小说创作项目同理。世界观、角色档案、章节大纲、写作规范，这些文档不变，换不同模型产出的风格都能保持一致。文档的样子定了，内容质量就定了。

包括模型这一层，差别也没那么大。deepseek-v4-flash, 足够处理绝大多数问题。

就算你真的要花钱买时间，该投资的也是文档本身，不是挑平台。

薅token实战

工作流搬到文档之后，最大的好处就是：平台随便切。

哪家有免费token用哪家，用完换下一家。

比如这些：

• OpenCode：每天有免费DeepSeek Flash
• Qoder：新用户送一些试用credits，还有免费模型额度
• Codex：试用套装，我其实到现在都还没轮到去薅他，总想着遇到一些复杂场景再去用它的免费额度，免得浪费了。但实际上根本遇不到这种场景。
• Hermes：不定期放出免费模型，有时候能意外捡到好模型，比如前阵子有免费的deepseek flash
• trae: 完全免费，只是要排队，有时候真有些任务觉得免费模型搞不动了，临时去trae跑一下，也完全没问题

除此之外还有不少路子：

• 大模型API的新用户赠金：OpenAI、Anthropic、DeepSeek等，新号通常送几美元。直接调API比走Agent平台更便宜
• 开源模型的免费托管：HuggingFace、Together AI有免费推理额度，小任务完全够用
• 学生优惠：GitHub Student Pack之类的，送一堆平台credits
• 一些社区活动：经常有AI平台送额度

所以这篇要说的结论其实挺简单：Agent只是工具，文档才是核心。 把文档维护好，平台随便换，哪里免费去哪薅。一个月省几十刀，换一顿火锅，不香吗？

至于那些每个月烧几百刀token的重度用户——我只能说，你们的钱花得值，但我的token没花钱，效果也差不多。

原文地址：https://lichuanyang.top/posts/26060/

常见问题

Q: Agent 和 Skill 是什么关系？

Agent 是”干活的人”，Skill 是”教它怎么干活的说明书”。Agent 的底层模型提供了通用推理能力，但它不知道你的项目结构、编码规范、API 设计约束——这些知识需要通过 Skill（结构化指令文档）告诉它。两者的关系可以这样理解：Agent = 通用推理引擎 + 按需加载 Skill。把 Skill 维护好，换不同的 Agent 平台也能保持一致的输出质量。

Q: Token 优化最有效的方法是什么？

不是换更便宜的模型，而是写好文档。一份完备的 AGENTS.md 或 SKILL.md，能让 Agent 精准定位到需要读取的文件，避免每次做任务都全量扫描项目。相比之下，在不完备的文档上折腾模型选择或 prompt 精简，省下的 token 远远小于文档带来的提升。先花时间把文档写清楚，再去薅免费 token，这是效益最高的路径。

Q: 文档维护和 Agent 订阅哪个更值？

文档维护更值。Agent 订阅每月花几十上百美元，本质上是为平台帮你”找文件、拼 prompt”的便利性付费。但如果你的项目文档已经足够完备——技术栈、目录结构、设计决策、编码规范都写清楚了——那么换个免费 Agent 效果几乎没差。文档是你自己的资产，可以跨平台复用；Agent 订阅是消耗品，换了平台就得重新来。

Q: 免费模型真的够用吗？

对绝大多数日常任务够用。作者的经验是 DeepSeek Flash 级别的免费模型就能处理大部分代码修改、文档生成、知识整理等任务。遇到确实搞不动的复杂场景，可以临时切到有免费试用额度的平台（如 Trae、Codex 试用套装）。真正的瓶颈通常不是模型能力，而是你给它的上下文（文档）够不够好。

快速上手步骤

1. 理解 Agent 与 Skill 的关系：Agent 是执行引擎（负责调模型、读文件、改代码），Skill 是结构化指令文档（告诉 Agent 你的项目结构、编码规范、操作流程）。文档质量直接决定 Agent 的输出质量，好的文档可以让不同 Agent 平台的产出高度一致。
2. 编写项目文档：在项目根目录创建 AGENTS.md，至少包含：项目概述（技术栈、目录结构、关键模块）、工作流说明（新增功能怎么做、修 bug 步骤、发布流程）、规则文档（命名规范、注释要求、踩坑记录）。
3. 让 AI 辅助写文档：将 karpathy 的 llm-wiki gist 或已有的项目规范喂给 AI，让它自动生成 AGENTS.md 和各模块的 SKILL 文档，人工审核后放入项目目录。
4. 切换平台验证：用不同的免费 Agent 平台（OpenCode、Qoder、Hermes 等）打开同一个项目，执行相同任务（如修 bug、加功能），对比输出质量。如果文档完备，差异应该很小。

原文地址：https://lichuanyang.top/posts/26060/

我试过用Confluence、Notion、甚至Git仓库的README来管理，但效果都不理想。直到看到了Karpathy提的llm-wiki思路，才觉得这可能是个突破口。

Karpathy的llm-wiki是什么？

Karpathy在Gist里提了个想法：让LLM维护一个Wiki中间层。原话是”the wiki is a persistent, compounding artifact”——这个Wiki层就像个编译器，把原始文档编译成结构化数据，这样LLM每次回答问题时就不用从头在原始文档里”找”信息，直接查Wiki就行。

我觉得这个思路特别妙。传统文档管理是”存”和”找”，而llm-wiki是”编译”和”查询”。原始文档可能很乱、有重复、甚至有矛盾，但Wiki层是干净、结构化、有交叉引用的。

举个例子：我们团队有十几份安全开发规范文档，从输入验证到渗透测试都有，还有近十份安全故障复盘报告。这些文档格式不一，有的在Word里，有的在Markdown里，有的甚至只是Slack聊天记录。如果让LLM直接处理这些原始材料，效率会很低。但如果先”编译”成Wiki，效果就完全不一样了。

我的实现过程

第一步：生成CLAUDE.md

我首先把Karpathy的Gist链接丢给Claude，让它基于这个思路生成一份CLAUDE.md文件。这个文件相当于给LLM的”操作手册”，告诉它如何维护Wiki。

生成的CLAUDE.md包含了几个关键部分：

• 三层架构说明（raw → wiki → output）
• Wiki页面规范（frontmatter格式、交叉引用规则）
• 摄入工作流（如何处理新素材）
• 查询工作流（如何回答用户问题）
• Lint检查（如何保证Wiki健康）

实际用下来，我发现模型生成的结果基本可用，没有做太多微调。只是另外让AI生成了output层，用于存放最终的规范文档。这样三层架构就完整了：raw放原始素材，wiki放结构化Wiki，output放最终输出。

第二步：收集和整理原始素材

这是最耗时的一步。我把散落在各处的安全开发规范文档和故障案例都收集起来，统一放到raw/sources/目录下。为了保持原貌，我没有修改这些文件的内容，也没有统一格式——PDF、Word、PPT、Markdown等各种格式直接放到raw层就行，模型都可以处理。

具体来说，我收集了：

• 十几份安全开发规范文档：涵盖输入验证、SQL注入防护、XSS防护、CSRF防护、敏感数据保护、日志安全等
• 近十份安全故障复盘报告：包括SQL注入漏洞、越权访问、敏感信息泄露、会话劫持等真实案例
• 几份安全架构方案文档：涉及零信任架构、安全编码指南、渗透测试流程等

这些素材质量参差不齐。有的写得很规范，有清晰的标题和列表；有的就是随手记的笔记，甚至还有截图。但没关系，llm-wiki的妙处就在于它能处理这种”脏数据”。

第三步：让LLM生成Wiki层

有了CLAUDE.md和原始素材，就可以让LLM开始工作了。我这里用的是Claude，主要是因为它的上下文窗口足够大，能一次性处理较多内容。

具体操作是这样的：

1. 把CLAUDE.md作为系统提示词
2. 告诉LLM：”请按照CLAUDE.md中的规范，处理raw/sources/目录下的所有素材，生成wiki层”
3. LLM会依次读取每个原始文件，提取关键信息，生成对应的Wiki页面

这个过程不是一次就能完成的。LLM生成的初版Wiki会有一些问题：

• 交叉引用不够充分
• 有些概念没有被提取成独立页面
• 页面之间的逻辑关系不够清晰

所以需要多轮迭代。我会检查生成的Wiki，指出问题，让LLM修正。比如：
“这个故障案例里提到了’连接池配置不当’，但为什么没有对应的concept页面？请创建一个[[connection-pool-best-practices]]页面，并在故障案例里引用它。”

经过5-6轮迭代，Wiki层才逐渐成型。

第四步：生成最终规范文档

Wiki层准备好后，就可以生成最终的规范文档了。我让LLM基于Wiki层，生成一份面向开发者的、可直接阅读的规范文档。

这里有个设计决策：最终文档是放在output/目录下，而不是直接修改原始素材。这样保持了三层架构的清晰性：

• raw/：原始素材，不可修改
• wiki/：结构化Wiki，LLM维护
• output/：最终输出，人类阅读

生成的规范文档有几个特点：

1. 每个规范条目都有”为什么”——不只是说”要这样做”，还解释”为什么要这样做”
2. 相关的故障案例会作为”反面教材”链接在旁边
3. 有交叉引用，比如”数据库连接池配置”会链接到”连接池最佳实践”这个concept页面

实际效果

阅读体验

最终的规范文档可以直接用Obsidian打开阅读。因为是Markdown格式，支持：

• 代码块高亮
• 内部链接跳转（点击就能跳转到相关概念或故障案例）
• 标签筛选（比如筛选所有#安全相关的规范）

更重要的是，每条安全规范都关联着真实的故障案例。比如在”SQL注入防护”这条规范旁边，就链接着[[sql-injection-vulnerability-incident]]这个故障案例，详细描述了漏洞是怎么产生的、造成了什么影响、怎么修复的。这样开发者不仅能知道”要怎么做”，还能看到”不这么做会出什么问题”。

比起以前散落在各处的文档，阅读体验好了不止一个量级。

LLM问答

更强大的是LLM问答能力。因为有了Wiki层，LLM回答问题时特别准。比如我问：
“数据库批量更新时要注意什么？”

LLM会：

1. 先在Wiki里找到[[batch-operation-security]]这个concept页面
2. 结合[[sql-injection-batch-incident]]这个故障案例
3. 给出具体的建议：必须使用参数化查询、禁止字符串拼接SQL、批量操作要有事务控制、超大批次要分页处理等
4. 还会解释为什么：因为批量操作一旦出问题，影响范围是单条操作的N倍

再比如问：”用户上传文件怎么处理才安全？”

LLM会：

1. 找到[[file-upload-security]]这个concept页面
2. 结合[[malicious-file-upload-incident]]这个故障案例
3. 给出具体建议：文件类型白名单校验、文件内容检测、重命名存储、限制文件大小、隔离存储等

这比让LLM在十几份原始文档里”找”答案要靠谱得多。

持续更新

最让我满意的是更新机制。当有新的规范文档或故障报告时，我只需要：

1. 把新文件放到raw/sources/目录下
2. 告诉LLM：”有新素材需要摄入”
3. LLM会自动更新Wiki层和规范文档

比如上周我们出了个新的安全故障：因为用户输入未过滤导致XSS漏洞。我把故障报告放到raw目录后，LLM自动：

1. 创建了[[xss-user-input-incident]]这个故障案例页面
2. 更新了[[input-validation-security]]这个concept页面，补充了XSS相关的注意事项
3. 在规范文档的”输入验证规范”章节增加了相关条目

遇到的问题和解决方案

问题1：LLM生成的Wiki质量不稳定

刚开始时，LLM生成的Wiki质量波动很大。有时能很好地提取关键信息，有时会漏掉重要内容。

解决方案：我细化了CLAUDE.md里的Wiki页面规范。比如要求每个页面必须有：

• Summary行：一句话描述核心内容
• Tags行：用#标签标记主题
• 明确的页面类型（concept/entity/source/comparison）

对于安全故障案例，还要求包含：漏洞类型、攻击向量、影响范围、修复方案、预防措施。这样LLM就有更清晰的指导，生成质量稳定了很多。

问题2：交叉引用经常断裂

Wiki的核心价值在于交叉引用，但LLM经常创建单向链接，或者链接到不存在的页面。

解决方案：在CLAUDE.md里强化了交叉引用规则：

1. 必须双向链接：如果A页面引用了[[B]]，那么B页面也必须引用[[A]]
2. frontmatter里的related字段必须和正文里的[[wiki-link]]一致
3. 只能引用已存在的页面，需要先创建再引用

我还加了Lint检查，定期检查断裂链接和孤儿页面。

问题3：处理非结构化素材效率低

有些原始素材质量很差，比如截图、手写笔记、甚至是Slack聊天记录的导出。LLM处理这些素材时效率很低。

解决方案：对于这类素材，我会先手动整理成结构化的Markdown，再交给LLM处理。虽然增加了前期工作量，但保证了最终质量。

一些经验教训

1. 不要追求一步到位。llm-wiki是个迭代过程。第一版Wiki肯定不完美，但可以通过持续迭代改进。

2. CLAUDE.md要不断优化。随着使用，你会发现CLAUDE.md里缺失的规则。比如我后来加了”安全故障案例必须包含：漏洞类型、攻击向量、影响范围、修复方案、预防措施”这样的结构化要求。

3. 保持三层架构的纯净。raw/就是raw/，不要修改；wiki/由LLM维护；output/面向人类。混在一起会越来越乱。

4. 定期做健康检查。我会每周跑一次Lint，检查断裂链接、孤儿页面、单向链接等问题。发现问题及时修复。

5. 接受不完美。LLM生成的Wiki不会100%准确，会有遗漏和错误。但相比完全靠人工维护，已经好太多了。

总结

用llm-wiki管理安全开发规范，本质上是把”文档管理”变成了”知识工程”。原始文档是”原材料”，Wiki是”半成品”，规范文档是”成品”。LLM在这个过程中充当了”编译器”和”维护者”的角色。

这个方法最大的价值是可持续性。传统的文档管理，时间一长就会荒废，因为维护成本太高。而llm-wiki把维护成本转移给了LLM，人类只需要：

1. 提供原始素材（这个避免不了）
2. 检查和修正LLM的工作（比从头写轻松多了）
3. 使用最终产出（享受成果）

如果你也在为安全开发规范的管理头疼，不妨试试这个思路。不用完全照搬我的实现，关键是理解”Wiki中间层”这个核心理念。至于具体用什么工具、怎么组织目录，都可以根据实际情况调整。

毕竟，工具是为人服务的，不是吗？

原文地址: https://lichuanyang.top/posts/88001/

常见问题

Q: LLM 生成的代码或规范文档安全吗？会不会引入新的安全风险？

llm-wiki 方案中，LLM 的角色是”编译器”而非”独立决策者”——它将原始的安全规范文档提取、结构化、交叉引用，最终生成的规范文档来源于团队已有的安全知识，并不是 LLM 凭空创造的。真正需要关注的风险点是：1) 原始素材本身是否正确（LLM 不会替你验证这一点）；2) LLM 可能会遗漏某些安全条款（因此需要人工审核）。LLM 本身不会主动引入安全漏洞，但过度信赖未经审核的 LLM 输出才是真正的风险。

Q: 用 LLM 管理规范后，如何审核和保证质量？

文中总结了三层质量保障机制：1) CLAUDE.md 规范约束：通过结构化的模板要求（如安全故障案例必须包含漏洞类型、攻击向量、影响范围、修复方案、预防措施），让 LLM 有章可循；2) 多轮迭代：初版 Wiki 不会完美，作者用了 5-6 轮迭代让 LLM 修正交叉引用、补充遗漏概念；3) 定期 Lint 检查：每周检查断裂链接、孤儿页面、单向链接等结构问题。最可靠的是人工最终校验——LLM 降低维护成本，但不替代人工把关。

Q: llm-wiki 方案和传统 lint 工具（SonarQube、ESLint 等）有何不同？

两者是互补关系，解决不同层次的问题。传统 lint 工具是规则引擎——检查代码是否违反预定义规则（如 SQL 注入、XSS），工作在代码层面，规则固定。llm-wiki 是知识管理工具——解决规范文档散落、新人学习成本高、故障经验无法沉淀复用的问题，工作在知识层面。理想状态下，llm-wiki 产出的规范可以作为 lint 规则的来源，而 lint 工具则自动化地检查代码是否遵守这些规范。

Q: 三层架构（raw/wiki/output）为什么重要？混在一起会怎样？

三层架构的核心是保持知识流向的单向性：raw 是原始素材（不可修改，保持原貌），wiki 是 LLM 维护的结构化中间层（可迭代优化），output 是面向人类的最终产出（直接可读）。混在一起的后果：1) 原始素材和加工产物无法区分，出问题时难以溯源；2) 修改 output 后 wiki 层过时，LLM 下次查询会给出矛盾信息；3) 维护成本回归传统模式——每次更新都要同时改多个地方。作者强调”保持三层架构的纯净”是方案可持续的关键。

首先，我们来思考一下，如果要做一个类似prometheus的监控系统，都有哪些难点，比如

• 每个服务的监控需求都不一样，那么对于监控系统来说，要怎么设计其数据模型，才能取得易用性和通用性之间的平衡
• 大量的数据量要如何存储
• 怎样能实现各种复杂的报表
• …

带着这些问题，我们就来看看prometheus是怎么设计的。

历史

让我们先从历史说起，prometheus最早由SoundCloud开发，后来捐赠到开源社区。在2016年假如CNCF, 即云原生计算基金会。Prometheus是CNCF的第二个项目，仅次于kubernets。 因此，可想而知，promethous在整个云原生体系中有多么重要的作用。Prometheus也逐渐成了云原生下监控系统的事实标准。

核心设计理念

对于一个监控系统来说，核心要解决的问题其实就三个：

1. 监控指标用什么形式表示
2. 怎么收集和存储指标
3. 怎么利用指标生成报表

对于这三个问题，prometheus都给出了很巧妙的解决方案。

数据模型

romethous的数据模型，简而言之，就是一个「时序」的 Metric数据。所谓metric, 就是数据的测量值，而所谓时序，就是这些metric, 会源源不断的产生不同时间点的数据。

Metric有唯一的名称标识，也可以设置多个label, 可以用于过滤和聚合，其格式如下。

1

<metric name>{<label name>=<label value>, ...}

这样，对于任何业务，我们都可以将监控数据设计成统一的metric格式。这样对于promethous来说，方案可以足够简单，只用处理这一种数据格式就可以。而同时又足以方便的应对千变万化的业务场景。

Prometheus提供了 counter, gauge, histogram, summary 四种核心的metric, 不过其区别仅体现在client端和promQL中。截至目前(2021.11)， 不同的metric 类型在 prometheus server 这一侧并不会有什么区别，

数据收集和存储

Prometheus server会定时从要监控的服务暴露出的http接口上抓取数据，是一种典型的拉模型。

相对推模型，拉模型会有一些好处，比如更容易监测某一个节点是否正常；更容易本地调试等。当然，对于一个监控系统来说，采用推还是拉，其实并不是一个主要问题。

Prometheus的数据是典型的时序数据，prometheus本身会将数据存储在本地磁盘上。要注意的是，本地存储不可复制，无法构建集群，如果本地磁盘或节点出现故障，存储将无法扩展和迁移。因此一般只能把本地存储视为近期数据的短暂滑动窗口。

而关于持久化存储的问题，prometheus实际上并没有试图解决。它的做法是定义出标准的读写接口，从而可以将数据存储到任意一个第三方存储上。

生成报表

Prometheus定义了功能强大的promQL, 可以满足各种复杂的查询场景，具体可参考 https://prometheus.io/docs/prometheus/latest/querying/basics/

周边生态

一个开源项目的发展，当然离不开周边生态的发展。而prometheus目前已经有了很完善的生态，在java, go, python等主流的开发语言下，都有完善的client包可以使用； 像spring中，可以很容易的为多种组件增加打点，这一点，在下边的实战环节我们会细讲；在kubernetes中，可以轻易的配置自动去各个节点抓取prometheus数据；借助grafana等工具，也可以配置出多种多样的报表。

实战

教程的接下来一部分，我们会以springboot项目为例，来看一看prometheus的实际效果。

其核心思路就是使用spring-actuator 为springboot应用配置监控，并以promethous的结构暴露出来。

首先，引入依赖

1
2

implementation("org.springframework.boot:spring-boot-starter-actuator")
implementation("io.micrometer:micrometer-registry-prometheus")

然后添加spring配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

management:
  endpoints:
    web:
      exposure:
        include: "prometheus"
  metrics:
    distribution:
      sla:
        http:
          server:
            requests: "100ms,150ms,250ms,500ms,1s"
      percentiles-histogram:
        http:
          server:
            requests: true
    web:
      server:
        request:
          autotime:
            enabled: true
    export:
      prometheus:
        enabled: true
    tags:
      application: name

这个配置里，其实做了几件事：将数据以prometheus的格式暴露出来；自动为http请求添加histogram监控；增加一个application标识，这个标识会作为一个label出现在所有metric中。

之后，启动springboot项目，并且访问/actuator/prometheus路径，就可以看到大量metric, 比如

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

# HELP executor_pool_size_threads The current number of threads in the pool
# TYPE executor_pool_size_threads gauge
executor_pool_size_threads{application="ads-programad",name="asyncExecutor",} 0.0
# HELP tomcat_servlet_request_seconds  
# TYPE tomcat_servlet_request_seconds summary
tomcat_servlet_request_seconds_count{application="ads-programad",name="dispatcherServlet",} 1.0
tomcat_servlet_request_seconds_sum{application="ads-programad",name="dispatcherServlet",} 0.0
# HELP executor_pool_core_threads The core number of threads for the pool
# TYPE executor_pool_core_threads gauge
executor_pool_core_threads{application="ads-programad",name="asyncExecutor",} 70.0
# HELP jvm_classes_unloaded_classes_total The total number of classes unloaded since the Java virtual machine has started execution
# TYPE jvm_classes_unloaded_classes_total counter
jvm_classes_unloaded_classes_total{application="ads-programad",} 0.0
# HELP executor_completed_tasks_total The approximate total number of tasks that have completed execution
# TYPE executor_completed_tasks_total counter
executor_completed_tasks_total{application="ads-programad",name="asyncExecutor",} 0.0
# HELP tomcat_threads_config_max_threads  
# TYPE tomcat_threads_config_max_threads gauge
tomcat_threads_config_max_threads{application="ads-programad",name="http-nio-9000",} 500.0
# HELP process_cpu_usage The "recent cpu usage" for the Java Virtual Machine process
# TYPE process_cpu_usage gauge
process_cpu_usage{application="ads-programad",} 0.0
# HELP tomcat_sessions_active_current_sessions  
# TYPE tomcat_sessions_active_current_sessions gauge
tomcat_sessions_active_current_sessions{application="ads-programad",} 0.0
# HELP jvm_memory_committed_bytes The amount of memory in bytes that is committed for the Java virtual machine to use
# TYPE jvm_memory_committed_bytes gauge
jvm_memory_committed_bytes{application="ads-programad",area="heap",id="G1 Eden Space",} 3.5651584E7
jvm_memory_committed_bytes{application="ads-programad",area="heap",id="G1 Old Gen",} 4.6137344E7
jvm_memory_committed_bytes{application="ads-programad",area="nonheap",id="Compressed Class Space",} 5767168.0
jvm_memory_committed_bytes{application="ads-programad",area="nonheap",id="CodeHeap 'non-profiled nmethods'",} 8847360.0
jvm_memory_committed_bytes{application="ads-programad",area="nonheap",id="CodeHeap 'non-nmethods'",} 2555904.0
jvm_memory_committed_bytes{application="ads-programad",area="nonheap",id="Metaspace",} 4.2287104E7
jvm_memory_committed_bytes{application="ads-programad",area="heap",id="G1 Survivor Space",} 4194304.0
# HELP tomcat_servlet_request_max_seconds  
# TYPE tomcat_servlet_request_max_seconds gauge
tomcat_servlet_request_max_seconds{application="ads-programad",name="dispatcherServlet",} 0.0
# HELP tomcat_connections_current_connections  
# TYPE tomcat_connections_current_connections gauge
tomcat_connections_current_connections{application="ads-programad",name="http-nio-9000",} 3.0
# HELP tomcat_sessions_active_max_sessions  
# TYPE tomcat_sessions_active_max_sessions gauge
...

其中，除了我们显式配置的http监控，其实还有大量的jvm, 机器负载等基础的监控信息。

除此之外，对于其他组件的监控也很容易添加，诸如线程池、http连接池、自定义监控等，可以参考 https://github.com/lcy362/springboot-prometheus-demo

这样，无论这个springboot项目如何部署，无论是用java原生的部署，还是用docker部署，还是部署在kubernetes上，都可以非常容易的获取各个监控metrics数据。

快速上手步骤

Step 1: 安装和配置 Prometheus

首先在服务器上下载并安装 Prometheus，编辑 prometheus.yml 配置文件，设置 global 抓取间隔和 evaluation interval 等基本参数。启动 Prometheus 后，访问 http://localhost:9090 即可打开 Web UI 界面。

Step 2: 配置数据采集目标

在配置文件的 scrape_configs 中定义需要监控的目标，包括你的应用暴露的 /actuator/prometheus 端点地址。通过 Spring Actuator 和 Micrometer 将 Spring Boot 应用的指标以 Prometheus 格式暴露出来，Prometheus 会按配置的间隔自动拉取数据。

Step 3: 编写 PromQL 查询

利用 Prometheus 内置的 PromQL 查询语言，可以对收集到的时序数据进行灵活查询。你可以按 metric 名称和 label 进行过滤、聚合、计算速率等操作，满足各种监控场景的分析需求。

Step 4: 对接 Grafana 可视化

将 Prometheus 作为数据源添加到 Grafana 中，利用 Grafana 丰富的面板和仪表盘功能，将监控数据以图表等可视化形式呈现。通过 Grafana 还可以设置告警规则，在指标异常时及时通知。

原文地址: https://lichuanyang.top/posts/28288/