From 37546fe4f7009cb63360df248ddf518551ae3bc7 Mon Sep 17 00:00:00 2001 From: csh Date: Sat, 10 Jan 2026 22:18:26 +0800 Subject: [PATCH] :bug: fix(playbook): enforce rulesets to agents flow --- .agents/cpp/index.md | 50 ------------------------------------- .agents/index.md | 13 ---------- .agents/markdown/index.md | 27 -------------------- .agents/python/index.md | 48 ----------------------------------- .agents/tsl/index.md | 47 ---------------------------------- .gitea/workflows/test.yml | 8 +++--- README.md | 13 +++++++--- scripts/sync_standards.bat | 5 ---- scripts/sync_standards.ps1 | 6 ----- scripts/sync_standards.sh | 3 --- scripts/vendor_playbook.bat | 7 ------ scripts/vendor_playbook.ps1 | 5 ---- scripts/vendor_playbook.sh | 4 --- 13 files changed, 13 insertions(+), 223 deletions(-) delete mode 100644 .agents/cpp/index.md delete mode 100644 .agents/index.md delete mode 100644 .agents/markdown/index.md delete mode 100644 .agents/python/index.md delete mode 100644 .agents/tsl/index.md diff --git a/.agents/cpp/index.md b/.agents/cpp/index.md deleted file mode 100644 index 7579a7a..0000000 --- a/.agents/cpp/index.md +++ /dev/null @@ -1,50 +0,0 @@ -# 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/` 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/.agents/markdown/index.md b/.agents/markdown/index.md deleted file mode 100644 index 878fb85..0000000 --- a/.agents/markdown/index.md +++ /dev/null @@ -1,27 +0,0 @@ -# Markdown 代理规则集 - -本规则集定义 AI/自动化代理在处理 Markdown（`.md`）文件时必须遵守的核心约束。 - -## 代理工作原则（铁律） - -1. 只调整代码块与行内代码；不改写正文内容 -2. 不改变标题层级、列表结构、段落顺序 -3. 不引入新工具/格式化链路，除非明确要求 - -## Markdown 代码格式约定（不可违反） - -### 代码块 -- 统一使用围栏代码块（```lang） -- 语言标识尽量准确：`tsl`/`cpp`/`python`/`bash`/`json` 等 -- 仅做必要的排版修复；不改变代码语义 - -### 工具 -- 优先使用仓库既有的格式化工具（如 Prettier） -- 不引入新的 Markdown 格式化依赖 - -### 行内代码 -- 用反引号包裹命令、路径、关键字或短代码 - -## 适用范围 -- 仅适用于 `.md` 文件 -- 涉及代码内容时，遵循对应语言的 `.agents` 规则 diff --git a/.agents/python/index.md b/.agents/python/index.md deleted file mode 100644 index 1daa2e0..0000000 --- a/.agents/python/index.md +++ /dev/null @@ -1,48 +0,0 @@ -# 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/` diff --git a/.agents/tsl/index.md b/.agents/tsl/index.md deleted file mode 100644 index 80f6e95..0000000 --- a/.agents/tsl/index.md +++ /dev/null @@ -1,47 +0,0 @@ -# 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/` diff --git a/.gitea/workflows/test.yml b/.gitea/workflows/test.yml index dedc00b..359f6b0 100644 --- a/.gitea/workflows/test.yml +++ b/.gitea/workflows/test.yml @@ -204,7 +204,7 @@ jobs: sh docs/standards/playbook/scripts/sync_standards.sh tsl # 验证结果 - if [ -d "rulesets/tsl" ] && [ -f "rulesets/tsl/index.md" ]; then + if [ -d ".agents/tsl" ] && [ -f ".agents/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 "rulesets/cpp" ] && [ -f "rulesets/cpp/index.md" ]; then + if [ -d ".agents/cpp" ] && [ -f ".agents/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 "rulesets/tsl" ] && [ -d "rulesets/cpp" ] && [ -f "rulesets/index.md" ]; then + if [ -d ".agents/tsl" ] && [ -d ".agents/cpp" ] && [ -f ".agents/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 "rulesets/tsl" ]; then + if [ -d "docs/standards/playbook" ] && [ -d "docs/standards/playbook/rulesets/tsl" ] && [ -d ".agents/tsl" ]; then echo "✅ vendor_playbook 脚本执行成功" else echo "❌ vendor_playbook 脚本执行失败" diff --git a/README.md b/README.md index 183bd21..2c4f14a 100644 --- a/README.md +++ b/README.md @@ -46,6 +46,7 @@ Playbook：TSL（`.tsl`/`.tsf`）+ C++ + Python + Markdown（代码格式化） > **重要说明**：playbook 仓库中的 `rulesets/` 是**规则集模板库**，不是 playbook 项目自身的代理规则。 > > Playbook 本身不包含源代码，因此不需要 AI 代理遵循规则。`rulesets/` 存在的目的是： +> > 1. 作为**模板源**，供其他项目复制 > 2. 通过 `sync_standards.sh` 部署到目标项目的 `.agents/` > 3. 目标项目的 AI 代理读取**项目根目录的 `.agents/`**（从模板生成） @@ -54,7 +55,7 @@ Playbook：TSL（`.tsl`/`.tsf`）+ C++ + Python + Markdown（代码格式化） ### 三层架构设计 -``` +```txt Layer 1: rulesets/ (≤50 行/语言，模板源) ├─ 核心约束与安全红线 └─ 指向 Skills 和 docs @@ -69,6 +70,7 @@ Layer 3: docs/ (权威静态文档) ``` **目录结构**： + - `rulesets/index.md`：规则集索引（跨语言） - `rulesets/tsl/index.md`：TSL 核心约定（47 行） - `rulesets/cpp/index.md`：C++ 核心约定（50 行） @@ -82,11 +84,13 @@ Layer 3: docs/ (权威静态文档) 本仓库内置一组 Codex CLI skills（见 `codex/skills/`），用于按需加载的工作流与知识库。 **核心 Skills**： + - **`$tsl-guide`**：TSL/TSF 语法完整指南（基础/高级/函数库/最佳实践） - **`$performance-optimization`**：跨语言性能优化工作流 - **`$testing-workflow`**：跨语言测试策略 **通用 Skills**： + - `$code-review-workflow`：代码审查流程 - `$commit-message`：提交信息规范 - `$systematic-debugging`：系统化调试 @@ -182,6 +186,7 @@ git commit -m ":package: deps(playbook): add tsl standards" > 会自动生成最小版；已存在则不会覆盖。 3. **验收**（任意满足其一即可）： + - 目录存在：`.agents/tsl/` - 规则入口可读：`.agents/tsl/index.md` - （可选）C++ 规则入口可读：`.agents/cpp/index.md` @@ -287,9 +292,9 @@ sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp 同步脚本支持以下可选环境变量（默认值可满足大多数项目）： -| 变量名 | 默认值 | 说明 | -| ------------------- | ------- | ------------------------------------------------------------------------------------------- | -| `AGENTS_NS` | `tsl` | 同步的规则集名/落地目录名：`.agents//`（例如 `tsl`、`cpp`） | +| 变量名 | 默认值 | 说明 | +| ------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| `AGENTS_NS` | `tsl` | 同步的规则集名/落地目录名：`.agents//`（例如 `tsl`、`cpp`） | | `SYNC_GITATTR_MODE` | `append` | `.gitattributes` 同步模式：`append` 仅追加缺失规则（忽略注释/空行，比对后按块追加）；`block` 仅维护 managed 区块；`overwrite` 全量覆盖；`skip` 不更新 | diff --git a/scripts/sync_standards.bat b/scripts/sync_standards.bat index c09aa14..07eab0e 100644 --- a/scripts/sync_standards.bat +++ b/scripts/sync_standards.bat @@ -20,11 +20,6 @@ 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%" ( diff --git a/scripts/sync_standards.ps1 b/scripts/sync_standards.ps1 index b563cc7..03bfbf0 100644 --- a/scripts/sync_standards.ps1 +++ b/scripts/sync_standards.ps1 @@ -23,12 +23,6 @@ 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)) { diff --git a/scripts/sync_standards.sh b/scripts/sync_standards.sh index 144dfca..4889632 100644 --- a/scripts/sync_standards.sh +++ b/scripts/sync_standards.sh @@ -22,9 +22,6 @@ 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 diff --git a/scripts/vendor_playbook.bat b/scripts/vendor_playbook.bat index 27ef752..7812e9a 100644 --- a/scripts/vendor_playbook.bat +++ b/scripts/vendor_playbook.bat @@ -77,13 +77,6 @@ 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" diff --git a/scripts/vendor_playbook.ps1 b/scripts/vendor_playbook.ps1 index f2b53df..9fa0cb7 100644 --- a/scripts/vendor_playbook.ps1 +++ b/scripts/vendor_playbook.ps1 @@ -77,11 +77,6 @@ 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 diff --git a/scripts/vendor_playbook.sh b/scripts/vendor_playbook.sh index 8cdf6d9..4c64b1b 100644 --- a/scripts/vendor_playbook.sh +++ b/scripts/vendor_playbook.sh @@ -84,10 +84,6 @@ 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