✨ feat(markdown): add ruleset and sync support

2026-01-10 17:25:33 +08:00 · 2026-01-10 17:25:33 +08:00 · 11b2bed878
parent 5b895807b5
commit 11b2bed878
12 changed files with 163 additions and 87 deletions
--- a/.agents/index.md
+++ b/.agents/index.md
@ -7,6 +7,7 @@
 - `.agents/tsl/`：TSL 相关规则集（适用于 `.tsl`/`.tsf`）
 - `.agents/cpp/`：C++ 相关规则集（C++23，含 Modules）
 - `.agents/python/`：Python 相关规则集
+- `.agents/markdown/`：Markdown 相关规则集（仅代码格式化）

 目标项目落地时，通常通过 `scripts/sync_standards.*`
 将某个规则集同步到目标项目根目录的 `.agents/<lang>/`。
--- a/.agents/markdown/index.md
+++ b/.agents/markdown/index.md
@ -0,0 +1,27 @@
+# Markdown 代理规则集
+
+本规则集定义 AI/自动化代理在处理 Markdown（`.md`）文件时必须遵守的核心约束。
+
+## 代理工作原则（铁律）
+
+1. 只调整代码块与行内代码；不改写正文内容
+2. 不改变标题层级、列表结构、段落顺序
+3. 不引入新工具/格式化链路，除非明确要求
+
+## Markdown 代码格式约定（不可违反）
+
+### 代码块
+- 统一使用围栏代码块（```lang）
+- 语言标识尽量准确：`tsl`/`cpp`/`python`/`bash`/`json` 等
+- 仅做必要的排版修复；不改变代码语义
+
+### 工具
+- 优先使用仓库既有的格式化工具（如 Prettier）
+- 不引入新的 Markdown 格式化依赖
+
+### 行内代码
+- 用反引号包裹命令、路径、关键字或短代码
+
+## 适用范围
+- 仅适用于 `.md` 文件
+- 涉及代码内容时，遵循对应语言的 `.agents` 规则
--- a/AGENTS.md
+++ b/AGENTS.md
@ -3,7 +3,7 @@
 请以 `.agents/` 下的规则为准：

 - 入口：`.agents/index.md`
- 语言规则：`.agents/tsl/index.md`、`.agents/cpp/index.md`、`.agents/python/index.md`
+- 语言规则：`.agents/tsl/index.md`、`.agents/cpp/index.md`、`.agents/python/index.md`、`.agents/markdown/index.md`

 ---

@ -16,7 +16,7 @@
 - **加载方式**：自动，持续在上下文
 - **内容**：硬性约束与安全红线
 - **职责**：快速判断"能做什么/不能做什么"
- **规模控制**：TSL 47 行 | Python 48 行 | C++ 50 行
+- **规模控制**：TSL 47 行 | Python 48 行 | C++ 50 行 | Markdown 23 行

 ### Layer 2: `codex/skills/`（按需加载，100-1000 行/skill）

@ -81,8 +81,8 @@ Token 消耗：~8,000 tokens

 | 指标 | 之前 | 当前 | 改善 |
 |------|--------|--------|------|
-| .agents/ 规模 | ~500 行 | 145 行 | **↓ 71%** |
-| 持续占用 tokens | ~12,500 | ~3,625 | **↓ 71%** |
+| .agents/ 规模 | ~500 行 | 168 行 | **↓ 66%** |
+| 持续占用 tokens | ~12,500 | ~4,200 | **↓ 66%** |
 | 平均场景 tokens | ~12,500 | ~10,500 | **↓ 16%** |

 ---
--- a/README.md
+++ b/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 形式提交
- 📋 新规则需包含动机、示例、迁移建议（如有）
--- a/docs/index.md
+++ b/docs/index.md
@ -32,3 +32,7 @@
 - 代码风格：`python/style_guide.md`
 - 工具链：`python/tooling.md`
 - 配置清单：`python/configuration.md`
+
+## Markdown（markdown）
+
+- 代码块与行内代码格式：`markdown/index.md`
--- a/docs/markdown/index.md
+++ b/docs/markdown/index.md
@ -0,0 +1,27 @@
+# Markdown 规范（仅代码格式化）
+
+本目录只规范 Markdown 中**代码块**与**行内代码**的格式化规则；正文、标题、列表与段落结构保持原样，除非明确要求调整。
+
+## 适用范围
+
+- `.md` 文件
+
+## 代码块
+
+- 统一使用围栏代码块（```lang）
+- 语言标识尽量准确（`tsl`/`cpp`/`python`/`bash`/`json` 等）
+- 仅做必要的排版修复；不改变代码语义
+
+## 行内代码
+
+- 用反引号包裹命令、路径、关键字或短代码
+
+## 格式化工具
+
+- 优先使用仓库已固定的工具配置
+- 若存在 Prettier 配置，使用项目脚本或 `npx prettier -w <files...>`
+- 不引入新的 Markdown 格式化工具
+
+## 关联规则
+
+- 代码内容遵循对应语言的 `.agents/<lang>/index.md`
--- a/scripts/sync_standards.bat
+++ b/scripts/sync_standards.bat
@ -123,7 +123,8 @@ if not exist "%AGENTS_ROOT%\index.md" (
  >> "%AGENTS_ROOT%\index.md" echo.
  >> "%AGENTS_ROOT%\index.md" echo - `.agents/tsl/`：TSL 相关规则集（由 `sync_standards.*` 同步；适用于 `.tsl`/`.tsf`）
  >> "%AGENTS_ROOT%\index.md" echo - `.agents/cpp/`：C++ 相关规则集（由 `sync_standards.*` 同步；适用于 C++23/Modules）
-  >> "%AGENTS_ROOT%\index.md" echo - `.agents/python/` 等：其他语言的规则集（按需增加）
+  >> "%AGENTS_ROOT%\index.md" echo - `.agents/python/`：Python 相关规则集（由 `sync_standards.*` 同步）
+  >> "%AGENTS_ROOT%\index.md" echo - `.agents/markdown/`：Markdown 相关规则集（仅代码格式化）
  >> "%AGENTS_ROOT%\index.md" echo.
  >> "%AGENTS_ROOT%\index.md" echo 规则发生冲突时，建议以“更靠近代码的目录规则更具体”为准。
  >> "%AGENTS_ROOT%\index.md" echo.
@ -131,6 +132,7 @@ if not exist "%AGENTS_ROOT%\index.md" (
  >> "%AGENTS_ROOT%\index.md" echo.
  >> "%AGENTS_ROOT%\index.md" echo - `.agents/tsl/index.md`（TSL 规则集入口）
  >> "%AGENTS_ROOT%\index.md" echo - `.agents/cpp/index.md`（C++ 规则集入口）
+  >> "%AGENTS_ROOT%\index.md" echo - `.agents/markdown/index.md`（Markdown 规则集入口）
  >> "%AGENTS_ROOT%\index.md" echo - `docs/standards/playbook/docs/`（人类开发规范快照：`tsl/`、`cpp/`、`python/`、`common/`）
  echo Created .agents\index.md
 )
--- a/scripts/sync_standards.ps1
+++ b/scripts/sync_standards.ps1
@ -119,7 +119,8 @@ if (-not (Test-Path $AgentsIndex)) {

 - `.agents/tsl/`：TSL 相关规则集（由 `sync_standards.*` 同步；适用于 `.tsl`/`.tsf`）
 - `.agents/cpp/`：C++ 相关规则集（由 `sync_standards.*` 同步；适用于 C++23/Modules）
- `.agents/python/` 等：其他语言的规则集（按需增加）
+- `.agents/python/`：Python 相关规则集（由 `sync_standards.*` 同步）
+- `.agents/markdown/`：Markdown 相关规则集（仅代码格式化）

 规则发生冲突时，建议以“更靠近代码的目录规则更具体”为准。

@ -127,6 +128,7 @@ if (-not (Test-Path $AgentsIndex)) {

 - `.agents/tsl/index.md`（TSL 规则集入口）
 - `.agents/cpp/index.md`（C++ 规则集入口）
+- `.agents/markdown/index.md`（Markdown 规则集入口）
 - `docs/standards/playbook/docs/`（人类开发规范快照：`tsl/`、`cpp/`、`python/`、`common/`）
 '@ | Set-Content -Path $AgentsIndex -Encoding UTF8
  Write-Host "Created .agents/index.md"
--- a/scripts/sync_standards.sh
+++ b/scripts/sync_standards.sh
@ -127,7 +127,8 @@ if [ ! -f "$AGENTS_INDEX" ]; then

 - `.agents/tsl/`：TSL 相关规则集（由 `sync_standards.*` 同步；适用于 `.tsl`/`.tsf`）
 - `.agents/cpp/`：C++ 相关规则集（由 `sync_standards.*` 同步；适用于 C++23/Modules）
- `.agents/python/` 等：其他语言的规则集（按需增加）
+- `.agents/python/`：Python 相关规则集（由 `sync_standards.*` 同步）
+- `.agents/markdown/`：Markdown 相关规则集（仅代码格式化）

 规则发生冲突时，建议以“更靠近代码的目录规则更具体”为准。

@ -135,6 +136,7 @@ if [ ! -f "$AGENTS_INDEX" ]; then

 - `.agents/tsl/index.md`（TSL 规则集入口）
 - `.agents/cpp/index.md`（C++ 规则集入口）
+- `.agents/markdown/index.md`（Markdown 规则集入口）
 - `docs/standards/playbook/docs/`（人类开发规范快照：`tsl/`、`cpp/`、`python/`、`common/`）
 EOF
  echo "Created .agents/index.md"
--- a/scripts/vendor_playbook.bat
+++ b/scripts/vendor_playbook.bat
@ -204,6 +204,7 @@ if not exist "%PROJECT_AGENTS_INDEX%" (
    if /I "%%~L"=="tsl" >> "%PROJECT_AGENTS_INDEX%" echo - .agents/tsl/：TSL 相关规则集（适用于 .tsl/.tsf）
    if /I "%%~L"=="cpp" >> "%PROJECT_AGENTS_INDEX%" echo - .agents/cpp/：C++ 相关规则集（C++23，含 Modules）
    if /I "%%~L"=="python" >> "%PROJECT_AGENTS_INDEX%" echo - .agents/python/：Python 相关规则集
+    if /I "%%~L"=="markdown" >> "%PROJECT_AGENTS_INDEX%" echo - .agents/markdown/：Markdown 相关规则集（仅代码格式化）
  )
  >> "%PROJECT_AGENTS_INDEX%" echo.
  >> "%PROJECT_AGENTS_INDEX%" echo 入口建议从：
@ -254,6 +255,12 @@ if /I "%LANG%"=="python" (
  >> "%DOC_INDEX%" echo - 工具链：`python/tooling.md`
  >> "%DOC_INDEX%" echo - 配置清单：`python/configuration.md`
 )
+if /I "%LANG%"=="markdown" (
+  >> "%DOC_INDEX%" echo.
+  >> "%DOC_INDEX%" echo ## Markdown（markdown）
+  >> "%DOC_INDEX%" echo.
+  >> "%DOC_INDEX%" echo - 代码块与行内代码格式：`markdown/index.md`
+)
 exit /b 0

 :Usage
--- a/scripts/vendor_playbook.ps1
+++ b/scripts/vendor_playbook.ps1
@ -144,6 +144,13 @@ function Append-DocsSection([string]$Lang) {
      $docLines.Add('- 配置清单：`python/configuration.md`')
      break
    }
+    "markdown" {
+      $docLines.Add("")
+      $docLines.Add("## Markdown（markdown）")
+      $docLines.Add("")
+      $docLines.Add('- 代码块与行内代码格式：`markdown/index.md`')
+      break
+    }
  }
 }

@ -219,6 +226,7 @@ if (-not (Test-Path $ProjectAgentsIndex)) {
      "tsl" { $agentLines.Add("- .agents/tsl/：TSL 相关规则集（适用于 .tsl/.tsf）"); break }
      "cpp" { $agentLines.Add("- .agents/cpp/：C++ 相关规则集（C++23，含 Modules）"); break }
      "python" { $agentLines.Add("- .agents/python/：Python 相关规则集"); break }
+      "markdown" { $agentLines.Add("- .agents/markdown/：Markdown 相关规则集（仅代码格式化）"); break }
    }
  }
  $agentLines.Add("")
--- a/scripts/vendor_playbook.sh
+++ b/scripts/vendor_playbook.sh
@ -170,6 +170,14 @@ EOF
 - 代码风格：`python/style_guide.md`
 - 工具链：`python/tooling.md`
 - 配置清单：`python/configuration.md`
+EOF
+      ;;
+    markdown)
+      cat >>"$DEST_PREFIX/docs/index.md" <<'EOF'
+
+## Markdown（markdown）
+
+- 代码块与行内代码格式：`markdown/index.md`
 EOF
      ;;
  esac
@ -245,6 +253,7 @@ EOF
      tsl) printf '%s\n' "- .agents/tsl/：TSL 相关规则集（适用于 .tsl/.tsf）" >>"$PROJECT_AGENTS_INDEX" ;;
      cpp) printf '%s\n' "- .agents/cpp/：C++ 相关规则集（C++23，含 Modules）" >>"$PROJECT_AGENTS_INDEX" ;;
      python) printf '%s\n' "- .agents/python/：Python 相关规则集" >>"$PROJECT_AGENTS_INDEX" ;;
+      markdown) printf '%s\n' "- .agents/markdown/：Markdown 相关规则集（仅代码格式化）" >>"$PROJECT_AGENTS_INDEX" ;;
    esac
  done