当前 AI 代理生态正从单一、固化的工具范式，向模块化、可编排的 “技能” 范式演进。开发者不再满足于让代理执行预定义的单一步骤，而是期望它能像经验丰富的工程师一样，在复杂的软件开发流程中，动态调用测试驱动、系统调试、子代理协作等不同 “技能”，并保持工作流的连贯性与状态持久性。这一转变的核心工程挑战，在于构建一个鲁棒的代理技能编排框架。本文将以 Obra 的 Superpowers 项目为切入点，聚焦三个关键的工程化子问题：模块化技能加载、运行时依赖解析与跨会话状态管理，并提供可落地的参数与监控清单。
技能目录：模块化加载的基石
模块化是任何框架得以扩展的前提。一个理想的技能编排框架，不应将技能硬编码在代理的核心逻辑中，而应通过外部目录进行管理，支持动态发现与加载。Superpowers 提供了一个清晰的范例。其技能库被明确分类为测试、调试、协作与元技能等，例如 test-driven-development、systematic-debugging、brainstorming、subagent-driven-development。每种技能本质上是一组结构化的指令、检查点与执行逻辑的集合。
实现模块化加载的关键，是定义统一的技能接口描述。一个技能至少应包含：技能标识符（唯一 ID）、触发条件（何时激活）、输入 / 输出规约、前置 / 后置依赖声明以及技能实现体。框架在初始化时，扫描预设的技能目录（如文件系统特定路径、远程仓库或插件市场），将这些描述加载到内存中的一个注册表中。当代理接收到用户请求或进入特定任务阶段时，框架便根据当前上下文（如对话历史、项目状态、用户意图）与技能的触发条件进行匹配，动态实例化并注入相应的技能模块。
这种设计带来了显著的灵活性。新技能的开发与集成变得标准化，开发者只需遵循接口规范编写技能实现，并将其放入目录即可，无需修改框架核心代码。同时，它也支持环境特定的技能包，正如 Superpowers 为 Claude Code、Codex 和 OpenCode 提供不同的安装与集成方式，底层是同一套技能目录在不同运行时环境下的适配加载。
运行时依赖解析：确保技能有序执行
当多个技能可能被顺序或并行触发时，技能间的依赖关系管理就成为框架必须解决的复杂性问题。例如，writing-plans（编写计划）技能很可能需要在 brainstorming（头脑风暴）技能产出设计文档之后执行；而 subagent-driven-development（子代理驱动开发）技能又依赖于一个已获批准的详细计划。如果框架不能正确处理这些依赖，可能导致技能执行顺序错乱、上下文信息缺失或状态不一致。
Superpowers 的工作流暗示了一种隐式的、基于阶段的依赖管理。其基本流程从 brainstorming 开始，经过 using-git-worktrees、writing-plans，再到 subagent-driven-development 或 executing-plans，最后以 finishing-a-development-branch 结束。这形成了一个有向无环图（DAG），每个技能节点对应开发流程中的一个阶段。框架的 “强制工作流” 机制，本质上是在运行时根据当前所处阶段，解析并锁定下一个必须执行的技能，禁止跳过。
对于更通用的框架，我们需要更显式的依赖解析策略。可以在技能接口描述中增加 depends_on 字段，声明其所依赖的其他技能 ID。框架在加载技能目录后，会构建一个技能依赖图。当触发某个技能时，调度器会进行拓扑排序，确保所有前置依赖技能都已成功执行（或确认其输出状态可用）。对于可能存在循环依赖的技能组合，框架应在加载期进行检测并报错。
此外，依赖不仅限于技能执行顺序，还包括数据依赖。技能 A 可能产出某个数据结构（如 “设计文档”），技能 B 需要消费它。框架需要提供一种轻量级的、类型化的上下文总线或共享状态存储，让技能能以声明的方式读写共享数据，并由框架保证在依赖技能执行时，所需数据已准备就绪。
跨会话状态管理：持久化智能体 “记忆”
AI 代理的对话通常是短暂的。一个会话结束后，所有中间状态（如已确认的设计、进行到一半的计划、子代理的执行结果）都会丢失。这对于需要长时间、多步骤协作的软件开发流程是致命的。因此，技能编排框架必须具备跨会话的状态持久化能力，让代理在下次被唤醒时，能够 “记住” 之前的工作进度与上下文。
Superpowers 通过保存设计文档、计划文件以及利用 Git 工作树来隐式地实现状态持久化。这些产物保存在项目文件系统中，成为了连接不同会话的 “物化状态”。当新会话开始时，代理可以读取这些文件来恢复上下文。这是一种实用且有效的方法，将状态管理委托给了版本控制系统和文件系统。
对于一个旨在更通用的框架，我们需要设计更系统化的状态管理模块。核心是将技能的 “执行上下文” 与 “产出物” 序列化并持久化。可以定义一个 SessionState 对象，它包含：会话 ID、当前活跃的技能链、技能执行历史（包含输入、输出、状态成功 / 失败）、共享数据快照以及用户定义的元数据。框架在技能执行的关键节点（如一个技能完成、用户中断、会话结束时）自动将 SessionState 序列化（如使用 JSON）并存储到后端（如数据库、键值存储或文件系统）。
当用户重新发起对话或继续任务时，框架可以通过会话 ID 或项目上下文检索到最新的 SessionState，反序列化后重建执行环境。代理便能直接从上次中断的技能链继续，或者基于已有的产出物进行决策。这实现了真正的 “断点续传”。监控系统可以跟踪状态存储的成功率、序列化大小与恢复耗时，确保该机制的可靠性。
可落地参数与监控清单
基于以上分析，构建此类框架时，以下参数与监控点至关重要：
技能加载参数：
SKILL_SCAN_DIRECTORIES: 技能描述文件的搜索路径列表。SKILL_CACHE_TTL_SECONDS: 技能元数据缓存时间，平衡发现延迟与动态更新需求。MAX_CONCURRENT_SKILL_LOADERS: 并行加载技能文件的线程 / 进程数。
依赖解析参数：
DEPENCY_VALIDATION_STRICT_MODE: 是否在加载期严格验证依赖图的无环性（建议开启）。MAX_DEPENDENCY_DEPTH: 允许的技能依赖链最大深度，防止无限递归或过于复杂的依赖。TIMEOUT_PER_DEPENDENCY_RESOLUTION_MS: 单个依赖解析步骤的超时时间。
状态管理参数：
STATE_SERIALIZATION_FORMAT: 序列化格式，如json、msgpack。STATE_PERSISTENCE_BACKEND: 存储后端，如redis、postgres、file。STATE_AUTO_SAVE_INTERVAL_SECONDS: 自动保存状态的时间间隔。MAX_STATE_SIZE_BYTES: 单个状态对象的尺寸上限，防止存储爆炸。
核心监控指标：
- 技能加载：技能目录扫描耗时、技能加载失败率、缓存命中率。
- 依赖解析：依赖图构建耗时、循环依赖检测告警、运行时依赖缺失错误数。
- 状态管理：状态序列化 / 反序列化耗时、状态存储成功率、状态恢复成功率、平均状态大小。
- 执行流：技能触发准确率、技能执行平均耗时、因状态丢失导致的流程重启次数。
结语
将 AI 代理从执行单一指令的工具，进化为能够协调多种技能、管理复杂状态的工作伙伴，是提升其实际生产力的关键。通过借鉴 Superpowers 等项目的思想，构建一个专注于模块化技能加载、显式依赖解析与健壮状态管理的编排框架，能够为开发更强大、更可靠的 AI 驱动工程流程奠定坚实的基础。框架的成功不仅在于其设计精巧，更在于对上述工程细节的持续打磨与监控。当技能能够像乐高积木一样被自由组合，且组合后的机器能够记住自己的工作并从中断处继续时，AI 代理才真正拥有了应对现实世界复杂性的 “超能力”。
资料来源
- Obra. Superpowers: An agentic skills framework & software development methodology that works. GitHub Repository. https://github.com/obra/superpowers
- 项目阐述了基于可组合技能的开发工作流、技能自动触发机制与核心技能库，为代理技能编排提供了具体的设计参考与实现范例。