初始痛点
- 单体脚本串行，耗时长且定位困难；
- 导航与聚合逻辑耦合紧，改动容易回归；
- 无统一指标出口，CI/本地观感不一致。
目标与改造要点
- 拆分职责模块（collect/sync/feeds/i18n/writer），并补齐单元与集成测试；
- 引入缓存、增量同步与批量写入，支持哈希跳过；
- Schema 化导航/语言/标签配置，运行前即守门；
- Telemetry 输出阶段指标，统一 CLI/页面观测；
- 调度并行化与插件生态，暴露生命周期事件。
收益与指标
- 重复运行的构建耗时显著下降；
- 写入阶段哈希命中减少不必要 I/O；
- 观测页可直观看到缓存命中率、写入失败、并发覆写与插件加载结果；
- 遇到异常时能迅速定位阶段、语言与目标路径。
风险与遗留
- 英文目录缺内容 → 导航 manifest 为空（不阻断）；
- 初期命中率偏低 → 属于冷启动正常现象；
- 插件错误可能中断生成 → 可在本地先用
--ignore-plugin-errors； - 需要持续维护 Schema 与测试，防止配置漂移。
占位阶段的经验
占位运行（placeholder）是一条稳妥的起步路线：
- 可以不依赖大模型或网络，先把内容/聚合/导航打通；
- 冒烟失败会自动回退，不会污染线上产物；
- Telemetry 用 “missing/skipped” 明确标记状态，提醒后续接入真实模型。
切换到真实模型时，只需参考《AI 管线占位与切换指南》，按步骤准备依赖、配置适配器、运行 ai:prepare && ai:smoke 即可。
下一步计划
- 丰富官方插件示例（如性能报告上报、链接检查增强）；
- 补齐英文内容，消除空 manifest 警告；
- 将 Pagegen 指标曲线化，提供历史趋势比对；
- 在 Telemetry 页加入告警阈值配置与屏蔽策略。