鸿蒙 App 加 AI：智能体跑在手机上还是服务端？

给 HarmonyOS／鸿蒙原生应用加 AI 助手时，最先要定的不是「选哪家模型」，而是：智能体运行链放在手机上，还是放在你控制的服务端？ 把规划、工具编排、上下文和平台凭据都塞进 HAP，短期看起来少一台机器；一旦应用可被逆向、安装包可被提取，长效密钥与权限裁决就变成整应用面的泄漏与失控面。

2026 年鸿蒙侧的公开材料，把「应用如何融入智能体生态」推到了开发者日常议程。华为开发者文档《方舟智能开发框架概述》（更新 2026-07-28，本机 2026-11-09 再核 HTTP 200）写明：系统智能体正成为用户与操作系统交互的新入口，应用通过意图、Skill、端侧 A2A 等机制把能力外化给系统智能体。《基于 ArkTS 脚本的应用 Skill 开发指导》（更新 2026-09-30，HTTP 200）进一步强调：Skill 入口脚本应是薄适配层，把系统智能体传入的参数转给既有业务，而不是在脚本里堆业务逻辑。华为开发者联盟话题合集《Harmony Intelligence AI 开放能力深度解读》（HTTP 200）与 HarmonyOS 开发者官方微博 2026-11-05 的Agent 实战课推介（HTTP 200）则把「应用搭建 → Agent 接入 → 界面交互」写成近期开发路径。业界同期实践也指向同一纪律：掘金《我为 HarmonyOS 做了一个统一大模型 SDK》（HTTP 200）明确要求不要把生产环境大模型 API Key 写进 HarmonyOS 客户端，正式应用应经自有服务端签发短期凭据；CSDN《鸿蒙 NEXT 也能接 MCP？》（HTTP 200）建议 ArkTS 薄 UI + Agent 编排服务 + 工具层，手机不直接堆推理与敏感编排。另有小艺应用内 Agent／英文版端侧 A2A 文档本机抓取为 HTTP 502，未采信为主证。

对鸿蒙／移动端 AI 开发者，完整行业答案可以收成六句话：

1. 系统智能体入口与应用内 AI 助手是两件事：前者问「怎么把应用能力交给系统智能体」；后者问「应用自己的助手内核跑在哪」。
2. 可分发 App 是 public client：长效平台密钥、上游模型密钥、服务端签名私钥不应进 HAP／Preferences／日志。
3. 手机侧更稳妥的是薄客户端：发送输入、归约事件流、执行你显式注册的本地工具、应答权限与提问；规划、上下文、权限引擎留在你部署的会话服务。
4. 公网抓取／HTTP／搜索类工具适合在服务端执行：缺省关闭、按应用开启，手机不代发、不自动批准。
5. Android／iOS／鸿蒙可以共用同一套视图归约与后端会话面：一应用一平台类型，分吊销面与用量归因。
6. 断线恢复、会话上限、工具参数形状都是接入硬约束：不能按「网页聊天框」习惯硬套。

本文把上述行业问题映射到已核实的 Tansr 机制：@tansr/harmony 作为会话服务的原生 ArkTS 薄客户端（HAR），智能体内核跑在你部署的 @tansr/serve；手机只经 AuthProvider 持有你自己的短期登录头；移动应用类型默认关闭文件／命令族，公网工具在服务端执行且缺省关；SessionView 与 Android／iOS 共用金样；0.2.0 HAR 全部请求只走 /api（见 鸿蒙 SDK 5 分钟跑通、鸿蒙接入指南、平台装配与 bundle、统一调用面，2026-11-09 再核均为 HTTP 200）。它不是 S08 的 Electron 安装包 appkey／短期令牌换发主线，也不是 S07 能力位治理全文、S06 调用排障、S01 提示词分层或 R01 费用；这里只回答开发者常问的：鸿蒙现有软件接 AI 时，运行位置怎么选、薄客户端边界在哪。

直接答案

1. 默认把智能体运行链放在你部署的 @tansr/serve：手机上的 @tansr/harmony 只做薄客户端——发输入、归约事件、跑显式注册的本地工具、答权限／提问。
2. 手机不持平台凭据：设备侧只有你自己的登录态；SDK 经 AuthProvider.headers() 按次取短期认证头，不持久化到 Preferences／文件／日志；不要放平台 AppKey、上游模型密钥或服务端签名私钥。
3. 先建「移动应用」类型：控制台应用类型决定能力面。移动应用（Android／iOS／鸿蒙）文件／命令族固定关；webFetch／http／webSearch 可勾选但缺省关，且在会话服务主机上执行，HAR 不在设备上代发网络请求。
4. 三端同律看视图，不看把内核塞进手机：SessionView 归约快照与 Android／iOS 金样同形；HAR 不含 ArkUI 页面，录音／播放／列表虚拟化由宿主自己接。
5. 版本与调用面要对齐：当前独立发布 HAR 0.2.0（2026-10-10），随 harmony-sdk.zip 分发，尚未上架公共 OHPM；声明最低 HarmonyOS 6.0／API 20（Stage；以 API 22 工具链构建）。0.2.0 全部请求只走服务端 0.13.0 起的统一调用面 /api，不回退 /v2。服务端核对基线为 @tansr/serve 0.15.1。
6. 本地工具要双一致：session.bridges.registerTool 与建会／resume 时的 clientTools 声明必须一致；parameters 是「参数名 → 规格」字典，无参数为 {}，不能传整份 JSON Schema（否则常见 400）。
7. 断线与容量是产品约束：断线 L1 游标重连、L2 拉 /history、L3 resume；每个终端用户缺省最多 8 个活跃会话，超限 429 capacity_exceeded（domainCode = session_limit_exceeded）。不用的会话请 close()。
8. 鸿蒙 SDK 不经 /api 会话请求传 system：共享角色走平台应用提示词，代码定制走 serve 的 platform.system，宿主说明用 platform.systemAppend（提示词细节见 S01；本文只标边界）。

行业问题：为什么「先在手机里跑通大模型」不够

ArkAF／Skill 材料强调的「薄适配」、统一大模型 SDK 文强调的「密钥不出端」、MCP 实务文强调的「薄 UI＋编排服务」，共同指向同一产品缺口：鸿蒙现有软件接 AI，要先定运行位置与凭据边界，再谈聊天 UI。

你原来要自己做的事 → Tansr 接手什么 → 应用仍要负责什么

原来常要自行完成的：

• 在 ArkTS 页面里直连多家模型 API，密钥进包或进本地存储。
• 自研事件流归约、工具卡状态、断线重连与「该不该新建会话」的分支。
• 为 Android／iOS／鸿蒙分别维护三套助手内核与权限语义。
• 公网工具、文件／命令类能力缺少应用级缺省关断与服务端执行边界。

Tansr 公开机制可接手的部分（以 2026-11-09 抓取的 docs.tansr.com 为准；公开可安装基线以文档当日为准；0.20.0 候发内容不得写成已上线；2026-10-10 之后进入主线但未随任何 HAR 发布的加密记忆／加密增量 RDB 等本文不描述）：

• @tansr/harmony：原生 ArkTS 薄客户端 HAR；发送输入、归约事件、本地工具桥、权限／提问应答。
• @tansr/serve：智能体内核、权限引擎、上下文治理与（按能力位）公网工具执行位置。
• 移动应用能力面：文件／命令族固定关；todoWrite／askUser／customTools／公网三位可配；公网工具在服务端执行。
• SessionView 与 Android／iOS 同形金样；连接态与 L1／L2／L3 恢复。
• /api 统一调用面与统一错误信封；AuthProvider／RefreshingAuthProvider 按次取头。
• 终端用户活跃会话缺省上限 8；clientTools.parameters 参数名字典约定。

应用仍要负责：

• 自建并运维可达的 @tansr/serve（含 HTTPS；真机连开发机私网须显式 allowPrivateNetworkHttp，生产不忽略证书错误）。
• 你自己的登录体系与 authenticate 缝（解出 endUserId）；换票失败不要暗中重放密码登录。
• ArkUI、录音、播放、列表虚拟化；操作系统麦克风授权与智能体工具许可是两层。
• 获取独立 harmony-sdk.zip、核对 SHA256SUMS、按版本整包升级；未上架公共 OHPM，不能写成「ohpm 一键最新」。
• 控制台为移动应用打开真正需要的公网位；紧急撤回要停止相应会话（改位不对运行中会话热更新工具表）。
• HarmonyOS 5.x 原生兼容当前不宣称可用；仅 Android 兼容栈的旧设备继续用 Android SDK。
• 本批未在 DevEco 模拟器／真机跑通接入演示；标题收窄为架构与接线要点，不承诺「五分钟照做必过」。

推荐接线顺序（机制说明，非「五分钟照做」承诺）

1. 部署 @tansr/serve（≥0.13.0 提供 /api；文档核对基线 0.15.1），确认统一调用面可用。
2. 控制台创建移动应用类型（鸿蒙与 Android／iOS 分应用更利于吊销与归因），按需打开公网工具位（缺省关）。
3. 解压 harmony-sdk.zip，核对 HAR 摘要后以 file: 依赖安装；useNormalizedOHMUrl: true 后再 ohpm install。
4. 实现 AuthProvider（生产用 RefreshingAuthProvider）；StaticAuthProvider 仅短时调试。
5. createSession 成功后先把确认的 sessionId 写入原登录作用域，再绑 AgentSession＋SessionView；保存失败不要自动再建。
6. 需要本地能力时：registerTool＋同形 clientTools；只响应 server.permission.request；未设 onPermission 默认拒绝。
7. 接前后台：stop() 停本地订阅不丢远端；回前台再 start()；退出登录／释放组件该 close() 时再关远端。
8. 联调把 contract_unavailable、invalid_request（参数字典）、capacity_exceeded、401 登录态分开展示，避免统一「网络繁忙」。

什么时候采用，什么时候不采用

值得按此推进：要把 AI 助手嵌进可分发的鸿蒙／移动产品；安全评审要求证明「安装包无平台／模型长效密钥」；需要 Android／iOS／鸿蒙共用后端会话与同形界面状态；接受自建会话服务与移动应用能力缺省面。

先不要：把平台 AppKey 或模型密钥写进 ArkTS「图省事」；把系统 Skill／A2A 文档直接当成「内核必须在端侧」的证明；在未取得独立 HAR 包／未核 SHA256 前对外承诺「可下载即用」；把 HarmonyOS 5.x 写成已支持原生包；或在本批未做真机验证的情况下承诺「照做五分钟跑通」。纯本地、永不联网、从不分发的实验脚本可以另议——一旦进入可分发鸿蒙应用，就应按薄客户端纪律。

与已有稿的差异

• 相对 S08：S08 讲 Electron 分发面 appkey 不进安装包／签名换发／token getter；本文讲 鸿蒙／移动运行位置：薄客户端 vs 会话服务。
• 相对 A08：A08 讲业务系统选进程内 SDK 还是会话服务；本文补 移动／鸿蒙拓扑（凭据位置、移动能力缺省、三端同形视图、HAR／/api 约束）。
• 相对 S07：S07 讲应用级能力位治理全文；本文只取 移动应用能力面与公网工具执行位置 与运行位置相关的切片。
• 相对 S06／S01／R01／M01／G01／Q01／S04／S05：排障分码、提示词分层、费用预算、模型切换、媒体三路径、稍后重试、MCP 安全令牌、Skills 完整性均非本篇主线。
• 相对规划 Q3／Q8：本篇取开发者向「运行位置＋薄客户端接线」合题，覆盖现有软件接入 AI；企业采购口径可另篇，不在本包重复扩写。

限制（紧邻结论）

• 产品事实以 2026-11-09 抓取的 docs.tansr.com 公开页为准；未做 DevEco／真机接入实测；不承诺「五分钟必过」。
• HAR 独立分发、未上架公共 OHPM；获取渠道与许可以当日文档／发放说明为准，正文不编造下载入口。
• 小艺应用内 Agent 文档与英文端侧 A2A 页本机 HTTP 502，未采信为主证。
• 不写具体价格；不写「免费试用」；不把未随 HAR 发布的能力写成已上线。
• AI 效果基线本批缺测，按指导单独记录，不阻塞内容交付。