cloudflare-mcp-smart-proxy 1.5.19 → 1.5.23

package/README.md

@@ -16,6 +16,16 @@
 
 ## 当前入口
 
+### 查找工具与准备授权
+
+连接器初始工具 `connector_discover_tools` 使用现有目录读取权限，无需先申请业务工具，也不会创建审批卡或执行业务动作。先按能力关键词搜索，例如 `{"query":"trends"}`；再把选中的名称一起放进 `toolNames`，获取公开参数、当前精确授权、资源要求及待申请清单。
+
+返回的 `authorizationRequests` 沿用 `request_project_tool_authorization`。只有 `ready: true` 的条目可原样提交其 `arguments`；缺少资源时，从 `resourceChoices` 选择后通过 `resourceSelections` 再次准备。用 `offset` 翻工具页、`resourceOffset` 翻资源页。资源不会因为唯一候选而自动扩大授权，已生效授权直接复用；创建动作所需的前置项目授权也会列入同一份准备结果。批准后用 `get_project_tool_authorization` 读取完整申请 ID，再调用原工具。
+
+查询按需执行，不加入启动同步。尚未绑定项目时仍可搜索目录，项目申请继续使用既有项目注册和连接器审批流程。全局能力仍由现有连接器全局授权治理。原始 `/mcp/tools` 目录响应保持兼容；连接器使用其 `discovery=true` 查询模式准备授权。
+
+若目录因工具重名而生成了与 Provider 合同不一致的名称，查询会返回 `catalog_name_conflict`，不生成可提交申请；Provider 修正唯一工具名后才能申请，不能去掉前缀后套用别的工具授权。
+
 ### 1. 作为 MCP stdio server 运行
 
 ```bash
@@ -100,6 +110,19 @@ npx -y -p cloudflare-mcp-smart-proxy cloudmcp-connector activate codex \
 - `GET /connectors/install-plan`
 - `POST /connectors/status-reports`
 - `POST /connectors/project-probes`
+- `GET /connectors/project-variables`
+- `POST /connectors/project-variables/pull`
+- `PUT /connectors/project-variables`
+- `DELETE /connectors/project-variables`
+
+项目变量不会作为云端 MCP 明文读取工具暴露。Connector 提供四个本地工具：
+
+- `connector_get_project_env_status`
+- `connector_plan_project_env_sync`
+- `connector_plan_project_env_delete`
+- `connector_apply_project_env_plan`
+
+Agent 只看到变量名、差异和计划 ID；值只在已绑定 Connector 与 CloudMCP 私有合同之间移动。完整语义见 [项目环境变量同步设计](../docs/CLOUDMCP_PROJECT_ENV_SYNC_2026-09-17.md)。
 
 对应的正式协议定义见：
 
@@ -148,6 +171,10 @@ node connector-cli.js reload codex
 
 ## 验证
 
+连接器启动默认不自动同步 Skill。需要更新时调用已有 `connector_sync_skills` 工具，它会完成受管版本校验、下载和本机激活后返回结果；未同步时继续使用本地已安装版本。
+
+如显式设置 `CLOUDMCP_AUTO_SYNC_SKILLS=true`，同步会在后台执行，不阻塞 MCP 握手和工具目录加载。`connector_bridge_status.state.lastSkillSync.status` 可查看 `running`、`succeeded` 或 `failed`；后台同步进行中调用手动同步会等待同一次工作，不重复下载或激活。同步失败可再次手动调用重试，不影响工具使用。
+
 ```bash
 node --test /home/coder/project/CLOUDMCP/tests/reference-connector-a3.test.js \
   /home/coder/project/CLOUDMCP/tests/codex-app-server-reload.test.js \

package/connector-cli.js

@@ -38,6 +38,8 @@ function printUsage() {
   console.error('  --codex-device-identity-path <path> Shared CloudMCP device identity');
   console.error('  --app-server-socket <path> Current runtime Codex app-server socket');
   console.error('  --runtime-id <id>          Current Codex runtime identity');
+  console.error('  --probe-timeout-ms <ms>    Fresh MCP catalog probe timeout (30000-300000; default 120000)');
+  console.error('                              Env: CLOUDMCP_CONNECTOR_PROBE_TIMEOUT_MS');
   console.error('  --dry-run                  Show output without writing');
   console.error('  --show-secrets             Explicitly include credentials in print output');
   console.error('  --approval-code <code>     One-time code shown by the CloudMCP administrator');
@@ -85,6 +87,27 @@ function resolveRequiredOption(options, flagName, envNames = []) {
   throw new Error(`Missing required option --${flagName}`);
 }
 
+function resolveConnectorProbeTimeoutMs(options = {}, env = process.env) {
+  const raw = options['probe-timeout-ms'] || env.CLOUDMCP_CONNECTOR_PROBE_TIMEOUT_MS || '120000';
+  const timeoutMs = Number(raw);
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 30_000 || timeoutMs > 300_000) {
+    throw new Error('probe-timeout-ms must be an integer between 30000 and 300000');
+  }
+  return timeoutMs;
+}
+
+async function runCodexReload(options, serverName, {
+  reload = reloadCodexMcpServer,
+  env = process.env
+} = {}) {
+  return reload({
+    serverName,
+    socketPath: options['app-server-socket'] || env.CODEX_APP_SERVER_SOCKET || '',
+    runtimeId: options['runtime-id'] || env.CODEX_RUNTIME_ID || '',
+    timeoutMs: resolveConnectorProbeTimeoutMs(options, env)
+  });
+}
+
 function buildInstallOptions(options) {
   const workspaceRoot = path.resolve(options['workspace-root'] || process.cwd());
   return {
@@ -181,11 +204,7 @@ async function runActivation(options) {
       dryRun: options.dryRun === true
     });
     if (options.ecosystem === 'codex' && !options.dryRun) {
-      result.activation = await reloadCodexMcpServer({
-        serverName: result.serverName,
-        socketPath: options['app-server-socket'] || process.env.CODEX_APP_SERVER_SOCKET || '',
-        runtimeId: options['runtime-id'] || process.env.CODEX_RUNTIME_ID || ''
-      });
+      result.activation = await runCodexReload(options, result.serverName);
     }
     if (!options.dryRun) fs.chmodSync(paths.credentialPath, 0o600);
     if (!options.dryRun && pending) {
@@ -357,11 +376,7 @@ async function main() {
     if (options.command === 'install') {
       const result = installReferenceConnector(buildInstallOptions(options));
       if (options.ecosystem === 'codex' && !options.dryRun) {
-        result.activation = await reloadCodexMcpServer({
-          serverName: result.serverName,
-          socketPath: options['app-server-socket'] || process.env.CODEX_APP_SERVER_SOCKET || '',
-          runtimeId: options['runtime-id'] || process.env.CODEX_RUNTIME_ID || ''
-        });
+        result.activation = await runCodexReload(options, result.serverName);
       }
       printInstallResult(result);
       return;
@@ -371,11 +386,7 @@ async function main() {
       if (options.ecosystem !== 'codex') {
         throw new Error('Runtime reload is currently supported only for Codex');
       }
-      const activation = await reloadCodexMcpServer({
-        serverName: options['server-name'] || 'cloudmcp',
-        socketPath: options['app-server-socket'] || process.env.CODEX_APP_SERVER_SOCKET || '',
-        runtimeId: options['runtime-id'] || process.env.CODEX_RUNTIME_ID || ''
-      });
+      const activation = await runCodexReload(options, options['server-name'] || 'cloudmcp');
       printInstallResult({
         ecosystem: 'codex',
         scope: 'user',
@@ -413,4 +424,10 @@ if (isMainEntrypoint()) {
   main();
 }
 
-export { isMainEntrypoint, parseArgs, shouldInstallExistingCredential };
+export {
+  isMainEntrypoint,
+  parseArgs,
+  resolveConnectorProbeTimeoutMs,
+  runCodexReload,
+  shouldInstallExistingCredential
+};

package/index.js

@@ -49,7 +49,7 @@ const WORKSPACE_ID = FIXED_PROJECT_CONTEXT
   : '';
 const DEVICE_IDENTITY_PATH = process.env.CLOUDMCP_DEVICE_IDENTITY_PATH || '';
 const AUTO_SYNC_PROFILE = (process.env.CLOUDMCP_AUTO_SYNC_PROFILE || 'true') !== 'false';
-const AUTO_SYNC_SKILLS = (process.env.CLOUDMCP_AUTO_SYNC_SKILLS || 'true') !== 'false';
+const AUTO_SYNC_SKILLS = process.env.CLOUDMCP_AUTO_SYNC_SKILLS === 'true';
 const AUTO_APPLY_BRAIN = (process.env.CLOUDMCP_AUTO_APPLY_BRAIN || 'true') !== 'false';
 const AUTO_REPORT_PROJECT_PROBE = (process.env.CLOUDMCP_AUTO_REPORT_PROJECT_PROBE || 'true') === 'true';
 const AUTO_GENERATE_CONTEXT_PACK = (process.env.CLOUDMCP_AUTO_GENERATE_CONTEXT_PACK || 'true') === 'true';
@@ -148,7 +148,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
 });
 
 // 工具调用处理器
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
+server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
   const { name, arguments: args } = request.params;
 
   if (!name) {
@@ -165,7 +165,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
   try {
     await refreshProjectScope();
-    const result = await router.executeTool(name, args || {});
+    const result = await router.executeTool(name, args || {}, { signal: extra.signal });
     
     // 格式化响应
     if (typeof result === 'string') {
@@ -310,7 +310,7 @@ async function main() {
       console.error(`Connector bridge auto probe: ${AUTO_REPORT_PROJECT_PROBE ? 'enabled' : 'disabled'}`);
       const skillSync = bridgeStatus.state?.lastSkillSync;
       if (skillSync) {
-        console.error(`Global Skill sync: ${skillSync.success ? `${skillSync.synchronized?.length || 0} synchronized` : `failed (${skillSync.error})`}`);
+        console.error(`Global Skill sync: ${skillSync.status === 'running' ? 'running in background' : skillSync.success ? `${skillSync.synchronized?.length || 0} synchronized` : `failed (${skillSync.error})`}`);
       }
     } else {
       console.error('Connector bridge profile: not configured');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cloudflare-mcp-smart-proxy",
-  "version": "1.5.19",
+  "version": "1.5.23",
   "description": "Smart proxy for Cloudflare MCP - routes tools to cloud or local execution",
   "repository": {
     "type": "git",
@@ -10,6 +10,12 @@
   "type": "module",
   "packageManager": "pnpm@10.33.0",
   "main": "index.js",
+  "files": [
+    "README.md",
+    "index.js",
+    "connector-cli.js",
+    "src"
+  ],
   "bin": {
     "cloudflare-mcp-smart-proxy": "./index.js",
     "cloudflare-mcp-proxy": "./index.js",
@@ -36,7 +42,7 @@
       "@hono/node-server": "2.0.12",
       "ajv": "8.20.0",
       "body-parser": "2.3.0",
-      "fast-uri": "3.1.5",
+      "fast-uri": "3.1.6",
       "hono": "4.12.34",
       "ip-address": "10.4.0",
       "path-to-regexp": "8.4.0",

package/src/cloud-client.js

@@ -19,14 +19,15 @@ export class CloudClient {
     if (query && typeof query === 'object') {
       Object.entries(query).forEach(([key, value]) => {
         if (value !== undefined && value !== null && value !== '') {
-          url.searchParams.set(key, String(value));
+          if (Array.isArray(value)) value.forEach(entry => url.searchParams.append(key, String(entry)));
+          else url.searchParams.set(key, String(value));
         }
       });
     }
     return url.toString();
   }
 
-  async request(path, { method = 'GET', body, query, idempotencyKey } = {}) {
+  async request(path, { method = 'GET', body, query, idempotencyKey, workspaceId } = {}) {
     const serializedBody = body == null ? '' : JSON.stringify(body);
     const requestUrl = new URL(this.buildUrl(path, query));
     const signedHeaders = this.deviceIdentity
@@ -44,6 +45,7 @@ export class CloudClient {
         'Content-Type': 'application/json',
         'X-CloudMCP-Connector-Contract-Version': CONNECTOR_CONTRACT_VERSION,
         ...this.getScopeHeaders(),
+        ...(workspaceId ? { 'X-CloudMCP-Workspace-ID': workspaceId } : {}),
         ...signedHeaders,
         ...(idempotencyKey ? { 'X-Idempotency-Key': idempotencyKey } : {})
       },
@@ -75,6 +77,15 @@ export class CloudClient {
     });
   }
 
+  async discoverTools({ query = '', toolNames = [], limit = 10, offset = 0, resourceOffset = 0, resourceSelections = [] } = {}, workspaceId) {
+    const response = await this.request('/mcp/tools', { workspaceId, query: {
+      discovery: true, query, toolName: toolNames, limit, offset, resourceOffset,
+      ...(resourceSelections.length ? { resourceSelections: JSON.stringify(resourceSelections) } : {})
+    } });
+    if (!response?.discovery) throw new Error('CloudMCP tool discovery is unavailable; update the CloudMCP service');
+    return response.discovery;
+  }
+
   async resolveWorkspace({ projectIdentity }) {
     return this.request('/connectors/workspace-resolution', {
       method: 'POST',
@@ -143,4 +154,32 @@ export class CloudClient {
   async getCurrentDevice() {
     return this.request('/connectors/device/current');
   }
+
+  async listProjectVariables({ workspaceId }) {
+    return this.request('/connectors/project-variables', { workspaceId });
+  }
+
+  async pullProjectVariables({ workspaceId, names, expectedRevisions, expectedSetRevision } = {}) {
+    return this.request('/connectors/project-variables/pull', {
+      method: 'POST',
+      workspaceId,
+      body: { workspaceId, names, expectedRevisions, expectedSetRevision }
+    });
+  }
+
+  async putProjectVariables({ workspaceId, variables, expectedSetRevision }) {
+    return this.request('/connectors/project-variables', {
+      method: 'PUT',
+      workspaceId,
+      body: { workspaceId, variables, expectedSetRevision }
+    });
+  }
+
+  async deleteProjectVariables({ workspaceId, variables, expectedSetRevision }) {
+    return this.request('/connectors/project-variables', {
+      method: 'DELETE',
+      workspaceId,
+      body: { workspaceId, variables, expectedSetRevision }
+    });
+  }
 }

package/src/connector-bridge.js

@@ -6,6 +6,7 @@ import { discoverProjectProbe } from './project-probe-discovery.js';
 import { detectIde, applyBrainSnapshot } from './ide-configurator.js';
 import { discoverProjectIdentity } from './project-identity.js';
 import { syncGlobalSkills } from './skill-sync.js';
+import { ProjectEnvSync } from './project-env-sync.js';
 
 function normalizeString(value, fallback = '') {
   const normalized = typeof value === 'string' ? value.trim() : '';
@@ -61,12 +62,49 @@ export class ConnectorBridge {
       lastError: null
     };
     this.cloudToolCaller = null;
+    this.skillSyncPromise = null;
+    this.projectEnvSync = null;
   }
 
   setCloudToolCaller(caller) {
     this.cloudToolCaller = typeof caller === 'function' ? caller : null;
   }
 
+  getProjectEnvSync() {
+    if (!this.projectEnvSync
+      || this.projectEnvSync.workspaceRoot !== this.workspaceRoot
+      || this.projectEnvSync.workspaceId !== this.workspaceId) {
+      this.projectEnvSync = new ProjectEnvSync({
+        workspaceRoot: this.workspaceRoot,
+        workspaceId: this.workspaceId,
+        cloudClient: this.cloudClient
+      });
+    }
+    return this.projectEnvSync;
+  }
+
+  async getProjectEnvStatus(params = {}) {
+    return this.getProjectEnvSync().getStatus(params);
+  }
+
+  async planProjectEnvSync(params = {}) {
+    return this.getProjectEnvSync().planSync(params);
+  }
+
+  async planProjectEnvDelete(params = {}) {
+    return this.getProjectEnvSync().planDelete(params);
+  }
+
+  async applyProjectEnvPlan(params = {}) {
+    return this.getProjectEnvSync().apply(params);
+  }
+
+  async discoverTools(params = {}) {
+    const workspaceId = this.workspaceId || this.state.workspaceResolution?.globalWorkspaceIds?.find(id => id === 'workspace.global');
+    if (!workspaceId) throw new Error('Resolve the connector workspace before discovering tools');
+    return this.cloudClient.discoverTools(params, workspaceId);
+  }
+
   isConfigured() {
     return Boolean(this.clientProfileId);
   }
@@ -119,7 +157,7 @@ export class ConnectorBridge {
   async initialize({
     autoSyncProfile = true,
     autoApplyBrain = true,
-    autoSyncSkills = true,
+    autoSyncSkills = false,
     autoReportProjectProbe = false,
     autoGenerateContextPack = false
   } = {}) {
@@ -128,15 +166,9 @@ export class ConnectorBridge {
     }
 
     if (autoSyncSkills) {
-      try {
-        await this.syncSkills();
-      } catch (error) {
-        this.state.lastSkillSync = {
-          success: false,
-          error: error.message,
-          synchronized_at: Date.now()
-        };
-      }
+      // Explicit startup synchronization runs independently of MCP readiness.
+      // syncSkills records failures for connector_bridge_status and manual retry.
+      void this.syncSkills().catch(() => {});
     }
     const workspaceResolution = await this.resolveCurrentWorkspace();
     if (!workspaceResolution.workspaceId) return this.getBridgeStatus();
@@ -257,15 +289,23 @@ export class ConnectorBridge {
   }
 
   async syncSkills(options = {}) {
-    if (typeof this.cloudToolCaller !== 'function') {
-      throw new Error('Cloud Skill synchronization is not configured');
-    }
-    const result = await syncGlobalSkills({
+    if (this.skillSyncPromise) return this.skillSyncPromise;
+    const startedAt = Date.now();
+    this.state.lastSkillSync = { status: 'running', started_at: startedAt };
+    this.skillSyncPromise = syncGlobalSkills({
       callCloudTool: this.cloudToolCaller,
       ...options
+    }).then(result => {
+      this.state.lastSkillSync = { ...result, status: 'succeeded', started_at: startedAt };
+      return result;
+    }).catch(error => {
+      this.state.lastSkillSync = { status: 'failed', success: false, error: error.message,
+        started_at: startedAt, synchronized_at: Date.now() };
+      throw error;
+    }).finally(() => {
+      this.skillSyncPromise = null;
     });
-    this.state.lastSkillSync = result;
-    return result;
+    return this.skillSyncPromise;
   }
 
   async reportStatus({

package/src/local-tools.js

@@ -66,6 +66,10 @@ export class LocalToolExecutor {
         if (!this.connectorBridge) throw new Error('Connector bridge is not configured');
         return this.connectorBridge.getBridgeStatus();
 
+      case 'connector_discover_tools':
+        if (!this.connectorBridge) throw new Error('Connector bridge is not configured');
+        return await this.connectorBridge.discoverTools(params || {});
+
       case 'connector_sync_profile':
         if (!this.connectorBridge) throw new Error('Connector bridge is not configured');
         return await this.connectorBridge.syncProfile();
@@ -74,6 +78,22 @@ export class LocalToolExecutor {
         if (!this.connectorBridge) throw new Error('Connector bridge is not configured');
         return await this.connectorBridge.syncSkills(params || {});
 
+      case 'connector_get_project_env_status':
+        if (!this.connectorBridge) throw new Error('Connector bridge is not configured');
+        return await this.connectorBridge.getProjectEnvStatus(params || {});
+
+      case 'connector_plan_project_env_sync':
+        if (!this.connectorBridge) throw new Error('Connector bridge is not configured');
+        return await this.connectorBridge.planProjectEnvSync(params || {});
+
+      case 'connector_plan_project_env_delete':
+        if (!this.connectorBridge) throw new Error('Connector bridge is not configured');
+        return await this.connectorBridge.planProjectEnvDelete(params || {});
+
+      case 'connector_apply_project_env_plan':
+        if (!this.connectorBridge) throw new Error('Connector bridge is not configured');
+        return await this.connectorBridge.applyProjectEnvPlan(params || {});
+
       case 'connector_report_status':
         if (!this.connectorBridge) throw new Error('Connector bridge is not configured');
         return await this.connectorBridge.reportStatus(params || {});
@@ -450,6 +470,25 @@ export class LocalToolExecutor {
           required: ['file_path']
         }
       },
+      {
+        name: 'connector_discover_tools',
+        description: 'Start here to find CloudMCP tools and prepare exact authorization requests without reading source code. Search with query; pass chosen toolNames to read schemas, current grants, required resources and ready-to-submit request_project_tool_authorization arguments. Read-only and available before business-tool approval. Existing grants are reused; approval stays in the existing authorization flow.',
+        inputSchema: {
+          type: 'object', additionalProperties: false,
+          properties: {
+            query: { type: 'string', description: 'Capability keywords, e.g. trends, deploy, database or email' },
+            toolNames: { type: 'array', maxItems: 30, items: { type: 'string' }, description: 'Exact names selected from search results; prepares their authorization requests together' },
+            limit: { type: 'integer', minimum: 1, maximum: 30 },
+            offset: { type: 'integer', minimum: 0 },
+            resourceOffset: { type: 'integer', minimum: 0, description: 'Continue resource choices using nextResourceOffset from a prepared request' },
+            resourceSelections: { type: 'array', maxItems: 30, items: {
+              type: 'object', additionalProperties: false,
+              properties: { backendId: { type: 'string' }, resourceType: { type: 'string' }, allowedResourceIds: { type: 'array', minItems: 1, items: { type: 'string' } }, defaultResourceId: { type: 'string' } },
+              required: ['backendId', 'resourceType', 'allowedResourceIds']
+            } }
+          }
+        }
+      },
       {
         name: 'connector_bridge_status',
         description: 'Get current connector bridge state, sync metadata, and workspace binding status',
@@ -474,6 +513,51 @@ export class LocalToolExecutor {
           properties: {}
         }
       },
+      {
+        name: 'connector_get_project_env_status',
+        description: 'List project .env and CloudMCP workspace variable names and synchronization status without returning variable values.',
+        inputSchema: {
+          type: 'object', additionalProperties: false,
+          properties: {
+            filePath: { type: 'string', description: 'Workspace-relative .env or .env.* path; defaults to .env' }
+          }
+        }
+      },
+      {
+        name: 'connector_plan_project_env_sync',
+        description: 'Preview an exact push or pull between a local project .env file and governed CloudMCP workspace variables. Returns names and changes only.',
+        inputSchema: {
+          type: 'object', additionalProperties: false,
+          properties: {
+            direction: { type: 'string', enum: ['push', 'pull'] },
+            filePath: { type: 'string' },
+            names: { type: 'array', minItems: 1, items: { type: 'string' } }
+          },
+          required: ['direction']
+        }
+      },
+      {
+        name: 'connector_plan_project_env_delete',
+        description: 'Preview deletion of exact variable names from CloudMCP or the local project env file. No deletion occurs until the returned plan is applied.',
+        inputSchema: {
+          type: 'object', additionalProperties: false,
+          properties: {
+            target: { type: 'string', enum: ['cloud', 'local'] },
+            filePath: { type: 'string' },
+            names: { type: 'array', minItems: 1, items: { type: 'string' } }
+          },
+          required: ['target', 'names']
+        }
+      },
+      {
+        name: 'connector_apply_project_env_plan',
+        description: 'Apply one previously previewed project environment plan. Rejects expired plans and stale local or cloud revisions.',
+        inputSchema: {
+          type: 'object', additionalProperties: false,
+          properties: { planId: { type: 'string' } },
+          required: ['planId']
+        }
+      },
       {
         name: 'connector_report_status',
         description: 'Report local connector apply status back to CloudMCP',

package/src/project-env-sync.js

@@ -0,0 +1,489 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { link, lstat, open, realpath, rename, unlink } from 'node:fs/promises';
+import path from 'node:path';
+
+const VARIABLE_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const PLAN_TTL_MS = 10 * 60 * 1000;
+
+function assertVariableName(name) {
+  const normalized = String(name || '').trim();
+  if (!VARIABLE_NAME.test(normalized)) throw new Error(`Invalid environment variable name: ${normalized || '(empty)'}`);
+  return normalized;
+}
+
+function resolveEnvPath(workspaceRoot, filePath = '.env') {
+  const relative = String(filePath || '.env').trim() || '.env';
+  const basename = path.basename(relative);
+  if (!(basename === '.env' || basename.startsWith('.env.'))) {
+    throw new Error('filePath must name a .env or .env.* file');
+  }
+  const root = path.resolve(workspaceRoot);
+  const resolved = path.resolve(root, relative);
+  if (resolved !== root && !resolved.startsWith(`${root}${path.sep}`)) {
+    throw new Error('Environment file must stay inside the connector workspace');
+  }
+  return { relative, resolved };
+}
+
+function parseEnv(text = '') {
+  const entries = new Map();
+  for (const line of String(text).split(/\r?\n/)) {
+    const match = line.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/);
+    if (!match) continue;
+    let value = match[2];
+    if (value.startsWith('"') && value.endsWith('"')) {
+      try { value = JSON.parse(value); } catch {}
+    } else if (value.startsWith("'") && value.endsWith("'")) {
+      value = value.slice(1, -1);
+    } else {
+      value = value.replace(/\s+#.*$/, '').trim();
+    }
+    entries.set(match[1], value);
+  }
+  return entries;
+}
+
+function serializeValue(value) {
+  const text = String(value ?? '');
+  return /^[A-Za-z0-9_./:@%+=,-]*$/.test(text) ? text : JSON.stringify(text);
+}
+
+function updateEnv(text, updates = new Map(), deletes = new Set()) {
+  const seen = new Set();
+  const lines = String(text).split(/\r?\n/).filter((line, index, all) => !(index === all.length - 1 && line === ''));
+  const output = [];
+  for (const line of lines) {
+    const match = line.match(/^(\s*(?:export\s+)?)([A-Za-z_][A-Za-z0-9_]*)(\s*=).*$/);
+    if (!match) {
+      output.push(line);
+      continue;
+    }
+    const name = match[2];
+    if (deletes.has(name)) continue;
+    if (updates.has(name)) {
+      output.push(`${match[1]}${name}${match[3]}${serializeValue(updates.get(name))}`);
+      seen.add(name);
+    } else {
+      output.push(line);
+    }
+  }
+  for (const [name, value] of updates) {
+    if (!seen.has(name)) output.push(`${name}=${serializeValue(value)}`);
+  }
+  return `${output.join('\n')}\n`;
+}
+
+function digest(text) {
+  return createHash('sha256').update(String(text)).digest('hex');
+}
+
+function transactionPaths(safePath, parentReal) {
+  const id = createHash('sha256').update(safePath).digest('hex').slice(0, 16);
+  return {
+    lockPath: path.join(parentReal, `.cloudmcp-env-${id}.lock`),
+    backupPath: path.join(parentReal, `.cloudmcp-env-${id}.previous`),
+    tempPath: path.join(parentReal, `.cloudmcp-env-${id}.next`)
+  };
+}
+
+function isProcessAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code !== 'ESRCH';
+  }
+}
+
+async function writeTransaction(handle, transaction) {
+  const payload = `${JSON.stringify(transaction)}\n`;
+  await handle.truncate(0);
+  await handle.write(payload, 0, 'utf8');
+  await handle.sync();
+}
+
+async function readRegularFileNoFollow(filePath, { allowMissing = false } = {}) {
+  let handle = null;
+  try {
+    handle = await open(filePath, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const before = await handle.stat();
+    if (!before.isFile()) throw new Error('Environment file must be a regular file and cannot be a symbolic link');
+    const text = await handle.readFile('utf8');
+    const after = await handle.stat();
+    if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size
+      || before.mtimeMs !== after.mtimeMs) {
+      throw new Error('Environment file changed while it was being read');
+    }
+    return { exists: true, text, stat: after };
+  } catch (error) {
+    if (allowMissing && error?.code === 'ENOENT') return { exists: false, text: '', stat: null };
+    if (error?.code === 'ELOOP') {
+      throw new Error('Environment file must be a regular file and cannot be a symbolic link');
+    }
+    throw error;
+  } finally {
+    if (handle) await handle.close().catch(() => {});
+  }
+}
+
+async function recoverInterruptedEnvWrite(safePath, parentReal) {
+  const paths = transactionPaths(safePath, parentReal);
+  const lock = await readRegularFileNoFollow(paths.lockPath, { allowMissing: true });
+  if (!lock.exists) return;
+  let transaction;
+  try {
+    transaction = JSON.parse(lock.text);
+  } catch {
+    transaction = {};
+  }
+  const startedAt = Number(transaction.startedAt || 0);
+  const fresh = startedAt > 0 && Date.now() - startedAt < PLAN_TTL_MS;
+  if (fresh && isProcessAlive(Number(transaction.pid))) {
+    throw new Error('Another project environment write is already in progress');
+  }
+  if (transaction.safePath && transaction.safePath !== safePath) {
+    throw new Error('Project environment recovery record does not match the target file');
+  }
+
+  const targetStat = await lstat(safePath).catch((error) => {
+    if (error?.code === 'ENOENT') return null;
+    throw error;
+  });
+  const backupStat = await lstat(paths.backupPath).catch((error) => {
+    if (error?.code === 'ENOENT') return null;
+    throw error;
+  });
+  if (backupStat?.isSymbolicLink() || (backupStat && !backupStat.isFile())) {
+    throw new Error('Project environment recovery backup is not a regular file');
+  }
+  if (backupStat && (!targetStat || targetStat.isSymbolicLink() || !targetStat.isFile())) {
+    if (targetStat) await unlink(safePath);
+    await rename(paths.backupPath, safePath);
+  } else if (backupStat) {
+    await unlink(paths.backupPath);
+  }
+  await unlink(paths.tempPath).catch(() => {});
+  await unlink(paths.lockPath);
+}
+
+async function readEnv(workspaceRoot, filePath) {
+  const target = resolveEnvPath(workspaceRoot, filePath);
+  const rootReal = await realpath(path.resolve(workspaceRoot));
+  const parentReal = await realpath(path.dirname(target.resolved));
+  const targetReal = path.join(parentReal, path.basename(target.resolved));
+  if (targetReal !== rootReal && !targetReal.startsWith(`${rootReal}${path.sep}`)) {
+    throw new Error('Environment file symlink must stay inside the connector workspace');
+  }
+  await recoverInterruptedEnvWrite(targetReal, parentReal);
+  const current = await readRegularFileNoFollow(targetReal, { allowMissing: true });
+  return {
+    ...target,
+    safePath: targetReal,
+    parentReal,
+    exists: current.exists,
+    stat: current.stat,
+    text: current.text,
+    values: parseEnv(current.text),
+    digest: digest(current.text)
+  };
+}
+
+async function atomicWriteEnv(target, text) {
+  const currentParent = await realpath(path.dirname(target.safePath));
+  if (currentParent !== target.parentReal) throw new Error('Environment file parent changed after planning');
+  const { tempPath, backupPath, lockPath } = transactionPaths(target.safePath, target.parentReal);
+  let handle = null;
+  let lockHandle = null;
+  let ownsLock = false;
+  let backupMoved = false;
+  let installed = false;
+  let tempStat = null;
+  try {
+    lockHandle = await open(lockPath, 'wx', 0o600).catch((error) => {
+      if (error?.code === 'EEXIST') throw new Error('Another project environment write is already in progress');
+      throw error;
+    });
+    ownsLock = true;
+    const staleArtifact = await Promise.all([backupPath, tempPath].map((filePath) => (
+      lstat(filePath).catch((error) => {
+        if (error?.code === 'ENOENT') return null;
+        throw error;
+      })
+    )));
+    if (staleArtifact.some(Boolean)) {
+      throw new Error('Project environment recovery artifacts require inspection before writing');
+    }
+    await writeTransaction(lockHandle, {
+      version: 1,
+      pid: process.pid,
+      startedAt: Date.now(),
+      safePath: target.safePath,
+      expectedDigest: target.digest,
+      replacementDigest: digest(text)
+    });
+    handle = await open(tempPath, 'wx', 0o600);
+    await handle.writeFile(text, 'utf8');
+    await handle.sync();
+    tempStat = await handle.stat();
+    await handle.close();
+    handle = null;
+
+    const verifiedParent = await realpath(path.dirname(target.safePath));
+    if (verifiedParent !== target.parentReal) throw new Error('Environment file parent changed during write');
+    const current = await readRegularFileNoFollow(target.safePath, { allowMissing: true });
+    if (current.exists !== target.exists || digest(current.text) !== target.digest) {
+      throw new Error('Local environment file changed during write; create a new plan');
+    }
+    const pathStat = await lstat(target.safePath).catch((error) => {
+      if (error?.code === 'ENOENT') return null;
+      throw error;
+    });
+    if ((current.stat && (!pathStat || pathStat.isSymbolicLink()
+      || current.stat.dev !== pathStat.dev || current.stat.ino !== pathStat.ino))
+      || (!current.stat && pathStat)) {
+      throw new Error('Environment file target changed during write');
+    }
+    if (target.exists) {
+      await rename(target.safePath, backupPath);
+      backupMoved = true;
+      await writeTransaction(lockHandle, {
+        version: 1, pid: process.pid, startedAt: Date.now(), safePath: target.safePath, stage: 'displaced'
+      });
+      const displaced = await readRegularFileNoFollow(backupPath);
+      if (displaced.stat.dev !== current.stat.dev || displaced.stat.ino !== current.stat.ino
+        || digest(displaced.text) !== target.digest) {
+        throw new Error('Local environment file changed during replacement; create a new plan');
+      }
+    } else if (await lstat(target.safePath).catch((error) => {
+      if (error?.code === 'ENOENT') return null;
+      throw error;
+    })) {
+      throw new Error('Environment file target appeared during write');
+    }
+
+    await link(tempPath, target.safePath).catch((error) => {
+      if (error?.code === 'EEXIST') throw new Error('Environment file target changed during replacement');
+      throw error;
+    });
+    installed = true;
+    await writeTransaction(lockHandle, {
+      version: 1, pid: process.pid, startedAt: Date.now(), safePath: target.safePath, stage: 'installed'
+    });
+
+    if (backupMoved) {
+      const displacedAfterInstall = await readRegularFileNoFollow(backupPath);
+      if (digest(displacedAfterInstall.text) !== target.digest) {
+        const installedStat = await lstat(target.safePath).catch(() => null);
+        if (installedStat && installedStat.dev === tempStat.dev && installedStat.ino === tempStat.ino) {
+          await unlink(target.safePath);
+          installed = false;
+          await link(backupPath, target.safePath);
+        }
+        throw new Error('Local environment file changed during replacement; the concurrent edit was preserved');
+      }
+      await unlink(backupPath);
+      backupMoved = false;
+    }
+  } finally {
+    if (handle) await handle.close().catch(() => {});
+    if (lockHandle) await lockHandle.close().catch(() => {});
+    await unlink(tempPath).catch(() => {});
+    if (backupMoved && !installed) {
+      await link(backupPath, target.safePath).catch(() => {});
+    }
+    if (backupMoved && (installed || await lstat(target.safePath).catch(() => null))) {
+      await unlink(backupPath).catch(() => {});
+    }
+    if (ownsLock) await unlink(lockPath).catch(() => {});
+  }
+}
+
+function normalizeNames(names, fallback = []) {
+  if (names !== undefined && !Array.isArray(names)) {
+    throw new Error('names must be an array of exact variable names when provided');
+  }
+  if (Array.isArray(names) && names.length === 0) {
+    throw new Error('names must contain at least one exact variable name when provided');
+  }
+  const source = Array.isArray(names) ? names : fallback;
+  return Array.from(new Set(source.map(assertVariableName))).sort();
+}
+
+function publicPlan(plan) {
+  return {
+    objectType: 'project_env_plan',
+    planId: plan.planId,
+    operation: plan.operation,
+    direction: plan.direction || null,
+    target: plan.target || null,
+    filePath: plan.filePath,
+    workspaceId: plan.workspaceId,
+    changes: plan.changes,
+    expiresAt: plan.expiresAt
+  };
+}
+
+export class ProjectEnvSync {
+  constructor({ workspaceRoot, workspaceId, cloudClient }) {
+    this.workspaceRoot = workspaceRoot;
+    this.workspaceId = workspaceId;
+    this.cloudClient = cloudClient;
+    this.plans = new Map();
+  }
+
+  assertReady() {
+    if (!this.workspaceId || this.workspaceId === 'workspace.global') {
+      throw new Error('Resolve an exact project workspace before syncing environment variables');
+    }
+    if (!this.cloudClient) throw new Error('Cloud client is required for project environment synchronization');
+  }
+
+  async snapshot(filePath = '.env') {
+    this.assertReady();
+    const [local, cloudResponse] = await Promise.all([
+      readEnv(this.workspaceRoot, filePath),
+      this.cloudClient.listProjectVariables({ workspaceId: this.workspaceId })
+    ]);
+    const cloud = Array.isArray(cloudResponse?.variables) ? cloudResponse.variables : [];
+    return {
+      local,
+      cloud,
+      cloudRevision: Number(cloudResponse?.revision || 0),
+      cloudByName: new Map(cloud.map((entry) => [entry.name, entry]))
+    };
+  }
+
+  async getStatus({ filePath = '.env' } = {}) {
+    const { local, cloud } = await this.snapshot(filePath);
+    return {
+      objectType: 'project_env_status',
+      workspaceId: this.workspaceId,
+      filePath: local.relative,
+      local: { exists: local.exists, names: Array.from(local.values.keys()).sort() },
+      cloud: { names: cloud.map((entry) => entry.name).sort() }
+    };
+  }
+
+  storePlan(plan) {
+    const complete = {
+      ...plan,
+      planId: randomUUID(),
+      workspaceId: this.workspaceId,
+      expiresAt: new Date(Date.now() + PLAN_TTL_MS).toISOString()
+    };
+    this.plans.set(complete.planId, complete);
+    return publicPlan(complete);
+  }
+
+  async planSync({ direction, filePath = '.env', names } = {}) {
+    if (!['push', 'pull'].includes(direction)) throw new Error('direction must be push or pull');
+    const { local, cloud, cloudRevision, cloudByName } = await this.snapshot(filePath);
+    const available = direction === 'push' ? Array.from(local.values.keys()) : cloud.map((entry) => entry.name);
+    const selected = normalizeNames(names, available);
+    const pulled = selected.length
+      ? await this.cloudClient.pullProjectVariables({
+        workspaceId: this.workspaceId, names: selected, expectedSetRevision: cloudRevision
+      })
+      : { variables: [] };
+    const cloudValues = new Map((pulled.variables || []).map((entry) => [entry.name, entry.value]));
+    const changes = { create: [], update: [], unchanged: [], missing: [] };
+    for (const name of selected) {
+      const localHas = local.values.has(name);
+      const cloudHas = cloudByName.has(name) && cloudValues.has(name);
+      if (direction === 'push' && !localHas) changes.missing.push(name);
+      else if (direction === 'pull' && !cloudHas) changes.missing.push(name);
+      else if (direction === 'push' && !cloudHas) changes.create.push(name);
+      else if (direction === 'pull' && !localHas) changes.create.push(name);
+      else if (local.values.get(name) === cloudValues.get(name)) changes.unchanged.push(name);
+      else changes.update.push(name);
+    }
+    return this.storePlan({
+      operation: 'sync', direction, filePath: local.relative, names: selected, changes,
+      localDigest: local.digest,
+      cloudRevision,
+      revisions: Object.fromEntries(selected.map((name) => [name, cloudByName.get(name)?.updatedAt ?? null]))
+    });
+  }
+
+  async planDelete({ target, filePath = '.env', names } = {}) {
+    if (!['cloud', 'local'].includes(target)) throw new Error('target must be cloud or local');
+    if (!Array.isArray(names) || names.length === 0) throw new Error('names must contain at least one exact variable name');
+    const { local, cloudRevision, cloudByName } = await this.snapshot(filePath);
+    const selected = normalizeNames(names);
+    const localDeletes = target === 'local' ? selected.filter((name) => local.values.has(name)) : [];
+    const cloudDeletes = target === 'cloud' ? selected.filter((name) => cloudByName.has(name)) : [];
+    const deletable = selected.filter((name) => localDeletes.includes(name) || cloudDeletes.includes(name));
+    return this.storePlan({
+      operation: 'delete', target, filePath: local.relative, names: selected,
+      changes: { delete: deletable, missing: selected.filter((name) => !deletable.includes(name)) },
+      localDeletes,
+      cloudDeletes,
+      localDigest: local.digest,
+      cloudRevision,
+      revisions: Object.fromEntries(selected.map((name) => [name, cloudByName.get(name)?.updatedAt ?? null]))
+    });
+  }
+
+  async apply({ planId } = {}) {
+    const plan = this.plans.get(String(planId || ''));
+    if (!plan) throw new Error('Project environment plan was not found or was already applied');
+    if (Date.parse(plan.expiresAt) <= Date.now()) {
+      this.plans.delete(plan.planId);
+      throw new Error('Project environment plan expired; create a new plan');
+    }
+    const local = await readEnv(this.workspaceRoot, plan.filePath);
+    if (local.digest !== plan.localDigest) throw new Error('Local environment file changed after planning; create a new plan');
+    const actionable = [...(plan.changes.create || []), ...(plan.changes.update || []), ...(plan.changes.delete || [])];
+    if (plan.operation === 'sync' && actionable.length === 0) {
+      const current = await this.cloudClient.listProjectVariables({ workspaceId: this.workspaceId });
+      if (Number(current?.revision || 0) !== plan.cloudRevision) {
+        throw new Error('Cloud variables changed after planning; create a new plan');
+      }
+    }
+    if (plan.operation === 'delete' && plan.target === 'cloud' && plan.cloudDeletes.length === 0) {
+      const current = await this.cloudClient.listProjectVariables({ workspaceId: this.workspaceId });
+      if (Number(current?.revision || 0) !== plan.cloudRevision) {
+        throw new Error('Cloud variables changed after planning; create a new plan');
+      }
+    }
+    if (plan.operation === 'sync' && plan.direction === 'push' && actionable.length) {
+      await this.cloudClient.putProjectVariables({
+        workspaceId: this.workspaceId,
+        expectedSetRevision: plan.cloudRevision,
+        variables: actionable.map((name) => ({
+          name, value: local.values.get(name), expectedUpdatedAt: plan.revisions[name]
+        }))
+      });
+    } else if (plan.operation === 'sync' && plan.direction === 'pull' && actionable.length) {
+      const response = await this.cloudClient.pullProjectVariables({
+        workspaceId: this.workspaceId,
+        names: actionable,
+        expectedSetRevision: plan.cloudRevision,
+        expectedRevisions: Object.fromEntries(actionable.map((name) => [name, plan.revisions[name]]))
+      });
+      const updates = new Map((response.variables || []).map((entry) => [entry.name, entry.value]));
+      if (updates.size !== actionable.length) throw new Error('Cloud variables changed or disappeared after planning; create a new plan');
+      await atomicWriteEnv(local, updateEnv(local.text, updates));
+    } else if (plan.operation === 'delete') {
+      if (plan.cloudDeletes.length) {
+        await this.cloudClient.deleteProjectVariables({
+          workspaceId: this.workspaceId,
+          expectedSetRevision: plan.cloudRevision,
+          variables: plan.cloudDeletes
+            .map((name) => ({ name, expectedUpdatedAt: plan.revisions[name] }))
+        });
+      }
+      if (plan.localDeletes.length) {
+        await atomicWriteEnv(local, updateEnv(local.text, new Map(), new Set(plan.localDeletes)));
+      }
+    }
+    this.plans.delete(plan.planId);
+    return {
+      objectType: 'project_env_apply_result', success: true, planId: plan.planId,
+      operation: plan.operation, direction: plan.direction || null, target: plan.target || null,
+      applied: actionable, unchanged: plan.changes.unchanged || [], missing: plan.changes.missing || []
+    };
+  }
+}

package/src/router.js

@@ -65,8 +65,13 @@ export class SmartRouter {
         'execute_command',
         'execute_shell_command',
         'connector_bridge_status',
+        'connector_discover_tools',
         'connector_sync_profile',
         'connector_sync_skills',
+        'connector_get_project_env_status',
+        'connector_plan_project_env_sync',
+        'connector_plan_project_env_delete',
+        'connector_apply_project_env_plan',
         'connector_report_status',
         'connector_discover_project_probe',
         'connector_report_project_probe',
@@ -139,7 +144,7 @@ export class SmartRouter {
   /**
    * 执行工具调用
    */
-  async executeTool(toolName, params) {
+  async executeTool(toolName, params, { signal = null } = {}) {
     const route = this.routeTool(toolName);
 
     if (route === 'local') {
@@ -151,7 +156,7 @@ export class SmartRouter {
             projectIdentity: this.localTools?.connectorBridge?.state?.projectIdentity
           }
         : params;
-      return await this.callCloudTool(toolName, recoveryParams);
+      return await this.callCloudTool(toolName, recoveryParams, { signal });
     }
   }
 
@@ -179,7 +184,7 @@ export class SmartRouter {
   /**
    * 调用云端工具
    */
-  async callCloudTool(toolName, params, { workspaceId = null } = {}) {
+  async callCloudTool(toolName, params, { workspaceId = null, signal = null } = {}) {
     // 对于 skill_* 工具，自动注入项目根路径信息
     if (toolName.startsWith('skill_')) {
       // 如果参数中没有 project_root 且没有 paths，自动添加 project_root
@@ -205,9 +210,10 @@ export class SmartRouter {
     }
     
     try {
+      const requestId = Date.now();
       const body = JSON.stringify({
         jsonrpc: '2.0',
-        id: Date.now(),
+        id: requestId,
         method: 'tools/call',
         params: {
           name: toolName,
@@ -222,11 +228,13 @@ export class SmartRouter {
         headers: {
           'Authorization': `Bearer ${this.cloudApiKey}`,
           'Content-Type': 'application/json',
+          'X-Request-ID': String(requestId),
           ...this.getScopeHeaders(),
           ...(workspaceId ? { 'X-CloudMCP-Workspace-ID': workspaceId } : {}),
           ...signedHeaders
         },
-        body
+        body,
+        signal
       });
 
       if (!response.ok) {