🐛 fix(playbook): add agents mirror for sync

.agents/cpp/index.md

@@ -0,0 +1,50 @@
+# C++ 代理规则集
+
+本规则集定义 AI/自动化代理在处理 C++ 代码时必须遵守的核心约束。
+
+## 范围与优先级
+
+- 作为仓库级基线规则集使用；更靠近代码目录的规则更具体并可覆盖基线。
+- 当代理规则与 docs 冲突：安全/合规优先，其次保持仓库一致性。
+
+## 代理工作原则（铁律）
+
+1. 先理解目标与上下文，再动手改代码
+2. 修改要小而清晰；避免无关重构
+3. 发现安全问题（内存安全/鉴权漏洞）立即标注或修复
+4. 不引入新依赖或工具，除非明确要求
+
+## C++ 核心约定（不可违反）
+
+- 语言标准：C++23；优先使用 Modules；避免裸指针、`new/delete`、C 风格字符串
+- 代码风格：Google C++ Style Guide；使用项目 `.clang-format`；头文件保护用 `#pragma once`
+- 命名规范：文件 `lower_with_under.cpp/.h/.cppm`；类型 `CapWords`；函数/变量 `lower_with_under`；常量 `kCapWords`；成员 `lower_with_under_`；命名空间 `lower_with_under`
+- Modules 工程：模块名点分层 `lower_snake_case`；接口文件 `.cppm`；修改 `export module` 必须更新 CMake module file-set
+- 构建与依赖：Conan 需提供 `conan-release`/`conan-debug`；`conan install` + `cmake --preset ...`；Windows 通过 Linux + Clang 交叉编译验证
+
+## 安全红线（不可触碰）
+
+- 不得在代码/日志/注释中写入明文密钥、密码、Token、API Key
+- 避免内存不安全操作：悬垂指针、双重释放、越界访问
+- 禁用不安全函数（`strcpy`, `sprintf`, `gets` 等）
+- 修改鉴权/权限逻辑必须说明动机与风险
+
+## 权威来源
+
+- 代码风格：`docs/cpp/code_style.md`
+- 命名规范：`docs/cpp/naming.md`
+- 工具链：`docs/cpp/toolchain.md`
+- 依赖管理：`docs/cpp/dependencies_conan.md`
+- clangd 配置：`docs/cpp/clangd.md`
+
+## Skills（按需加载）
+
+- `$performance-optimization`
+- `$testing-workflow`
+- `$code-review-workflow`
+- `$commit-message`
+
+## 与开发规范的关系
+
+- 本仓库内：`docs/cpp/` 与 `docs/common/`
+- 目标项目 subtree：`docs/standards/playbook/docs/cpp/` 与 `docs/standards/playbook/docs/common/`

.agents/index.md

@@ -0,0 +1,13 @@
+# .agents（多语言规则集快照）
+
+本目录用于存放 **AI/自动化代理在仓库内工作时必须遵守的规则**。
+
+本仓库将规则按语言拆分为多个规则集快照：
+
+- `.agents/tsl/`：TSL 相关规则集（适用于 `.tsl`/`.tsf`）
+- `.agents/cpp/`：C++ 相关规则集（C++23，含 Modules）
+- `.agents/python/`：Python 相关规则集
+- `.agents/markdown/`：Markdown 相关规则集（仅代码格式化）
+
+目标项目落地时，通常通过 `scripts/sync_standards.*`
+将某个规则集同步到目标项目根目录的 `.agents/<lang>/`。

.agents/markdown/index.md

@@ -0,0 +1,27 @@
+# Markdown 代理规则集
+
+本规则集定义 AI/自动化代理在处理 Markdown（`.md`）文件时必须遵守的核心约束。
+
+## 代理工作原则（铁律）
+
+1. 只调整代码块与行内代码；不改写正文内容
+2. 不改变标题层级、列表结构、段落顺序
+3. 不引入新工具/格式化链路，除非明确要求
+
+## Markdown 代码格式约定（不可违反）
+
+### 代码块
+- 统一使用围栏代码块（```lang）
+- 语言标识尽量准确：`tsl`/`cpp`/`python`/`bash`/`json` 等
+- 仅做必要的排版修复；不改变代码语义
+
+### 工具
+- 优先使用仓库既有的格式化工具（如 Prettier）
+- 不引入新的 Markdown 格式化依赖
+
+### 行内代码
+- 用反引号包裹命令、路径、关键字或短代码
+
+## 适用范围
+- 仅适用于 `.md` 文件
+- 涉及代码内容时，遵循对应语言的 `.agents` 规则

.agents/python/index.md

@@ -0,0 +1,48 @@
+# Python 代理规则集
+
+本规则集定义 AI/自动化代理在处理 Python 代码时必须遵守的核心约束。
+
+## 范围与优先级
+
+- 作为仓库级基线规则集使用；更靠近代码目录的规则更具体并可覆盖基线。
+- 当代理规则与 docs 冲突：安全/合规优先，其次保持仓库一致性。
+
+## 代理工作原则（铁律）
+
+1. 先理解目标与上下文，再动手改代码
+2. 修改要小而清晰；避免无关重构
+3. 发现安全问题（明文密钥/鉴权漏洞）立即标注或修复
+4. 不引入新依赖或工具，除非明确要求
+
+## Python 核心约定（不可违反）
+
+- 代码风格：Google Python Style Guide；优先使用仓库既有配置（`pyproject.toml`, `.flake8`, `.pylintrc`）
+- 工具链：未经沟通不切换 formatter/linter
+- Import：标准库 → 第三方 → 本地模块；分组间空行；避免 `import *`
+- 命名：模块/包 `lower_with_under.py`；类 `CapWords`；函数/变量 `lower_with_under`；常量 `UPPER_WITH_UNDER`；私有 `_private`
+- Docstring：Google 风格；公共模块/类/函数/方法必须写
+
+## 安全红线（不可触碰）
+
+- 不得在代码/日志/注释中写入明文密钥、密码、Token、API Key
+- 不得使用 `eval()` / `exec()` 处理不可信输入
+- 修改鉴权/权限逻辑必须说明动机与风险
+- 不确定是否敏感时按敏感信息处理
+
+## 权威来源
+
+- 代码风格：`docs/python/style_guide.md`
+- 工具链：`docs/python/tooling.md`
+- 配置清单：`docs/python/configuration.md`
+
+## Skills（按需加载）
+
+- `$performance-optimization`
+- `$testing-workflow`
+- `$code-review-workflow`
+- `$commit-message`
+
+## 与开发规范的关系
+
+- 本仓库内：`docs/python/` 与 `docs/common/`
+- 目标项目 subtree：`docs/standards/playbook/docs/python/` 与 `docs/standards/playbook/docs/common/`

.agents/tsl/index.md

@@ -0,0 +1,47 @@
+# TSL 代理规则集
+
+本规则集定义 AI/自动化代理在处理 TSL 代码时必须遵守的核心约束。
+
+## 范围与优先级
+
+- 作为仓库级基线规则集使用；更靠近代码目录的规则更具体并可覆盖基线。
+- 当代理规则与 docs 冲突：安全/合规优先，其次保持仓库一致性。
+
+## 代理工作原则（铁律）
+
+1. 先理解目标与上下文，再动手改代码
+2. 修改要小而清晰；避免无关重构
+3. 发现安全问题（明文密钥/鉴权漏洞）立即标注或修复
+4. 不引入新依赖或工具，除非明确要求
+
+## TSL 核心约定（不可违反）
+
+- 文件结构：一文件一顶层声明；文件名 = 声明名；`.tsl` 仅 `function`，`.tsf` 可 `function/class/unit`
+- 格式：4 空格缩进；关键字小写；多语句用 `begin/end`
+- 命名：类型/函数/property `PascalCase`；变量/参数 `snake_case`；私有 `snake_case_`；常量 `kPascalCase`
+
+## 安全红线（不可触碰）
+
+- 不得在代码/日志/注释中写入明文密钥、密码、Token、API Key
+- 修改鉴权/权限逻辑必须说明动机与风险
+- 不确定是否敏感时按敏感信息处理
+
+## 权威来源
+
+- 语法手册：`docs/tsl/syntax_book/index.md`
+- 函数库：`docs/tsl/syntax_book/function/`（按需检索，禁止整份加载）
+- 代码风格：`docs/tsl/code_style.md`
+- 命名规范：`docs/tsl/naming.md`
+
+## Skills（按需加载）
+
+- `$tsl-guide`
+- `$performance-optimization`
+- `$testing-workflow`
+- `$code-review-workflow`
+- `$commit-message`
+
+## 与开发规范的关系
+
+- 本仓库内：`docs/tsl/` 与 `docs/common/`
+- 目标项目 subtree：`docs/standards/playbook/docs/tsl/` 与 `docs/standards/playbook/docs/common/`

scripts/sync_standards.bat

@@ -20,6 +20,11 @@ for %%I in ("%ROOT%") do set "ROOT=%%~fI"
 for %%I in ("%SCRIPT_DIR%..") do set "SRC=%%~fI"
 
 set "AGENTS_SRC_ROOT=%SRC%\rulesets"
+if not exist "%AGENTS_SRC_ROOT%" (
+  if exist "%SRC%\.agents" (
+    set "AGENTS_SRC_ROOT=%SRC%\.agents"
+  )
+)
 set "GITATTR_SRC=%SRC%\.gitattributes"
 
 if not exist "%AGENTS_SRC_ROOT%" (

scripts/sync_standards.ps1

@@ -23,6 +23,12 @@ if (-not $Root) {
 $Root = (Resolve-Path $Root).Path
 
 $AgentsSrcRoot = Join-Path $Src "rulesets"
+if (-not (Test-Path $AgentsSrcRoot)) {
+  $legacyAgents = Join-Path $Src ".agents"
+  if (Test-Path $legacyAgents) {
+    $AgentsSrcRoot = $legacyAgents
+  }
+}
 $GitAttrSrc = Join-Path $Src ".gitattributes"
 
 if (-not (Test-Path $AgentsSrcRoot)) {

scripts/sync_standards.sh

@@ -22,6 +22,9 @@ fi
 ROOT="$(CDPATH= cd -- "$ROOT" && pwd -P)"
 
 AGENTS_SRC_ROOT="$SRC/rulesets"
+if [ ! -d "$AGENTS_SRC_ROOT" ] && [ -d "$SRC/.agents" ]; then
+  AGENTS_SRC_ROOT="$SRC/.agents"
+fi
 GITATTR_SRC="$SRC/.gitattributes"
 
 if [ ! -d "$AGENTS_SRC_ROOT" ]; then

scripts/vendor_playbook.bat

@@ -77,6 +77,13 @@ if errorlevel 1 (
 
 if not exist "%DEST_PREFIX%\\rulesets" mkdir "%DEST_PREFIX%\\rulesets"
 copy /y "%SRC%\\rulesets\\index.md" "%DEST_PREFIX%\\rulesets\\index.md" >nul
+if exist "%SRC%\\.agents" (
+  xcopy "%SRC%\\.agents\\*" "%DEST_PREFIX%\\.agents\\" /e /i /y >nul
+  if errorlevel 1 (
+    echo ERROR: failed to copy .agents
+    exit /b 1
+  )
+)
 
 if not exist "%DEST_PREFIX%\\templates" mkdir "%DEST_PREFIX%\\templates"
 
@@ -166,7 +173,7 @@ set "README=%DEST_PREFIX%\\README.md"
 >> "%README%" echo 查看规范入口：
 >> "%README%" echo.
 >> "%README%" echo - `docs/standards/playbook/docs/index.md`
->> "%README%" echo - `rulesets/index.md`
+>> "%README%" echo - `.agents/index.md`
 >> "%README%" echo.
 >> "%README%" echo ## Codex skills（可选）
 >> "%README%" echo.

scripts/vendor_playbook.ps1

@@ -77,6 +77,11 @@ Copy-Item (Join-Path $Src "docs/common") $DocsDir -Recurse -Force
 $AgentsDir = Join-Path $DestPrefix "rulesets"
 New-Item -ItemType Directory -Path $AgentsDir -Force | Out-Null
 Copy-Item (Join-Path $Src "rulesets/index.md") (Join-Path $AgentsDir "index.md") -Force
+# Compatibility: keep a mirrored .agents/ snapshot when present.
+$LegacyAgents = Join-Path $Src ".agents"
+if (Test-Path $LegacyAgents) {
+  Copy-Item $LegacyAgents (Join-Path $DestPrefix ".agents") -Recurse -Force
+}
 
 $TemplatesDir = Join-Path $DestPrefix "templates"
 New-Item -ItemType Directory -Path $TemplatesDir -Force | Out-Null
@@ -184,7 +189,7 @@ sh docs/standards/playbook/scripts/sync_standards.sh $langsCsv
 查看规范入口：
 
 - `docs/standards/playbook/docs/index.md`
-- `rulesets/index.md`
+- `.agents/index.md`
 
 ## Codex skills（可选）
 
@@ -211,27 +216,27 @@ sh docs/standards/playbook/scripts/install_codex_skills.sh
 
 Write-Host "Vendored snapshot -> $DestPrefix"
 
-$ProjectAgentsRoot = Join-Path $DestRootAbs "rulesets"
+$ProjectAgentsRoot = Join-Path $DestRootAbs ".agents"
 $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("# rulesets（多语言）")
+  $agentLines.Add("# .agents（多语言）")
   $agentLines.Add("")
   $agentLines.Add("本目录用于存放仓库级/语言级的代理规则集。")
   $agentLines.Add("")
   $agentLines.Add("本项目已启用的规则集：")
   foreach ($lang in $Langs) {
     switch ($lang) {
-      "tsl" { $agentLines.Add("- rulesets/tsl/：TSL 相关规则集（适用于 .tsl/.tsf）"); break }
+      "tsl" { $agentLines.Add("- .agents/tsl/：TSL 相关规则集（适用于 .tsl/.tsf）"); break }
-      "cpp" { $agentLines.Add("- rulesets/cpp/：C++ 相关规则集（C++23，含 Modules）"); break }
+      "cpp" { $agentLines.Add("- .agents/cpp/：C++ 相关规则集（C++23，含 Modules）"); break }
-      "python" { $agentLines.Add("- rulesets/python/：Python 相关规则集"); break }
+      "python" { $agentLines.Add("- .agents/python/：Python 相关规则集"); break }
-      "markdown" { $agentLines.Add("- rulesets/markdown/：Markdown 相关规则集（仅代码格式化）"); break }
+      "markdown" { $agentLines.Add("- .agents/markdown/：Markdown 相关规则集（仅代码格式化）"); break }
     }
   }
   $agentLines.Add("")
   $agentLines.Add("入口建议从：")
-  foreach ($lang in $Langs) { $agentLines.Add("- rulesets/$lang/index.md") }
+  foreach ($lang in $Langs) { $agentLines.Add("- .agents/$lang/index.md") }
   $agentLines.Add("")
   $agentLines.Add("标准快照文档入口：")
   $agentLines.Add("")

scripts/vendor_playbook.sh

@@ -84,6 +84,10 @@ cp -R "$SRC/docs/common" "$DEST_PREFIX/docs/"
 # Copy rulesets
 mkdir -p "$DEST_PREFIX/rulesets"
 cp "$SRC/rulesets/index.md" "$DEST_PREFIX/rulesets/index.md"
+# Compatibility: keep a mirrored .agents/ snapshot when present.
+if [ -d "$SRC/.agents" ]; then
+  cp -R "$SRC/.agents" "$DEST_PREFIX/"
+fi
 
 mkdir -p "$DEST_PREFIX/templates"
 if [ -d "$SRC/templates/ci" ]; then