Imported from mfkyddh/ZZZ-Simple-AI (
AGENTS.md). Install upstream withnpx skills add mfkyddh/ZZZ-Simple-AI. Copyright stays with the author.
AGENTS.md
项目概况
- 项目名：ZZZ白话讲AI（ZZZ-Simple-AI）
- 目标：用白话、极简、可复述的方式，帮零基础读者建立 AI 的基本认知
- 写给谁：零基础职场人士、大学生，以及想先建立整体框架的读者
核心原则：一切内容都服务于零基础读者。他们不需要知道所有细节，只需要能听懂、能复述、能用上。
核心理念：三个学习方法
| 方法 | 核心 | 写作检验 |
|---|---|---|
| 费曼学习法 | 用更简单的话重讲 | 一个零基础的朋友坐在我面前，我能让他听懂吗？ |
| 苏格拉底式提问 | 用问题引导思考 | 不用术语开头，先回到原始问题 |
| 第一性原理 | 回到最原始的问题和约束 | 每讲一个概念，先问：它最初是为了解决什么问题？ |
五个锚点（所有内容最终都要回到这里）：
| 锚点 | 一句话理解 |
|---|---|
| 🎯 本质一：概率模型 | 大模型最底层做的事，是根据前文预测下一个更可能出现的词 |
| 📋 本质二：上下文（Context） | 后面很多技术，本质上都在补充、整理和管理模型当前能看到的信息 |
| 主线一：大模型派 | 更关心模型本身能不能继续变强 |
| 主线二：驾驭工程派 | 更关心怎样用好模型，让它在真实场景里靠谱地跑起来 |
| 🧩 框架：八部件 | 智能体的八个核心部件：大脑、目标、上下文、记忆、工具、边界、观测、循环 |
八部件框架详细对照：
| 部件 | 比喻 | 功能 |
|---|---|---|
| 🧠 核心大脑 | 决策中心 | 大模型做判断 |
| 🎯 目标 | 方向盘 | 确定要去哪 |
| 📋 上下文 | 视野 | 能看到什么 |
| 🧠 记忆 | 笔记本 | 记得什么 |
| 🛠️ 工具 | 手 | 能调用什么 |
| 🔒 边界 | 围栏 | 什么能做不能做 |
| 👁️ 观测 | 眼睛 | 怎么知道结果 |
| 🔄 循环 | 心跳 | 如何持续运转 |
写作红线
这些红线源于真实踩坑，每条都有血的教训。按"问题→原则"的形式列出，不用记细节，记住原则就够了。
| 红线 | 原则 | 为什么 |
|---|---|---|
| ❌ 不要啰嗦 | 一章最多3-4个小节；每节只说一个核心观点 | 信息太多，读者记不住 |
| ❌ 不要自嗨 | 理论留给自己，白话留给读者；让读者通过故事和例子自己领悟 | 读者要的是"这是什么"，不是"我怎么分析的" |
| ❌ 不要炫技 | 一个简单比喻胜过一张复杂图表；让读者能复述，不是能看图 | 形式不能大于内容 |
| ❌ 不要忘记受众 | 读者是零基础，不是同行；不用术语定义开头，要从原始问题切入 | 受众错了，写得再好也没用 |
| ❌ 不要用学术概念代替生活比喻 | 用"脑子里同时想几件事"替代"有限（7±2个组块）" | 学术术语制造理解门槛 |
| ❌ 不要用抽象代号举例 | 用具体场景（开会、写代码）替代"A告诉B" | 抽象代号无法产生代入感 |
| ❌ 中英混杂 | 普通词汇一律用中文；英文只在术语首次出现、产品名、代码段中允许 | 打断阅读流畅度 |
章节结构标准
章节开头（2块）
1. 读前先想：1-2个口语化问题，拉回原始问题。不是陈述句，不是目录。
核心原则：必须从读者已知的体验出发，指向他们自然会产生的困惑，绝不能预支本章才要解释的概念。三个检查点：已知锚定（问题基于读者已接触的内容）、自然困惑（读者自己也会问出来）、零概念预支（不出现本章才首次定义的术语）。 2. 章节定位：包含"横向定位"（在本项目中的位置）和"本章回扣"（如何回到本质一和本质二）。
小节结构（6块模板）
每个小节按需使用：提问 → 术语 → 一句话解释 → 理解展开 → 示例 → 你只需要记住。
灵活调整：核心概念首次出现完整使用6块；对比/总结性小节保留"一句话+表格+总结"；过渡小节只用"过渡句+核心内容"。
章末结构（本章要义）
四段式：一句话核心结论（金句）→ 核心脉络回顾（表格）→ 回到两个本质（表格）→ 为下一章铺垫（抛出疑问）。
叙事连贯
小节之间用过渡句承接。读者读完上一节，心里自然产生一个新问题，下一节正好回答。
写作检查清单
写完一章对照检查。三方法是检验标准，不是写作工具；红线是过滤网，不是创作指南。
🔬 费曼检验（能复述吗？）
- 每小节有"一句话解释"和"你只需要记住"（2-3条）
- 用了生活化比喻而非抽象概念
- 一个零基础朋友坐在我面前，我能让他听懂吗？
❓ 苏格拉底检验（从问题开始吗？）
- "读前先想"是口语化问题，不是陈述句
- 每个小节从问题开始，不从术语定义开始
- 每一章是从"为什么会出现"切入，而非"是什么"
🎯 第一性原理检验（回到本质了吗？）
- "章节定位"包含横向定位 + 回扣本质一和本质二
- 本章要义四段式完整：金句 → 脉络回顾 → 回到本质 → 铺垫下文
- 明确本章属于主线一、主线二，或两者兼顾
✂️ 内容红线检查
- 小节不超过4个（深度系列除外）
- 没有学术术语代替生活比喻
- 没有中英混杂（英文只在术语首次出现、产品名、代码段）
- 例子是具体场景（职场/校园），没有ABCD抽象代号
📝 格式规范
- YAML frontmatter 8字段齐全，title与正文一致，updated为最新
- 引号无嵌套冲突，章节编号与文件名匹配
文档元数据规范（YAML Frontmatter）
所有 docs/ 下的章节文件必须在开头包含统一的 YAML frontmatter：
---
title: 章节标题（与正文一级标题一致）
slug: 英文短链接（如 ai-programming-workflow）
category: 分类（AI基础认知 / AI使用方法 / Agent理解）
tags: [标签1, 标签2, 标签3]
status: draft
version: 版本号（数字格式，每次修改递增0.1）
updated: YYYY-MM-DD
summary: 50字以内，概括本章核心内容
---禁止出现：description / date / author / layout / template。避免引号嵌套错误。
表达规范
中文书面语
禁用词（普通口语词在正文中必须替换）：
- "怎么接"→"如何接收/连接"；"稳不稳/靠不靠谱"→"是否稳定/可靠"；"兜底"→"风险防控/备选方案"；"搞砸"→"造成错误/引发问题"；"啰嗦"→"交互步骤较多"；"站队/吃掉/钩子"→"偏向/取代/铺垫"
术语与产品
- 首次出现：
中文（English），后续只用中文。口径统一以indexes/术语表.md为准。 - 产品举例优先国内（通义千问、豆包、DeepSeek、Kimi），辅助提及国外（ChatGPT、Claude）。
视觉规范
表情符号速查
| 场景 | 符号 | 场景 | 符号 |
|---|---|---|---|
| 章节标题 | # 🤖 |
一句话解释 | ### 💬 |
| 读前先想 | ## 🤔 |
深入理解 | ### 🧐 |
| 章节定位 | ## 🧭 |
示例 | ### 📚 |
| 小节提问 | ### ❓ |
核心要点 | ### ✅ |
| 术语 | ### 📝 |
过渡句 | 💭 ** |
排版要点
- 引用块（>）：突出金句、核心观点、阶段性总结
- 表格：用于对比和分类，减少大段文字；对比关系、多维度数据、结构化概念优先用表格
- 粗体：术语首次出现、核心结论、关键转折词
- 分隔线（---）：区分大段内容、概念到示例的过渡、前后对比
- 段落长度：普通段落2-4句；核心观点段1-2句（配合引用块）；列表项不超过2行
- 代码块：CLI命令、架构层级、流程逻辑
- 示意图：系统架构、流程流转、层次关系
- 长文章的排版规范参考
docs/extras/05-当软件不再给人用.md
系列规范
当文章形成系列（如多个扩展章节组成独立系列）时，需额外管理以下方面。
深度系列结构
深度系列可以突破"3-4个小节/2张表格"的限制，以讲全讲深为首要目标。但遵循三个原则：
| 原则 | 要求 |
|---|---|
| 信息量适中 | 单篇阅读时间控制在15-20分钟 |
| 不重复讲述 | 系列内部不重复定义同一概念 |
| 举例点到即可 | 例子简洁，说明白就停 |
系列内部咬合
- 每篇开篇回扣总纲：明确本篇回答总纲中提出的哪个核心问题
- 全系列措辞统一：同一强断言必须使用一致限定（如"约束相同，解法收敛"统一加"统计意义上"限定）
- 终章升华回扣：终章对全系列核心概念做认知升级，系列金句可在开篇和终章出现两次
章节结构调整
增删改章节位置时：修改目标文件 → 更新本章定位 → 更新前后章节的衔接（铺垫和承接）→ 更新README → 更新工作记忆 → 全局搜索旧引用确认无遗漏。
审查建议的独立判断
收到外部审查报告时，不应全盘接受或拒绝。按以下流程：
- 项目定位过滤：建议是否违背"零基础读者""白话讲AI"的定位？
- 可行性评估：建议在当前项目范围内能否执行？
- 质量判断：建议提升论证质量还是锦上添花？
- 按优先级执行：P0（必改）→ P1（重要）→ P2（有价值）→ P3（可选）
- 不采纳的建议必须给出明确项目规范依据
文件重命名
修改文件名后：搜索所有文件中对旧名的引用 → 更新 YAML title、slug、正文一级标题 → 搜索VitePress配置中的路径引用 → 确认编号与顺序一致。
章节逻辑递进
- 第1-5章：基础认知（理解AI是什么、怎么工作）
- 第6-8章：实践方法（如何用AI做事、工程纪律）
- 第9章：成长篇（如何借助AI实现个人成长）
- 扩展章节：独立深化，可跳跃阅读；YAML 需标注
related_mainline和prerequisites
完整章节列表见 README.md。
项目级 Skills
| Skill 名称 | 用途 | 安装位置 |
|---|---|---|
| article-to-chapter（文章转化为章节） | 将外部文章/观点转化为符合项目规范的章节 | ~/.qoderwork/skills/article-to-chapter/ |
| topic-and-writing（文章选题与创作工作流） | 搜索热点→形成选题→获得拍板→创作提交的完整流程 | ~/.qoderwork/skills/topic-and-writing/ |
仓库结构
| 路径 | 作用 |
|---|---|
README.md |
项目简介、阅读入口 |
docs/ |
知识库正文，按顺序编号 |
indexes/ |
术语表等索引 |
site/ |
预留：HTML 或静态站点产物 |
Markdown 是唯一长期内容源。docs/ 是唯一数据源，site/ 是完全独立的网站项目。禁止将 index.md、public/、网站配置放入 docs/。
VitePress 关键陷阱
vite.publicDir必须设为'../public'（相对于 content/ 向上一级）- CSS 选择器必须用直接子元素
.VPDoc > .container > .content - VPLocalNav 是移动端专用组件，桌面端应隐藏
协作约定
- 先理解，再写作：用户口述想法时，先整理成结构化要点
- 敢纠正：如果用户表述不准确，主动纠正，不要为了顺从而保留错误说法
- 主动收窄：发现内容偏离"简单、可复述、贴近工作场景"时，主动提出简化方案
- 先问后写：不确定时先问清楚，不要基于猜测写大段内容
- 核实先于修改：修改前先查看
docs/目录确认实际章节数量；涉及"上一章/下一章"的引用必须核实对应章节是否存在
跨学科思维原则
不是要求每篇文章都展开跨学科论述，而是在构思和理解问题时保持一种"开放参考系"的意识。
在理解或创作AI相关内容时，不局限于计算机或工程领域。当面对问题找不到答案时，可以回顾人类文明在个体、群体、组织、社会、文明等不同尺度上的发展经验，从各个学科乃至哲学与宗教中寻找参考。
具体运用方式：
- 如果某个概念在人类文明史上有清晰的对应，不妨点一句，用类比建立直觉
- 如果某个问题在其他学科中被深入研究过，不妨提一嘴，用引用增加厚度
- 如果某个难题在宗教或哲学中有过千年讨论，不妨一笔带过，用视角打开思路
点到即止，不必展开。 核心是让读者意识到"这个问题可以有更丰富的思考维度"，而不是把文章变成跨学科综述。
元框架章节创作经验
元框架章节（如总纲、ext-30 不确定性管理）站在比具体技术更高的抽象层，写作时有特殊的陷阱和经验。
核心教训：从"宏大断言"到"约束论解释"
- 问题：初稿容易犯"本体论断言"错误——"必然收敛""唯一解""这是数学"
- 修正：将表达从"必然"改为"容易"——"在相似的约束下，容易长出相似的结构"
- 定位：这不是理论，而是"约束驱动的系统类比框架（Constraint-based System Analogy Framework）"
三个"诚实声明"的引入时机
当引入新的解释框架时，必须显式声明其边界：
- 层vs环："三层不是严格分离的，更像三个观察角度"
- 映射边界："这些类比是启发式映射，不是严格等价"
- 单因子模型："不确定性不是唯一变量，只是最显性的入口"
原则：解释框架的边界必须显式声明，否则读者会误把"认知压缩器"当成"不可证伪理论"。
标题修改经验
- 描述性标题 → 直接点题 + 制造对称感 + 呼应核心比喻
- 例："从混沌到秩序..." → "不确定性管理——人类与AI的共同源代码"