# 1. 本机安装并启动【腾讯 Marvis】客户端后，可直接调用其内置高性能 Python 3.11 运行时启动本工具：
& "C:\Program Files\Tencent\Marvis\MarvisAgent\1.60.3000.716\runtime\python311\python.exe" server.py 8765

# 2. 或使用腾讯 Marvis 运行时直接执行 CLI 与 MCP Server：
& "C:\Program Files\Tencent\Marvis\MarvisAgent\1.60.3000.716\runtime\python311\python.exe" cli.py --matrix --budget 95000

flowchart LR
    subgraph Input["Layer 1 & 2: 5-Modal Ingestion"]
        A1["🔗 Social Profile URL\n(Best via Tencent Marvis)"]
        A2["📄 Product Doc / Text"]
        A3["🖼️ Cover / Screenshot"]
    end

    subgraph Core["Layer 3: Core Architecture (core/)"]
        direction TB
        B1["🔓 Open-Core Trial & SDK (veawho/via54SocialROI)\ncore/interfaces.py + schemas.py + demo_engine.py"]
        B2["🔒 Private Full Commercial Repo (veawho/via54SocialROIPro)\nFull Calibration + Live Marvis SSR + 5-Modal OCR"]
    end

    subgraph Outputs["Layer 4 & 5: Decision & Plugin Ecosystem"]
        C1["🎯 Stage 1 -> Stage 2 Lift\nViews / Index / JD·Tmall·Meituan UV"]
        C2["🤖 8-LLM GEO SoM & PAWC\n+ McKinsey Pocket Price ROI"]
        C3["🌟 Multi-Account Matrix PK\n& Optimal Budget Allocator"]
        C4["🔌 Agent Skill (via54socialroi)\n+ MCP Server + Node/Cordis Plugin"]
    end

    Input --> Core --> Outputs

# 1. 克隆仓库 / Clone the repository
git clone https://github.com/veawho/via54SocialROI.git
cd via54SocialROI

# 2. 查看当前激活引擎版本 / Check active engine edition
python cli.py --info

# 3. 命令行一键运行单账号投前精算试用 Demo / Run Single-Account CLI Demo
python cli.py --preset xhs_kefujia_medical

# 4. 命令行一键运行跨平台多账号矩阵 PK 与预算分配 Demo / Run Multi-Account Matrix CLI Demo
python cli.py --matrix --budget 95000

# 5. 启动极简傻瓜式 Web 测算工作台 / Launch the Web Workbench UI
python server.py 8765
# 浏览器打开 / Open in browser: http://127.0.0.1:8765

# 方式 A：使用 skills CLI 一键安装
npx skills add veawho/via54SocialROI

# 方式 B：复制到 Claude Code / Antigravity / 腾讯 Marvis 全局 skills 目录
cp -r via54socialroi ~/.claude/skills/
cp -r via54socialroi ~/.gemini/config/skills/

{
  "mcpServers": {
    "via54-social-roi": {
      "command": "python",
      "args": ["/path/to/via54SocialROI/mcp_server.py"]
    }
  }
}

const Via54SocialROIPlugin = require('./plugin');

// 单账号评测 / Single-account evaluation
const res = await Via54SocialROIPlugin.evaluateSingleAccount({
  brand: '科复佳',
  product: '医用透明质酸钠修复贴',
  platform: 'xiaohongshu',
  followers: 185000,
  budget: 18500,
  price: 118
});

via54SocialROI/
├── core/                         # [Base Architecture & Trial Sandbox] 五层开源架构与试用沙盒
│   ├── __init__.py               # 架构导出入口 (OPEN_CORE_DEMO)
│   ├── schemas.py                # 强类型领域数据模型 (SocialAccountProfile / ProductInput / Stage2)
│   ├── interfaces.py             # 五层系统抽象基类 (BasePromotionEngine / BaseSocialCrawler 等)
│   └── demo_engine.py            # 开源确定性试用沙盒与参考实现
├── plugin/                       # [Node/Cordis Plugin] JS/TS 跨框架插件适配器
│   ├── index.js                  # Cordis / Koishi / OpenClaw / Node 插件入口
│   └── index.d.ts                # TypeScript 类型声明
├── via54socialroi/               # [Agent Skill] 通用技能包 (兼容腾讯 Marvis / Antigravity / Claude)
│   ├── SKILL.md
│   └── scripts/social_roi_cli.py
├── skills/via54socialroi/        # 标准插件目录技能镜像
├── .claude-plugin/plugin.json    # Claude Code 插件清单
├── plugin.json                   # 根级 MCP 与技能插件声明清单
├── package.json                  # @via54/plugin-social-roi NPM/Node 插件配置
├── static/index.html             # v2.4 极简三步傻瓜式 Web 测算台 + 多账号 PK 选号看板
├── server.py                     # REST API 与 Web 工作台服务端
├── cli.py                        # 命令行工具 (支持 --info / --preset / --matrix / --json)
├── mcp_server.py                 # 零依赖 JSON-RPC 2.0 Stdio MCP 服务端
├── tests/test_demo.py            # 6项开源试用沙盒、插件形态与防泄漏自动化测试套件
├── README.md                     # 中英双语主文档 (Default Bilingual README)
├── README.zh-CN.md               # 中文说明文档
└── README_EN.md                  # Technical English Documentation

python -m unittest discover -s tests -v