4.5 KiB

Raw Blame History

tsl-playbook

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

目标

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

原则

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

适用范围

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

docs/（开发规范）

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

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

.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 同步（推荐）

在目标项目中首次引入：

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

后续同步更新：

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

目录约定（建议）

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

.agents/                          # 从 Playbook 同步后可按项目微调
.gitattributes                    # 从 Playbook 同步
docs/
standards/
    tsl_playbook/                 # git subtree 快照（只读）
    docs/                       # code_style.md / naming.md / commit_message.md
    .agents/                    # 标准代理规则快照
    .gitattributes
    SOURCE.md                   # 记录来源版本/commit（项目自行维护）
project/                        # 目标项目自己的文档
README.md                         # 说明遵循 standards

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

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

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

方式二：手动复制快照

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

步骤：

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

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

版本与贡献

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

4.5 KiB Raw Blame History Unescape Escape