224 lines
10 KiB
Markdown
224 lines
10 KiB
Markdown
# 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. 在目标项目中首次引入：
|
||
|
||
```bash
|
||
git subtree add \
|
||
--prefix docs/standards/tsl \
|
||
https://git.mytsl.cn/csh/tsl-playbook.git \
|
||
main --squash
|
||
```
|
||
|
||
2. 后续同步更新：
|
||
|
||
```bash
|
||
git subtree pull \
|
||
--prefix docs/standards/tsl \
|
||
https://git.mytsl.cn/csh/tsl-playbook.git \
|
||
main --squash
|
||
```
|
||
|
||
3. 目录约定（建议）
|
||
|
||
目标项目推荐采用以下结构（Playbook 快照与项目文档分离）：
|
||
|
||
```txt
|
||
.
|
||
├── .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 仓库** 内脚本位于 `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=overwrite|block|skip` 控制）
|
||
- 缺省创建：`.agents/index.md`
|
||
- 覆盖前备份：写入同目录的 `*.bak.*`（或 Windows 下随机后缀）
|
||
- 不修改：`.gitignore`（项目自行维护）
|
||
|
||
### 方式二：手动复制快照
|
||
|
||
如果不使用 `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）：
|
||
|
||
```txt
|
||
.
|
||
├── .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`）：
|
||
|
||
```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`）：
|
||
|
||
```powershell
|
||
$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 形式提交。
|
||
- 新规则需包含动机、示例、迁移建议（如有）。
|