先说一个现象开源项目能到 20 万星本身就是一件非常离谱的事。而如果这个项目还是零营销、零融资、纯靠社区口碑滚出来的那基本可以断定它踩中的绝对不是某个小圈子的自嗨需求而是一个普遍存在的、大家一直在忍的痛点。superpowers 就是这类项目。我第一次看到它的时候第一反应是“又一个大杂烩 Agent 配置库”但真正把它的 skills 体系、目录结构、规则加载方式过了一遍之后我的判断变了这已经不是单纯的提示词集合而是把整套 Agent 工程化的思路从“写一段巨型提示词”推进到了“设计一个文件系统”。很多人可能会觉得“文件系统”这个词夸张了。但如果你真正把一个 Agent 项目从几十行 prompt 做到几百个文件、几千行规则你会发现提示词工程这个赛道卷到最后拼的根本不是文笔而是组织结构。谁能让 Agent 在几万 token 的上下文中快速找到自己需要的那一段谁就能让复杂任务稳定落地。这也是这篇想聊的核心——superpowers 的 20 万星并非证明提示词技巧有什么新突破而是证明了文件系统化思维才是让 Agent 真正可扩展、可维护、可复用的终局答案。1. 20 万星背后到底证明了什么1.1 零营销零融资这个数据有多夸张先把这个星标数放到行业背景里看。一个开源项目要从零涨到 20 万星常规路径大概有三种第一种是靠大厂背书比如某个基础设施团队发布官方 SDK天然有流量入口第二种是靠资本推动融资之后疯狂做内容、做活动、买曝光把项目炒起来第三种是踩中平台红利比如某段时间 AI 工具集中爆发正好被算法推荐一波。superpowers 三条全不占。它没有任何公司主体在后面推也没有市场预算去做投放甚至从立项到现在的版本迭代看起来都更像一个“个人维护的高质量工具库”。20 万星意味着至少有 20 万个开发者主动点了 star并且相当一部分人 star 完还会实际拉下来用。这个数字背后是大量的技术口碑在滚动传播。这说明一件事在 Agent 开发这个领域大家缺的从来不是“更多技巧”而是“能直接用起来的组织方式”。superpowers 恰好把这个组织方式做对了。它告诉你与其每次写一大堆提示词和角色设定不如用一套可复用的 skills 体系把能力像积木一样拼起来。另一个值得注意的点是零融资在 AI 开源项目里其实是一种很特殊的“信任信号”。有钱投入的项目往往会追求生态扩张、商业化闭环路线会变得比较复杂。而纯社区驱动的项目设计和维护的动力一般都很纯粹就是为了让自己用着顺手。这种“顺手”反而更容易被一线开发者信任。因为大家心里清楚一个不急着赚钱的工具大概率不会在某一天突然改变接口、夹带私货。1.2 大模型的“文件系统”到底是什么如果说 20 万星是结果那么“文件系统”这个隐喻就是 superpowers 给我的最大启发。传统意义上我们跟大模型交互的载体就是一段对话。你给它一段长长的提示词它根据这段文字生成回复。这种方式在小任务上没什么问题但一旦任务变复杂需求变多样问题就出现了所有知识、规则、技能全部挤在一个字符串里维护成本高、互相干扰严重、换一个场景就得重新写一遍。superpowers 的解法是把 Agent 的知识和能力全部“落盘”——每个能力雨一个 skill每个 skill 是一个独立目录目录里有 SKILL.md 描述文件、有参考文档、有可执行的脚本或模板。Agent 在启动时不是把整个库全部加载进上下文而是先读最顶层的索引和路由规则再根据用户需求按需加载对应 skill。这个结构和操作系统的文件系统几乎一模一样inode 存储元数据目录做层级跳转文件内容按需读取。只不过这里的“数据”变成了 Agent 的知识、工作流和决策逻辑。我甚至觉得“文件系统”这个词最关键的价值是给提示词工程建立了一种工程化的心理模型。一旦你开始用目录、文件、命名规范、版本管理来组织提示词你就会自然地用处理代码工程的眼光来看待它要考虑可维护性、可测试性、可复用性要考虑命名是否自解释要考虑架构是否分层。所有这些在单一文本 prompt 的模式下是完全做不到的。所以 superpowers 的“文件系统”不是把一堆 markdown 文件叠在一起而是一套 Agent 版的“知识管理协议”。这个协议生效之后20 万星的传播自然水到渠成——因为任何一个人拿到这套结构都能明显感受到自己的 Agent 从“单打独斗”变成了“带装备进场”。2. 为什么提示词工程的终局是文件系统2.1 从提示词到规则记忆的工程化先思考一个很底层的问题提示词到底是什么绝大多数人的理解是提示词就是我们告诉大模型该怎么做事的一段话。但如果你把一个复杂的 Agent 项目拆开看提示词的功能其实已经悄悄地分裂成了三种完全不同的东西第一种是设定行为模式的全局规则比如“你是资深前端工程师”“回答用中文”第二种是特定场景的执行步骤比如“当用户询问部署问题时先检查配置文件再给建议”第三种是即时的参考信息比如项目背景、代码片段、过往决策记录。这三类内容有一个共同的敌人上下文窗口。全局规则、执行步骤、背景知识全部塞进一段提示词即使窗口能装下模型也会在长文本中对早期内容“注意力稀释”。而更现实的问题是这些信息是动态变化的——规则会迭代、项目知识会积累、步骤会优化。如果所有东西都在一个文本文件里每一次改动都可能牵一发动全身。文件系统的核心价值就是把这三类内容分离开并且让它们分别以独立的文件存在。全局规则放在 rules 目录执行步骤沉淀为 skill项目知识写进 memory 或 references。Agent 运行时会根据当前任务决定读哪些文件而不是把所有东西一股脑全部加载。这种做法本质上是在做“记忆的工程化”让 Agent 的记忆不再是那个一次性灌满的上下文黑盒而变成一个可增量写入、按需检索、可持续演进的数据库。对人来说这就像你不再试图把整本百科全书背下来而是学会在遇到问题时知道去哪一本书、哪一页查。Agent 也是这样它需要的不全是“知道所有答案”而是“知道去哪里找答案”。文件系统给了它这个“去哪里找”的路标。2.2 文件系统解决了提示词的三大老大难如果说记忆工程化是宏观框架那落到日常开发文件系统在实操层面解决的三个问题是让 superpowers 这类项目在社区里疯传的直接原因。第一个老大难是维护。一段 6000 字的巨型 prompt一旦写到后期你改任何一个词都可能影响整体行为而且你根本不知道影响在哪里。文件系统把提示词拆成小颗粒文件后每次修改只发生在单个文件里影响范围可控。你可以像给代码写单元测试一样给每个 skill 单独验证改完一个文件不需要重新过一遍全局逻辑。第二个老大难是复用。传统的 prompt 复用方式就是复制、粘贴、改名字改完发现和项目其他部分有冲突又要继续改。而文件系统天然解决这个问题一个 skill 目录就是一个自包含的能力单元在这个项目里用过的“代码评审技能”换一个项目直接把目录复制过去就能用因为它的所有依赖都在自己文件夹里。第三个老大难是协作。当一个 Agent 项目只有你一个人维护时一切都好说。但当团队里多人共用一套规则、多个 Agent 共享一套流程时如果知识全在一个 prompt 里协作就是灾难。文件系统则完全面向协作设计用 Git 管理 skills 目录、用 issue 跟踪规则变更、用 PR 评审技能更新。这些在代码工程里已经验证过的协作模式在提示词领域终于也可以复用了。这三个问题的本质其实都是同一个信息没有结构就无法管理。而文件系统恰恰是“信息结构化”最熟悉、最通用、工具链最完善的载体。2.3 上下文管理的“工作量证明”20 万星还有一个很隐晦的指向在 Agent 应用里真正昂贵的不是 token而是调试时间。尤其当你面对一个复杂的 Agent 行为问题时往往不知道问题出在哪——是规则没生效是上下文被别的内容挤占是模型理解偏了还是技能文件本身写得含糊这类问题每排查一次都要烧掉大量时间和 token。文件系统的优势在于它让上下文的内容“可审计”。因为所有加载进上下文的规则、技能、项目记忆都是独立的文件你可以在日志里记录 Agent 到底读了哪些文件复盘时一眼就能看出问题出在哪一层。这种可审计性是传统单段提示词完全不具备的。我甚至觉得20 万星本身就是一种“工作量证明”。每一个 star都对应着一个开发者从“完全不知道上下文还能这样管理”到“原来可以这么做”的认知转变。star 不代表项目本身多完美但它亮明确地告诉大家这个方向值得投入这条路径已经被大量同行验证过了。所以如果你正在做一个复杂的 Agent 项目并且发现自己已经开始频繁地陷入“改 prompt 不掉不如重写一遍”的泥潭那大概率是因为你还在用“提示词思维”而不是“文件系统思维”。转换认知可能是你最近这段时间能做的性价比最高的优化。3. 一套可以抄作业的文件系统落地打法3.1 顶层目录怎么设计聊了这么多理论和趋势接下来进入实操环节。我基于 superpowers 的思路结合自己做 Agent 项目的经验整理了一套可以被“抄”的目录结构。这套结构不一定完美但对于一个中大型 Agent 项目来说已经足够覆盖大部分需求。agent-project/ ├── .agents/ │ ├── rules/ │ │ ├── global.md │ │ ├── coding.md │ │ └── output-format.md │ ├── skills/ │ │ ├── code-reviewer/ │ │ │ ├── SKILL.md │ │ │ ├── reference/ │ │ │ └── scripts/ │ │ ├──>--- name: code-reviewer description: 适用于代码评审场景特别是 PR 复查和代码质量检查。能自动识别常见的性能、安全和可维护性问题。 when_to_use: 当用户要求审查代码、复查 PR、或者提到代码质量改进时使用。 ---这个描述不是写给人看的而是写给模型的。它需要做到“任务触发词”和“能力描述”双覆盖。写得太抽象比如“一个用于代码分析的技能”Agent 在遇到“帮我看看这个函数有没有问题”时可能不会把它关联起来写得太具体比如“仅限 Python 代码评审”适用范围又会变得很窄。可执行性是指 Agent 拿到这个 skill 之后知道按什么顺序做什么事。这部分的正文一定要用步骤化表达## 执行流程 1. 阅读目标代码文件建立整体结构认知。 2. 按照 reference/ 中的检查清单逐项排查。 3. 把问题按严重程度分三类输出阻断性问题 / 建议优化 / 代码风格。 4. 如发现潜在修复方案用 script 目录中的模板输出 diff 示例。为什么要这么写因为大模型对“分步骤指令”的执行稳定性远高于对“抽象原则”的执行稳定性。你在提示词里写“认真审查代码、注意安全和性能问题”模型大体也会做但输出结构和结论可靠性完全没法预期。而当你把步骤明确到树的层面模型的每次输出就有了稳定的落点。有一个技巧我一直觉得很好用给 skill 配一个reference/或templates/目录。比如 code-reviewer 的 reference 里放一份常见的代码反模式清单report-generator 的 templates 里放一份周报模板。这些内容不会被默认加载但 skill 被激活后Agent 会主动去读。这就在不占用顶层上下文的前提下给模型“加餐”了大量高频质量信息。3.3 规则与工作流的组合策略文件系统里面最容易犯的一个错误就是把所有东西都放进 global.md 或规则文件导致全局规则越来越胖。我见过有人把“如果用户问代码问题就怎么回答”“如果用户问部署问题就怎么回答”全部堆进全局规则结果每个对话都要白白消耗大量 token而且不同规则之间经常打架。正确的做法是分成两层全局规则只放“不需要思考、永远成立”的内容比如输出语言、语气基调、安全边界所有“特定场景下的行为”都放到 workflow 或 skill 里。例如“每周五生成周报”这种动作就应该是一个 workflow而不是全局规则。一个干净的 global.md 大概是这样的# 全局规则 - 默认使用中文回复除非用户明确使用英文。 - 所有回答必须是结构化输出善用列表和表格。 - 不确定的信息必须明确标注禁止编造。 - 涉及代码更改时先输出方案再动手改。而功能性的流程比如“周报生成”就拆到 workflows 里用单独文件描述。workflow 和 skill 的区别也值得说一下skill 更像是能力模块一个技能可以被多个流程调用workflow 则是串联多个 skill 的流程脚本。比如 PR 评审 workflow可能先调用 code-reviewer 技能再调用代码统计脚本最后调用 report-generator 输出报告。把这两层分开之后整个 Agent 项目的扩展性会非常舒服。新加一个流程不需要改任何 skill只要编排新的 workflow 就行。这套分层组合的逻辑本质上跟写代码是一个思路全局常量放配置文件工具函数沉淀成库业务逻辑写在业务层。文件系统模式的“终局感”其实就来自于这种和传统软件工程高度对标的结构。4. 实操中的踩坑记录与排查心得4.1 文件系统方案常见的三大坑文件系统方案看着优雅实际操作起来坑一点也不少。我挑三个最常见的也是社区里反馈最集中的提前给你打个预防针。第一个坑是文件过载。很多人一开始都觉得“文件越多越好”于是把项目背景、用户偏好、历史决策、参考文档全部拆成几百个小文件。结果 Agent 每次启动光扫描文件目录就要耗掉一堆 token而且文件之间互相引用、信息重叠反而干扰判断。文件系统不是“拆得越碎越好”而是要拆到“刚好能按需加载”的粒度。如果两个文件经常需要同时读取那它们大概率应该合并成一个。第二个坑是描述失效。有些 SKILL.md 的 description 写得模棱两可导致的直接问题就是 Agent 在需要的时候不加载不需要的时候乱加载。这个问题的排查又特别隐蔽因为你在单个 skill 文件里永远看不出问题只有在真实对话中才能发现“它怎么没调用这个技能”。描述是需要反复打磨的而且最好用一个“冗余覆盖”策略把可能触发的场景词都写进 description宁可重复不可遗漏。第三个坑是规则冲突。global.md、skill 内的规则、workflow 里的步骤三个地方如果对同一件事有不同的说法模型的输出就会飘忽不定。比如全局规则说“所有回答必须简洁”某个 workflow 又要求“输出详细到每行代码都有注释”冲突一出现Agent 的优先级判断就会混乱。这个问题的解决办法是建立规则层级全局规则永远覆盖局部规则局部规则只能细化全局规则不能推翻。4.2 排查思路与调试技巧文件系统方案出问题时最大的难点在于你看不到 Agent 在内部到底做了什么决策。所以我的第一个建议是不管用什么框架一定要想办法让 Agent 自己“说出”它读了什么文件。做法很简单在全局规则里加一条“回答任何问题前如果你读了额外的 skill 或 reference 文件请在回答末尾列出你参考的路径并说明为什么选择这些文件。”这一条看起来有点蠢但实际排查效率极高。当问题出现的时候你不需要猜直接看它列出的路径就知道是索引出了问题、还是描述触发出了问题、还是文件本身的内容有 bug。第二个技巧是“单点验证”。一个 skill 写完之后不要直接放进整个 Agent 系统里测那样出了问题根本无法定位。正确姿势是只保留这一个 skill其他规则全部关掉给它一个最典型的触发任务看它的表现是否符合预期。这个流程就像单元测试通过之后再放回系统里做集成测试。调试成本会大幅降低。第三个技巧是用好版本记录。给每个 skill 的 SKILL.md 头部加一个version字段并且在文件里记录最近几次变更的原因。这样当你发现“之前能用现在怎么不行了”的时候可以先看版本变更记录快速定位是哪一次改动引入了回归。4.3 和传统方案相比的取舍最后再说一下文件系统和传统方法的边界问题很多人容易夸文件系统而否定一切别的方案这也不健康。如果你只是在做一个一次性问答脚本prompt 只有几百 token那完全没必要引入复杂的文件系统纯提示词反而是最优解。文件系统的收益要等上下文复杂度上来了才体现。一般来说当一个项目开始出现以下信号提示词超过 3000 token或者同一段规则已经被复制到超过三个地方或者你已经开始分不清某个设定应该在哪个版本里改——这时候就该上文件系统了。另外文件系统也不等于 RAG检索增强生成。RAG 解决的是“海量外部知识的检索”问题而文件系统解决的是“Agent 内部知识结构和决策路由”的问题。两者可以协同RAG 负责从知识库召回事实文件系统负责决定“当需要事实的时候去查 RAG 的哪个索引”。很多人一开始会把文件系统当成 RAG 的替代品实际用下来会发现它们根本不是一个层级的东西。从我个人的实践看文件系统方案的维护成本前期确实比单一 prompt 模式高但这种成本是一次性的。当你把规则、技能、工作流都沉淀成独立文件之后后续每一次改动都是局部操作项目越复杂这套结构就越划算。就像写代码一样前期架构总是最痛苦的但架构质量决定了一个项目到底能走到多大。最后分享一个小技巧如果你不想从零开始搭文件系统可以先只做一个skills/目录把一个最常用的功能拆成第一个 skill边用边补。不用一上来就搞全套很多项目根本用不到全部层级。文件系统是手段不是目的别让方法论变成了新的负担。
先说一个现象开源项目能到 20 万星本身就是一件非常离谱的事。而如果这个项目还是零营销、零融资、纯靠社区口碑滚出来的那基本可以断定它踩中的绝对不是某个小圈子的自嗨需求而是一个普遍存在的、大家一直在忍的痛点。superpowers 就是这类项目。我第一次看到它的时候第一反应是“又一个大杂烩 Agent 配置库”但真正把它的 skills 体系、目录结构、规则加载方式过了一遍之后我的判断变了这已经不是单纯的提示词集合而是把整套 Agent 工程化的思路从“写一段巨型提示词”推进到了“设计一个文件系统”。很多人可能会觉得“文件系统”这个词夸张了。但如果你真正把一个 Agent 项目从几十行 prompt 做到几百个文件、几千行规则你会发现提示词工程这个赛道卷到最后拼的根本不是文笔而是组织结构。谁能让 Agent 在几万 token 的上下文中快速找到自己需要的那一段谁就能让复杂任务稳定落地。这也是这篇想聊的核心——superpowers 的 20 万星并非证明提示词技巧有什么新突破而是证明了文件系统化思维才是让 Agent 真正可扩展、可维护、可复用的终局答案。1. 20 万星背后到底证明了什么1.1 零营销零融资这个数据有多夸张先把这个星标数放到行业背景里看。一个开源项目要从零涨到 20 万星常规路径大概有三种第一种是靠大厂背书比如某个基础设施团队发布官方 SDK天然有流量入口第二种是靠资本推动融资之后疯狂做内容、做活动、买曝光把项目炒起来第三种是踩中平台红利比如某段时间 AI 工具集中爆发正好被算法推荐一波。superpowers 三条全不占。它没有任何公司主体在后面推也没有市场预算去做投放甚至从立项到现在的版本迭代看起来都更像一个“个人维护的高质量工具库”。20 万星意味着至少有 20 万个开发者主动点了 star并且相当一部分人 star 完还会实际拉下来用。这个数字背后是大量的技术口碑在滚动传播。这说明一件事在 Agent 开发这个领域大家缺的从来不是“更多技巧”而是“能直接用起来的组织方式”。superpowers 恰好把这个组织方式做对了。它告诉你与其每次写一大堆提示词和角色设定不如用一套可复用的 skills 体系把能力像积木一样拼起来。另一个值得注意的点是零融资在 AI 开源项目里其实是一种很特殊的“信任信号”。有钱投入的项目往往会追求生态扩张、商业化闭环路线会变得比较复杂。而纯社区驱动的项目设计和维护的动力一般都很纯粹就是为了让自己用着顺手。这种“顺手”反而更容易被一线开发者信任。因为大家心里清楚一个不急着赚钱的工具大概率不会在某一天突然改变接口、夹带私货。1.2 大模型的“文件系统”到底是什么如果说 20 万星是结果那么“文件系统”这个隐喻就是 superpowers 给我的最大启发。传统意义上我们跟大模型交互的载体就是一段对话。你给它一段长长的提示词它根据这段文字生成回复。这种方式在小任务上没什么问题但一旦任务变复杂需求变多样问题就出现了所有知识、规则、技能全部挤在一个字符串里维护成本高、互相干扰严重、换一个场景就得重新写一遍。superpowers 的解法是把 Agent 的知识和能力全部“落盘”——每个能力雨一个 skill每个 skill 是一个独立目录目录里有 SKILL.md 描述文件、有参考文档、有可执行的脚本或模板。Agent 在启动时不是把整个库全部加载进上下文而是先读最顶层的索引和路由规则再根据用户需求按需加载对应 skill。这个结构和操作系统的文件系统几乎一模一样inode 存储元数据目录做层级跳转文件内容按需读取。只不过这里的“数据”变成了 Agent 的知识、工作流和决策逻辑。我甚至觉得“文件系统”这个词最关键的价值是给提示词工程建立了一种工程化的心理模型。一旦你开始用目录、文件、命名规范、版本管理来组织提示词你就会自然地用处理代码工程的眼光来看待它要考虑可维护性、可测试性、可复用性要考虑命名是否自解释要考虑架构是否分层。所有这些在单一文本 prompt 的模式下是完全做不到的。所以 superpowers 的“文件系统”不是把一堆 markdown 文件叠在一起而是一套 Agent 版的“知识管理协议”。这个协议生效之后20 万星的传播自然水到渠成——因为任何一个人拿到这套结构都能明显感受到自己的 Agent 从“单打独斗”变成了“带装备进场”。2. 为什么提示词工程的终局是文件系统2.1 从提示词到规则记忆的工程化先思考一个很底层的问题提示词到底是什么绝大多数人的理解是提示词就是我们告诉大模型该怎么做事的一段话。但如果你把一个复杂的 Agent 项目拆开看提示词的功能其实已经悄悄地分裂成了三种完全不同的东西第一种是设定行为模式的全局规则比如“你是资深前端工程师”“回答用中文”第二种是特定场景的执行步骤比如“当用户询问部署问题时先检查配置文件再给建议”第三种是即时的参考信息比如项目背景、代码片段、过往决策记录。这三类内容有一个共同的敌人上下文窗口。全局规则、执行步骤、背景知识全部塞进一段提示词即使窗口能装下模型也会在长文本中对早期内容“注意力稀释”。而更现实的问题是这些信息是动态变化的——规则会迭代、项目知识会积累、步骤会优化。如果所有东西都在一个文本文件里每一次改动都可能牵一发动全身。文件系统的核心价值就是把这三类内容分离开并且让它们分别以独立的文件存在。全局规则放在 rules 目录执行步骤沉淀为 skill项目知识写进 memory 或 references。Agent 运行时会根据当前任务决定读哪些文件而不是把所有东西一股脑全部加载。这种做法本质上是在做“记忆的工程化”让 Agent 的记忆不再是那个一次性灌满的上下文黑盒而变成一个可增量写入、按需检索、可持续演进的数据库。对人来说这就像你不再试图把整本百科全书背下来而是学会在遇到问题时知道去哪一本书、哪一页查。Agent 也是这样它需要的不全是“知道所有答案”而是“知道去哪里找答案”。文件系统给了它这个“去哪里找”的路标。2.2 文件系统解决了提示词的三大老大难如果说记忆工程化是宏观框架那落到日常开发文件系统在实操层面解决的三个问题是让 superpowers 这类项目在社区里疯传的直接原因。第一个老大难是维护。一段 6000 字的巨型 prompt一旦写到后期你改任何一个词都可能影响整体行为而且你根本不知道影响在哪里。文件系统把提示词拆成小颗粒文件后每次修改只发生在单个文件里影响范围可控。你可以像给代码写单元测试一样给每个 skill 单独验证改完一个文件不需要重新过一遍全局逻辑。第二个老大难是复用。传统的 prompt 复用方式就是复制、粘贴、改名字改完发现和项目其他部分有冲突又要继续改。而文件系统天然解决这个问题一个 skill 目录就是一个自包含的能力单元在这个项目里用过的“代码评审技能”换一个项目直接把目录复制过去就能用因为它的所有依赖都在自己文件夹里。第三个老大难是协作。当一个 Agent 项目只有你一个人维护时一切都好说。但当团队里多人共用一套规则、多个 Agent 共享一套流程时如果知识全在一个 prompt 里协作就是灾难。文件系统则完全面向协作设计用 Git 管理 skills 目录、用 issue 跟踪规则变更、用 PR 评审技能更新。这些在代码工程里已经验证过的协作模式在提示词领域终于也可以复用了。这三个问题的本质其实都是同一个信息没有结构就无法管理。而文件系统恰恰是“信息结构化”最熟悉、最通用、工具链最完善的载体。2.3 上下文管理的“工作量证明”20 万星还有一个很隐晦的指向在 Agent 应用里真正昂贵的不是 token而是调试时间。尤其当你面对一个复杂的 Agent 行为问题时往往不知道问题出在哪——是规则没生效是上下文被别的内容挤占是模型理解偏了还是技能文件本身写得含糊这类问题每排查一次都要烧掉大量时间和 token。文件系统的优势在于它让上下文的内容“可审计”。因为所有加载进上下文的规则、技能、项目记忆都是独立的文件你可以在日志里记录 Agent 到底读了哪些文件复盘时一眼就能看出问题出在哪一层。这种可审计性是传统单段提示词完全不具备的。我甚至觉得20 万星本身就是一种“工作量证明”。每一个 star都对应着一个开发者从“完全不知道上下文还能这样管理”到“原来可以这么做”的认知转变。star 不代表项目本身多完美但它亮明确地告诉大家这个方向值得投入这条路径已经被大量同行验证过了。所以如果你正在做一个复杂的 Agent 项目并且发现自己已经开始频繁地陷入“改 prompt 不掉不如重写一遍”的泥潭那大概率是因为你还在用“提示词思维”而不是“文件系统思维”。转换认知可能是你最近这段时间能做的性价比最高的优化。3. 一套可以抄作业的文件系统落地打法3.1 顶层目录怎么设计聊了这么多理论和趋势接下来进入实操环节。我基于 superpowers 的思路结合自己做 Agent 项目的经验整理了一套可以被“抄”的目录结构。这套结构不一定完美但对于一个中大型 Agent 项目来说已经足够覆盖大部分需求。agent-project/ ├── .agents/ │ ├── rules/ │ │ ├── global.md │ │ ├── coding.md │ │ └── output-format.md │ ├── skills/ │ │ ├── code-reviewer/ │ │ │ ├── SKILL.md │ │ │ ├── reference/ │ │ │ └── scripts/ │ │ ├──>--- name: code-reviewer description: 适用于代码评审场景特别是 PR 复查和代码质量检查。能自动识别常见的性能、安全和可维护性问题。 when_to_use: 当用户要求审查代码、复查 PR、或者提到代码质量改进时使用。 ---这个描述不是写给人看的而是写给模型的。它需要做到“任务触发词”和“能力描述”双覆盖。写得太抽象比如“一个用于代码分析的技能”Agent 在遇到“帮我看看这个函数有没有问题”时可能不会把它关联起来写得太具体比如“仅限 Python 代码评审”适用范围又会变得很窄。可执行性是指 Agent 拿到这个 skill 之后知道按什么顺序做什么事。这部分的正文一定要用步骤化表达## 执行流程 1. 阅读目标代码文件建立整体结构认知。 2. 按照 reference/ 中的检查清单逐项排查。 3. 把问题按严重程度分三类输出阻断性问题 / 建议优化 / 代码风格。 4. 如发现潜在修复方案用 script 目录中的模板输出 diff 示例。为什么要这么写因为大模型对“分步骤指令”的执行稳定性远高于对“抽象原则”的执行稳定性。你在提示词里写“认真审查代码、注意安全和性能问题”模型大体也会做但输出结构和结论可靠性完全没法预期。而当你把步骤明确到树的层面模型的每次输出就有了稳定的落点。有一个技巧我一直觉得很好用给 skill 配一个reference/或templates/目录。比如 code-reviewer 的 reference 里放一份常见的代码反模式清单report-generator 的 templates 里放一份周报模板。这些内容不会被默认加载但 skill 被激活后Agent 会主动去读。这就在不占用顶层上下文的前提下给模型“加餐”了大量高频质量信息。3.3 规则与工作流的组合策略文件系统里面最容易犯的一个错误就是把所有东西都放进 global.md 或规则文件导致全局规则越来越胖。我见过有人把“如果用户问代码问题就怎么回答”“如果用户问部署问题就怎么回答”全部堆进全局规则结果每个对话都要白白消耗大量 token而且不同规则之间经常打架。正确的做法是分成两层全局规则只放“不需要思考、永远成立”的内容比如输出语言、语气基调、安全边界所有“特定场景下的行为”都放到 workflow 或 skill 里。例如“每周五生成周报”这种动作就应该是一个 workflow而不是全局规则。一个干净的 global.md 大概是这样的# 全局规则 - 默认使用中文回复除非用户明确使用英文。 - 所有回答必须是结构化输出善用列表和表格。 - 不确定的信息必须明确标注禁止编造。 - 涉及代码更改时先输出方案再动手改。而功能性的流程比如“周报生成”就拆到 workflows 里用单独文件描述。workflow 和 skill 的区别也值得说一下skill 更像是能力模块一个技能可以被多个流程调用workflow 则是串联多个 skill 的流程脚本。比如 PR 评审 workflow可能先调用 code-reviewer 技能再调用代码统计脚本最后调用 report-generator 输出报告。把这两层分开之后整个 Agent 项目的扩展性会非常舒服。新加一个流程不需要改任何 skill只要编排新的 workflow 就行。这套分层组合的逻辑本质上跟写代码是一个思路全局常量放配置文件工具函数沉淀成库业务逻辑写在业务层。文件系统模式的“终局感”其实就来自于这种和传统软件工程高度对标的结构。4. 实操中的踩坑记录与排查心得4.1 文件系统方案常见的三大坑文件系统方案看着优雅实际操作起来坑一点也不少。我挑三个最常见的也是社区里反馈最集中的提前给你打个预防针。第一个坑是文件过载。很多人一开始都觉得“文件越多越好”于是把项目背景、用户偏好、历史决策、参考文档全部拆成几百个小文件。结果 Agent 每次启动光扫描文件目录就要耗掉一堆 token而且文件之间互相引用、信息重叠反而干扰判断。文件系统不是“拆得越碎越好”而是要拆到“刚好能按需加载”的粒度。如果两个文件经常需要同时读取那它们大概率应该合并成一个。第二个坑是描述失效。有些 SKILL.md 的 description 写得模棱两可导致的直接问题就是 Agent 在需要的时候不加载不需要的时候乱加载。这个问题的排查又特别隐蔽因为你在单个 skill 文件里永远看不出问题只有在真实对话中才能发现“它怎么没调用这个技能”。描述是需要反复打磨的而且最好用一个“冗余覆盖”策略把可能触发的场景词都写进 description宁可重复不可遗漏。第三个坑是规则冲突。global.md、skill 内的规则、workflow 里的步骤三个地方如果对同一件事有不同的说法模型的输出就会飘忽不定。比如全局规则说“所有回答必须简洁”某个 workflow 又要求“输出详细到每行代码都有注释”冲突一出现Agent 的优先级判断就会混乱。这个问题的解决办法是建立规则层级全局规则永远覆盖局部规则局部规则只能细化全局规则不能推翻。4.2 排查思路与调试技巧文件系统方案出问题时最大的难点在于你看不到 Agent 在内部到底做了什么决策。所以我的第一个建议是不管用什么框架一定要想办法让 Agent 自己“说出”它读了什么文件。做法很简单在全局规则里加一条“回答任何问题前如果你读了额外的 skill 或 reference 文件请在回答末尾列出你参考的路径并说明为什么选择这些文件。”这一条看起来有点蠢但实际排查效率极高。当问题出现的时候你不需要猜直接看它列出的路径就知道是索引出了问题、还是描述触发出了问题、还是文件本身的内容有 bug。第二个技巧是“单点验证”。一个 skill 写完之后不要直接放进整个 Agent 系统里测那样出了问题根本无法定位。正确姿势是只保留这一个 skill其他规则全部关掉给它一个最典型的触发任务看它的表现是否符合预期。这个流程就像单元测试通过之后再放回系统里做集成测试。调试成本会大幅降低。第三个技巧是用好版本记录。给每个 skill 的 SKILL.md 头部加一个version字段并且在文件里记录最近几次变更的原因。这样当你发现“之前能用现在怎么不行了”的时候可以先看版本变更记录快速定位是哪一次改动引入了回归。4.3 和传统方案相比的取舍最后再说一下文件系统和传统方法的边界问题很多人容易夸文件系统而否定一切别的方案这也不健康。如果你只是在做一个一次性问答脚本prompt 只有几百 token那完全没必要引入复杂的文件系统纯提示词反而是最优解。文件系统的收益要等上下文复杂度上来了才体现。一般来说当一个项目开始出现以下信号提示词超过 3000 token或者同一段规则已经被复制到超过三个地方或者你已经开始分不清某个设定应该在哪个版本里改——这时候就该上文件系统了。另外文件系统也不等于 RAG检索增强生成。RAG 解决的是“海量外部知识的检索”问题而文件系统解决的是“Agent 内部知识结构和决策路由”的问题。两者可以协同RAG 负责从知识库召回事实文件系统负责决定“当需要事实的时候去查 RAG 的哪个索引”。很多人一开始会把文件系统当成 RAG 的替代品实际用下来会发现它们根本不是一个层级的东西。从我个人的实践看文件系统方案的维护成本前期确实比单一 prompt 模式高但这种成本是一次性的。当你把规则、技能、工作流都沉淀成独立文件之后后续每一次改动都是局部操作项目越复杂这套结构就越划算。就像写代码一样前期架构总是最痛苦的但架构质量决定了一个项目到底能走到多大。最后分享一个小技巧如果你不想从零开始搭文件系统可以先只做一个skills/目录把一个最常用的功能拆成第一个 skill边用边补。不用一上来就搞全套很多项目根本用不到全部层级。文件系统是手段不是目的别让方法论变成了新的负担。
 流量)
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
