# knowledgebase

**Repository Path**: yangjam_tm/knowledgebase

## Basic Information

- **Project Name**: knowledgebase
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-25
- **Last Updated**: 2026-10-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

---
title: 个人知识库规划（软件开发 + 个人生活）
aliases: [知识库规划, 个人知识库规划]
tags: [meta/plan]
created: 2026-09-27
updated: 2026-10-03
status: growing
---

# 个人知识库规划（软件开发 + 个人生活）

> 定位：单人维护、多端使用的个人知识库，收录软件开发（GPU 软硬件为主）与个人生活两类知识。git 只跟踪可公开的部分并推到 Gitee 公开库作异地备份；生活域含隐私，整体不进 git（§8 §9）。

## 0. 已定决策

| # | 决策项 | 结论 | 影响章节 |
|---|---|---|---|
| 1 | 链接形式 | **保留 Markdown 链接** `[文本](路径)`，保证 Gitee 网页端可直接点开 | §7.1 |
| 2 | 目录命名 | **一级目录用 ASCII**，链接目标中不出现中文路径（书籍拆解目录与其文件除外，见决策 12） | §3 §4 |
| 3 | 多端同步 | **Remotely Save**，后端为 **S3 兼容存储**（Cloudflare R2 / 阿里 OSS） | §9.1 §9.3 |
| 4 | 附件 | `assets`、`excalidraw` 进 git；`external` 与 `personal` 不进 git，但由 Remotely Save 同步到其它设备 | §8 §9.1 |
| 5 | `.obsidian/` | 进 git，但排除 `workspace*.json`；**不**交给 Remotely Save 同步 | §8.2 §9.1 |
| 6 | 笔记语言 | **中文为主**，专有名词、API、代码标识符保留英文原形并与中文对照 | §4 §6 |
| 7 | 仓库可见性 | **技术域公开**（Gitee 公开库）；**生活域不进 git**（`20-life/` 与 `91-attachments/personal/`），只由 Remotely Save 跨端同步 | §8 §9.2 §9.4 |
| 8 | Markdown 风格 | **Linter 插件**（`obsidian-linter`）保存时自动格式化，规则见 §8.3 | §6 §8.3 |
| 9 | 知识域 | **一级目录按知识域分**：`10-tech/`（软件开发）、`20-life/`（个人生活）、`30-reading/`（跨域阅读笔记）；域内再分层 | §2 §3 |
| 10 | 生活域隐私 | 生活笔记与其附件一律不进 git；生活笔记的图片必须落在 `91-attachments/personal/` | §8 §10 |
| 11 | 生活主题标签 | 只设 `life/` 前缀，二级自由命名，不预设受控清单 | §5 |
| 12 | 书籍拆解的归属 | **整本书的拆解按主题归域**：生活类（情感、关系、沟通、健康、金钱等）放 `20-life/<中文书名>/`（随生活域不进 git），非生活类放 `30-reading/<中文书名>/`；两处的目录结构与命名一致（目录名与入口文件同名 + `第NN章-<中文标题>.md`） | §2 §3 §5 |

## 1. 目标与范围

本库是个人知识库，收录两类知识，分别落在两个知识域（§2 §3）。

**A. 软件开发（技术域 `10-tech/`）**：

- 硬件：GPU 架构、显存层次、片间互联（NVLink/PCIe）、功耗与散热
- 操作系统：Linux（驱动、内存管理、调度、性能观测）
- 语言与运行时：C / C++ / Python / CUDA / HIP / OpenCL / Bash
- 框架与推理引擎：vLLM、PyTorch 等
- 软件架构：架构定义与质量属性、架构实践方法与团队组织（《Effective 软件架构》《软件架构：Python 语言实现》）
- 配套：性能剖析方法与工具（Nsight、rocprof 等）、环境搭建、故障排查

**B. 个人生活（生活域 `20-life/`）**：

- 收录**可复用的知识、方法与经验**：健康与身体、金钱与消费、人际与家庭、家务与生活技能、心理与习惯、学习方法。类别不预设，用 `life/` 标签的自由二级命名表达（§5）；某一类积累到 15 篇再加二级目录（§2）。
- 生活域含隐私，**整体不进 git**，只由 Remotely Save 在设备间同步（§8 §9）。
- **不收流水账式记录**（日程、心情日记、逐日打卡）：那是「发生的事」，不是「可复用的知识」。确有保存价值的，按 §4 的时间型命名收进来，并在笔记里写清可复用的结论。

**不收录**：成篇电子书与论文原文（原文放 `91-attachments/external/`，笔记里写来源链接，见 §8）。

**例外**：整本书的拆解是「读了一本书」这类产出，**按主题归域**（§0 决策 12）——生活类书籍放 `20-life/<书名>/`（随生活域整体不进 git）；非生活类（技术、跨域）放 `30-reading/<书名>/`，技术类也可以就近放进 `10-tech/` 的对应主题下。两处的目录结构与命名规则一致（§3）。

## 2. 组织原则：知识域 → 分层 → 标签

三层结构，第一层按**知识域**分，第二层域内分层，第三层用**标签**表达横切主题：

1. **第一层：知识域**（§3）。`10-tech/`（软件开发）、`20-life/`（个人生活）、`30-reading/`（跨域阅读笔记）。域是排他的，一篇笔记只属于一个域；域同时是**可见性边界** —— `10-tech/`、`30-reading/` 进 git（公开），`20-life/` 不进 git。**书籍拆解按书的主题归域**：生活类的书随 `20-life/` 不进 git，非生活类的书进 `30-reading/`（§0 决策 12）。
2. **第二层：域内分层**。`10-tech/` 按**知识形态**分，形态是排他的，一篇笔记只可能落在一处。`20-life/` 不预设分层，笔记少时直接平铺，某一类 ≥ 15 篇时再建与标签二级名一致的目录（它按**主题**分，因为生活知识的检索入口就是「这是关于什么的」）。**书籍拆解是这条规则的例外**：它以书为单位建目录，因为一本书本身就是天然的聚合单元（§3）。
3. **第三层：标签**（§5）。技术域用 `hw/`、`os/`、`lang/`、`fw/`、`perf/`、`tool/` 表达横切主题；生活域只用一个 `life/` 前缀，二级自由命名。一篇笔记可带多个标签。
4. **主题导航靠标签与图谱**（§7.2）：笔记本身不承担索引职责，跨目录聚合内容交给标签检索与图谱视图。

**二义在域内化解**：`CUDA 编程模型` 落在 `10-tech/` 的「基本概念」形态目录下，用 `lang/cuda` 标签补足主题归属；生活域的目录与 `life/*` 标签一一对应，不存在两套命名。

## 3. 目录结构

一级目录一律 ASCII（§0 决策 2）：目录名会进入 Markdown 链接的目标路径，而 Obsidian 在 Markdown 链接模式下会按 UTF-8 对链接目标做 percent-encoding（中文会变成 `%E5%9F%BA...`）。一级目录用 ASCII 后，域的边界稳定、可迁移。**域内则相反**：笔记文件名一律用中文（取自标题），书籍拆解目录也用中文书名 —— 链接里因此会出现 `%E4...` 转义，这是刻意接受的代价，换来文件浏览器与搜索结果里一眼可读（§7.1 第 2 条）。

```text
<库根>\
├─ 00-inbox\               收件箱；唯一允许低质量的地方，有处置期限（§10）。注意它进 git，生活草稿不要放这里
├─ 10-tech\                软件开发域 —— 进 git
├─ 20-life\                个人生活域 —— 不进 git（§8），只由 Remotely Save 跨端同步
├─ 30-reading\             跨域阅读区：非生活类书的整本书拆解（目录用中文书名）—— 进 git
├─ 90-templates\           模板：笔记模板（供核心「模板」插件读取）
└─ 91-attachments\         附件：图片、Excalidraw、维护工具、外部资料、生活域附件 —— 五类分管规则见 §8.1
```

**本节只定义一级目录。** 各域内部的二级、三级目录（技术域的知识形态分层、生活域的主题分层与书名目录）由 §2 的分层原则和 §4 的命名规范约定，不在本节逐一列举 —— 具体清单会随内容增补而增删，写死在文档里只会过期；需要准确结构时直接看文件系统。

要点：

- **一级目录 = 知识域**（§0 决策 9）。域是排他的，也是可见性边界：`10-tech/`、`30-reading/` 进 git（公开），`20-life/` 不进 git（隐私）。
- **数字前缀**用于固化 Obsidian 文件浏览器的排序。少了前缀，排序结果依赖编辑器与平台，顺序不稳定。域用 10 / 20 / 30，域内目录再从 `01` 起编号，给重排与增补留出空隙。
- **域内的分层规则见 §2**：技术域按知识形态分，形态目录之内再按知识领域或项目名细分；生活域按主题分，目录名与 `life/*` 标签的二级名一致。具体目录名遵循 §4 的 ASCII 命名规则，本节不列举（**书籍拆解目录除外**，它用中文书名，见下一条）。
- **`20-life` 不预设分层**：生活知识的检索入口是「这是关于什么的」，交给 `life/` 标签即可；只有当某类笔记 ≥ 15 篇才在该域下建二级目录，且目录名与标签二级名保持一致（`20-life/sleep/` ↔ `life/sleep`）。**书籍拆解是例外**：直接以中文书名建目录（`20-life/爱情心理学/`），不等待「某类 ≥ 15 篇」这个触发条件。
- **书籍拆解统一按书开二级目录**（`<中文书名>/`）：目录名与目录内的入口文件同名，都用中文书名（`爱情心理学/` ↔ `爱情心理学/爱情心理学.md`）——入口文件即整本书的索引，逐章拆解命名为 `第NN章-<中文标题>.md`（如 `第01章-爱情究竟是什么.md`）。**章号只写一次**：原书标题里的「第一章」/「第 1 章」要剥掉，`第NN章` 前缀统一用两位阿拉伯数字（`第01章`…`第16章`），这样排序稳定、也不会出现 `第01章-第一章-…` 这类重复。其余只把标题里的 `：（）·` 等字符换成 `-`；**章节文件同样用中文**。**归域看书的主题**：生活类的书放 `20-life/`（不进 git），非生活类的书放 `30-reading/`（§0 决策 12）。
- **书籍拆解的逐章文件必须带顺序导航**：每篇 `第NN章-….md` 文末留一个空行，再写一行引用块 `> 上一篇：[…](第NN章-….md) & 下一篇：[…](第NN章-….md) & [返回大纲](<中文书名>.md)`，其中 `[返回大纲]` 指向同目录里与目录同名的入口文件（如 `爱情心理学/爱情心理学.md`）。首篇的「上一篇」写 `无（本书从这里开始）`，末篇的「下一篇」写 `无（本书到此结束）`（§7.2）。入口文件的「逐章拆解」小节里另起一段给一句「按顺序阅读请从 [首篇](第00章-….md) 开始」，作为进入这条链的入口。这样一本书既能从索引跳进任意一篇，也能从任意一篇一路读到底；导航用的是库内既有的 Markdown 链接写法，不含锚点（§7.1）。
- **拆解只覆盖正文，附属材料不单列成篇**：书末的**致谢、审校后记、参考文献/注释**，以及出版方写的序跋这类礼节性或查阅性材料，一律**不单独成篇**；**作者本人写的自序/前言/导言**若含全书立场或方法论，把要点**并入入口文件的「关于开篇」一段**即可，章节文件仍从第一章开始编号、首篇的「上一篇」写 `无（本书从这里开始）`。判断标准沿用 §4 的分工原则——**换个上下文还能不能独立成立**：礼节与索引性材料不能，故不入库。2026-10 之前完成的几本（`人间清醒恋爱指南/`、`学会闲聊/`、`我们为何无聊/`、`爱情心理学/`）原本各自带 `第00章-序言` 之类的篇目，现已按同一规则处理：删掉该篇，要点并入各自入口文件的「关于开篇」段。
- `00-inbox` 强调它是流程入口而非长期存放区；它**进 git**，所以含隐私的生活草稿不要放这里（§10）。
- **空目录用「与目录同名的说明笔记」占位，不用 `.gitkeep`**：Remotely Save 不同步以 `.` 开头的路径，并会清理因此变空的目录（实测把 6 个只有 `.gitkeep` 的目录删没了）。改用可见的目录说明笔记后，目录既进得了 git，又能被正常同步，还顺带起导航作用（§9.1）。**命名规则见 §4「目录说明笔记」条**。
- **目录说明笔记的命名，`91-attachments/external/` 是全库唯一例外**。该目录的内容（含放进去的说明笔记）被 `91-attachments/external/*` 整体忽略（§8.2），注释文件同样进不了 git，只有 `.gitkeep` 能靠 `!` 例外被保留 —— 所以它是全库唯一保留 `.gitkeep` 的目录。
- 目录名统一小写 ASCII，不含空格（Gitee 对含空格路径要求 URL 转义，直接避免）。**书籍拆解目录与其内的全部文件是唯一例外**：直接用中文，目录名与入口文件名一致（`20-life/爱情心理学/爱情心理学.md`），章节文件为 `第NN章-<中文标题>.md`。

## 4. 命名规范

- **文件名与目录名一律不含空格**：需要分词时用连字符 `-` 或下划线 `_` 分隔，绝不留空格。空格在 Gitee 上必须写成 `%20`（§7.1 第 2 条），在命令行、同步工具与跨平台脚本里也都是隐患；新增时就写对，比事后改名（会让既有链接失效）便宜得多。示例：`30-reading/CUDA_C编程权威指南/CUDA_C编程权威指南.md`。**唯一例外**是 `91-attachments/external/` 下的外部资料：它们是下载来的原始文件名（含空格、括号、版本号），改名会与来源对不上，保持原样（该目录不进 git，笔记里也只写纯文本路径，§7.1 第 5 条）。
- **白板（Canvas）以 `.canvas` 结尾，直接放它描述的域或主题目录里，文件名用中文**（如 `10-tech/技术域全景.canvas`）。Canvas 跟笔记一起进 git；Excalidraw 那种「图 + 导出」的成对文件仍留在 `91-attachments/excalidraw/`（§2）。**Canvas 的链接必须单独校验**：它不在 Markdown 的 `[x](y.md)` 语法里，`check-case.js` 覆盖不到，用 `91-attachments/tools/check-canvas.js` 跑（否则「断链 0」这个验收口径会被绕过）。画 Canvas 的原则是**只放真实存在的关系**——边的两端都要能在库里指出来源，不要为了好看连没关系的卡片。
- **目录说明笔记：文件名与所在目录同名**（2026-10-11 起，全库 16 个）。每个目录的说明笔记命名为 `<目录名>.md`——如 `10-tech/10-tech.md`、`10-tech/03-architecture/03-architecture.md`、`20-life/总结/总结.md`、`91-attachments/tools/tools.md`。**只有库根例外，仍叫 `README.md`**（它是全库的总规则，不属于任何一个目录）。这条规则与上面「书籍拆解目录名与入口文件同名」是**同一条**：**目录的入口文件始终与目录同名**，拆解目录用它当书的大纲，其余目录用它当目录说明。**判断标准**：看到一个目录，就该能猜到入口文件叫什么；反过来，`README.md` 这种「哪儿都叫一个名」的写法会让人分不清是哪一层的入口。
- **文件名**：中文（全库非 README 笔记的现行规则）。文件名取自笔记标题，只把标题里的 `：（）·` 等字符换成 `-`（如 `显存类型-GDDR-HBM-LPDDR.md`、`第01章-爱情究竟是什么.md`）；`CUDA`、`HIP`、`C11`、`SIMT`、`CMake` 这类业界习惯直接用英文的术语照旧保留；**目录说明笔记照目录名**（`01-concepts.md`）。链接里的中文会变成 percent-encoding，不影响跳转（§7.1 第 2 条）。
- **目录名**：一级目录沿用数字前缀 + 小写 ASCII（§3）：域目录用 `10` / `20` / `30`，域内目录从 `01` 起编号。域内目录的中文与否按「中文是否比 ASCII 更可读」判断 —— 技术域按知识形态分（`01-concepts`、`02-principles`），形态之内按知识领域分（`c`、`cpp`、`python`、`hip`、`make`），这些用 ASCII 更短、也更贴近领域惯例；书籍拆解目录则直接用中文书名（`20-life/爱情心理学/`），与入口文件同名。**具体层级与目录名以文件系统为准**，不在本文列举。
- **中文标题**靠 frontmatter 的 `title` 与 `aliases` 承担（`aliases: [CUDA 执行模型]`），搜索、双链、图谱都能命中中文。**文件名也直接用中文**（取自标题），代价是链接里会出现 percent-encoding（§7.1 第 2 条），换来的是文件浏览器与搜索结果里一眼可读。
- **禁止字符**：`\ / : * ? " < > | # ^ [ ]`、`%`，以及结尾的 `.` 与空格。`%` 尤其危险：它会和 percent-encoding 冲突，含 `%` 的文件名只能写成 `%25`。
- **一概念一文件**：同一概念的多种写法（显存 / VRAM / video memory）写进 `aliases`，不重复建笔记。
- **概念笔记与书籍拆解的分工**：整本书的拆解负责「忠实复述这本书讲了什么」；**成体系的概念**（占用率、合并访问、原子操作、延迟隐藏…）应当在 `10-tech/01-concepts/` 有独立笔记，拆解里用一句话 + 链接导流过去，避免同一套定义在多本书、多个章节里各写一遍。判断标准是「换个上下文还能不能独立成立」——能，就值得独立成篇。跨领域通用、但库内还没有对应笔记的术语，先汇入 `CUDA-术语速查` 一类的速查笔记，等它积累到能独立成篇时再拆出去。
- **时间型笔记**（排查记录、生活记录）把日期作为文件名前缀，如 `2026-09-25-Triton-编译报错.md`；概念类笔记不把日期写进文件名，更新靠 frontmatter 的 `updated`。
- **两个域共用同一套命名规范**：生活域同样用中文文件名 + 中文标题进 `title`/`aliases`，如 `20-life/睡眠与咖啡因.md`（`aliases: [Sleep and Caffeine]`）。
- **笔记语言**：正文中文为主；专有名词、API、命令、代码标识符保留英文原形，首次出现时中英对照，如「写合并（write coalescing）」、「页表（page table）」。业界习惯直接用英文的术语不要硬译（`warp`、`SM`、`PagedAttention`）。

## 5. 元数据规范（frontmatter）

```yaml
---
title: CUDA 执行模型
aliases: [CUDA 执行模型, CUDA Execution Model, SIMT]
tags: [lang/cuda, form/concept, hw/thread-hierarchy]
created: 2026-09-25
updated: 2026-09-25
status: growing        # inbox | seed | growing | evergreen | archived
source:                # 可选，原文或文档链接
---
```

| 字段 | 必填 | 说明 |
|---|---|---|
| `title` | 是 | 中文可读标题，与正文 H1 一致 |
| `aliases` | 是 | 中英别名、同义词、缩写；双链与搜索的第二入口 |
| `tags` | 是 | 只能取自下面的命名空间 |
| `created` / `updated` | 是 | `updated` 每次实质修改都要改 |
| `status` | 是 | 见下表的**可验证判据**（2026-10-11 起按结构信号判定，不再靠手感） |
| `source` | 否 | 外部资料来源 |

**自由文本值必须加引号**：值里含 `: `（英文冒号加空格）、`#`、`{`、`[`、`>`、`|`、`&`，或以 `*` 开头时，整段用单引号包住，如 `source: '…原书 Out of My Skull: The Psychology of Boredom…'`。漏引号的代价是**整段 frontmatter 解析失败**：Obsidian 属性面板会把该笔记的所有属性显示为无效，Linter 的 YAML 规则（§8.3）也随之失效。

**标签命名空间**（**受控词表**，只允许这些前缀与二级名，防止 `cuda` / `CUDA` / `cuda编程` 这类碎片化）。**技术域与阅读区的二级名也是受控的** —— 2026-10 治理过一次：合并同义标签、拆细 `read/`、把主题标签从 `meta/` 搬出、收窄 `os/linux`：

| 前缀 | 用途 | 二级名 |
| --- | --- | --- |
| `hw/` | 硬件 | `gpu-arch`、`memory-hierarchy`、`thread-hierarchy`、`computer-arch` |
| `os/` | 操作系统 | `linux`、`driver`、`memory`、`network`、`fs`、`scheduler`、`ipc`、`security` |
| `lang/` | 语言与运行时 | `cuda`、`hip`、`c`、`cpp`、`python`、`bash` |
| `fw/` | 框架与引擎 | `pytorch`、`vllm` |
| `perf/` | 性能 | `profiling`、`kernel-opt`、`inference-opt` |
| `tool/` | 工具链 | `build`、`make`、`cmake`、`gdb`、`debug`、`rocm`、`nsight`、`onnx`、`tensorrt`、`knowledge-base` |
| `ai/` | AI 主题（2026-10 新增） | `llm`、`multimodal`、`ml`、`framework` |
| `form/` | 知识形态 | `concept`、`spec`、`arch`、`pattern`、`troubleshoot`、`case-study`、`reference` |
| `read/` | 阅读笔记（`30-reading/` 专用，**只用于非生活类书籍**） | `textbook`（形态）+ **领域二级**：`os`、`arch`、`ai`、`cs`、`gpu`、`learning`、`compilers` |
| `life/` | 个人生活（`20-life/` 专用，**二级自由命名**，不设受控清单） | `psychology`、`relationship`、`health`、`sleep`、`communication` 等 |
| `meta/` | **库自身管理**（只描述库本身，不参与知识筛选） | `plan`、`directory-note`、`knowledge-base` |

四条维护规则：

- `form/*` 与目录看似冗余，但它是唯一能跨目录筛选「只看概念类笔记」的手段，保留。
- **主题标签一律不进 `meta/`**：`meta/` 只描述库本身（规划、目录说明、知识库方法）。原先误放在那里的 AI 主题标签（`meta/ai` 33 次、`meta/ml` 8 次）已于 2026-10 迁到 `ai/` 前缀下。
- **`os/linux` 的含义已收窄**为「**Linux 平台/发行版相关的机制与工具**」，它**不是**「操作系统主题」的泛称：跨系统教材（如《现代操作系统》）的章节改用 `os/memory`、`os/scheduler`、`os/fs`、`os/ipc`、`os/security` 这些**主题**标签。治理前它覆盖 63 篇（含 CS:APP 全书），治理后为 25 篇。
- **`read/` 用「形态 + 领域」两级**：`read/textbook` 标识「这是教材拆解」，领域二级（`read/os`、`read/ai`…）才承担筛选职责 —— 只用 `read/textbook` 时 138 篇毫无区分度。
- `life/*` 的二级名不预设清单，代价是可能长出同义标签（`life/sleep`、`life/rest`）。代价用治理抵掉：二级名一律小写 ASCII，且每月维护时合并同义标签（§11）。
- **生活域笔记不强制带 `form/*`**——它的目录分层已经够粗，形态标签在以域为第一层的结构里是冗余的。
- **`form/summary` 已废弃（2026-10-11 全库移除，469 处）**：它被当成「拆解页」的通用标记，实际覆盖 432 篇章节页 + 33 篇入口页，等于常量——常量标签既不带区分度也不带信息，而拆解页的身份已由 `read/textbook` + 目录天然表达。判断标准：**一个标签若被全库 10% 以上的笔记使用且不区分任何东西，就该删掉或重打**。

**`status` 的判据**（2026-10-11 起，脚本可复现；`91-attachments/tools/fix-frontmatter.js`）：

| 取值 | 判据（可验证） |
| --- | --- |
| `inbox` | 收件箱草稿（§10 的 7 天规则约束） |
| `seed` | 明确未完成，或还没接进任何笔记（0 入链） |
| `growing` | 结构完整但**未经校对**：拆解章节页以「本书顺序导航链内部一致」为准；书入口页链一致但无校对痕迹；目录说明页；独立笔记（体量 ≥ 4 KB 且有入链） |
| `evergreen` | **章节齐全 + 入口页带校对痕迹**（「存疑点 / 拆解校验」小节）的整本书拆解。这是强断言，不要滥用 |

`90-templates/` 的模板一律留 `seed`（模板本就该是骨架）。当前全库：`growing` 615、`evergreen` 4、`seed` 4（模板），见 `10-tech/06-summary/库状态.md`。

## 6. Markdown 风格规范

风格由 Linter 插件自动落地：`lintOnSave` 已开启，保存即格式化并弹出改动提示；规则清单见 §8.3。本节区分哪些交给插件、哪些必须人工。

**插件自动强制**：

- 标题层级不跳级（`header-increment`）；标题前后、frontmatter 之后各留一个空行（`heading-blank-lines`）。
- 列表标记统一为 `-`，`*` 与 `+` 会被改写（`unordered-list-style`、`convert-bullet-list-markers`）；`-` 后一个空格（`space-after-list-markers`）。
- 去掉行尾空格（`trailing-spaces`）；连续空行压成一个（`consecutive-blank-lines`）；段落之间一个空行（`paragraph-blank-lines`）；文件末尾一个换行（`line-break-at-document-end`）。
- 代码块、表格、引用块、水平线、数学块前后各留一个空行（`empty-line-around-*`）。
- 加粗与斜体标记在同一文件内保持一致（`strong-style`、`emphasis-style`）；引用块统一 `> `（`blockquote-style`）。
- frontmatter 的 `tags`、`aliases` 写成单行数组并去重（`format-yaml-array`、`format-tags-in-yaml`、`dedupe-yaml-array-values`）。
- 中文与英文、数字之间补一个空格：`CUDA 编程模型`、`8 卡`（`space-between-chinese-japanese-or-korean-and-english-or-numbers`）。

**必须人工把关**（自动改写会误伤，对应规则在 §8.3 保持关闭）：

- 每篇一个 H1，内容与 `title` 一致；标题层级不跳级，小节一律用 `##`/`###` 标题，不要用加粗行代替标题。自动把 H1 对齐文件名（`file-name-heading`）或把标题改成 Title Case（`capitalize-headings`）都会破坏中文标题，两条规则关闭。
- **代码块必须标语言**：`cuda`、`cpp`、`python`、`bash`、`hip`、`opencl`；命令与输出分开写，输出用 `text`。GPU 笔记里代码占比极高，这是最值得强制的规则，但语言只能人工判断 —— 自动补 `text`（`default-language-for-code-fences`）会把本该标 `cuda` 的块也糊成 `text`，掩盖疏漏，故关闭。
- 行内代码、路径、API 名、寄存器名一律用反引号，如 `__syncthreads()`。
- **段落内不换行，段间空一行**。本库 `strictLineBreaks: true`，随意的软换行会渲染成真实换行，导致段落被切碎。
- 列表统一用 `-`，嵌套缩进 2 空格。
- 空列表项写 `-`，留作待补充的占位（`remove-empty-list-markers` 保持关闭）；空字段不留尾随空格。
- 表格只用于对比，不用来排版。
- 数学公式用 LaTeX 包裹：行内写 `$...$`，独立成行的写 `$$...$$`（顶格）。Obsidian 原生渲染；Gitee 网页端加载了 MathJax，`$...$` 与 `$$...$$` 两端显示一致。
- 图示一律用 Excalidraw 画（插件已开启自动导出 SVG）：源文件 `*.excalidraw.md` 与导出的 `*.excalidraw.svg` 都落在 `91-attachments/excalidraw/`。导出名是「源文件名去掉最后的 `.md`」，即 `foo.excalidraw.md` 对应 `foo.excalidraw.svg`；笔记里用 Markdown 图片链接引用 SVG（相对层级随笔记所在目录变化），这样 Obsidian 与 Gitee 都能显示。需要纯文本、可 diff 的结构图时，也可以用 Mermaid 代码块（Gitee 自 2022 年起支持渲染）。展示真实软件界面或硬件时才用截图，按 §7.1 落进 `91-attachments/assets/`（生活笔记的截图落 `91-attachments/personal/`）。
- **API 介绍必须写全三件事**：**签名与逐个参数的含义**、**使用场景**、**可直接编译的最小示例**。
  - 参数说明写成**标准 C++ 注释**（Doxygen 风格：`@brief`、`@param[in]`、`@param[out]`、`@return`、`@note`、`@warning`），与签名一起放进代码块；**不要用表格逐列罗列参数**。表格只留给「函数名 + 一句话用途」的速查索引，且不能代替介绍。
  - 示例要能独立编译，必要时补上变量声明与错误检查。
- 术语首次出现给中英对照（§4）。

## 7. 链接与导航

### 7.1 链接形式：Markdown 链接

本库使用 **Markdown 链接** `[显示文本](相对路径)`，即 `.obsidian/app.json` 保持 `"useMarkdownLinks": true`、`"newLinkFormat": "relative"`、`"alwaysUpdateLinks": true`。

**理由**：备份推到 Gitee 后，Markdown 链接在网页端能直接点开阅读，wikilink（`[[...]]`）在 Gitee 的渲染器里不会被解析成有效链接。代价是移动/重命名文件后要确认链接仍然正确（`alwaysUpdateLinks` 承担大部分工作，但跨目录批量搬动后仍需抽查）。

**Gitee 兼容的写法细则**（Gitee 支持仓库内相对路径，会自动解析为 raw 地址，但有以下前提）：

1. 链接目标一律用 `/` 分隔的相对路径，**不写 Windows 反斜杠**；反斜杠是 Gitee 图片与链接失效的头号原因。
2. 链接目标中的空格必须写成 `%20`。目录名一律 ASCII 无空格（§3），文件名则用中文（§4），因此指向文件的链接会带 `%E4...` 这类 percent-encoding —— 这是预期写法，Obsidian 与 Gitee 都能正确解析。**新文件名不要含空格**，否则在 Gitee 上必须写成 `%20`。
3. 只链接到文件，**不链接到小节锚点**（`#标题`）。中文标题生成的锚点在 Gitee 上不稳，跨平台引用一律指向文件本身，读者自己找小节。
4. 图片用同样的相对路径写法，但落点按域分：
   - `10-tech/` 与 `30-reading/` 的图片一律进 `91-attachments/assets/`，如 `![说明](../../91-attachments/assets/xxx.png)`，并且图片必须真的提交进仓库——`assets` 已纳入 git 正是为此；若图片被 `.gitignore` 排除，Gitee 上必然裂图。
   - `20-life/` 的图片一律进 `91-attachments/personal/`（不进 git，见 §8.1）；它在 Gitee 上必然不可见，那是刻意为之。
5. **不要给不进 git 的路径写链接**：`91-attachments/external/`、`91-attachments/personal/`、`20-life/` 都不进 git，Gitee 上一定 404。这类本地资料统一放在文末「本地资料」小节，写纯文本路径（不加链接语法），例如 `- 91-attachments/external/vllm-paper.pdf`。
6. 反向链接照常可用：Obsidian 会为 Markdown 链接建立反链并计入图谱，双向链接能力不受影响；只是显示文本不会随文件名自动更新（与 wikilink 的唯一实质差别）。
7. **跨域链接单向**：`10-tech/` 与 `30-reading/` 的笔记**不要**链到 `20-life/`——本地能跳，但 Gitee 上没有该目录，网页端必然 404，等于主动往公开库推断链。`20-life/` 的笔记可以自由链回 `10-tech/`、`30-reading/`、`91-attachments/`。**生活域内部可以自由互链**——这些链接只在本地 Obsidian 里生效。
8. 图谱与反链是本地功能：`20-life/` 不进 git，它的反链与图谱关系在新设备上要等 Remotely Save 同步完成才完整；刚 clone 的当天别急着判定「某篇笔记是孤岛」。

**已实测**：在 Gitee 公开库上相对路径链接可跳转；`91-attachments/assets/` 下的图片正常渲染（raw 返回 200 且字节数与本地一致）；`91-attachments/external/` 下的文件返回 404，与第 5 条一致。

### 7.2 主题导航：分层索引 + 标签 + 图谱

**索引页按「层」建，不按「篇」建。** 跨域、跨目录的主题聚合仍以 Obsidian 原生能力（标签、图谱）为主，但**每一层应当有且只有一个索引页** —— 因为标签检索要求你先知道要搜什么，而图谱在数百个节点上已经看不出簇结构：

| 层级 | 是否建索引 | 形式 |
|---|---|---|
| **域**（`10-tech`、`20-life`、`30-reading`） | **建**（域说明笔记，与目录同名，如 `10-tech.md`） | 域规则 + **按主题分组的**书目清单 |
| **知识形态层**（`01-concepts/` 等） | **建一个** | 按主题簇分组的清单，每篇一句话；**不做二次摘要**，避免维护成本 |
| **语言/平台层**（`c/`、`cpp/`、`python/`…） | 不建 | 由 `C99-总览`、`C++11-总览` 这类总览笔记承担 |
| **单篇笔记** | **不建 MOC** | 靠 frontmatter 标签 + 文末「相关笔记」段 |

1. **标签**：每篇笔记在 frontmatter 带主题标签（§5），用标签面板或搜索 `tag:#lang/cuda` 列出某主题的全部笔记。
2. **图谱**：新笔记必须至少链到 1 篇既有笔记，否则图谱里就是孤岛。
3. 月度维护时用图谱视图清理「0 入链 0 出链」的笔记。

**书籍拆解的两条例外**：① 整本书的拆解是线性内容，读者需要按顺序读，因此逐章文件自带「上一篇 / 下一篇 / 返回大纲」的顺序链（§3），与目录同名的入口文件同时承担进入这条链的入口；② 每个入口页另有「**相关阅读**」表，指向**同主题的其他书**并写清关联点。

**横向边是硬要求。** 新增一本书时必须同时做三件事：(a) 在所属域索引页的**主题分组**里定位它；(b) 至少在一本相邻书的「相关阅读」表里补上**双向**入口；(c) 在库根跑 `node 91-attachments/tools/sync-same-topic.js . --write`，把那张表同步成每个章节页文末的「同主题其他书与相关笔记」小节。理由是库越大越容易变成「一排互不相识的书架」——数据与做法见 `10-tech/06-summary/知识库现状与网络化方案.md`（第 1 批与第 5 批）。

**章节页脚注由脚本持有，不要手改。** 脚注夹在 `<!-- same-topic:begin -->` 与 `<!-- same-topic:end -->` 之间，内容从入口页的「## 相关阅读」表派生，重复运行是幂等的；要增删关联只改入口页那张表。新增拆解后忘了跑脚本，`audit-kb.js` 的第九节会把缺脚注的章节页列出来。

### 7.3 外部资料

文末固定「参考」小节，格式：`- [标题](URL)`，不写访问日期 —— 链接本身就是出处。收集的文章同样要留原文链接，避免来源丢失。

## 8. 附件与体积策略

### 8.1 附件分五类管

| 目录 | 内容 | git | Remotely Save | Gitee 网页 |
|---|---|---|---|---|
| `91-attachments/assets/` | 技术域与阅读区的图片、drawio、截图 | **纳入** | 纳入 | 可见、可显示 |
| `91-attachments/excalidraw/` | Excalidraw 源文件与导出的 SVG | **纳入** | 纳入 | 可见、可显示 |
| `91-attachments/tools/` | **库自身的维护脚本**（PDF 探查/提取、清洗切分、链接校验、全库审计）与 `package.json` | **排除**（本机专用、不做备份，见 §8.2） | 纳入 | 不可见 |
| `91-attachments/external/` | PDF、论文、网页存档、压缩包 | **排除** | 纳入 | 不可见（链接必然 404） |
| `91-attachments/personal/` | 生活域笔记的图片与附件 | **排除** | 纳入 | 不可见（链接必然 404） |

划分依据三条，记住即可，不必展开：

- **图片必须进 git**：图片是笔记正文的一部分，一旦排除，新设备 clone 后全部笔记裂图；图片体积小、数量可控。
- **外部资料必须排除**：Gitee 社区版配额是单仓库 500 MB、单文件 50 MB、账号总容量 5 GB（[配额说明](https://help.gitee.com/questions/Gitee%E4%BA%A7%E5%93%81%E9%85%8D%E9%A2%9D%E8%AF%B4%E6%98%8E)）。几篇 PDF 就能撑爆单仓库上限，之后 Gitee 会锁定推送。它不进 git，但仍由 Remotely Save 推到其它设备，所以在 Obsidian 里能正常打开。
- **生活域附件必须排除**：笔记与图片是同一份隐私，只排除笔记等于从另一条路把隐私推到公开仓库（`assets` 没有访问控制，公开库还会被搜索引擎索引）。
- **维护脚本不进 git、也不做备份**：`91-attachments/tools/` 是本机专用的工具（拆解流水线与校验脚本），**只有这一台机器上有**——它不在 git 里、不在 Gitee 上、不在 Remotely Save 的任何其它设备上。这是刻意的决定，理由见 §8.2。脚本的用法见该目录的 `tools.md`；**注意：换机器或重装系统后需要自己重建这套工具**（笔记与附件不受影响）。

**插图的目录是手工选的**：Obsidian 的 `attachmentFolderPath` 是全局设置（当前为 `91-attachments/assets`），不能按目录分流。因此生活笔记插图时要把附件改到 `91-attachments/personal/`，或插入后立即移动过去。这是生活域唯一的手工步骤，在 §11 的月度检查里复核一次。

**不可逆提醒**：git 历史会永久保留已提交的二进制，事后加 `.gitignore` 不会缩小仓库。所以落地顺序是「先写 `.gitignore`，再首次提交」；若已经提交过，需要 `git rm --cached`，仓库已超限时还要用 `git-repo-clean` 改写历史。

### 8.2 `.gitignore`

```gitignore
# Obsidian 本地状态（高频写入，冲突之源）
.obsidian/workspace.json
.obsidian/workspace-mobile.json
.obsidian/workspace*.json
.trash/
.DS_Store
Thumbs.db
.reasonix/

# meow-memory 插件的本地记忆库（含隐私，且误删不可恢复，不进公开仓）
.dsh-meow/

# 插件配置里的凭据：公开仓库绝不能带（Remotely Save 的 data.json 保存后端密钥）
.obsidian/plugins/remotely-save/data.json
# Excalidraw 的 data.json 带 apiKey / taskboneAPIkey 字段（当前均为空），一旦填入即成为凭据
.obsidian/plugins/obsidian-excalidraw-plugin/data.json

# 附件：只把技术域与阅读区的图片纳入 git，收集的文章与 PDF 不入库
# 注意必须写成 external/* 再例外 .gitkeep：父目录被整体忽略后，无法用 ! 重新包含其内文件
91-attachments/external/*
!91-attachments/external/.gitkeep
*.pdf
*.epub
*.djvu
*.zip
*.7z

# 生活域：含隐私，公开仓库不能带（笔记、附件与目录说明一起排除，不留例外）
20-life/*
91-attachments/personal/*

# Excalidraw 的插件资源：CJK 字体体积大，可重新下载，不入库
91-attachments/excalidraw/CJK Fonts/
91-attachments/tools/
```

- `.obsidian/` 其余内容（`app.json`、`community-plugins.json`、插件目录、主题、snippets）纳入 git，用于多端配置一致；只排除 `workspace*.json`，它记录窗口布局与光标位置，每台设备每秒都在改，是合并冲突的头号来源。
- **`91-attachments/tools/` 是被刻意排除的，不是遗漏**（真实 `.gitignore` 的最后一行）：整个目录不进公开仓，也不做任何备份——所以这套脚本**只有本机一份**。这样选是因为脚本与笔记正文不是同一类东西，不该出现在公开仓里；代价是换机器要自己重建。若哪天改主意要留一份副本，删掉 `.gitignore` 里那一行再提交即可。
- `.trash/` 必须排除：被 git 跟踪后，本机删掉的笔记会在 pull 时被「复活」。
- **`91-attachments/external/` 是 `.gitkeep` 占位的唯一例外**：该目录下的一切都被整体忽略，因此 §3 的「目录说明笔记占位」方案在这里失效 —— 只有用 `!` 单独例外的 `.gitkeep` 才能让这个目录本身入库。规则生效的前提是**先整体忽略、再例外**。
- `remotely-save` 插件目录里自带一个只含 `data.json` 的 `.gitignore`，与根 `.gitignore` 的那条规则构成双保险。

**生活域的排除要能自查**（别只靠记忆）：新建生活笔记或往里放图片之后跑一次——

```powershell
git check-ignore -v 20-life/example.md 91-attachments/personal/example.png
git status --short --untracked-files=all | Select-String '20-life|personal'
```

前一条应命中 `.gitignore` 里的对应规则（输出形如 `.gitignore:20-life/*`）；后一条**不应输出任何内容**。真出现了，说明规则被写坏：把目录整体忽略（`20-life/*`）之后就不能再用 `!` 把其中的某个文件捞回来。

### 8.3 `.gitattributes` 与 Linter 规则配置

```gitattributes
* text=auto eol=lf
*.md     text eol=lf
*.png    binary
*.jpg    binary
*.jpeg   binary
*.gif    binary
*.drawio text eol=lf
```

多端在 Windows/Linux/mac 之间切换时，CRLF 与 LF 混用会产生满屏「幽灵 diff」，把真实改动埋掉，因此强制 LF。

Markdown 风格由 Linter 插件落地（§6）。配置存于 `.obsidian/plugins/obsidian-linter/data.json`，随 `.obsidian/` 入库（§8.2），多端一致；该文件不含凭据，无需加进 `.gitignore`。已开启 22 条规则，关键项与 §6 的对应关系：

| 规则 | 设置 | 作用 |
|---|---|---|
| `header-increment` | 开启 | 标题层级不跳级 |
| `heading-blank-lines` | 开启（`bottom`、`empty-line-after-yaml`） | 标题前后、frontmatter 之后留空行 |
| `unordered-list-style` | 开启（`list-style: "-"`） | 列表标记统一 `-` |
| `convert-bullet-list-markers` | 开启 | `*`、`+` 列表转 `-` |
| `space-after-list-markers` | 开启 | `-` 之后一个空格 |
| `ordered-list-style` | 开启（`ascending`） | 有序列表按 `1.` `2.` `3.` 编号 |
| `trailing-spaces` | 开启（`two-space-line-break: false`） | 去行尾空格，不做两空格硬换行 |
| `consecutive-blank-lines` | 开启 | 连续空行压成一个 |
| `paragraph-blank-lines` | 开启 | 段落之间一个空行 |
| `line-break-at-document-end` | 开启 | 文件末尾一个换行 |
| `empty-line-around-*`（代码块、表格、引用、水平线、数学块） | 开启 | 各类块级元素前后留空行 |
| `strong-style`、`emphasis-style`、`blockquote-style` | 开启（`consistent`、`space`） | 加粗与斜体风格一致，引用块统一 `> ` |
| `format-yaml-array`、`format-tags-in-yaml`、`dedupe-yaml-array-values` | 开启（单行数组） | frontmatter 的 `tags`、`aliases` 写法与去重 |
| `space-between-chinese-japanese-or-korean-and-english-or-numbers` | 开启 | 中文与英文、数字之间加空格 |
| `remove-empty-list-markers` | **关闭** | 保留空列表项 `-` 作占位 |
| `default-language-for-code-fences` | **关闭** | 代码块语言由人工判断，不自动补 `text` |
| `file-name-heading`、`capitalize-headings` | **关闭** | 中文标题与 H1 不被自动改写 |
| `yaml-title`、`yaml-timestamp` | **关闭** | `title`、`created`、`updated` 手填（§5） |

触发与执行：`lintOnSave: true`，保存笔记即格式化；`lintOnFileChange` 保持关闭，避免打字过程中反复改动光标位置。批量整理用命令面板的 **Lint all files in the vault**。

`91-attachments/excalidraw` 已加入 `foldersToIgnore`：Excalidraw 文档的 `## Text Elements` 段对空行敏感，标题空行规则会把它改坏 —— 插件作者明确建议不要用其它插件 lint 这类文件。

## 9. 同步与备份

**分工原则：Remotely Save 管实时同步，git 管历史备份，同一时刻只有一套机制在自动写库。** 两套工具同时改同一个库会产生重复文件、反复冲突甚至误删。

### 9.1 多端同步：Remotely Save

- 插件：**Remotely Save**（社区插件，已安装并配置）。
- **后端**：S3 兼容存储（Cloudflare R2 / 阿里 OSS）。选它的理由是可以**在桶上开版本控制**，给生活域多一层回溯（§9.3）；代价是国内直连 R2 的延迟与 OSS 的流量费用，按用量评估。
- **同步范围**：全部笔记（含 `20-life/`）+ `90-templates/` + `91-attachments/`（含 `external` 与 `personal`，否则 PDF 与生活域图片在其它设备打不开）。**`20-life/` 绝不能被忽略规则排除**——它是生活域唯一的副本机制（§9.3）。
- **不要开启 Sync Config Dir**（同步 `.obsidian`）：该功能是实验性的，且 `community-plugins.json` 等文件被 Obsidian 持续重写，多端同时同步会互相覆盖插件配置。`.obsidian` 交给 git 保证一致性。
- **不要启用 Skip Large Files**，否则 `external` 里的大 PDF 会被静默跳过、跨端缺失；若要设阈值，必须大于最大 PDF 的体积。
- 忽略规则是黑名单正则：多个负向先行断言（`^(?!AAA\/).*`）叠加会过滤掉一切，要合并成单条 `^(?!(AAA|BBB)\/)`。
- 多端冲突时会生成冲突副本文件，需手工比对合并；同一篇笔记避免多台设备同时编辑。
- **移动端不要用 obsidian-git**：其移动端基于 isomorphic-git，大仓库上易卡死或崩溃，且不支持 SSH；移动端只走 Remotely Save。
- **`.gitkeep` 会被它清掉，别用它给空目录占位**：Remotely Save 不处理任何以 `.` 开头的路径，于是「只含 `.gitkeep` 的目录」在它眼里就是空目录，会被清理。空目录一律改用可见的**与目录同名的说明笔记**占位（§3）；提交前若发现 `.gitkeep` 的删除记录，先判断是不是被同步清掉的。
- `.git` 目录无需担心：Remotely Save 不处理以 `.` 开头的路径。若想显式保险，在忽略规则里加 `^\.git/`。

### 9.2 git 备份到 Gitee

```bash
git add .
git commit -m "<说明>"
git push
```

- 仓库是**技术域公开**的（§0 决策 7）：`.obsidian/`、`10-tech/`、`30-reading/`、`91-attachments/assets`、`91-attachments/excalidraw` 与本文档任何人都能读取；**`20-life/` 与 `91-attachments/personal/` 不在这个公开副本里**。两边都要守住 §9.4 的纪律。
- **push 之前扫一眼 `git status`**：待提交列表里一旦出现 `20-life/` 或 `91-attachments/personal/` 下的文件，说明 `.gitignore` 失效，先别推（自查命令见 §8.2）。
- **git 全程手动提交，不设定时自动化**：`autoSaveInterval`、`autoPushInterval`、`autoPullInterval` 都保持 `0`，写入时机由你掌握。**代理（AI 助手）不得提交**，改动留给人工审阅后手动提交。
- 保留 `autoPullOnBoot`（开机先拉一次）与 `pullBeforePush`（推送前先拉）：两项都不产生提交，只是让手动推送不易被 `non-fast-forward` 拒绝。
- 一次做完提交、拉取、推送：命令面板的 **Commit-and-sync**；提交完想顺手关掉 Obsidian，用 **Commit-and-sync and close**（可绑快捷键）。
- 与 Remotely Save 共存时，**Pull → Merge strategy 必须选 "Other sync service"**（配置字段 `syncMethod: "reset"`）：pull 只移动 HEAD、不碰工作区文件，因为文件已由 Remotely Save 更新过。`merge`、`rebase` 都会自己改写工作区，与 Remotely Save 抢同一批文件，是会丢改动的组合。自查：`.obsidian/plugins/obsidian-git/data.json` 里的 `syncMethod` 应为 `reset`。
- 手动同步的顺序固定为「**先 pull，再 commit，再 push**」。
- 定期打 tag 做快照（如 `vault-202609`），便于回退到某个时间点。

### 9.3 风险与退路

- Remotely Save 是第三方插件，冲突处理靠生成冲突副本再手工合并，属其薄弱环节；一旦停止维护，退路是 Obsidian 官方 Sync 或 Syncthing。因此**不要把同步方案做成唯一副本**：git/Gitee 上的文本类内容始终是完整的第二副本（但 `external` 附件不在其中，重要 PDF 需另行冷备）。
- **生活域只有 Remotely Save 一份机制**——这是把隐私排除出公开仓库的直接代价：它不在 git 历史里，也不在 Gitee 上，插件一旦冲突处理出错或后端丢数据，生活域没有第二副本。三条最低要求：
  1. **把对象存储的版本控制打开**：S3 兼容后端默认不带版本历史，R2 与 OSS 的版本控制都要单独开启（OSS 默认关闭）。Remotely Save 自身的同步状态不能当备份。
  2. **每月打一次生活域冷备**：把 `20-life/` 与 `91-attachments/personal/` 打包（`Compress-Archive` 或 7-Zip）放到本机之外（NAS、移动硬盘、另一家云盘）；可以用密码加密，但**密码不要进库**。已列入 §11 的月度维护。
  3. **避免多端同时编辑同一篇生活笔记**：技术域还能靠 git diff 合并，生活域只能手工比对。

### 9.4 公开仓库与生活域的纪律

技术域公开意味着 `.obsidian/`、`10-tech/`、`30-reading/` 与本文档都能被任何人和搜索引擎读取（`20-life/` 不进 git，不在其中），因此有五条硬规则：

1. **凭据绝不进库**：token、密码、私钥、云盘 access key。特别提醒 **Remotely Save 的 `.obsidian/plugins/remotely-save/data.json` 会保存后端凭据**（WebDAV 密码、S3 secret key），已排除；换用其它后端或插件时同样要检查。
2. **每装一个插件就扫一次它的配置**：

   ```powershell
   Select-String -Path .obsidian/plugins/*/data.json -Pattern '(?i)(password|passwd|secret|token|api[_-]?key|access[_-]?key|username)'
   ```

   命中即说明该 `data.json` 含凭据，把它加进 `.gitignore`。当前状态：`obsidian-excalidraw-plugin/data.json` 命中（`taskboneAPIkey`、`aiProviderProfiles/*/apiKey`，均为空值），已排除并 `git rm --cached`；`remotely-save/data.json` 未进过 git（插件自带 `.gitignore` 兜底）；`obsidian-git`、`obsidian-linter`、`obsidian-style-settings` 无命中，继续随 git 跟踪以保证多端配置一致。

3. **内容层面不要写**：公司内部系统名称与截图、内网主机名与 IP、未公开的产品信息、他人隐私。`91-attachments/external/` 里收集的文章多受版权保护，不进库正好。
4. **误交了敏感内容，删文件不够**：把文件从工作区删掉再提交，只解决「当前版本可见」，git 历史里仍能取到旧版本（公开仓库同样可读）。处置顺序是：① **立刻吊销或更换那个凭据**——最优先，且与是否改写历史无关；② 再用 `git-repo-clean` 或 `git filter-repo` 改写历史并强推。
5. **生活域的边界靠 `.gitignore` 维持，不靠自觉**：写生活笔记时不要图省事「先放到 `00-inbox/` 或 `10-tech/` 里再搬过去」——那两个地方进 git，一旦提交就永久留在公开历史里（第 4 条）。正确做法是直接在 `20-life/` 下新建，图片直接落 `91-attachments/personal/`。另外，Remotely Save 的后端若不是自己搭的盘，生活域内容就等同于交给了该服务方，选后端时把这点算进去（§9.1 §13）。

自查习惯：`git add` 之后先看 `git diff --cached`，确认没有陌生文件再提交；生活域内容另用 §8.2 的两条命令复核。

## 10. 收件箱生命周期

`00-inbox/` 的详细规则写在 [00-inbox 目录说明](00-inbox/00-inbox.md)（进 git、7 天规则、frontmatter 用 `status: inbox`）。本节只留要点：

- `00-inbox` 是唯一允许随手写的地方，frontmatter 用 `status: inbox`；它**进 git**，所以只能放可公开的草稿。
- **生活草稿不要进 `00-inbox`**：含隐私的内容直接在 `20-life/` 下新建（照样用 `status: inbox`），处置期限相同，只是不走公开的那条路。先把生活草稿写进收件箱再搬走，是这套规则里最容易犯、且最不可逆的错误（§9.4 第 5 条）。
- **7 天规则**：每篇收件箱笔记在 7 天内必须完成一次处置 —— 按 §2 的形态分层升级为 `10-tech/` 下的正式笔记、合并进既有笔记、或删除。不存在「长期留在收件箱」的选项。
- 每周固定时间清理（建议周五 30 分钟），用 dataview 或搜索 `status: inbox` 列出待办，两个域一起清。

## 11. 维护节奏

**探索产物的回填。** 日常对话、调研、排查中得出的**可复用结论**——一个对比表、一条取舍判断、一套排查步骤、一个被证伪的假设——应当在当次就落成笔记或并入既有笔记，**不要让它只留在对话历史里**。判据与 §4 的概念笔记分工一致：**换个上下文还能不能独立成立**，能，就值得落成笔记；再补一条「未来会不会再查一次」。落点按 §2 的形态分层选：概念与定义 → `10-tech/01-concepts/` 或既有笔记的相应小节；方法与流程 → 对应形态目录；排查结论 → troubleshoot 类笔记；与某本书相关 → 该书拆解笔记的相应小节。

这条针对的是**输出侧的漏损**。本库在「摄入」侧已经比较扎实（书籍拆解、概念提炼），真正容易丢的是聊出来却没写下来的东西。注意它与 §10 的区别——**§10 管的是「随手写的草稿」（7 天内处置），这条管的是「已经想清楚的结论」（当次落成）**；也不要求一步到位，先留下可追溯的结论与依据即可。

| 周期 | 动作 |
|---|---|
| 每次记笔记 | 填 frontmatter、打主题标签、代码块标语言、至少链到 1 篇既有笔记；生活域笔记直接落在 `20-life/`、图片落 `91-attachments/personal/` |
| 每次得出可复用结论 | **当次落成笔记或并入既有笔记**（见上），不等收件箱的 7 天周期 |
| 每周 | 清空收件箱（§10，含 `20-life/` 下的 `status: inbox`）、补反链、`git commit` |
| 每月 | `git tag vault-YYYYMM`（快照只含技术域与阅读区）；清理 0 入链/0 出链的孤立笔记；检查标签是否跑出命名空间并合并 `life/*` 同义标签；**打包一份生活域冷备**（§9.3）；用 §8.2 的命令复核生活域没进待提交列表 |
| 每季 | 合并重复笔记；重估目录（某主题 ≥ 15 篇时升二级目录） |

## 12. 模板

核心「模板」插件已启用，`90-templates/` 下已就位 4 个模板：`concept.md`、`spec.md`、`arch-analysis.md`、`troubleshoot.md`。它们是为技术域写的；生活域暂用 `concept.md` 起步（把 `tags` 改成 `life/*`、`status` 用 `seed`），是否单独建 `life.md` 见 §13。

模板使用约定：

- frontmatter 的 `title` 留空手填；正文 H1 写占位文本 `# 标题`，插入后替换为中文标题。不要用模板变量 `{{title}}`：它替换成的是 ASCII 文件名，与「H1 用中文标题」的规则（§4 §6）冲突。
- 骨架小节用 `##` 标题而非加粗行（§6）；空字段与空列表项不留尾随空格。
- `90-templates/` 已加入 Obsidian 的「已排除的文件」（`app.json` 的 `userIgnoreFilters`），模板不会混进搜索、图谱与反链。
- 新建笔记流程：插入模板 → 填 `title` 与 H1 → 填 `aliases`、`tags` → 挂上主题标签并至少链到 1 篇既有笔记。
- 模板本体与完整骨架见 `90-templates/` 下的对应文件（如 `concept.md` 的固定小节为「一句话定义 / 为什么重要 / 关键点 / 易混淆·对比 / 参考」）。

## 13. 待定决策

| 决策 | 选项 | 影响 |
|---|---|---|
| 生活域冷备方式 | 加密压缩包存 NAS / 7-Zip 加密 + 移动硬盘 / 云盘版本控制 | §9.3，决定生活域第二副本的强度 |
| 生活域模板 | 复用 `concept.md` / 新建 `90-templates/life.md` | §12，笔记量还小时不必建 |