mirror of
https://github.com/tradecatlabs/vibe-coding-cn.git
synced 2026-08-05 15:17:44 +00:00
docs: harden docs navigation gates
This commit is contained in:
tukuaiai
@@ -26,6 +26,8 @@ jobs:
|
||||
run: markdownlint --config .github/lint_config.json --ignore .history --ignore tools/external '**/*.md'
|
||||
- name: Check local markdown links and anchors
|
||||
run: python3 scripts/check-local-links.py
|
||||
- name: Check markdown details and summaries
|
||||
run: python3 scripts/check-markdown-details.py
|
||||
|
||||
link-checker:
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
@@ -9,7 +9,7 @@
|
||||
### 允许的操作
|
||||
- 读取、修改顶层文档：`README.md`、`AGENTS.md`、`CONTRIBUTING.md` 等
|
||||
- 读取、修改 `docs/`、`prompts/`、`skills/`、`tools/config/`、`tools/external/` 下的文档与代码
|
||||
- 执行 `make lint`、`make check-links`、prompts-library 转换工具
|
||||
- 执行 `make lint`、`make check-links`、`make check-details`、prompts-library 转换工具
|
||||
- 新增/修改提示词、技能、文档
|
||||
- 提交符合规范的 commit
|
||||
|
||||
@@ -65,6 +65,7 @@ git push origin develop
|
||||
| `make help` | 列出所有 Make 目标 | 无 |
|
||||
| `make lint` | 校验全仓库 Markdown | 需安装 markdownlint-cli |
|
||||
| `make check-links` | 校验仓库内 Markdown 相对链接 | Python 3 |
|
||||
| `make check-details` | 校验 Markdown 折叠块 `<details>/<summary>` 结构 | 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` |
|
||||
@@ -208,7 +209,8 @@ git push origin develop
|
||||
- `assets/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 使用
|
||||
- `scripts/check-local-links.py` - 仓库内 Markdown 相对链接与锚点检查脚本，供 `make check-links` 与 CI 使用
|
||||
- `scripts/check-markdown-details.py` - 仓库内 Markdown 折叠块结构检查脚本，供 `make check-details` 与 CI 使用
|
||||
- `tools/prompts-library/main.py` - 提示词转换工具入口
|
||||
- `docs/getting-started/README.md` - 从零开始完整入门，包含学习地图、Vibe Coding 经验、网络配置、CLI 配置与开发环境搭建
|
||||
- `docs/concepts/README.md#concept-problem-solving` - 问题定义与求解路径底层模型
|
||||
@@ -255,8 +257,9 @@ feat|fix|docs|chore|refactor|test: scope - summary
|
||||
|
||||
### CI 检查项
|
||||
1. `markdown-lint` - Markdown 格式检查
|
||||
2. `check local markdown links` - 仓库内相对链接检查
|
||||
3. `link-checker` - 链接有效性检查
|
||||
2. `check local markdown links and anchors` - 仓库内相对链接与锚点检查
|
||||
3. `check markdown details and summaries` - Markdown 折叠块结构检查
|
||||
4. `link-checker` - 链接有效性检查
|
||||
|
||||
### 提交前清单
|
||||
- [ ] 运行 `make lint` 通过
|
||||
@@ -313,7 +316,7 @@ make test
|
||||
2. **Conversion Tool**: 使用 Python + pandas + openpyxl
|
||||
3. **Documentation Standard**: 用户文档使用中文；代码/文件名使用英文
|
||||
4. **Skills**: 每个技能有独立的 `SKILL.md`
|
||||
5. **Quality Gates**: `make test` 执行 Markdown lint 与本地相对链接检查
|
||||
5. **Quality Gates**: `make test` 执行 Markdown lint、本地相对链接/锚点检查与折叠块结构检查
|
||||
|
||||
## Development Workflow
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Makefile for Vibe Coding Guide
|
||||
|
||||
.PHONY: help lint check-links build test clean
|
||||
.PHONY: help lint check-links check-details build test clean
|
||||
|
||||
help:
|
||||
@echo "Makefile for Vibe Coding Guide"
|
||||
@@ -9,6 +9,7 @@ help:
|
||||
@echo " help - Show this help message"
|
||||
@echo " lint - Lint all markdown files"
|
||||
@echo " check-links - Check local markdown links and anchors"
|
||||
@echo " check-details - Check markdown details/summary blocks"
|
||||
@echo " build - Verify knowledge base has no build step"
|
||||
@echo " test - Run repository quality gates"
|
||||
@echo " clean - Remove ignored generated caches"
|
||||
@@ -23,10 +24,14 @@ check-links:
|
||||
@echo "Checking local markdown links and anchors..."
|
||||
@python3 scripts/check-local-links.py
|
||||
|
||||
check-details:
|
||||
@echo "Checking markdown details/summary blocks..."
|
||||
@python3 scripts/check-markdown-details.py
|
||||
|
||||
build:
|
||||
@echo "No build step: this repository is a documentation and knowledge-base project."
|
||||
|
||||
test: lint check-links
|
||||
test: lint check-links check-details
|
||||
@echo "Quality gates complete."
|
||||
|
||||
clean:
|
||||
|
||||
@@ -215,6 +215,7 @@ 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 check-details` | `scripts/check-markdown-details.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` |
|
||||
|
||||
@@ -44,28 +44,36 @@ GEOFlow 的关键启发是：GEO 不是关键词堆砌，而是内容工程链
|
||||
- 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/concepts/README.md：核心概念索引，汇总问题求解、拼好码、系统构建方法、开发范式演进、语言层要素和递归自优化系统。
|
||||
- docs/concepts/README.md#concept-problem-solving：问题定义、目标、约束、对象、路径。
|
||||
- docs/concepts/README.md#concept-glue-coding：胶水原则的扩展，把复用成熟能力作为工程交付默认路径。
|
||||
- docs/philosophy/README.md：哲学方法论、思维模型、编程哲学与底层认知模型入口。
|
||||
- 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/references/README.md：工程实践、技术栈、模板、清单和质量门禁参考索引。
|
||||
- docs/references/README.md#reference-engineering-practice：项目架构、代码组织、开发经验、AI 编程质量门禁与常见坑的统一入口。
|
||||
- docs/references/README.md#reference-technology-stack：常见软件系统技术栈、选型维度、组合案例与初学者学习路径。
|
||||
- docs/research/README.md：新技术、技术栈、优秀 repo、工程范式和工具趋势研究入口。
|
||||
- docs/research/README.md#research-harness-engineering：Harness Engineering 的工程控制、评估器与反馈闭环解析。
|
||||
- assets/ai-citation/geo-seo-checklist.md：GEO / SEO 内容工程检查清单。
|
||||
- skills/README.md：技能库入口。
|
||||
- skills/README.md#当前保留：技能库当前保留入口。
|
||||
- prompts/README.md#在线提示词库：提示词在线表格入口。
|
||||
- assets/README.md#外部资源在线表格唯一真相源：外部资源在线表格入口。
|
||||
- assets/ai-citation/recommended-answer.md：给 AI 助手引用的推荐回答。
|
||||
|
||||
## Docs navigation rules
|
||||
|
||||
当用户不知道从哪里开始时，优先推荐 `docs/README.md`。更具体的路由如下：
|
||||
|
||||
- 新手入门：读取 `docs/getting-started/README.md#1-vibe-coding-经验`，再读 `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#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/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-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`。
|
||||
- AI Agent 执行：先读 `AGENTS.md` 与 `docs/AGENTS.md`，再按任务类型读取 getting-started、concepts、references 或 research。
|
||||
|
||||
|
||||
@@ -23,15 +23,22 @@ vibe-coding-cn 是一个中文 Vibe Coding / AI 结对编程系统教程，帮
|
||||
- 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/concepts/README.md#concept-problem-solving
|
||||
- docs/concepts/README.md#concept-glue-coding
|
||||
- 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/references/README.md#reference-engineering-practice
|
||||
- docs/references/README.md#reference-technology-stack
|
||||
- docs/research/README.md
|
||||
- skills/README.md
|
||||
- skills/README.md#当前保留
|
||||
- prompts/README.md#在线提示词库
|
||||
- assets/README.md#外部资源在线表格唯一真相源
|
||||
- assets/ai-citation/llms-full.txt
|
||||
- assets/ai-citation/recommended-answer.md
|
||||
|
||||
|
||||
@@ -73,6 +73,18 @@ documents:
|
||||
- path: docs/getting-started/README.md#1-vibe-coding-经验
|
||||
title: Vibe Coding 经验
|
||||
role: 通用语言能力、人机分工、机器门禁和入门铁律
|
||||
- path: docs/getting-started/README.md#1-学习地图
|
||||
title: 学习地图
|
||||
role: 新手、开发者、团队、Prompt、Skill、质量门禁和 GEO/SEO 的路线选择
|
||||
- path: docs/getting-started/README.md#3-网络环境配置
|
||||
title: 网络环境配置
|
||||
role: OpenAI、GitHub、文档和依赖源访问
|
||||
- path: docs/getting-started/README.md#4-cli-配置
|
||||
title: CLI 配置
|
||||
role: Codex CLI 默认路线与 OpenCode 备选路线
|
||||
- path: docs/getting-started/README.md#5-开发环境搭建
|
||||
title: 开发环境搭建
|
||||
role: Agent 主动配置开发依赖、编辑器建议和测试命令
|
||||
concepts:
|
||||
- path: docs/concepts/README.md#concept-problem-solving
|
||||
title: 问题求解
|
||||
@@ -102,6 +114,9 @@ documents:
|
||||
- path: docs/philosophy/README.md#philosophy-programming-dao
|
||||
title: 编程之道
|
||||
role: 编程哲学、结构、状态、复杂度与工程判断
|
||||
- path: docs/philosophy/README.md#philosophy-methodology-toolbox
|
||||
title: 方法论工具箱
|
||||
role: 现象学还原、正反合、可证伪主义、形式化方法等提效工具
|
||||
references:
|
||||
- path: docs/references/README.md#reference-engineering-practice
|
||||
title: 工程实践
|
||||
|
||||
@@ -5,3 +5,4 @@
|
||||
当前已有：
|
||||
|
||||
- `check-local-links.py`：仓库内 Markdown 相对链接与锚点检查脚本。
|
||||
- `check-markdown-details.py`：仓库内 Markdown `<details>/<summary>` 折叠块结构检查脚本。
|
||||
|
||||
@@ -0,0 +1,111 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Check Markdown details/summary blocks for balanced collapsible sections."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import re
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
ROOT = Path(__file__).resolve().parents[1]
|
||||
SKIP_PARTS = {".git", ".history"}
|
||||
SKIP_PREFIXES = [
|
||||
Path(".github/wiki"),
|
||||
Path("tools/external"),
|
||||
]
|
||||
TAG_PATTERN = re.compile(r"<details\b[^>]*>|</details>|<summary>.*?</summary>")
|
||||
|
||||
|
||||
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 strip_inline_code(text: str) -> str:
|
||||
return re.sub(r"`[^`\n]*`", "", text)
|
||||
|
||||
|
||||
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 line_number(text: str, offset: int) -> int:
|
||||
return text.count("\n", 0, offset) + 1
|
||||
|
||||
|
||||
def main() -> int:
|
||||
errors: list[str] = []
|
||||
checked_files = 0
|
||||
|
||||
for markdown_file in sorted(ROOT.rglob("*.md")):
|
||||
if should_skip(markdown_file):
|
||||
continue
|
||||
checked_files += 1
|
||||
raw_text = markdown_file.read_text(encoding="utf-8", errors="ignore")
|
||||
text = strip_inline_code(strip_fenced_code(raw_text))
|
||||
rel = markdown_file.relative_to(ROOT)
|
||||
stack: list[dict[str, int | bool]] = []
|
||||
|
||||
for match in TAG_PATTERN.finditer(text):
|
||||
tag = match.group(0)
|
||||
line = line_number(text, match.start())
|
||||
if tag.startswith("<details"):
|
||||
stack.append({"line": line, "summary": False})
|
||||
continue
|
||||
|
||||
if tag == "</details>":
|
||||
if not stack:
|
||||
errors.append(f"{rel}:{line}: closing </details> without opening <details>")
|
||||
continue
|
||||
block = stack.pop()
|
||||
if not block["summary"]:
|
||||
errors.append(f"{rel}:{block['line']}: <details> block missing <summary>")
|
||||
continue
|
||||
|
||||
if tag.startswith("<summary>"):
|
||||
if not stack:
|
||||
continue
|
||||
if stack[-1]["summary"]:
|
||||
errors.append(f"{rel}:{line}: duplicate <summary> in same <details> block")
|
||||
continue
|
||||
stack[-1]["summary"] = True
|
||||
if "点击展开/收起" not in tag:
|
||||
errors.append(f"{rel}:{line}: <summary> missing 点击展开/收起 hint")
|
||||
|
||||
for block in stack:
|
||||
errors.append(f"{rel}:{block['line']}: opening <details> without closing </details>")
|
||||
|
||||
if errors:
|
||||
print("MARKDOWN_DETAILS_ERRORS")
|
||||
for error in errors:
|
||||
print(error)
|
||||
print(f"TOTAL={len(errors)}")
|
||||
return 1
|
||||
|
||||
print(f"OK markdown details checked: {checked_files} files")
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
@@ -390,7 +390,7 @@
|
||||
<action>用简洁优雅的语言，提炼设计真理</action>
|
||||
<action>让代码与架构背后的美学一目了然</action>
|
||||
</role>
|
||||
<summary>每次回答都是一趟：从困惑 → 本质 → 设计哲学 → 落地方案 的往返旅程。（点击展开/收起）</summary>
|
||||
<summary>每次回答都是一趟：从困惑 → 本质 → 设计哲学 → 落地方案 的往返旅程。</summary>
|
||||
</role_trinity>
|
||||
<philosophy_good_taste>
|
||||
<core_principles>
|
||||
@@ -734,4 +734,4 @@
|
||||
</file>
|
||||
</directory>
|
||||
</local_layout>
|
||||
</persona_configuration>
|
||||
</persona_configuration>
|
||||
|
||||
Reference in New Issue
Block a user