[chore] 工程卫生治理汇总与进展跟踪

[liujuanjuan1984]

背景

本 issue 用于汇总当前仓库的工程卫生发现、治理计划与推进进展，作为后续子问题与变更的统一追踪入口。

首轮评估见：Relates to #248

当前发现

1. 发布包运行时依赖主要只有下界、缺少上界，安装结果可复现性不足。
2. 发布 workflow 的质量门禁弱于主干 CI，tag 发布前未重跑完整回归基线。
3. wheel smoke test 依赖本地 dist/ 现状，可能误测旧产物，且只覆盖 Python 3.13。
4. 测试覆盖率只控制总量阈值，核心大文件仍存在低覆盖热点。
5. 版本兜底值硬编码为过时常量，特殊场景下可能返回错误版本。

治理原则

• 优先修复会影响发布可信度、安装可复现性、回归门禁有效性的问题。
• 每次提交只处理与当前治理项直接相关的改动。
• 关键进展、风险和剩余问题持续回填到本 issue。

计划中的治理顺序

1. 加强发布门禁，使 release workflow 至少覆盖与 CI 对齐的关键验证。
2. 修复构建产物 smoke test 的产物选择与解释器覆盖问题。
3. 修复版本兜底逻辑，避免返回明显错误的版本号。
4. 评估并收紧运行时依赖策略。
5. 针对核心热点模块补充测试或拆分复杂度。

当前进展

• 完成首轮工程卫生评估
• 开始逐项治理

快照

• git rev-parse HEAD: e1ca009

[liujuanjuan1984]

本轮已在 chore/engineering-hygiene-assessment 分支完成以下治理：

• 已加强 release workflow：发布前重跑回归基线与依赖审计，并在构建前清理旧产物目录。
• 已修复 smoke test 脚本：
  • 多个本地 wheel 并存时要求显式指定目标产物，避免误测旧包。
  • 不再固定使用 Python 3.13，改为默认跟随当前解释器。
• 已修复版本兜底逻辑：缺失包元数据时返回 0+unknown，避免误报为历史发布版本。
• 已收紧运行时与开发依赖的版本范围，并同步更新 uv.lock。
• 已补充一轮参数解析与 text-parts 的测试，收回一部分低成本覆盖缺口。

当前验证结果：

• bash ./scripts/doctor.sh 通过
• uv run pip-audit 通过
• uv build --no-sources 通过
• bash ./scripts/smoke_test_built_cli.sh <latest-wheel> 通过

当前剩余主要项：

• 大体量核心模块（尤其 jsonrpc_ext.py、opencode_client.py）仍存在覆盖率热点，需要进入下一轮更有针对性的测试补强或结构拆分。

[liujuanjuan1984]

继续推进覆盖率热点治理，新增两类针对性测试：

1. tests/test_opencode_client_params.py

• 补充了响应预览、非 JSON 错误上下文、model ref 归一化、create_session 缺失 id、send_message 输入校验、客户端级 agent/system/variant 注入、中断请求缓存边界等分支。

2. tests/test_jsonrpc_ext_helpers.py

• 新增对 JSON-RPC 扩展辅助函数的单测，覆盖 permission/question 规范化、prompt/command/shell 参数校验、provider/model catalog 归一化等纯逻辑分支。

结果：

• jsonrpc_ext.py 覆盖率从 78% 提升到 86%
• opencode_client.py 覆盖率从 77% 提升到 86%
• text_parts.py 覆盖率提升到 100%
• 总覆盖率提升到 88.31%

当前验证：

• uv run pre-commit run --all-files 通过
• uv run pytest 通过（260 passed）

剩余热点已明显收敛，后续如果继续治理，可以优先看 agent.py 中最集中的未覆盖业务分支，而不是再补零散 helper 测试。

[liujuanjuan1984]

补充完成版本 fallback 的最后一处对齐：

• pyproject.toml 中 tool.setuptools_scm.fallback_version 已从 0.1.0 调整为 0+unknown。
• 这样源码包构建时的版本兜底与运行时 __version__ 兜底语义保持一致，不再出现“构建产物和运行时对 fallback 版本理解不一致”的情况。

验证：

• uv run pre-commit run --all-files 通过
• uv run pytest 通过（260 passed，总覆盖率 88.31%）
• uv build --no-sources 通过

[liujuanjuan1984]

继续推进 agent.py 热点治理，新增 tests/test_agent_helpers.py，覆盖了以下 helper 层分支：

• _StreamOutputState 的 echo/progress/interrupt 边界
• 上游 HTTP / in-band 错误的 profile、detail 提取与格式化
• terminal signal 等待与异常结束场景
• TTL cache 的 refresh / disabled / pop 行为
• output metadata、number coercion、token usage / usage merge
• role / session / terminal signal / progress / interrupt 相关提取与归一化
• 日志预览 fallback 与截断逻辑

结果：

• agent.py 覆盖率从 88% 提升到 93%
• 仓库总覆盖率提升到 90.16%

验证：

• uv run pre-commit run --all-files 通过
• uv run pytest 通过（272 passed）

当前剩余热点已集中在更深的执行路径与部分 streaming 分支，后续若继续推进，优先级可以转向 app.py 或 agent.py 主流程中的特定异常/取消分支，而不是继续补 helper。

[liujuanjuan1984]

本轮继续推进后，已知工程卫生项可以视为全部完成闭环：

• app.py 补齐了一轮行为与分支测试，新增 tests/test_app_behaviors.py，覆盖 request payload helpers、agent card builder、REST adapter、handler cancel/resubscribe、non-blocking message send、logging/main 等路径。
• 本轮全量验证通过：uv run pre-commit run --all-files、uv run pytest
• 覆盖率结果：
  • app.py 96%
  • agent.py 93%
  • jsonrpc_ext.py 86%
  • opencode_client.py 86%
  • total 91.64%

结论：

• 之前列出的已知工程卫生问题（发布门禁、构建产物污染、smoke test 稳定性、依赖约束、版本 fallback、主要覆盖率热点）都已完成治理。
• 目前剩余的是常规增量优化空间，不再属于本轮已知问题清单里的阻塞项。

[liujuanjuan1984]

追加后续工程卫生治理项：

1. 提高 coverage gate，并为关键高复杂度模块增加单文件最低覆盖率门槛。
2. 重构 CI 结构，避免在 Python 版本矩阵中重复执行静态检查、pip-audit、build 与 smoke test。
3. 为发布产物补充 sdist 安装路径的 smoke test，避免仅验证 wheel。
4. 收紧 mypy 配置，逐步减少 ignore_missing_imports 带来的类型信号缺失。

说明：

• 上述四项继续在当前分支推进。
• agent.py / jsonrpc_ext.py / app.py 的大文件拆分重构单独建 issue 跟踪，本分支不实施结构性拆分。

[liujuanjuan1984]

继续推进 2 / 3 / 4 / 5 后，当前分支已完成以下治理：

• coverage gate 提升：总覆盖率门槛从 80% 提高到 90%，并新增 scripts/check_coverage.py，对 agent.py / app.py / jsonrpc_ext.py / opencode_client.py 增加单文件最低覆盖率门槛。
• CI 去重：ci.yml 调整为单独的 quality-gate（3.13 上执行 lint / pytest+coverage / pip-audit / build / smoke）和 runtime-matrix（3.11/3.12 仅执行运行时 pytest），避免在版本矩阵中重复跑静态检查、审计和构建。
• 发布验证增强：publish.yml 现在会同时校验 wheel 与 sdist 的唯一性和版本一致性，并分别执行 wheel/sdist 安装 smoke test。
• mypy 收紧：移除全局 ignore_missing_imports = true，开启 check_untyped_defs 与 warn_return_any，并修复了新暴露出的类型问题。
• smoke script 泛化：smoke_test_built_cli.sh 支持显式 artifact 路径，兼容 wheel/sdist，并在参数歧义时直接失败。

额外说明：

• 按要求，大文件拆分重构未在本分支实施，已拆分成独立 issue：[chore] 拆分超大核心模块以降低结构复杂度 #250。

本轮验证通过：

• uv run pre-commit run --all-files
• uv run pytest
• uv run pip-audit
• uv run python ./scripts/check_coverage.py
• bash -n scripts/*.sh
• uv build --no-sources --out-dir <tmp>
• bash ./scripts/smoke_test_built_cli.sh <wheel>
• bash ./scripts/smoke_test_built_cli.sh <sdist>

当前覆盖率：total 91.64%，agent.py 93%，app.py 96%，jsonrpc_ext.py 86%，opencode_client.py 86%。