wangyunlong
01218b2907
- console: GET /api/workflows/{id}, /runs/{run_id}, /runs/{run_id}/diagnosis
(journal trace + sanitized bounded log tails, workflow/run pairing enforced)
- workbench/: dsh 宿主插件（7 个工作流工具、中文系统提示词、失败监控器、
本机回环桥接服务）+ 侧边栏面板客户端包（sidebar.footer.action 与
shell.overlay 追加插槽）+ 降级独立面板 + 一键启动脚本
- adapters/browser: 收敛 looks_like_login_url 到共享层，修复
jd_main_image_collector 对 gyxx_flow.accounts 的越层导入
- tests: 新端点覆盖；replay_policy 断言对齐已迁移的 catalog（repeatable）
140 lines
8.4 KiB
Markdown
140 lines
8.4 KiB
Markdown
# 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。
|