Conductor Skills：让 AI 编码代理为 Conductor 构建、运行与管理工作流

Conductor Skills：让 AI 编码代理为 Conductor 构建、运行与管理工作流

【免费下载链接】conductorConductor is an event driven agentic workflow engine providing durable and highly resilient execution engine for applications and AI Agents项目地址: https://gitcode.com/GitHub_Trending/co/conductor

Conductor Skills 是官方提供的一套"技能包"，它教会 Claude Code、Cursor、GitHub Copilot、Gemini CLI 等主流 AI 编码代理如何创建、注册、运行、监控和调优 Conductor 工作流与 Agent——你只需用自然语言描述需求，代理即可完成从工作流定义到 Worker 代码的完整交付。本文完整讲解其安装、连接服务器、能力边界与一个订单处理系统的端到端实战流程，并结合当前仓库源码剖析代理所操作的底层 REST API、任务执行与生命周期控制实现，帮助你在掌握用法的同时理解其背后的运行时语义。

前置条件：一个可用的 Conductor 服务器

Conductor Skills 本身不包含服务器，它只是教你的代理"怎么和服务器打交道"。因此第一个前提是本地或云端有一台 Conductor 服务。如果手头没有，可以用官方 CLI 快速起一个本地实例：

npm install -g @conductor-oss/conductor-cli conductor server start

也可以使用免费的托管 Developer Edition。连接相关的完整说明见仓库中的 Connect to Conductor。从仓库结构看，本地服务器对应server模块（Spring Boot 应用），它把core（核心执行引擎）、各持久化模块（redis-persistence、postgres-persistence等）与rest（REST API 控制器）装配在一起——这正是你的代理最终会调用的一组 HTTP 端点。

安装：一条命令适配所有编码代理

Conductor Skills 提供统一的安装脚本，自动检测本机已安装的 AI 编码代理并逐一安装：

macOS / Linux：

curl -sSL https://conductor-oss.github.io/conductor-skills/install.sh | bash -s -- --all

Windows (PowerShell)：

irm https://conductor-oss.github.io/conductor-skills/install.ps1 -OutFile install.ps1; .\install.ps1 -All

如果只想给某一个代理安装，用--agent指定其标识，例如 Claude Code：

curl -sSL https://conductor-oss.github.io/conductor-skills/install.sh | bash -s -- --agent claude

官方文档标注的安装耗时约为 2 分钟。安装后技能内容会以该代理约定的规则文件/技能目录形式落盘（下文"支持的代理"一节列出了每个代理的全局与项目级安装路径）。

连接你的服务器

安装完成后，需要告诉代理 Conductor 服务器在哪里。有两种方式：

方式一，直接用自然语言指令：

Connect to my Conductor server at http://localhost:8080/api

方式二，设置环境变量：

export CONDUCTOR_SERVER_URL=http://localhost:8080/api

这里http://localhost:8080/api是本地默认端口下的 REST 基地址。该地址最终会命中rest模块中的控制器——例如 WorkflowResource、TaskResource 与 MetadataResource，它们分别承载了执行控制、任务更新/信号与元数据注册（工作流定义、TaskDef）等端点。

代理能做什么：九类能力一览

装好之后，你可以直接给编码代理下达以下类型的提示，每条提示对应的结果如下表（原文档中的能力矩阵完整继承）：

能力	提示词示例	实际结果
创建工作流	"Create a workflow that calls the GitHub API and sends a Slack notification"	代理生成含 HTTP 任务、输入表达式与输出参数的完整工作流定义
运行工作流	"Run my-workflow with input userId 123"	代理启动执行并返回执行 ID
监控执行	"Show me all failed workflows from the last hour"	代理按状态、时间或关联 ID 搜索执行记录
调试失败	"What went wrong with execution abc-123?"	代理拉取执行详情，定位失败任务并展示错误
重试与恢复	"Retry all failed executions of order-processing"	代理批量重试失败执行
生命周期管理	"Pause execution xyz-456"	代理暂停、恢复、终止或重启工作流
信号任务	"Approve the payment wait task in execution abc-123"	代理向 WAIT/HUMAN 任务发信号以推进工作流
编写 Worker	"Write a Python worker that validates email addresses"	代理使用对应语言的 SDK 生成 Worker 代码
可视化	"Show me a diagram of the order-processing workflow"	代理将工作流渲染为 Mermaid 图

值得注意的是，这些"能力"并不是代理的魔法，而是它按约定调用 Conductor REST API 的结果。例如"生命周期管理"背后是 WorkflowExecutorOps 中的pauseWorkflow、resumeWorkflow、retry、terminateWorkflow、restart等方法，最终经由 WorkflowServiceImpl 暴露给 REST 层；"信号任务"则对应TaskResource中的信号端点（见下文实战 Step 5 的源码剖析）。

实战演练：用自然语言构建订单处理系统

以下示例完整展示了如何用自然语言提示，让编码代理构建一个 Conductor 应用。流程为：创建工作流 → 创建补偿工作流 → 编写自定义 Worker → 运行 → 人工审批 → 监控与调试 → 可视化。

Step 1：创建工作流

提示词：

Create an order processing workflow with these steps: validate the order, check inventory, charge payment, and fulfill the order. If payment fails, compensate by releasing the inventory hold. Add a HUMAN task before payment so a human can review high-value orders.

代理会生成如下工作流定义（这是 Conductor 标准 JSON 定义格式，可直接通过元数据接口注册）：

{ "name": "order_processing", "description": "Process customer orders with inventory check, payment, and fulfillment", "version": 1, "schemaVersion": 2, "inputParameters": ["orderId", "customerId", "items", "totalAmount"], "tasks": [ { "name": "validate_order", "taskReferenceName": "validate", "type": "HTTP", "inputParameters": { "http_request": { "uri": "https://api.example.com/orders/${workflow.input.orderId}/validate", "method": "POST", "body": { "items": "${workflow.input.items}" } } } }, { "name": "check_inventory", "taskReferenceName": "inventory", "type": "HTTP", "inputParameters": { "http_request": { "uri": "https://api.example.com/inventory/hold", "method": "POST", "body": { "items": "${workflow.input.items}" } } } }, { "name": "review_gate", "taskReferenceName": "review_gate", "type": "SWITCH", "evaluatorType": "graaljs", "expression": "$.totalAmount > 500 ? 'needs_review' : 'auto_approve'", "inputParameters": { "totalAmount": "${workflow.input.totalAmount}" }, "decisionCases": { "needs_review": [ { "name": "human_review", "taskReferenceName": "review", "type": "HUMAN", "inputParameters": { "orderId": "${workflow.input.orderId}", "amount": "${workflow.input.totalAmount}" } } ] }, "defaultCase": [] }, { "name": "charge_payment", "taskReferenceName": "payment", "type": "HTTP", "inputParameters": { "http_request": { "uri": "https://api.example.com/payments/charge", "method": "POST", "body": { "customerId": "${workflow.input.customerId}", "amount": "${workflow.input.totalAmount}", "holdId": "${inventory.output.response.body.holdId}" } } } }, { "name": "fulfill_order", "taskReferenceName": "fulfillment", "type": "HTTP", "inputParameters": { "http_request": { "uri": "https://api.example.com/fulfillment/ship", "method": "POST", "body": { "orderId": "${workflow.input.orderId}", "items": "${workflow.input.items}", "paymentId": "${payment.output.response.body.paymentId}" } } } } ], "failureWorkflow": "order_processing_compensation", "outputParameters": { "orderId": "${workflow.input.orderId}", "paymentId": "${payment.output.response.body.paymentId}", "trackingNumber": "${fulfillment.output.response.body.trackingNumber}" } }

这段定义里值得对照源码理解的三个关键点：

• schemaVersion: 2：在 WorkflowDef 中该字段被 Bean Validation 注解约束为@Min(2)且@Max(2)，即服务端当前只接受 schemaVersion 2 的定义。代理生成定义时若填错版本号，注册（POST /metadata/workflow）会被拒绝。
• SWITCH+evaluatorType: "graaljs"：分支判断由 GraalVM JavaScript 求值器执行，对应源码 GraalJSEvaluator 与 Switch 任务实现。decisionCases中的键（如needs_review）必须与表达式求值结果完全一致才会命中对应分支。
• failureWorkflow：工作流失败时自动触发补偿工作流order_processing_compensation。该字段同样是 WorkflowDef 中的一等字段（另有failureWorkflowVersion可固定补偿工作流版本），这正是本例 Saga 式补偿的实现基础。

代理生成定义后还应自动完成注册——即调用元数据接口POST /metadata/workflow（见 MetadataResource）。仓库中的 schemas/Workflow.json 提供了字段级 JSON Schema，可供校验代理生成的定义结构。

Step 2：创建补偿工作流

提示词：

Create the compensation workflow for order_processing. It should release the inventory hold and refund the payment if it was charged.

代理会创建名为order_processing_compensation的工作流，内容是与主流程逆序执行的逆向操作（释放库存占用、已扣款则退款）。它与主流程通过failureWorkflow字段绑定：任何主流程任务在重试耗尽后失败，Conductor 都会自动启动这个补偿定义。

Step 3：编写自定义 Worker

提示词：

Write a Python worker that validates orders by checking that all items exist and quantities are positive

代理使用 Conductor Python SDK 生成 Worker 代码：

from conductor.client.worker.worker_task import worker_task @worker_task(task_definition_name="validate_order") def validate_order(task): items = task.input_data.get("items", []) for item in items: if not item.get("productId"): return {"valid": False, "reason": f"Missing productId"} if item.get("quantity", 0) <= 0: return {"valid": False, "reason": f"Invalid quantity for {item['productId']}"} return {"valid": True, "itemCount": len(items)}

@worker_task装饰器会注册一个轮询服务器任务队列的后台循环：领取任务、调用回调函数、把返回字典作为任务输出上报。Java 侧对应的模式是@WorkerTask注解与 AnnotatedSystemTaskMapper（见 AGENTS.md 中"Worker tasks use the@WorkerTaskannotation for automatic discovery"）。多语言 SDK 的完整列表见 Client SDKs。

Step 4：运行工作流

提示词：

Run order_processing with orderId ORD-001, customerId CUST-42, items [{productId: SKU-100, quantity: 2}], totalAmount 750

代理输出：

Workflow started. - Execution ID: f8a2b3c4-d5e6-7890-abcd-ef1234567890 - Status: RUNNING - The order total ($750) exceeds $500, so it's waiting for human review.

执行启动后状态为RUNNING，但流程走到 SWITCH 分支判断：totalAmount为 750 超过 500，命中needs_review分支，进入human_review这个HUMAN任务。HUMAN 任务会持久地挂起执行状态，直到收到信号——这正是 Conductor "durable execution"（可持久化执行）语义的体现：等待不消耗线程，状态全部落在持久层。

Step 5：批准审批（信号 WAIT/HUMAN 任务）

提示词：

Approve the review task in execution f8a2b3c4

代理输出：

Task signaled: review → COMPLETED Workflow is now executing charge_payment.

从源码看，这条"批准"操作对应的是 REST 层的信号端点。TaskResource 中定义了POST /{workflowId}/{status}/signal（异步）与POST /{workflowId}/{status}/signal/sync（同步）两个端点，内部调用taskService.signalTask(workflowId, status, output)：服务器在当前执行中找到处于阻塞状态（WAIT/HUMAN 等）的目标任务，将其置为 COMPLETED 并写入信号输出，然后决策器（Decider）推进后续任务——本例即charge_payment。同步版本若找不到阻塞任务会抛出 "Found no blocked task in workflow ... to signal" 异常，这一点在批量审批脚本中值得留意。

Step 6：监控与调试

提示词：

Show me all failed order_processing executions from today

代理输出：

Found 2 failed executions: 1. exec-abc — Failed at charge_payment (HTTP 402: Insufficient funds) 2. exec-def — Failed at check_inventory (HTTP 409: Item SKU-200 out of stock)

接着可以批量或单个重试：

提示词：

Retry exec-abc

代理输出：

Execution exec-abc retried. Status: RUNNING.

"按状态搜索执行"依赖持久化后端的索引/查询能力（redis-persistence、postgres-persistence、es7/es8-persistence等模块各自实现）；"重试"则落到 WorkflowExecutorOps 的retry(workflowId, resumeSubworkflowTasks)。注意重试的语义边界：对已完成的任务不会重做，失败任务按 TaskDef 的重试策略恢复；如果工作流配置了failureWorkflow，补偿流程与重试是两条独立的恢复路径，代理在诊断时应当先确认失败是"可重试的瞬时错误"还是"需要补偿的业务失败"。

Step 7：可视化

提示词：

Show me a diagram of order_processing

代理把任务图渲染为 Mermaid：

支持的编码代理与安装位置

Conductor Skills 覆盖 12 类主流 AI 编码代理，各自的--agent安装标志、全局安装位置与项目级安装位置如下表：

代理	安装标志	全局安装位置	项目级安装位置
Claude Code	claude	原生 Skill	—
Codex CLI	codex	~/.codex/AGENTS.md	AGENTS.md
Gemini CLI	gemini	~/.gemini/GEMINI.md	GEMINI.md
Cursor	cursor	~/.cursor/skills/	.cursor/rules/
Windsurf	windsurf	~/.codeium/windsurf/	.windsurfrules
GitHub Copilot	copilot	—	.github/copilot-instructions.md
Cline	cline	—	.clinerules
Amazon Q	amazonq	—	.amazonq/rules/
Aider	aider	~/.conductor-skills/	.conductor-skills/
Roo Code	roo	~/.roo/rules/	.roo/rules/
Amp	amp	~/.config/AGENTS.md	.amp/instructions.md
OpenCode	opencode	~/.config/opencode/skills/	AGENTS.md

从表中可以看出，Conductor Skills 的安装产物本质上是注入到各代理"指令文件"约定中的行为规范——AGENTS.md、GEMINI.md、.cursor/rules 等。这也解释了为什么本仓库自身的 AGENTS.md 文件里写着面向 AI 编码代理的工程规范（构建命令、代码风格、测试要求）：Skills 让代理在生成工作流、调用 API 与编写 Worker 时遵循同样的约定，而不是自由发挥。

给任意 AI 助手的机器可读文档

除 Skills 之外，仓库还内置了一组专为 LLM/Agent 准备的入口，代理（或你手动）可以把它们直接喂给任意 AI 助手：

• Conductor for AI assistants：规范页面，定义了 Conductor 的权威词汇表、安全编写规则（如"外部副作用必须幂等""有后果的写入前要求 HUMAN 审批""不要把凭据放进工作流输入"）与任务选型指引；
• llms.txt：机器可读的文档索引，列出各主题页面的规范入口，并声明"当文档与实现不一致时，以工作流定义、Java 源码与 SDK 源码为准"；
• llms-full.txt：将完整文档合并为单文件的版本，适合一次性灌入上下文。

这意味着即使你的编码代理不安装 Skills，也可以把llms.txt指给它作为"检索地图"，达到类似效果。

升级

技能更新后，用带--upgrade标志的同一条安装命令刷新所有代理：

curl -sSL https://conductor-oss.github.io/conductor-skills/install.sh | bash -s -- --all --upgrade

小结与延伸阅读

Conductor Skills 把"Conductor 怎么用好"这件事从人工查文档变成了代理可执行的自然语言操作：创建工作流定义、注册元数据、启动执行、信号 HUMAN 任务、监控搜索、批量重试、生成 Worker 代码与 Mermaid 图，全部通过约定好的 REST API 完成——而这些 API 与任务语义都可以在本仓库源码中逐一对应验证（rest控制器、WorkflowExecutorOps、GraalJSEvaluator、Switch等）。掌握本文之后，你可以继续深入：

• 从零动手构建第一个工作流与 Worker：Your First Workflow & Worker；
• 构建持久化 AI Agent 工作流：Your First Agent 与 Agents overview；
• 编写 Worker 所用的各语言 SDK：Client SDKs；
• 工作流定义全部字段的参考：Workflow definition reference。

【免费下载链接】conductorConductor is an event driven agentic workflow engine providing durable and highly resilient execution engine for applications and AI Agents项目地址: https://gitcode.com/GitHub_Trending/co/conductor