学习知识的收录与编辑规范

这个知识库首先服务个人学习和复习，其次才追求类似公开技术文档的完整形式。用户主动问到一个技术概念，通常说明它已经出现在真实工作或学习路径中；只要知识通用、可以验证且没有敏感信息，就值得被积累。

积累不等于复制聊天。知识库保存的是问题背后的命令、概念、边界和使用方法，而不是对话措辞、任务时间线或一次性的项目细节。

默认收录规则

下面四个条件同时成立时，默认写入知识库：

属于通用开发知识：例如 Git、语言、框架、工具链、测试、架构或部署知识。
对个人学习有价值：用户主动询问或在任务中实际遇到，就足以证明这一点，不要求它必须高深或罕见。
能够验证：有官方文档、标准、源码、配置、聚焦测试或实际行为支持。
适合安全保存：不包含公司业务、私有代码、凭据、内部地址或可识别数据。

基础定义、单条命令、冷门参数、短比较和易错点都可以收录。只有以下情况跳过写入：

已经准确覆盖，而且新问题没有增加检索词、例子、区别或边界。
结论仍然无法验证。
内容只对当前任务成立，无法提炼出通用知识。
内容属于敏感信息、公司业务或单独维护的 Jimu/积木知识。

两层内容结构

知识不需要一开始就写成长文章。根据体量选择速记知识或专题文档。

层级	适合内容	写作目标
`note` 速记知识	命令、参数、定义、比较、陷阱、恢复方式	一眼能复习，搜索后能立即使用
`tutorial` 教程	第一次学习并建立基本能力	跟随练习获得一个完整结果
`how-to` 操作指南	已经理解基础，需要完成具体任务	按步骤解决问题并验证结果
`reference` 参考资料	需要快速确认一组准确事实	完整、稳定、可扫描
`explanation` 原理解释	想理解机制、关系和权衡	建立可迁移的心智模型

note 是个人学习库特有的轻量层。其余四类沿用 Diátaxis 的文档分类，用于内容已经足够完整的专题页面。

内容应该写到哪里

按以下顺序选择目标：

现有文章中已经有自然位置，就补充到对应章节。
原子知识不适合扩写文章，就追加到分类的速记页面，例如 knowledge/git/quick-notes.md。
分类还没有速记页面，在第一个合适知识点出现时创建，而不是预先生成空模板。
多条速记逐渐形成完整主题后，将它们升级为专题文章；速记页保留一句摘要和文章链接，避免维护两份全文。

不要为每个命令创建独立页面，也不要为了追求文章形式把一个简单事实扩写成几百字。

速记知识怎么写

速记条目只保留复习和应用需要的信息。推荐结构：

## `git command --option`

一句话说明它解决什么问题。

- **适合场景**：什么时候想到它。
- **关键用法**：最小可用命令或示例。
- **记忆点**：边界、易错点、撤销或恢复方式。
- **来源**：支持结论的官方资料或验证。

不是每条都必须拥有四个字段。例如一个概念比较可能更适合一张小表；一个布尔配置项可能只需要作用、默认行为和来源。验收重点是：

脱离原始会话仍然看得懂。
命令名、参数名和常用搜索词能够被全文搜索找到。
结论准确，没有省略会导致误用的重要条件。
能在几十秒内完成复习，而不是重新阅读一篇长文。

专题文档怎么写

内容涉及机制、多个关联概念或完整操作流程时，再采用专题结构。

原理解释通常适合：

问题背景 → 核心结论 → 心智模型 → 工作机制
→ 示例 → 权衡与边界 → 常见误解 → 验证方法

操作指南通常适合：

目标 → 前置条件 → 操作步骤与预期结果
→ 常见失败 → 完成验证 → 回滚或清理

教程应让学习者边做边获得反馈；参考资料应追求完整和可扫描，不承担长篇教学。专题页面发布前还应确认目标读者、阅读结果和内容范围。

验证与来源

证据优先级通常是：

与结论对应的实际运行行为和聚焦测试。
对应版本的源码与配置。
官方文档、标准或规范。
可信的一手技术资料。

来源应靠近它支持的知识点，不能只在页面末尾堆链接。实际测试只证明测试条件内的行为；官方文档只证明其明确描述的范围。若版本或环境会改变结论，应写清适用条件。

示例与脱敏

命令和代码使用最小、可复用的安全示例。
域名、路径、账号和数据使用公开值或占位符。
不保留与知识点无关的业务字段、日志和项目结构。
没有实际运行过的示例，不声称“已经运行验证”。
从具体故障中提炼知识时，只保留通用机制和安全的复现方式。

Frontmatter

速记页面示例：

---
title: Git 命令与易忘知识点
description: 按使用场景整理 Git 命令、参数和容易混淆的边界。
kind: note
audience: 希望快速复习 Git 行为和命令的开发者
lastVerified: "2026-08-31"
order: 3
---

专题页面将 kind 设置为 tutorial、how-to、reference 或 explanation。

audience 用一句话标明预期读者；分类首页可以省略。
lastVerified 只在本轮确实重新核验关键内容时填写或更新。
order 与同目录页面保持连续，不用它表达重要程度。
文件名使用简短的英文 kebab-case，并尽量保持 URL 稳定。

隐私与 Git 边界

禁止写入公司业务、内部域名、私有仓库地址、客户或员工数据、生产标识、API Key、Token、Cookie、密码、私钥和 .env 内容。Jimu/积木知识只进入单独的 Jimu 知识库。

知识维护只进行本地 Markdown 与站点编辑，所有改动保持未暂存。运行 pnpm check 检查内容结构；导航、渲染或站点行为变化时再运行 pnpm build。

方法来源

教程、操作指南、参考资料和原理解释的分类参考 Diátaxis 文档体系。note 速记知识是为个人持续积累和高效复习增加的轻量层。