1076 lines
32 KiB
Markdown
1076 lines
32 KiB
Markdown
# 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 适配层。
|
||
|
||
## Phase 2：qimingclaw 数字员工 API Adapter（已开始）
|
||
|
||
目标：让数字员工页面开始消费 qimingclaw 语义的数据，而不是完全依赖 sgRobot demo fallback。
|
||
|
||
当前 qimingclaw 已新增：
|
||
|
||
```text
|
||
crates/agent-electron-client/embedded/sgrobot-digital/src/lib/qimingclawAdapter.ts
|
||
```
|
||
|
||
当前覆盖的页面接口：
|
||
|
||
```text
|
||
GET /api/digital-employee/workday
|
||
POST /api/digital-employee/workday/actions
|
||
GET /api/scheduler/jobs
|
||
GET /api/debug/plans
|
||
GET /api/debug/tasks
|
||
GET /api/debug/plan/:planId/flow
|
||
POST /api/debug/plan/:planId/dispatch
|
||
GET /api/plan/:planId/messages
|
||
GET /api/skill
|
||
POST /api/skill/:skillId/enabled
|
||
```
|
||
|
||
当前数据来源：
|
||
|
||
- qimingclaw adapter 内置的客户端任务职责。
|
||
- `localStorage` 保存的今日任务选择、特性设置、日报生成状态。
|
||
- qimingclaw 语义的 ACP / MCP / computer server / artifact-report 技能定义。
|
||
|
||
当前页面表现：
|
||
|
||
- `source` 返回 `live`，数字员工首页会使用真实 adapter 数据通道。
|
||
- 今日任务从“白领一天 demo”切换为 qimingclaw 客户端职责。
|
||
- 任务中心、技能库、运行明细、日报预览开始使用 qimingclaw adapter 数据。
|
||
|
||
下一步：
|
||
|
||
- 将 adapter 的静态职责替换为 qimingclaw 主进程 IPC 数据源。
|
||
- 新增本地数字员工状态服务，持久化 Plan / Task / Run / Event / Artifact / Approval。
|
||
- 把 `/computer/chat`、ACP session、MCP tool status 写入 Run/Event。
|
||
|
||
## Phase 3：webview 只读状态桥（已开始）
|
||
|
||
目标：让 embedded 数字员工页能读取 qimingclaw 客户端真实状态，同时保持 webview 权限收敛。
|
||
|
||
当前 qimingclaw 已扩展：
|
||
|
||
```text
|
||
crates/agent-electron-client/src/preload/webviewPerfBridge.ts
|
||
crates/agent-electron-client/src/main/main.ts
|
||
```
|
||
|
||
桥接对象：
|
||
|
||
```text
|
||
window.QimingClawBridge.digital.getSnapshot()
|
||
```
|
||
|
||
当前 snapshot 内容：
|
||
|
||
- Agent service status
|
||
- MCP proxy status
|
||
- Computer Server status
|
||
- Lanproxy status
|
||
- File Server status
|
||
- GUI Server status
|
||
- ACP detailed sessions summary
|
||
|
||
安全边界：
|
||
|
||
- 只读。
|
||
- 不暴露 start / stop / restart。
|
||
- 不暴露 prompt / shell / computer chat。
|
||
- webview 页面只能拿到状态快照，再由 adapter 映射到数字员工页面。
|
||
|
||
当前页面表现：
|
||
|
||
- “客户端运行状态巡检”会显示 Agent、MCP、活跃会话数。
|
||
- “远程任务接入准备”会显示 Computer Server、Lanproxy、File Server 状态。
|
||
- 在非 Electron webview 环境下，adapter 自动降级为“未连接 bridge”的 fallback 文案。
|
||
|
||
下一步：
|
||
|
||
- 新增 qimingclaw digital employee state service。
|
||
- 将 bridge snapshot 写入 Run/Event，而不是只作为页面即时 projection。
|
||
- 让 `/computer/chat` 请求生成真实 Task / Run / Event。
|
||
|
||
## Phase 4：qimingclaw 本地状态服务雏形（已开始）
|
||
|
||
目标：让数字员工能力不只是页面 projection，而是开始拥有 qimingclaw 自己的本地状态沉淀。
|
||
|
||
当前 qimingclaw 已新增：
|
||
|
||
```text
|
||
crates/agent-electron-client/src/main/services/digitalEmployee/stateService.ts
|
||
crates/agent-electron-client/src/main/ipc/digitalEmployeeHandlers.ts
|
||
```
|
||
|
||
新增 IPC：
|
||
|
||
```text
|
||
digitalEmployee:getSnapshot
|
||
digitalEmployee:getState
|
||
```
|
||
|
||
当前职责：
|
||
|
||
- 主进程统一采集 Agent / MCP / Computer Server / Lanproxy / File Server / GUI Server / Sessions。
|
||
- 每次 snapshot 写入 `digital_employee_state_v1`。
|
||
- 状态服务生成轻量事件 `service_snapshot`。
|
||
- webview bridge 改为调用 `digitalEmployee:getSnapshot`，不再自行聚合多个 IPC。
|
||
|
||
当前边界：
|
||
|
||
- 状态服务仍保留 settings JSON 作为兼容快照。
|
||
- Plan / Task / Run / Event 已开始写入独立 SQLite 表。
|
||
- 当前事件主要记录服务状态变化，还没有接入 `/computer/chat` 和 ACP token/event stream。
|
||
|
||
下一步：
|
||
|
||
- 新建正式 SQLite 表：`digital_plans`、`digital_tasks`、`digital_runs`、`digital_events`、`digital_artifacts`、`digital_approvals`。
|
||
- 在 computer server 的 `/computer/chat` 入口创建 Task / Run。
|
||
- 在 ACP event forwarder 中写入 Run/Event。
|
||
|
||
## Phase 5：管理端任务入口落地（已开始）
|
||
|
||
目标：管理端或后端通过 `/computer/chat` 下发任务时，qimingclaw 本地数字员工状态可以生成真实任务记录。
|
||
|
||
当前 qimingclaw 已接入：
|
||
|
||
```text
|
||
crates/agent-electron-client/src/main/services/computerServer.ts
|
||
crates/agent-electron-client/src/main/ipc/computerHandlers.ts
|
||
crates/agent-electron-client/src/main/services/digitalEmployee/stateService.ts
|
||
```
|
||
|
||
记录时点：
|
||
|
||
- 收到 chat 请求：创建/更新 Plan、Task、Run，写入 `computer_chat_received`。
|
||
- chat 成功返回：Run 标记 completed，写入 `computer_chat_completed`。
|
||
- chat 失败返回：Run 标记 failed，写入 `computer_chat_failed`。
|
||
|
||
当前联动意义：
|
||
|
||
- 管理端任务进入客户端后，本地 SQLite 会立即有可追溯记录。
|
||
- 对应 Plan / Task / Run / Event 均进入 `digital_sync_outbox`。
|
||
- 后续管理端 sync API 确定后，可将 outbox 推送到管理端并回填 `remote_id`。
|
||
|
||
下一步：
|
||
|
||
- 接 ACP event forwarder，把 token、tool、step、artifact 写入 Run/Event/Artifact。
|
||
- 增加 sync worker，根据 `step1_config.serverHost` 和登录 token 推送 outbox。
|
||
|
||
## Phase 6：ACP / computer 运行事件落库（已开始）
|
||
|
||
目标：让数字员工不只知道“管理端下发了任务”，也能看到 qimingclaw 执行过程中的真实运行事件。
|
||
|
||
当前 qimingclaw 已接入：
|
||
|
||
```text
|
||
crates/agent-electron-client/src/main/ipc/eventForwarders.ts
|
||
crates/agent-electron-client/src/main/services/digitalEmployee/stateService.ts
|
||
```
|
||
|
||
记录来源：
|
||
|
||
- ACP session SSE 事件：`message.updated`、`session.updated`、`session.status`、`session.idle`、`session.error` 等。
|
||
- computer 执行进度：`computer:progress`。
|
||
- prompt 生命周期：`computer:promptStart`、`computer:promptEnd`。
|
||
- Agent 生命周期：`ready`、`destroyed`、`error`。
|
||
|
||
当前落库方式：
|
||
|
||
- 运行中的事件会创建/更新对应 Plan、Task、Run。
|
||
- 完成和失败事件会结束 Run。
|
||
- 每条 Event 都写入 `digital_events`。
|
||
- Plan / Task / Run / Event 均进入 `digital_sync_outbox`，等待后续同步到管理端。
|
||
|
||
与管理端联动的边界：
|
||
|
||
- SQLite 作为本地事实缓存和离线队列，不作为最终中心库。
|
||
- 管理端 API 未确定前，qimingclaw 先沉淀统一的本地实体和 outbox。
|
||
- 后续 sync worker 只消费 `digital_sync_outbox`，避免业务写入链路直接依赖网络。
|
||
|
||
下一步：
|
||
|
||
- 确认 qiming-backend 的数字员工同步 API 路径和鉴权方式。
|
||
- 将 Artifact / Approval 从普通 Event 中拆成正式实体。
|
||
- 数字员工页面展示同步状态：待同步、同步失败、最近同步时间。
|
||
|
||
## Phase 7：管理端 outbox 同步 worker（已开始）
|
||
|
||
目标：SQLite 继续作为本地事实缓存和离线队列，同时把 Plan / Task / Run / Event 推送到管理端，避免数字员工数据停留在单机。
|
||
|
||
当前 qimingclaw 已新增：
|
||
|
||
```text
|
||
crates/agent-electron-client/src/main/services/digitalEmployee/syncService.ts
|
||
crates/agent-electron-client/src/main/bootstrap/startup.ts
|
||
crates/agent-electron-client/src/main/ipc/digitalEmployeeHandlers.ts
|
||
crates/agent-electron-client/src/preload/webviewPerfBridge.ts
|
||
```
|
||
|
||
当前机制：
|
||
|
||
- 启动后后台启动 sync worker，默认每 30 秒扫描 `digital_sync_outbox`。
|
||
- 默认同步地址由 `step1_config.serverHost` 拼接：
|
||
|
||
```text
|
||
/api/digital-employee/sync/outbox
|
||
```
|
||
|
||
- 可通过 settings `digital_employee_sync_config.endpoint` 覆盖同步地址。
|
||
- 使用 `auth.saved_key` 或域名级 saved key 作为客户端标识。
|
||
- 使用管理端登录态 token 作为 `Authorization: Bearer <token>`，同时携带 `X-Qiming-Client-Key`。
|
||
- 同步成功后回填 outbox 状态，并根据后端 ack 回填实体 `remote_id` / `last_synced_at`。
|
||
- 同步失败时标记 failed 和错误信息；定时 worker 按指数退避补偿，手动 `flushSync` 可强制立即重试，不影响 `/computer/chat` 和 ACP 执行链路。
|
||
- 数字员工任务设置工具栏已增加“同步管理端”按钮，可通过 bridge 立即触发 `flushSync` 并刷新页面投影。
|
||
- 数字员工首页已增加管理端同步状态条，展示待同步数量、失败数量、可重试/退避分布、失败实体类型分布、最近同步时间和最近失败原因摘要。
|
||
- 数字员工嵌入页会通过 `window.QimingClawBridge.digital.getRuntimeRecords()` 读取本地 SQLite 的 `digital_plans`、`digital_tasks`、`digital_runs`、`digital_events`、`digital_artifacts`、`digital_approvals`，优先用真实本地记录生成 workday、任务中心、任务详情和流程投影；本地记录为空时才回落到 qimingclaw 固定适配任务。
|
||
- 数字员工页面的任务确认、资料设置、日报状态通过 `getUiState` / `saveUiState` 保存在主进程 SQLite settings；保存时会记录 `digital_workday_*` 本地事件并进入 outbox，避免这些页面操作只留在 webview localStorage。
|
||
- 数字员工技能库通过 `getSkillCapabilities` 读取 qimingclaw 当前 MCP 配置、server 状态、已发现工具与 allow/deny 限制，并把 MCP server/tool 投射为 `/api/skill` 技能项。
|
||
- 数字员工调试存储、dashboard、flow 和产物列表通过 qimingclaw adapter 的 `/api/debug/store`、`/api/dashboard`、`/api/debug/plan/:id/flow`、`/api/debug/task/:id/flow`、`/api/artifact` 投射本地 Plan / Task / Run / Event / Artifact / Approval；Run/Event payload 中的 `artifacts`、`outputs`、`files`、`outputPath`、`uri` 等字段会作为正式 artifact 记录为空时的兼容产物入口展示。
|
||
- qimingclaw 主进程记录 `/computer/chat` 结果和 runtime event 时，会从 payload 的 `artifacts`、`outputs`、`files`、`attachments`、`outputPath`、`uri` 以及 `approvals`、`approval_requests`、`needApproval` 等字段轻量提取正式 `digital_artifacts` / `digital_approvals` 记录，并进入 outbox 同步。
|
||
- `digital_approvals` 会投射为数字员工 workday 的 `decisions`；首页待解决事项按钮会调用本地 `decide_approval` action，把处理结果写入 SQLite UI state，回写正式 approval 状态并进入 approval outbox，同时生成 `digital_workday_decide_approval` runtime event。同步失败 review 只保留在 dashboard/同步诊断中，不作为可审批 workday decision。
|
||
- 任务中心的 `/api/governance/command` 已接入 qimingclaw 兼容层：`create_plan`、`submit_plan`、`approve_plan`、`activate_plan`、`create_schedule`、`run_schedule_now` 等命令返回本地可解释结果，其中激活/立即运行会映射到 adapter 的 dispatch/workday 状态。
|
||
- 日报下载不再打开 sgRobot 风格 PDF 后端直链；生成日报后会基于当前 qimingclaw workday 投影在浏览器内导出本地文本日报。
|
||
- 任务中心在加载到 qimingclaw 真实计划时不再混入示例 supplement；只有没有任何真实计划或请求失败时才使用 qimingclaw 客户端职责语义的本地示例兜底。
|
||
- 嵌入页 localStorage/sessionStorage 的运行态 key 已切换到 `qimingclaw:*` / `qimingclaw_digital_*` 命名；旧 sgRobot/zeroclaw key 仅作为迁移读取或清理，不再作为新状态写入目标。
|
||
- 数字员工本地表不另建 sgRobot SQLite；统一建在 qimingclaw 主进程数据库 `~/.qimingclaw/qimingclaw.db` 内，作为 qimingclaw 客户端本地事实缓存与 outbox；表结构在主进程启动时创建，数字员工 runtime/sync 服务读写前也会按需自修复执行 `CREATE TABLE IF NOT EXISTS`。
|
||
- 同步状态通过 bridge 返回最近失败 outbox 明细，首页可直接看到实体类型、outbox ID、操作类型、重试次数、失败时间和下次自动重试时间。
|
||
- 本地 SQLite 额外记录 `digital_sync_attempts`，每次 outbox 推送成功、失败或部分 ack 缺失都会留下一次尝试历史，默认保留最近 30 天。
|
||
- 点击失败 outbox 可打开详情弹窗，查看完整错误、实体 ID、退避状态、最近重试历史，并可复制或导出诊断 JSON；也可触发手动 `flushSync` 立即重试。若已配置管理端同步地址，详情弹窗可直接打开对应的管理端同步记录深链。
|
||
- qimingclaw 自动生成的管理端深链只携带 `device_id`、`entity_type`、`entity_id`、`outbox_id`，避免在 URL 中暴露客户端 Key，同时仍能区分同租户下的不同客户端；管理端列表仍保留客户端 Key 手动筛选能力。
|
||
|
||
新增 IPC / Bridge：
|
||
|
||
```text
|
||
digitalEmployee:getSyncStatus
|
||
digitalEmployee:flushSync
|
||
digitalEmployee:getRuntimeRecords
|
||
digitalEmployee:getUiState
|
||
digitalEmployee:saveUiState
|
||
digitalEmployee:getSkillCapabilities
|
||
window.QimingClawBridge.digital.getSyncStatus()
|
||
window.QimingClawBridge.digital.flushSync()
|
||
window.QimingClawBridge.digital.getRuntimeRecords()
|
||
window.QimingClawBridge.digital.getUiState()
|
||
window.QimingClawBridge.digital.saveUiState(update)
|
||
window.QimingClawBridge.digital.getSkillCapabilities()
|
||
```
|
||
|
||
当前边界：
|
||
|
||
- qiming-backend 已补最小接收端，先以通用同步记录表承接客户端 outbox。
|
||
- worker 只消费 outbox，不直接侵入 Plan / Task / Run / Event 写入链路。
|
||
- 管理端返回格式包含 `acked[]`，每项带 `outbox_id`、`entity_type`、`entity_id`、`remote_id`。
|
||
- 若管理端只 ack 批次中的部分 item，已 ack 的 item 会标记 synced，未 ack 的 item 会保留 failed 状态并进入下一轮补偿。
|
||
- 当前接口沿用管理端登录态鉴权，客户端必须能读取到客户端 Key 和登录 ticket/token 才会推送；缺少凭据时保持本地 outbox 等待，并在数字员工同步状态条显示缺少项。
|
||
- 管理端接收 outbox 时会校验 `X-Qiming-Client-Key`，请求体缺少 `client_key` 时以 header 为准，二者不一致时拒绝写入。
|
||
|
||
后端最小落点：
|
||
|
||
```text
|
||
qiming-backend/sql/update-20260605.sql
|
||
qiming-backend/app-platform-modules/app-platform-agent/app-platform-agent-core-ui/.../DigitalEmployeeSyncController.java
|
||
qiming-backend/app-platform-modules/app-platform-agent/app-platform-agent-core-application/.../DigitalEmployeeSyncApplicationServiceImpl.java
|
||
qiming-backend/app-platform-modules/app-platform-agent/app-platform-agent-core-adapter/.../DigitalEmployeeSyncRecord.java
|
||
```
|
||
|
||
后端观察接口：
|
||
|
||
```text
|
||
GET /api/digital-employee/sync/records
|
||
```
|
||
|
||
- 支持 `client_key`、`device_id`、`entity_type`、`entity_id`、`outbox_id`、`page_no`、`page_size` 查询参数。
|
||
- 按当前登录上下文租户隔离，默认每页 20 条，最大每页 100 条。
|
||
- 当前返回通用同步记录和原始 payload，用于管理端页面或联调工具先查看同步结果；后续再拆分为更丰富的 Plan / Task / Run / Event 查询模型。
|
||
- 管理端已增加“数字员工同步记录”菜单、权限资源和列表页，可按客户端 Key、设备 ID、实体类型、实体 ID、Outbox ID 查询并查看 payload；URL 查询参数会预填筛选条件，并在命中 Outbox ID 时自动打开 payload 抽屉。
|
||
- 管理端同步记录页会从通用 payload 中提炼标题、状态、Plan/Task/Run 关联、发生时间等业务摘要，列表和详情抽屉不再只能依赖原始 JSON 排障。
|
||
- 管理端列表和抽屉内的客户端 Key 仅脱敏展示，筛选框仍支持输入完整客户端 Key 精准查询。
|
||
|
||
下一步：
|
||
|
||
- 后续再拆分管理端 Plan / Task / Run / Event 查询模型，让同步记录从通用 payload 观察面升级为业务视图。
|
||
- 数字员工页面继续补充管理端业务视图入口和失败分组统计。
|
||
|
||
管理端业务视图建议：
|
||
|
||
```text
|
||
GET /api/digital-employee/plans
|
||
GET /api/digital-employee/plans/{plan_id}
|
||
GET /api/digital-employee/tasks
|
||
GET /api/digital-employee/runs
|
||
GET /api/digital-employee/events
|
||
GET /api/digital-employee/artifacts
|
||
GET /api/digital-employee/approvals
|
||
```
|
||
|
||
- 查询参数沿用同步记录维度：`client_key`、`device_id`、`entity_id`、`remote_id`、`status`、`sync_status`、`updated_from`、`updated_to`、`page_no`、`page_size`。
|
||
- 业务视图先从通用 sync record 的 `entity_type/entity_id/payload/status/created_at/updated_at` 聚合，不要求立即拆物理表；后续再按容量和查询压力拆正式业务表。
|
||
- Plan 视图输出 `plan_id`、`title`、`objective`、`status`、`client_key_masked`、`device_id`、`task_count`、`run_count`、`latest_event_at`、`sync_status`。
|
||
- Task / Run 视图保留 `plan_id`、`task_id`、`run_id` 关联，Run 额外输出 `started_at`、`finished_at`、`duration_ms`、`last_event_message`。
|
||
- Event / Artifact / Approval 视图保留原始 payload 抽屉，但列表层必须提炼 `kind/title/message/status/occurred_at`，避免管理端只能看 JSON 排障。
|
||
- qimingclaw 客户端的失败详情深链仍指向 sync record；管理端命中后可跳转到对应业务视图详情，形成“同步诊断 -> 业务事实”的双入口。
|
||
|
||
## 管理端联动原则
|
||
|
||
数字员工状态是本地优先，但不能成为本地孤岛。
|
||
|
||
本地 SQLite 表设计必须同时满足：
|
||
|
||
- 离线可用：客户端无网络时仍能展示任务、运行明细和日报。
|
||
- 可追溯：本地每个 Plan / Task / Run / Event 都有稳定本地 ID。
|
||
- 可同步：预留管理端 ID 和同步状态。
|
||
- 可补偿：同步失败后可通过 outbox 重试。
|
||
|
||
当前已新增/规划的本地表：
|
||
|
||
```text
|
||
digital_plans
|
||
digital_tasks
|
||
digital_runs
|
||
digital_events
|
||
digital_artifacts
|
||
digital_approvals
|
||
digital_sync_outbox
|
||
```
|
||
|
||
同步字段：
|
||
|
||
```text
|
||
remote_id
|
||
sync_status
|
||
last_synced_at
|
||
sync_error
|
||
```
|
||
|
||
同步流建议：
|
||
|
||
```text
|
||
本地写入 Plan/Task/Run/Event
|
||
-> digital_sync_outbox pending
|
||
-> 管理端 sync API
|
||
-> 回填 remote_id
|
||
-> sync_status = synced
|
||
```
|
||
|
||
管理端 API 尚未在 qiming-backend 中确认最终路径，因此当前 qimingclaw 先落本地同步契约，不硬编码远端接口。
|
||
|
||
### 产出
|
||
|
||
- 数字员工页面可以从源码重新构建。
|
||
- `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 吸收，而不是简单嵌入另一个应用。
|