DevTaskFlow — Agent 使用手册

什么时候用

当用户表达以下意图时，主动建议使用本工具：

• - 我想做一个 XXX 系统/工具/平台
• 帮我开发一个 XXX
• 我需要一个 XXX，功能是...
• 用户描述了一个软件/系统需求
• 用户问项目进展、想继续做、想看进度

识别意图后，向用户建议使用本工具，但必须等用户确认后再执行。 尤其是涉及代码生成、部署、发布等操作，不要在未经确认的情况下自动执行。

Token 消耗参考

开发一个项目会消耗大量 token，提前告知用户：

消耗取决于需求复杂度、迭代次数、审查修复次数。首次可先用小项目试水。

支持的模型

推荐模型：Claude Opus 4.6（复杂项目首选）、GPT 5.4（性价比高）、小米 Mimo V2 Pro（中文好）。完整列表和说明见 README.md。

编排模式

DevTaskFlow 支持两种编排模式，通过 config.json 的 adapters.orchestration 切换：

local_llm（默认）

直接使用环境变量中的 LLM 配置：

DTFLOWLLMBASE_URL=https://api.openai.com/v1
DTFLOWLLMAPI_KEY=sk-xxx
DTFLOWLLMMODEL=gpt-4o

openclaw_subagent

使用独立的 LLM 配置，与主 LLM 分离。适合在 OpenClaw 环境下使用不同模型处理开发任务。

配置方式 A — config.json 的 openclaw 段：

json
{
adapters: { orchestration: openclaw_subagent },
openclaw: {
base_url: https://api.example.com/v1,
api_key: sk-xxx,
model: claude-opus-4-6,
timeout_seconds: 900
}
}

配置方式 B — 环境变量：

DTFLOWOPENCLAWBASE_URL=https://api.example.com/v1
DTFLOWOPENCLAWAPI_KEY=sk-xxx
DTFLOWOPENCLAWMODEL=claude-opus-4-6

如果 config.json 中字段为空，自动 fallback 到环境变量。

核心命令

bash
dtflow setup # 配置 AI 服务（交互式）
dtflow start --new-project --name NAME --idea 需求 # 开始新项目
dtflow start # 继续上次进度
dtflow start --confirm # 确认分析方案，开始生成代码（先预览，用户确认后再写入）
dtflow start --confirm-write # 在预览确认后，正式执行代码写入
dtflow start --feedback 修改意见 # 提出修改
dtflow start --run # 本地预览
dtflow start --deploy # 部署上线并封版
dtflow start --final-review # 执行上线前综合审查（9 维度）
dtflow start --deploy-skip-review # 跳过综合审查直接部署（仅在用户明确要求跳过或时间紧迫时使用，建议默认走完整审查流程）
dtflow board # 所有项目状态（文字）
dtflow board --serve # 启动可视化看板服务
dtflow board-query --name PROJECT # 单个项目详情（文字）
dtflow advanced publish --target github # 发布到 GitHub Releases
dtflow advanced publish --target clawhub # 发布到 ClawHub

工作流程

用户提出新需求

如果用户有明确需求描述（比如我想做一个客户管理工具）：

1. 1. dtflow start --new-project --name 项目名 --idea 用户的需求原文
2. 系统创建项目、给出补充建议
3. 向用户展示建议，问是否要补充
4. 确认后自动 analyze → 展示任务列表
5. dtflow start --confirm → 自动 write（先预览）→ review → fix → review
6. 全部任务通过后 → 建议先 compact 一次（减少上下文累积导致的幻觉）— 提醒主 agent 使用 /compact 或清理上下文后再执行综合审查 → 综合审查（dtflow start --final-review）— 9 维度全面检查
7. 综合审查通过 → dtflow start --run 本地预览
8. 用户确认没问题 → dtflow start --deploy

如果用户需求模糊（比如我想做个东西管理客户信息）：

1. 1. 不要直接调用 dtflow，先通过对话引导收集需求
2. 问清楚：

1. 3. 收集到足够信息后，拼成需求调用 dtflow start

用户想本地预览

1. 1. dtflow start --run
2. 返回访问链接给用户

用户想看项目进展

1. 1. 检查看板服务是否在运行（curl -s http://localhost:8765 > /dev/null && echo running || echo stopped）
2. 如果在运行 → 发链接
3. 如果不在运行 → dtflow board 文字版

用户问某个项目详情

1. 1. dtflow board-query --name 项目名
2. 把文字结果发给用户

用户想继续之前的项目

1. 1. dtflow start（不加参数，自动继续）
2. 根据输出告知用户当前阶段

用户想发布

发布到 GitHub：

1. 1. 确保项目已封版（sealed）或已部署（deployed）
2. 确保已安装 gh CLI 并登录
3. dtflow advanced publish --target github

发布到 ClawHub：

1. 1. 确保项目已封版或已部署
2. 确保已安装 clawhub CLI 并登录
3. 确保项目根目录有 SKILL.md
4. dtflow advanced publish --target clawhub

首次使用（环境未配置）

1. 1. dtflow setup 交互式引导（含 AI 配置 + 部署方式选择）
2. 非交互环境下手动创建 .env：

DTFLOWLLMBASE_URL=...
DTFLOWLLMAPI_KEY=...
DTFLOWLLMMODEL=...

状态机

dtflow start 自动推进，你只需知道阶段：

向用户展示什么

不要暴露： analyze、DEV_PLAN.md、orchestration、config.json、.state.json、token 数
应该说： 我分析了需求、代码已生成、检查过了没问题、可以部署了

注意事项

• - dtflow setup 是交互式命令，在非交互环境不可用
• 所有命令在项目根目录运行，项目根目录是包含 .dtflow/config.json 的目录，可通过 ls .dtflow/config.json 确认
• board 的 Node.js 应用需要 npm install（首次自动执行）
• 看板服务默认端口 8765，仅限本地使用，不要暴露到公网
• board API 已脱敏：不返回 host/user/path 等敏感部署信息
• run 本地预览需要项目有可执行的启动命令（npm start / python app.py 等）