Break Proxy

这是 Break 插件共用的本地代理。新闻、灵感和收集箱都通过同一个地址访问：

http://localhost:8787

当前“灵感”模块的 UIUX 知识库已经内置在 MasterGo 插件包里；本地代理负责把插件整理好的请求转发给用户自己的 AI API。

使用 npx 启动

OPENAI_API_KEY="你的 API Key" \
OPENAI_BASE_URL="你的模型服务 Base URL" \
OPENAI_WIRE_API="auto" \
DEFAULT_MODEL="你的模型名" \
npx break-proxy

如果使用团队当前默认模型服务，例如 https://api.sublyx.org：

OPENAI_API_KEY="你的 API Key" \
OPENAI_BASE_URL="https://api.sublyx.org" \
OPENAI_WIRE_API="responses" \
DEFAULT_MODEL="gpt-5.5" \
npx break-proxy

然后插件设置里填写：

• Provider：Local Proxy / 本地终端代理
• Base URL：http://localhost:8787
• API Key：留空
• Model：gpt-5.5

新闻会请求同一个本地代理的 GET /api/news；灵感会请求同一个本地代理的 /v1/inspiration/* 接口。两者共用 OPENAI_API_KEY、OPENAI_BASE_URL、OPENAI_WIRE_API 和 DEFAULT_MODEL。

灵感分析时，插件会先通过本地代理让 AI 识别截图，再使用插件内置知识库检索最相关的 3-5 篇文档片段，最后把这些片段交给本地代理请求 AI 生成结果。用户不需要单独下载知识库包。

开发时本地启动

cd server
npm install
KEY_ENCRYPTION_SECRET="replace-with-a-long-random-secret" npm run dev

“给出建议”模式只返回文字建议和原图局部区域定位；插件会根据 AI 返回的百分比坐标从用户上传的原图中裁出相关区域，帮助用户看出这条建议指向哪里。

UIUX 知识库

开发时，知识库源文件放在：

server/knowledge/sources/

文件名和文件夹名可以使用中文。更新或新增 Markdown 后，重新生成索引：

cd server
npm run build:knowledge

生成结果在：

server/knowledge/generated/

插件构建时会自动把 server/knowledge/generated/ 打包成：

src/shared/embedded-knowledge.ts

然后随 MasterGo 插件一起发布。

主要文件：

• documents.json：每篇文档的标题、章节、界面类型、组件、评审维度和关键词。
• chunks.jsonl：按标题和长度切分的知识片段，实际给 AI 的依据来自这里。
• keyword-index.json：关键词到文档的倒排索引，方便后续扩展。
• routing-rules.json：一些高频 UI 类型和组件的路由规则。
• aliases.json：同义词表，例如“搜索框 / 搜索栏 / search bar”。
• stats.json：索引统计。

收集箱

本地代理也提供图片收集箱接口。浏览器插件会把右键收集的图片上传到：

POST /v1/inbox/images

图片默认保存到：

server/.data/inbox/

MasterGo 插件的“收集箱”页会读取：

GET /v1/inbox/images

然后可以把图片插入画布。

浏览器扩展在这个目录：

browser-extension/

Chrome / Edge 加载方式：

1. 打开扩展管理页。
2. 开启开发者模式。
3. 选择“加载已解压的扩展程序”。
4. 选择项目里的 browser-extension 文件夹。
5. 保持本地代理运行，然后在网页图片上右键选择“收集到 Break”。

默认地址是：

http://localhost:8787

插件设置里填写：

• 后端代理地址：http://localhost:8787，正式发布时换成你的线上 HTTPS 地址
• Provider：按用户 Key 选择，例如 OpenAI、DeepSeek、Kimi
• 模型名：例如 gpt-4.1-mini、deepseek-chat、moonshot-v1-8k
• 后端访问 Token：本 MVP 会把它作为用户标识；生产环境请替换为真实登录态
• 用户 AI API Key：用户自己的模型 Key，点击“保存 Key”后只提交给后端

环境变量

| 变量 | 默认值 | 说明 | | --- | --- | --- | | PORT | 8787 | 后端服务端口 | | DATA_DIR | .data | 加密 Key 的存储目录 | | KEY_ENCRYPTION_SECRET | dev-only-change-this-secret | Key 加密密钥，生产必须改成高强度随机值 | | DEFAULT_MODEL | gpt-5.5 | 后端实际调用的默认模型 | | DEFAULT_PROVIDER_BASE_URL | https://api.sublyx.org | OpenAI-compatible 模型接口地址 | | OPENAI_BASE_URL | https://api.sublyx.org | 新闻和灵感实际请求的 OpenAI/Responses Base URL | | OPENAI_WIRE_API | responses | chat 或 responses | | OPENAI_API_KEY | 空 | 灵感本地代理使用的 AI API Key | | NEWS_FEED_URLS | 空 | 可选，逗号分隔的 RSS 新闻源；留空时使用内置国内来源 | | CORS_ORIGIN | 允许全部 | 逗号分隔的允许来源，生产建议收紧 |

API

健康检查

curl http://localhost:8787/health

查询当前用户是否已保存 Key

curl http://localhost:8787/v1/ai/status \
  -H "Authorization: Bearer demo-user"

保存用户自己的 AI API Key

curl -X POST http://localhost:8787/v1/ai/key \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer demo-user" \
  -d '{
    "provider": "kimi",
    "model": "moonshot-v1-8k",
    "apiKey": "sk-..."
  }'

删除用户 Key

curl -X DELETE http://localhost:8787/v1/ai/key \
  -H "Authorization: Bearer demo-user"

设计画像 AI 解读

插件会调用这个接口：

POST /v1/design-profile/analyze

请求体是插件生成的结构化画像，包括当前画布画像、历史偏好趋势和本地规则解读。后端会使用当前用户保存的 AI Key 调用对应模型，并返回统一 JSON：

{
  "summary": "一句总结",
  "userProfile": ["画像标签"],
  "suggestions": [
    {
      "title": "建议标题",
      "detail": "原因",
      "action": "下一步动作",
      "priority": "medium"
    }
  ],
  "provider": "openai",
  "model": "gpt-4.1-mini",
  "generatedAt": 1760000000000
}

生产化注意事项

• 不要使用默认 KEY_ENCRYPTION_SECRET。
• 当前 MVP 用 Authorization: Bearer xxx 或 x-user-id 作为用户标识，生产环境应接入真实账号系统。
• .data/keys.json 适合本地和 MVP 验证，正式发布建议换成数据库或密钥管理服务。
• 后端只做模型适配和返回格式收敛，不承担 AI 费用；每个用户使用自己保存的 AI API Key。
• 建议加上调用频控、日志脱敏、Key 连通性测试和错误码细分。