From 8e1a32c49937475328c3db817a397c455a39681f Mon Sep 17 00:00:00 2001 From: tukuaiai Date: Mon, 4 May 2026 03:47:52 +0800 Subject: [PATCH] ci: update actions and strengthen docs gates --- .github/workflows/ci.yml | 6 +- .github/workflows/labeler.yml | 4 +- .github/workflows/welcome.yml | 4 +- AGENTS.md | 4 +- Makefile | 15 +- README.md | 1 + assets/ai-citation/llms-full.txt | 4 + docs/concepts/README.md | 89 ++++++----- docs/getting-started/README.md | 4 +- docs/philosophy/README.md | 102 ++++++------- docs/references/README.md | 247 ++++++++++++++++++++++--------- scripts/AGENTS.md | 1 + scripts/README.md | 1 + scripts/check-ai-citation.py | 35 +++++ scripts/check-doc-structure.py | 167 ++++++++++++++++----- scripts/sync-doc-toc.py | 196 ++++++++++++++++++++++++ 16 files changed, 675 insertions(+), 205 deletions(-) create mode 100644 scripts/sync-doc-toc.py diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 782d44f..3ee5b89 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -15,9 +15,9 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout code - uses: actions/checkout@v4 + uses: actions/checkout@v6 - name: Setup Node.js - uses: actions/setup-node@v4 + uses: actions/setup-node@v6 with: node-version: '22' cache: npm @@ -41,7 +41,7 @@ jobs: link-checker: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@v6 - name: Link Checker uses: lycheeverse/lychee-action@v2.8.0 with: diff --git a/.github/workflows/labeler.yml b/.github/workflows/labeler.yml index 1382a4e..91f9501 100644 --- a/.github/workflows/labeler.yml +++ b/.github/workflows/labeler.yml @@ -14,9 +14,9 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout code - uses: actions/checkout@v4 + uses: actions/checkout@v6 - name: Run Labeler - uses: actions/labeler@v4 + uses: actions/labeler@v6 with: repo-token: "${{ secrets.GITHUB_TOKEN }}" configuration-path: .github/labeler.yml diff --git a/.github/workflows/welcome.yml b/.github/workflows/welcome.yml index 1ba3ae1..2e5d42b 100644 --- a/.github/workflows/welcome.yml +++ b/.github/workflows/welcome.yml @@ -18,7 +18,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Welcome new contributor - uses: actions/first-interaction@v1 + uses: actions/first-interaction@v3 with: repo-token: ${{ secrets.GITHUB_TOKEN }} issue-message: | @@ -27,4 +27,4 @@ jobs: pr-message: | 👋 你好，@${{ github.actor }}！感谢你第一次向 vibe-coding-cn 提交 Pull Request！ - 我们将仔细评审你的贡献。感谢你让这个项目变得更好！ \ No newline at end of file + 我们将仔细评审你的贡献。感谢你让这个项目变得更好！ diff --git a/AGENTS.md b/AGENTS.md index 85fa868..3476209 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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`、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 @@ -70,6 +70,7 @@ git push origin develop | `make check-directory-docs` | 校验仓库自有目录 README/AGENTS 覆盖 | Python 3 | | `make check-metadata` | 校验 metadata 路径与锚点 | Python 3 | | `make check-ai-citation` | 校验 llms 与 AI 引用语料路径和锚点 | Python 3 | +| `make sync-doc-toc` | 根据 taxonomy 和文档锚点重建 docs 细粒度目录 | 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` | @@ -227,6 +228,7 @@ git push origin develop - `scripts/check-directory-docs.py` - 仓库自有目录 README/AGENTS 覆盖检查脚本，供 `make check-directory-docs` 与 CI 使用 - `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` 使用 - `tools/prompts-library/main.py` - 提示词转换工具入口 - `docs/getting-started/README.md` - 从零开始完整入门，包含学习地图、Vibe Coding 经验、网络配置、CLI 配置与开发环境搭建 - `docs/concepts/README.md#concept-problem-solving` - 问题定义与求解路径底层模型 diff --git a/Makefile b/Makefile index d5c2196..594de8d 100644 --- a/Makefile +++ b/Makefile @@ -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 build test clean +.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 help: @echo "Makefile for Vibe Coding Guide" @@ -14,9 +14,11 @@ help: @echo " check-directory-docs - Check required README/AGENTS pairs" @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 " build - Verify knowledge base has no build step" @echo " test - Run repository quality gates" @echo " clean - Remove ignored generated caches" + @echo " clean-deps - Remove local dependency caches" @echo "" node_modules/.bin/markdownlint: package.json package-lock.json @@ -50,14 +52,23 @@ check-ai-citation: @echo "Checking llms and AI citation paths and anchors..." @python3 scripts/check-ai-citation.py +sync-doc-toc: + @echo "Regenerating docs fine-grained TOC blocks..." + @python3 scripts/sync-doc-toc.py + build: @echo "No build step: this repository is a documentation and knowledge-base project." test: lint check-links check-details check-doc-structure check-directory-docs check-metadata check-ai-citation @echo "Quality gates complete." -clean: +clean: clean-deps @echo "Cleaning ignored generated caches..." @find . -type d -name '__pycache__' -prune -exec rm -rf {} + @rm -rf tools/prompts-library/prompt_jsonl @echo "Cleanup complete." + +clean-deps: + @echo "Cleaning local dependency caches..." + @rm -rf node_modules + @echo "Dependency cleanup complete." diff --git a/README.md b/README.md index fb66988..cfad0d5 100644 --- a/README.md +++ b/README.md @@ -224,6 +224,7 @@ pip install -r tools/prompts-library/scripts/requirements.txt | 目录 README/AGENTS 覆盖检查 | `make check-directory-docs` | `scripts/check-directory-docs.py` | | 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` | | 全部本地质量门禁 | `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` | diff --git a/assets/ai-citation/llms-full.txt b/assets/ai-citation/llms-full.txt index 5d403e5..cc1d344 100644 --- a/assets/ai-citation/llms-full.txt +++ b/assets/ai-citation/llms-full.txt @@ -51,6 +51,10 @@ GEOFlow 的关键启发是：GEO 不是关键词堆砌，而是内容工程链 - docs/concepts/README.md：核心概念索引，汇总问题求解、拼好码、系统构建方法、开发范式演进、语言层要素和递归自优化系统。 - docs/concepts/README.md#concept-problem-solving：问题定义、目标、约束、对象、路径。 - docs/concepts/README.md#concept-glue-coding：胶水原则的扩展，把复用成熟能力作为工程交付默认路径。 +- docs/concepts/README.md#concept-system-building：自顶向下、自底向上与分而治之的系统构建方法。 +- docs/concepts/README.md#concept-development-paradigms：软件开发组织方式和 AI 编程范式的演进。 +- docs/concepts/README.md#concept-language-layers：理解代码所需的语言层级、执行模型、类型系统和工程语义。 +- docs/concepts/README.md#concept-recursive-self-optimizing-system：递归自优化生成系统的形式化模型。 - docs/philosophy/README.md：哲学方法论、思维模型、编程哲学与底层认知模型入口。 - docs/philosophy/README.md#philosophy-thinking-models：第一性原理、奥卡姆剃刀、多阶思维、状态空间等认知工具。 - docs/philosophy/README.md#philosophy-compositional-description-model：对象、状态、快照、序列、过程、变换、同一/差异与关系。 diff --git a/docs/concepts/README.md b/docs/concepts/README.md index efaa2d1..2506e43 100644 --- a/docs/concepts/README.md +++ b/docs/concepts/README.md @@ -27,8 +27,12 @@ - [1. 问题求解](#concept-problem-solving) - [不会操作？先让网页 AI 生成逐步执行版](#concept-problem-solving-不会操作先让网页-ai-生成逐步执行版) - [描述](#concept-problem-solving-描述) - - [一、定义问题](#concept-problem-solving-一定义问题) - - [二、求解过程](#concept-problem-solving-二求解过程) + - [一、定义问题](#concept-problem-solving-一定义问题) + - [二、求解过程](#concept-problem-solving-二求解过程) + - [1）目标](#concept-problem-solving-1目标) + - [2）约束](#concept-problem-solving-2约束) + - [3）对象](#concept-problem-solving-3对象) + - [4）路径](#concept-problem-solving-4路径) - [一句话总结](#concept-problem-solving-一句话总结) - [这个框架为什么很底层](#concept-problem-solving-这个框架为什么很底层) - [继续压缩](#concept-problem-solving-继续压缩) @@ -38,59 +42,64 @@ - [3. 记忆](#concept-problem-solving-3-记忆) - [4. 理解](#concept-problem-solving-4-理解) - [5. 搭建体系](#concept-problem-solving-5-搭建体系) - - [一、问题从哪里来？](#concept-problem-solving-一问题从哪里来) - - [二、问题如何被定义？](#concept-problem-solving-二问题如何被定义) - - [三、问题如何被求解？](#concept-problem-solving-三问题如何被求解) - - [四、求解如何收敛？](#concept-problem-solving-四求解如何收敛) + - [一、问题从哪里来？](#concept-problem-solving-一问题从哪里来) + - [二、问题如何被定义？](#concept-problem-solving-二问题如何被定义) + - [三、问题如何被求解？](#concept-problem-solving-三问题如何被求解) + - [1. 目标决定方向](#concept-problem-solving-1-目标决定方向) + - [2. 约束决定边界](#concept-problem-solving-2-约束决定边界) + - [3. 对象决定方法](#concept-problem-solving-3-对象决定方法) + - [四、求解如何收敛？](#concept-problem-solving-四求解如何收敛) - [6. 应用](#concept-problem-solving-6-应用) - - [场景一：学习能力](#concept-problem-solving-场景一学习能力) - - [场景二：工作项目推进](#concept-problem-solving-场景二工作项目推进) - - [场景三：个人决策](#concept-problem-solving-场景三个人决策) + - [场景一：学习能力](#concept-problem-solving-场景一学习能力) + - [场景二：工作项目推进](#concept-problem-solving-场景二工作项目推进) + - [场景三：个人决策](#concept-problem-solving-场景三个人决策) - [7. 思辨](#concept-problem-solving-7-思辨) - - [常见误区一：把“现象”当成“问题”](#concept-problem-solving-常见误区一把现象当成问题) - - [常见误区二：一上来就找方法](#concept-problem-solving-常见误区二一上来就找方法) - - [常见误区三：只执行，不校正](#concept-problem-solving-常见误区三只执行不校正) - - [易混点：问题求解能力 vs 执行力](#concept-problem-solving-易混点问题求解能力-vs-执行力) - - [值得思考的问题](#concept-problem-solving-值得思考的问题) + - [常见误区一：把“现象”当成“问题”](#concept-problem-solving-常见误区一把现象当成问题) + - [常见误区二：一上来就找方法](#concept-problem-solving-常见误区二一上来就找方法) + - [常见误区三：只执行，不校正](#concept-problem-solving-常见误区三只执行不校正) + - [易混点：问题求解能力 vs 执行力](#concept-problem-solving-易混点问题求解能力-vs-执行力) + - [值得思考的问题](#concept-problem-solving-值得思考的问题) - [8. 创新](#concept-problem-solving-8-创新) - - [一、迁移到学习系统](#concept-problem-solving-一迁移到学习系统) - - [二、迁移到个人成长](#concept-problem-solving-二迁移到个人成长) - - [三、迁移到创新能力](#concept-problem-solving-三迁移到创新能力) - - [四、迁移到 AI 时代](#concept-problem-solving-四迁移到-ai-时代) + - [一、迁移到学习系统](#concept-problem-solving-一迁移到学习系统) + - [二、迁移到个人成长](#concept-problem-solving-二迁移到个人成长) + - [三、迁移到创新能力](#concept-problem-solving-三迁移到创新能力) + - [四、迁移到 AI 时代](#concept-problem-solving-四迁移到-ai-时代) - [9. 内化](#concept-problem-solving-9-内化) - - [立即可执行的行动建议](#concept-problem-solving-立即可执行的行动建议) + - [立即可执行的行动建议](#concept-problem-solving-立即可执行的行动建议) + - [行动一：用一句话重写你现在的问题](#concept-problem-solving-行动一用一句话重写你现在的问题) + - [行动二：建立一个“问题求解清单”](#concept-problem-solving-行动二建立一个问题求解清单) - [2. 拼好码](#concept-glue-coding) - [关系定位](#concept-glue-coding-关系定位) - [一句话定义](#concept-glue-coding-一句话定义) - [颠覆性宣言](#concept-glue-coding-颠覆性宣言) - [核心理念](#concept-glue-coding-核心理念) - - [范式转移](#concept-glue-coding-范式转移) + - [范式转移](#concept-glue-coding-范式转移) - [架构哲学](#concept-glue-coding-架构哲学) - [核心链路](#concept-glue-coding-核心链路) - [为什么有效](#concept-glue-coding-为什么有效) - - [1. 幻觉问题：从“发明”转向“核验”](#concept-glue-coding-1-幻觉问题从发明转向核验) - - [2. 复杂性问题：转交给成熟生态](#concept-glue-coding-2-复杂性问题转交给成熟生态) - - [3. 门槛问题：从底层实现转向业务编排](#concept-glue-coding-3-门槛问题从底层实现转向业务编排) + - [1. 幻觉问题：从“发明”转向“核验”](#concept-glue-coding-1-幻觉问题从发明转向核验) + - [2. 复杂性问题：转交给成熟生态](#concept-glue-coding-2-复杂性问题转交给成熟生态) + - [3. 门槛问题：从底层实现转向业务编排](#concept-glue-coding-3-门槛问题从底层实现转向业务编排) - [胶水原则](#concept-glue-coding-胶水原则) - [决策顺序](#concept-glue-coding-决策顺序) - [成熟方案判断标准](#concept-glue-coding-成熟方案判断标准) - [胶水代码应该做什么](#concept-glue-coding-胶水代码应该做什么) - [胶水代码不应该做什么](#concept-glue-coding-胶水代码不应该做什么) - [实践流程](#concept-glue-coding-实践流程) - - [使用 GitHub Topics 找成熟能力](#concept-glue-coding-使用-github-topics-找成熟能力) + - [使用 GitHub Topics 找成熟能力](#concept-glue-coding-使用-github-topics-找成熟能力) - [经典案例](#concept-glue-coding-经典案例) - - [Polymarket 数据分析 Bot](#concept-glue-coding-polymarket-数据分析-bot) + - [Polymarket 数据分析 Bot](#concept-glue-coding-polymarket-数据分析-bot) - [常见场景](#concept-glue-coding-常见场景) - - [登录认证](#concept-glue-coding-登录认证) - - [AI 客服](#concept-glue-coding-ai-客服) - - [订单流程](#concept-glue-coding-订单流程) + - [登录认证](#concept-glue-coding-登录认证) + - [AI 客服](#concept-glue-coding-ai-客服) + - [订单流程](#concept-glue-coding-订单流程) - [偏离协议](#concept-glue-coding-偏离协议) - [胶水原则之禅](#concept-glue-coding-胶水原则之禅) - [与相近概念的区别](#concept-glue-coding-与相近概念的区别) - - [拼好码 vs 胶水编程](#concept-glue-coding-拼好码-vs-胶水编程) - - [拼好码 vs 低代码](#concept-glue-coding-拼好码-vs-低代码) - - [拼好码 vs 微服务](#concept-glue-coding-拼好码-vs-微服务) - - [拼好码 vs 自研平台化](#concept-glue-coding-拼好码-vs-自研平台化) + - [拼好码 vs 胶水编程](#concept-glue-coding-拼好码-vs-胶水编程) + - [拼好码 vs 低代码](#concept-glue-coding-拼好码-vs-低代码) + - [拼好码 vs 微服务](#concept-glue-coding-拼好码-vs-微服务) + - [拼好码 vs 自研平台化](#concept-glue-coding-拼好码-vs-自研平台化) - [AI 时代的拼好码](#concept-glue-coding-ai-时代的拼好码) - [内化](#concept-glue-coding-内化) - [延伸阅读](#concept-glue-coding-延伸阅读) @@ -119,14 +128,14 @@ - [五、给你一个真正工程级的目标](#concept-language-layers-五给你一个真正工程级的目标) - [六、工程级追加：L9–L12（从"看懂"到"架构"）](#concept-language-layers-六工程级追加l9l12从看懂到架构) - [🧠 L9：时间维度模型（90% 人完全没意识到）](#concept-language-layers-l9时间维度模型90-人完全没意识到) - - [你必须能一眼判断：](#concept-language-layers-你必须能一眼判断) + - [你必须能一眼判断：](#concept-language-layers-你必须能一眼判断) - [🧠 L10：资源模型（CPU / IO / 内存 / 网络）](#concept-language-layers-l10资源模型cpu-io-内存-网络) - - [示例](#concept-language-layers-示例) + - [示例](#concept-language-layers-示例) - [🧠 L11：隐含契约 & 非语法规则（工程真相）](#concept-language-layers-l11隐含契约-非语法规则工程真相) - - [你必须识别这些"非代码规则"：](#concept-language-layers-你必须识别这些非代码规则) - - [示例](#concept-language-layers-示例-2) + - [你必须识别这些"非代码规则"：](#concept-language-layers-你必须识别这些非代码规则) + - [示例](#concept-language-layers-示例-2) - [🧠 L12：代码意图层（顶级能力）](#concept-language-layers-l12代码意图层顶级能力) - - [示例](#concept-language-layers-示例-3) + - [示例](#concept-language-layers-示例-3) - [七、终极完整版：12 层"语言层要素"总表](#concept-language-layers-七终极完整版12-层语言层要素总表) - [八、反直觉但真实的结论](#concept-language-layers-八反直觉但真实的结论) - [九、工程级自测题（非常准）](#concept-language-layers-九工程级自测题非常准) @@ -149,9 +158,9 @@ - [6. 讨论](#concept-recursive-self-optimizing-system-6-讨论) - [7. 结论](#concept-recursive-self-optimizing-system-7-结论) - [附录：高层次概念释义](#concept-recursive-self-optimizing-system-附录高层次概念释义) - - [1. 定义核心角色](#concept-recursive-self-optimizing-system-1-定义核心角色) - - [2. 描述递归生命周期](#concept-recursive-self-optimizing-system-2-描述递归生命周期) - - [3. 终极目标](#concept-recursive-self-optimizing-system-3-终极目标) + - [1. 定义核心角色](#concept-recursive-self-optimizing-system-1-定义核心角色) + - [2. 描述递归生命周期](#concept-recursive-self-optimizing-system-2-描述递归生命周期) + - [3. 终极目标](#concept-recursive-self-optimizing-system-3-终极目标) diff --git a/docs/getting-started/README.md b/docs/getting-started/README.md index 480e62b..da69033 100644 --- a/docs/getting-started/README.md +++ b/docs/getting-started/README.md @@ -38,8 +38,8 @@ ### 细粒度目录 -- [1. Vibe Coding 经验](#vibe-coding-experience) -- [2. 学习地图](#learning-map) + - [vibe-coding-experience](#vibe-coding-experience) + - [learning-map](#learning-map) - [3. 网络环境配置](#network-environment) - [4. CLI 配置](#cli-setup) - [5. 开发环境搭建](#development-environment) diff --git a/docs/philosophy/README.md b/docs/philosophy/README.md index 5ae3cb2..093ac0b 100644 --- a/docs/philosophy/README.md +++ b/docs/philosophy/README.md @@ -26,14 +26,14 @@ - [1. 思维模型](#philosophy-thinking-models) - [使用原则](#philosophy-thinking-models-使用原则) - [模型记录区](#philosophy-thinking-models-模型记录区) - - [第一性原理](#philosophy-thinking-models-第一性原理) - - [奥卡姆剃刀](#philosophy-thinking-models-奥卡姆剃刀) - - [网络效应](#philosophy-thinking-models-网络效应) - - [思想实验](#philosophy-thinking-models-思想实验) - - [逆向思维](#philosophy-thinking-models-逆向思维) - - [多阶思维](#philosophy-thinking-models-多阶思维) - - [组合描述模型](#philosophy-thinking-models-组合描述模型) - - [状态空间思维模型](#philosophy-thinking-models-状态空间思维模型) + - [第一性原理](#philosophy-thinking-models-第一性原理) + - [奥卡姆剃刀](#philosophy-thinking-models-奥卡姆剃刀) + - [网络效应](#philosophy-thinking-models-网络效应) + - [思想实验](#philosophy-thinking-models-思想实验) + - [逆向思维](#philosophy-thinking-models-逆向思维) + - [多阶思维](#philosophy-thinking-models-多阶思维) + - [组合描述模型](#philosophy-thinking-models-组合描述模型) + - [状态空间思维模型](#philosophy-thinking-models-状态空间思维模型) - [2. 组合描述模型](#philosophy-compositional-description-model) - [一、对象](#philosophy-compositional-description-model-一对象) - [二、状态](#philosophy-compositional-description-model-二状态) @@ -46,23 +46,23 @@ - [九、关系](#philosophy-compositional-description-model-九关系) - [十、概念之间的结构关系](#philosophy-compositional-description-model-十概念之间的结构关系) - [十一、不同学科中的展开](#philosophy-compositional-description-model-十一不同学科中的展开) - - [1. 哲学](#philosophy-compositional-description-model-1-哲学) - - [2. 数学](#philosophy-compositional-description-model-2-数学) - - [3. 物理学](#philosophy-compositional-description-model-3-物理学) - - [4. 计算机科学](#philosophy-compositional-description-model-4-计算机科学) - - [5. 系统科学](#philosophy-compositional-description-model-5-系统科学) - - [6. 语言学和认知科学](#philosophy-compositional-description-model-6-语言学和认知科学) + - [1. 哲学](#philosophy-compositional-description-model-1-哲学) + - [2. 数学](#philosophy-compositional-description-model-2-数学) + - [3. 物理学](#philosophy-compositional-description-model-3-物理学) + - [4. 计算机科学](#philosophy-compositional-description-model-4-计算机科学) + - [5. 系统科学](#philosophy-compositional-description-model-5-系统科学) + - [6. 语言学和认知科学](#philosophy-compositional-description-model-6-语言学和认知科学) - [十二、理论上的核心问题](#philosophy-compositional-description-model-十二理论上的核心问题) - - [1. 实体优先，还是过程优先](#philosophy-compositional-description-model-1-实体优先还是过程优先) - - [2. 同一怎么在变化里成立](#philosophy-compositional-description-model-2-同一怎么在变化里成立) - - [3. 差异到底是派生的，还是基础的](#philosophy-compositional-description-model-3-差异到底是派生的还是基础的) - - [4. 关系会不会比对象更基础](#philosophy-compositional-description-model-4-关系会不会比对象更基础) + - [1. 实体优先，还是过程优先](#philosophy-compositional-description-model-1-实体优先还是过程优先) + - [2. 同一怎么在变化里成立](#philosophy-compositional-description-model-2-同一怎么在变化里成立) + - [3. 差异到底是派生的，还是基础的](#philosophy-compositional-description-model-3-差异到底是派生的还是基础的) + - [4. 关系会不会比对象更基础](#philosophy-compositional-description-model-4-关系会不会比对象更基础) - [十三、五层统一模型](#philosophy-compositional-description-model-十三五层统一模型) - - [第一层：存在层](#philosophy-compositional-description-model-第一层存在层) - - [第二层：表征层](#philosophy-compositional-description-model-第二层表征层) - - [第三层：生成层](#philosophy-compositional-description-model-第三层生成层) - - [第四层：判定层](#philosophy-compositional-description-model-第四层判定层) - - [第五层：结构层](#philosophy-compositional-description-model-第五层结构层) + - [第一层：存在层](#philosophy-compositional-description-model-第一层存在层) + - [第二层：表征层](#philosophy-compositional-description-model-第二层表征层) + - [第三层：生成层](#philosophy-compositional-description-model-第三层生成层) + - [第四层：判定层](#philosophy-compositional-description-model-第四层判定层) + - [第五层：结构层](#philosophy-compositional-description-model-第五层结构层) - [十四、作为一种分析方法](#philosophy-compositional-description-model-十四作为一种分析方法) - [十五、结语](#philosophy-compositional-description-model-十五结语) - [3. 编程之道](#philosophy-programming-dao) @@ -122,36 +122,36 @@ - [总体作业流](#philosophy-methodology-toolbox-总体作业流) - [推荐底座（Python）](#philosophy-methodology-toolbox-推荐底座python) - [方法论](#philosophy-methodology-toolbox-方法论) - - [1. 现象学还原（悬置假设）](#philosophy-methodology-toolbox-1-现象学还原悬置假设) - - [2. 正反合（三段迭代）](#philosophy-methodology-toolbox-2-正反合三段迭代) - - [3. 可证伪主义（波普尔）](#philosophy-methodology-toolbox-3-可证伪主义波普尔) - - [4. 形式化方法（轻量形式化）](#philosophy-methodology-toolbox-4-形式化方法轻量形式化) - - [5. 奥卡姆剃刀（最小复杂度）](#philosophy-methodology-toolbox-5-奥卡姆剃刀最小复杂度) - - [6. 实用主义（以指标为准）](#philosophy-methodology-toolbox-6-实用主义以指标为准) - - [7. 系统论/整体论（边界与反馈回路）](#philosophy-methodology-toolbox-7-系统论整体论边界与反馈回路) - - [8. 诠释学（语境澄清）](#philosophy-methodology-toolbox-8-诠释学语境澄清) - - [9. "钢人化"原则（最强版本理解）](#philosophy-methodology-toolbox-9-钢人化原则最强版本理解) - - [10. 决策论/机会成本（可逆优先）](#philosophy-methodology-toolbox-10-决策论机会成本可逆优先) - - [11. 反事实推理（Counterfactuals）](#philosophy-methodology-toolbox-11-反事实推理counterfactuals) - - [12. 溯因推理（Abduction，最佳解释）](#philosophy-methodology-toolbox-12-溯因推理abduction最佳解释) - - [13. 贝叶斯式信念更新（与溯因配合）](#philosophy-methodology-toolbox-13-贝叶斯式信念更新与溯因配合) - - [14. 反思平衡（Reflective equilibrium）](#philosophy-methodology-toolbox-14-反思平衡reflective-equilibrium) - - [15. 概念分析 / 概念工程](#philosophy-methodology-toolbox-15-概念分析-概念工程) - - [16. 方法论怀疑（笛卡尔式）](#philosophy-methodology-toolbox-16-方法论怀疑笛卡尔式) - - [17. 视角三角测量（Triangulation）](#philosophy-methodology-toolbox-17-视角三角测量triangulation) - - [18. 机制解释（Mechanistic explanation）](#philosophy-methodology-toolbox-18-机制解释mechanistic-explanation) - - [19. 错误认识论（Error epistemology）](#philosophy-methodology-toolbox-19-错误认识论error-epistemology) - - [20. 实验哲学（x-phi）](#philosophy-methodology-toolbox-20-实验哲学x-phi) - - [21. 计算哲学（Computational philosophy）](#philosophy-methodology-toolbox-21-计算哲学computational-philosophy) - - [22. 自然化认识论（Naturalized epistemology）](#philosophy-methodology-toolbox-22-自然化认识论naturalized-epistemology) - - [23. 贝叶斯认识论（Bayesian epistemology）](#philosophy-methodology-toolbox-23-贝叶斯认识论bayesian-epistemology) + - [1. 现象学还原（悬置假设）](#philosophy-methodology-toolbox-1-现象学还原悬置假设) + - [2. 正反合（三段迭代）](#philosophy-methodology-toolbox-2-正反合三段迭代) + - [3. 可证伪主义（波普尔）](#philosophy-methodology-toolbox-3-可证伪主义波普尔) + - [4. 形式化方法（轻量形式化）](#philosophy-methodology-toolbox-4-形式化方法轻量形式化) + - [5. 奥卡姆剃刀（最小复杂度）](#philosophy-methodology-toolbox-5-奥卡姆剃刀最小复杂度) + - [6. 实用主义（以指标为准）](#philosophy-methodology-toolbox-6-实用主义以指标为准) + - [7. 系统论/整体论（边界与反馈回路）](#philosophy-methodology-toolbox-7-系统论整体论边界与反馈回路) + - [8. 诠释学（语境澄清）](#philosophy-methodology-toolbox-8-诠释学语境澄清) + - [9. "钢人化"原则（最强版本理解）](#philosophy-methodology-toolbox-9-钢人化原则最强版本理解) + - [10. 决策论/机会成本（可逆优先）](#philosophy-methodology-toolbox-10-决策论机会成本可逆优先) + - [11. 反事实推理（Counterfactuals）](#philosophy-methodology-toolbox-11-反事实推理counterfactuals) + - [12. 溯因推理（Abduction，最佳解释）](#philosophy-methodology-toolbox-12-溯因推理abduction最佳解释) + - [13. 贝叶斯式信念更新（与溯因配合）](#philosophy-methodology-toolbox-13-贝叶斯式信念更新与溯因配合) + - [14. 反思平衡（Reflective equilibrium）](#philosophy-methodology-toolbox-14-反思平衡reflective-equilibrium) + - [15. 概念分析 / 概念工程](#philosophy-methodology-toolbox-15-概念分析-概念工程) + - [16. 方法论怀疑（笛卡尔式）](#philosophy-methodology-toolbox-16-方法论怀疑笛卡尔式) + - [17. 视角三角测量（Triangulation）](#philosophy-methodology-toolbox-17-视角三角测量triangulation) + - [18. 机制解释（Mechanistic explanation）](#philosophy-methodology-toolbox-18-机制解释mechanistic-explanation) + - [19. 错误认识论（Error epistemology）](#philosophy-methodology-toolbox-19-错误认识论error-epistemology) + - [20. 实验哲学（x-phi）](#philosophy-methodology-toolbox-20-实验哲学x-phi) + - [21. 计算哲学（Computational philosophy）](#philosophy-methodology-toolbox-21-计算哲学computational-philosophy) + - [22. 自然化认识论（Naturalized epistemology）](#philosophy-methodology-toolbox-22-自然化认识论naturalized-epistemology) + - [23. 贝叶斯认识论（Bayesian epistemology）](#philosophy-methodology-toolbox-23-贝叶斯认识论bayesian-epistemology) - [附录](#philosophy-methodology-toolbox-附录) - - [通用"性质测试"提示（可复用）](#philosophy-methodology-toolbox-通用性质测试提示可复用) - - [建议的项目框架（最小）](#philosophy-methodology-toolbox-建议的项目框架最小) + - [通用"性质测试"提示（可复用）](#philosophy-methodology-toolbox-通用性质测试提示可复用) + - [建议的项目框架（最小）](#philosophy-methodology-toolbox-建议的项目框架最小) - [使用指南](#philosophy-methodology-toolbox-使用指南) - - [现象学还原用于 Vibe Coding](#philosophy-methodology-toolbox-现象学还原用于-vibe-coding) - - [辩证法用于 Vibe Coding：正反合](#philosophy-methodology-toolbox-辩证法用于-vibe-coding正反合) - - [控制论与科学方法论](#philosophy-methodology-toolbox-控制论与科学方法论) + - [现象学还原用于 Vibe Coding](#philosophy-methodology-toolbox-现象学还原用于-vibe-coding) + - [辩证法用于 Vibe Coding：正反合](#philosophy-methodology-toolbox-辩证法用于-vibe-coding正反合) + - [控制论与科学方法论](#philosophy-methodology-toolbox-控制论与科学方法论) diff --git a/docs/references/README.md b/docs/references/README.md index 8998d30..dd8bd7c 100644 --- a/docs/references/README.md +++ b/docs/references/README.md @@ -40,7 +40,6 @@ ### 细粒度目录 - [章节](#stable-anchor) - - [子章节](#stable-child-anchor) ``` @@ -56,64 +55,174 @@ - [使用方式](#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-数据服务结构) - - [8. 架构设计原则](#reference-engineering-practice-8-架构设计原则) - - [9. 最低门禁](#reference-engineering-practice-9-最低门禁) - - [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-一句话结论) + - [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-代码注释) + - [代码格式化](#reference-engineering-practice-代码格式化) - [文档](#reference-engineering-practice-文档) - - [文档字符串](#reference-engineering-practice-文档字符串) - - [自动化文档生成](#reference-engineering-practice-自动化文档生成) - - [README 文件](#reference-engineering-practice-readme-文件) + - [文档字符串](#reference-engineering-practice-文档字符串) + - [自动化文档生成](#reference-engineering-practice-自动化文档生成) + - [README 文件](#reference-engineering-practice-readme-文件) - [工具](#reference-engineering-practice-工具) - - [IDE](#reference-engineering-practice-ide) + - [IDE](#reference-engineering-practice-ide) - [3. 开发经验](#reference-engineering-practice-3-开发经验) - - [目录](#reference-engineering-practice-目录-2) + - [目录](#reference-engineering-practice-目录-2) - [**1. 变量名维护方案**](#reference-engineering-practice-1-变量名维护方案) - - [1.1 新建“变量名大全文件”](#reference-engineering-practice-11-新建变量名大全文件) + - [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-变量与定义规则及解释) + - [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-编程是长期练习) + - [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-系统提示词构建原则) - - [2. 强前置条件约束](#reference-engineering-practice-2-强前置条件约束) - - [3. 常见坑汇总](#reference-engineering-practice-3-常见坑汇总) + - [使用方式](#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-核心摘要) @@ -122,31 +231,31 @@ - [一、什么是技术栈](#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-前端常见组合) + - [基础语言](#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-后端) + - [常见后端语言](#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-文档数据库) + - [键值数据库](#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-原生开发) @@ -226,8 +335,8 @@ - [如果你想做网页前端](#reference-technology-stack-如果你想做网页前端) - [如果你想做后端](#reference-technology-stack-如果你想做后端) - [如果你想做全栈](#reference-technology-stack-如果你想做全栈) - - [路线一：JavaScript / TypeScript 全栈](#reference-technology-stack-路线一javascript-typescript-全栈) - - [路线二：Java 企业全栈](#reference-technology-stack-路线二java-企业全栈) + - [路线一：JavaScript / TypeScript 全栈](#reference-technology-stack-路线一javascript-typescript-全栈) + - [路线二：Java 企业全栈](#reference-technology-stack-路线二java-企业全栈) - [如果你想做 AI](#reference-technology-stack-如果你想做-ai) - [十六、技术栈的层级结构](#reference-technology-stack-十六技术栈的层级结构) - [十七、技术栈示例总表](#reference-technology-stack-十七技术栈示例总表) diff --git a/scripts/AGENTS.md b/scripts/AGENTS.md index 0588efb..a4686e7 100644 --- a/scripts/AGENTS.md +++ b/scripts/AGENTS.md @@ -6,6 +6,7 @@ - 脚本默认从仓库根目录运行，路径解析必须稳定。 - 新增检查脚本时，同步更新 `scripts/README.md`、`Makefile`、CI 和根目录 `AGENTS.md` 的命令清单。 +- 修改 docs 线性 README 的主章节或锚点后，优先运行 `python3 scripts/sync-doc-toc.py`，再运行 `make test`。 - 检查失败输出应包含文件路径、行号或可定位的错误信息。 - 跳过目录必须明确，至少跳过 `.git`、`.history`、`node_modules` 和外部源码快照。 diff --git a/scripts/README.md b/scripts/README.md index e8542c4..8adb545 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -10,3 +10,4 @@ - `check-directory-docs.py`：仓库自有目录 `README.md` / `AGENTS.md` 覆盖检查脚本。 - `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 的完整细粒度目录。 diff --git a/scripts/check-ai-citation.py b/scripts/check-ai-citation.py index 0f72024..e3d9bfb 100644 --- a/scripts/check-ai-citation.py +++ b/scripts/check-ai-citation.py @@ -10,6 +10,7 @@ from pathlib import Path ROOT = Path(__file__).resolve().parents[1] +TAXONOMY = ROOT / "metadata/taxonomy.yml" AI_ENTRY_FILES = [ Path("llms.txt"), Path("assets/ai-citation/llms-full.txt"), @@ -27,6 +28,31 @@ MARKDOWN_LINK_PATTERN = re.compile(r"!??\[[^\]]*\]\(([^)]+)\)") EXTERNAL_PREFIXES = ("http://", "https://", "mailto:", "tel:", "data:") +def strip_quotes(value: str) -> str: + return value.strip().strip("\"'") + + +def taxonomy_document_paths() -> list[str]: + paths: list[str] = [] + in_documents = False + + for line in TAXONOMY.read_text(encoding="utf-8").splitlines(): + if line == "documents:": + in_documents = True + continue + if in_documents and line and not line.startswith(" "): + break + if not in_documents: + continue + + stripped = line.strip() + if stripped.startswith("- path:"): + _, value = stripped.split(":", 1) + paths.append(strip_quotes(value)) + + return paths + + def github_slug(title: str) -> str: title = re.sub(r"<[^>]+>", "", title.strip().lower()) title = re.sub(r"[`*_~]", "", title) @@ -157,6 +183,15 @@ def main() -> int: if error: errors.append(error) + llms_full = ROOT / "assets/ai-citation/llms-full.txt" + if not llms_full.exists(): + errors.append("assets/ai-citation/llms-full.txt: missing full AI citation context") + else: + llms_full_text = llms_full.read_text(encoding="utf-8", errors="ignore") + for target in taxonomy_document_paths(): + if target not in llms_full_text: + errors.append(f"assets/ai-citation/llms-full.txt: missing taxonomy document coverage: {target}") + if errors: print("AI_CITATION_ERRORS") for error in errors: diff --git a/scripts/check-doc-structure.py b/scripts/check-doc-structure.py index 2f5e976..1d1f60b 100644 --- a/scripts/check-doc-structure.py +++ b/scripts/check-doc-structure.py @@ -9,42 +9,77 @@ from pathlib import Path ROOT = Path(__file__).resolve().parents[1] -DOC_READMES: dict[Path, list[str]] = { - Path("docs/getting-started/README.md"): [ - "vibe-coding-experience", - "learning-map", - "network-environment", - "cli-setup", - "development-environment", - ], - Path("docs/concepts/README.md"): [ - "concept-problem-solving", - "concept-glue-coding", - "concept-system-building", - "concept-development-paradigms", - "concept-language-layers", - "concept-recursive-self-optimizing-system", - ], - Path("docs/philosophy/README.md"): [ - "philosophy-thinking-models", - "philosophy-compositional-description-model", - "philosophy-programming-dao", - "philosophy-methodology-toolbox", - ], - Path("docs/references/README.md"): [ - "reference-engineering-practice", - "reference-technology-stack", - ], - Path("docs/research/README.md"): [ - "research-harness-engineering", - ], -} +TAXONOMY = ROOT / "metadata/taxonomy.yml" SKIP_PARTS = {".git", ".history", "node_modules"} SKIP_PREFIXES = [ Path(".github/wiki"), Path("tools/external"), ] ANCHOR_PATTERN = re.compile(r" str: + return value.strip().strip("\"'") + + +def taxonomy_sections() -> dict[str, dict[str, str]]: + sections: dict[str, dict[str, str]] = {} + current: str | None = None + in_sections = False + + for line in TAXONOMY.read_text(encoding="utf-8").splitlines(): + if line == "sections:": + in_sections = True + continue + if in_sections and line and not line.startswith(" "): + break + if not in_sections: + continue + + section_match = re.match(r"^ ([A-Za-z0-9_-]+):\s*$", line) + if section_match: + current = section_match.group(1) + sections[current] = {} + continue + field_match = re.match(r"^ (path|entry|agent_guide):\s*(.+?)\s*$", line) + if current and field_match: + sections[current][field_match.group(1)] = strip_quotes(field_match.group(2)) + + return sections + + +def taxonomy_document_paths() -> list[str]: + paths: list[str] = [] + in_documents = False + + for line in TAXONOMY.read_text(encoding="utf-8").splitlines(): + if line == "documents:": + in_documents = True + continue + if in_documents and line and not line.startswith(" "): + break + if not in_documents: + continue + + stripped = line.strip() + if stripped.startswith("- path:"): + _, value = stripped.split(":", 1) + paths.append(strip_quotes(value)) + + return paths + + +def doc_readmes_from_taxonomy() -> dict[Path, list[str]]: + readmes: dict[Path, list[str]] = {} + + for target in taxonomy_document_paths(): + path_part, _, anchor = target.partition("#") + if not anchor or not path_part.startswith("docs/") or not path_part.endswith("/README.md"): + continue + readmes.setdefault(Path(path_part), []).append(anchor) + + return readmes def strip_fenced_code(text: str) -> str: @@ -118,12 +153,72 @@ def check_linear_readme(path: Path, expected_anchors: list[str]) -> list[str]: errors.append(f"{rel}:{line}: main anchor '{anchor}' is out of expected section order") previous_line = line - toc_boundary = min((anchor_lines.get(anchor, len(text.splitlines()) + 1) for anchor in expected_anchors), default=0) - toc_text = "\n".join(text.splitlines()[:toc_boundary]) + toc_text = active_toc_text(text) + if not toc_text: + errors.append(f"{rel}: missing active collapsible fine-grained TOC block") + for anchor in expected_anchors: if f"#{anchor}" not in toc_text: errors.append(f"{rel}: top navigation or fine-grained TOC does not link to '#{anchor}'") + required_prefixes = tuple(f"{anchor}-" for anchor in expected_anchors) + for anchor in anchor_lines: + if anchor in expected_anchors or anchor.startswith(required_prefixes): + if f"#{anchor}" not in toc_text: + errors.append(f"{rel}: fine-grained TOC does not link to manual anchor '#{anchor}'") + + return errors + + +def active_toc_text(text: str) -> str: + in_fence = False + fence_marker = "" + collecting = False + collected: list[str] = [] + + for line in text.splitlines(): + stripped = line.lstrip() + if stripped.startswith(("```", "~~~")): + marker = stripped[:3] + if not in_fence: + in_fence = True + fence_marker = marker + elif marker == fence_marker: + in_fence = False + fence_marker = "" + + if in_fence: + continue + if SUMMARY_LINE in line: + collecting = True + if collecting: + collected.append(line) + if collecting and line.strip() == "": + break + + return "\n".join(collected) + + +def check_docs_index() -> list[str]: + errors: list[str] = [] + docs_index = ROOT / "docs/README.md" + rel = docs_index.relative_to(ROOT) + + if not docs_index.exists(): + return [f"{rel}: missing docs index"] + + text = docs_index.read_text(encoding="utf-8", errors="ignore") + for name, fields in taxonomy_sections().items(): + for field in ("path", "entry", "agent_guide"): + value = fields.get(field) + if not value: + errors.append(f"metadata/taxonomy.yml: section '{name}' missing '{field}'") + continue + docs_relative = value.removeprefix("docs/") + candidates = {value, f"./{docs_relative}", docs_relative} + if not any(candidate in text for candidate in candidates): + errors.append(f"{rel}: missing taxonomy {field} reference for '{name}': {value}") + return errors @@ -137,13 +232,19 @@ def main() -> int: checked_files += 1 errors.extend(duplicate_manual_anchors(markdown_file)) - for rel_path, expected_anchors in DOC_READMES.items(): + doc_readmes = doc_readmes_from_taxonomy() + if not doc_readmes: + errors.append("metadata/taxonomy.yml: no docs README anchors found under documents") + + for rel_path, expected_anchors in doc_readmes.items(): path = ROOT / rel_path if not path.exists(): errors.append(f"{rel_path}: missing docs README") continue errors.extend(check_linear_readme(path, expected_anchors)) + errors.extend(check_docs_index()) + if errors: print("DOC_STRUCTURE_ERRORS") for error in errors: diff --git a/scripts/sync-doc-toc.py b/scripts/sync-doc-toc.py new file mode 100644 index 0000000..2d45b68 --- /dev/null +++ b/scripts/sync-doc-toc.py @@ -0,0 +1,196 @@ +#!/usr/bin/env python3 +"""Regenerate collapsible fine-grained TOC blocks in docs linear README files.""" + +from __future__ import annotations + +import re +import sys +from pathlib import Path + + +ROOT = Path(__file__).resolve().parents[1] +TAXONOMY = ROOT / "metadata/taxonomy.yml" +SUMMARY_LINE = "完整细粒度目录（点击展开/收起）" +ANCHOR_PATTERN = re.compile(r" str: + return value.strip().strip("\"'") + + +def taxonomy_document_paths() -> list[str]: + paths: list[str] = [] + in_documents = False + + for line in TAXONOMY.read_text(encoding="utf-8").splitlines(): + if line == "documents:": + in_documents = True + continue + if in_documents and line and not line.startswith(" "): + break + if not in_documents: + continue + + stripped = line.strip() + if stripped.startswith("- path:"): + _, value = stripped.split(":", 1) + paths.append(strip_quotes(value)) + + return paths + + +def doc_readmes_from_taxonomy() -> dict[Path, list[str]]: + readmes: dict[Path, list[str]] = {} + + for target in taxonomy_document_paths(): + path_part, _, anchor = target.partition("#") + if not anchor or not path_part.startswith("docs/") or not path_part.endswith("/README.md"): + continue + readmes.setdefault(Path(path_part), []).append(anchor) + + return readmes + + +def heading_after(lines: list[str], start: int) -> tuple[int, str] | None: + for line in lines[start + 1 : start + 8]: + stripped = line.strip() + if not stripped: + continue + match = HEADING_PATTERN.match(stripped) + if not match: + return None + return len(match.group(1)), match.group(2).strip() + return None + + +def title_from_anchor(anchor: str, main_anchors: list[str]) -> str: + for main_anchor in sorted(main_anchors, key=len, reverse=True): + if anchor == main_anchor: + return main_anchor + prefix = f"{main_anchor}-" + if anchor.startswith(prefix): + return anchor.removeprefix(prefix).replace("-", " ") + return anchor.replace("-", " ") + + +def collect_toc_entries(text: str, main_anchors: list[str]) -> list[tuple[int, str, str]]: + lines = text.splitlines() + required_prefixes = tuple(f"{anchor}-" for anchor in main_anchors) + entries: list[tuple[int, str, str]] = [] + seen: set[str] = set() + + for idx, line in enumerate(lines): + for anchor in ANCHOR_PATTERN.findall(line): + if anchor in seen: + continue + if anchor not in main_anchors and not anchor.startswith(required_prefixes): + continue + seen.add(anchor) + + heading = heading_after(lines, idx) + if heading: + level, title = heading + else: + level, title = 3, title_from_anchor(anchor, main_anchors) + entries.append((level, title, anchor)) + + return entries + + +def render_toc(entries: list[tuple[int, str, str]]) -> str: + rendered = [ + "
", + SUMMARY_LINE, + "", + "### 细粒度目录", + "", + ] + + for level, title, anchor in entries: + indent = " " * max(level - 2, 0) + rendered.append(f"{indent}- [{title}](#{anchor})") + + rendered.extend(["", "
"]) + return "\n".join(rendered) + + +def active_toc_bounds(text: str) -> tuple[int, int] | None: + in_fence = False + fence_marker = "" + offset = 0 + details_start: int | None = None + + for line in text.splitlines(keepends=True): + stripped = line.lstrip() + if stripped.startswith(("```", "~~~")): + marker = stripped[:3] + if not in_fence: + in_fence = True + fence_marker = marker + elif marker == fence_marker: + in_fence = False + fence_marker = "" + + if not in_fence: + if "
" in line: + details_start = offset + line.index("
") + if SUMMARY_LINE in line and details_start is not None: + end = text.find("
", offset) + if end == -1: + return None + return details_start, end + len("
") + + offset += len(line) + + return None + + +def replace_toc_block(text: str, toc: str) -> tuple[str, bool]: + bounds = active_toc_bounds(text) + if bounds is None: + return text, False + + details_start, details_end = bounds + return f"{text[:details_start]}{toc}{text[details_end:]}", True + + +def main() -> int: + changed: list[str] = [] + errors: list[str] = [] + + for rel_path, main_anchors in doc_readmes_from_taxonomy().items(): + path = ROOT / rel_path + if not path.exists(): + errors.append(f"{rel_path}: missing docs README") + continue + + text = path.read_text(encoding="utf-8") + entries = collect_toc_entries(text, main_anchors) + if not entries: + errors.append(f"{rel_path}: no TOC entries generated") + continue + + new_text, replaced = replace_toc_block(text, render_toc(entries)) + if not replaced: + errors.append(f"{rel_path}: missing standard collapsible TOC block") + continue + + if new_text != text: + path.write_text(new_text, encoding="utf-8") + changed.append(str(rel_path)) + + if errors: + print("SYNC_DOC_TOC_ERRORS") + for error in errors: + print(error) + return 1 + + for rel_path in changed: + print(f"updated {rel_path}") + print(f"OK synced docs TOC blocks: {len(changed)} changed") + return 0 + + +if __name__ == "__main__": + sys.exit(main())