Repository navigation
Home
OpenKnowledge 是为 AI 编程助手提供的项目知识库——知识按项目隔离,通过各 AI 助手的 hooks/扩展自动注入 AI 上下文,并能强制执行「改代码必须写变更日志」这类工作流规则。单二进制 Go CLI(ok),零运行时依赖。
- 安装与升级 → 安装与升级
- 配置参考(config.toml 全量键与默认值) → 配置手册
- 各版本变更 → 更新日志
- 架构深入 → 主仓 ARCHITECTURE.md
| 平台 | 方式 |
|---|---|
| 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 用);模型首次启用时按需下载。详见 安装与升级。
双击 ok.exe(或执行 ok gui),浏览器自动打开管理界面 http://127.0.0.1:17888。首次使用落在引导页,按卡片顺序点完即可:
- 写 hooks——给机器上所有已检测的 AI 助手写入集成:Kimi Code、Pi、ZCode、Reasonix、opencode、Claude Code/CodePilot、Codex、Qoder CN(CLI + IDE)、DeepSeek Harness
-
装技能——
openknowledge-init / on / off / propose / capture / wiki六个技能写入各 agent 的技能目录 - 配 embedding——语义检索三选一:线上 OpenAI 兼容服务 / 本机 Ollama(免 key)/ 内置本地模型(完全离线,知识不出本机);跳过则只用关键词检索,之后随时可补配
完成后进入管理页,日常的条目维护都在这里点点鼠标完成:
| 标签页 | 功能 |
|---|---|
| 管理 | 项目/条目增删改、检索预览、全局开关;草稿条目带徽标,一键「采纳」转正 |
| 引导 | hooks、技能、embedding 一站配完(等价于命令行 ok setup),另有卸载卡片 |
| 其他 | 数据导出/导入(zip 备份恢复)、更新日志、删除项目知识库(三重确认) |
| 日志 | ok / 守护 / embedding 三来源实时日志,多选过滤 |
GUI 由全系统唯一的常驻 daemon 托管,关页面不退进程;ok daemon stop 可停止。不用图形界面的话,ok setup 是命令行等价物(幂等),ok doctor 可体检配置与 hooks 状态。
打开你的 AI 助手,在需要知识库的项目目录里新开一个会话(hooks 在会话启动时加载),然后:
-
初始化——输入
/openknowledge-init(或直接说「初始化知识库」):当前项目注册进知识库,名字自动取目录名 - 生成 wiki——再说「生成项目 wiki」:wiki 技能扫描代码结构与 git 历史,把项目沉淀成一批 reference 条目;之后新功能定稿时说「更新 wiki」增量维护
装好后基本不用记命令——自然语言会触发对应技能:
| 你说 | 发生的 |
|---|---|
| 「初始化知识库」 | 技能调 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),模型无关无需调参
- 信号叠加:泛化门控、时效衰减、注入→采纳反馈、跨轮注入冷却(详见 配置手册)