product-issue/docs/goodbuddy-integration.md

GoodBuddy 接入边界

本文件记录 Product Issue 已提供的服务端契约。GoodBuddy 桌面端接入应在 生产域名确定后实现。

推荐调用链

About 页面反馈表单
  → shared Zod contract
  → preload 显式方法
  → Main IPC handler
  → Main HTTPS client
  → POST /api/v1/feedback

不要从 Electron renderer 直接跨域调用公开 API，也不要向 renderer 暴露 通用网络能力。

Renderer

• 在“关于”页面内提供反馈入口，不跳转 GitHub Issue。
• 字段包括类型、标题、描述、可选邮箱和可选截图。
• 发送前显示会提交的环境字段和隐私说明。
• 截图需要主动选择或粘贴，支持预览和移除。
• 失败时保留所有输入，成功时显示服务端反馈编号。
• 同一次提交重试必须复用 clientRequestId。

Preload 与 IPC

• 在 src/shared 定义并复用 Zod 输入/输出 schema。
• 使用现有 trusted sender 校验。
• preload 只暴露一个用途明确的反馈提交方法。
• IPC 输入必须限制字符串长度、附件数量和字节数。
• 不传递文件系统路径给服务端。

Main HTTPS client

• 固定并校验生产 HTTPS origin。
• 使用正常系统 TLS 校验，不允许忽略证书错误。
• 设置连接和总超时，支持取消。
• 禁止或严格限制重定向，避免把反馈发送到非预期 origin。
• 限制响应体大小并按公共响应 schema 验证。
• 不记录请求正文、邮箱、图片、installation ID 或响应凭据。

标识

• installationId：应用首次生成并持久保存的随机 UUID，不使用硬件序列号、 用户名或设备指纹。
• clientRequestId：用户发起一条新反馈时生成；只有该次反馈的网络重试 复用。
• productKey：GoodBuddy 固定使用 goodbuddy。

明确不自动附加

• 对话和提示词
• 日志
• 文件、项目或工作区路径
• API key、Token、Cookie、SSH 信息
• 模型、知识库和 Runtime 配置
• 剪贴板或屏幕内容

服务端完整字段与响应见 公共 API 契约。