diff --git a/.planning/phases/15-output-compat/15-CONTEXT.md b/.planning/phases/15-output-compat/15-CONTEXT.md new file mode 100644 index 0000000..75b05f5 --- /dev/null +++ b/.planning/phases/15-output-compat/15-CONTEXT.md @@ -0,0 +1,101 @@ +# 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*