|
|
# 02 架构与目录
|
|
|
|
|
|
源码落地：`D:\ideaProject\gcode`（本次只定结构，不建库）。
|
|
|
|
|
|
## 分层
|
|
|
|
|
|
```text
|
|
|
┌─────────────────────────────────────────────┐
|
|
|
│ ui/detect + tui / repl │
|
|
|
│ 探测终端、画界面、收集确认（y/N、diff） │
|
|
|
├─────────────────────────────────────────────┤
|
|
|
│ graph + session + prompt │
|
|
|
│ ReAct、checkpoint、静态/动态提示词 │
|
|
|
├─────────────────────────────────────────────┤
|
|
|
│ models（注册表 + openai_compatible） │
|
|
|
├─────────────────────────────────────────────┤
|
|
|
│ tools + safety + mcp │
|
|
|
│ 文件/命令沙箱、HITL、Playwright MCP │
|
|
|
└─────────────────────────────────────────────┘
|
|
|
```
|
|
|
|
|
|
依赖只能从上到下。工具不得 `import` 图模块去改全局 `llm` / `agent`。TUI 与 REPL 都只消费 `graph.astream(...)`。
|
|
|
|
|
|
```mermaid
|
|
|
flowchart LR
|
|
|
detect[终端探测] -->|WT 等| tui[自研TUI]
|
|
|
detect -->|conhost| repl[REPL回退]
|
|
|
tui --> graph[LangGraph ReAct]
|
|
|
repl --> graph
|
|
|
graph --> llmCall[llm_call]
|
|
|
llmCall -->|tool_calls| toolNode[tool_node]
|
|
|
toolNode --> safety[HITL]
|
|
|
safety --> llmCall
|
|
|
llmCall -->|纯文本| uiOut[TUI或REPL渲染]
|
|
|
```
|
|
|
|
|
|
## 目录骨架
|
|
|
|
|
|
```text
|
|
|
D:\ideaProject\gcode\
|
|
|
pyproject.toml
|
|
|
README.md
|
|
|
src/gcode/
|
|
|
__init__.py
|
|
|
cli.py # 入口：解析参数、探测、选 UI
|
|
|
config.py # 单一 home：%APPDATA%\gcode 与 <cwd>/.gcode
|
|
|
windows.py # 代码页、默认 PowerShell、Job Object / taskkill
|
|
|
prompt.py
|
|
|
graph.py # StateGraph：llm_call / tool_node
|
|
|
session.py # sqlite checkpointer + thread_id
|
|
|
safety.py # 写文件 diff、shell 确认；回调由 UI 注入
|
|
|
ui/
|
|
|
detect.py
|
|
|
repl.py
|
|
|
tui/ # 自研 Textual，不拷 Qoze CSS/logo
|
|
|
models/
|
|
|
registry.py # 读 models.yaml
|
|
|
openai_compatible.py
|
|
|
tools/
|
|
|
fs.py
|
|
|
shell.py
|
|
|
mcp/
|
|
|
client.py # 薄客户端，默认只起 @playwright/mcp
|
|
|
tests/
|
|
|
test_path_sandbox.py
|
|
|
test_graph_smoke.py
|
|
|
test_detect_terminal.py
|
|
|
```
|
|
|
|
|
|
项目级数据：`<cwd>/.gcode/`（checkpoints、rules、debug log）。
|
|
|
用户级：`%APPDATA%\gcode\`（`models.yaml`、mcp 配置、token 统计）。禁止再混用 `~\.gcode` 与 `%APPDATA%` 两套根。
|
|
|
|
|
|
## Prompt 怎么写
|
|
|
|
|
|
不要一上来写 400 行。对照 Qoze 的 [system_prompt.py](D:\ideaProject\QozeCode-main\utils\system_prompt.py) 学 **静态/动态拆分**，不要整段粘贴。G-CODE 工具清单不同，抄过来模型会去调不存在的 `dispatch_subagent`。
|
|
|
|
|
|
每次加一段之前问：
|
|
|
|
|
|
1. 模型此刻有哪些工具？没实现的一句不写
|
|
|
2. 最容易做错的 3 件事？只为这些写硬规则
|
|
|
3. 静态还是动态？每次一样 → System；会变（cwd、git、rules）→ 动态段
|
|
|
4. 能用代码拦住的不要只靠文字（路径沙箱在 `read_file` 里拒绝）
|
|
|
5. 用失败任务加规则，不用想象加规则
|
|
|
|
|
|
静态段先控制在 80～150 行：身份、工具怎么选、5～8 条硬规则、ReAct 与「连续 3 次无进展就问人」、中文推理、TUI 内避免 emoji。
|
|
|
|
|
|
动态段保持短：cwd、目录树摘要、git 摘要、`.gcode/rules`。
|
|
|
|
|
|
## 多模型
|
|
|
|
|
|
不复制 Qoze 的枚举树。`models.yaml` 示例：
|
|
|
|
|
|
```yaml
|
|
|
providers:
|
|
|
deepseek:
|
|
|
api: openai_compatible
|
|
|
base_url: https://api.deepseek.com/v1
|
|
|
api_key_env: DEEPSEEK_API_KEY
|
|
|
models:
|
|
|
- id: deepseek-v4-flash
|
|
|
vision: false
|
|
|
reasoning: false
|
|
|
- id: deepseek-v4-pro
|
|
|
vision: false
|
|
|
reasoning: true
|
|
|
agicto:
|
|
|
api: openai_compatible
|
|
|
base_url: https://api.agicto.cn/v1
|
|
|
api_key_env: GCODE_API_KEY
|
|
|
models:
|
|
|
- id: deepseek-v4-flash
|
|
|
vision: false
|
|
|
reasoning: false
|
|
|
```
|
|
|
|
|
|
一期只实现 `openai_compatible`。加一家模型改 yaml，不改 Python。`reasoning_content` 尽量显式解析，避免猴子补丁 LangChain。Vertex / Anthropic / Bedrock 有账号再加 adapter。
|
|
|
|
|
|
启动：`gcode --model deepseek-v4-flash` 或 TUI 内选择。
|
|
|
|
|
|
## 人在回路
|
|
|
|
|
|
`safety.py` 定义确认点，UI 注入回调（TUI 用对话框，REPL 用 y/N）：
|
|
|
|
|
|
| 动作 | 展示 | 拒绝时 |
|
|
|
|------|------|--------|
|
|
|
| 写文件 / 替换 | unified diff | ToolMessage：「用户拒绝本次写入」 |
|
|
|
| `execute_command` | 完整命令 + 工作目录 | ToolMessage：「用户拒绝执行该命令」 |
|
|
|
|
|
|
读文件、列目录、只读 git 不必确认。安装依赖、构建、测试、`git commit` / `push` 必须走确认（prompt 硬规则 + HITL 双保险）。
|
|
|
|
|
|
## 工具
|
|
|
|
|
|
一期内置：
|
|
|
|
|
|
- `read_file` / `list_dir` / `replace_in_file`：仅 cwd 或用户级 gcode 目录；拒绝 `..`
|
|
|
- `execute_command`：默认 PowerShell；输出 UTF-8 失败则 GBK；超时用 Job Object 或 `taskkill /T`，不要只 `terminate()` 留孤儿
|
|
|
|
|
|
浏览器不进 `tools/` 进程内实现，见下一节。
|
|
|
|
|
|
## Playwright MCP（仅途径 A）
|
|
|
|
|
|
官方：`npx -y @playwright/mcp@latest`。
|
|
|
|
|
|
G-CODE 薄 MCP 客户端：stdio 拉起 → 把 tools 动态交给 `bind_tools`。MCP 只当 Playwright 插座，一期不接 GitHub / Postgres。不复活 Qoze 已注释的 `browser_tool.py`，不默认 `chrome-devtools-mcp`（那是 `--remote-debugging-port=9222` 附着已开 Chrome）。
|
|
|
|
|
|
硬依赖 Node.js / npx。检测不到则 TUI/REPL 提示「浏览器工具不可用，请安装 Node.js」，没有 Python Playwright 备选。
|
|
|
|
|
|
## 相对 Qoze 必须避开的结构
|
|
|
|
|
|
- 模块级全局 `llm`、`agent`、`tools_by_name` 被 MCP/TUI 到处改
|
|
|
- `mcp_tools` / `subagent_tool` 反向 import `qoze_code_agent`
|
|
|
- `qoze_tui.py` 里命令路由、拼消息、token、流式全混在一个 App 类
|
|
|
- 配置路径分裂：`%APPDATA%\qoze` vs `~\.qoze`
|
|
|
- shell 一律按 UTF-8 解码（cmd 的 `dir` 常为 GBK）
|
