Skip to content

docs(readme): 重写中英文 README,补充产品截图与品牌素材 - #27

Merged
JohnWuY merged 1 commit into
mainfrom
feature/readme-refresh
Nov 16, 2026
Merged

JohnWuY merged 1 commit into
mainfrom
feature/readme-refresh

Conversation

@JohnWuY

@JohnWuY JohnWuY commented Nov 16, 2026

Copy link
Copy Markdown
Collaborator

改了什么,为什么 / What changed and why

原来的 README 更像操作说明:没有图片,也没有写清支持哪些平台、当前是什么版本,访客打开仓库首页看不出 OpenTest 能做什么。这次参照 yetone/magpie 的结构,用 opentest.com 上的产品资料重写了中英文 README。两个语言版本逐段对应。

The old README read like a manual, with no images, platforms or versions. Both README files are rewritten as a product landing page based on opentest.com, mirroring the structure of yetone/magpie.

  • 首屏:OpenTest 图标、标语、版本 / Star / 许可徽章、平台徽章、导航链接和 FFT 测量界面大图。
  • 支持的平台与版本:官网安装包 V2.4.0 Beta(Windows 10/11 x64)、GitHub 社区每日构建 2.5.0-dev(Windows x64)、源码构建(Windows x64 / macOS arm64 / Linux x64)。
  • 内容:快速开始(源码构建折叠)、三种模式、6 个分析模块截图及对应 IEC / ISO / GB/T 标准、产线序列、报告、按协议列出的硬件兼容表、插件与 OpenTest CLI、版本与许可、核心概念(折叠)、FAQ、文档入口、社区和 Star 曲线。
  • 图片:放在 docs/assets/readme/(12 张,截图量化为 256 色)和 docs/assets/brand/(图标、横版 Logo、社交预览图),共约 1.1 MB,不依赖官网的图片路径。

几处表述与官网不同,按仓库的实际情况处理:

  • 官网写“核心功能全部开源”,README 按 OpenTest Community License 写“源码开放”。
  • 版本表只写通道数和主要能力,不写价格,注明以定价页为准。

怎么验证的 / How it was verified

  • 单元测试或集成测试 / Unit or integration tests

  • 真机验证 / Verified on real hardware(型号 model:,驱动 driver:)

  • 不涉及设备 / Does not affect devices

  • node tools/check-docs.mjs --base origin/main:0 条违规。

  • README 中的本地链接全部存在;外部链接均返回 200(stargazers 页面未登录时返回 404,登录后正常)。

  • 用 GitHub Markdown API 渲染两份 README:各 21 张图、8 个表格、2 个折叠区,无残留 Markdown 符号。

影响 / Impact

  • 修改了插件 API、通信协议或数据格式,已加 breaking-change 标签并附 ADR / Changes the plugin API, protocol or data format
  • 用户可见的改动,已更新文档 / User-visible change, documentation updated
  • release 分支也需要这个修复,已加 backport-to-release/A.B 标签 / Also needed on a release branch

贡献授权 / Contribution license

  • 我已阅读并同意 OpenTest 社区许可协议第 11 条“社区贡献” / I have read and agree to section 11, Community Contributions, of the OpenTest Community License

以 opentest.com 的产品资料为来源,按 magpie README 的结构重写宣传型首页:居中 Logo 与徽章、支持平台与版本表、快速开始、三种模式、分析模块截图、产线序列、报告、硬件兼容表、插件与 CLI、版本与许可、FAQ、文档入口和社区。图片放在 docs/assets 下,不依赖官网路径。
@JohnWuY
JohnWuY requested a review from a team November 16, 2026 06:15

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

AI 代码审查(claude-opus-5-5)

本次改动只涉及中英文 README 和图片素材,没有代码风险。主要问题是部分内容与仓库领域规范(CONTEXT.md)和许可协议不一致,需要在合入前修正:

  1. 版本表与许可摘要、FAQ 互相矛盾:版本表把序列、分析、录制、导出与报告划到付费版本,但正文、FAQ 和许可摘要都写“免费版即可满足企业内部生产需求”。
  2. 插件禁用和卸载的说明与领域定义不符:去掉了“禁用或卸载期间无法查看和导出结果”这一限制。
  3. 许可摘要漏掉了限制条件:“为客户提供测试服务”的免费条件少了“软件本身不交付给客户”。

其他说明:

  • README.md 的 diff 在第 143 行后被截断。下文针对 README.zh-CN.md 第 143 行之后内容(版本表、许可摘要、FAQ、插件说明)的意见,同样适用于英文版对应段落,请一并检查。
  • 拉取请求模板中“贡献授权(社区许可协议第 11 条)”一项未勾选。按项目流程,合并前需要提交者确认。
  • 截图和品牌素材在 diff 中不可见,本次未审查图片内容。

跳过 15 个文件(锁文件、生成文件、二进制或无文本 diff)

由 AI 自动生成,仅供参考,不作为合并依据。审查提交:6a1e8d8。维护者可评论 /review 重新审查。

Comment thread README.zh-CN.md
---
| 版本 | 通道数 | 主要能力 |
| :-- | :-- | :-- |
| **Community 社区版** · 免费 | 4 | 实时监测与信号发生器,基础 FFT、倍频程和扫频 |

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟠 中 版本表与本文其他位置相互矛盾:

  • 这里写社区版只有“实时监测与信号发生器,基础 FFT、倍频程和扫频”,序列模式、分析模式、录制、导出与报告要 Advanced 版才有。
  • 第 32 行、第 36 行把序列 / 产线描述为免费社区许可覆盖的场景,第 181 行 FAQ 写“免费版就能满足大多数研发和企业内部生产需求”。
  • 第 111 行模块表又把倍频程、扫频标为“官方安装包”,而不是社区版能力。

访客无法判断免费版到底能用什么。建议二选一:

  • 去掉功能分级,只链接定价页;
  • 或者明确区分“源码许可(OpenTest Community License)”和“功能权益 / 版本”,并统一修改 FAQ 和第 36 行的说法。

英文版对应段落需要同步修改。

Comment thread README.zh-CN.md

**没有专业采集卡能用吗?** 可以。电脑声卡和 USB 麦克风通过 Windows 音频即可接入,但无法保证仪器级精度,正式测试请使用经过校准的测量硬件。

**卸载插件会丢数据吗?** 不会。数据和配置都会保留,重新启用兼容版本后即可再次查看该插件的结果。

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟠 中 这条 FAQ 与 CONTEXT.md 中“插件禁用”的定义不一致。按定义,禁用期间所属历史结果的查看和导出都不可用,卸载期间同样无法查看。旧版 README 写明了“卸载或禁用期间无法查看和导出该插件的结果”,新版删掉了这一限制。另外,卸载之后应当是“重新安装”,而不是“重新启用”。

建议改为:“不会。数据和配置会保留,但卸载或禁用期间无法查看和导出该插件的结果;重新安装或启用兼容版本并完整重启后即可恢复。”英文版 FAQ 请同步修改。

Comment thread README.zh-CN.md

<sub>月付、年付、永久授权以及完整功能对比见[定价页](https://www.opentest.com/zh-hans/%E5%AE%9A%E4%BB%B7/),版本划分以定价页为准。</sub>

本仓库源码采用 **[OpenTest Community License 1.0](LICENSE.zh-CN.md)**。简单来说:个人使用、教育、科研、软件与产品研发、企业内部使用(包括生产环境),以及用 OpenTest 为客户提供测试服务,都可以免费使用,每套系统最多 **4 个可同时使用的物理通道**。需要更多通道、随硬件或其他产品交付(OEM、ODM、白牌)、出售或再分发,或以收费托管服务形式提供时,需要商业许可。以上为摘要,以协议原文为准。

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟠 中 许可摘要与原条款相比有偏差:

  • 旧版写“用 OpenTest 为客户提供测试、测量等技术服务(软件本身不交付给客户)”。新版删掉了括号中的条件,读者可能误以为把软件交付给客户也属于免费范围。
  • “出售或再分发”笼统地把再分发都列为需要商业许可,原文是“作为商业软件出售、出租或重新包装分发”。请以 LICENSE.zh-CN.md 的实际条款为准。

许可摘要属于法律相关内容,建议恢复限制条件,并与协议原文逐条核对。英文版同步检查。

Comment thread README.zh-CN.md
## 插件与 AI 辅助 CLI

## 开始使用
**插件。** 核心以外的能力都以 `.otplugin` 安装包提供:**业务插件**增加测量项,**设备插件**接入新硬件。在 **设置 → 插件管理** 中导入并重启即可生效;禁用或卸载插件不会删除已有数据。插件直接复用 OpenTest 的采集、算法、存储和图表,你只需编写自己的测量逻辑或设备对接。[OpenTest-Plugins](https://github.com/crysound/OpenTest-Plugins) 提供 FFT 和 SonoDAQ 插件的完整源码,可作为模板。插件是否开源、是否收费由你决定;开发和销售独立插件不需要额外的商业许可。

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 低 “导入并重启即可生效”没有说清楚是哪种重启。按 CONTEXT.md,插件变更要在完整重启(桌面端和后端都重启)后才生效,刷新页面或只重启窗口都不够;生效前还可以撤销。旧版 README 写有“插件需与 OpenTest 版本匹配”“完整重启后生效”,新版删掉了。建议补回“完整重启”和版本兼容的说明。

Comment thread README.zh-CN.md
<sub>官网下载按钮始终指向最新的官方版本。社区构建未签名,已关闭自动更新,安装前请核对发布页给出的 SHA-256。第一次测量时,一支能被 Windows 识别的麦克风就够用。</sub>

OpenTest 的测量能力由**内置功能**和**可选插件**两部分组成,你可以只安装需要的部分。
**2 · 登录并连接设备。** 用 CRYSOUND 云账号登录,或导入离线授权(本机或 USB)。接好设备,在 **设置 → 硬件** 中刷新,把需要的通道加入工程并填写传感器灵敏度。

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 低 英文版区分了 Setup → Hardware(准备页)和 Settings → Plugin Management(设置页),中文版第 54 行和第 147 行都写成“设置”,会让用户找错页面。旧版中文用的是“准备(Setup)”。建议按界面实际文案改为“准备 → 硬件”或保留英文原名。

Comment thread README.zh-CN.md
| 安装包 | 版本 | 平台 | 说明 |
| :-- | :-- | :-- | :-- |
| **官网安装包**(推荐) | V2.4.0 Beta | Windows 10 / 11,x64 | 从 [opentest.com](https://www.opentest.com/zh-hans/%E4%B8%8B%E8%BD%BD-2/) 下载,约 381 MB,包含完整的官方插件。V0.6.1 起的历史版本见[历史版本](https://www.opentest.com/opentest-software-previous-versions/?otd_product=opentest)页面 |
| **社区每日构建** | 2.5.0-dev | Windows 10 / 11,x64 | 由 CI 基于 `main` 构建,发布在 [GitHub Releases](https://github.com/crysound/OpenTest/releases),未签名。包含 OpenTest 和 [OpenTest-Plugins](https://github.com/crysound/OpenTest-Plugins) 中的公开插件(FFT 与 SonoDAQ 设备插件),每个版本附 SHA-256 |

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 低 按 CONTRIBUTING,每日构建的实际版本号为 A.B.C-dev.<年月日>,同一天的后续构建再加 .2、.3。这里写死的 2.5.0-dev,以及第 42 行的 V2.4.0 Beta、“约 381 MB”,都会在下次发布后过时,而且没有机制提醒更新。建议改为“见 Releases 页面最新预发布版本”,或者依赖首屏的 release 徽章,不在正文写死具体版本号和体积。英文版同理。

Comment thread README.zh-CN.md

| 安装包 | 版本 | 平台 | 说明 |
| :-- | :-- | :-- | :-- |
| **官网安装包**(推荐) | V2.4.0 Beta | Windows 10 / 11,x64 | 从 [opentest.com](https://www.opentest.com/zh-hans/%E4%B8%8B%E8%BD%BD-2/) 下载,约 381 MB,包含完整的官方插件。V0.6.1 起的历史版本见[历史版本](https://www.opentest.com/opentest-software-previous-versions/?otd_product=opentest)页面 |

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 低 中文版的“历史版本”链接指向英文页面(缺少 /zh-hans/ 前缀),本行其他官网链接都指向中文站。如果官网有对应的中文页面,建议改为中文链接。

@JohnWuY
JohnWuY merged commit d2c55d8 into main Nov 16, 2026
11 of 13 checks passed
@JohnWuY
JohnWuY deleted the feature/readme-refresh branch November 16, 2026 06:31
JohnWuY added a commit that referenced this pull request Nov 16, 2026
## 改了什么,为什么 / What changed and why

Refs #27

- **首屏图**:原图只保留了测量插件区,缺少顶部导航(Setup / Measure / Report)和左侧通道栏,看不出
OpenTest 的主框架。换成完整主界面的显示器样机图
`docs/assets/readme/opentest-main-window.webp`(1800×1243,152 KB,保留透明背景,在
GitHub 浅色和深色主题下都正常显示),删除旧图 `fft-measure-workspace.png`,中英文图片说明同步更新。
- **NI-DAQmx**:框架本身不支持 NI-DAQmx,需要额外插件。从中英文 README 的卖点句、硬件兼容表(NI
一行)和硬件章节开头三处移除。

The hero image showed only the measurement plugin area; it is replaced
with a full main-window screenshot. NI-DAQmx is removed from both
READMEs because the framework does not support it without an extra
plugin.

## 怎么验证的 / How it was verified

- [ ] 单元测试或集成测试 / Unit or integration tests
- [ ] 真机验证 / Verified on real hardware(型号 model:____,驱动 driver:____)
- [x] 不涉及设备 / Does not affect devices

- `node tools/check-docs.mjs --base origin/main`:0 条违规。
- 用 GitHub Markdown API 渲染两份 README:各 21 张图、8 个表格,新首屏图正常引用。
- README 中已搜不到 NI-DAQmx / cDAQ / USB-4431。

## 影响 / Impact

- [ ] 修改了插件 API、通信协议或数据格式,已加 `breaking-change` 标签并附 ADR / Changes the
plugin API, protocol or data format
- [x] 用户可见的改动,已更新文档 / User-visible change, documentation updated
- [ ] release 分支也需要这个修复,已加 `backport-to-release/A.B` 标签 / Also needed on
a release branch

## 贡献授权 / Contribution license

- [ ] 我已阅读并同意 OpenTest 社区许可协议第 11 条“社区贡献” / I have read and agree to
section 11, Community Contributions, of the OpenTest Community License

Co-authored-by: 吴勇 <wuyong@wuyongdeMacBook-Air.local>
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