This repository has been archived on 2026-08-07. You can view files and clone it. You cannot open issues or pull requests or push a commit.
Files
kb-skills/.planning/phases/15-output-compat/15-CONTEXT.md
T

3.9 KiB
Raw Blame History

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
  • 配置变更后的日志记录级别

<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 初始化时记录日志
## Deferred Ideas
  • 缓存配置选项 — 是否需要将 enable_cache 也添加到 KBSettings(当前只有构造函数参数)
  • 分段粒度配置 — 未来可能允许用户配置目标分段数量(当前硬编码为 5-8)
  • 环境变量简化 — 是否需要更短的别名(如 KB_LLMSeg)作为备选

Phase: 15-output-compat Context gathered: 2026-03-23