Harness CLI

一个交互式的 AI workflow CLI，用来管理多个项目、多个目标，以及目标下的任务执行。

它借鉴了 Anthropic《Effective harnesses for long-running agents》里的核心思路：不要把复杂工作塞进一次上下文窗口，而是把状态、目标、任务和交接信息持久化到文件系统里，让 agent 和人都能在离散 session 中持续推进。

当前版本已经实现的是 harness-cli 这层工作流编排和状态管理外壳；它不是旧版 README 里那种 init.sh + Python session_runner 形式的后台 runtime。

为什么是它

• 多项目：同一个 workspace 里管理多个独立项目
• 多目标：每个项目下维护多个 goal，并切换当前工作焦点
• 任务化推进：把 goal 拆成 task，按状态和依赖关系推进
• 交互式体验：默认 dashboard、选择器、状态看板都走交互式 CLI
• Git-aware 存储：在 git 仓库里优先用本地存储，否则走全局存储
• Agent-assisted：创建 goal 时可调用 agent 细化目标和任务

设计映射

Anthropic 那篇文章的重点不是“让 agent 一口气干完全部工作”，而是把长期任务拆成可交接、可恢复、可验证的小步推进。harness-cli 目前已经落地的映射是：

• 明确状态边界：Workspace -> Project -> Goal -> Task
• 避免一次做太多：run 每次聚焦一个 goal 里的一个 task
• 保留交接材料：目标、任务、状态都持久化为 YAML 和目录结构
• 降低上下文依赖：重新进入时先读结构化状态，而不是依赖对话记忆
• 保持执行框架：preflight -> worker -> verify

已实现能力

• harness init 初始化 workspace，检测 git 环境、默认 agent、存储模式等基础配置。
• harness project 创建、切换、列出、删除项目，支持全局和本地两种存储模式。
• harness goal 创建、切换、查看、完成、归档目标；创建时可让 agent 辅助细化成任务。
• harness run 选择 goal 和 task，检查依赖，推进任务状态，并按 preflight -> worker -> verify 的框架执行。
• harness status 查看全局或单项目状态，支持 --watch 实时刷新。
• harness 不带参数时进入 dashboard，直接做项目和目标导航。

快速开始

开发方式

pnpm install
pnpm run build
node dist/cli.js --help

最小 happy path

# 1. 初始化 workspace
node dist/cli.js init

# 2. 创建项目
node dist/cli.js project create --name "my-app"

# 3. 创建目标
node dist/cli.js goal create --name "实现用户认证 API"

# 4. 推进执行
node dist/cli.js run

# 5. 查看状态
node dist/cli.js status

如果你已经全局安装了 CLI，上面的 node dist/cli.js 可以直接换成 harness。

核心模型

flowchart TB
    Workspace["Workspace"] --> Project["Project"]
    Project --> Goal["Goal"]
    Goal --> Task["Task"]

Workspace

全局配置层，负责保存：

• 默认 agent
• 存储模式
• 预算阈值等 workspace 级配置
• 项目注册表

默认路径：

• XDG_CONFIG_HOME/harness
• 或 ~/.harness

Project

项目是独立的工作容器。支持两种存储模式：

• 全局：~/harness-workspace/<project-id>/
• 本地：<git-root>/.harness/projects/<project-id>/

每个项目目录里会生成：

• harness.yaml
• .harness/goals/
• .harness/current

Goal

goal 是项目内的中期目标，持久化在：

• .harness/goals/<goal-id>/goal.yaml

每个 goal 自带：

• 状态：active | paused | completed | archived | blocked
• 优先级
• 任务列表
• .state/
• logs/

Task

task 是 goal 下的最小执行单元，支持：

• pending
• in_progress
• completed
• failed

run 会优先继续 in_progress 任务，否则从 pending 任务里选择下一个。

典型流程

flowchart LR
    Init["harness init"] --> CreateProject["project create"]
    CreateProject --> CreateGoal["goal create"]
    CreateGoal --> Run["run"]
    Run --> Status["status"]
    Status --> Run

更具体一点：

1. init 建立 workspace 配置。
2. project create 创建项目并切到当前项目。
3. goal create 手动输入目标，或调用 agent 帮你生成任务。
4. run 选择当前 goal 的一个 task，按执行框架推进状态。
5. status / dashboard 用来观察全局和局部进度。

常用命令

harness init
harness project create --name "my-app"
harness project switch
harness goal create
harness goal switch
harness run
harness run --dry-run
harness status
harness status --watch

查看详细帮助：

harness --help
harness project --help
harness goal --help
harness run --help

Agent 接入现状

当前版本里，agent 主要出现在两个位置：

• goal create 会尝试调用已配置的 agent 来细化目标并生成任务。
• run 已经有执行框架和上下文拼装，但真实的 agent 执行链路还在建设中。

这意味着 harness-cli 现在已经适合拿来做 AI coding workflow 的组织层，但还不应该被描述成“完整的无人值守长时间运行 runtime”。

当前边界

这些点在 README 里必须说清楚，不然会误导：

• run 里的实际 agent 执行目前还是占位实现
• --resume 已暴露，但 checkpoint resume 还没完成
• claude-api 路径还没有真实 API 调用实现
• 预算和 telemetry 目前主要还是配置层能力，不是完整的平台能力

如果你要的是“Anthropic 风格 long-running harness 的完整 runtime”，这个仓库现在更准确的定位是：它已经把数据模型、交互式控制面和执行骨架搭起来了，但真正的 unattended runtime 还在演进中。

技术栈

• Node.js >= 22.22.0
• pnpm >= 9
• TypeScript
• Commander.js
• Enquirer
• YAML

许可证

MIT