create-windy 0.8.3 → 0.9.1

package/template/apps/server/src/agent-skills/routes.ts

@@ -0,0 +1,176 @@
+import type {
+  AgentSkillCommandRequest,
+  ImportAgentSkillRequest,
+} from "@southwind-ai/shared";
+import type { RequestGuardContext } from "../guards.js";
+import type { RouteApp } from "../system/route-types.js";
+import { AgentSkillError } from "./contracts.js";
+import type { AgentSkillService } from "./service.js";
+interface Context {
+  request: Request;
+  guardContext: RequestGuardContext;
+  params: Record<string, string | undefined>;
+}
+export function registerAgentSkillRoutes(
+  app: RouteApp,
+  service: AgentSkillService,
+) {
+  app.get("/agent/skills", (raw) =>
+    handle(raw, async (context) => {
+      const items = await service.list(context.guardContext);
+      await service.recordRead(context.guardContext, {
+        kind: "catalog",
+        itemCount: items.length,
+      });
+      return items;
+    }),
+  );
+  app.get("/agent/skills/:key", (raw) =>
+    handle(raw, async (context) => {
+      const item = await service.detail(key(context), context.guardContext);
+      await service.recordRead(context.guardContext, {
+        kind: "detail",
+        key: item.skill.key,
+        version: item.skill.version,
+      });
+      return item;
+    }),
+  );
+  app.get("/agent/skills/:key/versions", (raw) =>
+    handle(raw, async (context) => {
+      const items = await service.versions(key(context), context.guardContext);
+      await service.recordRead(context.guardContext, {
+        kind: "versions",
+        key: key(context),
+        itemCount: items.length,
+      });
+      return items;
+    }),
+  );
+  app.post(
+    "/agent/skills",
+    (raw) =>
+      handle(raw, async (context) => {
+        const body = await readBody(context.request);
+        fields(body, [
+          "format",
+          "content",
+          "scope",
+          "expectedVersion",
+          "requirements",
+          "safetyConstraints",
+        ]);
+        if (
+          typeof body.format !== "string" ||
+          typeof body.content !== "string" ||
+          typeof body.scope !== "string" ||
+          typeof body.expectedVersion !== "number"
+        )
+          throw invalid();
+        if (
+          body.requirements !== undefined &&
+          (!Array.isArray(body.requirements) ||
+            body.requirements.some(
+              (value) => !value || typeof value !== "object",
+            ))
+        )
+          throw invalid();
+        if (
+          body.safetyConstraints !== undefined &&
+          !Array.isArray(body.safetyConstraints)
+        )
+          throw invalid();
+        return service.publish(
+          body as unknown as ImportAgentSkillRequest,
+          idempotency(context),
+          context.guardContext,
+        );
+      }),
+    { parse: "none" },
+  );
+  for (const action of ["disable", "rollback"] as const)
+    app.post(
+      `/agent/skills/:key/${action}`,
+      (raw) =>
+        handle(raw, async (context) => {
+          const body = await readBody(context.request);
+          fields(body, ["expectedVersion", "version"]);
+          if (
+            typeof body.expectedVersion !== "number" ||
+            (body.version !== undefined && typeof body.version !== "number")
+          )
+            throw invalid();
+          return service.command(
+            key(context),
+            action,
+            body as unknown as AgentSkillCommandRequest,
+            idempotency(context),
+            context.guardContext,
+          );
+        }),
+      { parse: "none" },
+    );
+}
+async function readBody(request: Request): Promise<Record<string, unknown>> {
+  const reader = request.body?.getReader();
+  if (!reader) throw invalid();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  try {
+    while (true) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      total += value.length;
+      if (total > 6 * 1024 * 1024)
+        throw new AgentSkillError(
+          "SKILL_INPUT_TOO_LARGE",
+          "技能请求超过 6 MiB",
+          413,
+        );
+      chunks.push(value);
+    }
+  } finally {
+    await reader.cancel().catch(() => {});
+  }
+  let value: unknown;
+  try {
+    value = JSON.parse(Buffer.concat(chunks).toString("utf8")) as unknown;
+  } catch {
+    throw invalid();
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw invalid();
+  return value as Record<string, unknown>;
+}
+function fields(body: Record<string, unknown>, allowed: readonly string[]) {
+  if (Object.keys(body).some((name) => !allowed.includes(name)))
+    throw invalid();
+}
+function key(context: Context) {
+  return context.params.key ?? "";
+}
+function idempotency(context: Context) {
+  return context.request.headers.get("idempotency-key") ?? "";
+}
+function invalid() {
+  return new AgentSkillError("SKILL_INPUT_INVALID", "技能请求格式无效");
+}
+async function handle(
+  raw: unknown,
+  operation: (context: Context) => Promise<unknown>,
+) {
+  try {
+    return Response.json(await operation(raw as Context), {
+      headers: { "cache-control": "no-store" },
+    });
+  } catch (error) {
+    const safe =
+      error instanceof AgentSkillError
+        ? error
+        : new AgentSkillError("SKILL_UNAVAILABLE", "技能服务暂不可用", 503);
+    return Response.json(
+      { code: safe.code, message: safe.message, retryable: safe.status >= 500 },
+      { status: safe.status, headers: { "cache-control": "no-store" } },
+    );
+  }
+}

package/template/apps/server/src/agent-skills/service.test.ts

@@ -0,0 +1,295 @@
+import { describe, expect, test } from "bun:test";
+import type { AuditEvent, ImportAgentSkillRequest } from "@southwind-ai/shared";
+import { buildScopeContext } from "../data-access/context.js";
+import type { RequestGuardContext } from "../guards.js";
+import { InMemoryAgentSkillRepository } from "./repository.js";
+import { AgentSkillService } from "./service.js";
+import { platformBuiltinAgentSkills } from "./builtins.js";
+const markdown = (name = "test-query", body = "只使用当前授权的查询工具。") =>
+  `---\nname: ${name}\ndescription: 查询已授权资料\nmetadata:\n  displayName: 测试查询\n---\n${body}\n`;
+function context(
+  actorId = "actor-1",
+  departmentId = "department-1",
+  tenantWide = true,
+): RequestGuardContext {
+  return {
+    requestId: `request-${actorId}`,
+    startedAt: new Date().toISOString(),
+    actor: {
+      id: actorId,
+      type: "user",
+      name: actorId,
+      roleCodes: [],
+      permissionKeys: [],
+      credentialState: "active",
+      scopeContext: buildScopeContext(actorId, departmentId, [
+        {
+          id: "role-1",
+          code: "admin",
+          dataScope: tenantWide ? "tenant" : "self",
+          departmentIds: [],
+        },
+      ]),
+    },
+  };
+}
+function input(
+  name = "test-query",
+  expectedVersion = 0,
+): ImportAgentSkillRequest {
+  return {
+    format: "markdown",
+    content: markdown(name),
+    scope: "tenant",
+    expectedVersion,
+  };
+}
+function fixture() {
+  const repository = new InMemoryAgentSkillRepository(),
+    events: AuditEvent[] = [];
+  let allowed = true,
+    dependencyAllowed = true,
+    auditAvailable = true;
+  const service = new AgentSkillService(
+    repository,
+    {
+      async authorize() {
+        return allowed;
+      },
+      async requirement() {
+        return dependencyAllowed;
+      },
+    },
+    async (event) => {
+      if (!auditAvailable) throw new Error("audit unavailable");
+      if (!events.some((existing) => existing.id === event.id))
+        events.push(event);
+    },
+  );
+  return {
+    service,
+    repository,
+    events,
+    allow: (value: boolean) => {
+      allowed = value;
+    },
+    dependency: (value: boolean) => {
+      dependencyAllowed = value;
+    },
+    audit: (value: boolean) => {
+      auditAvailable = value;
+    },
+  };
+}
+describe("DSH shared skill governance", () => {
+  test("publishes actual SKILL.md, disables discovery and rolls back as a new immutable version", async () => {
+    const f = fixture(),
+      actor = context();
+    const first = await f.service.publish(input(), "publish-0001", actor);
+    expect(first.version).toBe(1);
+    const [published] = await f.service.publishedBundles(actor);
+    expect(published?.key).toBe("test-query");
+    expect(
+      Buffer.from(published!.files[0]!.contentBase64, "base64").toString(),
+    ).toBe(markdown());
+    const disabled = await f.service.command(
+      first.key,
+      "disable",
+      { expectedVersion: 1 },
+      "disable-0001",
+      actor,
+    );
+    expect(disabled.version).toBe(2);
+    expect(await f.service.publishedBundles(actor)).toEqual([]);
+    const restored = await f.service.command(
+      first.key,
+      "rollback",
+      { expectedVersion: 2, version: 1 },
+      "rollback-0001",
+      actor,
+    );
+    expect(restored.version).toBe(3);
+    expect(restored.restoredFromVersion).toBe(1);
+    expect(restored.digest).toBe(first.digest);
+    expect(
+      (await f.service.versions(first.key, actor)).map(
+        (record) => record.status,
+      ),
+    ).toEqual(["published", "disabled", "published"]);
+    expect(f.events.map((event) => event.action)).toEqual([
+      "agent.skill.publish",
+      "agent.skill.disable",
+      "agent.skill.rollback",
+    ]);
+    expect(JSON.stringify(f.events)).not.toContain("只使用当前授权");
+  });
+  test("enforces version CAS and idempotency across concurrent creates and replay", async () => {
+    const f = fixture(),
+      actor = context();
+    const attempts = await Promise.allSettled([
+      f.service.publish(input(), "publish-0001", actor),
+      f.service.publish(input(), "publish-0002", actor),
+    ]);
+    expect(
+      attempts.filter((result) => result.status === "fulfilled"),
+    ).toHaveLength(1);
+    expect(
+      attempts.filter((result) => result.status === "rejected"),
+    ).toHaveLength(1);
+    const replay = await f.service.publish(input(), "publish-0001", actor);
+    expect(replay.version).toBe(1);
+    expect(f.events).toHaveLength(1);
+    await expect(
+      f.service.publish(
+        { ...input(), content: markdown("other-query") },
+        "publish-0001",
+        actor,
+      ),
+    ).rejects.toMatchObject({ code: "SKILL_IDEMPOTENCY_CONFLICT" });
+    await expect(
+      f.service.command(
+        "test-query",
+        "disable",
+        { expectedVersion: 0 },
+        "disable-stale",
+        actor,
+      ),
+    ).rejects.toMatchObject({ code: "SKILL_VERSION_CONFLICT" });
+  });
+  test("reauthorizes every discovery and idempotent replay", async () => {
+    const f = fixture(),
+      actor = context();
+    await f.service.publish(input(), "publish-0001", actor);
+    f.allow(false);
+    await expect(f.service.publishedBundles(actor)).rejects.toMatchObject({
+      code: "SKILL_FORBIDDEN",
+    });
+    await expect(
+      f.service.publish(input(), "publish-0001", actor),
+    ).rejects.toMatchObject({ code: "SKILL_FORBIDDEN" });
+  });
+  test("honors personal and department ownership without accepting client scope claims", async () => {
+    const f = fixture(),
+      actor = context();
+    await f.service.publish(
+      { ...input("private-query"), scope: "personal" },
+      "personal-0001",
+      actor,
+    );
+    await f.service.publish(
+      { ...input("department-query"), scope: "department" },
+      "department-0001",
+      actor,
+    );
+    expect(
+      (await f.service.list(context("actor-2", "department-2"))).length,
+    ).toBe(0);
+    const colleague = await f.service.list(
+      context("actor-2", "department-1", false),
+    );
+    expect(colleague.map((item) => item.skill.key)).toEqual([
+      "department-query",
+    ]);
+    expect(colleague[0]?.governable).toBe(false);
+    await expect(
+      f.service.command(
+        "private-query",
+        "disable",
+        { expectedVersion: 1 },
+        "disable-private",
+        context("actor-2"),
+      ),
+    ).rejects.toMatchObject({ code: "SKILL_UNAVAILABLE" });
+    await expect(
+      f.service.publish(
+        input(),
+        "tenant-denied",
+        context("actor-2", "department-1", false),
+      ),
+    ).rejects.toMatchObject({ code: "SKILL_SCOPE_FORBIDDEN" });
+  });
+  test("does not expose an unaudited mutation and recovers durable receipts", async () => {
+    const f = fixture(),
+      actor = context();
+    f.audit(false);
+    await expect(
+      f.service.publish(input(), "publish-0001", actor),
+    ).rejects.toThrow("audit unavailable");
+    expect(await f.service.publishedBundles(actor)).toEqual([]);
+    expect(await f.repository.pendingAudits()).toHaveLength(1);
+    f.audit(true);
+    await f.service.recoverPendingAudits();
+    expect(await f.service.publishedBundles(actor)).toHaveLength(1);
+    await f.service.publish(input(), "publish-0001", actor);
+    expect(f.events).toHaveLength(1);
+  });
+  test("initialization retains an administrator disable across restarts", async () => {
+    const f = fixture();
+    await f.service.registerBuiltins(platformBuiltinAgentSkills, {
+      tenantId: "single-tenant",
+    });
+    await f.service.command(
+      "windy-tool-query",
+      "disable",
+      { expectedVersion: 1 },
+      "builtin-disable",
+      context(),
+    );
+    await f.service.registerBuiltins(platformBuiltinAgentSkills, {
+      tenantId: "single-tenant",
+    });
+    expect(await f.service.publishedBundles(context())).toEqual([]);
+    expect(
+      await f.service.versions("windy-tool-query", context()),
+    ).toHaveLength(2);
+  });
+  test("checks current manifest tool dependencies before publish, discovery and rollback", async () => {
+    const f = fixture(),
+      actor = context();
+    const required = {
+      ...input(),
+      requirements: [
+        {
+          toolKey: "system.query",
+          featureKey: "system.query",
+          permissionKey: "system.query.read",
+        },
+      ],
+    };
+    await f.service.publish(required, "publish-0001", actor);
+    f.dependency(false);
+    expect(await f.service.publishedBundles(actor)).toEqual([]);
+    expect((await f.service.list(actor))[0]?.available).toBe(false);
+    await f.service.command(
+      "test-query",
+      "disable",
+      { expectedVersion: 1 },
+      "disable-0001",
+      actor,
+    );
+    await expect(
+      f.service.command(
+        "test-query",
+        "rollback",
+        { expectedVersion: 2, version: 1 },
+        "rollback-0001",
+        actor,
+      ),
+    ).rejects.toMatchObject({ code: "SKILL_REQUIREMENT_UNAVAILABLE" });
+  });
+  test("a governor cannot privatize a different owner's shared skill", async () => {
+    const f = fixture();
+    await f.service.publish(input(), "publish-0001", context("owner"));
+    await expect(
+      f.service.publish(
+        { ...input(), expectedVersion: 1, scope: "personal" },
+        "private-rebind",
+        context("governor"),
+      ),
+    ).rejects.toMatchObject({ code: "SKILL_SCOPE_FORBIDDEN" });
+    expect(await f.repository.pendingAudits()).toEqual([]);
+    expect(
+      (await f.service.versions("test-query", context("owner"))).length,
+    ).toBe(1);
+  });
+});