gitworthy

Gitworthy

编码 Agent 开始工作前的决策层。

Gitworthy 帮助编码 Agent 在投入精力实现之前，侦察、排序并预先检查软件工作。它会找出最有希望的候选项，检查相关工作是否已经处理或受阻，并为每个目标返回有证据支持的 ACT、VERIFY 或 SKIP 决策。

MCP 配置 · CLI · Agent 工作流 · 判定结果 · 故障排查 · 案例研究 · 路线图 · 参与贡献

---

为什么选择 Gitworthy

编码 Agent 让实现变得廉价，但选错任务依然代价高昂。

某个问题看起来可能尚未解决，但实际上：

• 已有修复存在于未关联的分支上；
• 另一位贡献者已有正在处理的拉取请求；
• 更改已合并到 main，但尚未发布；
• 仓库要求先分配任务才接受贡献；
• 重复或已弃用的实现中已经包含答案。

Gitworthy 会在人工或 Agent 投入下一份工作之前，执行这项预先检查。

Agent 如何使用 Gitworthy

Agent 负责整个循环。Gitworthy 是 Agent 用来侦察和验证工作的 MCP 决策引擎。

Contribution goal, repository, or organization
                      │
                      ▼
         Cursor / ChatGPT / Hermes / agent
                      │
                 Gitworthy MCP
                      │
                      ▼
        policy → scan → rank → preflight
                      │
             ┌────────┼────────┐
             ▼        ▼        ▼
            ACT     VERIFY    SKIP
          queue it   inspect   drop it
             │
             ▼
     optional `portfolio`
     (mode + dispatch, not a new verdict)
             │
             ▼
       Ranked candidate shortlist
             │
             ▼
         Select a candidate
             │
             ▼
   recheck → reproduce → implement → review

这里有两个不同的阶段：

• **侦察阶段：**发现、筛选、排序、预先检查并返回候选项列表。
• **执行阶段：**选择目标、记录意向、重新检查最新状态、复现问题、实现、审查，并通过仓库允许的贡献渠道提交。

ACT 表示“值得考虑”，而不是“盲目开始编码”。侦察结果会过时，因此 Agent 实际认领或开始处理目标时，应再次运行 Gitworthy。

完整的 Agent 策略、工具选择指南以及从侦察到执行的交接说明，请参阅 docs/AGENT_WORKFLOW.md。

搭配 Cursor、ChatGPT、Hermes 或任何 MCP 客户端使用

本地 stdio（桌面端 / Agent VM）

{
  "mcpServers": {
    "gitworthy": {
      "command": "npx",
      "args": ["-y", "gitworthy@latest", "mcp"],
      "env": {
        "GITHUB_TOKEN": "github_pat_..."
      }
    }
  }
}

Streamable HTTP（Cloud Agents / 移动设备 / iPad）

通过 HTTP 运行或部署同一引擎，并让客户端连接到一个 URL：

export GITWORTHY_MCP_TOKEN="$(openssl rand -hex 32)"
export GITHUB_TOKEN="github_pat_..."
npx -y gitworthy@latest mcp --http --host 127.0.0.1 --port 8787

{
  "mcpServers": {
    "gitworthy": {
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:GITWORTHY_MCP_TOKEN}"
      }
    }
  }
}

绑定到非回环地址需要 GITWORTHY_MCP_TOKEN。请将 GITHUB_TOKEN 保存在服务端。完整部署说明和 Cloud Agent 注意事项，请参阅 docs/HTTP_MCP.md。工具描述、注释和结构化结果，请参阅 docs/MCP.md。可移植的 Agent Plugins 打包方式（技能 + MCP），请参阅 docs/AGENT_PLUGINS.md。

为 Agent 提供如下策略：

在投入外部仓库的工作之前，先使用 Gitworthy。使用 hunt 建立一个简短的排序队列。阅读每个候选项的 worth_check；hunt 不会给出一个全局判定结果。将 ACT 视为队列中的候选项，对 VERIFY 执行指定的检查，并移除 SKIP 候选项。实现选定目标之前，重新运行 worth_check，并遵循仓库的贡献政策。

令牌只需拥有对公共仓库的读取权限。为准确检测关联工作，请使用经典 PAT，或具有 Issues: Read 权限的细粒度令牌，这样 Gitworthy 才能查看时间线中的交叉引用。权限较弱的令牌仍可使用，但缺失的可见性会在 not_checked 中报告。

30 秒内试用

检查环境是否已就绪：

npx -y gitworthy@latest doctor --json

评估特定问题：

npx -y gitworthy@latest check owner/repo#123

根据已存储的决策生成确定性的交接简报：

npx -y gitworthy@latest brief decision_abc123 --format markdown --out brief.md

简报生成只读本地存储，不会调用 GitHub、npm 或大模型。已存储的决策在 24 小时后会被视为过期；过期的简报会发出警告并建议执行 recheck。

侦察并预检一份简短的贡献目标清单：

npx -y gitworthy@latest hunt owner/repo --json
npx -y gitworthy@latest hunt openclaw --max-checks 3 --json

探索时使用 @latest。在可重复的 Agent 工作流和 CI 中固定版本。

hunt 实际返回的内容

hunt 是一个有界漏斗，而不是批量判定命令：

contribution policy
        ↓
scan repository or organization
        ↓
rank issue quality and optional skill fit
        ↓
remove obvious land-only, assigned, weak, or known-SKIP rows
        ↓
run worth_check on only the best few candidates
        ↓
return candidates with individual verdicts and evidence

Agent 应读取每个 hunt_candidate.worth_check。Gitworthy 有意避免对广泛扫描返回的每个问题都运行成本高昂的完整预检。

ACT、VERIFY 或 SKIP

判定	侦察行为	执行行为
ACT	阅读证据后，将其加入排名队列。	在认领或实现前重新检查；只有在状态最新且策略仍允许时才继续。
VERIFY	显示该项，并指出尚未解决的检查。	在 fork 或公开认领前解决这些检查。
SKIP	将其从队列中移除。	不要开始并行工作；检查引用的工作或选择其他目标。

判定不是基于感觉的评分。Gitworthy 会返回结构化证据、已完成的检查，以及无法完成的检查。

一次真实的预检

block/buzz 中的一个目标问题看起来仍处于开放状态，但此前已有一个几乎使用相同标题的拉取请求实现了相应工作。

Target: block/buzz#1659
Verdict: VERIFY
Disposition: review

Evidence:
- An implementation exists in PR #1675.
- The pull request is linked work, not a duplicate issue.

Next action:
Inspect the current implementation before starting parallel work.

这个案例还揭示了重复项检测中的一条误报路径：GitHub 的 issues API 会包含拉取请求。修复方案后来成为回归测试和校准案例。

更多真实的贡献会话记录在 CASE_STUDIES.md 中。

工作原理

Gitworthy 结合多项有界检查，分别应对任务启动可能不安全或浪费资源的不同情况。

检查	防范的问题
关联工作	现有拉取请求、指派记录、引用的提交和先前尝试
分支扫描	未关联的远程分支上已有的工作
问题与 main 的对比	问题仍处于开放状态时已合入的修复
发布差异	main 上存在但尚未包含在已发布软件包中的更改
贡献策略	认领要求、指派规则，以及不接受拉取请求的仓库
重复项分析	相关问题或此前已报告的问题
扫描 / 组织扫描	未排序的问题跟踪器噪声
Hunt	在耗费较高的预检前缩小候选范围，避免浪费性的广泛检查

CLI 和 MCP 服务是基于同一个 TypeScript 核心构建的轻量适配器。

信任模型

Gitworthy 旨在提供实用帮助，同时不会假装自己知道超出检查范围的内容。

• 启发式证据不能单独触发硬性 SKIP。
• 硬性 SKIP 必须有确凿证据支持。
• 强制检查失败时，结果最高只能为 VERIFY。
• 每个实际结果都包含有意义的 checked 和 not_checked 字段。
• 不会解析面向人类的说明文字来决定判定结果。
• 将目标仓库和软件包视为不可信输入。
• 遥测默认关闭。MCP 路径不会发出任何遥测数据。
• 不会将侦察结果视为永久有效；执行前必须重新验证最新状态。

ACT 不代表“盲目开始编码”。投入工作前，请阅读证据、处置结果、原因、关联工作和仓库策略。

面向 Agent 的输出

每个核心结果都包含一个结构化封装：

{
  "verdict_summary": "one sentence",
  "evidence": [],
  "signals": [],
  "checked": [],
  "not_checked": [],
  "cached": false,
  "fetched_at": "2026-01-01T00:00:00.000Z"
}

signals 是决策策略所依赖的关键输入。checked 和 not_checked 是结果的一部分，而非脚注。

常用命令

gitworthy check owner/repo#123 [--npm-package name] [--json]
gitworthy hunt owner/repo [--manifest path] [--max-checks 3] [--json]
gitworthy portfolio owner/repo [--max-items 10] [--json]
gitworthy prs owner/repo [--json]
gitworthy ci-triage --head-check test:failure --base-check test:success [--json]
gitworthy history owner/repo --path src/core/hunt.ts [--json]
gitworthy opportunity-ingest --source hermes-eval --id case-9 [--json]
gitworthy scan owner/repo [--label "help wanted"] [--json]
gitworthy org owner [--manifest path] [--max-repos 8] [--json]
gitworthy policy owner/repo [--json]
gitworthy init [--user] [--repo] [--json]
gitworthy config validate [--path path] [--manifest path] [--json]
gitworthy config show --effective [--json]
gitworthy profile show [--json]
gitworthy related owner/repo [issue] [--json]
gitworthy ledger show owner/repo#123 [--json]
gitworthy doctor [--json]
gitworthy mcp
gitworthy mcp --http [--host 127.0.0.1] [--port 8787] [--stateless]

check 的退出码：

• 0 — ACT
• 10 — VERIFY
• 20 — SKIP
• 1 — 错误

严格的贡献门槛请参阅 SKILL.md，说明性工作流指南请参阅 docs/AGENT_WORKFLOW.md。

文档

文档	主题
docs/AGENT_WORKFLOW.md	Scout 与 execute、工具选择
docs/VERDICTS.md	ACT / VERIFY / SKIP 和处置方式
docs/CLI.md	CLI 参考和退出代码
docs/MCP.md	MCP 工具、注释、结构化结果
docs/AGENT_PLUGINS.md	Agent Plugins v1 打包（skill + MCP）
docs/HTTP_MCP.md	Streamable HTTP MCP
docs/CONFIG.md	配置、清单、配置档案
docs/DATA.md	本地存储、结果、捕获数据
docs/EVALS.md	冻结 / 实时 / 私有评估
docs/CORPUS.md	语料分类（通过率与精确率）
docs/CORPUS_CONTRIB.md	如何扩充 Track O 与 Track F
docs/TRACK_O.md	结果校准（Track O；不是发布门槛）
docs/BETA.md	设计合作伙伴 Beta（GW-034）
docs/SECURITY_MODEL.md	信任边界
docs/TROUBLESHOOTING.md	由 Doctor 驱动的修复
docs/COMPATIBILITY.md	1.0 之前的契约策略
docs/PERFORMANCE.md	计数器与预算
docs/RANKING.md	排名契约
docs/RELEASE_1.0.md	1.0 门槛检查清单

配置

• GITHUB_TOKEN / GH_TOKEN 用于启用经过身份验证的 GitHub REST 检查。
• 配置文件是仅包含数据的 JSON。Gitworthy 从 ~/.gitworthy/config.json 读取用户配置，从 .gitworthy/config.json 读取仓库本地配置。
• 优先级依次为：CLI/MCP 输入、GITWORTHY_* 环境变量、仓库配置、用户配置、内置默认值。gitworthy config show --effective --json 会显示每个生效值的来源。
• 使用 gitworthy init --repo 或 gitworthy init --user 创建不含密钥的配置框架。使用 gitworthy config validate 验证。
• 技能配置档案（配置中的 profile 或 --skill-profile）可以包含 languages、topics、preferred_ecosystems 和避免列表；它们只影响 scan/hunt 排名输入，不会改变硬性判定策略。
• 目标清单（--manifest path 或配置中的 manifest_path）可以列出仓库 / 组织、包含 / 排除筛选条件、每个仓库的 npm 软件包映射以及特定目标的覆盖项。含糊的 npm 软件包映射会被拒绝。GW-019 会验证包含 / 排除筛选条件，并将其作为清单元数据保留；完整的筛选条件应用推迟至 GW-027。
• 配置文件或清单中绝不会保存令牌和凭据；请使用 GITHUB_TOKEN / GH_TOKEN 等环境变量。
• GITWORTHY_MCP_TOKEN 是 Streamable HTTP MCP 的 bearer 密钥（非回环绑定时必需）。
• GITWORTHY_CACHE_DIR 用于覆盖 ~/.gitworthy/cache 下的缓存目录。
• GITWORTHY_LEDGER_DIR 用于覆盖 ~/.gitworthy/ledger 下的本地 scout 历史记录目录。
• 设置 GITWORTHY_TELEMETRY=on 和 GITWORTHY_POSTHOG_KEY 可请求启用可选遥测。

可选的 PostHog 遥测还需要用户自行安装 posthog-node 软件包。如果未安装，Gitworthy 会警告一次并继续运行，同时停用遥测。

如果没有 GitHub 令牌，需要 GitHub REST 的检查会返回结构化错误或明确的 not_checked 条目。可使用公开 git 或 npm 端点的检查仍会运行。

当前状态

Gitworthy 尚未达到 1.0，正在积极强化其决策契约、恶意输入处理、本地结果、评估语料和入门体验。

1.0 的目标是打造可信、本地优先的 CLI 和 MCP 决策引擎，而不是托管式 SaaS，也不是另一个编码 Agent。

请参阅 ROADMAP.md 了解发布阶段。

未来方向

Gitworthy 正在成为任务发现与实现之间的 Agent 原生就绪层：

1. 发现候选任务；
2. 排序，找出最有希望的目标；
3. 判断每个目标是否确实已就绪；
4. 返回可由机器执行的下一步操作；
5. 在执行前重新验证选定的任务；
6. 记录执行结果；
7. 根据实际结果改进未来的决策。

开源决策引擎将继续以本地优先的方式运行，并采用 MIT 许可证。1.0 版本之后可能加入的层包括共享结果历史记录、定时搜寻、私有仓库协作，以及用于 Agent 分派的 API。

贡献

Gitworthy 源于真实案例：看似尚未处理的任务，后来却发现已经有人处理、遭遇阻碍，或不适合着手开展。

最有价值的贡献包括：

• Gitworthy 做出错误判断的案例；
• Gitworthy 无法正确检查的仓库或生态系统；
• Cursor、ChatGPT、Claude Code、Codex、OpenClaw、Hermes 或其他 Agent 集成；
• 提升证据质量和故障报告的改进；
• 新的冻结评估案例；
• 帮助他人快速获得有用结果的文档。

有关开发环境设置和信任要求，请参阅 CONTRIBUTING.md。

要求

• Node.js 22 或更高版本
• 强烈建议使用 GitHub 令牌进行实际搜寻

安全

请通过 SECURITY.md 私下报告漏洞，或发送邮件至 [email protected]。

许可证

MIT