3.0 KiB
3.0 KiB
PLAN — 决策与路径
目标
在保持改动范围最小的前提下，让：
- CI 的
markdown-lint阶段可执行且退出 0； - 本地
make lint与 CI 完全一致（不会假通过）； - 迁移后仍会误导执行的旧路径指引被修复；
.gitignore与新结构一致，避免产物污染工作区。
方案对比（至少两种）
方案 A（推荐）：补齐 .github/lint_config.json + 对齐 Makefile + 最小修文档/忽略
做法
- 新增
.github/lint_config.json，以“最小放宽”让现有文档可通过。 - 更新
Makefile：使用与 CI 相同的 glob 形式（引用'**/*.md'），并指向同一 config。 - 修复少量关键文档旧路径（仅指引类 README/参考文档）。
- 更新
.gitignore覆盖assets/repo/backups/gz/与迁移后的 venv 路径。
Pros
- 改动小、可回滚、最容易让 CI 回绿。
- 不需要全仓重排 Markdown。
Cons
- 可能需要在 lint config 中禁用部分规则（需要记录原因，避免“质量坍塌”）。
方案 B：严格 lint（少放宽）+ 大范围修正文档格式
做法
- 补齐
.github/lint_config.json，尽量保持严格规则； - 逐个修正文档以满足规则（可能涉及大量文件）。
Pros
- 长期文档质量更稳定，规则更强约束。
Cons
- 成本巨大、风险高（断链/误改内容/大 PR 难回滚），不符合“最少修改原则”。
决策
选择 方案 A。若后续需要提升文档质量，再开独立任务做“严格化 + 大规模修复”，避免一次 PR 混入两类目标。
逻辑流图（Mermaid）
flowchart LR
dev_make[make lint] --> lint_cmd[markdownlint]
ci[GitHub Actions CI] --> lint_cmd
lint_cmd --> config[.github/lint_config.json]
lint_cmd --> glob['**/*.md']
原子变更清单（文件级，不写代码）
- 新增：
.github/lint_config.json（最小放宽，明确记录禁用项原因）。 - 修改：
Makefile的lint目标：- 使用 quoted glob：
'**/*.md' - 使用
--config .github/lint_config.json
- 使用 quoted glob：
- 修改：
.gitignore：- 忽略
assets/repo/backups/gz/ - 更新旧路径忽略项（如
skills/skills-skills/...→assets/skills/...）
- 忽略
- 修改：
assets/config/.codex/README.md（复制命令路径纠正）。 - 修改：
assets/skills/skills-skills/references/*.md（示例路径纠正）。 - 评估（可选）：是否需要限定 lint 范围/忽略
assets/repo/**（若第三方镜像导致无法通过）。
回滚协议（自愈步骤）
若任何一步导致 lint 或文档入口不可用：
git status --porcelain=v1确认改动文件集合git restore --staged --worktree <file...>回退到改动前（或git revert <commit>若已提交）- 重新跑：
make lintmarkdownlint --config .github/lint_config.json '**/*.md'
- 若仅
.github/lint_config.json导致行为异常，可先临时移除该文件再复验，以确认根因