Merge commit 'ac794a6a7051497ff60b947642d44f0f8c04d6c6' into lsp-server

This commit is contained in:
csh
2026-01-08 15:56:37 +08:00
113 changed files with 254751 additions and 176 deletions
+172 -32
View File
@@ -16,7 +16,7 @@ PlaybookTSL`.tsl`/`.tsf`+ C++ + Python 工程规范与代理规则合
## 适用范围
- 本指南适用于所有 TSL 相关仓库与脚本。
- 本指南适用于所有 TSL/C++/Python 相关仓库与脚本。
- 当现有代码与本指南冲突时,**以保持局部一致性为优先**,逐步迁移。
## docs/(开发规范)
@@ -25,8 +25,11 @@ PlaybookTSL`.tsl`/`.tsf`+ C++ + Python 工程规范与代理规则合
- `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/code_style.md`TSL 代码结构、格式、`begin/end`
代码块、注释与通用最佳实践。
- `docs/tsl/naming.md`:TSL 命名规范(顶层声明、文件同名规则、变量/成员/property、常量、集合命名等)。
- `docs/tsl/syntax_book/index.md`:TSL 语法手册(整理自原始语法/机制目录册;`function.md`
建议按需检索)。
- `docs/tsl/toolchain.md`TSL 工具链与验证命令模板。
- `docs/cpp/code_style.md`C++ 代码风格(C++23/Modules)。
- `docs/cpp/naming.md`:C++ 命名规范(Google 基线)。
@@ -35,22 +38,69 @@ PlaybookTSL`.tsl`/`.tsf`+ C++ + Python 工程规范与代理规则合
- `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/` 复制到项目根目录)。
- `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`)。
- `templates/python/`Python 落地模板(`pyproject.toml`
工具配置、`.flake8``.pylintrc``.pre-commit-config.yaml``.editorconfig``.vscode/settings.json`)。
- `templates/ci/`:目标项目 CI 示例模板(如 Gitea
Actions),用于自动化校验部分规范。
## .agents/(代理规则)
`.agents/` 目录是给自动化/AI 代理在本仓库内工作时遵守的规则快照,与 `docs/` 并行。
`.agents/` 目录是给自动化/AI 代理在本仓库内工作时遵守的规则快照,与 `docs/`
并行。
- `.agents/index.md`:规则集索引(多语言)。
- `.agents/tsl/`TSL 规则集(入口:`.agents/tsl/index.md`)。
- `.agents/cpp/`C++ 规则集(入口:`.agents/cpp/index.md`)。
- `.agents/python/`Python 规则集(入口:`.agents/python/index.md`)。
## SKILLSCodex CLI
本仓库内置一组 Codex CLI skills(见 `codex/skills/`),用于 code review
/ 格式化 / 调试等工作流;安装与编写规范见 `SKILLS.md`
## 在其他项目中使用本 Playbook
由于本仓库需要内部权限访问,其他项目**不能仅用外链引用**;推荐把 Playbook 规范 vendoring 到项目内。
### 🚀 快速决策:我应该用哪种方式?
| 你的情况 | 推荐方式 | 优势 |
| -------------------------------- | ------------------------------- | ------------------------------- |
| 新项目,需要持续同步更新 | **方式一:git subtree(推荐)** | 可随时拉取最新标准,版本可追溯 |
| 只需要一次性引入,不常更新 | 方式二:手动复制快照 | 简单直接,无需 git subtree 知识 |
| 只需要部分语言(如只要 TSL+C++) | 方式三:脚本裁剪复制 | 自动裁剪,只包含所需语言 |
| **不确定?** | **方式一:git subtree(推荐)** | 最灵活,后续可随时同步更新 |
**大部分情况推荐使用方式一(git subtree)。**
---
### ⚡ TL;DR - 30 秒快速开始
大部分项目只需运行以下命令即可完成落地(以 TSL 为例):
```bash
# 1. 引入标准快照
git subtree add --prefix docs/standards/playbook \
https://git.mytsl.cn/csh/playbook.git main --squash
# 2. 同步规则到项目根目录
sh docs/standards/playbook/scripts/sync_standards.sh tsl
# 3. 提交
git add .
git commit -m ":package: deps(playbook): add tsl standards"
```
**完成!** 后续同步更新只需重复步骤 1(把 `add` 改为 `pull`)和步骤 2。
详细说明和其他方式见下文 ↓
---
### 方式一:git subtree 同步(推荐)
1. 在目标项目中首次引入:
@@ -73,7 +123,8 @@ PlaybookTSL`.tsl`/`.tsf`+ C++ + Python 工程规范与代理规则合
#### 快速落地(最小 4 步)
在目标项目中按以下顺序执行即可完成落地(推荐固定使用 `--prefix docs/standards/playbook`):
在目标项目中按以下顺序执行即可完成落地(推荐固定使用
`--prefix docs/standards/playbook`):
1. 引入标准快照(见上文 `git subtree add`
2. 同步到项目根目录(生成/更新 `.agents/<lang>/`、更新 `.gitattributes`):
@@ -94,18 +145,39 @@ PlaybookTSL`.tsl`/`.tsf`+ C++ + Python 工程规范与代理规则合
sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp
```
3. 验收(任意满足其一即可):
> 说明:若项目根目录没有 `AGENTS.md``sync_standards.*`
> 会自动生成最小版;已存在则不会覆盖。
3. 验收(任意满足其一即可):
- 目录存在:`.agents/tsl/`
- 规则入口可读:`.agents/tsl/index.md`
- (可选)C++ 规则入口可读:`.agents/cpp/index.md`
- 标准文档可读:`docs/standards/playbook/docs/index.md`
- `.gitattributes` 包含区块`# BEGIN playbook .gitattributes` / `# END playbook .gitattributes`
- `.gitattributes` 包含追加块头`# Added from playbook .gitattributes`
4. 将同步产物纳入版本控制(目标项目建议提交):
- `docs/standards/playbook/`(标准快照)
- `.agents/tsl/`(落地规则集)
- `.gitattributes`managed block 更新
- `.gitattributes`追加缺失规则
- `AGENTS.md`(若本次自动生成)
#### 新项目 / 旧项目(命令示例)
新项目(无 `.agents/` 与 `AGENTS.md`):
```bash
git subtree add --prefix docs/standards/playbook https://git.mytsl.cn/csh/playbook.git main --squash
sh docs/standards/playbook/scripts/sync_standards.sh tsl
```
旧项目(已有 `AGENTS.md`):
```bash
git subtree pull --prefix docs/standards/playbook https://git.mytsl.cn/csh/playbook.git main --squash
sh docs/standards/playbook/scripts/sync_standards.sh tsl
```
旧项目的 `AGENTS.md` 不会被覆盖;如需指向 `.agents/`,请手动对齐内容。
#### 可选:项目包装脚本(多 playbook 串联)
@@ -149,26 +221,35 @@ sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp
根目录的 `.agents/<lang>/` 与 `.gitattributes` 通过同步脚本获得:
- 说明:在 **本 playbook 仓库** 内脚本位于 `scripts/`;在 **目标项目** 里通过 `git subtree` 引入到 `docs/standards/playbook/` 后,脚本路径变为 `docs/standards/playbook/scripts/`。
- 说明:在 **本 playbook 仓库** 内脚本位于 `scripts/`;在 **目标项目** 里通过
`git subtree` 引入到 `docs/standards/playbook/` 后,脚本路径变为
`docs/standards/playbook/scripts/`。
- 在目标项目里直接运行 Playbook 提供的脚本(子树快照里自带):
- `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/playbook`,因为同步后的 `.agents/*/` 会引用该路径下的标准快照文档(`docs/standards/playbook/docs/...`)。
注:默认同步到 `.agents/tsl/`;如需同步 C++ 规则集,推荐直接运行:`sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp`。
建议固定使用 `--prefix docs/standards/playbook`,因为同步后的 `.agents/*/`
会引用该路径下的标准快照文档(`docs/standards/playbook/docs/...`)。无参数时若已存在
`.agents/<lang>/`,将按现有语言同步;否则默认 `.agents/tsl/`。如需同步 C++ 规则集,
推荐直接运行:`sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp`。
这样 clone 任意项目时都能直接读取规范文件,不依赖外部访问权限。
同步脚本行为(目标项目内的最终落地内容):
- 覆盖/更新:`.agents/<AGENTS_NS>/`(默认 `.agents/tsl/`
- 更新 `.gitattributes`:默认只维护 `# BEGIN playbook .gitattributes` 区块(可用 `SYNC_GITATTR_MODE=block|overwrite|skip` 控制)
- 自动识别:未传语言参数且已存在 `.agents/<lang>/` 时,按现有语言同步
- 更新 `.gitattributes`:默认追加缺失规则(可用
`SYNC_GITATTR_MODE=append|block|overwrite|skip` 控制)
- 缺省创建:`.agents/index.md`
- 覆盖前备份:写入同目录的 `*.bak.*`(或 Windows 下随机后缀)
- 不修改:`.gitignore`(项目自行维护)
<details>
<summary>🔧 高级选项:环境变量配置(点击展开)</summary>
#### 环境变量(可选)
同步脚本支持以下可选环境变量(默认值可满足大多数项目):
@@ -176,25 +257,63 @@ sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp
| 变量名 | 默认值 | 说明 |
| ------------------- | ------- | ------------------------------------------------------------------------------------------- |
| `AGENTS_NS` | `tsl` | 同步的规则集名/落地目录名:`.agents/<AGENTS_NS>/`(例如 `tsl`、`cpp`) |
| `SYNC_GITATTR_MODE` | `block` | `.gitattributes` 同步模式:`block` 仅维护 managed 区块;`overwrite` 全量覆盖;`skip` 不更新 |
| `SYNC_GITATTR_MODE` | `append` | `.gitattributes` 同步模式:`append` 仅追加缺失规则(忽略注释/空行,比对后按块追加);`block` 仅维护 managed 区块;`overwrite` 全量覆盖;`skip` 不更新 |
</details>
### 方式二:手动复制快照
如果不使用 `git subtree`,也可以由有权限的人手动复制 Playbook 到目标项目中(适合规范不频繁更新或项目数量较少的情况)。
如果不使用
`git subtree`,也可以由有权限的人手动复制 Playbook 到目标项目中(适合规范不频繁更新或项目数量较少的情况)。
步骤:
1. 在目标项目创建目录:`docs/standards/playbook/`。
2. 从本仓库复制以下内容到目标项目:
- `docs/` → `docs/standards/playbook/docs/`(包含 `docs/common/`、`docs/tsl/`、`docs/cpp/`、`docs/python/`
- `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/playbook/SOURCE.md` 记录本次复制的来源版本/日期(建议写 Playbook 的 commit hash)。
3. 在目标项目根目录运行同步脚本,把 `.agents/tsl/` 与 `.gitattributes`
落到根目录(见上文脚本路径)。
4. 在 `docs/standards/playbook/SOURCE.md`
记录本次复制的来源版本/日期(建议写 Playbook 的 commit hash)。
该方式没有自动同步能力,后续更新需重复上述复制流程。
### 方式三:脚本裁剪复制(按语言,离线)
当你希望“只 vendoring 需要的语言规范”(例如只需要 `tsl` +
`cpp`)时,可直接运行本仓库提供的裁剪脚本:
- macOS/Linux
```bash
sh <PLAYBOOK_ROOT>/scripts/vendor_playbook.sh <target-project-root> tsl cpp
```
- PowerShell
```powershell
powershell -File <PLAYBOOK_ROOT>\\scripts\\vendor_playbook.ps1 -DestRoot <target-project-root> -Langs tsl,cpp
```
- Windows bat
```bat
<PLAYBOOK_ROOT>\\scripts\\vendor_playbook.bat <target-project-root> --langs tsl,cpp
```
脚本会:
- 生成裁剪快照到 `docs/standards/playbook/`(包含
`docs/common/` + 选定语言目录 + 对应 `.agents/<lang>/` + `scripts/` +
`.gitattributes` + 通用 `templates/ci/` + 相关 `templates/<lang>/`
- 自动执行 `docs/standards/playbook/scripts/sync_standards.*`,把
`.agents/<lang>/` 与 `.gitattributes` 落地到目标项目根目录
- 生成 `docs/standards/playbook/SOURCE.md` 记录来源与版本信息
### 多语言项目落地(TSL + C++/其他语言)
多语言项目建议把规范拆成两类:
@@ -204,14 +323,17 @@ sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp
- 行尾与文本规范:`.gitattributes`
- 代理最低要求:`.agents/*`(工作原则、质量底线、安全边界)
2. **语言级(Language-specific)规范**:只对某个语言成立的风格与工具。
- 例如 TSL 的命名/文件顶层声明限制、C++ 的 `.clang-format/.clang-tidy`、Python 的 `ruff` 等。
- 例如 TSL 的命名/文件顶层声明限制、C++ 的
`.clang-format/.clang-tidy`、Python 的 `ruff` 等。
建议:仓库级规则尽量少且稳定;语言级规则各自独立,避免互相“污染”。
本仓库提供两套代理规则集(同步后位于目标项目的 `.agents/tsl/` 与 `.agents/cpp/`):
本仓库提供两套代理规则集(同步后位于目标项目的 `.agents/tsl/` 与
`.agents/cpp/`):
- 两者都包含跨语言通用底线:`auth.md`、`code_quality.md`、`performance.md`、`testing.md`
- 并在 `index.md` 中叠加语言级“硬约束”(TSL/TSF 语法限制、C++23/Modules、Windows 支持等)
- 并在 `index.md`
中叠加语言级“硬约束”(TSL/TSF 语法限制、C++23/Modules、Windows 支持等)
多语言项目推荐结构(示例:TSL + C++ + Python):
@@ -236,18 +358,26 @@ sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp
规则优先级建议:
- 同一项目内多个规则集并行放在 `.agents/<lang>/`,不要互相覆盖。
- 若某个子目录需要更具体规则(模块/子系统差异),在更靠近代码的目录放置更具体规则(例如 `src/foo/.agents/`),并以“离代码更近者优先”为准。
- 若某个子目录需要更具体规则(模块/子系统差异),在更靠近代码的目录放置更具体规则(例如
`src/foo/.agents/`),并以"离代码更近者优先"为准。
<details>
<summary>🔧 高级选项:`.agents` 覆盖/合并策略(点击展开)</summary>
#### `.agents` 的覆盖/合并策略(可执行流程)
同步脚本会同步到项目根目录的 `.agents/tsl/`(并不会覆盖 `.agents/` 下的其他语言目录)。若项目需要追加 C++ 等语言/模块专属规则,建议二选一:
同步脚本会同步到项目根目录的 `.agents/tsl/`(并不会覆盖 `.agents/`
下的其他语言目录)。若项目需要追加 C++ 等语言/模块专属规则,建议二选一:
1. **推荐:子目录规则覆盖(无需改同步脚本)**
- 让本 Playbook 的规则集固定落在 `.agents/tsl/`,由同步脚本维护。
- 在其他语言/模块目录下新增更具体规则,例如 `.agents/cpp/`、`cpp/.agents/`、`src/.agents/`。
- 在其他语言/模块目录下新增更具体规则,例如
`.agents/cpp/`、`cpp/.agents/`、`src/.agents/`。
2. **Overlay 合并:项目维护叠加层并在同步后覆盖回去**
- 约定项目自定义规则放在 `docs/project/agents_overlay/`(不叫 `.agents`,避免被同步覆盖)。
- 每次运行 `sync_standards.*` 后,再把 overlay 覆盖回 `.agents/tsl/`(建议封装成项目脚本)。
- 约定项目自定义规则放在 `docs/project/agents_overlay/`(不叫
`.agents`,避免被同步覆盖)。
- 每次运行 `sync_standards.*` 后,再把 overlay 覆盖回
`.agents/tsl/`(建议封装成项目脚本)。
macOS/Linux 示例(目标项目的 `scripts/sync_standards.sh`):
@@ -276,19 +406,29 @@ if (Test-Path $overlay) {
}
```
</details>
#### 扩展新语言(模板)
当目标项目需要新增一门语言(例如 C++),建议按以下模板扩展:
- 文档:
- 若使用本 Playbook 自带的 C++ 规范:无需额外 subtree,直接使用 `docs/standards/playbook/docs/cpp/`,并在项目 `README.md`/`docs/index.md` 链接入口。
- 若新增“本 Playbook 未覆盖的语言”:再引入对应语言的标准仓库(subtree/vendoring 到 `docs/standards/<lang>/`)。
- 若使用本 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/`
- 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`)。
- C++ 补全:建议在项目根目录提供 `.clangd` 并指向正确的
`CompilationDatabase`(模板见 `templates/cpp/.clangd`)。
## 版本与贡献