openclacky 1.2.8 → 1.2.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '080944ed788d584c01c97ba01a27a63b2d2ab341ecf88140a63424460dcb105e'
-  data.tar.gz: 3c2b51bde81be7c18b3384297609f0163d5e6ed40de7121185a4cc374e576f10
+  metadata.gz: 0b32940868f1d61791afd615ff73dbaf72dc80c111f9f9435ef939ef39ae5dec
+  data.tar.gz: be8efa7ee318c3f174ddbbdf1f5b2754705eb6a5d3f263aa11cbe5539b198e8f
 SHA512:
-  metadata.gz: c21e88b443f05ae75979ca4b890142ad15283382ba39fba434a3478f9f3a7f08b13c50fd5760d128662dee26374d69695e6b35e0d25e8f92cdad7351517f564f
-  data.tar.gz: fd37b0b3d64bc68ac777c84beef22be2c6f10c260b5e959273b953aae739c1f176bce7dae5c01c738acb332c5eded97eb973250f51576accbce58ee5f9e12139
+  metadata.gz: abcbed799ca8feed1a41e39a72bd8e6a5e9184c8e76a67bac79f9bee07f88ebf6b639102d6cfcd6527bf80b7b3c9bda5665f131bf81a164b9a14b963cad1ea47
+  data.tar.gz: 829bc77c06483853c1d568d04a528a9611c6e7f775b38b6c6fdebe04c5a5ae6974328bb1ac9c0f8cb1afe0765a60795061157b65860eaf26e8bb7368dadb2b8e

data/CHANGELOG.md

@@ -5,6 +5,41 @@ 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.10] - 2026-06-03
+
+### Added
+- Compressor concurrency config and Ollama context size auto-detection
+- Channel sessions auto-rebind on server restart
+- Disk space check (4 GB minimum) on Windows install
+- WSL network connectivity pre-check before installation
+- MiniMax M3 provider with vision support and pricing
+- One-click exchange rate update in settings
+- Rich TUI controller for terminal interaction
+
+### Improved
+- WebUI working directory selector UX
+- Qwen pricing table: official rates, promo discounts, clean up stale models
+
+### Fixed
+- Directory picker interaction and indentation issues
+- File upload for PDF and Excel files
+- Session soft-delete: count-based cleanup and never evict pinned sessions
+- Usage tooltip total value showing unreadable blue background
+- Workspace file list now collapses on session switch
+- Install script network errors use exit code 2 for better error handling
+
+## [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

data/lib/clacky/agent/llm_caller.rb

@@ -583,6 +583,9 @@ module Clacky
           "exceeds the maximum context",    # Portkey & generic gateways
           "exceeds the model's context",    # Generic
           "exceeds the model's maximum",    # Generic
+          "exceeds the available context",  # llama.cpp / llama-server
+          "available context size",         # llama.cpp / llama-server variant
+          "try increasing it",              # llama.cpp action hint (server.cpp)
           "reduce the length of the input", # Qwen action hint
           "reduce the length of the messages", # OpenAI action hint
           "reduce the length of your",      # Generic action hint

data/lib/clacky/agent/message_compressor_helper.rb

@@ -5,9 +5,10 @@ module Clacky
     # Message compression functionality for managing conversation history
     # Handles automatic compression when token limits are exceeded
     module MessageCompressorHelper
-      # Compression thresholds
-      COMPRESSION_THRESHOLD = 150_000  # Trigger compression when exceeding this (in tokens)
-      MESSAGE_COUNT_THRESHOLD = 200   # Trigger compression when exceeding this (in message count)
+      # Compression behavior knobs.
+      # Token & message-count thresholds are owned by AgentConfig — see
+      # AgentConfig::DEFAULT_COMPRESSION_THRESHOLD / DEFAULT_MESSAGE_COUNT_THRESHOLD.
+      # The constants below are tuning parameters not currently exposed as user config.
       MAX_RECENT_MESSAGES = 20  # Keep this many recent message pairs intact
       TARGET_COMPRESSED_TOKENS = 10_000  # Target size after compression
       IDLE_COMPRESSION_THRESHOLD = 20_000  # Minimum messages needed for idle compression
@@ -141,8 +142,8 @@ module Clacky
         else
           # Normal compression - check thresholds
           # Either: token count exceeds threshold OR message count exceeds threshold
-          token_threshold_exceeded = total_tokens >= COMPRESSION_THRESHOLD
-          message_count_exceeded = message_count >= MESSAGE_COUNT_THRESHOLD
+          token_threshold_exceeded = total_tokens >= @config.compression_threshold
+          message_count_exceeded = message_count >= @config.message_count_threshold
 
           # Only compress if we exceed at least one threshold
           return nil unless token_threshold_exceeded || message_count_exceeded

data/lib/clacky/agent/session_serializer.rb

@@ -25,6 +25,9 @@ module Clacky
         # Restore source; fall back to :manual for sessions saved before this field existed
         @source = (session_data[:source] || "manual").to_sym
 
+        # Restore channel info for IM platform sessions
+        @channel_info = session_data[:channel_info]
+
         # Restore cache statistics if available
         @cache_stats = session_data.dig(:stats, :cache_stats) || {
           cache_creation_input_tokens: 0,
@@ -158,6 +161,7 @@ module Clacky
             model_base_url: persisted_card_field("base_url"),
             sub_model: @config.session_model_overlay_name
           },
+          channel_info: @channel_info,
           stats: stats_data,
           messages: @history.to_a
         }

data/lib/clacky/agent.rb

@@ -46,6 +46,7 @@ module Clacky
                 :latest_latency,  # Hash of latency metrics from the most recent LLM call (see Client#send_messages_with_tools)
                 :reasoning_effort
     attr_accessor :pinned
+    attr_accessor :channel_info
 
     REASONING_EFFORTS = %w[low medium high].freeze
 
@@ -72,6 +73,7 @@ module Clacky
       @config = config.is_a?(AgentConfig) ? config : AgentConfig.new(config)
       @agent_profile = AgentProfile.load(profile)
       @source = source.to_sym  # :manual | :cron | :channel
+      @channel_info = nil  # { platform:, user_id:, user_name:, chat_id: } set by ChannelManager
       @tool_registry = ToolRegistry.new
       @hooks = HookManager.new
       @session_id = session_id
@@ -1593,6 +1595,13 @@ module Clacky
         desktop ? "Desktop: #{desktop}" : nil,
         "Working directory: #{@working_dir}"
       ].compact.join(". ")
+      if @channel_info
+        platform = @channel_info[:platform].to_s
+        user_id  = @channel_info[:user_id].to_s
+        user_name = @channel_info[:user_name].to_s
+        sender = user_name.empty? ? user_id : "@#{user_name}(#{user_id})"
+        parts = "#{parts}. Channel: #{platform}, Sender: #{sender}"
+      end
 
       content = "[Session context: #{parts}]"
 

data/lib/clacky/agent_config.rb

@@ -151,8 +151,16 @@ module Clacky
 
     PERMISSION_MODES = [:auto_approve, :confirm_safes, :confirm_all].freeze
 
+    # Conversation-history compression defaults. Both are user-configurable
+    # via `settings.compression_threshold` / `settings.message_count_threshold`
+    # in ~/.clacky/config.yml — local-model users (llama.cpp / ollama / vllm)
+    # typically lower compression_threshold to fit their server's context window.
+    DEFAULT_COMPRESSION_THRESHOLD = 150_000
+    DEFAULT_MESSAGE_COUNT_THRESHOLD = 200
+
     attr_accessor :permission_mode, :max_tokens, :verbose,
                   :enable_compression, :enable_prompt_caching,
+                  :compression_threshold, :message_count_threshold,
                   :models, :current_model_index, :current_model_id,
                   :memory_update_enabled, :skill_evolution,
                   :max_running_agents, :max_idle_agents,
@@ -165,6 +173,13 @@ module Clacky
       @enable_compression = options[:enable_compression].nil? ? true : options[:enable_compression]
       # Enable prompt caching by default for cost savings
       @enable_prompt_caching = options[:enable_prompt_caching].nil? ? true : options[:enable_prompt_caching]
+      # Token threshold that triggers proactive history compression. Local models
+      # (llama.cpp, ollama, vllm) often have small context windows (e.g. 64k);
+      # users with such setups should lower this to avoid hitting the server-side ceiling.
+      @compression_threshold = options[:compression_threshold] || DEFAULT_COMPRESSION_THRESHOLD
+      # Message-count threshold that also triggers compression, independent of token count.
+      # Guards against pathological histories with many tiny messages.
+      @message_count_threshold = options[:message_count_threshold] || DEFAULT_MESSAGE_COUNT_THRESHOLD
 
       # Models configuration
       @models = options[:models] || []
@@ -318,7 +333,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
@@ -385,7 +402,9 @@ module Clacky
     # Settings keys that are persisted to config.yml.
     # These map directly to AgentConfig accessors.
     CONFIG_SETTINGS_KEYS = %w[
-      enable_compression enable_prompt_caching memory_update_enabled
+      enable_compression enable_prompt_caching
+      compression_threshold message_count_threshold
+      memory_update_enabled
       skill_evolution max_running_agents max_idle_agents
       default_working_dir
     ].freeze
@@ -400,6 +419,8 @@ module Clacky
       settings = {
         "enable_compression" => @enable_compression,
         "enable_prompt_caching" => @enable_prompt_caching,
+        "compression_threshold" => @compression_threshold,
+        "message_count_threshold" => @message_count_threshold,
         "memory_update_enabled" => @memory_update_enabled,
         "skill_evolution" => @skill_evolution,
         "max_running_agents" => @max_running_agents,
@@ -585,12 +606,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 +999,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/brand_config.rb

@@ -783,6 +783,7 @@ module Clacky
 
       FileUtils.rm_f(tmp_zip)
 
+
       record_installed_skill(slug, version, skill_info["description"],
                              encrypted: encrypted,
                              description_zh: skill_info["description_zh"],

data/lib/clacky/cli.rb

@@ -53,6 +53,7 @@ module Clacky
     option :list, type: :boolean, aliases: "-l", desc: "List recent sessions"
     option :attach, type: :string, aliases: "-a", desc: "Attach to session by number or keyword"
     option :json, type: :boolean, default: false, desc: "Output NDJSON to stdout (for scripting/piping)"
+    option :ui, type: :string, default: nil, desc: "Interactive UI implementation: ui2, rich (default: ui2)"
     option :message, type: :string, aliases: "-m", desc: "Run non-interactively with this message and exit"
     option :file,  type: :array, aliases: "-f", desc: "File path(s) to attach (use with -m; supports images and documents)"
     option :image, type: :array, aliases: "-i", desc: "Image file path(s) to attach (alias for --file, kept for compatibility)"
@@ -725,27 +726,47 @@ module Clacky
         # Brand license check — must happen before UI2 starts (raw terminal mode conflict)
         check_brand_license_cli
 
-        # Detect terminal background BEFORE starting UI2 to avoid output interference
-        is_dark_bg = UI2::TerminalDetector.detect_dark_background
+        ui_name = (options[:ui] || ENV["OPENCLACKY_UI"] || "ui2").to_s
 
-        # Pass detected background mode to theme manager (singleton)
-        UI2::ThemeManager.instance.set_background_mode(is_dark_bg)
+        ui_controller = if ui_name == "rich"
+          if Gem::Version.new(RUBY_VERSION) < Gem::Version.new("2.6.0")
+            say "Error: Rich UI requires Ruby >= 2.6. Use --ui ui2 on Ruby #{RUBY_VERSION}.", :red
+            exit 1
+          end
+          require_relative "rich_ui_controller"
+          RichUIController.new(
+            working_dir: working_dir,
+            mode: agent_config.permission_mode.to_s,
+            model: agent_config.model_name,
+            theme: options[:theme]
+          )
+        else
+          unless ui_name == "ui2"
+            say "Error: Unknown UI '#{ui_name}'. Available UIs: ui2, rich", :red
+            exit 1
+          end
+          # Detect terminal background BEFORE starting UI2 to avoid output interference
+          is_dark_bg = UI2::TerminalDetector.detect_dark_background
 
-        # Validate theme
-        theme_name = options[:theme] || "hacker"
-        available_themes = UI2::ThemeManager.available_themes.map(&:to_s)
-        unless available_themes.include?(theme_name)
-          say "Error: Unknown theme '#{theme_name}'. Available themes: #{available_themes.join(', ')}", :red
-          exit 1
-        end
+          # Pass detected background mode to theme manager (singleton)
+          UI2::ThemeManager.instance.set_background_mode(is_dark_bg)
 
-        # Create UI2 controller with configuration
-        ui_controller = UI2::UIController.new(
-          working_dir: working_dir,
-          mode: agent_config.permission_mode.to_s,
-          model: agent_config.model_name,
-          theme: theme_name
-        )
+          # Validate theme
+          theme_name = options[:theme] || "hacker"
+          available_themes = UI2::ThemeManager.available_themes.map(&:to_s)
+          unless available_themes.include?(theme_name)
+            say "Error: Unknown theme '#{theme_name}'. Available themes: #{available_themes.join(', ')}", :red
+            exit 1
+          end
+
+          # Create UI2 controller with configuration
+          UI2::UIController.new(
+            working_dir: working_dir,
+            mode: agent_config.permission_mode.to_s,
+            model: agent_config.model_name,
+            theme: theme_name
+          )
+        end
 
         # Inject UI into agent
         agent.instance_variable_set(:@ui, ui_controller)
@@ -758,6 +779,7 @@ module Clacky
 
         # Track current working thread (agent or idle compression that can be interrupted)
         current_task_thread = nil
+        shutting_down = false
 
         # Idle compression timer - triggers compression after 180s of inactivity
         idle_timer = Clacky::IdleCompressionTimer.new(
@@ -816,7 +838,9 @@ module Clacky
             end
 
             # Stop UI and exit
-            ui_controller.stop
+            shutting_down = true
+            idle_timer.shutdown
+            ui_controller.stop(clear_screen: true)
             exit(0)
           end
 
@@ -867,7 +891,9 @@ module Clacky
             ui_controller.update_todos([])
             next
           when "/exit", "/quit"
-            ui_controller.stop
+            shutting_down = true
+            idle_timer.shutdown
+            ui_controller.stop(clear_screen: true)
             exit(0)
           when "/help"
             sleep 0.1
@@ -909,7 +935,7 @@ module Clacky
             ensure
               current_task_thread = nil
               # Start idle timer after agent completes
-              idle_timer.start
+              idle_timer.start unless shutting_down
             end
           end
         end
@@ -928,7 +954,8 @@ module Clacky
         ui_controller.start_input_loop
 
         # Cleanup: kill any running threads
-        idle_timer.cancel
+        shutting_down = true
+        idle_timer.shutdown
         current_task_thread&.kill
 
         # Save final session state

data/lib/clacky/client.rb

@@ -561,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".