Skip to content
ZXY edited this page Aug 19, 2026 · 1 revision

OpenKnowledge

OpenKnowledge 是为 AI 编程助手提供的项目知识库——知识按项目隔离,通过各 AI 助手的 hooks/扩展自动注入 AI 上下文,并能强制执行「改代码必须写变更日志」这类工作流规则。单二进制 Go CLI(ok),零运行时依赖。

三分钟上手

1. 安装

平台 方式
Windows 运行 OpenKnowledgeSetup-<版本>.exe(免管理员,装到 %LOCALAPPDATA%\Programs\OpenKnowledge,卸载默认保留知识库数据)
Linux openknowledge_<版本>_linux_amd64.tar.gz 解压后 ./ok setup,或 sudo dpkg -i openknowledge_<版本>_amd64.deb

安装包约 50MB,内含 llama.cpp CPU runtime(本地 embedding 用);模型首次启用时按需下载。详见 安装与升级。

2. 打开 Web GUI,完成引导配置

双击 ok.exe(或执行 ok gui),浏览器自动打开管理界面 http://127.0.0.1:17888。首次使用落在引导页,按卡片顺序点完即可:

  1. 写 hooks——给机器上所有已检测的 AI 助手写入集成:Kimi Code、Pi、ZCode、Reasonix、opencode、Claude Code/CodePilot、Codex、Qoder CN(CLI + IDE)、DeepSeek Harness
  2. 装技能——openknowledge-init / on / off / propose / capture / wiki 六个技能写入各 agent 的技能目录
  3. 配 embedding——语义检索三选一:线上 OpenAI 兼容服务 / 本机 Ollama(免 key)/ 内置本地模型(完全离线,知识不出本机);跳过则只用关键词检索,之后随时可补配
引导页

完成后进入管理页,日常的条目维护都在这里点点鼠标完成:

管理页
标签页 功能
管理 项目/条目增删改、检索预览、全局开关;草稿条目带徽标,一键「采纳」转正
引导 hooks、技能、embedding 一站配完(等价于命令行 ok setup),另有卸载卡片
其他 数据导出/导入(zip 备份恢复)、更新日志、删除项目知识库(三重确认)
日志 ok / 守护 / embedding 三来源实时日志,多选过滤

GUI 由全系统唯一的常驻 daemon 托管,关页面不退进程;ok daemon stop 可停止。不用图形界面的话,ok setup 是命令行等价物(幂等),ok doctor 可体检配置与 hooks 状态。

3. 初始化项目并生成 wiki

打开你的 AI 助手,在需要知识库的项目目录里新开一个会话(hooks 在会话启动时加载),然后:

  1. 初始化——输入 /openknowledge-init(或直接说「初始化知识库」):当前项目注册进知识库,名字自动取目录名
  2. 生成 wiki——再说「生成项目 wiki」:wiki 技能扫描代码结构与 git 历史,把项目沉淀成一批 reference 条目;之后新功能定稿时说「更新 wiki」增量维护

4. 日常使用:在 AI 会话里用技能

装好后基本不用记命令——自然语言会触发对应技能:

你说 发生的
「初始化知识库」 技能调 ok init 注册当前项目
「生成项目 wiki」/「更新 wiki」 wiki 技能全量/增量沉淀项目结构
「开启/关闭知识库」 技能调 ok on / ok off 切全局开关
「开启自动提取」/「调整提取频率」 技能调 ok capture 切沉淀模式
(踩坑解决、新需求定稿) AI 主动问「要不要沉淀进知识库」,同意后 ok propose 记草稿,人批准后生效

同时 hooks 在后台自动做两件事,无需任何口令:

  • 提问即注入:每次提问按关键词 + 向量混合检索,把相关知识塞进 AI 上下文;首次提问还会带上强制约定全文(mandatory 条目)
  • 改代码必写日志:AI 改了代码没写变更日志,回合结束时被阻断提醒(同会话同规则只阻断一次)

知识条目

每条知识是一个带 frontmatter 的 Markdown 文件(ok add 创建,也可手写),集中存放在 ~/.openknowledge/,不污染项目仓库:

---
title: 变更日志强制规则
type: rule              # rule | pitfall | note | reference
tags: [changelog, workflow]
mandatory: true         # true = 每会话首次提问全文注入
summary: 每次代码修改必须立即记录变更日志
---

正文(Markdown 自由格式)

草稿流程(AI 提议,人批准):ok propose 记的草稿条目(draft: true)不参与检索与注入,只在 ok list 和 GUI 可见;确认后 ok approve <文件> 或 GUI「采纳」转正。沉淀模式用 ok capture propose|auto 切换。

常用命令

命令 作用
ok setup 首次引导:hooks 配置 + 技能安装 + embedding 配置
ok gui 启动 Web 管理界面(双击 exe 无参数运行同效)
ok init [名字] 注册当前项目,并幂等写入/更新 hooks 配置
ok add / ok list 新建条目 / 列出项目与条目
ok propose / ok approve <文件> AI 提议草稿 / 批准转正
ok capture [propose|auto|interval <n>] 查看/切换沉淀模式与轮次间隔
ok search <词> 命令行预览检索效果
ok index 同步索引与向量(手改条目后执行)
ok doctor 体检:配置、embedding 连通性、hooks 状态
ok on / ok off 全局开关
ok daemon [stop] 常驻进程管理(开机自启,一般无需手动操作)

检索算法一瞥

SQLite + FTS5 混合检索,单文件 kb.db 零基础设施:

  • 关键词通道:FTS5 + BM25,中文二元组分词;语义通道:embedding + 余弦相似度
  • 准入与排序分离:两路独立准入,融合默认按名次(RRF),模型无关无需调参
  • 信号叠加:泛化门控、时效衰减、注入→采纳反馈、跨轮注入冷却(详见 配置手册)