评估当前工程质量与设计实现风险

[liujuanjuan1984]

背景

对当前项目开展一次系统性的工程质量评估，识别可优化项以及潜在的设计与实现风险，为后续开发提供可追踪的改进依据。

范围

• 项目结构与模块边界
• 类型、安全、错误处理与并发行为
• 测试策略、覆盖率与验证流程
• 依赖、构建、发布与运维可维护性
• 文档、契约一致性与开发者体验

交付

• 输出按严重程度和优先级整理的评估报告
• 为每项发现提供证据、影响和建议
• 本 issue 暂不包含未经确认的实现改动

[liujuanjuan1984]

工程质量评估结果（2026-07-13）

总体结论

当前工程基线健康，模块分层、契约测试、类型检查、覆盖率门禁、依赖审计和制品验证较完整。适合继续作为受控/内部环境中的 Alpha runtime 演进；若面向公网、高并发或多副本部署，仍需补齐生产化边界。

已验证基线

• bash ./scripts/doctor.sh 完整通过
• 701 项测试通过
• 总覆盖率 93.04%，达到 90% 门禁
• mypy、ruff、pre-commit、依赖兼容检查通过
• sdist/wheel 构建与 wheel smoke test 通过

建议优先处理

1. P1：默认无上游并发上限且 stream timeout 无界

   • OPENCODE_MAX_CONCURRENT_REQUESTS、OPENCODE_MAX_CONCURRENT_STREAMS 默认均为 0（不限流），OPENCODE_TIMEOUT_STREAM 默认 None。
   • 在公网、异常客户端或慢上游场景下可能造成连接、任务和内存资源耗尽。
   • 建议：提供生产 profile/启动告警，配置安全默认值，增加并发与慢流压力测试；外部入口仍应配置网关限流。

2. P1：多副本状态迁移和会话一致性边界不完整

   • 自研 schema runner 在应用启动时执行 DDL/版本写入，没有显式 advisory lock 或独立 migration phase。
   • SessionManager 的去重与 session lock 是进程内结构；多进程/多副本无法共享。
   • 建议：明确声明单副本支持边界，或引入受控迁移步骤与数据库级原子 claim/lock 语义，并添加双实例集成测试。

3. P1：指标当前只是 DEBUG 日志，不是可采集指标后端

   • emit_metric() 仅输出 logger.debug，无法可靠支持告警、聚合和 SLO。
   • 建议：定义 metrics adapter，至少支持 Prometheus/OpenTelemetry，并补齐延迟、错误率、上游饱和度、DB 延迟和活跃 stream 等核心指标。

4. P2：全局 session lock 包裹数据库 I/O

   • SessionManager 使用单个 asyncio.Lock，且在锁内等待 repository 查询/写入，会串行化不相关 identity/context 的会话操作。
   • 建议：缩小临界区，使用 key-scoped lock；持久化一致性依靠数据库唯一约束/事务处理。

5. P2：静态凭据比较不是常量时间

   • bearer token 与 Basic password 使用普通字符串 ==。
   • 建议：使用 secrets.compare_digest，并为凭据轮换、失败审计与网关级暴力破解防护补充运维指导。

6. P2：默认 CI 不覆盖真实 OpenCode 与官方 TCK

   • 现有单元/契约测试质量高，但 conformance 明确是手工实验，默认路径使用 dummy upstream。
   • 建议：固定 TCK 版本，增加非阻断定时 conformance；增加一个真实 OpenCode 的最小 E2E/nightly 路径，结果逐步稳定后再提升为门禁。

7. P2：核心模块体积与职责仍偏大

   • server/application.py 1072 行、opencode_upstream_client.py 919 行、server/state_store.py 826 行、jsonrpc/methods.py 663 行。
   • 建议：按 app assembly/routes、transport/resource clients、repository domain、method families 分拆；以依赖方向和公共 API 为边界，避免仅机械拆文件。

8. P3：维护者架构文档已经漂移

   • 文档仍引用不存在的 invocation.py 和 contracts/extensions.py；实际扩展契约已拆为 contracts/extensions/ 包。
   • 建议：立即修正文档，并增加文档路径/link check。

推荐实施顺序

先明确单实例/多实例支持承诺并补资源治理与真实指标（1-3），再处理 session 并发和认证细节（4-5），随后完善 E2E/TCK 与模块拆分（6-7），文档漂移可作为低风险快速修复（8）。

本次仅评估，未修改代码。

[liujuanjuan1984]

已完成选定改进

当前分支：chore/491-engineering-quality-audit

修改

• 将上游普通请求并发默认值设为 32
• 将上游 stream 并发默认值设为 8
• 将上游 stream timeout 默认值设为 900 秒
• 将 SessionManager 全局锁拆为 context/session 细粒度锁；注册表锁不再包裹 repository I/O
• bearer token、Basic username/password 改用 secrets.compare_digest
• 修正维护者架构文档中不存在的 invocation.py 和旧 contracts/extensions.py 路径
• 增加有界默认值和跨 context repository 并发回归测试

验证

• bash ./scripts/doctor.sh 完整通过
• 703 项测试通过
• 覆盖率 93.02%
• mypy、ruff、pre-commit、依赖兼容、构建和 wheel smoke test 均通过

尚未提交或创建 PR，等待确认。

[liujuanjuan1984]

单实例支持边界已明确

已在以下英文文档中统一说明：

• 支持的持久化部署为单个 opencode-a2a 应用进程使用独立本地 SQLite 数据库
• 不支持多个 Uvicorn worker、容器或应用副本共享同一个 SQLite 文件
• PostgreSQL 及其他 SQLAlchemy dialect 不属于当前正式支持矩阵
• SQLAlchemy 的方言弹性属于内部实现细节，不构成兼容性承诺

更新文件：README.md、docs/guide.md、docs/compatibility.md。

验证：uv run pre-commit run --all-files 全部通过。由于本轮新增内容仅为文档澄清，未重复执行此前已完整通过的 703 项测试。

[liujuanjuan1984]

项目成熟度已调整为 Beta

• pyproject.toml classifier：Development Status :: 4 - Beta
• docs/compatibility.md：更新为 Beta 稳定性声明，公开契约保持稳定，内部实现及明确的 provider-private surface 可继续演进
• 已检查构建产物 METADATA，确认包含 Beta classifier

验证：bash ./scripts/doctor.sh 完整通过，703 项测试通过，覆盖率 93.02%，构建和 wheel smoke test 通过。

[liujuanjuan1984]

实现状态更新

本 issue 的已确认改进已在 Draft PR #492 中实现并推送：

• 有界上游并发与 stream timeout 默认值
• session manager 细粒度锁
• 静态凭据常量时间比较
• Beta 成熟度声明与单进程 SQLite 部署边界
• 仅允许 sqlite+aiosqlite 持久化 URL，并删除非支持矩阵的 PostgreSQL 原子写入兼容分支
• 修复测试中 SQLite engine 在错误事件循环释放的问题

最终 bash ./scripts/doctor.sh 通过：702 项测试、93.11% 覆盖率、类型检查、lint、构建及 wheel smoke test 均通过。