Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

404 KB
Raw Blame
import { parseGhostSecretCheck, type GhostSecretCheckDecl } from '@cindy/plugin-protocol';
import { parseGhostRoutineEvents, type GhostRoutineEvents } from '@cindy/plugin-protocol';
import { parseMailReader } from '@cindy/maker-shared/mail-message';
import { parsePluginAuthorizationRequest, type PluginAuthorizationRequest, type PluginAuthorizationResult } from '@cindy/device-link';
import {
  type GhostRecommendation,
  GHOST_LOCALES,
  GHOST_MANIFEST_SUMMARY_MAX_CHARS,
  GHOST_OAUTH_SCOPES_MAX,
  isValidCindyVersion,
  type GhostLocale,
  type GhostManifestLocales,
} from '@cindy/plugin-protocol';
import { PLUGIN_STORAGE_PART_RE } from './pluginStoragePartPattern.js';
import { PLUGIN_TASK_PERMISSION_MODES } from './pluginTasks.js';
import { DEFAULT_LOCALE, SUPPORTED_LOCALES, type SupportedLocale } from './locale';

/**
 * 意识(Ghost,.cindy 文件)的清单数据模型与校验 —— main / renderer 共用。
 *
 * 跨模块安全与布局不变量见 docs/dev-rules/architecture-invariants.md / docs/dev-rules/plugin-security-and-authoring.md:
 * - `.cindy` 是一个 zip 压缩包,根部放一份 `ghost.json` 清单(身份卡);
 * - 意识只有一种形态(2026-07-12 Lizi 定案):`kind: 'chip'`,带代码并运行在
 *   独立沙箱进程。schemaVersion 3 由直接字段声明能力;schemaVersion 2 的
 *   `slots` 只在解析边界兼容,进入运行时前会规范化掉。
 *   早期无代码的声明型(declaration, v1)已
 *   整体移除——Lizi 确认无存量包,不留兼容层(对齐 07-08"无曾用名兼容"
 *   先例);原规划的"经验"档(提示词层)同日取消,场景由 Skill 体系覆盖;
 * - 意识面板在布局树中的 panelKind 统一为 `ghost:<id>`,与布局引擎的
 *   与规则 27 的「未安装意识面板隐藏、重装原位复活」语义对接。
 *
 * 校验风格对齐 shared/layoutTree.ts:纯函数、返回 ok/reason,不抛异常;
 * main 端 GhostManager 与未来的 renderer 消费方共用,规则不漂移。
 */

/** 清单文件名(zip 根部)。 */
export const GHOST_MANIFEST_FILE = 'ghost.json';
/** Maximum manifest bytes accepted by both Forge and package ingestion. */
export const GHOST_MANIFEST_MAX_BYTES = 256 * 1024;

/**
 * 安装器读取包内 ghost.json 的硬上限。源码目录的发现/预读取可以使用更宽的
 * 安全预算,但最终写进 .cindy 的清单必须落在这个上限内。
 */
export const GHOST_INSTALL_MANIFEST_MAX_BYTES = 256 * 1024;

/** ghost.json 的 description / whenToUse 字符上限,正本在 plugin-protocol。 */
export { GHOST_MANIFEST_SUMMARY_MAX_CHARS };

/** 意识文件扩展名。 */
export const CINDY_FILE_EXT = '.cindy';

/** 意识面板在布局树中的 panelKind 前缀。 */
export const GHOST_PANEL_KIND_PREFIX = 'ghost:';

/** 意识沙箱文件供片协议;特权注册见 bootstrap。 */
export const GHOST_SCHEME = 'cindy-ghost';

/**
 * 意识沙箱的 session 分区前缀。无 `persist:` 前缀 = 纯内存分区,熄灯即蒸发。
 * Renderer 只用它声明待附加的意识 id;Main 验明当前 owner 后会覆盖成真正的
 * owner-scoped partition,不能把这里的 claim 当成最终 Electron session 边界。
 */
export const GHOST_PARTITION_PREFIX = 'cindy-ghost-';

/** Renderer 的意识 WebView attach claim;Main 放行前会覆盖成 owner 分区。 */
export function ghostPartition(id: string): string {
  return `${GHOST_PARTITION_PREFIX}${id}`;
}


/** 从 Renderer claim 解析实例 storage part;不是合法 claim 返回 null。 */
export function parseGhostPartition(partition: unknown): string | null {
  if (typeof partition !== 'string' || !partition.startsWith(GHOST_PARTITION_PREFIX)) return null;
  const id = partition.slice(GHOST_PARTITION_PREFIX.length);
  return PLUGIN_STORAGE_PART_RE.test(id) ? id : null;
}

/**
 * 意识 id 规则:小写字母/数字开头,后续允许小写字母/数字/连字符,总长 1–32。
 * 收紧到这个集合是因为 id 直接用作安装目录名(userData/brain/<id>),
 * 必须在 macOS / Windows 双平台都是安全的文件夹名,且天然杜绝路径穿越。
 */
const GHOST_ID_RE = /^[a-z0-9][a-z0-9-]{0,31}$/;

/**
 * schemaVersion 2 能力名清单,仅用于兼容旧包
 * (docs/dev-rules/plugin-security-and-authoring.md)。
 * 'cindy' = 请 Cindy 本体代办(借主机自带 AI 能力干活;2026-07-11 Lizi 定案
 * 由 'model' 更名——本质是 Cindy 在干活,与选模型无关;旧名在校验层作
 * 静默别名兼容,已装老包不消失)。
 * 'network' = 意识自带服务:域名白名单
 * 内的 HTTP 经主机代发(沙箱本身保持零直连),凭证锁主机保险库按声明注入。
 * 'notify' = 系统提示(2026-07-14):意识经管子请主机弹一条轻提示(toast),
 * 意识只供纯文本,整块 UI 主机画并带意识身份头(与订阅槽红条同一信任边界);
 * 无阻塞、无按钮、无回执——要用户点选/确认走 'confirm' 槽。
 * 'confirm' = 确认弹窗(2026-07-31):意识经管子请主机弹**主机同款**的二选一确认框
 * (renderer 的 ConfirmDialogProvider),拿回用户的真实点击。与 notify 的区别是它
 * **阻塞、有按钮、有回执**,所以骚扰面也大得多,护栏对齐 pick 槽:同插件最小间隔
 * GHOST_CONFIRM_MIN_INTERVAL_MS、全局同时只允许一个确认框在场(BUSY,不排队)、
 * 超时/无窗口/载荷非法一律 fail closed 当「没同意」。壳、标题与身份头(图标+名字)
 * 由主机画,意识只供被净化的正文与按钮字——伪装不了主机文案、冒充不了别的意识,
 * 也点不了自己的按钮。桌面独占:本机对话框在 device-link 白名单里属永不放行类别。
 * 'fs' = 写文件(2026-07-14):意识经管子请主机代写文件(创建/修改)。三档
 * 目的地:自己的私有数据目录(userData/ghost-fs/<id>,免确认)、当前会话
 * workdir(跟随会话 permission 模式:免批模式直写、逐条模式弹确认卡、
 * plan/只读拒)、save 票据目录(主 agent 过户,复用 saveDeposit 预算)。
 * 字节永远由主机落盘,沙箱本身仍无 fs——本槽是"申请主机代写"的资格,
 * 不是文件系统访问权。
 * 'main-view' = 应用级插件主视图:宿主从已批准 manifest 解析包内
 * HTML 入口,并提供 Cindy 一级侧边栏与路由。它与会话内 panel
 * 独立授权,本身不附赠网络、文件或凭证能力。
 * 'task-view' = 跟对话的任务页:页签存在各任务的右侧栏里,随任务切换;与
 * main-view 同一 WebView 沙箱,本身不附赠网络、文件或凭证能力。
 * 'library' = 持久作品库(2026-08-20):用户作品级存储(画布/素材/数据库),
 * 与 'fs' 私有储物柜(配额封顶、卸载回收)语义不同:不受 ghost-fs 配额约束,
 * 卸载插件**不删**(标 orphaned,删除必须走设置页独立确认)。字节与 SQL
 * 一律由主机在 owner×plugin 隔离的 Library 根内代执行,插件只持不透明
 * handle 与相对路径;SQLite 只能提交参数化语句,经宿主语句门(首词白名单)
 * 过滤后在专属 worker 里跑——插件拿不到数据库对象,也拿不到任意路径。
 * 'session-context' = 会话上下文(2026-07-23):agent 派活(tool-call)时,主机把
 * 当次会话的可信 {session_id, workdir, workdir_is_local, workdir_is_read_only}
 * 注入 args.session_context。
 * 只注入宿主认证过的事实,插件与 agent 自报的同名字段一律被剥除;远程工作区
 * (workdir 不在本机)时 workdir_is_local=false,插件不得把它当本机路径用。
 * 'pick' = 目录选择(2026-07-23):插件经管子申请主机弹**系统级**选文件夹窗口,
 * 用户亲手选中即授权(与浏览器文件选择同一哲学:决定权在用户的点击上)。
 * 返回票据(dir_deposit,同 ghost_call dir 通道);声明了 node 槽的插件额外
 * 拿到绝对路径(Node 侧本就有用户级本机权限,路径保密无意义,可信才是重点)。
 * 'preview' = 面板预览(2026-07-23):插件经管子申请在右侧栏内置浏览器里打开
 * 一个网址标签页。网址范围装入时在 preview.hosts 白名单里定死(同 network
 * 域名白名单语法),运行期主机逐次校验,范围外一律拒——防钓鱼是结构性的。
 * 'skill' = 捆绑 Agent Skills(2026-07-25):插件随包携带 SKILL.md 技能目录,
 * 装入且启用后由主机投影到 Cindy 的账号隔离目录,通过各 Harness 的私有入口
 * 提供给 Claude Code、Codex、Pi,不写入用户共用技能目录。信任面与其它槽完全不同量级:技能
 * 指令由主 Agent 以**用户全部权限**执行、对所有项目与会话生效、不受插件沙箱
 * 约束,也不随"某工作目录停用本插件"而隐藏——仅全局停用/卸载才撤链。因此
 * manifest 全声明式(items 的 name/description 必须与 SKILL.md frontmatter 逐字
 * 一致,打包与装入双侧强制),插件详情逐条列出并置于能力清单最上部。
 * 'workspace' = 工作区会话(2026-07-25):插件请主机在指定本机项目目录下确保
 * 存在一个会话入口并显示在侧边栏——目录下已有 active 会话即复用,没有才创建
 * 空 draft 会话(不拉起 agent 进程)。目录授权两条路:系统选文件夹窗口亲选
 * 即授权(pick 模式,路径不回沙箱),或 tool-call 语境下带在途 callId + 绝对
 * 路径(目录在该会话 workdir 内自动放行,workdir 外弹确认卡)。远程工作区
 * v1 一律拒(fail closed)。
 * 'ios-simulator' is retired; retained only to round-trip legacy approval receipts.
 *
 * 以下名称只用于 schemaVersion 2 的兼容解析。schemaVersion 3 已移除 slots,
 * 运行时统一使用 GhostManifest 上的直接字段;未知 v2 slot 只用于兼容诊断,
 * 不会被猜测为某个能力,也不会阻止安装。
 */
const LEGACY_GHOST_SLOTS = [
  'subscribe',
  'tool',
  'card',
  'panel',
  'main-view',
  'task-view',
  'cindy',
  'agent',
  'node',
  'network',
  'notify',
  'badge',
  'confirm',
  'fs',
  'library',
  'device-sync',
  'session-context',
  'pick',
  'preview',
  'skill',
  'workspace',
  'ios-simulator',
] as const;
type LegacyGhostSlot = string;

/** v2 slot 只在兼容解析入口出现;这里只限制可安全显示和传输的名称形状。 */
const GHOST_SLOT_NAME_RE = /^[a-z][a-z0-9._:-]{0,127}$/;

/**
 * Card 槽能力详单。card 槽默认仅允许渲染静态/交互卡片(含按钮动作);
 * externalLinks: true 额外允许卡片声明 data-ghost-link 外链,点击经宿主
 * 确认框后 openExternal——这是独立加档权限,插件详情中单列。
 */
export interface GhostCardNeeds {
  externalLinks?: boolean;
}

/**
 * Agent 新回合能力详单。
 *
 * 申请 `agent` 槽默认只允许消费宿主在真实用户点击插件卡片时签发的
 * 一次性通行票。`background: true` 额外允许插件在没有当次点击票据时,
 * 对已经由用户建立过关联的会话发起回合;这是更高一档权限,插件详情中单列。
 *
 * `errand: true` = 派活取件(2026-07-31 开闸):允许插件把任务交给 Cindy
 * agent 在**插件专属 errand 会话**里跑一轮,并把最终回复文字取回。与
 * background 同为高风险加档,插件详情中单列。安全边界(全部主机代码强制):
 * - 任务文本只进普通 user 消息,绝不进 system prompt(与 agent-request 同纪律);
 * - errand 会话默认跑在专属对话目录、保留历史缺省 plan 及原 Agent 行为;
 *   用户可在插件设置选择 ask/auto/bypassPermissions,插件请求不能自报授权;
 * - errand 会话在侧边栏可见、可旁观、可随时停,不存在隐身会话(errand 不支持
 *   隐藏;普通任务的后台隐藏只经 `tasks` + `hiddenTasks` 声明,见下);
 * - 每插件同时最多 1 单在途,任务表在内存(重启即丢,查询按"查无此单、
 *   可重新提交"处理)。
 */
export interface GhostAgentNeeds {
  background?: boolean;
  errand?: boolean;
  tasks?: boolean;
  /** 查询项目、任务、伙伴并投递消息;必须同时声明 tasks,需独立批准。 */
  targets?: boolean;
  /**
   * hiddenTasks = 「可创建不显示在任务列表里的后台任务」(2026-10)。
   *
   * 必须与 `tasks: true` 同时声明(清单校验强制)。任务默认仍对用户可见;只有声明
   * 本项后,插件才能经 `cindy.tasks.create({hidden: true})` / `cindy.tasks.setHidden`
   * 把**自己创建的**普通任务放到后台:不进任务列表、搜索、未结束提示、新任务通知与
   * 灵动岛。透明性兜底(全部主机代码强制):用户始终能在插件详情页「后台任务」查看、
   * 打开并「显示到任务列表」;插件卸载时其后台任务自动恢复显示。不授予其它任务的
   * 访问权,也不改变任务权限。未声明时 hidden / setHidden 返回 PERMISSION_DENIED。
   */
  hiddenTasks?: boolean;
  /**
   * schedule = 「可以请你新建自动化任务」(2026-08-04)。
   *
   * 用途:插件在自己面板上给用户一个「提醒我 XXXX」之类的选项,用户点了以后由
   * 插件请主机**打开自动化创建面板并预填**(名称 / 要干什么 / 建议频率)。
   *
   * 它能做什么、不能做什么(权限文案与实现必须一致):
   * - 只能**打开面板**。任务由用户在面板上选模型、亲手点保存才落库 —— 插件
   *   没有任何直接建任务的通道(scheduleSlot 只广播,不碰 storage;有测试钉住)。
   * - 落成的任务是一条**普通 agent 自动化**:执行者是 AI 会话,不是插件。插件在
   *   其中的角色是「被这条任务调用的目标」,靠已有的 tool 槽 + ghost_call 被叫到。
   * - 因此它**会消耗用户的模型额度** —— 插件详情必须说清楚。
   *
   * 它属于 agent 能力。未知扩展字段可保留为数据,不因字段存在就获得能力;
   * Host 只按明确支持的字段语义和运行时守门处理请求。
   */
  schedule?: boolean;
}

/** 插件随包本地 Node 工作进程使用的 stdio 协议。 */
export const GHOST_NODE_PROTOCOLS = ['json-rpc-stdio', 'mcp-stdio'] as const;
export type GhostNodeProtocol = (typeof GHOST_NODE_PROTOCOLS)[number];

/** Node 工作进程生命周期;常驻档会在插件详情中单列高风险能力。 */
export const GHOST_NODE_LIFECYCLES = ['on-demand', 'resident'] as const;
export type GhostNodeLifecycle = (typeof GHOST_NODE_LIFECYCLES)[number];

/** 单插件最多可声明的 Node 凭证绑定数。 */
export const GHOST_NODE_MAX_SECRET_BINDINGS = 4;
/** 单条 Node 凭证最多可绑定的 JSON-RPC 方法数。 */
export const GHOST_NODE_MAX_SECRET_METHODS = 16;
const GHOST_NODE_MCP_RESERVED_METHODS = new Set(['initialize', 'notifications/initialized']);

/** MCP 握手由宿主发起,插件业务请求与凭证绑定均不得占用这些方法。 */
export function isGhostNodeMcpReservedMethod(method: string): boolean {
  return GHOST_NODE_MCP_RESERVED_METHODS.has(method);
}

/**
 * 主机保险库 → 随包 Node Worker 的按请求凭证绑定。
 *
 * 值由 settingsHtml 经 `/secrets` 一次性写入 safeStorage;浏览器沙箱
 * main.js 不能直接从保险库读取明文。宿主仅在 method 与 entry 同时命中
 * 本声明时,把值放进发往 Worker 的保留字段 `cindy.secrets[key]`;
 * Worker 获得明文后仍可能主动回传或泄露。未声明 entry 时只允许主入口。
 */
export interface GhostNodeSecretBinding {
  /** 引用本插件 network.secrets 中的 OAuth key;仅注入短期 access token。 */
  oauthSecret?: string;
  /** 凭证键(插件内唯一):小写字母开头,允许小写/数字/下划线,1–32。 */
  key: string;
  /** 给用户看的名称(插件详情与设置状态使用)。 */
  label: string;
  /** 允许注入的 JSON-RPC 方法白名单(1–16 条)。 */
  methods: string[];
  /** 可选目标入口;缺省只绑定 node.entry 主入口。 */
  entry?: string;
  /** 可选输入提示。 */
  hint?: string;
  /** 可选凭证申请页(仅 https;设置页外链须逐字命中)。 */
  url?: string;
}

/**
 * 随插件安装的本地 Node 工作进程声明。
 *
 * Host 只按已支持的包内入口和固定协议启动进程;未知的 command / args / shell /
 * env 等扩展仅保留为数据,不传入进程启动参数。Node 进程拥有当前系统用户级本机权限,主机
 * 只保证它不能绕过 main.js 调 Cindy API,并不能把它变成系统级沙箱。
 */
export interface GhostNodeNeeds {
  entry: string;
  protocol: GhostNodeProtocol;
  lifecycle?: GhostNodeLifecycle;
  idleTimeoutSeconds?: number;
  /**
   * 额外工作进程入口(2026-07-23,能力 5 窄版):仍只能是包内申报过的 JS 文件,
   * node-request 带 entry 字段指名调用;每个入口一个独立进程,协议/生命周期/
   * 空闲策略与主入口共用同一份声明。不是任意命令执行——包外文件、未申报
   * 入口一律拒。
   */
  entries?: string[];
  /**
   * 宿主代启子进程开关(2026-07-23,缺口 1):worker 可经引导层窄接口
   * (spawnEntry)请求宿主再启动一个**已申报入口**(entry / entries 之内)的
   * 原样 stdio 子进程,并把子进程 stdio 字节中继回 worker。给 Maker Runtime
   * 这类"自己 spawn process.execPath"的库改道用——正式包关 RunAsNode,
   * 那条路生出来的不是 Node。默认关;开了会在插件详情单列一行。
   * 权限本质不变:仍只能跑包内申报过的 JS,node 槽本就是用户级执行权。
   */
  childSpawn?: boolean;
  /**
   * 由主机 safeStorage 持久化、按声明的方法临时注入 Worker 的凭证。
   * 这是 Node 高风险能力的一部分,插件详情会逐条披露。
   */
  secretBindings?: GhostNodeSecretBinding[];
}

/** node 额外入口条数上限(1 主 + 4 额外 = 每插件至多 5 个工作进程)。 */
export const GHOST_NODE_MAX_EXTRA_ENTRIES = 4;

/** 宿主代启子进程:每插件同时在世的子进程数上限(不含 worker 本体)。 */
export const GHOST_NODE_MAX_CHILDREN_PER_GHOST = 4;
/** 宿主代启子进程:启动参数条数上限。 */
export const GHOST_NODE_CHILD_MAX_ARGS = 16;
/** 宿主代启子进程:单条启动参数长度上限(字符)。 */
export const GHOST_NODE_CHILD_ARG_MAX_CHARS = 2048;
/** 宿主代启子进程:stdio 中继单帧 base64 字符数上限(≈ 768KB 原始字节)。 */
export const GHOST_NODE_CHILD_CHUNK_MAX_B64_CHARS = 1024 * 1024;
/** spawn-child / childId 的 id 形状(worker 侧自铸计数器 + 主机铸 UUID 都在内)。 */
export const GHOST_NODE_CHILD_ID_RE = /^[A-Za-z0-9-]{1,64}$/;

/**
 * 子进程原样模式的 argv 旗标(utilityProcess fork args[1];其后为透传参数)。
 * 放 shared 是因为 broker(主进程)与引导层(worker 进程)都要认它,而引导层
 * 模块有 import 即执行的副作用,不能被 broker 直接 import。
 */
export const GHOST_NODE_CHILD_MODE_FLAG = '__cindy-node-child__';

/**
 * ── 宿主代启子进程的引导层控制协议(worker bootstrap ↔ 主机 broker)──
 *
 * 这条通道是引导层(nodeRuntimeWorkerProcess)私藏的 parentPort,插件代码
 * 摸不到,只能经 spawnEntry 窄接口发起;它**不是** JSON-RPC stdio 通道,
 * "worker 反向 JSON-RPC 请求宿主能力恒拒 -32601"的铁律不受影响。
 * stdio 字节一律 base64 中继(chunk 可能把多字节字符切两半,文本转发会
 * 出现乱码;base64 逐字节保真)。
 */

/** worker → 主机:代启/喂 stdin/收 stdin/杀进程。 */
export type GhostNodeChildToHostMessage =
  | { type: 'plugin-authorize'; reqId: string; rpcId: string; request: PluginAuthorizationRequest }
  | { type: 'device-authorize'; reqId: string; rpcId: string; url: string }
  | { type: 'spawn-child'; reqId: string; entry: string; args?: string[]; rpcId?: string }
  | { type: 'child-stdin'; childId: string; b64: string }
  | { type: 'child-stdin-end'; childId: string }
  | { type: 'child-kill'; childId: string };

/** 主机 → worker:代启结果/子进程输出/退出。 */
export type GhostNodeChildToWorkerMessage =
  | { type: 'plugin-authorize-result'; reqId: string; ok: boolean; result?: PluginAuthorizationResult }
  | { type: 'device-authorize-result'; reqId: string; ok: boolean }
  | { type: 'spawn-child-result'; reqId: string; ok: true; childId: string; pid?: number }
  | { type: 'spawn-child-result'; reqId: string; ok: false; message: string }
  | { type: 'child-stdout'; childId: string; b64: string }
  | { type: 'child-stderr'; childId: string; b64: string }
  | { type: 'child-exit'; childId: string; code: number | null };

function isChildId(v: unknown): v is string {
  return typeof v === 'string' && GHOST_NODE_CHILD_ID_RE.test(v);
}

/** worker → 主机控制帧的形状校验(主机侧守门用;不合形一律静默丢)。 */
export function parseGhostNodeChildToHostMessage(raw: unknown): GhostNodeChildToHostMessage | null {
  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
  const m = raw as Record<string, unknown>;
  if (m.type === 'plugin-authorize') {
    if (Object.keys(m).sort().join(',') !== 'reqId,request,rpcId,type'
      || !isChildId(m.reqId) || typeof m.rpcId !== 'string' || !/^\d{1,16}$/.test(m.rpcId)) return null;
    try { return { type: m.type, reqId: m.reqId, rpcId: m.rpcId, request: parsePluginAuthorizationRequest(m.request) }; }
    catch { return null; }
  }
  if (m.type === 'device-authorize') {
    if (
      Object.keys(m).sort().join(',') !== 'reqId,rpcId,type,url' ||
      !isChildId(m.reqId) ||
      typeof m.rpcId !== 'string' ||
      !/^\d{1,16}$/.test(m.rpcId) ||
      typeof m.url !== 'string' ||
      m.url.length > 8192
    )
      return null;
    return { type: 'device-authorize', reqId: m.reqId, rpcId: m.rpcId, url: m.url };
  }
  if (m.type === 'spawn-child') {
    if (!isChildId(m.reqId) || typeof m.entry !== 'string') return null;
    if (m.rpcId !== undefined && (typeof m.rpcId !== 'string' || !/^\d{1,16}$/.test(m.rpcId))) return null;
    if (m.args !== undefined) {
      if (!Array.isArray(m.args) || m.args.length > GHOST_NODE_CHILD_MAX_ARGS) return null;
      for (const arg of m.args) {
        if (typeof arg !== 'string' || arg.length > GHOST_NODE_CHILD_ARG_MAX_CHARS) return null;
      }
    }
    return {
      type: 'spawn-child',
      reqId: m.reqId,
      entry: m.entry,
      ...(typeof m.rpcId === 'string' ? { rpcId: m.rpcId } : {}),
      ...(m.args !== undefined ? { args: m.args as string[] } : {}),
    };
  }
  if (m.type === 'child-stdin') {
    if (!isChildId(m.childId)) return null;
    if (typeof m.b64 !== 'string' || m.b64.length > GHOST_NODE_CHILD_CHUNK_MAX_B64_CHARS) {
      return null;
    }
    return { type: 'child-stdin', childId: m.childId, b64: m.b64 };
  }
  if (m.type === 'child-stdin-end' || m.type === 'child-kill') {
    if (!isChildId(m.childId)) return null;
    return { type: m.type, childId: m.childId };
  }
  return null;
}

/**
 * 电子脑启动模式(2026-07-12):
 * - 'on-demand'(缺省):被需要才拉起(agent 派活 / 面板 /wake / 重载);
 * - 'resident':唤醒即启动——enable 时拉起,应用启动时对"已唤醒"者拉起。
 * 两种模式下沉睡 / 抽离 / 更新换代一律先熄灯,规则不变;resident 会在装入
 * 确认框多一行如实告知(常驻 = 用户要背一个后台进程,必须知情)。
 */
export const GHOST_LAUNCH_MODES = ['on-demand', 'resident'] as const;
export type GhostLaunchMode = (typeof GHOST_LAUNCH_MODES)[number];

/**
 * 面板显示形态:left / right / top / bottom = 右侧栏页签系统里的停靠组(插件启用后自动
 * 成为对应边页签组里一个不跟对话的全局页签,用户可再拖到任何一边、弹成独立窗口或关闭;
 * 缺省 left,与历史停靠面板「停在聊天区左侧」一致);tab = 插件页内独占面板。
 * right 曾退役并入 left(2026-07-25),页签组落地后重新作为真实的一边。
 */
export const GHOST_PANEL_POSITIONS = ['left', 'right', 'top', 'bottom', 'tab'] as const;
export type GhostPanelPosition = (typeof GHOST_PANEL_POSITIONS)[number];

/** 面板声明(五个卡槽中的「面板」槽,一段意识至多一块)。 */
export interface GhostPanelDecl {
  /** 面板标题(右侧栏页签 / 插件页标题);缺省用意识 name。 */
  title?: string;
  /** 显示形态:left(缺省)/ right / top / bottom = 聊天区对应边的页签组(用户可再
   *  拖动改位,主机记住用户的放置);'tab' = 插件页内独占面板(2026-08-02 面板收束:
   *  只从插件页打开,离开插件页即关闭)。 */
  position?: GhostPanelPosition;
  /** 面板界面入口(安装目录内相对路径,意识自绘)。 */
  html: string;
  /** 面板最小宽度(px),布局引擎拖缝时的下限。仅停靠形态有效,'tab' 时禁用。 */
  minWidth?: number;
  /** 装入布局时的初始宽度占比(与 layoutTree 的 fraction 同语义)。仅停靠形态有效,'tab' 时禁用。 */
  defaultFraction?: number;
  /**
   * 标准头系统按钮开关(2026-07-25):缺省全开,声明 false 逐个关闭。
   * 当前一批:maximize =「撑满内容区」、detach =「在独立窗口中打开」、
   * minimize =「最小化面板」(恢复入口由用户偏好决定为浮动气泡或左侧栏)。
   * 标准头本体(标题条)恒由主机绘制、
   * 不可关——可配置的只是系统按钮;'tab' 形态没有标准头,声明本字段拒装。
   * 未知键保留为声明数据;当前宿主只读取已实现的按钮。
   */
  systemButtons?: { maximize?: boolean; detach?: boolean; minimize?: boolean };
}

/** 应用级插件主视图可用的 Cindy 系统线性图标。枚举值与图标名保持一致。 */
export const GHOST_MAIN_VIEW_ICONS = [
  'puzzle',
  'globe',
  'code',
  'folder',
  'database',
  'chart-column',
  'image',
  'message-circle',
  'calendar-days',
] as const;
export type GhostMainViewIcon = (typeof GHOST_MAIN_VIEW_ICONS)[number];

/** 应用级插件主视图;与会话内 panel 分开声明和批准。 */
/** 左侧栏入口点击后主视图在哪里打开(插件给的默认偏好;用户放置过后以用户的为准)。 */
export const GHOST_MAIN_VIEW_OPEN_MODES = ['page', 'sidebar', 'window'] as const;
export type GhostMainViewOpenMode = (typeof GHOST_MAIN_VIEW_OPEN_MODES)[number];
/** 主视图以页签形态打开时默认停在聊天区的哪一边。 */
export const GHOST_TAB_SIDES = ['left', 'right', 'top', 'bottom'] as const;
export type GhostTabSide = (typeof GHOST_TAB_SIDES)[number];

export interface GhostMainViewDecl {
  /** 侧边栏与页面标题;缺省回退插件 name。 */
  title?: string;
  /** 侧边栏使用的 Cindy 系统线性图标;缺省为 puzzle。 */
  icon?: GhostMainViewIcon;
  /** 主视图界面入口(安装目录内安全相对路径)。 */
  html: string;
  /**
   * 左侧栏入口点击后的默认打开方式:page(缺省)= 撑满内容区的页面;sidebar = 作为
   * 不跟对话的页签放进聊天区某一边的页签组(`side` 指定,缺省 right);window = 弹成
   * 独立窗口。只是默认值:用户拖过 / 弹过之后主机记住用户的放置,直到用户在插件
   * 详情页「恢复默认位置」。
   */
  open?: GhostMainViewOpenMode;
  /** open:'sidebar' 时的默认边;其它 open 值下声明本字段拒装。 */
  side?: GhostTabSide;
  /**
   * 允许同一个视图同时开在多处(整页 + 侧栏页签 / 独立窗口各一份,各自独立的 webview)。
   * 缺省单实例:主机保证同一插件视图同一时刻只活在一个地方——进整页就收掉页签,页签
   * 出现时整页让位——避免两份界面各自保存整份数据互相覆盖。只有自己处理好多视图
   * 一致性(共享写入方 / 版本号 / BroadcastChannel 同步)的插件才声明 true。
   */
  multiple?: true;
}

/**
 * 跟对话的任务页(taskView):插件在每个任务右侧栏里的页面。页签存在该任务里,
 * 切换任务时随任务切换;页签头由 Cindy 绘制,没有地址栏。页面经 URL 查询参数
 * `session` 得知自己所在的任务,逻辑页经 `cindy.taskView({sessionId})` 打开或聚焦它。
 */
export interface GhostTaskViewDecl {
  /** 页签标题;缺省回退插件 name。 */
  title?: string;
  /** 任务页入口(安装目录内安全相对路径)。 */
  html: string;
}

/**
 * 芯片型意识注册给 agent 的工具声明(卡槽②)。
 * 声明式而非运行时动态注册(规则 9:确定性;且会话中途增删工具会破坏
 * prompt 缓存前缀,规则 10)——主机在会话建立时按"已装且唤醒"的意识
 * 快照注入工具集。
 */
export interface GhostToolDecl {
  /** 工具名:小写字母开头,允许小写/数字/下划线/连字符,≤64。 */
  name: string;
  /** 给模型看的工具说明。 */
  description: string;
  /** JSON Schema(object)形态的参数声明;可省略(无参工具)。 */
  parameters?: Record<string, unknown>;
}

/** cindy 槽·图像类可申请的动作(主机代办菜单的"图像"类目)。 */
export const GHOST_MODEL_IMAGE_ACTIONS = ['generate', 'edit'] as const;
export type GhostModelImageAction = (typeof GHOST_MODEL_IMAGE_ACTIONS)[number];

/** cindy 槽·视频类可申请的动作(generate=文生视频,edit=参考图生视频)。 */
export const GHOST_MODEL_VIDEO_ACTIONS = ['generate', 'edit'] as const;
export type GhostModelVideoAction = (typeof GHOST_MODEL_VIDEO_ACTIONS)[number];

/**
 * cindy 槽·媒体类可申请的动作(2026-07-29 开闸,makecindy/cindy#784)。
 *
 * `deposit` = 寄存:把意识**手里已有**的媒体字节(用户在面板里粘贴/拖入的图、
 * 面板存量素材)存入媒体总仓、记到本意识名下,换回指纹——从此这些媒体与
 * 「意识自己生成的图」同权,可以直接当 edit_image / edit_video 的源图。
 *
 * 为什么单独成一档能力(而非跟着 image.edit 白送):它是本槽唯一**不经模型、
 * 不花钱**的入仓通道。声明了 network 槽的意识本就能从白名单域拉字节入仓
 * (as:'media'),寄存把同样的"写你的媒体库"能力给了没有 network 槽的意识,
 * 因此必须在插件详情里作为独立能力露出,并由运行期 Host 严格守门。
 *
 * 同一能力键同时授权 `release_media`(撤回自己寄存的那条引用):配额有上限,
 * 没有撤回口的配额等于"用满即永久坏掉",不成立。撤回只删本意识的寄存引用,
 * 不删字节(字节归回收器按引用归零处理),因此不是额外的信任面。
 */
export const GHOST_CINDY_MEDIA_ACTIONS = ['deposit'] as const;
export type GhostCindyMediaAction = (typeof GHOST_CINDY_MEDIA_ACTIONS)[number];

/**
 * cindy 槽·文本类可申请的动作(2026-07-31 开闸)。
 *
 * `oneshot` = 快问快答:意识递一段文字,主机经**轻量任务模型链**(与会话
 * 起标题、任务一句话总结同一条通道,见 utility-model/oneShotCandidates.ts)
 * 直答一次并把文字原样递回。不拉起 agent、无工具、无用户权限、不进任何
 * 会话——它与 agent 派活(agent 槽 errand)是两条信任面完全不同的路:
 * 这条只花模型额度,拿不到任何宿主能力。
 */
export const GHOST_CINDY_TEXT_ACTIONS = ['oneshot'] as const;
export type GhostCindyTextAction = (typeof GHOST_CINDY_TEXT_ACTIONS)[number];

/**
 * cindy 槽·向量类可申请的动作(2026-08-04 开闸)。
 *
 * `text` = 文本转向量:意识递一批文字,主机经统一 embedding 通道
 * (embedding-host 的 embedSync,与聊天历史语义检索同一条付费链路)返回等长的
 * 向量数组。**只生成、不存储**——主机不给意识碰向量表(那是宿主自己语义检索的
 * 家当,维度与表名都钉死),向量原样递回沙箱,存哪儿、怎么建索引由意识自己在
 * 自己的 kv / 文件里解决。
 *
 * 为什么与 text.oneshot 分成两档而不是塞进同一个能力键:两者花的是不同的钱
 * (轻量任务模型链 vs embedding 模型),合成一档就没法只授权其中一样。信任面同 oneshot —— 只花额度,拿不到任何宿主
 * 能力,不进会话。
 */
export const GHOST_CINDY_EMBED_ACTIONS = ['text'] as const;
export type GhostCindyEmbedAction = (typeof GHOST_CINDY_EMBED_ACTIONS)[number];

/**
 * cindy 槽·搜索类可申请的动作。
 *
 * `web` = Cindy 托管的公网搜索:意识只递查询词与结果数,主机固定走当前
 * model-access 下发的 XD endpoint + XD user key,通过固定模型别名调用
 * Anthropic Messages 原生网页搜索,不把网关 key、模型名或工具定义暴露给
 * 意识。它与 network 槽里的 BYO Brave/Tavily 是两条独立凭证与计费路径。
 */
export const GHOST_CINDY_SEARCH_ACTIONS = ['web'] as const;
export type GhostCindySearchAction = (typeof GHOST_CINDY_SEARCH_ACTIONS)[number];

/**
 * cindy 槽能力详单(卡槽⑤配套,原名模型槽,2026-07-11 设计定案):声明"这个意识被允许
 * 向主机点哪几类代办"——类目与动作之外只有**意图级**字段(oneshotModel 偏好,
 * 2026-08-05 起),**不构成任何硬依赖**(选型权在主机:快问快答 = 用户在详情页给
 * 插件选的模型 > 意识声明的偏好模型 > 系统辅助模型链;媒体/向量 = 调用时显式点名 >
 * 档位 > 目录默认;意识只表达意图,永不腐烂)。插件详情与代办资格审共同消费。
 */
export interface GhostCindyNeeds {
  /** 图像类:generate=出图,edit=改图(改图仅限本意识名下媒体)。 */
  image?: GhostModelImageAction[];
  /** 视频类:generate=文生视频,edit=参考图生视频(源图仅限本意识名下媒体,1–2 张首/尾帧)。 */
  video?: GhostModelVideoAction[];
  /** 媒体类:deposit=寄存自己手里的媒体字节入总仓(换指纹,兼授权 release_media)。 */
  media?: GhostCindyMediaAction[];
  /** 文本类:oneshot=快问快答(轻量任务模型链直答一次,无 agent 无工具)。 */
  text?: GhostCindyTextAction[];
  /** 向量类:text=文本转向量(只生成不存储,向量原样递回意识自己保管)。 */
  embed?: GhostCindyEmbedAction[];
  /** 搜索类:web=Cindy 托管的公网搜索(主机固定路由,意识不经手网关凭证)。 */
  search?: GhostCindySearchAction[];
  /**
   * 快问快答偏好模型(目录模型 id,如 "codex/gpt-5.5";须与 text 含 "oneshot"
   * 成对)。主机能从当前供应商目录解析到(且用户未停用)就用它,解析不到按
   * 未声明处理;用户在插件详情给插件选的模型永远优先于本声明。
   * 未实现本字段的兼容宿主保留声明但不使用它;插件仍需处理旧宿主差异。
   */
  oneshotModel?: string;
}

/**
 * 订阅槽 did- 旁听主题(卡槽①,2026-07-12 开闸)。v1 全部是**元数据级**:
 * turn = 轮次开始/结束(agent/模型/耗时/用量,不含消息内容);
 * activity = 轮次内思考/审批/等待用户输入的开始结束边界(只含 id 元数据);
 * session = 会话创建/归档/切换(切换 = 用户把哪个会话切到台前,2026-07-13 增)。
 * 正文级主题(消息内容旁听)刻意不开——隐私最重,等真实场景再议,权限文案
 * 也要另分一档。
 */
export const GHOST_SUBSCRIBE_TOPICS = ['turn', 'session', 'activity'] as const;
export type GhostSubscribeTopic = (typeof GHOST_SUBSCRIBE_TOPICS)[number];

/**
 * 订阅槽 will- 拦截钩子(真 hook:主机停等裁决)。两个点,一进一出:
 * - `will-user-message`(入口):用户消息即将交给 agent 之前(拦下 = turn 压根
 *   不启动);动作 allow/block/rewrite。
 * - `will-assistant-message`(出口):AI 这轮回复完成、最终气泡定案之前,把全文
 *   交给意识做润色/合规改写或自绘结果卡片;动作 allow/rewrite/render(无 block
 *   ——AI 已生成,拦无意义)。**不拦流式输出**(照常打字机),只在 turn 结束
 *   边界的独立异步续跑里裁决,不搅 maker-core 热路径;超时/崩溃 fail-open 用原文。
 * 两个钩子都不拦 tool-call。声明了任一钩子必须 launch:'resident'(要挡路就得常驻
 * 在场,冷启动延迟不可接受),校验强制。
 */
export const GHOST_SUBSCRIBE_HOOKS = ['will-user-message', 'will-assistant-message'] as const;
export type GhostSubscribeHook = (typeof GHOST_SUBSCRIBE_HOOKS)[number];

/**
 * 订阅槽详单(与 slots 含 'subscribe' 成对;有槽无详单允许装入但零事件——
 * 与 cindy 详单同语义)。topics = did- 旁听(fire-and-forget),hooks = will-
 * 拦截(停等裁决);没声明的主题/钩子,网关不挂处理段(接口不存在)。
 */
export interface GhostSubscribeNeeds {
  topics?: GhostSubscribeTopic[];
  hooks?: GhostSubscribeHook[];
}

/* ── network 槽详单(docs/dev-rules/plugin-security-and-authoring.md)──────────────────────────────────
 * 意识自带服务:作者声明域名白名单 + 凭证需求,装入时钉死、确认框逐项展示。
 * 运行期沙箱仍零直连,所有出网经管子 fetch-request 由主机代发;凭证明文
 * 永不进沙箱——主机只在"该凭证声明的注入位置"拼进请求头。 */

/** network 槽:域名白名单条数上限(声明面越小越好,超了说明设计有问题)。 */
export const GHOST_NETWORK_MAX_HOSTS = 8;
/** network 槽:凭证声明条数上限。 */
export const GHOST_NETWORK_MAX_SECRETS = 4;
/** network 槽:多连接(connections)声明条数上限(一段意识通常只对接一种自建服务)。 */
export const GHOST_NETWORK_MAX_CONNECTION_DECLS = 2;
/** network 槽:每条连接声明下用户可添加的连接数上限(同时是 maxConnections 缺省值)。 */
export const GHOST_NETWORK_MAX_CONNECTIONS_PER_DECL = 8;

/**
 * 域名白名单条目格式:小写域名,至少两段(拒绝裸 TLD / 单段内网名),
 * 通配只允许最左一段(`*.example.com`);不收 IP、端口、路径、协议。
 */
const GHOST_NETWORK_LABEL_RE = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/;
export function isValidGhostNetworkHostPattern(p: unknown): p is string {
  if (typeof p !== 'string' || p.length === 0 || p.length > 253) return false;
  const bare = p.startsWith('*.') ? p.slice(2) : p;
  const labels = bare.split('.');
  // 至少两段:`*.com` / `localhost` / 裸 TLD 全部拒绝,命中面必须是具体域。
  if (labels.length < 2) return false;
  // 纯数字四段视作 IP,拒收(白名单只认域名)。
  if (labels.every((l) => /^\d+$/.test(l))) return false;
  return labels.every((l) => GHOST_NETWORK_LABEL_RE.test(l));
}

/**
 * hostname 是否命中白名单条目。精确条目要求逐字相等;通配条目
 * (`*.example.com`)只命中子域(`a.example.com`),不命中裸域本身——
 * 作者两者都要就两条都声明,规则不做隐式扩张。
 */
export function ghostNetworkHostMatches(pattern: string, hostname: string): boolean {
  if (pattern.startsWith('*.'))
    return hostname.endsWith(pattern.slice(1)) && hostname.length > pattern.length - 1;
  return hostname === pattern;
}

function ghostNetworkHostPatternWithinCap(actual: string, reviewed: string): boolean {
  if (!actual.startsWith('*.')) return ghostNetworkHostMatches(reviewed, actual);
  if (!reviewed.startsWith('*.')) return false;
  return ghostNetworkHostMatches(reviewed, `cap-probe.${actual.slice(2)}`);
}

/**
 * 凭证注入声明:该凭证以什么形态、进哪些域名的请求头。绑定在 secret 上
 * (而非独立 auth 模板)是刻意的——结构上保证"key 只流向它声明的域名",
 * 意识更新扩白名单也扩不走存量凭证的流向。
 */
export interface GhostSecretInjectDecl {
  /**
   * 注入范围(manifest.network.hosts 的子集,逐字匹配声明条目);
   * 缺省 = 详单里的全部域名。
   */
  hosts?: string[];
  /** 注入的请求头名(如 Authorization / X-Subscription-Token)。 */
  header: string;
  /** 头值模板:恰含一个 `{value}` 占位,其余为静态文本(如 `Bearer {value}`)。 */
  format: string;
}

/** 凭证交换(key 换令牌)请求体类型白名单。 */
export const GHOST_SECRET_EXCHANGE_CONTENT_TYPES = [
  'application/json',
  'application/x-www-form-urlencoded',
] as const;
export type GhostSecretExchangeContentType = (typeof GHOST_SECRET_EXCHANGE_CONTENT_TYPES)[number];

/** 凭证交换:请求体模板长度上限。 */
export const GHOST_SECRET_EXCHANGE_BODY_MAX_CHARS = 2048;
/** 凭证交换:令牌缓存时长(秒)缺省 / 下限 / 上限(上限 30 天)。 */
export const GHOST_SECRET_EXCHANGE_TTL_DEFAULT_S = 3600;
export const GHOST_SECRET_EXCHANGE_TTL_MIN_S = 60;
export const GHOST_SECRET_EXCHANGE_TTL_MAX_S = 30 * 24 * 3600;
/** 凭证交换:tokenPath 点分路径形状(不支持数组下标,段名字母/数字/_/-)。 */
export const GHOST_SECRET_EXCHANGE_TOKEN_PATH_RE = /^[A-Za-z0-9_-]+(\.[A-Za-z0-9_-]+)*$/;

/** oauth.identity.displayTemplate:占位符提取(`{点分路径}`;路径形状同 tokenPath)。 */
export const GHOST_OAUTH_IDENTITY_TEMPLATE_PLACEHOLDER_RE = /\{([^{}]*)\}/g;
/** oauth.identity.displayTemplate 长度上限(渲染产物也按同上限截断降级)。 */
export const GHOST_OAUTH_IDENTITY_TEMPLATE_MAX_CHARS = 200;

/**
 * 凭证交换声明(可选):有些服务的 API key 不直接当请求凭证,要先拿 key
 * 去换一个临时令牌(如 mivo 的 key→session 二段式)。声明后主机照单代办:
 * POST 交换端点(请求体模板注入原始 key,按 contentType 确定性转义)→
 * 从响应 JSON 按 tokenPath 取令牌 → 按 ttl 内存缓存 → inject.format 的
 * {value} 注入的是**换来的令牌**而非原始 key;上游 401 时主机作废缓存
 * 重换重试一次。原始 key 与令牌全程不进沙箱。做成清单声明而非主机硬编码,
 * 是为了新意识接入二段式服务不需要更新 app(交换方式由意识作者声明)。
 */
export interface GhostSecretExchangeDecl {
  /** 交换端点(仅 https、默认端口;域名必须命中 network.hosts 白名单)。 */
  url: string;
  /**
   * POST 请求体模板:恰含一个 `{value}` 占位(原始凭证落点)。注入时按
   * contentType 转义:json → JSON 字符串转义;form → percent 编码。
   */
  bodyFormat: string;
  /** 请求体类型;缺省 'application/json'。 */
  contentType?: GhostSecretExchangeContentType;
  /** 令牌在响应 JSON 里的点分路径(如 "session" / "data.token";值须是非空字符串)。 */
  tokenPath: string;
  /** 令牌缓存时长(秒,60–2592000);缺省 3600。 */
  ttlSeconds?: number;
}

/**
 * OAuth 凭证:scopes 条数上限(超出拒装;确认框逐条展示要可读)。
 * 数值正本在本仓 packages/plugin-protocol(manifest.ts),服务端仓维护兼容副本。
 * 客户端只 re-export 不再手抄副本;调整上限须同步两仓并先确认 wire 兼容性。
 * 本校验取值级"严出"(plugin-security-and-authoring.md §7):超上限的包在旧版
 * 客户端拒装,插件市场铺开须等携带新上限的客户端先行发布。
 *
 * 当前 256 上限外另留 64 条防御余量。涨过 320 前必须同步两处 320 上限,
 * 否则会拒绝合法的缺权上报 / 静默判废 assessment:insufficient-scopes
 * 端点的整包条数上限(runtime/ghostOauthEndpoint.ts)与 cindy-tools 的
 * SETUP_REAUTH_SCOPE_MAX(ghost/mcpServer.ts,包依赖方向不允许直接引用本常量)。
 */
export { GHOST_OAUTH_SCOPES_MAX };
/** OAuth broker 模式可声明的备用 clientId 上限(默认 clientId 不计入)。 */
export const GHOST_OAUTH_CLIENT_ID_ALTERNATIVES_MAX = 8;
/** OAuth 凭证:extraAuthorizeParams 条数上限。 */
export const GHOST_OAUTH_EXTRA_PARAMS_MAX = 8;
/**
 * OAuth 授权 URL 的协议保留参数:由主机授权引擎独占,意识的
 * extraAuthorizeParams 不许声明(装入拒;引擎侧同名单防御性忽略)。
 */
export const GHOST_OAUTH_RESERVED_AUTHORIZE_PARAMS: readonly string[] = [
  'response_type',
  'client_id',
  'redirect_uri',
  'state',
  'scope',
  'code_challenge',
  'code_challenge_method',
];

/**
 * OAuth 凭证声明(source: 'oauth',2026-07-13 与 Lizi 定案"通用声明式"):
 * 平台不预设 provider 名单——意识声明"去哪授权、要什么 scope",clientId /
 * clientSecret 由用户在意识设置页自填(经 /oauth 只写通道入库),插件详情
 * 全量展示授权域名与 scopes。声明化的是**参数**不是**代码**:
 * 授权流程(拉浏览器、loopback 回调、state/PKCE 校验、code 换 token、刷新)
 * 永远由主机可信代码执行(cindy-brain/ghostOauthFlow.ts),意识无从插手,
 * access / refresh token 与 client 凭证全程不进沙箱,注入按 inject 声明由
 * networkSlot 出网时现取现注(401 作废重刷重试一次,与 exchange 同套路)。
 */
export interface GhostSecretOauthDecl {
  /** 授权页地址(https;域名必须命中 network.hosts 白名单——确认框上的域名集合 = 全部出网面)。 */
  authorizeUrl: string;
  /** code / refresh token 交换端点(https;域名必须命中 hosts——clientSecret 只流向用户同意过的域名)。 */
  tokenUrl: string;
  /**
   * 可选:作者内置的 OAuth 客户端 ID(2026-07-13 Lizi 定案,filo-google
   * 开箱即用前置)。声明后用户零配置即可点"连接账号";用户在设置页自填的
   * client 凭证**覆盖**内置值(清除自填 = 回落内置)。桌面应用的 client
   * 凭证按 Google 官方口径本非机密(installed-app),写进包里不引入新泄露面;
   * 授权仍需用户在浏览器里亲自同意,凭证本身访问不了任何数据。
   */
  clientId?: string;
  /**
   * 可选:broker 模式下允许意识在单次连接时选择的备用客户端 ID。
   * 典型场景是同一官方意识按宿主 region 连接不同 OAuth App。值都是公开
   * 标识,secret 仍由对应区域的 broker 持有;主机只接受本数组或 clientId
   * 明确声明过的值,意识不能借 connect 请求切到任意第三方应用。
   * 仅 tokenBroker 模式可用,默认 clientId 不要在这里重复声明。
   */
  clientIdAlternatives?: string[];
  /** 可选:内置 client 的 secret(与 clientId 成对;纯 PKCE 服务商可省略)。 */
  clientSecret?: string;
  /** 申请的 scope 列表(0–256 条,确认框逐条展示;缺省 = 不带 scope 参数)。 */
  scopes?: string[];
  /**
   * 可选:authorize URL 里 scope 参数的拼接分隔符。OAuth 标准是空格(缺省),
   * Slack 这类逗号分隔的服务商声明 ","(目前只认这一个值)。
   */
  scopeDelimiter?: ',';
  /** PKCE(S256)开关,缺省 true;个别不支持的老服务商可显式声明 false。 */
  pkce?: boolean;
  /**
   * 服务商特有的授权页附加参数(如 Google 的 access_type=offline +
   * prompt=consent、Atlassian 的 audience=api.atlassian.com);协议保留参数
   * (GHOST_OAUTH_RESERVED_AUTHORIZE_PARAMS)不许声明。
   */
  extraAuthorizeParams?: Record<string, string>;
  /**
   * 可选:授权成功后拉一次身份端点给账号打展示标签(设置页"已连接为 xxx");
   * url 仅 https 且域名须命中 hosts;labelPath 为响应 JSON 的点分路径
   * (与 exchange.tokenPath 同规则)。拉取失败不阻断授权(标签降级为空)。
   *
   * displayTemplate(可选,2026-07-15 cindy-slack 前置):人类可读的展示名
   * 模板,`{点分路径}` 占位符从同一份身份响应取值(如 Slack auth.test 的
   * `"{team} · {user}"`)。与 labelPath 分工:labelPath 指向**稳定且唯一**的
   * 身份键(user_id / 邮箱),是重复授权时同身份合并的判定键;displayTemplate
   * 只管展示(设置页 / 账号工具看到的名字),任一占位符取不到值时整体降级
   * 为空(回落显示 labelPath 标签)。不声明 = 展示名就用 labelPath 的值
   * (邮箱这类本身可读的服务商不需要它)。
   *
   * avatarPath(可选,2026-07-17 xd-feishu 设置页前置):头像 URL 在身份
   * 响应里的点分路径(如飞书 user_info 的 "data.avatar_thumb")。主机连接
   * 时按该路径取 https 地址、**不带任何凭证**地下载小图(mime / 体积硬顶),
   * 转 data URL 存主机保险库,经 /oauth 只读回给意识自绘设置页展示——图片
   * 字节不出主机、沙箱 CSP(img-src data:)恰好放行。取不到 / 下载失败一律
   * 降级无头像,不阻断授权。
   */
  identity?: { url: string; labelPath: string; displayTemplate?: string; avatarPath?: string };
  /**
   * 可选:loopback 回调固定端口(1024–65535)。Atlassian 这类服务商要求回调
   * URI 与应用注册值精确匹配(含端口),声明后主机授权引擎钉死
   * `http://127.0.0.1:<port>/callback`(端口被占用时结构化报错引导重试);
   * 声明 tokenBroker 时必填;其它 OAuth 缺省 = 随机端口(Google 等允许任意
   * loopback 端口的服务商)。
   */
  redirectPort?: number;
  /**
   * 可选:XDT server token broker 的 provider slug(2026-07-14,xd-atlassian
   * 意识化前置)。声明后 code 换 token 与 refresh 不直连 tokenUrl,改经主机
   * 调 XDT server 的授权 broker(带登录 JWT;client secret 在服务端,不随包
   * 分发)。必须同时声明 redirectPort,并与 clientSecret 互斥。资格按可信安装
   * 事实判定,名称前缀不放行。校验层保持纯函数不感知装入语境,门控在装入闸
   * 与连接闸。
   */
  tokenBroker?: string;
  /**
   * 可选:broker 弹跳回调(双地址模型,2026-07-15 cindy-slack 意识化前置)。
   * Slack 这类服务商后台只收 https redirect,不收 http loopback——声明后
   * 报给服务商的 redirect_uri 变成「授权 broker 服务的 https 弹跳路由」
   * (主机运行时用 broker 基地址 + `path` 拼出,清单不落域名字面量),浏览器
   * 授权后落弹跳路由,由其 302 回本机 `http://127.0.0.1:<redirectPort><callbackPath>`。
   * 约束:必须与 tokenBroker、redirectPort 同时声明(弹跳路由的 302 目标
   * 端口与路径在 broker 服务端写死,三者是一套约定);两个路径都必须是
   * `/` 开头的站内绝对路径。
   */
  brokerBounce?: { path: string; callbackPath: string };
}

/** tokenBroker slug 形状(小写字母开头,小写/数字/下划线/连字符,1–32)。 */
export const GHOST_OAUTH_TOKEN_BROKER_RE = /^[a-z][a-z0-9_-]{0,31}$/;

/** brokerBounce 路径形状(/ 开头的站内绝对路径,段字符限字母/数字/_/-,≤128)。 */
export const GHOST_OAUTH_BOUNCE_PATH_RE = /^\/[A-Za-z0-9_-]+(?:\/[A-Za-z0-9_-]+)*$/;

/**
 * 凭证值来源(2026-07-13,xd_service 意识化前置):
 * - 'user'(缺省):值由用户在该意识设置页填入主机保险库;
 * - 'login-email':值 = 主机当前登录账号的邮箱——主机注入时现取登录态,
 *   设置页只读展示该邮箱(不可编辑、不进保险库);未登录 / 登录态缺 email
 *   时 fail-closed 报错并引导重新登录。适用于"服务端按登录邮箱派生鉴权"
 *   的第一方服务(如 pages 服务的 pages_<email> token,经 inject.format
 *   的静态前缀完成派生)。
 * - 'oauth'(2026-07-13,google/conf/jira 意识化前置):值 = 主机托管 OAuth
 *   授权换来的 access token——用户在意识设置页填 client 凭证并点"连接账号",
 *   主机跑授权流程并保管全部令牌,出网时现取新鲜 token 注入(见
 *   GhostSecretOauthDecl;必须同时声明 oauth 详单)。
 * - 'gh-cli':仅供官方 cindy-github 使用。主机优先现读本机 GitHub CLI 的
 *   `gh auth token`,不可用时回落到同 key 经 /secrets 保存的 PAT。两种值都
 *   只在 networkSlot 请求 GitHub API 时注入,不进入插件、Renderer、KV 或日志。
 * - 'oidc-token':值 = Cindy 为当前企业 Membership 签发的短时 Connection
 *   JWT。当前组织的可信市场安装,或企业作者通过 ghost_forge_install 明确安装且
 *   id 命中本组织登记前缀时可签发;手动导入默认不取得该资格。临时例外,只对 root 实例生效:
 *   ghostId 精确等于 mivo-canvas、namespace 为 null 或尚未确认的旧 root 安装,在已装清单声明的精确
 *   oidc-token host 仅为 mivo-canvas.dsworks.cn 时可签发;企业 namespace 下的同名插件、其它本地插件、其它精确 host 仍不签发,已有市场记录(含 installed:false)仍走 digest。市场账本损坏不得当成无记录。
 *   Host 根据当前组织和插件 id 推导 audience,插件不能声明或读取。
 *   令牌只在 networkSlot 发请求时注入,且永不进入 Node Worker。
 *
 * ('login-feishu-token' 已于 2026-07-17 随飞书登录整体下线退役——xd-feishu
 * 改走 source:'oauth' + tokenBroker:'feishu';存量已装清单由内置意识播种器
 * 按指纹覆盖自愈,未覆盖前该意识加载被拒属预期。)
 */
export const GHOST_SECRET_SOURCES = [
  'user',
  'login-email',
  'oauth',
  'gh-cli',
  'oidc-token',
] as const;
export type GhostSecretSource = (typeof GHOST_SECRET_SOURCES)[number];

/**
 * user 凭证有两条 Host 受控收单路径:
 * - 调用前缺失时,Setup Runtime 根据本声明生成统一 inline_form;
 * - 详情页由 settingsHtml 经 `/secrets` 只写通道长期管理、替换和清除。
 *
 * 两条路径都只把明文一次性交给 Main 保险库,插件运行时只能获得 Host 注入后的
 * 请求,读不回原值。历史 `input` 字段仍退役:`input: "ghost"` 仅兼容接受并忽略,
 * `input: "host"` 拒绝;当前仍要求 user 凭证同时声明 settingsHtml 作为管理入口。
 */

/** 凭证声明:Host 用名字与说明生成 Setup 字段,值只写入主机保险库。 */
export interface GhostSecretDecl {
  /** 凭证键(意识内唯一):小写字母开头,允许小写/数字/下划线,1–32。 */
  key: string;
  /** 给用户看的名称(插件详情展示)。 */
  label: string;
  /** 凭证值来源;缺省 'user'(校验归一化:'user' 不落清单)。 */
  source?: GhostSecretSource;
  /** 可选提示(如"在 example.com/settings 生成")。 */
  hint?: string;
  /**
   * 可选:该凭证的控制台/申请页地址(仅 https)。settingsHtml 里可用
   * `<a href>` 逐字引用本地址——主机外链闸(GhostExternalLinkGate)只放行
   * 身份卡声明过的地址,点击转系统浏览器打开;也供确认框等宿主 UI 引用。
   */
  url?: string;
  /** 注入位置声明(必填:没有注入位置的凭证无处可用)。 */
  inject: GhostSecretInjectDecl;
  /** 可选:key 换令牌二段式声明(见 GhostSecretExchangeDecl;与 oauth 互斥)。 */
  exchange?: GhostSecretExchangeDecl;
  /** Optional settings-only credential check; never returns the credential. */
  check?: GhostSecretCheckDecl;
  /** source: 'oauth' 时必填的授权详单(见 GhostSecretOauthDecl);其它来源禁止声明。 */
  oauth?: GhostSecretOauthDecl;
  /**
   * @deprecated 已退役(2026-07-13 宿主凭证渲染退役):user 凭证一律意识
   * settingsHtml 收单。原始清单遗留的 'ghost' 装入时接受并忽略(归一化后
   * 不落清单,见 validateGhostManifest),其余值拒。字段仅为原始清单解析
   * 与存量消费点的类型兼容保留,新代码不要读写。
   */
  input?: 'ghost';
}

/**
 * 多连接声明(connections,2026-07-14,Cindy GitLab 自建实例前置):
 * "地址 + 凭证成对多条"的凭证形态——作者只声明连接类型(名字、注入形态、
 * 条数上限),具体地址与 token 由用户在意识设置页逐条添加(经 /connections
 * 协议通道入库)。与静态 hosts 白名单的关系:用户添加的每条地址并入该意识
 * 的放行域(精确匹配,不吃通配),**每次新增地址都要过主机受信确认弹窗**
 * ——动态白名单不能只凭意识设置页(意识自绘、不可信)单方面扩张。凭证注入
 * 范围恒等于各连接自身地址(结构上钉死"token 只流向它自己的实例"),因此
 * inject 不允许声明 hosts 子集(写了拒装)。
 */
export interface GhostConnectionDecl {
  /** 连接声明键(意识内唯一,与 secrets[].key 共用命名空间不得撞名):小写字母开头,1–32。 */
  key: string;
  /** 给人看的连接类型名(如「GitLab 实例」;确认框与设置页展示)。 */
  label: string;
  /** 可选提示(≤200 字,设置页展示,如"填实例域名与 Personal Access Token")。 */
  hint?: string;
  /**
   * 凭证注入形态(header + format,校验同 GhostSecretInjectDecl;**禁止**
   * 声明 hosts——注入范围恒等于各连接自身地址,不接受作者收窄/扩张)。
   */
  inject: { header: string; format: string };
  /** 每种连接可添加的地址数上限(1–8 整数;缺省 8)。 */
  maxConnections?: number;
}

/**
 * network 槽详单(与 slots 含 'network' 成对;有槽无详单允许装入但零能力,
 * 与 cindy / subscribe 同语义)。
 */
export interface GhostNetworkNeeds {
  /**
   * 静态域名白名单(装入时钉死;运行期主机逐请求校验)。常规必填 1–8 条;
   * 声明了 connections(动态连接地址)时可缺省/空数组——静态域名与动态
   * 连接至少有其一(校验保证),归一化后恒为数组(可能为空)。
   */
  hosts: string[];
  /** 凭证声明(0–4 条;用户填值,主机加密保管并按 inject 声明注入)。 */
  secrets?: GhostSecretDecl[];
  /** 多连接声明(0–2 条;地址+凭证成对多条,用户在设置页添加,见 GhostConnectionDecl)。 */
  connections?: GhostConnectionDecl[];
}

/** preview 槽:可打开预览的域名模式条数上限(范围越小越好,同 network 精神)。 */
export const GHOST_PREVIEW_MAX_HOSTS = 4;
/** preview 槽:单次请求打开的 URL 长度上限(字符)。 */
export const GHOST_PREVIEW_URL_MAX_CHARS = 2048;
/** preview 槽:同一插件两次打开预览的最小间隔 ms(防标签页刷屏)。 */
export const GHOST_PREVIEW_OPEN_MIN_INTERVAL_MS = 5000;

/**
 * agent.schedule:同一插件两次请求打开自动化面板的最小间隔 ms。
 * 比 preview 长一档 —— 这个面板是**打断式**的(会把用户从当前页带走),
 * 而预览标签只是在右侧栏多开一页。按尝试记账,spam 顺延窗口。
 */
export const GHOST_SCHEDULE_DRAFT_MIN_INTERVAL_MS = 15_000;
/** agent.schedule:预填任务名长度上限(字符;超出截断)。 */
export const GHOST_SCHEDULE_DRAFT_NAME_MAX_CHARS = 60;
/** agent.schedule:预填 prompt 长度上限(字符;超出截断)。 */
export const GHOST_SCHEDULE_DRAFT_PROMPT_MAX_CHARS = 2000;
/**
 * agent.schedule:插件能建议的最小触发间隔 ms(30 分钟)。
 *
 * 这不是权限闸门(任务由用户在面板上亲手保存,他改成 1 分钟是他的自由),而是
 * **对插件建议值的钳制** —— 不让插件预填出一个每分钟叫醒一次 AI 会话的任务,
 * 用户点保存时未必看清频率就把额度烧了。低于此值一律上调到此值。
 */
export const GHOST_SCHEDULE_DRAFT_MIN_INTERVAL_SUGGESTION_MS = 30 * 60_000;

/**
 * preview 槽详单(与 slots 含 'preview' 严格成对——有槽必有详单:范围是
 * 本能力的全部知情面,不允许"先装后说")。hosts 语法与 network 域名白名单
 * 一致(支持 `*.` 单层前缀通配),另特批 loopback 单段名(本地 dev server
 * 是预览的正当主场,network 语法"至少两段"表达不了它)。插件详情逐条展示。
 */
export interface GhostPreviewNeeds {
  hosts: string[];
}

/** preview.hosts 特批的 loopback 主机名(network 域名语法之外唯一的例外)。 */
export const GHOST_PREVIEW_LOOPBACK_HOSTS: ReadonlySet<string> = new Set([
  'localhost',
  '127.0.0.1',
  '[::1]',
]);

/** browserExtension 槽:当前宿主实现的扩展线协议标识(协议 3,签名线合同 0.4.13)。 */
export const GHOST_BROWSER_EXTENSION_PROTOCOL = 'cindy-browser-extension/3';
/** browserExtension 槽:允许连接的扩展 id 条数上限(商店版、Edge 版、开发版各一条足矣)。 */
export const GHOST_BROWSER_EXTENSION_MAX_IDS = 8;
/** Chromium 扩展 id:32 位 a–p 字母(公钥 SHA-256 前 128 位的映射)。 */
export const GHOST_BROWSER_EXTENSION_ID_RE = /^[a-p]{32}$/;
/** Native Messaging host 名:Chrome 要求小写字母、数字、下划线,点分段。 */
export const GHOST_BROWSER_EXTENSION_NATIVE_HOST_RE = /^[a-z0-9_]+(?:\.[a-z0-9_]+)*$/;

/**
 * browserExtension 槽详单(2026-10-27):插件随包携带一个浏览器扩展,由宿主
 * 在本机回环地址承接扩展的连接(配对、身份绑定、作业分发、请求转交),插件
 * 不再自带接线进程。extensionIds 是本能力的全部知情面:只有这些扩展 id 能
 * 连上宿主桥接;插件详情逐条展示。声明 pageControl 的扩展同时实现页面控制
 * 契约,Browser Use 可把它作为「我的浏览器」执行端。
 */
export interface GhostBrowserExtensionNeeds {
  /** 线协议标识;当前宿主只实现 GHOST_BROWSER_EXTENSION_PROTOCOL。 */
  protocol: typeof GHOST_BROWSER_EXTENSION_PROTOCOL;
  /** 允许连接的扩展 id(1–8 条;商店版、Edge 版、开发版)。 */
  extensionIds: string[];
  /**
   * 首次配对用的 Native Messaging host(可选):name 为注册名,binary 为包内
   * 平台二进制目录(`<binary>/<platform>-<arch>/cindy-browser-native[.exe]`),
   * 由宿主复制到本机私有目录并向各浏览器注册。
   */
  nativeHost?: { name: string; binary: string };
  /** 扩展实现页面控制契约;Browser Use 据此把它列为用户浏览器执行端。 */
  pageControl?: true;
  /**
   * 宿主承接页面控制后被取代的插件自有 Agent 工具与手册条目。宿主确实在经本插件
   * 提供「我的浏览器」时,对 Agent 隐藏它们,只留一套操作用户浏览器的工具;
   * 不认识此字段的旧宿主照常暴露。须同时声明 pageControl。
   */
  pageControlReplaces?: { tools: string[]; manual?: string[] };
}

/** skill 槽:单插件最多捆绑的 Agent Skill 数(范围越小越好,同 preview 精神)。 */
export const GHOST_SKILL_MAX_ITEMS = 4;
/** skill 槽:SKILL.md 单文件字节上限。打包与装入两侧共用,避免契约漂移。 */
export const GHOST_SKILL_MD_MAX_BYTES = 64 * 1024;
/** skill 槽:技能 name 长度上限(链接目录名的一半,克制)。 */
export const GHOST_SKILL_NAME_MAX_CHARS = 64;
/**
 * skill 槽:技能 name 形状——小写字母/数字,连字符仅作单段分隔(禁首尾与连续
 * 连字符)。比 learn-host 的 SKILL_NAME_RE 更严:意识 id 允许含 `--`
 * (GHOST_ID_RE),插件私有技能根的链接名是 `<id>--<name>`,只有 name 侧禁 `--`,
 * 按"最后一个 `--`"拆分才唯一,不同插件才不可能撞出同一个链接名。
 */
export const GHOST_SKILL_NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;

/** manual:单插件最多声明的渐进披露手册单元数。 */
export const GHOST_MANUAL_MAX_ITEMS = 8;
/** manual:每个声明单元固定的入口文件名。 */
export const GHOST_MANUAL_ENTRY_FILE = 'MANUAL.md';
/** manual:单个 Markdown 文件的字节上限。打包与装入两侧共用。 */
export const GHOST_MANUAL_MD_MAX_BYTES = 64 * 1024;
/** manual:一级索引说明的字符上限。 */
export const GHOST_MANUAL_DESCRIPTION_MAX_CHARS = GHOST_MANIFEST_SUMMARY_MAX_CHARS;

/** skill 槽单条技能声明(全声明式:插件详情展示的就是这里的字段)。 */
export interface GhostSkillItem {
  /** 包内技能目录(安全相对路径,目录内必须有 SKILL.md)。 */
  dir: string;
  /**
   * 技能名。必须与 SKILL.md frontmatter 的 name 逐字一致(打包与装入双侧
   * 强制)——详情里用户看到的,必须就是 Agent 实际读到的。
   */
  name: string;
  /** 技能说明。必须与 SKILL.md frontmatter 的 description 逐字一致(同上)。 */
  description: string;
}

/**
 * skill 槽详单(与 slots 含 'skill' 严格成对——有槽必有详单:捆绑了什么技能
 * 是本能力的全部知情面,不允许隐藏声明)。插件详情逐条展示。
 */
export interface GhostSkillNeeds {
  items: GhostSkillItem[];
}

/** manual 单条手册声明。name 是模型调用时使用的逻辑路径首段,dir 是包内物理目录。 */
export interface GhostManualItem {
  /** 包内手册目录(安全相对路径,目录内必须有 MANUAL.md)。 */
  dir: string;
  /** 逻辑名称;沿用 skill name 的小写连字符规则。 */
  name: string;
  /** ghost_info / ghost_manual 根索引展示的手册说明。 */
  description: string;
}

/** 插件随包提供、由 Host 按需读取的渐进披露手册索引。 */
export interface GhostManualNeeds {
  items: GhostManualItem[];
}

/**
 * preview 槽运行期 URL 守门(纯函数,主机侧调用):
 * - 只收 https;http 仅放行 loopback(localhost / 127.0.0.1 / [::1])——本地
 *   开发服务器是预览的正当主场;
 * - 不收 URL 内嵌凭证(user:pass@,钓鱼与凭证外带面);
 * - hostname 必须命中 preview.hosts 声明(逐模式 ghostNetworkHostMatches)。
 */
export function ghostPreviewUrlAllowed(manifest: GhostManifest, rawUrl: string): boolean {
  if (
    typeof rawUrl !== 'string' ||
    rawUrl.length === 0 ||
    rawUrl.length > GHOST_PREVIEW_URL_MAX_CHARS
  ) {
    return false;
  }
  const hosts = manifest.preview?.hosts ?? [];
  if (hosts.length === 0) return false;
  let url: URL;
  try {
    url = new URL(rawUrl);
  } catch {
    return false;
  }
  if (url.username !== '' || url.password !== '') return false;
  const hostname = url.hostname.toLowerCase();
  const isLoopback = hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '[::1]';
  if (url.protocol !== 'https:' && !(url.protocol === 'http:' && isLoopback)) return false;
  return hosts.some((pattern) => ghostNetworkHostMatches(pattern, hostname));
}

const LOOPBACK_HOSTNAMES = new Set(['localhost', '127.0.0.1', '[::1]']);

/**
 * 回环地址的「主机:端口」身份(http / ws,无凭证);非回环或其它协议返回 null。
 * 面板嵌入回环预览时,嵌入帧内的请求只许回到同一主机:端口。
 */
export function ghostLoopbackOrigin(rawUrl: unknown): string | null {
  if (typeof rawUrl !== 'string' || rawUrl.length === 0 || rawUrl.length > GHOST_PREVIEW_URL_MAX_CHARS) return null;
  let url: URL;
  try {
    url = new URL(rawUrl);
  } catch {
    return null;
  }
  if (url.username !== '' || url.password !== '') return null;
  if (url.protocol !== 'http:' && url.protocol !== 'ws:') return null;
  const hostname = url.hostname.toLowerCase();
  if (!LOOPBACK_HOSTNAMES.has(hostname)) return null;
  return `${hostname}:${url.port || '80'}`;
}

/**
 * 插件页面能否嵌入本机回环预览页:身份卡必须同时声明一种页面(panel / mainView /
 * taskView)、node 工作进程
 * (页面由随包进程在本机提供)以及 preview.hosts 中的 localhost / 127.0.0.1。
 * 满足时主机放行面板内指向回环地址的子帧,以及该子帧回到同一主机:端口的请求;
 * 面板页自身仍不能联网。
 */
export function ghostPanelLoopbackEmbedAllowed(manifest: GhostManifest): boolean {
  if (!(manifest.panel || manifest.mainView || manifest.taskView) || !manifest.node) return false;
  return (manifest.preview?.hosts ?? []).some((host) => host === 'localhost' || host === '127.0.0.1');
}

/**
 * 身份卡里声明过的全部外链地址(来源 = network.secrets[].url 与
 * node.secretBindings[].url,装包时
 * 已校验仅 https):意识 webview 外链闸(GhostExternalLinkGate)的白名单,
 * settingsHtml/面板里的 <a href> 逐字命中才转系统浏览器打开。
 */
export function ghostExternalLinkUrls(manifest: GhostManifest): string[] {
  return [...(manifest.network?.secrets ?? []), ...(manifest.node?.secretBindings ?? [])]
    .map((s) => s.url)
    .filter((url): url is string => typeof url === 'string' && url.length > 0);
}

/**
 * 注入头名黑名单:协议关键头由主机独占,作者声明命中即拒装
 * (小写比较;Cookie 也拒——会话粘连语义不给意识)。
 */
export const GHOST_NETWORK_FORBIDDEN_INJECT_HEADERS: readonly string[] = [
  'host',
  'content-length',
  'transfer-encoding',
  'connection',
  'cookie',
  'origin',
  'referer',
  // content-type 由请求语义决定(上传通道的 multipart boundary 依赖它),
  // 不许被凭证注入声明占用——401 重换/跨域跳转的重注入会砸掉 boundary。
  'content-type',
];

/* ── setup 就绪声明(使用前置检查,2026-07-21)──────────────────────────
 *
 * 作者用一份声明回答「这段意识用之前必须配好什么」,宿主在用户点「使用」
 * 时据此做确定性检查(规则 9:检查逻辑在宿主代码,作者只交知识),未就绪
 * 弹窗引导去配置页。语义:
 * - requires 组间 = 全部满足(allOf);组内 anyOf = 满足其一即可
 *   (Web Search 的 Brave / Tavily 任一 key 即典型组内关系);
 * - 条目三种引用:'secret:<key>'(network.secrets 声明的凭证:user 源查
 *   已保存、oauth 源查已连接账号)、'connection:<key>'(network.connections
 *   至少一条)、{ kv: '<key>', label: '...' }(意识 /kv 参数非空——kv 键名
 *   宿主无先验,label 必填供弹窗展示);
 * - 'login-email' 源凭证恒就绪,引用它属作者误解 → 拒装;
 * - 缺省(不声明 setup)= 宿主启发式:声明过凭证/连接的意识,任一项就绪
 *   即算 ready;什么都没声明的恒 ready。现有内置意识全部被启发式正确覆盖,
 *   只有启发式判不准才需要写本字段——两种典型:「必须同时配 A 和 B」用
 *   多组声明;「凭证全是可选项、不配也能用」用 requires: [](显式 opt-out,
 *   恒就绪,启发式不再兜底)。
 */

/** setup.requires 需求组条数上限。 */
export const GHOST_SETUP_MAX_GROUPS = 8;
/** Host-owned requirement groups (e.g. model-provider capability). */
export const GHOST_SETUP_MAX_HOST_GROUPS = 2;
/** 每个需求组内 anyOf 条目上限。 */
export const GHOST_SETUP_MAX_ITEMS_PER_GROUP = 8;
/** 一张 setup 卡最多需要覆盖 manifest 合法声明的全部可操作条目。 */
export const GHOST_SETUP_MAX_STEPS =
  (GHOST_SETUP_MAX_GROUPS + GHOST_SETUP_MAX_HOST_GROUPS) * GHOST_SETUP_MAX_ITEMS_PER_GROUP;
/**
 * Host-owned setup providers may append requirements that do not exist in the
 * plugin manifest (for example, a shared client capability). Reserve a bounded
 * number of steps for those Core-owned requirements so a maximally valid
 * manifest still crosses the Main → Renderer interaction boundary intact.
 */
export const GHOST_SETUP_MAX_HOST_STEPS = 8;
/** setup interaction/plan transport capacity, including Host-owned steps. */
export const GHOST_SETUP_MAX_INTERACTION_STEPS = GHOST_SETUP_MAX_STEPS + GHOST_SETUP_MAX_HOST_STEPS;
/** setup kv 引用的键名形状(意识 /kv 顶层键;点号仅作普通字符,不做路径下钻)。 */
export const GHOST_SETUP_KV_KEY_RE = /^[A-Za-z0-9_.-]{1,64}$/;

/** 归一化后的单条 setup 需求(原始清单里 secret/connection 是字符串引用,kv 是对象)。 */
export type GhostSetupRequirement =
  | { kind: 'secret'; key: string }
  | { kind: 'connection'; key: string }
  | { kind: 'kv'; key: string; label: string };

/** setup 需求组:组内 anyOf 任一满足即组满足。 */
export interface GhostSetupGroup {
  anyOf: GhostSetupRequirement[];
}

/** setup 就绪声明(见上方块注释;不变量由 validateGhostManifest 保证)。 */
export interface GhostSetupDecl {
  requires: GhostSetupGroup[];
}

/**
 * 单条需求的就绪展示项(ghosts:setup-status IPC 载荷;main 判定、renderer
 * 弹窗展示)。kind 决定文案口径:key = 填 API key,oauth = 连接账号,
 * connection = 添加连接,kv = 填自定义参数。
 */
export interface GhostSetupStatusItem {
  /** 需求引用原文(secret:<key> / connection:<key> / kv:<key>),排障与去重用。 */
  ref: string;
  /** 展示名(secret/connection 取 network 声明的 label;kv 取 setup 声明的 label)。 */
  label: string;
  kind: 'key' | 'oauth' | 'connection' | 'kv';
}

/** 意识配置就绪状态(main 侧 evaluateGhostSetup 产出)。 */
export interface GhostSetupStatus {
  ready: boolean;
  /**
   * 未满足的需求组(每组列出仍缺的条目;组内任一配好即满足,弹窗按
   * 「A / B」口径展示)。ready 时恒为空。
   */
  missingGroups: GhostSetupStatusItem[][];
  /** OAuth 账号存在但全部过期的条目(文案区分「重新连接」)。ready 时恒为空。 */
  reauth: GhostSetupStatusItem[];
}

/** Setup Runtime 暴露给 Agent / Renderer 的需求类型;不包含任何配置值。 */
export type GhostSetupRequirementKind =
  'oauth' | 'secret' | 'connection' | 'plugin_config' | 'client_config';

/** Host 对单条 requirement 的权威判定。 */
export type GhostSetupRequirementState = 'missing' | 'expired' | 'satisfied';

/** Setup Runtime 允许 Agent 选择、但只能由 Host 执行的动作。 */
export type GhostSetupActionKind =
  | 'oauth_connect'
  | 'open_plugin_settings'
  | 'manage_connection'
  | 'open_client_settings'
  | 'inline_form';

/** Secret 输入沿用 /secrets 的字符上限;值本身永远不进入 Shared DTO。 */
export const GHOST_SECRET_VALUE_MAX_CHARS = 4096;

export interface GhostSetupInlineSecretField {
  /** v1 只支持单字段,固定 id 防止 Renderer/Agent 构造任意存储键。 */
  id: 'value';
  type: 'secret';
  label: string;
  description?: string;
  placeholder?: string;
  /**
   * Host 从 manifest 的 network.secrets[].url 生成的辅助入口。
   * 仅供可信 Desktop UI 展示;MCP 边界会剥离,Agent 不能提供或改写 URL。
   */
  externalLink?: {
    url: string;
  };
  required: true;
  maxLength: number;
}

export type GhostSetupAllowedAction =
  | {
      /** Host 生成的动作引用;执行时必须按最新 assessment 再校验,不能直接当执行参数。 */
      id: string;
      kind: Exclude<GhostSetupActionKind, 'inline_form'>;
    }
  | {
      /** Host 生成的散列动作引用;不编码或暴露 Secret storage key。 */
      id: string;
      kind: 'inline_form';
      form: {
        /** v1 仅支持一个 Secret 字段。 */
        fields: [GhostSetupInlineSecretField];
      };
    };

export interface GhostSetupAssessmentItem {
  /** requirement 的稳定关联引用;不携带配置值,也不是可执行能力。 */
  ref: string;
  kind: GhostSetupRequirementKind;
  label: string;
  description?: string;
  state: GhostSetupRequirementState;
  actions: GhostSetupAllowedAction[];
}

export interface GhostSetupAssessmentGroup {
  id: string;
  mode: 'any_of';
  items: GhostSetupAssessmentItem[];
}

/**
 * 插件仍可调用、但默认 OAuth 账号的全量授权面落后于当前清单时的非阻塞建议。
 * 只含 scope 名称与 Host 生成的动作引用,不含令牌或 client 凭证。
 */
export interface GhostSetupReauthSuggest {
  ghostId: string;
  secretKey: string;
  missingScopes: string[];
  missingScopeCount: number;
  requirement: {
    ref: string;
    kind: 'oauth';
    label: string;
    action: {
      id: string;
      kind: 'oauth_connect';
    };
  };
}

/**
 * Setup Runtime 的完整判定结果。groups 之间 all-of,组内 any-of;
 * revision 由 Host 变更总线维护,用于丢弃过期卡片更新。
 */
export interface GhostSetupAssessment {
  state: 'ready' | 'required';
  revision: number;
  groups: GhostSetupAssessmentGroup[];
  /** ready 语义不变;Agent 可据此建议用户重新连接,但不得拦截当前调用。 */
  reauthSuggest?: GhostSetupReauthSuggest;
}

/** Agent 可选提供的展示编排;身份、Action 和完成状态仍由 Host 决定。 */
export interface GhostSetupPlan {
  assessmentRevision: number;
  intro?: string;
  steps: Array<{
    id: string;
    requirementRefs: string[];
    title: string;
    description: string;
    actionId: string;
  }>;
}

export type GhostSetupStepPhase =
  | 'pending'
  | 'action_running'
  | 'waiting_external'
  | 'verifying'
  | 'satisfied'
  | 'failed'
  | 'cancelled';

/**
 * Setup 卡片跨进程/跨设备传输的稳定错误码。
 *
 * Main 可以保留内部错误详情用于诊断,但 interaction snapshot 只携带这些
 * 与 locale 无关的 code;每个 Renderer 按自己的语言映射可操作文案。
 */
export const GHOST_SETUP_ERROR_CODES = [
  'ACTION_FAILED',
  'ACTION_STALE',
  'AUTH_CANCELLED',
  'AUTH_FAILED',
  'AUTH_NETWORK',
  'AUTH_SERVICE_UNAVAILABLE',
  'INLINE_INVALID',
  'INLINE_UNAVAILABLE',
  'SAVE_FAILED',
  'WINDOW_CLOSED',
  'TARGET_UNAVAILABLE',
  'ASSESSMENT_FAILED',
  'TIMEOUT',
] as const;

export type GhostSetupErrorCode = (typeof GHOST_SETUP_ERROR_CODES)[number];

/** 不可信 interaction payload 的稳定 Setup 错误码守卫。 */
export function isGhostSetupErrorCode(value: unknown): value is GhostSetupErrorCode {
  return (
    typeof value === 'string' && (GHOST_SETUP_ERROR_CODES as readonly string[]).includes(value)
  );
}

/** ghost.json 清单(不变量由 validateGhostManifest 保证)。 */
export interface GhostManifest {
  /** Optional v3 extension, validated only when projecting homepage recommendations. */
  recommendations?: unknown;
  /** 原始清单格式版本;v2 已在解析边界投影成与 v3 相同的直接字段。 */
  schemaVersion: 2 | 3;
  /** 唯一标识,同时是安装目录名与 panelKind 后缀。 */
  id: string;
  /** 展示名。 */
  name: string;
  /** 版本字符串(不强制 semver,仅展示用)。 */
  version: string;
  /** 包内本版本完整更新说明;旧包可省略。 */
  releaseNotes?: string;
  /** 安装此 Release 所需的最低 Cindy 客户端 SemVer;缺省表示不限制。 */
  minCindyVersion?: string;
  /** 作者展示名(仅展示用)。 */
  author?: string;
  /**
   * 本地化资源路径。声明后必须至少提供英文;宿主按当前应用语言读取,
   * 当前语言未提供时固定回退英文。路径均位于插件安装目录内。
   */
  locales?: GhostManifestLocales;
  /**
   * 宿主解析清单后附加的当前语言,只用于运行时视图与 webview 刷新。
   * 不属于 ghost.json 作者字段;validateGhostManifest 会忽略包内同名输入。
   */
  resolvedLocale?: SupportedLocale;
  /**
   * 意识自我介绍(1–300 字,仅展示用):这段意识是干嘛
   * 的、给谁用。插件详情页展示;与 tools[].description(给 AI 看的
   * 工具说明)职责不同,后者不因本字段缺省而顶上。
   */
  description?: string;
  /**
   * 语义召回线索(1–300 字;给模型看,不上界面):什么场景该想起
   * 这段意识——进 agent 会话的意识花名册。与 description 分开是因为读者不同:
   * 描述给人看要简洁,召回线索给模型看要场景枚举、且会反复调优。缺省时
   * 花名册回落用 description。
   */
  whenToUse?: string;
  /**
   * 图标图片(包内相对路径,装入后位于安装目录)。仅允许白名单扩展名
   * (见 ghostIconMimeType);由 main 读盘转 data URL 随清单下发,
   * renderer 直接 <img> 渲染——cindy-ghost:// 协议只挂沙箱分区,主窗口不走它。
   */
  icon?: string;
  /**
   * 意识形态,恒 'chip'(2026-07-12 单形态定案)。清单里可省略(同日晚间
   * 定案:单形态后纯冗余),校验归一化补齐——消费方永远拿到 'chip'。
   */
  kind: 'chip';
  /** 逻辑入口 JS(安装目录内相对路径,电子脑)。 */
  entry: string;
  /** 电子脑启动模式;缺省 = 'on-demand'(被需要才拉起)。 */
  launch?: GhostLaunchMode;
  /** Agent 新回合能力;空对象表示只允许真实用户点击触发。 */
  agent?: GhostAgentNeeds;
  /** 随包本地 Node 工作进程声明。 */
  node?: GhostNodeNeeds;
  /**
   * 设置页「自定义设置区」界面入口(可选;安装目录内相对路径,意识自绘)。
   * 与面板同款沙箱 webview 渲染(零桥、分区断网、CSP 'self'),主题 token
   * 由主机灌入。调用前缺失的 user Secret 可由 Host Setup 卡收单;详情页仍可
   * 通过同源只写 `/secrets` 管理、替换和清除。自定义参数持久化走 `/kv`,
   * Secret 不得写入 `/kv`。
   */
  settingsHtml?: string;
  /** Optional mobile page projection; unknown/invalid declarations leave desktop behavior unchanged. */
  mobile?: { channels: string[]; panel?: string; mainView?: string; settings?: string };
  /**
   * 自定义设置区固定高度(px,可选;160–800)。缺省 = 宿主量 guest 内容
   * 高度自适应(同区间收口);声明本字段 = 固定高度(内容动态增减的设置
   * 页用它避免抖动)。须与 settingsHtml 成对声明。
   */
  settingsHeight?: number;
  /** 本插件是否使用宿主默认配置卡;缺省/true 启用,false 隐藏且不读取该插件的卡片配置。 */
  showTaskPreferences?: boolean;
  /**
   * 卡片能力;空对象表示基础卡片渲染。
   * externalLinks: true 时卡片内可声明 data-ghost-link,点击经宿主确认框后打开浏览器。
   */
  card?: GhostCardNeeds;
  /** Host-owned mail editor; providers supply mailbox adapters only. */
  mail?: true;
  /** Fixed read-only tool for native mail previews; URLs must match an exact HTTPS host. */
  mailReader?: import('@cindy/maker-shared/mail-message').MailReaderDeclaration;
  /** 注册给 agent 的工具声明;字段本身就是能力声明。 */
  tools?: GhostToolDecl[];
  /** `@` 面板入口由已安装插件的 command 提供;不支持资源搜索字段。 */
  /**
   * Cindy 代办能力及范围。v2 清单里的旧字段名 model 在兼容校验层收入本字段。
   */
  cindy?: GhostCindyNeeds;
  /**
   * 订阅能力与事件范围。
   * hooks 非空时 launch 必须为 'resident'(校验强制)。
   */
  subscribe?: GhostSubscribeNeeds;
  /** Autonomous publishing of declared events into user-configured routines. */
  routineEvents?: GhostRoutineEvents;
  /**
   * 网络能力与范围。
   * 域名白名单 + 凭证声明,插件详情逐项展示,运行期主机代发并守门。
   */
  network?: GhostNetworkNeeds;
  /**
   * 预览能力:可在右侧栏内置浏览器
   * 打开预览标签页的域名白名单。
   */
  preview?: GhostPreviewNeeds;
  /**
   * 浏览器扩展能力:插件随包的浏览器扩展经宿主本机桥接连接 Cindy,
   * 允许连接的扩展 id 在装入时钉死。
   */
  browserExtension?: GhostBrowserExtensionNeeds;
  /**
   * 随包捆绑的 Agent Skills 清单。
   * 启用时由 Cindy 私有入口加载到本地 Claude Code、Codex 与 Pi,不写用户共享目录;字段不参与
   * 本地化(必须与 SKILL.md 逐字一致,见 GhostSkillItem)。
   */
  skill?: GhostSkillNeeds;
  /**
   * 随包渐进披露手册。它不是能力 slot 或授权项;Host 只把索引投影给模型,
   * 正文经 ghost_manual 按需读取。旧客户端忽略这一可选顶层字段。
   */
  manual?: GhostManualNeeds;
  /**
   * 就绪声明(使用前置检查,见 GhostSetupDecl 块注释):作者声明「用之前
   * 必须配好什么」,宿主点「使用」时确定性检查并引导配置。缺省 = 启发式
   * (声明过凭证/连接的意识任一项就绪即 ready)。
   */
  setup?: GhostSetupDecl;
  /**
   * 显式触发指令(聊天输入框 `/<command>`,与 Skill 共用命令入口;
   * 2026-07-09 Lizi 定案:由意识作者自定,装入时主机与已装意识查重,
   * 冲突即拒)。须声明 tools——没有工具的指令无事可做。
   */
  command?: string;
  /**
   * @deprecated 语义触发扩展词表——「语言提及软提示」已于 2026-07-14 移除
   * (普通用户无法理解凭空出现的「提及意识」胶囊),本字段不再有任何消费。
   * 校验保留(数量/长度/单字词限制)仅为旧包装入兼容,新意识不要写,
   * 手册(FORGE_GUIDE)已不再介绍。
   */
  keywords?: string[];
  /** 面板声明;没有面板的意识(如纯工具意识)可省略。 */
  panel?: GhostPanelDecl;
  /** 应用级主视图声明;v3 直接声明,v2 与 `main-view` slot 成对。 */
  mainView?: GhostMainViewDecl;
  /** 跟对话的任务页声明;v3 直接声明,v2 与 `task-view` slot 成对。 */
  taskView?: GhostTaskViewDecl;
  /** 无配置的 Host 能力只接受字面量 true;不需要时省略。 */
  notify?: true;
  badge?: true;
  confirm?: true;
  fs?: true;
  /** 持久作品库;卸载不删数据,位置和删除由 Host 设置页管理。 */
  library?: true;
  /** Encrypted opaque exchange with this plugin on same-account desktops. */
  deviceSync?: true;
  sessionContext?: true;
  pick?: true;
  workspace?: true;
  /** @deprecated Retirement detection only. No runtime capability is granted. */
  iosSimulator?: true;
  /** v3 未知字段为前向兼容原样保留,但 Host 不解释也不授权。 */
  [key: string]: unknown;
}

/**
 * 单个插件 locale 文件的 manifest 文案。协议键、工具名和参数名不翻译;
 * tools 以稳定 tool name 对齐,避免数组顺序变化导致翻译错位。
 * 所有条目都是可选项:缺失的条目在解析时回退原 manifest 文案。
 */
export interface GhostManifestLocaleResource {
  name?: string;
  description?: string;
  whenToUse?: string;
  tools?: Record<
    string,
    {
      description: string;
      /** JSON Pointer → 该参数 schema 节点已有的 title / description 翻译。 */
      parameters?: Record<string, { title?: string; description?: string }>;
    }
  >;
  panel?: { title: string };
  mainView?: { title: string };
  taskView?: { title: string };
  network?: {
    secrets?: Record<string, { label: string; hint?: string }>;
    connections?: Record<string, { label: string; hint?: string }>;
  };
  node?: {
    secretBindings?: Record<string, { label: string; hint?: string }>;
  };
  setup?: {
    kv?: Record<string, { label: string }>;
  };
}

/** 单个插件 locale JSON 的字节上限。Forge 与装入侧共用,避免两端契约漂移。 */
export const GHOST_LOCALE_MAX_BYTES = 64 * 1024;

/**
 * Host 对插件安装记录完整性的验证结论。
 *
 * `approved` 的 revision 由 Main 在真实包通过校验并原子落位后生成,不表示用户
 * 另行批准了插件能力;另外两态都不能运行,需要通过市场或 `.cindy` 重新安装。
 */
export type GhostInstallApproval =
  { state: 'approved'; revision: string } | { state: 'legacy-unapproved' } | { state: 'invalid' };

/** 把安装验证态投影成跨进程更新事务使用的稳定 token。 */
export function ghostInstallApprovalToken(approval: GhostInstallApproval | undefined): string {
  if (approval?.state === 'approved') return `approved:${approval.revision}`;
  return approval?.state ?? 'legacy-unapproved';
}

/** 更新 IPC 只接受 Host 列表曾下发过的安装验证 token。 */
export function isGhostInstallApprovalToken(value: unknown): value is string {
  return (
    value === 'legacy-unapproved' ||
    value === 'invalid' ||
    (typeof value === 'string' &&
      /^approved:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(value))
  );
}

/** Public attribution requires a server projection; other installs retain their package attribution. */
export function ghostFallbackDisplayAuthor(ghost: Pick<InstalledGhost, 'manifest' | 'publishingSource'>): string | null {
  return ghost.publishingSource?.kind === 'public-market' ? null : ghost.manifest.author ?? null;
}

/** 已装入主机的插件(批准清单 + 安装位置 + 启用态)。 */
export interface InstalledGhost {
  /** Read-only Host provenance, not authorship or publication permission. Missing is unknown. */
  publishingSource?:
    | { kind: 'local'; source: 'manual' | 'agent-forge' }
    | { kind: 'public-market'; pluginId: string }
    | { kind: 'unavailable' };
  /** Host retirement projection; never supplied by plugin authors. */
  retirement?: import('./featureRetirements').InstalledFeatureRetirement;
  /** Host receipt fact, not a manifest declaration. Missing means tasks need confirmation. */
  taskCapabilityApproved?: true;
  /** Independent Host consent for cross-task/companion target access. */
  targetCapabilityApproved?: true;
  manifest: GhostManifest;
  /** 安装目录绝对路径(userData/brain/<id> 或 userData/brain/_ns/<org>/<id>)。 */
  dir: string;
  /**
   * Host-verified install namespace. Missing is not a confirmed identity.
   * null is confirmed root; a string is a confirmed organization slug.
   */
  namespace?: string | null;
  /** Registry confirmation. Pending and unconfirmed must not receive new privileges. */
  namespaceState?: 'confirmed' | 'unconfirmed' | 'pending';
  /** Stable storage key. Absent only on projections built before the registry loads. */
  instanceKey?: string;
  /**
   * 是否启用。停用 = 面板与能力休眠(不注册、不渲染),但插件仍装着、
   * 布局位置保留;重新启用即恢复。批准安装的真身在 Host receipt 中;
   * 安装目录里的 `.disabled` 只保留为旧版本兼容镜像。
   */
  enabled: boolean;
  /** Host 是否持有一次明确安装/更新确认形成的批准快照。 */
  approval: GhostInstallApproval;
  /** Host-owned approval-revision snapshot root for approved skill directories. */
  approvedSkillRoot?: string;
  /** 安装时由主机验出的来源/签名等级;作者清单不能自报。 */
  trust?: GhostTrustInfo;
  /**
   * 图标的 data URL(main 按 manifest.icon 读安装目录生成;未声明图标、
   * 文件缺失或超限时缺省)。renderer 直接作 <img src> 用,无需 loading 态。
   */
  iconDataUrl?: string;
  /**
   * 是否随包内置插件(id 在随包种子清单里,由 main 投影;renderer 不自判前缀 ——
   * 企业种子不带 `cindy-` 前缀)。批准态异常时 UI 据此换文案:随包插件由启动对账
   * 自动补批准,「重启应用即恢复」,不走人工重新确认。
   */
  builtin?: boolean;
  /** 插件详情页宿主角标所需的最小陈旧授权投影;不含账号或 scope 明细。 */
  oauthScopeStale?: {
    secretKey: string;
    missingScopeCount: number;
  };
  /** 插件列表所需的失效授权投影;不暴露账号身份或凭证内容。 */
  oauthAuthorizationExpired?: {
    expiredAccountCount: number;
  };
}

/**
 * 插件包的来源与审核等级;通常只决定 UI 徽标。保留的 gh-cli 凭证来源还会
 * 要求 cindy-github 具备 cindy-official Host receipt,防止第三方仅自报 id。
 */
export type GhostTrustLevel = 'cindy-official' | 'reviewed' | 'verified-publisher' | 'unverified';

export interface GhostTrustInfo {
  level: GhostTrustLevel;
  publisherSigned: boolean;
  publisherVerified: boolean;
  reviewed: boolean;
  publisherName?: string;
  publisherKeyId?: string;
  reviewerName?: string;
  /** 包含 review 声明但当前客户端不认识该审核 key,不因此抬高等级。 */
  unknownReviewer?: boolean;
}

/** Shared PC/mobile display label; only Host-owned trust facts affect this result. */
export function ghostTrustLabelKey(trust: GhostTrustInfo | undefined):
  'official' | 'reviewed' | 'verifiedPublisher' | 'signedUnverified' | 'unsigned' {
  return trust?.level === 'cindy-official' ? 'official'
    : trust?.level === 'reviewed' ? 'reviewed'
    : trust?.level === 'verified-publisher' ? 'verifiedPublisher'
    : trust?.publisherSigned ? 'signedUnverified' : 'unsigned';
}

/** 意识面板的 panelKind(布局树寻址用)。 */
// 返回类型收窄到模板字面量:右侧栏 TabKindId 含 `ghost:${string}` 分支,
// 调用方无需再 as 断言;对既有 string 消费方完全兼容。
export function ghostPanelKind(id: string): `ghost:${string}` {
  return `${GHOST_PANEL_KIND_PREFIX}${id}`;
}

/**
 * 意识的内容清单(2026-07-09 Lizi 定案:界面不显示档位/形态词,只如实
 * 描述"这段意识包含什么")。返回 i18n key 的后缀,消费方拼
 * `settings.ghosts.contents.<key>`;顺序即展示顺序(先看得见的,后能力)。
 */
export function ghostContentKeys(manifest: GhostManifest): string[] {
  const keys: string[] = [];
  if (manifest.mainView) keys.push('mainView');
  if (manifest.taskView) keys.push('taskView');
  if (manifest.panel) keys.push('panel');
  if (manifest.settingsHtml) keys.push('settingsUi');
  keys.push('code');
  if (manifest.cindy) keys.push('slotCindy');
  if (manifest.agent) keys.push('slotAgent');
  if (manifest.node) keys.push('slotNode');
  if (manifest.tools) keys.push('slotTool');
  if (manifest.subscribe) keys.push('slotSubscribe');
  if (manifest.card) keys.push('slotCard');
  if (manifest.network) keys.push('slotNetwork');
  if (manifest.notify === true) keys.push('slotNotify');
  if (manifest.badge === true) keys.push('slotBadge');
  if (manifest.confirm === true) keys.push('slotConfirm');
  if (manifest.fs === true) keys.push('slotFs');
  if (manifest.library === true) keys.push('slotLibrary');
  // skill 是信任面最高的内容(给主 Agent 灌指令),详情页必须如实露出。
  if (manifest.skill) keys.push('slotSkill');
  if (manifest.workspace === true) keys.push('slotWorkspace');
  return keys;
}

export function isValidGhostId(id: unknown): id is string {
  return typeof id === 'string' && GHOST_ID_RE.test(id);
}

/** New author ids must start with a letter. Installed legacy ids may start with a digit. */
const NEW_GHOST_ID_RE = /^[a-z][a-z0-9-]{0,31}$/;
export function isValidNewGhostId(id: unknown): id is string {
  return typeof id === 'string' && NEW_GHOST_ID_RE.test(id);
}

/**
 * 官方意识历史 id 前缀常量:`cindy-`。完整保留集合与用户装入通道判定以
 * `GHOST_OFFICIAL_ID_PREFIXES` 为准;官方市场可安装命中保留前缀的插件,
 * 用户装入通道(拖入/选文件/forge 转交/自定义市场)则在 packaged 版本上拒装
 * (dev 默认豁免,可用开发开关复现)。否则同 id 的第三方包可抢注官方身份,连带
 * 蹭走凭证别名(providerSecrets 的 GHOST_SECRET_STORAGE_ALIASES 按 id 生效,
 * 抢注者能拿到用户历史填过的机器级 key)。
 */
export const GHOST_OFFICIAL_ID_PREFIX = 'cindy-';

/**
 * 官方保留前缀全集(2026-07-13 起增补 `filo-`:filo-google 更名时脱离
 * cindy- 命名空间,防抢注保护必须跟着走;同日增补 `xd-`:xd-mivo 更名同因
 * ——官方密钥别名按 id 登记,前缀不保留会被第三方抢注蹭钥匙)。
 * 新增官方前缀在此登记。
 */
export const GHOST_OFFICIAL_ID_PREFIXES: readonly string[] = [
  GHOST_OFFICIAL_ID_PREFIX,
  'filo-',
  'xd-',
];

/** id 是否属于官方保留命名空间。静态命名空间与不可逆恢复能力继续用这个。 */
export function isOfficialGhostId(id: string): boolean {
  return GHOST_OFFICIAL_ID_PREFIXES.some((prefix) => id.startsWith(prefix));
}

/**
 * 用户装入通道(拖入 / 选文件 / forge 转交 / 自定义市场)是否拒装该 id。
 * 仅保留 Cindy 平台前缀;XD/Filo 名字可普通导入,运行时资格另验可信来源。
 */
export function isUserInstallReservedGhostId(id: string): boolean {
  return id.startsWith(GHOST_OFFICIAL_ID_PREFIX);
}

/**
 * 保留命名空间谓词,与 `isOfficialGhostId` 同口径。
 * **不是** tokenBroker 授权:运行时资格见 ghostFirstPartyPrivilege。
 */
export function isBrokerEligibleGhostId(id: string): boolean {
  return isOfficialGhostId(id);
}

/**
 * 保留命名空间谓词,与 `isOfficialGhostId` 同口径。
 * **不是** 宿主原语授权:端口回收 / 头像代下载见 ghostFirstPartyPrivilege。
 */
export function isFirstPartyHostPrivilegeGhostId(id: string): boolean {
  return isOfficialGhostId(id);
}

/**
 * Bundled Ghosts whose execution depends on Cindy account-plane services.
 *
 * Local app sessions may still use external Ghosts and direct/BYOK built-ins
 * (GitHub, GitLab, Google, web search, Mermaid). These entries are hidden and
 * rejected by the main process unless a verified cloud session is active.
 */
export const CINDY_ACCOUNT_GHOST_IDS: ReadonlySet<string> = new Set([
  'cindy-art',
  'xd-pages',
  'xd-feishu',
  'xd-atlassian',
  'xd-mivo',
]);

export function isCindyAccountGhostId(id: string): boolean {
  return CINDY_ACCOUNT_GHOST_IDS.has(id);
}

/**
 * 插件详情页的单项能力说明。
 * 纯数据描述:renderer 拼 `settings.ghosts.perm.<labelKey>` 翻译,`detail` 是
 * 作者自由文本(如工具描述)如实展示不翻译,`detailKey` 是主机固定说明的
 * i18n 后缀(如可执行代码的沙箱说明)——两者互斥。
 */
export interface GhostPermissionItem {
  /** 稳定键:更新 diff 按它对齐(内容变化视为移除+新增,如面板换边)。 */
  key: string;
  /** 图标分组(renderer 按 kind 选图标)。 */
  kind:
    | 'cindy'
    | 'agent'
    | 'node'
    | 'tool'
    | 'command'
    | 'panel'
    | 'main-view'
    | 'task-view'
    | 'code'
    | 'subscribe'
    | 'card'
    | 'network'
    | 'notify'
    | 'confirm'
    | 'fs'
    | 'library'
    | 'deviceSync'
    | 'session-context'
    | 'pick'
    | 'preview'
    | 'browser-extension'
    | 'skill'
    | 'workspace';
  /** i18n key 后缀,消费方拼 `settings.ghosts.perm.<labelKey>`。 */
  labelKey: string;
  /** i18n 插值参数(工具名、指令名、面板标题等)。 */
  labelArgs?: Record<string, string>;
  /** 作者自由文本补充(如实展示,不翻译)。 */
  detail?: string;
  /** 主机固定说明的 i18n key 后缀(拼法同 labelKey)。 */
  detailKey?: string;
  /**
   * detailKey 的 i18n 插值参数(与 labelArgs 分开:说明行里的插值是**主机
   * 政策数字**,如寄存字节上限,由常量单源注入,不让四份 locale 各写死一个
   * 数字。没有 detailArgs 的条目行为与从前逐字节相同)。
   */
  detailArgs?: Record<string, string>;
}

/** cindy 详单能力键 → 权限项 labelKey(新增类目/动作在此登记)。 */
const GHOST_CINDY_PERM_LABEL: Record<string, string> = {
  'image.generate': 'cindyImageGenerate',
  'image.edit': 'cindyImageEdit',
  'video.generate': 'cindyVideoGenerate',
  'video.edit': 'cindyVideoEdit',
  'media.deposit': 'cindyMediaDeposit',
  'text.oneshot': 'cindyTextOneshot',
  'embed.text': 'cindyEmbedText',
  'search.web': 'cindySearchWeb',
};

/**
 * cindy 详单能力键 → 主机固定补充说明的 labelKey(可选;没有条目就不带 detail)。
 * 寄存是唯一"写你的媒体库"的能力,上限必须在详情里如实写出来(媒体规则:
 * 能力说明要展示持久媒体占用上限)。
 */
const GHOST_CINDY_PERM_DETAIL: Record<string, string> = {
  'media.deposit': 'cindyMediaDepositDetail',
  'text.oneshot': 'cindyTextOneshotDetail',
  // 向量:用户要知道的是"文字会被送去算向量"(计费面)与"结果不落主机"
  // (向量归意识自己保管)。单次条数上限一并插值,同 deposit 的口径。
  'embed.text': 'cindyEmbedTextDetail',
  'search.web': 'cindySearchWebDetail',
};

/**
 * 字节 → 确认框里给用户看的容量(含单位)。整数向下取整,不给"511.99"这种数;
 * 整 GB 用 GB 表述(1GB 显示成"1024 MB"读起来像凑数)。单位跟着数字一起从
 * 常量算出来,locale 里只留 {{quota}} 占位 —— 否则上限改成 GB 量级时,四份
 * locale 里写死的 "MB" 就成了错的。
 */
function formatGhostQuotaSize(bytes: number): string {
  const mb = Math.floor(bytes / (1024 * 1024));
  if (mb >= 1024 && mb % 1024 === 0) return `${mb / 1024} GB`;
  return `${mb} MB`;
}

/**
 * 从身份卡静态推导插件详情使用的逐项能力说明。
 * 顺序即展示顺序:Cindy 代办 → 注册工具 → 聊天指令 → 面板 → 订阅/卡片 →
 * 可执行代码(先能力后载体,与权限展示契约一致)。
 */
/**
 * 权限投影的规范化指纹:两份 manifest「用户在确认卡上看到的权限内容」是否逐字
 * 相同的唯一判据。
 *
 * **只比 `key` 是不够的**:同一个 key 下还有会呈现给用户、并构成授权语义的字段 ——
 * `labelArgs`(preview 的 hosts、工具名等)、`detail`(作者自由文本,OAuth scopes /
 * node secret 绑定方式等都经它展示)、`detailKey`/`detailArgs`。市场确认拿服务端
 * 清单给用户看、拿下载包装入,两份清单在这些字段上不同而 key 相同时,用户看的是 A、
 * receipt 钉的是 B。字段序列化按固定字段序 + labelArgs/detailArgs 键排序,与对象
 * 构造顺序无关。
 */
function ghostPermissionProjectionTuple(item: GhostPermissionItem): unknown[] {
  const sortRecord = (record: Record<string, string> | undefined): [string, string][] =>
    Object.entries(record ?? {}).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
  return [
    item.key,
    item.kind,
    permissionLabelKeyForFingerprint(item),
    sortRecord(item.labelArgs),
    item.detail ?? null,
    permissionDetailKeyForFingerprint(item) || null,
    sortRecord(item.detailArgs),
  ];
}

export function ghostPermissionProjectionKey(item: GhostPermissionItem): string {
  return JSON.stringify(ghostPermissionProjectionTuple(item));
}

export function ghostPermissionProjectionFingerprint(manifest: GhostManifest): string {
  return JSON.stringify(
    ghostPermissionItems(manifest)
      .map(ghostPermissionProjectionTuple)
      .sort((a, b) => {
        const ka = JSON.stringify(a);
        const kb = JSON.stringify(b);
        return ka < kb ? -1 : ka > kb ? 1 : 0;
      }),
  );
}

/**
 * 插件是否声明了后台隐藏任务能力。只认 `tasks: true` + `hiddenTasks: true` 组合:
 * 已安装快照里不成对的历史值只作为未知数据保留,不授予(见 validateGhostManifestInput)。
 */
export function ghostDeclaresHiddenTasks(manifest: Pick<GhostManifest, 'agent'> | null | undefined): boolean {
  return manifest?.agent?.tasks === true && manifest.agent.hiddenTasks === true;
}

export function ghostPermissionItems(manifest: GhostManifest): GhostPermissionItem[] {
  const items: GhostPermissionItem[] = [];
  for (const [category, actions] of Object.entries(manifest.cindy ?? {})) {
    if (category === 'oneshotModel') continue; // 偏好模型是标量意图,不是能力键
    if (!Array.isArray(actions)) continue;
    for (const action of actions) {
      if (typeof action !== 'string') continue;
      const cap = `${category}.${action}`;
      const labelKey = GHOST_CINDY_PERM_LABEL[cap];
      // 快问快答声明了偏好模型:说明行换带模型的版本(装入即知情,成本透明)。
      const declaredOneshotModel =
        cap === 'text.oneshot' ? manifest.cindy?.oneshotModel : undefined;
      const detailKey = declaredOneshotModel
        ? 'cindyTextOneshotModelDetail'
        : GHOST_CINDY_PERM_DETAIL[cap];
      // 未知声明保留为数据;只有当前 Host 实现的能力才进入权限投影。
      if (labelKey) {
        items.push({
          key: `cindy:${cap}`,
          kind: 'cindy',
          labelKey,
          ...(detailKey ? { detailKey } : {}),
          // 寄存上限由常量单源插值进详情说明(媒体规则要求能力说明展示
          // 持久媒体占用上限);改常量四份 locale 自动跟随。
          ...(cap === 'media.deposit'
            ? { detailArgs: { quota: formatGhostQuotaSize(GHOST_CINDY_DEPOSIT_QUOTA_BYTES) } }
            : cap === 'embed.text'
              ? { detailArgs: { max: String(GHOST_CINDY_EMBED_MAX_TEXTS) } }
              : declaredOneshotModel
                ? { detailArgs: { model: declaredOneshotModel } }
                : {}),
        });
      }
    }
  }
  // network 槽:域名逐条列(用户要逐个看到"将访问谁"),凭证逐条列
  // (只有名字,值是用户自己后来填的)。排在 Cindy 代办之后、工具之前——
  // 出网是仅次于拦截钩子的敏感能力,不能沉底。
  for (const host of manifest.network?.hosts ?? []) {
    // 域名行不带逐行 detail(多域名时会重复刷屏);"经主机代发、仅限白名单"
    // 的总说明由 code 条目的 codeDetailNetwork 一次讲清。
    items.push({
      key: `network:host:${host}`,
      kind: 'network',
      labelKey: 'networkHost',
      labelArgs: { host },
    });
  }
  // agent 槽:真人点击触发是基础档;后台自动触发另列一项高风险权限。
  if (manifest.agent) {
    items.push({
      key: 'agent:user-action',
      kind: 'agent',
      labelKey: 'agentUserAction',
      detailKey: 'agentUserActionDetail',
    });
    if (manifest.agent?.background === true) {
      items.unshift({
        key: 'agent:background',
        kind: 'agent',
        labelKey: 'agentBackground',
        detailKey: 'agentBackgroundDetail',
      });
    }
    // 派活取件与 background 同级高风险,unshift 到清单上部单列——"能让
    // agent 替它干活并拿走结果"必须在装入前看得清清楚楚。
    if (manifest.agent?.errand === true) {
      items.unshift({
        key: 'agent:errand',
        kind: 'agent',
        labelKey: 'agentErrand',
        detailKey: 'agentErrandDetail',
      });
    }
    if (manifest.agent?.tasks === true) {
      items.unshift({ key: 'agent:tasks', kind: 'agent', labelKey: 'agentTasks', detailKey: 'agentTasksDetail' });
    }
    if (manifest.agent?.tasks === true && manifest.agent.targets === true) {
      items.unshift({ key: 'agent:targets', kind: 'agent', labelKey: 'agentTargets', detailKey: 'agentTargetsDetail' });
    }
    // 后台隐藏任务:独立 key 单列(理由同 schedule —— 并进 agent:tasks 会让更新里
    // 新增 hiddenTasks 时 added 为空,扩权复核拦不住)。排在 agent:tasks 之后。
    if (ghostDeclaresHiddenTasks(manifest)) {
      const tasksIndex = items.findIndex((item) => item.key === 'agent:tasks');
      items.splice(tasksIndex + 1, 0, {
        key: 'agent:hidden-tasks',
        kind: 'agent',
        labelKey: 'agentHiddenTasks',
        detailKey: 'agentHiddenTasksDetail',
      });
    }
    // 「可以请你新建自动化任务」:独立 key 单列一档。理由同 badge/errand ——
    // diffGhostPermissionItems 按 key + detail 比对,若并进任何既有 key,已装插件
    // 在更新里新增 schedule 时 added 为空,plugin-market 的扩权复核不会拦,用户会
    // 在毫不知情的情况下多给出一份"能反复弹自动化面板、且任务会烧模型额度"的能力。
    // 排在 background/errand 之下:它必须经用户在面板上亲手保存才生效,风险低半档。
    if (manifest.agent?.schedule === true) {
      items.push({
        key: 'agent:schedule',
        kind: 'agent',
        labelKey: 'agentSchedule',
        detailKey: 'agentScheduleDetail',
      });
    }
  }
  // Node 是本机用户级执行权,不与浏览器沙箱的 `code` 混称。基础执行与
  // 常驻分别列出,用户能看懂“能运行”与“会一直运行”是两件事。
  if (manifest.node) {
    items.unshift({
      key: 'node:execute',
      kind: 'node',
      labelKey: manifest.node.protocol === 'mcp-stdio' ? 'nodeMcp' : 'nodeRuntime',
      detailKey: 'nodeRuntimeDetail',
    });
    for (const binding of manifest.node.secretBindings ?? []) {
      const targetEntry = binding.entry ?? manifest.node.entry;
      const stableMethods = [...binding.methods].sort();
      items.unshift({
        key: `node:secret:${binding.key}:${targetEntry}:${stableMethods.join(',')}${binding.oauthSecret ? `:oauth:${binding.oauthSecret}` : ''}`,
        kind: 'node',
        labelKey: 'nodeSecret',
        labelArgs: { name: binding.label },
        detailKey: 'nodeSecretDetail',
        detail: [binding.oauthSecret ? `OAuth: ${binding.oauthSecret}` : '', ...binding.methods].filter(Boolean).join('\n'),
      });
    }
    if (manifest.node.lifecycle === 'resident') {
      items.unshift({
        key: 'node:resident',
        kind: 'node',
        labelKey: 'nodeResident',
        detailKey: 'nodeResidentDetail',
      });
    }
    // 代启子进程单列一行:执行权本质没变(仍限包内申报入口),但"会开几个
    // 进程"是用户该知道的事实。
    if (manifest.node.childSpawn === true) {
      items.unshift({
        key: 'node:child-spawn',
        kind: 'node',
        labelKey: 'nodeChildSpawn',
        detailKey: 'nodeChildSpawnDetail',
      });
    }
  }
  // skill 槽:技能指令由主 Agent 以用户全部权限执行、全项目生效、不受沙箱
  // 约束——信任面仅次于拦截钩子,逐条 unshift 到清单上部(倒序遍历保持声明
  // 顺序)。key 用 name 稳定对齐更新 diff;detail = 作者声明的 description
  // 原样展示(装入/打包校验已保证与 SKILL.md 逐字一致)。
  for (const skillItem of [...(manifest.skill?.items ?? [])].reverse()) {
    items.unshift({
      key: `skill:${skillItem.name}`,
      kind: 'skill',
      labelKey: 'skill',
      labelArgs: { name: skillItem.name },
      detailKey: 'skillDetail',
      detail: skillItem.description,
    });
  }
  // 多连接声明:逐条列"可连接你添加的 <连接类型>"——地址是用户后来自己加的
  // (且每次新增都过主机受信确认弹窗),装入时只能告知形态,不能列出具体域名。
  for (const conn of manifest.network?.connections ?? []) {
    items.push({
      key: `connections:${conn.key}`,
      kind: 'network',
      labelKey: 'networkConnections',
      labelArgs: { label: conn.label },
      detailKey: 'networkConnectionsDetail',
    });
  }
  for (const secret of manifest.network?.secrets ?? []) {
    // 来源分档文案:登录邮箱派生 vs 用户自填(意识 settingsHtml 收单——宿主
    // 凭证渲染已退役,user 凭证只剩这一档)。收单档文案不许说"意识代码无法
    // 读取"这种过头话:录入瞬间明文经过意识页面,知情同意面要如实。
    // user/login-email/oauth/gh-cli 保持历史 key,不影响存量插件;gh-cli
    // 只改变 Host 来源文案,不把“自动复用 gh”误报成新增权限确认。
    if (secret.source === 'oauth' && secret.oauth) {
      // OAuth 凭证:展示授权域名 + scopes 全量如实列出(通用声明式的知情
      // 同意面——平台不预设 provider,用户看到的就是全部授权事实)。detail
      // 用作者声明的 scope 原文,不翻译不加工。
      let authorizeHost = secret.oauth.authorizeUrl;
      try {
        authorizeHost = new URL(secret.oauth.authorizeUrl).hostname;
      } catch {
        /* 校验已保证合法,防御性兜底原文 */
      }
      items.push({
        key: `network:secret:${secret.key}`,
        kind: 'network',
        labelKey: 'networkSecretOauth',
        labelArgs: { name: secret.label, host: authorizeHost },
        detailKey: 'networkSecretOauthDetail',
        ...(secret.oauth.scopes && secret.oauth.scopes.length > 0
          ? { detail: secret.oauth.scopes.join('\n') }
          : {}),
      });
      continue;
    }
    if (secret.source === 'oidc-token') {
      items.push({
        key: `network:secret:${secret.key}:oidc-token`,
        kind: 'network',
        labelKey: 'networkSecretOrganizationIdentity',
        labelArgs: { name: secret.label },
        detailKey: 'networkSecretOrganizationIdentityDetail',
      });
      continue;
    }
    if (secret.source === 'gh-cli') {
      items.push({
        key: `network:secret:${secret.key}`,
        kind: 'network',
        labelKey: 'networkSecretGhCli',
        labelArgs: { name: secret.label },
        detailKey: 'networkSecretGhCliDetail',
      });
      continue;
    }
    const identity = secret.source === 'login-email';
    items.push({
      key: `network:secret:${secret.key}`,
      kind: 'network',
      labelKey: identity ? 'networkSecretIdentity' : 'networkSecret',
      labelArgs: { name: secret.label },
      detailKey: identity ? 'networkSecretIdentityDetail' : 'networkSecretGhostInputDetail',
    });
  }
  // fs 槽:写文件是仅次于出网的敏感能力,紧随 network 之后展示。三档目的地
  // 与确认规则由 detailKey 的固定说明一次讲清(私有目录免确认/工作目录跟随
  // 会话权限/其它目录逐次确认),让用户装入前就知道边界在哪。
  if (manifest.fs === true) {
    items.push({ key: 'fs', kind: 'fs', labelKey: 'fsWrite', detailKey: 'fsWriteDetail' });
  }
  // library 能力:持久作品库(用户数据语义,不是临时缓存)。详情页必须讲清
  // 卸载不删、删除走独立确认、会打开系统文件夹/另存为对话框,以及可把 PNG
  // 位图写入系统剪贴板(无确认框,会覆盖当前剪贴板)。
  if (manifest.deviceSync === true) {
    items.push({ key: 'deviceSync', kind: 'deviceSync', labelKey: 'deviceSync', detailKey: 'deviceSyncDetail' });
  }
  if (manifest.library === true) {
    items.push({
      key: 'library',
      kind: 'library',
      labelKey: 'libraryPersist',
      detailKey: 'libraryPersistDetail',
    });
  }
  // pick 槽:能弹系统选文件夹窗口。授权动作是用户亲手选中,装入时只告知
  // "它会来要"。
  if (manifest.pick === true) {
    items.push({ key: 'pick', kind: 'pick', labelKey: 'pick', detailKey: 'pickDetail' });
  }
  // workspace 槽:能为指定项目目录创建/复用侧边栏会话入口。授权动作是用户
  // 亲选目录或点确认卡,装入时只告知"它会来要"。
  if (manifest.workspace === true) {
    items.push({
      key: 'workspace',
      kind: 'workspace',
      labelKey: 'workspace',
      detailKey: 'workspaceDetail',
    });
  }
  // session-context 槽:派活时可获知当前会话的项目目录位置(路径信息,
  // 非文件访问权;node 槽的执行权另行单列)。
  if (manifest.sessionContext === true) {
    items.push({
      key: 'session-context',
      kind: 'session-context',
      labelKey: 'sessionContext',
      detailKey: 'sessionContextDetail',
    });
  }
  // preview 槽:白名单域名如实逐行列出(detail 原样展示作者声明,同 oauth
  // scopes 风格),用户装入前就看到"它能打开谁的页面"。
  if (manifest.preview) {
    items.push({
      key: 'preview',
      kind: 'preview',
      labelKey: 'preview',
      detailKey: 'previewDetail',
      detail: manifest.preview.hosts.join('\n'),
    });
  }
  // browserExtension 槽:允许连接的扩展 id 逐行列出;实现页面控制契约的扩展
  // 用单独说明告知用户「Agent 可经它操作你正在用的浏览器」。
  if (manifest.browserExtension) {
    items.push({
      key: 'browser-extension',
      kind: 'browser-extension',
      labelKey: 'browserExtension',
      detailKey: manifest.browserExtension.pageControl === true
        ? 'browserExtensionPageControlDetail'
        : 'browserExtensionDetail',
      detail: manifest.browserExtension.extensionIds.join('\n'),
    });
  }
  for (const tool of manifest.tools ?? []) {
    items.push({
      key: `tool:${tool.name}`,
      kind: 'tool',
      labelKey: 'tool',
      labelArgs: { name: tool.name },
      detail: tool.description,
    });
  }
  if (manifest.command) {
    items.push({
      key: `command:${manifest.command}`,
      kind: 'command',
      labelKey: 'command',
      labelArgs: { command: manifest.command },
    });
  }
  if (manifest.panel) {
    const position = manifest.panel.position ?? 'left';
    items.push({
      key: `panel:${position}`,
      kind: 'panel',
      labelKey: position === 'tab' ? 'panelTab' : 'panelLeft',
      labelArgs: { title: manifest.panel.title ?? manifest.name },
    });
  }
  if (manifest.mainView) {
    items.push({
      key: 'main-view',
      kind: 'main-view',
      labelKey: 'mainView',
      labelArgs: { title: manifest.mainView.title ?? manifest.name },
      detailKey: 'mainViewDetail',
    });
  }
  if (manifest.taskView) {
    items.push({
      key: 'task-view',
      kind: 'task-view',
      labelKey: 'taskView',
      labelArgs: { title: manifest.taskView.title ?? manifest.name },
      detailKey: 'taskViewDetail',
    });
  }
  if (manifest.routineEvents) {
    items.push({ key: 'routine-events', kind: 'subscribe', labelKey: 'routineEvents', detail: manifest.routineEvents.events.map((event) => `${event.name} (${event.type}: ${event.fields.join(", ")})`).join(', ') });
  }
  if (manifest.subscribe) {
      // 订阅两档分列:旁听(元数据)常规位;拦截是全部槽里权限最重的一档,
      // unshift 排到清单最顶(敏感项排最上)。
      const topics = manifest.subscribe?.topics;
      if (topics?.length) {
        // 旧 key 只在真订了 turn / session 时产出:纯 activity 插件不该在确认框里
        // 多出一行"旁听轮次与会话事件"——网关根本不给它投 turn / session,那行是凭空
        // 多报的能力,用户可能据此误拒。存量已批准插件必然含 turn 或 session(activity
        // 是本版新增),所以旧 key 对它们照旧产出,批准状态不 churn。
        if (topics.includes('turn') || topics.includes('session')) {
          items.push({ key: 'subscribe:topics', kind: 'subscribe', labelKey: 'subscribeTopics' });
        }
        // activity 单列一项(不并进 subscribe:topics):它暴露的是"用户此刻正被要求
        // 批准某个操作 / 正被问问题"的行为时序,比 turn / session 的统计元数据敏感
        // 一档,文案也要另讲。更要紧的是权限扩张检测——diffGhostPermissionItems 按
        // key + detail 比对,若 activity 并进固定的 subscribe:topics,已装插件从
        // topics:["turn"] 更新到 ["turn","activity"] 时 added 为空,plugin-market
        // 的复核就不会拦,用户会在毫不知情的情况下多给出审批时序。旧 key 保持原样,
        // 只声明 turn / session 的存量插件权限清单逐字不变(批准状态不 churn)。
        if (topics.includes('activity')) {
          items.push({
            key: 'subscribe:topics:activity',
            kind: 'subscribe',
            labelKey: 'subscribeActivity',
            detailKey: 'subscribeActivityDetail',
          });
        }
      }
      if (manifest.subscribe?.hooks?.length) {
        // 拦截钩按点分列(入口=改用户消息、出口=读并重渲 AI 回复,后者更敏感);
        // 整体 unshift 到清单最顶(拦截是全部槽里权限最重的一档),内部保持
        // 入口→出口顺序。will-user-message 沿用旧 key 'subscribe:hooks',老意识
        // 更新时 diff 不churn。
        const hookItems: GhostPermissionItem[] = [];
        if (manifest.subscribe.hooks.includes('will-user-message')) {
          hookItems.push({
            key: 'subscribe:hooks',
            kind: 'subscribe',
            labelKey: 'subscribeHooks',
            detailKey: 'subscribeHooksDetail',
          });
        }
        if (manifest.subscribe.hooks.includes('will-assistant-message')) {
          hookItems.push({
            key: 'subscribe:hooks:assistant',
            kind: 'subscribe',
            labelKey: 'subscribeAssistantReply',
            detailKey: 'subscribeAssistantReplyDetail',
          });
        }
        items.unshift(...hookItems);
      }
    // v2 有槽无详单已在归一化时丢弃,因此这里不存在零事件能力。
  }
  if (manifest.card) {
    items.push({ key: 'card', kind: 'card', labelKey: 'card' });
    if (manifest.card.externalLinks) {
      items.push({
        key: 'card:external-link',
        kind: 'card',
        labelKey: 'cardExternalLink',
        detailKey: 'cardExternalLinkDetail',
      });
    }
  }
  if (manifest.mail === true) {
    items.push({ key: 'mail', kind: 'card', labelKey: 'mail', detailKey: 'mailDetail' });
    const reader = parseMailReader(manifest.mailReader);
    if (reader) {
      items.push({ key: `mail-reader:${reader.tool}`, kind: 'card', labelKey: 'mailReader' });
      for (const host of reader.hosts) {
        items.push({ key: `mail-reader:host:${host}`, kind: 'preview',
          labelKey: 'mailReaderHost', labelArgs: { host } });
      }
      if (reader.markRead === true) {
        items.push({ key: 'mail-reader:mark-read', kind: 'card', labelKey: 'mailMarkRead' });
      }
    }
  }
  if (manifest.notify === true) {
    items.push({ key: 'notify', kind: 'notify', labelKey: 'notify', detailKey: 'notifyDetail' });
  }
  // 未读角标:与 notify 槽**并列**的独立一档(不是它的子项)——绿点比 toast 克制,
  // 只想安静点个绿点的意识不该被迫连"能弹全屏顶部提示"一起申请。
  // key 独立还有一层必要性(同 subscribe 的 activity topic 判例):
  // diffGhostPermissionItems 按 key + detail 比对,若并进某个固定 key,已装插件
  // 新增这一档时 added 为空,plugin-market 的扩权确认就不会拦——用户会在毫不
  // 知情的情况下多给出一个常驻的注意力入口。
  if (manifest.badge === true) {
    items.push({ key: 'badge', kind: 'notify', labelKey: 'badge', detailKey: 'badgeDetail' });
  }
  // confirm 槽:能请主机弹一个二选一确认框(会打断操作)。装入时如实告知"它会来问",
  // 决定权仍在用户的点击上——detailKey 的固定说明把这层讲清。
  if (manifest.confirm === true) {
    items.push({
      key: 'confirm',
      kind: 'confirm',
      labelKey: 'confirm',
      detailKey: 'confirmDetail',
    });
  }
  // 常驻模式如实告知(用户要背一个后台进程);on-demand 是默认行为,不列。
  if (manifest.launch === 'resident') {
    items.push({
      key: 'resident',
      kind: 'code',
      labelKey: 'resident',
      detailKey: 'residentDetail',
    });
  }
  // 可执行代码的沙箱说明分档:
  // - 有 node 槽时浏览器沙箱部分仍隔离,但不能再笼统说"无文件无网络"
  //   (Node 侧已摊过牌);
  // - 声明了 network 槽时不能宣称"无网络访问";
  // - 默认:纯沙箱、无文件无网络。
  let codeDetailKey: string;
  if (manifest.node) codeDetailKey = 'codeDetailWithNode';
  else if (manifest.network) codeDetailKey = 'codeDetailNetwork';
  else codeDetailKey = 'codeDetail';
  items.push({
    key: 'code',
    kind: 'code',
    labelKey: 'code',
    detailKey: codeDetailKey,
  });
  return items;
}

/** 更新确认框的权限 diff(按稳定 key 对齐;unchanged 保持新版条目)。 */
export interface GhostPermissionDiff {
  added: GhostPermissionItem[];
  removed: GhostPermissionItem[];
  unchanged: GhostPermissionItem[];
  /** 同一凭证槽的内置直连 OAuth clientId 发生变化。 */
  builtinOauthClientChanged: boolean;
}

/**
 * 返回同一插件内置直连 OAuth clientId 发生变化的凭证槽。
 * tokenBroker 可能按区域选择不同 clientId,仅凭 manifest 无法判断账号实际
 * 使用哪一个,因此不把 broker 默认值变化判成确定失效。
 */
export function changedBuiltinOauthClientSecretKeys(
  previousManifest: GhostManifest,
  currentManifest: GhostManifest,
): string[] {
  if (previousManifest.id !== currentManifest.id) return [];
  const previousSecrets = new Map(
    (previousManifest.network?.secrets ?? []).map((secret) => [secret.key, secret]),
  );
  const changed: string[] = [];
  for (const current of currentManifest.network?.secrets ?? []) {
    if (current.source !== 'oauth' || !current.oauth) continue;
    const previous = previousSecrets.get(current.key);
    if (previous?.source !== 'oauth' || !previous.oauth) continue;
    if (current.oauth.tokenBroker || previous.oauth.tokenBroker) continue;
    const previousClientId = previous.oauth.clientId?.trim() || null;
    const currentClientId = current.oauth.clientId?.trim() || null;
    // 旧版没有内置 clientId 时,存量账号只能来自用户自定义配置;新增默认值
    // 不会让这些令牌失效。只有旧内置客户端真实存在时才属于迁移。
    if (previousClientId !== null && previousClientId !== currentClientId) {
      changed.push(current.key);
    }
  }
  return changed;
}

/**
 * 权限审阅基线指纹:同一份 manifest 推导出的完整用户可见权限投影。
 * 与 diffGhostPermissionItems 同口径(按稳定 key 对齐、任一展示字段变化算差异),
 * 权限条目指纹:key + 作者自由文本 detail + 主机固定说明(detailKey + detailArgs,
 * args 按键序稳定化)。detailKey/detailArgs 必须在内:同一 key 的固定说明会随
 * 声明变化(cindy text.oneshot 声明 oneshotModel、network secret 的 identity
 * 形态),只看 key+detail 会把"说明/成本面变了"漏判成"权限面没变",更新时
 * 用户看不到重新确认。
 */
function isGithubCredentialCompatibilityItem(item: GhostPermissionItem): boolean {
  return (
    item.key === 'network:secret:github_pat' &&
    (item.detailKey === 'networkSecretGhostInputDetail' ||
      item.detailKey === 'networkSecretGhCliDetail')
  );
}

function permissionLabelKeyForFingerprint(item: GhostPermissionItem): string {
  if (
    isGithubCredentialCompatibilityItem(item) &&
    (item.labelKey === 'networkSecret' || item.labelKey === 'networkSecretGhCli')
  ) {
    return 'networkSecretGithubCredential';
  }
  return item.labelKey;
}

function permissionDetailKeyForFingerprint(item: GhostPermissionItem): string {
  // cindy-github 从存量 PAT(source:user)升级为 Host 优先 gh-cli 时,凭证仍由
  // Main 只注入同一个 network secret key 与同一组目标;变化的是设置页/权限
  // 页对“凭证从哪里来”的说明,不是插件获得了新权限。两档共用历史 key 的
  // 同时也必须共用审阅指纹,否则升级会被误判成扩权并要求存量用户重新确认。
  // gh-cli 的 manifest 校验只允许官方 cindy-github,因此这个兼容等价不会
  // 放宽其它插件;其它 detailKey/detailArgs 变化仍按新说明完整性规则复核。
  if (isGithubCredentialCompatibilityItem(item)) {
    return 'networkSecretGithubCredentialDetail';
  }
  return item.detailKey ?? '';
}

/**
 * 权限审阅基线指纹:同一份 manifest 推导出的权限条目集合(条目指纹见上)。
 * 与 diffGhostPermissionItems 同口径(按 key 对齐、指纹变化算差异),
 * 所以"指纹相同"等价于"权限面没变",可安全沿用先前的审阅结论。
 *
 * renderer 审阅时记录基线并随安装请求回传,main 在安装锁内用**当前**已装
 * manifest 重算比对——两侧必须用同一个实现,否则复核形同虚设,故住在 shared。
 * 每项 JSON 编码后排序拼接,全可打印、无拼接歧义。
 */
export function ghostPermissionBaselineKey(manifest: GhostManifest): string {
  return ghostPermissionProjectionFingerprint(manifest);
}

export function diffGhostPermissionItems(
  prev: GhostManifest,
  next: GhostManifest,
): GhostPermissionDiff {
  const prevItems = ghostPermissionItems(prev);
  const nextItems = ghostPermissionItems(next);
  const prevKeys = new Set(prevItems.map((i) => i.key));
  const nextKeys = new Set(nextItems.map((i) => i.key));
  const prevProjectionByKey = new Map(
    prevItems.map((item) => [item.key, ghostPermissionProjectionKey(item)]),
  );
  const nextProjectionByKey = new Map(
    nextItems.map((item) => [item.key, ghostPermissionProjectionKey(item)]),
  );
  const added: GhostPermissionItem[] = [];
  const removed: GhostPermissionItem[] = [];
  const unchanged: GhostPermissionItem[] = [];
  for (const item of nextItems) {
    if (!prevKeys.has(item.key)) {
      added.push(item);
    } else if (ghostPermissionProjectionKey(item) !== prevProjectionByKey.get(item.key)) {
      added.push(item);
    } else {
      unchanged.push(item);
    }
  }
  for (const item of prevItems) {
    if (!nextKeys.has(item.key)) {
      removed.push(item);
    } else if (ghostPermissionProjectionKey(item) !== nextProjectionByKey.get(item.key)) {
      removed.push(item);
    }
  }
  return {
    added,
    removed,
    unchanged,
    builtinOauthClientChanged: changedBuiltinOauthClientSecretKeys(prev, next).length > 0,
  };
}

/**
 * Compare an installed Plugin with a candidate package without trusting a
 * mutable live manifest. Legacy or invalid installs have no approved baseline,
 * so every permission in the candidate must be reviewed as newly requested.
 */
export function diffInstalledGhostPermissionItems(
  installed: InstalledGhost,
  next: GhostManifest,
): GhostPermissionDiff {
  if (installed.approval.state === 'approved') {
    return diffGhostPermissionItems(installed.manifest, next);
  }
  return {
    added: ghostPermissionItems(next),
    removed: [],
    unchanged: [],
    // Legacy/invalid installs have no approved old manifest from which a
    // builtin client transition can be proven. Their complete permission set
    // is already forced through review via `added` above.
    builtinOauthClientChanged: false,
  };
}

function ghostOauthAuthorizationWithinCap(
  reviewed: GhostSecretOauthDecl,
  actual: GhostSecretOauthDecl,
): boolean {
  const { scopes: reviewedScopes, ...reviewedBase } = reviewed;
  const { scopes: actualScopes, ...actualBase } = actual;
  return (
    JSON.stringify(actualBase) === JSON.stringify(reviewedBase) &&
    (actualScopes ?? []).every((scope) => (reviewedScopes ?? []).includes(scope))
  );
}

function ghostOauthPermissionWithinCap(
  reviewed: GhostManifest,
  actual: GhostManifest,
  item: GhostPermissionItem,
): boolean {
  const actualSecret = actual.network?.secrets?.find(
    (secret) => `network:secret:${secret.key}` === item.key,
  );
  if (actualSecret?.source !== 'oauth' || !actualSecret.oauth) return false;
  const reviewedSecret = reviewed.network?.secrets?.find(
    (secret) => secret.key === actualSecret.key,
  );
  return (
    reviewedSecret?.source === 'oauth' &&
    reviewedSecret.oauth !== undefined &&
    actualSecret.label === reviewedSecret.label &&
    ghostOauthAuthorizationWithinCap(reviewedSecret.oauth, actualSecret.oauth)
  );
}

/** 市场清单对 Agent 可见工具参数 schema 的上限;对象键顺序不影响规范值。 */
export function ghostToolParametersWithinCap(
  reviewed: GhostManifest,
  actual: GhostManifest,
): boolean {
  const reviewedTools = new Map((reviewed.tools ?? []).map((tool) => [tool.name, tool]));
  return (actual.tools ?? []).every((tool) => {
    const cap = reviewedTools.get(tool.name);
    return (
      cap !== undefined &&
      canonicalGhostExtensionValue(tool.parameters) ===
        canonicalGhostExtensionValue(cap.parameters)
    );
  });
}

/** 返回真实包中超出市场声明与既有安装基线的 Host 能力。 */
export function unreviewedGhostPermissionItems(
  reviewed: GhostManifest,
  previouslyInstalled: GhostManifest | undefined,
  actual: GhostManifest,
): GhostPermissionItem[] {
  const reviewedItems = ghostPermissionItems(reviewed);
  const previousItems = ghostPermissionItems(previouslyInstalled ?? reviewed);
  const approved = new Set(reviewedItems.map(ghostPermissionProjectionKey));
  const approvedKeys = new Set(reviewedItems.map((item) => item.key));
  for (const item of previousItems) {
    approved.add(ghostPermissionProjectionKey(item));
    approvedKeys.add(item.key);
  }
  const previewWithinCap = (cap: GhostManifest): boolean => {
    if (actual.preview === undefined) return true;
    if (cap.preview === undefined) return false;
    const reviewedHosts = cap.preview.hosts;
    return actual.preview.hosts.every((actualPattern) =>
      reviewedHosts.some((reviewedPattern) =>
        ghostNetworkHostPatternWithinCap(actualPattern, reviewedPattern),
      ),
    );
  };
  const previewApproved =
    previewWithinCap(reviewed) ||
    (previouslyInstalled !== undefined && previewWithinCap(previouslyInstalled));
  const browserExtensionApproved =
    ghostBrowserExtensionWithinCap(reviewed, actual) ||
    (previouslyInstalled !== undefined && ghostBrowserExtensionWithinCap(previouslyInstalled, actual));
  const nodeSecretsApproved =
    ghostNodeSecretAuthorizationWithinCap(reviewed, actual) ||
    (previouslyInstalled !== undefined &&
      ghostNodeSecretAuthorizationWithinCap(previouslyInstalled, actual));
  const networkHostApproved = (item: GhostPermissionItem): boolean => {
    if (!item.key.startsWith('network:host:')) return false;
    const actualPattern = item.key.slice('network:host:'.length);
    return [reviewed, previouslyInstalled].some((cap) =>
      cap?.network?.hosts.some((reviewedPattern) =>
        ghostNetworkHostPatternWithinCap(actualPattern, reviewedPattern),
      ),
    );
  };
  const oauthPermissionApproved = (item: GhostPermissionItem): boolean =>
    ghostOauthPermissionWithinCap(reviewed, actual, item) ||
    (previouslyInstalled !== undefined &&
      ghostOauthPermissionWithinCap(previouslyInstalled, actual, item));
  return ghostPermissionItems(actual).filter(
    (item) =>
      !approved.has(ghostPermissionProjectionKey(item)) &&
      // code 的 detailKey 只是在复述已单列的 network/node 等能力。实际包少一项
      // 能力时文案会降档,但不能因此把“更少能力”反判为扩权。
      !(item.key === 'code' && approvedKeys.has(item.key)) &&
      // preview 的展示 detail 包含完整 hosts;真实包删减 host 是收权,不应因
      // detail 字符串变化被反判成新增能力。新增或替换 host 仍会保留为未审查项。
      !(item.key === 'preview' && previewApproved) &&
      // browserExtension 的展示 detail 是完整 id 清单;删减 id、去掉页面控制或
      // 去掉 native host 都是收权,新增 id、新增页面控制仍保留为未审查项。
      !(item.key === 'browser-extension' && browserExtensionApproved) &&
      // Network host 的展示 key 带声明模式;通配域收窄为具体域或更窄通配域
      // 仍是收权,实际覆盖关系由专用上限比较守住。
      !networkHostApproved(item) &&
      // Node secret 的展示 key 带完整 methods;换序或收窄是收权。URL/hint 与
      // entry 等 Host 实际消费字段由专用上限比较守住,不能依赖展示投影相等。
      !(item.key.startsWith('node:secret:') && nodeSecretsApproved) &&
      // OAuth 展示 detail 带完整 scopes;换序或收窄同样是收权。其余 OAuth
      // 参数、凭证标签与注入语义仍由专用上限和完整投影逐项钉住。
      !oauthPermissionApproved(item),
  );
}

/**
 * 市场清单对浏览器扩展能力的授权上限:真实包的扩展 id 必须是已审查清单的子集,
 * 页面控制与 native host 只能收窄不能新增(binary 路径是包内安装细节,不算权限)。
 */
export function ghostBrowserExtensionWithinCap(
  reviewed: GhostManifest,
  actual: GhostManifest,
): boolean {
  const actualNeeds = actual.browserExtension;
  if (actualNeeds === undefined) return true;
  const cap = reviewed.browserExtension;
  if (cap === undefined) return false;
  if (!actualNeeds.extensionIds.every((id) => cap.extensionIds.includes(id))) return false;
  if (actualNeeds.pageControl === true && cap.pageControl !== true) return false;
  if (actualNeeds.nativeHost !== undefined && cap.nativeHost?.name !== actualNeeds.nativeHost.name) {
    return false;
  }
  // Members this Host does not interpret ride along on the declaration. A later Host that starts to read
  // one must not find it already approved: every such member has to be in the reviewed declaration too.
  const unknownWithinCap = (actualObject: object, capObject: object, known: readonly string[]): boolean => {
    for (const [key, value] of Object.entries(actualObject)) {
      if (known.includes(key)) continue;
      if (
        !Object.prototype.hasOwnProperty.call(capObject, key) ||
        canonicalGhostExtensionValue(value) !==
          canonicalGhostExtensionValue((capObject as Record<string, unknown>)[key])
      ) {
        return false;
      }
    }
    return true;
  };
  if (
    actualNeeds.nativeHost !== undefined &&
    cap.nativeHost !== undefined &&
    !unknownWithinCap(actualNeeds.nativeHost, cap.nativeHost, ['name', 'binary'])
  ) {
    return false;
  }
  return unknownWithinCap(actualNeeds, cap, [
    'protocol',
    'extensionIds',
    'nativeHost',
    'pageControl',
    'pageControlReplaces',
  ]);
}

/** 市场清单对 Node Worker 凭证注入与配置引导的授权上限。 */
export function ghostNodeSecretAuthorizationWithinCap(
  reviewed: GhostManifest,
  actual: GhostManifest,
): boolean {
  const actualBindings = actual.node?.secretBindings ?? [];
  if (actualBindings.length === 0) return true;
  const reviewedNode = reviewed.node;
  if (!reviewedNode) return false;
  const reviewedBindings = reviewedNode.secretBindings ?? [];
  for (const binding of actualBindings) {
    const targetEntry = binding.entry ?? actual.node?.entry;
    const cap = reviewedBindings.find(
      (candidate) =>
        candidate.key === binding.key &&
        (candidate.entry ?? reviewedNode.entry) === targetEntry,
    );
    if (
      !cap ||
      binding.oauthSecret !== cap.oauthSecret ||
      binding.label !== cap.label ||
      !binding.methods.every((method) => cap.methods.includes(method))
    ) {
      return false;
    }
    if (binding.url !== undefined && binding.url !== cap.url) return false;
    if (binding.hint !== undefined && binding.hint !== cap.hint) return false;
  }
  return true;
}

/** 市场清单对真实包设置 WebView 暴露面的授权上限。 */
export function ghostSettingsUiWithinCap(
  reviewed: GhostManifest,
  actual: GhostManifest,
): boolean {
  if (actual.settingsHtml === undefined) return true;
  if (reviewed.settingsHtml === undefined) return false;
  if (actual.settingsHeight === undefined) return reviewed.settingsHeight === undefined;
  if (reviewed.settingsHeight === undefined) return true;
  return actual.settingsHeight <= reviewed.settingsHeight;
}

/**
 * 市场清单对真实包的 network 授权语义上限。
 *
 * `ghostPermissionItems` 是给人看的能力投影,不能作为凭证流向的安全判据:
 * 同一 secret 改写 inject.hosts、header、exchange 或 OAuth 目标时,展示项可能
 * 完全相同。这里单独比较 Host 真正消费的字段;允许真实包少声明 host/secret/
 * connection,但不能扩大任何一项。
 */
export function ghostNetworkAuthorizationWithinCap(
  reviewed: GhostManifest,
  actual: GhostManifest,
): boolean {
  const actualNetwork = actual.network;
  if (!actualNetwork) return true;
  const reviewedNetwork = reviewed.network;
  if (!reviewedNetwork) return false;

  const isHostPatternSubset = (values: readonly string[], cap: readonly string[]): boolean =>
    values.every((value) =>
      cap.some((reviewedPattern) => ghostNetworkHostPatternWithinCap(value, reviewedPattern)),
    );
  if (!isHostPatternSubset(actualNetwork.hosts, reviewedNetwork.hosts)) return false;

  const reviewedSecrets = new Map(
    (reviewedNetwork.secrets ?? []).map((secret) => [secret.key, secret] as const),
  );
  for (const secret of actualNetwork.secrets ?? []) {
    const cap = reviewedSecrets.get(secret.key);
    if (!cap || (secret.source ?? 'user') !== (cap.source ?? 'user')) return false;
    if (secret.inject.header !== cap.inject.header || secret.inject.format !== cap.inject.format) {
      return false;
    }
    const actualHosts = secret.inject.hosts ?? actualNetwork.hosts;
    const reviewedHosts = cap.inject.hosts ?? reviewedNetwork.hosts;
    if (!isHostPatternSubset(actualHosts, reviewedHosts)) return false;
    if (secret.url !== undefined && secret.url !== cap.url) return false;
    if (secret.hint !== undefined && secret.hint !== cap.hint) return false;
    if (
      secret.exchange !== undefined &&
      JSON.stringify(secret.exchange) !== JSON.stringify(cap.exchange)
    ) {
      return false;
    }
    if (secret.check !== undefined && JSON.stringify(secret.check) !== JSON.stringify(cap.check)) return false;
    if (secret.oauth !== undefined) {
      if (!cap.oauth || !ghostOauthAuthorizationWithinCap(cap.oauth, secret.oauth)) return false;
    }
  }

  const reviewedConnections = new Map(
    (reviewedNetwork.connections ?? []).map((connection) => [connection.key, connection] as const),
  );
  for (const connection of actualNetwork.connections ?? []) {
    const cap = reviewedConnections.get(connection.key);
    if (!cap) return false;
    if (
      connection.inject.header !== cap.inject.header ||
      connection.inject.format !== cap.inject.format ||
      (connection.maxConnections ?? GHOST_NETWORK_MAX_CONNECTIONS_PER_DECL) >
        (cap.maxConnections ?? GHOST_NETWORK_MAX_CONNECTIONS_PER_DECL)
    ) {
      return false;
    }
  }
  return true;
}

/** 市场清单对真实包的订阅事件授权上限;具体 topic/hook 只能保持或收缩。 */
export function ghostSubscribeAuthorizationWithinCap(
  reviewed: GhostManifest,
  actual: GhostManifest,
): boolean {
  const actualSubscribe = actual.subscribe;
  if (!actualSubscribe) return true;
  const reviewedSubscribe = reviewed.subscribe;
  if (!reviewedSubscribe) return false;
  return (
    (actualSubscribe.topics ?? []).every((topic) =>
      (reviewedSubscribe.topics ?? []).includes(topic),
    ) &&
    (actualSubscribe.hooks ?? []).every((hook) =>
      (reviewedSubscribe.hooks ?? []).includes(hook),
    )
  );
}

function ghostSetupGroupCapKey(group: GhostSetupGroup): string {
  return group.anyOf
    .map((requirement) =>
      requirement.kind === 'kv'
        ? `kv:${requirement.key}:${JSON.stringify(requirement.label)}`
        : `${requirement.kind}:${requirement.key}`,
    )
    .sort()
    .join('\0');
}

/**
 * 市场清单对真实包 setup 运行门的上限。
 *
 * 两边都未显式声明时继续采用 Host 启发式;其引用只能来自已经单独受限的
 * network/node 声明。市场未声明时,真实包只能显式 opt-out;市场已经声明时,
 * 真实包只能删除完整需求组,不能退回启发式、增加组、收紧 anyOf,或换入新的
 * 引用/kv 文案。
 */
export function ghostSetupAuthorizationWithinCap(
  reviewed: GhostManifest,
  actual: GhostManifest,
): boolean {
  if (reviewed.setup === undefined && actual.setup === undefined) return true;
  if (reviewed.setup === undefined) return actual.setup?.requires.length === 0;
  if (actual.setup === undefined) return false;

  const reviewedGroups = reviewed.setup.requires;
  const actualGroups = actual.setup.requires;
  const remainingReviewed = reviewedGroups.map(ghostSetupGroupCapKey);
  for (const group of actualGroups) {
    const key = ghostSetupGroupCapKey(group);
    const index = remainingReviewed.indexOf(key);
    if (index < 0) return false;
    remainingReviewed.splice(index, 1);
  }
  return true;
}

function canonicalGhostExtensionValue(value: unknown): string {
  if (Array.isArray(value)) {
    return `[${value.map(canonicalGhostExtensionValue).join(',')}]`;
  }
  if (isPlainObject(value)) {
    return `{${Object.entries(value)
      .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
      .map(([key, item]) => `${JSON.stringify(key)}:${canonicalGhostExtensionValue(item)}`)
      .join(',')}}`;
  }
  return JSON.stringify(value) ?? 'null';
}

/** v3 前向兼容字段可以被旧 Host 保留,但真实包不能超出市场清单声明。 */
export function ghostUnknownV3FieldsWithinCap(
  reviewed: GhostManifest,
  actual: GhostManifest,
): boolean {
  if (actual.schemaVersion !== 3) return true;
  return Object.entries(actual)
    .filter(
      ([key]) => key === 'model' || !GHOST_MANIFEST_KNOWN_TOP_LEVEL_FIELDS.has(key),
    )
    .every(
      ([key, value]) =>
        Object.prototype.hasOwnProperty.call(reviewed, key) &&
        canonicalGhostExtensionValue(value) ===
          canonicalGhostExtensionValue((reviewed as Record<string, unknown>)[key]),
    );
}

/**
 * icon 允许的图片扩展名 → mime(校验与 main 读盘供图共用同一口径)。
 * 不收 svg:svg 可携带脚本,虽经 <img> 渲染不执行,仍不给这个面。
 */
const GHOST_ICON_MIME_BY_EXT: Record<string, string> = {
  '.png': 'image/png',
  '.jpg': 'image/jpeg',
  '.jpeg': 'image/jpeg',
  '.webp': 'image/webp',
  '.gif': 'image/gif',
};

/**
 * icon 字节上限。icon 会以 data URL 形态同步下发给 Renderer,因此安装、
 * 本地读取与 Forge overlay 必须共用同一硬顶,避免“能打包但不能安装”。
 */
export const GHOST_ICON_MAX_BYTES = 512 * 1024;

/** icon 路径 → mime;扩展名不在白名单返回 null(即校验不通过)。 */
export function ghostIconMimeType(p: string): string | null {
  const dot = p.lastIndexOf('.');
  if (dot < 0) return null;
  return GHOST_ICON_MIME_BY_EXT[p.slice(dot).toLowerCase()] ?? null;
}

/**
 * 校验"安装目录内相对路径"(entry / panel.html / settingsHtml 共用):
 * 只允许 `a/b/c.ext` 形态——正斜杠分段、无盘符、无反斜杠、无空段、
 * 无 `.`/`..` 段、字符集收敛,天然杜绝路径穿越与跨平台歧义。
 */
const GHOST_PATH_SEGMENT_RE = /^[a-zA-Z0-9_][a-zA-Z0-9._-]{0,63}$/;
export function isSafeGhostRelativePath(p: unknown): p is string {
  if (typeof p !== 'string' || p.length === 0 || p.length > 256) return false;
  if (p.includes('\\')) return false;
  const segments = p.split('/');
  return segments.every((seg) => GHOST_PATH_SEGMENT_RE.test(seg) && seg !== '.' && seg !== '..');
}

const WINDOWS_RESERVED_GHOST_PATH_SEGMENT_RE =
  /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\..*)?$/i;

/**
 * New cross-platform manifest paths must also be creatable on Windows.
 * Keep the legacy helper above unchanged so an upgrade does not invalidate
 * already-installed plugins that were previously accepted on macOS.
 */
function isPortableGhostRelativePath(p: unknown): p is string {
  return (
    isSafeGhostRelativePath(p) &&
    p.split('/').every((segment) => !WINDOWS_RESERVED_GHOST_PATH_SEGMENT_RE.test(segment))
  );
}

/**
 * 意识 webview 允许附加的入口 pathname 白名单(attach 闸的可测真身):
 * 面板 panel.html、主视图 mainView.html、任务页 taskView.html 与设置区 settingsHtml,声明哪个放行哪个;
 * 多个能力指向同一
 * 文件时去重。空数组 = 该意识没有任何可附加的自绘界面,闸口一律拒。
 */
export function ghostWebviewEntryPaths(manifest: GhostManifest): string[] {
  const paths: string[] = [];
  if (manifest.panel?.html) paths.push(`/${manifest.panel.html}`);
  if (manifest.mainView?.html) {
    const p = `/${manifest.mainView.html}`;
    if (!paths.includes(p)) paths.push(p);
  }
  if (manifest.taskView?.html) {
    const p = `/${manifest.taskView.html}`;
    if (!paths.includes(p)) paths.push(p);
  }
  if (manifest.settingsHtml) {
    const p = `/${manifest.settingsHtml}`;
    if (!paths.includes(p)) paths.push(p);
  }
  return paths;
}

export type ManifestValidation =
  | { ok: true; manifest: GhostManifest; unsupportedLegacySlots: string[] }
  | { ok: false; reason: string };

const GHOST_MANIFEST_RESERVED_RECORD_KEYS = new Set(['__proto__', 'constructor', 'prototype']);

function isGhostManifestReservedRecordKey(value: string): boolean {
  return GHOST_MANIFEST_RESERVED_RECORD_KEYS.has(value);
}

/** Preserve future declaration data without turning it into implemented Host permissions. */
function unknownDeclarationFields(raw: Record<string, unknown>, known: readonly string[]): Record<string, unknown> {
  return Object.fromEntries(Object.entries(raw).filter(([key]) => !known.includes(key)));
}

function isPlainObject(v: unknown): v is Record<string, unknown> {
  return typeof v === 'object' && v !== null && !Array.isArray(v);
}

const GHOST_MANIFEST_KNOWN_TOP_LEVEL_FIELDS = new Set([
  'routineEvents',
  'schemaVersion',
  'id',
  'name',
  'version',
  'releaseNotes',
  'minCindyVersion',
  'author',
  'locales',
  'resolvedLocale',
  'description',
  'whenToUse',
  'icon',
  'kind',
  'entry',
  'launch',
  'agent',
  'node',
  'settingsHtml',
  'settingsHeight',
  'showTaskPreferences',
  'slots',
  'card',
  'mail',
  'mailReader',
  'tools',
  'cindy',
  'model',
  'subscribe',
  'network',
  'preview',
  'skill',
  'setup',
  'command',
  'keywords',
  'panel',
  'mainView',
  'taskView',
  'notify',
  'badge',
  'confirm',
  'fs',
  'library',
  'deviceSync',
  'sessionContext',
  'pick',
  'workspace',
  'iosSimulator',
  // Interpreted by Host: ghostBrowserExtensionWithinCap checks it against the reviewed manifest
  // (narrowing is allowed), so it must not also fall under the exact-match rule for unknown fields.
  'browserExtension',
]);

const V3_BOOLEAN_CAPABILITY_FIELDS = [
  'notify',
  'badge',
  'confirm',
  'fs',
  'library',
  'deviceSync',
  'sessionContext',
  'pick',
  'workspace',
  'iosSimulator',
] as const;

const V3_DECLARATION_TO_LEGACY_SLOT = [
  ['tools', 'tool'],
  ['card', 'card'],
  ['panel', 'panel'],
  ['mainView', 'main-view'],
  ['taskView', 'task-view'],
  ['subscribe', 'subscribe'],
  ['skill', 'skill'],
  ['cindy', 'cindy'],
  ['agent', 'agent'],
  ['node', 'node'],
  ['network', 'network'],
  ['preview', 'preview'],
] as const;

const V3_BOOLEAN_TO_LEGACY_SLOT: Record<(typeof V3_BOOLEAN_CAPABILITY_FIELDS)[number], string> = {
  notify: 'notify',
  badge: 'badge',
  confirm: 'confirm',
  fs: 'fs',
  library: 'library',
  deviceSync: 'device-sync',
  sessionContext: 'session-context',
  pick: 'pick',
  workspace: 'workspace',
  iosSimulator: 'ios-simulator',
};

type PreparedGhostManifest = {
  raw: Record<string, unknown>;
  schemaVersion: 2 | 3;
  unsupportedLegacySlots: string[];
  v3BaseCard: boolean;
  v3BaseAgent: boolean;
  unknownV3Fields: Record<string, unknown>;
};

function prepareGhostManifestForValidation(
  value: unknown,
): { ok: true; prepared: PreparedGhostManifest } | { ok: false; reason: string } {
  if (!isPlainObject(value)) return { ok: false, reason: '清单不是对象' };
  if (value.schemaVersion !== 2 && value.schemaVersion !== 3) {
    return {
      ok: false,
      reason: `schemaVersion 必须是 2 或 3,得到 ${JSON.stringify(value.schemaVersion)}(v1 声明型已于 2026-07-12 移除)`,
    };
  }

  if (value.schemaVersion === 2) {
    const sourceSlots = Array.isArray(value.slots) ? value.slots : [];
    const unsupportedLegacySlots = sourceSlots.flatMap((slot) => {
      const normalized = slot === 'model' ? 'cindy' : slot;
      return typeof normalized === 'string'
        && !(LEGACY_GHOST_SLOTS as readonly string[]).includes(normalized)
        ? [normalized]
        : [];
    });
    return {
      ok: true,
      prepared: {
        raw: Array.isArray(value.slots)
          ? { ...value, slots: dropEmptyLegacyCapabilitySlots(value, sourceSlots) }
          : value,
        schemaVersion: 2,
        unsupportedLegacySlots,
        v3BaseCard: false,
        v3BaseAgent: false,
        unknownV3Fields: {},
      },
    };
  }

  if (value.slots !== undefined) {
    return { ok: false, reason: 'schemaVersion 3 不再支持 slots;请直接声明对应能力字段' };
  }
  if (value.minCindyVersion === undefined) {
    return { ok: false, reason: 'schemaVersion 3 必须声明 minCindyVersion' };
  }
  for (const field of V3_BOOLEAN_CAPABILITY_FIELDS) {
    if (value[field] !== undefined && value[field] !== true) {
      return { ok: false, reason: `${field} 出现时必须是 true;不需要时请省略` };
    }
  }

  const syntheticSlots: string[] = [];
  for (const [field, slot] of V3_DECLARATION_TO_LEGACY_SLOT) {
    if (value[field] !== undefined) syntheticSlots.push(slot);
  }
  for (const field of V3_BOOLEAN_CAPABILITY_FIELDS) {
    if (value[field] === true) syntheticSlots.push(V3_BOOLEAN_TO_LEGACY_SLOT[field]);
  }
  const v3BaseCard = isPlainObject(value.card) && Object.keys(value.card).length === 0;
  const v3BaseAgent = isPlainObject(value.agent) && Object.keys(value.agent).length === 0;
  const raw: Record<string, unknown> = {
    ...value,
    slots: syntheticSlots,
    ...(v3BaseCard ? { card: undefined } : {}),
    ...(v3BaseAgent ? { agent: undefined } : {}),
  };
  const unknownV3Fields = Object.fromEntries(
    Object.entries(value).filter(
      ([key]) => key === 'model' || !GHOST_MANIFEST_KNOWN_TOP_LEVEL_FIELDS.has(key),
    ),
  );
  return {
    ok: true,
    prepared: {
      raw,
      schemaVersion: 3,
      unsupportedLegacySlots: [],
      v3BaseCard,
      v3BaseAgent,
      unknownV3Fields,
    },
  };
}

/** v2 允许历史上只有名字、没有实际能力详单的 slot;它们不进入运行时模型。 */
function dropEmptyLegacyCapabilitySlots(
  value: Record<string, unknown>,
  slots: unknown[],
): unknown[] {
  return slots.filter((slot) => {
    const normalized = slot === 'model' ? 'cindy' : slot;
    if (normalized === 'tool') return value.tools !== undefined;
    if (normalized === 'panel') return value.panel !== undefined;
    if (normalized === 'cindy') return value.cindy !== undefined || value.model !== undefined;
    if (normalized === 'subscribe') return value.subscribe !== undefined;
    if (normalized === 'node') return value.node !== undefined;
    if (normalized === 'network') return value.network !== undefined;
    if (normalized === 'preview') return value.preview !== undefined;
    if (normalized === 'skill') return value.skill !== undefined;
    return true;
  });
}

/** 当前宿主语言在插件未提供时固定回退英文。 */
export function ghostLocalePathFor(
  manifest: GhostManifest,
  locale: string | undefined | null,
): string | null {
  if (!manifest.locales) return null;
  const manifestLocale = (GHOST_LOCALES as readonly string[]).includes(locale ?? '')
    ? locale as GhostLocale
    : null;
  return (
    (manifestLocale ? manifest.locales[manifestLocale] : undefined) ?? manifest.locales.en ?? null
  );
}

/** 插件 app-context 只暴露协议旧四语;宿主新增语言固定回退英文以兼容存量插件。 */
export function ghostAppContextLocale(locale: string | undefined | null): GhostLocale {
  return (GHOST_LOCALES as readonly string[]).includes(locale ?? '')
    ? (locale as GhostLocale)
    : 'en';
}

/** 把当前宿主语言附到运行时清单视图;不支持的输入固定归一到英文。 */
export function withGhostResolvedLocale(
  manifest: GhostManifest,
  locale: string | undefined | null,
): GhostManifest {
  const resolvedLocale = (SUPPORTED_LOCALES as readonly string[]).includes(locale ?? '')
    ? (locale as SupportedLocale)
    : DEFAULT_LOCALE;
  return { ...manifest, resolvedLocale };
}

type GhostSchemaLocaleText = { title?: string; description?: string };
type GhostSchemaLocaleShape = { title: boolean; description: boolean };

const GHOST_SCHEMA_MAP_KEYWORDS = [
  'properties',
  'patternProperties',
  '$defs',
  'definitions',
  'dependentSchemas',
] as const;
const GHOST_SCHEMA_SINGLE_KEYWORDS = [
  'additionalProperties',
  'unevaluatedProperties',
  'propertyNames',
  'items',
  'contains',
  'not',
  'if',
  'then',
  'else',
] as const;
const GHOST_SCHEMA_ARRAY_KEYWORDS = ['allOf', 'anyOf', 'oneOf', 'prefixItems'] as const;

function ghostJsonPointerChild(pointer: string, segment: string | number): string {
  const escaped = String(segment).replace(/~/g, '~0').replace(/\//g, '~1');
  return `${pointer}/${escaped}`;
}

/** 收集 JSON Schema 节点中已有的 title / description,以 JSON Pointer 稳定寻址。 */
function collectGhostSchemaLocaleShape(
  schema: unknown,
  pointer = '',
  result: Record<string, GhostSchemaLocaleShape> = Object.create(null) as Record<
    string,
    GhostSchemaLocaleShape
  >,
): Record<string, GhostSchemaLocaleShape> {
  if (!isPlainObject(schema)) return result;
  const title = typeof schema.title === 'string';
  const description = typeof schema.description === 'string';
  if (title || description) result[pointer] = { title, description };
  for (const keyword of GHOST_SCHEMA_MAP_KEYWORDS) {
    const children = schema[keyword];
    if (!isPlainObject(children)) continue;
    for (const [key, child] of Object.entries(children)) {
      collectGhostSchemaLocaleShape(
        child,
        ghostJsonPointerChild(ghostJsonPointerChild(pointer, keyword), key),
        result,
      );
    }
  }
  for (const keyword of GHOST_SCHEMA_SINGLE_KEYWORDS) {
    collectGhostSchemaLocaleShape(schema[keyword], ghostJsonPointerChild(pointer, keyword), result);
  }
  for (const keyword of GHOST_SCHEMA_ARRAY_KEYWORDS) {
    const children = schema[keyword];
    if (!Array.isArray(children)) continue;
    children.forEach((child, index) => {
      collectGhostSchemaLocaleShape(
        child,
        ghostJsonPointerChild(ghostJsonPointerChild(pointer, keyword), index),
        result,
      );
    });
  }
  return result;
}

function resolveGhostSchemaLocale(
  schema: Record<string, unknown>,
  localized: Record<string, GhostSchemaLocaleText>,
  pointer = '',
): Record<string, unknown> {
  const result: Record<string, unknown> = { ...schema };
  const text = localized[pointer];
  if (text?.title !== undefined) result.title = text.title;
  if (text?.description !== undefined) result.description = text.description;
  for (const keyword of GHOST_SCHEMA_MAP_KEYWORDS) {
    const children = schema[keyword];
    if (!isPlainObject(children)) continue;
    result[keyword] = Object.fromEntries(
      Object.entries(children).map(([key, child]) => [
        key,
        isPlainObject(child)
          ? resolveGhostSchemaLocale(
              child,
              localized,
              ghostJsonPointerChild(ghostJsonPointerChild(pointer, keyword), key),
            )
          : child,
      ]),
    );
  }
  for (const keyword of GHOST_SCHEMA_SINGLE_KEYWORDS) {
    const child = schema[keyword];
    if (!isPlainObject(child)) continue;
    result[keyword] = resolveGhostSchemaLocale(
      child,
      localized,
      ghostJsonPointerChild(pointer, keyword),
    );
  }
  for (const keyword of GHOST_SCHEMA_ARRAY_KEYWORDS) {
    const children = schema[keyword];
    if (!Array.isArray(children)) continue;
    result[keyword] = children.map((child, index) =>
      isPlainObject(child)
        ? resolveGhostSchemaLocale(
            child,
            localized,
            ghostJsonPointerChild(ghostJsonPointerChild(pointer, keyword), index),
          )
        : child,
    );
  }
  return result;
}

/**
 * 校验 locale 文件。翻译是可选项(2026-07-25 起):文件里**提供**的条目严格
 * 校验——未知工具、未知 key、未知字段、原 manifest 没有的条目、类型或长度
 * 不合格照旧拒绝(防止翻译错位与哑弹);**未提供**的条目不再拒绝,解析时
 * 回退原 manifest 文案。完整翻译仍是质量推荐项,但不是装入/打包门槛。
 */
export function validateGhostManifestLocaleResource(
  raw: unknown,
  manifest: GhostManifest,
): { ok: true; resource: GhostManifestLocaleResource } | { ok: false; reason: string } {
  if (!isPlainObject(raw)) return { ok: false, reason: 'locale 文件必须是对象' };
  const allowedTopLevelFields = new Set([
    'name',
    'description',
    'whenToUse',
    'tools',
    'panel',
    'mainView',
    'taskView',
    'network',
    'node',
    'setup',
  ]);
  const unknownTopLevelField = Object.keys(raw).find((field) => !allowedTopLevelFields.has(field));
  if (unknownTopLevelField) {
    return { ok: false, reason: `locale 含未知字段 ${JSON.stringify(unknownTopLevelField)}` };
  }
  if (
    raw.name !== undefined &&
    (typeof raw.name !== 'string' || raw.name.trim().length === 0 || raw.name.length > 64)
  ) {
    return { ok: false, reason: 'locale.name 必须是 1–64 字符的非空字符串' };
  }
  const optionalText = (
    field: 'description' | 'whenToUse',
    max: number,
  ): string | undefined | { error: string } => {
    const value = raw[field];
    if (value === undefined) return undefined;
    if (manifest[field] === undefined) {
      return { error: `locale.${field} 不应存在:原 manifest 未声明该字段` };
    }
    if (typeof value !== 'string' || value.trim().length === 0 || value.length > max) {
      return { error: `locale.${field} 必须是 1–${max} 字符的非空字符串` };
    }
    return value;
  };
  const description = optionalText('description', GHOST_MANIFEST_SUMMARY_MAX_CHARS);
  if (isPlainObject(description) && typeof description.error === 'string') {
    return { ok: false, reason: description.error };
  }
  const whenToUse = optionalText('whenToUse', GHOST_MANIFEST_SUMMARY_MAX_CHARS);
  if (isPlainObject(whenToUse) && typeof whenToUse.error === 'string') {
    return { ok: false, reason: whenToUse.error };
  }

  let tools: GhostManifestLocaleResource['tools'];
  if (raw.tools !== undefined) {
    if (manifest.tools === undefined) {
      return { ok: false, reason: 'locale.tools 不应存在:原 manifest 未声明工具' };
    }
    if (!isPlainObject(raw.tools)) {
      return { ok: false, reason: 'locale.tools 必须按 tool name 提供对象' };
    }
    const expectedNames = new Set(manifest.tools.map((tool) => tool.name));
    const actualNames = Object.keys(raw.tools);
    const unknown = actualNames.find((name) => !expectedNames.has(name));
    if (unknown) return { ok: false, reason: `locale.tools 含未知工具 ${JSON.stringify(unknown)}` };
    tools = Object.create(null) as NonNullable<GhostManifestLocaleResource['tools']>;
    for (const tool of manifest.tools) {
      const localized = raw.tools[tool.name];
      if (localized === undefined) continue; // 缺译:该工具整体回退原文
      if (!isPlainObject(localized)) {
        return { ok: false, reason: `locale.tools[${JSON.stringify(tool.name)}] 必须是对象` };
      }
      const unknownToolField = Object.keys(localized).find(
        (field) => field !== 'description' && field !== 'parameters',
      );
      if (unknownToolField) {
        return {
          ok: false,
          reason: `locale.tools[${JSON.stringify(tool.name)}] 含未知字段 ${JSON.stringify(unknownToolField)}`,
        };
      }
      if (
        typeof localized.description !== 'string' ||
        localized.description.trim().length === 0 ||
        localized.description.length > 1024
      ) {
        return {
          ok: false,
          reason: `locale.tools[${JSON.stringify(tool.name)}].description 必须是 1–1024 字符的非空字符串`,
        };
      }
      const parameterShape = collectGhostSchemaLocaleShape(tool.parameters);
      const parameterPointers = Object.keys(parameterShape);
      let parameters: Record<string, GhostSchemaLocaleText> | undefined;
      if (localized.parameters !== undefined) {
        if (parameterPointers.length === 0) {
          return {
            ok: false,
            reason: `locale.tools[${JSON.stringify(tool.name)}].parameters 不应存在:原参数 schema 没有 title / description`,
          };
        }
        if (!isPlainObject(localized.parameters)) {
          return {
            ok: false,
            reason: `locale.tools[${JSON.stringify(tool.name)}].parameters 必须按 JSON Pointer 提供参数文案`,
          };
        }
        const expectedPointers = new Set(parameterPointers);
        const unknownPointer = Object.keys(localized.parameters).find(
          (pointer) => !expectedPointers.has(pointer),
        );
        if (unknownPointer) {
          return {
            ok: false,
            reason: `locale.tools[${JSON.stringify(tool.name)}].parameters 含未知路径 ${JSON.stringify(unknownPointer)}`,
          };
        }
        parameters = Object.create(null) as Record<string, GhostSchemaLocaleText>;
        for (const pointer of parameterPointers) {
          const shape = parameterShape[pointer];
          const localizedText = localized.parameters[pointer];
          if (localizedText === undefined) continue; // 缺译 pointer:回退原文
          if (!isPlainObject(localizedText)) {
            return {
              ok: false,
              reason: `locale.tools[${JSON.stringify(tool.name)}].parameters[${JSON.stringify(pointer)}] 必须是对象`,
            };
          }
          const allowedFields = new Set([
            ...(shape.title ? ['title'] : []),
            ...(shape.description ? ['description'] : []),
          ]);
          const unknownField = Object.keys(localizedText).find(
            (field) => !allowedFields.has(field),
          );
          if (unknownField) {
            return {
              ok: false,
              reason: `locale.tools[${JSON.stringify(tool.name)}].parameters[${JSON.stringify(pointer)}] 含未知字段 ${JSON.stringify(unknownField)}`,
            };
          }
          if (
            localizedText.title !== undefined &&
            (typeof localizedText.title !== 'string' ||
              localizedText.title.trim().length === 0 ||
              localizedText.title.length > 256)
          ) {
            return {
              ok: false,
              reason: `locale.tools[${JSON.stringify(tool.name)}].parameters[${JSON.stringify(pointer)}].title 必须是 1–256 字符的非空字符串`,
            };
          }
          if (
            localizedText.description !== undefined &&
            (typeof localizedText.description !== 'string' ||
              localizedText.description.trim().length === 0 ||
              localizedText.description.length > 1024)
          ) {
            return {
              ok: false,
              reason: `locale.tools[${JSON.stringify(tool.name)}].parameters[${JSON.stringify(pointer)}].description 必须是 1–1024 字符的非空字符串`,
            };
          }
          parameters[pointer] = {
            ...(typeof localizedText.title === 'string' ? { title: localizedText.title } : {}),
            ...(typeof localizedText.description === 'string'
              ? { description: localizedText.description }
              : {}),
          };
        }
      }
      tools[tool.name] = {
        description: localized.description,
        ...(parameters !== undefined ? { parameters } : {}),
      };
    }
  }

  let panel: GhostManifestLocaleResource['panel'];
  if (raw.panel !== undefined) {
    if (manifest.panel?.title === undefined) {
      return { ok: false, reason: 'locale.panel 不应存在:原 manifest 未声明 panel.title' };
    }
    if (!isPlainObject(raw.panel)) {
      return { ok: false, reason: 'locale.panel 必须是含 title 的对象' };
    }
    const unknownPanelField = Object.keys(raw.panel).find((field) => field !== 'title');
    if (unknownPanelField) {
      return { ok: false, reason: `locale.panel 含未知字段 ${JSON.stringify(unknownPanelField)}` };
    }
    if (
      typeof raw.panel.title !== 'string' ||
      raw.panel.title.trim().length === 0 ||
      raw.panel.title.length > 64
    ) {
      return { ok: false, reason: 'locale.panel.title 必须是 1–64 字符的非空字符串' };
    }
    panel = { title: raw.panel.title };
  }

  let mainView: GhostManifestLocaleResource['mainView'];
  if (raw.mainView !== undefined) {
    if (manifest.mainView?.title === undefined) {
      return {
        ok: false,
        reason: 'locale.mainView 不应存在:原 manifest 未声明 mainView.title',
      };
    }
    if (!isPlainObject(raw.mainView)) {
      return { ok: false, reason: 'locale.mainView 必须是含 title 的对象' };
    }
    const unknownMainViewField = Object.keys(raw.mainView).find((field) => field !== 'title');
    if (unknownMainViewField) {
      return {
        ok: false,
        reason: `locale.mainView 含未知字段 ${JSON.stringify(unknownMainViewField)}`,
      };
    }
    if (
      typeof raw.mainView.title !== 'string' ||
      raw.mainView.title.trim().length === 0 ||
      raw.mainView.title.length > 64
    ) {
      return {
        ok: false,
        reason: 'locale.mainView.title 必须是 1–64 字符的非空字符串',
      };
    }
    mainView = { title: raw.mainView.title };
  }

  let taskView: GhostManifestLocaleResource['taskView'];
  if (raw.taskView !== undefined) {
    if (manifest.taskView?.title === undefined) {
      return {
        ok: false,
        reason: 'locale.taskView 不应存在:原 manifest 未声明 taskView.title',
      };
    }
    if (!isPlainObject(raw.taskView)) {
      return { ok: false, reason: 'locale.taskView 必须是含 title 的对象' };
    }
    const unknownTaskViewField = Object.keys(raw.taskView).find((field) => field !== 'title');
    if (unknownTaskViewField) {
      return {
        ok: false,
        reason: `locale.taskView 含未知字段 ${JSON.stringify(unknownTaskViewField)}`,
      };
    }
    if (
      typeof raw.taskView.title !== 'string' ||
      raw.taskView.title.trim().length === 0 ||
      raw.taskView.title.length > 64
    ) {
      return {
        ok: false,
        reason: 'locale.taskView.title 必须是 1–64 字符的非空字符串',
      };
    }
    taskView = { title: raw.taskView.title };
  }

  const validateLocalizedLabels = (
    rawValue: unknown,
    fieldPath: string,
    declarations: ReadonlyArray<{ key: string; hint?: string }>,
  ):
    | { ok: true; labels?: Record<string, { label: string; hint?: string }> }
    | { ok: false; reason: string } => {
    if (rawValue === undefined) return { ok: true };
    if (declarations.length === 0) {
      return { ok: false, reason: `${fieldPath} 不应存在:原 manifest 未声明对应项目` };
    }
    if (!isPlainObject(rawValue)) {
      return { ok: false, reason: `${fieldPath} 必须按稳定 key 提供对象` };
    }
    const expectedKeys = new Set(declarations.map((declaration) => declaration.key));
    const unknownKey = Object.keys(rawValue).find((key) => !expectedKeys.has(key));
    if (unknownKey) {
      return { ok: false, reason: `${fieldPath} 含未知 key ${JSON.stringify(unknownKey)}` };
    }
    const labels = Object.create(null) as Record<string, { label: string; hint?: string }>;
    for (const declaration of declarations) {
      const localized = rawValue[declaration.key];
      if (localized === undefined) continue; // 缺译:该项回退原文
      if (!isPlainObject(localized)) {
        return { ok: false, reason: `${fieldPath}[${JSON.stringify(declaration.key)}] 必须是对象` };
      }
      const allowedFields =
        declaration.hint !== undefined ? new Set(['label', 'hint']) : new Set(['label']);
      const unknownField = Object.keys(localized).find((field) => !allowedFields.has(field));
      if (unknownField) {
        return {
          ok: false,
          reason: `${fieldPath}[${JSON.stringify(declaration.key)}] 含未知字段 ${JSON.stringify(unknownField)}`,
        };
      }
      if (
        typeof localized.label !== 'string' ||
        localized.label.trim().length === 0 ||
        localized.label.length > 64
      ) {
        return {
          ok: false,
          reason: `${fieldPath}[${JSON.stringify(declaration.key)}].label 必须是 1–64 字符的非空字符串`,
        };
      }
      if (
        localized.hint !== undefined &&
        (typeof localized.hint !== 'string' ||
          localized.hint.trim().length === 0 ||
          localized.hint.length > 200)
      ) {
        return {
          ok: false,
          reason: `${fieldPath}[${JSON.stringify(declaration.key)}].hint 必须是 1–200 字符的非空字符串`,
        };
      }
      labels[declaration.key] = {
        label: localized.label,
        ...(typeof localized.hint === 'string' ? { hint: localized.hint } : {}),
      };
    }
    return { ok: true, labels };
  };

  const secretDecls = manifest.network?.secrets ?? [];
  const connectionDecls = manifest.network?.connections ?? [];
  let network: GhostManifestLocaleResource['network'];
  if (raw.network !== undefined) {
    if (secretDecls.length === 0 && connectionDecls.length === 0) {
      return { ok: false, reason: 'locale.network 不应存在:原 manifest 未声明凭证或连接' };
    }
    if (!isPlainObject(raw.network)) {
      return { ok: false, reason: 'locale.network 必须是含 secrets / connections 的对象' };
    }
    const unknownNetworkField = Object.keys(raw.network).find(
      (field) => field !== 'secrets' && field !== 'connections',
    );
    if (unknownNetworkField) {
      return {
        ok: false,
        reason: `locale.network 含未知字段 ${JSON.stringify(unknownNetworkField)}`,
      };
    }
    const secrets = validateLocalizedLabels(
      raw.network.secrets,
      'locale.network.secrets',
      secretDecls,
    );
    if (!secrets.ok) return secrets;
    const connections = validateLocalizedLabels(
      raw.network.connections,
      'locale.network.connections',
      connectionDecls,
    );
    if (!connections.ok) return connections;
    network = {
      ...(secrets.labels !== undefined ? { secrets: secrets.labels } : {}),
      ...(connections.labels !== undefined ? { connections: connections.labels } : {}),
    };
  }

  const nodeSecretDecls = manifest.node?.secretBindings ?? [];
  let node: GhostManifestLocaleResource['node'];
  if (raw.node !== undefined) {
    if (nodeSecretDecls.length === 0) {
      return { ok: false, reason: 'locale.node 不应存在:原 manifest 未声明 node.secretBindings' };
    }
    if (!isPlainObject(raw.node)) {
      return { ok: false, reason: 'locale.node 必须是含 secretBindings 的对象' };
    }
    const unknownNodeField = Object.keys(raw.node).find((field) => field !== 'secretBindings');
    if (unknownNodeField) {
      return { ok: false, reason: `locale.node 含未知字段 ${JSON.stringify(unknownNodeField)}` };
    }
    const secretBindings = validateLocalizedLabels(
      raw.node.secretBindings,
      'locale.node.secretBindings',
      nodeSecretDecls,
    );
    if (!secretBindings.ok) return secretBindings;
    node = secretBindings.labels !== undefined ? { secretBindings: secretBindings.labels } : {};
  }

  const setupKvDecls = new Map<string, { key: string }>();
  for (const group of manifest.setup?.requires ?? []) {
    for (const requirement of group.anyOf) {
      if (requirement.kind === 'kv') setupKvDecls.set(requirement.key, { key: requirement.key });
    }
  }
  let setup: GhostManifestLocaleResource['setup'];
  if (raw.setup !== undefined) {
    if (setupKvDecls.size === 0) {
      return { ok: false, reason: 'locale.setup 不应存在:原 manifest 未声明 setup kv 项' };
    }
    if (!isPlainObject(raw.setup)) {
      return { ok: false, reason: 'locale.setup 必须是含 kv 的对象' };
    }
    const unknownSetupField = Object.keys(raw.setup).find((field) => field !== 'kv');
    if (unknownSetupField) {
      return { ok: false, reason: `locale.setup 含未知字段 ${JSON.stringify(unknownSetupField)}` };
    }
    const kv = validateLocalizedLabels(raw.setup.kv, 'locale.setup.kv', [...setupKvDecls.values()]);
    if (!kv.ok) return kv;
    if (kv.labels !== undefined) {
      const localizedKv = Object.create(null) as Record<string, { label: string }>;
      for (const [key, localized] of Object.entries(kv.labels)) {
        localizedKv[key] = { label: localized.label };
      }
      setup = { kv: localizedKv };
    } else {
      setup = {};
    }
  }

  return {
    ok: true,
    resource: {
      ...(typeof raw.name === 'string' ? { name: raw.name } : {}),
      ...(typeof description === 'string' ? { description } : {}),
      ...(typeof whenToUse === 'string' ? { whenToUse } : {}),
      ...(tools !== undefined ? { tools } : {}),
      ...(raw.mail === true ? { mail: true as const } : {}),
      ...(panel !== undefined ? { panel } : {}),
      ...(mainView !== undefined ? { mainView } : {}),
      ...(taskView !== undefined ? { taskView } : {}),
      ...(network !== undefined ? { network } : {}),
      ...(node !== undefined ? { node } : {}),
      ...(setup !== undefined ? { setup } : {}),
    },
  };
}

/**
 * 用已校验的 locale 资源生成宿主与 Agent 消费的本地化 manifest 视图。
 * 资源里缺失的条目一律回退原 manifest 文案(部分翻译是合法状态)。
 */
export function resolveGhostManifestLocale(
  manifest: GhostManifest,
  resource: GhostManifestLocaleResource,
): GhostManifest {
  return {
    ...manifest,
    ...(resource.name !== undefined ? { name: resource.name } : {}),
    ...(resource.description !== undefined ? { description: resource.description } : {}),
    ...(resource.whenToUse !== undefined ? { whenToUse: resource.whenToUse } : {}),
    ...(manifest.tools !== undefined && resource.tools !== undefined
      ? {
          tools: manifest.tools.map((tool) => {
            const localized = resource.tools![tool.name];
            if (localized === undefined) return tool;
            return {
              ...tool,
              description: localized.description,
              ...(tool.parameters !== undefined && localized.parameters !== undefined
                ? { parameters: resolveGhostSchemaLocale(tool.parameters, localized.parameters) }
                : {}),
            };
          }),
        }
      : {}),
    ...(manifest.panel !== undefined && resource.panel !== undefined
      ? { panel: { ...manifest.panel, title: resource.panel.title } }
      : {}),
    ...(manifest.mainView !== undefined && resource.mainView !== undefined
      ? { mainView: { ...manifest.mainView, title: resource.mainView.title } }
      : {}),
    ...(manifest.taskView !== undefined && resource.taskView !== undefined
      ? { taskView: { ...manifest.taskView, title: resource.taskView.title } }
      : {}),
    ...(manifest.network !== undefined && resource.network !== undefined
      ? {
          network: {
            ...manifest.network,
            ...(manifest.network.secrets !== undefined && resource.network.secrets !== undefined
              ? {
                  secrets: manifest.network.secrets.map((secret) => ({
                    ...secret,
                    ...(resource.network!.secrets![secret.key] ?? {}),
                  })),
                }
              : {}),
            ...(manifest.network.connections !== undefined &&
            resource.network.connections !== undefined
              ? {
                  connections: manifest.network.connections.map((connection) => ({
                    ...connection,
                    ...(resource.network!.connections![connection.key] ?? {}),
                  })),
                }
              : {}),
          },
        }
      : {}),
    ...(manifest.node !== undefined && resource.node?.secretBindings !== undefined
      ? {
          node: {
            ...manifest.node,
            secretBindings: manifest.node.secretBindings?.map((binding) => ({
              ...binding,
              ...(resource.node!.secretBindings![binding.key] ?? {}),
            })),
          },
        }
      : {}),
    ...(manifest.setup !== undefined && resource.setup?.kv !== undefined
      ? {
          setup: {
            requires: manifest.setup.requires.map((group) => ({
              anyOf: group.anyOf.map((requirement) =>
                requirement.kind === 'kv' && resource.setup!.kv![requirement.key] !== undefined
                  ? { ...requirement, label: resource.setup!.kv![requirement.key].label }
                  : requirement,
              ),
            })),
          },
        }
      : {}),
  };
}

/**
 * 校验一份解析后的 ghost.json。已知字段严格检查;v2 未知字段忽略,v3 未知
 * 顶层字段原样保留但不解释、不展示、不授权。任何已知字段不合格都给出 reason。
 */
export function validateGhostManifest(value: unknown): ManifestValidation {
  return validateGhostManifestInput(value, false);
}

/** Installed snapshots retain historical unknown tasks data without granting it. */
export function validateInstalledGhostManifest(value: unknown): ManifestValidation {
  return validateGhostManifestInput(value, true);
}

function validateGhostManifestInput(value: unknown, preserveHistoricalTasks: boolean): ManifestValidation {
  const preparation = prepareGhostManifestForValidation(value);
  if (!preparation.ok) return preparation;
  const prepared = preparation.prepared;
  const raw = prepared.raw;
  if (raw.mail !== undefined && raw.mail !== true) return { ok: false, reason: 'mail 出现时必须是 true' };
  const mailReader = raw.mailReader === undefined ? undefined : parseMailReader(raw.mailReader);
  if (raw.mailReader !== undefined && !mailReader) {
    return { ok: false, reason: 'mailReader 必须声明合法的 tool 与 hosts' };
  }
  if (mailReader && (raw.mail !== true || !Array.isArray(raw.tools) ||
      !raw.tools.some(tool => isPlainObject(tool) && tool.name === mailReader.tool))) {
    return { ok: false, reason: 'mailReader 必须同时声明 mail: true 与对应的 tools 工具' };
  }
  if (!isValidGhostId(raw.id)) {
    return { ok: false, reason: 'id 必须是 1–32 位小写字母/数字/连字符(不能以连字符开头)' };
  }
  if (typeof raw.name !== 'string' || raw.name.trim().length === 0 || raw.name.length > 64) {
    return { ok: false, reason: 'name 必须是 1–64 字符的非空字符串' };
  }
  if (
    typeof raw.version !== 'string' ||
    raw.version.trim().length === 0 ||
    raw.version.length > 32
  ) {
    return { ok: false, reason: 'version 必须是 1–32 字符的非空字符串' };
  }
  if (raw.releaseNotes !== undefined && typeof raw.releaseNotes !== 'string') {
    return { ok: false, reason: 'releaseNotes 必须是纯文本字符串' };
  }
  if (raw.minCindyVersion !== undefined && !isValidCindyVersion(raw.minCindyVersion)) {
    return { ok: false, reason: 'minCindyVersion 必须是合法的 SemVer 字符串' };
  }
  // kind 可省略(2026-07-12 晚定案:单形态后字段纯冗余,缺省即 chip);
  // 写了就必须是 chip——写错值仍拒,不静默纠正(规则 9)。
  if (raw.kind !== undefined && raw.kind !== 'chip') {
    return {
      ok: false,
      reason: `kind 必须是 "chip" 或省略(缺省即 chip),得到 ${JSON.stringify(raw.kind)}(意识只有芯片一种形态,declaration 已移除)`,
    };
  }
  if (
    raw.author !== undefined &&
    (typeof raw.author !== 'string' || raw.author.trim().length === 0 || raw.author.length > 64)
  ) {
    return { ok: false, reason: 'author 必须是 1–64 字符的非空字符串' };
  }
  const declaredFilePathFolds = [
    GHOST_MANIFEST_FILE,
    raw.entry,
    raw.icon,
    raw.settingsHtml,
    isPlainObject(raw.panel) ? raw.panel.html : undefined,
    isPlainObject(raw.mainView) ? raw.mainView.html : undefined,
    isPlainObject(raw.taskView) ? raw.taskView.html : undefined,
    isPlainObject(raw.node) ? raw.node.entry : undefined,
    ...(isPlainObject(raw.node) && Array.isArray(raw.node.entries) ? raw.node.entries : []),
  ]
    .filter((value): value is string => typeof value === 'string')
    .map((value) => value.toLowerCase());
  const isSameOrDescendant = (path: string, ancestor: string): boolean =>
    path === ancestor || path.startsWith(`${ancestor}/`);
  const pathsConflict = (left: string, right: string): boolean =>
    isSameOrDescendant(left, right) || isSameOrDescendant(right, left);
  let locales: GhostManifest['locales'];
  if (raw.locales !== undefined) {
    if (!isPlainObject(raw.locales)) {
      return { ok: false, reason: 'locales 必须是语言到 locale JSON 路径的对象' };
    }
    const unknownLocale = Object.keys(raw.locales).find(
      (locale) => !(GHOST_LOCALES as readonly string[]).includes(locale),
    );
    if (unknownLocale) {
      return {
        ok: false,
        reason: `locales 含宿主不支持的语言 ${JSON.stringify(unknownLocale)}(可用:${GHOST_LOCALES.join(' / ')})`,
      };
    }
    if (raw.locales.en === undefined) {
      return { ok: false, reason: 'locales 必须提供 en,作为所有不支持语言的固定回退' };
    }
    const normalized: Partial<Record<GhostLocale, string>> = {};
    const seenPaths = new Set<string>();
    const manualDirFolds = (
      isPlainObject(raw.manual) && Array.isArray(raw.manual.items) ? raw.manual.items : []
    )
      .map((item) => (isPlainObject(item) ? item.dir : undefined))
      .filter((value): value is string => typeof value === 'string')
      .map((value) => value.toLowerCase());
    for (const locale of GHOST_LOCALES) {
      const localePath = raw.locales[locale];
      if (localePath === undefined) continue;
      if (
        typeof localePath !== 'string' ||
        !isSafeGhostRelativePath(localePath) ||
        !localePath.toLowerCase().endsWith('.json')
      ) {
        return {
          ok: false,
          reason: `locales.${locale} 必须是安装目录内以 .json 结尾的安全相对路径`,
        };
      }
      const normalizedLocalePath = localePath.toLowerCase();
      const conflictsWithFile = declaredFilePathFolds.includes(normalizedLocalePath);
      const conflictsWithManualDir = manualDirFolds.some((dir) =>
        pathsConflict(dir, normalizedLocalePath),
      );
      if (conflictsWithFile || conflictsWithManualDir) {
        return {
          ok: false,
          reason: `locales.${locale} 路径 ${JSON.stringify(localePath)} 与插件其他声明文件大小写折叠后冲突`,
        };
      }
      if (seenPaths.has(normalizedLocalePath)) {
        return { ok: false, reason: `locales 含重复路径 ${JSON.stringify(localePath)}` };
      }
      seenPaths.add(normalizedLocalePath);
      normalized[locale] = localePath;
    }
    locales = normalized as GhostManifestLocales;
  }
  if (
    raw.description !== undefined &&
    (typeof raw.description !== 'string' ||
      raw.description.trim().length === 0 ||
      raw.description.length > GHOST_MANIFEST_SUMMARY_MAX_CHARS)
  ) {
    return {
      ok: false,
      reason: `description 必须是 1–${GHOST_MANIFEST_SUMMARY_MAX_CHARS} 字符的非空字符串`,
    };
  }
  if (
    raw.whenToUse !== undefined &&
    (typeof raw.whenToUse !== 'string' ||
      raw.whenToUse.trim().length === 0 ||
      raw.whenToUse.length > GHOST_MANIFEST_SUMMARY_MAX_CHARS)
  ) {
    return {
      ok: false,
      reason: `whenToUse 必须是 1–${GHOST_MANIFEST_SUMMARY_MAX_CHARS} 字符的非空字符串`,
    };
  }
  if (raw.icon !== undefined) {
    if (!isSafeGhostRelativePath(raw.icon)) {
      return { ok: false, reason: 'icon 必须是安装目录内的安全相对路径' };
    }
    if (ghostIconMimeType(raw.icon) === null) {
      return {
        ok: false,
        reason: `icon 扩展名不受支持(可用:${Object.keys(GHOST_ICON_MIME_BY_EXT).join(' / ')})`,
      };
    }
  }
  let panel: GhostPanelDecl | undefined;
  if (raw.panel !== undefined) {
    const p = raw.panel;
    if (!isPlainObject(p)) return { ok: false, reason: 'panel 必须是对象' };
    if (
      p.title !== undefined &&
      (typeof p.title !== 'string' || p.title.length === 0 || p.title.length > 64)
    ) {
      return { ok: false, reason: 'panel.title 必须是 1–64 字符的字符串' };
    }
    // 面板一律由意识自绘(html 必填):declaration 时代的静态 body 面板已随
    // 单形态定案(2026-07-12)移除。
    if (!isSafeGhostRelativePath(p.html)) {
      return { ok: false, reason: 'panel.html 必填,且必须是安装目录内的安全相对路径' };
    }
    if (
      p.minWidth !== undefined &&
      (typeof p.minWidth !== 'number' ||
        !Number.isFinite(p.minWidth) ||
        p.minWidth < 120 ||
        p.minWidth > 1200)
    ) {
      return { ok: false, reason: 'panel.minWidth 必须是 120–1200 之间的数字' };
    }
    if (
      p.defaultFraction !== undefined &&
      (typeof p.defaultFraction !== 'number' ||
        !Number.isFinite(p.defaultFraction) ||
        p.defaultFraction < 0.05 ||
        p.defaultFraction > 0.8)
    ) {
      return { ok: false, reason: 'panel.defaultFraction 必须是 0.05–0.8 之间的数字' };
    }
    let systemButtons: GhostPanelDecl['systemButtons'];
    if (p.systemButtons !== undefined) {
      const sb = p.systemButtons;
      if (!isPlainObject(sb)) {
        return { ok: false, reason: 'panel.systemButtons 必须是对象(如 { "maximize": false })' };
      }
      // 未来按钮声明保留为数据,当前界面仅消费已实现的按钮。
      const knownButtons = ['maximize', 'detach', 'minimize'];
      for (const key of Object.keys(sb)) {
        if (!knownButtons.includes(key)) {
          continue;
        }
        if (typeof (sb as Record<string, unknown>)[key] !== 'boolean') {
          return { ok: false, reason: `panel.systemButtons.${key} 必须是布尔值` };
        }
      }
      const maximize = (sb as Record<string, unknown>).maximize;
      const detach = (sb as Record<string, unknown>).detach;
      const minimize = (sb as Record<string, unknown>).minimize;
      systemButtons = {
        ...unknownDeclarationFields(sb, knownButtons),
        ...(typeof maximize === 'boolean' ? { maximize } : {}),
        ...(typeof detach === 'boolean' ? { detach } : {}),
        ...(typeof minimize === 'boolean' ? { minimize } : {}),
      };
    }
    let position: GhostPanelPosition | undefined;
    if (p.position !== undefined) {
      if (!(GHOST_PANEL_POSITIONS as readonly string[]).includes(p.position as string)) {
        return {
          ok: false,
          reason: `panel.position 必须是 ${GHOST_PANEL_POSITIONS.join(' / ')}`,
        };
      }
      position = p.position as GhostPanelPosition;
      // 页签形态没有拖缝宽度/标准头语义:收词明确拒绝而非静默忽略(规则 9)。
      if (
        position === 'tab' &&
        (p.minWidth !== undefined ||
          p.defaultFraction !== undefined ||
          p.systemButtons !== undefined)
      ) {
        return {
          ok: false,
          reason:
            "panel.minWidth / panel.defaultFraction / panel.systemButtons 仅停靠形态(left)有效,position:'tab' 时请移除",
        };
      }
    }
    panel = {
      ...unknownDeclarationFields(p, ['title', 'position', 'html', 'minWidth', 'defaultFraction', 'systemButtons']),
      ...(p.title !== undefined ? { title: p.title as string } : {}),
      ...(position !== undefined ? { position } : {}),
      html: p.html as string,
      ...(p.minWidth !== undefined ? { minWidth: p.minWidth as number } : {}),
      ...(p.defaultFraction !== undefined ? { defaultFraction: p.defaultFraction as number } : {}),
      ...(systemButtons !== undefined ? { systemButtons } : {}),
    };
  }

  let mainView: GhostMainViewDecl | undefined;
  if (raw.mainView !== undefined) {
    if (!isPlainObject(raw.mainView)) {
      return { ok: false, reason: 'mainView 必须是对象' };
    }
    if (
      raw.mainView.title !== undefined &&
      (typeof raw.mainView.title !== 'string' ||
        raw.mainView.title.trim().length === 0 ||
        raw.mainView.title.length > 64)
    ) {
      return { ok: false, reason: 'mainView.title 必须是 1–64 字符的非空字符串' };
    }
    if (
      raw.mainView.icon !== undefined &&
      !(GHOST_MAIN_VIEW_ICONS as readonly unknown[]).includes(raw.mainView.icon)
    ) {
      return {
        ok: false,
        reason: `mainView.icon 必须是以下系统图标之一:${GHOST_MAIN_VIEW_ICONS.join(' / ')}`,
      };
    }
    if (!isPortableGhostRelativePath(raw.mainView.html)) {
      return {
        ok: false,
        reason: 'mainView.html 必填,且必须是安装目录内的安全相对路径',
      };
    }
    if (
      raw.mainView.open !== undefined &&
      !(GHOST_MAIN_VIEW_OPEN_MODES as readonly unknown[]).includes(raw.mainView.open)
    ) {
      return {
        ok: false,
        reason: `mainView.open 必须是 ${GHOST_MAIN_VIEW_OPEN_MODES.join(' / ')}`,
      };
    }
    if (raw.mainView.multiple !== undefined && raw.mainView.multiple !== true) {
      return { ok: false, reason: 'mainView.multiple 只接受字面量 true(不需要时省略)' };
    }
    if (raw.mainView.side !== undefined) {
      if (raw.mainView.open !== 'sidebar') {
        return { ok: false, reason: "mainView.side 只在 open:'sidebar' 时有效,其它打开方式请移除" };
      }
      if (!(GHOST_TAB_SIDES as readonly unknown[]).includes(raw.mainView.side)) {
        return { ok: false, reason: `mainView.side 必须是 ${GHOST_TAB_SIDES.join(' / ')}` };
      }
    }
    mainView = {
      ...unknownDeclarationFields(raw.mainView, ['html', 'title', 'icon', 'open', 'side', 'multiple']),
      ...(raw.mainView.title !== undefined ? { title: raw.mainView.title } : {}),
      ...(raw.mainView.icon !== undefined ? { icon: raw.mainView.icon as GhostMainViewIcon } : {}),
      ...(raw.mainView.open !== undefined
        ? { open: raw.mainView.open as GhostMainViewOpenMode }
        : {}),
      ...(raw.mainView.side !== undefined ? { side: raw.mainView.side as GhostTabSide } : {}),
      ...(raw.mainView.multiple === true ? { multiple: true as const } : {}),
      html: raw.mainView.html,
    };
  }

  let taskView: GhostTaskViewDecl | undefined;
  if (raw.taskView !== undefined) {
    if (!isPlainObject(raw.taskView)) {
      return { ok: false, reason: 'taskView 必须是对象' };
    }
    if (
      raw.taskView.title !== undefined &&
      (typeof raw.taskView.title !== 'string' ||
        raw.taskView.title.trim().length === 0 ||
        raw.taskView.title.length > 64)
    ) {
      return { ok: false, reason: 'taskView.title 必须是 1–64 字符的非空字符串' };
    }
    if (!isPortableGhostRelativePath(raw.taskView.html)) {
      return { ok: false, reason: 'taskView.html 必填,且必须是安装目录内的安全相对路径' };
    }
    taskView = {
      ...unknownDeclarationFields(raw.taskView, ['html', 'title']),
      ...(raw.taskView.title !== undefined ? { title: raw.taskView.title } : {}),
      html: raw.taskView.html,
    };
  }

  if (!isSafeGhostRelativePath(raw.entry)) {
    return { ok: false, reason: '必须提供 entry(安装目录内的安全相对路径,电子脑逻辑入口)' };
  }
  if (
    raw.launch !== undefined &&
    !(GHOST_LAUNCH_MODES as readonly string[]).includes(raw.launch as string)
  ) {
    return { ok: false, reason: `launch 必须是 ${GHOST_LAUNCH_MODES.join(' / ')}` };
  }
  if (raw.settingsHtml !== undefined && !isSafeGhostRelativePath(raw.settingsHtml)) {
    return { ok: false, reason: 'settingsHtml 必须是安装目录内的安全相对路径' };
  }
  if (raw.showTaskPreferences !== undefined && typeof raw.showTaskPreferences !== 'boolean') {
    return { ok: false, reason: 'showTaskPreferences 必须是布尔值' };
  }
  if (raw.settingsHeight !== undefined) {
    if (raw.settingsHtml === undefined) {
      return {
        ok: false,
        reason: '声明了 settingsHeight 但没有 settingsHtml——没有界面就没有高度可言',
      };
    }
    if (
      typeof raw.settingsHeight !== 'number' ||
      !Number.isFinite(raw.settingsHeight) ||
      raw.settingsHeight < 160 ||
      raw.settingsHeight > 800
    ) {
      return { ok: false, reason: 'settingsHeight 必须是 160–800 之间的数字' };
    }
  }
  if (!Array.isArray(raw.slots)) {
    return { ok: false, reason: 'schemaVersion 2 的 slots 必须是数组' };
  }
  const slots: LegacyGhostSlot[] = [];
  for (const s of raw.slots) {
    // 旧名兼容:'model' 静默归一化为 'cindy'(2026-07-11 更名,已装老包不消失)。
    const name = s === 'model' ? 'cindy' : s;
    if (typeof name !== 'string' || !GHOST_SLOT_NAME_RE.test(name)) {
      return {
        ok: false,
        reason: `slots 含格式非法的卡槽名称 ${JSON.stringify(s)}`,
      };
    }
    if (slots.includes(name)) {
      return { ok: false, reason: `slots 含重复卡槽 ${JSON.stringify(s)}` };
    }
    slots.push(name);
  }
  // 声明了面板却没申请 panel 槽(或反之有槽无面板)都是清单自相矛盾。
  if (panel !== undefined && !slots.includes('panel')) {
    return { ok: false, reason: '声明了 panel 但 slots 未包含 "panel"' };
  }
  if (slots.includes('panel') && panel === undefined) {
    return { ok: false, reason: 'slots 声明了 "panel" 但缺少 panel(面板由意识自绘,html 必填)' };
  }
  if (mainView !== undefined && !slots.includes('main-view')) {
    return { ok: false, reason: '声明了 mainView 但 slots 未包含 "main-view"' };
  }
  if (slots.includes('main-view') && mainView === undefined) {
    return {
      ok: false,
      reason: 'slots 声明了 "main-view" 但缺少 mainView(html 必填)',
    };
  }
  if (taskView !== undefined && !slots.includes('task-view')) {
    return { ok: false, reason: '声明了 taskView 但 slots 未包含 "task-view"' };
  }
  if (slots.includes('task-view') && taskView === undefined) {
    return { ok: false, reason: 'slots 声明了 "task-view" 但缺少 taskView(html 必填)' };
  }

  // card 槽详单:有详单必有槽;有槽无详单 = 纯渲染卡片(默认行为,向后兼容)。
  let card: GhostCardNeeds | undefined;
  if (raw.card !== undefined) {
    if (!isPlainObject(raw.card)) {
      return { ok: false, reason: 'card 能力详单必须是对象(如 { "externalLinks": true })' };
    }
    if (!slots.includes('card')) {
      return { ok: false, reason: '声明了 card 能力详单但 slots 未包含 "card"' };
    }
    const cardRaw = raw.card as Record<string, unknown>;
    if (cardRaw.externalLinks !== undefined && typeof cardRaw.externalLinks !== 'boolean') {
      return { ok: false, reason: 'card.externalLinks 必须是布尔值' };
    }
    const cardExtensions = unknownDeclarationFields(cardRaw, ['externalLinks']);
    if (cardRaw.externalLinks === true || Object.keys(cardExtensions).length > 0) {
      card = { ...cardExtensions, ...(cardRaw.externalLinks === true ? { externalLinks: true } : {}) };
    }
  }

  /**
   * 未读角标槽(badge)与 `panel` 严格成对:未读点承诺「点开能看到内容」,
   * 纯工具型 / 对话型意识没有可打开的界面,点亮了也无处可点,给了就是骗点击。
   *
   * **为什么用一个新 slot 而不是 `notify` 下的子字段**(2026-08-03,codex review P1):
   * `badge` 引入时 `slots` 还是协议硬白名单,未登记的槽名会被旧客户端拒装。
   * 所以在它引入之前已经装在用户机器上的老包不可能带 `badge` 槽;这让当时的
   * 「新声明」与「老包的同名自定义字段」可证明地区分开,而不是靠概率赌。
   *
   * 早前的方案把它放在顶层 `notify` 对象里。那个字段在本改动前完全未登记、会被
   * 校验器静默忽略,于是两头堵:严格校验会让写过同名字段的老包升级后消失(§5 红线),
   * 放松成"识别到就给"又会让恰好写成 `badge:true` 且有面板的老包在**没有任何安装
   * 或更新确认**的情况下白拿一个常驻注意力面。换成 slot 后两个问题同时消失,
   * `notify` 顶层字段也不再被解释——存量清单里有什么形态都照旧忽略。
   */
  if (slots.includes('badge') && panel === undefined) {
    return {
      ok: false,
      reason:
        'slots 声明了 "badge" 但缺少 panel——未读点承诺「点开能看到内容」,没有面板的意识点亮了也无处可点',
    };
  }

  // 工具声明(卡槽②):与 slots 含 'tool' 严格成对,规则同 panel。
  let tools: GhostToolDecl[] | undefined;
  if (raw.tools !== undefined) {
    if (!Array.isArray(raw.tools) || raw.tools.length === 0 || raw.tools.length > 16) {
      return { ok: false, reason: 'tools 必须是 1–16 项的数组' };
    }
    tools = [];
    const seenNames = new Set<string>();
    for (const t of raw.tools) {
      if (!isPlainObject(t)) return { ok: false, reason: 'tools 每项必须是对象' };
      if (typeof t.name === 'string' && isGhostManifestReservedRecordKey(t.name)) {
        return {
          ok: false,
          reason: `tools[].name 不允许使用对象保留键名 ${JSON.stringify(t.name)}`,
        };
      }
      if (typeof t.name !== 'string' || !/^[a-z][a-z0-9_-]{0,63}$/.test(t.name)) {
        return {
          ok: false,
          reason: 'tools[].name 必须是小写字母开头的 1–64 位小写/数字/下划线/连字符',
        };
      }
      if (seenNames.has(t.name))
        return { ok: false, reason: `tools 含重名工具 ${JSON.stringify(t.name)}` };
      seenNames.add(t.name);
      if (
        typeof t.description !== 'string' ||
        t.description.trim().length === 0 ||
        t.description.length > 1024
      ) {
        return { ok: false, reason: 'tools[].description 必须是 1–1024 字符的非空字符串' };
      }
      if (t.parameters !== undefined) {
        if (!isPlainObject(t.parameters))
          return { ok: false, reason: 'tools[].parameters 必须是对象(JSON Schema)' };
        try {
          if (JSON.stringify(t.parameters).length > 16_384) {
            return { ok: false, reason: 'tools[].parameters 过大(上限 16KB)' };
          }
        } catch {
          return { ok: false, reason: 'tools[].parameters 必须可序列化' };
        }
      }
      tools.push({
        name: t.name,
        description: t.description,
        ...(t.parameters !== undefined
          ? { parameters: t.parameters as Record<string, unknown> }
          : {}),
      });
    }
  }
  if (tools !== undefined && !slots.includes('tool')) {
    return { ok: false, reason: '声明了 tools 但 slots 未包含 "tool"' };
  }
  if (slots.includes('tool') && tools === undefined) {
    return { ok: false, reason: 'slots 声明了 "tool" 但缺少 tools(注册什么工具要写清楚)' };
  }

  // 历史版本可能在 manifest 中带有已移除的资源搜索字段;它作为未知顶层字段忽略,
  // 保持存量插件可见且不因字段形状自动获得新的运行能力。
  // cindy 槽能力详单:与 slots 含 'cindy' 成对(有详单必有槽;有槽无详单
  // 允许装入但运行时零能力——老包不消失,只是代办被拒并提示作者更新)。
  // 字段旧名 model 作别名收入(两个都写以 cindy 为准)。
  const cindyRaw =
    raw.cindy !== undefined ? raw.cindy : prepared.schemaVersion === 2 ? raw.model : undefined;
  let cindy: GhostCindyNeeds | undefined;
  if (cindyRaw !== undefined) {
    if (!isPlainObject(cindyRaw)) {
      return { ok: false, reason: 'cindy 能力详单必须是对象(如 { "image": ["generate"] })' };
    }
    if (!slots.includes('cindy')) {
      return { ok: false, reason: '声明了 cindy 能力详单但 slots 未包含 "cindy"' };
    }
    cindy = unknownDeclarationFields(cindyRaw, ['image', 'video', 'media', 'text', 'embed', 'search', 'oneshotModel']);
    // oneshotModel(快问快答偏好模型)是标量键不是类目:先摘出,不进类目循环。
    // 只验形态不验存在——目录随主机演进,声明式字段永不构成硬依赖。
    const oneshotModelRaw = cindyRaw.oneshotModel;
    if (
      oneshotModelRaw !== undefined &&
      (typeof oneshotModelRaw !== 'string' ||
        oneshotModelRaw.trim().length === 0 ||
        oneshotModelRaw.length > 128)
    ) {
      return {
        ok: false,
        reason: 'cindy.oneshotModel 必须是 1–128 字符的目录模型 id(如 "codex/gpt-5.5")',
      };
    }
    // 类目 → 合法动作表(image / video / media;image 与 video 的动作集恰好
    // 同名,但按类目查表,未来某类目动作分叉时这里天然承接)。新增类目必须
    // 同时在下面的落位分支登记 —— 漏登记会让动作静默落进别的类目。
    const actionTable: Record<string, readonly string[]> = {
      image: GHOST_MODEL_IMAGE_ACTIONS,
      video: GHOST_MODEL_VIDEO_ACTIONS,
      media: GHOST_CINDY_MEDIA_ACTIONS,
      text: GHOST_CINDY_TEXT_ACTIONS,
      embed: GHOST_CINDY_EMBED_ACTIONS,
      search: GHOST_CINDY_SEARCH_ACTIONS,
    };
    for (const [category, actionsRaw] of Object.entries(cindyRaw)) {
      if (category === 'oneshotModel') continue;
      if (!Object.hasOwn(actionTable, category)) continue;
      if (!Array.isArray(actionsRaw) || actionsRaw.length === 0) {
        return { ok: false, reason: `cindy.${category} 必须是非空数组` };
      }
      const actions: string[] = [];
      for (const a of actionsRaw) {
        if (typeof a !== 'string' || !GHOST_SLOT_NAME_RE.test(a)) {
          return {
            ok: false,
            reason: `cindy.${category} 动作必须是合法的能力标识: ${JSON.stringify(a)}`,
          };
        }
        if (actions.includes(a)) {
          return { ok: false, reason: `cindy.${category} 含重复动作 ${JSON.stringify(a)}` };
        }
        actions.push(a);
      }
      // 逐类目显式落位:不要写成 `else cindy.video = …` 的兜底分支——新增
      // 类目时漏改这里会把新动作静默塞进 video(actionTable 已放行,校验不报错)。
      if (category === 'image') cindy.image = actions as GhostModelImageAction[];
      else if (category === 'video') cindy.video = actions as GhostModelVideoAction[];
      else if (category === 'media') cindy.media = actions as GhostCindyMediaAction[];
      else if (category === 'text') cindy.text = actions as GhostCindyTextAction[];
      else if (category === 'embed') cindy.embed = actions as GhostCindyEmbedAction[];
      else if (category === 'search') cindy.search = actions as GhostCindySearchAction[];
      else
        return {
          ok: false,
          reason: `cindy 能力类目 ${JSON.stringify(category)} 尚未接线(主机缺陷)`,
        };
    }
    // 偏好模型只是快问快答的选型意图,必须挂在能力本体上(无能力单挂偏好 =
    // 清单自相矛盾,与"有详单必有槽"同一判据)。
    if (oneshotModelRaw !== undefined) {
      if (!cindy.text?.includes('oneshot')) {
        return {
          ok: false,
          reason: 'cindy.oneshotModel 必须与 text 含 "oneshot" 成对声明(它是快问快答的偏好模型)',
        };
      }
      cindy.oneshotModel = (oneshotModelRaw as string).trim();
    }
    if (Object.keys(cindy).filter((key) => key !== 'oneshotModel').length === 0) {
      return { ok: false, reason: 'cindy 能力详单不能是空对象' };
    }
    if (cindy.search?.includes('web') && (!slots.includes('tool') || tools === undefined)) {
      return {
        ok: false,
        reason: 'cindy.search.web 只允许由真实 tool-call 触发,必须同时声明 "tool" 槽和 tools',
      };
    }
  }

  // agent 槽详单:有槽无详单 = 仅允许真实用户点击触发;background 是
  // 独立高风险加档。写了详单却没申请槽属于清单自相矛盾。
  let agent: GhostAgentNeeds | undefined;
  if (raw.agent !== undefined) {
    if (!isPlainObject(raw.agent)) {
      return { ok: false, reason: 'agent 能力详单必须是对象(如 { "background": true })' };
    }
    if (!slots.includes('agent')) {
      return { ok: false, reason: '声明了 agent 能力详单但 slots 未包含 "agent"' };
    }
    const agentRaw = raw.agent as Record<string, unknown>;
    if (agentRaw.background !== undefined && typeof agentRaw.background !== 'boolean') {
      return { ok: false, reason: 'agent.background 必须是布尔值' };
    }
    if (agentRaw.errand !== undefined && typeof agentRaw.errand !== 'boolean') {
      return { ok: false, reason: 'agent.errand 必须是布尔值' };
    }
    if (!preserveHistoricalTasks && agentRaw.tasks !== undefined && typeof agentRaw.tasks !== 'boolean') {
      return { ok: false, reason: 'agent.tasks must be boolean' };
    }
    // hiddenTasks 依赖 tasks。已安装快照(preserveHistoricalTasks)不因历史值拒绝,
    // 非 true+true 组合只作为未知数据保留,运行期经 ghostDeclaresHiddenTasks 判定不授予。
    if (!preserveHistoricalTasks && agentRaw.hiddenTasks !== undefined) {
      if (typeof agentRaw.hiddenTasks !== 'boolean') {
        return { ok: false, reason: 'agent.hiddenTasks must be boolean' };
      }
      if (agentRaw.hiddenTasks === true && agentRaw.tasks !== true) {
        return { ok: false, reason: 'agent.hiddenTasks: true 需要同时声明 agent.tasks: true' };
      }
    }
    if (!preserveHistoricalTasks && agentRaw.targets !== undefined) {
      if (typeof agentRaw.targets !== 'boolean') return { ok: false, reason: 'agent.targets must be boolean' };
      if (agentRaw.targets === true && agentRaw.tasks !== true) {
        return { ok: false, reason: 'agent.targets: true 需要同时声明 agent.tasks: true' };
      }
    }
    if (agentRaw.schedule !== undefined && typeof agentRaw.schedule !== 'boolean') {
      return { ok: false, reason: 'agent.schedule 必须是布尔值' };
    }
    if (agentRaw.background !== true && agentRaw.errand !== true && agentRaw.schedule !== true && agentRaw.tasks !== true && Object.keys(unknownDeclarationFields(agentRaw, preserveHistoricalTasks ? ['background', 'errand', 'schedule'] : ['background', 'errand', 'schedule', 'tasks', 'hiddenTasks', 'targets'])).length === 0) {
      return {
        ok: false,
        reason:
          'agent 能力详单只有 background: true / errand: true / schedule: true / tasks: true 四项加档;仅需用户点击触发时请省略 agent 字段',
      };
    }
    agent = {
      ...unknownDeclarationFields(agentRaw, preserveHistoricalTasks ? ['background', 'errand', 'schedule'] : ['background', 'errand', 'schedule', 'tasks', 'hiddenTasks', 'targets']),
      ...(agentRaw.background === true ? { background: true } : {}),
      ...(agentRaw.errand === true ? { errand: true } : {}),
      ...(agentRaw.tasks === true ? { tasks: true } : {}),
      ...(agentRaw.tasks === true && agentRaw.targets === true ? { targets: true } : {}),
      ...(agentRaw.tasks === true && agentRaw.hiddenTasks === true ? { hiddenTasks: true } : {}),
      ...(agentRaw.schedule === true ? { schedule: true } : {}),
    };
  }

  // Node 只执行受控入口与固定协议;未知扩展保留为数据,不传入进程启动参数。
  let node: GhostNodeNeeds | undefined;
  if (raw.node !== undefined) {
    if (!isPlainObject(raw.node)) {
      return { ok: false, reason: 'node 能力详单必须是对象' };
    }
    if (!slots.includes('node')) {
      return { ok: false, reason: '声明了 node 能力详单但 slots 未包含 "node"' };
    }
    const nodeRaw = raw.node as Record<string, unknown>;
    if (!isSafeGhostRelativePath(nodeRaw.entry)) {
      return { ok: false, reason: 'node.entry 必须是安装目录内的安全相对路径' };
    }
    if (!/\.(?:c?js)$/.test(nodeRaw.entry)) {
      return { ok: false, reason: 'node.entry 必须是 CommonJS .js / .cjs 文件' };
    }
    if (nodeRaw.entry === raw.entry) {
      return { ok: false, reason: 'node.entry 不能与浏览器沙箱 entry 使用同一个文件' };
    }
    if (
      typeof nodeRaw.protocol !== 'string' ||
      !(GHOST_NODE_PROTOCOLS as readonly string[]).includes(nodeRaw.protocol)
    ) {
      return { ok: false, reason: `node.protocol 必须是 ${GHOST_NODE_PROTOCOLS.join(' / ')}` };
    }
    if (
      nodeRaw.lifecycle !== undefined &&
      (typeof nodeRaw.lifecycle !== 'string' ||
        !(GHOST_NODE_LIFECYCLES as readonly string[]).includes(nodeRaw.lifecycle))
    ) {
      return { ok: false, reason: `node.lifecycle 必须是 ${GHOST_NODE_LIFECYCLES.join(' / ')}` };
    }
    if (
      nodeRaw.idleTimeoutSeconds !== undefined &&
      (typeof nodeRaw.idleTimeoutSeconds !== 'number' ||
        !Number.isInteger(nodeRaw.idleTimeoutSeconds) ||
        nodeRaw.idleTimeoutSeconds < 30 ||
        nodeRaw.idleTimeoutSeconds > 3600)
    ) {
      return { ok: false, reason: 'node.idleTimeoutSeconds 必须是 30–3600 的整数' };
    }
    if (nodeRaw.lifecycle === 'resident' && nodeRaw.idleTimeoutSeconds !== undefined) {
      return { ok: false, reason: 'node.lifecycle 为 resident 时不能再声明 idleTimeoutSeconds' };
    }
    // 额外入口(多进程窄版):同一套入口纪律——包内安全相对路径、CJS 文件、
    // 不与浏览器沙箱 entry / 主入口 / 彼此重复;条数封顶。
    let nodeEntries: string[] | undefined;
    if (nodeRaw.entries !== undefined) {
      if (!Array.isArray(nodeRaw.entries) || nodeRaw.entries.length === 0) {
        return { ok: false, reason: 'node.entries 必须是非空数组(额外工作进程入口清单)' };
      }
      if (nodeRaw.entries.length > GHOST_NODE_MAX_EXTRA_ENTRIES) {
        return { ok: false, reason: `node.entries 最多 ${GHOST_NODE_MAX_EXTRA_ENTRIES} 条` };
      }
      const seen = new Set<string>();
      for (const extra of nodeRaw.entries) {
        if (!isSafeGhostRelativePath(extra)) {
          return { ok: false, reason: 'node.entries 每项必须是安装目录内的安全相对路径' };
        }
        if (!/\.(?:c?js)$/.test(extra)) {
          return { ok: false, reason: 'node.entries 每项必须是 CommonJS .js / .cjs 文件' };
        }
        if (extra === raw.entry) {
          return { ok: false, reason: 'node.entries 不能包含浏览器沙箱 entry' };
        }
        if (extra === nodeRaw.entry) {
          return { ok: false, reason: 'node.entries 不能重复主入口 node.entry' };
        }
        if (seen.has(extra)) {
          return { ok: false, reason: `node.entries 含重复入口 ${JSON.stringify(extra)}` };
        }
        seen.add(extra);
      }
      nodeEntries = nodeRaw.entries as string[];
    }
    if (nodeRaw.childSpawn !== undefined && typeof nodeRaw.childSpawn !== 'boolean') {
      return { ok: false, reason: 'node.childSpawn 必须是布尔值' };
    }
    let nodeSecretBindings: GhostNodeSecretBinding[] | undefined;
    if (nodeRaw.secretBindings !== undefined) {
      if (
        !Array.isArray(nodeRaw.secretBindings) ||
        nodeRaw.secretBindings.length === 0 ||
        nodeRaw.secretBindings.length > GHOST_NODE_MAX_SECRET_BINDINGS
      ) {
        return {
          ok: false,
          reason: `node.secretBindings 必须是 1–${GHOST_NODE_MAX_SECRET_BINDINGS} 条的数组`,
        };
      }
      if (raw.settingsHtml === undefined) {
        return {
          ok: false,
          reason: 'node.secretBindings 需要 settingsHtml 收集凭证',
        };
      }
      nodeSecretBindings = [];
      const seenSecretKeys = new Set<string>();
      for (const bindingRaw of nodeRaw.secretBindings) {
        if (!isPlainObject(bindingRaw)) {
          return { ok: false, reason: 'node.secretBindings 每项必须是对象' };
        }
        const binding = bindingRaw as Record<string, unknown>;
        if (typeof binding.key === 'string' && isGhostManifestReservedRecordKey(binding.key)) {
          return {
            ok: false,
            reason: `node.secretBindings[].key 不允许使用对象保留键名 ${JSON.stringify(binding.key)}`,
          };
        }
        if (typeof binding.key !== 'string' || !/^[a-z][a-z0-9_]{0,31}$/.test(binding.key)) {
          return {
            ok: false,
            reason: 'node.secretBindings[].key 必须是小写字母开头的 1–32 位小写/数字/下划线',
          };
        }
        if (seenSecretKeys.has(binding.key)) {
          return {
            ok: false,
            reason: `node.secretBindings 含重复 key ${JSON.stringify(binding.key)}`,
          };
        }
        seenSecretKeys.add(binding.key);
        if (
          typeof binding.label !== 'string' ||
          binding.label.trim().length === 0 ||
          binding.label.length > 64
        ) {
          return {
            ok: false,
            reason: 'node.secretBindings[].label 必须是 1–64 字符的非空字符串',
          };
        }
        if (
          !Array.isArray(binding.methods) ||
          binding.methods.length === 0 ||
          binding.methods.length > GHOST_NODE_MAX_SECRET_METHODS
        ) {
          return {
            ok: false,
            reason: `node.secretBindings[].methods 必须是 1–${GHOST_NODE_MAX_SECRET_METHODS} 条的数组`,
          };
        }
        const methods: string[] = [];
        for (const method of binding.methods) {
          if (typeof method !== 'string' || !/^[A-Za-z0-9_./:-]{1,128}$/.test(method)) {
            return {
              ok: false,
              reason: 'node.secretBindings[].methods 每项必须是 1–128 位安全方法名',
            };
          }
          if (nodeRaw.protocol === 'mcp-stdio' && isGhostNodeMcpReservedMethod(method)) {
            return {
              ok: false,
              reason: `node.secretBindings[].methods 不能绑定宿主保留的 MCP 方法 ${JSON.stringify(method)}`,
            };
          }
          if (methods.includes(method)) {
            return {
              ok: false,
              reason: `node.secretBindings[].methods 含重复方法 ${JSON.stringify(method)}`,
            };
          }
          methods.push(method);
        }
        let bindingEntry: string | undefined;
        if (binding.entry !== undefined) {
          if (
            typeof binding.entry !== 'string' ||
            (binding.entry !== nodeRaw.entry && !(nodeEntries ?? []).includes(binding.entry))
          ) {
            return {
              ok: false,
              reason: 'node.secretBindings[].entry 必须逐字命中 node.entry 或 node.entries',
            };
          }
          bindingEntry = binding.entry;
        }
        if (
          binding.hint !== undefined &&
          (typeof binding.hint !== 'string' ||
            binding.hint.trim().length === 0 ||
            binding.hint.length > 200)
        ) {
          return {
            ok: false,
            reason: 'node.secretBindings[].hint 必须是 1–200 字符的非空字符串',
          };
        }
        if (binding.url !== undefined) {
          if (
            typeof binding.url !== 'string' ||
            binding.url.length === 0 ||
            binding.url.length > 200
          ) {
            return {
              ok: false,
              reason: 'node.secretBindings[].url 必须是 1–200 字符的字符串',
            };
          }
          let parsed: URL;
          try {
            parsed = new URL(binding.url);
          } catch {
            return { ok: false, reason: 'node.secretBindings[].url 不是合法的绝对地址' };
          }
          if (parsed.protocol !== 'https:' || parsed.username || parsed.password) {
            return {
              ok: false,
              reason: 'node.secretBindings[].url 仅支持 https 且不允许内嵌用户名/密码',
            };
          }
        }
        if (binding.oauthSecret !== undefined &&
          (typeof binding.oauthSecret !== 'string' || !/^[a-z][a-z0-9_]{0,31}$/.test(binding.oauthSecret))) {
          return { ok: false, reason: 'node.secretBindings[].oauthSecret 必须是本插件 OAuth 凭证键' };
        }
        nodeSecretBindings.push({
          ...unknownDeclarationFields(binding, ['key', 'label', 'methods', 'entry', 'hint', 'url', 'oauthSecret']),
          ...(binding.oauthSecret !== undefined ? { oauthSecret: binding.oauthSecret as string } : {}),
          key: binding.key,
          label: binding.label,
          methods,
          ...(bindingEntry !== undefined ? { entry: bindingEntry } : {}),
          ...(binding.hint !== undefined ? { hint: binding.hint as string } : {}),
          ...(binding.url !== undefined ? { url: binding.url as string } : {}),
        });
      }
    }
    node = {
      ...unknownDeclarationFields(nodeRaw, ['entry', 'protocol', 'lifecycle', 'idleTimeoutSeconds', 'entries', 'childSpawn', 'secretBindings']),
      entry: nodeRaw.entry,
      protocol: nodeRaw.protocol as GhostNodeProtocol,
      ...(nodeRaw.lifecycle !== undefined
        ? { lifecycle: nodeRaw.lifecycle as GhostNodeLifecycle }
        : {}),
      ...(nodeRaw.idleTimeoutSeconds !== undefined
        ? { idleTimeoutSeconds: nodeRaw.idleTimeoutSeconds }
        : {}),
      ...(nodeEntries !== undefined ? { entries: nodeEntries } : {}),
      ...(nodeRaw.childSpawn !== undefined ? { childSpawn: nodeRaw.childSpawn } : {}),
      ...(nodeSecretBindings !== undefined ? { secretBindings: nodeSecretBindings } : {}),
    };
  }
  if (slots.includes('node') && node === undefined) {
    return { ok: false, reason: 'slots 声明了 "node" 但缺少 node 工作进程详单' };
  }

  // preview 槽详单:与 slots 含 'preview' **严格成对**(有槽必有详单——域名
  // 范围是本能力的全部知情面,不允许"先装后说");域名语法与 network 白名单
  // 同一套(插件详情逐条展示)。
  let preview: GhostPreviewNeeds | undefined;
  if (raw.preview !== undefined) {
    if (!isPlainObject(raw.preview)) {
      return { ok: false, reason: 'preview 详单必须是对象(如 { "hosts": ["*.example.com"] })' };
    }
    if (!slots.includes('preview')) {
      return { ok: false, reason: '声明了 preview 详单但 slots 未包含 "preview"' };
    }
    const previewRaw = raw.preview as Record<string, unknown>;
    if (!Array.isArray(previewRaw.hosts) || previewRaw.hosts.length === 0) {
      return { ok: false, reason: 'preview.hosts 必须是非空数组(可打开预览的域名白名单)' };
    }
    if (previewRaw.hosts.length > GHOST_PREVIEW_MAX_HOSTS) {
      return { ok: false, reason: `preview.hosts 最多 ${GHOST_PREVIEW_MAX_HOSTS} 条` };
    }
    const seenPreviewHosts = new Set<string>();
    for (const host of previewRaw.hosts) {
      if (
        !isValidGhostNetworkHostPattern(host) &&
        !(typeof host === 'string' && GHOST_PREVIEW_LOOPBACK_HOSTS.has(host))
      ) {
        return { ok: false, reason: `preview.hosts 含不合法域名模式 ${JSON.stringify(host)}` };
      }
      if (seenPreviewHosts.has(host)) {
        return { ok: false, reason: `preview.hosts 含重复域名 ${JSON.stringify(host)}` };
      }
      seenPreviewHosts.add(host);
    }
    preview = { ...unknownDeclarationFields(previewRaw, ['hosts']), hosts: previewRaw.hosts as string[] };
  }
  if (slots.includes('preview') && preview === undefined) {
    return {
      ok: false,
      reason: 'slots 声明了 "preview" 但缺少 preview 详单(hosts 域名白名单必填)',
    };
  }

  // browserExtension 槽详单(v3 直接字段,v2 没有对应 slot):允许连接的扩展 id
  // 是全部知情面,装入时钉死;协议标识必须是当前宿主实现的版本,未来协议由
  // 新宿主识别后再放行,不按名字猜。
  let browserExtension: GhostBrowserExtensionNeeds | undefined;
  if (raw.browserExtension !== undefined) {
    if (!isPlainObject(raw.browserExtension)) {
      return { ok: false, reason: 'browserExtension 详单必须是对象(如 { "protocol": "cindy-browser-extension/3", "extensionIds": [...] })' };
    }
    const needsRaw = raw.browserExtension as Record<string, unknown>;
    if (needsRaw.protocol !== GHOST_BROWSER_EXTENSION_PROTOCOL) {
      return { ok: false, reason: `browserExtension.protocol 必须是 ${JSON.stringify(GHOST_BROWSER_EXTENSION_PROTOCOL)}` };
    }
    if (!Array.isArray(needsRaw.extensionIds) || needsRaw.extensionIds.length === 0) {
      return { ok: false, reason: 'browserExtension.extensionIds 必须是非空数组(允许连接的扩展 id)' };
    }
    if (needsRaw.extensionIds.length > GHOST_BROWSER_EXTENSION_MAX_IDS) {
      return { ok: false, reason: `browserExtension.extensionIds 最多 ${GHOST_BROWSER_EXTENSION_MAX_IDS} 条` };
    }
    const seenExtensionIds = new Set<string>();
    for (const id of needsRaw.extensionIds) {
      if (typeof id !== 'string' || !GHOST_BROWSER_EXTENSION_ID_RE.test(id)) {
        return { ok: false, reason: `browserExtension.extensionIds 含不合法扩展 id ${JSON.stringify(id)}` };
      }
      if (seenExtensionIds.has(id)) {
        return { ok: false, reason: `browserExtension.extensionIds 含重复扩展 id ${JSON.stringify(id)}` };
      }
      seenExtensionIds.add(id);
    }
    let nativeHost: GhostBrowserExtensionNeeds['nativeHost'];
    if (needsRaw.nativeHost !== undefined) {
      if (!isPlainObject(needsRaw.nativeHost)) {
        return { ok: false, reason: 'browserExtension.nativeHost 必须是对象(如 { "name": "com.example.browser", "binary": "native-host/bin" })' };
      }
      const nativeRaw = needsRaw.nativeHost as Record<string, unknown>;
      if (
        typeof nativeRaw.name !== 'string' ||
        nativeRaw.name.length > 128 ||
        !GHOST_BROWSER_EXTENSION_NATIVE_HOST_RE.test(nativeRaw.name)
      ) {
        return { ok: false, reason: 'browserExtension.nativeHost.name 必须是点分小写字母、数字、下划线的 Native Messaging host 名' };
      }
      if (!isPortableGhostRelativePath(nativeRaw.binary)) {
        return { ok: false, reason: 'browserExtension.nativeHost.binary 必须是包内相对路径(平台二进制目录)' };
      }
      nativeHost = {
        ...unknownDeclarationFields(nativeRaw, ['name', 'binary']),
        name: nativeRaw.name,
        binary: nativeRaw.binary,
      };
    }
    if (needsRaw.pageControl !== undefined && needsRaw.pageControl !== true) {
      return { ok: false, reason: 'browserExtension.pageControl 只能省略或为字面量 true' };
    }
    let pageControlReplaces: { tools: string[]; manual?: string[] } | undefined;
    if (needsRaw.pageControlReplaces !== undefined) {
      const raw = needsRaw.pageControlReplaces as Record<string, unknown> | null;
      const names = (value: unknown) =>
        Array.isArray(value) &&
        value.length <= 32 &&
        value.every((name) => typeof name === 'string' && /^[A-Za-z0-9_.-]{1,64}$/.test(name));
      if (
        needsRaw.pageControl !== true ||
        !raw ||
        typeof raw !== 'object' ||
        Array.isArray(raw) ||
        !names(raw.tools) ||
        (raw.manual !== undefined && !names(raw.manual))
      ) {
        return {
          ok: false,
          reason: 'browserExtension.pageControlReplaces 须与 pageControl 同时声明,形如 {tools:[名称…], manual?:[名称…]}',
        };
      }
      pageControlReplaces = {
        tools: [...(raw.tools as string[])],
        ...(raw.manual !== undefined ? { manual: [...(raw.manual as string[])] } : {}),
      };
    }
    browserExtension = {
      ...unknownDeclarationFields(needsRaw, ['protocol', 'extensionIds', 'nativeHost', 'pageControl', 'pageControlReplaces']),
      protocol: GHOST_BROWSER_EXTENSION_PROTOCOL,
      extensionIds: needsRaw.extensionIds as string[],
      ...(nativeHost !== undefined ? { nativeHost } : {}),
      ...(needsRaw.pageControl === true ? { pageControl: true as const } : {}),
      ...(pageControlReplaces !== undefined ? { pageControlReplaces } : {}),
    };
  }

  // skill 槽详单:与 slots 含 'skill' **严格成对**(有槽必有详单——捆绑了什么
  // 技能是本能力的全部知情面)。name/description 与 SKILL.md 的逐字一致性在
  // 打包(packGhostDir)与装入(GhostManager.parse)两侧另行强制,这里只管
  // 声明本身的形状。name/dir 大小写折叠去重:win32 文件系统折叠大小写,
  // 插件私有技能根的链接名不允许折叠后相撞。
  let skill: GhostSkillNeeds | undefined;
  if (raw.skill !== undefined) {
    if (!isPlainObject(raw.skill)) {
      return {
        ok: false,
        reason:
          'skill 详单必须是对象(如 { "items": [{ "dir": "skills/foo", "name": "foo", "description": "..." }] })',
      };
    }
    if (!slots.includes('skill')) {
      return { ok: false, reason: '声明了 skill 详单但 slots 未包含 "skill"' };
    }
    const skillRaw = raw.skill as Record<string, unknown>;
    if (!Array.isArray(skillRaw.items) || skillRaw.items.length === 0) {
      return { ok: false, reason: 'skill.items 必须是非空数组(随包捆绑的技能清单)' };
    }
    if (skillRaw.items.length > GHOST_SKILL_MAX_ITEMS) {
      return { ok: false, reason: `skill.items 最多 ${GHOST_SKILL_MAX_ITEMS} 条` };
    }
    const skillItems: GhostSkillItem[] = [];
    const seenSkillNames = new Set<string>();
    const seenSkillDirs = new Set<string>();
    for (const item of skillRaw.items) {
      if (!isPlainObject(item)) {
        return { ok: false, reason: 'skill.items 每项必须是对象({ dir, name, description })' };
      }
      const itemRaw = item as Record<string, unknown>;
      if (!isSafeGhostRelativePath(itemRaw.dir)) {
        return {
          ok: false,
          reason: `skill.items[].dir 必须是包内安全相对路径(如 "skills/foo"),得到 ${JSON.stringify(itemRaw.dir)}`,
        };
      }
      if (
        typeof itemRaw.name !== 'string' ||
        itemRaw.name.length > GHOST_SKILL_NAME_MAX_CHARS ||
        !GHOST_SKILL_NAME_RE.test(itemRaw.name)
      ) {
        return {
          ok: false,
          reason: `skill.items[].name 必须是小写字母/数字加单连字符分段(禁首尾/连续连字符)、长度 1–${GHOST_SKILL_NAME_MAX_CHARS},得到 ${JSON.stringify(itemRaw.name)}`,
        };
      }
      if (
        typeof itemRaw.description !== 'string' ||
        itemRaw.description.trim().length === 0 ||
        itemRaw.description.length > 1024
      ) {
        return { ok: false, reason: 'skill.items[].description 必须是 1–1024 字符的非空字符串' };
      }
      const nameFold = itemRaw.name.toLowerCase();
      if (seenSkillNames.has(nameFold)) {
        return { ok: false, reason: `skill.items 含重复 name ${JSON.stringify(itemRaw.name)}` };
      }
      seenSkillNames.add(nameFold);
      const dirFold = itemRaw.dir.toLowerCase();
      if (seenSkillDirs.has(dirFold)) {
        return { ok: false, reason: `skill.items 含重复 dir ${JSON.stringify(itemRaw.dir)}` };
      }
      seenSkillDirs.add(dirFold);
      skillItems.push({ ...unknownDeclarationFields(itemRaw, ['dir', 'name', 'description']), dir: itemRaw.dir, name: itemRaw.name, description: itemRaw.description });
    }
    skill = { ...unknownDeclarationFields(skillRaw, ['items']), items: skillItems };
  }
  if (slots.includes('skill') && skill === undefined) {
    return { ok: false, reason: 'slots 声明了 "skill" 但缺少 skill 详单(items 技能清单必填)' };
  }

  // manual 是独立顶层字段,不是能力 slot 或授权项。这里只校验一级逻辑索引;
  // MANUAL.md 存在性、Markdown 文本与逐文件 64KB 上限由打包/装入两侧校验。
  let manual: GhostManualNeeds | undefined;
  if (raw.manual !== undefined) {
    if (!isPlainObject(raw.manual)) {
      return {
        ok: false,
        reason:
          'manual 必须是对象(如 { "items": [{ "dir": "manual/getting-started", "name": "getting-started", "description": "..." }] })',
      };
    }
    const manualRaw = raw.manual as Record<string, unknown>;
    if (!Array.isArray(manualRaw.items) || manualRaw.items.length === 0) {
      return { ok: false, reason: 'manual.items 必须是非空数组(随包手册索引)' };
    }
    if (manualRaw.items.length > GHOST_MANUAL_MAX_ITEMS) {
      return { ok: false, reason: `manual.items 最多 ${GHOST_MANUAL_MAX_ITEMS} 条` };
    }
    const manualItems: GhostManualItem[] = [];
    const seenManualNames = new Set<string>();
    const seenManualDirs = new Set<string>();
    for (const item of manualRaw.items) {
      if (!isPlainObject(item)) {
        return { ok: false, reason: 'manual.items 每项必须是对象({ dir, name, description })' };
      }
      const itemRaw = item as Record<string, unknown>;
      if (!isSafeGhostRelativePath(itemRaw.dir)) {
        return {
          ok: false,
          reason: `manual.items[].dir 必须是包内安全相对路径(如 "manual/getting-started"),得到 ${JSON.stringify(itemRaw.dir)}`,
        };
      }
      const dirFold = itemRaw.dir.toLowerCase();
      if (declaredFilePathFolds.some((path) => pathsConflict(dirFold, path))) {
        return {
          ok: false,
          reason: `manual.items[].dir ${JSON.stringify(itemRaw.dir)} 与插件声明文件路径大小写折叠后冲突`,
        };
      }
      if (
        typeof itemRaw.name !== 'string' ||
        itemRaw.name.length > GHOST_SKILL_NAME_MAX_CHARS ||
        !GHOST_SKILL_NAME_RE.test(itemRaw.name)
      ) {
        return {
          ok: false,
          reason: `manual.items[].name 必须是小写字母/数字加单连字符分段(禁首尾/连续连字符)、长度 1–${GHOST_SKILL_NAME_MAX_CHARS},得到 ${JSON.stringify(itemRaw.name)}`,
        };
      }
      if (
        typeof itemRaw.description !== 'string' ||
        itemRaw.description.trim().length === 0 ||
        itemRaw.description.length > GHOST_MANUAL_DESCRIPTION_MAX_CHARS
      ) {
        return {
          ok: false,
          reason: `manual.items[].description 必须是 1–${GHOST_MANUAL_DESCRIPTION_MAX_CHARS} 字符的非空字符串`,
        };
      }
      const nameFold = itemRaw.name.toLowerCase();
      if (seenManualNames.has(nameFold)) {
        return { ok: false, reason: `manual.items 含重复 name ${JSON.stringify(itemRaw.name)}` };
      }
      seenManualNames.add(nameFold);
      if (seenManualDirs.has(dirFold)) {
        return { ok: false, reason: `manual.items 含重复 dir ${JSON.stringify(itemRaw.dir)}` };
      }
      seenManualDirs.add(dirFold);
      manualItems.push({ ...unknownDeclarationFields(itemRaw, ['dir', 'name', 'description']),
        dir: itemRaw.dir,
        name: itemRaw.name,
        description: itemRaw.description,
      });
    }
    manual = { ...unknownDeclarationFields(manualRaw, ['items']), items: manualItems };
  }

  // 订阅槽详单(卡槽①):与 slots 含 'subscribe' 成对(有详单必有槽;有槽
  // 无详单允许装入但零事件,同 cindy 语义)。硬规则:声明了 hooks(拦截)
  // 必须 launch:'resident'——要挡路就得常驻在场,每条消息等冷启动不可接受。
  if (raw.routineEvents !== undefined && prepared.schemaVersion !== 3) {
    return { ok: false, reason: 'routineEvents requires schemaVersion 3' };
  }
  const routineEvents = raw.routineEvents === undefined ? undefined : parseGhostRoutineEvents(raw.routineEvents);
  if (routineEvents === null) return { ok: false, reason: 'Invalid routineEvents declaration' };
  let subscribe: GhostSubscribeNeeds | undefined;
  if (raw.subscribe !== undefined) {
    if (!isPlainObject(raw.subscribe)) {
      return { ok: false, reason: 'subscribe 订阅详单必须是对象(如 { "topics": ["turn"] })' };
    }
    if (!slots.includes('subscribe')) {
      return { ok: false, reason: '声明了 subscribe 订阅详单但 slots 未包含 "subscribe"' };
    }
    const subRaw = raw.subscribe as Record<string, unknown>;
    subscribe = unknownDeclarationFields(subRaw, ['topics', 'hooks']);
    for (const field of ['topics', 'hooks'] as const) {
      const listRaw = subRaw[field];
      if (listRaw === undefined) continue;
      if (!Array.isArray(listRaw) || listRaw.length === 0) {
        return { ok: false, reason: `subscribe.${field} 必须是非空数组` };
      }
      const list: string[] = [];
      for (const item of listRaw) {
        if (typeof item !== 'string' || !GHOST_SLOT_NAME_RE.test(item)) {
          return {
            ok: false,
            reason: `subscribe.${field} 必须包含合法的事件标识: ${JSON.stringify(item)}`,
          };
        }
        if (list.includes(item)) {
          return { ok: false, reason: `subscribe.${field} 含重复项 ${JSON.stringify(item)}` };
        }
        list.push(item);
      }
      if (field === 'topics') subscribe.topics = list as GhostSubscribeTopic[];
      else subscribe.hooks = list as GhostSubscribeHook[];
    }
    if (Object.keys(subscribe).length === 0) {
      return { ok: false, reason: 'subscribe 订阅详单不能是空对象' };
    }
    if (subscribe.hooks?.some((hook) => (GHOST_SUBSCRIBE_HOOKS as readonly string[]).includes(hook)) && raw.launch !== 'resident') {
      return {
        ok: false,
        reason:
          '声明了 subscribe.hooks(拦截钩子)必须同时声明 launch: "resident"——拦截要求常驻在场,否则每条消息都要等冷启动',
      };
    }
  }

  // network 槽详单:与 slots 含 'network' 成对(有详单必有槽;有槽
  // 无详单允许装入但零能力,同 cindy / subscribe 语义)。hosts 是核心声明;
  // secrets 每条必须带 inject(没有注入位置的凭证无处可用),inject.hosts
  // 必须是 hosts 声明条目的子集——结构上钉死"key 只流向它声明的域名"。
  let network: GhostNetworkNeeds | undefined;
  if (raw.network !== undefined) {
    if (!isPlainObject(raw.network)) {
      return { ok: false, reason: 'network 详单必须是对象(如 { "hosts": ["api.example.com"] })' };
    }
    if (!slots.includes('network')) {
      return { ok: false, reason: '声明了 network 详单但 slots 未包含 "network"' };
    }
    const n = raw.network as Record<string, unknown>;
    // 连接声明在场性先探一眼(合法性下面细验):静态 hosts 的必填性依赖它——
    // 声明了 connections(动态连接地址)时 hosts 允许缺省/空数组,否则维持
    // 原规则必填 1–8 条(静态域名与动态连接至少有其一)。
    const hasConnectionDecls = Array.isArray(n.connections) && n.connections.length > 0;
    if (n.hosts === undefined && !hasConnectionDecls) {
      return {
        ok: false,
        reason: `network.hosts 必须是 1–${GHOST_NETWORK_MAX_HOSTS} 条的数组(仅声明了 network.connections 时才可缺省)`,
      };
    }
    if (
      n.hosts !== undefined &&
      (!Array.isArray(n.hosts) || n.hosts.length > GHOST_NETWORK_MAX_HOSTS)
    ) {
      return { ok: false, reason: `network.hosts 必须是 1–${GHOST_NETWORK_MAX_HOSTS} 条的数组` };
    }
    if (Array.isArray(n.hosts) && n.hosts.length === 0 && !hasConnectionDecls) {
      return {
        ok: false,
        reason: `network.hosts 必须是 1–${GHOST_NETWORK_MAX_HOSTS} 条的数组(仅声明了 network.connections 时才允许为空)`,
      };
    }
    const hosts: string[] = [];
    for (const h of Array.isArray(n.hosts) ? n.hosts : []) {
      if (typeof h !== 'string' || !isValidGhostNetworkHostPattern(h.trim().toLowerCase())) {
        return {
          ok: false,
          reason: `network.hosts 含非法条目 ${JSON.stringify(h)}(小写域名、至少两段、通配只允许最左 "*.";不收 IP / 端口 / 路径 / 协议)`,
        };
      }
      const host = h.trim().toLowerCase();
      if (hosts.includes(host)) {
        return { ok: false, reason: `network.hosts 含重复条目 ${JSON.stringify(h)}` };
      }
      hosts.push(host);
    }
    let secrets: GhostSecretDecl[] | undefined;
    if (n.secrets !== undefined) {
      if (
        !Array.isArray(n.secrets) ||
        n.secrets.length === 0 ||
        n.secrets.length > GHOST_NETWORK_MAX_SECRETS
      ) {
        return {
          ok: false,
          reason: `network.secrets 必须是 1–${GHOST_NETWORK_MAX_SECRETS} 条的数组`,
        };
      }
      secrets = [];
      const seenKeys = new Set<string>();
      for (const s of n.secrets) {
        if (!isPlainObject(s)) return { ok: false, reason: 'network.secrets 每项必须是对象' };
        if (typeof s.key === 'string' && isGhostManifestReservedRecordKey(s.key)) {
          return {
            ok: false,
            reason: `network.secrets[].key 不允许使用对象保留键名 ${JSON.stringify(s.key)}`,
          };
        }
        if (typeof s.key !== 'string' || !/^[a-z][a-z0-9_]{0,31}$/.test(s.key)) {
          return {
            ok: false,
            reason: 'network.secrets[].key 必须是小写字母开头的 1–32 位小写/数字/下划线',
          };
        }
        if (seenKeys.has(s.key)) {
          return { ok: false, reason: `network.secrets 含重复 key ${JSON.stringify(s.key)}` };
        }
        if (node?.secretBindings?.some((binding) => binding.key === s.key)) {
          return {
            ok: false,
            reason: `network.secrets 的 key ${JSON.stringify(s.key)} 与 node.secretBindings 撞名`,
          };
        }
        seenKeys.add(s.key);
        if (typeof s.label !== 'string' || s.label.trim().length === 0 || s.label.length > 64) {
          return { ok: false, reason: 'network.secrets[].label 必须是 1–64 字符的非空字符串' };
        }
        // 来源:缺省 'user';login-email / oauth / gh-cli / oidc-token 均由主机托管。
        // 归一化:'user' 不落清单(与缺省同义,权限 diff 不 churn)。
        let source: GhostSecretSource | undefined;
        if (s.source !== undefined) {
          if (
            typeof s.source !== 'string' ||
            !(GHOST_SECRET_SOURCES as readonly string[]).includes(s.source)
          ) {
            return {
              ok: false,
              reason: `network.secrets[].source 仅支持 ${GHOST_SECRET_SOURCES.join(' / ')}(缺省 user)`,
            };
          }
          if (s.source === 'login-email') source = 'login-email';
          if (s.source === 'oauth') source = 'oauth';
          if (s.source === 'gh-cli') source = 'gh-cli';
          if (s.source === 'oidc-token') source = 'oidc-token';
        }
        // 旧 input 字段已退役:Setup Runtime 直接从 Secret 声明生成 Host 表单,
        // settingsHtml 继续提供详情页管理。遗留 `input: "ghost"` 接受并忽略
        // (不落清单);其余值(含 'host')一律拒。
        if (s.input !== undefined && s.input !== 'ghost') {
          return {
            ok: false,
            reason:
              'network.secrets[].input 已退役:Setup 表单直接从 Secret 声明生成,详情页由 settingsHtml 管理(删掉 input 字段即可;唯一可接受的遗留值是 "ghost")',
          };
        }
        // login-email:值取自主机登录态派生,用户不填、没有输入面,
        // 禁 url / exchange,settingsHtml 豁免。
        const hostDerived = source === 'login-email' || source === 'oidc-token';
        if (s.input === 'ghost' && hostDerived) {
          return {
            ok: false,
            reason: `source: ${source} 的凭证不允许标注 input: ghost(派生凭证没有输入,谈不上谁收单)`,
          };
        }
        if (!hostDerived && raw.settingsHtml === undefined) {
          return {
            ok: false,
            reason:
              'network.secrets 声明了用户填写的凭证时必须同时声明 settingsHtml(调用前可由 Host Setup 卡收单,settingsHtml 仍是长期管理/替换/清除入口)',
          };
        }
        if (hostDerived && s.url !== undefined) {
          return {
            ok: false,
            reason: `network.secrets[].source 为 ${source} 时不允许声明 url(值取自主机登录态,没有"前往控制台"可去)`,
          };
        }
        if (hostDerived && s.exchange !== undefined) {
          // 组合会把登录态凭证作为原始值 POST 给交换端点,而确认框文案只
          // 承诺"派生注入请求头"——语义盖不住,结构上禁掉(有真实场景再议)。
          return {
            ok: false,
            reason: `network.secrets[].source 为 ${source} 时不允许声明 exchange(登录态凭证不外送交换端点)`,
          };
        }
        if (source === 'gh-cli' && s.exchange !== undefined) {
          return {
            ok: false,
            reason:
              'network.secrets[].source 为 gh-cli 时不允许声明 exchange(GitHub token 只能直接注入 GitHub API)',
          };
        }
        if (
          s.hint !== undefined &&
          (typeof s.hint !== 'string' || s.hint.trim().length === 0 || s.hint.length > 200)
        ) {
          return { ok: false, reason: 'network.secrets[].hint 必须是 1–200 字符的非空字符串' };
        }
        if (s.url !== undefined) {
          if (typeof s.url !== 'string' || s.url.length === 0 || s.url.length > 200) {
            return { ok: false, reason: 'network.secrets[].url 必须是 1–200 字符的字符串' };
          }
          let parsed: URL;
          try {
            parsed = new URL(s.url);
          } catch {
            return { ok: false, reason: 'network.secrets[].url 不是合法的绝对地址' };
          }
          if (parsed.protocol !== 'https:' || parsed.username || parsed.password) {
            return {
              ok: false,
              reason: 'network.secrets[].url 仅支持 https 且不允许内嵌用户名/密码',
            };
          }
        }
        if (!isPlainObject(s.inject)) {
          return {
            ok: false,
            reason: `network.secrets[${JSON.stringify(s.key)}].inject 必填(凭证要声明注入到哪个请求头)`,
          };
        }
        const inj = s.inject as Record<string, unknown>;
        if (typeof inj.header !== 'string' || !/^[A-Za-z0-9-]{1,64}$/.test(inj.header)) {
          return {
            ok: false,
            reason: 'network.secrets[].inject.header 必须是 1–64 位字母/数字/连字符的头名',
          };
        }
        if (GHOST_NETWORK_FORBIDDEN_INJECT_HEADERS.includes(inj.header.toLowerCase())) {
          return {
            ok: false,
            reason: `network.secrets[].inject.header 不允许使用协议关键头 ${JSON.stringify(inj.header)}`,
          };
        }
        if (
          typeof inj.format !== 'string' ||
          inj.format.length === 0 ||
          inj.format.length > 200 ||
          inj.format.split('{value}').length !== 2
        ) {
          return {
            ok: false,
            reason:
              'network.secrets[].inject.format 必须是 ≤200 字符且恰含一个 {value} 占位的字符串(如 "Bearer {value}")',
          };
        }
        let injectHosts: string[] | undefined;
        if (inj.hosts !== undefined) {
          if (!Array.isArray(inj.hosts) || inj.hosts.length === 0) {
            return {
              ok: false,
              reason: 'network.secrets[].inject.hosts 必须是非空数组(或省略 = 全部白名单域名)',
            };
          }
          injectHosts = [];
          for (const ih of inj.hosts) {
            if (typeof ih !== 'string' || !hosts.includes(ih.trim().toLowerCase())) {
              return {
                ok: false,
                reason: `network.secrets[].inject.hosts 含 ${JSON.stringify(ih)}——必须逐字取自 network.hosts 声明条目`,
              };
            }
            const ihNorm = ih.trim().toLowerCase();
            if (injectHosts.includes(ihNorm)) {
              return {
                ok: false,
                reason: `network.secrets[].inject.hosts 含重复条目 ${JSON.stringify(ih)}`,
              };
            }
            injectHosts.push(ihNorm);
          }
        }
        if (source === 'oidc-token') {
          if (inj.header !== 'Authorization' || inj.format !== 'Bearer {value}') {
            return {
              ok: false,
              reason:
                'network.secrets[].source 为 oidc-token 时 inject 必须是 Authorization: Bearer {value}',
            };
          }
          if (injectHosts === undefined) {
            return {
              ok: false,
              reason:
                'network.secrets[].source 为 oidc-token 时必须显式声明非空 inject.hosts,限制企业身份令牌的流向',
            };
          }
          if (injectHosts.some((host) => host.startsWith('*.'))) {
            return {
              ok: false,
              reason:
                'network.secrets[].source 为 oidc-token 时 inject.hosts 只允许精确域名,不允许通配',
            };
          }
        }
        if (source === 'gh-cli') {
          if (raw.id !== 'cindy-github') {
            return {
              ok: false,
              reason: 'network.secrets[].source 为 gh-cli 时仅允许官方 cindy-github 插件使用',
            };
          }
          if (
            inj.header !== 'Authorization' ||
            inj.format !== 'Bearer {value}' ||
            injectHosts?.length !== 1 ||
            injectHosts[0] !== 'api.github.com'
          ) {
            return {
              ok: false,
              reason:
                'network.secrets[].source 为 gh-cli 时 inject 必须固定为 api.github.com 的 Authorization: Bearer {value}',
            };
          }
        }
        // oauth(source: 'oauth' 时必填):主机托管 OAuth 授权详单。授权页与
        // token 端点域名都必须落在 hosts 白名单内——确认框展示的域名集合就是
        // 全部出网面(clientSecret 只流向 tokenUrl,授权只发生在 authorizeUrl)。
        let oauth: GhostSecretOauthDecl | undefined;
        if (source === 'oauth' && s.oauth === undefined) {
          return {
            ok: false,
            reason: `network.secrets[${JSON.stringify(s.key)}].oauth 必填(source: oauth 的凭证要声明去哪授权)`,
          };
        }
        if (source !== 'oauth' && s.oauth !== undefined) {
          return {
            ok: false,
            reason: 'network.secrets[].oauth 仅允许在 source: oauth 的凭证上声明',
          };
        }
        if (source === 'oauth' && s.exchange !== undefined) {
          // access token 已是最终注入物,再叠一段 key 换令牌没有语义。
          return {
            ok: false,
            reason:
              'network.secrets[].source 为 oauth 时不允许声明 exchange(access token 直接注入,无二段交换)',
          };
        }
        if (s.oauth !== undefined) {
          if (!isPlainObject(s.oauth)) {
            return {
              ok: false,
              reason: `network.secrets[${JSON.stringify(s.key)}].oauth 必须是对象`,
            };
          }
          const oa = s.oauth as Record<string, unknown>;
          const parseHostBoundUrl = (
            raw2: unknown,
            field: string,
          ): { ok: true; url: string } | { ok: false; reason: string } => {
            if (typeof raw2 !== 'string' || raw2.length === 0 || raw2.length > 2048) {
              return {
                ok: false,
                reason: `network.secrets[].oauth.${field} 必须是 1–2048 字符的字符串`,
              };
            }
            let parsed2: URL;
            try {
              parsed2 = new URL(raw2);
            } catch {
              return { ok: false, reason: `network.secrets[].oauth.${field} 不是合法的绝对地址` };
            }
            if (
              parsed2.protocol !== 'https:' ||
              parsed2.port !== '' ||
              parsed2.username ||
              parsed2.password
            ) {
              return {
                ok: false,
                reason: `network.secrets[].oauth.${field} 仅支持 https 默认端口且不允许内嵌用户名/密码`,
              };
            }
            if (!hosts.some((pattern) => ghostNetworkHostMatches(pattern, parsed2.hostname))) {
              return {
                ok: false,
                reason: `network.secrets[].oauth.${field} 的域名 ${JSON.stringify(parsed2.hostname)} 必须命中 network.hosts 白名单`,
              };
            }
            return { ok: true, url: raw2 };
          };
          const authorizeParsed = parseHostBoundUrl(oa.authorizeUrl, 'authorizeUrl');
          if (!authorizeParsed.ok) return authorizeParsed;
          const tokenParsed = parseHostBoundUrl(oa.tokenUrl, 'tokenUrl');
          if (!tokenParsed.ok) return tokenParsed;
          // 内置 client 凭证(可选,成对语义:secret 不许孤儿声明)。
          if (oa.clientId !== undefined) {
            if (
              typeof oa.clientId !== 'string' ||
              oa.clientId.trim().length === 0 ||
              oa.clientId.length > 200 ||
              /\s/.test(oa.clientId)
            ) {
              return {
                ok: false,
                reason: 'network.secrets[].oauth.clientId 必须是 1–200 字符、不含空白的字符串',
              };
            }
          }
          let oaClientIdAlternatives: string[] | undefined;
          if (oa.clientIdAlternatives !== undefined) {
            if (oa.clientId === undefined) {
              return {
                ok: false,
                reason: 'network.secrets[].oauth.clientIdAlternatives 必须与默认 clientId 一起声明',
              };
            }
            if (
              !Array.isArray(oa.clientIdAlternatives) ||
              oa.clientIdAlternatives.length === 0 ||
              oa.clientIdAlternatives.length > GHOST_OAUTH_CLIENT_ID_ALTERNATIVES_MAX
            ) {
              return {
                ok: false,
                reason: `network.secrets[].oauth.clientIdAlternatives 必须是 1–${GHOST_OAUTH_CLIENT_ID_ALTERNATIVES_MAX} 条的数组`,
              };
            }
            oaClientIdAlternatives = [];
            for (const clientId of oa.clientIdAlternatives) {
              if (
                typeof clientId !== 'string' ||
                clientId.trim().length === 0 ||
                clientId.length > 200 ||
                /\s/.test(clientId)
              ) {
                return {
                  ok: false,
                  reason:
                    'network.secrets[].oauth.clientIdAlternatives 含非法条目(须为 1–200 字符、不含空白的字符串)',
                };
              }
              if (clientId === oa.clientId || oaClientIdAlternatives.includes(clientId)) {
                return {
                  ok: false,
                  reason: `network.secrets[].oauth.clientIdAlternatives 含重复条目 ${JSON.stringify(clientId)}`,
                };
              }
              oaClientIdAlternatives.push(clientId);
            }
          }
          if (oa.clientSecret !== undefined) {
            if (oa.clientId === undefined) {
              return {
                ok: false,
                reason: 'network.secrets[].oauth.clientSecret 必须与 clientId 成对声明',
              };
            }
            if (
              typeof oa.clientSecret !== 'string' ||
              oa.clientSecret.trim().length === 0 ||
              oa.clientSecret.length > 200 ||
              /\s/.test(oa.clientSecret)
            ) {
              return {
                ok: false,
                reason: 'network.secrets[].oauth.clientSecret 必须是 1–200 字符、不含空白的字符串',
              };
            }
          }
          let oaScopes: string[] | undefined;
          if (oa.scopes !== undefined) {
            if (!Array.isArray(oa.scopes) || oa.scopes.length > GHOST_OAUTH_SCOPES_MAX) {
              return {
                ok: false,
                reason: `network.secrets[].oauth.scopes 必须是 ≤${GHOST_OAUTH_SCOPES_MAX} 条的数组`,
              };
            }
            oaScopes = [];
            for (const sc of oa.scopes) {
              if (
                typeof sc !== 'string' ||
                sc.trim().length === 0 ||
                sc.length > 200 ||
                /\s/.test(sc)
              ) {
                return {
                  ok: false,
                  reason: `network.secrets[].oauth.scopes 含非法条目 ${JSON.stringify(sc)}(1–200 字符、不含空白)`,
                };
              }
              if (oaScopes.includes(sc)) {
                return {
                  ok: false,
                  reason: `network.secrets[].oauth.scopes 含重复条目 ${JSON.stringify(sc)}`,
                };
              }
              oaScopes.push(sc);
            }
          }
          if (oa.pkce !== undefined && typeof oa.pkce !== 'boolean') {
            return { ok: false, reason: 'network.secrets[].oauth.pkce 必须是布尔值(缺省 true)' };
          }
          if (oa.scopeDelimiter !== undefined && oa.scopeDelimiter !== ',') {
            return {
              ok: false,
              reason: 'network.secrets[].oauth.scopeDelimiter 目前只支持 ","(缺省 = 空格拼接)',
            };
          }
          let oaExtra: Record<string, string> | undefined;
          if (oa.extraAuthorizeParams !== undefined) {
            if (!isPlainObject(oa.extraAuthorizeParams)) {
              return {
                ok: false,
                reason: 'network.secrets[].oauth.extraAuthorizeParams 必须是对象',
              };
            }
            const entries = Object.entries(oa.extraAuthorizeParams as Record<string, unknown>);
            if (entries.length === 0 || entries.length > GHOST_OAUTH_EXTRA_PARAMS_MAX) {
              return {
                ok: false,
                reason: `network.secrets[].oauth.extraAuthorizeParams 必须是 1–${GHOST_OAUTH_EXTRA_PARAMS_MAX} 条(或省略)`,
              };
            }
            oaExtra = {};
            for (const [pk, pv] of entries) {
              if (!/^[a-z][a-z0-9_]{0,31}$/.test(pk)) {
                return {
                  ok: false,
                  reason: `network.secrets[].oauth.extraAuthorizeParams 键 ${JSON.stringify(pk)} 必须是小写字母开头的 1–32 位小写/数字/下划线`,
                };
              }
              if (GHOST_OAUTH_RESERVED_AUTHORIZE_PARAMS.includes(pk)) {
                return {
                  ok: false,
                  reason: `network.secrets[].oauth.extraAuthorizeParams 不允许声明协议保留参数 ${JSON.stringify(pk)}`,
                };
              }
              if (typeof pv !== 'string' || pv.length === 0 || pv.length > 200) {
                return {
                  ok: false,
                  reason: `network.secrets[].oauth.extraAuthorizeParams[${JSON.stringify(pk)}] 必须是 1–200 字符的字符串`,
                };
              }
              oaExtra[pk] = pv;
            }
          }
          // redirectPort(可选):loopback 回调固定端口(Atlassian 等回调精确匹配)。
          if (oa.redirectPort !== undefined) {
            if (
              typeof oa.redirectPort !== 'number' ||
              !Number.isInteger(oa.redirectPort) ||
              oa.redirectPort < 1024 ||
              oa.redirectPort > 65535
            ) {
              return {
                ok: false,
                reason: 'network.secrets[].oauth.redirectPort 必须是 1024–65535 的整数',
              };
            }
          }
          // tokenBroker(可选):XDT server broker slug;secret 在服务端,与
          // clientSecret 互斥(同时声明说明作者没想清 secret 到底在哪)。
          if (oa.tokenBroker !== undefined) {
            if (
              typeof oa.tokenBroker !== 'string' ||
              !GHOST_OAUTH_TOKEN_BROKER_RE.test(oa.tokenBroker)
            ) {
              return {
                ok: false,
                reason:
                  'network.secrets[].oauth.tokenBroker 必须是小写字母开头的 1–32 位小写/数字/下划线/连字符',
              };
            }
            if (oa.clientSecret !== undefined) {
              return {
                ok: false,
                reason:
                  'network.secrets[].oauth.tokenBroker 与 clientSecret 互斥(broker 模式下 secret 由服务端持有,不随包分发)',
              };
            }
          }
          if (oaClientIdAlternatives !== undefined && oa.tokenBroker === undefined) {
            return {
              ok: false,
              reason: 'network.secrets[].oauth.clientIdAlternatives 仅允许与 tokenBroker 一起声明',
            };
          }
          // brokerBounce(可选):双地址弹跳回调,必须与 tokenBroker + redirectPort
          // 成套声明(302 目标端口/路径在 broker 服务端写死,三者是一套约定)。
          let oaBounce: { path: string; callbackPath: string } | undefined;
          if (oa.brokerBounce !== undefined) {
            if (oa.tokenBroker === undefined || oa.redirectPort === undefined) {
              return {
                ok: false,
                reason:
                  'network.secrets[].oauth.brokerBounce 必须与 tokenBroker、redirectPort 同时声明',
              };
            }
            if (!isPlainObject(oa.brokerBounce)) {
              return { ok: false, reason: 'network.secrets[].oauth.brokerBounce 必须是对象' };
            }
            const bb = oa.brokerBounce as Record<string, unknown>;
            for (const field of ['path', 'callbackPath'] as const) {
              const v = bb[field];
              if (typeof v !== 'string' || v.length > 128 || !GHOST_OAUTH_BOUNCE_PATH_RE.test(v)) {
                return {
                  ok: false,
                  reason: `network.secrets[].oauth.brokerBounce.${field} 必须是 / 开头的站内绝对路径(段字符限字母/数字/_/-,≤128 字符)`,
                };
              }
            }
            oaBounce = { path: bb.path as string, callbackPath: bb.callbackPath as string };
          }
          let oaIdentity:
            | { url: string; labelPath: string; displayTemplate?: string; avatarPath?: string }
            | undefined;
          if (oa.identity !== undefined) {
            if (!isPlainObject(oa.identity)) {
              return { ok: false, reason: 'network.secrets[].oauth.identity 必须是对象' };
            }
            const idn = oa.identity as Record<string, unknown>;
            const idnUrl = parseHostBoundUrl(idn.url, 'identity.url');
            if (!idnUrl.ok) return idnUrl;
            if (
              typeof idn.labelPath !== 'string' ||
              idn.labelPath.length > 128 ||
              !GHOST_SECRET_EXCHANGE_TOKEN_PATH_RE.test(idn.labelPath)
            ) {
              return {
                ok: false,
                reason:
                  'network.secrets[].oauth.identity.labelPath 必须是 ≤128 字符的点分路径(段名限字母/数字/_/-,如 "email" / "user.name")',
              };
            }
            // displayTemplate(可选):展示名模板,占位符 `{点分路径}`(路径
            // 形状同 labelPath),至少一个占位符——纯静态字符串没有"身份展示"
            // 语义,多半是作者笔误。
            let idnTemplate: string | undefined;
            if (idn.displayTemplate !== undefined) {
              if (
                typeof idn.displayTemplate !== 'string' ||
                idn.displayTemplate.length === 0 ||
                idn.displayTemplate.length > GHOST_OAUTH_IDENTITY_TEMPLATE_MAX_CHARS
              ) {
                return {
                  ok: false,
                  reason: `network.secrets[].oauth.identity.displayTemplate 必须是 1–${GHOST_OAUTH_IDENTITY_TEMPLATE_MAX_CHARS} 字符的字符串`,
                };
              }
              const placeholders = [
                ...idn.displayTemplate.matchAll(GHOST_OAUTH_IDENTITY_TEMPLATE_PLACEHOLDER_RE),
              ];
              if (placeholders.length === 0) {
                return {
                  ok: false,
                  reason:
                    'network.secrets[].oauth.identity.displayTemplate 必须含至少一个 {点分路径} 占位符(如 "{team} · {user}")',
                };
              }
              for (const m of placeholders) {
                const p = m[1] ?? '';
                if (p.length > 128 || !GHOST_SECRET_EXCHANGE_TOKEN_PATH_RE.test(p)) {
                  return {
                    ok: false,
                    reason: `network.secrets[].oauth.identity.displayTemplate 占位符 {${p}} 不是合法点分路径(段名限字母/数字/_/-)`,
                  };
                }
              }
              idnTemplate = idn.displayTemplate;
            }
            // avatarPath(可选):头像 URL 的点分路径,形状同 labelPath。
            let idnAvatarPath: string | undefined;
            if (idn.avatarPath !== undefined) {
              if (
                typeof idn.avatarPath !== 'string' ||
                idn.avatarPath.length > 128 ||
                !GHOST_SECRET_EXCHANGE_TOKEN_PATH_RE.test(idn.avatarPath)
              ) {
                return {
                  ok: false,
                  reason:
                    'network.secrets[].oauth.identity.avatarPath 必须是 ≤128 字符的点分路径(段名限字母/数字/_/-,如 "data.avatar_thumb")',
                };
              }
              idnAvatarPath = idn.avatarPath;
            }
            oaIdentity = {
              url: idnUrl.url,
              labelPath: idn.labelPath,
              ...(idnTemplate !== undefined ? { displayTemplate: idnTemplate } : {}),
              ...(idnAvatarPath !== undefined ? { avatarPath: idnAvatarPath } : {}),
            };
          }
          oauth = {
            authorizeUrl: authorizeParsed.url,
            tokenUrl: tokenParsed.url,
            ...(oa.clientId !== undefined ? { clientId: oa.clientId as string } : {}),
            ...(oaClientIdAlternatives !== undefined
              ? { clientIdAlternatives: oaClientIdAlternatives }
              : {}),
            ...(oa.clientSecret !== undefined ? { clientSecret: oa.clientSecret as string } : {}),
            ...(oaScopes !== undefined ? { scopes: oaScopes } : {}),
            ...(oa.scopeDelimiter !== undefined
              ? { scopeDelimiter: oa.scopeDelimiter as ',' }
              : {}),
            ...(oa.pkce !== undefined ? { pkce: oa.pkce as boolean } : {}),
            ...(oaExtra !== undefined ? { extraAuthorizeParams: oaExtra } : {}),
            ...(oaIdentity !== undefined ? { identity: oaIdentity } : {}),
            ...(oa.redirectPort !== undefined ? { redirectPort: oa.redirectPort as number } : {}),
            ...(oa.tokenBroker !== undefined ? { tokenBroker: oa.tokenBroker as string } : {}),
            ...(oaBounce !== undefined ? { brokerBounce: oaBounce } : {}),
          };
        }
        // exchange(可选):key 换令牌二段式。交换端点必须落在 hosts 白名单
        // 内——结构上保证原始 key 也只流向用户同意过的域名。
        let exchange: GhostSecretExchangeDecl | undefined;
        if (s.exchange !== undefined) {
          if (!isPlainObject(s.exchange)) {
            return {
              ok: false,
              reason: `network.secrets[${JSON.stringify(s.key)}].exchange 必须是对象`,
            };
          }
          const ex = s.exchange as Record<string, unknown>;
          if (typeof ex.url !== 'string' || ex.url.length === 0 || ex.url.length > 2048) {
            return {
              ok: false,
              reason: 'network.secrets[].exchange.url 必须是 1–2048 字符的字符串',
            };
          }
          let exUrl: URL;
          try {
            exUrl = new URL(ex.url);
          } catch {
            return { ok: false, reason: 'network.secrets[].exchange.url 不是合法的绝对地址' };
          }
          if (
            exUrl.protocol !== 'https:' ||
            exUrl.port !== '' ||
            exUrl.username ||
            exUrl.password
          ) {
            return {
              ok: false,
              reason: 'network.secrets[].exchange.url 仅支持 https 默认端口且不允许内嵌用户名/密码',
            };
          }
          if (!hosts.some((pattern) => ghostNetworkHostMatches(pattern, exUrl.hostname))) {
            return {
              ok: false,
              reason: `network.secrets[].exchange.url 的域名 ${JSON.stringify(exUrl.hostname)} 必须命中 network.hosts 白名单`,
            };
          }
          if (
            typeof ex.bodyFormat !== 'string' ||
            ex.bodyFormat.length === 0 ||
            ex.bodyFormat.length > GHOST_SECRET_EXCHANGE_BODY_MAX_CHARS ||
            ex.bodyFormat.split('{value}').length !== 2
          ) {
            return {
              ok: false,
              reason: `network.secrets[].exchange.bodyFormat 必须是 ≤${GHOST_SECRET_EXCHANGE_BODY_MAX_CHARS} 字符且恰含一个 {value} 占位的字符串`,
            };
          }
          let exContentType: GhostSecretExchangeContentType | undefined;
          if (ex.contentType !== undefined) {
            if (
              typeof ex.contentType !== 'string' ||
              !(GHOST_SECRET_EXCHANGE_CONTENT_TYPES as readonly string[]).includes(ex.contentType)
            ) {
              return {
                ok: false,
                reason: `network.secrets[].exchange.contentType 仅支持 ${GHOST_SECRET_EXCHANGE_CONTENT_TYPES.join(' / ')}`,
              };
            }
            exContentType = ex.contentType as GhostSecretExchangeContentType;
          }
          if (
            typeof ex.tokenPath !== 'string' ||
            ex.tokenPath.length > 128 ||
            !GHOST_SECRET_EXCHANGE_TOKEN_PATH_RE.test(ex.tokenPath)
          ) {
            return {
              ok: false,
              reason:
                'network.secrets[].exchange.tokenPath 必须是 ≤128 字符的点分路径(段名限字母/数字/_/-,如 "session" / "data.token")',
            };
          }
          let exTtl: number | undefined;
          if (ex.ttlSeconds !== undefined) {
            if (
              typeof ex.ttlSeconds !== 'number' ||
              !Number.isInteger(ex.ttlSeconds) ||
              ex.ttlSeconds < GHOST_SECRET_EXCHANGE_TTL_MIN_S ||
              ex.ttlSeconds > GHOST_SECRET_EXCHANGE_TTL_MAX_S
            ) {
              return {
                ok: false,
                reason: `network.secrets[].exchange.ttlSeconds 必须是 ${GHOST_SECRET_EXCHANGE_TTL_MIN_S}–${GHOST_SECRET_EXCHANGE_TTL_MAX_S} 的整数(秒)`,
              };
            }
            exTtl = ex.ttlSeconds;
          }
          exchange = {
            url: ex.url,
            bodyFormat: ex.bodyFormat,
            ...(exContentType !== undefined ? { contentType: exContentType } : {}),
            tokenPath: ex.tokenPath,
            ...(exTtl !== undefined ? { ttlSeconds: exTtl } : {}),
          };
        }
        const check = s.check === undefined ? undefined : parseGhostSecretCheck(s.check,
          (host) => hosts.some((pattern) => ghostNetworkHostMatches(pattern, host))
            && (injectHosts ?? hosts).some((pattern) => ghostNetworkHostMatches(pattern, host)));
        if (s.check !== undefined && (!check || (source !== undefined && source !== 'user'))) {
          return { ok: false, reason: 'network.secrets[].check requires a user secret, a declared injection host, and a bounded response mapping' };
        }
        secrets.push({
          key: s.key,
          label: s.label,
          ...(source !== undefined ? { source } : {}),
          ...(s.hint !== undefined ? { hint: s.hint as string } : {}),
          ...(s.url !== undefined ? { url: s.url as string } : {}),
          inject: {
            header: inj.header,
            format: inj.format,
            ...(injectHosts !== undefined ? { hosts: injectHosts } : {}),
          },
          ...(exchange !== undefined ? { exchange } : {}),
          ...(check ? { check } : {}),
          ...(oauth !== undefined ? { oauth } : {}),
        });
      }
    }
    // connections(可选):多连接声明——"地址 + 凭证成对多条"的凭证形态
    // (自建实例场景)。作者只声明连接类型与注入形态,地址与 token 由用户在
    // 设置页添加(每次新增地址都过主机受信确认);连接凭证的注入范围恒等于
    // 各连接自身地址,inject.hosts 禁止声明。
    let connections: GhostConnectionDecl[] | undefined;
    if (n.connections !== undefined) {
      if (
        !Array.isArray(n.connections) ||
        n.connections.length === 0 ||
        n.connections.length > GHOST_NETWORK_MAX_CONNECTION_DECLS
      ) {
        return {
          ok: false,
          reason: `network.connections 必须是 1–${GHOST_NETWORK_MAX_CONNECTION_DECLS} 条的数组`,
        };
      }
      // 没人收地址和 token:连接的地址与凭证一律由意识 settingsHtml 收单
      // (经 /connections 协议通道),没有界面就没有入口。
      if (raw.settingsHtml === undefined) {
        return {
          ok: false,
          reason:
            '声明了 network.connections 必须同时声明 settingsHtml(连接地址与凭证由意识设置界面收单,没有界面就没人收单)',
        };
      }
      connections = [];
      const seenConnKeys = new Set<string>();
      const secretKeySet = new Set((secrets ?? []).map((s) => s.key));
      const nodeSecretKeySet = new Set((node?.secretBindings ?? []).map((s) => s.key));
      for (const c of n.connections) {
        if (!isPlainObject(c)) return { ok: false, reason: 'network.connections 每项必须是对象' };
        if (typeof c.key === 'string' && isGhostManifestReservedRecordKey(c.key)) {
          return {
            ok: false,
            reason: `network.connections[].key 不允许使用对象保留键名 ${JSON.stringify(c.key)}`,
          };
        }
        if (typeof c.key !== 'string' || !/^[a-z][a-z0-9_]{0,31}$/.test(c.key)) {
          return {
            ok: false,
            reason: 'network.connections[].key 必须是小写字母开头的 1–32 位小写/数字/下划线',
          };
        }
        if (seenConnKeys.has(c.key)) {
          return { ok: false, reason: `network.connections 含重复 key ${JSON.stringify(c.key)}` };
        }
        // 与 secrets 共用键命名空间(保险库派生键同一前缀),撞名拒装。
        if (secretKeySet.has(c.key)) {
          return {
            ok: false,
            reason: `network.connections[].key ${JSON.stringify(c.key)} 与 network.secrets 的 key 撞名(两者共用命名空间)`,
          };
        }
        if (nodeSecretKeySet.has(c.key)) {
          return {
            ok: false,
            reason: `network.connections[].key ${JSON.stringify(c.key)} 与 node.secretBindings 的 key 撞名(两者共用命名空间)`,
          };
        }
        seenConnKeys.add(c.key);
        if (typeof c.label !== 'string' || c.label.trim().length === 0 || c.label.length > 64) {
          return { ok: false, reason: 'network.connections[].label 必须是 1–64 字符的非空字符串' };
        }
        if (
          c.hint !== undefined &&
          (typeof c.hint !== 'string' || c.hint.trim().length === 0 || c.hint.length > 200)
        ) {
          return { ok: false, reason: 'network.connections[].hint 必须是 1–200 字符的非空字符串' };
        }
        if (!isPlainObject(c.inject)) {
          return {
            ok: false,
            reason: `network.connections[${JSON.stringify(c.key)}].inject 必填(连接凭证要声明注入到哪个请求头)`,
          };
        }
        const cinj = c.inject as Record<string, unknown>;
        if (typeof cinj.header !== 'string' || !/^[A-Za-z0-9-]{1,64}$/.test(cinj.header)) {
          return {
            ok: false,
            reason: 'network.connections[].inject.header 必须是 1–64 位字母/数字/连字符的头名',
          };
        }
        if (GHOST_NETWORK_FORBIDDEN_INJECT_HEADERS.includes(cinj.header.toLowerCase())) {
          return {
            ok: false,
            reason: `network.connections[].inject.header 不允许使用协议关键头 ${JSON.stringify(cinj.header)}`,
          };
        }
        if (
          typeof cinj.format !== 'string' ||
          cinj.format.length === 0 ||
          cinj.format.length > 200 ||
          cinj.format.split('{value}').length !== 2
        ) {
          return {
            ok: false,
            reason:
              'network.connections[].inject.format 必须是 ≤200 字符且恰含一个 {value} 占位的字符串(如 "Bearer {value}")',
          };
        }
        if (cinj.hosts !== undefined) {
          // 注入范围恒等于各连接自身地址(用户添加哪条注入哪条),作者无从
          // 收窄或扩张——声明即结构性误解,直接拒装。
          return {
            ok: false,
            reason:
              'network.connections[].inject.hosts 不允许声明(连接凭证只注入对应连接自身的地址)',
          };
        }
        if (c.maxConnections !== undefined) {
          if (
            typeof c.maxConnections !== 'number' ||
            !Number.isInteger(c.maxConnections) ||
            c.maxConnections < 1 ||
            c.maxConnections > GHOST_NETWORK_MAX_CONNECTIONS_PER_DECL
          ) {
            return {
              ok: false,
              reason: `network.connections[].maxConnections 必须是 1–${GHOST_NETWORK_MAX_CONNECTIONS_PER_DECL} 的整数(缺省 ${GHOST_NETWORK_MAX_CONNECTIONS_PER_DECL})`,
            };
          }
        }
        connections.push({
          key: c.key,
          label: c.label,
          ...(c.hint !== undefined ? { hint: c.hint as string } : {}),
          inject: { header: cinj.header, format: cinj.format },
          ...(c.maxConnections !== undefined ? { maxConnections: c.maxConnections as number } : {}),
        });
      }
    }
    network = {
      hosts,
      ...(secrets !== undefined ? { secrets } : {}),
      ...(connections !== undefined ? { connections } : {}),
    };
  }

  // setup 就绪声明:引用必须指向已声明的凭证/连接(悬空引用在装包期拒,
  // 不留到运行期才发现作者写错);kv 引用要求 settingsHtml(没有设置页
  // 没人填参数);Host 派生源没有用户配置动作,引用它属结构性误解,直接拒装。
  // OAuth source resolution belongs to the runtime; declaration acceptance grants no credentials.
  let setup: GhostSetupDecl | undefined;
  if (raw.setup !== undefined) {
    if (!isPlainObject(raw.setup)) {
      return {
        ok: false,
        reason: 'setup 必须是对象(如 { "requires": [{ "anyOf": ["secret:api_key"] }] })',
      };
    }
    const su = raw.setup as Record<string, unknown>;
    // 空数组是合法的显式 opt-out:「本意识没有使用前置需求」——凭证全为
    // 可选项的意识用它关掉宿主启发式(不声明才走启发式)。
    if (!Array.isArray(su.requires) || su.requires.length > GHOST_SETUP_MAX_GROUPS) {
      return {
        ok: false,
        reason: `setup.requires 必须是 0–${GHOST_SETUP_MAX_GROUPS} 组的数组(空数组 = 显式声明无使用前置需求)`,
      };
    }
    const secretByKey = new Map<
      string,
      { hostDerivedSource: 'login-email' | 'gh-cli' | 'oidc-token' | null }
    >([
      ...(network?.secrets ?? []).map(
        (s) =>
          [
            s.key,
            {
              hostDerivedSource:
                s.source === 'login-email' || s.source === 'gh-cli' || s.source === 'oidc-token'
                  ? s.source
                  : null,
            },
          ] as const,
      ),
      ...(node?.secretBindings ?? []).filter((s) => !s.oauthSecret).map((s) => [s.key, { hostDerivedSource: null }] as const),
    ]);
    const connectionKeys = new Set((network?.connections ?? []).map((c) => c.key));
    const groups: GhostSetupGroup[] = [];
    for (const g of su.requires) {
      if (
        !isPlainObject(g) ||
        !Array.isArray(g.anyOf) ||
        g.anyOf.length === 0 ||
        g.anyOf.length > GHOST_SETUP_MAX_ITEMS_PER_GROUP
      ) {
        return {
          ok: false,
          reason: `setup.requires 每组必须是 { "anyOf": [...] } 且组内 1–${GHOST_SETUP_MAX_ITEMS_PER_GROUP} 条`,
        };
      }
      const items: GhostSetupRequirement[] = [];
      const seenRefs = new Set<string>();
      for (const it of g.anyOf) {
        let item: GhostSetupRequirement;
        if (typeof it === 'string') {
          const m = /^(secret|connection):(.+)$/.exec(it);
          if (!m) {
            return {
              ok: false,
              reason: `setup 条目 ${JSON.stringify(it)} 形态不对(字符串条目须为 "secret:<key>" 或 "connection:<key>";kv 用对象 { "kv": "<key>", "label": "..." })`,
            };
          }
          const [, refKind, refKey] = m;
          if (refKind === 'secret') {
            const decl = secretByKey.get(refKey);
            if (!decl) {
              return {
                ok: false,
                reason: `setup 引用了未声明的凭证 ${JSON.stringify(refKey)}(必须逐字取自 network.secrets[].key 或 node.secretBindings[].key)`,
              };
            }
            if (decl.hostDerivedSource) {
              return {
                ok: false,
                reason: `setup 不允许引用 ${decl.hostDerivedSource} 源凭证 ${JSON.stringify(refKey)}(Host 派生身份没有用户配置动作可引导)`,
              };
            }
            item = { kind: 'secret', key: refKey };
          } else {
            if (!connectionKeys.has(refKey)) {
              return {
                ok: false,
                reason: `setup 引用了未声明的连接 ${JSON.stringify(refKey)}(必须逐字取自 network.connections[].key)`,
              };
            }
            item = { kind: 'connection', key: refKey };
          }
        } else if (isPlainObject(it)) {
          if (typeof it.kv === 'string' && isGhostManifestReservedRecordKey(it.kv)) {
            return {
              ok: false,
              reason: `setup kv 条目的 kv 不允许使用对象保留键名 ${JSON.stringify(it.kv)}`,
            };
          }
          if (typeof it.kv !== 'string' || !GHOST_SETUP_KV_KEY_RE.test(it.kv)) {
            return {
              ok: false,
              reason: 'setup kv 条目的 kv 必须是 1–64 位字母/数字/下划线/点/连字符的键名',
            };
          }
          if (
            typeof it.label !== 'string' ||
            it.label.trim().length === 0 ||
            it.label.length > 64
          ) {
            return {
              ok: false,
              reason: 'setup kv 条目必须带 1–64 字符的 label(kv 键名宿主无先验,弹窗要有名字可展示)',
            };
          }
          if (raw.settingsHtml === undefined) {
            return {
              ok: false,
              reason:
                'setup 引用了 kv 参数但没有 settingsHtml——参数由意识设置界面收单,没有界面就没人填',
            };
          }
          item = { kind: 'kv', key: it.kv, label: it.label };
        } else {
          return {
            ok: false,
            reason: 'setup.requires[].anyOf 每条必须是字符串引用或 { "kv", "label" } 对象',
          };
        }
        const ref = `${item.kind}:${item.key}`;
        if (seenRefs.has(ref)) {
          return { ok: false, reason: `setup 同组内含重复条目 ${JSON.stringify(ref)}` };
        }
        seenRefs.add(ref);
        items.push(item);
      }
      groups.push({ anyOf: items });
    }
    setup = { requires: groups };
  }

  // 显式触发指令:1–32 字符、无空白、无 '/'(允许中文,如 /画图);
  // 必须有工具可干活。跨意识查重在装入时由 GhostManager 执行(需要本地清单)。
  if (raw.command !== undefined) {
    if (
      typeof raw.command !== 'string' ||
      raw.command.length === 0 ||
      raw.command.length > 32 ||
      /[\s/]/.test(raw.command)
    ) {
      return { ok: false, reason: 'command 必须是 1–32 字符、不含空白与 "/" 的字符串' };
    }
    if (tools === undefined) {
      return { ok: false, reason: '声明了 command 但没有 tools——没有工具的指令无事可做' };
    }
  }

  // 语义触发扩展词表:≤8 个、每个 2–24 字符(单字词命中面失控,拒收)、
  // 去首尾空白后不许为空;大小写折叠去重。必须有工具可干活(同 command)。
  let keywords: string[] | undefined;
  if (raw.keywords !== undefined) {
    if (!Array.isArray(raw.keywords) || raw.keywords.length === 0 || raw.keywords.length > 8) {
      return { ok: false, reason: 'keywords 必须是 1–8 项的数组' };
    }
    if (tools === undefined) {
      return { ok: false, reason: '声明了 keywords 但没有 tools——没有工具的触发词无事可做' };
    }
    const seen = new Set<string>();
    keywords = [];
    for (const k of raw.keywords) {
      if (typeof k !== 'string') return { ok: false, reason: 'keywords 每项必须是字符串' };
      const word = k.trim();
      if (word.length < 2 || word.length > 24) {
        return {
          ok: false,
          reason: `keywords 每项须为 2–24 字符(单字词命中面失控):${JSON.stringify(k)}`,
        };
      }
      const fold = word.toLowerCase();
      if (seen.has(fold)) continue; // 重复词静默去重,不拒装
      seen.add(fold);
      keywords.push(word);
    }
  }

  return {
    ok: true,
    manifest: {
      ...prepared.unknownV3Fields,
      schemaVersion: prepared.schemaVersion,
      id: raw.id,
      name: raw.name,
      version: raw.version,
      ...(raw.releaseNotes !== undefined ? { releaseNotes: raw.releaseNotes as string } : {}),
      ...(raw.minCindyVersion !== undefined
        ? { minCindyVersion: raw.minCindyVersion as string }
        : {}),
      kind: 'chip',
      ...(raw.author !== undefined ? { author: raw.author as string } : {}),
      ...(locales !== undefined ? { locales } : {}),
      ...(raw.description !== undefined ? { description: raw.description as string } : {}),
      ...(raw.whenToUse !== undefined ? { whenToUse: raw.whenToUse as string } : {}),
      ...(raw.icon !== undefined ? { icon: raw.icon as string } : {}),
      entry: raw.entry,
      ...(raw.launch !== undefined ? { launch: raw.launch as GhostLaunchMode } : {}),
      ...(raw.settingsHtml !== undefined ? { settingsHtml: raw.settingsHtml as string } : {}),
      ...(raw.mobile !== undefined ? { mobile: raw.mobile as GhostManifest['mobile'] } : {}),
      ...(raw.settingsHeight !== undefined ? { settingsHeight: raw.settingsHeight as number } : {}),
      ...(raw.showTaskPreferences !== undefined
        ? { showTaskPreferences: raw.showTaskPreferences as boolean }
        : {}),
      ...(tools !== undefined ? { tools } : {}),
      ...(raw.mail === true ? { mail: true as const } : {}),
      ...(mailReader ? { mailReader: { ...(raw.mailReader as Record<string, unknown>), ...mailReader } } : {}),
      ...(card !== undefined || prepared.v3BaseCard || slots.includes('card')
        ? { card: card ?? {} }
        : {}),
      ...(cindy !== undefined ? { cindy } : {}),
      ...(agent !== undefined || prepared.v3BaseAgent || slots.includes('agent')
        ? { agent: agent ?? {} }
        : {}),
      ...(node !== undefined ? { node } : {}),
      ...(subscribe !== undefined ? { subscribe } : {}),
      ...(routineEvents !== undefined ? { routineEvents } : {}),
      ...(network !== undefined ? { network } : {}),
      ...(preview !== undefined ? { preview } : {}),
      ...(browserExtension !== undefined ? { browserExtension } : {}),
      ...(skill !== undefined ? { skill } : {}),
      ...(manual !== undefined ? { manual } : {}),
      ...(slots.includes('notify') ? { notify: true as const } : {}),
      ...(slots.includes('badge') ? { badge: true as const } : {}),
      ...(slots.includes('confirm') ? { confirm: true as const } : {}),
      ...(slots.includes('fs') ? { fs: true as const } : {}),
      ...(slots.includes('device-sync') ? { deviceSync: true as const } : {}),
      ...(slots.includes('library') ? { library: true as const } : {}),
      ...(slots.includes('session-context') ? { sessionContext: true as const } : {}),
      ...(slots.includes('pick') ? { pick: true as const } : {}),
      ...(slots.includes('workspace') ? { workspace: true as const } : {}),
      ...(slots.includes('ios-simulator') ? { iosSimulator: true as const } : {}),
      ...(setup !== undefined ? { setup } : {}),
      ...(raw.command !== undefined ? { command: raw.command as string } : {}),
      ...(keywords !== undefined ? { keywords } : {}),
      ...(panel !== undefined ? { panel } : {}),
      ...(mainView !== undefined ? { mainView } : {}),
      ...(taskView !== undefined ? { taskView } : {}),
    },
    unsupportedLegacySlots: prepared.unsupportedLegacySlots,
  };
}

/**
 * 校验 Host 已归一化的 GhostManifest 快照(例如批准 receipt 中的 manifest)。
 *
 * ghost.json 的作者格式与运行期格式只在 setup 条目上不同:作者写字符串引用或
 * `{ kv, label }`,Host 归一化后统一保存 `{ kind, key, label? }`。这里仅把已归一化
 * setup 还原为作者格式,再复用同一套完整清单校验;原始 ghost.json 仍必须走
 * validateGhostManifest,因此作者直接写内部格式仍会被拒绝。
 */
export function validateNormalizedGhostManifest(raw: unknown): ManifestValidation {
  // Durable Host state is written in author format so released clients can read it
  // after a rollback. Still accept normalized snapshots produced by affected dev
  // builds and passed between current Host code paths.
  const authorInput = isPlainObject(raw) ? withLegacyAuthorSlots(raw) : raw;
  const authorResult = validateInstalledGhostManifest(authorInput);
  if (authorResult.ok || !isPlainObject(raw) || raw.setup === undefined) return authorResult;
  if (!isPlainObject(raw.setup) || !Array.isArray(raw.setup.requires)) {
    return { ok: false, reason: '标准化清单 setup 必须是带 requires 数组的对象' };
  }

  const requires: Array<{ anyOf: Array<string | { kv: unknown; label: unknown }> }> = [];
  for (const group of raw.setup.requires) {
    if (!isPlainObject(group) || !Array.isArray(group.anyOf)) {
      return { ok: false, reason: '标准化清单 setup.requires 每组必须是带 anyOf 数组的对象' };
    }
    const anyOf: Array<string | { kv: unknown; label: unknown }> = [];
    for (const requirement of group.anyOf) {
      if (!isPlainObject(requirement)) {
        return { ok: false, reason: '标准化清单 setup 条目必须是 { kind, key } 对象' };
      }
      if (requirement.kind === 'secret' || requirement.kind === 'connection') {
        if (typeof requirement.key !== 'string') {
          return { ok: false, reason: '标准化清单 setup 条目的 key 必须是字符串' };
        }
        anyOf.push(`${requirement.kind}:${requirement.key}`);
        continue;
      }
      if (requirement.kind === 'kv') {
        anyOf.push({ kv: requirement.key, label: requirement.label });
        continue;
      }
      return { ok: false, reason: '标准化清单 setup 条目的 kind 不受支持' };
    }
    requires.push({ anyOf });
  }

  return validateInstalledGhostManifest({ ...withLegacyAuthorSlots(raw), setup: { requires } });
}

/** 把无 slots 的 v2 运行时投影还原成旧客户端能读取的作者清单。 */
function withLegacyAuthorSlots(raw: Record<string, unknown>): Record<string, unknown> {
  if (raw.schemaVersion !== 2) return raw;
  const slots: unknown[] = Array.isArray(raw.slots) ? [...raw.slots] : [];
  if (!Array.isArray(raw.slots)) {
    for (const [field, slot] of V3_DECLARATION_TO_LEGACY_SLOT) {
      if (raw[field] !== undefined) slots.push(slot);
    }
    for (const field of V3_BOOLEAN_CAPABILITY_FIELDS) {
      if (raw[field] === true) slots.push(V3_BOOLEAN_TO_LEGACY_SLOT[field]);
    }
  }
  const legacy: Record<string, unknown> = { ...raw, slots };
  for (const field of V3_BOOLEAN_CAPABILITY_FIELDS) delete legacy[field];
  return legacy;
}

/** 同一份 v2 清单在移除运行时 slots 前后的持久摘要必须保持一致。 */
export function ghostManifestToLegacyV2DigestFormat(
  manifest: unknown,
  source?: unknown,
): unknown {
  if (!isPlainObject(manifest)) return manifest;
  if (
    manifest.schemaVersion === 2 &&
    isPlainObject(source) &&
    source.schemaVersion === 2 &&
    Array.isArray(source.slots)
  ) {
    const legacy = withLegacyAuthorSlots({
      ...manifest,
      slots: source.slots.map((slot) => (slot === 'model' ? 'cindy' : slot)),
    });
    // Reproduce the released v0.1.61 normalized output exactly. Its validator
    // omitted card unless externalLinks was true, and omitted false agent flags;
    // current validators may synthesize empty capability objects from slots.
    const sourceCard = isPlainObject(source.card) ? source.card : null;
    if (sourceCard?.externalLinks === true) legacy.card = { externalLinks: true };
    else delete legacy.card;
    const sourceAgent = isPlainObject(source.agent) ? source.agent : null;
    const legacyAgent: Record<string, true> = {};
    for (const field of ['background', 'errand', 'schedule'] as const) {
      if (sourceAgent?.[field] === true) legacyAgent[field] = true;
    }
    if (Object.keys(legacyAgent).length > 0) legacy.agent = legacyAgent;
    else delete legacy.agent;
    return legacy;
  }
  return withLegacyAuthorSlots(manifest);
}

/**
 * 把 Host 归一化清单投影回 ghost.json 作者格式,供跨版本持久化。
 *
 * receipt schema v2 已随 v0.1.48 发布;旧版读取时会直接调用
 * validateGhostManifest,因此不能把内部 `{ kind, key }` setup 形态写盘。
 */
export function ghostManifestToAuthorFormat(manifest: GhostManifest): Record<string, unknown> {
  const authorManifest = withLegacyAuthorSlots(manifest);
  if (manifest.setup === undefined) return { ...authorManifest };
  return {
    ...authorManifest,
    setup: {
      requires: manifest.setup.requires.map((group) => ({
        anyOf: group.anyOf.map((requirement) => {
          if (requirement.kind === 'kv') {
            return { kv: requirement.key, label: requirement.label };
          }
          return `${requirement.kind}:${requirement.key}`;
        }),
      })),
    },
  };
}

/**
 * ── 管子(脑机接口)消息协议(docs/dev-rules/plugin-security-and-authoring.md)──
 *
 * 下行(主机 → 电子脑,'ghost-pipe:message' 单向推):
 *   - tool-call:agent 经 ghost 总机派活。电子脑处理完必须用 send 上行
 *     tool-result 交卷(callId 配对;超时由主机掐,过期卷子作废)。
 *
 * 上行(电子脑 → 主机,cindy.send(payload) = ipcRenderer.invoke):
 *   - tool-result:交卷。
 *   - host-request:读取宿主公开上下文。目前只支持 app-context(region + locale),
 *     无需声明卡槽、无用户数据与凭证内容。
 *   - cindy-request(旧名 model-request 兼容):cindy 槽代办(意识请 Cindy 本体干活;invoke 的返回值即结果,
 *     无需另配对)。gen_image / edit_image / gen_video / edit_video /
 *     deposit_media / release_media / oneshot_text / embed_text;须声明
 *     'cindy' 卡槽与能力详单。
 *   - fetch-request:主机代理 HTTP(invoke 返回值即响应,无需另配对)。
 *     当前 Agent tool-call 带严格在途 callId 时复用 Agent 授权;其它调用
 *     须声明 network 域名详单。凭证只按声明注入,意识永不经手。
 *   - pick-request:pick 槽——请主机弹系统级选文件夹窗口(用户亲选即授权)。
 *   - model-picker-request:打开宿主统一模型选择器,返回 PluginTaskRoute;无需能力声明,
 *     不修改任何默认或执行任务。协议见 shared/pluginModelPicker.ts 与 FORGE_GUIDE §4.0.3a。
 *   - preview-request:preview 槽——请主机在右侧栏内置浏览器开预览标签页
 *     (URL 必须命中身份卡 preview.hosts 白名单)。
 *   - schedule-request:agent 槽 schedule 加档——请主机**打开自动化创建面板并预填**
 *     (名称 / 提示词 / 建议频率)。只能开面板:任务由用户选模型后亲手保存才落库,
 *     插件没有任何直接建任务的通道。本版也没有"建成了没有"的回执(语义见
 *     GhostPipeScheduleDraftResult);绑定与查改由后续版本提供。
 *
 * 身份永远由主机按 webContents 反查(不信自报),这里的类型只描述载荷形状。
 */

/** 下行:工具调用派发。 */
export interface GhostPipeToolCall {
  type: 'tool-call';
  /** 配对号(主机生成;交卷时原样带回)。 */
  callId: string;
  tool: string;
  args: Record<string, unknown>;
}

/** 上行:工具调用交卷。 */
export type GhostPipeToolResult =
  | { type: 'tool-result'; callId: string; ok: true; result: unknown }
  | { type: 'tool-result'; callId: string; ok: false; errorCode?: string; message: string };

/**
 * 上行:工具调用进度心跳(长任务续命)。在途 tool-call 每收到一次心跳,
 * 主机把该卷的超时窗口重新续满一个基础档(缺省 330s),从派发起算不超过
 * GHOST_PIPE_CALL_MAX_TOTAL_MS 天花板。经 cindy-request 请主机代办且带
 * callId 的署名单在途时主机自动续命,无需心跳;意识自己经 network 槽轮询
 * 外部长任务时才需要发。验身与交卷同纪律:callId 不是派给你的即丢弃。
 */
export interface GhostPipeToolProgress {
  type: 'tool-progress';
  callId: string;
}

/**
 * 管子 tool-call 从派发起算的绝对上限(毫秒,30 分钟):代办自动续命与
 * tool-progress 心跳共用的天花板——盖住视频代办 expected×3 的最大轮询
 * 预算(seedance-pro 为 900s)+ 余量,又不给真死掉的调用无限吊着的机会。
 * (2026-07-24 管子长任务续命定案:此前 330s 固定超时令分钟级视频代办
 * 必超时,任务在后台继续烧钱、结果却作废。)
 */
export const GHOST_PIPE_CALL_MAX_TOTAL_MS = 30 * 60_000;

/** 主机公开给意识的构建区域。与 desktop CURRENT_CINDY_REGION 同口径。 */
export type GhostAppRegion = 'cn' | 'global';

/**
 * 上行:读取宿主公开上下文。`cindy.request({kind:'app-context'})` 是 preload
 * 提供的语法糖,底层仍走同一根 ghost-pipe 与主机公开上下文校验。
 */
export type GhostPipeHostRequest =
  | {
      type: 'host-request';
      kind: 'app-context';
    }
  | {
      type: 'host-request';
      kind: 'cindy-preference';
      /** 只能读取本插件已声明的媒体能力配置。 */
      capability: GhostMediaCapability;
    };

/** Replaces only the calling plugin's catalog; never starts a task. */
export interface GhostPipeRecommendationsUpdate {
  type: 'recommendations-update';
  items: GhostRecommendation[];
}

/** 插件请求 Agent 新回合时可选的会话处理方式。 */
export const GHOST_AGENT_RUN_MODES = ['continue', 'fork', 'new'] as const;
export type GhostAgentRunMode = (typeof GHOST_AGENT_RUN_MODES)[number];

/** Agent 回合的触发来源;后台触发需要清单中的额外权限。 */
export const GHOST_AGENT_TRIGGER_KINDS = ['user-action', 'background'] as const;
export type GhostAgentTriggerKind = (typeof GHOST_AGENT_TRIGGER_KINDS)[number];

/**
 * 上行:请求 Cindy Agent 开始一个普通用户回合。
 *
 * promptTemplate 必须且只能含一个 `{{user_message}}`;宿主完成替换并把
 * `{{event_json}}` 替换成 event 的 JSON。插件文本始终进入普通 user 回合,
 * 不会进入 system prompt。
 */
export interface GhostPipeAgentRequest {
  type: 'agent-request';
  mode: GhostAgentRunMode;
  trigger?: GhostAgentTriggerKind;
  promptTemplate: string;
  userMessage: string;
  event?: unknown;
  /** user-action 触发必填;来自宿主下发的 card-action 事件。 */
  userActionToken?: string;
  /** background 触发必填;必须是该插件曾由真人点击建立过关联的会话。 */
  sessionId?: string;
  /** new 模式的新会话标题;其它模式忽略。 */
  title?: string;
}

/** 插件请求 Agent 新回合的结构化返回。 */
export type GhostPipeAgentResult =
  | {
      ok: true;
      sessionId: string;
      mode: GhostAgentRunMode;
      disposition: 'created' | 'resumed' | 'active' | 'queued' | 'forked';
    }
  | {
      ok: false;
      errorCode:
        | 'INVALID_REQUEST'
        | 'PERMISSION_DENIED'
        | 'TOKEN_EXPIRED'
        | 'RATE_LIMITED'
        | 'HOST_NOT_READY'
        | 'SESSION_NOT_FOUND'
        | 'SESSION_UNAVAILABLE'
        | 'FORK_FAILED'
        | 'INTERNAL';
      message: string;
    };

/* ── agent 槽·派活取件(errand,2026-07-31 开闸)──────────────────────────
 * 与 agent-request(把回合发进用户会话,结果给用户看)相对:errand 把任务
 * 交给插件**专属 errand 会话**里的 agent 跑一轮,最终回复文字取回给插件。
 * 须声明 'agent' 卡槽 + `agent.errand: true`(插件详情高风险能力单列)。
 * agent/模型/effort/fast/供应商/权限档/工作目录由用户在插件详情页配置
 * (缺省跟随新建草稿偏好;保留历史缺省 plan,用户可选择 ask/auto/bypassPermissions);
 * 任务文本只进普通 user 消息,绝不进 system prompt。 */

/** 任务描述上限(与 agent-request 的最终消息同量级)。 */
export const GHOST_ERRAND_MAX_TASK_CHARS = 32_768;
/** 结构化上下文 JSON 化后的上限(与 agent-request 的 event 同量级)。 */
export const GHOST_ERRAND_MAX_CONTEXT_JSON_CHARS = 65_536;
/** 取回结果的截断上限(超长从头保留;截断时结果尾部带明示标记)。 */
export const GHOST_ERRAND_MAX_RESULT_CHARS = 65_536;
/** 完成结果保留时长(毫秒;同 cindy 异步代办:过期即清,查询按查无此单)。 */
export const GHOST_ERRAND_JOB_TTL_MS = 30 * 60_000;
/** 每插件相邻两次提交的最小间隔(毫秒;与 agent-request 后台档同口径)。
 *  同步等待(mode:'wait')的绝对上限直接复用 GHOST_PIPE_CALL_MAX_TOTAL_MS。 */
export const GHOST_ERRAND_MIN_INTERVAL_MS = 10_000;
/** sessionKey 的合法形状(1–64 位字母/数字/._-;字符集刻意排除 `#`,
 *  存储层用 `ghostId#sessionKey` 做映射键,ghostId 字符集同样无 `#`,不会歧义)。 */
export const GHOST_ERRAND_SESSION_KEY_RE = /^[A-Za-z0-9._-]{1,64}$/;

/**
 * 插件新建任务与普通任务使用同一三档;启用卡片时受本插件设置上限约束,隐藏时不读取卡片。
 * plan / acceptEdits 仅保留旧配置及旧接口兼容,不自动升权或丢弃历史选择。
 */
export const GHOST_ERRAND_PERMISSION_MODES = [...PLUGIN_TASK_PERMISSION_MODES, 'plan', 'acceptEdits'] as const;
export type GhostErrandPermissionMode = (typeof GHOST_ERRAND_PERMISSION_MODES)[number];

/** 上行:派活提交与取件查询。 */
export type GhostPipeAgentErrandRequest =
  | {
      type: 'agent-errand-request';
      kind: 'run';
      /** 任务描述(1–32768 字符;进 errand 会话的普通 user 消息)。 */
      task: string;
      /** 可选结构化上下文:主机 JSON.stringify 后附在任务消息尾部(≤64KB)。 */
      context?: unknown;
      /** errand 会话标题提示(仅首次创建对应 errand 会话时采用;1–100 字符)。 */
      title?: string;
      /**
       * 可选的分会话钥匙(1–64 位字母/数字/._-)。不传 = 插件共用一间专属
       * errand 会话(旧行为);传了 = 同一把钥匙复用同一间、不同钥匙各开各
       * 的间(每单仍受"每插件同时 1 单在途"约束,分会话不放大并发)。适合
       * 「按业务对象各聊各的」场景,如每条 PR 一间:sessionKey:'pr-123'。
       */
      sessionKey?: string;
      /**
       * 可选:请求把 errand 会话建在这个目录(绝对路径,≤1024 字符)。
       * 只是**转述**,不是授权——主机只认用户此前在 pick 槽系统窗口里
       * 亲手选过的目录(pickGrantsStore 台账);台账里没有 → INVALID_REQUEST。
       * 用户在「任务设置」卡里配置了工作目录时以用户配置优先,本字段忽略。
       */
      workingDir?: string;
      /**
       * 'wait' = 同步吊着等完成(管子自动续命,30 分钟天花板);缺省异步:
       * 受理后立即返回 jobId,用 kind:'query' 轮询取件。agent 干活是分钟级
       * 的,推荐缺省异步 + 插件自己掌握轮询节奏。
       */
      mode?: 'wait';
      /** 归因号(tool-call 触发时把 callId 原样带上;同 cindy-request 语义)。 */
      callId?: string;
      /**
       * 可选:把 `card-action` 事件里主机签发的点击票原样带上。
       * 主机校验通过才把这次派活当成用户发起并切到 errand 任务;
       * 票一次性消费,不能再拿去 agent.run 或再派一次。
       */
      userActionToken?: string;
    }
  | {
      type: 'agent-errand-request';
      kind: 'query';
      /** 提交受理时返回的任务号(仅本插件自己的任务可查)。 */
      jobId: string;
    };

/** errand 结构化错误码(稳定契约,新增值不改旧值语义)。 */
export type GhostAgentErrandErrorCode =
  | 'INVALID_REQUEST'
  | 'PERMISSION_DENIED'
  | 'BUSY'
  | 'RATE_LIMITED'
  | 'HOST_NOT_READY'
  | 'JOB_NOT_FOUND'
  | 'SESSION_UNAVAILABLE'
  | 'TURN_FAILED'
  | 'TIMEOUT'
  | 'INTERNAL';

/** 下行(invoke 返回值):受理/进行中、完成、失败三态。 */
export type GhostPipeAgentErrandResult =
  | {
      /** 受理(kind:'run' 异步)与查询进行中(kind:'query')共用本分支。 */
      ok: true;
      jobId: string;
      status: 'running';
      /** errand 会话 id(用户可在侧边栏找到它旁观)。 */
      sessionId?: string;
      /** 已耗时(秒;仅查询返回)。 */
      elapsedSeconds?: number;
    }
  | {
      /** 完成态:text 即 agent 本轮的最终回复(超长按上限截断并带标记)。 */
      ok: true;
      jobId: string;
      status: 'done';
      sessionId: string;
      text: string;
      /** 实际干活的 agent 与模型(用户配置的解析结果;诊断展示用)。 */
      agentKind?: string;
      model?: string;
    }
  | { ok: false; errorCode: GhostAgentErrandErrorCode; message: string };

/**
 * node-request 长任务绝对上限(毫秒,15 分钟):声明 maxTotalMs 后请求最长
 * 可以吊多久的天花板——盖住旧 Bridge 约 12 分钟的构建时长,又不给真死掉的
 * 进程永远吊着的机会。
 */
export const GHOST_NODE_REQUEST_MAX_TOTAL_MS = 15 * 60_000;

/** Public artifact download; results deliberately exclude host filesystem paths. */
export type GhostPipeDownloadRequest =
  | { type: 'download-request'; kind: 'start'; id: string; url: string; sha256: string; bytes: number }
  | { type: 'download-request'; kind: 'cancel'; id: string };

export type GhostPipeDownloadResult =
  | { ok: true; token: string; bytes: number; sha256: string; fromCache: boolean }
  | { ok: true }
  | { ok: false; message: string };

export interface GhostPipeDownloadProgress {
  type: 'event';
  name: 'download-progress';
  data: {
    id: string;
    phase: 'queued' | 'downloading' | 'verifying' | 'retrying' | 'completed' | 'failed' | 'cancelled';
    loaded?: number;
    total?: number | null;
    speedBps?: number;
    attempt?: number;
    delayMs?: number;
    fromCache?: boolean;
  };
}

/** 上行:main.js 通过主机中继调用随包 Node 工作进程。 */
export interface GhostPipeNodeRequest {
  type: 'node-request';
  /** Host resolves same-plugin download receipts into params.downloads for this RPC only. */
  downloadTokens?: Record<string, string>;
  /** OAuth 注入的本插件账号 id;缺省使用对应 OAuth 槽的默认账号。 */
  authAccount?: string;
  /** Live tool-call identity; only cancelWithCall opts in to the new lifecycle. */
  callId?: string;
  /** Explicit opt-in: cancellation/completion stops this RPC and its children. */
  cancelWithCall?: boolean;
  /** JSON-RPC 方法名;mcp-stdio 时使用 tools/list、tools/call 等 MCP 方法。 */
  method: string;
  /** Live call only: show the existing protected card for this RPC's manual Node bindings. */
  promptSecrets?: boolean;
  params?: unknown;
  /**
   * 单次等待上限,缺省 30 秒;允许 1–120 秒。声明了 maxTotalMs 时语义变为
   * **沉默窗口**:worker 只要还有动静(stdout 协议消息或 stderr 日志)就续期。
   */
  timeoutMs?: number;
  /**
   * 长任务绝对上限(2026-07-23,构建续命):声明后开启"有动静就续期",
   * 必须 ≥ 生效的 timeoutMs 且 ≤ GHOST_NODE_REQUEST_MAX_TOTAL_MS(15 分钟)。
   * 缺省 = 不续期,行为与旧版完全一致。
   */
  maxTotalMs?: number;
  /**
   * 目标工作进程入口(2026-07-23,多进程窄版):缺省 = node.entry 主进程;
   * 指定时必须逐字命中 node.entries 申报清单,否则整单拒。
   */
  entry?: string;
}

/** Node / stdio MCP 请求的结构化返回。 */
export type GhostPipeNodeResult =
  | { ok: true; result: unknown }
  | {
      ok: false;
      errorCode:
        | 'CANCELLED'
        | 'INVALID_REQUEST'
        | 'PERMISSION_DENIED'
        | 'PROCESS_START_FAILED'
        | 'PROCESS_EXITED'
        | 'PROTOCOL_ERROR'
        | 'TIMEOUT'
        | 'RATE_LIMITED'
        | 'INTERNAL';
      message: string;
      data?: unknown;
    };

/**
 * session-context 槽注入到 tool-call args.session_context 的形态(主机铸造,
 * snake_case 与 dir_deposit / save_deposit 同风格)。
 *
 * workdir_is_local 是本注入的位置安全核心:只有主机能证明「该会话不是远程工作区
 * (sessions.remoteHostId 为空)」时才为 true;证明不了(远程会话 / 查无会话 /
 * 无 sessionId 语境)一律 false——插件此时**不得**把 workdir 当本机路径交给
 * Node 侧读写(fail closed,见 docs/dev-rules/plugin-security-and-authoring.md §6)。
 * workdir_is_read_only 则由同一份会话 permission / plan 状态铸造;为 true 时
 * 插件不得修改当前 workdir。证明不了会话状态时同样 fail closed 为 true。
 */
export interface GhostSessionContextInjected {
  session_id: string | null;
  workdir: string | null;
  workdir_is_local: boolean;
  workdir_is_read_only: boolean;
}

/**
 * session-context 注入体推导(纯函数;main 侧查会话快照后调用):
 * - 无 sessionId 语境 / 查无会话:回落 ALS workdir,但恒 workdir_is_local=false
 *   且 workdir_is_read_only=true(证明不了就不许当本机路径或修改,fail closed);
 * - 有快照:workdir 取会话真身,只有 remoteHostId 为空且 workdir 非空才算本地。
 */
export function deriveGhostSessionContext(
  sessionId: string | null,
  fallbackWorkdir: string | null,
  snapshot: {
    workingDir: string | null;
    remoteHostId: string | null;
    workdirIsReadOnly: boolean;
  } | null,
): GhostSessionContextInjected {
  if (!sessionId) {
    return {
      session_id: null,
      workdir: fallbackWorkdir,
      workdir_is_local: false,
      workdir_is_read_only: true,
    };
  }
  if (!snapshot) {
    return {
      session_id: sessionId,
      workdir: fallbackWorkdir,
      workdir_is_local: false,
      workdir_is_read_only: true,
    };
  }
  return {
    session_id: sessionId,
    workdir: snapshot.workingDir,
    workdir_is_local: snapshot.remoteHostId === null && snapshot.workingDir !== null,
    workdir_is_read_only: snapshot.workdirIsReadOnly,
  };
}

/** pick 槽:标题(选择框里的用途说明)长度上限。 */
export const GHOST_PICK_TITLE_MAX_CHARS = 80;
/** pick 槽:同一插件两次弹选择框的最小间隔 ms(防对话框骚扰)。 */
export const GHOST_PICK_MIN_INTERVAL_MS = 3000;

/**
 * 上行:pick 槽——请主机弹系统级选文件夹窗口。用户亲手选中即授权;
 * 取消即拒,插件拿不到任何路径信息。
 */
export interface GhostPipePickRequest {
  type: 'pick-request';
  mobilePageId?: string;
  /** v1 只支持选目录;将来扩文件类型时在此收窄枚举。 */
  mode: 'directory';
  /** 选择框内的用途说明(净化后随插件名一起展示,让用户知道谁在要、要来干嘛)。 */
  title?: string;
  /**
   * 是否同时签发目录过户票据(dir_deposit,上传等主机代办用;收集有
   * 文件数/体积上限,大目录会失败)。未声明 node 槽的插件必须请求票据——
   * 否则选完什么都拿不到,请求本身就是无意义的。
   */
  deposit?: boolean;
}

/** pick 能力结构化返回。path 仅在插件声明了 node 能力时提供。 */
export type GhostPipePickResult =
  | {
      ok: true;
      /** 所选目录名(展示用,不含上级路径)。 */
      name: string;
      /** 绝对路径:仅 node 槽插件可见(Node 侧本就有用户级本机权限)。 */
      path?: string;
      /** 目录过户票据(同 ghost_call dir 通道;上传等主机代办凭票取件)。 */
      dir_deposit?: DirDepositReceiptShape;
    }
  | {
      ok: false;
      errorCode:
        | 'PERMISSION_DENIED'
        | 'INVALID_REQUEST'
        | 'CANCELLED'
        | 'RATE_LIMITED'
        | 'BUSY'
        | 'INTERNAL';
      message: string;
    };

/**
 * dir_deposit 票据的意识可见形态(与 main/cindy-brain/dirDeposit.ts 的
 * DirDepositReceipt 同构;shared 不反向 import main,这里镜像声明)。
 */
export interface DirDepositReceiptShape {
  token: string;
  file_count: number;
  total_bytes: number;
  rel_paths: string[];
}

/** workspace 槽:用途说明/新会话标题长度上限。 */
export const GHOST_WORKSPACE_TITLE_MAX_CHARS = 100;
/** workspace 槽:同一插件两次请求的最小间隔 ms(防确认卡/对话框骚扰)。 */
export const GHOST_WORKSPACE_MIN_INTERVAL_MS = 3000;

/**
 * 上行:workspace 槽——请主机在指定本机项目目录下确保存在一个会话入口
 * (侧边栏可见)。目录下已有 active 会话时复用(created:false),没有才创建
 * 空 draft 会话(不拉起 agent 进程)。目录授权两条路:
 * - mode:'pick':主机弹系统级选文件夹窗口,用户亲手选中即授权,绝对路径
 *   不回沙箱(与 pick 槽同一哲学);
 * - mode:'dir':传绝对路径 + 当前在途 ghost_call 的 callId(主机签发的上下文
 *   凭证,反查发起会话)。目录在该会话 workdir 内自动放行,workdir 外弹
 *   确认卡由用户决定(对齐 attachments/dir 过户的两档钳制)。
 * 远程工作区(SSH)v1 不支持,一律拒(fail closed)。
 */
export type GhostPipeWorkspaceRequest =
  | {
      type: 'workspace-request';
      mobilePageId?: string;
      kind: 'ensure-session';
      mode: 'pick';
      /** pick 模式选择框里的用途说明(净化后随插件名展示);也用作新会话标题。 */
      title?: string;
      /** 建成/命中后是否跳转聚焦到该会话(缺省 false,只落侧边栏)。 */
      focus?: boolean;
    }
  | {
      type: 'workspace-request';
      mobilePageId?: string;
      kind: 'ensure-session';
      mode: 'dir';
      /** 目标项目目录的本机绝对路径。 */
      dir: string;
      /** 当前在途 ghost_call 的 callId。 */
      callId: string;
      /** 用作新会话标题(净化后展示)。 */
      title?: string;
      /** 建成/命中后是否跳转聚焦到该会话(缺省 false,只落侧边栏)。 */
      focus?: boolean;
    };

/** workspace 槽结构化返回。绝对路径不回沙箱,只给目录 basename。 */
export type GhostPipeWorkspaceResult =
  | {
      ok: true;
      sessionId: string;
      /** true = 本次新建;false = 命中已有会话复用。 */
      created: boolean;
      /** 目录名(展示用,不含上级路径)。 */
      name: string;
    }
  | {
      ok: false;
      errorCode:
        | 'PERMISSION_DENIED'
        | 'INVALID_REQUEST'
        | 'CANCELLED'
        | 'RATE_LIMITED'
        | 'BUSY'
        | 'DIR_NOT_FOUND'
        | 'NOT_DIRECTORY'
        | 'HOST_NOT_READY'
        | 'INTERNAL';
      message: string;
    };

export const GHOST_MEDIA_HANDOVER_MIME = 'application/x-cindy-ghost-handover';

export interface GhostMediaHandover {
  uri: string;
  sourceToken?: string;
}

export interface GhostPanelMediaTarget {
  ghostId: string;
  instanceId?: string;
}
/**
 * 上行:preview 槽——请主机在右侧栏内置浏览器打开一个预览标签页。
 * url 必须命中身份卡 preview.hosts 白名单(ghostPreviewUrlAllowed);
 * sessionId 缺省 = 当前活跃会话(通常配合 session-context 注入的 session_id)。
 */
export interface GhostPipePreviewRequest {
  type: 'preview-request';
  mobilePageId?: string;
  url: string;
  sessionId?: string;
}

/** preview 槽结构化返回。 */
export type GhostPipePreviewResult =
  | { ok: true }
  | {
      ok: false;
      errorCode:
        | 'PERMISSION_DENIED'
        | 'INVALID_REQUEST'
        | 'URL_NOT_ALLOWED'
        | 'RATE_LIMITED'
        | 'HOST_NOT_READY'
        | 'INTERNAL';
      message: string;
    };

/**
 * 上行:browserExtension 槽——插件经宿主桥接与自己的浏览器扩展通讯。
 * - status:连接与安装状态(不读页面);
 * - act:向扩展投递一个页面作业(action + payload 的形状由线协议定义,
 *   宿主校验地址后分发,结果脱敏后返回);
 * - setTrustedClients:插件把自己保存的配对身份推给宿主(宿主缓存);
 *   setPolicy 仅为兼容旧插件保留,站点名单已于 2026-10-30 取消,应答但不生效;
 * - relayActive / relayProgress / relayResult:插件处理完宿主转交的扩展
 *   请求(翻译、字幕等)后回传进度与结果。
 */
export type GhostPipeBrowserExtensionRequest =
  | { type: 'browser-extension-request'; kind: 'status' }
  | { type: 'browser-extension-request'; kind: 'act'; action: string; payload?: Record<string, unknown> }
  | { type: 'browser-extension-request'; kind: 'setPolicy'; policy: unknown }
  | { type: 'browser-extension-request'; kind: 'setTrustedClients'; clients: unknown[] }
  | { type: 'browser-extension-request'; kind: 'relayActive'; id: string }
  | { type: 'browser-extension-request'; kind: 'relayProgress'; id: string; progress: unknown }
  | { type: 'browser-extension-request'; kind: 'relayResult'; id: string; result: unknown };

/**
 * browserExtension 槽结构化返回。槽级拒绝带 errorCode;作业与状态结果沿用线
 * 协议自己的 `{ ok, error, message, execution }` 形状,原样交给插件工具结果。
 */
export type GhostPipeBrowserExtensionResult =
  | { ok: true; [key: string]: unknown }
  | {
      ok: false;
      errorCode?: 'PERMISSION_DENIED' | 'INVALID_REQUEST' | 'HOST_NOT_READY' | 'INTERNAL';
      error?: string;
      message: string;
      execution?: 'not_executed' | 'executed' | 'unknown';
      [key: string]: unknown;
    };

/**
 * 下行:宿主桥接收到扩展发起的请求(翻译、字幕等),转交给声明 browserExtension
 * 的插件处理;插件用 relayActive / relayProgress / relayResult 回传。
 */
export interface GhostPipeBrowserExtensionRelay {
  type: 'event';
  name: 'browser-extension-relay';
  /** 请求 id(扩展生成的 uuid;回传时原样带回)。 */
  id: string;
  /** 发起请求的扩展连接 id。 */
  clientId: string;
  /** 线协议校验后的请求载荷。 */
  request: unknown;
  ts: number;
}

/**
 * 任务页开页结果(`cindy.taskView`)。成功时带上实际落点任务:请求不指定任务时
 * 主机落到台前任务,插件据此把自己的业务状态(如设备)绑定到该任务。
 */
export type GhostPipeTaskViewResult =
  | { ok: true; sessionId: string; focusRequested?: true }
  | {
      ok: false;
      errorCode: 'PERMISSION_DENIED' | 'INVALID_REQUEST' | 'HOST_NOT_READY' | 'INTERNAL';
      message: string;
    };

/**
 * schedule-request(agent.schedule 加档)的上行载荷。
 *
 * 与本文件里其它上行请求(PickRequest / PreviewRequest / WorkspaceRequest …)同规格:
 * 只描述**形状**,不代表已通过校验 —— 资格审、文本净化截断、频率钳制与限速都在主机侧
 * scheduleSlot 完成,沙箱给什么都要重新过一遍。
 */
export interface GhostPipeScheduleDraftRequest {
  type: 'schedule-request';
  mobilePageId?: string;
  /** 预填的自动化名称(净化后按 GHOST_SCHEDULE_DRAFT_NAME_MAX_CHARS 截断)。 */
  name: string;
  /** 预填提示词:这条自动化到点要干什么(净化后按 …PROMPT_MAX_CHARS 截断)。 */
  prompt: string;
  /**
   * 建议触发间隔(毫秒)。低于 GHOST_SCHEDULE_DRAFT_MIN_INTERVAL_SUGGESTION_MS
   * 会被主机上调;缺省 = 不建议频率,面板用自己的默认值。
   */
  intervalMs?: number;
}

/**
 * schedule-request(agent.schedule 加档)的返回形态。
 *
 * ⚠️ ok:true 的语义严格是「**请求已被主机接受并投递给主壳窗口**」。它**不保证**
 * 面板真的打开了,更不表示任务已创建:
 *   - 用户当时可能正开着另一个自动化表单在编辑 —— 那种情况下本次草稿会被**丢弃**
 *     (保护用户没保存的输入),用户看到一句提示,面板不换内容;
 *   - 即使面板正常打开,任务也要用户选完模型**亲手点保存**才落库。
 *
 * 因此插件 UI **不要**据此显示「已开启」之类的完成态,应显示「已为你打开创建面板,
 * 请确认」。判据不是保守 —— 是这一版本来就没有任何"用户存没存"的回执通道。
 *
 * 后续会补上:任务与发起插件的**绑定关系**,以及插件查询 / 管理**自己绑定的那条
 * 任务**(是否有效、下次运行时间、频率,以及改时间 / 暂停 / 关掉)。届时插件才能在
 * 自己面板上显示「已开启 · 每小时 · 下次 15:00」并让用户就地改。绑定关系本身即是
 * 授权边界:插件只能看和改它自己请求创建的那条,看不到用户的其它自动化。
 */
export type GhostPipeScheduleDraftResult =
  | { ok: true }
  | {
      ok: false;
      errorCode:
        'PERMISSION_DENIED' | 'INVALID_REQUEST' | 'RATE_LIMITED' | 'HOST_NOT_READY' | 'INTERNAL';
      message: string;
    };

/**
 * 主机 → renderer 的「打开自动化创建面板并预填」推送载荷。
 *
 * 身份三件套(ghostId / name / iconDataUrl)由主机按已装清单填,**不信沙箱自报**
 * (同 GhostPreviewOpenPush 纪律):面板上要让用户看清是哪个插件在请求。
 * 文本字段已由主机净化 + 截断;频率建议已钳到最小间隔之上。
 */
export interface GhostScheduleDraftPush {
  /** 本次请求 id(renderer 去重用:重复推送不叠开多个面板)。 */
  requestId: string;
  ghostId: string;
  /**
   * 已知身份才带上。待迁移、或还没有 namespace 字段的旧安装省略。
   * 不写入调度存储:给任务表加列是不可回退的 migration,这里只跟着打开面板的推送走。
   */
  namespace?: string | null;
  /** 插件展示名(主机填,用于面板上的来源标注)。 */
  ghostName: string;
  iconDataUrl?: string;
  /** 预填任务名(已净化截断)。 */
  name: string;
  /** 预填提示词 —— 「这条任务到点要干什么」,由插件自己用自然语言写。 */
  prompt: string;
  /**
   * 建议触发间隔 ms。已钳到 GHOST_SCHEDULE_DRAFT_MIN_INTERVAL_SUGGESTION_MS 之上。
   * 缺省 = 不建议频率,面板用它自己的默认值。
   */
  intervalMs?: number;
}

/** host-request 与 settings 页面 `/app-context` 共用的只读返回形态。 */
export interface GhostAppContextResult {
  ok: true;
  context: {
    region: GhostAppRegion;
    /** 插件协议语言;宿主新增语言会在边界回退英文。 */
    locale: GhostLocale;
  };
}

/** Read-only agent routes. No credentials or provider configuration. */
export type GhostAgentModelsResult =
  | {
      ok: true;
      models: Array<{
        visible?: boolean;
        id: string;
        name: string;
        agent: 'codex' | 'claude-code' | 'pi';
        providerId: string;
        providerName: string;
        efforts: string[];
        defaultEffort: string | null;
      }>;
      agentDeviceId?: string;
      locations?: Array<{ agentDeviceId: string; name: string }>;
    }
  | { ok: false; errorCode: 'PERMISSION_DENIED' | 'NOT_AVAILABLE'; message: string };

/** 插件设置页 / 面板可读取的 Cindy Core 媒体模型类型。 */
export const GHOST_MEDIA_MODEL_TYPES = ['image', 'video'] as const;
export type GhostMediaModelType = (typeof GHOST_MEDIA_MODEL_TYPES)[number];

/** 四项 Cindy 媒体能力键(cindy-preference 只读查询用;插件没有逐项选模,返回系统默认选型)。 */
export const GHOST_MEDIA_CAPABILITIES = [
  'image.generate',
  'image.edit',
  'video.generate',
  'video.edit',
] as const;
export type GhostMediaCapability = (typeof GHOST_MEDIA_CAPABILITIES)[number];

/** 插件读取自身某项 Cindy 媒体能力当前实际选型的只读结果。 */
export type GhostCindyPreferenceResult =
  | { ok: true; capability: GhostMediaCapability; modelId: string; providerId: string }
  | {
      ok: false;
      errorCode: 'INVALID_REQUEST' | 'PERMISSION_DENIED' | 'NOT_AVAILABLE';
      message: string;
    };

/**
 * 插件配置界面使用的只读可执行媒体模型目录。Host 根据插件声明、Gateway modalities、
 * Guide operation 与当前客户端协议支持度过滤模型;响应只保留归一化 modalities,
 * 不向插件暴露 Guide 或内部兼容判定。
 */
export type GhostMediaModelsResult =
  | {
      ok: true;
      type: GhostMediaModelType;
      models: Array<{
        id: string;
        name: string;
        /** 同名模型可由多个来源提供;与 id 一起构成精确选择。 */
        providerId: string;
        /** Gateway architecture 的归一化投影;缺省表示上游未声明,插件不得猜测。 */
        modalities?: { input: string[]; output: string[] };
      }>;
      defaultModelId: string | null;
      defaultProviderId: string | null;
    }
  | {
      ok: false;
      errorCode: 'PERMISSION_DENIED' | 'NOT_AVAILABLE';
      message: string;
    };

/**
 * 上行:聊天卡片供片(卡槽③海报模式)。意识为自己的一次 tool-call
 * 提供聊天流卡片内容:收到 tool-call 后即可发第一版(过程海报),执行中
 * 整版换稿(主机按 GHOST_CARD_MIN_INTERVAL_MS 限速),交卷前发最终版。
 * html 必须是纯静态 HTML+CSS——脚本/事件属性/外链会被主机 sanitizer 剥除,
 * 图片只认本意识名下的 cindy-media://blobs/<指纹>.<ext> 地址。
 * 不发 = 聊天流按今日默认渲染(通用图卡),卡片是每次调用的可选项。
 */
export interface GhostPipeCardUpdate {
  type: 'card-update';
  /** Active tool call in the same task, when refreshing an earlier owned card. */
  sourceCallId?: string;
  /** 归因号:tool-call 下发的 callId 原样带回(主机验"这单是不是派给你的")。 */
  callId: string;
  /** 卡片正文(静态 HTML+CSS;≤ GHOST_CARD_HTML_MAX_BYTES,超限整条拒)。 */
  html: string;
  /** 期望渲染高度 px(clamp 到 [GHOST_CARD_HEIGHT_MIN, GHOST_CARD_HEIGHT_MAX])。 */
  height?: number;
  /**
   * 协议版本:1 = 海报模式(静态);2 = 交互卡(HTML 里可含 data-ghost-action
   * 按钮,点击经宿主回传 card-action 事件)。缺省 1。渲染层的点击委托对 v1/v2
   * 都生效(v 仅作意图声明 + 遥测),真正的闸是净化器放行 data-ghost-action。
   */
  v?: 1 | 2;
  /**
   * 后台活动状态声明(可选):
   * 'working' = 过程态、还在干活——主机据此:(a) 保持会话侧栏的运行呼吸;
   *   (b) 渲染层持续播放该卡的自绘动画(不再随调用 settle 停播);(c) 把该
   *   卡位的更新窗口跨调用保持打开(自首个 'working' 起封顶
   *   GHOST_CARD_WORKING_WINDOW_MS)——生成类意识可以把过程卡钉在提交调用
   *   的卡位上,由后续轮询调用持续刷进度,终态媒体(视频/音频播放器)仍由
   *   无卡的轮询调用按基座默认渲染。
   * 'done' = 终版——熄灭呼吸、关闭跨调用窗口(回到 settle 宽限语义)。
   * 不声明 = 旧语义(settle + 宽限窗;card-action 场景由主机"点击即亮、
   * 静默超时自动灭"兜底)。非法值整条拒收。
   */
  state?: 'working' | 'done';
}

/**
 * state:'working' 声明打开的跨调用更新窗口上限 ms(自该卡**首个** working
 * 版本起算,固定不滑动)。意义:让"提交调用画常驻过程卡、轮询调用跨卡位刷
 * 进度"的生成类流程走得通(视频/音乐可长达十几分钟);**固定上限**是安全
 * 缓冲——settle 后锁卡本是"不给已完结消息留远程改写面"的防线,working 窗口
 * 是对它的有界豁免,不能被意识用连续 working 无限续命。
 */
export const GHOST_CARD_WORKING_WINDOW_MS = 30 * 60_000;

/** 卡片 html 字节上限(UTF-8;与 manifest tools[].parameters 16KB 同精神,卡片放宽一倍)。 */
export const GHOST_CARD_HTML_MAX_BYTES = 32 * 1024;
/** 卡片渲染高度下限 px。 */
export const GHOST_CARD_HEIGHT_MIN = 120;
/** 卡片渲染高度上限 px(容 ~460 宽通栏竖图 9:16 + 题注;与 generic 图卡的
 *  "高图可以很高"口径对齐,再高截断)。 */
export const GHOST_CARD_HEIGHT_MAX = 900;
/** 未声明 height 时的缺省渲染高度 px。 */
export const GHOST_CARD_HEIGHT_DEFAULT = 240;
/** 同一 callId 两版卡片的最小间隔 ms(首版免罚;超发静默丢,防聊天流被刷)。 */
export const GHOST_CARD_MIN_INTERVAL_MS = 1000;

/**
 * 交互卡按钮的 action id 形状(v2,data-ghost-action 值):意识声明、宿主回传。
 * 收 `:`——mivo 的 customId 形如 `MJ::JOB::upsample::1::<uuid>` /
 * `NANOBANANA::image::imgPrompt::0::<id>`,含双冒号;长度放到 128。净化器按此
 * 校验,不合法整属性丢(元素本身仍在,只是点不动)。
 */
export const GHOST_CARD_ACTION_ID_RE = /^[A-Za-z0-9_:-]{1,128}$/;

/**
 * 宿主点击后的本地锁定窗口 ms:点了按钮先禁用/防连点,等意识 card-update
 * 换新卡自然解锁;窗口内意识没换卡也自动解禁(防卡死)。
 */
export const GHOST_CARD_ACTION_INFLIGHT_MS = 8000;

/**
 * 需要用户输入文字的动作(data-ghost-prompt 声明,如 mivo 的 imgPrompt 改写):
 * 宿主点击时弹输入框收集,随 card-action 的 prompt 字段回传。两个上限:
 * 输入正文与占位文案(data-ghost-prompt 属性值,超限整属性丢)。
 */
export const GHOST_CARD_ACTION_PROMPT_MAX_LEN = 2000;
export const GHOST_CARD_PROMPT_PLACEHOLDER_MAX_LEN = 128;

/**
 * 卡内外链声明(data-ghost-link,<a href> 由净化器转写为同一属性)的值上限。
 * 超限整属性丢(元素与文字保留,只是点不动)。
 */
export const GHOST_CARD_LINK_MAX_LEN = 2048;

/**
 * 卡内外链声明的白名单校验(净化器与宿主点击桥共用,双层同判):
 * 仅整串 http/https URL;空白与控制字符出现即拒——URL 构造器会静默剥掉
 * TAB/CR/LF,校验对象与落地属性值必须是同一串,不给"解析后合法、原文
 * 混淆"留缝。真实跳转仍由 main 的 shell:open-external 再验一道协议(第三道)。
 */
export function isGhostCardLinkAllowed(url: string): boolean {
  if (typeof url !== 'string' || url.length === 0 || url.length > GHOST_CARD_LINK_MAX_LEN) {
    return false;
  }
  for (let i = 0; i < url.length; i++) {
    const c = url.charCodeAt(i);
    if (c <= 32 || c === 127) return false;
  }
  if (!/^https?:\/\//i.test(url)) return false;
  try {
    const parsed = new URL(url);
    return parsed.protocol === 'http:' || parsed.protocol === 'https:';
  } catch {
    return false;
  }
}

/**
 * 衍生卡 callId 的分隔标记:card-action 派发时主机铸造 `<根callId>::sp<序>`
 * 作为新卡位(spawnCallId)随事件下发。意识对它 card-update = 在原卡下方长出
 * 一张新卡(原卡原封不动——MJ 抽卡式玩法,母卡按钮可反复点);仍写原 callId
 * = 原地换卡(旧行为,向后兼容)。所有衍生卡平铺挂在根卡下:点衍生卡上的
 * 按钮,新 spawn 仍以根 callId 为前缀铸造,不嵌套(callId 长度恒定)。
 * renderer 据此前缀识别衍生卡:不进活卡锚定池、堆叠渲染在母卡画布下方。
 */
export const GHOST_CARD_SPAWN_SEP = '::sp';

/** 取衍生卡的根 callId(非衍生卡原样返回)。 */
export function ghostCardRootCallId(callId: string): string {
  const i = callId.indexOf(GHOST_CARD_SPAWN_SEP);
  return i === -1 ? callId : callId.slice(0, i);
}

/**
 * card-action 触发后的卡片"重开"窗口 ms。交互卡的按钮常在卡片结算很久后
 * (甚至重启后)才被点,那时卡片调用早过 GRACE_MS 宽限、内存条目已被清扫,
 * 意识想 card-update 换新卡会撞 too-late/unknown-call。所以派发 card-action
 * 前把该 callId 重开为 in-flight(窗内自由更新,窗外由懒清扫回收);窗口取足够
 * 长以覆盖一次按钮动作的完整轮询(mivo 单窗 105s + 下载 + 余量)。
 */
export const GHOST_CARD_REOPEN_WINDOW_MS = 600_000;

/**
 * tool_result JSON 顶层的卡片配对令牌键名。仅当该次调用真供过卡时由主机
 * 注入(值 = callId),renderer 据此从卡片库取卡渲染;模型侧 mediaHint 已
 * 声明忽略。
 */
export const GHOST_CARD_ID_KEY = 'xdt_card_id';

/**
 * notify 槽的提示语气(→ 主机 Toast 的 variant;缺省 'info')。
 * 只影响图标与配色,不改变"轻提示、自动消失、无按钮"的形态。
 */
export const GHOST_NOTIFY_TONES = ['info', 'success', 'warning', 'error'] as const;
export type GhostNotifyTone = (typeof GHOST_NOTIFY_TONES)[number];

/**
 * 上行:系统提示(notify 槽,2026-07-14)。意识请主机在屏幕顶部弹一条
 * 轻提示(toast):意识只供**纯文本**(不是 HTML,主机原样作文本渲染,
 * 控制字符剥除、超限拒收),提示壳与意识身份头(图标+名字)由主机画——
 * 意识伪装不了主机通知、也冒充不了别的意识(信任边界与订阅槽红条同款)。
 * 无阻塞、无按钮、无回执;确认类交互不在本槽(面板自绘或卡槽③交互卡)。
 * 典型场景:分钟级代办完成、授权即将过期、订阅旁听发现值得提醒的事。
 */
export interface GhostPipeNotify {
  type: 'notify';
  mobilePageId?: string;
  /** 提示正文(纯文本,≤ GHOST_NOTIFY_MAX_CHARS;允许 \n 换行)。 */
  text: string;
  /** 语气(图标/配色);缺省 'info'。 */
  tone?: GhostNotifyTone;
}

/** notify 的 invoke 返回(失败带人话原因,供意识作者调试;不涉他人信息)。 */
export type GhostPipeNotifyResult = { ok: true } | { ok: false; message: string };

/**
 * 上行:未读角标(badge 槽,2026-08-03)。意识告诉主机"我这儿有新内容了",
 * 主机在插件入口与插件卡上点一颗**绿点**,并把 summary 显示在卡片简介位。
 *
 * 与 notify 的分工:notify 是"弹一条即走"的一次性 toast(错过就没了);本消息
 * 是**持久状态**——用户没去看就一直亮着,打开面板即清零。两者是**并列的两档
 * 权限**,不是加档关系:要 toast 声明 `notify` 槽,要绿点声明 `badge` 槽,
 * 谁也不是谁的前置(绿点比 toast 克制,不该被 toast 权限捆绑)。
 *
 * 门槛(validateGhostManifest 强制):只有声明了 `panel` 的意识能申请。理由是
 * 未读点承诺"点开能看到内容",纯工具型/对话型意识没有可打开的界面,给了就是
 * 骗点击。
 *
 * 信任边界与 notify 同款:意识只供纯文本 summary(净化 + 限长),点的颜色、
 * 位置、身份头全由主机画;意识改不了别人的角标(id 由沙箱绑定,不看载荷自报)。
 */
export interface GhostPipeBadge {
  type: 'badge';
  /** true = 有未读(点亮);false = 自己清零(如意识内已读)。 */
  unread: boolean;
  /**
   * 最新一条的摘要(纯文本,≤ GHOST_BADGE_SUMMARY_MAX_CHARS)。
   * 显示在插件卡的简介位,替代静态描述——用户扫一眼就知道新内容是什么。
   * unread:false 时忽略。
   */
  summary?: string;
}

/** badge 的 invoke 返回(与 notify 同款结构化拒绝,不抛异常穿透沙箱)。 */
export type GhostPipeBadgeResult = { ok: true } | { ok: false; message: string };

/**
 * 未读摘要长度上限。比 notify 正文更短:它要挤进卡片一行、单行省略,
 * 太长的部分用户根本看不到,不如让作者自己裁。
 */
export const GHOST_BADGE_SUMMARY_MAX_CHARS = 80;

/**
 * 同一意识两次角标上报的最小间隔 ms。比 notify 宽松得多——角标是幂等的
 * 状态写入(不像 toast 每条都打扰用户),但仍要挡住死循环刷写。
 */
export const GHOST_BADGE_MIN_INTERVAL_MS = 500;

/** 提示正文长度上限(与订阅槽 block reason ≤200 同量级:一眼能读完的量)。 */
export const GHOST_NOTIFY_MAX_CHARS = 200;

/**
 * 主机代言提示的文案键(host-origin notice,2026-07-14):凭证入库 / 授权
 * 成功这类**主机权威事件**的 tips——事件判定者是主机(/secrets 入库、OAuth
 * 流程收尾都在主机手里),不经意识代码、不占意识 notify 限速、也不要求意识
 * 声明 notify 槽。广播走同一 ghosts:notify 通道但载荷带 textKey/textArgs
 * (而非 text):文案是主机说的话,必须跟用户语言走,由 renderer 按本白名单
 * 校验后翻译渲染(i18n `chat.ghostNotify.<key>`);白名单外的键静默丢弃,
 * 防版本错配时把生肉 key 摆上界面。
 */
export const GHOST_HOST_NOTICE_KEYS = [
  'secretSaved',
  'oauthConnected',
  'oauthConnectedNoLabel',
  'connectionAdded',
] as const;
export type GhostHostNoticeKey = (typeof GHOST_HOST_NOTICE_KEYS)[number];

/** 同一意识两条提示的最小间隔 ms(超发拒收,防 toast 刷屏骚扰)。 */
export const GHOST_NOTIFY_MIN_INTERVAL_MS = 5000;

/**
 * 上行:确认弹窗(confirm 槽,2026-07-31)。意识请主机弹**主机同款**的二选一
 * 确认框(renderer 的 ConfirmDialogProvider),拿回用户的真实点击。
 *
 * 与 notify 的分工:notify 是「说一句就走」(无按钮无回执),本槽是「要一个答复」。
 * 所以它会打断用户,骚扰面更大,护栏对齐 pick 槽(限速 + 全局单飞 + fail closed)。
 *
 * 信任边界:弹窗的壳、标题(主机文案「插件「X」请你确认」)与身份头(图标 + 名字)
 * 全由主机画,身份取自已装清单而非载荷自报;意识只供 `body` 与按钮字,且一律过
 * sanitizeGhostNoticeText 净化 + 长度上限。意识发起得了请求,点不了自己的按钮。
 */
export interface GhostPipeConfirm {
  type: 'confirm-request';
  /** Forward the originating mobile business request's opaque page ID, if present. */
  mobilePageId?: string;
  /** 问句正文(纯文本,≤ GHOST_CONFIRM_BODY_MAX_CHARS;允许 \n 换行)。 */
  body: string;
  /** 主按钮文案(≤ GHOST_CONFIRM_BUTTON_MAX_CHARS);缺省用主机的「确认」。 */
  confirmText?: string;
  /** 次按钮文案(同上上限);缺省用主机的「取消」。 */
  cancelText?: string;
  /** 危险动作(删除/覆盖/改用户文件):主按钮走 destructive 语义色。缺省 false。 */
  danger?: boolean;
}

/**
 * confirm 的 invoke 返回。`ok:true` 只代表**问到了**;答案看 `confirmed`——
 * false = 用户点了取消 / 按了 Esc / 点了弹窗外部。
 * 失败分档带 errorCode,方便意识作者区分"被限速"与"用户拒绝"(两者处理完全不同)。
 */
export type GhostPipeConfirmResult =
  | { ok: true; confirmed: boolean }
  | {
      ok: false;
      errorCode:
        | 'PERMISSION_DENIED'
        | 'INVALID_REQUEST'
        | 'RATE_LIMITED'
        | 'BUSY'
        | 'UNAVAILABLE'
        | 'INTERNAL';
      message: string;
    };

/** 问句正文上限(比 notify 的 200 宽一点:确认要把后果说清,但仍是一眼读完的量)。 */
export const GHOST_CONFIRM_BODY_MAX_CHARS = 300;

/** 按钮文案上限(按钮就那么宽;超长会挤坏弹窗版式)。 */
export const GHOST_CONFIRM_BUTTON_MAX_CHARS = 12;

/** 同一意识两次确认请求的最小间隔 ms(按尝试记账,与 pick 槽同量级)。 */
export const GHOST_CONFIRM_MIN_INTERVAL_MS = 3000;

/**
 * 无人应答的兜底超时 ms:到点当「没同意」。
 * 90 秒是刻意选的——小于插件面板侧常用的 180 秒请求超时,好让面板拿到一个干净的
 * "用户没答应"而不是自己先超时、留下一个语义不明的悬空请求。
 */
export const GHOST_CONFIRM_TIMEOUT_MS = 90_000;

/** cindy 槽代办的质量档位:意识只表达"要多好",具体模型由主机解析表决定。 */
export const GHOST_MODEL_TIERS = ['draft', 'standard', 'best'] as const;
export type GhostModelTier = (typeof GHOST_MODEL_TIERS)[number];

/**
 * cindy 槽生图代办的画幅意图:方图 / 横图 / 竖图。与 tier 同一哲学——意识
 * 只声明比例意图,主机翻译成当前后端支持的具体像素尺寸(枚举值即真实产出
 * 比例,当前三档全后端可兑现,不做"最近似"降级)。将来扩值域(如 16:9)
 * 是向后兼容的加法,老意识不受影响。
 */
export const GHOST_IMAGE_ASPECT_RATIOS = ['1:1', '3:2', '2:3'] as const;
export type GhostImageAspectRatio = (typeof GHOST_IMAGE_ASPECT_RATIOS)[number];

/**
 * cindy 槽视频代办的画幅比例。与生图的 aspectRatio 分开成两套值域:视频
 * 后端(video provider 层)的公共集是 16:9 系,与图像后端的原生尺寸枚举
 * 没有交集,合成一套只会让两边都出现"声明了却兑现不了"的值。这里登记的
 * 是**所有已注册 provider 都支持**的交集,单个型号的实际支持集由主机在
 * 解析出选型后二次校验(型号不支持即明拒,不做最近似降级)。
 */
export const GHOST_VIDEO_RATIOS = ['16:9', '9:16', '1:1', '4:3', '3:4'] as const;
export type GhostVideoRatio = (typeof GHOST_VIDEO_RATIOS)[number];

/** cindy 槽视频代办的分辨率档(同 GHOST_VIDEO_RATIOS 的口径:公共集 + 按型号二次校验)。 */
export const GHOST_VIDEO_RESOLUTIONS = ['480p', '720p', '1080p'] as const;
export type GhostVideoResolution = (typeof GHOST_VIDEO_RESOLUTIONS)[number];

/**
 * edit_video 的参考图用法(2026-07 加法)。同样是「N 张图」,两种模式出片
 * 完全不同,所以由调用方显式声明,不靠张数隐式推断:
 *   - `'first_and_last_frame'`(**缺省**):1 张=首帧动画,2 张=首尾帧过渡。
 *     这是本字段出现之前的唯一行为,不传即走这条,与老协议逐字节同形——
 *     存量插件不改一行代码、不重新授权,行为不变。
 *   - `'reference_image'`:多张参考图锁主体/元素/风格,由模型另行构图。
 *     提示词里须用 `[Image 1]`、`[Image 2]` 指代第几张(上游要求;主机遵守
 *     提示词 passthrough,不代写),张数上限随型号,由主机按选型二次校验。
 *
 * 值域是**所有已注册 provider 的并集**,单个型号支不支持某种用法由主机在
 * 解析出选型后二次校验(不支持即明拒,不降级成另一种用法——降级会出一条
 * 用户没要的片子还照样计费)。
 */
export const GHOST_VIDEO_REF_MODES = ['first_and_last_frame', 'reference_image'] as const;
export type GhostVideoRefMode = (typeof GHOST_VIDEO_REF_MODES)[number];

/** 不传 refMode 时的落点。改这个值 = 改存量插件的行为,不要动。 */
export const GHOST_VIDEO_REF_MODE_DEFAULT: GhostVideoRefMode = 'first_and_last_frame';

/**
 * 各 refMode 的参考图张数上界(协议层粗筛,与型号无关):
 *   - 首尾帧:首 + 尾,语义上界就是 2,任何型号都不会更多。
 *   - 参考图:9,当前所有 provider 的最大值。
 * 型号实际上限更低(如 happyhorse 首尾帧模式只有首帧,上限 1)由主机在
 * 解析出选型后二次校验。
 *
 * 张数之外还有一道按模式分档的**总字节闸**
 * (GHOST_VIDEO_REF_IMAGE_MAX_TOTAL_BYTES_BY_REF_MODE):9 张小图与 2 张巨图
 * 是不同的失败面。
 */
export const GHOST_VIDEO_MAX_SOURCES_BY_REF_MODE: Readonly<Record<GhostVideoRefMode, number>> = {
  first_and_last_frame: 2,
  reference_image: 9,
};

/**
 * 单次图生视频的**参考图总字节**上限。张数闸(见
 * GHOST_VIDEO_MAX_SOURCES_BY_REF_MODE)管"几张",这道闸管"多大" —— 主机要把
 * 每张读成 base64 data URI 交给上游,链上会同时存在原始 Buffer(1×)+ base64
 * 字符串(4/3×)+ JSON 请求体(再 4/3×),峰值约聚合量的 3.7 倍。
 *
 * **按 refMode 分档,不能统一取一个数**:两种模式的约束不相交 —— 存量路径
 * 要的是"一单都不许比改之前更严",新路径要的是"最坏值必须有界",能同时满足
 * 两者的统一数不存在(见下)。null = 该模式不设闸。
 */
export const GHOST_VIDEO_REF_IMAGE_MAX_TOTAL_BYTES_BY_REF_MODE: Readonly<
  Record<GhostVideoRefMode, number | null>
> = {
  /*
   * 存量路径:**不设闸,原样保留**。
   *
   * 这条路径在多参考图之前没有任何字节闸,而源图远不止来自寄存 ——
   * resolveOwnedMedia 走 ledger.ghostCanRead,放行的还有 ghost-gallery
   * (network as:'media' 落仓,单张硬顶 GHOST_FETCH_MEDIA_MAX_BYTES = 256MB)
   * 与 ghost-grant(用户随附件引渡,上限另算)。所以"源图 ≤ 寄存上限 50MB"
   * 不成立,任何有限预算都可能拒掉一单改之前跑得通的活。
   *
   * 这条路径的 OOM 暴露面是**既有**问题(edit_image 吃源图同样没有闸),
   * 收紧它要改存量行为,不在本 PR 范围,已列入 PR 风险区跟踪。
   */
  first_and_last_frame: null,
  /*
   * 新路径:张数放到 9,不设闸最坏能拖进 9 × 256MB。这个模式是随本 PR 新开
   * 的,没有存量插件依赖,所以从第一天就给个保守边界。
   *
   * 100MB 聚合 → 峰值约 370MB(原始 Buffer 1× + base64 4/3× + JSON 请求体
   * 再 4/3×),是 main 进程能吞下的量级;9 张均摊 11MB,对参考图绰绰有余
   * (1080p 级单张通常几 MB)。不与寄存上限挂钩:那个数管"单张能存多大",
   * 与"一单能读多少"不是同一件事,挂上去只会绑出假的联动。
   */
  reference_image: 100 * 1024 * 1024,
};

/**
 * 视频时长/帧率的形状上限(秒 / fps)。这两项各型号差异大(如 seedance
 * 支持 4/6/8/10 秒,happyhorse 只有 5 秒),协议层不枚举值域,只做"正整数
 * 且不离谱"的粗筛,真正的可用集由主机按解析出的型号校验并在拒绝话术里
 * 列出。粗筛的意义是挡住沙箱乱填(负数、小数、天文数字)。
 */
export const GHOST_VIDEO_MAX_DURATION_SECONDS = 60;
export const GHOST_VIDEO_MAX_FPS = 120;

/**
 * 异步代办(mode:'submit')完成结果的保留时长(毫秒,30 分钟):完成后
 * 过期即清,query_job 查无此单。TTL 之外还有每意识完成记录条数上限
 * (cindySlot 的 settled-job eviction):快速提交循环下最旧的完成记录会
 * 在 TTL 未到时被提前淘汰。任务表在内存(主进程重启即丢),意识须把
 * "查无此单"当作可重新提交的正常失败面。
 */
export const GHOST_CINDY_JOB_TTL_MS = 30 * 60_000;

/**
 * 每意识后台异步代办在途上限。同步代办天然被管子超时与 agent 节奏限流,
 * 异步提交是瞬时的,必须有内置闸防批量提交刷爆付费通道;用户配置的
 * inflightLimit(同时约束同步+异步)更严时以更严者为准。
 */
export const GHOST_CINDY_MAX_ASYNC_JOBS = 2;

/**
 * ── deposit_media 政策参数(makecindy/cindy#784)─────────────────────────
 *
 * 寄存是插件写持久媒体的第三条路,而且是唯一**两道闸都没有**的一条:模型
 * 代办要花钱(成本即天然限流),network `as:'media'` 限 manifest 白名单域名,
 * 寄存收的是本地字节 —— 不花钱、不出网、可程序化循环调用。因此这条通道
 * 自带三重硬闸:单次上限、每意识累计配额、令牌桶频控。
 */

/**
 * 单次寄存上限(解码后字节;超限整单拒)。
 *
 * 2026-07-29 由 16MB(fs 槽单次写量级)上调至 50MB:实拍照片与短视频素材
 * 常态超过 16MB,压到 16MB 以下要插件自己转码,与"画布上的图直接能改"的
 * 目标冲突。下游没有新的天花板 —— network `as:'media'` 的入仓硬顶本就是
 * GHOST_FETCH_MEDIA_MAX_BYTES(256MB),blobStore 不设上限。
 *
 * 代价说明白:寄存的字节以 base64 走一次 ghost-pipe IPC(50MB → 约 67MB
 * 字符串的瞬时分配),这是本通道与 network 通道的结构性差别 —— 后者字节
 * 全程在主机手里、不过 IPC。因此这个数不宜再往上抬;真需要更大的素材,
 * 正确解法是插件侧压缩或分片,不是继续抬上限。
 */
export const GHOST_CINDY_DEPOSIT_MAX_BYTES = 50 * 1024 * 1024;

/**
 * 每意识寄存累计配额(字节)。只统计**寄存**引用(refKind 'ghost-deposit'),
 * 不含模型产物与 network 下载 —— 否则一个出图很多的意识会连一张参考图都
 * 存不进来。内容寻址天然去重:同一张图反复寄存不重复占额。
 * 用满的释放口是 release_media(面板删素材时撤回),不做静默 LRU 淘汰
 * ——"昨天能改今天改不了"正是 #784 要消灭的体验。
 *
 * 2026-07-29 由 512MB 上调至 1GB:单次上限同步抬到 50MB 后,原配额只够存
 * 十来件大素材,重度使用的无限画布会频繁撞顶。
 */
export const GHOST_CINDY_DEPOSIT_QUOTA_BYTES = 1024 * 1024 * 1024;

/**
 * 频控令牌桶:容量 = 允许的突发张数(用户一次粘一批图要立刻可用),
 * 之后按 refill 间隔匀速回补。防的是程序化死循环刷仓,不是拦正常批量粘贴。
 */
export const GHOST_CINDY_DEPOSIT_BURST = 8;
export const GHOST_CINDY_DEPOSIT_REFILL_MS = 1000;

/**
 * ── oneshot_text 政策参数(2026-07-31 开闸)────────────────────────────
 * 快问快答走轻量任务模型链,秒级到几十秒,只有同步形态(没有 submit 档:
 * 一单等不起的文本问答本身就是用错了通道)。prompt 上限对齐 agent-request
 * 的消息量级;输出**不设宿主级上限**——缺省按各供应商/模型的自然输出,
 * 插件可显式传 maxTokens 自我约束(仅正整数校验,不设上限),单次等待上限
 * (60s 超时)是实际边界。与宿主会话一致:用户主动使用插件的成本由用户承担,
 * 宿主不额外钳制输出 token 数(2026-08-07 决策)。
 */
export const GHOST_ONESHOT_TEXT_MAX_PROMPT_CHARS = 32_768;
/** 单次快问快答的等待上限(毫秒;超时按结构化失败收单,不吊管子)。 */
export const GHOST_ONESHOT_TEXT_TIMEOUT_MS = 60_000;

/** Cindy 托管 Web Search 的请求边界。 */
export const GHOST_CINDY_SEARCH_MAX_QUERY_CHARS = 2000;
export const GHOST_CINDY_SEARCH_DEFAULT_RESULTS = 5;
export const GHOST_CINDY_SEARCH_MAX_RESULTS = 10;

/**
 * ── embed_text 政策参数(2026-08-04 开闸)──────────────────────────────
 * 上限不是抄上游 API 的(Voyage / OpenAI 都收到 1000 条一批),而是被**回传体积**
 * 钉住的:向量原样穿管子回沙箱,一条 3072 维 float 序列化成 JSON 约 60KB ——
 * 32 条就是 ~2MB 一次 postMessage。再往上抬会让沙箱与主机同时卡在序列化上,
 * 而分批对调方只是多一次 await。
 *
 * 单条字符上限比 oneshot 低一档:embedding 模型的 context 本就短(最小的
 * gemini-embedding-2 只有 8K token),超长文本该由调方按语义切块,而不是指望
 * 上游 truncation 静默截掉后半段 —— 那样返回的向量代表的是被截断的文本,
 * 检索质量的坑不可见。
 */
export const GHOST_CINDY_EMBED_MAX_TEXTS = 32;
export const GHOST_CINDY_EMBED_MAX_CHARS_PER_TEXT = 8_192;
/** 单批的总字符预算(防 32 条 × 8K 顶格叠加成一次巨型请求)。 */
export const GHOST_CINDY_EMBED_MAX_TOTAL_CHARS = 65_536;
/** 单次向量代办的等待上限(毫秒;同 oneshot,超时按结构化失败收单)。 */
export const GHOST_CINDY_EMBED_TIMEOUT_MS = 60_000;

/**
 * 上行:cindy 槽代办请求(请 Cindy 本体出图 / 改图)。协议 type 为
 * 'cindy-request'(2026-07-11 由 'model-request' 更名,主机对旧名保持
 * 静默兼容)。选型双轨:
 * - tier(推荐):档位意图(draft 快省草稿 / standard 默认 / best 最好),
 *   主机按解析表翻译成当下的具体模型——意识代码永不腐烂;
 * - model(仅透传场景):用户在会话里显式点名某模型时原话带给主机,
 *   白名单外一律拒。意识自己**不要**替用户做选型。
 * 两者都给时 model 优先。意识永远不经手 key,也决定不了白名单之外的路由。
 */
export type GhostPipeCindyRequest =
  | {
      type: 'cindy-request';
      kind: 'gen_image';
      prompt: string;
      tier?: GhostModelTier;
      model?: string;
      /**
       * 画幅比例(可选):'1:1' 方图 / '3:2' 横图 / '2:3' 竖图;不传 =
       * 后端自定(auto)。比例是意图声明,主机映射为该后端的具体尺寸,
       * 实际像素以返回的 width/height 为准。图像类代办(生图/改图)专用,
       * 视频类请改用 ratio(值域不同),带错了会被明拒。
       */
      aspectRatio?: GhostImageAspectRatio;
      /**
       * 归因号(可选):这单代办由哪次 tool-call 触发,把收到的
       * callId 原样带上——配额记账、日志、用量面板由此对上"哪次调用花的
       * 钱"。面板交互等无 tool-call 语境的代办可不带(日志记 unattributed)。
       */
      callId?: string;
    }
  | {
      type: 'cindy-request';
      kind: 'edit_image';
      prompt: string;
      /**
       * 源图指纹(sha256,1–4 张)。只能引用本意识名下(出生自它或挂在
       * 它画廊)的媒体——主机逐张查账验归属,查无此账即拒。
       */
      hashes: string[];
      tier?: GhostModelTier;
      model?: string;
      /**
       * 画幅比例(可选,语义同 gen_image 分支)。不传 = 跟随源图画幅
       * (后端 auto),这也是历史行为;传了则按该比例重绘。
       */
      aspectRatio?: GhostImageAspectRatio;
      /** 归因号(同 gen_image 分支)。 */
      callId?: string;
    }
  | {
      type: 'cindy-request';
      kind: 'gen_video';
      prompt: string;
      tier?: GhostModelTier;
      model?: string;
      /**
       * 画面参数(全部可选):不传 = 该型号的出厂默认(与历史行为逐字节
       * 同形)。ratio/resolution 的值域见 GHOST_VIDEO_RATIOS /
       * GHOST_VIDEO_RESOLUTIONS;duration(秒)与 fps 各型号支持集不同,
       * 主机按解析出的选型校验,不支持即明拒并列出可用值。实际生效的
       * 参数随结果回传(见 GhostPipeModelResult 的 videoParams)。
       */
      ratio?: GhostVideoRatio;
      resolution?: GhostVideoResolution;
      duration?: number;
      fps?: number;
      /**
       * 要不要同时生成音频(对白 / 音效 / 背景音乐;2026-08 加法)。
       *
       * **三态,不传与传 false 不是一回事**:
       *   - 不传(**缺省**):主机不向上游传递任何音频字段,出声与否随该型号
       *     的上游默认——与本字段出现之前逐字节同形。存量插件不改一行代码,
       *     产出不变。
       *   - `true`:显式要求带音轨。台词/音效/配乐的具体内容写在 prompt 里
       *     (主机遵守提示词 passthrough,不代写)。
       *   - `false`:显式要求静音。
       *
       * 不是所有型号都有音轨能力:主机按解析出的选型二次校验,不支持的型号
       * 上**显式传**本字段即明拒(不静默忽略——静默出一条无声/有声都不是
       * 用户要的片子,还照样计费)。不传则永远不会因此被拒。
       *
       * 实际生效值随结果回传(见 GhostVideoResultParams 的 audio)。
       */
      audio?: boolean;
      /** 归因号(同 gen_image 分支)。 */
      callId?: string;
      /**
       * 异步模式(仅视频类代办):'submit' = 资格审与源图校验通过后立即
       * 返回 jobId,生成在后台继续,用 kind:'query_job' 轮询取件。适合
       * 可能超过管子超时窗口的超长任务;缺省同步等待(主机会为署名单
       * 自动续命,分钟级任务推荐同步)。
       */
      mode?: 'submit';
    }
  | {
      type: 'cindy-request';
      kind: 'edit_video';
      prompt: string;
      /**
       * 参考图指纹(sha256)。张数上限随 `refMode` 变化:
       *   - `first_and_last_frame`(缺省):1–2 张(1 张=首帧动画,2 张=首尾帧过渡)。
       *   - `reference_image`:1–N 张,N 随型号(主机按选型二次校验后明拒)。
       * 归属规则同 edit_image:只能引用本意识名下的媒体。**顺序有意义**——
       * 首尾帧模式下是首/尾,参考图模式下是提示词里 `[Image 1]`…的序号。
       */
      hashes: string[];
      /**
       * 参考图用法(见 GHOST_VIDEO_REF_MODES)。不传 = `first_and_last_frame`,
       * 与本字段出现之前逐字节同形。注意别和下面的 `mode`(异步受理)搞混:
       * 那个管的是同步还是后台跑,两者正交,可同时传。
       */
      refMode?: GhostVideoRefMode;
      tier?: GhostModelTier;
      model?: string;
      /** 画面参数(同 gen_video 分支;参考图不改变这几项的语义)。 */
      ratio?: GhostVideoRatio;
      resolution?: GhostVideoResolution;
      duration?: number;
      fps?: number;
      /** 音频开关(同 gen_video 分支的三态语义;参考图不改变它的含义)。 */
      audio?: boolean;
      /** 归因号(同 gen_image 分支)。 */
      callId?: string;
      /** 异步模式(同 gen_video 分支)。 */
      mode?: 'submit';
    }
  | {
      /**
       * Cindy 托管 Web Search:主机固定使用当前 XD endpoint、XD user key
       * 与内置 Anthropic Messages 搜索模型,不接受意识传入
       * api_base/header/key/model/tool。
       * `provider` 固定为 cindy,用于与插件 network 槽的 BYO Brave/Tavily
       * 明确分账。
       *
       * 须声明 'cindy' 卡槽 + `cindy.search: ["web"]`。
       */
      type: 'cindy-request';
      kind: 'search_web';
      /** 用户原话查询,trim 后 1–2000 字符。 */
      query: string;
      /** 结果条数,1–10,缺省 5。 */
      limit?: number;
      /** 固定为 cindy;其它值明拒。 */
      provider: 'cindy';
      /** 搜索只由 tool-call 触发,必须透传本次 callId 用于账单与日志归因。 */
      callId: string;
      /** 必须透传本次 tool-call 的 msg.tool,供宿主与 callId 事实表配对验身。 */
      callerTool: string;
    }
  | {
      type: 'cindy-request';
      kind: 'query_job';
      /** mode:'submit' 受理时返回的任务号(仅本意识自己的任务可查)。 */
      jobId: string;
    }
  | {
      /**
       * 寄存:把意识手里已有的媒体字节存入总仓、记到本意识名下,换回指纹
       * (makecindy/cindy#784)。典型来源是面板里用户粘贴/拖入的图与面板存量
       * 素材——它们的字节只在面板侧(IndexedDB / 面板内存),不在总仓,因此
       * 在寄存之前不能当 edit_image / edit_video 的源图。
       *
       * 不经模型、不花钱、不产出新内容:这条通道只是"字节换指纹"。因此它
       * **不进 ghost_call 产物账**(不会被当成生成物自动送进聊天/IM——用户
       * 自己粘的参考图被回推到 IM 会是隐私事故),也不进画廊(粘贴的参考图
       * 不是这个意识的"作品")。
       *
       * 须声明 'cindy' 卡槽 + `cindy.media: ["deposit"]`。
       */
      type: 'cindy-request';
      kind: 'deposit_media';
      /**
       * 媒体字节的 base64(不含 data: 前缀;解码后 ≤
       * GHOST_CINDY_DEPOSIT_MAX_BYTES = 50MB)。真实类型由主机按字节魔数
       * 判定,识别不出受支持媒体一律拒收——自报的 mime / 扩展名不作为依据。
       */
      data: string;
      /** 可选备注(入账 label;仅供主机侧账目与排查,不进聊天)。 */
      label?: string;
      /** 归因号(仅日志归因;寄存不计入产物账,见上)。 */
      callId?: string;
    }
  | {
      /**
       * 撤回寄存:删掉本意识对该指纹的寄存引用(配额随之释放)。面板上那件
       * 素材被用户删掉时调用,是 deposit 配额的正常释放口。
       *
       * 只删**本意识自己的寄存引用**:别人的引用、画廊引用、聊天消息引用都
       * 不受影响;字节本身交回收器按"引用归零"统一处理,本请求删不掉字节。
       * 与 deposit 共用 `cindy.media: ["deposit"]` 授权。
       */
      type: 'cindy-request';
      kind: 'release_media';
      /** 要撤回的寄存指纹(sha256)。 */
      hash: string;
    }
  | {
      /**
       * 快问快答(2026-07-31 开闸):把 prompt 交给主机的轻量任务模型链
       * 直答一次,答案文字随本次 invoke 的返回值递回。不拉起 agent、无
       * 工具、无用户权限、不进任何会话。须声明 'cindy' 卡槽 +
       * `cindy.text: ["oneshot"]`。
       *
       * 选型不在意识手里:走主机的轻量任务模型链(用户在设置里配置的
       * 快速通道,与会话起标题同一条),链上无可用候选时收到
       * errorCode:'NO_CANDIDATE' 的结构化失败——意识必须把它当正常失败面
       * 处理(典型场景:用户只登了订阅、没配可用的快速通道凭证)。
       */
      type: 'cindy-request';
      kind: 'oneshot_text';
      /** 要问的内容(1–32768 字符)。 */
      prompt: string;
      /**
       * 期望模型只输出 JSON:主机在提示里注明并校验返回可解析,解析失败
       * 按 errorCode:'BAD_MODEL_OUTPUT' 收单(text 里带原始输出,便于排查)。
       * 具体字段结构写进 prompt 里描述;主机不做 schema 逐字段校验。
       */
      expectJson?: boolean;
      /** 回答长度预算(token;1–4096,缺省 1024)。 */
      maxTokens?: number;
      /** 归因号(同 gen_image 分支)。 */
      callId?: string;
    }
  | {
      /**
       * 文本转向量(2026-08-04 开闸):把一批文字交给主机的统一 embedding
       * 通道,返回等长的向量数组。须声明 'cindy' 卡槽 +
       * `cindy.embed: ["text"]`。
       *
       * **只生成、不存储**:主机不代管向量,返回值即全部交付物——存哪儿、
       * 怎么建索引、什么时候重算,全在意识自己手里(面板 kv / 自带文件)。
       * 主机的向量表是宿主语义检索的家当,不对意识开放。
       *
       * 选型同媒体代办的双轨(tier / model),但**换模型 = 换向量空间**:
       * 不同模型(乃至同模型不同维度)的向量不可比,混着存进同一个索引会让
       * 相似度失去意义。所以拿到 `model` 与 `dim` 后请一并存下,下次检索前
       * 比对——不一致就得重嵌,而不是接着用。
       */
      type: 'cindy-request';
      kind: 'embed_text';
      /**
       * 待嵌文本(1–32 条,单条 1–8192 字符,合计 ≤65536 字符)。
       * 超长文本请自己按语义切块再递进来:上游会静默截断,那样拿到的向量
       * 代表的是被截掉后半段的文本,坑不可见。
       */
      texts?: string[];
      /**
       * 上下文化嵌入(可选,与 texts 二选一):按文档分组的 chunk 序列,
       * 每个内层数组 = 一个文档的若干 chunk。**同一文档内的 chunk 互为上下文**,
       * 因此同一段文字放进不同文档会得到不同向量 —— 这正是它比逐块独立嵌入好的
       * 地方(适合长文档检索),也意味着它必须整篇一起嵌,不能拆开分次。
       *
       * 只有支持上下文化的型号能用(voyage-context-*);其它型号传了会被明拒。
       * 返回值是 `documentEmbeddings`(三层:文档 → chunk → 维度),不是
       * `embeddings`。
       *
       * 分组上限与 texts 同一套预算:chunk 总数 ≤ 32、单 chunk ≤ 8192 字符、
       * 合计 ≤65536 字符。
       */
      documents?: string[][];
      /**
       * 检索用途(可选):'document' = 要入库被检索的内容,'query' = 用来检索的
       * 提问。主机按所选模型的家族翻成对应的上游参数(各家值域互不兼容,主机
       * 负责翻译,意识只表达意图)。不传 = 不加任何检索偏置。
       *
       * **建索引与查索引必须用同一套约定**:两侧都不传,或者存的时候
       * 'document'、查的时候 'query'。一侧传一侧不传不会报错,只是召回悄悄变差。
       *
       * 有的模型家族根本没有这个概念(OpenAI 系),此时主机静默不发 —— 传了不报
       * 错也不生效,所以别把它当"一定生效"的开关。
       */
      inputType?: GhostCindyEmbedInputType;
      /**
       * 期望维度(可选)。不传 = 该模型的默认维度(回执 `dim` 为准)。
       * 降维能显著压缩存储与回传体积(3072 → 1024 少 2/3),代价是检索精度略降。
       * 该模型不支持所要维度时按结构化失败收单('INVALID_PARAMS'),不会静默给
       * 另一个长度。
       */
      dimensions?: number;
      tier?: GhostModelTier;
      model?: string;
      /** 归因号(同 gen_image 分支)。 */
      callId?: string;
    };

/**
 * embed_text 的检索用途档(中立值;主机按模型家族翻成上游 wire 值)。
 *
 * 2026-08-04 经 XD 网关实测的家族差异(主机据此翻译,意识无需关心):
 *   - Voyage 系认小写 query / document;
 *   - Gemini 系走 Vertex 的大写枚举 RETRIEVAL_QUERY / RETRIEVAL_DOCUMENT;
 *   - OpenAI 系没有这个参数,主机不发。
 */
export const GHOST_CINDY_EMBED_INPUT_TYPES = ['document', 'query'] as const;
export type GhostCindyEmbedInputType = (typeof GHOST_CINDY_EMBED_INPUT_TYPES)[number];

/**
 * 视频代办实际生效的画面参数回执(仅视频类代办)。取值优先用上游任务
 * 上报的真实值,上游没报的那项回落主机提交值;各字段仍可能缺省(上游
 * 没报且主机也没显式指定时)。类型是宽松的 string/number 而非请求侧的
 * 枚举——回执是**上游说的**,不能假设它落在主机的值域里。
 *
 * 用途:老宿主会静默忽略请求里的新画面参数,意识拿这份回执才分得清
 * "宿主不支持,给了默认档"与"宿主兑现了我要的档"。
 */
export interface GhostVideoResultParams {
  durationSeconds?: number;
  resolution?: string;
  ratio?: string;
  fps?: number;
  /**
   * 本单是否带音轨。缺省 = 主机说不上来(该型号没有音轨能力,或老宿主根本
   * 不认识这个字段),**不等于"无声"**——想确认有没有兑现就看这个字段在不在,
   * 别把缺省读成 false。当前上游任务不回报音频状态,所以这里的值来自主机
   * 提交值 / 该型号的已知默认,不是上游上报的实测结果。
   */
  audio?: boolean;
}

/**
 * embed_text 两种成功形态共有的交付元数据。
 *
 * `model` 与 `dim` 是**必须一并存下**的:换了模型或维度,旧向量与新向量不在同一
 * 空间,相似度不可比,存量必须重嵌 —— 这是它跟出图最不一样的地方(出图换型号只是
 * 风格变了,向量换型号会让整个索引静默失效)。
 */
interface GhostCindyEmbedResultMeta {
  /**
   * 实际执行的模型 id,**主机白名单里的那个别名** —— 也就是可以原样回传给
   * `embed_text` 的那个值。
   *
   * 不回上游解析出的带版本号型号(PR #1707 review):手册要求调方把这个值存下、
   * 检索时原样传回,而 `model` 参数要过主机白名单;回一个不在白名单里的上游 id
   * 会让"入库成功 → 按回执检索"这条主路径确定性地撞 INVALID_PARAMS。
   */
  model: string;
  /**
   * 上游实际使用的型号 id(带版本号 / 服务端解析后的实现),**仅当它与 `model`
   * 不同时出现**。审计与"要不要重算存量"用,不要回传给 `embed_text`。
   *
   * 有什么用:同一别名的后端实现被换掉时(维度可能都没变),向量空间未必仍然可比,
   * 而只看别名是察觉不到的。
   */
  upstreamModel?: string;
  /** 实际返回的向量维度。 */
  dim: number;
  /** 模型展示名(目录 label;给用户看的场合用这个,不用裸 id)。 */
  modelLabel: string;
}

/** cindy 槽代办的返回(cindy.send 的 resolve 值)。 */
export type GhostPipeModelResult =
  | {
      ok: true;
      /** 生成媒体的取件地址(cindy-media://…,聊天与面板皆可渲染)。 */
      url: string;
      /** 内容指纹(面板经 cindy-ghost://<id>/media/<指纹> 取件用)。 */
      hash: string;
      /** 落盘扩展名(含点)。 */
      ext: string;
      /** 实际执行的模型 id(主机解析后的最终选型,主机说了算)。 */
      model: string;
      /** 模型展示名(目录 label;意识交卷 note 里给用户看)。 */
      modelLabel: string;
      /**
       * 图片像素宽/高(仅图片代办,best-effort:主机解析字节头得来,
       * 解析不出则缺省)。意识供聊天卡片时据此按宽高比精确声明卡高,
       * 首帧即最终高度,不再经历"估计值 → 实测值"的可见收敛。
       */
      width?: number;
      height?: number;
      /** 视频代办实际生效的画面参数(仅视频类代办;图像类不带此字段)。 */
      videoParams?: GhostVideoResultParams;
    }
  | {
      ok: true;
      /** 异步受理(mode:'submit')与 query_job 进行中共用本分支。 */
      jobId: string;
      status: 'running';
      /** 该型号预期耗时(秒;registry 登记值,供意识决定轮询节奏)。 */
      expectedSeconds?: number;
      /** 已耗时(秒;仅 query_job 返回)。 */
      elapsedSeconds?: number;
    }
  | {
      /**
       * query_job 完成态(独立成员,jobId/status 必填):`'status' in r`
       * 即可与同步成功分支可靠判别。取件字段与同步成功分支同形。
       */
      ok: true;
      jobId: string;
      status: 'done';
      url: string;
      hash: string;
      ext: string;
      model: string;
      modelLabel: string;
      /** 与同步成功分支同形(异步代办只有视频,这里通常必带)。 */
      videoParams?: GhostVideoResultParams;
    }
  | {
      /**
       * deposit_media 成功(独立成员:有 `bytes`、无 `model`/`status`,
       * 可与生成分支可靠判别)。指纹拿到手即可直接当 edit_image /
       * edit_video 的源图,也可经 cindy-ghost://<id>/media/<指纹><后缀>
       * 在面板里取件。
       */
      ok: true;
      url: string;
      hash: string;
      ext: string;
      /** 落仓字节数(去重命中时为既有内容的字节数)。 */
      bytes: number;
      /** 该字节此前已在总仓(全局内容去重命中)。 */
      deduplicated: boolean;
      /** 寄存配额:本意识已用 / 上限(字节)。作者据此提前提示用户。 */
      quotaUsedBytes: number;
      quotaLimitBytes: number;
    }
  | {
      /** release_media 成功。released=false 表示本就没有这条寄存引用(幂等)。 */
      ok: true;
      released: boolean;
      quotaUsedBytes: number;
      quotaLimitBytes: number;
    }
  | {
      /**
       * oneshot_text 成功(独立成员:有 `text`、无 `url`/`status`,可与
       * 其它成功分支可靠判别)。
       */
      ok: true;
      text: string;
      /** 实际应答的供应商/模型标识(轻量链解析结果;仅诊断展示用)。 */
      model?: string;
    }
  /**
   * embed_text 成功 —— 两种形态**互斥**,写成两个分支而不是一个"两个字段都可选"
   * 的分支(PR #1707 review):后者在类型层允许"两个都缺"和"两个都有"这两种非法
   * 响应,加新路径时 TS 不会拦。拆开之后每个分支各有一个**必填**的独占成员,既锁死
   * 二选一,也让它们与其它 ok:true 分支的判别更牢靠。wire 形态与拆分前完全一致。
   */
  | ({
      /** 逐条独立嵌(请求传 texts)。 */
      ok: true;
      /** 与请求 texts 等长、顺序一一对应。 */
      embeddings: number[][];
      documentEmbeddings?: never;
    } & GhostCindyEmbedResultMeta)
  | ({
      /** 上下文化嵌入(请求传 documents)。 */
      ok: true;
      embeddings?: never;
      /** 与请求 documents 同形:文档 → chunk → 维度。 */
      documentEmbeddings: number[][][];
    } & GhostCindyEmbedResultMeta)
  | {
      /** search_web 成功;逻辑 Provider 恒为 cindy,不暴露内部模型路由。 */
      ok: true;
      provider: 'cindy';
      results: Array<{
        title: string;
        url: string;
        snippet: string;
      }>;
    }
  | {
      ok: false;
      message: string;
      /**
       * 结构化错误码(2026-07-31 起 oneshot_text 填写,2026-08-04 起
       * embed_text 同样填写;媒体代办暂只有 message)。稳定值:
       * 'NO_CANDIDATE'(快速通道无可用模型/凭证;embed_text 复用它表示
       * 目录里没有可用的向量型号)、
       * 'BAD_MODEL_OUTPUT'(expectJson 下输出不可解析)、'RATE_LIMITED'、
       * 'TIMEOUT'、'PERMISSION_DENIED'、'INVALID_PARAMS'、'INTERNAL';
       * search_web 在这些通用值之外另使用 'NOT_CONFIGURED'、'QUOTA_EXHAUSTED'、
       * 'AUTH_REJECTED'、'UPSTREAM_UNAVAILABLE'、'RESPONSE_INVALID'。
       */
      errorCode?: string;
    };

/* ── 订阅槽①:事件协议(2026-07-12 定案:一种事件模型,两个类型)──────
 * did- 旁听:fire-and-forget,主机投完即走,意识崩/慢不影响任何会话;
 * will- 拦截:主机停等裁决(硬超时 fail-open + 连续失败熔断降级只旁听)。
 * 事件名前缀即类型;未来开新拦截点 = 加 will- 事件 + 同一裁决协议。 */

/** 熄灯期事件缓冲队列上限(每意识;溢出丢最旧并在下一条累计 dropped)。 */
export const GHOST_SUB_QUEUE_MAX = 100;
/** will- 钩子裁决硬超时(毫秒;超时 = 放行 fail-open,聊天绝不被坏意识卡死)。
 *  仅用于 will-user-message(入口):它挡在发送前,必须快,不能让用户等。 */
export const GHOST_HOOK_TIMEOUT_MS = 3000;
/** will-assistant-message(出口)裁决超时(毫秒,5 分钟)。它是"先定案 → 后台
 *  处理完再原地替换"的后置钩子,不阻塞发送/发下一条,故容许长处理(意识可能
 *  跑外部合规接口 / 自己的 LLM 润色 / 出图);超时同样 fail-open 用原文定案。 */
export const GHOST_ASSISTANT_HOOK_TIMEOUT_MS = 5 * 60_000;
/** 钩子连续失败(超时/崩溃)熔断阈值:达到即降级为只旁听并通知用户。 */
export const GHOST_HOOK_FUSE_THRESHOLD = 3;
/** 钩子改写(rewrite)正文长度上限(字符,超长截断):防意识塞巨量正文
 *  撑爆消息;提示词优化产物通常远小于此。 */
export const GHOST_HOOK_REWRITE_MAX_CHARS = 16_000;

/** activity topic 的旁听事件名。 */
export type GhostActivityEventName =
  | 'did-thinking-start'
  | 'did-thinking-end'
  | 'did-approval-start'
  | 'did-approval-end'
  | 'did-user-input-start'
  | 'did-user-input-end';

/** did- 旁听事件名(topic 归属:turn / session / activity)。 */
export type GhostDidEventName =
  | 'did-turn-start'
  | 'did-turn-end'
  | 'did-session-created'
  | 'did-session-archived'
  | 'did-session-switched'
  | GhostActivityEventName;

/** did-turn-start 载荷(全元数据,无消息内容)。 */
export interface GhostEventTurnStartData {
  sessionId: string;
  /** agent 种类(claude / codex;以主机实际派发为准)。 */
  agent: string;
  model?: string;
}

/** did-turn-end 载荷。usage 各字段**可选**:cc/codex 上报丰富度不同
 *  (cache 指标 claude 更全),意识作者不要假设字段必在。 */
export interface GhostEventTurnEndData extends GhostEventTurnStartData {
  durationMs: number;
  endReason: 'completed' | 'interrupted' | 'error';
  usage?: {
    inputTokens?: number;
    outputTokens?: number;
    cacheReadTokens?: number;
    cacheCreationTokens?: number;
  };
}

/** did-session-* 载荷。 */
export interface GhostEventSessionData {
  sessionId: string;
  workdir?: string;
}

/**
 * thinking 活动边界;只暴露 blockId,不暴露 reasoning 正文。
 *
 * `blockId` 是**主机生成的不透明配对键**(见 `ghostActivityId`),不是 provider 侧原值:
 * 只保证同一段 thinking 的 start / end 拿到同一个值、不同会话不同值,不承载任何语义,
 * 也不能用来关联主机或 provider 的任何其他标识。
 */
export interface GhostEventThinkingData {
  sessionId: string;
  blockId: string;
}

/**
 * 审批/用户输入活动边界;只暴露 requestId,不暴露请求或回答内容。
 *
 * `requestId` 同样是**主机生成的不透明配对键**(见 `ghostActivityId`),不是 provider 侧
 * 原值——provider 的 id 不保证语义中立(codex 的 MCP elicitation 会把服务名拼进去),
 * 原样转发会越过"只知道时机"的隐私边界。只保证 start / end 配对。
 */
export interface GhostEventInteractionActivityData {
  sessionId: string;
  requestId: string;
}

export type GhostEventActivityData = GhostEventThinkingData | GhostEventInteractionActivityData;

/** 所有 did- 旁听事件共享的安全元数据载荷。 */
export type GhostDidEventData =
  GhostEventTurnStartData | GhostEventTurnEndData | GhostEventSessionData | GhostEventActivityData;

export type GhostMessageHookData = { sessionId: string; text: string; model?: string };

/**
 * 下行:主机 → 意识的事件推送(经管子 onHostMessage 到达)。
 * did- 分支带 topic/seq(每意识单调递增,可自查漏收;dropped = 上一段
 * 熄灯期溢出丢弃数);will- 分支带 hookId,意识须在超时窗内回
 * GhostPipeEventVerdict,不回视为放行。
 */
export type GhostPipeEventPush =
  | GhostPipeDownloadProgress
  | GhostPipeBrowserExtensionRelay
  | {
      type: 'event';
      name: GhostDidEventName;
      topic: GhostSubscribeTopic;
      seq: number;
      ts: number;
      dropped?: number;
      data: GhostDidEventData;
    }
  | {
      type: 'event';
      name: 'will-user-message';
      hookId: string;
      ts: number;
      data: GhostMessageHookData;
    }
  | {
      type: 'event';
      name: 'will-assistant-message';
      hookId: string;
      ts: number;
      /** text = 本轮 AI 回复全文;意识可放行/改写/自绘(见 GhostPipeEventVerdict)。 */
      data: GhostMessageHookData;
    }
  | {
      /** 随包 Node 进程发来的 JSON-RPC notification / MCP 进度事件。 */
      type: 'event';
      name: 'node-notification';
      method: string;
      params?: unknown;
      ts: number;
    }
  | {
      /** Node 工作进程生命周期变化;供 main.js 更新自己的卡片/面板状态。 */
      type: 'event';
      name: 'node-status';
      state: 'starting' | 'running' | 'stopped' | 'crashed';
      message?: string;
      /** 哪个入口的进程(多进程窄版;缺省 = 主入口 node.entry)。 */
      entry?: string;
      ts: number;
    }
  | {
      /**
       * 交互卡按钮点击(v2,card 槽):真实用户点了自绘卡上的 data-ghost-action
       * 元素,宿主把点击回传给意识电子脑。fire-and-forget(无 hookId/裁决)——
       * 意识自己干活(如调工具 + card-update 换新卡)。callId = 被点那张卡的
       * 归因号(主机已验该卡归属本意识);actionId = data-ghost-action 的值
       * (过 GHOST_CARD_ACTION_ID_RE)。
       */
      type: 'event';
      name: 'card-action';
      /** Opaque origin for host confirmation routing. Forward it to cindy.confirm. */
      mobilePageId?: string;
      callId: string;
      actionId: string;
      /** 被点卡片所属会话;老卡可能没有归属,缺省时不能唤起 Agent。 */
      sessionId?: string;
      /**
       * 宿主为这次真实点击签发的一次性通行票。仅声明了 agent 槽且卡片有
       * 会话归属时提供;短时有效、消费一次即作废、绑定当前插件与会话。
       */
      userActionToken?: string;
      /**
       * 用户输入的文字(仅当按钮声明了 data-ghost-prompt:宿主点击时弹输入框
       * 收集,非空才带;≤ GHOST_CARD_ACTION_PROMPT_MAX_LEN)。无声明的普通
       * 按钮永远没有此字段。
       */
      prompt?: string;
      /** Text fields collected by the Host from a declarative card form. Never credentials. */
      formValues?: Record<string, string>;
      /** Host-selected single file. Never supplied by plugin HTML or form text. */
      mailAttachment?: { path: string; filename: string; bytes: number; sha256: string; contentId?: string };
      /** Passive editor update: no user-action token, no Agent continuation. */
      formChange?: boolean;
      /**
       * 主机铸造的衍生卡位(`<根callId>::sp<序>`,见 GHOST_CARD_SPAWN_SEP)。
       * 对它 card-update = 原卡下方长出新卡(原卡保留,母卡按钮可反复点);
       * 对原 callId card-update = 原地换卡。推荐新结果一律画到 spawnCallId。
       */
      spawnCallId: string;
      ts: number;
    };

/**
 * 上行:意识 → 主机的钩子裁决(cindy.send)。"停下来交给你做,做完继续"的
 * 几种收尾(哪些动作合法按钩子分:will-user-message 用 allow/block/rewrite,
 * will-assistant-message 用 allow/rewrite/render——主机侧各自校验,不合法的
 * 动作按 allow 兜底):
 * - 'allow':原样放行(意识可在窗口内做纯副作用:记账/日志,不改消息);
 * - 'rewrite':放行**改写后的正文**——`text`(≤GHOST_HOOK_REWRITE_MAX_CHARS,
 *   超长截断)替换即将落库/显示的消息正文;**静默替换**(气泡直接显示改写版,
 *   无标记无弹窗),提示词优化/合规改写走这条——插件详情已如实披露「可改写」;
 * - 'block'(仅 will-user-message):打回不继续,`reason`(≤200 字符)显示在被拦
 *   气泡的主机脚标上;
 * - 'render'(仅 will-assistant-message):自绘结果卡片替换 AI 气泡——`html`
 *   (主机净化 + 高度 clamp,规则同 card 槽海报)、`height` 初始高度估计。原文
 *   仍落库并保留"查看原文"入口(信任边界:意识盖不住 AI 实际输出)。
 * 无论哪种,窗口里意识想 await 外部接口(经 network 槽)、改写、记日志都行,
 * 主机只等它把裁决返回。整块承载 UI(脚标/身份头/查看原文)主机绘制,意识
 * 只供 text/reason/html。
 */
export interface GhostPipeEventVerdict {
  type: 'event-verdict';
  hookId: string;
  action: 'allow' | 'block' | 'rewrite' | 'render';
  /** block 时展示的理由。 */
  reason?: string;
  /** rewrite 时的新正文(替换消息正文;其它 action 忽略)。 */
  text?: string;
  /** render 时的自绘卡片 HTML(主机净化;其它 action 忽略)。 */
  html?: string;
  /** render 时的卡片初始高度估计(主机 clamp;缺省用 card 槽默认)。 */
  height?: number;
}

/* ── 主机代理 fetch 协议(2026-07-12)────────────────────────────────
 * 意识 cindy.send({type:'fetch-request',…}) → 主机调用上下文/白名单校验 +
 * 按声明注入凭证 + 真实 HTTP → invoke resolve 值即 GhostPipeFetchResult。
 * Agent 在途调用凭严格 callId 复用 Agent 授权;自主调用仍按 network
 * 详单守门。硬边界都在主机侧代码强制,常量在此与手册/校验共用一份。 */

/** 代理 fetch 允许的方法(REST 查询/提交/删除;body 仍仅 POST 允许)。 */
// PUT / PATCH 于 2026-07-13 随 oauth 凭证形态一并放行(Google Calendar 更新、
// Sheets 写入、Jira / Confluence 更新全是 PUT/PATCH;风险面与 POST 同档)。
export const GHOST_FETCH_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'] as const;
export type GhostFetchMethod = (typeof GHOST_FETCH_METHODS)[number];

/** 请求体上限(UTF-8 字节)。 */
export const GHOST_FETCH_BODY_MAX_BYTES = 256 * 1024;
/** 响应体上限(超限截断并标 truncated;2026-07-21 由 1MB 放宽到 50MB,Jira 等大 JSON 不再被截)。 */
export const GHOST_FETCH_RESPONSE_MAX_BYTES = 50 * 1024 * 1024;
/** 超时缺省/下限/上限(毫秒;越界 clamp 不拒单)。 */
export const GHOST_FETCH_TIMEOUT_DEFAULT_MS = 30_000;
export const GHOST_FETCH_TIMEOUT_MIN_MS = 1_000;
export const GHOST_FETCH_TIMEOUT_MAX_MS = 60_000;
/** 每意识在途代发请求硬顶(常量,不做配置项——防死循环刷单,非配额)。 */
export const GHOST_FETCH_INFLIGHT_LIMIT = 4;

/* ── 媒体模式(as:'media',mivo 迁移地基):字节不进沙箱 ──────────────
 * 意识声明"这个响应是媒体":主机把 2xx 的受支持媒体字节直接落 cindy-media
 * 总仓、记到该意识名下(ghost-gallery 引用,与 cindy 槽产物同等待遇),
 * resolve 只回取件地址——沙箱全程摸不到媒体字节,比"递进去再交回来"更省
 * 也更安全。非 2xx / 文本类响应自动回落文本形态(错误 JSON 意识看得到)。 */

/** 媒体响应字节硬顶(超限整单拒,不截断——截断的媒体是坏文件)。 */
export const GHOST_FETCH_MEDIA_MAX_BYTES = 256 * 1024 * 1024;
/** 媒体模式的超时缺省/上限(毫秒;下限与文本模式共用 GHOST_FETCH_TIMEOUT_MIN_MS)。 */
export const GHOST_FETCH_MEDIA_TIMEOUT_DEFAULT_MS = 120_000;
export const GHOST_FETCH_MEDIA_TIMEOUT_MAX_MS = 300_000;
/** 媒体入账备注(画廊 caption)长度上限。 */
export const GHOST_FETCH_LABEL_MAX_CHARS = 200;

/* ── 上传通道(upload,媒体模式的镜像):字节不进沙箱 ──────────────────
 * 意识把"自己名下"的总仓媒体上传给白名单服务(mivo 改图/图生视频的源图):
 * 请求里只报指纹,主机查账验归属(出生自它 / 挂它画廊 / 用户显式过户)、
 * 读 blob、代组 multipart/form-data 出网——沙箱全程摸不到媒体字节。 */

/** 上传:单次最多文件数。 */
export const GHOST_FETCH_UPLOAD_MAX_FILES = 4;
/** 上传:单文件字节上限(3D 模型可到几十 MB,给足;超限整单拒)。 */
export const GHOST_FETCH_UPLOAD_MAX_BYTES_PER_FILE = 64 * 1024 * 1024;
/** 上传:单次总字节上限(multipart 体整体驻内存组装,必须封顶)。 */
export const GHOST_FETCH_UPLOAD_MAX_TOTAL_BYTES = 128 * 1024 * 1024;
/** 上传:multipart 字段名形状(缺省 'file')。 */
export const GHOST_FETCH_UPLOAD_FIELD_RE = /^[A-Za-z0-9_-]{1,64}$/;
/** 总仓指纹形状(64 位十六进制,与 blobStore 同口径)。 */
export const GHOST_MEDIA_HASH_RE = /^[a-f0-9]{64}$/;

/* ── 目录上传(uploadDir,xd-service 意识化二期):字节与路径都不进沙箱 ──
 * 意识把"用户 / 主 agent 显式过户"的本地目录整体上传给白名单服务(静态
 * 站点部署等):主 agent 在 ghost_call 顶层传 dir(绝对路径,主机钳制在
 * 会话 workdir 内)→ 主机收集文件、发一次性票据(token)注入 args.dir_deposit
 * → 意识 fetch-request 只报 token,主机凭票读盘、代组 multipart 出网。
 * 意识永远拿不到绝对路径与文件字节,也无法自造票据指向任意目录。 */

/** 目录上传:单目录最多文件数(静态站点构建产物量级)。 */
export const GHOST_FETCH_DIR_UPLOAD_MAX_FILES = 500;
/** 目录上传:单文件字节上限。 */
export const GHOST_FETCH_DIR_UPLOAD_MAX_BYTES_PER_FILE = 50 * 1024 * 1024;
/** 目录上传:单次总字节上限(multipart 体整体驻内存组装,必须封顶)。 */
export const GHOST_FETCH_DIR_UPLOAD_MAX_TOTAL_BYTES = 500 * 1024 * 1024;
/** 目录上传:随行普通表单字段条数上限。 */
export const GHOST_FETCH_DIR_UPLOAD_MAX_FIELDS = 8;
/** 目录上传:普通表单字段值长度上限(字符)。
 * 要容纳与 MAX_FILES(500)同量级的部署清单类字段(站点部署插件的
 * metadata 按每文件路径+摘要 ~250 字符计,500 文件 ≈ 125K):2048 时
 * ~100 文件即溢出,大目录部署被本校验拦死。内存上界仍受
 * MAX_FIELDS(8)封顶(~1MB),远小于 multipart 总量上限。 */
export const GHOST_FETCH_DIR_UPLOAD_FIELD_VALUE_MAX_CHARS = 131072;
/** 目录过户票据形状(主机 randomUUID 发放)。 */
export const GHOST_DIR_DEPOSIT_TOKEN_RE = /^[a-f0-9-]{36}$/;
/** 目录过户票据有效期(毫秒;过期未消费自动作废)。 */
export const GHOST_DIR_DEPOSIT_TTL_MS = 10 * 60_000;

/**
 * 下行落盘(save 票据,2026-07-13,google/conf/jira 意识化「附件下载不降级」):
 * 主 agent 经 ghost_call 顶层 save_dir 过户一个 workdir 内的可写目录 →
 * 主机发限时票据注入 args.save_deposit → 意识 fetch({as:'file', saveTo})
 * 时主机把响应字节直接写进该目录——字节与绝对路径都不进沙箱,意识只拿到
 * 落盘后的文件名。与 dirDeposit(上行读)同一"显式交付"哲学的镜像。
 */
/** 下行票据有效期(毫秒)。 */
export const GHOST_SAVE_DEPOSIT_TTL_MS = 10 * 60_000;
/** 单张下行票据最多写入的文件数(一次 ghost_call 内多附件下载够用)。 */
export const GHOST_SAVE_DEPOSIT_MAX_USES = 16;
/** 单张下行票据的累计写入字节上限。 */
export const GHOST_SAVE_DEPOSIT_MAX_TOTAL_BYTES = 512 * 1024 * 1024;
/** 单文件下行体积上限(与媒体取件同档;超限整单拒不截断——截断文件是坏文件)。 */
export const GHOST_FETCH_FILE_MAX_BYTES = 256 * 1024 * 1024;
/** 意识建议文件名的长度上限(超限拒;消毒后仍以主机为准)。 */
export const GHOST_FETCH_FILE_NAME_MAX_CHARS = 128;

/* ── 主机文件操作(2026-07-14):字节由主机代办,沙箱仍零 fs ──────────
 * 意识 cindy.send({type:'fs-request', op, root, …}) → 按执行上下文与 root
 * 分档守门 → 主机代写/代读 → 结构化 GhostPipeFsResult。
 * 三个 root:
 * - 'data'    插件自主私有数据目录(userData/ghost-fs/<ghostId>);要求 fs:true,
 *             全 op,免确认,配额封顶,卸载随包回收。
 * - 'workdir' 当前会话工作目录;仅 write,须带 callId(反查 session),当前
 *             Agent 调用无需 fs:true,并跟随会话 permission 模式;远程工作区拒。
 * - 'save'    主 agent 过户的 save 票据目录;仅 write,复用 saveDeposit
 *             的 TTL/次数/字节预算与文件名消毒;票据自身就是授权,无需 fs:true。
 */
export const GHOST_FS_ROOTS = ['data', 'workdir', 'save'] as const;
export type GhostFsRoot = (typeof GHOST_FS_ROOTS)[number];
export const GHOST_FS_OPS = ['write', 'read', 'list', 'delete'] as const;
export type GhostFsOp = (typeof GHOST_FS_OPS)[number];

/** fs 相对路径总长上限(字符;分段规则同 isSafeGhostRelativePath)。 */
export const GHOST_FS_PATH_MAX_CHARS = 256;
/** 单次写入内容上限(解码后字节;超限整单拒——大数据请分文件)。 */
export const GHOST_FS_WRITE_MAX_BYTES = 16 * 1024 * 1024;
/** 单次读取上限(解码前字节;超限拒,提示分文件存)。 */
export const GHOST_FS_READ_MAX_BYTES = 16 * 1024 * 1024;
/** 私有数据目录:累计字节配额(超限写拒,提示自行删旧文件)。 */
export const GHOST_FS_DATA_MAX_TOTAL_BYTES = 256 * 1024 * 1024;
/** 私有数据目录:文件数配额。 */
export const GHOST_FS_DATA_MAX_FILES = 2000;
/** list 返回条数上限(超出截断并标 truncated)。 */
export const GHOST_FS_LIST_MAX_ENTRIES = 2000;

/** 上行:主机文件操作请求。 */
export interface GhostPipeFsRequest {
  type: 'fs-request';
  /** 操作:write=创建/覆盖,read/list/delete 仅 root:'data'。 */
  op: GhostFsOp;
  /** 目的地档位(见上方注释)。 */
  root: GhostFsRoot;
  /**
   * 相对路径(`a/b/c.ext` 形态,规则同 isSafeGhostRelativePath:正斜杠分段、
   * 无 `.`/`..`、段首不许点——写不了 .git 等隐藏目录是刻意的)。write/read/
   * delete 必填;list 可选(缺省列根)。root:'save' 时仅取 basename 语义
   * (票据目录不展开子目录),并经主机消毒去重。
   */
  path?: string;
  /** 写入内容(write 必填;encoding:'base64' 时为 base64 文本,否则 UTF-8)。 */
  content?: string;
  /** 内容编码(write 的入参编码 / read 的期望返回编码);缺省 'utf8'。 */
  encoding?: 'utf8' | 'base64';
  /** save 票据(root:'save' 必填;来自 ghost_call 顶层 save_dir 过户)。 */
  token?: string;
  /** 归因号(root:'workdir' 必填:主机凭它反查严格在途 Agent 调用、session 与权限;其余可选)。 */
  callId?: string;
}

/** fs 槽 list 的单条目(路径相对本意识私有目录根)。 */
export interface GhostFsListEntry {
  path: string;
  bytes: number;
  /** 最后修改时间(unix ms)。 */
  mtime: number;
}

/** 代写文件的返回(cindy.send 的 resolve 值;失败带人话原因,永不 reject)。 */
export type GhostPipeFsResult =
  | {
      ok: true;
      op: 'write';
      /** 落盘后的相对路径(save 档为消毒去重后的文件名)。 */ path: string;
      bytes: number;
    }
  | {
      ok: true;
      op: 'read';
      path: string;
      content: string;
      encoding: 'utf8' | 'base64';
      bytes: number;
    }
  | { ok: true; op: 'list'; entries: GhostFsListEntry[]; truncated?: boolean }
  | { ok: true; op: 'delete'; path: string; /** false = 本来就不存在(幂等)。 */ existed: boolean }
  | { ok: false; message: string };

/* ── library 能力:持久作品库(2026-08-20;详见 docs/dev-rules/plugin-library-storage.md)── */

/**
 * library 能力操作集。文件操作与 fs:data 同为"主机代劳 + 相对路径",差异在:
 * 无 256MiB/2000 文件配额(受磁盘保留水位与软水位约束)、写入原子化
 * (staging+fsync+rename+identity 复验)、大文件走分块流、结构化错误码、
 * 卸载不删。SQLite 子集(op:'db.*')只收参数化单语句,事务/迁移/备份由
 * 宿主管理;首词白名单外的语句(ATTACH/PRAGMA/VACUUM/事务语句)一律拒。
 */
export const GHOST_LIBRARY_OPS = [
  'open',
  'status',
  'capabilities',
  'read',
  'write',
  'writeBegin',
  'writeChunk',
  'writeCommit',
  'writeAbort',
  'list',
  'stat',
  'mkdir',
  'delete',
  'rename',
  'db.open',
  'db.exec',
  'db.batch',
  'db.migrate',
  'db.backup',
  'db.check',
  'db.userVersion',
  'reveal',
  'saveAs',
  'clipboardWrite',
  'staging.begin',
  'staging.chunk',
  'staging.commit',
  'staging.list',
  'staging.read',
  'staging.release',
  'staging.abort',
] as const;
export type GhostLibraryOp = (typeof GHOST_LIBRARY_OPS)[number];

/** v1 能力清单只表达宿主实现支持,不等于此刻有窗口 / 已授权 / 库可用。 */
export const GHOST_LIBRARY_CAPABILITY_OPERATIONS = ['clipboardWrite', 'saveAs'] as const;
export type GhostLibraryCapabilityOperation = (typeof GHOST_LIBRARY_CAPABILITY_OPERATIONS)[number];

export const GHOST_LIBRARY_STAGING_OPERATIONS = [
  'staging.begin',
  'staging.chunk',
  'staging.commit',
  'staging.list',
  'staging.read',
  'staging.release',
  'staging.abort',
] as const;
export type GhostLibraryStagingOperation = (typeof GHOST_LIBRARY_STAGING_OPERATIONS)[number];

export const GHOST_LIBRARY_STAGING_LIMITS_V1 = {
  version: 1 as const,
  maxTaskBytes: 8 * 1024 * 1024 * 1024,
  maxTotalBytes: 8 * 1024 * 1024 * 1024,
  maxConcurrentWrites: 4,
  maxChunkBytes: 16 * 1024 * 1024,
  reserveBytes: 1024 * 1024 * 1024,
};

export const GHOST_LIBRARY_CAPABILITIES_V1 = {
  version: 1 as const,
  operations: [...GHOST_LIBRARY_CAPABILITY_OPERATIONS, ...GHOST_LIBRARY_STAGING_OPERATIONS] as const,
  staging: GHOST_LIBRARY_STAGING_LIMITS_V1,
};

/** 宿主实际操作的稳定失败类别;TIMEOUT / TRANSPORT_ERROR 由插件查询层本地分类,不从 message 猜测。 */
export const GHOST_LIBRARY_ERROR_REASONS = [
  'IMPLEMENTATION_UNSUPPORTED',
  'NO_VISIBLE_WINDOW',
  'PERMISSION_DENIED',
  'LIBRARY_UNAVAILABLE',
  'INVALID_REQUEST',
  'CANCELLED',
] as const;
export type GhostLibraryErrorReason = (typeof GHOST_LIBRARY_ERROR_REASONS)[number];

/**
 * 消费 capabilities 结果:仅 version=1 且 operations 为字符串数组才有效。
 * 额外字段忽略,未知 operation 忽略,已知项保留;有效 v1 缺某项才是 unsupported;
 * 缺字段 / 错类型 / version 非 1 / 旧宿主 unknown-op 一律 unknown。
 */
export function classifyGhostLibraryOperationSupport(
  result: unknown,
  operation: GhostLibraryCapabilityOperation,
): 'supported' | 'unsupported' | 'unknown' {
  if (!result || typeof result !== 'object' || Array.isArray(result)) return 'unknown';
  const row = result as Record<string, unknown>;
  if (row.ok !== true || row.op !== 'capabilities') return 'unknown';
  const caps = row.capabilities;
  if (!caps || typeof caps !== 'object' || Array.isArray(caps)) return 'unknown';
  const body = caps as Record<string, unknown>;
  if (body.version !== 1 || !Array.isArray(body.operations)) return 'unknown';
  if (!body.operations.every((item) => typeof item === 'string')) return 'unknown';
  const known = new Set<string>(GHOST_LIBRARY_CAPABILITY_OPERATIONS);
  const listed = new Set<string>();
  for (const item of body.operations) {
    if (known.has(item)) listed.add(item);
  }
  return listed.has(operation) ? 'supported' : 'unsupported';
}

/** Opaque encrypted RPC; plugin identity is always inferred from the sender. */
export type GhostPipeDeviceSyncRequest =
  | { type: 'device-sync-request'; op: 'status' }
  | { type: 'device-sync-request'; op: 'request'; peer: string; data: unknown }
  | { type: 'device-sync-request'; op: 'reply'; requestId: string; data: unknown };

/** 上行:library 请求(cindy.library(req) ≡ send({type:'library-request', …req}))。 */
export interface GhostPipeLibraryRequest {
  type: 'library-request';
  op: GhostLibraryOp;
  /** library 相对路径(段数/总长上限比 fs 宽:32 段/512 字符)。 */
  path?: string;
  /** write 内容(≤16MiB;更大走 writeBegin 分块流);clipboardWrite 只收 encoding:'base64' 的 PNG 字节。 */
  content?: string;
  encoding?: 'utf8' | 'base64';
  /** write:排他创建(目标已存在则 ALREADY_EXISTS)。 */
  ifNotExists?: boolean;
  /** 分块流:声明总字节数与期望 sha256(Commit 时核对)。 */
  totalBytes?: number;
  sha256?: string;
  streamId?: string;
  seq?: number;
  /** list:递归开关/续游标/页大小。 */
  recursive?: boolean;
  cursor?: string;
  limit?: number;
  /** delete:目录递归。 */
  recursiveDelete?: boolean;
  /** rename 源/目标(库内相对路径)。 */
  from?: string;
  to?: string;
  overwrite?: boolean;
  /** SQLite 子集:库内 .sqlite 相对路径 + 参数化 SQL。 */
  dbPath?: string;
  sql?: string;
  params?: unknown;
  statements?: Array<{ sql: string; params?: unknown }>;
  targetVersion?: number;
  steps?: Array<{ toVersion: number; sql: string[] }>;
  /** read 分段。 */
  offset?: number;
  length?: number;
  /** saveAs: 另存为建议文件名(仅 basename)。 */
  name?: string;
  /** staging: 插件任务身份 / 源版本 / MIME / 恢复元数据。 */
  taskId?: string;
  sourceRevision?: string;
  mime?: string;
  recovery?: Record<string, unknown>;
  stagingId?: string;
  /** staging.release: Library ACK 字节数(不是 begin 的 totalBytes)。 */
  bytes?: number;
  libraryIdentity?: string;
  libraryGeneration?: number;
}

/**
 * library 返回:成功形态按 op 分流(文件操作带宿主实算 sha256——未来
 * 网络同步的素材完整性地基);失败**结构化**(errorCode + 人话 message,
 * 修掉 fs 槽无错误码的缺口),对沙箱永不 reject。
 */
export type GhostPipeLibraryResult =
  | {
      ok: true;
      op: 'open' | 'status';
      state: 'ready' | 'readonly' | 'unavailable';
      reason?: string;
      usedBytes: number;
      fileCount: number;
      diskFreeBytes?: number | null;
      softLimitBytes?: number;
      softLimitExceeded?: boolean;
      location?: 'default' | 'custom';
      authorizedReadonly?: boolean;
      libraryGeneration?: number;
      libraryIdentity?: string;
    }
  | {
      ok: true;
      op: 'read';
      path: string;
      content: string;
      encoding: 'utf8' | 'base64';
      bytes: number;
      sha256: string;
    }
  | {
      ok: true;
      op: 'write' | 'writeCommit';
      path: string;
      bytes: number;
      sha256: string;
      libraryGeneration?: number;
      libraryIdentity?: string;
    }
  | { ok: true; op: 'writeBegin'; streamId: string }
  | { ok: true; op: 'writeChunk'; accepted: number }
  | { ok: true; op: 'writeAbort'; aborted: boolean }
  | {
      ok: true;
      op: 'list';
      entries: Array<{ path: string; kind: 'file' | 'dir'; bytes: number; mtime: number }>;
      hasMore: boolean;
      nextCursor: string | null;
    }
  | { ok: true; op: 'stat'; path: string; kind: 'file' | 'dir'; bytes: number; mtime: number }
  | { ok: true; op: 'mkdir'; path: string; existed: boolean }
  | { ok: true; op: 'delete'; path: string; existed: boolean }
  | { ok: true; op: 'rename'; from: string; to: string }
  | { ok: true; op: 'db.open'; opened: boolean }
  | {
      ok: true;
      op: 'db.exec';
      rows?: unknown[];
      changes?: number;
      lastInsertRowid?: string | number;
    }
  | { ok: true; op: 'db.batch'; applied: number }
  | { ok: true; op: 'db.migrate'; fromVersion: number; toVersion: number }
  | { ok: true; op: 'db.backup'; backedUp: boolean }
  | { ok: true; op: 'db.check'; healthy: boolean; detail: string }
  | { ok: true; op: 'db.userVersion'; version: number | null }
  | { ok: true; op: 'reveal'; path: string }
  | { ok: true; op: 'saveAs'; cancelled: true }
  /** saveAs 成功:path 是库内相对键(与请求相同),不是用户另存到的绝对路径。 */
  | { ok: true; op: 'saveAs'; cancelled: false; path: string; bytes: number }
  /** clipboardWrite 成功:bytes 是写入系统剪贴板的 PNG 位图字节数,不是文件引用。 */
  | { ok: true; op: 'clipboardWrite'; bytes: number }
  /** capabilities:无会话只读查询;operations 只表示实现支持。 */
  | {
      ok: true;
      op: 'capabilities';
      capabilities: {
        version: 1;
        operations: ReadonlyArray<GhostLibraryCapabilityOperation | GhostLibraryStagingOperation>;
        staging?: {
          version: 1;
          maxTaskBytes: number;
          maxTotalBytes: number;
          maxConcurrentWrites: number;
          maxChunkBytes: number;
          reserveBytes: number;
        };
      };
    }
  | { ok: true; op: 'staging.begin'; stagingId: string }
  | { ok: true; op: 'staging.chunk'; accepted: number }
  | {
      ok: true;
      op: 'staging.commit';
      stagingId: string;
      taskId: string;
      sourceRevision: string;
      sha256: string;
      bytes: number;
      mime: string;
      durable: true;
    }
  | {
      ok: true;
      op: 'staging.list';
      items: Array<{
        stagingId: string;
        taskId: string;
        sourceRevision: string;
        sha256: string;
        bytes: number;
        mime: string;
        durable: true;
        recovery: Record<string, unknown>;
      }>;
      hasMore: boolean;
      nextCursor: string | null;
    }
  | {
      ok: true;
      op: 'staging.read';
      stagingId: string;
      content: string;
      encoding: 'base64';
      bytes: number;
      sha256: string;
    }
  | { ok: true; op: 'staging.release'; stagingId: string; released: boolean }
  | { ok: true; op: 'staging.abort'; aborted: boolean }
  | { ok: false; errorCode: string; message: string; reason?: GhostLibraryErrorReason };

/** Library 概览(ghosts:library-overview IPC 载荷;设置页插件详情消费)。 */
export interface GhostLibraryOverview {
  /** 插件是否声明了 library 能力(未声明时设置页不渲染该区)。 */
  supported: boolean;
  state: 'ready' | 'readonly' | 'unavailable';
  reason: string | null;
  location: 'default' | 'custom';
  /** 自定义位置的用户所选父目录(用户自己选的,如实展示;默认位置为 null)。 */
  customCandidate: string | null;
  usedBytes: number;
  fileCount: number;
  diskFreeBytes: number | null;
  softLimitBytes: number;
  softLimitExceeded: boolean;
  /** 卸载后未删除的标记(重装自动清除;设置页以横幅提示)。 */
  orphaned: boolean;
  /**
   * 裸 id 下还留着这个插件以前的作品库,可以换回当前实例(设置页提供「接回」)。
   * 没有可接回的旧库时为 null。
   */
  legacyLibrary: {
    usedBytes: number;
    fileCount: number;
    /** uninstalled = 卸载时留下;unknown = 没有宿主身份记录,来源无法证明。 */
    provenance: 'uninstalled' | 'unknown';
  } | null;
  /** 裸 id 下的旧作品库还被本机另一个安装(例如本地版)使用着,卸载它后才能接回。 */
  legacyLibraryInUse: boolean;
}

/** 上行:主机代理 fetch 请求。 */
export interface GhostPipeFetchRequest {
  type: 'fetch-request';
  /**
   * 目标地址:仅 https、默认端口。自主调用的 host 必须命中 network.hosts;
   * 当前 Agent tool-call 可凭严格在途 callId 访问普通未声明 host。
   */
  url: string;
  /** 缺省 GET。 */
  method?: GhostFetchMethod;
  /**
   * 意识自带请求头(如 Content-Type / Accept)。协议关键头与凭证类头
   * 由主机剥除后再注入声明的凭证——意识写了也不生效,不算错误。
   */
  headers?: Record<string, string>;
  /** 请求体(文本;仅 POST / PUT / PATCH / DELETE;≤ GHOST_FETCH_BODY_MAX_BYTES;与 upload 互斥)。 */
  body?: string;
  /**
   * 上传通道(仅 POST;与 body 互斥):把本意识名下的总仓媒体以
   * multipart/form-data 上传给目标——只报指纹,主机验归属、读字节、代组
   * 请求体,Content-Type(boundary)由主机独占。hashes 1–4 条(64 位
   * 十六进制指纹);field 为每个文件的表单字段名,缺省 'file';fields 为
   * 随行普通表单字段(在文件段之前;值里的字面量 "{bytes}" 由主机替换成
   * 全部上传文件的总字节数——飞书 upload_all 这类要求 size 字段的服务用,
   * 2026-07-16 lizi_feishu 意识化前置)。
   */
  upload?: { hashes: string[]; field?: string; fields?: Record<string, string> };
  /**
   * 目录上传通道(仅 POST;与 body / upload 互斥):把主机过户票据指向的
   * 本地目录整体以 multipart/form-data 上传——token 来自 ghost_call 顶层
   * dir 参数过户后注入的 args.dir_deposit.token(一次性、限本意识、限时);
   * fields 为随行普通表单字段(如 name / preset;值里的字面量 "{bytes}"
   * 由主机替换成全部上传文件的总字节数);fileFieldPrefix 为文件字段名前缀
   * (缺省 'file-',第 N 个文件字段名 `file-N`,filename=相对路径);
   * fileField 为单文件精确字段名(与 fileFieldPrefix 互斥,票据必须恰含
   * 1 个文件,filename=文件名不含目录——飞书 im 文件上传这类"字段名钉死
   * file"的服务用,2026-07-16)。
   */
  uploadDir?: {
    token: string;
    fields?: Record<string, string>;
    fileFieldPrefix?: string;
    fileField?: string;
  };
  /** 超时毫秒(clamp 到 [MIN, MAX];媒体模式与上传用 MEDIA_* 档;缺省各自 DEFAULT)。 */
  timeoutMs?: number;
  /**
   * 响应处理模式:'text'(缺省)= 文本回沙箱;'media' = 受支持的媒体字节由
   * 主机落总仓记账,只回取件地址(见 GHOST_FETCH_MEDIA_* 常量);'file' =
   * 任意类型字节由主机直接写进 save 票据指向的 workdir 目录(须同时传
   * saveTo;字节不进沙箱也不进总仓,见 GHOST_SAVE_DEPOSIT_* 常量)。
   */
  as?: 'text' | 'media' | 'file';
  /**
   * 下行落盘票据(仅 as:'file',必填):token 来自 ghost_call 顶层 save_dir
   * 过户后注入的 args.save_deposit.token;filename 为建议文件名(可选,主机
   * 消毒并防覆盖去重;缺省从 Content-Disposition / URL 派生)。
   */
  saveTo?: { token: string; filename?: string };
  /** 媒体入账备注(画廊 caption;仅媒体模式消费,≤GHOST_FETCH_LABEL_MAX_CHARS)。 */
  label?: string;
  /**
   * OAuth 多账号选择(仅对 source:'oauth' 的凭证生效):指定用哪个已连接
   * 账号的令牌注入(账号 id 来自 /oauth 端点的账号清单);缺省 = 默认账号。
   * 非 oauth 凭证忽略本字段。
   */
  authAccount?: string;
  /**
   * tool-call 的 callId 原样带上。当前 Agent 调用时既用于日志归因,也用于
   * 复用 Agent 授权;自主调用可省略并按 network 声明守门。
   */
  callId?: string;
}

/** 代理 fetch 的返回(cindy.send 的 resolve 值)。 */
export type GhostPipeFetchResult =
  | {
      ok: true;
      /** HTTP 状态码(4xx/5xx 也走 ok:true——那是"代发成功,对方说不行")。 */
      status: number;
      /** 响应头(主机过滤后的白名单字段,如 content-type)。 */
      headers: Record<string, string>;
      /** 响应体文本(≤ GHOST_FETCH_RESPONSE_MAX_BYTES,超限截断)。 */
      body: string;
      /** body 被截断时为 true。 */
      truncated?: boolean;
    }
  | {
      ok: true;
      status: number;
      headers: Record<string, string>;
      /**
       * 媒体模式取件单(as:'media' 且响应为受支持媒体):字节已落总仓、
       * 记在本意识名下——url 聊天/面板皆可渲染,hash 可作改图源图/面板取件。
       */
      media: { url: string; hash: string; ext: string; bytes: number };
    }
  | {
      ok: true;
      status: number;
      headers: Record<string, string>;
      /**
       * 下行落盘回执(as:'file' 且 2xx):字节已写进 save 票据指向的目录。
       * file_name 是消毒去重后的最终文件名(相对该目录);dir_name 是过户时
       * 注入 args.save_deposit 的目录名,拼给用户看用。
       */
      file: { file_name: string; bytes: number; mime_type: string };
    }
  | { ok: false; message: string };

/** 工具调用的结构化失败分类(与 cindy-tools 的 CindyGhostCallErrorCode 同构)。 */
export type GhostToolCallErrorCode =
  | 'GHOST_NOT_FOUND'
  | 'GHOST_NAMESPACE_MISMATCH'
  | 'GHOST_ASLEEP'
  | 'GHOST_DISABLED_IN_WORKDIR'
  | 'TOOL_NOT_FOUND'
  | 'GHOST_CRASHED'
  | 'TIMEOUT'
  | 'ATTACHMENT_INVALID'
  | 'DIR_INVALID'
  | 'INTERNAL';

/** 主机错误码不能被插件结果覆盖;其余格式合法的码作为业务错误码透传。 */
const GHOST_HOST_ERROR_CODES: ReadonlySet<string> = new Set([
  'GHOST_NOT_FOUND',
  'GHOST_NAMESPACE_MISMATCH',
  'GHOST_ASLEEP',
  'GHOST_DISABLED_IN_WORKDIR',
  'TOOL_NOT_FOUND',
  'GHOST_CRASHED',
  'TIMEOUT',
  'ATTACHMENT_INVALID',
  'DIR_INVALID',
  'INTERNAL',
]);

export function isGhostPluginErrorCode(value: unknown): value is string {
  return (
    typeof value === 'string' &&
    /^[A-Z][A-Z0-9_]{0,63}$/.test(value) &&
    !GHOST_HOST_ERROR_CODES.has(value)
  );
}

/** 工具调用结果(主机侧;ghost 总机 MCP 原样透传给 agent)。 */
/**
 * An image a plugin shows the model with its tool result (top-level `images` of
 * the `tool-result` message). `mimeType` is sniffed from the bytes by the host.
 */
export interface GhostModelImage {
  data: string;
  mimeType: string;
}

export type GhostToolCallResult =
  | { ok: true; result: unknown; images?: GhostModelImage[] }
  | { ok: false; errorCode: GhostToolCallErrorCode | (string & {}); message: string };

/**
 * ghost_call 的工具全名。两套 agent 的 MCP toolName 形态不同:
 * Claude Code 是 `mcp__<server>__<tool>`,Codex translator 组装成
 * `mcp:<server>:<tool>`(见 maker-core codex/translator.ts handleMcpToolCall),
 * 两种都要认——漏了 Codex 形态时,Codex 会话的意识召唤行/意识卡全部退化成
 * 通用 MCP 行「cindy · ghost call」。2026-07-12 server 由 'cindy_ghosts'
 * 更名 'cindy'(调用名更短);旧名保留用于匹配改名前持久化的历史消息
 * (召唤行/已召唤卡对老会话不失效)。
 */
export const GHOST_CALL_TOOL_NAMES: readonly string[] = [
  'mcp__cindy__ghost_call',
  'mcp__cindy_ghosts__ghost_call',
  'mcp:cindy:ghost_call',
  'mcp:cindy_ghosts:ghost_call',
];

/** toolName 是否是 ghost_call(兼容新旧 server 名)。 */
export function isGhostCallToolName(name: string | undefined | null): boolean {
  return typeof name === 'string' && GHOST_CALL_TOOL_NAMES.includes(name);
}

/** Plugin-to-host routine protocol; source identity always comes from the authenticated pipe. */
export type GhostPipeRoutineRequest =
  | { type: 'routine-request'; action: 'status'; status: 'listening' | 'disconnected' | 'error' }
  | { type: 'routine-request'; action: 'publish'; event: import('@cindy/maker-scheduler').RoutineEvent };