znaide

English · 中文

跑在终端里的"无所不能"通用 AI 助手。

用自然语言下达指令,znaide 自主完成:改文件、跑命令、查资料、整理数据、写文档……编程只是应用场景之一。它用 Rust 从零实现、自带 agent 循环:单个静态二进制、零 Node 依赖、中文交互、本地模型与云 API 通吃。

源码与获取:本工具以 AGPL-3.0 开源(仓库:github.com/twowb/znaide),自用/学习/开源衍生免费;商用或闭源集成需商业授权,见 COMMERCIAL.md。不想编译就直接下二进制:GitHub Releases 按平台取 znaide-<平台>-v<版本>(Linux/macOS/Windows/Android-Termux),--version 可查看版本。

  znaide                              # 交互模式(推荐,首次运行会引导配置)
  znaide -p "把 ~/Downloads 里的 zip 按日期归档"   # 无头模式直接执行任务

• 通用 Agent:内置工具 + agent 循环,自主"侦查 → 执行 → 汇报",不只限于写代码
• 多模型后端:OpenAI 兼容协议一网打尽——本地 ollama / vLLM,云端 DeepSeek / 通义(DashScope)/ OpenRouter 等,任意 base_url + key + model 均可
• 配置向导:首次运行分步引导——选服务商 → 自动查询可用模型列表(/models)→ 选/输入模型 → 填 Key → 验证连通成功后才解锁使用;之后随时 /config 修改并立即生效
• 工具集:文件读写/编辑(写前自动快照)、目录列举、glob、正则搜索、shell 命令(带超时)、网页抓取、长期记忆
• 安全四档:询问 ask(默认,写文件/命令先确认)/ 编辑放行 acceptEdits(文件修改自动放行)/ 全自动 bypassPermissions / 超级 yolo(一切放行含危险命令,后果自负),Shift+Tab 随时循环切换;危险命令走启发式高危判定(按解析出的目标路径判,不是匹配原文):目标是根目录/家目录/工作目录或其上级/块设备,或目标无法判定时,交互模式弹红色确认框、只允许单次放行,无头模式直接拒绝;超级 yolo 跳过判定。rm -rf /(多打空格)照样命中,rm -rf /tmp/123(具体路径)正常放行——但这是启发式提示,不是安全边界
• undo 回滚:每次改文件前自动快照,/undo 一键回滚,不依赖 git
• 长期记忆(两级):全局(随用户,记个人偏好/机器环境)+ 项目级(随当前仓库,记本仓库的约定/架构/待办,可提交也可 .gitignore);会话启动自动注入两级摘要,同名互不覆盖,删除按作用域走
• MCP 支持:配置 ~/.znaide/mcp.json 即可接入任意 MCP server 的工具
• 会话历史:每轮消息落盘 JSONL,/resume 随时恢复继续
• 技能(Skills):可被模型自主调用、也可 /技能名 手动触发的能力包(说明书 + 可选入口脚本),三层存放随时热扩展
• @文件 引用:输入 @路径 自动把文件内容/目录清单注入给模型;@"含空格路径" 可引用任意文件;输入时有路径补全(见下文)

cargo build --release
# 产物:target/release/znaide

make build        # 编译本机平台(自动检测)
make build-linux  # Linux x86_64(musl 全静态)
make build-linux-arm64  # Linux aarch64(musl 全静态)
make build-windows      # Windows x86_64(CRT 静态)
make build-macos        # macOS x86_64(zig 交叉编译)
make build-macos-arm64  # macOS aarch64(zig 交叉编译)
make build-android      # Android aarch64(NDK bionic 动态,Termux 用;NDK_ROOT 可覆盖)
make build-all          # 六平台一次构建(缺工具链自动跳过;android 需 NDK)

所有构建均为 --release 最小化产物(opt-level=z + LTO + 剥符号),产物在 dist/ 下。跨平台构建细节见 Makefile。

首次交叉编译可能提示 rustup target add <triple>(联网下载);Linux musl 静态需要 musl 交叉 gcc(Ubuntu:sudo apt install musl-tools);macOS 走 zig 万能交叉编译(无需 osxcross/SDK),需要 ~/.cargo/bin 下的 zig-cc-*-darwin wrapper 与 ~/.cargo/darwin-stubs/libiconv.tbd(说明见 Makefile 与 .cargo/config.toml)。

首次启动(尚无 ~/.znaide/config.json)时,交互模式会自动打开配置向导:

1. 选择服务商:内置 ollama / dashscope / deepseek / openrouter / zai,或选 custom 手输端点
2. 选择模型:程序自动请求该服务商的 /models 接口拉取真实可用模型,↑↓ 选择;若查询失败或想自定义,按 m 直接输入
3. 填 API Key:按 e 输入(本地服务如 ollama 可留空),Enter 进入下一步
4. 轮数上限:单条消息最多允许几轮模型往返,直接输入数字即可改(0 = 不限,留空 = 默认 200),Enter 完成
5. 验证并解锁:真实发一条请求验证——验证通过才保存配置并允许使用;失败则提示修改

重开(/config)时面板会带出当前配置(顶部有"当前配置"摘要行),改服务商/模型/Key/轮数上限,保存即生效(不中断当前会话)。

  znaide
  znaide --resume <会话ID|片段>   # 启动即恢复历史会话(ID 见底部状态栏/退出统计)

启动显示品牌横幅;/quit 或 /exit 退出(或 Ctrl+C),退出时在普通终端打印本次会话统计(时长/消息数/工具调用/Token/undo 快照/会话 ID)。启动后输入指令即可。常用按键:

模型工作中也能输入(排队):干活期间输入框照常可用(不再变灰,标签提示 Enter 排队),按 Enter 不会被丢弃——消息进队列(状态栏显示 队列 N),模型下一次调用就带着它继续干。排队不会打断正在跑的回合;想立刻停下当前的活按 Esc,队列里剩下的紧接着发出。

输入补全(实时):输入 / 弹出命令菜单(内置命令 + 已安装技能),输入 @ 弹出文件/目录补全(@dir/ 可逐层深入,@~/ 到家目录)——候选随输入实时过滤,首个候选同时在输入框内以淡色 ghost 预览。菜单打开时:↑ / ↓ 选择,Tab 或 Enter 采纳(采纳后需再按一次 Enter 才会发送,避免误触),Esc 关闭。含空格/标点的文件名采纳时自动转成 @"带空格路径" 形式(与 @ 引用解析一致),能引用任意文件。

鼠标:消息区内滚轮直接滚动;内容超出时消息区右侧会出现滚动条,可点击任意位置跳转,或按住拖动实时滚动(需终端支持鼠标事件;Linux 与 Windows 的 Windows Terminal / conhost 均可)。

工具调用卡片会实时显示 ⏳ → ✓/✗(执行中图标是脉动动画),标题下方浅灰小字直接展示正在调用的内容——命令类显示原文($ ls -la)、其它工具显示参数,执行中就能看清 AI 在干什么、要不要按 Esc 拦下,完成后也保留(结果输出在其下);模型自主调用技能时卡片显示为 skill「技能名」;需要写文件或执行命令时弹出确认框:y 允许一次 / a 本次会话都允许 / n 拒绝;破坏性操作(如 /clear 清空会话)弹独立确认框:y 确认 / n 或 Esc 取消。命令与工具输出的卡片预览保留 ANSI 颜色(所有上屏文本均经控制字节净化,不会污染画面);鼠标被接管后需复制时按住 Shift 拖动选择。

执行中的命令还有一块实时输出区:卡片下方划出 ────── 实时输出 ──────,像 tail -f 一样滚动显示最新 10 行输出(ANSI 颜色保留);消息区自动贴底跟随,你上翻看历史时暂停跟随、视野不会被新输出推走,回到底部恢复;命令结束后区域收回,卡片回落为结果预览。

卡片带动态计时:执行中的命令显示 ⏳ run_shell_command · 12s · 预算 4min,秒级跳动,完成后显示总用时。AI 执行命令时可传 idle_ms 作为预估完成时长(宁大勿小;不传则不设预算、正常命令零打扰):命令跑超预估(另有约 20%、最多 60s 宽限)仍未结束就被终止,终止时把运行时长与死前输出反馈给 AI,由它自行决定加大预算重试、拆步或换路;命令连续 90s 没动静会被判卡死;长时间无输出时卡片先变黄、临近终止变红,超出预算进入宽限期时卡片会明示"已超预算,宽限剩 Xs",终止原因与进展都会回给 AI,不会盲目重跑。

执行中按 Esc 可随时中断:正在跑的工具立即停,同批还没来得及执行的动作会在历史里记成「未执行」,会话历史始终保持完整——中断后继续对话、或日后 --resume 恢复,都能无缝接着聊,不会出现恢复后无法对话的情况。

底部状态栏从左到右显示:权限模式(中文短名:询问 / 编辑放行 / 全自动 / 超级)[| 人格(有人格时显示,空 = 默认助手)] | 模型 | 状态(就绪/工作中…/压缩中…;执行=流动光条、压缩=收纳推进条动画) · 轮 本轮已用/上限(上限 0 显示 ∞,见 max_turns)[| token 统计:**累计** in 输入 · out 输出 · Σ 总计(计费口径累计:每次模型往返都重发整段历史、各计一次,所以随轮数增长,**不是上下文占用**;/clear、/resume 归零,/compact不归零;流式中 out/Σ 带 ≈ 实时估算)][| ctx ▓▓▓▓▓░░░░░ 34% 上下文占用条(占模型窗口比例,窗口已知即常驻;70% 变黄 / 90% 变红并提示可 /compact;**占用还没测到时显示ctx ?**——刚 /resume、/compact完就是这样,真实值等下一轮回复;新会话与/clear后是真实的 0%;**窗口认不出来时显示ctx ~21.4k 窗口未知**:只报绝对量、不编百分比、不提示压缩)] · 会话 <id>。

输入框与输出框边框颜色 = 当前权限模式:询问=绿 / 编辑放行=天蓝 / 全自动=紫 / 超级(YOLO)=红(工作中也保持该颜色,输入框不再变灰;输出框常显);Shift+Tab 切换后边框立即变色。会话 ID 启动即显示,与本会话历史文件同名(~/.znaide/sessions/<id>.jsonl),可配合 /resume 用 ID 片段精确定位恢复。

全局人设:/persona 查看/切换内置人格(毒舌损友 / 耐心老师 / 热血极客 / 极简冷淡风),/persona 无 关闭(默认)。切完写回 config 持久生效——之后所有对话(问答/汇报/建议)都带着这个人格,重启也在,直到再切。底部状态栏常驻显示当前人格,随时知道"是谁在说话"。人格影响表达与视角;工作守则与安全边界(权限、危险命令拦截、工具纪律)作为底层约束不被覆盖。

人格就是一份 Markdown,随便改:人格文案放在仓库 personas示例/(编译期内嵌,单源),启动物化为 ~/.znaide/personas/<名字>.md——内置的四种人格也以文件形式躺在那里,打开就能看、随手改两句措辞(比如让毒舌损友少损一点),改完重启即生效;删掉某个人格文件就恢复内置默认;想要新人格,往目录里放一个 <名字>.md 就行,不用改代码。想收藏别人的?复制一份 md 进目录即可。

技能 = 可被模型自主调用、也可手动 /名字 触发的能力包。模型判断任务匹配某个技能时,会调用 skill 工具并把技能名带进来;系统把说明书正文(渲染好 {args})+ 可选入口脚本的输出注入上下文,模型按说明用基础工具逐步完成。技能不新增权限面——所有落地动作仍走权限档位、高危命令判定与 undo 快照。

存放三层(同名按 项目 > 用户 > 内置 覆盖):

内置(开箱即用)                       # archive-downloads / clean-junk / weekly-report
~/.znaide/skills/<名字>/SKILL.md       # 用户级(推荐)
.znaide/skills/<名字>/SKILL.md         # 项目级(随仓库分发,内容视为不可信输入)

三个示例技能已编译进二进制、开箱即有(/skills 可见、模型可自主调用),内容物化在 ~/.znaide/builtin-skills/(改了示例源目录即改内置;启动自动补齐缺失文件,已改动的不覆盖)。发布不再单独附带技能包。

格式(SKILL.md,frontmatter 简子集):

---
description: 把 ~/Downloads 里的压缩包按日期归档(给模型判断何时用)
disable-model-invocation: true   # 可选:true 则不出现在模型调用列表,只能手动 /名字
entry: scripts/run.sh            # 可选:调用时自动执行一次,stdout 并入上下文
---
正文:教模型怎么做。支持 {args} 占位,可指示"先读 scripts/checklist.md"。

• 模型调用:技能暴露为一个 skill 工具,可用技能名在参数 enum 里;disable-model-invocation: true 的技能不出现在列表
• 手动触发:/技能名 参数...;无入口脚本时正文直接作为本回合指令(旧自定义命令同款),有入口脚本时在 agent 侧统一执行(命令需按权限确认)
• 入口脚本 entry:相对技能目录的脚本,跨平台:macOS/Linux 用 .sh(bash 执行,不依赖 +x);Windows 上引擎自动找同名 .ps1 → .bat → .cmd(用 PowerShell/call 执行),都没有才退回 .sh 并在结果里说明。{args} 经命令行参数传入,环境变量 SKILL_DIR 指向技能目录。正文也应写平台分支命令(如移动:mv ↔ Windows move/Move-Item),不要只写自己机器的写法。项目级技能也允许 entry,但执行前会走权限确认,警惕第三方仓库自带的 SKILL.md/脚本

示例一(归档,跨平台:入口放 scripts/snapshot.sh,同目录再放一份 scripts/snapshot.ps1 供 Windows 用):

---
description: 把系统下载目录里的压缩包按类型归档
entry: scripts/snapshot.sh
---
入口输出按当前平台给出快照。来源目录:Linux/macOS 默认 ~/Downloads,
Windows 默认 %USERPROFILE%\Downloads。归档到 ~/archives(%USERPROFILE%\archives)。
移动命令按平台选择:macOS/Linux 用 mv;Windows 用 move 或 PowerShell Move-Item。

示例二(写周报,无入口):

---
description: 根据 git 提交记录写一段中文周报
---
先 cd 到目标仓库执行 git log --oneline -30 查看近期提交,
再按"做了什么 → 影响 → 下一步"总结成一段简洁中文周报。

旧版 ~/.znaide/commands/*.md 会在启动时自动迁移为 ~/.znaide/skills/<名字>/SKILL.md(保持仅手动触发),无需手动处理。

# 单次执行,默认 ask 模式(写文件/命令会被拒绝,按需放开)
znaide -p "看看这个目录里有什么"

# 允许自动改文件(命令仍需确认)
znaide -p "把 README 里的 X 改成 Y" --permission acceptEdits

# 全自动执行
znaide -p "把 ~/Downloads 里的 zip 按日期归档" --permission bypassPermissions

# 临时指定模型/服务商(不改配置文件)
znaide -p "你好" --provider deepseek
znaide -p "你好" --model qwen3:8b --base-url http://localhost:11434/v1

# 大任务跑更久(默认单条消息最多 200 轮模型往返;0 = 不限)
znaide -p "把整个仓库的 TODO 过一遍" --permission bypassPermissions --max-turns 0

# 本次运行走代理 / 强制直连(当次生效,不改配置文件;模型、抓网页、更新都走它)
znaide -p "查一下资料" --proxy http://127.0.0.1:7897
znaide -p "排查连接问题" --no-proxy

# 弱网重试:空回复 / 限流 / 5xx / 断连时自动重发同样的请求(默认关)
znaide -p "高峰期跑个任务" --retry 3

# 给模型请求加一个自定义头(网关/计费/审计用;当次生效,不改配置文件)
znaide -p "你好" --extra-header X-Tenant-Id=t1
# 排查网关 4xx:这次一个预设头都不发
znaide -p "你好" --no-extra-headers

{
  "provider": "ollama",
  "max_turns": 200,
  "providers": {
    "ollama": {
      "base_url": "http://localhost:11434/v1",
      "model": "qwen3:8b",
      "context_window": 40960
    },
    "dashscope": {
      "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
      "model": "qwen-plus",
      "api_key_env": "DASHSCOPE_API_KEY"
    },
    "deepseek": {
      "base_url": "https://api.deepseek.com/v1",
      "model": "deepseek-chat",
      "api_key_env": "DEEPSEEK_API_KEY"
    }
  }
}

字段说明:

• provider:当前启用的服务商——切它就换整套(端点 / 模型 / Key);想在多个服务商之间来回切,就在 providers 里各配各的
• providers:按字段覆盖内置预设(内置条目做底,只写你要改的字段,其它字段保留内置值);每个条目支持 base_url / model / api_key / api_key_env(推荐,从环境变量读 Key)/ context_window
• 顶层 model / base_url / api_key(可选):手动临时覆盖,优先级高于预设;面板保存不会写这里。老配置里已有的顶层值会在启动时自动搬进当前 provider 条目并清空顶层(一次性自愈迁移),之后切换 provider 才真正生效
• context_window(可选):该项建议写在 provider 条目里(各服务商各配各的);顶层那个是历史遗留兜底。不设置时按模型名匹配内置表(2026-09 检索:qwen3→40k、qwen-plus / qwen3.x-max→1M、deepseek-v4 / deepseek-flash→1M、gpt-5→400k、claude→200k 等);表里认不出来就按"未知"处理——状态栏只报绝对量(ctx ~21.4k 窗口未知),不给百分比、也不提示 /compact,不拿默认值假装知道(模型 ID 迭代很快,猜小了会把百万级模型算成快满了,劝你做没必要的压缩)。要百分比就把窗口填准(面板第 4 步或这个字段);本地模型(ollama)请与运行时的 num_ctx 保持一致
• max_turns(可选):单条消息最多允许的模型往返轮数(一轮可含多次工具调用),默认 200;0 = 不限。用完不再静默停——交互模式弹"继续执行"确认框,无头模式说明已达几轮与怎么调大;另有"同一调用重复 3 次提醒、6 次判原地打转中止"的刹车
• proxy(可选):网络代理,三档 —— 不写 / {"mode":"auto"} = 跟随环境变量(HTTPS_PROXY 等,与旧版一致);{"mode":"direct"} = 强制直连;{"mode":"manual","url":"http://127.0.0.1:7897"} = 所有请求走它。模型请求、网页抓取、更新下载三处统一走这一份;优先级:命令行 --proxy/--no-proxy > ZNAIDE_PROXY/ZNAIDE_NO_PROXY > 配置文件 > 标准环境变量(标准环境变量只在 auto 档生效);手动档仍尊重 NO_PROXY,所以"国内服务商直连 + 国外走代理"配上 NO_PROXY 即可
• retry(可选):弱网重试的追加尝试次数(0..=8,默认关)。只重试一次模型调用——不会重复执行工具,不占轮数预算,失败那次的输出不写历史也不计 token;空回复 / 429 / 5xx / 连接中断按 800ms 起指数退避重发,退避期间按 Esc 可中断。命令行 --retry N / --no-retry 优先于它
• extra_headers / extra_headers_enabled(可选):用户预设的 HTTP 请求头,给"网关要自定义头才放行 / 按头计费 / 内网审计"用(如 OpenRouter 的 HTTP-Referer、X-Title,网关的 X-Tenant-Id)。只作用于模型请求——网页抓取与更新下载不带,免得把内部标识泄漏给第三方 URL。生效头 = 顶层表 ⊕ 当前 provider 表(同名 provider 覆盖;provider 里值为空串 = 删掉顶层来的那条);extra_headers_enabled 是总闸,顶层或某个 provider 设 false 就一条都不发。值支持 ${VAR} / $VAR 展开(没读到就原样发送并提示),敏感值走环境变量、不落盘明文;Authorization / Host / Content-Type 等保留头会被忽略并提示。命令行 --extra-header K=V(可重复)/ --no-extra-headers 与 ZNAIDE_EXTRA_HEADERS 优先于配置

API Key 也可以完全不进配置文件,用环境变量提供:DASHSCOPE_API_KEY、DEEPSEEK_API_KEY、ZAI_API_KEY、OPENROUTER_API_KEY 等,向导会自动读取。

配置优先级:命令行参数 > 环境变量 > config.json > 内置预设。

~/.znaide/
├─ config.json      配置(provider / model / base_url / api_key)
├─ mcp.json         MCP server 配置(可选)
├─ skills/          技能(skills/<名字>/SKILL.md,可带 scripts/)
├─ sessions/        会话历史 *.jsonl(可有同名 *.meta.json 备注)
├─ memories/        长期记忆·全局级(*.md + MEMORY.md 索引)
└─ undo/            写文件前快照(manifest.jsonl + files/)

编辑 ~/.znaide/mcp.json:

{
  "mcpServers": {
    "filesystem": { "command": "node", "args": ["/path/to/server.js"] }
  }
}

启动后 znaide 自动连接并把 MCP 工具并入工具箱(工具名形如 mcp__<server>__<tool>),模型可直接调用;MCP 工具按"写操作"对待,询问模式下会先征求确认。

znaide/
├─ crates/
│  ├─ core/     引擎:agent 循环、LLM 客户端(OpenAI 兼容)、工具、权限、技能(skills)、记忆、会话、undo、MCP、配置(纯逻辑,零终端依赖)
│  ├─ tui/      交互界面(ratatui):对话区、输入、配置向导、确认框、工具卡片、滚动条与鼠标
│  └─ cli/      入口:交互 / -p 无头 / 参数解析
├─ docs/         方案与设计文档(plan-v1.md、plan-skills.md)
└─ Makefile      跨平台构建

cargo build              # 调试构建
cargo test               # 单元 + 集成测试(含本地 mock 端到端)
cargo test -p znaide-tui # TUI 相关(配置向导、按键逻辑)