适用于 DFCode 3.3.19。模型和命令由当前版本和企业配置决定。

使用顺序

安装、企业登录与 Provider 配置见登录与部署。

1. DFCode 是什么

DFCode 是终端中的 AI 编码助手，支持读取项目、搜索代码、编辑文件和运行命令。跨模块需求先用 Plan 分析；需要留存规格时使用 Spec，再执行修改。

2. 快速开始

安装

CLI 支持 Windows、macOS 和 Linux。选择一种安装方式即可，不要重复执行。

方式一：命令行一键安装（推荐）

选择对应系统的一条命令完成安装和校验，不需要先手动安装 Node.js 或执行 npm 安装命令：

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 权限，请按终端提示输入密码。

方式二：下载文件后运行

• Windows：把 install_win.bat 和 install_win.ps1 下载到同一个文件夹，双击 install_win.bat；只使用 CMD 时可下载 install_win_cmd.bat。
• macOS：下载 install_mac.sh，在 Terminal 中执行 bash ~/Downloads/install_mac.sh。
• Linux：下载 install_mac.sh，在终端中执行 bash ~/Downloads/install_mac.sh；如果文件位于其他目录，请替换为实际路径。

方式三：手动安装 Node.js 后使用 npm

• Windows：先安装 Node.js 18 或更高版本，再在 PowerShell 中使用 npm.cmd install -g dfcode@latest --include=optional --registry=https://registry.npmjs.org。
• macOS：先通过 Homebrew 或 nvm 安装 Node.js 18 或更高版本。
• Linux：先通过发行版包管理器或 nvm 安装 Node.js 18 或更高版本。

macOS 和 Linux 在 Node.js 准备好后执行：

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

三个系统安装完成后都执行 dfcode --version 验证，本次正式版预期输出 3.3.19。已有 beta 安装可用 npm install -g dfcode@stable --include=optional --registry=https://registry.npmjs.org 切换到正式版。完整步骤、前置条件和故障处理见登录与部署。

启动、登录和选模型

在项目根目录启动：

dfcode /path/to/project

进入 TUI 后：

1. 输入 /login，在企业门户完成登录和设备绑定。
2. 输入 /models，选择当前账号可用的模型；再用 /effort 调整该模型的推理深度。
3. 输入 /init，由 DFCode 读取项目并生成或更新 AGENTS.md。
4. 先提出一个只读问题，确认项目路径和上下文都正确。

1. 企业登录

输入 /login 后，在打开的浏览器中完成企业登录和设备绑定。保持终端打开，等 CLI 返回“登录成功”。

登录后遇到临时断网、HTTP 429 或可恢复的上游错误时，DFCode 会保留有效凭据并等待重试。模型配置或授权尚未就绪时，稍后再查看 /models。

2. 模型与推理深度

输入 /models，从账号可用的模型中选择。

输入 /effort 调整推理深度。可用档位取决于所选模型。

3. 初始化项目规则

输入 /init，生成或更新 AGENTS.md，核对其中的目录和命令。

$ git diff --check

4. 只读确认

提出一个只读问题，检查项目路径、目录结构和常用命令。

3. 工作方式与授权策略

工作方式与授权策略分别设置。例如，Plan + Manual 先分析并逐项确认；Build + Auto 在限定范围内修改代码。

Build：直接完成明确的小任务

Build 直接执行任务，适合修复函数、补充测试或修改文档。提示词中写明文件范围、验收标准和禁止事项。

请修复 src/auth/token.ts 中的过期判断，补充对应单元测试。
只修改 auth 模块，不改数据库和依赖；完成后运行相关测试并报告结果。

Plan：先分析，再决定是否执行

需求尚未明确或涉及多个模块时，先用 Plan 读取代码，列出修改范围、顺序和测试方式。

操作步骤：

1. 说明目标、现状、验收标准和限制。
2. 要求先只读检查，不要直接编辑文件。
3. 审查文件清单、兼容风险和测试计划。
4. 确认方案后切换到 Build，再执行改动。

Spec：把大型变更写成规格

Spec 用于需要规格评审的变更。输入 /spec 进入，输入 /unspec 返回 Build。

$ git diff --check

/spec

请为“设备绑定恢复”创建规格驱动变更。
先只读检查现有登录、设备状态和错误提示实现，说明 Why、What 和 Grounding；
然后整理 specs/changes/device-binding-recovery/，至少包含 proposal.md、tasks.md，
以及 deltas/authentication/spec.md。需求用 Given / When / Then 写清楚登录失败、
恢复绑定、重复提交和旧设备状态四类场景。先校验规格文档，不要直接修改业务代码。

规格保存在项目目录中；评审通过后再实施。

4. 授权策略：Manual、Auto 和 Trust

授权策略决定工具调用是否需要确认。

Manual：默认的逐项确认

Manual 会在需要权限的工具调用前询问。适合第一次接触的项目、访问密钥和项目外路径、需要逐步检查的任务，以及生产仓库或不可逆操作。

确认前检查目标路径、实际命令和执行后果。

Auto：让低风险操作连续完成

Auto 结合安全分类器、允许列表和熔断保护处理工具调用。低风险的读取、搜索和测试可自动放行；涉及依赖、部署或敏感文件时，需检查具体操作。

用 /auto 切换 Auto。Auto 与 Trust 独立设置：Auto 检查工具调用的风险，Trust 跳过常规权限确认和安全分类。

$ npm test -- form

RUN  v4.1.9 /projects/web-portal
❯ test/form.test.ts (16 tests | 2 failed)
Tests  2 failed | 14 passed (16)
Duration  482ms

$ npm test -- form

RUN  v4.1.9 /projects/web-portal
✓ test/form.test.ts (16 tests)
Test Files  1 passed (1)
Tests  16 passed (16)
Duration  395ms

运行相关测试并修复表单校验问题。
只修改 src/forms，不改依赖、部署配置、密钥和数据库迁移；测试失败时先说明原因。

Trust：明确授权后的连续执行

输入 /trust 可以进入 Trust，/notrust 或 /untrust 可以关闭。启动参数也支持 --trust-all。

Trust 会跳过常规权限确认和 Auto 安全分类，可能影响文件编辑、关键项目文件、.env、项目外路径、Shell 和 MCP 等操作。启用前会显示高风险说明；确认后仍保留失控循环保护。

$ git status --short --branch

## experiment/v3

$ git diff --check

只在可丢弃或可回滚的隔离工作区中使用 Trust。启用前移除生产凭据、客户数据和密钥，写明允许路径、禁止命令和停止条件。完成后关闭 Trust，检查 diff。不要在生产仓库或不可逆操作中使用。

5. 长任务：Goal、Supervisor 和后台 Shell

Goal：给会话绑定一个持续目标

Goal 按同一目标连续执行多轮任务。设置 Goal 会自动开启 Auto，执行前确认工作区、文件范围和验证命令。

/goal 持续修复当前分支的 TypeScript 和单元测试问题，直到 npm test 通过。
不要提交代码；遇到需要改数据库迁移的情况先暂停并报告。

常用操作：

/goal status
/goal pause
/goal resume
/goal clear

目标中写明验证命令、文件范围和停止条件。

$ npm test

RUN  v4.1.9 /projects/checkout-service
❯ test/payment-race.test.ts (12 tests | 1 failed)
Tests  1 failed | 183 passed (184)
Duration  1.82s

$ npm test && npm run typecheck

RUN  v4.1.9 /projects/checkout-service
✓ test/payment-race.test.ts (12 tests)
Test Files  14 passed (14)
Tests  184 passed (184)
Duration  1.75s

> typecheck
> tsc --noEmit

Supervisor：由验证命令驱动多轮任务

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

验证失败时继续执行，通过或达到轮数上限时停止。运行前清理无关改动，结束后检查 diff。迁移、发布和提交仍需人工确认。

$ dfcode supervise "修复测试直到通过；不要提交代码" --verify "npm test" --max-turns 8

supervise: local server on http://127.0.0.1:43219
[supervise] supervisor.sse.connected 
[supervise] supervisor.turn.start {"turn":1,"sessionID":"ses_demo"}
[supervise] supervisor.turn.end {"turn":1,"reason":"idle","stalled":false,"errors":0}
[supervise] verify: FAIL
[supervise] supervisor.judged {"turn":1,"decision":"continue"}
[supervise] supervisor.turn.start {"turn":2,"sessionID":"ses_demo"}
[supervise] supervisor.turn.end {"turn":2,"reason":"idle","stalled":false,"errors":0}
[supervise] verify: FAIL
[supervise] supervisor.judged {"turn":2,"decision":"continue"}
[supervise] supervisor.turn.start {"turn":3,"sessionID":"ses_demo"}
[supervise] supervisor.turn.end {"turn":3,"reason":"idle","stalled":false,"errors":0}
[supervise] verify: PASS
[supervise] supervisor.judged {"turn":3,"decision":"done"}

[supervise] FINAL: {"status":"done","reason":"verify command passed","turns":3,"sessionID":"ses_demo"}

后台 Shell：服务和 watcher 放到后台

开发服务器、日志跟踪和长时间测试可在后台运行。用 /bashes 查看任务、读取输出或停止进程。

请启动开发服务器并在后台观察日志。如果出现 ERROR 或 FAIL，先报告原因；
不要自动修改生产配置。任务完成后停止后台进程。

任务完成后停止后台进程。遇到端口冲突时，用 /bashes 检查已有进程。

等待后台结果超时不会终止进程，期间到达的输出仍会返回。常驻服务用就绪或健康检查确认启动；有其他独立工作时可先继续，依赖结果时再进行有时限的等待。

输出超出缓冲区容量时，结果、保存文件和完成通知会标明内容不完整。bash_output 过滤只覆盖仍保留的未读输出，每次读取都会推进游标。立即读取使用 block: false 或省略 block；timeout 以毫秒计，范围为 1–2147483647，不接受 0。

6. 常用命令与 TUI 操作

审查请求可以直接发给主会话；/review 则启动独立子任务。

$ git diff --stat

 src/export/service.ts | 2 ++
 1 file changed, 2 insertions(+)

$ git diff -- src/export/service.ts

diff --git a/src/export/service.ts b/src/export/service.ts
index 84b1a72..52f8c01 100644
--- a/src/export/service.ts
+++ b/src/export/service.ts
@@ -10,3 +10,5 @@
 export async function exportUsers(ctx: Context) {
+  await requirePermission(ctx, "users:export");
+  ctx.response.type = "text/csv";
   return streamUsers(ctx);
 }

$ npm test -- export

RUN  v4.1.9 /projects/admin-console
✓ test/export.test.ts (12 tests)
Test Files  1 passed (1)
Tests  12 passed (12)
Duration  514ms

CLI 子命令：

dfcode /path/to/project
dfcode upgrade
dfcode supervise "目标" --verify "验证命令" --max-turns 8

TUI 中可从 Composer 选择文件、命令、Skill 和附件：

• 用 @ 引用项目上下文。
• 用 / 查找命令。
• 用 $ 选择 Skill。

长会话可用 /btw、Timeline、Compact 或 Fork 管理上下文。

7. 配置、扩展与项目规则

AGENTS.md 和项目规则

/init 生成的 AGENTS.md 用来记录技术栈、启动命令、测试命令、目录边界和禁止事项。提交前人工检查其中的路径、命令和敏感信息；过时规则会直接影响后续任务。

Skill、Plugin、MCP 与 Memory

• Skill：可复用的任务指令。
• Plugin：包含命令、Skill、MCP 等扩展。
• MCP：连接外部工具和数据源。
• Memory：保存整理后的项目上下文，使用前仍需核对事实。

启用扩展前，检查它需要访问的文件、网络和外部系统。

老项目可能包含 GBK、GB18030、Shift-JIS 或 Big5 文件。先只读识别编码，再小范围转换和验证。 不要把整个仓库一次性转成 UTF-8。处理 .env、证书和本地配置时，限制路径并优先只读检查。

8. 从旧版升级到 3.3.x

升级后，用 /models 检查模型配置，重新确认 Manual、Auto 或 Trust 的选择。旧脚本中的命令和参数请对照 dfcode --help 或 TUI 的 /help 检查。

9. 日常检查清单

• 开始前：确认项目路径、分支、规则文件和 git status。
• 执行中：写清目标、文件范围、禁止事项和验证命令；需要扩大范围时先暂停。
• 提交前：检查 diff 和测试结果，停止无用的后台进程，排除密钥、临时文件及无关改动。