OpenViking Pi Agent 扩展

English version: README.en.md

这是面向 pi-coding-agent 的 OpenViking 扩展示例，参考并复刻了 OpenViking examples/opencode-plugin 的主要能力。扩展通过 Pi extension API 注册工具、注入上下文、同步会话，并用 HTTP API 与 OpenViking 服务通信。

功能概览

• 在每轮 agent 启动前读取 viking://resources/，把已索引仓库列表注入 system prompt。
• 自动召回相关长期记忆，并追加到最新用户消息的 <relevant-memories> 块中。
• 将 Pi session 映射到 OpenViking session，并同步 user/assistant 文本消息。
• 支持手动 memcommit 和定时后台 commit，用于 OpenViking 记忆抽取。
• 注册 OpenViking 工具：memsearch、memfind、memread、membrowse、memcommit、memgrep、memglob、memadd、meadd、memremove、memqueue。
• memadd 支持远程 URL 与本地文件。本地文件会先上传到 POST /api/v1/resources/temp_upload，再通过 POST /api/v1/resources 添加。

文件结构

examples/extensions/openviking/
├── index.ts
├── README.md
└── lib/
    ├── config.ts
    ├── http.ts
    ├── memadd-local.ts
    ├── memory-recall.ts
    ├── repo-context.ts
    ├── runtime.ts
    ├── session-sync.ts
    └── tools.ts

配置

扩展会按顺序查找配置文件：

1. OPENVIKING_PLUGIN_CONFIG 指向的路径
2. 当前项目 .pi/openviking-config.json
3. ~/.pi/agent/openviking-config.json
4. 扩展目录内 openviking-config.json

示例：

{
  "endpoint": "http://localhost:1933",
  "apiKey": "",
  "account": "",
  "user": "",
  "agentId": "",
  "enabled": true,
  "timeoutMs": 30000,
  "runtime": {
    "autoStartServer": false,
    "dataDir": ""
  },
  "repoContext": {
    "enabled": true,
    "cacheTtlMs": 60000
  },
  "autoCommit": {
    "enabled": true,
    "intervalMinutes": 10
  },
  "autoRecall": {
    "enabled": true,
    "limit": 6,
    "scoreThreshold": 0.15,
    "maxContentChars": 500,
    "preferAbstract": true,
    "tokenBudget": 2000
  }
}

OPENVIKING_API_KEY、OPENVIKING_ACCOUNT、OPENVIKING_USER、OPENVIKING_AGENT_ID 会覆盖配置文件中的同名认证信息。

默认运行时数据目录是 ~/.pi/agent/openviking/，会保存：

• openviking-memory.log
• openviking-session-map.json
• openviking-server.log，仅在 runtime.autoStartServer=true 时产生

启用方式

先启动 OpenViking 服务：

openviking-server --config ~/.openviking/ov.conf

如果已发布到 npm，普通用户推荐通过 Pi package 机制安装：

pi install npm:@tanyouqing/pi-openviking

临时试用可以用：

pi -e npm:@tanyouqing/pi-openviking

普通用户不需要直接运行 npm install @tanyouqing/pi-openviking。直接 npm install 只会把包安装到当前 Node 项目，不会自动写入 Pi 的 package 设置，也不会让 Pi 自动加载扩展。

开发时可以直接用绝对路径加载：

pi --extension ~\your_directory\openviking\index.ts

也可以复制整个 openviking/ 目录到用户扩展目录：

mkdir "%USERPROFILE%\.pi\agent\extensions\openviking"
xcopy /E /I download_dir\openviking "%USERPROFILE%\.pi\agent\extensions\openviking"
pi

工具说明

工具	用途
memsearch	语义搜索 memories/resources/skills。默认会在复杂问题或当前会话已映射时使用 OpenViking deep search。
memfind	快速语义搜索，固定走 /api/v1/search/find。
memread	读取一个 viking:// URI，支持 auto、abstract、overview、read。
membrowse	用 list、tree、stat 浏览 OpenViking 文件系统。
memcommit	提交当前 Pi 会话到 OpenViking 并触发记忆抽取。
memgrep	搜索精确符号、类名、函数名、错误字符串或已知关键词。
memglob	通过 glob 枚举文件，例如 **/*.ts、**/README.md。
memadd	添加远程 URL 或本地文件到 viking://resources/。
meadd	memadd 的兼容别名。
memremove	删除 viking:// 资源，必须传 confirm: true。
memqueue	查看 observer queue 状态。

常用操作

添加远程文档：

memadd path="https://example.com/spec.md" to="viking://resources/spec.md"

添加本地文件：

memadd path="./docs/notes.md" parent="viking://resources/" reason="project notes"

按符号查代码：

memgrep pattern="createMemorySessionManager" uri="viking://resources/pi-agent/"

按文件名枚举：

memglob pattern="**/*.ts" uri="viking://resources/OpenViking/"

手动抽取本轮会话记忆：

memcommit

实现备注

• index.ts 绑定 Pi 生命周期：session_start、session_tree、before_agent_start、context、message_end、session_shutdown。
• repo-context.ts 负责仓库列表缓存与 system prompt 片段。
• memory-recall.ts 负责自动召回、排序、去重和注入。
• session-sync.ts 负责 Pi session 到 OpenViking session 的映射、消息同步、后台 commit 和持久化。
• tools.ts 负责注册中间层工具，并把 Pi tool 参数转换成 OpenViking HTTP 请求。
• memadd-local.ts 负责本地文件解析、临时上传和资源添加流程。