|
|
# G-CODE
|
|
|
|
|
|
Windows 上的个人 Coding Agent。你在终端里下任务，模型按 ReAct 循环读文件、改文件、跑命令；需要浏览器时走 Playwright MCP。主界面是自研 Textual TUI；经典 CMD 无法承载 TUI 中文输入时，自动回退 REPL。
|
|
|
|
|
|
## 数据流
|
|
|
|
|
|
```text
|
|
|
gcode
|
|
|
├─ 探测终端（方案 C）
|
|
|
│ WT / VS Code / Cursor → TUI
|
|
|
│ conhost / 经典 cmd → 提示用 Windows Terminal，进入 REPL
|
|
|
└─ Runtime
|
|
|
UI 收集输入（含 /edit、HITL y/N）
|
|
|
→ Agent.stream_turn / invoke_turn
|
|
|
START → llm_call ⇄ tool_node → END
|
|
|
→ 静态 System prompt + 动态 cwd/目录树
|
|
|
→ 工具：read_file / list_dir / grep / replace_in_file / execute_command
|
|
|
→ 写文件出 diff、跑命令出命令，用户确认后才执行
|
|
|
→ 会话：<cwd>/.gcode/checkpoints.db + thread_id
|
|
|
```
|
|
|
|
|
|
TUI 和 REPL 都只消费 `Agent.stream_turn` 产生的事件。工具不能反向 import 图模块。
|
|
|
|
|
|
## 安装
|
|
|
|
|
|
Python 3.10+。
|
|
|
|
|
|
```text
|
|
|
cd D:\ideaProjects\gcode
|
|
|
python -m pip install -e ".[dev]"
|
|
|
```
|
|
|
|
|
|
首次运行会在 `%APPDATA%\gcode\` 写入 `models.yaml`。把对应环境变量配好，例如：
|
|
|
|
|
|
```text
|
|
|
setx GCODE_API_KEY "你的 key"
|
|
|
setx DEEPSEEK_API_KEY "你的 key"
|
|
|
```
|
|
|
|
|
|
建议在虚拟环境中安装，避免和其它项目的 LangChain 版本互相覆盖。
|
|
|
|
|
|
密钥只放用户目录或环境变量，不要提交到 git。模板见仓库里的 `models.yaml.example`。
|
|
|
|
|
|
## 使用
|
|
|
|
|
|
若 `gcode` 不在 PATH 上，用 `python -m gcode`：
|
|
|
|
|
|
```text
|
|
|
python -m gcode --list-models
|
|
|
python -m gcode --model agicto/deepseek-v4-flash
|
|
|
python -m gcode --ui repl
|
|
|
python -m gcode --session default
|
|
|
```
|
|
|
|
|
|
- `--ui auto`（默认）：能跑 TUI 就开 TUI；conhost 拒绝 TUI 并回退 REPL
|
|
|
- `--ui tui`：在 conhost 上会非零退出，不会黑屏假死
|
|
|
- `--ui repl`：任意终端熟模式，IME 归系统
|
|
|
|
|
|
斜杠命令（不进模型）：`/help` `/edit` `/clear` `/model` `/quit`。
|
|
|
|
|
|
`/edit` 打开 `%EDITOR%` 或记事本，保存后当作本轮用户输入。
|
|
|
|
|
|
## 配置根
|
|
|
|
|
|
| 位置 | 内容 |
|
|
|
|------|------|
|
|
|
| `%APPDATA%\gcode\` | `models.yaml`、`mcp.json` |
|
|
|
| `<cwd>/.gcode/` | `checkpoints.db`、`session.json` |
|
|
|
|
|
|
不要再混用 `~\.gcode`。
|
|
|
|
|
|
加一家 OpenAI 兼容模型：只改 `models.yaml`，不改 Python。一期只实现 `openai_compatible`。
|
|
|
|
|
|
## 人在回路
|
|
|
|
|
|
| 动作 | 展示 | 拒绝时 |
|
|
|
|------|------|--------|
|
|
|
| `replace_in_file` | unified diff | 工具返回「用户拒绝本次写入」，模型改方案 |
|
|
|
| `execute_command` | 完整命令 + 工作目录 | 工具返回「用户拒绝执行该命令」 |
|
|
|
|
|
|
读文件、列目录不确认。Windows 下命令默认走 PowerShell；输出先按 UTF-8 解码，失败再 GBK。超时用 `taskkill /T` 杀进程树。
|
|
|
|
|
|
## 浏览器
|
|
|
|
|
|
只接 `@playwright/mcp`（`npx -y @playwright/mcp@latest`）。没有 Node.js / npx 时提示不可用，没有 Python Playwright 备选。启动加 `--skip-mcp` 可关掉。
|
|
|
|
|
|
## 测试
|
|
|
|
|
|
```text
|
|
|
python -m pytest
|
|
|
```
|
|
|
|
|
|
核心图不依赖 Textual，mock LLM 的冒烟测试在 `tests/test_graph_smoke.py`。
|
|
|
|
|
|
## 明确不做
|
|
|
|
|
|
Skills、Subagent、Plan 模式、语音、Island、其它 MCP 市场、Vertex / Anthropic / Bedrock 原生协议。文档以代码为准。
|
