goding

goding 是一个干净的、从零手写的 Go 编码智能体，其架构灵感来自 Claude Code 背后的设计理念：provider 无关的轮次循环、显式的工具生命周期、权限决策、可恢复的追加式会话记录，以及有界上下文管理。

安装

前置要求：方式一/二无需安装 Go（直接下载预编译二进制）；方式三~五需要 Go 1.26 或更高版本（go.dev/dl）。

有以下几种方式，任选其一：

方式一：一行命令安装（推荐）

无需安装 Go，用官方脚本直接从 GitHub Releases 下载预编译二进制，安装到 ~/.goding/bin 并自动加入 PATH（含 SHA-256 校验）。

macOS / Linux（依赖 curl、unzip，均自带）：

curl -fsSL https://raw.githubusercontent.com/MrSibe/Goding/main/scripts/install.sh | sh

Windows（PowerShell 5.1+）：

irm https://raw.githubusercontent.com/MrSibe/Goding/main/scripts/install.ps1 | iex

可选环境变量：GODING_VERSION（指定版本号，默认 latest 即最新 Release）、GODING_INSTALL_DIR（安装目录，默认 ~/.goding）。安装完成后新开终端（或手动刷新 PATH）再运行 goding 验证。

方式二：从 GitHub Releases 手动下载

每次打 tag（如 v0.1.0）时，GitHub Actions 会自动用 GoReleaser 构建 Windows / macOS / Linux 三平台二进制并发布到 Releases。

1. 打开 Releases 页面，下载对应系统的归档（如 goding_0.1.0_windows_amd64.zip）；
2. 解压后把 goding（Windows 为 goding.exe）放进 PATH 目录（Windows 上如 C:\Users\<你>\go\bin，或任意你习惯的目录）；
3. 在终端运行 goding 验证。

方式三：go install（一条命令装全局）

go install github.com/mrsibe/goding/cmd/goding@latest

Go 会自动从 GitHub 下载源码、编译并安装到 GOBIN（默认 %USERPROFILE%\go\bin，请确保它在 PATH 中）。若仓库尚未发布，可本地安装：

cd <仓库目录>
go install ./cmd/goding

方式四：go build（构建单个二进制）

cd <仓库目录>
go build -o goding.exe ./cmd/goding

产出的单个二进制可随意拷贝到其他机器运行。交叉编译到其他平台：

$env:GOOS="linux"; $env:GOARCH="amd64"; go build -o goding-linux-amd64 ./cmd/goding

方式五：go run（开发调试）

cd <仓库目录>
go run ./cmd/goding

每次都会重新编译，适合开发，不适合日常使用。

快速开始

provider 是 openai-go，可对接任何 OpenAI 兼容的 Chat Completions 端点（OpenAI、DeepSeek 等）。

$env:OPENAI_API_KEY = "..."
$env:OPENAI_MODEL = "gpt-4o-mini"        # 可选；默认值如上所示
$env:OPENAI_BASE_URL = "..."             # 可选；OpenAI 兼容的 base URL，例如 https://api.deepseek.com
go run ./cmd/goding

工作目录中的 .env 文件同样生效 —— 变量在启动时读取，真实的环境变量优先：

OPENAI_API_KEY=sk-...
OPENAI_BASE_URL=https://api.deepseek.com
OPENAI_MODEL=deepseek-v4-flash

恢复一个会话：

go run ./cmd/goding resume <session-id>

运行时数据存储：

• 会话记录：全局 ~/.goding/sessions/<encoded-cwd>/（按项目编码分目录，写第一条记录时才创建；可用 GODING_SESSION_DIR 覆盖）
• 权限规则：~/.goding/permissions.json（可用 GODING_PERMISSIONS_FILE 覆盖）
• 项目信任：~/.goding/trust.json
• 密钥：~/.goding/auth.json（0600）

运行 goding 不会在项目工作区里产生任何文件（会话等运行时数据全部放全局 ~/.goding/）；项目目录里只有你主动放置的 .goding/settings.json 等 可提交的团队配置。

只读工具（Read、Glob、Grep）自由运行；Write、Edit 和 Shell 每次都要求单独确认（确认时可按 s 记本次会话、按 a 记全局规则）。

工具默认不限定路径范围（参照 Pi：以用户进程的权限直接访问任意路径，安全边界交给操作系统/容器）。因此 Read/Glob/Grep 可以读取工作区之外的任意文件，Write/Edit/Shell 在确认后也可操作工作区之外的位置。若希望恢复"拒绝逃出工作区"的旧行为，可开启 restrict_to_workspace（见下文配置）。

工具

agent 内置六种工具。Read、Glob 和 Grep 是只读的、无需确认即可运行；Write、Edit 和 Shell 会经过用户明确批准：

• Read —— 带行号读取文件。整文件读取上限为 64 KB；更大的文件请用 offset/limit 分片读取。可读取任意路径（默认不限制工作区）。
• Glob —— 查找匹配 glob 模式的文件（** 跨目录匹配，例如 **/*.go）。可指定任意基础目录。
• Grep —— 用 Go RE2 正则表达式搜索文件内容；返回 path:line:content 格式的匹配。可搜索任意目录。
• Write —— 创建或覆盖文件（父目录自动创建）。
• Edit —— 用精确字符串替换修改文件。文件必须已先被读取过；写入前会检测外部修改。
• Shell —— 运行 shell 命令并捕获其输出（起始目录为工作目录，命令本身可访问任意路径）。

Shell 输出在 32 KB 处截断，命令在 120 秒后超时。在 Windows 上，shell 默认使用 PowerShell（优先 pwsh，其次 powershell），否则回退到 cmd.exe —— 避免误选 WSL 的 C:\Windows\System32\bash.exe（那会把命令带进 WSL 环境）；可用 GODING_SHELL 覆盖（例如 cmd 表示 cmd.exe /C，pwsh 表示 PowerShell Core）。

配置

配置分环境变量与配置文件两层；优先级从低到高：默认值 → 全局配置 → 项目配置 → 环境变量（含 .env）。密钥走独立的 auth.json，与可提交到 git 的配置严格分离。

环境变量

变量	含义	默认值
OPENAI_API_KEY	Chat Completions 端点的 API 密钥（必填；也可写入 auth.json）	—
OPENAI_MODEL	模型名称	gpt-4o-mini
OPENAI_BASE_URL	任意 OpenAI 兼容端点的 base URL	OpenAI
GODING_SHELL	Shell 工具的 shell（cmd/powershell/pwsh 简写，或自定义 shell 路径）	Windows 默认 PowerShell→cmd，POSIX 默认 /bin/sh
GODING_MAX_CONTEXT_TOKENS	用于 token 预检的上下文预算	128000
GODING_SESSION_DIR	会话记录存储位置（默认全局 ~/.goding/sessions/<encoded-cwd>/，按项目分目录）	~/.goding/sessions/<encoded-cwd>/
GODING_AUTO_COMPACT	预算超限或模型报 context 过长时自动压缩并重试（0/false 关闭，手动 /compact 仍可用）	开启
GODING_SUMMARY_MAX_TOKENS	自动压缩摘要调用的输出 token 上限	2000
GODING_RESTRICT_TO_WORKSPACE	是否把工具路径限制在工作区内（1/true 开启，0/false 关闭）	关闭（不限制，Pi 风格）
GODING_CONFIG_DIR	覆盖全局配置目录（默认 ~/.goding）	~/.goding
GODING_PERMISSIONS_FILE	权限规则存储路径	~/.goding/permissions.json

配置文件

与 Pi / Claude Code 类似，配置为 JSON，支持全局 + 项目两层：

• 全局：~/.goding/settings.json（个人偏好，如默认模型、自动压缩开关）
• 项目：<项目>/.goding/settings.json（可提交到 git 的团队共享配置）

项目设置会深合并到全局之上（嵌套对象合并，数组整体替换）；环境变量始终最高优先级。

// ~/.goding/settings.json 或 <项目>/.goding/settings.json
{
  "model": "gpt-4o-mini",
  "base_url": "https://api.deepseek.com",
  "max_context_tokens": 128000,
  "auto_compact": true,
  "summary_max_tokens": 2000,
  "session_dir": "~/.goding/sessions/<encoded-cwd>",
  "default_project_trust": "ask", // ask | always | never（仅全局生效）
  "restrict_to_workspace": false, // true 时拒绝工具访问工作区之外的路径（默认 false，不限制）
  "instructions": ["GODING.md", "AGENTS.md", "CLAUDE.md"],
}

项目信任门禁：项目含 .goding/settings.json 等本地配置时，首次启动会询问是否 信任（default_project_trust: always 可跳过询问）；决策记入 ~/.goding/trust.json， 未信任的项目其 .goding/settings.json 不会加载。可用 REPL 内 /trust / /untrust 调整。

密钥：~/.goding/auth.json（权限 0600，明文密钥请勿提交）：

{ "openai_api_key": "sk-..." }

OPENAI_API_KEY 环境变量优先于 auth.json。

指令文件：GODING.md（兼容 AGENTS.md / CLAUDE.md）会作为系统提示注入。 加载顺序：全局 ~/.goding/<name> → 项目目录逐级向上回溯，越靠近当前目录优先级 越高。

REPL 命令

命令	作用
/exit	退出
/help	显示命令
/sessions	列出已保存的会话 ID
/clear	开启新会话（旧的仍可通过 ID 恢复）
/compact	丢弃最旧轮次以适配预算；恢复时保持被丢弃状态（自动压缩会生成 LLM 摘要，/compact 是手动兜底）
/allow	添加全局 allow 规则（如 /allow Shell(go build:*)）
/deny	添加全局 deny 规则（如 /deny Shell(rm -rf:*)）
/rules	列出/删除权限规则（/rules rm <n>）
/trust	信任当前项目（下次启动加载其 .goding/settings.json）
/untrust	取消信任当前项目

开发

go test ./...
go test -race ./...   # 在 Windows 上需要 C 工具链（gcc）

依赖：github.com/openai/openai-go/v3（唯一直接依赖）。

发布新版本

打一个 v* 标签即可触发 GitHub Actions 自动构建三平台二进制并发布到 GitHub Releases：

git tag v0.1.0
git push origin v0.1.0

发布由 .goreleaser.yaml + .github/workflows/release.yml 驱动，产物含校验和（checksums.txt）。本地预览发布内容（需安装 GoReleaser）：

goreleaser release --snapshot --clean