领域术语表
此术语表会随需求访谈持续更新。带“暂定”的定义尚未由产品决策确认。
| 术语 | 当前定义 | 状态 |
|---|---|---|
| 桌面客户端 | Serpent 的图形化第一方访问面；通过 Automation Command Gateway 使用领域能力，并承载 Console 与保存脚本的交互。 | 已确认 |
| 自动化命令网关（Automation Command Gateway） | Desktop、脚本、MCP 与测试共享的规范能力边界；统一命令 Schema、能力、副作用、错误、取消、日志与领域调度。避免称为 CLI 层或 MCP 层。 | 已确认 |
| 自动化命令（Automation Command） | 由稳定 ID、输入/结果 Schema、能力要求、影响等级和执行策略定义的一次语义化领域操作；不同 transport 对同一命令不得改变领域语义。 | 已确认 |
| 自动化执行（Automation Execution） | 一次脚本运行形成的受控执行单元；MCP transport session 不形成业务执行上下文，只承载请求关联、通知与取消。MCP 每个命令自包含目标和参数。避免称为系统进程或后台 Job，后两者是实现/调度概念。 | 已确认 |
| 执行计划（Execution Plan） | 高风险文件写入在真正执行前生成的不可变影响摘要；绑定命令参数、实体版本和资源库变更序号，前提变化后必须重新生成。 | 已确认 |
| 操作历史（Operation History） | 每个资源库独立的线性业务修改历史；Desktop、脚本、MCP 与插件共享。Library Worker 持有权威状态和版本化双向配方，Main 只投影菜单、toast 与调用结果。不同于浏览前进/后退、文件恢复日志或版本管理。 | 已确认 |
| 历史组（History Group，原 Undo Group） | 将同一用户意图下一个或多个已提交领域步骤组合成单一撤回/重做边界。Desktop 一次动作、脚本一次 execution、MCP 一个 mutation 默认各形成一组；组是补偿与展示边界，不冒充跨命令 ACID 事务。 | 已确认 |
| 历史步骤（History Step） | 历史组中一次已提交的领域修改；由 Worker 保存受 schema 约束的 forward/inverse recipe、受影响实体和两方向前置条件，不是任意 SQL、函数或 transport 参数。 | 已确认 |
| 历史尝试（History Attempt） | 对一个历史组执行一次 undo 或 redo 的可恢复技术记录；保存方向、步骤进度、幂等状态和关联 file operation，使多步骤转换在失败或重启后能收口。它不是新的用户历史条目。 | 已确认 |
| 撤回（Undo） | 对当前资源库操作历史的栈顶组按步骤逆序执行 inverse recipe，并在前置条件不满足时安全拒绝。不同于事务回滚、崩溃恢复和从回收站恢复。 | 已确认 |
| 重做（Redo） | 对刚被撤回的栈顶组按步骤正序执行已保存的 forward recipe；不是重新调用原始脚本/MCP 请求。撤回后发生新修改会清空 redo 分支。 | 已确认 |
| 历史屏障（History Barrier） | 已提交但不可撤回的领域修改，例如从磁盘永久删除；它截断 redo，并使依赖其受影响实体的旧历史条目失效。只读和可再生成任务不是屏障。 | 已确认 |
| 历史失效（Stale History Entry） | 历史条目仍存在，但实体版本、路径、内容或目标占用已不满足安全撤回/重做前置条件；系统必须返回结构化冲突，不能执行近似恢复。 | 已确认 |
| 自动化能力（Automation Capability） | 授权脚本或 Agent 调用一类领域命令的稳定权限单位，例如读取资产、写入标签或移动文件；拥有能力不绕过领域校验。避免泛称权限开关。 | 已确认 |
| 能力授权（Capability Grant） | 将脚本内容哈希、目标资源库与能力集合绑定的用户许可；代码、资源库或能力变化后失效，交互式 Console 默认仅会话有效。 | 已确认 |
| 权限策略（Permission Policy） | 用户为一个 MCP 客户端凭据持久配置的能力边界；默认 Auto，也可设为只读或预先禁用具体能力。调用期间不逐项询问人类，连接重启不改变策略。 | 已确认 |
| 会话权限授权（Session Permission Grant） | 已废止概念。transport session 不承载权限；不能以“本 session 总是允许”作为产品边界。 | 已废止 |
| 危险操作 Challenge（Dangerous Operation Challenge） | dangerous MCP 命令第一次调用返回的短时、一次性风险证明；绑定客户端、命令、完整参数、目标库和前置版本。Agent 携带它二次确认后才可执行，过期、篡改、重放或状态变化均失效。 | 已确认 |
| 关键危险确认（Critical Confirmation） | 已废止的运行时人类弹窗模型；MCP dangerous 操作改用 Agent 二阶段 Challenge，Desktop 自身的危险操作可按其独立交互设计处理。 | 已废止 |
| 自动化脚本 | 使用受控 serpent API 组合领域命令的 JS/TS 程序或交互式代码；不等同于 Node.js 脚本，默认不能访问任意模块、进程环境、文件系统、网络或数据库。 | 已确认 |
| 脚本运行时（Script Runtime） | 执行自动化脚本的隔离环境；只通过 Automation Command Gateway 获得能力，并可被限时、限内存、取消和终止。避免称为插件运行时。 | 已确认 |
| MCP Server | 正式 Desktop Main 内嵌、由应用设置启停的 loopback Streamable HTTP 服务；负责客户端认证、业务无状态的 MCP 请求和 Automation Command 协议适配，不拥有领域业务逻辑，也不提供任意脚本执行。避免称为 headless Host、attached proxy 或 daemon。 | 已确认 |
| MCP 客户端凭据（MCP Client Credential） | 用户从设置页为一个 MCP 客户端签发的本机连接能力，以 高熵 token 证明客户端身份；它不等于 session capability、资源库授权或高风险操作批准。 | 已确认 |
| 显式资源库目标（Explicit Library Target） | 每个 MCP 库级命令必须携带的 libraryId；它只作用于本次调用，不建立 session 默认值，也不随 Desktop 焦点变化。 | 已确认 |
| 活动资源库上下文（Active Library Context） | MCP 中已废止的 session 业务状态。Desktop 可以显示某个资源库，但它不成为 Agent 的隐式目标。 | 已废止 |
| 命令行客户端（CLI） | 已撤回的旧方案：2026-07-28 的只读 CLI 基础层已被移除，当前不对人类、Shell Agent 或 CI 提供通用 CLI。若将来恢复，必须作为 Gateway 的薄适配器重新决策。 | 已撤回 |
| 稳定标识符 | 不随实体移动、重命名或显示名称变化而改变的底层身份。 | 已确认 |
| 资源库路径 | 在一个显式指定的资源库内唯一定位实体的路径。移动或重命名实体会改变资源库路径，但不会改变稳定标识符；它不同于任意操作系统路径、显示名称或合集路径。 | 已确认 |
| 资源引用 | 在一个显式指定的资源库中精确定位单一实体的引用；只允许稳定 ID 或唯一资源库路径，不允许标签、合集、过滤条件或搜索表达式充当精确引用。 | 已确认 |
| 资产过滤 | 按标签、合集、文件夹、评分、格式等结构化条件选出一组资产；过滤不是单一实体定位。 | 已确认 |
| 资产 | 通过导入过滤规则、被 Serpent 纳入管理的文件。首版不把依赖文件组合成复合资产。 | 已确认 |
| 资源库 | 自包含的资产、数据库、预览、组织关系和设置目录；用户可以创建、整体移动并同时打开多个资源库。 | 已确认 |
| 资产名称 | 资产的真实文件名；MVP 不再提供独立 Label/显示别名，修改资产名称会重命名真实文件。 | 已确认 |
| 描述 | 用户或 AI 为资产填写的自然语言内容说明。 | 已确认 |
| 标签 | 附加在资产上的可复用分类词；AI 可选择现有标签或创建新标签。 | 已确认 |
| 元信息 | 用于描述、过滤或排序资产的结构化属性，包括通用文件属性和格式专属属性。 | 已确认 |
| 元数据并发版本（entity_version） | AssetMetadata 行的乐观并发控制 token，仅用于 expectedVersion 校验；不是文件内容版本，不作为用户可见版本号。 | 已确认 |
| 色卡 | 由本地算法从当前资产内容自动提取、也可由用户编辑或替换的一组代表色；人工色卡优先，不使用 AI。 | 已确认 |
| 分类 | 使用文件夹、合集、喜欢、标签、评分、元信息、用户等维度组织或筛选资产。 | 已确认 |
| 资源库文件夹 | 映射 Assets/ 下真实目录的主要存放位置；一项托管资产最多属于一个文件夹，移动分类会移动文件。 | 已确认 |
| 合集（Collection） | 文件夹主结构之外的树状虚拟分类和策展容器；支持名称、描述、封面和手动排序，一项资产可加入零个或多个合集且不改变文件位置。 | 已确认 |
| 喜欢 | 资产的布尔状态；被标记的资产自动出现在“喜欢”视图。 | 已确认 |
| 评分 | 用户给资产设置的 0–5 星评价。 | 已确认 |
| 磁盘目录 | 操作系统文件系统中的真实目录；Serpent 可在用户确认后移动、重命名或删除其中的文件。 | 已确认 |
| 复制导入 | 将原文件复制进由 Serpent 管理的资源库存储。 | 已确认 |
| 链接文件夹 | 用户通过“以链接方式导入”挂载到 Serpent 的真实磁盘目录；内容不复制，Serpent 中的文件操作会作用于源目录。 | 已确认 |
| 链接过滤规则 | 通过图形界面配置的路径过滤；命中的文件或目录不被 Serpent 索引、展示或操作。 | 已确认 |
| 丢失资产 | 资产记录仍存在于数据库，但托管文件或链接文件无法在记录位置找到。 | 已确认 |
| 批量重新定位 | 用户指定新根目录后，依据原有相对目录结构一次恢复多个丢失资产的文件引用；可用于托管或链接资产。 | 已确认 |
| 回收站 | 暂存从资源库删除的托管资产，使其在永久清理前可以恢复。 | 已确认 |
| 搜索 | 对文件名、标签、描述、源链接、文件夹和其他元信息执行的加权全文检索；不同于结构化过滤和排序。 | 已确认 |
| 可浏览资产集合 | 活动工作区在当前导航范围、是否包含子文件夹以及结构化过滤条件下可到达的资产集合。关键词搜索只缩小这个集合，不擅自切换到整个资源库或另一合集。 | 已确认 |
| 普通文本搜索 | 在全部已索引字段（文件名、标签、描述、源链接、作者、文件夹路径、元信息）上执行的大小写不敏感包含搜索；允许单字符关键词，输入停顿约 200ms 后自动执行，不等同于结构化过滤。AI 分析不提供另一种搜索模式。 | 已确认 |
| 搜索表达式 | 输入搜索栏的文本规则：空格分隔的词为 AND，` | 分隔的词为 OR，前缀- 排除词，双引号保留短语；name:、tag:、desc:、link:、author:、path:、meta:` 字段限定词将匹配限制在指定字段。表达式只在当前可浏览资产集合内求值。 |
| 命中高亮 | 搜索结果中与普通文本搜索词相符的、当前可显示文本片段的视觉强调；结果卡的文件名和上下文摘要可高亮，高亮不改变资产原始名称、标签或元信息。 | 已确认 |
| 向量搜索 | 使用 embedding 向量计算语义或视觉相似度的搜索方式；不进入 MVP。 | 已确认 |
| 人工内容 | 用户填写或修改的描述、标签等资产信息；独立于 AI 内容保存并拥有显示优先级。 | 已确认 |
| AI 内容 | 模型生成的描述、标签或结构化元信息；与人工内容和文件提取元信息分开保存，记录模型来源，可以按资产范围清空且不得覆盖人工内容。重新分析只保留当前结果。 | 已确认 |
| AI 写入策略 | 全局设置中按字段控制是否允许 AI 写入标签、描述等内容；MVP 默认全部开启。 | 已确认 |
| 视频联系表 | 从视频抽取多帧、标记时间并拼接成一张图，供视觉语言模型整体分析。 | 已确认 |
| 过滤 | 使用格式、标签、尺寸、时长、源链接等结构化条件缩小结果集合。 | 已确认 |
| 文件夹浏览项 | 资产画布中代表真实 ManagedFolder 或 LinkedFolder 子目录的条目；它可以显示计数和派生封面，但不是 Asset。 | 已确认 |
| 工作区历史 | 文件夹、合集、搜索或过滤等浏览上下文的后退/前进记录；不同于文件操作撤销，也不同于资产查看页面的返回。 | 已确认 |
| 排序 | 按名称、时间、大小、上传用户、颜色或时长等属性改变结果顺序。 | 已确认 |
| 缩略图 | 资产网格中用于快速识别内容的静态小图。 | 已确认 |
| 悬停放大 | 鼠标停留时放大资产卡片；可解析媒体在此状态下提供播放等行为。该交互需要原型验证。 | 暂定 |
| 资产查看页面 | 双击或按 Space，从资产浏览页面进入的中央临时深入状态；Esc 或“返回”恢复原浏览范围、滚动位置、选择和焦点。它不是弹窗或独立窗口。 | 已确认 |
| 返回查看来源 | 从资产查看页面回到来源资产浏览页面；切换文件夹、合集、标签等资产范围也隐含执行该返回。语义不同于关闭窗口、资源库或弹窗。 | 已确认 |
| 全屏查看 | 从资产查看页面显式进入的沉浸显示方式；它不等于进入资产查看页面。 | 已确认 |
| 外部打开 | 调用系统默认或用户指定的软件正式打开资产文件。 | 已确认 |
| 智能合集（Smart Collection） | 保存搜索、过滤和排序条件、内容随资产变化自动更新的动态合集；不保存手动成员关系。 | 已确认 |
| 修订（Revision） | 同一逻辑资产的一次文件内容状态。currentRevisionId 指向当前修订；导入、替换或接受外部内容变化时切换，元数据和组织操作不改变它。修订记录用于关联当前内容及其衍生物；存在记录不代表旧文件字节仍被保留。 | 已确认 |
| 版本管理 | 面向用户查看、保留和恢复历史修订的产品能力；不进入 MVP，且不同于底层修订记录。 | 已确认 |
| 同步 | 在客户端与集中资产库之间自动传递资产或元数据；同步方向、离线行为和冲突规则尚待确认。 | 暂定 |
| 多机并发使用 | 同一资源 库同时被两台或更多电脑打开或写入；MVP 明确不支持，也不把底层文件锁视为协作保证。 | 已确认 |
| 协作 | 多名成员使用同一共享资源库；评论、审批等显式协作工作流不进入 MVP。 | 暂定 |
| 插件 | 安装后可长期扩展格式、文件处理、搜索、AI、UI、输入、Hook、Provider、存储或自动化能力的 JS/TS Package；它拥有生命周期，不等同于一次自动化脚本运行。 | 已确认 |
| 受限插件（restricted） | 运行在受控 JS 环境、只能使用声明并授权的 Plugin SDK 的插件；权限是 Host 可执行的能力边界。 | 已确认 |
| 非受限插件（unrestricted） | 由用户明确选择、运行在独立 Node.js 进程并具有完整系统能力的插件；权限清单用于风险披露和 Serpent API 管理，不承诺拦截全部系统行为。 | 已确认 |
| 用户级插件 | Package 安装在当前 Serpent 用户数据中的插件；代码不随资源库同步，可选择在哪些资源库启用。 | 已确认 |
| 资源库级插件 | Package 和非秘密资源库配置保存在 .serpent/ 并随资源库同步的插件；每台设备首次执行前都需要本机信任。 | 已确认 |
| 插件信任 | 当前设备针对确定的 Package 摘要、来源、运行模式和权限集合做出的执行许可；不得随资源库同步。 | 已确认 |
| 插件版本选择 | 同一插件同时存在用户级和资源库级版本时，当前设备针对当前资源库选择其中一个版本或禁用的决定；两版本不能同时激活。 | 已确认 |
| 插件实例 | 一个确定插件版本的运行单元；范围可为应用会话级 global 或单资源库 library，与 Package 的用户级/资源库级安装位置相互独立。 | 已确认 |
| 插件 Contribution | 插件向 Host 注册的命令、菜单、工具栏、面板、视图、设置、Hook 或 Provider 描述；停用插件后必须可完整撤销。 | 已确认 |
| Contribution Context | Host 为当前窗口与 UI 表面发布的有界、可同步读取状态，只用于插件 Contribution 的显示、启用和选中条件，不是功能 API。 | 已确认 |
| Invocation Context | 用户触发插件命令时冻结的窗口、资源库和目标选择快照；命令据此确定本次目标，再通过 Domain API 读取或修改实体。 | 已确认 |
| Context Key | Contribution 条件表达式可读取的规范状态值；复杂插件判断必须异步解析并发布为插件命名空间 key，不能在菜单打开时执行 I/O。 | 已确认 |
| 输入捕获会话 | 插件在限定视图、查看页或 Serpent 应用内暂时独占键盘/指针事件的有界会话；不同于普通快捷键和操作系统全局 Hook。 | 已确认 |
| 白板 | 类似 PureRef 的独立自由布局文档，可引用资产库中的资产；不进入 MVP。 | 已确认 |
| 源链接 | 浏览器扩展保存网页图片或视频时记录的用户所见网页地址；它是文件资产的元数据，不是媒体直链或独立书签资产。 | 已确认 |
| 疑似重复 | 文件名和文件大小均相同的两项资产；系统只提示用户，不自动跳过或合并。 | 已确认 |