📦 deps(playbook): sync rules, prompts, memory-bank
This commit is contained in:
@@ -1,33 +0,0 @@
|
||||
# 安全与鉴权（Auth）
|
||||
|
||||
本文件定义代理在处理鉴权、安全、敏感数据相关任务时的边界与要求。
|
||||
|
||||
## 1. 基本原则
|
||||
|
||||
- **最小权限**：只使用完成任务所需的最低权限与最少数据。
|
||||
- **默认保守**：不确定是否敏感时按敏感处理。
|
||||
- **不扩散秘密**：任何 secret 只在必要范围内出现。
|
||||
|
||||
## 2. 凭证与敏感信息
|
||||
|
||||
- 不要在代码、日志、注释或文档中写入明文密钥、Token、密码。
|
||||
- 如需示例，使用占位符：`<TOKEN>`、`<PASSWORD>`。
|
||||
- 避免把敏感信息打印到标准输出或错误日志。
|
||||
|
||||
## 3. 鉴权逻辑修改
|
||||
|
||||
- 修改鉴权/权限控制时必须说明：
|
||||
- 变更动机
|
||||
- 风险评估
|
||||
- 兼容性/回滚方案
|
||||
- 默认保持旧行为兼容，除非明确要求破坏性变更。
|
||||
|
||||
## 4. 依赖与第三方
|
||||
|
||||
- 禁止无理由新增依赖，尤其是网络、加密、认证相关依赖。
|
||||
- 若必须新增，需在 PR 说明理由、替代方案与安全影响。
|
||||
|
||||
## 5. 审计与合规
|
||||
|
||||
- 任何涉及用户数据/权限边界的改动需可审计：代码清晰、注释说明“为什么”。
|
||||
- 发现潜在安全漏洞时，优先修复或明确标注 `FIXME(name): security risk ...`。
|
||||
@@ -1,37 +0,0 @@
|
||||
# 代码质量（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 清单
|
||||
|
||||
- 是否有无关改动？
|
||||
- 是否保持模块内风格一致？
|
||||
- 是否引入不必要的复杂度/依赖？
|
||||
- 是否有最小验证（构建/冒烟）步骤？
|
||||
+34
-34
@@ -1,47 +1,47 @@
|
||||
# C++ 代理规则集（.agents/cpp）
|
||||
# C++ 代理规则集
|
||||
|
||||
本规则集用于存放 **AI/自动化代理在仓库内工作时必须遵守的规则**（C++ 语言专属）。
|
||||
本规则集定义 AI/自动化代理在处理 C++ 代码时必须遵守的核心约束。
|
||||
|
||||
## 范围与优先级
|
||||
|
||||
- 作为仓库级基线规则集使用；更靠近代码目录的规则应更具体并可覆盖基线。
|
||||
- 当代理规则与 `docs` 发生冲突时：
|
||||
1. 安全/合规优先
|
||||
2. 其次保持仓库现有一致性
|
||||
- 作为仓库级基线规则集使用；更靠近代码目录的规则更具体并可覆盖基线。
|
||||
- 当代理规则与 docs 冲突：安全/合规优先，其次保持仓库一致性。
|
||||
|
||||
## 代理工作原则
|
||||
## 代理工作原则（铁律）
|
||||
|
||||
- 先理解目标与上下文，再动手改代码。
|
||||
- 修改要小而清晰；避免无关重构。
|
||||
- 不要引入新依赖或工具，除非明确要求。
|
||||
1. 先理解目标与上下文，再动手改代码
|
||||
2. 修改要小而清晰；避免无关重构
|
||||
3. 发现安全问题（内存安全/鉴权漏洞）立即标注或修复
|
||||
4. 不引入新依赖或工具，除非明确要求
|
||||
|
||||
## 子文档
|
||||
## C++ 核心约定（不可违反）
|
||||
|
||||
- 安全与鉴权：`auth.md`
|
||||
- 性能：`performance.md`
|
||||
- 代码质量：`code_quality.md`
|
||||
- 测试：`testing.md`
|
||||
- 语言标准：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 交叉编译验证
|
||||
|
||||
## 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`。
|
||||
- 不得在代码/日志/注释中写入明文密钥、密码、Token、API Key
|
||||
- 避免内存不安全操作：悬垂指针、双重释放、越界访问
|
||||
- 禁用不安全函数（`strcpy`, `sprintf`, `gets` 等）
|
||||
- 修改鉴权/权限逻辑必须说明动机与风险
|
||||
|
||||
## 权威来源
|
||||
|
||||
- 代码风格：`docs/standards/playbook/docs/cpp/code_style.md`
|
||||
- 命名规范：`docs/standards/playbook/docs/cpp/naming.md`
|
||||
- 工具链：`docs/standards/playbook/docs/cpp/toolchain.md`
|
||||
- 依赖管理：`docs/standards/playbook/docs/cpp/dependencies_conan.md`
|
||||
- clangd 配置：`docs/standards/playbook/docs/cpp/clangd.md`
|
||||
|
||||
## Skills（按需加载）
|
||||
|
||||
- `$commit-message`
|
||||
|
||||
## 与开发规范的关系
|
||||
|
||||
- 在本仓库内：`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`
|
||||
- 本仓库内：`docs/standards/playbook/docs/cpp/` 与 `docs/standards/playbook/docs/common/`
|
||||
- 目标项目 subtree：`docs/standards/playbook/docs/cpp/` 与 `docs/standards/playbook/docs/common/`
|
||||
|
||||
@@ -1,31 +0,0 @@
|
||||
# 性能（Performance）
|
||||
|
||||
本文件定义代理在做性能相关改动时的准则与检查项。
|
||||
|
||||
## 1. 目标与度量
|
||||
|
||||
- 明确性能目标：延迟、吞吐、内存、CPU、I/O 等。
|
||||
- 没有指标时不要盲目优化；先补充测量或基准。
|
||||
|
||||
## 2. 处理流程
|
||||
|
||||
1. 先定位瓶颈（profile/trace/log）。
|
||||
2. 再提出最小化改动方案。
|
||||
3. 最后用数据验证收益与副作用。
|
||||
|
||||
## 3. 优化准则
|
||||
|
||||
- 优先消除算法/结构性问题，再考虑微优化。
|
||||
- 避免引入复杂度换取小收益。
|
||||
- 性能优化不应牺牲可读性；必要时加注释说明权衡。
|
||||
|
||||
## 4. 常见风险
|
||||
|
||||
- 避免重复计算、无界缓存、隐式复制。
|
||||
- 注意热路径中的分配与 I/O。
|
||||
- 并发优化要考虑正确性与可测试性。
|
||||
|
||||
## 5. 验证
|
||||
|
||||
- 提供优化前后可复现的对比数据（基准、采样结果或压测报告）。
|
||||
- 若无测试体系，至少提供最小可运行的复现脚本/步骤。
|
||||
@@ -1,26 +0,0 @@
|
||||
# 测试（Testing）
|
||||
|
||||
本文件定义代理在改动代码时的测试策略与要求。
|
||||
|
||||
## 1. 测试层级
|
||||
|
||||
- **单元测试**：验证函数/模块的独立行为。
|
||||
- **集成测试**：验证模块间交互与关键流程。
|
||||
- **回归测试**：防止已修复问题复发。
|
||||
|
||||
## 2. 何时补测试
|
||||
|
||||
- 新功能必须新增对应测试（若项目有测试体系）。
|
||||
- 修复 bug 必须先写/补回归用例（若项目有测试体系）。
|
||||
- 仅当改动纯文档/注释/格式时可不加测试。
|
||||
|
||||
## 3. 测试可维护性
|
||||
|
||||
- 一个用例只验证一个行为点。
|
||||
- 测试命名清晰，能从名字看出期望。
|
||||
- 避免依赖外部不稳定资源；必要时 mock/stub。
|
||||
|
||||
## 4. 运行与失败处理
|
||||
|
||||
- 若项目提供构建/冒烟命令（CMake），优先保证最小构建可通过。
|
||||
- 失败时优先定位改动相关原因，不修无关失败。
|
||||
@@ -0,0 +1,44 @@
|
||||
# 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/standards/playbook/docs/tsl/syntax_book/index.md`
|
||||
- 函数库：`docs/standards/playbook/docs/tsl/syntax_book/function/`（按需检索，禁止整份加载）
|
||||
- 代码风格：`docs/standards/playbook/docs/tsl/code_style.md`
|
||||
- 命名规范：`docs/standards/playbook/docs/tsl/naming.md`
|
||||
|
||||
## Skills（按需加载）
|
||||
|
||||
- `$tsl-guide`
|
||||
- `$commit-message`
|
||||
|
||||
## 与开发规范的关系
|
||||
|
||||
- 本仓库内：`docs/standards/playbook/docs/tsl/` 与 `docs/standards/playbook/docs/common/`
|
||||
- 目标项目 subtree：`docs/standards/playbook/docs/tsl/` 与 `docs/standards/playbook/docs/common/`
|
||||
Reference in New Issue
Block a user