mindos-zh

MindOS スキル

CLI コマンド

mindos file <子命令> を使って、すべてのナレッジベース操作を行います。構造化出力を取得するには --json を追加します。

操作	コマンド
ファイルを一覧表示	mindos file list
ファイルを読み取る	mindos file read <パス>
書き込み／上書き	mindos file write <パス> --content "..."
新規ファイルを作成	mindos file create <パス> --content "..."
内容を追加	mindos file append <パス> --content "..."
セクションを編集	mindos file edit-section <パス> -H "## タイトル" --content "..."
見出しの後に挿入	mindos file insert-heading <パス> -H "## タイトル" --content "..."
CSV 行を追加	mindos file append-csv <パス> --row "列1,列2,列3"
ファイルを削除	mindos file delete <パス>
名前変更／移動	mindos file rename <旧> <新>
検索	mindos search "关键词"
バックリンク	mindos file backlinks <パス>
最近使ったファイル	mindos file recent --limit 10
Git 履歴	mindos file history <パス>
スペースを一覧表示	mindos space list
スペースを作成	mindos space create "名称"

MCP ユーザー： MCP ツール（mindos_*）しかない場合は、そのまま使用してください。ツールのスキーマには説明が含まれています。CLI がある場合は、CLI を優先してください（トークンを節約できます）。

CLI のインストール

npm install -g @geminilight/mindos
# 远程模式：mindos config set url http://<IP>:<端口> && mindos config set authToken <token>

---

ルール

1. まず構造を把握します — ナレッジベースのディレクトリツリーを一覧表示してから、検索または書き込みを行います。
2. デフォルトは読み取り専用です。 ユーザーが保存、記録、整理、編集を明確に求めた場合にのみ書き込みます。
3. ルールの優先順位（高い順）：ユーザーの現在の指示 → .mindos/user-preferences.md → 最も近いディレクトリの INSTRUCTION.md → ルートの INSTRUCTION.md → 本スキルのデフォルト。
4. 複数ファイルの編集は、まず計画を提示します。 変更内容の一覧をすべて示し、承認を得てから実行します。
5. 作成／削除／移動／名前変更の後は、関連する README を自動で同期します。
6. 書き込む前に読み取ります。 推測に基づいて書き込みません。
7. 自然に締めくくります。 返信ではユーザーが今回求めたことだけを完了します。十分な確認や書き込みが完了した後、不要な追加質問はしません。
8. ソースコードとの境界を守ります。 本スキルが扱うのは MindOS ナレッジベースのみです。ユーザーがアプリやプロジェクトのソースコード変更を求めているものの、ソースファイル、コード作業領域、コードツールがない場合は、具体的なリポジトリ／ファイル／コード片を尋ねます。コード変更を装うためにナレッジベースのノートを検索したり書き込んだりしてはいけません。コードだけの依頼では、ナレッジベースの list/search/read ツールを使ってソースファイルを探してはいけません。

---

回答の締めくくり

タスクの終了時には、次の契約に従って出力します。

• 検索／要約／引用： まず結論を示し、安定したファイルパスを添えて、読み取り専用を保ちます。ユーザーが具体的なローカルファイルパスを指定した場合、最終回答にその元のパスを含めます。ユーザーが変更しないよう明示した場合、または読み取り専用の処理を求めた場合は、最後にユーザーの言語で変更していないことを短く伝えます（中国語では「未做任何修改。」、英語では "No changes were made."）。ユーザーが次のステップを求めている場合や、根拠が不足している場合を除き、「保存／記録／更新しますか？」で終えてはいけません。
• 保存／更新／追加： 書き込みツールが成功した場合にのみ、実際のパスと操作を報告します。定型表現を使います：已保存到 <路径>、已更新 <路径>、已追加到 <路径>。さらに、ごく短い要約を一文添えるだけにします。
• アップロードされた内容の書き込み： ユーザーがアップロード内容をノートにまとめるよう求め、保存先の種類が明確な場合は、アップロード内容をそのまま使用します。構造や README を軽く確認するのは最大 1 回とし、その後ノートに書き込みます。ディレクトリ一覧の提示だけで終えてはいけません。
• 確認が必要な場合： 不足情報によって保存先、範囲、コスト、安全性、可逆性が変わる場合にのみ質問します。一度に尋ねる質問は具体的に 1 つとし、必要であれば 2～3 個の選択肢を示します。
• 根拠がない場合、またはツールが失敗した場合： 何が見つからなかったか、どの操作が失敗したか、次にどうすれば復旧できるかを明確に伝えます。根拠のない検索タスクでは、ユーザーが記録を求めていない限り、そのアイデアの保存、記録、作成、補足を自発的に提案してはいけません。返信を空にしてはいけません。
• 言語を忠実に保ちます： ユーザーの言語と元のノートの重要な用語を維持します。中国語のノートにある用語は、安易に英語へ翻訳せず、原文を優先します。役立つ場合に限り、英語の説明を括弧内に添えます。
• 読み取り専用の締めくくり： ユーザーが求めたのが要約、会議の文脈、または次のステップのみの場合は、回答したら終了します。「保存／記録／草案作成／書き込み／補足／調整／エクスポート／続行しますか？」などと追加で尋ねてはいけません。最後の文は質問ではなく、叙述文にします。SOP またはワークフローに基づいて回答する場合は、根拠とした SOP／ワークフローのパスを必ず引用します。次のステップだけを尋ねられた場合、実行するかどうかを聞き返してはいけません。

---

検索戦略

ナレッジの検索では、次の 2 つの経路を使い、まず絞り込んでから詳しく読みます。

経路 1：ディレクトリ構造のスキャン

まずナレッジベースのディレクトリツリーとファイル名を確認します。タイトルやディレクトリ名だけで答えが分かることもよくあります。たとえばユーザーが「認証方式」について尋ねていて、Decisions/auth-jwt-vs-session.md が見つかった場合は、有力な候補なのでそのまま読めます。

• Bootstrap 後、質問のテーマに関連するパスやディレクトリ名をまずスキャンします。
• ディレクトリの意味に注意します。Decisions/、Projects/、Workflows/、Resources/ などは、それぞれ異なる種類の内容を表します。
• 小規模なナレッジベース（ファイル数 50 未満）では、ツリーをざっと確認する方が検索より信頼できることがよくあります。

経路 2：全文検索

ファイル名から内容が分からない場合は、本文を検索します。

• ユーザーの言葉からキーワードを抽出します。ユーザーが「すごく遅いあの API」と言った場合、「遅い API」や「パフォーマンス API」で検索できます。
• 曖昧な検索を 4 回行うより、精度の高い検索を 1 回行う方が通常は効果的です。最初の結果が 3 件未満の場合、またはテーマに中国語・英語や略語の明らかな表記揺れがある場合にのみ、2 回目の検索を追加します。
• 毎回機械的に 2～4 回検索してはいけません。 まず判断してから、的確に検索します。

絞り込み：スニペットを確認してから詳しく読む

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

• スコアが高く、スニペットが明確に関連している → 全文を読みます。
• スコアが中程度で、スニペットが一部関連している → より良い候補がない場合に読みます。
• スコアが低い、またはスニペットが的外れ → 読まずに飛ばします。すべての検索結果に目を通してはいけません。
• 目標は 1～3 件のファイルを深く読むことであり、10 件のファイルに浅く目を通すことではありません。

---

禁止事項（苦い経験から学んだこと）

• 明確な指示がない限り、ナレッジベースのルートディレクトリに書き込んではいけません。 ルートディレクトリには管理ファイルのみを置き、新しい内容は最適なサブディレクトリに保存します。
• ディレクトリ名を推測してはいけません。 実際のディレクトリツリーから判断します。ナレッジベースでは中国語の名前やフラットな構成が使われている場合があります。
• 小さな変更にファイル全体の上書きを使ってはいけません。 mindos file edit-section または mindos file insert-heading で正確に編集します。ファイル全体を上書きすると git diff が損なわれます。
• 確認なしに INSTRUCTION.md や README.md を変更してはいけません。 これらは管理文書であり、取り扱いに注意が必要です。
• 周辺ファイルを確認せずにファイルを作成してはいけません。 まず対象ディレクトリのファイルを 1～2 件読み、命名規則とスタイルを把握します。
• 孤立した参照を残してはいけません。 名前変更／移動の後はバックリンクを確認し、すべての参照を更新します。
• 複数ファイルへの書き込み確認を省略してはいけません。 ユーザーの想定と異なる場合があります。

---

MindOS の概念

• スペース（Space） — あなたの思考方法に沿って整理されたナレッジの区分です。エージェントも同じ構造に従います。
• 指示（Instruction） — INSTRUCTION.md。接続されているすべてのエージェントが従うルールファイルです。
• スキル（Skill） — エージェントにナレッジベースの読み書きと整理の方法を教えます。
• 受信箱（Inbox） — Inbox/ ディレクトリは、情報をすばやく取り込むための領域です。一時的に置き場所が分からない内容はまずここに入れ、その後まとめて整理します。ユーザーが手動で行うことも、AI の支援を受けて一括分類することもできます。

ノートは指示とスキルの両方を担うことができます。どちらもディレクトリツリー内の Markdown ファイルにすぎません。

---

決定木

用户请求
  │
  ├─ 查找 / 总结 / 引用？
  │   └─ [只读路径]：搜索 → 读取 → 带引用回答。不写入。
  │
  ├─ 保存 / 记录 / 更新 / 整理具体内容？
  │   ├─ 知道放哪 → [单文件编辑]
  │   ├─ 不知道放哪 → [收集箱路径] — 存到 Inbox/，之后再归类
  │   └─ 多文件或不确定 → [多文件路由] — 先出方案
  │
  ├─ 整理收集箱 / 归类收集内容？
  │   └─ [收集箱整理] — 读 Inbox/ 文件，提议目标位置，获批后移动
  │
  ├─ 结构变更（重命名 / 移动 / 删除 / 重组）？
  │   └─ [结构路径] — 变更前后检查反向链接
  │
  ├─ 流程性 / 可重复任务？
  │   └─ [SOP 路径] — 找到并执行现有 SOP，或创建新的
  │
  ├─ 复盘 / 提炼 / 交接？
  │   └─ [复盘路径]
  │
  ├─ 知识健康检查 / 检测冲突？
  │   └─ [健康检查路径] — 读取 references/knowledge-health.md
  │
  └─ 模糊？
      └─ 提问。基于知识库状态提出 2-3 个具体选项。

---

判断启发

保存意图边界：

• "帮我记下来" / "保存" = 写入
• "搜一下" / "总结" = 只读
• "整理一下" → 先问：仅展示，还是写回知识库？
• "整理这些东西" 但没有文件、当前文件、上传内容或目标范围 → 先问要整理什么。最多允许一次轻量目录/树检查来给出 Inbox/、某个 Space、当前文件等具体选项；澄清前不要移动、编辑或深读内容。
• "告诉我下一步" → 读取 SOP 或 workflow，回答下一步和依据路径后停止。除非用户要求继续执行，不要追问是否现在执行、起草、保存、写入或继续。

文件位置不确定：

• 5 秒内定不了 → 存到 Inbox/，告知用户，之后提议归类
• "随便放哪" / "先放着" → 存到 Inbox/
• 用户拖拽文件或粘贴非结构化内容但没指定位置 → Inbox/

稳定路由和文件名：

• 如果明显存在相关文件，优先更新现有文件，不要新建重复笔记。
• 如果用户明确要求记录一条事实，而明显已有相关文件承载它，就局部更新该文件或说明它已经记录在那里。不要追问是否另存一份重复的 Inbox 笔记。
• 排错经验优先放 Debugging/；交接放 Handoffs/；会议记录放 Meetings/；归属不清的快速捕获放 Inbox/。
• 明确要求交接上下文时，读取可用的本地交接说明后，在 Handoffs/ 下创建或更新一份简洁交接笔记。包含目标、相关文件、验证状态和剩余风险，并报告保存路径。
• 新文件名从具体主题生成。除非目录已有其他约定，默认用小写 ASCII kebab-case。保留既有产品词和同目录命名习惯，例如 mindroot 与 mind-root 不要来回切换。
• 文件名优先表达可复用主题，不追求花哨概括：Agent benchmark 的 MIND_ROOT 排错经验应使用 agent-benchmark-mindroot...；Skill 优化和 query replay 的快速捕获，文件名尽量同时保留 skill-optimization 和核心主题。
• 用户说“当前文件”时，默认把 currentFile 作为目标，除非这会违反安全边界或局部治理规则。

范围蔓延：

• 输入路由到 >5 个文件 → 暂停确认
• "全部更新" + 跨多个主题 → 分批确认

引用规范： 引用知识库内容必须附带文件路径。

---

任务后钩子

写入任务（非简单读取）后扫描此表。最多 1 个提议；优先级最高的优先。先检查 .mindos/user-preferences.md 抑制项。

钩子	优先级	条件
经验沉淀	高	调试、排错或多轮工作
一致性同步	高	编辑的文件有反向链接
SOP 偏移	中	按 SOP 执行但实际偏离了步骤
关联更新	中	更改了 CSV/TODO 状态且有关联文档
结构分类	中	在临时位置或收集箱创建了文件
模式提取	低	本次会话中 3+ 个结构相似的操作

触发时 → 读取 references/post-task-hooks.md。

偏好捕获

用户表达持久偏好时 → 读取 references/preference-capture.md，按确认-写入流程操作。

类似"以后..."、"下次..."、"from now on..."的未来行为表达是偏好信号，不等于自动写入许可。除非用户明确说"保存/记录/写入这条偏好"，否则先确认是否保存。

SOP 编写

创建/重写工作流 SOP 时 → 读取 references/sop-template.md。

收集箱 (Inbox)

Inbox/ 目录是知识库的快速捕获区，有自己的 INSTRUCTION.md 约束行为。

何时使用收集箱：

• 用户说"先存着" / "放到收集箱" / "随便放哪"，没指定具体位置
• 内容明显不属于任何现有空间或目录
• 批量导入多个文件，需要逐个归类

如何存到收集箱：

mindos file create "Inbox/<文件名>.md" --content "..."

如何整理收集箱：

1. 列出暂存文件：mindos file list Inbox/
2. 读取每个文件，理解其内容
3. 根据知识库结构，为每个文件提议最佳目标目录
4. 向用户展示完整路由方案，获批后执行。明确使用"路由方案"等词，并列出每个源文件路径。
5. 移动文件：mindos file rename "Inbox/<文件>" "<目标目录>/<文件>"
6. 移动后检查目标目录的 README 是否需要更新

老化提醒： Inbox 中超过 7 天的文件视为"老化"。如果在 bootstrap 时发现老化文件，主动提醒： "收集箱有 N 个文件已经放了一周以上了，要我帮你整理一下吗？"

知识健康检查

用户要求检查知识库健康度、检测冲突、审计质量，或说"知识健康检查" / "检测冲突" / "check knowledge health" 时 → 读取 references/knowledge-health.md 获取完整流程。

检查维度速览：

• 矛盾/冲突：同一主题的不同文件说法互相矛盾
• 断裂链接：引用了不存在的文件
• 过期内容：带有过期日期标记的文件，或超过 6 个月未更新的活跃主题
• 重复内容：两个文件覆盖同一主题且没有互相引用
• 孤立文件：零反向链接，难以被发现
• 结构问题：文件放错目录、缺少 README、收集箱老化文件

失败恢复

当用户点名的文件路径不存在时：

1. 明确说明请求的路径不存在。
2. 从文件名和用户原话推断恢复检索词，不要只搜索字面上的 missing。
3. 搜索或扫描可能的替代记录。
4. 如果有候选，列出最强的替代路径；如果没有，说明没有找到相关记录，并说明查了什么。

---

错误处理（CLI）

"command not found: mindos"  → npm install -g @geminilight/mindos
"Mind root not configured"   → mindos onboard
"401 Unauthorized"           → 检查 AUTH_TOKEN：在服务器运行 mindos token
"ECONNREFUSED"               → 在服务器启动：mindos start