1. Docs
  2. Plugin development guide

Plugin development guide

Build a same-page interface with an optional local Node backend. The plugin API is experimental and may change.

First manifest

Save this as manifest.json and add ui.mjs. Import the folder in Settings → Plugins, review the code and initial locations, then choose Trust, install and enable. Install only keeps it disabled; the global switch and safe mode still apply.

{"tmApi":1,"id":"my-panel","name":"My panel","version":"1.0.0","ui":"ui.mjs","files":["ui.mjs"],"views":[{"id":"panel","title":"My panel","surfaces":["home","page"],"defaultSurfaces":["page"]}]}

Optional defaultSurfaces suggests initial locations. Confirm or change them at installation; install-only defers them until first enable. Updates preserve your choices. Full locations are skipped, and surface master switches stay unchanged.

export function activate(ctx) {
  return {
    mount(container, context) {
      const contextLabel = document.createElement('p');
      container.append(contextLabel);
      function update(next) {
        contextLabel.textContent = `My view: ${next.period || next.surface}`;
      }
      update(context);
      return { update, dispose() { contextLabel.remove(); } };
    }
  };
}

Same-page interface

Author modules use DOM/CSS/JS inside the host renderer. Bundle your CSS and use native content nodes or helpers where available. The UI has no Node integration.

Data and settings

Use ctx.data.query inside an async mount or handler to read captured App data; no backend is needed. The host supplies query version 1. Handle unavailable/stale results and unknown cost rather than turning them into zero.

A single query returns a snapshot and has no reset callback. Do not retain its data across source or privacy changes. For a persistent display, use the complete subscription example, which handles resets and cleanup.

Use the complete live UI example for subscriptions and cleanup, and the copyable settings schema and save example for the native form or a custom editor. Release subscriptions on disposal, discard old cursors on source/privacy resets, and reload deliberately after save conflicts.

For files, network or computation, declare an optional Node backend. It has the OS user’s authority and is shared across windows and locations. Honor hidden/visible state; background execution requires a separate explicit choice.

Test and distribute

Build dependencies first; installation never runs npm scripts. Follow the author self-check for the features you ship and test the exact package in a disposable profile. The host platform acceptance matrix is for maintainers, not a prerequisite for your first plugin.

Follow the publishing guide and README template for compatibility, access disclosures, screenshots and release steps. Use file/folder import or a direct HTTPS catalog; in-app GitHub discovery is not yet available. Rollback restores code, not arbitrary data migrations.

Trust before enabling

Plugins can read local files and credentials, use the network, change data or freeze the interface. Enable only code you trust. A hash is not a security audit.

Plugin API · UI · Packages · Create and sign a catalog

AI

Copy this prompt, add your idea, and give it to your coding assistant.

Prompt
Help me build a Token Monitor plugin. Read the official guide: https://github.com/Javis603/token-monitor/blob/main/docs/plugins/author-quickstart.md (and the reference it links to).

If any requirements are unclear, please ask me first. When finished, test the plugin and provide a folder or .tmplugin file I can import, along with installation and activation steps.

My idea:

外掛開發指南

以同頁介面配合選用的本機 Node 後端。外掛 API 屬實驗性，日後可能變更。

第一份宣告檔

儲存為 manifest.json 並新增 ui.mjs。匯入資料夾、確認首次顯示位置，再信任並啟用。

{"tmApi":1,"id":"my-panel","name":"My panel","version":"1.0.0","ui":"ui.mjs","files":["ui.mjs"],"views":[{"id":"panel","title":"My panel","surfaces":["home","page"],"defaultSurfaces":["page"]}]}

defaultSurfaces 可建議首次顯示位置。安裝時可確認或修改；只安裝會留待首次啟用才套用。更新保留用戶選擇，位置已滿會略過，亦不會更改顯示區域的總開關。

export function activate(ctx) {
  return {
    mount(container, context) {
      const contextLabel = document.createElement('p');
      container.append(contextLabel);
      function update(next) {
        contextLabel.textContent = `My view: ${next.period || next.surface}`;
      }
      update(context);
      return { update, dispose() { contextLabel.remove(); } };
    }
  };
}

同頁介面

作者可在宿主 renderer 以 DOM／CSS／JS 設計介面。請將 CSS 打包，並按需要使用原生內容節點或 helpers。UI 沒有 Node 整合。

資料與設定

在非同步 mount 或事件處理函式內使用 ctx.data.query 讀取 App 已收集的資料，毋須後端。宿主會補上 query version 1。處理不可用、過期與未知費用，勿當成零。

單次 query 回傳當下快照，沒有 reset 通知；不要跨來源或隱私變更保留資料。需要持續顯示時，請使用處理 reset 與清理的完整訂閱範例。

參閱完整即時 UI 範例的訂閱與清理方式，以及可複製的設定 schema 與儲存範例。卸載時解除訂閱；來源／隱私重設時丟棄舊 cursor；儲存衝突後由使用者決定重新載入，勿直接覆寫。

需要檔案、網絡或運算時才加入選用 Node 後端。它具有作業系統使用者權限，並在多窗口與顯示位置之間共享。遵守可見／隱藏狀態；背景執行需要另外明確啟用。

測試與發佈

先打包依賴；安裝不會執行 npm scripts。按所提供功能完成作者自測，並在拋棄式設定檔測試實際發布套件。宿主平台驗收矩陣供維護者使用，並非製作第一個外掛的前提。

按發佈指南與 README 範本說明相容性、存取權限、圖片及發布步驟。目前使用檔案／資料夾匯入或直接 HTTPS 目錄；App 內的 GitHub 探索功能尚未開放。回滾只還原程式碼，不會逆轉任意資料遷移。

信任後才啟用

外掛可能讀取本機檔案與憑證、連線、更改資料或令介面停止回應。只啟用你信任的程式碼；雜湊不代表安全審核。

外掛 API · UI · Packages · 建立及簽署目錄

AI

複製以下提示詞，補上你的想法，再交給編程助手。

提示詞
幫我製作一個 Token Monitor 外掛。請閱讀官方指南：https://github.com/Javis603/token-monitor/blob/main/docs/plugins/author-quickstart.md（以及其中連結的參考文件）。

如果需求有不清楚的地方，請先向我確認。完成後，請測試外掛，並提供可匯入的資料夾或 .tmplugin 檔案，以及安裝與啟用步驟。

我的想法：

插件开发指南

同页界面配合可选的本机 Node 后端。插件 API 为实验性，今后可能变更。

首个声明文件

保存为 manifest.json 并创建 ui.mjs。导入文件夹、确认首次显示位置，再信任并启用。

{"tmApi":1,"id":"my-panel","name":"My panel","version":"1.0.0","ui":"ui.mjs","files":["ui.mjs"],"views":[{"id":"panel","title":"My panel","surfaces":["home","page"],"defaultSurfaces":["page"]}]}

defaultSurfaces 可建议首次显示位置。安装时可以确认或修改；只安装会留待首次启用才应用。更新保留用户选择，位置已满会跳过，也不会更改显示区域的总开关。

export function activate(ctx) {
  return {
    mount(container, context) {
      const contextLabel = document.createElement('p');
      container.append(contextLabel);
      function update(next) {
        contextLabel.textContent = `My view: ${next.period || next.surface}`;
      }
      update(context);
      return { update, dispose() { contextLabel.remove(); } };
    }
  };
}

同页界面

作者可在宿主 renderer 中使用 DOM／CSS／JS 设计界面。请打包 CSS，并按需使用原生内容节点或 helpers。UI 没有 Node 集成。

数据与设置

在异步 mount 或事件处理函数内使用 ctx.data.query 读取 App 已收集的数据，无需后端。宿主会补上 query version 1。处理不可用、过期与未知费用，不要当成零。

单次 query 返回当下快照，没有 reset 通知；不要跨来源或隐私变更保留数据。需要持续显示时，请使用处理 reset 与清理的完整订阅示例。

参阅完整实时 UI 示例的订阅与清理方式，以及可复制的设置 schema 与保存示例。卸载时取消订阅；来源／隐私重置时丢弃旧 cursor；保存冲突后由用户决定重新加载，不要直接覆盖。

需要文件、网络或计算时才加入可选 Node 后端。它具有操作系统用户权限，并在多窗口与显示位置之间共享。遵守可见／隐藏状态；后台执行需要另外明确启用。

测试与分发

先打包依赖；安装不会执行 npm scripts。按所提供功能完成作者自测，并在临时配置中测试实际发布包。宿主平台验收矩阵供维护者使用，不是制作第一个插件的前提。

按发布指南与 README 模板说明兼容性、访问权限、图片及发布步骤。目前使用文件／文件夹导入或直接 HTTPS 目录；App 内的 GitHub 发现功能尚未开放。回滚只恢复代码，不会逆转任意数据迁移。

信任后再启用

插件可能读取本机文件和凭证、联网、修改数据或使界面停止响应。仅启用信任的代码；哈希不代表安全审核。

插件 API · UI · Packages · 创建和签署目录

AI

复制以下提示词，补充你的想法，再交给编程助手。

提示词
帮我制作一个 Token Monitor 插件。请阅读官方指南：https://github.com/Javis603/token-monitor/blob/main/docs/plugins/author-quickstart.md（以及其中链接的参考文档）。

如果需求有不清楚的地方，请先向我确认。完成后，请测试插件，并提供可导入的文件夹或 .tmplugin 文件，以及安装与启用步骤。

我的想法：

플러그인 개발 가이드

같은 페이지의 UI와 선택적 로컬 Node 백엔드를 만들 수 있습니다. 플러그인 API는 실험적이며 변경될 수 있습니다.

첫 매니페스트

manifest.json으로 저장하고 ui.mjs를 추가하세요. 폴더를 가져오고 초기 위치를 확인한 다음 신뢰하고 활성화하세요.

{"tmApi":1,"id":"my-panel","name":"My panel","version":"1.0.0","ui":"ui.mjs","files":["ui.mjs"],"views":[{"id":"panel","title":"My panel","surfaces":["home","page"],"defaultSurfaces":["page"]}]}

defaultSurfaces로 초기 표시 위치를 제안할 수 있습니다. 설치 시 확인하거나 변경하며, 설치만 한 경우 첫 활성화 시 적용합니다. 업데이트는 사용자 선택을 유지합니다. 가득 찬 위치는 건너뛰며 전체 스위치는 변경하지 않습니다.

export function activate(ctx) {
  return {
    mount(container, context) {
      const contextLabel = document.createElement('p');
      container.append(contextLabel);
      function update(next) {
        contextLabel.textContent = `My view: ${next.period || next.surface}`;
      }
      update(context);
      return { update, dispose() { contextLabel.remove(); } };
    }
  };
}

같은 페이지 UI

호스트 렌더러에서 DOM/CSS/JS로 UI를 디자인합니다. CSS를 번들에 포함하고 제공되는 네이티브 콘텐츠 노드나 helpers를 활용하세요. UI에는 Node 통합이 없습니다.

데이터와 설정

비동기 mount나 이벤트 핸들러에서 ctx.data.query로 앱이 수집한 데이터를 읽으세요. 백엔드는 필요 없으며 호스트가 query version 1을 채웁니다. 사용할 수 없거나 오래된 데이터와 알 수 없는 비용을 0으로 처리하지 마세요.

단일 query는 스냅샷을 반환하며 reset 콜백이 없습니다. 소스나 개인정보 설정이 바뀐 뒤에는 이전 데이터를 유지하지 마세요. 계속 표시하려면 reset과 정리를 처리하는 전체 구독 예제를 사용하세요.

실시간 UI 전체 예제에서 구독과 정리를, 설정 schema와 저장 예제에서 기본 폼과 사용자 편집기를 확인하세요. 해제 시 구독을 취소하고 소스/개인정보 재설정 시 이전 cursor를 버리세요. 저장 충돌은 덮어쓰지 말고 다시 불러올지 사용자에게 알리세요.

파일, 네트워크, 계산이 필요할 때만 Node 백엔드를 선언하세요. OS 사용자 권한으로 실행되며 창과 표시 위치 간에 공유됩니다. 표시/숨김 상태를 따르세요. 백그라운드 실행은 별도로 명시적 활성화가 필요합니다.

테스트와 배포

의존성을 먼저 번들하세요. 설치는 npm scripts를 실행하지 않습니다. 제공하는 기능에 맞게 작성자 자체 점검을 하고 임시 프로필에서 실제 배포 패키지를 테스트하세요. 호스트 플랫폼 인수 검증은 유지관리자용이며 첫 플러그인의 전제 조건이 아닙니다.

게시 가이드와 README 템플릿에 따라 호환성, 접근 권한, 이미지와 출시 절차를 설명하세요. 현재 파일/폴더 가져오기나 직접 HTTPS 카탈로그를 사용합니다. 앱 내 GitHub 검색 기능은 아직 제공되지 않습니다. 롤백은 코드를 복원하며 임의의 데이터 마이그레이션을 되돌리지 않습니다.

신뢰 후 활성화

플러그인은 파일과 자격 증명, 네트워크에 접근하고 데이터를 변경하거나 UI를 멈출 수 있습니다. 신뢰하는 코드만 활성화하세요. 해시는 보안 검토가 아닙니다.

플러그인 API · UI · Packages · 카탈로그 만들기 및 서명

AI

아래 프롬프트를 복사하고 원하는 기능을 적어 코딩 도우미에게 전달하세요.

프롬프트
Token Monitor 플러그인 만들기를 도와주세요. 공식 가이드를 읽어 주세요: https://github.com/Javis603/token-monitor/blob/main/docs/plugins/author-quickstart.md (및 거기서 링크된 레퍼런스).

요구사항이 불분명하면 먼저 저에게 확인해 주세요. 완성되면 플러그인을 테스트하고, 가져올 수 있는 폴더나 .tmplugin 파일과 설치 및 활성화 방법을 제공해 주세요.

원하는 기능:

プラグイン開発ガイド

同一ページの UI と任意のローカル Node バックエンドを作成できます。プラグイン API は実験的で、今後変更される可能性があります。

最初のマニフェスト

manifest.json として保存し ui.mjs を追加します。フォルダーを取り込み、初回の表示位置を確認して、信頼して有効化します。

{"tmApi":1,"id":"my-panel","name":"My panel","version":"1.0.0","ui":"ui.mjs","files":["ui.mjs"],"views":[{"id":"panel","title":"My panel","surfaces":["home","page"],"defaultSurfaces":["page"]}]}

defaultSurfaces で初回の表示位置を提案できます。インストール時に確認・変更でき、インストールのみの場合は初回有効化時に適用します。更新ではユーザーの選択を維持します。満員の場所はスキップし、全体スイッチは変更しません。

export function activate(ctx) {
  return {
    mount(container, context) {
      const contextLabel = document.createElement('p');
      container.append(contextLabel);
      function update(next) {
        contextLabel.textContent = `My view: ${next.period || next.surface}`;
      }
      update(context);
      return { update, dispose() { contextLabel.remove(); } };
    }
  };
}

同一ページの UI

ホストのレンダラー内で DOM/CSS/JS を使って UI を設計します。CSS を同梱し、提供されるネイティブの内容ノードや helpers を利用できます。UI に Node 統合はありません。

データと設定

非同期 mount やイベントハンドラー内で ctx.data.query を使い、App が収集済みのデータを読みます。バックエンドは不要で、ホストが query version 1 を補います。利用不可、古いデータ、不明な費用をゼロと扱わないでください。

単発の query はスナップショットを返し、reset の通知はありません。ソースやプライバシー設定の変更後に以前のデータを保持しないでください。継続的な表示には、reset と後処理に対応した購読の完全な例を使用してください。

購読と後処理を含む UI の完全な例、および設定 schema と保存の例を参照してください。破棄時に購読を解除し、ソース／プライバシーのリセット時は古い cursor を破棄します。保存の競合を上書きせず、再読み込みを利用者に案内してください。

ファイル、ネットワーク、計算が必要な場合だけ Node バックエンドを宣言します。OS ユーザー権限で動作し、複数のウィンドウと表示場所で共有されます。表示／非表示状態を尊重してください。バックグラウンド実行には別途明示的な有効化が必要です。

テストと配布

依存関係を事前にバンドルしてください。インストールは npm scripts を実行しません。提供機能に応じた作者向けセルフチェックを行い、使い捨てプロファイルで実際の配布パッケージをテストします。ホストのプラットフォーム受け入れ検証は保守担当者向けで、最初のプラグイン作成の前提条件ではありません。

公開ガイドと README テンプレートに従い、互換性、アクセス内容、画像、リリース手順を説明してください。現在はファイル／フォルダーの取り込みか直接 HTTPS カタログを利用します。App 内の GitHub 検索機能はまだ利用できません。ロールバックはコードを復元し、任意のデータ移行を戻しません。

信頼してから有効化

プラグインはファイルや認証情報、ネットワークにアクセスし、データを変更したり UI を停止させる可能性があります。信頼するコードだけを有効にしてください。ハッシュは安全性の審査ではありません。

プラグイン API · UI · Packages · カタログの作成と署名

AI

以下のプロンプトをコピーし、作りたいものを書き加えてコーディングアシスタントに渡してください。

プロンプト
Token Monitor のプラグイン作成を手伝ってください。公式ガイドを読んでください：https://github.com/Javis603/token-monitor/blob/main/docs/plugins/author-quickstart.md（およびそこからリンクされたリファレンス）。

要件に不明な点があれば、まず私に確認してください。完成したらプラグインをテストし、インポートできるフォルダーまたは .tmplugin ファイルと、インストール・有効化の手順を提供してください。

作りたいもの：

Guia de desenvolvimento de plugins

Crie uma interface na mesma página com backend Node local opcional. A API de plugins é experimental e pode mudar.

Primeiro manifesto

Salve como manifest.json e adicione ui.mjs. Importe a pasta, confirme os locais iniciais, confie e ative.

{"tmApi":1,"id":"my-panel","name":"My panel","version":"1.0.0","ui":"ui.mjs","files":["ui.mjs"],"views":[{"id":"panel","title":"My panel","surfaces":["home","page"],"defaultSurfaces":["page"]}]}

defaultSurfaces sugere locais iniciais. Confirme ou altere na instalação; instalar sem ativar adia a aplicação até a primeira ativação. Atualizações preservam suas escolhas. Locais cheios são ignorados e os controles gerais não mudam.

export function activate(ctx) {
  return {
    mount(container, context) {
      const contextLabel = document.createElement('p');
      container.append(contextLabel);
      function update(next) {
        contextLabel.textContent = `My view: ${next.period || next.surface}`;
      }
      update(context);
      return { update, dispose() { contextLabel.remove(); } };
    }
  };
}

UI na mesma página

Crie a UI com DOM/CSS/JS no renderizador do app. Inclua o CSS no pacote e use os elementos nativos ou helpers disponíveis. A UI não tem integração com Node.

Dados e configurações

Use ctx.data.query em um mount assíncrono ou manipulador de eventos para ler dados já coletados pelo app. Não é necessário backend; o host fornece query version 1. Não transforme dados indisponíveis, antigos ou custos desconhecidos em zero.

Uma query isolada retorna um snapshot e não oferece callback de reset. Não retenha seus dados após mudanças de origem ou privacidade. Para uma exibição persistente, use o exemplo completo de assinatura, que trata resets e limpeza.

Consulte o exemplo completo de UI ao vivo para assinaturas e limpeza e o schema de configurações e exemplo de gravação para o formulário nativo ou editor próprio. Cancele assinaturas ao descartar a UI e descarte cursors antigos quando a origem/privacidade mudar. Informe conflitos antes de recarregar; não sobrescreva outra edição silenciosamente.

Declare um backend Node opcional apenas para arquivos, rede ou cálculo. Ele tem a autoridade do usuário do sistema e é compartilhado entre janelas e locais. Respeite o estado visível/oculto; execução em segundo plano exige ativação explícita separada.

Teste e distribua

Empacote dependências antes; instalar não executa npm scripts. Siga a verificação do autor conforme os recursos oferecidos e teste o pacote exato em um perfil descartável. A matriz de aceitação da plataforma é para mantenedores, não um requisito para o primeiro plugin.

Siga o guia de publicação e modelo de README para compatibilidade, acesso, imagens e lançamentos. Use importação de arquivo/pasta ou catálogo HTTPS direto; a descoberta do GitHub dentro do app ainda não está disponível. Rollback restaura código, não migrações arbitrárias de dados.

Confie antes de ativar

Plugins podem acessar arquivos, credenciais e rede, modificar dados ou travar a interface. Ative apenas código confiável. Um hash não é uma auditoria de segurança.

API de plugins · UI · Packages · Criar e assinar um catálogo

AI

Copie o prompt abaixo, acrescente sua ideia e envie ao seu assistente de programação.

Prompt
Me ajude a criar um plugin para o Token Monitor. Leia o guia oficial: https://github.com/Javis603/token-monitor/blob/main/docs/plugins/author-quickstart.md (e a referência que ele indica).

Se algum requisito não estiver claro, confirme comigo primeiro. Ao terminar, teste o plugin e forneça uma pasta ou um arquivo .tmplugin que eu possa importar, junto com as instruções de instalação e ativação.

Minha ideia: