gavindiaz/vibe-coding-cn
1
0
Fork 0
mirror of https://github.com/tradecatlabs/vibe-coding-cn.git synced 2026-08-04 06:37:44 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: remove references source fragments

Browse Source
This commit is contained in:
tukuaiai
2026-05-05 01:24:00 +08:00
parent 6e3fffd541
commit 3f5f4c968f
15 changed files with 13 additions and 5700 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/workflows/ci.yml
-2
View File
@@ -28,8 +28,6 @@ jobs:
run: python3 scripts/check-local-links.py
- name: Check markdown details and summaries
run: python3 scripts/check-markdown-details.py
- name: Check references README generated state
run: python3 scripts/build-reference-readme.py --check
- name: Check docs README structure
run: python3 scripts/check-doc-structure.py
- name: Check required directory README and AGENTS files
AGENTS.md
+7 -11
View File
@@ -9,7 +9,7 @@
### 允许的操作
- 读取、修改顶层文档：`README.md`、`AGENTS.md`、`CONTRIBUTING.md` 等
- 读取、修改 `docs/`、`prompts/`、`skills/`、`tools/config/`、`tools/external/` 下的文档与代码
- 执行 `make lint`、`make check-links`、`make check-details`、`make check-doc-structure`、`make check-directory-docs`、`make check-metadata`、`make check-ai-citation`、`make sync-doc-toc`、`make sync-reference-readme`、prompts-library 转换工具
- 执行 `make lint`、`make check-links`、`make check-details`、`make check-doc-structure`、`make check-directory-docs`、`make check-metadata`、`make check-ai-citation`、`make sync-doc-toc`、prompts-library 转换工具
- 新增/修改提示词、技能、文档
- 提交符合规范的 commit
@@ -71,8 +71,6 @@ git push origin develop
| `make check-metadata` | 校验 metadata 路径与锚点 | Python 3 |
| `make check-ai-citation` | 校验 llms 与 AI 引用语料路径和锚点 | Python 3 |
| `make sync-doc-toc` | 根据 taxonomy 和文档锚点重建 docs 细粒度目录 | Python 3 |
| `make sync-reference-readme` | 从 `docs/references/sources/` 重建 references 线性总文档 | Python 3 |
| `make check-reference-readme` | 校验 references 线性总文档是否由源片段生成且无漂移 | Python 3 |
| `make test` | 执行本地质量门禁 | Node.js 22+、Python 3 |
| `git submodule update --init --recursive` | 初始化外部 Git 仓库指针 | Git |
| `cd tools/prompts-library && python3 main.py` | 提示词格式转换 | `pip install -r tools/prompts-library/requirements.txt` |
@@ -235,7 +233,6 @@ git push origin develop
- `scripts/check-metadata.py` - metadata 路径与锚点检查脚本，供 `make check-metadata` 与 CI 使用
- `scripts/check-ai-citation.py` - llms 与 AI 引用语料路径和锚点检查脚本，供 `make check-ai-citation` 与 CI 使用
- `scripts/sync-doc-toc.py` - docs 线性 README 细粒度目录重建脚本，供 `make sync-doc-toc` 使用
- `scripts/build-reference-readme.py` - references 线性总文档生成与漂移检查脚本，供 `make sync-reference-readme` 与 `make check-reference-readme` 使用
- `tools/prompts-library/main.py` - 提示词转换工具入口
- `docs/getting-started/README.md` - 从零开始完整入门，包含学习地图、Vibe Coding 经验、网络配置、CLI 配置与开发环境搭建
- `docs/concepts/README.md#concept-problem-solving` - 问题定义与求解路径底层模型
@@ -284,12 +281,11 @@ feat|fix|docs|chore|refactor|test: scope - summary
1. `markdown-lint` - Markdown 格式检查
2. `check local markdown links and anchors` - 仓库内相对链接与锚点检查
3. `check markdown details and summaries` - Markdown 折叠块结构检查
4. `check references README generated state` - references 总文档生成状态检查
5. `check docs README structure` - docs 线性 README 主章节顺序、重复锚点与目录入口检查
6. `check required directory README and AGENTS files` - 仓库自有目录 README/AGENTS 覆盖检查
7. `check metadata paths and anchors` - metadata 路径与锚点检查
8. `check llms and AI citation paths and anchors` - llms 与 AI 引用语料路径和锚点检查
9. `link-checker` - 链接有效性检查
4. `check docs README structure` - docs 线性 README 主章节顺序、重复锚点与目录入口检查
5. `check required directory README and AGENTS files` - 仓库自有目录 README/AGENTS 覆盖检查
6. `check metadata paths and anchors` - metadata 路径与锚点检查
7. `check llms and AI citation paths and anchors` - llms 与 AI 引用语料路径和锚点检查
8. `link-checker` - 链接有效性检查
### 提交前清单
- [ ] 运行 `make lint` 通过
@@ -346,7 +342,7 @@ make test
2. **Conversion Tool**: 使用 Python + pandas + openpyxl
3. **Documentation Standard**: 用户文档使用中文；代码/文件名使用英文
4. **Skills**: 每个技能有独立的 `SKILL.md`
5. **Quality Gates**: `make test` 执行 Markdown lint、本地相对链接/锚点检查、折叠块结构检查、references 生成状态检查、metadata 路径检查与 AI 引用路径检查
5. **Quality Gates**: `make test` 执行 Markdown lint、本地相对链接/锚点检查、折叠块结构检查、docs 结构检查、metadata 路径检查与 AI 引用路径检查
## Development Workflow
Makefile
+2 -12
View File
@@ -1,6 +1,6 @@
# Makefile for Vibe Coding Guide
.PHONY: help lint check-links check-details check-doc-structure check-directory-docs check-metadata check-ai-citation sync-doc-toc sync-reference-readme check-reference-readme build test clean clean-deps
.PHONY: help lint check-links check-details check-doc-structure check-directory-docs check-metadata check-ai-citation sync-doc-toc build test clean clean-deps
MARKDOWNLINT = npx --yes markdownlint-cli@0.48.0
@@ -17,8 +17,6 @@ help:
@echo " check-metadata - Check metadata paths and anchors"
@echo " check-ai-citation - Check llms and AI citation paths and anchors"
@echo " sync-doc-toc - Regenerate docs fine-grained TOC blocks"
@echo " sync-reference-readme - Regenerate docs/references/README.md from source fragments"
@echo " check-reference-readme - Check docs/references/README.md generated state"
@echo " build - Verify knowledge base has no build step"
@echo " test - Run repository quality gates"
@echo " clean - Remove ignored generated caches"
@@ -57,18 +55,10 @@ sync-doc-toc:
@echo "Regenerating docs fine-grained TOC blocks..."
@python3 scripts/sync-doc-toc.py
sync-reference-readme:
@echo "Regenerating docs/references/README.md from source fragments..."
@python3 scripts/build-reference-readme.py
check-reference-readme:
@echo "Checking docs/references/README.md generated state..."
@python3 scripts/build-reference-readme.py --check
build:
@echo "No build step: this repository is a documentation and knowledge-base project."
test: lint check-links check-details check-reference-readme check-doc-structure check-directory-docs check-metadata check-ai-citation
test: lint check-links check-details check-doc-structure check-directory-docs check-metadata check-ai-citation
@echo "Quality gates complete."
clean: clean-deps
README.md
-2
View File
@@ -225,8 +225,6 @@ pip install -r tools/prompts-library/scripts/requirements.txt
| Metadata 路径检查 | `make check-metadata` | `scripts/check-metadata.py` |
| AI 引用路径检查 | `make check-ai-citation` | `scripts/check-ai-citation.py` |
| 重建 docs 细粒度目录 | `make sync-doc-toc` | `scripts/sync-doc-toc.py` |
| 重建 references 线性总文档 | `make sync-reference-readme` | `scripts/build-reference-readme.py` |
| 检查 references 生成状态 | `make check-reference-readme` | `scripts/build-reference-readme.py` |
| 全部本地质量门禁 | `make test` | `Makefile` |
| 提示词格式转换 | `cd tools/prompts-library && python3 main.py` | `tools/prompts-library/main.py` |
| Skill 严格校验示例 | `skills/auto-skill/scripts/validate-skill.sh skills/auto-skill --strict` | `skills/auto-skill/scripts/validate-skill.sh` |
docs/references/AGENTS.md
+3 -5
View File
@@ -15,15 +15,13 @@
```text
references/
├── README.md # 生成后的线性总文档：工程实践、技术栈
├── README.md # 线性总文档：工程实践、技术栈
├── AGENTS.md # 本目录操作规则
└── sources/ # README.md 的有序源片段
```
## 修改规则
- 新增参考资料时，必须追加到 `sources/` 的对应源片段，再运行 `make sync-reference-readme`。
- 不直接编辑 `README.md` 主体内容；它由 `scripts/build-reference-readme.py` 从源片段生成。
- 新增参考资料时，直接追加到 `README.md` 的对应章节。
- 检查清单、模板、质量门禁和经验类内容优先合并进 `工程实践` 章节。
- 技术选型、技术栈组合和学习路径优先合并进 `技术栈` 章节。
- 不在本目录写一次性研究笔记；新技术判断应先放入 `docs/research/`。
@@ -33,4 +31,4 @@ references/
- 参考文档必须可执行、可检查、可复用。
- 门禁类内容尽量转成测试、CI、脚本、schema、类型或检查清单。
- 不确定项必须标注 TODO，不能编造成熟结论。
- 提交前必须运行 `make test`，确保生成状态、锚点、链接和目录结构一致。
- 提交前必须运行 `make test`，确保锚点、链接和目录结构一致。
docs/references/README.md
+1 -3
View File
@@ -7,8 +7,6 @@
## 字多不看
> 生成规则：本文件由 `docs/references/sources/` 按文件名顺序拼接生成；请修改源片段后运行 `make sync-reference-readme`，不要直接编辑总文档主体。
- 本目录回答“具体工程怎么组织、怎么选技术、怎么设置硬门禁”。
- 先看“工程实践”，获得项目架构、代码组织、开发经验、质量门禁和常见坑。
- 再看“技术栈”，完成技术选型、组合案例判断和初学者学习路径设计。
@@ -346,7 +344,7 @@
- 先从 [工程实践](#reference-engineering-practice) 判断项目结构、代码组织、质量门禁和常见坑。
- 再从 [技术栈](#reference-technology-stack) 判断技术选型、组合案例和学习路径。
- 只查具体问题时，优先使用上方“快速导航”和细粒度目录。
- 本 README 是生成文件；新增或调整正文时先改 `docs/references/sources/`。
- 新增或调整参考资料时，直接编辑本 README 的对应章节。
## 正文
docs/references/sources/00-intro.md
-366
View File
@@ -1,366 +0,0 @@
<a id="目录定位"></a>
<a id="顶部导航"></a>
# 参考资料
> `references/` 是工程实践、技术栈、模板、清单、质量门禁和可复用经验的线性手册。
## 字多不看
> 生成规则：本文件由 `docs/references/sources/` 按文件名顺序拼接生成；请修改源片段后运行 `make sync-reference-readme`，不要直接编辑总文档主体。
- 本目录回答“具体工程怎么组织、怎么选技术、怎么设置硬门禁”。
- 先看“工程实践”，获得项目架构、代码组织、开发经验、质量门禁和常见坑。
- 再看“技术栈”，完成技术选型、组合案例判断和初学者学习路径设计。
- 长文档优先走快速导航；需要完整索引时再展开细粒度目录。
## 快速导航
| 目标 | 直接跳转 |
|:---|:---|
| 新项目结构怎么搭 | [项目架构模板](#reference-engineering-practice-1-项目架构模板) |
| AI 代码质量怎么卡住 | [AI 编程质量门禁与常见坑](#quality-gates) |
| 系统提示词怎么写 | [系统提示词构建原则](#reference-engineering-practice-1-系统提示词构建原则) |
| 强前置条件怎么约束 | [强前置条件约束](#reference-engineering-practice-2-强前置条件约束) |
| 常见坑怎么排查 | [常见坑汇总](#reference-engineering-practice-3-常见坑汇总) |
| 底层程序逻辑怎么审 | [底层程序逻辑设计与工程优化项](#reference-engineering-practice-5-底层程序逻辑设计与工程优化项) |
| 技术栈怎么选 | [如何选择技术栈](#tech-stack-selection) |
| 初学者先学什么 | [初学者应该学什么技术栈](#reference-technology-stack-十五初学者应该学什么技术栈) |
<details>
<summary><strong>完整细粒度目录（点击展开/收起）</strong></summary>
### 细粒度目录
- [1. 工程实践](#reference-engineering-practice)
- [核心摘要](#reference-engineering-practice-核心摘要)
- [顶部导航](#reference-engineering-practice-顶部导航)
- [使用方式](#reference-engineering-practice-使用方式)
- [目录](#reference-engineering-practice-目录)
- [1. 项目架构模板](#reference-engineering-practice-1-项目架构模板)
- [1. 使用原则](#reference-engineering-practice-1-使用原则)
- [2. 快速选型](#reference-engineering-practice-2-快速选型)
- [3. Python Web/API 项目结构](#reference-engineering-practice-3-python-webapi-项目结构)
- [4. 数据科学 / 量化项目结构](#reference-engineering-practice-4-数据科学-量化项目结构)
- [5. Monorepo 项目结构](#reference-engineering-practice-5-monorepo-项目结构)
- [6. Full-Stack Web 应用结构](#reference-engineering-practice-6-full-stack-web-应用结构)
- [7. Dataset First 数据服务结构](#reference-engineering-practice-7-dataset-first-数据服务结构)
- [一句话](#reference-engineering-practice-一句话)
- [适合](#reference-engineering-practice-适合)
- [不适合直接照抄](#reference-engineering-practice-不适合直接照抄)
- [核心原则](#reference-engineering-practice-核心原则)
- [标准目录](#reference-engineering-practice-标准目录)
- [Dataset 最小结构](#reference-engineering-practice-dataset-最小结构)
- [Registry 真相矩阵](#reference-engineering-practice-registry-真相矩阵)
- [Dataset 命名](#reference-engineering-practice-dataset-命名)
- [Service Entry 与 Runtime](#reference-engineering-practice-service-entry-与-runtime)
- [数据模型分层](#reference-engineering-practice-数据模型分层)
- [新建数据服务流程](#reference-engineering-practice-新建数据服务流程)
- [外部源码接入流程](#reference-engineering-practice-外部源码接入流程)
- [8. 架构设计原则](#reference-engineering-practice-8-架构设计原则)
- [关注点分离](#reference-engineering-practice-关注点分离)
- [可测试性](#reference-engineering-practice-可测试性)
- [可配置性](#reference-engineering-practice-可配置性)
- [可维护性](#reference-engineering-practice-可维护性)
- [版本控制友好](#reference-engineering-practice-版本控制友好)
- [9. 最低门禁](#reference-engineering-practice-9-最低门禁)
- [代码门禁](#reference-engineering-practice-代码门禁)
- [结构门禁](#reference-engineering-practice-结构门禁)
- [运行门禁](#reference-engineering-practice-运行门禁)
- [数据门禁](#reference-engineering-practice-数据门禁)
- [文档门禁](#reference-engineering-practice-文档门禁)
- [10. `.gitignore` 推荐模板](#reference-engineering-practice-10-gitignore-推荐模板)
- [11. 技术选型参考](#reference-engineering-practice-11-技术选型参考)
- [12. 新项目检查清单](#reference-engineering-practice-12-新项目检查清单)
- [13. 常见反模式](#reference-engineering-practice-13-常见反模式)
- [14. 一句话结论](#reference-engineering-practice-14-一句话结论)
- [2. 代码组织](#reference-engineering-practice-2-代码组织)
- [模块化编程](#reference-engineering-practice-模块化编程)
- [命名规范](#reference-engineering-practice-命名规范)
- [代码注释](#reference-engineering-practice-代码注释)
- [代码格式化](#reference-engineering-practice-代码格式化)
- [文档](#reference-engineering-practice-文档)
- [文档字符串](#reference-engineering-practice-文档字符串)
- [自动化文档生成](#reference-engineering-practice-自动化文档生成)
- [README 文件](#reference-engineering-practice-readme-文件)
- [工具](#reference-engineering-practice-工具)
- [IDE](#reference-engineering-practice-ide)
- [3. 开发经验](#reference-engineering-practice-3-开发经验)
- [目录](#reference-engineering-practice-目录-2)
- [**1. 变量名维护方案**](#reference-engineering-practice-1-变量名维护方案)
- [1.1 新建“变量名大全文件”](#reference-engineering-practice-11-新建变量名大全文件)
- [文件内容包括（格式示例）：](#reference-engineering-practice-文件内容包括格式示例)
- [目的](#reference-engineering-practice-目的)
- [**2. 文件结构与命名规范**](#reference-engineering-practice-2-文件结构与命名规范)
- [2.1 子文件夹内容](#reference-engineering-practice-21-子文件夹内容)
- [2.2 文件命名规则](#reference-engineering-practice-22-文件命名规则)
- [2.3 变量与定义规则及解释](#reference-engineering-practice-23-变量与定义规则及解释)
- [**3. 编码规范**](#reference-engineering-practice-3-编码规范)
- [3.1 单一职责（Single Responsibility）](#reference-engineering-practice-31-单一职责single-responsibility)
- [3.2 可复用函数 / 构建（Reusable Components）](#reference-engineering-practice-32-可复用函数-构建reusable-components)
- [3.3 消费端 / 生产端 / 状态（变量）/ 变换（函数）](#reference-engineering-practice-33-消费端-生产端-状态变量-变换函数)
- [3.4 并发（Concurrency）](#reference-engineering-practice-34-并发concurrency)
- [**4. 系统架构原则**](#reference-engineering-practice-4-系统架构原则)
- [4.1 先梳理清楚架构](#reference-engineering-practice-41-先梳理清楚架构)
- [4.2 理解需求 → 保持简单 → 自动化测试 → 小步迭代](#reference-engineering-practice-42-理解需求-保持简单-自动化测试-小步迭代)
- [**5. 程序设计核心思想**](#reference-engineering-practice-5-程序设计核心思想)
- [5.1 从问题开始，而不是从代码开始](#reference-engineering-practice-51-从问题开始而不是从代码开始)
- [5.2 大问题拆小问题（Divide & Conquer）](#reference-engineering-practice-52-大问题拆小问题divide-conquer)
- [5.3 KISS 原则（保持简单）](#reference-engineering-practice-53-kiss-原则保持简单)
- [5.4 DRY 原则（不要重复）](#reference-engineering-practice-54-dry-原则不要重复)
- [5.5 清晰的命名](#reference-engineering-practice-55-清晰的命名)
- [5.6 单一职责](#reference-engineering-practice-56-单一职责)
- [5.7 代码可读性优先](#reference-engineering-practice-57-代码可读性优先)
- [5.8 合理注释](#reference-engineering-practice-58-合理注释)
- [5.9 Make it work → Make it right → Make it fast](#reference-engineering-practice-59-make-it-work-make-it-right-make-it-fast)
- [5.10 错误是朋友，调试是必修课](#reference-engineering-practice-510-错误是朋友调试是必修课)
- [5.11 Git 版本控制是必备技能](#reference-engineering-practice-511-git-版本控制是必备技能)
- [5.12 测试你的代码](#reference-engineering-practice-512-测试你的代码)
- [5.13 编程是长期练习](#reference-engineering-practice-513-编程是长期练习)
- [**6. 微服务**](#reference-engineering-practice-6-微服务)
- [**7. Redis（缓存 / 内存数据库）**](#reference-engineering-practice-7-redis缓存-内存数据库)
- [**8. 消息队列（Message Queue）**](#reference-engineering-practice-8-消息队列message-queue)
- [4. AI 编程质量门禁与常见坑](#reference-engineering-practice-4-ai-编程质量门禁与常见坑)
- [使用方式](#reference-engineering-practice-使用方式-2)
- [目录](#reference-engineering-practice-目录-3)
- [1. 系统提示词构建原则](#reference-engineering-practice-1-系统提示词构建原则)
- [核心身份与行为准则](#reference-engineering-practice-核心身份与行为准则)
- [沟通与互动](#reference-engineering-practice-沟通与互动)
- [任务执行与工作流](#reference-engineering-practice-任务执行与工作流)
- [技术与编码规范](#reference-engineering-practice-技术与编码规范)
- [安全与防护](#reference-engineering-practice-安全与防护)
- [工具使用](#reference-engineering-practice-工具使用)
- [2. 强前置条件约束](#reference-engineering-practice-2-强前置条件约束)
- [通用开发约束](#reference-engineering-practice-通用开发约束)
- [胶水开发约束](#reference-engineering-practice-胶水开发约束)
- [系统性代码与功能完整性检查约束](#reference-engineering-practice-系统性代码与功能完整性检查约束)
- [一、AI 编码常见伪高性能错误](#reference-engineering-practice-一ai-编码常见伪高性能错误)
- [二、AI 容易生成的隐藏低效逻辑](#reference-engineering-practice-二ai-容易生成的隐藏低效逻辑)
- [三、新手常见复杂度误区](#reference-engineering-practice-三新手常见复杂度误区)
- [四、Python 语法糖误用](#reference-engineering-practice-四python-语法糖误用)
- [五、错误的数据结构直觉](#reference-engineering-practice-五错误的数据结构直觉)
- [六、缓存误用](#reference-engineering-practice-六缓存误用)
- [七、异步误用](#reference-engineering-practice-七异步误用)
- [八、多线程 / 多进程误用](#reference-engineering-practice-八多线程-多进程误用)
- [九、NumPy 新手错误](#reference-engineering-practice-九numpy-新手错误)
- [十、pandas 新手错误](#reference-engineering-practice-十pandas-新手错误)
- [十一、PyTorch / 深度学习新手错误](#reference-engineering-practice-十一pytorch-深度学习新手错误)
- [十二、GPU 使用新手错误](#reference-engineering-practice-十二gpu-使用新手错误)
- [十三、JIT / 编译工具误用](#reference-engineering-practice-十三jit-编译工具误用)
- [十四、数据库与 ORM 新手错误](#reference-engineering-practice-十四数据库与-orm-新手错误)
- [十五、网络请求新手错误](#reference-engineering-practice-十五网络请求新手错误)
- [十六、文件与序列化新手错误](#reference-engineering-practice-十六文件与序列化新手错误)
- [十七、日志与观测误用](#reference-engineering-practice-十七日志与观测误用)
- [十八、Benchmark 新手错误](#reference-engineering-practice-十八benchmark-新手错误)
- [十九、资源配置新手错误](#reference-engineering-practice-十九资源配置新手错误)
- [二十、AI 最容易“自信瞎优化”的错误](#reference-engineering-practice-二十ai-最容易自信瞎优化的错误)
- [二十一、适合直接放进全局规则的总禁止池](#reference-engineering-practice-二十一适合直接放进全局规则的总禁止池)
- [一、数值计算反例](#reference-engineering-practice-一数值计算反例)
- [二、内存布局与缓存局部性反例](#reference-engineering-practice-二内存布局与缓存局部性反例)
- [三、BLAS / LAPACK / 矩阵计算反例](#reference-engineering-practice-三blas-lapack-矩阵计算反例)
- [四、JIT / 编译加速反例](#reference-engineering-practice-四jit-编译加速反例)
- [五、并行计算反例](#reference-engineering-practice-五并行计算反例)
- [六、共享内存与进程间通信反例](#reference-engineering-practice-六共享内存与进程间通信反例)
- [七、GPU / CUDA / 深度学习反例](#reference-engineering-practice-七gpu-cuda-深度学习反例)
- [八、PyTorch / TensorFlow 反例](#reference-engineering-practice-八pytorch-tensorflow-反例)
- [九、大数据与分布式计算反例](#reference-engineering-practice-九大数据与分布式计算反例)
- [十、文件格式与数据读取反例](#reference-engineering-practice-十文件格式与数据读取反例)
- [十一、性能测量反例](#reference-engineering-practice-十一性能测量反例)
- [十二、资源控制反例](#reference-engineering-practice-十二资源控制反例)
- [十三、Python 高性能计算精简总版](#reference-engineering-practice-十三python-高性能计算精简总版)
- [一、最高优先级禁止](#reference-engineering-practice-一最高优先级禁止)
- [二、推理与决策禁止](#reference-engineering-practice-二推理与决策禁止)
- [三、工程质量禁止](#reference-engineering-practice-三工程质量禁止)
- [四、代码实现禁止](#reference-engineering-practice-四代码实现禁止)
- [五、验证与测试禁止](#reference-engineering-practice-五验证与测试禁止)
- [六、工具调用禁止](#reference-engineering-practice-六工具调用禁止)
- [七、不可逆与高风险操作禁止](#reference-engineering-practice-七不可逆与高风险操作禁止)
- [八、架构与文档禁止](#reference-engineering-practice-八架构与文档禁止)
- [九、任务管理禁止](#reference-engineering-practice-九任务管理禁止)
- [十、沟通与输出禁止](#reference-engineering-practice-十沟通与输出禁止)
- [十一、协作与版本控制禁止](#reference-engineering-practice-十一协作与版本控制禁止)
- [十二、性能与设计哲学禁止](#reference-engineering-practice-十二性能与设计哲学禁止)
- [十三、可直接合并进你的「全局禁止池」精简版](#reference-engineering-practice-十三可直接合并进你的全局禁止池精简版)
- [建议删除或不要加入禁止池的内容](#reference-engineering-practice-建议删除或不要加入禁止池的内容)
- [一、输出完整性类](#reference-engineering-practice-一输出完整性类)
- [二、逻辑正确性类](#reference-engineering-practice-二逻辑正确性类)
- [三、性能类](#reference-engineering-practice-三性能类)
- [四、安全类](#reference-engineering-practice-四安全类)
- [五、代码质量类](#reference-engineering-practice-五代码质量类)
- [六、依赖与环境类](#reference-engineering-practice-六依赖与环境类)
- [七、测试与验证类](#reference-engineering-practice-七测试与验证类)
- [八、数据与状态类](#reference-engineering-practice-八数据与状态类)
- [九、用户体验类](#reference-engineering-practice-九用户体验类)
- [十、工程交付类](#reference-engineering-practice-十工程交付类)
- [十一、AI 编码行为类](#reference-engineering-practice-十一ai-编码行为类)
- [十二、推荐你整理成最终版“全局禁止池”](#reference-engineering-practice-十二推荐你整理成最终版全局禁止池)
- [3. 常见坑汇总](#reference-engineering-practice-3-常见坑汇总)
- [先查资料，再写代码](#reference-engineering-practice-先查资料再写代码)
- [为什么要用虚拟环境？](#reference-engineering-practice-为什么要用虚拟环境)
- [创建和使用 .venv](#reference-engineering-practice-创建和使用-venv)
- [常见问题](#reference-engineering-practice-常见问题)
- [一键重置环境](#reference-engineering-practice-一键重置环境)
- [常见问题](#reference-engineering-practice-常见问题-2)
- [常用命令](#reference-engineering-practice-常用命令)
- [终端代理配置](#reference-engineering-practice-终端代理配置)
- [常用 Git 命令](#reference-engineering-practice-常用-git-命令)
- [🔥 终极解决方案](#reference-engineering-practice-终极解决方案)
- [📝 贡献](#reference-engineering-practice-贡献)
- [5. 底层程序逻辑设计与工程优化项](#reference-engineering-practice-5-底层程序逻辑设计与工程优化项)
- [2. 技术栈](#reference-technology-stack)
- [核心摘要](#reference-technology-stack-核心摘要)
- [顶部导航](#reference-technology-stack-顶部导航)
- [使用方式](#reference-technology-stack-使用方式)
- [一、什么是技术栈](#reference-technology-stack-一什么是技术栈)
- [二、技术栈通常包含哪些部分](#reference-technology-stack-二技术栈通常包含哪些部分)
- [1. 前端技术栈](#reference-technology-stack-1-前端技术栈)
- [基础语言](#reference-technology-stack-基础语言)
- [前端框架](#reference-technology-stack-前端框架)
- [UI 框架和组件库](#reference-technology-stack-ui-框架和组件库)
- [构建工具](#reference-technology-stack-构建工具)
- [状态管理](#reference-technology-stack-状态管理)
- [前端路由](#reference-technology-stack-前端路由)
- [前端请求工具](#reference-technology-stack-前端请求工具)
- [前端测试](#reference-technology-stack-前端测试)
- [前端常见组合](#reference-technology-stack-前端常见组合)
- [2. 后端技术栈](#reference-technology-stack-2-后端技术栈)
- [常见后端语言](#reference-technology-stack-常见后端语言)
- [Java 后端](#reference-technology-stack-java-后端)
- [Python 后端](#reference-technology-stack-python-后端)
- [Node.js 后端](#reference-technology-stack-nodejs-后端)
- [Go 后端](#reference-technology-stack-go-后端)
- [PHP 后端](#reference-technology-stack-php-后端)
- [C# 后端](#reference-technology-stack-c-后端)
- [3. 数据库技术栈](#reference-technology-stack-3-数据库技术栈)
- [关系型数据库](#reference-technology-stack-关系型数据库)
- [非关系型数据库](#reference-technology-stack-非关系型数据库)
- [文档数据库](#reference-technology-stack-文档数据库)
- [键值数据库](#reference-technology-stack-键值数据库)
- [搜索引擎](#reference-technology-stack-搜索引擎)
- [图数据库](#reference-technology-stack-图数据库)
- [时序数据库](#reference-technology-stack-时序数据库)
- [三、移动端技术栈](#reference-technology-stack-三移动端技术栈)
- [iOS 原生开发](#reference-technology-stack-ios-原生开发)
- [Android 原生开发](#reference-technology-stack-android-原生开发)
- [跨平台移动开发](#reference-technology-stack-跨平台移动开发)
- [四、桌面端技术栈](#reference-technology-stack-四桌面端技术栈)
- [五、全栈技术栈](#reference-technology-stack-五全栈技术栈)
- [MERN](#reference-technology-stack-mern)
- [MEAN](#reference-technology-stack-mean)
- [MEVN](#reference-technology-stack-mevn)
- [PERN](#reference-technology-stack-pern)
- [T3 Stack](#reference-technology-stack-t3-stack)
- [Django 全栈](#reference-technology-stack-django-全栈)
- [Spring Boot 全栈](#reference-technology-stack-spring-boot-全栈)
- [六、DevOps 和部署技术栈](#reference-technology-stack-六devops-和部署技术栈)
- [操作系统](#reference-technology-stack-操作系统)
- [Web 服务器](#reference-technology-stack-web-服务器)
- [容器技术](#reference-technology-stack-容器技术)
- [容器编排](#reference-technology-stack-容器编排)
- [CI/CD](#reference-technology-stack-cicd)
- [云平台](#reference-technology-stack-云平台)
- [基础设施即代码](#reference-technology-stack-基础设施即代码)
- [监控和日志](#reference-technology-stack-监控和日志)
- [七、AI / 机器学习技术栈](#reference-technology-stack-七ai-机器学习技术栈)
- [编程语言](#reference-technology-stack-编程语言)
- [数据处理](#reference-technology-stack-数据处理)
- [机器学习](#reference-technology-stack-机器学习)
- [深度学习](#reference-technology-stack-深度学习)
- [大模型应用](#reference-technology-stack-大模型应用)
- [向量数据库](#reference-technology-stack-向量数据库)
- [MLOps](#reference-technology-stack-mlops)
- [八、数据工程技术栈](#reference-technology-stack-八数据工程技术栈)
- [数据采集](#reference-technology-stack-数据采集)
- [数据存储](#reference-technology-stack-数据存储)
- [数据计算](#reference-technology-stack-数据计算)
- [数据仓库](#reference-technology-stack-数据仓库)
- [数据调度](#reference-technology-stack-数据调度)
- [数据可视化](#reference-technology-stack-数据可视化)
- [九、游戏开发技术栈](#reference-technology-stack-九游戏开发技术栈)
- [游戏引擎](#reference-technology-stack-游戏引擎)
- [游戏开发语言](#reference-technology-stack-游戏开发语言)
- [图形技术](#reference-technology-stack-图形技术)
- [常见组合](#reference-technology-stack-常见组合)
- [十、嵌入式和物联网技术栈](#reference-technology-stack-十嵌入式和物联网技术栈)
- [编程语言](#reference-technology-stack-编程语言-2)
- [硬件平台](#reference-technology-stack-硬件平台)
- [操作系统](#reference-technology-stack-操作系统-2)
- [通信协议](#reference-technology-stack-通信协议)
- [十一、区块链技术栈](#reference-technology-stack-十一区块链技术栈)
- [智能合约语言](#reference-technology-stack-智能合约语言)
- [区块链平台](#reference-technology-stack-区块链平台)
- [开发工具](#reference-technology-stack-开发工具)
- [Web3 前端](#reference-technology-stack-web3-前端)
- [十二、网络安全技术栈](#reference-technology-stack-十二网络安全技术栈)
- [安全测试](#reference-technology-stack-安全测试)
- [安全开发](#reference-technology-stack-安全开发)
- [安全监控](#reference-technology-stack-安全监控)
- [代码安全](#reference-technology-stack-代码安全)
- [十三、常见项目对应技术栈](#reference-technology-stack-十三常见项目对应技术栈)
- [个人博客](#reference-technology-stack-个人博客)
- [企业官网](#reference-technology-stack-企业官网)
- [后台管理系统](#reference-technology-stack-后台管理系统)
- [电商系统](#reference-technology-stack-电商系统)
- [即时聊天系统](#reference-technology-stack-即时聊天系统)
- [在线教育平台](#reference-technology-stack-在线教育平台)
- [SaaS 系统](#reference-technology-stack-saas-系统)
- [AI 聊天机器人](#reference-technology-stack-ai-聊天机器人)
- [短视频平台](#reference-technology-stack-短视频平台)
- [物联网平台](#reference-technology-stack-物联网平台)
- [十四、如何选择技术栈](#reference-technology-stack-十四如何选择技术栈)
- [1. 项目类型](#reference-technology-stack-1-项目类型)
- [2. 团队能力](#reference-technology-stack-2-团队能力)
- [3. 项目规模](#reference-technology-stack-3-项目规模)
- [4. 性能要求](#reference-technology-stack-4-性能要求)
- [5. 成本](#reference-technology-stack-5-成本)
- [6. 生态成熟度](#reference-technology-stack-6-生态成熟度)
- [十五、初学者应该学什么技术栈](#reference-technology-stack-十五初学者应该学什么技术栈)
- [如果你想做网页前端](#reference-technology-stack-如果你想做网页前端)
- [如果你想做后端](#reference-technology-stack-如果你想做后端)
- [如果你想做全栈](#reference-technology-stack-如果你想做全栈)
- [路线一：JavaScript / TypeScript 全栈](#reference-technology-stack-路线一javascript-typescript-全栈)
- [路线二：Java 企业全栈](#reference-technology-stack-路线二java-企业全栈)
- [如果你想做 AI](#reference-technology-stack-如果你想做-ai)
- [十六、技术栈的层级结构](#reference-technology-stack-十六技术栈的层级结构)
- [十七、技术栈示例总表](#reference-technology-stack-十七技术栈示例总表)
- [十八、常见误区](#reference-technology-stack-十八常见误区)
- [误区一：技术栈越多越厉害](#reference-technology-stack-误区一技术栈越多越厉害)
- [误区二：只追求最新技术](#reference-technology-stack-误区二只追求最新技术)
- [误区三：前端只会框架，不懂基础](#reference-technology-stack-误区三前端只会框架不懂基础)
- [误区四：后端只会写接口，不懂数据库](#reference-technology-stack-误区四后端只会写接口不懂数据库)
- [误区五：会技术栈等于会做项目](#reference-technology-stack-误区五会技术栈等于会做项目)
- [十九、一个完整 Web 项目的技术栈案例](#reference-technology-stack-十九一个完整-web-项目的技术栈案例)
- [前端](#reference-technology-stack-前端)
- [后端](#reference-technology-stack-后端)
- [数据库](#reference-technology-stack-数据库)
- [文件存储](#reference-technology-stack-文件存储)
- [部署](#reference-technology-stack-部署)
- [监控](#reference-technology-stack-监控)
- [二十、面试中如何介绍自己的技术栈](#reference-technology-stack-二十面试中如何介绍自己的技术栈)
- [二十一、总结](#reference-technology-stack-二十一总结)
</details>
## 使用方式
- 先从 [工程实践](#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`。
---
docs/references/sources/10-engineering-practice.md
-3491
View File
File diff suppressed because it is too large Load Diff
docs/references/sources/20-technology-stack.md
-1695
View File
File diff suppressed because it is too large Load Diff
docs/references/sources/AGENTS.md
-19
View File
@@ -1,19 +0,0 @@
# References Sources Agent 指南
## 目录职责
`docs/references/sources/` 是 `docs/references/README.md` 的唯一正文来源。
## 修改规则
- 不直接编辑 `docs/references/README.md` 的主体内容。
- 新增或调整参考资料时，先修改本目录中的有序源片段。
- 文件名前缀用于控制总文档顺序，例如 `00-`、`10-`、`20-`。
- 修改后运行 `make sync-reference-readme` 生成总文档。
- 提交前运行 `make test`，确认生成结果、锚点、链接和目录结构全部通过。
## 边界
- 工程经验、质量门禁、模板和常见坑归入 `10-engineering-practice.md`。
- 技术栈选型、组合方案和学习路径归入 `20-technology-stack.md`。
- 新技术、技术栈或优秀 repo 的短篇判断笔记先放入 `docs/research/`，稳定后再沉淀到 references。
docs/references/sources/README.md
-16
View File
@@ -1,16 +0,0 @@
# References Sources
本目录存放 `docs/references/README.md` 的源片段。
生成规则：
- `README.md` 与 `AGENTS.md` 不参与拼接。
- 其他 `*.md` 文件按文件名升序拼接。
- 修改源片段后运行 `make sync-reference-readme`。
- 提交前运行 `make test`，确保总文档与源片段一致。
当前片段：
- `00-intro.md`：参考资料总入口、常用入口、总目录和维护规则。
- `10-engineering-practice.md`：工程实践、项目架构、代码组织、开发经验、质量门禁和常见坑。
- `20-technology-stack.md`：技术栈选型、组合案例和学习路径。
scripts/AGENTS.md
-1
View File
@@ -8,7 +8,6 @@
- 新增检查脚本时，同步更新 `scripts/README.md`、`Makefile`、CI 和根目录 `AGENTS.md` 的命令清单。
- `check-directory-docs.py` 对根 `.github/` 只要求 `AGENTS.md`，不要重新补 `.github/README.md`。
- 修改 docs 线性 README 的主章节或锚点后，优先运行 `python3 scripts/sync-doc-toc.py`，再运行 `make test`。
- 修改 `docs/references/sources/` 后，运行 `make sync-reference-readme`，再运行 `make test`。
- 检查失败输出应包含文件路径、行号或可定位的错误信息。
- 跳过目录必须明确，至少跳过 `.git`、`.history`、`node_modules` 和外部源码快照。
scripts/README.md
-1
View File
@@ -11,4 +11,3 @@
- `check-metadata.py`：`metadata/taxonomy.yml` 与 `metadata/redirects.yml` 路径和锚点检查脚本。
- `check-ai-citation.py`：`llms.txt`、`assets/ai-citation/llms-full.txt` 与 AI 引用语料路径和锚点检查脚本。
- `sync-doc-toc.py`：根据 `metadata/taxonomy.yml` 和文档锚点重建 docs 线性 README 的完整细粒度目录。
- `build-reference-readme.py`：根据 `docs/references/sources/*.md` 生成并校验 `docs/references/README.md`。
scripts/build-reference-readme.py
-70
View File
@@ -1,70 +0,0 @@
#!/usr/bin/env python3
"""Build docs/references/README.md from ordered source fragments."""
from __future__ import annotations
import argparse
import sys
from pathlib import Path
ROOT = Path(__file__).resolve().parents[1]
SOURCE_DIR = ROOT / "docs" / "references" / "sources"
TARGET = ROOT / "docs" / "references" / "README.md"
EXCLUDED_SOURCE_NAMES = {"README.md", "AGENTS.md"}
def iter_source_files() -> list[Path]:
if not SOURCE_DIR.exists():
raise FileNotFoundError(f"source directory not found: {SOURCE_DIR}")
files = sorted(
path
for path in SOURCE_DIR.glob("*.md")
if path.name not in EXCLUDED_SOURCE_NAMES
)
if not files:
raise FileNotFoundError(f"no source fragments found in: {SOURCE_DIR}")
return files
def build_content() -> str:
parts: list[str] = []
for path in iter_source_files():
content = path.read_text(encoding="utf-8").strip()
if content:
parts.append(content)
return "\n\n".join(parts).rstrip() + "\n"
def main() -> int:
parser = argparse.ArgumentParser(
description="Build docs/references/README.md from docs/references/sources/*.md."
)
parser.add_argument(
"--check",
action="store_true",
help="Fail if docs/references/README.md is not synced with source fragments.",
)
args = parser.parse_args()
expected = build_content()
if args.check:
actual = TARGET.read_text(encoding="utf-8") if TARGET.exists() else ""
if actual != expected:
print(
"docs/references/README.md is out of sync. "
"Run `make sync-reference-readme`.",
file=sys.stderr,
)
return 1
print("docs/references/README.md is synced with source fragments.")
return 0
TARGET.write_text(expected, encoding="utf-8")
print(f"wrote {TARGET.relative_to(ROOT)}")
return 0
if __name__ == "__main__":
raise SystemExit(main())
scripts/check-local-links.py
-6
View File
@@ -16,10 +16,6 @@ SKIP_PREFIXES = [
Path("tools/external"),
Path("tools/chat-vault"),
]
GENERATED_SOURCE_DIRS = {
Path("docs/references/sources"),
}
SOURCE_DOC_NAMES = {"README.md", "AGENTS.md"}
LINK_PATTERNS = [
re.compile(r"!??\[[^\]]*\]\(([^)]+)\)"),
re.compile(r"\b(?:href|src)=[\"']([^\"']+)[\"']"),
@@ -105,8 +101,6 @@ def should_skip(path: Path) -> bool:
rel = path.relative_to(ROOT)
if any(part in SKIP_PARTS for part in rel.parts):
return True
if rel.parent in GENERATED_SOURCE_DIRS and rel.name not in SOURCE_DOC_NAMES:
return True
return any(rel == prefix or prefix in rel.parents for prefix in SKIP_PREFIXES)