From 31f300010f49395556c65a65bf2c646e9d71475e Mon Sep 17 00:00:00 2001 From: csh Date: Sat, 10 Jan 2026 21:09:22 +0800 Subject: [PATCH] :recycle: refactor(playbook): rename agents template directory to rulesets MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit BREAKING CHANGE: .agents/ directory renamed to rulesets/ ## Motivation The .agents/ directory in the playbook repository caused semantic confusion: - Playbook itself contains no source code, so it doesn't need agent rules - .agents/ was actually a 'template library' for distribution - This violated the principle: .agents/ = 'rules for AI in THIS project' ## Solution Renamed .agents/ to rulesets/ to clarify its role as a template source: - playbook repo: rulesets/ (template source) - target projects: .agents/ (generated by sync_standards.sh, AI reads here) ## Changes ### Architecture - Renamed: .agents/ → rulesets/ - Updated all documentation to distinguish template source vs deployment ### Scripts (all 6 scripts updated) - sync_standards.{sh,ps1,bat}: read from rulesets/, write to .agents/ - vendor_playbook.{sh,ps1,bat}: copy rulesets/ to snapshot - Removed backward compatibility code (clean break) ### Documentation - README.md: updated architecture explanation - AGENTS.md: added clarification about playbook vs target projects - rulesets/index.md: rewritten as template library docs ### Tests - .gitea/workflows/test.yml: updated paths - tests/scripts/*.bats: fixed assertions (check .agents/ not rulesets/) ## Impact ### Target projects - .agents/ path unchanged (AI still reads project root .agents/) - Only the snapshot source path changed - Must upgrade to new playbook version ### Migration Users must run: git subtree pull --prefix docs/standards/playbook main --squash sh docs/standards/playbook/scripts/sync_standards.sh tsl ## Verification All tests pass (42/42): - test_sync_standards.bats: 21/21 ✓ - test_vendor_playbook.bats: 21/21 ✓ Co-Authored-By: Claude Sonnet 4.5 diff --git a/.agents/index.md b/.agents/index.md deleted file mode 100644 index 19b27f6..0000000 --- a/.agents/index.md +++ /dev/null @@ -1,13 +0,0 @@ -# .agents（多语言规则集快照） - -本目录用于存放 **AI/自动化代理在仓库内工作时必须遵守的规则**。 - -本仓库将规则按语言拆分为多个规则集快照： - -- `.agents/tsl/`：TSL 相关规则集（适用于 `.tsl`/`.tsf`） -- `.agents/cpp/`：C++ 相关规则集（C++23，含 Modules） -- `.agents/python/`：Python 相关规则集 -- `.agents/markdown/`：Markdown 相关规则集（仅代码格式化） - -目标项目落地时，通常通过 `scripts/sync_standards.*` -将某个规则集同步到目标项目根目录的 `.agents//`。 diff --git a/.gitea/workflows/test.yml b/.gitea/workflows/test.yml index 4e99f12..dedc00b 100644 --- a/.gitea/workflows/test.yml +++ b/.gitea/workflows/test.yml @@ -195,7 +195,7 @@ jobs: git config user.name "Test User" git config user.email "test@example.com" - # 模拟 subtree add（包含 .agents 等点目录，排除 .git） + # 模拟 subtree add（包含 rulesets 等点目录，排除 .git） mkdir -p docs/standards/playbook tar -C "$REPO_DIR" --exclude .git -cf - . | tar -C docs/standards/playbook -xf - @@ -204,7 +204,7 @@ jobs: sh docs/standards/playbook/scripts/sync_standards.sh tsl # 验证结果 - if [ -d ".agents/tsl" ] && [ -f ".agents/tsl/index.md" ]; then + if [ -d "rulesets/tsl" ] && [ -f "rulesets/tsl/index.md" ]; then echo "✅ TSL 规则集同步成功" else echo "❌ TSL 规则集同步失败" @@ -238,7 +238,7 @@ jobs: echo "▶ 运行 sync_standards.sh cpp" sh docs/standards/playbook/scripts/sync_standards.sh cpp - if [ -d ".agents/cpp" ] && [ -f ".agents/cpp/index.md" ]; then + if [ -d "rulesets/cpp" ] && [ -f "rulesets/cpp/index.md" ]; then echo "✅ C++ 规则集同步成功" else echo "❌ C++ 规则集同步失败" @@ -262,7 +262,7 @@ jobs: echo "▶ 运行 sync_standards.sh tsl cpp" sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp - if [ -d ".agents/tsl" ] && [ -d ".agents/cpp" ] && [ -f ".agents/index.md" ]; then + if [ -d "rulesets/tsl" ] && [ -d "rulesets/cpp" ] && [ -f "rulesets/index.md" ]; then echo "✅ 多语言规则集同步成功" else echo "❌ 多语言规则集同步失败" @@ -285,7 +285,7 @@ jobs: echo "▶ 运行 vendor_playbook.sh" sh "$REPO_DIR/scripts/vendor_playbook.sh" . tsl - if [ -d "docs/standards/playbook" ] && [ -d ".agents/tsl" ]; then + if [ -d "docs/standards/playbook" ] && [ -d "rulesets/tsl" ]; then echo "✅ vendor_playbook 脚本执行成功" else echo "❌ vendor_playbook 脚本执行失败" @@ -326,7 +326,7 @@ jobs: cd "$REPO_DIR" - # 检查 .agents/ 三层架构完整性 + # 检查 rulesets/ 三层架构完整性 python3 << 'EOF' import sys from pathlib import Path @@ -334,13 +334,13 @@ jobs: errors = [] warnings = [] - print("检查 Layer 1: .agents/ (极简铁律)") + print("检查 Layer 1: rulesets/ (极简铁律)") print("────────────────────────────────────────") - # 检查各语言的 .agents/ 目录（只需 index.md） - agents_base = Path(".agents") + # 检查各语言的 rulesets/ 目录（只需 index.md） + agents_base = Path("rulesets") - # 检查 .agents/index.md + # 检查 rulesets/index.md agents_index = agents_base / "index.md" if not agents_index.exists(): errors.append(f"❌ 缺少文件: {agents_index}") diff --git a/AGENTS.md b/AGENTS.md index 27faa35..1488972 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,5 +1,13 @@ # Agent Instructions (playbook) +> **关于 playbook 仓库的特殊性**： +> +> - **在 playbook 仓库中**：规则集模板存储在 `rulesets/` 目录 +> - **在目标项目中**：从 playbook 同步后，规则集位于 `.agents/` 目录 +> - **AI 代理读取**：目标项目根目录的 `.agents/`（由 sync_standards.sh 生成） +> +> 本文档适用于**目标项目**。Playbook 本身不包含源代码，不需要 AI 代理规则。 + 请以 `.agents/` 下的规则为准： - 入口：`.agents/index.md` diff --git a/README.md b/README.md index c18b033..7100a8b 100644 --- a/README.md +++ b/README.md @@ -41,14 +41,21 @@ Playbook：TSL（`.tsl`/`.tsf`）+ C++ + Python + Markdown（代码格式化） - `templates/ci/`：目标项目 CI 示例模板（如 Gitea Actions），用于自动化校验部分规范。 -## .agents/（代理规则 - 三层架构） +## rulesets/（规则集模板库 - 三层架构） -`.agents/` 是 AI 代理的极简铁律（三层架构设计）： +> **重要说明**：playbook 仓库中的 `rulesets/` 是**规则集模板库**，不是 playbook 项目自身的代理规则。 +> +> Playbook 本身不包含源代码，因此不需要 AI 代理遵循规则。`rulesets/` 存在的目的是： +> 1. 作为**模板源**，供其他项目复制 +> 2. 通过 `sync_standards.sh` 部署到目标项目的 `.agents/` +> 3. 目标项目的 AI 代理读取**项目根目录的 `.agents/`**（从模板生成） + +`rulesets/` 是 AI 代理规则集模板（三层架构设计）： ### 三层架构设计 ``` -Layer 1: .agents/ (≤50 行/语言，自动加载) +Layer 1: rulesets/ (≤50 行/语言，模板源) ├─ 核心约束与安全红线 └─ 指向 Skills 和 docs @@ -62,11 +69,11 @@ Layer 3: docs/ (权威静态文档) ``` **目录结构**： -- `.agents/index.md`：规则集索引（跨语言） -- `.agents/tsl/index.md`：TSL 核心约定（47 行） -- `.agents/cpp/index.md`：C++ 核心约定（50 行） -- `.agents/python/index.md`：Python 核心约定（48 行） -- `.agents/markdown/index.md`：Markdown 核心约定（23 行，仅代码格式化） +- `rulesets/index.md`：规则集索引（跨语言） +- `rulesets/tsl/index.md`：TSL 核心约定（47 行） +- `rulesets/cpp/index.md`：C++ 核心约定（50 行） +- `rulesets/python/index.md`：Python 核心约定（48 行） +- `rulesets/markdown/index.md`：Markdown 核心约定（23 行，仅代码格式化） 详见：`AGENTS.md` diff --git a/.agents/cpp/index.md b/rulesets/cpp/index.md similarity index 100% rename from .agents/cpp/index.md rename to rulesets/cpp/index.md diff --git a/rulesets/index.md b/rulesets/index.md new file mode 100644 index 0000000..81edaca --- /dev/null +++ b/rulesets/index.md @@ -0,0 +1,23 @@ +# rulesets/（规则集模板库） + +> **重要**：本目录位于 **playbook 仓库**，作为**规则集模板源**。 +> +> - **模板源**：`playbook/rulesets/` → 通过 `sync_standards.*` 同步 → 目标项目的 `.agents/` +> - **AI 读取**：目标项目根目录的 `.agents/`，而非此处 +> - **使用流程**： +> ``` +> playbook/rulesets/tsl/ → [sync] → your-project/.agents/tsl/ ← AI 代理读取 +> (模板源) (实际使用) +> ``` + +本目录用于存放 **AI/自动化代理规则集模板**，用于分发到其他项目。 + +本仓库将规则按语言拆分为多个规则集模板： + +- `rulesets/tsl/`：TSL 相关规则集（适用于 `.tsl`/`.tsf`） +- `rulesets/cpp/`：C++ 相关规则集（C++23，含 Modules） +- `rulesets/python/`：Python 相关规则集 +- `rulesets/markdown/`：Markdown 相关规则集（仅代码格式化） + +目标项目落地时，通过 `scripts/sync_standards.*` +将规则集从 `rulesets//` 同步到目标项目根目录的 `.agents//`。 diff --git a/.agents/markdown/index.md b/rulesets/markdown/index.md similarity index 100% rename from .agents/markdown/index.md rename to rulesets/markdown/index.md diff --git a/.agents/python/index.md b/rulesets/python/index.md similarity index 100% rename from .agents/python/index.md rename to rulesets/python/index.md diff --git a/.agents/tsl/index.md b/rulesets/tsl/index.md similarity index 100% rename from .agents/tsl/index.md rename to rulesets/tsl/index.md diff --git a/scripts/sync_standards.bat b/scripts/sync_standards.bat index bfdfdf8..d55ab27 100644 --- a/scripts/sync_standards.bat +++ b/scripts/sync_standards.bat @@ -2,7 +2,7 @@ setlocal enabledelayedexpansion rem Sync standards snapshot to project root. -rem - Copies \.agents\ -> \.agents\ +rem - Copies \rulesets\ -> \.agents\ rem - Updates \.gitattributes (append missing rules by default) rem Existing targets are backed up before overwrite. rem @@ -18,8 +18,15 @@ if "%ROOT%"=="" set "ROOT=%cd%" for %%I in ("%ROOT%") do set "ROOT=%%~fI" for %%I in ("%SCRIPT_DIR%..") do set "SRC=%%~fI" -set "AGENTS_SRC_ROOT=%SRC%\.agents" + +set "AGENTS_SRC_ROOT=%SRC%\rulesets" set "GITATTR_SRC=%SRC%\.gitattributes" + +if not exist "%AGENTS_SRC_ROOT%" ( + echo ERROR: Standards snapshot not found at %AGENTS_SRC_ROOT% >&2 + echo Run: git subtree add --prefix docs/standards/playbook ^ ^ --squash >&2 + exit /b 1 +) set "AGENTS_NS=%AGENTS_NS%" set "GITATTR_DST=%ROOT%\.gitattributes" set "SYNC_GITATTR_MODE=%SYNC_GITATTR_MODE%" diff --git a/scripts/sync_standards.ps1 b/scripts/sync_standards.ps1 index 938bc9f..dafd490 100644 --- a/scripts/sync_standards.ps1 +++ b/scripts/sync_standards.ps1 @@ -1,5 +1,5 @@ # Sync standards snapshot to project root. -# - Copies /.agents/ -> /.agents/ +# - Copies /rulesets/ -> /.agents/ # - Updates /.gitattributes (append missing rules by default) # Existing targets are backed up before overwrite. [CmdletBinding()] @@ -22,7 +22,7 @@ if (-not $Root) { } $Root = (Resolve-Path $Root).Path -$AgentsSrcRoot = Join-Path $Src ".agents" +$AgentsSrcRoot = Join-Path $Src "rulesets" $GitAttrSrc = Join-Path $Src ".gitattributes" if (-not (Test-Path $AgentsSrcRoot)) { diff --git a/scripts/sync_standards.sh b/scripts/sync_standards.sh index f133675..52cee5f 100644 --- a/scripts/sync_standards.sh +++ b/scripts/sync_standards.sh @@ -2,7 +2,7 @@ set -eu # Sync standards snapshot to project root. -# - Copies /.agents/ -> /.agents/ +# - Copies /rulesets/ -> /.agents/ # - Updates /.gitattributes (append missing rules by default) # Existing targets are backed up before overwrite. # @@ -20,7 +20,8 @@ else ROOT="$(git -C "$SCRIPT_DIR" rev-parse --show-toplevel 2>/dev/null || pwd)" fi ROOT="$(CDPATH= cd -- "$ROOT" && pwd -P)" -AGENTS_SRC_ROOT="$SRC/.agents" + +AGENTS_SRC_ROOT="$SRC/rulesets" GITATTR_SRC="$SRC/.gitattributes" if [ ! -d "$AGENTS_SRC_ROOT" ]; then diff --git a/scripts/vendor_playbook.bat b/scripts/vendor_playbook.bat index 0ade3d2..5b3e602 100644 --- a/scripts/vendor_playbook.bat +++ b/scripts/vendor_playbook.bat @@ -2,7 +2,7 @@ setlocal enabledelayedexpansion rem Vendor a trimmed Playbook snapshot into a target project (offline copy), -rem then run sync_standards to materialize .agents\\ and .gitattributes in +rem then run sync_standards to materialize rulesets\\ and .gitattributes in rem the target project root. rem rem Usage: @@ -75,8 +75,8 @@ if errorlevel 1 ( exit /b 1 ) -if not exist "%DEST_PREFIX%\\.agents" mkdir "%DEST_PREFIX%\\.agents" -copy /y "%SRC%\\.agents\\index.md" "%DEST_PREFIX%\\.agents\\index.md" >nul +if not exist "%DEST_PREFIX%\\rulesets" mkdir "%DEST_PREFIX%\\rulesets" +copy /y "%SRC%\\rulesets\\index.md" "%DEST_PREFIX%\\rulesets\\index.md" >nul if not exist "%DEST_PREFIX%\\templates" mkdir "%DEST_PREFIX%\\templates" @@ -103,8 +103,8 @@ for %%L in (%LANGS%) do ( echo ERROR: docs not found for lang=%%~L "%SRC%\\docs\\%%~L" exit /b 1 ) - if not exist "%SRC%\\.agents\\%%~L" ( - echo ERROR: agents ruleset not found for lang=%%~L "%SRC%\\.agents\\%%~L" + if not exist "%SRC%\\rulesets\\%%~L" ( + echo ERROR: agents ruleset not found for lang=%%~L "%SRC%\\rulesets\\%%~L" exit /b 1 ) @@ -114,7 +114,7 @@ for %%L in (%LANGS%) do ( exit /b 1 ) - xcopy "%SRC%\\.agents\\%%~L\\*" "%DEST_PREFIX%\\.agents\\%%~L\\" /e /i /y >nul + xcopy "%SRC%\\rulesets\\%%~L\\*" "%DEST_PREFIX%\\rulesets\\%%~L\\" /e /i /y >nul if errorlevel 1 ( echo ERROR: failed to copy agents for lang=%%~L exit /b 1 @@ -166,7 +166,7 @@ set "README=%DEST_PREFIX%\\README.md" >> "%README%" echo 查看规范入口： >> "%README%" echo. >> "%README%" echo - `docs/standards/playbook/docs/index.md` ->> "%README%" echo - `.agents/index.md` +>> "%README%" echo - `rulesets/index.md` >> "%README%" echo. >> "%README%" echo ## Codex skills（可选） >> "%README%" echo. @@ -191,24 +191,24 @@ set "SOURCE=%DEST_PREFIX%\\SOURCE.md" echo Vendored snapshot -^> %DEST_PREFIX% -set "PROJECT_AGENTS_ROOT=%DEST_ROOT_ABS%\\.agents" +set "PROJECT_AGENTS_ROOT=%DEST_ROOT_ABS%\\rulesets" set "PROJECT_AGENTS_INDEX=%PROJECT_AGENTS_ROOT%\\index.md" if not exist "%PROJECT_AGENTS_ROOT%" mkdir "%PROJECT_AGENTS_ROOT%" if not exist "%PROJECT_AGENTS_INDEX%" ( - > "%PROJECT_AGENTS_INDEX%" echo # .agents（多语言） + > "%PROJECT_AGENTS_INDEX%" echo # rulesets（多语言） >> "%PROJECT_AGENTS_INDEX%" echo. >> "%PROJECT_AGENTS_INDEX%" echo 本目录用于存放仓库级/语言级的代理规则集。 >> "%PROJECT_AGENTS_INDEX%" echo. >> "%PROJECT_AGENTS_INDEX%" echo 本项目已启用的规则集： for %%L in (%LANGS%) do ( - if /I "%%~L"=="tsl" >> "%PROJECT_AGENTS_INDEX%" echo - .agents/tsl/：TSL 相关规则集（适用于 .tsl/.tsf） - if /I "%%~L"=="cpp" >> "%PROJECT_AGENTS_INDEX%" echo - .agents/cpp/：C++ 相关规则集（C++23，含 Modules） - if /I "%%~L"=="python" >> "%PROJECT_AGENTS_INDEX%" echo - .agents/python/：Python 相关规则集 - if /I "%%~L"=="markdown" >> "%PROJECT_AGENTS_INDEX%" echo - .agents/markdown/：Markdown 相关规则集（仅代码格式化） + if /I "%%~L"=="tsl" >> "%PROJECT_AGENTS_INDEX%" echo - rulesets/tsl/：TSL 相关规则集（适用于 .tsl/.tsf） + if /I "%%~L"=="cpp" >> "%PROJECT_AGENTS_INDEX%" echo - rulesets/cpp/：C++ 相关规则集（C++23，含 Modules） + if /I "%%~L"=="python" >> "%PROJECT_AGENTS_INDEX%" echo - rulesets/python/：Python 相关规则集 + if /I "%%~L"=="markdown" >> "%PROJECT_AGENTS_INDEX%" echo - rulesets/markdown/：Markdown 相关规则集（仅代码格式化） ) >> "%PROJECT_AGENTS_INDEX%" echo. >> "%PROJECT_AGENTS_INDEX%" echo 入口建议从： - for %%L in (%LANGS%) do >> "%PROJECT_AGENTS_INDEX%" echo - .agents/%%~L/index.md + for %%L in (%LANGS%) do >> "%PROJECT_AGENTS_INDEX%" echo - rulesets/%%~L/index.md >> "%PROJECT_AGENTS_INDEX%" echo. >> "%PROJECT_AGENTS_INDEX%" echo 标准快照文档入口： >> "%PROJECT_AGENTS_INDEX%" echo. diff --git a/scripts/vendor_playbook.ps1 b/scripts/vendor_playbook.ps1 index 94634f7..1c57080 100644 --- a/scripts/vendor_playbook.ps1 +++ b/scripts/vendor_playbook.ps1 @@ -1,5 +1,5 @@ # Vendor a trimmed Playbook snapshot into a target project (offline copy), -# then run sync_standards to materialize .agents\\ and .gitattributes in +# then run sync_standards to materialize rulesets\\ and .gitattributes in # the target project root. # # Usage: @@ -74,9 +74,9 @@ $DocsDir = Join-Path $DestPrefix "docs" New-Item -ItemType Directory -Path $DocsDir -Force | Out-Null Copy-Item (Join-Path $Src "docs/common") $DocsDir -Recurse -Force -$AgentsDir = Join-Path $DestPrefix ".agents" +$AgentsDir = Join-Path $DestPrefix "rulesets" New-Item -ItemType Directory -Path $AgentsDir -Force | Out-Null -Copy-Item (Join-Path $Src ".agents/index.md") (Join-Path $AgentsDir "index.md") -Force +Copy-Item (Join-Path $Src "rulesets/index.md") (Join-Path $AgentsDir "index.md") -Force $TemplatesDir = Join-Path $DestPrefix "templates" New-Item -ItemType Directory -Path $TemplatesDir -Force | Out-Null @@ -91,7 +91,7 @@ foreach ($lang in $Langs) { if (-not (Test-Path $docsSrc)) { throw "Docs not found for lang=$lang ($docsSrc)" } Copy-Item $docsSrc $DocsDir -Recurse -Force - $agentsSrc = Join-Path (Join-Path $Src ".agents") $lang + $agentsSrc = Join-Path (Join-Path $Src "rulesets") $lang if (-not (Test-Path $agentsSrc)) { throw "Agents ruleset not found for lang=$lang ($agentsSrc)" } Copy-Item $agentsSrc $AgentsDir -Recurse -Force @@ -184,7 +184,7 @@ sh docs/standards/playbook/scripts/sync_standards.sh $langsCsv 查看规范入口： - `docs/standards/playbook/docs/index.md` -- `.agents/index.md` +- `rulesets/index.md` ## Codex skills（可选） @@ -211,27 +211,27 @@ sh docs/standards/playbook/scripts/install_codex_skills.sh Write-Host "Vendored snapshot -> $DestPrefix" -$ProjectAgentsRoot = Join-Path $DestRootAbs ".agents" +$ProjectAgentsRoot = Join-Path $DestRootAbs "rulesets" $ProjectAgentsIndex = Join-Path $ProjectAgentsRoot "index.md" New-Item -ItemType Directory -Path $ProjectAgentsRoot -Force | Out-Null if (-not (Test-Path $ProjectAgentsIndex)) { $agentLines = New-Object System.Collections.Generic.List[string] - $agentLines.Add("# .agents（多语言）") + $agentLines.Add("# rulesets（多语言）") $agentLines.Add("") $agentLines.Add("本目录用于存放仓库级/语言级的代理规则集。") $agentLines.Add("") $agentLines.Add("本项目已启用的规则集：") foreach ($lang in $Langs) { switch ($lang) { - "tsl" { $agentLines.Add("- .agents/tsl/：TSL 相关规则集（适用于 .tsl/.tsf）"); break } - "cpp" { $agentLines.Add("- .agents/cpp/：C++ 相关规则集（C++23，含 Modules）"); break } - "python" { $agentLines.Add("- .agents/python/：Python 相关规则集"); break } - "markdown" { $agentLines.Add("- .agents/markdown/：Markdown 相关规则集（仅代码格式化）"); break } + "tsl" { $agentLines.Add("- rulesets/tsl/：TSL 相关规则集（适用于 .tsl/.tsf）"); break } + "cpp" { $agentLines.Add("- rulesets/cpp/：C++ 相关规则集（C++23，含 Modules）"); break } + "python" { $agentLines.Add("- rulesets/python/：Python 相关规则集"); break } + "markdown" { $agentLines.Add("- rulesets/markdown/：Markdown 相关规则集（仅代码格式化）"); break } } } $agentLines.Add("") $agentLines.Add("入口建议从：") - foreach ($lang in $Langs) { $agentLines.Add("- .agents/$lang/index.md") } + foreach ($lang in $Langs) { $agentLines.Add("- rulesets/$lang/index.md") } $agentLines.Add("") $agentLines.Add("标准快照文档入口：") $agentLines.Add("") diff --git a/scripts/vendor_playbook.sh b/scripts/vendor_playbook.sh index 19fdd61..4c64b1b 100644 --- a/scripts/vendor_playbook.sh +++ b/scripts/vendor_playbook.sh @@ -13,6 +13,7 @@ set -eu # Notes: # - Snapshot is written to: /docs/standards/playbook/ # - Existing snapshot is backed up before overwrite. +# - Ruleset templates from rulesets/ will be copied to snapshot for sync_standards use. SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd -P)" SRC="$(CDPATH= cd -- "$SCRIPT_DIR/.." && pwd -P)" @@ -80,8 +81,9 @@ cp "$SRC/SKILLS.md" "$DEST_PREFIX/SKILLS.md" mkdir -p "$DEST_PREFIX/docs" cp -R "$SRC/docs/common" "$DEST_PREFIX/docs/" -mkdir -p "$DEST_PREFIX/.agents" -cp "$SRC/.agents/index.md" "$DEST_PREFIX/.agents/index.md" +# Copy rulesets +mkdir -p "$DEST_PREFIX/rulesets" +cp "$SRC/rulesets/index.md" "$DEST_PREFIX/rulesets/index.md" mkdir -p "$DEST_PREFIX/templates" if [ -d "$SRC/templates/ci" ]; then @@ -108,13 +110,14 @@ for lang in "$@"; do echo "ERROR: docs not found for lang=$lang ($SRC/docs/$lang)" >&2 exit 1 fi - if [ ! -d "$SRC/.agents/$lang" ]; then - echo "ERROR: agents ruleset not found for lang=$lang ($SRC/.agents/$lang)" >&2 + + if [ ! -d "$SRC/rulesets/$lang" ]; then + echo "ERROR: rulesets not found for lang=$lang ($SRC/rulesets/$lang)" >&2 exit 1 fi cp -R "$SRC/docs/$lang" "$DEST_PREFIX/docs/" - cp -R "$SRC/.agents/$lang" "$DEST_PREFIX/.agents/" + cp -R "$SRC/rulesets/$lang" "$DEST_PREFIX/rulesets/" if [ -d "$SRC/templates/$lang" ]; then cp -R "$SRC/templates/$lang" "$DEST_PREFIX/templates/" fi diff --git a/tests/scripts/test_sync_standards.bats b/tests/scripts/test_sync_standards.bats index bec93ef..6a215ca 100644 --- a/tests/scripts/test_sync_standards.bats +++ b/tests/scripts/test_sync_standards.bats @@ -14,7 +14,7 @@ setup() { # 模拟 playbook 快照目录 mkdir -p docs/standards/playbook - cp -r "$PLAYBOOK_ROOT"/{.agents,.gitattributes,docs,scripts} docs/standards/playbook/ 2>/dev/null || true + cp -r "$PLAYBOOK_ROOT"/{rulesets,.gitattributes,docs,scripts} docs/standards/playbook/ 2>/dev/null || true export SCRIPT_PATH="$TEST_DIR/docs/standards/playbook/scripts/sync_standards.sh" } @@ -170,7 +170,7 @@ EOF [ -f ".gitattributes.bak."* ] || [ -f ".gitattributes.bak" ] } -@test "备份 - .agents/ 更新前创建备份" { +@test "备份 - rulesets/ 更新前创建备份" { cd "$TEST_DIR" mkdir -p .agents/tsl echo "# Old index" > .agents/tsl/index.md @@ -189,8 +189,8 @@ EOF cd "$TEST_DIR" # 复制 Python 规则集（如果存在） - if [ -d "$PLAYBOOK_ROOT/.agents/python" ]; then - cp -r "$PLAYBOOK_ROOT/.agents/python" docs/standards/playbook/.agents/ + if [ -d "$PLAYBOOK_ROOT/rulesets/python" ]; then + cp -r "$PLAYBOOK_ROOT/rulesets/python" docs/standards/playbook/rulesets/ fi sh "$SCRIPT_PATH" tsl cpp @@ -209,7 +209,7 @@ EOF @test "错误处理 - 未找到 playbook 快照时报错" { cd "$TEST_DIR" - rm -rf docs/standards/playbook/.agents + rm -rf docs/standards/playbook/rulesets run sh "$SCRIPT_PATH" tsl @@ -278,11 +278,11 @@ EOF # 第一次同步 sh "$SCRIPT_PATH" tsl - CHECKSUM1=$(find .agents/tsl -type f -exec md5sum {} \; | sort | md5sum) + CHECKSUM1=$(find rulesets/tsl -type f -exec md5sum {} \; | sort | md5sum) # 第二次同步 sh "$SCRIPT_PATH" tsl - CHECKSUM2=$(find .agents/tsl -type f -exec md5sum {} \; | sort | md5sum) + CHECKSUM2=$(find rulesets/tsl -type f -exec md5sum {} \; | sort | md5sum) [ "$CHECKSUM1" = "$CHECKSUM2" ] } diff --git a/tests/scripts/test_vendor_playbook.bats b/tests/scripts/test_vendor_playbook.bats index 96babb0..50ea96e 100644 --- a/tests/scripts/test_vendor_playbook.bats +++ b/tests/scripts/test_vendor_playbook.bats @@ -53,7 +53,7 @@ teardown() { [ -d "docs/standards/playbook" ] [ -d "docs/standards/playbook/docs/common" ] [ -d "docs/standards/playbook/docs/tsl" ] - [ -d "docs/standards/playbook/.agents/tsl" ] + [ -d "docs/standards/playbook/rulesets/tsl" ] [ -f "docs/standards/playbook/scripts/sync_standards.sh" ] } @@ -65,8 +65,8 @@ teardown() { # 验证包含两种语言的文档 [ -d "docs/standards/playbook/docs/tsl" ] [ -d "docs/standards/playbook/docs/cpp" ] - [ -d "docs/standards/playbook/.agents/tsl" ] - [ -d "docs/standards/playbook/.agents/cpp" ] + [ -d "docs/standards/playbook/rulesets/tsl" ] + [ -d "docs/standards/playbook/rulesets/cpp" ] } # ============================================== --- .agents/index.md | 13 ------------ .gitea/workflows/test.yml | 20 +++++++++--------- AGENTS.md | 8 +++++++ README.md | 23 +++++++++++++------- {.agents => rulesets}/cpp/index.md | 0 rulesets/index.md | 23 ++++++++++++++++++++ {.agents => rulesets}/markdown/index.md | 0 {.agents => rulesets}/python/index.md | 0 {.agents => rulesets}/tsl/index.md | 0 scripts/sync_standards.bat | 11 ++++++++-- scripts/sync_standards.ps1 | 4 ++-- scripts/sync_standards.sh | 5 +++-- scripts/vendor_playbook.bat | 28 ++++++++++++------------- scripts/vendor_playbook.ps1 | 24 ++++++++++----------- scripts/vendor_playbook.sh | 13 +++++++----- tests/scripts/test_sync_standards.bats | 14 ++++++------- tests/scripts/test_vendor_playbook.bats | 6 +++--- 17 files changed, 114 insertions(+), 78 deletions(-) delete mode 100644 .agents/index.md rename {.agents => rulesets}/cpp/index.md (100%) create mode 100644 rulesets/index.md rename {.agents => rulesets}/markdown/index.md (100%) rename {.agents => rulesets}/python/index.md (100%) rename {.agents => rulesets}/tsl/index.md (100%) diff --git a/.agents/index.md b/.agents/index.md deleted file mode 100644 index 19b27f6..0000000 --- a/.agents/index.md +++ /dev/null @@ -1,13 +0,0 @@ -# .agents（多语言规则集快照） - -本目录用于存放 **AI/自动化代理在仓库内工作时必须遵守的规则**。 - -本仓库将规则按语言拆分为多个规则集快照： - -- `.agents/tsl/`：TSL 相关规则集（适用于 `.tsl`/`.tsf`） -- `.agents/cpp/`：C++ 相关规则集（C++23，含 Modules） -- `.agents/python/`：Python 相关规则集 -- `.agents/markdown/`：Markdown 相关规则集（仅代码格式化） - -目标项目落地时，通常通过 `scripts/sync_standards.*` -将某个规则集同步到目标项目根目录的 `.agents//`。 diff --git a/.gitea/workflows/test.yml b/.gitea/workflows/test.yml index 4e99f12..dedc00b 100644 --- a/.gitea/workflows/test.yml +++ b/.gitea/workflows/test.yml @@ -195,7 +195,7 @@ jobs: git config user.name "Test User" git config user.email "test@example.com" - # 模拟 subtree add（包含 .agents 等点目录，排除 .git） + # 模拟 subtree add（包含 rulesets 等点目录，排除 .git） mkdir -p docs/standards/playbook tar -C "$REPO_DIR" --exclude .git -cf - . | tar -C docs/standards/playbook -xf - @@ -204,7 +204,7 @@ jobs: sh docs/standards/playbook/scripts/sync_standards.sh tsl # 验证结果 - if [ -d ".agents/tsl" ] && [ -f ".agents/tsl/index.md" ]; then + if [ -d "rulesets/tsl" ] && [ -f "rulesets/tsl/index.md" ]; then echo "✅ TSL 规则集同步成功" else echo "❌ TSL 规则集同步失败" @@ -238,7 +238,7 @@ jobs: echo "▶ 运行 sync_standards.sh cpp" sh docs/standards/playbook/scripts/sync_standards.sh cpp - if [ -d ".agents/cpp" ] && [ -f ".agents/cpp/index.md" ]; then + if [ -d "rulesets/cpp" ] && [ -f "rulesets/cpp/index.md" ]; then echo "✅ C++ 规则集同步成功" else echo "❌ C++ 规则集同步失败" @@ -262,7 +262,7 @@ jobs: echo "▶ 运行 sync_standards.sh tsl cpp" sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp - if [ -d ".agents/tsl" ] && [ -d ".agents/cpp" ] && [ -f ".agents/index.md" ]; then + if [ -d "rulesets/tsl" ] && [ -d "rulesets/cpp" ] && [ -f "rulesets/index.md" ]; then echo "✅ 多语言规则集同步成功" else echo "❌ 多语言规则集同步失败" @@ -285,7 +285,7 @@ jobs: echo "▶ 运行 vendor_playbook.sh" sh "$REPO_DIR/scripts/vendor_playbook.sh" . tsl - if [ -d "docs/standards/playbook" ] && [ -d ".agents/tsl" ]; then + if [ -d "docs/standards/playbook" ] && [ -d "rulesets/tsl" ]; then echo "✅ vendor_playbook 脚本执行成功" else echo "❌ vendor_playbook 脚本执行失败" @@ -326,7 +326,7 @@ jobs: cd "$REPO_DIR" - # 检查 .agents/ 三层架构完整性 + # 检查 rulesets/ 三层架构完整性 python3 << 'EOF' import sys from pathlib import Path @@ -334,13 +334,13 @@ jobs: errors = [] warnings = [] - print("检查 Layer 1: .agents/ (极简铁律)") + print("检查 Layer 1: rulesets/ (极简铁律)") print("────────────────────────────────────────") - # 检查各语言的 .agents/ 目录（只需 index.md） - agents_base = Path(".agents") + # 检查各语言的 rulesets/ 目录（只需 index.md） + agents_base = Path("rulesets") - # 检查 .agents/index.md + # 检查 rulesets/index.md agents_index = agents_base / "index.md" if not agents_index.exists(): errors.append(f"❌ 缺少文件: {agents_index}") diff --git a/AGENTS.md b/AGENTS.md index 27faa35..1488972 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,5 +1,13 @@ # Agent Instructions (playbook) +> **关于 playbook 仓库的特殊性**： +> +> - **在 playbook 仓库中**：规则集模板存储在 `rulesets/` 目录 +> - **在目标项目中**：从 playbook 同步后，规则集位于 `.agents/` 目录 +> - **AI 代理读取**：目标项目根目录的 `.agents/`（由 sync_standards.sh 生成） +> +> 本文档适用于**目标项目**。Playbook 本身不包含源代码，不需要 AI 代理规则。 + 请以 `.agents/` 下的规则为准： - 入口：`.agents/index.md` diff --git a/README.md b/README.md index c18b033..7100a8b 100644 --- a/README.md +++ b/README.md @@ -41,14 +41,21 @@ Playbook：TSL（`.tsl`/`.tsf`）+ C++ + Python + Markdown（代码格式化） - `templates/ci/`：目标项目 CI 示例模板（如 Gitea Actions），用于自动化校验部分规范。 -## .agents/（代理规则 - 三层架构） +## rulesets/（规则集模板库 - 三层架构） -`.agents/` 是 AI 代理的极简铁律（三层架构设计）： +> **重要说明**：playbook 仓库中的 `rulesets/` 是**规则集模板库**，不是 playbook 项目自身的代理规则。 +> +> Playbook 本身不包含源代码，因此不需要 AI 代理遵循规则。`rulesets/` 存在的目的是： +> 1. 作为**模板源**，供其他项目复制 +> 2. 通过 `sync_standards.sh` 部署到目标项目的 `.agents/` +> 3. 目标项目的 AI 代理读取**项目根目录的 `.agents/`**（从模板生成） + +`rulesets/` 是 AI 代理规则集模板（三层架构设计）： ### 三层架构设计 ``` -Layer 1: .agents/ (≤50 行/语言，自动加载) +Layer 1: rulesets/ (≤50 行/语言，模板源) ├─ 核心约束与安全红线 └─ 指向 Skills 和 docs @@ -62,11 +69,11 @@ Layer 3: docs/ (权威静态文档) ``` **目录结构**： -- `.agents/index.md`：规则集索引（跨语言） -- `.agents/tsl/index.md`：TSL 核心约定（47 行） -- `.agents/cpp/index.md`：C++ 核心约定（50 行） -- `.agents/python/index.md`：Python 核心约定（48 行） -- `.agents/markdown/index.md`：Markdown 核心约定（23 行，仅代码格式化） +- `rulesets/index.md`：规则集索引（跨语言） +- `rulesets/tsl/index.md`：TSL 核心约定（47 行） +- `rulesets/cpp/index.md`：C++ 核心约定（50 行） +- `rulesets/python/index.md`：Python 核心约定（48 行） +- `rulesets/markdown/index.md`：Markdown 核心约定（23 行，仅代码格式化） 详见：`AGENTS.md` diff --git a/.agents/cpp/index.md b/rulesets/cpp/index.md similarity index 100% rename from .agents/cpp/index.md rename to rulesets/cpp/index.md diff --git a/rulesets/index.md b/rulesets/index.md new file mode 100644 index 0000000..81edaca --- /dev/null +++ b/rulesets/index.md @@ -0,0 +1,23 @@ +# rulesets/（规则集模板库） + +> **重要**：本目录位于 **playbook 仓库**，作为**规则集模板源**。 +> +> - **模板源**：`playbook/rulesets/` → 通过 `sync_standards.*` 同步 → 目标项目的 `.agents/` +> - **AI 读取**：目标项目根目录的 `.agents/`，而非此处 +> - **使用流程**： +> ``` +> playbook/rulesets/tsl/ → [sync] → your-project/.agents/tsl/ ← AI 代理读取 +> (模板源) (实际使用) +> ``` + +本目录用于存放 **AI/自动化代理规则集模板**，用于分发到其他项目。 + +本仓库将规则按语言拆分为多个规则集模板： + +- `rulesets/tsl/`：TSL 相关规则集（适用于 `.tsl`/`.tsf`） +- `rulesets/cpp/`：C++ 相关规则集（C++23，含 Modules） +- `rulesets/python/`：Python 相关规则集 +- `rulesets/markdown/`：Markdown 相关规则集（仅代码格式化） + +目标项目落地时，通过 `scripts/sync_standards.*` +将规则集从 `rulesets//` 同步到目标项目根目录的 `.agents//`。 diff --git a/.agents/markdown/index.md b/rulesets/markdown/index.md similarity index 100% rename from .agents/markdown/index.md rename to rulesets/markdown/index.md diff --git a/.agents/python/index.md b/rulesets/python/index.md similarity index 100% rename from .agents/python/index.md rename to rulesets/python/index.md diff --git a/.agents/tsl/index.md b/rulesets/tsl/index.md similarity index 100% rename from .agents/tsl/index.md rename to rulesets/tsl/index.md diff --git a/scripts/sync_standards.bat b/scripts/sync_standards.bat index bfdfdf8..d55ab27 100644 --- a/scripts/sync_standards.bat +++ b/scripts/sync_standards.bat @@ -2,7 +2,7 @@ setlocal enabledelayedexpansion rem Sync standards snapshot to project root. -rem - Copies \.agents\ -> \.agents\ +rem - Copies \rulesets\ -> \.agents\ rem - Updates \.gitattributes (append missing rules by default) rem Existing targets are backed up before overwrite. rem @@ -18,8 +18,15 @@ if "%ROOT%"=="" set "ROOT=%cd%" for %%I in ("%ROOT%") do set "ROOT=%%~fI" for %%I in ("%SCRIPT_DIR%..") do set "SRC=%%~fI" -set "AGENTS_SRC_ROOT=%SRC%\.agents" + +set "AGENTS_SRC_ROOT=%SRC%\rulesets" set "GITATTR_SRC=%SRC%\.gitattributes" + +if not exist "%AGENTS_SRC_ROOT%" ( + echo ERROR: Standards snapshot not found at %AGENTS_SRC_ROOT% >&2 + echo Run: git subtree add --prefix docs/standards/playbook ^ ^ --squash >&2 + exit /b 1 +) set "AGENTS_NS=%AGENTS_NS%" set "GITATTR_DST=%ROOT%\.gitattributes" set "SYNC_GITATTR_MODE=%SYNC_GITATTR_MODE%" diff --git a/scripts/sync_standards.ps1 b/scripts/sync_standards.ps1 index 938bc9f..dafd490 100644 --- a/scripts/sync_standards.ps1 +++ b/scripts/sync_standards.ps1 @@ -1,5 +1,5 @@ # Sync standards snapshot to project root. -# - Copies /.agents/ -> /.agents/ +# - Copies /rulesets/ -> /.agents/ # - Updates /.gitattributes (append missing rules by default) # Existing targets are backed up before overwrite. [CmdletBinding()] @@ -22,7 +22,7 @@ if (-not $Root) { } $Root = (Resolve-Path $Root).Path -$AgentsSrcRoot = Join-Path $Src ".agents" +$AgentsSrcRoot = Join-Path $Src "rulesets" $GitAttrSrc = Join-Path $Src ".gitattributes" if (-not (Test-Path $AgentsSrcRoot)) { diff --git a/scripts/sync_standards.sh b/scripts/sync_standards.sh index f133675..52cee5f 100644 --- a/scripts/sync_standards.sh +++ b/scripts/sync_standards.sh @@ -2,7 +2,7 @@ set -eu # Sync standards snapshot to project root. -# - Copies /.agents/ -> /.agents/ +# - Copies /rulesets/ -> /.agents/ # - Updates /.gitattributes (append missing rules by default) # Existing targets are backed up before overwrite. # @@ -20,7 +20,8 @@ else ROOT="$(git -C "$SCRIPT_DIR" rev-parse --show-toplevel 2>/dev/null || pwd)" fi ROOT="$(CDPATH= cd -- "$ROOT" && pwd -P)" -AGENTS_SRC_ROOT="$SRC/.agents" + +AGENTS_SRC_ROOT="$SRC/rulesets" GITATTR_SRC="$SRC/.gitattributes" if [ ! -d "$AGENTS_SRC_ROOT" ]; then diff --git a/scripts/vendor_playbook.bat b/scripts/vendor_playbook.bat index 0ade3d2..5b3e602 100644 --- a/scripts/vendor_playbook.bat +++ b/scripts/vendor_playbook.bat @@ -2,7 +2,7 @@ setlocal enabledelayedexpansion rem Vendor a trimmed Playbook snapshot into a target project (offline copy), -rem then run sync_standards to materialize .agents\\ and .gitattributes in +rem then run sync_standards to materialize rulesets\\ and .gitattributes in rem the target project root. rem rem Usage: @@ -75,8 +75,8 @@ if errorlevel 1 ( exit /b 1 ) -if not exist "%DEST_PREFIX%\\.agents" mkdir "%DEST_PREFIX%\\.agents" -copy /y "%SRC%\\.agents\\index.md" "%DEST_PREFIX%\\.agents\\index.md" >nul +if not exist "%DEST_PREFIX%\\rulesets" mkdir "%DEST_PREFIX%\\rulesets" +copy /y "%SRC%\\rulesets\\index.md" "%DEST_PREFIX%\\rulesets\\index.md" >nul if not exist "%DEST_PREFIX%\\templates" mkdir "%DEST_PREFIX%\\templates" @@ -103,8 +103,8 @@ for %%L in (%LANGS%) do ( echo ERROR: docs not found for lang=%%~L "%SRC%\\docs\\%%~L" exit /b 1 ) - if not exist "%SRC%\\.agents\\%%~L" ( - echo ERROR: agents ruleset not found for lang=%%~L "%SRC%\\.agents\\%%~L" + if not exist "%SRC%\\rulesets\\%%~L" ( + echo ERROR: agents ruleset not found for lang=%%~L "%SRC%\\rulesets\\%%~L" exit /b 1 ) @@ -114,7 +114,7 @@ for %%L in (%LANGS%) do ( exit /b 1 ) - xcopy "%SRC%\\.agents\\%%~L\\*" "%DEST_PREFIX%\\.agents\\%%~L\\" /e /i /y >nul + xcopy "%SRC%\\rulesets\\%%~L\\*" "%DEST_PREFIX%\\rulesets\\%%~L\\" /e /i /y >nul if errorlevel 1 ( echo ERROR: failed to copy agents for lang=%%~L exit /b 1 @@ -166,7 +166,7 @@ set "README=%DEST_PREFIX%\\README.md" >> "%README%" echo 查看规范入口： >> "%README%" echo. >> "%README%" echo - `docs/standards/playbook/docs/index.md` ->> "%README%" echo - `.agents/index.md` +>> "%README%" echo - `rulesets/index.md` >> "%README%" echo. >> "%README%" echo ## Codex skills（可选） >> "%README%" echo. @@ -191,24 +191,24 @@ set "SOURCE=%DEST_PREFIX%\\SOURCE.md" echo Vendored snapshot -^> %DEST_PREFIX% -set "PROJECT_AGENTS_ROOT=%DEST_ROOT_ABS%\\.agents" +set "PROJECT_AGENTS_ROOT=%DEST_ROOT_ABS%\\rulesets" set "PROJECT_AGENTS_INDEX=%PROJECT_AGENTS_ROOT%\\index.md" if not exist "%PROJECT_AGENTS_ROOT%" mkdir "%PROJECT_AGENTS_ROOT%" if not exist "%PROJECT_AGENTS_INDEX%" ( - > "%PROJECT_AGENTS_INDEX%" echo # .agents（多语言） + > "%PROJECT_AGENTS_INDEX%" echo # rulesets（多语言） >> "%PROJECT_AGENTS_INDEX%" echo. >> "%PROJECT_AGENTS_INDEX%" echo 本目录用于存放仓库级/语言级的代理规则集。 >> "%PROJECT_AGENTS_INDEX%" echo. >> "%PROJECT_AGENTS_INDEX%" echo 本项目已启用的规则集： for %%L in (%LANGS%) do ( - if /I "%%~L"=="tsl" >> "%PROJECT_AGENTS_INDEX%" echo - .agents/tsl/：TSL 相关规则集（适用于 .tsl/.tsf） - if /I "%%~L"=="cpp" >> "%PROJECT_AGENTS_INDEX%" echo - .agents/cpp/：C++ 相关规则集（C++23，含 Modules） - if /I "%%~L"=="python" >> "%PROJECT_AGENTS_INDEX%" echo - .agents/python/：Python 相关规则集 - if /I "%%~L"=="markdown" >> "%PROJECT_AGENTS_INDEX%" echo - .agents/markdown/：Markdown 相关规则集（仅代码格式化） + if /I "%%~L"=="tsl" >> "%PROJECT_AGENTS_INDEX%" echo - rulesets/tsl/：TSL 相关规则集（适用于 .tsl/.tsf） + if /I "%%~L"=="cpp" >> "%PROJECT_AGENTS_INDEX%" echo - rulesets/cpp/：C++ 相关规则集（C++23，含 Modules） + if /I "%%~L"=="python" >> "%PROJECT_AGENTS_INDEX%" echo - rulesets/python/：Python 相关规则集 + if /I "%%~L"=="markdown" >> "%PROJECT_AGENTS_INDEX%" echo - rulesets/markdown/：Markdown 相关规则集（仅代码格式化） ) >> "%PROJECT_AGENTS_INDEX%" echo. >> "%PROJECT_AGENTS_INDEX%" echo 入口建议从： - for %%L in (%LANGS%) do >> "%PROJECT_AGENTS_INDEX%" echo - .agents/%%~L/index.md + for %%L in (%LANGS%) do >> "%PROJECT_AGENTS_INDEX%" echo - rulesets/%%~L/index.md >> "%PROJECT_AGENTS_INDEX%" echo. >> "%PROJECT_AGENTS_INDEX%" echo 标准快照文档入口： >> "%PROJECT_AGENTS_INDEX%" echo. diff --git a/scripts/vendor_playbook.ps1 b/scripts/vendor_playbook.ps1 index 94634f7..1c57080 100644 --- a/scripts/vendor_playbook.ps1 +++ b/scripts/vendor_playbook.ps1 @@ -1,5 +1,5 @@ # Vendor a trimmed Playbook snapshot into a target project (offline copy), -# then run sync_standards to materialize .agents\\ and .gitattributes in +# then run sync_standards to materialize rulesets\\ and .gitattributes in # the target project root. # # Usage: @@ -74,9 +74,9 @@ $DocsDir = Join-Path $DestPrefix "docs" New-Item -ItemType Directory -Path $DocsDir -Force | Out-Null Copy-Item (Join-Path $Src "docs/common") $DocsDir -Recurse -Force -$AgentsDir = Join-Path $DestPrefix ".agents" +$AgentsDir = Join-Path $DestPrefix "rulesets" New-Item -ItemType Directory -Path $AgentsDir -Force | Out-Null -Copy-Item (Join-Path $Src ".agents/index.md") (Join-Path $AgentsDir "index.md") -Force +Copy-Item (Join-Path $Src "rulesets/index.md") (Join-Path $AgentsDir "index.md") -Force $TemplatesDir = Join-Path $DestPrefix "templates" New-Item -ItemType Directory -Path $TemplatesDir -Force | Out-Null @@ -91,7 +91,7 @@ foreach ($lang in $Langs) { if (-not (Test-Path $docsSrc)) { throw "Docs not found for lang=$lang ($docsSrc)" } Copy-Item $docsSrc $DocsDir -Recurse -Force - $agentsSrc = Join-Path (Join-Path $Src ".agents") $lang + $agentsSrc = Join-Path (Join-Path $Src "rulesets") $lang if (-not (Test-Path $agentsSrc)) { throw "Agents ruleset not found for lang=$lang ($agentsSrc)" } Copy-Item $agentsSrc $AgentsDir -Recurse -Force @@ -184,7 +184,7 @@ sh docs/standards/playbook/scripts/sync_standards.sh $langsCsv 查看规范入口： - `docs/standards/playbook/docs/index.md` -- `.agents/index.md` +- `rulesets/index.md` ## Codex skills（可选） @@ -211,27 +211,27 @@ sh docs/standards/playbook/scripts/install_codex_skills.sh Write-Host "Vendored snapshot -> $DestPrefix" -$ProjectAgentsRoot = Join-Path $DestRootAbs ".agents" +$ProjectAgentsRoot = Join-Path $DestRootAbs "rulesets" $ProjectAgentsIndex = Join-Path $ProjectAgentsRoot "index.md" New-Item -ItemType Directory -Path $ProjectAgentsRoot -Force | Out-Null if (-not (Test-Path $ProjectAgentsIndex)) { $agentLines = New-Object System.Collections.Generic.List[string] - $agentLines.Add("# .agents（多语言）") + $agentLines.Add("# rulesets（多语言）") $agentLines.Add("") $agentLines.Add("本目录用于存放仓库级/语言级的代理规则集。") $agentLines.Add("") $agentLines.Add("本项目已启用的规则集：") foreach ($lang in $Langs) { switch ($lang) { - "tsl" { $agentLines.Add("- .agents/tsl/：TSL 相关规则集（适用于 .tsl/.tsf）"); break } - "cpp" { $agentLines.Add("- .agents/cpp/：C++ 相关规则集（C++23，含 Modules）"); break } - "python" { $agentLines.Add("- .agents/python/：Python 相关规则集"); break } - "markdown" { $agentLines.Add("- .agents/markdown/：Markdown 相关规则集（仅代码格式化）"); break } + "tsl" { $agentLines.Add("- rulesets/tsl/：TSL 相关规则集（适用于 .tsl/.tsf）"); break } + "cpp" { $agentLines.Add("- rulesets/cpp/：C++ 相关规则集（C++23，含 Modules）"); break } + "python" { $agentLines.Add("- rulesets/python/：Python 相关规则集"); break } + "markdown" { $agentLines.Add("- rulesets/markdown/：Markdown 相关规则集（仅代码格式化）"); break } } } $agentLines.Add("") $agentLines.Add("入口建议从：") - foreach ($lang in $Langs) { $agentLines.Add("- .agents/$lang/index.md") } + foreach ($lang in $Langs) { $agentLines.Add("- rulesets/$lang/index.md") } $agentLines.Add("") $agentLines.Add("标准快照文档入口：") $agentLines.Add("") diff --git a/scripts/vendor_playbook.sh b/scripts/vendor_playbook.sh index 19fdd61..4c64b1b 100644 --- a/scripts/vendor_playbook.sh +++ b/scripts/vendor_playbook.sh @@ -13,6 +13,7 @@ set -eu # Notes: # - Snapshot is written to: /docs/standards/playbook/ # - Existing snapshot is backed up before overwrite. +# - Ruleset templates from rulesets/ will be copied to snapshot for sync_standards use. SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd -P)" SRC="$(CDPATH= cd -- "$SCRIPT_DIR/.." && pwd -P)" @@ -80,8 +81,9 @@ cp "$SRC/SKILLS.md" "$DEST_PREFIX/SKILLS.md" mkdir -p "$DEST_PREFIX/docs" cp -R "$SRC/docs/common" "$DEST_PREFIX/docs/" -mkdir -p "$DEST_PREFIX/.agents" -cp "$SRC/.agents/index.md" "$DEST_PREFIX/.agents/index.md" +# Copy rulesets +mkdir -p "$DEST_PREFIX/rulesets" +cp "$SRC/rulesets/index.md" "$DEST_PREFIX/rulesets/index.md" mkdir -p "$DEST_PREFIX/templates" if [ -d "$SRC/templates/ci" ]; then @@ -108,13 +110,14 @@ for lang in "$@"; do echo "ERROR: docs not found for lang=$lang ($SRC/docs/$lang)" >&2 exit 1 fi - if [ ! -d "$SRC/.agents/$lang" ]; then - echo "ERROR: agents ruleset not found for lang=$lang ($SRC/.agents/$lang)" >&2 + + if [ ! -d "$SRC/rulesets/$lang" ]; then + echo "ERROR: rulesets not found for lang=$lang ($SRC/rulesets/$lang)" >&2 exit 1 fi cp -R "$SRC/docs/$lang" "$DEST_PREFIX/docs/" - cp -R "$SRC/.agents/$lang" "$DEST_PREFIX/.agents/" + cp -R "$SRC/rulesets/$lang" "$DEST_PREFIX/rulesets/" if [ -d "$SRC/templates/$lang" ]; then cp -R "$SRC/templates/$lang" "$DEST_PREFIX/templates/" fi diff --git a/tests/scripts/test_sync_standards.bats b/tests/scripts/test_sync_standards.bats index bec93ef..6a215ca 100644 --- a/tests/scripts/test_sync_standards.bats +++ b/tests/scripts/test_sync_standards.bats @@ -14,7 +14,7 @@ setup() { # 模拟 playbook 快照目录 mkdir -p docs/standards/playbook - cp -r "$PLAYBOOK_ROOT"/{.agents,.gitattributes,docs,scripts} docs/standards/playbook/ 2>/dev/null || true + cp -r "$PLAYBOOK_ROOT"/{rulesets,.gitattributes,docs,scripts} docs/standards/playbook/ 2>/dev/null || true export SCRIPT_PATH="$TEST_DIR/docs/standards/playbook/scripts/sync_standards.sh" } @@ -170,7 +170,7 @@ EOF [ -f ".gitattributes.bak."* ] || [ -f ".gitattributes.bak" ] } -@test "备份 - .agents/ 更新前创建备份" { +@test "备份 - rulesets/ 更新前创建备份" { cd "$TEST_DIR" mkdir -p .agents/tsl echo "# Old index" > .agents/tsl/index.md @@ -189,8 +189,8 @@ EOF cd "$TEST_DIR" # 复制 Python 规则集（如果存在） - if [ -d "$PLAYBOOK_ROOT/.agents/python" ]; then - cp -r "$PLAYBOOK_ROOT/.agents/python" docs/standards/playbook/.agents/ + if [ -d "$PLAYBOOK_ROOT/rulesets/python" ]; then + cp -r "$PLAYBOOK_ROOT/rulesets/python" docs/standards/playbook/rulesets/ fi sh "$SCRIPT_PATH" tsl cpp @@ -209,7 +209,7 @@ EOF @test "错误处理 - 未找到 playbook 快照时报错" { cd "$TEST_DIR" - rm -rf docs/standards/playbook/.agents + rm -rf docs/standards/playbook/rulesets run sh "$SCRIPT_PATH" tsl @@ -278,11 +278,11 @@ EOF # 第一次同步 sh "$SCRIPT_PATH" tsl - CHECKSUM1=$(find .agents/tsl -type f -exec md5sum {} \; | sort | md5sum) + CHECKSUM1=$(find rulesets/tsl -type f -exec md5sum {} \; | sort | md5sum) # 第二次同步 sh "$SCRIPT_PATH" tsl - CHECKSUM2=$(find .agents/tsl -type f -exec md5sum {} \; | sort | md5sum) + CHECKSUM2=$(find rulesets/tsl -type f -exec md5sum {} \; | sort | md5sum) [ "$CHECKSUM1" = "$CHECKSUM2" ] } diff --git a/tests/scripts/test_vendor_playbook.bats b/tests/scripts/test_vendor_playbook.bats index 96babb0..50ea96e 100644 --- a/tests/scripts/test_vendor_playbook.bats +++ b/tests/scripts/test_vendor_playbook.bats @@ -53,7 +53,7 @@ teardown() { [ -d "docs/standards/playbook" ] [ -d "docs/standards/playbook/docs/common" ] [ -d "docs/standards/playbook/docs/tsl" ] - [ -d "docs/standards/playbook/.agents/tsl" ] + [ -d "docs/standards/playbook/rulesets/tsl" ] [ -f "docs/standards/playbook/scripts/sync_standards.sh" ] } @@ -65,8 +65,8 @@ teardown() { # 验证包含两种语言的文档 [ -d "docs/standards/playbook/docs/tsl" ] [ -d "docs/standards/playbook/docs/cpp" ] - [ -d "docs/standards/playbook/.agents/tsl" ] - [ -d "docs/standards/playbook/.agents/cpp" ] + [ -d "docs/standards/playbook/rulesets/tsl" ] + [ -d "docs/standards/playbook/rulesets/cpp" ] } # ==============================================