自動化とスクリプト

最終更新: 2026-07-15

Plainvaには、サードパーティのコードを実行するプラグインシステムはありません。その代わりに、保管庫そのものが拡張インターフェースです: あなたのノートは純粋なMarkdownで、データベースは純粋なYAML（.base）で、OKFの規約がすべてのファイルに予測可能な構造を与えます。ファイルを読み書きできるものであれば何でも——シェルスクリプト、Pythonプログラム、CLIツール、スケジュールされたジョブ、あるいはAIエージェントでも——Plainva固有のAPIを一切使わずに、あなたの保管庫を拡張し、生成し、再編成できます。

このページでは、それを安全に行う方法を説明します。すべてのファイルの正確なバイトレベルの形式はファイル形式リファレンスに別途文書化されています。このページはその実践的な補完です: ルール、ワークフロー、そしてAIアシスタントに何を渡すべきかです。

プラグインのサンドボックスではなくファイルを使う理由

セキュリティ。 コードプラグインシステムは、あなたのノートへのアクセス権を持ったまま、エディター内で他人のプログラムを実行します。普通のファイルであれば、そのような信頼は不要です: スクリプトが触れるのは、あなたが指定したフォルダーだけであり、それもオペレーティングシステムの通常の権限の範囲内です。
長寿命性。 形式はアプリより長生きします。5年前にスクリプトで生成したMarkdownファイルは、今日でも問題なく開けます——Plainvaでも、Obsidianでも、どんなテキストエディターでもです。廃止すべきプラグインAPIというもの自体が存在しません。
形式こそが契約です。 ディスク上の形式がオープンで文書化されているため、その「API」は安定していて検証可能です。diffを取ることも、Gitでバージョン管理することも、その挙動について推論することもできます。

Plainvaが標準で行わないことをしたい場合、プラグインを待つ必要はありません——ファイルを対象に小さなスクリプトを書けばよいのです。

保管庫を安全に読み取る

すべてはUTF-8テキストです:

ノート (.md)——任意のYAMLフロントマターブロック（一番上にある2つの---行の間）にプロパティが保持され、その後にMarkdown本文が続きます。フロントマターは任意のYAMLライブラリでパースできます。
データベース (.base)——ノートに対するビューを記述する、純粋なYAMLです。値は.baseの中には決して存在せず、ノートのフロントマターに存在します。
構造——タグは本文中の#tag、またはフロントマターのtags:です。リンクは[[Note]]（Wikiリンク）または[text](path.md)です。タスクは- [ ] / - [x]のリスト項目です。

読み取りには注意が一切不要です——テキストファイルは、読み取るだけで「破損」することはありません。以下のルールは、すべて書き込みに関するものです。

保管庫に安全に書き込む

これらのルールに従えば、Plainva（そしてObsidian）はあなたの変更を問題なく受け入れます。Plainvaは保管庫フォルダーを監視しています: 外部からの書き込みは自動的に検知され、通常は1秒以内に再インデックスされます。

BOMなしのUTF-8で、LF改行で書き込んでください。 デフォルトでUTF-16またはCRLFを使うWindowsのツールは、Plainvaが同期のたびに「変更あり」と扱ってしまうファイルを生成します。
アトミックに書き込んでください。 同じフォルダー内の一時ファイルに書き込み、その後それを対象ファイルの上にリネームしてください。（例えばクラッシュ後の）中途半端に書き込まれたノートは、変更なしより悪い結果を招きます。Plainva自身も、すべてのノートをこの方法で書き込んでいます。
OKFフロントマターと未知のキーを保持してください。 ノートを書き直す際はtypeとokf_versionを保持し、認識できないフロントマターキーを決して削除しないでください——変更せずに往復させてください。理解できないキーを「整理」しないでください。
.plainva/には決して触れないでください。 このフォルダーには、Plainvaのデバイスローカルなインデックス、バックアップ、グラフのピン、同期状態が保持されています。これはあなたのコンテンツの一部ではなく、あなたのスクリプトによって書き込まれたり、同期されたり、Gitにコミットされたりしてはいけません。
.baseのルールを守ってください。 .baseはObsidianの4つのトップレベルキー（filters、formulas、properties、views）だけを使います。すべてのビューにはnameが必要です。フィルターは単一ルートです。Plainva固有のデータはすべて、入れ子のplainva:サブキーの下に置かれます。完全な契約——両側のリレーションの例を含む——はファイル形式リファレンスにあります。
エディターと競合しないでください。 ノートがPlainvaで開かれていてかつ未保存の変更がある場合、その瞬間にスクリプトから書き直すのは避けてください。Plainvaにはセーフティネットとして競合解決の仕組みがありますが、最もクリーンな方法は、アプリに先に保存させることです（あるいは、現在開かれていないノートを編集することです）。

パターン

よくある作業をいくつか挙げます——すべて単なるファイル操作です:

ノートの一括作成——OKFフロントマターブロック（type、okf_version、そして独自のプロパティ）とMarkdown本文を持つ.mdファイルを生成します。Plainvaは、それらが現れるたびにインデックスします。
デイリーノートやレポートの生成——別のソースから内容を取り込み、日付付きのノートをデイリーノートフォルダーに書き込む、スケジュールされたスクリプトです。
プロパティの一括処理——すべてのノートのフロントマターを読み取り、フィールドを変換し、（アトミックに、未知のキーを保持したまま）書き戻します。
エクスポート/公開——保管庫を読み取り、HTML、静的サイト、またはPDFにレンダリングします。読み取りのみなので、気にすべきルールはありません。
リンクの保守——[[Note]]リンクとtags:を再スキャンしてレポートを作成するか、その場で修正します。

可能な限りスクリプトをべき等にしてください: 2回実行しても内容が重複しないようにします。

保管庫をAIアシスタントに渡す

保管庫フォルダーへの読み書きアクセス権を持つAIエージェントは、まさにこの設計が想定しているケースです。正しく動作させるには:

ファイル形式リファレンスを渡してください。 これは機械が読むことを前提に書かれています: OKFフロントマターの契約、プロパティ→YAMLのシリアライズ、Obsidianの厳格なルールを含む完全な.baseスキーマ、index.mdの契約、そして安全性のルール——エージェントがファイルを壊さずに編集するために必要なすべてです。
.plainva/フォルダーではなく、保管庫フォルダーを指定してください。 .plainva/が立入禁止であることを明確に伝えてください。
アトミックで最小限の編集を求めてください。 1つのプロパティを変更するためにノート全体を書き直すエージェントは、フロントマターと本文の残りをそのまま保持すべきです。

契約は稼働中のAPIではなく文書であるため、オフラインでもオンラインでも、同じ指示がどんなアシスタントにも通用します。

安全性のまとめ

UTF-8、BOMなし、LF。
アトミックに書き込む（一時ファイル + リネーム）。
type、okf_version、そして未知のキーを保持する。
.plainva/には決して書き込まない。
.base: 4つのトップレベルキー、名前付きのビュー、単一ルートのフィルター、それ以外はすべてplainva:サブキー。
保管庫は監視されています——外部からの変更は自動的にPlainvaに反映されます。