@difyz/pi-wecom-knowledge0.1.2

Independent Pi knowledge extension with per-user library access, model allowlists, bounded retrieval, and validated citations.

difyz Published 18 hours ago MIT ~183 downloads/mo

Untested on omp

This is a pi package. No one has reported whether it works on omp yet. If you try it, add your result below.

Reports 0

No reports yet.

Readme

@difyz/pi-wecom-knowledge

可独立安装的 Pi 知识扩展，内部保留通道无关的知识应用库。通过能力协议 v1 向可信通道提供只读问答，不依赖企业微信包或其安装路径。

Optional knowledge Q&A extension for Pi: user/library authorization, model allowlists, bounded retrieval, citation validation, and independent worker lifecycle.

安装和配置

Node >=22.19、Pi 1.4.0；需要维护者已公开发布支持双扩展架构的版本：

pi install npm:@difyz/pi-wecom-knowledge

企业微信用户另装 pi install npm:@difyz/pi-wecom，重启 Pi，两者可在不同安装目录。普通聊天不需要本包。不自动建库、不继承个人默认知识目录。引擎包含 better-sqlite3 原生绑定，安装需预编译支持或本机编译环境。

合并到用户级 ~/.pi/agent/settings.json：

{
  "knowledge": { "policy": "/absolute/private/knowledge-policy.json" },
  "wecom": {
    "botId": "你的 BotID",
    "secret": "你的 Secret",
    "allowedUsers": ["实际userid"],
    "knowledge": { "enabled": true }
  }
}

顶层 knowledge 只接受 policy 绝对路径；wecom 节点不由本扩展解析。旧 wecom.knowledgePolicy 必须迁移。配置在初始化/重启读取，不自动写回。不读取项目级配置，密钥/策略和备份应仅限本人访问。

独立管理

/knowledge doctor
/knowledge status
/knowledge stop
/knowledge restart

加载扩展时不打开数据库；通道首次连接时懒初始化，或由 restart 显式启动。doctor 在引擎停止时用临时 worker 校验并释放，已运行时只报告状态，防止第二引擎锁冲突。stop/restart 会取消所有知识租约的活动/排队任务，不断开通道、不重置普通历史、不重放问题。普通通道关闭只释放自身租约，不关闭共享服务。

诊断与初始化/停止/重启共用生命周期队列，不并发开启第二个 worker。管理员停止后不会由新租约自动唤醒。Pi 切换会话同样会停止知识服务；新会话先 /knowledge restart，再启动通道。

首次策略不可读、缺失扩展或接口不兼容时，通道无法确定自动问答意图，应拒绝潜在自动问题，不把问题默默发给普通模型。策略已确认 autoAnswer 为 false 时，知识维护不影响普通聊天；为 true 时知识普通文本始终拒绝回退。

worker 取消活动检索可能影响其他租约的知识调用，故障状态明确为 unavailable，不自动重试。修复后 /knowledge restart。

策略示例

管理员预先创建独立知识目录，取得精确 KB ID 和 ready 状态，填写策略：

{
  "schemaVersion": 1,
  "knowledgeDir": "/absolute/private/knowledge-store",
  "searchMode": "fast",
  "autoAnswer": false,
  "defaultLibrary": "hr",
  "users": { "实际userid": ["hr"] },
  "libraries": {
    "hr": {
      "id": "精确KB-ID",
      "title": "人事制度",
      "contentVersion": "v1",
      "allowedModels": ["approved-provider/model"]
    }
  }
}

knowledgeDir 必须含现有 knowledge.db；不自动使用个人资料。users 为精确用户→别名授权；回答模型必须在 allowedModels 中，仍须通过通道用户白名单。title 是可公开库名，不能含路径、链接或控制字符。defaultLibrary 可省略：自动问答仅在恰好一个授权库时选用，多库不能依赖 JSON 顺序；指定默认库仍须授权。

searchMode 支持 fast（默认 BM25，不加载 embedding）、hybrid、semantic。后两者仅使用知识目录 models 缓存中的 multilingual-e5-small，离线不下载，须提前准备缓存和验证索引/质量。自动化真实引擎测试验证 fast，不代表语义模式验收。

autoAnswer 默认 false；开启时单聊普通文本也进入知识检索。/kb list 只列当前用户及模型可访问库；/kb ask <问题> 显式查询。群聊始终拒绝，不列目录或检索，不开放远端导入/删除/导出。

问题最多 4096 字节，检索最多 5 片段、每段 3000 字节、共 12000 字节；排队与执行总计 15 秒，队列最多 16。检索结果反查精确库归属，无命中不调用模型，错误不降级普通聊天。

每题全新隔离回答会话，回答只使用所给证据；不发送原始模型增量，引用编号验证后再输出，来源由真实证据生成。校验不保证语义正确。获准片段会发送到宿主传入的回答模型供应商，allowedModels 是外发边界，不是重复模型配置。

集成协议和库 API

Pi 事件 difyz:knowledge:discover 接收 { respond(provider) }；提供者同步响应：

version: 1、只读 status。
connect(answerBackend, invalidate) 异步返回每通道租约。
租约含 status、route(context)、close()，与现有通道能力契约结构兼容。
invalidate 在服务切换代次时调用，宿主必须取消并丢弃本通道知识队列。
任务还绑定租约和服务代次的 AbortSignal；旧任务闭包不可重放。

通道传入已验证 userId、chatType、model、scope 和回复预算；不得信任客户端自报身份。回答后端须隔离工具和上下文。事件总线不是沙箱，同宿主扩展均需可信；接口通过版本兼容，不依赖两包同版本或 npm 模块解析。

仍保留 ESM 库 API，直接使用时不加载 Pi 扩展入口：

import { configure } from "@difyz/pi-wecom-knowledge";
const configured = configure("/absolute/private/policy.json", answerBackend);
const application = await configured.start();
try {
  const route = application.route({
    userId: verifiedUserId,
    scope: verifiedChannelAndBotScope,
    chatType: "single",
    text: "/kb ask hr 年假规则",
    model: "approved-provider/model",
    maxReplyBytes: 20480
  });
  if (route?.type === "task") {
    const answer = await route.run(freshPrivateDirectory, abortSignal);
  }
} finally {
  await application.close();
}

数据维护

锁定 pi-knowledge 0.12.0；“只读”指远端能力，初始化仍可能执行 WAL/数据库迁移。维护前 /knowledge stop，备份数据库，管理员更新并诊断，更新 contentVersion，再 /knowledge restart。不要与建库进程并发持锁。

回答会话可能保存问题/片段/未通过校验的输出，由宿主负责私有目录、权限、保留和加密。不保证操作系统级隔离，不自动删除资料，不提供私有库导出。真实业务 Recall@5、语义依据、p95 和稳定性须另行验收。

独立构建和发布

npm run version:knowledge -- patch
npm run check --workspace=@difyz/pi-wecom-knowledge
npm run build --workspace=@difyz/pi-wecom-knowledge
npm run test --workspace=@difyz/pi-wecom-knowledge
npm pack --workspace=@difyz/pi-wecom-knowledge
npm publish --workspace=@difyz/pi-wecom-knowledge --access public

在仓库根执行，构建后生成 difyz-pi-wecom-knowledge-0.1.2.tgz。发布与企业微信无固定先后，独立版本。prepack 构建编译 ESM、声明和 worker；prepublishOnly 先检查构建和自身测试。接口变化运行全仓 npm test 验证。只分发 dist、README、LICENSE 和包清单，不含资料或凭证。