编码工作台用户指南

编码工作台是 BiuMind 桌面端的「编码」页：把一个代码仓库交给 AI 工程师，你写任务描述、做审批、看进度，Git、终端、文件浏览都收在同一个界面里。可以同时派多个任务并行跑，你像项目经理一样逐个验收。

[!NOTE] 编码工作台只在桌面端（macOS / Windows / Linux 客户端）可用，网页端没有这个模块。

界面总览

打开一个项目后，工作台分为五块：

┌──┬────────────┬──────────────────────────┬──────────┬──┐
│项│ 分支条      │   主区                    │ 右栏面板  │图│
│目│ 任务列表    │   - 任务详情 + 会话回放    │ (文件/Git │标│
│栏│ (可搜索)    │   - 或文件查看 Tab        │ /历史/…)  │条│
│  │            │   ─────────────────────  │          │  │
│  │            │   (底部:终端面板 可开关)    │          │  │
└──┴────────────┴──────────────────────────┴──────────┴──┘
                底部状态栏:当前任务的 agent / 模型 / 权限 + 用量

• 项目栏（最左 48px）：项目头像竖排，点选切换项目，长按拖拽可重排；底部「+」添加新项目。
• 任务列表：当前项目的全部任务。顶部是当前分支条和「新建任务」按钮，下方是搜索框、任务计数和「全部清除」，底部显示运行中的任务数。需要注意的任务（等审批、连接断开、被中断）会以「需要注意」分组置顶。
• 主区：没选任务时显示新建任务页；选中任务时显示任务详情头 + 会话回放；从文件树点开文件后切换为文件查看 Tab（再点左侧任务即可切回会话）。
• 右栏面板（300px，可折叠）：文件 / Git / 历史 / Skills / 状态信号 / 项目配置 六个面板之一。
• 右侧图标条（48px）：文件、Git、历史、终端、搜索在上，Skills、项目配置、状态信号 (hook) 在下。点已展开的图标再点一次即折叠该面板；「终端」切换底部终端面板；「搜索」打开文件搜索浮层。
• 底部状态栏：显示当前任务的 agent、模型、权限档，右侧是用量入口。

[!TIP] 任务列表和主区之间的分隔条可以拖动调整宽度。

添加与切换项目

1. 点左侧项目栏底部的「+」，或首次进入时欢迎页的「添加项目」按钮。
2. 在系统目录选择器里选中一个本地代码仓库目录，点「添加」。
3. 添加后自动切换到该项目；之后随时点头像切换。

首次进入（没有任何项目）时，界面顶部有「项目 | 时间线」两个切换页签：项目页是欢迎页（含最近打开的项目列表），时间线页是跨项目的任务时间线（见并行任务）。选了项目后时间线不再显示，任务以左栏列表为准。

怎么让 AI 修一个 bug

1. 派任务

点任务列表顶部的「新建任务」，主区出现任务描述页（「今天想构建什么?」）：

• 描述：多行输入框写任务描述。输入 @ 会弹出文件选择器，按文件名搜索后选中，文件路径会以 @路径 插入描述里，AI 能直接定位到相关文件。
• 附件：点工具条左侧「+」可添加附件——选择图片、粘贴剪贴板图片（如报错截图）、粘贴文本。图片会存到项目的 .biu/attachments/ 下，文本会附在 prompt 末尾。
• Agent：选执行引擎——biu（BiuMind 自家 CLI）、Claude Code、Codex。
• 权限：三档——Ask Permission（每个敏感操作先问你）、Auto Edit（自动改文件）、Full Access（全自动）。
• 运行环境（输入框下方）：跟随设置（按全局设置决定）、本地处理（直接在项目目录跑）、新工作树（为本任务单独建一个 git worktree 隔离，可选基分支：当前 HEAD 或任一本地分支）。

按 ⌘/Ctrl + Enter 提交（按钮上也有提示）。提交后自动切到该任务。

[!TIP] 描述留空直接提交，会启动一个交互式终端会话——相当于在项目目录里开一个 AI 终端，边聊边干。

2. 跟进度、做审批

提交后主区显示任务详情头和会话内容：

• biu 任务：以结构化消息流展示——AI 的文字输出按 Markdown 渲染，每次工具调用显示为一张卡片（读文件、改文件的 diff 预览、Bash 命令和输出等），正在执行的卡片带转圈图标。
• Claude Code / Codex 任务：在真实终端里跑，主区显示实时终端画面；任务结束后如有结构化事件，自动切换为 Markdown 式回放。
• 审批：权限为 Ask 档时，AI 请求敏感操作会插入一张橙色审批卡片（Allow <工具>? + 参数），你可以 Allow（本次会话允许）、Allow once（仅允许这一次）或 Deny（拒绝）。等待审批的任务会进入「需要注意」分组置顶。
• 详情头：任务标题（可重命名、AI 命名、导出为 Markdown）、agent / 模型 / 权限、工作目录，以及时长、TOKENS、上下文占用、费用、增删行数等指标；右侧按状态提供 停止、标记完成、续跑（从中断处继续）、合并到主干（worktree 任务完成后把分支合回基分支）等按钮。

任务状态一览：

状态	含义
排队中	已创建，等待启动
运行中	正在执行
需要确认	等你审批某个操作
已完成 / 失败	正常结束 / 出错结束
已中断	进程已停止，可「恢复」续跑
终端连接断开	进程还在后台跑，只是界面断了连接，可「重新连接」

[!TIP] 「已中断」和「终端连接断开」都会在回放顶部显示横幅：前者点「恢复」用上次会话继续（无可续跑会话时按钮禁用），后者点「重新连接」接回仍在跑的终端（不会重启会话）。两者都可以「标记完成」收尾。

3. 验收

任务完成后：任务列表行尾会显示相对基分支的 +N −N 增删行数；worktree 任务在详情头点「合并到主干」将分支合并回基分支（有冲突时会失败并保留 worktree，去 Git 面板手工处理）。也可以在 Git 面板里查看 diff、提交。

并行跑多个任务

并行不需要任何特殊开关——每个任务互相独立：

1. 派出第一个任务后，再点「新建任务」派第二个、第三个……每个任务有自己的运行环境和状态。
2. 任务列表里点不同任务即可在主区切换查看；等待你处理的任务会集中在「需要注意」分组。
3. 左栏底部实时显示 N running。

并行的关键是隔离。在设置 → 编码工作台里有「任务隔离 (worktree)」开关：

• 开启（推荐）：每个任务自动创建独立的 git worktree 和分支（分支名形如 biu/<agent>-<id>），多个任务同时改文件互不干扰，完成后各自合并。
• 关闭：所有任务共享项目目录，并行时可能互相覆盖文件。

新建任务时也可以在「运行环境」里单独指定某个任务用「本地处理」或「新工作树」，覆盖全局默认。

任务列表的其他操作：

• 搜索：顶部搜索框按标题或任务描述过滤。
• 星标：悬停任务行点星形图标，星标任务排在前面。
• 右键菜单（或长按）：重命名、AI 命名（根据任务描述自动起名）、复制 Prompt、星标 / 取消、删除（删除会连同 worktree 一起清理，不可撤销）。
• 全部清除：一次删掉当前项目的全部任务（含 worktree），有二次确认。

任务行上的小图标含义：分支形图标 = 该任务有 worktree 分支（悬停显示分支名）；设备图标 = 任务来自你的另一台设备；不同图形区分 biu / Claude Code / Codex 三种 agent。

跨项目时间线

没有打开任何项目时，顶部切到「时间线」页签：按「今天 / 昨天 / 更早」分组，组内再按项目分组列出所有任务。点任一任务会自动切到对应项目并打开它。

浏览与查看文件

文件树

右侧图标条点「文件」打开文件面板：

• 目录树懒加载，点文件夹展开 / 收起，展开中显示小转圈。
• 头部三个小按钮：新建文件、新建文件夹、刷新（均作用于项目根目录）。
• 右键（或长按）目录可「新建文件 / 新建文件夹」；右键任意节点可「删除」（永久删除、不进回收站，有二次确认）。
• 点文件 → 在主区以 Tab 打开。

文件查看

主区的文件 Tab：

• 文本文件带语法高亮，只读查看；图片文件直接预览。超大文件会截断提示。
• 多个文件以多 Tab 并排，Tab 可关闭；切 Tab 不丢内容（后台保活）。
• 点左侧任务可随时切回会话视图。

文件搜索

右侧图标条点「搜索」打开搜索浮层：输入文件名模糊搜索已被 Git 管理的文件，↑ ↓ 选择、回车或点击在主区打开。搜索防抖 300ms，上限 50 条结果。

Git 操作

所有 Git 功能作用于当前打开的项目，真相源是你本地的 git 仓库。

分支切换

任务列表顶部的分支条显示当前分支，点击展开菜单：

• 切换分支：列出本地分支（当前分支带 ✓），点选即 checkout。
• 新建分支…：输入分支名（如 feature/x），创建并切换。
• 删除分支…：二级菜单选择非当前分支，确认后删除；分支有未合并提交时会追问是否强制删除。

源代码管理（Git 面板）

右侧图标条点「Git」，面板分为左列（380px）和右侧 diff 区，顶部可切「更改 / 历史」两个视图。

更改视图：

• 顶栏显示当前分支、领先 / 落后远端的数量（↑N ↓N），以及拉取 (pull)、推送 (push)、刷新三个按钮。
• 变更列表分两组：已暂存的更改（数量 + 「取消全部」；单行可「取消暂存」）和更改（数量 + 「全部暂存」「丢弃全部」；单行可「暂存」「丢弃更改」）。文件名前的字母标记状态：M 修改、A 新增、U 未跟踪、D 删除、R 重命名，各配色区分。
• 丢弃操作（单文件或全部）都有确认弹窗——未暂存改动和未跟踪文件会被删除，不可撤销。
• 底部提交框：填写提交信息（提示遵循 Conventional Commits），点 AI 生成可基于当前改动自动生成提交信息（有任何改动即可，不必先暂存）；点「提交 N 项」提交已暂存的内容。
• 点任一文件，右侧显示该文件的统一 diff，按行着色：新增绿、删除红、位置信息紫，等宽字体可横向滚动。

历史视图：列出提交历史，点任一提交，右侧显示该提交的元信息（信息、短哈希、作者、日期、增删行数、文件数）和完整 diff。

提交历史（历史面板）

右侧图标条的「历史」是独立的轻量历史面板：显示最近 100 条提交（信息、短哈希、作者、日期），点进任一条查看该提交的统一 diff，左上角箭头返回列表。与 Git 面板里的「历史」视图相比，这个面板更窄，适合快速翻看。

终端

右侧图标条点「终端」，在主区底部展开一个终端面板（可关闭）：

• 在当前项目目录里开的交互 shell（zsh / bash），与任务无关，随时可以用。
• 每个项目可开多个终端：顶部「Shell 1 / Shell 2 …」子 Tab 切换，+ 新建、× 关闭；切到后台的 shell 输出保留不丢。
• 进入终端面板时如无 shell 会自动开第一个。

任务会话的终端：Claude Code / Codex 任务本身就在真 PTY 终端里跑，运行中主区就是它的实时终端画面；重新打开一个跑过的任务，会先回放已落盘的终端日志再接上实时输出。进程结束后终端末尾会标注退出码。

[!NOTE] 终端配色跟随应用明暗主题切换；如果终端记录早于持久化功能或任务未产生输出，会显示「该任务没有可回放的终端记录」。

看用量

底部状态栏右侧的用量入口（图标可悬停提示「用量」）点开一个浮层：

• Claude Code：订阅的 5 小时窗口和 7 天窗口各自剩余百分比与重置时刻。
• Codex：主额度、次额度的剩余百分比与重置时刻，附套餐类型和账号。

剩余百分比着色：大于 70% 绿、20%–70% 橙、低于 20% 红。点浮层内的刷新按钮重新拉取快照。

[!TIP] 用量数据来自本地 daemon 读取的各 agent 订阅状态；daemon 未就绪时入口置灰。并行任务多时先看一眼剩余额度，避免跑到一半撞限额。

Skills（项目级）

右侧图标条点「Skills」打开项目级技能面板：

• 列出 ~/.biumind/skills 里的全部技能——与技能管理页是同一份存储，在技能管理里添加后回到这里就能看到。
• 每个技能卡片下方有 claude 和 codex 两个按钮，点选即为当前项目安装 / 卸载该 agent 的技能：安装时会把技能链接进项目的 .claude/skills 或 .codex/skills 目录，这样不仅工作台里的任务能用，你在终端里直接跑 Claude Code / Codex 时同样能发现并复用这些技能。

状态信号 (hook)

右侧图标条点「状态信号 (hook)」：

• Node.js 检测：hook 脚本需要 Node.js，面板显示是否找到及其路径。
• agent 就绪态：逐个列出 Claude / Codex 等是否达到可用的版本门槛，不满足时给出原因。
• 安装 / 重装 与 卸载 按钮：一键安装或移除 hook。

hook 的作用：让 Claude Code / Codex 在运行中主动上报生命周期事件（等待审批、一轮结束等），从而驱动任务列表里可靠的「需要注意」分组，而不是靠轮询日志反推状态。建议在开始用编码工作台时装上。

项目配置

右侧图标条点「项目配置」，编辑当前项目的 .biu/config.toml（面板副标题：新任务默认值与每个任务的 prompt 前缀）：

• 默认 agent：biu / claude / codex，新建任务页会预填。
• 默认权限档：ask / auto_edit / full_access，同样作为新建任务的默认值。
• prompt 前缀：一段自动拼到本项目每个任务描述最前面的文字，例如「遵循 STYLE.md 里的代码规范」。留空则不加。

改完点「保存」写入配置文件。

桌面端与本地 daemon

编码工作台的所有本地操作——Git、文件读写、终端、Skills 安装、用量读取——都通过一个本地 daemon 执行：登录后桌面端会自动在后台启动 biu serve（只监听本机回环地址），界面通过它与你的仓库交互。正常情况下你不需要关心它；如果各面板提示「本地 daemon 未就绪 —— 登录后桌面端会自动启动 biu serve」，检查两点：

1. 是否已登录账号；
2. biu CLI 是否已安装（见 CLI 快速上手 的安装章节）。

[!TIP] 桌面端检测到本机没有 biu 时可以自动下载安装。也可以自己在设置 → 编码工作台里点「自动检测路径与版本」，让 daemon 扫描 PATH 和常见安装目录（Homebrew、npm 全局、~/.local/bin 等）找到 biu / claude / codex 三个可执行文件，并对每个路径提供 Test 按钮验证版本。

设置：二进制与工作目录

设置 → 编码工作台页配置执行环境：

• 任务隔离 (worktree)：见并行任务。
• Working dir：任务默认执行的目录。
• biu / Claude / Codex 路径：三个 agent 的可执行文件路径，留空走 PATH 自动查找；每个字段有 Test 按钮执行 --version 验证。
• 当前生效的 PATH：从登录 shell 解析出的 PATH（桌面 App 从 Dock 启动时自带的 PATH 往往不全，这里展示 spawn 子进程实际使用的搜索路径）。

深入了解

• biu CLI 的安装、登录与日常用法：CLI 快速上手、CLI 使用指南
• 权限模式、规则与 Hooks 的完整语义：权限与 Hooks
• 全部子命令参考：命令参考
• 云端技能的浏览、安装与审批：Skills 用户指南