命令与配置见CLI 产品手册。桌面客户端的操作见 Studio 场景示例。

使用前先做三项检查

1. 在正确的项目目录和分支启动 DFCode。
2. 先看 git status，确认没有把无关改动交给工具。
3. 把“允许改什么、不能改什么、如何验证、何时停止”写进任务描述。

场景一：用 /init 接入一个新项目

首次在仓库中使用 DFCode，或项目规则已经过时。

1. 在项目根目录启动 dfcode。
2. 输入 /init，生成或更新 AGENTS.md。
3. 人工补充技术栈、测试命令、目录边界和禁止事项。
4. 先提出一个只读问题，核对它识别出的项目结构。

请阅读当前项目，说明主要模块、启动命令、测试命令和开发注意事项。
只修改 AGENTS.md，不修改业务代码；不确定的内容标记为待确认。

$ git diff --check

AGENTS.md 中的模块、路径和命令与项目一致。

如果项目根目录、包管理器或测试命令识别错了，先修正规则文件，不要继续执行改动。

场景二：Plan → Build 完成一个中型需求

需求跨越多个文件，但还不需要建立长期规格。

1. 进入 Plan，先只读分析影响范围。
2. 要求计划包含文件清单、接口兼容风险、测试方式和回滚点。
3. 审查计划，补充不可修改范围。
4. 确认后切换到 Build 执行，再运行验证命令。

请为“新增用户导出功能”制定实施计划。
先只读分析，不要修改文件。计划列出会改哪些文件、接口兼容风险、测试方式和回滚方案。
确认计划后再执行；不要修改数据库迁移和部署配置。

改动与确认后的文件清单一致，验证命令通过。

计划发现需要改数据库结构、权限模型或外部接口时，先扩大评审范围，不要直接切换 Build。

场景三：用 Auto 自动完成低风险测试修复

测试命令明确、修改范围可控时，可减少读取、搜索和普通测试的逐项确认。

1. 先在 Manual 下确认项目和测试命令。
2. 输入 /auto，明确允许修改的目录和禁止操作。
3. 先运行相关测试，再修复失败项。
4. 测试通过后回到 Manual，检查 diff。

/auto

运行当前表单模块的测试并修复失败用例。
只修改 src/forms 和对应测试，不改依赖、部署配置、密钥和数据库迁移。
每轮修复后运行 npm test -- form；如果需要扩大范围，先暂停并说明原因。

$ 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

相关测试通过，diff 只涉及约定的目录。

分类器提示高风险、测试表现出数据破坏可能，或需要修改依赖和部署文件时，退出 Auto 并人工判断。

场景四：在隔离工作区使用 Trust

临时 worktree 中需要连续运行大量可回滚操作，且已经确认目录不含生产凭据。

1. 创建或切换到可丢弃的隔离 worktree。
2. 检查路径、凭据和当前分支。
3. 输入 /trust，阅读高风险授权说明后再确认。
4. 任务完成后输入 /notrust，检查 diff 和测试结果。

/trust

在当前临时 worktree 中完成迁移脚本重构。
只修改 src/migrations，不提交、不推送、不访问生产凭据；遇到删除数据、改部署或访问项目外路径时立即停止。

$ git status --short --branch

## experiment/v3

$ git diff --check

脚本修改和测试在隔离 worktree 中完成。

目录不可回滚、发现 .env 或客户数据、需要生产访问，立即关闭 Trust，回到 Manual。

场景五：用 Spec 推进大型变更

跨模块变更，需要评审需求、设计和实施任务。

1. 输入 /spec。
2. 先检查真实实现和现有测试。
3. 形成 proposal.md，确认 Why、What、Grounding 和边界。
4. 把需求写成 Given / When / Then，整理 tasks.md 和 capability delta。
5. 评审通过后进入 apply，按任务逐项实现。
6. 完成后运行验证并 archive；需要回到普通会话时输入 /unspec。

/spec

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

$ git diff --check

提案、需求 delta 和任务清单已保存；实现与批准的规格一致。

无法从代码和测试确认关键事实时，停在 explore 或 propose，不要用猜测填充规格。

场景六：用 Goal 持续修复直到验证通过

需要多轮修复，并使用固定的测试命令验证结果。

1. 写出目标、验证命令、禁止事项和停止条件。
2. 输入 /goal <目标>。
3. 用 /goal status 查看进度，需要人工判断时 /goal pause。
4. 通过后运行 /goal clear，检查最终 diff。

设置 Goal 会自动进入 Auto。执行前先确认当前工作区和授权边界。

/goal 持续修复当前分支的 TypeScript 和单元测试问题，直到 npm test 通过。
不要提交代码；不改数据库迁移；如果连续两轮没有进展就暂停并报告。

验证通过或触发停止条件时，任务结束并保留执行记录。

测试命令不稳定、连续轮次没有进展、需要扩大修改范围或出现危险操作时暂停。

$ 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

运行前确认：工作区没有无关改动，验证命令可以独立执行，最大轮数符合任务规模。

$ 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"}

验证失败时继续尝试，验证通过或达到 8 轮后停止。

不要把发布、删除数据、修改生产配置和提交代码放进无监督循环；达到上限仍未通过时保留现场，人工接手。

场景八：后台启动开发服务器并观察日志

需要 dev server、watcher 或长时间测试，同时继续处理主任务。

请启动开发服务器并在后台观察日志。
出现 ERROR 或 FAIL 时先报告最近的日志和可能原因，不要自动修改生产配置。
任务结束后停止后台进程。

1. 将服务放到后台运行。
2. 用 /bashes 查看进程、输出和状态。
3. 发现错误后回到主会话定位；不要反复启动相同服务。
4. 完成后停止后台任务，确认端口已经释放。

确认服务可访问、日志可读取，停止后端口已释放。

日志持续增长、进程失控、端口冲突或服务访问真实数据时，立即停止并人工检查。

场景九：用 /btw 处理旁支问题

主任务进行中，需要临时询问错误码、函数或设计背景。

/btw 这个项目里的 RetryableError 和 FatalError 有什么区别？只解释，不修改文件。

回答出现在 BTW 侧栏，主任务继续执行。

如果旁支问题需要改代码、运行破坏性命令或改变主任务范围，回到主会话重新提出，并先更新计划。

场景十：提交前做一次 Review

代码已修改，准备提交、合并或创建 PR。

1. 先查看 git diff 和 git status。
2. 输入 /review 当前改动。
3. 按优先级处理审查结果。
4. 重新运行测试、构建或相关检查。
5. 人工决定是否 commit、push 或发布。

/review 当前改动

重点检查：功能回归、错误处理、权限边界、测试缺口、日志中的敏感信息和不相关文件。
只给出问题和证据，不要自动提交或推送。

审查问题已处理，相关测试通过。

审查发现改动范围失控、测试未通过或包含敏感信息时，不要提交，先回到 Plan 或 Manual 处理。

审查请求可以直接发给主会话；/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

任务提示词模板

目标：
项目范围：
允许修改：
禁止修改：
验证命令：
完成标准：
停止条件：
是否允许提交：否