gyuan-code
hkban99668-code/gyuan-code
终端 AI 编程助手 · 研究 Claude Code 架构后从零重构的 agentic coding CLI(多 Provider / 工具调用闭环 / 三态权限)
Instalação
npx convez-ai hkban99668-code/gyuan-code1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
Gyuan Code
终端里的 AI 编程助手(agentic coding CLI)。基于对 Claude Code 架构的学习研究,用 TypeScript 从零实现的精简版:Agent 主循环、工具系统、三态权限、流式终端 UI 一应俱全,开箱可用。

上图:让 Gyuan Code 实现一个带单元测试的函数 —— 它自动维护任务清单、写代码、跑测试并汇报结果(真实运行截图)。
功能
- 交互式 REPL:流式输出、markdown 终端渲染、输入历史(↑/↓)、slash 命令补全(Tab)
- 8 个工具:Bash(持久 shell)/ Read / Write / Edit / Glob / Grep / TodoWrite / Agent(子代理)
- 权限系统:只读直接放行;写操作弹窗确认(允许 / 本项目不再询问 / 拒绝);规则持久化到
.gyuan/settings.json - 安全护栏:Edit/Write 强制"先 Read 后改"(mtime 校验,防止覆盖外部修改)
- 项目记忆:自动加载
GYUAN.md/AGENTS.md/CLAUDE.md(逐级向上查找)+ git 状态注入 - 上下文压缩:
/compact手动压缩;超过上下文窗口 80% 自动压缩 - 会话:
--continue续接上次会话;/cost查看 token 用量与费用 - print 模式:
gyuan -p "任务"非交互执行,适合脚本/管道 - 多 Provider:Anthropic 官方 API、任意 OpenAI 兼容端点(DeepSeek/Kimi/GLM/vLLM…)、mock(离线演示)
安装
cd gyuan-code
npm install
npm run build
npm link # 之后可在任意目录使用 gyuan 命令
要求 Node.js ≥ 20。
配置 API
三选一:
# 1) Anthropic 官方
export ANTHROPIC_API_KEY=sk-ant-...
# 2) OpenAI 兼容端点(以 DeepSeek 为例)
export GYUAN_PROVIDER=openai
export GYUAN_BASE_URL=https://api.deepseek.com/v1
export GYUAN_API_KEY=sk-...
export GYUAN_MODEL=deepseek-chat
# 3) 什么都不配 → 自动进入 mock 演示模式(无真实模型,用于体验 UI)
也可写入全局配置 ~/.gyuan/config.json:
{
"provider": "anthropic",
"model": "claude-sonnet-4-6",
"apiKey": "sk-ant-...",
"permissions": { "allow": ["Bash(git *)"] }
}
用法
gyuan # 进入 REPL
gyuan "解释一下这个项目的结构" # 带初始提示进入 REPL
gyuan -p "把 README 里的错别字修了" # 非交互执行(默认拒绝写操作,--yolo 放行)
gyuan -c # 续接当前目录上次会话
gyuan -p "跑测试并修复失败用例" --yolo --max-turns 30
REPL 内命令:/help /clear /model /cost /compact /tools /init(生成 GYUAN.md)/exit
快捷键:Esc 中断当前任务 · Ctrl+C 清空输入/双击退出 · Ctrl+D 退出 · Tab 补全命令
测试
npm test # 28 项断言,3 个测试套件,全部离线,无需任何 API key
test/e2e.mjs(12 项):mock provider 驱动完整主循环——工具落盘、权限默认拒绝、--yolo放行、强制先读后写、持久 shell 跨调用保留 cwd、参数校验回灌、子代理闭环、--continue续接test/openai-provider.mjs(8 项):起一个假 OpenAI SSE 端点,验证文本增量、tool_call 跨 chunk 累积、tool_result 往返、消息格式转换test/anthropic-provider.mjs(8 项):起一个假 Anthropic SSE 端点(官方事件协议),验证input_json_delta分片累积、prompt cache 断点、tool_result 回灌
交互式 REPL 另经 tmux / expect 驱动真实 PTY 实测(banner、流式 markdown、方向键权限对话框、/cost、/exit)。
mock provider 可用脚本精确回放模型逐轮行为:
GYUAN_PROVIDER=mock GYUAN_MOCK_SCRIPT=script.json gyuan -p "..." --yolo
架构
用户输入 ─→ REPL (ink/React)
│
▼
query() 主循环 (async generator)
│ yield: 文本增量 / 工具事件 / 权限请求
▼
Provider (anthropic | openai 兼容 | mock)
│ stop_reason == tool_use ?
▼
权限判定 (allow/ask/deny) ─→ 工具执行 ─→ tool_result 回灌 ─→ 继续循环
详细设计与取舍见 docs/DESIGN.md。
致谢
架构设计学习自 Anthropic 的 Claude Code。本项目为教学目的的原创实现,未复制其源码。