create-windy 0.8.3 → 0.9.1

package/template/apps/agent-server/plugins/tool-catalog/README.md

@@ -0,0 +1,79 @@
+# Windy业务工具目录与按需加载
+
+工具事实来源是官方 MCP bridge 通过现有身份获得并注册的 `mcp__windy__*` 工具。
+不另建业务工具 allowlist，不复制输入输出 Schema，也不扩大业务 MCP 暴露面。
+
+alpha.3 的 MCP bridge 默认注册全部完整 Schema。当前 `openai-completions` 适配器
+没有可直接使用的通用延迟搜索协议；单独添加 `deferLoading` 会让工具被过滤且无法发现。
+本插件采用公开 `system-prompt/assemble` 裁剪本轮模型工具声明，配合 `tools.guard`
+拒绝未加载的调用；仅发现入口注册到同 Agent 的 `createScope`，原 MCP 定义保持不变。
+每个 Agent 初始业务工具仅看到
+`discover_business_tools`，其目录预览最多 12 项、1600 字符。模型先搜索/翻页查询每页
+20 项的简洁目录，再从实际工具名称选择最多 8 项，在该 Agent 后续模型请求中声明所选工具的原始完整 Schema。
+选择会替换该 Agent 已加载的业务工具，父子 Agent 分别选择，不向其它会话注册。
+原生文件、脚本、子 Agent 等非业务工具保持原有装配。
+
+目录刷新、MCP 重连和工具注册变化会重新校验各 Agent 的选择；被移除或被既有
+Agent 限制排除的工具立即撤销。插件不复制业务定义、不覆盖 scoped restriction，
+业务调用始终通过原 ToolRuntime 与官方 MCP 定义执行，服务端逐次校验 Feature、License、RBAC、Scope 和输入输出契约。发现工具
+不接受 Actor、权限、范围或任意工具名。
+
+设置「工具」使用认证本机 `/windy/tool-catalog` 接口读取实时 registry，支持搜索、
+分页及刷新，合并实时业务目录与活跃 Agent 的工作区工具，显示中文名称、简短说明及
+使用方式。页面不暴露参数 Schema、业务结果、
+连接凭据或其它用户目录。当前连接发现目录不代表权限永久有效，实际执行继续重授权。
+
+工具发现与目录浏览本身不计作业务处理成功，不补写系统效能贡献；底层业务调用仍使用
+原有 Tool 审计和版本化计量规则。
+
+## 中文展示契约
+
+设置目录保留内部 `name` 供模型选择与 keyed dispatch，另外返回 `displayName`、`summary`、
+`sourceLabel`、`strategyLabel`。界面主标题与描述只消费中文展示字段，不展示执行 ID、
+原始 description 或底座名称。业务中文名读取同一 Actor 边界的标准 MCP `tools/list`
+中由 Manifest 提供的 `title`（兼容 `annotations.title`），不从内部工具名猜业务类型。
+映射适配覆盖官方 server-qualified 命名的普通、含点号和超长哈希编码，并有真实官方
+MCP bridge 测试。标题缺失或元数据暂不可用时显示中文通用标题。
+
+元数据读取在后台进行，不阻塞 Agent 插件启动；请求使用当前 Worker Token，经已有
+MCP 边界重授权，单次最长 5 秒，同一时刻合并请求。成功缓存 15 秒，失败不缓存，设置
+刷新可重试。只保存中文标题与说明，不保存业务内容、Schema 或连接凭据。
+
+本机工具使用受限中文映射，包括文件、脚本、协作、后台任务、目标、会话、定时任务及
+终端；未识别扩展显示「工作区工具」。摘要优先现有中文首句，最多 44 字，含底座或契约
+实现称谓时使用中文通用说明，不调用模型翻译。
+
+## 业务分类与计数
+
+MCP `tools/list` 的 `_meta["windy/moduleKey"]`、`_meta["windy/moduleLabel"]` 直接来自工具
+注册源所属 Manifest 的 `name` 和 `label`，只携带展示归属。元数据适配仅保存这两个字段与
+现有中文标题/说明，不透传其它 `_meta`、权限凭据、Schema 或业务结果。
+业务分类使用真实所属模块，例如 `system.identity/身份管理`；
+不根据执行名、哈希、中文标题或用户材料推测归属。当前属于情报档案模块的人员工具仍归该模块，
+未来拆分真实模块后分类会随 Manifest 自动变化。元数据缺失时使用 `business/业务工具`。
+原生工具使用明确静态映射：`workspace.files/文件`、`workspace.commands/命令`、
+`workspace.collaboration/协作`、`workspace.tasks/任务`、`workspace.sessions/会话`、
+`workspace.discovery/工具与技能`；未知扩展归 `workspace.other/其他工作区工具`。
+
+目录项目新增 `categoryKey`、`categoryLabel`；响应增加 `category`、`matchedTotal` 和
+`groups: [{ categoryKey, categoryLabel, count }]`。`groups.count` 与 `matchedTotal` 基于当前
+实际工具 registry 和本次 `query` 的整个命中集合，位于分类筛选和分页之前；`total` 为再按
+`category` 筛选后的总数，`items` 是这个结果集的当前页。分组计数不受当前页大小影响。
+搜索同时匹配分类中文名，因此模块中文名称能找到该模块的工具。
+
+`GET /windy/tool-catalog` 与 `discover_business_tools` 均接受可选 `category`；空值代表全部，
+非空值必须逐字来自当前真实可见目录的分类 Key，不能凭名称猜分类。未知或已移除的分类由
+HTTP 返回 400、发现工具返回明确错误；分类筛选不能增加工具权限、改变已加载 Schema，
+也不能绕过原 MCP 的 Feature、License、RBAC、Scope 和逐次执行校验。
+
+设置布局与插件页对齐为紧凑网格：页面标题 20px/500/28px，卡片标题 14px/500/20px，
+简介和说明 13px/400/20px；展示中文名称、简短说明和使用方式，来源与执行 ID 不占据
+主内容。对话展示由 `../tool-presentation/` 复用官方公开插槽，详情见该插件说明。
+
+## 从目录使用工具
+
+卡片是可由键盘激活的完整点击区域。点击后通过官方 Session 公开引用和输入事件把中文工具意图带入当前对话，保留已有文字、附件和引用，不自动发送、不直接运行工具。输入处于提交/命令状态、对话切换或草稿版本变化时拒绝写入，错误显示在该卡片附近。没有当前会话时，复用官方工作区新会话入口准备草稿，不伪造业务范围。相同意图已在草稿尾部时不会重复追加。
+
+分类导航使用服务端返回的正式业务模块及明确的工作区工具分类，不解析哈希执行名。搜索时重置到全部，分类变更重置页码；已撤销分类返回 400 时回到全部。分组计数覆盖搜索命中的全量可见目录，列表分页只影响当前卡片集合。
+
+设置面板在当前组件实例内按搜索词、分类和页码缓存最近 24 组成功结果；切回已读取的分类或页码直接显示缓存，超出上限淘汰最久未使用项。点击「刷新」会清空整个面板缓存并重新查询当前筛选。失败与已取消请求不缓存，旧请求不会覆盖新选择；关闭面板后缓存随组件释放，不写入浏览器存储，也不在插件实例或用户之间共享。缓存仅减少目录查询，实际工具执行仍逐次重授权。

package/template/apps/agent-server/plugins/tool-catalog/categories.mjs

@@ -0,0 +1,111 @@
+const nativeGroups = [
+  [
+    "files",
+    "文件",
+    [
+      "delete",
+      "read",
+      "write",
+      "edit",
+      "glob",
+      "grep",
+      "read_image",
+      "present",
+      "working_directory",
+      "load_workspace_dependencies",
+    ],
+  ],
+  [
+    "commands",
+    "命令",
+    [
+      "exec",
+      "exec_command",
+      "write_stdin",
+      "bash",
+      "run_code",
+      "terminal_open",
+      "terminal_send",
+      "terminal_read",
+      "terminal_signal",
+      "terminal_close",
+      "terminal_list",
+    ],
+  ],
+  [
+    "collaboration",
+    "协作",
+    [
+      "list_agents",
+      "spawn_teammate",
+      "interrupt_agent",
+      "wait_subagents",
+      "list_subagent_models",
+      "subagent",
+      "send_message",
+      "wait",
+      "wait_agent",
+      "ask_user_question",
+    ],
+  ],
+  [
+    "tasks",
+    "任务",
+    [
+      "job_output",
+      "job_list",
+      "job_kill",
+      "get_goal",
+      "create_goal",
+      "update_goal",
+      "todo_write",
+      "schedule_create",
+      "schedule_list",
+      "schedule_update",
+      "schedule_delete",
+    ],
+  ],
+  [
+    "sessions",
+    "会话",
+    [
+      "session_search",
+      "session_event_search",
+      "session_trace",
+      "session_event_trace",
+      "session_event_read",
+    ],
+  ],
+  [
+    "discovery",
+    "工具与技能",
+    [
+      "discover_business_tools",
+      "skill",
+      "explain_feature",
+      "save_workflow_skill",
+    ],
+  ],
+];
+const nativeCategories = new Map(
+  nativeGroups.flatMap(([key, label, names]) =>
+    names.map((name) => [
+      name,
+      { categoryKey: `workspace.${key}`, categoryLabel: label },
+    ]),
+  ),
+);
+
+/** Business ownership comes exclusively from actor-authorized Manifest metadata. */
+export function categoryMetadata(tool, supplied) {
+  if (tool.name.startsWith("mcp__windy__"))
+    return supplied?.moduleKey && supplied?.moduleLabel
+      ? { categoryKey: supplied.moduleKey, categoryLabel: supplied.moduleLabel }
+      : { categoryKey: "business", categoryLabel: "业务工具" };
+  return (
+    nativeCategories.get(tool.name) ?? {
+      categoryKey: "workspace.other",
+      categoryLabel: "其他工作区工具",
+    }
+  );
+}

package/template/apps/agent-server/plugins/tool-catalog/categories.test.ts

@@ -0,0 +1,118 @@
+import { expect, test } from "bun:test";
+import type { Context } from "@deepseek-ai/cordis";
+import { catalogue } from "./discovery.mjs";
+import { displayMetadata } from "./presentation.mjs";
+
+test("categories use authoritative module metadata, never an execution name or hash", () => {
+  const key = "mcp__windy__case_get_hiddenhash";
+  expect(displayMetadata({ name: key })).toMatchObject({
+    categoryKey: "business",
+    categoryLabel: "业务工具",
+  });
+  expect(
+    displayMetadata(
+      { name: key },
+      new Map([
+        [
+          key,
+          {
+            displayName: "读取资料",
+            moduleKey: "intelligence",
+            moduleLabel: "情报档案",
+          },
+        ],
+      ]),
+    ),
+  ).toMatchObject({ categoryKey: "intelligence", categoryLabel: "情报档案" });
+  for (const [name, categoryKey] of [
+    ["read", "workspace.files"],
+    ["exec_command", "workspace.commands"],
+    ["subagent", "workspace.collaboration"],
+    ["job_list", "workspace.tasks"],
+    ["session_search", "workspace.sessions"],
+    ["unknown_extension", "workspace.other"],
+  ])
+    expect(displayMetadata({ name }).categoryKey).toBe(categoryKey);
+});
+
+test("group counts cover the searched authorized directory before category filtering and pagination", () => {
+  const tools = Array.from({ length: 40 }, (_, index) => ({
+    name: `mcp__windy__opaque_${index}`,
+    description: "合成查询",
+    parameters: { secretSchema: "never-forward" },
+  }));
+  tools.push(
+    ...["read", "exec", "unknown_extension"].map((name) => ({
+      name,
+      description: "工作区操作",
+      parameters: { secretSchema: "never-forward" },
+    })),
+  );
+  const metadata = new Map(
+    tools.slice(0, 40).map((tool, index) => [
+      tool.name,
+      {
+        displayName: "业务读取",
+        moduleKey: index < 30 ? "case" : "analysis",
+        moduleLabel: index < 30 ? "案件" : "分析",
+      },
+    ]),
+  );
+  metadata.set("mcp__windy__not_in_actor_scope", {
+    displayName: "不可见",
+    moduleKey: "private",
+    moduleLabel: "不可见模块",
+  });
+  const ctx = {
+    tools: { schemas: () => tools },
+    agents: { list: () => [] },
+  } as unknown as Context;
+  const options = { includeNative: true, metadata, pageSize: 5, page: 2 };
+  const all = catalogue(ctx, options);
+  expect(all).toMatchObject({
+    total: 43,
+    matchedTotal: 43,
+    category: "",
+    page: 2,
+  });
+  expect(all.items).toHaveLength(5);
+  expect(all.groups.find((group) => group.categoryKey === "case")?.count).toBe(
+    30,
+  );
+  expect(
+    all.groups.find((group) => group.categoryKey === "analysis")?.count,
+  ).toBe(10);
+  expect(all.groups.reduce((count, group) => count + group.count, 0)).toBe(43);
+  expect(all.groups.some((group) => group.categoryKey === "private")).toBe(
+    false,
+  );
+  const selected = catalogue(ctx, { ...options, category: "case" });
+  expect(selected).toMatchObject({
+    total: 30,
+    matchedTotal: 43,
+    category: "case",
+  });
+  expect(selected.items).toHaveLength(5);
+  expect(selected.items.every((tool) => tool.categoryKey === "case")).toBe(
+    true,
+  );
+  expect(selected.groups).toEqual(all.groups);
+  const search = catalogue(ctx, {
+    ...options,
+    category: "case",
+    query: "案件",
+  });
+  expect(search.total).toBe(30);
+  expect(search.groups).toEqual([
+    { categoryKey: "case", categoryLabel: "案件", count: 30 },
+  ]);
+  expect(
+    catalogue(ctx, { ...options, category: "case", query: "no-match" }).total,
+  ).toBe(0);
+  expect(() => catalogue(ctx, { ...options, category: "private" })).toThrow(
+    "TOOL_CATEGORY_NOT_IN_AUTHORIZED_CATALOGUE",
+  );
+  tools.splice(0, 1);
+  expect(catalogue(ctx, { ...options, category: "case" }).total).toBe(29);
+  expect(JSON.stringify(selected)).not.toContain("never-forward");
+});

package/template/apps/agent-server/plugins/tool-catalog/client-cache.test.ts

@@ -0,0 +1,264 @@
+import { expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { runInNewContext } from "node:vm";
+
+type Element = {
+  type: string;
+  props: Record<string, unknown>;
+  children: unknown[];
+};
+type Effect = { deps: unknown[]; cleanup?: () => void };
+const groups = [
+  { categoryKey: "case", categoryLabel: "案件", count: 21 },
+  { categoryKey: "analysis", categoryLabel: "分析", count: 1 },
+];
+function catalogue(label = "全部", page = 1) {
+  return {
+    total: 22,
+    matchedTotal: 22,
+    pageSize: 20,
+    groups,
+    items: [{ name: `${label}-${page}`, displayName: label }],
+  };
+}
+function fixture(fetchResult?: (url: URL) => Promise<Response>) {
+  const hooks: unknown[] = [];
+  const effects = new Map<number, Effect>();
+  const timers = new Map<number, () => Promise<void>>();
+  const pending: (() => void)[] = [];
+  const requests: URL[] = [];
+  let cursor = 0,
+    timerId = 0,
+    dirty = true;
+  let render!: () => Element;
+  let tree!: Element;
+  let plugin!: { apply(ctx: unknown): void };
+  runInNewContext(readFileSync(new URL("client.js", import.meta.url), "utf8"), {
+    URL,
+    URLSearchParams,
+    AbortController,
+    document: { baseURI: "https://example.test/agent/" },
+    fetch: async (url: URL) => {
+      requests.push(url);
+      return fetchResult
+        ? fetchResult(url)
+        : Response.json(
+            catalogue(
+              url.searchParams.get("category") || "全部",
+              Number(url.searchParams.get("page")),
+            ),
+          );
+    },
+    setTimeout: (run: () => Promise<void>) => {
+      timers.set(++timerId, run);
+      return timerId;
+    },
+    clearTimeout: (id: number) => timers.delete(id),
+    window: {
+      __ModuleLoader__: {
+        load(definition: {
+          factory(require: (name: string) => unknown): typeof plugin;
+        }) {
+          plugin = definition.factory((name: string) =>
+            name === "react"
+              ? {
+                  createElement(
+                    type:
+                      | string
+                      | ((props: Record<string, unknown>) => Element),
+                    props: Record<string, unknown>,
+                    ...children: unknown[]
+                  ) {
+                    return typeof type === "function"
+                      ? type({ ...props, children })
+                      : { type, props, children };
+                  },
+                  useState(initial: unknown) {
+                    const index = cursor++;
+                    if (!(index in hooks)) hooks[index] = initial;
+                    return [
+                      hooks[index],
+                      (next: unknown) => {
+                        hooks[index] =
+                          typeof next === "function"
+                            ? next(hooks[index])
+                            : next;
+                        dirty = true;
+                      },
+                    ];
+                  },
+                  useRef(initial: unknown) {
+                    const index = cursor++;
+                    return (hooks[index] ||= { current: initial });
+                  },
+                  useEffect(
+                    run: () => (() => void) | undefined,
+                    deps: unknown[],
+                  ) {
+                    const index = cursor++;
+                    const previous = effects.get(index);
+                    if (
+                      !previous ||
+                      deps.some((value, i) => value !== previous.deps[i])
+                    ) {
+                      pending.push(() => {
+                        previous?.cleanup?.();
+                        effects.set(index, { deps, cleanup: run() });
+                      });
+                    }
+                  },
+                }
+              : { Button: "button", Input: "input", Tag: "span" },
+          );
+        },
+      },
+    },
+  });
+  plugin.apply({
+    slots: {
+      inject: (_name: string, run: () => void) => run(),
+      register: (_row: unknown, component: typeof render) => {
+        render = component;
+      },
+    },
+  });
+  function flush() {
+    for (let attempts = 0; dirty && attempts < 20; attempts++) {
+      dirty = false;
+      cursor = 0;
+      tree = render();
+      pending.splice(0).forEach((run) => run());
+    }
+    return tree;
+  }
+  function elements(value: unknown): Element[] {
+    if (!value || typeof value !== "object" || !("type" in value)) return [];
+    const element = value as Element;
+    return [element, ...element.children.flatMap(elements)];
+  }
+  return {
+    requests,
+    flush,
+    click(label: string) {
+      const button = elements(flush()).find(
+        (element) =>
+          element.type === "button" && element.children.includes(label),
+      );
+      if (!button) throw Error(`missing button ${label}`);
+      expect(button.props.disabled).not.toBe(true);
+      (button.props.onClick as () => void)();
+      flush();
+    },
+    search(value: string) {
+      const input = elements(flush()).find(
+        (element) => element.type === "input",
+      )!;
+      (input.props.onChange as (event: { target: { value: string } }) => void)({
+        target: { value },
+      });
+      flush();
+    },
+    async load() {
+      flush();
+      const runs = [...timers.values()];
+      timers.clear();
+      await Promise.all(runs.map((run) => run()));
+      flush();
+    },
+    visible: () => JSON.stringify(flush()),
+    unmount: () => {
+      for (const effect of effects.values()) effect.cleanup?.();
+    },
+  };
+}
+
+test("switching tabs, query and pages reuses only the matching cached results; refresh invalidates all", async () => {
+  const f = fixture();
+  await f.load();
+  f.click("案件 21");
+  await f.load();
+  f.click("分析 1");
+  await f.load();
+  f.click("案件 21");
+  await f.load();
+  expect(f.requests).toHaveLength(3);
+  expect(f.visible()).toContain('"aria-label":"使用case"');
+  f.click("下一页");
+  await f.load();
+  f.click("上一页");
+  await f.load();
+  expect(f.requests).toHaveLength(4);
+  f.search("查询");
+  await f.load();
+  f.search("");
+  await f.load();
+  expect(f.requests).toHaveLength(5);
+  f.click("刷新");
+  await f.load();
+  expect(f.requests).toHaveLength(6);
+  f.click("案件 21");
+  await f.load();
+  expect(f.requests).toHaveLength(7);
+});
+
+test("failed queries retry, and cache is not shared with another mounted panel", async () => {
+  let failures = 1;
+  const f = fixture(async (url) => {
+    if (url.searchParams.get("category") === "case" && failures--)
+      return new Response(null, { status: 503 });
+    return Response.json(catalogue());
+  });
+  await f.load();
+  f.click("案件 21");
+  await f.load();
+  expect(f.visible()).toContain("工具目录暂不可用");
+  f.click("全部 0");
+  await f.load();
+  f.click("案件 21");
+  await f.load();
+  expect(f.requests).toHaveLength(3);
+  expect(f.visible()).not.toContain("工具目录暂不可用");
+  f.unmount();
+  const next = fixture();
+  await next.load();
+  expect(next.requests).toHaveLength(1);
+});
+
+test("cancelled requests cannot overwrite the next tab or enter its cache", async () => {
+  let complete!: (response: Response) => void;
+  const f = fixture(async (url) =>
+    url.searchParams.get("category") === "case"
+      ? new Promise<Response>((resolve) => {
+          complete = resolve;
+        })
+      : Response.json(catalogue()),
+  );
+  await f.load();
+  f.click("案件 21");
+  const old = f.load();
+  f.click("分析 1");
+  await f.load();
+  complete(Response.json(catalogue("旧案件响应")));
+  await old;
+  expect(f.visible()).not.toContain("旧案件响应");
+  f.click("案件 21");
+  const retry = f.load();
+  expect(f.requests).toHaveLength(4);
+  complete(Response.json(catalogue()));
+  await retry;
+});
+
+test("cache evicts the least recently used result after 24 distinct filters", async () => {
+  const f = fixture();
+  await f.load();
+  for (let i = 0; i < 24; i++) {
+    f.search(`工具${i}`);
+    await f.load();
+  }
+  f.search("工具0");
+  await f.load();
+  expect(f.requests).toHaveLength(25);
+  f.search("");
+  await f.load();
+  expect(f.requests).toHaveLength(26);
+});