# 02 知识点地图

每个知识点都绑到源码。学的时候合上文档，能用自己的话讲出来，才算过关。

## A. Agent 核心（必须牢固）

### A1. ReAct

- 概念：Thought → Action → Observation 循环，直到模型不再调工具
- 源码：`qoze_code_agent.py` 的 `llm_call` / `tool_node` / `should_continue`
- 过关标准：不看代码画出状态图；能解释“为什么 tool 之后必须再进 llm_call”

### A2. LangGraph StateGraph

- 概念：节点函数返回要**更新**的 state 字段，不是替换整个对象
- `messages: Annotated[list, operator.add]` 表示每次 append
- `compile(checkpointer=...)` 让同一 `thread_id` 能恢复对话
- 源码：`MessagesState`、`agent_builder`、`init_agent()`
- 过关标准：自己用 30 行写出同等的两节点图

### A3. Tool Calling（Function Calling）

- 概念：模型不直接“执行 Python”，它只输出 `tool_calls` JSON；运行时按名字找到函数再跑
- LangChain：`@tool` 从类型注解和 docstring 生成 schema；`llm.bind_tools(tools)`
- 源码：`tools/*.py` 的 `@tool`；`tool_node` 里 `tools_by_name[name].ainvoke(args)`
- 过关标准：自己写一个 `read_file` 工具，让模型真的读到磁盘内容

### A4. 消息协议

必须分清四种消息，否则 400 错误会搞很久：

| 类型 | 谁产生 | 作用 |
|------|--------|------|
| SystemMessage | 你 | 角色与规则 |
| HumanMessage | 用户 | 任务 |
| AIMessage | 模型 | 回复或 tool_calls |
| ToolMessage | 你的运行时 | 把工具结果交回，必须带 `tool_call_id` |

源码：`_repair_incomplete_tool_calls`

### A5. Prompt Caching 拆分

- 静态放 System，动态放 User 前缀
- 源码：`utils/system_prompt.py` 的 `get_static_system_prompt` / `get_dynamic_context`
- 过关标准：能说出“目录树为什么不能放进 SystemMessage”

## B. 模型接入（结合你现在的环境）

### B1. OpenAI 兼容协议

- `base_url` + `api_key` + `model` 三件套
- 你已经在用 `https://api.agicto.cn/v1` + DeepSeek
- 源码：`model_initializer.py` 的 `ChatOpenAI(...)`
- 过关标准：10 行脚本能 `ainvoke` 通；再 `bind_tools` 通

### B2. 推理模型的 thinking

- DeepSeek 一类会在 delta 里带 `reasoning_content`
- 源码：`model_initializer.patch_langchain_openai`
- TUI：`ThinkingWidget`
- 过关标准：知道 thinking 不是最终答案，不要当 assistant content 存

### B3. 多厂商适配

- 这是 Qoze 变复杂的主因：Vertex、Kimi、智谱、Qwen 各写一套
- 改写建议：第一版只保留 **OpenAI 兼容** 一个适配器

## C. 工具与安全

### C1. 文件工具

- 源码：`tools/file_tools.py`
- 要点：路径限制在 cwd；读文件带行号范围；改文件用精确替换而不是整文件覆盖
- 过关标准：能讲清为什么 `write_file` 危险、`replace_in_file` 更稳

### C2. Shell 工具

- 源码：`tools/execute_command_tool.py`
- 要点：`create_subprocess_shell`、超时、stdout/stderr 合并
- 风险：模型可以 `rm -rf` / 删盘；改写时要加**白名单或人工确认**

### C3. 并行 tool_calls

- 一轮里模型可能同时调多个工具
- 源码：`asyncio.gather` in `tool_node`
- 过关标准：知道“读两个文件可以并行，写同一文件不能瞎并行”

## D. 工程结构（决定你改写时像不像业余）

### D1. 配置与密钥

- 源码：`config_manager.py`，Windows 在 `%APPDATA%\qoze\qoze.conf`
- 原则：密钥不进仓库

### D2. Checkpoint / 会话

- SQLite + `thread_id`
- `/clear` 会换新 uuid 并清库
- 源码：`init_agent` / `save_thread_id` / `qoze_tui.py` 的 `clear`

### D3. 规则注入

- `.qoze/rules/*.md` 每次动态塞进 prompt
- 这就是 Cursor 的 `.cursor/rules` 同类机制，非常值得学

## E. 插件三件套（理解即可，MVP 不做）

### E1. Skills

- 发现路径：项目 `.qoze/skills` > 用户 `~/.qoze/skills` > 内置
- 激活后把 SKILL.md 正文注入动态上下文
- 源码：`skills/skill_manager.py`

### E2. MCP

- 配置里写 `command + args`，stdio 拉起外部 server
- 激活后 `get_active_tools()` 合并进 `tools_by_name`
- 源码：`qoze_mcp/mcp_manager.py`、`tools/mcp_tools.py`

### E3. Subagent

- 再 compile 一张无 checkpointer 的图
- 工具子集，禁止再 dispatch，避免套娃
- 源码：`tools/subagent_tool.py` 的 `_build_subagent`

## F. TUI（体验层，可后置）

| 概念 | 源码 | 你要懂什么 |
|------|------|------------|
| Textual App | `qoze_tui.py` 的 `class Qoze(App)` | compose / 事件 / 异步任务 |
| 流式增量 | `display_buffer.py` + `stream_scheduler.py` | 不要每个 token 都 refresh |
| 思考区 | `thinking_widget.py` | 和正文拆开 |
| 终端兼容 | `terminal_compat.py` | Windows GBK / 旧终端会炸 Unicode |

Windows 坑你已经踩过：Rich 默认 legacy_windows 会 GBK 编码失败。自己项目一开始就 `PYTHONUTF8=1`，TUI 用 Windows Terminal。

## G. 建议的练习题（每题半天到一天）

1. 不用 LangGraph，手写一个 while 循环 ReAct（messages 列表自己维护）
2. 用 LangGraph 把上面的循环换成两节点图
3. 给图加上 `read_file` + `execute_command`，完成“读 README 并总结”
4. 给图加上 SQLite checkpointer，重启进程还能续聊
5. 把 `astream` 的 token 打到终端（先 print，再考虑 Textual）
6. 实现一个 skill：激活后模型会按你的 Java 代码规范改代码
7. 实现一个危险命令拦截：`execute_command` 前打印 diff/命令并等 y/N