📝 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:
csh 2026-01-07 17:09:39 +08:00
parent 3b2188f336
commit 0d6b2a0702
1 changed files with 47 additions and 1 deletions

View File

@ -58,6 +58,42 @@ PlaybookTSL`.tsl`/`.tsf`+ C++ + Python 工程规范与代理规则合
由于本仓库需要内部权限访问,其他项目**不能仅用外链引用**;推荐把 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. 在目标项目中首次引入:
@ -197,6 +233,9 @@ sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp
- 覆盖前备份:写入同目录的 `*.bak.*`(或 Windows 下随机后缀)
- 不修改:`.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` |
| `SYNC_GITATTR_MODE` | `block` | `.gitattributes` 同步模式:`block` 仅维护 managed 区块;`overwrite` 全量覆盖;`skip` 不更新 |
</details>
### 方式二:手动复制快照
如果不使用 `git subtree`,也可以由有权限的人手动复制 Playbook 到目标项目中(适合规范不频繁更新或项目数量较少的情况)。
@ -292,7 +333,10 @@ sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp
规则优先级建议:
- 同一项目内多个规则集并行放在 `.agents/<lang>/`,不要互相覆盖。
- 若某个子目录需要更具体规则(模块/子系统差异),在更靠近代码的目录放置更具体规则(例如 `src/foo/.agents/`),并以“离代码更近者优先”为准。
- 若某个子目录需要更具体规则(模块/子系统差异),在更靠近代码的目录放置更具体规则(例如 `src/foo/.agents/`),并以"离代码更近者优先"为准。
<details>
<summary>🔧 高级选项:`.agents` 覆盖/合并策略(点击展开)</summary>
#### `.agents` 的覆盖/合并策略(可执行流程)
@ -332,6 +376,8 @@ if (Test-Path $overlay) {
}
```
</details>
#### 扩展新语言(模板)
当目标项目需要新增一门语言(例如 C++),建议按以下模板扩展: