create-windy 0.8.3 → 0.10.0

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

@@ -0,0 +1,19 @@
+import type { BuiltinAgentSkill } from "./service.js";
+export const platformBuiltinAgentSkills: readonly BuiltinAgentSkill[] = [
+  {
+    source: "windy-platform/builtin/windy-tool-query@1",
+    markdown: `---
+name: windy-tool-query
+description: 在当前身份授权范围内发现工具、只读查询并解释来源。
+metadata:
+  displayName: 平台工具查询
+---
+
+先读取当前会话实际可见的工具目录，使用与问题相关的简短关键词发现工具。
+仅调用当前身份已授权的只读查询工具，按真实参数 Schema 提交有界条件与分页。
+不得猜测工具名、身份、权限或内部地址；没有工具或权限时明确说明缺口。
+结果区分原始来源、计算结果与待核实推断，不将总结自动当作正式业务事实。
+用户要求修改时，解释需要的正式业务入口和审批；本技能不授予写入权限。
+`,
+  },
+];

package/template/apps/server/src/agent-skills/bundle-zip.ts

@@ -0,0 +1,163 @@
+import { Unzip, UnzipInflate } from "fflate";
+import { AgentSkillError } from "./contracts.js";
+export const SKILL_LIMITS = {
+  archive: 4 * 1024 * 1024,
+  total: 16 * 1024 * 1024,
+  file: 4 * 1024 * 1024,
+  markdown: 128 * 1024,
+  entries: 128,
+};
+function invalid(message: string, status = 400): never {
+  throw new AgentSkillError("SKILL_PACKAGE_INVALID", message, status);
+}
+export function skillPath(value: string): string {
+  if (
+    !value ||
+    value.length > 240 ||
+    value.includes("\\") ||
+    value.startsWith("/") ||
+    [...value].some(
+      (char) =>
+        char === ":" || char.charCodeAt(0) < 32 || char.charCodeAt(0) === 127,
+    )
+  )
+    invalid("技能包包含非法路径");
+  const parts = value.replace(/\/$/, "").split("/");
+  if (parts.some((part) => !part || part.startsWith(".") || part.length > 100))
+    invalid("技能包不能包含隐藏路径、父目录或空路径");
+  return value;
+}
+function inspectZip(bytes: Uint8Array) {
+  if (bytes.length > SKILL_LIMITS.archive || bytes.length < 22)
+    invalid("ZIP 超过 4 MiB 或格式无效", 413);
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  let end = bytes.length - 22;
+  while (
+    end >= Math.max(0, bytes.length - 65557) &&
+    view.getUint32(end, true) !== 0x06054b50
+  )
+    end--;
+  if (end < 0 || end < bytes.length - 65557) invalid("ZIP 目录无效");
+  const count = view.getUint16(end + 10, true),
+    start = view.getUint32(end + 16, true);
+  if (
+    view.getUint16(end + 4, true) ||
+    view.getUint16(end + 6, true) ||
+    count !== view.getUint16(end + 8, true) ||
+    !count ||
+    count > SKILL_LIMITS.entries ||
+    start + view.getUint32(end + 12, true) !== end ||
+    end + 22 + view.getUint16(end + 20, true) !== bytes.length
+  )
+    invalid("ZIP 文件数量或分卷格式不支持");
+  let cursor = start,
+    total = 0;
+  const names = new Map<string, { name: string; size: number }>();
+  for (let i = 0; i < count; i++) {
+    if (cursor + 46 > end || view.getUint32(cursor, true) !== 0x02014b50)
+      invalid("ZIP 目录损坏");
+    const size = view.getUint32(cursor + 24, true),
+      length = view.getUint16(cursor + 28, true),
+      extra = view.getUint16(cursor + 30, true),
+      comment = view.getUint16(cursor + 32, true);
+    const mode = (view.getUint32(cursor + 38, true) >>> 16) & 0xf000;
+    if (
+      cursor + 46 + length + extra + comment > end ||
+      view.getUint16(cursor + 8, true) & 1 ||
+      ![0, 8].includes(view.getUint16(cursor + 10, true)) ||
+      ![0, 0x8000, 0x4000].includes(mode)
+    )
+      invalid("ZIP 包含加密、特殊文件或不支持的压缩方式");
+    const name = skillPath(
+      new TextDecoder("utf-8", { fatal: true }).decode(
+        bytes.subarray(cursor + 46, cursor + 46 + length),
+      ),
+    );
+    const key = name.replace(/\/$/, "").toLowerCase();
+    if (
+      names.has(key) ||
+      size > SKILL_LIMITS.file ||
+      (total += size) > SKILL_LIMITS.total
+    )
+      invalid("ZIP 路径重复或展开体积过大", 413);
+    names.set(key, { name, size });
+    cursor += 46 + length + extra + comment;
+  }
+  if (cursor !== end) invalid("ZIP 目录不完整");
+  return names;
+}
+export function decodeSkillZip(bytes: Uint8Array): Record<string, Uint8Array> {
+  const advertised = inspectZip(bytes),
+    files: Record<string, Uint8Array> = Object.create(null),
+    seen = new Set<string>();
+  let expanded = 0,
+    failure: Error | undefined;
+  const archive = new Unzip((entry) => {
+    const name = skillPath(entry.name),
+      known = advertised.get(name.replace(/\/$/, "").toLowerCase());
+    if (!known || known.name !== name || seen.has(name))
+      invalid("ZIP 本地目录与中央目录不一致");
+    seen.add(name);
+    const chunks: Uint8Array[] = [];
+    let size = 0;
+    entry.ondata = (error, chunk, final) => {
+      if (error) {
+        failure = error;
+        entry.terminate();
+        return;
+      }
+      size += chunk.length;
+      expanded += chunk.length;
+      if (
+        size > known.size ||
+        size > SKILL_LIMITS.file ||
+        expanded > SKILL_LIMITS.total
+      ) {
+        failure = new AgentSkillError(
+          "SKILL_PACKAGE_INVALID",
+          "ZIP 展开体积超限",
+          413,
+        );
+        entry.terminate();
+        return;
+      }
+      chunks.push(chunk);
+      if (final && !name.endsWith("/")) {
+        if (size !== known.size) {
+          failure = new Error("ZIP 文件长度不一致");
+          return;
+        }
+        const output = new Uint8Array(size);
+        let offset = 0;
+        for (const part of chunks) {
+          output.set(part, offset);
+          offset += part.length;
+        }
+        files[name] = output;
+      }
+    };
+    entry.start();
+  });
+  archive.register(UnzipInflate);
+  for (let offset = 0; offset < bytes.length; offset += 1024) {
+    archive.push(
+      bytes.subarray(offset, offset + 1024),
+      offset + 1024 >= bytes.length,
+    );
+    if (failure) throw failure;
+  }
+  if (seen.size !== advertised.size) invalid("ZIP 文件目录不完整");
+  const keys = Object.keys(files),
+    markdown = keys.filter(
+      (name) => name === "SKILL.md" || /^[^/]+\/SKILL\.md$/.test(name),
+    );
+  if (markdown.length !== 1) invalid("ZIP 必须只包含一个技能目录及其 SKILL.md");
+  const prefix = markdown[0]!.slice(0, -8),
+    result: Record<string, Uint8Array> = Object.create(null);
+  for (const key of keys) {
+    if (!key.startsWith(prefix) || key === prefix)
+      invalid("ZIP 含技能目录之外的文件");
+    result[skillPath(key.slice(prefix.length))] = files[key]!;
+  }
+  return result;
+}

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

@@ -0,0 +1,79 @@
+import { describe, expect, test } from "bun:test";
+import { zipSync, strToU8 } from "fflate";
+import { parseSkillBundle } from "./bundle.js";
+const markdown =
+  "---\nname: safe-query\ndescription: 安全查询\n---\n仅使用已授权工具。\n";
+function archive(files: Record<string, Uint8Array>) {
+  return {
+    format: "zip" as const,
+    content: Buffer.from(zipSync(files)).toString("base64"),
+  };
+}
+describe("shared DSH skill import", () => {
+  test("imports one directory with binary attachments and a stable digest", () => {
+    const imported = parseSkillBundle(
+      archive({
+        "safe-query/SKILL.md": strToU8(markdown),
+        "safe-query/assets/sample.bin": Uint8Array.from([0, 1, 255]),
+      }),
+    );
+    expect(imported.name).toBe("safe-query");
+    expect(imported.files).toHaveLength(2);
+    expect(
+      imported.files.find((file) => file.path === "assets/sample.bin")
+        ?.contentBase64,
+    ).toBe("AAH/");
+    expect(
+      parseSkillBundle(
+        archive({
+          "safe-query/assets/sample.bin": Uint8Array.from([0, 1, 255]),
+          "safe-query/SKILL.md": strToU8(markdown),
+        }),
+      ).digest,
+    ).toBe(imported.digest);
+  });
+  test("rejects traversal, multiple skills and unrelated root files", () => {
+    const invalidBundles: Record<string, Uint8Array>[] = [
+      { "../SKILL.md": strToU8(markdown) },
+      { "a/SKILL.md": strToU8(markdown), "b/SKILL.md": strToU8(markdown) },
+      {
+        "safe-query/SKILL.md": strToU8(markdown),
+        "unrelated.txt": strToU8("x"),
+      },
+    ];
+    for (const files of invalidBundles)
+      expect(() => parseSkillBundle(archive(files))).toThrow();
+  });
+  test("rejects duplicate YAML, malformed flags, invalid UTF-8 and oversized markdown", () => {
+    for (const content of [
+      markdown.replace("description:", "name: duplicate\ndescription:"),
+      markdown.replace("---\n仅", "user-invocable: yes\n---\n仅"),
+      `---\nname: safe-query\ndescription: 安全\n---\n${"x".repeat(128 * 1024)}`,
+    ])
+      expect(() => parseSkillBundle({ format: "markdown", content })).toThrow();
+    expect(() =>
+      parseSkillBundle(archive({ "SKILL.md": Uint8Array.from([255, 255]) })),
+    ).toThrow();
+  });
+  test("rejects Unix symlinks and advertised expanded-size bombs before decompression", () => {
+    const bytes = zipSync({ "SKILL.md": strToU8(markdown) });
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    let cursor = 0;
+    while (view.getUint32(cursor, true) !== 0x02014b50) cursor++;
+    view.setUint32(cursor + 38, 0xa1ff << 16, true);
+    expect(() =>
+      parseSkillBundle({
+        format: "zip",
+        content: Buffer.from(bytes).toString("base64"),
+      }),
+    ).toThrow();
+    view.setUint32(cursor + 38, 0x81a4 << 16, true);
+    view.setUint32(cursor + 24, 0x7fffffff, true);
+    expect(() =>
+      parseSkillBundle({
+        format: "zip",
+        content: Buffer.from(bytes).toString("base64"),
+      }),
+    ).toThrow();
+  });
+});

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

@@ -0,0 +1,133 @@
+import { createHash } from "node:crypto";
+import { parseDocument } from "yaml";
+import type {
+  AgentSkillBundle,
+  ImportAgentSkillRequest,
+} from "@southwind-ai/shared";
+import { AgentSkillError } from "./contracts.js";
+import { decodeSkillZip, SKILL_LIMITS } from "./bundle-zip.js";
+export function skillKey(value: unknown): string {
+  if (
+    typeof value !== "string" ||
+    value.length > 64 ||
+    !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value)
+  )
+    throw new AgentSkillError(
+      "SKILL_PACKAGE_INVALID",
+      "技能标识须为小写英文、数字和连字符，最长 64 字符",
+    );
+  return value;
+}
+export function parseSkillBundle(
+  input: Pick<ImportAgentSkillRequest, "format" | "content">,
+): AgentSkillBundle {
+  if (typeof input.content !== "string")
+    throw new AgentSkillError(
+      "SKILL_PACKAGE_INVALID",
+      "请选择 SKILL.md 或 ZIP 文件",
+    );
+  let files: Record<string, Uint8Array>;
+  if (input.format === "markdown")
+    files = { "SKILL.md": new TextEncoder().encode(input.content) };
+  else if (input.format === "zip") {
+    if (
+      input.content.length > Math.ceil(SKILL_LIMITS.archive / 3) * 4 ||
+      !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(
+        input.content,
+      )
+    )
+      throw new AgentSkillError(
+        "SKILL_PACKAGE_INVALID",
+        "ZIP 编码或体积无效",
+        413,
+      );
+    files = decodeSkillZip(Buffer.from(input.content, "base64"));
+  } else
+    throw new AgentSkillError(
+      "SKILL_PACKAGE_INVALID",
+      "仅支持 SKILL.md 或 ZIP",
+    );
+  const markdown = files["SKILL.md"];
+  if (!markdown || markdown.length > SKILL_LIMITS.markdown)
+    throw new AgentSkillError(
+      "SKILL_PACKAGE_INVALID",
+      "SKILL.md 超过 128 KiB",
+      413,
+    );
+  let raw: string;
+  try {
+    raw = new TextDecoder("utf-8", { fatal: true }).decode(markdown);
+  } catch {
+    throw new AgentSkillError("SKILL_PACKAGE_INVALID", "SKILL.md 必须为 UTF-8");
+  }
+  const metadata = skillDocument(raw);
+  const encoded = Object.keys(files)
+    .sort()
+    .map((path) => ({
+      path,
+      contentBase64: Buffer.from(files[path]!).toString("base64"),
+    }));
+  return { ...metadata, digest: hashSkillValue(encoded), files: encoded };
+}
+export function hashSkillValue(value: unknown): string {
+  return `sha256:${createHash("sha256").update(JSON.stringify(value)).digest("hex")}`;
+}
+function skillDocument(raw: string) {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)([\s\S]*)$/.exec(raw);
+  if (!match || !match[2]!.trim() || raw.includes("\0"))
+    throw new AgentSkillError(
+      "SKILL_PACKAGE_INVALID",
+      "SKILL.md 需要 YAML 头部（name、description）及正文",
+    );
+  const doc = parseDocument(match[1]!, { uniqueKeys: true });
+  if (doc.errors.length)
+    throw new AgentSkillError("SKILL_PACKAGE_INVALID", "技能 YAML 格式无效");
+  let value: unknown;
+  try {
+    value = doc.toJS({ maxAliasCount: 20 }) as unknown;
+  } catch {
+    throw new AgentSkillError("SKILL_PACKAGE_INVALID", "技能 YAML 引用过多");
+  }
+  const meta = record(value),
+    name = skillKey(meta.name),
+    description = meta.description;
+  if (
+    typeof description !== "string" ||
+    !description.trim() ||
+    description.length > 2048
+  )
+    throw new AgentSkillError(
+      "SKILL_PACKAGE_INVALID",
+      "请填写不超过 2048 字符的技能说明",
+    );
+  for (const field of ["user-invocable", "disable-model-invocation"])
+    if (meta[field] !== undefined && typeof meta[field] !== "boolean")
+      throw new AgentSkillError(
+        "SKILL_PACKAGE_INVALID",
+        `${field} 必须为布尔值`,
+      );
+  const displayName = record(meta.metadata).displayName;
+  if (
+    displayName !== undefined &&
+    (typeof displayName !== "string" ||
+      !displayName.trim() ||
+      displayName.length > 60 ||
+      [...displayName].some(
+        (char) => char.charCodeAt(0) < 32 || char.charCodeAt(0) === 127,
+      ))
+  )
+    throw new AgentSkillError(
+      "SKILL_PACKAGE_INVALID",
+      "技能中文名称须为 1–60 字符的单行文字",
+    );
+  return {
+    name,
+    displayName: typeof displayName === "string" ? displayName.trim() : name,
+    description: description.trim(),
+  };
+}
+function record(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}

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

@@ -0,0 +1,46 @@
+import type {
+  AgentSkillBundle,
+  AgentSkillVersion,
+  AuditEvent,
+} from "@southwind-ai/shared";
+
+export class AgentSkillError extends Error {
+  constructor(
+    readonly code: string,
+    message: string,
+    readonly status = 400,
+  ) {
+    super(message);
+  }
+}
+export interface StoredAgentSkill {
+  readonly metadata: AgentSkillVersion;
+  readonly bundle: AgentSkillBundle;
+  readonly auditCommitted: boolean;
+}
+export interface SkillMutationIdentity {
+  readonly tenantId: string;
+  readonly actorId: string;
+  readonly idempotencyKey: string;
+  readonly requestDigest: string;
+}
+export interface SkillMutationReceipt extends SkillMutationIdentity {
+  readonly result: AgentSkillVersion;
+  readonly audit: AuditEvent;
+  readonly auditCommitted: boolean;
+}
+export interface AgentSkillRepository {
+  versions(
+    tenantId: string,
+    key?: string,
+  ): Promise<readonly StoredAgentSkill[]>;
+  mutate(
+    input: SkillMutationIdentity & { key: string; expectedVersion: number },
+    change: (
+      current: StoredAgentSkill | undefined,
+      versions: readonly StoredAgentSkill[],
+    ) => Promise<{ record: StoredAgentSkill; audit: AuditEvent }>,
+  ): Promise<SkillMutationReceipt>;
+  pendingAudits(): Promise<readonly SkillMutationReceipt[]>;
+  acknowledge(receipt: SkillMutationReceipt): Promise<void>;
+}

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

@@ -0,0 +1,125 @@
+import { and, asc, eq, sql } from "drizzle-orm";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import {
+  agentSkillMutations,
+  agentSkillVersions,
+} from "@southwind-ai/database";
+import type {
+  AgentSkillRepository,
+  SkillMutationReceipt,
+} from "./contracts.js";
+import { assertSkillMutation, assertSkillReplay } from "./repository.js";
+
+export class DrizzleAgentSkillRepository implements AgentSkillRepository {
+  constructor(private readonly db: NodePgDatabase) {}
+  async versions(tenantId: string, key?: string) {
+    return this.db
+      .select({
+        metadata: agentSkillVersions.metadata,
+        bundle: agentSkillVersions.bundle,
+        auditCommitted: agentSkillVersions.auditCommitted,
+      })
+      .from(agentSkillVersions)
+      .where(
+        and(
+          eq(agentSkillVersions.tenantId, tenantId),
+          key ? eq(agentSkillVersions.skillKey, key) : undefined,
+        ),
+      )
+      .orderBy(asc(agentSkillVersions.version));
+  }
+  async mutate(
+    input: Parameters<AgentSkillRepository["mutate"]>[0],
+    change: Parameters<AgentSkillRepository["mutate"]>[1],
+  ) {
+    return this.db.transaction(async (tx) => {
+      // Serialize both the new-key case and actor-wide mutation receipts before CAS.
+      await tx.execute(
+        sql`select pg_advisory_xact_lock(hashtextextended(${`agent-skill:${input.tenantId}`}, 0))`,
+      );
+      const [replay] = await tx
+        .select()
+        .from(agentSkillMutations)
+        .where(
+          and(
+            eq(agentSkillMutations.tenantId, input.tenantId),
+            eq(agentSkillMutations.actorId, input.actorId),
+            eq(agentSkillMutations.idempotencyKey, input.idempotencyKey),
+          ),
+        )
+        .limit(1);
+      if (replay) {
+        assertSkillReplay(replay, input);
+        return replay;
+      }
+      const versions = await tx
+        .select({
+          metadata: agentSkillVersions.metadata,
+          bundle: agentSkillVersions.bundle,
+          auditCommitted: agentSkillVersions.auditCommitted,
+        })
+        .from(agentSkillVersions)
+        .where(
+          and(
+            eq(agentSkillVersions.tenantId, input.tenantId),
+            eq(agentSkillVersions.skillKey, input.key),
+          ),
+        )
+        .orderBy(asc(agentSkillVersions.version));
+      assertSkillMutation(versions.at(-1), input.expectedVersion);
+      const { record, audit } = await change(versions.at(-1), versions);
+      const receipt = {
+        ...input,
+        result: record.metadata,
+        audit,
+        auditCommitted: false,
+      };
+      await tx.insert(agentSkillVersions).values({
+        tenantId: input.tenantId,
+        skillKey: input.key,
+        version: record.metadata.version,
+        metadata: record.metadata,
+        bundle: record.bundle,
+        auditCommitted: false,
+      });
+      await tx.insert(agentSkillMutations).values({
+        ...receipt,
+        skillKey: input.key,
+        version: record.metadata.version,
+      });
+      return receipt;
+    });
+  }
+  async pendingAudits() {
+    return this.db
+      .select()
+      .from(agentSkillMutations)
+      .where(eq(agentSkillMutations.auditCommitted, false))
+      .limit(500);
+  }
+  async acknowledge(receipt: SkillMutationReceipt) {
+    await this.db.transaction(async (tx) => {
+      await tx
+        .update(agentSkillVersions)
+        .set({ auditCommitted: true })
+        .where(
+          and(
+            eq(agentSkillVersions.tenantId, receipt.tenantId),
+            eq(agentSkillVersions.skillKey, receipt.result.key),
+            eq(agentSkillVersions.version, receipt.result.version),
+          ),
+        );
+      await tx
+        .update(agentSkillMutations)
+        .set({ auditCommitted: true })
+        .where(
+          and(
+            eq(agentSkillMutations.tenantId, receipt.tenantId),
+            eq(agentSkillMutations.actorId, receipt.actorId),
+            eq(agentSkillMutations.idempotencyKey, receipt.idempotencyKey),
+            eq(agentSkillMutations.requestDigest, receipt.requestDigest),
+          ),
+        );
+    });
+  }
+}

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

@@ -0,0 +1,29 @@
+import type { ImportAgentSkillRequest } from "@southwind-ai/shared";
+import { AgentSkillError } from "./contracts.js";
+export function version(value: number) {
+  if (!Number.isSafeInteger(value) || value < 0)
+    throw new AgentSkillError(
+      "SKILL_INPUT_INVALID",
+      "expectedVersion 必须为非负整数",
+    );
+}
+export function validateImport(input: ImportAgentSkillRequest) {
+  version(input.expectedVersion);
+  if (!["personal", "department", "tenant"].includes(input.scope))
+    throw new AgentSkillError("SKILL_INPUT_INVALID", "技能共享范围无效");
+  if (
+    (input.requirements?.length ?? 0) > 64 ||
+    (input.safetyConstraints?.length ?? 0) > 32
+  )
+    throw new AgentSkillError("SKILL_INPUT_INVALID", "技能依赖或约束数量过多");
+  for (const item of input.requirements ?? [])
+    if (
+      ![item.toolKey, item.permissionKey, item.featureKey].every(
+        (key) => typeof key === "string" && key.length > 0 && key.length <= 160,
+      )
+    )
+      throw new AgentSkillError("SKILL_INPUT_INVALID", "技能依赖无效");
+  for (const item of input.safetyConstraints ?? [])
+    if (typeof item !== "string" || !item.trim() || item.length > 1000)
+      throw new AgentSkillError("SKILL_INPUT_INVALID", "技能安全约束无效");
+}