docs: strengthen knowledge base indexes

2026-08-15 11:58:04 +00:00 · 2026-05-03 03:35:57 +08:00
parent 44c0c054dc
commit 24c94bc35d
12 changed files with 270 additions and 41 deletions
@@ -1,25 +1,90 @@
 # 知识库总索引

-> `docs/` 是本仓库的核心知识库入口，承载从入门路径、核心概念到参考清单的全部文档。
+> `docs/` 是本仓库的核心知识库入口，承载从零开始、核心概念、哲学模型、研究笔记和工程参考资料。

-## 目录结构
+## 目录地图

-| 目录 | 用途 |
-|:---|:---|
-| [getting-started](./getting-started/) | 从零开始、学习地图、环境配置与默认 AI CLI 路线 |
-| [concepts](./concepts/) | Vibe Coding、拼好码、问题求解、语言层、工程范式等核心概念 |
-| [philosophy](./philosophy/) | 哲学方法论、思维模型、编程哲学与底层认知模型 |
-| [research](./research/) | 新技术、技术栈、优秀 repo、工程范式和工具趋势的短篇研究 |
-| [references](./references/) | 清单、模板、强约束与常见坑 |
+| 目录 | 定位 | 首选入口 |
+|:---|:---|:---|
+| [getting-started](./getting-started/) | 从零开始的线性入门教程 | [从零开始完整入门](./getting-started/README.md) |
+| [concepts](./concepts/) | 核心概念、问题求解与工程思想 | [核心概念索引](./concepts/README.md) |
+| [philosophy](./philosophy/) | 哲学方法论、思维模型与底层认知模型 | [哲学方法论工具箱](./philosophy/README.md) |
+| [references](./references/) | 工程实践、技术栈、模板和检查清单 | [参考资料索引](./references/README.md) |
+| [research](./research/) | 新技术、优秀 repo 与工程范式研究 | [研究笔记索引](./research/README.md) |

-## 推荐入口
+## 推荐阅读路径
+
+### 新手路径

 1. [从零开始完整入门](./getting-started/README.md)
 2. [问题求解](./concepts/问题求解.md)
-3. [思维模型](./philosophy/思维模型.md)
-4. [组合描述模型](./philosophy/组合描述模型.md)
-5. [拼好码](./concepts/拼好码.md)
-6. [工程实践](./references/工程实践.md)
-7. [技术栈](./references/技术栈.md)
-8. [技术研究](./research/README.md)
-9. [哲学方法论](./philosophy/README.md)
+3. [拼好码](./concepts/拼好码.md)
+4. [工程实践](./references/工程实践.md)
+
+### 开发者路径
+
+1. [拼好码](./concepts/拼好码.md)
+2. [系统构建方法](./concepts/系统构建方法.md)
+3. [技术栈](./references/技术栈.md)
+4. [工程实践](./references/工程实践.md)
+
+### 思维模型路径
+
+1. [思维模型](./philosophy/思维模型.md)
+2. [组合描述模型](./philosophy/组合描述模型.md)
+3. [编程之道](./philosophy/编程之道.md)
+4. [递归自优化系统](./concepts/递归自优化系统.md)
+
+### AI Agent 读取路径
+
+1. [根目录 AGENTS](../AGENTS.md)
+2. [docs 目录 AGENTS](./AGENTS.md)
+3. [从零开始完整入门](./getting-started/README.md)
+4. [工程实践](./references/工程实践.md)
+5. [AI 引用语料](../assets/ai-citation/README.md)
+
+## 全部文档索引
+
+### getting-started
+
+- [README](./getting-started/README.md) - 从零开始完整入门，包含学习地图、Vibe Coding 经验、网络配置、CLI 配置与开发环境搭建。
+- [AGENTS](./getting-started/AGENTS.md) - 入门教程目录操作规则。
+
+### concepts
+
+- [README](./concepts/README.md) - 核心概念索引。
+- [AGENTS](./concepts/AGENTS.md) - 核心概念目录操作规则。
+- [问题求解](./concepts/问题求解.md) - 用目标、现状、差距、标准、约束、对象和路径定义问题。
+- [拼好码](./concepts/拼好码.md) - 复用成熟能力，用胶水代码连接、编排、适配业务流程。
+- [系统构建方法](./concepts/系统构建方法.md) - 自顶向下、自底向上与分而治之的组合使用。
+- [开发范式演进](./concepts/开发范式演进.md) - 软件工程组织方式的演进。
+- [语言层要素](./concepts/语言层要素.md) - 看懂代码需要掌握的语言层要素。
+- [递归自优化系统](./concepts/递归自优化系统.md) - 递归自优化生成系统的形式化模型。
+
+### philosophy
+
+- [README](./philosophy/README.md) - 哲学方法论工具箱。
+- [AGENTS](./philosophy/AGENTS.md) - 哲学方法论目录操作规则。
+- [思维模型](./philosophy/思维模型.md) - 可复用思维模型索引。
+- [组合描述模型](./philosophy/组合描述模型.md) - 用对象、状态、快照、序列、过程、变换、同一/差异与关系描述复杂系统。
+- [编程之道](./philosophy/编程之道.md) - 编程哲学与工程判断。
+
+### references
+
+- [README](./references/README.md) - 参考资料索引。
+- [AGENTS](./references/AGENTS.md) - 参考资料目录操作规则。
+- [工程实践](./references/工程实践.md) - 项目架构、代码组织、开发经验、质量门禁与常见坑。
+- [技术栈](./references/技术栈.md) - 技术栈选型、组合案例与初学者学习路径。
+
+### research
+
+- [README](./research/README.md) - 研究笔记索引。
+- [AGENTS](./research/AGENTS.md) - 研究笔记目录操作规则。
+- [Harness 工程解析](./research/Harness工程解析.md) - Harness Engineering 的工程控制、评估器与反馈闭环解析。
+
+## 维护规则
+
+- 每个目录必须同时维护 `README.md` 和 `AGENTS.md`。
+- 新增、删除、移动、重命名文档时，必须同步更新本索引、所在目录索引和 `metadata/taxonomy.yml`。
+- 面向 AI 引用的重要入口变化，必须同步更新 `assets/ai-citation/llms-full.txt` 和相关摘要文件。
+- 不确定信息标注 TODO，不用猜测补齐。
@@ -2,6 +2,24 @@

 > 本文件合并原 `学习地图.md`、`Vibe Coding 经验.md`、`网络环境配置.md`、`CLI配置.md` 与 `开发环境搭建.md`，作为零基础到独立交付项目的线性入门版本。

+## 核心摘要
+
+这是一条面向新电脑和零基础用户的线性路线：先解决网络环境与 Codex / ChatGPT 订阅，再跑通 Codex CLI，随后让本地 Agent 主动检查和配置 Git、Node.js、Python、编辑器、项目依赖、测试命令和 Git 工作流。
+
+本文件的目标不是让用户手工记住所有安装细节，而是让用户先获得一个可执行的 AI CLI 入口，再用 Agent 带动后续环境配置和项目交付。
+
+## 顶部导航
+
+| 章节 | 解决的问题 |
+|:---|:---|
+| [使用方式](#使用方式) | 不会操作时如何让网页 AI 生成逐步执行方案 |
+| [最短路径：先跑通 Codex CLI](#最短路径先跑通-codex-cli) | 为什么先配置 AI CLI，而不是先手工配置完整开发环境 |
+| [学习地图](#1-学习地图) | 根据新手、开发者、团队、Prompt、Skill、质量门禁和 GEO/SEO 选择路线 |
+| [Vibe Coding 经验](#2-vibe-coding-经验) | 人机分工、门禁、复盘和 AI 审 AI |
+| [网络环境配置](#3-网络环境配置) | OpenAI、GitHub、文档和依赖源访问 |
+| [CLI 配置](#4-cli-配置) | Codex CLI 默认路线与 OpenCode 备选路线 |
+| [开发环境搭建](#5-开发环境搭建) | 让 Agent 主动配置开发依赖、编辑器建议和测试命令 |
+
 ## 使用方式

 从上到下阅读即可：先明确学习路线和人机分工，再解决网络、CLI 与开发环境。遇到卡点时，把当前小节全文、你执行的命令和完整报错一起发给网页版 AI，让它按你的系统生成逐步修复命令。
@@ -1,25 +1,34 @@
-# 🧭 基础指南
+# 参考资料

-> Vibe Coding 的核心理念、原则与方法论
+> `references/` 存放工程实践、技术栈、模板、清单、质量门禁和可复用经验。

-## 📖 核心方法论
+## 目录定位

-### 拼好码（胶水编程的超集）
- [拼好码](../concepts/拼好码.md) - 复用成熟能力，用胶水代码连接、编排、适配业务流程
- [语言层要素](../concepts/语言层要素.md) - 看懂 100% 代码的 8 个层级
+本目录不是入门教程，也不是研究笔记；它负责把已经相对稳定的工程经验整理成可执行、可检查、可复用的参考资料。

-### 理论基础
- [递归自优化系统](../concepts/递归自优化系统.md) - 元方法论
- [编程之道](../philosophy/编程之道.md) - 编程哲学
+| 文件 | 用途 |
+|:---|:---|
+| [工程实践](工程实践.md) | 项目架构、代码组织、开发经验、底层程序逻辑、AI 编程质量门禁与常见坑的统一入口 |
+| [技术栈](技术栈.md) | 软件系统常见技术栈、选型维度、组合案例与初学者学习路径 |
+| [AGENTS](AGENTS.md) | 本目录 Agent 操作规则 |

-### 软件工程基础
- [问题求解](../concepts/问题求解.md) - 目标、现状、差距、标准与反馈迭代的底层能力
- [系统构建方法](../concepts/系统构建方法.md) - 自顶向下、自底向上与分而治之的组合使用
- [开发范式演进](../concepts/开发范式演进.md) - 从面向过程到云原生的工程组织方式演进
+## 相关核心概念

-### 工程实践
- [工程实践](工程实践.md) - 项目架构、代码组织、开发经验、底层程序逻辑、AI 编程质量门禁与常见坑的统一入口
- [技术栈](技术栈.md) - 软件系统常见技术栈、选型维度、组合案例与初学者学习路径
+- [拼好码](../concepts/拼好码.md) - 复用成熟能力，用胶水代码连接、编排、适配业务流程。
+- [问题求解](../concepts/问题求解.md) - 目标、现状、差距、标准与反馈迭代的底层能力。
+- [系统构建方法](../concepts/系统构建方法.md) - 自顶向下、自底向上与分而治之的组合使用。
+- [开发范式演进](../concepts/开发范式演进.md) - 从面向过程到云原生的工程组织方式演进。
+- [语言层要素](../concepts/语言层要素.md) - 看懂代码所需的语言层要素。

-## 🔗 相关资源
- [入门指南](../getting-started/) - 从零开始
+## 相关哲学模型
+
+- [思维模型](../philosophy/思维模型.md) - 第一性原理、奥卡姆剃刀、多阶思维、状态空间等可复用认知工具。
+- [组合描述模型](../philosophy/组合描述模型.md) - 对象、状态、快照、序列、过程、变换、同一/差异与关系。
+- [编程之道](../philosophy/编程之道.md) - 编程哲学与工程判断。
+- [递归自优化系统](../concepts/递归自优化系统.md) - 元方法论与自优化生成系统模型。
+
+## 维护规则
+
+- 检查清单、模板、质量门禁和经验类内容优先收敛到 [工程实践](工程实践.md)。
+- 技术选型、技术栈组合和学习路径优先收敛到 [技术栈](技术栈.md)。
+- 新技术、工具趋势、优秀 repo 解析先放入 [research](../research/README.md)，稳定后再迁入本目录。
@@ -2,6 +2,22 @@

 > 本文档合并原 `项目架构模板.md`、`代码组织.md`、`开发经验.md`、`底层程序逻辑设计与工程优化项.md` 与 `AI编程质量门禁与常见坑.md`，作为项目架构、代码组织、开发经验、底层程序逻辑、AI 编程质量门禁与常见坑的统一入口。

+## 核心摘要
+
+工程实践的核心目标是把“AI 可能写对”变成“系统必须可验证”：任务开始前写清目标、边界和验收标准；实现过程中用拼好码优先复用成熟方案；交付前用测试、CI、脚本、类型、schema、检查清单和代码审查形成硬门禁。
+
+本文件适合作为开发者和 Agent 的工程约束手册：遇到架构设计、代码组织、质量门禁、常见坑、环境问题、Git 操作和项目维护时，优先在这里查规则和检查项。
+
+## 顶部导航
+
+| 主题 | 用途 |
+|:---|:---|
+| [项目架构模板](#1-项目架构模板) | 判断目录、模块、边界和职责是否清楚 |
+| [代码组织](#2-代码组织) | 检查命名、分层、依赖、状态和可维护性 |
+| [开发经验](#3-开发经验) | 沉淀任务推进、协作、复盘和交付经验 |
+| [AI 编程质量门禁与常见坑](#4-ai-编程质量门禁与常见坑) | 把验收标准转成测试、CI、脚本、类型、schema 或清单 |
+| [底层程序逻辑设计与工程优化项](#5-底层程序逻辑设计与工程优化项) | 用运行、并发、数据、性能和可观测模型约束实现 |
+
 ## 使用方式

 - 新项目从「项目架构模板」开始，先确定目录、边界、门禁和检查清单。
@@ -1,6 +1,30 @@
-# 技术栈
-
-# 一、什么是技术栈
+# 技术栈
+
+> 本文件是技术栈参考入口，帮助读者理解软件系统通常由哪些技术层组成、不同场景如何组合技术栈、初学者应该如何选择学习路径。
+
+## 核心摘要
+
+技术栈不是单个框架或语言，而是一组完成系统交付所需的技术组合，包括前端、后端、数据库、缓存、部署、监控、测试、AI、数据工程、安全和运维工具。选择技术栈时，不只看技术是否流行，还要看项目目标、团队能力、维护成本、生态成熟度、部署环境、合规要求和替换路径。
+
+本文件适合三类场景：新手建立技术全景，开发者为项目选型，Agent 在生成方案前理解“应该优先复用哪些成熟技术组合”。
+
+## 顶部导航
+
+| 主题 | 用途 |
+|:---|:---|
+| [什么是技术栈](#一什么是技术栈) | 建立基本概念，理解技术组合而非单点技术 |
+| [技术栈通常包含哪些部分](#二技术栈通常包含哪些部分) | 前端、后端、数据库、部署、AI、数据、安全等层级 |
+| [常见项目对应技术栈](#十三常见项目对应技术栈) | Web、移动端、桌面端、全栈、游戏、数据工程等组合案例 |
+| [如何选择技术栈](#十四如何选择技术栈) | 从目标、约束、团队能力、生态成熟度和长期维护评估方案 |
+| [初学者应该学什么技术栈](#十五初学者应该学什么技术栈) | 从可交付项目出发，选择最小必要技术路线 |
+
+## 使用方式
+
+- 做新项目选型时，先按项目类型定位候选技术栈，再用维护成本和成熟度筛选。
+- 给 AI 提需求时，把目标平台、团队能力、部署环境、数据规模和必须规避的技术写清楚。
+- 当成熟技术栈能满足需求时，遵循拼好码原则，优先复用成熟方案，不默认自研底层能力。
+
+# 一、什么是技术栈

 **技术栈**，英文叫 **Technology Stack**，指开发一个软件系统时使用的一整套技术、框架、语言、工具和平台。

@@ -1528,4 +1552,4 @@ AI 路线：

 > Python + PyTorch + FastAPI + 大模型 API

-真正重要的不是“知道很多技术名词”，而是能用合适的技术栈，把一个项目稳定、清晰、可维护地做出来。
+真正重要的不是“知道很多技术名词”，而是能用合适的技术栈，把一个项目稳定、清晰、可维护地做出来。