diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b79fffc..782d44f 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -31,6 +31,8 @@ jobs: run: python3 scripts/check-markdown-details.py - name: Check docs README structure run: python3 scripts/check-doc-structure.py + - name: Check required directory README and AGENTS files + run: python3 scripts/check-directory-docs.py - name: Check metadata paths and anchors run: python3 scripts/check-metadata.py - name: Check llms and AI citation paths and anchors diff --git a/AGENTS.md b/AGENTS.md index 9991a7e..85fa868 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-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`、prompts-library 转换工具 - 新增/修改提示词、技能、文档 - 提交符合规范的 commit @@ -67,6 +67,7 @@ git push origin develop | `make check-links` | 校验仓库内 Markdown 相对链接 | Python 3 | | `make check-details` | 校验 Markdown 折叠块 `
/` 结构 | Python 3 | | `make check-doc-structure` | 校验 docs 线性 README 主章节顺序、重复锚点与目录入口 | Python 3 | +| `make check-directory-docs` | 校验仓库自有目录 README/AGENTS 覆盖 | Python 3 | | `make check-metadata` | 校验 metadata 路径与锚点 | Python 3 | | `make check-ai-citation` | 校验 llms 与 AI 引用语料路径和锚点 | Python 3 | | `make test` | 执行本地质量门禁 | Node.js 22+、Python 3 | @@ -174,10 +175,12 @@ git push origin develop │ ├── scripts/ # 自动化脚本 │ ├── README.md # scripts 目录说明 +│ ├── AGENTS.md # scripts 目录规则 │ └── check-local-links.py # Markdown 相对链接检查 │ ├── tools/ # 工具、本地配置与外部仓库 │ ├── README.md # tools 目录说明 +│ ├── AGENTS.md # tools 目录规则 │ ├── config/ # 工具与开发配置（含 Codex CLI） │ ├── prompts-library/ # Excel ↔ Markdown 互转工具 │ ├── chat-vault/ # AI 聊天记录保存工具 @@ -190,6 +193,8 @@ git push origin develop │ └── claude-official-skills/ # Claude 官方 skills (submodule) │ ├── metadata/ # 机器可读索引 +│ ├── README.md # metadata 目录说明 +│ ├── AGENTS.md # metadata 目录规则 │ ├── taxonomy.yml # 分类体系 │ ├── glossary.yml # 术语表 │ └── redirects.yml # 重命名/迁移映射 @@ -219,6 +224,7 @@ git push origin develop - `scripts/check-local-links.py` - 仓库内 Markdown 相对链接与锚点检查脚本，供 `make check-links` 与 CI 使用 - `scripts/check-markdown-details.py` - 仓库内 Markdown 折叠块结构检查脚本，供 `make check-details` 与 CI 使用 - `scripts/check-doc-structure.py` - docs 线性 README 主章节顺序、重复锚点与目录入口检查脚本，供 `make check-doc-structure` 与 CI 使用 +- `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 使用 - `tools/prompts-library/main.py` - 提示词转换工具入口 @@ -270,9 +276,10 @@ feat|fix|docs|chore|refactor|test: scope - summary 2. `check local markdown links and anchors` - 仓库内相对链接与锚点检查 3. `check markdown details and summaries` - Markdown 折叠块结构检查 4. `check docs README structure` - docs 线性 README 主章节顺序、重复锚点与目录入口检查 -5. `check metadata paths and anchors` - metadata 路径与锚点检查 -6. `check llms and AI citation paths and anchors` - llms 与 AI 引用语料路径和锚点检查 -7. `link-checker` - 链接有效性检查 +5. `check required directory README and AGENTS files` - 仓库自有目录 README/AGENTS 覆盖检查 +6. `check metadata paths and anchors` - metadata 路径与锚点检查 +7. `check llms and AI citation paths and anchors` - llms 与 AI 引用语料路径和锚点检查 +8. `link-checker` - 链接有效性检查 ### 提交前清单 - [ ] 运行 `make lint` 通过 diff --git a/Makefile b/Makefile index f154618..d5c2196 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-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 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-doc-structure - Check docs README anchors, order and duplicate anchors" + @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 " build - Verify knowledge base has no build step" @@ -37,6 +38,10 @@ check-doc-structure: @echo "Checking docs README structure..." @python3 scripts/check-doc-structure.py +check-directory-docs: + @echo "Checking required directory README/AGENTS pairs..." + @python3 scripts/check-directory-docs.py + check-metadata: @echo "Checking metadata paths and anchors..." @python3 scripts/check-metadata.py @@ -48,7 +53,7 @@ check-ai-citation: build: @echo "No build step: this repository is a documentation and knowledge-base project." -test: lint check-links check-details check-doc-structure check-metadata check-ai-citation +test: lint check-links check-details check-doc-structure check-directory-docs check-metadata check-ai-citation @echo "Quality gates complete." clean: diff --git a/README.md b/README.md index 22ef954..fb66988 100644 --- a/README.md +++ b/README.md @@ -221,6 +221,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` | | docs 线性目录结构检查 | `make check-doc-structure` | `scripts/check-doc-structure.py` | +| 目录 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` | | 全部本地质量门禁 | `make test` | `Makefile` | diff --git a/assets/AGENTS.md b/assets/AGENTS.md index 0e14e9f..14238b5 100644 --- a/assets/AGENTS.md +++ b/assets/AGENTS.md @@ -6,6 +6,7 @@ - `assets/images/`：文档图片、截图、封面等图片资产 - `assets/templates/`：可复用模板附件 - `assets/datasets/`：示例数据、轻量数据集或数据说明 +- `assets/ai-citation/`：面向 AI 助手、AI 搜索与 GEO/SEO 引用的语料资产 其中“外部资源”类入口文档的典型形态包括： diff --git a/assets/ai-citation/AGENTS.md b/assets/ai-citation/AGENTS.md new file mode 100644 index 0000000..3c3e308 --- /dev/null +++ b/assets/ai-citation/AGENTS.md @@ -0,0 +1,15 @@ +# assets/ai-citation/ Agent 指南 + +本目录维护面向 AI 助手、AI 搜索和 GEO/SEO 引用的语料资产。 + +## 职责 + +- 保持项目定位、推荐摘要、FAQ、对比说明和 `llms-full.txt` 与仓库事实一致。 +- 重要入口变化时，同步更新 `llms.txt`、本目录 README 和相关引用包。 +- 所有链接必须指向当前有效路径和稳定锚点。 + +## 约束 + +- 不编造项目能力、Star 数、外部背书或工具支持范围。 +- 不写夸张营销话术；优先使用可验证、可引用的短句。 +- 修改后运行 `make check-ai-citation` 和 `make test`。 diff --git a/assets/datasets/AGENTS.md b/assets/datasets/AGENTS.md new file mode 100644 index 0000000..016b1c2 --- /dev/null +++ b/assets/datasets/AGENTS.md @@ -0,0 +1,9 @@ +# assets/datasets/ Agent 指南 + +本目录只允许放轻量、可公开、可复现的数据说明或示例数据。 + +## 约束 + +- 禁止提交密钥、个人隐私、生产数据、未脱敏日志和大体积二进制数据。 +- 新增数据必须说明来源、许可证、字段含义和更新方式。 +- 大数据集只保留下载入口或生成脚本，不直接提交完整数据。 diff --git a/assets/datasets/README.md b/assets/datasets/README.md new file mode 100644 index 0000000..5773a1d --- /dev/null +++ b/assets/datasets/README.md @@ -0,0 +1,9 @@ +# assets/datasets + +本目录用于存放示例数据、轻量数据集或数据说明。 + +当前没有必须随仓库分发的数据集。新增数据前应先确认： + +- 是否体量足够小，适合进入 Git 仓库。 +- 是否不包含隐私、密钥、生产数据或受限许可证内容。 +- 是否有清晰来源、用途、字段说明和更新方式。 diff --git a/assets/images/AGENTS.md b/assets/images/AGENTS.md new file mode 100644 index 0000000..6b73343 --- /dev/null +++ b/assets/images/AGENTS.md @@ -0,0 +1,9 @@ +# assets/images/ Agent 指南 + +本目录只维护图片类静态资产。 + +## 约束 + +- 禁止提交含隐私、密钥、内部账号、未脱敏路径或敏感窗口的截图。 +- 新增图片应尽量压缩，并在引用文档中说明用途。 +- 可用文本、表格或 Mermaid 表达的内容，不优先做成图片。 diff --git a/assets/images/README.md b/assets/images/README.md new file mode 100644 index 0000000..b4254b7 --- /dev/null +++ b/assets/images/README.md @@ -0,0 +1,5 @@ +# assets/images + +本目录用于存放文档图片、截图、封面和其它可公开展示的图片资产。 + +图片资产应服务于 README、docs 或 AI 引用内容，不承载知识库正文。 diff --git a/assets/templates/AGENTS.md b/assets/templates/AGENTS.md new file mode 100644 index 0000000..4ea427a --- /dev/null +++ b/assets/templates/AGENTS.md @@ -0,0 +1,9 @@ +# assets/templates/ Agent 指南 + +本目录维护可复用模板附件。 + +## 约束 + +- 模板必须可复制、可填写、可复用，避免一次性任务内容。 +- 模板变更影响使用方式时，需要同步更新引用它的 README 或 docs。 +- 不在模板中写入真实密钥、真实个人信息或生产配置。 diff --git a/assets/templates/README.md b/assets/templates/README.md new file mode 100644 index 0000000..bfcce38 --- /dev/null +++ b/assets/templates/README.md @@ -0,0 +1,5 @@ +# assets/templates + +本目录用于存放可复用模板附件。 + +稳定知识正文放在 `docs/`，模板文件放在本目录；引用模板时应在对应文档中给出入口。 diff --git a/metadata/AGENTS.md b/metadata/AGENTS.md new file mode 100644 index 0000000..27b4ea0 --- /dev/null +++ b/metadata/AGENTS.md @@ -0,0 +1,17 @@ +# metadata/ Agent 指南 + +本目录维护机器可读索引，是 README、docs 和 AI 引用资产之间的结构桥。 + +## 约束 + +- 新增、删除、移动或重命名 docs 入口时，必须同步 `taxonomy.yml`。 +- 历史路径仍需被 AI 或外部说明理解时，维护 `redirects.yml`。 +- 术语口径变化时，同步 `glossary.yml`。 +- 不确定的映射不要猜；先查当前文件和锚点，再修改。 + +## 验证 + +```bash +make check-metadata +make test +``` diff --git a/metadata/README.md b/metadata/README.md new file mode 100644 index 0000000..07bf8a4 --- /dev/null +++ b/metadata/README.md @@ -0,0 +1,18 @@ +# metadata + +本目录存放机器可读索引，用于约束文档结构、AI 引用入口和历史路径映射。 + +## 文件 + +- `taxonomy.yml`：知识库分类、阅读路径和关键文档入口。 +- `glossary.yml`：项目术语表。 +- `redirects.yml`：历史路径到当前入口的映射，供维护和 AI 上下文使用。 + +## 使用 + +修改目录、锚点、阅读路径或关键入口后，必须同步更新本目录，并运行： + +```bash +make check-metadata +make test +``` diff --git a/scripts/AGENTS.md b/scripts/AGENTS.md new file mode 100644 index 0000000..0588efb --- /dev/null +++ b/scripts/AGENTS.md @@ -0,0 +1,16 @@ +# scripts/ Agent 指南 + +本目录维护仓库级自动化脚本，主要用于 Markdown、链接、锚点、metadata 和 AI 引用资产校验。 + +## 约束 + +- 脚本默认从仓库根目录运行，路径解析必须稳定。 +- 新增检查脚本时，同步更新 `scripts/README.md`、`Makefile`、CI 和根目录 `AGENTS.md` 的命令清单。 +- 检查失败输出应包含文件路径、行号或可定位的错误信息。 +- 跳过目录必须明确，至少跳过 `.git`、`.history`、`node_modules` 和外部源码快照。 + +## 验证 + +```bash +make test +``` diff --git a/scripts/README.md b/scripts/README.md index 6e29973..e8542c4 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -7,5 +7,6 @@ - `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-metadata.py`：`metadata/taxonomy.yml` 与 `metadata/redirects.yml` 路径和锚点检查脚本。 - `check-ai-citation.py`：`llms.txt`、`assets/ai-citation/llms-full.txt` 与 AI 引用语料路径和锚点检查脚本。 diff --git a/scripts/check-directory-docs.py b/scripts/check-directory-docs.py new file mode 100644 index 0000000..a9e4683 --- /dev/null +++ b/scripts/check-directory-docs.py @@ -0,0 +1,69 @@ +#!/usr/bin/env python3 +"""Check required repository-owned directories have README.md and AGENTS.md.""" + +from __future__ import annotations + +import sys +from pathlib import Path + + +ROOT = Path(__file__).resolve().parents[1] +REQUIRED_DIRS = [ + Path("assets"), + Path("assets/ai-citation"), + Path("assets/datasets"), + Path("assets/images"), + Path("assets/templates"), + Path("docs"), + Path("docs/concepts"), + Path("docs/getting-started"), + Path("docs/philosophy"), + Path("docs/references"), + Path("docs/research"), + Path("metadata"), + Path("prompts"), + Path("scripts"), + Path("skills"), + Path("skills/auto-skill"), + Path("tools"), + Path("tools/chat-vault"), + Path("tools/config"), + Path("tools/config/.codex"), + Path("tools/external"), + Path("tools/prompts-library"), +] +GENERATED_OR_VENDOR_DIRS = [ + Path("node_modules"), +] + + +def main() -> int: + errors: list[str] = [] + + for rel_dir in REQUIRED_DIRS: + directory = ROOT / rel_dir + if not directory.is_dir(): + errors.append(f"{rel_dir}: required directory is missing") + continue + for filename in ("README.md", "AGENTS.md"): + if not (directory / filename).is_file(): + errors.append(f"{rel_dir}/{filename}: missing required directory document") + + for rel_dir in GENERATED_OR_VENDOR_DIRS: + directory = ROOT / rel_dir + if directory.exists() and not (ROOT / ".gitignore").read_text(encoding="utf-8").count(str(rel_dir)): + errors.append(f"{rel_dir}: generated directory exists but is not ignored") + + if errors: + print("DIRECTORY_DOC_ERRORS") + for error in errors: + print(error) + print(f"TOTAL={len(errors)}") + return 1 + + print(f"OK directory README/AGENTS pairs checked: {len(REQUIRED_DIRS)} directories") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/skills/auto-skill/README.md b/skills/auto-skill/README.md new file mode 100644 index 0000000..4046f6e --- /dev/null +++ b/skills/auto-skill/README.md @@ -0,0 +1,20 @@ +# auto-skill + +`auto-skill` 是本仓库保留的 Skills 元技能，用于生成、升级、重构和校验 Claude/Codex 风格的 Skill。 + +## 入口 + +- `SKILL.md`：技能说明与执行规则。 +- `AGENTS.md`：本目录维护规则。 +- `references/`：技能设计、校验和迁移参考资料。 +- `scripts/`：技能校验与辅助脚本。 +- `assets/`：技能内部可复用资产。 + +## 使用 + +修改本技能后，至少运行： + +```bash +skills/auto-skill/scripts/validate-skill.sh skills/auto-skill --strict +make test +``` diff --git a/tools/AGENTS.md b/tools/AGENTS.md new file mode 100644 index 0000000..411cad8 --- /dev/null +++ b/tools/AGENTS.md @@ -0,0 +1,17 @@ +# tools/ Agent 指南 + +本目录维护辅助工具、外部工具入口和工具配置。 + +## 职责 + +- `tools/config/`：工具与开发环境配置基线。 +- `tools/prompts-library/`：提示词 Excel、Markdown、JSONL 转换工具。 +- `tools/chat-vault/`：AI 聊天记录保存工具。 +- `tools/external/`：第三方工具、外部仓库和 Git submodule。 + +## 约束 + +- 不把大型第三方源码直接复制进主仓库；新增外部仓库默认使用 submodule。 +- 不在工具配置中提交真实密钥、Token 或个人凭证。 +- 修改工具行为时，同步更新对应 README、AGENTS 和根目录命令说明。 +- 外部源码目录除非任务明确要求，否则不要顺手格式化或批量替换。 diff --git a/tools/config/AGENTS.md b/tools/config/AGENTS.md new file mode 100644 index 0000000..4c9d0e6 --- /dev/null +++ b/tools/config/AGENTS.md @@ -0,0 +1,15 @@ +# tools/config/ Agent 指南 + +本目录维护工具和开发环境配置基线。 + +## 约束 + +- 配置文件必须是可公开审查的模板或基线，不得包含真实密钥。 +- 本机专用配置应放在用户本地目录，不直接提交到仓库。 +- 修改 Codex 配置时，同步更新 `tools/config/.codex/README.md` 和相关 getting-started 文档。 + +## 验证 + +```bash +make test +``` diff --git a/tools/prompts-library/AGENTS.md b/tools/prompts-library/AGENTS.md new file mode 100644 index 0000000..daeae0b --- /dev/null +++ b/tools/prompts-library/AGENTS.md @@ -0,0 +1,17 @@ +# tools/prompts-library/ Agent 指南 + +本目录维护提示词格式转换工具，支持 Excel、Markdown 和 JSONL 之间的转换。 + +## 约束 + +- 修改转换逻辑前先阅读 `README.md` 和 `main.py`，不要猜输入输出格式。 +- 不提交生成目录、缓存和临时导出；`prompt_jsonl/` 为 ignored 生成物。 +- 新增依赖必须更新本目录的 `requirements.txt` 或脚本专用依赖文件。 +- 修改工具后，运行最小可用命令或说明无法运行的原因。 + +## 常用命令 + +```bash +cd tools/prompts-library +python3 main.py +```