@bicorne/task-flow

当用户要求实现新功能、修复 Bug、重构代码，或需要生成需求文档、设计方案、拆分任务时，使用此工具。提供从需求梳理到代码实现、审查合并的全流程工作流，通过 Git worktree 实现零冲突并行开发。

核心特性

• 🤖 AI-First 设计：支持 Slash Commands，在 AI 对话中直接执行任务
• 🌳 零冲突开发：基于 Git worktree 实现多任务并行开发
• 📋 标准化流程：从需求分析到代码合并的完整工作流
• 🔄 Hooks 机制：支持生命周期钩子，实现自动化检查和验证
• 📦 标准任务格式：PHASE-*.json 格式，支持依赖管理和进度跟踪

安装

# 全局安装（推荐）
npm install -g @bicorne/task-flow

# 或使用 pnpm
pnpm add -g @bicorne/task-flow

# 或使用 npx（无需安装）
npx @bicorne/task-flow init

系统要求：

| 依赖 | 版本 | 说明 | |------|------|------| | Node.js | >= 24.14.0 | CLI 运行环境 | | Git | >= 2.17 | worktree 功能依赖 | | Bash | >= 4.0 | 引导脚本依赖 |

Git 配置（worktree 测试需要）：

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

快速开始

方式一：Slash Commands（推荐）

在 AI 对话中直接输入命令，AI 会自动识别并执行：

# 1. 初始化项目
/tf:init

# 2. 从用户需求生成 PRD
/tf:propose my-feature --input "实现用户登录功能"

# 3. AI 审查并编辑生成的 PRD

# 4. 生成技术设计（可选）
/tf:design my-feature

# 5. 应用并创建工作区
/tf:apply my-feature

# 6. 在工作区中编码实现
cd .worktrees/harness-feat-my-feature

# 7. 任务完成确认（Hook 自动触发，AI 询问用户确认）
# Trae IDE: 使用 AskUserQuestion 工具
# 其他平台: 对话确认或 /tf:confirm --yes

# 8. 完成后合并
cd ../..
/tf:merge my-feature

# 9. 归档
/tf:archive my-feature

方式二：传统 CLI 命令

# 1. 初始化项目
task-flow init

# 2. 从用户需求生成 PRD
task-flow propose --change my-feature --input "实现用户登录功能"

# 3. AI 审查并编辑 PRD 文档
# 文件位置: spec/changes/my-feature/product-requirement.md

# 4. 生成技术设计（可选）
task-flow design --change my-feature

# 5. 生成任务文件
task-flow tasks --change my-feature --yes

# 6. 创建隔离工作区
task-flow worktree --change my-feature --yes

# 7. 在工作区中开发
cd .worktrees/harness-feat-my-feature

# 8. 任务完成确认
task-flow confirm --yes

# 9. 完成后合并
cd ../..
task-flow merge my-feature

命令速查

| CLI 命令 | Slash 形式 | 说明 | 关键参数 | |---------|-----------|------|----------| | init | /tf:init | 初始化项目 | --force 强制覆盖 | | analyze | - | 扫描项目生成 context | 默认输出到 .harness/context.json | | propose | /tf:propose <name> | 生成 PRD 文档 | --change <name> --input <text> | | design | /tf:design <name> | 生成技术设计 | --change <name> --skip-prompt | | tasks | /tf:tasks <name> | 生成任务文件 | --change <name> --yes --input <json> | | worktree | /tf:worktree <name> | 创建隔离工作区 | --change <name> --yes | | apply | /tf:apply <name> | 应用并创建工作区 | 组合 tasks + worktree | | review | /tf:review <name> | 请求代码审查 | - | | agents | - | Agent 管理 | list, show <id>, assign, unassign | | status | /tf:status | 显示当前状态 | - | | merge | /tf:merge <id> | 合并代码 | <change> --dry-run | | confirm | /tf:confirm | 确认任务完成 | --task-id <id> --yes | | archive | /tf:archive <name> | 归档已完成任务 | --change <name> --event <event> | | sync | /tf:sync <name> | 同步状态到 spec | --change <name> |

详细用法请参考 CLI 使用教程。

核心概念

AI 调用模型

AI 分析项目 → 生成 context.json → 调用 CLI 生成文档 → AI 审查并填充 → 执行任务

• AI 是"大脑"：理解项目、做决策、填充内容
• CLI 是"手"：文件操作、格式转换、状态管理

Agent 系统

Task Flow 支持多 Agent 协作，每个 Agent 扮演特定角色：

| 角色 | 职责 | 权限 | |------|------|------| | Implementer | 实现任务、编写代码、执行测试 | write, test, build | | Reviewer | 代码审查、质量检查、批准合并 | read, review, approve |

Agent 状态：

• idle - 空闲，未分配任务
• working - 工作中，正在执行任务
• blocked - 阻塞，等待依赖或资源
• completed - 已完成，任务已完成

详细流程见 Agent 工作流文档。

Context 协议

AI 在调用命令前生成 context JSON，传递项目理解。主要包含：

• version: 协议版本（当前为 1.0）
• project: 项目信息（名称、类型、技术栈）
• analysis: 项目分析（架构摘要、核心模块、风险点）
• task: 任务信息（类型、优先级、影响文件、约束条件）

详细类型定义见 src/types/ai-context.ts。

Context 文件说明

.harness/context.json 用于存储项目分析结果，供 design 命令使用：

# 分析项目结构
task-flow analyze

# AI 补充 .harness/context.json 中的 analysis 字段

# 基于 PRD 和 context.json 生成技术设计
task-flow design --change my-feature

上下文文件说明：

| 文件 | 来源 | 说明 | |------|------|------| | .harness/context.json | analyze 命令生成 + AI 补充 | CLI 自动扫描项目生成的初始上下文，AI 补充详细分析 |

工作流程：

1. analyze 生成 .harness/context.json（项目结构骨架）
2. AI 读取并分析项目，补充 .harness/context.json 中的 analysis 字段
3. 使用 propose 命令从用户需求生成 PRD
4. AI 审查并完善 PRD 内容

配置

配置文件 (.harnessrc)

{
  "harnessRoot": ".harness",
  "worktreesDir": ".worktrees",
  "tasksDir": "tasks",
  "snapshotsDir": "snapshots",
  "archiveDir": "archive",
  "reportsDir": "reports",
  "specRoot": "spec"
}

环境变量和 Hooks 配置详见 CLI 使用教程。

运行时目录结构

project/
├── .harness/                       # Harness 运行时目录
│   ├── context.json                # AI 上下文文件
│   ├── state.json                  # 当前运行状态（包含 agents 字段）
│   ├── hooks.json                  # Hooks 配置
│   ├── skills.json                 # 技能工具注册（可选）
│   ├── mcp.json                    # MCP 服务器注册（可选）
│   └── archive/                    # 归档目录
├── spec/                           # 规格文档目录
│   └── changes/                    # 变更提案目录
│       └── <change-name>/          # 具体变更
│           ├── product-requirement.md  # 产品需求文档
│           ├── design.md               # 技术规格（可选）
│           ├── tasks.md                # 任务清单
│           ├── tasks/                  # 多阶段任务 JSON
│           │   ├── PHASE-1-1-1.json
│           │   ├── PHASE-1-1-2.json
│           │   └── ...
│           └── manifest.json           # 执行配置清单
└── .worktrees/                     # Git worktree 目录
    └── harness-feat-<name>/        # 隔离工作区

state.json 结构说明：

{
  "version": "1.0",
  "status": "active",
  "currentTask": "add-oauth",
  "worktrees": [
    {
      "name": "harness-feat-add-oauth",
      "agents": ["agent-xxx-xxx"]  // 关联的 Agent ID 列表
    }
  ],
  "agents": [  // Agent 信息列表
    {
      "id": "agent-xxx-xxx",
      "type": "implementer",
      "status": "working",
      "currentWorktree": "harness-feat-add-oauth",
      "assignedAt": "2024-01-01T00:00:00Z",
      "lastActivity": "2024-01-01T00:00:00Z"
    }
  ]
}

任务文件格式

PHASE-*.json 任务文件遵循标准 Schema，包含以下核心字段：

• id: 任务唯一标识（如 PHASE-1-1-1）
• type: 任务类型（feat/fix/refactor/test/docs/chore）
• title: 任务标题
• priority: 优先级（high/medium/low）
• phase: 所属阶段
• dependencies: 依赖任务列表
• spec: 任务规格（描述、文件列表、上下文）
• acceptance_criteria: 验收标准
• implementation: 实现步骤
• validation: 验证命令和手动检查项
• status: 任务状态（pending/in_progress/completed）

完整 Schema 定义和示例见 assets/schema.json 和 assets/PHASE-task.json.example。

工具注册

skills.json

{
  "version": "1.0",
  "skills": [
    {
      "name": "project-scaffold",
      "description": "项目工程脚手架 skill",
      "path": ".trae/skills/scaffold",
      "enabled": true
    }
  ]
}

mcp.json

{
  "version": "1.0",
  "mcpServers": [
    {
      "name": "component-library",
      "description": "组件库知识库 MCP",
      "command": "node",
      "args": ["mcp-server.js"],
      "enabled": true
    }
  ]
}

开发

# 安装依赖
pnpm install

# 运行测试
pnpm test

# 代码检查
pnpm lint

# 类型检查
pnpm typecheck

# 构建
pnpm build

# 监听模式构建
pnpm build:watch

# 发布（使用 changesets）
pnpm changeset
pnpm version
pnpm release

文档

• CLI 使用教程 - 人类开发者如何使用 CLI 命令
• AI 对话教程 - 如何通过 AI 对话完成任务
• Agent 工作流 - Implementer 和 Reviewer 协作流程
• 任务确认流程 - 任务完成确认机制详细说明
• Git Worktree SOP - Git worktree 使用规范

许可证

MIT License - 详见 LICENSE 文件

链接

• Agent Skills Specification
• GitHub Repository
• Issue Tracker