metainsight-context-engine 0.0.1 → 0.0.4

package/BOOTSTRAP.md

@@ -1,341 +0,0 @@
-# COS Bootstrap — 前置条件初始化
-
-> Cloud Context Engine 的基础设施初始化模块，负责在引擎启动前确保所有云端资源就绪。
-
-## 概述
-
-`cos-bootstrap.ts` 是 Cloud Context Engine 的**第一个执行步骤**。它会自动检测并创建以下云端资源：
-
-1. **COS 存储桶** — 用于存储所有文档和数据
-2. **CI 数据集** — 用于智能文档搜索（支持多个数据集）
-3. **数据集绑定** — 将数据集关联到存储桶中的指定路径前缀
-
-```
-┌──────────────────────────────────────────────────────────────────────┐
-│                    COS 存储桶                                        │
-│            openclaw-metainsight-{APPID}                              │
-│                                                                     │
-│   ┌─────────────────┐  ┌──────────────────────────┐  ┌───────────┐ │
-│   │  memory/         │  │  asset/                   │  │  其他路径/ │ │
-│   │  *.md            │  │  *.jpg/png/pdf/...        │  │  (可扩展) │ │
-│   └──────┬──────────┘  └──────┬──────────┬─────────┘  └─────┬─────┘ │
-│          │                    │          │                   │       │
-│          ▼                    ▼          ▼                   ▼       │
-│   ┌─────────────────┐  ┌──────────┐ ┌──────────┐    ┌───────────┐  │
-│   │ memory 数据集    │  │ image    │ │ document │    │ 自定义    │  │
-│   │ DocSearch       │  │ ImgSearch│ │ DocSearch│    │ (可扩展)  │  │
-│   └─────────────────┘  └──────────┘ └──────────┘    └───────────┘  │
-└──────────────────────────────────────────────────────────────────────┘
-```
-
-## 前置条件
-
-### 1. 获取腾讯云访问密钥
-
-前往 [腾讯云 CAM 控制台](https://console.cloud.tencent.com/cam/capi) 获取以下信息：
-
-| 参数 | 说明 | 示例 |
-|------|------|------|
-| **SecretId** | 访问密钥 ID | `AKIDxxxxxxxxxxxxxxxxxxxx` |
-| **SecretKey** | 访问密钥 Key | `xxxxxxxxxxxxxxxxxxxxxxxxx` |
-| **APPID** | 腾讯云账号 APPID | `1253311026` |
-
-> ⚠️ **安全提示**：密钥应通过环境变量或安全配置管理传入，切勿硬编码到代码中。
-
-### 2. 地域限制
-
-COS CI（智能内容识别）仅支持以下地域：
-
-| 地域 | 地域代码 |
-|------|----------|
-| 北京 | `ap-beijing` |
-| 上海 | `ap-shanghai` |
-| 成都 | `ap-chengdu` |
-
-### 3. SDK 依赖
-
-```bash
-npm install cos-nodejs-sdk-v5
-```
-
-> **注意**：必须使用 `cos-nodejs-sdk-v5`（Node.js 版本），不支持 `cos-js-sdk-v5`（浏览器版本）。
-
-## 配置说明
-
-### 最小配置（使用默认值）
-
-```typescript
-import { bootstrap } from './cos-bootstrap.js';
-
-const outcome = await bootstrap({
-  secretId: process.env.COS_SECRET_ID!,
-  secretKey: process.env.COS_SECRET_KEY!,
-  appId: process.env.COS_APPID!,
-}, logger);
-```
-
-默认行为：
-- **bucket**: `openclaw-metainsight`（自动拼接 APPID → `openclaw-metainsight-{APPID}`）
-- **region**: `ap-beijing`
-- **datasets**: 三个默认数据集
-  - `openclaw-memory` — 绑定到 `memory/` 路径（对话记忆，DocSearch）
-  - `openclaw-image` — 绑定到 `asset/` 路径（图片检索，ImageSearch）
-  - `openclaw-document` — 绑定到 `asset/` 路径（文档检索，DocSearch）
-
-### 完整配置
-
-```typescript
-const outcome = await bootstrap({
-  secretId: 'AKIDxxxx',
-  secretKey: 'xxxx',
-  appId: '1253311026',
-
-  // 可选：自定义 bucket 名称（不含 APPID 后缀）
-  bucket: 'my-custom-bucket',
-
-  // 可选：自定义地域
-  region: 'ap-shanghai',
-
-  // 可选：自定义数据集定义
-  datasets: [
-    {
-      name: 'my-memory',
-      cosPrefix: 'memory/',
-      templateId: 'Official:DocSearch',
-      description: '对话记忆文档数据集',
-    },
-  ],
-}, logger);
-```
-
-### 配置字段说明
-
-#### `CosBootstrapConfig`
-
-| 字段 | 必填 | 默认值 | 说明 |
-|------|------|--------|------|
-| `secretId` | ✅ | — | 腾讯云访问密钥 ID |
-| `secretKey` | ✅ | — | 腾讯云访问密钥 Key |
-| `appId` | ✅ | — | 腾讯云 APPID，从 [CAM 控制台](https://console.cloud.tencent.com/cam/capi) 获取 |
-| `bucket` | ❌ | `openclaw-metainsight` | 存储桶短名称（不含 APPID 后缀，会自动拼接） |
-| `region` | ❌ | `ap-beijing` | COS 地域代码 |
-| `datasets` | ❌ | memory + image + document 数据集 | 数据集定义数组 |
-
-#### `DatasetDefinition`
-
-| 字段 | 必填 | 默认值 | 说明 |
-|------|------|--------|------|
-| `name` | ✅ | — | CI 数据集名称（APPID 范围内唯一） |
-| `cosPrefix` | ✅ | `{name}/` | COS 路径前缀，绑定覆盖的范围（必须以 `/` 结尾） |
-| `templateId` | ❌ | `Official:DocSearch` | CI 数据集模板 |
-| `description` | ❌ | 自动生成 | 数据集描述 |
-
-#### 可用的数据集模板
-
-| 模板 ID | 说明 | 适用场景 |
-|---------|------|----------|
-| `Official:DocSearch` | 文档搜索 | memory 等文本文档 |
-| `Official:ImageSearch` | 图像搜索 | 图像内容检索 |
-| `Official:FaceSearch` | 人脸搜索 | 人脸识别检索 |
-| `Official:COSBasicMeta` | COS 基础元信息 | 文件元数据索引 |
-
-## 数据集架构
-
-### 默认数据集
-
-当 `datasets` 参数省略时，自动创建以下三个数据集：
-
-#### memory 数据集
-
-```
-数据集名称: openclaw-memory
-绑定路径:   cos://{bucket}/memory/
-模板:       Official:DocSearch
-用途:       存储对话记忆文档，支持语义搜索
-```
-
-文件存储约定：
-```
-memory/
-  ├── conversation-{id}.json    # 对话记忆
-  ├── summary-{id}.json         # 对话摘要
-  └── ...
-```
-
-#### image 数据集
-
-```
-数据集名称: openclaw-image
-绑定路径:   cos://{bucket}/asset/
-模板:       Official:ImageSearch
-用途:       图片内容检索，支持多模态（文本→图片）语义搜索
-```
-
-#### document 数据集
-
-```
-数据集名称: openclaw-document
-绑定路径:   cos://{bucket}/asset/
-模板:       Official:DocSearch
-用途:       文档内容检索，对 asset/ 目录下的文档进行语义搜索
-```
-
-文件存储约定：
-```
-asset/
-  ├── screenshot.png            # 图片文件（由 image 数据集索引）
-  ├── images/
-  │   └── photo.jpg
-  ├── report.pdf                # 文档文件（由 document 数据集索引）
-  └── ...
-```
-
-> 📝 **多 Agent 模式**下，数据集名称会带上 agentId：
-> - memory: `openclaw-{agentId}-memory`（路径: `openclaw-{agentId}/workspace/`）
-> - image: `openclaw-{agentId}-image`（路径: `openclaw-{agentId}/asset/`）
-> - document: `openclaw-{agentId}-document`（路径: `openclaw-{agentId}/asset/`）
-
-### 如何扩展新数据集
-
-只需在 `datasets` 数组中追加新定义：
-
-```typescript
-datasets: [
-  // 已有默认数据集（显式声明时需手动包含）
-  { name: 'openclaw-memory', cosPrefix: 'memory/' },
-  { name: 'openclaw-image', cosPrefix: 'asset/', templateId: 'Official:ImageSearch' },
-  { name: 'openclaw-document', cosPrefix: 'asset/' },
-
-  // 新增：知识库数据集
-  {
-    name: 'openclaw-knowledge',
-    cosPrefix: 'knowledge/',
-    templateId: 'Official:DocSearch',
-    description: '外部知识库文档数据集',
-  },
-],
-```
-
-Bootstrap 会自动：
-1. 检测每个数据集是否存在，不存在则创建
-2. 检测每个数据集的绑定是否存在，不存在则创建
-3. 所有操作都是**幂等的**：重复运行不会出错
-
-## Bootstrap 输出
-
-```typescript
-interface BootstrapOutcome {
-  success: boolean;          // 整体是否成功
-  cos: COS;                  // COS SDK 实例（后续操作直接使用）
-  config: ResolvedCosConfig; // 解析后的完整配置
-  bucketCreated: boolean;    // 存储桶是否是本次新创建的
-  datasetOutcomes: Array<{   // 每个数据集的初始化结果
-    name: string;            // 数据集名称
-    cosPrefix: string;       // 绑定路径
-    datasetCreated: boolean; // 是否新创建
-    bindingCreated: boolean; // 绑定是否新创建
-  }>;
-  error?: string;            // 失败时的错误信息
-}
-```
-
-## 执行流程
-
-```
-bootstrap(config, logger)
-        │
-        ▼
-  ┌─ resolveConfig ──────────────────────────────┐
-  │  • 校验 appId、region                        │
-  │  • 拼接 bucket: {name}-{APPID}               │
-  │  • 解析 datasets（默认: memory + image + document）│
-  │  • 校验无重复数据集名称                       │
-  └──────────────────────────────────────────────┘
-        │
-        ▼
-  ┌─ Step 1: 存储桶 ─────────────────────────────┐
-  │  headBucket → 存在? 跳过 : putBucket 创建     │
-  └──────────────────────────────────────────────┘
-        │
-        ▼
-  ┌─ Step 2: 遍历 datasets ──────────────────────┐
-  │  for each dataset:                            │
-  │    2a. GET /dataset → 存在? 跳过 : POST 创建  │
-  │    2b. GET /datasetbinding → 存在? 跳过 :     │
-  │        POST 创建 (URI: cos://{bucket}/{prefix})│
-  └──────────────────────────────────────────────┘
-        │
-        ▼
-  BootstrapOutcome { success: true, ... }
-```
-
-## 辅助工具
-
-### `sendCIRequest()` — CI API 通用请求
-
-```typescript
-import { sendCIRequest, getCOSInstance } from './cos-bootstrap.js';
-
-const cos = getCOSInstance(secretId, secretKey);
-const result = await sendCIRequest(
-  cos,
-  'bucket-name-1253311026',
-  'ap-beijing',
-  'POST',                    // HTTP 方法
-  'datasetquery/hybridsearch', // CI API 端点
-  { /* 请求体 */ },
-  { /* 查询参数 */ },
-);
-```
-
-该方法自动处理：
-- COS SDK 签名鉴权
-- JSON 请求/响应序列化
-- CI API Host 拼接（`{bucket}.ci.{region}.myqcloud.com`）
-
-### `getCOSInstance()` — COS SDK 单例
-
-相同 `secretId` 返回同一实例，避免重复初始化：
-
-```typescript
-const cos1 = getCOSInstance(secretId, secretKey);
-const cos2 = getCOSInstance(secretId, secretKey);
-// cos1 === cos2 → true
-```
-
-## 内置保障
-
-| 特性 | 说明 |
-|------|------|
-| **幂等性** | 所有操作都是先检测后创建，重复执行安全无副作用 |
-| **自动重试** | 网络请求失败自动重试 2 次，指数退避（1s / 2s） |
-| **TTL 缓存** | 数据集和绑定查询结果缓存 5 分钟，减少 API 调用 |
-| **错误容错** | 新建桶后查询数据集可能返回 400（而非 404），已兼容处理 |
-| **Bucket 命名** | 自动拼接 APPID 后缀，已含 APPID 时不重复拼接 |
-| **cosPrefix 规范化** | 自动在路径末尾补 `/` |
-
-## 常见问题
-
-### Q: APPID 在哪里获取？
-
-前往 [腾讯云 CAM 控制台](https://console.cloud.tencent.com/cam/capi)，APPID 显示在密钥列表上方的账号信息区域。也可以通过 `getService`（ListBuckets）API 从返回的 Owner 字段获取。
-
-### Q: 为什么 Bucket 名称要带 APPID？
-
-COS 全局 Bucket 命名格式为 `{BucketName}-{APPID}`，这是腾讯云的强制要求。Bootstrap 会自动处理拼接。
-
-### Q: 数据集绑定后多久生效？
-
-绑定创建后状态会从 `Creating` 变为 `Running`，通常在几秒内完成。绑定生效后，往对应路径上传的文件会自动被索引。
-
-### Q: 能否给同一路径绑定多个数据集？
-
-可以。`image` 和 `document` 数据集都绑定到 `asset/` 路径，但使用不同的模板（`ImageSearch` vs `DocSearch`）。CI 会根据模板类型对同一路径下的文件进行不同方式的索引。
-
-### Q: memory 数据集的数据源是什么？
-
-memory 数据集绑定到 `memory/` 路径，数据源是本地的 memory 文件夹中的对话记忆文件。上传到 `cos://{bucket}/memory/` 的 JSON 文件会自动被 CI 索引，支持后续的语义搜索。
-
-### Q: image 数据集如何使用？
-
-image 数据集绑定到 `asset/` 路径，使用 `Official:ImageSearch` 模板。上传到 `cos://{bucket}/asset/` 的图片文件（jpg/png 等）会自动被 CI 索引。检索时通过 `category="image"` 路由到该数据集，`Templates` 会自动切换为 `ImageSearch`，支持文本→图片的多模态语义搜索。