AGENTS.md

本文档为 Codex 提供本知识库的架构说明和工作流指引。

知识库采用 LLM Wiki 模式（参考 Karpathy 的 LLM Wiki 设计）： LLM 持续维护一份会生长的 wiki，而不是每次查询都从零 RAG。

三层架构

Raw Sources (不可变原始资料)
    └── Clippings/     ← LLM 只读，从不修改
The Wiki (LLM 维护的知识库)
    ├── cc内容/         ← 结构化知识笔记（核心）
    ├── skill/          ← 方法论文档
    ├── 输出/           ← 最终成品
    └── 复盘/          ← 定期复盘报告
The Schema (配置)
    └── AGENTS.md      ← 本文件，告诉你如何维护这个库

Raw Sources — 你收集的原始资料（文章、字幕、笔记）。LLM 读取但不修改。
The Wiki — LLM 生成和维护的 markdown 文件。LLM 负责创建、更新、交叉引用。
The Schema — 本文件，定义工作流和规范。你和 LLM 共同演进。

核心区别：Wiki 是持续积累的复合产物。 交叉引用已经存在，矛盾已经标注，综合论述已包含所有已读内容。每新增一个源、每回答一个问题，Wiki 都在变丰富。

启动检查

每次对话开始时：

检查 Clippings/ 是否有未归档的 .md 文件（不在 已归档/ 中的）
如有，提示用户是否要处理
检查 复盘/ 中最近一次复盘报告的日期，如超过 7 天则建议再做一次复盘
检查 cc内容/_index.md 是否存在、是否与 cc内容/ 的实际文件一致（如有新文件未收录则更新）

目录结构

.
├── Clippings/            ← [A] Raw Sources（不可变）
│   ├── Bilibili/          视频字幕/笔记
│   ├── Web/              网页剪藏/文章
│   └── 已归档/             已处理的原始文件
├── cc内容/              ← [B] The Wiki - 结构化知识笔记
│   ├── _index.md          全局索引（LLM 维护）
│   ├── _log.md            操作日志（只追加）
│   ├── AI视频/
│   ├── 电商运营/
│   └── 工具方法/
├── skill/               ← [C1] 方法论文档库（人类可读）
├── .Codex/skills/       ← [C2] 可执行 Skill（Codex 可调用）
├── 输出/                ← [D] 产出区
│   └── 草稿/              输出过程中的半成品
├── 复盘/                ← 定期复盘/知识蒸馏报告
├── 附件/                ← 附件资源
│   └── excalidraw/         AI 生成的 Excalidraw 图表
└── .Codex/
    └── commands/           Codex 快捷指令

文件夹	层级	说明
`Clippings/`	Raw Sources	不可变的原始资料
`cc内容/`	The Wiki	LLM 维护的结构化知识（核心）
`skill/`	The Wiki	方法论文档
`输出/`	The Wiki	最终成品
`复盘/`	The Wiki	复盘报告
`AGENTS.md`	The Schema	工作流规范

操作流程

① Ingest — 摄入新源

当主动处理 Clippings/ 中的内容时：

读取原始内容，理解核心概念
与用户讨论关键要点，确认重点方向
提取关键观点、数据、案例
搜索现有 Wiki（先读 _index.md 定位相关页面），判断：
- 哪些已有页面需要更新
- 哪些新概念需要创建新页面
- 是否需要补充或修正已有论述
执行更新：
- 创建新的知识笔记 → cc内容/
- 更新已有相关页面（追加新观点、补充交叉引用、标注矛盾）
- 更新 _index.md（加入新页面索引）
- 追加 _log.md（记录本次操作）
归档原文件 → 移入 Clippings/已归档/

关键原则：不是只写一篇新笔记，而是让整个 Wiki 因新知识而进化。 一个源可能触及 5-10 个已有页面——更新它们。

② Query — 查询与回流

当用户提问时：

读 _index.md 定位相关页面
读相关页面，综合答案
答案回流的判断：
- 如果答案产生了新的结构化知识（对比、分析、综合论述），写回 Wiki 成为新页面
- 如果发现了现有页面的不足（缺失信息、矛盾、断链），标记并更新
- 普通问答不回流

好答案不应消失到聊天记录中。回流让知识持续积累。

③ Lint — 健康检查

按需（建议每 1-2 周）或在用户要求时执行：

[ ] 扫描 cc内容/ 与 _index.md 是否一致（漏收的文件 / 已删除仍列出的条目）
[ ] 检测孤立节点（有出链但目标不存在 / 有入链但来源文件不存在）
[ ] 检查 review_by 过期的笔记，标记需复审
[ ] 检测已被新源推翻或修正的旧论断，标记矛盾
[ ] 检查 _log.md 完整性（是否有未记录的明显操作）

Lint 输出 → 复盘/ 作为复盘报告的一部分。

Index 和 Log 规范

`cc内容/_index.md` — 全局索引

由 LLM 维护，列出 Wiki 中每一篇笔记：

markdown

## 分类名称

| 笔记 | 摘要 | 标签 |
|------|------|------|
| **笔记链接** | 一句话摘要 | `#标签` |

更新时机：每次 Ingest 后、每次 Query 回流后。

`cc内容/_log.md` — 操作日志

只追加，按时间顺序记录所有操作。格式：

markdown

## [2026-06-04] ingest | 源标题
- 创建: **新笔记**
- 更新: **已有笔记1**, **已有笔记2**
- 归档: Clippings/已归档/源文件.md

## [2026-06-04] query | 用户的问题
- 回流: **新创建的分析笔记**

## [2026-06-04] lint | 健康检查
- 发现: 2 个断链已修复, 1 个过期 review_by 已标注

每条用 ## [日期] type | 标题 开头，支持 grep 查询。

标签体系

所有笔记必须使用以下规范标签：

阶段标签（四选一）

标签	适用位置	说明
`#inbox`	`Clippings/` 中的未处理文件	原始资料
`#processed`	`cc内容/` 中的笔记	已处理的知识
`#skill`	`skill/` 中的文件	方法论文档
`#output`	`输出/` 中的文件	最终成品

领域标签（根据需要选用）

#AI视频 #Obsidian #AI工具 #提示词 #调色 #角色一致性

类型标签

#MOC 内容地图 / #复盘 复盘报告 / #模板 模板文档

Frontmatter 规范

yaml

---
title: "笔记标题"            # 必填
source: "来源"               # 建议填写，关联原始文件
author: cc                   # 固定
created: YYYY-MM-DD          # 必填
tags: [processed, 主题]      # 必填，含阶段标签 + 领域标签
review_by: YYYY-MM-DD       # 建议，通常 3-6 个月
confidence: high             # 可选：high / medium / low
status: processed            # 可选
---

字段	必填	说明
`title`	✅	清晰描述内容
`source`	建议	来源名称或原始文件关联
`author`	✅	统一为 `cc`
`created`	✅	创建日期
`tags`	✅	含阶段标签 + 领域标签
`review_by`	建议	知识过期检查日期
`confidence`	建议	可信度评估
`status`	可选	处理状态

可信度标准

级别	适用场景
`high`	普适方法论、成熟技术原理、经典理论
`medium`	工具教程（版本可能更新）、特定平台技巧
`low`	最新资讯、未经验证的方法、快速变化的领域

定期复盘

类型	频率	内容
知识蒸馏	按需	处理新入库内容 → `cc内容/`
周复盘	每周	检查新内容、修复断链、清理归档
知识老化检查	每月	扫描 `review_by` 已过期的笔记，标记或更新
Lint	按需	健康检查（见上文 Lint 流程）

周复盘 checklist

[ ] 扫描 Clippings 中未归档文件
[ ] 检查 cc内容笔记间是否有断链
[ ] 检查 review_by 是否过期
[ ] 清理过时/重复内容
[ ] 输出复盘报告到 复盘/

输出规范

作者标注：frontmatter 中 author 字段统一写 cc

文件命名：

翻译/整理内容：MM-DD-描述名称.md
其余内容：清晰的英文/中文描述

输出存放：

最终成品 → 输出/
半成品/草稿 → 输出/草稿/
输出过程中产生的知识洞察 → 补充回 cc内容/

Excalidraw 图表保存规范

AI 生成的 Excalidraw 图表必须保存到 附件/excalidraw/ 目录。

文件识别: 含 excalidraw-plugin: parsed 或 compressed-json 块，tags 含 excalidraw

命名: YYYY-MM-DD-描述.excalidraw.md

翻译格式化规范

翻译并整理外部内容时：

简体中文，禁止繁体字
问题背景和原因要解释清楚
概念和机制要详细说明
示例和场景要完整翻译
技术细节不能省略
保留原始的时间戳、章节标题、关键引述

元素	格式要求
结构化信息	使用表格
命令代码	使用代码块（```）
关键引述	使用引用块（>）
层级标题	使用 ## 和 ### 分级

AGENTS.md ​

三层架构 ​

启动检查 ​

目录结构 ​

操作流程 ​

① Ingest — 摄入新源 ​

② Query — 查询与回流 ​

③ Lint — 健康检查 ​

Index 和 Log 规范 ​

cc内容/_index.md — 全局索引 ​

cc内容/_log.md — 操作日志 ​

标签体系 ​

阶段标签（四选一） ​

领域标签（根据需要选用） ​

类型标签 ​

Frontmatter 规范 ​

可信度标准 ​

定期复盘 ​

周复盘 checklist ​

输出规范 ​

Excalidraw 图表保存规范 ​

翻译格式化规范 ​