安装与启动

系统要求

获取安装包

安装步骤

macOS

1. 双击 .dmg 文件。
2. 将 ZhiShi.app 拖到「应用程序」文件夹。
3. 从启动台打开。首次可能需在「系统设置 > 隐私与安全性」中允许打开。

Windows

1. 双击 .exe 按向导安装。
2. 或解压 .zip 便携版，双击 ZhiShi.exe 运行。
3. 如杀毒软件拦截，将安装目录加入信任列表。

Linux

1. AppImage：赋予执行权限后直接运行。
2. Debian/Ubuntu：sudo dpkg -i ZhiShi_*.deb 安装。

首次启动

首次打开时，ZhiShi 会自动完成初始化：解压运行环境、创建本地配置目录 ~/.zhishi/、加载默认 Agent 和技能。初始化完成后会看到启动页。

启动页包含：最近会话、工作区列表、新建会话、任务中心和设置入口。

启动失败处理

1. 检查系统要求和磁盘空间。
2. 检查权限（Windows 以管理员运行，macOS 允许打开）。
3. 检查杀毒软件是否拦截。
4. 查看 ~/.zhishi/logs/ 日志。
5. Windows：任务管理器结束 node.exe / zhishi.exe 后重试。

快速开始

第一步：配置 AI Provider

1. 启动 ZhiShi，进入启动页。
2. 点击左下角「设置」或按 Ctrl/Cmd + ,。
3. 选择「模型服务」，点击你要使用的 Provider。
4. 输入 API Key，可选修改 Base URL。
5. 点击「验证并保存」。启用后返回列表确保开关已开启。

第二步：创建或选择工作区

回到启动页，在工作区区域点击「添加工作区」或选择一个已有工作区。Agent 会默认把工作区当作当前项目目录。

第三步：新建会话

在启动页点击「新建会话」，选择要使用的 Agent，进入会话界面。

第四步：发送第一条消息

在输入框中输入：

请帮我查看当前工作区的文件结构，并告诉我主要目录的用途。

按 Enter 发送，Agent 会自动读取工作区并返回结果。

第五步：尝试具体任务

• 分析代码：请阅读 README.md 并总结主要内容。
• 运行命令：请运行 npm run typecheck，并总结结果。
• 处理文档：请从 report.pdf 中提取所有表格并保存到 output.xlsx。
• 浏览器自动化：请打开 example.com，截图首页，提取页面标题。

常用快捷键

接入 AI 服务

Provider 是 AI 服务提供商的接入配置。ZhiShi 内置 16 个 Provider 预设，覆盖国内外主流 AI 服务。

支持的 Provider

配置 Provider

1. 打开「设置 > 模型服务」。
2. 点击目标 Provider 卡片。
3. 输入 API Key，可选修改 Base URL。
4. 点击「验证并保存」。

验证状态会缓存 30 天。可以同时配置多个 Provider，通过拖拽调整优先级。

自定义 Provider

如果不在预设列表中，可以添加自定义 Provider，需填写：供应商名称、API 协议（Anthropic 或 OpenAI）、Base URL、认证方式、模型列表等。

会话与 Agent

会话界面概览

ZhiShi 的会话界面分为三个主要区域：

• 左侧边栏：会话列表、任务中心、搜索、设置入口。
• 中间对话区：显示你和 Agent 的消息流。
• 右侧面板：文件预览、终端、浏览器、上下文文件、工具调用记录。

与 Agent 对话

直接描述你要做的事。Agent 会理解需求，并决定读取哪些文件、调用哪些工具、运行哪些命令。

请帮我分析 src/server/index.ts 这个文件，说明它的主要功能和潜在问题。

请打开 https://example.com，截图首页，并提取导航栏链接。

输入框功能

• 附件上传：拖拽文件、粘贴图片、@ 引用工作区文件。
• / 命令：/compact 压缩上下文、/cost 查看消耗等。
• 底部工具栏：Runtime 选择、权限模式切换、MCP 工具管理、模型切换。

权限模式

消息操作

Agent 消息支持：复制、导出 Markdown、重试、分支。代码块支持语法高亮、一键复制、行号。

记忆与搭子

ZhiShi 有一套后台记忆系统，让 Agent 在对话之外也「记得」你们怎么一起干活：

• 记忆整理员：后台每小时把最近的工作史整理成几类认知——它眼中的你、它眼中的自己、你们的老规矩、该提醒你的事。你纠正过它的事，它会记住教训。
• 想法流：启动页输入框上方浮出「它想起的」——上次在哪栽过、临近的期限（每条附来源）。点「聊聊」接住、点「划走」推开。
• 信任账本：被验证的完成累计信任分，返工/否决扣分；跨阈值时建议升级权限，采纳与否由你决定。
• 记忆检索：Agent 可以在对话中按关键词翻你的长期记忆（zhishi memory search '<关键词>'）。检索被引用后系统会判断这条记忆用对没有——用对加分、被你纠正就重罚、一直没用上就随时间淡化。

记忆与人格都在本地（~/.zhishi/memory.db），不会上传云端。搭子页详见「设置 > 搭子」。

本地文件处理

Agent 可以直接读取和编辑你电脑上的文件，覆盖常见类型：

所有操作默认限制在当前工作区内，敏感写入/删除操作会请求确认。Office / PDF 处理由 docx、xlsx、pptx、pdf 等技能提供，详见 能力 章节。

聊天机器人 Bot

ZhiShi 可以把 Agent 接入即时通讯平台，让你在 IM 里直接和它对话：

• 内置平台：Telegram、钉钉。
• 官方推广插件：飞书、QQ、企业微信、微信（OpenClaw 插件）。
• 社区插件：从插件市场浏览更多 Bot 平台。

如何添加聊天机器人

聊天机器人以渠道（Channel）的方式挂载在 Agent 上，以下是两种添加方式。

方式一：将已有工作区升级为主动型智能体

适合已经有项目文件夹、想为其增加 IM 聊天能力的场景。

1. 在启动页找到目标工作区，hover 出现设置按钮，点击进入 Agent 设置。
   
2. 在「通用」Tab 找到「主动智能体模式」，打开开关。
   
3. 开启后出现「聊天机器人频道」，点击「+ 添加」选择平台并配置凭证。
   

方式二：创建全新的智能体工作区

适合从零开始、专门为聊天机器人创建一个独立 Agent 的场景。

1. 在启动页点击「+ 添加」，选择「添加本地文件夹」或「从模板创建智能体」，创建完成后按方式一开启主动模式并添加聊天机器人。
   

绑定会话

在会话菜单选「绑定聊天机器人」可把会话绑定到某个 Bot 频道——之后该频道发的消息会进这个会话。

Bot 支持私聊和群聊，可发送图片、文件等多媒体内容。

能力（技能 / 插件 / 工具扩展）

「能力」是设置页的一个分区（设置 > 能力），聚合了三个子页：技能 / 插件 / 工具扩展（MCP）。

技能 Skills

技能是 ZhiShi 的专业能力模块，可以理解为 Agent 的「专业技能书」。当 Agent 遇到复杂任务时，它会查找并调用合适的 Skill，按照其中定义的流程和工具执行。

内置 Skills

安装自定义 Skill

• 从 URL 安装：让 Agent 执行安装命令。
• 从本地文件夹导入：设置 > 能力 > 技能。
• 从 Claude Code 同步。
• 自己编写：Markdown + YAML Frontmatter 格式。

Skill vs MCP

插件 Plugins

用于管理 Claude 插件（设置 > 能力 > 插件）。一个插件可以包含 Skills、子智能体、Hooks、MCP。

• 安装插件：通过 GitHub 链接，或本地文件夹（file:// 路径）。
• 查看 / 启用 / 禁用 / 卸载：控制插件在各工作区是否可见。

插件开关只决定插件在工作区是否可见。要在会话中实际启用，需在 Agent 设置或会话工具菜单中勾选。

加密插件（.zsp）

ZhiShi 支持把插件打包成加密签名的 .zsp 文件分发——保护分发渠道与授权使用，没有有效许可串无法安装。

• 制作（作者）：zhishi plugin init / pack / keygen / verify，纯本地运行，app 不开也能用。
• 安装（用户）：拖入 .zsp + 粘贴 ZSP1- 许可串即激活——无服务器、无到期、永久离线。
• 向导：在对话里说「帮我做个插件」，内置 plugin-assistant 技能带你走完全流程。

工具扩展（MCP）

用于管理 Model Context Protocol（MCP）工具（设置 > 能力 > 工具扩展），把 Agent 的能力扩展到外部服务。

内置 MCP 预设

添加自定义 MCP

• 名称与类型：stdio / sse / http。
• stdio：命令、参数、环境变量；http / sse：URL、请求头、OAuth 配置。
• JSON 导入 MCP 配置；发现更多 MCP：MCP.SO、智谱 MCP。

Terminator 桌面自动化（AppCraft）

Terminator 桌面自动化（AppCraft 的基础）是内置的 Windows 桌面 UI 自动化 MCP——用 UIA 语义定位控件（不抢鼠标、抗窗口移动），适合操作原生应用；与 Cuse 视觉通道互补。启用后可以让 Agent 操作电脑上的桌面应用（如 Excel、微信、内部工具），把重复流程沉淀成可复用的自动化：

• 录制：让 Agent 操作一次应用，操作被捕获成 trace。零配置——不需要预先绑定应用。
• 沉淀：完成后问「这个以后还会做吗？存成 skill？」——确认后沉淀成技能，下次直接调用。
• 回放：之后让 Agent 按 skill 自动执行同样的操作。
• 失败自动顺接：回放遇预期外的界面时，若该步骤允许 AI 接管，Agent 自动带技能知识续跑，把新踩的坑整理成「已知坑」——先确认再写入。

CLI：zhishi appcraft list（查看）、zhishi appcraft record start/stop（录制）、zhishi appcraft replay <名称> [--var 键=值] [--yes-high-risk]（回放）。高危步骤（删除/提交/外发）回放时会先拦下等你确认。

沉淀、顺接、审批都只提议、不自动——是否执行由你确认。高危操作始终需要批准。

任务中心

任务中心用于保存可重复执行的工作流程。打开方式：Ctrl/Cmd + Y。界面分左右两栏：左侧是想法（Thought），右侧是任务列表。

想法（Thought）

想法是任务中心的基础单元，用来快速记录灵感、待办。创建后在左侧面板输入内容，可用 #标签 分类。

每个想法支持：

• 智能体讨论：打开新会话与 Agent 讨论这个想法（「捡起聊」）。
• 派发为任务：把想法转化为正式任务。
• 已派发互链：派发后想法卡显示「已派发 → 任务名」，点击跳到任务；任务详情也标注「来自想法」——双向可溯。
• 编辑 / 删除 / 归档 / 批量操作。

启动页输入框上方还会浮出「它想起的」想法流——那是搭子主动提起的（上次在哪栽过、临近的期限），点「聊聊」接住、点「划走」推开。

创建任务

• 手动新建：填写任务名称、工作区、task.md、执行模式等。
• 从想法派发：在左侧 Thought 面板中将想法转化为任务。
• 从会话创建：让 Agent 通过工具调用创建定时任务。

执行模式

Cron 常见示例

任务状态

待启动 → 进行中 → 验收中 → 已完成。也支持已阻塞、已暂停、已归档等状态。

本地搜索

ZhiShi 内置全文搜索，可以快速查找电脑中的文件内容和历史会话。

使用方式

• 全局搜索：按 Ctrl/Cmd + K，输入关键词。
• 在会话中搜索：让 Agent 帮你搜索，如 请搜索项目中所有用了 useAuth 的文件。

搜索语法

配置索引

在设置中可配置索引目录、排除规则（建议排除 node_modules/、.git/、dist/ 等）、索引更新方式。

终端与浏览器

内嵌终端

Agent 可直接在终端中执行命令。按 Ctrl/Cmd + Shift + ` 打开终端面板。

• 读取类命令自动执行（如 ls、cat）。
• 写入/删除类命令需要确认（默认行动模式）。

AI 驱动的可见面板

AI 干活时打开的内嵌终端和浏览器是你看得见的——操作过程全程可见，你可以随时接手：

• 终端：适合跑 dev server、实时编译这类要一直运行的长任务，输出实时可见，你随时能接手敲命令。
• 浏览器：用你本机的登录态（已登录的网站不用重新登录），它点了哪里、填了什么，整个过程你都看着。

在对话里说「在右边的终端里跑一下 dev server」或「用浏览器帮我打开这个页面操作一下」即可。

浏览器自动化

通过 agent-browser Skill 和 Playwright MCP 支持：打开网页、填表、截图、数据提取、模拟手机浏览器。

请打开 https://example.com，截图首页。

MCP 工具与桌面应用自动化（Terminator）的完整说明见 能力 章节。

常用设置

设置页（Ctrl/Cmd + U）分为 9 个分区：

搭子

「搭子」是 ZhiShi 的全局人格——出厂自带一个灵魂，任何工作区都是同一个它。这里是它的档案视图，不是配置表单。

• 身份 / 人格：它是谁、怎么说话做事——灵魂只能生长，不能换芯。
• 它眼中的你：它对你的认知，由后台从你们共同的工作史里维护，不可手编。
• 生长记录：信任分、记忆条数、最近学到的。

桌面搭子 Novo（有身体）

常驻桌面右下角的像素水獭，状态全部来自真实后端：呼吸=活着、干活帧=任务执行中、红点=有事等你、气泡=交付验收/定时预告/想起事、蔫了=你离开较久。点球回主窗，双击记想法，拖文件给它进会话。

通用设置

快捷键

更新与卸载

自动更新

ZhiShi 支持自动检查更新。也可手动在「设置 > 关于&反馈」中点击「检查更新」。

数据备份

更新或卸载前建议备份 ~/.zhishi/ 目录，包含配置、会话历史、任务、索引、自定义 Skills。

卸载

• macOS：将 ZhiShi.app 移到废纸篓。
• Windows：在设置中卸载，或直接删除便携版目录。
• Linux：删除 AppImage 或 sudo dpkg -r ZhiShi。

可选删除本地数据 ~/.zhishi/——会清除所有配置和数据。

常见问题

安装与启动

• 安装后无法打开？ macOS 检查安全性设置，Windows 以管理员运行或检查杀毒软件。
• 首次启动卡住？ 检查磁盘空间和网络，查看日志。
• Windows 提示文件被占用？ 结束 node.exe / zhishi.exe 进程后重试。

API Key 与模型

• API Key 无效？ 检查复制是否完整、有无空格、账户是否有额度。
• Agent 不回复？ 检查网络、API 额度、Provider 是否启用。
• 模型列表为空？ 重新验证 API Key。

文件与权限

• 无法读取文件？ 确认文件在工作区内。
• 写入前总是询问？ 可在权限模式中切换为「自主行动」。

功能使用

• Skill 没有触发？ 确认已启用该 Skill。
• MCP 没有响应？ 确认已在设置中启用。
• 定时任务未执行？ 确认 ZhiShi 保持运行，检查任务的执行方式设置（间隔 / 到点一次）。

性能问题

• 运行很慢？ 关闭不必要的标签页，减少索引范围。
• 内存占用高？ 长会话会累积上下文，尝试 /compact 压缩。

需求单与反馈

ZhiShi 内置需求单功能，可通过「设置 > 关于&反馈 > 我的需求单」提交问题、建议或开发需求。

提交需求单

1. 进入「设置 > 关于&反馈 > 我的需求单」。
2. 点击「提交需求单」。
3. 填写标题、类型（问题/建议/其他）、描述，可选上传附件。
4. 点击提交。

需求单状态

待处理 → 处理中 → 已回复 → 已解决 → 已关闭

建议提供的信息

• 问题具体描述和复现步骤
• 期望结果与实际结果
• 应用版本号和操作系统版本
• 相关截图和日志（通过「设置 > 通用设置 > 运行日志」导出）