docs(15): capture phase context

.planning/phases/15-output-compat/15-CONTEXT.md

@@ -0,0 +1,101 @@
+# Phase 15: 输出优化与兼容性 - Context
+
+**Gathered:** 2026-03-23
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+优化输出格式并确保配置开关和向后兼容性。
+
+**核心能力：**
+- 输出格式优化（已在 Phase 13 完成）— 主题/章节分段输出带 H2 标题的 Markdown 结构
+- 配置开关集成 — 将 enable_semantic_segmentation 添加到 KBSettings
+- 向后兼容性验证 — 确保禁用时不破坏现有规则分段功能
+
+**不包括：**
+- 新的输出格式设计（Phase 13 已完成）
+- 新的分段策略（Phase 13 已实现统一策略）
+
+</domain>
+
+<decisions>
+## 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
+- 配置变更后的日志记录级别
+
+</decisions>
+
+<code_context>
+## 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 已满足）
+
+</code_context>
+
+<specifics>
+## Specific Ideas
+
+- **配置变更影响** — 添加到 KBSettings 后，现有代码需要从配置读取而非硬编码默认值
+- **向后兼容性** — 禁用时（enable_semantic_segmentation=False），应完全使用规则分段，不调用 LLM
+- **日志记录** — 配置启用/禁用状态应在 SRTProcessor 初始化时记录日志
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+- **缓存配置选项** — 是否需要将 enable_cache 也添加到 KBSettings（当前只有构造函数参数）
+- **分段粒度配置** — 未来可能允许用户配置目标分段数量（当前硬编码为 5-8）
+- **环境变量简化** — 是否需要更短的别名（如 KB_LLMSeg）作为备选
+
+</deferred>
+
+---
+
+*Phase: 15-output-compat*
+*Context gathered: 2026-03-23*