@geminilight/mindos 0.7.2 → 0.7.4

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

@@ -0,0 +1,227 @@
+---
+name: mindos-zh
+disable-model-invocation: true
+description: >
+  MindOS 是用户的本地知识助手，也是跨会话、跨 Agent 共享的知识库。它保存决策记录、会议纪要、SOP、
+  排错经验、架构选型、调研结论和偏好设置。
+  仅 mindRoot 知识库内任务。不用于：改代码仓库、项目源码、KB 外路径。
+  核心概念：空间、指令(INSTRUCTION.md)、技能(SKILL.md)；笔记可承载指令与技能。
+
+  触发场景：保存或记录任何内容、搜索历史笔记或上下文、更新或编辑文件、整理或重组文件结构、
+  执行SOP或工作流、捕获对话中的决策、复盘或总结经验、追加表格或CSV数据、跨Agent交接上下文、
+  提炼经验教训、同步关联文档、查找之前是否讨论过某事、查询历史决策、查找模板或SOP、
+  为会议准备上下文、快速暂存到暂存台、整理暂存台、知识健康检查、检测知识冲突或矛盾、
+  查找过期内容。
+  触发词：帮我记下来、搜一下我的笔记、更新知识库、整理文件、执行工作流、保存到知识库、
+  记录一下、整理笔记、复盘、提炼经验、同步文档、查一下之前的记录、有没有相关的笔记、
+  我之前写过什么、把这个存起来、总结一下保存、交接给其他Agent、追加到表格、
+  放到暂存台、整理暂存台、知识健康检查、检测知识冲突。
+  English triggers: save, record, search notes, organize, retrospective, handoff, lessons learned,
+  inbox, staging, knowledge health, detect conflicts.
+
+  主动行为——不要等用户提到 MindOS：
+  (1) 用户的问题暗示可能存在历史记录（过去的决策、之前的讨论、会议纪要）→ 先搜 MindOS，
+  即使没有明确提到知识库。
+  (2) 完成有价值的工作后（修了 bug、做了决策、总结了经验、选定了架构、开完了会）→
+  主动提议保存到 MindOS，方便以后查阅。
+  (3) 经历了较长或多主题的对话后 → 建议把关键决策和上下文持久化。
+---
+
+# MindOS 技能
+
+<!-- version: 3.2.0 — CLI 优先，MCP 可选 -->
+
+## 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 如何读写和整理知识库。
+- **暂存台 (Inbox)** — `Inbox/` 目录是快速捕获区。内容暂时找不到归属时先放这里，之后再统一整理——用户手动或 AI 辅助批量归类。
+
+笔记可以同时承载指令和技能——它们只是目录树中的 Markdown 文件。
+
+---
+
+## 决策树
+
+```
+用户请求
+  │
+  ├─ 查找 / 总结 / 引用？
+  │   └─ [只读路径]：搜索 → 读取 → 带引用回答。不写入。
+  │
+  ├─ 保存 / 记录 / 更新 / 整理具体内容？
+  │   ├─ 知道放哪 → [单文件编辑]
+  │   ├─ 不知道放哪 → [暂存台路径] — 存到 Inbox/，之后再归类
+  │   └─ 多文件或不确定 → [多文件路由] — 先出方案
+  │
+  ├─ 整理暂存台 / 归类暂存文件？
+  │   └─ [暂存台整理] — 读 Inbox/ 文件，提议目标位置，获批后移动
+  │
+  ├─ 结构变更（重命名 / 移动 / 删除 / 重组）？
+  │   └─ [结构路径] — 变更前后检查反向链接
+  │
+  ├─ 流程性 / 可重复任务？
+  │   └─ [SOP 路径] — 找到并执行现有 SOP，或创建新的
+  │
+  ├─ 复盘 / 提炼 / 交接？
+  │   └─ [复盘路径]
+  │
+  ├─ 知识健康检查 / 检测冲突？
+  │   └─ [健康检查路径] — 读取 references/knowledge-health.md
+  │
+  └─ 模糊？
+      └─ 提问。基于知识库状态提出 2-3 个具体选项。
+```
+
+---
+
+## 判断启发
+
+**保存意图边界：**
+- "帮我记下来" / "保存" = 写入
+- "搜一下" / "总结" = 只读
+- "整理一下" → 先问：仅展示，还是写回知识库？
+
+**文件位置不确定：**
+- 5 秒内定不了 → 存到 `Inbox/`，告知用户，之后提议归类
+- "随便放哪" / "先放着" → 存到 `Inbox/`
+- 用户拖拽文件或粘贴非结构化内容但没指定位置 → `Inbox/`
+
+**范围蔓延：**
+- 输入路由到 >5 个文件 → 暂停确认
+- "全部更新" + 跨多个主题 → 分批确认
+
+**引用规范：** 引用知识库内容必须附带文件路径。
+
+---
+
+## 任务后钩子
+
+写入任务（非简单读取）后扫描此表。最多 1 个提议；优先级最高的优先。先检查 `.mindos/user-preferences.md` 抑制项。
+
+| 钩子 | 优先级 | 条件 |
+|------|--------|------|
+| 经验沉淀 | 高 | 调试、排错或多轮工作 |
+| 一致性同步 | 高 | 编辑的文件有反向链接 |
+| SOP 偏移 | 中 | 按 SOP 执行但实际偏离了步骤 |
+| 关联更新 | 中 | 更改了 CSV/TODO 状态且有关联文档 |
+| 结构分类 | 中 | 在临时位置或收件箱创建了文件 |
+| 模式提取 | 低 | 本次会话中 3+ 个结构相似的操作 |
+
+触发时 → 读取 [references/post-task-hooks.md](./references/post-task-hooks.md)。
+
+## 偏好捕获
+
+用户表达持久偏好时 → 读取 [references/preference-capture.md](./references/preference-capture.md)，按确认-写入流程操作。
+
+## SOP 编写
+
+创建/重写工作流 SOP 时 → 读取 [references/sop-template.md](./references/sop-template.md)。
+
+## 暂存台 (Inbox)
+
+`Inbox/` 目录是知识库的快速捕获区，有自己的 `INSTRUCTION.md` 约束行为。
+
+**何时使用暂存台：**
+- 用户说"先存着" / "放到暂存台" / "随便放哪"，没指定具体位置
+- 内容明显不属于任何现有空间或目录
+- 批量导入多个文件，需要逐个归类
+
+**如何存到暂存台：**
+```bash
+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](./references/knowledge-health.md) 获取完整流程。
+
+检查维度速览：
+- **矛盾/冲突**：同一主题的不同文件说法互相矛盾
+- **断裂链接**：引用了不存在的文件
+- **过期内容**：带有过期日期标记的文件，或超过 6 个月未更新的活跃主题
+- **重复内容**：两个文件覆盖同一主题且没有互相引用
+- **孤立文件**：零反向链接，难以被发现
+- **结构问题**：文件放错目录、缺少 README、暂存台老化文件
+
+---
+
+## 错误处理（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/_standalone/data/skills/mindos-zh/references/write-supplement.md

@@ -0,0 +1,119 @@
+# MindOS 写入与工作流补充
+
+<!-- 随 SKILL.md 一起由 route.ts 注入到每次请求的上下文中。 -->
+<!-- 只读查阅、问答、总结时此上下文同样可用。 -->
+
+---
+
+## 绝对不要（写路径专属）
+
+- **绝不把 `mindos_write_file` 当第一步。** 没读过当前内容就覆写 = 在黑暗中操作。哪怕你"应该知道"文件里有什么，也先读——你的假设可能已过时。
+- **绝不用 `mindos_create_file` 创建心智空间。** 这只会建一个普通目录，缺少 README + INSTRUCTION 脚手架。缺少治理文件的空间从诞生起就是残缺的。必须用 `mindos_create_space`。
+- **绝不 bootstrap 后直接写入。** Bootstrap 告诉你顶层结构，不代表目标路径附近的局部 `INSTRUCTION.md` 没有覆盖全局规则。写入前必须读目标路径附近的治理文件。
+- **绝不在没有展示路由表的情况下执行多文件写入。** 即使目标看起来显而易见——用户的心智模型和你的判断不一致的概率远高于你的直觉。展示路由表，等确认。
+- **绝不把 `mindos_append_to_file` 用于有结构要求的文件。** 盲目追加会忽略章节顺序。如果文件有标题层级、必填字段或 schema 约束，用 `insert_after_heading` 或 `update_section` 把内容落在正确位置。
+
+---
+
+## 写入工具选型
+
+| 意图 | 推荐工具 | 避免 |
+|------|----------|------|
+| 小范围文字修改 | `mindos_update_section` / `mindos_update_lines` / `mindos_insert_after_heading` | 小修改用 `mindos_write_file` |
+| 追加到末尾 | `mindos_append_to_file` | 为了加一行重写整文件 |
+| 整文件替换 | `mindos_write_file` | 用它做章节级编辑 |
+| 新建文件 | `mindos_create_file` | 自动创建父目录，但不会生成空间脚手架文件 |
+| 新建心智空间（目录 + README + INSTRUCTION）| `mindos_create_space` | 创建空间的唯一方式。`create_file` 只创建普通目录 |
+| 重命名空间目录 | `mindos_rename_space` | `rename_file`（仅文件，不能重命名文件夹）|
+| 追加 CSV | `mindos_append_csv`（校验表头）| 手动拼字符串不校验 |
+| 重命名前查影响 | `mindos_get_backlinks` | 不查引用就重命名 |
+| 查看近期变动 | `mindos_get_recent` | 猜最近改了什么 |
+| 恢复历史版本 | `mindos_get_file_at_version` | 让用户回忆之前内容 |
+
+**回退：** 行级/章节级工具不可用 → 读 + 受限 `mindos_write_file`（模拟最小修改）。
+
+---
+
+## 启动协议
+
+所有写入任务执行前运行：
+
+1. **Bootstrap** — `mindos_bootstrap`（首选），或手动读根 `INSTRUCTION.md` + `README.md`。
+2. **发现结构**
+   - 只需确认顶层分区 → `mindos_list_spaces`（更轻量，含 README 摘要）
+   - 需要找具体文件路径 → 先用 `mindos_list_spaces` 确认目标分区，再在该分区下 `mindos_list_files`
+   - 已知关键词 → 并行 2-4 条 `mindos_search_notes`，覆盖中英文和缩写变体
+   - **绝不假设顶层目录名**——用户可能用中文、拼音或自定义层级
+3. **加载局部治理** — 读取目标路径附近的 `README.md` / `INSTRUCTION.md`。局部约定覆盖全局假设。
+4. **匹配已有 SOP** — 任务偏流程时：从树中识别存放流程的目录（`Workflows/`、`SOPs/`、`流程/` 等仅为常见名，不假设一定存在）。用关键词 + `<!-- keywords: -->` 元数据搜索。找到则读取并执行；偏差则任务后提议更新。
+5. **写前检查** — 确认：路径存在或应创建；位置在子目录下（非根）；现有内容已读；修改范围最小；路径变更的反链影响已评估。
+6. **执行编辑。**
+
+上下文缺失时，按最佳努力继续并明确写出假设。
+
+---
+
+## 执行模式
+
+| 模式 | 适用场景 | 关键步骤 |
+|------|----------|----------|
+| **单文件编辑** | 目标文件明确 | 启动协议 → 读目标 + 局部约定 → 最小修改 → 验证 → 总结 |
+| **多文件路由** | 非结构化输入，多个目的地 | 解析为语义单元 → 路由表 → 确认 → 编辑 → 汇总 |
+| **对话复盘** | 提炼 / 沉淀会话 | 确认范围 → 抽取决策/踩坑/下一步 → 路由 → 记录变更 |
+| **SOP 执行** | 可重复流程 | 完整读 SOP → 分步执行 → 更新过时段落 → 偏差则提议更新 |
+| **结构变更** | 重命名 / 移动 / 删除 | `get_backlinks` → 影响报告 → 确认 → 执行 → 更新引用 → 同步 README |
+| **CSV 追加** | 追加表格行 | 读表头 → 校验字段 → `mindos_append_csv` |
+| **跨 Agent 接力** | 继续其他 Agent 的工作 | 读任务状态+决策 → 无需重新探索直接接续 → 回写进度 |
+| **周期性回顾** | 汇总近期变动 | `get_recent`/`get_history` → 读变动文件 → 结构化总结 |
+| **交接文档** | 创建简报 | 读来源 → 合成（背景、决策、状态、待办）→ 放项目目录 |
+
+---
+
+## 详细执行步骤
+
+### 单文件编辑
+搜索 → 读目标文件 + 读 1-2 个同目录文件了解本地约定 → 应用最小修改（优先 `update_section` / `update_lines` / `insert_after_heading`，避免整文件覆写）→ 验证标题/风格匹配 → 总结改了什么。
+
+### 多文件路由
+将非结构化输入拆解为离散语义单元 → 每个单元并行搜索 2-4 个关键词变体找最合适文件 → **展示路由表**（内容片段 → 目标文件 → 插入位置）→ 等用户确认 → 逐文件执行编辑 → 用文件路径汇总全部变更。
+
+### 对话复盘
+确认范围（哪次会话？哪些主题？）→ 抽取：已做决策、决策理由、遇到的坑、下一步行动 → 为每个产物通过搜索找最合适的现有文件 → 各归其位 → 每个改动文件追加一行变更说明。
+
+### SOP 执行
+开始前完整读 SOP（不要略读）→ 逐步执行，完成一步确认一步 → 遇到过时或与当前 KB 状态不符的步骤，记录下来 → 完成后，针对偏差步骤提议定向 SOP 更新。
+**创建新 SOP** → 先读 [references/sop-template.md](./references/sop-template.md) 了解必需结构。
+
+### 结构变更
+对要变更的路径执行 `get_backlinks` → 展示影响报告（N 个文件需要更新）→ 等确认 → 执行重命名/移动/删除 → 更新每一条反链 → 同步受影响的 `README.md`。
+
+### 交接 / 跨 Agent 接力
+读交接文档或上一个 Agent 的进度记录 → 识别：当前状态、已做决策、待处理事项 → 从该状态直接接续，不重复已完成的探索 → 完成后将进度回写到同一份交接文档。
+
+---
+
+## 任务后 Hooks
+
+**写入任务**完成后（简单单文件修改或只读查阅跳过），扫描下表。命中则发起一句话提议，最多 1 条，选优先级最高项。先查 `.mindos/user-preferences.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) 并按确认后写入流程存入 `.mindos/user-preferences.md`。
+**不要读** preference-capture 除非用户真的表达了要持久化的偏好。
+
+## SOP 编写
+
+创建或改写工作流 SOP 时，**必须 — 读 [references/sop-template.md](./references/sop-template.md)**（前置条件、分支步骤、退出条件、踩坑记录）。
+**不要读** sop-template 用于 SOP 执行（仅用于 SOP 创建/编辑）。

package/app/__tests__/api/mcp-install.test.ts

@@ -179,7 +179,9 @@ describe('POST /api/mcp/install', () => {
   it('handles empty config file gracefully (e.g. fresh VS Code mcp.json)', async () => {
     const { POST } = await importInstallRoute();
     // Pre-create an empty config file (common with VS Code)
-    const copilotDir = path.join(tempHome, '.config', 'Code', 'User');
+    const copilotDir = process.platform === 'darwin'
+      ? path.join(tempHome, 'Library', 'Application Support', 'Code', 'User')
+      : path.join(tempHome, '.config', 'Code', 'User');
     fs.mkdirSync(copilotDir, { recursive: true });
     fs.writeFileSync(path.join(copilotDir, 'mcp.json'), '', 'utf-8');
 
@@ -195,7 +197,11 @@ describe('POST /api/mcp/install', () => {
     const body = await res.json();
     expect(body.results[0].status).toBe('ok');
 
-    const config = JSON.parse(fs.readFileSync(path.join(copilotDir, 'mcp.json'), 'utf-8'));
+    const configPath = path.join(copilotDir, 'mcp.json');
+    expect(fs.existsSync(configPath)).toBe(true);
+    const content = fs.readFileSync(configPath, 'utf-8');
+    expect(content.trim()).not.toBe(''); // Should have written valid JSON
+    const config = JSON.parse(content);
     expect(config.servers.mindos.type).toBe('stdio');
   });
 

package/app/__tests__/core/embedding-provider.test.ts

@@ -8,6 +8,10 @@ import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 // Mock @huggingface/transformers to avoid real downloads
 vi.mock('@huggingface/transformers', () => ({
   pipeline: vi.fn(),
+  env: {
+    remoteHost: '',
+    remotePathTemplate: '',
+  },
 }));
 
 describe('embedding-provider retry logic', () => {
@@ -21,6 +25,80 @@ describe('embedding-provider retry logic', () => {
     vi.clearAllMocks();
   });
 
+  describe('mirror configuration', () => {
+    it('should configure hf-mirror.com when HF_ENDPOINT is not set', async () => {
+      const originalEnv = process.env.HF_ENDPOINT;
+      delete process.env.HF_ENDPOINT;
+
+      const { pipeline, env } = await import('@huggingface/transformers');
+      // Reset env to simulate fresh state
+      env.remoteHost = '';
+      env.remotePathTemplate = '';
+
+      const mockPipeline = { mock: true };
+      vi.mocked(pipeline).mockResolvedValueOnce(mockPipeline);
+
+      const { downloadLocalModel } = await import('@/lib/core/embedding-provider');
+      await downloadLocalModel('test-model');
+
+      // Verify mirror was configured
+      expect(env.remoteHost).toBe('https://hf-mirror.com');
+      expect(env.remotePathTemplate).toBe('{model}/resolve/{revision}/{fileName}');
+
+      // Restore
+      if (originalEnv) process.env.HF_ENDPOINT = originalEnv;
+    });
+
+    it('should respect HF_ENDPOINT environment variable', async () => {
+      const originalEnv = process.env.HF_ENDPOINT;
+      process.env.HF_ENDPOINT = 'https://custom-mirror.com';
+
+      const { pipeline, env } = await import('@huggingface/transformers');
+      // Reset env to simulate fresh state
+      env.remoteHost = '';
+      env.remotePathTemplate = '';
+
+      const mockPipeline = { mock: true };
+      vi.mocked(pipeline).mockResolvedValueOnce(mockPipeline);
+
+      const { downloadLocalModel } = await import('@/lib/core/embedding-provider');
+      await downloadLocalModel('test-model');
+
+      // Verify custom mirror was NOT overridden (env.remoteHost should remain empty)
+      expect(env.remoteHost).toBe('');
+
+      // Restore
+      if (originalEnv) {
+        process.env.HF_ENDPOINT = originalEnv;
+      } else {
+        delete process.env.HF_ENDPOINT;
+      }
+    });
+
+    it('should not override if env.remoteHost is already set', async () => {
+      const originalEnv = process.env.HF_ENDPOINT;
+      delete process.env.HF_ENDPOINT;
+
+      const { pipeline, env } = await import('@huggingface/transformers');
+      // Simulate user has already configured a custom mirror
+      env.remoteHost = 'https://user-custom-mirror.com';
+      env.remotePathTemplate = 'custom/{model}/{fileName}';
+
+      const mockPipeline = { mock: true };
+      vi.mocked(pipeline).mockResolvedValueOnce(mockPipeline);
+
+      const { downloadLocalModel } = await import('@/lib/core/embedding-provider');
+      await downloadLocalModel('test-model');
+
+      // Verify user's custom mirror was NOT overridden
+      expect(env.remoteHost).toBe('https://user-custom-mirror.com');
+      expect(env.remotePathTemplate).toBe('custom/{model}/{fileName}');
+
+      // Restore
+      if (originalEnv) process.env.HF_ENDPOINT = originalEnv;
+    });
+  });
+
   describe('isRetryableError classification', () => {
     // These would be internal to the module, tested indirectly through loadLocalPipeline behavior
     

package/app/__tests__/skills/mindos-skill-copy-alignment.test.ts

@@ -1,9 +1,10 @@
 import { describe, it, expect } from 'vitest';
-import { readFileSync } from 'node:fs';
+import { readFileSync, existsSync } from 'node:fs';
 import path from 'node:path';
 
-const root = '/data/home/geminitwang/code/sop_note';
+const root = path.resolve(__dirname, '../../..');
 const read = (relativePath: string) => readFileSync(path.join(root, relativePath), 'utf8');
+const exists = (relativePath: string) => existsSync(path.join(root, relativePath));
 
 describe('MindOS skill copy alignment', () => {
   it('keeps source and app skill copies aligned for default skill', () => {
@@ -12,8 +13,13 @@ describe('MindOS skill copy alignment', () => {
   });
 
   it('keeps source and app skill copies aligned for max skill', () => {
-    expect(read('skills/mindos-max/SKILL.md')).toBe(read('app/data/skills/mindos-max/SKILL.md'));
-    expect(read('skills/mindos-max-zh/SKILL.md')).toBe(read('app/data/skills/mindos-max-zh/SKILL.md'));
+    // Only check if both source and app copies exist
+    if (exists('app/data/skills/mindos-max/SKILL.md')) {
+      expect(read('skills/mindos-max/SKILL.md')).toBe(read('app/data/skills/mindos-max/SKILL.md'));
+    }
+    if (exists('app/data/skills/mindos-max-zh/SKILL.md')) {
+      expect(read('skills/mindos-max-zh/SKILL.md')).toBe(read('app/data/skills/mindos-max-zh/SKILL.md'));
+    }
   });
 
   it('removes second-brain wording from aligned skill descriptions', () => {