niceeval 0.5.4 → 0.6.1

package/src/agents/skills.test.ts

@@ -0,0 +1,214 @@
+// SkillSpec 安装的单测:本地形状(目录 / 单文件 / 不支持)、repo 的 ref 钉定与选择规则、
+// manifest 记录形状、以及「setup 装进 workspace 的东西不算 agent diff」这条护栏。
+// 沙箱是内存 fake(记命令 + 记文件),不起容器:这里要验的是 adapter 侧的翻译规则,
+// 不是 provider 的执行。
+
+import { describe, expect, it } from "vitest";
+import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { installSkills, installedSkillNames, skillDiscoveryInstruction } from "./skills.ts";
+import { AGENT_SETUP_MANIFEST_PATH, readAgentSetupManifest, writeAgentSetupManifest } from "./manifest.ts";
+import type { CommandResult, Sandbox, SandboxFile } from "../types.ts";
+
+/** 内存沙箱:runShell 记命令(可按前缀脚本化输出),writeFiles/uploadFiles 记文件。 */
+class FakeSandbox implements Partial<Sandbox> {
+  readonly workdir = "/workspace";
+  readonly sandboxId = "fake";
+  readonly otlpHost = null;
+  readonly commands: string[] = [];
+  readonly files = new Map<string, string>();
+  /** 命令 → 输出(按命令算,因为 clone 目录是随机的);没命中就是 exit 0、空输出。 */
+  script: { match: string; result: (cmd: string) => Partial<CommandResult> }[] = [];
+
+  async runShell(script: string): Promise<CommandResult> {
+    this.commands.push(script);
+    const hit = this.script.find((s) => script.includes(s.match));
+    return { stdout: "", stderr: "", exitCode: 0, ...hit?.result(script) };
+  }
+  async writeFiles(files: Record<string, string>, targetDir?: string): Promise<void> {
+    for (const [path, content] of Object.entries(files)) {
+      this.files.set(targetDir ? `${targetDir}/${path}` : path, content);
+    }
+  }
+  async uploadFiles(files: SandboxFile[], targetDir?: string): Promise<void> {
+    for (const f of files) {
+      this.files.set(targetDir ? `${targetDir}/${f.path}` : f.path, f.content.toString());
+    }
+  }
+  async fileExists(): Promise<boolean> {
+    return false;
+  }
+  async readFile(path: string): Promise<string> {
+    const hit = this.files.get(path);
+    if (hit === undefined) throw new Error(`no such file: ${path}`);
+    return hit;
+  }
+}
+
+const sb = (s?: FakeSandbox["script"]): FakeSandbox => {
+  const box = new FakeSandbox();
+  if (s) box.script = s;
+  return box;
+};
+const asSandbox = (box: FakeSandbox): Sandbox => box as unknown as Sandbox;
+
+async function skillProject(): Promise<string> {
+  const root = await mkdtemp(join(tmpdir(), "niceeval-skills-"));
+  await mkdir(join(root, "skills", "effect-ts"), { recursive: true });
+  await writeFile(join(root, "skills", "effect-ts", "SKILL.md"), "# Effect\nuse Effect\n", "utf-8");
+  await writeFile(join(root, "skills", "effect-ts", "reference.md"), "layers\n", "utf-8");
+  await writeFile(join(root, "skills", "repository-guide.md"), "# Repo guide\n", "utf-8");
+  await mkdir(join(root, "skills", "broken"), { recursive: true });
+  await writeFile(join(root, "skills", "broken", "notes.md"), "no SKILL.md here\n", "utf-8");
+  return root;
+}
+
+describe("installSkills · 本地 Skill", () => {
+  it("目录形态按原样上传(名字取目录名),单文件形态落成 <name>/SKILL.md(SKILL.md 取所在目录名);manifest 记 sha256", async () => {
+    const root = await skillProject();
+    try {
+      const box = sb();
+      const skills = await installSkills(
+        asSandbox(box),
+        [
+          { kind: "local", path: "skills/effect-ts" },
+          { kind: "local", path: "skills/effect-ts/SKILL.md" },
+          { kind: "local", path: "skills/repository-guide.md", name: "repo-guide" },
+        ],
+        { dir: ".claude/skills", projectRoot: root },
+      );
+
+      expect(skills.map((s) => s.kind === "local" && s.name)).toEqual(["effect-ts", "effect-ts", "repo-guide"]);
+      expect(box.files.get(".claude/skills/effect-ts/SKILL.md")).toContain("use Effect");
+      expect(box.files.get(".claude/skills/effect-ts/reference.md")).toBe("layers\n");
+      expect(box.files.get(".claude/skills/repo-guide/SKILL.md")).toBe("# Repo guide\n");
+      // sha256 是内容哈希:目录(两个文件)与单文件(只有 SKILL.md)不是同一份内容 → 不同哈希
+      const hashes = skills.map((s) => (s.kind === "local" ? s.sha256 : ""));
+      expect(hashes[0]).toMatch(/^[0-9a-f]{64}$/);
+      expect(hashes[0]).not.toBe(hashes[1]);
+      // setup 装进 workspace 的目录排除出 agent diff(git 基线早于 agent.setup)
+      expect(box.commands.some((c) => c.includes(".git/info/exclude") && c.includes(".claude/skills/"))).toBe(true);
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it("路径不存在 / 目录里没有 SKILL.md / 不是 .md 文件:setup 失败并说明原因", async () => {
+    const root = await skillProject();
+    try {
+      await expect(
+        installSkills(asSandbox(sb()), [{ kind: "local", path: "skills/nope" }], { dir: ".claude/skills", projectRoot: root }),
+      ).rejects.toThrow(/does not exist|不存在/);
+
+      await expect(
+        installSkills(asSandbox(sb()), [{ kind: "local", path: "skills/broken" }], { dir: ".claude/skills", projectRoot: root }),
+      ).rejects.toThrow(/SKILL\.md/);
+
+      await expect(
+        installSkills(asSandbox(sb()), [{ kind: "local", path: "skills/broken/notes.txt" }], {
+          dir: ".claude/skills",
+          projectRoot: root,
+        }),
+      ).rejects.toThrow(/does not exist|不存在/);
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("installSkills · repo Skill", () => {
+  /** clone 目录是随机的:find 的假输出从命令里把它抠出来再拼 SKILL.md 路径。 */
+  const cloneDirOf = (cmd: string): string => /find '([^']+)'/.exec(cmd)![1]!;
+  // repo 根就有 SKILL.md → 整个 repo 是一个 skill(名字取 repo 名)
+  const oneSkill = [{ match: "find", result: (cmd: string) => ({ stdout: `${cloneDirOf(cmd)}/SKILL.md\n` }) }];
+  // 多 skill repo:每个含 SKILL.md 的目录一个
+  const manySkills = [
+    {
+      match: "find",
+      result: (cmd: string) => ({
+        stdout: `${cloneDirOf(cmd)}/skills/effect/SKILL.md\n${cloneDirOf(cmd)}/skills/effect-sql/SKILL.md\n`,
+      }),
+    },
+  ];
+
+  it("repo 只有一个 skill、省略 skills:装唯一那个(名字取 repo 名);ref 钉定走完整 clone + checkout", async () => {
+    const box = sb(oneSkill);
+    const skills = await installSkills(
+      asSandbox(box),
+      [{ kind: "repo", source: "Effect-TS/skills", ref: "8f3c1a2" }],
+      { dir: ".agents/skills" },
+    );
+
+    expect(skills).toEqual([{ kind: "repo", source: "Effect-TS/skills", ref: "8f3c1a2", skills: ["skills"] }]);
+    const clone = box.commands.find((c) => c.includes("git clone"))!;
+    expect(clone).toContain("https://github.com/Effect-TS/skills.git");
+    expect(clone).not.toContain("--depth 1"); // 任意 commit checkout 不到浅克隆里
+    expect(clone).toContain("checkout --quiet '8f3c1a2'");
+    expect(box.commands.some((c) => c.includes("cp -R") && c.includes(".agents/skills/skills"))).toBe(true);
+  });
+
+  it("省略 ref → 浅克隆;repo 有多个 skill 而没给 skills → 失败并列出可选集", async () => {
+    const box = sb(oneSkill);
+    await installSkills(asSandbox(box), [{ kind: "repo", source: "Effect-TS/skills" }], { dir: ".agents/skills" });
+    expect(box.commands.find((c) => c.includes("git clone"))).toContain("--depth 1");
+
+    await expect(
+      installSkills(asSandbox(sb(manySkills)), [{ kind: "repo", source: "Effect-TS/skills" }], { dir: ".agents/skills" }),
+    ).rejects.toThrow(/effect, effect-sql/);
+  });
+
+  it("选中的 skill 不存在 → 失败并报 source / ref / 可选集;选中子集 → 只装选中的", async () => {
+    await expect(
+      installSkills(
+        asSandbox(sb(manySkills)),
+        [{ kind: "repo", source: "Effect-TS/skills", ref: "v1", skills: ["effect", "nope"] }],
+        { dir: ".agents/skills" },
+      ),
+    ).rejects.toThrow(/nope/);
+
+    const box = sb(manySkills);
+    const skills = await installSkills(
+      asSandbox(box),
+      [{ kind: "repo", source: "Effect-TS/skills", skills: ["effect"] }],
+      { dir: ".agents/skills" },
+    );
+    expect(skills).toEqual([{ kind: "repo", source: "Effect-TS/skills", skills: ["effect"] }]);
+    const copies = box.commands.filter((c) => c.includes("cp -R"));
+    expect(copies).toHaveLength(1);
+    expect(copies[0]).toContain(".agents/skills/effect");
+  });
+});
+
+describe("发现指引 / manifest", () => {
+  it("skillDiscoveryInstruction 逐条点名装好的 skill 路径(没有它 codex/bub 不会去读)", () => {
+    const text = skillDiscoveryInstruction(".agents/skills", ["effect", "repo-guide"]);
+    expect(text).toContain(".agents/skills/effect/SKILL.md");
+    expect(text).toContain(".agents/skills/repo-guide/SKILL.md");
+    expect(text).toMatch(/read its `SKILL\.md`/);
+  });
+
+  it("installedSkillNames 把 local / repo 两种记录摊平成目录名", () => {
+    expect(
+      installedSkillNames([
+        { kind: "local", name: "repo-guide", path: "skills/repo.md", sha256: "x" },
+        { kind: "repo", source: "Effect-TS/skills", skills: ["effect", "effect-sql"] },
+      ]),
+    ).toEqual(["repo-guide", "effect", "effect-sql"]);
+  });
+
+  it("manifest 写进沙箱固定路径,读回同一份;没写过 → undefined(不生成空 artifact)", async () => {
+    const box = sb();
+    expect(await readAgentSetupManifest(asSandbox(box))).toBeUndefined();
+
+    await writeAgentSetupManifest(asSandbox(box), {
+      skills: [{ kind: "repo", source: "Effect-TS/skills", ref: "8f3c1a2", skills: ["effect"] }],
+      mcpServers: [{ name: "browser", command: "npx", args: ["-y", "@modelcontextprotocol/server-browser"] }],
+    });
+
+    expect(box.files.has(AGENT_SETUP_MANIFEST_PATH)).toBe(true);
+    const back = await readAgentSetupManifest(asSandbox(box));
+    expect(back?.skills).toEqual([{ kind: "repo", source: "Effect-TS/skills", ref: "8f3c1a2", skills: ["effect"] }]);
+    expect(back?.mcpServers?.[0]?.name).toBe("browser");
+  });
+});

package/src/agents/skills.ts

@@ -0,0 +1,304 @@
+// SkillSpec 的安装实现 —— 三个内置沙箱型 adapter(claude-code / codex / bub)共用的那一半:
+// 「从哪里取得哪份 Skill」(本地目录/文件、repo + ref + 选择集)。另一半——装到哪个目录、
+// 要不要额外写发现指引——留在各 adapter 里,由它们传 `dir` 并自己写 project instruction。
+// 定稿见 docs/feature/adapters/architecture/coding-agent-extensions.md。
+//
+// 为什么不调 `npx skills add`:那个 installer 没有钉 ref 的入口,也没有机器可读的「这个 repo
+// 里有哪些 skill」输出(-l 只打人看的带 ANSI 的清单),而契约要求「来源必须可复现」(钉 ref)
+// 与「多 Skill Repo 必须明确选择启用集合」(选不中要报出可选集)。所以 repo skill 走 git:
+// clone → 枚举 SKILL.md → 按规则选 → 拷进 agent 的 skill 目录。顺带绕开了 memory 里
+// npx-skills-add-headless-hang 那个交互式选择框(无 tty 卡死)的整类问题。
+
+import { createHash } from "node:crypto";
+import { readFile, readdir, stat } from "node:fs/promises";
+import { basename, dirname, extname, join, posix, relative, resolve, sep } from "node:path";
+import { shellQuote as q } from "../sandbox/shell.ts";
+import { t } from "../i18n/index.ts";
+import type { AgentSetupSkill, Sandbox, SkillSpec } from "../types.ts";
+
+/** 沙箱里放临时 clone 的地方(装完即删;不在 workdir 下,不进 diff)。 */
+const CLONE_ROOT = "/tmp/niceeval-git";
+
+export interface InstallSkillsOptions {
+  /** 沙箱里的 Skill 安装根目录(相对 workdir):claude-code 用 `.claude/skills`,codex/bub 用 `.agents/skills`。 */
+  dir: string;
+  /** 本地 Skill 的解析根;省略用跑 niceeval 的项目根(process.cwd())。 */
+  projectRoot?: string;
+}
+
+/**
+ * 按配置顺序把 SkillSpec 装进沙箱,返回 manifest 里的 Skill 记录(与配置顺序一一对应)。
+ * 同名 Skill 来自多个来源时后装的覆盖磁盘、manifest 保留每一条(不静默合并)。
+ * 任何一条装不上(路径不存在 / 形状不支持 / clone 或 ref 解析失败 / 选择集不合法)直接抛错 ——
+ * setup 失败即 attempt errored,不伪装成断言失败。
+ */
+export async function installSkills(
+  sandbox: Sandbox,
+  specs: readonly SkillSpec[],
+  opts: InstallSkillsOptions,
+): Promise<AgentSetupSkill[]> {
+  const out: AgentSetupSkill[] = [];
+  for (const spec of specs) {
+    out.push(
+      spec.kind === "local"
+        ? await installLocalSkill(sandbox, spec, opts)
+        : await installRepoSkill(sandbox, spec, opts),
+    );
+  }
+  if (out.length) await excludeFromDiff(sandbox, [`${opts.dir}/`]);
+  return out;
+}
+
+// ───────────────────────── 本地 Skill ─────────────────────────
+
+async function installLocalSkill(
+  sandbox: Sandbox,
+  spec: Extract<SkillSpec, { kind: "local" }>,
+  opts: InstallSkillsOptions,
+): Promise<AgentSetupSkill> {
+  const root = opts.projectRoot ?? process.cwd();
+  const abs = resolve(root, spec.path);
+  const info = await stat(abs).catch(() => undefined);
+  if (!info) throw new Error(t("skill.localMissing", { path: spec.path, resolved: abs }));
+
+  if (info.isDirectory()) {
+    const files = await readDirFiles(abs);
+    if (!files.some((f) => f.path === "SKILL.md")) {
+      throw new Error(t("skill.localDirNoSkillFile", { path: spec.path }));
+    }
+    const name = spec.name ?? basename(abs);
+    const sha256 = hashFiles(files);
+    await sandbox.uploadFiles(
+      files.map((f) => ({ path: f.path, content: f.content })),
+      posix.join(opts.dir, name),
+    );
+    return { kind: "local", name, path: spec.path, sha256 };
+  }
+
+  if (!info.isFile() || extname(abs).toLowerCase() !== ".md") {
+    throw new Error(t("skill.localUnsupportedShape", { path: spec.path }));
+  }
+  const content = await readFile(abs, "utf-8");
+  const name = spec.name ?? localFileSkillName(abs);
+  await sandbox.writeFiles({ [posix.join(opts.dir, name, "SKILL.md")]: content });
+  return { kind: "local", name, path: spec.path, sha256: hashFiles([{ path: "SKILL.md", content }]) };
+}
+
+/** `skills/effect-ts/SKILL.md` → `effect-ts`(SKILL.md 的名字不含信息,取所在目录);`skills/guide.md` → `guide`。 */
+export function localFileSkillName(absPath: string): string {
+  const file = basename(absPath);
+  return file.toLowerCase() === "skill.md" ? basename(dirname(absPath)) : basename(file, extname(file));
+}
+
+/** 目录内容的确定性哈希:按相对路径排序,逐条喂 `path\0content\0`(二进制附件按原字节)。 */
+function hashFiles(files: { path: string; content: string | Buffer }[]): string {
+  const h = createHash("sha256");
+  for (const f of [...files].sort((a, b) => a.path.localeCompare(b.path))) {
+    h.update(f.path).update("\0").update(f.content).update("\0");
+  }
+  return h.digest("hex");
+}
+
+/** Skill 目录可以带脚本 / 图片等附件,一律按原字节读 + 上传,不做文本假设。 */
+async function readDirFiles(dir: string): Promise<{ path: string; content: Buffer }[]> {
+  const out: { path: string; content: Buffer }[] = [];
+  const walk = async (current: string): Promise<void> => {
+    for (const entry of await readdir(current, { withFileTypes: true })) {
+      const full = join(current, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name === ".git") continue;
+        await walk(full);
+      } else if (entry.isFile()) {
+        out.push({ path: relative(dir, full).split(sep).join("/"), content: await readFile(full) });
+      }
+    }
+  };
+  await walk(dir);
+  return out;
+}
+
+// ───────────────────────── Repo Skill ─────────────────────────
+
+async function installRepoSkill(
+  sandbox: Sandbox,
+  spec: Extract<SkillSpec, { kind: "repo" }>,
+  opts: InstallSkillsOptions,
+): Promise<AgentSetupSkill> {
+  const cloneDir = await cloneRepo(sandbox, spec.source, spec.ref);
+  try {
+    const available = await discoverSkills(sandbox, cloneDir, spec.source);
+    const selected = selectRepoSkills(available, spec);
+    for (const name of selected) {
+      const src = available.find((s) => s.name === name)!.dir;
+      const dest = posix.join(opts.dir, name);
+      const res = await sandbox.runShell(
+        `mkdir -p ${q(opts.dir)} && rm -rf ${q(dest)} && cp -R ${q(src)} ${q(dest)}`,
+      );
+      if (res.exitCode !== 0) {
+        throw new Error(t("skill.copyFailed", { name, dest, tail: tail(res.stdout + res.stderr) }));
+      }
+    }
+    return {
+      kind: "repo",
+      source: spec.source,
+      ...(spec.ref !== undefined ? { ref: spec.ref } : {}),
+      skills: selected,
+    };
+  } finally {
+    await sandbox.runShell(`rm -rf ${q(cloneDir)}`).catch(() => undefined);
+  }
+}
+
+/** repo 里可用的一个 Skill:名字 + 沙箱内 SKILL.md 所在目录。 */
+export interface DiscoveredSkill {
+  name: string;
+  dir: string;
+}
+
+/**
+ * 枚举 clone 里的 Skill:根 `SKILL.md` 存在 → 整个 repo 就是一个 Skill(名字取 repo 名);
+ * 否则每个含 `SKILL.md` 的目录是一个 Skill(名字取该目录名),与 `skills` CLI 的默认口径一致。
+ */
+async function discoverSkills(sandbox: Sandbox, cloneDir: string, source: string): Promise<DiscoveredSkill[]> {
+  const res = await sandbox.runShell(`find ${q(cloneDir)} -name SKILL.md -not -path '*/.git/*'`);
+  const paths = res.stdout.split("\n").map((l) => l.trim()).filter(Boolean).sort();
+  if (paths.length === 0) throw new Error(t("skill.repoNoSkills", { source }));
+
+  const rootFile = `${cloneDir}/SKILL.md`;
+  if (paths.includes(rootFile)) return [{ name: repoName(source), dir: cloneDir }];
+  return paths
+    .map((p) => {
+      const dir = posix.dirname(p);
+      return { name: posix.basename(dir), dir };
+    })
+    .sort((a, b) => a.name.localeCompare(b.name)); // 报错里的「可选集」按名字排,不按路径排
+}
+
+/**
+ * 选择规则(docs 的表):repo 只有一个 Skill 且省略 `skills` → 装唯一那个;多个且省略 →
+ * 失败并列出可选集;指定了不存在的 Skill → 失败并报 source / ref / 名字。
+ */
+export function selectRepoSkills(
+  available: readonly DiscoveredSkill[],
+  spec: Extract<SkillSpec, { kind: "repo" }>,
+): string[] {
+  const names = available.map((s) => s.name);
+  if (!spec.skills?.length) {
+    if (available.length === 1) return [names[0]!];
+    throw new Error(t("skill.repoAmbiguous", { source: spec.source, available: names.join(", ") }));
+  }
+  for (const want of spec.skills) {
+    if (!names.includes(want)) {
+      throw new Error(
+        t("skill.repoUnknownSkill", {
+          skill: want,
+          source: spec.source,
+          ref: spec.ref ?? "(default)",
+          available: names.join(", "),
+        }),
+      );
+    }
+  }
+  return [...spec.skills];
+}
+
+// ───────────────────────── git ─────────────────────────
+
+/**
+ * 把一个 repo clone 进沙箱临时目录,给了 ref 就钉到那个 tag/commit/branch,返回 clone 目录。
+ * ref 可能是任意 commit,所以钉 ref 时不能 `--depth 1`(浅克隆 checkout 不到历史 commit)。
+ * Skill 与 native plugin 的 marketplace(claude 侧 CLI 没有钉 ref 的入口)共用这一条。
+ */
+export async function cloneRepo(sandbox: Sandbox, source: string, ref?: string): Promise<string> {
+  const dir = `${CLONE_ROOT}/${slug(source)}-${Math.random().toString(36).slice(2, 8)}`;
+  const url = gitUrlOf(source);
+  const script =
+    `rm -rf ${q(dir)} && mkdir -p ${q(CLONE_ROOT)} && ` +
+    `git clone --quiet ${ref ? "" : "--depth 1 "}${q(url)} ${q(dir)}` +
+    (ref ? ` && git -C ${q(dir)} checkout --quiet ${q(ref)}` : "");
+  const res = await sandbox.runShell(script);
+  if (res.exitCode !== 0) {
+    throw new Error(
+      t("skill.repoCloneFailed", { source, ref: ref ?? "(default)", tail: tail(res.stdout + res.stderr) }),
+    );
+  }
+  return dir;
+}
+
+/** `owner/repo` → GitHub HTTPS URL;已经是 URL(含 `://` 或 `git@`)则原样用。 */
+export function gitUrlOf(source: string): string {
+  if (source.includes("://") || source.startsWith("git@")) return source;
+  return `https://github.com/${source}.git`;
+}
+
+function repoName(source: string): string {
+  const last = gitUrlOf(source).replace(/\/+$/, "").split("/").pop() ?? source;
+  return last.replace(/\.git$/, "");
+}
+
+function slug(source: string): string {
+  return source.replace(/[^\w.-]/g, "-");
+}
+
+function tail(output: string, n = 12): string {
+  return output.trim().split("\n").slice(-n).join("\n");
+}
+
+// ───────────────────────── 发现指引 ─────────────────────────
+
+/** manifest 里的 Skill 记录 → 沙箱里实际的目录名(发现指引要逐条点名)。 */
+export function installedSkillNames(skills: readonly AgentSetupSkill[]): string[] {
+  const names: string[] = [];
+  for (const skill of skills) {
+    if (skill.kind === "local") names.push(skill.name);
+    else names.push(...skill.skills);
+  }
+  return [...new Set(names)];
+}
+
+/**
+ * 给没有原生 Skill 加载机制的 agent(codex / bub)写的 project instruction 段落:
+ * 只把文件装到 skill 目录不足以让它们读到(见 memory/codex-no-native-skill-tool.md ——
+ * 不提示的话 codex 连一次 shell 读取都不会发生),必须在 AGENTS.md 里给出稳定的发现指引。
+ */
+export function skillDiscoveryInstruction(dir: string, skills: readonly string[]): string {
+  const list = skills.map((name) => `- ${name}: ${posix.join(dir, name)}/SKILL.md`).join("\n");
+  return [
+    "",
+    "## Skills",
+    "",
+    `Skill files are installed in \`${dir}/\`:`,
+    "",
+    list,
+    "",
+    "Before answering a task, check whether one of these skills covers it and read its `SKILL.md`",
+    "(e.g. with a shell command). Follow the skill's instructions when it applies.",
+    "",
+  ].join("\n");
+}
+
+/**
+ * 把发现指引追加进沙箱里的一个 instruction 文件(不存在则创建)。落在 workspace 里时,
+ * 新建的文件顺手排除出 diff —— setup 装的东西不是 agent 的产出(见 excludeFromDiff)。
+ * 文件本来就存在(starter 自带 AGENTS.md)时不排除:那是 agent 也可能改的文件,
+ * 排掉会把真实改动一起藏起来;此时追加的这一段会如实出现在 diff 里。
+ */
+export async function appendProjectInstruction(sandbox: Sandbox, text: string, file = "AGENTS.md"): Promise<void> {
+  const existed = await sandbox.fileExists(file).catch(() => false);
+  const delim = `NICEEVAL_EOF_${Math.random().toString(36).slice(2, 8)}`;
+  await sandbox.runShell(`cat >> ${q(file)} <<'${delim}'\n${text}\n${delim}\n`);
+  if (!existed) await excludeFromDiff(sandbox, [file]);
+}
+
+/**
+ * 把 setup 装进 workspace 的东西(skill 目录、adapter 新建的 instruction 文件)写进
+ * `.git/info/exclude`:git 基线是在 agent.setup **之前**打的,不排除的话这些文件会被
+ * `captureGeneratedFiles`(git add -A && git diff HEAD)当成「agent 生成的文件」记进
+ * diff.json —— 装了 skill 的实验,diff 里凭空多出几十个文件,基于 diff 的断言与展示全被污染。
+ * 排除只对未跟踪文件有效,这正是 adapter 自己创建的那一类。
+ */
+export async function excludeFromDiff(sandbox: Sandbox, paths: readonly string[]): Promise<void> {
+  if (!paths.length) return;
+  const lines = paths.map((p) => `printf '%s\\n' ${q(p)} >> .git/info/exclude`).join(" && ");
+  await sandbox.runShell(`test -d .git && mkdir -p .git/info && ${lines}`).catch(() => undefined);
+}

package/src/agents/streaming.ts

@@ -63,14 +63,14 @@ export async function driveFrameStream<Frame, RFrame = Frame>(
     const derived = reducer.add(frame as unknown as RFrame);
     events.push(...derived);
 
-    const outcome = onFrame?.(frame, derived, ctx);
-    if (outcome && "pause" in outcome) {
-      events.push({ type: "input.requested", request: outcome.pause });
+    const verdict = onFrame?.(frame, derived, ctx);
+    if (verdict && "pause" in verdict) {
+      events.push({ type: "input.requested", request: verdict.pause });
       return { status: "waiting", events, usage: reducer.usage };
     }
-    if (outcome && "fail" in outcome) {
+    if (verdict && "fail" in verdict) {
       transportFailed = true;
-      events.push({ type: "error", message: outcome.fail });
+      events.push({ type: "error", message: verdict.fail });
     }
   }
 

package/src/agents/types.ts

@@ -7,8 +7,9 @@ import type { StreamEvent, TraceSpan, Usage } from "../o11y/types.ts";
 import type { Sandbox } from "../sandbox/types.ts";
 
 /**
- * MCP server 描述符 —— Claude Code 与 Codex 共用的扩展插件单元。
- * 在 agent factory config 里声明,setup 阶段写进各自的配置文件。
+ * MCP server 描述符 —— 支持 MCP 的 adapter(Claude Code / Codex)共用的工具服务单元,
+ * 不是 native plugin 的一种。在 agent factory config 里声明,setup 阶段写进各自的配置文件。
+ * 见 docs/feature/adapters/architecture/coding-agent-extensions.md「类型边界」。
  */
 export interface McpServer {
   /** 服务器唯一名(config key)。 */
@@ -21,6 +22,57 @@ export interface McpServer {
   env?: Record<string, string>;
 }
 
+/**
+ * Skill 的来源描述 —— Claude Code / Codex / Bub 共用的**数据类型**:只统一「从哪里取得
+ * 哪份 Skill」,安装位置、发现机制、要不要额外写 project instruction 由各 Adapter 决定。
+ * 见 docs/feature/adapters/architecture/coding-agent-extensions.md「类型边界」。
+ */
+export type SkillSpec =
+  | {
+      kind: "local";
+      /** 相对项目根(跑 niceeval 的目录)的 Skill 文件或目录:`SKILL.md`、含 `SKILL.md` 的目录,或单个 `.md`。 */
+      path: string;
+      /** 展示名;省略时由文件或目录名推导(`<dir>/SKILL.md` → `<dir>`,`foo.md` → `foo`)。 */
+      name?: string;
+    }
+  | {
+      kind: "repo";
+      /** GitHub `owner/repo` 或 Git URL。 */
+      source: string;
+      /** 多 Skill Repo 中要启用的 Skill;repo 只有一个 Skill 时可省略,多个时省略即 setup 失败。 */
+      skills?: string[];
+      /** Tag、Commit 或 Branch;省略表示 repo 默认 ref。 */
+      ref?: string;
+    };
+
+/** Manifest 里的一条 Skill 安装记录:本地(带内容哈希)或 repo(带来源与 ref)。 */
+export type AgentSetupSkill =
+  | { kind: "local"; name: string; path: string; sha256: string }
+  | { kind: "repo"; source: string; ref?: string; skills: string[] };
+
+/**
+ * 一次 Agent setup 实际装了什么 —— 沙箱型 Coding Agent Adapter 在 setup 收尾写出的安装清单。
+ * 沙箱内落在 `__niceeval__/agent-setup.json`,运行器把它作为 attempt artifact 存成
+ * `agent-setup.json`(见 docs/feature/results/architecture.md)。不参与评分,只回答「这次实际
+ * 装了什么」;**环境变量值与 secret 不写进来**(所以 mcpServers 只记 name/command/args)。
+ */
+export interface AgentSetupManifest {
+  /** 装进去的 Skill(按配置顺序;同名来自多个来源时逐条保留,不静默合并)。 */
+  skills: AgentSetupSkill[];
+  /** Agent 原生 Plugin(Claude Code / Codex 各自的 Marketplace 协议)。 */
+  nativePlugins?: Array<{
+    agent: "claude-code" | "codex";
+    marketplace: { name: string; source: string; ref?: string };
+    name: string;
+    /** 安装后 CLI 报告的版本;取不到时省略。 */
+    resolvedVersion?: string;
+  }>;
+  /** 挂上的 MCP server(不含 env:secret 不进 manifest)。 */
+  mcpServers?: Array<{ name: string; command: string; args?: string[] }>;
+  /** Bub 的 Python Plugin(规范化后的 package 串)。 */
+  pythonPlugins?: Array<{ package: string }>;
+}
+
 /** 随一轮消息附带的文件(图片等多模态输入)。 */
 export interface InputFile {
   /** 文件名(可选,供 adapter / 模型参考)。 */
@@ -169,7 +221,11 @@ export interface AgentContext {
    * 具体取值)是两个维度——这里只是「跑的是哪个实验」的稳定标识,不携带条件内容。
    */
   readonly experimentId?: string;
-  /** 仅沙箱型 agent 有(运行器按 --sandbox 备好)。 */
+  /**
+   * 所有 agent 都有:沙箱型是运行器按项目/experiment 配置备好的真实沙箱句柄,remote 型是
+   * `createRemoteSandbox()` 产出的 stub(仅含 `workdir`/`sandboxId`/`otlpHost`/`stop` 等
+   * 元信息,其余方法调用即抛错)。
+   */
   readonly sandbox: Sandbox;
   readonly session: AgentSession;
   /**