Filtmall-Shopping-Skill源码解读：filtalgo.js CLI包装器的命令路由与15分钟推荐状态生命周期

【免费下载链接】Filtmall-Shopping-SkillAgent-native shopping for extreme value: verifiable same-product price evidence, checkout, orders, delivery, and after-sales.项目地址: https://gitcode.com/gh_mirrors/fi/Filtmall-Shopping-Skill

Filtmall-Shopping-Skill 是筛电（Filtalgo）官方购物 Skill，让 AI 智能体能够实时搜索商品、给出同款同规格比价证据，并完成结算、订单、物流与售后。它的入口文件 scripts/filtalgo.js 是一个约 300 行的「CLI 包装器」：一方面把用户输入的命令路由到不同处理分支，另一方面用「15 分钟过期的临时文件」管理推荐流程的中间状态。本文结合源码讲清这两件事。

🧭 包装器是干什么的

智能体不会直接调用打包后的 assets/filtalgo-cli.cjs，而是统一执行：

node scripts/filtalgo.js <command> --json

包装器在透传命令之前，会做四类额外的事：拦截recommend两阶段推荐命令、为search命令附加需求画像与结构化搜索、绑定商品详情链接、以及把关键流程的结果落盘为「状态文件」。理解它的命令路由，就能看懂整个购物流程如何被串起来。

🚦 命令路由：filtalgo.js 的 4 条分支

路由逻辑没有用复杂的解析库，而是按「第一个参数 + 特殊标志位」的顺序做 if 判断，从上到下依次是：

分支一：recommend 两阶段推荐（最优先）

只要第一个参数是recommend，就进入专用分支（见 scripts/filtalgo.js），支持三个动作：

这三个动作全部以「读取标准输入里的单个 JSON」作为模型输出通道，校验逻辑集中在 scripts/recommendation-two-stage.js。动作名不在白名单内时直接报错退出，这就是包装器最严格的一条路由。

分支二：--agent-response智能体响应模式

携带--agent-response标志时，包装器会把子进程的输出「接住」再加工（见 scripts/filtalgo.js）：

• search 命令：若未显式提供--filters等参数，先走结构化搜索管线 scripts/structured-search.js——把自然语言需求拆成类目适配器、硬预算过滤和排序偏好，再合并商品目录补齐字段；然后把搜索结果存为状态，返回search_ref和下一条要执行的prepare_command。
• checkout prepare-payment / order list：由 scripts/transaction-response.js 把原始数据渲染成订单卡片、待支付列表和「去支付」入口。
• 其他命令：直接报「--agent-response目前只用于 search、checkout prepare-payment 和 order list 命令」。

如果还带--request-profile-stdin，会先从标准输入读入需求画像（预算、肤质、功效等），并做字段白名单和敏感信息校验，详见 references/product-search.md。

分支三：--product-ref商品链接回查

当命令是search-tools lookup --product-ref <详情链接>时，包装器会先校验链接必须来自filtalgo.com的商品详情页并提取 SPU/SKU，再把参数改写为--ids <skuId>发起查询，最后用 bindProductRefLookup 把返回结果中所有 URL 统一「钉回」用户给出的那条原始链接，防止多轮对话中链接漂移。

分支四：兜底透传

以上都不命中时，包装器用spawnSync原样把参数转发给打包 CLI（见 scripts/filtalgo.js），auth、cart、order、logistics等命令都走这条路径，输出直接继承父进程的标准流。

⏱️ 15 分钟推荐状态生命周期

推荐流程跨多次命令调用（search → prepare → finalize → detail），中间结果不能塞进命令行参数，于是包装器用「系统临时目录 + 一次性 JSON 文件」来承载状态。

状态文件在哪里

const stateDirectory = path.join(os.tmpdir(), 'filtmall-shopping-recommendations'); const stateLifetimeMs = 15 * 60 * 1000;

（摘自 scripts/filtalgo.js）

每次写入都生成一个 UUID 作为 token：storeState创建目录（权限 0700）、写入文件（权限 0600、wx独占创建），返回 token（见 scripts/filtalgo.js）。智能体后续命令拿这个 token 就能取回状态。

读取即校验：过期即删除

loadState每次读取都检查文件修改时间：超过 15 分钟就删掉文件并抛出「推荐上下文已过期，请重新搜索」（见 scripts/filtalgo.js）。同时，任何一次新状态写入前，cleanupExpiredStates会顺带清扫目录里所有过期的 15 分钟旧文件，保证临时目录不会无限膨胀。

状态机：两个阶段 + 一次续命

有一个精巧细节：detail回查执行后会调用fs.utimesSync把文件修改时间刷新为当前时间（见 scripts/filtalgo.js）。也就是说，用户连续追问「第 2 款详情」「第 3 款呢」时，状态窗口随之续命；一旦 15 分钟没有任何后续命令，文件自然过期清理。整个窗口的设计意图是：一次推荐会话通常几分钟内完成，过期状态里的价格、库存已不可信，不如强制重新搜索。

每次路由切换的「接力棒」就是响应里的命令字符串：search 返回prepare_command，prepare 返回finalize_command，finalize 返回selection_command，智能体照着执行即可，无需自己拼接参数。

📌 小结

• 命令路由：recommend专用分支 →--agent-response加工分支 →--product-ref链接绑定分支 → 兜底透传，四层判断覆盖了「推荐决策、智能体响应、链接回查、普通命令」四类场景。
• 状态生命周期：15 分钟 UUID 临时文件串联 search/prepare/finalize/detail，读时校验过期、写时顺手清理，detail可续命，形成有界的推荐会话窗口。
• 安全设计：状态目录 0700、文件 0600、token 正则校验、链接域名白名单，细节见 SKILL.md 的全局安全约束。

读懂这个约 300 行的包装器，就掌握了 Filtmall-Shopping-Skill「模型做语义、代码做校验」的核心架构入口。

【免费下载链接】Filtmall-Shopping-SkillAgent-native shopping for extreme value: verifiable same-product price evidence, checkout, orders, delivery, and after-sales.项目地址: https://gitcode.com/gh_mirrors/fi/Filtmall-Shopping-Skill