diff --git a/docs/README.md b/docs/README.md index 2259fbc..1ae2894 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,7 +2,15 @@ > `docs/` 是本仓库的核心知识库入口，承载从零开始、核心概念、哲学模型、研究笔记和工程参考资料。 -## 目录地图 +## 字多不看 + +- 新手先读 `getting-started/`，按网络环境、CLI 配置、开发环境和 Git 闭环推进。 +- 想理解 Vibe Coding 的底层概念，读 `concepts/`。 +- 想补思维模型和方法论，读 `philosophy/`。 +- 想查工程模板、质量门禁、技术栈和常见坑，读 `references/`。 +- 想记录新技术、优秀 repo 或工程趋势，读 `research/`。 + +## 快速导航 | 目录 | 定位 | 首选入口 | |:---|:---|:---| @@ -12,39 +20,6 @@ | [references](./references/) | 工程实践、技术栈、模板和检查清单 | [参考资料索引](./references/README.md#目录定位) | | [research](./research/) | 新技术、优秀 repo 与工程范式研究 | [研究笔记索引](./research/README.md) | -## 推荐阅读路径 - -### 新手路径 - -1. [从零开始完整入门](./getting-started/README.md#learning-map) -2. [Vibe Coding 经验](./getting-started/README.md#vibe-coding-experience) -3. [问题求解](concepts/README.md#concept-problem-solving) -4. [拼好码](concepts/README.md#concept-glue-coding) -5. [工程实践](references/README.md#reference-engineering-practice) - -### 开发者路径 - -1. [拼好码](concepts/README.md#concept-glue-coding) -2. [系统构建方法](concepts/README.md#concept-system-building) -3. [技术栈](references/README.md#reference-technology-stack) -4. [工程实践](references/README.md#reference-engineering-practice) - -### 思维模型路径 - -1. [思维模型](philosophy/README.md#philosophy-thinking-models) -2. [组合描述模型](philosophy/README.md#philosophy-compositional-description-model) -3. [编程之道](philosophy/README.md#philosophy-programming-dao) -4. [递归自优化系统](concepts/README.md#concept-recursive-self-optimizing-system) - -### AI Agent 读取路径 - -1. [根目录 AGENTS](../AGENTS.md) -2. [docs 目录 AGENTS](./AGENTS.md) -3. [从零开始完整入门](./getting-started/README.md#learning-map) -4. [Vibe Coding 经验](./getting-started/README.md#vibe-coding-experience) -5. [工程实践](references/README.md#reference-engineering-practice) -6. [AI 引用语料](../assets/ai-citation/README.md) -
完整细粒度目录（点击展开/收起） @@ -52,7 +27,7 @@ ### getting-started -- [README](./getting-started/README.md#顶部导航) - 从零开始完整入门，包含学习地图、Vibe Coding 经验、网络配置、CLI 配置与开发环境搭建。 +- [README](./getting-started/README.md#快速导航) - 从零开始完整入门，包含学习地图、Vibe Coding 经验、网络配置、CLI 配置与开发环境搭建。 - [Vibe Coding 经验](./getting-started/README.md#vibe-coding-experience) - 通用语言能力、人机分工、机器门禁和入门铁律。 - [AGENTS](./getting-started/AGENTS.md) - 入门教程目录操作规则。 @@ -90,7 +65,49 @@
-## 维护规则 +## 使用方式 + +- 只想快速开始：从 [getting-started](./getting-started/README.md) 进入。 +- 已经有项目问题：先读 [问题求解](concepts/README.md#concept-problem-solving)，再读 [工程实践](references/README.md#reference-engineering-practice)。 +- 需要给 AI Agent 上下文：先给它 [AGENTS](./AGENTS.md)，再给它当前任务对应目录的 README。 +- 新增内容时，先判断它属于教程、概念、哲学、参考还是研究，再放入对应目录。 + +## 正文 + +### 推荐阅读路径 + +#### 新手路径 + +1. [从零开始完整入门](./getting-started/README.md#learning-map) +2. [Vibe Coding 经验](./getting-started/README.md#vibe-coding-experience) +3. [问题求解](concepts/README.md#concept-problem-solving) +4. [拼好码](concepts/README.md#concept-glue-coding) +5. [工程实践](references/README.md#reference-engineering-practice) + +#### 开发者路径 + +1. [拼好码](concepts/README.md#concept-glue-coding) +2. [系统构建方法](concepts/README.md#concept-system-building) +3. [技术栈](references/README.md#reference-technology-stack) +4. [工程实践](references/README.md#reference-engineering-practice) + +#### 思维模型路径 + +1. [思维模型](philosophy/README.md#philosophy-thinking-models) +2. [组合描述模型](philosophy/README.md#philosophy-compositional-description-model) +3. [编程之道](philosophy/README.md#philosophy-programming-dao) +4. [递归自优化系统](concepts/README.md#concept-recursive-self-optimizing-system) + +#### AI Agent 读取路径 + +1. [根目录 AGENTS](../AGENTS.md) +2. [docs 目录 AGENTS](./AGENTS.md) +3. [从零开始完整入门](./getting-started/README.md#learning-map) +4. [Vibe Coding 经验](./getting-started/README.md#vibe-coding-experience) +5. [工程实践](references/README.md#reference-engineering-practice) +6. [AI 引用语料](../assets/ai-citation/README.md) + +### 维护规则 - 每个目录必须同时维护 `README.md` 和 `AGENTS.md`。 - 新增、删除、移动、重命名文档时，必须同步更新本索引、所在目录索引和 `metadata/taxonomy.yml`。 diff --git a/docs/concepts/README.md b/docs/concepts/README.md index 69af592..b1ad633 100644 --- a/docs/concepts/README.md +++ b/docs/concepts/README.md @@ -4,13 +4,15 @@ > `concepts/` 是 Vibe Coding 的核心概念手册，用一个线性文档承载问题求解、拼好码、系统构建、开发范式、语言层要素与递归自优化系统。 -## 核心摘要 +## 字多不看 - 本目录回答“先用什么概念理解问题”。 -- 它不是操作教程，也不是工具清单，而是把 Vibe Coding 中反复出现的关键概念沉淀成稳定入口。 -- 本 README 提供稳定锚点和细粒度目录，作为核心概念的统一入口。 +- 先读“问题求解”，把目标、现状、差距、标准、约束、对象和路径说清楚。 +- 再读“拼好码”，把复用成熟能力作为默认工程路径。 +- 需要搭系统时读“系统构建方法”和“开发范式演进”。 +- 需要理解代码和 AI 生成系统时读“语言层要素”和“递归自优化系统”。 -## 总目录 +## 快速导航 1. [问题求解](#concept-problem-solving) - 目标、现状、差距、标准、约束、对象与路径。 2. [拼好码](#concept-glue-coding) - 复用成熟能力，用胶水代码连接、编排、适配业务流程。 @@ -164,17 +166,27 @@ -## 和其他目录的边界 +## 使用方式 -- 具体入门步骤放在 [getting-started](../getting-started/README.md#顶部导航)。 +- 先从 [问题求解](#concept-problem-solving) 建立任务定义，再进入具体工具和工程实践。 +- 如果内容是步骤、命令和环境配置，放到 [getting-started](../getting-started/README.md)。 +- 如果内容是工程清单、模板、质量门禁或技术栈，放到 [references](../references/README.md#目录定位)。 +- 如果内容是思维模型、哲学模型或底层认知框架，放到 [philosophy](../philosophy/README.md#philosophy-methodology-toolbox-怎么选)。 +- 如果内容是新技术、优秀 repo 或趋势判断，放到 [research](../research/README.md#目录定位)。 + +## 正文 + +### 和其他目录的边界 + +- 具体入门步骤放在 [getting-started](../getting-started/README.md)。 - 工程模板、质量门禁、常见坑和技术栈放在 [references](../references/README.md#目录定位)。 - 思维模型、编程哲学和底层认知模型放在 [philosophy](../philosophy/README.md#philosophy-methodology-toolbox-怎么选)。 - 新技术、优秀 repo 和趋势判断先放在 [research](../research/README.md#目录定位)。 -## 维护规则 +### 维护规则 - 本目录采用“线性总文档”结构，正文统一收敛到 `README.md`。 -- 新增内容时优先追加到对应大章节，并同步补充总目录或细粒度目录。 +- 新增内容时优先追加到对应大章节，并同步补充快速导航或完整细粒度目录。 - 不再新增同级主题 `.md` 文件；如确需拆分，必须同步更新全仓索引、AGENTS 与 metadata。 - 目录内只保留 `README.md` 与 `AGENTS.md`。 diff --git a/docs/getting-started/README.md b/docs/getting-started/README.md index 1065e99..523e900 100644 --- a/docs/getting-started/README.md +++ b/docs/getting-started/README.md @@ -1,38 +1,24 @@ # 从零开始：Vibe Coding 完整入门教程 -## 核心摘要 +## 字多不看 -这是一条面向新电脑和零基础用户的线性路线：先解决网络环境与 Codex / ChatGPT 订阅，再跑通 Codex CLI，随后让本地 Agent 主动检查和配置 Git、Node.js、Python、编辑器、项目依赖、测试命令和 Git 工作流。 +- 这是一条面向新电脑和零基础用户的线性路线。 +- 先解决网络环境与 Codex / ChatGPT 订阅，再跑通 Codex CLI。 +- Codex CLI 跑通后，让本地 Agent 主动检查和配置 Git、Node.js、Python、编辑器、项目依赖、测试命令和 Git 工作流。 +- 不要一开始手工配置完整开发环境；先获得一个能读写文件、执行命令、修复报错的本地 AI 入口。 +- 用户主要负责授权、复制报错、确认结果和保存版本。 -本文件的目标不是让用户手工记住所有安装细节，而是让用户先获得一个可执行的 AI CLI 入口，再用 Agent 带动后续环境配置和项目交付。 - -## 顶部导航 +## 快速导航 | 章节 | 解决的问题 | |:---|:---| | [使用方式](#使用方式) | 不会操作时如何让网页 AI 生成逐步执行方案 | -| [最短路径：先跑通 Codex CLI](#最短路径先跑通-codex-cli) | 为什么先配置 AI CLI，而不是先手工配置完整开发环境 | | [Vibe Coding 经验](#vibe-coding-experience) | 人机分工、门禁、复盘和 AI 审 AI | | [学习地图](#learning-map) | 根据新手、开发者、团队、Prompt、Skill、质量门禁和 GEO/SEO 选择路线 | | [网络环境配置](#network-environment) | OpenAI、GitHub、文档和依赖源访问 | | [CLI 配置](#cli-setup) | Codex CLI 默认路线与 OpenCode 备选路线 | | [开发环境搭建](#development-environment) | 让 Agent 主动配置开发依赖、编辑器建议和测试命令 | -## 使用方式 - -从上到下阅读即可：先明确学习路线和人机分工，再解决网络、CLI 与开发环境。遇到卡点时，把当前小节全文、你执行的命令和完整报错一起发给网页版 AI，让它按你的系统生成逐步修复命令。 - -## 最短路径：先跑通 Codex CLI - -对新手来说，最优先配置的不是完整开发环境，而是先满足 Codex CLI 的两个前置条件：可访问 OpenAI 的网络环境，以及可用的 Codex / ChatGPT 订阅。只要 Codex CLI 跑通，就可以让 Codex Agent 读取本文档和当前系统信息，主动完成 Git、Node.js、Python、编辑器、项目依赖、测试命令、Git 初始化等后续配置。用户主要负责提供授权、复制报错、确认结果和保存版本。 - -默认策略： - -- 先解决网络环境和 Codex / ChatGPT 订阅。 -- 再安装并登录 Codex CLI。 -- Codex CLI 可用后，优先让本地 Agent 主动配置剩余开发环境。 -- 只有遇到网页登录、订阅购买、验证码、系统密码、管理员授权、敏感凭证或不可逆操作时，才需要用户介入。 -
完整细粒度目录（点击展开/收起） @@ -46,6 +32,19 @@
+## 使用方式 + +从上到下阅读即可：先明确学习路线和人机分工，再解决网络、CLI 与开发环境。遇到卡点时，把当前小节全文、你执行的命令和完整报错一起发给网页版 AI，让它按你的系统生成逐步修复命令。 + +默认策略： + +- 先解决网络环境和 Codex / ChatGPT 订阅。 +- 再安装并登录 Codex CLI。 +- Codex CLI 可用后，优先让本地 Agent 主动配置剩余开发环境。 +- 只有遇到网页登录、订阅购买、验证码、系统密码、管理员授权、敏感凭证或不可逆操作时，才需要用户介入。 + +## 正文 +
1. Vibe Coding 经验 - 通用语言能力、人机分工、机器门禁和入门铁律。（点击展开/收起） diff --git a/docs/philosophy/README.md b/docs/philosophy/README.md index 093ac0b..7982655 100644 --- a/docs/philosophy/README.md +++ b/docs/philosophy/README.md @@ -5,13 +5,15 @@ > `philosophy/` 是哲学方法论、思维模型、编程哲学和底层认知模型的线性手册。 -## 核心摘要 +## 字多不看 - 本目录回答“为什么这样判断、如何减少幻觉、如何让复杂问题可描述、可推理、可验证”。 -- 它保留可迁移的认知模型和方法论，不放一次性命令、工具清单或新技术观察。 -- 本 README 提供稳定锚点和细粒度目录，作为哲学方法论的统一入口。 +- 先用“思维模型”选择认知工具。 +- 再用“组合描述模型”把对象、状态、序列、过程和关系说清楚。 +- 需要工程判断时读“编程之道”。 +- 需要提效方法时读“方法论工具箱”。 -## 总目录 +## 快速导航 1. [思维模型](#philosophy-thinking-models) - 第一性原理、奥卡姆剃刀、多阶思维、状态空间等认知工具。 2. [组合描述模型](#philosophy-compositional-description-model) - 对象、状态、快照、序列、过程、变换、同一/差异与关系。 @@ -155,17 +157,26 @@
-## 和其他目录的边界 +## 使用方式 + +- 遇到复杂问题，先读 [思维模型](#philosophy-thinking-models)，选择合适的分析工具。 +- 需要把复杂对象拆清楚，读 [组合描述模型](#philosophy-compositional-description-model)。 +- 需要判断代码、架构和复杂度，读 [编程之道](#philosophy-programming-dao)。 +- 需要形成可复用方法，读 [方法论工具箱](#philosophy-methodology-toolbox)。 + +## 正文 + +### 和其他目录的边界 - `concepts/` 负责 Vibe Coding 核心概念和工程思想。 - `references/` 负责可执行的工程实践、技术栈、门禁和清单。 - `research/` 负责新技术、新 repo 和趋势判断。 - 本目录只保留能迁移到多个问题上的认知模型和方法论。 -## 维护规则 +### 维护规则 - 本目录采用“线性总文档”结构，正文统一收敛到 `README.md`。 -- 新增内容时优先追加到对应大章节，并同步补充总目录或细粒度目录。 +- 新增内容时优先追加到对应大章节，并同步补充快速导航或完整细粒度目录。 - 不再新增同级主题 `.md` 文件；如确需拆分，必须同步更新全仓索引、AGENTS 与 metadata。 - 目录内只保留 `README.md` 与 `AGENTS.md`。 diff --git a/docs/references/README.md b/docs/references/README.md index 5b82389..5ee3e13 100644 --- a/docs/references/README.md +++ b/docs/references/README.md @@ -5,15 +5,16 @@ > `references/` 是工程实践、技术栈、模板、清单、质量门禁和可复用经验的线性手册。 -## 核心摘要 +## 字多不看 > 生成规则：本文件由 `docs/references/sources/` 按文件名顺序拼接生成；请修改源片段后运行 `make sync-reference-readme`，不要直接编辑总文档主体。 - 本目录回答“具体工程怎么组织、怎么选技术、怎么设置硬门禁”。 -- 它承载稳定、可执行、可检查、可复用的工程参考资料。 -- 本 README 提供稳定锚点和细粒度目录，作为工程参考资料的统一入口。 +- 先看“工程实践”，获得项目架构、代码组织、开发经验、质量门禁和常见坑。 +- 再看“技术栈”，完成技术选型、组合案例判断和初学者学习路径设计。 +- 长文档优先走快速导航；需要完整索引时再展开细粒度目录。 -## 常用入口 +## 快速导航 | 目标 | 直接跳转 | |:---|:---| @@ -26,26 +27,6 @@ | 技术栈怎么选 | [如何选择技术栈](#tech-stack-selection) | | 初学者先学什么 | [初学者应该学什么技术栈](#reference-technology-stack-十五初学者应该学什么技术栈) | -## 总目录 - -1. [工程实践](#reference-engineering-practice) - 项目架构、代码组织、开发经验、质量门禁与常见坑。 -2. [技术栈](#reference-technology-stack) - 技术栈选型、组合案例与学习路径。 - -## 折叠块语法 - -长目录统一使用 `details + summary`，常用入口放在折叠块外，完整细粒度目录放在折叠块内。 - -```md -
-完整细粒度目录（点击展开/收起） - -### 细粒度目录 - -- [章节](#stable-anchor) - -
-``` -
完整细粒度目录（点击展开/收起） @@ -360,16 +341,25 @@
-## 和其他目录的边界 +## 使用方式 + +- 先从 [工程实践](#reference-engineering-practice) 判断项目结构、代码组织、质量门禁和常见坑。 +- 再从 [技术栈](#reference-technology-stack) 判断技术选型、组合案例和学习路径。 +- 只查具体问题时，优先使用上方“快速导航”和细粒度目录。 +- 本 README 是生成文件；新增或调整正文时先改 `docs/references/sources/`。 + +## 正文 + +### 和其他目录的边界 - 检查清单、模板、质量门禁和经验类内容优先收敛到本 README 的工程实践部分。 - 技术选型、技术栈组合和学习路径优先收敛到本 README 的技术栈部分。 - 新技术、工具趋势、优秀 repo 解析先放入 [research](../research/README.md)，形成稳定工程参考后再放入本目录。 -## 维护规则 +### 维护规则 - 本目录采用“线性总文档”结构，正文统一收敛到 `README.md`。 -- 新增内容时优先追加到对应大章节，并同步补充总目录或细粒度目录。 +- 新增内容时优先追加到对应大章节，并同步补充快速导航或完整细粒度目录。 - 不再新增同级主题 `.md` 文件；如确需拆分，必须同步更新全仓索引、AGENTS 与 metadata。 - 目录内只保留 `README.md` 与 `AGENTS.md`。 diff --git a/docs/references/sources/00-intro.md b/docs/references/sources/00-intro.md index 73fcf6e..804391a 100644 --- a/docs/references/sources/00-intro.md +++ b/docs/references/sources/00-intro.md @@ -5,15 +5,16 @@ > `references/` 是工程实践、技术栈、模板、清单、质量门禁和可复用经验的线性手册。 -## 核心摘要 +## 字多不看 > 生成规则：本文件由 `docs/references/sources/` 按文件名顺序拼接生成；请修改源片段后运行 `make sync-reference-readme`，不要直接编辑总文档主体。 - 本目录回答“具体工程怎么组织、怎么选技术、怎么设置硬门禁”。 -- 它承载稳定、可执行、可检查、可复用的工程参考资料。 -- 本 README 提供稳定锚点和细粒度目录，作为工程参考资料的统一入口。 +- 先看“工程实践”，获得项目架构、代码组织、开发经验、质量门禁和常见坑。 +- 再看“技术栈”，完成技术选型、组合案例判断和初学者学习路径设计。 +- 长文档优先走快速导航；需要完整索引时再展开细粒度目录。 -## 常用入口 +## 快速导航 | 目标 | 直接跳转 | |:---|:---| @@ -26,26 +27,6 @@ | 技术栈怎么选 | [如何选择技术栈](#tech-stack-selection) | | 初学者先学什么 | [初学者应该学什么技术栈](#reference-technology-stack-十五初学者应该学什么技术栈) | -## 总目录 - -1. [工程实践](#reference-engineering-practice) - 项目架构、代码组织、开发经验、质量门禁与常见坑。 -2. [技术栈](#reference-technology-stack) - 技术栈选型、组合案例与学习路径。 - -## 折叠块语法 - -长目录统一使用 `details + summary`，常用入口放在折叠块外，完整细粒度目录放在折叠块内。 - -```md -
-完整细粒度目录（点击展开/收起） - -### 细粒度目录 - -- [章节](#stable-anchor) - -
-``` -
完整细粒度目录（点击展开/收起） @@ -360,16 +341,25 @@
-## 和其他目录的边界 +## 使用方式 + +- 先从 [工程实践](#reference-engineering-practice) 判断项目结构、代码组织、质量门禁和常见坑。 +- 再从 [技术栈](#reference-technology-stack) 判断技术选型、组合案例和学习路径。 +- 只查具体问题时，优先使用上方“快速导航”和细粒度目录。 +- 本 README 是生成文件；新增或调整正文时先改 `docs/references/sources/`。 + +## 正文 + +### 和其他目录的边界 - 检查清单、模板、质量门禁和经验类内容优先收敛到本 README 的工程实践部分。 - 技术选型、技术栈组合和学习路径优先收敛到本 README 的技术栈部分。 - 新技术、工具趋势、优秀 repo 解析先放入 [research](../research/README.md)，形成稳定工程参考后再放入本目录。 -## 维护规则 +### 维护规则 - 本目录采用“线性总文档”结构，正文统一收敛到 `README.md`。 -- 新增内容时优先追加到对应大章节，并同步补充总目录或细粒度目录。 +- 新增内容时优先追加到对应大章节，并同步补充快速导航或完整细粒度目录。 - 不再新增同级主题 `.md` 文件；如确需拆分，必须同步更新全仓索引、AGENTS 与 metadata。 - 目录内只保留 `README.md` 与 `AGENTS.md`。 diff --git a/docs/research/README.md b/docs/research/README.md index 6d99846..d295b50 100644 --- a/docs/research/README.md +++ b/docs/research/README.md @@ -4,13 +4,14 @@ > `research/` 是新技术、新技术栈、优秀 repo、工程范式和工具趋势的短篇解析与判断笔记。 -## 核心摘要 +## 字多不看 - 本目录是“观察与判断区”。 -- 内容还没有稳定到可以放入 `concepts/` 或 `references/`，但已经值得记录、分析和跟踪。 -- 本 README 提供稳定锚点和细粒度目录，作为研究笔记的统一入口。 +- 新技术、新技术栈、优秀 repo 和工程范式，先放这里研究。 +- 内容稳定后，再沉淀到 `concepts/` 或 `references/`。 +- 每篇研究笔记先回答：是什么、解决什么问题、是否值得采用、风险在哪里。 -## 总目录 +## 快速导航 1. [Harness 工程解析](#research-harness-engineering) - 工程控制、评估器、反馈闭环与 AI 生成系统可靠性。 @@ -23,16 +24,25 @@ -## 和其他目录的边界 +## 使用方式 + +- 用这里记录还在观察期的新技术、repo、工具趋势和工程范式。 +- 如果内容已经成为稳定概念，迁入 `concepts/`。 +- 如果内容已经变成可执行清单、模板或选型依据，迁入 `references/`。 +- 新增研究时同步补充快速导航、完整细粒度目录、`metadata/taxonomy.yml` 和 AI 引用索引。 + +## 正文 + +### 和其他目录的边界 - 稳定教程放入 `getting-started/` 或 `references/`。 - 核心概念放入 `concepts/`。 - 纯哲学模型放入 `philosophy/`。 -## 维护规则 +### 维护规则 - 本目录采用“线性总文档”结构，正文统一收敛到 `README.md`。 -- 新增内容时优先追加到对应大章节，并同步补充总目录或细粒度目录。 +- 新增内容时优先追加到对应大章节，并同步补充快速导航或完整细粒度目录。 - 不再新增同级主题 `.md` 文件；如确需拆分，必须同步更新全仓索引、AGENTS 与 metadata。 - 目录内只保留 `README.md` 与 `AGENTS.md`。