docs(phase-15): create phase 15 plans

This commit is contained in:
2026-03-23 22:53:07 +08:00
parent 6ea21ad565
commit 405761c6ea
4 changed files with 766 additions and 0 deletions
@@ -0,0 +1,161 @@
---
phase: 15-output-compat
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
- kb_workflow/pipeline/config.py
- tests/test_pipeline/test_config.py
autonomous: true
requirements:
- CONFIG-01
must_haves:
truths:
- "KBSettings 包含 enable_semantic_segmentation 字段"
- "字段默认值为 True"
- "可通过 KB_ENABLE_SEMANTIC_SEGMENTATION 环境变量覆盖"
- "Pydantic 自动解析布尔字符串(true/false, yes/no, 1/0)"
artifacts:
- path: "kb_workflow/pipeline/config.py"
provides: "KBSettings 配置类"
exports: ["enable_semantic_segmentation: bool"]
- path: "tests/test_pipeline/test_config.py"
provides: "配置测试"
contains: "TestEnableSemanticSegmentationField"
key_links:
- from: "KBSettings.__init__()"
to: "pydantic-settings BaseSettings"
via: "model_config = SettingsConfigDict(env_prefix='KB_')"
pattern: "class KBSettings\\(BaseSettings\\)"
- from: "环境变量 KB_ENABLE_SEMANTIC_SEGMENTATION"
to: "KBSettings.enable_semantic_segmentation"
via: "pydantic-settings 自动解析"
pattern: "env_prefix.*KB_"
---
<objective>
将 enable_semantic_segmentation 配置集成到 KBSettings,允许用户通过环境变量或 ~/.kb_env 文件控制 LLM 语义分段功能。
Purpose: 集中配置管理,用户无需修改代码即可启用/禁用语义分段
Output: KBSettings 新增字段,默认启用语义分段(True)
</objective>
<execution_context>
@/home/starmen1265/.claude/get-shit-done/workflows/execute-plan.md
@/home/starmen1265/.claude/get-shit-done/templates/summary.md
</execution_context>
<context>
@.planning/phases/15-output-compat/15-CONTEXT.md
@.planning/phases/15-output-compat/15-RESEARCH.md
@.planning/phases/14-robustness-cost/14-05-SUMMARY.md
@kb_workflow/pipeline/config.py
</context>
<interfaces>
<!-- KBSettings 现有结构 -->
From kb_workflow/pipeline/config.py:
```python
class KBSettings(BaseSettings):
model_config = SettingsConfigDict(
env_file=str(Path.home() / ".kb_env"),
env_file_encoding="utf-8",
env_prefix="KB_",
extra="ignore",
)
# 必需配置
base_path: str = Field(..., description="知识库根目录")
archive_path: str = Field(..., description="归档目录")
# 可选配置
git_root: str = Field(default="", description="Git 仓库根目录")
# 工作流行为配置
overwrite_archives: bool = Field(
default=False, description="覆盖已存在的归档文件(非交互模式)"
)
```
<!-- Pattern: 添加布尔配置字段 -->
```python
# 新增字段的模式
enable_semantic_segmentation: bool = Field(
default=True,
description="启用 LLM 语义分段(默认启用)"
)
```
<!-- Environment Variable Resolution -->
# ~/.kb_env 文件:
# KB_ENABLE_SEMANTIC_SEGMENTATION=true
# Pydantic 自动解析以下字符串为布尔 True:
# - "true", "True", "TRUE", "t", "yes", "y", "1"
# - False: "false", "False", "FALSE", "f", "no", "n", "0"
</interfaces>
<tasks>
<task type="auto" tdd="true">
<name>Task 1: 添加 enable_semantic_segmentation 字段到 KBSettings</name>
<files>kb_workflow/pipeline/config.py, tests/test_pipeline/test_config.py</files>
<behavior>
- Test 1: KBSettings 包含 enable_semantic_segmentation 字段,类型为 bool
- Test 2: 字段默认值为 True(未设置环境变量时)
- Test 3: 环境变量 KB_ENABLE_SEMANTIC_SEGMENTATION=false 覆盖默认值
- Test 4: 环境变量支持多种布尔表示(true, yes, 1 / false, no, 0)
</behavior>
<action>
1. 在 kb_workflow/pipeline/config.py 的 KBSettings 类中添加新字段:
```python
# 工作流行为配置
enable_semantic_segmentation: bool = Field(
default=True,
description="启用 LLM 语义分段(默认启用)"
)
```
位置:在 overwrite_archives 字段之后,保持配置分类清晰。
2. 更新 KBSettings 的 docstring,添加新字段的文档说明。
3. 实现测试(在 test_config.py 中移除 skip 标记):
- test_kbsettings_has_enable_semantic_segmentation_field
- test_enable_semantic_segmentation_default_value
- test_enable_semantic_segmentation_from_env
- test_enable_semantic_segmentation_boolean_parsing
测试模式参考现有的 test_kbsettings_has_base_path_field 等测试。
</action>
<verify>
<automated>pytest tests/test_pipeline/test_config.py::TestEnableSemanticSegmentationField -x -v</automated>
</verify>
<done>
- KBSettings.enable_semantic_segmentation 字段存在
- 默认值为 True
- 环境变量 KB_ENABLE_SEMANTIC_SEGMENTATION 可覆盖
- 4 个测试全部通过
</done>
</task>
</tasks>
<verification>
- pytest tests/test_pipeline/test_config.py::TestEnableSemanticSegmentationField 全部通过
- 字段类型为 bool,默认值为 True
- 环境变量解析正确(支持 true/false, yes/no, 1/0)
- 不影响现有配置字段
</verification>
<success_criteria>
- CONFIG-01 需求满足:LLM 分段功能可通过配置启用/禁用
- KBSettings 配置类符合 pydantic-settings 规范
- 测试覆盖默认值、环境变量覆盖、布尔解析
</success_criteria>
<output>
After completion, create `.planning/phases/15-output-compat/15-01-SUMMARY.md`
</output>