113 lines
4.5 KiB
Markdown
113 lines
4.5 KiB
Markdown
# tsl-playbook
|
||
|
||
TSL Playbook：Tinysoft Language（`.tsl` / `.tsf`）工程规范与代理规则合集。
|
||
|
||
## 目标
|
||
|
||
- 让代码**易读、易维护、易演进**。
|
||
- 风格保持一致，减少无意义的差异。
|
||
- 在不影响清晰度的前提下，尽量简洁。
|
||
|
||
## 原则
|
||
|
||
1. **可读性优先**：读代码的时间远大于写代码。
|
||
2. **一致性优先**：同一仓库内保持一致比追求“最优风格”更重要。
|
||
3. **遵从既有代码**：修改/扩展现有代码时优先沿用其局部风格。
|
||
|
||
## 适用范围
|
||
|
||
- 本指南适用于所有 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 同步（推荐）
|
||
|
||
1. 在目标项目中首次引入：
|
||
|
||
```bash
|
||
git subtree add \
|
||
--prefix docs/standards/tsl_playbook \
|
||
https://git.mytsl.cn/csh/tsl-playbook.git \
|
||
main --squash
|
||
```
|
||
|
||
2. 后续同步更新：
|
||
|
||
```bash
|
||
git subtree pull \
|
||
--prefix docs/standards/tsl_playbook \
|
||
https://git.mytsl.cn/csh/tsl-playbook.git \
|
||
main --squash
|
||
```
|
||
|
||
3. 目录约定（建议）
|
||
|
||
目标项目推荐采用以下结构（Playbook 快照与项目文档分离）：
|
||
|
||
```txt
|
||
.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 到目标项目中（适合规范不频繁更新或项目数量较少的情况）。
|
||
|
||
步骤：
|
||
|
||
1. 在目标项目创建目录：`docs/standards/tsl_playbook/`。
|
||
2. 从本仓库复制以下内容到目标项目：
|
||
- `docs/` → `docs/standards/tsl_playbook/docs/`
|
||
- `.agents/` → `docs/standards/tsl_playbook/.agents/`
|
||
- `.gitattributes` → `docs/standards/tsl_playbook/.gitattributes`
|
||
- `scripts/` → `docs/standards/tsl_playbook/scripts/`
|
||
3. 在目标项目根目录运行同步脚本，把 `.agents/` 与 `.gitattributes` 落到根目录（见上文脚本路径）。
|
||
4. 在 `docs/standards/tsl_playbook/SOURCE.md` 记录本次复制的来源版本/日期（建议写 Playbook 的 commit hash）。
|
||
|
||
该方式没有自动同步能力，后续更新需重复上述复制流程。
|
||
|
||
## 版本与贡献
|
||
|
||
- 本项目会持续迭代；变更以 PR 形式提交。
|
||
- 新规则需包含动机、示例、迁移建议（如有）。
|