🎨 style(docs): format markdown

This commit is contained in:
csh 2026-01-23 15:07:41 +08:00
parent b4f712acb4
commit d959f80de7
5 changed files with 33 additions and 17 deletions

1
.prettierignore Normal file
View File

@ -0,0 +1 @@
codex/skills/**

View File

@ -90,7 +90,7 @@ Token 消耗:~8,000 tokens
## 性能指标 ## 性能指标
| 指标 | 之前 | 现在 | 改善 | | 指标 | 之前 | 现在 | 改善 |
| --------------- | -------- | -------- | ---- | | --------------- | ------- | ------- | ---- |
| .agents 规模 | ~500 行 | 168 行 | -66% | | .agents 规模 | ~500 行 | 168 行 | -66% |
| 持久化 tokens | ~12,500 | ~4,200 | -66% | | 持久化 tokens | ~12,500 | ~4,200 | -66% |
| 场景平均 tokens | ~12,500 | ~10,500 | -16% | | 场景平均 tokens | ~12,500 | ~10,500 | -16% |

View File

@ -1,20 +1,24 @@
# Unified Playbook CLI Design # Unified Playbook CLI Design
## 目标 ## 目标
- 提供单一入口 `scripts/playbook.py`,以 TOML 配置驱动所有动作。 - 提供单一入口 `scripts/playbook.py`,以 TOML 配置驱动所有动作。
- 取消旧的 sh/ps1/bat 脚本与参数兼容,减少心智负担。 - 取消旧的 sh/ps1/bat 脚本与参数兼容,减少心智负担。
- 保持功能覆盖vendoring、同步模板、同步标准、安装 skills、格式化 Markdown。 - 保持功能覆盖vendoring、同步模板、同步标准、安装 skills、格式化 Markdown。
## 非目标 ## 非目标
- 不保留旧脚本的参数兼容层。 - 不保留旧脚本的参数兼容层。
- 不引入新的依赖Markdown 格式化仅使用已有 Prettier - 不引入新的依赖Markdown 格式化仅使用已有 Prettier
## CLI 设计 ## CLI 设计
- 入口:`python scripts/playbook.py -config <path>`。 - 入口:`python scripts/playbook.py -config <path>`。
- 仅支持两个参数:`-config`(必填)与 `-h/-help` - 仅支持两个参数:`-config`(必填)与 `-h/-help`
- `project_root` 默认取配置文件所在目录。 - `project_root` 默认取配置文件所在目录。
## TOML 结构 ## TOML 结构
- 通过 section 是否存在决定是否执行: - 通过 section 是否存在决定是否执行:
- `[vendor]` - `[vendor]`
- `[sync_templates]` - `[sync_templates]`
@ -25,6 +29,7 @@
`vendor → sync_templates → sync_standards → install_skills → format_md` `vendor → sync_templates → sync_standards → install_skills → format_md`
## 行为要点 ## 行为要点
- `vendor` 仅生成快照,不再隐式触发 `sync_standards` - `vendor` 仅生成快照,不再隐式触发 `sync_standards`
- `sync_standards` 负责 `.agents/`、`AGENTS.md` 区块与 `.gitattributes` - `sync_standards` 负责 `.agents/`、`AGENTS.md` 区块与 `.gitattributes`
- `sync_templates` 负责 memory-bank、docs/prompts、AGENTS/AGENT_RULES 模板。 - `sync_templates` 负责 memory-bank、docs/prompts、AGENTS/AGENT_RULES 模板。
@ -32,16 +37,19 @@
- `format_md` 仅调用已有 Prettier可通过 globs 指定范围)。 - `format_md` 仅调用已有 Prettier可通过 globs 指定范围)。
## 预期输出 ## 预期输出
- 新增:`scripts/playbook.py`、`playbook.toml.example`。 - 新增:`scripts/playbook.py`、`playbook.toml.example`。
- 删除:旧的 sh/ps1/bat 脚本与对应测试。 - 删除:旧的 sh/ps1/bat 脚本与对应测试。
- 更新README/模板说明/CI/test.yml。 - 更新README/模板说明/CI/test.yml。
## 测试策略 ## 测试策略
- 用 Python `unittest` 覆盖核心路径: - 用 Python `unittest` 覆盖核心路径:
- TOML 解析与动作触发顺序。 - TOML 解析与动作触发顺序。
- vendor/sync 模拟执行与关键输出文件检查。 - vendor/sync 模拟执行与关键输出文件检查。
- 保留现有模板验证与文档链接检查。 - 保留现有模板验证与文档链接检查。
## 风险 ## 风险
- 旧脚本移除会影响现有用户;通过 README 与示例配置降低迁移成本。 - 旧脚本移除会影响现有用户;通过 README 与示例配置降低迁移成本。
- Windows 环境权限可能影响 `npm install` 与符号链接;测试不依赖 npm。 - Windows 环境权限可能影响 `npm install` 与符号链接;测试不依赖 npm。

View File

@ -13,6 +13,7 @@
### Task 1: Create CLI test harness and basic argument handling ### Task 1: Create CLI test harness and basic argument handling
**Files:** **Files:**
- Create: `tests/cli/test_playbook_cli.py` - Create: `tests/cli/test_playbook_cli.py`
- Modify: `tests/README.md` - Modify: `tests/README.md`
@ -88,6 +89,7 @@ git commit -m ":white_check_mark: test(cli): add basic playbook cli tests"
### Task 2: Parse TOML config and enforce dispatch order ### Task 2: Parse TOML config and enforce dispatch order
**Files:** **Files:**
- Modify: `scripts/playbook.py` - Modify: `scripts/playbook.py`
- Create: `playbook.toml.example` - Create: `playbook.toml.example`
- Modify: `README.md` - Modify: `README.md`
@ -156,6 +158,7 @@ git commit -m ":sparkles: feat(cli): add toml config and dispatch order"
### Task 3: Implement `vendor` action (snapshot only) ### Task 3: Implement `vendor` action (snapshot only)
**Files:** **Files:**
- Modify: `scripts/playbook.py` - Modify: `scripts/playbook.py`
- Modify: `playbook.toml.example` - Modify: `playbook.toml.example`
- Modify: `README.md` - Modify: `README.md`
@ -209,6 +212,7 @@ git commit -m ":sparkles: feat(vendor): add playbook snapshot generation"
### Task 4: Implement `sync_templates` and `sync_standards` ### Task 4: Implement `sync_templates` and `sync_standards`
**Files:** **Files:**
- Modify: `scripts/playbook.py` - Modify: `scripts/playbook.py`
- Modify: `playbook.toml.example` - Modify: `playbook.toml.example`
- Modify: `templates/README.md` - Modify: `templates/README.md`
@ -283,6 +287,7 @@ git commit -m ":sparkles: feat(sync): add templates and standards actions"
### Task 5: Implement `install_skills` and `format_md` ### Task 5: Implement `install_skills` and `format_md`
**Files:** **Files:**
- Modify: `scripts/playbook.py` - Modify: `scripts/playbook.py`
- Modify: `playbook.toml.example` - Modify: `playbook.toml.example`
- Modify: `README.md` - Modify: `README.md`
@ -336,6 +341,7 @@ git commit -m ":sparkles: feat(actions): add install_skills and format_md"
### Task 6: Remove legacy scripts and update CI/test docs ### Task 6: Remove legacy scripts and update CI/test docs
**Files:** **Files:**
- Delete: `scripts/*.sh`, `scripts/*.ps1`, `scripts/*.bat` - Delete: `scripts/*.sh`, `scripts/*.ps1`, `scripts/*.bat`
- Delete: `tests/scripts/*.bats` - Delete: `tests/scripts/*.bats`
- Modify: `.gitea/workflows/test.yml` - Modify: `.gitea/workflows/test.yml`
@ -386,6 +392,7 @@ git commit -m ":wastebasket: remove(legacy): drop old scripts and tests"
### Task 7: Final cleanup and formatting ### Task 7: Final cleanup and formatting
**Files:** **Files:**
- Modify: `README.md`, `templates/README.md`, `tests/README.md` - Modify: `README.md`, `templates/README.md`, `tests/README.md`
**Step 1: Run Markdown format (exclude third-party skills)** **Step 1: Run Markdown format (exclude third-party skills)**

View File

@ -105,7 +105,7 @@ project/
项目上下文文档,用于让 AI 快速理解项目: 项目上下文文档,用于让 AI 快速理解项目:
| 文件 | 用途 | | 文件 | 用途 |
| --------------------------------- | -------------------- | | --------------------------- | -------------------- |
| `project-brief.template.md` | 项目定位、边界、约束 | | `project-brief.template.md` | 项目定位、边界、约束 |
| `tech-stack.template.md` | 技术栈、工具链、环境 | | `tech-stack.template.md` | 技术栈、工具链、环境 |
| `architecture.template.md` | 架构设计、模块职责 | | `architecture.template.md` | 架构设计、模块职责 |
@ -163,7 +163,7 @@ project/
**playbook 标记**(用于自动更新): **playbook 标记**(用于自动更新):
| 标记 | 用途 | 管理入口 | | 标记 | 用途 | 管理入口 |
| --------------------------------------- | ---------------------- | -------------------------------- | | --------------------------------------- | --------------------- | ------------------------------ |
| `<!-- playbook:agents:start/end -->` | 语言规则链接 | playbook.py `[sync_standards]` | | `<!-- playbook:agents:start/end -->` | 语言规则链接 | playbook.py `[sync_standards]` |
| `<!-- playbook:templates:start/end -->` | 路由链接(默认追加) | playbook.py `[sync_templates]` | | `<!-- playbook:templates:start/end -->` | 路由链接(默认追加) | playbook.py `[sync_templates]` |
| `<!-- playbook:framework:start/end -->` | 完整框架full 追加) | playbook.py `[sync_templates]` | | `<!-- playbook:framework:start/end -->` | 完整框架full 追加) | playbook.py `[sync_templates]` |