fix: clarify collaboration repository Git access errors

[beautyarbutin]

摘要

本 PR 改进 HALF 协作仓库访问失败时的错误提示，避免 Git clone/fetch 失败时只显示笼统的轮询错误。

主要改动：

• 保留 Git clone/fetch 失败时的 stderr/stdout 细节，用于后端判断错误类型。
• 将常见 Git 访问失败归类为 SSH key 缺失或权限不足、仓库不存在或无权限、网络/DNS 连接问题，以及兜底错误。
• 在轮询状态中展示更明确的用户提示。
• 补充 Docker 部署下后端容器访问私有协作仓库的 SSH key、known_hosts 和 HTTPS 凭据说明。
• 增加后端测试覆盖这些错误分类。

Closes #104

相关 Discussion：N/A

范围

• 本 PR 保持小而聚焦。
• 本 PR 没有把无关重构、纯格式化改动或翻译工作混入功能改动。
• 公开 API、数据模型、权限、安全边界和部署行为没有变化；如有变化，已
  在下方说明影响。

截图或录屏

1. 仓库不存在或私有仓库无权限

2. SSH 地址但后端容器缺少 SSH key / 权限不足

3. 网络问题导致服务不可达

本 PR 未新增 UI 组件；错误信息通过现有项目轮询状态区域展示。

迁移 / 配置影响

无数据库迁移，无新增环境变量。

文档补充了 Docker 部署时后端容器访问协作仓库的配置要求：

• SSH 地址需要在后端容器内配置可用 SSH key 和 known_hosts。
• private 仓库需要对应访问凭据。
• public GitHub 仓库推荐使用 HTTPS 匿名只读地址。

验证

• cd src/backend && uv run python -m pytest tests/ -v
• cd src/frontend && npm test
• cd src/frontend && npm run build

检查清单

• 改动范围清晰且聚焦。
• 已按需关联相关 Issue。
• 已按需关联相关 Discussion。
• 如果行为、API 形状或配置发生变化，已同步更新文档。
• 没有引入密钥、私有 URL 或个人本机路径。

[XiaoCooder]

1. 总体结论

可以接受并合并。

按“本 PR 只需要增加错误提示和文档说明”的验收口径，PR #118 完成了 #104 的核心目标：保留 Git stderr/stdout、将常见 clone/fetch 失败分类为更明确的用户提示，并同步补充 Docker 容
器 Git 凭据文档。受影响测试、完整后端测试、前端测试和构建均已在容器中通过；未发现阻塞合并的问题。

2. 是否解决 issue #104

#104 的核心要求 / 验收清单：

• 文档或 UI 明确说明 SSH/HTTPS 协作仓库地址对凭据的要求。
• Docker 部署文档说明如何让后端容器访问私有协作仓库。
• 当 SSH clone/fetch 因 Permission denied (publickey) 失败时，页面或 API 错误能提示 SSH key 缺失或权限不足。
• 用户可以区分 public 仓库使用 HTTPS 可匿名读取、SSH 地址仍需要 SSH key。

PR 已完成：

• src/backend/services/git_service.py:130 增加 _git_exception_detail()，保留 CalledProcessError 的 stderr/stdout，使后续分类能看到真实 Git 错误。
• src/backend/services/git_service.py:150 在重试失败时返回详细 Git 错误，而不是只有 Python 异常摘要。
• src/backend/services/polling_service.py:26 定义 SSH publickey、仓库不存在/无权限、网络错误三类更具体的用户提示。
• src/backend/services/polling_service.py:43 通过 format_git_repo_access_error() 对常见 Git 失败文本分类。
• src/backend/services/polling_service.py:188 在轮询 Git sync 失败时，把分类后的提示写入 running plan/task 的 last_error，页面会展示该错误。
• README.md:273、README.md:279、docs/quickstart.md:213 补充 public HTTPS、SSH key、known_hosts、deploy key 和 private HTTPS credential helper 说明。
• src/backend/tests/test_git_service.py:212 覆盖 clone 失败时保留 Permission denied (publickey) stderr。
• src/backend/tests/test_polling_service.py:485、src/backend/tests/test_polling_service.py:508 覆盖 SSH publickey、not found/auth、network、fallback 分类。

未完成或可疑部分：

• 无。按当前确认的范围，本 PR 不需要实现 HTTPS fallback 或自动修复容器凭据。

偏离 issue 的改动：

• src/frontend/src/pages/ProjectNewPage.test.ts 只有 import 格式化变化，影响很小，不构成问题。

3. 主要问题清单

Blocker

无。

Major

无。

Minor

无。

Nit

无。

4. 文档与命名检查

文档修改是必要的，因为 #104 明确要求说明 Docker 后端容器访问协作仓库的凭据边界。位置合理：README 放通用部署说明，quickstart 放故障排查路径，均属于稳定用户文档，不是提案或过
程草稿。

命名和内容边界没有问题。没有发现“当前分支未找到 X”“建议实施顺序”“实现前状态”等不应进入 main 的过程性内容。中英文 README 与 quickstart 都做了同步更新。

5. 测试与验证建议

实际运行结果：

• 已启动 PR 服务：docker compose -p half_pr118_review up -d --build 成功。
• 服务可访问：
  • http://localhost:8000/ 返回 HTTP 200。
  • http://localhost:3000/ 返回 HTTP 200。
• git diff --check main...HEAD：通过。
• 受影响后端测试：pytest tests/test_git_service.py tests/test_polling_service.py -v，39 passed, 72 subtests passed。
• 完整后端测试：pytest tests -q，251 passed, 97 subtests passed，仅有既有 deprecation warnings。
• 前端生产镜像是 nginx，docker compose run frontend npm test 不适用，报 npm: not found。替代验证：用一次性 node:22-alpine 容器运行 npm ci && npm test && npm run build，结果
  123 passed，构建通过。

已有测试足够覆盖本 PR 的关键路径：Git stderr 保留、错误分类、轮询时 plan/task 错误展示。

6. 建议给 PR 作者的修改意见

按 #104 的范围验证了这次改动。PR 能保留 Git clone/fetch 的 stderr/stdout，并在轮询失败时把 Permission denied (publickey)、仓库不存在/无权限、网络/DNS 等错误转成更明确的
页面提示；README 和 quickstart 也补充了 Docker 后端容器访问 Git 仓库所需的 SSH key、known_hosts、HTTPS/public/private 仓库差异说明。
在临时目录中用 Docker Compose 启动了服务，前后端均可访问。受影响后端测试、完整后端测试、前端测试和前端 build 都通过。未发现需要修改的问题。注意我没有把“自动 fallback 到

7. 最终建议

建议合并。