QuickOps SDK

概述

QuickOps SDK 让插件以只读、受策略约束的方式访问当前由 CoreApp host runtime 承载、由官方 touch-quickops 插件承接 CoreBox 入口的 QuickOps 能力，例如能力摘要、运行中会话、本地系统信息、网络/文件诊断和最近 Flow 审计摘要。QuickOps 的目标形态是继续把可迁移业务逻辑抽离到官方 touch-quickops 插件与 host capability 边界。

导入

插件先导脚本可以直接使用全局 quickOps / plugin.quickOps。插件渲染上下文可以使用 useQuickOps()，已有 channel 时也可以显式创建 SDK。

import { createQuickOpsSDK, useQuickOps } from '@talex-touch/utils/plugin/sdk'

// index.js / Prelude 全局上下文
const capabilitiesFromPrelude = await quickOps.capabilities()

// 插件渲染上下文
const quickOps = useQuickOps()
const capabilities = await quickOps.capabilities()

// 已持有插件 channel 时
const quickOpsFromChannel = createQuickOpsSDK(channel)
const sessions = await quickOpsFromChannel.sessions()

在普通 renderer / app 侧可使用 transport domain SDK：

import { createQuickOpsSdk } from '@talex-touch/utils/transport/sdk/domains/quick-ops'
import { useTuffTransport } from '@talex-touch/utils/transport'

const quickOps = createQuickOpsSdk(useTuffTransport())
const sessions = await quickOps.sessions()

API 速览

Developer Preview

QuickOps Developer CoreBox 表面由官方 plugins/touch-quickops 插件承接。插件识别 json、url encode、base64 decode、jwt decode、regex test、markdown table、csv to markdown、markdown to csv、timestamp、date、timezone、uuid、short id、qr code、case snake 等命令后，调用 quickOps.developerPreview({ query })。

developerPreview() 返回 ready 时包含 PreviewCardPayload，官方插件会渲染 core-preview-card。普通 preview 暴露 preview-copy-primary；QR preview 额外暴露插件自有 execute action，并通过 saveDeveloperPreview() 保存。

const result = await quickOps.developerPreview({
  query: {
    text: 'json {"ok":true}',
    inputs: []
  }
})

if (result.state === 'ready') {
  renderCorePreviewCard(result.payload)
}

saveDeveloperPreview() 只支持 PreviewSDK QR SVG payload，输出目录固定为 CoreApp app.getPath('temp')/tuff-quickops，成功后会把文件路径写入剪贴板。它不是通用文件写入 API。

const saved = await quickOps.saveDeveloperPreview({
  format: 'png',
  payload: result.payload
})

if (saved.state === 'saved') {
  console.info(saved.path)
}

CoreApp 通用 PreviewProvider 不再注册 QuickOps Developer ability，也不会为 Developer 命令读取剪贴板或暴露 QR 保存 action。不要从插件 fallback 到私有 PreviewProvider、raw IPC 或自行读取剪贴板来绕过 allowDeveloperTools 策略。

Files Input 路由

官方 plugins/touch-quickops manifest 已声明 acceptedInputTypes: ["text", "files"]。当 CoreBox 查询带 Files input 时，插件会解析 query.inputs[].type === "files" 的 JSON 字符串数组，并把首个有效文件路径作为 fileHash()、fileBase64() 或 pathFormat() 的默认 path；显式命令里的路径仍优先于 Files input。

当前 CoreApp 文件搜索 provider 只负责索引、打开文件、打开所在目录和路径复制类通用动作。路径复制动作使用通用 action id：file-copy-path、file-copy-shell-path、file-copy-url，以及按平台路径可用性追加的 file-copy-windows-path / file-copy-wsl-path；不要再新增 quick-ops-* 文件搜索 action id。QuickOps Hash/Base64 的结果渲染和命令路由必须放在官方插件里，不要把新的 QuickOps execute action 加回文件搜索结果或 provider onExecute() 分支。

选择扩展路径

先判断你是在“组合 QuickOps”还是“修改官方 QuickOps 能力”。普通插件默认只组合，不改 quickops.* 命名空间。

插件不要注册新的 quickops.* target，也不要调用 QuickOps 私有 IPC。插件自有能力应使用自己的 feature id / target id，并把 QuickOps 结果当作上下文输入。

读取能力矩阵

const info = await quickOps.capabilities()

for (const entry of info.entries) {
  if (entry.status === 'disabled') {
    console.info(`${entry.id} disabled: ${entry.reason}`)
  }
}

常见 disabled reason：

最近审计摘要

auditRecent() 返回 QuickOps Flow delivery 的本地最近摘要。它只保存可观测决策，不保存 payload 内容。

const audit = await quickOps.auditRecent({ limit: 10 })

for (const entry of audit.entries) {
  console.log(entry.targetId, entry.decision, entry.reason, entry.payloadKeys)
}

返回字段：

该审计摘要会在模块销毁后清空，不作为企业集中审计或合规留存。

Flow 扩展模式

QuickOps 内建 Flow target 已由 CoreApp 注册。插件如果要把自己的功能与 QuickOps 串起来，应通过 Flow SDK 分发到已有 target，而不是直接调用私有 IPC。

import { createFlowSDK } from '@talex-touch/utils/plugin/sdk'

const flow = createFlowSDK(channel, 'my-plugin-id')

const result = await flow.dispatch({
  type: 'json',
  data: {},
  context: {
    sourcePluginId: 'my-plugin-id'
  }
}, {
  preferredTarget: 'quickops.system-info',
  skipSelector: true,
  requireAck: true
})

if (result.state === 'blocked') {
  console.warn(result.reason)
}

带 requireConfirm=true 的 QuickOps target 必须由 app UI 发放一次性 confirmationToken 后才能交付，并在 dispatch options 中携带，例如 quickops.keep-awake、quickops.copy-to-clipboard、quickops.open-folder、quickops.temp-text-file。

Flow target 目录

公开 QuickOps target 使用 quickops.<target> 命名。目标分为只读、低风险状态控制和需要确认的动作：

插件可以把只读 target 的结果作为上下文继续处理。需要确认的 target 不应该在后台静默触发，也不应该缓存旧的 confirmationToken。

第三方扩展模式

普通插件不应该修改内置 QuickOps runtime。推荐扩展方式如下：

插件自定义 Ops 可以先读取能力矩阵，再在自己的 UI、CoreBox 结果或命令处理函数里调用 Flow：

import { createFlowSDK, useQuickOps } from '@talex-touch/utils/plugin/sdk'

const quickOps = useQuickOps()
const flow = createFlowSDK(channel, 'my-plugin-id')

async function runNetworkSummary() {
  const capabilities = await quickOps.capabilities()
  const hasNetwork = capabilities.entries.some((entry) =>
    entry.id.startsWith('quickops.network.') && entry.status !== 'disabled'
  )

  if (!hasNetwork) {
    return { state: 'blocked', reason: 'quickops-network-disabled' }
  }

  return flow.dispatch({ type: 'json', data: {} }, {
    preferredTarget: 'quickops.network-status',
    skipSelector: true,
    requireAck: true
  })
}

插件自有 Ops Checklist

1. 在 Manifest 中声明真实需要的权限和 reason，不借用 QuickOps 权限。
2. 入口使用插件自己的命名空间，例如插件 feature id 或自有 Flow target。
3. 执行前读取 capabilities()，把本地策略关闭、平台不支持和 degraded reason 反映到 UI。
4. 需要写剪贴板、写文件、打开目录、外联或改变本机状态时，复用 Permission / Flow 确认模型。
5. 返回 blocked / degraded 时给出稳定 reason，不做 fake success。
6. 日志和审计只记录 target、decision、reason、payload key 或长度，不记录敏感 payload 值。

修改官方 QuickOps

只有维护仓库时才应该修改官方 QuickOps。新增或调整通用能力时，优先迁入 plugins/touch-quickops；仍依赖 Electron / OS 的部分必须通过 CoreApp host capability 暴露。

当前官方插件已承接 CoreBox root-result 入口、更多只读面板、Developer preview、设置摘要入口和低风险状态控制触发：capability、sessions、auditRecent、system info、tuff diagnostics、disk space、directory usage、network status、local ip、port status、DNS query、file hash、file Base64、recent download、common directory、path format、format text、Developer preview、battery status、system proxy、quickops settings，以及 stop-all-sessions、timer / pomodoro / clean-screen / awake / stopwatch 的 stop/pause/resume/lap/reset 控制。只读面板通过 globalThis.quickOps 过渡 facade 取数和渲染；Developer preview 通过 developerPreview() 调 CoreApp host facade 渲染 core-preview-card，QR 保存通过 saveDeveloperPreview() 写入 Tuff QuickOps 临时目录；设置摘要通过 capability / diagnostics 只读读取当前策略和默认值，不写入 CoreApp host policy；低风险状态控制通过注入的 Flow SDK dispatch 到已有 QuickOps Flow target；文件 Hash/Base64/path format 支持 text 与 files 输入路由。插件也承接 QuickOps Flow/AI source-level adapter contract：命令路由输出脱敏 flowAdapterTrace，确认型动作只提示 App UI confirmationToken，高风险 kill port 类请求 fail-closed 且没有 dispatch payload。插件不执行高风险 action、不 fallback 到私有 IPC；确认型动作必须由 App UI 发放 confirmationToken，插件只能展示需要确认的提示。CoreApp 当前保留 QuickOpsRuntimeHost / quickOpsRuntime host boundary、platform capability、Flow confirmation、policy/evidence gate、AppSetting schema / settings read path 与 typed bridge；CoreApp 不再保留 QuickOps natural-language resolver 实现，也不再在通用 PreviewProvider、文件搜索 provider 或 Tools 设置页中承载 QuickOps 产品表面。后续新增可迁移入口时，优先扩展该插件的命令路由和渲染；可写设置必须设计官方插件白名单 host capability，不得用私有 IPC 直写配置，也不得重新引入 CoreApp QuickOps CoreBox provider、Tools 设置控件、通用 PreviewProvider Developer surface 或文件搜索专用 QuickOps execute 分支。

请同步以下落点：

内置能力变更 checklist：

1. 先确认能力属于只读、低风险状态控制、确认型动作还是高风险动作。
2. 只读能力可以进入 SDK facade；会改变状态、写文件、写剪贴板、打开本地目录或外联的能力必须优先走 Flow target 和确认模型。
3. 高风险能力默认不能进入插件 SDK；如需落地，必须先补策略、权限、确认 UI、审计和真实 evidence。
4. 如果涉及设置表面，优先在 plugins/touch-quickops 增加只读摘要；需要写入时先设计官方插件白名单 host capability、权限理由和 evidence，不得直接写 AppSetting.quickOps 或调用私有 IPC。
5. 更新 focused tests：插件命令路由、runtime helper、Flow delivery、策略 fail-closed、脱敏 ACK / audit、typed transport surface。
6. 运行 quickops:surface:audit --strict，确保没有 raw channel、SDK bypass 或 runtime facade 漂移。
7. 运行 quickops:flow-ai:audit --strict。它应证明 Flow target 目录、确认集合、策略阻断、脱敏 ACK / audit、插件侧 Flow dispatch adapter / trace 和 runtime dispatch bridge 合同；如果新增能力没有补齐这些源级合同，应 fail-closed。
8. 文档中只声明已有 evidence 支撑的能力；packaged、三平台、视觉、真实 AI UI 编排或确认 UI 证据缺失时必须明确写成未完成，不能把 Flow metadata、resolver/bridge focused test 或 mock artifact 当作完整 evidence。

扩展建议

1. 插件可以基于 capabilities() 决定是否展示某个入口。
2. 插件可以用 sessions() 展示运行状态，但不要缓存 session id 作为长期状态。
3. 插件可以用 auditRecent() 做本地最近执行状态面板，但不要把它上传为企业审计。
4. 自定义执行能力应优先声明 Manifest permissions，并使用 Permission / Flow 确认模型。
5. 涉及文件、网络、剪贴板或系统状态的扩展必须返回明确 degraded / blocked reason，不做 fake success。

相关文档

• TuffTransport
• Flow SDK
• Permission SDK
• Tuff QuickOps 用户指南