@sigmacamellia/dsh-dynamic-workflow 0.0.0-stage → 0.1.2

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,201 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction,
10
+ and distribution as defined by Sections 1 through 9 of this document.
11
+
12
+ "Licensor" shall mean the copyright owner or entity authorized by
13
+ the copyright owner that is granting the License.
14
+
15
+ "Legal Entity" shall mean the union of the acting entity and all
16
+ other entities that control, are controlled by, or are under common
17
+ control with that entity. For the purposes of this definition,
18
+ "control" means (i) the power, direct or indirect, to cause the
19
+ direction or management of such entity, whether by contract or
20
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
21
+ outstanding shares, or (iii) beneficial ownership of such entity.
22
+
23
+ "You" (or "Your") shall mean an individual or Legal Entity
24
+ exercising permissions granted by this License.
25
+
26
+ "Source" form shall mean the preferred form for making modifications,
27
+ including but not limited to software source code, documentation
28
+ source, and configuration files.
29
+
30
+ "Object" form shall mean any form resulting from mechanical
31
+ transformation or translation of a Source form, including but
32
+ not limited to compiled object code, generated documentation,
33
+ and conversions to other media types.
34
+
35
+ "Work" shall mean the work of authorship, whether in Source or
36
+ Object form, made available under the License, as indicated by a
37
+ copyright notice that is included in or attached to the work
38
+ (an example is provided in the Appendix below).
39
+
40
+ "Derivative Works" shall mean any work, whether in Source or Object
41
+ form, that is based on (or derived from) the Work and for which the
42
+ editorial revisions, annotations, elaborations, or other modifications
43
+ represent, as a whole, an original work of authorship. For the purposes
44
+ of this License, Derivative Works shall not include works that remain
45
+ separable from, or merely link (or bind by name) to the interfaces of,
46
+ the Work and Derivative Works thereof.
47
+
48
+ "Contribution" shall mean any work of authorship, including
49
+ the original version of the Work and any modifications or additions
50
+ to that Work or Derivative Works thereof, that is intentionally
51
+ submitted to Licensor for inclusion in the Work by the copyright owner
52
+ or by an individual or Legal Entity authorized to submit on behalf of
53
+ the copyright owner. For the purposes of this definition, "submitted"
54
+ means any form of electronic, verbal, or written communication sent
55
+ to the Licensor or its representatives, including but not limited to
56
+ communication on electronic mailing lists, source code control systems,
57
+ and issue tracking systems that are managed by, or on behalf of, the
58
+ Licensor for the purpose of discussing and improving the Work, but
59
+ excluding communication that is conspicuously marked or otherwise
60
+ designated in writing by the copyright owner as "Not a Contribution."
61
+
62
+ "Contributor" shall mean Licensor and any individual or Legal Entity
63
+ on behalf of whom a Contribution has been received by Licensor and
64
+ subsequently incorporated within the Work.
65
+
66
+ 2. Grant of Copyright License. Subject to the terms and conditions of
67
+ this License, each Contributor hereby grants to You a perpetual,
68
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
69
+ copyright license to reproduce, prepare Derivative Works of,
70
+ publicly display, publicly perform, sublicense, and distribute the
71
+ Work and such Derivative Works in Source or Object form.
72
+
73
+ 3. Grant of Patent License. Subject to the terms and conditions of
74
+ this License, each Contributor hereby grants to You a perpetual,
75
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
76
+ (except as stated in this section) patent license to make, have made,
77
+ use, offer to sell, sell, import, and otherwise transfer the Work,
78
+ where such license applies only to those patent claims licensable
79
+ by such Contributor that are necessarily infringed by their
80
+ Contribution(s) alone or by combination of their Contribution(s)
81
+ with the Work to which such Contribution(s) was submitted. If You
82
+ institute patent litigation against any entity (including a
83
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
84
+ or a Contribution incorporated within the Work constitutes direct
85
+ or contributory patent infringement, then any patent licenses
86
+ granted to You under this License for that Work shall terminate
87
+ as of the date such litigation is filed.
88
+
89
+ 4. Redistribution. You may reproduce and distribute copies of the
90
+ Work or Derivative Works thereof in any medium, with or without
91
+ modifications, and in Source or Object form, provided that You
92
+ meet the following conditions:
93
+
94
+ (a) You must give any other recipients of the Work or
95
+ Derivative Works a copy of this License; and
96
+
97
+ (b) You must cause any modified files to carry prominent notices
98
+ stating that You changed the files; and
99
+
100
+ (c) You must retain, in the Source form of any Derivative Works
101
+ that You distribute, all copyright, patent, trademark, and
102
+ attribution notices from the Source form of the Work,
103
+ excluding those notices that do not pertain to any part of
104
+ the Derivative Works; and
105
+
106
+ (d) If the Work includes a "NOTICE" text file as part of its
107
+ distribution, then any Derivative Works that You distribute must
108
+ include a readable copy of the attribution notices contained
109
+ within such NOTICE file, excluding those notices that do not
110
+ pertain to any part of the Derivative Works, in at least one
111
+ of the following places: within a NOTICE text file distributed
112
+ as part of the Derivative Works; within the Source form or
113
+ documentation, if provided along with the Derivative Works; or,
114
+ within a display generated by the Derivative Works, if and
115
+ wherever such third-party notices normally appear. The contents
116
+ of the NOTICE file are for informational purposes only and
117
+ do not modify the License. You may add Your own attribution
118
+ notices within Derivative Works that You distribute, alongside
119
+ or as an addendum to the NOTICE text from the Work, provided
120
+ that such additional attribution notices cannot be construed
121
+ as modifying the License.
122
+
123
+ You may add Your own copyright statement to Your modifications and
124
+ may provide additional or different license terms and conditions
125
+ for use, reproduction, or distribution of Your modifications, or
126
+ for any such Derivative Works as a whole, provided Your use,
127
+ reproduction, and distribution of the Work otherwise complies with
128
+ the conditions stated in this License.
129
+
130
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
131
+ any Contribution intentionally submitted for inclusion in the Work
132
+ by You to the Licensor shall be under the terms and conditions of
133
+ this License, without any additional terms or conditions.
134
+ Notwithstanding the above, nothing herein shall supersede or modify
135
+ the terms of any separate license agreement you may have executed
136
+ with Licensor regarding such Contributions.
137
+
138
+ 6. Trademarks. This License does not grant permission to use the trade
139
+ names, trademarks, service marks, or product names of the Licensor,
140
+ except as required for reasonable and customary use in describing the
141
+ origin of the Work and reproducing the content of the NOTICE file.
142
+
143
+ 7. Disclaimer of Warranty. Unless required by applicable law or
144
+ agreed to in writing, Licensor provides the Work (and each
145
+ Contributor provides its Contributions) on an "AS IS" BASIS,
146
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
147
+ implied, including, without limitation, any warranties or conditions
148
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
149
+ PARTICULAR PURPOSE. You are solely responsible for determining the
150
+ appropriateness of using or redistributing the Work and assume any
151
+ risks associated with Your exercise of permissions under this License.
152
+
153
+ 8. Limitation of Liability. In no event and under no legal theory,
154
+ whether in tort (including negligence), contract, or otherwise,
155
+ unless required by applicable law (such as deliberate and grossly
156
+ negligent acts) or agreed to in writing, shall any Contributor be
157
+ liable to You for damages, including any direct, indirect, special,
158
+ incidental, or consequential damages of any character arising as a
159
+ result of this License or out of the use or inability to use the
160
+ Work (including but not limited to damages for loss of goodwill,
161
+ work stoppage, computer failure or malfunction, or any and all
162
+ other commercial damages or losses), even if such Contributor
163
+ has been advised of the possibility of such damages.
164
+
165
+ 9. Accepting Warranty or Additional Liability. While redistributing
166
+ the Work or Derivative Works thereof, You may choose to offer,
167
+ and charge a fee for, acceptance of support, warranty, indemnity,
168
+ or other liability obligations and/or rights consistent with this
169
+ License. However, in accepting such obligations, You may act only
170
+ on Your own behalf and on Your sole responsibility, not on behalf
171
+ of any other Contributor, and only if You agree to indemnify,
172
+ defend, and hold each Contributor harmless for any liability
173
+ incurred by, or claims asserted against, such Contributor by reason
174
+ of your accepting any such warranty or additional liability.
175
+
176
+ END OF TERMS AND CONDITIONS
177
+
178
+ APPENDIX: How to apply the Apache License to your work.
179
+
180
+ To apply the Apache License to your work, attach the following
181
+ boilerplate notice, with the fields enclosed by brackets "[]"
182
+ replaced with your own identifying information. (Don't include
183
+ the brackets!) The text should be enclosed in the appropriate
184
+ comment syntax for the file format. We also recommend that a
185
+ file or class name and description of purpose be included on the
186
+ same "printed page" as the copyright notice for easier
187
+ identification within third-party archives.
188
+
189
+ Copyright 2026 dsh-dynamic-workflow contributors
190
+
191
+ Licensed under the Apache License, Version 2.0 (the "License");
192
+ you may not use this file except in compliance with the License.
193
+ You may obtain a copy of the License at
194
+
195
+ http://www.apache.org/licenses/LICENSE-2.0
196
+
197
+ Unless required by applicable law or agreed to in writing, software
198
+ distributed under the License is distributed on an "AS IS" BASIS,
199
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
200
+ See the License for the specific language governing permissions and
201
+ limitations under the License.
package/NOTICE.md ADDED
@@ -0,0 +1,42 @@
1
+ # NOTICE
2
+
3
+ `@sigmacamellia/dsh-dynamic-workflow`
4
+ Copyright 2026 dsh-dynamic-workflow contributors
5
+ Licensed under the Apache License, Version 2.0 (see [`LICENSE`](./LICENSE)).
6
+
7
+ ---
8
+
9
+ ## 1. Upstream Attribution — ZCode (Apache-2.0)
10
+
11
+ This project includes vendored, ported, and adapted code from **[ZCode](https://github.com/zai-org/ZCode)**, Copyright 2026 Z.AI Co., Ltd, licensed under the Apache License, Version 2.0 (original license text preserved at [`vendor/LICENSE-ZCode-Apache-2.0`](./vendor/LICENSE-ZCode-Apache-2.0)):
12
+
13
+ - **`vendor/dynamic-workflow/` and `vendor/dynamic-workflow-runtime/`** — Dynamic workflow compiler, static analyzer, execution engine, and sandbox runtime, vendored verbatim except for one documented modification in `vendor/dynamic-workflow-runtime/src/child-entry-file.ts` (redirects sandbox entry files from `.zcode/workflow-runs/` to `.dsh/workflow-runs/`, fallback `dsh-workflow-runs/`; see [`vendor/PATCHES.md`](./vendor/PATCHES.md)).
14
+ - **`src/journal/zcode/`**, **`src/service/import.ts`**, **`src/service/quota-resume.ts`**, **`src/world/world-read.ts`**, **`src/world/git-world-read.ts`**, **`src/display/graph-*.ts`**, **`src/shared/runs/`** — Ported from ZCode CLI / shared protocol modules with import paths, storage backends, and host types adapted for DeepSeek Harness.
15
+ - **`src/client/model/`** (including `src/client/model/timeline/spine-layout.ts`) and **`src/client/RunSpine.tsx`** — Ported and adapted from ZCode's timeline, workflow graph, and vertical spine UI models.
16
+ - **`skills/dynamic-workflows/`** — Adapted from ZCode's `dynamic-workflows` skill with DSH tool names, paths, and conventions.
17
+
18
+ All other files in this repository are original to `dsh-dynamic-workflow` and are licensed under Apache-2.0.
19
+
20
+ ### Relevant Operational Notices Retained from Upstream ZCode `NOTICE.md`
21
+
22
+ In accordance with Section 4(d) of the Apache License, Version 2.0, the following operational and safety disclosures from upstream ZCode's `NOTICE.md` that pertain to the workflow runtime are retained here:
23
+
24
+ - **AI Output & Execution Boundaries**: AI-generated workflow scripts, commands, files, and analyses may contain errors, omissions, or security issues. Always review the workflow script, target workspace, and side effects in the confirmation card before approving execution, and maintain recoverable backups.
25
+ - **Host Execution & Subagents**: Workflow scripts (`world.run`) and subagents execute under the permissions of the host OS user running DeepSeek Harness. Subagents and background workflow runs can continue issuing LLM requests, running commands, and producing workspace or external side effects; stopping a run or closing the UI does not roll back already-completed file writes or external operations.
26
+ - **Local Persistence & Credentials**: Workflow journals, drafts, sandbox entry files, and artifacts are stored locally under `<cwd>/.dsh/` and `$DSH_HOME/state/dynamic-workflow/` and may contain prompts, source code, and tool outputs. Never commit real credentials or private session exports to public repositories.
27
+ - **Third-Party Rights**: The Apache-2.0 license granted on first-party code does not add rights on behalf of third-party copyright holders and does not guarantee parity with official ZCode or DeepSeek Harness products.
28
+
29
+ ---
30
+
31
+ ## 2. Bundled Third-Party Components
32
+
33
+ The compiled distribution bundle (`lib/index.js`, full legal headers in `lib/index.js.LEGAL.txt`) bundles the following open-source libraries:
34
+
35
+ - **TypeScript** — Copyright (c) Microsoft Corporation. Licensed under the Apache License, Version 2.0.
36
+ - **Zod** — Copyright (c) 2020 Colin McDonnell. Licensed under the MIT License.
37
+
38
+ ---
39
+
40
+ ## 3. Trademark & Non-Affiliation Notice
41
+
42
+ In accordance with Section 6 of the Apache License, Version 2.0, this project is an **independent, unofficial community plugin**. It is not affiliated with, sponsored by, or endorsed by **DeepSeek** (DeepSeek Harness) or **Z.AI Co., Ltd / Zhipu AI** (ZCode). All product names, logos, and trademarks are the property of their respective owners and are used solely to identify compatibility and upstream origin.
package/README.md CHANGED
@@ -1,3 +1,313 @@
1
- # Temporary Holding Version
1
+ <div align="center">
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ <img src="https://raw.githubusercontent.com/LoneSigma1998/dsh-dynamic-workflow/main/icon.svg" alt="dsh-dynamic-workflow logo" width="68" height="68" />
4
+
5
+ # dsh-dynamic-workflow
6
+
7
+ **面向 DeepSeek Harness(DSH)的强类型 TypeScript 多代理动态工作流插件**
8
+
9
+ *Typechecked TypeScript multi-agent dynamic workflow plugin for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness), ported from [ZCode](https://github.com/zai-org/ZCode) (Apache-2.0).*
10
+
11
+ [![npm version](https://img.shields.io/npm/v/%40sigmacamellia%2Fdsh-dynamic-workflow?color=cb3837&logo=npm)](https://www.npmjs.com/package/@sigmacamellia/dsh-dynamic-workflow)
12
+ [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE)
13
+ [![Node.js >= 24.9](https://img.shields.io/badge/node-%3E%3D24.9-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
14
+ [![DSH >= 0.2.2-rc.3](https://img.shields.io/badge/DSH-%3E%3D0.2.2--rc.3-4f46e5)](https://github.com/deepseek-ai/deepseek-harness)
15
+ [![Publish to npm](https://github.com/LoneSigma1998/dsh-dynamic-workflow/actions/workflows/publish.yml/badge.svg)](https://github.com/LoneSigma1998/dsh-dynamic-workflow/actions/workflows/publish.yml)
16
+
17
+ [快速开始](#快速开始) · [核心特性](#核心特性) · [界面预览](#界面预览) · [配置参考](#配置参考) · [DSH 原生增强](#dsh-原生增强) · [安全与限制](#安全边界与已知限制) · [开发与测试](#开发与测试) · [协议与致谢](#开源协议致谢与免责声明)
18
+
19
+ </div>
20
+
21
+ > [!NOTE]
22
+ > 本项目为**非官方社区插件**,基于 [ZCode](https://github.com/zai-org/ZCode) 的 Apache-2.0 开源动态工作流引擎移植,并针对 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的可编程 Agent Loop 与插件体系做了原生重构与增强。与 DeepSeek 或 Z.AI / ZCode 官方无隶属或背书关系。
23
+
24
+ ---
25
+
26
+ ## 简介
27
+
28
+ 让主代理不再只能线性调用工具,而是针对一套精简的强类型 Facade 编写 **TypeScript 编排脚本**(`agent()`、`.ask<T>()`、`files.*`、`git.*`、`world.run`、`report()`、`artifact.*`、`phase()`、`hole<T>()`):
29
+
30
+ ```mermaid
31
+ flowchart LR
32
+ A["主代理编写 TS 编排脚本"] --> B["Host 类型检查 & 静态阶段图"]
33
+ B --> C["用户确认 / 调整并发与模型"]
34
+ C --> D["沙箱子进程运行工作流"]
35
+ D --> E["并行 DSH 子代理 & SQLite Journal"]
36
+ E --> F["右侧栏竖向 Spine & 实时看板"]
37
+ E --> G["终态 / 升级 / 留白通知回传主代理"]
38
+ ```
39
+
40
+ - **先验后跑**:Host 内置 TypeScript 编译器,先做完整类型检查并抽出静态阶段图,交由用户确认(可在确认卡上直接调整并发数和子代理模型,或打回修订)。
41
+ - **真·子代理 & 可恢复持久化**:每个子代理都是独立的 DSH 子会话;每一步执行状态与结果持久化至 SQLite Journal,支持**中断续跑(Resume)**、**带缓存修订(Amend)**、**中途留白补全(Hole)**与**升级提问(Escalation)**。
42
+ - **开箱即用**:编译产物自带打包好的 Host 半(`lib/index.js`)与 Web/Desktop 半(`lib/client.js`),与 DSH 内置的 `workflow`(纯 JS PTC 编排工具)工具名完全独立、互不冲突。
43
+
44
+ ---
45
+
46
+ ## 核心特性
47
+
48
+ - **强类型 TypeScript 编排**:提供结构化输出 `.ask<T>()`、显式阶段 `phase()`、多路并行扇出、跨运行复用存档(Saved Workflows)与只读代码片段求值(`eval_workflow_snippet`)。
49
+ - **SQLite 持久化 Journal**:支持进程崩溃 / 重启 / 额度耗尽后的断点续跑,以及带前缀缓存复用的热修订(Amend);支持运行中途留白 `hole<T>()` 与升级提问。
50
+ - **实时可视化与预设数据看板**:Web / Desktop 端内置工具卡、确认卡、独立 Turn 级运行卡、状态通知条与右侧栏**竖向 Spine 阶段轨**;支持 `artifact.chart` / `table` / `metrics` / `board` 增量实时渲染。
51
+ - **DSH 原生深度增强**:Turn 边界闸门、Headless 保活、`<workflow-runs>` 增量上下文投影、进程级 AIMD 限流、写操作追踪、只读子代理 Persona 策略、前向兼容的 `ignorable` 进度记录。
52
+ - **完整可追溯**:每个子代理的完整对话与文件改动 diff(`+行 / -行`)均可直接在 Web / Desktop 侧栏点开审查。
53
+
54
+ ---
55
+
56
+ ## 快速开始
57
+
58
+ ### 环境要求
59
+
60
+ - **Node.js** `>= 24.9.0`
61
+ - **DeepSeek Harness (DSH)** `>= 0.2.2-rc.3`
62
+
63
+ ### 安装方式一:Desktop 桌面端(推荐)
64
+
65
+ 无需配置任何 Token 或 `.npmrc`,直接在 DSH 桌面应用左侧栏打开 **Plugins → Add plugin**,输入包名即可安装:
66
+
67
+ ```text
68
+ @sigmacamellia/dsh-dynamic-workflow
69
+ ```
70
+
71
+ 安装后即可在 Plugin Manager 中自动检测新版本并一键更新。
72
+
73
+ ### 安装方式二:CLI / Web / TUI / Headless
74
+
75
+ ```sh
76
+ dsh plugin --profile web add @sigmacamellia/dsh-dynamic-workflow
77
+ ```
78
+
79
+ > 同样适用于 `--profile tui` 或 `--profile headless`;升级时直接运行 `dsh plugin --profile web update @sigmacamellia/dsh-dynamic-workflow`(或通过桌面端 Plugin Manager 更新)。
80
+
81
+ <details>
82
+ <summary>安装方式三:从本地源码构建安装(适合二次开发)</summary>
83
+
84
+ ```sh
85
+ git clone https://github.com/LoneSigma1998/dsh-dynamic-workflow.git
86
+ cd dsh-dynamic-workflow
87
+ npm install
88
+ npm run build
89
+ dsh plugin --profile web add "$(pwd)"
90
+ ```
91
+
92
+ > 桌面端可在 **Plugins → Add plugin** 中填入本地仓库的绝对路径。
93
+
94
+ </details>
95
+
96
+ ### 开始使用
97
+
98
+ 安装并启用插件后,在任意会话中:
99
+
100
+ - 直接输入 **`/workflow 深度审查 src/ 目录下的并发与错误处理逻辑`**
101
+ - 或直接用自然语言告诉主代理:**“用工作流帮我分析这个仓库的架构并输出报告”**
102
+
103
+ ---
104
+
105
+ ## 界面预览
106
+
107
+ 以下截图均采自真实 DSH Web 与真实模型运行:
108
+
109
+ <table>
110
+ <tr>
111
+ <td width="50%" valign="top">
112
+ <img src="https://raw.githubusercontent.com/LoneSigma1998/dsh-dynamic-workflow/main/docs/screenshots/08-confirm-settings.png" alt="确认卡:静态阶段图与并发/模型内联调整" />
113
+ <p align="center"><sub><b>确认卡</b>:静态阶段图、脚本预览,支持内联调整并发数与子代理模型(改动可一键还原)</sub></p>
114
+ </td>
115
+ <td width="50%" valign="top">
116
+ <img src="https://raw.githubusercontent.com/LoneSigma1998/dsh-dynamic-workflow/main/docs/screenshots/09-run-pane-changes-steps.png" alt="运行面板:子代理改动与脚本步骤" />
117
+ <p align="center"><sub><b>右侧栏运行面板</b>:子代理文件改动 diff(+行 / −行)与脚本文件/命令步骤追踪</sub></p>
118
+ </td>
119
+ </tr>
120
+ </table>
121
+
122
+ <p align="center">
123
+ <img src="https://raw.githubusercontent.com/LoneSigma1998/dsh-dynamic-workflow/main/docs/screenshots/06-big-run-page.png" alt="71 个任务大工作流完成后的运行卡与运行面板" />
124
+ <br />
125
+ <sub><b>中大型任务实测</b>:71 个任务、4 个阶段的并行代码审查运行卡与右侧栏详情面板</sub>
126
+ </p>
127
+
128
+ ### 界面组件一览
129
+
130
+ - **工具卡**(`create_workflow` / `amend_workflow`):模型流式编写脚本时,阶段随 `phase("…")` 实时落轨;类型检查失败直接展示诊断信息。
131
+ - **确认卡**:展示静态阶段图、并发数、子代理模型及完整脚本;支持 **运行 / 本会话始终允许 / 拒绝 / 提修改意见**,且可直接在卡上微调并发与模型。
132
+ - **运行卡**:作为独立的 Turn 级对话节点(`groupTree: 'turn'`)常驻对话流(不随工具调用折叠),实时脉动展示运行进度,重启 Host 后可从持久化记录无损恢复。
133
+ - **状态通知条**:主代理收到的 `<task-notification>`、升级提问、留白补全折叠为可展开单行状态条;子代理会话内明确标识为“工作流任务”。
134
+ - **右侧栏运行面板**(可从顶部会话栏“工作流”按钮随时打开):
135
+ - **竖向 Spine 阶段轨**:含并行分支轨道、分叉/汇合接头、阶段折叠、每阶段最多钉住 5 个子代理药丸 + 可展开分组名册(大扇出不撑爆侧栏),点击任意子代理即可直达完整子会话。
136
+ - **产物与预设看板**:支持 Markdown / 文本 / 图片内联预览与文件下载;`artifact.chart` / `table` / `metrics` / `board` 通过增量游标从 `report(item, id)` 实时渲染(折线/柱状/散点、线性/对数坐标、指标卡、去重表格、状态看板)。
137
+ - **脚本步骤 / 子代理改动 / 运行时配置**:支持查看脚本读了什么、跑了什么命令,按子代理查看文件 diff;运行中调整并发原地生效,调整模型自动开启带缓存复用的修订运行。
138
+ - **工作流列表页**:汇总本会话运行、按会话切换触发策略(`routing`),以及全局 / 项目级存档工作流(支持一键直跑,免经模型、免二次确认)。
139
+
140
+ ---
141
+
142
+ ## 命令、工具与存储路径
143
+
144
+ ### 斜杠命令
145
+
146
+ | 命令 | 说明 |
147
+ |---|---|
148
+ | `/workflow <任务描述>` | 启动工作流(在 `onDemand` 模式下同时激活工作流工具集) |
149
+ | `/dwf list` | 列出当前会话的所有工作流运行 |
150
+ | `/dwf stop <run_id>` | 停止指定运行中的工作流(同时终止其挂起的子代理与 `world.run` 子进程) |
151
+ | `/dwf resume <run_id>` | 从 SQLite Journal 恢复已停止或中断的运行 |
152
+ | `/dwf routing <explicit\|suggest\|auto>` | 为当前会话切换工作流触发策略(持久化在会话记录中) |
153
+
154
+ ### 注册的 Agent 工具
155
+
156
+ | 类别 | 工具名 |
157
+ |---|---|
158
+ | 生命周期控制 | `create_workflow`、`amend_workflow`、`resume_workflow_run`、`stop_workflow_run` |
159
+ | 中途交互 | `fill_workflow_hole`、`resolve_workflow_question` |
160
+ | 查询与观测 | `get_workflow_run`、`list_workflow_runs` |
161
+ | 存档与轻量求值 | `save_workflow`、`list_saved_workflows`、`eval_workflow_snippet` |
162
+
163
+ ### 本地存储位置
164
+
165
+ | 数据 | 路径 |
166
+ |---|---|
167
+ | 工作流草稿 | `<cwd>/.dsh/workflow-drafts/` |
168
+ | 沙箱入口文件 | `<cwd>/.dsh/workflow-runs/`(不可写时回落至系统临时目录) |
169
+ | 存档工作流 | `<cwd>/.dsh/workflows/`(项目级)与 `$DSH_HOME/workflows/`(全局) |
170
+ | SQLite Journal 与产物 | `$DSH_HOME/state/dynamic-workflow/` |
171
+
172
+ ---
173
+
174
+ ## 配置参考
175
+
176
+ 安装后会自动通过 `cordis.patch.yml` 注册为 `dynamic-workflow` 插件节点。你可以在 `$DSH_HOME/profiles/<profile>/cordis.patch.yml` 中按需调整:
177
+
178
+ ```yaml
179
+ - id: dynamic-workflow
180
+ name: '@sigmacamellia/dsh-dynamic-workflow'
181
+ config:
182
+ confirm: ask
183
+ holdTurnWhileRunning: false
184
+ skillGate: true
185
+ defaultMaxConcurrency: 8
186
+ readOnlySubagents: ['reviewer*']
187
+ governor: { initial: 8 }
188
+ quotaAutoResume: true
189
+ mode: alwaysOn
190
+ routing: explicit
191
+ resultSchema: exact
192
+ ```
193
+
194
+ | 选项 | 默认值 | 说明 |
195
+ |---|---|---|
196
+ | `confirm` | `'ask'` | 启动确认策略:`ask`(每次确认)、`never`(无头/自动模式)、`ask-or-allow` |
197
+ | `holdTurnWhileRunning` | `false` | 面向 Headless / SDK:设为 `true` 时,在工作流结束前保持主代理 Turn 不关闭,使升级提问、留白和终态通知在同一 Turn 内送达 |
198
+ | `skillGate` | `true` | 要求模型先加载内置 `dynamic-workflows` Skill 再提交脚本,显著提升编排质量 |
199
+ | `defaultMaxConcurrency` | 按 CPU `2–16` | 默认最大子代理并发数 |
200
+ | `readOnlySubagents` | `[]` | 按 Persona 名称通配(如 `['reviewer*']`)限制子代理仅获得只读工具集 |
201
+ | `governor` | `{ initial: 8 }` | 进程级 AIMD 限流治理器(按 `provider/model` 分桶,遇 429 自动降并发);设为 `false` 关闭 |
202
+ | `quotaAutoResume` | `true` | 因额度耗尽暂停的运行在额度重置后自动续跑(支持中英文额度耗尽提示识别) |
203
+ | `mode` | `'alwaysOn'` | 工具暴露模式:`alwaysOn`(常驻)、`onDemand`(输入 `/workflow` 前不暴露工具)、`disabled` |
204
+ | `routing` | `'explicit'` | 触发引导策略:`explicit`(仅明确要求时)、`suggest`(先评估方案与成本再征求同意)、`auto`(实质性复杂任务默认启用);支持通过 `/dwf routing` 或侧栏按会话覆盖 |
205
+ | `resultSchema` | `'exact'` | 结构化输出 Schema 传递方式:`exact`(原样下发)或 `relaxed`(降级至 DSH 子集以兼容受限网关) |
206
+
207
+ ---
208
+
209
+ ## DSH 原生增强
210
+
211
+ 在完整移植 ZCode 引擎的基础上,结合 DeepSeek Harness 的可编程 Hook 与插件能力实现了以下原生增强:
212
+
213
+ | 增强能力 | 实现机制 |
214
+ |---|---|
215
+ | **Turn 边界闸门** | 基于 `agent/turn-stopping`:主代理试图结束 Turn 但仍欠某运行一个升级回答或留白补全时,精确注入一次 `<workflow-blocked>` 提醒,不依赖轮询定时器 |
216
+ | **Headless 保活** | `holdTurnWhileRunning` 让非交互场景在同一 Turn 内完整接住升级、留白与终态结果 |
217
+ | **零轮询状态投影** | 通过 `systemPrompt.context` 增量注入 `<workflow-runs>`(仅状态变化时重发),主代理始终感知活跃运行 |
218
+ | **进程级 AIMD 限流** | 在 `llm/stream` 层按 `provider/model` 分桶控流,遇 429 自动退避且保障主代理请求优先不排队 |
219
+ | **写操作追踪与安全缓存** | `tools/pre-execute` 精确记录子代理工具调用与文件写入,Amend 缓存导入在首次写入工作区处安全截断 |
220
+ | **只读子代理策略** | 支持按 Persona 名称强制裁剪为只读工具集,避免审查类子代理误改代码 |
221
+ | **前向兼容持久化** | 运行进度以 `ignorable` 插件记录(`appendPluginRecord`)写入会话,任意版本 DSH 均可无损重开会话 |
222
+ | **子代理即原生子会话** | 每个子代理都是带 `subagent/descriptor` 的原生子会话,可在 Web / Desktop 直接打开完整轨迹并随会话持久化 |
223
+
224
+ ---
225
+
226
+ ## 实测表现与对照实验
227
+
228
+ <details>
229
+ <summary><b>中大型任务实测:让工作流审查本插件自身 <code>src/</code>(71 个任务,9 次跨重启续跑)</b></summary>
230
+
231
+ 在真实 DSH Web 中让模型“用工作流深度审查本仓库 `src/`”:
232
+
233
+ - 模型生成 4 阶段脚本:按目录分组初审(15 个子代理)→ 逐条独立证伪复核(53 个子代理)→ 去重排序 → 汇总报告。
234
+ - 共 **71 个任务**、并发 **16**、累计 **24.7M tokens**;中途 Host 因环境限时重启约 **9 次**,每次均从 SQLite Journal 无损续跑并从缓存重放已完成任务。
235
+ - 最终定位 32 个真实问题(3 高 / 14 中 / 15 低,详见 [`docs/reviews/2026-11-18-src-deep-review.md`](./docs/reviews/2026-11-18-src-deep-review.md)),高危与中危已全部修复并补充回归测试。
236
+
237
+ **实践建议**:Token 消耗主要取决于扇出粒度;确认卡会展示静态任务数,若单条发现拆出过多复核子代理,可在确认前使用**“提修改意见”**让模型合并复核批次。
238
+
239
+ </details>
240
+
241
+ <details>
242
+ <summary><b>A/B 对照实验(单代理 vs 动态工作流)</b></summary>
243
+
244
+ 在埋入 14 个 bug 与 5 个诱饵的小型代码库上对比测试(详见 [`docs/eval/2026-11-18-ab-review.md`](./docs/eval/2026-11-18-ab-review.md)):
245
+
246
+ - 两组均命中 10–11 个埋入 bug,且均无诱饵误报;
247
+ - 工作流组额外发现 1–3 个未埋设的真实边界问题;
248
+ - 代价约为单代理的 15–25 倍 Token 与 4–5 倍耗时。
249
+
250
+ **结论**:单次上下文就能装下的小型任务直接用主代理更划算;动态工作流更适合跨多目录大规模审查、并行重构、批量验证或需要断点续跑与独立子代理视角的复杂任务。
251
+
252
+ </details>
253
+
254
+ ---
255
+
256
+ ## 安全边界与已知限制
257
+
258
+ > [!WARNING]
259
+ > - **`world.run` 执行边界**:编排脚本中通过 `world.run` 调用的命令由插件自身执行端口在宿主进程权限下运行(与 ZCode 一致),**不经过 DSH 的沙箱策略**。请务必在确认卡中审阅脚本内容后再批准运行。
260
+ > - **“只读”角色需硬约束**:仅靠 Prompt 声明“只读审查员”在 `workspace-write` 模式下仍可能写入文件或执行 Shell。如需严格只读,请切换会话至只读模式或配置 `readOnlySubagents`。
261
+
262
+ - **确认卡隔离**:`save_workflow` 与 `eval_workflow_snippet` 始终禁用“本会话始终允许”,与工作流启动确认严格隔离,避免一次授权意外放行后续脚本保存或任意命令片段求值。
263
+ - **产物预览安全**:HTML 与 SVG 产物仅展示源码,不在前端直接渲染;预览接口仅返回纯文本或位图,并附带沙箱 CSP 响应头。
264
+ - **子代理会话模型**:子代理对话为一次性只读轨迹记录;续跑与修订通过 SQLite Journal 重放驱动,而非在子代理对话内继续追加消息。
265
+
266
+ ---
267
+
268
+ ## 开发与测试
269
+
270
+ 离线集成测试直接连接同级目录的 `../deepseek-harness` 源码运行真实 DSH(可通过 `DSH_REPO` 环境变量覆盖路径):
271
+
272
+ ```sh
273
+ npm run typecheck # Host + Web 双端 TypeScript 类型检查
274
+ npm run build # 构建 lib/index.js(含内置 TS 编译器)与 lib/client.js
275
+ npm test # 13 套核心与集成测试(引擎、限流、加固回归、续跑、wire 级端到端、审计回归等)
276
+ npm run test:bundle # 针对打包产物 lib/index.js 运行集成与 wire 测试
277
+ npm run test:client # 按 Web Shell 方式加载 lib/client.js 并验证组件渲染
278
+ npm run test:vendor # ZCode 引擎 2,037 个 vitest 用例 + 83 个 SQLite Journal 契约测试
279
+ ```
280
+
281
+ <details>
282
+ <summary>真实模型端到端测试与自动发布流程</summary>
283
+
284
+ **真实端到端测试**(需配置 `.env`,参见 `.env.example`):
285
+
286
+ ```sh
287
+ cp .env.example .env
288
+ DWF_E2E_INSTALL=1 npm run test:live
289
+ node tests/e2e/web-live.mjs <work-dir> <screenshots-dir>
290
+ ```
291
+
292
+ **自动发布到 npm(GitHub Actions)**:
293
+
294
+ 仓库已配置 [`.github/workflows/publish.yml`](./.github/workflows/publish.yml)(启用 npm Provenance 供应链校验)。发布新版本只需:
295
+
296
+ ```sh
297
+ npm version patch # 或 minor / major
298
+ git push origin main --follow-tags
299
+ ```
300
+
301
+ 推送 `v*` 标签后,GitHub Actions 会自动校验版本一致、构建 Host/Web 产物、运行引擎与 Journal 契约测试,并发布 `@sigmacamellia/dsh-dynamic-workflow` 到公开 npm Registry。
302
+
303
+ </details>
304
+
305
+ ---
306
+
307
+ ## 开源协议、致谢与免责声明
308
+
309
+ - **开源协议**:本项目基于 [**Apache License 2.0**](./LICENSE) 开源。
310
+ - **上游致谢**:
311
+ - 感谢 [**ZCode**](https://github.com/zai-org/ZCode)(Copyright 2026 Z.AI Co., Ltd,Apache-2.0)开源的高质量动态工作流编译器、静态分析器、执行引擎、沙箱运行时与前端模型。完整的归属清单、修改说明与第三方组件声明见 [`NOTICE.md`](./NOTICE.md)、[`vendor/LICENSE-ZCode-Apache-2.0`](./vendor/LICENSE-ZCode-Apache-2.0) 及 [`vendor/PATCHES.md`](./vendor/PATCHES.md)。
312
+ - 感谢 [**DeepSeek Harness (DSH)**](https://github.com/deepseek-ai/deepseek-harness) 提供的可扩展插件与可编程 Agent Loop 架构。
313
+ - **免责与商标声明**:本项目为独立的社区开源插件,与 DeepSeek、Z.AI / 智谱 AI(ZCode)无官方合作、赞助或背书关系;相关产品名称与商标均归各自权利人所有,仅用于说明兼容性与代码来源。
@@ -0,0 +1,14 @@
1
+ # Installs the plugin into the active profile: the Host half (lib/index.js —
2
+ # tools, runtime, journal, routes, projection) and, because the package
3
+ # declares `dsh.client.platform: web` with a `./client` export, the Web half
4
+ # (lib/client.js — tool cards, confirm card, run panel) from the same entry.
5
+ #
6
+ # DSH's own `workflow` tool (tool-workflow, plain-JS PTC orchestration script) is a
7
+ # different feature and stays enabled; the two do not share tool names.
8
+ - insert:
9
+ - id: dynamic-workflow
10
+ name: '@sigmacamellia/dsh-dynamic-workflow'
11
+ config:
12
+ # ask: confirm every launch (Allow / Always allow in this session / Deny / Refine)
13
+ confirm: ask
14
+ skillGate: true
package/icon.svg ADDED
@@ -0,0 +1,22 @@
1
+ <svg width="36" height="36" viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg">
2
+ <defs>
3
+ <linearGradient id="dwf-grad" x1="7" y1="7" x2="29" y2="29" gradientUnits="userSpaceOnUse">
4
+ <stop stop-color="#60A5FA" />
5
+ <stop offset="1" stop-color="#4F46E5" />
6
+ </linearGradient>
7
+ <mask id="dwf-center-cut">
8
+ <rect width="36" height="36" fill="#FFFFFF" />
9
+ <circle cx="18" cy="18" r="2.3" fill="#000000" />
10
+ </mask>
11
+ </defs>
12
+ <g mask="url(#dwf-center-cut)">
13
+ <path d="M11 10.5C15 10.5 14.5 18 18 18C21.5 18 21 10.5 25 10.5" stroke="url(#dwf-grad)" stroke-width="2.2" stroke-linecap="round" />
14
+ <path d="M11 10.5V25.5" stroke="url(#dwf-grad)" stroke-width="2.2" stroke-linecap="round" />
15
+ <path d="M11 25.5C15 25.5 14.5 18 18 18C21.5 18 21 25.5 25 25.5" stroke="url(#dwf-grad)" stroke-width="2.2" stroke-linecap="round" />
16
+ <circle cx="11" cy="10.5" r="3" fill="url(#dwf-grad)" />
17
+ <circle cx="11" cy="25.5" r="3" fill="url(#dwf-grad)" />
18
+ <circle cx="25" cy="10.5" r="3" fill="url(#dwf-grad)" />
19
+ <circle cx="25" cy="25.5" r="3" fill="url(#dwf-grad)" />
20
+ <circle cx="18" cy="18" r="4.2" fill="url(#dwf-grad)" />
21
+ </g>
22
+ </svg>