skelm：面向生产环境的 TypeScript 智能体工作流框架

skelm 是一个开源 TypeScript 框架，专注于构建安全、可维护、长运行的智能体工作流。它采用默认拒绝的安全模型，支持确定性代码、LLM 推理和智能体循环的混合编排，为生产环境中的 AI 应用提供可靠的基础设施。

背景：AI 应用开发的痛点\n\n随着大语言模型（LLM）能力的不断提升，越来越多的开发者开始构建基于 AI 的应用系统。从简单的聊天机器人到复杂的自动化工作流，AI 正在重塑软件开发的范式。然而，在实际落地过程中，开发者们普遍面临着几个核心挑战：\n\n首先是安全性问题。当 AI 智能体被赋予执行代码、访问文件系统或调用外部 API 的能力时，如何确保其行为在可控范围内？传统的权限模型往往是在问题发生后才进行审计，而非在事前进行预防。\n\n其次是可维护性。许多 AI 框架采用了复杂的领域特定语言（DSL）或可视化编辑器，这在项目初期看似降低了门槛，但随着业务逻辑的复杂化，这些抽象层反而成为了理解和修改代码的障碍。\n\n第三是健壮性。AI 工作流往往需要长时间运行，可能在执行过程中遇到网络中断、API 限流、模型幻觉等各种异常情况。如何确保工作流能够优雅地处理这些异常，并在恢复后继续执行，是生产环境必须解决的问题。\n\n## skelm 的设计理念\n\nskelm 是一个开源的 TypeScript 框架，其设计目标直指上述痛点。项目作者 Scott Glover 在 README 中明确提出了三个核心设计原则，并按优先级排序：\n\n### 1. 安全性：默认拒绝（Default-Deny）\n\nskelm 将安全性置于首位。框架采用"默认拒绝"的权限模型，这意味着智能体在默认情况下没有任何权限，必须显式声明其需要的每一项能力。\n\n具体而言，每个智能体步骤都需要声明：\n- 允许使用的工具（allowedTools）\n- 允许连接的 MCP 服务器（allowedMcpServers）\n- 允许访问的技能包（allowedSkills）\n- 允许的网络出口（networkEgress）\n- 允许读取和写入的文件系统路径（fsRead/fsWrite）\n\n这种设计使得权限审查变得简单直观。在代码审查时，开发者可以一目了然地看到每个智能体能够做什么，而不能做什么。更重要的是，如果后端无法强制执行声明的权限，工作流会在步骤启动时失败，而不是绕过安全检查继续执行。\n\n### 2. 可维护性：纯 TypeScript，无 DSL\n\nskelm 拒绝引入任何领域特定语言或可视化编辑器。工作流就是普通的 TypeScript 模块，这意味着开发者可以使用熟悉的工具链进行开发、测试和版本控制。\n\n框架的核心 API 非常简洁，主要包括三种步骤类型：\n- code()：用于确定性逻辑\n- llm()：用于单次 LLM 推理\n- agent()：用于完整的智能体循环\n\n这三种步骤类型相互独立，没有层层包装的关系。开发者可以根据需求自由组合，构建出复杂的工作流。\n\n### 3. 健壮性：类型安全与持久化状态\n\nskelm 提供了端到端的类型安全。从输入到输出，每个步骤的数据流都有明确的类型定义。这不仅减少了运行时错误，也使得 IDE 能够提供更好的自动补全和重构支持。\n\n框架还内置了持久化状态管理机制。通过 ctx.state，开发者可以在多次运行之间保持键值对状态。此外，skelm 提供了只追加的决策日志（decision journals），记录智能体在每一步的决策和推理过程，为审计和调试提供了宝贵的信息。\n\n## 核心特性详解\n\n### 工作空间隔离\n\n每个智能体步骤都会获得独立的文件系统工作空间。这些工作空间可以是持久化的（跨运行保留），也可以是临时的（每次运行后清理）。框架通过锁机制防止并发运行时的数据竞争，确保数据一致性。\n\n### 原生控制流\n\nskelm 内置了丰富的控制流原语，包括：\n- parallel：并行执行多个步骤\n- forEach：遍历集合并对每个元素执行步骤\n- branch：条件分支\n- loop：循环执行\n- wait：等待特定条件或时间\n- pipelineStep：嵌套子工作流\n\n这些控制流都是核心功能，而非通过插件实现，确保了行为的一致性和性能的可预测性。\n\n### 调度器原生支持\n\n在 skelm 中，每一次运行都是一个"调度"。无论是立即执行、单次定时执行，还是周期性执行（通过 cron、interval、webhook、poll 或队列触发），都使用统一的调度接口。这种设计使得开发者可以用相同的可观测性工具来监控临时任务和长期运行的服务。\n\n### 审计日志\n\nskelm 维护了一个单写、哈希链式的审计日志，与运行历史分离。这个日志是合规审查的关键证据，记录了系统中发生的所有重要事件，且不可篡改。\n\n### 本地优先与自托管\n\n框架默认使用 SQLite 作为存储后端，无需外部依赖即可运行。对于生产环境，skelm 提供了 PostgreSQL 和 Vault 的驱动支持。这种设计既满足了开发阶段的便利性，又提供了生产环境的扩展性。\n\n## 代码示例：问题分类工作流\n\n以下是一个典型的 skelm 工作流示例，展示了如何构建一个 GitHub Issue 自动分类系统：\n\ntypescript\nimport { pipeline, code, agent } from 'skelm'\nimport { z } from 'zod'\n\nexport default pipeline({\n id: 'triage-issue',\n description: 'Classify an inbound GitHub issue and label it.',\n input: z.object({ repo: z.string(), issueNumber: z.number() }),\n output: z.object({ label: z.string(), reasoning: z.string() }),\n steps: [\n code({\n id: 'fetch',\n run: async (ctx) => {\n const res = await fetch(\n `https://api.github.com/repos/${ctx.input.repo}/issues/${ctx.input.issueNumber}`\n )\n return await res.json()\n },\n }),\n agent({\n id: 'classify',\n backend: 'anthropic',\n agentDef: './agents/triager',\n skills: ['github-readonly'],\n mcp: [{ id: 'gh', transport: 'stdio', command: 'mcp-github' }],\n permissions: {\n allowedTools: ['gh.add_label'],\n allowedMcpServers: ['gh'],\n allowedSkills: ['github-readonly'],\n networkEgress: { allowHosts: ['api.github.com'] },\n fsRead: ['./'],\n fsWrite: [],\n },\n prompt: (ctx) => `Triage this issue:\\n${JSON.stringify(ctx.steps.fetch)}`,\n output: z.object({\n label: z.enum(['bug', 'feature', 'duplicate']),\n reasoning: z.string()\n }),\n maxTurns: 8,\n }),\n ],\n})\n\n\n这个示例清晰地展示了 skelm 的几个关键特性：\n\n1. 类型安全：输入、输出和中间数据都有明确的 Zod 类型定义\n2. 权限声明：智能体步骤明确声明了允许的操作范围\n3. 混合编排：确定性代码（获取 Issue）与 AI 推理（分类）无缝结合\n4. 模块化设计：智能体的角色定义（agentDef）和技能包（skills）都是可复用的模块\n\n## 部署与运行模式\n\nskelm 支持多种运行模式，适应不同的使用场景：\n\n### 单次运行\nbash\nskelm run workflows/triage-issue.workflow.ts --input '{"repo":"acme/x","issueNumber":42}'\n\n\n### Webhook 触发\nbash\nskelm schedule add workflows/triage-issue.workflow.ts --webhook /webhooks/issue-events\n\n\n### 长期运行的网关服务\nbash\nskelm gateway start\n\n\n网关服务可以托管工作流并通过 HTTP + SSE 提供访问，同时驱动调度器执行定时任务。它还支持作为 systemd 用户服务安装，方便在 Linux 服务器上长期运行。\n\n## 项目路线图\n\nskelm 目前处于早期开发阶段，API 在 v1 之前可能会发生变化。项目路线图分为四个里程碑：\n\nM1 - 核心运行时与 CLI：工作流编写、三种步骤类型、三种内置后端、完整的权限强制执行、SQLite 运行存储。\n\nM2 - 控制流与工作空间：并行/遍历/分支/循环/等待、智能体工作空间、持久化 KV 状态、智能体定义 Markdown 加载器、内省命令。\n\nM3 - 网关、审计、调度器与调试：长期运行的网关服务、HTTP + SSE、审计日志、密钥驱动、支持多种触发器的调度器、systemd 用户单元安装器、调试断点。\n\nM4 - 集成、智能体路由与 PostgreSQL：官方集成包、OAuth 设置、OpenAI 兼容的 HTTP 接口、成本/质量路由包装器、PostgreSQL 运行存储、Vault 密钥管理、分布式去重。\n\n## 技术选型与哲学\n\nskelm 选择了 MIT 许可证，这是比 Apache 2.0 更宽松的许可。项目明确排除了 GPL 风格的 copyleft 许可证，体现了作者希望最大化框架可用性的意图。\n\n在技术栈选择上，skelm 坚持使用 TypeScript 和 Node.js 生态，拒绝引入复杂的 DSL 或配置格式。这种"代码即配置"的哲学与现代 DevOps 工具（如 Pulumi、Terraform CDK）的趋势一致，即利用通用编程语言的表达能力来替代受限的配置语言。\n\n## 适用场景与价值主张\n\nskelm 特别适合以下场景：\n\n1. 企业级 AI 应用：需要严格的安全控制和审计能力\n2. 长期运行的自动化流程：如夜间报告生成、持续监控和告警\n3. 多步骤复杂工作流：涉及确定性处理、LLM 推理和外部 API 调用的混合场景\n4. 需要人工审查的 AI 系统：通过决策日志和权限控制实现人机协作\n\n相比其他 AI 框架，skelm 的价值在于它将安全性、可维护性和健壮性作为一等公民，而非事后补丁。这种设计哲学使其特别适合对可靠性要求较高的生产环境。\n\n## 结语\n\nskelm 代表了 AI 应用开发框架的一个重要进化方向：从追求功能丰富转向追求生产就绪。在 AI 技术快速迭代的今天，能够安全、可靠、可维护地运行 AI 工作流，比单纯追求模型能力或功能数量更为重要。\n\n对于正在构建 AI 驱动应用的团队，skelm 提供了一个值得认真考虑的选项。它的默认拒绝安全模型、纯 TypeScript 设计和健壮的运行时，为构建可持续演进的 AI 系统奠定了坚实的基础。

背景：AI 应用开发的痛点\n\n随着大语言模型（LLM）能力的不断提升，越来越多的开发者开始构建基于 AI 的应用系统。从简单的聊天机器人到复杂的自动化工作流，AI 正在重塑软件开发的范式。然而，在实际落地过程中，开发者们普遍面临着几个核心挑战：\n\n首先是安全性问题。当 AI 智能体被赋予执行代码、访问文件系统或调用外部 API 的能力时，如何确保其行为在可控范围内？传统的权限模型往往是在问题发生后才进行审计，而非在事前进行预防。\n\n其次是可维护性。许多 AI 框架采用了复杂的领域特定语言（DSL）或可视化编辑器，这在项目初期看似降低了门槛，但随着业务逻辑的复杂化，这些抽象层反而成为了理解和修改代码的障碍。\n\n第三是健壮性。AI 工作流往往需要长时间运行，可能在执行过程中遇到网络中断、API 限流、模型幻觉等各种异常情况。如何确保工作流能够优雅地处理这些异常，并在恢复后继续执行，是生产环境必须解决的问题。\n\nskelm 的设计理念\n\nskelm 是一个开源的 TypeScript 框架，其设计目标直指上述痛点。项目作者 Scott Glover 在 README 中明确提出了三个核心设计原则，并按优先级排序：\n\n1. 安全性：默认拒绝（Default-Deny）\n\nskelm 将安全性置于首位。框架采用"默认拒绝"的权限模型，这意味着智能体在默认情况下没有任何权限，必须显式声明其需要的每一项能力。\n\n具体而言，每个智能体步骤都需要声明：\n- 允许使用的工具（allowedTools）\n- 允许连接的 MCP 服务器（allowedMcpServers）\n- 允许访问的技能包（allowedSkills）\n- 允许的网络出口（networkEgress）\n- 允许读取和写入的文件系统路径（fsRead/fsWrite）\n\n这种设计使得权限审查变得简单直观。在代码审查时，开发者可以一目了然地看到每个智能体能够做什么，而不能做什么。更重要的是，如果后端无法强制执行声明的权限，工作流会在步骤启动时失败，而不是绕过安全检查继续执行。\n\n2. 可维护性：纯 TypeScript，无 DSL\n\nskelm 拒绝引入任何领域特定语言或可视化编辑器。工作流就是普通的 TypeScript 模块，这意味着开发者可以使用熟悉的工具链进行开发、测试和版本控制。\n\n框架的核心 API 非常简洁，主要包括三种步骤类型：\n- code()：用于确定性逻辑\n- llm()：用于单次 LLM 推理\n- agent()：用于完整的智能体循环\n\n这三种步骤类型相互独立，没有层层包装的关系。开发者可以根据需求自由组合，构建出复杂的工作流。\n\n3. 健壮性：类型安全与持久化状态\n\nskelm 提供了端到端的类型安全。从输入到输出，每个步骤的数据流都有明确的类型定义。这不仅减少了运行时错误，也使得 IDE 能够提供更好的自动补全和重构支持。\n\n框架还内置了持久化状态管理机制。通过 ctx.state，开发者可以在多次运行之间保持键值对状态。此外，skelm 提供了只追加的决策日志（decision journals），记录智能体在每一步的决策和推理过程，为审计和调试提供了宝贵的信息。\n\n核心特性详解\n\n工作空间隔离\n\n每个智能体步骤都会获得独立的文件系统工作空间。这些工作空间可以是持久化的（跨运行保留），也可以是临时的（每次运行后清理）。框架通过锁机制防止并发运行时的数据竞争，确保数据一致性。\n\n原生控制流\n\nskelm 内置了丰富的控制流原语，包括：\n- parallel：并行执行多个步骤\n- forEach：遍历集合并对每个元素执行步骤\n- branch：条件分支\n- loop：循环执行\n- wait：等待特定条件或时间\n- pipelineStep：嵌套子工作流\n\n这些控制流都是核心功能，而非通过插件实现，确保了行为的一致性和性能的可预测性。\n\n调度器原生支持\n\n在 skelm 中，每一次运行都是一个"调度"。无论是立即执行、单次定时执行，还是周期性执行（通过 cron、interval、webhook、poll 或队列触发），都使用统一的调度接口。这种设计使得开发者可以用相同的可观测性工具来监控临时任务和长期运行的服务。\n\n审计日志\n\nskelm 维护了一个单写、哈希链式的审计日志，与运行历史分离。这个日志是合规审查的关键证据，记录了系统中发生的所有重要事件，且不可篡改。\n\n本地优先与自托管\n\n框架默认使用 SQLite 作为存储后端，无需外部依赖即可运行。对于生产环境，skelm 提供了 PostgreSQL 和 Vault 的驱动支持。这种设计既满足了开发阶段的便利性，又提供了生产环境的扩展性。\n\n代码示例：问题分类工作流\n\n以下是一个典型的 skelm 工作流示例，展示了如何构建一个 GitHub Issue 自动分类系统：\n\ntypescript\nimport { pipeline, code, agent } from 'skelm'\nimport { z } from 'zod'\n\nexport default pipeline({\n id: 'triage-issue',\n description: 'Classify an inbound GitHub issue and label it.',\n input: z.object({ repo: z.string(), issueNumber: z.number() }),\n output: z.object({ label: z.string(), reasoning: z.string() }),\n steps: [\n code({\n id: 'fetch',\n run: async (ctx) => {\n const res = await fetch(\n `https://api.github.com/repos/${ctx.input.repo}/issues/${ctx.input.issueNumber}`\n )\n return await res.json()\n },\n }),\n agent({\n id: 'classify',\n backend: 'anthropic',\n agentDef: './agents/triager',\n skills: ['github-readonly'],\n mcp: [{ id: 'gh', transport: 'stdio', command: 'mcp-github' }],\n permissions: {\n allowedTools: ['gh.add_label'],\n allowedMcpServers: ['gh'],\n allowedSkills: ['github-readonly'],\n networkEgress: { allowHosts: ['api.github.com'] },\n fsRead: ['./'],\n fsWrite: [],\n },\n prompt: (ctx) => `Triage this issue:\\n${JSON.stringify(ctx.steps.fetch)}`,\n output: z.object({\n label: z.enum(['bug', 'feature', 'duplicate']),\n reasoning: z.string()\n }),\n maxTurns: 8,\n }),\n ],\n})\n\n\n这个示例清晰地展示了 skelm 的几个关键特性：\n\n1. 类型安全：输入、输出和中间数据都有明确的 Zod 类型定义\n2. 权限声明：智能体步骤明确声明了允许的操作范围\n3. 混合编排：确定性代码（获取 Issue）与 AI 推理（分类）无缝结合\n4. 模块化设计：智能体的角色定义（agentDef）和技能包（skills）都是可复用的模块\n\n部署与运行模式\n\nskelm 支持多种运行模式，适应不同的使用场景：\n\n单次运行\nbash\nskelm run workflows/triage-issue.workflow.ts --input '{"repo":"acme/x","issueNumber":42}'\n\n\nWebhook 触发\nbash\nskelm schedule add workflows/triage-issue.workflow.ts --webhook /webhooks/issue-events\n\n\n长期运行的网关服务\nbash\nskelm gateway start\n\n\n网关服务可以托管工作流并通过 HTTP + SSE 提供访问，同时驱动调度器执行定时任务。它还支持作为 systemd 用户服务安装，方便在 Linux 服务器上长期运行。\n\n项目路线图\n\nskelm 目前处于早期开发阶段，API 在 v1 之前可能会发生变化。项目路线图分为四个里程碑：\n\nM1 - 核心运行时与 CLI：工作流编写、三种步骤类型、三种内置后端、完整的权限强制执行、SQLite 运行存储。\n\nM2 - 控制流与工作空间：并行/遍历/分支/循环/等待、智能体工作空间、持久化 KV 状态、智能体定义 Markdown 加载器、内省命令。\n\nM3 - 网关、审计、调度器与调试：长期运行的网关服务、HTTP + SSE、审计日志、密钥驱动、支持多种触发器的调度器、systemd 用户单元安装器、调试断点。\n\nM4 - 集成、智能体路由与 PostgreSQL：官方集成包、OAuth 设置、OpenAI 兼容的 HTTP 接口、成本/质量路由包装器、PostgreSQL 运行存储、Vault 密钥管理、分布式去重。\n\n技术选型与哲学\n\nskelm 选择了 MIT 许可证，这是比 Apache 2.0 更宽松的许可。项目明确排除了 GPL 风格的 copyleft 许可证，体现了作者希望最大化框架可用性的意图。\n\n在技术栈选择上，skelm 坚持使用 TypeScript 和 Node.js 生态，拒绝引入复杂的 DSL 或配置格式。这种"代码即配置"的哲学与现代 DevOps 工具（如 Pulumi、Terraform CDK）的趋势一致，即利用通用编程语言的表达能力来替代受限的配置语言。\n\n适用场景与价值主张\n\nskelm 特别适合以下场景：\n\n1. 企业级 AI 应用：需要严格的安全控制和审计能力\n2. 长期运行的自动化流程：如夜间报告生成、持续监控和告警\n3. 多步骤复杂工作流：涉及确定性处理、LLM 推理和外部 API 调用的混合场景\n4. 需要人工审查的 AI 系统：通过决策日志和权限控制实现人机协作\n\n相比其他 AI 框架，skelm 的价值在于它将安全性、可维护性和健壮性作为一等公民，而非事后补丁。这种设计哲学使其特别适合对可靠性要求较高的生产环境。\n\n结语\n\nskelm 代表了 AI 应用开发框架的一个重要进化方向：从追求功能丰富转向追求生产就绪。在 AI 技术快速迭代的今天，能够安全、可靠、可维护地运行 AI 工作流，比单纯追求模型能力或功能数量更为重要。\n\n对于正在构建 AI 驱动应用的团队，skelm 提供了一个值得认真考虑的选项。它的默认拒绝安全模型、纯 TypeScript 设计和健壮的运行时，为构建可持续演进的 AI 系统奠定了坚实的基础。