我的写作原则

适用于 docs/01-健康幸福/、docs/02-事业有成/、docs/03-财务自由/ 和 docs/05-吴飞飞/ 下的大多数文档。docs/04-人生丰富/ 下的散文、游记使用 散文写作，数据页、相册和入口页仍按本文判断页面职责。

本文定义的是写作与审校逻辑，不是固定章节模板。先判断页面要完成什么任务，再决定需要多少洞见、论证、叙事和细节；不能用同一套结构处理观点文、教程、资料页与历史档案。

先定义什么是好文章

一篇好文章同时满足五个维度：

好文章 = 内容价值 × 可信度 × 传递效率 × 读者连接 × 使用价值

这里使用乘法，是因为任何一项接近零，都会限制整篇文章。观点再深，读者看不懂就无法传播；表达再顺，推理不成立就不可信；情绪再强，没有可使用的读后结果也很快被忘记。

维度	回答的问题	判断标准
内容价值	为什么值得写	问题真实且重要，核心产出能减少不确定性，而非重复常识
可信度	为什么可信	观点文的推理能够闭合，工具与保存型页面的来源、状态和结果可以验证
传递效率	为什么看得懂	按读者认知顺序展开，用准确的日常语言降低理解成本
读者连接	为什么与我有关	写出真实处境中的任务、冲突、选择和代价
使用价值	读完能获得什么	能迁移判断、复现结果、查询资料、观察变化或理解历史现场

常见写作要求在这套模型中的位置如下：

• 逻辑性属于可信度与组织。局部上，每个判断都有根据；整体上，章节之间存在因果、递进、转折、条件或可执行的先后关系。
• 通俗易懂属于传递效率。它是在不损失准确性的前提下降低认知成本，不是删掉必要概念或把复杂问题说得含糊。
• 共鸣属于读者连接。优先建立认知共鸣，让读者认出一个亲历却没有说清的问题；情感共鸣只在文体需要时使用。
• 深入浅出是跨维度的结果。深入来自内容价值和可信度，浅出来自传递效率；只有简单表达而没有机制，不叫深入浅出。

不同页面用不同方式满足五个维度。article 和 review 的可信度来自论证，tutorial 来自复现，reference 来自来源和查询结构，dashboard 来自数据口径与状态，archive 和 gallery 来自忠实保存与必要上下文。共鸣不等于讲故事，原创判断也不能强制套给工具型和保存型页面；证据不能被叙事或共鸣替代。

essay 是明确例外：正文内容、结构和编辑流程完全遵循 散文写作。本文只约束它的 front matter、外部事实与高风险内容的引用安全，以及仓库发布要求。

先确定页面契约

新增文档必须在 front matter 中填写 content_type，结构性重写旧文档时补齐。字段定义与 last_reviewed 要求详见 网站开发规范。

类型	读者任务	页面核心产出与完成标准
hub	理解栏目并选择下一步阅读	给出一个核心判断、当前重点和三到五条清晰路径
article	理解一个问题并形成判断	用机制和证据支撑核心判断，说明边界，给出可迁移判断或下一步
tutorial	稳定复现一个结果	写清前置条件、验证环境、步骤、故障排查和成功标准
reference	查询并追溯一组资料	写清来源、字段或分类、查询内容和更新时间
review	解释一个阶段发生了什么	呈现结果、原因、错误和下一阶段调整
archive	查看某个时间点的原貌	保留历史语境和原始内容，只补必要的状态说明
dashboard	观察持续变化的数据	说明数据口径、交互主体、异常和缺失情况
gallery	浏览一组媒体	以媒体为主体，补充必要的时间、地点和背景
essay	通过场景和叙事理解经验	使用 散文写作

一页只承担一种主要职责。入口页不兼任长篇观点仓库，观点文不兼任个人待办看板，教程不夹带与复现无关的行业评论，资料页不为了看起来像文章而强行添加议论。已有页面混合多种职责时，先删除、下沉或拆分，再润色句子。

页面结构服从读者任务：hub 按阅读选择组织，article 按论证关系组织，tutorial 按操作和验证顺序组织，reference 按查询路径组织，review 按变化与因果组织，archive 按历史时间和来源组织，dashboard 按观察与交互路径组织，gallery 按媒体浏览路径组织。资料页可以使用较深的分类层级，历史档案不能用当前观点重写原始正文；essay 的结构由 散文写作 定义。

写作前定义认知变化

除 essay 外，动笔前先完成一份最小写作简报：

目标读者与具体处境：
本文只回答的问题或任务：
读者原有判断或当前障碍：
核心判断、可复现结果或查询目标：
希望读后发生的认知或行动变化：
为什么这篇内容此刻值得存在：

值得写不等于题目宏大。第一手经验揭示了被忽略的机制，新证据改变了旧结论，现实结果与常识发生冲突，或者一套方法能让任务稳定复现，都可以构成价值。若内容只是重述已有共识，且没有更好的解释、证据、组织或使用路径，就应缩小问题、并入资料页或暂不写。

article 和 review 的核心判断应明确且尽量非显然；tutorial 的价值可以是可复现，reference 的价值可以是可查询，hub 的价值可以是降低选择成本。不能用“必须有新观点”否定整理和工具型内容的真实价值。

article 和解释性 review 的前几段应交代读者处境、问题和核心判断。可以用一个短场景引出矛盾，但不能为了制造悬念长期隐藏结论。

建立可检验的推理链

观点文和解释性复盘的主线应能压缩为：

核心判断 → 成立前提 → 中间机制 → 支撑证据
        → 反例或替代解释 → 适用边界 → 可迁移判断或行动

这是一套立论和审校工具，不要求机械地写成七个章节。全文只需为最重要的一到三个判断建立完整论证单元：

• 主张：到底认为哪件事成立，避免只有主题没有判断。
• 前提：结论依赖哪些事实、定义和假设。
• 机制：原因如何经过中间环节产生结果，不能用相关性代替因果过程。
• 证据：现实中观察到了什么，证据是否真的能区分当前解释与其他解释。
• 反例：最强的相反案例或替代解释是什么。
• 边界：结论对谁、在何时、什么条件和范围内成立。
• 启示：读者因此可以多做出什么判断或动作。

逻辑性既要检查句子，也要检查章节。完成提纲后，把每个 ## 压缩成一句子判断，尝试用“因为”“所以”“但是”“仅当”等关系连接。若标题只能形成“背景、现状、挑战、趋势”这类主题并列，文章通常还停留在知识清单，没有形成论证。

机制解释事实为什么可能发生，证据验证现实中是否发生，二者不能互相替代。结论由多个条件共同决定时，应明确必要条件、充分条件和概率性因素，避免把“有影响”偷换成“由它决定”。

根据句子选择证据

先判断一句话属于哪一类，再决定它需要什么支撑：

• 一手事实：亲历事件、个人数据和实际操作结果。写清场景、时间范围、动作和结果，不把一次经历直接推广为普遍规律。
• 外部事实：法规、产品能力、研究结果、行业事件和公开数据。优先链接原始法规、官方文档、论文或一手披露，并写明适用时间和范围。
• 机制判断：根据事实推导出的因果解释。把中间机制写出来，并给出可能失效的条件或反例。
• 个人选择：价值排序、执行策略和风险偏好。明确使用“我”的立场，不把私人处方包装成所有人都应遵守的答案。

重要判断的表达强度不能超过证据强度。出现“唯一”“永远”“必然”“本质”“所有人”等强断言时，先检查是否真的排除了反例；无法排除时，改为说明成立条件，例如“在当前阶段”“对这类系统”“在我可承受的风险范围内”。

数字可以作为证据，不能代替推理。使用数字时至少说明来源、时间和口径；比例类数字写清分子与分母，其他指标写清单位、样本量、时间窗口和聚合方式。实验与调查还要说明方法和不确定性，个人记录说明测量限制，教程参数说明验证环境。找不到可靠来源时使用定性表达，或明确标记为尚待验证的估计，不能把模型生成的数字当作事实。

直接引语必须注明作者与原始出处。转述外部观点时链接原文，不需要在正文展开人物履历；无法确认出处的名言、影视台词和网络摘录不作为论据。引用框架只能证明“框架如何定义”，不能直接证明某项控制有效或某个风险已发生。

医疗、投资、法律、安全和快速变化的 AI 内容属于高风险或高时效主题。正文要写清事实来源、适用对象和行动边界，并通过 front matter 的 last_reviewed 记录最后人工复核日期；日期本身影响理解时才在正文重复。个人执行方案可以公开，但必须与通用建议分开；模型评分、收益预测、健康效果和法律比例不能用没有验证方法的精确数字制造确定感。

技术文章必须落到可验证对象

技术深度不等于增加术语、篇幅或引用数量，而是把抽象判断展开为可以检查、实现和证伪的对象。安全、系统和 AI 文章的重要命题至少从以下六个支点中选择必要项，不能只停留在“应该做什么”：

1. 系统与攻击者模型：定义系统组成、信任假设，以及攻击者的访问权限、知识、查询预算和反馈条件。
2. 完整机制或攻击链：说明输入如何穿过数据、状态、权限和工具，在哪一步跨越边界，最终形成什么现实副作用。
3. 参考架构与强制位置：标出信任边界、策略决策点和执行强制点，说明控制为何不能只依赖被保护对象自律。
4. 实现原语：落到 Schema、策略伪代码、Token、Manifest、Trace Event、权限对象或协议字段，而非只列控制名称。
5. 可评测指标：比例类指标必须给出分子和分母；其他指标说明单位、样本量、时间窗口、聚合方式或分位数，并补充攻击预算、基线、置信区间和门禁条件。
6. 失效条件与取舍：写清控制能防什么、漏什么，以及安全性、效用、延迟、复杂度和成本如何选择。

技术证据优先形成完整链条：框架定义边界，论文解释机制，事故或官方披露证明现实影响，协议或开源实现说明如何落地，可复现实验验证效果与失效条件。不是每篇文章都要凑齐五类引用，但最强结论不能只有框架转述；至少应让读者看到机制、强制位置和验证方法如何相互对应。

评测结论必须绑定版本、数据分布、环境和攻击预算。一次通过只能说明在给定条件下没有发现失败，不能证明系统绝对安全；一次失败也要区分设计缺陷、实现缺陷和测试环境偏差。

深入浅出地解释

深入浅出遵循一条认知路径：

熟悉场景 → 暴露矛盾 → 命名概念 → 展开机制
        → 给出实例与反例 → 回到判断或应用

• 从读者已经知道的对象开始，再引入未知概念；术语首次出现时用一句准确的日常语言解释。
• 场景和例子必须承担解释功能，展示机制怎样发生，而非作为开头装饰或结尾佐证。
• 每上升一层抽象，就回到一个具体对象、动作、数据或结果；复杂概念按因果步骤拆开，不一次塞入多个新变量。
• 类比只帮助建立初始模型，随后要指出类比在哪里失效，不能让类比代替真实机制。
• 保留必要的专业名词、条件和不确定性。通俗化可以减少术语负担，不能删除决定结论的中间环节。

完成后优先请一个不了解背景的读者冷读并复述“结论是什么、为什么成立、什么时候不成立”。无法进行独立冷读时，合上正文，仅根据标题反向复述推理链，再检查是否遗漏关键条件。如果只能记住例子，说明抽象没有建立；如果只能重复术语，说明解释没有完成。

建立真实的读者连接

共鸣来自“这正是我遇到却没有说清的处境”，不是来自煽情。一个有效场景至少包含具体任务、现实约束、可选方案和选择代价；只有人物与环境，没有冲突和代价，只是背景描写。

• article 和 review 优先建立认知共鸣，再根据主题加入克制的情感细节。真实失败、犹豫和取舍通常比口号更有连接力。
• tutorial 和 reference 的连接体现为准确还原使用场景、前置障碍和查询路径，无须强行讲故事。
• essay 的叙事与情感要求使用 散文写作，不能反向套用技术文章的论证模板。
• 避免用“你是否也……”、虚构的普遍焦虑或抽象励志代替真实观察。
• 区分观察、推断和价值选择。个人经验和选择明确使用“我”，让作者声音来自真实立场，而非故作权威。

共鸣可以让读者愿意继续读，不能提高证据等级。越能激发情绪的案例，越要检查它是否具有代表性，避免用一个极端故事替代总体事实。

形成可迁移的读后结果

文章的终点不是“读者知道了更多”，而是读者获得了可以再次使用的东西：

• article 留下一个判断模型、决策问题或下一步，而非只给结论。
• tutorial 留下成功信号、验证方法和失败后的排查路径。
• reference 留下稳定的查询结构、来源和更新时间。
• review 留下经过修正的判断原则或下一阶段实验。
• hub 让读者知道自己当前在哪，以及下一篇该读什么。
• archive 留下忠实的历史现场与来源，避免读者用当前语境误读旧内容。
• dashboard 让读者识别当前状态、变化趋势、异常和数据缺口。
• gallery 提供连续、可定位的浏览体验和理解媒体所需的最小上下文。

可迁移不等于在结尾强加行动清单。读者应能说明“换一个对象或场景，我将检查哪些变量、依据什么做决定”。真正可记忆的内容通常是一个精确判断、一套简洁模型或一个承载机制的真实案例，不是重复出现的口号。

hub 和 article 不添加重复正文的总结段。内容已经完成预期认知变化时可以自然结束；需要结尾时，应推进到边界、选择或下一步，而非换一组措辞复述全文。

表达与版式服务于理解

• 使用直接、具体、可验证的句子。优先写清谁做了什么、经过什么机制、产生什么结果。
• 避免使用“不是……而是……”句式。直接陈述正面结论，必要时用独立短句说明被排除的误解。
• 避免把来源人物和论文背景写成长篇叙事。保留与论证有关的归因和原始链接，不能通过删除归因制造原创感。
• 长文借鉴论文的秩序、书籍的阅读体验和现代技术博客的视觉节奏，不把 Markdown 当成无限嵌套的文档树。
• 新写的 hub、article 和 review 最多使用三级标题；tutorial、reference 和需要分类说明的 dashboard、gallery 必要时可以使用 ####，但不使用 #####、######。archive 保留原始标题结构，essay 按 散文写作 处理。
• article 优先控制在 5～8 个 ##，hub 通常只需要 3～5 个。教程和资料页的章节数由操作链路或查询结构决定。
• 章节标题直接表达该节的具体判断或作用。快速浏览标题应能复述推理链或操作路径，避免“一个判断”“关键洞察”“背景”“其他”等空标题。
• docs/04-人生丰富/01-阅读/ 与 docs/04-人生丰富/02-影视/ 下的文章，标题中出现书籍、电影或剧集作品名时，front matter 的 title 和正文 H1 都使用书名号标出作品名，例如 《后会无期》、为什么重看《后会无期》。栏目入口标题如“阅读”“观影”不加书名号。
• 页面会自动给 ## 加结构编号，正文标题不手写 1、2、2.1。article 中的 ### 尽量少用，局部概念优先用加粗短句承载。
• 不使用“X 反常识”“X 最关键 / 最核心 / 最根本 / 最重要的真理 / 判断 / 真相”等夸张标题。
• 靠正文、引用、图片、图表、代码块、列表和留白形成节奏，不靠不断增加标题切碎内容。
• 需要图注的图片使用 Markdown 图片 title，例如 ![工作区](/media/a.webp "图 1：主要工作区。")，由主题自动渲染图注，不在正文手写 <figure>、<figcaption>。
• 题记放在 H1 标题下、正文之前。入口页不把哲学语录引用块放在靠前位置，应先提供核心判断、路径或其他可执行内容。
• 表格优先减少列、增加行，兼容手机竖屏。article 和 hub 避免宽表；reference 确需横向比较时可以保留，但要优先考虑拆表、结构化数据或专用交互组件。

仓库与发布约束

front matter 中的 icon 必须使用 src/components/ItsHoverIcon/icons/ 下的实际文件名，或 src/components/ItsHoverIcon/index.tsx 中 ICON_ALIASES 已注册的别名。不要使用既未注册、也没有对应文件的名称。

• 不添加注释，除非有非显而易见的原因需要说明。
• 不创建 README 或说明文档，除非用户明确要求。
• 新增内容优先复用现有文件，确认无合适位置后再新建。
• 移动文件会影响 sidebars.ts 自动侧边栏和导航，操作前确认影响范围，详见 docusaurus配置。
• 带“演讲”徽标的文章属于历史快照，不修改正文。需更新观点时复制为新文件后再编辑，原文件保留不动，详见 网站开发规范。

按层次编辑

除 essay 和不改正文的 archive 外，修改文章时按下面的顺序处理，不能先做表面润色：

1. 定位：确认 content_type，写清读者、处境、问题、核心产出和预期变化。
2. 立论：确定核心判断与二到四个支撑判断，只为关键判断补齐机制、证据、反例和边界。
3. 编排：按读者认知或操作顺序重建章节，用提纲压缩测试检查关系，删除、下沉或拆分并列知识点。
4. 解释与连接：按具体到抽象再到应用的顺序解释概念，补充承担解释功能的场景，清理术语拥堵。
5. 对抗审校：寻找最强替代解释、最可能误读之处和失效条件，校准结论与证据强度。
6. 发布：最后复核事实、数字、版本、标题、front matter、引用、图表和构建结果。

使用分层质量门禁

内容审校先检查文章是否真正有效，发布门禁再检查仓库是否合规。article 和 review 应完整检查五个维度；工具型和保存型页面按页面契约解释各维度，essay 改用 散文写作 的内容清单。机器检查只能发现格式与构建问题，不能证明文章值得读。

内容价值

[ ] 能说清目标读者、具体处境、本文唯一任务和预期变化
[ ] 核心判断、复现结果、查询结构或阅读路径确实降低了读者的不确定性

推理可信度

[ ] 章节压缩后形成论证关系、认知路径或操作顺序，而非主题并列
[ ] 最重要的一到三个判断写清机制、匹配证据、替代解释和适用边界
[ ] 外部事实与直接引语有原始来源，数字有时间、口径、分母和必要的不确定性
[ ] 高风险或高时效内容写清适用对象、行动边界并更新 last_reviewed

传递效率

[ ] 概念按已知到未知、具体到抽象再到应用的顺序出现，术语首次出现即解释
[ ] 场景、例子、图表和代码承担解释功能，并通过独立冷读或标题反向复述检查关键条件

读者连接

[ ] 内容对应真实任务、冲突、选择或摩擦；工具型页面没有为了共鸣强行讲故事

使用价值

[ ] 读者能迁移判断、复现结果、查询资料、观察变化、浏览媒体或理解历史现场

发布门禁

[ ] content_type 与页面职责一致，一页只承担一种主要职责
[ ] 新文档带 slug、icon、description、content_type，description 不超过 160 字
[ ] tutorial / reference 及高时效 hub / article / review 带 YYYY-MM-DD 格式的 last_reviewed
[ ] 标题层级、引用块、图片、表格和禁用句式符合本文约束
[ ] icon 在 ICON_ALIASES 中已注册或与真实文件名一致
[ ] npm run check:docs 通过
[ ] npm run build 通过