From 0d6b2a070215287fcec26fc920aef4aac980e81c Mon Sep 17 00:00:00 2001
From: csh <caoshenghui@tinysoft.com.cn>
Date: Wed, 7 Jan 2026 17:09:39 +0800
Subject: [PATCH] :memo: docs(readme): add quick decision table and TL;DR for
 distribution methods
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 添加快速决策表：帮助用户在3种分发方式中快速选择
- 添加 TL;DR 30秒快速开始：提供一键复制的命令
- 折叠高级选项：环境变量配置和 Overlay 合并策略
- 降低文档认知负担，提升新用户体验

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 README.md | 48 +++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 47 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index d52810f..c02e3a8 100644
--- a/README.md
+++ b/README.md
@@ -58,6 +58,42 @@ Playbook：TSL（`.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++），建议按以下模板扩展：