手册 · 03

安装与配置

约 5 分钟阅读 Apache-2.0 本文基于 v0.1.0（2026-11-01）

KBFold 的安装方式取决于你想让它出现在哪儿：命令行里、DSH 里、还是被别的 AI 编辑器调用。三种装法共用同一套判定内核，只是外壳不同。先克隆仓库：

bash

git clone https://github.com/wusongwwss-collab/kbfold.git
cd kbfold

GitHub 国内访问可能不稳定；若打不开，可用加速代理或稍后重试，Gitee 镜像筹备中。

01跑起来需要什么

需要	版本	不满足会怎样
Python	3.10 或更高（零第三方依赖，无需 pip 装包）	判定内核起不来。没装时打印官方下载指引并以退出码 2 结束
Node.js（仅 npm 壳需要）	18 或更高	只影响 `node bin/kbfold.js` 这层转发壳；直接用 Python CLI 则完全不需要
磁盘	源目录体积的 1.3 倍	`trash/` 留底放不下时，`apply` 拒绝执行而不是半途而废

以下都不是必需的：Ollama（没有就跳过语义检索那一路）、任何 API key、任何云账号、数据库服务。

02三种装法

一、命令行（最常用）

bash

python hosts/cli/kbfold_cli.py plan examples/demo/fixtures --demo

嫌路径长，可以用仓内自带的 npm 包装器（bin/kbfold.js，Node 18+，只做 argv 转发，自动定位系统 Python）：

bash

node bin/kbfold.js plan examples/demo/fixtures --demo

npm 包已上线（https://www.npmjs.com/package/kbfold）：npx kbfold … 免安装即用，npm i -g kbfold 可装全局；仓内 bin/kbfold.js 包装器仍随仓提供。

二、DSH 插件

bash

dsh plugin --profile default add dsh-plugin-kbfold

装完在 DSH 里会多出五个只读工具（kb.scan / kb.plan / kb.search / kb.explain / kb.validate）。apply 和 move 刻意没有注册成工具——AI 只能预演，真正动文件必须由你自己在命令行敲。

三、MCP（给 Claude Code、Cursor 这类支持 MCP 的编辑器）

MCP 服务器同样是 stdio 形态的 Python 零依赖脚本（hosts/mcp/kbfold_server.py），由宿主拉起与关闭：

json

{
  "mcpServers": {
    "kbfold": {
      "command": "python",
      "args": ["/你的路径/kbfold/hosts/mcp/kbfold_server.py"]
    }
  }
}

配置保存后重启宿主，工具列表里确认 kb.scan / kb.plan / kb.search / kb.explain / kb.validate 五个只读工具真实可见（唯一可信的验收＝在宿主里真看到工具）。

03配置文件放哪

规则文件只有一个，放在你要整理的资料目录根部，名字固定为 kbfold.yml：

text

你的资料目录/
├── kbfold.yml        ← 规则，人可以读懂的那种
├── 合同/
├── 会议/
└── .kb/              ← 它自己的产物，别提交进 git

想给多个目录用同一套规则？在任意目录放一份 kbfold.yml，用 root: 指向上层，或者干脆跑 kbfold plan <路径> --rules <规则文件>。

04默认值是安全默认值

装完什么都不改，它就是这个行为。这张表建议在第一次 apply 之前读一遍：

行为	默认	怎么改
只读扫描	开	没有关的必要，它不写源文件
写 `.kb/` 投影	关	`kbfold apply` 才写；`plan` 只算不写
移动源文件	关	`apply --move`，且需二次确认并打印受影响文件数
删除任何文件	不存在	代码里没有 `unlink` 调用
自动整理大目录	关	`--auto-tidy`，且四条件同时成立才动手
语义检索	开（本地）	`--no-semantic`；Ollama 没起就静默降级，不报错
匿名改进反馈	关（L0，零网络调用）	`kbfold feedback on/off/show`，三档口径见仓库 `docs/FEEDBACK.md`
LLM 兜底判定	关	显式打开才用
任何网络上传	从不	没有这个开关。除本地 Ollama 端口外零外连；反馈默认关闭，开了也只上行脱敏后的统计与结构信息

最后一条如果只是「文档里说没有」，那就是一句口号。所以它做成了可自证：kbfold audit 会列出本次运行用到的所有外部端点，正常情况下列表里只有一条 127.0.0.1:11434（或空）。

05升级与降级

升级：直接装新版本，.kb/manifest.json 里的 version 字段用于兼容检查；大版本升级会先提示你备份 .kb/。
换规则：改 kbfold.yml 后重跑 plan 即可，rules.lock.yaml 会记下这一批用的是哪一版规则，所以「三个月前那批文件是按哪版规则归的」永远查得到。
卸载：删掉克隆的仓库目录，再删源目录里的 .kb/ 就彻底干净了。源文件从来没被它改过（除非你跑过 apply；那种情况用 undo 逐批撤回）。

06插件装不上会怎样

DSH 插件注册失败时，只往 stderr 写一行错误，绝不让宿主起不来。这是硬约定：插件是增强，不是生命线。所以如果你发现 DSH 里没有那五个工具，先看 DSH 的 stderr 日志，再看 dsh plugin list 里这个包是否 enabled——而不是怀疑自己装坏了 DSH。