Skip to content

chore: harden runtime defaults and clarify deployment scope#492

Draft
liujuanjuan1984 wants to merge 3 commits into
mainfrom
chore/491-engineering-quality-audit
Draft

chore: harden runtime defaults and clarify deployment scope#492
liujuanjuan1984 wants to merge 3 commits into
mainfrom
chore/491-engineering-quality-audit

Conversation

@liujuanjuan1984

@liujuanjuan1984 liujuanjuan1984 commented Jul 13, 2026

Copy link
Copy Markdown
Collaborator

概述

  • 将项目成熟度声明从 Alpha 调整为 Beta,并同步兼容性文档。
  • 为上游请求和 stream 提供有界默认并发与 stream timeout,降低公网部署的资源耗尽风险。
  • 将 session manager 的全局锁拆为按 context/session 的细粒度锁,避免 repository I/O 串行化不相关会话操作。
  • 使用常量时间比较静态认证凭据。
  • 明确当前仅支持单应用进程配合独立本地 SQLite 文件;不支持多 worker/副本共享数据库文件,配置会拒绝 PostgreSQL 或其他 SQLAlchemy dialect。
  • 删除已不属于支持矩阵的 PostgreSQL 原子 task 写入兼容分支、不可达的非 SQLite engine/运行摘要分支及对应测试样例,并在测试 teardown 中于原事件循环释放 SQLite engine。
  • 修正维护者架构文档的失效路径。

影响

  • 默认上游普通请求并发限制为 32,stream 并发限制为 8,stream timeout 为 900 秒;可通过现有环境变量覆盖,0 仍可显式关闭并发限制。
  • 对外公开项目状态调整为 Beta;未改变包版本或协议版本。
  • 部署边界由原有 SQLite-first 描述收紧为明确的单进程 SQLite 支持矩阵;非 sqlite+aiosqlite 数据库 URL 会在配置加载时被拒绝。

验证

  • bash ./scripts/doctor.sh
    • 702 项测试通过
    • 覆盖率 93.11%
    • mypy、ruff、pre-commit、依赖兼容、构建及 wheel smoke test 通过

Closes #491

@liujuanjuan1984

Copy link
Copy Markdown
Collaborator Author

PR 自审结果

结论

未发现阻塞合并的问题。当前变更与 #491 中已确认的资源治理、session 并发、认证比较、部署边界澄清及项目成熟度调整一致;实现没有引入额外的分布式锁、迁移框架或数据库重写,范围与单进程 SQLite 支持矩阵相符。

代码与设计审查

  • 有界默认值保留环境变量覆盖,0 仍可显式关闭并发限制。
  • session manager 只用短暂的 registry lock 管理 lock registry;repository I/O 按 context/session 细粒度串行,并新增跨 context 并发回归测试。
  • 静态 bearer 和 Basic 凭据使用 secrets.compare_digest;Basic 用户名与密码都完成比较后才决定认证结果。
  • 文档对单应用进程、独立 SQLite 文件、禁止多 worker/副本共享文件及不支持 PostgreSQL 的描述一致。
  • Beta classifier 已在构建 wheel 的 METADATA 中验证。

全仓死代码/薄壳审查

已运行仓库的 scripts/find_thin_wrappers.py 并审查零静态调用候选。没有发现可在不改变行为或公开/SDK 接口的前提下删除的高置信死代码;候选项均属于动态属性调用、FastAPI 路由回调、SDK 生命周期接口、repository abstraction 或有明确的策略职责。本次不进行风险性“为删而删”。

关联与验证

  • Closes #491 准确:该 issue 记录了本 PR 已实现且已确认的工程质量改进。
  • 本地 bash ./scripts/doctor.sh 通过:703 项测试、93.02% 覆盖率、mypy、ruff、pre-commit、依赖兼容、构建和 wheel smoke test 均通过。
  • GitHub Actions 当前仍在运行,等待远端检查完成。

@liujuanjuan1984

Copy link
Copy Markdown
Collaborator Author

复审追加:SQLite-only 收敛

首次自审后发现并清理了一个高置信的非必要兼容分支:DatabaseTaskStoreCompat 的 PostgreSQL 原子写入路径与已声明的 SQLite-only 支持矩阵矛盾。

  • 配置层现在拒绝非 sqlite+aiosqlite 的持久化 URL。
  • 已删除 PostgreSQL insert factory、方言回退分支及只服务于该分支的测试。
  • 测试 fixture 改为在原 async test loop 内释放 application database engine,修复完整测试中出现的 aiosqlite 线程回调到已关闭 loop 的警告。

最终验证:bash ./scripts/doctor.sh 通过,702 项测试通过、覆盖率 93.11%,且无 pytest warning。

@liujuanjuan1984

Copy link
Copy Markdown
Collaborator Author

补充审查与收敛结果:\n\n- 以配置层仅接受 sqlite+aiosqlite 为可达性边界复核全仓。\n- 已删除余下两处不可达的非 SQLite 方言条件:engine 的非 SQLite pool_pre_ping 分支,以及持久化运行摘要的 not_applicable 分支;测试中的 PostgreSQL URL 样例也已替换为 SQLite URL。\n- 未发现其他 PostgreSQL 驱动、方言分支或依赖残留。文档中的 PostgreSQL 字样仅用于明确不支持,配置测试中的 PostgreSQL URL 仅用于验证拒绝行为。\n- migrations.py 中对 SQLAlchemy dialect 的使用仅用于针对当前 SQLite connection 安全编译 ALTER TABLE 语句,并非多数据库兼容路径,保留。\n\n验证:bash ./scripts/doctor.sh 通过(702 项测试、93.11% 覆盖率,以及类型、格式、依赖、构建和 wheel smoke 校验)。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

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

1 participant