csh/playbook
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

📝 docs(playbook): add contributing and multi-language standards

Browse Source 
Introduce C++ and Python docs/templates and split .agents rulesets by language (tsl/cpp/python).

Move commit message guidance to CONTRIBUTING.md (full spec remains in docs/common/commit_message.md).
This commit is contained in:
csh
2025-12-14 17:32:50 +08:00
parent 380228caca
commit e504a689dc
47 changed files with 1521 additions and 162 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+80 -52
View File
@@ -1,6 +1,6 @@
# tsl-playbook
# playbook
TSL Playbook：Tinysoft Language（`.tsl` / `.tsf`）工程规范与代理规则合集。
Playbook：TSL（`.tsl`/`.tsf`）+ C++ + Python 工程规范与代理规则合集。
## 目标
@@ -23,20 +23,29 @@ TSL Playbook：Tinysoft Language（`.tsl` / `.tsf`）工程规范与代理规则
`docs/` 目录是给开发者阅读的工程规范，约束代码写法、命名与提交信息。
- `docs/index.md`：文档导航（跨语言 common / TSL 专属）。
- `docs/index.md`：文档导航（跨语言 common / TSL / C++ / Python）。
- `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、常量、集合命名等）。
- `docs/tsl/toolchain.md`：TSL 工具链与验证命令模板。
- `docs/cpp/code_style.md`：C++ 代码风格（C++23/Modules）。
- `docs/cpp/naming.md`：C++ 命名规范（Google 基线）。
- `docs/cpp/toolchain.md`：C++ 工具链与验证命令模板。
- `docs/cpp/dependencies_conan.md`：C++ Conan 依赖管理建议。
- `docs/cpp/clangd.md`：clangd 补全配置建议（`.clangd`）。
- `docs/python/style_guide.md`：Python 代码风格（Google 基线）。
- `docs/python/tooling.md`：Python 工具链（black/isort/flake8/pylint/mypy/pytest/pre-commit）。
- `docs/python/configuration.md`：Python 配置清单（落地时从 `templates/python/` 复制到项目根目录）。
- `templates/cpp/`：C++ 落地模板（`.clang-format`、`conanfile.txt`、`CMakeUserPresets.json`、`CMakeLists.txt`）。
- `templates/python/`：Python 落地模板（`pyproject.toml` 工具配置、`.flake8`、`.pylintrc`、`.pre-commit-config.yaml`、`.editorconfig`、`.vscode/settings.json`）。
## .agents/（代理规则）
`.agents/` 目录是给自动化/AI 代理在本仓库内工作时遵守的规则，与 `docs/` 并行。
`.agents/` 目录是给自动化/AI 代理在本仓库内工作时遵守的规则快照，与 `docs/` 并行。
- `.agents/index.md`：代理规则索引、适用范围与工作原则。
- `.agents/auth.md`：安全与鉴权边界、敏感信息处理要求。
- `.agents/performance.md`：性能优化原则、流程与验证要求。
- `.agents/code_quality.md`：代码质量底线与 review 清单。
- `.agents/testing.md`：测试策略与何时补测试。
- `.agents/index.md`：规则集索引（多语言）。
- `.agents/tsl/`：TSL 规则集（入口：`.agents/tsl/index.md`）。
- `.agents/cpp/`：C++ 规则集（入口：`.agents/cpp/index.md`）。
## 在其他项目中使用本 Playbook
@@ -48,8 +57,8 @@ TSL Playbook：Tinysoft Language（`.tsl` / `.tsf`）工程规范与代理规则
```bash
git subtree add \
--prefix docs/standards/tsl \
https://git.mytsl.cn/csh/tsl-playbook.git \
--prefix docs/standards/playbook \
https://git.mytsl.cn/csh/playbook.git \
main --squash
```
@@ -57,31 +66,44 @@ TSL Playbook：Tinysoft Language（`.tsl` / `.tsf`）工程规范与代理规则
```bash
git subtree pull \
--prefix docs/standards/tsl \
https://git.mytsl.cn/csh/tsl-playbook.git \
--prefix docs/standards/playbook \
https://git.mytsl.cn/csh/playbook.git \
main --squash
```
#### 快速落地（最小 4 步）
在目标项目中按以下顺序执行即可完成落地（推荐固定使用 `--prefix docs/standards/tsl`）：
在目标项目中按以下顺序执行即可完成落地（推荐固定使用 `--prefix docs/standards/playbook`）：
1. 引入标准快照（见上文 `git subtree add`）
2. 同步到项目根目录（生成/更新 `.agents/tsl/`、更新 `.gitattributes`）：
2. 同步到项目根目录（生成/更新 `.agents/<lang>/`、更新 `.gitattributes`）：
```bash
sh docs/standards/tsl/scripts/sync_standards.sh
sh docs/standards/playbook/scripts/sync_standards.sh
```
同步 C++ 规则集（同一份快照，不同规则集）：
```bash
sh docs/standards/playbook/scripts/sync_standards.sh cpp
```
一次同步多个规则集（推荐，减少重复备份 `.gitattributes`）：
```bash
sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp
```
3. 验收（任意满足其一即可）：
- 目录存在：`.agents/tsl/`
- 规则入口可读：`.agents/tsl/index.md`
- 标准文档可读：`docs/standards/tsl/docs/index.md`
- `.gitattributes` 包含区块：`# BEGIN tsl-playbook .gitattributes` / `# END tsl-playbook .gitattributes`
- （可选）C++ 规则入口可读：`.agents/cpp/index.md`
- 标准文档可读：`docs/standards/playbook/docs/index.md`
- `.gitattributes` 包含区块：`# BEGIN playbook .gitattributes` / `# END playbook .gitattributes`
4. 将同步产物纳入版本控制（目标项目建议提交）：
- `docs/standards/tsl/`（标准快照）
- `docs/standards/playbook/`（标准快照）
- `.agents/tsl/`（落地规则集）
- `.gitattributes`（managed block 更新）
@@ -93,9 +115,14 @@ TSL Playbook：Tinysoft Language（`.tsl` / `.tsf`）工程规范与代理规则
#!/usr/bin/env sh
set -eu
sh docs/standards/tsl/scripts/sync_standards.sh
sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp
# sh docs/standards/python/scripts/sync_standards.sh
# sh docs/standards/cpp/scripts/sync_standards.sh
```
也可以直接一次同步多个规则集：
```sh
sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp
```
#### 目录约定（建议）
@@ -106,12 +133,13 @@ sh docs/standards/tsl/scripts/sync_standards.sh
.
├── .agents/
│ ├── index.md # 多语言代理规则集索引（缺省时由脚本创建）
│ └── tsl/ # 从 Playbook 同步（仅覆盖该子目录）
│ ├── tsl/ # 从 Playbook 同步（仅覆盖该子目录）
│ └── cpp/ # 从 Playbook 同步（仅覆盖该子目录，按需）
├── .gitattributes # 从 Playbook 同步
├── docs/
│ ├── standards/
│ │ └── tsl/ # git subtree 快照（只读）
│ │ ├── docs/ # common/ + tsl/
│ │ ├── docs/ # common/ + tsl/ + cpp/
│ │ ├── .agents/ # 标准代理规则快照
│ │ ├── .gitattributes
│ │ └── SOURCE.md # 记录来源版本/commit（项目自行维护）
@@ -119,24 +147,24 @@ sh docs/standards/tsl/scripts/sync_standards.sh
└── README.md # 说明遵循 standards
```
根目录的 `.agents/tsl/` 与 `.gitattributes` 通过同步脚本获得：
根目录的 `.agents/<lang>/` 与 `.gitattributes` 通过同步脚本获得：
- 说明：在 **本 playbook 仓库** 内脚本位于 `scripts/`；在 **目标项目** 里通过 `git subtree` 引入到 `docs/standards/tsl/` 后，脚本路径变为 `docs/standards/tsl/scripts/`。
- 说明：在 **本 playbook 仓库** 内脚本位于 `scripts/`；在 **目标项目** 里通过 `git subtree` 引入到 `docs/standards/playbook/` 后，脚本路径变为 `docs/standards/playbook/scripts/`。
- 在目标项目里直接运行 Playbook 提供的脚本（子树快照里自带）：
- `docs/standards/tsl/scripts/sync_standards.sh`（推荐）
- `docs/standards/tsl/scripts/sync_standards.ps1`（推荐）
- `docs/standards/tsl/scripts/sync_standards.bat`（推荐）
- `docs/standards/playbook/scripts/sync_standards.sh`（推荐，支持多语言参数）
- `docs/standards/playbook/scripts/sync_standards.ps1`（推荐，支持多语言参数）
- `docs/standards/playbook/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`）。
注：建议固定使用 `--prefix docs/standards/playbook`，因为同步后的 `.agents/*/` 会引用该路径下的标准快照文档（`docs/standards/playbook/docs/...`）。
注：默认同步到 `.agents/tsl/`；如需同步 C++ 规则集，推荐直接运行：`sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp`。
这样 clone 任意项目时都能直接读取规范文件，不依赖外部访问权限。
同步脚本行为（目标项目内的最终落地内容）：
- 覆盖/更新：`.agents/<AGENTS_NS>/`（默认 `.agents/tsl/`）
- 更新 `.gitattributes`：默认只维护 `# BEGIN tsl-playbook .gitattributes` 区块（可用 `SYNC_GITATTR_MODE=block|overwrite|skip` 控制）
- 更新 `.gitattributes`：默认只维护 `# BEGIN playbook .gitattributes` 区块（可用 `SYNC_GITATTR_MODE=block|overwrite|skip` 控制）
- 缺省创建：`.agents/index.md`
- 覆盖前备份：写入同目录的 `*.bak.*`（或 Windows 下随机后缀）
- 不修改：`.gitignore`（项目自行维护）
@@ -147,7 +175,7 @@ sh docs/standards/tsl/scripts/sync_standards.sh
| 变量名 | 默认值 | 说明 |
| ------------------- | ------- | ------------------------------------------------------------------------------------------- |
| `AGENTS_NS` | `tsl` | 规则集落地目录名：`.agents/<AGENTS_NS>/` |
| `AGENTS_NS` | `tsl` | 同步的规则集名/落地目录名：`.agents/<AGENTS_NS>/`（例如 `tsl`、`cpp`） |
| `SYNC_GITATTR_MODE` | `block` | `.gitattributes` 同步模式：`block` 仅维护 managed 区块；`overwrite` 全量覆盖；`skip` 不更新 |
### 方式二：手动复制快照
@@ -156,14 +184,14 @@ sh docs/standards/tsl/scripts/sync_standards.sh
步骤：
1. 在目标项目创建目录：`docs/standards/tsl/`。
1. 在目标项目创建目录：`docs/standards/playbook/`。
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/`
- `docs/` → `docs/standards/playbook/docs/`（包含 `docs/common/`、`docs/tsl/`、`docs/cpp/`、`docs/python/`）
- `.agents/` → `docs/standards/playbook/.agents/`
- `.gitattributes` → `docs/standards/playbook/.gitattributes`
- `scripts/` → `docs/standards/playbook/scripts/`
3. 在目标项目根目录运行同步脚本，把 `.agents/tsl/` 与 `.gitattributes` 落到根目录（见上文脚本路径）。
4. 在 `docs/standards/tsl/SOURCE.md` 记录本次复制的来源版本/日期（建议写 Playbook 的 commit hash）。
4. 在 `docs/standards/playbook/SOURCE.md` 记录本次复制的来源版本/日期（建议写 Playbook 的 commit hash）。
该方式没有自动同步能力，后续更新需重复上述复制流程。
@@ -180,12 +208,10 @@ sh docs/standards/tsl/scripts/sync_standards.sh
建议：仓库级规则尽量少且稳定；语言级规则各自独立，避免互相“污染”。
本仓库提供的代理规则集（同步后位于目标项目的 `.agents/tsl/`）以**跨语言通用规则**为主，但包含 TSL/TSF 文件（`.tsl`/`.tsf`）的必要约定（避免代理在缺少上下文时写出不符合 TSL 约束的代码）：
本仓库提供两套代理规则集（同步后位于目标项目的 `.agents/tsl/` 与 `.agents/cpp/`）：
- `auth.md`：敏感信息/鉴权边界
- `code_quality.md`：质量底线与 review 清单
- `performance.md`：性能原则与验证
- `testing.md`：测试策略
- 两者都包含跨语言通用底线：`auth.md`、`code_quality.md`、`performance.md`、`testing.md`
- 并在 `index.md` 中叠加语言级“硬约束”（TSL/TSF 语法限制、C++23/Modules、Windows 支持等）
多语言项目推荐结构（示例：TSL + C++ + Python）：
@@ -194,13 +220,12 @@ sh docs/standards/tsl/scripts/sync_standards.sh
├── .agents/
│ ├── index.md # 多语言索引（缺省时由脚本创建）
│ ├── tsl/ # 由本 Playbook 同步（适用于 .tsl/.tsf）
│ ├── cpp/ # C++ 规则集（来自另一个 playbook 或项目自建）
│ ├── cpp/ # 由本 Playbook 同步（适用于 C++23/Modules）
│ └── python/ # Python 规则集（同上）
├── .gitattributes # 行尾/文本规范（可由某个 playbook 同步）
├── docs/
│ ├── standards/
│ │ ├── tsl/ # 本 Playbook 快照（git subtree/vendoring）
│ │ ├── cpp/ # C++ playbook 快照（可选）
│ │ ├── tsl/ # 本 Playbook 快照（git subtree/vendoring；包含 common/tsl/cpp）
│ │ └── python/ # Python playbook 快照（可选）
│ └── project/ # 项目自有文档（架构、ADR、运行方式等）
├── scripts/
@@ -230,7 +255,7 @@ macOS/Linux 示例（目标项目的 `scripts/sync_standards.sh`）：
#!/usr/bin/env sh
set -eu
sh docs/standards/tsl/scripts/sync_standards.sh
sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp
OVERLAY="docs/project/agents_overlay"
if [ -d "$OVERLAY" ]; then
@@ -242,9 +267,7 @@ fi
PowerShell 示例（目标项目的 `scripts/sync_standards.ps1`）：
```powershell
$ErrorActionPreference = "Stop"
& "docs/standards/tsl/scripts/sync_standards.ps1"
& "docs/standards/playbook/scripts/sync_standards.ps1" -Langs tsl,cpp
$overlay = "docs/project/agents_overlay"
if (Test-Path $overlay) {
@@ -257,10 +280,15 @@ if (Test-Path $overlay) {
当目标项目需要新增一门语言（例如 C++），建议按以下模板扩展：
- 文档：在目标项目增加 `docs/standards/cpp/docs/`（或另一个标准仓库 subtree），并在项目 `README.md`/`docs/index.md` 链接入口。
- 代理规则：在目标项目增加 `.agents/cpp/`（与 `.agents/tsl/` 并行），只写 C++ 专属要求与工具链约束。
- 文档：
- 若使用本 Playbook 自带的 C++ 规范：无需额外 subtree，直接使用 `docs/standards/playbook/docs/cpp/`，并在项目 `README.md`/`docs/index.md` 链接入口。
- 若新增“本 Playbook 未覆盖的语言”：再引入对应语言的标准仓库（subtree/vendoring 到 `docs/standards/<lang>/`）。
- 代理规则：
- C++：运行 `sh docs/standards/playbook/scripts/sync_standards.sh cpp`（或 `& "docs/standards/playbook/scripts/sync_standards.ps1" -Langs cpp`），落地到 `.agents/cpp/`（与 `.agents/tsl/` 并行）。
- 其他语言：在目标项目增加 `.agents/<lang>/`（与 `.agents/tsl/` 并行），只写该语言专属要求与工具链约束。
- 同步策略：每个规则集只同步到对应子目录（例如 `.agents/cpp/`），避免覆盖整个 `.agents/`。
- CI/工具：按文件类型分别执行格式化、lint、测试（不要让 TSL 规则去约束 C++ 代码，反之亦然）。
- C++ 补全：建议在项目根目录提供 `.clangd` 并指向正确的 `CompilationDatabase`（模板见 `templates/cpp/.clangd`）。
## 版本与贡献