From c463cf9302634ef879f1c26533fdedc0086f1397 Mon Sep 17 00:00:00 2001 From: zytwd <1845371061@qq.com> Date: Sun, 22 Mar 2026 00:52:06 +0800 Subject: [PATCH] docs: Add Chinese README translations for OpenCode and OpenClaw plugins --- README_CN.md | 22 +- examples/openclaw-plugin/README_CN.md | 457 +++++++++++++++++++ examples/opencode-memory-plugin/README_CN.md | 196 ++++++++ examples/opencode/plugin/README_CN.md | 66 +++ 4 files changed, 730 insertions(+), 11 deletions(-) create mode 100644 examples/openclaw-plugin/README_CN.md create mode 100644 examples/opencode-memory-plugin/README_CN.md create mode 100644 examples/opencode/plugin/README_CN.md diff --git a/README_CN.md b/README_CN.md index 8814e0ef..a58691a8 100644 --- a/README_CN.md +++ b/README_CN.md @@ -534,7 +534,7 @@ ov chat 🚀 **在云端部署 OpenViking**： 为确保最佳的存储性能和数据安全，我们建议在 **火山引擎弹性计算服务 (ECS)** 上使用 **veLinux** 操作系统进行部署。我们准备了详细的分步指南，帮助您快速上手。 -👉 **[查看：服务器部署与 ECS 设置指南](./docs/en/getting-started/03-quickstart-server.md)** +👉 **[查看：服务器部署与 ECS 设置指南](./docs/zh/getting-started/03-quickstart-server.md)** ## OpenClaw 上下文插件详情 @@ -555,15 +555,15 @@ ov chat * 实验结论： 结合 OpenViking 后，若仍开启原生记忆，效果在原 OpenClaw 上提升 43%，输入 token 成本降低 91%；在 LanceDB 上效果提升 15%，输入 token 降低 96%。若关闭原生记忆，效果在原 OpenClaw 上提升 49%，输入 token 成本降低 83%；在 LanceDB 上效果提升 17%，输入 token 降低 92%。 -👉 **[查看：OpenClaw 上下文插件](examples/openclaw-plugin/README.md)** +👉 **[查看：OpenClaw 上下文插件](examples/openclaw-plugin/README_CN.md)** -👉 **[查看：OpenCode 记忆插件示例](examples/opencode-memory-plugin/README.md)** +👉 **[查看：OpenCode 记忆插件示例](examples/opencode-memory-plugin/README_CN.md)** ## VikingBot 部署详情 OpenViking 有一个类似 nanobot 的机器人用于交互工作，现已可用。 -👉 **[查看：使用 VikingBot 部署服务器](bot/README.md)** +👉 **[查看：使用 VikingBot 部署服务器](bot/README_CN.md)** -- @@ -575,7 +575,7 @@ OpenViking 有一个类似 nanobot 的机器人用于交互工作，现已可用 我们不再将上下文视为扁平的文本切片，而是将它们统一到一个抽象的虚拟文件系统中。无论是记忆、资源还是能力，都映射到 `viking://` 协议下的虚拟目录中，每个都有唯一的 URI。 -这种范式赋予智能体前所未有的上下文操作能力，使它们能够像开发者一样，通过 `ls` 和 `find` 等标准命令精确、确定地定位、浏览和操作信息。这将上下文管理从模糊的语义匹配转变为直观、可追踪的"文件操作"。了解更多：[Viking URI](./docs/en/concepts/04-viking-uri.md) | [上下文类型](./docs/en/concepts/02-context-types.md) +这种范式赋予智能体前所未有的上下文操作能力，使它们能够像开发者一样，通过 `ls` 和 `find` 等标准命令精确、确定地定位、浏览和操作信息。这将上下文管理从模糊的语义匹配转变为直观、可追踪的"文件操作"。了解更多：[Viking URI](./docs/zh/concepts/04-viking-uri.md) | [上下文类型](./docs/zh/concepts/02-context-types.md) ``` viking:// @@ -608,7 +608,7 @@ viking:// - **L1 (概览)**：包含核心信息和使用场景，用于智能体在规划阶段的决策。 - **L2 (详情)**：完整的原始数据，供智能体在绝对必要时深度阅读。 -了解更多：[上下文分层](./docs/en/concepts/03-context-layers.md) +了解更多：[上下文分层](./docs/zh/concepts/03-context-layers.md) ``` viking://resources/my_project/ @@ -637,13 +637,13 @@ viking://resources/my_project/ 4. **递归深入**：如果存在子目录，则逐层递归重复二次检索步骤。 5. **结果聚合**：最终获取最相关的上下文返回。 -这种"先锁定高分目录，再精细化内容探索"的策略不仅找到语义最佳匹配的片段，还能理解信息所在的完整上下文，从而提高检索的全局性和准确性。了解更多：[检索机制](./docs/en/concepts/07-retrieval.md) +这种"先锁定高分目录，再精细化内容探索"的策略不仅找到语义最佳匹配的片段，还能理解信息所在的完整上下文，从而提高检索的全局性和准确性。了解更多：[检索机制](./docs/zh/concepts/07-retrieval.md) ### 4. 可视化检索轨迹 → 可观察上下文 OpenViking 的组织采用分层虚拟文件系统结构。所有上下文以统一格式集成，每个条目对应一个唯一的 URI（如 `viking://` 路径），打破了传统的扁平黑盒管理模式，具有清晰易懂的层次结构。 -检索过程采用目录递归策略。每次检索的目录浏览和文件定位轨迹被完整保留，让用户能够清晰观察问题的根源，指导检索逻辑的优化。了解更多：[检索机制](./docs/en/concepts/07-retrieval.md) +检索过程采用目录递归策略。每次检索的目录浏览和文件定位轨迹被完整保留，让用户能够清晰观察问题的根源，指导检索逻辑的优化。了解更多：[检索机制](./docs/zh/concepts/07-retrieval.md) ### 5. 自动会话管理 → 上下文自迭代 @@ -652,7 +652,7 @@ OpenViking 内置了记忆自迭代循环。在每个会话结束时，开发者 - **用户记忆更新**：更新与用户偏好相关的记忆，使智能体响应更好地适应用户需求。 - **智能体经验积累**：从任务执行经验中提取操作技巧和工具使用经验等核心内容，辅助后续任务的高效决策。 -这使得智能体能够通过与世界的交互"越用越聪明"，实现自我进化。了解更多：[会话管理](./docs/en/concepts/08-session.md) +这使得智能体能够通过与世界的交互"越用越聪明"，实现自我进化。了解更多：[会话管理](./docs/zh/concepts/08-session.md) --- @@ -660,11 +660,11 @@ OpenViking 内置了记忆自迭代循环。在每个会话结束时，开发者 ### 文档 -更多详情，请访问我们的[完整文档](./docs/en/)。 +更多详情，请访问我们的[完整文档](./docs/zh/)。 ### 社区与团队 -更多详情，请参见：**[关于我们](./docs/en/about/01-about-us.md)** +更多详情，请参见：**[关于我们](./docs/zh/about/01-about-us.md)** ### 加入社区 diff --git a/examples/openclaw-plugin/README_CN.md b/examples/openclaw-plugin/README_CN.md new file mode 100644 index 00000000..731974d3 --- /dev/null +++ b/examples/openclaw-plugin/README_CN.md @@ -0,0 +1,457 @@ +# OpenClaw + OpenViking 上下文引擎插件 + +使用 [OpenViking](https://github.com/volcengine/OpenViking) 作为 [OpenClaw](https://github.com/openclaw/openclaw) 的长期记忆后端。在 OpenClaw 中，此插件注册为 `openviking` 上下文引擎。安装后，OpenClaw 将自动**记忆**对话中的重要信息，并在响应前**召回**相关上下文。 + +> **ℹ️ 历史兼容性说明** +> +> 传统的 OpenViking/OpenClaw 集成在 OpenClaw `2026.3.12` 附近存在一个已知问题，即对话可能在插件加载后挂起。 +> 该问题仅影响传统插件路径；本文档中描述的当前上下文引擎插件 2.0 不受此影响，因此新安装无需因此降级 OpenClaw。 +> 插件 2.0 也不向后兼容传统的 `memory-openviking` 插件及其配置，因此升级必须替换旧设置，而不是混合使用两个版本。 +> 插件 2.0 还依赖于 OpenClaw 的上下文引擎功能，不支持旧版 OpenClaw；使用此插件前请先升级 OpenClaw。 +> 如果您正在排查传统部署的问题，请参阅 [#591](https://github.com/volcengine/OpenViking/issues/591) 和上游修复 PR：openclaw/openclaw#34673、openclaw/openclaw#33547。 + +> **🚀 插件 2.0（上下文引擎架构）** +> +> 本文档涵盖当前基于上下文引擎架构的 OpenViking 插件 2.0，这是 AI 编码助手的推荐集成路径。 +> 有关设计背景和早期讨论，请参阅： +> https://github.com/volcengine/OpenViking/discussions/525 + +--- + +## 目录 + +- [一键安装](#一键安装) +- [手动设置](#手动设置) + - [前置要求](#前置要求) + - [本地模式（个人使用）](#本地模式个人使用) + - [远程模式（团队共享）](#远程模式团队共享) + - [火山引擎 ECS 部署](#火山引擎-ecs-部署) +- [启动与验证](#启动与验证) +- [配置参考](#配置参考) +- [日常使用](#日常使用) +- [Web 控制台（可视化）](#web-控制台可视化) +- [故障排除](#故障排除) +- [卸载](#卸载) + +--- + +## 一键安装 + +适用于想要快速获得本地体验的用户。安装助手会自动处理环境检测、依赖安装和配置文件生成。 + +### 方法 A：npm 安装（推荐，跨平台） + +```bash +npm install -g openclaw-openviking-setup-helper +ov-install +``` + +### 方法 B：curl 一键安装（Linux / macOS） + +```bash +curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/openclaw-plugin/install.sh | bash +``` + +安装助手将引导您完成： + +1. **环境检查** — 检测 Python >= 3.10、Node.js、cmake 等 +2. **选择 OpenClaw 实例** — 如果本地安装了多个实例，列出供您选择 +3. **选择部署模式** — 本地或远程（见下文） +4. **生成配置** — 自动写入 `~/.openviking/ov.conf` 和 `~/.openclaw/openviking.env` + +
+安装助手选项 + +``` +ov-install [options] + + -y, --yes 非交互式，使用默认值 + --workdir OpenClaw 配置目录（默认：~/.openclaw） + -h, --help 显示帮助 + +环境变量： + OPENVIKING_PYTHON Python 路径 + OPENVIKING_CONFIG_FILE ov.conf 路径 + OPENVIKING_REPO 本地 OpenViking 仓库路径 + OPENVIKING_ARK_API_KEY 火山引擎 API Key（-y 模式下跳过提示） +``` + +
+ +--- + +## 手动设置 + +### 前置要求 + +| 组件 | 版本 | 用途 | +|-----------|---------|---------| +| **Python** | >= 3.10 | OpenViking 运行时（本地模式） | +| **Node.js** | >= 22 | OpenClaw 运行时 | +| **火山引擎 Ark API Key** | — | Embedding + VLM 模型调用 | + +```bash +python3 --version # >= 3.10 +node -v # >= v22 +openclaw --version # 已安装 +``` + +- Python: https://www.python.org/downloads/ +- Node.js: https://nodejs.org/ +- OpenClaw: `npm install -g openclaw && openclaw onboard` + +--- + +### 本地模式个人使用 + +最简单的选项 — 几乎无需配置。记忆服务与您的OpenClaw一起在本地运行。您只需要一个火山引擎Ark API Key。 + +#### 步骤 1：安装 OpenViking + +```bash +python3 -m pip install openviking --upgrade +``` + +验证：`python3 -c "import openviking; print('ok')"` + +> 遇到 `externally-managed-environment`？使用一键安装程序（自动处理 venv）或手动创建一个： +> ```bash +> python3 -m venv ~/.openviking/venv && ~/.openviking/venv/bin/pip install openviking +> ``` + +#### 步骤 2：运行安装助手 + +```bash +# 方法 A：npm 安装（推荐，跨平台） +npm install -g openclaw-openviking-setup-helper +ov-install + +# 方法 B：curl 一键安装（Linux / macOS） +curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/openclaw-plugin/install.sh | bash +``` + +选择 **本地** 模式，保持默认设置，并输入您的 Ark API Key。 + +生成的配置文件： +- `~/.openviking/ov.conf` — OpenViking 服务配置 +- `~/.openclaw/openviking.env` — 环境变量（Python 路径等） + +#### 步骤 3：启动 + +```bash +source ~/.openclaw/openviking.env && openclaw gateway restart +``` + +> 在本地模式下，您必须先 `source` 环境文件 — 插件会自动启动一个 OpenViking子进程。 + +#### 步骤 4：验证 + +```bash +openclaw status +# ContextEngine 行应显示：enabled (plugin openviking) +``` + +--- + +### 远程模式团队共享 + +适用于多个OpenClaw实例或团队使用。部署一个独立的OpenViking服务，供多个agents共享。**客户端无需 Python/OpenViking。** + +#### 步骤 1：部署 OpenViking 服务 + +编辑 `~/.openviking/ov.conf` — 设置 `root_api_key` 以启用多租户： + +```json +{ + "server": { + "host": "127.0.0.1", + "port": 1933, + "root_api_key": "", + "cors_origins": ["*"] + }, + "storage": { + "workspace": "~/.openviking/data", + "vectordb": { + "name": "context", + "backend": "local" + }, + "agfs": { + "log_level": "warn", + "backend": "local" + } + }, + "embedding": { + "dense": { + "provider": "volcengine", + "api_key": "", + "model": "doubao-embedding-vision-251215", + "api_base": "https://ark.cn-beijing.volces.com/api/v3", + "dimension": 1024, + "input": "multimodal" + } + }, + "vlm": { + "provider": "volcengine", + "api_key": "", + "model": "doubao-seed-2-0-pro-260215", + "api_base": "https://ark.cn-beijing.volces.com/api/v3", + "temperature": 0.1, + "max_retries": 3 + } +} +``` + +启动服务： + +```bash +openviking-server +``` + +#### 步骤 2：创建团队和用户 + +```bash +# 创建团队 + 管理员 +curl -X POST http://localhost:1933/api/v1/admin/accounts \ + -H "Content-Type: application/json" \ + -H "X-API-Key: " \ + -d '{ + "account_id": "my-team", + "admin_user_id": "admin" + }' + +# 添加成员 +curl -X POST http://localhost:1933/api/v1/admin/accounts/my-team/users \ + -H "Content-Type: application/json" \ + -H "X-API-Key: " \ + -d '{ + "user_id": "xiaomei", + "role": "user" + }' +``` + +#### 步骤 3：配置 OpenClaw 插件 + +```bash +openclaw plugins enable openviking +openclaw config set gateway.mode local +openclaw config set plugins.slots.contextEngine openviking +openclaw config set plugins.entries.openviking.config.mode remote +openclaw config set plugins.entries.openviking.config.baseUrl "http://your-server:1933" +openclaw config set plugins.entries.openviking.config.apiKey "" +openclaw config set plugins.entries.openviking.config.agentId "" +openclaw config set plugins.entries.openviking.config.autoRecall true --json +openclaw config set plugins.entries.openviking.config.autoCapture true --json +``` + +#### 步骤 4：启动与验证 + +```bash +# 远程模式 — 无需 source 环境文件 +openclaw gateway restart +openclaw status +``` + +--- + +### 火山引擎 ECS 部署 + +在火山引擎 ECS 上部署 OpenClaw + OpenViking。详见 [火山引擎文档](https://www.volcengine.com/docs/6396/2249500?lang=zh)。 + +> ECS 实例限制在 root 下全局 pip 安装以保护系统 Python。请先创建 venv。 + +```bash +# 1. 安装 +npm install -g openclaw-openviking-setup-helper +ov-install + +# 2. 加载环境 +source /root/.openclaw/openviking.env + +# 3. 启动 OpenViking 服务器 +python -m openviking.server.bootstrap + +# 4. 启动 Web 控制台（确保入站安全组允许 TCP 8020） +python -m openviking.console.bootstrap --host 0.0.0.0 --port 8020 --openviking-url http://127.0.0.1:1933 +``` + +访问 `http://:8020` 使用 Web 控制台。 + +--- + +## 启动与验证 + +### 本地模式 + +```bash +source ~/.openclaw/openviking.env && openclaw gateway restart +``` + +### 远程模式 + +```bash +openclaw gateway restart +``` + +### 检查插件状态 + +```bash +openclaw status +# ContextEngine 行应显示：enabled (plugin openviking) +``` + +### 查看插件配置 + +```bash +openclaw config get plugins.entries.openviking.config +``` + +--- + +## 配置参考 + +### `~/.openviking/ov.conf`（本地模式） + +```json +{ + "root_api_key": null, + "server": { "host": "127.0.0.1", "port": 1933 }, + "storage": { + "workspace": "~/.openviking/data", + "vectordb": { "backend": "local" }, + "agfs": { "backend": "local", "port": 1833 } + }, + "embedding": { + "dense": { + "provider": "volcengine", + "api_key": "", + "model": "doubao-embedding-vision-251215", + "api_base": "https://ark.cn-beijing.volces.com/api/v3", + "dimension": 1024, + "input": "multimodal" + } + }, + "vlm": { + "provider": "volcengine", + "api_key": "", + "model": "doubao-seed-2-0-pro-260215", + "api_base": "https://ark.cn-beijing.volces.com/api/v3" + } +} +``` + +> `root_api_key`：设置后，所有 HTTP 请求必须包含 `X-API-Key` 头。本地模式下默认为 `null`（禁用身份验证）。 + +### 插件配置选项 + +| 选项 | 默认值 | 描述 | +|--------|---------|-------------| +| `mode` | `remote` | `local`（启动本地服务器）或 `remote`（连接远程服务器） | +| `baseUrl` | `http://127.0.0.1:1933` | OpenViking 服务器 URL（远程模式） | +| `apiKey` | — | OpenViking API Key（可选） | +| `agentId` | 自动生成 | agent标识符，用于区分 OpenClaw 实例。如果未设置则自动生成 `openclaw--` | +| `configPath` | `~/.openviking/ov.conf` | 配置文件路径（本地模式） | +| `port` | `1933` | 本地服务器端口（本地模式） | +| `targetUri` | `viking://user/memories` | 默认记忆搜索范围 | +| `autoCapture` | `true` | 对话后自动提取记忆 | +| `captureMode` | `semantic` | 提取模式：`semantic`（完整语义）/ `keyword`（仅触发词） | +| `captureMaxLength` | `24000` | 每次提取的最大文本长度 | +| `autoRecall` | `true` | 对话前自动召回相关记忆 | +| `recallLimit` | `6` | 自动召回期间注入的最大记忆数 | +| `recallScoreThreshold` | `0.01` | 召回的最低相关性分数 | +| `ingestReplyAssist` | `true` | 检测到多方对话文本时添加回复指导 | + +### `~/.openclaw/openviking.env` + +由安装助手自动生成，存储环境变量（如 Python 路径）： + +```bash +export OPENVIKING_PYTHON='/usr/local/bin/python3' +``` + +--- + +## 日常使用 + +```bash +# 启动（本地模式 — 先 source 环境文件） +source ~/.openclaw/openviking.env && openclaw gateway + +# 启动（远程模式 — 无需环境文件） +openclaw gateway + +# 禁用上下文引擎 +openclaw config set plugins.slots.contextEngine legacy + +# 重新启用 OpenViking 作为上下文引擎 +openclaw config set plugins.slots.contextEngine openviking +``` + +> 更改上下文引擎插槽后请重启网关。 + +--- + +## Web-控制台可视化 + +OpenViking 提供 Web 控制台用于调试和检查存储的记忆。 + +```bash +python -m openviking.console.bootstrap \ + --host 127.0.0.1 \ + --port 8020 \ + --openviking-url http://127.0.0.1:1933 \ + --write-enabled +``` + +在浏览器中打开 http://127.0.0.1:8020。 + +--- + +## 故障排除 + +### 常见问题 + +| 症状 | 原因 | 解决方案 | +|---------|-------|-----| +| 对话挂起，无响应 | 通常是受历史 OpenClaw `2026.3.12` 问题影响的 2.0 之前传统集成 | 如果您使用传统路径，请参阅 [#591](https://github.com/volcengine/OpenViking/issues/591) 并临时降级到 `2026.3.11`；对于当前安装，请迁移到插件 2.0 | +| 日志中出现 `registerContextEngine is unavailable` | OpenClaw 版本过旧，未暴露插件 2.0 所需的上下文引擎 API | 升级 OpenClaw 到当前版本，然后重启网关并验证 `openclaw status` 显示 `openviking` 作为 ContextEngine | +| agent静默挂起，无输出 | 自动召回缺少超时保护 | 临时禁用自动召回：`openclaw config set plugins.entries.openviking.config.autoRecall false --json`，或应用 [#673](https://github.com/volcengine/OpenViking/issues/673) 中的补丁 | +| ContextEngine 不是 `openviking` | 插件插槽未配置 | `openclaw config set plugins.slots.contextEngine openviking` | +| `memory_store failed: fetch failed` | OpenViking 未运行 | 检查 `ov.conf` 和 Python 路径；验证服务是否运行 | +| `health check timeout` | 端口被陈旧进程占用 | `lsof -ti tcp:1933 \| xargs kill -9`，然后重启 | +| `extracted 0 memories` | API Key 或模型名称错误 | 检查 `ov.conf` 中的 `api_key` 和 `model` | +| `port occupied` | 端口被其他进程占用 | 更改端口：`openclaw config set plugins.entries.openviking.config.port 1934` | +| 插件未加载 | 环境文件未 source | 启动前运行 `source ~/.openclaw/openviking.env` | +| `externally-managed-environment` | Python PEP 668 限制 | 使用 venv 或一键安装程序 | +| `TypeError: unsupported operand type(s) for \|` | Python < 3.10 | 升级 Python 到 3.10+ | + +### 查看日志 + +```bash +# OpenViking 日志 +cat ~/.openviking/data/log/openviking.log + +# OpenClaw 网关日志 +cat ~/.openclaw/logs/gateway.log +cat ~/.openclaw/logs/gateway.err.log + +# 检查 OpenViking 进程是否存活 +lsof -i:1933 + +# 快速连接检查 +curl http://localhost:1933 +# 预期：{"detail":"Not Found"} +``` + +--- + +## 卸载 + +```bash +lsof -ti tcp:1933 tcp:1833 tcp:18789 | xargs kill -9 +npm uninstall -g openclaw && rm -rf ~/.openclaw +python3 -m pip uninstall openviking -y && rm -rf ~/.openviking +``` + +--- + +**另见：** [INSTALL-ZH.md](./INSTALL-ZH.md)（中文详细安装指南）· [INSTALL.md](./INSTALL.md)（英文安装指南）· [INSTALL-AGENT.md](./INSTALL-AGENT.md)（Agent 安装指南） diff --git a/examples/opencode-memory-plugin/README_CN.md b/examples/opencode-memory-plugin/README_CN.md new file mode 100644 index 00000000..957ebe61 --- /dev/null +++ b/examples/opencode-memory-plugin/README_CN.md @@ -0,0 +1,196 @@ +# OpenCode 的 OpenViking 记忆插件 + +OpenCode 插件示例，将 OpenViking 记忆作为显式工具暴露，并自动同步对话会话到 OpenViking。 + +安装指南：[INSTALL-ZH.md](./INSTALL-ZH.md) + +## 机制 + +本示例使用 OpenCode 的工具机制将 OpenViking 功能暴露为agent可调用的显式工具。 + +实际上，这意味着： + +- agent可以看到具体的工具并决定何时调用它们 +- OpenViking 数据通过工具执行按需获取，而不是预先注入到每个提示中 +- 插件还保持 OpenViking 会话与 OpenCode 对话同步，并使用 `memcommit` 触发后台记忆提取 + +本示例专注于 OpenCode 中的显式记忆访问、文件系统风格的浏览和会话到记忆的同步。 + +## 功能 + +- 为 OpenCode agent暴露四个记忆工具： + - `memsearch` + - `memread` + - `membrowse` + - `memcommit` +- 自动将每个 OpenCode 会话映射到 OpenViking 会话 +- 将用户和助手消息流式传输到 OpenViking +- 使用后台 `commit` 任务避免重复的同步导致超时失败 +- 持久化本地运行时状态以支持重新连接和恢复 + +## 文件 + +本示例包含： + +- `openviking-memory.ts`：OpenCode 使用的插件实现 +- `openviking-config.example.json`：配置模板 +- `.gitignore`：复制到工作区后忽略本地运行时文件 + +## 前置要求 + +- OpenCode +- OpenViking HTTP 服务器 +- 如果您的服务器需要身份验证，则需要有效的 OpenViking API 密钥 + +如果服务器尚未运行，请先启动： + +```bash +openviking-server --config ~/.openviking/ov.conf +``` + +## 安装到 OpenCode + +OpenCode 文档推荐的安装位置： + +```bash +~/.config/opencode/plugins +``` + +使用以下命令安装： + +```bash +mkdir -p ~/.config/opencode/plugins +cp examples/opencode-memory-plugin/openviking-memory.ts ~/.config/opencode/plugins/openviking-memory.ts +cp examples/opencode-memory-plugin/openviking-config.example.json ~/.config/opencode/plugins/openviking-config.json +cp examples/opencode-memory-plugin/.gitignore ~/.config/opencode/plugins/.gitignore +``` + +然后编辑 `~/.config/opencode/plugins/openviking-config.json`。 + +OpenCode 会自动发现 `~/.config/opencode/plugins` 下一级目录中的 `*.ts` 和 `*.js` 文件，因此不需要在 `~/.config/opencode/opencode.json` 中显式配置 `plugin` 条目。 + +如果您有意将插件放置在工作区本地插件目录中，此插件也可以使用，因为它会将配置和运行时文件存储在插件文件旁边。 + +推荐：通过环境变量提供 API 密钥，而不是将其写入配置文件： + +```bash +export OPENVIKING_API_KEY="your-api-key-here" +``` + +## 配置 + +配置示例： + +```json +{ + "endpoint": "http://localhost:1933", + "apiKey": "", + "enabled": true, + "timeoutMs": 30000, + "autoCommit": { + "enabled": true, + "intervalMinutes": 10 + } +} +``` + +环境变量 `OPENVIKING_API_KEY` 优先于配置文件。 + +## 运行时文件 + +安装后，插件会在插件文件旁边创建这些本地文件： + +- `openviking-config.json` +- `openviking-memory.log` +- `openviking-session-map.json` + +这些是运行时生成的文件，不应提交到版本控制。 + +## 工具 + +### `memsearch` + +在记忆、资源和技能中进行统一搜索。 + +参数： + +- `query`：搜索查询 +- `target_uri?`：将搜索限制在 URI 前缀，如 `viking://user/memories/` +- `mode?`：`auto | fast | deep` +- `limit?`：最大结果数 +- `score_threshold?`：可选的最小分数 + +### `memread` + +从特定的 `viking://` URI 读取内容。 + +参数： + +- `uri`：目标 URI +- `level?`：`auto | abstract | overview | read` + +### `membrowse` + +浏览 OpenViking 文件系统布局。 + +参数： + +- `uri`：目标 URI +- `view?`：`list | tree | stat` +- `recursive?`：仅用于 `view: "list"` +- `simple?`：仅用于 `view: "list"` + +### `memcommit` + +触发当前会话的立即记忆提取。 + +参数： + +- `session_id?`：可选的显式 OpenViking 会话 ID + +返回后台任务进度或完成详情，包括 `task_id`、`memories_extracted` 和 `archived`。 + +## 使用示例 + +搜索然后读取： + +```typescript +const results = await memsearch({ + query: "user coding preferences", + target_uri: "viking://user/memories/", + mode: "auto" +}) + +const content = await memread({ + uri: results[0].uri, + level: "auto" +}) +``` + +先浏览： + +```typescript +const tree = await membrowse({ + uri: "viking://resources/", + view: "tree" +}) +``` + +强制进行会话中期提交： + +```typescript +const result = await memcommit({}) +``` + +## 审查者说明 + +- 插件设计为作为 OpenCode 插件目录中的一级 `*.ts` 文件运行 +- 有意将运行时配置、日志和会话映射保留在仓库示例之外 +- 使用 OpenViking 后台提交任务来避免长时间记忆提取期间的重复超时/重试循环 + +## 故障排除 + +- 插件未加载：确认文件存在于 `~/.config/opencode/plugins/openviking-memory.ts` +- 服务不可用：确认 `openviking-server` 正在运行并且在配置的端点可访问 +- 身份验证失败：检查 `OPENVIKING_API_KEY` 或 `openviking-config.json` +- 未提取记忆：检查您的 OpenViking 服务器是否有正常工作的 `vlm` 和 `embedding` 配置 diff --git a/examples/opencode/plugin/README_CN.md b/examples/opencode/plugin/README_CN.md new file mode 100644 index 00000000..db0d1a42 --- /dev/null +++ b/examples/opencode/plugin/README_CN.md @@ -0,0 +1,66 @@ +# openviking-opencode + +用于 [OpenCode](https://opencode.ai) 的 OpenViking 插件。将您索引的代码仓库注入到 AI 的上下文中，并在需要时自动启动 OpenViking 服务器。 + +## 前置要求 + +安装最新版的 OpenViking 并配置 `~/.openviking/ov.conf`： + +```bash +pip install openviking --upgrade +``` + +```json +{ + "storage": { + "workspace": "/path/to/your/workspace" + }, + "embedding": { + "dense": { + "provider": "openai", + "model": "your-embedding-model", + "api_key": "your-api-key", + "api_base": "https://your-provider/v1", + "dimension": 1024 + }, + "max_concurrent": 100 + }, + "vlm": { + "provider": "openai", + "model": "your-vlm-model", + "api_key": "your-api-key", + "api_base": "https://your-provider/v1" + } +} +``` + +对于其他提供商（火山引擎、Anthropic、DeepSeek、Ollama 等），请参阅 [OpenViking 文档](https://www.openviking.ai/docs)。 + +启动 OpenCode 之前，请确保 OpenViking 服务器正在运行。如果尚未启动： + +```bash +openviking-server > /tmp/openviking.log 2>&1 & +``` + +## 在 OpenCode 中使用 + +将插件添加到 `~/.config/opencode/opencode.json`： + +```json +{ + "plugin": ["openviking-opencode"] +} +``` + +重启 OpenCode — 技能会自动安装。 + +**索引仓库**（直接在聊天中询问）： +``` +"将 https://github.com/tiangolo/fastapi 添加到 OpenViking" +``` + +**搜索** — 仓库索引完成后，AI 会在相关时自动搜索它们。您也可以显式触发： +``` +"FastAPI 如何处理依赖注入？" +"使用 openviking 查找 JWT 令牌如何验证" +```