64 lines
2.1 KiB
Markdown
64 lines
2.1 KiB
Markdown
# GoodBuddy 接入边界
|
||
|
||
本文件记录 Product Issue 已提供的服务端契约。GoodBuddy 桌面端接入应在
|
||
生产域名确定后实现。
|
||
|
||
## 推荐调用链
|
||
|
||
```text
|
||
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 契约](api.md)。
|