如何使用这份文档

直接把本页面链接丢给 Codex、Claude Code、OpenCode 等 AI 编程工具，让 AI 帮你完成全部配置和整理工作。

具体操作：

1. 把当前文档的链接或内容发送给 AI 工具
2. 告诉 AI 你想搭建个人 Wiki 站点
3. AI 会根据本文档的流程，提示你配置以下平台账号和认证：
   • Cloudflare 账号和 API Token
   • Obsidian 或 Markdown 知识库
   • Quartz 静态站点生成器
4. 整体流程、数据整理和平台配置都可以交给 AI 处理

本文档的价值在于：为 AI 提供完整的知识库架构规范和操作流程，让 AI 能准确理解你的知识管理需求，并按标准流程执行。

个人 Wiki 不是”把 Markdown 放进一个目录”这么简单。真正能长期运转的系统，需要同时解决四件事：资料从哪里来，原始资料如何保持可信，知识如何被二次编译，最后如何发布成稳定可访问的网站。

这套技能的核心思想是：把知识管理当成一条工程流水线，而不是一个随手堆文件的笔记夹。

一句话模型

inbox -> raw -> wiki -> outputs -> Quartz -> Cloudflare Pages

每一层只做一件事：

只要这条边界守住，个人知识库就不会在几个月后变成无法维护的资料堆。

适用场景

这套技能适合以下人群：

• 想把 Obsidian、Markdown、AI Agent 和静态站点结合起来的人。
• 已经有大量资料、摘录、网页、知乎回答、论文、报告，但缺少统一整理流程的人。
• 希望让个人知识库既能被自己检索，又能选择性发布成公开网站的人。
• 希望用 AI 辅助整理，但不想让 AI 把来源、事实和总结混在一起的人。

不适合只想临时写几篇博客的人。博客可以直接写文章，Wiki 更适合长期沉淀、交叉引用和反复编译。

仓库结构

推荐从下面这组目录开始：

.
├── inbox/
│   └── processed/
├── raw/
│   ├── articles/
│   ├── books/
│   ├── papers/
│   ├── videos/
│   ├── podcasts/
│   ├── zhihu/
│   ├── reports/
│   └── manifests/
├── wiki/
│   ├── summaries/
│   ├── concepts/
│   └── indexes/
├── outputs/
│   ├── qa/
│   ├── health/
│   └── quartz/
├── .agents/
│   └── skills/
└── docs/
    └── skills/

其中最重要的边界是：raw/ 是输入层，wiki/ 是编译层，outputs/ 是运行层。不要把三者混用。

Inbox：允许混乱，但不能永久混乱

inbox/ 是预处理层，用来接收还没有定型的内容：

• 临时摘录
• 网页片段
• 阅读笔记
• 会议碎片
• 个人想法
• 没判断价值的材料

这里可以乱，但不能长期不处理。进入正式知识库之前，必须先做四件事：

1. 拆分：一份笔记里混了多个主题，要拆开。
2. 归并：同一来源的多个片段，要合并。
3. 补上下文：来源、作者、时间、链接、资料类型。
4. 判断归属：它是文章、书、论文、视频、播客、知乎，还是报告。

处理完成后，原始 inbox 内容移动到 inbox/processed/。这个目录只是临时已处理区，不能作为正式知识来源引用，也不参与索引、编译和发布。

Raw：原始资料层

raw/ 的职责是保存可信输入。它可以补元数据，但不要把原始内容改写成总结稿。

第一层目录只回答“资料是什么形态”，不要回答“资料讲什么主题”。例如：

raw/articles/
raw/books/
raw/papers/
raw/videos/
raw/podcasts/
raw/zhihu/
raw/reports/

知乎内容统一放到 raw/zhihu/，不要因为它讲管理、AI 或商业，就分散到 raw/articles/management/ 里。主题归属交给 frontmatter。

一个 raw 条目至少包含这些字段：

---
title: 提问的智慧
source_type: zhihu
domain:
  - 通用
topics:
  - 沟通
  - 提问
source_url: https://example.com/source
author: 作者名
published: 2017-01-26
ingested_at: 2026-05-07
tags:
  - 沟通
  - 提问
---

字段的分工要清楚：

标题要短、稳定、可读。不要使用序号前缀，不要用冒号、横线、下划线拼标题，也不要保留 **标题** 这类 Markdown 标记。

Wiki：编译层

wiki/ 不保存原文，保存对原文的结构化加工结果。

综述

综述放在 wiki/summaries/，文件命名使用：

<主题>综述.md

例如：

wiki/summaries/团队管理综述.md
wiki/summaries/低空经济综述.md
wiki/summaries/个人知识库综述.md

一篇综述至少包含：

• 主题
• 核心结论
• 关键证据
• 疑点与限制
• 关键术语
• 来源

综述的重点是“围绕主题聚合证据”，不是按导入批次写日报。不要创建 S-001、第1批资料总结 这种文件。

概念

概念放在 wiki/concepts/，文件名使用纯概念名：

wiki/concepts/组织博弈.md
wiki/concepts/向上管理.md
wiki/concepts/知识编译.md

概念页要解决“这个概念到底是什么”和“如何判断一个现象是否属于它”。建议结构是：

• 定义
• 别名
• 相关概念
• 边界：包含什么，不包含什么
• 常见混淆
• 判定规则
• 代表证据
• 来源

概念页不要写成综述压缩版。综述负责叙述和证据聚合，概念负责定义、边界和判定。

索引

索引放在 wiki/indexes/，常用三个：

wiki/indexes/All-Sources.md
wiki/indexes/All-Concepts.md
wiki/indexes/All-Topics.md

索引只服务本地 AI 和脚本检索，不参与公开站点发布，也不作为知识图谱节点。索引里只放目录和跳转，不堆正文。

Outputs：运行结果层

outputs/ 用来保存“运行中产生的结果”，而不是保存新资料。

常见内容有三类：

复杂问答归档建议包含：

• 问题
• 时间
• 使用来源
• 结论
• 证据
• 不确定性

健康检查至少检查三件事：

• 一致性：概念定义是否冲突。
• 完整性：条目是否缺定义、例子或来源。
• 孤岛：是否存在没有链接、无法被主题检索到的内容。

Agent Skills：把流程固化成可执行动作

个人 Wiki 最容易失败的地方，是每次整理都靠临场发挥。更好的方式是把流程拆成一组可调用的 skills。

推荐最小技能集：

技能文件放在：

.agents/skills/<skill-name>/SKILL.md

对应的人类说明文档放在：

docs/skills/

这样做的好处是：Agent 执行有机器可读的规则，人自己维护时也有中文操作手册。

附件处理

图片、PDF、视频等附件不要直接塞进 git。更稳的做法是：

1. 先放入 inbox。
2. 由整理脚本统一重命名。
3. 上传到对象存储，例如 Cloudflare R2。
4. 在 raw 或 wiki 中引用发布路径，例如 /assets/...。

这样仓库保持轻量，站点发布也更稳定。

发布路径规范

公开站点里的链接不要写本机绝对路径。应该使用发布路径：

/raw/...
/wiki/...
/assets/...

例如：

来源：[提问的智慧](/raw/zhihu/2017-01-26-提问的智慧/)
相关概念：[向上管理](/wiki/concepts/向上管理/)

这条规则很重要。只要文章里出现 /Users/... 这类路径，公开站点就和你的本机环境绑定了。

Quartz 发布工程

outputs/quartz/ 是完整的 Quartz 发布工程，但其中的 .generated-content/ 是生成目录，不能手工编辑。

发布流程应该固定成一个脚本入口：

./scripts/publish-project.sh

脚本负责：

1. 进入 outputs/quartz/。
2. 执行站点构建。
3. 读取当前 git commit hash、commit message 和工作区状态。
4. 使用 Wrangler 发布到 Cloudflare Pages。

如果只想检查命令，不真正发布：

./scripts/publish-project.sh --dry-run

默认 Pages 项目可以设为 wiki-gcssloop，也可以通过环境变量覆盖：

CLOUDFLARE_PAGES_PROJECT=your-project ./scripts/publish-project.sh

完整工作流

日常使用时，可以按这个顺序执行：

1. 把新资料放入 inbox/
2. 用 triage-inbox 拆分、归并、补上下文
3. 用 ingest-source 写入 raw/
4. 检查 raw 的 title、domain、topics、tags、source_url
5. 用 compile-summaries 生成或更新主题综述
6. 用 compile-concepts 维护概念页
7. 用 refresh-indexes 更新本地索引
8. 必要时用 archive-qa 保存复杂问答
9. 定期用 run-health-check 做体检
10. 用 deploy-project 发布 Quartz 站点

这条链路里最关键的是第 4 步。没有稳定元数据，后面的综述、概念和索引都会退化成手工整理。

判断一条资料能不能进入 raw

可以用下面的 checklist：

• 是否知道来源？
• 是否知道作者或发布主体？
• 是否知道发布时间，至少知道抓取时间？
• 是否能判断资料形态？
• 是否能写出简短标题？
• 是否能归入一个或多个 domain？
• 是否能标出一个或多个 topics？
• 是否保留了原始链接？
• 涉及政策、数据、统计时，是否有原始出处？

如果这些问题答不上来，先不要进入 raw，继续留在 inbox 处理。

判断一篇综述是否合格

一篇合格综述应该做到：

• 不是原文复制。
• 不是单篇资料的读后感。
• 不是按导入批次堆条目。
• 每个关键结论能回到来源。
• 能明确列出疑点和限制。
• 能产生可沉淀的概念候选。

综述不是越长越好。它的价值在于让你快速看到某个主题下“目前已经知道什么，还不知道什么”。

判断一个概念页是否合格

一个合格概念页应该能回答：

• 它是什么？
• 它不是什么？
• 它和哪些概念容易混？
• 判断它是否成立的规则是什么？
• 有哪些代表性证据？
• 这些证据来自哪里？

如果一个概念页只有一段定义，没有边界、混淆和判定规则，它还只是词条，不是可用的知识工具。

最小可运行版本

如果从零开始，不要一次性搭完整系统。可以先做最小版本：

inbox/
raw/articles/
wiki/summaries/
wiki/concepts/
wiki/indexes/
outputs/quartz/

第一阶段只要求做到：

1. 所有资料先进入 inbox。
2. 确认有价值的资料进入 raw。
3. 每周编译 1 到 3 篇综述。
4. 每周沉淀 3 到 5 个概念。
5. 每次发布只走固定脚本。

等这个流程稳定后，再补附件上传、健康检查、问答归档和多平台发布。

最常见的错误

结论

构建个人 Wiki 站点，真正要搭的不是一个网站，而是一条可重复运行的知识生产线。

inbox 负责接收混乱，raw 负责保留可信输入，wiki 负责结构化编译，outputs 负责沉淀运行结果，Quartz 和 Cloudflare Pages 负责把其中适合公开的部分发布出去。

只要每一层职责清楚，再配合一组稳定的 Agent skills，个人 Wiki 就可以从“写笔记”升级为“持续编译自己的知识系统”。