知识库规范

这份文件是本库唯一权威的结构与写作约定。给人看的操作流程在 CONTRIBUTING.md，给 AI 的约束在 AGENTS.md，机器契约在 _schema/pages.json。三者冲突时以本文件为准。

一、内容怎么分

一个部门的知识库 = 四条内容线 + 管理页 + 记录。

线	放在	判断
学习	部门/<部门>/学习/	有先后顺序、要教人
参考	部门/<部门>/参考/	没有顺序、要查
项目	部门/<部门>/项目/	我们做出来的东西
经验	部门/<部门>/经验/	我们炸过的坑
记录	部门/<部门>/历史与交接/	人、设备、系统的变动
管理	部门根目录、各类 README	介绍自己、约定流程

目录名就是分类，不靠 type 猜位置。

什么时候开专题

一个工具或技术满足下面任意两条，就在 参考/ 下给它开一个专题目录，而不是硬塞进一页：

1. 一页写清楚要超过 2,500 字；
2. 有 3 个以上彼此独立的子问题（装、用、调、排、生态），读者常常只需要其中一段；
3. 各部分更新节奏不同——部署跟官方版本走，插件跟社区走，性能跟显卡走；
4. 内容会长期增加，不是一次写完就能收尾。

反例也要守住：SSH、反向代理、Git 这类一页讲透的，不要拆专题，拆开只会让读者来回跳。

专题形态固定：参考/<专题名>/，首页必须是 README.md（type: 管理），其余页面按阅读顺序编号 01-、02-，专题自己的图片放该目录下的 assets/。

二、页面类型与必填章节

type	用在哪	必填章节（逐字）
课程	学习/ 下的每一讲	一、学习目标 / 二、前置 / 三、正文 / 四、练习 / 五、验收标准 / 六、下一讲
参考	参考/ 下的每一页（含专题内）	一、这页讲什么 / 二、开始之前 / 三、动手做 / 四、做完怎么确认 / 五、卡住了怎么排查 / 六、为什么这样能成 / 七、边界与替代 / 八、官方资料
推荐	参考/ 下「建议使用的软件或技术」	一、什么场景用 / 二、为什么是它 / 三、怎么开始 / 四、代价与坑 / 五、什么情况别用 / 六、核实记录
项目	项目/ 下的每一页	一、项目目标 / 二、环境 / 三、复现步骤 / 四、成果 / 五、已知问题 / 六、用到的技术
经验	经验/ 下的每一页	一、现象 / 二、环境 / 三、原因 / 四、解决 / 五、验证 / 六、经验
记录	历史与交接/	自由
管理	部门介绍、招新介绍、职责与服务目录、各类索引 README、专题首页	自由；索引页表格由脚本生成

章节标题必须逐字出现、按上表顺序。某一节不适用时保留标题，正文写「不适用」和原因。

参考页这套骨架只管「怎么做成」，不管「这东西的全部原理」：原理能不讲就不讲，必须讲时嵌进对应步骤，或放进第六节让想了解的人按需读。

参考 类暂不进 sectionsEnforced——存量页面还在按旧五节结构，批量重排完成后再收紧强制。

推荐 比普通参考页多三条硬要求：① 必须标 推荐级别（必装/建议/可选）；② 必须点名同类产品、写清为什么没选它们；③ 必须写「什么情况别用」。写不出第三条，说明还没想清楚它适合谁。

三、front-matter

---
title: 文件与路径
type: 课程
部门: 终端服务部
维护人: publieople
更新: 2026-10-20
状态: 草稿                     # 草稿 | 可用 | 待修订
可见性: 公开                    # 公开 | 内部
难度: 入门                      # 入门 | 进阶 | 深入 | 待补
适用版本: Windows 11 24H2       # 没有版本概念写「不限」，不确定写「待补」
tags: [Windows, 文件系统, 路径]  # 选填
---

1. 永远必填 7 项：title、type、部门、维护人、更新、状态、可见性。
2. 难度、适用版本 在 课程/参考/推荐/项目 四类里必填，不确定写 待补。
3. 更新 只在内容真的变了时改，只改格式不算。
4. 状态: 待修订 表示「曾经可用、现在已知过时」——把过时变成看得见的状态。
5. 推荐级别 只在 type: 推荐 时必填，取值 必装/建议/可选，不许空着或写 待补。

四、一页怎么写

1. 第一段回答「什么时候需要看这篇」，让读者在一屏内决定读不读。
2. 必须能验收：课程写学完能亲手做出什么，项目写怎么算跑通，参考页写照着做会看到什么。
3. 单一来源：同一件事只在一页写正文，别处只放链接。
4. 一页一事：单页 800–2,000 字；课程页可到 2,500 字；装、配、排障这类操作页可到 3,500 字，再超就拆页或开专题。导航型页面（部门首页、学习路径、职责与服务目录）不受上限制约，但每一节都要指向具体页面。标题写场景，不写内部代号。
5. 命令要能原样粘贴，写清在哪台机器、什么权限、什么目录下执行。
6. 不编造：没验证的结论标「待验证」，缺的事实要么补齐、要么不写，不留「待补」占位符当内容。

内容质量的四条底线：能理解、能学习、能复现、能延续。项目页至少要能让人照着复现——环境版本、硬件型号、逐步操作、预期结果、怎么算成功。

五、表达

两套工具都只改表达，不改事实：humanizer-zh 管「像不像人写的」（空话、重复、模板腔），STC 管「像不像技术文档」（空壳动词、模糊量词、营销词）。顺序是先写顺、再按 STC 通读一遍。

照做：删空壳动词（「进行」「加以」）；「部分」「若干」这类要么给数字要么说清；禁「赋能」「打造」「一站式」「无缝」「沉淀」「闭环」等词；禁「让我们……」「标志着……」；结论先行；三项以上用列表；一步一个动作；风险提示先动作后后果；提醒只用「警告/注意/说明」三个标签。

不照做：不强制把「我们」改成「本部门」（复盘、招新这类页面「我们」就是叙述主体）；不按 40 字机械切句（读不完就拆两句）；不用「【待补：…】」占位符；保留直角引号「」，不改弯引号（STC 的 G17「引号必须用全角」与本库冲突，以本库为准）；两条能机械判定的规则（D1 代词主语、G7 口号式对比）已接进 CI，其余规则只在通读和审稿时手动跑。

复查：node skills/stc/tools/cli.mjs check docs/部门/终端服务部 --profile for-document。规则正文、词表与快照指纹在 skills/stc/。

六、命名与目录

1. 目录名、文件名用中文，与页面标题一致。
2. 有序线加序号：章节 01-Windows基础，讲次 01-文件与路径.md；无序线（参考、项目、经验）不加序号。序号留两位，方便中间插入。
3. 改名等于断链：改名前搜一遍全库引用，再跑 mkdocs build --strict。
4. 专题目录：参考/<专题名>/，首页 README.md，页名 01-、02- 按阅读顺序，专题自己的图片放目录下的 assets/。
5. 不再维护的整块内容直接删掉，git 历史里查得到；需要留证据的，在对应页面的「相关」或「历史」里写一句「某年某月删除了什么、为什么」。

七、索引、导航、校验

索引表写在各类 README 的一对标记之间，脚本只重写标记内的内容：

<!-- gen:index 课程 01-Windows基础 -->
| 名称 | 一句话 | 难度 | 状态 | 更新 |
| --- | --- | --- | --- | --- |
| _还没有页面_ | — | — | — | — |
<!-- /gen:index -->

专题索引有两种写法：<!-- gen:index 目录 参考 --> 把子目录当一行列出来（读专题的 README），<!-- gen:index 参考 参考/ComfyUI --> 列出该专题下的全部页面。

node scripts/gen-index.mjs     # 重写所有索引表
node scripts/gen-nav.mjs       # 重写 mkdocs.yml 的 nav 块、nav.片段.yml、SUMMARY.md
node scripts/check-pages.mjs   # 校验字段与章节，列出待补字段、待复核页面
node scripts/check-secrets.mjs # 扫凭据与内网信息
node scripts/check-stc.mjs     # 表达：代词主语、口号代替事实（按基线只拦新增）
npx markdownlint-cli2          # 格式
mkdocs build --strict          # 断链与构建

七道检查都在 CI 里跑，本地先跑一遍再提 PR。

check-stc.mjs 只拦 STC 的两条规则：D1（代词主语，正文用代词顶替明确名称）、G7（口号式对比句，拿对比代替直陈事实）。其余规则（引号、长句等）对本库语料误报太多，不进门禁，只在通读和审稿时手动跑 node skills/stc/tools/cli.mjs check <路径> --profile for-document。

存量按文件记在 .stc-baseline.json（当前 245 处，集中在待重排的旧页面），门禁只挡新增。把一个页面改干净后，跑一次 node scripts/check-stc.mjs --update 把基线压低，否则下一个人看不出这个文件已经清理过。

八、加一页

node scripts/new.mjs 课程 docs/部门/终端服务部/学习/01-Windows基础/03-环境变量
node scripts/gen-index.mjs
node scripts/gen-nav.mjs

new.mjs 按类型套模板、建目录、把 更新 填成今天。写完当场跑一次第七节的全部检查。

九、什么不能进库

• 内网 IP、设备名、域名、用户名一律用占位符；凭据、token、私钥永不入库。
• 未经核实的主观评价不当结论写；有争议的写清分歧和依据。
• 别人的整篇文档不整段搬运，需要时写摘要并给出原始链接与访问日期。