Skip to content

bug: plugins built from a source checkout report version 0.1.0 instead of the release tag #511

Open

Description

@Dong1017

Posted by an agent on behalf of @Dong1017; bug report for discussion, no fix is included.

Current state: Proposed。从源码构建的插件包,版本号固定为模板里的 0.1.0(DSH 为 0.0.0),不跟随所在的 release tag;只有发版流程传 --release-version 时才改写。
Decision needed: 维护者确认这是否算缺陷,以及期望的版本口径(见「期望行为」的两种做法)。
Next action: 确认口径后另开修复 PR;本 issue 不授权实现或合并。

复现

核查基线:tag v0.2.5、main 9b418d7f(2026-11-19)。

git worktree add --detach /tmp/wt v0.2.5
cd /tmp/wt
python3 tools/build_codex_plugin.py --output /tmp/b/codex   # 文档「Build from the InferRSI source checkout」一节的命令
unzip -p /tmp/b/codex.zip inferrsi/plugin.json          -> "version": "0.1.0"
unzip -p /tmp/b/codex.zip inferrsi/runtime/manifest.json -> "plugin_version": "0.1.0", "runtime_version": "0+unknown"

对照:Release 资产 inferrsi-codex-plugin-v0.2.5.zip 里 plugin.json 的 version 与 runtime/manifest.json 的 plugin_version、runtime_version 均为 0.2.5,发布包本身正确。

原因(静态阅读)

  • 模板版本号写死:plugins/inferrsi/plugin.json、plugins/workswarm/inferrsi/manifest.json 为 0.1.0,plugins/inferrsi-dsh/package.json 为 0.0.0;v0.2.3–v0.2.5 三个 tag 上均如此。
  • tools/plugin_bundle.py 只在传入 release_version 时把它写进插件元数据(metadata["version"] = release_version),否则沿用模板值,并把同一个值写进 runtime/manifest.json 的 plugin_version。
  • .github/workflows/release.yml 构建时传 --release-version "${RELEASE_TAG#v}",所以只有发版产物正确。
  • tools/build_dsh_plugin.py 没有 --release-version 参数,DSH 包从源码构建时始终是 0.0.0。

影响

  • 在 tag 上从源码构建,插件显示 0.1.0,看起来像一个真实发布过的版本(README 里有 v0.1.0 Developer Preview),容易被误认为装了旧版。
  • 运行时已构建(_version.py 由 SCM 生成)但未传 --release-version 时,按代码路径 plugin_version 为 0.1.0、runtime_version 为真实版本,同一个包内两个版本号不一致;这一路径为静态阅读推断,本次只实跑了未构建运行时的情形。
  • docs/codex-plugin.md 写明「Unbuilt source previews use the runtime's explicit 0+unknown fallback」,但插件自身版本没有对应的「未知」标记。

期望行为(供维护者选)

  1. 未传 --release-version 时,插件版本跟随构建出的运行时版本(_version.py 存在时取它,否则取 0+unknown),使 plugin_version 与 runtime_version 一致;或
  2. 保持模板不变,但把模板值改成明显的占位(如 0+unknown / 0.0.0+source),并在文档里写明源码构建的插件版本不代表 release。

DSH 构建是否同样补 --release-version 或跟随运行时版本,一并决定。

Ownership and authorization

  • Proposed by / actual requester: @Dong1017
  • Status: Proposed
  • Accepted decision or scoped delegation: Not yet granted

Scope checked: 在 v0.2.5 的隔离 worktree 实跑一次 Codex 插件源码构建;下载并解包 v0.2.5 Release 的 Codex 插件 ZIP;静态阅读 tools/plugin_bundle.py、tools/build_codex_plugin.py、tools/build_dsh_plugin.py、.github/workflows/release.yml、docs/codex-plugin.md、docs/releases.md。未构建 WorkSwarm 与 DSH 包,未跑「运行时已构建但不传版本」的情形。

Activity

  1. added
    kind:bugDefect report: an observable symptom that differs from expected behavior
    on Nov 19, 2026
  2. Dong1017 commented on Nov 19, 2026

    @Dong1017
    CollaboratorAuthor

    Posted by Dong-bot, an automated agent acting on behalf of @Dong1017 (always-on-bot, model claude-sonnet-5-5).

    评估: 这是个真实但低严重度的缺陷,属于版本口径不一致,不影响发布包。issue 已有 v0.2.5 Release ZIP 的对照,说明发布流程是对的。我倾向选期望行为 1(跟随运行时版本),并加下面几条约束。我没有运行任何构建,以下判断基于 issue 正文里的复现和静态阅读。

    为什么倾向方案 1

    • 方案 2 只是把 0.1.0 换成占位符。plugin_version 和 runtime_version 仍是两个独立来源,issue 里第二条影响(已构建运行时但不传 --release-version 时两者不一致)还会存在。
    • 方案 1 让两个字段共用一个来源,源码构建时也不会出现看起来像真实发布版的 0.1.0。

    落地前需要澄清的点

    1. 版本格式约束。 _version.py 由 SCM 生成,通常是 PEP 440,例如 0.2.6.dev3+gabcdef。plugin.json、WorkSwarm manifest.json 和 DSH 的 package.json 大概率要求 semver。package.json 对格式要求最严,裸的 0+unknown 不是合法 semver。需要确认三类消费方各自接受什么格式。如果要统一,可以用 0.0.0+unknown,并规定 PEP 440 到 semver 的转换规则。
    2. DSH 的处理。 建议 tools/build_dsh_plugin.py 补上与 Codex 构建一致的 --release-version 和回退逻辑,不要只改 Codex。否则 DSH 源码构建永远是 0.0.0,口径仍然分裂。
    3. 模板里的 0.1.0。 即使选方案 1,模板里的硬编码值也应改成明确的占位符(如 0.0.0+unknown),避免有人绕过构建脚本直接读模板时再次误认。这等于吸收了方案 2 的一部分,且不冲突。
    4. 发布一致性校验。 release.yml 已传 --release-version。可以加一步断言:发布包的 plugin_version、runtime_version 与 tag 相同。这样以后改动构建逻辑不会悄悄破坏发布包。
    5. 覆盖范围。 issue 说明没有构建 WorkSwarm 和 DSH 包,也没有跑「运行时已构建、不传版本」的情形。修复 PR 里需要补这些验证,并加测试:
      • 未传版本且无 _version.py 时,两个字段都为 0+unknown(或统一后的占位符)。
      • 已构建运行时时,两个字段一致。
      • 传了 --release-version 时,行为与现在相同。
    6. 文档。 修复后更新 docs/codex-plugin.md 的 0+unknown 那一段,说明插件版本也遵循同一规则;docs/releases.md 视情况同步。

    建议的下一步

    • 维护者在方案 1 与方案 2 之间定口径,并回答第 1 点的格式约束和第 2 点 DSH 是否纳入。
    • 口径确认后另开修复 PR,范围涵盖 tools/plugin_bundle.py、tools/build_dsh_plugin.py、三个模板版本字段、文档和上述测试。
    • 本 issue 按正文所述,目前不授权实现。

    Dong-bot(authorized delegate):以上是首轮建议,不构成已记录的维护者决定。要把口径定下来,请在本 issue 里 @Dong1017 明确选择。

  3. zengchuang-hw commented on Nov 19, 2026

    @zengchuang-hw
    Contributor

    独立静态核对基线 9b418d7fe16f3979b67f74f290949629ef103e8f 后,建议把这里拆成两个明确的版本契约问题,而不是直接把模板值替换掉。

    1. 选项 1 本身不会让“干净 tag checkout 直接打插件包”得到 tag 版本。 tools/plugin_bundle.py 当前只读源码 _version.py,不存在时从 __init__.py 取 0+unknown;生成该文件的是 pyproject.toml 的 setuptools-scm 构建配置。因而“plugin_version 跟随 runtime_version”可以消除模板/runtime 分歧,但没有生成版本文件的 v0.2.5 checkout 仍会得到 unknown。若验收目标确实是源码 tag 自动得到 0.2.5,需要另行明确构建前置步骤或源码版本解析策略;不要把两种目标混成同一个修复。

    2. 我倾向于保留显式 release 模式,源码模式明确标识为非 release。 现有 --release-version 仅接受三段数字且必须匹配 built runtime,失配在写输出前拒绝,这个保护应保留。源码默认值是否从 runtime 派生由维护者决定,但应先确认各宿主接受的版本格式,尤其不能未经格式验证就把 Python 开发版字符串或 0+unknown 原样写入所有宿主 metadata。DSH 目前确实没有 release-version 参数,应在同一决策中说明它是否支持 release 模式,而不只是改 package.json 的常量。

    3. 建议补的回归矩阵很小且有针对性: 无 _version.py 的源码包、有生成版本但未传 release-version、显式 release-version 匹配/失配,分别检查 Codex、WorkSwarm、DSH 的顶层 metadata、runtime manifest 和 --plugin-info。现有 tests/test_codex_plugin.py:429–443 已覆盖 release 失配与不导入外部已安装 runtime 的 unknown fallback;保留这些保护。现有 DSH 测试检查输出彼此一致,却未约束“预期源码版本是什么”,所以模板常量也能通过。

    版本标签与内容身份应继续分开:manifest 已保留 content_sha256,不应把同一个 version 当作不同源码包字节相同的证明。

    以上是实际实现与测试定义的静态检查,不是构建复现;未检查 CI、未执行仓库代码、未核验 Release 二进制,也未接受范围或实施修复。

  4. added
    area:harnessHarness module: profile, A/B loop, quality gates, evidence reports
    on Nov 19, 2026
  5. Dong1017 commented on Nov 19, 2026

    @Dong1017
    CollaboratorAuthor

    @Dong1017 claim

  6. Dong1017 commented on Nov 19, 2026

    @Dong1017
    CollaboratorAuthor

    Posted by Dong-bot, an automated agent acting on behalf of @Dong1017 (always-on-bot, model claude-opus-5-5).

    Claimed for the PR pool. A coding agent (claude-opus-5-5, effort xhigh) will open a PR, or explain here why it cannot. The PR is merged only after 2 independent approvals.

  7. Dong1017 commented on Nov 19, 2026

    @Dong1017
    CollaboratorAuthor

    Posted by Dong-bot, an automated agent acting on behalf of @Dong1017 (always-on-bot, model claude-opus-5-5).

    The PR pool run stopped: fatal: 无法访问 'https://github.com/InferMatrixLab/InferRSI.git/':Failed to connect to github.com port 443 after 133369 ms: 连接超时

  8. Dong1017 commented on Nov 19, 2026

    @Dong1017
    CollaboratorAuthor

    Posted by an agent on behalf of @Dong1017, the issue owner.

    Decision: option 2, an explicit non-release marker (owner decision, 2026-11-19). This records the version contract the body asked for and authorizes a fix PR. It replaces the body's "Decision needed", "Next action" and "Not yet granted" lines. #512 does not cover this issue: it adds listing fields and leaves "version": "0.1.0" unchanged.

    Contract

    • Source builds (no --release-version): every plugin's own version is 0.0.0+source. This covers plugins/inferrsi/plugin.json, plugins/workswarm/inferrsi/manifest.json and plugins/inferrsi-dsh/package.json. It also covers plugin_version in each runtime/manifest.json and in --plugin-info. 0.0.0+source is valid SemVer 2.0 (build metadata), and the +source part marks the package as not a release.
    • runtime_version keeps reporting the runtime that was actually bundled: 0+unknown without a generated _version.py, or the generated version. So in a source build the two fields differ on purpose, and that difference is documented.
    • Release builds stay exactly as they are. --release-version still accepts only MAJOR.MINOR.PATCH, must match the built runtime, and is rejected before any output is written. .github/workflows/release.yml and tools/check_release.py keep their current release checks.
    • DSH gets no release mode. release.yml publishes only the Codex and WorkSwarm ZIPs, so DSH stays source-only and simply carries the marker.
    • Not in scope: making a clean tag checkout resolve to its tag version, raised by @zengchuang-hw above. That is a separate build-precondition question and can get its own issue. Version labels stay separate from content identity; content_sha256 is unchanged.

    Acceptance

    • The template versions become 0.0.0+source, with no other metadata changes.
    • Regression tests cover Codex, WorkSwarm and DSH. For each, they check the top-level metadata, runtime/manifest.json and --plugin-info in these cases:
      • a source build without _version.py;
      • a source build with a generated _version.py and no --release-version;
      • for Codex and WorkSwarm, an explicit --release-version that matches (release values unchanged) and one that does not (rejected).
    • The existing protections in tests/test_codex_plugin.py stay: release mismatch, and the unknown fallback that does not import an installed runtime.
    • docs/codex-plugin.md (and docs/releases.md if it describes source builds) states that a source-built plugin reports 0.0.0+source and is not a release.
    • The PR lists any host whose published schema is known to reject SemVer build metadata. If one does, stop and report it here instead of choosing another value.
  9. zengchuang-hw commented on Nov 19, 2026

    @zengchuang-hw
    Contributor

    PASS

    版本契约增量复核,不等于实现验收。对照 tools/plugin_bundle.py 和 tools/build_dsh_plugin.py,插件版本和实际 runtime 版本本来就在各打包入口分别传递,源码标记可复用插件字段,不需要改变 release 的严格版本匹配或运行时回退。0.0.0+source 符合 SemVer;Codex 当前打包文档引用的 portable schema 在结构上只要求 version 是字符串,这不是 native-host 导入或显示已验证。

    除已有三处值的回归,建议在有宿主可用时确认实际导入/显示仍有可辨别的 source 标记。同一标记会复用于不同源码包,不要用它替代 content_sha256 或来源提交进行归档比对。未构建插件、导入宿主或查询 CI。

  10. Dong1017 commented on Nov 19, 2026

    @Dong1017
    CollaboratorAuthor

    Posted by Dong-bot, an automated agent acting on behalf of @Dong1017 (always-on-bot, model claude-opus-5-5).

    The PR pool run stopped: the agent timed out after 60 min

  11. Dong1017 commented on Nov 19, 2026

    @Dong1017
    CollaboratorAuthor

    Posted by Dong-bot, an automated agent acting on behalf of @Dong1017 (always-on-bot, model claude-opus-5-5).

    Opened #525 for this issue.

    Source builds of the Codex, WorkSwarm and DSH plugins now report 0.0.0+source as the plugin version, per the owner's option-2 decision. The three template version lines changed. plugin_version in runtime/manifest.json and --plugin-info follows, and runtime_version still reports the bundled runtime. No builder code changed, and --release-version behavior is untouched. Docs (codex, workswarm, dsh, releases) and CHANGELOG.md describe the marker.
    Tests: new tests/test_plugin_source_version.py passed 15/15 (all three hosts, with and without _version.py; Codex and WorkSwarm release match and mismatch). Restoring the old template values made 9 of them fail. With test_workswarm_plugin.py, test_dsh_plugin.py and test_resource_migration.py that is 40 passed, and ruff check src tests tools is clean.
    Not verified: 8 failures in test_codex_plugin.py and 24 errors in test_release.py come from this sandbox lacking git (and PyYAML visible under python -I). I did not run them on a baseline, so they need a re-run where git exists. No release ZIP was built or checked with check_release.py.
    Host schemas: the portable Codex schema only requires version to be a string, and npm's semver parses the value. I found no published WorkSwarm schema and ran no native-host import, so none is known to reject it but none was checked.
    Left: native-host import/display check, and the out-of-scope question of resolving a clean tag checkout to its tag version.

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

    area:harnessHarness module: profile, A/B loop, quality gates, evidence reportskind:bugDefect report: an observable symptom that differs from expected behavior

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions