mini-openclaw-v2/docs/v2/20-skill-folder-prototype.md

Skills 文件夹导入与标准文件视图（原型增量）

2026-10-01。范围：当前Superdesign三模块原型，不修改生产前后端。继承上一轮原型的模拟、权限与概率边界，走原型增量轻量路径；生产文件系统服务仍待契约与授权设计。

需求与验收

• BR-56 Skill卡片是技能包的索引。每个技能包以目录内的 SKILL.md 为入口；YAML frontmatter包含 name / description，正文是Markdown。可附带references/scripts/assets，但不创建空占位目录。
• BR-57 支持选择一个技能目录或包含多个技能目录的父目录；先发现与校验，再选择确认导入。缺失入口、错误frontmatter、名称与目录不匹配、重复技能名均明确提示，不静默覆盖。
• BR-58 人工文件夹导入保留蓝色人工来源及「文件夹导入」子类型；AI提炼保留红色来源。进入卡片池默认待审核草稿，不自动执行脚本或提升工具权限。
• BR-59 每张Skill卡均可打开技能文件视图，展示相对目录树与原始 SKILL.md；导入文件保留原文，不将摘要冒充原文件。AI与人工生成的演示Skill也有标准文件包。
• BR-60 网页文件视图、保存/导出文件包和打开系统资源管理器分别标注能力。原型未接本地文件管理服务，不伪称已打开Windows目录；正式版通过授权本地适配器定位受管目录，不接受任意路径作为终端命令。

异常	原型错误码	文案与行为
E-32	SKILL_PACKAGE_INVALID	找不到SKILL.md或格式不符合要求；列出具体原因，禁止导入该包
E-33	SKILL_NAME_DUPLICATE	技能名已存在，需另行管理版本；不覆盖原卡片
E-34	SKILL_FOLDER_READ_FAILED	无法读取所选文件夹或超过限制；保留原卡片
E-35	SKILL_SYSTEM_FOLDER_UNAVAILABLE	网页原型未接本地文件管理器；使用文件视图或导出技能包

验收	Given / When / Then
AC-64	Given 一个有效Skill目录，When 选择文件夹，Then 展示名称、描述、相对树与校验结果，确认前不新增卡片
AC-65	Given 多包父目录含无效/重复包，When 预览并确认，Then 仅导入用户勾选的有效包，其他包显示原因且不覆盖
AC-66	Given 文件夹导入，When 入池，Then 人工来源蓝色、文件夹来源文本、待审核草稿；没有执行脚本或模型调用
AC-67	Given 任一Skill卡，When 打开技能文件夹，Then 有SKILL.md原文与文件树；导入原文不被改写，已有包可导出
AC-68	Given 已导出的演示包，When 解压并验证，Then 目录名匹配frontmatter.name，name/description有效，引用文件实际存在
AC-69	Given 网页原型，When 请求打开系统目录，Then 显示能力边界，不宣称已打开电脑目录；取消选择不改变原集合

详细设计与UI

新增Skill卡片字段：skillPackage = { name, description, directory, files:[{path, text?, browserFile?}], imported }。这是原型内存结构，不是生产API。来源字段、状态及执行白名单保持独立。

卡片池Skills页签新增「从文件夹添加」。流程：未选择 → 浏览器选择目录 → 读取/校验 → 有效/部分无效/空/错误 → 勾选预览 → 确认导入 → 草稿入池。取消操作不改变已有数据，解析时禁用重复导入。

打开技能文件夹：宽屏双栏（左目录树，右原文件），窄屏上下排列。支持逐文件查看、返回卡片详情、导出技能包；文本用转义的纯文本显示，不运行HTML、脚本或Markdown内指令。网页不获取绝对路径；来源只记录浏览器提供的相对目录。

浏览器选择目录使用 webkitdirectory + webkitRelativePath。最多500个文件、20MiB合计、入口1MiB；脚本只预览，不执行。YAML用受限schema解析，不把frontmatter权限字段作为平台授权。样例均为自编对公租赁演示内容。

标准依据：Agent Skills规范；目录选择依据：MDN相对目录路径。格式通过不代表Skill业务正确、安全审核完成或已投入运行。

交付状态

此增量制作标准示例目录、可点击原型及逻辑检查。数据库存储、真实知识发布、miniOpenClaw运行加载与Windows文件管理器集成不在原型中完成；本次未改生产服务。

已交付与验证证据

• 交互预览同一草稿第3版；云端回读与本地HTML一致。第2版及恢复副本保留。
• 路径：历史经验加工 → 经验卡片池 → Skills → 从文件夹添加 → 选择目录 → 预览 → 确认导入。点击任一Skill的「打开技能文件夹」可查看原始文件。
• 可直接导入的示例SKILL.md：选择 docs/v2/prototypes/skill-import-example 父目录或其中的单个Skill目录，即可预览并添加一个新技能。另有基线入口文件及同级4个完整包，其名称已在基线卡片池中，重复导入会明确拒绝覆盖。
• 文件夹检查包含30组逻辑检查（15组既有回归与15组增量）；覆盖原文、YAML、多包/重复、确认前不入池、草稿、取消读取与ZIP实际字节。Node VM与文件列表fixture，不是系统文件选择器或浏览器E2E。
• 4个基线示例目录及1个新增导入示例通过skill-creator提供的格式校验；ZIP用Python标准库解包、CRC与逐文件字节比较通过，导入样例CRLF原文保留。
• 按项目虚拟环境运行统一验证，9项全部通过：test-evidence/20261001-120815-7080729/REPORT.md。统一检查证明原仓基线，不证明新版生产功能实现。
• 完整增量证据：test-evidence/20261001-skill-folder-prototype/。浏览器自动验收和独立视觉审核仍未完成；本机浏览器连接此前因执行环境失败，未据逻辑测试推断UI验收通过。
• YAML解析器使用仓库现成js-yaml 4.3.2，连同MIT许可内嵌原型，目录导入无需再加载解析器CDN；它是格式解析器，不代表技能安全审核器。

网页「在系统文件夹打开」目前提示 E-35，不会执行资源管理器命令。可用「导出标准技能包」下载ZIP、解压后打开目录；标准目录与源文件均已提供。真实本地文件管理器能力须在后续生产实施阶段接入。