G-Code/项目资料/02-知识点地图.md

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