dsh-plugin-agentflow 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,89 @@
-# Temporary Holding Version
+# dsh-plugin-agentflow
 
-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.
+把 AgentFlow（物料画布式 agent 编排器）接进 DeepSeek Harness 的桌面插件：
+
+- 设置页 / 侧边栏嵌入画布界面（本地后端 `http://127.0.0.1:8791`）
+- 模型工具 `agentflow_list` / `agentflow_run`：看画布、跑画布
+- 引擎随插件分发（`runtime/`），装完即用，不需要单独安装 `~/.dsh/agent-flow`
+- 模型调用走 DSH 内核的 llm bridge（插件在 DSH 进程里起），不再自带 provider 凭据
+
+## 安装
+
+DSH 桌面版 → **设置 → 插件 → 添加插件**，然后二选一：
+
+- 输入 GitHub 仓库地址（例：`https://github.com/<owner>/dsh-plugin-agentflow`）
+- 输入本地目录（克隆下来的插件目录）
+
+DSH 会安装插件依赖并加载；侧边栏/设置页出现 AgentFlow 即成功，**不需要手动起服务、不需要构建前端**（仓库里已包含构建好的客户端与 `runtime/` 引擎）。
+
+## 首次启动会发生什么
+
+1. 插件用当前 DSH 的 Node 进程拉起 `runtime/server.mjs`（先探测 8791 端口，已在跑就不重复起；日志丢弃，不污染 DSH 终端）
+2. 后端监听 `127.0.0.1:8791`，数据目录默认 `~/.dsh/agent-flow-data`
+3. 若新数据目录不存在或为空，且旧目录 `~/.dsh/agent-flow/data` 里有 `board.json`，会自动把旧数据抄一份过来（只抄一次，旧文件保留不动）
+4. 新环境没有画布时，后端会自动建一张默认画布，打开页面即可看到
+
+## 数据目录
+
+默认：`~/.dsh/agent-flow-data/`
+
+```
+boards.json            # 画布索引
+boards/<id>.json       # 每张画布
+config.json            # 引擎配置（含密钥时权限 0600）
+drafts/                # 画布草稿
+data/dsh-bridge.json   # DSH llm bridge 的发现文件（进程级 token）
+```
+
+覆盖方式（优先级从高到低）：
+
+| 方式 | 例子 |
+| --- | --- |
+| 插件配置 `dataDir` | `{ "dataDir": "/path/to/data" }` |
+| 环境变量 `AGENTFLOW_DATA_DIR` | 启动 DSH 前 export |
+| 默认值 | `~/.dsh/agent-flow-data` |
+
+数据目录别放进插件安装目录：升级/重装插件会覆盖安装目录。
+
+## 依赖
+
+- DSH 0.2.x（插件依赖 `@deepseek-ai/dsh-tools ^0.2.1-rc.2`、`@deepseek-ai/cordis ^4.0.5`）
+- Node 22+（后端用到 `fetch`、`AbortSignal.timeout`、`fs.cp`）
+- 模型通道：引擎通过 DSH 内置的 llm bridge 调模型，需要 DSH 正在运行且插件已加载。DSH 没起 / 插件未加载时，画布仍能打开和编辑；关掉 mock 后跑图会失败，错误含「DSH 内核未连接」
+- 引擎默认是 mock 模式（返回假输出，不调用模型）；在画布设置里关掉 mock 才会真正调模型
+
+## 预设导出
+
+画布可导出成 DSH 预设，写入 `~/.dsh/profiles/<profile>/`（默认 profile 为 `desktop`）。
+
+- 换 profile：启动 DSH 前设置 `AGENTFLOW_PROFILE=<profile 名>`，后端子进程会继承
+- profile 目录不存在时导出接口返回 400，并提示具体路径
+
+## 开发
+
+```bash
+npm install
+npm run sync     # 把 ~/.dsh/agent-flow 的引擎快照进 runtime/（清空重建）
+npm run check    # node --check
+npm test         # bridge 自测
+npm run build    # 构建客户端 bundle（改了 src/client.tsx 才需要）
+```
+
+- `runtime/` 是 `npm run sync` 的生成物，不要手改；引擎更新后重新跑一次 sync
+- 开发时想直接改引擎源码，不必每次 sync：配 `agentflowDir` 或设 `AGENTFLOW_DIR=~/.dsh/agent-flow`，插件会改用该目录的引擎（此时 bridge 发现文件也写在该目录的 `data/` 下）
+- 同步源可用 `AGENTFLOW_SRC=/path/to/agent-flow npm run sync` 指定
+
+插件配置项：
+
+| 配置 | 说明 |
+| --- | --- |
+| `agentflowDir` | 引擎目录（开发用），覆盖自带 `runtime/` |
+| `agentflowPort` | 后端端口，默认 `8791`（界面目前固定连 8791，改端口需同步改客户端） |
+| `dataDir` | 数据目录，默认 `~/.dsh/agent-flow-data` |
+
+## 限制
+
+- 只在 macOS 上验证过；Windows 未测试（路径、进程管理可能还需适配）
+- 端口默认固定 `8791`；被别的实例占用时，探测到存活就复用，否则启动会失败（插件客户端的 iframe 也写死了 8791，改端口需要同时改客户端）
+- 一个 DSH 进程只托管一个自建后端；插件卸载时会杀掉自己拉起的那个，外部已在跑的不管
+- 引擎是插件版本快照：升级引擎需要重新 `npm run sync` 并发布新版本插件

package/cordis.patch.yml

@@ -0,0 +1,195 @@
+# dsh-plugin-agentflow 的 bundle patch：把 AgentFlow 的两个工具挂到 profile 上。
+#
+# 与其它 DSH 插件同样的形状 —— 用户的 profile patch 可以按 id 覆写这一行来改
+# agentflowDir（画布数据所在目录），不必复制整个插件配置。
+
+- insert:
+    - id: agentflow
+      name: 'dsh-plugin-agentflow'
+
+# >>> AgentFlow 预设（自动生成，重新导出会整体替换这段）
+# 本文件由 AgentFlow 自动生成，请勿手改 —— 重新生成会整体覆盖。
+# 来源画布：《AgentFlow》（id: demo）
+# 生成器：~/.dsh/agent-flow/preset-gen.mjs
+# 注意：delegation 组里的 tool-subagent 是分层下发子 agent 的唯一途径，不要删。
+
+- insert:
+  - id: preset-flow-agentflow
+    name: '@deepseek-ai/dsh-agent-preset'
+    config:
+      id: flow-agentflow
+      name: 'AgentFlow'
+      description: '由 AgentFlow 画布《AgentFlow》生成：6 个节点 / 5 层'
+      order: 50
+      plugins:
+        - id: persona
+          name: '@deepseek-ai/dsh-persona'
+          config:
+            prefix: |-
+              你是一个按固定流程组织子 agent 的调度者。
+
+              【你是谁】
+              你是「AgentFlow」。
+              这个流程共 6 个节点、5 层：大纲 → 对白版 / 下游卡片 → 人物版 → 合并 → 下游卡片。
+
+              【第一步：对齐需求】
+              动手前必须先把需求问清楚，最多问 3 个问题、一次问完：
+              - 这次的题材（主题）是什么？
+              - 期望的篇幅大概多少？
+              - 主要人物有哪些已有设定？
+              信息够了就说「开始执行」，不要边问边跑。
+
+              【流程】
+              第 1 层（串行）
+                ▸ 大纲 —— 根据给定的题材，写一个三幕剧的简要大纲，每幕两三句话用修仙类的。11
+                  完成标准：三幕结构清晰，每幕有一个明确转折.
+                  用模型：deepseek-flash
+                  参考技能：caveman、grill-me
+
+              第 2 层（并行，两个同时下发）
+                ▸ 对白版 —— 基于大纲，为关键场景写几句有张力的对白。
+                  完成标准：对白有潜台词，不要直白解释情绪
+                  用模型：deepseek-flash
+
+                ▸ 下游卡片
+                  完成标准：（未填写）
+                  用模型：deepseek-flash
+
+              第 3 层（等第 2 层全部完成）
+                ▸ 人物版 —— 基于大纲，塑造主要人物的动机与成长弧线。
+                  完成标准：主角有明确欲望、阻碍与转变
+                  用模型：deepseek-flash
+
+              第 4 层（等第 3 层全部完成）
+                ▸ 合并 —— 把两份材料合并成一份完整的三幕剧梗概，约 300 字。
+                  完成标准：读起来是一个连贯故事，不是拼接
+                  用模型：deepseek-flash
+
+              第 5 层（独立节点，可单独下发）
+                ▸ 下游卡片
+                  完成标准：（未填写）
+                  用模型：deepseek-flash
+
+              【怎么下发】
+              - 每个节点用一次 `subagent` 工具；prompt 里给全：任务 + 完成标准 + 上游产出
+              - 同一层的多个节点同时下发，不要一个个等
+              - 上游产出原样传给下游，不要自己改写或概括
+              - 子 agent 如果还有自己的子任务，把它的子任务一并写进它的 prompt，让它继续嵌套
+
+              【收尾】
+              全部跑完，把最终产出交给用户。中间有节点失败要说清楚是哪个、为什么，不要假装成功。
+        - id: agent-instructions
+          name: '@deepseek-ai/dsh-agent-instructions'
+          config:
+            maxBytes: 65536
+        - id: time-context
+          name: '@deepseek-ai/dsh-time-context'
+        - id: tool-bash
+          name: '@deepseek-ai/dsh-tool-bash'
+          disabled: !!js process.platform === 'win32'
+        - id: tool-pwsh
+          name: '@deepseek-ai/dsh-tool-pwsh'
+          disabled: !!js process.platform !== 'win32'
+        - id: tool-fs
+          name: '@deepseek-ai/dsh-tool-fs'
+        - id: tool-fs-search
+          name: '@deepseek-ai/dsh-tool-fs-search'
+          config:
+            sampleOverCapGlobResults: false
+        - id: tool-jobs
+          name: '@deepseek-ai/dsh-tool-jobs'
+        - id: tool-schedule
+          name: '@deepseek-ai/dsh-tool-schedule'
+        - id: skill-filesystem
+          name: '@deepseek-ai/dsh-skill-filesystem'
+        - id: tool-skill
+          name: '@deepseek-ai/dsh-tool-skill'
+        - id: command-goal
+          name: '@deepseek-ai/dsh-command-goal'
+        - id: tool-goal
+          name: '@deepseek-ai/dsh-tool-goal'
+        - id: planning
+          name: cordis:group
+          group: true
+          isolate:
+            planMode: true
+          config:
+            - id: plan-mode
+              name: '@deepseek-ai/dsh-plan-mode'
+              config:
+                section: |
+                  You are in plan mode. Stay in plan mode until the user approves your plan through exit_plan_mode or switches the session mode. Imperative language to implement changes means plan the implementation, not execute it. A user's conversational agreement — including an answer confirming something you asked — approves nothing and does not end plan mode; fold the confirmed decision into the plan and submit it through exit_plan_mode.
+
+                  Explore first. Use non-mutating reads, searches, static analysis, and checks to ground the plan in the actual repository. Do not edit or write files, change configuration, run formatters or code generation that rewrites tracked files, commit, or otherwise carry out the plan. Prefer existing functions and patterns over new machinery.
+
+                  The tool catalog stays the same across modes for request-cache stability. These plan-mode rules override any later tool description or guidance that suggests using mutation tools; those tools remain listed to keep the tool catalog unchanged. Do not use todo_write to track this planning phase: it tracks implementation after an approved plan, while the plan itself belongs in exit_plan_mode.
+
+                  Resolve discoverable facts by inspection. Use ask_user_question only for user-owned choices or material ambiguity that inspection cannot answer. Do not ask the user where code lives or how current behavior works when you can find out.
+
+                  Make the plan decision-complete: state the goal and success criteria; group implementation changes by subsystem; identify public API, schema, and data-flow changes; cover edge cases, failure modes, tests, acceptance criteria, and explicit assumptions. Keep it concise enough to review but detailed enough that another engineer can implement it without making design decisions.
+
+                  When ready, call exit_plan_mode with the complete plan markdown, starting with a # title. Make exit_plan_mode the only and final tool call in that assistant response: it presents the plan for approval, and implementation begins only in a later step after approval. Do not paste the final plan as a plain reply or ask "should I proceed?" through prose or ask_user_question. If review rejects it, incorporate the feedback and present again. If the review channel is unavailable or aborted, stay in plan mode and ask the user to switch modes manually; do not proceed with implementation.
+        - id: compaction
+          name: cordis:group
+          group: true
+          isolate:
+            compaction: true
+            toolResultPruner: true
+          config:
+            - id: compaction-basic
+              name: '@deepseek-ai/dsh-compaction-basic'
+            - id: command-compact
+              name: '@deepseek-ai/dsh-command-compact'
+            - id: tool-result-pruner
+              name: '@deepseek-ai/dsh-compaction-tool-result-pruner'
+              config:
+                thresholdChars: 8192
+                headChars: 4096
+                tailChars: 1024
+        - id: delegation
+          name: cordis:group
+          group: true
+          isolate:
+            workflowEngine: true
+          config:
+            - id: tool-subagent-control
+              name: '@deepseek-ai/dsh-tool-subagent-control'
+            - id: tool-subagent-list-agents
+              name: '@deepseek-ai/dsh-tool-subagent-control/list-agents'
+            - id: tool-subagent
+              name: '@deepseek-ai/dsh-tool-subagent'
+              config:
+                provider: spawn
+                toolName: subagent
+                modelSelectionSettings: true
+            - id: tool-subagent-fork
+              name: '@deepseek-ai/dsh-tool-subagent'
+              config:
+                provider: fork
+                toolName: subagent_fork
+            - id: workflow-ptc
+              name: '@deepseek-ai/dsh-workflow-ptc'
+              config:
+                provider: spawn
+            - id: tool-workflow
+              name: '@deepseek-ai/dsh-tool-workflow'
+        - id: tool-ask-user
+          name: '@deepseek-ai/dsh-tool-ask-user'
+        - id: tool-todo
+          name: '@deepseek-ai/dsh-tool-todo'
+          config:
+            allowParallelInProgress: true
+        - id: tool-web
+          name: '@deepseek-ai/dsh-tool-web'
+          config:
+            fetch: false
+            searchTimeoutMs: 60000
+        - id: present
+          name: '@deepseek-ai/dsh-tool-present'
+        - id: tool-plugin-manager
+          name: '@deepseek-ai/dsh-plugin-manager/tools'
+          disabled: true
+        - id: tool-plugin-market
+          name: '@deepseek-ai/dsh-plugin-market/tools'
+          disabled: true
+# <<< AgentFlow 预设结束