Serpent 产品简报

当前愿景

构建一款开源、免费的跨平台数字资产管理软件。Eagle 和 Billfish 是最直接的竞品。产品以本地资产管理体验为基础，并逐步提供 AI 自动分类、集中式资产同步及团队资产库能力。

游戏美术、影视后期和平面/UI/品牌设计师都是首发目标用户，不区分单一优先人群。MVP 先打透这些用户共有的图片与视频管理工作流，不提供垂直行业制作管线。

用户问题

• 资产散落在不同位置。
• 难以快速检索需要的资产。
• 难以在正式打开文件前快速预览内容。

产品原则

• 开源、免费。
• Windows 与 macOS 首发；不计划提供移动端。
• MVP 图形界面至少支持简体中文和英文，以及亮色、暗色和跟随系统主题；自定义主题推迟。
• 普通导入将文件复制进自包含资源库；只有“导入文件夹”可以明确选择“以链接方式导入”。
• 资源库文件夹映射 Assets/ 下的磁盘真实目录；MVP 不另设可让同一资产加入多个位置的独立虚拟文件夹实体。
• 搜索、过滤和排序是三个不同的用户动作，分别建模。
• 文件格式支持应可持续扩展，长期覆盖绝大多数常用图片和视频格式。
• AI 应能在导入时自动补全组织信息，也允许用户稍后手动触发。
• 插件必须显式声明权限，用户授权后才能访问敏感能力。

资产与组织

所有通过过滤规则的文件都是资产。首版不处理通用复合资产及任意文件依赖关系，但连续编号图片可以通过持久化序列关系折叠为一个可播放的序列图卡片；每帧仍保留独立文件资产身份。

资产可具有：

• 真实文件名作为资产名称；MVP 不提供独立 Label/显示别名，修改名称即执行文件重命名。
• 描述、标签、评分、“喜欢”状态和色卡。
• 文件夹、合集等组织关系。
• 文件格式、资产类型、分辨率、长宽比、时长、颜色、大小、添加/修改日期、源链接、上传用户等元信息。
• 随文件格式支持增加而扩展的格式专属元信息。

色卡由本地算法从当前资产内容中自动提取，不调用 AI。用户可以编辑或替换自动色卡；存在人工色卡时优先使用人工结果，内容修订变化后自动色卡重新生成。

AI 自动归类可生成描述、添加现有标签或创建新标签，但不能改名、移动文件、改变资产所在的资源库文件夹或把资产加入合集。

AI 自动识别结果默认写入独立的 AI 内容层，并标记生成模型与版本。用户可以在全局设置中分别关闭 AI 对标签、描述及其他支持字段的写入。人工内容、AI 内容与文件提取的技术元信息分开保存；人工内容优先显示且不会被 AI 覆盖，用户可以一键清空 AI 内容而不影响人工内容和技术元信息。首版不额外设计标签同义词治理机制，依靠模型能力与提示词尽量复用合适标签。

资源库文件夹是主要组织方式并映射真实磁盘目录，每项托管资产最多属于一个文件夹。合集（Collection）作为额外的虚拟分类和策展视图，可以跨文件夹收集资产且不改变磁盘位置；标签负责查找和筛选。

• 资源库文件夹用于实际存放一类资产，并映射真实磁盘目录。
• 合集用于长期归类和策展一类内容，不改变文件位置。一项资产可以加入零个或多个合集。
• 合集支持树状层级、名称、描述、封面和手动资产排序。打开父合集时默认汇总所有子合集资产，并可切换为“仅当前层”。
• “喜欢”是单个布尔状态，对应自动生成的“喜欢”视图。
• 评分使用 0–5 星。

资源库文件夹映射真实磁盘目录；在文件夹之间移动资产会移动托管文件。资产重命名会重命名真实文件并保持稳定资产 ID。

用户在 Serpent 内移动托管资产时，资产身份及描述、标签、合集、评分、喜欢、源链接和人工色卡等信息全部保持不变，并提供撤销移动。

所有用户元数据只保存在 Serpent 数据库中；MVP 不写入原文件，也不创建 sidecar 文件。

资源库

• 用户可以创建多个相互独立的资源库，并同时打开。
• 每个资源库是可整体移动的自包含磁盘目录，数据库、托管原文件和预览位于其中。
• Serpent 不额外维护自动备份；用户通过备份整个资源库目录保护资产与元数据。链接文件夹的源文件不在资源库内，需要用户另行备份。
• 多个资源库之间不进行联合搜索，标签彼此独立。
• 跨资源库拖放资产时执行复制，不从源资源库移除资产。
• 资源库允许位于本机磁盘、移动硬盘、NAS 或第三方同步目录；网络及同步目录存在一致性风险，产品提示风险但不禁止用户选择。
• MVP 中，同一资源库同一时间只支持在一台电脑上活动使用；从另一台电脑打开前，用户需要先在当前电脑关闭资源库。MVP 不实现跨设备并发协调或协作锁，也不承诺操作系统、NAS 或同步工具会可靠阻止同时写入。
• 不锁整个资源库。每台电脑只运行一个 Serpent 应用进程，该进程可同时打开多个窗口和资源库；数据库只在短事务期间持有写锁，文件操作只临时占用相关文件或文件夹。
• 资源库可在 Windows 与 macOS 之间直接移动并打开，无需格式转换；链接文件夹路径失效时需要重新指定。
• NAS 使用中断线时立即停止写入，界面进入只读/离线状态；恢复连接后重新校验资源库再允许写入。

MVP 工作流优先级

1. 导入本地素材目录并整理。
2. 通过链接文件夹持续管理外部工作目录。
3. 快速搜索、过滤和排序。
4. 快速浏览和预览素材。
5. 通过浏览器扩展采集素材。
6. AI 自动分类和描述。

三类首发用户共用同一条 MVP 验收主线：导入或链接图片与视频、立即开始浏览、使用真实文件夹/标签/元信息整理、通过关键词/过滤/排序找到目标素材、使用悬停预览/资产查看页面/显式全屏确认内容，最后通过外部应用打开。行业专属制作流程不作为 MVP 验收条件。

添加资产

MVP 支持：

• 选择文件或文件夹
• 拖拽导入
• 从剪贴板粘贴
• 通过浏览器扩展右键保存网页中的单张图片或视频，使用当前活动资源库并选择一个目标文件夹；保存时不选择合集，也不要求填写标签；媒体由浏览器下载后上传到本机 Serpent（无需配对码）
• 把网页图片或视频拖入 Serpent 窗口、侧边栏资源库文件夹或合集
• 浏览器采集时自动把原网页地址记录为资产的“源链接”元数据
• 通过链接文件夹持续反映真实目录内容

浏览器扩展发起保存时如果 Serpent 未运行，不自动启动应用；扩展提示用户先启动 Serpent，再重新执行保存。

复制导入整个文件夹时，完整保留源文件夹层级并复制到当前资源库文件夹下。单独导入文件、拖入文件或从剪贴板粘贴时，文件进入当前选中的资源库文件夹；没有选中文件夹时进入资源库 Assets/ 根目录。

MVP 不要求通过 URL 直接下载资产，也不要求接入操作系统分享菜单。

文件名与文件大小相同时视为疑似重复，提示用户选择跳过、合并或创建副本。该规则允许内容相同但名称不同的文件不被提示，也可能把名称、大小相同但内容不同的文件标为疑似重复，但不会自动处理。

文件进入同一资源库文件夹时若磁盘文件名已存在，提示“保留两者、替换或跳过”，默认选择保留两者，并为新文件名自动追加序号；批量操作允许把选择应用到全部。同名且同大小时先按疑似重复处理，其中“创建副本”即采用上述自动追加序号的保留两者行为。

选择合并时保留先加入的文件，并合并双方的标签、合集、“喜欢”和评分等元数据。

描述、源链接等单值字段冲突时，弹窗逐项选择，并允许勾选“为所有冲突文件执行此操作”。

不支持内置预览的文件仍然可以作为资产加入，使用通用文件图标，并可调用外部软件打开。

发现资产

资产画布不提供分页按钮，使用连续纵向浏览。用户可以在平铺和瀑布流之间切换，调整卡片大小，并选择是否显示名称、文件大小、修改日期等卡片信息。浏览与查看页面使用一致的缩放输入：Ctrl+鼠标滚轮和系统触控板 pinch；重排后尽量保持原视野中的资产仍然可见。视图和显示偏好跨重启保存。

进入资源库文件夹时，画布同时显示直接子文件夹和当前范围内资产。文件夹卡片使用完整圆角后层面板与带左侧标签、S 曲线搁架的前层口袋承载少量代表性资产缩略图，名称位于下方，并与当前瀑布流列宽对齐；所有目录入口显示资产数量，并允许显式切换是否包含后代文件夹资产。普通与链接文件夹在导航中统一呈现，链接或断链状态通过图标、颜色和说明表达，不另设链接文件夹分区。

顶层浏览工具栏只放搜索、过滤、排序、视图和显示控制。导入、粘贴、链接、资源库导入导出等动作进入资源库菜单、统一添加入口、快捷键或拖放流程。工作区提供可点击面包屑和后退/前进历史；鼠标前后侧键应触发与工具栏相同的后退/前进；面包屑不显示无效的“资源库”起始项。

标签不在左侧导航中完整枚举，也不提供独立标签管理页面。用户主要通过过滤条选择标签，并在 Inspector 中用 tag chip 查看、移除或添加标签；添加入口提供最近标签、搜索现有标签和输入新标签。

过滤

• 文件格式
• 标签
• 分辨率、长宽比、时长
• 源链接
• 其他结构化元信息

文件夹或合集可以作为当前主浏览范围，另一组织维度通过过滤面板叠加，最终结果取交集。

MVP 中，不同字段之间使用 AND，同一字段的多个值使用 OR，并允许把单个条件切换为排除。任意嵌套的高级 AND/OR 条件组推迟到后续版本。

排序

• 名称
• 修改时间、添加时间
• 文件大小
• 上传用户
• 颜色
• 时长

搜索

• 搜索只在当前可浏览的资产集合内执行：当前导航范围和已启用的结构化过滤条件共同决定该集合；在文件夹范围内，文本搜索默认包含全部后代文件夹，普通无搜索浏览仍由「包含子文件夹」开关控制。搜索不擅自跳转到整个资源库或另一合集。
• 普通关键词搜索匹配全部可索引字段（文件名、标签、描述、源链接、文件夹、其他元信息），采用大小写不敏感的包含匹配，并允许单字符关键词；输入停顿约 200ms 后自动刷新结果。
• 空格分隔的关键词使用 AND；| 分隔的关键词使用 OR；前缀 - 排除词；双引号保留包含空格或 | 的短语。字段限定使用规范短名：name:、tag:、desc:、link:、author:、path:、meta:。搜索框右侧提供问号提示，解释完整表达式语法。
• 文件名和标签命中优先，且完整匹配高于前缀与其他包含匹配；描述等其余字段随后。大量命中时先显示相关度最高的一批结果，再按现有资源浏览方式继续加载。
• 结果卡片中可显示的文件名及上下文摘要使用高亮强调；高亮不修改资产原始信息，也不得损害亮/暗主题下的可读性。
• MVP 不提供 AI 搜索、AI 查询转换或搜索栏中的 AI 开关；AI 仅用于用户明确发起的资产分析、自动分类和描述生成。
• MVP 不使用向量索引，不提供真正的向量语义搜索或视觉相似搜索。
• 视觉相似和向量语义搜索保留为后续能力，只有实际需求证明其价值后再引入。

智能合集

MVP 支持把搜索、过滤和排序条件保存为智能合集（Smart Collection）。其内容不是手动维护，而是随资产及元信息变化自动更新；智能合集位于合集区域，但不拥有手动成员关系。

在合集视图按 Delete 时只把资产从当前合集移除；真正删除资产使用独立的“从资源库删除”命令并确认。删除合集只删除合集及成员关系，不删除其中的资产。

预览

“预览”特指尚未正式打开资产时的快速检查：

• 图片：缩略图。
• 视频：直接播放、悬停自动播放、鼠标移动控制播放进度。
• 音频（后续格式）：波形和悬停播放。
• 3D（MVP 后）：简单模型查看。
• 不支持内置预览时：允许调用外部软件。

MVP 常用格式：PNG、JPG/JPEG、GIF、WebP、BMP、TIFF、TGA、EXR、ICO、SVG、PSD；主流相机 RAW（DNG、CR2、CR3、NEF、ARW、RAF、ORF、RW2）；MP4、MOV、AVI、WMV、WebM、MKV、M4V；WAV、MP3、OGG/OGA、M4A、AAC、FLAC、Opus。

预览与查看术语拆分为：

• 缩略图：资产网格中的静态小图。
• 悬停放大：所有资产卡片在鼠标停留时放大；可解析媒体在放大状态下提供播放等行为。具体视觉和易用性需要原型验证。
• 资产查看页面：双击或按 Space，从资产浏览进入主界面中央的临时深入状态。媒体默认完整适配可用区域；Esc 或左上角“返回”回到原浏览上下文。切换文件夹等资产范围也会返回浏览页面。
• 全屏查看：从资产查看页面显式进入的沉浸显示方式，不与“进入资产查看页面”混为同一动作。
• 外部打开：调用系统默认或用户指定的创作软件正式打开文件。

资产查看页面不常驻显示底部缩放条，也不使用占满顶部的工程式工具栏。正式实施前先研究成熟图片查看器并验证交互原型；缩放需要对触控板 pinch 足够灵敏、围绕手势焦点，并在放大后提供不会与资产切换或媒体控制冲突的平移方式。详细验收见 0013 查看器导航与手势。

所有资产在悬停时都放大卡片。在放大状态下，视频和 GIF 支持按设置自动播放或悬停播放，音频支持播放；其他格式逐步增加适合自身的快速交互。放大交互需先通过独立原型验证视觉效果与易用性；若验证不通过，MVP 使用普通资产卡片和显式预览入口，不为保留该交互牺牲可用性。

EXR、TIFF 和 TGA 在 MVP 中显示常规预览，并支持基本色彩管理与曝光显示。PSD 只显示合成预览，不读取或编辑图层；SVG 与 ICO 只提供可视化预览，不提供编辑能力；RAW 使用内置解码器生成显示预览，不提供 RAW 调整面板。EXR 必须列出并允许切换文件中的可显示 plane/part；复杂通道检查、专业调色和图层/矢量编辑推迟。

产品还计划提供类似 PureRef 的独立白板文档；白板引用资产库中的资产。该能力推迟到 MVP 后。

插件系统

插件系统建立在自动化命令网关之上，计划支持：

• 新格式解析与预览
• 导入、导出和文件处理
• 搜索与 AI 模型
• 资产/文件夹菜单、工具栏、Inspector、查看页、侧栏入口与完整工作区
• 应用内键盘、鼠标、输入捕获和领域事件 Hook
• 云存储与第三方服务
• 自动化工作流

插件只提供 TypeScript/JavaScript 一等开发模型。自动化脚本负责单次或保存的批处理， 插件负责安装、生命周期、UI、Hook、Provider、输入捕获和后台任务；两者共享同一 serpent 领域 API，但不能用常驻脚本代替插件。

标准插件运行在受控环境，权限是可执行的能力边界。可信插件获得完整 Node.js 能力， 等同用户主动运行的本地程序；其权限清单用于风险披露和 Serpent API 管理，不能承诺 拦截所有直接系统行为。

插件既可安装到用户配置，也可作为成品保存在资源库 .serpent/plugins/ 中随资源库 同步。资源库插件在每台设备上首次运行前必须显式信任；信任、密钥和本机路径不随资源库 同步。同一插件同时存在用户级和资源库级版本时，由用户选择当前资源库使用哪个版本， Serpent 不设置隐藏优先级。

第一阶段支持官方插件社区（Serpent-Plugin-Pool 钉死的 Release ZIP）、本地包、本地目录和符合规范的 GitHub 仓库 URL，并且不会执行 远程仓库中的依赖安装、构建或生命周期脚本。完整边界见 0024-script-plugin-platform.md。

资产调用外部应用只通过右键菜单中的“使用外部应用打开/打开方式”进入。

MVP 边界

MVP 明确推迟：

• 团队协作
• 多台电脑同时打开或写入同一资源库
• 资产版本管理
• 3D 预览
• 创作软件集成
• 开放投稿的第三方插件市场（当前为官方认证目录，不是任意上传）
• PureRef 式白板

移动端不属于长期产品计划。MVP 以已定义的工作流和性能指标验收，不设置用户量、留存率等商业指标，也不依赖遥测判断是否完成。

MVP 的设计容量上限为单个资源库最多约 10 万个文件、2 TB 原始内容。

MVP 性能行为要求：

• 给用户以安全感。 打开或切换资源库若持续超过 3 秒，才显示一行明确的资源库身份和“切换资源库”按钮；在文件夹、合集、标签、回收站摘要和首批资产查询形成一致快照前，不展示新资源库的部分首屏，也不保留旧资源库的导航。结构确认完成后再进入主界面。详见 docs/internal/ui/0006-progressive-loading-ux-principles.md。
• 普通内容路径继续渐进。 文件夹/合集范围切换、缩略图、查看器原图、搜索、导入和 AI 结果仍可先显示首屏或占位，再在后台补齐；打开资源库不等于同步完成全部缩略图、索引或 AI。
• 普通过滤、排序和关键词搜索在 1 秒内返回首屏。
• 新增文件立即显示占位项，缩略图和 AI 在后台完成。
• 后台任务显示进度和失败原因，并支持重试。
• 预览或 AI 失败不阻止资产加入资源库。

已有 10 万项资产的资源库仍须在结构一致性确认后再给出首屏；若打开持续超过 3 秒，只显示“正在打开某某资源库”和切换入口。资产列表、缩略图、索引与 AI 结果继续渐进式加载。

MVP 后方向

• 以共享资源库作为团队协作基本单位。
• 原始资产集中存储，并支持客户端自动同步。
• 若未来支持多人编辑，倾向使用资产锁避免并发修改；具体模型需结合竞品调研决定。
• 支持完全本地无账号、官方云和自托管；各模式的产品边界尚待确认。
• 本地模型、官方云、自托管、自动同步、可见版本管理和商业模式均明确推迟到 MVP 后分别设计，不作为当前实现或发布阻塞项。

链接文件夹

链接文件夹只在用户执行“导入文件夹”时，通过“以链接方式导入”显式创建。它不复制原始内容，而是在“链接文件夹”区域显示真实磁盘目录。

用户在 Serpent 中对链接文件夹及其内容进行增删查改时，直接作用于源目录。删除或移动文件/文件夹前需要弹出确认窗口；用户可以在设置中关闭确认。

链接文件夹支持类似 .gitignore 的过滤规则。匹配规则的文件和文件夹不被索引、展示或操作。

过滤规则通过图形界面配置，支持按路径、文件名、扩展名、文件夹以及排除条件组合，由程序在内部生成路径匹配规则，不要求普通用户编辑 .gitignore 风格文本。Serpent 提供可修改的推荐默认规则，例如忽略 .git、缓存、临时文件和操作系统杂项。

链接文件夹过滤与 AI 分析过滤是两套独立规则，但复用同一个图形化规则编辑器。

若规则变化使已有资产变成被忽略状态，该资产从界面移除，但保留描述、标签等数据库元数据；以后取消忽略时恢复。把普通资产拖入链接文件夹时，将文件复制到真实源目录。

链接文件内容在外部发生变化时，Serpent 自动刷新预览和元信息。找不到原文件时，资产保留并显示“文件丢失”，用户可以重新定位。

链接文件被外部软件覆盖后，MVP 不复制或保留旧文件字节。Serpent 可以记录内容已经变化并使旧预览、提取元信息和 AI 结果失效，但不能恢复被源目录覆盖的旧内容。

外部软件修改资源库中的托管文件时，Serpent 检测到变化后自动把磁盘现状作为当前内容，刷新预览、元信息和 AI 结果，并向用户显示非阻断通知。

托管文件被外部软件原地覆盖时，MVP 同样不承诺保留修改前的旧文件字节。用户在 Serpent 客户端内执行“替换文件”时，MVP 在提供可见的版本管理能力之前也不保留可恢复的历史内容；底层仍保留稳定资产身份和修订记录，以便安全切换当前内容并支持未来演进。

用户在 Finder、资源管理器或其他 Serpent 以外的软件中移动或重命名托管文件时，Serpent 不自动猜测新路径；原资产保留并标记“文件丢失”。用户可以手动找回单项资产，也可以指定新根目录按原相对结构批量找回。重新关联时询问是否沿用原资产信息并支持批量应用；选择沿用时保留描述、人工与现有 AI 标签、合集、评分、喜欢、源链接和人工色卡，重新生成缩略图、提取元信息及 AI 内容。

批量外部变化自动合并为一条摘要通知，不要求用户逐项接受。

批量重新定位时，允许用户指定一个新的根目录；若多个丢失文件在新位置保持原有相对目录结构，Serpent 可以一次恢复全部引用。

Serpent 不负责自动追踪任意文件移动。

链接文件夹支持单向转换为资源库托管文件夹：复制源内容进入资源库，成功后移除链接关系。

产品需要提供一键导入和导出整个资源库。导出既可完整复制目录，也可选择不使用 ZIP64 的普通 ZIP；导出前预检，超过普通 ZIP 支持的大小或条目限制时提示无法导出 ZIP，只允许改用完整文件夹导出。导出时询问是否把链接文件夹内容一并复制进导出结果。

MVP 只支持导出整个资源库，不提供按合集导出。

默认导出包含托管资产、数据库、用户元数据，以及资源库中实际仍被保留的历史修订；可重新生成的缩略图、预览、代理和 AI 临时文件默认排除。链接文件夹内容仍在每次导出时询问。

资源库采用用户可读的目录结构：托管资产位于 Assets/ 下并按资源库文件夹组织；数据库、预览、修订和回收站位于普通可见的 .serpent/ 内部目录。

删除与恢复

• 删除复制进资源库的资产时，先进入 Serpent 回收站，不弹出确认。
• 删除链接资产或链接文件夹时，默认将源文件移入系统回收站，不弹出确认。链接与托管在删除操作上同等。「从库中移除」只取消索引、不碰磁盘，是另一条动作，可保留确认。从硬盘永久删除（Shift+Delete）仍需确认。
• Serpent 回收站默认保留一个月。
• 清理到期内容时若文件正被其他软件占用，跳过该文件并在结果中提示，下次清理继续尝试；单个占用文件不使整批清理失败。

AI 执行方式

• MVP 只连接用户自带 Key 的云端模型；本地模型和 Ollama 等本地服务属于后续阶段。
• 首次配置云端模型时展示一次免责声明，说明资产内容可能发送到所选供应商；用户保存配置后仍需显式打开“新增资产自动进行 AI 分析”，不会默认对每次导入自动入队。
• API Key 配置界面提供“测试连接”，用最小请求验证当前供应商、Key 和所选模型此刻是否可访问，并明确区分认证、权限、额度和网络错误。
• 启用自动分析后，导入完成会在后台运行 AI 处理并向用户展示进度；未配置或未打开开关时只在用户手动触发后分析。
• AI 模型、自动运行行为和云端授权使用全局配置，适用于所有资源库。
• 全局设置允许分别开启或关闭 AI 对标签、描述及其他支持字段的写入；默认全部开启。
• 资产分析模型生成描述、标签和 AI 评分，不直接访问数据库；MVP 不使用搜索模型或 AI 查询转换。
• 每条当前 AI 生成结果记录生成模型与版本。重新分析资产时原子替换该资产原有的 AI 内容，MVP 不保留 AI 分析历史。
• 用户手动填写或修改的内容优先，AI 重新分析永不覆盖人工内容。
• AI 内容与人工内容、文件提取元信息独立保存；主界面显示当前生效值并为 AI 值添加来源标记，编辑界面分别展示人工层与 AI 层。
• 用户可以对单项资产、当前选择、文件夹或整个资源库清空全部 AI 内容；批量清空需要确认。清空只移除 AI 内容及其资产标签关系，AI 创建的标签实体即使暂时无人使用也保留，交由用户自行清理。
• 用户可以在全局设置中选择生成语言（当前为单选）。
• AI 优先复用资源库中的已有标签以形成分类，但允许按设置创建新标签。
• AI 队列支持暂停、继续、取消和重试，并支持按文件或文件夹过滤分析范围。
• 资产分析遇到可重试的网络、限流、超时或部分无效响应时按可靠性策略重试；认证、权限、额度和不支持格式通常不自动重试。最终失败的任务显示原因并允许用户手动重试。
• AI 任务界面统计请求数、处理文件数和失败数，并限制视频抽帧数量与请求并发；MVP 不追踪供应商账户额度，也不维护价格表或估算费用。
• 视频分析抽取多帧并拼成带时间编号的联系表；当前上传给模型的是联系表，不上传原始视频。

来源信息

“源链接”特指浏览器扩展保存网页图片或视频时记录的用户所见网页地址，不保存媒体文件的直接地址，也不等于本地文件路径或云存储地址。Serpent 不创建只有 URL 的书签资产。

分发与开源

• 客户端采用 MIT 许可证。
• 依赖选型需要经过许可证兼容性检查；若依赖的许可证要求改变整体分发条件，应避免采用或单独重新决策。
• 浏览器扩展首发支持 Chromium 系浏览器。
• 桌面客户端采用 Electron 与 TypeScript，前后端主要贡献语言统一为 TypeScript/JavaScript。
• MVP 不收集匿名使用数据或崩溃遥测；以后若重新考虑，需要新的明确决策。

AI 交付阶段

MVP：

• 只连接云端 AI 模型。
• 用户填写并自行承担第三方模型 API Key 与费用。
• Serpent 不提供官方代理、账号额度或商业化 AI 服务。
• 内置 DashScope、OpenAI Chat Completions、OpenAI Responses、Anthropic Messages 和 Gemini Native 适配器；它们使用统一的 Serpent 内部请求与结构化输出协议，但分别处理各供应商 API 差异。

后续：

• 自动下载和管理推荐本地模型。
• 允许用户选择本地模型文件。
• 连接 Ollama 等本地模型服务。
• 继续支持用户 API Key；是否提供官方代理服务在商业化阶段再决定。

实现与原型验证项

• 视频抽帧间隔、最大帧数和联系表尺寸。
• NAS 与同步目录的数据库模式、风险提示和完整性校验。
• 悬停放大卡片的交互验证。

相关研究

• 创意资产的版本、同步、锁与审批：建议 MVP 推迟版本管理 UI，但底层预留稳定资产身份、不可变修订与冲突保全。
• Electron 后台任务架构调研：建议沙箱化 Renderer、精简 Main、单个 UtilityProcess 和按需 FFmpeg 子进程。
• 数据库与全文搜索技术调研：建议 better-sqlite3、SQLite FTS5、应用单实例、每库单连接和按存储位置切换 journal 模式。
• 媒体解析与预览技术栈：建议 Chromium 播放、LGPL-only FFmpeg、sharp、OpenImageIO 和 OpenColorIO。

访谈原则

采用批量问题收集信息，再针对冲突点追问。确认后的结论进入产品简报、术语表或 ADR；未确认内容保持为开放问题。