From 30ee6d0e201545d0b3836c6c8738bf28578d3300 Mon Sep 17 00:00:00 2001 From: tukuaiai Date: Mon, 4 May 2026 05:07:59 +0800 Subject: [PATCH] fix: github - keep root readme authoritative --- .github/AGENTS.md | 2 ++ .github/README.md | 19 ------------------- AGENTS.md | 1 + scripts/AGENTS.md | 1 + scripts/README.md | 2 +- scripts/check-directory-docs.py | 8 +++++++- 6 files changed, 12 insertions(+), 21 deletions(-) delete mode 100644 .github/README.md diff --git a/.github/AGENTS.md b/.github/AGENTS.md index f6c8407..f3d6db2 100644 --- a/.github/AGENTS.md +++ b/.github/AGENTS.md @@ -2,6 +2,8 @@ 本目录承载 GitHub 平台自动化与协作配置。 +说明：本目录不放 `README.md`，避免 GitHub 仓库首页误展示平台配置说明；目录规则只保留在 `AGENTS.md`。 + ## 约束 - 修改 `workflows/` 前必须确认对应本地命令或验证方式。 diff --git a/.github/README.md b/.github/README.md deleted file mode 100644 index 399e020..0000000 --- a/.github/README.md +++ /dev/null @@ -1,19 +0,0 @@ -# .github - -GitHub 平台配置目录，集中管理 CI、Issue 模板、PR 模板、安全政策、赞助配置和 Wiki 说明。 - -## 目录 - -- `workflows/` - GitHub Actions 工作流。 -- `ISSUE_TEMPLATE/` - Issue 表单和模板。 -- `PULL_REQUEST_TEMPLATE.md` - PR 描述模板。 -- `SECURITY.md` - 安全报告入口。 -- `WIKI.md` - Wiki 使用说明。 -- `labeler.yml` - PR 自动标签规则。 -- `lint_config.json` - Markdown lint 配置。 - -## 维护规则 - -- CI 变更必须能用本地命令复现核心检查。 -- 外链检查规则集中放在 `.lychee.toml`。 -- 不在此目录保存密钥、Token 或本地账号信息。 diff --git a/AGENTS.md b/AGENTS.md index abb6f24..e0b5f9c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -221,6 +221,7 @@ git push origin develop - `assets/ai-citation/llms-full.txt` - 面向 AI 助手的完整上下文入口，用于 GEO / AI 推荐与引用 - `assets/ai-citation/` - AI 引用语料包，包含摘要、FAQ、对比、推荐回答与 GEO/SEO 检查清单 - `.gitattributes` - GitHub Linguist 语言统计规则，当前将 `tools/external/**` 标记为 vendored +- `.github/AGENTS.md` - GitHub 平台配置目录规则；根 `.github/` 不保留 `README.md`，避免 GitHub 首页误展示目录说明 - `.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 使用 diff --git a/scripts/AGENTS.md b/scripts/AGENTS.md index d1c2e11..32e7e88 100644 --- a/scripts/AGENTS.md +++ b/scripts/AGENTS.md @@ -6,6 +6,7 @@ - 脚本默认从仓库根目录运行，路径解析必须稳定。 - 新增检查脚本时，同步更新 `scripts/README.md`、`Makefile`、CI 和根目录 `AGENTS.md` 的命令清单。 +- `check-directory-docs.py` 对根 `.github/` 只要求 `AGENTS.md`，不要重新补 `.github/README.md`。 - 修改 docs 线性 README 的主章节或锚点后，优先运行 `python3 scripts/sync-doc-toc.py`，再运行 `make test`。 - 修改 `docs/references/sources/` 后，运行 `make sync-reference-readme`，再运行 `make test`。 - 检查失败输出应包含文件路径、行号或可定位的错误信息。 diff --git a/scripts/README.md b/scripts/README.md index b0eff8d..1559e53 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -7,7 +7,7 @@ - `check-local-links.py`：仓库内 Markdown 相对链接与锚点检查脚本。 - `check-markdown-details.py`：仓库内 Markdown `
/` 折叠块结构检查脚本。 - `check-doc-structure.py`：`docs/` 线性 README 的主章节顺序、重复锚点与细粒度目录入口检查脚本。 -- `check-directory-docs.py`：仓库自有目录 `README.md` / `AGENTS.md` 覆盖检查脚本。 +- `check-directory-docs.py`：仓库自有目录 `README.md` / `AGENTS.md` 覆盖检查脚本；根 `.github/` 仅要求 `AGENTS.md`，避免 GitHub 首页误展示平台配置说明。 - `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-directory-docs.py b/scripts/check-directory-docs.py index b8d8ac2..7080e39 100644 --- a/scripts/check-directory-docs.py +++ b/scripts/check-directory-docs.py @@ -41,6 +41,11 @@ REQUIRED_DIRS = [ Path("tools/prompts-library/docs"), Path("tools/prompts-library/scripts"), ] +README_OPTIONAL_DIRS = { + # GitHub repository pages can surface `.github/README.md` as an overview file. + # Keep the root project README authoritative and use `.github/AGENTS.md` only. + Path(".github"), +} GENERATED_OR_VENDOR_DIRS = [ Path("node_modules"), ] @@ -84,7 +89,8 @@ def main() -> int: if not directory.is_dir(): errors.append(f"{rel_dir}: required directory is missing") continue - for filename in ("README.md", "AGENTS.md"): + required_files = ["AGENTS.md"] if rel_dir in README_OPTIONAL_DIRS else ["README.md", "AGENTS.md"] + for filename in required_files: if not (directory / filename).is_file(): errors.append(f"{rel_dir}/{filename}: missing required directory document")