openclacky 1.2.7 → 1.2.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8057fdabcb077c8ca378fcbbc0efa442abc6b9664464d2d8d1b737e0206d2ed9
-  data.tar.gz: 657f282a20664ef793d7ff663e963739f5fbdb478b8e174df9c5e459ec09231b
+  metadata.gz: b2060d694267d0947681785d2e2ffe730d0b241a9ac2ec68e218eb037478bf27
+  data.tar.gz: 0b3e301010e16752da0bd64a9603b06010c2a23c5bd81884c7719d74f8f1bd67
 SHA512:
-  metadata.gz: fad3e045271032a1150745f1d8531aeed24ea376efdcd99346aeaeec4eb5f1edec187e9dbe38ee8d19e5a9cf599bfb7e5431ad55e5993f1dd243bb4ebf5faa2d
-  data.tar.gz: 95b1a7ec783b459f5c70b99d3535f5a0054d4a8c72d855d9c98b9771cde9d59cb33dcf609be844fade932e1487c82c525cf4354438c5ad4b271494a4166dc729
+  metadata.gz: 386e2359d904b9a6bc81e56429cd585aaef59b7174f5dbc93e51cdd2bf97df703fd8145910759f50427632fcc90a307ed3ec6b19e48f0230d7e0c39987d3e7a8
+  data.tar.gz: 15413b83259ef7a39acac101597149cbf2144473da691d885f14d3b271076399da14c924db19201a1b99d8bf264542b56f3619b6cb6b903dfdac462e46f15a97

data/CHANGELOG.md

@@ -5,6 +5,32 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.9] - 2026-06-01
+
+### Added
+- Image generation support via model tool calls
+- Startup telemetry now reports launch source for better usage analytics
+
+### Improved
+- Feishu channel setup simplified with Agent App flow — fewer manual steps and no redirect URL config needed
+
+### Fixed
+- Network region detection hardened with CDN fallback to handle edge cases and improve reliability
+
+## [1.2.8] - 2026-06-01
+
+### Added
+- Extensibility framework: patching, shell hooks, and channel user adapter plugins — customize Clacky behavior without modifying core code
+
+### Improved
+- Billing session list now shows session names, merged deleted sessions, and standardized token breakdown with cache hit/miss color coding
+
+### Fixed
+- Streaming LLM responses automatically retry when connection drops instead of silently truncating
+
+### More
+- Extend openclacky skill with additional extension points
+
 ## [1.2.7] - 2026-06-01
 
 ### Added

data/lib/clacky/agent.rb

@@ -137,6 +137,9 @@ module Clacky
       # Register built-in tools
       register_builtin_tools
 
+      # Load declarative shell hooks from ~/.clacky/hooks.yml
+      ShellHookLoader.load_into(@hooks)
+
       # Ensure user-space parsers are in place (~/.clacky/parsers/)
       Utils::ParserManager.setup!
 

data/lib/clacky/agent_config.rb

@@ -318,7 +318,9 @@ module Clacky
         end
       end
 
-      new(**constructor_args)
+      instance = new(**constructor_args)
+      instance.derive_media_models!
+      instance
     end
 
     # Auto-injection of provider-preset lite models into @models has been
@@ -585,12 +587,94 @@ module Clacky
       }.compact
     end
 
-    # Find model by type (default or lite)
-    # Returns the model hash or nil if not found
+    # Find model by type (default or lite or media kind)
+    # Returns the model hash or nil if not found.
+    # For media kinds (image/video/audio): explicit user-configured (custom)
+    # entries win; otherwise an auto-derived virtual entry is returned
+    # based on the default model's provider — mirroring how lite is
+    # virtually derived via #lite_model_config_for_current.
     def find_model_by_type(type)
+      kind = type.to_s
+      if Clacky::Providers::MEDIA_KINDS.include?(kind)
+        custom = @models.find { |m| m["type"] == kind }
+        return custom if custom
+        return derive_media_model(kind)
+      end
       @models.find { |m| m["type"] == type }
     end
 
+    private def derive_media_model(kind)
+      default = find_model_by_type("default")
+      return nil unless default
+
+      provider_id = Clacky::Providers.resolve_provider(
+        base_url: default["base_url"],
+        api_key:  default["api_key"]
+      )
+      return nil unless provider_id
+
+      model_name = Clacky::Providers.default_media_model(provider_id, kind)
+      return nil if model_name.nil? || model_name.to_s.empty?
+
+      {
+        "model"         => model_name,
+        "base_url"      => default["base_url"],
+        "api_key"       => default["api_key"],
+        "type"          => kind,
+        "auto_injected" => true
+      }
+    end
+
+    # Kept as a no-op for backward compatibility. Media auto entries are
+    # now derived virtually on read; nothing is materialized into @models.
+    def derive_media_models!
+      @models.reject! { |m| m["auto_injected"] && Clacky::Providers::MEDIA_KINDS.include?(m["type"].to_s) }
+    end
+
+    # Returns the configured/derived media model entry for `kind`, plus a
+    # hint about its source. UI uses this to render the tri-state control.
+    # @param kind [String] one of "image" / "video" / "audio"
+    # @return [Hash{String=>Object}] keys:
+    #   "configured" [Boolean]            — anything available?
+    #   "source"     [String]             — "off" | "auto" | "custom"
+    #   "model"      [String, nil]
+    #   "base_url"   [String, nil]
+    #   "provider"   [String, nil]        — provider id
+    #   "available"  [Array<String>]      — auto-source candidates from preset
+    def media_state(kind)
+      kind = kind.to_s
+      custom = @models.find { |m| m["type"] == kind }
+      auto   = custom ? nil : derive_media_model(kind)
+      entry  = custom || auto
+
+      provider_id = if entry
+                      Clacky::Providers.resolve_provider(
+                        base_url: entry["base_url"],
+                        api_key:  entry["api_key"]
+                      )
+                    end
+
+      available_provider_id = if custom
+                                provider_id
+                              else
+                                default = find_model_by_type("default")
+                                default && Clacky::Providers.resolve_provider(
+                                  base_url: default["base_url"],
+                                  api_key:  default["api_key"]
+                                )
+                              end
+      available = available_provider_id ? Clacky::Providers.media_models(available_provider_id, kind) : []
+
+      {
+        "configured" => !entry.nil?,
+        "source"     => custom ? "custom" : (auto ? "auto" : "off"),
+        "model"      => entry && entry["model"],
+        "base_url"   => entry && entry["base_url"],
+        "provider"   => provider_id,
+        "available"  => available
+      }
+    end
+
     # Find model by composite key (model name + base_url).
     # Used when restoring a session to match its original model without relying
     # on the runtime-only id (which changes on every process restart).
@@ -896,14 +980,14 @@ module Clacky
       Clacky::Providers.supports?(provider_id, capability, model_name: m["model"])
     end
 
-    # Set a model's type (default or lite)
-    # Ensures only one model has each type
+    # Set a model's type (default, lite, image, video, or audio).
+    # At most one model carries each type at a time.
     # @param index [Integer] the model index
-    # @param type [String, nil] "default", "lite", or nil to remove type
+    # @param type [String, nil] type tag, or nil to clear
     # Returns true if successful
     def set_model_type(index, type)
       return false if index < 0 || index >= @models.length
-      return false unless ["default", "lite", nil].include?(type)
+      return false unless ["default", "lite", "image", "video", "audio", nil].include?(type)
 
       if type
         # Remove type from any other model that has it

data/lib/clacky/billing/billing_store.rb

@@ -4,7 +4,7 @@ require "json"
 require "fileutils"
 require "securerandom"
 require_relative "billing_record"
-
+require_relative "../session_manager"
 module Clacky
   module Billing
     # Persistent storage for billing records using JSONL files
@@ -115,8 +115,112 @@ module Clacky
         }
       end
 
-      # Get daily cost breakdown for the last N days
-      # @param days [Integer] Number of days to include
+      # Get session-level summary statistics
+      # @param period [Symbol] :day, :week, :month, :year, or :all
+      # @param model [String, nil] Filter by model name
+      # @param limit [Integer] Maximum number of sessions to return
+      # @return [Array<Hash>] Session summaries sorted by cost descending
+      def session_summary(period: :month, model: nil, limit: 50)
+        from_time = period_start(period)
+        records = query(from: from_time, model: model)
+
+        # Load session names from session manager
+        session_names = load_session_names
+
+        # Group by session_id
+        by_session = records.group_by { |r| r.session_id || "unknown" }
+
+        active_sessions = []
+        deleted_records = []
+
+        by_session.each do |session_id, rs|
+          total_cost = rs.sum { |r| r.cost_usd || 0 }
+          total_prompt = rs.sum { |r| r.prompt_tokens || 0 }
+          total_completion = rs.sum { |r| r.completion_tokens || 0 }
+          total_cache_read = rs.sum { |r| r.cache_read_tokens || 0 }
+          total_cache_write = rs.sum { |r| r.cache_write_tokens || 0 }
+          first_record = rs.min_by { |r| r.timestamp }
+          last_record = rs.max_by { |r| r.timestamp }
+
+          entry = {
+            session_id: session_id,
+            session_name: session_names[session_id],
+            total_cost: total_cost.round(6),
+            total_tokens: total_prompt + total_completion,
+            prompt_tokens: total_prompt,
+            completion_tokens: total_completion,
+            cache_read_tokens: total_cache_read,
+            cache_write_tokens: total_cache_write,
+            requests: rs.size,
+            first_request: first_record&.timestamp&.iso8601,
+            last_request: last_record&.timestamp&.iso8601,
+            models: rs.map(&:model).uniq
+          }
+
+          if session_names[session_id]
+            active_sessions << entry
+          else
+            deleted_records << entry
+          end
+        end
+
+        # Merge all deleted sessions into a single row
+        if deleted_records.any?
+          merged = {
+            session_id: "_deleted_",
+            session_name: nil,
+            is_deleted: true,
+            total_cost: deleted_records.sum { |r| r[:total_cost] }.round(6),
+            total_tokens: deleted_records.sum { |r| r[:total_tokens] },
+            prompt_tokens: deleted_records.sum { |r| r[:prompt_tokens] },
+            completion_tokens: deleted_records.sum { |r| r[:completion_tokens] },
+            cache_read_tokens: deleted_records.sum { |r| r[:cache_read_tokens] },
+            cache_write_tokens: deleted_records.sum { |r| r[:cache_write_tokens] },
+            requests: deleted_records.sum { |r| r[:requests] },
+            first_request: deleted_records.map { |r| r[:first_request] }.compact.min,
+            last_request: deleted_records.map { |r| r[:last_request] }.compact.max,
+            models: deleted_records.flat_map { |r| r[:models] }.uniq
+          }
+          active_sessions << merged
+        end
+
+        # Sort by total cost descending
+        active_sessions.sort_by! { |s| -s[:total_cost] }
+
+        # Apply limit
+        limit ? active_sessions.first(limit) : active_sessions
+      end
+
+      # Load session names from session manager (including trashed sessions)
+      # Returns a hash mapping session_id to session name
+      def load_session_names
+        names = {}
+        begin
+          # Load from active sessions
+          manager = Clacky::SessionManager.new
+          manager.all_sessions.each do |session|
+            id = session[:session_id]
+            name = session[:name]
+            names[id] = name if id && name && !name.to_s.empty?
+          end
+
+          # Also load from trashed sessions
+          trash_dir = File.join(Dir.home, ".clacky", "trash", "sessions-trash")
+          if Dir.exist?(trash_dir)
+            Dir.glob(File.join(trash_dir, "*.json")).each do |filepath|
+              session = JSON.parse(File.read(filepath), symbolize_names: true) rescue next
+              id = session[:session_id]
+              name = session[:name]
+              names[id] = name if id && name && !name.to_s.empty?
+            end
+          end
+        rescue => e
+          # Silently fail if session manager is not available
+        end
+        names
+      end
+
+      # Get daily cost breakdown for the last N days      # @param days [Integer] Number of days to include
       # @param model [String, nil] Filter by model name
       # @return [Array<Hash>] Daily summaries with date and cost
       def daily_breakdown(days: 30, model: nil)

data/lib/clacky/cli.rb

@@ -942,6 +942,111 @@ module Clacky
     end
 
     # ── billing command ────────────────────────────────────────────────────────
+    desc "patch_new ID TARGET", "Scaffold a runtime patch for a method (TARGET like Clacky::Tools::WebSearch#execute)"
+    long_desc <<-LONGDESC
+      Generate a method-override patch under ~/.clacky/patches/ID/. The current
+      method fingerprint is computed automatically and stored in meta.yml; you
+      only edit the method body in patch.rb. If a future gem version changes the
+      targeted method, the fingerprint will no longer match and the patch is
+      auto-disabled on next start (rather than applied and risking breakage).
+
+      Examples:
+        $ clacky patch_new fix-search Clacky::Tools::WebSearch#execute -d "bump timeout"
+    LONGDESC
+    option :desc, type: :string, aliases: "-d", default: "", desc: "Short description"
+    def patch_new(id, target)
+      require_relative "patch_loader"
+      path = Clacky::PatchLoader.scaffold(id, target, description: options[:desc])
+      puts "Created patch: #{path}"
+      puts "Edit patch.rb, then run: clacky patch_verify"
+    rescue ArgumentError, StandardError => e
+      warn "Error: #{e.message}"
+      exit 1
+    end
+
+    desc "patch_verify", "Load ~/.clacky/patches/ and report applied / disabled / skipped"
+    def patch_verify
+      require "clacky"
+      result = Clacky::PatchLoader.last_result
+
+      if result.applied.empty? && result.disabled.empty? && result.skipped.empty?
+        puts "No patches found in ~/.clacky/patches/"
+        return
+      end
+
+      result.applied.each  { |id| puts "[OK]       #{id}" }
+      result.disabled.each { |(id, reason)| puts "[DISABLED] #{id} — #{reason}" }
+      result.skipped.each  { |(id, reason)| puts "[SKIP]     #{id} — #{reason}" }
+      exit 1 if result.skipped.any?
+    end
+
+    desc "patch_list", "List patches under ~/.clacky/patches/ and their status"
+    def patch_list
+      invoke :patch_verify, []
+    end
+
+    desc "hook_new", "Scaffold a starter ~/.clacky/hooks.yml with an example guard script"
+    def hook_new
+      require_relative "shell_hook_loader"
+      path = Clacky::ShellHookLoader.scaffold
+      puts "Created hooks config: #{path}"
+      puts "Edit it, then run: clacky hook_verify"
+    rescue ArgumentError => e
+      warn "Error: #{e.message}"
+      exit 1
+    end
+
+    desc "hook_verify", "Load ~/.clacky/hooks.yml and report which hooks register"
+    def hook_verify
+      require_relative "agent/hook_manager"
+      require_relative "shell_hook_loader"
+      hm = Clacky::HookManager.new
+      result = Clacky::ShellHookLoader.load_into(hm)
+
+      if result.registered.empty? && result.skipped.empty?
+        puts "No hooks found in ~/.clacky/hooks.yml"
+        return
+      end
+
+      result.registered.each { |(event, name)| puts "[OK]   #{event} → #{name}" }
+      result.skipped.each { |(name, reason)| puts "[SKIP] #{name} — #{reason}" }
+      exit 1 if result.skipped.any?
+    end
+
+    desc "channel_new NAME", "Scaffold a custom channel adapter at ~/.clacky/channels/NAME/"
+    long_desc <<-LONGDESC
+      Generate a ready-to-edit channel adapter skeleton. The skeleton already
+      self-registers and implements the full adapter interface with TODO markers —
+      you only fill in the method bodies, then run `clacky channel_verify`.
+
+      Examples:
+        $ clacky channel_new slack
+    LONGDESC
+    def channel_new(name)
+      require_relative "server/channel"
+      path = Clacky::Channel::Adapters::UserAdapterLoader.scaffold(name)
+      puts "Created channel adapter: #{path}"
+      puts "Edit the TODO sections, then run: clacky channel_verify"
+    rescue ArgumentError => e
+      warn "Error: #{e.message}"
+      exit 1
+    end
+
+    desc "channel_verify", "Load user channel adapters and report which are valid"
+    def channel_verify
+      require_relative "server/channel"
+      result = Clacky::Channel::Adapters::UserAdapterLoader.last_result
+
+      if result.loaded.empty? && result.skipped.empty?
+        puts "No custom channel adapters found in ~/.clacky/channels/"
+        return
+      end
+
+      result.loaded.each { |n| puts "[OK]   #{n}" }
+      result.skipped.each { |(n, reason)| puts "[SKIP] #{n} — #{reason}" }
+      exit 1 if result.skipped.any?
+    end
+
     desc "billing", "Show billing summary and usage statistics"
     long_desc <<-LONGDESC
       Display billing summary with token usage and cost breakdown.

data/lib/clacky/client.rb

@@ -258,7 +258,16 @@ module Clacky
         response.env.body = sse_buf if response.body.to_s.empty?
         raise_error(response)
       end
-      MessageFormat::Bedrock.parse_response(aggregator.to_h)
+
+      result = aggregator.to_h
+      # A complete Converse stream always emits stopReason in its messageStop
+      # frame. Its absence means the upstream cut the stream mid-response,
+      # leaving a half-written message; retry rather than accept the truncation.
+      if result["stopReason"].nil?
+        raise Clacky::UpstreamTruncatedError,
+          "[LLM] Streaming response ended without stopReason (upstream cut the stream). Retrying..."
+      end
+      MessageFormat::Bedrock.parse_response(result)
     end
 
     def parse_simple_bedrock_response(response)
@@ -307,7 +316,16 @@ module Clacky
         recovered = Struct.new(:status, :body).new(response.status, recovered_body)
         raise_error(recovered)
       end
-      MessageFormat::Anthropic.parse_response(aggregator.to_h)
+
+      result = aggregator.to_h
+      # A complete Messages stream always emits stop_reason in its message_delta
+      # frame. Its absence means the upstream cut the stream mid-response,
+      # leaving a half-written message; retry rather than accept the truncation.
+      if result["stop_reason"].nil?
+        raise Clacky::UpstreamTruncatedError,
+          "[LLM] Streaming response ended without stop_reason (upstream cut the stream). Retrying..."
+      end
+      MessageFormat::Anthropic.parse_response(result)
     end
 
     def parse_simple_anthropic_response(response)
@@ -360,7 +378,18 @@ module Clacky
         response.env.body = sse_buf if response.body.to_s.empty?
         raise_error(response)
       end
-      MessageFormat::OpenAI.parse_response(aggregator.to_h)
+
+      result = aggregator.to_h
+      # A complete chat-completion stream always terminates with a frame
+      # carrying finish_reason. Its absence means the upstream cut the stream
+      # mid-response (e.g. proxy idle-timeout, connection reset that Faraday
+      # didn't surface as an exception), leaving a half-written message. Treat
+      # as retryable so we don't hand a silently truncated answer to the agent.
+      if result.dig("choices", 0, "finish_reason").nil?
+        raise Clacky::UpstreamTruncatedError,
+          "[LLM] Streaming response ended without finish_reason (upstream cut the stream). Retrying..."
+      end
+      MessageFormat::OpenAI.parse_response(result)
     end
 
     def parse_simple_openai_response(response)
@@ -532,10 +561,14 @@ module Clacky
     # ── Error handling ────────────────────────────────────────────────────────
 
     def handle_test_response(response)
-      return { success: true } if response.status == 200
+      return { success: true, status: response.status } if response.status == 200
 
       error_body = JSON.parse(response.body) rescue nil
-      { success: false, error: extract_error_message(error_body, response.body) }
+      {
+        success: false,
+        status:  response.status,
+        error:   extract_error_message(error_body, response.body)
+      }
     end
 
     def raise_error(response)

data/lib/clacky/default_skills/channel-manager/SKILL.md

@@ -99,128 +99,51 @@ Ask:
 
 ### Feishu setup
 
-#### Step 1 — Try automated setup (script)
+Feishu now offers a one-click **Agent App** (智能体应用) that auto-configures all
+required permissions, events, and publishing for you — no Bot capability toggle,
+no permission JSON, no event subscription, no version/release steps. Just create
+the app and copy the credentials. The connection mode is unchanged (long
+connection / WebSocket), handled entirely by the server.
 
-Run the setup script (full path is available in the supporting files list above):
-```bash
-ruby "SKILL_DIR/feishu_setup.rb"
-```
-**Important**: call `terminal` with `timeout: 180` — the script may wait up to 90s for a WebSocket connection in Phase 4.
-
-**If exit code is 0:**
-- The script completed successfully.
-- Config is already written to `~/.clacky/channels.yml`.
-- Tell the user: "✅ Feishu channel configured automatically! The channel is ready."
-- **Skip Step 2 (manual fallback) and continue to Step 3.**
-
-**If exit code is non-0:**
-- Check stdout for the error message.
-- **If the error contains "Browser not configured" or "browser tool":**
-  - Tell the user: "The browser tool is not configured yet. Let me help you set it up first..."
-  - Invoke the `browser-setup` skill: `invoke_skill("browser-setup", "setup")`.
-  - After browser-setup completes, tell the user: "Browser is ready! Let me retry the Feishu setup..."
-  - **Retry the script** (same command, same timeout). If it succeeds this time, stop. If it fails again, check the new error and proceed accordingly.
-- **If the error contains "No cookies found" or "Please log in":**
-  - Open Feishu login page using browser tool:
-    ```
-    browser(action="navigate", url="https://open.feishu.cn/app")
-    ```
-  - Tell the user: "I've opened Feishu in your browser. Please log in, then reply 'done'."
-  - Wait for "done".
-  - **Retry the script** (same command, same timeout). Repeat this login-wait-retry loop up to **3 times total**.
-    - If any attempt succeeds (exit code 0), stop — setup is complete.
-    - If an attempt fails with a **different** error (not a login error), break out of the loop and continue to Step 2.
-    - If all 3 attempts fail with login errors, tell the user: "Automated setup was unable to detect a Feishu login after 3 attempts. Switching to guided setup..." and continue to Step 2.
-- **Otherwise (non-login, non-browser error):**
-  - Tell the user: "Automated setup encountered an issue: `<error message>`. Switching to guided setup..."
-  - Continue to Step 2 (manual flow) below.
-
----
-
-#### Step 2 — Manual guided setup (fallback)
-
-Only reach here if the automated script failed.
-
-##### Phase 1 — Open Feishu Open Platform
-
-1. Navigate: `open https://open.feishu.cn/app`. Pass `isolated: true`.
-2. If a login page or QR code is shown, tell the user to log in and wait for "done".
-3. Confirm the app list is visible.
-
-##### Phase 2 — Create a new app
-
-4. **Always create a new app** — do NOT reuse existing apps. Guide the user: "Click 'Create Enterprise Self-Built App', fill in name (e.g. Open Clacky) and description (e.g. AI assistant powered by openclacky), then submit. Reply done." Wait for "done".
-
-##### Phase 3 — Enable Bot capability
-
-5. Feishu opens Add App Capabilities by default after creating an app. Guide the user: "Find the Bot capability card and click the Add button next to it, then reply done." Wait for "done".
-
-##### Phase 4 — Get credentials
-
-6. Navigate to Credentials & Basic Info in the left menu.
-7. Guide the user: "Copy App ID and App Secret, then paste here. Reply with: App ID: xxx, App Secret: xxx" Wait for the reply. Parse `app_id` and `app_secret`.
+#### Step 1 — Open the Agent App creation page
 
-##### Phase 5 — Add message permissions
+1. Navigate: `open https://open.feishu.cn/page/launcher?from=backend_oneclick`. Pass `isolated: true`. If the browser is not configured (the `open` call fails), just give the user the URL and ask them to open it manually in any browser — the rest of the flow is fully manual and does not need browser automation.
+2. If a login page or QR code is shown, tell the user to scan/log in and wait for "done".
 
-8. Navigate to Permission Management and open the bulk import dialog.
-9. Guide the user: "In the bulk import dialog, clear the existing example first (select all, delete), then paste the following JSON. Reply done." Wait for "done". Do NOT try to clear or edit via browser — user does it.
+#### Step 2 — Create the Agent App
 
-```json
-{
-  "scopes": {
-    "tenant": [
-      "im:message",
-      "im:message.p2p_msg:readonly",
-      "im:message:send_as_bot"
-    ],
-    "user": []
-  }
-}
-```
+3. After login, the page lands on **创建飞书智能体应用 (Create Feishu Agent App)**.
+   Guide the user: "Enter an app name (e.g. Open Clacky), then click **立即创建 (Create Now)**. Reply done."
+   (The avatar is auto-assigned at random and can be changed anytime — it does not affect setup.)
+   Wait for "done".
 
-##### Phase 6 — Configure event subscription (Long Connection)
+#### Step 3 — Copy credentials
 
-**CRITICAL**: Feishu requires the long connection to be established *before* you can save the event config. The platform shows "No application connection detected" until `clacky server` is running and connected.
+4. The page jumps to **创建成功 (Created Successfully)**, showing `App ID` and `App Secret`.
+   The Secret is masked by default. Guide the user: "Click the eye icon next to **App Secret** to reveal it,
+   then copy both values and paste here. Reply with: App ID: xxx, App Secret: xxx"
+   Wait for the reply. Parse `app_id` (starts with `cli_`) and `app_secret`. Trim whitespace and
+   make sure the two values are not swapped.
 
-10. **Apply config and establish connection** — Run:
-    ```bash
-    curl -X POST http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/channels/feishu \
-      -H "Content-Type: application/json" \
-      -d '{"app_id":"<APP_ID>","app_secret":"<APP_SECRET>","domain":"https://open.feishu.cn"}'
-    ```
-    **CRITICAL: This curl call is the ONLY way to save credentials. NEVER write `~/.clacky/channels.yml` or any file under `~/.clacky/channels/` directly. The server API handles persistence and hot-reload.**
-11. **Wait for connection** — Poll until log shows `[feishu-ws] WebSocket connected ✅`:
-    ```bash
-    for i in $(seq 1 20); do
-      grep -q "\[feishu-ws\] WebSocket connected" ~/.clacky/logger/clacky-$(date +%Y-%m-%d).log 2>/dev/null && echo "CONNECTED" && break
-      sleep 1
-    done
-    ```
-12. **Configure events** — Guide the user: "In Events & Callbacks, select 'Long Connection' mode. Click Save. Then click Add Event, search `im.message.receive_v1`, select it, click Add. Reply done." Wait for "done".
+#### Step 4 — Save credentials
 
-##### Phase 7 — Publish the app
-
-13. Navigate to Version Management & Release. Guide the user: "Create a new version (e.g. 1.0.0, note: Initial release for Open Clacky) and publish it. Reply done." Wait for "done".
-
-##### Phase 8 — Validate
-
-```bash
-curl -s -X POST "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal" \
-  -H "Content-Type: application/json" \
-  -d '{"app_id":"<APP_ID>","app_secret":"<APP_SECRET>"}'
-```
-
-Check for `"code":0`. On success: continue to Step 3 (below).
-
-##### Phase 9 — done
+5. Run:
+   ```bash
+   curl -X POST http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/channels/feishu \
+     -H "Content-Type: application/json" \
+     -d '{"app_id":"<APP_ID>","app_secret":"<APP_SECRET>","domain":"https://open.feishu.cn"}'
+   ```
+   **CRITICAL: This curl call is the ONLY way to save credentials. NEVER write `~/.clacky/channels.yml`
+   or any file under `~/.clacky/channels/` directly. The server API handles persistence, hot-reload,
+   and establishing the long connection.**
 
-Step 2 ends here. **Continue to Step 3.**
+On success: tell the user "✅ Feishu channel configured!" and **continue to Step 5 (Feishu CLI)**.
 
 ---
 
-#### Step 3 — Optional: install Feishu CLI
+#### Step 5 — Optional: install Feishu CLI
 
-Reach here from either Step 1 success or end of Step 2. Read `app_id` and `app_secret` from `~/.clacky/channels.yml` (under `channels.feishu`) for the install commands below.
+Reach here after the channel is configured (Step 4 succeeded). Read `app_id` and `app_secret` from `~/.clacky/channels.yml` (under `channels.feishu`) for the install commands below.
 
 Call `request_user_feedback`:
 
@@ -269,7 +192,7 @@ When `lark-cli auth login` returns successfully, tell the user:
 
 ### WeCom setup
 
-1. Navigate: `open https://work.weixin.qq.com/wework_admin/frame#/aiHelper/create`. Pass `isolated: true`.
+1. Navigate: `open https://work.weixin.qq.com/wework_admin/frame#/aiHelper/create`. Pass `isolated: true`. If the browser is not configured (the `open` call fails), just give the user the URL and ask them to open it manually in any browser — the rest of the flow is fully manual and does not need browser automation.
 2. If a login page or QR code is shown, tell the user to log in and wait for "done".
 3. Guide the user: "Scroll to the bottom of the right panel and click 'API mode creation'. Reply done." Wait for "done".
 4. Guide the user: "Click 'Add' next to 'Visible Range'. Select the top-level company node. Click Confirm. Reply done." Wait for "done".