# 99Pages Agentic OS — Portable
## 产品定义报告（PDR · 中文版）

| 项目 | 内容 |
| --- | --- |
| 产品 | **99Pages Agentic OS — Portable（便携版）** |
| 版本 | v0.3.0（工程版），目标 v1.0 正式发布 |
| 文档 | PDR.zh.md |
| 作者 | NG TICK KEE（吴德祺），99Pages |
| 状态 | 草案 — Windows 路径工程完成；macOS / Linux 实机验证 + Portal 端 SKU 接线待办 |
| 最后更新 | 2026-05-18 |
| 关联文档 | [PORTAL_INTEGRATION.md](./PORTAL_INTEGRATION.md)、[ARCHITECTURE.md](./ARCHITECTURE.md)、[README.md](./README.md) |

---

## 1. 产品概述

**Portable（便携版）** 是 99Pages Agentic OS 的 USB 闪存版本。客户收到一支
实体 USB，里面只有两个可见文件（启动器 + 加密包）。插入**任何 Windows、
macOS、Linux** 电脑，双击对应系统的启动器，整套 Agentic OS Core + 30 个
MCP 模块 + 17 项专家技能即从 USB 启动。所有记忆持久化在 USB 本身。拔出
USB → 主机上不留痕。代理可通过本地 CLI shell、内置 PWA WebApp（同局域网
可访问）、或配对的 Telegram bot 三个面向操作 — 三个面向共享同一份记忆。

一支 USB，三个操作系统，一份共享加密包。

### 一句话定位
*"AI 超级秘书装进一支 USB。Windows / Mac / Linux 任意插，拔出就走，
主机不留痕。"*

### 与其他 Agentic OS 版本的差异

| 版本 | 分发方式 | 多设备 | 价格 | 适合人群 |
| --- | --- | --- | --- | --- |
| **Core（按用量付费）** | 一行安装到 `~/.agentic-os/` | 支持（Workspace Seat） | USD $10 起充值 | 日常桌面用户，使用自有电脑 |
| **Portable** ← *本 PDR* | 实体 USB | 单设备 | **USD $198** 一次性（含 $100 credit） | 经常借用电脑的专业人士、BYO-机器场景、隔网办公室、热席工位的承包商 |
| Workforce 网关（API only） | 云端 SaaS | 不适用 | 按调用扣 credit | 在自家 app 里集成 API 的开发者 |

---

## 2. 痛点陈述

Core 版本未能完全解决的三个客户痛点：

1. **"我在别人的电脑上工作。"** 律师在客户办公室、顾问在共享 kiosk、
   销售在客户笔记本上。不能安装软件，不能留痕，但需要随时使用自己的
   AI 助理。
2. **"我在 Windows / Mac / Linux 之间切换。"** 用户家里 Mac、公司
   Windows、实验室 Linux。他们要的是**一个代理 + 一份记忆**，跟着人走。
   多设备云端方案（Core 路径）要求每台机器联网 + 付费；Portable
   解决"间歇联网 + 离线优先"的场景。
3. **"我不想装任何东西。"** 家庭用户、年长买家、被 `curl | bash`
   劝退的非技术用户。即插即用 USB 是全行业摩擦最低的安装方式 —
   人人都会。

Portable 用一个 SKU 同时回答这三个痛点。

---

## 3. 范围

### 3.1 v1.0 包含

- ✅ 单支 USB，硬件绑定（只能在那一支物理 USB 上跑）
- ✅ 三个宿主操作系统：Windows / macOS / Linux
- ✅ 五个架构 binary：`windows/amd64`、`darwin/{arm64,amd64}`、`linux/{amd64,arm64}`
- ✅ 防篡改 vault（AES-256-GCM、HKDF 派生密钥、USB 硬件序列号为锚）
- ✅ 真正的 Agentic OS Core CLI + 30 个 MCP 模块 + 17 项 DSL 技能
  （与按用量付费版本完全相同的模块集合）
- ✅ 记忆持久化在 USB 自身（`AGENTIC_OS_HOME =
  <USB_ROOT>/agentic-os-home`）— 拔出 USB 插到另一台电脑，昨天的
  journal 记录、library 文档、calendar 事件全部还在
- ✅ 本地 PWA WebApp 监听 `http://127.0.0.1:7799` + LAN 接口 — 用手机
  或同网任何浏览器都能驱动
- ✅ Telegram bot 集成（可选，通过 `$AGENTIC_OS_HOME/config/telegram.token`
  配置）
- ✅ USD $198 一次性 Stripe 结账，付款成功即为新账户预载 USD $100 credit
- ✅ 首次启动账户绑定流程（参见 [PORTAL_INTEGRATION.md](./PORTAL_INTEGRATION.md)）

### 3.2 v1.0 不包含

- ❌ 多设备云端 Workspace Seats（请用 Core 版本）
- ❌ Agent2Agent relay 协同（按设计，本产品为单设备）
- ❌ macOS 代码签名 + 公证（v1.1 — 用户首次右键打开绕过 Gatekeeper）
- ❌ 内核级文件复制阻断（filter driver）— v2.0 评估
- ❌ 用户可替换的产品密钥 / BYOK 签名（vault key 全产品统一）
- ❌ USB 丢失 / 损坏的自助置换（走人工支持流程：身份验证后解绑，
  按邮费补寄）

### 3.3 vault 明确排除的内容

按用户明确要求，vault 只装运行时必需的东西：

- **排除：** SDK / SDK_CONTRACT / PDR / Quickstart 等文档、README /
  CHANGELOG / 开发脚本、`*.go` 源代码、测试文件、`agentic-os-installer`
  （产品本身就是 bundle）、`agentic-workspace`（云端 workspace，
  Portable 用不上）、`demo-*` 演示 app、任何公司内部材料。
- **嵌入在各自模块 binary 内（通过 `//go:embed`）：** 17 个技能 DSL
  文件（在 `agentic-mcp-skills` 内）、wiki 文档（在 `agentic-mcp-wiki`
  内）、library-ui 静态资源（在 `agentic-mcp-library-ui` 内）。

---

## 4. 价格与套餐

### 4.1 价格

| 项目 | 金额 |
| --- | --- |
| 一次性购买价 | **USD $198.00** |
| 付款时载入的 Workforce credit | **USD $100.00** |
| 实体 USB + 绑定服务 + 全球运费的净成本 | USD $98.00（覆盖 BOM、履约、支持） |
| 订阅 | **无** |
| 自动续费 | **无** |
| 退款 | **无 — credit 不退款，USB 拆封后不接受退货。** Stripe 结账时已明确告知。 |

客户支付 $198 → 即时：
1. Stripe webhook → Portal API
2. 邮箱首次出现则自动创建账户（magic-link，无密码）
3. `gap_accounts.balance_usd += 100.00`（实际 Workforce 调用时扣减）
4. 生成单次使用 24 字符 base32 兑换码，存库 + 发邮件
5. 实体 USB 排入发货队列

### 4.2 BOM（物料清单）— 内部参考

| 项目 | 成本（美元） |
| --- | --- |
| SanDisk 同级 USB 3.0，8–16 GB，品牌套装 | ~$3 – $6 |
| 印刷说明卡 | ~$0.50 |
| 全球可追踪运费（均值） | ~$8 – $25 |
| 履约人工 | ~$2 |
| Portable 工程摊销（按 500 单批） | ~$15 |
| Workforce credit COGS（均值 80% × $100 面值 → ~$25 上游模型成本） | ~$25 |
| **总 COGS 估算** | **~$54 – $73** |
| 单位毛利 | **~63 – 73%** |

### 4.3 SKU 编码

`agentic-os-portable`（小写、连字符）。Stripe Product 的 metadata
必须携带 `sku: agentic-os-portable`，webhook 处理器据此分支。

### 4.4 销售渠道

- **主渠道（v1.0）：** 官网直销，`https://99pages.uk/portable` →
  Stripe Payment Link → magic-link 创建账户 + 寄送地址表单。
- **次渠道（v1.1+）：** 经销商批量 SKU（10 支套装约 $1,750 批发价，
  条款待定）。
- **v1.0 排除：** 各大电商平台（Amazon、Lazada）、企业采购、
  渠道伙伴。

---

## 5. 功能需求

### 5.1 首次使用体验

| 编号 | 需求 |
| --- | --- |
| F-1 | 用户将 USB 插入任意 Win / Mac / Linux 电脑。 |
| F-2 | 用户双击对应系统的启动器（`.exe` / `.command` / `.sh`）。 |
| F-3 | 启动器读取 USB 硬件 + 卷序列号，派生 AES 密钥，解密 vault，解压到临时目录。**时限：USB 2.0 ≤ 30 秒，USB 3.0 ≤ 10 秒。** |
| F-4 | 仅首次：启动器打开默认浏览器到 `https://app.99pages.uk/portable/redeem?usb=<hw>`，等待用户从邮件粘贴兑换码。Portal 绑定 USB ↔ 账户，返回签名 JWT，写入 USB 上的 `bind.json`。 |
| F-5 | 后续运行：启动器检测 `bind.json` 有效，跳过浏览器，直接启动 `portable-core`。 |
| F-6 | `portable-core` 打印 banner，显示本地 PWA URL + LAN IP + Telegram 注册提示，然后驻留。 |
| F-7 | 用户拔出 USB → 所有子进程在 3 秒内退出（`portable-core` 的 context 机制处理）。 |

### 5.2 运行时代理面向

| 面向 | 需求 |
| --- | --- |
| 本地 CLI | 不带 `-pwa-only` / `-telegram-only` 参数启动时，`portable-core` 提供交互 CLI shell。（v1.1 可接受延期 — v1.0 可只启动 PWA。） |
| PWA WebApp | 启动时绑定 `0.0.0.0:7799`。LAN 可访问。可安装到桌面（manifest + service worker）。 |
| Telegram bot | 仅当 `$AGENTIC_OS_HOME/config/telegram.token` 存在时启动（用户自配置）。使用用户自己的 BotFather token。聊天权限限定在 `bind.json.allowed_chat_ids`。 |

### 5.3 状态持久化

| 编号 | 需求 |
| --- | --- |
| F-8 | `AGENTIC_OS_HOME = <USB_ROOT>/agentic-os-home`。**不写主机 PC 路径。** |
| F-9 | 每个模块的 SQLite（`journal`、`library`、`keybox`、`calendar`、`project`、`people`、`briefingstore`、`rss` 等）都写在 `AGENTIC_OS_HOME` 下。 |
| F-10 | 将 USB 移到另一台电脑：所有 journal 记录、library 文档、calendar 事件、联系人全部可见。 |
| F-11 | 启动器在 `%TEMP%/$TMPDIR` 的临时解压目录在正常退出时尽力删除。强行断电时会泄漏（可接受；没有运行中的代理 + 用户账户绑定，泄漏内容无用）。 |

### 5.4 网络需求

| 编号 | 需求 |
| --- | --- |
| F-12 | 所有 LLM / vision / voice / TTS / image 调用走 Workforce 网关（Portable 不允许 BYOK）。需要联网。 |
| F-13 | 离线降级：本地模块（journal、library、calendar、project、people、workflow、fs、ssh、keybox、harness）无网络也能用。 |
| F-14 | Workforce 网关从绑定账户的 `balance_usd` 扣费。余额 < $1 时调用失败，返回可操作的错误信息 + 充值链接。 |

### 5.5 防复制

| 编号 | 需求 |
| --- | --- |
| F-15 | 复制 `99pages.vault` 到不同的 USB → 密钥派生失败 → 用户可见的错误提示重新激活流程。 |
| F-16 | 单独复制 `99pages-portable.exe`（或其他系统对应物）→ 无可用字节（启动器很小 + 没有 vault 没用）。 |
| F-17 | 格式化 USB 改变卷序列号 → vault 失效 → 用户须重新激活。 |
| F-18 | 诚实说明：技术高手可在启动器运行时从 RAM dump 解压后的 binary。**可接受** — Workforce 网关对每次调用都校验账户 + 余额，盗版 binary 跑起来也是返回错误。 |

---

## 6. 非功能需求

### 6.1 性能

| 指标 | 目标 | 说明 |
| --- | --- | --- |
| 冷启动（USB 2.0） | ≤ 30 秒 | vault 解密 + tar 解压是大头 |
| 冷启动（USB 3.0+） | ≤ 10 秒 | |
| PWA 首字节 | `portable-core` 启动后 ≤ 1 秒 | |
| 单个模块 spawn | ≤ 500 毫秒 | 模块都是小 Go binary |
| 闲置时内存 | ≤ 400 MB（portable-core + webapp 子进程） | |

### 6.2 安全

| 需求 | 规格 |
| --- | --- |
| Vault 机密性 | AES-256-GCM，每 vault 随机 12 字节 nonce + 16 字节 HKDF salt |
| Vault 完整性 | GCM 认证标签覆盖 manifest 和 body |
| 密钥绑定 | USB 硬件序列号（跨 OS 归一化）+ USB 卷序列号 + 产品密钥 + 单 vault salt → HKDF-SHA256 → AES-256 密钥 |
| 产品密钥轮换 | 新密钥仅作废**未来**的 vault；已发出的 USB 继续工作 |
| 路径遍历防护 | tar 解压器拒绝任何 clean 后为绝对路径或以 `..` 开头的条目 |
| 代码签名 | Windows：Authenticode（v1.1，有收入后） · macOS：Developer ID + 公证（v1.1） · Linux：无 |
| 网络 | Workforce 网关走 TLS 1.3，证书钉扎可选 |

### 6.3 可靠性

| 需求 | 规格 |
| --- | --- |
| USB 设备寿命 | 推荐 SLC/MLC 工业级闪存（3 年主流质保） |
| `portable-core` 子进程监督 | 子进程崩溃时指数回退重启（v1.1；v1.0 = 记日志 + 退出） |
| 首次绑定幂等 | 用相同参数重放 `POST /api/v1/portable/bind` 返回现有 JWT（200，而非 409） |

### 6.4 兼容性矩阵

| OS | 架构 | 状态 |
| --- | --- | --- |
| Windows 10/11 | amd64 | ✅ v0.3 实机验证 |
| Windows 10/11 | arm64 | ⏳ v1.1 |
| macOS 12+（Apple Silicon） | arm64 | ⏳ 代码完成，待硬件验证 |
| macOS 12+（Intel） | amd64 | ⏳ 代码完成，待硬件验证 |
| Linux（glibc 2.31+） | amd64 | ⏳ 代码完成，待硬件验证 |
| Linux | arm64（Raspberry Pi 4+） | ⏳ 代码完成，待硬件验证 |
| ChromeOS Crostini | amd64 | ⏳ 尽力支持，未测试 |

---

## 7. 架构概要

（完整细节：[ARCHITECTURE.md](./ARCHITECTURE.md)）

```
USB 根目录
├── 99pages-portable.exe              Windows 启动器
├── 99pages-portable.command          macOS 启动器（Terminal 包装）
├── 99pages-portable.sh               Linux 启动器（shell 包装）
├── 99pages.vault                     ≈ 450 MB AES-256-GCM 加密包
├── START_HERE.txt
├── bin/
│   ├── 99pages-portable.mac-arm64
│   ├── 99pages-portable.mac-x64
│   ├── 99pages-portable.linux-amd64
│   └── 99pages-portable.linux-arm64
└── agentic-os-home/                  首次运行创建；承载状态
    ├── journal.db
    ├── library.db
    ├── config/telegram.token         （可选，用户创建）
    └── bind.json                     （Portal 签发的设备 JWT）

99pages.vault 内部（解密后）：
bin/
├── windows-amd64/                    31 个 binary：portable-core + 30 个模块
├── darwin-arm64/                     31 个
├── darwin-amd64/                     31 个
├── linux-amd64/                      31 个
├── linux-arm64/                      31 个
└── registry.json
```

密钥派生：`K = HKDF-SHA256(normalise(hw_serial) || "|" ||
normalise(vol_serial), random_salt, product_secret || "|99pages.portable.v1")`

跨 OS 序列号归一化在 `internal/usbid/normalize.go`，让 Windows / macOS /
Linux 从同一支物理 USB 上派生出**相同**的密钥（即使三个 OS 报告的序列号
padding / 框架字符不一样）。

Manifest 的 `entry_by_os["<goos>/<goarch>"]` 映射 → 启动器从解压后的
`bin/<os>-<arch>/` 选对应的 `portable-core` binary 启动。

---

## 8. 用户旅程

### 8.1 购买

1. 用户在 `https://99pages.uk/portable` 看到营销页。
2. 点击 "Buy — USD $198" → Stripe Payment Link。
3. 输入邮箱 + 收件地址。付款。
4. 收到 2 封邮件：
   - **订单确认**，含 Workforce 账户 magic-link。
   - **发货通知**，含追踪号 + 预计到达日期。
5. 账户已经激活，含 USD $100 余额 — USB 未到货前用户已可登录
   `app.99pages.uk` 查看余额。

### 8.2 首次插入

1. USB 寄到。用户打开说明卡 → URL `99pages.uk/start`。
2. 插入 USB。双击对应系统的启动器。
3. 启动器解压约 10–30 秒。浏览器弹出
   `app.99pages.uk/portable/redeem`。
4. 用户从邮件粘贴 24 字符兑换码。Portal 绑定 + 返回 `bind.json`。
   浏览器显示："全部就绪 — 返回启动器。"
5. `portable-core` 启动。Banner 显示本地 + LAN PWA URL。
6. 用户在手机上打开 `http://<LAN-IP>:7799`。聊天可用。

### 8.3 日常使用

- 插 USB → 双击启动器 → 开始聊天 / 提问 / 语音指令。
- Telegram bot（如已配置）在 USB 拔出后能不能继续工作？**不能。**
  Telegram polling 跑在被启动的 `agentic-mcp-telegram-bot` 进程里；
  拔出 = 进程死。这是设计 — USB 就是设备的权威。

### 8.4 跨机器连续性

- 在家 Mac 上拔出 USB → 公司 Windows 上插入 → 昨天的 journal、
  library、对话、todos 全部还在。同一账户登录，同一密钥，不同 OS。

### 8.5 丢失 / 被盗

- 用户从任意机器登录 `app.99pages.uk`。
- Account → Devices → Portable USBs → 点 "Unbind"。
- 绑定 JWT 服务端失效。即使攻击者拿到 USB，Workforce 调用也会 401。
- 置换 USB：走支持流程，身份验证，客户出运费。

---

## 9. 分销与履约

### 9.1 生产

- **v1.0（首 100 支）：** NG TICK KEE 在吉隆坡用主镜像手动烧录。
  每支按自身的 USB 序列号单独激活 — 烧录步骤是
  `deploy-to-d -modules-repo ... -target <usb-root>`，需要插着那支
  特定的 USB。
- **v1.1（100–1000 支）：** 外包烧录 + 贴标给马来西亚 USB 履约伙伴
  （TBD）。主镜像不能预烧 — 每个 vault 绑定到特定 USB 硬件序列号，
  伙伴需要 build 管线。
- **v2.0：** 重新评估。选项：发空白 USB + 独立的"激活"工具，用一次性
  voucher；或接受单支烧录成本。

### 9.2 物流

- 全球可追踪运输：Pos Malaysia / DHL eCommerce / 类似。
- 通常 5–15 个工作日。
- 马来西亚境内客户不另付运费；国际运费已包含在 $198 出口价
  ex-MYS，偏远区域调整待定。

### 9.3 支持

- 邮箱：`dicky@pbcap.org`
- 知识库：`app.99pages.uk` → 帮助板块（待建）
- 一线问题：vault 解不开（90% 是用户插错 USB）；启动器跑不起来
  （Gatekeeper / SmartScreen 的首次运行警告）。

---

## 10. 成功指标

### 10.1 上线 90 天

| KPI | 目标 |
| --- | --- |
| 出货数 | 50 |
| 退款 / chargeback 率 | < 2% |
| 首周激活率（USB 已绑定账户） | > 80% |
| 30 天复购率（credit 用完后充值） | > 30% |
| 每支 USB 支持工单数 | < 0.4 |

### 10.2 稳态（第一年）

| KPI | 目标 |
| --- | --- |
| 出货数 / 月 | 30+ |
| Portable 用户平均收入（含充值） | $260 / 12 个月 |
| 毛利 | ≥ 65% |
| NPS | ≥ 50 |

---

## 11. 路线图

| 版本 | 范围 | 预期 |
| --- | --- | --- |
| v0.3.0 | 跨平台启动器 + 跨编译管线 + 真正的 Core + 30 模块入 vault。**Windows 工程完成。** | ✅ 2026-05-18 |
| v0.4.0 | macOS + Linux 实机验证。首次浏览器兑换流程 + `bind.json`。 | 2026-05-25 |
| v0.5.0 | Portal `agentic-os-portable` SKU 上线，$198 Stripe 结账 + $100 自动 credit + 绑定 endpoint。 | 2026-06-01 |
| v1.0 GA | 首 100 支 USB 烧录 + 发货。`99pages.uk/portable` 营销页上线。 | 2026-06-15 |
| v1.1 | Windows Authenticode + macOS 公证。Telegram 跨启动器重启的持久化。批量 SKU。 | 2026-07 |
| v2.0 | 硬件 dongle 选项（单独 Enterprise SKU $498，含加密芯片 — 防 RAM-dump）。 | 2026-Q4 |

---

## 12. 风险与开放问题

| # | 风险 | 缓解 |
| --- | --- | --- |
| R-1 | macOS Gatekeeper 阻止未签名 `.command` 首次运行 | 在说明卡里写明右键打开流程。$198×500 = $99k 营收能覆盖每年 $99 Apple Developer 费时，v1.1 加公证。 |
| R-2 | Linux 发行版没有 `udevadm` | `usbid_linux.go` 已有 `lsblk` 后备。在 Alpine / busybox-init 上测试。 |
| R-3 | USB 硬件序列号冲突（部分山寨 USB 报告全 0） | `deploy-to-d` 时拒绝 `NormalizeHW(hw) == "0"` 的 USB。文档说明支持的品牌。 |
| R-4 | 在 `agentic-os-home` 写入时热插拔导致 exFAT 损坏 | SQLite 用 WAL + `synchronous=NORMAL`、`journal_mode=WAL`。文档说明局限。 |
| R-5 | 客户 USB 丢失 / 被盗 | Console 自助解绑；按运费售置换 SKU。 |
| R-6 | 单支手动烧录超不过 200 支 / 月 | v1.1 走履约伙伴流程。 |
| R-7 | 启动器 binary 逆向工程泄漏产品密钥 | 接受：产品密钥是三因素之一。没有匹配的 USB 序列号 + 用户账户绑定，单独密钥泄漏无效。v2.0 用新启动器轮换。 |

### 开放问题

- Q-1：Portable 用户是否享有**多 USB 折扣**（家里一支、办公室一支）？
  v1.0 不做。
- Q-2：是否做**可转让**流程（赠送 / 转售 Portable USB）？v1.0 不做
  （账户绑定）。
- Q-3：品牌套装 / 包装设计 — 外包给设计师 还是 in-house Vibe Coding？
  待定。

---

## 13. 签批

| 角色 | 姓名 | 签批 |
| --- | --- | --- |
| 产品负责人 | NG TICK KEE | — |
| 工程 | NG TICK KEE / Claude | v0.3.0 ✅ |
| 运营 / 履约 | NG TICK KEE | — |

---

*© 2026 99Pages. 保密及专有。仅限内部团队和授权伙伴传阅。*