mindos

MindOS スキル

CLI コマンド

すべてのナレッジベース操作には mindos file <subcommand> を使用します。構造化出力にするには --json を追加します。

操作	コマンド
ファイル一覧	mindos file list
ファイルを読む	mindos file read <path>
書き込み／上書き	mindos file write <path> --content "..."
新しいファイルを作成	mindos file create <path> --content "..."
ファイルに追記	mindos file append <path> --content "..."
セクションを編集	mindos file edit-section <path> -H "## Heading" --content "..."
見出しの後に挿入	mindos file insert-heading <path> -H "## Heading" --content "..."
CSV 行を追記	mindos file append-csv <path> --row "col1,col2,col3"
ファイルを削除	mindos file delete <path>
名前変更／移動	mindos file rename <old> <new>
検索	mindos search "query"
バックリンク	mindos file backlinks <path>
最近使ったファイル	mindos file recent --limit 10
Git 履歴	mindos file history <path>
スペース一覧	mindos space list
スペースを作成	mindos space create "name"

MCP users: MCP ツール（mindos_*）しか使えない場合は、スキーマから機能を確認できるため、そのまま使用してください。利用可能な場合は、CLI を優先してください（トークンコストが低いため）。

CLI のセットアップ

npm install -g @geminilight/mindos
# Remote mode: mindos config set url http://<IP>:<PORT> && mindos config set authToken <token>

---

ルール

1. まず初期確認を行う — 検索や書き込みの前に KB のツリーを一覧表示し、構造を把握します。
2. 原則として読み取り専用にします。 ユーザーが保存、記録、整理、編集を明示的に依頼した場合にのみ書き込みます。検索／要約／引用では書き込みません。
3. ルールの優先順位（上位が優先）：ユーザーの現在のターンでの指示 → .mindos/user-preferences.md → 最寄りのディレクトリの INSTRUCTION.md → ルートの INSTRUCTION.md → この SKILL のデフォルト設定。
4. 複数ファイルの編集では、まず計画を提示します。 変更内容の一覧をすべて提示し、承認を得てから実行します。
5. 作成／削除／移動／名前変更の後は、影響を受ける README を自動的に同期します。
6. 書き込む前に読みます。 上書きする前に、必ずファイルを読みます。推測に基づいて書き込んではいけません。
7. ターンを適切に終了します。 依頼された操作を完了したらそこで終了し、検索や書き込みが完了しているのに不要な追加質問をしないでください。
8. ソースコードとの境界を守ります。 このスキルの対象は MindOS KB です。ユーザーがアプリ／ソースコードの編集を依頼したにもかかわらず、ソースファイルやコード用ワークスペースツールを利用できない場合は、KB のメモを検索したり書き込んだりせず、具体的なリポジトリ／ファイル／コードの情報を求めてください。単にコーディングを依頼された場合は、ソースファイルを探すために KB の一覧表示／検索／読み取りツールを使ってはいけません。

回答の契約

任意のタスク後フックを実行する前に、この回答契約に従ってください。

• 検索／要約／引用： まず回答し、安定したファイルパスを明記して、書き込みを行わないことを明確にしてください。ユーザーが特定のローカルファイルパスを指定した場合は、その正確なパスを最終回答に含めてください。ユーザーが変更しないよう指示した場合、または読み取り専用の対応を求めた場合は、ユーザーの言語で短い変更なしの文を添えてください（中国語：「未做任何修改。」、英語：「No changes were made.」）。ユーザーが次の手順を求めた場合、または根拠が不十分な場合を除き、「保存／記録／更新しましょうか？」で終わらせないでください。
• 書き込み／更新／追記： 書き込みツールの実行が成功した後に限り、ユーザーの言語で正確なパスと操作を報告してください。英語：Saved to <path>、Updated <path>、Appended to <path>。中国語：「已保存到 <路径>」、「已更新 <路径>」、「已追加到 <路径>」。短い要約文を最大1文添えてください。
• アップロードされたコンテンツの書き込み： ユーザーがアップロードしたコンテンツをノートにするよう求め、保存先の種類が明確な場合は、アップロードされたコンテンツを直接使用し、ディレクトリ一覧やREADMEの確認は軽く1回まで行ってから、ノートを書き込んでください。ディレクトリ一覧の確認だけで止めないでください。
• 確認： 不足している回答によって保存先、範囲、コスト、安全性、または取り消し可能性が変わる場合に限り、具体的な質問を1つだけしてください。役立つ場合は、現実的な選択肢を2～3個提示してください。
• 根拠不足またはツールの失敗： 見つからなかったもの、または失敗したことを伝え、必要に応じて試した情報源／ツールを明記し、次に行う具体的な復旧手順を示してください。根拠が見つからない検索では、ユーザーから依頼されていない限り、見つからなかった内容を保存、記録、作成、追加する提案をしないでください。回答を空にしてはいけません。
• 言語の忠実性： ユーザーの言語と、元のノートの重要な用語を維持してください。ノートに中国語の用語が使われている場合は、その用語を再利用してください。役立つ場合に限り、英語の訳語を括弧内に添えてください。
• 読み取り専用の完了： ユーザーが要約、会議のコンテキスト、または次の手順のみを求めた場合は、回答した時点で終了してください。求められていない「保存／記録／草案作成／執筆／補足／修正／エクスポート／実行をしましょうか？」という提案を付け加えないでください。質問形ではなく、断定文で終えてください。SOPまたはワークフローに従う場合は、使用したSOP／ワークフローのパスを記載してください。ユーザーが次の手順だけを求めた場合は、それを実行するかどうか尋ねないでください。

---

情報検索の方針

ナレッジを検索する際は、2つの経路を並行して使い、詳しく読む前に絞り込んでください。

経路1：ディレクトリの確認（名前／構造から）

ナレッジベースのツリーを参照し、ファイル名とディレクトリ名を確認してください。タイトルから内容がわかることがよくあります。たとえばユーザーが「認証」について尋ねていて、Decisions/auth-jwt-vs-session.md が見つかった場合は、有力な候補です。検索はせず、直接読んでください。

• 初期化後、問い合わせのトピックに関連する名前のパスがないか、ツリーを確認してください。
• ディレクトリの意味にも注意してください。Decisions/、Projects/、Workflows/、Resources/ などは、それぞれにどのような内容が含まれるかを示しています。
• ナレッジベースが小さい場合（ファイルが50個未満）は、検索よりもツリーをざっと確認するほうが速く、確実なことがあります。

経路2：全文検索（内容から）

ファイル名だけでは推測できない内容を探すときは、searchを使ってください。

• ユーザーが実際に使った言葉をもとに検索語を作成してください。ユーザーが「那个很慢的接口」と言った場合は、「慢 接口」または「性能 API」で検索してください。
• 的を絞った検索を1回行うほうが、曖昧な検索を4回行うより効果的です。最初の検索結果が3件未満の場合、またはトピックに明らかな別表現（中国語と英語など）がある場合に限り、2回目の検索を追加してください。
• 毎回、機械的に2～4回検索しないでください。まず考えてから、適切な検索を行ってください。

絞り込み：全文を読む前にスニペットを確認

検索結果にはスニペットとBM25スコアが含まれます。それらを参考に、どのファイルを読むか判断してください。

• スコアが高く、スニペットが明らかに関連している → ファイル全体を読んでください。
• スコアが中程度で、スニペットが部分的に関連している → より適切な候補がない場合に限り、ファイル全体を読んでください。
• スコアが低い、またはスニペットが無関係 → 読まずに飛ばしてください。検索結果をすべて読む必要はありません。
• じっくり読むファイルは1～3件を目安にし、10件を浅く読むことは避けてください。

例

User: "之前关于数据库选型的讨论"

Step 1 (tree scan): See "Decisions/database-postgres-vs-mongo.md" → strong match by name.
Step 2 (search):    search("数据库选型") → returns 5 results.
Step 3 (triage):    Result #1 snippet mentions "PostgreSQL vs MongoDB 对比" (score 18.3) → read.
                    Result #2 snippet mentions "数据库连接池配置" (score 4.1) → skip, off-topic.
                    Result #3 snippet mentions "选型会议纪要" (score 12.7) → read.
Step 4 (answer):    Cite from the 2-3 files actually read.

---

絶対にしてはいけないこと（実体験から得た注意点）

• 明示的に指示されない限り、KB のルートには絶対に書き込まないでください。 ルートにはガバナンスファイルのみを置きます。新しいコンテンツは、最も適したサブディレクトリに配置します。
• ディレクトリ名を絶対に決めつけないでください。 実際のブートストラップツリーから推測してください。KB では中国語の名前が使われていたり、フラットな構成になっていたりする場合があります。
• 小さな編集にファイル全体の上書きを絶対に使わないでください。 対象を絞った変更には mindos file edit-section または mindos file insert-heading を使ってください。全体を書き直すと、git の差分が損なわれます。
• 確認を得ずに INSTRUCTION.md や README.md を絶対に変更しないでください。 これらはガバナンス文書であり、特に慎重に扱ってください。
• 同じディレクトリにあるファイルを確認せずに、絶対にファイルを作成しないでください。 対象ディレクトリにあるファイルを1〜2個読み、そこでのスタイルを把握してください。
• 参照先がなくなったリンクを絶対に放置しないでください。 名前の変更や移動の後は、バックリンクを確認し、参照元のすべてのファイルを更新してください。
• 複数ファイルへの書き込みで、ルーティングの確認を絶対に省略しないでください。 ユーザーのメンタルモデルは、あなたのものと異なる場合があります。
• 検索結果をすべて読むのは絶対に避けてください。 スニペットとスコアを使って選別してください。明らかに関連性の高いファイルだけを詳しく読んでください。

---

MindOS の概念

• Space — 考え方に合わせて整理されたナレッジの区分です。エージェントも同じ構造に従います。
• Instruction — 接続されたすべてのエージェントが従うルールファイル（INSTRUCTION.md）です。
• Skill — KB の読み取り、書き込み、整理の方法をエージェントに教えます。
• Inbox — Inbox/ ディレクトリは、手軽に情報を取り込むための一時置き場です。明確な保存先がまだないファイルは、ここに置かれます。後でユーザーが手動で整理するか、AI を活用した一括整理によって整理されます。

ノートは Instruction と Skill の両方の役割を果たせます。ツリー内の Markdown ファイルにすぎません。

---

決定木

User request
  │
  ├─ Lookup / summarize / quote?
  │   └─ [Read-only]: search → read → answer with citations. No writes.
  │
  ├─ Save / record / update / organize specific content?
  │   ├─ Know where it goes → [Single-file edit]
  │   ├─ Don't know where it goes → [Inbox path] — save to Inbox/, classify later
  │   └─ Multiple files or unclear → [Multi-file routing] — plan first
  │
  ├─ Organize inbox / classify staged files?
  │   └─ [Inbox organize] — read Inbox/ files, propose destinations, move after approval
  │
  ├─ Structural change (rename / move / delete / reorganize)?
  │   └─ [Structural path] — check backlinks before and after
  │
  ├─ Procedural / repeatable task?
  │   └─ [SOP path] — find and follow existing SOP, or create one
  │
  ├─ Retrospective / distill / handoff?
  │   └─ [Retrospective path]
  │
  ├─ Knowledge health check / detect conflicts?
  │   └─ [Health check path] — read references/knowledge-health.md
  │
  └─ Ambiguous?
      └─ ASK. Propose 2-3 specific options based on KB state.

---

判断のヒューリスティック

保存の意図の境界：

• 「これを保存して」／「記録して」／「書き留めて」＝書き込み
• 「検索して」／「要約して」／「調べて」＝読み取り専用
• 「整理して」→確認する：表示だけか、書き戻しもするか？
• 「これらを整理して」／ファイル、現在のファイル、アップロード、範囲の指定がない曖昧な対象 →何を整理するのか確認します。Inbox/、特定の Space、現在のファイルなど具体的な範囲を提示するための簡単なリスト／ツリー確認を1回だけ行うのは許容されますが、確認前に移動したり、内容を詳しく調べたりしてはいけません。
• 「次の手順を教えて」→SOP またはワークフローを読み、パスとともに次の手順を回答して終了します。ユーザーが続行を求めていない限り、実行、下書き、保存、書き込み、続行を提案してはいけません。

ファイルの保存場所が不明な場合：

• 5秒で判断できない → Inbox/ に保存し、ユーザーに伝え、後で分類することを提案します
• 「とりあえずどこかに置いて」／「先放着」 → Inbox/ に保存します
• 保存場所を指定せずにユーザーがファイルをドラッグしたり、構造化されていない内容を貼り付けたりした場合 → Inbox/

安定した振り分けとファイル名：

• 関連する既存ファイルが明らかな場合は、重複ファイルを作成せず、そのファイルを更新します。
• すでに明らかな既存ファイルに記録済みの事実を記録するよう明示的に求められた場合は、そのファイルを最小限更新するか、すでにそこに記録されていると伝えます。重複する Inbox メモを作成するかどうか尋ねてはいけません。
• デバッグで得た教訓は、Debugging/ ディレクトリがある場合はそこに保存します。引き継ぎは Handoffs/、会議メモは Meetings/、保存先が明確でない簡単な記録は Inbox/ に保存します。
• 明示的な引き継ぎの依頼では、利用可能な場合はローカルの引き継ぎガイダンスを読んだうえで、Handoffs/ に簡潔なメモを1つ作成または更新します。目的、関連ファイル、検証状況、残るリスクを含め、保存したパスを報告します。
• 新しいファイル名は具体的なトピックに基づいて付けます。KB に別の規則が示されていない場合は、小文字の ASCII ケバブケースを使用します。既存の製品トークンや同階層の既存の表記（mindroot と mind-root など）をそのまま使い、独自の表記を作ってはいけません。
• 気の利いた要約よりも、内容が長く使える主題ベースのファイル名を優先します。Agent ベンチマークの MIND_ROOT に関するデバッグメモには agent-benchmark-mindroot... というファイル名を使用します。Skill の最適化とクエリのリプレイに関する簡単な記録では、可能であれば skill-optimization と主要トピックの両方をファイル名に含めます。
• ユーザーが「現在のファイル」と言った場合、安全上の問題やローカルのガバナンスに反しない限り、currentFile を対象として扱います。

範囲の拡大：

• 入力の振り分け先が5ファイルを超える → いったん停止して、範囲を確認します
• 複数のトピックにまたがる「これらをすべて更新して」 → バッチに分けます

引用： KB の記載内容を引用する場合は、ファイルパスを含める必要があります。

---

タスク後のフック

書き込みタスクの後（単純な読み取りのみの場合を除く）は、この表を確認します。提案は最大1件とし、優先度が最も高いものを選びます。最初に .mindos/user-preferences.md を確認し、抑制設定を調べます。

フック	優先度	条件
経験の記録	高	デバッグ、トラブルシューティング、または複数回にわたる作業
一貫性の同期	高	バックリンクのあるファイルを編集した
SOP の乖離	中	SOP に従ったが、手順から外れた
関連項目の更新	中	関連ドキュメントがある CSV／TODO のステータスを変更した
構造の分類	中	Inbox／一時保存場所にファイルを作成した
パターンの抽出	低	今回のセッションで類似の操作を3回以上行った

フックが該当する場合は、references/post-task-hooks.md を読みます。

設定の記録

ユーザーが継続的な設定を表明した場合は、references/preference-capture.md を読み、確認してから書き込む手順に従います。

「これからは……」「次回は……」「以后……」など、将来に関する設定の表明は設定のシグナルであり、自動的に書き込みを許可するものではありません。「この設定を保存／記録して」と明示的に言われない限り、設定を確認したことを伝え、保存するかどうか尋ねます。

SOP の作成

SOP を作成または書き直す場合は、references/sop-template.md を読みます。

Inbox（ステージングエリア）

Inbox/ ディレクトリは、KB のクイックキャプチャ用エリアです。動作を規定する独自の INSTRUCTION.md があります。

Inbox を使用するタイミング：

• ユーザーが保存先を指定せずに「とりあえず保存して」／「先放着」／「放到收集箱」と言った場合
• コンテンツが既存の Space やディレクトリのどれにも明確に当てはまらない場合
• 個別の分類が必要な複数ファイルを一括インポートする場合

Inbox に保存する方法：

mindos file create "Inbox/<filename>.md" --content "..."

Inbox を整理する方法：

1. Inbox のファイルを一覧表示します：mindos file list Inbox/
2. 各ファイルを読み、その内容を把握します
3. 各ファイルについて、KB の構造に基づいて最適な移動先ディレクトリを提案します
4. 移動先の計画全体をユーザーに提示し、承認を得ます。「routing plan」／「路由方案」などの明確な言葉を使い、各ソースファイルのパスを含めます
5. ファイルを移動します：mindos file rename "Inbox/<file>" "<target-dir>/<file>"
6. 移動後、移動先ディレクトリの README を更新する必要があるか確認します

滞留リマインダー： Inbox に 7 日以上あるファイルは「滞留中」とみなします。初期化時に滞留中のファイルに気づいた場合は、「Inbox に 1 週間以上置かれているファイルが N 件あります。整理をお手伝いしましょうか？」と伝えます。

ナレッジの健全性チェック

ユーザーがナレッジの健全性チェック、矛盾の検出、品質監査を依頼した場合、または「知识健康检查」／「检测冲突」と言った場合は、references/knowledge-health.md を読んで手順全体を確認します。

チェック対象の概要：

• 矛盾：同じトピックに関するファイル間の事実の食い違い
• リンク切れ：存在しなくなったファイルへの参照
• 古いコンテンツ：日付の記載が古いファイル、または 6 か月以上更新されていないファイル

失敗時の復旧

ユーザーが指定したファイルパスが存在しない場合：

1. 要求されたパスが存在しないことを伝えます。
2. 文字どおりの「missing」という単語だけでなく、ファイル名とユーザーの表現から復旧用の検索クエリを推測します。
3. 代替候補となる記録を検索または一覧表示します。
4. 代替候補がある場合は、最有力候補のパスを示します。ない場合は、関連する記録が見つからなかったことと、確認した内容を伝えます。

• 重複：相互参照のない、同じ内容を扱う 2 つのファイル
• 孤立ファイル：バックリンクがなく、見つけにくいファイル
• 構造上の問題：誤ったディレクトリ、README の欠落、Inbox 内の滞留ファイル

---

エラー処理（CLI）

"command not found: mindos"  → npm install -g @geminilight/mindos
"Mind root not configured"   → mindos onboard
"401 Unauthorized"           → Check AUTH_TOKEN: mindos token (on server)
"ECONNREFUSED"               → Start server: mindos start