G-CODE

Windows 上的个人 Coding Agent。你在终端里下任务，模型按 ReAct 循环读文件、改文件、跑命令；需要浏览器时走 Playwright MCP。主界面是自研 Textual TUI；经典 CMD 无法承载 TUI 中文输入时，自动回退 REPL。

数据流

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+。

cd D:\ideaProjects\gcode
python -m pip install -e ".[dev]"

首次运行会在 %APPDATA%\gcode\ 写入 models.yaml。把对应环境变量配好，例如：

setx GCODE_API_KEY "你的 key"
setx DEEPSEEK_API_KEY "你的 key"

建议在虚拟环境中安装，避免和其它项目的 LangChain 版本互相覆盖。

密钥只放用户目录或环境变量，不要提交到 git。模板见仓库里的 models.yaml.example。

使用

若 gcode 不在 PATH 上，用 python -m gcode：

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 可关掉。

测试

python -m pytest

核心图不依赖 Textual，mock LLM 的冒烟测试在 tests/test_graph_smoke.py。

明确不做

Skills、Subagent、Plan 模式、语音、Island、其它 MCP 市场、Vertex / Anthropic / Bedrock 原生协议。文档以代码为准。