# 03 学习与改写计划

总原则：**先能讲清楚，再能写出来，最后才加功能。**  
不要边读边把整个 Qoze 复制到新仓库。

建议节奏：每天 1～2 小时，大约 8～10 周。可以按周压缩，但不要跳过“过关标准”。

---

## 阶段 0｜建立实验场（0.5 天）

- 继续用现有环境跑 Qoze：`deepseek-v4-flash`
- 自己下 5 个任务观察行为，并记笔记：
  1. “当前目录有哪些 py 文件”
  2. “读 README 前 80 行并总结”
  3. “用 grep 找 init_agent 在哪”
  4. “把某某函数加一行注释”（看它怎么改文件）
  5. “执行 `python --version`”
- 每次记下：调了哪些工具、调了几轮、哪一步走歪了

产出：本目录下自建 `笔记/观察日志.md`（自己写，不要求一次完美）

过关：能口述一轮对话的节点顺序

---

## 阶段 1｜精读心脏（第 1～2 周）

精读顺序（严格按此，不要先扎进 TUI）：

1. `enums.py` + `config_manager.py` + `model_initializer.py`（知道模型怎么来的）
2. `qoze_code_agent.py` 全文，重点 `MessagesState` 到 `init_agent`
3. `utils/system_prompt.py`
4. `tools/file_tools.py` + `tools/execute_command_tool.py`
5. `qoze_tui.py` 的 `process_user_input`（只看命令分发和 astream 入口）

配套练习：完成知识点地图里的练习 1～4。

过关标准：

- 画出主图 mermaid，不看文档
- 解释 `operator.add`、`thread_id`、缺失 ToolMessage 各是什么问题
- 能指出 README 里有哪些功能这份代码其实没有

---

## 阶段 2｜精读外壳（第 3 周）

1. `tui_components/messages/stream_handler.py`
2. `thinking_widget.py` / `tool_status_panel.py`
3. `skills/skill_manager.py` + `tools/skill_tools.py`
4. `qoze_mcp/` + `tools/mcp_tools.py`
5. `tools/subagent_tool.py` 的 `_build_subagent`

过关标准：用三句话区分 Skill / MCP / Subagent  
此阶段**仍不开始大改自己的项目结构**，只做小实验。

---

## 阶段 3｜最小复刻（第 4～6 周）★ 真正开始“自己的项目”

新仓库建议路径（示例）：`D:\myProgram\Learning\ai-coding改写\my-agent`  
新名字自己定，不要叫 Qoze。

只做这些：

```text
用户 CLI 输入
  → OpenAI 兼容 LLM（你的 Agicto + DeepSeek）
  → LangGraph ReAct
  → 工具：read_file / replace_in_file / list_dir / execute_command（带确认）
  → 终端打印思考摘要 + 工具日志 + 最终回答
  → SQLite 保存会话
```

详细文件清单见 `04-最小复刻清单.md`。

验收：

- 在任意代码目录启动，能完成“读文件 → 改一处 → 跑命令看结果”
- 重启进程，同一 session 还能接着聊
- 危险命令会停下来问你
- 你能 15 分钟给别人讲完架构

---

## 阶段 4｜补齐体验（第 7～8 周）

按需加，**加一个就停下来用一周**：

1. 流式输出（先 Rich Live，再考虑 Textual）
2. `/clear` `/help` 斜杠命令
3. `.myagent/rules/` 规则注入
4. 一个 Skill（例如 `java-style`）
5. git status 进动态上下文

不要同时开工 MCP 和 Subagent。

---

## 阶段 5｜差异化（第 9 周以后）

只从 `05-差异化增强方向.md` 里挑 **1 个主特色 + 1 个小增强**。

结合你的日常，优先候选：

- 主特色：公司 GitLab / Jenkins 只读查询工具（列 MR、看构建状态）
- 小增强：Windows 终端编码和 Java/Maven 项目分析

做完主特色再考虑 Subagent、MCP 浏览器。

---

## 每周固定动作

| 星期 | 做什么 |
|------|--------|
| 前 4 天 | 精读或写代码，每天结束写 10 行笔记 |
| 第 5 天 | 给自己做一次“口述架构”或给 Agent 下真实任务 |
| 周末 | 对照过关标准打勾；没过的下周重复，不硬开下一阶段 |

## 明确不要做的事

- 不要一上来复刻整个 TUI
- 不要把 10 家模型供应商抄进自己项目
- 不要在没路径沙箱的情况下开放 `execute_command`
- 不要把 API Key 写进新仓库
- 不要一边复制 Qoze 文件一边改名，那叫换皮，学不到东西

## 和源码许可证

QozeCode 是 Apache 2.0。若大量复制原文件，需要保留版权头和 NOTICE。  
推荐路径：看懂后**自己重写**同构实现，只借鉴状态图和分层，不复制 UI 文案与品牌。