329 lines
12 KiB
Markdown
329 lines
12 KiB
Markdown
---
|
|
phase: 06-code-consolidation
|
|
plan: 03
|
|
type: execute
|
|
wave: 1
|
|
depends_on: [06-01, 06-02]
|
|
files_modified:
|
|
- kb_workflow/kb_workflow.py
|
|
- kb_workflow/metadata/zhihu_extractor.py
|
|
- kb_workflow/metadata/zhihu_metadata.py
|
|
- kb_workflow/pipeline/processors/analyze.py
|
|
- kb_workflow/pipeline/__init__.py
|
|
autonomous: true
|
|
requirements: [MET-05, PIP-04]
|
|
gap_closure: true
|
|
|
|
must_haves:
|
|
truths:
|
|
- "所有 sys.path.insert 操作已从代码库中删除"
|
|
- "Pipeline 类可从 kb_workflow.pipeline 包级别导入"
|
|
- "所有模块使用标准 Python 包导入，无动态路径操作"
|
|
artifacts:
|
|
- path: "kb_workflow/kb_workflow.py"
|
|
provides: "CLI 入口"
|
|
contains: "无 sys.path 操作"
|
|
- path: "kb_workflow/metadata/zhihu_extractor.py"
|
|
provides: "知乎内容提取"
|
|
contains: "无 sys.path 操作"
|
|
- path: "kb_workflow/metadata/zhihu_metadata.py"
|
|
provides: "知乎元数据 CLI"
|
|
contains: "无 sys.path 操作"
|
|
- path: "kb_workflow/pipeline/processors/analyze.py"
|
|
provides: "AI 分析处理器"
|
|
contains: "无 sys.path 操作"
|
|
- path: "kb_workflow/pipeline/__init__.py"
|
|
provides: "Pipeline 包入口"
|
|
exports: ["Pipeline"]
|
|
key_links:
|
|
- from: "kb_workflow/pipeline/__init__.py"
|
|
to: "kb_workflow/pipeline/pipeline.py"
|
|
via: "from kb_workflow.pipeline.pipeline import Pipeline"
|
|
pattern: "from kb_workflow.pipeline.pipeline import Pipeline"
|
|
---
|
|
|
|
<objective>
|
|
消除代码库中遗留的 sys.path 动态操作，完善 Pipeline 类的包级别导出。
|
|
|
|
Purpose: 完成 Phase 6 的目标 —— 建立干净的 Python 包结构，无动态路径操作
|
|
Output: 5 个文件被修改，所有 sys.path 操作被删除，Pipeline 可从包级别导入
|
|
</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/PROJECT.md
|
|
@.planning/ROADMAP.md
|
|
@.planning/STATE.md
|
|
@.planning/phases/06-code-consolidation/06-VERIFICATION.md
|
|
|
|
## Gap 来源
|
|
|
|
06-VERIFICATION.md 发现了以下问题：
|
|
|
|
1. **sys.path 操作遗留** - 4 处文件中仍有 sys.path.insert 操作
|
|
2. **Pipeline 导出缺失** - Pipeline 类未在 `kb_workflow/pipeline/__init__.py` 中导出
|
|
|
|
## 当前文件状态
|
|
|
|
### kb_workflow/kb_workflow.py (第 40-43 行)
|
|
```python
|
|
# Add project root to path for kb_pipeline imports
|
|
project_root = Path(__file__).parent.parent
|
|
if str(project_root) not in sys.path:
|
|
sys.path.insert(0, str(project_root))
|
|
```
|
|
**问题**: 不再需要，因为 kb_workflow 已是正确的包结构
|
|
|
|
### kb_workflow/metadata/zhihu_extractor.py (第 12-15 行)
|
|
```python
|
|
# 添加当前目录到 Python 路径以支持绝对导入
|
|
current_dir = os.path.dirname(os.path.abspath(__file__))
|
|
if current_dir not in sys.path:
|
|
sys.path.insert(0, current_dir)
|
|
```
|
|
**问题**: 不再需要，markdown_converter 可通过相对导入 `.markdown_converter` 访问
|
|
|
|
### kb_workflow/metadata/zhihu_metadata.py (第 18-21 行)
|
|
```python
|
|
# 添加当前目录到 Python 路径
|
|
current_dir = os.path.dirname(os.path.abspath(__file__))
|
|
if current_dir not in sys.path:
|
|
sys.path.insert(0, current_dir)
|
|
```
|
|
**问题**: 不再需要，zhihu_extractor 可通过相对导入 `.zhihu_extractor` 访问
|
|
|
|
### kb_workflow/pipeline/processors/analyze.py (第 16-19 行)
|
|
```python
|
|
# Add kb-deep-analyzer to path for import
|
|
_kb_deep_analyzer_path = Path(__file__).parent.parent.parent / "kb-deep-analyzer"
|
|
if str(_kb_deep_analyzer_path) not in sys.path:
|
|
sys.path.insert(0, str(_kb_deep_analyzer_path))
|
|
```
|
|
**问题**: 这是为外部项目 kb-deep-analyzer 添加路径，需评估是否保留
|
|
|
|
### kb_workflow/pipeline/__init__.py
|
|
当前缺少 `from kb_workflow.pipeline.pipeline import Pipeline` 和在 `__all__` 中导出
|
|
|
|
</context>
|
|
|
|
<tasks>
|
|
|
|
<task type="auto">
|
|
<name>Task 1: 删除 kb_workflow.py 中的 sys.path 操作</name>
|
|
<files>kb_workflow/kb_workflow.py</files>
|
|
<action>
|
|
删除第 40-43 行的 sys.path 操作代码块：
|
|
```python
|
|
# Add project root to path for kb_pipeline imports
|
|
project_root = Path(__file__).parent.parent
|
|
if str(project_root) not in sys.path:
|
|
sys.path.insert(0, str(project_root))
|
|
```
|
|
|
|
原因：kb_workflow 现在是正确的 Python 包结构，所有导入都可以通过 `from kb_workflow.pipeline.xxx` 正常工作，不需要动态添加路径。
|
|
|
|
同时更新模块顶部的注释（第 8 行），将 "内部使用 kb_pipeline 包" 改为 "内部使用 kb_workflow.pipeline 包"。
|
|
</action>
|
|
<verify>
|
|
<automated>grep -n "sys.path" kb_workflow/kb_workflow.py; test $? -eq 1</automated>
|
|
</verify>
|
|
<done>kb_workflow.py 中无 sys.path 相关代码，CLI 仍可正常执行 --help</done>
|
|
</task>
|
|
|
|
<task type="auto">
|
|
<name>Task 2: 删除 zhihu_extractor.py 中的 sys.path 操作</name>
|
|
<files>kb_workflow/metadata/zhihu_extractor.py</files>
|
|
<action>
|
|
1. 删除第 12-15 行的 sys.path 操作代码块：
|
|
```python
|
|
# 添加当前目录到 Python 路径以支持绝对导入
|
|
current_dir = os.path.dirname(os.path.abspath(__file__))
|
|
if current_dir not in sys.path:
|
|
sys.path.insert(0, current_dir)
|
|
```
|
|
|
|
2. 更新第 17-20 行的导入方式，改为纯相对导入：
|
|
```python
|
|
# 旧代码：
|
|
try:
|
|
from .markdown_converter import MarkdownConverter
|
|
except ImportError:
|
|
from markdown_converter import MarkdownConverter
|
|
|
|
# 新代码：
|
|
from .markdown_converter import MarkdownConverter
|
|
```
|
|
|
|
原因：kb_workflow.metadata 已是标准 Python 包，相对导入可以正常工作。
|
|
</action>
|
|
<verify>
|
|
<automated>grep -n "sys.path" kb_workflow/metadata/zhihu_extractor.py; test $? -eq 1</automated>
|
|
</verify>
|
|
<done>zhihu_extractor.py 中无 sys.path 相关代码，模块可正常导入</done>
|
|
</task>
|
|
|
|
<task type="auto">
|
|
<name>Task 3: 删除 zhihu_metadata.py 中的 sys.path 操作</name>
|
|
<files>kb_workflow/metadata/zhihu_metadata.py</files>
|
|
<action>
|
|
1. 删除第 18-21 行的 sys.path 操作代码块：
|
|
```python
|
|
# 添加当前目录到 Python 路径
|
|
current_dir = os.path.dirname(os.path.abspath(__file__))
|
|
if current_dir not in sys.path:
|
|
sys.path.insert(0, current_dir)
|
|
```
|
|
|
|
2. 更新第 23 行的导入方式，改为相对导入：
|
|
```python
|
|
# 旧代码：
|
|
from zhihu_extractor import ZhihuPlaywrightExtractor
|
|
|
|
# 新代码：
|
|
from .zhihu_extractor import ZhihuPlaywrightExtractor
|
|
```
|
|
|
|
原因：kb_workflow.metadata 已是标准 Python 包，相对导入可以正常工作。
|
|
</action>
|
|
<verify>
|
|
<automated>grep -n "sys.path" kb_workflow/metadata/zhihu_metadata.py; test $? -eq 1</automated>
|
|
</verify>
|
|
<done>zhihu_metadata.py 中无 sys.path 相关代码，CLI 可正常执行</done>
|
|
</task>
|
|
|
|
<task type="auto">
|
|
<name>Task 4: 处理 analyze.py 中的 sys.path 操作</name>
|
|
<files>kb_workflow/pipeline/processors/analyze.py</files>
|
|
<action>
|
|
这处 sys.path 操作是为外部项目 kb-deep-analyzer 添加路径。评估后决定：
|
|
|
|
**保留但重构**：将 sys.path 操作移到 lazy import 内部，只在需要时执行一次。
|
|
|
|
修改方案：
|
|
1. 删除第 16-19 行的顶层 sys.path 操作
|
|
2. 在 `_run_analysis` 方法（第 193-214 行）中，在 `from deep_analyzer import ...` 之前动态添加路径
|
|
3. 添加模块级标志位 `_deep_analyzer_path_added = False` 确保只添加一次
|
|
|
|
具体实现：
|
|
```python
|
|
# 在文件顶部（删除原来的 sys.path 操作后）
|
|
_deep_analyzer_path_added = False
|
|
|
|
# 在 _run_analysis 方法中，第 204 行之前添加：
|
|
global _deep_analyzer_path_added
|
|
if not _deep_analyzer_path_added:
|
|
_kb_deep_analyzer_path = Path(__file__).parent.parent.parent / "kb-deep-analyzer"
|
|
if str(_kb_deep_analyzer_path) not in sys.path:
|
|
sys.path.insert(0, str(_kb_deep_analyzer_path))
|
|
_deep_analyzer_path_added = True
|
|
```
|
|
|
|
原因：kb-deep-analyzer 是外部项目，不在 kb_workflow 包内，需要通过 sys.path 引入。但将其移到 lazy import 内部更干净。
|
|
</action>
|
|
<verify>
|
|
<automated>grep -n "sys.path" kb_workflow/pipeline/processors/analyze.py | grep -v "_run_analysis" | wc -l | xargs test 0 -eq</automated>
|
|
</verify>
|
|
<done>analyze.py 的 sys.path 操作移到 lazy import 内部，顶层无 sys.path 操作</done>
|
|
</task>
|
|
|
|
<task type="auto">
|
|
<name>Task 5: 在 pipeline/__init__.py 中导出 Pipeline 类</name>
|
|
<files>kb_workflow/pipeline/__init__.py</files>
|
|
<action>
|
|
在 kb_workflow/pipeline/__init__.py 中添加 Pipeline 类的导入和导出：
|
|
|
|
1. 在导入区域（第 28 行之后）添加：
|
|
```python
|
|
from kb_workflow.pipeline.pipeline import Pipeline
|
|
```
|
|
|
|
2. 在 `__all__` 列表中（第 30 行之后）添加：
|
|
```python
|
|
"Pipeline",
|
|
```
|
|
|
|
最终 `__all__` 应该包含 "Pipeline" 字符串。
|
|
|
|
注意：确保 Pipeline 类在其他导入之后添加，避免循环导入问题。
|
|
</action>
|
|
<verify>
|
|
<automated>python -c "from kb_workflow.pipeline import Pipeline; print('Pipeline import OK')"</automated>
|
|
</verify>
|
|
<done>Pipeline 类可从 kb_workflow.pipeline 包级别导入</done>
|
|
</task>
|
|
|
|
<task type="auto">
|
|
<name>Task 6: 验证所有更改</name>
|
|
<files>kb_workflow/kb_workflow.py, kb_workflow/metadata/zhihu_extractor.py, kb_workflow/metadata/zhihu_metadata.py, kb_workflow/pipeline/processors/analyze.py, kb_workflow/pipeline/__init__.py</files>
|
|
<action>
|
|
运行全面验证：
|
|
|
|
1. 检查所有文件中无顶层 sys.path 操作（analyze.py 除外，其 sys.path 在方法内部）：
|
|
```bash
|
|
grep -rn "sys.path" kb_workflow/ --include="*.py" | grep -v "analyze.py" | grep -v ".pyc"
|
|
```
|
|
|
|
2. 验证所有核心导入正常工作：
|
|
```bash
|
|
python -c "from kb_workflow.pipeline import Pipeline; print('Pipeline OK')"
|
|
python -c "from kb_workflow.metadata.zhihu_extractor import ZhihuPlaywrightExtractor; print('ZhihuExtractor OK')"
|
|
python -c "from kb_workflow import process_command; print('CLI OK')"
|
|
```
|
|
|
|
3. 验证 CLI 可执行：
|
|
```bash
|
|
python kb_workflow/kb_workflow.py --help
|
|
```
|
|
|
|
4. 运行测试（预期 14 个预先存在的 mock 相关失败）：
|
|
```bash
|
|
pytest tests/ -v --tb=short 2>&1 | tail -20
|
|
```
|
|
</action>
|
|
<verify>
|
|
<automated>python -c "from kb_workflow.pipeline import Pipeline; from kb_workflow.metadata.zhihu_extractor import ZhihuPlaywrightExtractor; from kb_workflow import process_command; print('All imports OK')"</automated>
|
|
</verify>
|
|
<done>所有导入正常，CLI 可执行，无新增测试失败</done>
|
|
</task>
|
|
|
|
</tasks>
|
|
|
|
<verification>
|
|
## Gap Closure Verification
|
|
|
|
| Gap | Status | Verification |
|
|
|-----|--------|-------------|
|
|
| sys.path 操作未完全消除 | CLOSED | `grep -rn "sys.path" kb_workflow/ --include="*.py" | grep -v "analyze.py" | grep -v ".pyc"` 返回空 |
|
|
| Pipeline 未在包级别导出 | CLOSED | `from kb_workflow.pipeline import Pipeline` 成功 |
|
|
|
|
## Test Commands
|
|
|
|
```bash
|
|
# 验证无遗留 sys.path（除 analyze.py 内部）
|
|
grep -rn "sys.path" kb_workflow/ --include="*.py" | grep -v "analyze.py" | grep -v ".pyc"
|
|
|
|
# 验证 Pipeline 导出
|
|
python -c "from kb_workflow.pipeline import Pipeline; print('OK')"
|
|
|
|
# 验证 CLI
|
|
python kb_workflow/kb_workflow.py --help
|
|
```
|
|
</verification>
|
|
|
|
<success_criteria>
|
|
1. kb_workflow/kb_workflow.py 无 sys.path 操作
|
|
2. kb_workflow/metadata/zhihu_extractor.py 无 sys.path 操作
|
|
3. kb_workflow/metadata/zhihu_metadata.py 无 sys.path 操作
|
|
4. kb_workflow/pipeline/processors/analyze.py 的 sys.path 操作移到 lazy import 内部
|
|
5. Pipeline 类可从 kb_workflow.pipeline 包级别导入
|
|
6. 所有现有功能正常工作，无新增测试失败
|
|
</success_criteria>
|
|
|
|
<output>
|
|
After completion, create `.planning/phases/06-code-consolidation/06-03-SUMMARY.md`
|
|
</output>
|