@77-zhike/app-sdk 0.2.0-d7b1.12 → 0.2.0-d7b1.14

package/README.md

@@ -1,5 +1,13 @@
 # 智客 App SDK 与 CLI
 
+## 操作系统与 Windows 候选
+
+当前 npm 发布版的 Developer CLI 仅提供 macOS Keychain 适配。本开发分支新增 Windows Credential Manager 候选：复用现有浏览器 PKCE 和 Session，使用系统 Windows PowerShell 5.1 固定桥接，refresh credential 按当前用户和 API origin 存储。
+
+Windows 候选通过独立的 `SDK Windows 自动化验证（不发布）` Actions 检查，分别运行 Node 22/24。测试制品仅供验证，未发布 npm；Windows 11 桌面、系统默认浏览器弹起、双用户和注销重登暂未覆盖。完整结果与边界见 `openspec/changes/windows-app-developer-cli/`。
+
+`zhike doctor --json` 的 `secureStore` 检查表示当前机制可用性，`writeAccess: not_checked` 和 `authentication: not_checked` 不证明凭据已保存、登录有效或业务可用。系统策略禁止桥接时会返回安全存储错误，不修改系统策略或降级为明文文件。
+
 ## 获准依赖
 
 工具链从 `src/toolchain/allowed-packages.json` 读取平台维护的包白名单。目前允许 `@77-zhike/qiqi-openapi@0.1.0` 的服务端包根入口 `.`；前端不可导入。项目安装依赖后直接使用静态 ESM import，真实解析的包名、精确版本、入口及间接模块在打包时核对，代码合并进 Artifact。App 的 Manifest、Settings 或 `package.json` 不能扩展名单。
@@ -253,3 +261,11 @@ Chart 仅接受纯数据 `labels` 与 `series`，不接受脚本、HTML 或任
 ### 精确数字的表格录入
 
 `form.TextInput` 可选 `labelHidden` 和 `inputMode="numeric" | "decimal"`。隐藏标题仍保留与控件关联的读屏标签，默认标题继续显示，字段错误和说明仍显示。`inputMode` 只提示键盘，不转换、过滤或格式化值，不替代业务校验；需要保留十进制字符串或未完成输入时使用，数值型字段继续使用 `NumberInput`。
+
+## App 对话输入部件
+
+`Conversation.Root` 内自由组合 Messages、History、NewButton、Status、Composer。History 默认使用与 automation 相同的图标弹出列表；Composer 默认带附件/图片上传和语音回填，转写后仍需用户发送。输入能力由 Host 提供，不把 File/音频字节或凭据交给 App Worker。
+
+附件只读当前 App 会话中用户提交的文件，不扩展自定义 Tool 的权限。新 App 业务 Tool 仍在 agent 目录用 `.tools.ts` 合并定义并由 Integration Runtime 执行。元数据 Schema 必须为静态字面量，execute 可导入项目自己的业务校验函数。
+
+真实表单协作可参考 `built-in-apps/opportunity-quotes`：页面以 SDK 布局并列 Form 与 Conversation，callback 接收建议，用户确认后更新本地草稿；正式保存沿原入口。NativeDOM 内仍只允许原有控件，不直接放 Conversation；可以在 Conversation 内用独立 NativeDOM 展示本地建议确认区。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@77-zhike/app-sdk",
-  "version": "0.2.0-d7b1.12",
+  "version": "0.2.0-d7b1.14",
   "description": "智客 Integration App 一期 SDK 与本地 Toolchain",
   "repository": {
     "type": "git",
@@ -67,5 +67,5 @@
       "optional": true
     }
   },
-  "gitHead": "371b8a58d0f56deb5d1a330a688bc84c90704231"
+  "gitHead": "04ae9c07742d99322d12790db9c7934cea8f6f64"
 }

package/src/cli/browser-auth.js

@@ -2,6 +2,7 @@ import { execFile as execFileCallback } from "node:child_process";
 import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
 import { createServer } from "node:http";
 import { promisify } from "node:util";
+import { win32 } from "node:path";
 
 import { CLI_CLIENT_ID } from "../config.js";
 import { ZhikeCliError } from "../errors.js";
@@ -17,25 +18,33 @@ export async function authorizeCli({
   openBrowser = openSystemBrowser,
   onProgress = () => {},
   timeoutMs = 120_000,
+  signal,
 }) {
   const state = randomBytes(32).toString("base64url");
   const codeVerifier = randomBytes(48).toString("base64url");
   const codeChallenge = createHash("sha256")
     .update(codeVerifier, "ascii")
     .digest("base64url");
-  const callback = await createLoopbackCallback({ state, timeoutMs });
-  const redirectUri = `http://127.0.0.1:${callback.port}/callback`;
-  const authorizationUrl = new URL("/cli/authorize", consoleBaseUrl);
-  authorizationUrl.searchParams.set("client_id", CLI_CLIENT_ID);
-  authorizationUrl.searchParams.set("redirect_uri", redirectUri);
-  authorizationUrl.searchParams.set("code_challenge", codeChallenge);
-  authorizationUrl.searchParams.set("code_challenge_method", "S256");
-  authorizationUrl.searchParams.set("state", state);
-
+  const cancellation = new AbortController();
+  const stop = () => cancellation.abort();
+  const authorizationSignal = signal || cancellation.signal;
+  if (!signal) { process.once("SIGINT", stop); process.once("SIGTERM", stop); }
+  let callback;
   try {
+    if (authorizationSignal.aborted) throw new ZhikeCliError("zhike_cli_authorization_cancelled", "Developer CLI 授权已取消", { exitCode: 130 });
+    callback = await createLoopbackCallback({ state, timeoutMs, signal: authorizationSignal });
+    if (authorizationSignal.aborted) await callback.waitForCode;
+    const redirectUri = `http://127.0.0.1:${callback.port}/callback`;
+    const authorizationUrl = new URL("/cli/authorize", consoleBaseUrl);
+    authorizationUrl.searchParams.set("client_id", CLI_CLIENT_ID);
+    authorizationUrl.searchParams.set("redirect_uri", redirectUri);
+    authorizationUrl.searchParams.set("code_challenge", codeChallenge);
+    authorizationUrl.searchParams.set("code_challenge_method", "S256");
+    authorizationUrl.searchParams.set("state", state);
     callback.waitForCode.catch(() => {});
     onProgress("正在浏览器中完成 Developer CLI 授权...");
-    await openBrowser(authorizationUrl.toString());
+    try { await openBrowser(authorizationUrl.toString()); }
+    catch { onProgress(`无法自动打开浏览器，请手动访问：${authorizationUrl}`); }
     const code = await callback.waitForCode;
     onProgress("已收到浏览器授权，正在完成 Developer CLI 登录...");
     const api = new DeveloperApiClient({ apiBaseUrl, fetchImpl });
@@ -45,10 +54,11 @@ export async function authorizeCli({
       redirect_uri: redirectUri,
       code_verifier: codeVerifier,
     });
-    await credentialStore.set(apiBaseUrl, token.refresh_credential);
+    await persistRefreshCredential(api, token.refresh_credential, credentialStore);
     return renewableClient(api, token.access_token, credentialStore);
   } finally {
-    await callback.close();
+    await callback?.close();
+    if (!signal) { process.removeListener("SIGINT", stop); process.removeListener("SIGTERM", stop); }
   }
 }
 
@@ -77,7 +87,7 @@ export async function authenticateCli({
     }
     if (token) {
       if (token.refresh_credential !== refreshCredential) {
-        await credentialStore.set(apiBaseUrl, token.refresh_credential);
+        await persistRefreshCredential(api, token.refresh_credential, credentialStore);
       }
       return renewableClient(api, token.access_token, credentialStore);
     }
@@ -98,16 +108,27 @@ export async function authenticateCli({
   });
 }
 
-export async function openSystemBrowser(url, platform = process.platform) {
+export async function openSystemBrowser(url, platform = process.platform, { runner = execFile, systemRoot = process.env.SystemRoot } = {}) {
+  const parsed = new URL(url);
+  if (!["http:", "https:"].includes(parsed.protocol) || parsed.username || parsed.password) {
+    throw new ZhikeCliError("zhike_browser_open_failed", "浏览器地址必须是无凭据的 HTTP(S) URL");
+  }
+  // URL 只作为 base64 数据传入固定表达式，避免 cmd/start 把 query 中的 & 当成命令。
+  const encodedUrl = Buffer.from(parsed.href, "utf8").toString("base64");
+  const windowsCommand = `Start-Process -FilePath ([Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('${encodedUrl}')))`;
   const command =
     platform === "darwin"
       ? ["open", [url]]
       : platform === "win32"
-        ? ["cmd", ["/c", "start", "", url]]
+        ? [systemRoot && win32.isAbsolute(systemRoot)
+          ? win32.join(systemRoot, "System32", "WindowsPowerShell", "v1.0", "powershell.exe") : "",
+          ["-NoLogo", "-NoProfile", "-NonInteractive", "-EncodedCommand", Buffer.from(windowsCommand, "utf16le").toString("base64")]]
         : ["xdg-open", [url]];
   try {
-    await execFile(command[0], command[1], {
+    if (!command[0]) throw new Error("system browser unavailable");
+    await runner(command[0], command[1], {
       windowsHide: true,
+      timeout: 10_000,
     });
   } catch (error) {
     throw new ZhikeCliError(
@@ -127,14 +148,30 @@ function renewableClient(api, accessToken, credentialStore) {
     }
     const token = await api.refreshCliSession(refreshCredential);
     if (token.refresh_credential !== refreshCredential) {
-      await credentialStore.set(api.apiBaseUrl, token.refresh_credential);
+      await persistRefreshCredential(api, token.refresh_credential, credentialStore);
     }
     return token.access_token;
   };
   return client;
 }
 
-async function createLoopbackCallback({ state, timeoutMs }) {
+async function persistRefreshCredential(api, refreshCredential, credentialStore) {
+  try { await credentialStore.set(api.apiBaseUrl, refreshCredential); }
+  catch {
+    let cleanupConfirmed = false;
+    const previousSignal = api.signal;
+    try {
+      api.signal = AbortSignal.timeout(5_000);
+      await api.logoutCliSession(refreshCredential);
+      cleanupConfirmed = true;
+    } catch { /* 网络失败不改变本地存储失败这一事实。 */ }
+    finally { api.signal = previousSignal; }
+    throw new ZhikeCliError("zhike_secure_store_failed", "无法保存 Developer CLI 登录凭据，请修复系统安全存储后重新登录"
+      + (cleanupConfirmed ? "" : "；远端会话清理未确认"));
+  }
+}
+
+async function createLoopbackCallback({ state, timeoutMs, signal }) {
   let timer;
   let resolveCode;
   let rejectCode;
@@ -142,6 +179,7 @@ async function createLoopbackCallback({ state, timeoutMs }) {
     resolveCode = resolve;
     rejectCode = reject;
   });
+  waitForCode.catch(() => {});
   const server = createServer((request, response) => {
     const url = new URL(request.url || "/", "http://127.0.0.1");
     const receivedState = url.searchParams.get("state") || "";
@@ -169,6 +207,13 @@ async function createLoopbackCallback({ state, timeoutMs }) {
     server.once("error", reject);
     server.listen(0, "127.0.0.1", resolve);
   });
+  const cancel = () => {
+    rejectCode(new ZhikeCliError("zhike_cli_authorization_cancelled", "Developer CLI 授权已取消", { exitCode: 130 }));
+    server.close();
+    server.closeAllConnections();
+  };
+  signal?.addEventListener("abort", cancel, { once: true });
+  if (signal?.aborted) cancel();
   const address = server.address();
   if (!address || typeof address === "string") {
     server.close();
@@ -190,6 +235,7 @@ async function createLoopbackCallback({ state, timeoutMs }) {
     waitForCode,
     close: async () => {
       clearTimeout(timer);
+      signal?.removeEventListener("abort", cancel);
       if (!server.listening) {
         return;
       }

package/src/cli/credential-store.js

@@ -1,7 +1,9 @@
 import { execFile as execFileCallback } from "node:child_process";
 import { promisify } from "node:util";
+import { randomUUID } from "node:crypto";
 
 import { ZhikeCliError } from "../errors.js";
+import { WindowsCredentialStore } from "./windows-credential-store.js";
 
 const execFile = promisify(execFileCallback);
 const KEYCHAIN_SERVICE = "com.77hub.zhike.developer-cli";
@@ -86,12 +88,31 @@ export function createSystemCredentialStore(platform = process.platform) {
   if (platform === "darwin") {
     return new MacOSKeychainCredentialStore();
   }
+  if (platform === "win32") {
+    return new WindowsCredentialStore();
+  }
   throw new ZhikeCliError(
     "zhike_secure_store_unavailable",
     "当前操作系统尚未配置安全凭据存储适配器",
   );
 }
 
+export async function inspectSystemCredentialStore(platform = process.platform, createStore = createSystemCredentialStore) {
+  const provider = platform === "darwin" ? "macos-keychain" : platform === "win32" ? "windows-credential-manager" : null;
+  const check = { name: "secureStore", platform, provider, supported: Boolean(provider),
+    available: false, ok: false, writeAccess: "not_checked" };
+  if (!provider) return { ...check, code: "zhike_secure_store_unavailable" };
+  try {
+    const store = createStore(platform);
+    if (store.probe) await store.probe();
+    else await store.get(`https://probe-${randomUUID()}.invalid`);
+    return { ...check, available: true, ok: true };
+  } catch (error) {
+    return { ...check, code: ["zhike_secure_store_unavailable", "zhike_secure_store_failed"].includes(error?.code)
+      ? error.code : "zhike_secure_store_failed" };
+  }
+}
+
 function _keychainError(error) {
   return new ZhikeCliError(
     "zhike_secure_store_failed",

package/src/cli/local-commands.js

@@ -5,6 +5,7 @@ import { resolve } from "node:path";
 import { loadCliConfig } from "../config.js";
 import { ZhikeCliError } from "../errors.js";
 import { readProjectBinding } from "../project-binding.js";
+import { inspectSystemCredentialStore } from "./credential-store.js";
 
 const metadata = JSON.parse(await readFile(new URL("../../package.json", import.meta.url), "utf8"));
 export const commandHelp = {
@@ -72,7 +73,7 @@ export async function runLocalCommand(command, args, { cwd, environment }) {
   } catch {
     checks.push({ name: "package", ok: false, code: "package_missing_or_invalid" });
   }
-  checks.push({ name: "secureStore", ok: process.platform === "darwin", platform: process.platform });
+  checks.push(await inspectSystemCredentialStore());
   const result = localEnvelope({ localReady: checks.every((check) => check.ok),
     authentication: "not_checked", installation: "not_checked", checks });
   result.target = config ? { environment: config.apiBaseUrl, appId: binding?.appId ?? null } : null;

package/src/cli/windows-credential-bridge.ps1

@@ -0,0 +1,131 @@
+$ErrorActionPreference = 'Stop'
+$ProgressPreference = 'SilentlyContinue'
+$PSModuleAutoLoadingPreference = 'None'
+
+try {
+    if ($ExecutionContext.SessionState.LanguageMode -ne 'FullLanguage') {
+        [Console]::Out.Write('{"version":1,"ok":false,"code":"zhike_secure_store_unavailable"}')
+        exit 0
+    }
+    Import-Module "$PSHOME\Modules\Microsoft.PowerShell.Utility\Microsoft.PowerShell.Utility.psd1" -ErrorAction Stop
+    [Console]::InputEncoding = New-Object System.Text.UTF8Encoding($false)
+    [Console]::OutputEncoding = New-Object System.Text.UTF8Encoding($false)
+    $request = [Console]::In.ReadToEnd() | ConvertFrom-Json
+    $keys = @($request.PSObject.Properties.Name)
+    if ($request.version -ne 1 -or $request.operation -notin @('get', 'set', 'delete', 'probe') -or
+        @($keys | Where-Object { $_ -notin @('version', 'operation', 'origin', 'credential') }).Count -ne 0 -or
+        $request.origin -isnot [string] -or $request.origin.Length -gt 2048) { throw 'invalid request' }
+    $uri = New-Object System.Uri($request.origin, [System.UriKind]::Absolute)
+    if ($uri.Scheme -notin @('http', 'https') -or $uri.UserInfo -or $uri.AbsolutePath -ne '/' -or $uri.Query -or $uri.Fragment) { throw 'invalid origin' }
+    if ($request.operation -eq 'set') {
+        if ($request.credential -isnot [string] -or $request.credential.Length -lt 1 -or $request.credential.Length -gt 512) { throw 'invalid credential' }
+    } elseif ($keys -contains 'credential') { throw 'unexpected credential' }
+
+    # 仅绑定固定 Win32 API；全部在内存中构造，避免运行时编译器对 Unicode TEMP 的依赖。
+    $assembly = [AppDomain]::CurrentDomain.DefineDynamicAssembly(
+        (New-Object Reflection.AssemblyName('ZhikeCredentialBridge')), [Reflection.Emit.AssemblyBuilderAccess]::Run)
+    $module = $assembly.DefineDynamicModule('ZhikeCredentialBridge')
+    $layout = [Reflection.TypeAttributes]::Public -bor [Reflection.TypeAttributes]::SequentialLayout -bor [Reflection.TypeAttributes]::Sealed
+    $structure = $module.DefineType('ZhikeCredential', $layout, [ValueType])
+    # 字段顺序对应 CREDENTIALW；指针由当前进程位数决定，FILETIME 作为 64 位值对齐。
+    $fields = @(
+        @('Flags', [uint32]), @('Type', [uint32]), @('TargetName', [IntPtr]), @('Comment', [IntPtr]),
+        @('LastWritten', [long]), @('CredentialBlobSize', [uint32]), @('CredentialBlob', [IntPtr]),
+        @('Persist', [uint32]), @('AttributeCount', [uint32]), @('Attributes', [IntPtr]),
+        @('TargetAlias', [IntPtr]), @('UserName', [IntPtr]))
+    foreach ($field in $fields) { [void]$structure.DefineField($field[0], $field[1], [Reflection.FieldAttributes]::Public) }
+    $credentialType = $structure.CreateType()
+    $binding = $module.DefineType('ZhikeNativeCredential', [Reflection.TypeAttributes]::Public)
+    $dllImport = [Runtime.InteropServices.DllImportAttribute]
+    $importFields = [Reflection.FieldInfo[]]@($dllImport.GetField('EntryPoint'), $dllImport.GetField('CharSet'), $dllImport.GetField('SetLastError'))
+    $signatures = @(
+        @('Read', 'CredReadW', [bool], [type[]]@([string], [uint32], [uint32], [IntPtr].MakeByRefType())),
+        @('Write', 'CredWriteW', [bool], [type[]]@([IntPtr], [uint32])),
+        @('Delete', 'CredDeleteW', [bool], [type[]]@([string], [uint32], [uint32])),
+        @('Free', 'CredFree', [void], [type[]]@([IntPtr])))
+    foreach ($signature in $signatures) {
+        $method = $binding.DefineMethod($signature[0], [Reflection.MethodAttributes]'Public, Static, PinvokeImpl', $signature[2], $signature[3])
+        $attribute = New-Object Reflection.Emit.CustomAttributeBuilder(
+            $dllImport.GetConstructor([type[]]@([string])), [object[]]@('advapi32.dll'),
+            $importFields, [object[]]@($signature[1], [Runtime.InteropServices.CharSet]::Unicode, $true))
+        $method.SetCustomAttribute($attribute)
+        $method.SetImplementationFlags([Reflection.MethodImplAttributes]::PreserveSig)
+    }
+    $native = $binding.CreateType()
+    $hash = [Security.Cryptography.SHA256]::Create()
+    try { $digest = [BitConverter]::ToString($hash.ComputeHash([Text.Encoding]::UTF8.GetBytes($request.origin))).Replace('-', '').ToLowerInvariant() }
+    finally { $hash.Dispose() }
+    $target = 'com.77hub.zhike.developer-cli/v1/' + $digest
+    $value = $null
+    switch ($request.operation) {
+        { $_ -in @('get', 'probe') } {
+            $pointer = [IntPtr]::Zero
+            if (-not $native::Read($target, 1, 0, [ref]$pointer)) {
+                $errorCode = [Runtime.InteropServices.Marshal]::GetLastWin32Error()
+                if ($errorCode -ne 1168) { throw 'credential read failed' }
+            } else {
+                $blob = [IntPtr]::Zero
+                $blobSize = 0
+                try {
+                    # 按固定结构的实际偏移读取，避免 PowerShell 在 PtrToStructure 的 Type/Object 重载间歧义。
+                    $kind = [Runtime.InteropServices.Marshal]::ReadInt32($pointer, [Runtime.InteropServices.Marshal]::OffsetOf($credentialType, 'Type').ToInt32())
+                    $persist = [Runtime.InteropServices.Marshal]::ReadInt32($pointer, [Runtime.InteropServices.Marshal]::OffsetOf($credentialType, 'Persist').ToInt32())
+                    $blobSize = [Runtime.InteropServices.Marshal]::ReadInt32($pointer, [Runtime.InteropServices.Marshal]::OffsetOf($credentialType, 'CredentialBlobSize').ToInt32())
+                    $blob = [Runtime.InteropServices.Marshal]::ReadIntPtr($pointer, [Runtime.InteropServices.Marshal]::OffsetOf($credentialType, 'CredentialBlob').ToInt32())
+                    # Generic / 本用户本机跨登录持久化；BlobSize 单位为字节，内容为 UTF-16LE。
+                    if ($kind -ne 1 -or $persist -ne 2 -or $blobSize -lt 1 -or $blobSize -gt 1024 -or
+                        $blobSize % 2 -ne 0 -or $blob -eq [IntPtr]::Zero) { throw 'invalid credential metadata' }
+                    if ($request.operation -eq 'get') {
+                        $value = [Runtime.InteropServices.Marshal]::PtrToStringUni($blob, [int]($blobSize / 2))
+                    }
+                } finally {
+                    if ($blob -ne [IntPtr]::Zero -and $blobSize -gt 0 -and $blobSize -le 1024) {
+                        for ($i = 0; $i -lt $blobSize; $i++) { [Runtime.InteropServices.Marshal]::WriteByte($blob, $i, 0) }
+                    }
+                    $native::Free($pointer)
+                }
+            }
+        }
+        'set' {
+            $bytes = [Text.Encoding]::Unicode.GetBytes($request.credential)
+            $blob = [IntPtr]::Zero
+            $record = [IntPtr]::Zero
+            $namePointer = [IntPtr]::Zero
+            $userPointer = [IntPtr]::Zero
+            try {
+                $blob = [Runtime.InteropServices.Marshal]::AllocHGlobal($bytes.Length)
+                [Runtime.InteropServices.Marshal]::Copy($bytes, 0, $blob, $bytes.Length)
+                $namePointer = [Runtime.InteropServices.Marshal]::StringToHGlobalUni($target)
+                $userPointer = [Runtime.InteropServices.Marshal]::StringToHGlobalUni($request.origin)
+                $credential = [Activator]::CreateInstance($credentialType)
+                $credential.Type = 1
+                $credential.TargetName = $namePointer
+                $credential.UserName = $userPointer
+                $credential.CredentialBlob = $blob
+                $credential.CredentialBlobSize = $bytes.Length
+                $credential.Persist = 2
+                $record = [Runtime.InteropServices.Marshal]::AllocHGlobal([Runtime.InteropServices.Marshal]::SizeOf($credential))
+                [Runtime.InteropServices.Marshal]::StructureToPtr($credential, $record, $false)
+                if (-not $native::Write($record, 0)) { throw 'credential write failed' }
+            } finally {
+                [Array]::Clear($bytes, 0, $bytes.Length)
+                if ($blob -ne [IntPtr]::Zero) {
+                    [Runtime.InteropServices.Marshal]::Copy($bytes, 0, $blob, $bytes.Length)
+                    [Runtime.InteropServices.Marshal]::FreeHGlobal($blob)
+                }
+                foreach ($allocated in @($record, $namePointer, $userPointer)) {
+                    if ($allocated -ne [IntPtr]::Zero) { [Runtime.InteropServices.Marshal]::FreeHGlobal($allocated) }
+                }
+            }
+        }
+        'delete' {
+            if (-not $native::Delete($target, 1, 0)) {
+                $errorCode = [Runtime.InteropServices.Marshal]::GetLastWin32Error()
+                if ($errorCode -ne 1168) { throw 'credential delete failed' }
+            }
+        }
+    }
+    [Console]::Out.Write((@{ version = 1; ok = $true; value = $value } | ConvertTo-Json -Compress))
+} catch {
+    [Console]::Out.Write('{"version":1,"ok":false,"code":"zhike_secure_store_failed"}')
+}

package/src/cli/windows-credential-store.js

@@ -0,0 +1,112 @@
+import { execFile, spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { win32 } from "node:path";
+
+import { normalizeOrigin } from "../config.js";
+import { ZhikeCliError } from "../errors.js";
+
+let script;
+const failure = () => new ZhikeCliError("zhike_secure_store_failed", "无法访问 Windows 安全凭据存储，请检查系统凭据库和 PowerShell 策略后重试");
+const unavailable = () => new ZhikeCliError("zhike_secure_store_unavailable", "Windows 安全凭据适配不可用，需要系统 Windows PowerShell 5.1 及允许的原生 API 调用");
+
+export class WindowsCredentialStore {
+  constructor({ runner = runWindowsCredentialBridge } = {}) {
+    this.runner = runner;
+  }
+
+  async get(environmentId) { return this.request("get", normalizeOrigin(environmentId, "Developer API")); }
+
+  async set(environmentId, refreshCredential) {
+    if (typeof refreshCredential !== "string" || !refreshCredential.length || refreshCredential.length > 512) throw failure();
+    await this.request("set", normalizeOrigin(environmentId, "Developer API"), refreshCredential);
+  }
+
+  async delete(environmentId) { await this.request("delete", normalizeOrigin(environmentId, "Developer API")); }
+
+  async probe() { await this.request("probe", `https://probe-${randomUUID()}.invalid`); }
+
+  async request(operation, origin, credential) {
+    try {
+      const result = await this.runner({ version: 1, operation, origin, ...(credential === undefined ? {} : { credential }) });
+      if (!result || result.version !== 1 || typeof result.ok !== "boolean" ||
+          Object.keys(result).some((key) => !["version", "ok", "value", "code"].includes(key))) throw failure();
+      if (!result.ok) {
+        if (result.code === "zhike_secure_store_unavailable") throw unavailable();
+        throw failure();
+      }
+      if (operation === "get") {
+        if (result.value !== null && (typeof result.value !== "string" || !result.value.length || result.value.length > 512)) throw failure();
+        return result.value;
+      }
+      if (result.value !== null) throw failure();
+    } catch (error) {
+      if (error instanceof ZhikeCliError) throw error;
+      throw failure();
+    }
+  }
+}
+
+/** 固定程序/脚本与秘密数据分离；子进程输出不得原文进入 CLI 错误。 */
+export async function runWindowsCredentialBridge(request, {
+  spawnImpl = spawn, systemRoot = process.env.SystemRoot, environment = process.env,
+  timeoutMs = 10_000, maxOutputBytes = 65_536,
+} = {}) {
+  if (!systemRoot || !win32.isAbsolute(systemRoot)) throw unavailable();
+  let source;
+  try { source = await (script ??= readFile(new URL("./windows-credential-bridge.ps1", import.meta.url), "utf8")); } catch { throw unavailable(); }
+  const executable = win32.join(systemRoot, "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+  const encoded = Buffer.from(source, "utf16le").toString("base64");
+  const env = Object.fromEntries(Object.entries(environment).filter(([key]) =>
+    ["systemroot", "windir", "temp", "tmp", "path", "comspec", "systemdrive",
+      "userprofile", "appdata", "localappdata", "homedrive", "homepath", "username", "userdomain",
+      "programfiles", "programfiles(x86)", "programw6432", "programdata", "allusersprofile",
+      "pathext", "computername", "processor_architecture", "processor_identifier", "processor_level",
+      "processor_revision", "number_of_processors", "os"].includes(key.toLowerCase())));
+  // ConvertFrom-Json / Add-Type 的模块解析只使用系统目录，不加载项目或用户自定义模块。
+  // 固定子进程不需要持久化命令发现缓存；避免依赖 runner/用户的缓存路径或锁。
+  env.PSModuleAnalysisCachePath = "NUL";
+  env.PSModulePath = win32.join(systemRoot, "System32", "WindowsPowerShell", "v1.0", "Modules");
+  return new Promise((resolve, reject) => {
+    let child;
+    let output = "";
+    let outputSize = 0;
+    let settled = false;
+    let timer;
+    const finish = (error, result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      output = "";
+      if (error) reject(error); else resolve(result);
+    };
+    const terminate = () => {
+      if (Number.isInteger(child?.pid) && process.platform === "win32") {
+        execFile(win32.join(systemRoot, "System32", "taskkill.exe"), ["/PID", String(child.pid), "/T", "/F"],
+          { windowsHide: true, timeout: 3_000 }, () => child.kill());
+      } else child?.kill();
+    };
+    try {
+      child = spawnImpl(executable, ["-NoLogo", "-NoProfile", "-NonInteractive", "-EncodedCommand", encoded],
+        { shell: false, windowsHide: true, stdio: ["pipe", "pipe", "pipe"], env });
+    } catch { finish(unavailable()); return; }
+    timer = setTimeout(() => { terminate(); finish(failure()); }, timeoutMs);
+    const collect = (bytes, keep) => {
+      if (settled) return;
+      outputSize += Buffer.byteLength(bytes);
+      if (outputSize > maxOutputBytes) { terminate(); finish(failure()); return; }
+      if (keep) output += bytes;
+    };
+    child.stdout.setEncoding("utf8");
+    child.stdout.on("data", (bytes) => collect(bytes, true));
+    child.stderr.on("data", (bytes) => collect(bytes, false));
+    child.on("error", () => finish(unavailable()));
+    child.stdin.on("error", () => { terminate(); finish(failure()); });
+    child.on("close", (code) => {
+      if (settled) return;
+      if (code !== 0) { finish(failure()); return; }
+      try { finish(null, JSON.parse(output)); } catch { finish(failure()); }
+    });
+    child.stdin.end(JSON.stringify(request), "utf8");
+  });
+}

package/src/server/agents/index.d.ts

@@ -0,0 +1,22 @@
+/** 静态信息进入不可变 Manifest；工具集合由同目录 .tools.ts 唯一决定。 */
+export interface AppAgentDefinition {
+  key: string;
+  name: string;
+  /** App 提供的系统提示词，最多 16KiB UTF-8，不交付 Client Worker。 */
+  systemPrompt: string;
+}
+export type ToolSchema = Readonly<Record<string, unknown>>;
+export interface AppToolDefinition<Input, Output> {
+  key: string;
+  name: string;
+  description: string;
+  /** 有界 JSON Schema；平台在模型调用和结果交付时再次严格验证。 */
+  inputSchema: ToolSchema;
+  outputSchema: ToolSchema;
+  /** 默认 none；output 只允许成功且通过校验的结果进入实时 callback。 */
+  clientResult?: 'none' | 'output';
+  /** 仅在所属安装的服务端执行环境运行，凭据沿用现有 Server SDK。 */
+  execute(input: Input): Output | Promise<Output>;
+}
+export function defineAgent(definition: AppAgentDefinition): Readonly<AppAgentDefinition>;
+export function defineTool<Input = Record<string, unknown>, Output = unknown>(definition: AppToolDefinition<Input, Output>): Readonly<AppToolDefinition<Input, Output>>;

package/src/server/agents/index.js

@@ -0,0 +1,30 @@
+const KEY = /^[a-z][a-z0-9-]{0,63}$/;
+
+function fields(value, required, optional = []) {
+  if (!value || typeof value !== "object" || Array.isArray(value) ||
+      required.some(key => !Object.hasOwn(value, key)) ||
+      Object.keys(value).some(key => ![...required, ...optional].includes(key))) {
+    throw new TypeError("agent_definition_invalid");
+  }
+  if (typeof value.key !== "string" || value.key.trim() !== value.key || !KEY.test(value.key) || typeof value.name !== "string" ||
+      !value.name.trim() || value.name.length > 80) throw new TypeError("agent_definition_invalid");
+}
+
+export function defineAgent(definition) {
+  fields(definition, ["key", "name", "systemPrompt"]);
+  if (typeof definition.systemPrompt !== "string" || !definition.systemPrompt.trim() ||
+      new TextEncoder().encode(definition.systemPrompt).length > 16384) {
+    throw new TypeError("agent_definition_invalid");
+  }
+  return Object.freeze({ ...definition });
+}
+
+export function defineTool(definition) {
+  fields(definition, ["key", "name", "description", "inputSchema", "outputSchema", "execute"], ["clientResult"]);
+  if (typeof definition.execute !== "function" || typeof definition.description !== "string" ||
+      !definition.description.trim() || definition.description.length > 1200 ||
+      ![undefined, "none", "output"].includes(definition.clientResult)) {
+    throw new TypeError("agent_tool_definition_invalid");
+  }
+  return Object.freeze({ ...definition, clientResult: definition.clientResult ?? "none" });
+}

package/src/server/index.d.ts

@@ -1,3 +1,4 @@
+export { defineAgent, defineTool, type AppAgentDefinition, type AppToolDefinition, type ToolSchema } from "./agents/index.js";
 import type { JsonValue } from "../index.js";
 export { defineWorkflowStep, defineWorkflowStepExecute } from "./steps/index.js";
 export type { WorkflowObjectSchema, WorkflowScalarSchema, WorkflowStepDefinition, WorkflowStepOutcome, WorkflowStepResult, WorkflowSchemaValue } from "./steps/index.js";

package/src/server/index.js

@@ -1,3 +1,4 @@
+export { defineAgent, defineTool } from "./agents/index.js";
 const SERVER_FUNCTION_MARKER = Symbol.for("zhike.server-function.v1");
 export { defineWorkflowStep, defineWorkflowStepExecute } from "./steps/index.js";
 export { defineWorkflowTrigger, defineWorkflowTriggerActivate, defineWorkflowTriggerOnEvent, defineWorkflowTriggerDeactivate } from "./triggers/index.js";