ec-web 0.0.20 → 0.0.21

package/dist/server.js

@@ -4,7 +4,7 @@
  * - HTTP: 静态资源 + 配对 API
  * - WebSocket: 订阅式实时推送（aid / msg / session）
  * - 鉴权: 6 位配对码（5 分钟有效）→ token（30 天，有访问自动续期），持久化到磁盘
- * - 安全: 绑定 0.0.0.0（支持远程访问），token 校验，只读
+ * - 安全: 绑定 0.0.0.0（支持远程访问），token 校验；远程连接可执行受控管理操作，不能修改 daemon 配置或读取 secret
  *
  * 与 evolcore 的唯一通信：启动时发 ping 检查 protocolVersion（soft 校验）。
  */
@@ -35,14 +35,23 @@ import { roleDefinitionsSource, handleRoleDefinitionsApi } from './sources/role-
 import { handleModelsApi } from './sources/models.js';
 import { detectBaseAgents } from './sources/baseagent-detector.js';
 import { readCodexSessionResult } from './sources/session-codex.js';
+import { handleBasicSettingsApi } from './sources/basic-settings.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const STATIC_DIR = path.join(__dirname, 'static');
 const TOKEN_TTL_MS = 30 * 24 * 60 * 60 * 1000; // 30天（滑动窗口：每次有效访问刷新 lastActive 自动续期）
 const PAIRING_TTL_MS = 5 * 60 * 1000; // 5min
 const DEFAULT_PORT = 42705;
 const PROTOCOL_VERSION = 1; // 与 evolcore ping response 对齐的软校验版本
-function daemonOwnerMenuAuth() {
-    return { localDirect: true, actorAid: null };
+function daemonOwnerMenuAuth(localDirect, actorAid) {
+    return {
+        localDirect,
+        actorAid: actorAid ?? null,
+        // Every request reaching this helper has already passed the ECWeb
+        // authentication gate (local-direct exemption or a valid bearer token).
+        // ECWeb is the daemon-owner management surface, so remote tokens receive
+        // the same persistent fullaccess approval capability as local requests.
+        canApprovePersistentFullAccess: true,
+    };
 }
 function daemonTriggerControlToken() {
     try {
@@ -52,6 +61,14 @@ function daemonTriggerControlToken() {
         return undefined;
     }
 }
+function matchesDaemonControlToken(value) {
+    const expected = daemonTriggerControlToken();
+    if (typeof value !== 'string' || !expected)
+        return false;
+    const provided = Buffer.from(value);
+    const target = Buffer.from(expected);
+    return provided.length === target.length && crypto.timingSafeEqual(provided, target);
+}
 const SOURCES = { agents: aidSource, msg: msgSource, session: sessionSource, cache: cacheSource, system: systemSource, triggers: triggersSource, monitor: monitorSource, logs: logsSource, gateway: gatewaySource, roles: relationRolesSource, roleDefinitions: roleDefinitionsSource };
 // ECWeb 自身版本：渲染 System 页时随快照下发（不走 daemon IPC，ECWeb 就是这个进程）。
 function readEcwebVersion() {
@@ -122,20 +139,31 @@ function pruneExpired(store, now) {
     store.tokens = store.tokens.filter(t => now - t.lastActive < TOKEN_TTL_MS);
     return store.tokens.length !== before;
 }
-function validateAndRenew(token, now) {
+function validAuthorizedBy(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const normalized = value.trim();
+    if (!normalized || normalized.length > 512 || /[\r\n]/.test(normalized))
+        return undefined;
+    return normalized;
+}
+function getValidTokenRecord(token, now) {
     if (!token)
-        return false;
+        return null;
     const store = loadTokens();
     const changed = pruneExpired(store, now);
     const rec = store.tokens.find(t => t.token === token);
     if (rec) {
         rec.lastActive = now;
         saveTokens(store);
-        return true;
+        return rec;
     }
     if (changed)
         saveTokens(store);
-    return false;
+    return null;
+}
+function validateAndRenew(token, now) {
+    return getValidTokenRecord(token, now) !== null;
 }
 // ── Static ──
 // 经 AUN Service Proxy 转发时，proxy-server 注入 x-forwarded-prefix 头，
@@ -225,6 +253,15 @@ function parseUrl(rawUrl) {
     }
     return { path: rawUrl.slice(0, qIdx), query };
 }
+function requestPath(rawUrl) {
+    try {
+        const pathname = new URL(rawUrl || '/', 'http://localhost').pathname;
+        return pathname.replace(/\/+$/, '') || '/';
+    }
+    catch {
+        return rawUrl.split('?')[0].replace(/\/+$/, '') || '/';
+    }
+}
 function handleStatsApi(req, res) {
     const { path: urlPath, query } = parseUrl(req.url || '');
     res.setHeader('Content-Type', 'application/json');
@@ -436,7 +473,7 @@ function genPairingCode() {
     return String(crypto.randomInt(0, 1000000)).padStart(6, '0');
 }
 // ── Pair handler ──
-function handlePair(req, res, pairingCode, pairingExpiry, log) {
+function handlePair(req, res, pairingCode, pairingExpiry, authorizedBy, log) {
     let body = '';
     req.on('data', (chunk) => { body += chunk; if (body.length > 4096)
         req.destroy(); });
@@ -461,10 +498,16 @@ function handlePair(req, res, pairingCode, pairingExpiry, log) {
         const token = crypto.randomBytes(32).toString('hex');
         const store = loadTokens();
         pruneExpired(store, now);
-        store.tokens.push({ token, createdAt: now, lastActive: now, label: ip });
+        store.tokens.push({
+            token,
+            createdAt: now,
+            lastActive: now,
+            label: ip,
+            ...(authorizedBy ? { authorizedBy } : {}),
+        });
         saveTokens(store);
         res.writeHead(200, { 'Content-Type': 'application/json' }).end(JSON.stringify({ ok: true, token }));
-        log(`✓ 配对成功 from ${ip}（token 缓存 30 天，有访问自动续期）`);
+        log(`✓ 配对成功 from ${ip}（token 缓存 30 天，有访问自动续期${authorizedBy ? `，批准者 ${authorizedBy}` : ''}）`);
     });
 }
 /**
@@ -485,8 +528,10 @@ function issueLocalDirectToken(req, log) {
     return token;
 }
 // ── WebSocket connection ──
-function handleConnection(ws, req, log) {
+function handleConnection(ws, req, log, tokenRecord) {
     const ip = clientIp(req);
+    const localDirect = isLocalDirect(req);
+    const actorAid = tokenRecord?.authorizedBy ?? null;
     let unsubscribe = null;
     let currentView = null;
     let subscriptionGeneration = 0;
@@ -510,7 +555,7 @@ function handleConnection(ws, req, log) {
             send({ type: 'error', message: `unknown view: ${view}` });
             return;
         }
-        const sourceParams = { ...params, __menuAuth: daemonOwnerMenuAuth() };
+        const sourceParams = { ...params, __menuAuth: daemonOwnerMenuAuth(localDirect, actorAid) };
         // System 视图：把 ECWeb 自身版本合并进快照（前端版本卡用）
         const decorate = (data) => (view === 'system' && data ? { ...data, ecwebVersion: ECWEB_VERSION } : data);
         let initialSnapshot;
@@ -589,7 +634,7 @@ function handleConnection(ws, req, log) {
             const timeoutMs = Number.isFinite(Number(msg.timeoutMs)) && Number(msg.timeoutMs) > 0
                 ? Math.min(Number(msg.timeoutMs), 120_000)
                 : 5000;
-            const menuAuth = daemonOwnerMenuAuth();
+            const menuAuth = daemonOwnerMenuAuth(localDirect, actorAid);
             const resp = await ipcQuery(p.socket, { type: 'menu.exec', payload: msg.payload, auth: { source: 'ecweb', ...menuAuth } }, timeoutMs);
             if (resp?.ok) {
                 send({ type: 'menu.response', requestId: msg.requestId, data: resp.response });
@@ -708,7 +753,11 @@ function bindPort(server, preferred, log) {
                     reject(err);
                 }
             });
-            server.listen(port, '0.0.0.0', () => resolve({ port, displaced: false }));
+            server.listen(port, '0.0.0.0', () => {
+                const address = server.address();
+                const boundPort = address && typeof address !== 'string' ? address.port : port;
+                resolve({ port: boundPort, displaced: false });
+            });
         };
         tryBind(preferred);
     });
@@ -724,15 +773,19 @@ export async function startWatchWebServer(opts = {}) {
     }
     let pairingCode = genPairingCode();
     let pairingExpiry = Date.now() + PAIRING_TTL_MS;
+    let pairingAuthorizedBy;
     function freshPairing() {
         if (Date.now() > pairingExpiry) {
             pairingCode = genPairingCode();
             pairingExpiry = Date.now() + PAIRING_TTL_MS;
+            pairingAuthorizedBy = undefined;
             log(`↺ 配对码已刷新：${pairingCode}（5 分钟有效）`);
         }
         return { code: pairingCode, expiresAt: pairingExpiry };
     }
     const server = http.createServer((req, res) => {
+        const pathname = requestPath(req.url || '');
+        const localDirect = isLocalDirect(req);
         if (req.method === 'GET' && (req.url || '') === '/api/available-baseagents') {
             // Base agent 可用性检测 API
             const available = detectBaseAgents();
@@ -749,6 +802,15 @@ export async function startWatchWebServer(opts = {}) {
                 return;
             }
             const { code, expiresAt } = freshPairing();
+            // daemon 通过 localhost 取码时带上 AUN 已认证的 owner AID。只接受
+            // 第一次绑定，避免同一配对码在不同 owner 间被重新归属。
+            const ownerHeader = req.headers['x-evolcore-pair-authorized-by'];
+            const controlHeader = req.headers['x-evolcore-control-token'];
+            const requestedOwner = validAuthorizedBy(Array.isArray(ownerHeader) ? ownerHeader[0] : ownerHeader);
+            const suppliedControlToken = Array.isArray(controlHeader) ? controlHeader[0] : controlHeader;
+            if (!pairingAuthorizedBy && requestedOwner && matchesDaemonControlToken(suppliedControlToken)) {
+                pairingAuthorizedBy = requestedOwner;
+            }
             res.writeHead(200, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({ code, expiresAt }));
         }
@@ -760,7 +822,34 @@ export async function startWatchWebServer(opts = {}) {
                 res.end(JSON.stringify({ ok: true, token: autoToken }));
                 return;
             }
-            handlePair(req, res, pairingCode, pairingExpiry, log);
+            handlePair(req, res, pairingCode, pairingExpiry, pairingAuthorizedBy, log);
+        }
+        else if (pathname === '/api/basic-settings' || pathname === '/api/basic-settings/secret') {
+            const authHeader = req.headers.authorization || '';
+            const bearerToken = authHeader.startsWith('Bearer ') ? authHeader.slice(7) : '';
+            const { query } = parseUrl(req.url || '');
+            let token = bearerToken || query.token || '';
+            if (!token) {
+                const autoToken = issueLocalDirectToken(req, log);
+                if (autoToken)
+                    token = autoToken;
+            }
+            if (!token || !validateAndRenew(token, Date.now())) {
+                res.writeHead(401, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ success: false, error: 'unauthorized' }));
+                return;
+            }
+            if (!localDirect && pathname === '/api/basic-settings/secret') {
+                res.writeHead(403, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
+                res.end(JSON.stringify({ success: false, error: 'remote ECWeb connections cannot reveal API keys' }));
+                return;
+            }
+            if (!localDirect && req.method !== 'GET') {
+                res.writeHead(403, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ success: false, error: 'remote ECWeb connections cannot modify daemon settings' }));
+                return;
+            }
+            void handleBasicSettingsApi(req, res, { redactConnectionMaps: !localDirect });
         }
         else if (req.method === 'GET' && (req.url || '').startsWith('/api/stats/')) {
             // Stats API — 本地直连自动发 token（免鉴权），远程需鉴权
@@ -808,12 +897,13 @@ export async function startWatchWebServer(opts = {}) {
                 if (autoToken)
                     token = autoToken;
             }
-            if (!token || !validateAndRenew(token, Date.now())) {
+            const tokenRecord = token ? getValidTokenRecord(token, Date.now()) : null;
+            if (!token || !tokenRecord) {
                 res.writeHead(401, { 'Content-Type': 'application/json' });
                 res.end(JSON.stringify({ error: 'unauthorized' }));
                 return;
             }
-            handleRelationRolesApi(req, res, daemonOwnerMenuAuth());
+            handleRelationRolesApi(req, res, daemonOwnerMenuAuth(localDirect, tokenRecord.authorizedBy));
         }
         else if ((req.url || '') === '/api/role-definitions' || (req.url || '').startsWith('/api/role-definitions/') || (req.url || '').startsWith('/api/role-definitions?')) {
             // Role Definitions API（含集合端点 /api/role-definitions 与 /api/role-definitions/:role）
@@ -826,12 +916,13 @@ export async function startWatchWebServer(opts = {}) {
                 if (autoToken)
                     token = autoToken;
             }
-            if (!token || !validateAndRenew(token, Date.now())) {
+            const tokenRecord = token ? getValidTokenRecord(token, Date.now()) : null;
+            if (!token || !tokenRecord) {
                 res.writeHead(401, { 'Content-Type': 'application/json' });
                 res.end(JSON.stringify({ error: 'unauthorized' }));
                 return;
             }
-            handleRoleDefinitionsApi(req, res, daemonOwnerMenuAuth());
+            handleRoleDefinitionsApi(req, res, daemonOwnerMenuAuth(localDirect, tokenRecord.authorizedBy));
         }
         else if ((req.url || '').startsWith('/api/assignments/peer/')) {
             const authHeader = req.headers.authorization || '';
@@ -843,12 +934,13 @@ export async function startWatchWebServer(opts = {}) {
                 if (autoToken)
                     token = autoToken;
             }
-            if (!token || !validateAndRenew(token, Date.now())) {
+            const tokenRecord = token ? getValidTokenRecord(token, Date.now()) : null;
+            if (!token || !tokenRecord) {
                 res.writeHead(401, { 'Content-Type': 'application/json' });
                 res.end(JSON.stringify({ error: 'unauthorized' }));
                 return;
             }
-            handlePeerRoleApi(req, res, daemonOwnerMenuAuth());
+            handlePeerRoleApi(req, res, daemonOwnerMenuAuth(localDirect, tokenRecord.authorizedBy));
         }
         else {
             serveStatic(req, res);
@@ -858,14 +950,16 @@ export async function startWatchWebServer(opts = {}) {
     server.on('upgrade', (req, socket, head) => {
         const { query } = parseUrl(req.url || '');
         // 本地直连免 token；远程需 token。
-        const authed = isLocalDirect(req) || validateAndRenew(query.token || '', Date.now());
+        const localDirect = isLocalDirect(req);
+        const tokenRecord = localDirect ? null : getValidTokenRecord(query.token || '', Date.now());
+        const authed = localDirect || tokenRecord !== null;
         wss.handleUpgrade(req, socket, head, (ws) => {
             if (!authed) {
                 log(`✗ WS 拒绝（无效 token） from ${clientIp(req)}`);
                 ws.close(4001, 'invalid-token');
                 return;
             }
-            handleConnection(ws, req, log);
+            handleConnection(ws, req, log, tokenRecord);
         });
     });
     const { port, displaced } = await bindPort(server, opts.port ?? DEFAULT_PORT, log);

package/dist/sources/aid.js

@@ -9,6 +9,7 @@ import fs from 'fs';
 import path from 'path';
 import { resolvePaths } from '../paths.js';
 import { ipcQuery } from '../ipc-client.js';
+import { watchMenuRequestAuth } from './types.js';
 /** 精简版实例扫描：仅在 daemon IPC 不可达时降级用，读各 alive main 进程的 aid 活动日志 */
 function scanAidActivity() {
     const result = new Map();
@@ -66,22 +67,28 @@ function scanAidActivity() {
 }
 // evolcore 版本：与 watch aid 状态栏一致。daemon 进程级、整轮 watch 不变，
 // 故缓存一次（首次 menu.query name=system 拿到后复用），避免每秒多发一次 IPC。
-let _cachedVersion = null;
-async function fetchVersion(socket) {
-    if (_cachedVersion)
-        return _cachedVersion;
+const versionCache = new Map();
+function authContextKey(params = {}) {
+    const auth = watchMenuRequestAuth(params);
+    return `${auth.localDirect ? 'local' : 'remote'}:${auth.actorAid || ''}`;
+}
+async function fetchVersion(socket, params = {}) {
+    const key = authContextKey(params);
+    const cached = versionCache.get(key);
+    if (cached)
+        return cached;
     try {
-        const r = await ipcQuery(socket, { type: 'menu.exec', payload: { type: 'menu.query', id: 'aid-sys-q', name: 'system' }, auth: { source: 'ecweb', localDirect: true } }, 4000);
+        const r = await ipcQuery(socket, { type: 'menu.exec', payload: { type: 'menu.query', id: 'aid-sys-q', name: 'system' }, auth: watchMenuRequestAuth(params) }, 4000);
         const v = r?.ok ? r.response?.data?.version : null;
         if (v)
-            _cachedVersion = v;
+            versionCache.set(key, v);
         return v ?? null;
     }
     catch {
         return null;
     }
 }
-async function buildSnapshot(fallback = null) {
+async function buildSnapshot(fallback = null, params = {}) {
     const p = resolvePaths();
     const [aidsResp, statsResp, agentStatsResp, statusResp, agentsResp, version] = await Promise.all([
         ipcQuery(p.socket, { type: 'aun-aids' }),
@@ -89,7 +96,7 @@ async function buildSnapshot(fallback = null) {
         ipcQuery(p.socket, { type: 'agent-stats' }),
         ipcQuery(p.socket, { type: 'status' }),
         ipcQuery(p.socket, { type: 'evolagent.list' }),
-        fetchVersion(p.socket),
+        fetchVersion(p.socket, params),
     ]);
     // 任一只读命令能返回就说明 IPC/daemon 仍可达。慢主机上某个较重的
     // 统计命令单独超时，不应把整个 Agent 页面判成离线。
@@ -118,48 +125,60 @@ async function buildSnapshot(fallback = null) {
 }
 const AID_POLL_INTERVAL_MS = 1000;
 const DAEMON_FAILURE_THRESHOLD = 3;
-// IPC 查询是整页共享的：每个浏览器标签页各自发起一组查询会在慢主机上
-// 形成请求堆积。共享 promise 还可以让初始 snapshot 和轮询复用同一轮结果。
-const subscribers = new Set();
-let pollTimer = null;
-let pollInFlight = null;
-let lastSuccessfulSnapshot = null;
-let lastResolvedSnapshot = null;
-let consecutiveDaemonFailures = 0;
-async function readStableSnapshot() {
-    if (!pollInFlight) {
-        pollInFlight = (async () => {
+// 同一认证上下文的浏览器标签页共享轮询；本地直连与远程 token 必须隔离，
+// 避免本地 owner 查询的快照或 in-flight promise 被远程连接复用。
+const pollStates = new Map();
+function pollState(params = {}) {
+    const key = authContextKey(params);
+    let state = pollStates.get(key);
+    if (!state) {
+        state = {
+            params,
+            subscribers: new Set(),
+            pollTimer: null,
+            pollInFlight: null,
+            lastSuccessfulSnapshot: null,
+            lastResolvedSnapshot: null,
+            consecutiveDaemonFailures: 0,
+        };
+        pollStates.set(key, state);
+    }
+    return state;
+}
+async function readStableSnapshot(state) {
+    if (!state.pollInFlight) {
+        state.pollInFlight = (async () => {
             let snapshot;
             try {
-                snapshot = await buildSnapshot(lastSuccessfulSnapshot);
+                snapshot = await buildSnapshot(state.lastSuccessfulSnapshot, state.params);
             }
             catch {
                 snapshot = { daemonRunning: false, aids: [], stats: [], agentStats: [], agents: [] };
             }
             if (snapshot?.daemonRunning) {
-                consecutiveDaemonFailures = 0;
-                lastSuccessfulSnapshot = snapshot;
-                lastResolvedSnapshot = snapshot;
+                state.consecutiveDaemonFailures = 0;
+                state.lastSuccessfulSnapshot = snapshot;
+                state.lastResolvedSnapshot = snapshot;
                 return snapshot;
             }
-            consecutiveDaemonFailures += 1;
+            state.consecutiveDaemonFailures += 1;
             // 单轮 IPC 超时不代表 daemon 已停止。保留最近一次成功数据，直到
             // 连续多轮都失败，避免页面在慢主机上反复清空和恢复。
-            if (lastSuccessfulSnapshot && consecutiveDaemonFailures < DAEMON_FAILURE_THRESHOLD) {
-                lastResolvedSnapshot = lastSuccessfulSnapshot;
-                return lastSuccessfulSnapshot;
+            if (state.lastSuccessfulSnapshot && state.consecutiveDaemonFailures < DAEMON_FAILURE_THRESHOLD) {
+                state.lastResolvedSnapshot = state.lastSuccessfulSnapshot;
+                return state.lastSuccessfulSnapshot;
             }
-            lastResolvedSnapshot = snapshot;
+            state.lastResolvedSnapshot = snapshot;
             return snapshot;
         })().finally(() => {
-            pollInFlight = null;
+            state.pollInFlight = null;
         });
     }
-    return pollInFlight;
+    return state.pollInFlight;
 }
-function notifySubscribers(snapshot) {
+function notifySubscribers(state, snapshot) {
     const json = JSON.stringify(snapshot);
-    for (const subscriber of subscribers) {
+    for (const subscriber of state.subscribers) {
         if (json === subscriber.lastJson)
             continue;
         subscriber.lastJson = json;
@@ -169,40 +188,41 @@ function notifySubscribers(snapshot) {
         catch { /* subscriber disconnected */ }
     }
 }
-function schedulePoll(delayMs = AID_POLL_INTERVAL_MS) {
-    if (pollTimer !== null || subscribers.size === 0)
+function schedulePoll(state, delayMs = AID_POLL_INTERVAL_MS) {
+    if (state.pollTimer !== null || state.subscribers.size === 0)
         return;
-    pollTimer = setTimeout(async () => {
-        pollTimer = null;
-        if (subscribers.size === 0)
+    state.pollTimer = setTimeout(async () => {
+        state.pollTimer = null;
+        if (state.subscribers.size === 0)
             return;
         try {
-            notifySubscribers(await readStableSnapshot());
+            notifySubscribers(state, await readStableSnapshot(state));
         }
         catch { /* ignore transient IPC errors */ }
         // 下一轮从本轮完成后开始计时，绝不与上一轮重叠。
-        schedulePoll();
+        schedulePoll(state);
     }, delayMs);
 }
 export const aidSource = {
     kind: 'agents',
-    async snapshot() {
-        return readStableSnapshot();
+    async snapshot(params = {}) {
+        return readStableSnapshot(pollState(params));
     },
-    subscribe(_params, push) {
+    subscribe(params, push) {
+        const state = pollState(params);
         // server 会在 subscribe 前先发送 snapshot；以最近成功值作为基线，避免
         // 第一轮轮询把同一份数据再推送一次。
         const subscriber = {
             push,
-            lastJson: lastResolvedSnapshot ? JSON.stringify(lastResolvedSnapshot) : '',
+            lastJson: state.lastResolvedSnapshot ? JSON.stringify(state.lastResolvedSnapshot) : '',
         };
-        subscribers.add(subscriber);
-        schedulePoll();
+        state.subscribers.add(subscriber);
+        schedulePoll(state);
         return () => {
-            subscribers.delete(subscriber);
-            if (subscribers.size === 0 && pollTimer !== null) {
-                clearTimeout(pollTimer);
-                pollTimer = null;
+            state.subscribers.delete(subscriber);
+            if (state.subscribers.size === 0 && state.pollTimer !== null) {
+                clearTimeout(state.pollTimer);
+                state.pollTimer = null;
             }
         };
     },

package/dist/sources/baseagent-detector.js

@@ -1,14 +1,16 @@
 /**
- * Base agent 环境检测 — 检测 Claude 和 Codex 的可用性。
+ * Base agent 环境检测 — 检测本机可用的 Claude、Codex、Gemini 和内置 EC Agent。
  *
  * 检测条件：
- * - Claude: ~/.claude/projects/ 目录存在
- * - Codex: ~/.codex/sessions/ 和 ~/.codex/state_*.sqlite 存在，且 Node 版本 >= 22.5
+ * 命令行工具优先按 PATH 检测；同时保留会话目录检测，兼容 CLI 不在当前 shell
+ * PATH 但已经在本机初始化过的情况。ecagent 随 EvolCore 一起提供，始终作为可选
+ * 基座展示，实际凭据和网关配置由配置校验负责。
  */
 import fs from 'fs';
 import path from 'path';
 import os from 'os';
 import { createRequire } from 'module';
+import { spawnSync } from 'child_process';
 const requireFromHere = createRequire(import.meta.url);
 let _cached = null;
 /**
@@ -45,6 +47,40 @@ function checkClaudeProjects() {
     const claudeProjects = path.join(os.homedir(), '.claude', 'projects');
     return fs.existsSync(claudeProjects);
 }
+function commandExists(command) {
+    try {
+        const result = process.platform === 'win32'
+            ? spawnSync('where', [command], { stdio: 'ignore', windowsHide: true })
+            : spawnSync('sh', ['-lc', `command -v ${JSON.stringify(command)}`], { stdio: 'ignore' });
+        return result.status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+function checkGeminiHome() {
+    return fs.existsSync(path.join(os.homedir(), '.gemini'));
+}
+function detectSources(id) {
+    if (id === 'ecagent')
+        return ['内置'];
+    const sources = [];
+    if (commandExists(id))
+        sources.push('PATH');
+    if (id === 'claude' && checkClaudeProjects())
+        sources.push('~/.claude/projects');
+    if (id === 'codex') {
+        if (checkCodexSessions())
+            sources.push('~/.codex/sessions');
+        if (checkCodexStateDb())
+            sources.push('~/.codex/state_*.sqlite');
+        if (checkSqliteAvailable())
+            sources.push('node:sqlite');
+    }
+    if (id === 'gemini' && checkGeminiHome())
+        sources.push('~/.gemini');
+    return sources;
+}
 /**
  * 检测 Codex sessions 目录是否存在
  */
@@ -59,11 +95,29 @@ function checkCodexSessions() {
 export function detectBaseAgents() {
     if (_cached)
         return _cached;
-    const claude = checkClaudeProjects();
-    const codex = checkCodexSessions() && checkCodexStateDb() && checkSqliteAvailable();
-    _cached = { claude, codex };
+    const claude = detectSources('claude').length > 0;
+    const codex = detectSources('codex').length > 0;
+    const gemini = detectSources('gemini').length > 0;
+    const ecagent = true;
+    _cached = { claude, codex, gemini, ecagent };
     return _cached;
 }
+/** Return display-oriented detection details for the Basic Settings API. */
+export function detectBaseAgentDetails(defaults = {}) {
+    const configured = isRecord(defaults?.baseagents) ? defaults.baseagents : {};
+    return ['claude', 'codex', 'gemini', 'ecagent'].map(id => {
+        const detectionSource = detectSources(id);
+        return {
+            id,
+            detected: id === 'ecagent' || detectionSource.length > 0,
+            configured: Object.prototype.hasOwnProperty.call(configured, id),
+            detectionSource,
+        };
+    });
+}
+function isRecord(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
 /**
  * 重置缓存（测试用）
  */