codelark 0.1.0

package/scripts/supervisor-windows.ps1

@@ -0,0 +1,481 @@
+<#
+.SYNOPSIS
+  Windows daemon manager for CodeLark bridge.
+
+.DESCRIPTION
+  Manages the bridge process on Windows.
+  Preferred: WinSW or NSSM wrapping as a Windows Service.
+  Fallback:  Start-Process with hidden window + PID tracking.
+
+  Usage:
+    powershell -File scripts\daemon.ps1 start
+    powershell -File scripts\daemon.ps1 stop
+    powershell -File scripts\daemon.ps1 status
+    powershell -File scripts\daemon.ps1 logs [N]
+    powershell -File scripts\daemon.ps1 install-service   # WinSW/NSSM setup
+    powershell -File scripts\daemon.ps1 uninstall-service
+#>
+
+param(
+    [Parameter(Position=0)]
+    [ValidateSet('start','stop','status','logs','install-service','uninstall-service','help')]
+    [string]$Command = 'help',
+
+    [Parameter(Position=1)]
+    [int]$LogLines = 50
+)
+
+$ErrorActionPreference = 'Stop'
+
+# ── Paths ──
+$CodelarkHome    = if ($env:CODELARK_HOME) { $env:CODELARK_HOME } else { Join-Path $env:USERPROFILE '.codelark' }
+$SkillDir   = Split-Path -Parent (Split-Path -Parent $PSCommandPath)
+$RuntimeDir = Join-Path $CodelarkHome 'runtime'
+$PidFile    = Join-Path $RuntimeDir 'bridge.pid'
+$StatusFile = Join-Path $RuntimeDir 'status.json'
+$LogFile    = Join-Path (Join-Path $CodelarkHome 'logs') 'bridge.log'
+$ErrLogFile = Join-Path (Join-Path $CodelarkHome 'logs') 'bridge.stderr.log'
+$DaemonMjs  = Join-Path (Join-Path $SkillDir 'dist') 'daemon.mjs'
+$ConfigFile = Join-Path $CodelarkHome 'config.env'
+
+$ServiceName = 'CodeLarkBridge'
+
+# ── Helpers ──
+
+function Ensure-Dirs {
+    @('data','logs','runtime','data/messages') | ForEach-Object {
+        $dir = Join-Path $CodelarkHome $_
+        if (-not (Test-Path $dir)) { New-Item -ItemType Directory -Path $dir -Force | Out-Null }
+    }
+}
+
+function Ensure-Built {
+    if (-not (Test-Path $DaemonMjs)) {
+        Write-Host "Building daemon bundle..."
+        Push-Location $SkillDir
+        npm run build
+        Pop-Location
+    } else {
+        $srcFiles = Get-ChildItem -Path (Join-Path $SkillDir 'src') -Filter '*.ts' -Recurse
+        $bundleTime = (Get-Item $DaemonMjs).LastWriteTime
+        $stale = $srcFiles | Where-Object { $_.LastWriteTime -gt $bundleTime } | Select-Object -First 1
+        if ($stale) {
+            Write-Host "Rebuilding daemon bundle (source changed)..."
+            Push-Location $SkillDir
+            npm run build
+            Pop-Location
+        }
+    }
+}
+
+function Get-ConfigEnvironment {
+    $configEnv = @{}
+    if (-not (Test-Path $ConfigFile)) {
+        return $configEnv
+    }
+
+    foreach ($line in Get-Content $ConfigFile) {
+        $trimmed = $line.Trim()
+        if (-not $trimmed -or $trimmed.StartsWith('#')) { continue }
+        $eqIndex = $trimmed.IndexOf('=')
+        if ($eqIndex -lt 1) { continue }
+
+        $name = $trimmed.Substring(0, $eqIndex).Trim()
+        $value = $trimmed.Substring($eqIndex + 1).Trim()
+        if (
+            ($value.StartsWith('"') -and $value.EndsWith('"')) -or
+            ($value.StartsWith("'") -and $value.EndsWith("'"))
+        ) {
+            $value = $value.Substring(1, $value.Length - 2)
+        }
+        $configEnv[$name] = $value
+    }
+
+    return $configEnv
+}
+
+function Read-Pid {
+    if (Test-Path $PidFile) { return (Get-Content $PidFile -Raw).Trim() }
+    return $null
+}
+
+function Test-PidAlive {
+    param([string]$ProcessId)
+    if (-not $ProcessId) { return $false }
+    try { $null = Get-Process -Id ([int]$ProcessId) -ErrorAction Stop; return $true }
+    catch { return $false }
+}
+
+function Test-StatusRunning {
+    if (-not (Test-Path $StatusFile)) { return $false }
+    $json = Get-Content $StatusFile -Raw | ConvertFrom-Json
+    return $json.running -eq $true
+}
+
+function Show-LastExitReason {
+    if (Test-Path $StatusFile) {
+        $json = Get-Content $StatusFile -Raw | ConvertFrom-Json
+        if ($json.lastExitReason) {
+            Write-Host "Last exit reason: $($json.lastExitReason)"
+        }
+    }
+}
+
+function Show-FailureHelp {
+    Write-Host ""
+    Write-Host "Recent logs:"
+    if (Test-Path $LogFile) {
+        Get-Content $LogFile -Tail 20
+    } else {
+        Write-Host "  (no log file)"
+    }
+    if (Test-Path $ErrLogFile) {
+        Write-Host ""
+        Write-Host "Recent stderr:"
+        Get-Content $ErrLogFile -Tail 20
+    }
+    Write-Host ""
+    Write-Host "Next steps:"
+    Write-Host "  1. Run diagnostics:  powershell -File `"$SkillDir\scripts\doctor.ps1`""
+    Write-Host "  2. Check full logs:  powershell -File `"$SkillDir\scripts\daemon.ps1`" logs 100"
+    Write-Host "  3. Rebuild bundle:   cd `"$SkillDir`"; npm run build"
+}
+
+function Get-NodePath {
+    $nodePath = (Get-Command node -ErrorAction SilentlyContinue).Source
+    if (-not $nodePath) {
+        Write-Error "Node.js not found in PATH. Install Node.js >= 20."
+        exit 1
+    }
+    return $nodePath
+}
+
+# ── WinSW / NSSM detection ──
+
+function Find-ServiceManager {
+    # Prefer WinSW, then NSSM
+    $winsw = Get-Command 'WinSW.exe' -ErrorAction SilentlyContinue
+    if ($winsw) { return @{ type = 'winsw'; path = $winsw.Source } }
+
+    $nssm = Get-Command 'nssm.exe' -ErrorAction SilentlyContinue
+    if ($nssm) { return @{ type = 'nssm'; path = $nssm.Source } }
+
+    return $null
+}
+
+function Install-WinSWService {
+    param([string]$WinSWPath)
+    $nodePath = Get-NodePath
+    $xmlPath = Join-Path $SkillDir "$ServiceName.xml"
+    $configEnv = Get-ConfigEnvironment
+
+    # Run as current user so the service can access ~/.codelark and Codex login state
+    $currentUser = [System.Security.Principal.WindowsIdentity]::GetCurrent().Name
+    Write-Host "Service will run as: $currentUser"
+    $cred = Get-Credential -UserName $currentUser -Message "Enter password for '$currentUser' (required for Windows Service logon)"
+    $plainPwd = $cred.GetNetworkCredential().Password
+
+    # Generate WinSW config XML
+    $xml = @"
+<service>
+  <id>$ServiceName</id>
+  <name>CodeLark Bridge</name>
+  <description>CodeLark bridge daemon</description>
+  <executable>$nodePath</executable>
+  <arguments>$DaemonMjs</arguments>
+  <workingdirectory>$SkillDir</workingdirectory>
+  <serviceaccount>
+    <username>$currentUser</username>
+    <password>$([System.Security.SecurityElement]::Escape($plainPwd))</password>
+    <allowservicelogon>true</allowservicelogon>
+  </serviceaccount>
+  <env name="USERPROFILE" value="$env:USERPROFILE"/>
+  <env name="APPDATA" value="$env:APPDATA"/>
+  <env name="LOCALAPPDATA" value="$env:LOCALAPPDATA"/>
+  <env name="PATH" value="$env:PATH"/>
+  <env name="CODELARK_HOME" value="$CodelarkHome"/>
+  <logpath>$(Join-Path $CodelarkHome 'logs')</logpath>
+  <log mode="append">
+    <logfile>bridge-service.log</logfile>
+  </log>
+  <onfailure action="restart" delay="10 sec"/>
+  <onfailure action="restart" delay="30 sec"/>
+  <onfailure action="none"/>
+</service>
+"@
+
+    $extraEnvXml = ($configEnv.GetEnumerator() | ForEach-Object {
+        '  <env name="{0}" value="{1}"/>' -f $_.Key, [System.Security.SecurityElement]::Escape($_.Value)
+    }) -join "`r`n"
+    if ($extraEnvXml) {
+        $xml = $xml -replace '  <logpath>', "$extraEnvXml`r`n  <logpath>"
+    }
+
+    $xml | Set-Content -Path $xmlPath -Encoding UTF8
+
+    # Copy WinSW next to the XML with matching name
+    $winswCopy = Join-Path $SkillDir "$ServiceName.exe"
+    Copy-Item $WinSWPath $winswCopy -Force
+
+    & $winswCopy install
+    Write-Host "Service '$ServiceName' installed via WinSW."
+    Write-Host "  Service account: $currentUser"
+    Write-Host "Start with:  & `"$winswCopy`" start"
+    Write-Host "Or:          sc.exe start $ServiceName"
+}
+
+function Install-NSSMService {
+    param([string]$NSSMPath)
+    $nodePath = Get-NodePath
+    $configEnv = Get-ConfigEnvironment
+
+    # Run as current user so the service can access ~/.codelark and Codex login state
+    $currentUser = [System.Security.Principal.WindowsIdentity]::GetCurrent().Name
+    Write-Host "Service will run as: $currentUser"
+    $cred = Get-Credential -UserName $currentUser -Message "Enter password for '$currentUser' (required for Windows Service logon)"
+    $plainPwd = $cred.GetNetworkCredential().Password
+
+    & $NSSMPath install $ServiceName $nodePath $DaemonMjs
+    & $NSSMPath set $ServiceName AppDirectory $SkillDir
+    & $NSSMPath set $ServiceName ObjectName $currentUser $plainPwd
+    & $NSSMPath set $ServiceName AppStdout $LogFile
+    & $NSSMPath set $ServiceName AppStderr $LogFile
+    & $NSSMPath set $ServiceName AppStdoutCreationDisposition 4
+    & $NSSMPath set $ServiceName AppStderrCreationDisposition 4
+    & $NSSMPath set $ServiceName Description "CodeLark bridge daemon"
+    & $NSSMPath set $ServiceName AppRestartDelay 10000
+    $envArgs = @(
+        "USERPROFILE=$env:USERPROFILE",
+        "APPDATA=$env:APPDATA",
+        "LOCALAPPDATA=$env:LOCALAPPDATA",
+        "CODELARK_HOME=$CodelarkHome"
+    )
+    foreach ($entry in $configEnv.GetEnumerator()) {
+        $envArgs += "$($entry.Key)=$($entry.Value)"
+    }
+    & $NSSMPath set $ServiceName AppEnvironmentExtra @envArgs
+
+    Write-Host "Service '$ServiceName' installed via NSSM."
+    Write-Host "  Service account: $currentUser"
+    Write-Host "Start with:  nssm start $ServiceName"
+    Write-Host "Or:          sc.exe start $ServiceName"
+}
+
+# ── Fallback: Start-Process (no service manager) ──
+
+function Start-Fallback {
+    $nodePath = Get-NodePath
+    $configEnv = Get-ConfigEnvironment
+
+    # Clean env
+    $envClone = [System.Collections.Hashtable]::new()
+    foreach ($key in [System.Environment]::GetEnvironmentVariables().Keys) {
+        $envClone[$key] = [System.Environment]::GetEnvironmentVariable($key)
+    }
+    # Remove CLAUDECODE
+    [System.Environment]::SetEnvironmentVariable('CLAUDECODE', $null)
+    [System.Environment]::SetEnvironmentVariable('CODELARK_HOME', $CodelarkHome, 'Process')
+
+    foreach ($entry in $configEnv.GetEnumerator()) {
+        [System.Environment]::SetEnvironmentVariable($entry.Key, $entry.Value, 'Process')
+    }
+
+    try {
+        $proc = Start-Process -FilePath $nodePath `
+            -ArgumentList $DaemonMjs `
+            -WorkingDirectory $SkillDir `
+            -WindowStyle Hidden `
+            -RedirectStandardOutput $LogFile `
+            -RedirectStandardError $ErrLogFile `
+            -PassThru
+    } finally {
+        foreach ($key in $envClone.Keys) {
+            [System.Environment]::SetEnvironmentVariable($key, $envClone[$key], 'Process')
+        }
+        foreach ($entry in $configEnv.GetEnumerator()) {
+            if (-not $envClone.ContainsKey($entry.Key)) {
+                [System.Environment]::SetEnvironmentVariable($entry.Key, $null, 'Process')
+            }
+        }
+        if (-not $envClone.ContainsKey('CODELARK_HOME')) {
+            [System.Environment]::SetEnvironmentVariable('CODELARK_HOME', $null, 'Process')
+        }
+    }
+
+    # Write initial PID (main.ts will overwrite with real PID)
+    Set-Content -Path $PidFile -Value $proc.Id
+    return $proc.Id
+}
+
+# ── Commands ──
+
+switch ($Command) {
+    'start' {
+        Ensure-Dirs
+        Ensure-Built
+
+        $existingPid = Read-Pid
+        if ($existingPid -and (Test-PidAlive $existingPid)) {
+            Write-Host "Bridge already running (PID: $existingPid)"
+            if (Test-Path $StatusFile) { Get-Content $StatusFile -Raw }
+            exit 1
+        }
+
+        # Check if registered as Windows Service
+        $svc = Get-Service -Name $ServiceName -ErrorAction SilentlyContinue
+        if ($svc) {
+            Write-Host "Starting bridge via Windows Service..."
+            Start-Service -Name $ServiceName
+            Start-Sleep -Seconds 3
+
+            $newPid = Read-Pid
+            if ($newPid -and (Test-PidAlive $newPid) -and (Test-StatusRunning)) {
+                Write-Host "Bridge started (PID: $newPid, managed by Windows Service)"
+                if (Test-Path $StatusFile) { Get-Content $StatusFile -Raw }
+            } else {
+                Write-Host "Failed to start bridge via service."
+                Show-LastExitReason
+                Show-FailureHelp
+                exit 1
+            }
+        } else {
+            Write-Host "Starting bridge (background process)..."
+            $bridgePid = Start-Fallback
+            Start-Sleep -Seconds 3
+
+            $newPid = Read-Pid
+            if ($newPid -and (Test-PidAlive $newPid) -and (Test-StatusRunning)) {
+                Write-Host "Bridge started (PID: $newPid)"
+                if (Test-Path $StatusFile) { Get-Content $StatusFile -Raw }
+            } else {
+                Write-Host "Failed to start bridge."
+                if (-not $newPid -or -not (Test-PidAlive $newPid)) {
+                    Write-Host "  Process exited immediately."
+                }
+                Show-LastExitReason
+                Show-FailureHelp
+                exit 1
+            }
+        }
+    }
+
+    'stop' {
+        $svc = Get-Service -Name $ServiceName -ErrorAction SilentlyContinue
+        if ($svc -and $svc.Status -eq 'Running') {
+            Write-Host "Stopping bridge via Windows Service..."
+            Stop-Service -Name $ServiceName -Force
+            Write-Host "Bridge stopped"
+            if (Test-Path $PidFile) { Remove-Item $PidFile -Force }
+        } else {
+            $bridgePid = Read-Pid
+            if (-not $bridgePid) { Write-Host "No bridge running"; exit 0 }
+            if (Test-PidAlive $bridgePid) {
+                Stop-Process -Id ([int]$bridgePid) -Force
+                Write-Host "Bridge stopped"
+            } else {
+                Write-Host "Bridge was not running (stale PID file)"
+            }
+            if (Test-Path $PidFile) { Remove-Item $PidFile -Force }
+        }
+    }
+
+    'status' {
+        $bridgePid = Read-Pid
+
+        # Check Windows Service
+        $svc = Get-Service -Name $ServiceName -ErrorAction SilentlyContinue
+        if ($svc) {
+            Write-Host "Windows Service '$ServiceName': $($svc.Status)"
+        }
+
+        if ($bridgePid -and (Test-PidAlive $bridgePid)) {
+            Write-Host "Bridge process is running (PID: $bridgePid)"
+            if (Test-StatusRunning) {
+                Write-Host "Bridge status: running"
+            } else {
+                Write-Host "Bridge status: process alive but status.json not reporting running"
+            }
+            if (Test-Path $StatusFile) { Get-Content $StatusFile -Raw }
+        } else {
+            Write-Host "Bridge is not running"
+            if (Test-Path $PidFile) { Remove-Item $PidFile -Force }
+            Show-LastExitReason
+        }
+    }
+
+    'logs' {
+        if (Test-Path $LogFile) {
+            Get-Content $LogFile -Tail $LogLines | ForEach-Object {
+                $_ -replace '(token|secret|password)(["'']?\s*[:=]\s*["'']?)[^\s"]+', '$1$2*****'
+            }
+        } else {
+            Write-Host "No log file found at $LogFile"
+        }
+        if (Test-Path $ErrLogFile) {
+            Write-Host ""
+            Write-Host "stderr:"
+            Get-Content $ErrLogFile -Tail $LogLines
+        }
+    }
+
+    'install-service' {
+        Ensure-Dirs
+        Ensure-Built
+
+        $mgr = Find-ServiceManager
+        if (-not $mgr) {
+            Write-Host "No service manager found. Install one of:"
+            Write-Host "  WinSW:  https://github.com/winsw/winsw/releases"
+            Write-Host "  NSSM:   https://nssm.cc/download"
+            Write-Host ""
+            Write-Host "After installing, add it to PATH and re-run:"
+            Write-Host "  powershell -File `"$PSCommandPath`" install-service"
+            exit 1
+        }
+
+        switch ($mgr.type) {
+            'winsw' { Install-WinSWService -WinSWPath $mgr.path }
+            'nssm'  { Install-NSSMService  -NSSMPath  $mgr.path }
+        }
+    }
+
+    'uninstall-service' {
+        $svc = Get-Service -Name $ServiceName -ErrorAction SilentlyContinue
+        if (-not $svc) {
+            Write-Host "Service '$ServiceName' is not installed."
+            exit 0
+        }
+
+        if ($svc.Status -eq 'Running') {
+            Stop-Service -Name $ServiceName -Force
+        }
+
+        $mgr = Find-ServiceManager
+        if ($mgr -and $mgr.type -eq 'nssm') {
+            & $mgr.path remove $ServiceName confirm
+        } else {
+            # WinSW or generic
+            $winswExe = Join-Path $SkillDir "$ServiceName.exe"
+            if (Test-Path $winswExe) {
+                & $winswExe uninstall
+                Remove-Item $winswExe -Force -ErrorAction SilentlyContinue
+                Remove-Item (Join-Path $SkillDir "$ServiceName.xml") -Force -ErrorAction SilentlyContinue
+            } else {
+                sc.exe delete $ServiceName
+            }
+        }
+        Write-Host "Service '$ServiceName' uninstalled."
+    }
+
+    'help' {
+        Write-Host "Usage: daemon.ps1 {start|stop|status|logs [N]|install-service|uninstall-service}"
+        Write-Host ""
+        Write-Host "Commands:"
+        Write-Host "  start             Start the bridge daemon"
+        Write-Host "  stop              Stop the bridge daemon"
+        Write-Host "  status            Show bridge status"
+        Write-Host "  logs [N]          Show last N log lines (default 50)"
+        Write-Host "  install-service   Install as Windows Service (requires WinSW or NSSM)"
+        Write-Host "  uninstall-service Remove the Windows Service"
+    }
+}

package/skills/codelark/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: codelark
+description: Use this skill when working through CodeLark and you need Codex to send a local image or file back to the current IM chat. It teaches the attachment-send protocol and when to use it.
+---
+
+# CodeLark Attachment Sending
+
+Use this skill only when the user is chatting through CodeLark and wants you to send a generated or existing local artifact back to the IM chat.
+
+## What this skill does
+
+CodeLark can send local files back to the chat after your reply. Trigger that by including one or more `<clk-send>...</clk-send>` blocks in your final answer.
+
+Supported artifact kinds:
+
+- `image`
+- `file`
+
+## Required format
+
+Output valid JSON inside the block, with no markdown fence.
+
+Single artifact:
+
+```text
+<clk-send>
+{"type":"image","path":"D:\\path\\to\\result.png","caption":"optional caption"}
+</clk-send>
+```
+
+or
+
+```text
+<clk-send>
+{"type":"file","path":"D:\\path\\to\\report.pdf","caption":"optional caption"}
+</clk-send>
+```
+
+Multiple artifacts:
+
+```text
+<clk-send>
+{"items":[
+  {"type":"image","path":"D:\\path\\to\\result.png"},
+  {"type":"file","path":"D:\\path\\to\\report.pdf"}
+]}
+</clk-send>
+```
+
+## Rules
+
+- The `path` must be an absolute local path.
+- The file must already exist before you emit the block.
+- Keep normal user-facing explanation outside the `<clk-send>` block.
+- Do not invent artifacts that were not actually created or found.
+- If you are unsure whether the file exists, verify first.
+- If the channel probably does not support the artifact well, explain that plainly instead of inventing a successful send.
+
+## When to use
+
+Use this protocol when the user asks you to:
+
+- send a generated chart, diagram, screenshot, or edited image
+- send a report, archive, patch, PDF, spreadsheet, or other output file
+- send the final result as an attachment instead of only pasting text
+
+Do not use it for ordinary text replies.

package/skills/codelark-auto/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: codelark-auto
+description: Use this skill when the user wants to create a local script for CodeLark /auto-script automation. The script should wait for or detect a trigger condition, then print the exact prompt that /auto-script should send back into the bound bridge session.
+---
+
+# CodeLark /auto-script creation
+
+Use this skill when the user asks to create an automation script for:
+
+```text
+/auto-script new <absolute-script-path> <times>
+```
+
+`times` is a positive integer. `/auto-script new` does not accept `0`; use `/auto set <index> 0` later to pause an existing task.
+
+## Contract
+
+Create a local executable script that:
+
+- lives under the current Codex home, preferably `~/.codex/auto-scripts/`
+- waits for the requested timing or condition
+- checks any relevant local process, log, job, Ray cluster, file, or command state
+- prints exactly one useful Codex prompt to stdout
+- exits with code 0 when stdout is ready for Codex
+- exits non-zero only when the script itself cannot run
+
+The bridge runs the script repeatedly. Each stdout becomes the next prompt sent to the bridge session that owns the `/auto-script` task.
+
+## Output to the user
+
+After creating the script, tell the user:
+
+- the script content
+- the absolute script path
+- the suggested `/auto-script new <absolute-script-path> <positive-times>` command
+
+Name the script after the trigger timing or condition, for example `check_experiment_progress_every_20m.sh`, and place it under `~/.codex/auto-scripts/`.
+
+## Script pattern
+
+Prefer Bash on Unix-like systems:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+prompt="20分钟过去了，请检查一下实验进度。"
+deadline=$((SECONDS + 20 * 60))
+
+while (( SECONDS < deadline )); do
+  sleep 5
+
+  # Replace this block with task-specific checks.
+  if ! pgrep -f "experiment-command-or-name" >/dev/null 2>&1; then
+    prompt="实验进程似乎已经退出。请检查实验进度、最近日志和退出原因。"
+    break
+  fi
+
+  if command -v ray >/dev/null 2>&1; then
+    ray_status="$(ray status 2>&1 || true)"
+    if printf '%s\n' "$ray_status" | grep -qiE "failed|error|dead|unhealthy"; then
+      prompt="ray status 显示异常，请检查实验进度并诊断：\n$ray_status"
+      break
+    fi
+  fi
+done
+
+printf '%b\n' "$prompt"
+```
+
+Make the script executable with `chmod +x`.
+
+## Rules
+
+- Use absolute paths inside the script when checking known files or logs.
+- Store the script itself under `~/.codex/auto-scripts/`; scripts outside Codex home are rejected by `/auto-script new`.
+- Always provide the exact creation command in this shape: `/auto-script new /home/<user>/.codex/auto-scripts/<script>.sh <times>`.
+- Keep stdout focused on the Codex prompt. Put debug logs on stderr if needed.
+- Do not start long-running experiment work unless the user asked for that; `/auto-script` scripts should usually observe and report.
+- If the user asks for “every N minutes”, the script itself should sleep for N minutes, checking every few seconds when useful.

package/skills/codelark-question/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: codelark-question
+description: 在 CodeLark 中需要向 IM 用户发起结构化确认、选择或批准时使用；用户说“找我确认”“问我 xxx”“请我批准”“让我选择”“需要我确认/批准”时必须触发。
+---
+
+# CodeLark 问题卡片
+
+当当前会话通过 CodeLark 连接到 IM，并且你需要用户做选择、确认、批准或补充一个很短的信息后才能继续时，使用这个 skill。
+
+## 触发条件
+
+只要用户表达了下面任一意图，就应该触发这个 skill：
+
+- “找我确认”“让我确认”“需要我确认”。
+- “问我 xxx”“向我提问”“让我选择 xxx”。
+- “请我批准”“需要我批准”“找我审批”。
+- 需要用户在继续执行前从几个互斥选项中选择一个。
+- 需要用户批准高影响操作，例如合并、删除、部署、发布、改配置或执行不可逆动作。
+
+不要只因为普通聊天里出现问号就触发；只有你确实需要用户输入来推进任务时才使用。
+
+## 这个 skill 做什么
+
+CodeLark 会把最终回复里的 `<clk-ask>` 块转换成飞书/Lark 问题卡片。用户提交后的结果会作为下一条用户消息回到同一个 bridge session。
+
+## 输出格式
+
+在一个 `<clk-ask>` 块里输出合法 JSON。不要把 JSON 放进 markdown 代码块。
+
+简单选择：
+
+
+```text
+<clk-ask>
+{"question":"请选择发布策略","options":["灰度","全量"],"allowTextReply":true}
+</clk-ask>
+```
+
+选择加可选文本：
+
+```text
+<clk-ask>
+{"question":"是否继续执行部署？","options":["继续","取消"],"input":{"label":"补充说明","placeholder":"可留空"},"submitText":"提交","allowTextReply":true}
+</clk-ask>
+```
+
+## 规则
+
+- 只有在确实需要用户输入才能继续时才使用。
+- 普通说明放在 `<clk-ask>` 块外。
+- 只是在总结、写代码、汇报已完成工作时，不要发问题卡片。
+- `options` 要短，并且互斥；最多展示 8 个选项。
+- 如果普通文本问题已经足够，不要创建问题卡片。
+- 除非用户询问桥接协议，否则不要向用户解释 `<clk-ask>` 协议本身。