# 01 架构与调用链

对照源码：`D:\ideaProject\QozeCode-main`

## 1. 它到底是什么

QozeCode 是一个**命令行里的 Coding Agent**。用户在终端打字，模型按 ReAct 循环自己决定要不要读文件、跑命令、搜网页；过程实时画在 Textual TUI 上。

它不是 IDE 插件，也不是 Web 对话页。核心就三件事：

- 把“对话状态”交给 LangGraph 管
- 把“动手能力”做成 LangChain Tool
- 把“思考 / 工具 / 回复”流式渲染到终端

## 2. 分层（从外到内）

```text
┌─────────────────────────────────────────────────────────┐
│  启动层  launcher.py + qoze_tui.py:main()               │
│  选模型、读配置、拉起 Textual App                        │
├─────────────────────────────────────────────────────────┤
│  交互层  qoze_tui.py + tui_components/                  │
│  斜杠命令、流式渲染、思考区、工具状态条                   │
├─────────────────────────────────────────────────────────┤
│  决策层  qoze_code_agent.py                             │
│  LangGraph: llm_call ⇄ tool_node                        │
├─────────────────────────────────────────────────────────┤
│  模型层  model_initializer.py + config_manager.py       │
│  ChatOpenAI 等，兼容 OpenAI 协议的自定义 base_url        │
├─────────────────────────────────────────────────────────┤
│  能力层                                                  │
│  tools/ 文件、命令、搜索                                  │
│  skills/ 专家知识注入 prompt                             │
│  qoze_mcp/ 外部 MCP 工具热加载                           │
│  tools/subagent_tool.py 子图并行                         │
└─────────────────────────────────────────────────────────┘
```

## 3. 目录对照（只记主干）

| 路径 | 职责 | 改写时优先级 |
|------|------|----------------|
| `qoze_tui.py` | Textual App，用户输入入口 | 第二阶段再写，MVP 可用纯 CLI |
| `launcher.py` | 启动选模型 | 可做成 `--model` 参数 |
| `qoze_code_agent.py` | **心脏**：State、图、checkpoint | 第一阶段必须吃透并重写 |
| `model_initializer.py` | 按厂商创建 LLM | 先只留 DeepSeek / OpenAI 兼容 |
| `config_manager.py` | 读 ini 配置和密钥 | 先 YAML/ENV 即可 |
| `enums.py` | Provider / ModelType | 自己项目用简单字符串就行 |
| `utils/system_prompt.py` | 静态 prompt + 动态上下文 | 必须理解，缓存设计值得学 |
| `tools/` | 所有 Function Calling 工具 | 先 4 个：读文件、改文件、跑命令、列目录 |
| `tools/subagent_tool.py` | 迷你版主图 | 第三阶段 |
| `skills/` | SKILL.md 发现与激活 | 第三阶段 |
| `qoze_mcp/` | MCP 配置、激活、工具注入 | 第三阶段 |
| `tui_components/` | 气泡、流式、thinking widget | 第二阶段 |
| `utils/git_context.py` | 把 git status/diff 塞进 prompt | 增强阶段很有用 |

## 4. 启动调用链

```text
qoze / python qoze_tui.py
        │
        ├─ launcher.ensure_config()     没有配置就写模板
        ├─ get_model_choice()           交互选模型（可用 --model 跳过）
        └─ Qoze(provider, model_type).run()
                │
                ├─ initialize_llm()     得到 ChatOpenAI 实例
                ├─ llm.bind_tools(tools)
                ├─ init_agent()         SQLite checkpointer 编译 StateGraph
                └─ 用户回车
                        └─ process_user_input()
```

TUI 里以 `/` 开头的是**本地命令**，不进图：`/clear`、`/skills`、`/mcp`、`/quit`、`/checkpoint`。  
普通自然语言才 `agent.astream(...)`。

## 5. 一轮对话怎么走完（必须能默画）

主图在 `qoze_code_agent.py`：

```text
START
  │
  ▼
llm_call
  │  拼 SystemMessage(静态 prompt)
  │  + 动态上下文（目录树、git、规则、技能）
  │  + 历史 messages
  │  → await llm_with_tools.ainvoke(...)
  │
  ├─ 有 tool_calls ──► tool_node ──► 再回到 llm_call
  │                      │
  │                      └─ 多个 tool_call 用 asyncio.gather 并行
  │
  └─ 没有 tool_calls ──► END
```

对应代码：

- 状态：`MessagesState`（`messages` 用 `operator.add` 追加）
- 节点：`llm_call`、`tool_node`
- 边：`should_continue` / `should_continue_from_tool`
- 持久化：`AsyncSqliteSaver`，库在当前项目 `.qoze/data/checkpoints.db`

这就是 ReAct：**Reason（llm_call）→ Act（tool_node）→ Observe（ToolMessage 写回）→ 再 Reason**。

## 6. Prompt 怎么拼（这是质量关键）

`llm_call` 每次都会重算上下文，但拆成两段：

| 段 | 放哪 | 内容 | 为什么 |
|----|------|------|--------|
| 静态 | `SystemMessage` | 角色、工具用法、行为规范 | 方便 Prompt Caching |
| 动态 | 第一条 `HumanMessage` 前面 | 系统信息、工作目录树、git、`.qoze/rules`、已激活 skill、memory | 每次会变，不能进静态段 |

还要处理两件脏活：

- 模型不支持视觉时，剥掉 `image_url`
- checkpoint 恢复后，assistant 有 `tool_calls` 但缺 `ToolMessage`，要补占位，否则 OpenAI 兼容接口会 400

## 7. 工具层真实情况（以代码为准）

当前挂在主 Agent 上的核心工具：

- `execute_command`：shell（Windows 也能跑，但没有 Linux 的进程组杀法）
- `read_file` / `list_files` / `search_in_files` / `grep_file` / `find_files` / `replace_in_file`
- `tavily_search` / `read_url`
- skill 四个：activate / list / deactivate / install guide
- MCP 四个：list / activate / deactivate / install guide
- `dispatch_subagent`
- `analyze_project` / `find_symbols` / `trace_imports`
- `transcribe_audio` / `get_current_datetime`

注意：

- `write_file` **被注释了**，写文件靠 `replace_in_file` 或 `execute_command`
- `browser_*` **整段注释**，浏览器走 MCP（`chrome-devtools`）
- README 的 `/plan` 在这份代码里**没有对应实现**，别按文档去找

路径安全：`file_tools._resolve_under_cwd` 只允许 cwd 和 `~/.qoze/`，这是改写时必须保留的约束。

## 8. 三条插件通道（先分清，再决定要不要抄）

```text
Skill     发现 SKILL.md → 用户 activate → 把文档塞进动态 prompt
MCP       读 mcp_config.json → 拉起外部进程 → 把远端 tools 注入 tools_by_name
Subagent  再建一张同样的小图，工具更少、无 checkpoint、上下文隔离
```

记忆口诀：

- Skill = **知识**（改 prompt）
- MCP = **外来工具**（改 tool 列表）
- Subagent = **再开一个大脑**（改执行拓扑）

## 9. TUI 流式

`tui_components/messages/stream_handler.py` 订阅 `agent.astream`：

- 模型 `reasoning_content` → `ThinkingWidget`
- 正文 token → `BotMessageWidget`（增量 buffer + 调度器，避免刷爆终端）
- 出现 tool_call → 工具状态面板
- ToolMessage 回来 → 标记完成/失败

自己复刻时，第一版可以不流式，等图跑完再 `print`。流式是体验，不是 Agent 正确性。

## 10. 和宣传文案不一致的地方（精读避坑）

| README 说法 | 这份源码 |
|-------------|----------|
| `/plan` 三份文档 | 未见实现 |
| Playwright 浏览器工具 | `browser_tool.py` 注释，改 MCP |
| 语音 | 有 `AudioManager` / Soniox，Windows 基本不可用 |
| 内置 skills 一堆 | 仓库 `skills/` 只有管理器，内置技能目录可能不在这份拷贝里 |

精读原则：**调用链以 `qoze_code_agent.py` + `qoze_tui.py` 为准。**