iPhone Shortcut Migration Guide

把已有快捷指令改成安全配对版

适用于你已经有一个旧版 MonoSpend 快捷指令，但里面把 Authorization token 写死了的情况。目标是保留原来的语音记账动作，把凭证改成「首次运行输入配对码，本机保存 device token」。

进入高级管理生成配对码 查看安装页 打开长图备用版

01

复制旧指令

保留原件，所有修改都在副本里完成。

02

删除旧 token

清掉写死的 Authorization header。

03

新增配对分支

没有本机 token 时，询问网页配对码。

04

保存 device token

把 pair 返回的 token 存在本机文件。

05

一句话 capture

日常记账只调用 /api/capture。

Before Editing

开始前先确认三件事

这一步能避免把旧 token 继续传播出去。这里的 token 指生产凭证或个人 device token，不要写进要分享的 iCloud 快捷指令安装包。

Account

能登录 MonoSpend 工作台

打开 https://monospend.app/app，登录后才能生成 10 分钟有效的一次性配对码。

Shortcut

先复制，不直接改原件

在 iPhone「快捷指令」里长按旧指令，选择复制。把副本命名为 MonoSpend Capture Pairing。

  1. 1打开 iPhone「快捷指令」App。
  2. 2长按旧的 MonoSpend 快捷指令。
  3. 3点「复制」或「Duplicate」。只编辑副本。

Storage

约定本机 token 文件

后续动作统一读写 Shortcuts/monospend-token.txt。这个文件只在本机，不放进公开安装包。

Find Your Starting Point

先判断你的旧快捷指令是哪一种

不要一上来就改。先打开旧指令，找到最核心的「获取 URL 内容」动作，看它有没有写死 Authorization，有没有已有的配对逻辑。

Most likely

只有 /api/capture + 固定 token

这是最常见的老版本。按下面完整迁移步骤做：复制旧指令、删除固定 token、新增配对分支、保存 device token。

Half migrated

已经有 /api/pair，但 token 仍写死

保留配对请求，重点检查 capture 请求里的 Authorization，必须改成读取本机保存的 Device Token 变量。

Clean start

旧指令太乱或找不到请求动作

不要硬修。打开 /shortcut，按安全安装页重新建一份，再把旧指令里的听写文案或菜单动作搬过去。

Action Map

旧动作应该保留、删除还是替换

你可以把这节当成核对表。迁移的关键不是重写所有动作，而是把“凭证来源”从固定文本改成本机设备 token。

Keep
听写文本 / 询问输入

继续保留。它的结果最终进入 JSON 的 transcript 字段。

Keep
POST https://monospend.app/api/capture

继续保留这个日常记账请求，只改 Authorization 的来源。

Delete
固定的 Bearer xxx

必须删除。任何真实 token 都不能留在要分享的 iCloud 快捷指令里。

Add
首次运行 /api/pair 分支

没有本机 token 时，询问配对码，换取 device token，并保存到本机文件。

Change
Authorization Header

改成 Bearer [Device Token]。这里的 Device Token 必须是变量，不是手写文本。

Keep
显示结果 / 打开纠错 URL

继续读取 confirmation。需要改错时再打开 correctionUrl。

Action By Action

按这个顺序改快捷指令

下面用 iOS 快捷指令里的常见动作名称描述。不同 iOS 版本中文翻译会略有差异，核心是同一件事：先拿 device token，再用它写 capture。

01

找到旧的「获取 URL 内容」动作

旧版通常已经有一个请求指向 https://monospend.app/api/capture，Method 是 POST，Body 是 JSON。

  1. 1点开副本右上角的编辑按钮。
  2. 2向下滚动，找到「获取 URL 内容」或「Get Contents of URL」。
  3. 3确认 URL 里包含 /api/capture。
Get Contents of URL POST /api/capture

要保留：URL、POST、JSON body、听写文本变量。
要删除：写死的 Authorization token。

02

删除旧 Header 里的真实 token

进入 Headers，找到 Authorization。如果值是 Bearer sk...、Bearer msp... 或任何固定字符串，把它删掉。

  1. 1展开「获取 URL 内容」动作里的 Headers。
  2. 2找到 key 为 Authorization 的字段。
  3. 3先删除 value 里的真实 token；后面会改成变量。
Authorization Bearer 固定值 删除

不要把旧指令继续分享出去。只要里面有真实 token，这个 iCloud 链接就不适合作为公开安装包。

03

在 capture 前新增「读取本机 token」

新增文件读取动作，读取 Shortcuts/monospend-token.txt。搜索「获取文件」时，要选「获取文件夹中的文件」，不要选「获取文件的详细信息」。这一行动作的字段顺序容易看错：路径填文件名，文件夹填 Shortcuts。

  1. 1在 capture 请求前添加「获取文件夹中的文件」。它才会从文件夹里取出保存好的 token 文件。
  2. 2点「从路径」后面的蓝色块，清空原来的变量或示例文本，填纯文本 monospend-token.txt。
  3. 3点「获取」后面的文件夹位置，选择 iCloud Drive 里的 Shortcuts / 快捷指令文件夹。最终应类似：从路径 monospend-token.txt 获取 iCloud Drive / Shortcuts 中的文件。
  4. 4如果有「显示文稿选择器」，把它关闭；如果有「找不到时报错」，也关闭，让首次运行能进入配对分支。
  5. 5紧跟一个「获取文本」或「从输入中获取文本」，输入选择刚才取到的文件；再添加「设定变量」，变量名用 Device Token。
Get File Get Text monospend-token.txt Set Variable

如果弹窗里出现「名称」「文件大小」「文件路径」这些选项，说明你正在选文件详情。这里不要选「名称」，否则 Authorization 会变成 Bearer monospend-token.txt。
如果没有「获取文件夹中的文件」，用「获取文件夹内容」加「筛选文件」按名称找到 monospend-token.txt。

04

新增「首次配对」分支

在没有 token 时，先用「询问输入」让用户输入网页上的配对码，再请求 POST /api/pair。这个 If 要放在设定 Device Token 之后、/api/capture 请求之前。

  1. 1点底部搜索框，搜索「如果」，选择脚本里的「如果」动作。
  2. 2把这个 If 拖到「设定变量 Device Token」后面，并放在旧的 /api/capture 请求前面。
  3. 3点 If 第一格的蓝色变量，选择 Device Token。如果看不到，就点「选择变量」，再点上面那一步的 Device Token 魔法变量。
  4. 4点条件下拉，选择「没有任何值」。最后这一行应显示：如果 Device Token 没有任何值。
  5. 5在 If 里面添加「询问输入」，问题填“请输入 MonoSpend 配对码”。
  6. 6继续在 If 里面添加新的「获取 URL 内容」，URL 填 https://monospend.app/api/pair，方法改 POST，请求体改 JSON。
Ask for Input Pairing Code POST /api/pair

这个 pair 请求不能只是普通 URL。JSON 请求体里要有 pairingCode，值选择「请输入 MonoSpend 配对码」的输入结果；再加 deviceName，值可填 iPhone Shortcut。

05

从 pair 响应里取出 token 并保存

请求成功后，用「获取词典值」读取 token。先把这个 token 重新设为 Device Token，再用「存储文件」保存为 monospend-token.txt，允许覆盖。

  1. 1在 pair 请求后添加「获取词典值」。Key 填 token。
  2. 2立刻添加「设定变量」，把 Device Token 设为刚取出的 token 值。否则首次运行会保存成功，但本次 capture 仍然没有 token。
  3. 3添加「存储文件」，保存内容选择刚取出的 token 值，位置选 Shortcuts，子路径填 monospend-token.txt。
  4. 4打开“如果文件存在则覆盖”。
Get Dictionary Value token Save File

推荐顺序：获取 token 的值 -> 设定变量 Device Token -> 存储 token 到 monospend-token.txt -> 结束如果 -> 继续 capture。

06

把 capture 的 Authorization 改成变量

回到 /api/capture 的请求，把 Header 改为：Authorization: Bearer Device Token。这里的 Device Token 是变量，不是固定文本。

  1. 1在 capture 请求前添加 Text 动作。
  2. 2文本内容写 Bearer ，后面插入 Device Token 变量。
  3. 3把这个 Text 填到 Header 的 Authorization value。
Header Bearer + 变量 Device Token

建议用一个 Text 动作拼出：
Bearer [Device Token]
再把这个文本填到 Authorization。

07

保留听写或输入，把内容放进 transcript

旧快捷指令里如果已经有「听写文本」或「询问输入」，可以继续使用。只要把结果写到 JSON 的 transcript 字段；不要把 Shortcuts 文件夹、token 文件或 Device Token 放到这里。

  1. 1确认 capture 请求 Body 类型是 JSON。
  2. 2source 填 shortcut。
  3. 3transcript 选择听写或输入结果变量。
Dictate Text Ask for Input transcript

你的 capture 请求里，transcript 那一格应该选最上面的「听写文本」结果。测试句：
午饭 58，咖啡 22，打车 31

08

显示 confirmation，保留 correctionUrl

请求返回后，用「获取词典值」取 confirmation 并显示。需要改错账时，可以取 correctionUrl 并打开。

  1. 1添加「获取词典值」，Key 填 confirmation。
  2. 2添加「显示结果」，显示 confirmation。
  3. 3可选：再取 correctionUrl，需要纠错时打开 URL。
confirmation correctionUrl Show Result

成功后网页账本应出现多条 item。旧链接仍会跳到 /app?line=... 做纠错。

Exact Requests

两个请求照这个结构填

如果你只想核对字段，这一节最关键。配对请求只在首次运行时发生；日常记账请求每次运行都会发生。

First Run Only

配对请求：换取 device token

这个请求没有 Authorization。它只需要网页生成的一次性配对码。

URL https://monospend.app/api/pair
Method POST
Header Content-Type: application/json 
{
  "pairingCode": "网页显示的配对码",
  "deviceName": "iPhone Shortcut"
}

Every Capture

记账请求：写入一句话账单

这里必须使用本机保存的 device token。不要填共享生产 token。

URL https://monospend.app/api/capture
Method POST
Headers Content-Type + Authorization 
{
  "source": "shortcut",
  "transcript": "听写或输入结果",
  "clientRequestId": "shortcut-当前日期",
  "syncTargets": ["feishu", "notion", "google_sheets"]
}

Debug Notes

常见问题怎么判断

先用网页控制台确认配对码和设备列表，再回到 iPhone 调整快捷指令。多数问题都发生在 token 文件、Authorization 拼接或请求体 JSON。

返回 401

通常是 Authorization 没有拼成 Bearer DEVICE_TOKEN，或者设备在网页端已经被撤销。重新生成配对码并删除本机 token 文件再试。

首次运行没有进入配对

检查 monospend-token.txt 是否已经存在但内容为空或旧。删除文件后重新运行，应该询问配对码。

只生成一条 item

确认 transcript 是完整句子，例如「午饭 58，咖啡 22，打车 31」，不要只传了第一段文本。

分享安装包前不放心

在快捷指令里搜索 Bearer、token、Authorization。公开安装包里不应该出现真实 token 值。

Reset And Re-pair

想重新配对时，按这个顺序清理

如果你改到一半搞乱了，或者设备 token 已撤销，不需要重建整个快捷指令。清理本机 token 后重新跑首次配对即可。

On iPhone

删除本机 token 文件

打开「文件」App，进入 iCloud Drive 的 Shortcuts 文件夹，删除 monospend-token.txt。下一次运行快捷指令时，它应该重新询问配对码。

  1. 1打开「文件」App。
  2. 2进入 iCloud Drive / Shortcuts。
  3. 3删除 monospend-token.txt。

On Web

撤销旧设备并生成新配对码

打开 MonoSpend 工作台，撤销旧 iPhone 设备，再生成新的 iPhone 配对码。新配对码只有 10 分钟有效，并且只能用一次。

  1. 1打开 https://monospend.app/app 并登录。
  2. 2在「已连接设备」里撤销旧 iPhone。
  3. 3点击「生成 iPhone 配对码」。

Acceptance

改完后用这四项验收

验收通过后，这个快捷指令才适合继续复制成公开安装包或发给早期用户。

Security 安装包无真实 token

iCloud 分享链接里没有生产 token，也没有你的个人 device token。

Pairing 设备列表可见

首次运行输入配对码后，网页端能看到这台 iPhone Shortcut。

Capture 一句话拆多条

测试句能拆成 3 条账本 item，并显示 confirmation。

Revoke 撤销后失效

网页撤销设备后，这台手机旧 token 再请求 capture 应该失败。