Merge commit '35e6a301aa36e43df8458cb7c6ed40f60c642b78' into lsp-server
This commit is contained in:
@@ -1,6 +1,13 @@
|
||||
# playbook
|
||||
|
||||
Playbook:TSL(`.tsl`/`.tsf`)+ C++ + Python + Markdown(代码格式化)工程规范与代理规则合集。
|
||||
Playbook:工程规范与代理规则合集,当前覆盖:
|
||||
|
||||
- TSL(`.tsl`/`.tsf`)
|
||||
- C++
|
||||
- Python
|
||||
- TypeScript(`.ts`/`.tsx`)
|
||||
- JavaScript(`.js`/`.mjs`/`.cjs`)
|
||||
- Markdown(代码格式化)
|
||||
|
||||
## 原则
|
||||
|
||||
@@ -10,14 +17,14 @@ Playbook:TSL(`.tsl`/`.tsf`)+ C++ + Python + Markdown(代码格式化)
|
||||
|
||||
## 适用范围
|
||||
|
||||
- 本指南适用于所有 TSL/C++/Python/Markdown 相关仓库与脚本
|
||||
- 本指南适用于所有 TSL/C++/Python/TypeScript/JavaScript/Markdown 相关仓库与脚本
|
||||
- 当现有代码与本指南冲突时,**以保持局部一致性为优先**,逐步迁移
|
||||
|
||||
## docs/(开发规范)
|
||||
|
||||
`docs/` 目录是给开发者阅读的工程规范,约束代码写法、命名与提交信息。
|
||||
|
||||
- `docs/index.md`:文档导航(跨语言 common / TSL / C++ / Python / Markdown)。
|
||||
- `docs/index.md`:文档导航(跨语言 common / TSL / C++ / Python / TypeScript / Markdown)。
|
||||
- `docs/common/commit_message.md`:提交信息与版本号规范(type/scope/subject/body/footer、可选 Emoji 图例、SemVer)。
|
||||
- `docs/tsl/code_style.md`:TSL 代码结构、格式、`begin/end`
|
||||
代码块、注释与通用最佳实践。
|
||||
@@ -35,6 +42,10 @@ Playbook:TSL(`.tsl`/`.tsf`)+ C++ + Python + Markdown(代码格式化)
|
||||
- `docs/python/configuration.md`:Python 配置清单(落地时从 `templates/python/`
|
||||
复制到项目根目录)。
|
||||
- `docs/markdown/index.md`:Markdown 代码块与行内代码格式(仅代码格式化)。
|
||||
- `docs/typescript/code_style.md`:TypeScript 代码风格(Google 基线)。
|
||||
- `docs/typescript/naming.md`:TypeScript 命名规范。
|
||||
- `docs/typescript/toolchain.md`:TypeScript 工具链(typescript/prettier/eslint/vitest)。
|
||||
- `docs/typescript/configuration.md`:TypeScript 配置清单(tsconfig/eslint/prettier)。
|
||||
- `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`)。
|
||||
@@ -124,6 +135,7 @@ Layer 3: docs/ (权威静态文档)
|
||||
- `rulesets/tsl/index.md`:TSL 核心约定(44 行)
|
||||
- `rulesets/cpp/index.md`:C++ 核心约定(47 行)
|
||||
- `rulesets/python/index.md`:Python 核心约定(45 行)
|
||||
- `rulesets/typescript/index.md`:TypeScript 核心约定(47 行)
|
||||
- `rulesets/markdown/index.md`:Markdown 核心约定(31 行,仅代码格式化)
|
||||
|
||||
更多说明:`rulesets/index.md`
|
||||
@@ -287,16 +299,16 @@ python scripts/playbook.py -config playbook.toml
|
||||
- 行尾与文本规范:`.gitattributes`
|
||||
- 代理最低要求:`.agents/*`(工作原则、质量底线、安全边界)
|
||||
2. **语言级(Language-specific)规范**:只对某个语言成立的风格与工具。
|
||||
- 例如 TSL 的命名/文件顶层声明限制、C++ 的 `.clang-format/.clang-tidy`、Python 的 `ruff` 等。
|
||||
- 例如 TSL 的命名/文件顶层声明限制、C++ 的 `.clang-format/.clang-tidy`、Python 的 `ruff`、TypeScript 的 ESLint/类型约束等。
|
||||
|
||||
**建议**:仓库级规则尽量少且稳定;语言级规则各自独立,避免互相"污染"。
|
||||
|
||||
本仓库提供多套代理规则集(同步后位于目标项目的 `.agents/tsl/` / `.agents/cpp/` / `.agents/python/` / `.agents/markdown/`):
|
||||
本仓库提供多套代理规则集(同步后位于目标项目的 `.agents/tsl/` / `.agents/cpp/` / `.agents/python/` / `.agents/typescript/` / `.agents/markdown/`):
|
||||
|
||||
- 三者都包含核心约定与安全红线
|
||||
- 并在 `index.md` 中叠加语言级"硬约束"(TSL/TSF 语法限制、C++23/Modules、Python 风格、Markdown 代码格式化等)
|
||||
- 并在 `index.md` 中叠加语言级"硬约束"(TSL/TSF 语法限制、C++23/Modules、Python 风格、TypeScript 类型约束、Markdown 代码格式化等)
|
||||
|
||||
**多语言项目推荐结构**(示例:TSL + C++ + Python + Markdown):
|
||||
**多语言项目推荐结构**(示例:TSL + C++ + Python + TypeScript + Markdown):
|
||||
|
||||
```txt
|
||||
.
|
||||
@@ -305,6 +317,7 @@ python scripts/playbook.py -config playbook.toml
|
||||
│ ├── tsl/ # 由本 Playbook 同步(适用于 .tsl/.tsf)
|
||||
│ ├── cpp/ # 由本 Playbook 同步(适用于 C++23/Modules)
|
||||
│ ├── python/ # Python 规则集(同上)
|
||||
│ ├── typescript/ # TypeScript/JavaScript 规则集(同上)
|
||||
│ └── markdown/ # Markdown 规则集(仅代码格式化)
|
||||
├── .gitattributes # 行尾/文本规范
|
||||
├── docs/
|
||||
|
||||
Reference in New Issue
Block a user