slang-workflows

███████╗██╗      █████╗ ███╗   ██╗ ██████╗
██╔════╝██║     ██╔══██╗████╗  ██║██╔════╝
███████╗██║     ███████║██╔██╗ ██║██║  ███╗
╚════██║██║     ██╔══██║██║╚██╗██║██║   ██║
███████║███████╗██║  ██║██║ ╚████║╚██████╔╝
╚══════╝╚══════╝╚═╝  ╚═╝╚═╝  ╚═══╝ ╚═════╝
     provable, declarative multi-agent workflows for Claude Code
     a non-LLM executor runs your typed .slang files

slang-workflows

在 Claude Code 中运行可验证、由 .slang 驱动的多 Agent 工作流。

一个非大模型状态机（即 slang 执行器）运行在 MCP 服务中并协调各个 Agent；每个 Agent 都是一个 Claude Agent SDK 会话。你在类型化的 .slang 文件中声明协作方式，由执行器强制执行——包括类型化输出契约、静态分析、工具范围限定和可验证的终止条件——而不是把协调工作交给模型。顶层 Claude Code 会话只负责触发和观察，绝不做出协调决策。

Claude Code 原生的动态工作流也会将编排过程写成代码（由 Claude 编写 JS 脚本）；slang 的不同之处在于，其结构会受到强制执行并可进行静态分析，运行结果则会呈现为 Mermaid 拓扑图和跟踪图。参见基准测试中的 A/B/C 直接对比。

起源。 .slang 工作流引擎诞生于 Shofer——这款 AI Agent VS Code 扩展最初构建了这个确定性的非大模型执行器。此插件将它引入 Claude Code。

设计与原理：DESIGN.md。语言参考：slang_specs.md。隐私：PRIVACY.md。

工作原理

flowchart TB
    You(["You"])
    CC["Claude Code<br/>top-level session"]

    subgraph server["slang-workflows · MCP server"]
        direction TB
        SL["your .slang workflow<br/>agents · stakes · contracts · converge"]
        EX["slang executor<br/>deterministic · non-LLM state machine"]
        MB[("FlowState + mailbox")]
        SL -->|"parsed once"| EX
        EX <--> MB
    end

    subgraph Agents["Agent SDK sessions — the agents your .slang declares"]
        direction LR
        A1["Agent A"]
        A2["Agent B"]
        A3["Agent …"]
    end

    You <-->|"ask · approve escalations"| CC
    CC -->|"run_workflow"| EX
    EX -->|"topology + trace diagrams"| CC
    EX ==>|"dispatch stake — one session per agent, resumed"| Agents
    Agents ==>|"typed result → output-contract check + retry"| EX
    EX -.->|"escalate @Human"| CC

    classDef brain fill:#eaeaff,stroke:#5b5bd6,stroke-width:2px;
    class EX brain;

顶层 Claude Code 会话只负责触发和观察——绝不做出协调决策。非大模型执行器会读取你的 .slang 文件，将每个 stake 分派给一个 Agent SDK 会话（每个 Agent 使用一个长时运行的会话，并在各轮之间恢复），根据每个结果的输出契约进行检查（失败时重试），通过邮箱路由结果，并持续进行下一轮，直到满足工作流的 converge 条件或达到轮次上限。运行结果会呈现为 Mermaid 拓扑图和跟踪图；escalate @Human 会在普通聊天中向你发起升级。

使用场景

具体工作流（每个都是一个通过 run_workflow 运行的 .slang 文件）：

• 通过人工设计审批关卡实现功能（implement-feature.slang）——架构师会分解你的请求并编写设计文档，但其权限受限，实际上无法编写代码（write_paths: ["**/*.md"]、deny: [Bash]），且必须进行委派。你审批设计（escalate @Human）后，开发者会逐个切片实现，同时由审核者在每轮进行审核，提交前还有最后一道审核关卡。
• 将功能作为独立且经过验证的交付物发布（implement-feature-complex.slang）——线性的“设计 → 实现 → 测试 → 审核 → 文档”流水线，五位专家各自产出一项成果（实现代码、一个通过测试的 vitest 规范、使用文档），且不能越俎代庖，因此代码、测试和文档能与设计保持一致。只有每个阶段都已提交时，工作流才会收敛。
• 由两位独立调查者排查 Bug（debug.slang）——粘贴问题症状或复现步骤；两位开发者会严格以只读方式并行查找根因（避免意外修改），编排者会将双方独立的发现整合为一份修复计划，一位开发者负责实现，另一位则会反复进行同行审核，直到满意为止。
• 只能检查、绝不修改的审核者——为审核 Agent 授予 read/execute 权限，不授予写入范围；这样，“检查我的工作”运行可以执行测试和阅读代码，却无法更改内容——这是由系统强制执行的，而不只是提示要求。

功能

• 可复现的多 Agent 工作流 — 协作流程以 .slang 文件编写，并由确定性（非大模型）执行器驱动，因此每次运行的流程都相同——没有临时拼凑、无法复现的子 Agent 协调。
• 强制执行每个 Agent 的工具范围限制 — write_paths 将每个 Agent 的 Write/Edit 限制在路径 glob 范围内，deny 则移除工具（例如 Bash）；这些限制通过 SDK 的 canUseTool 强制执行，而非仅在提示词中提出要求。
• 运行前静态分析 — validate_workflow 会在解析时检测死锁、未知引用和孤立输出，此时尚未消耗任何 token。
• 有类型的输出契约 — 每个任务节点都必须返回在结构和语义上均有效的结果（output: {…} where <expr>）；无效结果会触发重试，而不会悄然传递到下游。
• 可证明的终止性 — 轮次预算（budget: rounds(N)）与每个任务节点的超时设置可确保每次运行都会结束。
• 自动生成图表 — 每次运行都会生成 Mermaid 拓扑图（get_topology）和时序图跟踪（get_trace），供实时检查或事后分析。
• 由收敛驱动的协作 — Agent 通过邮箱路由并反复迭代，直到满足声明的收敛条件或达到预算上限；会话恢复功能可让 Agent 在多轮中保留上下文。

这与 Claude Code 的原生 动态工作流 有何不同

Claude Code 已内置 动态工作流 功能：当任务需要编排时，Claude 会（通过 Agent SDK / Workflow 工具）编写 JavaScript 脚本，以启动并协调子 Agent。这比临时、一次性的子 Agent 调用确实进了一大步——脚本将编排流程编写下来，编写完成后便会确定性地运行，并以近乎零的额外大模型成本进行协调。slang 的目标与之相同；我们的基准测试显示，两种方法都能以近乎零的协调大模型成本实现真正可用的成果。区别在于编排流程的本质，以及它能提供哪些保证**：**

	原生动态工作流	slang-workflows
编排流程是……	由大模型编写的 JavaScript 脚本	由固定的非大模型执行器运行的有类型声明式 .slang 文件
协调逻辑由谁编写	Claude 为每个任务用通用语言编写	由你（或大模型一次性）用运行时可理解的领域专用语言编写
阶段间的输出契约	取决于脚本具体会检查什么	由运行时强制执行——结构 + 语义（output: {…} where <expr>）；无效结果 → 重试
每个 Agent 的工具范围限制	由脚本决定	通过 SDK 的 canUseTool，对 write_paths / deny 强制执行
结构的正确性	不会检查 JS	运行前静态分析——死锁 / 未知引用 / 孤立输出
终止性	由脚本决定	可证明——budget: rounds(N) + 每个任务节点的超时设置
可观测性	需要自行添加监测	自动生成 Mermaid 拓扑图 + 时序图跟踪
可复用的产物	模型每次重新生成的脚本	有版本管理的 .slang 文件 + 固定解释器

简而言之：原生动态工作流将编排流程放在由大模型编写、需要你信任的代码中；slang 则将其放在由运行时验证并强制执行的有类型声明中——运行前可分析，运行时有范围限制并检查契约，运行后会生成图表。当你需要保证和可审计性（安全范围受限的 Agent、可证明的终止性、符合契约的交接、可复用且有版本管理的工作流）时，选择 slang；如果你只想要“这次模型协调了一些子 Agent”，则不必如此。两者都远胜于无结构的子 Agent——slang 以预先编写少量声明为代价，换取强制执行和可复现性。

当前可用功能

• 发现 / 验证 / 运行 .slang 工作流——可直接编写，也可由大模型内联生成（见下方 MCP 工具）。
• 确定性执行器：stake → 输出契约验证 + 重试 → 邮箱路由 → 收敛；多 Agent流程；会话恢复（一个 Agent = 跨 stake 的一个会话）； escalate @Human。
• 输出契约：结构性（output: {...}，通过 SDK outputFormat）+ 语义性（where <expr>）。
• 强制工具范围限制：write_paths（Write/Edit 仅限指定路径 glob，通过 PreToolUse 命令钩子实现）和 deny（移除原生工具或 MCP 工具）。
• 静态分析（validate_workflow）：运行前检测死锁 / 未知引用 / 孤立输出。
• 可证明终止：budget: rounds(N) + 每个 stake 的超时设置——运行总会结束。
• 图表：get_topology（Mermaid 流程图）+ get_trace（Mermaid 时序图 + 事件日志）。
• 同步或后台运行（background:true），并实时轮询状态 / 拓扑 / 跟踪记录。

完整矩阵请参见 DESIGN.md § Implementation Status。

要求

• Node.js 22+ 和 pnpm。
• 已安装并完成身份验证的 Claude Code（PATH 中的 claude CLI）——Agent SDK 会启动它来运行 Agent。

安装

cd server
pnpm install

Agent SDK 说明。 @anthropic-ai/claude-agent-sdk 被声明为可选依赖， 因为一些内部注册表不会镜像它。如果 pnpm install 跳过了它，请从 公共注册表添加：

pnpm add @anthropic-ai/claude-agent-sdk --registry=https://registry.npmjs.org/

没有它，服务仍可解析 / 验证工作流；但运行 Agent 需要它。

验证安装：

pnpm typecheck   # type-checks the whole server
pnpm test        # runs the unit suite (mock-based, no model calls)

使用

运行时，服务会在你的项目的 .claude/workflows/（以及 ~/.claude/workflows/）中发现 .slang 文件——这是用户存放自定义工作流的位置。插件在 server/test/fixtures/ 中附带了示例工作流；复制进去即可试用：

mkdir -p .claude/workflows
cp /PATH/TO/slang-orchestrator/server/test/fixtures/*.slang .claude/workflows/

最快捷方式：向 Claude Code 注册 MCP 服务

在你希望运行其 .claude/workflows/ 的项目中执行：

claude mcp add slang-workflows -- npx tsx /ABSOLUTE/PATH/TO/slang-orchestrator/server/src/main.ts

然后在 Claude Code 中让它使用这些工具——例如 “列出 slang 工作流”、“运行 where-clause 工作流”。

作为 Claude Code 插件

此目录是一个独立插件：.claude-plugin/plugin.json

• .mcp.json（通过 npx tsx ${CLAUDE_PLUGIN_ROOT}/server/src/main.ts 启动的 stdio 服务）。 通过 Claude Code 的插件机制安装，即可自动提供这些工具。

斜杠命令

加载插件后，可直接使用以下命令驱动它（Claude Code 会按插件命名空间组织命令，因此你的 / 菜单会显示 slang-workflows:…）：

命令	功能
/slang-workflows:slang-run <name or path> [k=v …]	运行工作流直至完成——同步执行，因此会提示你响应 @Human 门控。
/slang-workflows:slang-list	列出它能找到的 .slang 工作流。
/slang-workflows:slang-new <description>	根据描述生成工作流、验证并运行。
/slang-workflows:slang-trace [workflow_id]	渲染一次运行的拓扑图 + 时序图跟踪记录。

这些命令只是对下方 MCP 工具的简单封装——你也可以直接用自然语言向 Claude 提出请求（例如 “运行 where-clause 工作流”）。

MCP 工具

工具	用途
list_workflows	查找 .slang 文件（名称、标题、参数、Agent 数量）。
get_slang_grammar	简明语法速查表和示例，便于大模型生成可内联运行的工作流。
validate_workflow	解析并进行静态分析（死锁、未知引用、孤立输出），但不运行。接受 name/path 或内联 source。
run_workflow	按 name/path 或内联 source 运行工作流（先检查并拒绝解析或静态分析错误）。默认同步运行；background:true 会立即返回 workflow_id，用于轮询实时状态。
get_workflow_state	按 workflow_id 获取序列化的 FlowState（各 Agent 的状态、轮次、预算）；在 background 运行期间可获取实时状态。
get_topology	按 workflow_id 获取工作流拓扑的 Mermaid 流程图（按状态着色的快照）。
get_trace	按 workflow_id 获取 Mermaid 时序图形式的执行跟踪记录和原始事件日志（谁进行了质押／路由给谁、提交、升级、终止）。

生成并运行的循环： get_slang_grammar → 编写 slang → validate_workflow{source} → run_workflow{source, background:true} → 运行期间轮询 get_topology / get_trace。工作流由大模型编写，但以确定性方式执行（强制执行契约，并始终终止）。@Human 升级仅适用于同步运行（交互式信息收集需要工具调用保持打开状态）。

开发

pnpm dev        # run the server over stdio (logs to stderr)
pnpm typecheck  # tsc --noEmit
pnpm test       # node:test suite

执行器只依赖 Dispatcher 接口；FakeDispatcher 让整个 VM 无需 Agent SDK 或任何模型调用即可进行测试（参见 server/test/）。

目录结构

.claude-plugin/plugin.json   plugin manifest
.mcp.json                    stdio MCP server declaration
server/
  src/
    main.ts                  MCP server + tool surface
    constants.ts             tunable defaults in one place (round cap, retry budget, stake timeout, loop guard)
    executor.ts              deterministic round loop + output contracts
    dispatcher.ts            Dispatcher interface + FakeDispatcher (the agent-runtime seam)
    agent-sdk-dispatcher.ts  production backend (Claude Agent SDK)
    tool-group-map.ts        slang tool-groups → Claude Code tools
    workflows.ts             .slang discovery + validation
    slang/                   vendored, framework-agnostic slang VM (lexer/parser/interpreter/…)
  test/                      node:test unit + conformance suite
    fixtures/                showcase .slang workflows (also the conformance fixtures)

许可证

Apache-2.0。参见 LICENSE。