mindos

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

MindOS Skill

CLI commands

CLI 命令

Use

mindos file <subcommand>

for all knowledge base operations. Add

--json

for structured output.

Operation	Command
List files	`mindos file list`
Read file	`mindos file read <path>`
Write/overwrite	`mindos file write <path> --content "..."`
Create new file	`mindos file create <path> --content "..."`
Append to file	`mindos file append <path> --content "..."`
Edit section	`mindos file edit-section <path> -H "## Heading" --content "..."`
Insert after heading	`mindos file insert-heading <path> -H "## Heading" --content "..."`
Append CSV row	`mindos file append-csv <path> --row "col1,col2,col3"`
Delete file	`mindos file delete <path>`
Rename/move	`mindos file rename <old> <new>`
Search	`mindos search "query"`
Backlinks	`mindos file backlinks <path>`
Recent files	`mindos file recent --limit 10`
Git history	`mindos file history <path>`
List spaces	`mindos space list`
Create space	`mindos space create "name"`

MCP users: If you only have MCP tools (
mindos_*
), use them directly — they are self-describing via their schemas. Prefer CLI when available (lower token cost).

所有知识库操作均使用

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用户说明： 若仅拥有MCP工具（
mindos_*
），可直接使用——它们通过自身架构实现自描述。若有CLI可用则优先使用（更低的token消耗）。

CLI setup

CLI 安装配置

bash

npm install -g @geminilight/mindos

bash

npm install -g @geminilight/mindos

Remote mode: mindos config set url http://<IP>:<PORT> && mindos config set authToken <token>

远程模式：mindos config set url http://<IP>:<PORT> && mindos config set authToken <token>

---

---

Rules

规则

Bootstrap first — list the KB tree to understand structure before searching or writing.
Default to read-only. Only write when the user explicitly asks to save, record, organize, or edit. Lookup / summarize / quote = no writes.
Rule precedence (highest wins): user's current-turn instruction →
```
.mindos/user-preferences.md
```
→ nearest directory
```
INSTRUCTION.md
```
→ root
```
INSTRUCTION.md
```
→ this SKILL's defaults.
Multi-file edits require a plan first. Present the full change list; execute only after approval.
After create/delete/move/rename → sync affected READMEs automatically.
Read before write. Always read a file before overwriting it. Never write based on assumptions.

先初始化——在搜索或写入前，先列出知识库目录树以了解其结构。
默认只读。仅当用户明确要求保存、记录、整理或编辑时才执行写入操作。查询/总结/引用操作无需写入。
规则优先级（从高到低）：用户当前轮次的指令 →
```
.mindos/user-preferences.md
```
→ 最近目录下的
```
INSTRUCTION.md
```
→ 根目录下的
```
INSTRUCTION.md
```
→ 本Skill的默认规则。
多文件编辑需先制定计划。先呈现完整的变更清单，获得批准后再执行。
创建/删除/移动/重命名文件后 → 自动同步受影响的README文件。
先读后写。覆盖文件前务必先读取文件内容，切勿凭假设进行写入。

Retrieval strategy

检索策略

When retrieving knowledge, use two paths in parallel, then filter before deep-reading:

检索知识时，需并行使用两种路径，在深度阅读前先进行筛选：

Path 1: Directory scan (by name/structure)

路径1：目录扫描（按名称/结构）

Browse the KB tree and look at file names and directory names. Titles often reveal content without reading. If a user asks about "authentication", and you see

Decisions/auth-jwt-vs-session.md

, that's a strong candidate — read it directly, no search needed.

After bootstrap, scan the tree for paths whose names relate to the query topic.
Pay attention to directory semantics:
```
Decisions/
```
,
```
Projects/
```
,
```
Workflows/
```
,
```
Resources/
```
etc. each imply what kind of content lives there.
If the KB is small (<50 files), a quick tree scan may be faster and more reliable than search.

浏览知识库目录树，查看文件名和目录名。标题通常无需阅读即可揭示内容。若用户询问“认证相关内容”，而你看到

Decisions/auth-jwt-vs-session.md

，这就是强匹配候选——直接读取该文件，无需搜索。

初始化后，扫描目录树查找与查询主题相关的路径。
注意目录语义：
```
Decisions/
```
、
```
Projects/
```
、
```
Workflows/
```
、
```
Resources/
```
等目录分别代表不同类型的内容。
若知识库规模较小（<50个文件），快速扫描目录树可能比搜索更快、更可靠。

Path 2: Full-text search (by content)

路径2：全文搜索（按内容）

Use

search

for content that can't be guessed from file names alone.

Craft queries from the user's actual words. If the user says "那个很慢的接口", search for "慢接口" or "性能 API".
One well-targeted search is better than 4 vague ones. Only add a second search if the first returned <3 results or if the topic has obvious alternate terms (e.g., Chinese + English).
Do NOT mechanically fire 2-4 searches every time. Think first, search precisely.

对于无法通过文件名推断内容的情况，使用

search

命令。

根据用户的实际措辞构建查询语句。若用户说“那个很慢的接口”，则搜索“慢接口”或“性能 API”。
一次精准的搜索胜过四次模糊搜索。仅当第一次搜索返回结果<3条，或主题有明显替代术语（如中文+英文）时，才进行第二次搜索。
切勿每次都机械地执行2-4次搜索。先思考，再精准搜索。

Filter: snippet triage before full read

筛选：深度阅读前的片段筛选

Search results include a snippet and a BM25 score. Use them to decide what to read:

High score + snippet clearly on-topic → read full file.
Medium score + snippet partially relevant → read full file only if no better candidates exist.
Low score or snippet off-topic → skip. Do not read every search result.
Aim to read 1-3 files deeply, not 10 files superficially.

搜索结果包含片段和BM25分数。利用它们决定是否读取完整文件：

高分+片段明确匹配主题 → 读取完整文件。
中等分数+部分相关片段 → 仅在无更好候选文件时读取完整文件。
低分或片段偏离主题 → 跳过。无需读取所有搜索结果。
目标是深度阅读1-3个文件，而非肤浅浏览10个文件。

Combined example

组合示例

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.

用户："之前关于数据库选型的讨论"

步骤1（目录扫描）：看到 "Decisions/database-postgres-vs-mongo.md" → 名称强匹配。
步骤2（搜索）：执行 search("数据库选型") → 返回5条结果。
步骤3（筛选）：结果#1片段提及 "PostgreSQL vs MongoDB 对比"（分数18.3）→ 读取。
              结果#2片段提及 "数据库连接池配置"（分数4.1）→ 跳过，偏离主题。
              结果#3片段提及 "选型会议纪要"（分数12.7）→ 读取。
步骤4（回答）：引用实际读取的2-3个文件内容。

NEVER do (hard-won pitfalls)

绝对禁止操作（经验总结的避坑指南）

NEVER write to the KB root unless explicitly told. Root is for governance files only. New content goes under the most fitting subdirectory.
NEVER assume directory names. Infer from the actual bootstrap tree — the KB may use Chinese names or flat layout.
NEVER use full-file overwrite for a small edit. Use
```
mindos file edit-section
```
or
```
mindos file insert-heading
```
for targeted changes. Full rewrites destroy git diffs.
NEVER modify
INSTRUCTION.md
or
README.md
without confirmation. Governance docs — treat as high-sensitivity.
NEVER create a file without checking siblings. Read 1-2 files in the target directory to learn local style.
NEVER leave orphan references. After rename/move, check backlinks and update every referring file.
NEVER skip routing confirmation for multi-file writes. The user's mental model may differ from yours.
NEVER read every search result. Use snippet + score to triage. Only deep-read files that are clearly relevant.

绝对禁止写入知识库根目录，除非明确告知。根目录仅用于治理文件。新内容应放入最适合的子目录。
绝对禁止假设目录名称。根据实际初始化的目录树推断——知识库可能使用中文名称或扁平结构。
绝对禁止用全文件覆盖方式进行小修改。使用
```
mindos file edit-section
```
或
```
mindos file insert-heading
```
进行针对性修改。全量重写会破坏git差异记录。
绝对禁止未经确认修改
INSTRUCTION.md
或
README.md
。这些是治理文档——视为高敏感度内容。
绝对禁止创建文件前不查看同级文件。读取目标目录下1-2个文件以了解本地风格。
绝对禁止留下孤立引用。重命名/移动文件后，检查反向链接并更新所有引用该文件的内容。
绝对禁止多文件写入时跳过路由确认。用户的认知模型可能与你的不同。
绝对禁止读取所有搜索结果。利用片段+分数进行筛选。仅深度阅读明确相关的文件。

MindOS concepts

MindOS核心概念

Space — Knowledge partitions organized the way you think. Agents follow the same structure.
Instruction — A rules file (
```
INSTRUCTION.md
```
) all connected agents obey.
Skill — Teaches agents how to read, write, and organize the KB.
Inbox — The
```
Inbox/
```
directory is a staging area for quick capture. Files land here when there's no obvious home yet. They get organized later — by the user manually or via AI-assisted batch organization.

Notes can embody both Instruction and Skill — they're just Markdown files in the tree.

Space（空间）——按照你的思维方式组织的知识分区。所有Agent遵循相同结构。
Instruction（规则文件）——所有关联Agent需遵守的规则文件（
```
INSTRUCTION.md
```
）。
Skill（技能文件）——教Agent如何读取、写入和组织知识库的文件。
Inbox（收件箱）——
```
Inbox/
```
目录是快速捕获内容的暂存区。当内容暂无明确归属时，会先存放在此处。后续由用户手动或AI辅助批量整理。

笔记可同时承载Instruction和Skill——它们只是目录树中的Markdown文件。

Decision tree

决策树

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/，后续分类
  │   └─ 多文件或路径不明 → [多文件路由] —— 先制定计划
  │
  ├─ 整理收件箱/分类暂存文件？
  │   └─ [收件箱整理] —— 读取Inbox/文件，提议目标路径，获得批准后移动
  │
  ├─ 结构变更（重命名/移动/删除/重组）？
  │   └─ [结构变更流程] —— 操作前后检查反向链接
  │
  ├─ 流程化/重复性任务？
  │   └─ [SOP流程] —— 查找并遵循现有SOP，或创建新SOP
  │
  ├─ 复盘/提炼经验/交接？
  │   └─ [复盘流程]
  │
  ├─ 知识健康检查/检测冲突？
  │   └─ [健康检查流程] —— 读取references/knowledge-health.md
  │
  └─ 请求模糊？
      └─ 询问用户。根据知识库状态提出2-3个具体选项。

Judgment heuristics

判断启发规则

Save intent boundary:

"save this" / "record" / "write down" = write
"search" / "summarize" / "look up" = read-only
"organize" → ask: display only, or write back?

File location uncertainty:

Can't decide in 5 seconds → save to
```
Inbox/
```
, inform user, propose classification later
"Just put it somewhere" / "先放着" → save to
```
Inbox/
```
User drags files or pastes unstructured content without specifying location →
```
Inbox/
```

Scope creep:

Input routes to >5 files → pause, confirm scope
"Update all of these" spanning multiple topics → split into batches

Citation: KB-cited facts must include the file path.

保存意图边界：

"save this" / "记录" / "写下来" = 执行写入
"搜索" / "总结" / "查询" = 只读模式
"整理" → 询问用户：仅展示，还是需要写入修改？

文件位置不确定性：

5秒内无法决定存放路径 → 保存至
```
Inbox/
```
，告知用户，后续提议分类
"随便放哪里" / "先放着" → 保存至
```
Inbox/
```
用户拖拽文件或粘贴非结构化内容但未指定位置 →
```
Inbox/
```

范围蔓延：

输入需路由至>5个文件 → 暂停，确认范围
"更新所有这些内容"涉及多个主题 → 拆分为批次处理

引用规则： 从知识库引用的事实必须包含文件路径。

Post-task hooks

任务后钩子

After write tasks (not simple reads), scan this table. At most 1 proposal; highest priority wins. Check

.mindos/user-preferences.md

suppression first.

Hook	Priority	Condition
Experience capture	high	Debugging, troubleshooting, or multi-round work
Consistency sync	high	Edited file with backlinks
SOP drift	medium	Followed SOP but diverged
Linked update	medium	Changed CSV/TODO status with related docs
Structure classification	medium	Created file in inbox/temp location
Pattern extraction	low	3+ similar operations this session

If a hook triggers → read references/post-task-hooks.md.

完成写入任务后（简单读取任务除外），查看下表。最多提出1个建议；优先级最高的触发项生效。先检查

.mindos/user-preferences.md

中的抑制设置。

钩子	优先级	触发条件
经验捕获	高	调试、故障排查或多轮工作完成后
一致性同步	高	编辑了带有反向链接的文件
SOP偏差	中	遵循SOP但出现偏离
关联更新	中	修改了CSV/TODO状态且存在关联文档
结构分类	中	在收件箱/临时位置创建了文件
模式提取	低	本次会话中执行了3次以上相似操作

若钩子触发 → 读取references/post-task-hooks.md。

Preference capture

偏好捕获

When user expresses a standing preference → read references/preference-capture.md and follow confirm-then-write flow.

当用户表达长期偏好时 → 读取references/preference-capture.md并遵循“确认后写入”流程。

SOP authoring

SOP编写

When creating/rewriting an SOP → read references/sop-template.md.

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

Inbox (staging area)

Inbox（暂存区）

The

Inbox/

directory is the KB's quick-capture zone. It has its own

INSTRUCTION.md

that governs behavior.

When to use Inbox:

User says "just save it" / "先放着" / "放到暂存台" without specifying a location
Content doesn't clearly fit any existing Space or directory
Batch import of multiple files that need individual classification

How to save to Inbox:

bash

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

How to organize Inbox:

List Inbox files:
```
mindos file list Inbox/
```
Read each file to understand its content
For each file, propose the best destination directory based on KB structure
Present the full routing plan to user for approval

Move files:

mindos file rename "Inbox/<file>" "<target-dir>/<file>"

After moving, check if the target directory's README needs updating

Aging reminder: Files in Inbox older than 7 days are considered "aging". If you notice aging files during bootstrap, mention it: "You have N files in Inbox that have been sitting there for over a week. Want me to help organize them?"

Inbox/

目录是知识库的快速捕获区域。它有自己的

INSTRUCTION.md

文件来规范行为。

使用Inbox的场景：

用户说“先保存” / “先放着” / “放到暂存台”但未指定位置
内容无法明确适配现有Space或目录
批量导入多个需要单独分类的文件

保存至Inbox的方法：

bash

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

整理Inbox的方法：

列出Inbox文件：
```
mindos file list Inbox/
```
读取每个文件以理解内容
针对每个文件，根据知识库结构提议最佳目标目录
向用户呈现完整的路由计划并等待批准

移动文件：

mindos file rename "Inbox/<file>" "<target-dir>/<file>"

移动完成后，检查目标目录的README是否需要更新

过期提醒： Inbox中存放超过7天的文件视为“过期”。若在初始化时发现过期文件，需告知用户：“你有N个文件在Inbox中存放已超过一周，需要我帮忙整理吗？”

Knowledge health check

知识健康检查

When user asks to check knowledge health, detect conflicts, audit quality, or says "知识健康检查" / "检测冲突" → read references/knowledge-health.md for the full procedure.

Quick summary of what gets checked:

Contradictions: conflicting facts across files on the same topic
Broken links: references to files that no longer exist
Stale content: files with outdated date markers or untouched for >6 months
Duplicates: two files covering the same ground without cross-referencing
Orphan files: files with zero backlinks, hard to discover
Structural issues: wrong directory, missing READMEs, aging Inbox files

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

检查内容快速总结：

矛盾内容：同一主题下不同文件中的事实冲突
失效链接：引用了已不存在的文件
过期内容：带有过时日期标记或超过6个月未更新的文件
重复内容：两个文件内容重复但未相互引用
孤立文件：无任何反向链接，难以被发现的文件
结构问题：存放目录错误、缺少README、Inbox文件过期

Error handling (CLI)

错误处理（CLI）

bash

"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

bash

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