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

package/package.json

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

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