openclacky 0.8.6 → 0.8.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0190a435c18d666a4d2cc7c65b301bd24f18cc6a0159f5d7a4ae25ee552883d7'
-  data.tar.gz: 62eecd22f6cc112aa00674c683002f14ada01d637b95551a5ca7ff29d408ad75
+  metadata.gz: 94fe2f9fd0477231e7411c762aacfecc9eb15b87f027366d7598c73e738499c0
+  data.tar.gz: 41e84ac897d4d120dec9c7d88f69b35f82779adc2963a13dd099fd686d926ec3
 SHA512:
-  metadata.gz: 8b0dcb369eeb481fc32dd8e02d4cc22ed6b21f3fb5115d9145623444bb88be1cf95cf1c3f8b62988bd54c28888512ee90ecf4df74f98250a04f2f0fcbd9d77d8
-  data.tar.gz: a6d72920b58547540dd6b389cb8c5dadafc4cf9face794217a7d4c2245bb4f2b46fce4e83616074d1054b9f7542ee0601cad1f9e43fc9358563f6d0dc8b97124
+  metadata.gz: 1f28d84aab760ca2c53cc0c558ec82fb3b0bebc8b2fe5279021f3d0cc5c896ebe5dda7fc8f060f7d77609bb6b6aedffa064ef1897185db01a9b6f4e022364646
+  data.tar.gz: 64b71cd3c7793201f16600b100088cd739671c9c414252dadc6a593600f15271fc79a953877e59bc2014af929888384e3640ee78e7c1227c8b72e81f919ca72c

data/CHANGELOG.md

@@ -7,6 +7,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.8] - 2026-03-13
+
+### Added
+- **i18n system with zh/en runtime switching**: WebUI now supports Chinese and English; all UI text is served through an `I18n` module and switches instantly without a page reload
+- **Onboard language selection step**: first-time setup now opens with a language picker (中文 / English) before any configuration, so the entire onboard experience is conducted in the user's chosen language
+- **Onboard "what's your name" step**: onboard flow now asks for the user's preferred name early on and addresses them by name throughout the rest of the setup
+- **Chinese SOUL.md default**: when a user onboards in Chinese and skips the soul-setup conversation, a Chinese-language SOUL.md is written automatically so the assistant responds in Chinese by default
+
+### Fixed
+- **Onboard WS race condition**: fixed a bug where the first auto-triggered `/onboard` command was silently lost — the WebSocket `session_list` event arrived before the session view was active and redirected the UI to the welcome screen, hiding the agent's response
+
+## [0.8.7] - 2026-03-13
+
+### Added
+- **PDF file upload and reading**: users can now upload PDF files directly in the WebUI chat; the agent reads and analyzes the content via the built-in `pdf-reader` skill
+- **WebUI favicon and SVG icons**: browser tab now shows the Clacky icon
+- **Public skill store install**: skills from the public store can be installed directly via the WebUI without a GitHub URL
+- **Auto-kill previous server on startup**: launching `clacky serve` now automatically kills any previously running instance via pidfile, preventing port conflicts
+
+### Improved
+- **Brand skill loading speed**: loading brand skills no longer triggers a network decryption request — name and description are now read from the local `brand_skills.json` cache, making New Session significantly faster
+- **Memory update UX**: memory update step now shows a spinner and info-style message instead of a bare log line
+- **Browser snapshot output**: snapshot output is compressed to reduce token cost when the agent uses browser tools
+- **Subagent output**: subagent task completion now shows a brief info line instead of a full "Task Complete" block, reducing noise in the parent agent's context
+
+### Fixed
+- **Subagent token delta on first iteration**: subagent now inherits `previous_total_tokens` correctly, fixing an inflated token count on the first tool iteration
+- **Chrome DevTools inspect URL**: updated the remote debugging URL to include the `#remote-debugging` fragment for correct navigation
+- **Shell output token explosion**: long lines in shell output are now truncated to prevent excessive token usage
+
+### More
+- Binary file size limit lowered from 5 MB to 512 KB to reduce accidental token cost
+- `kill_existing_server` logic moved from CLI into `HttpServer` for cleaner separation
+- Browser tool prefers `snapshot -i` over `screenshot` for lower token cost
+- Cross-platform PID file path using `Dir.tmpdir` instead of hardcoded `/tmp`
+
 ## [0.8.6] - 2026-03-12
 
 ### Added

data/lib/clacky/agent/memory_updater.rb

@@ -42,7 +42,7 @@ module Clacky
 
         @memory_prompt_injected = true
         @memory_updating = true
-        @ui&.show_info("Updating long-term memory...")
+        @ui&.show_progress("Updating long-term memory…")
 
         @messages << {
           role: "user",
@@ -62,7 +62,7 @@ module Clacky
         @messages.reject! { |m| m[:memory_update] }
         @memory_prompt_injected = false
         @memory_updating = false
-        @ui&.show_info("Memory updated.")
+        @ui&.clear_progress
       end
 
       private def memory_update_enabled?

data/lib/clacky/agent/session_serializer.rb

@@ -275,6 +275,13 @@ module Clacky
             next unless source.is_a?(Hash) && source[:type].to_s == "base64"
 
             "data:#{source[:media_type]};base64,#{source[:data]}"
+          when "document"
+            # Anthropic PDF document block — return a sentinel string for frontend display
+            source = block[:source]
+            next unless source.is_a?(Hash) && source[:media_type].to_s == "application/pdf"
+
+            # Return a special marker so the frontend can render a PDF badge instead of an <img>
+            "pdf:#{source[:data]&.then { |d| d[0, 32] }}"  # prefix to identify without full payload
           end
         end
       end

data/lib/clacky/agent.rb

@@ -141,7 +141,7 @@ module Clacky
       @config.model_name
     end
 
-    def run(user_input, images: [])
+    def run(user_input, images: [], files: [])
       # Start new task for Time Machine
       task_id = start_new_task
 
@@ -172,8 +172,8 @@ module Clacky
         @messages << system_message
       end
 
-      # Format user message with images if provided
-      user_content = format_user_content(user_input, images)
+      # Format user message with images and files if provided
+      user_content = format_user_content(user_input, images, files)
       @messages << { role: "user", content: user_content, task_id: task_id, created_at: Time.now.to_f }
       @total_tasks += 1
 
@@ -208,7 +208,12 @@ module Clacky
 
           # Check if done (no more tool calls needed)
           if response[:finish_reason] == "stop" || response[:tool_calls].nil? || response[:tool_calls].empty?
-            @ui&.show_assistant_message(response[:content]) if response[:content] && !response[:content].empty?
+            # During memory update phase, show LLM response as info (not a chat bubble)
+            if @memory_updating && response[:content] && !response[:content].empty?
+              @ui&.show_info("🧠 " + response[:content].strip)
+            elsif response[:content] && !response[:content].empty?
+              @ui&.show_assistant_message(response[:content])
+            end
 
             # Debug: log why we're stopping
             if @config.verbose && (response[:tool_calls].nil? || response[:tool_calls].empty?)
@@ -227,7 +232,8 @@ module Clacky
           end
 
           # Show assistant message if there's content before tool calls
-          if response[:content] && !response[:content].empty?
+          # During memory update phase, suppress text output (only tool calls matter)
+          if response[:content] && !response[:content].empty? && !@memory_updating
             @ui&.show_assistant_message(response[:content])
           end
 
@@ -272,13 +278,17 @@ module Clacky
           @modified_files_in_task = []  # Reset for next task
         end
 
-        @ui&.show_complete(
-          iterations: result[:iterations],
-          cost: result[:total_cost_usd],
-          duration: result[:duration_seconds],
-          cache_stats: result[:cache_stats],
-          awaiting_user_feedback: awaiting_user_feedback
-        )
+        if @is_subagent
+          @ui&.show_info("Subagent done (#{result[:iterations]} iterations, $#{result[:total_cost_usd].round(4)})")
+        else
+          @ui&.show_complete(
+            iterations: result[:iterations],
+            cost: result[:total_cost_usd],
+            duration: result[:duration_seconds],
+            cache_stats: result[:cache_stats],
+            awaiting_user_feedback: awaiting_user_feedback
+          )
+        end
         @hooks.trigger(:on_complete, result)
         result
       rescue Clacky::AgentInterrupted
@@ -714,6 +724,10 @@ module Clacky
         ui: @ui,
         profile: @agent_profile.name
       )
+      subagent.instance_variable_set(:@is_subagent, true)
+
+      # Inherit previous_total_tokens so the first iteration delta is calculated correctly
+      subagent.instance_variable_set(:@previous_total_tokens, @previous_total_tokens)
 
       # Deep clone messages to avoid cross-contamination
       subagent.instance_variable_set(:@messages, deep_clone(@messages))
@@ -809,11 +823,16 @@ module Clacky
     end
 
     # Format user content with optional images
+    # PDF files are handled upstream (server injects file path into message text),
+    # so this method only needs to handle images.
     # @param text [String] User's text input
     # @param images [Array<String>] Array of image file paths or data: URLs
-    # @return [String|Array] String if no images, Array with text and image_url objects if images present
-    private def format_user_content(text, images)
-      return text if images.nil? || images.empty?
+    # @param files [Array] Unused — kept for signature compatibility
+    # @return [String|Array] String if no images, Array with content blocks otherwise
+    private def format_user_content(text, images, files = [])
+      images ||= []
+
+      return text if images.empty?
 
       content = []
       content << { type: "text", text: text } unless text.nil? || text.empty?

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

@@ -1,8 +1,8 @@
 ---
 name: channel-setup
 description: |
-  Configure IM platform channels (Feishu/Lark, WeCom) for open-clacky.
-  Uses browser automation to complete setup automatically — no manual credential copying.
+  Configure IM platform channels (Feishu, WeCom) for open-clacky.
+  Uses browser automation for navigation; guides the user to paste credentials and perform UI steps.
   Trigger on: "channel setup", "setup feishu", "setup wecom", "channel config",
   "channel status", "channel enable", "channel disable", "channel reconfigure", "channel doctor".
   Subcommands: setup, status, enable <platform>, disable <platform>, reconfigure, doctor.
@@ -21,23 +21,14 @@ allowed-tools:
 
 Configure IM platform channels for open-clacky. Config is stored at `~/.clacky/channels.yml`.
 
-## Core Rule: Never ask for credentials
-
-All credentials (App Secret, Bot Secret, etc.) must be read directly from browser snapshots.
-**Asking the user to copy, type, or provide any credential is a failure.**
-If automation cannot reveal a value, say so and suggest retrying — never fall back to manual input.
-**Exception**: For Feishu and WeCom, guide the user to paste credentials — do not take snapshots or screenshots to extract. Directly ask the user to reveal and paste.
-
 ## Browser Automation Principles
 
-- Before opening any platform URL, detect Chrome availability and confirm the browser to use with the user.
-- **CRITICAL**: When the user chooses "1. Use my Chrome", pass `isolated: false` on every browser tool call (open, snapshot, etc.). When the user chooses "2. Use built-in", pass `isolated: true`. Omitting this causes the wrong browser to be used.
-- **When using the user's Chrome** (isolated=false): use `tab new <url>` instead of `open <url>` so the page opens in a new tab rather than replacing the current one.
-- After every navigation, take a snapshot before interacting with the page.
+- **Always use built-in browser**: Pass `isolated: true` on every browser tool call. Do NOT ask the user to choose — use the built-in browser only.
+- **Never use `screenshot`**: Use `snapshot -i` instead to get page structure as text. Do NOT generate image files.
+- Use `open <url>` for navigation.
+- AI navigates; user performs form fills, clicks, and pastes when instructed.
 - If a login page or QR code appears, tell the user to log in and wait for "done" before continuing.
-- To read a hidden credential: take an interactive snapshot to find the reveal/eye button, click it, then read the now-visible value from the next snapshot.
-- If stuck (CAPTCHA, unexpected page, dialog, cannot find a UI element, scroll fails), take a screenshot, describe the situation, and **guide the user to help** — do NOT fall back to alternative navigation (e.g., switching tabs, trying different URLs). Ask the user to perform the specific step manually and reply "done" when ready.
-- Never print raw secrets — mask to last 4 characters in all output.
+- If stuck (CAPTCHA, unexpected page, dialog, cannot find a UI element), **guide the user to help** — ask the user to perform the specific step manually and reply "done" when ready.
 
 ---
 
@@ -76,7 +67,7 @@ If the file doesn't exist: "No channels configured yet. Run `/channel-setup setu
 Ask:
 > Which platform would you like to connect?
 >
-> 1. Feishu / Lark
+> 1. Feishu
 > 2. WeCom (Enterprise WeChat)
 
 ---
@@ -85,33 +76,27 @@ Ask:
 
 #### Phase 1 — Open Feishu Open Platform
 
-1. Detect Chrome and confirm browser preference with the user. **Remember**: user chose 1 → pass `isolated: false`; chose 2 → pass `isolated: true` on every browser call.
-2. Ask (if not clear from context):
-   > Are you using Feishu (China) or Lark (International)?
-   > 1. Feishu — https://open.feishu.cn
-   > 2. Lark — https://open.larksuite.com
-3. Navigate to `https://open.feishu.cn/app` (or `/larksuite.com/app`).
-4. Take a snapshot. If a login page or QR code is shown, tell the user to log in and wait for "done".
-5. Confirm the app list is visible.
+1. Navigate: `open https://open.feishu.cn/app`. Pass `isolated: true`.
+2. Use `snapshot -i` to check page state. 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
 
-6. **Always create a new app** — do NOT reuse existing apps. Click "Create Enterprise Self-Built App", then create with name `Open Clacky` and description `AI assistant powered by open-clacky`.
+6. **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 open-clacky), then submit. Reply done." Wait for "done".
 
-#### Phase 3 — Get credentials
+#### Phase 3 — Enable Bot capability
 
-7. Navigate to the app's Credentials & Basic Info page.
-8. Do NOT take snapshots or screenshots. Directly guide the user: "Click the eye icon next to App Secret to reveal it. Copy App ID and App Secret, then paste here. Reply with: App ID: xxx, App Secret: xxx" (confirm back masked to last 4 chars).
+7. 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 — Enable Bot capability
+#### Phase 4 — Get credentials
 
-10. Navigate to Add App Capabilities in the left menu.
-11. Find the Bot capability card and add it. Confirm any dialog.
+8. Navigate to Credentials & Basic Info in the left menu.
+9. Guide the user: "Copy App ID and App Secret, then paste here. Reply with: App ID: xxx, App Secret: xxx" Wait for "done".
 
 #### Phase 5 — Add message permissions
 
-12. Navigate to Permission Management and open the bulk import dialog.
-13. **Clear the default/example content first** (select all, delete), then paste the following JSON:
+10. Navigate to Permission Management and open the bulk import dialog.
+11. 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.
 
 ```json
 {
@@ -126,45 +111,21 @@ Ask:
 }
 ```
 
-14. Confirm all three permissions appear as enabled.
+#### Phase 6 — Configure event subscription (Long Connection)
 
-#### Phase 6 — Configure event subscription
+**CRITICAL**: Feishu requires the long connection to be established *before* you can save the event config. The platform shows "No application connection detected, ensure long connection is established before saving" until `clacky server` is running and connected. Do NOT try to save until the connection is established.
 
-15. Navigate to Events & Callbacks.
-16. Change the subscription method to **Long Connection** and save.
-17. Add the event `im.message.receive_v1`.
+12. **Apply config and establish connection** — Run `curl -X POST http://localhost:7070/api/channels/feishu -H "Content-Type: application/json" -d '{"app_id":"...","app_secret":"...","domain":"..."}'`. The server hot-reloads the Feishu adapter and establishes the WebSocket.
+13. **Wait for connection** — Wait until the log shows `[feishu-ws] WebSocket connected ✅`.
+14. **Navigate to Events & Callbacks** — Then guide the user: "Select 'Long Connection' mode. Click Save. Then click Add Event, type `im.message.receive_v1` in the search box, select it, click Add. Reply done." Wait for "done".
 
 #### Phase 7 — Publish the app
 
-18. Navigate to Version Management & Release, create a new version (e.g. `1.0.0`), and publish.
-19. Note: personal accounts publish immediately; enterprise accounts require admin approval — tell the user if this applies.
-
-#### Phase 8 — Allowed users (optional)
+15. Navigate to Version Management & Release. Then guide the user: "Create a new version, fill in version (e.g. 1.0.0) and update description (e.g. Initial release for Open Clacky), then publish. Reply done." Wait for "done".
 
-20. Ask:
-    > Do you want to restrict which Feishu users can send tasks to the AI?
-    > Reply "skip" to allow everyone, or "yes" to configure a whitelist.
-21. If "yes":
-    - Tell the user to send any message to the Open Clacky bot in Feishu, then reply "done".
-    - Navigate to Log Search → Event Log, find the latest `im.message.receive_v1` event, and read `sender.sender_id.open_id` (format `ou_xxx`) directly from the page.
-    - Repeat for additional users if needed.
+#### Phase 8 — Finalize config and validate
 
-#### Phase 9 — Save config and validate
-
-Write `~/.clacky/channels.yml` (merge with existing content, never overwrite other platforms):
-
-```yaml
-channels:
-  feishu:
-    enabled: true
-    app_id: <from user paste>
-    app_secret: <from user paste>
-    domain: https://open.feishu.cn   # or https://open.larksuite.com
-    # allowed_users:                 # omit if not configured
-    #   - ou_xxx
-```
-
-Run `chmod 600 ~/.clacky/channels.yml`.
+Config was applied in step 12 (via API).
 
 Validate:
 ```bash
@@ -174,57 +135,23 @@ curl -s -X POST "${DOMAIN}/open-apis/auth/v3/tenant_access_token/internal" \
 ```
 Check for `"code":0`. If it fails, explain and offer to retry.
 
-On success: "✅ Feishu channel configured. Restart `clacky server` to activate."
+On success: "✅ Feishu channel configured. The channel is already active."
 
 ---
 
 ### WeCom setup
 
-First ask: "Are you an admin of your WeCom enterprise (can log in to work.weixin.qq.com)? Reply 1 or 2."
-- If using AskFollowupQuestion: pass options as `Yes — I am an enterprise admin` and `No — I am not an admin` (no leading numbers; the tool will add 1. and 2.).
-- **1** → use Admin Console flow (browser automation).
-- **2** → use Client flow (guide user in WeCom desktop client, then ask for Bot ID and Secret).
-
----
-
-#### Admin Console flow (user has admin access)
-
-**Principle**: Do NOT take snapshots or screenshots to inspect the UI. Directly guide the user through each step. For Bot ID and Secret, guide the user to paste them — do NOT try to extract from the page.
+1. Navigate: `open https://work.weixin.qq.com/wework_admin/frame#/aiHelper/create`. Pass `isolated: true`.
+2. Use `snapshot -i` to check page state. If a login page or QR code is shown, tell the user to log in and wait for "done".
+3. Steps 3–7: Do NOT take snapshots. 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'. In the scope dialog, select the top-level company node (or specific users/departments). Click Confirm. Reply done." Wait for "done".
+5. Guide the user: "If Secret is not visible, click 'Get Secret'. Copy Bot ID and Secret **before** clicking Save — do NOT click 'Get Secret' again after copying (it invalidates the previous secret). Paste here. Reply with: Bot ID: xxx, Secret: xxx" Wait for "done".
+6. Guide the user: "Click Save. In the dialog, enter name (e.g. Open Clacky) and description (e.g. AI assistant powered by open-clacky). Click Confirm. Click Save again. Reply done." Wait for "done".
+7. **Apply config and hot-reload** — Parse credentials from step 5. Trim leading/trailing whitespace from bot_id and secret. Run `curl -X POST http://localhost:7070/api/channels/wecom -H "Content-Type: application/json" -d '{"bot_id":"...","secret":"..."}'`. Ensure bot_id (starts with `aib`) and secret (longer string) are not swapped.
 
-1. Detect Chrome and confirm browser preference with the user (if not already done). **Remember**: user chose 1 → pass `isolated: false` when calling browser; chose 2 → pass `isolated: true`.
-2. Navigate directly to `https://work.weixin.qq.com/wework_admin/frame#/aiHelper/create` (use `tab new <url>` when isolated=false). Pass the same `isolated` value on every browser call.
-3. Directly guide the user: "If you see a login page or QR code, log in. When the create page is visible, reply done." Wait for "done".
-4. Guide the user: "Scroll to the bottom of the right panel and click 'API mode creation', then reply done." Wait for "done".
-5. Guide the user: "In the scope dialog, select the top-level company node to allow all members, or select specific users/departments if you prefer. Click Confirm, then reply done." Wait for "done".
-6. Guide the user: "If the Secret is not yet visible, click 'Get Secret'. When both Bot ID and Secret are visible, copy them and paste here. Reply with: Bot ID: xxx, Secret: xxx" (confirm back masked to last 4 chars).
-7. Guide the user: "Click Save. In the dialog, enter name 'Open Clacky' and description 'AI assistant powered by open-clacky', click Confirm, then reply done." Wait for "done".
-8. Write config and run `chmod 600 ~/.clacky/channels.yml`.
-
----
-
-#### Client flow (user is not admin; cannot access admin console)
-
-Guide the user to operate in the **WeCom desktop client** (Workbench). No browser automation needed.
-
-1. Guide the user: "Open the WeCom desktop client → Workbench → Smart Bot → "Create Bot". Reply done when you see the creation page." Wait for "done".
-2. Guide the user: "Scroll to the bottom of the page and click 'API Mode'. Reply done." Wait for "done".
-3. Guide the user: "The Bot ID appears on the right side. Under 'API Configuration', find the Secret row and click 'Click to Reveal' if needed. Copy both and paste here. Reply with: Bot ID: xxx, Secret: xxx" (confirm back masked to last 4 chars).
-4. Guide the user: "Fill in name 'Open Clacky' and description 'AI assistant powered by open-clacky', click Save (or Confirm), then reply done." Wait for "done".
-5. Write `~/.clacky/channels.yml` and run `chmod 600 ~/.clacky/channels.yml`.
-
----
-
-#### Save config (both flows)
-
-```yaml
-channels:
-  wecom:
-    enabled: true
-    bot_id: <extracted or entered>
-    secret: <extracted or entered>
-```
+On success: "✅ WeCom channel configured."
 
-On success: "✅ WeCom channel configured. Restart `clacky server` to activate. To use the bot: WeCom client → Workbench → Management → click the bot details → Go to use."
+On success: "✅ WeCom channel configured. To use the bot: WeCom client → Contacts → select Smart Bot to see the newly created bot.".
 
 ---
 

data/lib/clacky/default_skills/onboard/SKILL.md

@@ -14,22 +14,72 @@ All structured input is gathered through `request_user_feedback` cards — no fr
 
 ## Steps
 
+### 0. Detect language
+
+The user's language was set during the onboarding intro screen. The skill is invoked with
+a `lang:` argument in the slash command, e.g. `/onboard lang:zh` or `/onboard lang:en`.
+
+Check the invocation message for `lang:zh` or `lang:en`:
+- If `lang:zh` is present → conduct the **entire** onboard in **Chinese**, write SOUL.md & USER.md in Chinese.
+- Otherwise (or if missing) → use **English** throughout.
+
+If the `lang:` argument is absent, infer from the user's first reply; default to English.
+
 ### 1. Greet the user
 
-Send a short, warm welcome message (2–3 sentences). Detect the user's language from any
-text they've already typed; default to English. Do NOT ask any questions yet.
+Send a short, warm welcome message (2–3 sentences). Use the language determined in Step 0.
+Do NOT ask any questions yet.
 
 Example (English):
 > Hi! I'm your personal assistant ⚡
 > Let's take 30 seconds to personalize your experience — I'll ask just a couple of quick things.
 
-### 2. Collect AI personality (card)
+Example (Chinese):
+> 嗨！我是你的专属 AI 助手 ⚡
+> 只需 30 秒完成个性化设置，我会问你两个简单问题。
+
+### 2. Ask the user's name (card)
+
+Call `request_user_feedback` to get the user's preferred name.
+
+If `lang == "zh"`, use:
+```json
+{
+  "question": "先告诉我，我该怎么称呼你？"
+}
+```
+
+Otherwise (English):
+```json
+{
+  "question": "First, what should I call you?"
+}
+```
+
+Store the reply as `user.name` (default `"there"` for English, `"朋友"` for Chinese if blank).
+
+### 3. Collect AI personality (card)
 
-Call `request_user_feedback` with a card to set the assistant's name and personality:
+Call `request_user_feedback` with a card to set the assistant's personality.
+Address the user by `user.name` in the question.
+
+If `lang == "zh"`, use:
+```json
+{
+  "question": "好的，[user.name]！来设置一下你的助手吧。",
+  "options": [
+    "🎯 专业型 — 精准、结构化、不废话",
+    "😊 友好型 — 热情、鼓励、像一位博学的朋友",
+    "🎨 创意型 — 富有想象力，善用比喻，充满热情",
+    "⚡ 简洁型 — 极度简短，用要点，信噪比最高"
+  ]
+}
+```
 
+Otherwise (English):
 ```json
 {
-  "question": "First, let's set up your assistant.",
+  "question": "Nice to meet you, [user.name]! Now let's set up your assistant.",
   "options": [
     "🎯 Professional — Precise, structured, minimal filler",
     "😊 Friendly — Warm, encouraging, like a knowledgeable friend",
@@ -39,48 +89,49 @@ Call `request_user_feedback` with a card to set the assistant's name and persona
 }
 ```
 
-Also ask for a custom name in the same message if the platform supports a text field;
-otherwise follow up with: "What should I call myself? (leave blank to keep 'Clacky')"
-
 Map the chosen option to a personality key:
 - Option 1 → `professional`
 - Option 2 → `friendly`
 - Option 3 → `creative`
 - Option 4 → `concise`
 
-Store: `ai.name` (default `"Clacky"`), `ai.personality`.
+Store: `ai.personality`.
 
-### 3. Collect user profile (card)
+### 4. Collect user profile (card)
 
-Call `request_user_feedback` again:
+Call `request_user_feedback` again.
 
+If `lang == "zh"`, use:
 ```json
 {
-  "question": "Now a bit about you — all optional, skip anything you like.",
+  "question": "再简单了解一下你自己吧 —— 全部可选，随便填：\n• 职业\n• 最希望用 AI 做什么\n• 社交 / 作品链接（GitHub、微博、个人网站等）—— AI 会读取公开信息来了解你",
   "options": []
 }
 ```
 
-Ask for the following in the question text (as labeled fields description, since options is empty):
-- Name / nickname
-- Occupation
-- What you want to use AI for most
-- Social / portfolio links (GitHub, Twitter/X, personal site…) — AI will read them to learn about you
+Otherwise (English):
+```json
+{
+  "question": "Now a bit about you — all optional, skip anything you like.\n• Occupation\n• What you want to use AI for most\n• Social / portfolio links (GitHub, Twitter/X, personal site…) — AI will read them to learn about you",
+  "options": []
+}
+```
 
 Parse the user's reply as free text; extract whatever they provide.
 
-### 4. Learn from links (if any)
+### 5. Learn from links (if any)
 
 For each URL the user provided, use the `web_search` tool or fetch the page to read
 publicly available info: bio, projects, tech stack, interests, writing style, etc.
 Note key facts for the USER.md. Skip silently if a URL is unreachable.
 
-### 5. Write SOUL.md
+### 6. Write SOUL.md
 
 Write to `~/.clacky/agents/SOUL.md`.
 
 Use `ai.name` and `ai.personality` to shape the content.
-If the user's language appears to be non-English (detected from their replies), write in that language.
+Write in the language determined in Step 0 (`zh` → Chinese, otherwise English).
+If `lang == "zh"`, add a line: `**始终用中文回复用户。**` near the top of the Identity section.
 
 **Personality style guide:**
 
@@ -113,7 +164,7 @@ I am [AI Name], a personal assistant and technical co-founder.
 [2–3 sentences about how I approach tasks, matching the personality.]
 ```
 
-### 6. Write USER.md
+### 7. Write USER.md
 
 Write to `~/.clacky/agents/USER.md`.
 
@@ -121,7 +172,7 @@ Write to `~/.clacky/agents/USER.md`.
 # User Profile
 
 ## About
-- **Name**: [nickname or "Not provided"]
+- **Name**: [user.name, or "Not provided"]
 - **Occupation**: [or "Not provided"]
 - **Primary Goal**: [or "Not provided"]
 
@@ -133,9 +184,31 @@ Write to `~/.clacky/agents/USER.md`.
 [1–2 sentences tailored to the user's goal and background.]
 ```
 
-### 7. Confirm and close
+### 7b. Write USER.md (Chinese version, if applicable)
+
+If `lang == "zh"`, write `~/.clacky/agents/USER.md` in Chinese:
+
+```markdown
+# 用户档案
+
+## 基本信息
+- **姓名**: [user.name，未填则写「未填写」]
+- **职业**: [未填则写「未填写」]
+- **主要目标**: [未填则写「未填写」]
+
+## 背景与兴趣
+[如有链接：3–5 条从公开信息中提取的要点。否则：写「暂无更多背景信息。」]
+
+## 如何最好地帮助用户
+[1–2 句话，根据用户目标和背景量身定制。]
+```
+
+### 8. Confirm and close
+
+If `lang == "zh"`, reply:
+> 全部设置完成！我已保存你的偏好。关掉这个对话，开启一个新对话就可以开始了 —— 尽情享用吧！🚀
 
-Reply with a single short message, e.g.:
+Otherwise:
 > All set! I've saved your preferences. Feel free to close this tab and start a fresh session — enjoy! 🚀
 
 Do NOT open a new session — the UI handles navigation after the skill finishes.