Zeph

English | 简体中文

终端优先的 AI 编码代理（自研 Agent Harness）。TypeScript + Bun 单仓（monorepo），对照 oh-my-pi 与 MiMo-Code 的能力面自研实现；需求、设计与决策记录见 docs/。

当前为 MVP 阶段（0.1.0）：Agent 主循环、多 provider 流式客户端、基础工具面、JSONL 会话持久化、-p 一次性模式与交互 TUI 均可用；完整路线图（MVP / V1 / V2）见 docs/agent-harness.md §14。

特性

已实现

• Agent 主循环 — prompt → 流式 → 工具调用 → 结果 → 续轮，事件驱动（agent_start / message_update / tool_execution_* / turn_end），支持中止与继续（packages/agent）
• 多 provider 流式客户端 — OpenAI / OpenAI Responses / Anthropic / Gemini（REST + CLI + Vertex）/ Azure / Bedrock / Codex / Mock（packages/ai）
• 工具框架与内置工具 — read / write / edit / grep / glob / bash / ask，参数 schema 即校验源（arktype）（packages/tools）
• 会话持久化 — JSONL append-only 会话文件，可回放、可列表（packages/session）
• CLI — zeph -p "…" 一次性模式（CI 友好）、极简 REPL、交互 TUI（Ink 差分渲染：编辑器 / transcript / 选择器 / 状态栏）、zeph login / zeph logout 凭证管理、zeph setup 首启 TUI 配置（向导内直接 OAuth）、会话内 slash 命令：/init（为仓库生成 AGENTS.md 并解析回 repo rules）、/clear（就地清空对话上下文、保留 session）、/compaction（/compact，将当前上下文折叠为摘要）与 /append / /append-file / /append-reset（向系统提示词追加一段文本 / 文件，claude-code --append-system-prompt 语义，下一轮生效；无参数 /append 审计已累积的追加块，/append-reset 丢弃运行时追加回到启动值）（packages/cli）
• 回退链与重试 — 429/配额自动走 fallback 链，带背压与冷却（docs/agent-harness.md §2.7）
• 认证 — Google ADC / OAuth 流程；订阅 coding plan OAuth：Anthropic（Claude Pro/Max）、xAI SuperGrok（grok-build）、GitHub Copilot、Kimi Code、Z.AI GLM Coding Plan、OpenAI Codex 设备登录、Zhipu Coding Plan key 登录（packages/ai/src/auth）

规划中（见 docs/agent-harness.md）

• V1：hashline 编辑、LSP、多子代理（actor + worktree 隔离）、持久记忆（文件式 MEMORY/checkpoint）、compaction、审批/权限、SDK + RPC、扩展/钩子/slash
• V2：browser / computer、DAP、技能治理、workflow 确定性编排、MCP 完善、collab、marketplace

仓库结构

packages/
  core/     事件 / 消息 / 工具 / 模型目录类型与 schema（arktype）
  ai/       多 provider 流式客户端、toolconv、回退链、认证
  agent/    Agent 主循环与消息处理
  session/  JSONL 会话持久化与分支导航
  tools/    工具框架与内置工具
  cli/      zeph 入口：-p / REPL / 交互 TUI
docs/       需求与设计文档（agent-harness.md · tui.md · knowledge-base.md · topics/）

快速开始

要求：Bun（≥ 1.3）。发布的 CLI 打包了 Bun 运行时 API，无论通过哪种方式安装，运行时都需要 Bun。

安装

# 推荐 —— 通过 Bun 包管理器
bun add -g @viloris/zeph

# 或用 npm（运行时仍需 Bun）
npm install -g @viloris/zeph

验证安装：

zeph --version

升级到最新版本：

bun add -g @viloris/zeph@latest

从源码构建

bun install
bun run check      # 全仓类型检查
bun test           # 全仓测试

使用

# 存储凭证（provider: opencode-go / azure / google-gemini-cli / google-vertex / bedrock / anthropic / xai-oauth / github-copilot / kimi-code / zai / openai-codex / zhipu-coding-plan）
zeph login <provider>

# 清除已存凭证（不带参数时列出当前已配置项）
zeph logout [provider]

# 更新到最新发布版本（启动时发现新版本也会提示）
zeph update

# 在 TUI 中配置 provider + 模型（TUI 内也可运行 /setup）
zeph setup

# 一次性模式
zeph -p "解释这个仓库的结构"

# 交互模式（REPL 或 TUI）
zeph

# 指定模型
zeph --model provider/id

CLI 选项

| 选项 | 说明 | |---|---| | -p, --prompt <text> | 一次性 prompt（裸参数等同） | | -C, --cwd <dir> | 工作目录（默认当前目录） | | --model <provider/id> | 指定模型（否则按 models.yml / 环境变量 / 内置目录回退） | | --system-prompt <text> | 覆盖基础系统提示词 | | --append-system-prompt <text> | 在基础系统提示词上追加一段提示词 | | --append-system-prompt-file <file> | 读取文件内容并追加到基础系统提示词 | | --no-session | 不落盘会话 | | -v, --verbose | 向 stderr 打印 agent 事件 | | --list-sessions | 列出已持久化的会话 | | -h, --help / --version | 帮助 / 版本 |

启动时 zeph 会检查 npm registry 是否有新版本，有则显示升级提示；zeph update 直接升级。可用 ZEPH_NO_UPDATE_CHECK=1 关闭检查。

配置

• 首次运行：未配置模型时裸 zeph 仍进入 TUI——状态栏显示 no model — /setup，发送 prompt 会给出提示。在 TUI 内运行 /setup（或 zeph setup）选择 provider、粘贴 API key（掩码显示）、选择模型；保存到 credentials.json + models.yml。本地无 key 引擎（ollama / lm-studio / vllm）无需 key；Gemini CLI 在向导内直接完成 OAuth 登录（自动开浏览器，粘贴回 code，无需退出到 CLI）；google-vertex / bedrock / openai-codex 显示外部凭证指引（Ctrl+K 打开控制台）。
• 模型与自定义 provider：models.yml（ZEPH_DATA_DIR 内，默认 ~/.zeph/agent/models.yml）
• 凭证：~/.zeph/agent/credentials.json（0600 权限）；OAuth 凭证在 ~/.zeph/agent/oauth/<provider>.json（0600 权限）与 ~/.config/gcloud；zeph logout <provider> 清除已存 key / OAuth token
• 可用环境变量：ZEPH_DATA_DIR 覆盖数据目录

文档

• docs/agent-harness.md — 能力清单与决策主文档（§0–§16）
• docs/tui.md — TUI 完整契约（渲染引擎 / 组件 / 键位 / 主题）
• docs/knowledge-base.md — 内化知识库
• docs/topics/ — 专题（persistent-memory / subagents / workflow）

许可

MIT © 2026 viloris