goaltree

GoalT（目标树）

一个多父级、价值传播的目标图。处于概念阶段，已开源，欢迎大家指出问题。

构想

大多数优先级排序工具都假设存在清晰的层级结构：一个目标拆分成子目标，子目标再拆分成更细的子目标，以此类推。但实际工作很少是这样。一个功能可能同时依赖另外两项工作；一个缺陷修复可能因为不同原因，对三个不同项目都很重要。树无法表达这种关系，图或许可以。

GoalT 正是为此而设计的小型引擎：

• 只有一个根目标。 一切都可以追溯到它。
• 任意目标都可以有多个子目标，也可以有多个父目标。 这是有向无环图（DAG），不是树。
• 每个父目标都在其子目标之间分配总计恰好为 1.0 的价值。
• 有多个父目标的目标会累加来自各个父目标的价值——因此，对更多目标确实重要的目标自然会排在前面。
• 添加目标时，只会重新计算它影响到的图部分，而不是整个图。
• 明确拒绝环路，不会悄悄允许循环。

价值重新分配（即父目标如何在子目标之间拆分价值）的方式可插拔。默认方式是简单的平均分配——结果确定、无需 API 密钥，而且总能收敛。你也可以接入 LLM，让它根据上下文决定权重（例如“这个冲刺中，速度比精雕细琢更重要”）。引擎绝不会直接信任 LLM 返回的数值：它会验证并重新归一化所有结果，确保即使模型返回了异常值，图在数学上仍然保持一致。

无需安装即可试用

点击上方的“Open in Colab”徽章，即可在浏览器中打开 demo.ipynb，无需任何设置。从上到下运行各个单元格即可。

本地安装

要求： Python 3.10+（Claude Code 服务所需的 mcp 包要求此版本）。如果你使用 macOS，且 pip install 因类似“Requires-Python >=3.10”或“No matching distribution found for mcp”的错误而失败，很可能是因为你安装了多个 Python，而 pip 指向了错误的版本（Xcode 命令行工具捆绑的 Python 就常出现这种情况）。使用 python3 --version 检查；如果版本为 3.10+，请使用 python3 -m pip install ...，而不是直接运行 pip install ...，这样可以确保软件包安装到实际运行服务的同一个 Python 环境中。

python3 -m pip install goaltree

核心引擎只需要 networkx。较重的组件是可选项，因此只需 安装实际会用到的组件：

python3 -m pip install "goaltree[viz]"   # + matplotlib, for visualize.draw
python3 -m pip install "goaltree[mcp]"   # + the Claude Code MCP server and dashboard
python3 -m pip install "goaltree[all]"   # everything

也可以从源码安装：

git clone https://github.com/GOAL-T/goaltree.git
cd goaltree
python3 -m pip install -e ".[all]"

from goaltree import GoalGraph

g = GoalGraph()
g.add_root("root", "Ship v2 of the product")
g.add_goal("a", "Improve onboarding", parents=["root"])
g.add_goal("b", "Improve performance", parents=["root"])
g.add_goal("c", "Fix export bug", parents=["a", "b"])  # depends on both

print(g)

GoalGraph(root='root')
  1.000  Ship v2 of the product (root)
  1.000  Fix export bug (c)
  0.500  Improve onboarding (a)
  0.500  Improve performance (b)

请注意，c 的值为 1.000，根目标的值也为 1.000，而 a、b 和 c 的值之和大于根目标的值。这是有意设计的，不是错误：价值是按父目标 守恒的（每个父目标都会在其子目标之间分配总计恰好为 1.0 的价值）， 而不是在整个图中全局守恒。一个目标服务于两个父目标时，会从两者累加价值。

因此，这个数值并不表示固定预算中的份额，与根目标的 1.0 相比也没有意义。它表示影响权重，回答的是“有多少事情取决于它”，而不是“它占整个项目的多少”。在这里，导出缺陷是两个子目标的关键依赖，因此图中其他工作都无法在不受其影响的情况下完成——这正是 1.000 所表达的含义。

完整演示请参阅 demo.ipynb，其中包括由 LLM 驱动的价值重新分配示例。

在 Claude Code 中使用

GoalT 以 Claude Code 插件的形式提供：一个 MCP 服务（可在对话中构建和查询目标树），以及一个实时仪表板。仪表板会随服务自动启动，并实时突出显示 Claude 当前正在处理的目标。

安装为插件（推荐）

首先安装一次服务的依赖项：

python3 -m pip install "goaltree[mcp]"

然后，在 Claude Code 中：

/plugin marketplace add GOAL-T/goaltree
/plugin install goalt@goalt-marketplace

这会自动配置 MCP 工具和活动钩子。GoalT 刻意不会在服务启动时替你安装软件包：启动时运行 pip install 的插件会从你刚审查过的仓库之外从网络获取代码，没人应该需要如此信任一个插件。如果缺少依赖项，服务会明确告知要运行哪条命令，而不会背着你安装任何东西。

手动安装（没有活动钩子，但仍可使用）

git clone https://github.com/GOAL-T/goaltree.git
cd goaltree
claude mcp add --transport stdio goalt -- bash "$(pwd)/bootstrap.sh"

这样可以获取工具，但没有“Claude 当前正在……”的自动活动脉冲——这部分依赖插件钩子，只会通过上面的插件安装路径注册。

使用方法

为现有代码库创建目标树： 在你想要规划的项目中运行 /goalt:start 斜杠命令。Claude 会探索代码仓库（README、包清单、文件夹结构，以及存在时的数据库迁移），识别实际的功能领域，并构建一棵树，其中包含真实的描述——链接到它确信确实能实现每个目标的文件和后端构件（数据库表、边缘函数等），而不是捏造结构。

从头开始时， 在 Claude Code 会话中输入：

“为发布我们产品的 v2 创建一棵目标树，包含入门引导和性能两个子目标，以及一个依赖这两个子目标的共享 Bug 修复目标。向我展示优先级并打开仪表板。”

Claude 会调用 create_tree、add_goal 和 list_priorities，然后由 open_dashboard 提供一个 URL（http://127.0.0.1:8765），供你在浏览器中打开。接下来，你可以：

• 监视模式：Claude 工作时，让仪表板保持打开。每次调用工具时，页眉都会显示实时的“Claude 当前正在……”指示器——这一功能有保证，并通过 Claude Code hook 实现。
• 文件编辑高亮（有保证）：为目标关联 related_files 后，只要编辑其中一个文件，该目标就会自动以发光的绿色边框高亮显示——无需额外调用工具，hook 会将编辑过的路径与每个目标的关联文件进行匹配。
• 主动目标高亮（尽力而为）：对于无法明确关联到特定文件的目标，Claude 可以调用 set_active_goal 并提供原因。此功能仅尽力而为——是否触发取决于 Claude 是否选择调用，并无保证。
• 未提交更改跟踪：如果创建目标树时设置了 project_root，后台线程会每隔几秒轮询一次 git status；如果任何关联文件存在未提交更改，就会为相应目标显示琥珀色边框——无论此时是否正在编辑文件。
• 点击任意节点可打开侧边面板，其中有两个选项卡：描述（目标描述及其关联文件／后端构件）和更改（当前正在编辑和／或存在未提交更改的文件，仅限此目标）。点击当前处于活动状态或有未提交更改的节点时，会直接打开“更改”选项卡。
• 在 VS Code 中打开文件：关联文件或更改列表中的每个文件都是可点击的链接（vscode://file/...），点击即可在 VS Code 中直接打开——如果已安装 VS Code，则开箱即用，无需设置。存在未提交更改的文件还会显示一个差异按钮，可打开标准的并排差异视图（HEAD 与工作副本）。在 macOS 上，该按钮会直接启动 VS Code（无需设置 PATH，只要安装了 VS Code 即可）；其他平台上则会使用 PATH 中的 code CLI。如果两者都不可用，按钮会明确告知你该怎么做，而不是静默失败。
• 拖动节点可重新排列它们——位置会保留，不会在下次更新时恢复原位。点击“重置布局”可让图表重新自动布局。

可用工具： load_tree、create_tree、add_goal、link_artifacts、list_priorities、set_active_goal、clear_active_goal、open_dashboard、reset_tree。

当前限制：

• 每次更改都会将目标树自动保存到 <project_root>/.goalt/tree.json，并在下次会话时自动加载（启动时尽力猜测，或在 Claude 确定实际项目根目录后通过 load_tree 可靠加载——系统指令会先引导 Claude 到该目录）。如果你不想提交 .goalt/，请将其添加到项目的 .gitignore 中。
• 文件与目标的匹配（goals_for_file）使用的是后缀匹配启发式算法，而非精确路径解析——在不常见的项目布局中，模糊的相对路径可能导致匹配错误。
• 未提交更改跟踪假定 project_root 下只有一个 Git 仓库，并按固定间隔（几秒）重新轮询，因此更改发生后要过一小段时间才会显示。

此仓库的实际内容

• goaltree/goal_tree.py -- 核心引擎：图构建、环检测、确定性值传播，以及可插拔的 LLM 再分配钩子。唯一没有可选依赖的模块，也是唯一直接从 goaltree 重新导出的模块。

• goaltree/visualize.py -- 一个轻量的 matplotlib/networkx 封装，供 demo.ipynb 绘制静态图像。需要 [viz] extra。

• demo.ipynb -- 交互式、可运行的演示指南（可在 Colab 中运行，无需本地设置）。

• goaltree/mcp_server.py -- MCP 服务：提供用于构建／查询树的工具，以及尽力而为的活动目标跟踪功能。加载时会自动启动仪表板。需要 [mcp] extra。

• goaltree/dashboard.py -- 实时交互式 Web 仪表板（FastAPI + vis-network，单文件，无需构建步骤），其中包含 Claude Code 的 PreToolUse 钩子所调用的钩子端点。需要 [mcp] extra。

• pyproject.toml -- 打包元数据；还定义了 goalt-mcp 控制台脚本，它只是用较短的名称执行 python -m goaltree.mcp_server。

• .claude-plugin/plugin.json、.claude-plugin/marketplace.json、.mcp.json、hooks/hooks.json -- 插件打包配置，让整个项目只需两个命令即可安装（见上文）。

• commands/start.md -- /goalt:start 斜杠命令，可将 GoalT 引入现有代码库。

• bootstrap.sh -- 插件的实际入口点（见 .mcp.json）。运行时会查找 Python 3.10+ 解释器，因此不会在任何位置硬编码特定于某台机器的路径；它会检查服务依赖是否可导入，如果不可导入，则拒绝启动并提供可直接复制粘贴的安装命令。按设计，它本身不会安装任何内容。

• hooks/hooks.json、hooks/pulse.py -- 活动脉冲。Claude Code 会将完整的工具负载交给 PreToolUse 钩子；对于 Write，其中包含要写入的整个文件；pulse.py 会在将数据 POST 到 127.0.0.1 上的仪表板之前，将其精简为工具名称和文件路径。命令绝不会被发送，连预览也不会，所以 shell 调用只会显示为“正在运行：Bash”。钩子进程不会发送其他任何内容。

• tests/ -- 62 个测试，涵盖核心引擎、仪表板的 API／钩子逻辑，以及 MCP 工具的端到端测试（通过真实 MCP 客户端，以 Claude Code 与其通信的相同方式进行）。参见下方的“运行测试”。

目前还没有 CLI -- 如果有需求，这会是自然的下一步。

运行测试

python3 -m pip install -e ".[dev]"
pytest

共 62 个测试，分布在三个文件中：

• tests/test_goal_tree.py -- 核心引擎（多父节点值传播、环处理、工件关联、文件匹配、保存／加载往返），不涉及 I/O。
• tests/test_dashboard.py -- 纯辅助函数、用于检测未提交更改的真实 git 测试样例、VS Code 差异比较回退链（使用模拟，无需 GUI），以及通过 TestClient 测试 FastAPI 端点。
• tests/test_mcp_server.py -- 集成测试：真实 MCP 客户端通过 stdio 与真实的 goaltree.mcp_server 子进程通信，涵盖实际工具（create_tree、add_goal、link_artifacts、set_active_goal、load_tree／持久化、reset_tree）。运行较慢（总计约 30 秒），因为每个测试都会启动真实进程；但这确实会测试 Claude Code 所调用的工具层。

已知未解决的问题

坦诚说明这些问题，不夸大其词：

• 使用 LLM 驱动权重时的收敛性。 确定性回退机制在设计上总会收敛。反复使用 LLM 驱动的重新加权，在大型图中经过多次编辑后能否保持稳定，目前尚未得到证明，只在小型示例中观察到这一点。
• 全局值不会守恒。 由于一个节点可以有多个父节点，图中所有节点值的总和整体上并非 1.0 —— 只有在每个父节点的局部范围内，其子节点的权重之和才是 1.0。这是有意设计的（正是这种机制让“实际依赖越多，影响力越大”得以实现），但在过度解读原始数值前，值得先了解这一点。
• 大规模场景下的成本。 接入真实 LLM 后，每次 add_goal 调用都可能针对每个受影响的父节点触发一次重新分配调用。在大型、层级很深的图中，每次编辑都可能产生大量 API 调用。目前尚未实现缓存或批处理。
• 尚无基准测试。 尚未在真实待办事项列表上，将其与经典优先级排序方法（AHP、加权评分、简单的 OKR 逐级分解）进行比较。这是自然的下一步，而非已经提出的主张。
• 目前的循环检测是防御性后备措施，而非主动防护。 仅通过公开的 add_goal API，不可能构成循环，因为新节点尚无出边。此检查针对的是计划中的未来功能——将两个已存在的目标关联起来；届时循环才真正有可能出现。
• 启动时自动加载只是推测，并非保证。 在服务启动时，GoalT 会尝试加载已保存的树，并用其自身进程的工作目录推测 project_root —— 当 Claude Code 恰好从项目目录启动 MCP 服务时，这种方式有效，但无法保证。可靠的方式是显式调用 load_tree 工具；系统指令会要求 Claude 首先使用实际项目根目录调用该工具，再判断树是否不存在。
• 与现有工作的关系。 这种值传播机制与基于 DAG 的 PageRank 类算法密切相关。如果你知道有更好的既有方案，欢迎提交 issue —— 我们确实很感兴趣，并非想重复发明已有的东西。

贡献

欢迎提交问题和 PR —— 请参阅 CONTRIBUTING.md。指出问题和扩展功能同样有价值；如果你发现某种情况下图会产生错误或不稳定的结果，这正是目前最需要的反馈。

许可证

Apache 2.0 —— 请参阅 LICENSE。欢迎使用、分叉并基于它构建，无论是否用于商业用途。