内容
以下是翻译后的文档：
███████╗██╗ █████╗ ███╗ ██╗ ██████╗
██╔════╝██║ ██╔══██╗████╗ ██║██╔════╝
███████╗██║ ███████║██╔██╗ ██║██║ ███╗
╚════██║██║ ██╔══██║██║╚██╗██║██║ ██║
███████║███████╗██║ ██║██║ ╚████║╚██████╔╝
╚══════╝╚══════╝╚═╝ ╚═╝╚═╝ ╚═══╝ ╚═════╝
可证明的、声明式的多智能体工作流，为 Claude Code
非大语言模型执行器运行您的类型 `.slang` 文件
# 工具列表
在 Claude Code 中运行 **可证明的**、`.slang` 驱动的 **多智能体工作流**。
非大语言模型状态机（*slang 执行器*）在 MCP 服务器中运行，并协调智能体；
每个智能体都是一个 Claude **Agent SDK** 会话。你在类型 `.slang` 文件中声明协作，执行器 *强制执行* 它 — 类型输出契约、静态分析、工具范围和
可证明的终止 — 而不是将协调留给模型。顶级 Claude Code 会话仅 *触发* 和 *观察*；它从不做出协调决策。
Claude Code 的原生 **动态工作流** 也编码了编排（Claude 编写 JavaScript 脚本）；
slang 的区别在于结构是 **强制执行和静态可分析的**，并且运行呈现为 **Mermaid 拓扑图 + 跟踪图**。参见 [基准测试](benchmark/) 以进行 A/B/C 对比。
> **起源。** `.slang` 工作流引擎诞生于 [**Shofer**](https://shofer.dev) —
> AI 智能体 VS Code 扩展 — 其中确定性、非大语言模型执行器首次被构建。该插件将其带到 Claude Code。
> 设计和原理：[`DESIGN.md`](DESIGN.md)。语言参考：[`slang_specs.md`](slang_specs.md)。隐私：[`PRIVACY.md`](PRIVACY.md)。
## 工作原理
```mermaid
flowchart TB
You(["您"])
CC["Claude Code<br/>顶级会话"]
subgraph server["slang-workflows · MCP 服务器"]
direction TB
SL["您的 .slang 工作流<br/>智能体 · 权益 · 契约 · 收敛"]
EX["slang 执行器<br/>确定性 · 非大语言模型状态机"]
MB[("FlowState + 邮箱")]
SL -->|"解析一次"| EX
EX <--> MB
end
subgraph Agents["Agent SDK 会话 — 您的 .slang 声明的智能体"]
direction LR
A1["智能体 A"]
A2["智能体 B"]
A3["智能体 …"]
end
You <-->|"询问 · 批准升级"| CC
CC -->|"运行工作流"| EX
EX -->|"拓扑图 + 跟踪图"| CC
EX ==>|"调度权益 — 一个会话每个智能体，恢复"| Agents
Agents ==>|"类型结果 → 输出契约检查 + 重试"| EX
EX -.->|"升级 @ 人类"| CC
classDef brain fill:#eaeaff,stroke:#5b5bd6,stroke-width:2px;
class EX brain;
```
顶级 Claude Code 会话仅 **触发和观察** — 它从不做出协调决策。非大语言模型 **执行器** 读取您的 `.slang` 文件，调度每个 *权益* 到 Agent SDK 会话（一个长寿命会话每个智能体，恢复跨轮），检查每个结果与其 **输出契约** （重试失败），通过 **邮箱** 路由，重复每个轮，直到工作流的 `收敛` 条件或轮预算满足。运行呈现为 Mermaid **拓扑图** 和 **跟踪图**；`升级 @ 人类` 返回到您在正常聊天中。
## 用例
具体工作流（每个都是 `.slang` 文件，您使用 `运行工作流` 运行）：
- **实现具有人类设计批准门槛的功能** (`implement-feature.slang`) — 一个 *架构师*
将您的请求分解并编写设计文档，但范围限定为 **它不能物理地编写代码**
(`write_paths: ["**/*.md"]`，`deny: [Bash]`) 并且必须委托。您批准设计（`升级 @ 人类`），
然后 *开发者* 分片实现，同时 *审查者* 签署每个轮，带有最终审查门槛，然后提交。
- **将功能作为单独的、经过验证的可交付成果发布** (`implement-feature-complex.slang`) — 一个线性
设计 → 实现 → 测试 → 审查 → 文档管道，其中五个专家各自生成 **一个** 工件
（实现，一个 *通过* 的 vitest 规范，用例文档）并且不能做其他人的工作 — 因此代码、测试和
文档实际上与设计相符。仅当每个阶段都提交时才收敛。
- **使用两个独立的调查人员排除故障** (`debug.slang`) — 粘贴症状/重现；两个
开发者并行地、严格只读地（无意外编辑）地查找原因，*编排器*
将他们的独立发现合并成一个修复计划，一个开发者实现它，另一个
**同行审查修复在一个循环中**，直到满意。
- **一个只能检查但不能编辑的审查者** — 给审查智能体 `读取`/`执行` 和无写入
范围，以便“检查我的工作”运行可以运行测试和读取代码但不能修改它 — 强制执行，而不是仅仅提示。
## 功能
- **可复制的多智能体管道** — 协作在 `.slang` 文件中编码，由确定性（非大语言模型）执行器驱动，因此运行每次展开相同 — 无即兴的、不可重复的子智能体协调。
- **强制执行的每个智能体工具范围** — `write_paths` 将每个智能体的写入/编辑限制为路径通配符，`deny` 删除工具（例如 `Bash`），通过 SDK 的 `canUseTool` 强制执行 — 而不是在提示中简单请求。
- **运行前静态分析** — `validate_workflow` 在任何代币花费之前检测死锁、未知引用和孤立输出。
- **类型输出契约** — 每个权益必须返回结构上 *和* 语义上有效的结果
(`output: {…} where <expr>`); 无效结果重试而不是静默传播下游。
- **可证明的终止** — 轮预算（`budget: rounds(N)`）+ 每个权益超时保证每个运行完成。
- **自动生成的图表** — 每个运行呈现一个 Mermaid 拓扑图（`get_topology`）和一个序列图
跟踪（`get_trace`），用于实时或事后检查。
- **收敛驱动的协作** — 智能体通过邮箱路由并迭代，直到声明的收敛
条件或预算达到，具有会话恢复，以便智能体在轮之间保持其上下文。
## 与 Claude Code 的原生 *动态工作流* 的区别
Claude Code 已经具有内置的 **动态工作流** 功能：当任务需要编排时，Claude
编写一个 **JavaScript 脚本** （通过 Agent SDK / `Workflow` 工具）来生成和协调子智能体。
这是一个真正的步骤，超越了即兴的、一次性的子智能体调用 — 脚本编码了编排，并且
一旦编写完成，就确定性地运行并协调，几乎没有额外的 LLM 成本。slang 共享了这些目标；我们的
[基准测试](benchmark/) 显示 **两者** 都达到了具有近乎零协调 LLM 成本的实际、可工作的实现。**区别在于编排的内容和保证的内容：**
| | 原生动态工作流 | slang-workflows |
|---|---|---|
| 编排是… | 一个 **LLM 编写的 JavaScript** 脚本 | 一个 **类型化的、声明式的 `.slang`** 文件，由固定的非大语言模型执行器运行 |
| 谁编写了协调逻辑 | Claude，每个任务，在通用语言中 | 您（或 LLM，有一次）在运行时理解的领域特定语言中 |
| 阶段之间的输出契约 | 脚本发生的检查 | **强制执行** 由运行时 — 结构 + 语义 (`output: {…} where <expr>`); 无效 → 重试 |
| 每个智能体的工具范围 | 取决于脚本 | **强制执行** — `write_paths` / `deny` 通过 SDK 的 `canUseTool` |
| 结构的正确性 | 无检查 JS | **运行前静态分析** — 死锁 / 未知引用 / 孤立输出检测 |
| 终止 | 取决于脚本 | **可证明** — `budget: rounds(N)` + 每个权益超时 |
| 可观察性 | 自己仪器 | **自动生成** Mermaid 拓扑图 + 序列图跟踪 |
| 可重用的工件 | 脚本由模型每次重新生成 | 一个 **版本化的 `.slang` 文件** + 固定的解释器 |
简而言之：原生动态工作流将编排放在 **LLM 编写的代码中，您必须信任**；slang
将它放在 **类型化的声明中，运行时验证和强制执行** — 可分析 *之前* 运行，范围和契约检查 *在* 运行，呈现为图表 *之后*。当您想要
**保证和可审计性** （安全范围的智能体，可证明的终止，契约有效的交接，一个
可重用的版本化工作流），而不是仅仅“模型这次协调了一些子智能体”。两者都远优于
非结构化的子智能体 — slang 交换了一点前期声明以获得强制执行和重复性。
## 当前功能
- 发现/验证/运行 `.slang` 工作流 — **由 LLM 生成的内联** （下面的 MCP 工具）。
- 确定性执行器：权益 → **输出契约** 验证 + 重试 → 邮箱路由 →
收敛；**多智能体** 流；**会话恢复** （一个智能体 = 一个会话跨权益）；
`升级 @ 人类`。
- **输出契约**：结构性 (`output: {...}`，通过 SDK `outputFormat`) + 语义 (`where <expr>`).
- **强制执行的工具范围**：`write_paths` （写入/编辑限制为路径通配符，通过 PreToolUse
命令钩子）和 `deny` （删除原生或 MCP 工具）。
- **静态分析** (`validate_workflow`)：死锁/未知引用/孤立输出检测在运行前。
- **可证明的终止**：`budget: rounds(N)` + 每个权益超时 — 运行始终完成。
- **图表**：`get_topology` （Mermaid 流程图）+ `get_trace` （Mermaid 序列图 + 事件日志）。
- **同步或后台** 运行（`background:true`）带有状态/拓扑/跟踪的实时轮询。
参见 [`DESIGN.md` § 实现状态](DESIGN.md#implementation-status) 以获取完整矩阵。
## 要求
- **Node.js 22+** 和 **pnpm**。
- **Claude Code** 已安装并认证（`claude` CLI 在您的 `PATH` 上）— Agent SDK
生成它来运行智能体。
## 安装
```bash
cd server
pnpm install
```
> **Agent SDK 注意。** `@anthropic-ai/claude-agent-sdk` 被声明为 *可选* 依赖项
> 因为一些内部注册中心不镜像它。如果 `pnpm install` 跳过它，请从
> 公共注册中心添加它：
>
> ```bash
> pnpm add @anthropic-ai/claude-agent-sdk --registry=https://registry.npmjs.org/
> ```
>
> 服务器 *解析/验证* 工作流而无需它；*运行* 智能体需要它。
验证安装：
```bash
pnpm typecheck # 类型检查整个服务器
pnpm test # 运行单元测试（基于模拟，无模型调用）
```
## 使用
在运行时，服务器在 **您的项目** 的 `.claude/workflows/` （和
`~/.claude/workflows/`）中发现 `.slang` 文件 — 那是用户为其自己的工作流的空间。插件在 [`server/test/fixtures/`](server/test/fixtures) 中提供展示工作流；复制它们来尝试：
```bash
mkdir -p .claude/workflows
cp /PATH/TO/slang-orchestrator/server/test/fixtures/*.slang .claude/workflows/
```
### 最快：用 Claude Code 注册 MCP 服务器
从您要运行的项目的 `.claude/workflows/`：
```bash
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`](.claude-plugin/plugin.json)
+ [`.mcp.json`](.mcp.json) （一个 stdio 服务器，作为 `npx tsx ${CLAUDE_PLUGIN_ROOT}/server/src/main.ts` 启动）。通过 Claude Code 的插件机制安装它以自动公开工具。
### 斜杠命令
一旦插件加载，这些命令直接驱动它（Claude Code 按插件命名它们，因此您的 `/` 菜单显示 `slang-workflows:…`）：
| 命令 | 执行 |
|---------|------|
| `/slang-workflows:slang-run <名称或路径> [k=v …]` | 运行工作流到完成 — 同步，因此 `@Human` 门槛提示您。 |
| `/slang-workflows:slang-list` | 列出它可以看到的 `.slang` 工作流。 |
| `/slang-workflows:slang-new <描述>` | 从描述中生成工作流，验证它并运行它。 |
| `/slang-workflows:slang-trace [workflow_id]` | 渲染运行的拓扑图 + 序列图跟踪。 |
它们是对下面 MCP 工具的薄包装 — 您可以随时用自然语言询问 Claude （例如 *"运行 where-clause 工作流"*）。
## MCP 工具
| 工具 | 目的 |
|------|---------|
| `list_workflows` | 发现 `.slang` 文件（名称，标题，参数，智能体数量）。 |
| `get_slang_grammar` | 简洁的语法速查表 + 示例，以便 LLM 可以 **生成** 工作流来内联运行。 |
| `validate_workflow` | 解析 + 静态分析（死锁，未知引用，孤立输出）无需运行。接受 `名称`/`路径` **或** 内联 `source`。 |
| `run_workflow` | 按 `名称`/`路径` **或** 内联 `source` 运行工作流（首先拒绝解析/静态分析错误）。同步默认；`background:true` 立即返回 `workflow_id` 以实时轮询。 |
| `get_workflow_state` | 序列化 `FlowState` （每个智能体的状态，轮，预算）按 `workflow_id` — 在 `background` 运行期间实时。 |
| `get_topology` | 运行拓扑图作为 Mermaid **流程图** （状态彩色快照）按 `workflow_id`。 |
| `get_trace` | 执行 **跟踪** 作为 Mermaid **序列图** + 原始事件日志（谁投注/路由到谁，提交，升级，终端）按 `workflow_id`。 |
**生成和运行循环：** `get_slang_grammar` → 编写 slang → `validate_workflow{source}` → `run_workflow{source, background:true}` → 轮询 `get_topology` / `get_trace` 同时运行。工作流由 LLM 编写但 **确定性执行** （强制执行契约，始终终止）。`@Human` 升级仅在同步运行中有效（交互式引出需要工具调用保持打开）。
## 开发
```bash
pnpm dev # 在 stdio 上运行服务器（日志输出到 stderr）
pnpm typecheck # tsc --noEmit
pnpm test # node:test 套件
```
执行器仅依赖于 `Dispatcher` 接口；`FakeDispatcher` 使整个 VM
在没有 Agent SDK 或任何模型调用的情况下可测试（参见 [`server/test/`](server/test)）。
## 布局
```
.claude-plugin/plugin.json 插件清单
.mcp.json stdio MCP 服务器声明
server/
src/
main.ts MCP 服务器 + 工具表面
constants.ts 可调默认设置在一个地方（轮上限，重试预算，权益超时，循环守卫）
executor.ts 确定性轮循环 + 输出契约
dispatcher.ts Dispatcher 接口 + FakeDispatcher（代理运行时缝隙）
agent-sdk-dispatcher.ts 生产后端（Claude Agent SDK）
tool-group-map.ts slang 工具组 → Claude Code 工具
workflows.ts .slang 发现 + 验证
slang/ 供应商，框架无关的 slang VM（词法分析器/解析器/解释器/…）
test/ node:test 单元 + 一致性套件
fixtures/ 展示 .slang 工作流（也是 一致性测试夹具）
```
## 许可证
Apache-2.0。参见 [`LICENSE`](LICENSE)。
