# 智能工作台设计（dsh-refact 分支）

> 状态：v1 已实现。本文档记录「以 deepseek-harness 为 agent 底座、gyxx-flow 工作流插件化」
> 的架构决策与边界。使用说明见 [../workbench/README.md](../workbench/README.md)。

## 目标与约束

- **底座**：deepseek-harness（`dsh`）Web UI + DeepSeek 模型 = 智能体运行时；
  gyxx-flow 保持唯一的工作流执行/调度事实来源（LangGraph 引擎、`RunJournal`、
  `LockManager`、`EffectLedger` 契约不变）。
- **插件化**：不重写工作流；通过 dsh「everything-is-a-plugin」扩展点把现有
  控制台能力投影为智能体工具与 UI 面板。
- **UI**：在原 dsh Web UI 侧边栏追加工作流入口（`sidebar.footer.action` +
  `shell.overlay` 两个**追加型**插槽，不替换任何内置区域），选中工作流即可
  提问 / 诊断 / 修复。
- **生产约束**（AGENTS.md）：`gyxx schedule run` 仍是唯一生产调度路径；
  正式执行保持 `execute + confirmed` 双确认；控制台仍以 `--env-file` 注入云端凭据
  （启动脚本默认 `D:\product-collector-analyze-flow\.env`）。

## 为什么不把 gyxx-flow 改写进 dsh monorepo

dsh 是 pnpm monorepo（host/client 双聚合、Typert 远程契约、自有构建链）。
把 Python 工作流引擎迁进去既不可能也无必要。dsh 的外部插件机制
（`--patch` cordis.yml + 绝对路径插件 + `dsh.client` 包声明）就是为这种
「外部系统接入」设计的。我们选择**进程外集成**：

- gyxx-flow 控制台 HTTP API 是唯一集成面（已含脱敏、并发守卫、写操作令牌）；
- 工作台插件只是控制台的客户端 + 智能体能力注册器；
- 控制台挂了，dsh 照常可用；dsh 挂了，调度器照常跑。

## 组件

### 1. 控制台诊断端点（Python，`src/gyxx_flow/console.py`）

| 端点 | 说明 |
| --- | --- |
| `GET /api/workflows/{id}` | 单工作流详情（overview 投影 + `schedule_revision`） |
| `GET /api/workflows/{id}/runs/{run_id}` | 单次运行 + 步骤明细 |
| `GET /api/workflows/{id}/runs/{run_id}/diagnosis` | 诊断包：运行 + journal trace + 脱敏日志尾部 |

诊断包日志来源：`run.json` 的 `trace.paths.log` 目录 + 运行时间窗内的控制台日志
（`logs/console/{workflow_id}-*.log`），每个文件限读尾部 256KB，经 `_sanitize_error`
脱敏并截断，单响应最多 5 个文件。`run_id` 与 `workflow_id` 强制配对（404 不泄露
跨工作流记录）。

### 2. 宿主插件（`workbench/plugin/gyxx-workbench.mjs`，零运行时依赖）

- **7 个工具**（原始 JSON-Schema `ToolDefinition`，不 import 任何 dsh 包，
  保证以绝对路径加载时无解析风险）；
- **系统提示词段**（`gyxx-workbench`，order 700）：中文运维契约与安全规则；
- **失败监控器**：`ctx.effect` 轮询，`workflow_id+run_id` 去重，自定义事件
  `gyxx-workbench/alert` + 可选自动诊断会话；
- **桥接服务**（127.0.0.1:8790）：为浏览器面板代理控制台 API（控制台禁 CORS，
  面板无法直连），并承载 `/bridge/ask` 会话创建与降级页面。
  写操作校验 `x-gyxx-workbench: 1` + JSON content-type；CORS 仅回环来源。

### 3. 侧边栏面板（`workbench/plugin/client/`）

- React 源码经 esbuild 打包为 CJS，平台模块（react 等）按 dsh 模块表协议外置，
  包装为 `window.__ModuleLoader__.load({id, factory})`——与官方 tsdown 产物同协议；
- `package.json` 的 `dsh.client` 声明让 `client-modules` 扫描器（支持路径型
  Loader 条目，向上找最近 package.json）发现并提供该浏览器包；
- 插槽：`sidebar.footer.action`（「工作流」开关 + 聚合状态点）、`shell.overlay`
  （左抽屉面板 + 失败 toast）。均为 list 型追加插槽，不替换内置区域；
- 面板动作：提问/诊断/修复（创建带工作流上下文的智能体会话）、试运行/正式运行
  （浏览器端 confirm）、停止、运行历史查看、单运行诊断视图。

### 4. 会话创建（`/bridge/ask`）

`ctx.agents.create({ sessionId, meta: { cwd, origin } })` → `agent.followup()` 注入
带工作流上下文的首条用户消息。新会话自动出现在 dsh 会话列表（host 侧创建即入册）。
文案模板区分 ask/diagnose/repair 三种动作。

## 已知限制（v1）

- 会话创建后不能自动聚焦（dsh 客户端无公开的「选中会话」运行时 API）；面板以
  toast 提示用户在会话列表中点开。
- `sidebar.workspaces` 为 single 型插槽（替换即失去会话树），故面板走 overlay
  抽屉而非内嵌会话树；若未来 dsh 提供追加型侧栏区块插槽，可平移。
- 客户端包协议依赖 dsh 未冻结的 developer-preview 契约；升级 dsh 需回归验证
  （README「依赖的 dsh 扩展点」一节列出了核对清单）。
- `autoDiagnose` 默认关闭：自动开会话会产生模型调用成本。

## 测试

- Python：`tests/test_console.py` 新增 5 用例（详情/运行详情/诊断包/越权配对/HTTP 路由）。
- 插件：`workbench/plugin/tests/`（node:test）——工具注册、离线错误结构化、
  confirmed 守卫、桥接代理。
- 端到端手工验证：`start-workbench.ps1` → 面板选中工作流 → 提问/诊断/修复/试运行。