第一库文档管理规范
0. 使用导航
这份文档现在同时承担 文档治理 区的总入口说明，不再额外拆一个薄 首页 或 目录 页面。
如果你是为了找资料，直接按下面进：
- 想看“第一库整体怎么管理” -> 继续看本文
- 想看 “MCP 应该怎么安装、收编、登记” ->
MCP 清单总表.md - 想看 “我现在能怎么写文档、出图、导 PDF、怎么下指令” -> 先遵循
C:\Users\ASUS-KL\.codex\AGENTS.md，维护说明见C:\Users\ASUS-KL\.codex\AGENTS.annotated.md
当前 文档治理 推荐理解为三份高信息密度主文档：
第一库文档管理规范MCP 清单总表全局 AGENTS 文档规则层
这三份承担的是 文档治理 入口与规则说明，不是项目 current-state 三件套。项目当前状态的唯一活入口仍是：
PROJECT-CONTEXT.mdSESSION-HANDOFF.mdplan.md
当前 canonical 路径：docs/agent/第一库文档管理规范.md。
目录结构上，根目录不再单独放空壳首页；导航信息并回到主文档里。
1. 当前结构判断
第一库 目前已经形成了较明显的主题分区，但还存在三个问题：
- 根目录仍有零散笔记，入口感不统一
- 部分目录已经工程化，部分目录仍是纯堆放式
- 文档、附件、脚本、导出产物之间的边界还不够明确
结合当前实际内容，建议把 第一库 视为一个“主题知识库 + 项目资料库 + 写作资料库”的混合型仓库，不要继续按单一笔记仓库管理。
2. 推荐管理原则
2.1 一级目录只放主题，不放零散临时文件
建议一级目录长期稳定，只保留：
01 指令创作方法小说视频规划技术资料服务器体系毕业论文职业资料知识库评论随笔扣子文档治理attachments999 无法分类
根目录零散文件建议逐步归档，不要继续在根目录新增无归属文档。
2.2 导航要与高信息量文档一体化
不建议为了导航单独制造很多薄 首页 / 目录 文档。
更推荐的方式是：
- 让一份真正有内容的总文档同时承担导航职责
- 在文档开头放“使用导航 / 阅读入口 / 关联文档”
- 根目录尽量少放重复说明页
只有在某个目录内容很多、且主文档不适合承担导航时，才额外补一个目录页。
2.3 文档、资源、构建工具三者分离
一个主题目录内，建议严格区分三类内容：
- 文档源：
*.md - 展示资源：图片、PDF、SVG、截图
- 工具链：脚本、模板、自动化依赖
建议规则：
- 文档源文件直接放主题目录
- 本地图片与图示统一存放到
E:\My Project\Atramenti-Console\codex\plugins\obsidian\data\image - 文档内可以使用相对路径，但解析终点必须落到
data\image - 活文档中的本地文件路径、链接路径和资源路径，必须使用当前仍然有效的 canonical 路径，不要继续引用已迁移或已删除的旧根路径
- 不要在
docs下再建*.images、assets、docs/image或主题同级图片副本 - 脚本和依赖放到工作区或外部工具目录，不直接混放在 Obsidian 文档目录
2.4 版本化文档要分“工作版”和“定稿版”
像毕业论文、手册、系统说明这类会持续修订的文档，建议拆分为：
- 工作版：当前持续修改中的
*.md - 定稿版：导出的
*.pdf/*.docx - 旧版归档：单独放
archive或历史版本
如果是迁移记录、修复记录、转换日志、审计清单这类历史材料，可以保留旧路径作为历史证据，但应明确这些路径只代表当时状态，不代表当前有效位置。
不要把十几个版本直接平铺在同一层目录里。
2.5 docs/agent 的管理型输出采用“统一落点 + 同职责单 canonical 文件”
对 E:\My Project\Atramenti-Console\codex\plugins\obsidian\data\docs\agent 下的管理型输出，默认执行下面这组规则：
- live canonical 协议、规范、手册、浏览层、任务 owning 文档继续统一落在
docs/agent - 专题知识、产品说明、工具指南、参考汇编、敏感附录、dated migration note 不再混放进
docs/agent，统一改放docs/codex-knowledge/根目录 - 每种职责只允许一个 canonical 文件，不为同一职责并行新建第二份台账、汇总或记录页
plan、verification、research decision、handoff、artifact index虽然都属于管理输出，但不是同一种职责，不应强行塞进同一个文件- 原始证据允许独立文件存在，例如截图、JSON、日志、diff、probe 输出，但必须被对应的 canonical 文件索引，不能作为无入口散落 artifact 长期漂着
- 一次性证据、烟测输出、扫描结果默认放
_artifacts，不要塞进docs/agent或docs/codex-knowledge - 文档整理默认采用单层扁平目录，不要在
docs/codex-knowledge里继续建分类子目录；主题信息优先写进 frontmattertags
这里还要额外分清两层：
PROJECT-CONTEXT.md/SESSION-HANDOFF.md/plan.md是项目 current-state 的唯一活入口docs/agent承担的是专题文档层 / 专题 canonical 层，用来承载协议、规范、手册、清单、浏览层与专题治理说明docs/codex-knowledge承担的是专题知识与资料层，用来承接不应该继续混在docs/agent的产品、工具、参考、敏感与历史经验资料docs/codex-knowledge默认保持单层平铺；除README.md外，文档直接放根目录，通过中文标题与 frontmattertags表达主题
更直接地说，这里的治理目标不是“把所有东西压成一个文件”，也不是“让 docs/agent 整体变成项目总真源层”，而是“把专题管理文档收口到 docs/agent，并保证每种职责只有一个活入口”。
2.6 docs/agent 的 Git tracked canonical whitelist 要显式维护
docs/agent 是专题文档层 / 专题 canonical 层，但不是项目 current-state 总真源层，更不是“整目录默认都进 Git”。更稳的默认规则是：
- 项目当前状态先看 triad：
PROJECT-CONTEXT.md、SESSION-HANDOFF.md、plan.md docs/agent下的大多数文档继续保留为本地专题 canonical 文档- 只有明确承担长期 canonical 职责、且需要跨会话 / 跨仓稳定复用的文件，才进入 tracked whitelist
- tracked whitelist 不能靠“现在正好被 track 到了”隐式形成，必须在本页、
.gitignore与PROJECT-CONTEXT.md三处保持一致
当前允许进入 Git 的 docs/agent canonical whitelist 按职责收口为：
- 知识层入口：
..\codex-knowledge\README.md - 计划台账：
plan.md - 文档治理：
第一库文档管理规范.md - 图文写作规范：
图文文档写作规范.md - 论文工作流：
..\codex-knowledge\应付论文工作流.md - 前端设计规范：
Frontend Design Specs.md - 操作术语协议：
操作术语协议.md - 任务包 / 能力路由规范：
任务包与能力分层路由规范.md - Mortis controller / Guard 专题规范：
Mortis 指挥层与 Guard 双脑架构规范.md - 服务器手册浏览层：
服务器手册伴随仪表盘.md - 服务器手册 Bases 视图：
服务器手册伴随视图.base
其余 docs/agent 文档默认视为本地专题 canonical 材料，但不自动加入 repo tracked 集。当前继续留在 local-only canonical 层的重点例子包括：
..\codex-knowledge\Atramenti-Console 文档汇编.mdMCP 清单总表.mdServer Operation & Maintenance Manual.md
如果某份文档要提升为 tracked canonical 文件，必须在同一工作周期同时完成：
- 更新本页 whitelist
- 更新 repo
.gitignore - 更新
PROJECT-CONTEXT.md的 standing rule
不要把历史方案、敏感附录、一次性说明、原始证据或 dated note 因为“以后可能有用”就顺手拉进 whitelist。
2.7 高频操作术语要收口到单一协议文件
对“整合进 / 接入到 / 迁入 / 并入 / 保留独立仓 / GitHub 推哪个仓 / 前端以谁为基础”这类高频操作语义，当前 canonical 文件已收口为：
操作术语协议.md
默认规则：
- 后续再新增操作术语时，继续向
操作术语协议.md扩写 - 不要在
docs/agent下再造并行的“术语补充 / 术语说明 / 口径页” - 如果某个新术语会改变真实执行方式，必须同轮把入口规则也一起改掉，而不是只把定义留在文档里
这里要追求的是“稳定触发 + 单一语义真源”，不是“术语多了就多建几个说明页”。
3. 对现有目录的具体建议
3.1 服务器体系
定位：服务器资产、控制面、MCP、AI 员工体系、部署手册。
建议保留：
- 总手册
- 服务器角色档案
- MCP 体系文档
- 运行规范与 SOP
- 图片资源目录
建议不要继续放入：
- npm 依赖
- node_modules
- 临时导出脚本
- 一次性调试中间文件
3.2 毕业论文
这是当前最工程化的目录，建议继续保持，但要加强版本治理：
原稿转换稿导出稿脚本工具资源素材当前版本索引
其中 转换稿 下版本过多，后续建议只保留：
- 最新工作版
- 最近两个回退版
- 其余转入
历史版本
3.3 小说 / 视频规划
这两个目录内容增长快，建议采用“项目制”管理：
- 每个作品或系列单独建目录
- 目录内固定包含：
大纲.md、设定.md、正文.md、目录.md - 若有配图或分镜，放
assets
3.4 01 指令 / 创作方法
这两个目录是“方法库”，不是项目库。
建议：
- 只放稳定可复用的规则
- 不放临时草稿
- 默认不再新增子目录；只有确实存在长期稳定的层级需求时，才额外建子目录并补
目录.md - 高价值文档建立索引页，避免同类提示词多版本混乱
3.5 999 无法分类
这个目录要继续保留，但只能作为中转站，不能长期堆积。
建议每周或每次整理时执行一次：
- 新增内容先丢进这里
- 后续归档到正式主题目录
- 保持这里只存放尚未归类的内容
4. 命名规范建议
4.1 文档命名
建议优先使用以下风格：
- 长期文档：
主题名.md - 索引文档：
目录.md、首页.md - 手册文档：
xxx技术手册.md - 规范文档：
xxx规范.md - 操作文档：
xxxSOP.md - 记录文档：
xxx记录（YYYY-MM-DD）.md
对 codex 管理层文档，再额外补一条更硬的落地规则：
docs/agent里的既有 live canonical 文件，继续保持稳定的人类可读 canonical 名，不为了“统一英文名”打断现有入口docs/codex-knowledge新增或迁入的文件默认使用人类可读中文标题，不再强制kebab-case或数字分类前缀docs/codex-knowledge默认不建分类子目录；需要分类时优先补 frontmattertags，而不是先扩展文件名前缀或加文件夹- date-scoped 文件继续允许保留日期，但应作为标题自然组成部分，例如
Mortis 页面扩展与上线操作经验（2026-04-20）.md - 只有术语本身就是稳定标识时，才保留必要英文或协议字样，例如
OpenAI v1、PaddleOCR、DOCX - 原始草稿、聊天转录、过程记录如果需要保留，优先通过
状态-归档标签表达归档属性；只有在文件名也需要一眼可辨时，才使用归档 -中文前缀 - 不要再使用
final、new、temp、misc、整理后这类不可持续命名
4.2 资源命名
- 手册配图：
image/手册名.images__01-xxx.svg - 截图：
screenshot-YYYYMMDD-HHMMSS.png - 导出稿：
文档名.pdf
4.3 不建议的命名
新建文档.md最终版.md终极版2.md修改后.md整合版最终修复版.mdfinal-notes.mdnew-doc.mdtemp-record.mdmisc.md
这些名字后期不可管理。
5. 你这个库最值得马上执行的三件事
- 把根目录零散文件逐步移动到各自主题目录
- 给
服务器体系、技术资料、知识库、评论随笔补统一首页 - 把所有“脚本 / node_modules / 导出工具”移出 Obsidian 文档区
6. 敏感信息提醒
当前 第一库/配置.md 中包含明显的认证与密钥内容。这类内容不建议继续直接存放在 Obsidian 文档库中。
建议改为：
- 文档里只写配置说明与字段结构
- 真正密钥放环境变量、密码管理器或本机私密配置目录
- 如果必须存档，至少单独放到不参与同步与公开分享的位置
7. 推荐的治理结构
建议在 第一库 下固定保留 文档治理 目录，专门放：
- 文档管理规范
- MCP 管理规范
- AI 文档生产能力说明
- 目录调整记录
- 归档与版本策略
这样以后你查“文档应该怎么写、怎么放、怎么导出”，就不用再翻聊天记录。
