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

以 [deepseek-harness](https://github.com/deepseek-ai/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 自身要求）。

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

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

```bash
# 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 | 新建智能体会话的工作目录 |

## 开发

```bash
# 重建客户端包（修改 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。