🐛 fix(sync_standards): preserve project gitattributes and clarify tsl/tsf

- default to managed .gitattributes block (block/overwrite/skip)

- ensure .agents/tsl points to docs/standards/tsl snapshot paths

- document expected structure and TSL/TSF constraints

README.md

@@ -85,17 +85,26 @@ TSL Playbook：Tinysoft Language（`.tsl` / `.tsf`）工程规范与代理规则
 
     根目录的 `.agents/tsl/` 与 `.gitattributes` 通过同步脚本获得：
 
-    - 直接运行 Playbook 提供的脚本（子树快照里自带）：
+    - 说明：在 **本 playbook 仓库** 内脚本位于 `scripts/`；在 **目标项目** 里通过 `git subtree` 引入到 `docs/standards/tsl/` 后，脚本路径变为 `docs/standards/tsl/scripts/`。
+    - 在目标项目里直接运行 Playbook 提供的脚本（子树快照里自带）：
     - `docs/standards/tsl/scripts/sync_standards.sh`（推荐）
     - `docs/standards/tsl/scripts/sync_standards.ps1`（推荐）
     - `docs/standards/tsl/scripts/sync_standards.bat`（推荐）
     - 脚本会从快照目录同步到项目根目录，并先备份旧文件（`.bak.*`）。
 
-    注：`docs/standards/tsl/` 只是推荐目录名；你可以用任意 `--prefix`（例如 `docs/standards/tsl_playbook/`）。同步脚本会从脚本自身路径推导快照根目录，不再依赖目录名。
+    注：建议固定使用 `--prefix docs/standards/tsl`，因为同步后的 `.agents/tsl/` 会引用该路径下的标准快照文档（`docs/standards/tsl/docs/...`）。
     注：默认同步到 `.agents/tsl/`；如需指定规则集名称，可通过环境变量 `AGENTS_NS`（例如 `AGENTS_NS=tsl`、`AGENTS_NS=common`）。
 
     这样 clone 任意项目时都能直接读取规范文件，不依赖外部访问权限。
 
+    同步脚本行为（目标项目内的最终落地内容）：
+
+    - 覆盖/更新：`.agents/<AGENTS_NS>/`（默认 `.agents/tsl/`）
+    - 更新 `.gitattributes`：默认只维护 `# BEGIN tsl-playbook .gitattributes` 区块（可用 `SYNC_GITATTR_MODE=overwrite|block|skip` 控制）
+    - 缺省创建：`.agents/index.md`
+    - 覆盖前备份：写入同目录的 `*.bak.*`（或 Windows 下随机后缀）
+    - 不修改：`.gitignore`（项目自行维护）
+
 ### 方式二：手动复制快照
 
 如果不使用 `git subtree`，也可以由有权限的人手动复制 Playbook 到目标项目中（适合规范不频繁更新或项目数量较少的情况）。
@@ -126,13 +135,39 @@ TSL Playbook：Tinysoft Language（`.tsl` / `.tsf`）工程规范与代理规则
 
 建议：仓库级规则尽量少且稳定；语言级规则各自独立，避免互相“污染”。
 
-本仓库提供的代理规则集（同步后位于目标项目的 `.agents/tsl/`）当前全部为**跨语言通用规则**：
+本仓库提供的代理规则集（同步后位于目标项目的 `.agents/tsl/`）以**跨语言通用规则**为主，但包含 TSL/TSF 文件（`.tsl`/`.tsf`）的必要约定（避免代理在缺少上下文时写出不符合 TSL 约束的代码）：
 
 - `auth.md`：敏感信息/鉴权边界
 - `code_quality.md`：质量底线与 review 清单
 - `performance.md`：性能原则与验证
 - `testing.md`：测试策略
 
+多语言项目推荐结构（示例：TSL + C++ + Python）：
+
+```txt
+.
+├── .agents/
+│   ├── index.md                      # 多语言索引（缺省时由脚本创建）
+│   ├── tsl/                          # 由本 Playbook 同步（适用于 .tsl/.tsf）
+│   ├── cpp/                          # C++ 规则集（来自另一个 playbook 或项目自建）
+│   └── python/                       # Python 规则集（同上）
+├── .gitattributes                    # 行尾/文本规范（可由某个 playbook 同步）
+├── docs/
+│   ├── standards/
+│   │   ├── tsl/                      # 本 Playbook 快照（git subtree/vendoring）
+│   │   ├── cpp/                      # C++ playbook 快照（可选）
+│   │   └── python/                   # Python playbook 快照（可选）
+│   └── project/                      # 项目自有文档（架构、ADR、运行方式等）
+├── scripts/
+│   └── sync_standards.sh             # 项目包装脚本：依次调用各 playbook 的 sync
+└── src/                              # 源码目录（按项目实际情况）
+```
+
+规则优先级建议：
+
+- 同一项目内多个规则集并行放在 `.agents/<lang>/`，不要互相覆盖。
+- 若某个子目录需要更具体规则（模块/子系统差异），在更靠近代码的目录放置更具体规则（例如 `src/foo/.agents/`），并以“离代码更近者优先”为准。
+
 #### `.agents` 的覆盖/合并策略（可执行流程）
 
 同步脚本会同步到项目根目录的 `.agents/tsl/`（并不会覆盖 `.agents/` 下的其他语言目录）。若项目需要追加 C++ 等语言/模块专属规则，建议二选一：