基本流程

DFCode Studio 是以 DFCode Engine 为核心的桌面客户端。它提供项目、会话、Review、终端、扩展和更新入口，也能读取项目、修改代码、执行命令和规划任务。

首次使用时，建议按以下顺序阅读：

1. 基本流程
2. DFCode Studio 是什么
3. 安装、启动与更新
4. 项目、工作区与隔离目录
5. 企业登录、Provider、模型与推理深度
6. Studio 的工作模式与执行控制
7. Composer：描述任务与附加上下文
8. 会话、Timeline、Fork、Compact 与 BTW
9. 阅读项目、修改文件与工具活动
10. Review、Diff、Commit 与 Discard
11. 内置 Terminal 与后台 Tasks
12. Goal、Todo、子智能体与项目记忆
13. Skill、Plugin、MCP 与 Agent
14. 设置、主题、通知与快捷键
15. 常用流程
16. Studio 与 CLI 如何选择

部分能力会随客户端版本、Engine 版本和企业部署策略变化，以实际界面和管理员配置为准。CLI 的无头运行、Supervisor、loop、server 管理、ACP 和 PR 拉取见 CLI 产品手册。具体任务的操作步骤见 Studio 场景示例。

1. DFCode Studio 是什么

DFCode Studio 是 DFCode 的桌面工作台，可在一个窗口中管理项目、会话、任务、代码改动和验证结果。打开客户端后，添加项目并创建会话即可开始使用。

Studio 与 CLI 共享这些能力：

• 搜索文件、理解目录、追踪调用链和阅读项目文档。
• 创建或修改文件，查看内联 Diff。
• 分析任务、制定计划并实施。
• 执行测试、构建命令和开发服务器。
• 审查未提交改动、上一轮改动和单次工具调用的变更。
• 使用 Auto、Goal、后台 Tasks 和子智能体处理长任务。
• 使用 Skill、Plugin 和 MCP；Browser Use 需部署支持。
• 读取项目记忆、压缩长会话上下文，将子任务结果带回主会话。

Studio 还提供：

• 多项目和项目标签页
• 多目录工作区；支持的 Engine 可列出并创建 Worktree，再从环境菜单切换
• 会话搜索、重命名、Timeline 和 Fork
• 文件、图片和目录附件
• Review、Commit 与 Discard
• 内置多 PTY 终端和后台任务面板
• Marketplace、MCP 和右侧浏览器；Agent 浏览器操作取决于 Engine 启动方式和连接状态
• 本地主题、通知、桌面 OTA 更新与项目工作台

2. 安装、启动与更新

安装桌面客户端

下载并安装官方提供的 macOS 或 Windows 安装包，然后打开 DFCode Studio。无需先安装 Node.js 或执行 npm install -g dfcode。

首次打开时：

1. Studio 检查本地 Engine 是否可用。
2. 复用兼容的本地 Engine；没有可复用的 Engine 时，Studio 启动内置或明确配置的 Engine。
3. 客户端连接 Engine，并进入项目桌面。
4. 用户添加项目后即可创建会话。

Studio 和 CLI 可以同时安装，共用项目规则、Skill、MCP 和 Engine 配置；操作入口不同。

桌面更新

启用 OTA 的版本会在标题栏显示更新入口：

1. 点击标题栏中的“检查更新”。
2. 查看新版本号和 Release Notes。
3. 下载更新并观察进度。
4. 下载完成后选择“安装并重启”。

如果当前版本没有显示“检查更新”，请使用企业管理员提供的新安装包完成更新。

Studio Settings 管理的是桌面偏好；完整 Engine 配置仍由 dfcode.jsonc、企业远程配置和环境变量等高级方式管理。

3. 项目、工作区与隔离目录

添加和切换项目

在 Studio 桌面点击“添加工作区”，通过系统目录选择器打开本地仓库。项目会出现在桌面历史和项目页签中，可进行以下操作：

• 切换多个已添加工作区
• 新建当前工作区会话
• 从本地历史中移除项目记录

每个项目按目录隔离会话、Git 状态、文件搜索和终端上下文。切换项目时先确认顶部项目标签和 Composer 的工作区标签，避免在错误目录执行任务。

使用 Worktree 隔离任务（可选）

Studio 可把任意本地目录添加为独立工作区，包括已经通过 Git 创建的 Worktree。如果 Composer 的环境菜单提供“创建 Worktree”，可以直接创建并切换。

高风险改造、长期功能或需要独立提交的任务可使用单独的 Worktree。切换目录不会复制当前会话上下文；请先完成当前阶段，或在新 Worktree 中新建会话并附上必要信息。

4. 企业登录、Provider、模型与推理深度

企业登录

企业登录从 Studio 的 Composer 发起：

1. 输入 /login 并发送。
2. 系统浏览器打开企业登录门户。
3. 完成账号验证和设备绑定。
4. 等待 Studio 刷新登录状态和 Provider 清单。
5. 登录成功后，Studio 显示当前身份和连接状态。

如需退出当前账号，在 Composer 输入 /logout 并发送。Studio 会刷新账号状态和 Provider 清单。

选择模型

点击 Composer 的模型胶囊，搜索并选择企业模型。列表只包含已连接、且被 Studio 识别为 MaaS 的 Provider 模型。

企业用户通常无需在 Studio 中填写 API Key；模型和额度由企业统一配置。Studio 没有通用的 Provider API Key 或 OpenAI 兼容 Relay 配置界面。个人 Provider 需按企业规定使用 Engine 高级配置或 CLI 流程。

调整推理深度

在模型菜单中调整 reasoning effort（推理深度）：

档位由当前模型决定，不同模型可能提供额外 Variant。

如果之前保存的模型已下线或权限发生变化，Studio 会根据最新 Provider 清单恢复到可用模型，或要求重新选择。

5. Studio 的工作模式与执行控制

先确认工作区的 Code / Doc 呈现方式，再从 Composer 底部选择运行模式。需要建立规格时，从“更多”菜单进入 Spec。

工作区呈现：Code 与 Doc

• Code：围绕源码、工具活动、Diff、Terminal 和 Git Review 组织工作区。
• Doc：以文档产出、资料组织和预览为重点。

同一工作区的 Code 与 Doc 共享会话历史和当前会话。切换呈现方式后可继续同一个任务；切换项目或 Worktree 时，先确认目标目录和会话。

运行模式：Plan、Manual、Auto 与 Trust

点击 Composer 底部的运行模式胶囊，按任务选择：

Plan 的典型流程：

1. 在运行模式菜单选择 Plan，发送目标、文件范围和验证要求。
2. 在计划审批卡中检查方案。选择 Manual 或 Auto 进入实施；需要修改方案时选择 Continue planning。
3. 若实施阶段需要 Trust，再从运行模式菜单选择 Trust 并确认授权。

菜单里的“Plan 阶段自动审批”控制规划期间的工具审批。实施方式仍需在计划审批卡中选择。Auto 进入实施后，会在低风险工具调用旁标记“自动通过”；遇到破坏性或敏感操作，会显示“安全分类器拦截”，不会继续执行。Agent 的主动提问也不会由 Auto 自动代答。

Trust 的文件、Shell、MCP 和网络访问仍使用当前 Engine 提供的能力与配置。启用前确认工作区、允许修改的路径和停止条件；结束后切回 Manual 并检查改动。

读取 CI 配置 · 86 lines

找到 3 个失败用例

16 passed · 0 failed

检测到敏感配置写入 · tool-error

Spec：先整理规格，再实施变更

跨模块需求需要记录背景、验收场景和实施任务时，使用 Spec。它会先给出方案，确认可行后才开始修改业务代码：

1. 在 Composer 的“更多”菜单点击 规格进展。Composer 会增加一个可关闭的“规格进展”工作流标签；Manual、Auto、Trust 仍单独控制权限。
2. 发送需求，读取相关实现和测试，并整理 specs/changes/<变更名>/。
3. 在项目总览查看当前变更。看板只使用 提案中 / 实施中 / 可归档 三个阶段，并集中展示变更原因、范围、需求 delta、场景数量、tasks.md 完成数和下一步。
4. 查看 Agent 给出的方案、proposal.md、tasks.md 和 deltas/<能力名>/spec.md，确认 Given / When / Then 场景、任务边界和验收条件。
5. Agent 会先询问方案是否可行。需要调整时直接说明；确认无误后，在会话中回复“可以实施，按这个方案开始吧”。
6. 收到确认后，阶段进入“实施中”，按 tasks.md 修改业务代码并逐项勾选；全部完成后进入“可归档”。

选择“规格进展”后，在 Composer 发送：

请为“设备绑定恢复”建立规格变更。
先检查现有登录、设备状态和错误提示实现，说明背景、变更范围和代码依据。
整理 specs/changes/device-binding-recovery/ 下的 proposal.md、tasks.md
和 deltas/authentication/spec.md，用 Given / When / Then 覆盖恢复绑定、
重复提交和旧设备状态。先校验规格文档，等待我确认后再修改业务代码。

规格进展选择按会话保存，规格文档保留在项目目录中。结束工作流时，点击 Composer 中“规格进展”标签的关闭按钮；这不会替你切换 Manual、Auto 或 Trust。

在 Code 会话中也可以分别执行 /spec 和 /unspec。先发送切换命令，成功后再单独发送任务提示词。Goal 正在运行时，需要先暂停 Goal，才能进入规格进展。

6. Composer：描述任务与附加上下文

Composer 用于输入任务，也支持文件引用、命令、Skill 和附件。

@ 引用文件

输入 @ 搜索项目文件，再从列表中选择路径。只有选中的文件才会作为 file part 发送给 Engine；直接输入 @word 不会自动附加文件。

适合：

• 指定需要修改的文件
• 附上配置、日志或测试
• 缩小大型仓库的搜索范围
• 要求比较多个实现文件

/ 查找命令

Code 模式提供这些本地命令：

这些本地命令需要先进入会话。/summarize 是 /compact 的兼容别名，但不会显示在菜单中。

Studio 还会合并 Engine 动态返回的命令。其余命令是否出现，取决于当前 Engine 版本、项目配置和扩展。Doc 模式当前不显示通用 / 命令建议；两种模式的命令入口并不完全相同。

$ 选择 Skill

输入 $ 搜索当前 Engine 发现的 Skill。选择后，Skill 会为当前任务提供团队经验、检查步骤或固定工作流。

图片和文档附件

可以通过拖放、粘贴或附件入口加入：

• 图片
• PDF
• Word、Excel 和 PowerPoint 文档
• 多个受支持文件

通过 Composer 的“添加文件夹”入口可以附加目录上下文。文档附件仍受类型和大小限制。项目源码和配置优先通过 @ 文件选择器或文件夹入口引用。附件会显示在输入框上方的附件条中。

任务描述写明目标、范围、限制和验证方式：

请结合 @src/checkout/submit.ts 定位重复扣款，使用 $security-review 检查幂等与并发风险。只改 checkout 模块，完成后运行 npm test -- checkout。

7. 会话、Timeline、Fork、Compact 与 BTW

会话列表

每个项目有独立的会话列表，可进行以下操作：

• 新建会话
• 搜索会话标题
• 选择会话
• 删除会话
• 查看运行中状态

会话标题显示在侧栏，可通过会话菜单重命名。当前版本暂不支持归档会话。

Timeline 与 Fork

Timeline 列出当前会话的用户消息，并显示父会话和子分支。从指定用户消息 Fork 新会话，可用来：

• 比较不同技术方案
• 保留原方案，同时尝试高风险改法
• 从早期需求节点重新开始
• 避免把实验性讨论污染主线

Compact

长会话接近上下文上限时执行 /compact。Engine 会压缩较早内容，保留当前目标、重要约束、关键决定和未完成工作。

压缩前应确认：

• 关键路径和文件名已经明确
• 尚未完成的 Todo 有清晰状态
• 重要测试命令已写入会话
• 不可丢失的原文已保存到项目文档

BTW 侧问

/btw 适合临时询问不应打断主任务的问题。侧问有独立结果和历史，不会作为普通消息加入主会话上下文。

Studio 的 Revert / Unrevert 按会话轮次撤回和恢复，不能用作编辑器的逐次 Undo / Redo。

8. 阅读项目、修改文件与工具活动

Agent 会调用搜索、读取、编辑、命令和子任务工具，过程显示在活动卡和线程中。

常见活动包括：

• read：读取文件
• glob：按路径模式查找文件
• grep：搜索代码内容
• bash：执行命令
• write / edit / apply_patch：修改文件并显示 Diff
• task：调用子智能体
• todowrite：更新 Plan / Todo 状态

工具卡可展开查看输出；运行中的命令会显示实时状态。修改类工具会显示文件路径、增加/删除行数和内联 Diff。

工作流程：

高风险任务先选择 Plan 并要求只读分析，确认方案后再选择 Manual 实施。

9. Review、Diff、Commit 与 Discard

Review 范围

Studio 右侧 Review 工作台提供两个范围：

• Uncommitted：工作区所有未提交改动
• Last turn：上一轮会话产生的改动

Uncommitted 显示工作区的未提交改动，Last turn 显示上一轮会话产生的改动。单次工具调用的 Diff 在对应工具卡中查看。

检查并提交

Review 支持：

1. 查看文件增加/删除行数。
2. 展开 Diff 检查具体代码。
3. 选择准备提交的文件。
4. 填写提交信息。
5. 提交所选路径。

提交前仍应运行项目要求的测试、类型检查、Lint 或构建，不应只依赖 Agent 的完成说明。

移除改动

Discard all 会丢弃当前工作区所有未提交改动，属于难以恢复的操作。确认前应检查是否包含手工修改或其他会话留下的文件。

Review 用于检查和提交本地改动。Push、远程检查和合并 PR 请使用外部 Git 工具、Terminal 或 CLI。

10. 内置 Terminal 与后台 Tasks

Terminal

右侧 Terminal 是交互式 PTY，支持：

• 运行测试和构建
• 启动开发服务器
• 查看 Git 状态
• 执行项目脚本
• 调试 Agent 修改后的行为

Studio 支持多个 PTY 标签。收起 Terminal 或切换面板不会中断仍在运行的进程。

Tasks

Tasks 面板用于观察 Agent 已经启动的后台 Shell 和 Monitor：

• 当前状态
• 命令和任务类型
• 实时输出
• 已完成、失败、超时或终止等结果状态
• 停止运行中的 Shell

Tasks 用于查看和控制 Agent 启动的后台 Shell。手动运行命令请使用 Terminal；Terminal 输出和 Tasks 状态分别在对应面板查看。

同一目录、会话和任务类型下的相同命令会合并显示，并标注尝试次数。先失败后成功的任务会标记为已通过重试解决，也可以过滤运行中或已解决的任务。分组依据任务记录，日志中的 ERROR、FAIL 等文字仍需结合输出判断。

后台任务结束时，Studio 可按本地通知设置和窗口焦点状态生成应用内或桌面通知。

11. Goal、Todo、子智能体与项目记忆

Goal

Goal 用于让同一会话围绕一个持续目标多轮推进，例如反复定位和修复测试失败，直到达到验收条件。

1. 先进入一个已有的 Code 会话，确认工作区和验证命令。
2. 在 Composer 输入 /goal 和目标；也可以点击“更多 → 目标”，在预填的 /goal 后补充任务再发送。
3. 在会话的 Goal 条查看目标、状态和轮数。展开后可暂停、继续或清除目标。

/goal 持续修复 checkout 模块的单元测试，直到 npm test -- checkout 通过。
只修改 src/checkout 和对应测试；需要修改依赖或扩大范围时暂停并说明原因。
不要提交代码。

常用命令：

Goal 条显示当前轮数和最大轮数，但不能手动设置最大轮数。需要按指定验证命令和轮数上限运行的任务，可参考 CLI 的 Supervisor。

Todo / Plan

Agent 会把复杂任务拆成 Todo。右侧面板和工具卡显示：

• pending
• in_progress
• completed
• cancelled

Todo 由 Agent 根据任务进度更新，可在右侧面板和工具卡中查看；当前不能手动排序或编辑。

子智能体

复杂任务可以调用子智能体。Studio 支持以下操作：

• 展开 task 卡查看子任务提示和结果
• 点击 task 卡的“查看详情”，在右侧面板查看子会话文本与工具活动
• 重试加载子会话记录

可用子智能体名称和类别由当前配置决定。右侧详情用于查看执行记录；需要继续处理子任务结果时，在主会话中说明。

项目记忆

项目记忆按类别保存项目架构、团队规范、已验证的解决方案和偏好，供新会话读取。当前面板以查看为主。

12. Skill、Plugin、MCP 与 Agent

Skill

Skill 是可复用的任务说明。Studio 支持以下 Skill 操作：

• 浏览和搜索 Skill
• 安装 Skill
• 通过 Composer 的 $ 菜单选择 Skill
• 查看当前项目或配置目录发现的 Skill

Skill 适合保存代码审查规范、发布 SOP、领域检查表和固定交付流程。MCP 和 Agent 在各自页签中查看。

Plugin

从扩展入口打开“在线市场”。弹窗包含“技能”“工具 (MCP)”和“代理”三个页签；“技能”页的下方还会显示在线市场区域：

• 查看已配置 Marketplace
• 展开插件列表
• 添加 Marketplace 来源
• 安装 Plugin

Plugin 可以扩展工具、Agent、命令或 Skill。可以从在线市场安装 Plugin；创建、调试和更新 Plugin 时，请使用 Engine / CLI 工具。

MCP

打开在线市场的“工具 (MCP)”页：

• 查看 Server 和连接状态
• 添加本地 stdio MCP
• 添加远程 URL MCP
• Connect / Disconnect

通过 MCP 面板添加的 Server 只在当前环境中使用，重新启动后可能需要再次添加。需要长期使用时，请按企业管理员提供的配置流程接入。

Agent

打开在线市场的“代理”页，浏览当前 Engine 提供的 Agent，可按名称、描述或适用情况搜索，再查看类别、角色和使用说明。任务的执行方式从 Composer 的 Plan / Manual / Auto / Trust 菜单选择，规格任务使用“更多 → Spec”。

浏览器与 Browser Use

在右侧面板的“＋”菜单选择 浏览器，打开网页、查看本地预览，并在页面和会话之间切换。

Agent 操作浏览器需要 Studio 与 Engine 的 Browser MCP 集成：

• 由 Studio 自行启动 Engine：客户端会自动尝试接入 Browser MCP；连接成功后，Agent 可打开 URL、读取页面、点击、输入、滚动和截图。
• 复用本机已运行的 Engine：Studio 不会接入这项 Browser Use 集成，右侧浏览器仍可用于手动查看页面。

执行网页操作前，确认 Browser MCP 已连接，再向 Agent 描述要检查的页面和操作目标。连接失败时，检查 Engine 启动方式和连接状态。

13. 设置、主题、通知与快捷键

Studio 本地设置

设置面板包括：

• 主题：System、Light、White、Cream、Green、Dark、Mono
• 字号：Small、Medium、Large
• 自动滚动
• 通知中心（包括后台任务完成提醒）

这些设置属于 Studio 客户端偏好。模型、权限、MCP 和命令由 Engine 配置管理。

常用快捷键

Composer 中：

• Enter：发送
• Shift+Enter：换行
• Esc：停止当前响应

审批卡会优先处理 Enter、Shift+Enter、Esc 和问题选项数字键，避免快捷键误触发其他区域。

14. 常用流程

新项目

1. 添加项目并确认项目路径。
2. 阅读 AGENTS.md、README 和开发规范。
3. 先提出只读问题，要求解释目录和关键数据流。
4. 选择适合的模型和推理深度。
5. 跨模块任务先选择 Plan；需要评审规格的变更从“更多 → Spec”开始。
6. 小任务先选择 Manual 并说明修改范围；确认环境可控后再按需选择 Auto。

实施与验证

1. 用 @ 指定关键文件和测试。
2. 检查 Agent 的 Plan 和工具活动。
3. 敏感操作只在确认路径、命令和影响范围后批准。
4. 在 Terminal 运行相关测试、类型检查和构建。
5. 在 Review 检查 Last turn 和 Uncommitted。
6. 只提交当前任务相关文件。

长任务

• 在已有 Code 会话中通过 /goal 设置持续目标，并从 Goal 条管理进度。
• 使用 Auto 减少低风险审批，但不要在未知仓库或生产环境中盲目放宽权限。
• 将后台服务器和 watcher 放到 Tasks 观察。
• 将独立探索和审查交给子智能体。
• 会话过长时使用 Compact，并先保存关键结论。

安全边界

• 生产环境、密钥、客户数据、付费接口和共享系统先只读分析。
• 不把密码、Token 或凭据直接粘贴进普通会话。
• 任何高权限操作都只应在明确授权且可恢复的隔离环境中执行。
• Discard、删除会话和终止任务前确认是否存在未保存工作。
• Browser Use、MCP 和 Plugin 应只连接可信来源。
• Agent 声称“完成”后仍需通过测试、构建和人工 Review 验证。

15. Studio 与 CLI 如何选择

CLI 专属命令、TUI 快捷键和自动化操作见 CLI 产品手册。