CrossBorderInsight

CrossBorderInsight 是面向跨境卖家的本地单用户 LLM-led Agent Web 产品。用户只和 Agent 对话，Agent 负责读取产品链接/素材、生成 Brief、调用搜索和抓取工具、沉淀证据链、做区域优先市场判断，并输出可导出的中文市场进入报告。

当前参赛上传口径：W3 Web Agent 产品 + W2 Skill 基础资产。W2 Skill 文档、模板和黄金案例用于定义流程和质量标准；W3 /product 是当前可运行产品入口。

当前状态

• 产品入口：http://127.0.0.1:8787/product
• 启动命令：scripts/run-w3-product.sh
• UI 形态：Bugatti cockpit 风格的三栏 Agent Workbench，包括任务/设置、对话区、报告/进度/来源/证据输出区。
• Agent 主线：普通聊天不创建任务；商品链接先生成 Brief/确认；确认后由 LLM Agent 调用内置工具推进研究。
• 证据链：ProviderAttempt -> SourceRecord -> EvidenceCard -> WikiEntry -> DecisionRecord -> ReportArtifact。
• 导出边界：未通过 delivery gate 的报告不能导出为合格 Markdown/HTML；provider 状态、搜索壳、登录墙、raw JSON 和内部 trace 不能冒充证据。

真实运行质量仍依赖本地配置的 LLM、Exa、Firecrawl、OpenCLI/Browser Bridge、平台登录态和目标平台可访问性。当前产品可以输出证据链清楚的低置信/中置信报告，但不能承诺任何市场或品类都达到高置信自动调研。

快速运行

python3 --version
scripts/run-w3-product.sh

然后打开：

http://127.0.0.1:8787/product

设置页可配置：

• LLM API Key / Base URL / model / Responses 或 Chat Completions 模式 / reasoning effort。
• Codex CLI / OpenCLI 路径。
• Firecrawl API Key。
• Exa API Key。
• 抓取策略、最大搜索结果数、最大抓取页数。

真实密钥只保存到本地 .env.local、.env 或 runs/product-settings.json，不进入提交。

推荐评审顺序

1. SUBMISSION.md：参赛上传说明、演示路径和边界。
2. SPEC.md：产品定义、LLM-led Agent 主控原则和公开自评标准。
3. HANDOFF.md：当前可恢复状态、已验证证据、风险和下一步。
4. docs/implementation/w3-launch-readiness.md：本地运行、自动验收和真实 Chrome 验收口径。
5. docs/implementation/w3-agent-workbench-remediation-plan.md：W3 当前执行主文档。
6. docs/implementation/w3-agent-data-collection-determinism.md：外部数据采集、登录态、SourceRecord 分类和数据预算门禁。
7. skills/crossborder-insight/SKILL.md：主 Skill，定义黄金流程。
8. skills/README.md：子 Skill 注册表。
9. DEMO.md：W2 Skill 黄金案例和验证脚本。
10. docs/implementation/w2-fallback-routing.md：W2/W3 共享的阻断、用户动作和低置信降级口径。
11. skills/crossborder-insight/examples/wiki-reuse-diff-example.md：LLM Wiki 复用、刷新和结论变化示例。

如果是互评 agent 或评委快速打分，优先看 SUBMISSION.md 的 “W3 评分 / 互评对照”。

历史实现规划可看 docs/implementation/w3-agent-web-plan.md，但它只作为历史记录；当前执行基准以上方 W3 remediation/data-determinism 文档为准。

验证命令

最小产品启动：

scripts/run-w3-product.sh

核心回归：

PYTHONPATH=agent/src PYTHONPYCACHEPREFIX=/private/tmp/codex-pycache python3 -m unittest discover -s agent/tests -q
node --check web/product-agent.js
node --check web/product.js
npm run test:e2e
git diff --check

上线前矩阵：

scripts/verify-w3-launch-readiness.sh

Skill 基础包：

scripts/verify-skill-package.sh
scripts/run-w2-demo-check.sh

真实 Web 产品验收必须使用 Chrome 打开 /product，模拟人类输入、查看流式回复、检查右侧报告/来源/证据、打开 Markdown/HTML 导出。Playwright、API、shell 和 fixture 只能作为辅助验证。

项目边界

本仓库是独立项目，不混入其他工作区资产、真实 API key、浏览器账号、用户私有配置或本机插件状态。

运行数据写入 runs/；本地配置写入 .env.local、.env 或 runs/product-settings.json。这些文件默认不提交。

关键目录

agent/                         W3 Agent 后端、Product API、证据链和测试
web/                           W3 Web Agent Workbench
skills/                        W2/W3 共用 Skill、模板、策略库和黄金案例
docs/architecture/             架构和 API 合同
docs/implementation/           W3 执行计划、验收、数据确定性和审计
docs/demo/                     Demo 辅助说明
scripts/                       启动、验证和导出脚本
tests/e2e/                     Playwright 产品验收

黄金样例

W3 报告质量要对照 W2 Skill 阶段的黄金样例，而不是只看结构是否完整：

• Tmall 立式笔记本支架最终报告
• 日本一次性袜最终报告

这两份报告定义了内容密度、具名竞品、价格点、本地关键词、渠道路径、策略推演、风险边界和最终建议的最低参考。