🔧 chore(standards): sync cpp playbook rules
Vendor standards live under docs/standards/playbook and are synced into .agents/cpp. Add AGENTS.md entries so agents working in lsp-server follow the C++ ruleset and standards.
This commit is contained in:
parent
dbdde4ed48
commit
7c13d70d3a
|
|
@ -0,0 +1,33 @@
|
|||
# 安全与鉴权（Auth）
|
||||
|
||||
本文件定义代理在处理鉴权、安全、敏感数据相关任务时的边界与要求。
|
||||
|
||||
## 1. 基本原则
|
||||
|
||||
- **最小权限**：只使用完成任务所需的最低权限与最少数据。
|
||||
- **默认保守**：不确定是否敏感时按敏感处理。
|
||||
- **不扩散秘密**：任何 secret 只在必要范围内出现。
|
||||
|
||||
## 2. 凭证与敏感信息
|
||||
|
||||
- 不要在代码、日志、注释或文档中写入明文密钥、Token、密码。
|
||||
- 如需示例，使用占位符：`<TOKEN>`、`<PASSWORD>`。
|
||||
- 避免把敏感信息打印到标准输出或错误日志。
|
||||
|
||||
## 3. 鉴权逻辑修改
|
||||
|
||||
- 修改鉴权/权限控制时必须说明：
|
||||
- 变更动机
|
||||
- 风险评估
|
||||
- 兼容性/回滚方案
|
||||
- 默认保持旧行为兼容，除非明确要求破坏性变更。
|
||||
|
||||
## 4. 依赖与第三方
|
||||
|
||||
- 禁止无理由新增依赖，尤其是网络、加密、认证相关依赖。
|
||||
- 若必须新增，需在 PR 说明理由、替代方案与安全影响。
|
||||
|
||||
## 5. 审计与合规
|
||||
|
||||
- 任何涉及用户数据/权限边界的改动需可审计：代码清晰、注释说明“为什么”。
|
||||
- 发现潜在安全漏洞时，优先修复或明确标注 `FIXME(name): security risk ...`。
|
||||
|
|
@ -0,0 +1,34 @@
|
|||
# 代码质量（Code Quality）
|
||||
|
||||
本文件定义代理对代码质量的最低要求与审查清单（C++）。
|
||||
|
||||
## 1. 总体要求
|
||||
|
||||
- C++ 代码遵守 `docs/cpp/code_style.md` 与 `docs/cpp/naming.md`（在目标项目中通常 vendoring 到标准快照路径）。
|
||||
- 统一使用 `clang-format`（Google 基线）保持格式一致；不要手工“对齐排版”制造 diff 噪音。
|
||||
- 改动聚焦目标；避免“顺手重构”。
|
||||
- API 变更要显式说明影响与迁移方式。
|
||||
- 涉及三方依赖（例如 Conan）的改动必须说明动机、替代方案与影响面；默认不“顺手升级依赖”。
|
||||
- 涉及 C++ Modules 的改动（`.cppm` 或 `export module` 变更）必须同步更新构建系统的模块清单与相关 target 配置。
|
||||
|
||||
## 2. 可读性
|
||||
|
||||
- 复杂逻辑拆分为具名函数/类型；避免深层嵌套与重复代码。
|
||||
- 必要注释解释“为什么”而不是“做什么”。
|
||||
|
||||
## 3. 错误处理与资源管理
|
||||
|
||||
- 默认使用 RAII；避免裸 `new/delete`。
|
||||
- 失败路径必须可观测（返回值/异常/日志其一或按项目约定）。
|
||||
|
||||
## 4. 复杂度与规模
|
||||
|
||||
- 单函数尽量 ≤ 80 行；超过应说明原因或拆分（可按项目调整）。
|
||||
- 单次 PR 尽量小步提交，便于 review。
|
||||
|
||||
## 5. Review 清单
|
||||
|
||||
- 是否有无关改动？
|
||||
- 是否保持模块内风格一致？
|
||||
- 是否引入不必要的复杂度/依赖？
|
||||
- 是否有最小验证（构建/冒烟）步骤？
|
||||
|
|
@ -0,0 +1,41 @@
|
|||
# C++ 代理规则集（.agents/cpp）
|
||||
|
||||
本规则集用于存放 **AI/自动化代理在仓库内工作时必须遵守的规则**（C++ 语言专属）。
|
||||
|
||||
## 范围与优先级
|
||||
|
||||
- 作为仓库级基线规则集使用；更靠近代码目录的规则应更具体并可覆盖基线。
|
||||
- 当代理规则与 `docs` 发生冲突时：
|
||||
1. 安全/合规优先
|
||||
2. 其次保持仓库现有一致性
|
||||
|
||||
## 代理工作原则
|
||||
|
||||
- 先理解目标与上下文，再动手改代码。
|
||||
- 修改要小而清晰；避免无关重构。
|
||||
- 不要引入新依赖或工具，除非明确要求。
|
||||
|
||||
## 子文档
|
||||
|
||||
- 安全与鉴权：`auth.md`
|
||||
- 性能：`performance.md`
|
||||
- 代码质量：`code_quality.md`
|
||||
- 测试：`testing.md`
|
||||
|
||||
## C++ 必要约定（必须遵守）
|
||||
|
||||
- 语言标准：C++23（含 Modules）。
|
||||
- 格式化：统一使用 `clang-format`（Google 基线）；避免手工排版对齐造成 diff 噪音。
|
||||
- 文件与命名：遵守 `docs/cpp/` 下的规范（或目标项目 vendoring 的标准快照路径）。
|
||||
- Modules：module 名建议使用点分层级；每段用 `lower_snake_case`；module interface unit 推荐 `.cppm`。
|
||||
- Modules 工程：新增/删除/重命名 `.cppm` 或修改 `export module` 时，必须更新 CMake target 的模块 file-set/清单（否则构建容易漂移）。
|
||||
- Windows：不支持原生 Windows 开发环境；Windows 产物通过 Linux + Clang 交叉编译 profile 验证（profile 的 `[settings] os=Windows`）。
|
||||
- 依赖管理（如使用 Conan）：必须提供统一 preset（`conan-release`/`conan-debug`）；优先通过 `conan install` + `cmake --preset ...` 验证；如遇 Conan 家目录权限问题可临时设置 `CONAN_HOME=/tmp/conan-home`。
|
||||
|
||||
## 与开发规范的关系
|
||||
|
||||
- 在本仓库内：`docs/cpp/` 与 `docs/common/`。
|
||||
- 在目标项目内（若按 README 推荐的 subtree prefix `docs/standards/playbook`）：
|
||||
- 代码风格：`docs/standards/playbook/docs/cpp/code_style.md`
|
||||
- 命名规范：`docs/standards/playbook/docs/cpp/naming.md`
|
||||
- 提交信息：`docs/standards/playbook/docs/common/commit_message.md`
|
||||
|
|
@ -0,0 +1,31 @@
|
|||
# 性能（Performance）
|
||||
|
||||
本文件定义代理在做性能相关改动时的准则与检查项。
|
||||
|
||||
## 1. 目标与度量
|
||||
|
||||
- 明确性能目标：延迟、吞吐、内存、CPU、I/O 等。
|
||||
- 没有指标时不要盲目优化；先补充测量或基准。
|
||||
|
||||
## 2. 处理流程
|
||||
|
||||
1. 先定位瓶颈（profile/trace/log）。
|
||||
2. 再提出最小化改动方案。
|
||||
3. 最后用数据验证收益与副作用。
|
||||
|
||||
## 3. 优化准则
|
||||
|
||||
- 优先消除算法/结构性问题，再考虑微优化。
|
||||
- 避免引入复杂度换取小收益。
|
||||
- 性能优化不应牺牲可读性；必要时加注释说明权衡。
|
||||
|
||||
## 4. 常见风险
|
||||
|
||||
- 避免重复计算、无界缓存、隐式复制。
|
||||
- 注意热路径中的分配与 I/O。
|
||||
- 并发优化要考虑正确性与可测试性。
|
||||
|
||||
## 5. 验证
|
||||
|
||||
- 提供优化前后可复现的对比数据（基准、采样结果或压测报告）。
|
||||
- 若无测试体系，至少提供最小可运行的复现脚本/步骤。
|
||||
|
|
@ -0,0 +1,26 @@
|
|||
# 测试（Testing）
|
||||
|
||||
本文件定义代理在改动代码时的测试策略与要求。
|
||||
|
||||
## 1. 测试层级
|
||||
|
||||
- **单元测试**：验证函数/模块的独立行为。
|
||||
- **集成测试**：验证模块间交互与关键流程。
|
||||
- **回归测试**：防止已修复问题复发。
|
||||
|
||||
## 2. 何时补测试
|
||||
|
||||
- 新功能必须新增对应测试（若项目有测试体系）。
|
||||
- 修复 bug 必须先写/补回归用例（若项目有测试体系）。
|
||||
- 仅当改动纯文档/注释/格式时可不加测试。
|
||||
|
||||
## 3. 测试可维护性
|
||||
|
||||
- 一个用例只验证一个行为点。
|
||||
- 测试命名清晰，能从名字看出期望。
|
||||
- 避免依赖外部不稳定资源；必要时 mock/stub。
|
||||
|
||||
## 4. 运行与失败处理
|
||||
|
||||
- 若项目提供构建/冒烟命令（CMake），优先保证最小构建可通过。
|
||||
- 失败时优先定位改动相关原因，不修无关失败。
|
||||
|
|
@ -0,0 +1,17 @@
|
|||
# .agents（多语言）
|
||||
|
||||
本目录用于存放仓库级/语言级的代理规则集。
|
||||
|
||||
建议约定：
|
||||
|
||||
- `.agents/tsl/`：TSL 相关规则集（由 `sync_standards.*` 同步；适用于 `.tsl`/`.tsf`）
|
||||
- `.agents/cpp/`：C++ 相关规则集（由 `sync_standards.*` 同步；适用于 C++23/Modules）
|
||||
- `.agents/python/` 等：其他语言的规则集（按需增加）
|
||||
|
||||
规则发生冲突时，建议以“更靠近代码的目录规则更具体”为准。
|
||||
|
||||
入口建议从：
|
||||
|
||||
- `.agents/tsl/index.md`（TSL 规则集入口）
|
||||
- `.agents/cpp/index.md`（C++ 规则集入口）
|
||||
- `docs/standards/playbook/docs/`（人类开发规范快照：`tsl/`、`cpp/`、`python/`、`common/`）
|
||||
|
|
@ -23,3 +23,63 @@
|
|||
/lsp-server/test/tree_sitter_tsf/** linguist-generated=true
|
||||
!/lsp-server/test/tree_sitter_tsf/grammar.js
|
||||
**/node_modules/** linguist-vendored=true
|
||||
|
||||
# BEGIN playbook .gitattributes
|
||||
# Ensure all text files use UTF-8 (by convention) and LF line endings.
|
||||
# Line endings are normalized to LF in the repo and checked out as LF,
|
||||
# regardless of OS/core.autocrlf settings.
|
||||
|
||||
# Default: detect text automatically, enforce LF on checkout/commit.
|
||||
* text=auto eol=lf
|
||||
|
||||
# Explicit text types in this repo.
|
||||
*.tsl text eol=lf
|
||||
*.tsf text eol=lf
|
||||
*.md text eol=lf
|
||||
*.txt text eol=lf
|
||||
*.json text eol=lf
|
||||
*.yml text eol=lf
|
||||
*.yaml text eol=lf
|
||||
*.toml text eol=lf
|
||||
*.ini text eol=lf
|
||||
*.cfg text eol=lf
|
||||
*.xml text eol=lf
|
||||
*.csv text eol=lf
|
||||
*.sh text eol=lf
|
||||
*.py text eol=lf
|
||||
*.pyi text eol=lf
|
||||
*.pyx text eol=lf
|
||||
*.pxd text eol=lf
|
||||
*.pxi text eol=lf
|
||||
*.c text eol=lf
|
||||
*.h text eol=lf
|
||||
*.cc text eol=lf
|
||||
*.cpp text eol=lf
|
||||
*.cxx text eol=lf
|
||||
*.hh text eol=lf
|
||||
*.hpp text eol=lf
|
||||
*.hxx text eol=lf
|
||||
*.inl text eol=lf
|
||||
*.ipp text eol=lf
|
||||
*.ixx text eol=lf
|
||||
*.cppm text eol=lf
|
||||
*.mpp text eol=lf
|
||||
*.cmake text eol=lf
|
||||
CMakeLists.txt text eol=lf
|
||||
CMakePresets.json text eol=lf
|
||||
*.clangd text eol=lf
|
||||
.clangd text eol=lf
|
||||
|
||||
# Binary files (no line-ending conversion).
|
||||
*.png binary
|
||||
*.jpg binary
|
||||
*.jpeg binary
|
||||
*.gif binary
|
||||
*.ico binary
|
||||
*.pdf binary
|
||||
*.zip binary
|
||||
*.7z binary
|
||||
*.gz binary
|
||||
*.tar binary
|
||||
*.exe binary
|
||||
# END playbook .gitattributes
|
||||
|
|
|
|||
|
|
@ -0,0 +1,19 @@
|
|||
# AGENTS (Repository Rules)
|
||||
|
||||
This repository vendors the **playbook** standards snapshot under:
|
||||
|
||||
- `docs/standards/playbook/`
|
||||
|
||||
Sync language rulesets into the repo root via:
|
||||
|
||||
- `sh docs/standards/playbook/scripts/sync_standards.sh cpp` (C++)
|
||||
- `sh docs/standards/playbook/scripts/sync_standards.sh tsl` (TSL)
|
||||
- `sh docs/standards/playbook/scripts/sync_standards.sh python` (Python)
|
||||
|
||||
When working on C++ code, follow the generated ruleset entry:
|
||||
|
||||
- `.agents/cpp/index.md`
|
||||
|
||||
Human-facing standards snapshot (vendored):
|
||||
|
||||
- `docs/standards/playbook/docs/`
|
||||
|
|
@ -0,0 +1,23 @@
|
|||
# AGENTS (lsp-server)
|
||||
|
||||
## Scope
|
||||
|
||||
This directory tree (`lsp-server/`) contains the C++ codebase for the LSP server.
|
||||
|
||||
## Rules
|
||||
|
||||
- Follow the repository C++ agent ruleset: `.agents/cpp/index.md`.
|
||||
- Follow the vendored C++ standards snapshot:
|
||||
- `docs/standards/playbook/docs/cpp/code_style.md`
|
||||
- `docs/standards/playbook/docs/cpp/naming.md`
|
||||
- `docs/standards/playbook/docs/cpp/toolchain.md`
|
||||
|
||||
## Local tooling config
|
||||
|
||||
This project already provides local configs:
|
||||
|
||||
- `lsp-server/.clang-format`
|
||||
- `lsp-server/.clangd`
|
||||
- `lsp-server/CMakeLists.txt`
|
||||
- `lsp-server/CMakeUserPresets.json`
|
||||
- `lsp-server/conanfile.txt`
|
||||
Loading…
Reference in New Issue