qiming/qimingclaw/docs/digital-employee-frontend-integration-plan.md

# sgRobot 核心能力融合计划

## 定位

本计划不是单纯的“前端页面嵌入计划”。

真正目标是：

```text
以 qimingclaw 为客户端底座，
以数字员工页面为主要产品载体，
逐步吸收 sgRobot 的核心任务操作系统能力。
```

数字员工页面不是一个展示壳，而是后续承载以下能力的主入口：

- 今日工作台
- 任务中心
- 技能库
- 执行记录
- 审批与人工介入
- 运行时间线
- 产物与日报
- 计划模板与业务流程

当前 qimingclaw 已经完成一个过渡版本：在“概览”菜单内嵌 sgRobot 数字员工静态页面，不启动 sgRobot 后端也能展示页面。但这只是第一步，后续要把 sgRobot 的核心模型和执行治理能力融合进 qimingclaw。

## 总体原则

### 1. qimingclaw 是底座

保留 qimingclaw 当前已有优势：

- Electron 客户端
- 登录与注册链路
- lanproxy 远程接入
- `/computer/chat` 本地执行入口
- ACP 引擎
- MCP 工具接入
- 本地 SQLite 配置与状态存储

不把 sgRobot Rust daemon 原样搬进来，不让 qimingclaw 启动依赖 sgRobot 进程。

### 2. 数字员工页面是产品载体

sgRobot 的能力不是以后台模块裸露给用户，而是通过数字员工页面呈现：

- 用户看到的是数字员工的任务、状态、汇报和介入点。
- 后台融合的是 Plan / Task / Run / Skill / Event / Artifact / Approval。
- 页面最终从 demo fallback 过渡到 qimingclaw 真实数据。

### 3. 源码融合，运行隔离

数字员工前端采用源码级融合，而不是长期维护 `dist` 快照。

但第一阶段仍保持独立构建，不直接混入 qimingclaw 主 renderer bundle，避免：

- React 18 / React 19 冲突
- Tailwind / Ant Design 样式污染
- 路由体系互相影响

推荐方式：

```text
源码融合
  -> 独立构建
  -> 输出静态资源
  -> qimingclaw webview 加载
  -> 后续通过 qimingclaw API 接真实数据
```

## 目标架构

最终目标链路：

```text
用户目标 / 后端远程任务 / 定时任务
  -> Plan 或 Direct Task
  -> Task
  -> Run
  -> qimingclaw ACP / MCP 执行
  -> Event / Artifact / Approval
  -> Projection
  -> 数字员工页面展示与人工介入
```

核心对象：

```text
Plan
PlanStep
Task
Run
Skill
Event
Artifact
Approval
MemoryEntry
ManagedService
```

第一轮不要求一次性实现全部对象，但数据库和 API 设计要为这些对象预留边界。

## 当前状态

已完成的过渡实现：

```text
crates/agent-electron-client/public/sgrobot-digital/
crates/agent-electron-client/src/renderer/components/pages/OverviewPage.tsx
```

当前链路：

```text
qimingclaw 左侧菜单“概览”
  -> OverviewPage
  -> Electron webview
  -> sgrobot-digital/index.html#/digital
  -> sgRobot 数字员工静态页面
  -> demo fallback 数据
```

当前问题：

- 数字员工前端还是构建产物快照。
- 页面数据主要来自 sgRobot demo fallback。
- qimingclaw 没有 Plan / Task / Run / Event / Artifact 的正式状态模型。
- qimingclaw 的 ACP 执行链路尚未映射到数字员工任务中心。
- Skill、Approval、日报、执行时间线还不是 qimingclaw 真实能力。

## 分阶段融合计划

## Phase 1：数字员工前端源码融合（已开始）

目标：把现在的静态快照变成可维护源码集成。

### 做法

在 qimingclaw 中新增独立 embedded 前端源码目录：

```text
crates/agent-electron-client/
  embedded/
    sgrobot-digital/
      package.json
      vite.config.ts
      tsconfig.json
      src/
        pages/digital/
        components/digital/
        contexts/
        lib/
        types/
        index.css
        main.tsx
      public/
        digital-assets/
        logo.png
      patches/
        README.md
  public/
    sgrobot-digital/
```

新增脚本：

```text
scripts/sync-sgrobot-digital.js
scripts/build-sgrobot-digital.js
```

当前 qimingclaw 已新增：

```text
crates/agent-electron-client/embedded/sgrobot-digital/
crates/agent-electron-client/scripts/sync-sgrobot-digital.js
crates/agent-electron-client/scripts/build-sgrobot-digital.js
```

常用命令：

```bash
cd crates/agent-electron-client
npm run sync:sgrobot-digital
npm --prefix embedded/sgrobot-digital install
npm run build:sgrobot-digital
npm run build:renderer
```

其中：

- `sync:sgrobot-digital` 从 sgRobot 的 web 源码同步数字员工相关源码和资源。
- `build:sgrobot-digital` 从 qimingclaw 内的 embedded 源码构建到 `public/sgrobot-digital`。
- `build:renderer` 验证 qimingclaw 主客户端构建。

同步范围优先包含：

```text
sgRobot/crates/sgclaw-core/web/src/pages/digital/
sgRobot/crates/sgclaw-core/web/src/components/digital/
sgRobot/crates/sgclaw-core/web/src/contexts/RoleContext.tsx
sgRobot/crates/sgclaw-core/web/src/lib/api.ts
sgRobot/crates/sgclaw-core/web/src/lib/basePath.ts
sgRobot/crates/sgclaw-core/web/src/lib/i18n.ts
sgRobot/crates/sgclaw-core/web/src/lib/tauri.ts
sgRobot/crates/sgclaw-core/web/src/types/api.ts
sgRobot/crates/sgclaw-core/web/src/index.css
sgRobot/crates/sgclaw-core/web/public/digital-assets/
```

qimingclaw 专用 patch：

- 直达 `#/digital`
- 禁用 sgRobot 配对页
- 静态资源使用相对 base path，兼容 Vite dev server 和 Electron `file://` 打包态
- API 暂时允许 fallback 到 demo 数据
- 关闭 sgRobot 独立窗口行为，交给 qimingclaw 容器处理

当前边界：

- 前端已从“纯构建产物快照”推进为“源码同步 + 独立构建 + 静态嵌入”。
- 数字员工页面仍主要使用 sgRobot 的 demo fallback 和同源 API 探测。
- qimingclaw 还没有正式落地 Plan / Task / Run / Event / Artifact / Approval 数据模型。
- 下一阶段应开始建设 qimingclaw 本地数字员工 API 适配层。

### 产出

- 数字员工页面可以从源码重新构建。
- `public/sgrobot-digital` 不再手工维护。
- qimingclaw 不启动 sgRobot 也能打开数字员工页面。

### 验收

- `npm run sync:sgrobot-digital`
- `npm run build:sgrobot-digital`
- `npm run build:renderer`
- qimingclaw“概览”直接显示数字员工首页，不出现配对页。

## Phase 2：数字员工 API 适配层

目标：让数字员工页面开始读取 qimingclaw 真实数据。

### 做法

在 qimingclaw main process 或本地 HTTP 服务中新增数字员工 API 适配层。

先实现这些 sgRobot 兼容 API：

```text
GET  /api/digital-employee/workday
POST /api/digital-employee/workday/actions
GET  /api/debug/plans
GET  /api/debug/tasks
GET  /api/skill
GET  /api/debug/store
```

数据来源先映射 qimingclaw 当前已有能力：

- 当前用户
- 登录状态
- 服务状态
- Agent 状态
- 会话列表
- 最近 `/computer/chat` 请求
- ACP session 状态
- MCP tool 列表

此阶段不追求完整 Plan/Task/Run，只先让页面从 qimingclaw 取真实状态。

### 产出

- 数字员工首页展示 qimingclaw 的真实运行状态。
- 技能库可以显示 qimingclaw 当前 MCP/ACP 工具能力。
- 任务中心开始展示 qimingclaw 最近执行记录。

### 验收

- 停止 sgRobot 后端，数字员工页面仍然工作。
- 页面 API 请求命中 qimingclaw。
- demo fallback 只作为无数据兜底，不再是主数据源。

## Phase 3：Run / Event / Artifact 轻量控制平面

目标：把 qimingclaw 当前执行链路正式记录为可展示、可审计的运行对象。

### 当前 qimingclaw 执行链路

```text
backend
  -> lanproxy
  -> computerServer:60006 /computer/chat
  -> agentService.ensureEngineForRequest
  -> AcpEngine.chat
  -> ACP session / prompt
  -> /computer/progress/{session_id} SSE
```

### 需要新增的核心表

先落地最小集合：

```text
runs
events
artifacts
approvals
```

推荐语义：

- `Run`：一次 qimingclaw 执行尝试。
- `Event`：执行过程中的事实记录。
- `Artifact`：执行结果、文件、报告、截图、日志摘要。
- `Approval`：权限请求、人工确认、风险操作确认。

### 映射方式

```text
/computer/chat request
  -> create Run
ACP progress event
  -> append Event
permission request
  -> create Approval
tool result / final message
  -> create Artifact 或 Event
session complete
  -> finish Run
```

### 产出

- 每次执行都有 Run ID。
- 数字员工“今日执行”“运行明细”读取真实 Run/Event。
- 后续日报和审计有数据基础。

### 验收

- 发起一次远程 `/computer/chat` 后，数字员工页面能看到执行记录。
- Run 状态能从 running 进入 succeeded / failed / cancelled。
- Event 时间线可追踪主要执行过程。

## Phase 4：Task / PlanStep / Plan

目标：吸收 sgRobot 的任务操作系统骨架。

### 先做 Task

把一次业务执行抽象成 Task：

```text
Task
  -> Run attempt 1
  -> Run attempt 2
```

Task 管业务目标，Run 管执行尝试。

### 再做 Plan / PlanStep

当 Task 稳定后，引入：

```text
Plan
PlanStep
```

Plan 用于承载多步骤业务流程。

### 数据关系

```text
Plan
  -> PlanStep[]
  -> Task[]
  -> Run[]
  -> Event[]
  -> Artifact[]
  -> Approval[]
```

### 产出

- 数字员工任务中心从“执行记录列表”升级为“计划 / 任务 / 步骤”视图。
- 支持多步骤任务展示。
- 支持失败隔离和重试。

### 验收

- 单步任务能以 Task 展示。
- 多步任务能以 Plan 展示。
- 每个 Task 能看到 Run 历史。

## Phase 5：PlanTemplate 融合

目标：吸收 sgRobot 的业务流程模板能力。

### 新增目录

```text
~/.qimingclaw/plan_templates/
```

支持文件：

```text
PlanTemplate.toml
```

### API

```text
GET  /api/plan-templates
GET  /api/plan-templates/:id
POST /api/plan-templates/:id/activate
```

### 与数字员工页面关系

数字员工“任务设置”区域读取 PlanTemplate。

用户可以：

- 查看模板
- 选择今日任务
- 一键执行
- 设置定时

### 产出

- qimingclaw 具备业务流程沉淀能力。
- 数字员工不只是临时聊天入口，而是可选择业务模板执行。

### 验收

- 放入一个 `PlanTemplate.toml` 后，数字员工页面能展示。
- 点击执行后生成 Plan / Task / Run。

## Phase 6：Skill Catalog 融合

目标：把 qimingclaw 的 MCP / ACP 工具治理成 sgRobot 风格 Skill。

### 数据模型

```text
Skill
  skill_id
  name
  description
  version
  kind
  input_schema
  output_schema
  timeout_policy
  retry_policy
  approval_policy
  sandbox_policy
  enabled
```

### 来源映射

```text
MCP tools
ACP commands
qimingclaw built-in tools
GUI agent tools
file server tools
```

### 与数字员工页面关系

数字员工“技能库”展示 qimingclaw Skill Catalog。

用户可以：

- 查看技能
- 启用 / 禁用
- 查看所属 MCP server
- 查看输入输出说明
- 查看最近调用记录

### 产出

- 工具从“技术配置”变成“数字员工能力”。
- PlanTemplate 可以绑定 Skill。

### 验收

- MCP tool 能出现在技能库。
- 禁用技能后，PlanTemplate 或任务执行不会再选择它。

## Phase 7：Approval / Human-in-the-loop

目标：吸收 sgRobot 的人工治理机制。

### 融合对象

qimingclaw 已有 ACP permission 和 sandbox permission 概念。

需要统一成：

```text
Approval
```

来源包括：

- 文件写入
- 命令执行
- 外部服务调用
- 高风险工具
- Plan 执行确认
- Task 重试 / 跳过 / 取消

### 与数字员工页面关系

数字员工页面展示：

- 待审批
- 已批准
- 已拒绝
- 等待输入
- 风险说明

用户可操作：

- approve
- reject
- approve once
- approve always
- pause
- resume
- cancel

### 产出

- 人工介入成为主路径能力。
- 数字员工不是黑箱自动执行。

### 验收

- ACP permission request 能进入数字员工审批区。
- 用户在数字员工页面审批后，ACP 执行继续。

## Phase 8：Artifact / 日报 / 汇报

目标：把执行结果正式沉淀为产物，并由数字员工生成日报和汇报视图。

### Artifact 类型

```text
file
report
screenshot
log
json
markdown
diff
summary
```

### 日报数据来源

```text
Run
Event
Artifact
Approval
Task status
Plan status
```

### 与数字员工页面关系

数字员工“日报”区域展示：

- 今日执行
- 成功 / 失败 / 异常
- 人工介入次数
- 关键产物
- 风险提示
- 可下载报告

### 产出

- qimingclaw 的执行结果可沉淀、可回看、可汇报。

### 验收

- 完成任务后能在日报区域看到执行摘要。
- Artifact 可从任务详情进入查看。

## Phase 9：ManagedService / 常驻能力治理

目标：吸收 sgRobot 对长期服务能力的治理方式。

qimingclaw 当前已有多个服务：

```text
computerServer
fileServer
lanproxy
mcpProxy
agent
guiServer
adminServer
```

需要把它们建模为：

```text
ManagedService
ServiceInstance
ServiceLease
```

### 与数字员工页面关系

数字员工页面可以展示：

- 服务健康
- 最近错误
- 重启次数
- 当前依赖它的任务
- 是否需要人工处理

### 产出

- 服务状态不只在客户端设置页展示，也进入数字员工的运行上下文。

### 验收

- 服务异常时，数字员工首页能提示。
- 服务恢复后，事件和状态同步更新。

## Phase 10：Plan Agent / Task Agent

目标：在 qimingclaw 内形成 sgRobot 的双层 Agent 架构。

这是后期能力，不建议提前做。

### Plan Agent

负责：

- 计划生命周期
- 用户对话
- 异常决策
- 审批转发
- 重试 / 跳过 / 重规划

### Task Agent

负责：

- 单个 Task 的执行
- ACP session 调用
- MCP tool 调用
- 进度上报
- 产物回写

### 推荐链路

```text
User
  -> Digital Employee
  -> Plan Agent
  -> Task Agent
  -> ACP / MCP
  -> Event / Artifact / Approval
  -> Digital Employee Projection
```

### 产出

- qimingclaw 从“Agent 客户端”升级为“数字员工任务操作系统”。

## 推荐实施顺序

按风险和收益排序：

```text
1. 数字员工前端源码融合
2. 数字员工 API 适配层
3. Run / Event / Artifact 轻量控制平面
4. Task / Plan 基础模型
5. PlanTemplate
6. Skill Catalog
7. Approval / Human-in-the-loop
8. 日报与 Artifact
9. ManagedService
10. Plan Agent / Task Agent
```

## 第一阶段验收清单

第一阶段完成后，应满足：

- qimingclaw 内有数字员工前端源码目录。
- `public/sgrobot-digital` 可由脚本生成。
- 不启动 sgRobot 后端也能打开“概览”。
- “概览”直接显示数字员工页面。
- 不出现 sgRobot 配对页。
- 不手工维护压缩后的 `dist/assets/*.js`。
- sgRobot 仓库不参与 qimingclaw 提交。
- `npm run build:renderer` 通过。

## 最终验收标准

整个融合完成后，应满足：

- 数字员工页面显示 qimingclaw 真实数据。
- 远程 `/computer/chat` 请求能生成 Run 和 Event。
- 用户能在数字员工页面看到任务进度、失败、产物和审批。
- PlanTemplate 能创建可执行计划。
- Skill Catalog 能治理 MCP/ACP 工具。
- 日报能基于真实 Run/Event/Artifact 生成。
- qimingclaw 不依赖 sgRobot daemon。
- sgRobot 的核心理念和对象模型被 qimingclaw 吸收，而不是简单嵌入另一个应用。