# knowledge-growth

**Repository Path**: BernardW/knowledge-growth

## Basic Information

- **Project Name**: knowledge-growth
- **Description**: 知识生长 Starter - 个人知识库作为第二大脑（Gitee 镜像）
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-08-25
- **Last Updated**: 2026-10-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 知识生长

> **从一个真实问题开始，让材料逐步长成自己的判断。**

一个由 AI 助手协助维护、但始终由你确认判断的本地个人知识工作区。

> **当前完整体验：Windows 电脑 + WorkBuddy 桌面端 + 一份非敏感文件附件。** 手机端 / Android 目前不承诺能完成本地工作区、附件原样保存和知识沉淀的完整链路——这是为了防止你被引导到一半才发现走不通。下面从零开始，一步一步来。

---

## 第一次用，从这里开始

> 核心判断：普通人搭第二大脑，第一步不是看懂原理，而是今晚就跑通一遍——电脑 + 一个助手 + 一份不敏感的材料。

我是一个普通人。上一篇讲了「为什么从问题开始」，这篇不聊原理，只聊你怎么从零跑通第一遍。每一步做完再走下一步，全程不用懂任何技术。卡住了，翻到文末的「常见卡点」。

> ⚠️ **注意**：当前完整体验以 Windows 电脑 + WorkBuddy 桌面端为准。手机端暂时不承诺完整的本地流程——先说清楚，免得你走到一半才发现跑不动。

### 第 1 步 · 准备一样东西

- 一台 **Windows 电脑**。

材料不用自己找——「知识生长」起步包里自带一份「示例材料.md」（动迁主题），第一次就用它跑通。

> 想拿自己的材料练手？可以，准备一份**不敏感**的文件：Word、PDF、Markdown 都行。

> ⛔ **隐私提醒**：不要用身份证、病历、合同、公司机密或他人隐私来做第一次测试。

> ✅ **完成标志**：电脑能用，能上网。

### 第 2 步 · 安装 WorkBuddy 桌面端

知识生长不只支持一个助手——Kimi Work、Codex、千问办公、Hermes 等也都能跑通；这篇以目前普及度相对较高的 WorkBuddy 为例，换成其他助手，步骤大同小异。当前完整体验仍以 WorkBuddy 为准。

从官网安装：**https://www.workbuddy.cn/**

请走官方入口，不要用第三方下载站。

> ✅ **完成标志**：桌面上能打开 WorkBuddy。

### 第 3 步 · 下载「知识生长」起步包

任选一个能打开的地址，下载 ZIP 并解压：

- **GitHub**：https://github.com/bernardw5174-zfyb/knowledge-growth
- **Gitee**（国内更快）：https://gitee.com/BernardW/knowledge-growth

> ![Gitee 仓库页面，「克隆/下载」下的「下载 ZIP」按钮](docs/images/gitee-download.png)

**GitHub 入口参考**（界面可能略有差异，认「Download ZIP」按钮即可）：

> ![GitHub 仓库页面，Code 菜单里的 Download ZIP 入口](docs/images/github-download.png)

页面上找下载入口：GitHub 点 `Code → Download ZIP`，Gitee 点「克隆/下载」。下载后解压，会得到一个文件夹——名字可能叫 `knowledge-growth`，也可能带 `-main` 后缀（比如 `knowledge-growth-main`）。两种都行，不用改名，认准里面装着 `AGENTS.md`、`vault`、`scripts` 这些内容的就是它。

**不需要懂 Git、仓库或命令行——把 GitHub 想成一个「放文件的网页」就行，这一步只做一件事：把整个起步包下载下来。**

> ✅ **完成标志**：你手里有一个解压好的文件夹——不管叫 `knowledge-growth` 还是 `knowledge-growth-main`，里面有 `AGENTS.md`、`vault`、`scripts` 就行。

### 第 4 步 · 把文件夹设为工作区

打开 WorkBuddy，新建一个对话，把刚解压出的那个文件夹设为工作区（不管它叫 `knowledge-growth` 还是 `knowledge-growth-main`）。

> ![WorkBuddy 里「打开本地文件夹」对话框，选择下载好的 knowledge-growth 文件夹](docs/images/set-workspace.png)

> ✅ **完成标志**：对话里能确认，工作区指向了这个文件夹。

### 第 5 步 · 上传文件，发第一条指令

直接拖「示例材料.md」：打开刚解压的文件夹，把里面的「示例材料.md」拖进对话框。

> 想用自己的材料？可以，拖第 1 步准备的那份文件也行。

> ![WorkBuddy 里把「示例材料.md」拖入对话框的操作](docs/images/select-material.png)

拖完后，发下面这句话（整段复制，不用改）：

> 请按这个工作区里的规则，处理我刚上传的这份文件：把内容分成「原文事实」「AI 的推断」「还不确定的」三块，先给我一版草稿，不要替我下结论。

AI 可能回问你两件事——「归到哪个领域」就填「演示」；「你想弄清楚什么」就填你真正关心的问题（比如：家里传的动迁消息到底有没有依据）。领域和问题都只是给材料贴的标签，这次先跑通，以后都能改。

> ✅ **完成标志**：AI 分三块给了你草稿，而不是直接甩一段总结。

### 第 6 步 · 看见什么算成功

成功标志是**两点**，不是一段漂亮的话。为什么要看这两点？因为第二大脑不是让 AI 替你总结——**原始材料原样保留 → AI 给出待确认的整理 → 你拍板**，这条链缺一环，它就不是你的知识库，只是 AI 的总结。

1. AI **明确告诉你**：你的原文件已经**原样留了一份副本**（并说清存在哪）；
2. AI 给了你一份**待确认的草稿**，把「原文事实 / AI 的推断 / 不确定」分开，而不是替你定了案。

> ![一次成功的草稿输出：原文事实、AI 的推断、还不确定的，三块分开列](docs/images/result-display.png)

看到这两点，第一次就跑通了。目录长什么样、有哪些规则，第一天不用管。

### 常见卡点

| 卡住的地方 | 怎么办 |
|---|---|
| ZIP 下载不动、打不开 | 换另一个地址（GitHub ↔ Gitee 内容一样） |
| 助手说找不到文件夹 | 回到第 4 步，确认选对了解压出的那个文件夹 |
| 助手说读不到附件 | 把文件直接拖进对话，再发一次 |
| 发出去 AI 直接开始「总结」 | 把第 5 步那段话原样再发一次，重点在「先给我草稿，不要替我下结论」 |
| AI 追问「你想弄清楚什么」 | 填你真正关心的问题；用「示例材料.md」的话，材料开头就写着问题，照着说就行 |

### 跑通了，下一步？

你刚刚做的，不是「学会了一个 AI 工具」，而是第一次跑通了一个最小的知识生长闭环：

**问题 → 材料 → AI 整理 → 你确认。**

这就是上一篇《有的放矢？现在的问题是，连靶子都没有》四步法里的前三步——剩下那一步「你确认」，是你以后每次看三栏草稿时都会做的动作，也是唯一不能交给 AI 的一步。

以后你面对的每一份新材料，都可以重复这套动作：说清问题、附一份材料、看清三栏、你确认。用熟了，你就不用再看教程了。

### 关于知识生长

知识生长关注的不是「又多了一个 AI 工具」，而是普通人怎样把资料、判断与复盘连成自己的认知系统。

如果某一步卡住了，欢迎留言告诉我卡在哪一步——那是最值得修的坑。

---

## 它解决什么问题

资料越收越多，通常会遇到三个问题：

- 原文、摘要、自己的判断混在一起，回头说不清依据；
- AI 看过材料，却没有留下可审、可改、可复用的过程；
- 还没想清楚，结论和行动已经被自动写死。

知识生长提供的是一套轻量的工作协议：

```text
真实问题 + 一份材料
        ↓
原样留一份原始副本
        ↓
AI 生成可审阅草稿：事实 / 推断 / 不确定项 / 下一步
        ↓
你明确确认后，才成为正式知识
        ↓
需要时，再提炼框架、记录实践或复盘结果
```

**AI 负责整理与提案；你负责确认、取舍与现实决策。**

---

## 核心原则

1. **领域优先**：资料不按「所有原文 / 所有笔记」混放；每个真实领域都有自己的原文、知识、框架、实战和复盘。
2. **来源可追溯**：正式支持的文件附件，会原样保存一份到对应领域，原始材料只进不改。
3. **草稿先行**：AI 可以写草稿，但不能把草稿自动当成你的正式判断。
4. **事实与推断分开**：材料写了什么、AI 推导了什么、仍缺什么信息，应当能被单独审阅。
5. **框架也要确认**：要求「提炼框架」只会生成候选提案；你确认结构后才进入正式框架区。
6. **本地隐私边界**：持久化内容只引用工作区内的相对路径，不应回显附件绝对路径、本机用户名或临时下载位置。

---

## 框架如何产生

当你已经确认了多份知识，并主动说「提炼成框架」时，AI 的第一步必须是创建**框架提案**，而不是直接写进正式框架区。

提案至少应说明：

- 推荐的最小充分结构；
- 每一部分究竟解决什么独立问题；
- 输入 → 处理 → 输出（IPO）；
- 适用范围、证据来源、置信度与缺口；
- 哪些内容只是主框架的一节或附件，不应单独建页。

有限城市经验、单个案例或商业文章不能包装成「全国通用规则」。只有你明确确认采用的结构，才会成为正式框架。

---

## 手工模式

没有可读写本地工作区的 AI 助手时，仍可使用模板，手工维护同一套思路：

- [`vault/_templates/手工模式-问题笔记.md`](vault/_templates/手工模式-问题笔记.md)
- [`vault/_templates/知识草稿.md`](vault/_templates/知识草稿.md)
- [`vault/_templates/阶段总结草稿.md`](vault/_templates/阶段总结草稿.md)

手工模式不自动保存原文、创建领域或生成草稿，但保留同一套「来源 → 草稿 → 确认 → 复盘」的思路。

---

## 进阶：目录结构与技术细节

> 下面是给想理解内部结构、或需要排障的人看的；第一次使用不需要读。

### 工作区结构

```text
vault/
├── 00-系统/                       # schema、manifest、领域索引
├── <已确认领域>/                   # 例如：学习、房产、健康
│   ├── 00-raw/                    # 原始材料的字节级副本，只进不改
│   ├── 01-知识/
│   │   └── _drafts/               # 等待人工确认的草稿
│   ├── 02-框架/                    # 已确认、可跨问题复用的规则
│   ├── 03-实战/                    # 已确认的判断、行动、验证点
│   └── 04-复盘/                    # 结果、修正与经验
└── _templates/                     # 草稿与手工模式模板
```

领域按真实问题逐个创建，不需要一开始就预建「健康 / 理财 / 学习 / 工作」等空目录。

### 治理档位（确认摩擦可调）

`vault/00-系统/manifest.yaml` 里的 `governance_mode` 控制「知识 / 框架」写入时的**确认摩擦**——三档都须你确认后才正式化，可调的是确认粒度：

| 档位 | 知识页 | 框架 | 决策 / 实战 / 复盘 |
|---|---|---|---|
| `free` 自由 | 草稿待确认，要素齐全可整批一次确认 | 候选待确认 | 永不自动 |
| `collaborative` 协作（默认） | 草稿待确认，支持批量确认低风险项 | 候选待确认 | 永不自动 |
| `strict` 严格 | 草稿待确认，补证后才可确认 | 候选待确认 | 永不自动 |

**任何档位下不变**：知识页草稿都要你确认后才成为正式知识（不自动晋升）；决策、实战、复盘都要你显式指令；框架永远只能先成为候选提案。「不替你下结论」这条底线，跟档位无关。

### 本地脚本与测试

```bash
# 创建一个已确认领域
python3 scripts/create_domain.py "学习"

# 一键安装垂直包（clone 到 _packages/ + 建领域工作区 + 注册 active_domains；可用包见 [docs/可用垂直包.md](docs/可用垂直包.md)）
python3 scripts/install_package.py "https://github.com/bernardw5174-zfyb/job-search-bw.git"

# 升级：在 Agent 里说「升级求职知识库」或「升级知识库底座」即可（底座须 git clone 安装；ZIP 安装无法自动升级）

# 将运行时明确提供的附件路径做字节级复制
python3 scripts/import_attachment.py "/path/from-runtime/article.md" "学习"

# 抓取 URL 正文，存为「非字节级」文本 Raw（附时间戳 + URL + 标注）
python3 scripts/import_url.py "https://example.com/article" "学习"

# 校验工作区核心不变量（隐私泄露 / 晋升留痕 / 版本线一致性）
python3 scripts/validate.py

# 运行脚本行为测试
python3 -m unittest discover -s tests -v
```

现有测试覆盖：

- 创建领域时生成完整五层目录并更新索引；
- 同名同字节原文不重复保存；
- 同名不同字节原文不覆盖历史材料；
- 路径型非法领域名被拒绝；
- 校验脚本对隐私泄露、晋升留痕缺失、版本线漂移分别报 WARN / WARN / ERROR；
- 校验脚本对 superseded_by 时态一致性报 WARN（active 带 superseded_by、指向页断链），frozen/archived 无替代页仅 --verbose 提示（降噪）。

> 这些测试验证的是脚本和目录契约，不能替代某个 AI 助手运行时的实际验收。更换助手、模型、操作系统或附件方式时，请先用一份非敏感材料做冒烟测试，并检查所有持久化产物。

### 文件附件与链接的区别

- **文件附件 / 运行时提供的本地文件路径**：本项目的正式支持路径。助手应运行复制脚本，完成字节级复制和校验。
- **URL / 微信文章 / 登录墙网页**：是否能读取取决于运行时与网站限制。本项目**不承诺**任意 URL 都能入库。
- **URL 能抓到正文时**：助手默认直接抓取正文，保存为「非字节级」文本 Raw（附抓取时间戳、原文 URL，显式标注非字节级原件），不再追问 Raw 口径；抓取丢失的图片、排版等内容会在 Raw 文件头如实标注。
- 如果无法取得原始文件字节，助手不得把网页摘要或转写内容冒充为原文副本；可让用户提供 HTML/PDF/文本文件，或将「二手摘录」显式标为非字节级来源。

详细行为边界见 [`AGENTS.md`](AGENTS.md)、[`vault/00-系统/schema.md`](vault/00-系统/schema.md)、[兼容性与验证](docs/兼容性与验证.md)、[垂直包](docs/垂直包.md) 与 [可用垂直包](docs/可用垂直包.md)。

---

## 隐私与安全

- 文件默认保留在你的电脑；但助手是否把材料发送给模型服务商，取决于你选择的运行时、模型与隐私设置。
- 不要上传敏感个人材料、公司机密或他人隐私。
- 不把工作区内的原文、草稿、正式知识、实践记录和复盘直接提交到公开仓库；本仓库的 `.gitignore` 默认将这些用户数据排除。
- 本项目不提供医疗、法律、投资、职业或关系决策；它只帮助你保存依据、形成可审阅草稿并记录不确定项。

---

## 当前状态与路线

- **当前版本**：v0.1.6（正式版）。
- **双版本线**：产品包版本（`starter_version`，见 `vault/00-系统/manifest.yaml`）与协议版本（`schema_version`，见 `vault/00-系统/schema.md` 头部）独立演进。产品包版本表示发布形态（当前 v0.1.6）；schema 版本表示协议 / 字段语义修订（当前 0.2.5），可随产品或独立于产品递增。两线数值不一致不是漂移；判冲突以 schema.md 头部声明为准。
- **已具备**：领域优先目录、原文字节复制脚本、知识草稿/确认流程（含 `confirmed_at` 晋升留痕）、框架候选门、治理档位、工作区校验脚本（`validate.py`）、手工模式模板与脚本行为测试。
- **仍需验证**：每个具体助手 + 模型 + 操作系统组合的附件能力、网页访问能力、持久化隐私边界和完整闭环体验。
- **验证证据**：[docs/兼容性与验证.md](docs/兼容性与验证.md) —— 各运行时逐项验收记录、已验证范围与 v0.1.4 现场证据（2026-09-18 回填）。

如果你使用了新的运行时，欢迎提交可复现的兼容性反馈：运行时/模型/系统版本、输入类型、产生的文件树、协议通过项与卡点。请先删除个人材料和路径信息。

---

## 项目状态与维护承诺

- **单人维护**：本项目由个人在业余时间维护，更新节奏不定期，不承诺固定发版周期。
- **反馈与接手**：欢迎提交 Issue 反馈问题、发起 PR 改进，或 fork 仓库自行接手维护。维护者会尽量回复，但不承诺响应时间。
- **数据逃生**：即使项目未来停止更新，`vault/` 下的内容仍是纯 Markdown + YAML，任何文本编辑器或 AI 助手都能继续读写——你的知识不会因项目停更而被锁死。

---

## Gitee 镜像（国内访问）

GitHub 在国内访问可能较慢或被墙。本仓库的**完整镜像**同步在 Gitee：

- **GitHub（主仓）**：https://github.com/bernardw5174-zfyb/knowledge-growth
- **Gitee（镜像）**：https://gitee.com/BernardW/knowledge-growth

日常只推 GitHub；通过 GitHub Actions 自动把每次提交镜像到 Gitee（见 `.github/workflows/mirror.yml`）。首次使用前需在本地执行一次初始镜像：

```bash
git remote add gitee https://gitee.com/BernardW/knowledge-growth.git
git push gitee main
```

之后你只需 `git push origin main`，Gitee 会自动跟上。

---

## License

[MIT](LICENSE)

---

**品牌：知识生长 · AI 个人知识系统**