📦 deps(standards): vendor playbook
This commit is contained in:
@@ -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,11 @@
|
||||
# .agents（多语言规则集快照）
|
||||
|
||||
本目录用于存放 **AI/自动化代理在仓库内工作时必须遵守的规则**。
|
||||
|
||||
本仓库将规则按语言拆分为多个规则集快照：
|
||||
|
||||
- `.agents/tsl/`：TSL 相关规则集（适用于 `.tsl`/`.tsf`）
|
||||
- `.agents/cpp/`：C++ 相关规则集（C++23，含 Modules）
|
||||
- `.agents/python/`：Python 相关规则集
|
||||
|
||||
目标项目落地时，通常通过 `scripts/sync_standards.*` 将某个规则集同步到目标项目根目录的 `.agents/<lang>/`。
|
||||
@@ -0,0 +1,15 @@
|
||||
# 安全与鉴权（Auth & Security）
|
||||
|
||||
本文件定义代理在涉及鉴权/密钥/权限时必须遵守的最低要求（Python）。
|
||||
|
||||
## 基本原则
|
||||
|
||||
- 默认最小权限：避免使用全局管理员/Root 权限完成可在用户权限完成的事。
|
||||
- 不要提交任何密钥材料：token、私钥、证书、访问密钥、`.env` 中的真实值等。
|
||||
- 任何涉及加密/鉴权的实现变更必须说明威胁模型与兼容性影响。
|
||||
|
||||
## 常见风险与要求
|
||||
|
||||
- 输入校验：对外部输入（CLI 参数、环境变量、文件、网络数据）要做类型/范围校验，避免命令注入、路径穿越等问题。
|
||||
- 依赖安全：避免新增“来源不明”的依赖；如必须新增，需说明来源与版本锁定策略。
|
||||
- 日志脱敏：日志中不得输出凭据、个人敏感信息（PII）或可重放的签名/URL。
|
||||
@@ -0,0 +1,27 @@
|
||||
# 代码质量（Code Quality）
|
||||
|
||||
本文件定义代理对代码质量的最低要求与审查清单（Python）。
|
||||
|
||||
## 1. 总体要求
|
||||
|
||||
- 改动聚焦目标；避免“顺手重构”。
|
||||
- API/行为变更要显式说明影响与迁移方式（尤其是脚本/CLI 输出与配置项）。
|
||||
- 保持仓库现有约定：优先复用既有结构、命名与工具配置（见 `docs/python/`）。
|
||||
|
||||
## 2. 可读性
|
||||
|
||||
- 复杂逻辑拆分为具名函数/模块；避免超长函数。
|
||||
- 尽量使用显式类型与数据结构表达意图（必要时补类型标注）。
|
||||
- 注释解释“为什么”，避免注释重复代码表述。
|
||||
|
||||
## 3. 错误处理
|
||||
|
||||
- 失败必须可观测：返回码/异常/日志至少一种要明确。
|
||||
- CLI/自动化脚本：遇到不可恢复错误应非零退出码。
|
||||
|
||||
## 4. Review 清单
|
||||
|
||||
- 是否引入了不必要的新依赖？
|
||||
- 是否遵循 `pyproject.toml` 与 lint 配置？
|
||||
- 是否对 I/O（文件/网络/数据库）失败路径做了处理？
|
||||
- 是否需要补测试或示例？
|
||||
@@ -0,0 +1,40 @@
|
||||
# Python 代理规则集（.agents/python）
|
||||
|
||||
本规则集用于存放 **AI/自动化代理在仓库内工作时必须遵守的规则**（Python 语言专属）。
|
||||
|
||||
## 范围与优先级
|
||||
|
||||
- 作为仓库级基线规则集使用；更靠近代码目录的规则应更具体并可覆盖基线。
|
||||
- 当代理规则与 `docs` 发生冲突时：
|
||||
1. 安全/合规优先
|
||||
2. 其次保持仓库现有一致性
|
||||
|
||||
## 代理工作原则
|
||||
|
||||
- 先理解目标与上下文，再动手改代码。
|
||||
- 修改要小而清晰；避免无关重构。
|
||||
- 不要引入新依赖或工具，除非明确要求。
|
||||
|
||||
## 子文档
|
||||
|
||||
- 安全与鉴权：`auth.md`
|
||||
- 性能：`performance.md`
|
||||
- 代码质量：`code_quality.md`
|
||||
- 测试：`testing.md`
|
||||
|
||||
## Python 必要约定（必须遵守）
|
||||
|
||||
- 代码风格基线：Google Python Style Guide。
|
||||
- 格式化与静态检查：优先使用仓库既有配置（`pyproject.toml`、`.flake8`、`.pylintrc`、`.pre-commit-config.yaml`）；不要在未沟通前切换到另一套工具链。
|
||||
- import 顺序：遵守 `isort profile = google`（若启用）。
|
||||
- 文档字符串：Google 风格（与 `.flake8`/团队约定对齐）。
|
||||
- 命名：遵循 `docs/python/style_guide.md` 中的约定；如与既有代码冲突，以局部一致性优先。
|
||||
|
||||
## 与开发规范的关系
|
||||
|
||||
- 在本仓库内：`docs/python/` 与 `docs/common/`。
|
||||
- 在目标项目内（若按 README 推荐的 subtree prefix `docs/standards/playbook`）：
|
||||
- 代码风格：`docs/standards/playbook/docs/python/style_guide.md`
|
||||
- 工具链：`docs/standards/playbook/docs/python/tooling.md`
|
||||
- 配置说明：`docs/standards/playbook/docs/python/configuration.md`
|
||||
- 提交信息：`docs/standards/playbook/docs/common/commit_message.md`
|
||||
@@ -0,0 +1,15 @@
|
||||
# 性能（Performance）
|
||||
|
||||
本文件定义代理在性能相关改动时的最低要求（Python）。
|
||||
|
||||
## 基本原则
|
||||
|
||||
- 先保证正确性与可读性，再做优化。
|
||||
- 优化前先定位瓶颈：避免盲目微优化。
|
||||
- 对可能影响性能的改动，说明复杂度变化与典型数据规模假设。
|
||||
|
||||
## 常见注意点
|
||||
|
||||
- 避免在热路径重复 I/O（文件读写、网络请求、重复解析）。
|
||||
- 对大列表/大文件处理优先采用流式处理与生成器。
|
||||
- 警惕 `O(n^2)` 循环、重复正则编译、重复 JSON/YAML 解析等。
|
||||
@@ -0,0 +1,13 @@
|
||||
# 测试（Testing）
|
||||
|
||||
本文件定义代理在测试相关工作的最低要求（Python）。
|
||||
|
||||
## 原则
|
||||
|
||||
- 优先增加与变更直接相关的测试（回归测试优先）。
|
||||
- 测试应可重复运行、无顺序依赖、尽量避免真实网络/真实环境依赖。
|
||||
|
||||
## 约定（模板）
|
||||
|
||||
- 若项目使用 `pytest`：遵循 `pyproject.toml` 中的 `pytest.ini_options` 配置。
|
||||
- I/O 相关代码建议使用临时目录与 mock，避免污染工作区。
|
||||
@@ -0,0 +1,33 @@
|
||||
# 安全与鉴权（Auth）
|
||||
|
||||
本文件定义代理在处理鉴权、安全、敏感数据相关任务时的边界与要求。
|
||||
|
||||
## 1. 基本原则
|
||||
|
||||
- **最小权限**：只使用完成任务所需的最低权限与最少数据。
|
||||
- **默认保守**：不确定是否敏感时按敏感处理。
|
||||
- **不扩散秘密**：任何 secret 只在必要范围内出现。
|
||||
|
||||
## 2. 凭证与敏感信息
|
||||
|
||||
- 不要在代码、日志、注释或文档中写入明文密钥、Token、密码。
|
||||
- 如需示例，使用占位符：`<TOKEN>`、`<PASSWORD>`。
|
||||
- 避免把敏感信息打印到标准输出或错误日志。
|
||||
|
||||
## 3. 鉴权逻辑修改
|
||||
|
||||
- 修改鉴权/权限控制时必须说明：
|
||||
- 变更动机
|
||||
- 风险评估
|
||||
- 兼容性/回滚方案
|
||||
- 默认保持旧行为兼容，除非明确要求破坏性变更。
|
||||
|
||||
## 4. 依赖与第三方
|
||||
|
||||
- 禁止无理由新增依赖，尤其是网络、加密、认证相关依赖。
|
||||
- 若必须新增，需在 PR 说明理由、替代方案与安全影响。
|
||||
|
||||
## 5. 审计与合规
|
||||
|
||||
- 任何涉及用户数据/权限边界的改动需可审计：代码清晰、注释说明“为什么”。
|
||||
- 发现潜在安全漏洞时，优先修复或明确标注 `FIXME(name): security risk ...`。
|
||||
@@ -0,0 +1,32 @@
|
||||
# 代码质量（Code Quality）
|
||||
|
||||
本文件定义代理对代码质量的最低要求与审查清单（TSL）。
|
||||
|
||||
## 1. 总体要求
|
||||
|
||||
- 对 `.tsl`/`.tsf` 文件一律按 TSL 规范处理（`.tsf` 也是 TSL 源文件）：遵守标准快照中的 `docs/tsl/code_style.md` 与 `docs/tsl/naming.md`（在目标项目中通常 vendoring 到 `docs/standards/playbook/docs/tsl/`）。
|
||||
- 改动聚焦目标；避免“顺手重构”。
|
||||
- API 变更要显式说明影响与迁移方式。
|
||||
|
||||
## 2. 可读性
|
||||
|
||||
- 复杂逻辑拆分为具名函数/变量。
|
||||
- 避免深层嵌套与重复代码。
|
||||
- 必要注释解释“为什么”而不是“做什么”。
|
||||
|
||||
## 3. 错误处理
|
||||
|
||||
- 错误必须显式处理；禁止静默吞错。
|
||||
- 失败路径要可观测（返回/抛出/日志）。
|
||||
|
||||
## 4. 复杂度与规模
|
||||
|
||||
- 单函数尽量 ≤ 60 行；超过应说明原因或拆分。
|
||||
- 单次 PR 尽量小步提交，便于 review。
|
||||
|
||||
## 5. Review 清单
|
||||
|
||||
- 是否有无关改动？
|
||||
- 是否有清晰的动机与行为说明？
|
||||
- 是否保持模块内风格一致？
|
||||
- 是否需要补测试/示例？
|
||||
@@ -0,0 +1,39 @@
|
||||
# TSL 代理规则集（.agents/tsl）
|
||||
|
||||
本规则集用于存放 **AI/自动化代理在仓库内工作时必须遵守的规则**（TSL 语言专属）。
|
||||
|
||||
## 范围与优先级
|
||||
|
||||
- 作为仓库级基线规则集使用；更靠近代码目录的规则应更具体并可覆盖基线。
|
||||
- 当代理规则与 `docs` 发生冲突时：
|
||||
1. 安全/合规优先
|
||||
2. 其次保持仓库现有一致性
|
||||
|
||||
## 代理工作原则
|
||||
|
||||
- 先理解目标与上下文，再动手改代码。
|
||||
- 修改要小而清晰；避免无关重构。
|
||||
- 任何可能影响行为的改动都要补充或更新测试/示例（若项目有测试体系）。
|
||||
- 不要引入新依赖或工具，除非明确要求。
|
||||
|
||||
## 子文档
|
||||
|
||||
- 安全与鉴权：`auth.md`
|
||||
- 性能：`performance.md`
|
||||
- 代码质量：`code_quality.md`
|
||||
- 测试：`testing.md`
|
||||
|
||||
## TSL/TSF 必要约定（必须遵守）
|
||||
|
||||
- `.tsl` 与 `.tsf` 都是 Tinysoft Language 源文件；修改它们时统一按 TSL 规范处理（不要把 `.tsf` 当成“另一种语言/无风格约束的脚本”）。
|
||||
- 文件级约束：一个文件只能有一个顶层声明，且文件基名必须与该顶层声明同名（推荐 `PascalCase`）；`.tsl` 顶层声明只能是 `function`。
|
||||
- 格式：空格缩进（默认 4 空格），关键字用小写，复杂分支/多语句分支用 `begin/end` 块表达结构。
|
||||
- 命名：类型/顶层函数/property 用 `PascalCase`；局部变量/参数用 `snake_case`；私有成员变量用 `snake_case_`。
|
||||
|
||||
## 与开发规范的关系
|
||||
|
||||
- 在本仓库内：`docs/tsl/` 与 `docs/common/`。
|
||||
- 在目标项目内（若按 README 推荐的 subtree prefix `docs/standards/playbook`）：
|
||||
- 代码风格：`docs/standards/playbook/docs/tsl/code_style.md`
|
||||
- 命名规范：`docs/standards/playbook/docs/tsl/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. 运行与失败处理
|
||||
|
||||
- 本仓库未来若引入测试命令，需在此补充统一的运行方式。
|
||||
- 测试失败时优先定位改动相关原因，不修无关失败。
|
||||
Reference in New Issue
Block a user