目录

河澜录

黄河河南段文化数字档案 · 一轴黄河,一卷千年

把黄河河南段的 5 座城、6 个年代、15 处遗址,铺成一卷可以顺流而下、可以随时发问、可以排成一天行程的时空长卷。

第九届传智杯 · AI 鸿蒙赛道 | HarmonyOS NEXT / OpenHarmony(ArkTS + ArkUI) | API 12 · com.example.helanlu


这是什么

一个不是列表的文化档案。打开它,你先看到一张立轴;点「开卷」,河从屏幕顶端开始流,向下滑就是顺流而下,五座城依次展开;点任意一处遗址,半屏浮层从底下升起、上方仍露着河;读不懂的地方,问「小录」,它只按馆藏资料作答、每句话都带可点回的出处;想去看,说一句「周六一天,从郑州出发,带 8 岁小孩」,它把三座城排成一条带车程和票价的时间轴。

三件事是同一条河的三层:

层 是什么 在哪
地理轴 三门峡 → 洛阳 → 郑州 → 开封 → 濮阳,全程 711 km,纵向滑动 = 顺流而下 长卷
时间轴 仰韶 → 龙山 → 夏商 → 周 → 汉唐 → 宋,横向是每一代的断面 长卷 / 文脉星图
人的轴 收藏 / 笔记 / 拓片 / 主题 / 行程 —— 你看过什么、想问什么、准备去哪 收藏 / 小录 / 行程

它要解决的三个断点

断点 现实里长什么样 这个作品怎么接
散 15 处遗址分属 5 个地市、6 个年代,讲起来是 15 份互不相干的资料 一条河串成一张图:一眼看见谁在谁的下游、谁在谁之后
远 年代、地层、考古术语离普通人很远,看完只记得”很古老” 小录(RAG)只依据 131 段馆藏作答,句末 [n] 点回原文,不编造
浅 看完不知道”我该怎么去、一天够不够、带孩子行不行” 行程 Agent 把一句话翻译成带车程 / 停留 / 开放时间 / 票价的时间轴

功能地图

底栏五格,对应”读 / 藏 / 问 / 望 / 行”:

长卷 ──── 读:卷首立轴 → 五城章节 → 卷尾 711 km,河道随屏蜿蜒
收藏 ──── 藏:收藏 / 笔记 / 拓片三栏,按年代筛,跨遗址汇总
小录 ──── 问:BM25 召回 131 段馆藏 → 星火 X2 → 逐字打字机 + 可点引用
文脉 ──── 望:5 城 × 6 代星座图,节点=到过/问过/记过,捏合缩放 + 拖动平移
行程 ──── 行:一句话 → 抽槽位 → 工具检索 → 模型只挑 ID → 本地排程 → 兜底

长卷上还叠着两枚入口:「河的一生」(六次治水叠在同一条河上,河道按史实改道)与 「巡航」(约 20 秒自动走完全卷,讲解词随城切换,可暂停退出)。顶栏是年代筛选 + 检索。

14 项能力与状态

# 模块 入口 状态
1 时空长卷(卷首 / 五城 / 卷尾 / 里程尺跳章) 底栏「长卷」 ✅
2 遗址半屏浮层(可上拖、可下滑读、右上放大图标进整页) 点卡片 ✅
3 遗址详情(考古 / 历史地位 / 诗词 / 文旅 / 沿河定位 / 纹样 / 笔记 / 收藏 / 推荐) 浮层或列表 ✅
4 小录问答(RAG + 引用角标 + 打字机) 底栏「小录」 ✅
5 行程 Agent(状态机 + 工具 + 白名单校验 + 兜底) 底栏「行程」 ✅
6 文脉星图(星座图 / 缩放 / 平移 / 关联连线) 底栏「文脉」 ✅
7 收藏 / 笔记 / 拓片 底栏「收藏」 ✅
8 文化主题 → 知识节点网络 收藏页「文化主题」 ✅
9 河的一生(六次治水) 长卷左下 ✅
10 以纹入卷(六族程序化纹样,可拓一枚) 详情页 ✅
11 自动巡航 长卷右下 ✅
12 分布式同步(KV autoSync + 冲突仲裁) 收藏页「同步」 ✅ 代码完成,双机复验见测试说明 §3.9
13 备份与恢复 同步面板 ✅
14 关键词检索(八字段匹配 + 词建议) 长卷顶栏 ✅

鸿蒙与 AI 能力

HarmonyOS 原生能力

能力 用在哪 关键 API
分布式数据管理 收藏 / 笔记 / 主题 / 拓片跨设备同步,一条数据一个 Key,dataChange 实时刷新 distributedKVStore.SingleKVStore、autoSync、on('dataChange')
分布式设备管理 取 networkId 做手动 PUSH_PULL 兜底 distributedDeviceManager
全屏布局与安全区 底栏沉到物理屏幕最底,不漏出后方河道 setWindowLayoutFullScreen(true)、getWindowAvoidArea
半模态浮层 遗址详情不离开长卷 bindSheet(detents: [MEDIUM, LARGE])
Canvas 绘制 放大图标、河道、纹样、星图连线 Canvas + CanvasRenderingContext2D
属性动画 / 转场 启卷过渡、页面横向推入、巡航推进 animateTo、pageTransition、curve
本地存储 离线配置、阅读进度 preferences

AI 能力

能力 实现 诚实边界
大模型接入 讯飞星火 MaaS,spark-x2.6-1.7b,OpenAI 兼容 /v2/chat/completions;关思考模式、temperature=0.2 需自备 key,三条配置路径见运行说明 §3
RAG 中文 unigram+bigram 分词 → BM25(topK=4,单条截断 420 字)→ 七条硬约束 Prompt → [n] 角标落地 语料是本地 131 段馆藏,不是向量库;未命中会明示”无出处”
Agent 行程规划:规则抽槽位 → 工具检索 → 模型只挑 ID 与理由 → 白名单校验 → 本地排程 → 显式兜底 模型不产出任何时间 / 票价 / 开放时间,事实全来自本地事实表
端侧智能 分词、BM25、排程、相似度、纹样生成,全部本地计算,离线可用 无语义向量、无端侧推理模型

完整的参数、Prompt、状态机、成本估算与”明确没做的”,见 docs/AI能力说明.md。


技术架构

┌──────────────────────────── 表现层 · pages/ (11 路由) ────────────────────────────┐
│ Index(长卷)  Detail  Search  Favorites  Themes  ThemeDetail                        │
│ KnowledgeGraph  Assistant  Trip  Trace  SyncPanel                                  │
│ 组件层:ScrollPrologue / ScrollHud / BottomNav / SiteCard / MileageRuler /         │
│         CruiseOverlay / EraPicker / TraceConstellation / FloodTimeline …          │
└───────────────────────────────────┬────────────────────────────────────────────────┘
                                    │ 只调静态方法,不碰存储细节
┌───────────────────────────────────┴────────────────────────────────────────────────┐
│ 能力层 · utils/                                                                     │
│ AiClient(星火) · AiConfig · XiaoluBrain(Prompt) · KnowledgeBase(BM25)              │
│ TripAgent(状态机) · TripTools(事实表) · Mileage(里程) · RiverCourse(河道几何)      │
│ TraceGraph · ThemeGraph · EraPalette(设计令牌) · AppRoute(路由表) · ZoomLevel       │
└───────────────────────────────────┬────────────────────────────────────────────────┘
                                    │
┌───────────────────────────────────┴────────────────────────────────────────────────┐
│ 数据层 · data/ + model/                                                             │
│ KVStoreManager(SingleKVStore) · FavoritesStore · NotesStore · SyncManager          │
│ BackupUtils · DataLoader · DataModels                                              │
└───────────────────────────────────┬────────────────────────────────────────────────┘
                                    │
┌───────────────────────────────────┴────────────────────────────────────────────────┐
│ 离线资源 · rawfile/          │ 分布式设备                            │ 云端         │
│ sites.json(15) kb.json(131)  │ 手机 ⇄ 平板(同一账号 / 同签名)       │ 星火 MaaS    │
│ flood_history.json extensions│                                      │              │
└─────────────────────────────────────────────────────────────────────────────────────┘

一句话技术骨架:长卷不是一张背景图,而是坐标系本身 —— 15 处遗址的横纵位置由「城市 × 年代」唯一确定,里程读数、章节跳转、巡航讲解、星图布点全部共用这一套坐标。改一处坐标,四处同时正确。


仓库结构

hongmeng/
├── README.md                  ← 本文件(项目总览与导航)
├── docs/                      ← ★ 交付文档(从这里读)
│   ├── README.md              文档索引 + 提交要求逐条对照
│   ├── 作品说明文档.md          主文档,7 章(评委必读)
│   ├── AI能力说明.md          大模型 / RAG / Agent / 密钥 / 成本
│   ├── 测试说明.md            环境、方法、11 组用例、已知问题
│   ├── 运行与体验说明.md       构建、配置、5 分钟动线、FAQ
│   ├── 提交打包说明.md         ZIP 结构、打包清单、体积控制
│   └── assets/                9 张实机截图(1320×2232)
├── A/                         ← ★ 唯一的 DevEco 工程根(用 DevEco 打开这一层)
│   ├── AppScope/app.json5     bundleName: com.example.helanlu
│   ├── build-profile.json5    compatibleSdkVersion 5.0.0(12)
│   ├── entry/src/main/ets/    84 个 .ets,约 2.35 万行
│   │   ├── entryability/      EntryAbility(全屏 + 库初始化)
│   │   ├── pages/             11 个路由页 + FloodTimeline(长卷内浮层)
│   │   ├── components/        Scroll/ 与通用组件
│   │   ├── utils/             能力层(AI / 几何 / 令牌 / 路由)
│   │   ├── data/              分布式 KV / 收藏 / 笔记 / 同步 / 备份
│   │   └── model/             数据结构
│   ├── entry/src/main/resources/rawfile/   离线数据与图片
│   └── README.md              ★ 主开发文档(设计要点 + 踩坑记录)
├── demo/                      演示视频
├── tools/                     llm-proxy.js / strip-key.sh / package-submission.sh
└── B/                         归档:早期原型,已不参与编译与交付

⚠️ 两个易错点:

  1. DevEco Studio 要打开 A/ 这一层,不是仓库根(根目录没有 build-profile.json5)。
  2. B/ 与 A/A/ 是历史快照,不参与编译。打包脚本会排除 A/A/ 与 rawfile/_backup/; B/ 保留在 ZIP 内是为了说明数据层的演进,其 README 已标明”勿用”。

快速开始

# 1. 构建(Windows Git Bash)
cd A
DEVECO_SDK_HOME="/e/DevEco Studio/sdk" \
node.exe "/e/DevEco Studio/tools/hvigor/bin/hvigorw.js" \
  --mode module -p product=default assembleHap --no-daemon

# 2. 安装(模拟器或真机)
export PATH="/e/DevEco Studio/sdk/default/openharmony/toolchains:$PATH"
hdc install -r entry/build/default/outputs/default/entry-default-unsigned.hap

# 3. 启动
hdc shell aa start -a EntryAbility -b com.example.helanlu

模型密钥:A/entry/src/main/ets/utils/AiKey.ets,一把讯飞星火 MaaS 的 key(spark-x2.6-1.7b,免费模型)。 默认随包带着,评委装好即可试 AI。若想换形态,详见 docs/运行与体验说明.md §3:

  1. 保持原样(当前采用)—— 免费额度,泄露影响可控
  2. 走 tools/llm-proxy.js 代理:key 留在环境变量里,包里只有 http://<电脑局域网IP>:8787/v2 (路径原样转给上游,星火是 /v2、DeepSeek 是 /v1)
  3. 置空串(小录会提示”没配置密钥”,其余 13 项功能不受影响 —— 全部离线)
bash tools/strip-key.sh --check   # 体检:列出源码里还在的 key(可选)
bash tools/package-submission.sh  # 一键出 ZIP

更省事的方式:用 DevEco Studio 打开 A/,勾选自动签名,直接 Run。见运行说明 §2.1。


文档导航

你想知道 去哪
这个作品到底做了什么、凭什么得奖 docs/作品说明文档.md
哪些是鸿蒙原生能力、哪些是 AI,各自怎么做 docs/作品说明文档.md §2 + docs/AI能力说明.md
怎么在自己机器上跑起来 docs/运行与体验说明.md
测过什么、有没有坑 docs/测试说明.md
怎么打包提交、命名怎么改 docs/提交打包说明.md
某个具体设计为什么这么定(长卷几何、里程读线、转场、打字机…) A/README.md(3.x 节,逐条带踩坑原因)
提交要求逐条对照在哪 docs/README.md §二

已知边界

写在这里,比写在答辩时被问到更好:

  • 分布式同步:代码路径完整(autoSync + dataChange + 时间戳仲裁 + 冲突计数 + 手动 PUSH_PULL),但双机复验需要在同一华为账号下的两台设备完成,当前提交的是单机可验部分 + 复验步骤(测试说明 §3.9)。
  • AI 依赖网络:小录与行程的”模型决策”一步需联网;断网时行程自动降级为本地规则(页面会明写”本次由本地规则兜底”),小录提示无网络。其余功能全部离线。
  • 语料规模:131 段、15 处遗址。这是”可核查”的前提,也是当前的边界 —— 扩展到全省需要重做检索层(见 AI 说明 §六)。
  • 未做:流式输出(当前是完整的逐字打字机)、语音输入、拍照识别、跨设备协同编辑的合并排序、主题持久化到云端。

提交物

项 位置 状态
源代码 A/ ✅
作品说明文档 docs/作品说明文档.md ✅
AI 能力说明 docs/AI能力说明.md ✅
测试说明 docs/测试说明.md ✅
运行与配置说明 docs/运行与体验说明.md ✅
演示视频(3 分钟) demo/ ✅

数据与素材

  • 遗址条目(名称 / 年代 / 城市 / 考古发现 / 诗词 / 文旅信息)均取自公开出版物与官方考古通报,逐条可核;
  • 图片素材为自摄或可商用授权,缺失时回落为”年代渐变底 + 类型剪影”的程序化占位,不阻塞任何界面;
  • 代码为原创,第三方依赖仅 HarmonyOS SDK 与系统 Kit,无额外 npm/ohpm 包。

文档版本 v1.0.0(2026-11-17)。主开发文档与踩坑记录见 A/README.md,交付文档索引见 docs/README.md。

关于
285.6 MB
邀请码
    Gitlink(确实开源)
  • 加入我们
  • 官网邮箱:gitlink@ccf.org.cn
  • QQ群
  • QQ群
  • 公众号
  • 公众号

版权所有:中国计算机学会技术支持:开源发展技术委员会
京ICP备13000930号-9 京公网安备 11010802047560号