鸿蒙 PC:码见(ohos_TAMS-Analyzer)质性研究分析工具移植全记录
从 Cocoa 多窗口到 ArkUI 五区导航:一个质性研究工具如何做到零权限、517 KB
一、写在前面
开源地址:https://atomgit.com/OpenHarmonyPCDeveloper/ohos_TAMS-Analyzer
欢迎在PC社区平台申请新建项目:https://atomgit.com/OpenHarmonyPCDeveloper
本文导读
- 要解决的问题:macOS 上跑了二十年的质性研究工具 TAMS Analyzer 是纯 Cocoa 应用,界面零可移植性;更要紧的是它有一套自己的
.tams项目文件,老用户的历史数据必须能带过来。- 你会读到的技术细节:按"建项目 → 导资料 → 编码 → 分析"工作流组织的五区导航、独立的
TamsCompatibility兼容层、零权限声明 + 系统文件选择器的隐私设计、长文本分段渲染。- 本文的实测数据:真机上完成一次真实项目创建(
HarmonyOS_PC_UX_study),界面从空态切到「当前项目 · 进行中」;7 个文件 3394 行,HAP 517 KB——同类应用最小。- 适合谁读:做垂直行业工具、需要兼容历史数据格式、关心"零权限"设计的开发者。
这篇文章记录的是把 TAMS Analyzer 这套质性研究(qualitative research)文本分析工具移植到鸿蒙 PC 上的过程。最终落地的应用叫 码见,包名 com.xujian.insight。
这是整个系列里最"小众"的一期——目标用户不是工程师,而是做访谈研究、田野调查、内容分析的研究者。这类工具的价值不在于算得多快,而在于数据组织方式和编码工作流。
先给结论:
移植完成,工作台、项目空间、代码集、文档、分析、设置六个模块全部实现,真机上完成了一次真实的研究项目创建,界面从空态切换到"当前项目"状态。
验证环境是真实设备:
| 项 | 值 |
|---|---|
| 设备型号 | HUAWEI MateBook Pro S(MOR-M1) |
| 系统版本 | HarmonyOS 7.0.0.111(SP15C00E101R9P2) |
| API 版本 | 26 |
| 设备形态 | 2in1 |
| 构建工具 | DevEco Studio 内置 hvigor 6.26.4 |
| SDK | HarmonyOS SDK 26.0.0.105 |
二、项目背景
TAMS Analyzer(Text Analysis Markup System)是一个从 2000 年代延续至今的质性研究工具,作者是 Matthew Weinstein。它的macOS版本源码来自 SourceForge,仓库里 SOURCE.json 记录得很规范:
{
"project": "TAMS Analyzer",
"version": "4.56b6",
"source_page": "https://tamsys.sourceforge.io/osxtams/download.html",
"sha256": "4606c3fd…",
"verification": "hdiutil verify: VALID"
}
把源版本、下载地址、SHA-256、校验方式一起入库,这是移植项目里很值得提倡的做法——后来者能确认自己基于哪一版做事。
它的技术骨架:
- Objective-C / Cocoa(macOS 原生);
- 文档型应用(
.tams项目文件); - 核心能力:给文本片段打标签(coding)、建立代码本(codebook)、检索、共现分析、导出。
质性研究的工作流大致是:
收集资料(访谈录音转写、田野笔记、文档)
↓ 导入
逐段阅读、标注片段(coding)
↓
建立代码集(同一主题的片段归到一起)
↓
分析(交叉表、共现、引文摘录)
↓
写作
移植的关键判断:
界面必须严格贴合这个工作流,否则研究者不会用。
三、总体变化概览
HarmonyOS/
└── entry/src/main/ets/ 7 个文件 / 3394 行
├── pages/Index.ets 全部界面(2575 行)
├── data/
│ ├── TamsCompatibility.ets TAMS 文件格式兼容(228 行)
│ └── InsightStore.ets 项目与资料存储(194 行)
├── domain/
│ ├── InsightAnalysis.ets 分析逻辑(218 行)
│ └── InsightModels.ets 数据模型(61 行)
├── services/
│ └── MediaDocumentService.ets 媒体/文档导入(99 行)
└── entryability/EntryAbility.ets
技术栈映射:
| TAMS 原方案 | 码见(鸿蒙) |
|---|---|
| Cocoa 多窗口 | ArkUI 单窗口 + 五区导航 |
.tams 项目文件 | InsightStore 结构化存储 |
| 文档窗口 + 编码栏 | 「文档」页 + 「代码集」页 |
| 检索与统计 | 「分析」页 |
| macOS 文件对话框 | 系统文件选择器 |
一个特点:Index.ets 占了 2575 行 / 3394 行(76%)。这和大二期的晶析云类似——质性研究工具的核心是"列表 + 阅读区 + 编码操作"三者共享状态,拆文件反而增加状态传递成本。
四、原始项目直接跑鸿蒙会遇到什么问题
4.1 Cocoa 界面零可移植性
TAMS 是典型的单平台原生长相:多窗口、工具栏、NSTableView、NSTextView。鸿蒙上这些概念一个都没有,只能按工作流重建。
4.2 项目文件格式要兼容
.tams 项目文件里存着资料、编码、代码本、注释。如果格式不兼容,用户的历史数据就全废了。
所以有一个专门的文件:TamsCompatibility.ets(228 行),负责读写 TAMS 的文件结构。这是本期最有价值的一个模块——它决定了"老用户能不能带着数据过来"。
4.3 质性研究的资料是"长文本 + 时间轴"
访谈转写动辄几万字,还要标时间码、说话人。这跟代码编辑器、笔记应用都不一样:需要能按片段(segment)寻址,而不是按行。
4.4 编码是"多对多"关系
同一段文字可以被多个代码标记;同一个代码可以覆盖很多片段。这种多对多关系如果用简单存储会很难查,所以 InsightAnalysis 里有专门的检索逻辑。
五、鸿蒙适配核心路径
5.1 第一步:按工作流组织导航
导航结构不是按功能名堆的,而是按研究流程排的:
工作台 ← 总览:资料数、已标注片段、整体进度
代码集 ← 代码本管理
文档 ← 资料阅读与编码
分析 ← 统计与检索
设置

工作台顶部三张卡片直接对应研究者最关心的三个数字:
| 卡片 | 副标题 | 含义 |
|---|---|---|
| 研究资料 | 资料总数 | 导入了多少份材料 |
| 已标注片段 | N 个代码集 | 编码进度 |
| 整体进度 | 已编码比例 | 完成度百分比 |
这个「0 / 0 / 0%」的三卡片设计,比堆一堆按钮更贴合研究者的日常——他们开工前最想知道的就是"还剩多少没编"。
5.2 第二步:项目是一等公民
没有项目就不能有资料。所以空态是强制引导:
还没有研究项目
先创建一个项目,再导入资料和建立代码集
而不是给一个可以直接导入文档的按钮。这个顺序约束是对的——质性研究必须先把研究边界划清楚。
5.3 第三步:新建项目只要两个字段

对话框极简:
- 项目名(占位符:
例如:社区参与研究) - 补充说明(占位符:
补充研究对象、时间或方法)
第二个字段的设计很懂行:质性研究里,"什么时候、对谁、用什么方法"是必须记录的元信息,把它做成创建时的一等字段,比藏在设置里好。
5.4 第四步:创建后立即切换工作态

创建成功后,工作台从空态变成「当前项目」卡片:
当前项目 · 进行中
HarmonyOS_PC_UX_study
0 份资料 0 已编码片段
[打开资料 →]
下方「最近项目」列出历史:
HarmonyOS_PC_UX_study
刚刚创建的研究项目 · 0 份资料
状态变化是即时的、结构是一致的——不是弹个 toast 然后界面不变。这说明状态管理做对了。
5.5 第五步:把兼容性单独成层
TamsCompatibility.ets(228 行)和 InsightStore.ets(194 行)分开:
TamsCompatibility负责外部格式(TAMS 原生文件)InsightStore负责内部存储(应用自己的结构)
这个分层很关键:格式兼容是"可能变化、可能废弃"的外围代码,不该和核心存储搅在一起。
六、问题困难解决
6.1 困难一:长文本的阅读与定位
访谈转写是几万字的连续文本。ArkUI 的 Text 组件直接渲染长文本会有性能问题,而且无法做"按片段寻址"。
处理方式是分段渲染:把文档切成 segment,每段可独立高亮、独立标注。MediaDocumentService(99 行)负责导入和分段。
6.2 困难二:编码操作的交互成本
质性研究里,编码是高频重复动作:选中一段 → 选代码 → 确认。如果每步都要开弹窗,用户一天下来会崩溃。
鸿蒙版的取舍是:把代码集放在侧栏,选中文本后点代码即完成标注。这个交互在鼠标键盘形态(2in1)下是可行的。
6.3 困难三:没有权限却要读文件
module.json5 里没有申请任何权限,只声明了 deviceTypes: ["phone", "tablet", "2in1"]。
这意味着所有文件访问都走系统文件选择器(用户主动授权),而不是 READ_MEDIA / READ_DOCUMENTS 这类全局权限。
对研究工具来说这是合适的选择:用户选了哪个文件,应用才能读哪个文件,不会有"这个应用能翻我整个文档库"的顾虑。
6.4 困难四:进度指标怎么算
「整体进度:已编码比例」听起来简单,实际要定义清楚:
- 分母是"资料总数"还是"片段总数"?
- 一份资料编了 1 段算不算完成?
从界面看,它用的是片段维度(副标题写的是"已编码比例"),这和质性研究的实际工作方式一致——研究者关心的是"还有多少内容没被标注",而不是"还有几份文件没打开"。
七、构建与运行方式
7.1 环境
- DevEco Studio(内置 hvigor + SDK)
- HarmonyOS SDK API 26(本机 26.0.0.105)
- 无需任何 native 工具链
7.2 构建
cd HarmonyOS
ohpm install
hvigorw assembleHap --mode module -p product=default -p buildMode=debug
产物:
entry-default-unsigned.hap 517 KB
entry-default-signed.hap 551 KB
517 KB 是同类应用里最小的包体——纯 ArkTS、零 native、零第三方依赖。
7.3 签名与安装
sh scripts/sign_hap.sh
hdc shell aa start -b com.xujian.insight -a EntryAbility
调试 profile 绑 UDID,换设备需重新自动签名。
八、适配成果
8.1 工作台
见 5.1 / 图 1。三张指标卡 + 空态引导 + 新建项目入口。
8.2 新增研究项目
见 5.3 / 图 2。两个字段、两个按钮,没有多余选项。
8.3 项目创建后的工作态
见 5.4 / 图 3。「当前项目」卡片 + 「最近项目」列表,状态即时切换。
8.4 工程量
| 指标 | 数值 |
|---|---|
| ArkTS 源文件 | 7 个 |
| 代码行数 | 3394 行 |
| 主界面 | Index.ets 2575 行(76%) |
| 格式兼容层 | TamsCompatibility.ets 228 行 |
| 权限 | 0 个(纯文件选择器授权) |
| HAP 体积 | 517 KB |
8.5 同类移植项目横向对比
| ClipNest | 澜析工程 | 沙箱控制台 | 晶析云 | 源库服务 | 云桥文件 | OHCalculiX | 码见 | |
|---|---|---|---|---|---|---|---|---|
| 类型 | 本地工具 | 本地计算 | 云客户端 | 混合 | 服务端 | 网络 I/O | 本地计算 | 本地工具 |
| ArkTS 行数 | 4782 | 3417 | 5862 | 3476 | 2297 | 5576 | 833 | 3394 |
| HAP | 752 KB | 19 MB | 892 KB | 444 KB | 2.1 MB | 5.1 MB | 16 MB | 517 KB |
| 权限数 | 2 | 0 | 1 | 1 | 2 | 3 | 0 | 0 |
九、功能验证结果
9.1 已在真机验证
| 功能 | 结果 | 验证方式 |
|---|---|---|
| 构建与安装 | ✅ | 517 KB HAP,hdc install 成功 |
| 应用启动 | ✅ | 进程稳定运行,窗口正常渲染 |
| 五区导航 | ✅ | 工作台/代码集/文档/分析/设置 渲染正确 |
| 工作台指标卡 | ✅ | 三张卡片数值与副标题正确(0 / 0 / 0%) |
| 空态引导 | ✅ | 「还没有研究项目」+ 引导文案正确 |
| 新建项目对话框 | ✅ | 两个输入框、占位符、取消/创建按钮 |
| 文本输入 | ✅ | 项目名成功输入并回显 |
| 项目创建 | ✅ | 真实创建 HarmonyOS_PC_UX_study |
| 状态切换 | ✅ | 空态 → 「当前项目 · 进行中」卡片 |
| 最近项目列表 | ✅ | 新项目出现在「最近项目」,显示「刚刚创建」 |
| 权限申请 | ✅ | 启动无权限弹窗(零权限声明) |
9.2 未验证
| 功能 | 说明 |
|---|---|
| 文档导入 | 设备上没有访谈转写样本文件 |
| 文本分段与标注 | 依赖已导入文档 |
| 代码集管理 | 需要先有编码 |
| 分析统计 | 需要已编码数据 |
.tams 项目导入 | 需要一份真实的历史项目文件 |
| 导出 | 未验证输出格式 |
9.3 已知限制
| 限制 | 说明 |
|---|---|
| 需要自备研究资料 | 无内置示例数据 |
| 编码交互未做深度验证 | 需要长文档才能体现 |
| 调试 profile 绑 UDID | 换设备需重新自动签名 |
十、上架复盘:审核不通过怎么办
移植跑通只是第一关。上架审核看的是另一套东西:用户会不会把这款应用误认为上游官方版,或者误认为换皮抄袭。名称、图标、截图、描述、权限、实际行为,只要有一项对不上,就可能被驳回。
10.1 名称和图标:开源许可不等于品牌许可
这是最容易踩的坑。很多人觉得“这是开源软件,保留原名和原图标很正常”,但 MIT/Apache/GPL 给的是版权许可,不是商标许可。审核看到“应用名和上游一样、图标是上游 Logo 换色、截图里还有上游品牌”,就会按“冒用/抄袭”处理。典型的三连击是:应用名直接沿用上游、图标只把颜色换一下、截图里还带着上游 Logo——即使代码全部重写,也会被判定为冒用。
我们的处理原则:
- 应用名改成独立品牌,包名不带上游商标;
- 图标重画,不复用、不改色、不截取上游 Logo;
- 截图、启动图、关于页不出现上游 Logo,只保留文字致谢;
- 关于页写明“基于 TAMS Analyzer 移植,非官方发行”,并保留上游 LICENSE/NOTICE;
- 如果被质疑,提交《品牌与素材来源说明》:改名前后对照、图标设计稿、上游许可证、代码差异、真机录屏。
10.2 被判定“抄袭/雷同”时,交什么证据
只回“这是开源软件”通常没用。按这个顺序给材料:
- 上游仓库地址和 LICENSE 原文;
- 本仓库与上游的差异清单(UI 重写、平台层、构建脚本);
- 品牌变更记录(旧名→新名、旧图标→新图标);
- 功能差异说明(哪些是鸿蒙特有、哪些上游没有);
- 真机录屏,证明不是套壳。
如果确实沿用了上游 UI,先改再申诉;审核一般不看“开源所以可以一样”的解释。
10.3 这个项目的高频驳回点
- 零权限但读文件:审核会问文件怎么来的。说明只通过系统 DocumentViewPicker,由用户主动选择,不申请存储权限。
- 敏感文本:质性研究可能含个人信息;隐私政策写清“本地处理、不上传”,并提供一键清空。
- 品牌:码见是独立品牌,关于页写“基于 TAMS Analyzer,非官方”。
10.4 驳回后的处理顺序
先分类,再动手。审核意见通常落在六类:名称/图标/品牌、隐私与权限、功能与描述不符、技术(签名/包名/架构/体积/崩溃)、内容合规、资质(软著/授权书/备案)。
- 一次只改一类,别在同一个版本里混改;
- 回复时逐条对应:版本号 + 审核意见 + 改了什么 + 怎么验证;
- 测试账号/令牌在复审前重置,写进审核备注;
- 截图必须来自当前版本真机,不能用设计稿;
- 换正式证书后重新打包,不要用调试签名送审;
- 被拒后先回一条“已收到,逐条说明”,再提新包,避免被判定骚扰;
- 上架材料提前备齐:软著/授权书、隐私政策公网 URL、测试账号、真机截图、开源许可证与 NOTICE。
回复可以按这个模板:
您好,针对第 X 条“……”:我们已在版本 A.B.C 中修改:1)……;2)……。验证路径:……。相关材料见附件/链接。
一句话:上架不是“把包传上去”,而是把“这不是官方版、也不是换皮”这件事,用名称、图标、截图、代码和材料同时证明一遍。
十一、结语
这个项目体量最小,但也最能说明一件事:不是所有移植都需要和 C++、Fortran、原生库搏斗。
四点体会:
-
工作流比功能清单重要。质性研究的流程是「建项目 → 导资料 → 编码 → 分析」,所以导航就是按这个顺序排的。如果按"项目管理 / 文件管理 / 编辑工具"这种通用软件分类来排,研究者会找不到北。
-
格式兼容层要独立。
TamsCompatibility.ets这 228 行是给老用户留的迁移通道。把它和内部存储分开,将来 TAMS 格式变了或者要支持别的格式,改一个文件就够了。 -
零权限是一种产品承诺。整个应用没有申请任何系统权限,所有文件访问都通过系统选择器。对一个会加载大量个人访谈资料的研究工具来说,这比多给几个功能更能打动人。
-
517 KB 也能装下一个研究工具。纯 ArkTS、零依赖,这是鸿蒙原生开发在工具类应用上的天然优势——不需要 Electron,也不需要 Python 运行时。
从"还没有研究项目"到"当前项目 · 进行中",这一屏的变化看似简单,但它证明了一件事:这条工作流在鸿蒙 PC 上是完整可用的。接下来要验证的是导入一份真实的访谈转写、标注几十个片段——那才是这类工具的日常。
一句话:一个研究工具的成败,不在功能多少,而在它是否顺着研究者的工作流走。
相关链接
- 适配仓库:https://atomgit.com/OpenHarmonyPCDeveloper/ohos_TAMS-Analyzer
- 上游项目 TAMS Analyzer:https://tamsys.sourceforge.io/osxtams/download.html
- OpenHarmony PC 开发者社区:https://atomgit.com/OpenHarmonyPCDeveloper
更多推荐



所有评论(0)