csh
/
playbook
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
69 Commits 2 Branches 0 Tags 6.7 MiB
Commit Graph

12 Commits

Author SHA1 Message Date
csh b2eb475a6d ✅ test(templates): add template coverage 2026-01-21 10:51:48 +08:00
csh cc340f1944 🔧 chore(ci): align standards-check workflow template 2026-01-13 13:14:58 +08:00
csh e9de0aa497 🔧 chore(ci): drop removed skill check 2026-01-13 11:06:14 +08:00
csh 37546fe4f7 🐛 fix(playbook): enforce rulesets to agents flow 2026-01-10 22:18:26 +08:00
csh 31f300010f ♻️ refactor(playbook): rename agents template directory to rulesets 
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 <url> 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 <noreply@anthropic.com>

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/<lang>/`。
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/<lang>/` 同步到目标项目根目录的 `.agents/<lang>/`。
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 <snapshot>\.agents\<AGENTS_NS> -> <project-root>\.agents\<AGENTS_NS>
+rem - Copies <snapshot>\rulesets\<AGENTS_NS> -> <project-root>\.agents\<AGENTS_NS>
 rem - Updates <project-root>\.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 ^<url^> ^<branch^> --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 <snapshot>/.agents/<AGENTS_NS> -> <project-root>/.agents/<AGENTS_NS>
+# - Copies <snapshot>/rulesets/<AGENTS_NS> -> <project-root>/.agents/<AGENTS_NS>
 # - Updates <project-root>/.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 <snapshot>/.agents/<AGENTS_NS> -> <project-root>/.agents/<AGENTS_NS>
+# - Copies <snapshot>/rulesets/<AGENTS_NS> -> <project-root>/.agents/<AGENTS_NS>
 # - Updates <project-root>/.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\<lang>\ and .gitattributes in
+rem then run sync_standards to materialize rulesets\<lang>\ 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\<lang>\ and .gitattributes in
+# then run sync_standards to materialize rulesets\<lang>\ 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: <project-root>/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" ]
 }

 # ==============================================
 2026-01-10 21:17:12 +08:00
csh 5822a8736d ♻️ refactor(playbook): streamline agents and refresh tsl docs 2026-01-10 16:55:44 +08:00
csh 6244aa39da 🔧 chore(ci): relax gitattributes check 2026-01-08 15:40:50 +08:00
csh 15d4d63f24 🔧 chore(ci): install python3-pip 2026-01-08 15:35:36 +08:00
csh 90c6313afa 🔧 chore(ci): run tests in a single job 2026-01-08 15:23:39 +08:00
csh d84eff04b9 🔧 chore(ci): make actions base url configurable 2026-01-08 14:06:15 +08:00
csh 395598dcc8 🔧 chore(ci): fix yaml step names 2026-01-08 13:43:37 +08:00
csh da0ef2b7a2 ✅ test: add automated tests and ci workflow 2026-01-08 11:29:44 +08:00