# 使用 AI 接入 Licentivo Launch

> 當前未發布改動采用帳號身份交換，具體職責和遷移約束見 [購買期限與帳號 SDK 邊界](/zh-hant/launch-documents/account-purchase-boundary/)。Launch 計算購買期限；Licentivo SDK 執行授權。

Launch 后臺的 **運營工具 → AI 快速接入** 會生成一份可交給 AI 編程工具的英文任務說明。它使用當前商店、已有軟體和已發布套餐的真實公開配置，并要求 AI 安裝公開的 Launch 客戶端包、調用真實 API、把權限檢查放到業務操作中，再完成接入測試。

程序接入頁的 **接入檢查與代碼 / AI 快速接入** 導航也可進入同一功能。手動開發不需要使用 AI，可直接閱讀 [九種語言手動接入指南](/zh-hant/launch-documents/manual-integration/)。

## 生成前準備

1. 在 Launch 中創建軟體和銷售套餐，并把套餐關聯到 Licentivo 產品與授權策略。
2. 將套餐發布到要測試的 `sandbox` 或 `live` 環境。
3. 確認 Launch 的公開地址可被客戶軟體訪問，正式環境使用 HTTPS。
4. 在 **程序接入 → 接入檢查與代碼** 讀取產品資訊，確認產品映射和簽名公鑰通過檢查。
5. 明確要保護的真實業務動作，例如 `export`、`save` 或 `render`，不要只寫“整個軟體”。

沒有完成產品配置時可以生成草稿，但草稿會明確標出待填寫項，不能作為可交付接入配置。完成產品與環境配置后應重新生成。

## 在后臺生成提示詞

1. 選擇 Go、Python、C#、Java、JavaScript / Node.js、Rust、Ruby、C 或 C++。Web 后端方案使用 Go，不另算一種 SDK 語言。
2. 選擇 Windows、Linux、macOS 或適用平臺，以及桌面、Web 后端或后臺服務項目。
3. 使用英文填寫已有項目結構、啟動方式、界面框架和要保護的業務功能。不要填寫密碼、密鑰、客戶資料或私有源碼。
4. 選擇已有軟體和 `sandbox` / `live` 環境。Launch 自動讀取當前商店地址、Launch 與 Licentivo 的產品映射、環境和簽名公鑰。
5. 檢查預覽中的包版本、安裝命令、文件鏈接和已填寫連接函數，然后復制或下載提示詞。
6. 把提示詞交給自己的 AI 編程工具，讓它在你的工程中完成修改、編譯和本地測試。

Launch 只在瀏覽器中生成文本。它不會自動連接任何 AI 服務，不會上傳項目，也不會代替開發者執行生成的程序。

## 提示詞會告訴 AI 在哪里下載 SDK

當前 0.1.6 的九種語言公開安裝驗證已全部通過（9/9），下列注冊表命令和原生下載均已驗證。Java 的 Maven Central 文件及四份簽名、Rust 的 crates.io 精確版本和全部后臺生成的初始化代碼也已完成獨立消費者檢查；[v0.1.6 GitHub Release](https://github.com/spf86/licentivo-launch-sdk/releases/tag/v0.1.6) 同時提供原生包和離線文件。

生成的提示詞必須包含與所選語言對應的、固定版本的公開安裝方式：

```text
Go:         go get github.com/spf86/licentivo-launch-sdk/pkg/launchclient@v0.1.6
Python:     python -m pip install licentivo-launch==0.1.6
C# / .NET: dotnet add package Licentivo.Launch --version 0.1.6
Java:       com.licentivo.launch:launch-client:0.1.6
Node.js:    npm install @licentivo/launch@0.1.6
Rust:       cargo add licentivo-launch@=0.1.6
Ruby:       gem install licentivo-launch --version 0.1.6
C / C++:    https://github.com/spf86/licentivo-launch-sdk/releases/tag/v0.1.6
```

公開源碼、各語言 README 和當前發布狀態位于：

- [Licentivo Launch SDK 倉庫](https://github.com/spf86/licentivo-launch-sdk)
- [v0.1.6 GitHub 發布版本](https://github.com/spf86/licentivo-launch-sdk/releases/tag/v0.1.6)
- [九種語言公開安裝驗證](https://github.com/spf86/licentivo-launch-sdk/blob/main/docs/registry-verification.json)
- [版本與包說明](/zh-hant/launch-documents/integration-packages/)
- [九種語言手動接入指南](/zh-hant/launch-documents/manual-integration/)
- [應用接入架構與安全要求](/zh-hant/launch-documents/software-sdk-integration/)
- [接入驗收清單](/zh-hant/launch-documents/acceptance/)

只安裝所選語言的 Launch 包。v0.1.6 已內置官方 Licentivo SDK v0.11.6、預設適配器和鏈接配置，不再單獨安裝第二份官方 SDK。

## 提示詞會告訴 AI 如何接入

已配置的提示詞包含后臺生成的連接函數。該函數已經填入商店公開地址、Launch 產品與 Licentivo 產品映射、簽名公鑰和支付環境。AI 不需要猜測或手填兩個內部產品編號，也不需要創建 `launch-config.json` 或 `product.json`。

服務端的私有 `config.yaml` 只用于運行 Launch 網站，絕不能放進客戶應用、提示詞或安裝包。

AI 必須按以下生命周期修改客戶軟體：

```text
Connect/connect → Login or Restore → RunFeature → Logout / Close
                                      └──────────→ ReleaseDevice (explicit device unlink only)
```

- `Connect/connect` 創建 Launch 客戶端，并初始化內置官方 SDK；它本身不代表帳號已經登錄或功能已經授權。
- `Login` 使用客戶在當前商店注冊的郵箱和密碼取得該帳號的產品憑據。
- `Restore` 從安全存儲恢復已記住的會話；沒有會話時顯示登錄，明確拒絕不能當作離線成功。
- `RunFeature` 必須包住導出、保存、渲染或后臺任務等真實業務動作。只禁用按鈕不能替代執行位置的檢查。
- `Logout` 先調用官方 SDK 統一退出，再清理帳號會話；`ReleaseDevice` 是同一明確退出流程的兼容入口。`Close` 普通關閉保留設備綁定。
- 客戶端對象應在應用運行期間保持存活，以便 SDK 執行心跳、浮動席位和運行時規則。

Web 應用只在可信后端執行授權檢查。Node.js / Electron 將憑據和 SDK 放在主進程或服務端，瀏覽器與渲染進程不保存授權秘密。

## AI 應交付什么

提示詞要求 AI 完成并報告以下內容：

1. 檢查現有項目的語言版本、依賴管理、啟動與退出流程，以及需要保護的真實業務操作。
2. 使用上面的固定版本命令安裝一個 Launch 包，并核對對應語言 README 中的真實接口。
3. 加入客戶帳號登錄、錯誤提示和安全會話恢復，不在源碼或日志中保存密碼和完整許可證。
4. 使用后臺提供的連接函數初始化，不自行發明產品編號、簽名公鑰或配置文件。
5. 在每個受保護業務動作的執行位置使用 `RunFeature` 或對應語言方法，并正確處理計次與重試。
6. 區分帳號失敗、郵箱待驗證、權益同步中、未購買、到期、暫停、設備已滿、網路故障和離線到期。
7. 實現普通關閉、帳號退出和明確設備釋放，并按商店、帳號、產品和環境隔離快取。
8. 運行適合該項目的編譯與測試，最后列出修改文件、功能映射、實際結果和客戶驗收步驟。

AI 輸出代碼后，開發者仍需核對功能名與 Licentivo 策略完全一致，并在真實的 sandbox 商店帳號上完成端到端測試。

## 不納入提示詞的內容

提示詞只包含可公開的商店來源、產品映射、環境、包版本和簽名公鑰。以下內容不得進入提示詞：

- 客戶郵箱、密碼、登錄會話和刷新令牌；
- 完整許可證、設備憑據和本地授權快取；
- Licentivo 管理 API Key；
- Stripe、PayPal、Waffo 或 Paddle 密鑰；
- 資料庫連接、`master_key` 和服務端 `config.yaml`；
- 不需要交給外部工具的私有源碼、業務資料或日志。

Launch 的公開配置檢查、AI 草稿和本地編譯都不能證明真實支付、許可證簽發或外部激活已經成功。支付沙箱、商店帳號和 Licentivo 環境需單獨驗收。

## 接入后的驗收清單

- 新客戶能夠登錄，未驗證郵箱與錯誤密碼得到明確但不過度泄露資訊的提示。
- 已購買帳號可以運行目標功能；未購買、到期或暫停帳號無法執行同一業務代碼。
- 重啟后只有成功恢復會話并通過授權檢查時才能繼續使用。
- 有效離線策略可以工作，離線許可到期后拒絕；明確的 401/403/404 不降級為離線成功。
- 功能次數只在業務成功時正確提交，失敗與重試不會重復扣減。
- 普通關閉保留設備綁定；明確退出先調用官方 SDK 統一退出，保留待撤銷日志并報告真實結果。
- 浮動席位心跳在應用運行時持續，非正常退出后的回收時間符合當前授權策略。
- 切換商店、帳號、產品或環境不會復用另一身份的快取。

更完整的自動與外部驗收邊界見 [acceptance.md](/zh-hant/launch-documents/acceptance/)。

## 在源碼分發包中使用提示詞生成器

`licentivo-launch-0.1.6-source.zip` 保留下列文件，便于在自己的工具中生成相同結構的提示詞：

- `internal/httpapi/web/integration-prompts.js`：不依賴頁面或服務端的提示詞生成模塊；
- `scripts/integration-prompts.test.mjs`：本地 Node 測試；
- `internal/httpapi/web/integration-state.js` 與 `scripts/integration-state.test.mjs`：配置草稿隔離和舊驗證結果清理；
- 本指南、各語言接入包、示例和驗收說明。

模塊導出 `integrationTargets` 與 `buildIntegrationPrompt(options)`。選項包括 `language`、`appKind`、`platform`、`projectNotes`、`feature`、`merchantOrigin`、`environment` 和已驗證的 `report`，返回 `{ text, ready, title, code }`。不提供 `report` 時只生成草稿；不能通過手工篡改報告繞過公開配置檢查。

在支持 ES 模塊的開發工具中可以從源碼包根目錄生成本地草稿：

```powershell
@'
import { readFile, writeFile } from 'node:fs/promises';
const source = await readFile('internal/httpapi/web/integration-prompts.js', 'utf8');
const { buildIntegrationPrompt } = await import(
  'data:text/javascript;base64,' + Buffer.from(source).toString('base64')
);
const prompt = buildIntegrationPrompt({
  language: 'python',
  appKind: 'desktop',
  platform: 'windows',
  projectNotes: 'Existing Python desktop application. Add account sign-in and protect report exports.',
  feature: 'export'
});
await writeFile('integration-prompt.md', prompt.text, 'utf8');
console.log(prompt.title);
'@ | node --input-type=module
```

這個命令只生成未配置草稿，不調用 AI 或授權服務。真實接入應回到自己的 Launch 實例，選擇已有軟體和環境重新生成帶公開配置的版本。

驗證本地生成器：

```powershell
node --test scripts/integration-prompts.test.mjs scripts/integration-state.test.mjs
```