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

package/README.md

@@ -0,0 +1,281 @@
+# 智客 App SDK 与 CLI
+
+## 正文批注与待发同步
+
+`TextSelection` 可接收有界 `marks`（id、UTF-16区间、逐字text、1至20的ordinal）与 `onMarkActivate`；Host默认保留编号，通过当前view锚点打开Popover时才高亮对应原文，关闭后清除高亮，点击编号可重新编辑；不向App交付DOM或坐标。通过 `useConversation().state.references ?? []` 派生标记，与Composer待发引用保持同源。
+
+annotation的comment允许空字符串，支持“先加入对话、再编辑评论”。保存更新同id，取消保留已加入引用，删除通过removeReference同步移除。仅引用原文而无评论时需在主输入说明要求；至少一条有评论才支持缺省正文发送。`form.TextArea`新增可选labelHidden，隐藏视觉标题但保留可访问名称。使用这些增量前须同步升级SDK、Runtime与双端Host，不能单独向旧宿主发布App。
+
+## 操作系统与 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` 不能扩展名单。
+
+Node builtin、CommonJS、动态 import、原生模块、未获准包和路径越界仍禁止。项目内 `file:` 包可用，但同名同版本不是来源证明。白名单只控制构建兼容性；不替代运行时沙箱、网络策略、租户隔离及 API 权限，不进行运行时 npm 安装。
+
+## 统一构建
+
+`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` 的实时订阅仍是独立用途，七天断线补读窗口不代表历史查询可超过三天。
+
+## Object Action 与 Bulk Record Action
+
+对象列表上的两类 Action 仍使用 `src/app/extensions/<key>/extension.tsx`：
+
+```tsx
+import { defineFrontendExtension, showToast } from '@77-zhike/app-sdk/client'
+
+export default defineFrontendExtension({
+  key: 'sync-selected-customers',
+  type: 'bulk-record-action',
+  label: '同步选中客户',
+  objects: ['accounts'],
+  async onTrigger({ object, recordIds }) {
+    await syncCustomers({ object, recordIds: [...recordIds] })
+    await showToast({ message: `已提交 ${recordIds.length} 条客户`, tone: 'success' })
+  },
+})
+```
+
+- `object-action` 显示在列表右上角对象操作菜单，只接收 `{ object }`。
+- `bulk-record-action` 只在产品列表允许当前页显式多选时出现，接收 `{ object, recordIds }`；`recordIds` 为点击瞬间按当前页顺序冻结的 1～100 个公开 ID。
+- `objects` 只允许 `accounts`、`contacts`、`opportunities` 和公开的 `custom_*` slug。任务、跟进记录、笔记不是 SDK Record Surface，不能用于 `record-action`、`object-action` 或 `bulk-record-action`。SDK 不暴露查询、权限、revision、内部 definition ID、系统 mutation 或产品 Action slot。
+- Web/H5 使用同一产品目录和执行合同，但分别渲染菜单、Dialog/Sheet 与选择交互。没有可执行 Bulk Action 时不会出现空选择入口。
+- Action 发现不会启动 Worker；点击后才校验当前 Installation 并 Lazy 执行。Action 本期不能调用 `navigate()`。
+- Destination 的可导航对象与 Record 扩展白名单是两个独立合同；某类产品对象可以被打开，不代表 App 可以向它注册 Record Action。
+
+## Record Widget、Record Section 与 Record Tab
+
+记录页面组件继续使用 `src/app/extensions/<key>/extension.tsx`。Widget 由管理员加入卡片区；Record Section 进入统一 Section 目录，当前列表式设置默认将新 placement 加入 Overview；Tab 安装后进入产品 Tab 目录。三者都只接收平台签发的公开记录身份：
+
+```tsx
+import {
+  defineFrontendExtension,
+  type RecordComponentProps,
+} from '@77-zhike/app-sdk/client'
+import { Badge, Widget } from '@77-zhike/app-sdk/ui'
+
+function HealthWidget({ object, recordId }: RecordComponentProps) {
+  return (
+    <Widget.TextWidget onTrigger={() => openHealthDetails({ object, recordId })}>
+      <Widget.Title>客户健康度</Widget.Title>
+      <Widget.Text.Primary>92</Widget.Text.Primary>
+      <Widget.Text.Secondary>{`记录：${recordId}`}</Widget.Text.Secondary>
+      <Widget.Decoration>
+        <Badge tone="success">正常</Badge>
+      </Widget.Decoration>
+    </Widget.TextWidget>
+  )
+}
+
+export default defineFrontendExtension({
+  key: 'customer-health',
+  type: 'record-widget',
+  label: '客户健康度',
+  objects: ['accounts'],
+  Widget: HealthWidget,
+})
+```
+
+Record Section 使用同一声明形态，把 `type` 改为 `record-section` 并以 `Section` 提供组件；它按 final plan 在 placement 指定的 Section 区域渲染。`recordDetails.supportingSections` 与 `overview.sections` 只是位置，共用同一 capability 和 View。Record Tab 则使用 `record-tab` 和 `Tab`。`objects` 省略时适用于客户、联系人、商机和全部自定义对象；具体 `custom_*` 只匹配同名公开对象。任务、跟进记录和笔记不是 SDK Record Surface。
+
+```tsx
+import {
+  defineFrontendExtension,
+  type RecordComponentProps,
+} from '@77-zhike/app-sdk/client'
+import { Button, Stack, TextBlock } from '@77-zhike/app-sdk/ui'
+
+function BusinessSummary({ object, recordId }: RecordComponentProps) {
+  return (
+    <Stack gap="medium">
+      <TextBlock>当前记录：{`${object} / ${recordId}`}</TextBlock>
+      <Button onClick={() => refreshSummary({ object, recordId })}>刷新摘要</Button>
+    </Stack>
+  )
+}
+
+export default defineFrontendExtension({
+  key: 'business-summary',
+  type: 'record-section',
+  label: '经营摘要',
+  objects: ['accounts', 'opportunities'],
+  Section: BusinessSummary,
+})
+```
+
+`record-widget` 表示 Overview 顶部卡片。唯一根节点必须是 `Widget.TextWidget`，首次数据尚未就绪时可以返回 `Widget.Loading`。`Widget.Title`、`Widget.Text.Primary`、`Widget.Text.Secondary` 与可选的 `Widget.Decoration` 只描述卡片语义；其中 Decoration 只接受 `Badge` 或 `StatusBadge`。Web/H5 Host 使用各自 `components/ui` 实现外框、间距、字体、可信归属与 loading/error，App 不要在根节点再次套 `Card` 或自行模拟卡片样式。产品原生重点字段也复用同一套 Overview Widget 原子组件，因此 App 与产品卡片在同一端保持一致。
+
+`Widget.TextWidget.onTrigger` 用于整卡点击，Host 会提供 pending 单飞与失败反馈；发现和渲染本身不会触发该回调。未提供 `Widget.Title` 时，Host 使用 capability label 作为受信回退标题。全宽内容必须使用 `record-section`，不能复用 `record-widget`。
+
+- 产品只保存稳定 capability placement，不保存 App 版本或 Worker 身份；升级、卸载后重装仍可恢复原布局。Widget、Section、Tab 分别进入固定共享贡献点，不为每个组件创建新贡献点。
+- Web/H5 使用同一份布局和 `{ object, recordId }`，但分别渲染适合当前宿主的 UI。H5 不支持的 Forms/`LookupCell` 只让当前 Widget/Section/Tab 进入 `unsupported`，不会拖垮详情或同 App 的其他组件。
+- Widget/Section/Tab 标签和设置候选的发现不启动 Worker；可见 Widget/Section 或当前选中 Tab 才挂载 App View。Section 挂载后可自行初始化查询，Host 不提供数据预取合同。Server Function 仍必须由用户在已挂载组件中显式触发。
+- App 不能声明 capability ID、布局位置、排序 tier、产品 route、`viewName`、Workspace/Installation 身份或 Native availability metadata。
+- 当前 Record Page 三类组件不开放命令式 `navigate()`；详情 Tab 的 URL 与刷新恢复由产品 Host 统一管理。
+
+## Workspace Page
+
+Page 源码放在 `src/app/pages/<slug>/page.tsx`。一级目录名就是稳定 slug；Page 只声明名称、排序、布局和纯 React 组件，不接收 Router、Workspace、鉴权 token 或宿主 props。
+
+```tsx
+import {
+  definePage,
+  Destinations,
+} from '@77-zhike/app-sdk/client'
+import {
+  Card,
+  ZhikeLink,
+  Stack,
+  TextBlock,
+} from '@77-zhike/app-sdk/ui'
+
+function QueuePage() {
+  return (
+    <Stack gap="large">
+      <Card title="任务队列">
+        <TextBlock>当前没有待处理任务。</TextBlock>
+      </Card>
+      <ZhikeLink destination={Destinations.appPage('overview')}>
+        返回总览
+      </ZhikeLink>
+    </Stack>
+  )
+}
+
+export default definePage({
+  name: '任务队列',
+  order: 20,
+  variant: 'centered',
+  Page: QueuePage,
+})
+```
+
+同一 App 内，有 `order` 的 Page 排在前面并按 `order + slug` 稳定排序；未声明 `order` 的 Page 排在后面并按 slug 排序。`name` trim 后长度为 1～80 个 Unicode code points。`variant: 'full' | 'centered'` 只表达布局语义，Desktop 与 H5 分别决定具体页面壳。
+
+Page UI 必须使用 `@77-zhike/app-sdk/ui` 和 `@77-zhike/app-sdk/forms` 的公开组件，不能依赖 DOM、React Router 或自行复制产品控件。当前 Desktop 支持 Components 与 Forms；H5 支持 TextBlock、布局、反馈、Button、Tabs、Table、Card、Grid、EmptyState、Link、ZhikeLink 等 portable Components，并支持 Forms，暂不支持 `LookupCell`。含有不支持能力的 Page 在 H5 会整体显示“不支持”，不会静默丢节点或部分提交。
+
+导航只提交结构化 Destination：
+
+- `Destinations.appPage(slug)` 打开当前 App 的另一个 Page。
+- `Destinations.record({ object, recordId })` 支持 `accounts`、`contacts`、`opportunities`、`tasks`、`activities` 和当前 Workspace 可见的 `custom_*` 公开 API slug。
+- `ZhikeLink` 保留普通链接、复制地址和新标签行为；普通点击仍会在跳转前重验当前 Page 身份。外部 HTTPS 使用 `Link`。
+- `navigate()` 当前只允许从已挂载的 Page 调用，三类 Action 都不具备该能力。
+
+目录展示不会启动 Worker。首次打开 Page 时，宿主才会下载并校验 Manifest/Bundle、启动 Installation Worker；因此“Apps 菜单可见”不等于代码已经验证可运行。页面数据读写仍应通过受控 Server Function 完成。
+
+## 当前 Workspace 用户
+
+Client 与用户触发的 Server Function 都可以同步读取当前 Workspace 成员：
+
+```tsx
+import { getCurrentUser } from '@77-zhike/app-sdk/client'
+
+const currentUser = getCurrentUser()
+// currentUser.workspaceMemberId 是 Workspace 成员 ID，不是平台全局 User ID。
+```
+
+```ts
+import { getCurrentUser } from '@77-zhike/app-sdk/server'
+
+export default async function readForCurrentMember() {
+  const currentUser = getCurrentUser()
+  return { workspaceMemberId: currentUser.workspaceMemberId }
+}
+```
+
+返回值只包含 `workspaceMemberId`、`displayName`、`primaryEmailAddress`、`avatarUrl`，且为只读快照。它不包含 Token、角色、权限集合或平台全局 User ID；App 仍须通过 Server Function 与公开 API 完成数据授权，不能用该快照自行推断权限。Lifecycle、Webhook 等无人触发入口没有当前用户，调用时抛出 `current_user_unavailable`；不得回退到管理员、安装者或 Connection 所有者。
+
+## 基础UI组件扩展
+
+新增Avatar、DescriptionList、Divider、Json、外部Link、StatusBadge、TextBlock与Typography，补齐Banner动作、Badge颜色、Card呈现、Grid容器模式、EmptyState操作编排和Table.HeaderCell。复合写法使用同一节点。
+
+Desktop与H5注册的组件合同中，`ZhikeLink` 仍仅限Page，`Link` 是受治理的外部HTTPS链接；H5支持Forms，仍不开放Settings入口。新包要求`remote-react.v3`，发布前必须先部署对应Host及Bundle准入合同。
+
+新增组件的日常验证：修改Core `components/contracts.mjs`后执行`npm run generate:components --workspace @77-zhike/app-sdk`和`npm run check:components --workspace @77-zhike/app-sdk`，同步双端manifest与adapter。App项目运行`zhike dev --workspace <workspace-id>`，从对应Workspace的Apps入口打开Page；Desktop Settings仅验证其允许的子集。
+
+仓库内还提供无业务数据库的独立组件预览，命令和证据边界见`integration-app-runtime/verification/fixtures/ui-parity/README.md`。该预览不替代真实安装、权限与Server Function验证。
+
+## 表单组件
+
+Desktop 与 H5 均支持 17 个可视 Forms 节点，以及只读 `WithState`。文本、多行、数字、日期、时间、选择、分组等输入复用各端基础 UI；Host 继续持有 RHF 状态，组件选择不会自动保存。数字空值为 null，日期为 YYYY-MM-DD，日期时间提交为带时区 ISO；旧 string/boolean/enum 语义保留。
+
+`RecordCombobox` 默认只需在 schema 声明单个 `objectSlug`（或 `Forms.record(objectSlug)`），由 Host 使用当前安装的 Records Read 权限读取公开记录，保存值是 `{ objectSlug, recordId }`。空词沿用 Query 分页，非空词使用最多 25 条、无分页的 Record Search，已选值独立 Get。自定义数据源才提供 `RecordOptionsProvider.search/getOption` 并可自行分页；业务有效性及显式保存仍由消费方负责。`WithState` 仅订阅指定的 values/errors/submitting，不提供状态修改或程序化提交。
+
+可复制的非 CRM 示例与真实 tarball/Worker/SF/Settings/PostgreSQL 验证入口见 `integration-app-runtime/verification/fixtures/forms-parity/README.md`。当前尚未发布，所有新增 Forms 能力并入 remote-react.v3，ABI=2 不变；沿用 v1/v2 合同校验。SDK 与双端 Host 应整体交付，不引入新的版本分叉。
+
+## Dialog
+
+通过 `showDialog({ title, Dialog, size })` 打开临时界面；内容组件接收 `hideDialog()`。Desktop 复用 Dialog，H5 复用 Sheet，继续组合已有 UI/Form。可选 `size` 为 `default | wide | content`：默认保持原规格，宽版最大 1120px，自适应按内容固有宽度展开并受视口约束；H5 均保持全屏 Sheet。当前不提供 DialogList、嵌套 Dialog 或固定 Footer，按钮直接放在正文中。
+
+从 Page/Settings 事件或 Record Action 调用。普通关闭完成 Promise；身份失效或打开失败拒绝。Action 正常返回后已受理 Dialog 可继续使用；保存必须由 App 显式调用 Server Function。Dialog 内不提供 Page 导航身份。详见开发者文档 `app-sdk/dialogs/show-dialog`。
+
+## 当前成员的只读分析与 Chart
+
+App Page 可从 `@77-zhike/app-sdk/client` 调用 `queryAnalysis({ operation, input })`。`operation` 仅允许 `list`、`get`、`execute`；输入沿用公开 MCP 分析目录、详情和执行合同。先分页读取获权目录，再从定义详情的 `capability` 与 `queryHints` 构造执行请求。禁止传入成员、租户、URL、任意 SQL 或内联定义。
+
+此能力由 Host 注入当前成员和已安装 Page 的可信身份，不经 App 机器身份执行。Settings、Action 与 Dialog 不支持。读取前后均复验安装资格；页面关闭或切换工作空间时取消请求，迟到结果不交付。不可用历史、缺数据和权限错误须作为明确状态呈现。
+
+```tsx
+import { queryAnalysis } from '@77-zhike/app-sdk/client';
+import { Chart } from '@77-zhike/app-sdk/ui';
+
+const directory = await queryAnalysis({ operation: 'list', input: { limit: 20, offset: 0 } });
+// 执行输入依据详情发布的维度和 Widget 能力构造。
+const trend = <Chart label="经营趋势" variant="area" format="currency" height={280}
+  data={{ labels: ['一月', '二月'], series: [{ id: 'amount', label: '金额', values: [120000, null] }] }} />;
+```
+
+Chart 仅接受纯数据 `labels` 与 `series`，不接受脚本、HTML 或任意样式。最多 200 个标签、4 条系列，32 KiB；系列 ID 唯一，各系列长度与标签相等。`null` 保留缺失断点；标签可重复，按位置区分。`variant` 支持 `line | bar | area`，`format` 支持 `number | currency | percent`，`height` 为 200、280 或 360。比例以 0..1 传入。`onSelect({ seriesId, index })` 支持提示和数据表选择；Web/H5 共用组件，图例与可展开数据表由 Host 提供。
+
+### Dashboard 与高级分析呈现
+
+`DashboardSurface` 提供固定 `graphite` 业务色板，深浅主题跟随主应用；`DashboardLayout` 提供 `mainAside`、`equal`、`three` 响应式布局，配合 `DashboardPanel` 和 `MetricReadout`。这些组件不接受任意 CSS、DOM 或主题变量。
+
+`AnalysisView` 接收同一资产的 `queryAnalysis(get)` 定义和 `queryAnalysis(execute)` 结果。Host 复用已有分析渲染器，支持同期群、漏斗、基础/增强/堆叠/表格阶梯与历史构成瀑布；状态分析可切换度量，并查看全部度量原始结果。高级呈现须符合定义开放的能力，历史覆盖不足须由调用方明确显示。
+
+定义与结果分别限制为 256 KiB / 20,000 项 / 24 层；状态分析最多 400 行、24 个唯一度量，结果单元格最多 2,400 个。拒绝跨资产结果、脚本、非有限值和无界数据。`onSelect` 仅返回受控数据选择，不开放内部记录路由或网络请求。使用这些组件需要同步升级本仓库的 SDK 和双端 Host。
+
+### 精确数字的表格录入
+
+`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 展示本地建议确认区。
+
+### Slider（源码增量，需匹配 Host）
+
+`@77-zhike/app-sdk/ui` 提供单值/双端 `Slider`，支持整段拖动、step、minRange、键盘与最终commit。App只消费数值；Host合并在途变化并保留手势草稿。需先发布匹配的SDK和桌面/手机Host，再发布消费App。完整属性与行为见 Developer Docs `app-sdk/components/slider`。

package/package.json

@@ -1,7 +1,12 @@
 {
   "name": "@77-zhike/app-sdk",
-  "version": "0.2.0-d7b1.2",
-  "description": "\u667a\u5ba2 Integration App \u4e00\u671f SDK \u4e0e\u672c\u5730 Toolchain",
+  "version": "0.2.0-d7b1.20",
+  "description": "智客 Integration App 一期 SDK 与本地 Toolchain",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tonyjiang88215/TruthLoop.git",
+    "directory": "developer-tools/packages/app-sdk"
+  },
   "type": "module",
   "engines": {
     "node": ">=20"
@@ -31,6 +36,14 @@
     "./forms": {
       "types": "./src/forms/index.d.ts",
       "default": "./src/forms/index.js"
+    },
+    "./jsx-runtime": {
+      "types": "./src/jsx-runtime.d.ts",
+      "default": "./src/jsx-runtime.js"
+    },
+    "./jsx-dev-runtime": {
+      "types": "./src/jsx-dev-runtime.d.ts",
+      "default": "./src/jsx-dev-runtime.js"
     }
   },
   "files": [
@@ -53,5 +66,6 @@
     "react": {
       "optional": true
     }
-  }
+  },
+  "gitHead": "c7f1b793276cbde656dbd058731fcb8b51b95745"
 }

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/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/development-logs.js

@@ -32,9 +32,12 @@ export function formatAppLog(app, entry, {
   const levelLabel = { log: "INFO ", warn: "WARN ", error: "ERROR" }[level];
   const levelColor = { log: colors.cyan, warn: colors.yellow, error: colors.red }[level];
   const timestamp = formatTimestamp(entry.received_at);
+  const version = entry.app_version_id ? safe(entry.app_version_id).replace(/\n/g, " ").slice(0, 64) : "";
+  const request = entry.invocation_id ? safe(entry.invocation_id).replace(/\n/g, " ").slice(0, 64) : "";
+  const identity = version || request ? `  [${[version, request].filter(Boolean).join(" · ")}]` : "";
   const prefix = color
-    ? `${colors.dim}${timestamp}${colors.reset}  ${levelColor}${levelLabel}${colors.reset}  ${colors.bold}${label}${colors.reset}`
-    : `${timestamp}  ${levelLabel}  ${label}`;
+    ? `${colors.dim}${timestamp}${colors.reset}  ${levelColor}${levelLabel}${colors.reset}  ${colors.bold}${label}${colors.reset}${identity}`
+    : `${timestamp}  ${levelLabel}  ${label}${identity}`;
   return safe(entry.message).split("\n").map((line) => `${prefix}  ${line}`).join("\n");
 }