From fdd6c0821121419c9d0a67f0e4a1611050166c53 Mon Sep 17 00:00:00 2001 From: starmen1265 Date: Tue, 17 Mar 2026 00:28:35 +0800 Subject: [PATCH] docs(06): create gap closure plan 06-03 --- .planning/ROADMAP.md | 13 +- .../06-code-consolidation/06-03-PLAN.md | 328 ++++++++++++++++++ 2 files changed, 336 insertions(+), 5 deletions(-) create mode 100644 .planning/phases/06-code-consolidation/06-03-PLAN.md diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 79eef2c..bae1656 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -68,7 +68,7 @@ Plans: - [x] 05-03-PLAN.md — 最终目录结构验证和测试 (OUT-01, OUT-02, OUT-03, OUT-04) #### Phase 6: 代码整合 -**Goal**: 将独立的元数据技能和 Pipeline 模块整合进 kb-workflow +**Goal**: 将独立的元数据技能和 Pipeline 模块整合进 kb-workflow，消除 sys.path 操作，建立标准 Python 包结构 **Depends on**: Phase 5 **Requirements**: MET-01, MET-02, MET-03, MET-04, MET-05, PIP-01, PIP-02, PIP-03, PIP-04 **Success Criteria** (what must be TRUE): @@ -76,11 +76,14 @@ Plans: 2. kb_pipeline/ 代码合并入 kb-workflow/ 保持 processors/, platforms/, schemas.py 结构 3. 所有导入路径更新指向新位置，CLI 正常工作 4. 原独立的 kb-bilibili-metadata、kb-zhihu-metadata、kb_pipeline 目录已删除 -**Plans**: 2 plans + 5. 所有 sys.path 动态操作已删除或重构 + 6. Pipeline 类可从 kb_workflow.pipeline 包级别导入 +**Plans**: 3 plans Plans: -- [ ] 06-01-PLAN.md — 元数据技能整合 (MET-01, MET-02, MET-03, MET-04, MET-05) -- [ ] 06-02-PLAN.md — Pipeline 模块整合 (PIP-01, PIP-02, PIP-03, PIP-04) +- [x] 06-01-PLAN.md — 元数据技能整合 (MET-01, MET-02, MET-03, MET-04, MET-05) +- [x] 06-02-PLAN.md — Pipeline 模块整合 (PIP-01, PIP-02, PIP-03, PIP-04) +- [ ] 06-03-PLAN.md — Gap Closure: 消除 sys.path 操作和补充 Pipeline 导出 (MET-05, PIP-04) ## Progress @@ -94,4 +97,4 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 | 3. Processors | v1.0 | 3/3 | Complete | 2026-03-15 | | 4. Pipeline | v1.0 | 2/2 | Complete | 2026-03-15 | | 5. 归档与目录优化 | v1.1 | 3/3 | Complete | 2026-03-16 | -| 6. 代码整合 | v1.1 | 0/2 | Not started | - | +| 6. 代码整合 | v1.1 | 2/3 | In Progress | - | diff --git a/.planning/phases/06-code-consolidation/06-03-PLAN.md b/.planning/phases/06-code-consolidation/06-03-PLAN.md new file mode 100644 index 0000000..4e8b654 --- /dev/null +++ b/.planning/phases/06-code-consolidation/06-03-PLAN.md @@ -0,0 +1,328 @@ +--- +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" +--- + + +消除代码库中遗留的 sys.path 动态操作，完善 Pipeline 类的包级别导出。 + +Purpose: 完成 Phase 6 的目标 —— 建立干净的 Python 包结构，无动态路径操作 +Output: 5 个文件被修改，所有 sys.path 操作被删除，Pipeline 可从包级别导入 + + + +@/home/starmen1265/.claude/get-shit-done/workflows/execute-plan.md +@/home/starmen1265/.claude/get-shit-done/templates/summary.md + + + +@.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__` 中导出 + + + + + + + Task 1: 删除 kb_workflow.py 中的 sys.path 操作 + kb_workflow/kb_workflow.py + + 删除第 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 包"。 + + + grep -n "sys.path" kb_workflow/kb_workflow.py; test $? -eq 1 + + kb_workflow.py 中无 sys.path 相关代码，CLI 仍可正常执行 --help + + + + Task 2: 删除 zhihu_extractor.py 中的 sys.path 操作 + kb_workflow/metadata/zhihu_extractor.py + + 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 包，相对导入可以正常工作。 + + + grep -n "sys.path" kb_workflow/metadata/zhihu_extractor.py; test $? -eq 1 + + zhihu_extractor.py 中无 sys.path 相关代码，模块可正常导入 + + + + Task 3: 删除 zhihu_metadata.py 中的 sys.path 操作 + kb_workflow/metadata/zhihu_metadata.py + + 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 包，相对导入可以正常工作。 + + + grep -n "sys.path" kb_workflow/metadata/zhihu_metadata.py; test $? -eq 1 + + zhihu_metadata.py 中无 sys.path 相关代码，CLI 可正常执行 + + + + Task 4: 处理 analyze.py 中的 sys.path 操作 + kb_workflow/pipeline/processors/analyze.py + + 这处 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 内部更干净。 + + + grep -n "sys.path" kb_workflow/pipeline/processors/analyze.py | grep -v "_run_analysis" | wc -l | xargs test 0 -eq + + analyze.py 的 sys.path 操作移到 lazy import 内部，顶层无 sys.path 操作 + + + + Task 5: 在 pipeline/__init__.py 中导出 Pipeline 类 + kb_workflow/pipeline/__init__.py + + 在 kb_workflow/pipeline/__init__.py 中添加 Pipeline 类的导入和导出： + + 1. 在导入区域（第 28 行之后）添加： + ```python + from kb_workflow.pipeline.pipeline import Pipeline + ``` + + 2. 在 `__all__` 列表中（第 30 行之后）添加： + ```python + "Pipeline", + ``` + + 最终 `__all__` 应该包含 "Pipeline" 字符串。 + + 注意：确保 Pipeline 类在其他导入之后添加，避免循环导入问题。 + + + python -c "from kb_workflow.pipeline import Pipeline; print('Pipeline import OK')" + + Pipeline 类可从 kb_workflow.pipeline 包级别导入 + + + + Task 6: 验证所有更改 + 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 + + 运行全面验证： + + 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 + ``` + + + 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')" + + 所有导入正常，CLI 可执行，无新增测试失败 + + + + + +## 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 +``` + + + +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. 所有现有功能正常工作，无新增测试失败 + + + +After completion, create `.planning/phases/06-code-consolidation/06-03-SUMMARY.md` +