助教的笔记仓库格式（供参考）¶

本页最后更新于，内容可能过时

本文用助教自己的笔记仓库 Mind-City 作例子，说明笔记仓库可以怎样组织，下面按层级列出各个目录。格式不用照搬，按自己的学科和笔记风格调整即可。

1. 顶层目录¶

顶层是四个目录、.claude 和两个文件，各自管一类内容：

名称	内容
`.claude/`	技能文件，见 7
`Annex/`	零散文件与自写的小工具，见 2
`Coursera/`	学科笔记，见 3
`Paper/`	论文笔记，见 4
`Skill/`	环境配置备忘录，见 5
`CLAUDE.md`	仓库级提示词，见 6
`README.md`	笔记目录与电子书的对应表，见 6

2. Annex：杂项¶

不适合和笔记放在一起的文件放这里：图标、CSS 样式表、备份文件，以及两个自己写的 VSCode 扩展。

markdown-preview-scroll-toggle：在编辑器标题栏放一个按钮，切换预览的滚动同步
markdown-preview-smiles：把预览里 &CCO& 形式的文本渲染成分子结构式，对应第 6 节的 CLAUDE.md 里「SMILES 渲染」一节

分子结构在化学笔记里出现频繁，做成扩展之后，笔记里直接写 &CCO& 就能看到结构式，不必每次裁图、上传、回填链接。

3. Coursera：笔记的目录分级¶

一级目录按学科分，名字写成 [N]学科。N 只用来排序，方括号把编号和学科名隔开，展开后按数字顺序排列。

二级是课程，写成 (N)课程名；课程下每一章一个文件，写成 (N)章节名.md。

(3)抽象代数 下是 (0)数论 到 (4)域论 五个章节文件。编号用半角圆括号，和课程目录的写法统一，展开目录时能看出哪一层是编号。

这些笔记的统一风格，由第 6 节的 CLAUDE.md 来约束。

4. Paper：论文笔记¶

论文笔记按 年份-论文简称.md 命名，年份在前，资源管理器里自动按时间排序。

仓库里存的是中文整理版，论文原文同步在 Zotero，不进仓库。

5. Skill：环境配置备忘录¶

装系统和配软件的过程记在这里，一个主题一篇：Conda配置、Linux配置、Docker笔记、Zotero配置 等。这些文件是重装环境时，用于复现的操作记录。

6. CLAUDE.md STYLES.md 与 README.md¶

下载链接（CLAUDE.md+STYLES.md+README.md+skills/）：https://mind-city.com/downloads/markdown-repo.zip

三个文件分工不同：

CLAUDE.md 是仓库级提示词，写长期约定：仓库结构、技能的放置、文风、标点与断句、文档结构、公式渲染。
STYLES.md 决定文件的形态：节标题层级、结构、标点、公式、插图的写法。用词与语气按 CLAUDE.md 的「文风」一节，两份文件的内容不重叠。
README.md 是一张对应表：左边是笔记目录，右边是对应的电子书路径

CLAUDE.md

# 仓库结构

笔记按学科组织在 `Coursera/` 下
笔记目录与配套电子书的对应关系见 `README.md`

# Skill

本仓库的 skill 放在 `.claude/skills/` 下
新增 skill 时, frontmatter 默认写 `user-invocable: false`

从教材 PDF 做笔记走 `textbook-to-notes`, 分对齐风格, 渲染, 写作, 补图四步
笔记的版式细则在仓库根 `STYLES.md`

调试 skill 走 `debug-skill`, 分起子 agent 试跑, 记录问题, 改 skill, 复查四步

# 文风

## 用词

适用于写入本仓库的文件, 也适用于对话回复
- 用平实的说明文, 接近产品说明书的写法
- 陈述事实与操作, 以可读性和准确性为准
- 不用夸张、煽动、摆谱的措辞
- 不用口语化说法
- 不拟人, 不调侃, 不评价读者, 不表演共情
- 补充解释之前不写俏皮话
- 动词选最普通的: 由...组成, 演示, 决定, 换成, 生成

### 高危用词

下面这些词 AI 味重, 读起来别扭, 写作时不要用这样的语气

| 类别     | 词                       | 问题                       |
| -------- | ------------------------ | -------------------------- |
| 动宾连写 | 管用词, 管样式           | 动词与宾语连写, 会产生歧义 |
| 比喻动作 | 憋到, 攒到, 攒够         | 把普通动作说成比喻         |
| 拟人动作 | 跟着走, 自己判断, 自己挑 | 把无生命对象写成人         |
| 缩略动宾 | 落盘, 存档               | 行业口语缩略               |
| 程度修饰 | 不堆, 堆长段             | 口语化程度词               |
| 口语依赖 | 靠, 靠...实现            | 用口语动词代替具体手段     |
| 口语代指 | 长什么样, 长啥样         | 用口语疑问代替名词         |

改法: 换成动词加宾语的完整说法
1. 管用词 -> 用词按...定
2. 憋到最后 -> 等到最后再... 
3. 跟着走 -> 与...一致
4. 自己判断 -> 自行判断, 或写明由谁决定
5. 落盘 -> 写入
6. 不堆长段 -> 不合并成长段
7. 靠...实现 -> 用...实现, 或由...决定
8. 文件长什么样 -> 文件的结构, 版式

## 文件形态

笔记与仓库内 Markdown 文件的结构, 标点, 公式, 插图写法见 `STYLES.md`
本文件的「文风」一节只规定用词与语气, 文件的结构与版式一律按 `STYLES.md`

@STYLES.md

# 校验

- 写完尽量自己 Read 通读一遍验收, 不要写一堆 Python 校验脚本
- 脚本尽量只用在真正机械的操作上, 例如批量插入空行

# 系统编码

本机代码页为 936 (GBK), Python 的 stdout 默认编码是 gbk, 命令行输出中文会乱码
改为 UTF-8 需写以下三个注册表值

[需要管理员权限, 且必须重启后生效]

```
Set-ItemProperty 'HKLM:\SYSTEM\CurrentControlSet\Control\Nls\CodePage' -Name ACP   -Value 65001
Set-ItemProperty 'HKLM:\SYSTEM\CurrentControlSet\Control\Nls\CodePage' -Name OEMCP -Value 65001
Set-ItemProperty 'HKLM:\SYSTEM\CurrentControlSet\Control\Nls\CodePage' -Name MACCP -Value 65001
```

重启后用 `python -I -c "import sys; print(sys.stdout.encoding)"` 验证, 输出 utf-8 即生效

STYLES.md

# 笔记风格

本文件写笔记与仓库内其他 Markdown 文件的形态: 结构, 版式, 标点, 公式, 插图
用词与语气按仓库根 `CLAUDE.md` 的「文风」一节
本文件与 `CLAUDE.md` 不再有重叠, 无需判断以哪份为准

## 适用范围

适用于 `Coursera/` 下的全部笔记, 以及仓库内其他 Markdown 文件
写某一学科时, 参考该学科已完成笔记的实际写法
两者的差异写进当轮报告, 不修改本文件

## 节标题层级

`#` 与 `##` 有两种写法, 按学科选定一种, 同一批笔记内保持一致

| 情形                    | 用哪个           |
| ----------------------- | ---------------- |
| 本文件未特别指定        | `#`              |
| 同目录已完成笔记用 `##` | 与同目录一致     |
| 用户当轮指定            | 按用户指定的层级 |

- 同一篇内不混用, 同一批并行写作的笔记之间也不混用
- 用 `#` 时, 节内分点写 `(1) (2) (3)`, 再下一层写 `1. 2. 3.`
- 用 `##` 时, 下一层用 `###`, 再下一层用正文 `(1)`
- 写作前选定层级, 写入本次记录与每个子 agent 的提示词, 不交由子 agent 自行判断

## 结构

- 文件开头空三行
- 不写书名, 章名大标题, 学习目标, 导读
- 标题上方空两行, 下方空一行
- 标题前不写 `------`, 标题渲染后自带分割线
- 块组之间用独立一行 `------`, 分割线前后各空一行
- 块组是一个完整的知识单元, 指一个定义簇, 一个定理连同它的证明, 或一串例题
- 块组内部按阶段用空行分段, 不插 `------`
  - 定理的陈述与证明之间空一行
  - 证明内部每 2 到 6 行一段
    分段点取在引入新的量(取, 令, 设), 换到另一个对象, 得出阶段性结论, 以及最后收束处
  - 定义簇里并列的多个定义之间空一行
  - 一串例题之间空一行
- 排版范例见 `Coursera/[1]数学/(3)抽象代数` 与 `Coursera/[1]数学/(5)数学分析` 下的笔记

## 断句与行文

- 不用全角标点 `。` `，` `、` `：` `；` `（）` `「」`
- 不用 `①②③` `⑴⑵⑶` `⒈⒉⒊` `㈠㈡㈢` 这类带圈或带括号的序号字符
  序号一律写成 `(1)` `(2)` 或 `1.` `2.`
- 逗号写成半角 `, `, 后面跟一个空格
- 冒号与括号用半角 `:` `(` `)`
- 句末不加终止符, 靠换行断开
- 一行一个短句
- 并列项, 条件, 结论, 结论前的说明各自成行, 该停顿的地方换行, 不合并成长句
- 一行尽量不超过 60 个字符, 中文与 LaTeX 都按 1 个字符计
- 长句在逗号, 以及 `且` `或` `则` `即` `所以` `于是` `由` 等处断开, 拆成多行
- 中文与数字, 中文与行内公式之间加空格
- 行内变量一律写入数学模式, 例如 `$p$` `$V$` `$n$`
- 不用加粗, 斜体, callout, emoji, 强调由标题, 列表, 分隔线承担
- 动词用最普通的: 由…组成, 表示, 决定, 换成, 生成

改前
该系统由三部分组成，分别是 A、B 和 C。

改后
该系统由三部分组成
1. A
2. B
3. C

## 标记约定

- 术语写成 `术语: 解释`
- 例题与推导写成 `> 例1-1: ...` 引用块
- 附注, 特例用 `[方括号]` 标出

## 公式与化学式

- 行内与独立公式都用单个 `$...$`, 全篇不出现 `$$`
- 独立公式单独成段, 前后空行
- 一条公式单独占一行, 不与说明文字混排
- 推导链一行一步, 写成 `$...$` 顺次排下来
- 多步推导用 `$\begin{aligned}...\end{aligned}$`, `&` 对齐等号, 行尾 `\\`
- 行内分数过小时, 用 `\dfrac` 或 `aligned` 包裹
- 断不开的长公式(`\begin{cases}`, 长不等式链)保留整行, 不拆分
- 数学模式内可以放中文, 不需要为此改写公式
- 不要为了验证渲染去装 KaTeX 等命令行工具, 命令行版与渲染器内嵌的解析器不是同一套
- 子 agent 看不到渲染结果, 遇到不确定的写法照原样写, 并在报告里列出待确认项
- 化学式一律写 `\ce{}`, 含离子, 电子排布, 杂化, 水合物
- `\ce{}` 内可以放中文, 不需要写到外面
- 箭头写 `->`, 平衡写 `<=>`, 条件写在箭头上 `->[高温]`
- 化学键写 `-`, `=`, `#`
- 单位写 `\mathrm{}`, 数值与单位之间用 `\ `
- 状态函数上下标统一写成 `\Delta_rH_\text{m}^\ominus` 这一种
- 分子结构用 SMILES 写, 两端加 `&`, 例如 `&CCO&`
  写在正文中间或单独占一行都可以, 渲染宽度由是否独占一行决定

## 例题

- 用引用块, 编号与教材章号一致, 例如 `> 例12-1: ...`
- 题干与解答之间用一行空的 `>`
- 解答以 `> 解:` 起头
- 结论句以「即」「故」「所以」收尾
- 例题内的表格与插图整体加 `> ` 前缀

## 表格

- 表题在表上方, 格式 `表N-M 表题 (条件)`, 表号后是空格, 不是冒号
- 表题与表之间空一行
- 正文里的数据表转为 Markdown 表格, 不裁图
- 单位用 `$.../(\mathrm{...})$`
- 缺项写 `—`, 趋势用 `↑ ↓`
- 双栏排版的表格按逻辑行顺序展平为一栏

## 插图

- 可以不用加文字图注
- 图号 `N` 与教材章号一致, 沿用教材原图号, 允许跳号
- 默认只写空占位 `![图N-M]()`, 不裁图, 不上传
- 全部笔记写完再询问用户是否补图
- 用户确认后才裁剪上传, 把占位换成真实链接
- 尺寸参数写成 `=Wx`, W 默认 400, 结构小图 200 到 300, 宽图 500 到 600
- 裁图时不包含教材印刷的图注

## 取舍

进笔记

- 定义, 定律, 判据, 关键公式
- 推导链, 每步写成一行
- 数据表, 装置图, 曲线图, 结构式
- 教材例题, 保持原题, 原数据, 原解法
- 例外, 反常现象, 适用条件

不进笔记

- 章首导语, 史实背景, 人物轶事
- 拓展学习资源, 总结与思考题, 习题
- 附录里的完整数据表
- 教材的冗长叙述压缩到 1 到 3 行, 公式与数据不压缩

README.md

# Mind-City

个人笔记仓库。笔记按学科组织在 `Coursera/` 下
配套电子书放在 Google Drive 的 `G:\我的云端硬盘\电子书`
两边大体按 `[学科]/(课程)` 同构命名

- 笔记根目录: `Coursera/`
- 电子书根目录: `G:\我的云端硬盘\电子书`
- 下表「电子书」列是相对电子书根目录的路径

## [1]数学

| 笔记目录        | 电子书                                                                                                                                                                          |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `(0)数理逻辑`   | `[1]数学/(0)数理逻辑/数理逻辑-证明及其限度-杨跃.pdf`                                                                                                                            |
| `(1)组合数学`   | `[1]数学/(1)组合数学/组合数学引论.pdf`                                                                                                                                          |
| `(2)图与网络`   | `[1]数学/(2)图与网络/图论与代数结构.pdf`                                                                                                                                        |
| `(3)抽象代数`   | `[1]数学/(3)抽象代数/初等数论.pdf`<br>`[1]数学/(3)抽象代数/近世代数-丘维声.pdf`<br>`[1]数学/(3)抽象代数/抽象代数基础-丘维声.pdf`<br>`[1]数学/(3)抽象代数/抽象代数学-姚慕生.pdf` |
| `(4)线性代数`   | `[1]数学/(4)线性代数/线性代数应该这样学-第四版.pdf`<br>`[1]数学/(4)线性代数/线性代数应该这样学-第三版.pdf`                                                                      |
| `(5)数学分析`   | `[1]数学/(5)数学分析/数学分析原理.pdf`（Rudin）<br>`[1]数学/(5)数学分析/数学分析-伍胜健.pdf`<br>`[1]数学/(5)数学分析/实分析-陶哲轩.pdf`                                         |
| `(6)概率统计`   | `[1]数学/(6)概率统计/数理统计学导论.pdf`<br>`[1]数学/(6)概率统计/测度论与概率论基础.pdf`                                                                                        |
| `(7)常微分方程` | `[1]数学/(7)常微分方程/常微分方程教程.pdf`                                                                                                                                      |

## [2]计算机

| 笔记目录          | 电子书                                                                                              |
| ----------------- | --------------------------------------------------------------------------------------------------- |
| `(0)C语言`        | `[2]计算机/(0)编程语言/C语言程序设计（第3版）.pdf`                                                  |
| `(0)计算机网络`   | `[2]计算机/(0)计算机网络/计算机网络 自顶向下方法.pdf`                                               |
| `(0)编译原理`     | `[2]计算机/(0)编译原理/编译原理（第2版）.pdf`                                                       |
| `(0)数据库`       | `[2]计算机/(0)数据库系统/数据库系统概念.pdf`                                                        |
| `(0)数字信号`     | `[2]计算机/(0)数字信号/数字信号处理教程.pdf`                                                        |
| `(0)操作系统`     | `[2]计算机/(0)操作系统/操作系统导论.pdf`                                                            |
| `(1)计算理论`     | `[2]计算机/(1)计算理论/计算理论导引.pdf`<br>`[2]计算机/(1)计算理论/计算复杂性-现代方法.pdf`         |
| `(2)算法导论`     | `[2]计算机/(2)算法导论/算法导论（原书第3版）.pdf`<br>`[2]计算机/(2)算法导论/椭圆曲线密码学导论.pdf` |
| `(3-1)监督学习`   | `[2]计算机/(3)机器学习/统计学习方法-李航.pdf`                                                       |
| `(3-2)无监督学习` | `[2]计算机/(3)机器学习/统计学习方法-李航.pdf`                                                       |
| `(4)深度学习`     | `[2]计算机/(4)深度学习/深度学习 花书.pdf`                                                           |

## [3]物理

| 笔记目录      | 电子书                                       |
| ------------- | -------------------------------------------- |
| `(1)理论力学` | `[3]物理/(1)理论力学/经典力学的数学方法.pdf` |
| `(2)电动力学` | `[3]物理/(2)电动力学/电动力学导论.pdf`       |

## [4]化学

| 笔记目录             | 电子书                                                                                         |
| -------------------- | ---------------------------------------------------------------------------------------------- |
| `(1-1)无机化学-上册` | `[4]化学/(1)无机化学/无机化学-上册.pdf`<br>`[4]化学/(1)无机化学/无机化学-习题解答.pdf`         |
| `(1-2)无机化学-下册` | `[4]化学/(1)无机化学/无机化学-下册.pdf`                                                        |
| `(2-1)有机化学-上册` | `[4]化学/(2)有机化学/基础有机化学-上册.pdf`<br>`[4]化学/(2)有机化学/基础有机化学-习题解析.pdf` |
| `(2-2)有机化学-下册` | `[4]化学/(2)有机化学/基础有机化学-下册.pdf`                                                    |

## [5]生物

| 笔记文件           | 电子书                                                                                                                                 |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| `(1)普通生物学.md` | `[5]生物/普通生物学-陈阅增-第5版.pdf`<br>`[5]生物/普通生物学-陈阅增-第4版.pdf`<br>`[5]生物/普通生物学-陈阅增-第4版-笔记和课后习题.pdf` |
| `(2)细胞生物学.md` | `[5]生物/细胞生物学.pdf`                                                                                                               |
| `(3)分子生物学.md` | `[5]生物/分子生物学.pdf`                                                                                                               |
| `(4)生物信息学`    | `[5]生物/生物信息学.pdf`                                                                                                               |

7. 笔记配套的 Skill 工具链¶

下载链接（CLAUDE.md+STYLES.md+README.md+skills/）：https://mind-city.com/downloads/markdown-repo.zip

技能	功能描述
`debug-skill`	调试 skill 的流程: 起一个子 agent 按 debug 模式跑一遍真实任务, 收集它遇到的问题与思考过程, 记录到 skill-bug.md, 据此修 skill, 最后复查文风
`textbook-to-notes`	从教材 PDF 生成 Coursera 笔记的总流程: 对齐风格, 渲染页面, 读图写笔记, 插图默认留空占位, 用户确认后再补图上传
`pdf-bookmark`	给扫描版教材 PDF 制作书签目录: 读图找目录页, 定每章的书页到 PDF 页偏移量, 从后往前核对, 写入书签
`pdf-page-image`	把教材 PDF 的指定页渲染成读图用的页面图, 多页时纵向拼成一张, 同时输出每页在图中的像素区间清单
`pdf-figure-crop`	按给定的像素矩形从页面图里裁出插图: 四周留白, 可选换算回源页用更高 dpi 重裁
`super-resolution`	用 SwinIR-L realSR GAN 对本地图片做 4 倍超分. 当用户要求放大图片, 超分, 提高分辨率, 让笔记里的图更清晰, 或需要处理低分辨率插图时使用
`coscmd`	用 coscmd 操作腾讯云 COS 图床 image-1379176255 ap-shanghai, 上传, 下载, 列出, 查看, 删除图片对象, 以及替换笔记图片链接的完整流程. 当需要上传图片, 更换图床链接, 清理桶内旧文件或查看桶内容时使用
`push`	本笔记仓库 Mind-City 的提交约定: 当用户说 push / 提交 / commit / 推送, 或需要把改动写进 git 提交历史时使用

7.1 从教材到笔记的链路¶

入口是 textbook-to-notes，其余技能由它按顺序调用：

读仓库根目录 README.md 的映射表，确定教材与这篇笔记的输出路径。表里没有的教材直接问用户
选定参考笔记，把风格整理进仓库根目录的 STYLES.md，再把这份文件交给每个写笔记的子 agent
扫描版教材没有文字层，章节范围需要调用技能 pdf-bookmark 做一遍书签目录，之后按书签定位章节
调用技能 pdf-page-image 把教材页渲染成页面图，读图写笔记正文
用户确认正文之后，调用技能 pdf-figure-crop 按坐标从页面图裁出插图
裁出的插图仍然模糊时，调用技能 super-resolution 做 4 倍超分
接着调用技能 coscmd 上传插图，把公网链接回填进笔记
最后调用技能 push 提交并推送

文档完成登记：完成本文全部流程后告知助教