@super-coding/cli 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,71 @@
-# Temporary Holding Version
+# @super-coding/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+把本机的 **Claude Code** / **Cursor** 作为执行器接入 Super Coding 控制台：远端下发任务，本地 daemon 在独立会话目录中执行并回传过程与结果。
+
+包名是 `@super-coding/cli`，安装后提供的命令是 **`scode`**。
+
+## 环境要求
+
+- Node.js **>= 24**
+- 已安装并登录 `claude`（Claude Code CLI）或 `cursor-agent`，运行时按需探测，未安装的执行器不会上报
+
+## 安装与启动
+
+```bash
+npm install -g @super-coding/cli
+scode daemon            # 后台启动（等价于 scode daemon start）
+```
+
+首次启动且本地没有设备凭证时，会在终端输出 6 位配对码，按提示在控制台完成配对；凭证写入 `~/.super-coding/daemon.json`（权限 `0600`）。
+
+## 命令
+
+```bash
+scode daemon              # 后台启动（已在运行则提示）
+scode daemon start        # 同上
+scode daemon stop         # 停止（SIGTERM，超时 SIGKILL）
+scode daemon restart      # 重启
+scode daemon status       # 状态（pid / 服务地址 / 心跳）
+scode daemon logs [-f] [-n 50]   # 查看日志，-f 持续输出
+scode daemon run          # 前台运行（调试或交给外部 supervisor）
+```
+
+## 配置
+
+配置文件：`~/.super-coding/config.json`（目录可用 `SC_HOME` 覆盖）。
+
+| 字段 | 说明 |
+| --- | --- |
+| `allowedCwds` | `run:start` 允许的 cwd 前缀白名单；缺省不限制 |
+| `repo_url` | 默认项目仓库地址：任务未给目录时，内置 agent 会克隆它到会话目录的 `repo/`；缺省为空（不克隆） |
+
+环境变量：
+
+| 变量 | 说明 |
+| --- | --- |
+| `DAEMON_SERVER_URL` | 中转服务 WebSocket 地址（默认连接 Super Coding 官方中转；自建/本地调试时覆盖） |
+| `DAEMON_SERVER_HTTP_URL` | 配对等 HTTP 基址；缺省由 WS 地址推导 |
+| `SC_HOME` | 配置与运行目录，默认 `~/.super-coding` |
+| `SC_AGENT_REPO_URL` | 默认项目仓库地址，优先级高于配置文件的 `repo_url`；显式置空表示不克隆 |
+| `SC_AGENT_INJECTION=off` | 关闭 agent 注入（不写 agent 文件、不声明能力），退回旧行为 |
+| `SC_ALLOW_BYPASS_PERMISSIONS=0` | 禁止 `bypassPermissions`，任务执行前需要审批 |
+| `SC_AGENT_BUILTIN_PATH` | 覆盖内置 agent 定义文件路径（调文案用） |
+
+## 安全与数据说明
+
+daemon 本质上是**把本机作为远程执行器**，请只在可信环境中使用：
+
+- **任务执行**：远端下发的任务在本机会话目录（`~/.super-coding/workspaces/session-*`）中执行。内置 agent 默认 `permission_mode: bypassPermissions`（无人值守，不会弹审批），默认禁用 `WebFetch`、`NotebookEdit`。需要收紧时设置 `SC_ALLOW_BYPASS_PERMISSIONS=0`。
+- **凭证**：设备 token 仅在配对时明文出现一次，落盘为 `~/.super-coding/daemon.json`（`0600`），不会写入日志或上报。
+- **会上传的内容**：执行事件与日志、会话目录路径、执行器与模型配置摘要、任务提示词及执行输出。
+- **MCP 配置**：`mcp:list` 只返回 `env` / `headers` 的**键名**，值统一脱敏为 `***`；原样回写时保留磁盘上的真实值，显式改值才会覆盖。
+- **本地日志**：`~/.super-coding/daemon.log` 含执行路径与任务信息，默认按当前 umask 创建，建议自行收紧权限。
+
+## 开发
+
+```bash
+pnpm --filter @super-coding/cli build      # 构建（先构建 protocol，再编译并拷贝 agent.md）
+pnpm --filter @super-coding/cli test       # 单测
+pnpm --filter @super-coding/cli typecheck
+pnpm dev:cli                               # daemon 开发模式
+```

package/dist/cli.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { Command } from "commander";
+import { logsDaemon, restartDaemon, runDaemonForeground, startDaemon, statusDaemon, stopDaemon, } from "./daemon/manage.js";
+import { connectPingcode, disconnectPingcode, printPingcodeStatus } from "./pingcode/index.js";
+const pkg = createRequire(import.meta.url)("../package.json");
+const program = new Command();
+program.name("scode").version(pkg.version).description("super-coding CLI");
+/** 统一错误出口：失败打印一行并以退出码 1 结束 */
+async function run(fn) {
+    try {
+        await fn();
+    }
+    catch (err) {
+        console.error(err?.message ?? String(err));
+        process.exitCode = 1;
+    }
+}
+const daemon = program
+    .command("daemon")
+    .description("本地守护进程：连接 remote-server，编排本机 AI agent（默认后台启动）")
+    .action(() => run(() => startDaemon())); // 裸命令 = start
+daemon.command("start").description("后台启动守护进程（已在运行则提示）").action(() => run(() => startDaemon()));
+daemon.command("stop").description("停止守护进程（SIGTERM→SIGKILL 兜底）").action(() => run(() => stopDaemon()));
+daemon.command("restart").description("重启守护进程").action(() => run(() => restartDaemon()));
+daemon.command("status").description("查看守护进程状态").action(() => run(() => statusDaemon()));
+daemon
+    .command("logs")
+    .description("查看守护进程日志")
+    .option("-f, --follow", "持续输出新日志（tail -f 语义）")
+    .option("-n, --lines <n>", "显示行数", "50")
+    .action((opts) => run(() => logsDaemon({ follow: !!opts.follow, lines: Number(opts.lines) || 50 })));
+daemon.command("run").description("前台运行（调试/外部 supervisor 托管）").action(() => run(() => runDaemonForeground()));
+// 嵌套命令默认无 help 子命令；补上使 `daemon help` 可用（npm 会吞掉 -h，`help` 是 npm 安全路径）
+daemon.addHelpCommand("help [command]");
+const pingcode = program
+    .command("pingcode")
+    .description("PingCode（pc）集成：保存本机凭据、查看可用性");
+pingcode
+    .command("status")
+    .description("查看 pc 二进制、凭据来源与凭据注入方式")
+    .action(() => run(() => printPingcodeStatus()));
+pingcode
+    .command("connect")
+    .description("保存 PingCode 凭据（写入 ~/.super-coding/pingcode.json，权限 0600）")
+    .option("--token <token>", "用户令牌（以个人身份调用）")
+    .option("--client-id <id>", "应用 Client ID（与 client-secret 成对）")
+    .option("--client-secret <secret>", "应用 Client Secret")
+    .option("--base-url <url>", "Open API 地址（默认 https://open.pingcode.com；私有部署填 https://<host>/open）")
+    .option("--no-verify", "跳过 client 凭据的令牌换取校验")
+    .action((opts) => run(() => connectPingcode(opts)));
+pingcode
+    .command("disconnect")
+    .description("删除本地 PingCode 凭据")
+    .action(() => run(() => disconnectPingcode()));
+pingcode.addHelpCommand("help [command]");
+await program.parseAsync();

package/dist/daemon/adapters/base.js

@@ -0,0 +1,37 @@
+/** push/close 异步队列：AgentSession 的事件缓冲 */
+export class EventQueue {
+    buffer = [];
+    waiters = [];
+    ended = false;
+    push(event) {
+        if (this.ended)
+            return;
+        const waiter = this.waiters.shift();
+        if (waiter) {
+            waiter({ value: event, done: false });
+        }
+        else {
+            this.buffer.push(event);
+        }
+    }
+    end() {
+        if (this.ended)
+            return;
+        this.ended = true;
+        for (const waiter of this.waiters.splice(0)) {
+            waiter({ value: undefined, done: true });
+        }
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: () => {
+                const buffered = this.buffer.shift();
+                if (buffered !== undefined)
+                    return Promise.resolve({ value: buffered, done: false });
+                if (this.ended)
+                    return Promise.resolve({ value: undefined, done: true });
+                return new Promise((resolve) => this.waiters.push(resolve));
+            },
+        };
+    }
+}

package/dist/daemon/adapters/claude-code.js

@@ -0,0 +1,184 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { createInterface } from "node:readline";
+import { EventQueue } from "./base.js";
+/** binary 以 .mjs 结尾时用当前 node 执行（测试注入 fake CLI） */
+const spawnCli = (binary, args, cwd, extraEnv) => {
+    const env = extraEnv ? { ...process.env, ...extraEnv } : process.env;
+    if (binary.endsWith(".mjs")) {
+        return spawn(process.execPath, [binary, ...args], { cwd, stdio: ["pipe", "pipe", "inherit"], env });
+    }
+    return spawn(binary, args, { cwd, stdio: ["pipe", "pipe", "inherit"], env });
+};
+class ClaudeCodeSession {
+    opts;
+    queue = new EventQueue();
+    proc;
+    sawDone = false;
+    constructor(opts) {
+        this.opts = opts;
+        const binary = opts.binary ?? "claude";
+        const { model, permission_mode, resume_session_id } = opts.options ?? {};
+        this.proc = spawnCli(binary, [
+            "-p", "--output-format", "stream-json", "--input-format", "stream-json", "--verbose",
+            ...(model ? ["--model", model] : []),
+            ...(permission_mode ? ["--permission-mode", permission_mode] : []),
+            ...(resume_session_id ? ["--resume", resume_session_id] : []),
+            // 以平台物化的原生 agent 作为主会话身份（版本不支持时由 orchestrator 降级为 CLAUDE.md）
+            ...(opts.agentName ? ["--agent", opts.agentName] : []),
+            // 只认本轮下发的 MCP 配置，与用户 ~/.claude.json 隔离
+            ...(opts.mcpConfigPath ? ["--mcp-config", opts.mcpConfigPath, "--strict-mcp-config"] : []),
+            // variadic 必须放最后（不然后续 flag 会被当成工具名）
+            ...(opts.disallowedTools?.length ? ["--disallowedTools", ...opts.disallowedTools] : []),
+        ], opts.cwd, opts.env);
+        // spawn 失败（如 agent 未安装 ENOENT）：语义化 error + done，不静默悬挂
+        this.proc.on("error", (err) => {
+            this.sawDone = true;
+            this.queue.push({ kind: "error", message: `spawn ${binary} failed: ${err.message}`, retryable: false });
+            this.queue.push({ kind: "done", status: "failed" });
+            this.queue.end();
+        });
+        // 首条 user 消息（prompt）；空 prompt（如 resume 重挂）则不写，由 sendMessage 驱动
+        if (opts.prompt) {
+            this.write({
+                type: "user",
+                message: { role: "user", content: [{ type: "text", text: opts.prompt }] },
+                parent_tool_use_id: null,
+            });
+        }
+        const rl = createInterface({ input: this.proc.stdout });
+        rl.on("line", (line) => {
+            let msg;
+            try {
+                msg = JSON.parse(line);
+            }
+            catch {
+                return;
+            }
+            for (const event of this.normalize(msg)) {
+                this.queue.push(event);
+            }
+            if (msg.type === "result")
+                this.sawDone = true;
+        });
+        // 进程退出且 stdout 耗尽后结束迭代器
+        rl.on("close", () => {
+            if (!this.sawDone) {
+                this.queue.push({ kind: "done", status: "failed" });
+            }
+            this.queue.end();
+        });
+    }
+    *normalize(msg) {
+        if (msg.type === "system" && msg.subtype === "init") {
+            yield {
+                kind: "init",
+                agent: "claude-code",
+                session_id: msg.session_id ?? "",
+                model: msg.model,
+                capabilities: msg.capabilities ?? [],
+            };
+            return;
+        }
+        if (msg.type === "assistant") {
+            for (const block of msg.message?.content ?? []) {
+                if (block.type === "text" && block.text) {
+                    yield { kind: "text_delta", text: block.text };
+                }
+                else if ((block.type === "thinking" || block.type === "reasoning") && (block.thinking || block.text)) {
+                    yield { kind: "thinking_delta", text: block.thinking ?? block.text ?? "" };
+                }
+                else if (block.type === "tool_use") {
+                    yield {
+                        kind: "tool_call_start",
+                        tool_call_id: block.id ?? "",
+                        tool: block.name ?? "",
+                        input: block.input,
+                    };
+                }
+            }
+            return;
+        }
+        if (msg.type === "user") {
+            for (const block of msg.message?.content ?? []) {
+                if (block.type === "tool_result") {
+                    yield {
+                        kind: "tool_call_end",
+                        tool_call_id: block.tool_use_id ?? "",
+                        output: typeof block.content === "string" ? block.content : JSON.stringify(block.content),
+                        is_error: block.is_error ?? false,
+                    };
+                }
+            }
+            return;
+        }
+        if (msg.type === "control_request" && msg.request?.subtype === "can_use_tool") {
+            yield {
+                kind: "permission_request",
+                request_id: msg.request_id ?? "",
+                tool: msg.request.tool_name ?? "",
+                input: msg.request.input,
+                options: ["allow_once", "allow_always", "deny"],
+            };
+            return;
+        }
+        if (msg.type === "result") {
+            const status = msg.subtype === "success"
+                ? "succeeded"
+                : msg.subtype === "error_interrupted"
+                    ? "cancelled"
+                    : "failed";
+            const u = msg.usage;
+            const total_usage = u && (u.input_tokens != null || u.output_tokens != null)
+                ? {
+                    input_tokens: u.input_tokens ?? 0,
+                    output_tokens: u.output_tokens ?? 0,
+                    ...(u.cache_read_input_tokens != null ? { cache_read_tokens: u.cache_read_input_tokens } : {}),
+                    ...(u.cache_creation_input_tokens != null ? { cache_write_tokens: u.cache_creation_input_tokens } : {}),
+                }
+                : undefined;
+            yield { kind: "done", status, final_text: msg.result, ...(total_usage ? { total_usage } : {}) };
+            return;
+        }
+    }
+    write(obj) {
+        if (this.proc.stdin?.writable) {
+            this.proc.stdin.write(JSON.stringify(obj) + "\n");
+        }
+    }
+    async sendMessage(text) {
+        this.write({
+            type: "user",
+            message: { role: "user", content: [{ type: "text", text }] },
+            parent_tool_use_id: null,
+        });
+    }
+    async respondPermission(request_id, decision) {
+        this.write({
+            type: "control_response",
+            response: {
+                request_id: request_id,
+                response: { behavior: decision === "deny" ? "deny" : "allow" },
+            },
+        });
+    }
+    async interrupt() {
+        this.write({
+            type: "control_request",
+            request_id: randomUUID(),
+            request: { subtype: "interrupt" },
+        });
+    }
+    async close() {
+        this.proc.kill("SIGTERM");
+        this.queue.end();
+    }
+    [Symbol.asyncIterator]() {
+        return this.queue[Symbol.asyncIterator]();
+    }
+}
+export const claudeCodeAdapter = {
+    id: "claude-code",
+    capabilities: { can_interactive_approve: true, can_resume: true, can_steer: true },
+    start: async (opts) => new ClaudeCodeSession(opts),
+};

package/dist/daemon/adapters/cursor.js

@@ -0,0 +1,138 @@
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { EventQueue } from "./base.js";
+/** binary 以 .mjs 结尾时用当前 node 执行（测试注入 fake CLI） */
+const spawnCli = (binary, args, cwd, extraEnv) => {
+    const env = extraEnv ? { ...process.env, ...extraEnv } : process.env;
+    if (binary.endsWith(".mjs")) {
+        return spawn(process.execPath, [binary, ...args], { cwd, stdio: ["pipe", "pipe", "inherit"], env });
+    }
+    return spawn(binary, args, { cwd, stdio: ["pipe", "pipe", "inherit"], env });
+};
+/**
+ * cursor-agent 适配器：单向流（无 stdin 协议）。
+ * 多轮通过 respawn 实现：sendMessage 等当前进程退出后以 `--resume <chatId>` 重新拉起。
+ * 不支持运行中审批（启动即 --force），respondPermission 抛错。
+ */
+class CursorSession {
+    opts;
+    queue = new EventQueue();
+    proc;
+    session_id;
+    closed = false;
+    constructor(opts) {
+        this.opts = opts;
+        this.session_id = opts.options?.resume_session_id;
+        // 空 prompt（resume 重挂）：延迟到 sendMessage 才拉起进程
+        if (opts.prompt)
+            this.spawnTurn(opts.prompt, this.session_id);
+    }
+    spawnTurn(prompt, resumeId) {
+        const binary = this.opts.binary ?? "cursor-agent";
+        const args = [
+            "-p", "--output-format", "stream-json", "--force",
+            ...(this.opts.options?.model ? ["--model", this.opts.options.model] : []),
+            ...(resumeId ? ["--resume", resumeId] : []),
+            prompt,
+        ];
+        this.proc = spawnCli(binary, args, this.opts.cwd, this.opts.env);
+        // spawn 失败（如 agent 未安装 ENOENT）：语义化 error + done
+        this.proc.on("error", (err) => {
+            this.queue.push({ kind: "error", message: `spawn ${binary} failed: ${err.message}`, retryable: false });
+            this.queue.push({ kind: "done", status: "failed" });
+            this.proc = undefined;
+        });
+        const rl = createInterface({ input: this.proc.stdout });
+        rl.on("line", (line) => {
+            let msg;
+            try {
+                msg = JSON.parse(line);
+            }
+            catch {
+                return;
+            }
+            for (const event of this.normalize(msg)) {
+                this.queue.push(event);
+            }
+        });
+        rl.on("close", () => {
+            // 单轮结束：迭代器保持打开，等待 sendMessage 开启下一轮或 close() 终结
+            this.proc = undefined;
+        });
+    }
+    *normalize(msg) {
+        if (msg.type === "system" && msg.subtype === "init") {
+            this.session_id = msg.session_id;
+            yield { kind: "init", agent: "cursor", session_id: msg.session_id ?? "", capabilities: [] };
+            return;
+        }
+        if (msg.type === "assistant") {
+            for (const block of msg.message?.content ?? []) {
+                if (block.type === "text" && block.text) {
+                    yield { kind: "text_delta", text: block.text };
+                }
+                else if ((block.type === "thinking" || block.type === "reasoning") && (block.thinking || block.text)) {
+                    yield { kind: "thinking_delta", text: block.thinking ?? block.text ?? "" };
+                }
+                else if (block.type === "tool_use") {
+                    yield {
+                        kind: "tool_call_start",
+                        tool_call_id: block.id ?? "",
+                        tool: block.name ?? "",
+                        input: block.input,
+                    };
+                }
+            }
+            return;
+        }
+        if (msg.type === "user") {
+            for (const block of msg.message?.content ?? []) {
+                if (block.type === "tool_result") {
+                    yield {
+                        kind: "tool_call_end",
+                        tool_call_id: block.tool_use_id ?? "",
+                        output: typeof block.content === "string" ? block.content : JSON.stringify(block.content),
+                        is_error: block.is_error ?? false,
+                    };
+                }
+            }
+            return;
+        }
+        if (msg.type === "result") {
+            yield {
+                kind: "done",
+                status: msg.subtype === "success" ? "succeeded" : "failed",
+                final_text: msg.result,
+            };
+            return;
+        }
+    }
+    async sendMessage(text) {
+        if (this.closed)
+            return;
+        // 等当前轮进程退出后 respawn（fake/真实 CLI 都会在 result 后退出）
+        if (this.proc) {
+            await new Promise((resolve) => this.proc.once("exit", () => resolve()));
+        }
+        this.spawnTurn(text, this.session_id);
+    }
+    async respondPermission() {
+        throw new Error("cursor 不支持运行中审批");
+    }
+    async interrupt() {
+        this.proc?.kill("SIGTERM");
+    }
+    async close() {
+        this.closed = true;
+        this.proc?.kill("SIGTERM");
+        this.queue.end();
+    }
+    [Symbol.asyncIterator]() {
+        return this.queue[Symbol.asyncIterator]();
+    }
+}
+export const cursorAdapter = {
+    id: "cursor",
+    capabilities: { can_interactive_approve: false, can_resume: true, can_steer: false },
+    start: async (opts) => new CursorSession(opts),
+};

package/dist/daemon/adapters/features.js

@@ -0,0 +1,51 @@
+// runner 能力探测：决定能否用 --agent 让原生 agent 成为主会话身份。
+// 探测失败不阻塞启动（按不支持处理），结果进程内缓存一次。
+import { execFile } from "node:child_process";
+const UNSUPPORTED = { agentFlag: false, strictMcp: false };
+const cache = new Map();
+/** SC_CLAUDE_AGENT_FLAG=1/0 可强制覆盖（运维应急 / 灰度） */
+function override() {
+    const value = process.env["SC_CLAUDE_AGENT_FLAG"];
+    if (value === "1")
+        return true;
+    if (value === "0")
+        return false;
+    return undefined;
+}
+function probeHelp(binary) {
+    return new Promise((resolve) => {
+        execFile(binary, ["--help"], { timeout: 5_000, maxBuffer: 1024 * 1024 }, (err, stdout) => {
+            // 多数 CLI --help 退出码为 0；非 0 但有输出也照常解析
+            resolve(err && !stdout ? "" : String(stdout ?? ""));
+        });
+    });
+}
+/**
+ * 探测 runner 能力。cursor 没有对应 flag，直接返回不支持；
+ * 未知 runner 一律按「只支持主指令文件」处理。
+ */
+export async function detectRunnerFeatures(runner, binary) {
+    if (runner !== "claude-code")
+        return UNSUPPORTED;
+    const key = `${runner}:${binary}`;
+    const cached = cache.get(key);
+    if (cached)
+        return cached;
+    const forced = override();
+    if (forced !== undefined) {
+        const features = { agentFlag: forced, strictMcp: true };
+        cache.set(key, features);
+        return features;
+    }
+    const help = await probeHelp(binary);
+    const features = {
+        agentFlag: /--agent\b/.test(help),
+        strictMcp: /--mcp-config\b/.test(help),
+    };
+    cache.set(key, features);
+    return features;
+}
+/** 测试用：清空探测缓存 */
+export function resetFeatureCache() {
+    cache.clear();
+}

package/dist/daemon/adapters/registry.js

@@ -0,0 +1,9 @@
+import { claudeCodeAdapter } from './claude-code.js';
+import { cursorAdapter } from './cursor.js';
+/** agent_id → adapter */
+export const adapters = new Map([claudeCodeAdapter, cursorAdapter].map(a => [a.id, a]));
+/** agent_id → 本机 CLI 可执行文件名（detectAgents 探测用） */
+export const agentBinaries = {
+    'claude-code': 'claude',
+    cursor: 'cursor-agent',
+};