zhi CLI 中文教程¶

zhi 是一个开源的 Python 命令行工具，由智谱 GLM 大模型驱动。安装后即可在终端中获得一个智能助手，支持对话、文件处理、OCR 识别、自定义技能等功能。

5 分钟快速入门¶

从零开始安装 zhi，配置 API 密钥，完成第一次对话。

前提条件¶

Python 3.10 或更高版本
pip 包管理器
智谱开放平台账号（用于获取 API 密钥）

第一步：安装 zhi¶

pip install zhicli

验证安装成功：

zhi --version

第二步：配置¶

运行设置向导（推荐）：

zhi --setup

向导会引导你完成三个步骤：

Welcome to zhi (v0.1.0)

Let's get you set up. This takes about 30 seconds.

Step 1/3: API Key
  Paste your Zhipu API key (get one at open.bigmodel.cn):
  > 你的API密钥

Step 2/3: Defaults
  Default model for chat [glm-5]:
  Default model for skills [glm-4-flash]:
  Output directory [zhi-output]:

Step 3/3: Quick Demo
  Want to try a sample skill? [Y/n]:

Setup complete. Type /help to see available commands.

也可以通过环境变量配置：

# Linux / macOS
export ZHI_API_KEY="你的API密钥"

# Windows (PowerShell)
$env:ZHI_API_KEY = "你的API密钥"

第三步：开始使用¶

交互模式 -- 启动 REPL：

zhi

单次提问 -- 问一个问题后退出：

zhi -c "什么是机器学习？"

运行技能 -- 用内置技能处理文件：

zhi run summarize document.txt

完成！你已经可以开始使用了。

交互式对话教程¶

进入交互模式¶

zhi

Welcome to zhi. Type /help for commands.
You [approve]:

提示符中的 [approve] 表示当前的权限模式。

查看帮助¶

You [approve]: /help

输出所有可用命令：

Available commands:
  /help              Show this help message
  /auto              Switch to auto mode (no permission prompts)
  /approve           Switch to approve mode (default)
  /model <name>      Switch model (glm-5, glm-4-flash, glm-4-air)
  /think             Enable thinking mode
  /fast              Disable thinking mode
  /run <skill> [args]  Run a skill
  /skill list|new|show|edit|delete  Manage skills
  /reset             Clear conversation history
  /undo              Remove last exchange
  /usage             Show token/cost stats
  /verbose           Toggle verbose output
  /exit              Exit zhi

权限模式切换¶

zhi 有两种权限模式：

approve 模式（默认）：执行有风险的操作（如写文件、运行 Shell 命令）时需要你确认
auto 模式：跳过确认提示，自动执行所有操作

You [approve]: /auto
Mode switched to auto

You [auto]: /approve
Mode switched to approve

Warning

Shell 命令始终需要确认，即使在 auto 模式下也不例外。这是一项不可绕过的安全特性。

切换模型¶

zhi 支持三个模型：

模型	类型	特点
`glm-5`	高级	默认对话模型，智能但较贵
`glm-4-flash`	经济	技能执行模型，快速且便宜
`glm-4-air`	经济	轻量替代方案

查看和切换模型：

You [approve]: /model
Current model: glm-5. Available: glm-5, glm-4-flash, glm-4-air

You [approve]: /model glm-4-flash
Model switched to glm-4-flash

思考模式¶

启用思考模式后，模型会展示推理过程（仅 glm-5 支持）：

You [approve]: /think
Thinking mode enabled

You [approve]: 解释为什么天空是蓝色的

You [approve]: /fast
Thinking mode disabled

多行输入¶

在行末添加 \ 可以输入多行内容：

You [approve]: 请帮我写一个 Python 函数，\
...  要求接受一个列表参数，\
...  返回列表中的最大值

管理对话历史¶

撤销上一轮对话：

You [approve]: /undo
Last exchange removed

清空所有对话历史：

You [approve]: /reset
Conversation cleared

查看用量统计¶

You [approve]: /usage

会显示当前会话的 token 用量和预估费用。

退出¶

You [approve]: /exit
Goodbye!

也可以按 Ctrl+D 退出，或按 Ctrl+C 取消当前输入。

Tip

输入历史会自动保存，下次启动可以用上下方向键浏览历史记录
包含敏感信息（如 api_key、password、token）的输入不会被保存到历史记录
Tab 键可以自动补全斜杠命令和模型名称
切换模型只影响当前会话，不会修改配置文件

文件处理教程¶

读取文本文件¶

在对话中让 zhi 读取文件：

You [approve]: 请读取 README.md 文件并总结其内容

zhi 会调用 file_read 工具读取文件内容，然后生成总结。

file_read 工具的特点：

只允许读取当前工作目录内的文件（相对路径）
单个文件最大 100KB，超出部分会被截断
自动检测编码，优先使用 UTF-8
不能读取二进制文件

列出目录内容¶

You [approve]: 列出当前目录下的所有文件

zhi 会调用 file_list 工具展示文件列表，包含文件名、大小和修改时间。

OCR 识别图片和 PDF¶

将图片或 PDF 中的文字提取出来：

You [approve]: 请识别 invoice.png 中的文字内容

You [approve]: 提取 report.pdf 中的文字并总结要点

ocr 工具支持的格式：

图片：PNG, JPG, JPEG, GIF, WEBP
文档：PDF
文件大小限制：20MB

写入新文件¶

zhi 的所有文件输出都保存在 zhi-output/ 目录中：

You [approve]: 请把刚才的总结写成一个 Markdown 文件

zhi 会调用 file_write 工具，提示你确认后（approve 模式下）写入文件。

file_write 支持多种格式：

格式	扩展名	内容格式
纯文本	`.md`, `.txt`	直接文本
JSON	`.json`	任意 JSON
CSV	`.csv`	headers + rows
Excel	`.xlsx`	sheets 数据
Word	`.docx`	Markdown 文本

示例对话：

You [approve]: 帮我创建一个 CSV 文件，包含以下三个人的信息：
张三, 25岁, 北京
李四, 30岁, 上海
王五, 28岁, 广州

zhi 会在 zhi-output/ 下创建 CSV 文件。

组合使用：读取 + 处理 + 写入¶

You [approve]: 读取 data.csv 文件，分析数据趋势，然后把分析报告写成 report.md

zhi 会依次调用 file_read 读取数据、分析内容、然后调用 file_write 生成报告。

Info

file_write 只能创建新文件，不能覆盖已有文件
所有输出文件都在 zhi-output/ 目录下，不会影响你的原始文件
路径不允许包含 ..，防止写入工作目录以外的位置
Excel (.xlsx) 和 Word (.docx) 格式开箱即用，无需额外安装

技能系统教程¶

什么是技能？¶

技能（Skill）是一组预定义的 YAML 配置，指定了系统提示词、可用工具和模型。它让你可以将常用的工作流程保存下来，一键运行。技能默认使用 glm-4-flash 模型，成本不到 GLM-5 的 10%。

内置技能¶

zhi 自带 15 个内置技能 -- 9 个单一用途技能和 6 个组合技能（将多个单一技能串联成多步工作流）。

单一用途技能（9 个）¶

技能	功能	用法
`summarize`	文档总结	`zhi run summarize report.txt`
`translate`	翻译文档（默认翻译为中文）	`zhi run translate readme-en.md`
`extract-text`	从 PDF/图片中 OCR 提取文字	`zhi run extract-text scan.pdf`
`extract-table`	从文档中提取表格数据	`zhi run extract-table invoice.pdf`
`analyze`	深度分析文档结构与内容	`zhi run analyze proposal.md`
`proofread`	语法、拼写、风格校对	`zhi run proofread draft.md`
`reformat`	文档格式转换	`zhi run reformat notes.txt`
`meeting-notes`	将原始笔记整理为会议纪要	`zhi run meeting-notes notes.txt`
`compare`	对比两份文档并标注差异	`zhi run compare v1.md v2.md`

组合技能（6 个）¶

这些技能将多个单一技能串联成多步工作流。详见下方组合技能章节。

技能	流程	用法
`contract-review`	分析 + 对比 + 校对	`zhi run contract-review contract.pdf`
`daily-digest`	目录扫描 + 批量总结	`zhi run daily-digest ./reports/`
`invoice-to-excel`	表格提取 + 格式转换	`zhi run invoice-to-excel invoices/`
`meeting-followup`	会议纪要 + 总结 + 翻译	`zhi run meeting-followup notes.txt`
`report-polish`	校对 + 分析 + 格式优化	`zhi run report-polish draft.md`
`translate-proofread`	翻译 + 校对	`zhi run translate-proofread doc.md`

查看已安装的技能¶

You [approve]: /skill list

运行技能¶

从命令行直接运行：

zhi run summarize report.txt

在交互模式中运行：

You [approve]: /run summarize report.txt

创建自定义技能¶

方式一：在对话中让 zhi 创建

You [approve]: 帮我创建一个代码审查技能，名叫 code-review，
能读取源代码文件并给出改进建议

zhi 会调用 skill_create 工具生成 YAML 配置文件。

方式二：手动编写 YAML 文件

在配置目录的 skills/ 下创建 YAML 文件。以下是一个技能配置示例：

name: code-review
description: Review source code and suggest improvements
model: glm-4-flash
system_prompt: |
  You are an experienced code reviewer. Read the provided source code
  and give actionable suggestions for improvement. Focus on:
  - Code quality and readability
  - Potential bugs
  - Performance issues
  Output your review as structured markdown.
tools:
  - file_read
  - file_write
max_turns: 10
input:
  description: Source code file to review
  args:
    - name: file
      type: file
      required: true
output:
  description: Code review report in markdown
  directory: zhi-output

技能 YAML 字段说明¶

字段	必填	说明
`name`	是	技能名称，只能包含字母、数字、连字符和下划线，最长 64 字符
`description`	是	技能描述
`system_prompt`	是	系统提示词，指导模型行为
`tools`	是	允许使用的工具列表
`model`	否	使用的模型，默认 `glm-4-flash`
`max_turns`	否	最大执行轮次，默认 15
`input`	否	输入参数定义
`output`	否	输出配置（描述和目录）

可用工具列表¶

创建技能时可以选择以下工具：

工具名	功能	风险等级
`file_read`	读取文本文件	低
`file_write`	写入新文件到 zhi-output/	高
`file_list`	列出目录内容	低
`ocr`	图片/PDF 文字识别	低
`shell`	执行 Shell 命令	高
`web_fetch`	获取网页内容	低
`skill_create`	创建新技能	高

管理技能¶

You [approve]: /skill show code-review   # 查看技能详情
You [approve]: /skill delete code-review # 删除自定义技能

Info

技能名称必须匹配 ^[a-zA-Z0-9][a-zA-Z0-9_-]*$，不允许包含空格或特殊字符
每个技能只能访问其 tools 列表中声明的工具
技能的输出默认保存在 zhi-output/ 目录
只能删除用户创建的技能 YAML 文件，内置技能受保护

Shell 命令教程¶

基本用法¶

在对话中要求 zhi 执行命令：

You [approve]: 运行 ls -la 查看当前目录

zhi 会显示即将执行的命令，等待你确认：

zhi wants to run: ls -la
Allow? [y/n]:

输入 y 允许执行，输入 n 拒绝。

三层安全保护¶

1. 始终需要确认¶

无论处于 approve 模式还是 auto 模式，Shell 命令都需要用户确认。这是 zhi 最重要的安全原则。

2. 危险命令额外警告¶

以下类型的命令会触发额外的破坏性警告：

文件删除：rm, del, rmdir
文件移动：mv
权限修改：chmod, chown
磁盘操作：mkfs, dd, shred, truncate
文件就地修改：sed -i
Git 危险操作：git reset --hard, git clean

3. 灾难性命令直接阻止¶

以下命令被永久禁止，无法执行：

rm -rf / 或 rm -rf ~
rm -rf /* 或 rm -rf ~/
mkfs /dev/...
fork 炸弹等恶意命令
dd if=/dev/zero of=/dev/...

命令超时¶

Shell 命令默认超时 30 秒，最长可设置为 300 秒（5 分钟）。超时后 zhi 会终止整个进程组，确保不会有遗留进程。

输出限制¶

命令输出最大显示 100KB，超出部分会被截断并提示。

实用示例¶

You [approve]: 查看系统的 Python 版本

You [approve]: 统计 src/ 目录下有多少行代码

You [approve]: 运行 pytest 测试并告诉我结果

Warning

永远不要让 AI 运行你不理解的命令，即使 zhi 会请求确认。跨平台支持：在 Windows 上使用 CREATE_NEW_PROCESS_GROUP，在 Unix 上使用 start_new_session。

Web 内容获取教程¶

获取网页内容¶

You [approve]: 获取 https://example.com 的内容

zhi 会调用 web_fetch 工具抓取页面内容，自动将 HTML 转换为纯文本。

分析网页内容¶

You [approve]: 获取这个网页的内容并总结要点：https://example.com/article

zhi 会先获取内容，然后基于 GLM 模型进行分析。

获取并保存¶

You [approve]: 抓取 https://example.com/data 的内容，提取关键数据，保存为 CSV 文件

zhi 会组合使用 web_fetch 和 file_write 工具完成任务。

在技能中使用¶

可以创建包含 web_fetch 的技能，自动化网页内容处理：

name: web-summary
description: Fetch and summarize web pages
model: glm-4-flash
system_prompt: |
  Fetch the given URL, read the content, and produce a concise
  summary in Chinese. Save the summary as a markdown file.
tools:
  - web_fetch
  - file_write
max_turns: 5

然后运行：

zhi run web-summary

Info

URL 必须以 http:// 或 https:// 开头
请求超时时间为 30 秒
响应内容上限为 50KB，超出部分会被截断
HTML 页面会自动去除标签，转换为纯文本
web_fetch 会自动跟随重定向
内置 SSRF 防护

组合技能¶

组合技能将多个单一技能串联成自动化的多步工作流。它们同样使用 glm-4-flash 模型，保持低成本。

contract-review（合同审查）¶

流程： analyze + compare + proofread

从三个角度审查合同文档：结构分析以识别关键条款和风险，可选的版本对比以标注变更内容，以及校对以发现模糊措辞。

# 审查单份合同
zhi run contract-review contract.pdf

# 对比两个版本
zhi run contract-review contract-v2.pdf contract-v1.pdf

输出： 一份全面的审查报告，包含执行摘要、结构分析、版本变更（如适用）、语言问题、风险评估和谈判建议。

daily-digest（每日摘要）¶

流程： file_list + summarize（批量）

扫描文件夹中的所有文档，生成一份包含各文档摘要和跨文档洞察的综合摘要报告。

zhi run daily-digest ./inbox/

输出： 摘要报告列出每份文档的总结、共同主题、矛盾之处和建议的后续行动。

Tip

支持的文件类型包括 .txt、.md、.pdf、.csv、.docx、.xlsx、.png 和 .jpg。二进制文件和系统文件会被自动跳过。

invoice-to-excel（发票转 Excel）¶

流程： extract-table + reformat

通过 OCR 表格提取处理发票文件（PDF、图片或文本），然后将所有明细项整合到结构化的 Excel 表格中。

# 单张发票
zhi run invoice-to-excel invoice.pdf

# 批量处理发票文件夹
zhi run invoice-to-excel ./invoices/

输出： 一个 Excel 文件，包含两个工作表 -- "Line Items"（所有发票的逐行明细）和 "Invoice Summary"（每张发票的汇总）。日期统一为 YYYY-MM-DD 格式，货币符号已清理，总额已验证。

meeting-followup（会议跟进）¶

流程： meeting-notes + summarize + translate

接收原始会议笔记，生成完整的会后跟进材料包：结构化的会议纪要、供领导参阅的执行摘要，以及可选的翻译版本。

# 基本跟进
zhi run meeting-followup raw-notes.txt

# 附带翻译
zhi run meeting-followup raw-notes.txt --to english

输出： 三个文件 -- 完整的会议纪要、1 页执行摘要，以及（可选的）翻译版摘要。待办事项同时出现在完整纪要和摘要中。

report-polish（报告润色）¶

流程： proofread + analyze + reformat

接收草稿文档，通过语言校对、结构分析和格式优化，输出可发布的终稿。

zhi run report-polish draft-report.md

# 指定输出格式
zhi run report-polish draft.md --format docx

输出： 两个文件 -- 润色后的文档和一份修改日志，包含修改前后的质量评分、所有修正内容、结构改进和剩余建议。

translate-proofread（翻译校对）¶

流程： translate + proofread

翻译文档后对译文进行校对，确保译文在目标语言中读起来自然流畅。

# 默认翻译为中文
zhi run translate-proofread article-en.md

# 指定目标语言
zhi run translate-proofread article.md --to english

输出： 两个文件 -- 校对后的最终译文和一份质量报告，包含检测到的源语言、翻译质量评分、发现并修正的问题，以及可能需要人工审核的段落。

附录¶

管道模式¶

可以通过管道将文本输入 zhi：

echo "翻译成英文：你好世界" | zhi

cat article.txt | zhi

调试模式¶

如果遇到问题，启用调试日志：

zhi --debug

禁用颜色输出¶

在不支持颜色的终端中：

zhi --no-color

或设置环境变量：

export NO_COLOR=1

配置文件完整参考¶

配置文件位于系统配置目录下的 config.yaml：

api_key: "你的API密钥"
default_model: "glm-5"
skill_model: "glm-4-flash"
output_dir: "zhi-output"
max_turns: 30
log_level: "INFO"

配置文件位置：

macOS: ~/Library/Application Support/zhi/config.yaml
Linux: ~/.config/zhi/config.yaml
Windows: %APPDATA%\zhi\config.yaml

支持的环境变量覆盖：

环境变量	对应配置项
`ZHI_API_KEY`	`api_key`
`ZHI_DEFAULT_MODEL`	`default_model`
`ZHI_OUTPUT_DIR`	`output_dir`
`ZHI_LOG_LEVEL`	`log_level`

环境变量 ZHI_API_KEY 的优先级高于配置文件。

常见问题¶

Q: 提示 "No API key configured"

运行 zhi --setup 或设置环境变量 ZHI_API_KEY。

Q: 文件写入失败提示 "File already exists"

file_write 不能覆盖已有文件。删除或重命名 zhi-output/ 中的同名文件后重试。

Q: OCR 识别结果为空

确认文件格式受支持（PDF, PNG, JPG, JPEG, GIF, WEBP）且文件大小不超过 20MB。图片清晰度会影响识别效果。

Q: Shell 命令被阻止

某些危险命令（如 rm -rf /）被永久禁止。这是安全特性，无法绕过。

Q: 想用 Excel/Word 输出但报错

Excel (.xlsx) 和 Word (.docx) 已包含在默认安装中。请确认安装了最新版本：pip install --upgrade zhicli。