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