# 知识库

本项目是由 AI 协助整理和维护的知识库，通过文件夹组织主题，使用 Markdown 记录知识。所有知识库原文内容均归档于 docs/ 目录。

# 主题目录

# HTML 阅读页面

运行 npm install 安装依赖，再运行 npm run build，生成页面位于 dist/，首页为 dist/index.html。

页面顶部提供“跟随系统 / 浅色 / 深色”主题选择，默认跟随系统并响应系统配色变化。手动选择会在浏览器允许本地存储时保存；通过同一站点访问时可在页面间沿用。直接打开本地 HTML 文件时，偏好共享取决于浏览器对 file: 本地存储的支持。代码高亮随主题一起切换。

每个标题前的 # 可点击定位，地址栏会保留对应锚点；复制该地址或右键复制 # 链接，即可分享直达该标题的位置。打开带锚点的 HTML 链接时会自动定位。

# 自动导航

导航由 scripts/navigation.mjs 在构建时生成，Markdown 只维护正文和标题：

• 面包屑根据文件所在目录及各级 README.md 生成，链接文字取目标文档的一级标题。
• 目录页使用 <!-- navigation:children --> 指定目录位置；自动收集直属文章与子目录的 README.md，根首页展示 docs/ 下的主题。新增文档无需手写目录链接。
• 目录的自定义排序与说明集中在 scripts/navigation.json 的 catalog 中；未配置的文档按路径排序，追加在已有条目后。移动或删除已配置的文档时需同步修改配置，否则构建报错。
• 正文顶部和底部提供上下篇卡片与篇数位置，按主题下的编号章节、章内目录顺序连接，支持跨章继续阅读；维护文档和模板不进入顺读队列。精选导读顺序仍由 readingPaths 配置，通过独立的折叠入口跳读。
• 篇内目录从二、三级标题及其实际锚点生成，独立显示为无边框浮动侧栏，随滚动标记当前章节。宽度达到 1100px 时位于右侧并固定展开，不自动收起；较窄屏幕在右下角默认收起，通过与主题选择框一致的直角边框“篇内目录”按钮展开，按钮沿用页面背景色。窄屏下停止滚动且鼠标、键盘焦点均不在目录内时，闲置 3 秒自动收起；选择章节、点击外部或按 Escape 也会收起，入口始终保留。
• 左侧栏展示全库目录与当前文章，当前章节默认展开。宽度达到 1100px 时显示可收起侧栏并记住收起偏好；较窄屏幕使用默认关闭的抽屉，可通过关闭按钮、遮罩或 Escape 关闭。顶部目录按钮在滚动时保持可用。

这些导航仅出现在生成的 HTML 中；直接阅读 Markdown 时可通过文件目录定位文章。正文中的前置阅读、相关阅读和参考资料仍使用普通 Markdown 链接。

# 维护规范

知识库的维护原则、文档规范与提交要求参见 AGENTS.md。