3.9 KiB
3.9 KiB
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 已实现统一策略)
配置开关位置
- 添加到 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
- 配置变更后的日志记录级别
<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>
## Specific Ideas- 配置变更影响 — 添加到 KBSettings 后,现有代码需要从配置读取而非硬编码默认值
- 向后兼容性 — 禁用时(enable_semantic_segmentation=False),应完全使用规则分段,不调用 LLM
- 日志记录 — 配置启用/禁用状态应在 SRTProcessor 初始化时记录日志
- 缓存配置选项 — 是否需要将 enable_cache 也添加到 KBSettings(当前只有构造函数参数)
- 分段粒度配置 — 未来可能允许用户配置目标分段数量(当前硬编码为 5-8)
- 环境变量简化 — 是否需要更短的别名(如 KB_LLMSeg)作为备选
Phase: 15-output-compat Context gathered: 2026-03-23