Skip to content

Harness 产品形态设计

目录


一、产品定位

1.1 产品定义

Harness 是什么?

一个企业级 AI 驱动的自动化软件工程系统,能够根据需求规范自动生成、验证、合并代码,并通过多层验证和纠错确保代码质量。

1.2 核心价值主张

价值说明
🤖 自动化编码从 OpenSpec 到可运行代码的端到端自动化
🛡️ 质量保证双层验证(语义 + 质量)确保代码可靠
💰 成本可控预算追踪 + 上下文压缩,成本透明可预测
🔄 闭环纠错自动修复失败 → 重试 → 升级人工的完整闭环

1.3 产品架构概览

┌─────────────────────────────────────────────────────────┐
│                    Harness 产品层                         │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
│  │   CLI 工具   │  │   Web 平台   │  │  API 服务    │ │
│  │              │  │              │  │              │ │
│  │  harness     │  │  Dashboard   │  │  REST/gRPC   │ │
│  │  run ...    │  │  + IDE 扩展  │  │  API         │ │
│  └──────────────┘  └──────────────┘  └──────────────┘ │
│         │                │                │            │
│         └────────────────┴────────────────┘            │
│                          │                              │
│                          ▼                              │
│              ┌───────────────────────┐                  │
│              │   Harness Engine     │                  │
│              │   (后端服务)          │                  │
│              └───────────────────────┘                  │
└─────────────────────────────────────────────────────────┘

1.4 目标用户

用户类型使用方式核心诉求
个人开发者CLI 工具快速完成编码任务,提升效率
小团队Web Dashboard团队协作、任务可视化管理
大企业自托管/SaaS权限管理、成本控制、合规审计
DevOps 工程师API 集成CI/CD 自动化、批量任务执行

二、产品形态

1. CLI 工具形态

使用方式

bash
# 安装
npm install -g @harness/cli

# 基础使用
harness init                    # 初始化项目
harness run "实现用户登录功能"   # 执行任务
harness status                   # 查看任务状态
harness logs <session-id>       # 查看日志

# 高级使用
harness run --task "重构用户模块" \
  --spec ./spec/openapi.yaml \
  --budget 5.0 \
  --branch feature/user-refactor

# 批量执行
harness run --batch tasks.json

# 查看指标
harness metrics --last-7d

# 工作空间管理
harness worktree list
harness worktree prune <id>

输出示例

✓ 初始化会话: gsd-abc123
✓ 解析 OpenSpec: ./spec/openapi.yaml
✓ 创建 worktree: .gsd/worktrees/feature/login
✓ 执行任务: 实现用户登录功能
  ├─ 生成代码: src/auth/login.ts
  ├─ 生成测试: src/auth/login.test.ts
  └─ 生成类型: src/types/auth.ts
✓ Superpowers 验证: 通过
✓ Archon 验证: 通过
  ├─ 测试覆盖率: 85%
  ├─ 圈复杂度: 8
  └─ 安全扫描: 无漏洞
✓ 创建 PR: https://github.com/org/repo/pull/123

📊 成本: $1.23 (预算: $5.00, 剩余: $3.77)
⏱️  耗时: 8分32秒
🎉 成功!

CLI 核心命令

命令功能
harness init初始化项目,创建 .gsd 配置目录
harness run执行任务(支持自然语言或 OpenSpec)
harness status查看当前任务状态
harness logs查看任务日志
harness metrics查看成本、成功率等指标
harness worktree管理 git worktree
harness config管理配置文件

2. Web 平台形态

Dashboard 首页

┌─────────────────────────────────────────────────────────────────┐
│  Harness Dashboard                                              │
├─────────────────────────────────────────────────────────────────┤
│  [仪表盘] [任务] [会话] [配置] [团队] [设置]                    │
│                                                                 │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │ 今日任务     │  │ 成功率      │  │ 本月成本    │             │
│  │     23      │  │    85%      │  │   $127.50   │             │
│  │  ↑ 12%     │  │  ↑ 5%      │  │  ↓ 8%      │             │
│  └─────────────┘  └─────────────┘  └─────────────┘             │
│                                                                 │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │ 平均耗时    │  │ 验证通过率  │  │ 人工干预率  │             │
│  │   8.5min   │  │    92%      │  │    15%      │             │
│  │  ↓ 10%     │  │  ↑ 3%      │  │  ↓ 2%      │             │
│  └─────────────┘  └─────────────┘  └─────────────┘             │
│                                                                 │
│  最近任务                                                        │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │ 任务           │ 状态  │ 成本   │ 耗时  │ PR               │  │
│  ├──────────────────────────────────────────────────────────┤  │
│  │ 实现用户登录   │ ✓     │ $1.23  │ 8m    │ #123 (merged)   │  │
│  │ 重构订单模块   │ ✓     │ $2.10  │ 15m   │ #124 (draft)    │  │
│  │ 修复支付漏洞   │ ⚠     │ $0.80  │ 5m    │ - (人工介入)    │  │
│  │ 生成 API 文档  │ ❌    │ $3.20  │ 12m   │ - (失败)        │  │
│  └──────────────────────────────────────────────────────────┘  │
│                                                                 │
│  查看全部 →                                                    │
└─────────────────────────────────────────────────────────────────┘

会话详情页

┌─────────────────────────────────────────────────────────────────┐
│  会话详情: gsd-abc123                                          │
├─────────────────────────────────────────────────────────────────┤
│  状态: Done  ✓                                                 │
│  任务: 实现用户登录功能                                         │
│  分支: feature/login                                           │
│  创建时间: 2026-04-15 10:30:00                                │
│                                                                 │
│  状态机执行流                                                   │
│  ┌──────┐   ┌──────┐   ┌──────┐   ┌──────┐   ┌──────┐       │
│  │ Idle │ → │Parsing│ → │Planning│ → │Executing│ → │Done │       │
│  └──────┘   └──────┘   └──────┘   └──────┘   └──────┘       │
│     1s         3s         5s          7m          8m           │
│                                                                 │
│  验证结果                                                       │
│  ├─ Superpowers: ✓ 通过                                       │
│  │   └─ 语义一致性检查: 所有功能已实现                        │
│  ├─ Archon: ✓ 通过                                           │
│  │   ├─ 测试覆盖率: 85% (阈值: 80%)                           │
│  │   ├─ 圈复杂度: 8 (阈值: 10)                               │
│  │   └─ 安全扫描: 无漏洞                                     │
│                                                                 │
│  成本明细                                                       │
│  ├─ LLM 调用: $1.00 (33,333 tokens)                          │
│  ├─ API 调用: $0.15                                          │
│  └─ 其他: $0.08                                               │
│  总计: $1.23                                                   │
│                                                                 │
│  代码变更                                                       │
│  ├─ + src/auth/login.ts (新增)                                │
│  ├─ + src/auth/login.test.ts (新增)                            │
│  └─ M src/types/auth.ts (修改)                                │
│                                                                 │
│  [查看日志] [查看代码] [下载] [重新运行]                         │
└─────────────────────────────────────────────────────────────────┘

配置管理页

┌─────────────────────────────────────────────────────────────────┐
│  项目配置: my-project                                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  [基本配置] [Guardrails] [Hooks] [质量门禁] [预算策略]         │
│                                                                 │
│  基本配置                                                       │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │ OpenSpec 路径: ./spec/openapi.yaml                     │  │
│  │ 目标分支: main                                        │  │
│  │ LLM 模型: claude-3-5-sonnet-20241022                  │  │
│  │ 温度: 0.7                                             │  │
│  └──────────────────────────────────────────────────────────┘  │
│                                                                 │
│  Guardrails 规则                                                │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │ ☑ 禁止强制推送到主分支                                   │  │
│  │ ☑ 危险操作需要确认                                      │  │
│  │ ☑ 预算不足时拒绝新任务                                  │  │
│  │ ☑ 阻止提交敏感文件 (.env, credentials)                  │  │
│  └──────────────────────────────────────────────────────────┘  │
│                                                                 │
│  质量门禁                                                       │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │ 测试覆盖率: 80%                                         │  │
│  │ 圈复杂度: 10                                            │  │
│  │ 安全扫描: 开启                                          │  │
│  │ 类型检查: 开启                                          │  │
│  └──────────────────────────────────────────────────────────┘  │
│                                                                 │
│  [保存配置]                                                    │
└─────────────────────────────────────────────────────────────────┘

Web 核心功能

模块功能
仪表盘任务统计、成本概览、成功率、趋势图
任务管理任务列表、详情查看、重新运行、批量操作
会话追踪状态机流程、日志查看、代码对比
配置管理Guardrails、Hooks、质量门禁、预算策略
团队管理用户权限、项目成员、操作审计
告警中心失败告警、成本预警、异常通知

3. API 服务形态

REST API 示例

typescript
// 1. 提交任务
POST /harness/v1/tasks
{
  "description": "实现用户登录功能",
  "openSpecPath": "./spec/openapi.yaml",
  "targetBranch": "feature/login",
  "budget": 5.0
}
Response: {
  "sessionId": "gsd-abc123",
  "status": "running",
  "createdAt": "2026-04-15T10:30:00Z"
}

// 2. 查询任务状态
GET /harness/v1/tasks/gsd-abc123
Response: {
  "sessionId": "gsd-abc123",
  "status": "done",
  "state": "Done",
  "prUrl": "https://github.com/org/repo/pull/123",
  "metrics": {
    "cost": 1.23,
    "duration": 512,
    "attempts": 1
  }
}

// 3. 获取会话日志
GET /harness/v1/sessions/gsd-abc123/logs?limit=100
→ Response: [
  {
    "timestamp": "2026-04-15T10:30:05Z",
    "level": "info",
    "message": "开始解析 OpenSpec"
  },
  {
    "timestamp": "2026-04-15T10:30:10Z",
    "level": "info",
    "message": "创建 worktree: .gsd/worktrees/feature/login"
  }
]

// 4. 获取指标
GET /harness/v1/metrics?from=2026-04-08&to=2026-04-15
→ Response: {
  "period": { "from": "2026-04-08", "to": "2026-04-15" },
  "tasks": {
    "total": 23,
    "success": 20,
    "failed": 2,
    "manual": 1,
    "successRate": 0.87
  },
  "cost": {
    "total": 127.50,
    "average": 5.54
  },
  "performance": {
    "avgDuration": 480,
    "maxDuration": 1200,
    "minDuration": 120
  }
}

// 5. 批量提交任务
POST /harness/v1/tasks/batch
{
  "tasks": [
    { "description": "实现用户登录", "budget": 2.0 },
    { "description": "实现用户注册", "budget": 2.0 },
    { "description": "实现密码重置", "budget": 2.0 }
  ]
}
Response: {
  "sessionIds": ["gsd-001", "gsd-002", "gsd-003"]
}

// 6. 取消任务
DELETE /harness/v1/tasks/gsd-abc123
Response: { "cancelled": true }

// 7. Webhook 配置
POST /harness/v1/webhooks
{
  "url": "https://example.com/webhook",
  "events": ["task.done", "task.failed", "budget.exhausted"],
  "secret": "webhook-secret"
}
Response: { "webhookId": "wh-123" }

API 核心端点

端点方法功能
/harness/v1/tasksPOST提交任务
/harness/v1/tasks/batchPOST批量提交任务
/harness/v1/tasks/{id}GET查询任务状态
/harness/v1/tasks/{id}DELETE取消任务
/harness/v1/sessions/{idGET获取会话详情
/harness/v1/sessions/{id}/logsGET获取会话日志
/harness/v1/metricsGET获取指标
/harness/v1/configGET/PUT配置管理
/harness/v1/webhooksPOST配置 Webhook

三、核心功能模块

1. 任务执行引擎

用户输入 → GSD Loop → 代码生成 → 验证 → 合并 → PR

能力

能力说明
🤖 智能代码生成从自然语言/OpenSpec 自动生成代码
🧩 任务拆解自动拆解复杂任务为子任务
🔄 自动重试失败自动重试,支持多次迭代
💰 预算控制预算追踪、预警、超限停止
🔒 隔离执行Git worktree 隔离,不影响主分支

执行流程

1. 接收任务

2. 解析 OpenSpec (Parsing)

3. 拆分子任务 (Planning)

4. 执行代码生成 (Executing)
   ├─ 创建 worktree
   ├─ 调用 LLM 生成代码
   └─ 写入文件

5. 验证结果 (Validating)
   ├─ Superpowers 语义验证
   └─ Archon 质量验证

6. 处理结果
   ├─ 通过 → 合并代码 → 创建 PR
   └─ 失败 → 自动修复 或 升级人工

2. 质量验证系统

代码

┌─────────────────────┐
│  Superpowers (语义) │ → 业务逻辑一致性
└─────────────────────┘

┌─────────────────────┐
│  Archon (质量)      │ → 覆盖率、复杂度、安全
└─────────────────────┘

通过 → 合并 / 失败 → 修复

能力

能力说明
🔍 语义验证验证代码是否符合需求意图
📊 质量门禁覆盖率、复杂度、安全扫描
🔧 自动修复针对可修复问题生成修复建议
👤 人工升级不可修复时自动创建 Draft PR

验证维度

维度检查项阈值
语义是否实现所有功能100%
语义业务逻辑是否正确N/A
质量测试覆盖率≥80%
质量圈复杂度≤10
安全安全漏洞0
质量类型检查通过

3. 成本管理系统

实时追踪 LLM/API 调用成本

预算预警 (剩余 20%)

预算超限 (停止执行)

成本报告 (按天/周/月)

能力

能力说明
💰 实时追踪追踪每次调用的 token 消耗和成本
⚠️ 预算预警剩余 20% 时发送预警
🛑 预算控制超限自动停止执行
📈 成本分析按项目/用户/时间维度分析
📊 成本报告生成日/周/月成本报告

成本构成

类型说明计算方式
LLM 调用token 数 × 模型定价
API 调用GitHub API、第三方服务调用次数 × 定价
存储数据库、对象存储存储容量 × 定价
其他网络、计算实际使用 × 定价

4. 可观测系统

┌────────────────────────────────────────┐
│  Harness Observability                 │
├────────────────────────────────────────┤
│  ┌──────────┐  ┌──────────┐          │
│  │  日志     │  │  指标     │          │
│  │  (Logs)  │  │ (Metrics)│          │
│  └──────────┘  └──────────┘          │
│  ┌──────────┐  ┌──────────┐          │
│  │  追踪     │  │  告警     │          │
│  │ (Traces) │  │ (Alerts) │          │
│  └──────────┘  └──────────┘          │
└────────────────────────────────────────┘

能力

能力说明
📝 结构化日志DEBUG/INFO/WARN/ERROR 级别日志
📊 关键指标成功率、成本、延迟、吞吐量
🔗 分布式追踪完整执行链路追踪
🔔 自定义告警失败率、成本异常、延迟告警

核心指标

指标类型说明
tasks_totalCounter总任务数
tasks_successCounter成功任务数
tasks_failedCounter失败任务数
task_duration_secondsHistogram任务耗时分布
task_cost_usdGauge任务成本
llm_tokens_totalCounterLLM token 总数
llm_cost_usdGaugeLLM 成本

5. 配置与权限系统

项目配置
  ├─ Guardrails 规则
  ├─ Hooks 配置
  ├─ 质量门禁阈值
  └─ 预算策略

用户权限
  ├─ 角色管理 (Admin/User/Viewer)
  ├─ 项目权限
  └─ 操作审计

能力

能力说明
⚙️ 配置管理项目级、组织级配置
🔐 权限控制RBAC 角色权限管理
👁️ 审计日志操作审计、合规追踪
🌐 多租户支持多组织、多项目

角色定义

角色权限
Admin所有权限、配置管理、用户管理
Developer提交任务、查看日志、基本配置
Viewer只读权限、查看任务和日志

四、部署架构

系统架构

┌─────────────────────────────────────────────────────────────┐
│                        用户层                                 │
│  CLI / Web / API / GitHub App                               │
└────────────────────────────┬──────────────────────────────────┘


┌─────────────────────────────────────────────────────────────┐
│                     Harness Engine                           │
├─────────────────────────────────────────────────────────────┤
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  │
│  │ API 网关  │  │ GSD Loop │  │验证服务  │  │成本追踪  │  │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘  │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  │
│  │会话管理  │  │日志服务  │  │配置服务  │  │权限服务  │  │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘  │
└────────────────────────────┬──────────────────────────────────┘

        ┌────────────────────┼────────────────────┐
        │                    │                    │
        ▼                    ▼                    ▼
┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│ PostgreSQL   │    │   Redis      │    │  S3 / OSS    │
│ (会话/配置)  │    │ (缓存/队列)  │    │ (日志/代码)   │
└──────────────┘    └──────────────┘    └──────────────┘

部署方式

方式适用场景优点缺点
Docker开发、测试简单、快速不适合生产高可用
Kubernetes生产环境高可用、自动扩容运维复杂度高
Serverless低频使用按需计费、免运维冷启动延迟
SaaS无需运维零运维、快速上手数据在第三方

推荐技术栈

组件技术选型
后端框架FastAPI / Express / Gin
数据库PostgreSQL
缓存Redis
消息队列RabbitMQ / Kafka
对象存储S3 / OSS
日志系统ELK / Loki
监控Prometheus + Grafana
容器编排Kubernetes / Docker Compose

五、典型使用场景

场景 1: 开发者个人使用

场景: 开发者需要快速实现一个功能模块

流程:

bash
# 1. 开发者写好 OpenSpec
vim ./spec/openapi.yaml

# 2. 端到端自动化
harness run --spec ./spec/openapi.yaml --task "实现用户管理"

# 3. 几分钟后查看 PR
gh pr list
# → #123: [GSD] 实现用户管理 (Draft)

收益:

  • ✅ 从需求到 PR 全自动
  • ✅ 无需手动写代码
  • ✅ 自动通过质量检查

场景 2: 团队协作

场景: 团队需要标准化开发流程

流程:

产品经理
  ↓ 写好 OpenSpec (需求规范)
工程师
  ↓ 配置 Harness (Guardrails/质量门禁)
CI/CD
  ↓ 定时触发 harness run
Harness
  ↓ 自动生成代码 + 验证 + 创建 PR
团队
  ↓ Code Review + 合并

收益:

  • ✅ 标准化开发流程
  • ✅ 减少代码 Review 时间
  • ✅ 统一质量标准

场景 3: GitHub App 集成

场景: 通过 PR 评论触发任务

流程:

在 PR 中评论:
  @harness refactor "重构用户模块"

Harnes GitHub App
  ↓ 自动创建新分支
  ↓ 执行重构任务
  ↓ 创建新的 PR

工程师
  ↓ Review 新 PR
  ↓ 合并

收益:

  • ✅ 零配置触发
  • ✅ 直接在 GitHub 中使用
  • ✅ 适合小改动和重构

场景 4: CI/CD 集成

场景: 自动化代码生成作为 CI/CD 的一部分

流程:

yaml
# .github/workflows/harness.yml
name: Harness Automated Coding

on:
  push:

jobs:
  harness:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run Harness
        run: |
          npm install -g @harness/cli
          harness run --task "实现新功能" --spec ./spec/openapi.yaml

收益:

  • ✅ 深度集成到 CI/CD
  • ✅ 代码生成可追溯
  • ✅ 失败自动阻止合并

场景 5: 批量任务执行

场景: 需要同时执行多个独立任务

流程:

bash
# 创建任务列表
cat > tasks.json << EOF
[
  { "description": "实现用户登录", "budget": 2.0 },
  { "description": "实现用户注册", "budget": 2.0 },
  { "description": "实现密码重置", "budget": 2.0 }
]
EOF

# 批量执行
harness run --batch tasks.json --parallel

收益:

  • ✅ 并行执行,节省时间
  • ✅ 统一管理任务
  • ✅ 统一成本追踪

六、与现有工具对比

产品类型核心能力Harness 差异
GitHub CopilotIDE 助手代码补全、生成Harness 端到端自动生成 + 验证 + 合并
Cursor / WindsurfAI IDE编辑器集成 AIHarness 独立服务 + 团队协作
LangChain开发框架LLM 应用开发Harness 针对软件工程的完整方案
GitHub ActionsCI/CD自动化流水线Harness 用 AI 自动生成代码
Snyk安全扫描安全漏洞检查Harness 集成 + 语义验证
SonarQube代码质量质量分析Harness 集成 + 自动修复

核心差异总结

维度传统工具Harness
自动化程度辅助开发端到端自动化
质量保证人工检查自动验证 + 修复
成本控制不透明实时追踪 + 预算控制
团队协作个人使用团队平台
集成能力单点工具完整解决方案

七、产品路线图

阶段 1: MVP (Month 1-2)

目标: 核心功能可用

功能:

  • ✅ CLI 工具基础功能
  • ✅ GSD Loop 状态机
  • ✅ 基础代码生成
  • ✅ Git worktree 隔离
  • ✅ 文件系统 Session 存储

交付物:

  • harness run 命令可用
  • 能够生成简单代码
  • 创建基础 PR

阶段 2: 验证与纠错 (Month 3-4)

目标: 质量保证闭环

功能:

  • ✅ Superpowers 语义验证
  • ✅ Archon 质量门禁
  • ✅ 自动修复机制
  • ✅ 升级人工策略
  • ✅ SQLite Session 存储

交付物:

  • 双层验证可用
  • 失败可自动修复
  • 质量门禁可配置

阶段 3: 平台化 (Month 5-6)

目标: 团队协作能力

功能:

  • ✅ Web Dashboard
  • ✅ 任务管理
  • ✅ 会话追踪
  • ✅ 成本追踪
  • ✅ 基础权限管理

交付物:

  • 可视化 Dashboard
  • 团队协作能力
  • 成本透明化

阶段 4: 企业化 (Month 7-8)

目标: 企业级能力

功能:

  • ✅ REST API
  • ✅ GitHub App 集成
  • ✅ 高可用部署
  • ✅ 审计日志
  • ✅ 告警系统

交付物:

  • 完整 API 服务
  • GitHub App
  • 生产级部署

阶段 5: 优化与扩展 (Month 9+)

目标: 性能优化、功能扩展

功能:

  • ✅ 性能优化
  • ✅ 多模型支持
  • ✅ 自定义验证器
  • ✅ 插件系统
  • ✅ SaaS 版本

交付物:

  • 更高性能
  • 更多功能
  • SaaS 产品

总结

Harness 最终形态:

一个企业级 AI 驱动的软件工程自动化平台,集成 CLI、Web、API 三种使用方式,提供从需求到代码的端到端自动化能力。

核心产品特征:

  • 🛠️ 工具化: CLI 工具,开发者友好
  • 🌐 平台化: Web Dashboard,团队协作
  • 🔌 服务化: API 服务,CI/CD 集成
  • 🛡️ 企业化: 权限、审计、成本管理

目标用户:

  • 个人开发者 → CLI 工具
  • 小团队 → Web Dashboard
  • 大企业 → 自托管/SaaS
  • DevOps → API 集成

一句话概括:

Harness 是"AI 版的 GitHub Copilot + CI/CD + 代码审查"的整合体,能够自动完成从需求到合并 PR 的完整流程。

Released under the MIT License.