Alshhbaa Copperware — نحاسيات الشهباء

Alshhbaa Copperware AI Agent Kit 🏺✨

Alshhbaa Copperware（متجر نحاسيات الشهباء）官方 AI Agent 集成套件——该沙特知名手工艺品零售商专营手工黄铜吊灯、伊斯兰风格与传统照明、壁灯、豪华台灯、波西米亚水晶制品和意大利玻璃器皿。

此代码仓库为自主 AI Agent、编码助手和大模型（Claude、ChatGPT、Cursor、Google Antigravity、OpenClaw、Cline）提供所需的一切，以便安全、高效地发现、查询、验证并与 Alshhbaa Copperware 商店交互。

---

📦 包含内容

alshhbaa-agent-kit/
├── README.md                          # Main documentation and integration overview
├── AGENTS.md                          # Detailed instructions & guidelines for AI agents
├── plugin.json                        # Agent Plugins 1.0.0 manifest
├── mcp.json                           # MCP remote streamable HTTP server configuration
├── LICENSE                            # MIT License
├── .gitignore                         # Standard git ignore rules
└── skills/
    └── alshhbaa-store/
        └── SKILL.md                   # Agent skill definition conforming to skills.sh

---

⚡ 快速开始

1. 使用 Model Context Protocol（MCP）

Alshhbaa Copperware 提供远程流式 HTTP MCP 服务，地址为：

https://shop.alshhbaa.com/.well-known/mcp

在 Claude Desktop / Cline / Cursor 中使用（claude_desktop_config.json 或 mcp.json）：

{
  "mcpServers": {
    "alshhbaa-store": {
      "type": "streamable-http",
      "url": "https://shop.alshhbaa.com/.well-known/mcp"
    }
  }
}

该服务提供：

• search_products：快速搜索公开商品目录，获取吊灯、台灯和玻璃器皿的搜索建议。
• read_docs：访问商店开发者指南、OpenAPI 规范和政策文档。
• UI 资源：用于开发者门户和商品目录搜索界面的交互式 HTML 组件。

2. 使用 Agent 插件和技能（skills.sh）

直接安装或加载 alshhbaa-store 技能：

• 技能路径： skills/alshhbaa-store/SKILL.md
• 插件清单： plugin.json

此技能会指导 Agent 如何浏览商品、查询沙特境内的配送承运商费用，并在移交结账前验证购物车。

3. 直接使用 REST API 和 OpenAPI 3.1

完整的 OpenAPI 规范可通过以下地址访问：

https://shop.alshhbaa.com/openapi.json

主要 REST API 端点：

端点	方法	描述	身份验证
/api/v1/products	GET	支持筛选的游标分页商品目录列表	无（公开）
/api/v1/search/suggestions	GET	根据查询 ?q= 快速获取搜索建议	无（公开）
/api/v1/cities	GET	搜索支持配送的沙特城市	无（公开）
/api/v1/shipping-carriers	GET	根据城市和商品获取实时报价	无（公开）
/api/v1/cart/sync	POST	服务端购物车验证和库存检查	无（Idempotency-Key）
/api/v1/orders/{id}/status	GET	订单履行状态和货件追踪	客户令牌
/api/v1/orders/{id}/invoice/jobs	POST	异步生成 PDF 发票	客户令牌

---

🛡️ 治理与人类参与环节（HITL）防护措施

Alshhbaa Copperware 根据 /.well-known/agent-permissions.json 中的定义，严格限制 Agent 的权限：

1. 人类参与结账： AI Agent 可以搜索、浏览、估算运费并同步购物车。但是，结账和付款必须获得明确的人类确认。Agent 绝不能自主完成付款。
2. 支付安全： Agent 绝不能获取、存储或传输信用卡信息或 CVV。所有交易均通过 https://shop.alshhbaa.com/checkout 安全完成。
3. 杜绝幻觉： 产品价格、库存情况和配送费用必须从 API 获取。
4. 数据隐私： 订单令牌和客户信息必须保密。严格禁止访问管理端点（/admin）。

完整规则和 Agent 指南，请参阅 AGENTS.md。

---

🌐 公开发现端点

• 店铺： shop.alshhbaa.com
• OpenAPI 3.1： shop.alshhbaa.com/openapi.json
• MCP 服务卡片： shop.alshhbaa.com/.well-known/mcp/server-card.json
• Agent 技能索引： shop.alshhbaa.com/.well-known/agent-skills/index.json
• Agent 权限： shop.alshhbaa.com/.well-known/agent-permissions.json
• 大模型简介： shop.alshhbaa.com/llms.txt & shop.alshhbaa.com/agenticweb.md
• 开发者门户： shop.alshhbaa.com/developers

---

📄 许可证

本仓库采用 MIT License 授权。 版权所有 (c) 2026 Alshhbaa Copperware (متجر نحاسيات الشهباء)。