Initial commit

docs/goodbuddy-integration.md

@@ -0,0 +1,63 @@
+# 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)。