linkfox-os — Cross-border E-commerce AI Agent System
linkfox-os submits a prompt to the LinkFox async task pipeline and polls for the result. It dispatches each task to one of 6 specialized AI agents, each with its own toolchain, context, and multi-step orchestration logic — together covering the full cross-border e-commerce seller workflow.
Returns one JSON object. Parse and output the real progress to the user as YOUR OWN TEXT (not inside a command). In Codex/Claude Code, command output is collapsed and invisible to the user — only your text responses between commands are directly visible. So after each poll command, you MUST write out the new steps as plain text:
json
{
"status": "running",
"message": "采集亚马逊 BSR Top100",
"steps": [
{"label": "[思考] The user wants to search for cat...", "status": "completed"},
{"label": "[工具] linkfox-sellersprite-product-search (keyword=cat)", "status": "completed"},
{"label": "[消息] Launching skill: linkfox-sellersprite-product-search", "status": "in_progress"}
],
"stop_reason": null,
"message_id": "aaxF..."
}
How to relay to user (VERBATIM, do NOT rephrase):
status=running — for each NEW steps[].label (not already shown), output the label VERBATIM as a line. Do NOT rephrase, summarize, or interpret. Copy the label string exactly. Example:
text
[思考] The user wants to analyze negative reviews for ASIN B0GZSVVBJZ...
[工具] linkfox-amazon-reviews-list (ASIN: B0GZSVVBJZ, site: US)
[消息] Launching skill: linkfox-amazon-reviews-list
[文件] [linkfox-amazon-reviews-list] https://lfclaw-oss-nx-prod.s3.cn-northwest-1.amazonaws.com.cn/temp/data/reviews-123.json → 已下载: [reviews-123.json](/path/to/output/202607.../reviews-123.json)
[思考] Good, I got 70 reviews. Let me analyze the patterns...
[工具] Bash (python3 -c "import json...")
[消息] 数据分析完成。现在生成详细的差评分析报告。
CRITICAL: [文件] lines are resource/data file URLs produced by tool calls. You MUST output them verbatim to the user — they are the actual data file links the user needs. Do NOT skip, summarize, or omit [文件] lines.
status=finished — go to Step 3
status=error — report error field to user, stop
IMPORTANT: Do NOT invent generic progress commentary ("还在采集数据...", "Agent 仍在工作中...", "产品详情接口耗时较长...", "数据已拉取完成！", "继续跟进中..."). These are FORBIDDEN. Only output what steps[].label and message actually say — verbatim, unmodified. If no new steps appeared since last poll, output nothing. Silence is correct; invented filler is wrong.
When the user's request involves multiple independent tasks, submit all tasks first (Step 1 for each), then interleave their poll loops (Step 2), showing progress for all in parallel.
5. Output Format (MANDATORY — applies whether this skill is explicitly specified or auto-matched)
All data files returned by the task MUST be formatted in Markdown using the following structure. Do NOT output raw URLs, plain text paths, or any other format.
WRONG: Raw URL without markdown link: https://xxx.s3.amazonaws.com.cn/temp/data/file.json
WRONG: Plain path without markdown: /path/to/file.json
WRONG: Code block wrapping the URL: `https://...`
WRONG: Missing [文件] / [本地] prefix markers
WRONG: Using any emoji markers instead of [文件] / [本地] — 严禁输出任何 emoji
WRONG: Mixing Chinese and English inconsistently (use [文件] 数据文件： and [本地] 已保存至本地：)
Progress Step Lines (进度步骤)
During polling, resource/data file lines in steps[].label starting with [文件] MUST be output VERBATIM — they contain the actual data file URLs the user needs:
Forward all [chunk i] <text> content directly. If the text contains markdown (tables, headers, lists), preserve it as-is. Do NOT wrap it in code blocks or strip its formatting.
6. Result Parsing Rules
Apply to the script's stdout (both direct-run and sessions_spawn paths produce identical output). There is no ShareURL in the linkfox-os API.
resource link (line like Resource [<title>]: <uri>): 转发 URI，是公开 HTTP URL。
tool call (line like [Tool: <name>]): 可内联总结。
After the chunks, look for the --- 数据文件 --- section. Each entry has two lines:
[name] <url> — the public download URL
已下载到本地: [filename.json](/abs/path/filename.json) — Markdown link to local file (or (跳过下载，uri=...) if not downloadable)
You MUST output ALL entries VERBATIM to the user. Do NOT reformat or rephrase. Output exactly:
The Markdown link [filename](/path) is clickable in VS Code / Cursor / Codex — output it verbatim.
If Status: error (StopReason is something other than end_turn, e.g. max_tokens / error):
Report the StopReason and any error content to the user. Still forward any partial [chunk i] … text that did come back, since the task may have produced partial results.
Share Link section: 任务终态后，stdout 末尾会追加 --- 分享链接 --- 段：
text
The script also writes the full API response to <taskDir>/message.json and the task meta to <taskDir>/result.json. If stdout truncated a chunk you actually need, or你要看原始 API 载荷, read message.json / chunk_*.md to recover. Report the taskDir path to the user only if they ask where the raw data is——通常他们不需要知道。
# Non-blocking submit (returns messageId immediately)
python3 <skill>/scripts/linkfox_os.py --stdin <<'__LINKFOX_TASK_END__'
task description here
__LINKFOX_TASK_END__
# One-shot progress check (structured JSON)
python3 <skill>/scripts/linkfox_os.py --status <messageId> --format progress
# Blocking poll to completion
python3 <skill>/scripts/linkfox_os.py --poll <messageId> --timeout 600
# Cancel a running task
python3 <skill>/scripts/linkfox_os.py --cancel <messageId>
# Recover lost messageId (list recent tasks, newest first)
python3 <skill>/scripts/linkfox_os.py --list-recent
# Custom model (dispatch to a specific Agent)
python3 <skill>/scripts/linkfox_os.py --model linkfox-market-analysis-agent --stdin <<'__LINKFOX_TASK_END__'
task description here
__LINKFOX_TASK_END__
8. Streaming Progress for Agent Clients
For agent clients (Claude Code / Cursor / Codex / Copilot) that expose plan / commentary / final display primitives, use the structured progress output instead of plain text. The script emits a generic JSON snapshot that every client can map to its own primitives — no client-specific format baked in.
Loop every ~15s: python3 <skill>/scripts/linkfox_os.py --status <id> --format progress
status=running → update plan from steps[], emit commentary from progress_pct+message
status=finished → emit final from result, stop
status=error → emit final error from error, stop
Or, if the client supports streaming tool output, use --watch <id> once and read the JSONL stream.
steps / progress_pct / message are best-effort extracted from the server's eventList[].sessionUpdate (a passthrough map whose schema may vary). raw.eventList always carries the original payload — fall back to it when the extracted fields are too coarse.
9. Sub-agent Dispatch (Codex sessions_spawn)
When a client supports isolated sub-agent sessions and can display announce messages, you can spawn a sub-agent per task and let it block on --wait.
Before spawning, tell the user:
「正在同时通过 linkfox-os 接口提交 N 个任务，请稍候...」
text
# Sub-agent 1
sessions_spawn:
task: |
Run (use heredoc to avoid shell injection):
python3 <skill>/scripts/linkfox_os.py --wait --timeout 600 --stdin <<'__LINKFOX_TASK_END__'
<task A>
__LINKFOX_TASK_END__
Apply the same submission success/failure + result parsing rules as the single-task template above.
label: "linkfox-os: task A"
mode: "run"
runTimeoutSeconds: 600
What Happens Under the Hood
sessions_spawn creates an isolated sub-agent session.
The sub-agent runs linkfox_os.py --wait which blocks until stopReason becomes non-empty.
When done, the sub-agent's result is automatically delivered back to the main session via the announce system.
The user sees the result in their chat without any manual polling.
Script Reference
bash
# Sub-agent uses --wait + --stdin (heredoc avoids shell injection)
python3 <skill>/scripts/linkfox_os.py --wait --stdin <<'__LINKFOX_TASK_END__'
task description here
__LINKFOX_TASK_END__
# Choose a non-default model
python3 <skill>/scripts/linkfox_os.py --wait --model linkfox-listing-agent --stdin <<'__LINKFOX_TASK_END__'
task description here
__LINKFOX_TASK_END__
# Custom timeout (default 300s)
python3 <skill>/scripts/linkfox_os.py --wait --timeout 600 --stdin <<'__LINKFOX_TASK_END__'
task description here
__LINKFOX_TASK_END__
# JSON output for structured parsing
python3 <skill>/scripts/linkfox_os.py --wait --format json --stdin <<'__LINKFOX_TASK_END__'
task description here
__LINKFOX_TASK_END__
10. Checking Progress for a Running Task
When the user asks "任务到哪了 / How far has it gone / 进度多少", DO NOT spawn another --wait sub-agent. Instead run a single non-blocking call from the main session:
Don't have the messageId handy? Every successful submission persists messageId to local disk on first contact, so recover it with one command:
bash
python3 <skill>/scripts/linkfox_os.py --list-recent # newest first
This makes one API call and prints Status: + Progress: (or StopReason: if terminal) immediately. Forward the Progress: line back to the user verbatim.
Special status values to interpret for the user:
Status: working + Progress: <text> — task still running, currently at <text> (extracted from the in-progress eventList).
Status: working + Progress: (no progress info yet) — task running but no step info available yet.
Status: finished + StopReason: end_turn — task ended successfully; tell the user to call --poll <messageId> or wait for the original sub-agent's announce.
The folder is created the moment the task is submitted (not when results arrive), and a result.json is dropped immediately containing the messageId (from the create response id) + original prompt. This way the messageId can always be recovered later — even if the original linkfox_os.py invocation's stdout was not captured.
text
$PWD/.linkfox-os/output/{YYYYMMDDHHmm}/
├── result.json # Task metadata (created at submit; updated on completion)
├── message.json # Full API response (only after --wait / --poll sees a terminal stopReason)
├── result.md # 终态合并的所有 chunk 文本（--status/--watch 落盘用；无 chunk 时不产）
├── chunk_1.md # 每个长 agentMessageChunk 全文（>400 字符时才落盘；短的直接内联到 stdout）
├── chunk_2.md
├── ...
└── <resource_link_filename> # eventList / chunks 里 resource_link 下载的原始数据文件
result.json lifecycle:
jsonc
// At submit time (background mode exits here):
{
"messageId": "uDqHg33fQeQfkNB5pj5LLA",
"prompt": "在亚马逊美国站搜索 usb charger cable，返回前 40 条",
"status": "submitted",
"submittedAt": "2026-07-14T10:30:05",
"stopReason": ""
}
// After --wait / --poll sees a terminal stopReason:
{
"messageId": "uDqHg33fQeQfkNB5pj5LLA",
"prompt": "...",
"status": "finished", // finished (end_turn) / error (other stopReason)
"submittedAt": "2026-07-14T10:30:05",
"stopReason": "end_turn",
"completedAt": "2026-07-14T10:33:18"
}
Field meanings:
messageId: the task id returned by /agent-studio/task/create (field id); used to look up status and results.
prompt: the original prompt text that was submitted.
status: lifecycle marker — submitted after submit, then finished / error once the task ends.
stopReason: the raw message.stopReason value from the API (empty while running; end_turn on success; other values indicate abnormal end).
submittedAt / completedAt: ISO-formatted local timestamps (no tz suffix).
Recovering messageId from local state
If the user comes back later but the messageId is no longer in the chat, run:
Pick the matching task, then call --status <messageId> for live progress or --poll <messageId> to fetch the full result.
To access raw result data: read <taskDir>/message.json — it holds the complete {message, eventList} response, including every agentMessageChunks entry.
12. Retry on Failure
If a task fails, inspect message.json for the stopReason and any error content in agentMessageChunks. Common issues:
stopReason is an error code (not end_turn) — the pipeline rejected the prompt or hit a server error; retry with a simpler / adjusted prompt.
