開放的套件生態：沒有官方套件，只有你選擇信任的發佈者。

Principles

每個套件都是第三方套件

Shinsou X 不內建、不審核、也不替任何套件背書，包含專案作者自己維護的套件。App 內沒有任何依套件名稱、網址或雜湊值例外放行的清單；安全性來自沙箱隔離、最小權限與使用者逐項授權，而不是來自誰發佈。

How it works

從儲存庫到閱讀器

儲存庫只是一組靜態檔案，不是內容託管服務。App 負責驗證、授權、網路、敏感資料與閱讀；套件只負責和來源網站溝通，回傳作品、章節與內容。

Repositories

加入儲存庫並確認發佈者

任何發佈者都可以提供自己的儲存庫。加入時 App 會顯示發佈者自稱的名稱（標示為未驗證）與金鑰指紋，請和發佈者在自己網站公布的完整指紋比對。

複製shinsou://add-repository?url=https://you.github.io/plugins&fp=sha256:<full-fingerprint>

Permissions

宣告要求，不等於取得權限

有效權限 = 套件宣告（索引、sidecar、腳本三方一致）∩ App 支援 ∩ 沙箱上限 ∩ 你對這個確切版本的授權。沙箱上限是 App 常數，套件與使用者都無法提高。

Updates & revocation

更新、撤回與金鑰事件

Sandbox

所有平台都在沙箱中執行

平台沒有可用的沙箱時一律拒絕執行，不會退回 App 內的引擎。每個套件有自己的記憶體、時間與 bridge 呼叫上限，超限以穩定錯誤碼失敗，不回傳部分結果。

Content contract

漫畫、小說，也可以在同一個套件

一個套件可以混合多個來源，每個來源各自宣告內容種類；App 依確切的 sourceId 選擇來源，不依陣列順序。sourceId 一經發佈就不能更改，書庫、閱讀進度與登入都以它綁定。

Data boundary

備份帶走儲存庫清單，不帶走套件與秘密

For developers

開發指引：從金鑰到使用者安裝

套件是一支 JavaScript 腳本加上一份宣告檔。儲存庫是靜態檔案，可以放在 GitHub Pages、raw GitHub 或任何靜態主機，不需要伺服器，也不需要任何人核准上架。

複製keygen → init → build → lint → test → serve (developer mode) → sign → publish
then:  bump versionCode → build / lint / test → sign
       refresh (scheduled) / revoke / rotate / revoke-key

1. 安裝 CLI

需要 Node.js 20 以上。CLI 尚未發佈到 npm，請從 GitHub 安裝：

複製npm install --global github:aluo96078/shinsou-plugin-cli
shinsou-plugin help

2. 產生發佈者金鑰

複製shinsou-plugin keygen --name mykey --passphrase
shinsou-plugin fingerprint --key mykey

3. 建立專案

複製shinsou-plugin init my-plugin --template manga --id zh.example --name "Example" --lang zh

4. 撰寫宣告檔

shinsou.plugin.json 是唯一的事實來源，索引、sidecar 與腳本內的宣告都由它產生。只宣告真正用到的能力、權限與網站。

複製{
  "manifestVersion": 1,
  "packageId": "zh.example",
  "name": "Example",
  "version": "1.0.0",
  "versionCode": 1,
  "lang": "zh",
  "contract": "shinsou",
  "runtime": "legacy-shinsou-adapter-v2",
  "contentType": "manga",
  "contentKinds": ["IMAGE_SEQUENCE"],
  "capabilities": ["CATALOGUE", "LATEST", "BROWSE", "METADATA", "UNITS", "CONTENT", "SEARCH"],
  "runtimePermissions": ["EXECUTE_SCRIPT", "NETWORK"],
  "requestedHostPermissions": [],
  "systemEvents": { "required": [], "optional": [] },
  "entry": "src/index.js",
  "sources": [{
    "sourceId": "1234567890123456789",
    "name": "Example",
    "lang": "zh",
    "baseUrl": "https://example.com",
    "requestOrigins": ["https://example.com"],
    "credentialOrigins": [],
    "contentOrigins": ["https://img.example.com"],
    "browserSessionOrigins": [],
    "contentHostSuffixes": []
  }],
  "repository": {
    "name": "My Plugins",
    "website": "https://github.com/you/plugins",
    "mirrors": ["https://you.github.io/plugins"]
  }
}

Script API

腳本結構與可呼叫的 bridge

腳本是 classic script，進入點在頂層宣告 source 物件（多來源用 sources 陣列）；build 會把 import 打包成單一檔案。Hook 可以回傳 Promise。

複製var source = {
  baseUrl: "https://example.com",
  supportsLatest: true,

  getPopularManga: function (page) {
    var doc = Jsoup.parse(bridge.httpGet(this.baseUrl + "/popular?page=" + (page + 1)), this.baseUrl);
    var list = doc.select(".item").map(function (el) {
      var m = SManga.create();
      m.url = el.selectFirst("a").attr("href");
      m.title = el.selectFirst(".title").text();
      m.thumbnail_url = el.selectFirst("img").absUrl("src");
      return m;
    });
    return new MangasPage(list, list.length > 0);
  },

  getChapterList: function (manga) { /* return SChapter[] */ },
  getPageList: function (chapter) { /* return [new Page(0, "", imageUrl), ...] */ }
};

Build、lint 與 test

複製shinsou-plugin build          # bundle, digest, index + sidecar; verifies all three agree
shinsou-plugin lint           # undeclared bridge calls, non-HTTPS origins, misleading names
shinsou-plugin test           # replay recorded HTTP fixtures in a QuickJS sandbox
shinsou-plugin test --record  # record missing fixtures from the live site

在 App 上試用：開發者模式

在 App 的「套件安全」開啟開發者模式，就能載入未簽章的開發儲存庫。手機測試時，在開發伺服器位址填入電腦的私有區網 IPv4 位址。

複製shinsou-plugin serve              # http://127.0.0.1:8787
shinsou-plugin serve --host lan   # private LAN IPv4, prints a shinsou:// link and QR code

Sign & publish

簽章並發佈到靜態主機

複製shinsou-plugin sign --key mykey --mirror https://you.github.io/plugins

repo.json
index.json
sidecars/<packageId>.json
plugins/<packageId>.js
publisher-revocations.json
publisher-key-rotation.json   (after rotate)
publisher-key-revoked.json    (after revoke-key)

Maintenance

維護你的發佈

複製shinsou-plugin refresh --key mykey                  # renew the revocation list
shinsou-plugin revoke <sha256> --key mykey           # pull a bad version
shinsou-plugin rotate --key mykey --to newkey        # rotate keys, users keep trust
shinsou-plugin revoke-key --key mykey                # leaked key: disable everything it signed

GitHub Actions

用 GitHub Actions 自動簽章

把金鑰放進儲存庫的 secrets 後，GitHub Actions 可以在你推送程式碼時自動檢查、簽章並發佈，也能定期續簽撤回清單，不必每次在自己電腦上手動執行。

1. 把 CLI 依賴固定到 GitHub 版本

init 產生的 package.json 依賴的 CLI 版本尚未發佈到 npm，Actions 執行 npm ci 時會失敗。請改成固定的 GitHub commit：

複製npm install --save-dev github:aluo96078/shinsou-plugin-cli#<commit>

2. 設定 secrets

在 GitHub 儲存庫的 Settings → Secrets and variables → Actions 新增兩個 secret，或使用 GitHub CLI：

複製gh secret set SHINSOU_PLUGIN_KEY < ~/.config/shinsou-plugin/keys/mykey.json
gh secret set SHINSOU_PLUGIN_PASSPHRASE

3. 推送時自動簽章並部署

以下範例在原始碼改變時檢查並簽章、每週在撤回清單剩不到一半效期時續簽，最後把簽好的鏡像目錄部署到 GitHub Pages。請在 Settings → Pages 把來源設為 GitHub Actions，並把 SITE_DIR 換成 sign 輸出的鏡像目錄。

複製# .github/workflows/shinsou-sign.yml
name: Sign and publish

on:
  push:
    branches: [main]
    paths: ["src/**", "test/**", "shinsou.plugin.json"]
  schedule:
    - cron: "17 3 * * 1" # every Monday 03:17 UTC
  workflow_dispatch:

permissions:
  contents: write
  pages: write
  id-token: write

concurrency:
  group: shinsou-sign
  cancel-in-progress: false

env:
  SITE_DIR: public/you.github.io_plugins # the mirror directory written by sign

jobs:
  sign:
    runs-on: ubuntu-latest
    environment: github-pages
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - run: npx shinsou-plugin lint
      - run: npx shinsou-plugin test

      - name: Sign
        if: github.event_name != 'schedule'
        env:
          SHINSOU_PLUGIN_KEY: ${{ secrets.SHINSOU_PLUGIN_KEY }}
          SHINSOU_PLUGIN_PASSPHRASE: ${{ secrets.SHINSOU_PLUGIN_PASSPHRASE }}
        run: npx shinsou-plugin sign --key "$(node -p 'JSON.parse(process.env.SHINSOU_PLUGIN_KEY).name')"

      - name: Renew the revocation list when due
        env:
          SHINSOU_PLUGIN_KEY: ${{ secrets.SHINSOU_PLUGIN_KEY }}
          SHINSOU_PLUGIN_PASSPHRASE: ${{ secrets.SHINSOU_PLUGIN_PASSPHRASE }}
        run: npx shinsou-plugin refresh --if-due --key "$(node -p 'JSON.parse(process.env.SHINSOU_PLUGIN_KEY).name')"

      - name: Commit signatures and sequence numbers
        run: |
          git config user.name "shinsou-sign"
          git config user.email "[email protected]"
          git add .shinsou/state.json public
          git diff --cached --quiet || { git commit -m "chore: sign repository"; git push; }

      - uses: actions/upload-pages-artifact@v3
        with:
          path: ${{ env.SITE_DIR }}
      - uses: actions/deploy-pages@v4

AI Skill

讓 AI 開發助手協助撰寫套件

shinsou-extension-creator 是給 AI 開發助手使用的工作指南，協助建立、遷移或修復套件：保持穩定的來源身分、如實宣告內容、最小化權限，並讓腳本、sidecar 與索引一致。它不是 App 內的套件，也不會替你簽章或發佈。

FAQ

套件常見問題