✨ feat(markdown): add ruleset and sync support

README.md

@@ -1,29 +1,23 @@
-# 📚 playbook
+# playbook
 
-Playbook：TSL（`.tsl`/`.tsf`）+ C++ + Python 工程规范与代理规则合集。
+Playbook：TSL（`.tsl`/`.tsf`）+ C++ + Python + Markdown（代码格式化）工程规范与代理规则合集。
 
-## 🎯 目标
-
-- 让代码**易读、易维护、易演进**
-- 风格保持一致，减少无意义的差异
-- 在不影响清晰度的前提下，尽量简洁
-
-## 📏 原则
+## 原则
 
 1. **可读性优先**：读代码的时间远大于写代码
 2. **一致性优先**：同一仓库内保持一致比追求"最优风格"更重要
 3. **遵从既有代码**：修改/扩展现有代码时优先沿用其局部风格
 
-## 🌐 适用范围
+## 适用范围
 
-- 本指南适用于所有 TSL/C++/Python 相关仓库与脚本
+- 本指南适用于所有 TSL/C++/Python/Markdown 相关仓库与脚本
 - 当现有代码与本指南冲突时，**以保持局部一致性为优先**，逐步迁移
 
-## 📖 docs/（开发规范）
+## docs/（开发规范）
 
 `docs/` 目录是给开发者阅读的工程规范，约束代码写法、命名与提交信息。
 
-- `docs/index.md`：文档导航（跨语言 common / TSL / C++ / Python）。
+- `docs/index.md`：文档导航（跨语言 common / TSL / C++ / Python / Markdown）。
 - `docs/common/commit_message.md`：提交信息与版本号规范（type/scope/subject/body/footer、可选 Emoji 图例、SemVer）。
 - `docs/tsl/code_style.md`：TSL 代码结构、格式、`begin/end`
   代码块、注释与通用最佳实践。
@@ -40,17 +34,18 @@ Playbook：TSL（`.tsl`/`.tsf`）+ C++ + Python 工程规范与代理规则合
 - `docs/python/tooling.md`：Python 工具链（black/isort/flake8/pylint/mypy/pytest/pre-commit）。
 - `docs/python/configuration.md`：Python 配置清单（落地时从 `templates/python/`
   复制到项目根目录）。
+- `docs/markdown/index.md`：Markdown 代码块与行内代码格式（仅代码格式化）。
 - `templates/cpp/`：C++ 落地模板（`.clang-format`、`conanfile.txt`、`CMakeUserPresets.json`、`CMakeLists.txt`）。
 - `templates/python/`：Python 落地模板（`pyproject.toml`
   工具配置、`.flake8`、`.pylintrc`、`.pre-commit-config.yaml`、`.editorconfig`、`.vscode/settings.json`）。
 - `templates/ci/`：目标项目 CI 示例模板（如 Gitea
   Actions），用于自动化校验部分规范。
 
-## 🤖 .agents/（代理规则 - 三层架构）
+## .agents/（代理规则 - 三层架构）
 
 `.agents/` 是 AI 代理的极简铁律（三层架构设计）：
 
-### 📦 三层架构设计
+### 三层架构设计
 
 ```
 Layer 1: .agents/          (≤50 行/语言，自动加载)
@@ -66,41 +61,37 @@ Layer 3: docs/             (权威静态文档)
   └─ 完整语法手册/代码风格/工具链配置
 ```
 
-**📂 目录结构**：
+**目录结构**：
 - `.agents/index.md`：规则集索引（跨语言）
 - `.agents/tsl/index.md`：TSL 核心约定（47 行）
 - `.agents/cpp/index.md`：C++ 核心约定（50 行）
 - `.agents/python/index.md`：Python 核心约定（48 行）
+- `.agents/markdown/index.md`：Markdown 核心约定（23 行，仅代码格式化）
 
-**✨ 设计收益**：
-- 持续上下文占用从 ~500 行降至 145 行（↓ 71%）
-- 平均场景 token 消耗降低 16%
-- TSL 未训练语言获得渐进式教学支持
+详见：`AGENTS.md`
 
-📄 详见：`AGENTS.md`
-
-## ⚡ SKILLS（Codex CLI）
+## SKILLS（Codex CLI）
 
 本仓库内置一组 Codex CLI skills（见 `codex/skills/`），用于按需加载的工作流与知识库。
 
-**⭐ 核心 Skills**：
+**核心 Skills**：
 - **`$tsl-guide`**：TSL/TSF 语法完整指南（基础/高级/函数库/最佳实践）
 - **`$performance-optimization`**：跨语言性能优化工作流
 - **`$testing-workflow`**：跨语言测试策略
 
-**🔨 通用 Skills**：
+**通用 Skills**：
 - `$code-review-workflow`：代码审查流程
 - `$commit-message`：提交信息规范
 - `$systematic-debugging`：系统化调试
 - 更多见 `SKILLS.md`
 
-**📥 安装与使用**：详见 `SKILLS.md`
+**安装与使用**：详见 `SKILLS.md`
 
-## 🔧 在其他项目中使用本 Playbook
+## 在其他项目中使用本 Playbook
 
 由于本仓库需要内部权限访问，其他项目**不能仅用外链引用**；推荐把 Playbook 规范 vendoring 到项目内。
 
-### 🚀 快速决策：我应该用哪种方式？
+### 快速决策：我应该用哪种方式？
 
 | 你的情况                         | 推荐方式                        | 优势                            |
 | -------------------------------- | ------------------------------- | ------------------------------- |
@@ -113,7 +104,7 @@ Layer 3: docs/             (权威静态文档)
 
 ---
 
-### ⚡ TL;DR - 30 秒快速开始
+### TL;DR - 30 秒快速开始
 
 大部分项目只需运行以下命令即可完成落地（以 TSL 为例）：
 
@@ -136,7 +127,7 @@ git commit -m ":package: deps(playbook): add tsl standards"
 
 ---
 
-### 🌲 方式一：git subtree 同步（推荐）
+### 方式一：git subtree 同步（推荐）
 
 1. 在目标项目中首次引入：
 
@@ -156,13 +147,13 @@ git commit -m ":package: deps(playbook): add tsl standards"
    main --squash
    ```
 
-#### ⚙️ 快速落地（最小 4 步）
+#### 快速落地（最小 4 步）
 
 在目标项目中按以下顺序执行即可完成落地（推荐固定使用
 `--prefix docs/standards/playbook`）：
 
-1. **📥 引入标准快照**（见上文 `git subtree add`）
-2. **🔄 同步到项目根目录**（生成/更新 `.agents/<lang>/`、更新 `.gitattributes`）：
+1. **引入标准快照**（见上文 `git subtree add`）
+2. **同步到项目根目录**（生成/更新 `.agents/<lang>/`、更新 `.gitattributes`）：
 
    ```bash
    sh docs/standards/playbook/scripts/sync_standards.sh
@@ -180,41 +171,41 @@ git commit -m ":package: deps(playbook): add tsl standards"
    sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp
    ```
 
-   > 💡 说明：若项目根目录没有 `AGENTS.md`，`sync_standards.*`
+   >  说明：若项目根目录没有 `AGENTS.md`，`sync_standards.*`
    > 会自动生成最小版；已存在则不会覆盖。
 
-3. **✅ 验收**（任意满足其一即可）：
+3. **验收**（任意满足其一即可）：
    - 目录存在：`.agents/tsl/`
    - 规则入口可读：`.agents/tsl/index.md`
    - （可选）C++ 规则入口可读：`.agents/cpp/index.md`
    - 标准文档可读：`docs/standards/playbook/docs/index.md`
    - `.gitattributes` 包含追加块头：`# Added from playbook .gitattributes`
 
-4. **📝 将同步产物纳入版本控制**（目标项目建议提交）：
+4. **将同步产物纳入版本控制**（目标项目建议提交）：
    - `docs/standards/playbook/`（标准快照）
    - `.agents/tsl/`（落地规则集）
    - `.gitattributes`（追加缺失规则）
    - `AGENTS.md`（若本次自动生成）
 
-#### 💼 新项目 / 旧项目（命令示例）
+#### 新项目 / 旧项目（命令示例）
 
-**🆕 新项目**（无 `.agents/` 与 `AGENTS.md`）：
+**新项目**（无 `.agents/` 与 `AGENTS.md`）：
 
 ```bash
 git subtree add --prefix docs/standards/playbook https://git.mytsl.cn/csh/playbook.git main --squash
 sh docs/standards/playbook/scripts/sync_standards.sh tsl
 ```
 
-**🔄 旧项目**（已有 `AGENTS.md`）：
+**旧项目**（已有 `AGENTS.md`）：
 
 ```bash
 git subtree pull --prefix docs/standards/playbook https://git.mytsl.cn/csh/playbook.git main --squash
 sh docs/standards/playbook/scripts/sync_standards.sh tsl
 ```
 
-⚠️ 旧项目的 `AGENTS.md` 不会被覆盖；如需指向 `.agents/`，请手动对齐内容。
+旧项目的 `AGENTS.md` 不会被覆盖；如需指向 `.agents/`，请手动对齐内容。
 
-#### 🔗 可选：项目包装脚本（多 playbook 串联）
+#### 可选：项目包装脚本（多 playbook 串联）
 
 多语言项目建议在目标项目创建一个包装脚本（便于一键同步多个规则集）：
 
@@ -232,7 +223,7 @@ sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp
 sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp
 ```
 
-#### 📁 目录约定（建议）
+#### 目录约定（建议）
 
 目标项目推荐采用以下结构（Playbook 快照与项目文档分离）：
 
@@ -256,23 +247,23 @@ sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp
 
 根目录的 `.agents/<lang>/` 与 `.gitattributes` 通过同步脚本获得：
 
-- 💡 **说明**：在 **本 playbook 仓库** 内脚本位于 `scripts/`；在 **目标项目** 里通过
+- **说明**：在 **本 playbook 仓库**内脚本位于 `scripts/`；在 **目标项目**里通过
   `git subtree` 引入到 `docs/standards/playbook/` 后，脚本路径变为
   `docs/standards/playbook/scripts/`。
-- 📜 **在目标项目里直接运行 Playbook 提供的脚本**（子树快照里自带）：
+- **在目标项目里直接运行 Playbook 提供的脚本**（子树快照里自带）：
   - `docs/standards/playbook/scripts/sync_standards.sh`（推荐，支持多语言参数）
   - `docs/standards/playbook/scripts/sync_standards.ps1`（推荐，支持多语言参数）
   - `docs/standards/playbook/scripts/sync_standards.bat`（推荐，支持多语言参数）
-- 💾 脚本会从快照目录同步到项目根目录，并先备份旧文件（`.bak.*`）
+- 脚本会从快照目录同步到项目根目录，并先备份旧文件（`.bak.*`）
 
-💡 建议固定使用 `--prefix docs/standards/playbook`，因为同步后的 `.agents/*/`
+建议固定使用 `--prefix docs/standards/playbook`，因为同步后的 `.agents/*/`
 会引用该路径下的标准快照文档（`docs/standards/playbook/docs/...`）。无参数时若已存在
 `.agents/<lang>/`，将按现有语言同步；否则默认 `.agents/tsl/`。如需同步 C++ 规则集，
 推荐直接运行：`sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp`。
 
-✅ 这样 clone 任意项目时都能直接读取规范文件，不依赖外部访问权限。
+这样 clone 任意项目时都能直接读取规范文件，不依赖外部访问权限。
 
-**🔄 同步脚本行为**（目标项目内的最终落地内容）：
+**同步脚本行为**（目标项目内的最终落地内容）：
 
 - 覆盖/更新：`.agents/<AGENTS_NS>/`（默认 `.agents/tsl/`）
 - 自动识别：未传语言参数且已存在 `.agents/<lang>/` 时，按现有语言同步
@@ -283,9 +274,9 @@ sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp
 - 不修改：`.gitignore`（项目自行维护）
 
 <details>
-<summary>🔧 高级选项：环境变量配置（点击展开）</summary>
+<summary> 高级选项：环境变量配置（点击展开）</summary>
 
-#### ⚙️ 环境变量（可选）
+#### 环境变量（可选）
 
 同步脚本支持以下可选环境变量（默认值可满足大多数项目）：
 
@@ -296,12 +287,12 @@ sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp
 
 </details>
 
-### 📋 方式二：手动复制快照
+### 方式二：手动复制快照
 
 如果不使用
 `git subtree`，也可以由有权限的人手动复制 Playbook 到目标项目中（适合规范不频繁更新或项目数量较少的情况）。
 
-**📝 步骤**：
+**步骤**：
 
 1. 在目标项目创建目录：`docs/standards/playbook/`。
 2. 从本仓库复制以下内容到目标项目：
@@ -315,9 +306,9 @@ sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp
 4. 在 `docs/standards/playbook/SOURCE.md`
    记录本次复制的来源版本/日期（建议写 Playbook 的 commit hash）。
 
-⚠️ 该方式没有自动同步能力，后续更新需重复上述复制流程。
+该方式没有自动同步能力，后续更新需重复上述复制流程。
 
-### ✂️ 方式三：脚本裁剪复制（按语言，离线）
+### 方式三：脚本裁剪复制（按语言，离线）
 
 当你希望“只 vendoring 需要的语言规范”（例如只需要 `tsl` +
 `cpp`）时，可直接运行本仓库提供的裁剪脚本：
@@ -340,16 +331,16 @@ sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp
   <PLAYBOOK_ROOT>\\scripts\\vendor_playbook.bat <target-project-root> --langs tsl,cpp
   ```
 
-**✨ 脚本会**：
+**脚本会**：
 
-- ✂️ 生成裁剪快照到 `docs/standards/playbook/`（包含
+- 生成裁剪快照到 `docs/standards/playbook/`（包含
   `docs/common/` + 选定语言目录 + 对应 `.agents/<lang>/` + `scripts/` +
   `.gitattributes` + 通用 `templates/ci/` + 相关 `templates/<lang>/`）
-- 🔄 自动执行 `docs/standards/playbook/scripts/sync_standards.*`，把
+- 自动执行 `docs/standards/playbook/scripts/sync_standards.*`，把
   `.agents/<lang>/` 与 `.gitattributes` 落地到目标项目根目录
-- 📝 生成 `docs/standards/playbook/SOURCE.md` 记录来源与版本信息
+- 生成 `docs/standards/playbook/SOURCE.md` 记录来源与版本信息
 
-### 🌍 多语言项目落地（TSL + C++/其他语言）
+### 多语言项目落地（TSL + C++/其他语言）
 
 多语言项目建议把规范拆成两类：
 
@@ -361,14 +352,14 @@ sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp
    - 例如 TSL 的命名/文件顶层声明限制、C++ 的
      `.clang-format/.clang-tidy`、Python 的 `ruff` 等。
 
-💡 **建议**：仓库级规则尽量少且稳定；语言级规则各自独立，避免互相"污染"。
+**建议**：仓库级规则尽量少且稳定；语言级规则各自独立，避免互相"污染"。
 
-本仓库提供多套代理规则集（同步后位于目标项目的 `.agents/tsl/` / `.agents/cpp/` / `.agents/python/`）：
+本仓库提供多套代理规则集（同步后位于目标项目的 `.agents/tsl/` / `.agents/cpp/` / `.agents/python/` / `.agents/markdown/`）：
 
-- ✅ 三者都包含核心约定与安全红线
-- 📝 并在 `index.md` 中叠加语言级"硬约束"（TSL/TSF 语法限制、C++23/Modules、Python 风格等）
+- 三者都包含核心约定与安全红线
+- 并在 `index.md` 中叠加语言级"硬约束"（TSL/TSF 语法限制、C++23/Modules、Python 风格、Markdown 代码格式化等）
 
-**📂 多语言项目推荐结构**（示例：TSL + C++ + Python）：
+**多语言项目推荐结构**（示例：TSL + C++ + Python + Markdown）：
 
 ```txt
 .
@@ -376,7 +367,8 @@ sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp
 │   ├── index.md                      # 多语言索引（缺省时由脚本创建）
 │   ├── tsl/                          # 由本 Playbook 同步（适用于 .tsl/.tsf）
 │   ├── cpp/                          # 由本 Playbook 同步（适用于 C++23/Modules）
-│   └── python/                       # Python 规则集（同上）
+│   ├── python/                       # Python 规则集（同上）
+│   └── markdown/                     # Markdown 规则集（仅代码格式化）
 ├── .gitattributes                    # 行尾/文本规范（可由某个 playbook 同步）
 ├── docs/
 │   ├── standards/
@@ -388,14 +380,14 @@ sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp
 └── src/                              # 源码目录（按项目实际情况）
 ```
 
-**⚖️ 规则优先级建议**：
+**规则优先级建议**：
 
-- ✅ 同一项目内多个规则集并行放在 `.agents/<lang>/`，不要互相覆盖
-- 📍 若某个子目录需要更具体规则（模块/子系统差异），在更靠近代码的目录放置更具体规则（例如
+- 同一项目内多个规则集并行放在 `.agents/<lang>/`，不要互相覆盖
+- 若某个子目录需要更具体规则（模块/子系统差异），在更靠近代码的目录放置更具体规则（例如
   `src/foo/.agents/`），并以"离代码更近者优先"为准
 
 <details>
-<summary>🔧 高级选项：`.agents` 覆盖/合并策略（点击展开）</summary>
+<summary> 高级选项：`.agents` 覆盖/合并策略（点击展开）</summary>
 
 #### `.agents` 的覆盖/合并策略（可执行流程）
 
@@ -441,29 +433,24 @@ if (Test-Path $overlay) {
 
 </details>
 
-#### 🔌 扩展新语言（模板）
+#### 扩展新语言（模板）
 
 当目标项目需要新增一门语言（例如 C++），建议按以下模板扩展：
 
-- 📖 **文档**：
+- **文档**：
   - 若使用本 Playbook 自带的 C++ 规范：无需额外 subtree，直接使用
     `docs/standards/playbook/docs/cpp/`，并在项目 `README.md`/`docs/index.md`
     链接入口。
   - 若新增"本 Playbook 未覆盖的语言"：再引入对应语言的标准仓库（subtree/vendoring 到
     `docs/standards/<lang>/`）
-- 🤖 **代理规则**：
+- **代理规则**：
   - C++：运行 `sh docs/standards/playbook/scripts/sync_standards.sh cpp`（或
     `& "docs/standards/playbook/scripts/sync_standards.ps1" -Langs cpp`），落地到
     `.agents/cpp/`（与 `.agents/tsl/` 并行）。
   - 其他语言：在目标项目增加 `.agents/<lang>/`（与 `.agents/tsl/`
     并行），只写该语言专属要求与工具链约束
-- 🔄 **同步策略**：每个规则集只同步到对应子目录（例如 `.agents/cpp/`），避免覆盖整个
+- **同步策略**：每个规则集只同步到对应子目录（例如 `.agents/cpp/`），避免覆盖整个
   `.agents/`
-- 🛠️ **CI/工具**：按文件类型分别执行格式化、lint、测试（不要让 TSL 规则去约束 C++ 代码，反之亦然）
-  - 💡 C++ 补全：建议在项目根目录提供 `.clangd` 并指向正确的
+- **CI/工具**：按文件类型分别执行格式化、lint、测试（不要让 TSL 规则去约束 C++ 代码，反之亦然）
+  -  C++ 补全：建议在项目根目录提供 `.clangd` 并指向正确的
     `CompilationDatabase`（模板见 `templates/cpp/.clangd`）
-
-## 🤝 版本与贡献
-
-- 🔄 本项目会持续迭代；变更以 PR 形式提交
-- 📋 新规则需包含动机、示例、迁移建议（如有）