Workova Agent 当前架构说明（2026-03-13）

历史路径说明

文中后半段仍然保留了部分 archive/desktop-legacy/ 路径，这些内容主要用来说明历史实现背景。

如果你要继续开发，请以当前 desktop/ 工作区为准。

1. 架构边界（已锁定）

客户端（桌面端，唯一执行真源）

执行 Agent Loop：LLM -> tool.call -> approval -> tool.result -> next iteration
执行工具调用、审批暂停恢复、问题提问恢复
执行 MCP 生命周期（连接、断开、重连、工具发现）
执行技能扫描/校验/绑定注入
执行多 Agent 协同（delegate/graph/bus）
执行工作流工具族（workflow.start/wait/control/snapshot/query/history）
渲染结构化聊天卡片（todo/question/tool/workflow/mcp/context/status/error）

后端（仅存储与转发）

LLM 网关：/api/v1/llm/*
同步接口：/api/v1/sync/push、/api/v1/sync/pull
设备心跳：/api/v1/device/heartbeat
允许保存 Agent/聊天/运行事件数据用于跨端同步，但不参与任何执行决策

明确禁止（后端）

禁止服务端执行 tool call / MCP call / Agent loop / 协同编排 / workflow 编排

2. 同步协议（硬切到 `changes[]`）

Push 请求

POST /api/v1/sync/push

json

{
  "device_id": "desktop-local",
  "changes": [
    {
      "entity_type": "agents",
      "entity_id": "agent-1",
      "op": "upsert",
      "version": 3,
      "updated_at": "2026-03-06T12:00:00Z",
      "source_ts": "2026-03-06T12:00:00Z",
      "payload": {}
    }
  ]
}

Pull 响应

GET /api/v1/sync/pull

json

{
  "changes": [],
  "has_more": false,
  "cursor_ts": "2026-03-06T12:00:00Z"
}

冲突规则（服务端固定实现）

append-only：messages/tool_calls/agent_run_steps/workflow_run_events
LWW：agents/agent_tool_policies/agent_skill_bindings/mcp_servers
todo 快照：按条目状态时间戳合并（统一使用 todos 字段）

3. 客户端 Agent 能力清单

内置工具（默认内建）

文件：fs.list/read/search/write/edit/move/delete/mkdir
脚本与进程：shell.exec/script.run/process.list/process.kill
网页：web.search/web.fetch/web.extract
浏览器：browser.open/click/type/select/wait/eval/screenshot/network_logs/console_logs
工作流：workflow.start/wait/control/snapshot/query/history
知识库：kb.search/kb.ingest/kb.reindex
记忆：memory.add/search/update/delete
协同：agent.delegate/agent.spawn/agent.merge_result
任务：todo.create/update/list/complete
系统：time.now/http.request
MCP 动态工具：mcp.<server_id>.<tool>

权限与审批

auto / required / manual_each_call / deny
Agent 级工具授权矩阵：enabled/approval_mode/rate_limit/time_limit/network_scope/fs_scope

沙箱模式

trusted
workspace（默认）
strict（强拦截 shell、越权网络、browser.eval）

运行时恢复点（2026-03-13 当前状态）

新增数据库级 runtime_run_checkpoints 作为 run checkpoint 真源
恢复点保存：run metadata / run loop cursor / conversation slice / tool state / approval queue / pending mutation metadata / memory flush markers / recovery hints
当前每个 checkpoint 还带恢复链元数据：recovery_chain_id / recovery_chain_version / parent_checkpoint_id
新增 runtime_checkpoint_artifacts 保存本地文件修改前快照
恢复点用户表达统一使用：任务恢复点 / 安全回退点
fs.write/edit/move/delete/mkdir 会在执行前自动创建恢复点
agent_run_list_checkpoints / agent_run_get_checkpoint / agent_run_restore_checkpoint 已经暴露为 Tauri command，并接入桌面端恢复点控制面
restore_run_checkpoint() 对文件系统类快照已经是真恢复；shell.exec / script.run 现在会先按 cwd / script 所在目录 收缩恢复作用域：
- 小作用域走 filesystem_snapshot 真恢复
- 中等偏大作用域走 manifest_snapshot，至少能清理恢复点之后新增的副作用文件
- 超大作用域现在会走 inventory_snapshot
- inventory_snapshot 会记录目录直接孩子清单，并结合命令显式目标提取来恢复关键文件
- 命令里的 --output / --out / --file / --write / -o 等显式输出目标现在也会被提取进恢复目标
- manifest_snapshot / inventory_snapshot 还会在预算内提升一部分小文件为真实内容快照，补强“旧文件被覆盖”的恢复能力
resume_agent_run 已经不再把 checkpoint 直接拼成 CHECKPOINT_CONTEXT system prompt 注入模型消息；现在会先生成结构化 resume_contract，并作为 runtime step / observability 元数据记录
checkpoint retention 不再只是“固定保留最近 20 个”，现在已经升级为分层治理：
- 默认至少保留最近 5 个 checkpoint
- 普通 checkpoint 按 14 天窗口清理
- restored / pending approval / failure taxonomy != none 的关键恢复链节点按 45 天窗口保护
- 超出数量上限时，优先删除非保护节点
当前恢复语义已经明确拆成两条：
- restore：回滚文件快照、重建 tool call / approval 状态，并把 run 置为 paused
- resume：基于当前 run 状态继续 loop，依赖结构化 resume_contract + recent run context，不是“拿恢复点文本喂模型”
失败分类已经从“单纯字符串匹配”升级到“结构化 failure contract 优先，字符串只做最后兜底”：
- PolicyEnforcement -> policy_failure
- ToolExecution + sandbox block -> sandbox_failure
- RestoreFlow + shell/script opaque restore -> degraded_recovery
- ResumeFlow -> resume_failure
- 当前每条关键失败事件还会补充 failure_contract：taxonomy / stage / source / reason_code / recoverability / details

长期记忆与自我进化（2026-03-13 当前状态）

长期记忆已经从“基础 memory.add/search/update/delete/compact”升级到第一批结构化真源：
- memories 新增治理字段：memory_kind / confidence / source_type / source_run_id / confirmed_by_user / expires_at / conflicts_with / supersedes / last_used_at
- 新增 user_models：用户画像真源
- 新增 agent_identity_profiles：Agent 身份真源
- 新增 memory_heartbeat_reviews：周期复盘事实表
当前已经落地的 OpenClaw / CoPaw 对标能力：
- 六层记忆里的基础分层已经入库：episodic / semantic / preference / decision / procedural / relationship
- memory_search 现在带双通道返回：semantic_recall + exact_evidence
- create_agent / create_conversation 会自动 bootstrap user model + agent identity
- memory_compact() 会先执行 pre-compaction memory flush
- memory_run_heartbeat_review() 已经能提炼 preference / decision / procedural / relationship / lessons learned
- user_models 已补齐 preference_signals / habit_profile / goal_profile / persona_profile / communication_profile / cadence_profile / risk_profile
新增 memory_relationship_graph：关系图谱真源
关系图现在带 ontology_tags / edge_weight / relation_source
关系图还新增 subject_role / object_role / ontology_path / interaction_pattern
新增 memory_relationship_entities：关系实体注册真源
节点现在带 canonical_name / ontology_domain / aliases / mention_count
关系图会继续生成多跳边：expects_update_via / operates_on / protects / shapes_output_for
agent 全局视角下已经补了跨会话实体合并：
- 相同 stakeholder / workflow / preference 实体会在查询层聚合成单一长期节点视图
- 聚合边会保留 source_conversation_ids
新增 runtime_user_corrections：用户纠错沉淀真源
- 已新增 Tauri command：memory_record_user_correction / memory_get_relationship_graph
- 已新增 observability 事件：memory_flush_triggered / memory_flush_completed / heartbeat_review_completed
当前长期记忆治理已经补到：
- apply_memory_resolution_cycle()：会在 flush / heartbeat 后自动处理 conflict / supersede
- default retention / expiry policy：不同 memory kind 会自动分配默认保留期，并在过期后归档
- procedural_memory：已支持“模型优先、规则兜底”的步骤级提炼
procedural memory 现在已经从环境变量开关升级成 runtime policy：
- heuristic：完全本地规则
- adaptive：默认模式，复杂流程优先尝试模型蒸馏
- llm_first：优先模型蒸馏，失败再回退
- 已新增 Tauri command：list_procedural_memory_policies / get_procedural_memory_policy / set_procedural_memory_policy
当前仍然保留的简化项：
- procedural memory 默认模式虽然已经升级成 adaptive
- 但复杂度判断仍然是“runtime policy + 本地线索”驱动，不是更强的学习型蒸馏策略
- relationship ontology 的跨会话实体合并策略还可以继续增强
Phase C 已经进入第一批内核闭环：
- 新增 runtime_outcome_evaluations：run 结果评分真源
- 新增 runtime_reflections：失败归因 / 复盘结论真源
- 新增 runtime_memory_writeback_candidates：长期记忆写回候选真源
- 新增 runtime_policy_candidates：策略候选真源
- 新增 runtime_policy_candidate_validations：shadow / canary / rollback 验证事实表
- terminal run (completed/failed/canceled) 现在会自动触发 outcome evaluator
- restore_run_checkpoint() 触发 rollback 后也会进入 learning cycle
- 已新增 Tauri command：agent_run_list_policy_candidates / agent_run_get_policy_candidate / agent_run_validate_policy_candidate_shadow / agent_run_prepare_policy_candidate_canary / agent_run_apply_policy_candidate_canary / agent_run_rollback_policy_candidate
- 已新增 observability 事件：outcome_scored / reflection_generated / policy_candidate_generated / policy_shadow_validated / policy_canary_applied / policy_rollback_completed
当前已经落地的复盘输出包括：
- root_cause
- affected_subsystem
- recommended_memory_writeback
- recommended_policy_update
- recommended_workflow_extraction
- recommended_skill_gap_analysis
当前 recommended_memory_writeback 已经不只是 reflection 字段：
- 会自动生成 memory writeback candidate
- 可经 Tauri command / 前端控制面触发真正写回长期记忆
当前已经落地的策略验证链包括：
- shadow_pending -> shadow_passed | shadow_failed
- shadow_passed -> canary_ready -> canary_applied
- shadow_passed | canary_ready | canary_applied -> rolled_back
- get_runtime_policy_candidate() 会返回候选详情和全部验证记录
已新增策略候选自动执行器：
- runtime 启动时会拉起 policy_candidate_scheduler
- 单次 learning cycle 结束后也会自动推进当前 run 的策略候选
- 后续失败 / restore 会自动回滚旧的 canary policy candidate
Phase C 现在还新增了 failure pattern clustering：
- 新增 runtime_failure_patterns：失败模式聚类真源
- record_run_learning_cycle() 会在 reflection 后继续聚合失败模式
- 已新增 Tauri command：agent_run_list_failure_patterns
- 已新增 observability 事件：failure_pattern_clustered
Phase D 已经进入第一批结构化闭环：
- 新增 runtime_behavior_traces：行为轨迹真源
- 新增 runtime_skill_gap_analyses：技能缺口分析真源
- 新增 runtime_skill_recommendations：技能 / workflow 推荐真源
- record_run_learning_cycle() 现在会继续触发 skills evolution cycle
- 已新增 Tauri command：skill_list_behavior_traces / skill_list_gap_analyses / skill_list_recommendations / skill_get_recommendation
- 已新增 observability 事件：behavior_trace_mined / skill_gap_detected / skill_recommendation_generated
当前已经落地的 Phase D 第一层能力：
- 采集 run 内部工具序列、重复约束、人工补救动作
- 依据重复频率和已有技能绑定情况区分 knowledge_gap / workflow_gap / skill_gap / policy_gap
- 在没有现成技能时产出 draft_pending 的本地技能草案建议
- 在已有技能注册表命中时产出绑定现有技能的建议
Phase D 第二层已补到“生命周期可操作”：
- 新增 runtime_skill_recommendation_validations：技能推荐生命周期验证事实表
- 新增 runtime_skill_versions：技能正式升级 / 版本治理真源
- 推荐结果现在可以走 draft_generated -> validated -> shadow_ready -> shadow_active -> canary_ready -> canary_applied -> live -> rolled_back / retired
- 已新增 Tauri command：
  - skill_generate_recommendation_draft
  - skill_validate_recommendation
  - skill_prepare_recommendation_shadow
  - skill_apply_recommendation_shadow
  - skill_prepare_recommendation_canary
  - skill_apply_recommendation_canary
  - skill_promote_recommendation_to_live
  - skill_list_versions
  - skill_rollback_recommendation
  - skill_retire_recommendation
- 已新增 observability 事件：
  - skill_draft_generated
  - skill_validation_completed
  - skill_shadow_run_completed
  - skill_canary_applied
  - skill_promoted_to_live
  - skill_rollback_completed
  - skill_retired
已新增技能 rollout 自动执行器：
- runtime 启动时会拉起 skill_rollout_scheduler
- 单次 learning cycle 结束后会自动把 recommendation 尽量推进到当前可达的最远状态
- 后续失败 / restore 会自动回滚旧的 canary_applied / live recommendation
技能环境兼容性 gating 已经从“只看 skill validator”补强为：
- host os
- workspace markers
- required sandbox
- bin / env / path
- workspace write access
- container / virtualenv / remote host
- remote_executor_protocol / required_remote_capabilities
- recommendation 如果已经拿到 SKILL.md 路径，会优先按路径解析
- 因此推荐验证不再只是“文件合法”，而是开始校验“宿主能不能跑”
外部执行器现在已经补进实时协商链：
- runtime 启动时会拉起 remote_executor_handshake_scheduler
- 优先通过 POST /handshake 发送本地 runtime 能力、版本和工作区上下文
- 如果远端不支持 handshake，会退回 GET /capabilities + /health
- 协商结果会进入 runtime cache，并反映到 health / compatibility probe / diagnostics
前端诊断中心现在已经补了“学习与技能演化”控制面：
- 展示长期记忆 writeback 候选
- 展示 policy candidate
- 展示 skill recommendation
- 支持手动 heartbeat review / 写回长期记忆 / 推进 candidate 生命周期 / 手动触发一轮自动推进
设置中心现在已经补了“记忆与成长”页签：
- 普通用户可以直接录入纠错
- 可以手动触发 heartbeat review
- 可以查看用户画像摘要与关系图谱摘要
当前仍然保留的简化项：
- 设置中心目前还是“轻产品页 + 控制面”形态，还不是完整的记忆成长中心
- rollout compatibility 目前已经补到“本地动态宿主探测 + 远程服务端实时协商”
- 但远端协议仍然以 HTTP JSON handshake 为主，不是更复杂的长连接协商
- relationship ontology 已经补到“实体注册 + 多跳边 + 跨会话聚合”，但实体消歧与别名学习还可以继续增强

4. 聊天 UI 结构化契约

消息规则

用户消息：右侧气泡
assistant 正文：非气泡全宽内容区
system：轻量状态条

运行细节规则

细节卡片：Thinking/ToolCall/ToolResult/ContextCompact/Workflow/McpStatus/RunStatus/Error
运行中（running|paused）：默认展开
终态（completed|failed|canceled）：800ms 自动折叠
用户 pin（钉住）后：保持展开，不自动折叠

独立交互

TodoCard：任务状态交互
QuestionCard：回答后自动触发 agent_run_resume

5. MCP 与技能

MCP

支持 stdio / http
状态机：created/testing/connected/degraded/disconnected/failed
支持测试连接、手动连接/断开、自动重连、工具刷新、心跳时间展示
MCP 工具默认审批策略：required

技能

扫描 SKILL.md（含 frontmatter）
依赖校验：缺 bin/env/path 时返回标准化原因
绑定策略：summary_only/on_demand/always/full
支持 bind/unbind，并写回同步 outbox

6. 当前验证命令（2026-03-13）

bash

# desktop 工作区
cd desktop
npm run test
npm run build

# 桌面 runtime
cd apps/gui/src-tauri
cargo check

# 后端
cd ../../../backend
go build ./...
go test ./...

当前仓库在当前阶段更建议按下面的思路理解：

desktop/ 是继续演进的主工作区
apps/gui/src-tauri 是当前桌面 runtime 入口
历史 archive/desktop-legacy/ 命令只保留作演进背景参考，不再作为默认开发入口

当前仍需单独说明：

cd desktop && npm run tauri:build 需要完整桌面构建环境，签名相关配置不足时会失败
Phase B Memory & User Model、Phase C Learning & Reflection、Phase D Skill Evolution 的核心闭环已经落地，但仍然保留若干简化项，不应写成“所有治理深度都已封顶”

Workova Agent 当前架构说明（2026-03-13） ​

1. 架构边界（已锁定） ​

客户端（桌面端，唯一执行真源） ​

后端（仅存储与转发） ​

明确禁止（后端） ​

2. 同步协议（硬切到 changes[]） ​

Push 请求 ​

Pull 响应 ​

冲突规则（服务端固定实现） ​

3. 客户端 Agent 能力清单 ​

内置工具（默认内建） ​

权限与审批 ​

沙箱模式 ​

运行时恢复点（2026-03-13 当前状态） ​

长期记忆与自我进化（2026-03-13 当前状态） ​

4. 聊天 UI 结构化契约 ​

消息规则 ​

运行细节规则 ​

独立交互 ​

5. MCP 与技能 ​

MCP ​

技能 ​

6. 当前验证命令（2026-03-13） ​

Workova Agent 当前架构说明（2026-03-13）

1. 架构边界（已锁定）

客户端（桌面端，唯一执行真源）

后端（仅存储与转发）

明确禁止（后端）

2. 同步协议（硬切到 `changes[]`）

Push 请求

Pull 响应

冲突规则（服务端固定实现）

3. 客户端 Agent 能力清单

内置工具（默认内建）

权限与审批

沙箱模式

运行时恢复点（2026-03-13 当前状态）

长期记忆与自我进化（2026-03-13 当前状态）

4. 聊天 UI 结构化契约

消息规则

运行细节规则

独立交互

5. MCP 与技能

MCP

技能

6. 当前验证命令（2026-03-13）