542 lines
14 KiB
Markdown
542 lines
14 KiB
Markdown
# Qiming Harness 业务场景方案
|
|
|
|
> 基于 harness-monorepo + qimingclaw 沙箱 + Anthropic/OpenAI 最佳实践
|
|
> **版本**: 3.0.0
|
|
> **更新**: 2026-03-23
|
|
|
|
---
|
|
|
|
## 1. 业务场景概述
|
|
|
|
### 1.1 核心场景
|
|
|
|
| 场景 | 说明 | 优先级 |
|
|
|------|------|--------|
|
|
| **沙箱创建** | 用户发起任务 → 创建隔离沙箱 | P0 |
|
|
| **任务执行** | Agent 在沙箱内执行代码任务 | P0 |
|
|
| **权限审批** | 危险操作需用户确认 | P0 |
|
|
| **任务追踪** | CP 工作流 + Checkpoint | P0 |
|
|
| **错误恢复** | 失败后自动/手动恢复 | P1 |
|
|
| **会话管理** | 多任务并行 / 会话持久化 | P1 |
|
|
| **审计日志** | 完整操作记录 | P1 |
|
|
|
|
### 1.2 典型业务流程
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ 用户发起任务 │
|
|
│ "帮我实现用户登录功能" │
|
|
└─────────────────────────┬───────────────────────────────────┘
|
|
↓
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ CP0: 任务确认 │
|
|
│ - 解析任务意图 │
|
|
│ - 检查权限 │
|
|
│ - 分配 sandbox │
|
|
└─────────────────────────┬───────────────────────────────────┘
|
|
↓
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ CP1: 任务规划 │
|
|
│ - 分解子任务 │
|
|
│ - 风险评估 │
|
|
│ - 资源预估 │
|
|
└─────────────────────────┬───────────────────────────────────┘
|
|
↓
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ CP2: 沙箱执行 │
|
|
│ - 创建沙箱 │
|
|
│ - 执行代码 │
|
|
│ - 权限检查 │
|
|
└─────────────────────────┬───────────────────────────────────┘
|
|
↓
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ CP3: 质量验证 │
|
|
│ - lint / typecheck │
|
|
│ - 测试验证 │
|
|
│ - 构建验证 │
|
|
└─────────────────────────┬───────────────────────────────────┘
|
|
↓
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ CP4: 完成交付 │
|
|
│ - 代码合并 │
|
|
│ - 状态更新 │
|
|
│ - 通知用户 │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 2. 场景一：沙箱创建
|
|
|
|
### 2.1 用户流程
|
|
|
|
```
|
|
用户: "开始一个新任务"
|
|
↓
|
|
系统: 创建沙箱 + 分配 workspace
|
|
↓
|
|
Agent: 进入沙箱，开始工作
|
|
```
|
|
|
|
### 2.2 状态定义
|
|
|
|
```json
|
|
{
|
|
"session": {
|
|
"id": "sess_xxx",
|
|
"userId": "user_xxx",
|
|
"status": "creating",
|
|
"sandbox": {
|
|
"id": "sand_xxx",
|
|
"type": "docker",
|
|
"workspace": "/tmp/qimingclaw/sess_xxx",
|
|
"createdAt": "2026-03-23T00:00:00Z"
|
|
},
|
|
"agent": {
|
|
"mode": "autonomous",
|
|
"model": "claude-3-5"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### 2.3 Checkpoint 记录
|
|
|
|
```json
|
|
{
|
|
"checkpoint": {
|
|
"CP0_INIT": {
|
|
"status": "completed",
|
|
"timestamp": "2026-03-23T00:00:00Z",
|
|
"duration": 1500,
|
|
"sandboxId": "sand_xxx"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 3. 场景二：任务执行
|
|
|
|
### 3.1 用户流程
|
|
|
|
```
|
|
用户: "帮我写一个登录页面"
|
|
↓
|
|
Agent: 规划 → 写代码 → 验证
|
|
↓
|
|
系统: 更新 checkpoint + 状态
|
|
↓
|
|
用户: 收到完成通知
|
|
```
|
|
|
|
### 3.2 任务结构
|
|
|
|
```json
|
|
{
|
|
"task": {
|
|
"id": "task_xxx",
|
|
"sessionId": "sess_xxx",
|
|
"description": "实现用户登录功能",
|
|
"status": "in_progress",
|
|
"currentStep": 2,
|
|
"totalSteps": 5,
|
|
|
|
"steps": [
|
|
{ "id": 1, "description": "创建登录组件", "status": "completed" },
|
|
{ "id": 2, "description": "实现 API 调用", "status": "in_progress" },
|
|
{ "id": 3, "description": "添加验证逻辑", "status": "pending" },
|
|
{ "id": 4, "description": "编写测试", "status": "pending" },
|
|
{ "id": 5, "description": "构建验证", "status": "pending" }
|
|
],
|
|
|
|
"artifacts": [
|
|
{ "path": "src/login/index.tsx", "action": "created" },
|
|
{ "path": "src/api/auth.ts", "action": "modified" }
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
### 3.3 执行日志
|
|
|
|
```json
|
|
{
|
|
"execution": {
|
|
"taskId": "task_xxx",
|
|
"command": "pnpm install && pnpm run build",
|
|
"cwd": "/tmp/qimingclaw/sess_xxx/projects/login",
|
|
"startedAt": "2026-03-23T00:01:00Z",
|
|
"duration": 45000,
|
|
"exitCode": 0,
|
|
"stdout": "...",
|
|
"stderr": ""
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 4. 场景三：权限审批
|
|
|
|
### 4.1 触发条件
|
|
|
|
| 操作类型 | 触发条件 | 审批级别 |
|
|
|---------|-----------|---------|
|
|
| `file:delete` | 删除超过 5 个文件 | 高 |
|
|
| `command:execute` | `npm install` | 中 |
|
|
| `command:execute` | `git push` | 高 |
|
|
| `network:download` | 下载外部资源 | 中 |
|
|
| `package:install` | 安装包 | 低 |
|
|
|
|
### 4.2 审批请求
|
|
|
|
```json
|
|
{
|
|
"approval": {
|
|
"id": "apr_xxx",
|
|
"taskId": "task_xxx",
|
|
"type": "command:execute",
|
|
"priority": "medium",
|
|
|
|
"title": "执行 npm install",
|
|
"description": "需要在项目中安装 lodash 依赖",
|
|
|
|
"context": {
|
|
"command": "npm install lodash",
|
|
"cwd": "/tmp/qimingclaw/sess_xxx/project",
|
|
"package": "lodash@4.17.21",
|
|
"riskLevel": "low"
|
|
},
|
|
|
|
"options": [
|
|
{ "label": "批准", "action": "approve" },
|
|
{ "label": "拒绝", "action": "deny" },
|
|
{ "label": "修改命令", "action": "modify", "prompt": "建议使用 pnpm" }
|
|
],
|
|
|
|
"timeout": 60,
|
|
"status": "pending",
|
|
"createdAt": "2026-03-23T00:02:00Z"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 4.3 ACP 消息格式
|
|
|
|
```typescript
|
|
// 请求
|
|
interface ACPApprovalRequest {
|
|
type: "approval_request";
|
|
channel: "discord" | "telegram" | "app";
|
|
approval: ApprovalRequest;
|
|
}
|
|
|
|
// 响应
|
|
interface ACPApprovalResponse {
|
|
type: "approval_response";
|
|
approvalId: string;
|
|
decision: "approve" | "deny" | "modify";
|
|
modifiedCommand?: string;
|
|
reason?: string;
|
|
respondedAt: string;
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 5. 场景四：任务追踪
|
|
|
|
### 5.1 状态机
|
|
|
|
```
|
|
pending → in_progress → completed
|
|
↓ ↓
|
|
failed ←── ←──
|
|
↓
|
|
recovering → in_progress (retry)
|
|
↓
|
|
abandoned
|
|
```
|
|
|
|
### 5.2 状态持久化
|
|
|
|
```json
|
|
{
|
|
"taskState": {
|
|
"id": "task_xxx",
|
|
"checkpoint": "CP2_EXEC",
|
|
"checkpointStatus": "in_progress",
|
|
|
|
"progress": {
|
|
"currentStep": 2,
|
|
"totalSteps": 5,
|
|
"percentComplete": 40
|
|
},
|
|
|
|
"lastCheckpoint": {
|
|
"type": "CP1_PLAN",
|
|
"completedAt": "2026-03-23T00:01:00Z",
|
|
"result": "Task breakdown completed"
|
|
},
|
|
|
|
"nextCheckpoint": {
|
|
"type": "CP2_EXEC",
|
|
"plannedAt": "2026-03-23T00:01:30Z",
|
|
"estimatedDuration": 120000
|
|
},
|
|
|
|
"canResume": true,
|
|
"resumeFrom": "CP1_PLAN"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 5.3 进度通知
|
|
|
|
```typescript
|
|
// ACP 消息
|
|
interface ACPProgressUpdate {
|
|
type: "progress_update";
|
|
taskId: string;
|
|
checkpoint: string;
|
|
percentComplete: number;
|
|
message: string; // "正在执行第 2/5 步..."
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 6. 场景五：错误恢复
|
|
|
|
### 6.1 错误分类
|
|
|
|
| 错误类型 | 例子 | 恢复策略 |
|
|
|---------|------|---------|
|
|
| **瞬时错误** | 网络超时、API 限流 | 自动重试 |
|
|
| **验证错误** | TypeScript 编译失败 | 暂停 + 通知 |
|
|
| **权限错误** | 权限被拒绝 | 人工审批 |
|
|
| **资源错误** | 内存不足、磁盘满 | 清理 + 重试 |
|
|
| **安全错误** | 路径遍历攻击 | 终止 + 审计 |
|
|
|
|
### 6.2 恢复流程
|
|
|
|
```
|
|
错误发生
|
|
↓
|
|
错误分类
|
|
↓
|
|
┌─────────────────────────────────────────┐
|
|
│ 瞬时错误 │
|
|
│ → 等待 → 重试 (最多3次) │
|
|
│ → 成功 → 继续 │
|
|
│ → 失败 → 升级 │
|
|
└─────────────────────────────────────────┘
|
|
↓
|
|
┌─────────────────────────────────────────┐
|
|
│ 验证错误 │
|
|
│ → 暂停任务 │
|
|
│ → 通知用户 │
|
|
│ → 等待修复 │
|
|
└─────────────────────────────────────────┘
|
|
↓
|
|
┌─────────────────────────────────────────┐
|
|
│ 安全错误 │
|
|
│ → 终止任务 │
|
|
│ → 审计日志 │
|
|
│ → 通知安全团队 │
|
|
└─────────────────────────────────────────┘
|
|
```
|
|
|
|
### 6.3 恢复状态
|
|
|
|
```json
|
|
{
|
|
"recovery": {
|
|
"enabled": true,
|
|
"attempt": 2,
|
|
"maxAttempts": 3,
|
|
|
|
"lastError": {
|
|
"type": "transient",
|
|
"code": "RATE_LIMIT",
|
|
"message": "API rate limit exceeded",
|
|
"occurredAt": "2026-03-23T00:03:00Z"
|
|
},
|
|
|
|
"nextRetry": {
|
|
"scheduledAt": "2026-03-23T00:03:30Z",
|
|
"countdown": 30
|
|
},
|
|
|
|
"history": [
|
|
{ "attempt": 1, "error": "timeout", "recovered": false },
|
|
{ "attempt": 2, "error": "rate_limit", "recovered": true }
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 7. 场景六：会话管理
|
|
|
|
### 7.1 多任务并行
|
|
|
|
```json
|
|
{
|
|
"session": {
|
|
"id": "sess_xxx",
|
|
"userId": "user_xxx",
|
|
|
|
"tasks": {
|
|
"active": ["task_1", "task_2"],
|
|
"completed": ["task_0"],
|
|
"failed": []
|
|
},
|
|
|
|
"limits": {
|
|
"maxConcurrentTasks": 3,
|
|
"maxTotalDuration": 3600000,
|
|
"maxCost": 10.00
|
|
},
|
|
|
|
"usage": {
|
|
"currentTasks": 2,
|
|
"totalDuration": 1200000,
|
|
"totalCost": 3.50
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### 7.2 会话持久化
|
|
|
|
```json
|
|
{
|
|
"sessionSnapshot": {
|
|
"id": "sess_xxx",
|
|
"createdAt": "2026-03-23T00:00:00Z",
|
|
"lastActiveAt": "2026-03-23T00:05:00Z",
|
|
|
|
"state": {
|
|
"tasks": [...],
|
|
"sandboxes": [...],
|
|
"artifacts": [...],
|
|
"checkpoints": [...]
|
|
},
|
|
|
|
"canResume": true,
|
|
"expiresAt": "2026-03-24T00:00:00Z"
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 8. 场景七：审计日志
|
|
|
|
### 8.1 日志结构
|
|
|
|
```json
|
|
{
|
|
"auditLog": {
|
|
"id": "audit_xxx",
|
|
"timestamp": "2026-03-23T00:05:00Z",
|
|
|
|
"event": {
|
|
"type": "task.completed",
|
|
"taskId": "task_xxx",
|
|
"sessionId": "sess_xxx"
|
|
},
|
|
|
|
"actor": {
|
|
"type": "agent",
|
|
"id": "agent_xxx",
|
|
"model": "claude-3-5"
|
|
},
|
|
|
|
"resource": {
|
|
"type": "file",
|
|
"path": "src/login/index.tsx",
|
|
"action": "created"
|
|
},
|
|
|
|
"context": {
|
|
"checkpoint": "CP4_COMPLETE",
|
|
"duration": 300000,
|
|
"cost": 0.50
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### 8.2 安全事件
|
|
|
|
```json
|
|
{
|
|
"securityEvent": {
|
|
"id": "sec_xxx",
|
|
"timestamp": "2026-03-23T00:05:00Z",
|
|
|
|
"type": "command_blocked",
|
|
"severity": "high",
|
|
|
|
"description": "危险命令被拦截",
|
|
|
|
"details": {
|
|
"command": "rm -rf /",
|
|
"reason": "Path traversal attempt",
|
|
"sandboxId": "sand_xxx",
|
|
"blocked": true
|
|
},
|
|
|
|
"action": {
|
|
"taken": "blocked",
|
|
"notified": ["user", "security_team"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 9. 实现优先级
|
|
|
|
### Phase 1: 核心沙箱 (本周)
|
|
- [ ] 沙箱创建/销毁
|
|
- [ ] 基本任务执行
|
|
- [ ] CP 工作流
|
|
|
|
### Phase 2: 权限审批 (下周)
|
|
- [ ] 权限触发机制
|
|
- [ ] ACP 审批消息
|
|
- [ ] 用户确认 UI
|
|
|
|
### Phase 3: 状态管理 (第3周)
|
|
- [ ] 任务状态持久化
|
|
- [ ] Checkpoint 记录
|
|
- [ ] 进度追踪
|
|
|
|
### Phase 4: 错误恢复 (第4周)
|
|
- [ ] 错误分类
|
|
- [ ] 自动恢复
|
|
- [ ] 人工介入
|
|
|
|
---
|
|
|
|
## 10. 参考
|
|
|
|
- [harness-monorepo](https://github.com/dongdada29/harness-monorepo)
|
|
- [Anthropic: Effective Harnesses](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
|
|
- [qimingclaw sandbox](./sandbox/)
|
|
|
|
---
|
|
|
|
## 11. 变更记录
|
|
|
|
| 日期 | 版本 | 变更 |
|
|
|------|------|------|
|
|
| 2026-03-23 | 3.0.0 | 初始版本，基于业务场景 |
|