chore: harden repository quality gates

.github/workflows/ci.yml

@@ -24,6 +24,8 @@ jobs:
       run: npm install -g markdownlint-cli
     - name: Run markdownlint
       run: markdownlint --config .github/lint_config.json --ignore .history --ignore tools/external --ignore scripts/backups/gz '**/*.md'
+    - name: Check local markdown links
+      run: python3 scripts/check-local-links.py
 
   link-checker:
     runs-on: ubuntu-latest

.gitignore

@@ -56,6 +56,7 @@ skills/auto-skill/scripts/.venv-skill-seekers/
 
 # prompts-library generated exports
 tools/prompts-library/prompt_jsonl/
+tools/external/my-nvim/nvim-config/nvim
 
 libs/external/tmux
 libs/external/.tmux

AGENTS.md

@@ -66,6 +66,8 @@ git push origin develop
 |:---|:---|:---|
 | `make help` | 列出所有 Make 目标 | 无 |
 | `make lint` | 校验全仓库 Markdown | 需安装 markdownlint-cli |
+| `make check-links` | 校验仓库内 Markdown 相对链接 | Python 3 |
+| `make test` | 执行本地质量门禁 | Node.js 22+、Python 3 |
 | `git submodule update --init --recursive` | 初始化外部 Git 仓库指针 | Git |
 | `bash scripts/backups/一键备份.sh` | 创建完整项目备份 | 无 |
 | `python3 scripts/backups/快速备份.py` | Python 版备份脚本 | Python 3.8+ |
@@ -216,6 +218,8 @@ git push origin develop
 - `metadata/ai-citation/` - AI 引用语料包，包含摘要、FAQ、对比、推荐回答与 GEO/SEO 检查清单
 - `.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 使用
+- `docs/guides/仓库维护与质量门禁.md` - 仓库维护、迁移检查和质量门禁指南
 - `tools/prompts-library/main.py` - 提示词转换工具入口
 - `scripts/backups/一键备份.sh` - 备份脚本入口
 - `docs/getting-started/Codex-CLI配置.md` - 零基础路径的默认 AI CLI 配置入口
@@ -266,7 +270,8 @@ feat|fix|docs|chore|refactor|test: scope - summary
 
 ### CI 检查项
 1. `markdown-lint` - Markdown 格式检查
-2. `link-checker` - 链接有效性检查
+2. `check local markdown links` - 仓库内相对链接检查
+3. `link-checker` - 链接有效性检查
 
 ### 提交前清单
 - [ ] 运行 `make lint` 通过

CHANGELOG.md

@@ -7,3 +7,5 @@
 - 启动标准知识库结构迁移：新增 `docs/`、`metadata/`、`scripts/`、`tools/` 骨架。
 - 完成第一轮完全搬家：`assets/documents/` 迁入 `docs/`，`assets/skills/` 迁入 `skills/`，`assets/prompt/` 迁入 `prompts/`，`assets/config/` 迁入 `tools/config/`，`assets/repos/` 拆分为 `tools/external/`、`tools/prompts-library/`、`tools/chat-vault/` 与 `scripts/backups/`。
 - 更新 README、AGENTS、llms、metadata、CI 与目录级 AGENTS，统一新知识库路径口径。
+- 增加 `scripts/check-local-links.py`、`make check-links` 与 `make test`，把本地链接检查纳入质量门禁和 CI。
+- 清退 `tools/external/my-nvim/nvim-config/nvim` 二进制运行时，改为文档说明从官方渠道安装 Neovim。

Makefile

@@ -1,6 +1,6 @@
 # Makefile for Vibe Coding Guide
 
-.PHONY: help lint build test clean
+.PHONY: help lint check-links build test clean
 
 help:
 	@echo "Makefile for Vibe Coding Guide"
@@ -8,9 +8,10 @@ help:
 	@echo "Available commands:"
 	@echo "  help     - Show this help message"
 	@echo "  lint     - Lint all markdown files"
-	@echo "  build    - Build the project (Placeholder)"
-	@echo "  test     - Run tests (Placeholder)"
-	@echo "  clean    - Clean build artifacts (Placeholder)"
+	@echo "  check-links - Check local markdown links"
+	@echo "  build    - Verify knowledge base has no build step"
+	@echo "  test     - Run repository quality gates"
+	@echo "  clean    - Remove ignored generated caches"
 	@echo ""
 
 lint:
@@ -18,17 +19,18 @@ lint:
 	@npm install -g markdownlint-cli
 	@markdownlint --config .github/lint_config.json --ignore .history --ignore tools/external --ignore scripts/backups/gz '**/*.md'
 
-build:
-	@echo "Building the project..."
-	# Add your project build commands here
-	@echo "Build complete."
+check-links:
+	@echo "Checking local markdown links..."
+	@python3 scripts/check-local-links.py
 
-test:
-	@echo "Running tests..."
-	# Add your test commands here
-	@echo "Tests complete."
+build:
+	@echo "No build step: this repository is a documentation and knowledge-base project."
+
+test: lint check-links
+	@echo "Quality gates complete."
 
 clean:
-	@echo "Cleaning up build artifacts..."
-	# Add your clean commands here (e.g., rm -rf dist/ build/)
+	@echo "Cleaning ignored generated caches..."
+	@find . -type d -name '__pycache__' -prune -exec rm -rf {} +
+	@rm -rf tools/prompts-library/prompt_jsonl
 	@echo "Cleanup complete."

README.md

@@ -214,6 +214,8 @@ pip install -r tools/prompts-library/scripts/requirements.txt
 |:---|:---|:---|
 | 查看 Make 任务 | `make help` | `Makefile` |
 | 全仓 Markdown lint | `make lint` | `Makefile` + `.github/lint_config.json` |
+| 本地相对链接检查 | `make check-links` | `scripts/check-local-links.py` |
+| 全部本地质量门禁 | `make test` | `Makefile` |
 | 提示词格式转换 | `cd tools/prompts-library && python3 main.py` | `tools/prompts-library/main.py` |
 | 完整备份 | `bash scripts/backups/一键备份.sh` | `scripts/backups/README.md` |
 | Python 备份 | `python3 scripts/backups/快速备份.py` | `scripts/backups/README.md` |
@@ -222,13 +224,13 @@ pip install -r tools/prompts-library/scripts/requirements.txt
 ### 配置与 CI
 
 - Markdown lint 配置：`.github/lint_config.json`
-- CI 配置：`.github/workflows/ci.yml`，在 `main` 分支的 push / pull_request 上运行 markdown-lint 与 link-checker
+- CI 配置：`.github/workflows/ci.yml`，在 `develop` / `master` 分支的 push / pull_request 上运行 markdown-lint、本地链接检查与 link-checker
 - Codex 配置基线：`tools/config/.codex/config.toml`
 - Submodule 来源：`.gitmodules`
 
 ### 部署
 
-TODO：仓库内没有发现 Dockerfile、docker-compose.yml、K8s/Helm 部署入口或可验证服务端口；如后续新增部署方式，需要同步本节。
+本仓库是文档与知识库项目，当前没有 Dockerfile、docker-compose.yml、K8s/Helm 部署入口或固定服务端口；发布质量以 `make test` 与 GitHub Actions CI 为准。
 
 </details>
 

docs/README.md

@@ -22,3 +22,4 @@
 4. [拼好码](./concepts/拼好码.md)
 5. [强前置条件约束](./references/强前置条件约束.md)
 6. [GEO 与 SEO 优化方法](./playbooks/GEO与SEO优化方法.md)
+7. [仓库维护与质量门禁](./guides/仓库维护与质量门禁.md)

docs/guides/README.md

@@ -7,3 +7,7 @@
 - [从零开始](../getting-started/)
 - [可复用流程](../playbooks/)
 - [参考清单](../references/)
+
+## 当前指南
+
+- [仓库维护与质量门禁](./仓库维护与质量门禁.md)

docs/guides/仓库维护与质量门禁.md

@@ -0,0 +1,64 @@
+# 仓库维护与质量门禁
+
+本文档是维护 `vibe-coding-cn` 的操作指南，用于保证目录迁移、文档更新、Skills 调整和工具配置变更后仍然可验证。
+
+## 必跑命令
+
+```bash
+make test
+```
+
+`make test` 当前会执行：
+
+1. `make lint`：使用 `.github/lint_config.json` 校验 Markdown。
+2. `make check-links`：使用 `scripts/check-local-links.py` 校验仓库内 Markdown 相对链接。
+
+## 单项检查
+
+```bash
+make lint
+make check-links
+git diff --check
+git submodule status --recursive
+find . -xtype l -print
+```
+
+验收标准：
+
+- `make lint` 无错误。
+- `make check-links` 输出 `OK local links checked`。
+- `git diff --check` 无输出。
+- `git submodule status --recursive` 能列出所有 submodule 指针。
+- `find . -xtype l -print` 无输出。
+
+## CI 规则
+
+GitHub Actions 的 CI 监听：
+
+- `push` 到 `develop` 或 `master`
+- `pull_request` 到 `develop` 或 `master`
+- 手动触发 `workflow_dispatch`
+
+CI 使用 Node.js 22 运行 `markdownlint-cli`，避免新版依赖在旧 Node.js 上因正则 `/v` flag 崩溃。
+
+## 大文件规则
+
+- 不提交二进制运行时、构建产物、缓存目录和生成数据。
+- 第三方仓库优先放在 `tools/external/`，完整仓库优先使用 Git submodule。
+- 工具生成物默认加入 `.gitignore`。
+- 如果确需保留大文件，必须在对应 README 中写明用途、来源、更新方式和替代方案。
+
+## 迁移检查
+
+目录迁移或重命名后，必须检查：
+
+1. `README.md`
+2. `AGENTS.md`
+3. `llms.txt`
+4. `llms-full.txt`
+5. `metadata/redirects.yml`
+6. 相关目录下的 `README.md` / `AGENTS.md`
+7. `.github/workflows/ci.yml`
+8. `.github/labeler.yml`
+
+旧路径只允许出现在 `CHANGELOG.md`、`metadata/redirects.yml` 或调试/迁移记录中。

scripts/check-local-links.py

@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+"""Check local Markdown links that should resolve inside this repository."""
+
+from __future__ import annotations
+
+import re
+import sys
+import urllib.parse
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+SKIP_PARTS = {".git", ".history"}
+SKIP_PREFIXES = [
+    Path(".github/wiki"),
+    Path("tools/external"),
+    Path("tools/chat-vault"),
+    Path("scripts/backups/gz"),
+]
+LINK_PATTERNS = [
+    re.compile(r"!??\[[^\]]*\]\(([^)]+)\)"),
+    re.compile(r"\b(?:href|src)=[\"']([^\"']+)[\"']"),
+]
+EXTERNAL_PREFIXES = (
+    "#",
+    "http://",
+    "https://",
+    "wss://",
+    "ws://",
+    "mailto:",
+    "tel:",
+    "data:",
+)
+
+
+def should_skip(path: Path) -> bool:
+    rel = path.relative_to(ROOT)
+    if any(part in SKIP_PARTS for part in rel.parts):
+        return True
+    return any(rel == prefix or prefix in rel.parents for prefix in SKIP_PREFIXES)
+
+
+def normalize_target(raw: str) -> str:
+    raw = raw.strip()
+    if not raw or raw.startswith(EXTERNAL_PREFIXES):
+        return ""
+    target = raw.split()[0] if " " in raw and not raw.startswith("<") else raw
+    target = target.strip("<>").split("#", 1)[0]
+    return urllib.parse.unquote(target)
+
+
+def main() -> int:
+    missing: list[tuple[Path, str, Path]] = []
+    checked_files = 0
+
+    for markdown_file in sorted(ROOT.rglob("*.md")):
+        if should_skip(markdown_file):
+            continue
+        checked_files += 1
+        text = markdown_file.read_text(encoding="utf-8", errors="ignore")
+
+        for pattern in LINK_PATTERNS:
+            for match in pattern.finditer(text):
+                raw = match.group(1)
+                target = normalize_target(raw)
+                if not target or target.startswith(("/", "\\")):
+                    continue
+
+                destination = (markdown_file.parent / target).resolve()
+                try:
+                    destination.relative_to(ROOT)
+                except ValueError:
+                    continue
+
+                if not destination.exists():
+                    missing.append((markdown_file.relative_to(ROOT), raw, markdown_file.parent / target))
+
+    if missing:
+        print("MISSING_LINKS")
+        for source, raw, resolved in missing:
+            print(f"{source} -> {raw} => {resolved.relative_to(ROOT)}")
+        print(f"TOTAL={len(missing)}")
+        return 1
+
+    print(f"OK local links checked: {checked_files} files")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tools/external/my-nvim/README.md

@@ -9,7 +9,7 @@
 - **状态**: 经过全面测试，无任何问题或报错
 
 ### 📦 包含内容
-- ✅ 最新版 Neovim v0.11.5 AppImage 可执行文件
+- ✅ LazyVim 配置文件；Neovim 可执行文件需从官方渠道或系统包管理器安装
 - ✅ 标准 LazyVim 配置框架
 - ✅ 修复的 Neotree 配置（无重复问题）
 - ✅ 默认 tokyonight 主题
@@ -29,22 +29,18 @@ cd vim
 # 复制配置文件
 cp -r nvim-config/* ~/.config/
 
-# 复制可执行文件
-cp nvim-config/nvim ~/.local/bin/
-chmod +x ~/.local/bin/nvim
-
-# 确保路径在 PATH 中
-echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
-source ~/.bashrc
+# 安装 Neovim
+# 推荐使用系统包管理器、官方 AppImage 或 GitHub Release。
+# 不再在本仓库跟踪 nvim 二进制运行时。
 ```
 
 ### 3. 启动使用
 ```bash
 # 直接启动
-~/.local/bin/nvim
+nvim
 
 # 或使用别名（推荐）
-alias n='~/.local/bin/nvim'
+alias n='nvim'
 n
 ```
 
@@ -118,10 +114,10 @@ vim.api.nvim_create_autocmd("VimEnter", {
 ### 启动测试
 ```bash
 # 基础启动测试
-~/.local/bin/nvim --headless -c "echo 'OK'" -c "qa"
+nvim --headless -c "echo 'OK'" -c "qa"
 
 # 配置加载测试
-~/.local/bin/nvim --headless -c "lua print('Config OK')" -c "qa"
+nvim --headless -c "lua print('Config OK')" -c "qa"
 ```
 
 ### 健康检查
@@ -135,7 +131,6 @@ nvim-config/
 ├── init.lua                    # 入口文件
 ├── lazy-lock.json             # 插件锁文件
 ├── lazyvim.json               # LazyVim 配置
-├── nvim                       # Neovim v0.11.5 AppImage
 ├── lua/
 │   ├── config/
 │   │   ├── autocmds.lua       # 自动命令
@@ -197,4 +192,4 @@ Ctrl+w h/j/k/l
 - ✅ 美观实用的界面设计
 - ✅ 经过全面测试验证
 
-**确定没有任何问题和报错** - 你可以放心使用这份完美配置！
+**确定没有任何问题和报错** - 你可以放心使用这份完美配置！

tools/external/my-nvim/nvim-config/README.md

@@ -9,7 +9,7 @@
 - **状态**: 经过全面测试，无任何问题或报错
 
 ### 📦 包含内容
-- ✅ 最新版 Neovim v0.11.5 AppImage 可执行文件
+- ✅ LazyVim 配置文件；Neovim 可执行文件需从官方渠道或系统包管理器安装
 - ✅ 标准 LazyVim 配置框架
 - ✅ 修复的 Neotree 配置（无重复问题）
 - ✅ 默认 tokyonight 主题
@@ -29,22 +29,18 @@ cd vim
 # 复制配置文件
 cp -r nvim-config/* ~/.config/
 
-# 复制可执行文件
-cp nvim-config/nvim ~/.local/bin/
-chmod +x ~/.local/bin/nvim
-
-# 确保路径在 PATH 中
-echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
-source ~/.bashrc
+# 安装 Neovim
+# 推荐使用系统包管理器、官方 AppImage 或 GitHub Release。
+# 不再在本仓库跟踪 nvim 二进制运行时。
 ```
 
 ### 3. 启动使用
 ```bash
 # 直接启动
-~/.local/bin/nvim
+nvim
 
 # 或使用别名（推荐）
-alias n='~/.local/bin/nvim'
+alias n='nvim'
 n
 ```
 
@@ -118,10 +114,10 @@ vim.api.nvim_create_autocmd("VimEnter", {
 ### 启动测试
 ```bash
 # 基础启动测试
-~/.local/bin/nvim --headless -c "echo 'OK'" -c "qa"
+nvim --headless -c "echo 'OK'" -c "qa"
 
 # 配置加载测试
-~/.local/bin/nvim --headless -c "lua print('Config OK')" -c "qa"
+nvim --headless -c "lua print('Config OK')" -c "qa"
 ```
 
 ### 健康检查
@@ -135,7 +131,6 @@ nvim-config/
 ├── init.lua                    # 入口文件
 ├── lazy-lock.json             # 插件锁文件
 ├── lazyvim.json               # LazyVim 配置
-├── nvim                       # Neovim v0.11.5 AppImage
 ├── lua/
 │   ├── config/
 │   │   ├── autocmds.lua       # 自动命令
@@ -197,4 +192,4 @@ Ctrl+w h/j/k/l
 - ✅ 美观实用的界面设计
 - ✅ 经过全面测试验证
 
-**确定没有任何问题和报错** - 你可以放心使用这份完美配置！
+**确定没有任何问题和报错** - 你可以放心使用这份完美配置！