2.9 KiB
2.9 KiB
TSL Playbook 代理规则集（.agents/tsl）
本规则集用于存放 AI/自动化代理在仓库内工作时必须遵守的规则。
在多语言项目中，推荐将本规则集放在目标项目的 .agents/tsl/ 下（由 scripts/sync_standards.* 同步），并与其他语言规则集并行：
.agents/tsl/：TSL 标准规则集（本仓库提供）.agents/cpp/、.agents/python/等：其他语言规则集（按需新增）
这些规则与 docs/ 下的人类开发规范并行：
docs/：给人看的编码/命名/提交规范.agents/：给代理看的任务边界、质量与安全要求
范围与优先级
- 作为仓库级基线规则集使用；更靠近代码目录的规则应更具体并可覆盖基线。
- 当代理规则与
docs发生冲突时：- 安全/合规优先
- 其次保持仓库现有一致性
代理工作原则
- 先理解目标与上下文，再动手改代码。
- 修改要小而清晰；避免无关重构。
- 任何可能影响行为的改动都要补充或更新测试/示例（若项目有测试体系）。
- 不要引入新依赖或工具，除非明确要求。
子文档
- 安全与鉴权：
auth.md - 性能：
performance.md - 代码质量：
code_quality.md - 测试：
testing.md
分类（本仓库现状）
当前本规则集下的文件以 跨语言通用规则 为主（不绑定具体语言语法/工具链），但包含 TSL 代码在仓库里最容易踩坑的“语言级硬约束”，以避免代理在缺少上下文时写出不符合 TSL/TSF 约定的代码。
auth.md：敏感信息/鉴权边界code_quality.md：质量底线与 review 清单performance.md：性能原则与验证testing.md：测试策略
若项目需要更细的语言/模块专属代理要求，建议在更靠近源码的目录放置更具体的规则（例如 src/.agents/），或并行新增其他规则集（例如 .agents/cpp/）。
TSL/TSF 必要约定（必须遵守）
.tsl与.tsf都是 Tinysoft Language 源文件；修改它们时统一按 TSL 规范处理（不要把.tsf当成“另一种语言/无风格约束的脚本”）。- 文件级约束：一个文件只能有一个顶层声明，且文件基名必须与该顶层声明同名（推荐
PascalCase）；.tsl顶层声明只能是function。 - 格式：空格缩进（默认 4 空格），关键字用小写，复杂分支/多语句分支用
begin/end块表达结构。 - 命名：类型/顶层函数/property 用
PascalCase；局部变量/参数用snake_case；私有成员变量用snake_case_。
与开发规范的关系
- 在本仓库内：
docs/tsl/与docs/common/。 - 在目标项目内：标准快照应 vendoring 到
docs/standards/tsl/，对应路径为：- 代码风格：
docs/standards/tsl/docs/tsl/code_style.md - 命名规范：
docs/standards/tsl/docs/tsl/naming.md - 提交信息：
docs/standards/tsl/docs/common/commit_message.md
- 代码风格：