@h2562961224/cc-runner 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chuzhen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,77 @@
+# cc-runner
+
+云端下发、本地执行的 Claude Code 任务守护进程。**做这套东西的初衷:告警 webhook 一响,本地 cc 自动排查、把"要不要紧"回给你。** 云端是唯一事实源;本地只做三件事——轮询拉取、到点执行、结果上报。零 npm 依赖,Node ≥ 18。
+
+本地全程**只有出站 HTTPS,不监听任何端口**——所以告警回调打到云端,不需要在你的机器上开公网入口。每次请求带 `X-Runner-Token`,**令牌即身份**(服务器据此认出是哪台 runner),凭证在控制台 Runner 页复制、可随时重置。
+
+## 纯中心化:一律先领取
+
+runner **不做任何本地自主调度**——不算 cron、不离线自跑。**要执行的任务(webhook 触发 / 手动立即执行 / 定时到期)全部由服务器生成为待领队列,runner 先 `/claim` 领到才执行。** 断网就是纯粹拉不到任务,恢复后接着领。
+
+```
+                          云端应用(唯一调度中心)
+  告警/CI/GitLab webhook ─┐
+  界面手动"立即执行"      ├──▶ 服务器生成待领队列(pending job)
+  定时任务到期(服务器算)─┘                 │
+                                            ▼ /claim 逐条领取(服务器原子置 claimed)
+  ┌──────────────────────── cc-runner 守护进程(launchd 常驻)────────────────────┐
+  │            claude -p(headless)                              飞书通知          │
+  └──────────────────────────────────────┬──────────────────────────────────────┘
+                                          ▼ /report 回填(outbox 断线补传)
+```
+
+- **`/heartbeat`** 每 30s 打卡,返回定时任务版本号。
+- **`/sync`** 版本变了拉本机定时任务定义——**仅本地缓存供 `status` 展示,不驱动执行**(执行一律走 `/claim`)。
+- **`/claim`** 唯一执行入口:逐条领取服务器生成的 pending job。
+- **`/report`** 回填结果(只能改自己领走的那条)。
+
+## 安装(用户视角,一次粘贴)
+
+```bash
+npm i -g @h2562961224/cc-runner
+cc-runner init --api https://<your-project>.example.com/functions/v1/runner-api --token <X-Runner-Token> --workdir ~/your-project
+cc-runner install        # 挂载 launchd:开机自启、crash 自动拉起
+```
+
+验证:`cc-runner status`;日志 `tail -f ~/.cc-runner/logs/daemon.log`。
+
+## 协议契约(runner-api,全部 POST + `X-Runner-Token`)
+
+| 动作 | 调用 | 返回 |
+|---|---|---|
+| 心跳 + 拿版本 | `POST /heartbeat` | `{ok, runner, orgId, orgName, schedulesVersion}` |
+| 拉定时任务定义 | `POST /sync`(版本变了才拉,全量覆盖) | `{version, runner, orgId, schedules:[...]}` |
+| 领队列任务 | `POST /claim`(逐条领到空为止) | `{job}` 或 `{job: null}` |
+| 回填队列结果 | `POST /report`(只能改自己领走的那条) | `{ok, jobId, status}` |
+
+`/report` body:`{jobId, status, exitCode, summary, error, startedAt, finishedAt}`。
+
+- **幂等**:所有任务由服务器 `/claim` 原子认领,天然不会被两台 runner 抢到同一条;本地 `done` 表再兜一层,防同一进程内重复入队。
+- **上报走 outbox**:结果先落 `~/.cc-runner/data/outbox/`,每轮先补传再领新;断线累积、恢复补传。网络/5xx 重试,4xx(如 job 已被接管)丢弃不死循环。
+- **定时任务**:cron/once 到期由**服务器**生成待领 job,runner 和 webhook/手动一视同仁地领取、执行、`/report` 回填——所以定时任务结果同样进服务器 job 历史。
+- **崩溃恢复**:领取后没跑完就 crash 的任务,会停在服务器侧 `claimed`——本 runner 不自动重跑(宁缺勿重),由服务器/控制台按超时回收或人工重新触发。
+
+## 安全边界
+
+- 本地只有出站 HTTPS,不监听端口。
+- 云端建任务 ≈ 在本机执行代码:`allowed_workdirs` 白名单**由本地 config 说了算**,云端下发的 workdir 不在白名单内直接 `rejected`,不执行。
+- `config.json` 含 runner token,权限 0600;默认 `--dangerously-skip-permissions` 跑 cc,介意就改 `claude_args`(如 `--permission-mode acceptEdits`)。
+
+## 目录
+
+```
+~/.cc-runner/
+├── config.json          init 生成(0600)
+├── logs/daemon.log      launchd 重定向
+└── data/
+    ├── state.json       定时任务版本+缓存+done 表+outbox 序号
+    ├── outbox/          待补传的 /report(可重放)
+    └── transcripts/     每次执行的 cc 原始输出(按 run_id)
+```
+
+## 已知取舍(MVP)
+
+- 轮询间隔即指令延迟(默认 30s);想更低做 long-poll,协议不用改。
+- cron 回看窗口 48h;`catchup_latest` 停机超 48h 不补。
+- 串行执行,同刻多任务排队;超时 SIGKILL。
+- 日志不轮转,大了自己清。

package/bin/cli.js

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+// cc-runner CLI:init(写配置)/ start(前台跑)/ install(挂 launchd 常驻)
+//              / uninstall / status
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const HOME_DIR = process.env.CC_RUNNER_HOME || path.join(os.homedir(), '.cc-runner');
+const CONFIG_PATH = path.join(HOME_DIR, 'config.json');
+const LOG_DIR = path.join(HOME_DIR, 'logs');
+const PLIST_LABEL = 'com.cc-runner.daemon';
+const PLIST_PATH = path.join(os.homedir(), 'Library', 'LaunchAgents', `${PLIST_LABEL}.plist`);
+
+const [cmd, ...rest] = process.argv.slice(2);
+
+// 简易 flag 解析:--key value,可重复的收集为数组
+function parseFlags(argv, multi = []) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    if (!argv[i].startsWith('--')) continue;
+    const k = argv[i].slice(2);
+    const v = argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[++i] : 'true';
+    if (multi.includes(k)) (out[k] = out[k] || []).push(v);
+    else out[k] = v;
+  }
+  return out;
+}
+
+function usage() {
+  console.log(`cc-runner — 云端下发、本地执行的 Claude Code 任务守护进程
+
+用法:
+  cc-runner init --api <runner-api地址> --token <X-Runner-Token> [选项]   写配置到 ~/.cc-runner/
+      选项: --workdir <path>   允许执行任务的目录白名单,可重复(默认 ~)
+            --feishu <webhook> 默认飞书通知地址
+            --poll <秒>        轮询间隔(默认 30)
+            --model <model>    执行任务用的模型
+      说明: runner 身份由 token 决定,凭证在控制台 Runner 页复制、可随时重置
+  cc-runner start              前台运行(调试用)
+  cc-runner install            挂载为 launchd 常驻服务(macOS,开机自启+守护)
+  cc-runner uninstall          卸载 launchd 服务
+  cc-runner status             查看运行状态与最近任务`);
+}
+
+function requireConfig() {
+  if (!fs.existsSync(CONFIG_PATH)) {
+    console.error('还没配置,先跑 cc-runner init(命令可从云端控制台「接入指引」页复制)');
+    process.exit(1);
+  }
+}
+
+switch (cmd) {
+  case 'init': {
+    const f = parseFlags(rest, ['workdir']);
+    if (!f.api || !f.token) { console.error('init 需要 --api 和 --token'); process.exit(1); }
+    fs.mkdirSync(HOME_DIR, { recursive: true });
+    const cfg = {
+      api_url: f.api.replace(/\/$/, ''),
+      runner_token: f.token,
+      runner_id: f.runner || '', // 留空:身份以服务器 heartbeat 返回的为准
+      poll_interval_seconds: f.poll ? parseInt(f.poll, 10) : 30,
+      allowed_workdirs: f.workdir || [os.homedir()],
+      default_feishu_webhook: f.feishu || '',
+      model: f.model || '',
+      claude_args: ['--dangerously-skip-permissions'],
+    };
+    fs.writeFileSync(CONFIG_PATH, JSON.stringify(cfg, null, 2));
+    fs.chmodSync(CONFIG_PATH, 0o600); // 里面有 runner token
+    console.log(`已写入 ${CONFIG_PATH}`);
+    console.log('下一步: cc-runner install(常驻)或 cc-runner start(前台调试)');
+    break;
+  }
+
+  case 'start': {
+    requireConfig();
+    require(path.join(__dirname, '..', 'runner.js'));
+    break;
+  }
+
+  case 'install': {
+    requireConfig();
+    if (process.platform !== 'darwin') {
+      console.error('install 目前只做了 macOS launchd;Linux 请用 systemd 跑 `cc-runner start`');
+      process.exit(1);
+    }
+    fs.mkdirSync(LOG_DIR, { recursive: true });
+    fs.mkdirSync(path.dirname(PLIST_PATH), { recursive: true });
+    const plist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>Label</key><string>${PLIST_LABEL}</string>
+  <key>ProgramArguments</key><array>
+    <string>${process.execPath}</string>
+    <string>${path.join(__dirname, 'cli.js')}</string>
+    <string>start</string>
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>${path.join(LOG_DIR, 'daemon.log')}</string>
+  <key>StandardErrorPath</key><string>${path.join(LOG_DIR, 'daemon.log')}</string>
+  <key>EnvironmentVariables</key><dict>
+    <key>PATH</key><string>${process.env.PATH || '/usr/local/bin:/usr/bin:/bin'}</string>
+    <key>HOME</key><string>${os.homedir()}</string>
+  </dict>
+</dict></plist>`;
+    fs.writeFileSync(PLIST_PATH, plist);
+    try { execSync(`launchctl unload ${PLIST_PATH} 2>/dev/null`); } catch (_) { /* 未加载过 */ }
+    execSync(`launchctl load -w ${PLIST_PATH}`);
+    console.log(`已挂载 launchd 服务 ${PLIST_LABEL}(开机自启,crash 自动拉起)`);
+    console.log(`日志: tail -f ${path.join(LOG_DIR, 'daemon.log')}`);
+    break;
+  }
+
+  case 'uninstall': {
+    try { execSync(`launchctl unload ${PLIST_PATH} 2>/dev/null`); } catch (_) { /* 忽略 */ }
+    if (fs.existsSync(PLIST_PATH)) fs.unlinkSync(PLIST_PATH);
+    console.log('已卸载(配置和数据保留在 ~/.cc-runner,需要的话手动删)');
+    break;
+  }
+
+  case 'status': {
+    requireConfig();
+    let loaded = false;
+    try { loaded = execSync('launchctl list').toString().includes(PLIST_LABEL); } catch (_) { /* 非 macOS */ }
+    console.log(`launchd: ${loaded ? '已挂载' : '未挂载'}`);
+    try {
+      const st = JSON.parse(fs.readFileSync(path.join(HOME_DIR, 'data', 'state.json'), 'utf8'));
+      console.log(`同步版本: ${st.schedule_version},定时任务数: ${(st.schedules || []).length}`);
+      const done = Object.entries(st.done || {}).sort((a, b) => (a[1].at < b[1].at ? 1 : -1)).slice(0, 5);
+      for (const [k, v] of done) console.log(`  最近执行: ${k}  ${v.status}  ${v.at}`);
+    } catch (_) { console.log('还没有本地状态(从未成功同步/执行)'); }
+    const outbox = path.join(HOME_DIR, 'data', 'outbox');
+    if (fs.existsSync(outbox)) {
+      const n = fs.readdirSync(outbox).length;
+      if (n) console.log(`待补传上报: ${n} 条`);
+    }
+    break;
+  }
+
+  default:
+    usage();
+    process.exit(cmd ? 1 : 0);
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@h2562961224/cc-runner",
+  "version": "0.1.0",
+  "description": "云端下发、本地执行的 Claude Code 任务守护进程(纯中心化 pull 模型,零依赖)",
+  "bin": {
+    "cc-runner": "bin/cli.js"
+  },
+  "files": [
+    "bin/cli.js",
+    "runner.js",
+    "README.md",
+    "skills/"
+  ],
+  "keywords": [
+    "claude-code",
+    "runner",
+    "daemon",
+    "webhook",
+    "cron",
+    "automation"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/h2562961224/cc-runner.git"
+  },
+  "homepage": "https://github.com/h2562961224/cc-runner#readme",
+  "bugs": {
+    "url": "https://github.com/h2562961224/cc-runner/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}

package/runner.js

@@ -0,0 +1,294 @@
+#!/usr/bin/env node
+// cc-runner: 本地任务守护进程(pull 模型,纯中心化)。走 runner 专属通道 runner-api,
+// 每次请求带 X-Runner-Token(令牌即身份,服务器据此认出是哪台 runner)。
+//
+// 中心化:runner 不做任何本地自主调度。**所有要执行的任务(webhook / 手动 / 定时)
+// 一律由服务器生成为待领队列,runner 先 /claim 领到才执行** —— 不在本地算 cron、
+// 不离线自跑。断网就是纯粹拉不到任务,恢复后继续领。
+//
+// 四个操作,全部 POST:
+//   /heartbeat  每 30s 打卡,返回 { schedulesVersion }
+//   /sync       版本变了拉本机定时任务定义(仅本地缓存供 status 展示,不驱动执行)
+//   /claim      领一条待执行任务,返回 { job } 或 { job: null }
+//   /report     回报结果 { jobId, status, exitCode, summary, error, startedAt, finishedAt }
+//               只能改自己领走的那条(服务器校验)
+//
+// 结果先写本地 outbox 再上报 /report,断线累积、恢复补传。
+// 零 npm 依赖:Node >= 18(需要全局 fetch)。入口是 bin/cli.js(cc-runner start)。
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const { spawn } = require('child_process');
+
+// ---------------------------------------------------------------------------
+// 配置与状态
+// ---------------------------------------------------------------------------
+const HOME_DIR = process.env.CC_RUNNER_HOME || path.join(os.homedir(), '.cc-runner');
+const CONFIG_PATH = process.env.CC_RUNNER_CONFIG || path.join(HOME_DIR, 'config.json');
+let cfg;
+try { cfg = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8')); } catch (e) {
+  console.error(`[fatal] 读不到配置 ${CONFIG_PATH},先跑: cc-runner init --api <runner-api地址> --token <X-Runner-Token>`);
+  process.exit(1);
+}
+for (const k of ['api_url', 'runner_token']) {
+  if (!cfg[k]) { console.error(`[fatal] config 缺少 ${k}(旧版 cloud_url/service_key 已废弃,请重新 cc-runner init)`); process.exit(1); }
+}
+const API_BASE = cfg.api_url.replace(/\/$/, '');
+let runnerId = cfg.runner_id || 'default'; // 本地标签;首次 heartbeat 后用服务器返回的真实值覆盖
+let orgName = '';
+const POLL_MS = (cfg.poll_interval_seconds || 30) * 1000;
+const CLAUDE_BIN = cfg.claude_bin || 'claude';
+const CLAUDE_ARGS = cfg.claude_args || ['--dangerously-skip-permissions'];
+const MODEL = cfg.model || '';
+// 云端下发的 workdir 常含字面量 ~(平台 UI 里用户自然会填 ~/xxx),path.resolve 不认
+// ~,会拼成 <cwd>/~/xxx。这里统一把开头的 ~ 展开成 home,再交给 resolve/白名单/spawn。
+function expandTilde(p) {
+  if (typeof p !== 'string' || !p) return p;
+  if (p === '~') return os.homedir();
+  if (p.startsWith('~/')) return path.join(os.homedir(), p.slice(2));
+  return p;
+}
+const ALLOWED_WORKDIRS = (cfg.allowed_workdirs || []).map((p) => path.resolve(expandTilde(p)));
+const JOB_PULL_LIMIT = cfg.job_pull_limit || 20; // 每轮最多 /claim 多少条,防一次拉太多
+
+const DATA_DIR = path.join(HOME_DIR, 'data');
+const OUTBOX_DIR = path.join(DATA_DIR, 'outbox');
+const TRANSCRIPT_DIR = path.join(DATA_DIR, 'transcripts');
+const STATE_PATH = path.join(DATA_DIR, 'state.json');
+for (const d of [DATA_DIR, OUTBOX_DIR, TRANSCRIPT_DIR]) fs.mkdirSync(d, { recursive: true });
+
+// state = { schedule_version, schedules: [](仅缓存展示), done: {"<dedup_key>": {status, at}}, outbox_seq }
+let state = { schedule_version: -1, schedules: [], done: {}, outbox_seq: 0 };
+try { state = { ...state, ...JSON.parse(fs.readFileSync(STATE_PATH, 'utf8')) }; } catch (_) { /* 首次运行 */ }
+
+function saveState() {
+  const keys = Object.keys(state.done);
+  if (keys.length > 5000) {
+    keys.sort((a, b) => (state.done[a].at < state.done[b].at ? -1 : 1));
+    for (const k of keys.slice(0, keys.length - 5000)) delete state.done[k];
+  }
+  fs.writeFileSync(STATE_PATH, JSON.stringify(state));
+}
+
+function log(msg) { console.log(`${new Date().toISOString()} ${msg}`); }
+
+// ---------------------------------------------------------------------------
+// runner-api 调用(POST + X-Runner-Token)
+//   抛出的 error 带 .retriable:网络错误/5xx 可重试;4xx/{error} 视为永久失败。
+// ---------------------------------------------------------------------------
+async function api(op, body) {
+  let res;
+  try {
+    res = await fetch(`${API_BASE}/${op}`, {
+      method: 'POST',
+      headers: { 'X-Runner-Token': cfg.runner_token, 'Content-Type': 'application/json' },
+      body: JSON.stringify(body || {}),
+      signal: AbortSignal.timeout(20000),
+    });
+  } catch (e) {
+    const err = new Error(`${op} 网络错误: ${e.message}`); err.retriable = true; throw err;
+  }
+  const text = await res.text();
+  let data = null; try { data = text ? JSON.parse(text) : null; } catch (_) { /* 非 JSON */ }
+  if (!res.ok || (data && data.error)) {
+    const msg = (data && data.error) ? data.error : `${res.status} ${text.slice(0, 200)}`;
+    const err = new Error(`${op} -> ${msg}`); err.retriable = res.status >= 500; throw err;
+  }
+  return data;
+}
+
+// ---------------------------------------------------------------------------
+// 心跳拿版本 + 定时任务定义同步(仅缓存,供 status 展示;执行一律走 /claim)
+// ---------------------------------------------------------------------------
+async function heartbeat() {
+  const r = await api('heartbeat');
+  if (r && r.runner) runnerId = r.runner;
+  if (r && r.orgName) orgName = r.orgName;
+  return r && r.schedulesVersion != null ? Number(r.schedulesVersion) : null;
+}
+
+async function syncSchedules() {
+  const r = await api('sync');
+  state.schedules = Array.isArray(r && r.schedules) ? r.schedules : [];
+  if (r && r.version != null) state.schedule_version = Number(r.version);
+  saveState();
+  log(`[sync] 定时任务版本 ${state.schedule_version},清单 ${state.schedules.length} 条(仅缓存,执行走 /claim)`);
+}
+
+// ---------------------------------------------------------------------------
+// 领取任务队列(服务器原子认领,逐条领到空为止)。webhook / 手动 / 定时 都在这。
+// ---------------------------------------------------------------------------
+async function claimJobs() {
+  const items = [];
+  for (let i = 0; i < JOB_PULL_LIMIT; i++) {
+    const r = await api('claim');
+    const job = r && r.job;
+    if (!job) break; // 队列空
+    items.push({
+      dedupKey: job.dedup_key || `job:${job.id}`, source: job.source || 'webhook', jobId: job.id,
+      scheduledAt: job.scheduled_at || job.created_at,
+      name: job.source === 'webhook' ? `webhook:${job.trigger_id || ''}` : (job.source || 'job'),
+      prompt: job.prompt, workdir: expandTilde(job.workdir),
+      timeoutSeconds: job.timeout_seconds || 900, output: job.output || {},
+    });
+  }
+  return items;
+}
+
+// ---------------------------------------------------------------------------
+// 执行
+// ---------------------------------------------------------------------------
+function workdirAllowed(dir) {
+  if (!ALLOWED_WORKDIRS.length) return false; // 白名单空 = 全拒,安全兜底本地说了算
+  const r = path.resolve(dir || '');
+  return ALLOWED_WORKDIRS.some((w) => r === w || r.startsWith(w + path.sep));
+}
+
+function runClaude(item, runId) {
+  return new Promise((resolve) => {
+    const args = ['-p', item.prompt, '--output-format', 'json', ...CLAUDE_ARGS];
+    if (MODEL) args.push('--model', MODEL);
+    const timeoutMs = item.timeoutSeconds * 1000;
+    const child = spawn(CLAUDE_BIN, args, { cwd: item.workdir, env: process.env, stdio: ['ignore', 'pipe', 'pipe'] });
+    let out = ''; let errOut = ''; let timedOut = false;
+    const timer = setTimeout(() => { timedOut = true; child.kill('SIGKILL'); }, timeoutMs);
+    child.stdout.on('data', (d) => { out += d; });
+    child.stderr.on('data', (d) => { errOut += d.toString().slice(0, 4000); });
+    child.on('error', (e) => { clearTimeout(timer); resolve({ status: 'failed', error: `spawn 失败: ${e.message}` }); });
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      fs.writeFileSync(path.join(TRANSCRIPT_DIR, `${runId}.json`), out || errOut || '');
+      if (timedOut) return resolve({ status: 'timeout', error: `超时(${timeoutMs / 1000}s)强杀`, exitCode: code });
+      let summary = '';
+      try { summary = String(JSON.parse(out).result || '').slice(0, 4000); } catch (_) { summary = (out || '').slice(0, 4000); }
+      if (code !== 0) return resolve({ status: 'failed', exitCode: code, summary, error: errOut.slice(0, 1000) });
+      resolve({ status: 'success', exitCode: 0, summary });
+    });
+  });
+}
+
+async function notifyFeishu(item, run) {
+  const url = (item.output && item.output.feishu_webhook) || cfg.default_feishu_webhook;
+  if (!url) return;
+  const icon = { success: '✅', failed: '❌', timeout: '⏱️', rejected: '🚫' }[run.status] || '•';
+  const body = {
+    msg_type: 'interactive',
+    card: {
+      header: { title: { tag: 'plain_text', content: `${icon} [${run.status}] ${item.name}` },
+        template: run.status === 'success' ? 'green' : 'red' },
+      elements: [{ tag: 'markdown',
+        content: `${(run.summary || run.error || '(无输出)').slice(0, 2000)}\n<font color="grey">runner ${runnerId} · ${item.source} · ${run.scheduled_at}</font>` }],
+    },
+  };
+  try {
+    await fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body), signal: AbortSignal.timeout(10000) });
+  } catch (e) { log(`[feishu] ${e.message}`); }
+}
+
+// ---------------------------------------------------------------------------
+// 上报(outbox:存可重放的 /report 调用;断线累积,恢复补传)
+// ---------------------------------------------------------------------------
+function enqueueOp(op) {
+  const seq = String(state.outbox_seq++).padStart(9, '0');
+  fs.writeFileSync(path.join(OUTBOX_DIR, `${seq}.json`), JSON.stringify(op));
+  saveState();
+}
+
+async function flushOutbox() {
+  for (const f of fs.readdirSync(OUTBOX_DIR).sort()) {
+    const p = path.join(OUTBOX_DIR, f);
+    let op;
+    try { op = JSON.parse(fs.readFileSync(p, 'utf8')); } catch (_) { fs.unlinkSync(p); continue; }
+    if (!op || !op.op) { fs.unlinkSync(p); continue; } // 旧格式/损坏,丢弃
+    try {
+      await api(op.op, op.body);
+      fs.unlinkSync(p);
+    } catch (e) {
+      if (e.retriable) { log(`[outbox] ${f} 稍后重试: ${e.message}`); return; } // 网络/5xx:留待下轮
+      log(`[outbox] ${f} 永久失败,丢弃: ${e.message}`); fs.unlinkSync(p); // 4xx(如 job 已被接管)
+    }
+  }
+}
+
+function reportRun(item, run) {
+  enqueueOp({ op: 'report', body: {
+    jobId: item.jobId, status: run.status, exitCode: run.exit_code ?? null,
+    summary: run.summary, error: run.error, startedAt: run.started_at, finishedAt: run.finished_at,
+  } });
+}
+
+// ---------------------------------------------------------------------------
+// 串行执行队列 + 主循环
+// ---------------------------------------------------------------------------
+const queue = [];
+const enqueued = new Set(); // 本进程内已排队的 dedupKey,防同一 tick 重复入队
+let working = false;
+
+function enqueue(items) {
+  for (const it of items) {
+    if (state.done[it.dedupKey] || enqueued.has(it.dedupKey)) continue;
+    enqueued.add(it.dedupKey);
+    queue.push(it);
+  }
+}
+
+async function processQueue() {
+  if (working) return;
+  working = true;
+  while (queue.length) {
+    const item = queue.shift();
+    const key = item.dedupKey;
+    if (state.done[key]) { enqueued.delete(key); continue; }
+
+    const runId = crypto.randomUUID();
+    const startedAt = new Date().toISOString();
+    log(`[run] ${item.name}(${item.source})sched=${item.scheduledAt}`);
+
+    let result;
+    if (!workdirAllowed(item.workdir)) {
+      result = { status: 'rejected', error: `workdir 不在本地白名单: ${item.workdir}` };
+    } else {
+      result = await runClaude(item, runId);
+    }
+
+    const run = {
+      scheduled_at: item.scheduledAt, started_at: startedAt, finished_at: new Date().toISOString(),
+      status: result.status, exit_code: result.exitCode ?? null,
+      summary: result.summary || null, error: result.error || null,
+    };
+    state.done[key] = { status: result.status, at: run.finished_at }; saveState();
+    enqueued.delete(key);
+    log(`[run] ${item.name} -> ${result.status}`);
+    reportRun(item, run);
+    await flushOutbox();
+    await notifyFeishu(item, run);
+  }
+  working = false;
+}
+
+async function tick() {
+  let online = true;
+  // 先补传上一轮攒下的上报
+  try { await flushOutbox(); } catch (e) { log(`[tick/outbox] ${e.message}`); }
+  // 心跳拿版本
+  let remoteVersion = null;
+  try { remoteVersion = await heartbeat(); } catch (e) { online = false; log(`[heartbeat] ${e.message}`); }
+  // 版本变了才拉全量定时任务定义(仅刷新本地缓存,不驱动执行)
+  if (online && remoteVersion !== null && remoteVersion !== state.schedule_version) {
+    try { await syncSchedules(); } catch (e) { log(`[sync] ${e.message}`); }
+  }
+  // 唯一执行入口:领取待办队列(webhook / 手动 / 定时都在服务器侧生成为 job)
+  if (online) {
+    try { enqueue(await claimJobs()); } catch (e) { log(`[claim] ${e.message}`); }
+  }
+  processQueue();
+}
+
+log(`[cc-runner] 启动 runner_id=${runnerId} poll=${POLL_MS / 1000}s(纯中心化,任务一律 /claim 领取)`);
+tick();
+setInterval(tick, POLL_MS);

package/skills/cc-runner/SKILL.md

@@ -0,0 +1,222 @@
+# CC 任务控制台接入指南（Skill）
+
+> 面向 **agent 自动执行**。把告警 webhook 或定时任务，自动交给你本地机器上的 Claude Code 执行 —— 告警一响，本地 cc 自动排查并回填结论。按顺序做完四步即可：① 连中心项目 → ② 装本地 runner → ③ 建触发器/定时 → ④ 查记录。涉及在本机执行代码，装 runner 前务必和用户确认 workdir（见第二步安全提示）。
+
+## 这是什么
+
+CC 任务控制台把两类触发，转成本地 Claude Code 的自主执行：
+
+- **Webhook 触发（主用途）**：腾讯云告警、GitLab、CI 等打一个回调过来 → 本地 `claude -p` 自动排查 → 结论回填控制台。做这套东西的初衷就是「告警一响，本地 cc 自动告诉你要不要紧」。
+- **定时触发**：cron / 一次性任务，到点由服务器生成待领任务，runner 领走执行。
+
+架构是**中心化的**：云端一个中心项目记录任务、下发指令、汇总结果；你本地跑一个守护进程 `cc-runner`，只做出站轮询（不监听任何端口），拉指令、执行、回填。
+
+---
+
+## 配置（已填好，可直接复制运行）
+
+中心项目地址与 anon key（anon key 设计上就可公开，安全）已在本文填好，所有用户通用：
+
+- 中心项目地址：`https://bb41veoe8re43upmktc6.db.superun.com`
+- Edge Function OpenAPI manifest：`https://id--1799105425833984-40e8d3eebf4e4e18893a4b0309261dc4.superun.yun/superun/openapi.json`
+
+以下每个用户各自持有、**切勿写进公开文档或提交仓库**：
+
+- 你的登录凭证（`superun login` 用的 token 或邮箱密码）
+- runner token（`cc-runner init --token` 用，在控制台 **Runner 页**复制，可随时重置）
+- 每个 webhook 触发器的 `secret`
+
+---
+
+## 前置条件
+
+在开始前，确认本机具备（缺什么先装什么）：
+
+```bash
+node -v            # 需要 >= 18
+claude --version   # Claude Code CLI 必须已安装并登录过（runner 会调 claude -p 执行任务）
+```
+
+- **Claude Code CLI 必须能直接跑** —— runner 靠它执行任务。先 `claude` 交互跑一次确认已登录。
+- 安装两个 CLI：
+
+```bash
+npm i -g superun-cli   # 管理侧：连项目、建任务、查记录（命令为 superun）
+npm i -g @h2562961224/cc-runner   # 执行侧：本地守护进程（命令为 cc-runner）
+```
+
+---
+
+## 第一步：连接中心项目（superun）
+
+注册中心项目并以本人身份登录。**注意 superun 用的是项目根地址，不带 `/rest/v1`；`--manifest` 让 `superun fn` 认得 Edge Functions。**
+
+```bash
+superun init --name cc-task-console \
+  --url https://bb41veoe8re43upmktc6.db.superun.com \
+  --anon-key eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiYW5vbiIsImlzcyI6InN1cGFiYXNlIiwiaWF0IjoxNzg0ODg4NDAwLCJleHAiOjIxMDAyNDg0MDB9.mhgBlmntm49GKhGxH4OEUX8v0yglI48mzjN1knyQ9Vk \
+  --manifest https://id--1799105425833984-40e8d3eebf4e4e18893a4b0309261dc4.superun.yun/superun/openapi.json
+```
+
+登录（拿到 token 用 token，最省事；也支持邮箱密码）：
+
+```bash
+superun login --token <你的访问令牌>
+# 或： superun login --password --email <邮箱> --pass <密码>
+```
+
+验证连上了、看得到那几张表：
+
+```bash
+superun whoami        # 能解出你的身份
+superun db tables     # 应能看到 schedules / webhook_triggers / jobs / runners / sync_meta
+```
+
+> 之后所有 `superun db ...` 都以你登录的身份执行，受 RLS 约束 —— 你只能看到/操作自己有权限的数据。这也是为什么管理走 superun，而不是拿 service key 直连。
+
+---
+
+## 第二步：安装本地 runner（cc-runner）
+
+runner 是真正在你机器上执行任务的守护进程。它走 **runner 专属通道**，令牌即身份 —— 在控制台 **Runner 页**「创建 runner」拿到 `X-Runner-Token`，填进 `--token`。
+
+> ⚠️ **安全边界（务必和用户确认）**：`--workdir` 是白名单，等于**授权云端在这台机器上、以这个目录为工作区，跑 Claude Code**（默认 `--dangerously-skip-permissions`）。只把你确实想让它操作的项目目录加进来。云端下发的任务若 workdir 不在白名单，会被本地直接拒绝执行。
+
+```bash
+cc-runner init \
+  --api https://bb41veoe8re43upmktc6.db.superun.com/functions/v1/runner-api \
+  --token <控制台 Runner 页复制的 X-Runner-Token> \
+  --workdir ~/你的项目目录
+
+cc-runner install    # 挂常驻：macOS 走 launchd（开机自启 + crash 自动拉起）；Linux 用 systemd 跑 `cc-runner start`
+cc-runner status     # 看是否已同步、launchd 是否挂载
+```
+
+这台机器的 runner 身份由 token 决定（不再手填 `--runner`）。首次心跳后，它会自动出现在控制台「看板」。想在多台机器跑，就在控制台各建一个 runner、拿各自的 token，在每台机器 `init`。
+
+验证心跳到了云端：
+
+```bash
+superun db select runners --select id,last_seen_at,version
+```
+
+---
+
+## 第三步：创建 webhook 触发器（主用途）
+
+一条触发器 = 一个回调地址 + 一段排查说明书。用 `superun db insert` 建：
+
+```bash
+superun db insert webhook_triggers --data '{
+  "name": "节点/Pod 健康告警",
+  "slug": "k8s-health",
+  "secret": "<生成一个随机串，如 openssl rand -hex 16>",
+  "prompt_template": "收到一条 K8s 告警。请只读排查：定位告警对象，看 describe / logs --previous / events / top，判断是 urgent / attention / ignore，最后给出结论和依据。不要做任何写操作。",
+  "workdir": "~/你的项目目录",
+  "runner": "<目标 runner 名，见控制台看板，如 default>",
+  "timeout_seconds": 900,
+  "dedup_paths": ["alarmPolicyInfo.policyName", "alarmObjInfo.dimensions"],
+  "dedup_window_seconds": 1800
+}'
+```
+
+字段要点：
+
+- **`slug`**：回调地址的路径段，唯一。
+- **`secret`**：调用方必须带的令牌，自己生成一个随机串。
+- **`prompt_template`**：交给 Claude 的说明书；系统会自动把原始告警 JSON 附在末尾。
+- **`runner`**：在哪台机器执行，填目标 runner 名（控制台看板里那个，由令牌决定，默认 `default`）。
+- **`dedup_paths` + `dedup_window_seconds`**：按 payload 里这几个字段的值 + 时间窗做去重，同一窗口内的重复告警只跑一次，天然抗告警风暴。
+
+拿到回调地址（把 `<slug>` `<secret>` 换成上面的值），填进腾讯云可观测→告警策略的接口回调、或 GitLab/CI 的 webhook：
+
+```
+https://bb41veoe8re43upmktc6.db.superun.com/functions/v1/hook/<slug>?token=<secret>
+```
+
+原有的飞书/邮件通知照留，这个回调是**额外加一条**。
+
+自测一下整条链路（发一条假 payload，看是否入队 → 被 runner 认领 → 跑出结论）：
+
+```bash
+curl -X POST "https://bb41veoe8re43upmktc6.db.superun.com/functions/v1/hook/<slug>?token=<secret>" \
+  -H "Content-Type: application/json" \
+  -d '{"alarmPolicyInfo":{"policyName":"点火测试"},"note":"self test, not a real alert"}'
+# 返回 {"queued":true,"jobId":"..."} 即入队成功；约 30~60s 后在「查看记录」里能看到结果
+```
+
+---
+
+## 第四步（可选）：创建定时任务
+
+定时任务走 `schedules` 表。cron（5 段：分 时 日 月 周）或一次性 `once`：
+
+```bash
+# 每个工作日 18:00 跑一次回归检查
+superun db insert schedules --data '{
+  "name": "每日回归检查",
+  "type": "cron",
+  "cron": "0 18 * * 1-5",
+  "prompt": "跑一遍冒烟测试，把失败项和可疑点总结给我。",
+  "workdir": "~/你的项目目录",
+  "runner": "<目标 runner 名，如 default>",
+  "timeout_seconds": 600
+}'
+
+# 一次性：某个时间点之后跑一次（type=once + not_before）
+superun db insert schedules --data '{
+  "name": "上线后 2 小时看效果",
+  "type": "once",
+  "not_before": "2026-08-01T12:00:00Z",
+  "prompt": "检查新功能上线后的日志和指标，判断有没有异常。",
+  "workdir": "~/你的项目目录",
+  "runner": "<目标 runner 名，如 default>"
+}'
+```
+
+定时任务由**服务器统一调度**：到期时服务器生成一条待领 job，runner `/claim` 领走执行、回填结果（和 webhook / 手动任务同一条路径）。runner 不在本地算 cron。`once` 跑成功后自动停用。
+
+---
+
+## 查看执行记录
+
+所有执行结果（webhook / 定时 / 手动）都落在 `jobs` 表 —— 定时任务到期由服务器生成 job，runner 领取执行后同样回填，历史完整。
+
+```bash
+# 最近 20 条
+superun db select jobs \
+  --select "source,status,summary,started_at,finished_at" \
+  --order "created_at.desc" --limit 20
+
+# 只看失败的
+superun db select jobs --eq status=failed --order "created_at.desc" --limit 20
+
+# 只看某个 runner
+superun db select jobs --eq runner=<目标 runner 名，如 default> --order "created_at.desc" --limit 20
+```
+
+`status` 含义：`pending` 待认领 / `claimed` 执行中 / `success` 成功 / `failed` 失败 / `timeout` 超时 / `rejected`（workdir 不在本地白名单，被拒）。`summary` 是 Claude 给出的结论，`error` 是失败原因。
+
+本地侧也能快速看：
+
+```bash
+cc-runner status                        # 同步版本、最近执行、待补传条数
+tail -f ~/.cc-runner/logs/daemon.log    # 守护进程实时日志
+```
+
+---
+
+## 运维与排查
+
+- **runner 显示离线**（看板灰点 / `last_seen_at` 很旧）：`cc-runner status` 看 launchd 是否挂载；`tail ~/.cc-runner/logs/daemon.log` 看报错。断网期间领不到新任务（纯中心化，不本地自跑）；已跑完待回填的结果攒在 outbox，恢复后自动补传。
+- **任务 `rejected`**：workdir 不在本地白名单。要么改触发器/定时的 `workdir`，要么 `cc-runner init` 时把目录加进 `--workdir`（可重复传多个）。
+- **webhook 打过去没反应**：确认地址带对了 `?token=<secret>`；`secret` 不匹配返回 401，`slug` 不存在返回 404。
+- **卸载**：`cc-runner uninstall`（配置和数据保留在 `~/.cc-runner`，需要再手删）。
+
+---
+
+## 安全边界（一句话版）
+
+- 本地只有**出站 HTTPS**，不监听任何端口 —— 告警回调打到云端，不需要在你机器上开公网入口。
+- workdir 白名单**由本地说了算**，云端下发不在白名单的目录一律拒绝执行。
+- 管理操作走 `superun` 登录身份（RLS 约束），不发 service key 给用户；runner 的访问 key 存在本地 `~/.cc-runner/config.json`（权限 0600），别提交进仓库。