git-fit 0.24.3 → 0.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c834f3b0e5e85120e6e29fe14cf32ebdfe6893f9a6e247baf574b69ffe5ecf79
-  data.tar.gz: 7cd64d82a9fa70fe3e614c7566b2262dbcde8d7c70ee0e65f9e6435ee0d1c234
+  metadata.gz: 0b5ac295fe113517b660831a4cdaf826ac0905781ccdc591174117e0ec91973b
+  data.tar.gz: ecafcdedbdb2469570e946bd2b885d2605d92bf43a65fed7668f0074709a9a09
 SHA512:
-  metadata.gz: 714b7fdaf63da4e029372996514590b53b1866d561ca45a22b41ed2bd3bc7d0eda524f96156b44b2794a460946c5e6ae20eb78ba01b9e143d60aaf6fbd8fb14e
-  data.tar.gz: 48a886f80f97ccd1c7d93c00490f061480f67d32e3254d9d15b4800ca18bdb0454cd998b7cb1891aabe796185ad2d950b6cfb22e3ba43338158de21559db1ae9
+  metadata.gz: a588657ec9decf802ec4b2dc68bce7eb9e3c149282fd67e10a8e80a07c69c22cb418aef44513ba62e4de59c153475ba37dbf66da596b330d88d64601ea89f5a1
+  data.tar.gz: 2f1cdbe55b0f3ddd59406bb3b01c8d43ea09d491ec9a47a3fb316356e35cf6834633a1aa0315e495f5f26e623b214052b6934bd025a3c620d6f869c50d707a1e

data/lib/git-fit.rb

@@ -93,6 +93,8 @@ require_relative 'git_fit/cli/install_cli'
 require_relative 'git_fit/cli/purge_cli'
 require_relative 'git_fit/cli/gh_cli'
 require_relative 'git_fit/mcp'
+require_relative 'git_fit/ability'
+require_relative 'git_fit/cli/ability'
 require_relative 'git_fit/cli/export'
 require_relative 'git_fit/cli/mcp'
 require_relative 'git_fit/cli/import_cli'

data/lib/git_fit/ability/computer.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+require 'date'
+require_relative 'snapshot'
+
+module GitFit
+  module Ability
+    # Derives two-layer athlete ability snapshots (fitness + per-sport) from the L3 DB.
+    # Design: wiki/Ability (workouts#49); contract: git-fit#95.
+    #
+    # Rules (all acceptance-tested):
+    # - causal: --as-of excludes activities after the cutoff date
+    # - dedup: same unique-totals semantics as Export::Calculator — grouped run_ids
+    #   are excluded and each dedup group counts once via per-field median
+    # - windowing: start_date_local wall-clock date (see Snapshot.date_of)
+    # - no invented metrics: volume/frequency/longest/trend + pace percentiles + Riegel
+    class Computer
+      RIEGEL_EXP = 1.06
+      MIN_PACE_SAMPLES = 5
+      DIRECT_MATCH_TOLERANCE = 0.02
+      MIN_VALID_DISTANCE_M = 500
+      MIN_VALID_TIME_S = 60
+      TARGET_SPORTS = %w[run ride].freeze
+      RUN_TARGETS = { '5k' => 5000.0, '10k' => 10_000.0, 'half' => 21_097.5, 'full' => 42_195.0 }.freeze
+      RIDE_TARGETS = { '20k' => 20_000.0, '40k' => 40_000.0, '100k' => 100_000.0 }.freeze
+
+      def initialize(db:, as_of: nil)
+        @db = db
+        @as_of = normalize_as_of(as_of)
+      end
+
+      def call
+        rows = load_rows
+        {
+          'schema_version' => 1,
+          'generated_at' => Time.now.utc.strftime('%Y-%m-%dT%H:%M:%SZ'),
+          'fitness' => { 'snapshots' => fitness_snapshots(rows) },
+          'sports' => sports_section(rows),
+        }
+      end
+
+      private
+
+      def normalize_as_of(as_of)
+        return nil if as_of.nil? || as_of.to_s.empty?
+
+        valid = as_of.to_s.match?(/\A\d{4}-\d{2}-\d{2}\z/)
+        unless valid
+          raise ArgumentError, "Ability: invalid --as-of '#{as_of}' (expected YYYY-MM-DD)\n" \
+                               '  Fix: git fit ability compute --as-of 2025-03-15'
+        end
+
+        as_of
+      end
+
+      def load_rows
+        rows = @db[:activities]
+               .order(:start_date_local)
+               .select(:run_id, :start_date_local, :sport_category, :distance, :moving_time)
+               .all
+        # Causal filter: undated rows cannot be proven to precede the cutoff — excluded.
+        rows = rows.select { |r| Snapshot.date_of(r) && Snapshot.date_of(r) <= @as_of } if @as_of
+        dedup_aware(rows)
+      end
+
+      # Mirrors Export::Calculator#dedup_aware_totals: grouped activities drop out of
+      # the unique set; each group contributes one representative with per-field medians.
+      def dedup_aware(rows)
+        return rows unless @db.table_exists?(:dedup_groups) && @db.table_exists?(:dedup_group_members)
+
+        grouped_ids = @db[:dedup_group_members].select_map(:run_id)
+        unique = rows.reject { |r| grouped_ids.include?(r[:run_id]) }
+        by_run_id = rows.each_with_object({}) { |r, h| h[r[:run_id]] = r }
+        @db[:dedup_groups].select_map(:group_id).each do |gid|
+          members = @db[:dedup_group_members].where(group_id: gid).select_map(:run_id)
+                                             .filter_map { |rid| by_run_id[rid] }
+          next if members.empty?
+
+          unique << representative(members)
+        end
+        unique.sort_by { |r| Snapshot.date_of(r).to_s }
+      end
+
+      def representative(members)
+        first = members.first
+        first.merge(
+          distance: median(members.map { |r| r[:distance] }),
+          moving_time: median(members.map { |r| r[:moving_time] }),
+        )
+      end
+
+      def median(values)
+        sorted = values.compact.sort
+        return nil if sorted.empty?
+
+        sorted[sorted.size / 2]
+      end
+
+      # --- fitness layer ---
+
+      def fitness_snapshots(rows)
+        base = {}
+        Snapshot::PERIOD_TYPES.each do |type|
+          buckets = bucketize(rows, type)
+          buckets.each { |key, period_rows| base[[type, key]] = fitness_fields(type, key, period_rows) }
+        end
+        out = []
+        Snapshot::PERIOD_TYPES.each do |type|
+          bucketize(rows, type).keys.sort.each do |key|
+            fields = base[[type, key]]
+            prev_key = Snapshot.previous_key(type, key)
+            prev = prev_key && base[[type, prev_key]]
+            out << fields.merge('trend_vs_prev' => prev ? trend_fields(fields, prev) : nil)
+          end
+        end
+        out
+      end
+
+      def bucketize(rows, type)
+        rows.each_with_object({}) do |row, buckets|
+          date = Snapshot.date_of(row)
+          # Windowless rows (NULL/unparseable start_date_local) join only 'all'.
+          next if type != 'all' && date.nil?
+
+          key = type == 'all' ? 'all' : Snapshot.period_key(type, date)
+          (buckets[key] ||= []) << row
+        end
+      end
+
+      def fitness_fields(type, key, period_rows)
+        distances = period_rows.map { |r| r[:distance] }.compact
+        dates = period_rows.filter_map { |r| Snapshot.date_of(r) }
+        start_d, end_d = Snapshot.period_bounds(type, key, period_rows)
+        total_weeks = start_d ? Snapshot.week_count(start_d, end_d) : 0
+        active_weeks = dates.map { |d| Snapshot.week_key_of_date(Date.parse(d)) }.uniq.size
+        {
+          'period_key' => key,
+          'period_type' => type,
+          'volume_km' => (distances.sum / 1000.0).round(1),
+          'volume_s' => period_rows.map { |r| r[:moving_time] }.compact.sum,
+          'frequency' => total_weeks.zero? ? nil : (active_weeks.to_f / total_weeks).round(2),
+          'longest_km' => distances.empty? ? nil : (distances.max / 1000.0).round(1),
+          'confidence' => Snapshot.confidence_for(period_rows.size),
+        }
+      end
+
+      def trend_fields(cur, prev)
+        {
+          'volume_pct' => pct_delta(cur['volume_km'], prev['volume_km']),
+          'frequency_pct' => pct_delta(cur['frequency'], prev['frequency']),
+        }
+      end
+
+      def pct_delta(cur, prev)
+        return nil if prev.nil? || cur.nil? || prev.zero?
+
+        (((cur - prev) / prev.abs) * 100).round(1)
+      end
+
+      # --- sports layer ---
+
+      def sports_section(rows)
+        total_km = rows.sum { |r| r[:distance] || 0 } / 1000.0
+        TARGET_SPORTS.each_with_object({}) do |sport, section|
+          sport_rows = rows.select { |r| r[:sport_category] == sport }
+          section[sport] = { 'snapshots' => sport_snapshots(sport, sport_rows, total_km) }
+        end
+      end
+
+      def sport_snapshots(sport, sport_rows, total_km)
+        Snapshot::PERIOD_TYPES.flat_map do |type|
+          buckets = bucketize(sport_rows, type)
+          buckets.keys.sort.map do |key|
+            period_rows = buckets[key]
+            sport_km = period_rows.sum { |r| r[:distance] || 0 } / 1000.0
+            {
+              'period_key' => key,
+              'period_type' => type,
+              'volume_km' => sport_km.round(1),
+              'share' => total_km.positive? ? (sport_km / total_km).round(2) : nil,
+              'pace_profile' => pace_profile(sport, period_rows),
+              'pr_equivalents' => pr_equivalents(sport, period_rows),
+              'confidence' => Snapshot.confidence_for(period_rows.size),
+            }
+          end
+        end
+      end
+
+      # run: pace percentiles p80(easy)/p50/p40(fast) in s_per_km;
+      # ride: speed percentiles p20(easy)/p50/p80(fast) in km_h.
+      def pace_profile(sport, period_rows)
+        samples = period_rows.filter_map do |r|
+          d = r[:distance]
+          t = r[:moving_time]
+          next if d.nil? || t.nil? || d < MIN_VALID_DISTANCE_M || t < MIN_VALID_TIME_S
+
+          sport == 'ride' ? (d / 1000.0) / (t / 3600.0) : t / (d / 1000.0)
+        end.sort
+        return nil if samples.size < MIN_PACE_SAMPLES
+
+        if sport == 'ride'
+          { 'p20' => Snapshot.percentile(samples, 20).round(1),
+            'p50' => Snapshot.percentile(samples, 50).round(1),
+            'p80' => Snapshot.percentile(samples, 80).round(1),
+            'unit' => 'km_h', 'sample_n' => samples.size }
+        else
+          { 'p80' => Snapshot.percentile(samples, 80).round,
+            'p50' => Snapshot.percentile(samples, 50).round,
+            'p40' => Snapshot.percentile(samples, 40).round,
+            'unit' => 's_per_km', 'sample_n' => samples.size }
+        end
+      end
+
+      # Riegel equivalents: direct result when an activity matches the target within
+      # ±2% (extrapolated: false); otherwise best prediction T2 = T1 * (D2/D1)^1.06
+      # — every prediction is extrapolated: true with its source label (contract
+      # sample: half -> full). Factors above 3.5x are low-trust; the prompt layer
+      # (git-fit#96) states that in prose, the flag itself stays honest.
+      def pr_equivalents(sport, period_rows)
+        targets = sport == 'ride' ? RIDE_TARGETS : RUN_TARGETS
+        valid = period_rows.select { |r| valid_effort?(r) }
+        targets.each_with_object({}) do |(label, target_d), out|
+          direct = valid.select { |r| (r[:distance] - target_d).abs <= target_d * DIRECT_MATCH_TOLERANCE }
+                        .min_by { |r| r[:moving_time] }
+          if direct
+            out[label] = { 's' => direct[:moving_time], 'date' => Snapshot.date_of(direct),
+                           'run_id' => direct[:run_id], 'extrapolated' => false }
+            next
+          end
+
+          prediction = valid.filter_map do |r|
+            factor = target_d / r[:distance]
+            [(r[:moving_time] * factor**RIEGEL_EXP).round, r]
+          end.min_by(&:first)
+          next unless prediction
+
+          seconds, source = prediction
+          out[label] = { 's' => seconds, 'extrapolated' => true,
+                         'from' => nearest_label(targets, source[:distance]) }
+        end
+      end
+
+      def valid_effort?(row)
+        d = row[:distance]
+        t = row[:moving_time]
+        !d.nil? && !t.nil? && d >= MIN_VALID_DISTANCE_M && t >= MIN_VALID_TIME_S
+      end
+
+      def nearest_label(targets, distance)
+        targets.min_by { |_, d| (d - distance).abs }.first
+      end
+    end
+  end
+end

data/lib/git_fit/ability/snapshot.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require 'date'
+
+module GitFit
+  module Ability
+    # Period key math + statistical gates for ability snapshots (wiki/Ability).
+    # Wall-clock windowing: start_date_local with offset slices to local date,
+    # naive values are already UTC-stored — both cases take the first 10 chars.
+    module Snapshot
+      PERIOD_TYPES = %w[week month quarter year all].freeze
+
+      DATE_PREFIX_RE = /\A\d{4}-\d{2}-\d{2}/
+
+      class << self
+        # Wall-clock date prefix, or nil when the value is missing/unparseable
+        # (e.g. apple_health rows without start_date_local — windowless rows
+        # participate only in the timeless 'all' bucket).
+        def date_of(row)
+          raw = row[:start_date_local].to_s
+          raw.match?(DATE_PREFIX_RE) ? raw[0, 10] : nil
+        end
+
+        # week -> "2025-W12" (ISO cwyear/cweek, may cross calendar year)
+        # month -> "2025-03"; quarter -> "2025-Q1"; year -> "2025"; all -> "all"
+        def period_key(type, date)
+          case type
+          when 'week'
+            d = Date.parse(date)
+            format('%<year>04d-W%<week>02d', year: d.cwyear, week: d.cweek)
+          when 'month' then date[0, 7]
+          when 'quarter'
+            y = date[0, 4].to_i
+            m = date[5, 2].to_i
+            format('%<year>04d-Q%<quarter>d', year: y, quarter: (m - 1) / 3 + 1)
+          when 'year' then date[0, 4]
+          when 'all' then 'all'
+          end
+        end
+
+        def period_bounds(type, key, all_rows = nil)
+          case type
+          when 'week'
+            y, w = key.split('-W').map(&:to_i)
+            start_d = Date.commercial(y, w, 1)
+            [start_d, start_d + 6]
+          when 'month'
+            start_d = Date.parse("#{key}-01")
+            [start_d, start_d.next_month - 1]
+          when 'quarter'
+            y, q = key.split('-Q').map(&:to_i)
+            start_d = Date.new(y, (q - 1) * 3 + 1, 1)
+            [start_d, Date.new(y, q * 3, 1).next_month - 1]
+          when 'year'
+            start_d = Date.parse("#{key}-01-01")
+            [start_d, Date.new(key.to_i, 12, 31)]
+          when 'all'
+            dates = all_rows.filter_map { |r| date_of(r) }.sort
+            dates.empty? ? [nil, nil] : [Date.parse(dates.first), Date.parse(dates.last)]
+          end
+        end
+
+        # Previous same-type key; nil for 'all' (no earlier peer).
+        def previous_key(type, key)
+          case type
+          when 'week'
+            y, w = key.split('-W').map(&:to_i)
+            week_key_of_date(Date.commercial(y, w, 1) - 7)
+          when 'month'
+            d = Date.parse("#{key}-01") << 1
+            format('%<year>04d-%<month>02d', year: d.year, month: d.month)
+          when 'quarter'
+            y, q = key.split('-Q').map(&:to_i)
+            if q == 1
+              format('%<year>04d-Q%<quarter>d', year: y - 1, quarter: 4)
+            else
+              format('%<year>04d-Q%<quarter>d', year: y, quarter: q - 1)
+            end
+          when 'year' then format('%<year>04d', year: key.to_i - 1)
+          end
+        end
+
+        def week_key_of_date(date)
+          format('%<year>04d-W%<week>02d', year: date.cwyear, week: date.cweek)
+        end
+
+        # Distinct ISO weeks overlapping [start, end].
+        def week_count(start_date, end_date)
+          keys = {}
+          (start_date..end_date).each { |d| keys[week_key_of_date(d)] = true }
+          keys.size
+        end
+
+        # Sample-count confidence: <3 low (prompt-excluded), 3-9 medium, >=10 high.
+        def confidence_for(count)
+          if count < 3
+            'low'
+          elsif count < 10
+            'medium'
+          else
+            'high'
+          end
+        end
+
+        # Nearest-rank percentile of ascending-sorted values.
+        def percentile(sorted_values, percent)
+          return nil if sorted_values.empty?
+
+          sorted_values[((percent / 100.0) * sorted_values.size).ceil - 1]
+        end
+      end
+    end
+  end
+end

data/lib/git_fit/ability.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Athlete ability snapshots — two-layer (fitness + per-sport) derived profile.
+# Design: wiki/Ability (workouts#49); contract: git-fit#95.
+
+require_relative 'ability/snapshot'
+require_relative 'ability/computer'
+
+module GitFit
+  module Ability
+  end
+end

data/lib/git_fit/cli/ability.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'thor'
+require 'json'
+require 'fileutils'
+
+module GitFit
+  class AbilityCLI < Thor
+    desc 'compute', 'Compute athlete ability snapshots (fitness + per-sport) to ability.json'
+    option :output, type: :string, aliases: '-o', desc: 'Output path'
+    option :as_of, type: :string, desc: 'Causal cutoff YYYY-MM-DD — activities after are excluded (digest use)'
+
+    no_commands do
+      def git_fit_config
+        @git_fit_config ||= GitFit::Config.new(options[:config])
+      end
+    end
+
+    def compute
+      config = git_fit_config
+      conn = GitFit::DB::Connection.new(config.db_path)
+      conn.migrate!
+      path = options[:output] || config.export_config.dig('ability', 'path') || 'site/ability.json'
+      doc = Ability::Computer.new(db: conn.db, as_of: options[:as_of]).call
+      FileUtils.mkdir_p(File.dirname(path))
+      File.write(path, "#{JSON.pretty_generate(doc)}\n")
+      count = doc['fitness']['snapshots'].size
+      say_status :done, "Ability snapshots -> #{path} (fitness: #{count} periods)", :green
+    rescue StandardError => e
+      say_status :error, "Ability compute failed: #{e.message}", :red
+    end
+
+    desc 'show', 'Print a single ability snapshot by period key'
+    option :period, type: :string, required: true, desc: 'Period key, e.g. 2025-03 / 2025-Q1 / 2025-W12 / 2025 / all'
+    option :output, type: :string, aliases: '-o', desc: 'ability.json path to read'
+
+    def show
+      path = options[:output] || git_fit_config.export_config.dig('ability', 'path') || 'site/ability.json'
+      doc = JSON.parse(File.read(path))
+      snapshot = find_snapshot(doc, options[:period])
+      if snapshot
+        puts JSON.pretty_generate(snapshot)
+      else
+        say_status :warn, "Ability: no snapshot for period '#{options[:period]}' in #{path}", :yellow
+      end
+    rescue StandardError => e
+      say_status :error, "Ability show failed: #{e.message}", :red
+    end
+
+    private
+
+    def find_snapshot(doc, period_key)
+      candidates = (doc.dig('fitness', 'snapshots') || []) +
+                   (doc['sports'] || {}).values.flat_map { |s| s['snapshots'] || [] }
+      matches = candidates.select { |s| s['period_key'] == period_key }
+      return matches.first if matches.one?
+
+      matches # both fitness and sport layers may carry the key — print all
+    end
+  end
+end

data/lib/git_fit/cli.rb

@@ -23,6 +23,9 @@ module GitFit
     desc 'export SUBCOMMAND', 'Export activities to various formats'
     subcommand 'export', ExportCLI
 
+    desc 'ability SUBCOMMAND', 'Athlete ability snapshots (fitness + per-sport, wiki/Ability)'
+    subcommand 'ability', AbilityCLI
+
     desc 'mcp serve', 'Start the MCP stdio server (read-only workouts data for AI clients)'
     subcommand 'mcp', McpCLI
 

data/lib/git_fit/config.rb

@@ -31,6 +31,7 @@ module GitFit
         'language' => 'zh',
         'timeout' => 60,
         'style' => '',
+        'ability_disabled' => false, # skip ability baseline injection (wiki/Ability)
         'prompts' => {}, # scenario => template override; multi-line, intentionally not env-overridable
       },
       'system' => {
@@ -139,8 +140,10 @@ module GitFit
       if ENV['GIT_FIT_AI_TIMEOUT'] && !ENV['GIT_FIT_AI_TIMEOUT'].empty?
         @data['ai']['timeout'] = typed_value(ENV['GIT_FIT_AI_TIMEOUT'])
       end
-      return unless ENV['GIT_FIT_AI_STYLE'] && !ENV['GIT_FIT_AI_STYLE'].empty?
-      @data['ai']['style'] = ENV['GIT_FIT_AI_STYLE']
+      @data['ai']['style'] = ENV['GIT_FIT_AI_STYLE'] if ENV['GIT_FIT_AI_STYLE'] && !ENV['GIT_FIT_AI_STYLE'].empty?
+      return unless ENV['GIT_FIT_ABILITY_DISABLED'] && !ENV['GIT_FIT_ABILITY_DISABLED'].empty?
+
+      @data['ai']['ability_disabled'] = typed_value(ENV['GIT_FIT_ABILITY_DISABLED'])
     end
 
     def validate!

data/lib/git_fit/export/ai.rb

@@ -42,6 +42,7 @@ module GitFit
         rows = activity_rows
         return warn_skip('no activities in database') if rows.empty?
 
+        @ability_context = build_ability_context
         digest = source_digest(stats, rows)
         return warn_skip('insights unchanged (source_digest match)') if unchanged?(digest)
 
@@ -121,8 +122,10 @@ module GitFit
       end
 
       # Digest covers everything that changes the output: data, prompt mode,
-      # language and model. Prompt template edits are intentionally NOT
-      # tracked — delete insights.json to force regeneration.
+      # language, model and the ability baseline (derived from the full table —
+      # changes beyond the recent-activity window must invalidate the digest).
+      # Prompt template edits are intentionally NOT tracked — delete
+      # insights.json to force regeneration.
       def source_digest(stats, lines)
         payload = ::JSON.generate(
           'model' => @client.model,
@@ -131,6 +134,7 @@ module GitFit
           'period' => period_label,
           'stats' => stats,
           'activities' => lines,
+          'ability' => @ability_context,
         )
         "sha256:#{Digest::SHA256.hexdigest(payload)}"
       end
@@ -226,6 +230,7 @@ module GitFit
           'today' => Time.now.strftime('%Y-%m-%d'),
           'stats' => ::JSON.generate(stats),
           'activities_summary' => activity_lines.join("\n"),
+          'ability_context' => @ability_context,
           'language' => @language,
         }
       end
@@ -239,6 +244,74 @@ module GitFit
         [{ 'role' => 'system', 'content' => content }]
       end
 
+      # --- ability baseline (wiki/Ability, git-fit#96) ---
+
+      # One compact block (<=150 tokens) injected into every scenario template.
+      # Failures degrade to empty string — never block the export.
+      def build_ability_context
+        return '' if @config.ai_config['ability_disabled']
+
+        doc = Ability::Computer.new(db: @db).call
+        month = doc.dig('fitness', 'snapshots')
+                   &.select { |s| s['period_type'] == 'month' }
+                   &.max_by { |s| s['period_key'] }
+        return '' unless month
+
+        lines = ['运动员能力基线（系统派生估算，仅作参考）：']
+        lines << fitness_line(month)
+        doc['sports'].each do |sport, layer|
+          sport_line = sport_line(sport, layer)
+          lines << sport_line unless sport_line.empty?
+        end
+        lines << '样本不足，评价置信度低' if month['confidence'] == 'low'
+        lines.join("\n")
+      rescue StandardError => e
+        warn "AI: ability context unavailable (#{e.class.name.split('::').last}: #{e.message.to_s[0, 120]})"
+        ''
+      end
+
+      def fitness_line(month)
+        parts = ["基础体能（#{month['period_key']}）：月量 #{month['volume_km']}km"]
+        parts << "活跃周 #{(month['frequency'] * 100).round}%" if month['frequency']
+        parts << "最长单次 #{month['longest_km']}km" if month['longest_km']
+        trend = month.dig('trend_vs_prev', 'volume_pct')
+        parts << "距上月量 #{trend.positive? ? '+' : ''}#{trend}%" if trend
+        parts.join(' · ')
+      end
+
+      def sport_line(sport, layer)
+        month = layer['snapshots'].to_a.select { |s| s['period_type'] == 'month' }
+                                  .max_by { |s| s['period_key'] }
+        return '' unless month
+
+        parts = []
+        parts << pace_part(month['pace_profile']) if month['pace_profile']
+        prs = direct_prs(month['pr_equivalents'])
+        parts << "等效 #{prs.map { |label, entry| "#{label} #{format_clock(entry['s'])}" }.join(' / ')}" unless prs.empty?
+        return '' if parts.empty?
+
+        "#{sport}（#{month['period_key']}）：#{parts.join(' · ')}"
+      end
+
+      def pace_part(profile)
+        if profile['unit'] == 'km_h'
+          "easy #{profile['p20']}km/h（P20）"
+        else
+          "easy 配速 #{format_clock(profile['p80'])}/km（P80）"
+        end
+      end
+
+      def direct_prs(equivalents)
+        (equivalents || {}).select { |_, entry| entry['extrapolated'] == false }.first(2)
+      end
+
+      def format_clock(seconds)
+        s = seconds.to_i
+        return format('%<m>d:%<ss>02d', m: s / 60, ss: s % 60) if s < 3600
+
+        format('%<h>d:%<m>02d:%<ss>02d', h: s / 3600, m: (s % 3600) / 60, ss: s % 60)
+      end
+
       # Models like glm-4-flash wrap JSON in ```json fences despite the
       # contract — strip them before parsing.
       def strip_fences(text)

data/lib/git_fit/llm/prompts.rb

@@ -23,9 +23,13 @@ module GitFit
           ### 活动摘要
           {{activities_summary}}
 
+          ### 能力基线（系统派生估算，可能为空）
+          {{ability_context}}
+
           ## 写作要求
           - 汇总统计中的 summary 是全历史累计，不是 {{period}} 当期数据；当期数据以 monthly/yearly 中 {{period}} 对应行为准，活动摘要可用作补充
           - 今天是 {{today}}。若活动摘要中出现 {{period}} 之后的当月数据，那是不完整的当月数据：仅在结尾以『最新动态』一句带过并明确标注，不纳入总结主体，禁止据此得出训练量骤降/中断等跨周期结论
+          - 能力基线非空时作为评价参照：结论应相对该基线（如本期量/配速相对基线的变化）；基线为空或标注『样本不足』时禁止编造能力结论
           - 用 {{language}} 撰写，Markdown 格式，正文 800 字以内
           - 结构：先总后分 —— 总体负荷印象 → 亮点 → 隐忧
           - 所有数字必须来自输入数据，禁止编造或外推
@@ -42,10 +46,14 @@ module GitFit
           ### 活动摘要
           {{activities_summary}}
 
+          ### 能力基线（系统派生估算，可能为空）
+          {{ability_context}}
+
           ## 分析要求
           - 汇总统计中的 summary 是全历史累计，不是 {{period}} 当期数据；对比当期与历史时以 monthly/yearly 分组行为准
           - 今天是 {{today}}。当月不完整的数据（如月内仅数天）只可作为『最新动态』级别观察并明确标注，禁止据此输出骤降/中断等趋势性 anomaly
           - 关注维度：趋势变化、个人纪录（PB）、疲劳信号、季节性规律、运动项目占比变化
+          - 能力基线非空时作为评价参照（如异常判断相对基线水平）；基线为空或标注『样本不足』时禁止编造能力结论
           - 输出 3-6 条，按重要性排序
           - 数据不足以支撑的结论不要输出；无异常时给少量 info 条目即可，禁止强行制造发现
           - 每条结论必须引用具体数字，并给出其来源路径（如 monthly.2026-08.ride.distance）
@@ -62,10 +70,14 @@ module GitFit
           ### 活动摘要
           {{activities_summary}}
 
+          ### 能力基线（系统派生估算，可能为空）
+          {{ability_context}}
+
           ## 建议要求
           - 汇总统计中的 summary 是全历史累计，不是 {{period}} 当期数据；当期负荷以 monthly/yearly 中 {{period}} 对应行为准
           - 今天是 {{today}}。不完整的当月数据不足以支撑训练量调整类建议；如有，仅作观察性提示并标注
           - 输出 2-4 条可执行建议，每条说明数据依据
+          - 能力基线非空时建议强度应相对该基线（渐进而非跳级）；基线为空或标注『样本不足』时禁止编造能力结论
           - 除非数据明确支持（如连续多周稳定负荷且无疲劳信号），不建议提高训练量
           - 关注一致性、恢复与渐进，而非单次表现
           - 用 {{language}} 撰写

data/lib/git_fit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module GitFit
-  VERSION = '0.24.3'
+  VERSION = '0.25.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: git-fit
 version: !ruby/object:Gem::Version
-  version: 0.24.3
+  version: 0.25.0
 platform: ruby
 authors:
 - Lax
@@ -273,6 +273,9 @@ files:
 - db/migrations/001_full_schema.rb
 - exe/git-fit
 - lib/git-fit.rb
+- lib/git_fit/ability.rb
+- lib/git_fit/ability/computer.rb
+- lib/git_fit/ability/snapshot.rb
 - lib/git_fit/auth/garmin.rb
 - lib/git_fit/auth/garmin/di_exchange.rb
 - lib/git_fit/auth/garmin/login_session.rb
@@ -282,6 +285,7 @@ files:
 - lib/git_fit/auth/paths.rb
 - lib/git_fit/auth/strava.rb
 - lib/git_fit/cli.rb
+- lib/git_fit/cli/ability.rb
 - lib/git_fit/cli/checkpointable.rb
 - lib/git_fit/cli/elevation.rb
 - lib/git_fit/cli/export.rb