product-spec-mcp 0.3.34 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,77 @@
+# Changelog
+
+## 0.4.0 - Self-serve Online Gate connection
+
+- Added `product_spec_connect` so Agents can guide users through connecting the Online PM Gate without manual token copying.
+- Added a Worker `/connect` page and `/v1/connect-token` endpoint that generate `product-spec-mcp-connect.json` files with `psm_` scoped tokens.
+- Added D1 token and usage tables for per-token daily/monthly quota tracking and future paid access.
+- Kept legacy `GATE_TOKEN` compatibility while allowing generated `psm_` tokens to call `/v1/pm-intent`.
+- Added connect-flow docs, README guidance, Worker tests, and black-box MCP regression coverage for the new tool.
+
+## 0.3.28 - Mimo JSON response hardening
+
+- Added `response_format: { type: "json_object" }` to Online Gate LLM calls.
+- Strengthened the remote gate prompt with a compact JSON example and stricter JSON-only instructions.
+- Made OpenAI-compatible response parsing tolerate content arrays, reasoning content, plain text choices, and fenced JSON.
+- Verified the deployed Worker can call `mimo-v2.5` and return a valid `data_visualization_site` decision.
+
+## 0.3.27 - Mimo online gate default
+
+- Switched the Cloudflare Online Gate template default provider to Mimo's OpenAI-compatible endpoint.
+- Defaulted the remote gate model to `mimo-v2.5` with `LLM_PROVIDER`, `LLM_BASE_URL`, and `LLM_MODEL` Worker vars.
+- Kept DeepSeek as a later switchable provider through Worker vars and `DEEPSEEK_API_KEY`.
+
+## 0.3.26 - PM intent gate
+
+- Added a PM-style intent gate that classifies usage scope, maintenance mode, access topology, technical shape, and deployment direction before domain templates.
+- Added gate-specific handling for multi-user collaboration, content marketing sites, and xlsx/csv data visualization sites, including safer defaults and boundary questions.
+- Added an optional remote Online Gate client protocol with local-rule fallback, schema validation, prompt truncation, telemetry mode, and hard local corrections.
+- Added a Cloudflare Workers P0 Online Gate template with KV prompt cache, IP daily limit, D1 redacted sample storage, and an OpenAI-compatible JSON classification provider.
+- Carried `pmIntentDecision` through assist, compile, architecture, and acceptance structured outputs.
+- Added regression coverage for household tools, roommate task collaboration, gym GEO content sites, xlsx chart sites, and negative local/static/backend routing cases.
+
+## 0.3.25 - Local MVP spec quality
+
+- Fed local tool signals into generic local-first spec generation so MVP drafts include concrete fields, data examples, and acceptance criteria.
+- Defaulted recognizable household/local record tools to Draft Ready with localStorage scope instead of showing contradictory Not Ready wording.
+- Kept the change horizontal: no new medicine domain pack, and backend/domain upgrades still require explicit signals.
+
+## 0.3.24 - Beginner MVP draft output
+
+- Changed generic local-first beginner requests to return an MVP spec draft from `product_spec_assist` instead of only an interrogation result.
+- Included architecture, data, API, non-goals, and acceptance sections in local-first draft markdown while keeping backend upgrades gated by explicit signals.
+- Added regression coverage so household medicine requests produce a lightweight localStorage MVP draft without registration/admin template pollution.
+
+## 0.3.23 - Visual polish is not backend scope
+
+- Clarified that "页面高级一点" affects UI direction and acceptance, not backend/login/database scope.
+- Added local beginner-tool guidance that advanced visual polish remains compatible with `localStorage`.
+- Added regression coverage to prevent agents from treating visual quality as a reason to override local-first architecture.
+
+## 0.3.22 - Beginner default flow guidance
+
+- Changed local beginner tool assist results to recommend `spec_compile` with defaults instead of blocking on all questions.
+- Added agent guidance to avoid asking users to answer raw quickQuestions or compact choices like `B + a`.
+- Kept quickQuestions available for structured consumers while encouraging one natural-language confirmation at most.
+
+## 0.3.21 - Local tool signal extraction
+
+- Added horizontal signal extraction for beginner local tools without adding new domain packs.
+- Contextualized local-first quick questions with inferred record object, fields, reminders, inventory, and visual requirements.
+- Improved generic local-tool specs and acceptance checks for short requests such as household medicine tracking.
+
+## 0.3.20 - README cleanup
+
+- Moved maintainer notes out of the main README flow.
+- Replaced npm-rendered relative docs links with a GitHub maintainer link.
+- Removed client-specific WorkBuddy wording from the public README introduction.
+
+## 0.3.19 - Local-first Gate release candidate
+
+- Added a shared `technicalProfile` across assist, interrogation, compile, architecture, and acceptance outputs.
+- Changed product planning to classify technical complexity before business domain matching.
+- Defaulted beginner/local tools to static pages, browser storage, JSON import/export, or `data.json` pages.
+- Preserved backend/domain handling for registration, AI SaaS, digital commerce, and knowledge-base scenarios.
+- Added beginner-friendly examples to clarification questions.
+- Added black-box MCP regression coverage for local-first and reverse-domain scenarios.
+- Fixed publish/test ordering so fresh clones build `dist/index.cjs` before black-box tests run.

package/README.md

@@ -19,13 +19,16 @@
 
 **不确定用哪个工具？** 先用 `product_spec_assist`，它会自动识别场景并调用合适的工具。
 
+**想启用在线 PM Gate？** 先用 `product_spec_connect`，它会引导用户打开连接页、下载连接文件，并让当前 Agent 把 token 写入 MCP 配置。
+
 ## Features
 
-This MCP Server provides 7 tools for product development workflow:
+This MCP Server provides 8 tools for product development workflow:
 
 | Tool | Description |
 |------|-------------|
 | `product_spec_assist` | **推荐入口** - 根据用户原话自动识别场景并调用对应能力 |
+| `product_spec_connect` | **在线增强连接** - 引导用户下载连接文件，并生成当前 Agent 应写入的 MCP 环境变量 |
 | `spec_interrogate` | Analyze requirement completeness and generate clarification questions |
 | `spec_compile` | Compile full product specification and development prompt |
 | `architecture_decide` | Make architecture decisions based on product type and features |
@@ -58,6 +61,8 @@ npm run dev
 
 默认只使用本地 PM Gate。需要让低置信或冲突需求走在线 LLM 辅助归门时，可以配置独立 HTTP gate：
 
+对普通用户，推荐让 Agent 调用 `product_spec_connect`。用户只需要打开连接页，点击下载 `product-spec-mcp-connect.json`，再把文件发回 Agent；Agent 读取文件后把其中的 `instructions.env` 写入当前 MCP 配置即可。
+
 ```bash
 PRODUCT_SPEC_REMOTE_GATE_URL=https://gate.example.com/v1/pm-intent
 PRODUCT_SPEC_REMOTE_GATE_TOKEN=replace-with-token
@@ -66,7 +71,7 @@ PRODUCT_SPEC_REMOTE_GATE_MODE=auto
 PRODUCT_SPEC_TELEMETRY=off
 ```
 
-`auto` 模式只在本地规则低置信、unknown 或冲突时调用远程。远程失败、限流、超时或 schema 错误时会自动降级到本地判断。Cloudflare Workers 部署模板随 npm 包一起发布，见 `docs/online-pm-gate.md`。
+`auto` 模式只在本地规则低置信、unknown 或冲突时调用远程。远程失败、限流、超时或 schema 错误时会自动降级到本地判断。Cloudflare Workers 部署模板随 npm 包一起发布，见 `docs/online-pm-gate.md` 和 `docs/connect-flow.md`。
 
 ## MCP Client Configuration
 
@@ -181,6 +186,41 @@ Client-specific integration notes are intentionally kept out of the main user fl
 
 ---
 
+### product_spec_connect
+
+引导用户连接在线 PM Gate。未配置时返回连接页面；收到连接文件后返回当前 Agent 应写入 MCP 配置的环境变量。
+
+**Input:**
+- `connect_file`: 用户从连接页下载的 `product-spec-mcp-connect.json` 内容
+- `client`: 当前 Agent 名称，例如 `workbuddy`、`codex`、`opencode`
+
+**Example:**
+```json
+{
+  "client": "workbuddy"
+}
+```
+
+如果用户已经上传连接文件：
+
+```json
+{
+  "client": "workbuddy",
+  "connect_file": {
+    "type": "product-spec-mcp-connect",
+    "instructions": {
+      "env": {
+        "PRODUCT_SPEC_REMOTE_GATE_URL": "https://productmcp.opc-mind.top/v1/pm-intent",
+        "PRODUCT_SPEC_REMOTE_GATE_TOKEN": "psm_xxx",
+        "PRODUCT_SPEC_REMOTE_GATE_MODE": "auto"
+      }
+    }
+  }
+}
+```
+
+---
+
 ### spec_interrogate
 
 Analyze requirement completeness and generate clarification questions.

package/dist/index.cjs

@@ -28252,6 +28252,116 @@ var routes = ["spec_compile", "spec_interrogate", "architecture_decide"];
 var confidences = ["high", "medium", "low"];
 var sources = ["local_rule", "online_llm", "merged"];
 
+// src/core/connectGuide.ts
+var DEFAULT_CONNECT_URL = "https://productmcp.opc-mind.top/connect";
+function buildConnectGuide(connectFile, client = "unknown") {
+  const connectUrl = process.env.PRODUCT_SPEC_CONNECT_URL || DEFAULT_CONNECT_URL;
+  const currentEnv = currentRemoteGateEnv();
+  if (isRemoteGateConfigured() && !connectFile) {
+    return {
+      configured: true,
+      connectUrl,
+      env: currentEnv,
+      steps: [
+        "\u5F53\u524D product-spec MCP \u5DF2\u914D\u7F6E\u5728\u7EBF PM Gate\u3002",
+        "\u7EE7\u7EED\u6B63\u5E38\u4F7F\u7528 product_spec_assist\uFF1B\u4F4E\u7F6E\u4FE1\u6216\u51B2\u7A81\u9700\u6C42\u4F1A\u81EA\u52A8\u5C1D\u8BD5\u5728\u7EBF\u5224\u65AD\u3002"
+      ],
+      warnings: []
+    };
+  }
+  const parsed = parseConnectFile(connectFile);
+  if (parsed.env) {
+    return {
+      configured: false,
+      connectUrl,
+      env: parsed.env,
+      steps: [
+        `\u68C0\u6D4B\u5230\u8FDE\u63A5\u6587\u4EF6\u3002\u8BF7\u628A env \u5199\u5165\u5F53\u524D ${client || "Agent"} \u7684 product-spec-mcp \u914D\u7F6E\u3002`,
+        "\u4FDD\u5B58\u914D\u7F6E\u540E\uFF0C\u91CD\u542F\u6216\u5237\u65B0 MCP Server\u3002",
+        "\u91CD\u542F\u540E\u518D\u6B21\u8C03\u7528 product_spec_connect\uFF0C\u786E\u8BA4 configured=true\u3002"
+      ],
+      warnings: parsed.warnings
+    };
+  }
+  return {
+    configured: false,
+    connectUrl,
+    steps: [
+      `\u6253\u5F00 ${connectUrl}`,
+      "\u70B9\u51FB\u201C\u751F\u6210\u5E76\u4E0B\u8F7D\u8FDE\u63A5\u6587\u4EF6\u201D\u3002",
+      "\u628A\u4E0B\u8F7D\u7684 product-spec-mcp-connect.json \u53D1\u56DE\u5F53\u524D Agent \u5BF9\u8BDD\u3002",
+      "\u8BA9 Agent \u8BFB\u53D6\u8FDE\u63A5\u6587\u4EF6\uFF0C\u5E76\u628A instructions.env \u5199\u5165\u5F53\u524D MCP \u914D\u7F6E\u3002"
+    ],
+    warnings: [
+      "\u4E0D\u8981\u624B\u52A8\u586B\u5199 token\uFF1B\u8FDE\u63A5\u6587\u4EF6\u4E2D\u5DF2\u7ECF\u5305\u542B\u6240\u9700\u914D\u7F6E\u3002",
+      "\u6D4F\u89C8\u5668\u9875\u9762\u4E0D\u80FD\u76F4\u63A5\u4FEE\u6539\u672C\u673A Agent \u914D\u7F6E\uFF0C\u9700\u8981\u628A\u8FDE\u63A5\u6587\u4EF6\u4EA4\u7ED9 Agent \u5B8C\u6210\u3002"
+    ]
+  };
+}
+function isRemoteGateConfigured() {
+  return Boolean(process.env.PRODUCT_SPEC_REMOTE_GATE_URL && process.env.PRODUCT_SPEC_REMOTE_GATE_TOKEN);
+}
+function currentRemoteGateEnv() {
+  const env = {};
+  for (const key of [
+    "PRODUCT_SPEC_REMOTE_GATE_URL",
+    "PRODUCT_SPEC_REMOTE_GATE_TOKEN",
+    "PRODUCT_SPEC_REMOTE_GATE_MODE",
+    "PRODUCT_SPEC_REMOTE_GATE_TIMEOUT_MS",
+    "PRODUCT_SPEC_TELEMETRY"
+  ]) {
+    if (process.env[key]) env[key] = key === "PRODUCT_SPEC_REMOTE_GATE_TOKEN" ? "[CONFIGURED]" : String(process.env[key]);
+  }
+  return env;
+}
+function parseConnectFile(connectFile) {
+  if (!connectFile) return { warnings: [] };
+  const warnings = [];
+  if (connectFile.type !== "product-spec-mcp-connect") {
+    warnings.push("\u8FDE\u63A5\u6587\u4EF6 type \u4E0D\u662F product-spec-mcp-connect\uFF0C\u8BF7\u786E\u8BA4\u6587\u4EF6\u6765\u6E90\u3002");
+  }
+  const instructions = getRecord(connectFile.instructions);
+  const env = getRecord(instructions?.env);
+  if (env) {
+    const normalized = normalizeEnv(env);
+    if (normalized.PRODUCT_SPEC_REMOTE_GATE_URL && normalized.PRODUCT_SPEC_REMOTE_GATE_TOKEN) {
+      return { env: normalized, warnings };
+    }
+  }
+  const remoteGate = getRecord(connectFile.remoteGate);
+  const url = asString(remoteGate?.url);
+  const token = asString(remoteGate?.token);
+  if (url && token) {
+    return {
+      env: {
+        PRODUCT_SPEC_REMOTE_GATE_URL: url,
+        PRODUCT_SPEC_REMOTE_GATE_TOKEN: token,
+        PRODUCT_SPEC_REMOTE_GATE_MODE: asString(remoteGate?.mode) || "auto",
+        PRODUCT_SPEC_REMOTE_GATE_TIMEOUT_MS: String(remoteGate?.timeoutMs || "10000"),
+        PRODUCT_SPEC_TELEMETRY: asString(remoteGate?.telemetry) || "off"
+      },
+      warnings
+    };
+  }
+  warnings.push("\u8FDE\u63A5\u6587\u4EF6\u7F3A\u5C11 PRODUCT_SPEC_REMOTE_GATE_URL \u6216 PRODUCT_SPEC_REMOTE_GATE_TOKEN\u3002");
+  return { warnings };
+}
+function normalizeEnv(env) {
+  const normalized = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+      normalized[key] = String(value);
+    }
+  }
+  return normalized;
+}
+function getRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function asString(value) {
+  return typeof value === "string" ? value : "";
+}
+
 // src/core/assistEngine.ts
 function executeAssist(message, knownContext, preferredPlatform = "unknown", strictness = "normal", autoExecute = true) {
   const routed = routeIntent(message);
@@ -28273,7 +28383,7 @@ async function executeAssistWithRemoteGate(message, knownContext, preferredPlatf
   const result = executeAssist(message, knownContext, preferredPlatform, strictness, autoExecute);
   if (result.routedIntent.scenario !== "build_product" || !result.pmIntentDecision) return result;
   const remote = await callRemotePmIntentGate(message, knownContext || {}, result.pmIntentDecision);
-  if (!remote) return result;
+  if (!remote) return appendConnectHintIfUseful(result);
   const merged = remote.decision;
   if (merged.needType !== result.pmIntentDecision.needType && ["multi_user_collaboration", "content_marketing_site", "data_visualization_site"].includes(merged.needType)) {
     const technicalProfile = buildTechnicalProfile(message, knownContext || {});
@@ -28289,7 +28399,7 @@ async function executeAssistWithRemoteGate(message, knownContext, preferredPlatf
       remote.meta.fallbackReason
     );
   }
-  return appendRemoteGateMeta({ ...result, pmIntentDecision: merged }, remote.meta.fallbackReason);
+  return appendConnectHintIfUseful(appendRemoteGateMeta({ ...result, pmIntentDecision: merged }, remote.meta.fallbackReason));
 }
 function detectPlatform(message, preferred) {
   if (preferred !== "unknown") return preferred;
@@ -28446,6 +28556,19 @@ function appendRemoteGateMeta(result, fallbackReason) {
     ]
   };
 }
+function appendConnectHintIfUseful(result) {
+  const decision = result.pmIntentDecision;
+  if (!decision || isRemoteGateConfigured()) return result;
+  const shouldHint = decision.confidence === "low" || decision.needType === "unknown" || decision.technicalShape === "unknown";
+  if (!shouldHint) return result;
+  return {
+    ...result,
+    agentGuidance: [
+      ...result.agentGuidance,
+      "\u5728\u7EBF PM Gate \u672A\u8FDE\u63A5\uFF1B\u5982\u9700\u63D0\u5347\u4F4E\u7F6E\u4FE1\u9700\u6C42\u7684\u5F52\u95E8\u8D28\u91CF\uFF0C\u53EF\u5148\u8C03\u7528 product_spec_connect\uFF0C\u5F15\u5BFC\u7528\u6237\u4E0B\u8F7D\u8FDE\u63A5\u6587\u4EF6\u5E76\u7531 Agent \u5199\u5165 MCP \u914D\u7F6E\u3002"
+    ]
+  };
+}
 function buildPmGateInterrogateResult(message, routed, technicalProfile, pmIntentDecision, quickQuestions) {
   const title = formatNeedTypeTitle(pmIntentDecision.needType);
   return {
@@ -29972,11 +30095,66 @@ function registerProductSpecAssist(server) {
   );
 }
 
+// src/schemas/productSpecConnect.schema.ts
+var ProductSpecConnectInputSchema = external_exports.object({
+  connect_file: external_exports.record(external_exports.string(), external_exports.unknown()).optional().describe("\u7528\u6237\u4ECE /connect \u4E0B\u8F7D\u7684 product-spec-mcp-connect.json \u5185\u5BB9"),
+  client: external_exports.string().optional().describe("\u5F53\u524D Agent \u6216 MCP \u5BA2\u6237\u7AEF\u540D\u79F0\uFF0C\u4F8B\u5982 workbuddy\u3001claude_desktop\u3001cursor\u3001codex\u3001unknown")
+});
+
+// src/schemas/outputs/productSpecConnect.output.ts
+var ProductSpecConnectOutputSchema = external_exports.object({
+  configured: external_exports.boolean(),
+  connectUrl: external_exports.string(),
+  env: external_exports.record(external_exports.string()).optional(),
+  steps: external_exports.array(external_exports.string()),
+  warnings: external_exports.array(external_exports.string())
+});
+
+// src/tools/productSpecConnect.ts
+function registerProductSpecConnect(server) {
+  const handler = async (input) => {
+    const result = buildConnectGuide(input.connect_file, input.client || "unknown");
+    return {
+      content: [{ type: "text", text: formatConnectGuide(result) }],
+      structuredContent: result
+    };
+  };
+  server.registerTool(
+    "product_spec_connect",
+    {
+      title: "\u8FDE\u63A5\u5728\u7EBF PM Gate",
+      description: "\u5F15\u5BFC\u7528\u6237\u8FDE\u63A5 product-spec MCP \u5728\u7EBF PM Gate\u3002\u672A\u914D\u7F6E\u65F6\u8FD4\u56DE /connect \u4E0B\u8F7D\u8FDE\u63A5\u6587\u4EF6\uFF1B\u6536\u5230\u8FDE\u63A5\u6587\u4EF6\u540E\u8FD4\u56DE\u5E94\u5199\u5165\u5F53\u524D Agent MCP \u914D\u7F6E\u7684\u73AF\u5883\u53D8\u91CF\u3002",
+      inputSchema: ProductSpecConnectInputSchema.shape,
+      outputSchema: ProductSpecConnectOutputSchema.shape
+    },
+    handler
+  );
+}
+function formatConnectGuide(result) {
+  const lines = [
+    "# product-spec MCP \u5728\u7EBF\u589E\u5F3A\u8FDE\u63A5",
+    "",
+    `- **\u5F53\u524D\u72B6\u6001:** ${result.configured ? "\u5DF2\u914D\u7F6E" : "\u672A\u914D\u7F6E\u6216\u5F85\u5199\u5165\u914D\u7F6E"}`,
+    `- **\u8FDE\u63A5\u9875\u9762:** ${result.connectUrl}`,
+    "",
+    "## \u4E0B\u4E00\u6B65",
+    "",
+    ...result.steps.map((step, index) => `${index + 1}. ${step}`)
+  ];
+  if (result.env) {
+    lines.push("", "## \u9700\u8981\u5199\u5165 MCP \u914D\u7F6E\u7684\u73AF\u5883\u53D8\u91CF", "", "```json", JSON.stringify(result.env, null, 2), "```");
+  }
+  if (result.warnings.length > 0) {
+    lines.push("", "## \u6CE8\u610F", "", ...result.warnings.map((warning) => `- ${warning}`));
+  }
+  return lines.join("\n");
+}
+
 // src/server.ts
 function createServer() {
   const server = new McpServer({
     name: "product-spec-mcp",
-    version: "0.3.34"
+    version: "0.4.0"
   });
   registerSpecInterrogate(server);
   registerSpecCompile(server);
@@ -29985,6 +30163,7 @@ function createServer() {
   registerDebugGuide(server);
   registerAcceptanceGenerate(server);
   registerProductSpecAssist(server);
+  registerProductSpecConnect(server);
   return server;
 }
 

package/docs/connect-flow.md

@@ -0,0 +1,152 @@
+# product-spec MCP 0.4 Connect Flow
+
+目标：让普通用户不用手抄 token，也不用理解不同 Agent 的 MCP 配置格式。用户只做三步：
+
+1. Agent 提示打开连接页。
+2. 用户点击下载 `product-spec-mcp-connect.json`。
+3. 用户把连接文件发回 Agent，由 Agent 写入 MCP 配置。
+
+## User Flow
+
+Agent 侧先调用：
+
+```json
+{
+  "tool": "product_spec_connect",
+  "arguments": {
+    "client": "current-agent-name"
+  }
+}
+```
+
+MCP 返回连接页，默认是：
+
+```text
+https://productmcp.opc-mind.top/connect
+```
+
+用户打开页面后点击“生成并下载连接文件”。页面调用 Worker：
+
+```http
+POST /v1/connect-token
+```
+
+Worker 会创建一个 `psm_` 开头的专属 token，并返回连接文件。
+
+## Connect File
+
+下载文件名：
+
+```text
+product-spec-mcp-connect.json
+```
+
+文件格式：
+
+```json
+{
+  "type": "product-spec-mcp-connect",
+  "version": 1,
+  "remoteGate": {
+    "url": "https://productmcp.opc-mind.top/v1/pm-intent",
+    "token": "psm_xxx",
+    "mode": "auto",
+    "timeoutMs": 10000,
+    "telemetry": "off"
+  },
+  "instructions": {
+    "summary": "请把 remoteGate 配置写入当前 Agent 的 product-spec-mcp 环境变量。",
+    "env": {
+      "PRODUCT_SPEC_REMOTE_GATE_URL": "https://productmcp.opc-mind.top/v1/pm-intent",
+      "PRODUCT_SPEC_REMOTE_GATE_TOKEN": "psm_xxx",
+      "PRODUCT_SPEC_REMOTE_GATE_MODE": "auto",
+      "PRODUCT_SPEC_REMOTE_GATE_TIMEOUT_MS": "10000",
+      "PRODUCT_SPEC_TELEMETRY": "off"
+    }
+  }
+}
+```
+
+Agent 收到文件后，再调用：
+
+```json
+{
+  "tool": "product_spec_connect",
+  "arguments": {
+    "client": "current-agent-name",
+    "connect_file": {}
+  }
+}
+```
+
+把真实文件 JSON 放到 `connect_file`。MCP 会返回应写入当前 Agent MCP 配置的 `env`。
+
+## Agent Responsibility
+
+Agent 应做的事：
+
+- 读取 `instructions.env`。
+- 写入当前 Agent 的 product-spec MCP server 配置。
+- 重启或刷新 MCP server。
+- 再调用 `product_spec_connect` 验证 `configured=true`。
+
+Agent 不应该做的事：
+
+- 不要让用户手抄 token。
+- 不要把 token 打印到公开日志。
+- 不要把连接文件提交到 Git。
+- 不要把 `psm_` token 写入项目源码。
+
+## Worker Endpoints
+
+```http
+GET /connect
+POST /v1/connect-token
+POST /v1/pm-intent
+GET /health
+```
+
+`/v1/pm-intent` 同时接受两类 token：
+
+- 旧的全局 `GATE_TOKEN`，用于内部验证和兼容老配置。
+- 新的 `psm_` token，用于用户自助连接和后续计量。
+
+## Storage
+
+D1 新增两张表：
+
+```sql
+api_tokens
+usage_events
+```
+
+`api_tokens` 存 token hash，不存明文 token。`usage_events` 记录按 token 的 LLM 使用情况，后续可以接入计费、月额度、封禁和用户面板。
+
+## Quotas
+
+默认每日额度仍由 Worker 变量控制：
+
+```toml
+DAILY_LLM_LIMIT = "20"
+```
+
+连接页生成的新 token 默认继承 `DAILY_LLM_LIMIT`。如果需要给连接 token 单独设置每日额度，可配置：
+
+```toml
+CONNECT_TOKEN_DAILY_LIMIT = "20"
+```
+
+如果需要月额度，可配置：
+
+```toml
+CONNECT_TOKEN_MONTHLY_LIMIT = "600"
+```
+
+改这些值只需要重新部署 Worker，或在 Cloudflare Dashboard 修改 Worker 环境变量，不需要发布 npm。
+
+## Security Notes
+
+- 连接文件包含访问 token，只应交给当前 Agent。
+- Worker 只把 token hash 写入 D1。
+- MCP 本地包不内置任何用户 token。
+- 远程失败、限流或超时时，本地 MCP 会降级到本地 PM Gate。

package/docs/online-pm-gate.md

@@ -76,10 +76,37 @@ Runtime behavior:
 - Prompt cache key: `cache:{model}:{promptHash}:pm-gate-v1`
 - Cache TTL: 7 days
 - LLM quota: `DAILY_LLM_LIMIT` non-cached LLM decisions per IP per Shanghai calendar day. Default: 20.
+- Self-serve token quota: `CONNECT_TOKEN_DAILY_LIMIT` can override the daily limit for newly generated `psm_` tokens. If omitted, it inherits `DAILY_LLM_LIMIT`.
+- Optional monthly token quota: `CONNECT_TOKEN_MONTHLY_LIMIT` limits monthly non-cached LLM calls per token.
 - User message sent to LLM: max 500 characters
 - LLM max output tokens: 600
 - LLM temperature: 0.1
 
+## Self-Serve Connect Flow
+
+0.4 版本新增浏览器连接页，给非技术用户使用：
+
+```http
+GET /connect
+POST /v1/connect-token
+```
+
+用户打开 `/connect` 后点击下载 `product-spec-mcp-connect.json`。文件里包含当前 Agent 应写入 MCP 配置的环境变量：
+
+```json
+{
+  "PRODUCT_SPEC_REMOTE_GATE_URL": "https://productmcp.opc-mind.top/v1/pm-intent",
+  "PRODUCT_SPEC_REMOTE_GATE_TOKEN": "psm_xxx",
+  "PRODUCT_SPEC_REMOTE_GATE_MODE": "auto",
+  "PRODUCT_SPEC_REMOTE_GATE_TIMEOUT_MS": "10000",
+  "PRODUCT_SPEC_TELEMETRY": "off"
+}
+```
+
+MCP 侧对应工具是 `product_spec_connect`。Agent 应先调用它拿连接页；用户上传连接文件后，再调用它解析出应写入当前 MCP 配置的 `env`。
+
+`psm_` token 会写入 D1 的 `api_tokens` 表，Worker 只存 hash，不存明文 token。调用 `/v1/pm-intent` 时，Worker 仍兼容旧的全局 `GATE_TOKEN`。
+
 ## Change LLM Daily Quota
 
 `DAILY_LLM_LIMIT` controls the number of non-cached LLM gate calls allowed per IP per Shanghai calendar day. It is a Worker runtime variable, not an npm package setting.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "product-spec-mcp",
-  "version": "0.3.34",
+  "version": "0.4.0",
   "description": "MCP Server for product specification - requirement interrogation, architecture decision, UI translation, debug guidance, and acceptance generation",
   "type": "commonjs",
   "main": "dist/index.cjs",
@@ -9,7 +9,9 @@
   },
   "files": [
     "dist/index.cjs",
+    "CHANGELOG.md",
     "README.md",
+    "docs/connect-flow.md",
     "docs/online-pm-gate.md",
     "workers/pm-intent-gate.mjs",
     "workers/schema.sql",

package/workers/pm-intent-gate.mjs

@@ -10,12 +10,19 @@ export default {
   async fetch(request, env) {
     const url = new URL(request.url);
     if (request.method === "GET" && url.pathname === "/health") {
-      return json({ ok: true, gateSchemaVersion: GATE_SCHEMA_VERSION });
+      return json({ ok: true, gateSchemaVersion: GATE_SCHEMA_VERSION, connect: true });
+    }
+    if (request.method === "GET" && url.pathname === "/connect") {
+      return html(connectPageHtml(url.origin));
+    }
+    if (request.method === "POST" && url.pathname === "/v1/connect-token") {
+      return createConnectToken(request, env, url.origin);
     }
     if (request.method !== "POST" || url.pathname !== "/v1/pm-intent") {
       return json({ error: "not_found" }, 404);
     }
-    if (!isAuthorized(request, env)) {
+    const auth = await authorizeRequest(request, env);
+    if (!auth.ok) {
       return json({ error: "unauthorized" }, 401);
     }
 
@@ -35,6 +42,7 @@ export default {
     const ipKey = await rateLimitKey(request, env);
     const resetAt = nextShanghaiMidnightIso();
     const dailyLimit = resolveDailyLimit(env);
+    const tokenLimit = auth.token ? resolveTokenDailyLimit(auth.token, dailyLimit) : null;
 
     if (cached?.decision) {
       await maybeStoreSample(env, telemetryMode, body, cached.decision, cached.decision, {
@@ -42,6 +50,15 @@ export default {
         cacheHit: 1,
         rateLimitStatus: "cache_hit",
       });
+      await maybeStoreUsageEvent(env, auth, {
+        llmUsed: 0,
+        cacheHit: 1,
+        model: llm.model,
+        promptTokensApprox: cached.promptTokensApprox || 0,
+        completionTokensApprox: cached.completionTokensApprox || 0,
+        costUnits: 0,
+      });
+      const remaining = await combinedRemaining(env, ipKey, dailyLimit, auth.token, tokenLimit);
       return json({
         decision: cached.decision,
         llmGate: {
@@ -53,26 +70,34 @@ export default {
           cacheHit: true,
         },
         rateLimit: {
-          limit: dailyLimit,
-          remaining: await remainingForKey(env, ipKey, dailyLimit),
+          limit: tokenLimit || dailyLimit,
+          remaining,
           resetAt,
         },
         privacy: privacyResult(telemetryMode),
       });
     }
 
-    const limit = await consumeLimit(env, ipKey, resetAt, dailyLimit);
+    const limit = await consumeCombinedLimit(env, ipKey, resetAt, dailyLimit, auth.token, tokenLimit);
     if (!limit.allowed) {
       await maybeStoreSample(env, telemetryMode, body, null, body.ruleDecision || {}, {
         llmUsed: 0,
         cacheHit: 0,
         rateLimitStatus: "limited",
-        fallbackReason: "rate_limited",
+        fallbackReason: limit.reason || "rate_limited",
+      });
+      await maybeStoreUsageEvent(env, auth, {
+        llmUsed: 0,
+        cacheHit: 0,
+        model: llm.model,
+        promptTokensApprox: 0,
+        completionTokensApprox: 0,
+        costUnits: 0,
       });
       return json({
         decision: fallbackDecision(body.ruleDecision),
         llmGate: { used: false, provider: llm.provider, model: llm.model, cacheHit: false },
-        rateLimit: { limit: dailyLimit, remaining: 0, resetAt },
+        rateLimit: { limit: tokenLimit || dailyLimit, remaining: 0, resetAt },
         privacy: privacyResult(telemetryMode),
       }, 429);
     }
@@ -109,6 +134,14 @@ export default {
       rateLimitStatus: "allowed",
       fallbackReason,
     });
+    await maybeStoreUsageEvent(env, auth, {
+      llmUsed: llmDecision ? 1 : 0,
+      cacheHit: 0,
+      model: llm.model,
+      promptTokensApprox,
+      completionTokensApprox,
+      costUnits: llmDecision ? 1 : 0,
+    });
 
     return json({
       decision: finalDecision,
@@ -122,7 +155,7 @@ export default {
         ...(fallbackReason ? { fallbackReason } : {}),
       },
       rateLimit: {
-        limit: dailyLimit,
+        limit: tokenLimit || dailyLimit,
         remaining: limit.remaining,
         resetAt,
       },
@@ -131,9 +164,28 @@ export default {
   },
 };
 
-function isAuthorized(request, env) {
-  if (!env.GATE_TOKEN) return false;
-  return request.headers.get("authorization") === `Bearer ${env.GATE_TOKEN}`;
+async function authorizeRequest(request, env) {
+  const token = parseBearerToken(request);
+  if (!token) return { ok: false, kind: "none" };
+  if (env.GATE_TOKEN && token === env.GATE_TOKEN) return { ok: true, kind: "legacy" };
+  if (!token.startsWith("psm_")) return { ok: false, kind: "unknown" };
+  if (!env.PROMPT_SAMPLES) return { ok: false, kind: "token", reason: "missing_d1" };
+  await ensureConnectTables(env);
+  const tokenHash = await sha256(token);
+  const row = await env.PROMPT_SAMPLES.prepare(
+    "SELECT id, token_prefix, daily_limit, monthly_limit, enabled FROM api_tokens WHERE token_hash = ? LIMIT 1"
+  ).bind(tokenHash).first();
+  if (!row || Number(row.enabled) !== 1) return { ok: false, kind: "token" };
+  await env.PROMPT_SAMPLES.prepare("UPDATE api_tokens SET last_used_at = ? WHERE id = ?")
+    .bind(new Date().toISOString(), row.id)
+    .run();
+  return { ok: true, kind: "token", token: row };
+}
+
+function parseBearerToken(request) {
+  const header = request.headers.get("authorization") || "";
+  const match = header.match(/^Bearer\s+(.+)$/i);
+  return match ? match[1].trim() : "";
 }
 
 function buildGatePrompt(message, rule, choices) {
@@ -202,6 +254,183 @@ function resolveDailyLimit(env) {
   return Math.floor(parsed);
 }
 
+function resolveTokenDailyLimit(token, fallback) {
+  const parsed = Number(token?.daily_limit || fallback);
+  if (!Number.isFinite(parsed) || parsed <= 0) return fallback;
+  return Math.floor(parsed);
+}
+
+function resolveConnectTokenDailyLimit(env) {
+  const parsed = Number(env.CONNECT_TOKEN_DAILY_LIMIT || env.DAILY_LLM_LIMIT || DEFAULT_DAILY_LIMIT);
+  if (!Number.isFinite(parsed) || parsed <= 0) return DEFAULT_DAILY_LIMIT;
+  return Math.floor(parsed);
+}
+
+async function createConnectToken(request, env, origin) {
+  if (!env.PROMPT_SAMPLES) return json({ error: "missing_d1_binding" }, 503);
+  await ensureConnectTables(env);
+  let body = {};
+  try {
+    body = await request.json();
+  } catch {
+    body = {};
+  }
+  const token = `psm_${randomToken(32)}`;
+  const tokenHash = await sha256(token);
+  const id = crypto.randomUUID();
+  const now = new Date().toISOString();
+  const dailyLimit = resolveConnectTokenDailyLimit(env);
+  const monthlyLimit = positiveIntegerOrNull(env.CONNECT_TOKEN_MONTHLY_LIMIT);
+  const client = sanitizeShortText(body.client || "unknown", 40);
+  const label = sanitizeShortText(body.label || `${client} connect token`, 80);
+
+  await env.PROMPT_SAMPLES.prepare(
+    `INSERT INTO api_tokens (
+      id, token_hash, token_prefix, label, daily_limit, monthly_limit, enabled, created_at, last_used_at
+    ) VALUES (?, ?, ?, ?, ?, ?, 1, ?, NULL)`
+  ).bind(
+    id,
+    tokenHash,
+    token.slice(0, 12),
+    label,
+    dailyLimit,
+    monthlyLimit,
+    now
+  ).run();
+
+  const remoteGateUrl = resolveRemoteGateUrl(env, origin);
+  const connectFile = buildConnectFile(remoteGateUrl, token);
+  return json({
+    ok: true,
+    tokenPrefix: token.slice(0, 12),
+    dailyLimit,
+    monthlyLimit,
+    connectFile,
+  });
+}
+
+function buildConnectFile(remoteGateUrl, token) {
+  const env = {
+    PRODUCT_SPEC_REMOTE_GATE_URL: remoteGateUrl,
+    PRODUCT_SPEC_REMOTE_GATE_TOKEN: token,
+    PRODUCT_SPEC_REMOTE_GATE_MODE: "auto",
+    PRODUCT_SPEC_REMOTE_GATE_TIMEOUT_MS: "10000",
+    PRODUCT_SPEC_TELEMETRY: "off",
+  };
+  return {
+    type: "product-spec-mcp-connect",
+    version: 1,
+    remoteGate: {
+      url: remoteGateUrl,
+      token,
+      mode: "auto",
+      timeoutMs: 10000,
+      telemetry: "off",
+    },
+    instructions: {
+      summary: "请把 remoteGate 配置写入当前 Agent 的 product-spec-mcp 环境变量。",
+      env,
+    },
+  };
+}
+
+function connectPageHtml(origin) {
+  const apiUrl = `${origin}/v1/connect-token`;
+  return `<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>连接 product-spec MCP</title>
+  <style>
+    :root { color-scheme: light; font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
+    body { margin: 0; min-height: 100vh; background: #f6f8fb; color: #172033; display: grid; place-items: center; }
+    main { width: min(760px, calc(100vw - 32px)); padding: 48px 0; }
+    h1 { font-size: 36px; line-height: 1.12; margin: 0 0 16px; letter-spacing: 0; }
+    p { font-size: 16px; line-height: 1.7; color: #526071; margin: 0 0 18px; }
+    .panel { background: rgba(255,255,255,.86); border: 1px solid #e4e9f1; border-radius: 8px; padding: 28px; box-shadow: 0 18px 48px rgba(25, 38, 64, .10); }
+    .steps { display: grid; gap: 12px; margin: 26px 0; padding: 0; list-style: none; }
+    .steps li { display: flex; gap: 12px; align-items: flex-start; color: #243246; }
+    .num { flex: 0 0 28px; height: 28px; border-radius: 999px; background: #0f766e; color: white; display: grid; place-items: center; font-weight: 700; font-size: 14px; }
+    button { appearance: none; border: 0; border-radius: 8px; background: #0f766e; color: white; font-size: 16px; font-weight: 700; padding: 14px 18px; cursor: pointer; }
+    button:disabled { opacity: .65; cursor: wait; }
+    .status { margin-top: 16px; font-size: 14px; color: #526071; min-height: 22px; }
+    .fine { margin-top: 24px; font-size: 13px; color: #7a8698; }
+  </style>
+</head>
+<body>
+  <main>
+    <section class="panel">
+      <h1>连接 product-spec MCP</h1>
+      <p>下载连接文件，然后把文件发回给你正在使用的 Agent。Agent 会读取文件并把在线 PM Gate 配置写入当前 MCP 设置。</p>
+      <ol class="steps">
+        <li><span class="num">1</span><span>点击下方按钮生成你的连接文件。</span></li>
+        <li><span class="num">2</span><span>把下载的 <strong>product-spec-mcp-connect.json</strong> 拖回或上传到 Agent 对话。</span></li>
+        <li><span class="num">3</span><span>让 Agent 按文件里的说明完成配置并重启 MCP。</span></li>
+      </ol>
+      <button id="download">生成并下载连接文件</button>
+      <div class="status" id="status"></div>
+      <p class="fine">连接文件里包含你的专属访问 token，请不要公开分享。默认额度由服务端配置控制。</p>
+    </section>
+  </main>
+  <script>
+    const button = document.getElementById("download");
+    const status = document.getElementById("status");
+    button.addEventListener("click", async () => {
+      button.disabled = true;
+      status.textContent = "正在生成连接文件...";
+      try {
+        const response = await fetch(${JSON.stringify(apiUrl)}, {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ client: "browser-connect-page" })
+        });
+        const payload = await response.json();
+        if (!response.ok || !payload.connectFile) throw new Error(payload.error || "connect_failed");
+        const blob = new Blob([JSON.stringify(payload.connectFile, null, 2)], { type: "application/json" });
+        const url = URL.createObjectURL(blob);
+        const a = document.createElement("a");
+        a.href = url;
+        a.download = "product-spec-mcp-connect.json";
+        a.click();
+        URL.revokeObjectURL(url);
+        status.textContent = "已下载连接文件。请把它发回给你的 Agent。";
+      } catch (error) {
+        status.textContent = "生成失败，请稍后重试。";
+      } finally {
+        button.disabled = false;
+      }
+    });
+  </script>
+</body>
+</html>`;
+}
+
+function resolveRemoteGateUrl(env, origin) {
+  return String(env.PUBLIC_REMOTE_GATE_URL || `${origin}/v1/pm-intent`);
+}
+
+function randomToken(byteLength) {
+  const bytes = new Uint8Array(byteLength);
+  crypto.getRandomValues(bytes);
+  let raw = "";
+  for (const byte of bytes) raw += String.fromCharCode(byte);
+  return btoa(raw).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+
+function positiveIntegerOrNull(value) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) return null;
+  return Math.floor(parsed);
+}
+
+function sanitizeShortText(value, maxLength) {
+  return String(value || "")
+    .replace(/[^\w\s.@:-]/g, "")
+    .trim()
+    .slice(0, maxLength) || "product-spec-mcp";
+}
+
 async function callOpenAiCompatible(llm, prompt) {
   if (!llm.apiKey) throw new Error(`missing_${llm.provider}_api_key`);
   const response = await fetch(`${normalizeBaseUrl(llm.baseUrl)}/chat/completions`, {
@@ -366,6 +595,48 @@ async function remainingForKey(env, key, dailyLimit) {
   return Math.max(0, dailyLimit - current);
 }
 
+async function consumeCombinedLimit(env, ipKey, resetAt, dailyLimit, token, tokenLimit) {
+  const ipLimit = await consumeLimit(env, ipKey, resetAt, dailyLimit);
+  if (!ipLimit.allowed) return { allowed: false, remaining: 0, reason: "ip_rate_limited" };
+  if (!token || !tokenLimit) return ipLimit;
+
+  const monthly = await checkMonthlyLimit(env, token);
+  if (!monthly.allowed) return { allowed: false, remaining: 0, reason: "token_monthly_limited" };
+
+  const tokenKey = tokenRateLimitKey(token.id);
+  const tokenDaily = await consumeLimit(env, tokenKey, resetAt, tokenLimit);
+  if (!tokenDaily.allowed) return { allowed: false, remaining: 0, reason: "token_daily_limited" };
+
+  return {
+    allowed: true,
+    remaining: Math.min(ipLimit.remaining, tokenDaily.remaining, monthly.remaining ?? tokenDaily.remaining),
+  };
+}
+
+async function combinedRemaining(env, ipKey, dailyLimit, token, tokenLimit) {
+  const ipRemaining = await remainingForKey(env, ipKey, dailyLimit);
+  if (!token || !tokenLimit) return ipRemaining;
+  const tokenRemaining = await remainingForKey(env, tokenRateLimitKey(token.id), tokenLimit);
+  const monthly = await checkMonthlyLimit(env, token);
+  return Math.min(ipRemaining, tokenRemaining, monthly.remaining ?? tokenRemaining);
+}
+
+function tokenRateLimitKey(tokenId) {
+  return `token-rate:${shanghaiDateKey()}:${tokenId}`;
+}
+
+async function checkMonthlyLimit(env, token) {
+  const monthlyLimit = Number(token?.monthly_limit || 0);
+  if (!env.PROMPT_SAMPLES || !Number.isFinite(monthlyLimit) || monthlyLimit <= 0) return { allowed: true };
+  await ensureConnectTables(env);
+  const month = shanghaiDateKey().slice(0, 7);
+  const row = await env.PROMPT_SAMPLES.prepare(
+    "SELECT COALESCE(SUM(cost_units), 0) AS used FROM usage_events WHERE token_id = ? AND event_month = ?"
+  ).bind(token.id, month).first();
+  const used = Number(row?.used || 0);
+  return { allowed: used < monthlyLimit, remaining: Math.max(0, monthlyLimit - used) };
+}
+
 async function rateLimitKey(request, env) {
   const ip = request.headers.get("cf-connecting-ip") || request.headers.get("x-forwarded-for") || "unknown";
   const day = shanghaiDateKey();
@@ -373,6 +644,70 @@ async function rateLimitKey(request, env) {
   return `rate:${day}:${await sha256(`${salt}:${ip}`)}`;
 }
 
+async function ensureConnectTables(env) {
+  if (!env.PROMPT_SAMPLES) return;
+  await env.PROMPT_SAMPLES.prepare(
+    `CREATE TABLE IF NOT EXISTS api_tokens (
+      id TEXT PRIMARY KEY,
+      token_hash TEXT UNIQUE NOT NULL,
+      token_prefix TEXT NOT NULL,
+      label TEXT,
+      daily_limit INTEGER NOT NULL,
+      monthly_limit INTEGER,
+      enabled INTEGER NOT NULL,
+      created_at TEXT NOT NULL,
+      last_used_at TEXT
+    )`
+  ).run();
+  await env.PROMPT_SAMPLES.prepare(
+    `CREATE INDEX IF NOT EXISTS idx_api_tokens_token_hash
+      ON api_tokens(token_hash)`
+  ).run();
+  await env.PROMPT_SAMPLES.prepare(
+    `CREATE TABLE IF NOT EXISTS usage_events (
+      id TEXT PRIMARY KEY,
+      token_id TEXT,
+      created_at TEXT NOT NULL,
+      event_date TEXT NOT NULL,
+      event_month TEXT NOT NULL,
+      llm_used INTEGER NOT NULL,
+      cache_hit INTEGER NOT NULL,
+      model TEXT,
+      prompt_tokens_approx INTEGER,
+      completion_tokens_approx INTEGER,
+      cost_units INTEGER NOT NULL
+    )`
+  ).run();
+  await env.PROMPT_SAMPLES.prepare(
+    `CREATE INDEX IF NOT EXISTS idx_usage_events_token_month
+      ON usage_events(token_id, event_month)`
+  ).run();
+}
+
+async function maybeStoreUsageEvent(env, auth, event) {
+  if (!env.PROMPT_SAMPLES || !auth?.token) return;
+  await ensureConnectTables(env);
+  const date = shanghaiDateKey();
+  await env.PROMPT_SAMPLES.prepare(
+    `INSERT INTO usage_events (
+      id, token_id, created_at, event_date, event_month, llm_used, cache_hit, model,
+      prompt_tokens_approx, completion_tokens_approx, cost_units
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+  ).bind(
+    crypto.randomUUID(),
+    auth.token.id,
+    new Date().toISOString(),
+    date,
+    date.slice(0, 7),
+    event.llmUsed ? 1 : 0,
+    event.cacheHit ? 1 : 0,
+    event.model || null,
+    event.promptTokensApprox || 0,
+    event.completionTokensApprox || 0,
+    event.costUnits || 0
+  ).run();
+}
+
 async function maybeStoreSample(env, telemetryMode, body, llmDecision, finalDecision, meta) {
   if (!env.PROMPT_SAMPLES || telemetryMode === "off") return;
   const id = crypto.randomUUID();
@@ -481,6 +816,13 @@ function json(payload, status = 200) {
   });
 }
 
+function html(body, status = 200) {
+  return new Response(body, {
+    status,
+    headers: { "content-type": "text/html; charset=utf-8" },
+  });
+}
+
 const needTypes = [
   "static_display",
   "personal_local_tool",

package/workers/schema.sql

@@ -22,3 +22,35 @@ ON prompt_samples(created_at);
 
 CREATE INDEX IF NOT EXISTS idx_prompt_samples_message_hash
 ON prompt_samples(message_hash);
+
+CREATE TABLE IF NOT EXISTS api_tokens (
+  id TEXT PRIMARY KEY,
+  token_hash TEXT UNIQUE NOT NULL,
+  token_prefix TEXT NOT NULL,
+  label TEXT,
+  daily_limit INTEGER NOT NULL,
+  monthly_limit INTEGER,
+  enabled INTEGER NOT NULL,
+  created_at TEXT NOT NULL,
+  last_used_at TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_api_tokens_token_hash
+ON api_tokens(token_hash);
+
+CREATE TABLE IF NOT EXISTS usage_events (
+  id TEXT PRIMARY KEY,
+  token_id TEXT,
+  created_at TEXT NOT NULL,
+  event_date TEXT NOT NULL,
+  event_month TEXT NOT NULL,
+  llm_used INTEGER NOT NULL,
+  cache_hit INTEGER NOT NULL,
+  model TEXT,
+  prompt_tokens_approx INTEGER,
+  completion_tokens_approx INTEGER,
+  cost_units INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_usage_events_token_month
+ON usage_events(token_id, event_month);