filtalgo/Filtmall-Shopping-Skill

Filtmall Shopping Skill – 에이전트 네이티브 이커머스

개요

• AI 에이전트(예: OpenAI 호환 에이전트)가 Filtmall 마켓플레이스에서 실제 제품을 탐색, 비교, 구매할 수 있도록 하는 Node.js 기반 skill 입니다.
• "에이전트 네이티브" 사용을 위해 설계되었습니다. 이 스킬은 LLM이 추론하고 발견, 결제, 사후 관리 전반에 걸쳐 대화 컨텍스트를 유지할 수 있도록 구조화된 데이터(가격, 사양, 재고, 타임스탬프)를 반환합니다.

주요 기능

단계	스킬의 역할
발견	자연어 요청(예: "100위안 이하의 보습 페이셜 마스크")을 Filtmall 카탈로그의 실시간 제품 후보로 변환합니다.
결정	가격, 사양, 재고의 병렬 비교를 제공하며, 공개 마켓플레이스의 동일 사양 가격과 비교하여 절약 비율을 보여줍니다.
구매	아이템을 지속적인 장바구니에 추가하거나 CLI 명령을 통해 단일 SKU의 BUY_NOW 흐름을 실행합니다.
결제	사용자가 브라우저에서 열어 결제를 완료할 수 있는 구매자용 결제 링크(데스크톱 웹 또는 모바일 H5)를 생성합니다.
사후 관리	에이전트가 주문 조회, 배송 추적, 주소 관리, 대상 주문 취소 및 사후 관리 워크플로우를 시작할 수 있도록 합니다.

작동 방식

• 에이전트는 단일 CLI 진입점 (node scripts/filtalgo.js <command> --json)을 호출합니다.
• CLI는 Filtmall의 백엔드 서비스(카탈로그, 장바구니, 결제, 주문, 물류)와 통신하여 JSON 결과를 반환합니다.
• 스킬 패키지에는 CLI 런타임, 에이전트 측 지침 파일 (SKILL.md, agents/openai.yaml) 및 skills.sh 마켓플레이스용 메타데이터가 포함되어 있습니다.

설치

# skills.sh 생태계를 통한 원라인 설치
npx skills add filtalgo/Filtmall-Shopping-Skill --skill filtmall-shopping -g

• Node.js 18+가 필요합니다.
• 리포지토리에 CLI 런타임이 번들로 제공되므로 별도의 npm install은 필요하지 않습니다.

일반적인 에이전트 프롬프트

• 발견: "100위안 이하의 끈적이지 않는 보습 페이셜 마스크가 필요해."
• 결정: "첫 번째와 세 번째 제품을 비교해서 어떤 것이 민감한 피부에 더 적합한지 설명해줘."
• 거래: "결제가 완료되었니?" / "최근 주문은 어디에 있니?"

안전 및 사용자 제어

• 이 스킬은 사용자의 명시적인 요청 없이는 결제나 계정 변경을 수행하지 않습니다.
• 모든 자격 증명, 장치 코드 및 토큰은 비공개로 유지됩니다.
• 에이전트는 사용자가 브라우저에서 열 수 있도록 URL(결제, 주문 상세, 사후 관리)을 제시해야 합니다.
• 건강 관련 불만(예: 알레르기 반응)의 경우, 스킬은 흐름을 중단하고 전문적인 치료를 권장합니다.

개발자 퀵스타트

# 런타임 확인 및 라이브 카탈로그 검색
node scripts/filtalgo.js doctor --json
node scripts/filtalgo.js search "想要保湿一点的面膜，预算 100 元以内，但别太黏" --json

# 인증된 작업을 위한 OAuth 장치 흐름
node scripts/filtalgo.js auth login
node scripts/filtalgo.js auth status --json

# 장바구니 및 결제 예시
node scripts/filtalgo.js cart add-item --way CART --sku-id <sku_id> --quantity 1 --json
node scripts/filtalgo.js checkout create --way CART --json
node scripts/filtalgo.js checkout prepare-payment <checkout_session_id> --link-channel mobile_h5 --json

# 주문 및 물류 조회
node scripts/filtalgo.js order list --page-size 5 --json
node scripts/filtalgo.js logistics get <order_sn> --json

기술 스택

• 런타임: Node.js 18+ (번들된 CLI 런타임 assets/filtalgo-cli.cjs)。
• 인터페이스: JSON 인코딩 명령을 노출하는 명령줄 래퍼 (scripts/filtalgo.js)。
• 에이전트 통합: skills.sh 형식을 지원하는 플랫폼에서 스킬을 검색 가능하게 하는 메타데이터 파일 (SKILL.md, agents/openai.yaml)。

리포지토리 구조

SKILL.md                # 에이전트 지침 및 트리거 메타데이터
references/            # 선택적 워크플로우 규칙 파일
scripts/filtalgo.js    # 경량 CLI 래퍼 (진입점)
assets/filtalgo-cli.cjs# 번들된 CLI 런타임
agents/openai.yaml     # OpenAI 호환 스킬 설명
skills.sh.json         # skills.sh 마켓플레이스 메타데이터
CHANGELOG.md           # 릴리스 노트
README.*               # 문서 (EN & CN)

사용 대상

• 대화를 떠나지 않고 사용자가 뷰티/퍼스널 케어 제품을 구매할 수 있도록 해야 하는 AI 어시스턴트 제품을 구축하는 개발자.
• 중국 시장 이커머스 카탈로그를 LLM 기반 챗봇에 통합하려는 기업.
• 라이브 커머스를 포함한 엔드 투 엔드 에이전트 워크플로우를 연구하는 연구원.

제한 사항

• 카탈로그는 현재 뷰티 및 퍼스널 케어 제품에 중점을 두고 있으며, 더 광범위한 카테고리는 아직 다루지 않습니다.
• 결제 및 계정 작업은 사용자가 브라우저 링크를 열어야 합니다. 스킬은 자격 증명을 직접 처리하지 않습니다.
• 가격 우위 주장은 Filtmall의 실시간 데이터에 의존하며 지역, 멤버십 등급 및 프로모션에 따라 다를 수 있습니다.

---

결론: Filtmall Shopping Skill은 AI 에이전트가 Filtmall 플랫폼의 실시간 데이터를 사용하여 제품 발견, 비교, 결제 및 구매 후 지원이라는 전체 이커머스 흐름을 수행할 수 있도록 하는 구체적이고 프로덕션 준비가 완료된 구성 요소입니다. 모든 기능은 에이전트가 JSON 명령으로 호출할 수 있는 간단한 Node.js CLI로 래핑되어 있습니다.