引言：一位鸿蒙开发者的“第二大脑”探索手记

最近，我在鸿蒙应用市场上架了一款叫做《轻规划》的应用。最开始，它的设计初衷非常纯粹——帮用户做好 4D 任务规划、目标拆解、习惯打卡与清单履约，让日常的每一项待办都能清晰落地。然而在使用和用户反馈中，我们渐渐发现：有了清晰的行事规划和待办清单，固然能让人不漏掉每一件小事，但总觉得还缺少了点什么。——没错，缺少了知识管理！

单纯做“规划”，容易让应用沦为没有思想深度的清单列表（Checklist）；而真正的效率跃迁，必须依靠知识的沉淀与复盘。在知识管理（PKM）领域，Obsidian 无疑是全球无数极客与知识工作者心中的“神级工具”。它采用纯文本 Markdown 语法，强调本地优先（Local-First）与私密存储，并通过强大的双向链接帮助用户构建交织互联的网状知识体系。遗憾的是，Obsidian 作为一款国外软件，至今未能原生适配 HarmonyOS。在鸿蒙生态中，知识工作者们急需一款既具备 Obsidian 极客灵魂、又能深度拥抱鸿蒙原生特性的替代品。

出于对“行事规划 + 知识管理 = 打造个人第二大脑”理念的执念，以及对鸿蒙原生生态建设的热情，我们做出了一个决定：在《轻规划》中，打造一个真正的鸿蒙原生版 Obsidian 平替！ 我们不仅 100% 兼容了 Obsidian 的 Markdown 沙箱仓、YAML 属性、Wiki 双链图谱以及Obsidian海量的插件，更希望借助鸿蒙系统级的强大能力，带来超越传统桌面软件的新体验。

但这么多年知识管理中，一直有十分棘手的痛点：我们在记录笔记时，存在收纳箱的白板草图、课堂板书、会议记录或文献截图，受限于拍照光线、焦距或剪贴板二次压缩，这些图片往往字迹模糊、细节难辨。如果按照传统做法上传云端 AI 处理，既违背了 Obsidian 本地私密的核心信仰，又受制于网络延迟与成本问题。

幸运的是，全新 HarmonyOS 7.0 带来的 CoreVision 端侧 AI 图像超分（Image Super Resolution） 特性，为我们带来了转机！所以决定在轻规划应用的脑图仓库中图片预览和markdown预览中增加超分图片功能。

超分前后对比图：

---

图像超分带来的三大体验突破

在轻规划集成 HarmonyOS 7.0 图像超分特性后，鸿蒙原生版 Obsidian 完成了三大维度的用户体验颠覆：

1. 模糊字迹与白板“毫秒级清晰重绘”：用户插入的模糊会议白板、手写草图、小字截图，一键触发端侧 2X/4X 像素重绘，模糊字迹瞬间变为锐利高清；
2. 100% 隐私零出设备（Local-First）：贯彻 Obsidian 本地优先理念，无需将私密笔记图片上传云端，端侧 NPU 硬件直连，无网状态下依然秒级响应；
3. 极客胶囊手势无缝融合：将 AI 超分无缝集成于全屏大图预览与 Markdown 图片卡片中，配合 ButtonType.Capsule 胶囊控制与双指捏合缩放，实现零打断的流畅知识沉浸体验。

---

一、 鸿蒙版 Obsidian 的超分架构设计

在 轻规划 中，所有笔记与附件均存储于应用的本地沙箱 Vault 目录中。为了在不破坏 Markdown 干净文件结构的前提下实现毫秒级超分重绘，我们将端侧 AI 架构设计如下：

图像超分带来的三大体验突破对比

维度	传统云端图像 API 方案	HarmonyOS 7.0 端侧 AI 超分 (CoreVision)	体验突破总结
隐私安全性	需将沙箱私密图片上传云端，违背 Obsidian 本地优先原则	100% 本地沙箱数据安全，图片无需离开设备	隐私零风险：敏感白板与商业机密安全保密
网络与时延	依赖高带宽，离线或弱网下无法查看高清板书	零网络依赖，离线状态下毫秒级响应	全场景可用：地铁、飞机上离线秒级变清晰
画质与渲染	需下载并保存临时文件，交互撕裂	PixelMap 原生对接，结合 ArkUI 渲染无缝呈现	极致画质重绘：模糊小字放大后边缘依然清晰

---

二、 实战：端侧 NPU 图像超分引擎封装

在 轻规划 中，ImageSuperResolutionUtil 作为端侧 AI 超分的核心单例工具，负责完成分析器初始化、硬件兼容性校验、PixelMap 重建与资源释放。

1. 超分引擎核心实现 (ImageSuperResolutionUtil.ets)

import { image } from '@kit.ImageKit';
import { promptAction } from '@kit.ArkUI';
// 导入 HarmonyOS 7.0 CoreVision 图像超分 API
import imageSuperResolution from '@ohos.multimedia.imageSuperResolution';

export interface SRProcessResult {
  pixelMap: image.PixelMap | null;
  beforeWidth: number;
  beforeHeight: number;
  afterWidth: number;
  afterHeight: number;
  durationMs: number;
  supported: boolean;
  message: string;
}

export class ImageSuperResolutionUtil {
  private static instance: ImageSuperResolutionUtil | null = null;
  private analyzer: imageSuperResolution.ImageSRAnalyzer | null = null;
  private isInitializing: boolean = false;

  public static getInstance(): ImageSuperResolutionUtil {
    if (!ImageSuperResolutionUtil.instance) {
      ImageSuperResolutionUtil.instance = new ImageSuperResolutionUtil();
    }
    return ImageSuperResolutionUtil.instance;
  }

  /**
   * 初始化 HarmonyOS 7.0 端侧 AI 超分分析器
   */
  public async init(): Promise<boolean> {
    if (this.analyzer) return true;
    if (this.isInitializing) return false;

    this.isInitializing = true;
    try {
      // 创建端侧图像超分分析器实例
      this.analyzer = await imageSuperResolution.createImageSRAnalyzer();
      this.isInitializing = false;
      return true;
    } catch (err) {
      this.isInitializing = false;
      console.error(`[轻规划 AI] 超分分析器初始化失败: ${JSON.stringify(err)}`);
      return false;
    }
  }

  /**
   * 执行端侧图像超分像素重建
   */
  public async processSuperResolutionDetail(inputPixelMap: image.PixelMap): Promise<SRProcessResult> {
    const startTime = Date.now();
    const result: SRProcessResult = {
      pixelMap: null,
      beforeWidth: 0,
      beforeHeight: 0,
      afterWidth: 0,
      afterHeight: 0,
      durationMs: 0,
      supported: true,
      message: ''
    };

    if (!inputPixelMap) {
      result.message = '无效的输入 PixelMap';
      return result;
    }

    const imageInfo = await inputPixelMap.getImageInfo();
    result.beforeWidth = imageInfo.size.width;
    result.beforeHeight = imageInfo.size.height;

    if (!this.analyzer) {
      const initialized = await this.init();
      if (!initialized || !this.analyzer) {
        result.supported = false;
        result.message = '当前设备 NPU 超分引擎初始化失败';
        return result;
      }
    }

    try {
      // 配置 2X 超分与高质量纹理重建
      const config: imageSuperResolution.SRConfig = {
        scale: imageSuperResolution.ScaleType.SCALE_2X,
        quality: imageSuperResolution.QualityLevel.HIGH
      };

      // 调用端侧 NPU 硬件执行算法重绘
      const outputPixelMap = await this.analyzer.process(inputPixelMap, config);
      const outputInfo = await outputPixelMap.getImageInfo();

      result.pixelMap = outputPixelMap;
      result.afterWidth = outputInfo.size.width;
      result.afterHeight = outputInfo.size.height;
      result.durationMs = Date.now() - startTime;
      result.message = 'AI 超清重建完成';
      return result;
    } catch (error) {
      console.error(`[轻规划 AI] NPU 超分执行异常: ${JSON.stringify(error)}`);
      result.message = `超分处理异常: ${error.message || '系统限制'}`;
      return result;
    }
  }

  /**
   * 销毁并释放 NPU 硬件资源
   */
  public async destroy() {
    if (this.analyzer) {
      try {
        await this.analyzer.destroy();
      } catch (e) {
        console.warn(`[轻规划 AI] 释放超分资源异常: ${JSON.stringify(e)}`);
      }
      this.analyzer = null;
    }
  }
}

---

三、 图像超分交互落地与胶囊 UI 设计

在 轻规划 中，用户在全屏预览沙箱附件或 Markdown 内嵌图片时，只需点击底部胶囊工具栏中的 ✨ AI 超清 按钮，即可无缝触发超分重绘：

// ImageDetailView.ets 底部胶囊工具栏
Row({ space: 10 }) {
  Button('- 缩小')
    .type(ButtonType.Capsule)
    .fontSize(11)
    .fontColor('#E5E7EB')
    .backgroundColor('rgba(255, 255, 255, 0.16)')
    .height(32)
    .onClick(() => { if (this.scaleValue > 0.6) this.scaleValue -= 0.3; })

  Text(`${Math.round(this.scaleValue * this.pinchValue * 100)}%`)
    .fontSize(12)
    .fontWeight(FontWeight.Bold)
    .fontColor('#FACC15')

  Button('+ 放大')
    .type(ButtonType.Capsule)
    .fontSize(11)
    .fontColor('#E5E7EB')
    .backgroundColor('rgba(255, 255, 255, 0.16)')
    .height(32)
    .onClick(() => { if (this.scaleValue < 4.5) this.scaleValue += 0.3; })

  Button('重置 100%')
    .type(ButtonType.Capsule)
    .fontSize(11)
    .fontColor('#A855F7')
    .backgroundColor('rgba(168, 85, 247, 0.2)')
    .height(32)
    .onClick(() => this.resetZoom())

  // ✨ AI 超清 胶囊按钮 (ButtonType.Capsule 保证绝对圆角)
  Button() {
    Row({ space: 4 }) {
      Text('✨').fontSize(11)
      Text(this.isSRProcessing ? 'AI 超清中...' : 'AI 超清')
        .fontSize(11)
        .fontWeight(FontWeight.Bold)
        .fontColor('#FACC15')
    }
  }
  .type(ButtonType.Capsule)
  .height(32)
  .padding({ left: 10, right: 10 })
  .backgroundColor('rgba(250, 204, 21, 0.16)')
  .border({ width: 1, color: 'rgba(250, 204, 21, 0.35)' })
  .onClick(() => this.triggerSuperResolution())
}

---

四、 图像超分实战踩坑与解决方案

在 鸿蒙原生版 Obsidian（轻规划）中落地图像超分的过程中，我们遇到了三个核心坑点，以下是踩坑分析与解决方案：

坑点 1：沙箱相对路径与 file:// 协议解析引发的超分加载失败

坑点描述：
Obsidian 规范中，Markdown 附件图片通常以相对文件名存储（例如 attachments/architecture.png 或 architecture.png）。直接将相对路径字符串传给 ImageSRAnalyzer 或 ImageSource 时，系统无法识别路径，导致超分引擎返回“无效图片路径”或直接 crash。

解决方案：
必须构建绝对沙箱 URI 解析逻辑。首先通过 VaultManager.getInstance().getAttachmentsDir() 获取应用沙箱绝对路径 /data/storage/el2/base/haps/entry/files/Vault/attachments；若传入的路径不包含 file:// 前缀或非绝对路径，自动补全协议头：

let fullPath = attName;
if (!attName.startsWith('file://') && !attName.startsWith('/')) {
  fullPath = `file://${VaultManager.getInstance().getAttachmentsDir()}/${attName}`;
}

补全为标准的 file:///data/storage/... 格式后，再通过 fileIo.openSync 提取文件句柄或加载为 PixelMap，超分引擎便能 100% 成功读取沙箱文件。

坑点 2：超分返回结果 SRProcessResult 类型兼容性避坑

坑点描述：
在不同版本的 HarmonyOS SDK 升级过程中，SRProcessResult 接口定义的返回字段有所调整。直接在 ArkTS 代码中访问 result.success 触发了编译报错：Property 'success' does not exist on type 'SRProcessResult'。

解决方案：
在 ArkTS 强类型约束下，不能依赖未在 interface 中定义的 success 属性。应当将逻辑修正为对 result.pixelMap 是否非空进行判断：

const result = await ImageSuperResolutionUtil.getInstance().processImageUriDetail(this.imageUrl);

// ✅ 正确判定方式：校验生成的 PixelMap 是否非空
if (result.pixelMap) {
  this.srPixelMap = result.pixelMap;
  promptAction.showToast({ message: '✨ AI 超清完成！图片细节与清晰度已大幅提升' });
} else {
  promptAction.showToast({ message: result.message || '超清处理未完成' });
}

坑点 3：ArkUI 默认主题下按钮呈现“矩形直角”的外观坑

坑点描述：
开发初期，我们使用了 .type(ButtonType.Normal) 并设置了 .borderRadius(14)，但在某些设备主题下，系统依然将按钮渲染为带有直角的矩形框，影响胶囊美感。

解决方案：
在 ArkUI 框架中，将 Button 的 type 显式设置为 ButtonType.Capsule（用于扁平胶囊按钮）或 ButtonType.Circle（用于圆形图标按钮）。ButtonType.Capsule 会切断系统默认主题的矩形阴影，强制将两端切为完美的半圆弧度，呈现出最纯粹的极客胶囊效果。

---

五、 总结与展望

作为一款 鸿蒙原生版 Obsidian 平替，轻规划 借力 HarmonyOS 7.0 端侧 AI 图像超分 特性，真正做到了“行事规划 + 知识管理 = 第二大脑”与“本地优先（Local-First）+ 端侧智能（On-Device AI）”的双重融合。

在零云端依赖、零隐私泄露的前提下，轻规划 让用户的每一张白板截图、手写板书都能在指尖实现超清重绘与精准辨识。未来，我们将继续在鸿蒙生态中探索端侧 AI 与知识管理系统的深度结合，为用户打造更加智能、纯粹的第二大脑！