快速开始 · 02

快速开始

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

第一步：装

这工具在不同市场里的叫法不一样。按你手上有什么挑一条，别混装——同一台机器上装两套会互相盖掉产物目录。

渠道	那个市场里它叫什么	怎么装	状态
DSH 插件市场	知识库整备台`dsh-plugin-kbfold`	dsh plugin add dsh-plugin-kbfold	筹备中
WorkBuddy 开放平台	知识库整备台`kbfold`	在市场里搜「知识库整备台」	筹备中
npm registry	kbfold`kbfold`	npm 包装器（bin/kbfold.js）已随仓提供，registry 发布筹备中；当前请先从 GitHub 克隆仓库	筹备中
GitHub Releases	KBFold`kbfold`	`git clone https://github.com/wusongwwss-collab/kbfold.git`	已上架

搜不到就按包名搜。中文市场显示中文名，英文包管理器只认包名——这两列写得不一样不是笔误，是各市场的规矩。

这一篇只让你先看到它跑起来是什么样：一屏判定报告，零写入。跑完你会有一个带索引的知识库目录，以及一份可以逐条回看的执行记录。原理和取舍在「架构与设计」里。

下文的 kbfold 命令＝克隆仓库后的 python hosts/cli/kbfold_cli.py（判定内核，Python 3.10+ 零第三方依赖），也可以用仓内自带的 Node 壳 node bin/kbfold.js 代替——两者转发到同一个内核。

bash

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

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

01第二步：跑一次不改任何东西的预演

不用先准备自己的资料。仓库里带了一个约 1000 个文件的合成假目录 examples/demo/fixtures/（配好 examples/demo/kbfold.yml），任何人都能复现同一份输出：

bash

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

你会看到三块东西：

现状统计：扫到多少文件、多少能判定、多少待归、多少被规则排除——先给你一个「这堆东西有多乱」的量。
疑似知识库：每条带置信和原因，比如「0.95，发现 .xhproject 标记」或「0.45，仅名称词表命中，建议你确认」。
平手清单：两条规则具体程度一样的文件，不猜，直接列进 _inbox/ 并附两条候选。

演示目录里故意放了三组打平的目录，所以你第一次跑就会看见 _inbox。这是设计好的：把「不猜」变成亲眼所见，而不是 README 里的一句承诺。

02第三步：第一次看得见的变化

预演满意了，再让它动真格——但第一次只改名，不搬家：

bash

python hosts/cli/kbfold_cli.py apply examples/demo/fixtures --rename-only

--rename-only 只做原地改名，不动目录结构。改完它会在末尾打出这一批的批次号，以及那条退路：

bash

python hosts/cli/kbfold_cli.py undo 20261030-1412-a3f9

undo 是逆序回滚，而且每一次撤销本身也是往 journal 里追加一条记录，历史永不被改写。所以你可以撤了再撤，也可以回头看「这一批到底干了什么」。

03产物长什么样

全部产物都在这一个目录里，源文件一个都没动：

text

<库根>/.kb/
├── manifest.json       指纹台账：增量与「移动识别」的唯一依据
├── plan.json           本次判定计划，可直接 diff、贴进 issue、人工改
├── projection/         投影视图（软链接或纯清单）
│   ├── 02-合同/
│   └── _inbox/         平手与低置信的落点，附候选与理由
├── index.sqlite        FTS5 全文 + 分块，可被 DSH / MCP 直接查
├── rules.lock.yaml     本次生效的规则快照
├── journal.jsonl       追加式回滚日志，永不改写
├── trash/<batch>/      原件快照，保留 N 天
└── undo/               按批次分组的回滚索引

一句话：rm -rf .kb 即完全复原。 删之前建议先跑一遍 kbfold audit，看看投影里有没有你后来手工加进去、而源目录里没有的东西。

04第一次别急着做的事

别做	为什么	先做什么
直接对整个盘 `apply --move`	跨卷移动不是原子操作，且第一次判定必然出现平手	先 `plan`，看完平手清单再分批跑
第一次就开 `--auto-tidy`	自动整理只在「未分类 + 白名单扩展名 + 大小上限 + 目标唯一」四条同时成立时动手	先拿几十个文件试试手感
把 `.kb/` 提交进 git	里面有 trash 快照和 sqlite，体积会炸	把 `.kb/` 写进 `.gitignore`
同一目录装两套工具	两个工具各自维护 manifest，会互相盖掉产物	一个库只用一个工具

05想看它凭什么这么判

挑一个文件，问它为什么在这儿：

bash

python hosts/cli/kbfold_cli.py explain "02-合同/2024-星海-采购合同-v2.pdf"

它读的是 manifest 里的 reason 字段，回答「命中第几级、依据是什么、如果改规则会变成什么」。这也是为什么 .kb/manifest.json 的格式是完全公开的——库格式公开规范 FORMAT v0.1（仓库 docs/FORMAT.md）已冻结：第三方按规范即可读写 .kb/，我们不加私有字段。一个能自证的文件组织器，才配被用在真实资料上。