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
   

快速落地（最小 4 步）

在目标项目中按以下顺序执行即可完成落地（推荐固定使用 --prefix docs/standards/tsl）：

1. 引入标准快照（见上文 git subtree add）

2. 同步到项目根目录（生成/更新 .agents/tsl/、更新 .gitattributes）：

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

3. 验收（任意满足其一即可）：

   • 目录存在：.agents/tsl/
   • 规则入口可读：.agents/tsl/index.md
   • 标准文档可读：docs/standards/tsl/docs/index.md
   • .gitattributes 包含区块：# BEGIN tsl-playbook .gitattributes / # END tsl-playbook .gitattributes

4. 将同步产物纳入版本控制（目标项目建议提交）：

   • docs/standards/tsl/（标准快照）
   • .agents/tsl/（落地规则集）
   • .gitattributes（managed block 更新）

可选：项目包装脚本（多 playbook 串联）

多语言项目建议在目标项目创建一个包装脚本（便于一键同步多个规则集）：

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

sh docs/standards/tsl/scripts/sync_standards.sh
# sh docs/standards/python/scripts/sync_standards.sh
# sh docs/standards/cpp/scripts/sync_standards.sh

目录约定（建议）

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

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

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

• 说明：在 本 playbook 仓库 内脚本位于 scripts/；在 目标项目 里通过 git subtree 引入到 docs/standards/tsl/ 后，脚本路径变为 docs/standards/tsl/scripts/。
• 在目标项目里直接运行 Playbook 提供的脚本（子树快照里自带）：
• docs/standards/tsl/scripts/sync_standards.sh（推荐）
• docs/standards/tsl/scripts/sync_standards.ps1（推荐）
• docs/standards/tsl/scripts/sync_standards.bat（推荐）
• 脚本会从快照目录同步到项目根目录，并先备份旧文件（.bak.*）。

注：建议固定使用 --prefix docs/standards/tsl，因为同步后的 .agents/tsl/ 会引用该路径下的标准快照文档（docs/standards/tsl/docs/...）。 注：默认同步到 .agents/tsl/；如需指定规则集名称，可通过环境变量 AGENTS_NS（例如 AGENTS_NS=tsl、AGENTS_NS=common）。

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

同步脚本行为（目标项目内的最终落地内容）：

• 覆盖/更新：.agents/<AGENTS_NS>/（默认 .agents/tsl/）
• 更新 .gitattributes：默认只维护 # BEGIN tsl-playbook .gitattributes 区块（可用 SYNC_GITATTR_MODE=block|overwrite|skip 控制）
• 缺省创建：.agents/index.md
• 覆盖前备份：写入同目录的 *.bak.*（或 Windows 下随机后缀）
• 不修改：.gitignore（项目自行维护）

环境变量（可选）

同步脚本支持以下可选环境变量（默认值可满足大多数项目）：

变量名	默认值	说明
AGENTS_NS	tsl	规则集落地目录名：.agents/<AGENTS_NS>/
SYNC_GITATTR_MODE	block	.gitattributes 同步模式：block 仅维护 managed 区块；overwrite 全量覆盖；skip 不更新

方式二：手动复制快照

如果不使用 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/）以跨语言通用规则为主，但包含 TSL/TSF 文件（.tsl/.tsf）的必要约定（避免代理在缺少上下文时写出不符合 TSL 约束的代码）：

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

多语言项目推荐结构（示例：TSL + C++ + Python）：

.
├── .agents/
│   ├── index.md                      # 多语言索引（缺省时由脚本创建）
│   ├── tsl/                          # 由本 Playbook 同步（适用于 .tsl/.tsf）
│   ├── cpp/                          # C++ 规则集（来自另一个 playbook 或项目自建）
│   └── python/                       # Python 规则集（同上）
├── .gitattributes                    # 行尾/文本规范（可由某个 playbook 同步）
├── docs/
│   ├── standards/
│   │   ├── tsl/                      # 本 Playbook 快照（git subtree/vendoring）
│   │   ├── cpp/                      # C++ playbook 快照（可选）
│   │   └── python/                   # Python playbook 快照（可选）
│   └── project/                      # 项目自有文档（架构、ADR、运行方式等）
├── scripts/
│   └── sync_standards.sh             # 项目包装脚本：依次调用各 playbook 的 sync
└── src/                              # 源码目录（按项目实际情况）

规则优先级建议：

• 同一项目内多个规则集并行放在 .agents/<lang>/，不要互相覆盖。
• 若某个子目录需要更具体规则（模块/子系统差异），在更靠近代码的目录放置更具体规则（例如 src/foo/.agents/），并以“离代码更近者优先”为准。

.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 形式提交。
• 新规则需包含动机、示例、迁移建议（如有）。