git-fit 0.21.4 → 0.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ee59f447feece2b79c93671bd58f34374178d6b7e1f17ad6444f6b1d07a906c3
-  data.tar.gz: 35493309be5989b82b7b27dcee0821befc8f42fe86d68c0f1304444e63461ab3
+  metadata.gz: 1f9fda747ee0bdc1b1d6588bce636576cb8e371ea0ae36b2bcfedd377a516891
+  data.tar.gz: e19094889528196ead4715706a46fe035516d219ba2c69264cf32e4fc0820da6
 SHA512:
-  metadata.gz: da503a2a3edfad88f2de9dd5018be3955f254316630aa507a2a58b7c55632001c1b942422c1f306850f1792d7858298a4c0c3cfbf19bf5f8559e696480fee60c
-  data.tar.gz: ffa50cac4cb4ef2534408cc971c6f75bb61c4b2e921146cdf3d58e647c7e549c3e57e5e87c082f504bc9addd6b8d28878e6e0649632dfadb7b4aa4b32cd71599
+  metadata.gz: a3fec0c7cfe0f51d7087698900585e480b9ce52d73aa6a8238cfa2493d5500e9d20e93087dda785da91844b3099ea1c4d36b4e642dbd867187d94843ae63b466
+  data.tar.gz: b98ec2e23dc34c3c5694d4627c6ae12a153a2b185d76f0f9567903c2e39a4ff6bb7995ff928e4b17ef4978cdd0a03485e38ae41ef17d9f95bf63f16870d2324b

data/db/migrations/001_full_schema.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+
+# rubocop:disable Metrics/BlockLength
 Sequel.migration do
   up do
     create_table?(:activities) do
@@ -7,7 +10,7 @@ Sequel.migration do
       Float :distance
       Integer :moving_time
       Integer :elapsed_time
-      String :sport_category, null: false, default: "run"
+      String :sport_category, null: false, default: 'run'
       String :sport_type
       String :start_date
       String :start_date_local
@@ -23,6 +26,14 @@ Sequel.migration do
       Integer :calories
       Float :average_speed
       Float :elevation_gain
+      Float :elevation_loss
+      Float :elevation_min
+      Float :elevation_max
+      Float :elevation_gain_terrain
+      Float :elevation_loss_terrain
+      Float :elevation_min_terrain
+      Float :elevation_max_terrain
+      Integer :steps
       String :source
       String :duplicate_info, text: true
       String :divisions, text: true
@@ -62,3 +73,4 @@ Sequel.migration do
     drop_table?(:activities)
   end
 end
+# rubocop:enable Metrics/BlockLength

data/lib/git-fit.rb

@@ -61,6 +61,7 @@ require_relative 'git_fit/import'
 require_relative 'git_fit/sync/base'
 require_relative 'git_fit/std/resolver'
 require_relative 'git_fit/util'
+require_relative 'git_fit/llm'
 require_relative 'git_fit/sync/lorem'
 require_relative 'git_fit/sync/garmin_base'
 require_relative 'git_fit/sync/garmin_base_di'

data/lib/git_fit/cli/export.rb

@@ -78,5 +78,36 @@ module GitFit
     rescue StandardError => e
       say_status :error, "Stats export failed: #{e.message}", :red
     end
+
+    desc 'ai', 'Export AI insights to insights.json (skips with warn when ai: disabled — never blocks CI)'
+    option :output, type: :string, aliases: '-o', desc: 'Output path'
+    option :period, type: :string, default: 'monthly', enum: %w[monthly yearly]
+    option :lang, type: :string, desc: 'Output language override (default: ai.language)'
+
+    def ai
+      config = git_fit_config
+      unless config.ai_config['enabled']
+        say_status :warn, 'AI: ai.enabled is false, skipping (Fix: set ai.enabled: true or GIT_FIT_AI_ENABLED=true)',
+                   :yellow
+        return
+      end
+      client = GitFit::LLM::Client.from_config(config)
+      return if client.nil? # unreachable: disabled handled above
+
+      conn = GitFit::DB::Connection.new(config.db_path)
+      conn.migrate!
+      path = options[:output] || config.export_config.dig('ai', 'path') || 'site/insights.json'
+      doc = Export::AI.new(db: conn.db, config: config, client: client, output: path,
+                           period: options[:period], language: options[:lang]).call
+      if doc
+        sections = %w[summary_markdown insights coaching].count { |k| doc[k] }
+        say_status :done, "Exported AI insights to #{path} (#{sections}/3 sections)", :green
+      else
+        say_status :warn, 'AI: nothing to do (empty db or insights unchanged)', :yellow
+      end
+    rescue GitFit::LLM::Error => e
+      # AI failures are non-fatal by contract — CI deploys must not break.
+      say_status :warn, e.message, :yellow
+    end
   end
 end

data/lib/git_fit/config.rb

@@ -18,10 +18,21 @@ module GitFit
         'svg' => { 'dir' => 'site/svg' },
         'csv' => { 'path' => 'site/workouts.csv' },
         'gpx' => { 'path' => 'site/gpx_out' },
+        'ai' => { 'path' => 'site/insights.json' },
       },
       'privacy' => {
         'start_end_range' => 200,
       },
+      'ai' => {
+        'enabled' => false,
+        'endpoint' => nil, # OpenAI-compatible base URL, e.g. https://open.bigmodel.cn/api/paas/v4
+        'model' => nil,
+        'api_key_env' => 'AI_API_KEY',
+        'language' => 'zh',
+        'timeout' => 60,
+        'style' => '',
+        'prompts' => {}, # scenario => template override; multi-line, intentionally not env-overridable
+      },
       'system' => {
         'units' => 'metric',
         'log_level' => 'info',
@@ -29,7 +40,7 @@ module GitFit
       },
     }.freeze
 
-    KNOWN_TOP_KEYS = %w[database sync export privacy system].freeze
+    KNOWN_TOP_KEYS = %w[database sync export privacy ai system].freeze
 
     # Default config file path: GIT_FIT_CONFIG_PATH env override, else root config.yml.
     def self.default_path
@@ -67,6 +78,10 @@ module GitFit
       @data['export'] || {}
     end
 
+    def ai_config
+      @data['ai'] || {}
+    end
+
     def db_path
       @data.dig('database', 'path') || DEFAULTS['database']['path']
     end
@@ -94,6 +109,9 @@ module GitFit
         @data['system']['timezone'] = ENV['GIT_FIT_SYSTEM_TIMEZONE']
       end
 
+      # ai: scalars only; ai.prompts templates are multi-line and config.yml-only.
+      load_ai_env
+
       GitFit.registered_configs.each do |reg|
         reg[:keys].each do |key|
           segments = key.is_a?(Array) ? key.map(&:to_s) : [key.to_s]
@@ -104,6 +122,27 @@ module GitFit
       end
     end
 
+    def load_ai_env
+      if ENV['GIT_FIT_AI_ENABLED'] && !ENV['GIT_FIT_AI_ENABLED'].empty?
+        @data['ai']['enabled'] = typed_value(ENV['GIT_FIT_AI_ENABLED'])
+      end
+      if ENV['GIT_FIT_AI_ENDPOINT'] && !ENV['GIT_FIT_AI_ENDPOINT'].empty?
+        @data['ai']['endpoint'] = ENV['GIT_FIT_AI_ENDPOINT']
+      end
+      @data['ai']['model'] = ENV['GIT_FIT_AI_MODEL'] if ENV['GIT_FIT_AI_MODEL'] && !ENV['GIT_FIT_AI_MODEL'].empty?
+      if ENV['GIT_FIT_AI_API_KEY_ENV'] && !ENV['GIT_FIT_AI_API_KEY_ENV'].empty?
+        @data['ai']['api_key_env'] = ENV['GIT_FIT_AI_API_KEY_ENV']
+      end
+      if ENV['GIT_FIT_AI_LANGUAGE'] && !ENV['GIT_FIT_AI_LANGUAGE'].empty?
+        @data['ai']['language'] = ENV['GIT_FIT_AI_LANGUAGE']
+      end
+      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']
+    end
+
     def validate!
       @data.each_key do |k|
         next if k.empty? || KNOWN_TOP_KEYS.include?(k)

data/lib/git_fit/export/ai.rb

@@ -0,0 +1,286 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'json'
+require 'time'
+
+module GitFit
+  module Export
+    # Builds insights.json — the AI narrative layer on top of stats (#40, git-fit#93).
+    # Contract (wiki/AI): generated_at / period / source_digest / model / language /
+    # summary_markdown / insights[] / coaching[]
+    #
+    # Cost guardrails:
+    # - input is summary-level (~2-5k tokens, ≤200 activity lines)
+    # - source_digest unchanged vs existing file -> zero LLM calls
+    # - per-scenario retry 1 -> warn + omit that section (never raises to caller)
+    class AI
+      SCENARIOS = %i[monthly_report insights coaching].freeze
+      ACTIVITY_LIMIT = 200
+      INSIGHT_TYPES = %w[trend anomaly pb consistency season].freeze
+      INSIGHT_SEVERITIES = %w[info positive warning].freeze
+      COACHING_PRIORITIES = %w[low medium high].freeze
+
+      # Raised when a scenario response violates the insights.json contract.
+      class ValidationError < StandardError; end
+
+      def initialize(db:, config:, client:, output:, period: 'monthly', language: nil)
+        @db = db
+        @config = config
+        @client = client
+        @output = output
+        unless %w[monthly yearly].include?(period.to_s)
+          raise ArgumentError, "AI: unknown period '#{period}'\n  Fix: use --period monthly|yearly"
+        end
+        @period = period.to_s
+        @language = language || config.ai_config['language'] || 'zh'
+      end
+
+      # Returns the written doc hash, or nil when skipped (empty db / digest match).
+      def call
+        stats = Calculator.new(db: @db).call
+        rows = activity_rows
+        return warn_skip('no activities in database') if rows.empty?
+
+        digest = source_digest(stats, rows)
+        return warn_skip('insights unchanged (source_digest match)') if unchanged?(digest)
+
+        sections = {}
+        SCENARIOS.each do |scenario|
+          sections[scenario] = generate_scenario(scenario, stats, rows)
+        end
+
+        doc = base_doc(digest)
+        doc['summary_markdown'] = sections[:monthly_report]['summary_markdown'] if sections[:monthly_report]
+        doc['insights'] = sections[:insights]['insights'] if sections[:insights]
+        doc['coaching'] = sections[:coaching]['coaching'] if sections[:coaching]
+
+        File.write(@output, "#{::JSON.pretty_generate(doc)}\n")
+        doc
+      end
+
+      private
+
+      def warn_skip(reason)
+        warn "AI: skipping export — #{reason}"
+        nil
+      end
+
+      # --- input digest ---
+
+      def activity_rows
+        @activity_rows ||= @db[:activities]
+                           .order(Sequel.desc(:start_date_local))
+                           .limit(ACTIVITY_LIMIT)
+                           .select(:start_date_local, :sport_category, :distance,
+                                   :moving_time, :average_heartrate, :elevation_gain)
+                           .all
+      end
+
+      # Compact one-line-per-activity summary — keeps the prompt in the
+      # ~2-5k token budget (distance km / time min / HR bpm / ascent m).
+      def activity_lines
+        activity_rows.map do |r|
+          parts = [r[:start_date_local].to_s[0, 10], r[:sport_category].to_s]
+          parts << format('%.1fkm', r[:distance] / 1000.0) if r[:distance]
+          parts << "#{(r[:moving_time] / 60).round}min" if r[:moving_time]
+          parts << "HR#{r[:average_heartrate].round}" if r[:average_heartrate]
+          parts << "asc#{r[:elevation_gain].round}m" if r[:elevation_gain]
+          parts.join(' ')
+        end
+      end
+
+      def period_label
+        latest = activity_rows.find { |r| r[:start_date_local] }
+        base = latest ? latest[:start_date_local].to_s : Time.now.utc.iso8601
+        @period == 'yearly' ? base[0, 4] : base[0, 7]
+      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.
+      def source_digest(stats, lines)
+        payload = ::JSON.generate(
+          'model' => @client.model,
+          'language' => @language,
+          'period_mode' => @period,
+          'stats' => stats,
+          'activities' => lines,
+        )
+        "sha256:#{Digest::SHA256.hexdigest(payload)}"
+      end
+
+      def unchanged?(digest)
+        return false unless File.exist?(@output)
+
+        existing = ::JSON.parse(File.read(@output))
+        existing.is_a?(Hash) && existing['source_digest'] == digest
+      rescue JSON::ParserError, TypeError
+        false
+      end
+
+      # --- generation ---
+
+      def generate_scenario(scenario, stats, rows)
+        template = LLM::Prompts.resolve(scenario, @config.ai_config['prompts'])
+        rendered = LLM::Template.render(template, slots(stats, rows))
+        messages = system_messages + [{ 'role' => 'user', 'content' => rendered }]
+
+        last_error = nil
+        2.times do
+          parsed = parse_model_json(@client.chat(messages: messages))
+          validate_section!(scenario, parsed)
+          return parsed
+        rescue GitFit::LLM::Error, ::JSON::ParserError, ValidationError => e
+          last_error = e
+        end
+        warn "AI: scenario #{scenario} failed after retry, omitting section " \
+             "(#{last_error.class.name.split('::').last}: #{last_error.message.to_s[0, 120]})"
+        nil
+      end
+
+      # Parse model output: strip fences, then fall back to a repair pass —
+      # models like glm-4-flash emit literal newlines inside string values
+      # (invalid JSON; the spec requires \n escapes), e.g. long markdown in
+      # summary_markdown. The repair walks the text tracking string state and
+      # escapes control characters inside strings; newlines outside strings
+      # (pretty formatting) are legal and kept as-is.
+      def parse_model_json(raw)
+        body = strip_fences(raw)
+        begin
+          ::JSON.parse(body)
+        rescue ::JSON::ParserError
+          ::JSON.parse(repair_json(body))
+        end
+      end
+
+      def repair_json(text)
+        out = +''
+        in_string = false
+        escape = false
+        text.each_char do |ch|
+          if in_string && escape
+            escape = false
+            out << ch
+          elsif in_string && ch == '\\'
+            escape = true
+            out << ch
+          elsif in_string && ch == '"'
+            in_string = false
+            out << ch
+          elsif in_string && ch == "\n"
+            out << '\\n'
+          elsif in_string && ch == "\t"
+            out << '\\t'
+          elsif in_string && ch == "\r"
+            out << '\\r'
+          else
+            in_string = true if !in_string && ch == '"'
+            out << ch
+          end
+        end
+        out
+      end
+
+      def slots(stats, _rows)
+        {
+          'period' => period_label,
+          'stats' => ::JSON.generate(stats),
+          'activities_summary' => activity_lines.join("\n"),
+          'language' => @language,
+        }
+      end
+
+      # ai.style is a site-owner directive — belongs in the system message,
+      # never in the user template (user templates are user-overridable).
+      def system_messages
+        content = "你是运动数据产品 workouts 的分析助手，输出语言：#{@language}。"
+        style = @config.ai_config['style'].to_s.strip
+        content += "\n站主附加指令：#{style}" unless style.empty?
+        [{ 'role' => 'system', 'content' => content }]
+      end
+
+      # Models like glm-4-flash wrap JSON in ```json fences despite the
+      # contract — strip them before parsing.
+      def strip_fences(text)
+        text.to_s.strip
+            .sub(/\A```(?:json)?\s*/m, '')
+            .sub(/```\s*\z/m, '')
+            .strip
+      end
+
+      # --- contract validation ---
+
+      def validate_section!(scenario, parsed)
+        case scenario
+        when :monthly_report then validate_summary(parsed)
+        when :insights then validate_insights(parsed)
+        when :coaching then validate_coaching(parsed)
+        end
+      end
+
+      def validate_summary(parsed)
+        summary = parsed.is_a?(Hash) ? parsed['summary_markdown'] : nil
+        return if summary.is_a?(String) && !summary.strip.empty?
+
+        raise ValidationError, 'missing or empty summary_markdown'
+      end
+
+      def validate_insights(parsed)
+        items = parsed.is_a?(Hash) ? parsed['insights'] : nil
+        raise ValidationError, 'missing insights array' unless items.is_a?(Array)
+
+        items.each_with_index { |item, i| validate_insight_item(item, i) }
+      end
+
+      def validate_insight_item(item, index)
+        raise ValidationError, "insights[#{index}] is not an object" unless item.is_a?(Hash)
+
+        unless INSIGHT_TYPES.include?(item['type'])
+          raise ValidationError, "insights[#{index}].type '#{item['type']}' not in #{INSIGHT_TYPES.join('|')}"
+        end
+        unless INSIGHT_SEVERITIES.include?(item['severity'])
+          raise ValidationError,
+                "insights[#{index}].severity '#{item['severity']}' not in #{INSIGHT_SEVERITIES.join('|')}"
+        end
+        %w[id title body].each do |field|
+          unless item[field].is_a?(String) && !item[field].empty?
+            raise ValidationError, "insights[#{index}].#{field} missing or empty"
+          end
+        end
+        item['data_refs'] = item['data_refs'].is_a?(Array) ? item['data_refs'] : []
+      end
+
+      def validate_coaching(parsed)
+        items = parsed.is_a?(Hash) ? parsed['coaching'] : nil
+        raise ValidationError, 'missing coaching array' unless items.is_a?(Array)
+
+        items.each_with_index do |item, i|
+          raise ValidationError, "coaching[#{i}] is not an object" unless item.is_a?(Hash)
+
+          unless COACHING_PRIORITIES.include?(item['priority'])
+            raise ValidationError,
+                  "coaching[#{i}].priority '#{item['priority']}' not in #{COACHING_PRIORITIES.join('|')}"
+          end
+          %w[title body].each do |field|
+            unless item[field].is_a?(String) && !item[field].empty?
+              raise ValidationError, "coaching[#{i}].#{field} missing or empty"
+            end
+          end
+        end
+      end
+
+      # --- output ---
+
+      def base_doc(digest)
+        {
+          'generated_at' => Time.now.utc.iso8601,
+          'period' => period_label,
+          'source_digest' => digest,
+          'model' => @client.model,
+          'language' => @language,
+        }
+      end
+    end
+  end
+end

data/lib/git_fit/export.rb

@@ -11,3 +11,4 @@ require_relative 'export/csv'
 require_relative 'export/gpx'
 require_relative 'export/calculator'
 require_relative 'export/stats'
+require_relative 'export/ai'

data/lib/git_fit/llm/client.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'json'
+
+module GitFit
+  module LLM
+    # OpenAI-compatible chat-completions client (POST {endpoint}/chat/completions).
+    #
+    # Provider-agnostic: endpoint / model / api key all come from the config
+    # `ai:` section — the gem never hardcodes a vendor. Non-streaming (P1);
+    # SSE can be layered later without changing call sites.
+    class Client
+      attr_reader :endpoint, :model, :timeout
+
+      # Builds a client from GitFit::Config.
+      # Returns nil when ai.enabled is false (caller decides to warn+skip);
+      # raises ConfigError with a Fix: hint when enabled but misconfigured.
+      def self.from_config(config)
+        ai = config.ai_config
+        return nil unless ai['enabled']
+
+        missing = %w[endpoint model].select { |k| ai[k].to_s.strip.empty? }
+        unless missing.empty?
+          raise ConfigError,
+                "LLM: ai.#{missing.join(', ai.')} not configured\n" \
+                '  Fix: set ai.endpoint / ai.model in config.yml ' \
+                '(e.g. https://open.bigmodel.cn/api/paas/v4 + glm-4-flash)'
+        end
+
+        key_env = ai['api_key_env'].to_s.strip
+        key_env = 'AI_API_KEY' if key_env.empty?
+        api_key = ENV[key_env].to_s
+        if api_key.empty?
+          raise ConfigError,
+                "LLM: env #{key_env} is empty\n" \
+                "  Fix: export #{key_env}=<your-api-key> (local: add to .env.local and source it)"
+        end
+
+        new(endpoint: ai['endpoint'], model: ai['model'], api_key: api_key, timeout: ai['timeout'])
+      end
+
+      def initialize(endpoint:, model:, api_key:, timeout: 60)
+        @endpoint = endpoint.to_s.sub(%r{/+\z}, '')
+        @model = model
+        @api_key = api_key
+        @timeout = timeout.is_a?(Numeric) ? timeout : 60
+      end
+
+      # messages: [{ 'role' => 'system'|'user', 'content' => '...' }, ...]
+      # Returns the assistant content string.
+      def chat(messages:, temperature: nil)
+        payload = { model: @model, messages: messages }
+        payload[:temperature] = temperature if temperature
+        status, body = http_post(chat_completions_url, JSON.generate(payload))
+        parse_content(status, body)
+      end
+
+      private
+
+      def chat_completions_url
+        @endpoint.end_with?('/chat/completions') ? @endpoint : "#{@endpoint}/chat/completions"
+      end
+
+      # Single HTTP seam — specs stub this method (zero network), mirroring
+      # the http_request stub convention used by sync adapters.
+      # Returns [status, body_string].
+      def http_post(url, body_json)
+        resp = conn.post(url) do |req|
+          req.headers['Content-Type'] = 'application/json'
+          req.headers['Authorization'] = "Bearer #{@api_key}"
+          req.body = body_json
+        end
+        [resp.status, resp.body]
+      rescue Faraday::TimeoutError
+        raise TimeoutError,
+              "LLM: request timed out after #{@timeout}s\n" \
+              "  Fix: increase ai.timeout (current #{@timeout}) or check endpoint reachability: curl #{url}"
+      rescue Faraday::ConnectionFailed => e
+        raise ConnectionError,
+              "LLM: connection failed — #{e.message}\n  Fix: verify ai.endpoint is reachable: curl #{url}"
+      end
+
+      def conn
+        @conn ||= Faraday.new do |f|
+          f.options.timeout = @timeout
+          f.options.open_timeout = 10
+        end
+      end
+
+      def parse_content(status, body)
+        case status
+        when 200..299
+          data = parse_json_body(body)
+          content = data.dig('choices', 0, 'message', 'content')
+          if content.nil?
+            raise BadResponseError,
+                  "LLM: unexpected response shape (missing choices[0].message.content)\n" \
+                  "  Fix: verify ai.endpoint is an OpenAI-compatible API; top-level keys: #{data.keys.inspect}"
+          end
+          if content.to_s.strip.empty?
+            raise BadResponseError,
+                  "LLM: empty completion content\n" \
+                  '  Fix: retry; if persistent, check ai.model output style or switch model'
+          end
+          content
+        when 400
+          raise RequestError,
+                "LLM: bad request (400) — #{api_message(body)}\n" \
+                '  Fix: check ai.model name and prompt size (activities_summary may need a lower limit)'
+        when 401, 403
+          raise AuthError,
+                "LLM: auth failed (#{status}) — #{api_message(body)}\n" \
+                '  Fix: check the API key env var (ai.api_key_env) and rotate it if expired'
+        when 429
+          raise RateLimitError,
+                "LLM: rate limited (429) — #{api_message(body)}\n" \
+                '  Fix: retry later or switch ai.model to a lower/cheaper tier'
+        else
+          raise ServerError,
+                "LLM: upstream error (#{status}) — #{api_message(body)}\n" \
+                '  Fix: retry later; if persistent, switch provider via ai.endpoint'
+        end
+      end
+
+      def parse_json_body(body)
+        JSON.parse(body)
+      rescue JSON::ParserError, TypeError
+        raise BadResponseError,
+              "LLM: response is not valid JSON (got #{body.to_s[0, 80].inspect}...)\n" \
+              '  Fix: verify ai.endpoint points to an OpenAI-compatible API (…/v1), not a HTML page'
+      end
+
+      def api_message(body)
+        JSON.parse(body.to_s).dig('error', 'message')
+      rescue JSON::ParserError, TypeError
+        body.to_s[0, 200]
+      end
+    end
+  end
+end

data/lib/git_fit/llm/errors.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module GitFit
+  module LLM
+    # Base for all LLM errors. Messages follow the actionable-error convention:
+    # "<scope>: <failure reason>" + "\n  Fix: <copy-paste command>"
+    class Error < StandardError; end
+
+    # ai.enabled but endpoint/model/api key missing or invalid.
+    class ConfigError < Error; end
+
+    # HTTP 400 — prompt too large / malformed request / unknown model name.
+    class RequestError < Error; end
+
+    # HTTP 401/403 — API key rejected or revoked.
+    class AuthError < Error; end
+
+    # HTTP 429 — rate limited / quota exhausted.
+    class RateLimitError < Error; end
+
+    # HTTP 5xx — provider-side failure.
+    class ServerError < Error; end
+
+    # HTTP 2xx but body not JSON or unexpected shape (not OpenAI-compatible).
+    class BadResponseError < Error; end
+
+    class TimeoutError < Error; end
+
+    class ConnectionError < Error; end
+  end
+end

data/lib/git_fit/llm/prompts.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module GitFit
+  module LLM
+    # Built-in prompt templates for AI insight scenarios.
+    #
+    # Contract: the JSON schema block (SCHEMAS) is baked at the end of every
+    # resolved template and is intentionally NOT user-customizable —
+    # ai.prompts.<scenario> replaces only the body, so insights.json
+    # structured output stays stable (see wiki/AI).
+    module Prompts
+      SCENARIOS = %i[monthly_report insights coaching].freeze
+
+      BODIES = {
+        monthly_report: <<~TXT,
+          你是资深骑行/跑步教练。请基于以下运动数据撰写 {{period}} 的训练总结。
+
+          ## 输入数据
+
+          ### 汇总统计
+          {{stats}}
+
+          ### 活动摘要
+          {{activities_summary}}
+
+          ## 写作要求
+          - 汇总统计中的 summary 是全历史累计，不是 {{period}} 当期数据；当期数据以 monthly/yearly 中 {{period}} 对应行为准，活动摘要可用作补充
+          - 用 {{language}} 撰写，Markdown 格式，正文 800 字以内
+          - 结构：先总后分 —— 总体负荷印象 → 亮点 → 隐忧
+          - 所有数字必须来自输入数据，禁止编造或外推
+          - 语气客观克制，避免空洞鼓励和套话
+        TXT
+        insights: <<~TXT,
+          你是运动数据分析专家。请基于以下运动数据找出值得注意的洞察与异常。分析周期：{{period}}。
+
+          ## 输入数据
+
+          ### 汇总统计
+          {{stats}}
+
+          ### 活动摘要
+          {{activities_summary}}
+
+          ## 分析要求
+          - 汇总统计中的 summary 是全历史累计，不是 {{period}} 当期数据；对比当期与历史时以 monthly/yearly 分组行为准
+          - 关注维度：趋势变化、个人纪录（PB）、疲劳信号、季节性规律、运动项目占比变化
+          - 输出 3-6 条，按重要性排序
+          - 数据不足以支撑的结论不要输出；无异常时给少量 info 条目即可，禁止强行制造发现
+          - 每条结论必须引用具体数字，并给出其来源路径（如 monthly.2026-08.ride.distance）
+          - 用 {{language}} 撰写
+        TXT
+        coaching: <<~TXT,
+          你是谨慎的耐力运动教练。请基于以下运动数据给出下一周期的训练建议。当前周期：{{period}}。
+
+          ## 输入数据
+
+          ### 汇总统计
+          {{stats}}
+
+          ### 活动摘要
+          {{activities_summary}}
+
+          ## 建议要求
+          - 汇总统计中的 summary 是全历史累计，不是 {{period}} 当期数据；当期负荷以 monthly/yearly 中 {{period}} 对应行为准
+          - 输出 2-4 条可执行建议，每条说明数据依据
+          - 除非数据明确支持（如连续多周稳定负荷且无疲劳信号），不建议提高训练量
+          - 关注一致性、恢复与渐进，而非单次表现
+          - 用 {{language}} 撰写
+        TXT
+      }.freeze
+
+      # Structured output contract — appended to every resolved template,
+      # never user-editable (guarantees insights.json parseability).
+      SCHEMAS = {
+        monthly_report: <<~TXT,
+          ## 输出契约（必须严格遵守）
+          仅输出一个 JSON 对象，不要输出任何其他文字、解释或代码块标记：
+          {"summary_markdown": "<训练总结正文，Markdown 字符串>"}
+        TXT
+        insights: <<~TXT,
+          ## 输出契约（必须严格遵守）
+          仅输出一个 JSON 对象，不要输出任何其他文字、解释或代码块标记：
+          {"insights": [{"id": "<kebab-case-id>", "type": "<trend|anomaly|pb|consistency|season>", "severity": "<info|positive|warning>", "title": "<一句话结论>", "body": "<Markdown 正文，引用具体数字>", "data_refs": ["<stats 数据路径>"]}]}
+        TXT
+        coaching: <<~TXT,
+          ## 输出契约（必须严格遵守）
+          仅输出一个 JSON 对象，不要输出任何其他文字、解释或代码块标记：
+          {"coaching": [{"title": "<建议标题>", "body": "<Markdown 正文，含数据依据>", "priority": "<low|medium|high>"}]}
+        TXT
+      }.freeze
+
+      def self.builtin(scenario)
+        BODIES.fetch(scenario.to_sym)
+      end
+
+      def self.schema(scenario)
+        SCHEMAS.fetch(scenario.to_sym)
+      end
+
+      # Resolves a scenario template: user override (config ai.prompts) if
+      # present, else the built-in body; then appends the baked schema block.
+      def self.resolve(scenario, overrides = {})
+        key = scenario.to_sym
+        raise_unknown_scenario(scenario) unless BODIES.key?(key)
+        body = overrides.is_a?(Hash) ? (overrides[scenario.to_s] || overrides[key.to_s] || BODIES[key]) : nil
+        "#{body.to_s.rstrip}\n\n#{SCHEMAS[key].rstrip}"
+      end
+
+      def self.raise_unknown_scenario(scenario)
+        raise ConfigError,
+              "LLM: unknown prompt scenario '#{scenario}'\n" \
+              "  Fix: use one of #{SCENARIOS.map(&:to_s).join(', ')}"
+      end
+    end
+  end
+end

data/lib/git_fit/llm/template.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module GitFit
+  module LLM
+    # {{slot}} renderer for prompt templates.
+    # Unknown or leftover slots fail fast — never ship a half-rendered prompt.
+    module Template
+      SLOT_PATTERN = /\{\{\s*([a-zA-Z_][a-zA-Z0-9_]*)\s*\}\}/
+
+      # Raised when a template references a slot that is not provided.
+      class UnknownSlotError < Error
+        def initialize(name, allowed)
+          super(
+            "LLM: template references unknown slot {{#{name}}}\n" \
+            "  Fix: use one of the allowed slots: #{allowed.join(', ')}"
+          )
+        end
+      end
+
+      # Renders {{slot}} placeholders. Values are coerced with to_s.
+      # Raises UnknownSlotError for slots without a provided value and for
+      # slots that appear in the output after substitution (data-injected
+      # placeholders are treated as a bug, not passed through).
+      def self.render(text, slots)
+        rendered = text.gsub(SLOT_PATTERN) do
+          name = Regexp.last_match(1)
+          raise UnknownSlotError.new(name, slots.keys.sort) unless slots.key?(name)
+
+          slots[name].to_s
+        end
+        leftover = rendered.match(SLOT_PATTERN)
+        return rendered unless leftover
+
+        raise UnknownSlotError.new(leftover[1], slots.keys.sort)
+      end
+    end
+  end
+end

data/lib/git_fit/llm.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# LLM integration — OpenAI-compatible chat completions.
+# Provider-agnostic by design: endpoint / model / api key are all config-driven
+# (config.yml `ai:` section, see Config::DEFAULTS['ai'] and wiki/AI).
+
+require_relative 'llm/errors'
+require_relative 'llm/template'
+require_relative 'llm/prompts'
+require_relative 'llm/client'
+
+module GitFit
+  module LLM
+  end
+end

data/lib/git_fit/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: git-fit
 version: !ruby/object:Gem::Version
-  version: 0.21.4
+  version: 0.22.0
 platform: ruby
 authors:
 - Lax
@@ -257,9 +257,6 @@ extensions: []
 extra_rdoc_files: []
 files:
 - db/migrations/001_full_schema.rb
-- db/migrations/002_iso8601_time_format.rb
-- db/migrations/003_add_elevation_fields.rb
-- db/migrations/004_add_elevation_terrain_fields.rb
 - exe/git-fit
 - lib/git-fit.rb
 - lib/git_fit/auth/garmin.rb
@@ -306,6 +303,7 @@ files:
 - lib/git_fit/elevation/train/fitter.rb
 - lib/git_fit/elevation/train/runner.rb
 - lib/git_fit/export.rb
+- lib/git_fit/export/ai.rb
 - lib/git_fit/export/calculator.rb
 - lib/git_fit/export/csv.rb
 - lib/git_fit/export/defaults.rb
@@ -329,6 +327,11 @@ files:
 - lib/git_fit/install/actions.rb
 - lib/git_fit/install/actions/db-store/restore.yml.erb
 - lib/git_fit/install/actions/db-store/save.yml.erb
+- lib/git_fit/llm.rb
+- lib/git_fit/llm/client.rb
+- lib/git_fit/llm/errors.rb
+- lib/git_fit/llm/prompts.rb
+- lib/git_fit/llm/template.rb
 - lib/git_fit/parser.rb
 - lib/git_fit/parser/base.rb
 - lib/git_fit/parser/fit.rb

data/db/migrations/002_iso8601_time_format.rb

@@ -1,54 +0,0 @@
-Sequel.migration do
-  up do
-    rows = self[:activities].all
-
-    rows.each do |row|
-      updates = {}
-
-      # Detect format: ISO 8601 contains "T", naive format does not
-      sd = row[:start_date]
-      if sd && sd.is_a?(String) && !sd.include?("T")
-        t = Time.parse(sd) rescue nil
-        if t
-          case row[:source]
-          when "apple_health"
-            # Apple Health stored +0800 local time as naive "2026-06-25 19:49:17"
-            # Parse as local (+0800) then convert to UTC ISO 8601
-            local_t = Time.parse(sd + " +0800") rescue nil
-            updates[:start_date] = local_t.utc.iso8601 if local_t
-          else
-            # All other sources stored UTC naive "2026-06-25 11:49:17"
-            # Parse as UTC then output ISO 8601
-            utc_t = Time.parse(sd + " UTC") rescue nil
-            updates[:start_date] = utc_t.iso8601 if utc_t
-          end
-        end
-      end
-
-      sdl = row[:start_date_local]
-      if sdl && sdl.is_a?(String) && !sdl.include?("T")
-        t = Time.parse(sdl) rescue nil
-        if t
-          case row[:source]
-          when "strava", "igpsport"
-            # These stores proper local time, preserve as ISO 8601 with offset
-            local_t = Time.parse(sdl + " +0800") rescue nil
-            updates[:start_date_local] = local_t.iso8601 if local_t
-          else
-            # Same as start_date (UTC)
-            utc_t = Time.parse(sdl + " UTC") rescue nil
-            updates[:start_date_local] = utc_t.iso8601 if utc_t
-          end
-        end
-      end
-
-      self[:activities].where(run_id: row[:run_id]).update(updates) unless updates.empty?
-    end
-  end
-
-  down do
-    # One-way migration: cannot automatically revert ISO 8601 → naive
-    # because timezone info would be silently lost.
-    # To rollback: restore from DB backup or re-import.
-  end
-end

data/db/migrations/003_add_elevation_fields.rb

@@ -1,19 +0,0 @@
-Sequel.migration do
-  up do
-    alter_table(:activities) do
-      add_column :elevation_loss, Float
-      add_column :elevation_min, Float
-      add_column :elevation_max, Float
-      add_column :steps, Integer
-    end
-  end
-
-  down do
-    alter_table(:activities) do
-      drop_column :steps
-      drop_column :elevation_max
-      drop_column :elevation_min
-      drop_column :elevation_loss
-    end
-  end
-end

data/db/migrations/004_add_elevation_terrain_fields.rb

@@ -1,19 +0,0 @@
-Sequel.migration do
-  up do
-    alter_table(:activities) do
-      add_column :elevation_gain_terrain, Float
-      add_column :elevation_loss_terrain, Float
-      add_column :elevation_min_terrain,  Float
-      add_column :elevation_max_terrain,  Float
-    end
-  end
-
-  down do
-    alter_table(:activities) do
-      drop_column :elevation_max_terrain
-      drop_column :elevation_min_terrain
-      drop_column :elevation_loss_terrain
-      drop_column :elevation_gain_terrain
-    end
-  end
-end