Content
# ShopOps
ShopOps is an AgentOps management platform for e-commerce operations scenarios. The project aims to break down natural language tasks from operations personnel into an executable, auditable, approvable, configurable, and evaluable Agent execution link.
> Operations personnel initiate daily tasks in the Agent workbench using natural language, and the system automatically identifies intentions, calls tools such as orders, reviews, products, and placements, generates structured operation reports, abnormal alarms, and improvement suggestions, and precipitates task, tool, report, approval, audit, and quantitative evaluation data.
## Verifiable Results
| Metric | Current Result | Evidence |
| --- | ---: | --- |
| Public real data business examples | 760 | Olist、Criteo、UCI Online Retail、Store Sales |
| Derived MCP tool calls | 2670 | `docs/ShopOps-public-real-baseline.json` |
| High-risk approval routes calls | 450 | Refund, product title, ad budget suggestions |
| Agent automated evaluation | 14/14 passed | `shopops-admin/target/evaluation` |
| Tool call success rate | 98.6% | `docs/ShopOps-resume-claim-evidence.md` |
| Anomaly signal evaluation | Precision 94.81%, Recall 100% | `docs/ShopOps-real-anomaly-evaluation.md` |
| Feishu webhook batch verification | 100/100 success, HTTP 200 rate 100% | `docs/evaluation/feishu-webhook-batch-summary.json` |
| Feishu webhook average time consumption | 311.9 ms | 100 consecutive real webhook calls |
| Excel report export | Real `.xlsx`, 4 worksheets | `docs/evaluation/shopops-operation-report-sample.xlsx` |
| Daily report time consumption benefit | Estimated 35.4 minutes -> 4.2 minutes | Marked as `ESTIMATED`, not actual manual timing |
## Project Highlights
- Natural Language Agent Workbench: Operations personnel can input tasks such as "generate today's shop operation report", "analyze recent bad reviews", and "find low-click products and provide optimization suggestions". The system automatically routes and displays execution steps, tool calls, and final reports.
- MCP-style tool orchestration: Unified encapsulation of 18 tools including order query, evaluation analysis, product optimization, placement review, Excel export, and Feishu synchronization. All calls enter the tool log, audit link, and evaluation statistics.
- Agent execution closed loop: Supports task creation, intention routing, step execution, synchronous/asynchronous scheduling, failure retry, degradation processing, task tracking, and report storage.
- Risk control and manual approval: High-risk tools such as refund execution, product title modification, and ad budget suggestions enter the approval process, supporting confirmation language, withdrawal, batch processing, expiration processing, and audit tracking.
- Shop operation configuration: Refund rate threshold, bad review threshold, approval switch, and model strategy can be configured by shop, and take effect in Agent reports and tool execution.
- Real data and evaluation: Olist as the online demonstration main link, Criteo, UCI Online Retail, Store Sales to make up for advertising, refund/cancellation proxy and external event evaluation gaps.
- Report output closed loop: Operation report can view Markdown evidence chain, export real Excel file, and has passed 100 times of real Feishu webhook batch synchronization verification.
- React management front-end: The background has been migrated to React + TypeScript + Axios + ECharts + Ant Design, covering workbench, tasks, reports, audit, tools, approvals, models, and organization configuration and other pages.
- Reproducible work portfolio evidence: Provides baseline generation, Agent evaluation, anomaly signal evaluation, Feishu batch verification, time-consuming benefit estimation and other scripts and documents.
## Current Completion
| Module | Status | Description |
| --- | --- | --- |
| Agent Workbench | Completed v1 | Natural language input, quick tasks, Olist demo, execution steps, quantitative results, report entry |
| Agent Task Flow | Completed | Create, run, retry, steps, events, task details, asynchronous/synchronous execution |
| MCP Tool Center | Completed | Tool registration, tool gateway, call log, failure statistics, tool approval status |
| Approval Center | Completed | Create, pass, reject, withdraw, batch operation, expiration processing, confirmation language |
| Audit Center | Completed | Overview, risk events, timeline, details, export, cross-page jump |
| Report Center | Completed | Report list, details, Markdown view, report evidence chain |
| User and Tenant | Completed | Users, tenants, shops, members, role permissions, password reset |
| Shop Configuration | Completed | Configuration maintenance, runtime reading, threshold and approval switch taking effect |
| Model Gateway | Completed basic version | Provider, Prompt template, call log, OpenAI-compatible adaptation, rule fallback |
| React Front-end | Completed main page migration | Workbench, dashboard, tasks, reports, audit, tools, approvals, models, organization and other pages |
| Olist Data | Completed demo version | Order, review, product candidate real data access |
| Public multi-source real data baseline | Completed v1 | Criteo advertising, UCI refund/cancellation proxy, Store Sales external event evaluation included in the evaluation baseline |
## Quick Start
Environment requirements:
- JDK 17
- Maven 3.9+
- Node.js 18+
- Python 3.10+
- Optional: Docker, MySQL, Redis, RabbitMQ
One-click start demo:
```powershell
powershell -ExecutionPolicy Bypass -File scripts/start-shopops.ps1
```
The script will automatically prepare Olist demo data, install `shopops-common`, check/start local MySQL persistent storage, start the backend, and open the workbench after successful startup. If `8080` is occupied, it will automatically try `8081` to `8100`.
If only Docker Desktop is installed, you can directly build, start and preset the complete demo link:
```powershell
powershell -ExecutionPolicy Bypass -File scripts/start-shopops-docker.ps1
```
When Docker Hub access is restricted:
```powershell
powershell -ExecutionPolicy Bypass -File scripts/start-shopops-docker.ps1 -UseChinaMirror
```
Stop container:
```powershell
docker compose -p shopops-demo -f deploy/docker-compose.demo.yml down
```
Access after startup:
```text
http://localhost:8080/admin/workbench.html
```
If the script automatically switches to another port, take the `Workbench` address output by the script as the standard.
Common options:
```powershell
powershell -ExecutionPolicy Bypass -File scripts/start-shopops.ps1 -Port 8081
powershell -ExecutionPolicy Bypass -File scripts/start-shopops.ps1 -NoOpenBrowser
powershell -ExecutionPolicy Bypass -File scripts/start-shopops.ps1 -StrictPort
powershell -ExecutionPolicy Bypass -File scripts/start-shopops.ps1 -Memory
```
Pre-demo health check:
```powershell
powershell -ExecutionPolicy Bypass -File scripts/check-shopops.ps1
```
One-click preset complete demo link:
```powershell
powershell -ExecutionPolicy Bypass -File scripts/seed-shopops-demo.ps1
```
The script will wait for the service to be ready, perform a health check, and create a business report task, report, high-risk tool approval, approval retry, and audit record. After completion, it will output task, report, tool, approval, audit page address and open the workbench. By default, under the JDBC/MySQL mode, task, report, tool log, approval, and audit records are retained; if you need to demonstrate with temporary cleaning, use `start-shopops.ps1 -Memory`.
If the backend is not on `8080`:
```powershell
powershell -ExecutionPolicy Bypass -File scripts/check-shopops.ps1 -Port 8081
powershell -ExecutionPolicy Bypass -File scripts/seed-shopops-demo.ps1 -Port 8081
```
You can also start manually step by step:
Prepare Olist demo data:
```powershell
python scripts/prepare_olist_demo.py
```
Start the backend:
```powershell
mvn -pl shopops-admin spring-boot:run "-Dspring-boot.run.profiles=dev" "-Dspring-boot.run.arguments=--server.port=8080"
```
Open Agent workbench:
```text
http://localhost:8080/admin/workbench.html
```
Recommended demo date:
```text
2018-08-07
```
In the workbench, you can click "Olist demo data" and then start the Agent task.
## Recommended Demo Process
1. Open `/admin/workbench.html`, which is the main entry for operations personnel.
2. Input or select quick tasks, such as "Based on Olist real orders and review data, generate 2018-08-07 shop operation report".
3. Start Agent, observe intention recognition, task creation, step execution, and tool calls.
4. View quantitative indicators: GMV, refund agent rate, risk evaluation number, product candidate number.
5. Open the final report, display Markdown business report, evidence chain, and shop configuration snapshot.
6. Jump to task details, display steps, status, retry, and tracking capabilities.
7. Jump to tool log, display MCP tool call records.
8. Jump to audit center, display task, report, tool, approval association link.
9. Display approval center, explain high-risk actions require manual confirmation.
10. Finally, display the evaluation report, emphasizing that the project is not just doing the page, but also has quantitative acceptance.
## Olist Data Demo
The project reads by default:
```text
docs/demo-data/olist/order-summary-olist.json
docs/demo-data/olist/negative-comments-olist.json
docs/demo-data/olist/product-candidates-olist.json
```
These files are generated from Brazilian E-Commerce Public Dataset by Olist:
```powershell
python scripts/prepare_olist_demo.py
```
Current Olist demo summary:
| Metric | Result |
| --- | ---: |
| Business Date | 2018-08-07 |
| GMV | 62057.77 |
| Orders | 370 |
| After-sales/refund agent amount | 4732.62 |
| After-sales/refund agent rate | 7.63% |
| Risk evaluation number | 51 |
| Product candidate number | 10 |
Description:
- Olist does not include real refund amount, the project uses `canceled / unavailable` order payment amount as after-sales risk agent value.
- Olist does not include real ad placement data, ad performance has been used in the public multi-source baseline using Criteo Attribution data to make up; the current Olist online demo connector can still fall back to built-in demo data.
- Olist does not include platform external environment indicators, external events have been used in the public multi-source baseline using Store Sales `holidays_events.csv` to make up; the current Olist online demo connector can still fall back to built-in demo data.
- Olist does not provide product title, the current use of English category and productId prefix to generate display name.
## Agent Main Link
```text
Natural language task
-> Intention recognition and routing
-> Agent task
-> Planner generates execution steps
-> Tool Gateway unified tool call
-> order.query_summary
-> comment.query_negative
-> product.query_candidates
-> ad.query_performance
-> report.query_external_metrics
-> report.generate_daily_review
-> Business report
-> Tool log / Approval center / Audit timeline
```
## Architecture Overview
```text
React Admin Console
├── Agent Workbench
├── Dashboard
├── Tasks / Reports
├── Tool Logs / Approval Center
├── Audit Center
├── Model Gateway
└── Organization / Shop Config
Spring Boot Backend
├── Auth / Tenant / Shop
├── Agent Task Queue
├── Planner / Executor
├── MCP-style Tool Registry
├── Tool Gateway
├── Approval Service
├── Report Service
├── Audit Service
├── Model Gateway
└── Connector Layer
Persistence and Integrations
├── Memory mode for local demo and tests
├── JDBC / MySQL mode for dev deployment
├── Redis and RabbitMQ optional infrastructure
├── Olist file connectors
└── OpenAI-compatible model provider
```
## Technology Stack
Backend:
- Java 17
- Spring Boot 3.3
- Maven multi-module
- Spring MVC
- MyBatis
- Flyway
- MySQL
- Redis
- RabbitMQ
- JUnit 5
- Spring Boot Test
Frontend:
- React 19
- TypeScript
- Vite
- Axios
- ECharts
- Ant Design
- Ant Design Icons
Agent and platform capabilities:
- MCP-style Tool Registry
- Agent Task Queue
- Rule Planner
- Sequential Executor
- Tool Gateway
- Approval Center
- Audit Timeline
- Report Center
- Model Gateway
- OpenAI-compatible Provider
- Shop Runtime Configuration
## Main Pages
| Page | Address | Purpose |
| --- | --- | --- |
| Agent Workbench | `/admin/workbench.html` | Natural language initiate tasks, view execution process and final report |
| Dashboard | `/admin/dashboard.html` | Overview tasks, reports, tools, audit indicators |
| Task Center | `/admin/tasks.html` | View task list, details, steps, retry |
| Report Center | `/admin/reports.html` | View business report, Markdown content, evidence chain |
| Audit Center | `/admin/audit.html` | View risk events, timeline, associated details |
| Tool Center | `/admin/tools.html` | View tool registration, call log, failure statistics |
| Approval Center | `/admin/approvals.html` | Process high-risk tool approvals |
| Model Gateway | `/admin/prompts.html` | Manage Prompt, model calls, and Provider |
| Organization Management | `/admin/users.html` | Manage users, tenants, shops, members, shop configuration |
## Common Commands
GitHub Actions will execute backend tests, React frontend builds, and Docker Compose/mirroring builds in parallel on each push and Pull Request. The workflow is located in `.github/workflows/ci.yml`.
Backend full test:
```powershell
mvn -pl shopops-admin -am test
```
Frontend build:
```powershell
cd shopops-admin-ui
npm run build
```
Agent workbench related tests:
```powershell
mvn -pl shopops-admin "-Dtest=AdminWorkbenchStaticPageIntegrationTest,AgentNaturalLanguageTaskIntegrationTest" test
```
Refresh Agent evaluation baseline:
```powershell
powershell -ExecutionPolicy Bypass -File scripts/run-agent-evaluation.ps1
```
Generate portfolio quantitative report:
```powershell
powershell -ExecutionPolicy Bypass -File scripts/generate-portfolio-report.ps1
```
Verify Olist demo link:
```powershell
powershell -ExecutionPolicy Bypass -File scripts/verify-agentops-demo.ps1 -Port 8080 -Start 2018-08-07 -End 2018-08-07 -Scenario olist-agentops-demo -Dataset olist
```
Start MySQL / Redis / RabbitMQ development environment:
```powershell
docker compose -f deploy/docker-compose.dev.yml up -d
```
JDBC dev profile startup:
```powershell
mvn -pl shopops-admin spring-boot:run "-Dspring-boot.run.profiles=dev"
```
## Quantitative Acceptance
Current portfolio baseline:
| Dimension | Result |
|---|---:|
| Agent evaluation cases | 14 |
| Passed cases | 14 |
| Completion rate | 100% |
| Tool invocation success rate | 98.6% |
| Approval decision accuracy | 100% |
| Config effect accuracy | 100% |
| Public real-data business samples | 760 |
| Public real-data derived MCP tool calls | 2670 |
| Public real-data high-risk approval-routed calls | 450 |
| Olist real orders | 99441 |
| Olist real reviews | 99224 |
| Olist real products | 32951 |
| Criteo real ad impressions | 16468027 |
| Criteo real ad clicks | 5947563 |
| Criteo real ad conversions | 806196 |
| UCI Online Retail lines | 541909 |
| UCI cancellation/refund proxy lines | 10624 |
| Store Sales holiday events | 350 |
| Real anomaly signal precision | 94.81% |
| Real anomaly signal recall | 100% |
| Feishu webhook batch success rate | 100/100 |
| Feishu webhook HTTP 200 rate | 100% |
| Feishu webhook average latency | 311.9 ms |
| Estimated daily report time saving | 35.4 min -> 4.2 min |
| Recent full test | 88 tests, 0 failures, 8 skipped |
Evaluation coverage:
- Daily business report task
- Risk identification of negative reviews
- Product optimization candidate identification
- Tool invocation success rate
- High-risk tool approval
- Direct execution after approval closure
- Store threshold configuration taking effect
- Model strategy entering report evidence
- Model degradation completion after failure
- Feishu webhook real HTTP synchronization
- Excel report real export
Note: `Estimated daily report time saving` comes from fixed workflow estimation baseline, and the evidence item is marked as `ESTIMATED`; real manual timing still needs to supplement at least 5 manual process records.
## Model Gateway
Default report generation can use rule fallback, so local demonstration can be completed without real API Key. To enable real model calls, configure OpenAI-compatible provider:
```powershell
$env:SHOPOPS_MODEL_OPENAI_COMPATIBLE_ENABLED="true"
$env:SHOPOPS_MODEL_OPENAI_COMPATIBLE_BASE_URL="https://your-provider.example/v1"
$env:SHOPOPS_MODEL_OPENAI_COMPATIBLE_API_KEY="your-api-key"
$env:SHOPOPS_MODEL_OPENAI_COMPATIBLE_DEFAULT_MODEL="your-model"
$env:SHOPOPS_MODEL_GATEWAY_REPORT_ENABLED="true"
$env:SHOPOPS_MODEL_GATEWAY_PLANNER_ENABLED="true"
```
Related scripts:
```powershell
powershell -ExecutionPolicy Bypass -File scripts/start-model-gateway-demo.ps1
powershell -ExecutionPolicy Bypass -File scripts/verify-model-gateway-demo.ps1 -Port 8080
```
## Directory Structure
```text
.
├── shopops-admin
│ ├── src/main/java/com/sirithree/shopops/admin
│ ├── src/main/resources
│ └── src/test/java/com/sirithree/shopops/admin
├── shopops-common
├── shopops-admin-ui
│ └── src
├── docs
│ └── demo-data/olist
├── scripts
└── deploy
```
## Key Documents
- [Agent Workbench Portfolio Demo Script](docs/Agent%20Workbench%20Portfolio%20Demo%20Script.md)
- [ShopOps Portfolio Quantitative Report](docs/ShopOps-portfolio-report.md)
- [ShopOps Public Real Baseline](docs/ShopOps-public-real-baseline.md)
- [ShopOps Real Anomaly Signal Evaluation](docs/ShopOps-real-anomaly-evaluation.md)
- [ShopOps Resume Claim Evidence Table](docs/ShopOps-resume-claim-evidence.md)
- [ShopOps Resume Project Description LaTeX](docs/ShopOps%20Resume%20Project%20Description%20LaTeX.md)
- [ShopOps Daily Time-Saving Evidence Table](docs/ShopOps-operation-timing-evidence.md)
- [ShopOps Olist Real Data Baseline](docs/ShopOps-olist-real-baseline.md)
- [ShopOps Resume Baseline](docs/ShopOps-resume-baseline.md)
- [Feishu Synchronous Webhook Acceptance Description](docs/Feishu%E5%90%8C%E6%89%8BWebhook%E9%AA%8C%E6%94%B6%E8%AF%81%E6%98%8E.md)
- [Feishu Batch Synchronization Acceptance Record](docs/Feishu%E6%89%B9%E9%87%8F%E5%90%8C%E6%89%8B%E9%AA%8C%E6%94%B6%E8%AF%81%E5%BD%95.md)
- [ShopOps Portfolio Chinese Demo Lecture](docs/ShopOps%E4%BD%9C%E5%93%81%E9%9B%86%E4%B8%AD%E6%96%87%E6%BC%94%E7%A4%BA%E8%AE%9E.md)
- [Olist Real Data Access Description](docs/Olist%E7%9C%9F%E5%AE%9E%E6%95%B0%E6%8D%85%E6%8E%A5%E8%AF%81%E6%98%8E.md)
- [Agent Evaluation Baseline and Portfolio Data](docs/Agent%20Evaluation%20Baseline%20and%20Portfolio%20Data.md)
- [Real Model Gateway Demo](docs/%E7%9C%9F%E5%AE%9E%E6%A8%A1%E5%9E%8B%E7%BD%91%E5%85%B3%E6%BC%94%E7%A4%BA.md)
- [Local Development Startup Guide](docs/%E5%BD%93%E5%9C%B0%E5%BC%80%E5%8F%91%E5%90%AF%E5%8A%A8%E6%8C%82%E5%8D%97.md)
- [Document Index](docs/README.md)
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available