AI 智能体助手（HarmonyOS NEXT）

一个使用 ArkTS 与 ArkUI 开发的 HarmonyOS NEXT 原生 AI 智能体应用。它不仅支持流式对话，还能在用户控制下调用工具、管理长期记忆、加载角色卡，并通过无障碍扩展执行有限的界面操作。

当前版本：0.1.0

目标系统：HarmonyOS 6.1.1 / API 24

当前阶段：功能开发版，可构建签名 HAP；核心导航与角色创建已在 Pura 90 模拟器验证，Mate X7 已验证本地对话、基础工具调用、闹钟本地落库和 WAMR 固定计算，完整真机回归和发布材料仍在推进

主要能力

• 模型快捷配置：预置 DeepSeek、OpenAI、通义千问和 Moonshot；选择供应商、填写 API Key、选择模型即可保存，同时保留完整自定义 OpenAI 兼容配置。
• 本地 GGUF 模型：内置模型下载页，可像下载软件一样选择轻量模型并自动下载、校验、创建配置；也保留系统文件选择器手动导入 GGUF。模型安装后通过内置 llama.cpp 完全离线对话。
• 流式对话：SSE 增量输出、停止生成、超时控制、有限重试，并保留被停止或中断的部分回复。
• 模型切换：聊天页可选择默认模型，切换后立即作用于当前会话。
• 首页角色切换：聊天页顶栏可选择默认助手或角色卡；切换角色会开启新对话，避免不同人设混入同一段历史。
• 对话历史：从屏幕左侧向右滑打开历史抽屉；抽屉打开后，全屏向左滑可关闭。历史支持搜索、新建、重命名、置顶和删除。
• 工具调用：共注册 21 个工具，包含文件、网络、剪贴板、闹钟创建与管理、长期记忆和无障碍操作。
• 工具运行环境：内置 WAMR 2.4.5 解释器，可在应用进程内运行不生成本机代码的固定 WASM 自检；设置页同时检测 N-API、fork + pipe、ptrace、应用自带 ELF、匿名内存 ELF、PTY 和系统 Shell，为后续安全插件、Python-WASI 与可选远程 Ubuntu 提供真实依据。
• 长期记忆：支持主动写入、人工管理、关键词降级检索、Embedding 语义召回和旧对话异步摘要。
• 角色卡：支持创建、编辑、删除、JSON 导入导出、酒馆 PNG chara / ccv3 元数据导入，以及从聊天首页直接选择角色。
• 原生光感弹层：模型、角色、记忆、白名单、备份和危险确认使用应用内可控弹层与系统模糊效果，避免部分设备上系统 Sheet 点击后不显示。
• 本地备份：可导出和恢复会话、消息、角色、记忆及非敏感设置，支持合并或替换。
• 本地优先：会话、角色、记忆和设置保存在设备本地；只有模型、Embedding 和用户主动触发的网络工具会访问网络。

当前实现状态

模块	状态	说明
工程与数据层	✅ 已实现	Stage 模型、10 个页面、RelationalStore、Preferences、数据库 v5
模型配置	✅ 已实现	四类供应商快捷配置、自定义兼容配置、HUKS 加密 API Key、连通性测试、默认模型切换
本地模型	🚧 首版已实现	内置可信模型目录、境内优先双下载源、残留清理、大小/SHA-256/GGUF 校验、手动导入、ARM64 CPU 推理和 Agent 接入；双源真机回归与 NPU 加速待完成
聊天与历史	✅ 已实现	SSE 流式输出、模型与角色选择、停止/超时/重试、历史抽屉、搜索、重命名、置顶、删除
工具系统	✅ 已实现	原生与文本协议兼容、参数校验、只读并行、重复调用保护、三级风险与脱敏审计
工具运行环境	🧪 WASM 安全运行时原型	Mate X7 已连续两次通过 WAMR 2.4.5 固定 add(20, 22) = 42 真机执行；外部 ELF、PTY 和系统 Shell 仍受沙箱限制。下一步实现受签名、限资源、声明权限的 WASM 插件包；Python-WASI 和远程 Ubuntu 后置
智能体闹钟	🚧 本地链路已实现	创建、查询、修改、启停、重试和删除已接入，并提供可视化管理页；Mate X7 已验证“每周一 08:00”准确落库，系统代理提醒仍受 1700002 阻塞
长期记忆	🚧 核心链路已实现	关键词和语义召回、记忆管理、向量重建；多供应商真机验证仍需扩大
角色卡	🚧 核心链路已实现	CRUD、首页选择、JSON 与酒馆 PNG 导入、头像落盘、人设注入；更多 PNG 样本兼容性待验证
无障碍自动化	🚧 核心链路已实现	UI 树、点击、滑动、20 步保护和急停；跨应用真机回归待完成
发布准备	🚧 进行中	隐私安全备份已实现；正式图标、正式签名、上架材料和完整回归尚未完成

这里的“已实现”表示代码链路完成并通过 ArkTS 编译与 HAP 打包，不代表所有供应商和设备组合都已经完成真机验收。

PRoot 上游采用 GPL-2.0-or-later，Talk 当前采用 MIT。当前探针不包含 PRoot 代码或 Operit 二进制；许可证与源码分发方案确定前不会把它们链接进主应用。

当前 HAP 静态包含 WAMR 2.4.5（固定提交 25bd7eb63e828e4bd242cc9b38d260b4b31c6605），其上游采用 Apache-2.0 with LLVM Exception。首版只启用经典解释器，关闭 AOT/JIT、WASI、文件、网络、线程和共享内存。

界面与手势

聊天页

• 左上角菜单按钮或从左侧向右滑：打开对话历史抽屉。
• 抽屉打开后，在屏幕任意位置向左滑：关闭抽屉。
• 顶部“角色”：选择默认助手或已有角色卡；切换后开启新对话。没有角色卡时可直接进入创建页。
• 顶部“选择模型”：打开模型选择面板。
• 右上角“设置”：进入统一设置页；返回聊天页时会重新同步全屏布局和上下安全区。
• 底部输入框：发送消息；生成期间可停止，且会阻止模型切换、历史删除和破坏性设置操作。

角色、模型、记忆编辑、危险确认和数据管理面板均由页面根 Stack 渲染，不依赖 bindSheet。系统返回键会优先关闭当前弹层；危险工具确认必须通过“拒绝”或“允许执行”结束。

设置页

设置页包括：

• 常规：最大工具轮数、上下文保留轮数、云端严格工具模式、聊天深色模式。云端严格模式关闭时，无法稳定输出原生 tool_calls 的兼容模型可使用显式文本工具协议；本地 GGUF 没有原生函数调用通道，始终使用受限的显式工具协议。
• 智能体：云端模型配置、本地 GGUF 导入、角色卡、记忆库和 Embedding。
• 工具与自动化：工具箱、工具运行环境能力检测、无障碍自动化状态和自检。
• 闹钟管理：查看 Talk 本地任务、系统接管状态与失败原因，可重试、启停或安全删除。
• 安全与数据：危险工具白名单、备份导出、备份恢复、清空聊天记录。

所有页面使用同一套窗口与系统栏管理逻辑，避免页面切换后出现状态栏或导航条遮挡。

工具清单

风险等级：

• READONLY：只读取信息，通常直接执行。
• WRITE：写入应用数据或系统状态，执行并留审计记录。
• DANGEROUS：删除、外部写请求或自动化手势，默认逐次弹窗确认。

工具	风险	用途与限制
file_read	READONLY	按字符位置分段读取沙箱内不超过 512 KiB 的 UTF-8 文本
file_search	READONLY	在沙箱文本文件中递归搜索字面文本，限制深度、文件数和结果数
file_list	READONLY	列出应用沙箱目录
file_write	WRITE	覆盖写入应用沙箱文本，内容最多 512 KiB
file_delete	DANGEROUS	删除沙箱内文件或空目录
http_request	动态	纯 GET/HEAD/OPTIONS 为只读；带请求体/自定义头或写方法为危险操作
web_fetch	READONLY	抓取公开 HTTPS 页面并提取正文
clipboard_read	READONLY	读取剪贴板；受系统权限与 ACL 限制
clipboard_write	WRITE	写入剪贴板
device_info	READONLY	获取有限的设备和网络状态
create_reminder	WRITE	创建一次性或每周重复闹钟；先保存 Talk 本地记录，再尝试交给系统代理提醒
create_recurring_alarm	WRITE	面向本地小模型的窄参数重复闹钟工具；只接收小时、分钟和重复星期
list_alarms	READONLY	查询 Talk 闹钟 ID、时间、启停状态和系统调度状态
update_alarm	WRITE	按 Talk 闹钟 ID 修改标题、时间或重复星期
set_alarm_enabled	WRITE	启用、停用或重试尚未生效的 Talk 闹钟
delete_alarm	DANGEROUS	取消对应系统提醒并永久删除 Talk 闹钟记录
get_current_time	READONLY	获取当前时间
update_memory	WRITE	保存明确、稳定且对未来有帮助的长期记忆
ui_tree_dump	READONLY	读取前台可访问的 UI 树摘要
tap	DANGEROUS	注入一次点击手势
swipe	DANGEROUS	注入一次滑动手势

文件工具统一经过沙箱路径校验，拒绝绝对路径、盘符、URI、. 和 ..。网络工具只允许公开 https:// 地址，拒绝本机、局域网、保留地址、数字主机变体和自动重定向；单次响应最多 2 MiB。

工具参数会在执行前统一检查 JSON、必填项和基础类型。模型同批请求的工具全部为 READONLY 时并行执行；包含写入或危险操作时保持原顺序。连续重复相同调用会先拒绝执行，持续重复则中断工具循环。

本地模型执行闹钟类确定性工具后，若同批每个结果都提供权威答复，应用会直接展示该结果并结束本轮，不再让小模型二次复述。这样可以避免把“每周一”说成“每小时”或改写系统错误码；云端模型与其他需要继续推理的工具仍使用标准结果回填循环。

闹钟工具以 Talk 本地数据库为事实来源。创建时先落库，再调用 reminderAgentManager；系统通知关闭、权限拒绝或代理提醒服务异常时，记录仍会保留并显示 “尚未生效”，不会把系统失败伪装成创建成功。系统可靠后台触发仍受 HarmonyOS 代理提醒服务约束，Talk 不会直接写入系统时钟应用的私有数据库。

云端默认优先使用供应商原生 tool_calls。云端严格工具模式关闭时，可识别显式 <tool_call>{"name":"...","arguments":{...}}</tool_call> 标签作为兼容兜底；本地 GGUF 始终使用该协议。针对真机上的小模型输出，只在显式标签内部容忍缺失结束标签、已知时间字段的数字前导零和对象后的少量闭合符号。普通 JSON、Markdown 代码块和自然语言不会触发执行，所有兼容调用仍经过工具启停、参数校验、风险确认和审计。重复闹钟还会以用户原句中可确定的星期、时间和标题校正模型参数，防止“每周一”被误设成每天。

隐私与安全

• API Key 使用 HUKS AES-256-GCM 加密后保存，不在界面和日志中回显。
• 备份不包含 API Key、HUKS 密文、签名材料或设备绝对路径。
• 工具审计会隐藏 Authorization、Cookie、Token、Secret、Password、请求正文、文件正文和 URL 查询参数。
• 数据库 v4 迁移会清理旧工具日志中的原始参数和结果内容，同时保留工具名、风险、成功率和耗时统计；当前数据库为 v5，并新增不保存凭据的闹钟记录表。
• 危险工具的“不再询问”可以在设置页撤销。
• 模型生成内容和工具建议不等于可信指令；删除、外部写入和自动操作前应检查确认面板中的目标与参数。

详细说明见 隐私与安全。 原生依赖的固定版本和许可证见 第三方组件说明。

环境要求

• DevEco Studio，安装 HarmonyOS 6.1.1 / API 24 SDK。
• JDK、Node.js 和 Hvigor 使用 DevEco Studio 自带版本。
• HarmonyOS NEXT 手机或兼容模拟器。
• 本地模型仅打包 arm64-v8a 原生库；推荐真机测试，并为模型文件、运行时和 KV Cache 预留足够存储与内存。
• 真机调试需要在 DevEco Studio 中配置自己的签名。

工程当前配置：

• Bundle name：com.example.talk
• Version：0.1.0（versionCode 1000000）
• Target / Compatible SDK：6.1.1(24)
• 设备类型：Phone、Tablet

构建与运行

使用 DevEco Studio

1. 克隆仓库并用 DevEco Studio 打开仓库根目录。
2. 等待 SDK、ohpm 与索引同步完成。
3. 在 File → Project Structure → Signing Configs 配置你自己的调试签名。
4. 连接设备或启动模拟器。
5. 运行 entry 模块。

使用 Hvigor

先配置本机的 DEVECO_HOME、DEVECO_SDK_HOME 和 JAVA_HOME，然后从仓库根目录执行：

macOS / zsh：

"$DEVECO_HOME/tools/node/bin/node" \
  "$DEVECO_HOME/tools/hvigor/bin/hvigorw.js" \
  --mode project -p product=default assembleApp -p buildMode=debug --no-daemon

Windows / PowerShell：

& "$env:DEVECO_HOME\tools\node\node.exe" `
  "$env:DEVECO_HOME\tools\hvigor\bin\hvigorw.js" `
  --mode project -p product=default assembleApp -p buildMode=debug --no-daemon

成功后，签名 HAP 通常位于：

entry/build/default/outputs/default/entry-default-signed.hap

仓库不包含可复用签名材料；不要提交本机签名配置、证书、私钥或密码。

首次从干净缓存构建时，CMake 会按 entry/src/main/cpp/CMakeLists.txt 中固定的提交下载 llama.cpp 与 WAMR 源码；后续可复用本机构建缓存。离线构建前需预先保留两项依赖的 FetchContent 缓存。

首次使用

1. 打开“设置 → 模型配置”。
2. 云端模型点击“新增”，选择供应商、填写 API Key、选择模型并保存；未预置的服务可进入“自定义配置”。本地模型点击“浏览并下载模型”，可从 9 个约 0.3–2.4 GB 的精选模型中选择，等待自动下载、校验并设为默认；已有 .gguf 文件时仍可点击“导入本地文件”。
3. 回到聊天页，通过顶部按钮选择模型。
4. 如需角色人设，通过顶部“角色”按钮创建或选择角色。
5. 发送普通消息确认流式输出正常。
6. 再测试一个只读工具，例如询问当前时间。
7. 如需长期记忆，进入记忆库或配置 Embedding。
8. 如需自动操作，在系统无障碍设置中手动启用本应用服务，并先运行应用内自检。

Base URL 可以填写供应商域名、带 /v1 的 API 根地址或完整的 /chat/completions 地址，应用会规范化 OpenAI 兼容 endpoint。

数据与备份

• 会话、消息、角色、记忆和工具审计保存在本机数据库中。
• 导出备份包含会话、消息、角色、记忆和非敏感设置。
• 合并恢复：保留本地数据，按 ID 或内容去重导入。
• 替换恢复：替换可备份的本地业务数据，但保留本机模型供应商和 API Key。
• 导入会话会绑定到本机可用的默认模型，避免引用其他设备不存在的模型配置。

项目结构

AppScope/app.json5
entry/src/main/
├── module.json5
├── resources/base/
├── cpp/                  # llama.cpp 原生模块、N-API 桥与 ArkTS 类型声明
└── ets/
    ├── entryability/       # 应用入口与初始化
    ├── accessibility/      # 无障碍扩展能力
    ├── pages/              # 9 个 ArkUI 页面
    ├── agent/              # AgentEngine、上下文裁剪、提示词组装
    ├── model/              # 适配器工厂、OpenAI/SSE 与本地 llama.cpp 封装
    │   └── ModelProviderPresets.ets # 常用供应商快捷配置
    ├── alarm/              # HarmonyOS 代理提醒调度与配额恢复
    ├── tools/              # 工具接口、权限、沙箱与网络策略
    │   ├── builtin/        # 18 个内置工具
    │   └── automation/     # 3 个自动化工具
    ├── automation/         # UI 树、动作执行、跨 Ability 桥
    ├── memory/             # 长期记忆、Embedding、向量检索
    ├── character/          # 角色卡存储与解析
    ├── data/               # 数据库、DAO、备份与偏好
    └── common/             # 设计令牌、日志、HUKS、窗口与通用能力

可靠性约束

• 消息和工具结果先落库，再通知 UI 渲染。
• 删除会话和清空聊天使用事务，并按工具审计 → 消息 → 会话的顺序处理。
• 单个工具结果默认最多 2000 字符，超出后写入沙箱文件并返回摘要与相对路径。
• Agent 最多连续调用 15 轮工具；云端单轮最长 60 秒，本地模型首轮含加载最长 300 秒。
• 记忆召回最多等待 2 秒，失败时自动降级，不阻塞聊天。
• 流式请求在已产生内容或工具调用后不会自动重试，避免重复回复或重复操作。
• 用户停止、网络中断或超时时，会尽量保存已经生成的部分回复并标记状态。

已知限制

• 不同 OpenAI 兼容供应商对 SSE、工具调用和 Embedding 的细节可能不同，需要逐个真机验证。
• 当前本地模型首版为 ARM64 CPU 推理，不调用麒麟 NPU；模拟器速度不能代表麒麟真机性能。模型能否运行取决于 GGUF 架构、量化格式、可用内存和上下文设置。
• 内置目录提供 Qwen3/3.5、Gemma 3、DeepSeek-R1 Distill 和 SmolLM3 共 9 个量化模型，优先从对应的 ModelScope 镜像下载，连接或传输失败时自动切换到 Hugging Face 仓库。切换来源会清理半成品并重新计算 SHA-256；单个模型首次下载会消耗约 0.3–2.4 GB 流量。目录中的许可证提示不替代模型仓库的完整许可条款。
• 本地 GGUF 暂不提供 Embedding；启用语义记忆时仍需单独配置兼容的 Embedding 供应商，否则自动降级到关键词检索。
• 预置模型 ID 用于简化配置，但供应商可能调整模型名称、权限或开放范围；以实际账号连通性测试结果为准。
• READ_PASTEBOARD 属于受限能力，未获得相应权限时剪贴板读取不可用。
• Mate X7 当前对第三方 reminderAgentManager 返回 1700002。已排除权限声明、当前签名/Profile、通知关闭、旧签名身份残留和 Talk 自身提醒数量：彻底卸载重装、开启通知后创建两分钟测试提醒，系统仍在 Talk 有效提醒为 0 且重置本应用状态后返回同一错误。闹钟会保留为本地“尚未生效”记录，系统时钟 App 能创建闹钟不代表第三方代理提醒通道可用。
• 自动化依赖用户手动启用无障碍服务，只能操作无障碍框架可见的 UI；不支持 Root、ADB、屏幕截图识别或任意二进制执行。
• 公开 HTTPS 域名仍可能存在 DNS 解析层面的风险；危险外部写请求必须由用户确认。
• 项目仍有部分 SDK 弃用与“可能抛异常”编译警告，当前不阻止 HAP 构建，但发布前需要逐步收敛。

许可证

本项目使用 MIT License。

相关文档

• 隐私与安全
• 真机验收清单
• 架构说明
• 开发交接
• 版本记录

贡献与敏感信息

提交前至少执行完整 ArkTS/HAP 构建，并检查：

git status --short
git diff --check

禁止提交以下内容：

• API Key、访问令牌、Cookie 或 Authorization 头。
• 签名证书、私钥、密码和本机签名配置。
• 含敏感信息的聊天备份、数据库或日志。
• 开发者个人设备序列号和不必要的绝对路径。