# Phase 15: 输出优化与兼容性 - Context **Gathered:** 2026-03-23 **Status:** Ready for planning ## Phase Boundary 优化输出格式并确保配置开关和向后兼容性。 **核心能力:** - 输出格式优化(已在 Phase 13 完成)— 主题/章节分段输出带 H2 标题的 Markdown 结构 - 配置开关集成 — 将 enable_semantic_segmentation 添加到 KBSettings - 向后兼容性验证 — 确保禁用时不破坏现有规则分段功能 **不包括:** - 新的输出格式设计(Phase 13 已完成) - 新的分段策略(Phase 13 已实现统一策略) ## Implementation Decisions ### 配置开关位置 - **添加到 KBSettings** — 将 `enable_semantic_segmentation` 添加到 `kb_workflow/pipeline/config.py` 中的 `KBSettings` 类 - **配置方式** — 用户可在 `~/.kb_env` 文件中设置 `KB_ENABLE_SEMANTIC_SEGMENTATION=true` - **优点** — 与现有配置(KB_BASE_PATH、KB_ARCHIVE_PATH 等)保持一致,集中管理 ### 环境变量命名 - **变量名**: `KB_ENABLE_SEMANTIC_SEGMENTATION` — 使用全名,清晰明确 - **风格一致** — 与现有配置变量命名保持一致(KB_ 前缀,全大写下划线分隔) - **示例**: `KB_ENABLE_SEMANTIC_SEGMENTATION=true` 或 `KB_ENABLE_SEMANTIC_SEGMENTATION=false` ### 默认行为 - **默认启用** — 当用户未配置时,默认值为 `True`(启用语义分段) - **API Key 检查保留** — 即使配置启用,如果 AI API key 未配置,代码仍会自动降级到规则分段 - **用户体验** — 配置了 API key 的用户自动获得最佳体验,无需额外配置 ### Claude's Discretion - KBSettings 中字段的具体类型定义(bool Field with default) - 是否需要添加 enable_cache 相关的配置选项到 KBSettings - 配置变更后的日志记录级别 ## Existing Code Insights ### Reusable Assets - **kb_workflow/pipeline/config.py** — KBSettings 类,使用 pydantic-settings 从环境变量和 ~/.kb_env 加载配置 - **kb_workflow/pipeline/processors/srt.py** — SRTProcessor 类,已有 `enable_semantic_segmentation` 构造函数参数 - **kb_workflow/srt/semantic_engine.py** — SemanticSegmentationEngine,语义分段的核心实现 ### Established Patterns - **Pydantic Settings 模式** — 使用 BaseSettings,env_file="~/.kb_env",env_prefix="KB_" - **SecretStr 敏感信息** — hf_token, zhihu_cookie 等使用 SecretStr 类型 - **布尔配置示例** — `overwrite_archives: bool = Field(default=False, description="...")` ### Integration Points - **KBSettings 类** — 需要添加 `enable_semantic_segmentation: bool` 字段 - **SRTProcessor 初始化** — 需要从 `get_settings()` 读取配置并传递给构造函数 - **CLI 入口** — `kb_workflow/kb_workflow.py` 中创建 SRTProcessor 时使用配置值 ### 已实现的功能(Phase 13/14) - `_generate_markdown()` 已实现语义分段的 H2 标题输出(OUTPUT-01, OUTPUT-02 已满足) - 规则分段继续使用 "## 内容" 标题(OUTPUT-03 向后兼容已满足) - AnalyzeProcessor 处理知乎/文章,不受 SRTProcessor 变更影响(CONFIG-03 已满足) ## Specific Ideas - **配置变更影响** — 添加到 KBSettings 后,现有代码需要从配置读取而非硬编码默认值 - **向后兼容性** — 禁用时(enable_semantic_segmentation=False),应完全使用规则分段,不调用 LLM - **日志记录** — 配置启用/禁用状态应在 SRTProcessor 初始化时记录日志 ## Deferred Ideas - **缓存配置选项** — 是否需要将 enable_cache 也添加到 KBSettings(当前只有构造函数参数) - **分段粒度配置** — 未来可能允许用户配置目标分段数量(当前硬编码为 5-8) - **环境变量简化** — 是否需要更短的别名(如 KB_LLMSeg)作为备选 --- *Phase: 15-output-compat* *Context gathered: 2026-03-23*