gyxx-flow/workbench

GYXX 智能工作台（deepseek-harness 集成）

以 deepseek-harness（dsh，DeepSeek 智能体底座） 为 agent 运行时，把 gyxx-flow 的现有工作流以插件形式扩展进 dsh Web UI，形成一个 可监控、可启动、可智能诊断/修复工作流的智能工作台。

┌──────────────────────── dsh Web UI（DeepSeek 智能体）────────────────────────┐
│  侧边栏「工作流」面板 ───────────────┐                                       │
│  （插件客户端包 shell.overlay 抽屉）   │   对话：选中工作流后提问 / 诊断 / 修复     │
└─────────┬────────────────────────────┴───────────────────▲─────────────────┘
          │ 本机回环桥接 127.0.0.1:8790                     │ 7 个工作流工具
┌─────────▼─────────────────────────────────────────────────┴─────────────────┐
│            gyxx-workbench 宿主插件（workbench/plugin/gyxx-workbench.mjs）      │
│   工具注册 · 系统提示词 · 失败监控器 · 桥接服务 · 会话创建                       │
└─────────┬────────────────────────────────────────────────────────────────────┘
                      │ HTTP（只读 + 受控写）
┌─────────▼─────────────────────────────────────────┐
│  gyxx console（127.0.0.1:8765，gyxx-flow 现有控制台） │
│  /api/overview · /api/workflows/* · /api/dynamic-configs │
└─────────┬─────────────────────────────────────────┘
┌─────────▼─────────────────────────────────────────┐
│  gyxx-flow 工作流引擎（LangGraph）· 调度器 · RunJournal │
└───────────────────────────────────────────────────┘

快速开始

前置条件：Python 3.12 + uv sync 已完成；Node.js 22.19+；一个 DeepSeek API Key （DEEPSEEK_API_KEY，dsh 自身要求）。

# Windows：渲染补丁、拉起控制台（注入云端凭据）、启动 dsh Web UI
powershell -File workbench\bin\start-workbench.ps1

# 控制台凭据文件不是默认路径时
powershell -File workbench\bin\start-workbench.ps1 -ConsoleEnvFile <你的.env 路径>

# Linux/macOS
bash workbench/bin/start-workbench.sh [console_env_file]

启动后打开 dsh Web UI（默认 http://127.0.0.1:3080）：

• 侧边栏底部出现「工作流」按钮 → 打开工作流面板；
• 面板按模块分组列出全部调度工作流（状态点：绿=成功 / 红=失败 / 蓝=运行中 / 灰=未运行）；
• 选中任意工作流后可直接：
  • 「提问」：带着该工作流上下文创建智能体会话，自由提问；
  • 「诊断」：自动获取最近一次失败运行的诊断包（步骤、脱敏日志）并输出根因报告；
  • 「修复」：智能体先诊断再给修复方案，任何正式执行/调度修改必须先经你确认；
  • 「试运行 / 正式运行 / 停止」：对应控制台的受控执行语义（试运行无外部副作用）。

降级方案：若 dsh 客户端包因版本差异未能加载，直接打开桥接服务自带的独立面板 http://127.0.0.1:8790/，功能与侧边栏面板一致（零依赖页面）。

目录结构

workbench/
  cordis.template.yml      # dsh 组合补丁模板（启动脚本渲染出 cordis.local.yml）
  bin/
    start-workbench.ps1    # Windows 一键启动
    start-workbench.sh     # Linux/macOS 一键启动
  plugin/                  # dsh 插件包（@gyxx/dsh-plugin-gyxx-workbench）
    package.json           # 含 dsh.client 声明（浏览器包发现契约）
    gyxx-workbench.mjs     # 宿主插件：工具 / 提示词 / 监控 / 桥接（零运行时依赖）
    client/
      src/                 # 侧边栏面板源码（React，打包时 react 外置）
      standalone.html      # 降级独立面板（桥接服务直接托管）
    scripts/build-client.mjs
    lib/client.js          # 已构建的浏览器包（随仓库提交，改源码后需重建）
    tests/                 # node --test 冒烟测试

智能体工具清单

工具	说明	副作用
gyxx_workflow_list	全部工作流及调度、最近运行状态	无
gyxx_workflow_detail	单工作流定义（步骤/依赖/重放策略/调度）	无
gyxx_workflow_runs	最近运行历史（步骤级状态、退出码、脱敏错误）	无
gyxx_workflow_diagnose	一次运行的完整诊断包（journal 路径 + 脱敏日志尾部）	无
gyxx_workflow_trigger	触发运行；默认试运行	试运行无副作用；正式执行需 execute=true + confirmed=true
gyxx_workflow_cancel	停止手动/定时运行	有（停止进程）
gyxx_schedule_update	启用/停用/改调度（读-改-写，带版本校验）	有（改 config/schedules.json）

安全模型

• 宿主插件与控制台都只绑定 127.0.0.1；桥接服务的写操作要求 x-gyxx-workbench: 1 自定义头 + application/json，拒绝跨站表单提交；CORS 仅回环来源。
• 控制台自身的守卫不变：正式执行仍需 confirmed=true，写操作仍需 X-GYXX-Console: 1 与同源检查；令牌模式（GYXX_CONSOLE_TOKEN）对插件同样生效。
• 系统提示词固化「诊断 → 方案 → 用户确认 → 执行」的修复顺序，禁止智能体跳过确认。
• 日志经控制台脱敏管道（口令/Token/URL 凭据打码）后才进入对话上下文。

失败监控

宿主插件每 30s（pollIntervalMs）轮询 /api/overview：某工作流出现新的失败运行时 → 面板右下角弹出告警 toast（可一键「立即诊断」）；autoDiagnose: true 时还会自动创建 诊断会话。告警去重以 workflow_id + run_id 为准，恢复成功后重置。

配置项（cordis.local.yml → config）

键	默认	说明
consoleBaseUrl	http://127.0.0.1:8765（或环境变量 GYXX_CONSOLE_URL）	gyxx 控制台地址
consoleToken	环境变量 GYXX_CONSOLE_TOKEN	控制台访问令牌（控制台以令牌模式运行时必填）
bridgeHost / bridgePort	127.0.0.1 / 8790	桥接服务监听地址
pollIntervalMs	30000	失败监控轮询间隔
autoDiagnose	false	发现失败时自动创建诊断会话
projectRoot	dsh 进程 cwd	新建智能体会话的工作目录

开发

# 重建客户端包（修改 client/src 后必须执行并提交 lib/client.js）
cd workbench/plugin && npm install && npm run build

# 宿主插件冒烟测试（不需要 dsh / gyxx console）
cd workbench/plugin && npm test

# Python 侧端点测试
uv run pytest tests/test_console.py -k "workflow_detail or run_detail or diagnosis"

依赖的 dsh 扩展点（上游契约）

• ctx.tools.register() 原始 JSON-Schema 工具定义（cookbook: extension-cookbook）
• ctx.systemPrompt.section() 系统提示词段
• cordis.yml --patch 组合覆盖（apps/cli/src/args.ts，npm 版同样支持）
• dsh.client package.json 声明 → 客户端包发现（packages/client/modules）
• 插槽：sidebar.footer.action（list，追加）、shell.overlay（list，追加）
• ctx.agents.create() + agent.followup() 编程式会话

dsh 处于 developer preview，扩展点可能变化；升级 dsh 后若面板消失，先检查 浏览器控制台模块加载错误，再核对上述插槽名是否仍存在于 packages/client/ui-layout / ui-sidebar 的 SlotMap。