@geminilight/mindos 0.6.39 → 0.6.41

package/app/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
+```

package/app/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/hooks/useAcpDetection.ts

@@ -30,7 +30,7 @@ interface AcpDetectionState {
 
 const STORAGE_KEY = 'mindos:acp-detection';
 const STALE_TTL_MS = 30 * 60 * 1000;
-const REVALIDATE_TTL_MS = 5 * 60 * 1000;
+const REVALIDATE_TTL_MS = 30 * 60 * 1000;
 
 interface DetectionCache {
   installed: DetectedAgent[];

package/app/hooks/useAskChat.ts

@@ -0,0 +1,248 @@
+'use client';
+
+import { useRef, useState, useCallback } from 'react';
+import type { Message, ImagePart, AskMode } from '@/lib/types';
+import type { ProviderId } from '@/lib/agent/providers';
+import { consumeUIMessageStream } from '@/lib/agent/stream-consumer';
+import { isRetryableError, retryDelay, sleep } from '@/lib/agent/reconnect';
+
+export type LoadingPhase = 'connecting' | 'thinking' | 'streaming' | 'reconnecting';
+
+export interface AskChatRefs {
+  inputValueRef: React.RefObject<string>;
+  mentionRef: React.RefObject<{ mentionQuery: string | null }>;
+  slashRef: React.RefObject<{ slashQuery: string | null }>;
+  imageUploadRef: React.RefObject<{ images: ImagePart[]; clearImages: () => void }>;
+  sessionRef: React.RefObject<{
+    messages: Message[];
+    setMessages: React.Dispatch<React.SetStateAction<Message[]>>;
+  }>;
+  uploadRef: React.RefObject<{
+    localAttachments: { name: string; content: string }[];
+  }>;
+  selectedSkillRef: React.RefObject<{ name: string } | null>;
+  selectedAcpAgentRef: React.RefObject<unknown>;
+  attachedFilesRef: React.RefObject<string[]>;
+}
+
+interface UseAskChatOpts {
+  currentFile?: string;
+  chatMode: AskMode;
+  providerOverride: ProviderId | null;
+  onFirstMessage?: () => void;
+  refs: AskChatRefs;
+  errorLabels: { noResponse: string; stopped: string };
+  resetInputState: () => void;
+}
+
+export function useAskChat({
+  currentFile,
+  chatMode,
+  providerOverride,
+  onFirstMessage,
+  refs,
+  errorLabels,
+  resetInputState,
+}: UseAskChatOpts) {
+  const [isLoading, setIsLoading] = useState(false);
+  const [loadingPhase, setLoadingPhase] = useState<LoadingPhase>('connecting');
+  const [reconnectAttempt, setReconnectAttempt] = useState(0);
+  const reconnectMaxRef = useRef(3);
+  const abortRef = useRef<AbortController | null>(null);
+  const firstMessageFired = useRef(false);
+
+  const stop = useCallback(() => { abortRef.current?.abort(); }, []);
+
+  const submit = useCallback(async (e: React.FormEvent) => {
+    e.preventDefault();
+    const m = refs.mentionRef.current;
+    const s = refs.slashRef.current;
+    const img = refs.imageUploadRef.current;
+    const sess = refs.sessionRef.current;
+    const upl = refs.uploadRef.current;
+    if (!m || !s || !img || !sess || !upl) return;
+    if (m.mentionQuery !== null || s.slashQuery !== null) return;
+    const text = refs.inputValueRef.current?.trim() ?? '';
+    if ((!text && img.images.length === 0) || isLoadingRef.current) return;
+
+    const skill = refs.selectedSkillRef.current;
+    const acpAgent = refs.selectedAcpAgentRef.current;
+    const pendingImages = img.images.length > 0 ? [...img.images] : undefined;
+    const userMsg: Message = {
+      role: 'user',
+      content: text,
+      timestamp: Date.now(),
+      ...(skill && { skillName: skill.name }),
+      ...(pendingImages && { images: pendingImages }),
+    };
+    img.clearImages();
+    const requestMessages = [...sess.messages, userMsg];
+    sess.setMessages([...requestMessages, { role: 'assistant', content: '', timestamp: Date.now() }]);
+
+    resetInputState();
+
+    if (onFirstMessage && !firstMessageFired.current) {
+      firstMessageFired.current = true;
+      onFirstMessage();
+    }
+    setIsLoading(true);
+    setLoadingPhase('connecting');
+    setReconnectAttempt(0);
+
+    const controller = new AbortController();
+    abortRef.current = controller;
+
+    let maxRetries = 3;
+    try {
+      const stored = localStorage.getItem('mindos-reconnect-retries');
+      if (stored !== null) { const n = parseInt(stored, 10); if (Number.isFinite(n)) maxRetries = Math.max(0, Math.min(10, n)); }
+    } catch { /* localStorage unavailable */ }
+    reconnectMaxRef.current = maxRetries;
+
+    const requestBody = JSON.stringify({
+      messages: requestMessages,
+      currentFile,
+      attachedFiles: refs.attachedFilesRef.current,
+      uploadedFiles: upl.localAttachments.map(f => ({
+        name: f.name,
+        content: f.content.length > 20_000
+          ? f.content.slice(0, 20_000) + '\n\n[...truncated to first ~20000 chars]'
+          : f.content,
+      })),
+      selectedAcpAgent: acpAgent,
+      mode: chatMode,
+      providerOverride: providerOverride ?? undefined,
+    });
+
+    const doFetch = async (): Promise<{ finalMessage: Message }> => {
+      const res = await fetch('/api/ask', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: requestBody,
+        signal: controller.signal,
+      });
+
+      if (!res.ok) {
+        let errorMsg = `Request failed (${res.status})`;
+        try {
+          const errBody = await res.json() as { error?: { message?: string } | string; message?: string };
+          if (typeof errBody?.error === 'string' && errBody.error.trim()) {
+            errorMsg = errBody.error;
+          } else if (typeof errBody?.error === 'object' && typeof errBody.error?.message === 'string' && errBody.error.message.trim()) {
+            errorMsg = errBody.error.message;
+          } else if (typeof errBody?.message === 'string' && errBody.message.trim()) {
+            errorMsg = errBody.message;
+          }
+        } catch (err) { console.warn("[useAskChat] error body parse failed:", err); }
+        const err = new Error(errorMsg);
+        (err as Error & { httpStatus?: number }).httpStatus = res.status;
+        throw err;
+      }
+
+      if (!res.body) throw new Error('No response body');
+
+      setLoadingPhase('thinking');
+
+      const finalMessage = await consumeUIMessageStream(
+        res.body,
+        (msg) => {
+          setLoadingPhase('streaming');
+          refs.sessionRef.current?.setMessages(prev => {
+            const updated = [...prev];
+            updated[updated.length - 1] = msg;
+            return updated;
+          });
+        },
+        controller.signal,
+      );
+      return { finalMessage };
+    };
+
+    try {
+      let lastError: Error | null = null;
+
+      for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        if (controller.signal.aborted) break;
+
+        if (attempt > 0) {
+          setReconnectAttempt(attempt);
+          setLoadingPhase('reconnecting');
+          refs.sessionRef.current?.setMessages(prev => {
+            const updated = [...prev];
+            updated[updated.length - 1] = { role: 'assistant', content: '', timestamp: Date.now() };
+            return updated;
+          });
+          await sleep(retryDelay(attempt - 1), controller.signal);
+          setLoadingPhase('connecting');
+        }
+
+        try {
+          const { finalMessage } = await doFetch();
+          if (!finalMessage.content.trim() && (!finalMessage.parts || finalMessage.parts.length === 0)) {
+            refs.sessionRef.current?.setMessages(prev => {
+              const updated = [...prev];
+              updated[updated.length - 1] = { role: 'assistant', content: `__error__${errorLabels.noResponse}` };
+              return updated;
+            });
+          }
+          return;
+        } catch (err) {
+          lastError = err instanceof Error ? err : new Error(String(err));
+          const httpStatus = (err as Error & { httpStatus?: number }).httpStatus;
+          if (!isRetryableError(err, httpStatus) || attempt >= maxRetries) break;
+        }
+      }
+
+      if (lastError) throw lastError;
+    } catch (err) {
+      if ((err as Error).name === 'AbortError') {
+        refs.sessionRef.current?.setMessages(prev => {
+          const updated = [...prev];
+          const lastIdx = updated.length - 1;
+          if (lastIdx >= 0 && updated[lastIdx].role === 'assistant') {
+            const last = updated[lastIdx];
+            const hasContent = last.content.trim() || (last.parts && last.parts.length > 0);
+            if (!hasContent) {
+              updated[lastIdx] = { role: 'assistant', content: `__error__${errorLabels.stopped}` };
+            }
+          }
+          return updated;
+        });
+      } else {
+        const errMsg = err instanceof Error ? err.message : 'Something went wrong';
+        refs.sessionRef.current?.setMessages(prev => {
+          const updated = [...prev];
+          const lastIdx = updated.length - 1;
+          if (lastIdx >= 0 && updated[lastIdx].role === 'assistant') {
+            const last = updated[lastIdx];
+            const hasContent = last.content.trim() || (last.parts && last.parts.length > 0);
+            if (!hasContent) {
+              updated[lastIdx] = { role: 'assistant', content: `__error__${errMsg}` };
+              return updated;
+            }
+          }
+          return [...updated, { role: 'assistant', content: `__error__${errMsg}` }];
+        });
+      }
+    } finally {
+      setIsLoading(false);
+      setReconnectAttempt(0);
+      abortRef.current = null;
+    }
+  }, [currentFile, chatMode, providerOverride, errorLabels.noResponse, errorLabels.stopped, onFirstMessage, refs, resetInputState]);
+
+  const isLoadingRef = useRef(isLoading);
+  isLoadingRef.current = isLoading;
+
+  return {
+    isLoading,
+    isLoadingRef,
+    loadingPhase,
+    reconnectAttempt,
+    reconnectMaxRef,
+    abortRef,
+    firstMessageFired,
+    submit,
+    stop,
+  };
+}