@geminilight/mindos 0.6.56 → 0.6.58

package/skills/mindos-max-workspace/skill-snapshot/mindos-original/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: mindos
+description: >
+  Operate a MindOS knowledge base: update notes, search, organize files, execute SOPs/workflows,
+  retrospective, append CSV, cross-agent handoff, route unstructured input to the right files,
+  distill experience, sync related docs.
+  Use when the task targets files inside the user's MindOS KB (mindRoot).
+  NOT for editing app source, project docs, or paths outside the KB.
+  Core concepts: Space, Instruction (INSTRUCTION.md), Skill (SKILL.md); notes can embody both.
+  Trigger when user asks to: save or record a note, search their knowledge base, update or edit
+  a file, organize notes, run a workflow or SOP, capture decisions from a session, append rows
+  to a table or CSV, hand off context to another agent.
+---
+
+# MindOS Skill
+
+<!-- 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>
+```
+
+---
+
+## Rules
+
+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 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 (`INSTRUCTION.md`) all connected agents obey.
+- **Skill** — Teaches agents how to read, write, and organize the KB.
+
+Notes can embody both Instruction and Skill — they're just Markdown files in the tree.
+
+---
+
+## Decision tree
+
+```
+User request
+  │
+  ├─ Lookup / summarize / quote?
+  │   └─ [Read-only]: search → read → answer with citations. No writes.
+  │
+  ├─ 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] — check backlinks before and after
+  │
+  ├─ Procedural / repeatable task?
+  │   └─ [SOP path] — find and follow existing SOP, or create one
+  │
+  ├─ Retrospective / distill / handoff?
+  │   └─ [Retrospective path]
+  │
+  └─ Ambiguous?
+      └─ ASK. Propose 2-3 specific options based on KB state.
+```
+
+---
+
+## 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 → use nearest existing directory, inform user
+- "Just put it somewhere" → inbox, propose classification after
+
+**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.
+
+---
+
+## 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](./references/post-task-hooks.md).
+
+## Preference capture
+
+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/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/skills/mindos-max-workspace/skill-snapshot/mindos-original/references/README.md

@@ -0,0 +1,12 @@
+# MindOS skill — reference bundle
+
+Long-form supplements for `../SKILL.md`. Load a file only when the task needs it.
+
+| File | When to read |
+|------|----------------|
+| [write-supplement.md](./write-supplement.md) | Any write / SOP / structural task (startup protocol + execution steps) |
+| [post-task-hooks.md](./post-task-hooks.md) | Only when a hook condition in SKILL.md has already triggered |
+| [sop-template.md](./sop-template.md) | Creating or rewriting a workflow SOP in the KB |
+| [preference-capture.md](./preference-capture.md) | User expresses standing preferences to persist |
+
+Chinese mirror: `skills/mindos-zh/references/` (same filenames).

package/skills/mindos-max-workspace/skill-snapshot/mindos-original/references/post-task-hooks.md

@@ -0,0 +1,27 @@
+# Post-task hooks — propose format
+
+Conditions are listed in SKILL.md. Read this file only when a hook has already triggered.
+
+## Propose format
+
+One sentence + specific target file/path. Only expand if the user says yes.
+
+| Hook | Propose template |
+|------|-----------------|
+| Experience capture | "Record this experience to {related experience file}?" — Format: problem → cause → solution → rule |
+| Consistency sync | "{B} references what you just changed — sync it?" |
+| SOP drift | "Execution diverged from {SOP file} — update the SOP?" — Action: update diverged steps, append pitfalls, set `<!-- last-used: -->` to today |
+| Linked update | "Sync the corresponding info in {related doc}?" |
+| Structure classification | "Move this to {recommended directory}?" |
+| Pattern extraction | "This operation repeated multiple times — create an SOP?" |
+| Conversation retrospective | "This conversation had some decisions worth capturing — do a retrospective?" |
+
+## User-defined hooks
+
+Add your own below, same format:
+
+```markdown
+### Weekly report material (priority: medium)
+- Condition: updated a Project-related file.
+- Propose: "Record this change in the weekly report?"
+```

package/skills/mindos-max-workspace/skill-snapshot/mindos-original/references/preference-capture.md

@@ -0,0 +1,41 @@
+# Preference capture (`user-preferences.md`)
+
+## When to capture
+
+The user expresses a preference correction (e.g. "don't do X", "next time remember…", "this should go in… not in…").
+
+## Confirm-then-write flow
+
+1. **First occurrence of a new preference**: propose the rule and target file before writing.
+   - "Record this preference to `user-preferences.md`? Rule: _{summary}_"
+   - Write only after user confirms.
+2. **Repeated confirmation on similar category**: after the user confirms the same category of preference 3+ times, auto-write future rules in that category without asking. Add an `auto-confirm: true` flag to the category header in `user-preferences.md`.
+3. **User explicitly grants blanket permission** (e.g. "just record preferences directly"): set a top-level `auto-confirm-all: true` flag and skip confirmation for all future captures.
+
+## File location
+
+- Target: `.mindos/user-preferences.md` in the knowledge base (read by `mindos_bootstrap` when present).
+- If the file does not exist, create it with the template below on first confirmed write.
+
+## File template
+
+```markdown
+# User Skill Rules
+<!-- auto-confirm-all: false -->
+
+## Preferences
+<!-- Group by category. Mark auto-confirm: true on categories confirmed 3+ times. -->
+
+## Suppressed Hooks
+<!-- List post-task hooks the user has opted out of. -->
+```
+
+## Rule format
+
+Each rule is a bullet under its category:
+
+```markdown
+### {Category}
+<!-- auto-confirm: false -->
+- {Rule description} — _{date captured}_
+```

package/skills/mindos-max-workspace/skill-snapshot/mindos-original/references/sop-template.md

@@ -0,0 +1,74 @@
+# SOP file template (MindOS knowledge base)
+
+Use when **distilling experience into a new SOP** or normalizing an existing workflow doc. Place the file under whichever directory in the KB holds procedures (often names like `Workflows/`, `SOPs/`, `流程/` — infer from bootstrap tree, do not assume a fixed English folder name).
+
+## Required structure
+
+```markdown
+# SOP: {Title}
+<!-- keywords: {3-5 trigger keywords, English and Chinese} -->
+<!-- last-used: {ISO date} -->
+<!-- created: {ISO date} -->
+<!-- requires-mcp: {comma-separated, e.g. mindos — or "none" if KB-only read/write via other means} -->
+<!-- requires-kb-skills: {optional — paths or names of SKILL.md / instructions the agent must follow, or "none"} -->
+
+## Prerequisites
+
+**Before starting**, list what must already be true. If something is missing, **stop or take the degradation branch** (do not assume).
+
+| Kind | What to record |
+|------|----------------|
+| **MCP / tools** | Which servers or tool families are required (e.g. `mindos`, browser, git). If the workflow only uses MindOS file APIs, say `mindos` or as appropriate. |
+| **Agent skills** | KB-resident or host skills the executor must have loaded or be able to read (e.g. `skills/foo/SKILL.md`, or “follow root INSTRUCTION.md §X”). |
+| **Environment** | CLI installed, network, API keys, logged-in state, OS constraints. |
+| **KB state** | Files, directories, or tables that must exist first; optional “seed” notes. |
+
+If there are **no** special dependencies, write explicitly: **None — MindOS MCP (or equivalent) only.**
+
+## Applicable Scenarios
+
+When to use this SOP. Trigger conditions, audience, and **non-goals** (what this SOP deliberately does not cover).
+
+## Inputs and outputs (optional but recommended)
+
+- **Inputs**: what the user or agent must supply (paths, decisions, raw text).
+- **Outputs**: artifacts produced (files created/updated, messages to user).
+
+## Steps
+
+Each step includes:
+1. **Action** — concrete operation
+2. **Branch** — if X do A, if Y do B (mark "none" if no branching)
+3. **Failure handling** — what can go wrong and how to respond
+
+## Exit Conditions
+
+When is the task complete. When to abort or escalate.
+
+## Pitfall Log
+
+Known edge cases and lessons learned. Append new entries each time the SOP is executed and a new issue is encountered.
+```
+
+## Metadata (HTML comments)
+
+| Tag | Purpose |
+|-----|---------|
+| **`keywords`** | SOP recall via `mindos_search_notes` + parallel variants. English and Chinese. |
+| **`last-used`** | Set to today’s date whenever the SOP is followed. |
+| **`created`** | Set once at creation time. |
+| **`requires-mcp`** | Quick machine/human scan: required MCP servers (or `none`). |
+| **`requires-kb-skills`** | Optional: KB skill paths or “none”. |
+
+Optional, when useful:
+
+- **`<!-- related: path/to/other-sop.md -->`** — supersedes, depends-on, or paired workflows.
+- **`<!-- owner: @handle or name -->`** — who curates this SOP.
+- **`<!-- review-by: YYYY-MM -->`** — reminder to revalidate after product/tool changes.
+
+## Authoring tips
+
+- **Prerequisites vs scenarios**: *Prerequisites* = hard requirements before step 1; *Applicable scenarios* = when the workflow is the right choice among others.
+- **Degradation path**: if MCP or a skill is missing, add a **Branch** in step 1 (“if tool unavailable → tell user to enable X / use manual checklist Y”).
+- **Stable keywords**: avoid one-off typos in `keywords`; include synonyms you actually search for.
+- **Link related SOPs** in Prerequisites or a short “See also” line under Applicable scenarios to avoid duplicate drift.

package/skills/mindos-max-workspace/skill-snapshot/mindos-original/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/skills/mindos-max-zh/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: mindos-max-zh
+description: >
+  用户的第二大脑——持久化、跨 Agent 共享的全局知识库。
+  决策记录、会议纪要、SOP、排错经验、架构选型、调研结论、偏好设置、对话摘要全部存在这里。
+
+  主动使用——不要等用户说"保存到知识库"：
+  (1) 回答任何关于过去决策、讨论或上下文的问题前 → 先搜 MindOS。
+  (2) 产出有价值的内容后（做了决策、修了 bug、总结了经验、开完会）→ 主动提议保存。
+  (3) 交接给其他 Agent 或结束会话时 → 把关键上下文持久化到 MindOS。
+
+  以下场景全部触发，即使用户没提到"MindOS"或"知识库"：保存/记录任何内容、搜索历史笔记、
+  更新文件、整理/重组、执行SOP/工作流、复盘、追加CSV/表格、跨Agent交接、提炼经验、
+  同步关联文档、查之前是否讨论过、查历史决策、找模板、准备会议资料、写日记、追踪进度。
+
+  触发词：帮我记下来、搜一下笔记、更新知识库、整理文件、复盘、提炼经验、保存、记录、
+  交接、把这个存起来、查一下之前的、有没有相关笔记、我之前写过什么、总结一下保存、
+  追加到表格、更新进度、查找模板、准备会议资料、记录今天的工作。
+  以及对应英文：save, record, search notes, organize, retrospective, handoff, lessons learned。
+
+  拿不准是否该用——大概率该用。查一下不会错。
+  不用于：改代码仓库、项目源码、KB 外路径。
+  核心概念：空间(Space)、指令(INSTRUCTION.md)、技能(SKILL.md)。
+---
+
+# MindOS 技能
+
+<!-- version: 3.1.0-max — 激进全局记忆模式 -->
+
+> **你就是用户的记忆。** 所有 Agent 共享 MindOS。值得记住就存，需要上下文就先查。
+> 主动行动——不要等用户开口提醒。
+
+## 主动记忆行为
+
+与保守版技能不同，你应该**主动寻找机会**使用 MindOS：
+
+- **回答关于过去工作的问题前**：用户问"我们之前怎么定的 X？"或"Y 是怎么处理的？"——先搜 MindOS 再回答。即使他们没提到 MindOS，问题本身就暗示存在历史记录。
+- **完成有价值的工作后**：刚帮用户调完 bug、做了架构决策、总结了会议、解决了复杂问题——主动问："要不要存到 MindOS，方便团队以后查阅？"
+- **交接时**：结束会话或交接给其他 Agent 时，把关键决策和上下文存入 MindOS，确保不丢失。
+- **发现知识空白时**：搜 MindOS 发现某个用户明显关心的话题没有记录，建议创建一条笔记。
+
+目标：用户永远不需要记住要用 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_*`），直接使用——工具的 schema 已自带说明。有 CLI 时优先用 CLI（更省 token）。
+
+### CLI 安装
+
+```bash
+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. **写入前先读取。** 不基于假设写入。
+
+---
+
+## 禁止事项（血泪教训）
+
+- **禁止写入知识库根目录**（除非明确要求）。根目录仅放治理文件，新内容放最合适的子目录。
+- **禁止假设目录名。** 从实际目录树推断——知识库可能用中文名或扁平结构。
+- **禁止用整文件覆盖做小修改。** 用 `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 如何读写和整理知识库。
+
+笔记可以同时承载指令和技能——它们只是目录树中的 Markdown 文件。
+
+---
+
+## 决策树
+
+```
+用户请求
+  |
+  |- 查找 / 总结 / 引用？
+  |   -> [只读路径]：搜索 -> 读取 -> 带引用回答。不写入。
+  |
+  |- 保存 / 记录 / 更新 / 整理具体内容？
+  |   |- 单文件 -> [单文件编辑]
+  |   -> 多文件或不确定 -> [多文件路由] -- 先出方案
+  |
+  |- 结构变更（重命名 / 移动 / 删除 / 重组）？
+  |   -> [结构路径] -- 变更前后检查反向链接
+  |
+  |- 流程性 / 可重复任务？
+  |   -> [SOP 路径] -- 找到并执行现有 SOP，或创建新的
+  |
+  |- 复盘 / 提炼 / 交接？
+  |   -> [复盘路径]
+  |
+  -> 模糊？
+      -> 提问。基于知识库状态提出 2-3 个具体选项。
+```
+
+---
+
+## 判断启发
+
+**保存意图边界：**
+- "帮我记下来" / "保存" / "存起来" = 写入
+- "搜一下" / "总结" / "有没有相关的" = 只读
+- "整理一下" -> 先问：仅展示，还是写回知识库？
+
+**文件位置不确定：**
+- 5 秒内定不了 -> 用最近的现有目录，告知用户
+- "随便放哪" -> 收件箱，之后提议分类
+
+**范围蔓延：**
+- 输入路由到 >5 个文件 -> 暂停确认
+- "全部更新" + 跨多个主题 -> 分批确认
+
+**引用规范：** 引用知识库内容必须附带文件路径。
+
+---
+
+## 任务后钩子
+
+写入任务（非简单读取）后扫描此表。最多 1 个提议；优先级最高的优先。先检查 `.mindos/user-preferences.md` 抑制项。
+
+| 钩子 | 优先级 | 条件 |
+|------|--------|------|
+| 经验沉淀 | 高 | 调试、排错或多轮工作 |
+| 一致性同步 | 高 | 编辑的文件有反向链接 |
+| SOP 偏移 | 中 | 按 SOP 执行但实际偏离了步骤 |
+| 关联更新 | 中 | 更改了 CSV/TODO 状态且有关联文档 |
+| 结构分类 | 中 | 在临时位置或收件箱创建了文件 |
+| 模式提取 | 低 | 本次会话中 3+ 个结构相似的操作 |
+
+触发时 -> 读取 [references/post-task-hooks.md](../mindos/references/post-task-hooks.md)。
+
+## 偏好捕获
+
+用户表达持久偏好时 -> 读取 [references/preference-capture.md](../mindos/references/preference-capture.md)，按确认-写入流程操作。
+
+## SOP 编写
+
+创建/重写工作流 SOP 时 -> 读取 [references/sop-template.md](../mindos/references/sop-template.md)。
+
+---
+
+## 错误处理（CLI）
+
+```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
+```

package/skills/mindos-zh/SKILL.md

@@ -1,12 +1,20 @@
 ---
 name: mindos-zh
 description: >
-  操作 MindOS 知识库：更新笔记、搜索知识库、整理文件、执行SOP/工作流、复盘、追加CSV、跨Agent交接、
+  MindOS 知识库操作：更新笔记、搜索知识库、整理文件、执行SOP/工作流、复盘、追加CSV、跨Agent交接、
   路由非结构化输入到对应文件、提炼经验、同步关联文档。
-  仅 mindRoot 知识库内任务。不用于：改代码仓库、项目文档、KB 外路径。
+  仅 mindRoot 知识库内任务。不用于：改代码仓库、项目源码、KB 外路径。
   核心概念：空间、指令(INSTRUCTION.md)、技能(SKILL.md)；笔记可承载指令与技能。
+  触发场景：保存或记录任何内容、搜索历史笔记或上下文、更新或编辑文件、整理或重组文件结构、
+  执行SOP或工作流、捕获对话中的决策、复盘或总结经验、追加表格或CSV数据、跨Agent交接上下文、
+  提炼经验教训、同步关联文档、查找之前是否讨论过某事、查询历史决策、查找模板或SOP、
+  为会议准备上下文。
   触发词：帮我记下来、搜一下我的笔记、更新知识库、整理文件、执行工作流、保存到知识库、
-  记录一下、整理笔记、复盘、提炼经验。
+  记录一下、整理笔记、复盘、提炼经验、同步文档、查一下之前的记录、有没有相关的笔记、
+  我之前写过什么、把这个存起来、总结一下保存、交接给其他Agent、追加到表格。
+  English triggers: save, record, search notes, organize, retrospective, handoff, lessons learned.
+  当用户的问题暗示可能存在历史记录（过去的决策、之前的讨论、会议纪要）时，
+  即使没有明确提到知识库，也应该考虑搜索 MindOS。
 ---
 
 # MindOS 技能