@bolloon/bolloon-agent 0.1.0 → 0.1.2

package/docs/plans/2026-05-15-document-agent-design.md

@@ -1,479 +0,0 @@
-# AI智能体自主文档处理系统 - 设计文档
-
-## 1. 概述
-
-设计一个基于 OpenClaw 双层架构的 AI 智能体系统，实现文档自主阅读、总结、改进和 P2P 发送。系统通过 **约束层（Prompt Guardrails）** + **执行层（Code-Driven Workflow）** 实现安全可控的完全自主运行。
-
-### 1.1 OpenCLI 集成
-
-系统集成 OpenCLI 实现**零 Token 消耗的浏览器自动化**和数据获取能力：
-
-| 能力 | 命令示例 | Token 消耗 |
-|------|----------|------------|
-| 社交媒体搜索 | `opencli zhihu search "AI Agent"` | 0 |
-| 视频/图文下载 | `opencli bilibili download <url>` | 0 |
-| 私域聊天记录 | `opencli wx search <keyword>` | 0 |
-| 办公套件 | `opencli lark search <keyword>` | 0 |
-| 浏览器 CDP 控制 | `opencli cdp screenshot` | 0 |
-
-**核心优势**：CLI 命令在本地浏览器直接执行，不经过 LLM 推理，实现零 Token 消耗的确定性操作。
-
-## 2. 架构设计
-
-### 2.1 双层架构
-
-```
-┌─────────────────────────────────────────────────────────┐
-│                    Human Interaction                     │
-└─────────────────────────────────────────────────────────┘
-                             │
-                             ▼
-┌─────────────────────────────────────────────────────────┐
-│  Constraint Layer (Prompt Guardrails)                    │
-│  - System Prompt: Agent 边界、规则、禁忌                 │
-│  - Task Prompt: 当前任务的具体约束                     │
-│  - Privacy Guardrail: 私域数据访问拦截                  │
-└─────────────────────────────────────────────────────────┘
-                             │
-                             ▼
-┌─────────────────────────────────────────────────────────┐
-│  Execution Layer (Code-Driven Workflow)                 │
-│  - WorkflowEngine: 工作流执行引擎                       │
-│  - Step 执行 + 重试机制 + Guardrail 检查                │
-│  - OpenCLI Adapter: 零Token浏览器自动化                │
-│  - CDP Controller: Electron应用控制                      │
-└─────────────────────────────────────────────────────────┘
-                             │
-                             ▼
-┌─────────────────────────────────────────────────────────┐
-│  P2P Network (libp2p + DIaoP Identity)                │
-└─────────────────────────────────────────────────────────┘
-```
-
-### 2.2 核心组件
-
-| 组件 | 职责 |
-|------|------|
-| `ConstraintLayer` | Prompt 约束管理、安全拦截、规则执行 |
-| `PrivacyGuardrail` | 私域数据访问权限检查（微信/飞书等） |
-| `WorkflowEngine` | 工作流编排、步骤执行、重试逻辑 |
-| `OpenCLIAdapter` | OpenCLI 命令执行，零 Token 数据获取 |
-| `CDPController` | 浏览器 CDP 协议控制，Electron 应用自动化 |
-| `WorkflowStep` | 单个步骤定义（含 scrape/opencli/chat 等新类型） |
-| `AgentSession` | Agent 会话管理、状态维护 |
-
-## 3. 约束层设计
-
-### 3.1 System Prompt 约束
-
-```typescript
-const SYSTEM_PROMPT = `
-你是一个文档处理Agent，在以下规则下运行：
-
-【边界规则】
-1. 只处理：txt, md, pdf, docx 格式文档
-2. 不修改原始文件，只输出改进版本
-3. 发送前必须记录操作日志
-
-【自主权限】
-- ✅ 自主决定：摘要详细程度、chunk分块策略
-- ✅ 自主决定：重试次数（最多3次）
-- ✅ 自主决定：是否需要补充信息
-- ❌ 必须确认：首次向新对等节点发送文档
-- ❌ 必须确认：删除操作
-
-【敏感操作拦截】
-if (操作 === '发送文档' && 对等节点不在已知列表) {
-  拦截 → 记录 → 等待确认
-}
-`;
-```
-
-### 3.2 约束执行流程
-
-```
-任务输入 → 约束检查 → 放行/拦截/确认
-                │
-                ▼
-        ┌───────────────┐
-        │ 新节点发送?    │──Yes──→ 拦截 + 记录 + 等待确认
-        └───────────────┘
-                │No
-                ▼
-        ┌───────────────┐
-        │ 在规则内?      │──No──→ 拦截 + 返回错误
-        └───────────────┘
-                │Yes
-                ▼
-            放行执行
-```
-
-## 4. 执行层设计
-
-### 4.1 WorkflowStep 接口
-
-```typescript
-type StepType =
-  | 'read' | 'chunk' | 'summarize' | 'improve' | 'review' | 'send' | 'report'
-  | 'scrape'    // 网页数据抓取（opencli）
-  | 'opencli'   // OpenCLI 命令执行
-  | 'chat'      // 私域聊天记录获取（wx/tg/discord）
-  | 'cdp';      // CDP 浏览器控制
-
-interface WorkflowStep {
-  id: string;
-  type: StepType;
-  config?: Record<string, unknown>;
-  retry: {
-    max: number;      // 最大重试次数
-    current: number;  // 当前重试次数
-    backoffMs: number; // 退避时间（毫秒）
-  };
-  onFail: 'skip' | 'abort' | 'retry';
-  guardrail?: (context: WorkflowContext) => Promise<boolean>;
-  guardrailOnRetry?: boolean; // 重试时是否也执行 guardrail
-}
-
-interface WorkflowContext {
-  document?: DocumentContent;
-  summary?: string;
-  improved?: string;
-  qualityScore?: number;
-  scrapedData?: ScrapedData;  // OpenCLI 获取的数据
-  chatHistory?: ChatMessage[]; // 私域聊天记录
-  peers: string[];
-  logs: OperationLog[];
-}
-```
-
-### 4.2 WorkflowEngine 执行逻辑
-
-```typescript
-class WorkflowEngine {
-  async execute(step: WorkflowStep, context: WorkflowContext): Promise<StepResult> {
-    // 1. Guardrail 前置检查
-    if (step.guardrail && !await step.guardrail(context)) {
-      return { status: 'blocked', reason: 'guardrail_failed' };
-    }
-
-    // 2. 执行步骤，带重试
-    for (let attempt = 0; attempt <= step.retry.max; attempt++) {
-      try {
-        const result = await this.runStep(step, context);
-
-        // 3. Guardrail 后置检查（可选）
-        if (step.onRetry !== false && step.guardrail && !await step.guardrail(context)) {
-          return { status: 'blocked', reason: 'guardrail_failed' };
-        }
-
-        return { status: 'success', result };
-      } catch (error) {
-        if (attempt === step.retry.max) {
-          return step.onFail === 'skip'
-            ? { status: 'skipped', error: String(error) }
-            : { status: 'failed', error: String(error) };
-        }
-        await this.backoff(step.retry.backoffMs * Math.pow(2, attempt));
-      }
-    }
-  }
-}
-```
-
-### 4.3 OpenCLI Adapter
-
-```typescript
-class OpenCLIAdapter {
-  constructor(private shell: ShellExecutor) {}
-
-  async execute(command: string, args: string[]): Promise<OpenCLIResult> {
-    const cmd = `opencli ${command} ${args.join(' ')}`;
-    const output = await this.shell.exec(cmd);
-    return this.parseOutput(output);
-  }
-
-  // 社交媒体数据获取
-  async scrapeSite(platform: string, query: string): Promise<ScrapedData> {
-    return this.execute(platform, ['search', `"${query}"`]);
-  }
-
-  // 私域聊天记录（需 PrivacyGuardrail 通过）
-  async fetchChatHistory(
-    platform: 'wx' | 'tg' | 'discord',
-    options: ChatFetchOptions
-  ): Promise<ChatMessage[]> {
-    const cmd = platform === 'wx' ? 'wx' : `opencli ${platform}`;
-    return this.execute(cmd, ['history', '--keyword', options.keyword]);
-  }
-
-  // CDP 浏览器控制
-  async controlBrowser(action: CDPAction): Promise<CDPResult> {
-    return this.execute('cdp', [action.type, `--selector`, action.selector]);
-  }
-}
-```
-
-### 4.4 Privacy Guardrail（私域数据访问控制）
-
-```typescript
-const PRIVACY_GUARDRAIL: Guardrail = async (ctx, step) => {
-  const sensitivePlatforms = ['wx', 'tg', 'discord', 'lark', 'wecom', 'dingtalk'];
-
-  if (sensitivePlatforms.includes(step.config?.platform as string)) {
-    // 检查是否有明确授权
-    if (!ctx.authorizedPlatforms?.includes(step.config.platform)) {
-      log('BLOCKED: Access to private data platform', { platform: step.config.platform });
-      return false;
-    }
-    // 记录访问日志
-    log('PRIVACY: Accessing private data', {
-      platform: step.config.platform,
-      scope: step.config.scope,
-    });
-  }
-  return true;
-};
-```
-
-### 4.5 默认工作流
-
-```typescript
-const DEFAULT_WORKFLOW: WorkflowStep[] = [
-  {
-    id: 'read',
-    type: 'read',
-    retry: { max: 3, current: 0, backoffMs: 1000 },
-    onFail: 'abort'
-  },
-  {
-    id: 'chunk',
-    type: 'chunk',
-    retry: { max: 0, current: 0, backoffMs: 0 },
-    onFail: 'abort'
-  },
-  {
-    id: 'summarize',
-    type: 'summarize',
-    retry: { max: 3, current: 0, backoffMs: 1000 },
-    onFail: 'skip',
-    guardrail: validateSummaryQuality
-  },
-  {
-    id: 'improve',
-    type: 'improve',
-    retry: { max: 2, current: 0, backoffMs: 1500 },
-    onFail: 'skip'
-  },
-  {
-    id: 'send',
-    type: 'send',
-    retry: { max: 2, current: 0, backoffMs: 2000 },
-    onFail: 'skip',
-    guardrail: validateSendTarget
-  }
-];
-
-// OpenCLI 增强工作流（可选）
-const OPENCLI_ENHANCED_WORKFLOW: WorkflowStep[] = [
-  {
-    id: 'scrape',
-    type: 'scrape',
-    config: { platform: 'zhihu', query: 'AI Agent' },
-    retry: { max: 2, current: 0, backoffMs: 500 },
-    onFail: 'skip',
-    guardrail: validatePublicDataAccess
-  },
-  {
-    id: 'enrich',
-    type: 'summarize',
-    retry: { max: 3, current: 0, backoffMs: 1000 },
-    onFail: 'skip'
-  },
-  {
-    id: 'send',
-    type: 'send',
-    retry: { max: 2, current: 0, backoffMs: 2000 },
-    onFail: 'skip',
-    guardrail: validateSendTarget
-  }
-];
-```
-
-## 5. 数据流
-
-```
-用户输入 → 约束层检查 → 工作流引擎
-                           │
-    ┌──────────────────────┼──────────────────────┐
-    ▼                      ▼                      ▼
-Read文档 → Chunk分块 → Summarize → (可选)Improve → Send
-    │           │           │              │
-    └───────────┴───────────┴──────────────┘
-                    │
-                    ▼
-              质量评估 → Guardrail检查 → 决策（重试/跳过/完成）
-
-┌─────────────────────────────────────────────────────────┐
-│  OpenCLI 增强数据流（零 Token）                           │
-│                                                           │
-│  Scrape → ChatHistory → Enrich → Summarize → Send        │
-│     │          │             │                           │
-│     └──────────┴─────────────┘                           │
-│              ↓                                            │
-│     PrivacyGuardrail（私域数据拦截）                       │
-└─────────────────────────────────────────────────────────┘
-```
-
-## 6. 安全机制
-
-### 6.1 敏感操作 Guardrail
-
-```typescript
-// 发送到新节点时拦截
-const validateSendTarget: Guardrail = async (ctx, step) => {
-  const targetPeer = step.config?.peerId as string;
-  if (!ctx.peers.includes(targetPeer)) {
-    log('BLOCKED: Sending to unknown peer', { targetPeer });
-    return false; // 拦截，等待确认
-  }
-  return true;
-};
-
-// 摘要质量检查
-const validateSummaryQuality: Guardrail = async (ctx) => {
-  if (ctx.qualityScore < 0.5) {
-    log('WARN: Low quality summary', { score: ctx.qualityScore });
-    return false; // 触发重试
-  }
-  return true;
-};
-
-// OpenCLI 数据访问权限检查
-const validateOpenCLIAccess: Guardrail = async (ctx, step) => {
-  const platform = step.config?.platform as string;
-  const privatePlatforms = ['wx', 'tg', 'discord', 'lark', 'wecom', 'dingtalk'];
-
-  if (privatePlatforms.includes(platform)) {
-    if (!ctx.userConsent?.includes(platform)) {
-      log('BLOCKED: No consent for private platform', { platform });
-      return false;
-    }
-    log('ALLOWED: Private platform access', { platform });
-  }
-  return true;
-};
-
-// 公共数据访问检查（用于 scrape 步骤）
-const validatePublicDataAccess: Guardrail = async (ctx, step) => {
-  const platform = step.config?.platform as string;
-  const whitelist = ['zhihu', 'bilibili', 'xiaohongshu', 'reddit', 'hackernews'];
-
-  if (!whitelist.includes(platform)) {
-    log('BLOCKED: Unsupported platform', { platform });
-    return false;
-  }
-  return true;
-};
-```
-
-### 6.2 Privacy Guardrail 决策流程
-
-```
-数据访问请求 → 平台分类 → 公共平台? ─Yes─→ 放行
-                              │
-                              No
-                              ▼
-                    授权平台列表检查 ─Yes─→ 放行 + 记录日志
-                              │
-                              No
-                              ▼
-                         拦截 + 等待用户确认
-```
-
-### 6.3 操作日志
-
-```typescript
-interface OperationLog {
-  timestamp: number;
-  action: string;
-  details: Record<string, unknown>;
-  status: 'success' | 'failed' | 'blocked';
-}
-
-const logs: OperationLog[] = [];
-```
-
-## 7. 文件结构
-
-```
-src/
-├── agents/
-│   ├── pi-sdk.ts           # AgentSession（已存在）
-│   ├── constraint-layer.ts # 约束层实现
-│   ├── workflow-engine.ts  # 工作流引擎
-│   └── opencli-adapter.ts  # NEW: OpenCLI 命令适配器
-├── browser/
-│   ├── cdp-controller.ts   # NEW: CDP 浏览器控制
-│   └── electron-bridge.ts   # NEW: Electron 应用桥接
-├── privacy/
-│   ├── guardrails.ts       # NEW: 隐私 guardrail 实现
-│   └── consent-manager.ts   # NEW: 用户授权管理
-├── data/
-│   ├── reader.ts           # 文档读取（已存在）
-│   ├── scraper.ts          # NEW: 网页数据抓取
-│   └── chat-fetcher.ts     # NEW: 私域聊天记录获取
-├── llm/
-│   └── minimax.ts          # LLM调用（已存在）
-├── network/
-│   └── p2p.ts              # P2P网络（已存在）
-└── index.ts                # 入口（已存在）
-```
-
-### 7.1 OpenCLI 安装与配置
-
-```bash
-# 安装 OpenCLI（Node.js 21+）
-npm install -g @jackwener/opencli
-
-# 安装私域聊天适配器
-npm install -g @jackwener/wx-cli      # 微信
-npm install -g @jackwener/tg-cli      # Telegram
-npm install -g @jackwener/discord-cli # Discord
-
-# 初始化微信（需 root 权限）
-sudo wx init
-
-# 验证安装
-opencli list
-```
-
-## 8. 实现顺序
-
-1. **约束层** (`constraint-layer.ts`) - Prompt 管理与拦截
-2. **工作流引擎** (`workflow-engine.ts`) - 执行与重试逻辑
-3. **OpenCLI 适配器** (`opencli-adapter.ts`) - 命令执行与结果解析
-4. **隐私 Guardrail** (`guardrails.ts`) - 私域数据访问控制
-5. **CDP 控制器** (`cdp-controller.ts`) - 浏览器自动化
-6. **集成** - 将各组件集成到 `AgentSession`
-7. **测试** - 验证各步骤和重试机制
-
-## 9. OpenCLI 能力矩阵
-
-| 平台 | 搜索 | 下载 | 历史记录 | 自动化 |
-|------|------|------|----------|--------|
-| 知乎 | ✅ | ✅ | - | ✅ |
-| B站 | ✅ | ✅ | - | ✅ |
-| 小红书 | ✅ | ✅ | - | ✅ |
-| 微信公众号 | ✅ | ✅ | - | ✅ |
-| Reddit | ✅ | ✅ | - | ✅ |
-| Twitter/X | ✅ | ✅ | - | ✅ |
-| 微信 | ✅ | - | ✅ | - |
-| Telegram | ✅ | - | ✅ | - |
-| Discord | ✅ | - | ✅ | ✅ |
-| 飞书 | ✅ | ✅ | ✅ | ✅ |
-| 企业微信 | ✅ | ✅ | ✅ | - |
-| 钉钉 | ✅ | ✅ | ✅ | - |
-| GitHub | ✅ | ✅ | - | ✅ |
-| Google Scholar | ✅ | ✅ | - | - |
-
-**注**：零 Token 消耗指的是 OpenCLI 命令执行本身不消耗 LLM Token，但解析结果用于 LLM 处理时仍会产生 Token 消耗。