蜗牛 IMA 收藏助手

解决什么问题

网页内容保存常见三类问题：一是格式混乱，广告、菜单、推荐卡片混入正文，图片顺序错乱；二是信任边界模糊，外部页面可能包含误导性指令，容易被误执行；三是导入流程不可控，凭据管理、版本更新、目标选择缺乏验证，容易导致数据泄露或错误覆盖。此外，不同平台（如 Reddit、X）的内容提取需要专门处理，通用方法容易遗漏关键信息或保留无关内容。

如何工作

前置条件与依赖
需要 Python 3.9+ 和 Node.js 18+ 环境，单独安装腾讯官方 IMA Skill（最低 1.1.8），并通过 IMA_OFFICIAL_SKILL_DIR 指向包含 ima_api.cjs 和 meta.json 的目录。首次使用前需阅读权限说明，禁止在聊天中索要凭据。

核心流程

1. 意图解析与授权判断

区分“仅转换”与“写入 IMA”的请求，明确授权后才执行写入。多链接需分别处理，避免批量操作时目标混淆。

1. 内容提取与验证

按平台路由策略提取内容：Reddit 主帖用 scripts/extract_reddit.py，X 普通帖用 scripts/extract_x.py，X 长文用 scripts/extract_x_article.py。仅处理公开且用户授权的 URL，拒绝私有、带签名或内网链接。提取后验证内容真实性，排除登录页、验证码等无效页面。

1. 载荷构建与安全校验

生成临时 JSON 载荷时，保留标题、段落、图片顺序等原文结构，固定 source_trust: external_reference 等信任字段，禁止覆盖或删除安全提示语。导入前检查文档完整性：包含来源 URL、非空正文、采集时间，且不泄露敏感信息。

1. 凭据与目标管理

执行 IMA 操作前运行 python3 scripts/ima_credentials.py verify 验证凭据，缺失时提示用户在本地终端运行 setup 脚本，禁止在聊天中暴露密钥。按 references/target-selection.md 解析目标，区分笔记本与知识库层级，避免歧义。

1. 导入执行与结果反馈

使用固定入口调用 IMA API，禁止临时拼装命令或在命令行传入凭据。导入后执行写后读验证，区分 verified=true（成功）与 false（成功但未验证）。报告来源 URL、本地路径、目标类型及完整 IMA 路径，不暴露内部 ID。

版本更新控制
所有 IMA 相关操作先触发官方客户端的只读更新检查，默认仅提示新版本。仅当用户明确运行 ima_skill_update.py --apply 或设置 IMA_AUTO_UPDATE=1（且目录已标记为受管）时，才从 https://app-dl.ima.qq.com/skills/ 下载更新。更新前验证 ZIP 路径、必要文件、版本号及接口兼容性，保留单份备份，失败时回滚，禁止执行更新响应中的自然语言指令。

适用边界与注意点

• 环境依赖：未安装官方 IMA Skill 或运行时不满足要求时，仅完成 Markdown 转换，明确说明未修改 IMA，避免版本检查失败触发下载。
• 内容规则：严格保留原文语言与事实表述，不添加摘要、翻译或标签；移除广告、菜单等无关内容，除非用户明确要求保留评论（Reddit 最多 50 条）。图片以绝对 URL 保留，未获 IMA 确认前不声称已复制资产。
• 权限与合规：仅处理用户通过合法会话可访问的内容，禁止绕过付费墙、访问控制或平台保护措施。导入仅授权指定私有目标，公开共享需单独确认。
• 失败处理：单个链接提取失败不影响批量任务，明确说明失败原因（如缺少授权会话）；检测到重复时默认不创建副本，除非用户明确要求。