Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
docs: Add Chinese README translations for OpenCode and OpenClaw plugins (#850)
SCPZ24f09060c64f97
diff --git a/README_CN.md b/README_CN.mdindex 8814e0ef9..a58691a85 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.mdnew file mode 100644index 000000000..731974d36--- /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`++<details>+<summary>安装助手选项</summary>++```+ov-install [options]++ -y, --yes 非交互式,使用默认值+ --workdir <path> OpenClaw 配置目录(默认:~/.openclaw)+ -h, --help 显示帮助++环境变量:+ OPENVIKING_PYTHON Python 路径+ OPENVIKING_CONFIG_FILE ov.conf 路径+ OPENVIKING_REPO 本地 OpenViking 仓库路径+ OPENVIKING_ARK_API_KEY 火山引擎 API Key(-y 模式下跳过提示)+```++</details>++---++## 手动设置++### 前置要求++| 组件 | 版本 | 用途 |+|-----------|---------|---------|+| **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": "<your-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": "<your-ark-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": "<your-ark-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: <root-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: <root-or-admin-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 "<user-api-key>"+openclaw config set plugins.entries.openviking.config.agentId "<agent-id>"+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://<public-ip>: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": "<your-ark-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": "<your-ark-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-<hostname>-<random>` |+| `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.mdnew file mode 100644index 000000000..957ebe611--- /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.mdnew file mode 100644index 000000000..db0d1a42c--- /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 令牌如何验证"+```