dsh-knj-workflow

dsh plugin --profile web add dsh-knj-workflow

dsh-knj-workflow

开发任务编排插件（DeepSeek Harness）：配置驱动的工作流 + 开发任务管理 + 可视化阶段进度。

📖 详细设计文档见 [DESIGN.md](./DESIGN.md)（架构、数据模型、Host/Client 设计、编排器、踩坑记录、验证记录）。

功能

• 工作流管理：可新增 N 个工作流，每个工作流由多个阶段组成；阶段行为由 prompt（提示词）+ 可选 skill 定义
• 模板导入/导出：工作流列表与图编辑器均支持把模板导出为 .workflow.json 文件、从文件导入（跨机器移植）；导入后先进入编辑器检查再保存，同 ID 冲突会提示
• 开发任务：创建任务并绑定工作流，自动启动执行
• 需求描述（可选，可长）：新建任务弹窗里需求描述是可选项——不填也能建任务；标题由系统依描述自动生成（首行前 50 字，空则时间戳占位），因此表单没有标题输入框。支持粘贴十万字级长文本；超过 8000 字的完整需求会随任务落盘 requirement.md，AI 节点 prompt 只注入头部摘录 + 文件指针（不丢内容、不炸上下文）。任务详情可展开查看/复制完整需求，看板搜索支持搜需求正文
• 内置通用附件（无需任何声明，推荐）：新建任务弹窗里永远有一个「附件（可选）」区，可一次多选若干本地文件（docx / md / 表格都行），也能逐个移除。Host 在启动前把它们落到 <工作目录>/.knj-inputs/<任务 id>/，并把换行拼接的绝对路径串写进 inputs.附件——节点 prompt 里写 ${inputs.附件} 拿到清单，自己写提示词解析文档。同名文件自动加序号（2-名字.ext）不覆盖；暂存失效时拒绝启动并报出文件名（不静默少文件）。支持最多 20 个附件，单文件上限 32MB。详见 [design/task-attachments.md](./design/task-attachments.md)
• 文件类型任务输入参数（声明式，只传路径）：编辑器里的「输入参数」声明参数（名称 / 显示名 / 必填 / 类型：文本｜文件）。文件类型的参数在新建任务时选文件：上传后由 Host 在启动前落到 <工作目录>/.knj-inputs/<任务 id>/，并把绝对路径写进 inputs.<参数名>——节点用 ${inputs.参数名} 拿到路径，文档解析由节点自己写提示词完成（不注入文件内容，也不塞进需求描述）。该目录自带 .gitignore（内容 *），默认不进用户版本库；单文件上限 32MB；未提交的上传暂存在 ~/.dsh/dev-orchestrator/uploads/，24 小时后自动清理
• 文件入参还支持「按路径引用」（给定时任务用）：同一参数可以只给一个路径（pathInputs）：相对路径按任务工作目录解析成绝对路径，且启动前校验文件确实存在——不存在就拒绝启动并报出参数名与路径（路径引用意味着每次触发读当时的文件，不做快照）。必填文件入参由「上传」或「路径」任一种满足；knjWorkflowScheduler.listWorkflows() 返回各工作流声明的入参，调用方据此渲染字段
• 可视化进度：右侧栏「开发任务」tab 横向步骤条展示每个阶段状态（待执行/运行中/完成/失败），实时刷新
• 阶段重跑 / 继续：失败的阶段可点击「重跑」，暂停/失败的任务可点击「继续」——基于断点持久化（每阶段结果落盘）
• 斜杠命令：/dev-task new <标题>、/dev-task list、/dev-task status <id>、/dev-task wf
• AI 助手对话配置（新）：在图编辑器里用自然语言改流程图——对话坞位于编辑器下半区（左=对话过程 / 右=指令输入），AI 返回「回复 + 编辑动作序列」，逐条校验后实时应用到画布草稿；整轮改动一次撤销，可查看推理/工具/正文流与 token 用量
• 定时调度集成（可选）：为 dsh-scheduler 提供进程内 knjWorkflowScheduler 服务；定时触发时按最新保存的流程定义创建并启动任务，历史可直达该任务详情
• UI 融入原生：左侧栏底部「新建任务」入口 + 右侧栏两个 tab（better-sidebar 扩展点），全部使用 DSH 原生设计令牌（--dsw-*）

架构

┌─ Client 端（lib/client.js）───────────────────────────────┐
│  左侧栏 sidebar.footer.action →「➕ 新建任务」              │
│  右侧栏 better-sidebar →「开发任务」「工作流」两个 tab        │
└──────────────┬──────────────────────────────────────────┘
               │ fetch('/devtask/...') 同源 HTTP
┌──────────────▼──────────────────────────────────────────┐
│  Host 端（lib/index.js）                                  │
│  DevTaskStore（JSON 持久化） + HTTP API + /dev-task 命令   │
│  WorkflowBridge：从 parent agent 作用域取 workflowEngine    │
│  （rc.8 起引擎位于 agent preset realm，非 host realm）      │
└──────────────┬──────────────────────────────────────────┘
               │ ctx.workflowEngine（script = lib/orchestrator.js）
┌──────────────▼──────────────────────────────────────────┐
│  编排器（lib/orchestrator.js）支持 resumeFrom / rerunStage │
│  每阶段子 agent 结果落盘 <taskDir>/stages/<stageId>.json   │
└─────────────────────────────────────────────────────────┘

数据目录（默认）：~/.dsh/dev-orchestrator/
  workflows.json                    # N 个工作流定义（含 inputs 声明：type = text | file）
  uploads/<uploadId>/<文件>          # 文件入参的**暂存**：表单打开时任务还没建，先落这里
                                    # （24h 自动清理；启动前物化进工作区并从暂存删除）
  tasks/<taskId>/task.json          # 任务元数据 + 阶段状态（需求描述全文存这里）
  tasks/<taskId>/requirement.md     # 仅当需求超 8000 字：完整需求全文，**启动前**统一写出
                                    # （落盘在 WorkflowBridge.startTask 完成，HTTP 路由 / 调度器 /
                                    #   /dev-task 命令 / 续跑 rerun+resume 全部入口都覆盖）
  tasks/<taskId>/stages/<stageId>.json  # 阶段断点产物

工作目录内（文件入参/附件的最终位置，按任务隔离）：
  <cwd>/.knj-inputs/.gitignore      # 内容 `*`：上传文件默认不进版本库
  <cwd>/.knj-inputs/<taskId>/<文件>  # 声明式入参：节点用 ${inputs.参数名} 拿路径
                                    # 内置附件：节点用 ${inputs.附件} 拿换行拼接的路径串

安装

dsh plugin --profile web add dsh-knj-workflow

npm 包 dsh-knj-workflow；安装后重启 dsh web 生效。dsh-scheduler 可独立安装；同时安装本插件后，调度器才会显示「KNJ 工作流」任务类型。

配置（可选，在 profile 的 cordis.patch.yml 中按 id knj-workflow 覆盖）：

键 · 默认 · 说明

dataRoot · ~/.dsh/dev-orchestrator · 数据存储目录（含 workflows.json、tasks/、uploads/、knj-host-debug.log）

httpPrefix · /devtask · HTTP API 前缀。改了不用动前端：客户端启动时向固定端点 GET /knj-workflow/meta 询问真实前缀（旧宿主无此端点时回退 /devtask）

orchestratorScript · 空 · 编排脚本源码文本（不是路径）；留空则读取 lib/orchestrator.js

HTTP API

方法 · 路径 · 说明

GET · /devtask/health · 健康检查（回 { ok, plugin, dataRoot }）

GET · /devtask/models · 可用 provider/model 列表（直接解析 ~/.dsh/settings.yaml，供新建任务下拉）

GET · /devtask/diag · 诊断：workflowEngine 在各层 agent scope 的可见性（排障用）

GET/POST/PUT · /devtask/workflows · 工作流列表 / 保存（POST 与 PUT 同为 upsert）

DELETE · /devtask/workflows/:id · 删除工作流

GET/POST · /devtask/tasks · 任务列表 / 创建（绑定工作流并启动）· GET 支持 ?archived=1 与 ?q=<关键词>（Host 侧按标题/需求正文/工作流 id 全文过滤；列表项不含需求正文，只给 descriptionChars）· POST 可带 fileInputs: { <参数名>: { uploadId, name } }（必填文件入参缺失 → 400）

GET · /devtask/tasks/:id · 任务详情（含阶段状态与需求描述全文）

DELETE · /devtask/tasks/:id · 删除任务（先取消运行中的 run，再删目录）

POST · /devtask/tasks/:id/start /cancel /resume · 启动 / 取消 / 继续（/resume 可带 { mode: 'resume' \ · 'rerun' }）

POST · /devtask/tasks/:id/rerun-stage · 重跑指定阶段（{ stageId }）

POST · /devtask/tasks/:id/decide · 人工审批：{ decision, feedback? }；decision 必须是该节点配置的去向 label（兼容旧值 approve/reject），仅 waiting-human 状态可调用

POST · /devtask/tasks/:id/archive /restore · 归档 / 恢复（写 / 删 archivedAt，不改变 status）

GET · /devtask/tasks/:id/stages/:stageId · 阶段断点产物

GET · /devtask/tasks/:id/results · 终态节点输出汇总（results.json）

GET · /devtask/tasks/:id/file?path=<相对路径> · 文件预览：限任务 cwd 内（relative + realpath 双重校验）；目录回 entries，>200KB 只回 meta

POST · /devtask/uploads · 文件入参上传暂存：{ name, dataBase64 } → { uploadId, name, size }；文件名先消毒成 basename（不可用 → invalid-name），单文件上限 32MB（file-too-large），失败 400 + { error, code }

POST · `/devtask/assis

…(truncated)