# 03 分期实施与优化清单

源码：`D:\ideaProject\gcode`（阶段 1 再 `git init`）。  
原则：每一阶段有过关标准；没过不要开下一阶段。不要边读 Qoze 边整文件复制。

---

## 阶段 0｜对照方案精读（0.5～1 天）

精读 Qoze 时带着本方案，不写 G-CODE 业务代码。

过关：能口述 ReAct 节点顺序、方案 C 在 cmd 下会怎样、HITL 拒绝后图为什么不会崩。

---

## 阶段 1｜心脏（图 + 四件套 + HITL）

只做 REPL，先保证能打中文、能改文件。

- `graph.py`：`START → llm_call ⇄ tool_node → END`
- `tools/fs.py` + `tools/shell.py` + `safety.py`（回调先做成终端 y/N）
- `session.py`：sqlite + `thread_id`
- `prompt.py`：短静态 + cwd/树
- `models/`：先能跑通一家 OpenAI 兼容（例如 Agicto / DeepSeek）
- `windows.py`：UTF-8→GBK 解码；超时杀进程树

过关：

- 在任意项目目录启动，完成「读 README → 改一处 → 跑命令看结果」
- 路径逃出 cwd 被拒绝（有测试）
- mock LLM 的图测试：一次 tool_call 再纯文本，能 END
- 写入和 shell 输入 `n` 会取消，模型能收到拒绝原因
- 重启进程同一 session 能接着聊

---

## 阶段 2｜主界面（TUI + 方案 C）

- `ui/detect.py` + `ui/tui/` + `ui/repl.py`
- TUI：消息列表、思考流、工具卡片、输入框（自己的样式）
- conhost：拒绝 TUI、引导 WT、回退 REPL
- `--ui tui` / `--ui repl`；Kitty 协议在 TUI 路径关闭
- `/edit`、`/clear`、`/help`、`/quit`

过关：见 [01-Windows中文输入方案.md](./01-Windows中文输入方案.md) 验收表。  
核心图仍可在无 Textual 时单测。

---

## 阶段 3｜多模型注册表

把阶段 1 的「写死一家」换成 `models.yaml`。TUI 可选模型。加一家 = 改配置。  
`reasoning` 模型要把思考内容接到思考区，尽量不打 LangChain 猴子补丁。

过关：至少两家兼容端点（例如 DeepSeek 官方 + Agicto）能切换完成同一任务。

---

## 阶段 4｜Playwright MCP

薄 `mcp/client.py`，默认只配置 `@playwright/mcp`。无 Node 时提示不可用。  
prompt 静态段此时才写「如何使用浏览器工具」，之前禁止出现。

过关：WT 下让 Agent 打开一个本地或公开页、取快照或截图、把结果写进对话。公司内网站点注意别把 Cookie 打进日志。

---

## 阶段 5｜按需增强（每次只加一个）

从下面挑，不要一次全上：

- `.gcode/rules/` 项目规则
- git 状态注入动态上下文
- `/compact` 对话摘要截断
- Java / Maven 专用工具（`pom` 模块、失败日志截断）
- 公司 GitLab / Jenkins **只读** 查询（写操作必须再走 HITL）

仍默认不做：Skills、Subagent、Plan 模式、语音、Island、其它 MCP 市场。

---

## 相对 Qoze 的优化清单

### 一期就该比它好

| 问题（Qoze） | G-CODE |
|--------------|--------|
| cmd 中文 IME 失败，只推荐 WT | 方案 C，启动探测 + 回退 |
| `execute_command` 强制 UTF-8 | UTF-8 失败再 GBK；默认 PowerShell |
| 无 HITL，`ask_for_user` 已注释 | 写文件 diff + 命令确认 |
| `%APPDATA%\qoze` 与 `~\.qoze` 分裂 | 单一 `get_home_dir()` |
| Windows 超时只 `terminate()` | Job Object 或 `taskkill /T` |
| README 宣传 `/plan`、内置 Playwright，代码没有 | 文档以代码为准 |
| TUI 绑死核心、全局单例、工具反向 import | 分层；UI 只消费 stream |

### 刻意不搬

Island、语音、飞书 dead code、1300 行注释浏览器、十家厂商 if-else、Subagent、Skills。

### 二期再看

上下文压缩、规则文件、git 注入、Java/CI 工具箱。

---

## 明确不要做的事

- 不要把 Qoze 的 CSS、ASCII logo、长 prompt 整段拷进 G-CODE
- 不要在没沙箱的情况下开放 `execute_command`
- 不要把 API Key 写进仓库
- 不要在 cmd 里硬开 TUI 充「功能完整」
- 不要宣传未实现的 Plan / 语音 / Subagent

## 阶段 1 完成定义

当下面全是「是」，才进入阶段 2：

- [ ] `D:\ideaProject\gcode` 能独立 `pip install -e .` 跑起来
- [ ] 四件套工具 + HITL + 会话恢复
- [ ] 路径沙箱与图的 mock 测试存在
- [ ] README 是自己写的架构说明
- [ ] 不看代码能画出数据流