evolcore 0.0.31 → 0.0.33

package/dist/core/session/session-idle-monitor.js

@@ -1,25 +1,142 @@
 import fs from 'fs';
 import path from 'path';
-import { ConfigTarget, read as readConfig } from '../../config/config-manager.js';
+import { ConfigTarget, mutateConfig, read as readConfig } from '../../config/config-manager.js';
 import { formatPeerKey } from '../relation/peer-identity.js';
+import { isSystemControlChannel } from '../system-channels.js';
 import { logger } from '../../utils/logger.js';
 import { atomicWriteJson } from './session-fs-store.js';
 import { createRootCausation } from '../causation/context.js';
-export const MIN_SESSION_IDLE_SECONDS = 30;
-export function readRelationSessionIdleSeconds(session) {
-    if (!session.selfAID || !session.channelId)
+export const DEFAULT_SESSION_LOOP_SECONDS = 300;
+export const MIN_SESSION_LOOP_SECONDS = 30;
+export const MAX_SESSION_LOOP_SECONDS = 86400;
+export function normalizeSessionLoopConfig(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
         return undefined;
-    try {
-        const relation = readConfig(ConfigTarget.Relation, {
-            self: session.selfAID,
-            peerKey: formatPeerKey(session.channelType || session.channel, session.channelId),
-        }, { cache: true, expand: true });
-        return relation?.sessionIdleSec;
-    }
-    catch (error) {
-        logger.warn(`[SessionIdleMonitor] Failed to read relation config for ${session.id}: ${error instanceof Error ? error.message : String(error)}`);
+    const raw = value;
+    if (Object.keys(raw).some(key => key !== 'enabled' && key !== 'idleSeconds'))
+        return undefined;
+    if (raw.enabled === false && Object.keys(raw).every(key => key === 'enabled'))
+        return { enabled: false };
+    if (raw.enabled !== true || !isValidIdleSeconds(raw.idleSeconds))
+        return undefined;
+    return { enabled: true, idleSeconds: raw.idleSeconds };
+}
+export function validateIdleSeconds(value) {
+    return isValidIdleSeconds(value) ? value : undefined;
+}
+export function resolveSessionLoopTarget(session) {
+    if (!session || session.deletedAt || session.topicStatus === 'archived'
+        || session.metadata?.sessionType || isSystemControlChannel(session.channel)
+        || (session.chatType !== 'private' && session.chatType !== 'group'))
+        return undefined;
+    const peerId = session.chatType === 'group'
+        ? session.metadata?.groupId || session.channelId
+        : session.channelId;
+    if (!session.selfAID || !peerId)
         return undefined;
+    const peerKey = formatPeerKey(session.channelType || session.channel, peerId);
+    return { level: session.threadId ? 'topic-session' : 'relation-main', session, peerKey };
+}
+export function readSessionLoopConfig(target) {
+    let value;
+    if (target.level === 'topic-session')
+        value = target.session.metadata?.sessionLoop;
+    else {
+        try {
+            const relation = readConfig(ConfigTarget.Relation, {
+                self: target.session.selfAID,
+                peerKey: target.peerKey,
+            }, { cache: true, expand: true });
+            value = relation?.sessionLoop;
+        }
+        catch (error) {
+            logger.warn(`[SessionLoop] Failed to read configuration for ${target.session.id}; disabled: ${error instanceof Error ? error.message : String(error)}`);
+            return undefined;
+        }
+    }
+    const config = normalizeSessionLoopConfig(value);
+    if (value !== undefined && !config)
+        logger.warn(`[SessionLoop] Invalid configuration for ${target.session.id}; disabled`);
+    return config;
+}
+export function readSessionLoopConfigForSession(session) {
+    const target = resolveSessionLoopTarget(session);
+    return target ? readSessionLoopConfig(target) : undefined;
+}
+export function updateRelationSessionLoop(session, config) {
+    const target = resolveSessionLoopTarget(session);
+    if (!target || target.level !== 'relation-main')
+        throw sessionLoopError('INVALID_TARGET', 'relation main session is required');
+    const selector = { self: session.selfAID, peerKey: target.peerKey };
+    const normalized = normalizeSessionLoopConfig(config);
+    if (!normalized)
+        throw sessionLoopError('INVALID_ARGUMENT', 'invalid sessionLoop configuration');
+    mutateConfig(ConfigTarget.Relation, selector, current => {
+        current.sessionLoop = normalized;
+    });
+}
+export async function resolveCurrentSessionLoopTarget(store, route) {
+    let session;
+    try {
+        session = route.threadId
+            ? await store.getThreadSession(route.channel, route.channelId, route.threadId)
+            : await store.getActiveSession(route.channel, route.channelId);
+    }
+    catch {
+        throw sessionLoopError('SESSION_LOOKUP_FAILED', '无法读取当前会话，拒绝回退到其他会话');
+    }
+    if (!session || session.deletedAt)
+        throw sessionLoopError(route.threadId ? 'NOT_FOUND' : 'NO_ACTIVE_SESSION', '当前会话不存在');
+    const target = resolveSessionLoopTarget(session);
+    if (!target || !route.selfAid || session.selfAID !== route.selfAid
+        || session.channel !== route.channel || session.channelId !== route.channelId
+        || (session.threadId || '') !== (route.threadId || '')) {
+        throw sessionLoopError('INVALID_CONTEXT', '当前会话路由或归属不匹配');
+    }
+    return target;
+}
+export async function refreshSessionLoopTarget(store, route, expected) {
+    const current = await resolveCurrentSessionLoopTarget(store, route);
+    if (current.session.id !== expected.session.id || current.peerKey !== expected.peerKey || current.level !== expected.level) {
+        throw sessionLoopError('CONFLICT', '当前会话已发生变化，请重新查询');
     }
+    return current;
+}
+export function writeSessionLoopConfig(store, target, config) {
+    if (target.level === 'topic-session') {
+        const session = store.updateSessionLoop(target.session.id, config);
+        return { ...target, session };
+    }
+    const active = store.getActiveSessionSync(target.session.channel, target.session.channelId);
+    if (!active || active.deletedAt || active.id !== target.session.id || active.threadId) {
+        throw sessionLoopError('CONFLICT', '当前主会话已发生变化，请重新查询');
+    }
+    updateRelationSessionLoop(active, config);
+    return { ...target, session: active };
+}
+export function sessionLoopPayload(target) {
+    const config = readSessionLoopConfig(target);
+    return {
+        target: { level: target.level, sessionId: target.session.id },
+        sessionId: target.session.id,
+        value: config?.enabled === true,
+        ...(config?.enabled ? { idleSeconds: config.idleSeconds } : {}),
+    };
+}
+export function sessionLoopError(code, message) {
+    return Object.assign(new Error(message), { code });
+}
+function isValidIdleSeconds(value) {
+    return typeof value === 'number'
+        && Number.isFinite(value)
+        && Number.isSafeInteger(value)
+        && value >= MIN_SESSION_LOOP_SECONDS
+        && value <= MAX_SESSION_LOOP_SECONDS;
+}
+export const MIN_SESSION_IDLE_SECONDS = MIN_SESSION_LOOP_SECONDS;
+export function readSessionLoopIdleSeconds(session) {
+    const config = readSessionLoopConfigForSession(session);
+    return config?.enabled ? config.idleSeconds : undefined;
 }
 /**
  * Publishes one session:idle event after a runner task ends, using the
@@ -71,7 +188,17 @@ export class SessionIdleMonitor {
         if (event.type !== 'session:switched')
             return;
         this.clearSession(event.fromSessionId);
-        this.clearSession(event.toSessionId);
+        void this.activateMainSession(event.toSessionId);
+    };
+    onSessionCreated = (event) => {
+        if (event.type !== 'session:created' || event.threadId)
+            return;
+        for (const sessionId of this.sessions.keys())
+            void this.pruneInactiveMainSession(sessionId);
+    };
+    onSessionLoopChanged = (event) => {
+        if (event.type === 'session:loop-changed')
+            void this.refreshSession(event.sessionId, event.timestamp);
     };
     constructor(options) {
         this.options = options;
@@ -88,6 +215,8 @@ export class SessionIdleMonitor {
         this.options.eventBus.subscribe('task:started', this.onTaskStarted);
         this.options.eventBus.subscribe('session:deleted', this.onSessionDeleted);
         this.options.eventBus.subscribe('session:switched', this.onSessionSwitched);
+        this.options.eventBus.subscribe('session:created', this.onSessionCreated);
+        this.options.eventBus.subscribe('session:loop-changed', this.onSessionLoopChanged);
     }
     /** Arm restored timers only after event-trigger subscriptions are registered. */
     activate() {
@@ -108,6 +237,47 @@ export class SessionIdleMonitor {
             this.scheduleSession(sessionId);
         }
     }
+    async refreshSession(sessionId, changedAt = this.now()) {
+        const state = this.sessions.get(sessionId);
+        if (!state || !this.active)
+            return;
+        const generation = this.generations.get(sessionId) ?? 0;
+        try {
+            const session = await this.options.getSessionById(sessionId);
+            if (!session || !this.isEligibleSession(session))
+                return;
+            const seconds = await this.readIdleSeconds(session);
+            if (this.sessions.get(sessionId) !== state || (this.generations.get(sessionId) ?? 0) !== generation)
+                return;
+            if (state.idleSeconds === seconds)
+                return;
+            this.clearTimers(sessionId);
+            this.generations.set(sessionId, generation + 1);
+            state.idleSeconds = seconds;
+            state.armedAt = changedAt;
+            state.emitted = false;
+            this.persistState();
+            if (seconds !== undefined && !await this.options.isSessionBusy(sessionId))
+                this.scheduleSession(sessionId);
+        }
+        catch (error) {
+            this.warn(`Failed to refresh loop configuration for ${sessionId}`, error);
+        }
+    }
+    async refreshRelation(selfAid, peerKey, changedAt = this.now()) {
+        for (const sessionId of this.sessions.keys()) {
+            try {
+                const session = await this.options.getSessionById(sessionId);
+                const target = resolveSessionLoopTarget(session);
+                if (target?.level === 'relation-main' && target.peerKey === peerKey && session?.selfAID === selfAid) {
+                    await this.refreshSession(sessionId, changedAt);
+                }
+            }
+            catch (error) {
+                this.warn(`Failed to refresh relation loop configuration for ${sessionId}`, error);
+            }
+        }
+    }
     stop() {
         this.active = false;
         this.clearAllTimers();
@@ -120,6 +290,8 @@ export class SessionIdleMonitor {
         this.options.eventBus.unsubscribe('task:started', this.onTaskStarted);
         this.options.eventBus.unsubscribe('session:deleted', this.onSessionDeleted);
         this.options.eventBus.unsubscribe('session:switched', this.onSessionSwitched);
+        this.options.eventBus.unsubscribe('session:created', this.onSessionCreated);
+        this.options.eventBus.unsubscribe('session:loop-changed', this.onSessionLoopChanged);
     }
     now() {
         return this.options.now?.() ?? Date.now();
@@ -172,15 +344,21 @@ export class SessionIdleMonitor {
             this.clearSession(sessionId);
             return;
         }
-        if (!isSupportedSession(session))
+        if (!this.isEligibleSession(session)) {
+            this.clearTimers(sessionId);
             return;
+        }
         const idleSeconds = await this.readIdleSeconds(session);
         if (!this.isCurrentCycle(sessionId, state.lastEndedAt, generation))
             return;
+        if (this.timers.has(sessionId))
+            return;
         const idleMs = toIdleMs(idleSeconds);
+        state.idleSeconds = idleSeconds;
+        this.persistState();
         if (idleMs === undefined)
             return;
-        const delay = Math.max(0, state.lastEndedAt + idleMs - this.now());
+        const delay = Math.max(0, (state.armedAt ?? state.lastEndedAt) + idleMs - this.now());
         const timer = setTimeout(() => {
             this.timers.delete(sessionId);
             void this.emitIfIdle(sessionId, state.lastEndedAt, generation);
@@ -209,14 +387,14 @@ export class SessionIdleMonitor {
             this.clearSession(sessionId);
             return;
         }
-        if (!isSupportedSession(session))
+        if (!this.isEligibleSession(session))
             return;
         const idleMs = toIdleMs(await this.readIdleSeconds(session));
         if (!this.isCurrentCycle(sessionId, lastEndedAt, generation))
             return;
         if (idleMs === undefined)
             return;
-        const remaining = lastEndedAt + idleMs - this.now();
+        const remaining = (this.sessions.get(sessionId)?.armedAt ?? lastEndedAt) + idleMs - this.now();
         if (remaining > 0) {
             this.scheduleSession(sessionId);
             return;
@@ -232,6 +410,8 @@ export class SessionIdleMonitor {
         }
         if (!this.isCurrentCycle(sessionId, lastEndedAt, generation))
             return;
+        if (!this.isEligibleSession(session))
+            return;
         if (busy) {
             // An active/queued task is not idle. Disarm this cycle and let its next
             // terminal event start a fresh one; repeatedly rearming here would poll
@@ -248,7 +428,8 @@ export class SessionIdleMonitor {
         if (!state || state.emitted)
             return;
         state.emitted = true;
-        this.persistState();
+        if (!this.persistState())
+            return;
         this.options.eventBus.publish({
             type: 'session:idle',
             sessionId,
@@ -308,6 +489,49 @@ export class SessionIdleMonitor {
             return undefined;
         }
     }
+    isEligibleSession(session) {
+        return !!resolveSessionLoopTarget(session)
+            && (!!session.threadId || !this.options.isCurrentMainSession || this.options.isCurrentMainSession(session));
+    }
+    async disarmMainSession(sessionId) {
+        try {
+            const session = await this.options.getSessionById(sessionId);
+            if (!session || session.threadId)
+                return;
+            this.clearTimers(sessionId);
+            this.generations.set(sessionId, (this.generations.get(sessionId) ?? 0) + 1);
+        }
+        catch (error) {
+            this.warn(`Failed to disarm main session ${sessionId}`, error);
+        }
+    }
+    async activateMainSession(sessionId) {
+        try {
+            const session = await this.options.getSessionById(sessionId);
+            const state = this.sessions.get(sessionId);
+            if (!session || session.threadId || !state || !this.isEligibleSession(session))
+                return;
+            this.clearTimers(sessionId);
+            this.generations.set(sessionId, (this.generations.get(sessionId) ?? 0) + 1);
+            state.armedAt = this.now();
+            state.emitted = false;
+            this.persistState();
+            this.scheduleSession(sessionId);
+        }
+        catch (error) {
+            this.warn(`Failed to activate main session ${sessionId}`, error);
+        }
+    }
+    async pruneInactiveMainSession(sessionId) {
+        try {
+            const session = await this.options.getSessionById(sessionId);
+            if (session && !session.threadId && !this.isEligibleSession(session))
+                await this.disarmMainSession(sessionId);
+        }
+        catch (error) {
+            this.warn(`Failed to inspect main session ${sessionId}`, error);
+        }
+    }
     loadState() {
         try {
             if (!fs.existsSync(this.options.statePath))
@@ -330,6 +554,8 @@ export class SessionIdleMonitor {
                     lastEndedAt,
                     emitted,
                     ...(typeof rawState.encrypted === 'boolean' ? { encrypted: rawState.encrypted } : {}),
+                    ...(typeof rawState.armedAt === 'number' && Number.isFinite(rawState.armedAt) ? { armedAt: rawState.armedAt } : {}),
+                    ...(typeof rawState.idleSeconds === 'number' ? { idleSeconds: rawState.idleSeconds } : {}),
                 });
             }
         }
@@ -344,23 +570,24 @@ export class SessionIdleMonitor {
                 lastEndedAt: state.lastEndedAt,
                 emitted: state.emitted,
                 ...(typeof state.encrypted === 'boolean' ? { encrypted: state.encrypted } : {}),
+                ...(state.armedAt !== undefined ? { armedAt: state.armedAt } : {}),
+                ...(state.idleSeconds !== undefined ? { idleSeconds: state.idleSeconds } : {}),
             };
         }
         try {
             fs.mkdirSync(path.dirname(this.options.statePath), { recursive: true });
             atomicWriteJson(this.options.statePath, { version: 2, sessions });
+            return true;
         }
         catch (error) {
             this.warn(`Failed to persist session idle state at ${this.options.statePath}`, error);
+            return false;
         }
     }
     warn(message, error) {
         logger.warn(`[SessionIdleMonitor] ${message}${error === undefined ? '' : `: ${error instanceof Error ? error.message : String(error)}`}`);
     }
 }
-function isSupportedSession(session) {
-    return session.chatType === 'group' || session.chatType === 'private';
-}
 function toIdleMs(seconds) {
     if (seconds === undefined || !Number.isFinite(seconds) || seconds <= 0)
         return undefined;

package/dist/core/session/session-manager.js

@@ -1,3 +1,4 @@
+import { normalizeSessionLoopConfig, resolveSessionLoopTarget, sessionLoopError } from './session-idle-monitor.js';
 import { ensureDir } from '../../utils/atomic-write.js';
 import { resolvePaths } from '../../paths.js';
 import { logger } from '../../utils/logger.js';
@@ -225,7 +226,7 @@ export function pageForkHistory(snapshot, before = snapshot.items.length, limit
     };
 }
 /** Metadata keys owned by ordinary topic/session routing writers. */
-const TOPIC_METADATA_PROTECTED_KEYS = new Set(['turnState', 'resumeAt', 'agentSessions']);
+const TOPIC_METADATA_PROTECTED_KEYS = new Set(['turnState', 'resumeAt', 'agentSessions', 'sessionLoop']);
 const TOPIC_BACKEND_SCOPED_KEYS = ['resumeAt', 'agentSessions'];
 function topicMetadataOwnershipError(key) {
     const error = new Error(`topic metadata field is owned by a dedicated updater: ${key}`);
@@ -646,6 +647,15 @@ export class SessionManager {
      * @returns 是否真的写入了 .jsonl（去重命中时返回 false）
      */
     persistSession(session, intent, opts) {
+        if (!opts?.sessionLoopMutation) {
+            const latest = this.readMetaLatest(this.metaPathForSession(session));
+            const metadata = { ...(session.metadata ?? {}) };
+            if (latest?.metadata?.sessionLoop !== undefined)
+                metadata.sessionLoop = latest.metadata.sessionLoop;
+            else
+                delete metadata.sessionLoop;
+            session.metadata = metadata;
+        }
         // Topic session snapshots can be written by synchronous legacy paths
         // (mark/clear processing) after an async /renew has committed.  Preserve
         // the newest backend fence unless this call is one of the two explicit
@@ -1308,6 +1318,8 @@ export class SessionManager {
         if (updates.name !== undefined)
             current.name = updates.name;
         if (updates.metadata !== undefined) {
+            if (Object.hasOwn(updates.metadata, 'sessionLoop'))
+                throw topicMetadataOwnershipError('sessionLoop');
             if (current.threadId) {
                 for (const key of Object.keys(updates.metadata)) {
                     if (TOPIC_METADATA_PROTECTED_KEYS.has(key))
@@ -1337,6 +1349,8 @@ export class SessionManager {
             return;
         const { current } = loaded;
         for (const key of Object.keys(patch)) {
+            if (key === 'sessionLoop')
+                throw topicMetadataOwnershipError(key);
             if (current.threadId && TOPIC_METADATA_PROTECTED_KEYS.has(key)) {
                 throw topicMetadataOwnershipError(key);
             }
@@ -1351,6 +1365,21 @@ export class SessionManager {
         current.metadata = metadata;
         this.persistSession(current, 'sync');
     }
+    updateSessionLoop(sessionId, config) {
+        const normalized = normalizeSessionLoopConfig(config);
+        if (!normalized)
+            throw sessionLoopError('INVALID_ARGUMENT', 'invalid sessionLoop configuration');
+        return this.mutateLatestTopicSession(sessionId, current => {
+            const target = resolveSessionLoopTarget(current);
+            if (!target || target.level !== 'topic-session')
+                throw sessionLoopError('INVALID_CONTEXT', '话题会话不存在或已不可用');
+            current.metadata = { ...(current.metadata ?? {}), sessionLoop: normalized };
+            const changed = this.persistSession(current, 'none', { sessionLoopMutation: true });
+            if (changed)
+                this.eventBus.publish({ type: 'session:loop-changed', sessionId, timestamp: Date.now() });
+            return current;
+        });
+    }
     /** Persist only the turn coordinator-owned metadata field. */
     async updateTurnState(sessionId, turnState) {
         const loaded = this.loadSessionForUpdate(sessionId);
@@ -1366,6 +1395,8 @@ export class SessionManager {
         this.persistSession(current, 'sync', { turnStateMutation: true });
     }
     getOrCreateThreadSession(channel, channelId, threadId, defaultProjectPath, metadata, name, baseagent, selfAID, channelType, peerType, chatType, label, topicStatus) {
+        const topicMetadata = { ...(metadata ?? {}) };
+        delete topicMetadata.sessionLoop;
         // 使用精确路径（channelType + selfAID）
         const chatDir = (channelType && selfAID)
             ? (() => { const d = chatDirPath(this.sessionsDir, channelType, channelId, selfAID, channel); fs.mkdirSync(d, { recursive: true }); fs.mkdirSync(path.join(d, '_threads'), { recursive: true }); return d; })()
@@ -1387,7 +1418,7 @@ export class SessionManager {
                 let mutated = false;
                 if (metadata) {
                     const creatorPeerId = existing.metadata?.peerId;
-                    existing.metadata = { ...(existing.metadata || {}), ...metadata };
+                    existing.metadata = { ...(existing.metadata || {}), ...topicMetadata };
                     if (creatorPeerId && existing.metadata)
                         existing.metadata.peerId = creatorPeerId;
                     mutated = true;
@@ -1411,7 +1442,21 @@ export class SessionManager {
         const mainActive = readJsonFile(path.join(chatDir, 'active.json'));
         // 兼容旧字段名
         const mainBaseagent = mainActive?.baseagent || mainActive?.agentType;
-        const inheritedBaseagent = mainBaseagent || baseagent;
+        // 最终兜底：从 agent config.json 读 active_baseagent（宿主终端下 active.json 可能不存在）
+        const configBaseagent = (() => {
+            if (mainBaseagent || baseagent)
+                return undefined;
+            if (!selfAID)
+                return undefined;
+            try {
+                const cfg = readJsonFile(path.join(resolvePaths().agentsDir, selfAID, 'config.json'));
+                return cfg?.active_baseagent || undefined;
+            }
+            catch {
+                return undefined;
+            }
+        })();
+        const inheritedBaseagent = mainBaseagent || baseagent || configBaseagent;
         if (!inheritedBaseagent) {
             throw new Error('[SessionManager] getOrCreateThreadSession: baseagent is empty');
         }
@@ -1426,7 +1471,7 @@ export class SessionManager {
             baseagent: inheritedBaseagent,
             sessionKey,
             chatType: effectiveChatType,
-            metadata,
+            metadata: topicMetadata,
             name: name || '话题会话',
             label: normalizeTopicLabel(label),
             topicStatus: topicStatus ? normalizeTopicStatus(topicStatus) : 'pending',
@@ -1671,10 +1716,10 @@ export class SessionManager {
             return !!session && !session.threadId;
         });
     }
-    async getThreadSession(channel, channelId, threadId) {
+    async getThreadSession(channel, channelId, threadId, selfAID) {
         let chatDir;
         try {
-            chatDir = this.resolveChatDirSafe(channel, channelId);
+            chatDir = this.resolveChatDirSafe(channel, channelId, channel === 'aun' ? 'aun' : undefined, selfAID);
         }
         catch {
             return undefined;
@@ -1687,9 +1732,6 @@ export class SessionManager {
         const session = this.readMetaLatest(metaPath);
         if (!session)
             return undefined;
-        // Do not consult provider-file existence to derive topic binding state;
-        // the topic JSONL boundary is authoritative and may intentionally point
-        // at a backend that needs an explicit /renew or repair operation.
         const validSessionId = normalizeBackendSessionId(session.agentSessionId);
         return { ...session, agentSessionId: validSessionId };
     }
@@ -1761,6 +1803,8 @@ export class SessionManager {
         return target;
     }
     updateMetadata(sessionId, metadata) {
+        if (Object.hasOwn(metadata, 'sessionLoop'))
+            throw topicMetadataOwnershipError('sessionLoop');
         const loaded = this.loadSessionForUpdate(sessionId);
         if (!loaded)
             return;
@@ -2123,6 +2167,7 @@ export class SessionManager {
         delete metadata.agentSessions;
         delete metadata.resumeAt;
         delete metadata.replyContext;
+        delete metadata.sessionLoop;
         metadata.__sessionRenewedAt = Date.now();
         const session = {
             id: generateSessionId(),

package/dist/core/skill/command-parser.js

@@ -0,0 +1,13 @@
+import { isValidAid } from '../../aun/aid/validation.js';
+export function resolveSkillRefreshArgv(argv) {
+    if (argv[0] !== 'skill' || argv[1] !== 'refresh' || argv.length < 3 || argv.length > 4
+        || argv.some(value => typeof value !== 'string'))
+        throw new Error('Invalid skill refresh argv');
+    const positional = argv.slice(2).filter(value => value !== '--json');
+    if (positional.length !== 1)
+        throw new Error('Specify one Agent AID');
+    const aid = positional[0].replace(/^@/, '');
+    if (!isValidAid(aid))
+        throw new Error('Invalid Agent AID');
+    return aid;
+}

package/dist/core/skill/index-generator.js

@@ -42,6 +42,9 @@ function generateOneIndex(indexDir, filename, skills, label) {
     const sep = path.sep;
     const header = `[skills-${label}] 本 Agent 已启用 ${skills.length} 个${label === 'builtin' ? '内置' : '本机'}技能。
 
+加载方式: EC 技能用 Read 工具读取上面对应的 SKILL.md 全文后按内容执行；
+  它们不是宿主工具自带的技能或斜杠命令，用 Skill/斜杠命令加载会报 Unknown skill/未知命令。
+
 路径规则:
   根目录: ${rootDir}
   技能目录 = 根目录 + "${sep}" + 技能名
@@ -66,7 +69,7 @@ function generateOneIndex(indexDir, filename, skills, label) {
  * 直接按目录读，不走 discoverSkillDirectories——后者按父目录扫描再按 name 匹配，
  * 同名技能（本机覆盖内置）会读到另一份的 description。
  */
-function readSkillDescription(skillDir) {
+export function readSkillDescription(skillDir) {
     try {
         const text = fs.readFileSync(path.join(skillDir, 'SKILL.md'), 'utf-8');
         const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);

package/dist/core/skill/startup.js

@@ -2,6 +2,28 @@ import { generateSkillIndexes } from './index-generator.js';
 import { globalSkillWatcher } from './global-watcher.js';
 import { logger } from '../../utils/logger.js';
 import { invalidateKitCache } from '../../eck/kit-renderer.js';
+import { isSkillWatchEnabled } from '../../config-store.js';
+/**
+ * 监控开关（daemon.json `skills.watch`，默认 false），daemon 启动时读一次。
+ *
+ * 关闭时不创建任何 chokidar watcher：Windows 上 chokidar 每个文件/目录各占一个
+ * 目录句柄（本机实测 ~/.evolcore/skills 约 3400 个），子目录因此无法被资源管理器
+ * 删除或重命名。关闭后改完技能需执行 `ec skill refresh <aid>`（refreshSkillIndex）。
+ * 监控与手动刷新互不冲突，打开开关后两者可同时使用。
+ */
+let watchEnabled;
+function skillWatchEnabled() {
+    if (watchEnabled === undefined) {
+        try {
+            watchEnabled = isSkillWatchEnabled();
+        }
+        catch (e) {
+            logger.warn(`[skill] 读取 skills.watch 失败，按关闭处理: ${e instanceof Error ? e.message : String(e)}`);
+            watchEnabled = false;
+        }
+    }
+    return watchEnabled;
+}
 /**
  * daemon 启动时，启动全局监控器。
  *
@@ -11,6 +33,10 @@ import { invalidateKitCache } from '../../eck/kit-renderer.js';
  * - agent 收到消息需要组装系统上下文时，检查并按需生成索引
  */
 export function startSkillWatcher() {
+    if (!skillWatchEnabled()) {
+        logger.info('[skill] 技能目录监控已关闭（daemon.json skills.watch=false），改动技能后请执行 ec skill refresh <aid>');
+        return;
+    }
     // 启动全局监控器（监控内置和本机技能目录）
     globalSkillWatcher.start();
     // 注册防抖回调：内置和本机技能变化时标记所有 agent 为脏并失效缓存
@@ -36,6 +62,8 @@ export function startSkillWatcher() {
  * 重复调用会 re-arm debounce timer 造成 2 秒自激循环。
  */
 export function watchAgentSkills(aid) {
+    if (!skillWatchEnabled())
+        return;
     globalSkillWatcher.watchAgent(aid);
     globalSkillWatcher.onDebouncedChange(`agent:${aid}`, () => {
         logger.info(`[skill] Agent ${aid} 技能目录有变化，标记为脏状态并失效缓存`);
@@ -65,6 +93,19 @@ export function ensureSkillIndexUpToDate(agentDir, aid) {
         }
     }
 }
+/**
+ * 手动刷新指定 agent 的技能索引（`ec skill refresh <aid>` 的 daemon 侧实现）。
+ *
+ * 与懒加载入口不同：无条件重建，失败直接抛出（由 IPC 返回给调用方），
+ * 成功后清掉该 agent 的脏标记，避免下一轮对话再重建一次。
+ */
+export function refreshSkillIndex(agentDir, aid) {
+    generateSkillIndexes(agentDir);
+    globalSkillWatcher.markAgentChecked(aid);
+    globalSkillWatcher.markAgentClean(aid);
+    invalidateKitCache();
+    logger.info(`[skill] 已手动刷新 agent ${aid} 的技能索引`);
+}
 /**
  * 停止全局监控器（daemon 关闭时调用）
  */