evolcore 0.0.1 → 0.0.3

package/dist/core/message/response-snapshot.js

@@ -0,0 +1,83 @@
+/**
+ * 响应模式迁移：行为快照探针
+ *
+ * 用途：迁移前后对比 message-processor 的实际行为是否逐字节一致（防线 1）。
+ *
+ * 设计：
+ *   - 按 (sessionId, taskId) 聚合一条快照，任务处理过程中逐步填充字段
+ *   - 任务结束时落盘到 $EVOLCORE_HOME/data/eck-debug/response-snapshots.jsonl
+ *   - 零侵入：探针关闭时所有方法是 no-op，不影响行为
+ *   - 仅记录「模式特有决策点」的输入输出，不记录消息内容（隐私 + 体积）
+ *
+ * 开关：进程级 debug.eckSnapshots 总闸开启，且 RESPONSE_SNAPSHOT=1 时启用。
+ */
+import fs from 'fs';
+import path from 'path';
+import { isEckSnapshotsEnabled } from '../../config-store.js';
+import { eckDebugDir } from '../../paths.js';
+import { appendJsonl } from '../session/session-fs-store.js';
+import { logger } from '../../utils/logger.js';
+// 动态检查环境变量（而非模块级常量）
+function isEnabled() {
+    return isEckSnapshotsEnabled() && process.env.RESPONSE_SNAPSHOT === '1';
+}
+class SnapshotRecorder {
+    /** (sessionId::taskId) → 进行中的快照 */
+    active = new Map();
+    key(sessionId, taskId) {
+        return `${sessionId}::${taskId}`;
+    }
+    getOutPath() {
+        const dir = eckDebugDir();
+        fs.mkdirSync(dir, { recursive: true });
+        return path.join(dir, 'response-snapshots.jsonl');
+    }
+    /** 开始一条快照（beforeProcess 阶段调用） */
+    begin(sessionId, taskId, source, msgId) {
+        if (!isEnabled())
+            return;
+        this.active.set(this.key(sessionId, taskId), {
+            ts: Date.now(), sessionId, taskId, source, msgId,
+        });
+    }
+    /** 填充字段（处理过程中逐步调用） */
+    set(sessionId, taskId, patch) {
+        if (!isEnabled())
+            return;
+        const snap = this.active.get(this.key(sessionId, taskId));
+        if (snap)
+            Object.assign(snap, patch);
+    }
+    /** 向数组字段追加（outbound 等） */
+    pushOutbound(sessionId, taskId, entry) {
+        if (!isEnabled())
+            return;
+        const snap = this.active.get(this.key(sessionId, taskId));
+        if (!snap)
+            return;
+        if (!snap.outbound)
+            snap.outbound = [];
+        snap.outbound.push(entry);
+    }
+    /** 结束并落盘（任务收尾时调用） */
+    end(sessionId, taskId) {
+        if (!isEnabled())
+            return;
+        const k = this.key(sessionId, taskId);
+        const snap = this.active.get(k);
+        if (!snap)
+            return;
+        this.active.delete(k);
+        try {
+            appendJsonl(this.getOutPath(), snap);
+        }
+        catch (e) {
+            logger.debug(`[snapshot] write failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    isEnabled() {
+        return isEnabled();
+    }
+}
+/** 全局单例探针 */
+export const snapshot = new SnapshotRecorder();

package/dist/core/message/send-receipt.js

@@ -0,0 +1,24 @@
+export function sendOperationId(envelope) {
+    return envelope.operationId || envelope.taskId;
+}
+export function sentReceipt(envelope, messageIds, threadId) {
+    const messages = messageIds
+        .filter((messageId) => typeof messageId === 'string' && messageId.length > 0)
+        .map((messageId, partIndex) => ({ messageId, partIndex, threadId }));
+    if (messages.length === 0) {
+        throw new Error(`MISSING_MESSAGE_ID: operation=${sendOperationId(envelope)}`);
+    }
+    return {
+        status: 'sent',
+        operationId: sendOperationId(envelope),
+        messages: messages,
+    };
+}
+export function suppressedReceipt(envelope, reason) {
+    return {
+        status: 'suppressed',
+        operationId: sendOperationId(envelope),
+        messages: [],
+        reason,
+    };
+}

package/dist/core/message/stream-debouncer.js

@@ -0,0 +1,139 @@
+import { logger } from '../../utils/logger.js';
+/**
+ * 入站消息去抖器
+ *
+ * 在 debounceMs 窗口内收到的同一 session 的多条消息合并为一次 enqueue：
+ * - content 用 \n 连接
+ * - images / mentions 合并
+ * - replyContext / 其余字段取最后一条
+ *
+ * cancel(messageId) 可精确移除窗口中的某条消息，不影响其余消息。
+ */
+export class StreamDebouncer {
+    pending = new Map();
+    delayMs;
+    maxWaitMs;
+    maxMessages;
+    constructor(debounceSeconds, maxMessages = 5) {
+        this.delayMs = debounceSeconds * 1000;
+        this.maxWaitMs = this.delayMs * 3;
+        this.maxMessages = maxMessages;
+    }
+    get enabled() {
+        return this.delayMs > 0;
+    }
+    /**
+     * 提交一条消息。如果窗口内已有消息则追加并重置 timer；
+     * 否则新建窗口。timer 到期后自动 flush。
+     */
+    submit(key, message, enqueue) {
+        const { content, images, mentions, messageId, sourceMessageIds, replyContext, ...rest } = message;
+        return new Promise((resolve, reject) => {
+            const entry = { messageId, sourceMessageIds, content, images, mentions, replyContext, rest, resolve, reject };
+            const win = this.pending.get(key);
+            if (win) {
+                clearTimeout(win.timer);
+                win.entries.push(entry);
+                if (win.entries.length >= this.maxMessages) {
+                    logger.debug(`[Debounce] Max messages (${this.maxMessages}) reached for ${key}, flushing immediately`);
+                    clearTimeout(win.maxWaitTimer);
+                    this.flush(key, enqueue);
+                    return;
+                }
+                win.timer = setTimeout(() => this.flush(key, enqueue), this.delayMs);
+                logger.debug(`[Debounce] Appended message for ${key}, ${win.entries.length} pending`);
+            }
+            else {
+                const timer = setTimeout(() => this.flush(key, enqueue), this.delayMs);
+                const maxWaitTimer = setTimeout(() => this.flush(key, enqueue), this.maxWaitMs);
+                this.pending.set(key, { entries: [entry], timer, maxWaitTimer });
+                logger.debug(`[Debounce] New window for ${key}, debounce=${this.delayMs}ms, maxWait=${this.maxWaitMs}ms`);
+            }
+        });
+    }
+    /**
+     * 从 debounce 窗口中撤回指定 messageId 的消息。
+     * 如果窗口只剩这一条，整个窗口取消。
+     * @returns true 如果找到并移除
+     */
+    cancel(messageId) {
+        for (const [key, win] of this.pending) {
+            const idx = win.entries.findIndex(e => e.messageId === messageId);
+            if (idx === -1)
+                continue;
+            // resolve 被撤回的那条（静默完成，不报错）
+            win.entries.splice(idx, 1)[0].resolve();
+            logger.info(`[Debounce] Cancelled message ${messageId} from window ${key}`);
+            // 窗口空了 → 整个取消
+            if (win.entries.length === 0) {
+                clearTimeout(win.timer);
+                clearTimeout(win.maxWaitTimer);
+                this.pending.delete(key);
+                logger.info(`[Debounce] Window ${key} empty after cancel, removed`);
+            }
+            return true;
+        }
+        return false;
+    }
+    flush(key, enqueue) {
+        const win = this.pending.get(key);
+        if (!win)
+            return;
+        this.pending.delete(key);
+        clearTimeout(win.timer);
+        clearTimeout(win.maxWaitTimer);
+        const { entries } = win;
+        // 合并：content 用 \n 连接，images/mentions 扁平合并，其余取最后一条
+        const allImages = [];
+        const allMentions = [];
+        const contents = [];
+        const sourceMessageIds = [];
+        const seenSourceMessageIds = new Set();
+        for (const e of entries) {
+            contents.push(e.content);
+            if (e.images)
+                allImages.push(...e.images);
+            if (e.mentions)
+                allMentions.push(...e.mentions);
+            for (const id of [...(e.sourceMessageIds ?? []), ...(e.messageId ? [e.messageId] : [])]) {
+                if (!seenSourceMessageIds.has(id)) {
+                    seenSourceMessageIds.add(id);
+                    sourceMessageIds.push(id);
+                }
+            }
+        }
+        const last = entries[entries.length - 1];
+        // 合并后保留最新一条的 messageId（用于 thought 锚定与中断追踪）
+        let latestMessageId;
+        for (let i = entries.length - 1; i >= 0; i--) {
+            if (entries[i].messageId) {
+                latestMessageId = entries[i].messageId;
+                break;
+            }
+        }
+        const merged = {
+            ...last.rest,
+            content: contents.join('\n'),
+            images: allImages.length > 0 ? allImages : undefined,
+            mentions: allMentions.length > 0 ? allMentions : undefined,
+            replyContext: last.replyContext,
+            messageId: latestMessageId,
+            sourceMessageIds: sourceMessageIds.length > 0 ? sourceMessageIds : undefined,
+        };
+        const resolves = entries.map(e => e.resolve);
+        const rejects = entries.map(e => e.reject);
+        enqueue(merged).then(() => resolves.forEach(r => r()), (e) => rejects.forEach(r => r(e)));
+    }
+    /** 当前挂起的 key 数量（用于测试/调试） */
+    get pendingCount() {
+        return this.pending.size;
+    }
+    /** 清理所有挂起的 timer（用于 shutdown） */
+    dispose() {
+        for (const win of this.pending.values()) {
+            clearTimeout(win.timer);
+            clearTimeout(win.maxWaitTimer);
+        }
+        this.pending.clear();
+    }
+}

package/dist/core/message/stream-idle-monitor.js

@@ -0,0 +1,124 @@
+/**
+ * 事件流空闲监控器
+ * 记录事件流执行上下文，分级响应空闲状态
+ */
+// 分级倍率
+const NOTIFY_MULTIPLIER = 1; // 1× idleMs
+const WARN_MULTIPLIER = 2.5; // 2.5× idleMs
+const KILL_MULTIPLIER = 5; // 5× idleMs
+export class StreamIdleMonitor {
+    state;
+    triggeredLevels = new Set();
+    idleMs;
+    paused = false;
+    constructor(idleMs) {
+        this.idleMs = idleMs;
+        this.state = {
+            lastEventType: '',
+            lastEventTime: Date.now(),
+            lastToolName: undefined,
+            lastToolStartTime: undefined,
+            totalEvents: 0,
+            totalToolCalls: 0,
+            hasReceivedText: false,
+        };
+    }
+    /**
+     * 暂停空闲计时（等待用户交互期间调用，如权限确认 / AskUserQuestion / PlanMode）。
+     * 暂停期间 check() 始终返回 null，等待时长不计入 idle。
+     */
+    pause() {
+        this.paused = true;
+    }
+    /**
+     * 恢复空闲计时。从恢复时刻重新起算 idle，并清空已触发级别——
+     * 用户应答后是一次全新的执行周期，不应继承等待前的 idle 状态。
+     */
+    resume() {
+        if (!this.paused)
+            return;
+        this.paused = false;
+        this.state.lastEventTime = Date.now();
+        this.triggeredLevels.clear();
+    }
+    /**
+     * 记录 SDK 事件，更新状态并重置空闲计时
+     */
+    recordEvent(type, toolName) {
+        this.state.lastEventType = type;
+        this.state.lastEventTime = Date.now();
+        this.state.totalEvents++;
+        if (toolName) {
+            this.state.lastToolName = toolName;
+            this.state.lastToolStartTime = Date.now();
+            this.state.totalToolCalls++;
+        }
+        if (type === 'text' || type === 'text_delta' || type === 'complete' || type === 'result') {
+            this.state.hasReceivedText = true;
+        }
+        // 收到新事件，重置已触发级别
+        this.triggeredLevels.clear();
+    }
+    /**
+     * 检查空闲状态，返回 null（未空闲）或分级结果
+     */
+    check() {
+        if (this.paused)
+            return null;
+        const now = Date.now();
+        const idleDuration = now - this.state.lastEventTime;
+        const notifyThreshold = this.idleMs * NOTIFY_MULTIPLIER;
+        const warnThreshold = this.idleMs * WARN_MULTIPLIER;
+        const killThreshold = this.idleMs * KILL_MULTIPLIER;
+        // Check from lowest to highest — return first untriggered level
+        if (idleDuration >= notifyThreshold && !this.triggeredLevels.has('notify')) {
+            this.triggeredLevels.add('notify');
+            return {
+                action: 'notify',
+                idleSec: Math.round(idleDuration / 1000),
+                state: { ...this.state },
+                message: this.buildMessage('notify', idleDuration),
+            };
+        }
+        if (idleDuration >= warnThreshold && !this.triggeredLevels.has('warn')) {
+            this.triggeredLevels.add('warn');
+            return {
+                action: 'warn',
+                idleSec: Math.round(idleDuration / 1000),
+                state: { ...this.state },
+                message: this.buildMessage('warn', idleDuration),
+            };
+        }
+        if (idleDuration >= killThreshold && !this.triggeredLevels.has('kill')) {
+            this.triggeredLevels.add('kill');
+            return {
+                action: 'kill',
+                idleSec: Math.round(idleDuration / 1000),
+                state: { ...this.state },
+                message: this.buildMessage('kill', idleDuration),
+            };
+        }
+        return null;
+    }
+    /**
+     * 获取当前执行状态快照
+     */
+    getState() {
+        return { ...this.state };
+    }
+    buildMessage(action, idleDuration) {
+        const idleSec = Math.round(idleDuration / 1000);
+        const lastToolInfo = this.state.lastToolName
+            ? `🔧 ${this.state.lastToolName}`
+            : '无工具调用';
+        const timeSinceLastEvent = idleSec;
+        if (action === 'kill') {
+            return `🛑 执行超时（${idleSec}秒无响应），已自动中断\n\n执行状态：\n- 已处理 ${this.state.totalEvents} 个事件，${this.state.totalToolCalls} 次工具调用\n- 最后活动：${lastToolInfo}（${timeSinceLastEvent}秒前）`;
+        }
+        if (action === 'warn') {
+            return `⚠️ 执行监控：已 ${idleSec} 秒无输出\n\n执行状态：\n- 已处理 ${this.state.totalEvents} 个事件，${this.state.totalToolCalls} 次工具调用\n- 最后活动：${lastToolInfo}（${timeSinceLastEvent}秒前）\n\n如果持续无响应，将在 ${Math.round((this.idleMs * KILL_MULTIPLIER - idleDuration) / 1000)} 秒后自动中断。\n使用 /stop 可立即中断当前任务。`;
+        }
+        // notify
+        return `🔍 执行监控：已 ${idleSec} 秒无输出\n\n执行状态：\n- 已处理 ${this.state.totalEvents} 个事件，${this.state.totalToolCalls} 次工具调用\n- 最后活动：${lastToolInfo}（${timeSinceLastEvent}秒前）\n\n仍在运行中。使用 /stop 可中断当前任务。`;
+    }
+}

package/dist/core/model/config-scope.js

@@ -0,0 +1,162 @@
+/**
+ * config-scope: model/effort 的多作用域读写，以及角色 permissionMode 解析。
+ *
+ * 所有参数统一在 config.json。
+ * 存储经 ConfigManager（全项目唯一合并实现点）。本模块是面向 CLI / 运行时的薄封装：
+ * 把"作用域 + baseagent"语义映射到 config 链的读写。
+ *
+ * model/effort 作用域（越具体越优先）：关系 > 角色 > agent。
+ *   agent  agents/<self>/config.json                          → baseagents.<ba>.{model,effort}
+ *   角色   agents/<self>/config.json 的 roles.definitions 块   → model 白名单/默认值
+ *   关系   agents/<self>/relations/<peerKey>/config.json       → baseagents
+ *   global（历史保留）：全局 model 作用域已退场，只读 agent 兜底。
+ *
+ * 改任一作用域后，对应范围所有会话的下一条消息即时生效（运行时每条消息解析，不缓存）。
+ *
+ * 详见 docs/config/
+ */
+import { formatPeerKey, parsePeerKey } from '../relation/peer-identity.js';
+import { ConfigTarget, read, write, ensureFile, } from '../../config/config-manager.js';
+import { resolveRuntimePermissionMode } from '../role/runtime-policy.js';
+export class ModelScopeError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'ModelScopeError';
+    }
+}
+// ── peer 归一化 ────────────────────────────────────────────────────────
+/**
+ * 把 `--peer` 入参归一为规范 peerKey。
+ *   - `channelType#channelId`（统一 round-trip 重编码）
+ *   - 裸 aid（无 '#'）→ 视为 `aun#<aid>`
+ */
+export function normalizePeer(input) {
+    const raw = (input || '').trim();
+    if (!raw)
+        throw new ModelScopeError('INVALID_PEER', '--peer 不能为空');
+    if (raw.includes('#')) {
+        let parsed;
+        try {
+            parsed = parsePeerKey(raw);
+        }
+        catch {
+            throw new ModelScopeError('INVALID_PEER', `无法解析 --peer: ${raw}`);
+        }
+        if (!parsed.channelType || !parsed.channelId) {
+            throw new ModelScopeError('INVALID_PEER', `无法解析 --peer: ${raw}`);
+        }
+        return formatPeerKey(parsed.channelType, parsed.channelId);
+    }
+    return formatPeerKey('aun', raw);
+}
+// ── 作用域判定（CLI 写入目标）─────────────────────────────────────────────
+/**
+ * 由选择器判定**写入目标**作用域。依赖：peerKey/role 须配 self。
+ */
+export function determineScope(sel) {
+    const hasSelf = !!sel.self;
+    if (sel.peerKey && !hasSelf)
+        throw new ModelScopeError('PEER_WITHOUT_SELF', '--peer 必须配合 --self 使用');
+    if (sel.role && !hasSelf)
+        throw new ModelScopeError('ROLE_WITHOUT_SELF', '--role 必须配合 --self 使用');
+    if (sel.peerKey)
+        return 'relation';
+    if (sel.role)
+        return 'role';
+    if (hasSelf)
+        return 'agent';
+    return 'global';
+}
+// ── baseagent 解析 ───────────────────────────────────────────────────────
+/** 取本端的活跃 baseagent（从 agent/config 读 active_baseagent）；缺省 'claude'。 */
+export function activeBaseagent(self) {
+    try {
+        if (self) {
+            const b = read(ConfigTarget.Agent, { self }, { cache: true });
+            if (b?.active_baseagent)
+                return b.active_baseagent;
+        }
+    }
+    catch { /* fall through */ }
+    return 'claude';
+}
+/** codex 的推理强度字段名是 reasoning，其余是 effort。 */
+function effortField(ba) {
+    return ba === 'codex' ? 'reasoning' : 'effort';
+}
+// ── 写：单作用域 ──────────────────────────────────────────────────────
+/** 写入指定作用域。patch 中 undefined 不动；显式 null 删除字段。 */
+export function writeScope(scope, sel, ba, patch) {
+    const ef = effortField(ba);
+    if (scope === 'global') {
+        throw new ModelScopeError('NO_GLOBAL_SCOPE', '全局 model 作用域已退场：请用 --self 逐 agent 设置');
+    }
+    if (scope === 'agent') {
+        requireSelf(sel);
+        const target = ConfigTarget.Agent;
+        const cur = read(target, { self: sel.self }) || {};
+        applyBaPatch(cur, ba, ef, patch);
+        ensureFile(target, { self: sel.self });
+        write(target, cur, { self: sel.self });
+        return;
+    }
+    if (scope === 'role') {
+        throw new ModelScopeError('ROLE_POLICY_MANAGED', '角色模型策略只能通过角色策略编辑器修改');
+    }
+    // relation
+    requirePeer(sel);
+    const target = ConfigTarget.Relation;
+    const selr = { self: sel.self, peerKey: sel.peerKey };
+    const cur = read(target, selr) || {};
+    applyBaPatch(cur, ba, ef, patch);
+    ensureFile(target, selr);
+    write(target, cur, selr);
+}
+function applyBaPatch(cfg, ba, ef, patch) {
+    cfg.baseagents = cfg.baseagents || {};
+    applyBaPatchTo(cfg.baseagents, ba, ef, patch);
+}
+function applyBaPatchTo(block, ba, ef, patch) {
+    block[ba] = block[ba] || {};
+    const sub = block[ba];
+    if (patch.model === null)
+        delete sub.model;
+    else if (patch.model !== undefined)
+        sub.model = patch.model;
+    if (patch.effort === null)
+        delete sub[ef];
+    else if (patch.effort !== undefined)
+        sub[ef] = patch.effort;
+}
+// ── 清除：单作用域 ────────────────────────────────────────────────────
+/** 清除指定作用域的 model+effort。 */
+export function clearScope(scope, sel, ba) {
+    if (scope === 'global')
+        return;
+    writeScope(scope, sel, ba, { model: null, effort: null });
+}
+// ── permissionMode 解析 ────────────────────────────────────────────────────
+const FALLBACK_PERMISSION_MODE = 'readonly';
+/**
+ * 解析实际生效的 permissionMode。不抛出——运行时 per-message 调用。
+ * permissionMode 只来自角色定义；缺失或未知角色安全回退 readonly。
+ */
+export function resolvePermissionMode(sel) {
+    try {
+        return resolveRuntimePermissionMode({ selfAid: sel.self, role: sel.role }).effectiveValue;
+    }
+    catch {
+        return FALLBACK_PERMISSION_MODE;
+    }
+}
+// ── helpers ──────────────────────────────────────────────────────────────────
+function requireSelf(sel) {
+    if (!sel.self)
+        throw new ModelScopeError('AGENT_NOT_FOUND', 'agent 作用域需要 --self');
+}
+function requirePeer(sel) {
+    if (!sel.self || !sel.peerKey)
+        throw new ModelScopeError('PEER_WITHOUT_SELF', '关系作用域需要 --self + --peer');
+}

package/dist/core/model/field-scope.js

@@ -0,0 +1,78 @@
+/**
+ * field-scope: 顶层配置字段的多作用域读写（通用框架）。
+ *
+ * 与 config-scope.ts（model 专用，处理 baseagents/roles 嵌套结构）互补：
+ *   - config-scope：model/effort → config.json / relation config.json 的嵌套结构
+ *   - field-scope：顶层字段（如 responseMode / responseModeParams）→ config.json（H 链）
+ *
+ * 复用 config-scope 的作用域判定与 peer 归一化（同一套语义，不重复造）。
+ *
+ * 作用域（越具体越优先）：关系 > agent > 全局(defaults)。
+ *   defaults  agents/defaults.json
+ *   agent     agents/<self>/config.json
+ *   relation  agents/<self>/relations/<peerKey>/config.json
+ *
+ * 读写单个顶层字段：read-modify-write（整文件读出 → 改字段 → 写回，带 schema 校验）。
+ * 改任一作用域后，对应范围所有会话的下一条消息即时生效（运行时每条消息解析）。
+ */
+import { ConfigTarget, read, write } from '../../config/config-manager.js';
+import { normalizePeer, determineScope, ModelScopeError } from './config-scope.js';
+/** 把 ScopeSelector 映射到 FieldScope；角色策略必须走专用编辑器。 */
+export function determineFieldScope(sel) {
+    const scope = determineScope(sel);
+    if (scope === 'global')
+        return 'defaults';
+    if (scope === 'role')
+        throw new ModelScopeError('ROLE_POLICY_MANAGED', '角色策略只能通过角色策略编辑器修改');
+    return scope; // 'agent' | 'relation'
+}
+/** scope → ConfigTarget */
+function targetFor(scope) {
+    switch (scope) {
+        case 'defaults': return ConfigTarget.Defaults;
+        case 'agent': return ConfigTarget.Agent;
+        case 'relation': return ConfigTarget.Relation;
+    }
+}
+/**
+ * 读取指定作用域的某个顶层字段（未设返回 undefined）。不抛出。
+ */
+export function readField(scope, sel, field) {
+    try {
+        const target = targetFor(scope);
+        const cfg = read(target, sel, { cache: true });
+        return cfg ? cfg[field] : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * 写入指定作用域的某个顶层字段（read-modify-write，带 schema 校验）。
+ * value 为 undefined 时删除该字段。
+ */
+export function writeField(scope, sel, field, value) {
+    if (scope === 'agent' && !sel.self) {
+        throw new ModelScopeError('SELF_REQUIRED', 'agent 作用域必须提供 --self');
+    }
+    if (scope === 'relation' && (!sel.self || !sel.peerKey)) {
+        throw new ModelScopeError('PEER_WITHOUT_SELF', 'relation 作用域必须提供 --self 和 --peer');
+    }
+    const target = targetFor(scope);
+    const cur = (read(target, sel) || {});
+    if (value === undefined) {
+        delete cur[field];
+    }
+    else {
+        cur[field] = value;
+    }
+    write(target, cur, sel);
+}
+/**
+ * 清除指定作用域的某个顶层字段（等价于 writeField(..., undefined)）。
+ */
+export function clearField(scope, sel, field) {
+    writeField(scope, sel, field, undefined);
+}
+// re-export 复用 config-scope 的 peer 归一化（同一套语义）
+export { normalizePeer, ModelScopeError };