Skip to content

[Enhancement] 启用 Ruff 安全规则集(S)并收敛 24 处 assert #539

Open

Description

@liujuanjuan1984

背景

本仓库 .github/workflows/validate.yml 的静态检查通过 pre-commit 调用 ruff,但 pyproject.toml 的规则集为:

[tool.ruff.lint]
select = ["E", "F", "I", "B", "UP"]

缺少 S(flake8-bandit 安全规则)。同类仓库(如 codex-a2a)已启用 S,本仓库作为对外提供 A2A/JSON-RPC 服务的运行时,缺少静态安全规则是一处门禁缺口。

现状核实

实测(main):

uv run --locked --extra dev ruff check --select S --statistics src/opencode_a2a

结果:24 处 S101(Use of assert),集中在:

  • src/opencode_a2a/jsonrpc/handlers/session_lifecycle.py(11 处)
  • src/opencode_a2a/jsonrpc/handlers/session_queries.py(4 处)
  • src/opencode_a2a/jsonrpc/handlers/workspace_control.py(3 处)
  • src/opencode_a2a/server/agent_card.py(2 处)
  • src/opencode_a2a/jsonrpc/handlers/provider_discovery.py(1 处)
  • src/opencode_a2a/server/rest_tasks.py(1 处)

除 S101 外没有其他 S 违例。多数 assert 是 mypy 的类型收窄(assert session_id is not None,在前置校验之后);少数是内部不变量断言(如 agent_card.py 的扩展 URI 顺序校验)。

需要决策/处理的问题

  1. 对类型收窄类 assert:是保留(python -O 下会消失,但不影响外部契约),还是改成显式 raise。
  2. 对内部不变量类 assert:建议改为显式 raise(避免 python -O 下被剥离)。
  3. 不要通过 ignore = ["S101"] 之类的全局豁免来“通过规则”——那会重新引入本仓库正在治理的“掩盖问题”模式。

验收标准

  • pyproject.toml 的 ruff 规则集包含 S,且 uv run ruff check 在 src/ 与 tests/ 上通过。
  • tests/ 可按需使用 per-file-ignores 关闭 S(测试内断言属正常用法),但 src/ 不允许全局豁免 S101。
  • bash ./scripts/doctor.sh 全绿;新增/修改的行为有对应测试覆盖,且不降低覆盖率门禁。

说明

该事项独立于 #537(CI lint 门禁严格性修复),单独跟踪以避免把 24 处断言改造混入门禁修复 PR。

Activity

  1. liujuanjuan1984 commented on Oct 2, 2026

    @liujuanjuan1984
    CollaboratorAuthor

    按评审要求(不拆分更多细节 PR,把此前发现的 CI/静态检查改动合入既有 PR),本 issue 的工作已并入 PR #538(该 PR 以 Closes #539 关联,合并后自动关闭)。

    落地方式(对齐 codex-a2a 的既有做法):

    • pyproject.toml 规则集加入 S,并对 tests/** 使用 per-file-ignores 豁免(测试模块本就要用 assert 与假凭证),不扩大豁免范围。
    • src/ 24 处 assert 全部收敛:
      • 校验后类型收窄 → 显式 typing.cast(...)(与 codex-a2a cast(ReviewStartControlParams, parsed_params) 等写法一致);
      • 上游负载缺失守卫(3 处)→ 显式 raise UpstreamContractError(...);
      • 模块级契约不变量(agent_card.py 2 处)→ 显式 raise RuntimeError(...);
      • session_lifecycle.py 末尾的 assert method == ... → 显式 elif + 兜底 raise。
    • scripts/conformance_probe.py 的 S607 通过 shutil.which("git") 消除;残留 S603 为静态误报,就地 # noqa: S603 并写明原因(与 codex-a2a 同类写法一致)。

    验证:ruff check(含 S)/ ruff format --check / mypy / pre-commit --all-files 全部通过,bash ./scripts/doctor.sh 退出码 0(覆盖率 93.46%)。

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions