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

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
+62
View File
@@ -0,0 +1,62 @@
# TSL 工具链与验证命令(模板)
本文件提供一份**通用占位模板**,用于在不同 TSL 项目中快速补齐“工具链与如何验证”的关键上下文。
使用方式:
- 在具体项目中复制本模板并把占位符替换为真实信息;
- 或在项目文档中引用本模板,并在项目内提供对应的 `scripts/*` 统一入口脚本。
## 1. TSL 工具链
### 1.1 解释器/编译器(必填)
- 工具名称:`<tsl/tslcli/内部工具名>`
- 可执行命令:
- macOS/Linux`<command>`(例:`tsl` / `tslcli` / `sh scripts/tsl.sh`
- Windows`<command>`(例:`tsl.exe` / `tslcli.exe` / `powershell -File scripts/tsl.ps1`
- 版本要求:`<固定版本或范围,例如:= 3.2.1 / >=3.2,<4.0>`
- 安装方式:`<内部安装包/路径/IDE 自带/CI 镜像等>`
- 推荐统一入口脚本:`scripts/tsl.{sh,ps1}`(封装参数与环境变量,避免每个任务重复猜测)
### 1.2 运行环境(按需)
- 必要环境变量:`<TSL_HOME> <TSL_LIB_PATH> <LICENSE_PATH> ...`
- 外部依赖:`<数据库/服务/共享目录/网络权限/账户权限>`
- 运行约束:
- 是否允许联网:`<yes/no>`
- 是否需要许可证/凭证:`<说明如何在本地与 CI 提供;禁止写入仓库>`
## 2. 验证命令
> 要求:改动完成后至少能跑通“最小冒烟”;若项目存在测试体系,尽量补到对应层级。
### 2.1 最小冒烟(必须能跑)
- macOS/Linux`<tsl> run <path/to/SmokeTest.tsl> -- <args>`
- Windows`<tsl.exe> run <path\\to\\SmokeTest.tsl> -- <args>`
- 或统一入口:
- `sh scripts/smoke.sh`
- `powershell -File scripts/smoke.ps1`
### 2.2 单元测试(如有)
- `sh scripts/test.sh`
- 或:`<tsl> test <tests/>`
- 或:`<tsl> run <path/to/TestRunner.tsf>`
### 2.3 静态检查/格式化(如有)
- `sh scripts/lint.sh`
- `sh scripts/format.sh`
- 或:`<tsl> check <src/>` / `<tsl> fmt <src/>`
### 2.4 构建/打包(如有)
- `sh scripts/build.sh`
- 或:`<tsl> build <project-file>`
### 2.5 失败处理约定(必填)
- 只修复与本次改动直接相关的失败;无关失败在输出中说明并隔离。
- 若某验证步骤无法执行(缺环境/缺凭证),必须明确写出原因与替代验证手段(例如最小复现脚本/手动检查清单)。