create-windy 0.8.2 → 0.9.1

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

@@ -0,0 +1,108 @@
+import type {
+  AgentSkillGovernanceItem,
+  AgentSkillRuntimeBundle,
+} from "@southwind-ai/shared";
+import type { RequestGuardContext } from "../guards.js";
+import {
+  requireSkillAccess,
+  skillActor,
+  skillGovernable,
+  skillReadable,
+  skillRequirementsAvailable,
+  type AgentSkillAccess,
+} from "./access.js";
+import { skillKey } from "./bundle.js";
+import {
+  AgentSkillError,
+  type AgentSkillRepository,
+  type StoredAgentSkill,
+} from "./contracts.js";
+export class AgentSkillReader {
+  constructor(
+    protected readonly repository: AgentSkillRepository,
+    protected readonly access: AgentSkillAccess,
+  ) {}
+  async list(
+    context: RequestGuardContext,
+  ): Promise<readonly AgentSkillGovernanceItem[]> {
+    await requireSkillAccess(this.access, context, "read");
+    const records = await this.repository.versions(
+      skillActor(context).tenantId,
+    );
+    const current = new Map<string, StoredAgentSkill>();
+    for (const record of records)
+      if (record.auditCommitted) current.set(record.metadata.key, record);
+    return Promise.all(
+      [...current.values()]
+        .filter((record) => skillReadable(record.metadata, context))
+        .map(async (record) => ({
+          skill: record.metadata,
+          available:
+            record.metadata.status === "published" &&
+            (await skillRequirementsAvailable(
+              this.access,
+              record.metadata,
+              context,
+            )),
+          governable:
+            skillGovernable(record.metadata, context) &&
+            (await this.access.authorize(context, "manage")),
+        })),
+    );
+  }
+  async versions(key: string, context: RequestGuardContext) {
+    await requireSkillAccess(this.access, context, "read");
+    const records = await this.repository.versions(
+      skillActor(context).tenantId,
+      skillKey(key),
+    );
+    const current = records.filter((record) => record.auditCommitted).at(-1);
+    if (!current || !skillReadable(current.metadata, context))
+      throw unavailable();
+    return records
+      .filter(
+        (record) =>
+          record.auditCommitted && skillReadable(record.metadata, context),
+      )
+      .map(({ metadata }) => metadata);
+  }
+  async detail(key: string, context: RequestGuardContext) {
+    await requireSkillAccess(this.access, context, "read");
+    const records = await this.repository.versions(
+      skillActor(context).tenantId,
+      skillKey(key),
+    );
+    const record = records.filter((item) => item.auditCommitted).at(-1);
+    if (!record || !skillReadable(record.metadata, context))
+      throw unavailable();
+    return { skill: record.metadata, bundle: record.bundle };
+  }
+  async publishedBundles(
+    context: RequestGuardContext,
+  ): Promise<readonly AgentSkillRuntimeBundle[]> {
+    await requireSkillAccess(this.access, context, "execute");
+    const records = await this.repository.versions(
+      skillActor(context).tenantId,
+    );
+    const current = new Map<string, StoredAgentSkill>();
+    for (const record of records)
+      if (record.auditCommitted) current.set(record.metadata.key, record);
+    const results: AgentSkillRuntimeBundle[] = [];
+    for (const { metadata, bundle } of current.values())
+      if (
+        metadata.status === "published" &&
+        skillReadable(metadata, context) &&
+        (await skillRequirementsAvailable(this.access, metadata, context))
+      )
+        results.push({
+          key: metadata.key,
+          version: metadata.version,
+          digest: metadata.digest,
+          files: bundle.files,
+        });
+    return results;
+  }
+}
+function unavailable() {
+  return new AgentSkillError("SKILL_UNAVAILABLE", "技能或版本不可用", 404);
+}

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

@@ -0,0 +1,105 @@
+import type {
+  AgentSkillRepository,
+  SkillMutationIdentity,
+  SkillMutationReceipt,
+  StoredAgentSkill,
+} from "./contracts.js";
+import { AgentSkillError } from "./contracts.js";
+
+export function assertSkillMutation(
+  current: StoredAgentSkill | undefined,
+  expectedVersion: number,
+) {
+  if (
+    (current?.metadata.version ?? 0) !== expectedVersion ||
+    (current && !current.auditCommitted)
+  )
+    throw new AgentSkillError(
+      "SKILL_VERSION_CONFLICT",
+      "技能版本已变化或尚有审计未完成，请刷新后重试",
+      409,
+    );
+}
+export function assertSkillReplay(
+  receipt: SkillMutationReceipt,
+  identity: SkillMutationIdentity,
+) {
+  if (receipt.requestDigest !== identity.requestDigest)
+    throw new AgentSkillError(
+      "SKILL_IDEMPOTENCY_CONFLICT",
+      "幂等键已用于不同的技能操作",
+      409,
+    );
+}
+export class InMemoryAgentSkillRepository implements AgentSkillRepository {
+  private records: StoredAgentSkill[] = [];
+  private receipts = new Map<string, SkillMutationReceipt>();
+  private tail: Promise<void> = Promise.resolve();
+  async versions(tenantId: string, key?: string) {
+    return structuredClone(
+      this.records.filter(
+        (r) =>
+          r.metadata.tenantId === tenantId && (!key || r.metadata.key === key),
+      ),
+    );
+  }
+  async mutate(
+    input: Parameters<AgentSkillRepository["mutate"]>[0],
+    change: Parameters<AgentSkillRepository["mutate"]>[1],
+  ) {
+    const previous = this.tail;
+    let release!: () => void;
+    this.tail = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    await previous;
+    try {
+      const receiptKey = identityKey(input);
+      const replay = this.receipts.get(receiptKey);
+      if (replay) {
+        assertSkillReplay(replay, input);
+        return structuredClone(replay);
+      }
+      const versions = await this.versions(input.tenantId, input.key);
+      const current = versions.at(-1);
+      assertSkillMutation(current, input.expectedVersion);
+      const value = await change(current, versions);
+      const receipt = {
+        ...input,
+        result: value.record.metadata,
+        audit: value.audit,
+        auditCommitted: false,
+      };
+      this.records.push(structuredClone(value.record));
+      this.receipts.set(receiptKey, structuredClone(receipt));
+      return receipt;
+    } finally {
+      release();
+    }
+  }
+  async pendingAudits() {
+    return structuredClone(
+      [...this.receipts.values()].filter((receipt) => !receipt.auditCommitted),
+    );
+  }
+  async acknowledge(receipt: SkillMutationReceipt) {
+    const key = identityKey(receipt),
+      existing = this.receipts.get(key);
+    if (!existing) throw new Error("Skill mutation receipt missing");
+    this.receipts.set(key, { ...existing, auditCommitted: true });
+    this.records = this.records.map((record) =>
+      record.metadata.tenantId === receipt.tenantId &&
+      record.metadata.key === receipt.result.key &&
+      record.metadata.version === receipt.result.version
+        ? { ...record, auditCommitted: true }
+        : record,
+    );
+  }
+}
+function identityKey(identity: SkillMutationIdentity) {
+  return JSON.stringify([
+    identity.tenantId,
+    identity.actorId,
+    identity.idempotencyKey,
+  ]);
+}

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);
+  });
+});