327 lines
11 KiB
Markdown
327 lines
11 KiB
Markdown
# 仓库问题清单
|
||
|
||
本文档整理当前仓库中已经确认的问题，重点覆盖可复现现象、根因、影响范围和建议修复方向。
|
||
|
||
## 适用范围
|
||
|
||
- 仓库：`playbook`
|
||
- 分析时间：2026-03-09
|
||
- 当前分析环境：Windows + PowerShell + Python 3.12
|
||
|
||
## 问题总览
|
||
|
||
| ID | 严重级别 | 主题 | 主要影响 |
|
||
| --- | -------- | ---------------------------------------------- | --------------------------------------- |
|
||
| 1 | 高 | Windows 下 TOML 配置解析失效 | 大量 CLI 功能无法执行 |
|
||
| 2 | 中 | `SKILLS.md` 中 Third-party 内容重复维护 | 文档容易漂移，测试契约错误 |
|
||
| 3 | 中 | `.agents/index.md` 不会随语言集合更新 | 生成产物前后不一致 |
|
||
| 4 | 低 | 本地验证文档默认依赖 POSIX shell | 平台前提不清晰，易误导新环境用户 |
|
||
| 5 | 低 | `load_config()` 真实入口测试曾缺失（现已补齐） | 当前无需增加 Windows runner |
|
||
| 6 | 低 | Python 缓存忽略已补上（现已缓解） | 当前工作区不会再因测试产生 pycache 噪音 |
|
||
|
||
## 问题 1：Windows 下 TOML 配置解析失效
|
||
|
||
### 位置
|
||
|
||
- `scripts/playbook.py`
|
||
- 关键入口：
|
||
- `load_config()`
|
||
- `main()`
|
||
|
||
### 现象
|
||
|
||
在当前 Windows 环境中，`playbook.py` 使用 `tomllib.loads()` 解析配置文件时，会因为双引号字符串中的反斜杠路径而直接抛出异常。
|
||
|
||
典型错误：
|
||
|
||
```text
|
||
tomllib.TOMLDecodeError: Invalid hex value (at line 3, column 21)
|
||
```
|
||
|
||
### 根因
|
||
|
||
当前逻辑是：
|
||
|
||
1. 只要运行环境存在 `tomllib`，就直接调用 `tomllib.loads(raw)`。
|
||
2. Windows 临时目录路径通常形如 `D:\...\tmp`。
|
||
3. 这些路径被直接写进 TOML 的双引号字符串后，反斜杠会被 TOML 当作转义前缀。
|
||
4. 结果在真正执行任何动作之前就解析失败。
|
||
|
||
仓库虽然实现了 `loads_toml_minimal()`，但只有 `tomllib` 不存在时才会启用；`tomllib` 存在但解析失败时不会回退。
|
||
|
||
### 影响
|
||
|
||
会阻断以下动作的正常执行：
|
||
|
||
- `vendor`
|
||
- `sync_memory_bank`
|
||
- `sync_rules`
|
||
- `sync_prompts`
|
||
- `sync_standards`
|
||
- `install_skills`
|
||
- `format_md`
|
||
|
||
### 证据
|
||
|
||
- `scripts/playbook.py`
|
||
- `tests/cli/test_playbook_cli.py`
|
||
- `tests/test_format_md_action.py`
|
||
- `tests/test_gitattributes_modes.py`
|
||
- `tests/test_no_backup_flags.py`
|
||
- `tests/test_sync_directory_actions.py`
|
||
- `tests/test_sync_templates_placeholders.py`
|
||
- `tests/test_vendor_snapshot_templates.py`
|
||
|
||
### 修复建议
|
||
|
||
- 在 `tomllib.TOMLDecodeError` 时回退到 `loads_toml_minimal()`。
|
||
- 或统一要求 Windows 路径在 TOML 中使用单引号或双反斜杠。
|
||
- 最好同时补针对 `load_config()` 的 Windows 路径测试，而不是只测备用解析器。
|
||
|
||
## 问题 2：`SKILLS.md` 中 Third-party 内容重复维护
|
||
|
||
### 位置
|
||
|
||
- `SKILLS.md`
|
||
- `codex/skills/.sources/superpowers.list`
|
||
- `.gitea/ci/sync_superpowers.sh`
|
||
- `tests/test_superpowers_list_sync.py`
|
||
|
||
### 现象
|
||
|
||
`SKILLS.md` 的 Third-party Skills (superpowers) 一节同时承担了两种职责：
|
||
|
||
1. 声明第三方技能的来源是 `codex/skills/.sources/superpowers.list`
|
||
2. 在文档内部再次内嵌一份 third-party skills 列表
|
||
|
||
这种设计会制造两份需要同步维护的信息源；一旦同步脚本没有正确执行或生成产物未提交，文档内容和来源清单就会漂移，测试也会随之失败。
|
||
|
||
### 根因
|
||
|
||
Third-party skills 的唯一真相来源本应是 `codex/skills/.sources/superpowers.list`，但仓库同时又要求 `.gitea/ci/sync_superpowers.sh` 把这份列表回写进 `SKILLS.md`。文档承担了“路由页”和“列表副本”两种角色，导致重复维护。
|
||
|
||
### 影响
|
||
|
||
- `SKILLS.md` 容易与真实来源清单失步。
|
||
- 一致性测试会围绕错误契约失败。
|
||
- vendoring 快照会携带多余且容易过期的 third-party 列表副本。
|
||
|
||
### 证据
|
||
|
||
- `SKILLS.md`
|
||
- `codex/skills/.sources/superpowers.list`
|
||
- `tests/test_superpowers_list_sync.py`
|
||
- `.gitea/ci/sync_superpowers.sh`
|
||
|
||
### 修复建议
|
||
|
||
- 保留 `SKILLS.md`，但将 Third-party Skills (superpowers) 一节降级为路由页。
|
||
- 在 `SKILLS.md` 中仅保留来源说明：`codex/skills/.sources/superpowers.list`。
|
||
- 停止由同步脚本向 `SKILLS.md` 回写 third-party skills 列表。
|
||
- 将测试契约改为验证“route-only”，而不是验证 `SKILLS.md` 内嵌列表与来源清单完全一致。
|
||
|
||
## 问题 3：`.agents/index.md` 不会随语言集合更新
|
||
|
||
### 位置
|
||
|
||
- `scripts/playbook.py`
|
||
- 关键函数：
|
||
- `sync_standards_action()`
|
||
- `create_agents_index()`
|
||
|
||
### 现象
|
||
|
||
首次执行 `sync_standards` 时会创建 `.agents/index.md`。但之后如果同步语言集合发生变化，这个文件不会刷新。
|
||
|
||
实测场景：
|
||
|
||
1. 第一次同步：`langs = ["tsl"]`
|
||
2. 第二次同步：`langs = ["tsl", "cpp"]`
|
||
|
||
结果：
|
||
|
||
- `AGENTS.md` 已更新为同时列出 TSL 和 C++
|
||
- `.agents/index.md` 仍然只保留首次创建时的 TSL 入口
|
||
|
||
### 根因
|
||
|
||
`create_agents_index()` 中只要发现 `.agents/index.md` 已存在，就直接返回，不会执行任何重写或区块更新。
|
||
|
||
### 影响
|
||
|
||
- 同一次同步产物内部不一致。
|
||
- `AGENTS.md` 和 `.agents/index.md` 会长期漂移。
|
||
- 后续代理或人工阅读时，可能误以为只有单语言规则生效。
|
||
|
||
### 证据
|
||
|
||
- `scripts/playbook.py`
|
||
- 手工复现实验：两次连续执行 `sync_standards`
|
||
|
||
### 修复建议
|
||
|
||
- 把 `.agents/index.md` 改成幂等重生成。
|
||
- 或为它增加类似 `AGENTS.md` 的区块更新机制。
|
||
- 最好补一个回归测试，覆盖“第二次同步增加语言”的场景。
|
||
|
||
## 问题 4：本地验证文档默认依赖 POSIX shell，缺少平台前提说明
|
||
|
||
### 位置
|
||
|
||
- `CONTRIBUTING.md`
|
||
- `tests/README.md`
|
||
- `tests/templates/*.sh`
|
||
- `tests/integration/check_doc_links.sh`
|
||
|
||
### 现象
|
||
|
||
仓库文档默认要求执行多条 `sh ...` 命令，例如：
|
||
|
||
```text
|
||
sh tests/integration/check_doc_links.sh
|
||
```
|
||
|
||
对于未安装 Git Bash / WSL / Git for Windows 的 Windows 环境，这类命令会直接失败，例如：
|
||
|
||
```text
|
||
sh: The term 'sh' is not recognized
|
||
```
|
||
|
||
当前分析环境中 `sh` 实际可用（来自 Git for Windows），因此上述报错在本机未复现。问题的核心不在于“仓库必然无法在 Windows 运行”，而在于文档没有明确说明这些检查默认依赖 POSIX shell。
|
||
|
||
### 根因
|
||
|
||
模板验证和文档检查采用 POSIX shell 脚本实现，且文档没有明确声明运行这些命令需要 `sh` 环境（例如 Git Bash / WSL / Git for Windows）。仓库也没有提供 PowerShell 或 Python 的替代入口。
|
||
|
||
### 影响
|
||
|
||
- 新环境用户可能误以为任意 Windows PowerShell 都能直接执行这些本地检查。
|
||
- 实际开发体验与 CI（Linux）存在环境前提差异，但文档没有明确提示。
|
||
- 这是文档说明问题，不是当前部署链路或 CI 链路的阻塞故障。
|
||
|
||
### 证据
|
||
|
||
- `tests/README.md`
|
||
- `CONTRIBUTING.md`
|
||
- `tests/templates/validate_python_templates.sh`
|
||
- `tests/templates/validate_cpp_templates.sh`
|
||
- `tests/templates/validate_ci_templates.sh`
|
||
- `tests/templates/validate_project_templates.sh`
|
||
- `tests/integration/check_doc_links.sh`
|
||
|
||
### 修复建议
|
||
|
||
- 在 `CONTRIBUTING.md` 和 `tests/README.md` 中明确说明这些本地检查默认需要 `sh` 环境。
|
||
- 推荐使用 Git Bash / WSL / Git for Windows，并说明 CI 以 Linux 为准。
|
||
- 只有在仓库明确要支持 Windows 本地开发时，再考虑补充 PowerShell 或 Python 替代入口。
|
||
|
||
## 问题 5：`load_config()` 真实入口测试曾缺失（现已补齐）
|
||
|
||
### 位置
|
||
|
||
- `.gitea/workflows/test.yml`
|
||
- `scripts/playbook.py`
|
||
- `tests/test_toml_edge_cases.py`
|
||
|
||
### 现象
|
||
|
||
这个问题按原描述“CI 只跑 Ubuntu，因此 Windows 回归会长期漏检”现在已经不完全成立。
|
||
|
||
当前仓库虽然仍然只有 `ubuntu-22.04` runner，但已经补上了针对主入口 `load_config()` 的回归测试，而且测试输入直接使用 Windows 风格路径。由于这里的故障点是 TOML 字符串解析，而不是 Windows 系统调用，这类测试在 Linux 上同样能有效守住回归。
|
||
|
||
### 根因
|
||
|
||
原先真正的问题不是“没有 Windows runner”本身，而是：
|
||
|
||
- 测试只覆盖了备用解析器 `loads_toml_minimal()`。
|
||
- 没有覆盖真实入口 `load_config()`。
|
||
- 因而让人误以为主路径已有保护。
|
||
|
||
这个缺口现在已经通过 `tests/test_toml_edge_cases.py` 中的 `load_config()` 回归测试补上。
|
||
|
||
### 影响
|
||
|
||
- 历史上的漏测风险已显著下降。
|
||
- 在当前“部署需跨平台、测试和工作流默认 Linux”这一边界下，它不再构成单独阻塞问题。
|
||
- 只有当后续部署链路引入真正依赖 Windows OS 行为的逻辑时，才需要重新评估是否增加 Windows runner。
|
||
|
||
### 证据
|
||
|
||
- `.gitea/workflows/test.yml`
|
||
- `scripts/playbook.py`
|
||
- `tests/test_toml_edge_cases.py`
|
||
- `python -m unittest tests.test_toml_edge_cases -v`
|
||
|
||
### 处理建议
|
||
|
||
- 保持 Linux CI 不变。
|
||
- 持续保留 `load_config()` 的 Windows 路径回归测试。
|
||
- 不再把“增加 Windows runner”作为当前问题的默认修复项；只有出现真正的 OS 级差异时再引入。
|
||
|
||
## 问题 6：Python 缓存忽略已补上（现已缓解）
|
||
|
||
### 位置
|
||
|
||
- `.gitignore`
|
||
|
||
### 现象
|
||
|
||
这个问题按原描述也已不再成立。`.gitignore` 已显式忽略当前仓库会产生的 Python 缓存目录：
|
||
|
||
- `scripts/__pycache__`
|
||
- `tests/__pycache__`
|
||
- `tests/cli/__pycache__`
|
||
|
||
并且 `git check-ignore -v` 可以验证这些路径当前都会被忽略。
|
||
|
||
### 根因
|
||
|
||
历史上的问题确实是缺少缓存忽略项；当前仓库已经通过定向规则补上。结合仓库里 Python 文件目前只分布在 `scripts/`、`tests/` 和 `tests/cli/`，这些规则已经覆盖实际产物路径。
|
||
|
||
### 影响
|
||
|
||
- 当前工作区不会再因为测试生成的 `__pycache__` 目录而变脏。
|
||
- 剩余的只是“规则偏定向、不够通用”的风格问题，不再是当前确认问题。
|
||
|
||
### 证据
|
||
|
||
- `.gitignore`
|
||
- `git check-ignore -v scripts/__pycache__/x.pyc tests/__pycache__/x.pyc tests/cli/__pycache__/x.pyc`
|
||
- `rg --files -g "*.py"`
|
||
|
||
### 处理建议
|
||
|
||
- 保持现有规则即可。
|
||
- 如果后续新增 Python 目录，再考虑收敛为通用规则：`__pycache__/`、`*.pyc`、`*.pyo`。
|
||
|
||
## 已执行验证
|
||
|
||
已执行：
|
||
|
||
```text
|
||
python -m unittest discover -s tests/cli -v
|
||
python -m unittest discover -s tests -p "test_*.py" -v
|
||
```
|
||
|
||
结果摘要：
|
||
|
||
- `tests/cli`：3 通过，6 失败
|
||
- `tests`：13 通过，14 失败
|
||
|
||
无法在当前环境完成：
|
||
|
||
```text
|
||
sh tests/integration/check_doc_links.sh
|
||
```
|
||
|
||
原因：
|
||
|
||
- 当前 Windows 环境缺少 `sh`
|
||
|
||
## 建议修复优先级
|
||
|
||
1. 先修问题 1：否则大部分 CLI 回归测试都无法有效验证。
|
||
2. 再修问题 2 和问题 3：这两项会直接影响产出内容正确性。
|
||
3. 然后处理问题 4 和问题 5：补平台说明和测试覆盖。
|
||
4. 最后处理问题 6：属于低风险但高频噪音问题。
|