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。

164 KB
Raw Blame
import { parseGhostSecretCheck, type GhostSecretCheckDecl } from './secretCheck.js';
import { parseGhostRoutineEvents, type GhostRoutineEvents } from './routineEvents.js';

/** `.cindy` 包根目录中的 manifest 文件名。 */
export const GHOST_MANIFEST_FILE = 'ghost.json';

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

/** 新建 ghost.json 使用的格式版本;与 Plugin HTTP API envelope 版本独立演进。 */
export const GHOST_MANIFEST_SCHEMA_VERSION = 3 as const;

/** ghost.json 的 description / whenToUse 字符上限。 */
export const GHOST_MANIFEST_SUMMARY_MAX_CHARS = 300;

/** Cindy host locales supported by Plugin manifest resources. */
export const GHOST_LOCALES = ['zh-CN', 'en', 'ja', 'ko'] as const;
export type GhostLocale = (typeof GHOST_LOCALES)[number];
export type GhostManifestLocales = {
  en: string;
} & Partial<Record<Exclude<GhostLocale, 'en'>, string>>;

/** Maximum size of one locale JSON resource in a `.cindy` package. */
export const GHOST_LOCALE_MAX_BYTES = 64 * 1024;

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

/** Windows 设备保留名;带扩展名时仍不能作为文件或目录名。 */
const WINDOWS_RESERVED_NAME_RE = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\..*)?$/i;

function isWindowsReservedName(name: string): boolean {
  return WINDOWS_RESERVED_NAME_RE.test(name);
}

/**
 * schemaVersion 2 能力名清单,仅用于兼容旧包。
 * 'cindy' = 请 Cindy 本体代办(借主机自带 AI 能力干活;2026-07-11 定案
 * 由 'model' 更名——本质是 Cindy 在干活,与选模型无关;旧名在校验层作
 * 静默别名兼容,已装老包不消失)。
 * 'network' = 意识自带服务:域名白名单
 * 内的 HTTP 经主机代发(沙箱本身保持零直连),凭证锁主机保险库按声明注入。
 * 'notify' = 系统提示(2026-07-14):意识经管子请主机弹一条轻提示(toast),
 * 意识只供纯文本,整块 UI 主机画并带意识身份头(与订阅槽红条同一信任边界);
 * 无阻塞、无按钮、无回执——确认类交互不在此槽(走面板自绘或卡槽③交互卡)。
 * 'fs' = 写文件(2026-07-14):意识经管子请主机代写文件(创建/修改)。三档
 * 目的地:自己的私有数据目录(userData/ghost-fs/<id>,免确认)、当前会话
 * workdir(跟随会话 permission 模式:免批模式直写、逐条模式弹确认卡、
 * plan/只读拒)、save 票据目录(主 agent 过户,复用 saveDeposit 预算)。
 * 字节永远由主机落盘,沙箱本身仍无 fs——本槽是"申请主机代写"的资格,
 * 不是文件系统访问权。
 * 'main-view' = 应用级插件主视图:宿主只挂载已批准 manifest 声明的包内
 * HTML 入口。它与会话内 panel 独立授权,本身不附赠网络、文件或
 * 凭证能力。
 * 'task-view' = 跟对话的任务页:页签存在各任务的右侧栏里、随任务切换;与
 * main-view 同一 WebView 沙箱,本身不附赠网络、文件或凭证能力。
 * 'session-context' = 会话上下文(2026-07-23):agent 派活(tool-call)时,主机把
 * 当次会话的可信 {session_id, workdir, workdir_is_local} 注入 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。未知 v2 slot 会被保留供兼容诊断,但不会
 * 被猜测成某个 Host 能力,也不会阻止安装。
 */
export 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}$/;

/**
 * 电子脑启动模式(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 = 右侧栏页签系统里聊天区对应边的页签组
 * (不跟对话的全局页签,用户放置过后以用户为准);'tab' = 不进页签组,由插件页独占承载。
 */
export const GHOST_PANEL_POSITIONS = ['left', 'right', 'top', 'bottom', 'tab'] as const;
export type GhostPanelPosition = (typeof GHOST_PANEL_POSITIONS)[number];

/** 面板声明(卡槽之一,一段意识至多一块)。 */
export interface GhostPanelDecl {
  /** 面板标准头(PanelChrome)标题;缺省用意识 name。 */
  title?: string;
  /** 显示形态:left / right 停靠,或 'tab' 右侧栏页签;缺省 = right(2026-07-12 定案)。 */
  position?: GhostPanelPosition;
  /** 面板界面入口(安装目录内相对路径,意识自绘,由主机面板容器渲染)。 */
  html: string;
  /** 面板最小宽度(px),布局引擎拖缝时的下限。仅停靠形态有效,'tab' 时禁用。 */
  minWidth?: number;
  /** 装入布局时的初始宽度占比(与 layoutTree 的 fraction 同语义)。仅停靠形态有效,'tab' 时禁用。 */
  defaultFraction?: number;
}

/** 应用级插件主视图可用的 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 独立授权;
 * Host 只会挂载这里声明且经过批准的包内 HTML 入口。
 */
/** 左侧导航入口点击后主视图在哪里打开(插件给的默认偏好;用户放置过后以用户的为准)。 */
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。 */
  open?: GhostMainViewOpenMode;
  /** open:'sidebar' 时的默认边;其它 open 值下声明拒装。 */
  side?: GhostTabSide;
  /** 允许同一视图同时开在多处;缺省单实例。只接受字面量 true。 */
  multiple?: true;
}

/** 跟对话的任务页:页签存在各任务的右侧栏里,随任务切换;页面经查询参数 `session` 得知所在任务。 */
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>;
}

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

/**
 * Agent 新回合能力详单。
 *
 * 声明 `agent` 默认只允许消费宿主在真实用户点击插件卡片时签发的
 * 一次性通行票;可选加档由 Desktop 如实展示,并由 Host 在运行时守门。
 */
export interface GhostAgentNeeds {
  background?: boolean;
  errand?: boolean;
  tasks?: boolean;
  /** 查询项目、任务、伙伴并投递消息;必须同时声明 tasks,需独立批准。 */
  targets?: boolean;
  /** 后台隐藏任务;必须与 `tasks: true` 同时声明。 */
  hiddenTasks?: boolean;
  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;

/** 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 槽·媒体类可申请的动作(deposit=寄存自己手里的媒体字节入总仓)。 */
export const GHOST_CINDY_MEDIA_ACTIONS = ['deposit'] as const;
export type GhostCindyMediaAction = (typeof GHOST_CINDY_MEDIA_ACTIONS)[number];

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

/**
 * cindy 槽·向量类可申请的动作(2026-08-04 开闸)。
 *
 * `text` = 文本转向量:意识递一批文字,主机经统一 embedding 通道返回等长的
 * 向量数组。只生成、不存储;向量原样递回意识自己保管。与 text.oneshot
 * 分成两档:两者花不同的钱(轻量任务模型链 vs embedding 模型),合成一档
 * 就没法只授权其中一样。
 */
export const GHOST_CINDY_EMBED_ACTIONS = ['text'] as const;
export type GhostCindyEmbedAction = (typeof GHOST_CINDY_EMBED_ACTIONS)[number];

/** cindy 槽·搜索类可申请的动作(web=Cindy 托管的公网搜索)。 */
export const GHOST_CINDY_SEARCH_ACTIONS = ['web'] as const;
export type GhostCindySearchAction = (typeof GHOST_CINDY_SEARCH_ACTIONS)[number];

/**
 * cindy 槽能力详单(卡槽⑤配套,原名模型槽,2026-07-11 设计定案):声明"这个意识被允许
 * 向主机点哪几类代办"——只有类目与动作,**不含任何具体模型/供应商信息**
 * (选型权在主机的解析表:调用时显式点名 > 意识专属覆盖 > 用户能力偏好 >
 * 出厂默认;意识只表达意图,永不腐烂)。插件详情与代办资格审共同消费。
 */
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/模型/耗时/用量,不含消息内容);
 * session = 会话创建/归档/切换(切换 = 用户把哪个会话切到台前,2026-07-13 增)。
 * 正文级主题(消息内容旁听)刻意不开——隐私最重,等真实场景再议,权限文案
 * 也要另分一档。
 */
export const GHOST_SUBSCRIBE_TOPICS = ['turn', 'session'] 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 槽详单──────────────────────────────────
 * 意识自带服务:作者声明域名白名单 + 凭证需求,装入时钉死、确认框逐项展示。
 * 运行期沙箱仍零直连,所有出网经管子 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`、`a.b.example.com`),
 * 但不命中裸域本身——作者两者都要就两条都声明,规则不做隐式扩张。
 * 注意:此行为必须与桌面端 base 的同名校验器逐字一致(两端同一契约),
 * 任何语义调整都属于协议变更,需两侧同步。
 */
function ghostNetworkHostMatches(pattern: string, hostname: string): boolean {
  if (pattern.startsWith('*.'))
    return hostname.endsWith(pattern.slice(1)) && hostname.length > pattern.length - 1;
  return hostname === pattern;
}

/**
 * 凭证注入声明:该凭证以什么形态、进哪些域名的请求头。绑定在 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
 * 去换一个临时令牌(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 条数上限(超出拒装;确认框逐条展示要可读)。 */
export const GHOST_OAUTH_SCOPES_MAX = 256;
/** OAuth broker 模式允许声明的备用 client ID 数量上限。 */
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 定案"通用声明式"):
 * 平台不预设 provider 名单——意识声明"去哪授权、要什么 scope",clientId /
 * clientSecret 由用户在意识设置页自填(经 /oauth 只写通道入库),插件详情
 * 全量展示授权域名与 scopes,用户知情自担。声明化的是**参数**不是**代码**:
 * 授权流程(拉浏览器、loopback 回调、state/PKCE 校验、code 换 token、刷新)
 * 永远由主机可信代码执行,意识无从插手,
 * 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 定案,开箱即用前置)。
   * 声明后用户零配置即可点"连接账号";用户在设置页自填的
   * client 凭证**覆盖**内置值(清除自填 = 回落内置)。桌面应用的 client
   * 凭证按 Google 官方口径本非机密(installed-app),写进包里不引入新泄露面;
   * 授权仍需用户在浏览器里亲自同意,凭证本身访问不了任何数据。
   */
  clientId?: string;
  /** 可选:broker 模式下允许意识在单次连接时选择的备用客户端 ID。 */
  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 增补):人类可读的展示名
   * 模板,`{点分路径}` 占位符从同一份身份响应取值(如 Slack auth.test 的
   * `"{team} · {user}"`)。与 labelPath 分工:labelPath 指向**稳定且唯一**的
   * 身份键(user_id / 邮箱),是重复授权时同身份合并的判定键;displayTemplate
   * 只管展示(设置页 / 账号工具看到的名字),任一占位符取不到值时整体降级
   * 为空(回落显示 labelPath 标签)。不声明 = 展示名就用 labelPath 的值
   * (邮箱这类本身可读的服务商不需要它)。
   */
  identity?: {
    url: string;
    labelPath: string;
    displayTemplate?: string;
    avatarPath?: string;
  };
  /**
   * 可选:loopback 回调固定端口(1024–65535)。Atlassian 这类服务商要求回调
   * URI 与应用注册值精确匹配(含端口),声明后主机授权引擎钉死
   * `http://127.0.0.1:<port>/callback`(端口被占用时结构化报错引导重试);
   * 缺省 = 随机端口(Google 等允许任意 loopback 端口的服务商)。
   */
  redirectPort?: number;
  /**
   * 可选:服务端 token broker 的 provider slug(2026-07-14 增补)。
   * 声明后 code 换 token 与 refresh 不直连 tokenUrl,改经主机
   * 调服务端的授权 broker(带登录 JWT;client secret 在服务端,不随包
   * 分发)。与 clientSecret 互斥。静态官方前缀照旧放行;其余资格由可信组织市场
   * 来源、批准包字节与当前组织事实共同判定。校验层保持纯函数不感知装入语境,
   * 门控在装入闸与连接闸。
   */
  tokenBroker?: string;
  /**
   * 可选:broker 弹跳回调(双地址模型,2026-07-15 增补)。
   * 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 定型):
 * - 'user'(缺省):值由用户在该意识设置页填入主机保险库;
 * - 'login-email':值 = 主机当前登录账号的邮箱——主机注入时现取登录态,
 *   设置页只读展示该邮箱(不可编辑、不进保险库);未登录 / 登录态缺 email
 *   时 fail-closed 报错并引导重新登录。适用于"服务端按登录邮箱派生鉴权"
 *   的第一方服务(经 inject.format 的静态前缀完成派生)。
 * - 'oauth'(2026-07-13 增补):值 = 主机托管 OAuth
 *   授权换来的 access token——用户在意识设置页填 client 凭证并点"连接账号",
 *   主机跑授权流程并保管全部令牌,出网时现取新鲜 token 注入(见
 *   GhostSecretOauthDecl;必须同时声明 oauth 详单)。
 * - 'login-feishu-token'(2026-07-16 增补):值 = 主机
 *   飞书登录态的 user access token——主机注入时现取(登录态管理器
 *   自刷新,token 明文不进沙箱、不进错误消息);未连接飞书 / 刷新链路判
 *   AUTH_EXPIRED 时 fail-closed 报错并引导重新登录飞书。适用于"能力面
 *   直接复用产品飞书登录身份"的第一方服务;与 login-email 同族:用户
 *   不填值,禁 url / exchange / oauth,settingsHtml 豁免。
 * - 'oidc-token'(2026-08-03 增补):值 = 主机为当前企业 Membership
 *   按受信组织插件 provenance 按需签发的短时 Cindy Connection JWT;
 *   插件和 Node Worker 都不能读取或保存令牌。必须固定注入
 *   `Authorization: Bearer {value}` 并显式声明非空的精确 inject.hosts;
 *   不允许 url / exchange / oauth / input,也不要求 settingsHtml。只有
 *   organization scope 的插件可以通过 Plugin Market 发布该来源。
 * - 'gh-cli'(2026-08-05 增补):值优先取主机本地 GitHub CLI
 *   登录态(`gh auth token`),不可用时回落到用户在该插件设置页
 *   保存的备用 Token。两种值都只允许固定注入
 *   `https://api.github.com` 的 `Authorization: Bearer {value}`;插件和
 *   Node Worker 不能读取令牌。必须声明 settingsHtml 作为
 *   备用 Token 的管理入口,不允许 exchange / oauth / input。
 */
export const GHOST_SECRET_SOURCES = [
  'user',
  'login-email',
  'oauth',
  'login-feishu-token',
  'oidc-token',
  'gh-cli',
] as const;
export type GhostSecretSource = (typeof GHOST_SECRET_SOURCES)[number];

/**
 * 凭证收单(2026-07-13 两次定案,当天收敛):user 凭证的收单**一律**由意识
 * settingsHtml 自绘——经协议 `/secrets` 只写通道一次性入库,存入后意识拿不回
 * 明文,保管(safeStorage)与注入(主机代发时)由主机独占。安全模型弱化点
 * 仅一处:录入瞬间明文经过意识页面(用户主动敲进它的输入框),插件详情
 * 如实告知。**宿主渲染凭证输入行已整体退役**(基座不再为意识特设凭证 UI,
 * 定案):清单里遗留的 `input: "ghost"` 接受并忽略(与现状同义),
 * `input: "host"` 直接拒绝;声明 user 凭证必须同时声明 settingsHtml。
 */

/** 凭证声明:只有名字与说明——值由用户在该意识设置区填入主机保险库。 */
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[];
}

/**
 * 注入头名黑名单:协议关键头由主机独占,作者声明命中即拒装
 * (小写比较;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',
];

/** preview 槽:可打开预览的域名模式条数上限(范围越小越好,同 network 精神)。 */
export const GHOST_PREVIEW_MAX_HOSTS = 4;

/**
 * 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]',
]);

/** 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 形状——小写字母/数字,连字符仅作单段分隔(禁首尾与连续
 * 连字符)。比 SkillHub 的技能名规则更严:意识 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[];
}

/** setup 作者声明:组间 allOf,组内 anyOf。 */
export type GhostSetupRequirement =
  | { kind: 'secret'; key: string }
  | { kind: 'connection'; key: string }
  | { kind: 'kv'; key: string; label: string };

export interface GhostSetupGroup {
  anyOf: GhostSetupRequirement[];
}

export interface GhostSetupDecl {
  requires: GhostSetupGroup[];
}

export const GHOST_SETUP_MAX_GROUPS = 8;
export const GHOST_SETUP_MAX_ITEMS_PER_GROUP = 8;
export const GHOST_SETUP_KV_KEY_RE = /^[A-Za-z0-9_.-]{1,64}$/;

/** 已校验的 ghost.json 协议文档;Desktop 会再投影成无 slots 的运行时模型。 */
export interface GhostManifest {
  /** Host-owned mail editor; providers supply mailbox adapters only. */
  mail?: true;
  /** Provider-owned read capability; Cindy owns mail presentation. */
  mailReader?: { tool: string; hosts: string[]; markRead?: true };
  /** Optional v3 extension; consumers validate it without changing legacy approval content. */
  recommendations?: unknown;
  /** v2 仅作存量兼容;新插件使用 v3。 */
  schemaVersion: 2 | typeof GHOST_MANIFEST_SCHEMA_VERSION;
  /** 唯一标识,同时是安装目录名与 panelKind 后缀。 */
  id: string;
  /** 展示名。 */
  name: string;
  /** 版本字符串(不强制 semver,仅展示用)。 */
  version: string;
  /** 本版本相对上一实际发布包的完整更新说明;旧包可省略。纯文本。 */
  releaseNotes?: string;
  /**
   * 安装此 Release 所需的最低 Cindy 客户端版本。缺省表示不限制客户端版本;
   * 声明时必须是合法 SemVer,客户端与 Plugin Server 使用同一比较语义。
   */
  minCindyVersion?: string;
  /** 作者展示名(仅展示用)。 */
  author?: string;
  /**
   * 宿主语言到包内 locale JSON 的映射。声明时必须提供英文资源作为固定
   * 回退;路径须唯一,且不能与其它 manifest 文件声明冲突。
   */
  locales?: GhostManifestLocales;
  /**
   * 意识自我介绍(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 新回合能力;v3 空对象表示仅允许真实用户点击触发。 */
  agent?: GhostAgentNeeds;
  /** 随包本地 Node 工作进程能力。 */
  node?: GhostNodeNeeds;
  /**
   * 设置页「自定义设置区」界面入口(可选;安装目录内相对路径,意识自绘)。
   * 与面板同款沙箱 webview 渲染(零桥、分区断网、CSP 'self'),主题 token
   * 由主机灌入。用户填写的 `network.secrets` 与 `node.secretBindings` 凭证
   * 必须在此页面收单并经 `/secrets` 只写通道立即交给主机保险库,不得写入
   * `/kv`;其它自定义参数持久化走同源 `fetch('/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;
  /** 仅 schemaVersion 2 存在的兼容声明。 */
  slots?: LegacyGhostSlot[];
  /**
   * card 能力;v3 空对象表示仅渲染、无外链。
   * externalLinks: true 时卡片内可声明 data-ghost-link,点击经宿主确认框后打开浏览器。
   */
  card?: GhostCardNeeds;
  /** 注册给 agent 的工具声明;字段本身就是能力声明。 */
  tools?: GhostToolDecl[];
  /**
   * Cindy 代办能力。v2 的旧字段名 model 在兼容校验层收入本字段。
   */
  cindy?: GhostCindyNeeds;
  /**
   * 订阅能力与事件范围。
   * hooks 非空时 launch 必须为 'resident'(校验强制)。
   */
  subscribe?: GhostSubscribeNeeds;
  /** Autonomous publishing of declared events into user-configured routines. */
  routineEvents?: GhostRoutineEvents;
  /**
   * network 能力与访问范围。
   * 域名白名单 + 凭证声明由插件详情逐项展示,运行期主机代发并守门。
   */
  network?: GhostNetworkNeeds;
  /**
   * 显式触发指令(聊天输入框 `/<command>`,与 Skill 共用命令入口;
   * 2026-07-09 定案:由意识作者自定,装入时主机与已装意识查重,
   * 冲突即拒)。须声明 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;
  /**
   * preview 能力详单;v2 与 'preview' slot 成对。可在右侧栏内置浏览器
   * 打开预览标签页的域名白名单。
   */
  preview?: GhostPreviewNeeds;
  /**
   * skill 能力详单;v2 与 'skill' slot 成对。随包捆绑的 Agent Skills 清单。
   * 启用时由 Cindy 私有入口加载到本地 Claude Code、Codex 与 Pi,不写用户共享目录;字段不参与
   * 本地化(必须与 SKILL.md 逐字一致,见 GhostSkillItem)。
   */
  skill?: GhostSkillNeeds;
  /** 无配置的 Host 能力在 v3 中只接受字面量 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;
  /**
   * 随包渐进披露手册。它不是能力 slot 或授权项;Host 只把索引投影给模型,
   * 正文经 ghost_manual 按需读取。旧客户端忽略这一可选顶层字段。
   */
  manual?: GhostManualNeeds;
  /** 使用前置检查;引用必须绑定本清单已声明的凭证、连接或设置项。 */
  setup?: GhostSetupDecl;
  /** v3 未知顶层字段原样保留,但 Host 不解释、不展示、不授权。 */
  [key: string]: unknown;
}

/** 判断已校验的 manifest 是否请求 Host 托管的企业身份凭证。 */
export function ghostManifestUsesOidcToken(manifest: GhostManifest): boolean {
  return manifest.network?.secrets?.some((secret) => secret.source === 'oidc-token') ?? false;
}

/** 判断值是否可作为 `ghost.json.id` 和跨平台安全的安装目录名。 */
export function isValidGhostId(id: unknown): id is string {
  return typeof id === 'string' && GHOST_ID_RE.test(id) && !isWindowsReservedName(id);
}

/**
 * 插件详情与不兼容安装提醒共用的单项能力说明。
 * 纯数据描述:renderer 拼 `settings.ghosts.perm.<labelKey>` 翻译,`detail` 是
 * 作者自由文本(如工具描述)如实展示不翻译,`detailKey` 是主机固定说明的
 * i18n 后缀(如可执行代码的沙箱说明)——两者互斥。
 */
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 路径 → 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` 形态——正斜杠分段、无盘符、无反斜杠、无空段、
 * 无 `.`/`..` 段、无 Windows 设备保留名、字符集收敛,天然杜绝路径穿越
 * 与跨平台歧义。
 */
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 !== '..' && !isWindowsReservedName(seg),
  );
}

/** `validateGhostManifest` 的无异常校验结果。 */
export type ManifestValidation =
  { ok: true; manifest: GhostManifest } | { ok: false; reason: string };

interface ParsedCindyVersion {
  core: readonly [string, string, string];
  prerelease: readonly { numeric: boolean; value: string }[];
}

function compareNumericIdentifiers(left: string, right: string): -1 | 0 | 1 {
  if (left.length !== right.length) return left.length < right.length ? -1 : 1;
  if (left === right) return 0;
  return left < right ? -1 : 1;
}

function parseCindyVersion(value: string): ParsedCindyVersion | null {
  const match =
    /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.exec(
      value,
    );
  if (!match) return null;
  const core = [match[1], match[2], match[3]] as [string, string, string];
  const prerelease: Array<{ numeric: boolean; value: string }> = [];
  for (const part of match[4]?.split('.') ?? []) {
    const numeric = /^\d+$/.test(part);
    if (numeric && !/^(0|[1-9]\d*)$/.test(part)) return null;
    prerelease.push({ numeric, value: part });
  }
  return { core, prerelease };
}

/** 判断值是否是可参与兼容性比较的 Cindy SemVer。 */
export function isValidCindyVersion(value: unknown): value is string {
  return typeof value === 'string' && value.length <= 32 && parseCindyVersion(value) !== null;
}

/** 开发构建没有正式版本号,按当前源码兼容处理。 */
export function isVersionlessCindyVersion(value: string): boolean {
  return value === '0.0.0' || value.startsWith('0.0.0-');
}

/** 按 SemVer 2.0.0 比较两个 Cindy 版本;任一格式非法时返回 null。 */
export function compareCindyVersions(leftValue: string, rightValue: string): -1 | 0 | 1 | null {
  const left = parseCindyVersion(leftValue);
  const right = parseCindyVersion(rightValue);
  if (!left || !right) return null;
  for (let index = 0; index < 3; index += 1) {
    const coreComparison = compareNumericIdentifiers(left.core[index], right.core[index]);
    if (coreComparison !== 0) return coreComparison;
  }
  if (left.prerelease.length === 0 || right.prerelease.length === 0) {
    if (left.prerelease.length === right.prerelease.length) return 0;
    return left.prerelease.length === 0 ? 1 : -1;
  }
  const length = Math.max(left.prerelease.length, right.prerelease.length);
  for (let index = 0; index < length; index += 1) {
    const leftPart = left.prerelease[index];
    const rightPart = right.prerelease[index];
    if (leftPart === undefined || rightPart === undefined) {
      return leftPart === undefined ? -1 : 1;
    }
    if (leftPart.numeric !== rightPart.numeric) return leftPart.numeric ? -1 : 1;
    const partComparison = leftPart.numeric
      ? compareNumericIdentifiers(leftPart.value, rightPart.value)
      : leftPart.value === rightPart.value
        ? 0
        : leftPart.value < rightPart.value
          ? -1
          : 1;
    if (partComparison !== 0) return partComparison;
  }
  return 0;
}

/** 缺少最低版本即不限制;非法当前版本按不兼容处理。 */
export function supportsCindyVersion(
  currentVersion: string,
  minCindyVersion: string | undefined,
): boolean {
  if (minCindyVersion === undefined) return true;
  if (!isValidCindyVersion(currentVersion) || !isValidCindyVersion(minCindyVersion)) return false;
  if (isVersionlessCindyVersion(currentVersion)) return true;
  const comparison = compareCindyVersions(currentVersion, minCindyVersion);
  return comparison !== null && comparison >= 0;
}

/** 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_RESERVED_RECORD_KEYS = new Set(['__proto__', 'constructor', 'prototype']);

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

const GHOST_MANIFEST_KNOWN_TOP_LEVEL_FIELDS = new Set([
  'routineEvents',
  'schemaVersion',
  'id',
  'name',
  'version',
  'releaseNotes',
  'minCindyVersion',
  'author',
  'locales',
  'description',
  'whenToUse',
  'icon',
  'kind',
  'entry',
  'launch',
  'agent',
  'node',
  'settingsHtml',
  'settingsHeight',
  'showTaskPreferences',
  'slots',
  'card',
  'mail',
  'mailReader',
  'tools',
  'cindy',
  'model',
  'subscribe',
  'network',
  'command',
  'keywords',
  'panel',
  'mainView',
  'taskView',
  'preview',
  'skill',
  'manual',
  'setup',
  'notify',
  'badge',
  'confirm',
  'fs',
  'library',
  'deviceSync',
  'sessionContext',
  'pick',
  'workspace',
  'iosSimulator',
]);

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;
  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) {
    return {
      ok: true,
      prepared: {
        raw: Array.isArray(value.slots)
          ? { ...value, slots: dropEmptyLegacyCapabilitySlots(value, value.slots) }
          : value,
        schemaVersion: 2,
        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;
  return {
    ok: true,
    prepared: {
      raw: {
        ...value,
        slots: syntheticSlots,
        ...(v3BaseCard ? { card: undefined } : {}),
        ...(v3BaseAgent ? { agent: undefined } : {}),
      },
      schemaVersion: 3,
      v3BaseCard,
      v3BaseAgent,
      unknownV3Fields: Object.fromEntries(
        Object.entries(value).filter(
          ([key]) => key === 'model' || !GHOST_MANIFEST_KNOWN_TOP_LEVEL_FIELDS.has(key),
        ),
      ),
    },
  };
}

/** 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;
  });
}

/**
 * 校验一份 JSON.parse 后的未知 `ghost.json` 值。已知字段严格检查;v2 未知
 * 字段忽略,v3 未知顶层字段原样保留但不解释、不授权。
 */
export function validateGhostManifest(value: unknown): 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' };
  // Keep this shape aligned with maker-shared's runtime reader parser.
  const reader = raw.mailReader as Record<string, unknown> | undefined;
  if (raw.mailReader !== undefined && (!reader || typeof reader !== 'object' ||
      typeof reader.tool !== 'string' || !/^[a-zA-Z][a-zA-Z0-9_-]{0,127}$/.test(reader.tool) ||
      (reader.markRead !== undefined && reader.markRead !== true) ||
      !Array.isArray(reader.hosts) || !reader.hosts.length || reader.hosts.length > 16 ||
      !reader.hosts.every(h => typeof h === 'string' && h.length <= 253 && /^[a-z0-9]+(?:[.-][a-z0-9]+)*\.[a-z]{2,}$/.test(h)))) {
    return { ok: false, reason: 'mailReader 必须声明合法的 tool 与 hosts' };
  }
  if (reader && (raw.mail !== true || !Array.isArray(raw.tools) ||
      !raw.tools.some(tool => isPlainObject(tool) && tool.name === reader.tool))) {
    return { ok: false, reason: 'mailReader 必须同时声明 mail: true 与对应的 tools 工具' };
  }
  if (!isValidGhostId(raw.id)) {
    return {
      ok: false,
      reason: 'id 必须是 1–32 位小写字母/数字/连字符(不能以连字符开头或使用 Windows 设备保留名)',
    };
  }
  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 &&
    (typeof raw.minCindyVersion !== 'string' || !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: string[] = [];
    const skillDirFolds = (
      isPlainObject(raw.skill) && Array.isArray(raw.skill.items) ? raw.skill.items : []
    )
      .map((item) => (isPlainObject(item) ? item.dir : undefined))
      .filter((value): value is string => typeof value === 'string')
      .map((value) => value.toLowerCase());
    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.some((path) =>
        pathsConflict(path, normalizedLocalePath),
      );
      const conflictsWithSkillDir = skillDirFolds.some((dir) =>
        isSameOrDescendant(dir, normalizedLocalePath),
      );
      const conflictsWithManualDir = manualDirFolds.some((dir) =>
        pathsConflict(dir, normalizedLocalePath),
      );
      if (conflictsWithFile || conflictsWithSkillDir || conflictsWithManualDir) {
        return {
          ok: false,
          reason: `locales.${locale} 路径 ${JSON.stringify(localePath)} 与插件其他声明文件大小写折叠后冲突`,
        };
      }
      if (seenPaths.includes(normalizedLocalePath)) {
        return {
          ok: false,
          reason: `locales 含重复路径 ${JSON.stringify(localePath)}`,
        };
      }
      if (
        seenPaths.some(
          (path) =>
            isSameOrDescendant(path, normalizedLocalePath) ||
            isSameOrDescendant(normalizedLocalePath, path),
        )
      ) {
        return {
          ok: false,
          reason: `locales.${locale} 路径 ${JSON.stringify(localePath)} 与其他 locale 文件存在祖先路径冲突`,
        };
      }
      seenPaths.push(normalizedLocalePath);
      normalized[locale] = localePath;
    }
    locales = {
      ...normalized,
      en: normalized.en!,
    };
  }
  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 之间的数字',
      };
    }
    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(' / ')}`,
        };
      }
      // 页签形态没有拖缝宽度语义:收词明确拒绝而非静默忽略(规则 9)。
      if (p.position === 'tab' && (p.minWidth !== undefined || p.defaultFraction !== undefined)) {
        return {
          ok: false,
          reason:
            "panel.minWidth / panel.defaultFraction 仅停靠形态(left / right / top / bottom)有效,position:'tab' 时请移除",
        };
      }
    }
    panel = {
      ...unknownDeclarationFields(p, ['title', 'position', 'html', 'minWidth', 'defaultFraction']),
      ...(p.title !== undefined ? { title: p.title as string } : {}),
      ...(p.position !== undefined ? { position: p.position as GhostPanelPosition } : {}),
      html: p.html as string,
      ...(p.minWidth !== undefined ? { minWidth: p.minWidth as number } : {}),
      ...(p.defaultFraction !== undefined ? { defaultFraction: p.defaultFraction as number } : {}),
    };
  }

  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 (!isSafeGhostRelativePath(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 (!isSafeGhostRelativePath(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 必填)' };
  }
  if (slots.includes('badge') && panel === undefined) {
    return {
      ok: false,
      reason: 'slots 声明了 "badge" 但缺少 panel——未读点必须有可打开的面板内容',
    };
  }

  // card 槽能力详单:缺省 = 仅渲染;externalLinks: true 是独立加档权限。
  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 } : {}) };
    }
  }

  // 工具声明(卡槽②):与 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' || !/^[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(注册什么工具要写清楚)',
    };
  }

  // 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']);
    // 类目 → 合法动作表(image / video / media / text / embed / search;动作集恰好
    // 同名,但按类目查表,未来某类目动作分叉时这里天然承接)。
    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);
      }
      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 (Object.keys(cindy).filter((key) => key !== 'oneshotModel').length === 0) {
      return { ok: false, reason: 'cindy 能力详单不能是空对象' };
    }
    // oneshotModel(快问快答偏好模型)是标量意图键,不是类目:先摘出,不进类目循环。
    const oneshotModelRaw = cindyRaw.oneshotModel;
    if (oneshotModelRaw !== undefined) {
      if (
        typeof oneshotModelRaw !== 'string' ||
        oneshotModelRaw.trim().length === 0 ||
        oneshotModelRaw.length > 128
      ) {
        return {
          ok: false,
          reason: 'cindy.oneshotModel 必须是 1–128 字符的目录模型 id(如 "codex/gpt-5.5")',
        };
      }
      if (!cindy.text?.includes('oneshot')) {
        return {
          ok: false,
          reason: 'cindy.oneshotModel 必须与 text 含 "oneshot" 成对声明(它是快问快答的偏好模型)',
        };
      }
      cindy.oneshotModel = oneshotModelRaw.trim();
    }
    if (cindy.search?.includes('web') && (!slots.includes('tool') || tools === undefined)) {
      return {
        ok: false,
        reason: 'cindy.search.web 只允许由真实 tool-call 触发,必须同时声明 "tool" 槽和 tools',
      };
    }
  }

  // 订阅槽详单(卡槽①):与 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' || !/^[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)}`,
          };
        }
        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' = 主机登录邮箱派生(用户不填值)。
        // 归一化:'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 === 'login-feishu-token') source = 'login-feishu-token';
          if (s.source === 'oidc-token') source = 'oidc-token';
          if (s.source === 'gh-cli') source = 'gh-cli';
        }
        // 输入面字段已退役(2026-07-13 宿主凭证渲染整体退役):user 凭证
        // 一律意识 settingsHtml 收单。遗留 `input: "ghost"` 接受并忽略
        // (与现状同义、不落清单);其余值(含 'host')一律拒。
        if (s.input !== undefined && s.input !== 'ghost') {
          return {
            ok: false,
            reason:
              'network.secrets[].input 已退役:宿主收单不存在,用户填写的凭证一律由意识 settingsHtml 收单(删掉 input 字段即可;唯一可接受的遗留值是 "ghost")',
          };
        }
        // login-email / login-feishu-token 同族:值取自主机登录态派生,用户
        // 不填、没有输入面,禁 url / exchange,settingsHtml 豁免。oidc-token
        // 同样由 Host 托管,但值来自当前组织 Membership 的 Connection JWT。
        const loginDerived = source === 'login-email' || source === 'login-feishu-token';
        const oidcManaged = source === 'oidc-token';
        const ghCliManaged = source === 'gh-cli';
        if (s.input === 'ghost' && (loginDerived || oidcManaged || ghCliManaged)) {
          return {
            ok: false,
            reason: `source: ${source} 的凭证不允许标注 input: ghost(Host 托管凭证没有输入,谈不上谁收单)`,
          };
        }
        if (!loginDerived && !oidcManaged && raw.settingsHtml === undefined) {
          return {
            ok: false,
            reason:
              'network.secrets 声明了用户填写的凭证时必须同时声明 settingsHtml(凭证由意识设置界面收单,没有界面就没人收单;宿主渲染输入行已退役)',
          };
        }
        if (loginDerived && s.url !== undefined) {
          return {
            ok: false,
            reason: `network.secrets[].source 为 ${source} 时不允许声明 url(值取自主机登录态,没有"前往控制台"可去)`,
          };
        }
        if (loginDerived && s.exchange !== undefined) {
          // 组合会把登录态凭证作为原始值 POST 给交换端点,而确认框文案只
          // 承诺"派生注入请求头"——语义盖不住,结构上禁掉(有真实场景再议)。
          return {
            ok: false,
            reason: `network.secrets[].source 为 ${source} 时不允许声明 exchange(登录态凭证不外送交换端点)`,
          };
        }
        if (oidcManaged && s.url !== undefined) {
          return {
            ok: false,
            reason: 'network.secrets[].source 为 oidc-token 时不允许声明 url(令牌由 Host 按需签发)',
          };
        }
        if (oidcManaged && s.exchange !== undefined) {
          return {
            ok: false,
            reason:
              'network.secrets[].source 为 oidc-token 时不允许声明 exchange(不允许把 Connection JWT 转交给第三方端点)',
          };
        }
        if (ghCliManaged && s.exchange !== undefined) {
          return {
            ok: false,
            reason:
              'network.secrets[].source 为 gh-cli 时不允许声明 exchange(不允许把 GitHub 登录令牌转交给第三方端点)',
          };
        }
        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 (oidcManaged) {
          if (inj.header !== 'Authorization' || inj.format !== 'Bearer {value}') {
            return {
              ok: false,
              reason:
                'network.secrets[].source 为 oidc-token 时 inject 必须是 Authorization: Bearer {value}',
            };
          }
          if (injectHosts === undefined || injectHosts.length === 0) {
            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 (ghCliManaged) {
          if (inj.header !== 'Authorization' || inj.format !== 'Bearer {value}') {
            return {
              ok: false,
              reason:
                'network.secrets[].source 为 gh-cli 时 inject 必须是 Authorization: Bearer {value}',
            };
          }
          if (
            injectHosts === undefined ||
            injectHosts.length !== 1 ||
            injectHosts[0] !== 'api.github.com'
          ) {
            return {
              ok: false,
              reason:
                'network.secrets[].source 为 gh-cli 时 inject.hosts 必须且只能是 api.github.com',
            };
          }
        }
        // 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(可选):服务端 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;
            }
            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));
      for (const c of n.connections) {
        if (!isPlainObject(c)) return { ok: false, reason: 'network.connections 每项必须是对象' };
        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 撞名(两者共用命名空间)`,
          };
        }
        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 } : {}),
    };
  }

  // agent 能力详单:缺省 = 仅点击票据;可选加档由 Desktop 展示并由 Host 守门。
  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 (agentRaw.tasks !== undefined && typeof agentRaw.tasks !== 'boolean') {
      return { ok: false, reason: 'agent.tasks must be boolean' };
    }
    if (agentRaw.hiddenTasks !== undefined && 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 (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, ['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, ['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 文件',
      };
    }
    // 入口重合判定折叠大小写:Windows / macOS 默认文件系统大小写不敏感,
    // main.js 与 Main.js 是同一个文件,原样比较会漏判。
    if (nodeRaw.entry.toLowerCase() === (raw.entry as string).toLowerCase()) {
      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 文件',
          };
        }
        const extraFold = extra.toLowerCase();
        if (extraFold === (raw.entry as string).toLowerCase()) {
          return { ok: false, reason: 'node.entries 不能包含浏览器沙箱 entry' };
        }
        if (extraFold === nodeRaw.entry.toLowerCase()) {
          return {
            ok: false,
            reason: 'node.entries 不能重复主入口 node.entry',
          };
        }
        if (seen.has(extraFold)) {
          return {
            ok: false,
            reason: `node.entries 含重复入口 ${JSON.stringify(extra)}`,
          };
        }
        seen.add(extraFold);
      }
      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' || !/^[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 工作进程详单',
    };
  }
  if (node?.secretBindings) {
    for (const binding of node.secretBindings) {
      if (network?.secrets?.some((secret) => secret.key === binding.key)) {
        return {
          ok: false,
          reason: `network.secrets 的 key ${JSON.stringify(binding.key)} 与 node.secretBindings 撞名`,
        };
      }
      if (network?.connections?.some((connection) => connection.key === binding.key)) {
        return {
          ok: false,
          reason: `network.connections[].key ${JSON.stringify(binding.key)} 与 node.secretBindings 的 key 撞名(两者共用命名空间)`,
        };
      }
    }
  }

  // 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 域名白名单必填)',
    };
  }

  // skill 槽详单:与 slots 含 'skill' **严格成对**(有槽必有详单——捆绑了什么
  // 技能是本能力的全部知情面)。name/description 与 SKILL.md 的逐字一致性在
  // 打包与装入两侧另行强制,这里只管声明本身的形状。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 };
  }

  // setup 引用必须在交付边界就与同一份 manifest 的凭证、连接和设置入口对齐;
  // 不能让服务端接受、Desktop 装入时才拒绝。
  // 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 setupRaw = raw.setup as Record<string, unknown>;
    if (
      !Array.isArray(setupRaw.requires) ||
      setupRaw.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(
        (secret) =>
          [
            secret.key,
            {
              hostDerivedSource:
                secret.source === 'login-email' ||
                secret.source === 'gh-cli' ||
                secret.source === 'oidc-token'
                  ? secret.source
                  : null,
            },
          ] as const,
      ),
      ...(node?.secretBindings ?? []).filter((secret) => !secret.oauthSecret).map(
        (secret) => [secret.key, { hostDerivedSource: null }] as const,
      ),
    ]);
    const connectionKeys = new Set((network?.connections ?? []).map((connection) => connection.key));
    const groups: GhostSetupGroup[] = [];
    for (const group of setupRaw.requires) {
      if (
        !isPlainObject(group) ||
        !Array.isArray(group.anyOf) ||
        group.anyOf.length === 0 ||
        group.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 requirement of group.anyOf) {
        let item: GhostSetupRequirement;
        if (typeof requirement === 'string') {
          const match = /^(secret|connection):(.+)$/.exec(requirement);
          if (!match) {
            return {
              ok: false,
              reason: `setup 条目 ${JSON.stringify(requirement)} 形态不对(字符串条目须为 "secret:<key>" 或 "connection:<key>";kv 用对象 { "kv": "<key>", "label": "..." })`,
            };
          }
          const [, kind, key] = match;
          if (kind === 'secret') {
            const declaration = secretByKey.get(key);
            if (!declaration) {
              return {
                ok: false,
                reason: `setup 引用了未声明的凭证 ${JSON.stringify(key)}(必须逐字取自 network.secrets[].key 或 node.secretBindings[].key)`,
              };
            }
            if (declaration.hostDerivedSource) {
              return {
                ok: false,
                reason: `setup 不允许引用 ${declaration.hostDerivedSource} 源凭证 ${JSON.stringify(key)}(Host 派生身份没有用户配置动作可引导)`,
              };
            }
            item = { kind: 'secret', key };
          } else {
            if (!connectionKeys.has(key)) {
              return {
                ok: false,
                reason: `setup 引用了未声明的连接 ${JSON.stringify(key)}(必须逐字取自 network.connections[].key)`,
              };
            }
            item = { kind: 'connection', key };
          }
        } else if (isPlainObject(requirement)) {
          if (
            typeof requirement.kv === 'string' &&
            isGhostManifestReservedRecordKey(requirement.kv)
          ) {
            return {
              ok: false,
              reason: `setup kv 条目的 kv 不允许使用对象保留键名 ${JSON.stringify(requirement.kv)}`,
            };
          }
          if (
            typeof requirement.kv !== 'string' ||
            !GHOST_SETUP_KV_KEY_RE.test(requirement.kv)
          ) {
            return {
              ok: false,
              reason: 'setup kv 条目的 kv 必须是 1–64 位字母/数字/下划线/点/连字符的键名',
            };
          }
          if (
            typeof requirement.label !== 'string' ||
            requirement.label.trim().length === 0 ||
            requirement.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: requirement.kv, label: requirement.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 } : {}),
      ...(agent !== undefined || prepared.v3BaseAgent
        ? { agent: agent ?? {} }
        : {}),
      ...(node !== undefined ? { node } : {}),
      ...(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 }
        : {}),
      ...(prepared.schemaVersion === 2 ? { slots } : {}),
      ...(card !== undefined
        || prepared.v3BaseCard
        || (prepared.schemaVersion === 3 && slots.includes('card'))
        ? { card: card ?? {} }
        : {}),
      ...(tools !== undefined ? { tools } : {}),
      ...(raw.mail === true ? { mail: true as const } : {}),
      ...(reader ? { mailReader: { ...reader, tool: reader.tool as string, hosts: [...new Set(reader.hosts as string[])] } } : {}),
      ...(cindy !== undefined ? { cindy } : {}),
      ...(subscribe !== undefined ? { subscribe } : {}),
      ...(routineEvents !== undefined ? { routineEvents } : {}),
      ...(network !== undefined ? { network } : {}),
      ...(raw.command !== undefined ? { command: raw.command as string } : {}),
      ...(keywords !== undefined ? { keywords } : {}),
      ...(panel !== undefined ? { panel } : {}),
      ...(mainView !== undefined ? { mainView } : {}),
      ...(taskView !== undefined ? { taskView } : {}),
      ...(preview !== undefined ? { preview } : {}),
      ...(skill !== undefined ? { skill } : {}),
      ...(prepared.schemaVersion === 3 && slots.includes('notify') ? { notify: true as const } : {}),
      ...(prepared.schemaVersion === 3 && slots.includes('badge') ? { badge: true as const } : {}),
      ...(prepared.schemaVersion === 3 && slots.includes('confirm') ? { confirm: true as const } : {}),
      ...(prepared.schemaVersion === 3 && slots.includes('fs') ? { fs: true as const } : {}),
      ...(slots.includes('device-sync') ? { deviceSync: true as const } : {}),
      ...(prepared.schemaVersion === 3 && slots.includes('library')
        ? { library: true as const }
        : {}),
      ...(prepared.schemaVersion === 3 && slots.includes('session-context')
        ? { sessionContext: true as const }
        : {}),
      ...(prepared.schemaVersion === 3 && slots.includes('pick') ? { pick: true as const } : {}),
      ...(prepared.schemaVersion === 3 && slots.includes('workspace')
        ? { workspace: true as const }
        : {}),
      ...(prepared.schemaVersion === 3 && slots.includes('ios-simulator')
        ? { iosSimulator: true as const }
        : {}),
      ...(manual !== undefined ? { manual } : {}),
      ...(setup !== undefined ? { setup } : {}),
    },
  };
}