1362 lines
58 KiB
Markdown
1362 lines
58 KiB
Markdown
# L3 — 数据流与 Skill 体系层
|
||
|
||
**文档版本**: 1.0
|
||
**适用项目**: sgClaw (业数融合一平台 AI Agent 底座)
|
||
**编制日期**: 2026-03-03
|
||
|
||
**读者**: 高级开发者、Skill 开发者 —— 需要理解 Agent 内部数据流转、编写业务 Skill、集成 LLM、
|
||
调优感知层和记忆系统。
|
||
|
||
---
|
||
|
||
## 1. 核心数据流时序
|
||
|
||
### 1.1 端到端数据流全景
|
||
|
||
一次完整的用户任务执行涉及以下数据流转路径。从用户在 Side Panel 输入自然语言指令开始，
|
||
到最终任务完成结果返回，数据流经前端 → C++ → Pipe → Rust → LLM → Pipe → C++ → DOM。
|
||
|
||
```
|
||
用户输入 结果展示
|
||
"导出本月合规报表" "已导出3份报表"
|
||
│ ▲
|
||
▼ │
|
||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||
│ Side Panel (Vue) │
|
||
│ AgentControlPanel.vue │
|
||
│ ├─ sgFunctionsUI('sgclaw_submit_task', { instruction: "..." }) │
|
||
│ └─ 接收 onLogEntry / onTaskCompleted 事件 │
|
||
└──────────────┬────────────────────────────────────────────────┬────────────┘
|
||
│ FunctionsUI IPC ▲ ExecuteJS push
|
||
▼ │
|
||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||
│ C++ Browser Process │
|
||
│ │
|
||
│ SgClawProcessHost │
|
||
│ ├─ 将 instruction 封装为 pipe submit_task 消息 │
|
||
│ ├─ PipeListener 接收 sgClaw 的 command 消息 │
|
||
│ ├─ MAC Whitelist Check 校验 │
|
||
│ └─→ CommandRouter → CdpCommandExecutor → 页面 DOM 操作 │
|
||
│ │
|
||
│ 响应路径: │
|
||
│ CommandRouter result → PipeWriter → sgClaw │
|
||
│ + AOM Snapshot (操作后的页面状态快照) │
|
||
└──────────────┬────────────────────────────────────────────────┬────────────┘
|
||
│ STDIO Pipe (JSON Line) ▲
|
||
▼ │
|
||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||
│ sgClaw Rust Process │
|
||
│ │
|
||
│ ┌──────────────────────────────────────────────────────────────┐ │
|
||
│ │ Agent Runtime (ReAct Loop) │ │
|
||
│ │ │ │
|
||
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
|
||
│ │ │ THINK │───→│ ACT │───→│ OBSERVE │──┐ │ │
|
||
│ │ │ │ │ │ │ │ │ │ │
|
||
│ │ │ LLM 推理 │ │ 执行工具 │ │ 解析结果 │ │ │ │
|
||
│ │ │ 生成计划 │ │ 发送命令 │ │ 更新记忆 │ │ │ │
|
||
│ │ └──────────┘ └──────────┘ └──────────┘ │ │ │
|
||
│ │ ▲ │ │ │
|
||
│ │ └──── Critic 评估 ◄──────────────────────┘ │ │
|
||
│ │ │ OK → 继续循环 │ │
|
||
│ │ │ Abort → 终止任务 │ │
|
||
│ └──────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ 数据交互: │
|
||
│ ├─ BrowserPipeTool ──→ Pipe ──→ Browser (command) │
|
||
│ ├─ LLM Provider ──→ HTTP(S) ──→ Claude / GPT / Ollama │
|
||
│ ├─ Memory ──→ SQLite (本地文件) │
|
||
│ └─ SkillLoader ──→ 文件系统 (技能脚本) │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 1.2 单步数据流详解
|
||
|
||
Agent 每一步（ReAct loop 的一次迭代）的数据流如下：
|
||
|
||
```
|
||
Step N 开始
|
||
│
|
||
├── 1. 构造 LLM 输入
|
||
│ ├── system_prompt (模板渲染)
|
||
│ │ ├── 可用工具描述 (BrowserPipeTool + MCP tools)
|
||
│ │ ├── 可用技能列表 (SkillLoader.list_skills())
|
||
│ │ ├── 安全约束说明
|
||
│ │ └── 当前会话 trace_id
|
||
│ │
|
||
│ ├── messages (对话历史)
|
||
│ │ ├── 短期记忆 (最近 N 条, token 截断)
|
||
│ │ └── 长期记忆检索结果 (语义相关的历史经验)
|
||
│ │
|
||
│ └── tools (工具定义)
|
||
│ ├── browser_action: { 参数 JSON Schema }
|
||
│ └── mcp_tools: [外部工具列表]
|
||
│
|
||
├── 2. 调用 LLM (THINK)
|
||
│ ├── → HTTP(S) → Claude API / OpenAI API / Ollama
|
||
│ ├── ← streaming chunks (thinking + tool_call)
|
||
│ └── 解析 LLM 输出:
|
||
│ ├── 纯文本 → 最终回答 (任务完成)
|
||
│ └── tool_call → 继续执行
|
||
│
|
||
├── 3. 执行工具调用 (ACT)
|
||
│ │
|
||
│ ├── [browser_action] BrowserPipeTool.execute()
|
||
│ │ ├── MAC Policy 校验 (Rust 层)
|
||
│ │ ├── 构造 pipe command JSON
|
||
│ │ │ { seq: N, type: "command", action: "click",
|
||
│ │ │ params: { selector: "#btn" },
|
||
│ │ │ security: { expected_domain: "erp.example.com", hmac: "..." } }
|
||
│ │ ├── 写入 stdout (→ pipe → Browser)
|
||
│ │ └── 等待 response (← pipe ← Browser)
|
||
│ │ { seq: N, type: "response", success: true,
|
||
│ │ data: { clicked: true },
|
||
│ │ aom_snapshot: [...] }
|
||
│ │
|
||
│ └── [mcp_tool] McpClientManager.call_tool()
|
||
│ ├── STDIO → MCP Server
|
||
│ └── ← tool result JSON
|
||
│
|
||
├── 4. 处理结果 (OBSERVE)
|
||
│ ├── 格式化 observation 文本
|
||
│ │ ├── 操作成功/失败
|
||
│ │ ├── 结果数据摘要
|
||
│ │ └── AOM 快照 (页面状态描述)
|
||
│ │
|
||
│ ├── 存入短期记忆
|
||
│ └── 追加到 messages 历史
|
||
│
|
||
├── 5. 质量评估 (CRITIC)
|
||
│ ├── 检查操作成功/失败
|
||
│ ├── 检查是否重复操作 (死循环检测)
|
||
│ ├── 检查任务时长
|
||
│ └── 更新 Circuit Breaker 状态
|
||
│
|
||
└── Step N 结束 → Step N+1 或 任务完成
|
||
```
|
||
|
||
### 1.3 数据格式在各阶段的变换
|
||
|
||
```
|
||
阶段 数据格式 示例
|
||
──────────── ──────────────────────────── ──────────────────────────────
|
||
用户输入 自然语言字符串 "导出本月合规报表"
|
||
│
|
||
▼
|
||
LLM 输入 Message[] + ToolDef[] { role: "user", content: "..." }
|
||
│
|
||
▼
|
||
LLM 输出 ToolCall { name: "browser_action",
|
||
│ arguments: { action: "click", ... } }
|
||
▼
|
||
Pipe 命令 JSON Line {"seq":1,"type":"command","action":"click",...}
|
||
│
|
||
▼
|
||
C++ 内部 base::Value (Dict) CommandRouter 参数字典
|
||
│
|
||
▼
|
||
DOM 操作 CDP / JS 执行 document.querySelector('#btn').click()
|
||
│
|
||
▼
|
||
DOM 结果 CDP 返回值 { "result": { "type": "undefined" } }
|
||
│
|
||
▼
|
||
Pipe 响应 JSON Line {"seq":1,"type":"response","success":true,...}
|
||
│
|
||
▼
|
||
Observation 格式化文本 "操作成功：点击了'提交'按钮。\n当前页面..."
|
||
│
|
||
▼
|
||
LLM 下一轮 Message (role: "tool") { role: "tool", content: "操作成功：..." }
|
||
```
|
||
|
||
---
|
||
|
||
## 2. Agent 循环详解
|
||
|
||
### 2.1 ReAct 循环模型
|
||
|
||
sgClaw 采用 ReAct（Reasoning + Acting）循环模型，这是当前 AI Agent 领域最成熟的执行范式。
|
||
核心思想：让 LLM 交替进行推理（Reasoning）和行动（Acting），每次行动后观察结果，
|
||
再决定下一步。
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ ReAct 循环 │
|
||
│ │
|
||
│ ┌──────────┐ │
|
||
│ │ 用户指令 │ │
|
||
│ └─────┬────┘ │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||
│ │ │ │ │ │ │ │
|
||
│ ┌─→│ THINK │────→│ ACT │────→│ OBSERVE │──┐ │
|
||
│ │ │ │ │ │ │ │ │ │
|
||
│ │ │ 推理下一步│ │ 调用工具 │ │ 读取结果 │ │ │
|
||
│ │ │ 生成计划 │ │ 执行操作 │ │ 理解状态 │ │ │
|
||
│ │ └──────────┘ └──────────┘ └──────────┘ │ │
|
||
│ │ │ │
|
||
│ │ ┌──────────┐ │ │
|
||
│ └─────────│ CRITIC │◄─────────────────────────────┘ │
|
||
│ │ │ │
|
||
│ │ 质量评估 │ │
|
||
│ │ 熔断检查 │ │
|
||
│ └────┬─────┘ │
|
||
│ │ │
|
||
│ OK → 继续 │
|
||
│ Abort → 终止 │
|
||
│ Done → 返回结果 │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 2.2 System Prompt 模板
|
||
|
||
Agent 的行为由 System Prompt 定义。以下是 sgClaw 的 System Prompt 模板结构：
|
||
|
||
```
|
||
你是 sgClaw，一个运行在 SuperRPA 浏览器中的 AI 助手。你的任务是帮助用户在企业业务系统
|
||
中完成自动化操作。
|
||
|
||
## 身份与角色
|
||
- 你运行在国家电网"业数融合一平台"的 SuperRPA 浏览器中
|
||
- 你可以操控浏览器中打开的业务系统页面（ERP、OA、财务、HR 等）
|
||
- 你的每个操作都会被审计记录，trace_id: {{trace_id}}
|
||
|
||
## 可用工具
|
||
你有一个核心工具 `browser_action`，支持以下操作：
|
||
{{#each tools}}
|
||
### {{this.name}}
|
||
{{this.description}}
|
||
参数: {{this.parameters}}
|
||
{{/each}}
|
||
|
||
## 可用技能
|
||
以下是预置的业务技能脚本，当任务匹配时优先使用：
|
||
{{#each skills}}
|
||
- **{{this.name}}** (v{{this.version}}): {{this.description}}
|
||
适用域名: {{this.domains}}
|
||
{{/each}}
|
||
|
||
## 安全约束
|
||
1. 只能操作以下域名的页面: {{allowed_domains}}
|
||
2. 每个 browser_action 调用必须指定 expected_domain
|
||
3. 禁止尝试执行 eval、executeJsInPage 等操作
|
||
4. 涉及登录、登出、清空存储的操作会请求用户确认
|
||
5. 不要尝试读取或猜测用户密码
|
||
|
||
## 执行策略
|
||
1. 先观察当前页面状态 (getAomSnapshot)
|
||
2. 制定执行计划，分步骤完成
|
||
3. 每步操作后检查结果
|
||
4. 遇到异常时尝试恢复（最多重试 3 次）
|
||
5. 任务完成后提供简明的执行摘要
|
||
|
||
## 输出格式
|
||
- 思考过程用自然语言描述
|
||
- 操作通过 tool_call 执行
|
||
- 最终结果用中文文本总结
|
||
```
|
||
|
||
### 2.3 消息历史管理策略
|
||
|
||
Agent 的 LLM 调用需要发送对话历史（messages），但上下文窗口有限。
|
||
sgClaw 采用分层记忆策略管理消息历史：
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────┐
|
||
│ LLM 上下文窗口 (如 200K tokens) │
|
||
│ │
|
||
│ ┌─ System Prompt ────────────────────────────────────────┐ │
|
||
│ │ ~2000 tokens (固定) │ │
|
||
│ │ 工具定义 + 技能列表 + 安全约束 + 执行策略 │ │
|
||
│ └────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌─ 长期记忆检索 ─────────────────────────────────────────┐ │
|
||
│ │ ~1000 tokens (按相关度检索) │ │
|
||
│ │ 相似任务的历史经验、成功的操作路径 │ │
|
||
│ └────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌─ 短期对话记忆 ─────────────────────────────────────────┐ │
|
||
│ │ 动态大小 (剩余 token 预算) │ │
|
||
│ │ │ │
|
||
│ │ ┌─ 最近 N 步完整记录 ──────────────────────────────┐ │ │
|
||
│ │ │ Step K: thinking + action + observation │ │ │
|
||
│ │ │ Step K+1: thinking + action + observation │ │ │
|
||
│ │ │ ... │ │ │
|
||
│ │ │ Step N: thinking + action + observation │ │ │
|
||
│ │ └──────────────────────────────────────────────────┘ │ │
|
||
│ │ │ │
|
||
│ │ ┌─ 更早步骤的压缩摘要 ─────────────────────────────┐ │ │
|
||
│ │ │ "Steps 1-5: 登录 ERP，导航到报表模块， │ │ │
|
||
│ │ │ 设置了时间范围为本月" │ │ │
|
||
│ │ └──────────────────────────────────────────────────┘ │ │
|
||
│ │ │ │
|
||
│ └────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌─ 当前用户指令 ─────────────────────────────────────────┐ │
|
||
│ │ ~100 tokens │ │
|
||
│ │ "导出本月合规报表" │ │
|
||
│ └────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
└──────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
**Token 预算分配**：
|
||
|
||
| 区域 | Token 预算 | 策略 |
|
||
|------|-----------|------|
|
||
| System Prompt | ~2000 | 固定，编译时确定 |
|
||
| 长期记忆检索 | ~1000 | 按语义相关度排序取 top-3 |
|
||
| 短期对话记忆 | 剩余空间 | 最近步骤完整保留，早期步骤压缩 |
|
||
| 用户指令 | ~100 | 原文保留 |
|
||
| LLM 生成预留 | ~4096 | max_tokens 参数 |
|
||
|
||
**短期记忆截断算法**：
|
||
|
||
```
|
||
truncate_messages(messages, token_budget):
|
||
// 1. 保留最近 5 步完整记录
|
||
recent = messages[-5:]
|
||
recent_tokens = count_tokens(recent)
|
||
|
||
// 2. 如果最近 5 步已超预算，减少保留数
|
||
while recent_tokens > token_budget * 0.8 and len(recent) > 2:
|
||
recent = recent[-len(recent)+1:]
|
||
recent_tokens = count_tokens(recent)
|
||
|
||
// 3. 对更早的步骤生成压缩摘要
|
||
remaining_budget = token_budget - recent_tokens
|
||
older = messages[:-len(recent)]
|
||
if older:
|
||
summary = compress_steps(older, remaining_budget)
|
||
return [summary_message] + recent
|
||
else:
|
||
return recent
|
||
```
|
||
|
||
### 2.4 任务生命周期状态机
|
||
|
||
```
|
||
┌────────────────────────────┐
|
||
│ TaskState Machine │
|
||
└────────────────────────────┘
|
||
|
||
┌─────────┐
|
||
│ Idle │
|
||
└────┬────┘
|
||
│ submit_task(instruction)
|
||
▼
|
||
┌─────────┐
|
||
│Planning │ ← LLM 分析指令，生成初步计划
|
||
└────┬────┘
|
||
│ 计划生成完成
|
||
▼
|
||
┌─────────┐
|
||
┌───→│Executing│◄───┐
|
||
│ └────┬────┘ │
|
||
│ │ │
|
||
│ ┌────┴────┐ │
|
||
│ │Step N │ │
|
||
│ │executing│ │
|
||
│ └────┬────┘ │
|
||
│ │ │
|
||
│ ┌────┴────┐ │
|
||
│ │Waiting │ │ step OK, more to do
|
||
│ │for resp │ │
|
||
│ └────┬────┘ │
|
||
│ │ │
|
||
│ ┌────┴────┐ │
|
||
│ │Observing│────┘
|
||
│ └────┬────┘
|
||
│ │
|
||
│ ┌────┴────┐
|
||
│ │Confirm? │ ← human-in-the-loop
|
||
│ └──┬───┬──┘
|
||
│ yes │ │ no (auto-proceed)
|
||
│ │ │
|
||
│ ┌──┴───┴──┐
|
||
└────│Evaluate │
|
||
└────┬────┘
|
||
│
|
||
┌─────────┼─────────┐
|
||
│ │ │
|
||
▼ ▼ ▼
|
||
┌─────────┐ ┌──────┐ ┌────────┐
|
||
│Completed│ │Failed│ │Aborted │
|
||
│ (成功) │ │(失败) │ │(用户终止)│
|
||
└─────────┘ └──────┘ └────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 3. Skill 体系
|
||
|
||
### 3.1 Skill 定义格式
|
||
|
||
每个 Skill 是一个 JavaScript 文件，包含元数据头和执行函数。
|
||
|
||
**完整 Skill 文件结构**：
|
||
|
||
```javascript
|
||
/**
|
||
* @skill erp-monthly-report
|
||
* @version 1.0.0
|
||
* @description 从ERP系统导出月度财务报表。支持按部门、科目筛选，
|
||
* 自动处理分页数据，合并导出为完整报表。
|
||
* @domains erp.example.com, erp-test.example.com
|
||
* @author sgClaw Team
|
||
* @params {
|
||
* "type": "object",
|
||
* "required": ["month"],
|
||
* "properties": {
|
||
* "month": {
|
||
* "type": "string",
|
||
* "pattern": "^\\d{4}-\\d{2}$",
|
||
* "description": "报表月份 (如 2026-03)"
|
||
* },
|
||
* "department": {
|
||
* "type": "string",
|
||
* "description": "部门名称 (可选, 不填则导出全部)"
|
||
* },
|
||
* "format": {
|
||
* "type": "string",
|
||
* "enum": ["xlsx", "csv", "pdf"],
|
||
* "default": "xlsx",
|
||
* "description": "导出格式"
|
||
* }
|
||
* }
|
||
* }
|
||
*/
|
||
|
||
/**
|
||
* 技能执行入口
|
||
* @param {object} params - 输入参数 (符合上方 @params 定义)
|
||
* @param {function} browserAction - BrowserAction 调用函数
|
||
* @returns {object} 执行结果 { success: boolean, data?: any, error?: string }
|
||
*/
|
||
async function execute(params, browserAction) {
|
||
const { month, department, format = 'xlsx' } = params;
|
||
|
||
try {
|
||
// Step 1: 导航到 ERP 报表页面
|
||
await browserAction('navigate', 'https://erp.example.com/report/finance');
|
||
await browserAction('waitForSelector', '.report-filter', 5000);
|
||
|
||
// Step 2: 设置筛选条件
|
||
await browserAction('click', '#month-picker');
|
||
await browserAction('type', '#month-input', month);
|
||
|
||
if (department) {
|
||
await browserAction('click', '#dept-selector');
|
||
await browserAction('type', '#dept-search', department);
|
||
await browserAction('click', `.dept-option[data-name="${department}"]`);
|
||
}
|
||
|
||
// Step 3: 选择导出格式
|
||
await browserAction('select', '#export-format', format);
|
||
|
||
// Step 4: 点击导出
|
||
await browserAction('click', '#export-btn');
|
||
|
||
// Step 5: 等待导出完成
|
||
await browserAction('waitForSelector', '.export-success', 30000);
|
||
|
||
// Step 6: 获取结果信息
|
||
const resultText = await browserAction('getText', '.export-result');
|
||
|
||
return {
|
||
success: true,
|
||
data: {
|
||
message: resultText,
|
||
month: month,
|
||
department: department || '全部',
|
||
format: format
|
||
}
|
||
};
|
||
|
||
} catch (error) {
|
||
return {
|
||
success: false,
|
||
error: `导出报表失败: ${error.message}`
|
||
};
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.2 Skill 仓库结构
|
||
|
||
```
|
||
sgclaw-skills/
|
||
├── registry.json # 技能清单 (签名 + 哈希索引)
|
||
├── builtin/ # 内置技能 (随产品交付)
|
||
│ ├── erp-monthly-report.js # ERP 月度报表导出
|
||
│ ├── erp-anomaly-check.js # ERP 异常交易检查
|
||
│ ├── oa-approval.js # OA 审批单处理
|
||
│ ├── oa-meeting-schedule.js # OA 会议日程管理
|
||
│ ├── finance-compliance.js # 财务合规线索提报
|
||
│ ├── finance-reconciliation.js # 财务对账
|
||
│ ├── hr-social-insurance.js # 人力社保申报
|
||
│ ├── hr-salary-check.js # 薪酬数据核验
|
||
│ ├── legal-contract-monitor.js # 合同履约监测
|
||
│ └── cross-system-sync.js # 跨系统数据同步
|
||
│
|
||
├── custom/ # 用户自定义技能
|
||
│ └── (用户创建的 .js 文件)
|
||
│
|
||
└── keys/
|
||
└── skill_verify.pub # Ed25519 公钥 (校验签名)
|
||
```
|
||
|
||
**registry.json 格式**：
|
||
|
||
```json
|
||
{
|
||
"version": "1.0",
|
||
"updated_at": "2026-03-03T00:00:00Z",
|
||
"skills": [
|
||
{
|
||
"name": "erp-monthly-report",
|
||
"file": "builtin/erp-monthly-report.js",
|
||
"version": "1.0.0",
|
||
"hash": "sha256:a1b2c3d4e5f6...",
|
||
"signature": "ed25519:x7y8z9...",
|
||
"enabled": true
|
||
},
|
||
{
|
||
"name": "oa-approval",
|
||
"file": "builtin/oa-approval.js",
|
||
"version": "1.2.0",
|
||
"hash": "sha256:f6e5d4c3b2a1...",
|
||
"signature": "ed25519:z9y8x7...",
|
||
"enabled": true
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 3.3 Skill 生命周期
|
||
|
||
```
|
||
┌─────────────┐
|
||
│ 开发阶段 │
|
||
│ (JS 编写) │
|
||
└──────┬──────┘
|
||
│
|
||
▼
|
||
┌─────────────┐
|
||
│ 签名阶段 │
|
||
│ 构建系统 │
|
||
│ Ed25519 签名│
|
||
│ SHA-256 哈希│
|
||
└──────┬──────┘
|
||
│
|
||
▼
|
||
┌─────────────┐
|
||
│ 发布阶段 │
|
||
│ 更新 │
|
||
│ registry │
|
||
│ .json │
|
||
└──────┬──────┘
|
||
│
|
||
▼
|
||
┌─────────────┐
|
||
│ 部署阶段 │
|
||
│ 放入 │
|
||
│ sgclaw- │
|
||
│ skills/ │
|
||
└──────┬──────┘
|
||
│
|
||
▼
|
||
┌─────────────┐
|
||
│ 加载阶段 │
|
||
│ sgClaw 启动 │
|
||
│ 校验签名 │
|
||
│ 校验哈希 │
|
||
│ 解析元数据 │
|
||
│ 注册到 Agent│
|
||
└──────┬──────┘
|
||
│
|
||
▼
|
||
┌─────────────┐
|
||
│ 执行阶段 │ ← Agent ReAct 循环中 LLM 选择使用
|
||
│ Agent 调用 │
|
||
│ 传入 params │
|
||
│ + browser │
|
||
│ Action 引用 │
|
||
└──────┬──────┘
|
||
│
|
||
▼
|
||
┌─────────────┐
|
||
│ 沉淀阶段 │ ← 执行结果存入 Memory
|
||
│ 记录经验 │
|
||
│ 成功率统计 │
|
||
│ 供后续复用 │
|
||
└─────────────┘
|
||
```
|
||
|
||
### 3.4 从现有 JS 场景代码迁移到 Skill
|
||
|
||
SuperRPA 已有大量 agent-vue 中的 JS 场景代码（49 个文件，208+ 个调用点）。
|
||
这些代码可以迁移为 sgClaw Skill，实现复用。
|
||
|
||
**迁移策略**：
|
||
|
||
| 阶段 | 内容 | 说明 |
|
||
|------|------|------|
|
||
| **Phase 1: 直接复用** | 现有 JS 代码通过 BrowserAction API 调用 | sgClaw 发送 pipe 命令 → Browser 执行 → JS SDK 代码无需改动 |
|
||
| **Phase 2: 技能化封装** | 将高频场景代码提取为 Skill | 添加元数据头、参数 schema、错误处理 |
|
||
| **Phase 3: LLM 增强** | Skill 作为 Agent 的工具选项 | LLM 根据用户指令自动选择合适的 Skill |
|
||
|
||
**迁移示例**：将 agent-vue 中的 OA 审批代码迁移为 Skill
|
||
|
||
现有代码（agent-vue 中）：
|
||
|
||
```javascript
|
||
// agent-vue/src/scenes/oa-approval.js
|
||
async function approveAll() {
|
||
await sgBrowser.page.navigate('https://oa.example.com/approval/pending');
|
||
await sgBrowser.page.waitForSelector('.approval-list');
|
||
const items = await sgBrowser.page.getText('.approval-list .item');
|
||
for (const item of items) {
|
||
await sgBrowser.input.click(`.item[data-id="${item.id}"] .approve-btn`);
|
||
await sgBrowser.page.waitForSelector('.confirm-dialog');
|
||
await sgBrowser.input.click('.confirm-dialog .ok-btn');
|
||
}
|
||
}
|
||
```
|
||
|
||
迁移后的 Skill：
|
||
|
||
```javascript
|
||
/**
|
||
* @skill oa-approval
|
||
* @version 1.0.0
|
||
* @description OA系统待审批单据批量处理。支持查看待审批列表、
|
||
* 批量审批、批量驳回、添加审批意见。
|
||
* @domains oa.example.com, oa-test.example.com
|
||
* @params {
|
||
* "type": "object",
|
||
* "required": ["action"],
|
||
* "properties": {
|
||
* "action": { "enum": ["list", "approve_all", "reject", "approve_one"] },
|
||
* "item_id": { "type": "string", "description": "单据ID (approve_one/reject 时需要)" },
|
||
* "opinion": { "type": "string", "description": "审批意见 (可选)" }
|
||
* }
|
||
* }
|
||
*/
|
||
async function execute(params, browserAction) {
|
||
const { action, item_id, opinion } = params;
|
||
|
||
// 导航到审批页面
|
||
await browserAction('navigate', 'https://oa.example.com/approval/pending');
|
||
await browserAction('waitForSelector', '.approval-list', 5000);
|
||
|
||
switch (action) {
|
||
case 'list': {
|
||
const text = await browserAction('getText', '.approval-list');
|
||
return { success: true, data: { items: text } };
|
||
}
|
||
case 'approve_all': {
|
||
// 获取所有待审批项
|
||
const snapshot = await browserAction('getAomSnapshot', '.approval-list');
|
||
let count = 0;
|
||
|
||
// 逐个审批 (带错误处理)
|
||
for (const item of snapshot) {
|
||
try {
|
||
await browserAction('click', `.item[data-id="${item.name}"] .approve-btn`);
|
||
await browserAction('waitForSelector', '.confirm-dialog', 3000);
|
||
if (opinion) {
|
||
await browserAction('type', '.opinion-input', opinion);
|
||
}
|
||
await browserAction('click', '.confirm-dialog .ok-btn');
|
||
await browserAction('waitForSelector', '.success-toast', 3000);
|
||
count++;
|
||
} catch (e) {
|
||
// 单条失败不影响整体
|
||
continue;
|
||
}
|
||
}
|
||
|
||
return { success: true, data: { approved: count, total: snapshot.length } };
|
||
}
|
||
// ... 其他 action
|
||
}
|
||
}
|
||
```
|
||
|
||
**迁移改动点总结**：
|
||
|
||
| 改动项 | 说明 |
|
||
|-------|------|
|
||
| 添加元数据头 | `@skill`, `@version`, `@description`, `@domains`, `@params` |
|
||
| 函数签名统一 | `async function execute(params, browserAction)` |
|
||
| API 调用方式 | `sgBrowser.page.navigate(url)` → `browserAction('navigate', url)` |
|
||
| 错误处理 | 添加 try/catch，返回统一格式 `{ success, data, error }` |
|
||
| 参数化 | 硬编码值改为 params 输入 |
|
||
|
||
### 3.5 Skill 执行沙箱
|
||
|
||
Skill 的 JS 脚本需要在受限环境中执行，防止恶意代码突破安全边界。
|
||
|
||
**沙箱约束**：
|
||
|
||
| 能力 | 是否允许 | 说明 |
|
||
|------|---------|------|
|
||
| `browserAction()` | 允许 | 唯一的外部交互方式，受 MAC 策略约束 |
|
||
| `console.log/error` | 允许 | 输出到 Agent 日志 |
|
||
| `JSON.parse/stringify` | 允许 | 数据处理必需 |
|
||
| `Promise / async-await` | 允许 | 异步控制流必需 |
|
||
| `setTimeout / setInterval` | 允许 (受限) | 最大延迟 30s，用于等待 |
|
||
| `fetch / XMLHttpRequest` | **禁止** | 网络请求必须通过 browserAction |
|
||
| `require / import` | **禁止** | 不允许加载外部模块 |
|
||
| `process / child_process` | **禁止** | 不允许访问系统进程 |
|
||
| `fs / path` | **禁止** | 不允许访问文件系统 |
|
||
| `eval / Function()` | **禁止** | 不允许动态代码执行 |
|
||
|
||
**实现方案**：
|
||
|
||
sgClaw 使用轻量级 JS 引擎（如 Boa 或 embedded V8 via Rusty_V8）运行 Skill 脚本，
|
||
在创建执行上下文时仅注入允许的全局对象：
|
||
|
||
```rust
|
||
// Skill 沙箱执行 (概念代码)
|
||
fn execute_skill(script: &str, params: Value, browser_tool: &BrowserPipeTool) -> Result<Value> {
|
||
let mut context = JsContext::new();
|
||
|
||
// 仅注入允许的全局对象
|
||
context.register_global("browserAction", |args| {
|
||
// 代理到 BrowserPipeTool.execute()
|
||
browser_tool.execute(args)
|
||
});
|
||
context.register_global("console", ConsoleProxy::new());
|
||
context.register_global("JSON", JsonGlobal::new());
|
||
context.register_global("Promise", PromiseGlobal::new());
|
||
|
||
// 禁止所有其他全局对象
|
||
// (JsContext 默认不提供 Node.js / Browser API)
|
||
|
||
// 执行技能脚本
|
||
context.eval(script)?;
|
||
|
||
// 调用 execute 函数
|
||
let result = context.call("execute", &[params, browser_action_ref])?;
|
||
|
||
Ok(result)
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 感知层数据格式
|
||
|
||
### 4.1 AOM（Accessibility Object Model）快照
|
||
|
||
AOM 快照是 Agent 理解页面状态的核心数据源。每次浏览器操作后，响应中附带当前页面的
|
||
AOM 快照，供 Agent 的 OBSERVE 阶段使用。
|
||
|
||
**AOM 快照格式**：
|
||
|
||
```json
|
||
{
|
||
"aom_snapshot": [
|
||
{
|
||
"role": "navigation",
|
||
"name": "主导航栏",
|
||
"bounds": [0, 0, 1920, 60],
|
||
"children": [
|
||
{ "role": "link", "name": "首页", "bounds": [20, 10, 60, 40] },
|
||
{ "role": "link", "name": "财务报表", "bounds": [100, 10, 80, 40], "focused": true },
|
||
{ "role": "link", "name": "系统设置", "bounds": [200, 10, 80, 40] }
|
||
]
|
||
},
|
||
{
|
||
"role": "main",
|
||
"name": "报表筛选区",
|
||
"bounds": [0, 60, 1920, 200],
|
||
"children": [
|
||
{
|
||
"role": "combobox",
|
||
"name": "月份选择",
|
||
"value": "2026-03",
|
||
"bounds": [20, 80, 200, 40],
|
||
"selector": "#month-picker"
|
||
},
|
||
{
|
||
"role": "combobox",
|
||
"name": "部门筛选",
|
||
"value": "",
|
||
"bounds": [240, 80, 200, 40],
|
||
"selector": "#dept-selector"
|
||
},
|
||
{
|
||
"role": "button",
|
||
"name": "导出报表",
|
||
"bounds": [460, 80, 100, 40],
|
||
"selector": "#export-btn",
|
||
"disabled": false
|
||
}
|
||
]
|
||
},
|
||
{
|
||
"role": "table",
|
||
"name": "报表数据",
|
||
"bounds": [0, 260, 1920, 600],
|
||
"row_count": 25,
|
||
"children": [
|
||
{
|
||
"role": "row",
|
||
"name": "表头",
|
||
"children": [
|
||
{ "role": "columnheader", "name": "科目编号" },
|
||
{ "role": "columnheader", "name": "科目名称" },
|
||
{ "role": "columnheader", "name": "借方金额" },
|
||
{ "role": "columnheader", "name": "贷方金额" }
|
||
]
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**AOM 快照字段说明**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `role` | string | ARIA 角色 (button, link, textbox, table, etc.) |
|
||
| `name` | string | 元素的可访问名称 (label text, aria-label, etc.) |
|
||
| `bounds` | [x, y, w, h] | 元素的视口坐标和尺寸 (px) |
|
||
| `value` | string | 元素当前值 (input, select 等) |
|
||
| `selector` | string | CSS 选择器 (供后续操作使用) |
|
||
| `focused` | boolean | 是否获得焦点 |
|
||
| `disabled` | boolean | 是否禁用 |
|
||
| `checked` | boolean | 是否选中 (checkbox, radio) |
|
||
| `children` | array | 子元素列表 |
|
||
| `row_count` | number | 表格行数 (仅 table 角色) |
|
||
|
||
**AOM 快照与 LLM 的关系**：
|
||
|
||
AOM 快照被格式化为结构化文本后，作为 observation 的一部分发送给 LLM：
|
||
|
||
```
|
||
操作结果: 点击"财务报表"链接成功。
|
||
|
||
当前页面状态:
|
||
- 导航栏: 首页 | [财务报表] (当前) | 系统设置
|
||
- 报表筛选区:
|
||
- 月份选择: 2026-03
|
||
- 部门筛选: (未选择)
|
||
- [导出报表] 按钮 (可用)
|
||
- 报表数据: 25行数据已加载
|
||
- 表头: 科目编号 | 科目名称 | 借方金额 | 贷方金额
|
||
```
|
||
|
||
### 4.2 SoM（Set-of-Mark）标注
|
||
|
||
在需要视觉辅助时，sgClaw 可以请求带 SoM 标注的页面截图。SoM 在页面截图上为每个
|
||
可交互元素叠加数字标签，便于 LLM 通过编号引用元素。
|
||
|
||
**请求方式**：
|
||
|
||
```json
|
||
{
|
||
"seq": 10,
|
||
"type": "command",
|
||
"action": "pageScreenshot",
|
||
"params": {
|
||
"full_page": false,
|
||
"som_overlay": true
|
||
},
|
||
"security": { "expected_domain": "erp.example.com", "hmac": "..." }
|
||
}
|
||
```
|
||
|
||
**响应**：
|
||
|
||
```json
|
||
{
|
||
"seq": 10,
|
||
"type": "response",
|
||
"success": true,
|
||
"data": {
|
||
"image_base64": "/9j/4AAQSkZJRg...",
|
||
"som_labels": [
|
||
{ "id": 1, "selector": "#month-picker", "name": "月份选择", "bounds": [20, 80, 200, 40] },
|
||
{ "id": 2, "selector": "#dept-selector", "name": "部门筛选", "bounds": [240, 80, 200, 40] },
|
||
{ "id": 3, "selector": "#export-btn", "name": "导出报表", "bounds": [460, 80, 100, 40] }
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
**LLM 使用 SoM 的方式**：
|
||
|
||
LLM 看到截图后可以引用标签编号：
|
||
|
||
```
|
||
我看到页面上有以下可交互元素:
|
||
[1] 月份选择 - 当前值 2026-03
|
||
[2] 部门筛选 - 未选择
|
||
[3] 导出报表按钮
|
||
|
||
我需要点击 [3] 导出报表按钮来导出数据。
|
||
```
|
||
|
||
**SoM 使用策略**：
|
||
|
||
| 场景 | 使用方式 | 优先级 |
|
||
|------|---------|--------|
|
||
| 正常操作 | AOM 快照（文本） | 默认，token 开销低 |
|
||
| AOM 不可用或不完整 | SoM 截图 | 兜底方案 |
|
||
| 复杂视觉布局 | AOM + SoM 结合 | 特殊场景 |
|
||
| 表格/图表分析 | SoM 截图 | 视觉信息丰富时 |
|
||
|
||
### 4.3 感知数据选择策略
|
||
|
||
Agent 在 OBSERVE 阶段根据当前状态自动选择感知方式：
|
||
|
||
```
|
||
OBSERVE(pipe_response):
|
||
│
|
||
├── 1. 解析 pipe_response.aom_snapshot
|
||
│ │
|
||
│ ├── AOM 不为空且完整度 > 80%?
|
||
│ │ → 使用 AOM 文本格式作为 observation
|
||
│ │
|
||
│ └── AOM 为空或不完整?
|
||
│ → 请求 SoM 截图作为 observation
|
||
│
|
||
├── 2. AOM 完整度判断
|
||
│ ├── 页面有可交互元素但 AOM 未列出 → 不完整
|
||
│ ├── AOM 元素数为 0 但页面非空白 → 不完整
|
||
│ └── 其他情况 → 完整
|
||
│
|
||
└── 3. 格式化 observation
|
||
├── AOM: 结构化文本描述
|
||
└── SoM: 截图 (base64) + 标签列表
|
||
```
|
||
|
||
---
|
||
|
||
## 5. LLM 集成
|
||
|
||
### 5.1 Provider 适配层
|
||
|
||
sgClaw 通过 ZeroClaw 的 Provider trait 抽象对接不同的 LLM 服务。
|
||
每个 Provider 实现 HTTP 调用、streaming 解析、错误重试等逻辑。
|
||
|
||
**Provider 统一行为要求**：
|
||
|
||
| 行为 | 要求 | 说明 |
|
||
|------|------|------|
|
||
| 超时 | 连接 10s，首 token 30s，总体 120s | 防止挂起 |
|
||
| 重试 | 最多 3 次，指数退避 (1s, 2s, 4s) | 仅重试 5xx 和网络错误 |
|
||
| Streaming | 必须支持 | 用于实时日志显示 |
|
||
| Tool-use | 必须支持 | Agent ReAct 的核心能力 |
|
||
| Token 计量 | 每次调用后上报 usage | 审计和成本控制 |
|
||
| 错误分类 | 区分可重试/不可重试错误 | 401/403 不重试 |
|
||
|
||
### 5.2 Claude Provider 实现要点
|
||
|
||
```rust
|
||
pub struct ClaudeProvider {
|
||
client: reqwest::Client,
|
||
api_key: String,
|
||
model: String,
|
||
base_url: String,
|
||
}
|
||
|
||
impl ClaudeProvider {
|
||
const DEFAULT_BASE_URL: &'static str = "https://api.anthropic.com";
|
||
const API_VERSION: &'static str = "2023-06-01";
|
||
|
||
/// 将 sgClaw 的 Message 格式转换为 Claude API 格式
|
||
fn convert_messages(messages: &[Message]) -> Vec<ClaudeMessage> {
|
||
// Message::User → { role: "user", content: [...] }
|
||
// Message::Assistant → { role: "assistant", content: [...] }
|
||
// Message::Tool → { role: "user", content: [{ type: "tool_result", ... }] }
|
||
}
|
||
|
||
/// 将 sgClaw 的 ToolDefinition 转换为 Claude tool 格式
|
||
fn convert_tools(tools: &[ToolDefinition]) -> Vec<ClaudeTool> {
|
||
// ToolDefinition → { name, description, input_schema }
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5.3 输出约束
|
||
|
||
LLM 的输出必须遵循以下约束：
|
||
|
||
**Tool-use 输出格式** (Claude API):
|
||
|
||
```json
|
||
{
|
||
"role": "assistant",
|
||
"content": [
|
||
{
|
||
"type": "thinking",
|
||
"thinking": "用户要导出本月合规报表。我需要先导航到 ERP 系统的报表模块..."
|
||
},
|
||
{
|
||
"type": "tool_use",
|
||
"id": "toolu_01xyz",
|
||
"name": "browser_action",
|
||
"input": {
|
||
"action": "navigate",
|
||
"params": {
|
||
"url": "https://erp.example.com/report/compliance"
|
||
},
|
||
"expected_domain": "erp.example.com"
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**输出校验规则**：
|
||
|
||
```
|
||
LLM 输出校验:
|
||
│
|
||
├── 1. 是否为合法 JSON?
|
||
│ → 否: 请求 LLM 重新生成 (最多 2 次)
|
||
│
|
||
├── 2. tool_call 格式是否正确?
|
||
│ ├── name 必须是 "browser_action" 或已注册的 MCP 工具
|
||
│ ├── input 必须包含 action 字段
|
||
│ └── action 必须在 Action 枚举中
|
||
│
|
||
├── 3. 参数是否通过 JSON Schema 校验?
|
||
│ → 否: 将校验错误信息反馈给 LLM，请求修正
|
||
│
|
||
├── 4. 是否包含 expected_domain?
|
||
│ → 否: 自动从上下文推断 (当前页面域名)
|
||
│
|
||
└── 5. 通过所有校验
|
||
→ 交给 BrowserPipeTool 执行
|
||
```
|
||
|
||
### 5.4 System Prompt 中的工具描述
|
||
|
||
提供给 LLM 的工具描述需要精确、简洁，帮助 LLM 正确选择操作：
|
||
|
||
```json
|
||
{
|
||
"name": "browser_action",
|
||
"description": "在浏览器中执行操作。可以点击元素、输入文本、导航页面、获取页面内容等。每次调用需要指定 action 类型和对应参数。",
|
||
"input_schema": {
|
||
"type": "object",
|
||
"required": ["action", "expected_domain"],
|
||
"properties": {
|
||
"action": {
|
||
"type": "string",
|
||
"enum": ["click", "type", "navigate", "getText", "getHtml", "waitForSelector", "pageScreenshot", "select", "scrollTo", "getAomSnapshot", "storageSet", "storageGet", "zombieSpawn", "zombieKill"],
|
||
"description": "要执行的操作类型"
|
||
},
|
||
"params": {
|
||
"type": "object",
|
||
"description": "操作参数，根据 action 类型不同而不同"
|
||
},
|
||
"expected_domain": {
|
||
"type": "string",
|
||
"description": "操作目标页面的域名（安全校验用）"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 记忆与自进化
|
||
|
||
### 6.1 记忆分层架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 记忆系统架构 │
|
||
│ │
|
||
│ ┌─ L0: 即时记忆 ─────────────────────────────────────────┐ │
|
||
│ │ LLM 上下文窗口内的消息历史 │ │
|
||
│ │ 生命周期: 单次 LLM 调用 │ │
|
||
│ │ 容量: max_tokens (如 4096) │ │
|
||
│ │ 用途: 当前步骤的推理依据 │ │
|
||
│ └────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌─ L1: 短期记忆 (Ring Buffer) ────────────────────────────┐ │
|
||
│ │ VecDeque<Message> │ │
|
||
│ │ 生命周期: 单次任务 (execute_task 调用) │ │
|
||
│ │ 容量: 50 条消息 / 8000 tokens │ │
|
||
│ │ 用途: 当前任务的完整对话历史 │ │
|
||
│ │ 淘汰策略: FIFO，超限时压缩最早的消息为摘要 │ │
|
||
│ └────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌─ L2: 长期记忆 (SQLite) ─────────────────────────────────┐ │
|
||
│ │ 持久化存储 │ │
|
||
│ │ 生命周期: 跨任务、跨会话 │ │
|
||
│ │ 容量: 磁盘空间限制 (建议 < 100MB) │ │
|
||
│ │ 用途: 任务经验、用户偏好、技能执行记录 │ │
|
||
│ │ 检索: 语义相似度 (向量) + 关键词匹配 │ │
|
||
│ └────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 6.2 记忆读写流程
|
||
|
||
**写入流程**（任务执行过程中）：
|
||
|
||
```
|
||
Agent 每步操作后:
|
||
│
|
||
├── 1. 写入短期记忆 (L1)
|
||
│ ├── 追加 thinking 消息
|
||
│ ├── 追加 action 消息
|
||
│ └── 追加 observation 消息
|
||
│
|
||
├── 2. 检查短期记忆容量
|
||
│ ├── 消息数 > 50? → 压缩最早 10 条为摘要
|
||
│ └── token 数 > 8000? → 压缩直至 < 8000
|
||
│
|
||
└── 3. (任务结束时) 写入长期记忆 (L2)
|
||
├── 保存任务摘要 (type: TaskResult)
|
||
├── 保存成功步骤序列 (type: SkillExperience)
|
||
└── 更新技能执行统计 (skill_executions 表)
|
||
```
|
||
|
||
**读取流程**（新任务开始时）：
|
||
|
||
```
|
||
execute_task(instruction):
|
||
│
|
||
├── 1. 清空短期记忆 (新任务)
|
||
│
|
||
├── 2. 从长期记忆检索相关经验
|
||
│ ├── 语义搜索: embedding(instruction) vs memory_entries
|
||
│ ├── 取 top-3 相关条目
|
||
│ └── 格式化为 "历史经验" 上下文
|
||
│
|
||
├── 3. 检查是否有精确匹配的 Skill 经验
|
||
│ ├── 查询 skill_executions 表
|
||
│ ├── 找到成功执行记录?
|
||
│ │ → 作为推荐步骤加入 system_prompt
|
||
│ └── 未找到?
|
||
│ → 不影响执行
|
||
│
|
||
└── 4. 组装初始上下文
|
||
├── system_prompt + 长期记忆检索结果
|
||
├── 用户指令
|
||
└── 开始 ReAct 循环
|
||
```
|
||
|
||
### 6.3 自进化学习机制
|
||
|
||
sgClaw 的自进化核心思想：每次成功执行的任务都是一个学习样本。
|
||
通过记录和检索这些样本，Agent 在后续遇到相似任务时可以更快、更准确地完成。
|
||
|
||
**自进化循环**：
|
||
|
||
```
|
||
┌─────────────────────────────┐
|
||
│ 首次执行新任务 │
|
||
│ │
|
||
│ LLM 从零推理 │
|
||
│ 多步试探 │
|
||
│ 可能遇到错误和回退 │
|
||
│ 平均 8-15 步完成 │
|
||
└──────────┬──────────────────┘
|
||
│ 成功完成
|
||
│
|
||
▼
|
||
┌─────────────────────────────┐
|
||
│ 经验沉淀 │
|
||
│ │
|
||
│ 记录成功步骤序列 │
|
||
│ 记录关键决策点 │
|
||
│ 计算向量嵌入 │
|
||
│ 存入长期记忆 (L2) │
|
||
└──────────┬──────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────┐
|
||
│ 再次执行相似任务 │
|
||
│ │
|
||
│ 检索到历史经验 │
|
||
│ LLM 参考已有路径 │
|
||
│ 跳过试探阶段 │
|
||
│ 平均 4-6 步完成 │
|
||
└──────────┬──────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────┐
|
||
│ 技能提炼 (可选) │
|
||
│ │
|
||
│ 高频任务 (>5 次相似执行) │
|
||
│ 提取为正式 Skill 脚本 │
|
||
│ 后续直接调用，1-2 步完成 │
|
||
└─────────────────────────────┘
|
||
```
|
||
|
||
**经验记录格式**：
|
||
|
||
```json
|
||
{
|
||
"id": "exp-2026-03-03-001",
|
||
"type": "task_result",
|
||
"content": "任务: 导出本月ERP合规报表\n\n执行路径:\n1. navigate → erp.example.com/report\n2. click → #month-picker → 设置为2026-03\n3. click → #compliance-tab\n4. click → #export-btn\n5. waitForSelector → .export-success\n\n结果: 成功导出，文件名 compliance-2026-03.xlsx",
|
||
"metadata": {
|
||
"task_instruction": "导出本月合规报表",
|
||
"steps": 5,
|
||
"duration_ms": 12500,
|
||
"domains_visited": ["erp.example.com"],
|
||
"skills_used": [],
|
||
"success": true
|
||
},
|
||
"embedding": [0.12, -0.34, 0.56, ...],
|
||
"created_at": "2026-03-03T10:30:00Z",
|
||
"session_id": "trace-abc123"
|
||
}
|
||
```
|
||
|
||
### 6.4 向量检索实现
|
||
|
||
长期记忆的语义检索使用简单的余弦相似度计算。在数据量较小时（< 10000 条），
|
||
线性扫描足够快（< 10ms）。
|
||
|
||
**嵌入向量生成**：
|
||
|
||
```
|
||
文本 → 嵌入方式:
|
||
│
|
||
├── 在线模型可用时:
|
||
│ └── 调用 LLM Provider 的 embedding API
|
||
│ ├── Claude: 不提供独立 embedding API，使用 summarize + hash
|
||
│ ├── OpenAI: text-embedding-3-small (1536 维)
|
||
│ └── Ollama: nomic-embed-text (384 维)
|
||
│
|
||
└── 离线/无 embedding API 时:
|
||
└── 简单 TF-IDF 向量 + 关键词匹配
|
||
├── 中文分词 (jieba-rs)
|
||
├── 计算词频向量
|
||
└── 余弦相似度排序
|
||
```
|
||
|
||
**检索优化策略**：
|
||
|
||
| 策略 | 说明 | 适用场景 |
|
||
|------|------|---------|
|
||
| 类型过滤 | 先按 entry_type 过滤，减少扫描量 | 总是使用 |
|
||
| 时间窗口 | 优先检索最近 30 天的记忆 | 默认策略 |
|
||
| 域名过滤 | 按当前任务涉及的域名过滤 | 域名已知时 |
|
||
| 混合排序 | 0.7 * 向量相似度 + 0.3 * 时间衰减 | 综合排序 |
|
||
|
||
---
|
||
|
||
## 7. 审计与追溯
|
||
|
||
### 7.1 Trace ID 体系
|
||
|
||
每次 Agent 会话分配唯一的 `trace_id`，贯穿所有模块和组件，用于事后审计追溯。
|
||
|
||
**trace_id 格式**：
|
||
|
||
```
|
||
sgclaw-{date}-{random}
|
||
示例: sgclaw-20260303-a1b2c3d4
|
||
```
|
||
|
||
**trace_id 传播路径**：
|
||
|
||
```
|
||
SgClawProcessHost::Start()
|
||
│ 生成 trace_id
|
||
│
|
||
├─→ init message: { trace_id: "sgclaw-20260303-a1b2c3d4" }
|
||
│
|
||
├─→ sgClaw Runtime: 所有日志附带 trace_id
|
||
│ ├─→ LLM 调用记录
|
||
│ ├─→ Pipe 命令记录
|
||
│ └─→ Memory 条目关联
|
||
│
|
||
├─→ PipeListener: 所有 pipe 消息日志附带 trace_id
|
||
│
|
||
└─→ CommandRouter: 操作审计日志附带 trace_id
|
||
```
|
||
|
||
### 7.2 审计日志格式
|
||
|
||
**sgClaw 端日志** (输出到 stderr，结构化 JSON)：
|
||
|
||
```json
|
||
{
|
||
"timestamp": "2026-03-03T10:23:05.123Z",
|
||
"level": "INFO",
|
||
"trace_id": "sgclaw-20260303-a1b2c3d4",
|
||
"module": "agent::runtime",
|
||
"event": "step_completed",
|
||
"data": {
|
||
"step": 3,
|
||
"action": "click",
|
||
"selector": "#export-btn",
|
||
"domain": "erp.example.com",
|
||
"success": true,
|
||
"duration_ms": 245
|
||
}
|
||
}
|
||
```
|
||
|
||
**Browser 端日志** (SuperRPA 已有日志系统)：
|
||
|
||
```
|
||
[2026-03-03 10:23:05.123] [sgclaw] [trace:sgclaw-20260303-a1b2c3d4]
|
||
PIPE_CMD seq=3 action=click selector=#export-btn domain=erp.example.com
|
||
MAC_CHECK: ALLOW
|
||
CMD_EXEC: OK (245ms)
|
||
```
|
||
|
||
### 7.3 日志采集与存储
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ 日志采集架构 │
|
||
│ │
|
||
│ sgClaw (Rust) Browser (C++) │
|
||
│ ┌───────────┐ ┌───────────┐ │
|
||
│ │ tracing │ │ LOG() │ │
|
||
│ │ → stderr │ │ → file │ │
|
||
│ └─────┬─────┘ └─────┬─────┘ │
|
||
│ │ │ │
|
||
│ ▼ ▼ │
|
||
│ sgclaw.log chrome_debug.log │
|
||
│ (JSON Lines) (SuperRPA 格式) │
|
||
│ │ │ │
|
||
│ └───────────┬───────────────────┘ │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ 审计查询接口 │
|
||
│ (按 trace_id 关联检索) │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
**日志保留策略**：
|
||
|
||
| 日志类型 | 保留时长 | 存储位置 |
|
||
|---------|---------|---------|
|
||
| sgClaw 操作日志 | 90 天 | 本地文件 + 可选远程上传 |
|
||
| Pipe 通信记录 | 30 天 | 本地文件 |
|
||
| LLM 调用记录 | 90 天 | 本地文件 (含 token 用量) |
|
||
| 长期记忆 (SQLite) | 永久 | 本地数据库 |
|
||
| 浏览器审计日志 | 按已有策略 | SuperRPA 日志系统 |
|
||
|
||
---
|
||
|
||
*文档结束。本文档为 sgClaw L3 层数据流与 Skill 体系参考。Skill 开发者应重点关注
|
||
第 3 节（Skill 体系）和第 4 节（感知层数据格式），高级开发者应关注第 2 节（Agent 循环）
|
||
和第 6 节（记忆与自进化）。*
|