@geminilight/mindos 0.6.39 → 0.6.41

package/_standalone/data/skills/mindos/SKILL.md

@@ -15,152 +15,152 @@ description: >
 
 # MindOS Skill
 
-<!-- version: 1.3.2 -->
+<!-- version: 3.0.0 — CLI-first, MCP optional -->
+
+## CLI commands
+
+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).
+
+### CLI setup
+
+```bash
+npm install -g @geminilight/mindos
+# Remote mode: mindos config set url http://<IP>:<PORT> && mindos config set authToken <token>
+```
+
+---
 
-**Before every task, internalize these 5 rules:**
+## Rules
 
-1. The **bootstrap directory tree is the primary index** — reason from names and hierarchy before calling search. Most questions can be answered by reading what's already in context.
-2. **Default to read-only.** Only invoke write tools when the user explicitly asks to save, record, organize, or edit. Lookup / summarize / quote = no writes.
-3. **Rule precedence** (highest wins): user's current-turn instruction → `user-skill-rules.md` → nearest directory `INSTRUCTION.md` → root `INSTRUCTION.md` → this SKILL's defaults.
+1. **Bootstrap first** — list the KB tree to understand structure before searching or writing.
+2. **Default to read-only.** Only write when the user explicitly asks to save, record, organize, or edit. Lookup / summarize / quote = no writes.
+3. **Rule precedence** (highest wins): user's current-turn instruction → `.mindos/user-preferences.md` → nearest directory `INSTRUCTION.md` → root `INSTRUCTION.md` → this SKILL's defaults.
 4. **Multi-file edits require a plan first.** Present the full change list; execute only after approval.
 5. After create/delete/move/rename → **sync affected READMEs** automatically.
+6. **Read before write.** Always read a file before overwriting it. Never write based on assumptions.
 
 ---
 
 ## NEVER do (hard-won pitfalls)
 
-- **NEVER write to the KB root** unless the user explicitly says so. Root is for governance files only (`README.md`, `INSTRUCTION.md`, `CONFIG`). New content goes under the most semantically fitting subdirectory.
-- **NEVER assume directory names.** Don't hardcode `Workflows/`, `Projects/`, `Contacts/` — always infer from the bootstrap tree you actually received. The user's KB may use Chinese names, flat layout, or unconventional hierarchy.
-- **NEVER use `mindos_write_file` for a small edit.** Use `update_section`, `update_lines`, or `insert_after_heading` — full-file rewrites destroy git diffs and make changes unauditable.
-- **NEVER search with a single keyword.** Always fire 2-4 parallel searches (synonyms, abbreviations, Chinese/English variants). One keyword misses too much.
-- **NEVER modify `INSTRUCTION.md` or `README.md` without confirmation.** These are governance docs — treat as high-sensitivity even for trivial-looking typo fixes.
-- **NEVER create a file without checking siblings first.** Read at least 1-2 files in the target directory to learn local naming, heading style, and CSV schema. Inventing a new convention is a common cause of inconsistency.
-- **NEVER leave orphan references.** After any rename/move, run `get_backlinks` and update every referring file. Missing this is the #1 source of broken links in a KB.
-- **NEVER skip the routing confirmation for multi-file writes.** Even when the destinations seem obvious — the user's mental model may differ from yours.
+- **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 search with a single keyword.** Fire 2-4 parallel searches (synonyms, abbreviations, Chinese/English variants).
+- **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.
 
 ---
 
 ## MindOS concepts
 
 - **Space** — Knowledge partitions organized the way you think. Agents follow the same structure.
-- **Instruction** — A rules file all connected agents obey. Written once, enforced everywhere.
-- **Skill** — Teaches agents how to read, write, and organize the KB. Agents execute installed Skills, not guesses.
+- **Instruction** — A rules file (`INSTRUCTION.md`) all connected agents obey.
+- **Skill** — Teaches agents how to read, write, and organize the KB.
 
-**Notes as Instruction and Skill** — `INSTRUCTION.md` and `SKILL.md` are just Markdown files in the tree. A note can be free-form text, governance rules agents must follow, or a procedure package agents execute.
+Notes can embody both Instruction and Skill — they're just Markdown files in the tree.
 
 ---
 
-## Thinking framework
-
-Before acting, ask yourself:
-
-1. **What is the user's intent category?** → read-only lookup | single-file edit | multi-file routing | structural change | SOP execution. This determines which path to take below.
-2. **Where does this content belong?** → Scan the directory tree. If you can't place it in <5 seconds of looking at names, the user probably needs to confirm.
-3. **What already exists nearby?** → Read 1-2 sibling files before writing. Match their style.
-4. **What will break if I change this?** → For renames/moves: `get_backlinks`. For content edits: think about who else cites this fact.
-5. **Am I being asked, or am I volunteering?** → If the user didn't ask you to write, don't write.
-
----
-
-## Task routing decision tree
+## Decision tree
 
 ```
 User request
   │
-  ├─ Only asks to look up / summarize / quote?
-  │   └─ YES → [Read-only path]: search + read + cite sources. No writes. Skip hooks.
+  ├─ Lookup / summarize / quote?
+  │   └─ [Read-only]: search → read → answer with citations. No writes.
   │
-  ├─ Asks to save / record / update / organize specific content?
-  │   ├─ Single file target? → [Single-file edit]
-  │   └─ Multiple files or unclear target? → [Multi-file routing]
+  ├─ Save / record / update / organize specific content?
+  │   ├─ Single file → [Single-file edit]
+  │   └─ Multiple files or unclear → [Multi-file routing] — plan first
   │
   ├─ Structural change (rename / move / delete / reorganize)?
-  │   └─ [Structural path]
+  │   └─ [Structural path] — check backlinks before and after
   │
   ├─ Procedural / repeatable task?
-  │   └─ [SOP path]
+  │   └─ [SOP path] — find and follow existing SOP, or create one
   │
   ├─ Retrospective / distill / handoff?
   │   └─ [Retrospective path]
   │
-  └─ Ambiguous or too broad?
-      └─ ASK for clarification. Propose 2-3 specific options based on KB state. Do NOT start editing.
+  └─ Ambiguous?
+      └─ ASK. Propose 2-3 specific options based on KB state.
 ```
 
-**For any write/SOP/structural path above → the write supplement is already loaded in context (see `## Write & Workflow Supplement` section below or in the next context block).**
-
----
-
-## Tool selection
-
-| Intent | Best tool | Avoid |
-|--------|-----------|-------|
-| Load context at start | `mindos_bootstrap` | Reading random files without bootstrap |
-| List top-level Mind Spaces | `mindos_list_spaces` | Full `mindos_list_files` when you only need zone names and README blurbs |
-| Find files | `mindos_search_notes` (2-4 parallel keyword variants) | Single-keyword search |
-| Read content | `mindos_read_file` or `mindos_read_lines` (for large files) | Reading entire large file when you need 10 lines |
-
-Write, structural, and history tools → see Write & Workflow Supplement (loaded below or in next context block).
-
-### Fallbacks
-
-- `mindos_bootstrap` unavailable → manual reads of root `INSTRUCTION.md` + `README.md`.
-- Search returns empty → don't give up: (1) scan tree in context, (2) read candidate files directly, (3) `mindos_list_files` on specific subdirectories, (4) try synonym/alternate-language keywords.
-
----
-
-## Execution patterns
-
-| Pattern | When | Key steps |
-|---------|------|-----------|
-| **Read-only Q&A** | Lookup / summarize / quote | Tree reasoning → search → read → answer with citations → state gaps |
-
-For write, SOP, structural, and handoff patterns → see Write & Workflow Supplement (loaded below or in next context block).
-
 ---
 
 ## Judgment heuristics
 
-**Save intent — read vs. write boundary**
-- "帮我记下来" / "记录一下" / "保存这个" = write
-- "搜一下有没有关于 X 的笔记" / "总结上周的工作" = read-only
-- Ambiguous boundary ("整理一下这些内容") → ask first: display only, or write back to KB?
+**Save intent boundary:**
+- "帮我记下来" / "保存" = write
+- "搜一下" / "总结" = read-only
+- "整理一下" → ask: display only, or write back?
 
-**File location uncertainty**
-- 扫目录树 5 秒内定不下来 → don't invent a new directory; use the nearest semantically-fit existing one and inform the user
-- User says "just put it somewhere" → place in inbox or top-level general directory, propose classification after (triggers Structure classification hook)
+**File location uncertainty:**
+- Can't decide in 5 seconds → use nearest existing directory, inform user
+- "Just put it somewhere" → inbox, propose classification after
 
-**Scope creep signals**
-- Single input routes to >5 files → pause, confirm scope; users rarely intend bulk rewrites
-- "Update all of these" + content spans multiple topics → split into batches, confirm each, don't execute all at once
+**Scope creep:**
+- Input routes to >5 files → pause, confirm scope
+- "Update all of these" spanning multiple topics → split into batches
 
-**Citation discipline**
-- KB-cited facts must include the file path so the user can verify
+**Citation:** KB-cited facts must include the file path.
 
 ---
 
 ## Post-task hooks
 
-After **write tasks** (not simple single-file edits or read-only), scan this table. If a condition matches, make a one-line proposal. At most 1 proposal; pick highest priority. Check `user-skill-rules.md` suppression section first. Skip all if user asked for quiet mode.
+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 took multiple rounds |
-| Consistency sync | high | Edited file A which has backlinks (check `get_backlinks`) |
-| SOP drift | medium | Followed an SOP but execution diverged from its steps |
-| Linked update | medium | Changed a CSV/TODO status and related docs exist |
-| Structure classification | medium | Created a file in a temporary location or inbox |
-| Pattern extraction | low | 3+ structurally similar operations this session |
-| Conversation retrospective | low | Session >10 turns with decisions or trade-offs |
+| 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](./references/post-task-hooks.md) for the propose format and any user-defined hooks. If nothing matches, end quietly — do not read the file.
+If a hook triggers → read [references/post-task-hooks.md](./references/post-task-hooks.md).
 
 ## Preference capture
 
-When the user expresses a standing preference ("don't do X", "always put Y in Z"), read [references/preference-capture.md](./references/preference-capture.md) and follow the confirm-then-write flow to `user-skill-rules.md`.
-**Do NOT read** preference-capture unless the user actually expressed a preference to persist.
+When user expresses a standing preference → read [references/preference-capture.md](./references/preference-capture.md) and follow confirm-then-write flow.
 
 ## SOP authoring
 
-When creating or rewriting a workflow SOP, **MANDATORY — read [references/sop-template.md](./references/sop-template.md)** for required structure (prerequisites, steps with branches, exit conditions, pitfall log).
-**Do NOT read** sop-template for SOP execution (only for SOP creation/editing).
+When creating/rewriting an SOP → read [references/sop-template.md](./references/sop-template.md).
+
+---
+
+## Error handling (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
+```

package/_standalone/data/skills/mindos/references/write-supplement.md

@@ -0,0 +1,119 @@
+# MindOS Write & Workflow Supplement
+
+<!-- Always injected alongside SKILL.md by route.ts for every request. -->
+<!-- For read-only lookups, Q&A, and summarization this context is also available. -->
+
+---
+
+## NEVER do (write-path specific)
+
+- **NEVER use `mindos_write_file` as your first move.** Writing without reading first means replacing content you haven't seen. Even when you "know" the file's content, read it — your assumption may be stale.
+- **NEVER create a Mind Space with `mindos_create_file`.** That only creates a plain directory — no README, no INSTRUCTION scaffolding. A Space missing its governance files is broken from birth. Use `mindos_create_space`.
+- **NEVER write immediately after bootstrap.** Bootstrap gives you the top-level structure; it does NOT tell you whether a local `INSTRUCTION.md` near your target overrides the root rules. Read local governance before touching anything.
+- **NEVER execute multi-file writes without first showing the routing table.** Even when destinations seem obvious — the user's mental model diverges from yours more often than intuition suggests. Show the table, wait for confirmation.
+- **NEVER use `mindos_append_to_file` on structured files.** Blind appending ignores section order. If the file has headings, required fields, or schema constraints, use `insert_after_heading` or `update_section` to land content in the right place.
+
+---
+
+## Write tool selection
+
+| Intent | Best tool | Avoid |
+|--------|-----------|-------|
+| Small text edit | `mindos_update_section` / `mindos_update_lines` / `mindos_insert_after_heading` | `mindos_write_file` for small changes |
+| Append to end | `mindos_append_to_file` | Rewriting entire file to add a line |
+| Full file replacement | `mindos_write_file` | Using this when a section edit suffices |
+| New file | `mindos_create_file` | Creates parent dirs but does NOT scaffold Space files |
+| New Mind Space (zone + README + INSTRUCTION) | `mindos_create_space` | The only way to create a Space. `create_file` creates plain folders |
+| Rename a Space directory | `mindos_rename_space` | `rename_file` (files only; does not rename folders) |
+| Add CSV row | `mindos_append_csv` (validates header) | Manual string append without header check |
+| Check impact before rename | `mindos_get_backlinks` | Renaming without checking references |
+| Inspect recent changes | `mindos_get_recent` | Guessing what changed recently |
+| Recover old version | `mindos_get_file_at_version` | Asking user to recall what was there |
+
+**Fallback:** Line/section tools unavailable → read + constrained `mindos_write_file` (simulate minimal edit).
+
+---
+
+## Startup protocol
+
+Run this before executing any write path:
+
+1. **Bootstrap** — `mindos_bootstrap` (preferred) or manually read root `INSTRUCTION.md` + `README.md`.
+2. **Discover structure**
+   - Only need top-level zones? → `mindos_list_spaces` (lighter; includes README blurbs)
+   - Need a specific file path? → confirm zone with `mindos_list_spaces`, then `mindos_list_files` inside that zone
+   - Know keywords? → fire 2-4 parallel `mindos_search_notes` covering CN/EN variants and abbreviations
+   - **Never assume top-level directory names** — the user's KB may use Chinese, pinyin, or unconventional hierarchy
+3. **Load local governance** — Read `README.md` / `INSTRUCTION.md` near the target path. Local conventions override global assumptions.
+4. **Match existing SOP** — If the task is procedural: scan tree for a procedure-holding directory (names like `Workflows/`, `SOPs/`, `流程/` are hints — don't assume). Search by keywords + `<!-- keywords: -->` metadata. If found, read and follow. If execution diverges, propose updating the SOP after.
+5. **Pre-write checks** — Confirm: target path exists or should be created; location is under a subdirectory (not root); current content is read; edit scope is minimal; backlink impact assessed for path changes.
+6. **Execute edits.**
+
+If context is missing, continue with best effort and state assumptions.
+
+---
+
+## Execution patterns
+
+| Pattern | When | Key steps |
+|---------|------|-----------|
+| **Single-file edit** | One clear target file | Startup → read target + local conventions → minimal edit → verify → summarize |
+| **Multi-file routing** | Unstructured input, multiple destinations | Parse into semantic units → routing table → confirm → edit → summarize |
+| **Conversation retrospective** | Distill / capture session | Confirm scope → extract decisions/pitfalls/actions → route → trace changes |
+| **SOP execution** | Repeatable procedure | Read SOP fully → execute stepwise → update stale sections → propose SOP update if diverged |
+| **Structural change** | Rename / move / delete | `get_backlinks` → impact report → confirm → execute → update refs → sync READMEs |
+| **CSV append** | Add row to a table | Read header → validate fields → `mindos_append_csv` |
+| **Cross-agent handoff** | Continue another agent's work | Read task state + decisions → continue without re-discovery → write back progress |
+| **Periodic review** | Summarize recent changes | `get_recent`/`get_history` → read changed files → structured summary |
+| **Handoff doc** | Create a briefing | Read sources → synthesize (background, decisions, status, open items) → place in project dir |
+
+---
+
+## Detailed execution steps
+
+### Single-file edit
+Search → read target + read 1-2 sibling files for local conventions → apply minimal edit (prefer `update_section` / `update_lines` / `insert_after_heading` over full rewrite) → verify heading/style match → summarize what changed.
+
+### Multi-file routing
+Parse unstructured input into discrete semantic units → for each unit: search 2-4 keyword variants to find best-fit file → **present routing table** (content snippet → target file → insertion point) → wait for user confirmation → execute edits one file at a time → summarize all changes with file paths.
+
+### Conversation retrospective
+Confirm scope (which session? which topics?) → extract: decisions made, rationale, pitfalls encountered, next actions → for each artifact, find the best existing file via search → route each to the right place → append a one-line change trace per file touched.
+
+### SOP execution
+Read the full SOP before starting (never skim) → execute step by step, checking off as you go → if a step is stale or diverges from current KB state, note it → after completion, propose a targeted SOP update for any diverged steps.
+**Creating a new SOP** → first read [references/sop-template.md](./references/sop-template.md) for required structure.
+
+### Structural changes
+`get_backlinks` on the path being changed → present impact report (N files will need updates) → wait for confirmation → execute rename/move/delete → update every backlink → sync affected `README.md` files.
+
+### Handoff / cross-agent continuation
+Read the handoff document or last agent's progress notes → identify: current state, decisions already made, open items → continue from that state without re-running discovery already done → write progress back to the same handoff doc when done.
+
+---
+
+## Post-task hooks
+
+After **write tasks** (not simple single-file edits or read-only), scan this table. If a condition matches, make a one-line proposal. At most 1 proposal; pick highest priority. Check `.mindos/user-preferences.md` suppression section first. Skip all if user asked for quiet mode.
+
+| Hook | Priority | Condition |
+|------|----------|-----------|
+| Experience capture | high | Debugging, troubleshooting, or took multiple rounds |
+| Consistency sync | high | Edited file A which has backlinks (check `get_backlinks`) |
+| SOP drift | medium | Followed an SOP but execution diverged from its steps |
+| Linked update | medium | Changed a CSV/TODO status and related docs exist |
+| Structure classification | medium | Created a file in a temporary location or inbox |
+| Pattern extraction | low | 3+ structurally similar operations this session |
+| Conversation retrospective | low | Session >10 turns with decisions or trade-offs |
+
+If a hook triggers → read [references/post-task-hooks.md](./references/post-task-hooks.md) for the propose format and any user-defined hooks. If nothing matches, end quietly — do not read the file.
+
+## Preference capture
+
+When the user expresses a standing preference ("don't do X", "always put Y in Z"), read [references/preference-capture.md](./references/preference-capture.md) and follow the confirm-then-write flow to `.mindos/user-preferences.md`.
+**Do NOT read** preference-capture unless the user actually expressed a preference to persist.
+
+## SOP authoring
+
+When creating or rewriting a workflow SOP, **MANDATORY — read [references/sop-template.md](./references/sop-template.md)** for required structure (prerequisites, steps with branches, exit conditions, pitfall log).
+**Do NOT read** sop-template for SOP execution (only for SOP creation/editing).

package/_standalone/data/skills/mindos-zh/SKILL.md

@@ -2,164 +2,160 @@
 name: mindos-zh
 description: >
   操作 MindOS 知识库：更新笔记, 搜索知识库, 整理文件, 执行SOP/工作流, 复盘, 追加CSV, 跨Agent交接,
-  路由非结构化输入到对应文件, 提炼经验, 同步关联文档.
-  update notes, search knowledge base, organize, SOP, retrospective, CSV, handoff, route notes, distill experience.
+  路由非结构化输入到对应文件, 提炼经验, 同步关联文档. update notes, search knowledge base, organize,
+  SOP, retrospective, CSV, handoff, route notes, distill experience.
   仅 mindRoot 知识库内任务。不用于：改代码仓库/项目文档/KB 外路径。
   核心概念：空间、指令(INSTRUCTION.md)、技能(SKILL.md)；笔记可承载指令与技能。
-  当用户说"帮我记下来"、"搜一下我的笔记"、"更新知识库"、"整理文件"、"执行工作流"、
-  "记录这次会议的决策"、"追加到表格"、"交接给下一个 Agent" 时触发。
-  也适用于：save/record a note, search KB, update/edit files, run SOP, capture decisions,
-  append CSV rows, cross-agent handoff — 所有 mindRoot 知识库内的读写操作。
 ---
 
-# MindOS Skill
+# MindOS 技能
 
-<!-- version: 1.3.2 -->
+<!-- version: 3.0.0 — CLI 优先，MCP 可选 -->
 
-**每次任务前，内化这 5 条规则：**
+## CLI 命令
 
-1. **bootstrap 目录树是首要索引** — 先从目录名和层级推断，再搜索。大多数定位不需要工具调用。
-2. **默认只读。** 只有用户明确要求保存、记录、整理、修改时才调写入工具。查阅/总结/引用 = 不写。
-3. **规则优先级**（越上越优先）：用户当轮指令 → `user-skill-rules.md` → 就近目录 `INSTRUCTION.md` → 根 `INSTRUCTION.md` → 本 SKILL 默认。
-4. **多文件编辑必须先出计划。** 展示完整变更清单，确认后再执行。
-5. 增删/移动/重命名后 → **自动同步受影响 README**。
+使用 `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_*`），直接使用——工具的 schema 已自带说明。有 CLI 时优先用 CLI（更省 token）。
 
-## 绝对不要（踩坑清单）
+### CLI 安装
 
-- **绝不写入 KB 根目录**，除非用户明确要求。根目录只放治理文件（`README.md`、`INSTRUCTION.md`、`CONFIG`）。新内容放语义最合适的子目录。
-- **绝不假设目录名。** 不要写死 `Workflows/`、`Projects/`、`Contacts/` — 必须从实际收到的 bootstrap 目录树推断。用户可能用中文名、扁平结构或独特层级。
-- **绝不用 `mindos_write_file` 做小修改。** 用 `update_section`、`update_lines` 或 `insert_after_heading` — 整文件覆写破坏 git diff，变更无法审计。
-- **绝不单关键词搜索。** 必须并行 2-4 条搜索（同义词、缩写、中英文变体）。单条命中率太低。
-- **绝不未经确认就改 `INSTRUCTION.md` 或 `README.md`。** 它们是治理文档，即使看起来只是修个错别字。
-- **绝不在没看过邻居文件的情况下创建新文件。** 至少读 1-2 个同目录文件，学习本地命名/标题/CSV 格式。自创新规是不一致的常见根源。
-- **绝不留孤链。** 重命名/移动后必须 `get_backlinks` 并更新每一个引用方。这是知识库断链的首因。
-- **绝不跳过多文件写入的路由确认。** 即使目标看起来很明显——用户的心智模型可能和你不同。
+```bash
+npm install -g @geminilight/mindos
+# 远程模式：mindos config set url http://<IP>:<端口> && mindos config set authToken <token>
+```
 
 ---
 
-## MindOS 核心概念
+## 规则
+
+1. **先了解结构** — 列出知识库目录树，再搜索或写入。
+2. **默认只读。** 只有用户明确要求保存、记录、整理、编辑时才写入。
+3. **规则优先级**（从高到低）：用户当前指令 → `.mindos/user-preferences.md` → 最近目录 `INSTRUCTION.md` → 根 `INSTRUCTION.md` → 本技能默认。
+4. **多文件编辑先出方案。** 展示完整变更列表，获批后再执行。
+5. 创建/删除/移动/重命名后 → **自动同步相关 README**。
+6. **写入前先读取。** 不基于假设写入。
+
+---
 
-- **空间（Space）** — 按你的思维方式组织的知识分区。Agent 遵循同样的结构。
-- **指令（Instruction）** — 所有接入 Agent 都遵守的规则文件。写一次，全局生效。
-- **技能（Skill）** — 教 Agent 如何读写、整理知识库。Agent 按安装的 Skill 执行，不是瞎猜。
+## 禁止事项（血泪教训）
 
-**笔记即指令 / 技能** — `INSTRUCTION.md` 和 `SKILL.md` 就是目录树里的 Markdown 文件。笔记可以是随笔，也可以是 Agent 必须遵守的治理规则，或 Agent 按步骤执行的程序包。
+- **禁止写入知识库根目录**（除非明确要求）。根目录仅放治理文件，新内容放最合适的子目录。
+- **禁止假设目录名。** 从实际目录树推断——知识库可能用中文名或扁平结构。
+- **禁止用整文件覆盖做小修改。** 用 `mindos file edit-section` 或 `mindos file insert-heading` 做精准修改，整文件覆盖破坏 git diff。
+- **禁止单关键词搜索。** 至少 2-4 个并行搜索（同义词、缩写、中英文变体）。
+- **禁止未确认就修改 `INSTRUCTION.md` 或 `README.md`。** 治理文档——高敏感度。
+- **禁止不看邻居就创建文件。** 先读目标目录 1-2 个文件，了解命名和风格。
+- **禁止遗留孤立引用。** 重命名/移动后检查反向链接并更新所有引用。
+- **禁止跳过多文件写入确认。** 用户的心理模型可能和你不同。
 
 ---
 
-## 思维框架
+## MindOS 概念
 
-动手前，问自己：
+- **空间 (Space)** — 按你的思维方式组织的知识分区。Agent 遵循相同结构。
+- **指令 (Instruction)** — `INSTRUCTION.md`，所有连接的 Agent 都遵守的规则文件。
+- **技能 (Skill)** — 教 Agent 如何读写和整理知识库。
 
-1. **用户意图属于哪类？** → 只读查阅 | 单文件编辑 | 多文件路由 | 结构变更 | SOP 执行。决定走下面哪条路径。
-2. **这个内容该放哪？** → 扫目录树。如果看名字 5 秒内定不下来，大概率要问用户确认。
-3. **附近有什么？** → 写之前读 1-2 个同级文件，照它们的风格。
-4. **改这里会打断什么？** → 重命名/移动：`get_backlinks`。内容修改：想想谁引用了这个事实。
-5. **用户让我写了吗，还是我自作主张？** → 没让你写就别写。
+笔记可以同时承载指令和技能——它们只是目录树中的 Markdown 文件。
 
 ---
 
-## 任务路由决策树
+## 决策树
 
 ```
 用户请求
   │
-  ├─ 只是查找 / 总结 / 引用？
-  │   └─ 是 → [只读路径]：搜索 + 读取 + 标注来源。不写入。跳过 Hooks。
+  ├─ 查找 / 总结 / 引用？
+  │   └─ [只读路径]：搜索 → 读取 → 带引用回答。不写入。
   │
-  ├─ 要求保存 / 记录 / 更新 / 整理具体内容？
-  │   ├─ 单文件目标？ → [单文件编辑]
-  │   └─ 多文件或目标不明？ → [多文件路由]
+  ├─ 保存 / 记录 / 更新 / 整理具体内容？
+  │   ├─ 单文件 → [单文件编辑]
+  │   └─ 多文件或不确定 → [多文件路由] — 先出方案
   │
   ├─ 结构变更（重命名 / 移动 / 删除 / 重组）？
-  │   └─ [结构路径]
+  │   └─ [结构路径] — 变更前后检查反向链接
   │
-  ├─ 流程性 / 可重复的任务？
-  │   └─ [SOP 路径]
+  ├─ 流程性 / 可重复任务？
+  │   └─ [SOP 路径] — 找到并执行现有 SOP，或创建新的
   │
   ├─ 复盘 / 提炼 / 交接？
   │   └─ [复盘路径]
   │
-  └─ 模糊或范围过大？
-      └─ 先问清楚。基于 KB 状态提出 2-3 个具体选项。不要开始编辑。
+  └─ 模糊？
+      └─ 提问。基于知识库状态提出 2-3 个具体选项。
 ```
 
-**以上任何写入 / SOP / 结构路径 → 写入补充已加载到上下文（见下方或下一个上下文块中的 `## 写入与工作流补充` 章节）。**
-
 ---
 
-## 工具选型
+## 判断启发
 
-| 意图 | 推荐工具 | 避免 |
-|------|----------|------|
-| 启动时加载上下文 | `mindos_bootstrap` | 不 bootstrap 就随机读文件 |
-| 列出顶层心智空间 | `mindos_list_spaces` | 只需分区概览却拉整棵 `list_files` |
-| 找文件 | `mindos_search_notes`（2-4 条并行关键词变体）| 单关键词搜索 |
-| 读内容 | `mindos_read_file` 或 `mindos_read_lines`（大文件） | 只需 10 行却读整文件 |
+**保存意图边界：**
+- "帮我记下来" / "保存" = 写入
+- "搜一下" / "总结" = 只读
+- "整理一下" → 先问：仅展示，还是写回知识库？
 
-写入、结构变更、历史工具 → 见写入与工作流补充（已加载到下方或下一个上下文块）。
+**文件位置不确定：**
+- 5 秒内定不了 → 用最近的现有目录，告知用户
+- "随便放哪" → 收件箱，之后提议分类
 
-### 回退
+**范围蔓延：**
+- 输入路由到 >5 个文件 → 暂停确认
+- "全部更新" + 跨多个主题 → 分批确认
 
-- `mindos_bootstrap` 不可用 → 手动读根 `INSTRUCTION.md` + `README.md`。
-- 搜索无结果 → 不放弃：(1) 扫上下文中的树；(2) 直接读候选文件；(3) `mindos_list_files` 细化子目录；(4) 用同义词/中英文变体重试。
+**引用规范：** 引用知识库内容必须附带文件路径。
 
 ---
 
-## 执行模式
+## 任务后钩子
 
-| 模式 | 适用场景 | 关键步骤 |
-|------|----------|----------|
-| **只读问答** | 查找 / 总结 / 引用 | 目录树推断 → 搜索 → 读取 → 标注来源 → 明确说信息缺口 |
+写入任务（非简单读取）后扫描此表。最多 1 个提议；优先级最高的优先。先检查 `.mindos/user-preferences.md` 抑制项。
 
-写入模式详细执行步骤 → 见写入与工作流补充（已加载到下方或下一个上下文块）。
+| 钩子 | 优先级 | 条件 |
+|------|--------|------|
+| 经验沉淀 | 高 | 调试、排错或多轮工作 |
+| 一致性同步 | 高 | 编辑的文件有反向链接 |
+| SOP 偏移 | 中 | 按 SOP 执行但实际偏离了步骤 |
+| 关联更新 | 中 | 更改了 CSV/TODO 状态且有关联文档 |
+| 结构分类 | 中 | 在临时位置或收件箱创建了文件 |
+| 模式提取 | 低 | 本次会话中 3+ 个结构相似的操作 |
 
----
+触发时 → 读取 [references/post-task-hooks.md](./references/post-task-hooks.md)。
 
-## 判断启发式规则
-
-**保存意图 — 读写边界识别**
-- "帮我记下来" / "记录一下" / "保存这个" = 写入
-- "搜一下有没有关于 X 的笔记" / "总结上周的工作" = 只读
-- 模糊边界（"整理一下这些内容"）→ 先问：是读取展示，还是写回 KB？
+## 偏好捕获
 
-**文件位置不确定时**
-- 扫目录树 5 秒内定不下来 → 不要自创新目录；放语义最近的已有目录，告知用户
-- 用户说"随便放个地方" → 放 inbox 或最顶层通用目录，任务后提议归类（触发 Structure classification hook）
+用户表达持久偏好时 → 读取 [references/preference-capture.md](./references/preference-capture.md)，按确认-写入流程操作。
 
-**范围蔓延信号**
-- 单条输入导致路由表 > 5 个文件 → 暂停，先确认范围；用户鲜少意图批量重写
-- "把这些都更新一下" + 内容跨越多个主题 → 拆成批次确认，不一次性执行
+## SOP 编写
 
-**引用纪律**
-- KB 中引用的事实必须附带文件路径，便于用户核查
+创建/重写工作流 SOP 时 → 读取 [references/sop-template.md](./references/sop-template.md)。
 
 ---
 
-## 任务后 Hooks
-
-**写入任务**完成后（简单单文件修改或只读查阅跳过），扫描下表。命中则发起一句话提议，最多 1 条，选优先级最高项。先查 `user-skill-rules.md` 的抑制区；用户要求安静模式时全部跳过。
-
-| Hook | 优先级 | 触发条件 |
-|------|--------|---------|
-| 经验沉淀 | 高 | 调试、排错、踩坑，或多轮才解决 |
-| 一致性同步 | 高 | 编辑了有反链的文件（查 `get_backlinks`） |
-| SOP 偏差 | 中 | 按 SOP 执行但实际步骤与文档不符 |
-| 联动更新 | 中 | 改了 CSV/TODO 状态且存在关联文档 |
-| 结构归类 | 中 | 在临时目录或收件箱新建了文件 |
-| 模式提炼 | 低 | 本会话 3+ 次结构相似操作 |
-| 对话复盘 | 低 | 会话 >10 轮且涉及决策或权衡 |
-
-有 hook 命中 → 读 [references/post-task-hooks.md](./references/post-task-hooks.md) 获取提议措辞和用户自定义 hooks。都不命中则安静结束，不读此文件。
-
-## 偏好捕获
-
-用户表达要长期记住的偏好（「以后不要…」「这个该放在…」）时，读 [references/preference-capture.md](./references/preference-capture.md) 并按确认后写入流程存入 `user-skill-rules.md`。
-**不要读** preference-capture 除非用户真的表达了要持久化的偏好。
+## 错误处理（CLI）
 
-## SOP 编写
-
-创建或改写工作流 SOP 时，**必须 — 读 [references/sop-template.md](./references/sop-template.md)**（前置条件、分支步骤、退出条件、踩坑记录）。
-**不要读** sop-template 用于 SOP 执行（仅用于 SOP 创建/编辑）。
+```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
+```