remnote-bridge 0.1.0

package/dist/mcp/tools/infra-tools.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 基础设施工具：connect、disconnect、health
+ */
+import type { FastMCP } from 'fastmcp';
+export declare function registerInfraTools(server: FastMCP): void;

package/dist/mcp/tools/infra-tools.js

@@ -0,0 +1,43 @@
+/**
+ * 基础设施工具：connect、disconnect、health
+ */
+import { z } from 'zod';
+import { callCli } from '../daemon-client.js';
+export function registerInfraTools(server) {
+    // -------------------------------------------------------------------------
+    // connect
+    // -------------------------------------------------------------------------
+    server.addTool({
+        name: 'connect',
+        description: '启动守护进程（daemon），建立 CLI 与 RemNote Plugin 之间的通信通道。这是所有业务命令（read_rem、edit_rem、search 等）的前置步骤。\n\n适用场景：\n- 开始一次 RemNote 操作会话前，必须先调用此工具\n- 不确定 daemon 是否在运行时，也可安全调用（幂等）\n\n输出：返回 JSON，关键字段 ok、alreadyRunning（是否已运行）、pid、wsPort。\n幂等：重复调用不会启动多个 daemon。daemon 默认 30 分钟无活动自动关闭。\n关联工具：disconnect（结束会话）、health（检查状态）',
+        parameters: z.object({}),
+        execute: async () => {
+            const response = await callCli('connect');
+            return JSON.stringify(response, null, 2);
+        },
+    });
+    // -------------------------------------------------------------------------
+    // disconnect
+    // -------------------------------------------------------------------------
+    server.addTool({
+        name: 'disconnect',
+        description: '停止守护进程，释放所有端口、清空内存缓存、结束当前会话。\n\n适用场景：\n- 操作完成后主动释放资源\n- 需要重置连接状态（例如排查问题时先 disconnect 再 connect）\n\n输出：返回 JSON，关键字段 ok、wasRunning（之前是否在运行）、pid。\n幂等：daemon 未运行时调用也返回 ok: true。\n所有缓存随 daemon 退出清空，下次 connect 后需重新 read。\n关联工具：connect（启动会话）、health（检查状态）',
+        parameters: z.object({}),
+        execute: async () => {
+            const response = await callCli('disconnect');
+            return JSON.stringify(response, null, 2);
+        },
+    });
+    // -------------------------------------------------------------------------
+    // health
+    // -------------------------------------------------------------------------
+    server.addTool({
+        name: 'health',
+        description: '检查系统三层状态（daemon 守护进程 / Plugin 连接 / SDK 就绪），用于诊断连接问题。\n\n适用场景：\n- 业务命令失败时，首先调用 health 定位故障层级\n- 执行 connect 后确认通道是否完全就绪\n- 长时间未操作后，检查 daemon 是否仍在运行\n\n输出：返回 JSON，关键字段 ok（三层是否全部健康）、daemon.running、plugin.connected、sdk.ready、timeoutRemaining。\n三层有严格依赖：daemon 运行 → Plugin 连接 → SDK 就绪。\nok 为 false 时：daemon 未运行则 connect；Plugin 未连接则确认 RemNote 已打开；SDK 未就绪则等待重试。\n只读不写，不改变任何状态。\n关联工具：connect（启动）、disconnect（结束）',
+        parameters: z.object({}),
+        execute: async () => {
+            const response = await callCli('health');
+            return JSON.stringify(response, null, 2);
+        },
+    });
+}

package/dist/mcp/tools/read-tools.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 读取类工具：search、read_rem、read_tree、read_globe、read_context
+ */
+import type { FastMCP } from 'fastmcp';
+export declare function registerReadTools(server: FastMCP): void;

package/dist/mcp/tools/read-tools.js

@@ -0,0 +1,195 @@
+/**
+ * 读取类工具：search、read_rem、read_tree、read_globe、read_context
+ */
+import { z } from 'zod';
+import { callCli } from '../daemon-client.js';
+export function registerReadTools(server) {
+    // -------------------------------------------------------------------------
+    // search
+    // -------------------------------------------------------------------------
+    server.addTool({
+        name: 'search',
+        description: '在 RemNote 知识库中按关键词全文搜索 Rem，返回匹配结果的摘要列表。\n\n适用场景：知道关键词但不知道位置时使用；按结构浏览应使用 read_globe。\n输出：results 数组，每项包含 remId、text（Markdown 单行）、isDocument，以及 totalFound。\n搜索结果不写入缓存——需要详情请拿 remId 调用 read_rem 或 read_tree。\n中文搜索限制：SDK 分词基于空格，中文多字词可能搜不到，建议用单字重试或改用 read_globe + read_tree 按结构定位。\n常见工作流：search 定位 → read_rem 获取详情 → read_tree 展开子树。\n关联工具：read_rem（详情）、read_tree（子树）、read_globe（按结构浏览）',
+        parameters: z.object({
+            query: z.string().describe('搜索关键词'),
+            numResults: z
+                .number()
+                .optional()
+                .describe('结果数量上限，默认 20'),
+        }),
+        execute: async (args) => {
+            const payload = { query: args.query };
+            if (args.numResults !== undefined)
+                payload.numResults = args.numResults;
+            const response = await callCli('search', payload);
+            return JSON.stringify(response, null, 2);
+        },
+    });
+    // -------------------------------------------------------------------------
+    // read_rem
+    // -------------------------------------------------------------------------
+    server.addTool({
+        name: 'read_rem',
+        description: '通过 Rem ID 读取单个 Rem 的完整属性，返回标准化的 RemObject（JSON 格式）。\n\n适用场景：\n- 查看 Rem 的详细属性（文本、类型、标签、父子关系、练习方向等）\n- 作为 edit_rem 的前置步骤——必须先 read_rem 建立缓存\n- 不适合查看子树结构（那是 read_tree）\n\n输出：RemObject JSON，默认 34 个常用字段，full=true 返回 51 个，fields 可指定子集。\n关键字段：id, text, backText, type, parent, children, tags, isDocument, practiceDirection。\n结果自动缓存供 edit_rem 使用。默认过滤 Powerup 噪音。\n完整字段列表见 resource://rem-object-fields。\n关联工具：search（定位 remId）→ read_rem → edit_rem（编辑属性）\n区别：read_tree 返回子树大纲，read_rem 返回单个 Rem 的 JSON',
+        parameters: z.object({
+            remId: z.string().describe('目标 Rem 的 ID'),
+            fields: z
+                .array(z.string())
+                .optional()
+                .describe('只返回指定字段（默认返回全部）'),
+            full: z
+                .boolean()
+                .optional()
+                .describe('是否返回完整 RichText 原始结构'),
+            includePowerup: z
+                .boolean()
+                .optional()
+                .describe('是否包含 Powerup 元信息'),
+        }),
+        execute: async (args) => {
+            const payload = { remId: args.remId };
+            if (args.fields !== undefined)
+                payload.fields = args.fields;
+            if (args.full !== undefined)
+                payload.full = args.full;
+            if (args.includePowerup !== undefined)
+                payload.includePowerup = args.includePowerup;
+            const response = await callCli('read-rem', payload);
+            return JSON.stringify(response, null, 2);
+        },
+    });
+    // -------------------------------------------------------------------------
+    // read_tree
+    // -------------------------------------------------------------------------
+    server.addTool({
+        name: 'read_tree',
+        description: '将指定 Rem 的子树序列化为 Markdown 大纲，支持深度/节点预算控制和祖先路径追溯。\n\n适用场景：\n- 查看 Rem 的子树结构（而非单个 Rem 属性，那是 read_rem）\n- 作为 edit_tree 的强制前置步骤——必须先 read_tree 建立缓存\n- 不适合全局鸟瞰（那是 read_globe）\n\n输出：Markdown 大纲文本，每行格式 {缩进}{内容} <!-- {remId} {标记} -->。\n该大纲同时也是 edit_tree 的操作对象。\n\n预算控制三维度：\n- depth（默认 3，-1 无限）：递归深度，超限节点标记 children:N\n- maxSiblings（默认 20）：单层上限，超限时 70%头+30%尾 省略\n- maxNodes（默认 200）：全局上限\n\n结果自动缓存供 edit_tree 使用。ancestorLevels 可追溯祖先提供面包屑上下文。\n详细大纲格式见 resource://outline-format。\n关联工具：search（定位 remId）→ read_tree → edit_tree（结构编辑）',
+        parameters: z.object({
+            remId: z.string().describe('根 Rem 的 ID'),
+            depth: z
+                .number()
+                .optional()
+                .describe('展开深度（默认由服务端决定）'),
+            maxNodes: z
+                .number()
+                .optional()
+                .describe('节点总数上限'),
+            maxSiblings: z
+                .number()
+                .optional()
+                .describe('同级节点显示上限（超出省略）'),
+            ancestorLevels: z
+                .number()
+                .optional()
+                .describe('向上展示的祖先层级数'),
+            includePowerup: z
+                .boolean()
+                .optional()
+                .describe('是否包含 Powerup 元信息'),
+        }),
+        execute: async (args) => {
+            const payload = { remId: args.remId };
+            if (args.depth !== undefined)
+                payload.depth = args.depth;
+            if (args.maxNodes !== undefined)
+                payload.maxNodes = args.maxNodes;
+            if (args.maxSiblings !== undefined)
+                payload.maxSiblings = args.maxSiblings;
+            if (args.ancestorLevels !== undefined)
+                payload.ancestorLevels = args.ancestorLevels;
+            if (args.includePowerup !== undefined)
+                payload.includePowerup = args.includePowerup;
+            const response = await callCli('read-tree', payload);
+            // read-tree 返回的大纲在 response.data.outline 中
+            const data = response.data;
+            if (data?.outline && typeof data.outline === 'string') {
+                return data.outline;
+            }
+            return JSON.stringify(response, null, 2);
+        },
+    });
+    // -------------------------------------------------------------------------
+    // read_globe
+    // -------------------------------------------------------------------------
+    server.addTool({
+        name: 'read_globe',
+        description: '读取知识库全局 Document 层级概览，生成 Markdown 大纲。\n无需指定 remId，自动扫描整个知识库的顶层 Rem，仅递归展开 Document 类型节点；\n非 Document 子节点不展开，仅标注 children:N。\n\n适用场景：\n- 首次探索知识库，了解有哪些文档及层级关系\n- 用户说"有哪些文档"、"知识库里有什么"\n- 不适合搜索特定内容（用 search）\n- 不适合查看某 Rem 内部子节点（用 read_tree）\n\n输出：Markdown 大纲，每行包含 Document 名称和元数据。\n不缓存结果，每次调用获取最新数据。Powerup 节点自动过滤。Portal 感知。\n预算参数：depth（默认 -1 无限）、maxNodes（200）、maxSiblings（20）。\n典型工作流：read_globe 获取宏观结构 → search 或 read_tree 深入。',
+        parameters: z.object({
+            depth: z
+                .number()
+                .optional()
+                .describe('展开深度'),
+            maxNodes: z
+                .number()
+                .optional()
+                .describe('节点总数上限'),
+            maxSiblings: z
+                .number()
+                .optional()
+                .describe('同级节点显示上限'),
+        }),
+        execute: async (args) => {
+            const payload = {};
+            if (args.depth !== undefined)
+                payload.depth = args.depth;
+            if (args.maxNodes !== undefined)
+                payload.maxNodes = args.maxNodes;
+            if (args.maxSiblings !== undefined)
+                payload.maxSiblings = args.maxSiblings;
+            const response = await callCli('read-globe', payload);
+            const data = response.data;
+            if (data?.outline && typeof data.outline === 'string') {
+                return data.outline;
+            }
+            return JSON.stringify(response, null, 2);
+        },
+    });
+    // -------------------------------------------------------------------------
+    // read_context
+    // -------------------------------------------------------------------------
+    server.addTool({
+        name: 'read_context',
+        description: '读取用户在 RemNote 中的当前上下文视图，生成带面包屑路径的 Markdown 大纲。\n无需指定 remId，自动获取用户当前焦点位置或打开的页面。\n\n适用场景：\n- 用户说"我现在在看什么"、"当前页面是什么"\n- 需要了解用户焦点位置以提供上下文帮助\n- 不适合查看特定 Rem（已知 remId 用 read_tree）\n\n两种模式：\n- focus（默认）：以焦点 Rem 为中心的鱼眼视图。焦点完全展开（depth=3），siblings 浅层预览（depth=1），叔伯不展开。焦点行以 * 前缀标记。\n- page：以当前页面为根均匀展开子树。\n\n输出：Markdown 大纲 + 面包屑路径。不缓存。\n前提：focus 模式需用户有焦点 Rem，page 模式需有打开的页面。\n典型工作流：read_context 了解位置 → read_tree/read_rem 深入。',
+        parameters: z.object({
+            mode: z
+                .enum(['focus', 'page'])
+                .optional()
+                .describe('视图模式：focus（聚焦）或 page（页面），默认 focus'),
+            ancestorLevels: z
+                .number()
+                .optional()
+                .describe('向上展示的祖先层级数'),
+            depth: z
+                .number()
+                .optional()
+                .describe('展开深度'),
+            maxNodes: z
+                .number()
+                .optional()
+                .describe('节点总数上限'),
+            maxSiblings: z
+                .number()
+                .optional()
+                .describe('同级节点显示上限'),
+        }),
+        execute: async (args) => {
+            const payload = {};
+            if (args.mode !== undefined)
+                payload.mode = args.mode;
+            if (args.ancestorLevels !== undefined)
+                payload.ancestorLevels = args.ancestorLevels;
+            if (args.depth !== undefined)
+                payload.depth = args.depth;
+            if (args.maxNodes !== undefined)
+                payload.maxNodes = args.maxNodes;
+            if (args.maxSiblings !== undefined)
+                payload.maxSiblings = args.maxSiblings;
+            const response = await callCli('read-context', payload);
+            const data = response.data;
+            if (data?.outline && typeof data.outline === 'string') {
+                return data.outline;
+            }
+            return JSON.stringify(response, null, 2);
+        },
+    });
+}

package/dist/mcp/types.d.ts

@@ -0,0 +1,12 @@
+/**
+ * MCP Server 共享类型定义
+ */
+/** remnote-bridge --json 模式的标准响应结构 */
+export interface CliResponse {
+    ok: boolean;
+    command: string;
+    error?: string;
+    data?: unknown;
+    timestamp?: string;
+    [key: string]: unknown;
+}

package/dist/mcp/types.js

@@ -0,0 +1,4 @@
+/**
+ * MCP Server 共享类型定义
+ */
+export {};

package/docs/instruction/connect.md

@@ -0,0 +1,158 @@
+# connect
+
+> 启动守护进程，建立 CLI ↔ Plugin 通信通道。这是所有业务命令的前置步骤。
+
+---
+
+## 功能
+
+`connect` 以 fork 子进程方式启动后台守护进程（daemon），daemon 内部启动三个服务：
+
+| 服务 | 默认端口 | 用途 |
+|------|----------|------|
+| WS Server | 3002 | CLI 命令 ↔ daemon ↔ Plugin 的双向通信 |
+| webpack-dev-server | 8080 | 将 remnote-plugin 热加载到 RemNote 浏览器 |
+| ConfigServer | 3003 | HTTP 配置管理界面 |
+
+daemon 启动后脱离父进程（detached），CLI 进程退出但 daemon 继续运行。
+
+---
+
+## 用法
+
+### 人类模式
+
+```bash
+remnote-bridge connect
+```
+
+输出示例：
+
+```
+守护进程已启动（PID: 12345）
+  WS Server:         ws://127.0.0.1:3002
+  webpack-dev-server: http://localhost:8080
+  配置页面:          http://127.0.0.1:3003
+  超时: 30 分钟无 CLI 交互后自动关闭
+```
+
+### JSON 模式
+
+```bash
+remnote-bridge --json connect
+```
+
+---
+
+## JSON 输出
+
+### 首次启动
+
+```json
+{
+  "ok": true,
+  "command": "connect",
+  "alreadyRunning": false,
+  "pid": 12345,
+  "wsPort": 3002,
+  "devServerPort": 8080,
+  "configPort": 3003,
+  "timeoutMinutes": 30,
+  "timestamp": "2026-03-06T10:00:00.000Z"
+}
+```
+
+### 已在运行
+
+```json
+{
+  "ok": true,
+  "command": "connect",
+  "alreadyRunning": true,
+  "pid": 12345,
+  "wsPort": 3002,
+  "devServerPort": 8080,
+  "timestamp": "2026-03-06T10:00:00.000Z"
+}
+```
+
+### 启动失败
+
+```json
+{
+  "ok": false,
+  "command": "connect",
+  "error": "守护进程启动超时（10 秒）",
+  "timestamp": "2026-03-06T10:00:00.000Z"
+}
+```
+
+---
+
+## 启动流程
+
+```
+1. 检查 PID 文件 (.remnote-bridge.pid)
+   ├─ 已在运行 → 返回 ok + alreadyRunning: true
+   └─ 未运行 / stale PID → 继续
+
+2. fork 守护进程（detached, stdio 全部 ignore）
+
+3. daemon 内部按顺序启动：
+   ├─ WS Server（必须成功，否则 daemon 退出）
+   ├─ ConfigServer（非关键，失败不阻塞）
+   └─ webpack-dev-server（必须成功，否则 daemon 退出）
+
+4. daemon 写入 PID 文件
+
+5. daemon 通过 IPC 发送 ready 信号给父进程
+
+6. 父进程（CLI）收到 ready → 输出结果 → 退出
+   ├─ 10 秒内未收到 → 超时失败
+   └─ 收到 error → 启动失败
+```
+
+---
+
+## 超时机制
+
+daemon 启动后开始计时，默认 **30 分钟无 CLI 交互**自动关闭（执行优雅 shutdown）。每次收到 CLI 请求时重置计时器。
+
+超时时间可通过配置文件 `.remnote-bridge.json` 的 `daemonTimeoutMinutes` 字段调整。
+
+---
+
+## 幂等性
+
+重复调用 `connect` 是安全的。如果 daemon 已在运行，命令直接返回 `ok: true, alreadyRunning: true`，不会启动第二个实例。
+
+---
+
+## 退出码
+
+| 退出码 | 含义 |
+|--------|------|
+| 0 | 启动成功，或已在运行 |
+| 1 | 启动失败（超时、端口冲突、webpack-dev-server 异常等） |
+
+---
+
+## 配置依赖
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| wsPort | 3002 | WS Server 监听端口 |
+| devServerPort | 8080 | webpack-dev-server 端口 |
+| configPort | 3003 | ConfigServer 端口 |
+| daemonTimeoutMinutes | 30 | 无活动自动关闭的分钟数 |
+
+三个端口不允许冲突（配置加载时校验）。
+
+---
+
+## 产生的文件
+
+| 文件 | 位置 | 生命周期 |
+|------|------|----------|
+| `.remnote-bridge.pid` | 项目根目录 | daemon 运行期间存在，关闭时删除 |
+| `.remnote-bridge.log` | 项目根目录 | 追加写入，跨会话保留 |

package/docs/instruction/disconnect.md

@@ -0,0 +1,146 @@
+# disconnect
+
+> 停止守护进程，释放端口、清空缓存、结束会话。
+
+---
+
+## 功能
+
+`disconnect` 向守护进程发送 SIGTERM 信号，触发优雅关闭：
+
+1. 关闭 WS Server（断开所有连接）
+2. 关闭 ConfigServer
+3. 停止 webpack-dev-server 子进程
+4. 删除 PID 文件
+5. 内存缓存随进程退出自动消失
+
+---
+
+## 用法
+
+### 人类模式
+
+```bash
+remnote-bridge disconnect
+```
+
+输出示例：
+
+```
+正在停止守护进程（PID: 12345）...
+守护进程已停止
+```
+
+### JSON 模式
+
+```bash
+remnote-bridge --json disconnect
+```
+
+---
+
+## JSON 输出
+
+### 正常停止
+
+```json
+{
+  "ok": true,
+  "command": "disconnect",
+  "wasRunning": true,
+  "pid": 12345,
+  "forced": false,
+  "timestamp": "2026-03-06T10:00:00.000Z"
+}
+```
+
+### 强制终止（SIGTERM 超时后 SIGKILL）
+
+```json
+{
+  "ok": true,
+  "command": "disconnect",
+  "wasRunning": true,
+  "pid": 12345,
+  "forced": true,
+  "timestamp": "2026-03-06T10:00:00.000Z"
+}
+```
+
+### 未在运行
+
+```json
+{
+  "ok": true,
+  "command": "disconnect",
+  "wasRunning": false,
+  "timestamp": "2026-03-06T10:00:00.000Z"
+}
+```
+
+---
+
+## 关闭流程
+
+```
+1. 检查 PID 文件
+   └─ 未运行 → 返回 ok + wasRunning: false
+
+2. 发送 SIGTERM
+   ├─ 进程已退出 → 清理 PID 文件 → 返回 ok
+   └─ 进程仍在 → 进入等待
+
+3. 轮询等待退出（每 200ms 检查一次）
+   ├─ 10 秒内退出 → 清理 PID 文件 → 返回 ok + forced: false
+   └─ 超时未退出 → 发送 SIGKILL → 清理 PID 文件 → 返回 ok + forced: true
+```
+
+### daemon 优雅关闭（SIGTERM 触发）
+
+daemon 收到 SIGTERM 后依次执行：
+
+1. 停止超时计时器
+2. 关闭 WS Server（所有 WS 连接断开）
+3. 关闭 ConfigServer（HTTP 服务停止）
+4. 停止 webpack-dev-server（先 SIGTERM，5 秒后 SIGKILL）
+5. 删除 PID 文件
+6. 关闭日志流
+7. `process.exit(0)`
+
+---
+
+## 副作用
+
+| 影响 | 说明 |
+|------|------|
+| **缓存清空** | 所有 `rem:*` 和 `tree:*` 缓存随 daemon 进程退出消失 |
+| **Plugin 断开** | WS 连接关闭，Plugin 进入重连循环（指数退避） |
+| **端口释放** | wsPort / devServerPort / configPort 全部释放 |
+| **PID 文件删除** | `.remnote-bridge.pid` 被删除 |
+| **日志保留** | `.remnote-bridge.log` 保留（追加写入，不删除） |
+
+---
+
+## 退出码
+
+| 退出码 | 含义 |
+|--------|------|
+| 0 | 停止成功，或本来就未运行 |
+
+`disconnect` 总是返回 `ok: true`，无论 daemon 是否在运行。
+
+---
+
+## 幂等性
+
+重复调用 `disconnect` 是安全的。如果 daemon 已经停止，命令直接返回 `ok: true, wasRunning: false`。
+
+---
+
+## 输出字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `wasRunning` | boolean | 调用前 daemon 是否在运行 |
+| `pid` | number | daemon 的进程 ID（仅 wasRunning=true 时） |
+| `forced` | boolean | 是否使用 SIGKILL 强制终止（仅 wasRunning=true 时） |