📝 docs(readme): add quick decision table and TL;DR for distribution methods
- 添加快速决策表:帮助用户在3种分发方式中快速选择 - 添加 TL;DR 30秒快速开始:提供一键复制的命令 - 折叠高级选项:环境变量配置和 Overlay 合并策略 - 降低文档认知负担,提升新用户体验 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
parent
3b2188f336
commit
0d6b2a0702
48
README.md
48
README.md
|
|
@ -58,6 +58,42 @@ Playbook:TSL(`.tsl`/`.tsf`)+ C++ + Python 工程规范与代理规则合
|
||||||
|
|
||||||
由于本仓库需要内部权限访问,其他项目**不能仅用外链引用**;推荐把 Playbook 规范 vendoring 到项目内。
|
由于本仓库需要内部权限访问,其他项目**不能仅用外链引用**;推荐把 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 同步(推荐)
|
### 方式一:git subtree 同步(推荐)
|
||||||
|
|
||||||
1. 在目标项目中首次引入:
|
1. 在目标项目中首次引入:
|
||||||
|
|
@ -197,6 +233,9 @@ sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp
|
||||||
- 覆盖前备份:写入同目录的 `*.bak.*`(或 Windows 下随机后缀)
|
- 覆盖前备份:写入同目录的 `*.bak.*`(或 Windows 下随机后缀)
|
||||||
- 不修改:`.gitignore`(项目自行维护)
|
- 不修改:`.gitignore`(项目自行维护)
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary>🔧 高级选项:环境变量配置(点击展开)</summary>
|
||||||
|
|
||||||
#### 环境变量(可选)
|
#### 环境变量(可选)
|
||||||
|
|
||||||
同步脚本支持以下可选环境变量(默认值可满足大多数项目):
|
同步脚本支持以下可选环境变量(默认值可满足大多数项目):
|
||||||
|
|
@ -206,6 +245,8 @@ sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp
|
||||||
| `AGENTS_NS` | `tsl` | 同步的规则集名/落地目录名:`.agents/<AGENTS_NS>/`(例如 `tsl`、`cpp`) |
|
| `AGENTS_NS` | `tsl` | 同步的规则集名/落地目录名:`.agents/<AGENTS_NS>/`(例如 `tsl`、`cpp`) |
|
||||||
| `SYNC_GITATTR_MODE` | `block` | `.gitattributes` 同步模式:`block` 仅维护 managed 区块;`overwrite` 全量覆盖;`skip` 不更新 |
|
| `SYNC_GITATTR_MODE` | `block` | `.gitattributes` 同步模式:`block` 仅维护 managed 区块;`overwrite` 全量覆盖;`skip` 不更新 |
|
||||||
|
|
||||||
|
</details>
|
||||||
|
|
||||||
### 方式二:手动复制快照
|
### 方式二:手动复制快照
|
||||||
|
|
||||||
如果不使用 `git subtree`,也可以由有权限的人手动复制 Playbook 到目标项目中(适合规范不频繁更新或项目数量较少的情况)。
|
如果不使用 `git subtree`,也可以由有权限的人手动复制 Playbook 到目标项目中(适合规范不频繁更新或项目数量较少的情况)。
|
||||||
|
|
@ -292,7 +333,10 @@ sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp
|
||||||
规则优先级建议:
|
规则优先级建议:
|
||||||
|
|
||||||
- 同一项目内多个规则集并行放在 `.agents/<lang>/`,不要互相覆盖。
|
- 同一项目内多个规则集并行放在 `.agents/<lang>/`,不要互相覆盖。
|
||||||
- 若某个子目录需要更具体规则(模块/子系统差异),在更靠近代码的目录放置更具体规则(例如 `src/foo/.agents/`),并以“离代码更近者优先”为准。
|
- 若某个子目录需要更具体规则(模块/子系统差异),在更靠近代码的目录放置更具体规则(例如 `src/foo/.agents/`),并以"离代码更近者优先"为准。
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary>🔧 高级选项:`.agents` 覆盖/合并策略(点击展开)</summary>
|
||||||
|
|
||||||
#### `.agents` 的覆盖/合并策略(可执行流程)
|
#### `.agents` 的覆盖/合并策略(可执行流程)
|
||||||
|
|
||||||
|
|
@ -332,6 +376,8 @@ if (Test-Path $overlay) {
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
</details>
|
||||||
|
|
||||||
#### 扩展新语言(模板)
|
#### 扩展新语言(模板)
|
||||||
|
|
||||||
当目标项目需要新增一门语言(例如 C++),建议按以下模板扩展:
|
当目标项目需要新增一门语言(例如 C++),建议按以下模板扩展:
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue