feat(skills): 技能详情页配置脚本必需的供应商环境变量,缺失时标记暂不可用并在调用时引导

[AlphaCatMeow]

背景

不少技能的脚本要调第三方供应商的 API(天气、翻译、图床、搜索等),运行前提是环境里有对应的 API Key 或账号配置。目前 SKILL.md 没有地方声明这类依赖:

• 用户装完技能就能启用,直到脚本真正跑起来才报错,报错还是脚本自己的原始输出,看不出缺什么、去哪配;
• 模型拿到失败结果后,可能反过来引导用户把密钥直接贴进聊天,既不安全也不好管理;
• 技能作者只能把"请先设置 XXX_API_KEY"写在正文里,靠用户自觉,没有任何界面支撑。

期望行为

1. 声明:技能在 SKILL.md frontmatter 里声明脚本必需的环境变量——变量名、供应商名称、用途说明、申请地址、是否可选。未声明的技能行为完全不变。
2. 详情页配置:技能详情抽屉新增「运行要求」区块,逐项展示变量状态(未配置 / 已填写 / 使用系统环境变量),支持 masked 填写,也支持一键"从系统环境变量读取"(检测到系统已有该变量时,存引用不落盘值)。
3. 可用性标记:必填变量未满足时,技能标记为「暂不可用」——卡片上出现提示徽标,注入模型的技能清单里也带上不可用标注和缺失项;不锁启用开关,不弹窗打断。
4. 调用时兜底:会话中模型读取该技能(SkillsManager action=read 或 /技能名 提及)时先做前置检查,不满足则返回结构化的"缺少必要环境变量"结果;聊天界面渲染引导卡片,询问用户「跳转技能详情页填写」或「读取系统环境变量」,配置完成后可直接重试。
5. 注入:用户填写的值在该技能启用的会话里注入 shell 工具的执行环境;"系统环境变量"模式下子进程本来就继承,不重复存值。

边界与安全

• 值在界面上始终 mask,错误信息做 redact(参照 stt 模块 secretFields 的做法);
• SkillsManager 的结果只回传"哪些变量缺失/已满足",不回传值本体;
• 返回给模型的文案明确指示:等待用户在界面配置,不要请求用户在聊天中粘贴密钥;
• 声明格式向后兼容,解析器忽略未知字段,其他工具读同一份 SKILL.md 不受影响。

涉及范围(初步)

• Rust 技能服务:frontmatter 解析、list/read 响应扩展、读取前置检查(crates/agent-gui/src-tauri/src/services/skills/);
• 前端共享层:SkillSummary 类型、SkillsSettings 存储、buildSkillsSystemPrompt 标注(crates/agent-ui/src/lib/skills/);
• Skills Hub:InstalledSkillCard 徽标、InstalledSkillPreviewDrawer 运行要求区块;
• 聊天:skillTools.ts 拦截、工具结果卡片与跳转交互;
• shell 执行:按会话注入技能环境变量;
• 双端:gateway webui 复用同一 Rust 后端(skills.manage 桥接)与共享组件,聊天侧引导卡片需要两端接入。

具体实现方案正在评审,定稿后补充到本 issue。

[AlphaCatMeow]

方案定稿(已经维护者评审),开始实现。

评审决策

1. 不引入新的 frontmatter 声明字段。对本机 89 个真实技能的扫描:0 个技能声明过环境变量,frontmatter 在用字段只有 name / description / disable-model-invocation / argument-hint / version / metadata / license / allowed-tools。依赖识别以自动探测为主;生态已有的 metadata 自由字段里约定 metadata.env 作为可选覆盖,不发明顶层字段。
2. 未配置禁止启用(硬门禁),配合误报豁免与手动补充,避免探测误差把技能锁死。
3. 系统环境变量现场探测、自动计入满足,不设确认步骤;详情页展示来源。
4. 值存 settings + shell spawn 注入,不写入技能脚本。写脚本的四个问题:升级覆盖丢值;密钥进入模型可读的 skill:// 区(系统提示词允许 Read/Write/Edit);action=package 会把密钥打进可分享的 .skill 包;值写入后环境读取语句消失,探测器失去"需要且已配置"的判定依据。settings 通道与供应商 apiKey 同水位:界面 mask、报错 redact、*Configured 遮蔽。
5. Tauri GUI 与 gateway webui 同步全量。

探测规则(精度优先于召回)

误检会把无辜技能锁死在"禁止启用";漏检只是维持现状(脚本运行时报原始错误)。规则从严:

• 强信号(计入必需):脚本文件(.py/.sh/.ps1/.js/…)中的显式环境读取——os.environ["X"] / os.getenv("X") 无默认值、process.env.X、$env:X、shell 的 ${X:?}——且变量名为凭据形状(*_API_KEY / *_KEY / *_TOKEN / *_SECRET / *_PASSWORD 等后缀)。
• 弱信号(仅提示,可一键升级为必需):SKILL.md 代码块中的引用(示例代码高发区,实测 tdd 等教学类技能的 STRIPE_SECRET_KEY 即在此列)、带默认值的读取(${X:-d}、get("X", d))、非凭据形状的环境读取。
• 否决表:系统与运行时变量(PATH / HOME / LASTEXITCODE / 颜色码 / SKILL_* / ARGUMENTS / …)。
• 覆盖链:用户标记(误报豁免 / 弱信号升级 / 手动添加)> metadata.env 声明 > 探测。
• 探测在 Rust 技能服务完成,按目录签名缓存;新增 skills.manage 动作 env_status 供双端查询系统变量满足状态。

交互

• 卡片:「待配置」徽标;必需项未满足时启用开关置灰,点击置灰开关直接打开详情抽屉并定位到配置区块。
• 抽屉「运行要求」区块:必需项(状态、来源、masked 输入、从系统读取、标记误报)+ 折叠的弱信号列表(标记为必需)+ 手动添加变量。
• 已启用技能事后失去满足(升级新增必需项 / 系统变量消失 / 清空值):选中状态保留,开关显示关闭态 + 待配置徽标,从系统提示词注入中剔除,修复后自动恢复启用。
• 调用兜底:SkillsManager(action="read") 前置检查,失败返回 details.kind="skill_env_missing",聊天渲染引导卡片——「去技能详情页填写」(跳转 + 抽屉定位)/「读取系统环境变量」(现场重探,成功给出"已配置,继续"快捷回复);模型侧文案明确禁止引导用户在聊天中粘贴密钥。
• 批量启用跳过未满足项并提示数量;模型会话内安装技能的自动启用路径同样过门禁。

实施分块

1. Rust 探测引擎 + SkillSummary.envRequirements + env_status 动作 + 目录签名缓存;
2. SkillsSettings.env 存储与 normalize + 覆盖(升级 / 误报 / 手动添加)模型;
3. 抽屉「运行要求」区块 + 卡片徽标 + 启用门禁交互;
4. 系统提示词生效过滤与 drift 标注 + read 拦截 + 聊天引导卡 + 双端跳转;
5. shell / cron spawn 注入 + redact;
6. settings sync 遮蔽 + i18n(zh/en)+ 测试(以本机 89 技能语料做探测规则回归样本)。

[AlphaCatMeow]

实现完成，PR：#586。

验收阶段的方案修订（相对上一条定稿评论）

桌面端试用后确认：脚本扫描判断依赖不够准确，不能当权威。据此把「探测驱动硬门禁」修订为「恒定手动入口 + 探测仅建议」：

1. 恒定入口：每个技能的详情抽屉恒显「运行要求」区块（与探测结果无关），卡片 hover 提供 Key 图标直达；用户主动配置，或技能调用失败后循入口补配。
2. 探测降级为建议：扫描结果（不再区分强/弱对待）收进「检测到的可能依赖」折叠组，每条一键「采纳」；不自动计入必需、不驱动门禁。Rust 引擎与 env_status 动作保留，仅供建议数据与现场探测。
3. 门禁只认明确来源：metadata.env 声明必填 + 用户标记/采纳的变量；未满足时才显示「待配置」徽标并拦截启用。
4. 批量添加：手动入口支持 NAME / NAME=值，多行 .env 粘贴一次导入（容忍 export 前缀、# 注释、引号包裹，去重跳过非法名）。
5. 调用拦截、聊天引导卡、注入、同步脱敏、双端接线不变，只是"谁算必需"的判定源收窄。

另附独立修复：@svgr/core / @svgr/plugin-jsx 提升至根 devDependencies（pnpm 隔离下 unplugin-icons 经 local-pkg 懒加载解析失败，TS7 升级后全新检出首次 dev 即触发），详见 PR 首个 commit。