# MTA 项目架构笔记：媒体到 Agent 的数据管道

## MTA 是什么

MTA = Media to Agent。

一句话概括：**把各种形态的媒体内容，变成 AI Agent 能理解和处理的结构化数据。**

听起来有点抽象。举个具体的例子：

```
一段直播录像（视频）
  ↓
语音转文字（音频→文本）
  ↓
主播说了什么、什么时候说了什么
  ↓
Agent 分析：这段讲的是产品介绍，这段是互动环节
  ↓
Agent 决策：根据分析结果执行操作
```

MTA 就是这条管道的骨架。

---

## 为什么需要 MTA

在搭 MTA 之前，我的工作流是：

```
看到一个直播片段 → 手动看回放 → 记笔记 → 告诉 Agent 去执行
```

这里面有几个瓶颈：

1. **时间差** — 从看到信息到 Agent 执行，中间隔了"人"这个环节
2. **信息损耗** — 人工转述会有遗漏和偏差
3. **规模限制** — 一天几十个小时的直播内容，看完就不现实
4. **非实时** — 只能事后分析，不能实时感知

MTA 想解决的问题就是：**让 Agent 能"看"媒体、"听"媒体，不需要人在中间当翻译。**

---

## 架构演变

### V1：原型（验证可行性）

```
媒体文件 → 本地 Whisper 转写 → 文本文件 → 手动喂给 Agent
```

最原始的版本。用 OpenAI Whisper 做语音转写，结果存成 txt，然后手动丢给 LLM。

问题很明显：
- 转写结果散落在各处，没有统一管理
- 每次都要手动操作，步骤重复
- 只能处理音频，不能处理视频流

### V2：管道化（打通流程）

```
媒体源                    处理层                  存储层                  消费层
┌──────┐              ┌──────────┐           ┌──────────┐           ┌──────────┐
│ 视频  │──检测格式──→  │ 语音转写  │──结构化──→│ 数据库   │──检索──→  │ Agent   │
│ 音频  │──提取音轨    │ 说话人分离 │──元数据  │          │          │          │
│ 直播  │              │ NER提取   │          │          │          │          │
└──────┘              └──────────┘           └──────────┘           └──────────┘
```

把处理流程拆成独立阶段，每个阶段可独立部署、独立替换。

### V3（当前）：平台化

第三代还在迭代中，目标是做成通用平台：

```
输入层             处理引擎            存储与索引           API 层             输出层
┌────┐     ┌──────────────┐     ┌──────────────┐     ┌────────────┐     ┌──────────┐
│RSS  │     │ 语音识别      │     │ 向量数据库    │     │ 搜索 API    │     │ AI Agent │
│API  │────→│ NLP 分析      │────→│ 知识图谱      │────→│ 事件订阅    │────→│ 用户通知  │
│文件  │     │ 实体解析      │     │ 时间线索引    │     │ 分析报告    │     │ Dashboard│
│直播  │     │ 质量评分      │     │              │     │            │     │          │
└────┘     └──────────────┘     └──────────────┘     └────────────┘     └──────────┘
```

特点：
- **插件化处理引擎** — 语音识别、NLP、实体提取都是独立模块，可插拔
- **统一数据模型** — 所有媒体处理后的输出遵循同一份 schema
- **事件驱动** — 新内容处理完成后主动通知消费者
- **水平扩展** — 处理引擎可多实例并行（不过单机场景暂时用不上）

---

## 核心技术选型

### 语音转写

| 引擎 | 准确性 | 速度 | 资源占用 | 选择 |
|------|-------|------|---------|------|
| Whisper 本地 | 高（多语言） | 慢 | GPU > 6GB | ❌ 太重 |
| Whisper API | 高 | 快 | 无 | ✅ 主力 |
| Vosk | 中 | 极快 | 低 | ❌ 中文一般 |
| FunASM | 高 | 中 | 中 | 待评估 |

目前用云端 Whisper API，本地 RTX4060Ti 跑 whisper.cpp 做离线兜底。

### 说话人分离

多人对话场景（直播连麦、会议）需要区分谁在说话。

- **基于频谱分析** — 传统方法，效果好但依赖音频质量
- **基于模型** — pyannote-audio，效果好但资源消耗大
- **基于时间戳** — 引入外部标注，对已知场景够用

当前方案：时间戳 + 声纹特征简化版，对直播间场景（主播 + 观众问答）已经够用。

### 结构化提取

原始转写文本只是一堆字，需要进一步处理才有价值：

```
原始转写：
"欢迎来到直播间，今天给大家带来一款新茶，铁观音的新工艺
 啊，这个茶汤特别透亮，入口回甘很快"

结构化提取：
{
  "speaker": "主播",
  "segments": [
    {"type": "greeting", "text": "欢迎来到直播间"},
    {"type": "product_intro", "product": "铁观音新工艺",
     "features": ["茶汤透亮", "入口回甘快"]}
  ],
  "call_to_action": false,
  "products_mentioned": ["铁观音新工艺"]
}
```

提取过程用 LLM 完成（few-shot + schema 约束），准确率大约 85%，对后续决策够用了。

---

## 当前状态：V3 后端开发中

项目目前处于 V3 后端开发阶段。V2 管道化的核心流程已经跑通了，当前工作重点：

1. **统一的媒体接入层** — 支持 RSS 订阅源、API 推送、文件上传三种接入方式
2. **处理引擎标准化** — 所有处理模块遵循同一接口，方便替换和组合
3. **结构化存储** — 向量数据库 + 关系型数据库的混合存储方案
4. **事件系统** — 处理完成后的主动通知机制

---

## 实际使用场景

### 场景 1：直播内容分析

```
输入：铁观音直播间回放（4小时视频）
输出：
- 产品出现的频次和时间点
- 互动高峰时段
- 主播话术分析（什么措辞转化率高）
- 竞品提及分析
```

### 场景 2：课程转录

```
输入：千川投放线下培训录音（1.5小时）
输出：
- 结构化笔记，按知识点分段
- 关键数据指标提取
- 实操步骤拆解
- 自动入库到知识库（ChromaDB）
```

### 场景 3：实时监控

```
输入：直播间实时音频流
输出：
- 关键词命中告警（提到竞品、违规词）
- 互动密度变化检测
- 自动生成跟播建议
```

---

## 踩坑记录

**1. 长音频的处理**
4 小时直播直接丢给 Whisper 会 OOM。解决方案：按静音段切割 + 流式处理，每次处理 30 秒窗口。

**2. 说话人分离的精度**
直播间背景音乐干扰严重，传统声纹效果差。妥协方案：大部分场景只标注"主播/非主播"两分类，够用即可。

**3. 时间线对齐**
视频 + 语音 + 转写文本三个时间轴对齐——这是 V2 阶段最耗时的 debug。最后用了 ffmpeg 的时间基做统一参考系。

**4. 存储架构选择**
纯向量数据库存结构化数据很别扭（ChromaDB 不适合时间范围查询），纯关系型存 embedding 也很别扭。最终方案：双写——向量库管搜索，PG 管精确查询和时间线。

---

## 未来方向

- **实时流处理** — 从"事后分析"到"实时感知"
- **多模态融合** — 不只是音频，还有画面分析（直播中的产品展示）
- **反馈闭环** — Agent 基于分析结果执行操作后，操作效果回流到 MTA，形成学习循环
- **轻量化部署** — 一套 docker-compose 搞定，别人也能直接用

MTA 项目架构笔记：媒体到 Agent 的数据管道

# 知识库系统从 0 到 1：本地语义搜索的轻量方案

## 为什么要自己搭知识库

市面上知识库方案很多：Notion、飞书文档、Confluence……每个都能用。但我的需求比较特殊：

1. **数据隐私** — 知识库里包含商业数据（千川投放策略、业务数据），不想走云服务
2. **AI 原生** — 知识库的消费方不是人，是 AI Agent。需要 API 接口，不是 GUI
3. **语义搜索** — 精确关键词命中不够，要能"意思差不多也能搜到"
4. **增量更新** — 知识在持续增长，不能每次重建索引
5. **本地运行** — 没有云预算，全靠一台带 RTX4060Ti 的台式机

基于这些条件，我搭了一套全本地化的知识库系统。

---

## 架构总览

```
数据源层                    索引层                   检索层
┌─────────────┐        ┌──────────────┐        ┌────────────┐
│ 医学手册(MSD)├───────→│              │        │            │
│ 中文精要    │        │  ChromaDB    │←───────│  kb-api    │
│ 转录文档    │        │  (向量数据库) │        │  (8120)    │
│ 项目笔记    │───────→│              │        │            │
└─────────────┘        └──────┬───────┘        └────────────┘
                              │
                        ┌─────▼──────┐
                        │  embedding  │
                        │ 模型(Silicon│
                        │  Flow API)  │
                        └────────────┘

监控层
┌─────────────┐
│  kb-watch   │
│ 文件变动→自动│
│ 增量索引    │
└─────────────┘
```

### 组件清单

| 组件 | 技术选型 | 端口 | 功能 |
|------|---------|------|------|
| 向量数据库 | ChromaDB | — | 存储 embeddings + 元数据 |
| Embedding | Ollama(bge-m3) → SiliconFlow API | — | 文本转向量 |
| 检索服务 | kb-api | 8120 | RESTful 语义搜索 |
| 文件监控 | kb-watch | — | 目录变化感知 + 自动索引 |

---

## 为什么是 ChromaDB

对比了几款主流方案：

| 方案 | 部署复杂度 | 语义搜索 | 持久化 | 社区 | 资源占用 |
|------|-----------|---------|-------|------|---------|
| ChromaDB | ★☆☆ 极简 | ✅ | ✅ | 活跃 | 低 |
| Qdrant | ★★★ 适中 | ✅ | ✅ | 活跃 | 中 |
| Milvus | ★★★★★ 重 | ✅ | ✅ | 大厂 | 高 |
| Pinecone | 云服务 | ✅ | ✅ | — | 托管 |
| Weaviate | ★★★ 适中 | ✅ | ✅ | 活跃 | 中 |

ChromaDB 胜在**极简部署**——`pip install chromadb` 就能跑。API 设计也干净，针对我这个"本地运行、文档数量万级"的场景刚刚好。

实际规模：**2827 个文件，49237 个 chunk，约 192MB**——ChromaDB 对这种体量处理得毫无压力。

---

## Embedding 模型的选择

Embedding 质量直接影响搜索结果。踩了几天坑，最后选了这条路：

**初期：Ollama 本地模型**
用 `bge-m3` 跑本地 embedding。好处是纯离线，缺点也很明显——8GB 显存里跑 embedding 和其他模型抢资源，推理速度也慢（单条几百毫秒）。

**生产：SiliconFlow API**
切换到 SiliconFlow 的云端 embedding API：
- 延迟低（几十毫秒）
- 质量稳定
- 价格便宜（embedding 本身就很便宜）
- 不占本地 GPU 资源

**兜底：Ollama 本地**
万一联网断了，自动 fallback 回 Ollama 本地模型，保持服务不中断。

---

## kb-api：检索服务设计

`kb-api` 跑在 8120 端口，提供两个核心端点：

### 语义搜索

```
POST /search
{
  "query": "铁观音跟播ROI设置",     // 自然语言查询
  "top_k": 5,                       // 返回条数
  "threshold": 0.35                 // 相似度阈值
}

→ {
  "results": [
    {
      "content": "跟播方案：铁观音账号每天09:00-17:00，
                  ROI ≥ 10 预算不限...",
      "metadata": {
        "source": "铁观音跟播方案.md",
        "category": "千川投放"
      },
      "score": 0.82
    },
    ...
  ]
}
```

### 知识检索（供 Agent 调用）

```
POST /query
{ "query": "千川的品广加热怎么操作" }

→ 结构化的上下文摘要，含来源引用
```

### 混合搜索策略

纯语义搜索有一个问题：匹配"意思"而不是"关键词"。有时候用户/Agent 确实需要精确命中。

```
最终分数 = 0.7 × 语义相似度 + 0.3 × 关键词命中

# 关键词命中 = BM25分数归一化
# 语义相似度 = Cosine(查询向量, 文档向量)
```

权重可调，对知识密集场景（如医学词汇）会加大关键词权重。

---

## kb-watch：增量索引

知识库最怕的是——文档改了，但搜索还是旧内容。

`kb-watch` 解决的：
- 监控 `knowledge-fill/` 目录的 inotify 事件
- 文件新增/修改 → 重新 chunk → 重新 embed → 更新 ChromaDB
- 文件删除 → 清理对应索引

增量更新一般在 **秒级** 完成（仅处理变化部分），不影响服务可用性。

---

## 数据源：knowledge-fill 管道

知识库的数据来自 `knowledge-fill` 项目：

**数据源：**
- **MSD Manual（英文学手册）** — 爬取整理的专业医学参考
- **中文医学精要** — 翻译编译的中文版
- **转录文档** — 千川投放培训课的语音转录
- **项目笔记** — 日常操作中沉淀的 markdown 笔记

**处理流程：**
```
原始文档 → 清理格式化 → 智能 chunk（~512 tokens）→ 提取元数据 → 写入 ChromaDB
```

Chunk 策略很重要：
- 太短（<100 tokens）→ 上下文不足，搜索出来读不懂
- 太长（>1000 tokens）→ 语义模糊，容易 scope drift
- 重叠 10-20% → 避免边界截断

---

## 与 Agent 系统的集成

知识库的最终消费者是 AI Agent。Agent 在需要时通过 kb-api 获取上下文：

```python
def search_knowledge(query: str) -> str:
    """Agent 调用知识库的接口"""
    resp = requests.post("http://127.0.0.1:8120/search", json={
        "query": query,
        "top_k": 3
    })
    contexts = resp.json()["results"]
    # 组装成 LLM 友好的格式
    return "\n\n".join([
        f"[来源：{c['metadata']['source']}]\n{c['content']}"
        for c in contexts
    ])
```

效果：Agent 回答千川相关问题时的准确率从 **~60% 提升到 ~85%**（目测），尤其是那些"我记得说过但不确定在哪"的知识点。

---

## 踩坑记录

**1. ChromaDB 并发写**
多进程同时写入会报锁错误。解决方案：写操作串行化，读操作放开并发。

**2. Chunk 重叠导致重复**
前后 chunk 各 50% 重叠，遇到短文档会产出几乎相同的多个 chunk。加了去重逻辑——ChromaDB 同一 source 下的 content hash 去重。

**3. Embedding 维度不一致**
切换 embedding 模型后发现向量维度变了（bge-m3 是 1024，另一个模型是 768）。解决办法：一个 collection 只绑一个 embedding 模型，切换模型时新建 collection。

**4. kb-watch inotify 限制**
监控超 8192 个文件时需要调大 `/proc/sys/fs/inotify/max_user_watches`。

---

## 适合谁抄作业

- 有本地部署需求的个人/小团队
- 需要给 AI 应用挂知识库的开发者
- 数据敏感不想上云的内容运营

整套方案零云成本，依赖就是一台有 Python 环境的 Linux 机器。ChromaDB + kb-api 加起来不到 500 行核心代码，维护成本很低。

---

## 未来

- **多模态** — 支持图片、PDF 的语义检索
- **知识图谱** — 在向量之上叠加实体关系
- **自动摘要** — 检索结果由 Agent 自动摘要，提升阅读效率

知识库系统从 0 到 1：本地语义搜索的轻量方案

# 千川广告 CDP 自动化：不用 Selenium 的 Chrome 操控方案

## 为什么不用 Selenium

接触过电商广告投放自动化的朋友，第一个想到的肯定是 Selenium 或 Playwright。我也试过，但痛点很明显：

- **慢** — 每次启动浏览器 + 加载页面，十几秒就没了
- **容易被检测** — 平台对自动化工具越来越敏感（user-agent、navigator.webdriver）
- **元素定位脆弱** — 千川的 DOM 结构三天两头变，XPath 说废就废
- **Cookie 管理麻烦** — 需要持久化的登录态，Selenium 的 profile 管理不够透明

**Chrome DevTools Protocol（CDP）** 是另一条路。它不是模拟用户操作，而是通过 WebSocket 协议直接控制 Chrome 的 DevTools 功能。

---

## CDP 方案的优势

```
Selenium 模式                    CDP 模式
┌──────────────┐               ┌──────────────┐
│ 模拟点击输入  │    vs.         │ 直接调 API   │
│ ← 慢速、脆弱  │               │ ← 快速、稳定  │
│ 浏览器检测风险 │               │ ← 无痕迹     │
│ 依赖 selector │               │ ← DOM 直接交互│
└──────────────┘               └──────────────┘
```

- **速度** — 页面一加载完就能操作，不用等模拟渲染
- **隐身性** — CDP 本身是 Chrome 的标准调试协议，不存在检测问题
- **稳定性** — 通过 `Runtime.evaluate` 直接执行 JS，不用找元素定位
- **持久 Profile** — 指定 Chrome 用户数据目录，Cookie/登录态天然持久

---

## 架构：两个浏览器实例

```
桌面 Chrome (9222)          Headless Chrome (9223)
  日常跟播、监控                定时任务、批量操作
  ┌─────────────────┐         ┌─────────────────┐
  │ GUI 可见         │         │ 后台运行         │
  │ 实时跟播调控      │         │ 素材追投          │
  │ ROI 监控          │         │ 一键调速          │
  │ 计划新建/编辑     │         │ 数据拉取          │
  └─────────────────┘         └─────────────────┘
```

**9222（桌面）**：启动时 `--remote-debugging-port=9222`，日常跟播时我还能看到浏览器界面，做人工干预。

**9223（Headless）**：纯后台运行，处理定时任务（素材追投、预算调控、数据采集）。

---

## 登录流程：最头疼的部分

千川（巨量引擎）登录走的是字节的 SSO 系统，Cookie 有效期不长，过期就要重新登录。

### 自动重登方案

```
1. POST business.oceanengine.com/login
2. 切换到密码登录模式
3. 填入邮箱: 2601890547@qq.com
4. 填入密码
5. 点击登录按钮
6. 验证页面跳转后的 Cookie
7. 跳转到千川后台 (qianchuan.jinritemai.com/brand_bid/)
```

关键点：
- **窗口复用** — 不每次新开窗口，复用已有标签页节省资源
- **Cookie 持久化** — Profile 目录设在数据盘 `/data/hermes/chrome-profile/`，重启不丢
- **Session 检测** — 操作前先检查当前页面是否登录过期，发现过期自动重登

### CDP 操作脚本核心流程

```python
# 1. 连接到 Chrome
import json, requests
ws_endpoint = json.loads(
    requests.get("http://127.0.0.1:9222/json/version").text
)["webSocketDebuggerUrl"]

# 2. 获取已有标签页或新建
tabs = json.loads(requests.get("http://127.0.0.1:9222/json").text)
target = next((t for t in tabs if "qianchuan" in t["title"]), None)
if not target:
    # 新建标签页并导航
    ...

# 3. 通过 CDP 执行 JavaScript
# Runtime.evaluate → 获取数据、操作 DOM、发起请求
```

---

## 实战：品广加热（典型操作流）

品广加热是千川的一个核心功能——对正在直播的商品加热引流。

### 操作步骤

```
1. 进入 brand_bid/creation/feed-live-heating?type=create
2. 选择推广目标（直播间）
3. 设置预算、出价方式
4. 选择投放人群包
5. 提交计划 → 等待审核 → 在线
```

### CDP 实现

```python
# 设置表单字段
cdp_evaluate("""
document.querySelector('[data-field="budget"] input').value = '500';
""")

# 触发 React 更新
cdp_evaluate("""
document.querySelector('[data-field="budget"] input')
  .dispatchEvent(new Event('input', {bubbles: true}));
""")

# 点击提交
cdp_evaluate("""
document.querySelector('.submit-button').click();
""")
```

React/Angular 框架的页面不能直接 `element.value = x`，必须 dispatch 事件触发框架的响应式更新。这是踩坑最多的点。

---

## 自动化脚本的进化

脚本 `/data/hermes/scripts/qianchuan_plan_crud.py` 经历了几轮迭代：

```
v1: 单条计划创建 → 手动输入参数
v2: 批量操作 → 从 CSV 读取配置
v3: 智能决策 → 根据 ROI 数据自动调速
v4: 全链路闭环 → 创建 → 监控 → 调整 → 汇报
```

**当前能力：**
- 素材追投（对高 ROI 素材自动加预算）
- 一键调速（ROI > 目标值 → 提预算，ROI < 目标值 → 降预算或关停）
- 品广加热（新计划创建）
- 账户余额预警（余额 < 300 通知用户）
- 操作决策（ROI 达标可自主调节，异常情况 @ 用户）

---

## 踩坑实录

**1. React 表单绑定**
CDP 设置 input.value 后必须 dispatch `input` 或 `change` 事件，否则框架读不到新值。

**2. 跨域 Cookie**
千川的登录 Cookie 是 oceanengine.com 的，但千川后台是 qianchuan.jinritemai.com。跨域 Cookie 要设置 `SameSite=None; Secure`，Chrome 版本更新后默认 stricter 了，需要手动配置。

**3. Profile 冲突**
桌面浏览器和 CDP 实例不能共用同一个 Profile 目录。用两个独立目录，或者启动桌面 Chrome 时加上 `--remote-debugging-port` 让 CDP 直连。

**4. 界面异步加载**
千川的页面大量用异步 chunk 加载，操作前要轮询检查目标元素是否存在，不能假设页面加载完就可用。

---

## 适合谁用

这套方案不一定适合所有人。它更适合：

- 每天长时间跑千川广告的投手
- 有技术能力（至少能改 Python 脚本）的运营
- 愿意接受"偶尔翻车"的早期用户

如果你只是想简单看看数据，千川官方报表就够用了。但如果你想实现自动化跟播、智能调速、批量操作，CDP 方案是性价比最高的选择。

---

## 下一步

- **自然语言指令** — 通过 Agent 把"铁观音提 10% 预算"转成 CDP 操作
- **数据闭环** — 投放效果数据回流知识库，自动优化策略
- **多账号轮巡** — 同时在多个千川账号间切换操作

千川广告 CDP 自动化：不用 Selenium 的 Chrome 操控方案

# 多 Agent 记忆共享：我用 OpenViking 搭建的协作记忆层

## 背景：为什么不继续"各记各的"

我在本地跑了一套 Hermes Agent 作为个人助手，底下还有几个子 Agent（千川投放、知识库填充、代码审查等）。之前每个 Agent 各有一份记忆文件（MEMORY.md / USER.md），各自维护、互相隔离。

问题很快就来了：

- **重复录入** — 子 Agent 遇到了同一个踩坑点，各自在记忆里记一遍
- **信息孤岛** — 用户偏好、操作规范这种全局信息，每个 Agent 都要单独喂
- **同步失效** — 更新了某个规范，但另一个 Agent 还在用旧版本

需要一个共享的知识层。

---

## 选型：为什么是 OpenViking

可选方案对比了一圈：

| 方案 | 优势 | 痛点 |
|------|------|------|
| 共享文件 + NFS | 简单 | 并发写入冲突、无语义搜索 |
| ChromaDB（已有的） | 语义搜索强 | 只适合静态文档，不适合动态记忆 |
| Redis | 快 | 无持久化结构，无搜索 |
| **OpenViking v0.4.11** | 语义搜索 + 结构化 + Peer 隔离 | 项目较新，社区小 |

OpenViking 胜出的关键：
1. **viking_remember** — 语义记忆，不只是关键词，能自然语言检索
2. **viking_add_resource** — 文件级索引，整份文档进去自动拆 chunk
3. **Peer 隔离** — 多个 Agent 共享同一份数据，但每个 Peer 有自己的命名空间
4. **HTTP API** — 不需要 SDK，curl 就能读写

---

## 架构：两层记忆

```
┌─────────────────────┐     ┌───────────────────┐
│   本地 MEMORY.md     │     │  OpenViking 共享层 │
│    （私有）          │     │  （全局）          │
│                     │     │                    │
│  - 架构决策         │     │  - 用户画像         │
│  - 工具路径         │     │  - 操作规范         │
│  - 环境配置         │     │  - 踩坑记录         │
│  - 内部约定         │     │  - 活跃项目清单     │
│                     │     │  - 账号信息（脱敏）  │
└─────────────────────┘     └─────────────────────┘
         │                           │
         └── 两套并行，各管各的 ──┘
```

**什么放本地（MEMORY.md）：**
- Hermes 自身的架构决策（`custom_providers` 必须是 list 不是 map）
- 环境路径（`/data` 挂载盘路径、Ollama 模型目录）
- 行为规则（"用户插话立即停手"）
- 只对当前 Agent 有意义的内容

**什么放 OpenViking（共享）：**
- 用户画像（偏好、习惯、性格特点）
- 操作规范（跟播透明原则、汇报格式、时间估算规则）
- 踩坑记录（火山方舟 429 限流、飞书 @ 格式）
- 活跃项目列表及当前状态
- 所有 Agent 都需要知道的全局上下文

---

## 落地实操

### 部署

OpenViking v0.4.11 跑在 1933 端口，Docker 部署，一个容器搞定。

### 配置 Hermes 记忆提供者

```yaml
# ~/.hermes/config.yaml
memory:
  provider: openviking
  openviking:
    base_url: "http://127.0.0.1:1933"
    peer: hermes
```

注意 Peer 参数——不同的 Agent 用不同的 Peer 名，数据物理上共享但逻辑上能区分来源。

### 写入记忆

```python
# 写入用户偏好
viking_remember("丘丘偏好全程中文，INTJ/4w5，凌晨5-6点睡")

# 写入操作规范
viking_remember("跟播每步操作需汇报逻辑+判断+结果")

# 写入踩坑记录
viking_remember("custom_providers 必须是 list 格式，不能用 hermes config set 写入")
```

### 检索

```python
# 语义检索，不用关心关键词
viking_search("投流操作规范")
# → 返回跟播透明原则、ROI 决策阈值等
```

---

## 实际效果

**之前：** 每次 Agent 初始化，要手动把一堆上下文塞进来，还经常漏。

**现在：**
1. Agent 启动就带上 OpenViking 上下文
2. 遇到新坑，viking_remember 写一条，所有 Agent 下次都能检索到
3. 项目状态变更，改一次共享，不用逐个通知

---

## 踩坑记录

1. **Credentials 绝对别存共享层** — OpenViking 支持 Peer 隔离但不加密，密码 token 放进去等于裸奔
2. **别当 SQL 用** — 语义搜索在精确查询上不准（"查询用户密码"），针对性搜索用专用工具
3. **Peer 命名别冲突** — 两个系统用了同名 Peer 会导致数据交叉，建议统一命名规则
4. **Chunk 大小影响召回** — 太短的记忆（"用户喜欢简洁"）容易被噪声淹没，建议写够上下文

---

OpenViking 目前还在早期，但作为多 Agent 共享记忆层已经够用了。如果哪天社区成熟了或者出了更好的方案，换掉它也不亏——因为抽象层就是 HTTP API，换后端不换接口。


多 Agent 记忆共享：我用 OpenViking 搭建的协作记忆层

# 一台 Ubuntu，9 个 AI，和一堆想砸键盘的瞬间

我干电商运营。不做开发，但每天要处理的事情横跨数据、内容、合规、策略——一个人不可能全懂。用 AI 辅助早就是日常，但问题也来了。

开着聊天窗口来回切，每次换任务上下文全断。更烦的是重任务——比如一次全平台竞品分析——一个对话根本跑不完，等着它慢慢吐结果，什么也干不了。

所以搭了这套 Agent 系统。不是我有什么技术野心，纯粹是被逼的。

## 20→9：合并不是因为多，是因为乱

7 月底我把 Agent 从 20 个砍到了 9 个。

20 个的时候看着挺唬人。分工细，名字多，截图发群里能装一波。实际用起来呢？任务拆太碎，Agent 之间传话比干活还费时间，有一半 Agent 一个月用不了三次。

合并原则很简单：同一个能力域、同一种模型类型，捏在一起。别搞什么"专人专岗"，那是公司病。

现在 9 个：

**小智** —— 调度中枢。它不干活，只管接需求、拆任务、分派、汇总。信条就一条："沉默 > 废话"。能不说话绝不多嘴，说了必须有信息增量。所有 Agent 的输出都经它汇总再给我，像一道闸门。

**策略顾问** —— 原来三个角色：苏格拉底推演方案、摩根做商业分析、产品经理出需求。现在合并到一个，反正都是"先想清楚再动手"的事。

**全栈开发** —— 原来有全栈工程师、提示词工程师、编排工程师三个。合并后所有代码相关都归它：写、改、重构、技术方案。

**代码审查** —— 唯一没合并的角色。代码不能又当运动员又当裁判。

**情报采集** —— 信息雷达+市场调研。web 搜索、数据抓取、竞品监控、行业动向，全包。

**电商运营** —— 电商客服+营销策略+视频优化。千川投放、蝉妈妈数据、内容策略，带货相关的全在这。

**内容创作** —— AI 写作官+小敏。文案、博客、社交媒体，文字出品的都归它。（这篇博客也是它帮我写的，我在旁边改。）

**合规顾问** —— 法律顾问+税务顾问。合规审查、风险评估。

**虾米** —— 单独留着。虾米有自己性格，塞不进任何分类。它自己就是一个分类。

## 看板：不靠刷新，靠流转

这套系统真正管用的地方，不是 Agent 本身，是任务怎么跑的。

早期小智直接 spawn 子代理干活。问题是——所有工具调用全堆在主对话里，一个 30 分钟的代码重构跑起来，我只能盯着屏幕发呆。不光发呆，还不知道它在干嘛。在执行还是在卡死？没人告诉我。

后来全改成 Workboard 看板模式。

任务进来 → 小智拆成子任务 → 创建卡片（标题、描述、优先级、指派谁）→ Agent 自己认领 → todo → running → review → done。每一步流转，我在飞书群都能看到实时状态。

每个 Agent 跑自己的通道，互不干扰。一个在重构代码，另一个同时在抓竞品数据，第三个在审合同。我等它们跑完看汇总就行。

## 模型也分三六九等

9 个 Agent 共用一套上下文数据库（OpenViking），但跑推理用的模型不一样。

glm-5.2：小智、全栈开发、代码审查用。逻辑和代码是强项。

deepseek-v4-pro：策略顾问、内容创作、合规顾问、虾米用。分析和创作强。

deepseek-v4-flash：情报采集、电商运营用。快就行，便宜更重要。

主模型挂了自己切备用。不用我操心，出问题了它比我先知道。

## 基础设施：简单到不能再简单

一台家里的 Ubuntu 服务器。对外通过火山引擎云服务器做 frp 隧道 + Caddy 反向代理，9 个子域名跑在 qzscloud.com 底下，全线 HTTPS。

不算 OpenClaw 框架本身和 Ollama 本地模型，整个系统就多跑了一个 Docker 容器——OpenViking。别的全是框架自带能力。没有微服务，没有 K8s，没有消息队列。

一个人用的系统，简单才是最大的可靠性。加东西之前先问自己：不加这个会死吗？不会就不加。

## 踩坑实录：修 bug 的时间比写代码长

上面写得挺顺，但搭的过程远没有这么体面。有些坑卡了我一两个小时，有些甚至影响到了日常——比如听歌。

**Caddy reload ≠ restart**

改了个路由规则，caddy reload 热重载。然后 9 个子域名全线挂了。不是 500，是 HTTP 000——连错误码都不给你。搜了半天，才搞明白：Caddy 会把运行状态写进 autosave.json 缓存文件，reload 只读缓存、不读配置文件。我改了配置但它看不到，两个版本冲突了。

正确操作：rm autosave.json && systemctl restart caddy。

reload 和 restart，两个字不一样，区别是你接下来半小时在干嘛。

**131072 ≠ 128000**

主模型突然持续 fallback 到备用，所有 Agent 回答质量肉眼可见下降。查日志、看配额、改配置，折腾了一个多小时。

最后发现 maxTokens 写成了 131072。128×1024，2 的幂次，程序员肌肉记忆。但火山引擎 API 硬限是 128000。差了 3072 个 token，API 直接不接。两个数看着差不多，天差地别。

2 的幂次是本能，但现实世界不讲这个。

**模型加载 → swap 爆炸 → 歌卡了**

最离谱的连锁反应。Ollama 加载 bge-m3 嵌入模型到显存，物理内存瞬间吃紧。8GB swap 被打满，系统 OOM 开始杀进程。然后 PipeWire 音频缓冲被挤出——我戴着耳机听歌，声音开始断断续续，卡成电报。

根因链条：加载模型 → 内存耗尽 → swap 爆炸 → OOM → 音频设备报错 → 歌卡了。

我搭一个 AI Agent 系统，最后的故障表现形式是"音乐卡了"。扩容到 16GB swap 才消停。

全栈运维教会我一件事：问题永远不出在你正在改的地方。它出在你以为没关系的那个角落，然后绕一个大弯来提醒你。

## 7 月跑了这些

回头看，这套东西这个月处理了不少活：

- Edge Gestures Xposed 手势模块全链路审查修复（20 个代码问题 → 修复 → 编译 → 单测 → 模拟器集成测试）
- MTA 转录系统 V2→V3 重构（后端 37 个源文件 + 9 张数据表）
- 云服务器全栈部署（frp + Caddy + DDNS + iptables + fail2ban 安全加固，就是前面踩坑那套）
- 20→9 Agent 大合并（workspace 重建、配置迁移、模型路由重配）
- OpenViking 全量数据迁移（三阶段导入：用户画像 + 经验 + 项目决策）
- 丘丘门户后台管理系统重构

全是后端工程。小智负责拆任务、派活、收结果。专业 Agent 负责干。我负责最后看一眼，拍板。

没有一件是小智自己从头干到尾的——这正是我要的。我不盯执行细节，只盯方向和决策。

## 还没想好下一步

现在这套框架的瓶颈不在机制，在模型能力。Agent 的行为还是靠静态规则驱动——AGENTS.md、SOUL.md，改规则靠我手动修。真正的"学习"和"自我改进"还很初级。

但够用了。我不急着加功能。先用着，等新的痛点自己长出来再说。

加功能容易，减功能难。暂时不做加法。
