euzhi

v0.1.13

Published

2 months ago

Euzhi Assistant standalone CLI with configurable OpenAI-compatible runtimes.

0High
0Medium
0Low

euzhi-code

cli ai coding assistant openai-compatible euzhi

Euzhi Assistant CLI

Euzhi Assistant CLI 是一个可独立发布的 npm 命令行工具，目标体验是：

npm install -g euzhi
euzhi
euzhi console

默认配置已经切到你自己的网关方案：

默认模型：gpt-5.4
默认网关：https://api.okinto.com/v1
默认密钥环境变量：EUZHI_API_KEY
默认协议：responses
默认交互模式：native
默认原生传输：direct
默认兼容原生界面命令：claude

项目仓库：

https://gitee.com/nafla/euzhi-code

安装

先确认 Node 版本，建议 22 或 24，最低 20：

node -v

如果你当前还是 Node 18，先切到更高版本再安装，例如：

nvm use 24

然后再安装：

npm install -g euzhi

如果你在本地开发这个包，也可以直接：

cd packages/euzhi-cli
bun install
bun run build
node dist/cli.js --help

如果你想在本机先模拟全局安装效果，推荐直接：

cd packages/euzhi-cli
npm install
npm link
euzhi --help

快速开始

设置密钥

export EUZHI_API_KEY="你的密钥"

初始化配置

euzhi config init

进入对话

euzhi

如果这是第一次使用，CLI 会先进入初始化向导：

询问你是否使用默认的 Euzhi 推荐模型方案
如果选择“是”，会写入默认配置，并提示你设置 EUZHI_API_KEY
如果选择“否”，会要求你提供一个自定义配置 JSON 文件路径并导入

你也可以手动执行初始化：

euzhi config init
euzhi config init --sample
euzhi config init --from /absolute/path/to/config.json

如果你的网关本身兼容 Anthropic Messages 风格请求，直接启动即可：

export EUZHI_API_KEY="你的密钥"
euzhi

这时 euzhi 会直接把真实模型名注入给本地兼容终端界面，默认命令是 claude，例如 gpt-5.4 会按真实模型名透传。

如果你是在这个仓库里开发或调试，并且想强制优先使用仓库根目录已经构建出的 dist/cli.js，可以显式设置：

EUZHI_NATIVE_PREFER_WORKSPACE_DIST=1 euzhi

默认情况下，euzhi 仍会优先使用系统上的 claude 原生命令，只有在 PATH 里找不到 claude 时，才会回退到当前工作目录所在仓库的本地原生入口。这样可以保留完整 GUI / 调度能力，同时避免研究快照本地构建未完全可运行时的启动错误。

如果你的网关只支持 OpenAI chat.completions，再切到适配器模式：

euzhi config set ui.nativeTransport adapter
euzhi config set model.wireApi chat.completions
euzhi

单次提问

euzhi --print "帮我写一个 TypeScript debounce"

指定会话继续聊

euzhi --session project-a

本地全局调试

开发阶段推荐这样使用：

cd packages/euzhi-cli
npm install
npm run build
npm link

完成后你就可以在任意目录直接执行：

export EUZHI_API_KEY="你的密钥"
euzhi
euzhi ui
euzhi native
euzhi console
euzhi --print "请帮我生成一个 React hooks 示例"
euzhi --session demo
euzhi --resume

取消全局链接：

npm unlink -g euzhi

常用命令

euzhi
euzhi ui
euzhi native
euzhi console
euzhi console --port 4567
euzhi --session demo
euzhi --resume
euzhi --resume --session demo
euzhi --print "你好"
euzhi code --print "兼容旧用法"
euzhi config init
euzhi config get model.name
euzhi config set model.name gpt-5.4
euzhi config set model.baseUrl https://api.okinto.com/v1
euzhi provider add primary --model gpt-5.4 --base-url https://api.okinto.com/v1
euzhi provider clone primary primary-backup
euzhi provider list
euzhi provider use primary
euzhi provider export primary ./primary.json
euzhi provider import ./primary.json imported-primary --activate
euzhi session list
euzhi session search vite
euzhi session latest
euzhi session show demo
euzhi session export demo ./demo-session.json
euzhi session import ./demo-session.json demo-copy
euzhi session rename demo
euzhi session rename old-name new-name
euzhi session delete demo
euzhi config show
euzhi config path
euzhi doctor
euzhi model show

配置文件

可以先用下面命令查看实际配置路径：

euzhi config path

配置内容示例：

{
  "activeProfile": "default",
  "model": {
    "provider": "openai-compatible",
    "name": "gpt-5.4",
    "baseUrl": "https://api.okinto.com/v1",
    "apiKeyEnv": "EUZHI_API_KEY",
    "wireApi": "responses",
    "reasoningEffort": "medium",
    "systemPrompt": "You are Euzhi Assistant, a focused and practical coding partner.",
    "maxOutputTokens": 4096
  },
  "profiles": {
    "default": {
      "provider": "openai-compatible",
      "name": "gpt-5.4",
      "baseUrl": "https://api.okinto.com/v1",
      "apiKeyEnv": "EUZHI_API_KEY",
      "wireApi": "responses",
      "reasoningEffort": "medium",
      "systemPrompt": "You are Euzhi Assistant, a focused and practical coding partner.",
      "maxOutputTokens": 4096
    }
  },
  "session": {
    "autoSave": true,
    "defaultName": "default"
  },
  "ui": {
    "mode": "native",
    "command": "claude",
    "nativeArgs": [],
    "nativeTransport": "direct",
    "facadeModel": "sonnet"
  }
}

你也可以切换成别的模型、协议或命名 profile，比如：

euzhi config set model.name gpt-5.4
euzhi config set model.baseUrl https://api.okinto.com/v1
euzhi config set model.apiKeyEnv EUZHI_API_KEY
euzhi config set session.defaultName default
euzhi config set session.autoSave true
euzhi config set ui.mode native
euzhi config set ui.command claude
euzhi config set ui.nativeArgs '[]'
euzhi config set ui.nativeTransport direct
euzhi config set ui.facadeModel sonnet
euzhi config set model.wireApi chat.completions
euzhi provider add backup --model gpt-5.4 --wire-api chat.completions
euzhi provider use backup
euzhi --model gpt-5.4 --wire-api chat.completions
euzhi --model gpt-5.4 --wire-api responses
euzhi --base-url https://api.okinto.com/v1 --print "你好"

原生 UI 传输模式说明：

ui.nativeTransport=direct
- 适合“原生终端界面 + 自定义模型网关”这类接法
- euzhi 会直接设置 ANTHROPIC_BASE_URL / ANTHROPIC_API_KEY / ANTHROPIC_MODEL
- 原生终端界面会看到真实模型名，例如 gpt-5.4
ui.nativeTransport=adapter
- 适合只支持 OpenAI chat.completions 的中转站
- euzhi 会启动本地适配器把 Anthropic 风格请求转成 OpenAI 格式
- 这时 UI 里显示的是 ui.facadeModel，不一定等于真实上游模型名

Profile 导出和导入：

euzhi provider export backup
euzhi provider export backup ./backup-profile.json
euzhi provider clone backup backup-2
euzhi provider import ./backup-profile.json
euzhi provider import ./backup-profile.json backup-2 --activate

会话持久化

默认会自动保存会话历史。你可以：

euzhi --session worklog
euzhi --resume
euzhi --resume --session worklog
euzhi session list
euzhi session search worklog
euzhi session latest
euzhi session show worklog
euzhi session export worklog ./worklog-session.json
euzhi session import ./worklog-session.json worklog-copy
euzhi session path worklog
euzhi session rename worklog

交互模式里还支持：

/save [name]
/new [name]
/load <name>
/sessions

如果你在 REPL 里执行 /new 且没有提供名字，第一次提问后 CLI 会尝试根据首条用户消息自动给这个匿名会话命名。

本地控制台

全局安装 euzhi 后，也可以直接启动本地可视化控制台：

euzhi console

自定义端口：

euzhi console --port 4567

然后打开：

http://127.0.0.1:3456

现在的 console 已经不是只读面板，而是一个本地控制中心：

查看原生界面诊断状态
修改当前模型、网关、密钥环境变量、推理强度
编辑 ui.mode、ui.command、ui.facadeModel、ui.nativeArgs
切换当前 active profile
保存当前配置为命名 profile
删除非激活 profile
搜索和查看本地会话历史
从浏览器里一键请求拉起原生终端界面

原生界面模式

这是你当前主推的产品形态：

npm install -g euzhi
export EUZHI_API_KEY="你的网关密钥"
euzhi config init
euzhi config set model.baseUrl https://api.okinto.com/v1
euzhi config set model.name gpt-5.4
euzhi config set model.apiKeyEnv EUZHI_API_KEY
euzhi config set model.wireApi chat.completions
euzhi

这时 euzhi 会：

启动本地适配器
默认直接进入这套原生终端界面，仍然复用你机器上已经装好的兼容界面，默认命令是 claude
让原生终端界面使用一个本地可识别的 facade model，比如 sonnet
再由适配器转发到你配置的 OpenAI 兼容模型网关

当前原生适配层已经补上的接口包括：

POST /v1/messages
POST /v1/messages/count_tokens
GET /v1/models
GET /health

如果你的 claude 命令不在 PATH，可以显式配置：

euzhi config set ui.command /absolute/path/to/claude

或者临时覆盖：

EUZHI_NATIVE_COMMAND=/absolute/path/to/claude euzhi

原生命令解析优先级如下：

EUZHI_NATIVE_COMMAND
ui.command，当它不是默认的 claude 时
显式开启 EUZHI_NATIVE_PREFER_WORKSPACE_DIST=1 时，优先使用当前工作目录所在本地研究仓库根的 dist/cli.js
PATH 里的 claude
当前工作目录所在本地研究仓库根的 dist/cli.js
显式开启 EUZHI_NATIVE_ALLOW_REPO_DIST=1 时使用打包时关联的仓库 dist/cli.js

诊断

检查当前配置和密钥状态：

euzhi doctor

如果看到 apiKeyPresent: false，说明当前 shell 里还没有导出 EUZHI_API_KEY。

发布

发布前建议先执行：

bun install
bun run euzhi:release:check
bun run euzhi:release:publish

如果你想走 GitHub Actions，也已经补好了工作流：

文件：euzhi-cli-publish.yml
触发方式：推送 tag euzhi-v* 或 euzhi-cli-v*，或手动 workflow_dispatch
需要的 secret：NPM_TOKEN

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme