内容
# MadeForAI 供应链技能
[中文说明](./README.zh-CN.md)
MadeForAI 是连接 AI 代理与中国现实供应链执行的接口层。0.3.4 版本将 AI 代理的小批量制造请求转换为结构化的现实供应链任务，由人类现实操作员执行。
**给 AI 代理在现实世界中提供双手，让人类掌控每一个不可逆的闸门。**
在第一阶段，人类现实操作员可以审查任务、联系供应商或批发市场运营商、确认流程、请求报价、检查样品、上传照片或视频，并将执行结果返回给 AI 代理。
## 为什么存在
AI 代理可以描述他们想要什么，但现实制造仍然依赖于人类的确认：材料、最小订购量、工艺可行性、质量、样品、物流和供应商信任。MadeForAI 提供了一个狭窄、可审计的桥梁，从 AI 意图到人类操作的现实供应链执行。
MadeForAI 不生成图像，不运行 LLM 推理，不处理现实支付，也不自动下达现实订单。它只为人类现实操作员创建和跟踪供应链执行任务。包含的模拟支付流程验证了批准关口，而不移动资金。
## 功能
- 用于本地 AI 客户端（如 Claude Desktop、Codex 和 Cursor）的 MCP stdio 服务器。
- `POST /mcp` 的可流式 HTTP MCP 端点，用于未来的远程使用。
- `GET /health` 的 Express 健康检查。
- 人类现实操作员的 `GET /operator` 操作员控制台。
- Prisma + PostgreSQL 持久性。
- 本地制造规则评估，无外部 LLM 调用。
- 艺术品准备指南，供用户拥有的 AI 工具或设计师使用，无图像生成。
- 供应商报价和样品结果的人工审批优先工作流程。
- 所有工具输入的 Zod 验证。
- 结构化的双语指南，告诉 AI 客户端何时操作、询问或暂停。
- 非阻塞制造健全性检查，将可疑输入转换为澄清问题。
- 九个企业身份和高频定制商品类别的 1 期制造知识。
- 用于评估的零配置内存演示启动器。
## 工具
- `create_supplychain_task`：创建现实供应链任务。
- `generate_artwork_brief`：指导用户自己的 AI 代理或设计师在任务提交前准备生产就绪的艺术品。
- `generate_quote_request`：创建报价请求文本。
- `generate_order_draft`：创建结构化的订单草稿供用户确认，以及中文生产请求预览。
- `confirm_order_draft`：记录用户的批准或拒绝，并在批准后创建生产请求。
- `submit_production_feedback`：让生产方返回可行性、报价、交货时间和风险。
- `confirm_production_feedback`：记录用户接受或拒绝确切的操作员报价和风险。
- `create_payment_link`：从接受的操作员报价快照中创建模拟支付链接。
- `confirm_mock_payment`：模拟支付确认，用于本地工作流程测试。
- `update_production_status`：记录已支付订单的生产进度。
- `submit_shipment_info`：记录发货承运商、跟踪和发货备注。
- `complete_task`：将已履行的任务标记为已完成，并附上交付备注。
- `update_task_status`：让人类现实操作员更新任务状态。
- `upload_sample_result`：上传样品媒体网址、报价、生产时间和反馈。
- `quick_start_prototype_pipeline`：在一个调用中安全地创建任务和订单草稿，始终在用户确认之前停止。
- `get_task`：返回完整的任务详细信息、报价请求、样品结果和历史记录。
## 安装
对于 60 秒的本地评估，无需数据库：
```bash
npm install
npm run demo
```
启动器打印临时操作员凭证、两个工作区、HTTP MCP 端点和一个可粘贴的本地 MCP 配置。
对于 PostgreSQL 支持的开发：
```bash
npm install
cp .env.example .env
npm run prisma:generate
```
创建 `DATABASE_URL` 引用的 PostgreSQL 数据库，然后运行：
```bash
npx prisma migrate dev --name init
```
## 本地开发
运行 stdio MCP 服务器：
```bash
npm run start:stdio
```
运行 HTTP 服务器：
```bash
npm run start:http
```
在 Windows 上，该存储库还包括用于本地持久 PostgreSQL 的辅助脚本：
```bash
npm run postgres:start
npm run postgres:ensure-db
npm run prisma:migrate
npm run start:http:postgres
```
停止本地 PostgreSQL 服务器：
```bash
npm run postgres:stop
```
运行完整的本地持久验证：
```bash
npm run verify:persistent
```
这会在需要时启动 PostgreSQL、构建项目、运行测试、运行 lint、对 PostgreSQL 进行完整的 MCP 工作流程、重启 HTTP 服务器，并在 `http://localhost:3000/operator` 处留下操作员控制台可供访问。
健康检查：
```bash
curl http://localhost:3000/health
```
操作员控制台：
```text
http://localhost:3000/operator
```
操作员控制台是一个中文、以任务为导向的工作空间，供人类现实操作员使用。它将工作分为需求审查、报价和交货时间、样品、生产和质量控制、物流和历史记录。控制台突出显示下一个所需的动作，而不是一次显示所有表单。它受到环境配置的用户名和密码的保护。缺少凭证会锁定控制台，而不是公开任务数据。
用户工作流程：
```text
http://localhost:3000/user
```
英文用户工作空间演示了 AI 客户端看到的审批优先流程：生产简介、订单草稿确认、人类现实操作员反馈、模拟支付确认、生产和验证交付。每个步骤都调用真正的本地工作流程工具，并在用户审批关口暂停。演练使用脚本操作员响应和模拟支付，仅此而已；它不会下订单或处理资金。
非技术验收页面：
```text
http://localhost:3000/acceptance
```
此页面需要与 `/operator` 相同的操作员登录。登录后，它通过一个按钮运行完整的 AI 端和生产端工作流程，并用中文报告通过/失败。
有关非技术本地验收测试，请参阅 `docs/LOCAL_VALIDATION.zh-CN.md`。
构建和测试：
```bash
npm run build
npm test
```
当前版本包括 16 个 MCP 工具、16 步审批优先工作流程、九个 1 期制造类别和 48 个专注的自动化测试，包括路由级端到端覆盖。支付链接绑定到接受的报价版本，金额不能在没有明确货币的情况下存在，带有证据的状态需要专用业务工具，质量检查在发货前是必需的，发货在完成之前是必需的。
对于无数据库的本地 MCP 烟雾测试，设置 `MCP_DEV_MEMORY_STORE=true`，启动 HTTP 服务器，然后运行：
```bash
npm run smoke:http
```
## 环境变量
| 名称 | 必需 | 描述 |
| --- | --- | --- |
| `DATABASE_URL` | 是 | Prisma 使用的 PostgreSQL 连接字符串。 |
| `PORT` | 否 | HTTP 端口。默认为 `3000`。 |
| `MCP_TRANSPORT` | 否 | `stdio` 或 `http`。默认为 `stdio`。 |
| `MCP_DEV_MEMORY_STORE` | 否 | 仅在本地 MCP 测试时设置为 `true`，无需 PostgreSQL。数据不会持久化。 |
| `MCP_HTTP_AUTH_REQUIRED` | 否 | 为 `/mcp` 需要 bearer API 密钥。生产模式始终需要一个。 |
| `MCP_HTTP_API_KEY` | 生产环境中需要 | 远程 MCP bearer 密钥。使用至少 32 个随机字符。 |
| `ENABLE_DEMO_ROUTES` | 否 | 启用 `/demo`、`/user` 和 `/acceptance`。生产环境中默认为关闭。 |
| `OPERATOR_USERNAME` | 否 | 操作员控制台用户名。默认为 `operator`。 |
| `OPERATOR_PASSWORD` | `/operator` 需要 | 操作员控制台密码。永远不要提交真实值。 |
| `OPERATOR_SESSION_SECRET` | `/operator` 需要 | 用于签署操作员会话的随机密钥。使用至少 32 个随机字符。 |
| `OPERATOR_COOKIE_SECURE` | 否 | 当公共操作员控制台通过 HTTPS 提供服务时设置为 `true`。 |
| `TRUST_PROXY` | 否 | 仅在信任的反向代理后面运行时设置为 `true`。 |
| `CORS_ORIGIN` | 否 | 以逗号分隔的浏览器源允许列表。空值禁用浏览器跨源使用。 |
用于此机器上的持久本地开发：
```env
DATABASE_URL="postgresql://madeforai@127.0.0.1:5432/madeforai"
MCP_DEV_MEMORY_STORE=false
MCP_HTTP_AUTH_REQUIRED=false
ENABLE_DEMO_ROUTES=true
OPERATOR_USERNAME=operator
OPERATOR_PASSWORD=替换为强密码
OPERATOR_SESSION_SECRET=替换为至少32个随机字符
OPERATOR_COOKIE_SECURE=false
CORS_ORIGIN=
```
## 使用 Docker 运行
```bash
OPERATOR_PASSWORD="替换为强密码" \
OPERATOR_SESSION_SECRET="替换为至少32个随机字符" \
docker compose up --build
```
应用程序监听端口 `3000`，PostgreSQL 监听端口 `5432`。
在生产使用之前，请对目标数据库运行 Prisma 迁移，通过 HTTPS 提供操作员控制台，并设置 `OPERATOR_COOKIE_SECURE=true`。
有关生产导向的单服务器 Compose 配置和 HTTPS 要求，请参阅 [docs/DEPLOYMENT.md](./docs/DEPLOYMENT.md)。
## MCP 客户端配置示例
本地 stdio 配置示例：
```json
{
"mcpServers": {
"madeforai-supplychain-skill": {
"command": "node",
"args": ["/absolute/path/to/madeforai-supplychain-skill/dist/src/index.js", "--stdio"],
"env": {
"DATABASE_URL": "postgresql://madeforai:madeforai@localhost:5432/madeforai"
}
}
}
}
```
远程流式 HTTP 配置示例：
```json
{
"mcpServers": {
"madeforai-supplychain-skill": {
"url": "https://your-domain.example/mcp",
"headers": {
"Authorization": "Bearer 替换为您的MCP_HTTP_API_KEY"
}
}
}
}
```
远程客户端配置格式不同，但 `/mcp` 请求必须将 API 密钥作为 `Authorization: Bearer ...` 头发送。
## 工具示例
### 语言模型
MadeForAI 分离面向用户和面向生产的语言：
- 面向用户的 AI 应用程序输出默认为英文，需要时可以请求中文。
- 生产端的供应商和现实操作员材料应为中文。
- `generate_order_draft` 默认返回英文用户确认文本，并始终包含中文生产请求预览。
- `generate_quote_request` 默认为中文，因为它通常发送到生产端；如果 AI 应用程序需要英文版本供用户使用，请传递 `"language": "en"`。
生成艺术品准备简报：
```json
{
"product_category": "acrylic",
"product_name": "亚克力人物立牌",
"manufacturing_goal": "为小批量商品样品准备生产就绪的艺术品。",
"quantity": 100,
"target_market": "Japan",
"language": "en"
}
```
创建任务：
```json
{
"title": "自定义珐琅徽章样品",
"description": "需要小批量珐琅徽章用于限量商品投放。",
"product_category": "badge",
"quantity": 200,
"budget_range": "需要手动报价",
"target_market": "US",
"asset_urls": ["https://example.com/artwork.png"],
"shipping_destination": "Los Angeles, CA"
}
```
生成中文报价请求：
```json
{
"task_id": "task_xxxxxxxxxxxxxxxxxx",
"language": "zh"
}
```
生成用户可确认的订单草稿：
```json
{
"task_id": "task_xxxxxxxxxxxxxxxxxx",
"user_language": "en"
}
```
确认订单草稿：
```json
{
"task_id": "task_xxxxxxxxxxxxxxxxxx",
"confirmed": true,
"message": "用户批准了订单草稿。"
}
```
提交生产端反馈：
```json
{
"task_id": "task_xxxxxxxxxxxxxxxxxx",
"feasible": true,
"confirmed_process": "带有金色电镀的硬珐琅",
"quote": "6.80 CNY/unit x 200",
"total_amount": "1360.00",
"currency": "CNY",
"sample_cost": "需要手动确认",
"estimated_production_time": "样品批准后12-15天",
"estimated_shipping_time": "5-8天",
"risks": ["颜色匹配需要样品批准"]
}
```
确认操作员报价和风险（人工关口 2）：
```json
{
"task_id": "task_xxxxxxxxxxxxxxxxxx",
"accepted": true,
"accepted_quote_id": "quote_xxxxxxxxxxxxxxxxxx",
"accepted_risks": true,
"message": "用户接受了报价和所述风险。"
}
```
创建模拟支付链接：
```json
{
"task_id": "task_xxxxxxxxxxxxxxxxxx",
"accepted_quote_id": "quote_xxxxxxxxxxxxxxxxxx",
"description": "模拟支付链接，用于接受的生产报价"
}
```
金额和货币从服务器上的接受的报价快照中读取。调用者无法提供它们。提交与用户接受的 `accepted_quote_id` 不同的 `accepted_quote_id` 将被拒绝。
确认模拟支付：
```json
{
"task_id": "task_xxxxxxxxxxxxxxxxxx",
"payment_id": "pay_mock_xxxxxxxxx",
"confirmed": true,
"message": "模拟支付手动确认。"
}
```
更新生产进度：
```json
{
"task_id": "task_xxxxxxxxxxxxxxxxxx",
"stage": "production_in_progress",
"message": "生产在支付确认后开始。",
"production_photos": ["https://example.com/production.jpg"]
}
```
提交发货信息：
```json
{
"task_id": "task_xxxxxxxxxxxxxxxxxx",
"carrier": "Mock Air",
"tracking_number": "TRACK123",
"tracking_url": "https://example.com/track/TRACK123",
"estimated_delivery": "5-8 days"
}
```
完成交付：
```json
{
"task_id": "task_xxxxxxxxxxxxxxxxxx",
"completion_notes": "由操作员确认并交付。",
"proof_urls": ["https://example.com/delivery-proof.jpg"]
}
```
上传样品结果：
```json
{
"task_id": "task_xxxxxxxxxxxxxxxxxx",
"sample_images": ["https://example.com/sample.jpg"],
"quoted_price": "价格需要手动确认。",
"production_time": "样品批准后7-10天",
"supplier_feedback": "供应商建议使用硬珐琅以获得更好的效果。",
"quality_notes": "批量生产前检查电镀和珐琅颜色。"
}
```
## 安全边界
- 无 AI 图像生成。
- 无 LLM 或 GPU 推理。
- 无市场。
- 无支付处理。
- 模拟支付链接仅用于工作流程测试，不收集资金。
- 无自动订购。
- 无任意文件读取或写入工具。
- 无 shell 执行工具。
- 除非明确请求未来供应商 API 集成，否则无外部网络调用。
- 无支付信息存储。
- 无敏感身份信息存储。
- 所有供应商定价和可行性必须手动确认。
- 操作员控制台路由需要身份验证的 HTTP-only 同站会话 cookie。
- 本地演示、用户和验收路由需要相同的操作员会话。
- 操作员登录失败次数在 15 分钟内限制为每个 IP 地址 5 次。
- 生产 HTTP MCP 请求需要 bearer API 密钥。
- 演示和验收路由在生产环境中默认禁用，因为它们会创建测试任务。
- 除非配置了确切的 `CORS_ORIGIN` 允许列表，否则浏览器跨源访问被禁用。
## 路线图
下一个里程碑不是更大的平台。它是一条通过 AI 客户端发起并由人类现实操作员交付的真实闭环订单。参见 [ROADMAP.md](./ROADMAP.md) 和 [PRODUCT_SPEC.md](./PRODUCT_SPEC.md)。
## 许可证
MIT
