Voki办公 / docs

DOCUMENTATION / v1.0.0 BETA

文档

从安装、企业登录、连接模型到扩展 Harness：这里汇总 Voki办公 的核心概念、上手步骤和常见问题。 本页内容随站点一起发布，不依赖外部仓库。

适用于 v1.0.0 Beta（构建 0.24.0） ·macOS / Windows / Linux ·最后更新 2026-10-25

概览

Voki办公 是一个可私有化部署、本地优先的企业级 AI 桌面工作台。它把项目、 会话、智能体、模型、Harness 扩展与工作流放进同一个长期可用的桌面环境， 而不是依附于某个终端或编辑器。

LOCAL FIRST

数据留在本机

项目、会话、设置和日志保存在本地；API Key 进入操作系统钥匙串，而不是明文文件。

MODEL FREEDOM

模型随时可换

云端模型、本地模型、自建网关和兼容 API 都可以接入；不同会话可以使用不同模型。

HARNESS EXTENSIBLE

能力由 Harness 扩展

原生工具、Skills、MCP、子智能体与插件可以接成完整业务工作流，无需改造客户端核心。

ENTERPRISE READY

企业可私有化部署

客户端运行在企业终端，登录、模型网关与更新源可指向企业自有环境；企业 SSO 统一身份，权限与审批由 IT 管理。

EXTENSION DRIVEN

工作台由扩展组装

命令、面板、悬浮窗、智能体工具、技能、主题、MCP 和常驻服务都可以由扩展提供。

ORCHESTRATION

一个智能体不够就拆开做

子智能体承担后台任务；Worker 会话拥有独立上下文，可以并行工作并逐一检视。

进程与职责

Renderer（React 界面） │ Preload IPC Electron Main（窗口、菜单、进程编排） ├── Rust Host Core（SQLite、文件、权限、插件宿主） └── Node Agent Runtime（智能体循环、模型调用）
  • 界面只负责展示与交互，不直接访问 SQLite。
  • Host Core 拥有持久化、项目沙箱、权限网关和本地能力。
  • 插件入口运行在独立 Node 进程；插件面板运行在隔离窗口中，通过权限网关调用宿主 API。

当前版本：v1.0.0 Beta 基于 0.24.0 构建。Beta 期间部分接口与桌面能力仍会演进， 但已可用于真实的开发工作流。

快速开始

  1. 下载并安装

    在 下载页 选择 macOS、Windows 或 Linux 安装包。 系统要求：macOS 11+、Windows 10+，或 glibc 2.35+ 的 Linux 发行版。

    macOS 版本已签名并公证；首次打开使用 Voki 账号登录，企业环境由管理员配置企业 SSO。

  2. 连接模型

    登录后默认接入账号模型网关，可直接开始工作。打开 设置 → 模型 / 提供商 还可以选择其他内置提供商或添加兼容 OpenAI 的接口， 也可以接入 Ollama、LM Studio、本地模型或企业自建网关。

    密钥由宿主写入操作系统钥匙串。自定义接口可以配置为无需 API Key， 此模式不会发送认证信息。

  3. 创建项目与会话

    在首页创建项目并选择本地文件夹；也可以创建 SSH 项目项目，直接浏览远程目录。 新建会话后，按任务选择 Agent、Plan 或 Goal 模式。

    项目文件保留在原位置，Voki办公 不会把整个仓库复制进应用数据目录。

  4. 处理权限与提问

    智能体调用工具、读写文件或运行命令前会请求授权。 可以逐次允许、拒绝，或在当前会话内放行。

    AskTool 会把需要澄清的问题变成可操作的卡片；长时间无人操作时， 未回答的问题会被跳过，以免任务永久等待。

  5. 按需扩展

    从 插件市场、技能市场 或 连接器市场 添加扩展。 需要自己编写插件时，从 插件开发 开始。

登录后本地可用：完成首次登录后，应用启动、项目管理、会话记录和本地文件 操作不依赖网络；模型请求与显式配置的外部服务仍需网络。

核心概念

概念说明
Project 一个项目，对应本地文件夹或 SSH 远程目录。项目拥有自己的会话、文件与设置。
Session 一次完整的对话与执行记录，包含消息、工具调用、审批、产物和上下文用量。
Agent 模式 直接执行任务：读代码、改文件、运行命令、测试并迭代。
Plan 模式 先给出方案并等待确认，适合重构和高风险变更。
Goal 模式 定义结果与验收标准，由智能体自行选择执行路径。
Subagent 由主会话委派的后台智能体，拥有独立上下文，可在完成后汇报。
Worker Session 由父会话协调的完整会话，适合长期、并行、需要单独检视的工作。
Plugin 扩展智能体、工作空间或平台的打包单元；可以同时贡献多种能力。
Skill 由智能体按需加载的指令文档，用来固化可复用的工作方法。
MCP 通过 Model Context Protocol 接入本地或远程工具服务器。
Remote Host 通过 SSH 配对的远程主机；桌面端可以协调远端项目与升级。
Mobile 手机端远程控制桌面会话：查看进度、处理审批、追加指令并验收交付物。

会话之间如何协作

一个主会话可以委派子智能体，也可以创建多个 Worker 会话。 每个 Worker 都有独立上下文和完整记录，主会话负责委派、监控与合并。 这样复杂任务不会被塞进单一上下文窗口。

随时切换模型：会话内可以切换模型与推理等级；规划、编码、评审和 隐私任务可以分别使用不同模型，而不改变工作流。

Harness 与扩展

Harness 是智能体的执行层。扩展不是“给智能体多加一个工具”的附属功能： 一个扩展可以同时提供界面、后台服务和智能体能力，把企业系统组合成完整业务界面。

AGENT

扩展智能体

智能体工具、技能、一次性补全、pi 扩展。

WORKSPACE

扩展工作空间

命令、面板、工作面板视图、悬浮小组件、主题、渲染插槽。

PLATFORM

扩展平台

MCP 服务器、常驻服务、插件消息总线、OAuth 提供方。

TRUST

权限边界

入口代码在独立进程中运行，面板在隔离窗口中运行；宿主 API 统一经过权限网关。

从哪里开始

  • 浏览 插件市场，查看已有插件的权限与 README。
  • 阅读 插件开发指南，从模板创建一个面板插件。
  • 用 pi-plugin check 与 pi-plugin pack 校验并打包 .piplug。

打开插件开发指南 → 浏览插件市场

常见问题

应用数据保存在哪里？

项目、会话、设置和日志保存在本机的应用数据目录。项目源文件仍留在你选择的文件夹中。

设置中可以指定自定义数据目录，并通过冷迁移流程搬迁已有数据； 不可重新生成的用户数据不会被静默删除。

API Key 和账号凭据如何保存？

凭据由宿主写入操作系统钥匙串，不保存在明文配置文件中。 自定义接口可以配置为免密模式，此时请求不会携带认证信息。

是否必须注册或登录？

桌面端需要登录 Voki 账号；企业环境由管理员配置企业 SSO，员工使用企业身份登录。 登录后默认接入账号模型网关，也可以自行添加本地模型或企业自建网关。

会上传遥测或项目内容吗？

应用不包含遥测。只有你显式发起的模型请求、市场下载、更新检查或 云服务操作会访问网络；请求内容取决于你选择的提供商。

支持哪些模型和服务提供商？

支持 OpenAI、Anthropic、兼容 OpenAI 的接口、自定义网关、Ollama、LM Studio 以及本地模型。提供商目录会随版本更新。

如何更新到新版本？

应用内更新卡片会显示下载进度，并提供取消和重试。 也可以从 发布版本 页面手动下载安装包。

Windows 和 Linux 版本可以使用吗？

可以。Windows 10+ 提供安装程序与便携 ZIP；Linux 需要 glibc 2.35+ （Ubuntu 22.04 / Debian 12 / Fedora 36 或更新版本）。 具体产物以 发布版本 页面为准。

手机端能做什么？

移动端用于远程控制桌面会话：查看进度、处理审批、追加指令、中断回合， 并验收交付物。详见 移动端页面。

第三方插件安全吗？

插件通过权限网关访问宿主能力，面板运行在隔离窗口中。但插件入口代码运行在 Node 进程中，并不是完整的操作系统沙箱；只加载你信任的来源，并检查安装时 展示的权限。

这份文档对应哪个版本？

当前文档对应 v1.0.0 Beta（构建 0.24.0）。站点内容随版本更新； 实际行为以你安装的应用版本为准。

反馈与安全

问题反馈与功能建议

在应用内打开反馈对话框（侧边栏账户菜单或设置页面中的「反馈」）， 选择问题类型、填写说明并附上截图。反馈会附带当前账号、界面语言和应用信息， 便于定位问题。

安全漏洞

请不要通过公开渠道披露安全漏洞。请将报告发送到 support@vokiai.com，主题使用： 

[voki-work Security] <简短描述>

报告中请包含影响范围、复现步骤、受影响版本与安装方式，并在发送前移除 API Key、访问令牌、密码、私有代码和个人数据。我们会在 7 个自然日内确认收到， 并在 14 个自然日内给出初步评估。

测试边界：不要针对其他用户、他人数据或生产服务进行破坏性测试。 安全修复只提供给最新发布版本。

↑ 回到顶部