📝 docs(readme): clarify project docs vs standards

- 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

.agents/auth.md

@@ -0,0 +1,33 @@
+# 安全与鉴权（Auth）
+
+本文件定义代理在处理鉴权、安全、敏感数据相关任务时的边界与要求。
+
+## 1. 基本原则
+
+- **最小权限**：只使用完成任务所需的最低权限与最少数据。
+- **默认保守**：不确定是否敏感时按敏感处理。
+- **不扩散秘密**：任何 secret 只在必要范围内出现。
+
+## 2. 凭证与敏感信息
+
+- 不要在代码、日志、注释或文档中写入明文密钥、Token、密码。
+- 如需示例，使用占位符：`<TOKEN>`、`<PASSWORD>`。
+- 避免把敏感信息打印到标准输出或错误日志。
+
+## 3. 鉴权逻辑修改
+
+- 修改鉴权/权限控制时必须说明：
+  - 变更动机
+  - 风险评估
+  - 兼容性/回滚方案
+- 默认保持旧行为兼容，除非明确要求破坏性变更。
+
+## 4. 依赖与第三方
+
+- 禁止无理由新增依赖，尤其是网络、加密、认证相关依赖。
+- 若必须新增，需在 PR 说明理由、替代方案与安全影响。
+
+## 5. 审计与合规
+
+- 任何涉及用户数据/权限边界的改动需可审计：代码清晰、注释说明“为什么”。
+- 发现潜在安全漏洞时，优先修复或明确标注 `FIXME(name): security risk ...`。

.agents/code_quality.md

@@ -0,0 +1,32 @@
+# 代码质量（Code Quality）
+
+本文件定义代理对代码质量的最低要求与审查清单。
+
+## 1. 总体要求
+
+- 对 `.tsl`/`.tsf` 文件一律按 TSL 规范处理（`.tsf` 也是 TSL 源文件）：遵守标准快照中的 `docs/tsl/code_style.md` 与 `docs/tsl/naming.md`（在目标项目中应 vendoring 到 `docs/standards/tsl/docs/tsl/`）。
+- 改动聚焦目标；避免“顺手重构”。
+- API 变更要显式说明影响与迁移方式。
+
+## 2. 可读性
+
+- 复杂逻辑拆分为具名函数/变量。
+- 避免深层嵌套与重复代码。
+- 必要注释解释“为什么”而不是“做什么”。
+
+## 3. 错误处理
+
+- 错误必须显式处理；禁止静默吞错。
+- 失败路径要可观测（返回/抛出/日志）。
+
+## 4. 复杂度与规模
+
+- 单函数尽量 ≤ 60 行；超过应说明原因或拆分。
+- 单次 PR 尽量小步提交，便于 review。
+
+## 5. Review 清单
+
+- 是否有无关改动？
+- 是否有清晰的动机与行为说明？
+- 是否保持模块内风格一致？
+- 是否需要补测试/示例？

.agents/index.md

@@ -0,0 +1,60 @@
+# TSL Playbook 代理规则集（.agents/tsl）
+
+本规则集用于存放 **AI/自动化代理在仓库内工作时必须遵守的规则**。
+
+在多语言项目中，推荐将本规则集放在目标项目的 `.agents/tsl/` 下（由 `scripts/sync_standards.*` 同步），并与其他语言规则集并行：
+
+- `.agents/tsl/`：TSL 标准规则集（本仓库提供）
+- `.agents/cpp/`、`.agents/python/` 等：其他语言规则集（按需新增）
+
+这些规则与 `docs/` 下的人类开发规范并行：
+
+- `docs/`：给人看的编码/命名/提交规范
+- `.agents/`：给代理看的任务边界、质量与安全要求
+
+## 范围与优先级
+
+- 作为仓库级基线规则集使用；更靠近代码目录的规则应更具体并可覆盖基线。
+- 当代理规则与 `docs` 发生冲突时：
+  1. 安全/合规优先
+  2. 其次保持仓库现有一致性
+
+## 代理工作原则
+
+- 先理解目标与上下文，再动手改代码。
+- 修改要小而清晰；避免无关重构。
+- 任何可能影响行为的改动都要补充或更新测试/示例（若项目有测试体系）。
+- 不要引入新依赖或工具，除非明确要求。
+
+## 子文档
+
+- 安全与鉴权：`auth.md`
+- 性能：`performance.md`
+- 代码质量：`code_quality.md`
+- 测试：`testing.md`
+
+## 分类（本仓库现状）
+
+当前本规则集下的文件以 **跨语言通用规则** 为主（不绑定具体语言语法/工具链），但包含 TSL 代码在仓库里最容易踩坑的“语言级硬约束”，以避免代理在缺少上下文时写出不符合 TSL/TSF 约定的代码。
+
+- `auth.md`：敏感信息/鉴权边界
+- `code_quality.md`：质量底线与 review 清单
+- `performance.md`：性能原则与验证
+- `testing.md`：测试策略
+
+若项目需要更细的语言/模块专属代理要求，建议在更靠近源码的目录放置更具体的规则（例如 `src/.agents/`），或并行新增其他规则集（例如 `.agents/cpp/`）。
+
+## TSL/TSF 必要约定（必须遵守）
+
+- `.tsl` 与 `.tsf` 都是 Tinysoft Language 源文件；修改它们时统一按 TSL 规范处理（不要把 `.tsf` 当成“另一种语言/无风格约束的脚本”）。
+- 文件级约束：一个文件只能有一个顶层声明，且文件基名必须与该顶层声明同名（推荐 `PascalCase`）；`.tsl` 顶层声明只能是 `function`。
+- 格式：空格缩进（默认 4 空格），关键字用小写，复杂分支/多语句分支用 `begin/end` 块表达结构。
+- 命名：类型/顶层函数/property 用 `PascalCase`；局部变量/参数用 `snake_case`；私有成员变量用 `snake_case_`。
+
+## 与开发规范的关系
+
+- 在本仓库内：`docs/tsl/` 与 `docs/common/`。
+- 在目标项目内：标准快照应 vendoring 到 `docs/standards/tsl/`，对应路径为：
+  - 代码风格：`docs/standards/tsl/docs/tsl/code_style.md`
+  - 命名规范：`docs/standards/tsl/docs/tsl/naming.md`
+  - 提交信息：`docs/standards/tsl/docs/common/commit_message.md`

.agents/performance.md

@@ -0,0 +1,31 @@
+# 性能（Performance）
+
+本文件定义代理在做性能相关改动时的准则与检查项。
+
+## 1. 目标与度量
+
+- 明确性能目标：延迟、吞吐、内存、CPU、I/O 等。
+- 没有指标时不要盲目优化；先补充测量或基准。
+
+## 2. 处理流程
+
+1. 先定位瓶颈（profile/trace/log）。
+2. 再提出最小化改动方案。
+3. 最后用数据验证收益与副作用。
+
+## 3. 优化准则
+
+- 优先消除算法/结构性问题，再考虑微优化。
+- 避免引入复杂度换取小收益。
+- 性能优化不应牺牲可读性；必要时加注释说明权衡。
+
+## 4. 常见风险
+
+- 避免重复计算、无界缓存、隐式复制。
+- 注意热路径中的分配与 I/O。
+- 并发优化要考虑正确性与可测试性。
+
+## 5. 验证
+
+- 提供优化前后可复现的对比数据（基准、采样结果或压测报告）。
+- 若无测试体系，至少提供最小可运行的复现脚本/步骤。

.agents/testing.md

@@ -0,0 +1,26 @@
+# 测试（Testing）
+
+本文件定义代理在改动代码时的测试策略与要求。
+
+## 1. 测试层级
+
+- **单元测试**：验证函数/模块的独立行为。
+- **集成测试**：验证模块间交互与关键流程。
+- **回归测试**：防止已修复问题复发。
+
+## 2. 何时补测试
+
+- 新功能必须新增对应测试。
+- 修复 bug 必须先写/补回归用例。
+- 仅当改动纯文档/注释/格式时可不加测试。
+
+## 3. 测试可维护性
+
+- 一个用例只验证一个行为点。
+- 测试命名清晰，能从名字看出期望。
+- 避免依赖外部不稳定资源；必要时 mock/stub。
+
+## 4. 运行与失败处理
+
+- 本仓库未来若引入测试命令，需在此补充统一的运行方式。
+- 测试失败时优先定位改动相关原因，不修无关失败。

.gitattributes

@@ -0,0 +1,34 @@
+# Ensure all text files use UTF-8 (by convention) and LF line endings.
+# Line endings are normalized to LF in the repo and checked out as LF,
+# regardless of OS/core.autocrlf settings.
+
+# Default: detect text automatically, enforce LF on checkout/commit.
+* text=auto eol=lf
+
+# Explicit text types in this repo.
+*.tsl   text eol=lf
+*.tsf   text eol=lf
+*.md    text eol=lf
+*.txt   text eol=lf
+*.json  text eol=lf
+*.yml   text eol=lf
+*.yaml  text eol=lf
+*.toml  text eol=lf
+*.ini   text eol=lf
+*.cfg   text eol=lf
+*.xml   text eol=lf
+*.csv   text eol=lf
+*.sh    text eol=lf
+
+# Binary files (no line-ending conversion).
+*.png   binary
+*.jpg   binary
+*.jpeg  binary
+*.gif   binary
+*.ico   binary
+*.pdf   binary
+*.zip   binary
+*.7z    binary
+*.gz    binary
+*.tar   binary
+*.exe   binary

README.md

@@ -1,3 +1,268 @@
-# tsl-style-guide
+# tsl-playbook
 
-tsl代码风格
+TSL Playbook：Tinysoft Language（`.tsl` / `.tsf`）工程规范与代理规则合集。
+
+## 目标
+
+- 让代码**易读、易维护、易演进**。
+- 风格保持一致，减少无意义的差异。
+- 在不影响清晰度的前提下，尽量简洁。
+
+## 原则
+
+1. **可读性优先**：读代码的时间远大于写代码。
+2. **一致性优先**：同一仓库内保持一致比追求“最优风格”更重要。
+3. **遵从既有代码**：修改/扩展现有代码时优先沿用其局部风格。
+
+## 适用范围
+
+- 本指南适用于所有 TSL 相关仓库与脚本。
+- 当现有代码与本指南冲突时，**以保持局部一致性为优先**，逐步迁移。
+
+## docs/（开发规范）
+
+`docs/` 目录是给开发者阅读的工程规范，约束代码写法、命名与提交信息。
+
+- `docs/index.md`：文档导航（跨语言 common / TSL 专属）。
+- `docs/common/commit_message.md`：提交信息与版本号规范（type/scope/subject/body/footer、可选 Emoji 图例、SemVer）。
+- `docs/tsl/code_style.md`：TSL 代码结构、格式、`begin/end` 代码块、注释与通用最佳实践。
+- `docs/tsl/naming.md`：TSL 命名规范（顶层声明、文件同名规则、变量/成员/property、常量、集合命名等）。
+
+## .agents/（代理规则）
+
+`.agents/` 目录是给自动化/AI 代理在本仓库内工作时遵守的规则，与 `docs/` 并行。
+
+- `.agents/index.md`：代理规则索引、适用范围与工作原则。
+- `.agents/auth.md`：安全与鉴权边界、敏感信息处理要求。
+- `.agents/performance.md`：性能优化原则、流程与验证要求。
+- `.agents/code_quality.md`：代码质量底线与 review 清单。
+- `.agents/testing.md`：测试策略与何时补测试。
+
+## 在其他项目中使用本 Playbook
+
+由于本仓库需要内部权限访问，其他项目**不能仅用外链引用**；推荐把 Playbook 规范 vendoring 到项目内。
+
+### 方式一：git subtree 同步（推荐）
+
+1. 在目标项目中首次引入：
+
+   ```bash
+   git subtree add \
+   --prefix docs/standards/tsl \
+   https://git.mytsl.cn/csh/tsl-playbook.git \
+   main --squash
+   ```
+
+2. 后续同步更新：
+
+   ```bash
+   git subtree pull \
+   --prefix docs/standards/tsl \
+   https://git.mytsl.cn/csh/tsl-playbook.git \
+   main --squash
+   ```
+
+#### 快速落地（最小 4 步）
+
+在目标项目中按以下顺序执行即可完成落地（推荐固定使用 `--prefix docs/standards/tsl`）：
+
+1. 引入标准快照（见上文 `git subtree add`）
+2. 同步到项目根目录（生成/更新 `.agents/tsl/`、更新 `.gitattributes`）：
+
+   ```bash
+   sh docs/standards/tsl/scripts/sync_standards.sh
+   ```
+
+3. 验收（任意满足其一即可）：
+
+   - 目录存在：`.agents/tsl/`
+   - 规则入口可读：`.agents/tsl/index.md`
+   - 标准文档可读：`docs/standards/tsl/docs/index.md`
+   - `.gitattributes` 包含区块：`# BEGIN tsl-playbook .gitattributes` / `# END tsl-playbook .gitattributes`
+
+4. 将同步产物纳入版本控制（目标项目建议提交）：
+   - `docs/standards/tsl/`（标准快照）
+   - `.agents/tsl/`（落地规则集）
+   - `.gitattributes`（managed block 更新）
+
+#### 可选：项目包装脚本（多 playbook 串联）
+
+多语言项目建议在目标项目创建一个包装脚本（便于一键同步多个规则集）：
+
+```sh
+#!/usr/bin/env sh
+set -eu
+
+sh docs/standards/tsl/scripts/sync_standards.sh
+# sh docs/standards/python/scripts/sync_standards.sh
+# sh docs/standards/cpp/scripts/sync_standards.sh
+```
+
+#### 目录约定（建议）
+
+目标项目推荐采用以下结构（Playbook 快照与项目文档分离）：
+
+```txt
+.
+├── .agents/
+│   ├── index.md                   # 多语言代理规则集索引（缺省时由脚本创建）
+│   └── tsl/                       # 从 Playbook 同步（仅覆盖该子目录）
+├── .gitattributes                 # 从 Playbook 同步
+├── docs/
+│   ├── standards/
+│   │   └── tsl/                   # git subtree 快照（只读）
+│   │       ├── docs/              # common/ + tsl/
+│   │       ├── .agents/           # 标准代理规则快照
+│   │       ├── .gitattributes
+│   │       └── SOURCE.md          # 记录来源版本/commit（项目自行维护）
+│   └── project/                   # 目标项目自己的文档（非语言标准：架构/运行/ADR/使用说明/业务约定等）
+└── README.md                      # 说明遵循 standards
+```
+
+根目录的 `.agents/tsl/` 与 `.gitattributes` 通过同步脚本获得：
+
+- 说明：在 **本 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.*`）。
+
+注：建议固定使用 `--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=block|overwrite|skip` 控制）
+- 缺省创建：`.agents/index.md`
+- 覆盖前备份：写入同目录的 `*.bak.*`（或 Windows 下随机后缀）
+- 不修改：`.gitignore`（项目自行维护）
+
+#### 环境变量（可选）
+
+同步脚本支持以下可选环境变量（默认值可满足大多数项目）：
+
+| 变量名              | 默认值  | 说明                                                                                        |
+| ------------------- | ------- | ------------------------------------------------------------------------------------------- |
+| `AGENTS_NS`         | `tsl`   | 规则集落地目录名：`.agents/<AGENTS_NS>/`                                                    |
+| `SYNC_GITATTR_MODE` | `block` | `.gitattributes` 同步模式：`block` 仅维护 managed 区块；`overwrite` 全量覆盖；`skip` 不更新 |
+
+### 方式二：手动复制快照
+
+如果不使用 `git subtree`，也可以由有权限的人手动复制 Playbook 到目标项目中（适合规范不频繁更新或项目数量较少的情况）。
+
+步骤：
+
+1. 在目标项目创建目录：`docs/standards/tsl/`。
+2. 从本仓库复制以下内容到目标项目：
+   - `docs/` → `docs/standards/tsl/docs/`（包含 `docs/common/` 与 `docs/tsl/`）
+   - `.agents/` → `docs/standards/tsl/.agents/`
+   - `.gitattributes` → `docs/standards/tsl/.gitattributes`
+   - `scripts/` → `docs/standards/tsl/scripts/`
+3. 在目标项目根目录运行同步脚本，把 `.agents/tsl/` 与 `.gitattributes` 落到根目录（见上文脚本路径）。
+4. 在 `docs/standards/tsl/SOURCE.md` 记录本次复制的来源版本/日期（建议写 Playbook 的 commit hash）。
+
+该方式没有自动同步能力，后续更新需重复上述复制流程。
+
+### 多语言项目落地（TSL + C++/其他语言）
+
+多语言项目建议把规范拆成两类：
+
+1. **仓库级（跨语言）共识**：对所有语言都成立的规则与流程。
+   - 提交信息：`docs/common/commit_message.md`
+   - 行尾与文本规范：`.gitattributes`
+   - 代理最低要求：`.agents/*`（工作原则、质量底线、安全边界）
+2. **语言级（Language-specific）规范**：只对某个语言成立的风格与工具。
+   - 例如 TSL 的命名/文件顶层声明限制、C++ 的 `.clang-format/.clang-tidy`、Python 的 `ruff` 等。
+
+建议：仓库级规则尽量少且稳定；语言级规则各自独立，避免互相“污染”。
+
+本仓库提供的代理规则集（同步后位于目标项目的 `.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++ 等语言/模块专属规则，建议二选一：
+
+1. **推荐：子目录规则覆盖（无需改同步脚本）**
+   - 让本 Playbook 的规则集固定落在 `.agents/tsl/`，由同步脚本维护。
+   - 在其他语言/模块目录下新增更具体规则，例如 `.agents/cpp/`、`cpp/.agents/`、`src/.agents/`。
+2. **Overlay 合并：项目维护叠加层并在同步后覆盖回去**
+   - 约定项目自定义规则放在 `docs/project/agents_overlay/`（不叫 `.agents`，避免被同步覆盖）。
+   - 每次运行 `sync_standards.*` 后，再把 overlay 覆盖回 `.agents/tsl/`（建议封装成项目脚本）。
+
+macOS/Linux 示例（目标项目的 `scripts/sync_standards.sh`）：
+
+```sh
+#!/usr/bin/env sh
+set -eu
+
+sh docs/standards/tsl/scripts/sync_standards.sh
+
+OVERLAY="docs/project/agents_overlay"
+if [ -d "$OVERLAY" ]; then
+  cp -R "$OVERLAY"/. ".agents/tsl/"
+  echo "Applied agents overlay."
+fi
+```
+
+PowerShell 示例（目标项目的 `scripts/sync_standards.ps1`）：
+
+```powershell
+$ErrorActionPreference = "Stop"
+
+& "docs/standards/tsl/scripts/sync_standards.ps1"
+
+$overlay = "docs/project/agents_overlay"
+if (Test-Path $overlay) {
+  Copy-Item "$overlay\\*" ".agents\\tsl" -Recurse -Force
+  Write-Host "Applied agents overlay."
+}
+```
+
+#### 扩展新语言（模板）
+
+当目标项目需要新增一门语言（例如 C++），建议按以下模板扩展：
+
+- 文档：在目标项目增加 `docs/standards/cpp/docs/`（或另一个标准仓库 subtree），并在项目 `README.md`/`docs/index.md` 链接入口。
+- 代理规则：在目标项目增加 `.agents/cpp/`（与 `.agents/tsl/` 并行），只写 C++ 专属要求与工具链约束。
+- 同步策略：每个规则集只同步到对应子目录（例如 `.agents/cpp/`），避免覆盖整个 `.agents/`。
+- CI/工具：按文件类型分别执行格式化、lint、测试（不要让 TSL 规则去约束 C++ 代码，反之亦然）。
+
+## 版本与贡献
+
+- 本项目会持续迭代；变更以 PR 形式提交。
+- 新规则需包含动机、示例、迁移建议（如有）。

docs/common/commit_message.md

@@ -0,0 +1,161 @@
+# 提交信息规范（Commit Messages）
+
+提交信息用于清晰表达变更意图、范围和原因，便于回溯与自动化发布。
+
+## 1. 目标
+
+- 让每次提交都能被独立理解。
+- 支持快速定位问题与版本回滚。
+- 可被工具解析（变更日志/发布流程）。
+
+## 2. 格式
+
+推荐使用以下结构（emoji 可选）：
+
+```
+:emoji: type(scope): subject
+
+body
+
+footer
+```
+
+- `emoji`：可选，位于首行行首；若使用，必须与 `type` 一一对应（见 4）。
+- `type`：变更类型，必须从 4 的对应表中选取。
+- `scope`：可选，业务域/组件名（`lower_snake_case`），用于辅助定位影响范围。
+- `subject`：一句话概述，使用祈使句/现在时，首字母小写，不加句号。
+- `body`：可选，说明动机、关键实现、影响面；每行建议 ≤ 72 字符。
+- `footer`：可选，关联任务/缺陷号，或 `BREAKING CHANGE:` 说明不兼容变更。
+
+不使用 emoji 时，首行直接写 `type(scope): subject` 即可。
+
+## 3. 约定
+
+### 3.1 一次提交的边界
+
+- 一个提交对应一个**逻辑变更**，而不是一个文件或一个模块。
+- 可以同时修改多个 `unit/class/function`，只要它们属于同一逻辑变更。
+- **允许合并的情况**：联动修改是变更所必需的同步/适配（不一起提会导致编译失败、测试失败或行为不一致）。
+  - 例：改了 A 的接口签名，同时更新 B 的调用点。
+- **应当拆分的情况**：改动彼此独立，仅是“顺手优化/无关重构/额外功能”。
+  - 例：在修复 A 的 bug 时顺便重构 B 的内部实现。
+- 实用判断：
+  1. 这次提交能用一句话概括吗？若需要两句话，考虑拆分。
+  2. 若只回滚其中一部分，系统还能保持正确吗？不能则不拆。
+  3. 每个提交是否都能保持可运行/可构建/测试不更坏？做不到则合并。
+
+### 3.2 大模块重构的提交拆分
+
+当重构整个模块并影响到其他模块时，建议按“可回滚的小步”拆分提交：
+
+1. **前置整理**：仅做无行为影响的清理（重命名、抽函数、补注释/类型、补测试）。
+2. **核心重构**：在模块内部做结构调整，尽量保持对外接口不变；必要时加适配层。
+3. **迁移调用方**：逐步把其他模块迁移到新接口/新行为上。
+4. **清理旧接口**：确认无人使用后再删除适配层/旧代码。
+
+若重构为破坏性变更，优先采用“两阶段”：先引入新接口并兼容旧接口（deprecated），迁移完成后再删除旧接口。
+
+### 3.3 其他约定
+
+- `subject` 尽量 ≤ 72 字符；必要时用 `body` 补充细节。
+- `body/footer` 说明“为什么改、影响什么”，而不是复述代码。
+
+## 4. 提交类型与 Emoji 对应
+
+本仓库采用固定的 `type`/emoji 一一对应关系；使用 emoji 时必须使用对应的那一个，不得错配。
+
+| type        | emoji（预览 / 代码）              | 说明                         |
+| ----------- | --------------------------------- | ---------------------------- |
+| `init`      | :tada: `:tada:`                   | 初始化/首次发布              |
+| `feat`      | :sparkles: `:sparkles:`           | 新功能                       |
+| `fix`       | :bug: `:bug:`                     | Bug 修复                     |
+| `perf`      | :rocket: `:rocket:`               | 性能优化                     |
+| `refactor`  | :recycle: `:recycle:`             | 重构（行为不变）             |
+| `style`     | :art: `:art:`                     | 代码样式/格式（行为不变）    |
+| `docs`      | :memo: `:memo:`                   | 文档更新                     |
+| `test`      | :white_check_mark: `:white_check_mark:` | 测试新增/修正           |
+| `deps`      | :package: `:package:`             | 依赖更新                     |
+| `security`  | :lock: `:lock:`                   | 安全修复                     |
+| `deprecate` | :warning: `:warning:`             | 废弃/弃用标记                |
+| `remove`    | :wastebasket: `:wastebasket:`     | 删除功能/代码                |
+| `chore`     | :wrench: `:wrench:`               | 构建/配置/工具/维护性改动    |
+| `contrib`   | :busts_in_silhouette: `:busts_in_silhouette:` | 贡献者/致谢相关 |
+| `release`   | :bookmark: `:bookmark:`           | 发布/打版本标签              |
+
+注：`:white_check_mark:` 为补充图例，用于 `test` 类型。
+
+如需新增新的 `type`，必须同时补充对应 emoji 与说明。
+
+---
+
+## 5. 版本号规范（SemVer）
+
+遵循语义化版本规范。
+
+### 5.1 格式
+
+```txt
+MAJOR.MINOR.PATCH
+```
+
+### 5.2 字段说明
+
+| 字段      | 说明     | 何时递增           |
+| --------- | -------- | ------------------ |
+| **MAJOR** | 主版本号 | 不兼容的 API 修改  |
+| **MINOR** | 次版本号 | 向后兼容的功能新增 |
+| **PATCH** | 修订号   | 向后兼容的问题修正 |
+
+### 5.3 更新规则
+
+- **MAJOR（主版本）**：破坏性变更，不向后兼容。递增后 MINOR 和 PATCH 重置为 0。
+- **MINOR（次版本）**：新增功能但保持兼容。递增后 PATCH 重置为 0。
+- **PATCH（修订）**：仅修复 bug，不新增功能。
+
+### 5.4 示例
+
+```txt
+1.0.0    # 首个稳定版
+1.1.0    # 新增功能
+1.1.1    # Bug 修复
+2.0.0    # 破坏性变更
+```
+
+### 5.5 Pre-release 版本
+
+```txt
+1.0.0-alpha.1
+1.0.0-beta
+1.0.0-rc.1
+1.0.0
+```
+
+### 5.6 初始开发阶段
+
+```txt
+0.1.0    # 初始版本
+0.2.0    # API 未稳定
+1.0.0    # 首个稳定版
+```
+
+注意：`0.x.x` 版本可以随时破坏兼容性。
+
+---
+
+## 6. 示例
+
+带 emoji：
+
+```
+:sparkles: feat(order): add batch cancel api
+
+support canceling multiple orders in one request; keep old api unchanged.
+
+Refs: TSL-1234
+```
+
+不带 emoji：
+
+```
+refactor(order): simplify cancel flow
+```

docs/index.md

@@ -0,0 +1,13 @@
+# 文档导航（Docs Index）
+
+本仓库文档按“跨语言共识 / 语言专属”分层组织，便于在多语言项目中扩展与复用。
+
+## 跨语言（common）
+
+- 提交信息与版本号：`common/commit_message.md`
+
+## TSL（tsl）
+
+- TSL 源文件后缀同时包含：`.tsl`（脚本）与 `.tsf`（模块/库代码）。
+- 代码风格：`tsl/code_style.md`
+- 命名规范：`tsl/naming.md`

docs/tsl/code_style.md

@@ -0,0 +1,123 @@
+# TSL 代码风格（Code Style）
+
+本章节规定 TSL 代码的结构与格式约定。
+
+## 1. 文件与组织
+
+- 一个文件只做一件事；职责明确。
+- 文件名使用 `PascalCase`，并与文件内唯一的顶层声明同名（语法要求）。扩展名按类型使用 `.tsl`/`.tsf`（两者都属于 TSL 源文件，风格规则一致）。
+- 避免循环依赖；公共能力下沉到可复用模块。
+- 同类代码按“对外 API → 核心实现 → 辅助工具 → 测试/示例”的顺序组织。
+
+## 2. 格式（Formatting）
+
+### 2.1 缩进与空白
+
+- 使用**空格缩进**，禁止 Tab。
+- 默认缩进 **4 个空格**；继续缩进保持与上层语义一致。
+- 行尾不留空格；文件以换行符结尾。
+- 逻辑块之间用空行分隔，不要用空行堆砌。
+
+### 2.2 行宽与换行
+
+- 单行建议不超过 **100 字符**；超过时应换行以保持可读性。
+- 换行遵循“**断在运算符后**、对齐到语义层级”的原则。
+- 长字符串/URL 可适当超出，但避免影响阅读。
+
+### 2.3 begin/end 与代码块
+
+- 代码块使用统一的块结构（示例为伪代码，按 TSL 语法调整）：
+
+```tsl
+if cond then
+begin
+    DoSomething()
+end
+else
+begin
+    DoOther()
+end
+```
+
+- 多语句分支使用 `begin/end` 包裹：在 `then/else` 后换行写 `begin`，`end` 单独成行。
+- `else/elseif` 等分支关键字另起一行，与上一块的 `end` 对齐。
+
+### 2.4 运算符与分隔符
+
+- 二元运算符两侧加空格：`a + b`、`x == y`。
+- 一元运算符不加空格：`!flag`、`-value`。
+- 逗号后加空格：`f(a, b, c)`。
+- 不要为了对齐而插入多余空格；让格式由缩进表达结构。
+
+### 2.5 控制流
+
+- 多语句分支必须使用 `begin/end`；单语句分支可省略 `begin/end`，写成单行（如 `if cond then stmt`）。
+- 复杂条件拆分为具名布尔变量或小函数。
+- 早返回优于深层嵌套：
+
+```tsl
+if !ok then return err
+// main path
+```
+
+## 3. 注释（Comments）
+
+注释用于解释**为什么**以及必要的背景，而不是重复代码。
+
+### 3.1 文件级注释
+
+- 文件开头说明用途、主要职责、关键依赖/约束。
+- 若文件实现某个对外 API，写明入口与预期行为。
+
+### 3.2 函数/接口注释
+
+- 对外可见的函数必须写注释，包含：
+  - 做什么（行为）
+  - 入参/返回值含义（必要时含单位、范围）
+  - 关键副作用与异常情况
+- 注释使用完整句子，末尾带标点。
+
+### 3.3 行内注释
+
+- 用于解释复杂逻辑、非直观边界条件、性能/安全考量。
+- 避免“显而易见注释”：
+
+```tsl
+count = count + 1  // bad: obvious
+```
+
+### 3.4 TODO/FIXME
+
+- 统一格式：`TODO(name): ...` / `FIXME(name): ...`
+- 写清原因和期望修复方向，而非“留个坑”。
+
+## 4. 代码实践（Best Practices）
+
+### 4.1 变量与常量
+
+- 默认使用不可变/只读（如语法支持 `const` 或等价机制）。
+- 变量声明与第一次使用尽量靠近。
+- 避免隐藏式类型转换与隐式全局。
+
+### 4.2 函数设计
+
+- 函数参数建议显式写类型注解，提升可读性与工具检查能力。
+- 无返回值函数显式标注返回类型为 `void`。
+
+```tsl
+function Func(a: string; b: ClassName): void;
+```
+
+- 单一职责；函数过长说明拆分点已出现（建议 ≤ 40–60 行）。
+- 参数顺序：输入参数在前，输出/回调在后。
+- 尽量避免超过 5 个参数；必要时封装为对象（class/unit）。
+
+### 4.3 错误处理
+
+- 错误必须显式处理：返回错误、抛出异常或记录并降级（按项目约定）。
+- 不要吞掉异常/错误；必须加注释说明原因。
+
+### 4.4 性能与可测试性
+
+- 避免过早优化；先写清晰正确的代码，再用数据驱动优化。
+- 复杂逻辑要可测试：拆成纯函数或可注入依赖的模块。

docs/tsl/naming.md

@@ -0,0 +1,152 @@
+# TSL 命名规范（Naming）
+
+本仓库命名规则与 Google C++ Style Guide 对齐：通过名字的“形状”快速判断实体类型（类型/函数/变量/常量等），减少阅读成本。
+
+## 1. 选名原则
+
+- **可读一致**：名字清晰可读，并随可见范围调整具体程度。
+- **少用生僻缩写**：能写全称就写全称。
+- **驼峰/帕斯卡中的缩写规则**：缩写（首字母缩写/词组缩写）在 `PascalCase`/`camelCase` 中**按一个单词处理**，写成“首字母大写其余小写”，不要写一串全大写。
+  - 示例：`UserId`（不是 `UserID`）、`UrlTable`（不是 `URLTable`）、
+    `StartRpcServer`（不是 `StartRPCServer`）、`HttpClient`（不是 `HTTPClient`）。
+- **避免无意义词**：如 `data`、`info`、`tmp`、`handle` 等。
+
+## 2. 命名风格总览
+
+对于以下规则，“单词”指英文中不带空格的词。
+
+- `snake_case`：全小写，下划线分隔单词，用于普通变量/参数等；私有类成员变量在此基础上末尾加下划线。
+- `PascalCase`（`UpperCamelCase`）：每个单词首字母大写，无下划线，用于类型、顶层函数/方法、property，以及（少量）公有成员字段。
+
+**大小写与关键字约定**
+
+- TSL 语言大小写无关，但本指南仍要求按约定使用大小写以提升可读性；不要用仅大小写不同的名字区分不同实体。
+- 所有语法关键字统一使用全小写书写，例如 `if`、`for`、`class`、`function`、`unit`、`return` 等。
+- 调用内置/标准库方法时，推荐保持官方大小写形式（`aaBBCC`/lowerCamelCase），例如 `getSysParams("xxx")`。
+
+
+## 3. 类型命名（Type Names）
+
+TSL 的顶层声明只有三种：`class`、`unit`、`function`。
+
+- **类（class）与单元（unit）**使用 `PascalCase`，不带下划线。
+- **顶层函数（function）**使用 `PascalCase`，详见函数命名章节。
+- 示例：`UserAccount`、`OrderUnit`、`LoadMarketData()`。
+
+## 4. 文件命名与顶层声明（File Names）
+
+TSL 的语法要求：每个文件只能有一个顶层声明，且**文件基名必须与该顶层声明名字一致**。
+
+- 顶层声明可能是 `class`、`unit` 或 `function`（见类型命名）。
+- `.tsl` 脚本文件：顶层声明只能是 `function`，因此文件基名 = 顶层函数名。
+- `.tsf` 代码文件：顶层声明可为 `class`/`unit`/`function`，文件基名需与之同名。
+  - 注：`.tsf` 也是 TSL 源文件，命名/风格与 `.tsl` 遵循同一套规则。
+
+命名建议：
+
+- 基名统一使用 `PascalCase`，与顶层声明的推荐写法一致。
+- 示例：
+  - `LoadMarketData.tsl` 中定义 `function LoadMarketData(...)`.
+  - `UserAccount.tsf` 中定义 `type UserAccount = class ... end;`.
+  - `DocxEnumerations.tsf` 中定义 `unit DocxEnumerations; ... end.`
+
+注：TSL 大小写无关，实际编译时按大小写比较不会出错，但仍应保持文件名与声明名的推荐写法一致以便检索与协作。
+
+## 5. 变量命名（Variable Names）
+
+### 5.1 普通变量与参数
+
+- **局部变量、函数参数、非成员变量**使用 `snake_case`。
+- 若参数名与 TSL 关键字冲突导致编译失败，使用前导下划线的 `snake_case` 作为例外，例如 `_type`、`_unit`。
+- 前导下划线 `_` **仅用于上述关键字冲突的参数场景**，不要用于其他局部变量、成员变量、函数/类型/单元名称或全局变量。
+- 示例：`table_name`、`max_retry_count`、`user_id`。
+
+### 5.2 类成员（Class Data Members）
+
+- **私有成员变量**使用 `snake_case_`（尾随下划线）。
+- 尾随下划线 `_` **仅用于私有成员变量**，不要用于局部变量、参数、公有成员字段、property 名称或顶层全局变量。
+- **公有成员变量**若必须存在，使用 `PascalCase`；但**不推荐外部直接访问公有字段**。
+- 对外暴露的成员优先使用 **property**：
+  - property 名称使用 `PascalCase`（视为对外 API）。
+  - property 的 `read/write` 指向真实成员（通常为私有 `snake_case_`）。
+- 示例：
+
+```tsl
+type User = class
+public
+    property UserId read user_id_ write user_id_;
+private
+    user_id_;
+end;
+```
+
+### 5.3 全局/静态变量
+
+- 不推荐使用顶层全局/静态可变变量；优先封装到 `unit`/`class` 中，通过函数或 property 访问。
+- 若必须声明顶层全局/静态变量，使用 `g_snake_case` 前缀显式标识其全局性质，例如 `g_user_cache`、`g_market_state`。
+- 全局/静态常量仍按常量规则使用 `kPascalCase`。
+
+### 5.4 布尔变量
+
+- 使用 `is_ / has_ / can_ / should_` 等前缀表达语义。
+- 示例：`is_ready`、`has_error`、`can_retry`。
+
+### 5.5 短名例外
+
+- 在极小作用域内可用习惯短名：`i`、`j`、`n`、`t` 等。
+- 作用域一旦扩大，必须改为有含义的名字。
+
+### 5.6 集合与复数命名（Collections）
+
+- **数组/列表/可迭代集合**使用复数名词的 `snake_case`：`users`、`order_items`。
+- 若复数形式不直观或为不可数名词，使用后缀明确类型：`news_list`、`price_items`。
+- **映射/字典（key→value）**使用 `snake_case` 并加后缀 `_map`，必要时可用 `_by_<key>` 表达键语义：`user_map`、`price_by_symbol`。
+- **集合/去重集合**使用后缀 `_set`：`user_id_set`、`symbol_set`。
+
+## 6. 常量命名（Constant Names）
+
+- **编译期/全局期固定的常量**使用 `kPascalCase`，以 `k` 开头。
+- 示例：`kDaysInAWeek`、`kAndroid8_0_0`。
+- 对于**局部 const 但值来自参数/运行时**的变量：
+  - 可用普通变量名 `snake_case`；
+  - 不要用 `k` 前缀误导读者认为其全局固定。
+
+### 6.1 单元枚举模拟（Unit Enumerations）
+
+TSL 没有内置 `enum`，推荐使用 `unit` + `const` 在 `interface` 区域模拟枚举集合。
+
+- `unit` 名称使用 `PascalCase`，建议以 `Enumerations`/`Enums` 结尾表达用途。
+- 枚举值使用 `const` 定义并放在 `interface` 中；命名优先沿用外部/业务域既有前缀与风格（属于例外场景）。
+
+示例：
+
+```tsl
+unit DocxEnumerations;
+interface
+
+    // WdAlertLevel
+    const wdAlertsAll = -1;
+end.
+```
+
+## 7. 函数与方法命名（Function Names）
+
+- 所有**普通**函数/方法（包含 `public`/`private`）均使用 `PascalCase`。
+- **特殊函数/运算符重载为语法固定名，必须使用全小写**：
+  - 构造/初始化函数：`create`。
+  - 析构/释放函数：`destroy`。
+  - 运算符重载：`operator+()` 等，按语法使用小写 `operator<op>()` 形式。
+- 示例：`AddTableEntry()`、`DeleteUrl()`、`OpenFileOrDie()`。
+- **推荐使用 property 语法**对外暴露访问器：property 名 `PascalCase`，`read/write` 绑定成员变量（见类成员章节）。
+- 不推荐新增显式 getter/setter；仅当 property 无法表达语义时，才使用 getter/setter，命名可与字段同形的 `snake_case`（如 `count()`、`set_count(x)`）。
+
+## 8. 宏与编译期开关（Macro Names）
+
+- 能不用宏就不用。
+- 必须使用时，命名为全大写加下划线，并带项目/业务前缀：
+  - `TSL_ROUND(x)`、`TSL_ENABLE_FOO`。
+
+## 9. 例外（Exceptions）
+
+- 当命名需要与外部既有 API/协议保持一致时，可沿用对方风格。
+- 例如对接 C/C++ 库、历史接口、跨语言互操作代码等。

scripts/sync_standards.bat

@@ -0,0 +1,170 @@
+@echo off
+setlocal enabledelayedexpansion
+
+rem Sync standards snapshot to project root.
+rem - Copies <snapshot>\.agents -> <project-root>\.agents\tsl
+rem - Updates <project-root>\.gitattributes (managed block by default)
+rem Existing targets are backed up before overwrite.
+
+set "SCRIPT_DIR=%~dp0"
+for /f "delims=" %%R in ('git -C "%SCRIPT_DIR%" rev-parse --show-toplevel 2^>nul') do set "ROOT=%%R"
+if "%ROOT%"=="" set "ROOT=%cd%"
+for %%I in ("%ROOT%") do set "ROOT=%%~fI"
+
+for %%I in ("%SCRIPT_DIR%..") do set "SRC=%%~fI"
+set "AGENTS_SRC=%SRC%\.agents"
+set "GITATTR_SRC=%SRC%\.gitattributes"
+set "AGENTS_NS=%AGENTS_NS%"
+if "%AGENTS_NS%"=="" set "AGENTS_NS=tsl"
+echo %AGENTS_NS%| findstr /r "[\\/]" >nul && (
+  echo ERROR: invalid AGENTS_NS=%AGENTS_NS%
+  exit /b 1
+)
+echo %AGENTS_NS%| findstr /c:".." >nul && (
+  echo ERROR: invalid AGENTS_NS=%AGENTS_NS%
+  exit /b 1
+)
+set "AGENTS_ROOT=%ROOT%\.agents"
+set "AGENTS_DST=%AGENTS_ROOT%\%AGENTS_NS%"
+set "GITATTR_DST=%ROOT%\.gitattributes"
+set "SYNC_GITATTR_MODE=%SYNC_GITATTR_MODE%"
+if "%SYNC_GITATTR_MODE%"=="" set "SYNC_GITATTR_MODE=block"
+
+if not exist "%AGENTS_SRC%" (
+  echo ERROR: Standards snapshot not found at "%AGENTS_SRC%".
+  echo Run: git subtree add --prefix ^<your-prefix^> ^<standards-url^> ^<branch^> --squash
+  exit /b 1
+)
+
+if /I "%SRC%"=="%ROOT%" (
+  echo Skip: snapshot root equals project root.
+  goto AfterGitAttr
+)
+
+if not exist "%AGENTS_ROOT%" mkdir "%AGENTS_ROOT%"
+
+if exist "%AGENTS_DST%" (
+  set "RAND=%RANDOM%"
+  pushd "%AGENTS_ROOT%"
+  ren "%AGENTS_NS%" "%AGENTS_NS%.bak.!RAND!"
+  popd
+  echo Backed up existing %AGENTS_NS% agents -> %AGENTS_NS%.bak.!RAND!
+)
+
+xcopy "%AGENTS_SRC%\\*" "%AGENTS_DST%\\" /e /i /y >nul
+if errorlevel 1 (
+  echo ERROR: failed to copy .agents
+  exit /b 1
+)
+
+echo Synced .agents\%AGENTS_NS% from standards.
+
+if not exist "%AGENTS_ROOT%\index.md" (
+  > "%AGENTS_ROOT%\index.md" echo # .agents（多语言）
+  >> "%AGENTS_ROOT%\index.md" echo.
+  >> "%AGENTS_ROOT%\index.md" echo 本目录用于存放仓库级/语言级的代理规则集。
+  >> "%AGENTS_ROOT%\index.md" echo.
+  >> "%AGENTS_ROOT%\index.md" echo 建议约定：
+  >> "%AGENTS_ROOT%\index.md" echo.
+  >> "%AGENTS_ROOT%\index.md" echo - `.agents/tsl/`：TSL 相关规则集（由 `sync_standards.*` 同步；适用于 `.tsl`/`.tsf`）
+  >> "%AGENTS_ROOT%\index.md" echo - `.agents/cpp/`、`.agents/python/` 等：其他语言的规则集（按需增加）
+  >> "%AGENTS_ROOT%\index.md" echo.
+  >> "%AGENTS_ROOT%\index.md" echo 规则发生冲突时，建议以“更靠近代码的目录规则更具体”为准。
+  >> "%AGENTS_ROOT%\index.md" echo.
+  >> "%AGENTS_ROOT%\index.md" echo 入口建议从：
+  >> "%AGENTS_ROOT%\index.md" echo.
+  >> "%AGENTS_ROOT%\index.md" echo - `.agents/tsl/index.md`（TSL 规则集入口）
+  >> "%AGENTS_ROOT%\index.md" echo - `docs/standards/tsl/docs/tsl/`（TSL 人类开发规范快照，推荐 subtree/vendoring 到该路径）
+  echo Created .agents\index.md
+)
+
+:SyncGitAttr
+if exist "%GITATTR_SRC%" (
+  if /I "%SYNC_GITATTR_MODE%"=="skip" (
+    echo Skip: .gitattributes sync ^(SYNC_GITATTR_MODE=skip^).
+    goto AfterGitAttr
+  )
+
+  if /I "%SYNC_GITATTR_MODE%"=="overwrite" (
+    for %%I in ("%GITATTR_SRC%") do set "GITATTR_SRC_F=%%~fI"
+    for %%I in ("%GITATTR_DST%") do set "GITATTR_DST_F=%%~fI"
+    if /I "!GITATTR_SRC_F!"=="!GITATTR_DST_F!" (
+      echo Skip: .gitattributes source equals destination.
+      goto AfterGitAttr
+    )
+
+    if exist "%GITATTR_DST%" (
+      set "RAND=%RANDOM%"
+      set "BAK_NAME=.gitattributes.bak.!RAND!"
+      ren "%GITATTR_DST%" "!BAK_NAME!"
+      echo Backed up existing .gitattributes -> !BAK_NAME!
+    )
+    copy /y "%GITATTR_SRC%" "%GITATTR_DST%" >nul
+    echo Synced .gitattributes from standards ^(overwrite^).
+    goto AfterGitAttr
+  )
+
+  if /I not "%SYNC_GITATTR_MODE%"=="block" (
+    echo ERROR: invalid SYNC_GITATTR_MODE=%SYNC_GITATTR_MODE% ^(use block^|overwrite^|skip^) 
+    exit /b 1
+  )
+
+  rem block mode: maintain a managed block inside the destination file
+  set "BEGIN=# BEGIN tsl-playbook .gitattributes"
+  set "END=# END tsl-playbook .gitattributes"
+  set "TMP_FILE=%TEMP%\\gitattributes.%RANDOM%.tmp"
+
+  if exist "%GITATTR_DST%" (
+    set "RAND=%RANDOM%"
+    set "BAK_NAME=.gitattributes.bak.!RAND!"
+    ren "%GITATTR_DST%" "!BAK_NAME!"
+    echo Backed up existing .gitattributes -> !BAK_NAME!
+    set "DST_IN=%ROOT%\\!BAK_NAME!"
+  ) else (
+    set "DST_IN="
+  )
+
+  set "IN_BLOCK=0"
+  set "DONE=0"
+
+  if not "%DST_IN%"=="" (
+    > "!TMP_FILE!" (
+      for /f "usebackq delims=" %%L in ("!DST_IN!") do (
+        set "LINE=%%L"
+        if "!LINE!"=="%BEGIN%" (
+          if "!DONE!"=="0" (
+            echo %BEGIN%
+            type "%GITATTR_SRC%"
+            echo %END%
+            set "DONE=1"
+          )
+          set "IN_BLOCK=1"
+        ) else if "!LINE!"=="%END%" (
+          set "IN_BLOCK=0"
+        ) else (
+          if "!IN_BLOCK!"=="0" echo(!LINE!
+        )
+      )
+      if "!DONE!"=="0" (
+        echo.
+        echo %BEGIN%
+        type "%GITATTR_SRC%"
+        echo %END%
+      )
+    )
+  ) else (
+    > "!TMP_FILE!" (
+      echo %BEGIN%
+      type "%GITATTR_SRC%"
+      echo %END%
+    )
+  )
+
+  copy /y "!TMP_FILE!" "%GITATTR_DST%" >nul
+  del /q "!TMP_FILE!" >nul 2>nul
+  echo Updated .gitattributes from standards ^(managed block^).
+)
+
+:AfterGitAttr
+echo Done.
+endlocal

scripts/sync_standards.ps1

@@ -0,0 +1,127 @@
+# Sync standards snapshot to project root.
+# - Copies <snapshot>/.agents -> <project-root>/.agents/tsl
+# - Updates <project-root>/.gitattributes (managed block by default)
+# Existing targets are backed up before overwrite.
+$ErrorActionPreference = "Stop"
+
+$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$Src = (Resolve-Path (Join-Path $ScriptDir "..")).Path
+
+$Root = (git -C $ScriptDir rev-parse --show-toplevel 2>$null)
+if (-not $Root) { $Root = (Get-Location).Path }
+$Root = (Resolve-Path $Root).Path
+
+$AgentsSrc = Join-Path $Src ".agents"
+$GitAttrSrc = Join-Path $Src ".gitattributes"
+
+if (-not (Test-Path $AgentsSrc)) {
+  throw "Standards snapshot not found at $AgentsSrc. Run git subtree add first (choose any prefix)."
+}
+
+$timestamp = Get-Date -Format "yyyyMMddHHmmss"
+
+$AgentsNs = $env:AGENTS_NS
+if (-not $AgentsNs) { $AgentsNs = "tsl" }
+if ($AgentsNs -match '[\\/]' -or $AgentsNs -match '\.\.') {
+  throw "Invalid AGENTS_NS=$AgentsNs"
+}
+$AgentsRoot = Join-Path $Root ".agents"
+$AgentsDst = Join-Path $AgentsRoot $AgentsNs
+
+if ($Src -ieq $Root) {
+  Write-Host "Skip: snapshot root equals project root."
+  Write-Host "Done."
+  exit 0
+}
+
+New-Item -ItemType Directory -Path $AgentsRoot -Force | Out-Null
+
+if (Test-Path $AgentsDst) {
+  $bak = (Join-Path $AgentsRoot "$AgentsNs.bak.$timestamp")
+  Move-Item $AgentsDst $bak
+  Write-Host "Backed up existing $AgentsNs agents -> $(Split-Path -Leaf $bak)"
+}
+
+New-Item -ItemType Directory -Path $AgentsDst -Force | Out-Null
+Copy-Item (Join-Path $AgentsSrc "*") $AgentsDst -Recurse -Force
+Write-Host "Synced .agents/$AgentsNs from standards."
+
+$AgentsIndex = Join-Path $AgentsRoot "index.md"
+if (-not (Test-Path $AgentsIndex)) {
+@'
+# .agents（多语言）
+
+本目录用于存放仓库级/语言级的代理规则集。
+
+建议约定：
+
+- `.agents/tsl/`：TSL 相关规则集（由 `sync_standards.*` 同步；适用于 `.tsl`/`.tsf`）
+- `.agents/cpp/`、`.agents/python/` 等：其他语言的规则集（按需增加）
+
+规则发生冲突时，建议以“更靠近代码的目录规则更具体”为准。
+
+入口建议从：
+
+- `.agents/tsl/index.md`（TSL 规则集入口）
+- `docs/standards/tsl/docs/tsl/`（TSL 人类开发规范快照，推荐 subtree/vendoring 到该路径）
+'@ | Set-Content -Path $AgentsIndex -Encoding UTF8
+  Write-Host "Created .agents/index.md"
+}
+
+$GitAttrDst = Join-Path $Root ".gitattributes"
+if (Test-Path $GitAttrSrc) {
+  $mode = $env:SYNC_GITATTR_MODE
+  if (-not $mode) { $mode = "block" }
+  switch ($mode.ToLowerInvariant()) {
+    "skip" {
+      Write-Host "Skip: .gitattributes sync (SYNC_GITATTR_MODE=skip)."
+      break
+    }
+    "overwrite" {
+      if ($GitAttrSrc -ieq $GitAttrDst) {
+        Write-Host "Skip: .gitattributes source equals destination."
+        break
+      }
+      if (Test-Path $GitAttrDst) {
+        $bak = "$GitAttrDst.bak.$timestamp"
+        Move-Item $GitAttrDst $bak
+        Write-Host "Backed up existing .gitattributes -> $bak"
+      }
+      Copy-Item $GitAttrSrc $GitAttrDst -Force
+      Write-Host "Synced .gitattributes from standards (overwrite)."
+      break
+    }
+    "block" {
+      $begin = "# BEGIN tsl-playbook .gitattributes"
+      $end = "# END tsl-playbook .gitattributes"
+      $src = Get-Content -Path $GitAttrSrc -Raw
+      $block = $begin + "`r`n" + $src.TrimEnd() + "`r`n" + $end + "`r`n"
+
+      $dst = ""
+      if (Test-Path $GitAttrDst) {
+        $bak = "$GitAttrDst.bak.$timestamp"
+        Move-Item $GitAttrDst $bak
+        Write-Host "Backed up existing .gitattributes -> $bak"
+        $dst = Get-Content -Path $bak -Raw
+      }
+
+      $pattern = "(?ms)^" + [regex]::Escape($begin) + "\\R.*?^" + [regex]::Escape($end) + "\\R?"
+      if ($dst -and ($dst -match $pattern)) {
+        $new = [regex]::Replace($dst, $pattern, $block)
+      } elseif ($dst) {
+        $new = $dst.TrimEnd() + "`r`n`r`n" + $block
+      } else {
+        $new = $block
+      }
+
+      $new | Set-Content -Path $GitAttrDst -Encoding UTF8
+      Write-Host "Updated .gitattributes from standards (managed block)."
+      break
+    }
+    default {
+      throw "Invalid SYNC_GITATTR_MODE=$mode (use block|overwrite|skip)"
+    }
+  }
+}
+
+Write-Host "Done."

scripts/sync_standards.sh

@@ -0,0 +1,146 @@
+#!/usr/bin/env sh
+set -eu
+
+# Sync standards snapshot to project root.
+# - Copies <snapshot>/.agents -> <project-root>/.agents/tsl
+# - Updates <project-root>/.gitattributes (managed block by default)
+# Existing targets are backed up before overwrite.
+
+SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd -P)"
+SRC="$(CDPATH= cd -- "$SCRIPT_DIR/.." && pwd -P)"
+ROOT="$(git -C "$SCRIPT_DIR" rev-parse --show-toplevel 2>/dev/null || pwd)"
+ROOT="$(CDPATH= cd -- "$ROOT" && pwd -P)"
+AGENTS_SRC="$SRC/.agents"
+GITATTR_SRC="$SRC/.gitattributes"
+
+if [ ! -d "$AGENTS_SRC" ]; then
+  echo "ERROR: Standards snapshot not found at $AGENTS_SRC" >&2
+  echo "Run: git subtree add --prefix <your-prefix> <standards-url> <branch> --squash" >&2
+  exit 1
+fi
+
+timestamp="$(date +%Y%m%d%H%M%S 2>/dev/null || echo bak)"
+
+if [ "$SRC" = "$ROOT" ]; then
+  echo "Skip: snapshot root equals project root."
+  echo "Done."
+  exit 0
+fi
+
+: "${AGENTS_NS:=tsl}"
+case "$AGENTS_NS" in
+  ""|*/*|*\\*|*..*)
+    echo "ERROR: invalid AGENTS_NS=$AGENTS_NS" >&2
+    exit 1
+    ;;
+esac
+
+AGENTS_ROOT="$ROOT/.agents"
+AGENTS_DST="$AGENTS_ROOT/$AGENTS_NS"
+mkdir -p "$AGENTS_ROOT"
+
+if [ -e "$AGENTS_DST" ]; then
+  mv "$AGENTS_DST" "$AGENTS_ROOT/$AGENTS_NS.bak.$timestamp"
+  echo "Backed up existing $AGENTS_NS agents -> $AGENTS_NS.bak.$timestamp"
+fi
+
+cp -R "$AGENTS_SRC" "$AGENTS_DST"
+echo "Synced .agents/$AGENTS_NS from standards."
+
+AGENTS_INDEX="$AGENTS_ROOT/index.md"
+if [ ! -f "$AGENTS_INDEX" ]; then
+  cat >"$AGENTS_INDEX" <<'EOF'
+# .agents（多语言）
+
+本目录用于存放仓库级/语言级的代理规则集。
+
+建议约定：
+
+- `.agents/tsl/`：TSL 相关规则集（由 `sync_standards.*` 同步；适用于 `.tsl`/`.tsf`）
+- `.agents/cpp/`、`.agents/python/` 等：其他语言的规则集（按需增加）
+
+规则发生冲突时，建议以“更靠近代码的目录规则更具体”为准。
+
+入口建议从：
+
+- `.agents/tsl/index.md`（TSL 规则集入口）
+- `docs/standards/tsl/docs/tsl/`（TSL 人类开发规范快照，推荐 subtree/vendoring 到该路径）
+EOF
+  echo "Created .agents/index.md"
+fi
+
+echo "Synced agents ruleset to $AGENTS_DST."
+
+GITATTR_DST="$ROOT/.gitattributes"
+if [ -f "$GITATTR_SRC" ]; then
+  : "${SYNC_GITATTR_MODE:=block}"
+  case "$SYNC_GITATTR_MODE" in
+    skip)
+      echo "Skip: .gitattributes sync (SYNC_GITATTR_MODE=skip)."
+      ;;
+    overwrite)
+      if [ "$(CDPATH= cd -- "$(dirname -- "$GITATTR_SRC")" && pwd -P)/$(basename -- "$GITATTR_SRC")" = "$GITATTR_DST" ]; then
+        echo "Skip: .gitattributes source equals destination."
+      else
+        if [ -e "$GITATTR_DST" ]; then
+          mv "$GITATTR_DST" "$ROOT/.gitattributes.bak.$timestamp"
+          echo "Backed up existing .gitattributes -> .gitattributes.bak.$timestamp"
+        fi
+        cp "$GITATTR_SRC" "$GITATTR_DST"
+        echo "Synced .gitattributes from standards (overwrite)."
+      fi
+      ;;
+    block)
+      begin="# BEGIN tsl-playbook .gitattributes"
+      end="# END tsl-playbook .gitattributes"
+
+      if [ -e "$GITATTR_DST" ]; then
+        mv "$GITATTR_DST" "$ROOT/.gitattributes.bak.$timestamp"
+        echo "Backed up existing .gitattributes -> .gitattributes.bak.$timestamp"
+      fi
+
+      tmp="${GITATTR_DST}.tmp.${timestamp}"
+      if [ -f "$ROOT/.gitattributes.bak.$timestamp" ]; then
+        src_dst="$ROOT/.gitattributes.bak.$timestamp"
+      else
+        src_dst=""
+      fi
+
+      if [ -n "$src_dst" ]; then
+        awk -v begin="$begin" -v end="$end" -v src="$GITATTR_SRC" '
+          function emit_src() {
+            print begin
+            while ((getline line < src) > 0) print line
+            close(src)
+            print end
+          }
+          BEGIN { in_block=0; done=0 }
+          $0 == begin { in_block=1; if (!done) { emit_src(); done=1 } ; next }
+          $0 == end   { in_block=0; next }
+          !in_block   { print }
+          END {
+            if (!done) {
+              if (NR > 0) print ""
+              emit_src()
+            }
+          }
+        ' "$src_dst" >"$tmp"
+      else
+        {
+          printf "%s\n" "$begin"
+          cat "$GITATTR_SRC"
+          printf "\n%s\n" "$end"
+        } >"$tmp"
+      fi
+
+      mv "$tmp" "$GITATTR_DST"
+      echo "Updated .gitattributes from standards (managed block)."
+      ;;
+    *)
+      echo "ERROR: invalid SYNC_GITATTR_MODE=$SYNC_GITATTR_MODE (use block|overwrite|skip)" >&2
+      exit 1
+      ;;
+  esac
+fi
+
+echo "Done."