@geminilight/mindos 0.6.40 → 0.6.41

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/lib/fs.ts

@@ -284,9 +284,6 @@ function buildFileTree(dirPath: string, rootOverride?: string): FileNode[] {
         nodes.push(node);
       }
     } else if (entry.isFile()) {
-      // Filter out system files at root level
-      if (dirPath === root && SYSTEM_FILES.has(entry.name)) continue;
-      
       const ext = path.extname(entry.name).toLowerCase();
       if (ALLOWED_EXTENSIONS.has(ext)) {
         nodes.push({ name: entry.name, path: relativePath, type: 'file', extension: ext });
@@ -323,9 +320,6 @@ function buildAllFiles(dirPath: string): string[] {
       if (IGNORED_DIRS.has(entry.name)) continue;
       files.push(...buildAllFiles(fullPath));
     } else if (entry.isFile()) {
-      // Filter out system files at root level
-      if (dirPath === root && SYSTEM_FILES.has(entry.name)) continue;
-      
       const ext = path.extname(entry.name).toLowerCase();
       if (ALLOWED_EXTENSIONS.has(ext)) {
         files.push(path.relative(root, fullPath));

package/app/lib/i18n/modules/features.ts

@@ -24,7 +24,7 @@ export const featuresEn = {
       step2Title: 'Chat with AI',
       step2Desc: 'Press ⌘/ (or Ctrl/) to open the AI panel. Ask anything about your knowledge base, or use @ to attach a specific file for context.',
       step3Title: 'Connect your AI agents',
-      step3Desc: 'Go to Settings → MCP to connect external agents like Claude Code, Cursor, or Windsurf. Once connected, they can read and write your knowledge base directly.',
+      step3Desc: 'Go to Settings → Connections to connect external agents like Claude Code, Cursor, or Windsurf. Once connected, they can read and write your knowledge base directly.',
     },
     concepts: {
       title: 'Core Concepts',
@@ -63,7 +63,7 @@ export const featuresEn = {
       title: 'FAQ',
       items: [
         { q: 'How do I change the language?', a: 'Go to Settings → Appearance → Language. You can switch between English and Chinese.' },
-        { q: 'How do I connect an AI agent?', a: 'Go to Settings → MCP & Skills. MindOS auto-detects installed agents (Claude Code, Cursor, etc.) and lets you connect them with one click.' },
+        { q: 'How do I connect an AI agent?', a: 'Go to Settings → Connections. MindOS auto-detects installed agents (Claude Code, Cursor, etc.) and lets you connect them with one click.' },
         { q: 'Where is my data stored?', a: 'All your data stays on your local machine as plain Markdown files. MindOS never uploads your data to any cloud service. You own everything.' },
         { q: 'How do I sync across devices?', a: 'Go to Settings → Sync. MindOS uses Git for cross-device sync. Enter your Git remote URL and access token to start syncing.' },
         { q: 'Can I use my own AI provider?', a: 'Yes! Go to Settings → AI. You can use OpenAI, Anthropic, Google, or any OpenAI-compatible API with a custom base URL.' },
@@ -100,7 +100,7 @@ export const featuresZh = {
       step2Title: '和 AI 对话',
       step2Desc: '按 ⌘/（或 Ctrl/）打开 AI 面板。询问任何关于知识库的问题，或使用 @ 附加特定文件作为上下文。',
       step3Title: '连接你的 AI Agent',
-      step3Desc: '前往 设置 → MCP 连接外部 Agent，如 Claude Code、Cursor 或 Windsurf。连接后，它们可以直接读写你的知识库。',
+      step3Desc: '前往 设置 → 连接 以连接外部 Agent，如 Claude Code、Cursor 或 Windsurf。连接后，它们可以直接读写你的知识库。',
     },
     concepts: {
       title: '核心概念',
@@ -139,7 +139,7 @@ export const featuresZh = {
       title: '常见问题',
       items: [
         { q: '如何切换语言？', a: '前往 设置 → 外观 → 语言。支持中文和英文切换。' },
-        { q: '如何连接 AI Agent？', a: '前往 设置 → MCP 与技能。MindOS 会自动检测已安装的 Agent（Claude Code、Cursor 等），一键即可连接。' },
+        { q: '如何连接 AI Agent？', a: '前往 设置 → 连接。MindOS 会自动检测已安装的 Agent（Claude Code、Cursor 等），一键即可连接。' },
         { q: '我的数据存储在哪里？', a: '所有数据以纯 Markdown 文件的形式存储在你的本地机器上。MindOS 不会将你的数据上传到任何云服务。数据完全由你掌控。' },
         { q: '如何跨设备同步？', a: '前往 设置 → 同步。MindOS 使用 Git 进行跨设备同步。输入 Git 远程仓库 URL 和访问令牌即可开始同步。' },
         { q: '可以使用自己的 AI 服务商吗？', a: '可以！前往 设置 → AI。支持 OpenAI、Anthropic、Google，或任何 OpenAI 兼容的 API（自定义 Base URL）。' },

package/app/lib/i18n/modules/knowledge.ts

@@ -349,6 +349,8 @@ export const knowledgeEn = {
     tocCollapse: 'Collapse',
     tocExpand: 'Expand',
     emptyNote: 'This note is empty. Press E to start writing.',
+    switchToDoc: 'Document view',
+    switchToGraph: 'Wiki Graph',
   },
   findInPage: {
     placeholder: 'Find in document…',
@@ -706,6 +708,8 @@ export const knowledgeZh = {
     tocCollapse: '收起',
     tocExpand: '展开',
     emptyNote: '此笔记为空。按 E 开始编辑。',
+    switchToDoc: '文档视图',
+    switchToGraph: '知识图谱',
   },
   findInPage: {
     placeholder: '在文档中查找…',

package/app/lib/i18n/modules/onboarding.ts

@@ -15,7 +15,7 @@ export const onboardingEn = {
     dismiss: 'Dismiss',
   },
   setup: {
-    stepTitles: ['Knowledge Base', 'AI Configuration', 'Agent Tools', 'Confirm'],
+    stepTitles: ['Knowledge Base', 'AI Configuration', 'Agent Connection', 'Confirm'],
     // Step 1
     kbPath: 'Knowledge base path',
     kbPathHint: 'Absolute path to your notes directory.',
@@ -60,17 +60,22 @@ export const onboardingEn = {
     webPasswordHint: 'Protect your knowledge base from unauthorized browser access.',
     webPasswordRequired: 'Password is required to protect your data.',
     advancedPorts: 'Advanced Settings',
-    tokenSectionTitle: 'MCP Auth Token (auto-generated)',
+    tokenSectionTitle: 'Auth Token (auto-generated)',
     tokenSectionHint: 'Used by AI agents to connect to your MindOS server.',
-    // Step 5 — Agent Tools
-    agentToolsTitle: 'Agent Tools',
-    agentToolsHint: 'Select AI agents to configure with MindOS MCP. Agents marked "not installed" can be configured now — they will work once you install the app.',
+    // Step 5 — Agent Connection
+    agentToolsTitle: 'Agent Connection',
+    connectionModeTitle: 'Connection Mode',
+    connectionModeCliHint: 'Recommended · Lower token usage',
+    connectionModeMcpHint: 'Optional · Higher token usage',
+    agentToolsHint: 'Select which AI agents to configure. This step is optional.',
+    agentToolsHintCliOnly: 'Agent selection applies when MCP mode is enabled. CLI works with all agents that have bash access.',
+    agentToolsHintNone: 'No connection mode selected. Select at least one mode to connect agents.',
     agentTransport: 'Transport',
     agentScope: 'Scope',
     agentToolsLoading: 'Loading agents…',
     agentToolsEmpty: 'No supported agents detected.',
-    agentNoneSelected: 'No agents selected — you can configure later in Settings → MCP.',
-    agentSkipLater: 'Skip — install agents later in Settings > MCP',
+    agentNoneSelected: 'No agents selected. You can configure agents later in Settings.',
+    agentSkipLater: 'Clear all',
     agentSelectDetected: 'Select detected agents',
     agentNoneDetected: 'No agents detected on your system.',
     agentShowMore: (n: number) => `Show ${n} more agents`,
@@ -91,9 +96,9 @@ export const onboardingEn = {
     agentVerified: 'verified',
     agentUnverified: 'unverified',
     agentVerifyNote: 'stdio agents are verified after restart',
-    // Skill auto-install
-    skillWhat: 'Skills teach AI agents how to use your knowledge base — like instructions for reading, writing, and organizing your notes.',
-    skillAutoHint: (name: string) => `Based on your template, the "${name}" skill will be installed to selected agents.`,
+    // Skill (kept for type compat — UI section removed in v0.7)
+    skillWhat: '',
+    skillAutoHint: () => '',
     skillLabel: 'Skill',
     skillInstalling: 'Installing skill…',
     skillInstalled: 'Skill installed',
@@ -111,7 +116,7 @@ export const onboardingEn = {
     retryAgent: 'Retry',
     agentFailedCount: (n: number) => `${n} agent${n > 1 ? 's' : ''} failed`,
     agentCountSummary: (n: number) => `${n} agent${n > 1 ? 's' : ''}`,
-    agentFailureNote: 'Agent failures are non-blocking — you can enter MindOS and retry from Settings → MCP.',
+    agentFailureNote: 'Agent failures are non-blocking — you can enter MindOS and retry from Settings → Connections.',
     portAvailable: 'Available',
     portChanged: 'Port changed — please restart the server for it to take effect.',
     restartRequired: 'Server restart required for these changes to take effect.',
@@ -134,14 +139,14 @@ export const onboardingEn = {
     healthAi: 'AI Provider',
     healthAiNone: 'Not configured — AI features disabled',
     healthAiAction: 'Add an API key in Settings → AI.',
-    healthAgents: 'Agent Tools',
+    healthAgents: 'Agent Connection',
     healthAgentsOk: (n: number) => `${n} agent${n > 1 ? 's' : ''} configured`,
     healthAgentsPartial: 'Configuration in progress...',
     healthAgentsNone: 'No agents configured',
-    healthAgentsAction: 'You can add agents later in Settings → MCP.',
-    healthTokenTitle: 'MCP Auth Token',
+    healthAgentsAction: 'You can add agents later in Settings → Connections.',
+    healthTokenTitle: 'Auth Token',
     healthTokenCopy: 'Copy token',
-    healthTokenHint: 'Use this token when connecting AI agents. Also available in Settings → MCP.',
+    healthTokenHint: 'Used by CLI remote mode and MCP connections. Also available in Settings → Connections.',
     healthGoHome: 'Go to MindOS',
     // Welcome banner (shown after first onboard)
     welcomeTitle: 'Welcome to MindOS!',
@@ -229,7 +234,7 @@ export const onboardingZh = {
     dismiss: '关闭',
   },
   setup: {
-    stepTitles: ['知识库', 'AI 配置', 'Agent 工具', '确认'],
+    stepTitles: ['知识库', 'AI 配置', 'Agent 连接', '确认'],
     // Step 1
     kbPath: '知识库路径',
     kbPathHint: '笔记目录的绝对路径。',
@@ -274,17 +279,22 @@ export const onboardingZh = {
     webPasswordHint: '保护你的知识库，防止未授权的浏览器访问。',
     webPasswordRequired: '密码是必填项，用于保护你的数据。',
     advancedPorts: '高级设置',
-    tokenSectionTitle: 'MCP 认证令牌（已自动生成）',
+    tokenSectionTitle: '认证令牌（已自动生成）',
     tokenSectionHint: 'AI Agent 连接你的 MindOS 服务器时使用。',
-    // Step 5 — Agent Tools
-    agentToolsTitle: 'Agent 工具',
-    agentToolsHint: '选择要与 MindOS MCP 配置的 AI Agent。标注「未安装」的 agent 可以先行配置，安装应用后即可生效。',
+    // Step 5 — Agent Connection
+    agentToolsTitle: 'Agent 连接',
+    connectionModeTitle: '连接模式',
+    connectionModeCliHint: '推荐 · 更省 token',
+    connectionModeMcpHint: '可选 · 消耗更多 token',
+    agentToolsHint: '选择要配置的 AI Agent。此步骤可选。',
+    agentToolsHintCliOnly: 'Agent 选择在 MCP 模式启用时生效。CLI 可直接用于所有支持 bash 的 Agent。',
+    agentToolsHintNone: '未选择连接模式。请至少选择一种模式以连接 Agent。',
     agentTransport: '传输方式',
     agentScope: '范围',
     agentToolsLoading: '正在加载 Agent…',
     agentToolsEmpty: '未检测到受支持的 Agent。',
-    agentNoneSelected: '未选择 agent — 可稍后在 设置 → MCP 中配置。',
-    agentSkipLater: '跳过 — 稍后在 设置 > MCP 中安装',
+    agentNoneSelected: '未选择 Agent。可稍后在设置中配置。',
+    agentSkipLater: '清除选择',
     agentSelectDetected: '选择已检测到的 Agent',
     agentNoneDetected: '未在系统中检测到已安装的 Agent。',
     agentShowMore: (n: number) => `显示另外 ${n} 个 Agent`,
@@ -305,9 +315,9 @@ export const onboardingZh = {
     agentVerified: '已验证',
     agentUnverified: '未验证',
     agentVerifyNote: 'stdio agent 需重启后验证',
-    // Skill auto-install
-    skillWhat: '技能教 AI Agent 如何使用你的知识库——包括笔记的读取、写入和整理规则。',
-    skillAutoHint: (name: string) => `根据您选择的模板，将向选中的 Agent 安装「${name}」技能。`,
+    // Skill (kept for type compat — UI section removed in v0.7)
+    skillWhat: '',
+    skillAutoHint: () => '',
     skillLabel: '技能',
     skillInstalling: '正在安装技能…',
     skillInstalled: '技能已安装',
@@ -325,7 +335,7 @@ export const onboardingZh = {
     retryAgent: '重试',
     agentFailedCount: (n: number) => `${n} 个 Agent 配置失败`,
     agentCountSummary: (n: number) => `${n} 个 Agent`,
-    agentFailureNote: 'Agent 安装失败不影响进入 MindOS — 可稍后在 设置 → MCP 中重试。',
+    agentFailureNote: 'Agent 安装失败不影响进入 MindOS — 可稍后在 设置 → 连接 中重试。',
     portAvailable: '可用',
     portChanged: '端口已变更 — 请重启服务以使其生效。',
     restartRequired: '以下变更需要重启服务后生效。',
@@ -348,14 +358,14 @@ export const onboardingZh = {
     healthAi: 'AI 服务',
     healthAiNone: '未配置 — AI 功能不可用',
     healthAiAction: '可在 设置 → AI 中添加 API 密钥。',
-    healthAgents: 'Agent 工具',
+    healthAgents: 'Agent 连接',
     healthAgentsOk: (n: number) => `已配置 ${n} 个 Agent`,
     healthAgentsPartial: '正在配置中...',
     healthAgentsNone: '未配置 Agent',
-    healthAgentsAction: '可稍后在 设置 → MCP 中添加。',
-    healthTokenTitle: 'MCP 认证令牌',
+    healthAgentsAction: '可稍后在 设置 → 连接 中添加。',
+    healthTokenTitle: '认证令牌',
     healthTokenCopy: '复制令牌',
-    healthTokenHint: '连接 AI 助手时需要此令牌。也可在 设置 → MCP 中找到。',
+    healthTokenHint: 'CLI 远程模式和 MCP 连接时使用。也可在 设置 → 连接 中找到。',
     healthGoHome: '进入 MindOS',
     // Welcome banner
     welcomeTitle: '欢迎使用 MindOS！',

package/app/lib/i18n/modules/settings.ts

@@ -3,7 +3,7 @@
 export const settingsEn = {
   settings: {
     title: 'Settings',
-    tabs: { ai: 'AI', appearance: 'Appearance', knowledge: 'General', sync: 'Sync', mcp: 'MCP & Skills', plugins: 'Plugins', shortcuts: 'Shortcuts', monitoring: 'Monitoring', agents: 'Agents', update: 'Update', uninstall: 'Uninstall' },
+    tabs: { ai: 'AI', appearance: 'Appearance', knowledge: 'General', sync: 'Sync', mcp: 'Connections', plugins: 'Plugins', shortcuts: 'Shortcuts', monitoring: 'Monitoring', agents: 'Agents', update: 'Update', uninstall: 'Uninstall' },
     ai: {
       provider: 'Provider',
       model: 'Model',
@@ -226,6 +226,7 @@ export const settingsEn = {
       portLabel: 'MCP Port',
       portHint: 'Changes require server restart',
       skillsTitle: 'Skills',
+      skillsDesc: 'Teach agents how to operate your knowledge base.',
       skillAutoLoaded: 'Auto-loaded on every request',
       skillSource: 'Source',
       skillBuiltin: 'Built-in',
@@ -268,8 +269,11 @@ export const settingsEn = {
       noAuthWarning: '⚠ No auth token — set one in Settings → General before enabling remote access.',
       showJson: 'Show JSON',
       hideJson: 'Hide JSON',
-      connectionTitle: 'Connection',
-      connectionHint: 'Use these credentials to connect AI agents to your MindOS knowledge base.',
+      connectionTitle: 'Connect Agents',
+      connectionHint: 'Choose how your AI agents connect to MindOS.',
+      tokenCardTitle: 'Auth Token',
+      tokenCardDesc: 'Used by CLI remote mode and MCP connections.',
+      mcpHint: 'For Claude Desktop, Cursor, and agents that use MCP tool protocol.',
       tokenLabel: 'Auth Token',
       tokenMasked: 'Click Show to reveal the full token',
       tokenShow: 'Show',
@@ -285,6 +289,38 @@ export const settingsEn = {
       howToStep2: 'Add a new MCP server with the URL above',
       howToStep3: 'Set the Auth Token as the bearer token',
       howToStep4: 'Save and verify the connection',
+      // CLI Skill
+      cliSkillTitle: 'CLI Skill',
+      cliSkillHint: 'For agents with bash (Claude Code, Gemini CLI, Codex) — lower token cost, no MCP needed.',
+      cliSkillDesc: 'Lower token cost, Skill included — just install and go.',
+      cliLocalDesc: 'MindOS Skill is built-in. Install the CLI and you\'re good to go.',
+      cliRemoteDesc: 'Install the CLI on another machine and connect to this MindOS server.',
+      cliSkillInstall: 'Install',
+      cliSkillInstallCmd: 'npm install -g @geminilight/mindos',
+      cliSkillRemote: 'Remote',
+      cliSkillVerify: 'Verify',
+      cliSkillVerifyCmd: 'mindos file list',
+      cliRemoteConfigure: 'Configure',
+      cliInstallSkill: 'Install Skill',
+      cliAgents: 'Claude Code · Gemini CLI · Codex',
+      mcpAgents: 'Claude Desktop · Cursor',
+      mcpDesc: 'Requires per-agent MCP config. Install Skill separately via',
+      mcpLocalDesc: 'Copy the config snippet and paste into your agent\'s MCP settings.',
+      mcpRunningLabel: 'MCP Running',
+      mcpServerStatus: 'MCP Server',
+      autoInstallAgents: 'Auto-install to detected agents',
+      detectedAgentsTitle: 'Detected Agents',
+      cliInstallDesc: 'Install the MindOS Skill to your agent so it can operate your knowledge base.',
+      mcpInstallDesc: 'Install MCP config + Skill to detected agents on this machine.',
+      tokenCopyFullHint: 'Copies full token',
+      skillsInstalled: 'skills installed',
+      recommended: 'Recommended',
+      localTitle: 'Local',
+      localReady: 'Ready to use',
+      remoteTitle: 'Remote Access',
+      remoteSubtitle: 'Connect from another device',
+      restarting: 'Restarting...',
+      restart: 'Restart',
     },
     monitoring: {
       system: 'System',
@@ -409,7 +445,7 @@ export const settingsEn = {
 export const settingsZh = {
   settings: {
     title: '设置',
-    tabs: { ai: 'AI', appearance: '外观', knowledge: '通用', sync: '同步', mcp: 'MCP 与技能', plugins: '插件', shortcuts: '快捷键', monitoring: '监控', agents: '智能体', update: '更新', uninstall: '卸载' },
+    tabs: { ai: 'AI', appearance: '外观', knowledge: '通用', sync: '同步', mcp: '连接', plugins: '插件', shortcuts: '快捷键', monitoring: '监控', agents: '智能体', update: '更新', uninstall: '卸载' },
     ai: {
       provider: '服务商',
       model: '模型',
@@ -632,6 +668,7 @@ export const settingsZh = {
       portLabel: 'MCP 端口',
       portHint: '修改后需重启服务',
       skillsTitle: '技能',
+      skillsDesc: '教 Agent 如何操作你的知识库。',
       skillAutoLoaded: '每次请求自动加载',
       skillSource: '来源',
       skillBuiltin: '内置',
@@ -674,8 +711,11 @@ export const settingsZh = {
       noAuthWarning: '⚠ 未设置认证令牌 — 请先在 设置 → 通用 中配置，再启用远程访问。',
       showJson: '显示 JSON',
       hideJson: '隐藏 JSON',
-      connectionTitle: '连接信息',
-      connectionHint: '使用以下凭据将 AI 助手连接到你的 MindOS 知识库。',
+      connectionTitle: '连接 Agent',
+      connectionHint: '选择 AI Agent 连接 MindOS 的方式。',
+      tokenCardTitle: '认证令牌',
+      tokenCardDesc: '用于 CLI 远程模式和 MCP 连接。',
+      mcpHint: '适用于 Claude Desktop、Cursor 等使用 MCP 工具协议的 Agent。',
       tokenLabel: '认证令牌',
       tokenMasked: '点击「显示」查看完整令牌',
       tokenShow: '显示',
@@ -691,6 +731,38 @@ export const settingsZh = {
       howToStep2: '添加一个新的 MCP 服务，填入上方地址',
       howToStep3: '将认证令牌设为 Bearer Token',
       howToStep4: '保存并验证连接',
+      // CLI Skill
+      cliSkillTitle: 'CLI 技能',
+      cliSkillHint: '适用于支持 bash 的 Agent（Claude Code、Gemini CLI、Codex）——更省 token，无需 MCP。',
+      cliSkillDesc: '更省 token，技能内置——安装即可使用。',
+      cliLocalDesc: 'MindOS Skill 已内置，安装 CLI 即可直接使用。',
+      cliRemoteDesc: '在其他设备上安装 CLI，远程连接到此 MindOS 服务器。',
+      cliSkillInstall: '安装',
+      cliSkillInstallCmd: 'npm install -g @geminilight/mindos',
+      cliSkillRemote: '远程',
+      cliSkillVerify: '验证',
+      cliSkillVerifyCmd: 'mindos file list',
+      cliRemoteConfigure: '配置',
+      cliInstallSkill: '安装技能',
+      cliAgents: 'Claude Code · Gemini CLI · Codex',
+      mcpAgents: 'Claude Desktop · Cursor',
+      mcpDesc: '需要逐个 Agent 配置 MCP，通过以下命令单独安装技能：',
+      mcpLocalDesc: '复制下方配置代码，粘贴到你的 Agent 的 MCP 设置中。',
+      mcpRunningLabel: 'MCP 运行中',
+      mcpServerStatus: 'MCP 服务',
+      autoInstallAgents: '自动安装到已检测的 Agent',
+      detectedAgentsTitle: '检测到的 Agent',
+      cliInstallDesc: '为你的 Agent 安装 MindOS Skill，让它能操作你的知识库。',
+      mcpInstallDesc: '为本机检测到的 Agent 安装 MCP 配置和 Skill。',
+      tokenCopyFullHint: '复制完整令牌',
+      skillsInstalled: '个技能已安装',
+      recommended: '推荐',
+      localTitle: '本机',
+      localReady: '可直接使用',
+      remoteTitle: '远程访问',
+      remoteSubtitle: '从其他设备连接',
+      restarting: '重启中...',
+      restart: '重启',
     },
     monitoring: {
       system: '系统',

package/app/lib/mcp-agents.ts

@@ -6,10 +6,9 @@ import { execSync } from 'child_process';
 /** Parse JSONC — strips single-line (//) and block comments before JSON.parse */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 function parseJsonc(text: string): any {
-  // Strip single-line comments (not inside strings)
   let stripped = text.replace(/\\"|"(?:\\"|[^"])*"|(\/\/.*$)/gm, (m, g) => g ? '' : m);
-  // Strip block comments
   stripped = stripped.replace(/\/\*[\s\S]*?\*\//g, '');
+  if (!stripped.trim()) return {};
   return JSON.parse(stripped);
 }
 

package/app/lib/mcp-snippets.ts

@@ -94,9 +94,13 @@ export function generateSnippet(
   if (transport === 'stdio') {
     return generateStdioSnippet(agent);
   }
+  // For remote/http mode, prefer localIP over endpoint (which is always localhost)
+  const endpoint = status?.localIP
+    ? `http://${status.localIP}:${status.port}/mcp`
+    : (status?.endpoint ?? 'http://127.0.0.1:8781/mcp');
   return generateHttpSnippet(
     agent,
-    status?.endpoint ?? 'http://127.0.0.1:8781/mcp',
+    endpoint,
     status?.authToken,
     status?.maskedToken,
   );

package/app/lib/renderers/index.ts

@@ -3,6 +3,7 @@
  * To regenerate: node scripts/gen-renderer-index.js
  */
 import { registerRenderer } from './registry';
+import { manifest as agentInspector } from '@/components/renderers/agent-inspector/manifest';
 import { manifest as backlinks } from '@/components/renderers/backlinks/manifest';
 import { manifest as config } from '@/components/renderers/config/manifest';
 import { manifest as csv } from '@/components/renderers/csv/manifest';
@@ -13,7 +14,7 @@ import { manifest as workflowYaml } from '@/components/renderers/workflow-yaml/m
 import { manifest as graph } from '@/components/renderers/graph/manifest';
 
 const manifests = [
-  backlinks, config, csv, summary, timeline, todo, workflowYaml, graph,
+  agentInspector, backlinks, config, csv, summary, timeline, todo, workflowYaml, graph,
 ];
 
 for (const m of manifests) {