前言

欢迎加入鸿蒙PC开发者社区，共同打造开发者工具生态：鸿蒙PC开发者社区 ：https://harmonypc.csdn.net/

项目开源地址：https://AtomGit.com/lqjmac/ele-zhishiku

我做 知识库 时最先确认的，不是颜色和布局，而是它到底帮谁省了哪一步。
经验不是没有产生，而是没有被稳定沉淀。知识库要让经验能被重新找到、理解和复用。
它面向的是需要长期整理项目复盘、产品观察、调研结论和工作方法的人。

知识库这一篇我会按“经验怎么被再次找到”来写。
它不是把内容都堆进本地存储，而是让项目经验、调研结论和方法论有稳定的回看入口。

一、先确认知识库沉淀什么

1.1 知识库真正要解决什么

经验不是没有产生，而是没有被稳定沉淀。知识库要让经验能被重新找到、理解和复用。
很多经验当时很清楚，过两周就散在聊天、文档和脑子里。
知识库要解决的是二次检索和二次理解。

第一版我只抓住本地知识条目的基本闭环：

1. 条目要有主题和关键词
2. 高亮和正文要能说明结论
3. 关联和复习时间帮助知识重新浮上来

1.2 为什么不做成大而全

知识库特别容易一步跨到全文搜索、双链、图谱、云同步。
这次先不急，我更想先把一条知识记录写扎实。

能力	第一版处理	原因
主题和关键词	保留	检索入口要稳定
高亮摘要	保留	回看时先看结论
关联条目	保留简单文本	先建立上下文，不做复杂图谱
云同步	暂不做	第一版先保证本地可靠

这个取舍让它更像个人知识台，而不是一上来就追求完整知识管理系统。

二、文件分工对应知识条目

2.1 主要文件职责

文件	职责	这篇关注点
Home.vue	组织知识台	分类、目录、编辑和关联信息在这里汇合
NoteSidebar.vue	管知识目录	用主题和关键词帮助回找
NoteEditor.vue	编辑知识条目	高亮、正文、关联和复习时间都在这里维护
NoteToolbar.vue	放流转动作	新建、复制、导出、删除
useNotes.ts	管知识数据	本地保存、筛选和当前条目
useNativeBridge.ts	衔接剪贴板	把条目导出到外部文档

知识库的组件边界要围绕“找得到、读得懂、带得走”。
仅仅说页面编排，会显得太像模板。

三、整体结构围绕搜索和回看

3.1 页面结构图

知识库结构图展示知识分类、目录、编辑台和关联信息侧栏。

3.2 布局为什么这样分

知识库采用的是 知识分类 + 知识目录 + 关键词、高亮和关联侧栏。
它的浏览顺序是先找到主题，再进入正文，最后看关联和复习提醒。

区域	承担的任务	设计注意点
知识分类	粗粒度定位	类目不要过细
知识目录	找到具体条目	主题和关键词要能快速扫读
编辑台	沉淀正文和高亮	长内容要耐读
关联侧栏	放相关条目和复习时间	帮助知识重新连接

知识库不是一次性工具，布局要耐看、可回访。

四、字段设计要包含来源和可信度

4.1 知识库的核心字段

知识条目如果没有来源、关键词和复习点，很快会变成一堆孤立文本。
字段要帮助它再次被找到。

字段	含义	页面位置
id	知识条目标识	状态层
topic	条目主题	列表/编辑区
keywords	检索关键词	筛选/编辑区
highlights	关键结论	列表/编辑区
content	完整内容	编辑区
related	相关条目或上下文	侧栏/导出
reviewAt	建议回看时间	侧栏

4.2 TypeScript 类型

export interface AppItem {
  id: string;
  topic: string;
  keywords: string;
  highlights: number | string;
  content: string;
  related: string;
  reviewAt: number | string;
}

export type AppFilter = 'all' | 'active' | 'archived';

这套类型没有做复杂知识图谱。
先把主题、关键词、高亮、正文这四件事做稳，已经能支撑第一版回看。

五、默认条目要像真实经验

5.1 为什么要写种子数据

默认条目要像真实经验。
否则用户看不出高亮、关联和复习时间为什么存在。

我给种子知识定了三个标准：

• 主题来自真实问题
• 高亮能直接复用
• related 能提示下一条关联内容

5.2 示例数据

export const seedAppItems: AppItem[] = [
  {
    id: 'zhishi_ku-001',
    topic: 'OpenHarmony Electron 白屏排查',
    keywords: 'HAP, libelectron.so, Exec format error',
    highlights: '本地知识沉淀',
    content: '白屏不一定是前端资源问题，日志出现 Exec format error 时要优先检查 HAP 内 native so 是否为正确 ELF。',
    related: 'HAP 打包校验清单',
    reviewAt: '2026-06-01',
  },
];

真实知识条目能测试关键词换行、高亮展示和关联侧栏是否清楚。

六、状态层处理保存和更新

6.1 composable 的职责

useNotes.ts 这层我更愿意把它理解成“当前工具的数据服务”。
页面不应该直接处理太多 localStorage、排序和导出拼接。

const STORAGE_KEY = 'zhishi-ku';

const items = ref<AppItem[]>(loadItems());
const activeId = ref(items.value[0]?.id ?? '');

function persist() {
  localStorage.setItem(STORAGE_KEY, JSON.stringify(items.value));
}

function loadItems() {
  const raw = localStorage.getItem(STORAGE_KEY);
  return raw ? JSON.parse(raw) : seedAppItems;
}

6.2 本地存储 key 一定要独立

这里的 key 我会明确写成 zhishi-ku。
这样做可以避免不同工具之间互相读到旧数据。

本地数据一旦串了，页面看起来像小问题，实际会让调试和截图都变得很难判断。

七、筛选排序服务再次找到

7.1 computed 更适合承接派生视图

筛选、搜索、排序这些逻辑如果直接写在模板里，很快会让页面变得难读。
我更倾向于让状态层先准备好可展示列表。

const keyword = ref('');
const filter = ref<'all' | 'topic'>('all');

const visibleItems = computed(() => {
  const text = keyword.value.trim().toLowerCase();
  return items.value
    .filter(item => JSON.stringify(item).toLowerCase().includes(text))
    .sort((a, b) => String(b.id).localeCompare(String(a.id)));
});

7.2 排序服务于场景

本地知识库应用里，排序不是“哪个字段容易写就按哪个排”。
它应该服务用户打开应用时最想看到的那批内容。

1. 未处理内容优先出现
2. 置顶或高优先级内容靠前
3. 最近更新内容不要沉底

八、Vue 页面组织知识台

8.1 Home.vue 只做编排

我不希望 Home.vue 变成所有逻辑的大杂烩。
它更适合负责页面骨架和组件之间的数据传递。

<template>
  <main class="zhishi_ku-page">
    <NoteToolbar
      @create="createItem"
      @copy="copyCurrent"
      @export="exportCurrent"
    />
    <section class="workspace">
      <NoteSidebar :items="visibleItems" @select="selectItem" />
      <NoteEditor :item="currentItem" @update="updateItem" />
    </section>
  </main>
</template>

8.2 组件之间的边界

组件	应该知道什么	不应该知道什么
NoteToolbar	当前能触发哪些动作	具体字段如何存储
NoteSidebar	列表、筛选、选中项	导出 Markdown 细节
NoteEditor	当前对象字段	全局搜索逻辑

边界清楚以后，后续改样式和改字段都会轻很多。

九、编辑器要承接长内容沉淀

9.1 不要只留下标题和正文

知识库如果只保留标题和正文，就会退回普通记事本。
所以编辑器必须把核心字段摆出来。

<script setup lang="ts">
defineProps<{ item: AppItem | null }>();
const emit = defineEmits<{ update: [item: AppItem] }>();
</script>

<template>
  <form v-if="item" class="editor-form">
    <input v-model="item.topic" />
    <textarea v-model="item.content" />
  </form>
</template>

9.2 表单不是越多越好

我会优先放能影响用户判断的字段。
辅助字段可以放到右侧信息区，或者只在导出时使用。

十、工具栏围绕复制和导出

10.1 工具栏放哪些按钮

工具栏最容易变成按钮仓库。
知识库里我只保留和主流程强相关的动作。

• 新增知识
• 标记关键词
• 提炼高亮
• 关联条目
• 复制摘要
• 导出知识

10.2 复制摘要

function buildAppSummary(item: AppItem) {
  return [
    '# 知识库摘要',
    '- topic: ' + item.topic,
    '- keywords: ' + item.keywords,
    '- highlights: ' + item.highlights,
    '- content: ' + item.content,
  ].join('\n');
}

复制摘要的好处是很实际的。
用户不一定每次都要导出文件，有时只是想把当前内容发到聊天窗口或文档里。

十一、桥接层收住桌面能力

11.1 桥接层只暴露稳定动作

页面不应该知道底层是 Electron clipboard，还是 OpenHarmony 侧的能力。
它只需要知道“复制”“导出”“通知”这些动作。

export function useNativeBridge() {
  const api = window.ohosBridge ?? window.electronAPI;

  async function copyText(text: string) {
    if (api?.copyText) return api.copyText(text);
    return navigator.clipboard.writeText(text);
  }

  async function notify(message: string) {
    if (api?.notify) return api.notify(message);
  }

  return { copyText, notify };
}

11.2 为什么要有浏览器兜底

开发阶段经常会直接跑 Vite。
如果没有浏览器兜底，页面调试会被原生环境绑得太死。

十二、导出 Markdown 要保留来源脉络

12.1 导出内容要能独立阅读

导出的 Markdown 不能只是把字段拼起来。
它最好离开应用以后也能被看懂。

function exportAppMarkdown(item: AppItem) {
  return [
    '# 知识库',
    '',
    '> 由 知识库 导出。',
    '## topic', String(item.topic ?? ''),
    '## keywords', String(item.keywords ?? ''),
    '## highlights', String(item.highlights ?? ''),
    '## content', String(item.content ?? ''),
    '## related', String(item.related ?? ''),
    '## reviewAt', String(item.reviewAt ?? ''),
  ].join('\n');
}

12.2 导出动作和通知联动

async function exportCurrent() {
  if (!currentItem.value) return;
  const markdown = exportAppMarkdown(currentItem.value);
  await bridge.copyText(markdown);
  await bridge.notify('知识库内容已复制为 Markdown');
}

这样用户完成导出以后能马上得到反馈。

十三、主进程加载保证本地可用

13.1 开发环境和生产环境分开

桌面应用最常见的白屏问题之一，是生产环境还在访问开发服务器。
所以主进程里一定要把加载逻辑分清楚。

const path = require('path');

function resolveRendererUrl() {
  if (process.env.VITE_DEV_SERVER_URL) {
    return process.env.VITE_DEV_SERVER_URL;
  }
  return `file://${path.join(__dirname, '../dist/index.html')}`;
}

mainWindow.loadURL(resolveRendererUrl());

13.2 preload 只注入必要接口

const { contextBridge, ipcRenderer } = require('electron');

contextBridge.exposeInMainWorld('electronAPI', {
  copyText: text => ipcRenderer.invoke('copy-text', text),
  notify: message => ipcRenderer.invoke('notify', message),
});

接口少一点，维护起来更安心。

十四、知识库样式要耐读

14.1 视觉气质服务使用场景

知识库的视觉方向是：沉稳、绿色、长期复用感。
这个判断会影响间距、字号、卡片密度和按钮重量。

.zhishi_ku-page {
  min-height: 100vh;
  display: flex;
  flex-direction: column;
  background: #f7f8fb;
  color: #1f2937;
}

.workspace {
  display: grid;
  grid-template-columns: 280px minmax(0, 1fr);
  gap: 16px;
  min-height: 0;
}

14.2 滚动区要提前处理

桌面应用窗口经常被用户缩小。
如果滚动区没有处理好，内容一多就会挤成一团。

• 左侧列表要能独立滚动
• 编辑区不能把工具栏挤出屏幕
• 右侧信息区要允许内容截断和换行

十五、构建后检查知识主题

15.1 先确认前端产物能生成

写文章之前，我会先跑一次构建。
这一步很朴素，但能挡住不少低级问题。

cd ../../electron_for_harmony/electron-openharmony-vue3-20/ohos_hap/web_engine/src/main/resources/resfile/resources/app/vue-app
npm install
npm run build

15.2 再确认关键文件没有串主题

rg "zhishi-ku|/knowledge-base|知识库" src package.json
rg "TODO|旧标题|测试数据" src

构建通过不代表体验完美，但至少说明当前页面和依赖关系是站得住的。

十六、这版本地知识库的经验

16.1 先换问题，再换界面

知识库最重要的不是页面长什么样，而是它先回答了一个明确问题：经验不是没有产生，而是没有被稳定沉淀。知识库要让经验能被重新找到、理解和复用。
问题清楚以后，字段、布局和按钮才知道往哪里收。

16.2 哪些东西可以复用

• 清晰的页面、状态层、桥接层分工
• 状态层和本地存储节奏
• 复制、导出、通知这组桌面动作
• 开发环境与生产环境分开的加载逻辑

16.3 哪些东西不要硬套

• 旧的数据字段
• 旧的默认文案
• 旧的视觉重心
• 旧的排序规则

十七、后续可以补的检索能力

知识库目前已经能让经验条目有主题、有关键词、有回看入口。
真要继续加功能，我会优先从这些方向补：

1. 增加关键词自动汇总
2. 支持相关条目双向引用
3. 增加复习提醒和过期标记
4. 支持把知识条目导出成专题合集
5. 给高亮内容增加单独列表

知识库后续要解决“再次找到”和“再次理解”，而不是只追求条目数量。

十八、发布前做一次知识检查

发布前我会按下面这张表再扫一遍，尤其确认 主题一致性 和可发布性。

检查项	结果	说明
标题和主题一致	通过	知识库实战：把项目经验和调研结论沉淀成本地知识条目
图片存在	通过	保留项目结构图或运行效果图
代码块数量	通过	覆盖类型、状态、组件、桥接、导出、构建
资源链接	通过	保留社区和官方文档入口

总结

知识库这一版把经验沉淀变成可回看的条目。它不追求一开始就做大而全的知识管理，而是先让项目经验、调研结论和方法论有稳定位置。
知识库的第一版不需要急着变成复杂图谱。
只要主题、关键词、高亮、正文和关联能稳定保存，很多经验就已经从“想起来才有用”变成了“需要时找得到”。

如果这篇文章对你有帮助，欢迎点赞👍、收藏⭐、关注🔔，你的支持是我持续创作的动力！

---

相关资源：

• 鸿蒙PC开发者社区：https://harmonypc.csdn.net/
• OpenHarmony 官网：https://www.openharmony.cn/