@77-zhike/app-sdk 0.2.0-d7b1.2 → 0.2.0-d7b1.20

package/src/toolchain/ai-capabilities.js

@@ -0,0 +1,69 @@
+import { assertToolManifest, assertAgentSchema } from './agents/manifest.js';
+import { assertAiExposure } from './agents/exposure.js';
+
+export function assertAiCapabilities(manifest) {
+  const invalid = () => { throw new TypeError('app_manifest_ai_capabilities_invalid'); };
+  const actions = manifest.actions === undefined ? [] : manifest.actions;
+  const data = manifest.dataCapabilities === undefined ? [] : manifest.dataCapabilities;
+  const agents = manifest.agents ?? [];
+  const hasAiFields = manifest.actions !== undefined || manifest.dataCapabilities !== undefined ||
+    agents.some(agent => agent.aiExposure !== undefined || agent.actionRefs !== undefined ||
+      agent.tools.some(tool => tool.aiExposure !== undefined));
+  if (manifest.aiCapabilitiesVersion !== undefined && manifest.aiCapabilitiesVersion !== '1') invalid();
+  if (hasAiFields && manifest.aiCapabilitiesVersion !== '1') invalid();
+  if (manifest.aiCapabilitiesVersion !== undefined && manifest.sdkAbiVersion !== '2') invalid();
+  if (!Array.isArray(actions) || actions.length > 64 || !Array.isArray(data) || data.length > 64) invalid();
+  if (manifest.frontendExtensions !== undefined) {
+    const renderers = new Set(manifest.frontendExtensions.filter(item => item.type === 'tool-renderer').map(item => item.key));
+    for (const tool of [...actions, ...agents.flatMap(agent => agent.tools)]) {
+      if (tool.toolRenderer && !renderers.has(tool.toolRenderer.key)) invalid();
+    }
+  }
+  const byKey = new Map();
+  for (const action of actions) {
+    assertToolManifest(action, `action/${action.key}`);
+    if (byKey.has(action.key) || action.clientResult !== 'none') invalid();
+    byKey.set(action.key, action);
+  }
+  const dataKeys = new Set();
+  for (const item of data) {
+    assertDataCapability(item);
+    if (dataKeys.has(item.key)) invalid();
+    dataKeys.add(item.key);
+    if (item.kind === 'live') {
+      const action = byKey.get(item.actionRef);
+      if (!action?.aiExposure || item.sourceBinding !== undefined ||
+          item.subjectTypes.some(type => !action.aiExposure.subjectTypes.includes(type))) invalid();
+    } else if (item.kind === 'published') {
+      if (typeof item.sourceBinding !== 'string' || !/^[a-z][a-z0-9-]{0,63}$/.test(item.sourceBinding) || item.actionRef !== undefined) invalid();
+    } else invalid();
+  }
+  for (const agent of agents) {
+    const refs = agent.actionRefs === undefined ? [] : agent.actionRefs;
+    if (!Array.isArray(refs) || refs.length > 32 || new Set(refs).size !== refs.length || refs.some(ref => !byKey.has(ref))) invalid();
+    if (agent.aiExposure !== undefined) {
+      assertAiExposure(agent.aiExposure, null, true);
+      assertAgentSchema(agent.aiExposure.outputSchema);
+      if (refs.some(ref => !byKey.get(ref).aiExposure) ||
+          (agent.aiExposure.toolKeys ?? []).some(key => !agent.tools.find(tool => tool.key === key)?.aiExposure)) invalid();
+    }
+  }
+  return manifest;
+}
+
+export function assertDataCapability(item) {
+  const invalid = () => { throw new TypeError('app_manifest_ai_capabilities_invalid'); };
+    if (!item || typeof item !== 'object' || Array.isArray(item) ||
+        Object.keys(item).some(key => !['key', 'name', 'description', 'subjectTypes', 'kind', 'sourceBinding', 'actionRef', 'usage'].includes(key)) ||
+        typeof item.key !== 'string' || !/^[a-z][a-z0-9-]{0,63}$/.test(item.key)) invalid();
+    for (const [key, max] of [['name', 80], ['description', 1200], ['usage', 1200]]) {
+      if (typeof item[key] !== 'string' || !item[key].trim() || item[key].length > max) invalid();
+    }
+    assertAiExposure({subjectTypes:item.subjectTypes, usage:item.usage, limitations:item.description, effect:'query'});
+  if (item.kind === 'published') {
+    if (typeof item.sourceBinding !== 'string' || !/^[a-z][a-z0-9-]{0,63}$/.test(item.sourceBinding) || item.actionRef !== undefined) invalid();
+  } else if (item.kind === 'live') {
+    if (typeof item.actionRef !== 'string' || !/^[a-z][a-z0-9-]{0,63}$/.test(item.actionRef) || item.sourceBinding !== undefined) invalid();
+  } else invalid();
+  return item;
+}

package/src/toolchain/allowed-packages.json

@@ -0,0 +1,7 @@
+{
+  "@77-zhike/qiqi-openapi": {
+    "versions": ["0.1.0"],
+    "targets": ["server"],
+    "subpaths": ["."]
+  }
+}

package/src/toolchain/dependency-policy.js

@@ -0,0 +1,181 @@
+import { readFileSync } from "node:fs";
+import { readFile, realpath } from "node:fs/promises";
+import { builtinModules } from "node:module";
+import { dirname, extname, isAbsolute, relative, resolve, sep } from "node:path";
+import ts from "typescript";
+import { ZhikeCliError } from "../errors.js";
+
+const packages = JSON.parse(readFileSync(new URL("./allowed-packages.json", import.meta.url), "utf8"));
+export const SDK_IMPORTS = new Set([
+  "@77-zhike/app-sdk", "@77-zhike/app-sdk/client", "@77-zhike/app-sdk/ui",
+  "@77-zhike/app-sdk/jsx-runtime", "@77-zhike/app-sdk/jsx-dev-runtime",
+  "@77-zhike/app-sdk/forms", "@77-zhike/app-sdk/server",
+  "react", "react/jsx-runtime", "react/jsx-dev-runtime",
+]);
+const builtins = new Set(builtinModules.map(name => name.replace(/^node:/, "")));
+
+function fail(code, source, message) {
+  throw new ZhikeCliError(code, source + ": " + message);
+}
+
+function splitPackage(specifier) {
+  const parts = specifier.split("/");
+  const length = specifier.startsWith("@") ? 2 : 1;
+  return { name: parts.slice(0, length).join("/"),
+    subpath: parts.length === length ? "." : "./" + parts.slice(length).join("/") };
+}
+
+export function assertAllowedPackageImport(specifier, target, source) {
+  if (specifier.startsWith("node:") || builtins.has(specifier)) {
+    fail("zhike_node_builtin_forbidden", source, "禁止 Node builtin " + specifier);
+  }
+  if (SDK_IMPORTS.has(specifier)) {
+    if (target === "client" && specifier === "@77-zhike/app-sdk/server") {
+      fail("zhike_server_sdk_client_forbidden", source, "前端代码不得导入服务端 SDK");
+    }
+    if (target === "server" && specifier === "@77-zhike/app-sdk/client") {
+      fail("zhike_client_sdk_server_forbidden", source, "服务端代码不得导入客户端 SDK 运行时");
+    }
+    return null;
+  }
+  const { name, subpath } = splitPackage(specifier);
+  const policy = Object.hasOwn(packages, name) ? packages[name] : null;
+  if (!policy) fail("zhike_external_dependency_forbidden", source, "未获准依赖 " + specifier);
+  if (!policy.targets.includes(target)) {
+    fail("zhike_dependency_target_forbidden", source, "该运行端不允许导入 " + name);
+  }
+  if (!policy.subpaths.includes(subpath)) {
+    fail("zhike_dependency_subpath_forbidden", source, "未获准包入口 " + specifier);
+  }
+  return { name, policy };
+}
+
+function within(root, path) {
+  const suffix = relative(root, path);
+  return suffix === "" || (!isAbsolute(suffix) && suffix !== ".." && !suffix.startsWith(".." + sep));
+}
+
+// 构建准入规则，不执行依赖代码；最终安全与授权仍由平台沙箱保证。
+export async function createDependencyPolicyPlugin(projectDirectory, target, validateSource) {
+  const projectRoot = await realpath(projectDirectory);
+  const sourceRoot = resolve(projectRoot, "src");
+  const roots = new Map();
+  const packageInfos = new Map();
+  const label = path => relative(projectRoot, path).split(sep).join("/");
+
+  async function packageInfo(path) {
+    let directory = dirname(path);
+    while (within(projectRoot, directory)) {
+      if (packageInfos.has(directory)) return packageInfos.get(directory);
+      let bytes;
+      try { bytes = await readFile(resolve(directory, "package.json"), "utf8"); }
+      catch (error) { if (error.code !== "ENOENT") throw error; }
+      if (bytes !== undefined) {
+        let metadata;
+        try { metadata = JSON.parse(bytes); }
+        catch { fail("zhike_dependency_metadata_invalid", label(path), "包元数据不是合法 JSON"); }
+        const info = { root: directory, name: metadata.name, version: metadata.version };
+        packageInfos.set(directory, info);
+        return info;
+      }
+      const parent = dirname(directory);
+      if (parent === directory) break;
+      directory = parent;
+    }
+    fail("zhike_dependency_path_forbidden", label(path), "依赖必须位于项目内的独立 npm 包");
+  }
+
+  function owner(path) {
+    return [...roots.values()].filter(info => within(info.root, path))
+      .sort((a, b) => b.root.length - a.root.length)[0] ?? null;
+  }
+
+  async function approve(path, expectedName) {
+    if (!within(projectRoot, path)) {
+      fail("zhike_dependency_path_forbidden", "dependency", "依赖真实路径不得越过项目目录");
+    }
+    const info = await packageInfo(path);
+    if (expectedName && info.name !== expectedName) {
+      fail("zhike_dependency_path_forbidden", label(path), "实际包身份与导入包名不一致");
+    }
+    const approved = assertAllowedPackageImport(info.name ?? "", target, label(path));
+    if (!approved) fail("zhike_dependency_path_forbidden", label(path), "不得经相对路径导入平台模块");
+    if (!approved.policy.versions.includes(info.version)) {
+      fail("zhike_dependency_version_forbidden", label(path), "未获准包版本 " + info.name + "@" + info.version);
+    }
+    roots.set(info.root, info);
+    return info;
+  }
+
+  return {
+    name: "zhike-package-policy",
+    setup(buildApi) {
+      async function resolveChecked(args, expectedName) {
+        const resolved = await buildApi.resolve(args.path, { resolveDir: args.resolveDir,
+          importer: args.importer, kind: args.kind,
+          pluginData: { zhikePolicyResolution: true } });
+        if (resolved.errors.length) {
+          fail("zhike_dependency_resolution_failed", args.path, "依赖无法解析，请安装项目声明的依赖");
+        }
+        if (resolved.external || resolved.namespace !== "file") {
+          fail("zhike_dependency_path_forbidden", args.path, "白名单包必须静态合并到 Artifact");
+        }
+        const path = await realpath(resolved.path);
+        let parent = null;
+        if (args.importer) {
+          try { parent = owner(await realpath(args.importer)); }
+          catch (error) { if (error.code !== "ENOENT") throw error; } // esbuild 的虚拟入口不在磁盘上。
+        }
+        if (!expectedName && parent && !within(parent.root, path)) {
+          fail("zhike_dependency_path_forbidden", label(path), "相对依赖不得越过所属包");
+        }
+        if (expectedName || parent) await approve(path, expectedName);
+        else if (!within(sourceRoot, path)) {
+          fail("zhike_source_import_outside_root", label(path), "App relative import 不得越过 src 根目录");
+        }
+        return { path };
+      }
+
+      buildApi.onResolve({ filter: /.*/ }, async args => {
+        if (args.pluginData?.zhikePolicyResolution || args.namespace !== "file") return;
+        if (args.path.startsWith(".") || isAbsolute(args.path)) return resolveChecked(args);
+        const approved = assertAllowedPackageImport(args.path, target, args.path);
+        if (approved) return resolveChecked(args, approved.name);
+      });
+
+      buildApi.onLoad({ filter: /.*/, namespace: "file" }, async args => {
+        const path = await realpath(args.path);
+        const info = owner(path);
+        if (!info) return;
+        await approve(path, info.name);
+        const extension = extname(path);
+        if (extension === ".json") return;
+        const loaders = { ".ts": "ts", ".tsx": "tsx", ".js": "js", ".mjs": "js", ".jsx": "jsx" };
+        if (!Object.hasOwn(loaders, extension)) {
+          fail("zhike_dependency_file_unsupported", label(path), "依赖只支持静态 ESM JS/TS 和 JSON");
+        }
+        const contents = await readFile(path, "utf8");
+        const sourceFile = ts.createSourceFile(label(path), contents, ts.ScriptTarget.ES2022, true,
+          extension === ".tsx" || extension === ".jsx" ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+        validateSource(sourceFile, label(path), { target, dependency: true });
+        // 在解析优化之前逐条解析，未使用的 import 也不能隐藏未批准依赖或路径逃逸。
+        for (const statement of sourceFile.statements) {
+          const specifier = (ts.isImportDeclaration(statement) || ts.isExportDeclaration(statement))
+            && statement.moduleSpecifier;
+          if (specifier && ts.isStringLiteral(specifier)) {
+            if (target === "server" && specifier.text === "@77-zhike/app-sdk/client"
+              && (statement.isTypeOnly || (ts.isImportDeclaration(statement) && statement.importClause?.isTypeOnly))) continue;
+            if (specifier.text.startsWith(".")) await resolveChecked({ path: specifier.text,
+              resolveDir: dirname(path), importer: path, kind: "import-statement" });
+            else {
+              const approved = assertAllowedPackageImport(specifier.text, target, label(path));
+              if (approved) await resolveChecked({ path: specifier.text, resolveDir: dirname(path),
+                importer: path, kind: "import-statement" }, approved.name);
+            }
+          }
+        }
+        return { contents, loader: loaders[extension], resolveDir: dirname(path) };
+      });
+    },
+  };
+}

package/src/toolchain/index.js

@@ -1,11 +1,3 @@
-import { createHash } from "node:crypto";
-import { mkdir, writeFile } from "node:fs/promises";
-import { resolve } from "node:path";
-
-import { TOOLING_VERSION } from "../config.js";
-import { ZhikeCliError } from "../errors.js";
-import { readProjectBinding } from "../project-binding.js";
-
 export { discoverAppSources } from "./source-discovery.js";
 export {
   APP_BUNDLE_CONTENT_TYPE,
@@ -21,83 +13,3 @@ export {
   createTransportTar,
   parseTransportTar,
 } from "./transport-tar.js";
-
-export const MOCK_PACKAGE_FORMAT = "zhike.mock-build.v1";
-export const MOCK_ARTIFACT_KIND = "mock";
-export const MOCK_ARTIFACT_MAX_BYTES = 1024 * 1024;
-
-export async function buildMockArtifact({
-  projectDirectory = process.cwd(),
-  expectedEnvironment = null,
-  writeToDist = false,
-} = {}) {
-  await readProjectBinding(projectDirectory, expectedEnvironment);
-  const payload = {
-    format: MOCK_PACKAGE_FORMAT,
-    kind: MOCK_ARTIFACT_KIND,
-    payload: {
-      message: "qiqizhike developer app mock build",
-    },
-    toolingVersion: TOOLING_VERSION,
-  };
-  const bytes = Buffer.from(`${JSON.stringify(payload)}\n`, "utf8");
-  if (bytes.byteLength > MOCK_ARTIFACT_MAX_BYTES) {
-    throw new ZhikeCliError(
-      "zhike_mock_artifact_too_large",
-      "Mock Artifact 超过 1 MiB 上限",
-    );
-  }
-  const result = Object.freeze({
-    bytes,
-    size: bytes.byteLength,
-    sha256: createHash("sha256").update(bytes).digest("hex"),
-    packageFormat: MOCK_PACKAGE_FORMAT,
-    kind: MOCK_ARTIFACT_KIND,
-    toolingVersion: TOOLING_VERSION,
-  });
-  if (writeToDist) {
-    const distDirectory = resolve(projectDirectory, "dist");
-    await mkdir(distDirectory, { recursive: true });
-    await writeFile(resolve(distDirectory, "mock-build.json"), bytes, {
-      flag: "w",
-    });
-  }
-  return result;
-}
-
-export function validateMockArtifact(bytes) {
-  if (!Buffer.isBuffer(bytes) || bytes.byteLength > MOCK_ARTIFACT_MAX_BYTES) {
-    throw new ZhikeCliError(
-      "zhike_mock_artifact_invalid",
-      "Mock Artifact 无效或超过 1 MiB 上限",
-    );
-  }
-  let value;
-  try {
-    value = JSON.parse(bytes.toString("utf8"));
-  } catch (error) {
-    throw new ZhikeCliError(
-      "zhike_mock_artifact_invalid",
-      "Mock Artifact 不是有效 JSON",
-      { cause: error },
-    );
-  }
-  const keys = Object.keys(value).sort();
-  if (
-    keys.join(",") !== "format,kind,payload,toolingVersion" ||
-    value.format !== MOCK_PACKAGE_FORMAT ||
-    value.kind !== MOCK_ARTIFACT_KIND ||
-    value.toolingVersion !== TOOLING_VERSION ||
-    !value.payload ||
-    typeof value.payload !== "object" ||
-    Array.isArray(value.payload) ||
-    Object.keys(value.payload).join(",") !== "message" ||
-    value.payload.message !== "qiqizhike developer app mock build"
-  ) {
-    throw new ZhikeCliError(
-      "zhike_mock_artifact_invalid",
-      "Mock Artifact 不符合 zhike.mock-build.v1 严格合同",
-    );
-  }
-  return value;
-}