@aalis/api-workflow 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Ace Nyan <ace@acenyan.com>
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,171 @@
1
+ export type TriggerSpec = {
2
+ type: 'cron';
3
+ expr: string;
4
+ } | {
5
+ type: 'interval';
6
+ seconds: number;
7
+ } | {
8
+ type: 'once';
9
+ runAt: string;
10
+ } | {
11
+ type: 'event';
12
+ event: string;
13
+ filter?: Record<string, unknown>;
14
+ } | {
15
+ type: 'manual';
16
+ };
17
+ export type NodeType = 'tool' | 'send-message' | 'wait' | 'agent';
18
+ interface BaseNodeSpec {
19
+ /** 节点唯一 id(在工作流内) */
20
+ id: string;
21
+ /** 节点类型 */
22
+ type: NodeType;
23
+ /** 上游依赖节点 id 列表;空数组表示根节点 */
24
+ deps?: string[];
25
+ /** 把节点结果存入 outputs[out],供下游 {{outputs.<out>}} 插值 */
26
+ out?: string;
27
+ }
28
+ export interface ToolNodeSpec extends BaseNodeSpec {
29
+ type: 'tool';
30
+ /** 工具名(必须已注册) */
31
+ tool: string;
32
+ /** 工具参数;字符串值会被插值({{vars.X}} / {{outputs.Y}}) */
33
+ args?: Record<string, unknown>;
34
+ }
35
+ export interface SendMessageNodeSpec extends BaseNodeSpec {
36
+ type: 'send-message';
37
+ sessionId: string;
38
+ platform?: string;
39
+ /** 消息内容;支持插值 */
40
+ content: string;
41
+ }
42
+ export interface WaitNodeSpec extends BaseNodeSpec {
43
+ type: 'wait';
44
+ /** 等待秒数 */
45
+ seconds: number;
46
+ }
47
+ /**
48
+ * agent 节点:把一段指令派发给 agent 处理并**等待其回复**,回复文本作为节点结果。
49
+ *
50
+ * 与 send-message 的区别:send-message 是 fire-and-forget;agent 节点会注册
51
+ * `agent:turn:after` 监听、join 目标会话本轮回复,从而把"一个子任务 = 一次 agent 调用"
52
+ * 接入 DAG——配合 deps/串并行/`{{outputs.X}}` 插值即可表达"分解→依赖→管道→聚合"的确定性编排。
53
+ */
54
+ export interface AgentNodeSpec extends BaseNodeSpec {
55
+ type: 'agent';
56
+ /** 交给 agent 处理的指令/任务正文;支持插值({{vars.X}} / {{outputs.Y}}) */
57
+ instruction: string;
58
+ /**
59
+ * 目标会话 id;支持插值。省略时为本节点生成一次性隔离子会话
60
+ * (`workflow:agent:<runId>:<nodeId>`),互不串扰,适合"子任务"语义(推荐)。
61
+ *
62
+ * ⚠️ 同一并行层内**不要**让多个 agent 节点指向**相同的显式 sessionId**:`agent:turn:after`
63
+ * 按 sessionId 匹配回复,会发生串扰捕获(A 可能拿到 B 的回复)。需要隔离子任务就省略本字段。
64
+ */
65
+ sessionId?: string;
66
+ /** 平台标识;默认 'workflow' */
67
+ platform?: string;
68
+ /** 等待 agent 回复的超时秒数;默认 120。超时则该节点失败。 */
69
+ timeoutSeconds?: number;
70
+ }
71
+ export type NodeSpec = ToolNodeSpec | SendMessageNodeSpec | WaitNodeSpec | AgentNodeSpec;
72
+ export interface WorkflowDef {
73
+ /** 工作流唯一 id(文件名/外部引用键) */
74
+ id: string;
75
+ /** 显示名 */
76
+ name?: string;
77
+ /** 描述 */
78
+ description?: string;
79
+ /** 默认变量;运行时可覆盖 */
80
+ vars?: Record<string, unknown>;
81
+ /** 触发器;manual 表示仅手动调用 */
82
+ trigger: TriggerSpec;
83
+ /** DAG 节点 */
84
+ nodes: NodeSpec[];
85
+ /** 是否启用 */
86
+ enabled?: boolean;
87
+ }
88
+ export type RunStatus = 'pending' | 'running' | 'success' | 'failed' | 'cancelled';
89
+ export type NodeStatus = 'pending' | 'running' | 'success' | 'failed' | 'skipped';
90
+ export interface NodeRunInfo {
91
+ id: string;
92
+ type: NodeType;
93
+ status: NodeStatus;
94
+ startedAt?: number;
95
+ finishedAt?: number;
96
+ /** 节点输出(截断后的字符串展示) */
97
+ output?: string;
98
+ /** 失败原因 */
99
+ error?: string;
100
+ }
101
+ export interface WorkflowRun {
102
+ runId: string;
103
+ workflowId: string;
104
+ status: RunStatus;
105
+ /** 触发来源(cron/interval/event/manual) */
106
+ triggerSource: string;
107
+ startedAt: number;
108
+ finishedAt?: number;
109
+ /** 实例变量(trigger payload + 运行时传入) */
110
+ vars: Record<string, unknown>;
111
+ /** 节点运行明细 */
112
+ nodes: NodeRunInfo[];
113
+ /** 整体错误(首个失败的简要) */
114
+ error?: string;
115
+ }
116
+ export interface WorkflowService {
117
+ /** 列出全部工作流定义 */
118
+ listWorkflows(): WorkflowDef[];
119
+ /** 按 id 获取定义 */
120
+ getWorkflow(id: string): WorkflowDef | undefined;
121
+ /** 注册/覆盖一个工作流定义;persist=true 时同步写入 workspace/workflows/<id>.yaml */
122
+ defineWorkflow(def: WorkflowDef, opts?: {
123
+ persist?: boolean;
124
+ }): Promise<void>;
125
+ /** 删除工作流(若 persist 文件存在则删除) */
126
+ removeWorkflow(id: string): Promise<boolean>;
127
+ /** 手动触发一次运行;vars 与定义中的 vars 浅合并 */
128
+ runWorkflow(id: string, vars?: Record<string, unknown>, triggerSource?: string,
129
+ /** 调用者身份:经 workflow_run 工具触发时透传,使内部工具按调用者权限裁决(缺省=匿名) */
130
+ caller?: {
131
+ platform?: string;
132
+ userId?: string;
133
+ }): Promise<WorkflowRun>;
134
+ /** 取消一个运行中的实例(若执行引擎支持) */
135
+ cancelRun(runId: string): boolean;
136
+ /** 获取运行实例(含历史) */
137
+ getRun(runId: string): WorkflowRun | undefined;
138
+ /** 列出最近 N 个运行实例(按时间倒序) */
139
+ listRuns(limit?: number, workflowId?: string): WorkflowRun[];
140
+ }
141
+ declare module '@aalis/core' {
142
+ interface AalisEvents {
143
+ /** 触发器触发 — 由 scheduler/event/webhook 等触发源发出,workflow 订阅 */
144
+ 'trigger:fired': [
145
+ info: {
146
+ /** 触发器来源标识(如 scheduler:job-name / event:session:end) */
147
+ source: string;
148
+ /** 触发器类型 */
149
+ type: 'cron' | 'interval' | 'event' | 'webhook' | 'manual';
150
+ /** 关联的工作流 id(若触发器只服务一个 workflow) */
151
+ workflowId?: string;
152
+ /** 透传给运行实例 vars 的负载 */
153
+ payload?: Record<string, unknown>;
154
+ }
155
+ ];
156
+ 'workflow:run:start': [run: WorkflowRun];
157
+ 'workflow:run:done': [run: WorkflowRun];
158
+ 'workflow:run:error': [run: WorkflowRun];
159
+ 'workflow:node:done': [info: {
160
+ runId: string;
161
+ node: NodeRunInfo;
162
+ }];
163
+ }
164
+ }
165
+ declare module '@aalis/core' {
166
+ interface ServiceTypeMap {
167
+ workflow: WorkflowService;
168
+ }
169
+ }
170
+ export {};
171
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
package/dist/index.js ADDED
@@ -0,0 +1,15 @@
1
+ // ============================================================
2
+ // @aalis/api-workflow
3
+ //
4
+ // Workflow 插件的公共契约:DSL 类型、运行实例类型、服务接口。
5
+ // 实际执行引擎由 @aalis/plugin-workflow 提供。
6
+ //
7
+ // 设计要点:
8
+ // - 工作流 = 触发器 + DAG(节点 + deps 边)
9
+ // - 节点类型:tool / send-message / wait / agent;后续可扩 decision / parallel-fanout
10
+ // - DAG 引擎按 deps 拓扑分层并行执行;任一节点失败整个 run 标记 failed
11
+ // - 节点可声明 `out`,将 string 结果存入 outputs 命名空间,供下游 `{{outputs.X}}` 插值
12
+ // - 工作流"定义"是用户/AI 资产,存 workspace;"运行实例"是运行时,存 data
13
+ // ============================================================
14
+ export {};
15
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,sBAAsB;AACtB,EAAE;AACF,uCAAuC;AACvC,qCAAqC;AACrC,EAAE;AACF,QAAQ;AACR,mCAAmC;AACnC,8EAA8E;AAC9E,mDAAmD;AACnD,oEAAoE;AACpE,qDAAqD;AACrD,+DAA+D"}
package/package.json ADDED
@@ -0,0 +1,40 @@
1
+ {
2
+ "name": "@aalis/api-workflow",
3
+ "version": "0.9.0",
4
+ "license": "MIT",
5
+ "repository": {
6
+ "type": "git",
7
+ "url": "git+https://github.com/AalisLabs/Aalis.git",
8
+ "directory": "packages/api-workflow"
9
+ },
10
+ "author": "Ace Nyan <ace@acenyan.com>",
11
+ "bugs": {
12
+ "url": "https://github.com/AalisLabs/Aalis/issues"
13
+ },
14
+ "homepage": "https://github.com/AalisLabs/Aalis#readme",
15
+ "type": "module",
16
+ "main": "dist/index.js",
17
+ "types": "dist/index.d.ts",
18
+ "files": [
19
+ "dist"
20
+ ],
21
+ "devDependencies": {
22
+ "@types/node": "^22.0.0",
23
+ "typescript": "^5.7.0",
24
+ "@aalis/core": "0.10.0"
25
+ },
26
+ "aalis": {
27
+ "types": true
28
+ },
29
+ "peerDependencies": {
30
+ "@aalis/core": ">=0.2.0 <1.0.0"
31
+ },
32
+ "keywords": [
33
+ "aalis",
34
+ "aalis-api"
35
+ ],
36
+ "scripts": {
37
+ "build": "tsc",
38
+ "dev": "tsc --watch"
39
+ }
40
+ }