tsl-playbook

TSL Playbook：Tinysoft Language（.tsl / .tsf）工程规范与代理规则合集。

目标

• 让代码易读、易维护、易演进。
• 风格保持一致，减少无意义的差异。
• 在不影响清晰度的前提下，尽量简洁。

原则

1. 可读性优先：读代码的时间远大于写代码。
2. 一致性优先：同一仓库内保持一致比追求“最优风格”更重要。
3. 遵从既有代码：修改/扩展现有代码时优先沿用其局部风格。

适用范围

• 本指南适用于所有 TSL 相关仓库与脚本。
• 当现有代码与本指南冲突时，以保持局部一致性为优先，逐步迁移。

docs/（开发规范）

docs/ 目录是给开发者阅读的工程规范，约束代码写法、命名与提交信息。

• docs/index.md：文档导航（跨语言 common / TSL 专属）。
• docs/common/commit_message.md：提交信息与版本号规范（type/scope/subject/body/footer、可选 Emoji 图例、SemVer）。
• docs/tsl/code_style.md：TSL 代码结构、格式、begin/end 代码块、注释与通用最佳实践。
• docs/tsl/naming.md：TSL 命名规范（顶层声明、文件同名规则、变量/成员/property、常量、集合命名等）。

.agents/（代理规则）

.agents/ 目录是给自动化/AI 代理在本仓库内工作时遵守的规则，与 docs/ 并行。

• .agents/index.md：代理规则索引、适用范围与工作原则。
• .agents/auth.md：安全与鉴权边界、敏感信息处理要求。
• .agents/performance.md：性能优化原则、流程与验证要求。
• .agents/code_quality.md：代码质量底线与 review 清单。
• .agents/testing.md：测试策略与何时补测试。

在其他项目中使用本 Playbook

由于本仓库需要内部权限访问，其他项目不能仅用外链引用；推荐把 Playbook 规范 vendoring 到项目内。

方式一：git subtree 同步（推荐）

1. 在目标项目中首次引入：

   git subtree add \
   --prefix docs/standards/tsl \
   https://git.mytsl.cn/csh/tsl-playbook.git \
   main --squash
   

2. 后续同步更新：

   git subtree pull \
   --prefix docs/standards/tsl \
   https://git.mytsl.cn/csh/tsl-playbook.git \
   main --squash
   

3. 目录约定（建议）

   目标项目推荐采用以下结构（Playbook 快照与项目文档分离）：

   .
   ├── .agents/
   │   ├── index.md                   # 多语言代理规则集索引（缺省时由脚本创建）
   │   └── tsl/                       # 从 Playbook 同步（仅覆盖该子目录）
   ├── .gitattributes                 # 从 Playbook 同步
   ├── docs/
   │   ├── standards/
   │   │   └── tsl/                   # git subtree 快照（只读）
   │   │       ├── docs/              # common/ + tsl/
   │   │       ├── .agents/           # 标准代理规则快照
   │   │       ├── .gitattributes
   │   │       └── SOURCE.md          # 记录来源版本/commit（项目自行维护）
   │   └── project/                   # 目标项目自己的文档
   └── README.md                      # 说明遵循 standards
   

   根目录的 .agents/tsl/ 与 .gitattributes 通过同步脚本获得：

   • 直接运行 Playbook 提供的脚本（子树快照里自带）：
   • docs/standards/tsl/scripts/sync_standards.sh（推荐）
   • docs/standards/tsl/scripts/sync_standards.ps1（推荐）
   • docs/standards/tsl/scripts/sync_standards.bat（推荐）
   • 脚本会从快照目录同步到项目根目录，并先备份旧文件（.bak.*）。

   注：docs/standards/tsl/ 只是推荐目录名；你可以用任意 --prefix（例如 docs/standards/tsl_playbook/）。同步脚本会从脚本自身路径推导快照根目录，不再依赖目录名。 注：默认同步到 .agents/tsl/；如需指定规则集名称，可通过环境变量 AGENTS_NS（例如 AGENTS_NS=tsl、AGENTS_NS=common）。

   这样 clone 任意项目时都能直接读取规范文件，不依赖外部访问权限。

方式二：手动复制快照

如果不使用 git subtree，也可以由有权限的人手动复制 Playbook 到目标项目中（适合规范不频繁更新或项目数量较少的情况）。

步骤：

1. 在目标项目创建目录：docs/standards/tsl/。
2. 从本仓库复制以下内容到目标项目：
   • docs/ → docs/standards/tsl/docs/（包含 docs/common/ 与 docs/tsl/）
   • .agents/ → docs/standards/tsl/.agents/
   • .gitattributes → docs/standards/tsl/.gitattributes
   • scripts/ → docs/standards/tsl/scripts/
3. 在目标项目根目录运行同步脚本，把 .agents/tsl/ 与 .gitattributes 落到根目录（见上文脚本路径）。
4. 在 docs/standards/tsl/SOURCE.md 记录本次复制的来源版本/日期（建议写 Playbook 的 commit hash）。

该方式没有自动同步能力，后续更新需重复上述复制流程。

多语言项目落地（TSL + C++/其他语言）

多语言项目建议把规范拆成两类：

1. 仓库级（跨语言）共识：对所有语言都成立的规则与流程。
   • 提交信息：docs/common/commit_message.md
   • 行尾与文本规范：.gitattributes
   • 代理最低要求：.agents/*（工作原则、质量底线、安全边界）
2. 语言级（Language-specific）规范：只对某个语言成立的风格与工具。
   • 例如 TSL 的命名/文件顶层声明限制、C++ 的 .clang-format/.clang-tidy、Python 的 ruff 等。

建议：仓库级规则尽量少且稳定；语言级规则各自独立，避免互相“污染”。

本仓库提供的代理规则集（同步后位于目标项目的 .agents/tsl/）当前全部为跨语言通用规则：

• auth.md：敏感信息/鉴权边界
• code_quality.md：质量底线与 review 清单
• performance.md：性能原则与验证
• testing.md：测试策略

.agents 的覆盖/合并策略（可执行流程）

同步脚本会同步到项目根目录的 .agents/tsl/（并不会覆盖 .agents/ 下的其他语言目录）。若项目需要追加 C++ 等语言/模块专属规则，建议二选一：

1. 推荐：子目录规则覆盖（无需改同步脚本）
   • 让本 Playbook 的规则集固定落在 .agents/tsl/，由同步脚本维护。
   • 在其他语言/模块目录下新增更具体规则，例如 .agents/cpp/、cpp/.agents/、src/.agents/。
2. Overlay 合并：项目维护叠加层并在同步后覆盖回去
   • 约定项目自定义规则放在 docs/project/agents_overlay/（不叫 .agents，避免被同步覆盖）。
   • 每次运行 sync_standards.* 后，再把 overlay 覆盖回 .agents/tsl/（建议封装成项目脚本）。

macOS/Linux 示例（目标项目的 scripts/sync_standards.sh）：

#!/usr/bin/env sh
set -eu

sh docs/standards/tsl/scripts/sync_standards.sh

OVERLAY="docs/project/agents_overlay"
if [ -d "$OVERLAY" ]; then
  cp -R "$OVERLAY"/. ".agents/tsl/"
  echo "Applied agents overlay."
fi

PowerShell 示例（目标项目的 scripts/sync_standards.ps1）：

$ErrorActionPreference = "Stop"

& "docs/standards/tsl/scripts/sync_standards.ps1"

$overlay = "docs/project/agents_overlay"
if (Test-Path $overlay) {
  Copy-Item "$overlay\\*" ".agents\\tsl" -Recurse -Force
  Write-Host "Applied agents overlay."
}

扩展新语言（模板）

当目标项目需要新增一门语言（例如 C++），建议按以下模板扩展：

• 文档：在目标项目增加 docs/standards/cpp/docs/（或另一个标准仓库 subtree），并在项目 README.md/docs/index.md 链接入口。
• 代理规则：在目标项目增加 .agents/cpp/（与 .agents/tsl/ 并行），只写 C++ 专属要求与工具链约束。
• 同步策略：每个规则集只同步到对应子目录（例如 .agents/cpp/），避免覆盖整个 .agents/。
• CI/工具：按文件类型分别执行格式化、lint、测试（不要让 TSL 规则去约束 C++ 代码，反之亦然）。

版本与贡献

• 本项目会持续迭代；变更以 PR 形式提交。
• 新规则需包含动机、示例、迁移建议（如有）。