@bicorne/task-flow

需求分析与任务拆分的 Harness Engineering 工具。帮助 AI 梳理用户需求生成 PRD 文档、编写技术规格、拆分多阶段任务文件，并通过 Git worktree 实现零冲突并行开发。适用于新功能开发、Bug 修复、代码重构等场景。

核心特性

• 🤖 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. 一键创建变更提案（extract + design + tasks）
/tf:propose my-feature

# 3. AI 审查并编辑生成的 PRD 和设计文档

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

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

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

# 7. 归档
/tf:archive --task-id my-feature

方式二：传统 CLI 命令

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

# 2. 扫描项目（可选）
task-flow analyze --output context.json

# 3. 生成 PRD 文档
task-flow extract --change my-feature --context-file context.json

# 4. 编辑 PRD 文档
# 文件位置: spec/changes/my-feature/product-requirement.md

# 5. 生成技术设计（可选）
task-flow design --change my-feature --context-file context.json

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

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

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

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

命令参考

Slash Commands

| 命令 | 说明 | 示例 | |------|------|------| | /tf:init | 初始化项目 | /tf:init | | /tf:propose <name> | 一键创建变更提案（extract + design + tasks） | /tf:propose add-oauth | | /tf:apply <name> | 应用并创建工作区 | /tf:apply add-oauth | | /tf:extract <name> | 生成 PRD 文档 | /tf:extract add-oauth | | /tf:design <name> | 生成技术设计 | /tf:design add-oauth | | /tf:tasks <name> | 生成任务文件 | /tf:tasks add-oauth | | /tf:worktree <name> | 创建隔离工作区 | /tf:worktree add-oauth | | /tf:merge <id> | 合并代码 | /tf:merge add-oauth | | /tf:archive --task-id <id> | 归档已完成任务 | /tf:archive --task-id add-oauth | | /tf:status | 显示当前状态 | /tf:status | | /tf:sync --task-id <id> | 同步状态到 spec | /tf:sync --task-id add-oauth |

CLI 命令

| 命令 | 说明 | 关键参数 | |------|------|----------| | init | 初始化项目 | --force 强制覆盖 | | analyze | 扫描项目生成 context | --output <path> | | extract | 生成 PRD 文档 | --change <name> --context-file <path> | | design | 生成技术设计 | --change <name> --context-file <path> --skip-prompt | | tasks | 生成任务文件 | --change <name> --yes --input <json> | | worktree | 创建隔离工作区 | --change <name> --yes | | status | 显示当前状态 | - | | merge | 合并代码 | <task-id> --dry-run | | archive | 归档任务 | --task-id <id> --event <event> | | sync | 同步状态到 spec | --task-id <id> |

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

核心概念

AI 调用模型

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

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

Context 协议

AI 在调用命令前生成 context JSON，传递项目理解：

interface AiContext {
  version: '1.0';
  project: {
    name: string;
    type?: 'library' | 'application' | 'service' | 'cli' | 'monorepo';
    techStack?: { language?: string; framework?: string; runtime?: string; };
  };
  analysis?: {
    architectureSummary?: string;
    coreModules?: Array<{ name: string; path: string; description: string }>;
    risks?: string[];
  };
  task?: {
    type?: 'feat' | 'fix' | 'refactor' | 'test' | 'docs' | 'chore';
    priority?: 'high' | 'medium' | 'low';
    affectedFiles?: string[];
    constraints?: string[];
  };
}

工作流程

analyze → extract → design → tasks → worktree → implement → review → merge
   │        │         │         │         │
   │        │         │         │         └── 创建隔离 git worktree
   │        │         │         └── 生成 PHASE-*.json 任务文件
   │        │         └── 分析 PRD 生成技术规格（可选）
   │        └── 提取需求生成 PRD 文档
   └── 自动扫描项目结构，生成 context.json 骨架

配置

环境变量

| 变量 | 默认值 | 说明 | |------|--------|------| | HARNESS_ROOT | .harness | Harness 状态根目录 | | HARNESS_WORKTREES_DIR | .worktrees | worktree 检出目录 | | HARNESS_CONFIG_FILE | .harnessrc | 配置文件路径 | | HARNESS_SPEC_ROOT | spec | spec 文件根目录 |

配置文件 (.harnessrc)

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

Hooks 配置

在 .harness/hooks.json 中配置生命周期钩子：

{
  "version": "1.0",
  "hooks": {
    "pre-design": [
      { "name": "check-prd-exists", "script": "src/hooks/check-prd-exists.js", "enabled": true }
    ],
    "pre-worktree": [
      { "name": "check-worktree-conflict", "script": "src/hooks/check-worktree-conflict.js", "enabled": true }
    ],
    "post-task-complete": [
      { "name": "phase-gate-validator", "script": "src/hooks/phase-gate-validator.js", "enabled": true }
    ]
  }
}

目录结构

项目目录

harness-task-flow/
├── src/
│   ├── index.ts                    # CLI 入口
│   ├── commands/                   # 命令实现
│   │   ├── init.ts
│   │   ├── extract.ts
│   │   ├── design.ts
│   │   ├── tasks.ts
│   │   ├── worktree.ts
│   │   ├── status.ts
│   │   ├── archive.ts
│   │   ├── merge.ts
│   │   ├── sync.ts
│   │   ├── analyze.ts
│   │   ├── merge/                  # 合并命令子模块
│   │   └── tasks-gen/              # 任务生成子模块
│   ├── lib/                        # 核心工具库
│   │   ├── config.ts               # 配置管理
│   │   ├── state.ts                # 状态管理
│   │   ├── archive.ts              # 归档管理
│   │   ├── constants.ts            # 常量定义
│   │   ├── interactive.ts          # 交互式 CLI
│   │   └── mcp-client.ts           # MCP 客户端
│   ├── hooks/                      # 事件钩子
│   │   ├── hook-runner/            # Hook 执行引擎
│   │   ├── check-prd-exists.ts
│   │   ├── check-worktree-conflict.ts
│   │   ├── phase-gate-validator.ts
│   │   ├── phase-complete-detector.ts
│   │   ├── save-checkpoint.ts
│   │   ├── start-mcp-servers.ts
│   │   └── stop-mcp-servers.ts
│   ├── slash/                      # Slash Commands
│   │   ├── parser.ts
│   │   ├── registry.ts
│   │   └── executor.ts
│   ├── spec/                       # Spec 集成
│   │   ├── openspec-to-task/       # OpenSpec 转换
│   │   ├── sync-openspec-to-task.ts
│   │   └── sync-task-to-openspec.ts
│   └── types/                      # 类型定义
│       └── ai-context.ts
├── assets/                         # 文件模板
│   ├── schema.json                 # 任务 JSON Schema
│   ├── product-requirement.md      # PRD 模板
│   ├── design.md                   # 技术规格模板
│   ├── tasks.md                    # 任务清单模板
│   ├── PHASE-task.json.example     # 任务 JSON 示例
│   ├── hooks.json                  # Hooks 配置示例
│   └── .harnessrc                  # 配置文件示例
├── tests/                          # 测试文件
├── references/                     # 参考文档
│   ├── CLI-TUTORIAL.md
│   ├── AI-CONVERSATION-TUTORIAL.md
│   └── GIT-WORKTREE-SOP.md
├── SKILL.md                        # Skill 文档
└── package.json

运行时目录

project/
├── .harness/                       # Harness 运行时目录
│   ├── state.json                  # 当前运行状态
│   ├── 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>/        # 隔离工作区

任务文件格式

PHASE-*.json 任务文件遵循标准 Schema：

{
  "id": "PHASE-1-1-1",
  "type": "feat",
  "title": "实现用户认证",
  "priority": "high",
  "phase": 1,
  "dependencies": [],
  "docs_to_read": ["spec/changes/my-feature/design.md"],
  "spec": {
    "description": "实现基于 JWT 的用户认证系统",
    "files": ["src/auth/jwt.ts", "src/auth/middleware.ts"],
    "context": ["spec/changes/my-feature/product-requirement.md"]
  },
  "acceptance_criteria": [
    "用户可以登录并获取 JWT token",
    "受保护的路由需要验证 token",
    "token 过期后自动刷新"
  ],
  "implementation": {
    "steps": [
      { "step": "安装依赖", "details": "npm install jsonwebtoken" },
      { "step": "实现 JWT 工具函数", "details": "创建 sign 和 verify 函数" },
      { "step": "实现认证中间件", "details": "验证 token 并注入用户信息" }
    ],
    "notes": "使用 RS256 算法"
  },
  "validation": {
    "commands": [
      "pnpm build",
      "pnpm test",
      "pnpm lint"
    ],
    "manual_checks": [
      "验证登录流程正常",
      "检查 token 刷新机制"
    ]
  },
  "status": "pending"
}

完整 Schema 定义见 assets/schema.json。

工具注册

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 对话完成任务
• Git Worktree SOP - Git worktree 使用规范

许可证

MIT License - 详见 LICENSE 文件

链接

• Agent Skills Specification
• GitHub Repository
• Issue Tracker