问题定位流程

模块速查

模块	覆盖问题	编号
一、安装与升级	环境、安装失败、版本回退、镜像问题	Q1-Q7
二、登录与设备	企业门户、设备绑定、登录问题、旧登录说明	Q8-Q15
三、模型与 Provider	模型选择、API Key、个人或外部通道、额度	Q16-Q21
四、日常操作	Plan/Build、Auto、Ctrl+C、粘贴、编码	Q22-Q29
五、长任务与后台任务	/goal、Supervisor、后台 Shell、卡住	Q30-Q35
六、安全与旧版本	敏感信息、生产操作、旧问题处理	Q36-Q41

---

一、安装与升级

Q1：安装前需要准备什么？

需要一台可联网电脑、可访问企业登录门户的网络环境，以及 Windows Terminal 或 PowerShell 7+（Windows）或 Terminal（macOS/Linux）。可直接运行官方脚本：

Windows

Windows 上的 PowerShell 和 CMD 是两种并列的一键安装入口，任选一种即可。

PowerShell

irm http://dfcode.codes:8091/install.ps1 -TimeoutSec 120 -ErrorAction Stop | iex

CMD

for %F in ("%TEMP%\dfcode-install-%RANDOM%-%RANDOM%.bat") do (curl.exe -fsSL --connect-timeout 10 --max-time 120 http://dfcode.codes:8091/install/install_win_cmd.bat -o "%~F" && call "%~F")

如果安装过程中弹出 UAC 授权窗口，请点击是。

macOS / Linux

macOS 和 Linux 使用同一条 Unix 命令：

(dfcode_installer="$(mktemp "${TMPDIR:-/tmp}/dfcode-install.XXXXXX")" && trap 'rm -f "$dfcode_installer"' EXIT && curl -fsSL --connect-timeout 10 --max-time 120 http://dfcode.codes:8091/install.sh -o "$dfcode_installer" && test -s "$dfcode_installer" && bash "$dfcode_installer")

• macOS 如果提示安装 Xcode Command Line Tools，按提示完成后重新执行命令。
• Linux 如果需要 sudo 权限，请按终端提示输入密码。

运行对应命令即可完成安装。运行前可打开 URL 查看脚本内容。

Q2：怎么安装 DFCode？

使用 Q1 中对应系统的一键安装命令。

如果需要手动安装，再使用 npm：

npm install -g dfcode@latest --include=optional --registry=https://registry.npmjs.org
dfcode --version

核对程序实际输出的版本。若要固定某个已发布版本，可使用指定版本安装。

脚本下载：install_win.bat、install_win.ps1、fix_win.bat、install_mac.sh。

Q3：node -v 或 npm -v 没反应怎么办？

现象：提示命令找不到、不是内部或外部命令、版本低于 18。

重新安装 Node.js LTS，关闭并重开终端，再执行 node -v 和 npm -v。Windows 如仍失败，检查 PATH。

Q4：npm install -g dfcode 很慢或失败怎么办？

Windows 升级时，只检查本次更新目录中的 DFCode。目标文件被占用时，安装器会显示路径和可查询到的 PID，并停止安装；其他安装目录的会话不受影响。保存工作并正常退出对应的终端、Studio 或 IDE 任务，再运行安装命令，无需卸载或清空缓存。安装器不会自动结束进程或删除历史会话。

升级后回到原项目目录，执行 dfcode -c 继续最近的会话，或启动后输入 /sessions 选择历史会话。退出前请先妥善停止正在执行的任务。

如果提示缺少平台包或依赖，使用官方源重新安装，并包含可选依赖：

npm install -g dfcode@latest --include=optional --registry=https://registry.npmjs.org
dfcode --version

镜像需要同时包含目标版本的主包和平台包。缺包时查看安装日志，不要先卸载已有版本或清空全局缓存。

官方源优先，版本查询、安装和重试共用 10 分钟等待时间。单次请求最多等待 5 分钟、最多重试两次；临时网络失败还会在剩余时间内再尝试一次安装。每 15 秒显示当前阶段和已用时间。

网络重试失败或超时后，依次尝试华为云、腾讯云。镜像包的版本和完整性必须通过独立的官方信息校验；校验失败则停止。文件占用、权限、空间不足和启动错误不会触发换源。

需要手动指定备用源时：

npm install -g dfcode@latest --include=optional --registry=https://repo.huaweicloud.com/repository/npm
npm install -g dfcode@latest --include=optional --registry=https://mirrors.cloud.tencent.com/npm

安装后显示错误版本：

安装后，dfcode/node_modules 目录为空：

安装后提示路径不是内部或外部命令，也不是可运行的程序：

Q5：升级后版本反而变旧怎么办？

先用官方源安装明确版本，避免镜像渠道滞后：

npm install -g dfcode@3.3.19 --include=optional --registry=https://registry.npmjs.org
dfcode --version

预期输出 3.3.19。一键安装器默认保留更高的可运行版本；显式指定 DFCODE_VERSION 时按该版本安装。

Q6：稳定版和 beta 版有什么区别？

DFCode 提供稳定版和 beta 双渠道。稳定版适合日常使用；beta 用于先行验证新功能。升级不会跨渠道自动降级。普通用户建议使用当前稳定版。

当前正式版为 3.3.19，beta 为 3.3.17-beta.2。beta 用户切换到正式版时执行：

npm install -g dfcode@stable --include=optional --registry=https://registry.npmjs.org
dfcode --version

Windows PowerShell 若拦截 npm.ps1，使用 npm.cmd 执行相同参数。

Q7：如何确认当前版本？

dfcode -v

需要排障时，先升级到最新版，避免把已修复问题当成当前问题。

---

二、登录与设备

Q8：默认怎么登录？

在 TUI 输入 /login，按企业门户提示完成浏览器登录和设备绑定。登录成功后保持客户端打开，企业 MaaS Provider 会自动注册，可用模型会出现在 /models 中。

Q9：还需要填写工号和姓名吗？

当前登录在企业门户完成身份验证和设备绑定，是否需要补充信息以门户页面提示为准。

Q10：/login 卡住或没反应怎么办？

请先确认浏览器能正常打开企业门户，并检查网络、代理、项目路径和设备名是否包含特殊字符。

图中红框标出的路径、文件名和设备名需使用英文。

Q11：浏览器登录完成后 TUI 没刷新怎么办？

登录和登出后，TUI 会自动刷新状态。浏览器已完成登录但 TUI 未更新时：

1. 确认 dfcode -v 已是最新版。
2. 确认浏览器企业门户页面已完成认证，并回到终端查看状态。
3. 检查代理、浏览器默认打开策略和企业门户访问；HTTP 429 或临时网络错误时，等待退避重试。
4. 身份验证成功但模型配置或授权尚未就绪时，保留登录状态，稍后再查看 /models。明确提示凭据失效时重新 /login；账号被禁用时联系管理员。

3.3.18 起不会因临时网络故障或可恢复的上游错误直接清除有效凭据，无需先 /logout。

Q12：设备绑定是什么意思？

每个账号默认最多绑定 2 台设备，设备指纹按设备生成。换电脑前先执行 /logout。

Q13：提示设备数量已满怎么办？

先确认旧电脑是否还登录；能操作旧设备时执行 /logout。不能操作时联系管理员解绑。不要复制他人 token 或配置文件。

Q14：怎么注销？

在 TUI 输入：

/logout

注销当前设备后，如需继续使用，再 /login。

Q15：非企业用户怎么登录？

非企业用户可用 /connect 连接 Provider，或 /relay 添加 OpenAI 兼容端点；CLI 侧也可使用 dfcode auth login。这类个人或外部通道通常需要自行准备凭证。关于使用该类方式的数据安全问题，请参考条款与协议。

---

三、模型与 Provider

Q16：为什么我不用填 API Key？

企业用户默认使用公司配置的模型通道。登录后，企业 MaaS Provider 会自动注册，模型在 /models 中选择。

Q17：什么时候需要 API Key？

只有使用 /connect 或 /relay 接入个人或外部 Provider、自建端点或第三方模型服务时，才可能需要 API Key。使用前要确认成本、额度、合规和数据边界。

Q18：怎么切换模型？

在 TUI 输入：

/models

选择适合当前任务的模型。复杂任务选能力更强的模型，普通解释和文档任务可选更快的模型。

Q19：如何打开模型列表？

在 TUI 输入 /models，再选择模型并按回车确认。

Q20：怎么调整推理深度？

输入：

/effort

复杂设计、跨文件重构可提高推理深度；简单改文案或查信息可降低。

Q21：怎么查看用量？

可通过命令行或企业个人门户查询用量。两者的统计周期不同，数据可能有差异，以企业个人门户为准。

打开新的终端窗口，输入：

dfcode stats --days 7

可按模型、工具、项目查看 token 和成本统计。

企业额度可从登录页面进入个人门户查看；有疑问时联系管理员。

---

四、日常操作

Q22：Plan 和 Build 怎么选？

大任务、架构调整、涉及多个模块时先用 Plan；小修小改、明确 bug、文档更新可以直接 Build。Plan 模式只规划，不改文件。

Q23：Auto 模式安全吗？

/auto 会自动放行低风险操作，破坏性或敏感操作仍会询问。适合测试、构建、常规编辑等长任务，但涉及生产、密钥、删除数据时仍应人工确认。

Q24：Ctrl+C 现在是什么行为？

Windows 和 macOS 的默认终端行为不同。

Windows：有选中内容时，Ctrl+C 复制选中内容；没有选中内容但输入框有内容时，Ctrl+C 清空输入框；输入框为空时，连续按两次 Ctrl+C 退出 DFCode。

macOS：输入框有内容时，Ctrl+C 清空输入框；输入框为空时，连续按两次 Ctrl+C 退出 DFCode。

单击 Ctrl+C 导致闪退的问题，请先升级到最新版。

Q25：老项目中文文件乱码怎么办？

DFCode 支持 GBK、GB18030、Shift-JIS、Big5 等编码。仍有乱码时，在项目根目录修改或新建 dfcode.jsonc：

{
  "files": { "encoding": "gbk" },
}

Q26：鼠标滚动或点击失灵怎么办？

Windows 偶发鼠标跟踪异常时输入：

/mouse

Q27：长按 Backspace 删除太快怎么办？

长按 Backspace 会加速删除；短草稿仍保留误触保护。仍不习惯时使用：

/fastdelete

Q28：怎么统一改主题、侧栏、时间戳等显示？

输入：

/config

统一设置面板可管理主题、深浅色、模型、思考过程、工具详情、时间戳、动画、滚动条、终端标题、提示条、侧栏和 Worker 面板。

Q29：怎么临时问一个旁支问题？

用 /btw：

/btw 这个报错和当前任务有没有关系？

这条问题不会加入主任务上下文，也不会打断主任务。

---

五、长任务与后台任务

Q30：任务看起来卡住了怎么办？

DFCode 会显示进度并提示慢响应。先看 TUI 底栏活动指示器；如果上游模型变慢，界面会给出原因，进程卡死时会尝试恢复。

Q31：怎么让 DFCode 持续朝一个目标推进？

用 /goal：

/goal 持续修复当前项目的测试失败，直到测试通过或说明无法继续

可用 /goal status、/goal pause、/goal resume、/goal clear 管理。

Q32：怎么让 DFCode 持续修复直到测试通过？

用 Supervisor：

dfcode supervise "修复测试直到通过" --verify "npm test" --max-turns 8

适合有明确验收命令的任务。

Q33：怎么跑后台服务或监听日志？

长命令可放到后台 Shell。用 /bashes 查看后台任务；输出出现 [CHANGE]、[ERROR] 等标记时，Monitor 会将变化提示到当前会话。

3.3.18 中，等待超时会返回期间到达的输出，后台进程继续运行。开发服务器等常驻进程用就绪或健康检查确认启动，无需等待退出。若提示输出不完整，说明部分内容已被缓冲区丢弃，保存的文件也可能只有保留部分。

Q34：后台任务会不会一直占资源？

后台 Shell 使用环形缓冲，并会清理孤儿进程。任务结束后仍应停止不再需要的 watcher、dev server 和日志跟踪。

Q35：上下文满了怎么办？

DFCode 会自动压缩上下文，也可以手动 /compact。压缩后的旧内容会保存到记忆归档，需要时可召回。

---

六、安全与旧版本

Q36：能让 DFCode 直接操作生产环境吗？

不要直接在生产环境启用自动执行。涉及生产、数据库、密钥、付费资源或客户数据时，先执行只读分析，再由人工确认执行。

Q37：敏感信息能贴进对话吗？

不要贴明文密钥、客户隐私、生产 token、内部敏感配置。必须分析时先脱敏，并说明哪些字段被替换。

Q38：旧版登录说明还适用吗？

当前版本通过企业门户登录。旧说明中的步骤可能已变更，按当前客户端和企业门户提示操作。

Q39：遇到 Ctrl+C 异常、粘贴失败或登录冻结怎么办？

先执行 dfcode upgrade 升级，再检查终端版本和系统环境。当前版本的 Ctrl+C 行为见 Q24；仍有异常时，记录复现步骤和报错信息交给支持人员。

Q40：Team 模式为什么不能直接用？

当前 Team 功能默认关闭，需要设置 DFCODE_ENABLE_TEAM。普通用户先使用 Plan/Build/Auto 即可。

Q41：仍解决不了时应该给支持人员什么信息？

提供：

• dfcode -v 输出。
• 操作系统和终端。
• 触发问题的命令。
• 关键报错文本、登录页面提示或 TUI 状态信息。
• 截图或日志片段。
• 是否使用代理、镜像源、个人 Provider。

---