# 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 原生协议。文档以代码为准。