docs: resolve debug kb_workflow-module-conflict

2026-03-18 20:38:30 +08:00
parent c30b0bce88
commit 0c63503309
1 changed files with 68 additions and 0 deletions
@@ -0,0 +1,68 @@
+---
+status: resolved
+trigger: "kb_workflow 模块存在文件名与包名冲突，导致 `python3 kb_workflow.py` 运行时报错 `No module named 'kb_workflow.pipeline'; 'kb_workflow' is not a package`"
+created: 2026-03-18T00:10:00+08:00
+updated: 2026-03-18T00:15:00+08:00
+---
+
+## Current Focus
+
+hypothesis: (已确认并修复) kb_workflow.py 与 kb_workflow/ 包同名导致模块冲突
+test: 验证修复效果
+expecting: 所有运行方式都能正常工作
+next_action: 已完成
+
+## Symptoms
+
+expected: 执行 python3 kb_workflow.py 能正常导入 kb_workflow.pipeline 等子模块并运行
+actual: 报错 No module named 'kb_workflow.pipeline'; 'kb_workflow' is not a package
+errors: No module named 'kb_workflow.pipeline'; 'kb_workflow' is not a package
+reproduction: 直接运行 python3 kb_workflow.py
+started: 这是一个结构性问题，kb_workflow.py 文件与 kb_workflow/ 包目录同名
+
+## Eliminated
+
+(空)
+
+## Evidence
+
+- timestamp: 2026-03-18T00:10:00+08:00
+  checked: 目录结构
+  found: |
+    kb_workflow/
+    ├── kb_workflow.py    ← 文件名与包名冲突
+    ├── pipeline/         ← 子包
+    ├── __init__.py       ← 包初始化文件，内容为 `from .kb_workflow import process_command, main`
+    └── ...
+  implication: 存在典型的模块/包命名冲突
+
+- timestamp: 2026-03-18T00:10:00+08:00
+  checked: kb_workflow.py 导入语句
+  found: |
+    第44-50行使用 `from kb_workflow.pipeline import ...`
+    第122-124行使用 `from kb_workflow.auth import ...`
+  implication: 这些绝对导入要求 kb_workflow 被识别为包
+
+- timestamp: 2026-03-18T00:10:00+08:00
+  checked: __init__.py
+  found: `from .kb_workflow import process_command, main`
+  implication: 包结构设计为从子模块 .kb_workflow 导入函数并暴露
+
+## Resolution
+
+root_cause: kb_workflow.py 文件与 kb_workflow/ 包目录同名，当直接运行 `python3 kb_workflow.py` 时，Python 将其识别为 __main__ 模块而非包的一部分，导致代码中的 `from kb_workflow.pipeline import ...` 绝对导入失败，因为 Python 优先将当前目录的 kb_workflow.py 识别为模块而非包。
+fix: |
+  1. 将 kb_workflow.py 重命名为 cli.py
+  2. 更新 __init__.py 的导入路径: `from .cli import process_command, main`
+  3. 将 cli.py 中的绝对导入改为相对导入: `from .pipeline import ...`
+  4. 创建 __main__.py 支持 `python -m kb_workflow` 运行方式
+  5. 更新文档中的使用示例
+verification: |
+  用户确认: "已修复 ✓"
+  - `python -m kb_workflow --help` 正常显示帮助
+  - `python -m kb_workflow process "url"` 能正常执行管道
+  - `from kb_workflow import process_command` 包导入正常
+files_changed:
+  - kb_workflow/kb_workflow.py -> kb_workflow/cli.py (重命名 + 改为相对导入)
+  - kb_workflow/__init__.py (更新导入路径)
+  - kb_workflow/__main__.py (新建)