好友

好友（Friends）是构建在 Kaiwu 会话之上的社交层：

• 发现：通过用户名（@username）查找用户
• 申请：发送好友申请并管理好友关系
• 分享：直接与好友共享会话

服务器通过 GET /v1/features 告知客户端是否支持好友功能及 GitHub OAuth。UI 则利用该端点决定是否显示好友模块，以及是否提供 GitHub 关联入口。

身份模型（无论来源，统一为一个用户名）

Kaiwu 采用唯一的标识符进行用户发现：account.username。

• 用户搜索（GET /v1/user/search）会匹配 username
• 好友申请在内部使用账户 ID，但在 UI 交互上以 @username 为核心
• 用户名在服务器端会统一规范化为小写

用户无需关心某个用户名是来自 GitHub 还是手动设置的——直接搜索 @username 即可。

关联 GitHub（OAuth）

用户关联 GitHub 时：

1. 服务器完成 OAuth 流程并获取 GET https://api.github.com/user（权限范围为 read:user）。
2. 服务器将该 GitHub 账户与 Kaiwu 账户绑定（1 个 GitHub 账户对应 1 个 Kaiwu 账户）。
3. 服务器不会覆盖已有的 account.username。
4. 若 account.username 为空，服务器会尝试将其设置为该 GitHub 的 login（转为小写），前提是该用户名尚未被占用。

如果该 GitHub 登录用户名已被占用（或不符合服务器的用户名规范），GitHub 依然可以成功关联，但应用会在完成好友功能设置前，提示用户另选一个 @username。

解除 GitHub 关联：

• 必定会移除 GitHub 绑定关系。
• 保留自定义用户名。
• 仅当 account.username 与 GitHub 登录名一致（被视为“衍生自 GitHub”）时，才会清空该项。

仅用户名模式（无需 GitHub）

部分自托管服务器不希望强制绑定 GitHub。启用此模式后，用户可以直接认领本地用户名。

• 端点：POST /v1/account/username
• 校验规则由服务器环境变量控制（见下文）。

必须绑定 GitHub 的服务器上的用户名选取

即使好友功能要求绑定 GitHub，应用有时仍可能要求用户选择一个用户名。

这种情况通常发生在用户的 GitHub 登录名无法作为服务器上的唯一用户名时（例如已被占用）。此时：

• GitHub 仍可成功关联。
• 用户必须另选一个 @username，才能被其他人搜索到。
• 应用会在好友页面以及设置 → 账户中提示用户操作。

服务器配置

功能开关

• KAIWU_FEATURE_SOCIAL_FRIENDS__ENABLED（true/false，默认 true）：好友功能端点及 UI 的总开关。
• KAIWU_FEATURE_SOCIAL_FRIENDS__ALLOW_USERNAME（true/false，默认 false）：
  • false：好友申请与搜索必须关联 GitHub。
  • true：好友功能只需认领 @username（GitHub 关联可选）。

用户名策略（启用基于用户名的好友模式时）

• FRIENDS_USERNAME_MIN_LEN（默认 3）
• FRIENDS_USERNAME_MAX_LEN（默认 32）
• FRIENDS_USERNAME_REGEX（默认 ^[a-z0-9_-]+$）

GitHub OAuth

启用 GitHub 关联所需的配置：

• GITHUB_CLIENT_ID
• GITHUB_CLIENT_SECRET
• GITHUB_REDIRECT_URL（规范名称）或 GITHUB_REDIRECT_URI（旧版名称）

可选配置：

• KAIWU_WEBAPP_URL（默认 https://kaiwu.wujilabs.cn）：客户端的基础 URL / scheme。服务器回调完成后，会将请求重定向至 ${KAIWU_WEBAPP_URL}/oauth/github。
  • 只有在使用 https://kaiwu.wujilabs.cn 上的托管客户端时，该项才属“可选”。如果您自托管了 Web 应用（或使用本地开发的 Web UI），请设置 KAIWU_WEBAPP_URL（或 KAIWU_WEBAPP_OAUTH_RETURN_URL_BASE），以便 OAuth 能正确跳回您的客户端。
• GITHUB_STORE_ACCESS_TOKEN（true/false，默认 false）：是否在服务器上持久化存储 GitHub 访问令牌（好友功能不需要此项）。如果您通过 AUTH_GITHUB_ORG_MEMBERSHIP_SOURCE=oauth_user_token 强制校验组织成员身份（通过用户 OAuth 令牌模式进行成员校验），则必须存储令牌以执行离职/成员退出检查。详见组织成员身份来源。
• OAUTH_PENDING_TTL_SECONDS（默认 600，最小 60，最大 3600）：“待完成 OAuth（pending OAuth finalize）”（例如等待用户选择用户名）允许被完成的最长保留时间。
  • 旧版别名：GITHUB_OAUTH_PENDING_TTL_SECONDS（未设置 OAUTH_PENDING_TTL_SECONDS 时生效）。

GitHub 配置（OAuth App）

1. 在 GitHub 中，进入 Settings → Developer settings → OAuth Apps → New OAuth App。
2. 将 Authorization callback URL 设置为您的服务器回调端点：
   • https://YOUR_SERVER/v1/oauth/github/callback
   • 您无需启用 GitHub 的“设备流（Device Flow / device authentication flow）”。Kaiwu 使用标准浏览器重定向 OAuth 流程，因此让“Enable Device Flow”保持未勾选即可。
3. 将 Client ID 和 Client secret 复制到服务器环境变量中，分别对应 GITHUB_CLIENT_ID 和 GITHUB_CLIENT_SECRET。
4. 将 GITHUB_REDIRECT_URL 设置为您在上面注册的同一回调 URL。 5.（自托管）将 KAIWU_WEBAPP_URL 设置为接收 OAuth 完成后重定向的 URL / scheme。
   • 服务器会重定向至 ${KAIWU_WEBAPP_URL}/oauth/github?...

客户端行为（UI）

• 好友功能入口位于 /friends。该路径不会发生重定向，且独立于位于 /inbox 的全局收件箱——详见收件箱与审批。
• 若好友功能被禁用（features.social.friends.enabled=false），UI 会隐藏“好友”标签页及相关界面。
• 若好友功能要求绑定 GitHub（features.social.friends.requiresGitHub=true），但尚未配置 GitHub OAuth（features.oauth.providers.github.configured=false），UI 会禁用 GitHub 关联按钮，并显示明确的“未配置”提示。

API 接口概览

• GET /v1/features：服务器公布的功能特性开关（好友功能 + GitHub OAuth）。
• GET /v1/user/search?query=...：按用户名搜索用户。
• POST /v1/friends/add：发送好友申请。
• POST /v1/friends/remove：删除好友。
• GET /v1/friends：获取好友及好友关系列表。
• POST /v1/account/username：认领或更新用户名（需要身份认证；仅在好友功能已启用且满足“启用了基于用户名的好友模式”或“已关联 GitHub”之一时可用）。
  • 请求体：{ "username": "alice" }
  • 成功返回：200 { "username": "alice" }
  • 错误响应：
    • 400 { "error": "friends-disabled" }：好友功能已禁用
    • 400 { "error": "username-disabled" }：未启用基于用户名的好友模式，且用户未关联 GitHub 身份
    • 400 { "error": "invalid-username" }：用户名未通过校验规则
    • 409 { "error": "username-taken" }：用户名已被占用