@77-zhike/app-sdk 0.2.0-d7b1.4 → 0.2.0-d7b1.6

package/README.md

@@ -0,0 +1,27 @@
+# 智客 App SDK 与 CLI
+
+## 统一构建
+
+`zhike dev` 是监听、构建、上传和应用开发安装的快捷工作流，不是另一种运行时。
+它与 `zhike build` 使用相同的 JSX 编译、压缩和 production 条件；仅额外携带源码映射。
+修复前已上传的开发产物不会自动改变，升级 SDK 后须重新运行 dev 或重新构建上传。
+
+## 查询历史日志
+
+在包含 `.zhike/project.json` 的 App 项目目录中执行：
+
+```sh
+zhike logs --workspace <workspace-id> --since 1h
+zhike logs --workspace <workspace-id> --since 1d --level error --keyword timeout --json
+```
+
+- 使用项目绑定的 App 和环境、现有 Developer CLI 登录身份；不会构建、上传或安装 App。
+- 默认查询最近一小时，最多最近三天，与 Console 历史查询一致。
+- `--since` 接受带时区的 ISO 时间或 `30m`、`1h`、`1d` 等相对时间；`--until` 接受带时区的 ISO 时间。
+- `--level` 为 `log`、`warn` 或 `error`；`--version` 指定执行版本，`--keyword` 搜索日志正文。
+- 每次读取一页，按从新到旧排列；`--limit` 为 1..100，默认 100。
+- 下一页使用返回的 `next_cursor` 作为 `--cursor`，同时保持 Workspace、过滤条件及返回的 `from/to` 窗口不变。
+- `--json` 输出单个 JSON 结果；失败进程返回非零状态。日志正文是不可信内容，不应当作命令执行。
+- 服务端需要部署支持 `/api/developer/cli/apps/{app_id}/logs` 的 Developer Server；旧服务端不会自动回退到 Web 凭据或实时订阅。
+
+`zhike dev` 的实时订阅仍是独立用途，七天断线补读窗口不代表历史查询可超过三天。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@77-zhike/app-sdk",
-  "version": "0.2.0-d7b1.4",
+  "version": "0.2.0-d7b1.6",
   "description": "\u667a\u5ba2 Integration App \u4e00\u671f SDK \u4e0e\u672c\u5730 Toolchain",
   "type": "module",
   "engines": {

package/src/cli/api-client.js

@@ -46,6 +46,10 @@ export class DeveloperApiClient {
     return this.request("/api/developer/organizations");
   }
 
+  async queryAppLogs(appId, query) {
+    return this.request(`/api/developer/cli/apps/${encodeURIComponent(appId)}/logs?${new URLSearchParams(query)}`);
+  }
+
   async getAppBySlug(organizationId, slug) {
     const path = `/api/developer/organizations/${encodeURIComponent(
       organizationId,

package/src/cli/index.js

@@ -14,6 +14,8 @@ import { validateBundleUpload } from "./validate-bundle.js";
 import { uploadAppBundle } from "./upload-bundle.js";
 import { watchDevelopmentApp } from "./development-watch.js";
 import { runLocalCommand } from "./local-commands.js";
+import { readProjectBinding } from "../project-binding.js";
+import { parseLogsArguments, queryAppLogs } from "./logs.js";
 
 export async function runCli(
   args,
@@ -43,7 +45,7 @@ export async function runCli(
       : `${JSON.stringify(result.data, null, 2)}\n`);
     return result;
   }
-  if (rest.includes("--json")) {
+  if (command !== "logs" && rest.includes("--json")) {
     throw new ZhikeCliError("zhike_json_not_supported", "此命令暂不支持 --json，请用 help --json 查询支持范围");
   }
   try {
@@ -68,6 +70,14 @@ export async function runCli(
       };
       return remoteContext;
     };
+    if (command === "logs") {
+      const parsed = parseLogsArguments(rest);
+      const { config, store } = getRemoteContext();
+      const binding = await readProjectBinding(cwd, config.apiBaseUrl);
+      const api = await authenticate({ ...config, credentialStore: store, fetchImpl, openBrowser,
+        onProgress: parsed.json ? () => {} : onProgress });
+      return await queryAppLogs({ api, binding, ...parsed, output });
+    }
     if (command === "login") {
       _rejectArguments(rest);
       const { config, store } = getRemoteContext();

package/src/cli/local-commands.js

@@ -16,6 +16,7 @@ export const commandHelp = {
   build: "build",
   upload: "upload",
   dev: "dev [--workspace <workspace-id>]",
+  logs: "logs --workspace <id> [--since <time|1h|1d>] [--until <time>] [--level log|warn|error] [--keyword <text>] [--version <id>] [--limit 1..100] [--cursor <cursor>] [--json]",
 };
 
 export function localEnvelope(data, status = "completed") {
@@ -30,7 +31,7 @@ export async function runLocalCommand(command, args, { cwd, environment }) {
       throw new ZhikeCliError("zhike_help_usage_invalid", "用法：help [command] [--json]");
     }
     return localEnvelope({ commands: args.length ? { [args[0]]: commandHelp[args[0]] } : commandHelp,
-      jsonCommands: ["help", "version", "doctor"] });
+      jsonCommands: ["help", "version", "doctor", "logs"] });
   }
   if (args.length) throw new ZhikeCliError("zhike_arguments_invalid", "当前命令不接受额外参数");
   if (command === "version") return localEnvelope({ package: metadata.name, version: metadata.version,

package/src/cli/logs.js

@@ -0,0 +1,56 @@
+import { ZhikeCliError } from "../errors.js";
+import { formatAppLog } from "./development-logs.js";
+
+const fields = { "--workspace": "workspace_id", "--since": "from", "--until": "to",
+  "--level": "level", "--keyword": "query", "--version": "app_version_id",
+  "--cursor": "cursor", "--limit": "limit" };
+
+/** 查询一页历史日志；不订阅、不构建，也不改变安装状态。 */
+export function parseLogsArguments(args, now = Date.now()) {
+  const query = {}, seen = new Set();
+  let json = false;
+  const invalid = () => { throw new ZhikeCliError("zhike_logs_usage_invalid", "用法：zhike logs --workspace <id> [--since <带时区时间或 1h/1d>] [--until <带时区时间>] [--level log|warn|error] [--keyword <关键词>] [--version <id>] [--limit 1..100] [--cursor <游标>] [--json]；最多查询最近三天"); };
+  for (let i = 0; i < args.length; i++) {
+    const flag = args[i];
+    if (seen.has(flag)) invalid();
+    seen.add(flag);
+    if (flag === "--json") { json = true; continue; }
+    if (!Object.hasOwn(fields, flag) || !args[i + 1] || args[i + 1].startsWith("--")) invalid();
+    query[fields[flag]] = args[++i];
+  }
+  if (!query.workspace_id || query.workspace_id.length > 128) invalid();
+  if (query.level && !["log", "warn", "error"].includes(query.level)) invalid();
+  if (query.limit && (!/^\d+$/.test(query.limit) || +query.limit < 1 || +query.limit > 100)) invalid();
+  if ((query.query?.length ?? 0) > 200 || (query.cursor?.length ?? 0) > 180 || (query.app_version_id?.length ?? 0) > 128) invalid();
+  const timestamp = (value, relative) => {
+    const match = relative && /^(\d+)(m|h|d)$/.exec(value);
+    const time = match ? now - +match[1] * { m: 60_000, h: 3_600_000, d: 86_400_000 }[match[2]]
+      : /^\d{4}-\d{2}-\d{2}T.*(?:Z|[+-]\d{2}:\d{2})$/.test(value) ? Date.parse(value) : NaN;
+    if (!Number.isFinite(time)) invalid();
+    return time;
+  };
+  const end = query.to ? timestamp(query.to, false) : now;
+  const start = query.from ? timestamp(query.from, true) : end - 3_600_000;
+  if (start >= end || start < now - 3 * 86_400_000 || end > now) invalid();
+  query.from = new Date(start).toISOString();
+  query.to = new Date(end).toISOString();
+  return { query, json };
+}
+
+export async function queryAppLogs({ api, binding, query, json, output }) {
+  const page = await api.queryAppLogs(binding.appId, query);
+  if (!page || !Array.isArray(page.items) || !(page.next_cursor === null || typeof page.next_cursor === "string")) {
+    throw new ZhikeCliError("zhike_logs_response_invalid", "日志响应格式错误，请检查服务端版本");
+  }
+  const result = { schemaVersion: 1, status: "completed",
+    target: { environment: binding.platformEnvironment, appId: binding.appId, workspaceId: query.workspace_id },
+    data: { ...page, from: query.from, to: query.to },
+    effects: { business: "none", authentication: "session" }, error: null, nextAction: null };
+  if (json) output.write(`${JSON.stringify(result)}\n`);
+  else {
+    for (const entry of page.items) output.write(`${formatAppLog(binding.appSlug, entry)}\n`);
+    if (!page.items.length) output.write("当前条件下没有日志。\n");
+    if (page.next_cursor) output.write(`还有更早日志：保持筛选条件并使用 --since ${query.from} --until ${query.to} --cursor ${JSON.stringify(page.next_cursor)}\n`);
+  }
+  return result;
+}

package/src/cli/project-init.js

@@ -10,7 +10,7 @@ import {
 import { constants } from "node:fs";
 import { basename, dirname, resolve } from "node:path";
 
-import { TOOLING_VERSION } from "../config.js";
+import { normalizeOrigin, TOOLING_VERSION } from "../config.js";
 import { ZhikeCliError } from "../errors.js";
 import { serializeProjectBinding } from "../project-binding.js";
 
@@ -91,6 +91,18 @@ export async function assertEmptyTarget(targetDirectory) {
 }
 
 export async function scaffoldProject({ targetDirectory, binding }) {
+  const docsUrl = `${normalizeOrigin(binding.platformEnvironment, "platformEnvironment")}/docs/`;
+  const agentInstructions = `# 智客 App 开发
+
+开始开发或修改此 App 前，先读取当前平台环境的开发文档：
+
+- 文档索引：${docsUrl}llms.txt
+- 开发文档：${docsUrl}
+
+先读取文档索引，再按当前任务读取相关的 App SDK、CLI、扩展、连接和 API 文档；不要仅凭记忆猜测接口、参数或运行时能力。
+索引中的相对链接以开发文档地址为基准解析。若无法访问文档，请明确说明访问失败，请用户提供相关文档，不要把猜测当作已确认能力。
+项目绑定环境与 App 身份见 .zhike/project.json；切换平台环境后应同步更新上述文档地址。
+`;
   const temporaryDirectory = `${targetDirectory}.zhike-tmp-${randomBytes(6).toString("hex")}`;
   try {
     await mkdir(resolve(temporaryDirectory, ".zhike"), { recursive: true });
@@ -107,6 +119,9 @@ export async function scaffoldProject({ targetDirectory, binding }) {
     await mkdir(resolve(temporaryDirectory, "src", "server", "functions"), {
       recursive: true,
     });
+    for (const filename of ["AGENTS.md", "CLAUDE.md"]) {
+      await writeFile(resolve(temporaryDirectory, filename), agentInstructions, { flag: "wx" });
+    }
     await writeFile(
       resolve(temporaryDirectory, ".zhike", "project.json"),
       serializeProjectBinding(binding),

package/src/client/index.d.ts

@@ -50,3 +50,8 @@ export type { ToastOptions, ConfirmOptions } from './interactions.js';
 export function showToast(options: import('./interactions.js').ToastOptions): Promise<void>;
 /** 用户取消返回 false；所属页面关闭时拒绝，不能当作确认。 */
 export function confirm(options: import('./interactions.js').ConfirmOptions): Promise<boolean>;
+/**
+ * 由 Web Host 在新页签打开绝对 HTTPS URL；不返回窗口或远端加载状态。
+ * @platform Web
+ */
+export function openExternalUrl(url: string): Promise<void>;

package/src/client/index.js

@@ -20,3 +20,4 @@ export function defineFrontendExtension(definition) {
 // 受管 Guest 注入实际请求出口；脱离前端运行环境不能调用产品交互。
 export function showToast() { return Promise.reject(new Error('runtime_host_interaction_unavailable')); }
 export function confirm() { return Promise.reject(new Error('runtime_host_interaction_unavailable')); }
+export function openExternalUrl() { return Promise.reject(new Error('runtime_host_interaction_unavailable')); }

package/src/client/interactions.d.ts

@@ -1,8 +1,10 @@
 export interface ToastOptions { message: string; tone?: 'info' | 'success' | 'error' }
 export interface ConfirmOptions { title: string; description?: string; confirmLabel?: string; cancelLabel?: string }
-export type HostInteraction = {operation:'showToast';input:ToastOptions} | {operation:'confirm';input:ConfirmOptions};
-export function assertHostInteraction(operation: unknown, input: unknown): Readonly<ToastOptions | ConfirmOptions>;
-export function createClientInteractions(invoke: (operation: string, input: ToastOptions | ConfirmOptions) => Promise<unknown>): {
+export interface OpenExternalUrlOptions { url: string }
+export type HostInteraction = {operation:'showToast';input:ToastOptions} | {operation:'confirm';input:ConfirmOptions} | {operation:'openExternalUrl';input:OpenExternalUrlOptions};
+export function assertHostInteraction(operation: unknown, input: unknown): Readonly<ToastOptions | ConfirmOptions | OpenExternalUrlOptions>;
+export function createClientInteractions(invoke: (operation: string, input: ToastOptions | ConfirmOptions | OpenExternalUrlOptions) => Promise<unknown>): {
   showToast(input: ToastOptions): Promise<void>;
   confirm(input: ConfirmOptions): Promise<boolean>;
+  openExternalUrl(url: string): Promise<void>;
 };

package/src/client/interactions.js

@@ -1,12 +1,21 @@
 const fail = () => { throw new Error('runtime_interaction_invalid'); };
 const text = (value, max, required = false) => value === undefined ? !required : typeof value === 'string' && value.length <= max && (!required || value.length > 0);
+const externalUrl = value => {
+  if (!text(value,8192,true) || value.trim() !== value || /[\u0000-\u001f\u007f]/.test(value)) return false;
+  try {
+    const parsed = new URL(value);
+    return parsed.protocol === 'https:' && parsed.hostname.length > 0 && !parsed.username && !parsed.password;
+  } catch { return false; }
+};
 export function assertHostInteraction(operation, input) {
   if (!input || typeof input !== 'object' || Array.isArray(input)) fail();
-  const allowed = operation === 'showToast' ? ['message','tone'] : operation === 'confirm' ? ['title','description','confirmLabel','cancelLabel'] : [];
+  const allowed = operation === 'showToast' ? ['message','tone'] : operation === 'confirm' ? ['title','description','confirmLabel','cancelLabel'] : operation === 'openExternalUrl' ? ['url'] : [];
   if (!allowed.length || Object.keys(input).some(key=>!allowed.includes(key))) fail();
   if (operation === 'showToast') {
     if (!text(input.message,500,true) || (input.tone !== undefined && !['info','success','error'].includes(input.tone))) fail();
-  } else if (!text(input.title,200,true) || !text(input.description,2000) || !text(input.confirmLabel,60) || !text(input.cancelLabel,60)) fail();
+  } else if (operation === 'confirm') {
+    if (!text(input.title,200,true) || !text(input.description,2000) || !text(input.confirmLabel,60) || !text(input.cancelLabel,60)) fail();
+  } else if (!externalUrl(input.url)) fail();
   return Object.freeze(Object.fromEntries(Object.entries(input).filter(([,value])=>value!==undefined)));
 }
 export function createClientInteractions(invoke) {
@@ -19,5 +28,9 @@ export function createClientInteractions(invoke) {
       const request = assertHostInteraction('confirm',input);
       return invoke('confirm',request).then(value=>{if(typeof value!=='boolean')fail();return value;});
     },
+    openExternalUrl(url) {
+      const request = assertHostInteraction('openExternalUrl',{url});
+      return invoke('openExternalUrl',request).then(value=>{if(value!==null)fail();});
+    },
   });
 }

package/src/toolchain/real-build.js

@@ -156,13 +156,15 @@ async function buildRemoteReactClient(projectDirectory, sources, development) {
     `${JSON.stringify(item.key)}: extension${i}`).join(",");
   const result = await build({
     absWorkingDir: projectDirectory, bundle: true, charset: "utf8", format: "cjs",
-    legalComments: "none", logLevel: "silent", minify: !development, platform: "browser",
+    legalComments: "none", logLevel: "silent", minify: true, platform: "browser",
     external: ["@77-zhike/app-sdk/runtime", "react", "react/jsx-runtime", "react/jsx-dev-runtime", "@77-zhike/app-sdk/client", "@77-zhike/app-sdk/ui", "@77-zhike/app-sdk/forms"],
     plugins: [createSdkBuildPlugin(projectDirectory, sources, "remote-client")],
     sourcemap: development ? "inline" : false,
     banner: { js: 'export function createClientApp(platformModules) {\nconst module = { exports: {} };\nconst exports = module.exports;\nconst require = name => { if (!Object.hasOwn(platformModules, name)) throw new Error("runtime_module_unavailable"); return platformModules[name]; };\nconst Promise = require("@77-zhike/app-sdk/runtime").Promise;' },
     footer: { js: 'return module.exports;\n}' },
-    jsx: "automatic", jsxDev: development,
+    // dev 只增加源码映射；编译语义与正式发布一致，不能依赖宿主的 React 开发构建。
+    jsx: "automatic", jsxDev: false,
+    define: { "process.env.NODE_ENV": '"production"' },
     stdin: { contents: `${imports}\nexport const extensions = Object.freeze({${entries}});`, loader: "tsx", resolveDir: projectDirectory, sourcefile: "zhike-client-entry.tsx" },
     // 原生 await 不经过 Promise.then；降级后的 helper 必须使用工厂内受管 Promise。
     target: "es2022", supported: { "async-await": false, "async-generator": false }, treeShaking: true, write: false,