Skip to main content
Glama

estimate-maestro

一个用于记录估算和实际耗时的个人 MCP 服务器与命令行工具,让估算最终能够对照实际结果来检验,而不是凭感觉。

这是一个用于估算校准的数据收集工具,而不是估算器。 它永远不会替你估算任何东西。它记录的是你对一项工作估算的规模、计划最终变成的样子,以及这项工作实际消耗的墙钟时间。你拿这份记录做什么——比较、发现偏差、判断自己对某类工作一贯过于乐观——取决于你自己,也取决于之后读取存储的任何东西。这个工具的职责止于如实记录。

模型

有四类东西会被记录:

  • Effort(工作项) — 一件值得单独跟踪的工作:一个 pull request、一个 mega-PR,任何有计划和大小的东西。一个 effort 从它拥有计划产物(一份 spec、一个 .PR.md,无论计划存在于什么之中)和初始估算的那一刻起就存在。在那之前,还没有什么可记录的。

  • Slice(切片) — effort 的一部分,通常是子 PR。切片可以被添加、针对某个 pull request 关闭、丢弃或重命名。在 effort 开始之前添加的切片属于原始计划的一部分;之后添加的则属于范围增长,两者在记录中保持可区分。

  • Interval(时间区间) — 一段打卡记录的时间跨度,通常对应某个切片。区间可以手动关闭,可以在会话结束时时钟仍在运行的情况下自动关闭,也可以在完全没有打卡记录时事后根据提交时间戳推导得出。

  • Absence(缺勤) — 完全没有工作的时间:假期、约会、无关的会议。缺勤是事后记录的,而且理应如此。它们会从所重叠的任何区间中扣除。

Related MCP server: time-tracker-ai-mcp

估算:以故事点表示的三点三元组

每个估算都是一个 PERT 三元组 —— 乐观值、最可能值、悲观值 —— 以抽象的点数标度给出,绝不以小时为单位。期望值和标准差在读取时从三元组推导得出;任何地方都不会存储单一的"估算值是 N"这样的数字,因为一个光秃秃的数字会丢掉那些让它成为估算而非事实的不确定性。

点数的锚定方式是将手头的工作与形状相似的先前 effort 进行比较,而不是在脑子里把感觉到的工时数换算成点数。抽象标度的全部意义就在于,在你还不知道实际耗时的 effort 之间进行同类比较。

一个 effort 会被估算 两次:

  • 初始估算,针对最初写下的计划进行,切片数量与计划开始时相同。

  • 最终估算,在回顾时针对计划实际变成的样子进行——包括过程中插入的每一个切片。这是一个反事实问题:"鉴于你现在对这件事实际发展走向的全部了解,你当初会估算多少?"——绝不是"花了多长时间?",也绝不是对任何东西的测量。

把估算拆成两次,正是为了让估算可能出错的两种方式在事后可以分离。初始那次可能因为清单误差而出错——存在当时还没人知道的工作,或者原本以为存在的工作结果并不存在。最终那次针对计划实际变成的样子进行,隔离出规模误差——那些从头到尾都知道、只是判断错了的项目。每个 effort 一个数字会把两者混为一谈;两个数字、每次一个,就能把它们分开。

修订后的估算也可以在 effort 进行中记录——通常是在插入了原始计划中没有的切片时——不必等到回顾时。

时间模型:默认一个正常工作日

默认假设一个正常的工作日,只记录与之不同的偏差。 打卡上下班是例外,不是常规——这个工具并不指望每天有八小时的秒表在跑。具体来说:

  • 手动打卡的时间全额计入,无论落在什么钟点。晚上和周末也包括在内:如果你在周六 22:00 打卡,那就是真实时间,按原样记录,不应用任何工作时段调整。

  • 工作时段模型只在实际没有记录任何时间的地方生效。 它恰好用在两个地方:

    • 截断被遗忘的计时器。 如果会话结束时时钟仍在运行,区间会在配置的工作日结束时间关闭(或者,在配置的工作日和时段之外,上限为固定的会话时长),而不是无限期保持开启或被精确到分钟地猜测。

    • 从提交时间戳重建区间,当某个切片从未有过任何打卡记录时。一组邻近的提交会变成一个推导出的工作会话,使用工作时段模型来判断它们之间的跨度中有多少算作工作,而不是隔夜间隙。

记录在某段时间上的缺勤会从它所重叠的任何区间——无论是打卡的还是推导的——中扣除,对于手动打卡的区间全额扣除,对于推导的区间则通过工作时段模型扣除。

工具类别与污染规则

MCP 服务器暴露的每个工具都恰好属于一个类别:

  • recording(记录) — start_effort、add_slice、close_slice、drop_slice、rename_slice、clock_in、clock_out、annotate_interval、repair_interval、record_absence、record_revision、record_final_plan、harvest_commits、record_landed_commit、remap_commits、finish_effort。

  • estimation(估算) — reference_efforts,在做出估算时显示先前的 effort 以供比较。

  • status(状态) — current,报告当前打卡了什么以及从何时开始。

  • calibration(校准) — effort_table、effort_detail、summary,把累积的记录读出来。

记录、估算和状态工具绝不返回时长或聚合值。只有校准工具可以。 这一点在结构上得到强制:记录、估算或状态工具使用的每个响应模型都会被检查字段名是否包含 hours、minutes、duration、wall、average 或 share 等词,如果发现一个,检查就会失败。

原因不是整洁。在看到工作的真实时长之后做出的估算,是那个时长的锚定回声,而不是独立的判断——你产出的数字已经被刚刚看到的答案污染了。污染规则确保在做出估算或运行时钟期间,墙钟时间数字永远不会出现在工具响应中,从而使初始与最终的比较保持诚实。校准工具是豁免的,因为它们的全部目的就是在估算完成之后报告这些数字。

环境变量

全部都是可选的;每一个都有默认值。如果两者出现不一致,以 src/estimate_maestro/config.py 为准,而不是这份列表。

变量

默认值

含义

ESTIMATE_MAESTRO_STORE

$XDG_DATA_HOME/estimate-maestro,回退到 ~/.local/share/estimate-maestro

存储目录的路径。

ESTIMATE_MAESTRO_DAY_START

09:00

工作日的开始时间(ISO 8601 时间)。

ESTIMATE_MAESTRO_DAY_END

17:00

工作日的结束时间(ISO 8601 时间)。

ESTIMATE_MAESTRO_LUNCH_START

12:00

每日午休的开始时间,从工作秒数中排除。

ESTIMATE_MAESTRO_LUNCH_END

13:00

每日午休的结束时间。

ESTIMATE_MAESTRO_WORKDAYS

0,1,2,3,4

以逗号分隔的、计为工作日的星期几(周一 0 … 周日 6)。

ESTIMATE_MAESTRO_OFF_HOURS_SESSION_CAP_MINUTES

240(4 小时)

给在工作时段窗口之外开始的截断会话的最大时长。

ESTIMATE_MAESTRO_DERIVE_LEAD_IN_MINUTES

30

在推导会话中最早提交之前增加的时间,用于覆盖第一次提交之前完成的工作。

ESTIMATE_MAESTRO_DERIVE_SESSION_GAP_MINUTES

120(2 小时)

提交之间的工作时间间隔,超过该间隔即认为推导会话已结束、新会话已开始。

ESTIMATE_MAESTRO_MINIMUM_EFFORTS

5

summary 报告数字而非诚实拒绝之前所需的最少已记录 effort 数量。

ESTIMATE_MAESTRO_DERIVE_LEAD_IN_MINUTES 不得超过 ESTIMATE_MAESTRO_DERIVE_SESSION_GAP_MINUTES;否则服务器拒绝启动。

命令行工具

estimate-maestro-cli 覆盖不需要对话的日常记录操作:clock-in、clock-out、current、record-absence、effort-table 和 summary。那些只有作为估算对话的一部分才有意义的操作——启动 effort、修订估算、记录最终计划、收集提交——刻意只作为 MCP 工具而非 CLI 命令:它们本应发生在展示可比先前 effort 的会话中,而不是作为脱离该上下文的裸命令输入。

退出码

代码

含义

0

成功。

1

发生了错误。

3

仅 clock-out:没有打卡任何内容。这是预期且常见的,不是失败——将 clock-out 接入自动钩子的脚本应当把 3 与 0 同等对待。

安装

以下操作都没有替你执行过——请复制下面的命令并自行运行。

注册 MCP 服务器:

claude mcp add --scope user maestro-estimate -- uv --directory ~/mcp/estimate-maestro run estimate-maestro

将两个技能符号链接到你的个人技能目录:

ln -s ~/mcp/estimate-maestro/skills/recording-work-time ~/.claude/skills/recording-work-time
ln -s ~/mcp/estimate-maestro/skills/estimating-work ~/.claude/skills/estimating-work

将存储设为 git 仓库。其文件是纯文本且仅追加,因此可以提交并在机器之间漫游,而且它是所记录内容的唯一存续副本:其中丢失或错误的数据无法从任何其他地方重建。请保持其私有——它包含项目名称、分支名称以及耗时信息,这些都不应出现在公共仓库中。

mkdir -p ~/.local/share/estimate-maestro
git -C ~/.local/share/estimate-maestro init

默认存储位置遵循 XDG Base Directory Specification,无需配置。仅当您希望将存储放在其他位置时才设置 ESTIMATE_MAESTRO_STORE——例如与其他个人仓库放在一起,这样更容易记得提交和推送。它必须对服务器和您的 shell 都可见,因此请将其放在两者都能读取的位置(通常是您的 shell 配置文件):

export ESTIMATE_MAESTRO_STORE=~/somewhere/else

将两个钩子脚本接入 ~/.claude/settings.json:将 hooks/session-end.sh 作为 SessionEnd 钩子(关闭被遗忘的计时器,并限制在配置的工作日内)以及将 hooks/session-start.sh 作为 SessionStart 钩子(报告计时器是否已在运行):

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          { "type": "command", "command": "~/mcp/estimate-maestro/hooks/session-start.sh" }
        ]
      }
    ],
    "SessionEnd": [
      {
        "hooks": [
          { "type": "command", "command": "~/mcp/estimate-maestro/hooks/session-end.sh" }
        ]
      }
    ]
  }
}

如果 ~/.claude/settings.json 中已有 hooks 块,请将其合并到现有块中,而不是覆盖它。

Development

uv sync --locked
uv run ruff format --check
uv run ruff check
uv run pyright
uv run pytest src/ -v

Available Tools

21 tools
add_sliceC

Add a slice. One added while the effort is active is scope growth.

Inputs: title (required), effort (required). Returns: recorded, identifier

annotate_intervalC

Attach meeting participants or a note to an interval after the fact.

Inputs: effort (required), interval (required), note, external, +2 more. Returns: recorded, identifier

clock_inC

Start an interval. Refused if one is already open.

Inputs: effort (required), kind, note, external, +3 more. Returns: recorded, identifier

clock_outC

Close the open interval.

Inputs: at, note. Returns: recorded, identifier

close_sliceC

Close a slice against its pull request.

Inputs: effort (required), work_slice (required), pull_request (required). Returns: recorded, identifier

currentB

What is clocked in, and since when.

Inputs: no named parameters. Returns: since, effort, interval, work_slice

drop_sliceC

Drop a slice that turned out to be unnecessary.

Inputs: effort (required), reason (required), work_slice (required). Returns: recorded, identifier

effort_detailC

One effort's full event history.

Inputs: effort (required). Returns: row, meta, slices, commits, +2 more

effort_tableC

One near-raw row per effort: estimates, wall hours, slice counts.

Inputs: no named parameters. Returns: result

finish_effortC

Mark an effort done.

Inputs: effort (required). Returns: recorded, identifier

harvest_commitsC

Copy commit metadata from a working tree into the store.

Inputs: path (required), since (required), until (required), effort (required), +1 more. Returns: recorded, identifier

record_absenceC

Declare time not spent working. Retroactive by design.

Inputs: kind (required), stop (required), start (required), note. Returns: recorded, identifier

record_final_planD

Record the final plan and the counterfactual estimate against it.

Inputs: effort (required), likely (required), plan_path (required), rationale (required), +3 more. Returns: recorded, identifier

record_landed_commitC

Record the durable commit that landed on the default branch.

Inputs: effort (required), identifier (required), repository (required), work_slice (required). Returns: recorded, identifier

record_revisionC

Record a revised estimate, typically when a slice is inserted.

Inputs: effort (required), likely (required), rationale (required), optimistic (required), +1 more. Returns: recorded, identifier

reference_effortsC

Prior efforts with their summaries and estimates, for comparison. No actuals.

Inputs: kind, limit. Returns: result

remap_commitsC

Map a rewritten commit id onto its replacement.

Inputs: new (required), old (required), effort (required), reason (required). Returns: recorded, identifier

rename_sliceD

Rename a slice.

Inputs: title (required), effort (required), work_slice (required). Returns: recorded, identifier

repair_intervalB

Correct an interval's bounds. Appends; never rewrites.

Inputs: effort (required), interval (required), stop, start. Returns: recorded, identifier

start_effortC

Create an effort from a plan artefact and an initial PERT estimate.

Inputs: kind (required), title (required), likely (required), plan_path (required), +5 more. Returns: recorded, identifier

summaryB

Aggregate calibration, or an honest refusal when there is too little data.

Inputs: no named parameters. Returns: note, efforts_counted, mean_hours_per_point, mean_inventory_growth, +2 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.8/5.0

    Scored across 21 tools

    Disambiguation5/5

    Every tool has a clearly distinct purpose. Even overlapping domains like commits (harvest, record, remap) and intervals (clock, annotate, repair) are separated by specific actions and targets. No two tools could be easily confused for the same operation.

    Naming Consistency4/5

    The majority of tools follow a consistent verb_noun pattern (e.g., repair_interval, start_effort, add_slice). A few query tools are named as nouns (current, summary, effort_table, effort_detail), which is a minor deviation but still readable and sensible for retrieval operations.

    Tool Count4/5

    With 21 tools, the surface is substantial but justified by the domain's complexity—covering efforts, intervals, slices, commits, estimates, and queries. Each tool adds distinct functionality, though the count is on the higher end and could feel heavy for simpler use cases.

    Completeness5/5

    The toolset provides comprehensive lifecycle coverage: starting and finishing efforts, managing slices (add/close/drop/rename), tracking time (clock in/out, absence), revising estimates, recording commits, and rich reporting (current, table, detail, summary). No obvious gaps or dead ends are apparent.

    Related MCP Connectors

    Related MCP Servers