XunOPC 使用文档

XunOPC 把「一个人的公司」变成一套可运行、会积累的执行系统:经营台看清全局,数字团队并行推进,自动化按计划落地,Record & Replay 再把成功过程变成经过验证的公司 SOP。它读取真实的会话、权限、任务与结果——不虚构经营数字,也不把未经回放的流程冒充可靠能力。本文以当前稳定版 v0.8.0 的真实界面与能力为准。

下载 XunOPC 返回产品页

安装与首次启动

十分钟内从下载走到第一次运行。唯一容易出错的是芯片架构——先对一眼,后面都顺。

  1. 选对安装包。到官方下载页,芯片显示 Apple M1 / M2 / M3 / M4 等,下载 arm64;显示 Intel,下载 x64。不确定就看下方提示。
  2. 拖进「应用程序」。双击 DMG,把 XunOPC 拖入「应用程序」,再从 Launchpad 或「应用程序」目录启动。
  3. 直接打开即可。正式安装包已用润迅 Developer ID 签名并通过 Apple 公证,不需要运行 xattr 等额外命令绕过拦截。
  4. 先配模型,再干活。首次启动后进入「设置 → MaxModel」完成模型配置,然后再创建项目和会话。
不确定芯片? 打开 macOS 左上角「 → 关于本机」,查看「芯片」或「处理器」一栏。Apple 芯片版与 Intel 版走各自独立的官方更新通道,别装错架构。

配置 MaxModel:一个密钥,接入所有大模型

模型由你选、成本与合规由你控。XunOPC 不锁定单一模型,通过 MaxModel 网关接入主流大模型,随时切换。

打开「设置 → MaxModel → 配置 MaxModel」,粘贴从 MaxModel 获取的 API Key。接口地址保持默认,不要手动追加 /v1:

接口地址  https://api.maxmodel.com
API Key   sk-••••••••••••  （从 MaxModel 控制台获取）
  • 选择模型:页面同步 MaxModel 在线模型目录,可按名称、模型 ID 或厂商搜索;目录暂时不可用时,仍可手动输入模型 ID。
  • 四类映射:主模型、快速模型、均衡模型、高性能模型可分别指定;只想用一个模型时,设为相同 ID 即可。
  • 高级上下文:已知模型自动采用对应上下文窗口。只有网关限制变化或使用自定义模型 ID 时,才需手动调整。
  • 保存前测试:点「测试连接」,确认「连接性」与「模型代理转换」两步都通过再保存。
API Key 是敏感凭证。 不要写进项目文件、截图、聊天消息、工单或公开日志;设置页对已保存的敏感字段做脱敏展示。凭证一旦外泄,等同账户外泄。

完成第一项任务

第一项任务能不能成,取决于你有没有把「目标、范围、验收」一次说清。下面四步走一遍。

  1. 新建会话。点左侧「新建会话」,选「使用现有文件夹」或创建空白项目。
  2. 确认三件事。工作目录、模型与权限模式;首次使用建议保留「询问权限」。
  3. 把任务写清。目标、范围、验收标准一次写全;需要时直接粘贴图片、拖入文件,或用 @ 引用工作区文件。
  4. 审阅并验收。执行中审阅工具调用与权限申请;完成后在工作台查看更改文件、Diff、输出物和运行结果。
一个更容易成功的任务写法
目标:把登录页改成科技蓝,并修复窄屏布局。
范围:只改前端,不动接口。
验收:桌面与 390px 宽度都通过,运行测试并列出改动文件。

经营台与决策收件箱

经营台不是装饰性仪表盘。它读取本机真实的会话、权限请求、定时任务和运行结果,只回答三件事:系统正在做什么、已经交付什么、现在需要你决定什么。

需要你决定

等待处理的工具权限与电脑操作申请。点「去处理」回到来源会话,保留完整上下文。

已替你完成

最近自动任务留下的真实完成记录,可回溯到具体会话。

自动工作时间

按已完成任务的实际运行时长统计,不用虚构的「节省成本」替代事实。

需要介入

最近检测到的失败与超时,可直接转到定时任务继续处理。

当前经营台不是财务、CRM 或合同系统,也不会生成不存在的客户、收入和现金指标。只有接入对应业务数据后,这些经营对象才会进入首页。看到的每一项,都对应本机一件真实发生的事。

项目、会话与独立 worktree

项目以真实本机目录为边界,并行任务之间互不踩踏。这是「一个人同时推多条线」的底层保障。

侧栏按项目归档会话。可搜索全部聊天内容、置顶或隐藏项目、在访达中打开目录,并在指定项目中继续新建会话。

  • 当前目录:适合直接在现有工作区继续做事。
  • 独立 worktree:为并行任务创建隔离工作目录,不触碰你正在使用的分支和未提交改动。
  • 脏工作树保护:项目存在未提交改动、或目标分支已被其他 worktree 占用时,直接切换会被拦下;此时选独立 worktree,或先自行提交 / 暂存。
  • 历史仍保留:临时 worktree 清理后,会话记录仍可查看;继续工作时在原项目中新建会话即可。

工作台、审阅与交付物

右侧工作台把对话和真实产物放在一起,减少在访达、编辑器和浏览器之间来回切换。

  • 文件与 Diff:浏览全部文件或只看已更改文件,按行查看新增、删除、重命名和未跟踪内容。
  • 把意见送回会话:选中 Diff 行添加评论,再把评论加入对话,让 XunOPC 按具体位置继续修改。
  • 预览与浏览器:直接预览代码、文档、图片和本地网页;对 localhost 输出可在应用内继续验证。
  • 输出物:助手生成的 Markdown、HTML、图片、本地服务等会作为可打开的结果显示,不必从长对话里翻找。
  • 终端与历史:需要时打开宿主机终端;会话历史和运行状态独立保留。

6 个内置智能体

它们不是六个独立聊天机器人,而是同一执行系统里的六种专业职责——各有职责、模型、工具范围和系统提示词,仍受当前项目目录与权限策略约束。

通用智能体

研究复杂问题、搜索代码并执行多步骤任务。

代码探索

按路径、文件模式或关键词快速理解代码库。

方案规划

拆解实现步骤,指出关键文件、依赖关系和架构取舍。

质量验证

交付前运行构建、测试和检查,给出明确结论。

XunOPC 指南

回答产品设置、命令、MCP、技能与开发接口问题。

状态栏设置

配置 XunOPC 状态栏显示内容。

在「设置 → 智能体」可查看当前生效的内置、用户、项目、本地、插件和托管来源;同名定义会被更高优先级来源覆盖。

权限模式与可信执行

权限模式决定「能否执行」,不替你判断「该不该负责」。越自动,越要事先划清边界。

询问权限 推荐

执行工具前先询问,作为默认模式最稳妥。

接受编辑

自动批准文件编辑;命令、外部操作等仍需询问。

计划模式

只分析和规划,不执行任何修改。

跳过全部

跳过权限检查,风险最高,仅适合边界清晰且可恢复的受控环境。

权限卡会展示工具类型、命令或改动预览。你可以仅允许本次、在当前会话内持续允许同类操作,或直接拒绝。所有待处理申请也会进入经营台的决策收件箱。

这些动作建议永远保留人工批准:付款、对外发布、合同、客户承诺、删除数据、修改访问控制,以及其他不可逆的动作。自动化提速,不等于替你承担商业责任。

Record & Replay:把成功变成可验证的公司能力

这是 XunOPC v0.8.0 的核心能力。它解决的不是「怎样再保存一段聊天」,而是更难的事:怎样把一次成功提炼成可复用工作流,证明它脱离原对话仍能跑通,并在流程变坏时自动停下来。

成功会话

复杂任务完成并出现测试、构建或明确验收后,会话底部主动建议「沉淀为 SOP」。

手动提炼

随时输入 /skillify,把当前对话中的最短成功路径整理成 Skill 草稿。

桌面示教

没有 API 的软件流程,你亲手做一遍;XunOPC 根据授权采集的关键帧生成可审查草稿。

一句话理解:录制只是取证,草稿只是候选,回放通过才是验证,人工启用之后才成为系统可以自动调用的能力。

① 从成功结果提炼最短路径

系统会去掉失败尝试、临时诊断和一次性清理,保留目标、必要步骤与验收标准。它不会未经确认自动写文件——完整闭环如下:

1 触发成功会话、/skillify 或主动示教
2 脱敏密钥、客户数据和机器专属值改成运行时参数
3 审阅完整的 SKILL.md 与 workflow.json 先给你确认
4 回放在默认权限的干净会话独立验证
5 启用证据匹配当前版本后,由你决定是否允许自动使用
6 改进确认结果;失败则带着证据生成新草稿

草稿会剔除 API Key、密码、客户数据和机器专属路径,把每次运行才知道的值改成参数。这样同一 SOP 才能迁移到下一个客户、项目或操作者,而不把秘密固化进去。

② 你做一遍:XunOPC 只采集完成流程所需的证据

进入「设置 → 技能」的示教工作流,填写流程名称、边界或成功标准,确认屏幕采集授权后开始演示。录制中可以暂停、恢复,并在关键时刻主动标记:

  • 变量输入:例如客户名称、发票编号或日期,每次运行时重新提供,不写死在 SOP。
  • 人工审批点:例如发送邮件、提交订单或发布内容,工作流运行到这里必须停下等你确认。
  • 示教说明:告诉系统这一步为什么重要、怎样才算成功,避免只凭画面猜测意图。

XunOPC 只低频采集并去重屏幕关键帧,不记录键盘内容、剪贴板和原始点击轨迹。结束后先审查原始帧,可以立即删除;未删除的帧最多只在本机保留 24 小时。生成结果仍是草稿,不会自动启用或覆盖现有 Skill。

录制前关闭无关隐私窗口。 屏幕关键帧仍可能拍到客户资料或账号信息。生成草稿前先审查,不需要的录制立即删除。

③ 不止生成提示词:工作流把责任边界写进结构

每个工作流都可以在编辑器里明确以下字段。它们让同一流程可审阅、可测试,也让系统知道什么时候必须停下来找人:

结构解决什么问题
目标与最终验收要交付什么结果,出现哪些可观察证据才算真正完成
运行时输入区分必填与敏感参数,避免把密钥和客户专属值写入 SOP
执行步骤每一步可指定智能体、MCP、浏览器、电脑操作、命令行或人工完成
风险与审批标记低 / 中 / 高风险,并设置执行前审批或准备好后审阅
步骤证据与恢复定义怎样判断步骤成功,失败后怎样安全恢复
预计节约时间只在你确认成功后计入累计结果,不把一次调用冒充一次产出

④ 用干净回放证伪,用版本门禁防止能力悄悄变坏

新建、编辑或恢复的工作流默认都是「草稿 / 待验证」。点「在干净会话验证」会创建一个独立会话,采用默认权限重新执行;只有你确认结果通过,且证据摘要仍对应当前内容,才获得启用资格。

发生的变化XunOPC 的处理
干净回放通过并由人确认当前版本标记为已验证,可以由你启用自动使用
编辑步骤或恢复历史版本生成新的草稿版本,旧证据不继承,必须重新回放
文件被外部修改或内容摘要不一致立即让验证失效并暂停自动使用,防止已验证名义覆盖未知内容
实际运行失败或选择「需要改进」记录失败证据、暂停不可靠能力,并生成递增版本的改进草稿

⑤ 把结果变成公司的复利,但不粉饰数字

技能中心展示调用次数、验证成功次数、成功率、累计节约时间和最近使用时间。这里坚持一条规则:调用不等于成功。只有你在运行后选择「验证通过」,才会增加成功次数并按工作流设定的单次预计节约时间累计;选择「需要改进」则保留失败记录并启动改进流程。

技能分「个人」与「公司 / 项目」两个范围,决定它保存在哪、能被谁复用:

范围保存位置适用与共享
个人技能用户技能目录跨你所有项目使用,不随项目分发
公司 / 项目 SOP项目内 .xuncode/skills/随项目审阅与共享,团队一致对齐
/skillify SKILL.md workflow.json .xuncode/skills/ history/
适合先沉淀什么? 优先选择高频、边界清楚、结果可验证的流程,例如发版检查、周报汇总、客户资料整理、逾期发票跟进草稿。付款、正式发布、合同与客户承诺等不可逆步骤,应保留人工审批点。

插件与项目记忆

工作流负责把做事方法固化下来;插件负责成套扩展能力,项目记忆负责保留长期上下文。三者共同构成 XunOPC 的公司方法库。

  • 插件:把技能、智能体、命令、Hooks、MCP 和语言服务打包管理。启用、禁用或更新后,点「应用变更」让当前桌面运行时重新加载。
  • 项目记忆:按项目查看和编辑 Markdown 记忆文件,保存在本机项目记忆目录,由 XunOPC CLI 在后续运行时加载——这是让系统「记住这家公司怎么做事」的地方。
安装第三方技能或插件前,先核三样:作者是谁、装到哪、会暴露什么能力。付款、发布、发消息、改凭证、删数据等不可逆步骤,应在 SOP 里保留人工批准点。

MCP 服务:接入外部工具与数据源

MCP 是 XunOPC 伸向外部系统的手。接得越多,能力越大,越要管好范围与最小权限。

打开「设置 → MCP → 添加服务」,可连接 STDIO、Streamable HTTP 或 SSE 服务。页面会显示服务总数、连接状态和需要处理的异常。三种配置范围决定它对谁生效:

项目私有 Local

只对当前用户生效,并绑定一个项目。

项目共享 Project

写入项目的 .mcp.json,随项目与团队共享。

全局用户 User

写入用户级配置,对你的所有项目生效。

STDIO 服务直接在宿主机运行,所需的 Node.js、Python、Bun、uv 等运行时必须已安装并能从 PATH 找到。HTTP / SSE 可设置 URL、请求头和 OAuth 参数;API Key、Token、Secret、Password 等字段展示时会脱敏。

添加前确认来源、配置范围和最小权限;项目共享配置里不要包含个人密钥——它会随项目分发给每一个协作者。

定时任务:让重复工作按计划运行

把每天、每周都要做的事交给系统按点跑,人只在失败时介入。这是「一个人」也能持续运转的关键。

从侧栏进入「定时任务」,或在会话中用创建定时任务的命令。任务可设名称、目标提示、工作目录、执行频率、模型、权限和完成通知。频率支持:

每 N 分钟 / 小时   ·   每天固定时间
工作日 / 指定星期   ·   每月
自定义 Cron        （例：0 9 * * 1-5  工作日 09:00）
  • 可随时启用、暂停、手动运行,查看上次结果、下次执行和输出物。
  • 完成后可发桌面通知,或推送到已配置的 IM 渠道。
  • 失败和超时会进入经营台的「需要介入」,方便集中处理。
当前是本地调度。 电脑必须保持唤醒、XunOPC 桌面应用必须打开,任务才会按时触发。关闭应用或电脑休眠期间,不会在云端代跑。

消息接入与账号配对

把 XunOPC 接进你已经在用的 IM,人在手机上说一句,系统在电脑上把事做完。

「设置 → 消息接入」支持 Telegram、飞书、微信、钉钉和 WhatsApp。可设置平台凭证、默认项目、允许用户,并让定时任务完成后把结果推送到消息渠道。

机器人凭证

Telegram 用 Bot Token;飞书用 App ID / App Secret;钉钉可扫码创建并授权机器人。

账号扫码

微信、WhatsApp 用二维码把一个可收发消息的账号能力绑定给本机适配器;确认后适配器自动重启建连。

用户配对码

绑定账号 ≠ 允许所有联系人使用。具体用户仍需在私聊发送桌面端生成的配对码,或被加入「允许的用户」。

默认项目

新 IM 会话默认在哪个目录工作由这里决定;留空时用当前用户工作目录。

两层边界要分清:扫码解决「本机适配器用哪个账号收发消息」;配对码或允许用户解决「谁能通过这个账号调用 XunOPC」。解绑账号 → 该渠道停止收发;解除用户配对 → 只移除该用户的访问权。

电脑操作:让 Agent 看见并操作桌面

让 XunOPC 越过命令行,直接截屏、识别界面、点击和输入——覆盖那些没有 API 的桌面软件。

macOS 与 Windows 支持该能力;macOS 还需系统辅助功能和屏幕录制权限。首次启用按四步走:

  1. 确认 Python 3。进入「设置 → 电脑操作」,确认系统能找到 Python 3;用 conda、pyenv 等环境时可手动选择解释器。
  2. 安装组件。点「环境安装」,创建隔离虚拟环境并安装屏幕识别、鼠标键盘控制和系统集成组件。
  3. 授予系统权限。在 macOS「系统设置 → 隐私与安全性」中允许辅助功能与屏幕录制,随后重启 XunOPC。
  4. 启用并预批。启用电脑操作,选择可预先批准的应用;未预批或被视为敏感的应用仍会在会话中请求确认。
页面里的「组件未安装」指电脑操作所需的独立 Python 虚拟环境和自动化组件,不是 XunOPC 主程序缺失。只聊天、读写项目文件或调用普通工具时,不需要安装它们。

手机远程访问

人离开工位,活儿不停。手机扫码即可打开 XunOPC 的 H5 界面,接管桌面会话。

「设置 → 远程访问」可让同一可信局域网内的手机连上。启用后生成访问令牌和二维码,手机扫码即可连接桌面会话。

  • 普通局域网访问填本机可达的局域网 IP;需要反向代理时可配置完整公开 URL、固定端口和允许来源。
  • 手机锁屏或切后台短暂断连时,运行中的任务会继续;「断连保活」决定空闲且无人连接后多久停止 CLI。
  • 二维码内含访问令牌,拿到链接的人即可访问 H5 暴露的桌面能力。
令牌等同密码,只在可信网络启用。 手机扫码后连不上,先检查保存的主机 IP 是否仍属于本机当前网卡;切换 Wi-Fi 后通常需要更新 IP。

数据、自动更新与迁移

数据默认在你自己的机器上,更新不动你的会话。所有权和连续性,始终在本地。

  • 本机数据:会话、设置、技能、MCP、插件、项目记忆、任务和缓存默认保存在本机;高级用户可在通用设置切换自定义数据目录。
  • 自动更新:正式版从润迅官方国内更新源检查新版本,Apple 芯片和 Intel 各走独立通道;下载完成后按提示安装并重启。
  • 更新前:保存正在编辑的内容,等重要会话或电脑操作结束;安装重启不会主动删除已有会话和配置。
  • 诊断与调用记录:设置里的「诊断」和「调用记录」用于定位配置、数据或模型调用问题;分享日志前先检查并移除敏感内容。

故障排查

常见问题的一分钟自查。大多数「连不上、跑不动」都指向模型配置或本地环境这两处。

  • 新建会话提示断开 / 重试 / ECONNRESET:先在「设置 → MaxModel」测试连接,确认 API Key、当前模型和网络可用,再重启会话;持续出现就到「设置 → 诊断」看本地错误。
  • 模型目录加载失败:点刷新;目录不可用不影响手动填写模型 ID;确认接口地址没误加 /v1。
  • 网关返回 400 参数不支持 / 输出上限过大:先更新到最新版并重新选择该模型,让目录预设重新应用;仍失败就降低输出 / 推理强度,或在 MaxModel 高级设置关闭实验性 Beta 头。
  • 电脑操作显示组件未安装:确认 Python 3 可用,点「环境安装」,再检查 macOS 辅助功能和屏幕录制权限;授权后重启应用。
  • 定时任务没执行:确认任务已启用、电脑未休眠且 XunOPC 一直打开;本地任务不会在应用关闭时运行。
  • 微信 / WhatsApp 已扫码但不能对话:扫码只完成账号绑定;还需让该用户发送配对码,或把用户 ID 加入允许列表。
  • 更新已下载但重启异常:先退出正在运行的会话和终端,再完全退出 XunOPC 后重新打开;仍失败可从官方下载页覆盖安装同一架构版本。

联系与反馈

产品使用、企业部署、消息渠道接入与问题反馈,请联系润迅。

反馈故障时,请提供 XunOPC 版本、Mac 架构、复现步骤和已脱敏的错误信息;不要发送 API Key、访问令牌或客户数据。

下载当前版本 查看版本历史