{"_id":"@agent-ils/workflow-sdk","_rev":"3-416edaaee1511afe6e04fc7a660d0d9c","name":"@agent-ils/workflow-sdk","dist-tags":{"latest":"0.0.4"},"versions":{"0.0.1":{"name":"@agent-ils/workflow-sdk","version":"0.0.1","_id":"@agent-ils/workflow-sdk@0.0.1","maintainers":[{"name":"bugfix2018","email":"923401025@qq.com"},{"name":"bugfix2019","email":"670882978@qq.com"}],"dist":{"shasum":"d117b7f20aa3539ed24ba568e960dbfea38acd60","tarball":"https://registry.npmjs.org/@agent-ils/workflow-sdk/-/workflow-sdk-0.0.1.tgz","fileCount":12,"integrity":"sha512-GzKwp0tsjkKYObb+YHry3bvPgo30Yo59baoKv0o8mi24exuNuYfnwMYt1vLfC866XzJ1W5iXDV743ASFupFVXw==","signatures":[{"sig":"MEUCIQCh9nW7XOFKh1+8Z4NdUhLWZeGnGkJd1xLybAMJkdfTNAIgTRJW7ttpB/CWid8Kd9mzQYFPQWcr9P3Bv1aNo5q2QzU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":38412},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./vue":{"types":"./dist/vue/index.d.ts","import":"./dist/vue/index.js"},"./core":{"types":"./dist/core/index.d.ts","import":"./dist/core/index.js"},"./react":{"types":"./dist/react/index.d.ts","import":"./dist/react/index.js"}},"gitHead":"c9c43e7bd925b9e584af9ddaede453e84951c3ce","scripts":{"dev":"tsup --watch","test":"tsx --test __tests__/**/*.test.ts","build":"tsup","test:vue":"tsx --test src/vue/__tests__/**/*.test.ts","test:core":"tsx --test src/core/__tests__/**/*.test.ts","typecheck":"tsc --noEmit","test:react":"tsx --test src/react/__tests__/**/*.test.ts"},"_npmUser":{"name":"bugfix2019","email":"670882978@qq.com"},"_npmVersion":"10.9.3","description":"Framework-agnostic workflow infrastructure for AgentILS","directories":{},"_nodeVersion":"22.18.0","publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.4","tsup":"^8.5.1","vitest":"^4.1.5","typescript":"^5.8.3","@types/node":"^22.15.3","@types/react":"^18.3.12","@testing-library/react":"^16.3.2"},"peerDependencies":{"vue":">=3.0.0","react":">=18.0.0"},"peerDependenciesMeta":{"vue":{"optional":true},"react":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/workflow-sdk_0.0.1_1778511427466_0.049081584132592226","host":"s3://npm-registry-packages-npm-production"}},"0.0.3":{"name":"@agent-ils/workflow-sdk","version":"0.0.3","license":"MIT","_id":"@agent-ils/workflow-sdk@0.0.3","maintainers":[{"name":"bugfix2018","email":"923401025@qq.com"},{"name":"bugfix2019","email":"670882978@qq.com"}],"homepage":"https://github.com/bugfix2020/AgentILS#readme","bugs":{"url":"https://github.com/bugfix2020/AgentILS/issues"},"dist":{"shasum":"db4749caa7fb89aa0dde9ea7a2c924c9645c51b4","tarball":"https://registry.npmjs.org/@agent-ils/workflow-sdk/-/workflow-sdk-0.0.3.tgz","fileCount":12,"integrity":"sha512-z+A3+wR2oCo61zKVPyu3oVN9yNws18kxVss53rDlnBgziXOn37i2UzgymgMZNi2AkHD4RmaXaQ/qIyvhv67lbQ==","signatures":[{"sig":"MEUCIQDl0YU9/7mB9PwGvrDAcFaGvUuKfC79WnmM3Yeu+5hdVwIgBv1BNlfUROxl8KyokDOXHMhjiXnZkutjChdi6cB5mI4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@agent-ils%2fworkflow-sdk@0.0.3","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":39081},"main":"dist/index.js","type":"module","_from":"file:agent-ils-workflow-sdk-0.0.3.tgz","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./vue":{"types":"./dist/vue/index.d.ts","import":"./dist/vue/index.js"},"./core":{"types":"./dist/core/index.d.ts","import":"./dist/core/index.js"},"./react":{"types":"./dist/react/index.d.ts","import":"./dist/react/index.js"}},"scripts":{"dev":"tsup --watch","test":"tsx --test __tests__/**/*.test.ts","build":"tsup","test:vue":"tsx --test src/vue/__tests__/**/*.test.ts","test:core":"tsx --test src/core/__tests__/**/*.test.ts","typecheck":"tsc --noEmit","test:react":"tsx --test src/react/__tests__/**/*.test.ts"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:566608fc-0cd8-4c2e-bc03-b0b267966351"}},"_resolved":"/tmp/1d908a9235bf05ac65425fc5e0c8f0bf/agent-ils-workflow-sdk-0.0.3.tgz","_integrity":"sha512-z+A3+wR2oCo61zKVPyu3oVN9yNws18kxVss53rDlnBgziXOn37i2UzgymgMZNi2AkHD4RmaXaQ/qIyvhv67lbQ==","repository":{"url":"git+https://github.com/bugfix2020/AgentILS.git","type":"git","directory":"packages/workflow-sdk"},"_npmVersion":"11.11.0","description":"Framework-agnostic workflow infrastructure for AgentILS","directories":{},"_nodeVersion":"24.14.1","publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.4","tsup":"^8.5.1","vitest":"^4.1.5","typescript":"^5.8.3","@types/node":"^22.15.3","@types/react":"^18.3.12","@testing-library/react":"^16.3.2"},"peerDependencies":{"vue":">=3.0.0","react":">=18.0.0"},"peerDependenciesMeta":{"vue":{"optional":true},"react":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/workflow-sdk_0.0.3_1778513920254_0.9140545364712436","host":"s3://npm-registry-packages-npm-production"}},"0.0.4":{"name":"@agent-ils/workflow-sdk","version":"0.0.4","description":"Framework-agnostic workflow infrastructure for AgentILS","type":"module","main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./core":{"types":"./dist/core/index.d.ts","import":"./dist/core/index.js"},"./react":{"types":"./dist/react/index.d.ts","import":"./dist/react/index.js"},"./vue":{"types":"./dist/vue/index.d.ts","import":"./dist/vue/index.js"}},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"repository":{"type":"git","url":"git+https://github.com/bugfix2020/AgentILS.git","directory":"packages/workflow-sdk"},"license":"MIT","devDependencies":{"@testing-library/react":"^16.3.2","@types/node":"^22.15.3","@types/react":"^18.3.12","tsup":"^8.5.1","tsx":"^4.19.4","typescript":"^5.8.3","vitest":"^4.1.5"},"peerDependencies":{"react":">=18.0.0","vue":">=3.0.0"},"peerDependenciesMeta":{"react":{"optional":true},"vue":{"optional":true}},"scripts":{"build":"tsup","dev":"tsup --watch","typecheck":"tsc --noEmit","test":"tsx --test __tests__/**/*.test.ts","test:core":"tsx --test src/core/__tests__/**/*.test.ts","test:react":"tsx --test src/react/__tests__/**/*.test.ts","test:vue":"tsx --test src/vue/__tests__/**/*.test.ts"},"_id":"@agent-ils/workflow-sdk@0.0.4","bugs":{"url":"https://github.com/bugfix2020/AgentILS/issues"},"homepage":"https://github.com/bugfix2020/AgentILS#readme","_integrity":"sha512-gwRQGQciIpENveDYyAuirCGw98p4KDLsRLfR+bCxvfd34cVxXU9+RmII7AdwED6d5j3Uf5pYEoMzlk7CEWbYAg==","_resolved":"/tmp/5a35882d31e141248dea916d2f1531d0/agent-ils-workflow-sdk-0.0.4.tgz","_from":"file:agent-ils-workflow-sdk-0.0.4.tgz","_nodeVersion":"24.14.1","_npmVersion":"11.11.0","dist":{"integrity":"sha512-gwRQGQciIpENveDYyAuirCGw98p4KDLsRLfR+bCxvfd34cVxXU9+RmII7AdwED6d5j3Uf5pYEoMzlk7CEWbYAg==","shasum":"4cc5852575789bfd95ef578f3103ca2ee32c559e","tarball":"https://registry.npmjs.org/@agent-ils/workflow-sdk/-/workflow-sdk-0.0.4.tgz","fileCount":12,"unpackedSize":35430,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@agent-ils%2fworkflow-sdk@0.0.4","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCiGPidJ5OF4Ov3CFDJqjLEntL9noMqXjF2aBsKUYM1+wIgLht/Y/jNlAtMRJ1rKR/FGdvYkBuUYcLKwXh4B1xkMiw="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:566608fc-0cd8-4c2e-bc03-b0b267966351"}},"directories":{},"maintainers":[{"name":"bugfix2018","email":"923401025@qq.com"},{"name":"bugfix2019","email":"670882978@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/workflow-sdk_0.0.4_1778597384322_0.22430350416191236"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-11T14:57:07.374Z","modified":"2026-05-12T14:49:44.883Z","0.0.1":"2026-05-11T14:57:07.613Z","0.0.3":"2026-05-11T15:38:40.425Z","0.0.4":"2026-05-12T14:49:44.474Z"},"bugs":{"url":"https://github.com/bugfix2020/AgentILS/issues"},"license":"MIT","homepage":"https://github.com/bugfix2020/AgentILS#readme","repository":{"type":"git","url":"git+https://github.com/bugfix2020/AgentILS.git","directory":"packages/workflow-sdk"},"description":"Framework-agnostic workflow infrastructure for AgentILS","maintainers":[{"name":"bugfix2018","email":"923401025@qq.com"},{"name":"bugfix2019","email":"670882978@qq.com"}],"readme":"# AgentILS Workflow SDK\n\n<p align=\"center\">\n  <a href=\"https://www.npmjs.com/package/@agent-ils/workflow-sdk\"><img alt=\"npm\" src=\"https://img.shields.io/npm/v/@agent-ils/workflow-sdk?label=npm&color=CB3837\"></a>\n  <img alt=\"TypeScript\" src=\"https://img.shields.io/badge/TypeScript-5.8-3178C6?logo=typescript&logoColor=white\">\n  <img alt=\"Node.js\" src=\"https://img.shields.io/badge/Node.js-20%2B-339933?logo=node.js&logoColor=white\">\n  <img alt=\"tsup\" src=\"https://img.shields.io/badge/tsup-ESM-7C3AED\">\n  <img alt=\"React\" src=\"https://img.shields.io/badge/React-18%2B-61DAFB?logo=react&logoColor=black\">\n  <img alt=\"Vue\" src=\"https://img.shields.io/badge/Vue-3%2B-4FC08D?logo=vue.js&logoColor=white\">\n</p>\n\n<p align=\"center\">\n  <a href=\"https://github.com/bugfix2020/AgentILS/blob/main/packages/workflow-sdk/README.md\">English</a> | 简体中文\n</p>\n\n`@agent-ils/workflow-sdk` 是一个框架无关的工作流执行引擎。将多步骤工作流定义为节点数组，运行时通过 context 传递和 patch 更新状态，并可选用 React hooks 或 Vue 3 composables 接入响应式 UI。\n\n它**不**提供可视化编辑器、持久化存储或服务端运行时——它是一个轻量级的客户端编排层。\n\n## 安装\n\n```sh\npnpm add @agent-ils/workflow-sdk\n```\n\n## 场景：鉴权后查看敏感数据\n\n用户点击「查看敏感数据」→ 弹出验证码表单 → 验证码正确则拉取并展示数据，**验证码错误则工作流立即中断**——数据拉取不会执行。\n\n```\ninit → verify → fetch-data → complete\n                ↑\n                └── 验证码错误 → stop（fetch-data 不会执行）\n```\n\n### 定义工作流\n\n```ts\n// workflow.ts\nimport { defineNode, defineWorkflow } from '@agent-ils/workflow-sdk/core'\n\nexport interface AuthContext {\n    requestId: string\n    code: string\n    secretData: string\n    fetchedAt: number\n    completed: boolean\n}\n\nexport const authWorkflow = defineWorkflow<AuthContext>({\n    id: 'auth-view-secret',\n    nodes: [\n        defineNode({\n            id: 'init',\n            run: async () => ({\n                type: 'continue',\n                patch: { requestId: `req_${Date.now()}` },\n            }),\n        }),\n        // 关键：验证码错误时返回 stop，后续节点不会执行\n        defineNode({\n            id: 'verify',\n            run: async (ctx) => {\n                if (ctx.code !== '123456') {\n                    return { type: 'stop', reason: `验证码错误：${ctx.code}` }\n                }\n                return { type: 'continue' }\n            },\n        }),\n        defineNode({\n            id: 'fetch-data',\n            run: async () => ({\n                type: 'continue',\n                patch: { secretData: '机密内容...', fetchedAt: Date.now() },\n            }),\n        }),\n        defineNode({\n            id: 'complete',\n            run: async () => ({ type: 'continue', patch: { completed: true } }),\n        }),\n    ],\n})\n```\n\n### React + Antd\n\n```sh\npnpm add @agent-ils/workflow-sdk react antd\n```\n\n```tsx\nimport { useWorkflow } from '@agent-ils/workflow-sdk/react'\nimport { Steps, Button, Alert } from 'antd'\nimport { authWorkflow, type AuthContext } from './workflow'\nimport { VerifyForm } from './VerifyForm'\nimport { DataViewer } from './DataViewer'\n\nfunction App() {\n    const { status, start } = useWorkflow({ definition: authWorkflow })\n\n    const handleVerify = async (code: string) => {\n        const res = await start({\n            requestId: '',\n            code,\n            secretData: '',\n            fetchedAt: 0,\n            completed: false,\n        })\n        if (res.status === 'stopped') {\n            // 验证失败 — fetch-data 从未执行\n            message.error(res.reason)\n        }\n    }\n\n    return (\n        <>\n            <Steps\n                current={status === 'done' ? 3 : status === 'stopped' ? 1 : 0}\n                status={status === 'stopped' ? 'error' : 'process'}\n            >\n                <Step title=\"初始化\" />\n                <Step title=\"身份验证\" />\n                <Step title=\"获取数据\" />\n                <Step title=\"完成\" />\n            </Steps>\n            {status === 'idle' && <VerifyForm onSubmit={handleVerify} />}\n            {status === 'stopped' && <Alert type=\"error\" description=\"验证失败\" />}\n            {status === 'done' && <DataViewer />}\n        </>\n    )\n}\n```\n\n完整可运行项目：[`examples/react-antd/`](https://github.com/bugfix2020/AgentILS/tree/main/packages/workflow-sdk/examples/react-antd)\n\n### Vue 3 + Element Plus\n\n```sh\npnpm add @agent-ils/workflow-sdk vue element-plus\n```\n\n```vue\n<script setup lang=\"ts\">\nimport { useWorkflow } from '@agent-ils/workflow-sdk/vue'\nimport { authWorkflow, type AuthContext } from './workflow'\n\nconst { status, start, abort } = useWorkflow({ definition: authWorkflow })\n\nasync function handleVerify(code: string) {\n    const res = await start({\n        requestId: '',\n        code,\n        secretData: '',\n        fetchedAt: 0,\n        completed: false,\n    })\n    if (res.status === 'stopped') {\n        ElMessage.error(res.reason)\n    }\n}\n</script>\n\n<template>\n    <el-steps :active=\"status === 'done' ? 3 : status === 'stopped' ? 1 : 0\">\n        <el-step title=\"初始化\" /><el-step title=\"身份验证\" /> <el-step title=\"获取数据\" /><el-step title=\"完成\" />\n    </el-steps>\n    <VerifyForm v-if=\"status === 'idle'\" @submit=\"handleVerify\" />\n    <el-alert v-if=\"status === 'stopped'\" type=\"error\" description=\"验证失败\" />\n    <DataViewer v-if=\"status === 'done'\" />\n</template>\n```\n\n完整可运行项目：[`examples/vue-element-plus/`](https://github.com/bugfix2020/AgentILS/tree/main/packages/workflow-sdk/examples/vue-element-plus)\n\n## 中断工作流\n\n有三种方式阻止后续节点执行：\n\n### 1. `stop` 信号 — 受控中断\n\n在节点的 `run` 中返回 `{ type: 'stop', reason: '...' }`。工作流立即中断，patch 仍然会被应用，`result.status === 'stopped'`。\n\n```ts\ndefineNode({\n    id: 'gate',\n    run: async (ctx) => {\n        if (!ctx.authorized) return { type: 'stop', reason: '未授权' }\n        return { type: 'continue' }\n    },\n})\n```\n\n### 2. 抛出异常 — 意外失败\n\n在 `run` 内部 `throw`。工作流捕获异常，设置 `result.status === 'failed'`，错误存储在 `result.error`。\n\n```ts\ndefineNode({\n    id: 'api-call',\n    run: async (ctx) => {\n        const res = await fetch(ctx.url)\n        if (!res.ok) throw new Error(`HTTP ${res.status}`)\n        return { type: 'continue', patch: { data: await res.json() } }\n    },\n})\n```\n\n### 3. `AbortSignal` — 外部取消\n\n通过 `run({ signal })` 传入 `AbortSignal`。引擎在节点之间检查是否已取消。\n\n```ts\nconst ac = new AbortController()\nsetTimeout(() => ac.abort(), 5000)\nconst result = await workflow.run({ initialContext: {}, signal: ac.signal })\n```\n\n## API\n\n### 核心\n\n| 导出                      | 类型 | 说明                                |\n| ------------------------- | ---- | ----------------------------------- |\n| `defineNode(opts)`        | 函数 | 创建带类型节点的辅助函数            |\n| `defineWorkflow(def)`     | 函数 | 创建带类型工作流定义的辅助函数      |\n| `createWorkflow(def)`     | 函数 | 返回 `{ definition, run(options) }` |\n| `applyPatch(ctx, patch?)` | 函数 | 浅合并 partial patch 到 context     |\n\n### 节点 `run` 返回值 — `WorkflowSignal`\n\n| 类型       | 字段                        | 效果                     |\n| ---------- | --------------------------- | ------------------------ |\n| `continue` | `patch?: Partial<TContext>` | 合并 patch，进入下个节点 |\n| `stop`     | `reason: string`, `patch?`  | 合并 patch，停止工作流   |\n\n### `run()` 参数\n\n| 选项             | 类型                  | 说明                             |\n| ---------------- | --------------------- | -------------------------------- |\n| `initialContext` | `TContext`            | 必填，传给第一个节点的初始上下文 |\n| `hook?`          | `{ before?, after? }` | 每个节点执行前后的生命周期回调   |\n| `signal?`        | `AbortSignal`         | 节点间合作式取消                 |\n\n### `run()` 返回值 — `WorkflowRunResult`\n\n| 字段      | 类型                              | 说明                             |\n| --------- | --------------------------------- | -------------------------------- |\n| `status`  | `'done' \\| 'stopped' \\| 'failed'` | 终态                             |\n| `context` | `TContext`                        | 最终上下文（含最后一次 patch）   |\n| `reason?` | `string`                          | 当 `status === 'stopped'` 时存在 |\n| `error?`  | `unknown`                         | 当 `status === 'failed'` 时存在  |\n\n## 不做的事\n\n- 不提供可视化工作流编辑器或 DAG UI。\n- 不提供内置持久化、回放或时间旅行调试。\n- 不提供服务端编排、队列或分布式执行。\n- 不校验节点间的输入/输出 schema——类型安全由 TypeScript 编译期保证。\n","readmeFilename":"README.zh-CN.md"}