mps-preflight

Maha Strategies

Maha Strategies 平台：一个 Next.js 应用，提供公开网站和内容发布界面、需要凭证的商业 API，以及其背后的私有运维控制平面。该平台部署在 Vercel 上，网址为 www.mahastrategies.com。

本文件的大部分内容是特定子系统的操作说明——请阅读所需章节，无需通读全文。

技术栈

事项	服务
应用和托管	Next.js（App Router）、React、TypeScript，运行于 Vercel
数据库	Supabase Postgres，启用 RLS，且没有公共访问策略
缓存、速率限制、余额	Upstash Redis，按部署环境划分命名空间
GPU 计算	Modal — workers/maha_workers.py
支付	Stripe — 每条产品线均使用单独的端点和签名密钥
电子邮件	Resend
遥测	Sentry，已清理负载中的敏感信息

本地运行

需要 Node 22 或更高版本。

npm install
npm run dev

应用将在 http://localhost:3000 上提供服务。将 .env.example 复制为 .env.local，并填写当前工作界面所需的配置；大多数功能在缺少相关变量时会进入禁用状态，而不会崩溃。

如需在本地使用数据库，请启动 Supabase（supabase start），并应用 supabase/migrations 和 supabase/seed.sql，后者会提供确定性的测试数据。

检查

npm run typecheck && npm run lint && npm test

npm test 会运行 test/ 中的完整测试套件。每个拉取请求都会在 CI 中运行同样的命令，此外还会执行生产构建、生产依赖项审计，以及下文所述的迁移完整性检查。

在此代码库中开发

以下三条规则是强制执行的，而非默认遵守，因为违反规则会破坏无法重建的状态：

1. 迁移只能追加。 绝不要编辑、重命名或删除已提交的迁移——它可能已经在 Production 中运行。请添加新的向前迁移。文件名格式为 <14-digit UTC timestamp>_<snake_case>.sql，且排序必须晚于 main 上已有的所有迁移。使用以下命令进行验证：

   node --experimental-strip-types scripts/check-migrations.ts
   

2. 账本只能追加。 更正应作为新行添加，退款应作为冲销分录；不得编辑或删除已记录的商业结果。运营人员的干预应通过 MPS 运维控制平面中经过审计且幂等的操作执行，而不是直接写入表。

3. 密钥仅保留在服务器端。 只有 NEXT_PUBLIC_* 变量会传递到浏览器。凭证密钥仅在签发时披露一次，并且只以哈希形式存储。

框架说明：此代码库使用的 Next.js 版本，其 API 可能与较早版本的文档不同。请参阅 AGENTS.md。

运维

运维手册	涵盖内容
docs/agent-discovery-metering.md	衡量 Agent 是否发现了该平台，并如实解读数据
docs/backup-restore.md	演练数据库恢复，并衡量 RTO 和 RPO
docs/database-migrations.md	在生产环境应用架构变更、检测偏差并留存证据
docs/observability.md	Sentry 配置、签名告警验证、就绪状态检查
docs/release-recovery.md	发布健康状况、恢复演练、回滚、彩排、必需的 GitHub 环境
docs/preview-e2e.md	每次 Preview 部署的集成门禁，以及如何让门禁阻止合并
docs/slo-capacity.md	服务目标、错误预算、有界容量测试框架
docs/x402-conformance-corpus.md	与供应商无关的 x402 v2 测试样例和离线参考运行器
docs/x402-declaration-digest-proposal.md	目录证明的发现声明摘要草案及测试向量
docs/x402-doctor.md	实时资源、爬虫、Bazaar 偏差和有界结算诊断
docs/x402-observatory.md	公开的协议正确性观测、收录政策和定期运行
docs/x402-buyer-policy.md	与供应商无关的签名前预算、审批、重放控制和结算验证
SECURITY.md	漏洞报告和平台长期适用的安全假设

对外市场发现矩阵

私有 Market Scout 是一个只读发现流程。它会将可追溯的网络搜索证据提取到 /admin/market-mapping，其中每项提议都必须经过确定性评分和人工审核。它无法发布内容、花费资金、部署或联系任何人。

设置 MARKET_SCOUT_SOURCES=exa 和 EXA_API_KEY 后，默认矩阵会按 UTC 日期轮换五个查询，覆盖 MPS 声明验证、研究简报、文档数据提取和收据操作。每个查询最多检索八条 Exa 结果。

要替换默认值，请设置以下仅供服务端使用的 JSON 环境变量：

MARKET_SCOUT_QUERY_MATRIX={"lanes":[{"id":"claims","label":"Claim verification","queries":["claim verification API pricing","citation audit tool quote"]},{"id":"documents","label":"Document extraction","queries":["PDF table extraction API pricing"]}]}

该矩阵最多允许八个命名通道，每个通道最多十二个查询；Scout 每次每日运行仍只会从各通道中选择五个查询。旧版 MARKET_SCOUT_QUERIES JSON 字符串数组设置仍受支持，并作为单个自定义通道使用，以保持向后兼容。

Agent 咨询网关

POST /api/agent-inquiries 是一个经过身份验证、无约束力的受理端点，用于处理发布在 /agent-offers.json 中的服务。该端点会根据 /agent-inquiry-schema.json 验证请求，将咨询及其首条事件保存到私有 Supabase 台账，然后尝试通过 Resend 通知审核人员。它不会收取付款、创建委托，也不会自动发送工作。

咨询网关接受有名称且存储在数据库中的客户端凭据。凭据的签发和撤销属于私有审核人员操作；没有共享的公开咨询令牌。

启用前，请设置以下部署环境变量：

AGENT_REVIEW_TOKEN=<unique reviewer bearer token>
RESEND_API_KEY=<existing Resend key>

可选的发送配置覆盖项为 AGENT_INQUIRY_FROM 和 AGENT_INQUIRY_TO。请将审核人员令牌保存在服务器端。客户端凭据由私有注册表创建，且只会在签发时显示一次。

经批准的客户端使用 /agent-inquiry-schema.json 中的架构发送 JSON：

curl --request POST https://www.mahastrategies.com/api/agent-inquiries \
  --header "Authorization: Bearer $CLIENT_CREDENTIAL" \
  --header "Content-Type: application/json" \
  --data '{
    "clientRequestId": "client-generated-unique-id",
    "offerId": "rapid-intelligence-brief",
    "requester": { "name": "Requesting principal", "email": "[email protected]" },
    "decision": "The decision this brief will inform.",
    "question": "One clearly defined market, technology, or policy question.",
    "requesterAuthorized": true,
    "agent": { "name": "Approved client agent", "version": "1.0" }
  }'

成功返回 202 仅表示请求已记录，等待人工审核。返回的 notificationStatus 表示可选的邮件通知是否已送达。这两种结果都不代表接受委托、确认购买或承诺服务级别。

启用完整的 Agent 基础设施前，请在 Supabase SQL Editor 中应用 supabase/migrations/20260716_agent_inquiry_ledger.sql、supabase/migrations/20260716_agent_client_credentials.sql、supabase/migrations/20260716_mps_audit_jobs.sql 和 supabase/migrations/20260717_serverless_credential_rate_limits.sql。这些迁移共同创建私有咨询台账、凭据注册表、MPS 审计台账、由数据库维护的事件历史，以及带有 RLS 且没有公开访问策略的原子共享凭据速率限制器。还需要现有的 NEXT_PUBLIC_SUPABASE_URL 和 SUPABASE_SERVICE_ROLE_KEY 部署变量。

部分基于凭据的商业 API 也会通过 20260727000100_privacy_preserving_commercial_api_metering.sql 写入 commercial_api_usage_daily。这是用于 MPS 审计、MPS 额度读取、图书权益检查和结构化图书内容交付的每日汇总计量。它会刻意排除 IP 地址、用户代理、令牌值或指纹、请求和响应正文、引荐来源、电子邮件及访客标识符。只读汇总面板位于 /admin/commercial-api-metering，需要 REVENUE_CONTROL_TOKEN。

审核人员操作使用单独的私有端点：

GET   /api/agent-inquiries/:inquiryId
PATCH /api/agent-inquiries/:inquiryId

两者都要求 Authorization: Bearer <AGENT_REVIEW_TOKEN>。GET 会返回完整的私有请求及其事件历史。PATCH 接受一个操作：start_review、needs_clarification、decline 或 approve_for_scoping；最后一项是内部处理结果，不代表接受委托。

客户端凭据注册表

审核人员可通过以下私有操作端点进行操作：

GET  /api/agent-credentials
POST /api/agent-credentials
GET  /api/agent-credentials/:credentialId
PATCH /api/agent-credentials/:credentialId

所有端点都要求 Authorization: Bearer <AGENT_REVIEW_TOKEN>。POST 会签发凭据，其明文值仅在该响应中返回。请提供一个新的 clientName 或现有的 clientId，以及 credentialLabel、一个或多个 allowedOfferIds 和／或可选的 allowedCapabilities、可选的 rateLimitPerHour（默认值为 12）以及可选的 expiresAt（默认值为 90 天）。允许仅使用能力的凭据。能力默认不启用；目前唯一的能力是 mps_audit。PATCH 接受 { "action": "revoke", "reason": "optional note" }。GET 端点绝不会返回凭据密钥。

签发示例：

curl --request POST https://www.mahastrategies.com/api/agent-credentials \
  --header "Authorization: Bearer $AGENT_REVIEW_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "clientName": "Example client agent",
    "credentialLabel": "Production research intake",
    "allowedOfferIds": ["rapid-intelligence-brief"],
    "allowedCapabilities": ["mps_audit"],
    "rateLimitPerHour": 12
  }'

受能力门控的 MPS 审计 API

POST /api/mps-audits 将无头 MPS/0.1 引擎应用于单个段落。它要求使用具名客户端凭据，且该凭据明确具有 mps_audit 能力；此 API 使用与该凭据相同的速率限制，并在 Supabase 中存储幂等审计记录。系统会处理源段落，但刻意不予保留；记录会保留输入哈希、输出声明摘录、模型标识符、状态和事件历史。这是计算型 API，不构成认证，也不能替代人工核验。

请求架构发布于 /mps-audit-schema.json。请使用唯一的 clientRequestId；如果使用相同的值但文本不同，则会返回 409。已完成的响应包含审计结果。使用相同请求 ID 和段落重放时，会返回已存储的结果，不会再次调用模型。

curl --request POST https://www.mahastrategies.com/api/mps-audits \
  --header "Authorization: Bearer $MPS_AUDIT_CREDENTIAL" \
  --header "Content-Type: application/json" \
  --data '{
    "clientRequestId": "example-audit-20260716-01",
    "text": "In 2024, the company reported a 32 percent increase in output."
  }'

公开 MPS 审计预检

/audit 是免费的、有限制的公开 MPS 预检。它接受最多 6,000 个字符的段落，在浏览器中返回声明映射，并允许访客下载不含源文本的 JSON 记录。它与需凭据的 API 以及 /mps/preflight 上的付费私有 Preflight 不同。

部署此版本前，请应用 supabase/migrations/20260717_public_mps_audit_usage.sql 并设置仅限服务器使用的 MPS_PUBLIC_AUDIT_RATE_LIMIT_SECRET。该密钥会对 IP 和用户代理组成的访客指纹进行 HMAC 运算，以实施每天三次的配额；公开用量表或事件表均不会保存源文本或源文本哈希。公开事件表仅记录已提交、已完成、失败和记录下载事件及其计数／时间戳，以便衡量转化率，同时不收集段落内容。

MPS 审计预付费访问

仓库包含位于 /mps/audit-access 的 Stripe 自助结账功能。每次购买都会创建一个仅限 mps_audit 的休眠凭据；Stripe 签名 Webhook 会以原子方式发放已配置的 mps_audit_invocation 套餐并激活该凭据。密钥只会在购买者的浏览器中显示一次。

此功能默认禁用。要使 POST /api/mps-credits/checkout 能够创建结账，请先应用 20260717_mps_audit_credit_ledger.sql、20260717_self_service_mps_audit_access.sql 和 20260717_stripe_webhook_idempotency.sql 迁移，配置专用 Stripe Price、位于 /api/mps-credits/webhook 的专用 Webhook 端点，以及以下所有仅限服务器使用的变量：

STRIPE_MPS_AUDIT_CREDIT_PRICE_ID
MPS_AUDIT_CREDIT_PACK_UNITS
MPS_AUDIT_CREDIT_CHECKOUT_ENABLED=true
STRIPE_MPS_CREDITS_WEBHOOK_SECRET

请为该端点订阅 checkout.session.completed、checkout.session.async_payment_succeeded、refund.created 和 refund.updated。付款成功后会添加一条购买授予记录；退款成功后会添加一条按比例冲销的记录，而不会修改授予记录。Webhook 迁移会在唯一约束下记录每个 Stripe evt_ ID，并以原子方式将该事件记录与账本变更一同提交。重复事件会收到确认，但不会再次更改余额；如果退款事件先于购买授予事件到达，则会收到可重试的响应，直到相应的结账授予记录存在。

GET /api/mps-credits 会返回已认证客户端的账本余额。对于预付费凭据，POST /api/mps-audits 会以原子方式预留一个额度；如果没有剩余额度，则返回 HTTP 402 和购买 URL；如果执行失败，则会创建一条幂等退款记录。现有凭据默认使用 internal_meter，并保留之前仅按计量收费的行为，不实施额度检查。

书籍结账 Webhook 必须订阅 checkout.session.completed、checkout.session.async_payment_succeeded、refund.created、refund.updated 和 charge.dispute.closed。付款成功后只会生成一次书籍访问权。每笔 Stripe 退款只会记录一次已确认的退款对象；只有当累计冲销金额达到原始付款金额时，才会撤销访问权。只有在 Stripe 将争议关闭为败诉时，才会撤销访问权限。

MPS 运营控制平面

在预付额度和 Stripe webhook 迁移之后，应用 supabase/migrations/20260718_mps_operational_control_plane.sql，然后配置专用的、仅限服务端使用的 MPS_OPERATIONS_TOKEN。不要重复使用 AGENT_REVIEW_TOKEN。控制平面没有公共 UI，也绝不会返回已存储的密钥哈希或明文凭据。

执行任何干预前，请先使用精确匹配查询端点。请求正文不会让收据邮箱和客户标识符出现在 URL/访问日志中。支持的值包括收据邮箱、客户端 ID、凭据 ID、14 个字符的凭据前缀、结账 ID、Stripe Checkout Session ID、PaymentIntent ID、Refund ID 或 Event ID。

curl --request POST https://www.mahastrategies.com/api/admin/mps-operations/lookup \
  --header "Authorization: Bearer $MPS_OPERATIONS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"query":"[email protected]"}'

变更使用 /api/admin/mps-operations/actions。每个请求都必须包含操作人员提供的唯一幂等键、原因，以及外部工单或 Stripe 参考信息。数据库会在一个事务中提交变更和不可变的操作人员操作记录。

追加额度更正；切勿编辑或删除现有账本行：

{
  "action": "credit_adjustment",
  "clientId": "client_...",
  "quantity": 1,
  "idempotencyKey": "support-ticket-1042-credit-restore",
  "reason": "Restore one credit after a confirmed engine failure.",
  "referenceId": "ticket-1042"
}

立即撤销处于有效或待付款状态的凭据：

{
  "action": "credential_revocation",
  "credentialId": "cred_...",
  "idempotencyKey": "abuse-case-1043-revoke",
  "reason": "Credential reported as compromised.",
  "referenceId": "ticket-1043"
}

为丢失的有效预付 MPS 凭据办理更换，同时保留其客户端级余额：

{
  "action": "credential_replacement",
  "credentialId": "cred_...",
  "idempotencyKey": "support-ticket-1044-replace",
  "reason": "Customer lost the only plaintext copy.",
  "referenceId": "ticket-1044"
}

更换操作会以原子方式撤销旧凭据，并仅返回一次新的明文凭据。幂等重放会确认原有更换操作，但无法再次披露其明文凭据。通过获准的密钥共享渠道发送新凭据；切勿将其放入工单、日志、源代码管理或聊天中。可以使用 Supabase Studio 进行检查，但所有余额更正、撤销和更换都必须通过这些经过审计的操作执行，而不是直接编辑表。

从报价到现金收入控制平面

应用 supabase/migrations/20260720001900_revenue_control_plane.sql 和 supabase/migrations/20260720002000_revenue_event_reconciliation.sql，然后配置单独的、仅限服务端使用的 REVENUE_CONTROL_TOKEN。不要重复使用审核人员或 MPS 操作令牌。私有端点为：

POST /api/admin/revenue-control-plane

它只记录非个人身份信息（PII）的来源参考信息、报价路由和不可变的商业结果事件。它无法发送外联消息、向客户收费、签署合同、操作钱包或接受合作。现有自助服务报价会跳转到各自当前的购买页面；Rapid Intelligence Brief 和 Verified Research Brief 信号仍须由人工确认范围和价格。

使用稳定的来源参考信息路由入站信号：

{
  "action": "route_inbound",
  "idempotencyKey": "inbound-brief-1042",
  "reason": "Qualified website inquiry entered the commercial review queue.",
  "referenceId": "contact-1042",
  "signal": {
    "sourceType": "website_contact",
    "sourceReference": "contact-1042",
    "offerId": "rapid-intelligence-brief",
    "hasDefinedDecision": true,
    "hasSpecificQuestion": true,
    "hasOrganization": true
  }
}

之后使用不同的幂等键记录有状态的结果。paid 和 refunded 状态需要正数的 amountCents 和三字母货币代码。账本仅允许有效的状态转换：从路由/审核转为结账、从结账转为已付款、从已付款转为已交付，以及从已付款或已交付转为已退款。

已验证的 Stripe 付款和撤销 webhook 现在会自动同步到此账本。MPS 审计额度和图书权益仅在现有产品 webhook 发放访问权限后才会标记为已交付；MPS Preflight 则会在报告完成时记录交付。Stripe 仍是付款的权威来源，收入控制平面令牌不会发送给 Stripe 或浏览器。

运维与可观测性

平台包含经过隐私清理的 Sentry 错误与性能遥测、Redis 和 Modal MCP 依赖追踪、带签名的低额度与上游连接状态 Webhook，以及私有配置就绪状态端点。环境变量、签名验证、仪表板和发布测试详见运维手册。

生产发布健康检查每小时运行四次，保留确切的最后一个已知良好 Vercel 部署，并支持由审核者把关的回滚，以及恢复后的就绪状态检查和完整的金丝雀验证。详见发布恢复手册。

内部可用性和延迟目标通过有界的 Preview 容量测试工具执行，该工具覆盖公共界面、就绪状态依赖项、Upstash 键查找，以及需明确确认的受控上游 MCP 配置文件。详见服务目标与容量验收。

入站收入把关

应用 supabase/migrations/20260720002100_inbound_revenue_gatekeeper.sql。公众和 Agent 提交者通过 POST /api/inbound-submissions 提交，架构位于 /inbound-submission-schema.json，机器可读的 Agent 卡片位于 /.well-known/agent.json。该端点使用基于数据库的每小时速率限制、蜜罐、严格的大小和架构验证，以及确定性资格判定。所有已接受的提交都会被转交至私有 Revenue Control Plane，但绝不会创建承诺、付款、合同或自动外联。

定时执行的 GET /api/cron/inbound-digest 端点每天发送一次未发送的合格提交摘要。请配置 INBOUND_DIGEST_TO 和 Vercel 的 CRON_SECRET；INBOUND_DIGEST_TOKEN 仅供另行授权的手动触发使用。vercel.json 将 Vercel Cron 调用安排在 UTC 13:00。摘要包含个人联系信息，因此请对收件人地址保密。

入站运营队列

应用 supabase/migrations/20260720003200_inbound_operations_queue.sql，配置单独的、仅供服务端使用的 INBOUND_OPERATIONS_TOKEN，然后打开 /admin/inbound。私有队列会显示入站资格判定、联系背景信息、关联的收入状态，以及仅追加的审核历史记录。其操作仅限于审核、请求澄清、批准范围、转介至结账、拒绝和标记为流失。它不能发送任何消息、接受合作，也不能将付款标记为已收到。