@aispea/taskforge

v0.1.3

Published

a month ago

Task-first CLI for Git worktree workflows and task-based development.

Downloads

503

0High
0Medium
0Low

zyxyxz

task taskforge worktree git-worktree cli workflow developer-tools devops

TaskForge

Task-driven development system for modern teams and AI agents
面向任务的开发工作区编排工具，基于 Git worktree、环境管理与服务运行时编排。

TaskForge turns this workflow:

Task -> Branch -> Worktree -> Env -> Service

把任务从“分支操作”升级为一套团队可执行、可扩展、可自动化的开发系统。

什么是 TaskForge？

TaskForge 是一个基于 git worktree 的任务驱动开发工具。

它把每个开发任务映射为一个独立、可运行、可管理的工作空间，并统一处理分支、目录、环境变量、端口分配与服务生命周期。

相比把分支当成核心单元，TaskForge 更强调“任务”才是开发协作的真实对象。

解决什么问题？

在实际团队开发中，常见的问题包括：

来回 git checkout，上下文频繁切换
本地环境互相踩端口、踩数据、踩缓存
分支很多，但没有清晰的任务映射关系
每个人的本地环境不一致，问题难以复现
AI Agent 无法在不稳定的执行环境里可靠工作

TaskForge 的目标，是让团队用一套标准化流程去创建、运行、查看和清理任务级工作区。

核心能力

任务驱动开发：每个任务对应一个独立 worktree
并行开发：不再依赖来回切换分支
统一环境管理：统一处理 env、ports、db 等运行资源
可控隔离策略：共享与隔离可以按任务风险灵活配置
团队协作标准化：所有操作统一走 CLI
AI Agent 友好：天然适合作为 Agent 的任务执行底座

文档索引

README.md：当前 CLI、项目背景与 MVP 能力说明

核心理念

1. Task First（任务优先）

一个任务 = 一个分支 = 一个 worktree

每个任务都拥有自己的执行空间，与其他进行中的任务保持解耦。

2. Shared + Isolated（共享 + 可控隔离）

TaskForge 的策略不是一味隔离，而是共享安全资源、隔离高风险资源。

| 资源 | 默认策略 | | --- | --- | | Python / Node | 共享 | | Redis / DB 实例 | 共享 | | 数据库数据 | 可共享 / 可隔离 | | 端口 | 隔离 | | 代码目录 | 隔离 |

3. CLI as Entry（统一入口）

所有任务操作统一通过 CLI 入口完成：

taskforge ...

这让团队行为更一致，也更方便自动化和后续平台化。

安装

发布到 npm 后，可以全局安装：

npm install -g @aispea/taskforge

安装完成后，实际使用的命令仍然是：

taskforge
tf

也可以直接通过 npx 使用：

npx @aispea/taskforge init

开发时也可以直接全局 link，并使用短命令：

npm link
tf help

快速开始

1. 初始化项目

在项目根目录执行：

taskforge init

taskforge init 现在会确保项目被初始化为一个可用的 git 仓库，并自动创建可作为 worktree 基线的初始提交；TaskForge 后续的任务创建、提交、合并都基于这个 git/worktree 工作流。

2. 创建任务工作区

tf create task-101-login --assignee zhangsan

执行后会自动完成：

创建分支 task-101-login
创建 worktree：myapp-worktrees/task-101-login
分配独立端口，例如 3101 和 8101
生成 .env.local
注册任务元信息

3. 启动开发环境

tf up task-101-login

典型行为包括：

进入对应 worktree
加载 .env.local
启动 frontend / backend 服务
使用该任务专属端口运行环境

4. 查看当前状态

tf status

示例输出：

TASK              USER       PORTS        DB        STATUS     WORKFLOW
task-101-login    zhangsan   3101/8101    shared    running    in_progress
task-102-admin    lisi       3102/8102    isolated  stopped    review_requested

5. 删除任务

tf remove task-101-login

工作区结构

假设项目位于：

/opt/aispea/myapp

TaskForge 会将工作区组织为：

/opt/aispea/
|- myapp/                   # 原始仓库
|- .taskforge/              # 项目级状态与任务元数据
`- myapp-worktrees/         # 所有任务工作区
   |- task-101-login/
   |- task-102-admin/
   `- ...

配置系统

TaskForge 的项目配置目录为 .taskforge/：

.taskforge/
|- config.json
`- tasks/

跨 worktree 的命令自动发现文件：

worktree/.taskforge/worktree.json

示例 config.json：

project:
  name: myapp
  root: /opt/aispea/myapp

paths:
  main_worktree: /opt/aispea/myapp
  worktree_root: /opt/aispea/myapp-worktrees

git:
  base_branch: main

ports:
  frontend_start: 3100
  backend_start: 8100

env:
  shared_python: true
  shared_node: true

database:
  mode: shared
  engine: postgres
  host: 127.0.0.1
  port: 5432
  user: dev
  password: xxx
  shared_db_name: myapp_dev
  isolated_db_prefix: myapp_task_

resource_profiles:
  shared:
    db: shared
    redis_prefix: false

  safe:
    db: isolated
    redis_prefix: true

  full:
    db: isolated
    redis_prefix: true

生命周期命令：

{
  "lifecycle": {
    "package_manager": "pnpm",
    "after_create": [
      {
        "name": "install dependencies",
        "command": "pnpm install --prefer-offline",
        "cwd": ".",
        "enabled": true,
        "interactive": false
      }
    ],
    "before_develop": [],
    "on_develop": []
  }
}

说明：

after_create：任务 worktree 创建完成后运行，适合 pnpm install --prefer-offline。
before_develop：在 dashboard 选择“开始开发”后、进入 shell 前运行，适合依赖检查或代码生成。
on_develop：进入开发前可选执行交互命令，适合项目自定义启动脚本。
taskforge init 会尝试识别 pnpm-lock.yaml / package-lock.json / yarn.lock，并写入推荐 lifecycle 配置。

数据库策略

TaskForge 同时支持共享数据库和隔离数据库两种模式。

默认模式：共享数据库

适合绝大多数日常开发场景：

taskforge task create task-101-login --db shared

所有任务共用同一个数据库，例如：

myapp_dev

隔离模式：独立数据库

适合 migration、数据修复、高风险任务等场景：

taskforge task create task-102-migration --db isolated

系统可以自动生成独立数据库名，例如：

myapp_task_101

Resource Profile（资源策略）

Resource Profile 用来定义任务创建时的资源隔离等级。

创建任务时可以直接指定：

taskforge task create task-102-migration --resource-profile safe

内置 profile：

| Profile | 行为 | | --- | --- | | shared | 共享 DB，共享 Redis | | safe | DB 隔离，Redis key prefix 隔离 | | full | DB 隔离，Redis 隔离，对象存储隔离 |

命令总览

任务管理

taskforge task create
taskforge task list
taskforge task show
taskforge task remove
taskforge task status set <name> <todo|in_progress|review_requested|changes_requested|approved|merge_conflicted|merged|done|archived>
taskforge task submit <name> [--message <message>]
taskforge task commit <name> [--message <message>]
taskforge task merge <name> [--stash-dirty|--commit-dirty] [--use-codex-on-conflict]
taskforge task path <name>
taskforge describe <name>
taskforge projects list
taskforge projects show <name|path>
taskforge projects remove <name|path>
taskforge projects prune

# shortcuts
tf create
tf list
tf show
tf remove
tf path
tf submit
tf commit
tf merge
tf info

简化规则：

tf 是 taskforge 的短别名。
在项目根目录、.taskforge/、具体 task worktree、以及整个 *-worktrees/ 目录里，TaskForge 都会自动识别当前 project。
在项目相关目录执行 tf list，默认等价于 tf task list。
在 task worktree 内执行 tf describe / tf up / tf down 时，如果省略任务名，会优先使用当前 worktree 对应的 task。
在 task worktree 内执行 tf submit / tf commit 时，如果省略任务名，也会优先使用当前 worktree 对应的 task。
直接执行 tf 默认进入 tf info 控制台。
tf show / tf describe / tf projects show 默认输出人类可读视图，--json 才输出机器可读 JSON。
tf projects 默认等价于 tf projects list。
在主项目目录执行 tf merge 且不带任务名时，如果在 TTY 中，会弹出一个可上下键选择的 merge task 列表。
如果主项目有未提交改动，tf merge 会在交互式终端提示你选择：
- stash 当前改动后继续 merge
- 先提交当前改动再继续 merge
- 取消操作

提交流程：

tf submit：推荐的任务提交流程；会把任务推进到 review_requested
- 始终执行真实 git add / git commit
tf commit：兼容旧习惯，等价于 tf submit
tf merge <task>：把任务推进到 merged
- 会在主项目目录把 task 分支 merge 回 base branch
tf merge：在交互式终端中可直接选择一个候选任务进行合并
tf merge --stash-dirty <task>：发现主项目有未提交改动时，先自动 stash 再 merge
tf merge --commit-dirty <task> [--dirty-message "..."]：发现主项目有未提交改动时，先自动提交主项目改动再 merge
如果 merge 过程中发生冲突，任务会被标记为 merge_conflicted
在交互式终端中，发生冲突时会提示是否调用 Codex 协助解决冲突并自动继续 merge
也可以直接使用 tf merge --use-codex-on-conflict <task> 在冲突时自动调用 Codex
create / submit / merge / up / down / restart 成功后，CLI 会直接给出推荐下一步，降低第一次使用时的摸索成本

任务工作状态

taskforge up <task>
taskforge down <task>
taskforge restart <task>
taskforge describe <task>
tf up <task>
tf down <task>
tf restart <task>
tf describe <task>

当前版本里，这一组命令只管理任务的工作状态，而不是托管真实服务进程：

up/down/restart：更新任务当前工作状态，便于团队查看谁在处理中
describe：查看任务详情，包括状态、分支、worktree、端口和数据库模式
如果后续要接真实服务管理，建议作为独立扩展层，而不是当前核心模型的一部分

状态与排障

taskforge status
taskforge doctor
tf status
tf info
tf doctor

其中：

tf info 会展示当前 project 的主目录、worktree root、任务数量、当前所在位置等信息。
在交互式终端里，tf info 默认会进入一个轻量 dashboard，可以用上下键浏览当前列表，按 p 在 task / project 视图之间切换，按 h 查看帮助，按 Esc 退出。
在 dashboard 里，选中 task 后可以直接按 Enter 进入动作菜单；动作菜单支持开始开发、开始/停止、提交、撤回提交、合并、删除和查看路径。
选择“开始开发”并确认后，TaskForge 会加载任务环境，打开一个位于该 worktree 的交互式 shell；退出 shell 后会回到原终端。
tf status / tf list / tf projects list 会优先使用彩色表格输出。
当你身处某个 task worktree 时，tf list / tf status 会高亮当前 task；tf projects list 会标出当前 project。

初始化与定位

taskforge init [path-or-root]
taskforge init --root <path>

说明：

taskforge init 默认在当前目录初始化项目，并确保当前目录成为 git 仓库。
taskforge init <path> 或 taskforge init --root <path> 可在目标项目目录初始化并自动创建 path/myapp-worktrees。
在 worktree 目录内执行 taskforge task show/taskforge task list/taskforge up 时，会自动回跳到对应项目上下文，不需要手工切回主目录。
在整个 myapp-worktrees/ 目录中执行 tf list / tf info / tf status 时，也会自动识别到对应项目。
taskforge projects list 会读取 ~/.taskforge/projects.json（可通过 TASKFORGE_HOME 覆盖）查看当前主机上已注册项目。

团队协作规范

AI Agent 支持

TaskForge 天然适配以下工作流：

Task -> Worktree -> Agent -> Commit -> Review

未来可以继续扩展为：

自动创建任务
自动执行代码生成
自动提交 PR
自动 review

架构定位

TaskForge 的定位是开发任务执行层（Execution Layer）。

它可以作为：

AI 编程系统的底座
多 Agent 编排的执行环境
团队本地开发的任务操作系统

Roadmap

[ ] Web UI 控制台
[ ] AI Agent 集成
[ ] 自动 review
[ ] CI/CD 集成
[ ] 云端任务调度
[ ] 任务模板与脚手架
[ ] 任务配置编辑命令（如 assignee / profile / env）
[ ] 批量操作与更强的项目级工作流 UX

一句话总结

TaskForge = 把开发从“分支操作”升级为“任务执行系统”

License

MIT

作者

CyberTronics / AiSpea

任务开发记录（MVP）

已完成的实现（当前版本）:

taskforge init：初始化 .taskforge 目录与配置。
taskforge task create <name>：创建任务记录，分配前端/后端端口。
taskforge task list / taskforge task show <name>：查看任务信息（含 WORKFLOW）。
taskforge task remove <name>：移除任务记录与工作区。
taskforge task status set <name> <state>：更新任务状态（如 review_requested / approved）。
taskforge task submit <name>：推荐提交流程；提交并推进到 review_requested。
taskforge task commit <name>：兼容旧命令，等价于 taskforge task submit <name>。
taskforge task merge <name>：在主项目合并指定任务，并把状态推进到 merged。
taskforge up|down|restart <name>：更新任务工作状态，便于协作视图统一。
taskforge describe <name>：查看任务详情。
taskforge status：展示任务端口、运行状态与流程状态。
tf：taskforge 的全局短别名。
tf info：查看当前项目总览；TTY 中默认进入可上下键浏览的 dashboard。
tf list/show/create/remove/path/submit/commit/merge：常用 task 子命令快捷入口。
彩色表格输出：status / list / projects list 默认使用更清晰的终端表格。
taskforge doctor：环境健康检查。
taskforge projects list/show：全局查看当前主机注册项目，支持在任意目录查询。
taskforge projects remove：从全局注册表移除项目。
taskforge projects prune：清理失效项目记录（缺少 config.json 或目录不存在）。
taskforge task path <name>：显示任务对应 worktree 的绝对路径。
taskforge task list --json / projects list --json / status --json：机器友好输出。

发布到 npm

项目已具备 npm 打包能力（bin/taskforge + package.json）。当前打包与测试命令：

npm run lint      # 语法检查
npm test         # 本地测试
npm pack         # 生成发布包（dry 包检查）
npm publish --dry-run  # 模拟发布到 npm

正式发布前请满足：

已登录 npm（npm whoami 成功）。
配置期望的发布名称（当前配置名为 @aispea/taskforge）。
准备好 README、版本号与 LICENSE。