[Proposal] Upstream generic features from a self-hosted fork (Forgejo, MCP auth, i18n, OAuth…) / 回馈通用功能提案

[manana2520]

English

Hi maintainers, and thank you for OpenDeepWiki — we run it self-hosted to generate wikis for our internal Git repositories.

We maintain a fork that is currently ~60 commits ahead of a recent main baseline (and we rebase on upstream regularly). Most of that work is generic and we'd like to contribute it back rather than carry it privately. We've already scrubbed our deployment-specific identifiers from the generic code, and everything is built on your current stack (.NET 10 / EF Core 10 / Next.js 16, xUnit + Playwright), so it should slot in cleanly.

Before opening a stack of PRs, we'd like your guidance so we contribute in the shape you prefer.

What we'd like to contribute (generic features)

Area	Summary	Notes
Forgejo / Gitea git platform	A small provider abstraction so repos can be browsed/cloned/analyzed from Forgejo & Gitea (self-hosted or cloud) alongside GitHub/GitLab. Includes unit tests.	Headline feature; replaces the hardcoded host switch with a config-driven registry.
Admin-managed git-platform credentials + private-repo import	Encrypted credential storage, admin UI, and private-repo import (Gitea API + GitHub PAT).	We'd split this into 3 PRs: (a) schema + at-rest encryption, (b) SSRF guard, (c) import + UI.
MCP server authentication & authorization	API-key + OAuth auth and per-repository scope for the MCP endpoint.	Additive; backward compatible.
MCP ListRepositories summary	Optional repo summary (prefers an Overview doc, honors requested language).	Small, depends on the MCP-auth PR.
i18n completeness	Route remaining hardcoded UI strings through i18n and fill en/zh/ja/ko parity.	New keys only; no collisions expected.
Browser OAuth login fixes	Backend 3xx redirect (not JSON), SPA callback page, reverse-proxy /api pass-through, de-hardcoded provider error text.	Google/GitHub/Forgejo.
Bulk repository → department assignment	Tri-state (Google-Drive style) bulk assign dialog, select-all-on-page + select-all-matching, indeterminate-checkbox rendering.	UI-heavy; we'll rebase on your latest admin-repo refactor.
Git push webhook	/api/webhooks/git with signature verification to trigger near-real-time incremental updates.	Independent.
Gemini finish_reason normalizer	Maps Gemini's non-OpenAI finish_reason values to the SDK's expected set in the agent HTTP pipeline.	Fully standalone; cleanest first PR.
Role-assignment FK bugfix	Fixes a foreign-key violation when updating user roles.	Standalone bugfix.
Security: require JWT signing key from env	Removes the committed default Jwt:SecretKey and fails fast if JWT_SECRET_KEY is unset.	⚠️ Breaking for deployments relying on the default — see below.

How we propose to do it

• Small, focused, dependency-ordered PRs, each rebased on current main — not one mega-PR.
• Suggested order, lowest-risk first: Gemini normalizer → role-FK fix → JWT security → i18n → Forgejo provider → (credentials → SSRF → import) → OAuth login → MCP auth → MCP summary → admin language settings → bulk department assignment → webhook.
• We'll include tests with each (we already have xUnit + Playwright coverage for most).

Things to flag

• Breaking change (JWT): removing the default secret means existing deployments must set JWT_SECRET_KEY. We can soften this with a one-release "loud warning, then enforce" path if you prefer.
• EF migrations: we'll regenerate migrations against upstream for all providers (SQLite, PostgreSQL, MySQL) — we won't import our fork's migration history.
• SSRF guard: internal-IP blocking will be configurable so self-hosters running Gitea/Forgejo on the same LAN aren't blocked.

Questions for you

1. Are these features welcome in principle? Any you'd rather we keep out of scope?
2. Preferred PR size / granularity and branch/commit conventions?
3. EF migration workflow you'd like us to follow for the multi-provider setup?
4. Preferred language for PR descriptions (English / 中文 / both)? Any CLA/sign-off requirement?

Happy to start with one or two small PRs (e.g. the Gemini normalizer and the role-FK fix) so we can align on style before the larger ones. Thanks again!

---

中文

各位维护者好，首先感谢 OpenDeepWiki —— 我们在内部自托管运行它，用来为公司的 Git 仓库生成 wiki。

我们维护了一个分支，目前领先某个较新的 main 基线约 60 个提交（并会定期 rebase 到上游）。其中大部分改动是通用的，我们希望回馈给上游，而不是长期私有维护。我们已经把部署相关的专有标识从通用代码中清理干净，并且全部基于你们当前的技术栈（.NET 10 / EF Core 10 / Next.js 16，xUnit + Playwright），应该可以较平滑地合入。

在提交一系列 PR 之前，我们希望先听取你们的意见，按你们偏好的方式来贡献。

我们希望贡献的内容（通用功能）

模块	概述	备注
Forgejo / Gitea 平台支持	一个轻量的平台抽象层，使仓库可以从 Forgejo 和 Gitea（自托管或云端）浏览/克隆/分析，与 GitHub/GitLab 并列。含单元测试。	核心功能；用基于配置的注册表替换了原先硬编码的主机分支判断。
管理员管理的平台凭据 + 私有仓库导入	加密凭据存储、管理界面，以及私有仓库导入（Gitea API + GitHub PAT）。	计划拆成 3 个 PR：(a) 数据模型 + 静态加密，(b) SSRF 防护，(c) 导入 + UI。
MCP 服务器鉴权与授权	MCP 端点的 API Key + OAuth 鉴权，以及按仓库的访问范围控制。	纯增量；向后兼容。
MCP ListRepositories 摘要	可选的仓库摘要（优先使用 Overview 文档，遵循请求语言）。	体量小，依赖 MCP 鉴权 PR。
i18n 完整性	将剩余硬编码 UI 字符串接入 i18n，并补齐 en/zh/ja/ko 四语。	仅新增 key，预期无冲突。
浏览器 OAuth 登录修复	后端 3xx 跳转（而非 JSON）、SPA 回调页、反向代理 /api 透传、去硬编码的报错文案。	Google/GitHub/Forgejo。
仓库到部门的批量分配	三态（类 Google Drive）批量分配对话框、本页全选 + 全部匹配项全选、半选复选框渲染。	UI 较多；会在你们最新的 admin-repo 重构上 rebase。
Git push webhook	带签名校验的 /api/webhooks/git，触发近实时增量更新。	独立功能。
Gemini finish_reason 归一化	在 agent 的 HTTP 管线中，把 Gemini 的非 OpenAI finish_reason 值映射为 SDK 期望的取值。	完全独立；最适合作为第一个 PR。
角色分配外键修复	修复更新用户角色时的外键约束冲突。	独立 bug 修复。
安全：JWT 签名密钥强制取自环境变量	移除已提交的默认 Jwt:SecretKey，未设置 JWT_SECRET_KEY 时启动即失败。	⚠️ 对依赖默认值的部署是破坏性变更，详见下文。

我们建议的方式

• 小而聚焦、按依赖排序的 PR，每个都在当前 main 上 rebase —— 不做一个巨型 PR。
• 建议顺序（风险从低到高）：Gemini 归一化 → 角色外键修复 → JWT 安全 → i18n → Forgejo 平台 →（凭据 → SSRF → 导入）→ OAuth 登录 → MCP 鉴权 → MCP 摘要 → 管理员语言设置 → 批量部门分配 → webhook。
• 每个 PR 都会附带测试（大部分已有 xUnit + Playwright 覆盖）。

需要特别说明的点

• 破坏性变更（JWT）： 移除默认密钥意味着现有部署必须设置 JWT_SECRET_KEY。如你们倾向，我们可以加一个"先告警一个版本、再强制"的过渡方案。
• EF 迁移： 我们会在上游基线上重新生成迁移，覆盖全部 provider（SQLite、PostgreSQL、MySQL），不会导入我们分支的迁移历史。
• SSRF 防护： 内网 IP 拦截将可配置，以免与 DeepWiki 部署在同一内网的自托管 Gitea/Forgejo 被误拦。

想请教你们的问题

1. 这些功能原则上是否欢迎？有没有你们倾向不纳入的？
2. 偏好的 PR 粒度 与 分支/提交规范？
3. 多 provider 场景下，你们希望我们遵循怎样的 EF 迁移 流程？
4. PR 描述偏好哪种语言（英文 / 中文 / 双语）？是否有 CLA / sign-off 要求？

我们很乐意先从一两个小 PR 开始（例如 Gemini 归一化和角色外键修复），先对齐风格，再做较大的改动。再次感谢！

[manana2520]

First PR is up: #372 — fix(agents): normalize Gemini finish_reason values for the OpenAI SDK (smallest, fully standalone item from the list above). Happy to adjust style/conventions based on your feedback before we send the next ones.