Beans 是一款专为你、你的团队以及你的编程助手打造的问题追踪工具。 与在独立应用中跟踪任务不同，Beans 将任务直接存储在你的代码旁边。你可以使用 beans CLI 来管理任务，但更重要的是，你最喜欢的编程助手也可以做到！

这为你的机器人伙伴带来了重大升级：现在它们能够全面了解你的项目，提出下一步工作的建议，跟踪进度，针对发现的问题创建 bug 问题，等等。

你一生都在编程；现在，你也可以扮演产品经理的角色了！让我们一起出发吧！🚀

宣传预告片 ✨

https://github.com/user-attachments/assets/dbe45408-d3ed-4681-a436-a5e3046163da

稳定性警告 ⚠️

Beans 仍处于快速开发阶段，其功能和 API 可能还会发生较大变化。如果你决定现在就使用它，请密切关注发布说明。

由于 Beans 会为你的编程助手生成专属的提示指令，大多数更改都能“无缝衔接”；但有时我们会修改底层数据文件的结构，这可能需要一些手动迁移步骤。如果遇到这类变更，你的助手通常可以帮你自动迁移数据：

Beans 数据格式已更新。请将该项目的 beans 迁移到新格式。

功能特性

• 在代码旁直接跟踪任务、bug、功能需求等。
• 使用存储在项目 .beans 目录中的纯 Markdown 文件。易于版本控制，人机皆可读写！
• 使用 beans CLI 创建、列出、查看、更新和归档 beans；但更重要的是，让你的编程助手代你完成这些操作！
• 通过提供关于项目及其未完成任务的完整上下文信息，为你的机器人伙伴赋能。内置的GraphQL 查询引擎使助手能够精准获取所需信息，从而最大限度地减少 token 消耗。
• 项目记忆：已完成的 beans 会被归档，作为项目记忆供编程助手查询，以获取过往工作的背景信息。
• 内置精美的TUI 界面，方便你在终端中浏览和管理 beans。
• 根据你的数据自动生成项目的Markdown 路线图文档。

安装

我们需要完成三件事：

1. 安装 beans CLI 工具。
2. 配置你的项目以使用它。
3. 配置你的编程助手使其能够与之交互。

你可以从 Releases 页面下载 Beans，或者通过 Homebrew 安装：

brew install hmans/beans/beans

你也可以直接通过 Go 安装：

go install github.com/hmans/beans@latest

配置你的项目

在项目的根目录下运行：

beans init

这将会在项目根目录下创建一个 .beans/ 目录和一个 .beans.yml 配置文件。所有这些内容都应纳入版本控制系统进行管理。

从此时起，你可以通过 beans CLI 与你的 Beans 进行交互。要查看可用命令列表：

beans help

但更重要的是，你需要配置你的编程助手来使用它。让我们开始吧！

助手配置

让你的助手了解 Beans 的最简单方法，就是在你的 AGENTS.md、CLAUDE.md 或类似文件中添加以下指令：

**重要提示**：在执行任何操作之前，请先运行 `beans prime` 命令，并按照其输出指示操作。

有些助手提供了自动化这一步骤的机制：

Claude Code

官方的 Beans 插件正在开发中，但目前，请手动将以下钩子添加到你项目的 .claude/settings.json 文件中：

{
  "hooks": {
    "SessionStart": [
      { "hooks": [{ "type": "command", "command": "beans prime" }] }
    ],
    "PreCompact": [
      { "hooks": [{ "type": "command", "command": "beans prime" }] }
    ]
  }
}

OpenCode

Beans 通过插件与 OpenCode 集成，该插件会在会话中注入任务上下文。要进行设置，请将插件从 .opencode/plugin/beans-prime.ts 复制到你项目的 .opencode/plugin/ 目录（或复制到 ~/.opencode/plugin/ 以使插件在所有项目中全局可用）。

使用提示

作为人类，你可以通过运行以下命令来概览 CLI 的各项功能：

beans help

你可能对交互式 TUI 特别感兴趣：

beans tui

示例工作流程

但 Beans 的真正强大之处在于让你的编程助手为你管理任务。

假设你已正确将 Beans 集成到你的编程助手中，它就已经知道如何为你创建和管理 beans。你可以使用常规的自然语言查询方式。如果你刚刚将 Beans 添加到现有项目中，可以尝试让助手识别潜在的任务并为其创建 beans：

这个项目有哪些需要跟踪的任务吗？如果有，请为它们创建 beans。

如果你已经有一些 beans，可以请助手推荐下一步的工作内容：

我们接下来应该做什么？

你也可以明确要求助手开始处理某个特定的 bean：

现在该处理 myproj-123 了。

请记住，你的助手处理 beans 的能力与处理代码的能力一样强，因此不妨让它快速重组你的任务：

请检查一下这个项目的 beans，并将它们重新组织成史诗级任务。同时，请创建 2–3 个里程碑，以便以有意义的方式分组这些史诗级任务。

你还可以在 AGENTS.md、CLAUDE.md 或类似文件中添加专门针对 Beans 的指令，例如：

提交代码时，请在提交信息中包含相关的 bean ID。

贡献

目前该项目暂不接受贡献——因为还为时过早！不过，如果你有任何建议或反馈，欢迎随时提交 issue。

许可证

本项目采用 Apache-2.0 许可证。详细信息请参阅 LICENSE 文件。

联系我们

如果您有任何问题、建议，或者只是想打个招呼，欢迎随时联系我在 Bluesky 上，或在这个仓库中提交一个议题。

Beans 快速上手指南

Beans 是一款专为开发者、团队及 AI 编程助手设计的轻量级问题追踪工具。它将任务以 Markdown 文件的形式直接存储在代码仓库的 .beans 目录中，让 AI 助手能够全面理解项目上下文、自主规划任务并追踪进度。

环境准备

• 操作系统：支持 macOS、Linux 及 Windows（需配置相应终端环境）。
• 前置依赖：
  • 已安装 Git（用于版本控制任务文件）。
  • 已配置常用的 AI 编程助手（如 Claude Code, OpenCode 等），以便发挥 Beans 的核心优势。
• 网络要求：需能访问 GitHub Releases 或 Go 模块代理。

安装步骤

你可以选择以下任意一种方式进行安装：

方式一：使用 Homebrew (推荐 macOS 用户)

brew install hmans/beans/beans

方式二：使用 Go 直接安装

go install github.com/hmans/beans@latest

方式三：手动下载 访问 GitHub Releases 页面下载对应系统的二进制文件，并将其添加到系统环境变量 PATH 中。

基本使用

1. 初始化项目

在你的项目根目录下运行以下命令，Beans 将创建 .beans/ 目录和配置文件：

beans init

提示：请将生成的 .beans/ 目录和 .beans.yml 文件提交到 Git 版本控制中。

2. 人机交互

• 查看帮助：列出所有可用命令。

  beans help
  

• 启动图形界面：打开内置的终端用户界面（TUI）来浏览和管理任务。

  beans tui
  

3. 集成 AI 助手（核心用法）

为了让 AI 助手自动管理任务，请在项目的 AGENTS.md、CLAUDE.md 或等效配置文件中添加以下指令：

**IMPORTANT**: before you do anything else, run the `beans prime` command and heed its output.

针对特定助手的配置：

• Claude Code: 在项目 .claude/settings.json 中添加钩子：

  {
    "hooks": {
      "SessionStart": [
        { "hooks": [{ "type": "command", "command": "beans prime" }] }
      ],
      "PreCompact": [
        { "hooks": [{ "type": "command", "command": "beans prime" }] }
      ]
    }
  }
  

• OpenCode: 将插件文件 .opencode/plugin/beans-prime.ts 复制到你的项目 .opencode/plugin/ 目录（或全局 ~/.opencode/plugin/）。

4. 开始协作

配置完成后，你可以直接用自然语言与 AI 助手协作：

• 发现任务："Are there any tasks we should be tracking for this project? If so, please create beans for them."
• 规划下一步："What should we work on next?"
• 执行特定任务："It's time to tackle myproj-123."

注意：Beans 目前处于活跃开发阶段，数据格式可能会发生变化。若遇到格式变更提示，可指示你的 AI 助手运行迁移命令即可。