---
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 (新建)