mindos

MindOS Skill

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 用户： 如果你只能使用 MCP 工具（mindos_*），请直接使用，它们的架构会自我说明。有 CLI 时优先使用 CLI（令牌成本更低）。

CLI 设置

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

---

规则

1. 先进行初始化 — 搜索或写入前，先列出知识库目录树以了解其结构。
2. 默认只读。 仅当用户明确要求保存、记录、整理或编辑时才写入。查找 / 总结 / 引述 = 不写入。
3. 规则优先级（由高到低）：用户当前轮次的指令 → .mindos/user-preferences.md → 最近的目录 INSTRUCTION.md → 根目录 INSTRUCTION.md → 本 SKILL 的默认规则。
4. 编辑多个文件前必须先制定计划。 提供完整的更改列表；仅在获得批准后执行。
5. 创建/删除/移动/重命名后 → 自动同步受影响的 README。
6. 先读后写。 覆盖文件前务必先读取。绝不可基于假设写入。
7. 妥善结束本轮对话。 按照请求执行并在此结束；完整完成查找或写入后，不要多此一举地追问。
8. 遵守源代码边界。 此 skill 用于 MindOS 知识库。如果用户要求编辑应用程序/源代码，但没有可用的源文件或代码工作区工具，请询问具体的仓库/文件/代码背景，而不是搜索或写入知识库笔记。对于简单的编码请求，不要使用知识库列表/搜索/读取工具来查找源文件。

答复约定

在执行任何可选的任务后钩子之前，先遵循此完成约定：

• 查找 / 总结 / 引用： 先回答，引用稳定的文件路径，并明确说明不会写入。如果用户指定了具体的本地文件路径，请在最终答复中包含该路径原文。如果用户要求不要修改或要求只读处理，请用用户的语言以简短的未更改说明结尾（中文：“未做任何修改。”；英文：“No changes were made.”）。除非用户要求后续步骤或证据不完整，否则不要以“要我保存 / 记录 / 更新这个吗？”结尾。
• 写入 / 更新 / 追加： 只有在写入工具成功后，才用用户的语言报告确切路径和操作。英文：Saved to <path>、Updated <path>、Appended to <path>。中文：已保存到 <路径>、已更新 <路径>、已追加到 <路径>。最多再加一句简短总结。
• 写入上传内容： 如果用户要求将上传内容整理成笔记，且目标类型明确，请直接使用上传内容，最多进行一次简单的结构 / README 检查，然后写入笔记。不要在列出目录后就停止。
• 澄清： 只有在缺失的信息会影响目的地、范围、成本、安全性或可逆性时，才问一个具体问题。有帮助时提供 2–3 个实际选项。
• 证据缺失或工具失败： 说明未找到什么或哪里失败；必要时指出尝试过的信息来源 / 工具，并给出下一步具体的恢复方法。对于证据缺失的查找，不要主动提议保存、记录、创建或补充未找到的想法，除非用户要求记录。绝不要返回空答复。
• 语言忠实度： 保留用户的语言和源笔记中的关键术语。如果笔记使用中文术语，请沿用该术语；只有在有帮助时才在括号中补充英文释义。
• 只读完成： 如果用户只要求总结、会议背景或下一步，就在回答后停止。不要擅自追加“要我保存 / 记录 / 起草 / 撰写 / 补充 / 修改 / 导出 / 执行这个吗？”之类的提议。以陈述句而非问句结尾。遵循 SOP 或工作流时，请引用所用 SOP / 工作流的路径。如果用户只问下一步，不要询问是否要执行。

---

检索策略

检索知识时，请并行使用两种路径，然后先筛选再深入阅读：

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

浏览知识库目录树，查看文件名和目录名。标题往往无需阅读正文就能透露内容。如果用户询问“身份验证”，而你看到 Decisions/auth-jwt-vs-session.md，这就是很有力的候选项——直接阅读即可，无需搜索。

• 引导启动后，扫描目录树，查找名称与查询主题相关的路径。
• 留意目录的含义：Decisions/、Projects/、Workflows/、Resources/ 等分别暗示其中内容的类型。
• 如果知识库较小（<50 个文件），快速扫描目录树可能比搜索更快、更可靠。

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

对于无法仅凭文件名推测的内容，使用 search。

• 根据用户的实际用词拟定查询。如果用户说“那个很慢的接口”，搜索“慢 接口”或“性能 API”。
• 一次精准的搜索胜过 4 次宽泛搜索。只有当第一次搜索结果少于 3 条，或主题存在明显的其他说法（例如中文 + 英文）时，才增加第二次搜索。
• 不要每次都机械地执行 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.

---

切勿执行（血泪教训）

• 切勿写入知识库根目录，除非得到明确指示。根目录仅用于存放治理文件。新内容应放在最合适的子目录下。
• 切勿臆测目录名称。 根据实际的引导目录树判断——知识库可能使用中文名称，也可能采用扁平布局。
• 小范围编辑时切勿覆盖整个文件。 使用 mindos file edit-section 或 mindos file insert-heading 进行定点修改。完整重写会破坏 Git 差异。
• 未经确认，切勿修改 INSTRUCTION.md 或 README.md。 这些是治理文档，需按高敏感度对待。
• 创建文件前切勿不检查同级文件。 阅读目标目录中的 1-2 个文件，了解该处的风格。
• 切勿留下孤立引用。 重命名或移动后，检查反向链接并更新所有引用该文件的文件。
• 涉及多个文件的写入时，切勿跳过路径确认。 用户的思路可能与你不同。
• 切勿阅读每条搜索结果。 根据摘要和评分进行筛选。仅深入阅读明显相关的文件。

---

MindOS 概念

• Space — 按照你的思维方式组织的知识分区。Agent 遵循相同的结构。
• Instruction — 一份规则文件（INSTRUCTION.md），所有已连接的 Agent 都必须遵守。
• Skill — 教 Agent 如何读取、写入和整理知识库。
• 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 或当前文件；在得到澄清前，不要移动内容或深入检查。
• “告诉我下一步” → 阅读 SOP 或工作流，告知下一步及其路径，然后停止。除非用户要求继续，否则不要询问是否要执行、起草、保存、写入或继续。

文件位置不确定：

• 5 秒内无法判断 → 保存到 Inbox/，告知用户，并建议之后再分类
• “随便放哪儿” / “先放着” → 保存到 Inbox/
• 用户拖入文件或粘贴未整理的内容，但未指定位置 → Inbox/

稳定的路由和文件名：

• 如果明显存在相关文件，应更新该文件，而不是创建重复文件。
• 如果用户明确要求记录的事实已保存在明显相关的现有文件中，应以最小改动更新该文件，或告知用户该内容已记录在其中。不要询问是否要创建重复的 Inbox 笔记。
• 调试经验应放在 Debugging/（如果该目录存在）；交接内容应放在 Handoffs/；会议笔记应放在 Meetings/；不明确的快速记录应放在 Inbox/。
• 明确要求交接时，如有本地交接指南，应先阅读，然后在 Handoffs/ 下创建或更新一份简洁的笔记。包括目标、相关文件、验证状态和剩余风险；报告保存路径。
• 新文件名应根据具体主题生成；如果知识库没有显示其他命名惯例，则使用小写 ASCII kebab-case。保留已有的产品名称写法和同级文件的拼写（mindroot 与 mind-root），不要自行创造变体。
• 优先采用持久且直观的主题文件名，而不是巧妙的摘要：关于 Agent 基准测试 MIND_ROOT 的调试笔记应使用 agent-benchmark-mindroot... 文件名；关于 Skill 优化和查询重放的快速记录，在可行时应同时保留 skill-optimization 和核心主题。
• 如果用户说“当前文件”，则将 currentFile 视为目标，除非这与安全要求或本地治理规定冲突。

范围蔓延：

• 输入涉及超过 5 个文件 → 暂停并确认范围
• “更新所有这些内容”涉及多个主题 → 分批处理

**引用：**引用知识库中的事实时，必须包含文件路径。

---

任务后钩子

完成写入任务后（简单读取除外），请检查此表。最多提出 1 项建议；优先级最高者优先。先检查 .mindos/user-preferences.md 中是否有抑制设置。

钩子	优先级	条件
经验记录	高	调试、故障排查或多轮工作
一致性同步	高	编辑的文件包含反向链接
SOP 偏移	中	遵循 SOP 时出现偏离
关联更新	中	更改 CSV/TODO 状态，且存在相关文档
结构分类	中	在收件箱/临时位置创建文件
模式提取	低	本次会话中有 3 项或更多类似操作

如果触发钩子 → 阅读 references/post-task-hooks.md。

偏好记录

当用户表达长期偏好时 → 阅读 references/preference-capture.md，并遵循先确认再写入的流程。

“从现在起……”“下次……”或“以后……”等面向未来的偏好表述属于偏好信号，不代表自动获得写入许可。除非用户明确说“保存/记录/写入此偏好”，否则应确认该偏好，并询问是否要保存。

SOP 编写

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

收集箱（暂存区）

Inbox/ 目录是知识库的快速收集区。它有自己的 INSTRUCTION.md，用于规定行为。

何时使用收集箱：

• 用户说“先保存”／“先放着”／“放到收集箱”，但没有指定位置
• 内容不明显适合任何现有空间或目录
• 批量导入多个需要单独分类的文件

如何保存到收集箱：

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

如何整理收集箱：

1. 列出收集箱文件：mindos file list Inbox/
2. 阅读每个文件，了解其内容
3. 根据知识库结构，为每个文件提出最合适的目标目录
4. 将完整的路由方案呈现给用户审批。使用“路由方案”等明确表述，并包含每个源文件路径。
5. 移动文件：mindos file rename "Inbox/<file>" "<target-dir>/<file>"
6. 移动后，检查目标目录的 README 是否需要更新

**超期提醒：**收集箱中超过 7 天的文件视为“超期”。如果在启动检查期间发现超期文件，请提醒用户：“收集箱中有 N 个文件已存放超过一周。需要我帮你整理吗？”

知识健康检查

当用户要求检查知识健康状况、检测冲突、审核质量，或说“知识健康检查”／“检测冲突”时 → 阅读 references/knowledge-health.md 了解完整流程。

检查内容速览：

• 矛盾：同一主题在不同文件中的事实存在冲突
• 失效链接：引用的文件已不存在
• 过时内容：带有过期日期标记，或超过 6 个月未更新的文件

故障恢复

当用户指定的文件路径不存在时：

1. 报告所请求的路径不存在。
2. 根据文件名和用户措辞推断恢复查询，而不只是查找“missing”这个字面词。
3. 搜索／列出可能的替代记录。
4. 如果存在替代项，指出最有可能的候选路径。如果没有，则说明未找到相关记录，并说明检查了哪些内容。

• 重复项：两个文件涉及相同内容，却没有相互引用
• 孤立文件：没有任何反向链接，难以发现
• 结构问题：目录错误、缺少 README、收集箱文件超期

---

错误处理（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