wisemind-ai

WiseMindAI スキル

このスキルを使用すると、HTTP 経由でローカルの WiseMindAI アプリを操作できます。

デフォルト設定

• ベース URL：http://127.0.0.1:38221
• まずデフォルトのポートを試してください。ヘルスチェックに失敗した場合、またはユーザーが別のポートを明示した場合にのみ、カスタムポートをユーザーに確認してください。
• レガシーエンドポイントよりも /api/v2/* を優先してください。
• Content-Type: application/json を指定して JSON を送信してください。
• ホスト側のエージェントに、より適した組み込み HTTP ツールがすでにある場合を除き、curl を使用してください。

必須のワークフロー

1. ほかの作業を始める前に、接続を確認してください。
2. 列挙値、ルート、またはペイロードの形式が不明な場合は、ケイパビリティを取得してください。
3. 書き込む前に、適切な WiseMindAI オブジェクトの種類を選択してください。
4. 書き込み、更新、削除の前に、検索または読み取りを行ってください。
5. フォルダー、ナレッジベース、デッキ、カードフォルダーには resolve エンドポイントを使用してください。
6. 繰り返し書き込まれる可能性のある URL やファイルパスには upsert を使用してください。
7. ユーザーが明確に削除を依頼しない限り、削除しないでください。
8. 保存または変更した内容と保存先を簡潔に報告してください。

標準のソースフィールド

ナレッジドキュメントを作成または更新する場合は、ソースメタデータを必ず保持してください。

ソースの種類	type	fileType	fileExt	fileUrl
ユーザーが入力したプレーンテキスト	input	input	input	空文字列
Web URL、ブックマーク、またはウェブページの記事	link	link	link	元の URL
ローカルファイル／インポートしたファイル	file または upload	検出されたファイルの種類	実際の拡張子	ファイルパスまたは Wise ファイル URL

ウェブページや URL のコンテンツをナレッジベースに保存する場合は、fileUrl が必須であり、元の URL を指定する必要があります。URL 由来のナレッジドキュメントを、空の fileUrl、fileType、または fileExt で保存しないでください。アプリはこれらのフィールドを使用して、ドキュメントをリンクとして表示します。

ペイロードに関する一般的な注意事項

• ノートには title と content を使用してください。Markdown／プレーンテキストのノートを保存する場合、意図的に異なる表現が必要な場合を除き、同じ本文を content、md、text に送信してください。tags は配列である必要があります。
• ファイルレコードでは、表示されるタイトルに name を、URL またはローカルパスに filePath を使用してください。リンクの場合は、常に type:"link" と fileType:"link" を送信してください。入力テキストのレコードでは、type:"input" と fileType:"input" を送信してください。
• ドキュメント領域に保存するウェブページには、url、title、summary、content を指定して /api/v2/files/save-webpage を使用してください。
• ナレッジドキュメントでは、表示用に title を使用し、knowledgeBaseId を必ず含めてください。ソースを記録するレコードには、type、fileType、fileExt、fileUrl のすべてを含めてください。デフォルト値に頼らないでください。
• カードには、数値の deckId、数値の folderId、空でない content が必要です。一括作成の場合、cards 内の各項目に content を含めてください。指定する場合、tags は配列にしてください。
• Patch リクエストには、意図して変更するフィールドだけを含めてください。ユーザーが消去を依頼していない限り、パッチに空のソースフィールドを送信しないでください。

ヘルスチェック

最初にこれを実行してください：

curl -s http://127.0.0.1:38221/api/health

想定される形式：

{"ok": true, "service": "wisemindai-local-api", "version": "2.0.0"}

失敗した場合：

• WiseMindAI を起動し、ローカル API を有効にするようユーザーに依頼してください。
• カスタムポートを使用している場合は、そのポートで再試行してください。
• サービスに接続できるようになるまでは、書き込み操作を続行しないでください。

ケイパビリティの検出

現在サポートされているグループ、エンドポイント、または列挙値が必要な場合に使用してください：

curl -s http://127.0.0.1:38221/api/capabilities

このエンドポイントでは、以下を取得できます：

• サポートされているグループ
• エンドポイント一覧
• fileTypeOptions
• fileCategoryOptions
• knowledgeTypeOptions
• knowledgeStatusOptions

不明な場合は、オプション値をハードコードするのではなく、実行時の検出を優先してください。

適切な保存先を選ぶ

ユーザーの意図	推奨する保存先
ちょっとした考え、会議メモ、下書き、日記、一般的なメモ	notes
ローカルファイル、URL、ブックマーク、ウェブページ、自由形式の文書レコードを保存する	files
長期的な整理のために、名前付きナレッジベースにコンテンツを保存する	knowledge-documents
学習カードや間隔反復用の教材を作成する	cards

既定の選択肢：

• より明確な構造が求められていないプレーンテキスト：ノートとして保存します。
• URL または外部リソース：ファイルレコードとして保存します。
• ナレッジベース用であることが明示されたコンテンツ：ナレッジドキュメントとして保存します。
• クイズ、暗記、フラッシュカード、またはカードのリクエスト：カードを作成します。

主なエンドポイント

共通

• GET /api/health
• GET /api/capabilities
• GET /api/search

ノート

• GET /api/v2/notes
• GET /api/v2/notes/:id
• POST /api/v2/notes
• PATCH /api/v2/notes/:id
• DELETE /api/v2/notes/:id
• GET /api/v2/note-folders
• POST /api/v2/note-folders
• POST /api/v2/note-folders/resolve

ファイル、リンク、ウェブページ

• GET /api/v2/files
• GET /api/v2/files/:id
• POST /api/v2/files
• PATCH /api/v2/files/:id
• DELETE /api/v2/files/:id
• POST /api/v2/files/upsert
• POST /api/v2/files/save-webpage
• GET /api/v2/file-folders
• POST /api/v2/file-folders
• POST /api/v2/file-folders/resolve

ナレッジベース

• GET /api/v2/knowledge-bases
• POST /api/v2/knowledge-bases
• PATCH /api/v2/knowledge-bases/:id
• POST /api/v2/knowledge-bases/resolve
• GET /api/v2/knowledge-documents
• GET /api/v2/knowledge-documents/:id
• POST /api/v2/knowledge-documents
• PATCH /api/v2/knowledge-documents/:id
• DELETE /api/v2/knowledge-documents/:id

カード

• GET /api/v2/card-decks
• POST /api/v2/card-decks
• PATCH /api/v2/card-decks/:id
• POST /api/v2/card-decks/resolve
• GET /api/v2/card-folders
• POST /api/v2/card-folders
• PATCH /api/v2/card-folders/:id
• POST /api/v2/card-folders/resolve
• GET /api/v2/cards
• GET /api/v2/cards/:id
• POST /api/v2/cards
• PATCH /api/v2/cards/:id
• DELETE /api/v2/cards/:id
• POST /api/v2/cards/batch

運用ルール

書き込む前に検索する

新しいコンテンツを作成する前に、次を優先します。

curl -s "http://127.0.0.1:38221/api/search?q=keyword&limit=10"

これにより、ノート、ドキュメント、ナレッジドキュメント、カードの重複を避けられます。

更新する前に読み込む

更新する場合：

1. 候補を一覧表示するか、検索します。
2. 必要に応じて現在の項目を読み込みます。
3. 変更するフィールドのみをパッチします。

ID を推測せず、コンテナーを解決する

ユーザーが保存先を指定していても ID を提示していない場合は、まず解決エンドポイントを使用します。

• /api/v2/note-folders/resolve
• /api/v2/file-folders/resolve
• /api/v2/knowledge-bases/resolve
• /api/v2/card-decks/resolve
• /api/v2/card-folders/resolve

人が読みやすい名前が指定された場合は、これを既定の動作とします。

URL とパスには冪等な書き込みを優先する

同じ URL またはファイルパスを複数回保存する可能性がある場合は、次を優先します。

curl -s -X POST "http://127.0.0.1:38221/api/v2/files/upsert" \
  -H "Content-Type: application/json" \
  -d '{"name":"Example","filePath":"https://example.com","type":"link","fileType":"link"}'

実際のウェブページのコンテンツがある場合は save-webpage を使用し、URL またはパスによる重複排除が主な要件の場合は upsert を使用します。

よく使う手順

ノートを保存する

ノートを作成します。

curl -s -X POST "http://127.0.0.1:38221/api/v2/notes" \
  -H "Content-Type: application/json" \
  -d '{"title":"Note title","content":"Body text","md":"Body text","text":"Body text","tags":["tag1","tag2"]}'

ユーザーがフォルダー名を指定した場合は、先にフォルダーを解決し、from_folder を渡します。

自由形式のテキストまたはローカルファイルレコードを保存する

ノートではなくドキュメントレコードとして保存するテキストの場合：

curl -s -X POST "http://127.0.0.1:38221/api/v2/files" \
  -H "Content-Type: application/json" \
  -d '{"name":"Document title","type":"input","fileType":"input","filePath":"","content":"Text content","summary":"Short summary"}'

URL の場合はリンクメタデータを使用し、元の URL を filePath に保持します。

curl -s -X POST "http://127.0.0.1:38221/api/v2/files/upsert" \
  -H "Content-Type: application/json" \
  -d '{"name":"Article title","filePath":"https://example.com/article","type":"link","fileType":"link","summary":"Short summary","content":"Optional captured content"}'

ローカルファイルの場合は、適切な type 拡張子と fileType カテゴリーを選択します。不明な場合は /api/capabilities を取得します。

ウェブページを保存する

ユーザーが URL のみを提示した場合：

1. ホストエージェントが利用できるウェブ、ブラウザー、またはフェッチ機能を使って、ページタイトルと主要な内容を取得します。
2. 全文を取得できる場合は、save-webpage で保存します。
3. 全文を取得できない場合は、upsert でリンクレコードを保存するか、保存したい内容をユーザーに提供してもらいます。
4. ユーザーが URL をナレッジベースに保存するよう明示した場合は、代わりに /api/v2/knowledge-documents を使用し、リンク形式のナレッジドキュメントのペイロードに従います。

コンテンツ付きでウェブページを保存する：

curl -s -X POST "http://127.0.0.1:38221/api/v2/files/save-webpage" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/article","title":"Article title","summary":"Short summary","content":"Main article content"}'

要約のガイダンス：

• 指定がない限り、ユーザーの言語に合わせます。
• 要約は簡潔で役立つものにします。
• 短い要約段落を 1 つと、いくつかの要点を記載するのが望ましいです。

ナレッジベースにコンテンツをインポートする

最初にナレッジベースを特定します。

curl -s -X POST "http://127.0.0.1:38221/api/v2/knowledge-bases/resolve" \
  -H "Content-Type: application/json" \
  -d '{"name":"AI Research"}'

次に、ナレッジドキュメントを作成します。

curl -s -X POST "http://127.0.0.1:38221/api/v2/knowledge-documents" \
  -H "Content-Type: application/json" \
  -d '{"knowledgeBaseId":1,"title":"RAG Notes","content":"Document body","summary":"Short summary","type":"input","fileType":"input","fileExt":"input","fileUrl":""}'

ソースが URL またはウェブページの場合は、元の URL を fileUrl に保持し、すべてのソースタイプフィールドを link に設定します。

curl -s -X POST "http://127.0.0.1:38221/api/v2/knowledge-documents" \
  -H "Content-Type: application/json" \
  -d '{"knowledgeBaseId":1,"title":"Article title","content":"Main article content","summary":"Short summary","type":"link","fileType":"link","fileExt":"link","fileUrl":"https://example.com/article"}'

「この記事の URL をナレッジベース X に入れて」のような依頼では、可能な場合はタイトルとコンテンツを取得してから、上記のリンクペイロードでナレッジドキュメントを作成します。コンテンツを取得できない場合も URL フィールドを保持し、取得可能なタイトル、説明、または短いメモを content と summary に設定した簡潔なリンクレコードを保存します。

既存のナレッジドキュメントの更新を依頼された場合は、まず検索または一覧表示を行い、一致する項目を特定してから更新します。

カードを作成する

デッキ、フォルダーの順に特定してから、カードを作成します。

単一のカード：

curl -s -X POST "http://127.0.0.1:38221/api/v2/cards" \
  -H "Content-Type: application/json" \
  -d '{"deckId":1,"folderId":1,"content":"Card content"}'

複数のカード：

curl -s -X POST "http://127.0.0.1:38221/api/v2/cards/batch" \
  -H "Content-Type: application/json" \
  -d '{"deckId":1,"folderId":1,"cards":[{"content":"Card 1","tags":["tag1"]},{"content":"Card 2","tags":["tag2"]}]}'

カード作成のガイダンス：

• 各カードでは、1 つのアイデアに焦点を当てます。
• ユーザーが複数のカードを明確に希望している場合は、一括作成を使用します。
• ユーザーが少数のカードのみを希望している場合に、むやみに大量のカードを生成しないでください。

既存のコンテンツを更新する

ユーザーが「更新する」「移動する」「名前を変更する」「要約を変更する」などと依頼した場合：

1. 検索、一覧表示、または明示された ID で対象を特定します。
2. 候補が複数ある場合は、簡潔な確認質問をします。
3. 正しいエンドポイントで PATCH を使用します。
4. 何を変更したかをユーザーに正確に伝えます。

既存のコンテンツを削除する

削除は取り消せない操作です。次の場合にのみ実行します。

• ユーザーが削除を明示的に依頼していること、かつ
• 対象が明確であること。

対象が曖昧な場合は、何も削除する前に確認します。

結果の報告

操作が成功した後、次の内容を簡潔なメッセージ 1 つで報告します。

• 作成、更新、または削除した内容
• 保存先
• 役立つ場合に限り、主要な識別子

良い例：

• 「記事をウェブページレコードとして、WiseMindAI の Reading Queue に保存しました。」
• 「デッキ AI Basics ／フォルダー RAG に 8 枚のカードを作成しました。」
• 「Product Notes にある既存のナレッジドキュメントの要約を更新しました。」

レガシーエンドポイント

互換性のためレガシーエンドポイントも引き続き存在しますが、新しい作業では /api/v2/* を使用してください。