openclacky 0.9.19 → 0.9.21

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b959a76ace0015ec6279b1572afa3e961d862d9c856c9fdecc98f72d9e190e59
-  data.tar.gz: 53cc27fce3b47e83cb428955eb6591d53acc148cdab55721c7c32330b351fed0
+  metadata.gz: d48d1b62badf0b608e9f6dc6cacb6b0d2c8f92263a8df77d64f6c63ee26e3580
+  data.tar.gz: f4abb3c3aa7dc140a91622135c4eaff7dfbad66bca6908abfb3c76ab7c183629
 SHA512:
-  metadata.gz: 5b0d27875497a290060cabfc409c5b8a18b90b95c8bec82157f8d1f8e63a25fc78e3d52bff8bcbf3bd9969f8e65090137dc7ce7b394ac35779412a51534a166e
-  data.tar.gz: 2b08d76c821e84c7196b4bc6364323879669259895b30cb803e01e70c49a59f44a40f5f607f8a4d3e10a96bfaa47167c03ed991fcebe6a5dcb44d099b18bdccd
+  metadata.gz: acfdcca20845b40c076f1974dde40d5d62f194af03c14541a98c02c5fd431790df3e811ac17a0d35276938bb5475a53c3e22e8c8b9f56b87d0637f7a5168d7c5
+  data.tar.gz: a3ea45c455a7591917801963bb4a08587ea1ab24173d42cb8d1d2718dbf0a17fdf40e11296840dc107863d98e4aa1a2dad8008542b6214a10bda9d575fec7715

data/CHANGELOG.md

@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.21] - 2026-03-30
+
+### Fixed
+- **Feishu channel setup compatibility with v2.6**: fixed Ruby 3.1 syntax incompatibility in the Feishu setup script that caused failures on newer Feishu API versions
+
+### Improved
+- **skill-creator YAML validation**: added frontmatter schema validation for skill files, catching malformed skill definitions before they cause runtime errors
+
+### More
+- Removed `install_simple.sh` (consolidated into `install.sh`)
+
+## [0.9.20] - 2026-03-30
+
+### Added
+- **SSL error retry**: LLM API calls now automatically retry on SSL errors (same as other network failures — up to 10 retries with 5s delay)
+
+### Fixed
+- **Brand wrapper not found under root**: the install script now places the brand command wrapper in the same directory as the `openclacky` binary, so it is always on PATH regardless of whether running as root or a normal user
+
+### Improved
+- **Cron task management refactored to API**: cron task CRUD operations now go through the HTTP API instead of running ad-hoc Ruby scripts, making the scheduler more reliable and easier to maintain
+- **UTF-8 encoding fix for browser tool on Windows**: browser command output with non-ASCII characters no longer causes encoding errors
+
+### More
+- Installer no longer adds `~/.local/bin` to PATH (wrapper now colocated with gem binary, making the extra PATH entry unnecessary)
+- Brand install tips in Windows PowerShell installer
+
 ## [0.9.19] - 2026-03-29
 
 ### Added

data/docs/c-end-user-positioning.md

@@ -0,0 +1,64 @@
+# C-End User Positioning
+
+> Date: 2026-03-30
+
+---
+
+## Market Context
+
+The "OpenClaw ecosystem" has exploded in 2026. Key players:
+
+- **OpenClaw** — open-source, self-hosted, community Skills. Designed for technical users who configure everything themselves.
+- **QClaw** — Tencent's fork. Bundled Kimi model, WeChat binding. Mass-market but Tencent-ecosystem only.
+- **Others** (Wukong, etc.) — same lane.
+
+OpenClaw has 5,700+ Skills, but almost all are open-source, free, and easily copied. The ecosystem lacks **expertise-backed, production-grade Skills worth paying for**.
+
+---
+
+## Who openclacky Is For
+
+**Ordinary users, not technical geeks.**
+
+The target user knows OpenClaw exists, has heard about "raising a lobster", but can't or doesn't want to:
+- configure Docker / environment / webhooks
+- manage their own API keys without knowing what they'll spend
+- troubleshoot when a long task breaks halfway
+
+They want to use a lobster built by an expert (a lawyer, a trader, an SEO specialist) — not build one themselves.
+
+> Core insight: **OpenClaw is built for people who create Skills. openclacky is built for people who use them.**
+
+---
+
+## Why openclacky Over OpenClaw: 3 Core Reasons
+
+### 1. Zero-friction IM setup — the strongest differentiator
+
+OpenClaw requires users to manually configure webhooks, tokens, and config files to connect WeChat / Feishu / WeCom. High technical barrier, most ordinary users give up.
+
+openclacky uses **AI-automated channel setup**: one sentence, and the AI configures the IM connection for you — no plugins, no docs, no engineering knowledge required. This is a genuine technical moat.
+
+### 2. Built for China, natively
+
+- No VPN required, no overseas credit card
+- WeChat / Feishu / WeCom are the primary daily tools for Chinese users — openclacky treats them as first-class citizens
+- Supports domestic models (DeepSeek, Kimi, etc.) out of the box
+- QClaw is domestic too, but locked to Tencent's ecosystem and model choices
+
+### 3. Cost transparency and long-task reliability
+
+- Real-time token cost tracking — users always know what they're spending
+- Automatic compression (up to 90% savings via Insert-then-Compress + Prompt Caching)
+- Long tasks don't break: sub-agent isolation + Time Machine architecture keeps context intact
+
+---
+
+## The User Progression
+
+```
+Can use it  →  Dare to use it  →  Keep using it
+(zero setup)   (cost clarity)     (tasks don't break)
+```
+
+Each of the 3 reasons maps directly to one stage of this progression.

data/lib/clacky/agent/llm_caller.rb

@@ -34,7 +34,7 @@ module Clacky
             max_tokens: @config.max_tokens,
             enable_caching: @config.enable_prompt_caching
           )
-        rescue Faraday::ConnectionFailed, Faraday::TimeoutError, Errno::ECONNREFUSED, Errno::ETIMEDOUT => e
+        rescue Faraday::ConnectionFailed, Faraday::TimeoutError, Faraday::SSLError, Errno::ECONNREFUSED, Errno::ETIMEDOUT => e
           @ui&.clear_progress
           retries += 1
           if retries <= max_retries

data/lib/clacky/default_skills/channel-setup/feishu_setup.rb

@@ -71,9 +71,9 @@ BOT_PERMISSIONS = %w[
 # Logging helpers
 # ---------------------------------------------------------------------------
 
-def step(msg)  = puts("[feishu-setup] #{msg}")
-def ok(msg)    = puts("[feishu-setup] ✅ #{msg}")
-def warn(msg)  = puts("[feishu-setup] ⚠️  #{msg}")
+def step(msg);  puts("[feishu-setup] #{msg}"); end
+def ok(msg);    puts("[feishu-setup] ✅ #{msg}"); end
+def warn(msg);  puts("[feishu-setup] ⚠️  #{msg}"); end
 def fail!(msg)
   puts("[feishu-setup] ❌ #{msg}")
   exit 1
@@ -501,7 +501,7 @@ def run_setup(browser, api)
     id   = s["id"].to_s
     name_to_id[name] = id if name && !id.empty?
   end
-  ids     = BOT_PERMISSIONS.filter_map { |n| name_to_id[n] }
+  ids     = BOT_PERMISSIONS.map { |n| name_to_id[n] }.compact
   missing = BOT_PERMISSIONS.reject { |n| name_to_id.key?(n) }
   warn "#{missing.size} permissions not matched: #{missing.join(", ")}" unless missing.empty?
   fail! "No permission IDs matched. API response keys: #{name_to_id.keys.first(5).inspect}" if ids.empty?

data/lib/clacky/default_skills/cron-task-creator/SKILL.md

@@ -17,21 +17,14 @@ Storage:
   ~/.clacky/schedules.yml        # All scheduled plans (YAML list)
   ~/.clacky/logger/clacky-*.log  # Execution logs (daily rotation)
 
-WebUI Task Panel (Clacky Web Interface):
-  - Automatically reads tasks/ + schedules.yml and renders the task list
-  - Each row shows task name, cron expression, and content preview
-  - Action buttons: ▶ Run (execute now), ✎ Edit (edit in session), ✕ (delete)
-  - Run button triggers POST /api/tasks/run → executes task in a new session
-
-API Endpoints (available when clacky server is running):
-  GET    /api/tasks              → list all tasks
-  POST   /api/tasks              → create task {name, content}
-  GET    /api/tasks/:name        → get task content
-  DELETE /api/tasks/:name        → delete task
-  POST   /api/tasks/run          → run immediately {name}
-  GET    /api/schedules          → list all schedules
-  POST   /api/schedules          → create schedule {name, task, cron}
-  DELETE /api/schedules/:name    → delete schedule
+API Base: http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}
+
+Cron-Tasks API (unified — manages task file + schedule together):
+  GET    /api/cron-tasks              → list all cron tasks with schedule info
+  POST   /api/cron-tasks              → create task + schedule {name, content, cron, enabled?}
+  PATCH  /api/cron-tasks/:name        → update {content?, cron?, enabled?}
+  DELETE /api/cron-tasks/:name        → delete task file + schedule
+  POST   /api/cron-tasks/:name/run    → execute immediately (creates a new session)
 ```
 
 ## Cron Expression Quick Reference
@@ -54,10 +47,11 @@ Field order: `minute hour day-of-month month day-of-week`
 
 ### 1. LIST — Show all tasks
 
-When user asks "what tasks do I have", "list scheduled tasks", etc.:
+```bash
+curl -s http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/cron-tasks
+```
 
-1. Run `ruby ~/.clacky/skills/cron-task-creator/scripts/list_tasks.rb`
-2. Display results: task name, cron schedule, enabled status, last run status
+Display each task: name, cron schedule, enabled status, content preview.
 
 If no tasks exist, inform the user and offer to create one or show templates.
 
@@ -69,15 +63,14 @@ If no tasks exist, inform the user and offer to create one or show templates.
 
 **Step 1: Gather required info** (only ask for what's missing)
 - What should the task DO? (goal, behavior, output format)
-- How often should it run? (or is it manual-only?)
+- How often should it run? (or is it manual-only without a schedule?)
 - Any specific parameters? (URLs, file paths, output location, language)
 
 **Step 2: Generate task name**
 - Rule: only `[a-z0-9_-]`, lowercase, no spaces
 - Examples: `daily_report`, `price_monitor`, `weekly_summary`
 
-**Step 3: Write the task prompt file**
-Path: `~/.clacky/tasks/<name>.md`
+**Step 3: Write the task prompt**
 
 The prompt must be:
 - **Self-contained**: the agent running it has zero prior context — include everything needed
@@ -85,7 +78,7 @@ The prompt must be:
 - **Detailed**: include URLs, file paths, output format, language, expected output location
 
 Good task prompt example:
-```markdown
+```
 You are a price monitoring assistant. Complete the following task:
 
 ## Goal
@@ -100,14 +93,17 @@ Check the current BTC price on CoinGecko, compare with yesterday's price, and lo
 Execute immediately.
 ```
 
-**Step 4: Write file and add schedule**
+**Step 4: Create via API**
 
 ```bash
-# Write task file
-ruby ~/.clacky/skills/cron-task-creator/scripts/manage_task.rb create "<name>" "<content>"
-
-# Add schedule (if applicable)
-ruby ~/.clacky/skills/cron-task-creator/scripts/manage_schedule.rb add "<name>" "<task_name>" "<cron_expr>"
+curl -s -X POST http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/cron-tasks \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "task_name",
+    "content": "task prompt content...",
+    "cron": "0 9 * * *",
+    "enabled": true
+  }'
 ```
 
 **Step 5: Confirm creation**
@@ -116,7 +112,6 @@ ruby ~/.clacky/skills/cron-task-creator/scripts/manage_schedule.rb add "<name>"
 ✅ Task created successfully!
 
 📋 Task name: daily_standup
-📄 File: ~/.clacky/tasks/daily_standup.md
 ⏰ Schedule: Weekdays at 09:00 (cron: 0 9 * * 1-5)
 
 View and manage this task in the Clacky WebUI → Tasks panel. Click ▶ Run to execute immediately.
@@ -126,24 +121,27 @@ View and manage this task in the Clacky WebUI → Tasks panel. Click ▶ Run to
 
 ### 3. EDIT — Modify an existing task
 
-When the user wants to change task content, cron schedule, or rename:
+**Step 1**: Identify the task (if unclear, LIST first and ask)
 
-**Step 1**: Identify the task to modify (if unclear, LIST first and ask)
+**Step 2**: Show current state via LIST or ask user to confirm
 
-**Step 2**: Show current state (first 10 lines + cron expression)
-
-**Step 3**: Determine what to change
-- Prompt only → rewrite `~/.clacky/tasks/<name>.md`
-- Schedule only → update `cron` field in `schedules.yml`
-- Both → do both
-- Rename → rename .md file + update schedules.yml
+**Step 3**: Update via API
 
 ```bash
-# Update task content
-ruby ~/.clacky/skills/cron-task-creator/scripts/manage_task.rb update "<name>" "<new_content>"
-
-# Update cron schedule
-ruby ~/.clacky/skills/cron-task-creator/scripts/manage_schedule.rb update "<schedule_name>" "<new_cron>"
+# Update content only
+curl -s -X PATCH http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/cron-tasks/task_name \
+  -H "Content-Type: application/json" \
+  -d '{"content": "new prompt content..."}'
+
+# Update cron schedule only
+curl -s -X PATCH http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/cron-tasks/task_name \
+  -H "Content-Type: application/json" \
+  -d '{"cron": "0 8 * * 1-5"}'
+
+# Update both
+curl -s -X PATCH http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/cron-tasks/task_name \
+  -H "Content-Type: application/json" \
+  -d '{"content": "...", "cron": "0 8 * * 1-5"}'
 ```
 
 **Step 4**: Confirm changes
@@ -151,7 +149,6 @@ ruby ~/.clacky/skills/cron-task-creator/scripts/manage_schedule.rb update "<sche
 ```
 ✅ Task updated!
 📋 daily_standup
-  Prompt: updated ✓
   Schedule: 0 9 * * 1-5 → 0 8 * * 1-5 (now weekdays at 08:00)
 ```
 
@@ -160,7 +157,15 @@ ruby ~/.clacky/skills/cron-task-creator/scripts/manage_schedule.rb update "<sche
 ### 4. ENABLE / DISABLE — Toggle a task
 
 ```bash
-ruby ~/.clacky/skills/cron-task-creator/scripts/manage_schedule.rb toggle "<schedule_name>" true|false
+# Disable
+curl -s -X PATCH http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/cron-tasks/task_name \
+  -H "Content-Type: application/json" \
+  -d '{"enabled": false}'
+
+# Enable
+curl -s -X PATCH http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/cron-tasks/task_name \
+  -H "Content-Type: application/json" \
+  -d '{"enabled": true}'
 ```
 
 Confirm:
@@ -180,15 +185,22 @@ Always confirm before deleting (unless the user has explicitly said to delete):
 ```
 
 ```bash
-ruby ~/.clacky/skills/cron-task-creator/scripts/manage_task.rb delete "<name>"
+curl -s -X DELETE http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/cron-tasks/task_name
 ```
 
 ---
 
 ### 6. HISTORY — View run history
 
+Read the daily log files directly:
+
 ```bash
-ruby ~/.clacky/skills/cron-task-creator/scripts/task_history.rb "<task_name>"
+grep "task_name" ~/.clacky/logger/clacky-$(date +%Y-%m-%d).log | tail -20
+```
+
+Or search across recent days:
+```bash
+grep -h "task_name" ~/.clacky/logger/clacky-*.log | tail -30
 ```
 
 Display format:
@@ -198,24 +210,21 @@ Display format:
 Mar 10  19:00  ❌ Failed  — JSON::ParserError: unexpected end of input
 Mar 09  19:00  ✅ Success — took 1m 42s
 Mar 08  19:00  ✅ Success — took 2m 10s
-Mar 07  19:00  ⚠️ Skipped — (task was disabled)
-
-Recent error:
-  JSON::ParserError at line 226
-  Possible cause: API response was truncated or empty
 ```
 
 ---
 
 ### 7. RUN NOW — Execute immediately
 
+```bash
+curl -s -X POST http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/cron-tasks/task_name/run
 ```
-▶️ Go to the Clacky WebUI → Tasks panel, find the task, and click ▶ Run.
 
-The task will execute in a new session. You can watch it run in real time via the WebUI.
+This creates a new session. Tell the user:
+```
+▶️ Task started in a new session.
+   View it in the Clacky WebUI → Sessions panel.
 ```
-
-If the user wants to run the task in the current session, read the task file and execute the instructions directly.
 
 ---
 
@@ -243,8 +252,6 @@ Tell me which one interests you, or describe your own use case!
 ## Important Notes
 
 - Task names: only `[a-z0-9_-]`, no spaces, no uppercase
-- When modifying `schedules.yml`: always read → modify → write back the full file (never append directly)
 - Task prompt files must be **self-contained** — the executing agent has no prior memory
 - Clacky server must be running for cron to trigger automatically (checked every minute)
 - The WebUI Task Panel is the preferred interface for managing tasks — always remind the user to check it after changes
-- Path expansion: always use absolute paths, expand `~` to the actual home directory

data/lib/clacky/default_skills/skill-creator/SKILL.md

@@ -86,6 +86,12 @@ Components to fill in:
 >
 > **YAML description gotcha**: If the description contains `word: value` patterns (colons followed by space), YAML treats them as key-value pairs and the frontmatter parse fails silently. Always wrap description values in single quotes. Avoid embedded double-quotes inside single-quoted strings (use rephrasing instead).
 
+> **After writing SKILL.md — always validate and auto-fix**: Run this immediately after creating or updating any skill file:
+> ```bash
+> ruby SKILL_DIR/scripts/validate_skill_frontmatter.rb /path/to/new-skill/SKILL.md
+> ```
+> The script validates the YAML frontmatter and auto-fixes common issues (unquoted descriptions, multi-line block scalars with colons). If it prints `OK:` — you're done. If it prints `Auto-fixed and saved` — it repaired the file automatically. If it prints `ERROR` — manual fix required.
+
 ### Skill Writing Guide
 
 #### Anatomy of a Skill

data/lib/clacky/default_skills/skill-creator/scripts/validate_skill_frontmatter.rb

@@ -0,0 +1,143 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# validate_skill_frontmatter.rb
+#
+# Validates and auto-fixes the YAML frontmatter of a SKILL.md file.
+#
+# Usage:
+#   ruby validate_skill_frontmatter.rb <path/to/SKILL.md>
+#
+# What it does:
+#   1. Parses the frontmatter between --- delimiters
+#   2. If YAML is invalid OR description is not a plain String:
+#      - Extracts name/description via regex fallback
+#      - Re-wraps description in single quotes (collapsed to one line)
+#      - Rewrites the frontmatter in the file
+#   3. Exits 0 on success (with or without auto-fix), 1 on unrecoverable error
+
+require "yaml"
+
+path = ARGV[0]
+
+if path.nil? || path.strip.empty?
+  warn "Usage: ruby validate_skill_frontmatter.rb <path/to/SKILL.md>"
+  exit 1
+end
+
+unless File.exist?(path)
+  warn "File not found: #{path}"
+  exit 1
+end
+
+content = File.read(path)
+
+# Extract frontmatter block
+fm_match = content.match(/\A(---\n)(.*?)(\n---[ \t]*\n?)/m)
+unless fm_match
+  warn "ERROR: No frontmatter block found in #{path}"
+  exit 1
+end
+
+prefix      = fm_match[1]          # "---\n"
+yaml_raw    = fm_match[2]          # raw YAML text
+suffix      = fm_match[3]          # "\n---\n"
+body        = content[fm_match.end(0)..]  # rest of file after frontmatter
+
+# Attempt normal YAML parse
+parse_ok = false
+data = nil
+begin
+  data = YAML.safe_load(yaml_raw) || {}
+  parse_ok = data["description"].is_a?(String)
+rescue Psych::Exception => e
+  warn "YAML parse error: #{e.message}"
+end
+
+if parse_ok
+  puts "OK: name=#{data['name'].inspect} description_length=#{data['description'].length}"
+  exit 0
+end
+
+# --- Auto-fix ---
+puts "Frontmatter invalid or description broken — attempting auto-fix..."
+
+# Regex fallback: extract name and description lines
+name_match = yaml_raw.match(/^name:\s*(.+)$/)
+unless name_match
+  warn "ERROR: Cannot extract 'name' field from frontmatter. Manual fix required."
+  exit 1
+end
+name_value = name_match[1].strip.gsub(/\A['"]|['"]\z/, "")
+
+# description may be:
+#   description: some text           (unquoted)
+#   description: 'some text'         (single-quoted)
+#   description: "some text"         (double-quoted)
+#   description: first line\n  continuation  (multi-line block scalar)
+desc_match = yaml_raw.match(/^description:\s*(.+?)(?=\n[a-z]|\z)/m)
+unless desc_match
+  warn "ERROR: Cannot extract 'description' field from frontmatter. Manual fix required."
+  exit 1
+end
+
+raw_desc = desc_match[1].strip
+
+# Strip existing outer quotes if present (simple single-line quoted values)
+if raw_desc.start_with?("'") && raw_desc.end_with?("'")
+  raw_desc = raw_desc[1..-2]
+elsif raw_desc.start_with?('"') && raw_desc.end_with?('"')
+  raw_desc = raw_desc[1..-2]
+end
+
+# Collapse multi-line: strip leading whitespace from continuation lines
+description_value = raw_desc.gsub(/\n\s+/, " ").strip
+
+# Escape any single quotes inside the description value
+description_value_escaped = description_value.gsub("'", "''")
+
+# Extract all other frontmatter lines (everything except name: and description:)
+other_lines = yaml_raw.each_line.reject do |line|
+  line.match?(/^(name|description):/) || line.match?(/^\s+\S/) && yaml_raw.match?(/^description:.*\n(\s+.+\n)*/m)
+end
+
+# More precise: collect lines that are not part of the name/description block
+remaining = []
+skip_continuation = false
+yaml_raw.each_line do |line|
+  if line.match?(/^(name|description):/)
+    skip_continuation = true
+    next
+  end
+  if skip_continuation && line.match?(/^\s+\S/)
+    next  # continuation of a multi-line block value
+  end
+  skip_continuation = false
+  remaining << line unless line.strip.empty? && remaining.empty?
+end
+
+# Rebuild frontmatter
+fixed_fm_lines = []
+fixed_fm_lines << "name: #{name_value}"
+fixed_fm_lines << "description: '#{description_value_escaped}'"
+remaining.each { |l| fixed_fm_lines << l.chomp }
+
+# Remove trailing blank lines from remaining
+fixed_fm = fixed_fm_lines.join("\n").strip
+
+new_content = "#{prefix}#{fixed_fm}#{suffix}#{body}"
+
+File.write(path, new_content)
+puts "Auto-fixed and saved: #{path}"
+
+# Final verification
+begin
+  verify_content = File.read(path)
+  verify_match = verify_content.match(/\A---\n(.*?)\n---/m)
+  verify_data = YAML.safe_load(verify_match[1])
+  raise "description not a String" unless verify_data["description"].is_a?(String)
+  puts "OK: name=#{verify_data['name'].inspect} description_length=#{verify_data['description'].length}"
+rescue => e
+  warn "ERROR: Auto-fix failed, manual intervention required: #{e.message}"
+  exit 1
+end