mirror of
https://github.com/tradecatlabs/vibe-coding-cn.git
synced 2026-08-05 15:17:44 +00:00
docs: add directory governance docs
This commit is contained in:
tukuaiai
@@ -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
|
||||
|
||||
@@ -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 折叠块 `<details>/<summary>` 结构 | 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` 通过
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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` |
|
||||
|
||||
@@ -6,6 +6,7 @@
|
||||
- `assets/images/`：文档图片、截图、封面等图片资产
|
||||
- `assets/templates/`：可复用模板附件
|
||||
- `assets/datasets/`：示例数据、轻量数据集或数据说明
|
||||
- `assets/ai-citation/`：面向 AI 助手、AI 搜索与 GEO/SEO 引用的语料资产
|
||||
|
||||
其中“外部资源”类入口文档的典型形态包括：
|
||||
|
||||
|
||||
@@ -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`。
|
||||
@@ -0,0 +1,9 @@
|
||||
# assets/datasets/ Agent 指南
|
||||
|
||||
本目录只允许放轻量、可公开、可复现的数据说明或示例数据。
|
||||
|
||||
## 约束
|
||||
|
||||
- 禁止提交密钥、个人隐私、生产数据、未脱敏日志和大体积二进制数据。
|
||||
- 新增数据必须说明来源、许可证、字段含义和更新方式。
|
||||
- 大数据集只保留下载入口或生成脚本，不直接提交完整数据。
|
||||
@@ -0,0 +1,9 @@
|
||||
# assets/datasets
|
||||
|
||||
本目录用于存放示例数据、轻量数据集或数据说明。
|
||||
|
||||
当前没有必须随仓库分发的数据集。新增数据前应先确认：
|
||||
|
||||
- 是否体量足够小，适合进入 Git 仓库。
|
||||
- 是否不包含隐私、密钥、生产数据或受限许可证内容。
|
||||
- 是否有清晰来源、用途、字段说明和更新方式。
|
||||
@@ -0,0 +1,9 @@
|
||||
# assets/images/ Agent 指南
|
||||
|
||||
本目录只维护图片类静态资产。
|
||||
|
||||
## 约束
|
||||
|
||||
- 禁止提交含隐私、密钥、内部账号、未脱敏路径或敏感窗口的截图。
|
||||
- 新增图片应尽量压缩，并在引用文档中说明用途。
|
||||
- 可用文本、表格或 Mermaid 表达的内容，不优先做成图片。
|
||||
@@ -0,0 +1,5 @@
|
||||
# assets/images
|
||||
|
||||
本目录用于存放文档图片、截图、封面和其它可公开展示的图片资产。
|
||||
|
||||
图片资产应服务于 README、docs 或 AI 引用内容，不承载知识库正文。
|
||||
@@ -0,0 +1,9 @@
|
||||
# assets/templates/ Agent 指南
|
||||
|
||||
本目录维护可复用模板附件。
|
||||
|
||||
## 约束
|
||||
|
||||
- 模板必须可复制、可填写、可复用，避免一次性任务内容。
|
||||
- 模板变更影响使用方式时，需要同步更新引用它的 README 或 docs。
|
||||
- 不在模板中写入真实密钥、真实个人信息或生产配置。
|
||||
@@ -0,0 +1,5 @@
|
||||
# assets/templates
|
||||
|
||||
本目录用于存放可复用模板附件。
|
||||
|
||||
稳定知识正文放在 `docs/`，模板文件放在本目录；引用模板时应在对应文档中给出入口。
|
||||
@@ -0,0 +1,17 @@
|
||||
# metadata/ Agent 指南
|
||||
|
||||
本目录维护机器可读索引，是 README、docs 和 AI 引用资产之间的结构桥。
|
||||
|
||||
## 约束
|
||||
|
||||
- 新增、删除、移动或重命名 docs 入口时，必须同步 `taxonomy.yml`。
|
||||
- 历史路径仍需被 AI 或外部说明理解时，维护 `redirects.yml`。
|
||||
- 术语口径变化时，同步 `glossary.yml`。
|
||||
- 不确定的映射不要猜；先查当前文件和锚点，再修改。
|
||||
|
||||
## 验证
|
||||
|
||||
```bash
|
||||
make check-metadata
|
||||
make test
|
||||
```
|
||||
@@ -0,0 +1,18 @@
|
||||
# metadata
|
||||
|
||||
本目录存放机器可读索引，用于约束文档结构、AI 引用入口和历史路径映射。
|
||||
|
||||
## 文件
|
||||
|
||||
- `taxonomy.yml`：知识库分类、阅读路径和关键文档入口。
|
||||
- `glossary.yml`：项目术语表。
|
||||
- `redirects.yml`：历史路径到当前入口的映射，供维护和 AI 上下文使用。
|
||||
|
||||
## 使用
|
||||
|
||||
修改目录、锚点、阅读路径或关键入口后，必须同步更新本目录，并运行：
|
||||
|
||||
```bash
|
||||
make check-metadata
|
||||
make test
|
||||
```
|
||||
@@ -0,0 +1,16 @@
|
||||
# scripts/ Agent 指南
|
||||
|
||||
本目录维护仓库级自动化脚本，主要用于 Markdown、链接、锚点、metadata 和 AI 引用资产校验。
|
||||
|
||||
## 约束
|
||||
|
||||
- 脚本默认从仓库根目录运行，路径解析必须稳定。
|
||||
- 新增检查脚本时，同步更新 `scripts/README.md`、`Makefile`、CI 和根目录 `AGENTS.md` 的命令清单。
|
||||
- 检查失败输出应包含文件路径、行号或可定位的错误信息。
|
||||
- 跳过目录必须明确，至少跳过 `.git`、`.history`、`node_modules` 和外部源码快照。
|
||||
|
||||
## 验证
|
||||
|
||||
```bash
|
||||
make test
|
||||
```
|
||||
@@ -7,5 +7,6 @@
|
||||
- `check-local-links.py`：仓库内 Markdown 相对链接与锚点检查脚本。
|
||||
- `check-markdown-details.py`：仓库内 Markdown `<details>/<summary>` 折叠块结构检查脚本。
|
||||
- `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 引用语料路径和锚点检查脚本。
|
||||
|
||||
@@ -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())
|
||||
@@ -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
|
||||
```
|
||||
@@ -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 和根目录命令说明。
|
||||
- 外部源码目录除非任务明确要求，否则不要顺手格式化或批量替换。
|
||||
@@ -0,0 +1,15 @@
|
||||
# tools/config/ Agent 指南
|
||||
|
||||
本目录维护工具和开发环境配置基线。
|
||||
|
||||
## 约束
|
||||
|
||||
- 配置文件必须是可公开审查的模板或基线，不得包含真实密钥。
|
||||
- 本机专用配置应放在用户本地目录，不直接提交到仓库。
|
||||
- 修改 Codex 配置时，同步更新 `tools/config/.codex/README.md` 和相关 getting-started 文档。
|
||||
|
||||
## 验证
|
||||
|
||||
```bash
|
||||
make test
|
||||
```
|
||||
@@ -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
|
||||
```
|
||||
Reference in New Issue
Block a user