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

102 lines
3.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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*