Epoch

Epoch -- 时间估算 MCP 服务

Epoch 是一款时间估算 MCP 服务，可帮助需要校准工期估算的工程负责人、Agent 和规划人员生成 PERT／参考类别估算并记录实际数据。

简而言之： Epoch — 时间估算 MCP 服务。最适合需要校准工期估算的工程负责人、Agent 和规划人员。

Epoch 帮助 AI Agent 理解时间。

AI 能编写代码、分析数据和构建应用——但它无法判断一件事需要多长时间、要花多少钱，或截止日期是否现实。Epoch 能解决这个问题。

---

看看效果

You: "How long will a 15,000 line project take with a small team?"

Claude (using Epoch):
  COCOMO II nominal: 100 person-months (traditional team)
  AI-adjusted: 9 person-months (LLM-assisted workflow)
  Schedule risk: medium (MAPE 15%, based on 28 historical features)
  Cost estimate (Claude Sonnet): ~$340 in API tokens

You: "How many working days between now and launch?"

Claude (using Epoch):
  Start: May 1, 2026
  End: July 15, 2026
  Business days: 54
  Weekend days: 16
  Holidays: 1 (Independence Day)
  Total calendar days: 75

You: "Which AI model should we use for a 50k-token job?"

Claude (using Epoch):
  gemini-2.0-flash:  $0.02 -- fast, budget-friendly
  gpt-4o-mini:       $0.02 -- fast, budget-friendly
  gemini-2.5-pro:    $0.37 -- standard, high quality
  claude-sonnet-5:    $0.57 -- standard, high quality
  Recommendation: gemini-2.0-flash for cost, claude-sonnet-5 for quality

为什么选择 Epoch？

每个 AI Agent 都会幻觉出项目时间表。“这应该需要大约 2 小时”最后却变成了 2 天。Epoch 为 AI 提供有依据、数据驱动的估算，而不是猜测。它将成熟的估算方法（PERT、COCOMO II、蒙特卡洛、参考类别预测）封装为 26 个可供任意 AI 调用的工具——让你的助手不再猜测，而是开始计算。

开箱即用。 Epoch 自带参考数据库，其中包含任务类型校正系数、基于维护者记录的估算与实际数据以及精选公开研究得出的范围基线，以及工具使用量／延迟遥测样本（捆绑的 canary 测试和会话基准共 117,791 个样本），让令牌与时间的换算依据充分。你从第一天起就能获得合理的估算——无需收集数据或设置账户。如果你选择记录实际数据，Epoch 的自我改进引擎会学习你的模式，随着时间推移提供更精准的估算。

什么是 MCP？

MCP（模型上下文协议）是 Claude 等 AI 助手连接外部工具的方式。你可以把它看作插件系统——只需一条命令添加 Epoch，你的 AI 助手就能估算时间表、计算工作日、比较模型成本，并预测项目能否按时完成。

快速开始

30 秒即可完成设置——适用于 Claude Code、Cursor、VS Code 和 Windsurf：

claude mcp add epoch -- npx @kyanitelabs/epoch

就这样。你的 AI 助手现在拥有 26 个时间估算工具。

你也可以将它添加到项目的 .mcp.json 中：

{
  "mcpServers": {
    "epoch": {
      "command": "npx",
      "args": ["@kyanitelabs/epoch"]
    }
  }
}

Agent 技能

Epoch 还提供公开的 Agent 技能，位于 skills/epoch/SKILL.md。在兼容的 Agent 宿主中使用 $epoch，即可让 Agent 为时间估算、工作日计算、模型成本比较、进度风险和估算与实际数据反馈选择合适的 Epoch MCP 或 CLI 工作流。

Epoch 能做什么？

你想知道什么	Epoch 会做什么	通俗说法
“这要花多长时间？”	提供包含最乐观和最悲观情况的现实估算范围	时间估算
“我们能赶上这个截止日期吗？”	告诉你当前时间安排是否现实或有风险	进度风险
“AI 调用要花多少钱？”	并排计算 16 种 AI 模型的令牌成本	成本对比
“从现在到发布还有多少个工作日？”	计算排除周末和节假日后的天数（5 个国家）	日历计算
“我们的估算越来越准确了吗？”	追踪一段时间内的准确度并自动修正	自我改进
“我们应该使用哪个模型？”	对比所有主流 AI 模型的速度、成本和质量	模型对比

---

技术参考

以下内容面向希望了解内部实现、使用 CLI 或 REST API，或为 Epoch 做出贡献的开发者。

架构

六层设计，包含 26 个用于时间估算、进度安排、成本分析和反馈的工具：

层	用途	工具
1. 核心时间	时间、时区、时长、日期计算	get_current_time, convert_timezone, parse_duration, time_math
2. 日历计算	工作日、节假日（US/UK/FR/DE/JP）	add_business_days, count_business_days
3. 估算	PERT、COCOMO II、冲刺、CPM、蒙特卡洛	pert_estimate, cocomo_estimate, sprint_forecast, critical_path, monte_carlo_schedule
4. 分析	参考类别、上下文分类、校准、令牌-时间转换、等待机制截止时间	reference_class_estimate, estimate_from_context, calibrate_estimates, token_time_bridge, wait_bound
5. 成本与风险	令牌成本、模型对比、准确度趋势、风险、COCOMO 验证	token_cost_estimate, compare_models, accuracy_trend, schedule_risk, cocomo_validate, cocomo_ground_truth
6. 反馈	记录实际值、追踪待处理估算、批量操作、健康检查	record_actual, get_pending_estimates, batch_record_actuals, feedback_health

工具参考

第 1 层 -- 核心时间

get_current_time -- 获取任意 IANA 时区的当前挂钟时间

Input:  { timezone: "America/New_York" }
Output: {
  iso: "2026-05-01T08:30:00.000-04:00",
  humanReadable: "Fri, May 1, 2026, 8:30 AM EDT",
  timezone: "America/New_York",
  utcOffset: "-04:00"
}

convert_timezone -- 在 IANA 时区之间转换时间戳

Input:  { timestamp: "2026-05-01T12:00:00Z", target_tz: "Asia/Tokyo" }
Output: {
  iso: "2026-05-01T21:00:00.000+09:00",
  timezone: "Asia/Tokyo",
  utcOffset: "+09:00",
  humanReadable: "Fri, May 1, 2026, 9:00 PM JST"
}

parse_duration -- 解析人类可读的时长字符串

Input:  { duration_string: "2h30m" }
Output: {
  input: "2h30m",
  totalSeconds: 9000,
  humanReadable: "2 hours 30 minutes"
}

time_math -- 日期算术运算

Input:  { operation: "add_days", operands: { start_date: "2026-05-01", days: 7 } }
Output: "2026-05-08"

支持的操作：add_days、add_business_days、diff、convert_tz、parse_nl、format_duration

第 2 层 -- 日历计算

add_business_days -- 添加 N 个工作日，并考虑节假日（US、UK、FR、DE、JP）

Input:  { start_date: "2026-05-01", days: 5, country: "US" }
Output: {
  startDate: "2026-05-01",
  endDate: "2026-05-08",
  businessDays: 5,
  countryCode: "US",
  holidaySupport: "holiday_calendar",
  humanReadable: "5 business days from 2026-05-01 to 2026-05-08 (US)."
}

count_business_days -- 计算两个日期之间的工作日数量

Input:  { start_date: "2026-05-01", end_date: "2026-05-15", country: "US" }
Output: {
  startDate: "2026-05-01",
  endDate: "2026-05-15",
  businessDays: 10,
  countryCode: "US",
  holidaySupport: "holiday_calendar",
  humanReadable: "10 business days between 2026-05-01 and 2026-05-15 (US)."
}

这两个工具在成功输出中始终包含 holidaySupport（如果该国家/地区有内置节假日集合——US/UK/FR/DE/JP——则为 "holiday_calendar"；否则为 "weekends_only"）；country 必须匹配 ^[A-Za-z]{2}$，不接受 "USA" 这类代码，并会返回易于理解的错误。

第 3 层 —— 估算

pert_estimate —— 使用置信区间和紧迫度评分进行 PERT 三点估算

Input:  {
  optimistic: 2,
  most_likely: 4,
  pessimistic: 12,
  unit: "hours"
}
Output: {
  expected: 5,
  variance: 2.78,
  stdDeviation: 1.67,
  confidence95: [1.67, 8.33],
  confidence99: [0, 10],
  unit: "hours",
  urgencyCategory: "medium",
  riskLevel: "high",
  humanReadable: "Expected 2.86–7.14 hours (80% confidence interval); point estimate 5 hours (ledger-recorded basis; adjustedEstimate 5 applies the correction factor). No task_type was supplied, so this interval is derived from the PERT variance (optimistic/most_likely/pessimistic spread) instead of empirical data.",
  developerProfile: { mode: "ai_native", correctionFactor: 1 },
  adjustedEstimate: 5,
  rawEstimate: 5,
  correctionFactor: 1,
  n: 0,
  interval: { p50: { lower: 3.87, upper: 6.13 }, p80: { lower: 2.86, upper: 7.14 }, p90: { lower: 2.25, upper: 7.75 }, source: "pert_variance" },
  intervalNote: "No task_type was supplied, so this interval is derived from the PERT variance (optimistic/most_likely/pessimistic spread) instead of empirical data.",
  basisNote: "Interval and point estimate are on the ledger-recorded basis (raw PERT expected × unit factor). adjustedEstimate (5 hours) additionally applies the correction factor (1) and is display-only — it is never recorded or calibrated against."
}

（这是全新安装且尚无累积反馈时的示例；对于该任务类型，如果有 ≥5 个经过排除项筛选的匹配样本对，interval.source 将变为 "empirical_ratio_quantile"，n 会报告样本量，intervalPopulation 会指出所用的比率总体。）

cocomo_estimate —— 使用经 LLM 调整的成本驱动因素进行 COCOMO II 软件规模估算

Input:  {
  kloc: 15,
  reasoning_complexity: 1.2,
  context_completeness: 1.0,
  transformation_impact: 0.8,
  iterative_cycles: 1.5,
  human_oversight: 1.2
}
Output: {
  kloc: 15,
  personMonthsNominal: 99.9,
  personMonthsLlmAdjusted: 8.9,
  effortMultipliers: {
    reasoning_complexity: 1.2,
    context_completeness: 1.0,
    transformation_impact: 0.8,
    iterative_cycles: 1.5,
    human_oversight: 1.2,
    product: 1.728
  },
  developerProfile: { mode: "ai_native", correctionFactor: 1.45 }
}

经 LLM 调整的成本驱动因素包括推理复杂度、上下文完整性、转换影响、迭代周期和人工监督要求。

sprint_forecast —— 根据历史数据预测 Sprint 速度

Input:  {
  backlog_points: 100,
  velocity_history: [20, 25, 22, 23],
  sprint_length_days: 14,
  hours_per_sprint: 80
}
Output: {
  backlogPoints: 100,
  averageVelocity: 22.5,
  requiredSprints: 4.4,
  pessimisticSprints: 4.9,
  hoursPerPoint: 3.56,
  totalHours: 355.6,
  completionDays: 62,
  sprintLengthDays: 14,
  developerProfile: { mode: "ai_native", sprintVelocityPoints: 80, correctionFactor: 1.45 }
}

critical_path —— 对并行任务进行合并偏差调整的关键路径法

Input:  {
  tasks: [
    { name: "A", duration: 5, predecessors: [] },
    { name: "B", duration: 3, predecessors: ["A"] },
    { name: "C", duration: 4, predecessors: ["A"] }
  ]
}
Output: {
  critical_path: ["A", "C"],
  total_duration: 9,
  slack_per_task: { A: 0, B: 1, C: 0 },
  merge_bias_adjustment: 0
}

monte_carlo_schedule —— 使用带种子的 PRNG 进行蒙特卡洛模拟，确保结果确定且可复现

Input:  {
  tasks: [
    { name: "A", optimistic: 2, most_likely: 4, pessimistic: 8 },
    { name: "B", optimistic: 1, most_likely: 3, pessimistic: 6 }
  ],
  iterations: 10000
}
Output: {
  p10: "5.9",
  p50: "7.91",
  p80: "9.39",
  p95: "10.75",
  riskEvents: [
    { description: "Task \"A\" exceeded 1.5x PERT expected in 10% of simulations", probability: 0.1, impactDays: 0.05 },
    { description: "Task \"B\" exceeded 1.5x PERT expected in 10% of simulations", probability: 0.1, impactDays: 0.04 }
  ],
  criticalPathProbability: null
}

（除非提供 target_hours 截止时间，否则 criticalPathProbability 为 null；提供后，它表示实际的 P(total ≤ target)；riskEvents[].impactDays 是每项任务的预期超期天数，按影响排序。）

第 4 层 —— 分析

reference_class_estimate —— 使用参考类别预测并修正计划谬误

Input:  {
  task_type: "feature",
  complexity: 3
}
Output: {
  rawEstimate: 2,
  correctedEstimate: 2,
  correctionFactor: 1,
  sampleSize: 0,
  baselineSource: "inferred_scope_medium_real_tasks",
  scopeUsed: "medium",
  scopeInferred: true,
  confidence: "pessimistic",
  developerProfile: { mode: "ai_native", estimationMape: 15, underestimationBias: 0.2, correctionFactor: 1 },
  adjustedEstimate: 2,
  basisNote: "correctedEstimate (2 hours) is the ledger-recorded and displayed basis (rawEstimate × correctionFactor). adjustedEstimate (2 hours) additionally applies the developerProfile factor (1) and is display-only — it is never recorded or calibrated against.",
  intervalNote: "Fewer than 5 exclusion-filtered historical \"feature\" reference_class_estimate pairs are available yet, so no empirical confidence interval could be computed."
}

（全新安装时的输出；累积反馈后，修正系数和样本量将根据你自己的匹配样本对计算，并填入经验区间；correctedEstimate 始终是记录的依据。）

有效的 task_type 值：feature、bugfix、refactor、migration、infrastructure、documentation、testing、design。

estimate_from_context —— 对自由文本任务描述进行分类，并委托参考类别估算

Input:  {
  context: "Add OAuth2 login support to the API, including refresh token rotation and a new /auth/callback endpoint"
}
Output: {
  tool: "estimate_from_context",
  rawEstimate: 2,
  correctedEstimate: 2,
  correctionFactor: 1,
  sampleSize: 0,
  baselineSource: "inferred_scope_medium_real_tasks",
  scopeUsed: "medium",
  scopeGuide: "For feature tasks: small=~2.3h, medium=~6h, large=~10.6h, xl=~17h",
  classification: {
    classified_task_type: "feature",
    classified_complexity: 3,
    confidence: "medium",
    signals: ["task_type_matched:feature"],
    task_type_from_hint: false,
    complexity_from_hint: false
  },
  note: "Using reference database correction factors. Submit actuals via record_actual to improve accuracy."
}

使用本地、确定性的关键词/信号启发式方法，根据自由文本（问题正文、PR/差异描述或任务摘要）对 task_type 和 complexity 进行分类，不会调用 LLM。调用方提供的 task_type/complexity 提示始终优先于分类结果。随后，解析出的输入会委托给 reference_class_estimate 使用的同一参考类别预测流程，因此响应包含相同的估算字段，以及一个说明工具如何解读上下文的 classification 来源信息块。当分类置信度较低时，会返回额外的 lowConfidenceNote 字段，而不是默默猜测。

calibrate_estimates —— 根据历史估算值与实际值，为团队校准准确度

Input:  {
  task_type: "feature",
  team_id: "backend"
}
Output: {
  correctionFactor: 1.45,
  accuracyTrend: "stable",
  velocityTrend: "stable",
  recommendations: [
    "Using reference database correction factor (1.45x) — 8 matched samples, need 5.",
    "Record actuals via POST /v1/feedback/record-actual to refine for your team's patterns."
  ]
}

token_time_bridge —— 将 LLM token 预算映射为实际耗时，支持 16 个模型系列

Input:  {
  tokens: 50000,
  model: "claude-sonnet-4-20250514",
  tool_calls: 10,
  reasoning_depth: "deep"
}
Output: {
  estimatedSeconds: 697,
  estimatedMinutes: 11.6,
  confidence: "likely",
  urgency: "short",
  breakdown: {
    promptTokens: 15000,
    completionTokens: 35000,
    toolOverheadSeconds: 2
  }
}

第 5 层 —— 成本与风险

token_cost_estimate —— 估算 LLM API 调用的 token 成本

Input:  {
  tokens: 50000,
  model: "claude-sonnet-5"
}
Output: {
  tokens: 50000,
  model: "claude-sonnet-5",
  estimatedSeconds: 695,
  estimatedMinutes: 11.6,
  estimatedCost: 0.57,
  costBreakdown: { inputCost: 0.045, outputCost: 0.525, toolCallOverheadCost: 0 },
  confidence: "likely"
}

compare_models —— 并排比较不同 LLM 模型的成本与能力

Input:  {
  tokens: 50000,
  sort_by: "cost"
}
Output: {
  tokens: 50000,
  models: [
    { model: "gemini-2.0-flash", estimatedCost: 0.0155, qualityTier: "fast", tokensPerSecond: 230 },
    { model: "deepseek-v3", estimatedCost: 0.0189, qualityTier: "standard", tokensPerSecond: 97 },
    { model: "gpt-4o-mini", estimatedCost: 0.0233, qualityTier: "fast", tokensPerSecond: 180 }
  ],
  sortBy: "cost"
}

accuracy_trend —— 根据记录的反馈数据追踪估算准确度随时间的变化

Input:  { team_id: "backend", window_size: 50 }
Output: {
  overallTrend: "improving",
  currentMape: 26.5,
  industryBaselineMape: 25,
  totalEstimates: 1049,
  totalWithActuals: 1049,
  windows: [{ period: "Window 1 (estimates 1-50)", mape: 32, bias: 5.3, sampleSize: 50 }]
}

schedule_risk —— 为项目时间线评估进度风险

Input:  {
  estimated_hours: 40,
  task_type: "feature"
}
Output: {
  estimatedHours: 40,
  riskLevel: "low",
  confidenceIntervals: { p50: 40, p80: 45.1, p95: 49.9 },
  historicalAccuracy: { mape: 15, sampleSize: 42 },
  recommendation: "Low risk. Estimate is within normal variance.",
  humanReadable: "Schedule risk: low. MAPE: 15% (based on 42 historical records). Confidence intervals: p50=40h, p80=45.1h, p95=49.9h."
}

cocomo_validate —— 根据参考数据验证 COCOMO II 估算

Input:  {}
Output: {
  projectsEvaluated: 182,
  mape: 85.55,
  bias: 53.5,
  byProjectType: {
    organic: { mape: 86.57, count: 22 },
    semidetached: { mape: 84.75, count: 106 },
    embedded: { mape: 86.71, count: 54 }
  },
  recommendedAdjustments: []
}

cocomo_ground_truth —— 使用相同的真实历史项目，对所有 COCOMO 变体（Basic、COCOMO II nominal、AI 12x speedup、AI + developer-profile gradients）进行基准测试，并按数据集和类型分别汇总

Input:  {}
Output: {
  projectsEvaluated: 182,
  models: [
    { name: "COCOMO Basic", mape: 85.55, mmre: 0.856, pred25: 0.313, pred50: 0.544, bias: 53.5, count: 182 },
    ...
  ],
  byDataset: { ... },
  byType: { ... },
  winner: "AI + Profile (human)",
  conclusion: "Best model: AI + Profile (human) (MAPE=79.66%). ...",
  humanReadable: "..."
}

ai_native 模式

Epoch 工具支持两种估算模式，以适应 AI 辅助开发与纯人工开发在速度上的根本差异。

当 ai_native=true（默认值）时，工具会使用 Epoch 的参考数据库，并应用感知工具的校正因子。这些基准反映了 AI Agent 工作流的特点：迭代更快、产出量更高，错误特征也有所不同。

当 ai_native=false 时，工具会采用人工开发者基准：

参数	人工基准	AI 原生基准
功能开发	14 个日历日（行业数据）	中位数 5.7 小时（超过 126K 项真实任务）
Bug 修复周转时间	72 小时（行业数据）	中位数 6.2 小时（139 组匹配的估算值与实际值；来源：src/lib/supplementary-data.ts）
Sprint 速度	35 个故事点（行业数据）	80 个故事点
估算准确度（MAPE）	25%（Jorgensen 2004）	15%（来自 AI 原生配置）
校正因子	1.8x（行业标准）	1.07-1.45x（来自参考数据库）

支持 ai_native 的工具：pert_estimate、cocomo_estimate、sprint_forecast、reference_class_estimate、schedule_risk。

混合工作流： ai_native 接受 0.0（完全人工）到 1.0（完全 AI 原生）之间的浮点数。像 0.5 这样的值会生成插值配置，适用于 AI 与人工混合的工作流。布尔值（true/false）仍受支持，以保持向后兼容。

自我改进引擎

使用 Epoch 越多，它就越能了解你的模式。内置参考数据库结合了少量维护者的估算与实际结果配对数据（用于生成校正因子的种子数据）、经过整理的公开研究基线，以及 117,791 条工具使用／延迟遥测样本（canary 测试和会话基准——这些数据用于支撑延迟和令牌耗时数据，而非估算准确度）。它能让你从第一天起就有一个合理的起点——而随着你记录实际结果，它会变得更加精准。

记录实际结果后，Epoch 还能进一步个性化：

1. 估算 -- 使用任意估算工具生成初始估算
2. 记录 -- 跟踪实际结果（record_actual）
3. 学习 -- 自我改进功能根据你的数据计算个性化校正因子
4. 改进 -- 后续估算会采用你团队的实际模式
5. 趋势 -- accuracy_trend 跟踪你的准确度是否随时间提升

Your estimates + your actuals -> Your correction factors -> Better estimates -> Repeat

这个循环可以自动闭合。 记录实际结果是大家最容易忘记的一步，因此 Epoch 可以代劳：epoch auto-actuals --session <id> 会记录该会话中未完成估算的实际耗时（Agent 主机可将其接入会话结束钩子）。自动记录的实际耗时会限制在合理范围内（0.05–12 小时，且小于估算值的 10 倍），来源标记为 auto_wallclock，不会覆盖真实实际结果；feedback_health 会单独报告这些数据（byProvenance），避免自动化数据悄然扭曲校准结果。

如果估算记录器无法写入 inputs.session_id，请明确传入会话的实际时间范围：epoch auto-actuals --session <id> --window-start <ts> --window-end <ts>。每个 <ts> 可以是纪元毫秒数或 ISO 时间戳，并且必须同时提供两个标志，且结束时间不得早于开始时间。只有当持久化账本中不存在会话 ID 完全匹配的估算（包括已完成或已过期的估算）时，Epoch 才会使用此时间范围；并且只会选择未标记会话的待处理估算。标记为其他会话的估算绝不会被选中。通过时间范围选出的候选项仍须通过与会话 ID 精确匹配相同的合理性和重复项检查。

你的 git 历史也是实际结果的来源。 epoch mine-git --repo <path> --since <date> 会遍历本地 git 仓库——其设计本身即为离线且只读——并通过规划流程已写入的身份键（task_label、branch 或 issue_ref），将待处理估算与已关闭的工作（已合并 PR 和普通合并）关联起来。每个单元会推导并分别报告两个周期时长窗口，绝不混合：首次提交→合并（来源标记为 git_derived）以及开启→合并（来源标记为 git_derived_review_inclusive，仅在本地仍保留分支创建锚点时计算——普通克隆中不存在该锚点，且绝不会伪造此窗口）。使用 --window dev|review-inclusive 选择记录哪个窗口；另一个窗口会随附在实际结果的备注中。挖掘出的实际耗时会限制在合理范围内（[0.05 小时，720 小时]——日历时间窗口跨越夜晚和周末是合理的，且小于估算值的 10 倍），不会覆盖真实实际结果；feedback_health 会在自己的 byProvenance 分类（gitDerived）中单独统计这些数据，避免日历时间窗口中的噪声悄然扭曲校准结果。

估算会优先给出诚实的范围。 对于至少有 5 组匹配数据的任务类型，pert_estimate 和 reference_class_estimate 会以校准后的 80% 区间开头（“预计 1.6–4.2 小时（80% 置信区间）；点估算为 2.5 小时”）。该区间根据你自己的历史估算与实际结果比率得出；如果数据还不足，也会明确说明。

引擎会检测系统性偏差（长期低估、准确度下降），并提供可执行的建议。

你不必与任何人共享数据，也能使用这项功能。 自我改进完全在本地运行，使用你自己的 ~/.epoch/ 数据。

经过测量的校正循环

上述自我改进的说法并非营销文案，而是有可运行的验证结果作为依据。scripts/backtest-pert-correction.mjs 会对你的 ~/.epoch 账本创建只读临时副本，按时间顺序将匹配的 pert_estimate（估算值、实际值）对拆分为 80/20，仅使用训练集训练按（工具、task_type）学习的校正因子，并报告从未用于训练的留出测试集上的 MdAPE：

npx tsx scripts/backtest-pert-correction.mjs

在维护者的生产账本上测得的结果（撰写本文时有 697 个留出的匹配对）：在校正因子训练时从未见过的数据上，MdAPE 从 105.2%（未校正）改善至 80.5%（学习校正）。这正是 EPOCH_PERT_LEARNED_CORRECTION 在默认启用建议前用于把关的机制——该脚本还会检查校正后的实际值/预测值中位数比是否落在 [0.7, 1.3]，如果第二项保护条件尚未达标，则报告 HOLD（暂不建议启用），因此只有两项条件都满足后，该标志才会以“启用”状态发布。运行脚本并使用你自己的账本查看结果；随着记录更多实际值，数据会不断变化，这正是目的所在。

reference_class_estimate 的校正因子使用的是同一种学习机制，只是应用于不同的工具。可通过 epoch data status 或 feedback_health（按工具统计的 MAPE/MdAPE、偏差和趋势）跟踪当前校准情况，也可以通过 node scripts/build-calibration-dashboard.mjs 生成完整的校准决策面报告——同样只会读取你的账本。

数据流水线

Epoch 采用三层数据策略，确保从一开始就准确，并随时间不断改进：

1. 内置参考数据库（开箱即用，无需设置）： Epoch 自带预构建的参考数据库：根据维护者自身的估算值与实际值历史记录生成的校正因子、基于精选公开研究的范围基线，以及 117,791 条工具使用/延迟遥测样本（涵盖 8 种任务类型和 5 个复杂度等级的金丝雀测试与会话基准测试）。Epoch 在展示数据量时，会将遥测样本数量与匹配的估算值-实际值对数量分开报告。

2. 本地自我改进（自动、私密）： 使用 Epoch 并记录实际值后，自我改进引擎会根据你的数据重新校准校正因子。整个过程都在本地 ~/.epoch/ 中运行——不会有任何数据离开你的机器。引擎每 100 次工具调用或每 24 小时自动触发一次。

• **自动记录：**使用 scripts/auto-record-actual.mjs 自动记录待处理估算的实际用时。
• **来源标记：**设置 EPOCH_SOURCE=<project-name>，按项目标记估算记录。
• 检查你的数据：epoch data where 和 epoch data status 会显示本地存储的数据。

3. 社区贡献（可选，主动选择加入）： 你可以选择分享匿名数据，帮助改进所有用户的基线数据。社区数据会移除所有身份识别信息——仅保留任务类型、复杂度、估算小时数、实际小时数和日期。格式和隐私要求请参阅 CONTRIBUTING-data.md。

epoch share-data --validate --description "My anonymized estimation data"

完全可以不参与。即使没有社区贡献，Epoch 也能很好地运行。

使用界面

Epoch 通过三个界面提供相同的 26 个工具：

界面	传输方式	使用场景
MCP 服务	stdio	Claude Code、Cursor、VS Code、Windsurf
CLI	直接调用	脚本、CI/CD、快速查询
REST API	HTTP (Hono)	Web 应用、AI Agent、集成

默认行为：不带参数运行 epoch 会启动 MCP stdio 服务。

CLI

# PERT estimate
epoch pert-estimate --optimistic 2 --most-likely 4 --pessimistic 12 --unit hours

# Token-to-time bridge
epoch token-time-bridge --tokens 50000 --model claude-sonnet-4-20250514

# Monte Carlo simulation
epoch monte-carlo-schedule --tasks '[{"name":"A","optimistic":2,"most_likely":4,"pessimistic":8}]'

# COCOMO II estimate
epoch cocomo-estimate --kloc 15

# Schedule risk score
epoch schedule-risk --estimated-hours 40

# List all tools
epoch list-tools

# Pretty table output
epoch pert-estimate --optimistic 2 --most-likely 4 --pessimistic 12 --pretty

从源代码检出目录开始，执行 pnpm install 和 pnpm run build 后，对应的 CLI 命令为 dist/index.js。CI 会在每次变更时运行此代码块，并要求输出中包含每个 # expect: 行，因此这些示例不会与代码脱节：

node dist/index.js --version
node dist/index.js parse-duration --duration 2h30m
# expect: "totalSeconds": 9000
node dist/index.js count-business-days --start-date 2026-05-01 --end-date 2026-05-15 --country US
# expect: "businessDays": 10
node dist/index.js add-business-days --start-date 2026-05-01 --days 5 --country US
# expect: "endDate": "2026-05-08"
node dist/index.js time-math --operation add_days --date 2026-05-01 --days 7
# expect: "data": "2026-05-08"

REST API

# Start the server
epoch serve --port 3099
# or: EPOCH_TRANSPORT=http EPOCH_PORT=3099 epoch

# Call any tool
curl -X POST http://localhost:3099/v1/tools/pert_estimate \
  -H "Content-Type: application/json" \
  -d '{"optimistic": 2, "most_likely": 4, "pessimistic": 12, "unit": "hours"}'

# Health check
curl http://localhost:3099/health

# OpenAPI spec
curl http://localhost:3099/openapi.json

反馈 REST 路由

/v1/feedback/* 是一个稳定的 REST API，用于闭合估算值与实际值之间的反馈闭环。它不是反馈工具的别名：请求验证、响应格式和状态码都与通过 POST /v1/tools/<name>（或 MCP 或 CLI）调用相同工具时不同。请根据你调用的接口编写代码。

路由	REST 契约	通过 /v1/tools/<name> 调用的工具
POST /v1/feedback/record-actual	{estimate_id, actual_hours, notes?}。成功时返回 {estimateId, actualHours, recorded, flagged?, flagHint?}（驼峰命名）。状态码：输入无效或调用方可修正的拒绝情况（below_threshold、synthetic_id、unknown_tool、自动检查或 git 合理性检查未通过）返回 400；重复记录返回 409；存储失败返回 500。	record_actual：成功时返回 {recorded, estimate_id, actual_hours, message, flagged?, flagHint?}（蛇形命名）。所有失败都返回 422，且消息会指出原因。
GET /v1/feedback/pending?limit=	limit 默认值为 50，范围限制为 1–200，非数字值将回退为 50。返回上限内的所有待处理估算记录，且包含完整记录。	get_pending_estimates：limit 默认值为 20，最大值为 100。返回 {count, summary, estimates}，其中 count 统计整个限制范围内的记录数，而 estimates 最多包含 10 条最新记录。
POST /v1/feedback/batch-record-actuals	1–500 条记录。**部分成功：**有效记录会被保存，每条无效记录都会按索引列入 errors。如果没有任何记录成功，存储原因之外的情况返回 422，存储原因则返回 500。	batch_record_actuals：Zod 会先验证每条记录，因此只要有一条记录无效，就会拒绝整个批次（422），且不会保存任何记录。
GET /v1/feedback/health	反馈健康报告。	feedback_health：返回相同报告，另外还包含 intervalCoverage（P80 预测区间校准）。

Agent 优先

Epoch 专为 Agent 打造，将其视为一等调用方，而不是事后才考虑让人类在终端中输入命令。

为什么 Agent 需要时间感知能力。 大模型无法切实感知时长或成本——对于为期两天的迁移，它会说“快速修复”；对于耗时两小时的配置更改，它又会说“大型项目”，而且两者都同样自信，因为没有反馈循环告诉它实际情况。对于聊天回答，这没什么问题；但当 Agent 开始规划多步骤工作、安排冲刺，或判断截止日期是否现实，一切就会出问题。Epoch 为 Agent 提供计算器，而不是猜测：PERT/COCOMO/Monte Carlo 数学模型、基于真实任务数据构建的参考类别基线，以及随着 Agent（或其操作者）记录实际数据而自我校正的反馈循环。

面向无头部署 / Agent 操作者的 EPOCH_TELEMETRY=1。 遥测默认关闭，且必须获得知情同意。对于在终端前的人类，这意味着运行 epoch telemetry enable，查看数据并确认。Agent 绝不能代表自己点击提示中的“是”——我们特意不提供用于启用遥测的 MCP 工具，因此 Agent 无法自行同意。对于无头部署或由 Agent 操作的部署，操作者须在 Agent 启动前，通过带外方式在服务环境中设置 EPOCH_TELEMETRY=1 来选择启用（例如，在 MCP 服务配置的 env 块中设置）。同意权始终属于配置部署的人类，而非在其中运行的 Agent。

MCP 客户端资格判定。 Epoch 的遥测架构（v2）会记录 MCP clientInfo 中的 client_name / client_version（由主机在连接时报告），以及 transport（stdio / http）。这是对 Agent 的资格判定，而非身份识别：它能让聚合准确率统计将“跨 N 次 Agent 驱动的功能估算，中位数为 5.7h”作为一等 Agent 数据统计，而不是与匿名 CLI 用量混在一起，同时不增加任何新的按用户识别信号。报告 clientInfo 的 MCP 客户端（Claude Code、Cursor 和大多数当前主机都支持）可免费获得此功能；不报告 clientInfo 的客户端仍可完整使用，只会显示为 client_name: null。

Epoch 还提供内置发现端点，让 Agent 无需预先配置即可查找并使用 HTTP API：

端点	描述
GET /.well-known/ai-plugin.json	OpenAI 插件清单
GET /llms.txt	可供大模型读取的文档
GET /openapi.json	OpenAPI 3.1 规范
GET /health	服务健康状态与版本

安装

git clone https://github.com/KyaniteLabs/Epoch.git
cd Epoch
pnpm install
pnpm run build

开发

pnpm test          # Run the Vitest suite
pnpm run build     # Build with tsup
pnpm run typecheck # TypeScript strict mode check
pnpm run dev       # Run development server
pnpm run inspector # Open MCP Inspector for interactive testing

技术栈

• 运行时：Node.js 22+（ESM；engines.node >=22 — Node 20 于 2026 年 4 月结束生命周期）
• 语言：TypeScript 6（严格模式，noUncheckedIndexedAccess，verbatimModuleSyntax）
• 验证：Zod 4，每个字段均带有 .describe()
• MCP SDK：@modelcontextprotocol/sdk 1.12+
• HTTP：Hono（轻量级，支持多种运行时）
• CLI：Commander.js
• 日期处理：date-fns 4.x + date-fns-tz 3.x
• 构建：tsup（ESM 输出）
• 测试：vitest 4.x，使用 v8 覆盖率（97% 语句，88% 分支）

配置

变量	默认值	描述
EPOCH_TRANSPORT	stdio	传输模式：stdio 或 http
EPOCH_PORT	3000	HTTP 服务端口
EPOCH_HOST	127.0.0.1	HTTP 服务绑定地址
EPOCH_DATA_DIR	~/.epoch/	用于反馈和自我改进的数据目录
EPOCH_COMMUNITY_DIR	data/community/	社区数据目录
EPOCH_RATE_LIMIT	100	每个客户端每分钟的最大请求数（仅限 HTTP）。0 表示禁用限制；无效或负值会回退为 100 并发出警告。429 响应会携带 Retry-After 标头。
EPOCH_TRUST_PROXY	0	仅在可信反向代理后运行时设为 1：此时速率限制会依据 X-Forwarded-For/X-Real-IP 而非连接地址进行（这些标头可被客户端伪造，因此默认会忽略）。
EPOCH_CORS_ORIGINS	(none)	HTTP API 的 CORS 处理中允许的来源，以逗号分隔（例如 https://app.example.com,http://localhost:5173），或设为 * 以允许任何来源。默认情况下不发送任何 CORS 标头——同源工具、curl 和 MCP 客户端不受影响；跨源浏览器请求会失败。始终会响应预检 OPTIONS 请求。
EPOCH_SOURCE	(none)	附加到估算记录的项目/来源标签
EPOCH_TELEMETRY	0	设为 1 以启用匿名遥测。请参阅遥测与隐私。
EPOCH_TELEMETRY_ENDPOINT	(none)	覆盖已配置的遥测接收端点，用于状态查询/提交。

遥测与隐私

Epoch 可以共享匿名化的估算值/实际值配对数据，以提高所有用户的准确性。此功能默认关闭，需要明确选择加入。

**Agent 操作者同意模式：**我们刻意不提供用于启用遥测的 MCP 工具——Agent 不得代表他人自行同意。人工用户可通过交互式运行 epoch telemetry enable 选择加入。Agent/无头模式操作者可在 Agent 启动前，通过在服务的环境中设置 EPOCH_TELEMETRY=1 来选择加入（请参阅 Agent 优先）。无论采用哪种方式，同意权都属于配置部署的人员。

epoch telemetry enable     # Opt in (shows exactly what will be shared)
epoch telemetry preview    # Preview anonymized data before enabling
epoch telemetry status     # Show current settings
epoch telemetry set-endpoint --endpoint https://your-server.example.com/v1/telemetry
epoch telemetry submit     # Submit queued anonymized records to the configured endpoint
epoch telemetry disable    # Opt out
epoch telemetry export     # Export all local data as anonymized JSON

**共享内容：**任务类型、复杂度、工具名称、估算小时数、实际小时数、比例、日期（仅 YYYY-MM-DD）。

**绝不共享的内容：**项目名称、备注、团队 ID、IP 地址、包含具体时刻的时间戳、源代码、描述。

完整详情请参阅隐私政策和遥测文档。

数据存储位置

默认情况下，Epoch 会将本地数据存储在 ~/.epoch/ 或 EPOCH_DATA_DIR 下。你的本地使用数据不会自动提交到 GitHub，也不会自动提交到任何地方。

epoch data where     # Show local data file locations
epoch data status    # Show data file counts, feedback health, telemetry config

分享数据

使用 epoch share-data --validate 创建适用于 data/community/ 的社区数据 JSON 文件。创建 PR 前请先检查该文件。

epoch share-data --description "Anonymized Epoch usage export" --validate

机器标签

本仓库不会发布机群主机清单。docs/ops/machines.md 说明了内部用于跟踪机器的架构；实际主机名、地址和 SSH 用户由运行时通过环境变量提供（请参阅 scripts/ 和 docs/ops/epoch-fleet-audit.md）。windows-receiver 仅为历史标签。

许可证

Apache License 2.0。完整条款请参阅 LICENSE。有日期记录的许可证变更历史（包括 npm 0.2.x MIT 使用者）：LICENSING.md。

---

KyaniteLabs 旗下项目

了解更多 KyaniteLabs 项目。相关项目：

• kinocut — 为 AI Agent 提供带防护措施的视频编辑 MCP 服务（原名 mcp-video）
• DialectOS — 西班牙语方言本地化 MCP 服务和 CLI
• checkyourself — 面向 AI 构建代码的本地优先生产就绪检查工具

→ 更多信息请访问 kyanitelabs.tech

Epoch 是什么？

Epoch 是一款时间估算 MCP 服务，帮助需要校准工期估算的工程负责人、Agent 和规划人员 生成 PERT／参考类别估算并记录实际耗时。

产品	Epoch
类别	时间估算 MCP 服务
最适合	需要校准工期估算的工程负责人、Agent 和规划人员
不适合	日历或项目跟踪工具
源码	GitHub · Forgejo（私有，仅维护者可访问）
关键词	时间估算 MCP、PERT、参考类别预测

适用对象

• 主要适用于：需要校准工期估算的工程负责人、Agent 和规划人员
• 需要生成 PERT／参考类别估算并记录实际耗时时使用
• 如果需要的是日历或项目跟踪工具，请勿使用

常见问题

Epoch 是什么？

Epoch 是一款时间估算 MCP 服务。它帮助需要校准工期估算的工程负责人、Agent 和规划人员生成 PERT／参考类别估算并记录实际耗时。

谁应该使用 Epoch？

需要校准工期估算的工程负责人、Agent 和规划人员。

Epoch 有何不同？

与凭感觉估算工时不同，Epoch 会强制采用结构化估算，并根据实际耗时提供反馈。

Epoch 是生产级软件吗？

请以 README 中的状态说明和发行标签为成熟度的准确信息来源。用于生产环境前，请根据自身需求进行验证。

状态

• 截至 2026 年，默认分支仍在维护
• 固定依赖版本时，优先使用发行标签
• 请在 GitHub 上报告问题

面向 Agent 的信息

• 编码 Agent：请先阅读此 README，然后查看仓库文档／AGENTS.md（如果存在）
• 如果仓库提供机器可读的简介（llms.txt），请优先使用
• 适用时，仓库内会说明 MCP 或技能入口

贡献

欢迎通过 GitHub 提交问题和 PR。公开文档中请勿包含机密信息和机器本地路径。

许可证

请参阅此仓库中的 LICENSE（如果许可证仅适用于软件包，则请查看软件包元数据）。