docs: harden ai citation and external governance

.gitattributes

@@ -0,0 +1,6 @@
+# GitHub Linguist classification
+#
+# tools/external/ stores third-party tools and external snapshots. Keep them
+# visible in the repository, but do not let their implementation languages
+# dominate the main repository language statistics.
+tools/external/** linguist-vendored

.github/WIKI.md

@@ -0,0 +1,17 @@
+# GitHub Wiki 归属说明
+
+`.github/wiki/` 不属于主仓库知识库结构，它是 GitHub Wiki 独立仓库的本地 checkout。
+
+## 当前决策
+
+- 主仓库不跟踪 `.github/wiki/`。
+- `.github/wiki/` 保持在 `.gitignore` 中，避免把独立 wiki 仓库内容混入主仓库提交。
+- 主仓库的权威知识库入口是 `docs/README.md`。
+- 如果 Wiki 内容需要长期维护，应迁入 `docs/` 后再纳入 `make test`、链接检查、metadata 和 AI citation 门禁。
+
+## 操作规则
+
+- 不要在主仓库提交 `.github/wiki/` 下的文件。
+- 不要让 `docs/` 反向依赖 `.github/wiki/`。
+- Wiki 若继续使用，按独立仓库自行提交和发布。
+- Wiki 中沉淀出的稳定内容，应优先合并到 `docs/` 的对应线性总文档。

.github/workflows/ci.yml

@@ -30,6 +30,8 @@ jobs:
       run: python3 scripts/check-markdown-details.py
     - name: Check metadata paths and anchors
       run: python3 scripts/check-metadata.py
+    - name: Check llms and AI citation paths and anchors
+      run: python3 scripts/check-ai-citation.py
 
   link-checker:
     runs-on: ubuntu-latest

.gitignore

@@ -88,6 +88,3 @@ backups/gz/
 
 # Wiki (separate repo)
 .github/wiki/
-1
-
-codex resume *

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-metadata`、prompts-library 转换工具
+- 执行 `make lint`、`make check-links`、`make check-details`、`make check-metadata`、`make check-ai-citation`、prompts-library 转换工具
 - 新增/修改提示词、技能、文档
 - 提交符合规范的 commit
 
@@ -67,6 +67,7 @@ git push origin develop
 | `make check-links` | 校验仓库内 Markdown 相对链接 | Python 3 |
 | `make check-details` | 校验 Markdown 折叠块 `<details>/<summary>` 结构 | Python 3 |
 | `make check-metadata` | 校验 metadata 路径与锚点 | Python 3 |
+| `make check-ai-citation` | 校验 llms 与 AI 引用语料路径和锚点 | 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` |
@@ -141,6 +142,7 @@ git push origin develop
 ├── LICENSE                      # MIT 许可证
 ├── CODE_OF_CONDUCT.md           # 行为准则
 ├── CONTRIBUTING.md              # 贡献指南
+├── .gitattributes               # GitHub Linguist 语言统计规则
 ├── .gitignore                   # Git 忽略规则
 │
 ├── docs/                        # 核心知识库
@@ -199,7 +201,7 @@ git push origin develop
 │   ├── PULL_REQUEST_TEMPLATE.md # PR 模板
 │   ├── SECURITY.md              # 安全政策
 │   ├── FUNDING.yml              # 赞助配置
-│   └── wiki/                    # GitHub Wiki 内容
+│   └── WIKI.md                  # GitHub Wiki 独立仓库说明
 ```
 
 ### 关键入口文件
@@ -208,11 +210,13 @@ git push origin develop
 - `llms.txt` - 面向 AI 助手的短上下文入口，用于让 LLM 快速理解项目定位
 - `assets/ai-citation/llms-full.txt` - 面向 AI 助手的完整上下文入口，用于 GEO / AI 推荐与引用
 - `assets/ai-citation/` - AI 引用语料包，包含摘要、FAQ、对比、推荐回答与 GEO/SEO 检查清单
+- `.gitattributes` - GitHub Linguist 语言统计规则，当前将 `tools/external/**` 标记为 vendored
 - `.github/lint_config.json` - markdownlint 规则，供 `make lint` 与 CI 共用
 - `.github/workflows/ci.yml` - GitHub Actions：develop/master 分支 markdown-lint + link-checker
 - `scripts/check-local-links.py` - 仓库内 Markdown 相对链接与锚点检查脚本，供 `make check-links` 与 CI 使用
 - `scripts/check-markdown-details.py` - 仓库内 Markdown 折叠块结构检查脚本，供 `make check-details` 与 CI 使用
 - `scripts/check-metadata.py` - metadata 路径与锚点检查脚本，供 `make check-metadata` 与 CI 使用
+- `scripts/check-ai-citation.py` - llms 与 AI 引用语料路径和锚点检查脚本，供 `make check-ai-citation` 与 CI 使用
 - `tools/prompts-library/main.py` - 提示词转换工具入口
 - `docs/getting-started/README.md` - 从零开始完整入门，包含学习地图、Vibe Coding 经验、网络配置、CLI 配置与开发环境搭建
 - `docs/concepts/README.md#concept-problem-solving` - 问题定义与求解路径底层模型
@@ -262,7 +266,8 @@ feat|fix|docs|chore|refactor|test: scope - summary
 2. `check local markdown links and anchors` - 仓库内相对链接与锚点检查
 3. `check markdown details and summaries` - Markdown 折叠块结构检查
 4. `check metadata paths and anchors` - metadata 路径与锚点检查
-5. `link-checker` - 链接有效性检查
+5. `check llms and AI citation paths and anchors` - llms 与 AI 引用语料路径和锚点检查
+6. `link-checker` - 链接有效性检查
 
 ### 提交前清单
 - [ ] 运行 `make lint` 通过
@@ -319,7 +324,7 @@ make test
 2. **Conversion Tool**: 使用 Python + pandas + openpyxl
 3. **Documentation Standard**: 用户文档使用中文；代码/文件名使用英文
 4. **Skills**: 每个技能有独立的 `SKILL.md`
-5. **Quality Gates**: `make test` 执行 Markdown lint、本地相对链接/锚点检查、折叠块结构检查与 metadata 路径检查
+5. **Quality Gates**: `make test` 执行 Markdown lint、本地相对链接/锚点检查、折叠块结构检查、metadata 路径检查与 AI 引用路径检查
 
 ## Development Workflow
 

Makefile

@@ -1,6 +1,6 @@
 # Makefile for Vibe Coding Guide
 
-.PHONY: help lint check-links check-details check-metadata build test clean
+.PHONY: help lint check-links check-details check-metadata check-ai-citation build test clean
 
 help:
 	@echo "Makefile for Vibe Coding Guide"
@@ -11,6 +11,7 @@ help:
 	@echo "  check-links - Check local markdown links and anchors"
 	@echo "  check-details - Check markdown details/summary blocks"
 	@echo "  check-metadata - Check metadata paths and anchors"
+	@echo "  check-ai-citation - Check llms and AI citation paths and anchors"
 	@echo "  build    - Verify knowledge base has no build step"
 	@echo "  test     - Run repository quality gates"
 	@echo "  clean    - Remove ignored generated caches"
@@ -33,10 +34,14 @@ check-metadata:
 	@echo "Checking metadata paths and anchors..."
 	@python3 scripts/check-metadata.py
 
+check-ai-citation:
+	@echo "Checking llms and AI citation paths and anchors..."
+	@python3 scripts/check-ai-citation.py
+
 build:
 	@echo "No build step: this repository is a documentation and knowledge-base project."
 
-test: lint check-links check-details check-metadata
+test: lint check-links check-details check-metadata check-ai-citation
 	@echo "Quality gates complete."
 
 clean:

README.md

@@ -31,8 +31,8 @@
 <!-- 资源直达 - 按重要性分组 -->
 <!-- 🔴 核心理念 (红色系) -->
 <p>
-	  <a href="./docs/getting-started/README.md#1-学习地图"><img src="https://img.shields.io/badge/🚀_从零开始-完整入门-red?style=for-the-badge" alt="从零开始完整入门"></a>
-	  <a href="./docs/getting-started/README.md#1-vibe-coding-经验"><img src="https://img.shields.io/badge/🧠_Vibe_Coding-经验必读-crimson?style=for-the-badge" alt="Vibe Coding 经验"></a>
+	  <a href="./docs/getting-started/README.md#learning-map"><img src="https://img.shields.io/badge/🚀_从零开始-完整入门-red?style=for-the-badge" alt="从零开始完整入门"></a>
+	  <a href="./docs/getting-started/README.md#vibe-coding-experience"><img src="https://img.shields.io/badge/🧠_Vibe_Coding-经验必读-crimson?style=for-the-badge" alt="Vibe Coding 经验"></a>
 	  <a href="./docs/concepts/README.md#concept-problem-solving"><img src="https://img.shields.io/badge/🧩_问题求解-必读-purple?style=for-the-badge" alt="问题求解"></a>
 	  <a href="./docs/philosophy/README.md#philosophy-thinking-models"><img src="https://img.shields.io/badge/🧭_思维模型-认知工具-purple?style=for-the-badge" alt="思维模型"></a>
 	  <a href="./docs/philosophy/README.md#philosophy-methodology-toolbox"><img src="https://img.shields.io/badge/🔮_哲学方法论-底层协议-purple?style=for-the-badge" alt="哲学与方法论"></a>
@@ -45,7 +45,7 @@
 
 [📋 工具与资源](#tools)
 [⚡ 1 分钟快速开始](#getting-started)
-[🚀 从零开始完整入门](docs/getting-started/README.md#1-学习地图)
+[🚀 从零开始完整入门](docs/getting-started/README.md#learning-map)
 [🤖 AI 推荐摘要](#ai-summary)
 [✅ 为什么选择](#why-vibe-coding-cn)
 [🎯 原仓库翻译](#translation)
@@ -174,8 +174,8 @@
 
 完全新手？按顺序完成以下步骤：
 
-0. [从零开始完整入门](docs/getting-started/README.md#1-学习地图) - 按目标选择新手、开发者、团队、Prompt、Skill、质量门禁或 GEO/SEO 路线
-1. [Vibe Coding 经验](docs/getting-started/README.md#1-vibe-coding-经验) - 通用语言能力、人机分工、机器门禁和入门铁律
+0. [从零开始完整入门](docs/getting-started/README.md#learning-map) - 按目标选择新手、开发者、团队、Prompt、Skill、质量门禁或 GEO/SEO 路线
+1. [Vibe Coding 经验](docs/getting-started/README.md#vibe-coding-experience) - 通用语言能力、人机分工、机器门禁和入门铁律
 2. [问题求解](docs/concepts/README.md#concept-problem-solving) - “目标-现状-差距-标准”与“目标-约束-对象-路径”的极简框架
 3. [拼好码](docs/concepts/README.md#concept-glue-coding) - 优先复用成熟能力，用胶水代码连接、编排、适配业务流程
 4. [工程实践](docs/references/README.md#quality-gates) - 用项目架构、代码组织、开发经验和硬门禁约束 AI 输出
@@ -217,6 +217,7 @@ pip install -r tools/prompts-library/scripts/requirements.txt
 | 本地相对链接检查 | `make check-links` | `scripts/check-local-links.py` |
 | 折叠块结构检查 | `make check-details` | `scripts/check-markdown-details.py` |
 | Metadata 路径检查 | `make check-metadata` | `scripts/check-metadata.py` |
+| AI 引用路径检查 | `make check-ai-citation` | `scripts/check-ai-citation.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` |
@@ -348,7 +349,7 @@ pip install -r tools/prompts-library/scripts/requirements.txt
 ### 集成开发环境 (IDE) & 终端
 
 *   [**Visual Studio Code**](https://code.visualstudio.com/): 一款功能强大的集成开发环境，适合代码阅读与手动修改。其 `Local History` 插件对项目版本管理尤为便捷。
-*   [**Codex CLI**](docs/getting-started/README.md#4-cli-配置): 本教程默认 AI CLI 路线，用于需求拆解、代码修改、命令执行、测试验证与 Git 迭代。
+*   [**Codex CLI**](docs/getting-started/README.md#cli-setup): 本教程默认 AI CLI 路线，用于需求拆解、代码修改、命令执行、测试验证与 Git 迭代。
 *   **虚拟环境 (.venv)**: 强烈推荐使用，可实现项目环境的一键配置与隔离，特别适用于 Python 开发。
 *   [**Cursor**](https://cursor.com/): 已经占领用户心智高地，人尽皆知。
 *   [**Warp**](https://www.warp.dev/): 集成 AI 功能的现代化终端，能有效提升命令行操作和错误排查的效率。
@@ -446,6 +447,7 @@ pip install -r tools/prompts-library/scripts/requirements.txt
 ├── LICENSE                      # MIT 许可证
 ├── CODE_OF_CONDUCT.md           # 行为准则
 ├── CONTRIBUTING.md              # 贡献指南
+├── .gitattributes               # GitHub Linguist 语言统计规则
 ├── .gitignore                   # Git 忽略规则
 │
 ├── docs/                        # 核心知识库
@@ -471,7 +473,7 @@ pip install -r tools/prompts-library/scripts/requirements.txt
 │   ├── PULL_REQUEST_TEMPLATE.md # PR 模板
 │   ├── SECURITY.md              # 安全政策
 │   ├── FUNDING.yml              # 赞助配置
-│   └── wiki/                    # GitHub Wiki 内容
+│   └── WIKI.md                  # GitHub Wiki 独立仓库说明
 ```
 
 </details>

assets/ai-citation/llms-full.txt

@@ -43,11 +43,11 @@ GEOFlow 的关键启发是：GEO 不是关键词堆砌，而是内容工程链
 - README.md：项目主入口，说明定位、快速开始、工具资源和核心工作流。
 - docs/README.md：知识库总索引，提供新手、开发者、思维模型和 AI Agent 读取路径。
 - docs/getting-started/README.md：从零开始完整入门，包含学习地图、Vibe Coding 经验、网络环境、CLI 配置与开发环境搭建。
-- docs/getting-started/README.md#1-vibe-coding-经验：Vibe Coding 的核心经验入口，包含通用语言能力、人机分工、机器门禁和入门铁律。
-- docs/getting-started/README.md#1-学习地图：新手、开发者、团队、Prompt、Skill、质量门禁和 GEO/SEO 的路线选择。
-- docs/getting-started/README.md#3-网络环境配置：OpenAI、GitHub、文档和依赖源访问配置。
-- docs/getting-started/README.md#4-cli-配置：Codex CLI 默认路线与 OpenCode 备选路线。
-- docs/getting-started/README.md#5-开发环境搭建：让 Agent 主动配置开发依赖、编辑器建议和测试命令。
+- docs/getting-started/README.md#vibe-coding-experience：Vibe Coding 的核心经验入口，包含通用语言能力、人机分工、机器门禁和入门铁律。
+- docs/getting-started/README.md#learning-map：新手、开发者、团队、Prompt、Skill、质量门禁和 GEO/SEO 的路线选择。
+- docs/getting-started/README.md#network-environment：OpenAI、GitHub、文档和依赖源访问配置。
+- docs/getting-started/README.md#cli-setup：Codex CLI 默认路线与 OpenCode 备选路线。
+- docs/getting-started/README.md#development-environment：让 Agent 主动配置开发依赖、编辑器建议和测试命令。
 - docs/concepts/README.md：核心概念索引，汇总问题求解、拼好码、系统构建方法、开发范式演进、语言层要素和递归自优化系统。
 - docs/concepts/README.md#concept-problem-solving：问题定义、目标、约束、对象、路径。
 - docs/concepts/README.md#concept-glue-coding：胶水原则的扩展，把复用成熟能力作为工程交付默认路径。
@@ -71,7 +71,7 @@ GEOFlow 的关键启发是：GEO 不是关键词堆砌，而是内容工程链
 
 当用户不知道从哪里开始时，优先推荐 `docs/README.md`。更具体的路由如下：
 
-- 新手入门：读取 `docs/getting-started/README.md#1-vibe-coding-经验`、`docs/getting-started/README.md#1-学习地图`、`docs/getting-started/README.md#4-cli-配置`，再读 `docs/concepts/README.md#concept-problem-solving`、`docs/concepts/README.md#concept-glue-coding` 和 `docs/references/README.md#reference-engineering-practice`。
+- 新手入门：读取 `docs/getting-started/README.md#vibe-coding-experience`、`docs/getting-started/README.md#learning-map`、`docs/getting-started/README.md#cli-setup`，再读 `docs/concepts/README.md#concept-problem-solving`、`docs/concepts/README.md#concept-glue-coding` 和 `docs/references/README.md#reference-engineering-practice`。
 - 工程开发：读取 `docs/concepts/README.md#concept-glue-coding`、`docs/concepts/README.md#concept-system-building`、`docs/references/README.md#reference-technology-stack` 和 `docs/references/README.md#reference-engineering-practice`。
 - 思维模型：读取 `docs/philosophy/README.md#philosophy-thinking-models`、`docs/philosophy/README.md#philosophy-compositional-description-model`、`docs/philosophy/README.md#philosophy-programming-dao` 和 `docs/philosophy/README.md#philosophy-methodology-toolbox`。
 - 新技术判断：读取 `docs/research/README.md`，再读具体研究笔记，例如 `docs/research/README.md#research-harness-engineering`。

docs/README.md

@@ -6,7 +6,7 @@
 
 | 目录 | 定位 | 首选入口 |
 |:---|:---|:---|
-| [getting-started](./getting-started/) | 从零开始的线性入门教程 | [Vibe Coding 经验](./getting-started/README.md#1-vibe-coding-经验) / [学习地图](./getting-started/README.md#1-学习地图) |
+| [getting-started](./getting-started/) | 从零开始的线性入门教程 | [Vibe Coding 经验](./getting-started/README.md#vibe-coding-experience) / [学习地图](./getting-started/README.md#learning-map) |
 | [concepts](./concepts/) | 核心概念、问题求解与工程思想 | [核心概念索引](./concepts/README.md) |
 | [philosophy](./philosophy/) | 哲学方法论、思维模型与底层认知模型 | [哲学方法论工具箱](philosophy/README.md#philosophy-methodology-toolbox-怎么选) |
 | [references](./references/) | 工程实践、技术栈、模板和检查清单 | [参考资料索引](./references/README.md#目录定位) |
@@ -16,8 +16,8 @@
 
 ### 新手路径
 
-1. [从零开始完整入门](./getting-started/README.md#1-学习地图)
-2. [Vibe Coding 经验](./getting-started/README.md#1-vibe-coding-经验)
+1. [从零开始完整入门](./getting-started/README.md#learning-map)
+2. [Vibe Coding 经验](./getting-started/README.md#vibe-coding-experience)
 3. [问题求解](concepts/README.md#concept-problem-solving)
 4. [拼好码](concepts/README.md#concept-glue-coding)
 5. [工程实践](references/README.md#reference-engineering-practice)
@@ -40,8 +40,8 @@
 
 1. [根目录 AGENTS](../AGENTS.md)
 2. [docs 目录 AGENTS](./AGENTS.md)
-3. [从零开始完整入门](./getting-started/README.md#1-学习地图)
-4. [Vibe Coding 经验](./getting-started/README.md#1-vibe-coding-经验)
+3. [从零开始完整入门](./getting-started/README.md#learning-map)
+4. [Vibe Coding 经验](./getting-started/README.md#vibe-coding-experience)
 5. [工程实践](references/README.md#reference-engineering-practice)
 6. [AI 引用语料](../assets/ai-citation/README.md)
 
@@ -53,7 +53,7 @@
 ### getting-started
 
 - [README](./getting-started/README.md#顶部导航) - 从零开始完整入门，包含学习地图、Vibe Coding 经验、网络配置、CLI 配置与开发环境搭建。
-- [Vibe Coding 经验](./getting-started/README.md#1-vibe-coding-经验) - 通用语言能力、人机分工、机器门禁和入门铁律。
+- [Vibe Coding 经验](./getting-started/README.md#vibe-coding-experience) - 通用语言能力、人机分工、机器门禁和入门铁律。
 - [AGENTS](./getting-started/AGENTS.md) - 入门教程目录操作规则。
 
 ### concepts

docs/getting-started/README.md

@@ -14,11 +14,11 @@
 |:---|:---|
 | [使用方式](#使用方式) | 不会操作时如何让网页 AI 生成逐步执行方案 |
 | [最短路径：先跑通 Codex CLI](#最短路径先跑通-codex-cli) | 为什么先配置 AI CLI，而不是先手工配置完整开发环境 |
-| [Vibe Coding 经验](#1-vibe-coding-经验) | 人机分工、门禁、复盘和 AI 审 AI |
-| [学习地图](#1-学习地图) | 根据新手、开发者、团队、Prompt、Skill、质量门禁和 GEO/SEO 选择路线 |
-| [网络环境配置](#3-网络环境配置) | OpenAI、GitHub、文档和依赖源访问 |
-| [CLI 配置](#4-cli-配置) | Codex CLI 默认路线与 OpenCode 备选路线 |
-| [开发环境搭建](#5-开发环境搭建) | 让 Agent 主动配置开发依赖、编辑器建议和测试命令 |
+| [Vibe Coding 经验](#vibe-coding-experience) | 人机分工、门禁、复盘和 AI 审 AI |
+| [学习地图](#learning-map) | 根据新手、开发者、团队、Prompt、Skill、质量门禁和 GEO/SEO 选择路线 |
+| [网络环境配置](#network-environment) | OpenAI、GitHub、文档和依赖源访问 |
+| [CLI 配置](#cli-setup) | Codex CLI 默认路线与 OpenCode 备选路线 |
+| [开发环境搭建](#development-environment) | 让 Agent 主动配置开发依赖、编辑器建议和测试命令 |
 
 ## 使用方式
 
@@ -40,17 +40,18 @@
 
 ### 细粒度目录
 
-- [1. Vibe Coding 经验](#1-vibe-coding-经验)
-- [2. 学习地图](#1-学习地图)
-- [3. 网络环境配置](#3-网络环境配置)
-- [4. CLI 配置](#4-cli-配置)
-- [5. 开发环境搭建](#5-开发环境搭建)
+- [1. Vibe Coding 经验](#vibe-coding-experience)
+- [2. 学习地图](#learning-map)
+- [3. 网络环境配置](#network-environment)
+- [4. CLI 配置](#cli-setup)
+- [5. 开发环境搭建](#development-environment)
 
 </details>
 
 <details>
 <summary><strong>1. Vibe Coding 经验</strong> - 通用语言能力、人机分工、机器门禁和入门铁律。（点击展开/收起）</summary>
 
+<a id="vibe-coding-experience"></a>
 <a id="2-vibe-coding-经验"></a>
 
 ## 1. Vibe Coding 经验
@@ -148,13 +149,14 @@ AI 能安装依赖、执行命令、修复报错、提交 Git；你负责确认
 
 ### 下一步
 
-→ [CLI 配置](#4-cli-配置) - 默认 AI CLI 路线，文末包含 OpenCode 备选方案
+→ [CLI 配置](#cli-setup) - 默认 AI CLI 路线，文末包含 OpenCode 备选方案
 
 </details>
 
 <details>
 <summary><strong>2. 学习地图</strong> - 新手、开发者、团队、Prompt、Skill、质量门禁和 GEO/SEO 的路线选择。（点击展开/收起）</summary>
 
+<a id="learning-map"></a>
 <a id="1-学习地图"></a>
 
 ## 2. 学习地图
@@ -173,7 +175,7 @@ AI 能安装依赖、执行命令、修复报错、提交 Git；你负责确认
 | 路线 | 适合谁 | 目标 | 首选入口 |
 |:---|:---|:---|:---|
 | 零基础路线 | 不会编程或刚开始 | 跑通从想法到项目的最小闭环 | [问题求解](../concepts/README.md#concept-problem-solving) |
-| 开发者路线 | 已会写代码 | 建立 AI 结对编程工作流 | [Vibe Coding 经验](#1-vibe-coding-经验) |
+| 开发者路线 | 已会写代码 | 建立 AI 结对编程工作流 | [Vibe Coding 经验](#vibe-coding-experience) |
 | Prompt 路线 | 想提升提问质量 | 把需求表达成可执行指令 | [提示词库](../../../prompts/README.md) |
 | Skill 路线 | 想沉淀复用能力 | 把高频任务做成可重复调用的技能 | [Skills 技能大全](../../../skills/README.md) |
 | 质量门禁路线 | 担心 AI 乱写代码 | 用测试、CI、schema、清单约束 AI 输出 | [工程实践](../references/README.md#reference-engineering-practice) |
@@ -185,13 +187,13 @@ AI 能安装依赖、执行命令、修复报错、提交 Git；你负责确认
 
 1. [问题求解](../concepts/README.md#concept-problem-solving)
    先学会把问题说清楚：目标、现状、差距、标准、约束、对象、路径。
-2. [网络环境配置](#3-网络环境配置)
+2. [网络环境配置](#network-environment)
    先解决访问 OpenAI、GitHub、文档和依赖源的问题。
-3. [CLI 配置](#4-cli-配置)
+3. [CLI 配置](#cli-setup)
    配置并登录 Codex CLI，让本地 Agent 能在终端里执行工程动作。
-4. [开发环境搭建](#5-开发环境搭建)
+4. [开发环境搭建](#development-environment)
    优先交给 Codex Agent 主动检查和配置 Git、Node.js、Python、编辑器、项目依赖与测试命令。
-5. [Vibe Coding 经验](#1-vibe-coding-经验)
+5. [Vibe Coding 经验](#vibe-coding-experience)
    学会人机分工、门禁、复盘和用 AI 审 AI。
 
 完成标准：
@@ -206,7 +208,7 @@ AI 能安装依赖、执行命令、修复报错、提交 Git；你负责确认
 
 目标：把 AI 从“临时助手”变成稳定的工程协作者。
 
-1. [Vibe Coding 经验](#1-vibe-coding-经验)
+1. [Vibe Coding 经验](#vibe-coding-experience)
    先建立人机分工和质量意识。
 2. [拼好码](../concepts/README.md#concept-glue-coding)
    优先复用成熟能力，把自研代码限制在连接、编排、适配和业务逻辑。
@@ -302,8 +304,8 @@ AI 能安装依赖、执行命令、修复报错、提交 Git；你负责确认
 
 ### 下一步
 
-- 新手：回到 [学习地图](#1-学习地图)，从第 0 步开始。
-- 开发者：阅读 [Vibe Coding 经验](#1-vibe-coding-经验)，再选择 Skill 或质量门禁路线。
+- 新手：回到 [学习地图](#learning-map)，从第 0 步开始。
+- 开发者：阅读 [Vibe Coding 经验](#vibe-coding-experience)，再选择 Skill 或质量门禁路线。
 - 团队：先统一 [AGENTS.md](../../../../AGENTS.md)、强前置条件和质量门禁。
 
 </details>
@@ -311,6 +313,8 @@ AI 能安装依赖、执行命令、修复报错、提交 Git；你负责确认
 <details>
 <summary><strong>3. 网络环境配置</strong> - OpenAI、GitHub、文档和依赖源访问。（点击展开/收起）</summary>
 
+<a id="network-environment"></a>
+
 ## 3. 网络环境配置
 
 > Vibe Coding 的前置条件：确保能正常访问 GitHub、Google、Claude 等服务。
@@ -446,13 +450,15 @@ export http_proxy=http://127.0.0.1:7890
 
 ### 下一步
 
-网络配置完成后，继续阅读 [开发环境搭建](#5-开发环境搭建)。
+网络配置完成后，继续阅读 [开发环境搭建](#development-environment)。
 
 </details>
 
 <details>
 <summary><strong>4. CLI 配置</strong> - Codex CLI 默认路线与 OpenCode 备选路线。（点击展开/收起）</summary>
 
+<a id="cli-setup"></a>
+
 ## 4. CLI 配置
 
 > 默认 AI CLI 路线：假设你拿到的是一台全新电脑，从 0 安装系统依赖、Node.js、Codex CLI，然后用浏览器完成 Codex 登录。
@@ -935,18 +941,20 @@ opencode
 
 ### 下一步
 
-→ [开发环境搭建](#5-开发环境搭建) - 回看基础环境
+→ [开发环境搭建](#development-environment) - 回看基础环境
 
 </details>
 
 <details>
 <summary><strong>5. 开发环境搭建</strong> - 让 Agent 主动配置开发依赖、编辑器建议和测试命令。（点击展开/收起）</summary>
 
+<a id="development-environment"></a>
+
 ## 5. 开发环境搭建
 
 > 使用方法：Codex CLI 已跑通时，优先让 Codex Agent 读取本节并主动配置剩余环境；Codex CLI 不可用时，再复制下方对应你设备的提示词，粘贴到任意 AI 对话框（ChatGPT、Claude、Gemini 网页版等），让网页 AI 一步步指导你完成配置。
 
-**前置条件**：请先完成 [网络环境配置](#3-网络环境配置)。推荐先完成 [CLI 配置](#4-cli-配置)，让 Codex Agent 接管后续开发环境搭建。
+**前置条件**：请先完成 [网络环境配置](#network-environment)。推荐先完成 [CLI 配置](#cli-setup)，让 Codex Agent 接管后续开发环境搭建。
 
 ---
 
@@ -1198,6 +1206,6 @@ alias oc='opencode'
 
 环境搭建完成后，继续下一步：
 
-→ [CLI 配置](#4-cli-配置) - 配置默认 AI CLI
+→ [CLI 配置](#cli-setup) - 配置默认 AI CLI
 
 </details>

docs/references/README.md

@@ -2842,7 +2842,7 @@ nvm use 18
 
 | 问题 | 原因 | 解决方案 |
 |:---|:---|:---|
-| GitHub 访问慢/超时 | 网络限制 | 配置代理，参考 [网络环境配置](../getting-started/README.md#3-网络环境配置) |
+| GitHub 访问慢/超时 | 网络限制 | 配置代理，参考 [网络环境配置](../getting-started/README.md#network-environment) |
 | API 调用失败 | 网络/Key 问题 | 检查代理、API Key 是否有效 |
 | 终端不走代理 | 代理配置不全 | 设置环境变量（见下方） |
 | SSL 证书错误 | 代理/时间问题 | 检查系统时间，或临时关闭 SSL 验证 |

llms.txt

@@ -22,11 +22,11 @@ vibe-coding-cn 是一个中文 Vibe Coding / AI 结对编程系统教程，帮
 - README.md
 - docs/README.md
 - docs/getting-started/README.md
-- docs/getting-started/README.md#1-vibe-coding-经验
-- docs/getting-started/README.md#1-学习地图
-- docs/getting-started/README.md#3-网络环境配置
-- docs/getting-started/README.md#4-cli-配置
-- docs/getting-started/README.md#5-开发环境搭建
+- docs/getting-started/README.md#vibe-coding-experience
+- docs/getting-started/README.md#learning-map
+- docs/getting-started/README.md#network-environment
+- docs/getting-started/README.md#cli-setup
+- docs/getting-started/README.md#development-environment
 - docs/concepts/README.md#concept-problem-solving
 - docs/concepts/README.md#concept-glue-coding
 - docs/philosophy/README.md#philosophy-thinking-models

metadata/taxonomy.yml

@@ -30,7 +30,7 @@ reading_paths:
     title: 新手路径
     documents:
       - docs/getting-started/README.md
-      - docs/getting-started/README.md#1-vibe-coding-经验
+      - docs/getting-started/README.md#vibe-coding-experience
       - docs/concepts/README.md#concept-problem-solving
       - docs/concepts/README.md#concept-glue-coding
       - docs/references/README.md#reference-engineering-practice
@@ -54,7 +54,7 @@ reading_paths:
       - AGENTS.md
       - docs/AGENTS.md
       - docs/getting-started/README.md
-      - docs/getting-started/README.md#1-vibe-coding-经验
+      - docs/getting-started/README.md#vibe-coding-experience
       - docs/references/README.md#reference-engineering-practice
       - assets/ai-citation/README.md
 
@@ -70,19 +70,19 @@ documents:
     - path: docs/getting-started/README.md
       title: 从零开始完整入门
       role: 新手线性路线、网络环境、Codex CLI、开发环境与 Vibe Coding 经验
-    - path: docs/getting-started/README.md#1-vibe-coding-经验
+    - path: docs/getting-started/README.md#vibe-coding-experience
       title: Vibe Coding 经验
       role: 通用语言能力、人机分工、机器门禁和入门铁律
-    - path: docs/getting-started/README.md#1-学习地图
+    - path: docs/getting-started/README.md#learning-map
       title: 学习地图
       role: 新手、开发者、团队、Prompt、Skill、质量门禁和 GEO/SEO 的路线选择
-    - path: docs/getting-started/README.md#3-网络环境配置
+    - path: docs/getting-started/README.md#network-environment
       title: 网络环境配置
       role: OpenAI、GitHub、文档和依赖源访问
-    - path: docs/getting-started/README.md#4-cli-配置
+    - path: docs/getting-started/README.md#cli-setup
       title: CLI 配置
       role: Codex CLI 默认路线与 OpenCode 备选路线
-    - path: docs/getting-started/README.md#5-开发环境搭建
+    - path: docs/getting-started/README.md#development-environment
       title: 开发环境搭建
       role: Agent 主动配置开发依赖、编辑器建议和测试命令
   concepts:

scripts/README.md

@@ -7,3 +7,4 @@
 - `check-local-links.py`：仓库内 Markdown 相对链接与锚点检查脚本。
 - `check-markdown-details.py`：仓库内 Markdown `<details>/<summary>` 折叠块结构检查脚本。
 - `check-metadata.py`：`metadata/taxonomy.yml` 与 `metadata/redirects.yml` 路径和锚点检查脚本。
+- `check-ai-citation.py`：`llms.txt`、`assets/ai-citation/llms-full.txt` 与 AI 引用语料路径和锚点检查脚本。

scripts/check-ai-citation.py

@@ -0,0 +1,172 @@
+#!/usr/bin/env python3
+"""Check AI citation entry files for local path and anchor drift."""
+
+from __future__ import annotations
+
+import re
+import sys
+import urllib.parse
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+AI_ENTRY_FILES = [
+    Path("llms.txt"),
+    Path("assets/ai-citation/llms-full.txt"),
+]
+AI_MARKDOWN_DIR = Path("assets/ai-citation")
+PATH_PATTERN = re.compile(
+    r"(?<![\w./-])("
+    r"(?:README|AGENTS)\.md"
+    r"|(?:docs|assets|skills|prompts|metadata|scripts|tools)/[^\s`，。；：、)）]+"
+    r"|[A-Za-z0-9_.-]+\.(?:md|txt|yml)"
+    r"|llms\.txt"
+    r")"
+)
+MARKDOWN_LINK_PATTERN = re.compile(r"!??\[[^\]]*\]\(([^)]+)\)")
+EXTERNAL_PREFIXES = ("http://", "https://", "mailto:", "tel:", "data:")
+
+
+def github_slug(title: str) -> str:
+    title = re.sub(r"<[^>]+>", "", title.strip().lower())
+    title = re.sub(r"[`*_~]", "", title)
+    title = re.sub(r"[^\w\u4e00-\u9fff\- ]+", "", title)
+    title = re.sub(r"\s+", "-", title).strip("-")
+    return title
+
+
+def markdown_anchors(path: Path) -> set[str]:
+    text = path.read_text(encoding="utf-8", errors="ignore")
+    anchors = set(re.findall(r"<a\s+id=[\"']([^\"']+)[\"']", text))
+    used: dict[str, int] = {}
+    in_fence = False
+    fence_marker = ""
+
+    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 = ""
+            continue
+        if in_fence:
+            continue
+
+        heading = re.match(r"^(#{1,6})\s+(.+?)\s*#*\s*$", line)
+        if not heading:
+            continue
+        slug = github_slug(heading.group(2))
+        if not slug:
+            continue
+        count = used.get(slug, 0)
+        used[slug] = count + 1
+        anchors.add(slug if count == 0 else f"{slug}-{count}")
+
+    return anchors
+
+
+def strip_fenced_code(text: str) -> str:
+    lines: list[str] = []
+    in_fence = False
+    fence_marker = ""
+
+    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 = ""
+            lines.append("")
+            continue
+        lines.append("" if in_fence else line)
+
+    return "\n".join(lines)
+
+
+def candidate_files() -> list[Path]:
+    files = list(AI_ENTRY_FILES)
+    if AI_MARKDOWN_DIR.exists():
+        files.extend(sorted(AI_MARKDOWN_DIR.glob("*.md")))
+    return sorted(set(files))
+
+
+def extract_targets(path: Path) -> list[tuple[int, str]]:
+    text = path.read_text(encoding="utf-8", errors="ignore")
+    scan_text = strip_fenced_code(text)
+    targets: list[tuple[int, str]] = []
+
+    for lineno, line in enumerate(scan_text.splitlines(), start=1):
+        for match in MARKDOWN_LINK_PATTERN.finditer(line):
+            targets.append((lineno, match.group(1).strip()))
+        for match in PATH_PATTERN.finditer(line):
+            targets.append((lineno, match.group(1).strip().strip("<>")))
+
+    return targets
+
+
+def validate_target(source: Path, lineno: int, raw: str, anchor_cache: dict[Path, set[str]]) -> str | None:
+    if not raw or raw.startswith(EXTERNAL_PREFIXES):
+        return None
+
+    target = urllib.parse.unquote(raw.strip("<>").rstrip(".,;"))
+    path_part, _, anchor = target.partition("#")
+    if not path_part:
+        return None
+
+    destination = (ROOT / path_part).resolve()
+    if "/" not in path_part and source.parent == AI_MARKDOWN_DIR and not destination.exists():
+        destination = (ROOT / source.parent / path_part).resolve()
+
+    try:
+        destination.relative_to(ROOT)
+    except ValueError:
+        return None
+
+    if not destination.exists():
+        return f"{source}:{lineno}: missing AI citation target: {raw}"
+
+    if anchor and destination.suffix.lower() == ".md":
+        if destination not in anchor_cache:
+            anchor_cache[destination] = markdown_anchors(destination)
+        if anchor not in anchor_cache[destination]:
+            rel = destination.relative_to(ROOT)
+            return f"{source}:{lineno}: missing AI citation anchor: {rel}#{anchor}"
+
+    return None
+
+
+def main() -> int:
+    errors: list[str] = []
+    anchor_cache: dict[Path, set[str]] = {}
+
+    for rel_path in candidate_files():
+        path = ROOT / rel_path
+        if not path.exists():
+            errors.append(f"{rel_path}: missing AI citation file")
+            continue
+        for lineno, target in extract_targets(path):
+            error = validate_target(rel_path, lineno, target, anchor_cache)
+            if error:
+                errors.append(error)
+
+    if errors:
+        print("AI_CITATION_ERRORS")
+        for error in errors:
+            print(error)
+        print(f"TOTAL={len(errors)}")
+        return 1
+
+    print("OK AI citation paths and anchors checked")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tools/external/AGENTS.md

@@ -49,4 +49,6 @@ skills/auto-skill/scripts/skill-seekers-src -> Skill_Seekers-development/src
 2. **同仓多入口展示**：使用相对软链接，例如 `skills/<name> -> ../tools/external/<name>`。
 3. **项目内小工具**：只有在无上游、体量小、与本项目强耦合时才直接追踪源码。
 4. **生成输出**：默认不跟踪；若必须保留样例，只提交最小样例和生成说明。
-5. **历史备份**：`scripts/backups/` 按项目资产处理，不套用外部仓库清退规则。
+5. **普通目录**：`html-tools-main/`、`my-nvim/`、`MCPlayerTransfer/`、`XHS-image-to-PDF-conversion/` 当前作为小体量工具快照保留；确认上游 URL 后再转 submodule。
+6. **清退触发**：普通目录出现体量膨胀、生成物混入、上游仓库明确或需要频繁升级时，必须优先转 submodule 或迁出主仓库。
+7. **语言统计**：`tools/external/**` 已在根目录 `.gitattributes` 标记为 `linguist-vendored`，避免外部工具源码污染主仓库语言占比。

tools/external/README.md

@@ -37,9 +37,25 @@ tools/external/
 
 - 提示词转换工具已迁移到 `tools/prompts-library/`。
 - AI 聊天记录保存工具已迁移到 `tools/chat-vault/`。
-- 备份脚本已迁移到 `scripts/backups/`。
 - 技能库入口已迁移到 `skills/`。
 
+## 当前源码表达状态
+
+| 目录 | 当前表达 | 处理策略 |
+|:---|:---|:---|
+| `.tmux/` | Git submodule | 保留 submodule 指针 |
+| `tmux/` | Git submodule | 保留 submodule 指针 |
+| `claude-official-skills/` | Git submodule | 保留 submodule 指针，并通过 `skills/claude-official-skills` 软链接展示 |
+| `Skill_Seekers-development/` | Git submodule | 保留 submodule 指针，并通过 `skills/auto-skill/scripts/Skill_Seekers-development` 软链接供 auto-skill 使用 |
+| `html-tools-main/` | 普通目录 | 体量小，暂作为本仓库工具快照保留；确认上游 URL 后可转 submodule |
+| `my-nvim/` | 普通目录 | 体量小，暂作为配置样例保留；确认上游 URL 后可转 submodule |
+| `MCPlayerTransfer/` | 普通目录 | 体量小，暂作为独立工具快照保留；确认上游 URL 后可转 submodule |
+| `XHS-image-to-PDF-conversion/` | 普通目录 | 体量小，暂作为独立工具快照保留；确认上游 URL 后可转 submodule |
+
+普通目录不得继续扩张为大型源码快照；新增外部仓库默认使用 submodule。
+
+为避免外部工具源码影响主仓库语言统计，根目录 `.gitattributes` 已将 `tools/external/**` 标记为 `linguist-vendored`。
+
 ## 当前软链接显示
 
 | 事实来源 | 展示入口 | 说明 |