Lancer 入门教程：搭建可追溯的并行 AI 桌面工作区

Lancer 是什么

Lancer 是一个基于 pi-gui 和 pi 开发的桌面 AI 工作区。它把对话、并行分支、运行过程和交付文件集中在同一界面中，帮助你追溯一项任务从创建、拆分到交付的完整过程。

重要：Lancer 当前处于 Alpha 阶段，macOS Apple Silicon 是主要验证平台。Linux 和 Windows 虽然具有打包配置，但并不表示所有原生能力都已完成验证。源码压缩包也不是可以直接双击运行的桌面安装包。

核心功能

会话与模块化任务

普通会话可以独立运行。模块会话则可以配置阶段、模型、Skill、目标和交付要求，适合处理步骤明确、需要验收结果的复杂任务。

并行分支与结果汇总

一个助手可以管理多个会话。任务能够派生子分支和孙分支，各分支完成后再把结果返回父会话汇总。这种结构适合并行研究、方案比较和多阶段内容生产。

GitTree 任务事件图

界面右侧的 GitTree 可以同时显示多条会话线、分支、合并及交付节点，也可以聚焦当前会话。需要注意，GitTree 表达的是任务事件图，其中的节点并不都代表真实的 Git 提交。

运行反馈与光线效果

活动气泡和过程行会显示流动边框，模型输出与交付动作则会向对应节点发送同色光线。这些视觉反馈用于展示当前正在运行的任务及其结果流向。

模型、账号与豆包接管

Lancer 通过 pi 连接订阅账号、API 密钥和自定义端点，并分别管理模型品牌与网关。在 macOS 上，它还可以关联一个已经打开的豆包 App 会话，以接收回复和视频。豆包接管需要本机辅助功能权限，而且桌面版豆包的界面更新可能影响兼容性。

视频分析工作流

视频工作流能够下载或接收视频、提取关键帧，并生成包含证据的分析与交接文件。不过，自动复刻目前不能保证与模板达到 1:1 一致。豆包接管、模型分析、代码动画和最终剪辑属于不同环节，应分别进行验收。

安装前准备

开始前，请确认开发环境满足以下要求：

• Node.js >=22.19.0 且 <26，推荐使用 Node.js 24。
• pnpm 10.34.9。
• Git。
• macOS 需要 Xcode Command Line Tools。
• Linux 需要 Python 3、make、C++ 编译器、图形桌面环境以及 Electron 所需的系统运行库。
• Windows 的原生依赖可能需要 Python 和带 C++ 工作负载的 Visual Studio Build Tools，但当前版本尚未完整验证 Windows 原生行为。

macOS 缺少命令行工具时，可以运行：

xcode-select --install

Debian 或 Ubuntu 可以安装 Linux 编译依赖：

sudo apt-get install build-essential python3

从源码安装并启动

将源码解压或克隆到一个新目录，进入仓库根目录，然后依次执行：

npx --yes pnpm@10.34.9 run doctor
npx --yes pnpm@10.34.9 install --frozen-lockfile
npx --yes pnpm@10.34.9 dev

这些命令固定使用 pnpm 10.34.9，不需要运行 corepack enable，也不要求全局安装 pnpm。如果系统已经安装相同版本，可以直接把命令前缀替换为 pnpm。

依赖下载需要网络连接。如果安装时跳过了依赖脚本，Electron 二进制文件可能不存在。确认网络可以访问 Electron 下载源后，执行：

npx --yes pnpm@10.34.9 run setup:electron
npx --yes pnpm@10.34.9 dev

不要通过无差别允许或关闭全部依赖脚本来修复 Electron 安装问题，应先检查安装日志和网络错误。

完成首次配置

1. 启动 Lancer 并进入设置。
2. 连接受支持的模型账号、提供商或自定义端点。源码不会附带个人凭据。
3. 添加或选择一个工作区。
4. 创建普通会话，或根据任务需要创建带阶段、模型、Skill、目标及交付要求的模块会话。
5. 运行任务后，在 GitTree 中观察会话线、派生分支、汇总和交付节点。

可以通过环境变量指定界面语言：

LANCER_LOCALE=zh-CN npx --yes pnpm@10.34.9 dev

英文界面可将值设置为 en。

加载可选环境配置

可选配置记录在仓库的 .env.example 中，但桌面启动脚本不会自动读取该文件。在 macOS 或 Linux 上，可以复制模板并在当前终端加载：

cp .env.example .env.local
set -a
. ./.env.local
set +a
npx --yes pnpm@10.34.9 dev

PowerShell 用户可以逐项设置环境变量，例如：

$env:LANCER_LOCALE = "en"

真实模型账号应在应用设置中连接。不要把 API 密钥、认证文件、私有端点、真实对话或会话录屏提交到公开仓库。

配置视频工具

仅使用对话界面时不需要媒体工具。若要运行视频下载、关键帧提取和媒体分析流程，则需要可执行的 FFmpeg、FFprobe 与 yt-dlp。

pnpm run doctor --media

如果这些工具不在 PATH 中，可以通过 FFMPEG、FFPROBE 和 YT_DLP 环境变量指定绝对路径，也可以在用户数据目录的 video-learn-tools.json 中配置路径。

诊断命令会实际执行各工具的版本命令，因此不仅能发现文件缺失，也能识别“可执行文件存在但动态库缺失”的损坏安装。进行完整验证前，可以先手动检查：

ffmpeg -version
ffprobe -version

运行检查、构建与测试

准备提交修改或评估源码状态时，可运行以下检查：

pnpm check
pnpm build
pnpm audit:dependencies
pnpm verify:install-copy
pnpm verify:release-config
pnpm --filter @lancer/desktop run test:e2e:core

开发过程中还可以验证桌面重载：

pnpm --filter @lancer/desktop run test:dev:reload

Core 测试使用隔离数据运行真实 Electron 界面，但通过 Core 测试并不能证明真实模型、原生权限、安装包、性能或全部平台兼容性均已验证。媒体相关测试还要求 FFmpeg 和 FFprobe 能够正常运行。

单独复用 Lancer Light UI

如果只需要模型或气泡连接工作树的光线效果，可以导出 Lancer Light UI。它不依赖 Electron、CLI 或模型服务，并提供单线、分叉合并及多会话并行示例。

pnpm export:light-ui /absolute/new/lancer-light-ui
cd /absolute/new/lancer-light-ui
npm install && npm run dev

导出路径必须替换为目标机器上的绝对路径。更多说明可查看仓库中的 Light UI README。

在 macOS 构建本地应用

源码包不包含可直接双击的 .app，独立应用下载也尚未发布。安装依赖后，可以运行本地构建脚本：

bash scripts/build-mac-lancer.sh --skip-install --dir

本地安装包要求预先配置持久签名证书。脚本不会自动创建证书、切换为临时签名或执行公证。构建结果保存在独立的 apps/desktop/release-local-*/ 目录中。

验证候选应用后，可以加入 --install 安装到 /Applications：

bash scripts/build-mac-lancer.sh --skip-install --dir --install

安装器要求旧应用正常退出，会检查签名并保留可恢复的旧版本，同时不会清空会话数据。公开分发仍需要 Developer ID、公证和干净机器验收，本地签名不能视为已经完成公开发布认证。

高级使用与安全建议

理解运行数据的位置

会话与账号数据使用 pi 的 ~/.pi/agent。macOS 上的 Lancer 界面状态位于 ~/Library/Application Support/Lancer。把源码复制到另一个目录并不会隔离这些运行数据；如需完全隔离的人工测试，应使用单独的操作系统用户。

为复杂任务设计分支

可将研究、分析、实现和验收拆成不同子分支，再由父会话汇总。使用 GitTree 时，应把节点理解为任务事件和交付关系，而不是默认把每个节点当作代码提交。

分别验收视频流程

对于视频项目，应分别检查接管输入、模型分析、代码动画和最终剪辑。不要仅凭某一环节成功，就推断最终作品能够自动与参考模板完全一致。

导出可审核的源码候选包

准备源码发布时，可以导出新的候选目录和 SHA-256 清单：

pnpm export:source /absolute/path/to/new/lancer-source

该命令会排除 .git、本地会话产物、密钥文件和构建输出，但会保留当前工作区、历史截图及录屏。导出成功不代表可以直接公开发布，仍需人工审核素材授权和敏感内容。

常见问题

• Corepack 出现权限错误：使用固定版本的 npx --yes pnpm@10.34.9 命令，无需修改全局 shim。
• Electron 未正确安装：检查网络和安装错误，然后运行 run setup:electron。
• Linux 提示缺少 make 或编译器：先安装 Python 3、make 和 C++ 构建工具，再重新安装依赖。
• 视频工具检查失败：执行 pnpm doctor --media，并确认可执行文件及其动态库均可用。
• 模型不可用：在设置中连接受支持的账号或提供商；源码不包含个人认证信息。

总结

Lancer 将并行 AI 会话、递归分支、过程反馈和交付文件组织在同一个桌面工作区中。按照本教程完成环境检查、源码启动、账号连接和媒体工具配置后，即可开始建立可追溯的任务流程。由于项目仍处于 Alpha 阶段，生产使用、跨平台兼容、豆包接管和视频复刻结果都应进行独立验证。