使用指南

FOR RESEARCHERS — 安装 · 环境 · 模型 · TUI · 引擎 · 情报

面向研究员的使用手册。从这里开始：安装 → 选环境 → 配模型 → 开始研究。

01安装与启动

发行包（Windows）

下载安装包 ZhiShi_<版本>_x64-setup.exe（NSIS）安装，或便携 ZIP 解压即用。安装后开一个终端：

zhishi agent

TUI 启动，zhishi 命令已同步到 ~/.zhishi/bin/。Tauri 壳在后台负责引擎（sidecar）生命周期，无需手动起服务。

源码运行（开发态）

要求 Node.js ≥ 22：

npm install

# 终端 1：sidecar（引擎 + admin API）
node --import tsx/esm src/server/index.ts --agent-dir "$PWD"

# 终端 2：TUI（先 set ZHISHI_PORT=3000 指向 sidecar 端口）
node --import tsx/esm src/cli/zhishi.ts agent

退出

TUI 空闲时 Ctrl+C 退出；/quit 退出会话界面。发行包退出 TUI 后后台壳仍在（托盘可退出）；源码运行时退出 sidecar 进程即可。

02第一次使用：正门与环境

TUI 启动即进正门——强制选择本次会话的工作环境（没有「宿主机模式」，研究只发生在环境里）：

已登记环境：直接选中，未运行会尽力拉起（VM 会按快照约定恢复）。
本机已有（未注册）：自动发现宿主机上的 Docker 容器与 VM，选中即登记。
新建环境（选类型）：从内置环境类型新建——dev（开发）、pwn / pwn-vm（二进制利用）、fuzz / fuzz-vm（模糊测试）、rev（逆向）、code-audit（白盒审计）、pentest（渗透）、ai-security（AI 安全）。docker 类型需要本机 Docker；VM 类型需要 VMware/Hyper-V 等。
手动接入 SSH 主机：已有机器走三步表单（host / 用户 / 密钥路径）。

两条铁律

1. 创建权在人——环境只能由人创建/纳管，agent 不会自建环境。

2. 环境类型绑定能力——选了哪个类型的环境，agent 就用那套工具。

03环境管理

CLI 命令

zhishi env recipes                              # 内置环境类型清单
zhishi env up pwn-vm                            # 从环境类型建环境（首次构建需几分钟）
zhishi env adopt pwn-vm --vm <vmx路径> --user <用户>   # 纳管已有 VM
zhishi env list                                 # 已登记环境
zhishi env ps                                   # 运行中实例

TUI 命令

命令	作用
`/env`	重新选择工作环境
`/snapshot [名]`	给当前环境打快照
`/rollback <快照名>`	回滚到快照
`/attach`	接管环境 shell（TUI 挂起，exit 返回）
`/extract <环境内路径>`	回收环境内文件到宿主

VM 类型环境的快照约定：每次 env up 回到 zhishi-clean 干净快照——环境脏了不用收拾，回滚重来。

04模型配置

内置 8 家供应商，填 key 即用，不用配端点：

供应商 id	说明	格式
`deepseek`	DeepSeek	anthropic 兼容
`kimi`	Kimi（pi 内置通道）	内置
`openai`	OpenAI	OpenAI
`moonshot`	Kimi（Moonshot 开放平台）	OpenAI
`dashscope`	通义千问	OpenAI
`zhipu`	智谱 GLM	OpenAI
`siliconflow`	硅基流动（聚合平台）	OpenAI
`anthropic-api`	Anthropic	anthropic

CLI 配置

zhishi model list                                # 各家状态与模型
zhishi model set-key deepseek <apiKey>           # 保存 key（自动拉取模型列表）
zhishi model verify deepseek                     # 验证 key 可用
zhishi model set-default deepseek deepseek-v4-pro   # 设置默认模型

TUI 配置（不用退出去）

/model                              状态卡：各家 key 状态/当前默认/模型数
/model set-key <供应商id>           隐藏输入填 key（不回显）→ 自动拉列表
/model use <供应商id> <模型名>      切换模型（下一轮对话生效）
/model <模型名>                     快速切换（旧语法）

主力供应商配额耗尽（如 403）时，另一家已配 key 的供应商可随时 /model use 切过去——模型可换，harness 不变。

05TUI 操作大全

斜杠命令

命令	作用
`/env`	重新选择工作环境
`/attach`	接管环境 shell（TUI 挂起）
`/snapshot [名]` / `/rollback <名>`	环境快照 / 回滚
`/extract <环境内路径>`	回收环境内文件到宿主
`/model ...`	模型配置/切换
`/mcp [enable\|disable <id>] [-r]`	MCP 状态/开关/刷新
`/rewind`	回退到历史消息（改完重发）
`/fork`	从某条消息分叉出新线程
`/queue`	查看/取消排队消息
`/reset`	重置对话（新会话）
`/help`	键位与命令帮助
`/quit`	退出会话界面

键位

键	作用
`Enter`	发送；turn 进行中发送 = 纠偏注入
`Ctrl+J` / `Alt+Enter`	多行输入
`↑` / `↓`	历史消息（输入为空时）
`Ctrl+R`	历史搜索
`Esc`	中断 turn / 关闭面板 / 回到底部
`Ctrl+Z`	回退到历史消息（rewind）
`Ctrl+O`	展开/收起最近工具输出
`Ctrl+L`	开关帮助
`PgUp` / `PgDn`	回看会话（输入永不锁）
`Tab`	补全 / `@` 引用
`Ctrl+C`	清空输入；空输入时中断；空闲时退出
`/`	命令面板
`@`	引用环境 / 文件

读屏幕

工具卡：agent 每步动作一张卡，折叠后只留关键信号（exit 码 / 崩溃 / flag / CVE / 端口）。Ctrl+O 展开。
后台任务：状态行显示长驻进程（⛁ fuzz · 跑着），退出时插行。
越界模态：红色框 = agent 要做跨界动作，逐次问人——没有「永远允许」。
中断五档：Esc 停止 · 运行中输入即纠偏 · Ctrl+Z 回思路 · /rollback 回环境 · /attach 接管 shell。

06引擎能力：四个工具

工具	做什么	使用时机
`env_exec`	在环境内执行一条命令，等它返回（exit/stdout/stderr）	短命令：查事实、编译、跑 exp
`env_bg`	后台长驻进程：start / poll / log / kill / list	预计超 30 秒的命令：长扫描、fuzz、监听
`delegate_task`	派子任务给专用子代理，结论回注主循环	独立子目标，避免污染主上下文
`research_log`	研究留痕（成败/漏洞类型/一句话结论）	拿到 flag / 确认根因 / 放弃时落一条

人机关系：边界之内 agent 全自动推进；跨越边界（写宿主/动凭据/改网络/销毁有成果环境）才停下来问。人只做授权官，不做驾驶员。

长任务纪律：长命令走 env_bg——env_exec 一次性等返回，堵住它会拖死本轮。布置任务时可以直接说「这个用后台跑」。

07情报检索

本地情报索引（CVE / exploit / nuclei 检测模板），agent 用 intel_search 查，人用 CLI 管：

zhishi intel update                     # 更新索引（默认 minimal 档）
zhishi intel update --mode window       # 近 3 年（约 150-230MB）
zhishi intel update --mode full         # 全量（约 300MB，按 maxSizeMb 自裁）
zhishi intel update --nuclei-file <本地cves.json>   # 网络不通时手动导入
zhishi intel status                     # 索引状态与水位

更新有实时进度（⏳ 已入库 N 条），可中断续传；数据源失败自动多源切换。
agent 在复现/验证漏洞前会主动查情报（受影响版本、CVSS、公开 exploit、nuclei 检测模板）——情报是线索不是结论。

08研究留痕与记忆

研究关键节点 agent 通过 research_log 落一条成败信号（任务类型 / 成败 / 漏洞类型 / 一句话结论）：

zhishi research list                    # 研究记录
zhishi research log ...                 # 手动补记

记录定期按研究域蒸馏成经验（不跨域混压，置信度分级），逐轮反喂进系统提示——研究做得越多，下一次越少走弯路。死路与突破口在上下文压缩中永不裁剪。

09MCP 服务器

扩展 agent 的工具面。配置走 CLI，开关走 TUI：

zhishi mcp add <npm-spec | GitHub URL | 本地路径>   # 添加（含 OAuth 流程）
zhishi mcp list                                      # 清单
zhishi mcp enable <id> / disable <id>                # 启用/停用

TUI 内：/mcp 看状态，/mcp enable|disable <id> 开关（桥热重载即刻生效），/mcp -r 刷新。MCP 工具在会话里以 mcp__<server>__<tool> 命名，与内置工具同受边界规则管辖。

10常见问题

环境连不上 / 认证失败

VM：确认 guest 里 sshd 在跑、端口 22 可达；公钥不通时 zhishi env adopt 会提示现场输入 guest 密码（不落盘）。网络层问题优先查本机到 guest 的连通性。

模型报 403 / 配额不足

换一家已配 key 的供应商：TUI 里 /model use <供应商> <模型>，或 CLI zhishi model set-default。

intel update 慢 / 失败

首次回填 NVD 数据量大（window 档约 15 万条），受速率限制，1 小时级耗时正常——断点续传，中断重跑接着来。数据源网络不通时：宿主机 curl 下载 nuclei 的 cves.json，用 --nuclei-file 导入。

TUI 输入看起来「卡住」

turn 进行中：输入会排队注入（不是丢）；Esc 中断，/queue 看排队。长任务无响应：确认任务是否该走 env_bg。

后台进程去哪了

turn 结束/会话重置时，后台长驻进程会被回收杀掉（当前策略）；要长跑跨会话的任务，用环境内托管方式（见 docs/env-bg-design.md 的后续方向）。

zhishi 执失 · Security Research Lab · v1.1.5 · 内容源：仓库 docs/user-guide.md