xianyu-hunter-hermes-skill/skill/xianyu-hunter-monitor/references/item-link-normalization-2026-05.md

Xianyu Item Link Normalization — 2026-05

Context

BOSS reported that generated Xianyu/Goofish candidate links were not reliably clickable from Feishu/mobile messages. Existing data often stored desktop links like:

https://www.goofish.com/item?id=<id>&categoryId=<category>

These can return HTTP 200 in curl but may not deep-link well from messaging clients. Mobile item links are more reliable for user-facing reports/notifications:

https://h5.m.goofish.com/item?id=<id>

Implemented pattern

Add/use lib/links.mjs:

• normalizeItemId(value) extracts item IDs from id, itemId, full item URLs, IM URLs, and raw text.
• buildItemLinks(itemOrId) returns desktop and mobile URLs.
• enrichItemLinks(item) preserves original URL in originalHref, stores desktop URL in webHref, mobile URL in mobileHref, and sets user-facing href to the mobile URL.

Integration points:

• lib/search.mjs: after scraping desktop card href/category, call enrichItemLinks(item) before returning results.
• lib/filter.mjs: after merging detail fields, call enrichItemLinks({ ...product, ...detail }) so fine-filtered candidates keep clickable mobile links.
• lib/task.mjs: normalize products during load/serialize/persist so existing data/tasks.json records become compatible without manual migration.
• lib/analyzer.mjs, lib/notifier.mjs, tools/hermes_report.mjs: use buildItemLinks(item).primaryUrl when rendering reports and notifications.

Verification commands

cd /Users/chick/.Hermes/workspace/research/xianyu-hunter
node --check lib/links.mjs && node --check lib/search.mjs && node --check lib/filter.mjs && node --check lib/task.mjs && node --check lib/analyzer.mjs && node --check lib/notifier.mjs && node --check tools/hermes_report.mjs

node --input-type=module - <<'NODE'
import { buildItemLinks, enrichItemLinks } from './lib/links.mjs';
console.log(buildItemLinks({ id: '1017096975429', href: 'https://www.goofish.com/item?id=1017096975429&categoryId=126856267' }));
console.log(enrichItemLinks({ href: '/item?id=1039232668094&categoryId=126856522' }));
NODE

node tools/hermes_report.mjs --task <task_id> --limit 3 --out /tmp/xianyu-link-test.md
sed -n '1,80p' /tmp/xianyu-link-test.md

Expected user-facing links in reports/notifications:

https://h5.m.goofish.com/item?id=<id>

Pitfall

Do not replace chatUrl with mobile item links. Seller chat still needs desktop IM URLs such as:

https://www.goofish.com/im?itemId=<id>&peerUserId=<sellerId>

Only user-facing product links should prefer h5 mobile URLs.