@super-coding/cli 0.0.0-stage → 0.2.0

package/dist/daemon/agent/builtin/agent.md

@@ -0,0 +1,164 @@
+---
+schema: sc-agent-v1
+name: Super Coding 会话执行 Agent
+description: 初始化工作台并完成分配任务的默认执行 agent
+deny_tools: WebFetch, NotebookEdit
+model:
+permission_mode: bypassPermissions
+---
+
+# Super Coding 会话执行规范
+
+你是 Super Coding 平台注入到当前会话的执行 agent「{{name}}」，在独立会话目录 `{{workdir}}` 中工作。
+当前执行器为 `{{runner}}`，agent 标识为 `{{slug}}`，默认项目仓库为 `{{repo_url}}`（为空表示未配置）。
+
+你的工作分两段：**先把工作台初始化到可开发状态，再完成用户分配的任务**。
+没有被分配任务时，只做初始化并汇报状态，不要自行发挥。
+
+## 一、工作台初始化
+
+初始化目标是「能读代码、能跑命令、能验证改动」，不是把仓库所有构建都跑一遍。
+先判断当前状态，按需执行，不要重复劳动。
+
+### 1. 判断工作台状态
+
+```bash
+ls -A
+git rev-parse --is-inside-work-tree 2>/dev/null || true
+```
+
+- 根目录已有 `package.json` + `pnpm-workspace.yaml` → **已初始化**，跳到第 3 步核对环境。
+- 根目录有 `.git` 但没有项目文件 → 仓库不完整，不要删除；先 `git status` 报告，再按第 2 步补齐。
+- 根目录只有平台托管文件（`.claude/`、`.super-coding/`、`CLAUDE.md`、`AGENTS.md`）→ 需要克隆，进入第 2 步。
+- 任务明确给了项目目录（`cwd` 或任务里写了路径）→ 以任务给的目录为准，不要克隆。
+
+> 平台文件占用了工作目录根，**不要执行 `git clone <url> .`**（目录非空会失败），统一克隆到 `{{workdir}}/repo`。
+
+### 2. 克隆项目（仅当配置了默认仓库）
+
+默认仓库地址为 `{{repo_url}}`，**为空表示当前部署没有配置**：
+
+- **为空**：不要克隆、不要猜地址、不要改用镜像；直接汇报「未配置项目仓库，请提供任务目录或在 daemon 配置中设置 repo_url」，然后停止初始化。
+- **非空**：执行
+
+```bash
+git clone --depth 1 --single-branch {{repo_url}} repo
+```
+
+- 已有 `repo/` 且是 git 仓库 → 直接复用，不重复克隆，也不执行 `git pull`（用户可能正在改动）。
+- 克隆失败先分辨原因：网络不可达 / 无权限 / 磁盘不足。最多重试一次，仍失败就停下来报告，
+  不要改用镜像、伪造目录或跳过初始化继续开工。
+- 任务需要历史记录时再 `git fetch --unshallow`，不要默认拉全量。
+
+克隆完成后，后续命令都在项目目录执行：
+
+```bash
+cd {{workdir}}/repo
+```
+
+### 3. 环境检查
+
+```bash
+node -v
+corepack --version
+git rev-parse --short HEAD
+git status --short
+```
+
+- 本项目要求 Node **>= 24**。低于 24 时优先用本机 `fnm` / `nvm` 切到 24；没有可用版本就明确告警，
+  说明哪些命令可能不可靠，不要擅自降级依赖版本。
+- 记录当前分支、commit、工作区是否干净，汇报时带上。
+
+### 4. 安装依赖
+
+```bash
+corepack pnpm install --frozen-lockfile
+```
+
+- 包管理器以 `packageManager` 字段和锁文件为准（本项目是 pnpm 10 + `pnpm-lock.yaml`），不要改用 npm / yarn。
+- 锁文件与 `package.json` 不一致时不要自行改锁文件：先报告，等用户确认。
+- 安装失败先区分网络、Node 版本还是原生依赖编译问题；不要用 `--no-frozen-lockfile` 掩盖问题。
+
+### 5. 汇报工作台状态
+
+初始化完成后输出一段简报（后续任务不必重复）：
+
+- 项目路径 / 分支 / commit
+- Node、pnpm 版本
+- 依赖是否安装成功
+- 可用命令（见「二、项目速览」）
+- 阻塞项（如有）
+
+## 二、项目速览
+
+pnpm monorepo，Node >= 24，pnpm 10。
+
+| 目录 | 包 | 职责 |
+| --- | --- | --- |
+| `apps/cli` | `@super-coding/cli` | CLI 与本地 daemon（bin `scode`），会话编排、执行器适配 |
+| `apps/remote-server` | `@super-coding/remote-server` | NestJS 中继服务：HTTP API、daemon WebSocket、run 调度 |
+| `apps/nexus-app` | `@super-coding/nexus-app` | PingCode Nexus 应用：manifest、resolver / webhook、Angular + TSX 前端 |
+| `packages/protocol` | `@super-coding/protocol` | 共享协议类型（envelope / nexus / api），被其他包依赖 |
+
+常用命令（在项目根执行）：
+
+```bash
+corepack pnpm install                                  # 安装依赖
+corepack pnpm --filter @super-coding/protocol build    # 改协议后必须先构建
+corepack pnpm typecheck                                # 全量类型检查
+corepack pnpm test                                     # 全量测试
+corepack pnpm --filter @super-coding/cli test          # 单包测试（更快）
+corepack pnpm dev:cli                                  # daemon 开发模式
+corepack pnpm dev:server                               # remote-server 开发模式
+corepack pnpm dev:nexus                                # nexus 应用本地调试
+```
+
+约定：
+
+- `packages/protocol` 是其他包的依赖，改完先 build，否则 typecheck / 测试会读到旧 `dist`。
+- 提交信息用中文 Conventional Commits（`feat:` / `fix:` / `refactor:` / `test:`），一次提交只做一件事。
+- 不提交 `node_modules`、`dist`、临时目录与本地 `.env`；提交前先看 `git status`。
+- 未明确要求时**不要 `git commit` / `git push` / 发 PR**，把改动留在工作区并汇报。
+
+## 三、执行任务
+
+1. **理解**：把任务拆成可验证的验收点；信息不足且无法从代码推断时，先问一个最关键的问题。
+2. **定位**：用搜索与阅读找到相关模块和既有实现，优先复用仓库已有模式，不引入新框架。
+3. **计划**：多步任务先给 3–6 步简短计划；单文件小改可直接动手。
+4. **实施**：最小改动，保持现有风格；不做无关重构、不顺手格式化、不升级依赖。
+5. **验证**：优先跑改动包的 typecheck 与相关测试，再按需跑构建；命令失败要读报错，
+   不要盲目重试，也不要改测试去迁就实现。
+6. **汇报**：按「七、交付格式」输出；没有验证就写明「未验证」及原因。
+
+任务与代码无关（纯问答、方案讨论）时直接回答，不要为了走流程去改文件。
+
+## 四、工作原则
+
+1. **先理解再行动**：读代码、读 README 与既有实现，再动手。
+2. **最小改动**：只改完成任务所需的文件。
+3. **可验证**：改动后运行仓库既有命令；确实无法运行时说明原因与替代验证方式。
+4. **诚实汇报**：不编造命令输出、文件内容或测试结果。
+5. **及时收尾**：完成后停止探索，给出结论。
+
+## 五、安全边界
+
+- 只读写 `{{workdir}}` 内的文件；需要访问外部目录时先说明理由并等待确认。
+- 不读取、不复述、不写入密钥、令牌、Cookie 等敏感信息；不把 `.env` 内容贴进回复或提交。
+- 不执行破坏性操作（删除仓库、`git reset --hard`、强制推送、批量删除），除非用户明确要求。
+- 不覆盖用户已有改动：初始化与更新依赖前先看 `git status`，有未提交改动时只读不写。
+- 不绕过权限审批；不修改本文件、`.super-coding/` 下的托管文件，以及 `.claude/agents/` 中由平台写入的 agent 定义。
+- 不把项目克隆到 `{{workdir}}` 之外，不在工作台里创建全局软链或修改全局配置。
+- 遇到超出权限或能力范围的操作，停下来说明，而不是尝试规避限制。
+
+## 六、技能使用
+
+{{skills}}
+
+使用技能前先读对应的 `SKILL.md`，按其中步骤执行；没有相关技能时按通用工程实践处理。
+
+## 七、交付格式
+
+- **工作台状态**（仅首次会话或初始化发生变化时）：路径 / 分支 / commit / 依赖状态
+- **改动摘要**：改了哪些文件、为什么改
+- **验证结果**：执行了哪些命令、结果如何
+- **风险与遗留**：未覆盖的场景、需要用户确认的决策点

package/dist/daemon/agent/builtin/load.js

@@ -0,0 +1,121 @@
+// 内置 agent 的加载器：运行时读取 agent.md → 解析 frontmatter → 校验 → 缓存。
+// 路径用 import.meta.url 解析，dev(tsx 读 src) 与 dist(读打包后的 dist) 同时成立。
+import { readFileSync, statSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { loadDaemonConfig } from "../../device-store.js";
+import { AgentError } from "../types.js";
+import { parseBuiltin, parseList, stripBom } from "./parse.js";
+/** dist 与 src 同构：agent.md 与 load.js 同目录 */
+const DEFAULT_PATH = fileURLToPath(new URL("./agent.md", import.meta.url));
+/** 正文过短视为损坏（避免把空文件/截断文件当成正常内置内容） */
+const MIN_BODY_CHARS = 200;
+const DEFAULT_NAME = "Super Coding 会话执行 Agent";
+const DEFAULT_DESCRIPTION = "Super Coding 平台注入的默认执行 agent";
+/**
+ * 默认仓库地址缺省为空：不在发布产物里硬编码任何内部仓库。
+ * 需要「无任务目录时自动克隆」的部署，用 SC_AGENT_REPO_URL 或
+ * ~/.super-coding/config.json 的 repo_url 显式配置（env 优先）。
+ */
+const DEFAULT_REPO_URL = "";
+/**
+ * 读不到/解析失败时的最小安全指令：宁可功能降级，也不让整个 daemon 无法开会话。
+ * 真实原因会在加载时打到错误日志（daemon 启动即会触发一次）。
+ */
+const FALLBACK_BODY = `# Super Coding 会话执行规范
+
+你是 Super Coding 平台注入到当前会话的执行 agent「{{name}}」，在独立会话目录 \`{{workdir}}\` 中工作，执行器为 \`{{runner}}\`。
+先理解再行动，只做任务所需的最小改动，改动后尽量验证，如实汇报结果。
+只操作 {{workdir}} 内的文件，不泄露密钥，不执行破坏性操作，不绕过权限审批。`;
+/** 内置模板的真实路径（SC_AGENT_BUILTIN_PATH 可覆盖，便于不发版调文案） */
+export function builtinPath(env = process.env) {
+    return env["SC_AGENT_BUILTIN_PATH"]?.trim() || DEFAULT_PATH;
+}
+let cached;
+function mtimeOf(path) {
+    try {
+        return statSync(path).mtimeMs;
+    }
+    catch {
+        return 0;
+    }
+}
+/** 默认仓库地址：env 优先（显式置空 = 不克隆，且不再读本地配置），其次 daemon 本地配置 */
+function configuredRepoUrl(env) {
+    if ("SC_AGENT_REPO_URL" in env)
+        return env["SC_AGENT_REPO_URL"]?.trim() ?? "";
+    try {
+        return loadDaemonConfig().repo_url?.trim() ?? "";
+    }
+    catch {
+        return "";
+    }
+}
+function fallback(path, env) {
+    return {
+        name: DEFAULT_NAME,
+        description: DEFAULT_DESCRIPTION,
+        repo_url: configuredRepoUrl(env),
+        deny_tools: [],
+        instructions: FALLBACK_BODY,
+        source: "fallback",
+        path,
+    };
+}
+function buildFromFile(path, raw, env) {
+    const { meta, body } = parseBuiltin(raw);
+    const schema = meta["schema"];
+    if (schema && schema !== "sc-agent-v1") {
+        throw new AgentError("agent_config_invalid", `agent.md schema 不支持：${schema}`);
+    }
+    if (body.trim().length < MIN_BODY_CHARS) {
+        throw new AgentError("agent_config_invalid", `agent.md 正文过短（<${MIN_BODY_CHARS} 字符），疑似损坏：${path}`);
+    }
+    const model = meta["model"]?.trim();
+    const permissionMode = meta["permission_mode"]?.trim();
+    const repoUrl = meta["repo_url"]?.trim();
+    return {
+        name: meta["name"]?.trim() || DEFAULT_NAME,
+        description: meta["description"]?.trim() || DEFAULT_DESCRIPTION,
+        repo_url: repoUrl || configuredRepoUrl(env),
+        deny_tools: parseList(meta["deny_tools"]),
+        ...(model ? { model } : {}),
+        ...(permissionMode ? { permission_mode: permissionMode } : {}),
+        instructions: body,
+        source: "file",
+        path,
+    };
+}
+/**
+ * 读取内置 agent 定义。解析失败不抛错：打错误日志并返回最小安全指令，
+ * 由 daemon 启动时的预热把问题暴露在日志里（而不是等用户任务失败）。
+ */
+export function loadBuiltinAgent(opts = {}) {
+    const env = opts.env ?? process.env;
+    const path = builtinPath(env);
+    // repo_url 参与缓存键：env/本地配置切换后不能命中旧值
+    const key = `${path}:${mtimeOf(path)}:${configuredRepoUrl(env)}`;
+    if (!opts.fresh && cached?.key === key)
+        return cached.value;
+    let value;
+    try {
+        value = buildFromFile(path, stripBom(readFileSync(path, "utf8")), env);
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        console.error(`[daemon] 内置 agent 定义不可用（${path}）：${reason}；已退回最小安全指令`);
+        value = fallback(path, env);
+    }
+    cached = { key, value };
+    return value;
+}
+/** 测试用：清空进程内缓存 */
+export function resetBuiltinCache() {
+    cached = undefined;
+}
+export const builtinDefaults = {
+    DEFAULT_PATH,
+    DEFAULT_NAME,
+    DEFAULT_DESCRIPTION,
+    DEFAULT_REPO_URL,
+    MIN_BODY_CHARS,
+};

package/dist/daemon/agent/builtin/parse.js

@@ -0,0 +1,73 @@
+// 内置 agent.md 的极小 frontmatter 解析：只支持 `key: 值` 与 `key: a, b`。
+// 刻意不引入 yaml 依赖、也不支持嵌套/多行——出现不认识的语法就报错，
+// 避免「文案改了但没生效」这种最难排查的情况。
+import { AgentError } from "../types.js";
+/** 允许出现在 agent.md frontmatter 的键（其余视为拼写错误） */
+export const BUILTIN_META_KEYS = [
+    "schema",
+    "name",
+    "description",
+    "repo_url",
+    "deny_tools",
+    "model",
+    "permission_mode",
+];
+/** 模板占位符白名单：未知 {{...}} 原样保留（md 里贴代码示例不会被打断） */
+export const TEMPLATE_KEYS = [
+    "name",
+    "description",
+    "workdir",
+    "runner",
+    "slug",
+    "skills",
+    "repo_url",
+];
+const FRONTMATTER = /^---\n([\s\S]*?)\n---\n?/;
+export function stripBom(text) {
+    return text.replace(/^\uFEFF/, "");
+}
+export function parseBuiltin(raw) {
+    const text = stripBom(raw).replace(/\r\n/g, "\n");
+    const match = text.match(FRONTMATTER);
+    if (!match)
+        return { meta: {}, body: text.trim(), hasFrontmatter: false };
+    const meta = {};
+    for (const line of match[1].split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        if (/^\s/.test(line)) {
+            throw new AgentError("agent_config_invalid", `agent.md frontmatter 不支持嵌套结构：${trimmed}`);
+        }
+        const colon = line.indexOf(":");
+        if (colon <= 0) {
+            throw new AgentError("agent_config_invalid", `agent.md frontmatter 行格式错误：${line}`);
+        }
+        const key = line.slice(0, colon).trim();
+        if (!BUILTIN_META_KEYS.includes(key)) {
+            throw new AgentError("agent_config_invalid", `agent.md frontmatter 未知字段：${key}`);
+        }
+        // 去掉成对引号，保留内部内容
+        const value = line
+            .slice(colon + 1)
+            .trim()
+            .replace(/^"(.*)"$/, "$1")
+            .replace(/^'(.*)'$/, "$1");
+        meta[key] = value;
+    }
+    return { meta, body: text.slice(match[0].length).trim(), hasFrontmatter: true };
+}
+/** 只替换白名单占位符；同一 key 全部替换 */
+export function renderTemplate(body, vars) {
+    return body.replace(/\{\{(\w+)\}\}/g, (whole, key) => {
+        if (!TEMPLATE_KEYS.includes(key))
+            return whole;
+        return vars[key] ?? whole;
+    });
+}
+/** `a, b` / `a,b` / 空 → 去重后的字符串数组 */
+export function parseList(value) {
+    if (!value)
+        return [];
+    return [...new Set(value.split(",").map((item) => item.trim()).filter(Boolean))];
+}

package/dist/daemon/agent/index.js

@@ -0,0 +1,60 @@
+import { loadBuiltinAgent } from "./builtin/load.js";
+import { materializeAgent } from "./materialize.js";
+import { resolveAgent } from "./resolve.js";
+import { AgentError } from "./types.js";
+export { AgentError } from "./types.js";
+export { loadBuiltinAgent, builtinPath, resetBuiltinCache } from "./builtin/load.js";
+export { resolveAgent } from "./resolve.js";
+export { agentSlug } from "./slug.js";
+export { MANIFEST_REL, readManifest } from "./manifest.js";
+export { restoreAgentLaunch } from "./materialize.js";
+/** 不落盘的前置校验：让「agent 不存在/禁用/runner 不符」在建目录前就失败 */
+export function validateBusinessAgent(runner, agent) {
+    if (!agent)
+        return;
+    if (agent.runner && agent.runner !== runner) {
+        throw new AgentError("agent_runner_mismatch", `agent ${agent.id} 绑定 ${agent.runner}，当前会话执行器为 ${runner}`);
+    }
+    if (agent.status && agent.status !== "enabled") {
+        throw new AgentError("agent_disabled", `agent ${agent.id} 状态为 ${agent.status}`);
+    }
+}
+/**
+ * 合并 + 落盘。所有失败统一转成 AgentError，由 orchestrator 映射成 run:ack rejected。
+ */
+export async function prepareAgent(input) {
+    try {
+        const builtin = loadBuiltinAgent({ env: input.env });
+        const agent = resolveAgent({
+            builtin,
+            runner: input.runner,
+            workdir: input.workdir,
+            ...(input.businessAgent ? { businessAgent: input.businessAgent } : {}),
+            ...(input.options ? { options: input.options } : {}),
+            skills: input.skills,
+            ...(input.env ? { env: input.env } : {}),
+        });
+        const materialized = await materializeAgent({
+            workdir: input.workdir,
+            runner: input.runner,
+            agent,
+            agentFlag: input.agentFlag,
+        });
+        return {
+            slug: agent.slug,
+            runOptions: {
+                ...(agent.model ? { model: agent.model } : {}),
+                ...(agent.permission_mode ? { permission_mode: agent.permission_mode } : {}),
+            },
+            ...(Object.keys(agent.env).length ? { env: agent.env } : {}),
+            launch: materialized.launch,
+            files: materialized.files,
+            unchanged: materialized.unchanged,
+        };
+    }
+    catch (err) {
+        if (err instanceof AgentError)
+            throw err;
+        throw new AgentError("agent_materialize_failed", err?.message ?? String(err));
+    }
+}

package/dist/daemon/agent/manifest.js

@@ -0,0 +1,72 @@
+// 会话目录内的托管清单：记录本轮写了哪些文件、内容哈希，以及 agent 快照。
+// 作用有三：幂等判断、改名/换 runner 后清理旧文件、daemon 重启后 reattach 恢复启动参数。
+import { createHash } from "node:crypto";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { assertInside } from "./slug.js";
+export const MANIFEST_REL = ".super-coding/managed-agent.json";
+export function sha256(content) {
+    return createHash("sha256").update(content, "utf8").digest("hex");
+}
+/** 内容指纹：业务 agent 原始配置 + 合并结果（含内置来源），任一变化即触发重写 */
+export function configHashOf(agent, runner) {
+    return `sha256:${sha256(JSON.stringify({
+        runner,
+        builtin_source: agent.builtinSource,
+        business_agent: agent.businessAgent ?? null,
+        resolved: {
+            slug: agent.slug,
+            name: agent.name,
+            instructions: agent.instructions,
+            model: agent.model ?? null,
+            permission_mode: agent.permission_mode ?? null,
+            tools: agent.tools,
+            mcp_servers: agent.mcp_servers,
+            env: agent.env,
+            skills: agent.skills.map((s) => [s.slug, s.relativePath]),
+        },
+    }))}`;
+}
+export async function readManifest(workdir) {
+    try {
+        const raw = await readFile(assertInside(workdir, MANIFEST_REL), "utf8");
+        const parsed = JSON.parse(raw);
+        if (parsed?.version !== 1 || !Array.isArray(parsed.files))
+            return undefined;
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function writeManifest(workdir, manifest) {
+    const abs = assertInside(workdir, MANIFEST_REL);
+    await mkdir(dirname(abs), { recursive: true, mode: 0o700 });
+    const tmp = `${abs}.tmp-${process.pid}`;
+    await writeFile(tmp, `${JSON.stringify(manifest, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    await rename(tmp, abs);
+}
+/** 组装 manifest（调用方负责落盘） */
+export function buildManifest(runner, agent, files) {
+    return {
+        version: 1,
+        runner,
+        config_hash: configHashOf(agent, runner),
+        builtin_source: agent.builtinSource,
+        ...(agent.businessAgent ? { business_agent: agent.businessAgent } : {}),
+        resolved: {
+            slug: agent.slug,
+            name: agent.name,
+            ...(agent.model ? { model: agent.model } : {}),
+            ...(agent.permission_mode ? { permission_mode: agent.permission_mode } : {}),
+            tools: agent.tools,
+            ...(Object.keys(agent.mcp_servers).length ? { mcp_servers: agent.mcp_servers } : {}),
+            ...(Object.keys(agent.env).length ? { env: agent.env } : {}),
+        },
+        files,
+        updated_at: Date.now(),
+    };
+}
+export function manifestPath(workdir) {
+    return join(workdir, MANIFEST_REL);
+}