evolcore 0.0.2 → 0.0.4

package/dist/cli/trigger-command.js

@@ -2,7 +2,7 @@ import fs from 'fs';
 import path from 'path';
 import { resolvePaths } from '../paths.js';
 import { ipcQuery } from '../ipc.js';
-import { isHelpFlag } from './help.js';
+import { isHelpFlag, wantsHelp } from './help.js';
 import { AGENT_DELEGATION_TOKEN_ENV } from '../core/auth/agent-delegation.js';
 import { readTaskRuntimeContextFromEnv } from './task-context.js';
 import { normalizeTriggerDefinition, resolveScriptPath, } from '../trigger/validation.js';
@@ -12,12 +12,25 @@ export async function cmdTrigger(args) {
         printHelp();
         return;
     }
-    if (sub === 'template') {
-        handleTemplate(args.slice(1));
+    if (wantsHelp(args)) {
+        printHelp();
         return;
     }
     const rest = args.slice(1);
     const json = hasFlag(rest, '--json') || flagValue(rest, '--format') === 'json';
+    if (sub === 'template') {
+        try {
+            handleTemplate(rest);
+        }
+        catch (err) {
+            if (json)
+                console.log(JSON.stringify({ ok: false, error: err?.message || String(err) }, null, 2));
+            else
+                console.error(err?.message || String(err));
+            process.exit(1);
+        }
+        return;
+    }
     try {
         switch (sub) {
             case 'list':
@@ -30,6 +43,7 @@ export async function cmdTrigger(args) {
                 await showHistory(rest, json);
                 return;
             case 'create':
+            case 'set':
                 await createTrigger(rest, json);
                 return;
             case 'update':
@@ -69,23 +83,27 @@ function printHelp() {
   list [--agent <aid>] [--all] [--json]
   show [--agent <aid>] <triggerId> [--json]
   history [--agent <aid>] [triggerId] [--limit <n>] [--json]
-  create --file <trigger.json|trigger-dir> [--enable] [--json]
+  create --exec <script|trigger-session|target-session> --file <trigger.json|trigger-dir> [--enable] [--json]
     OR
-  create [--agent <aid>] --cron <expr>|--event <pattern> --prompt <text> [--enable] [其他flag]
+  create [--agent <aid>] --exec <script|trigger-session|target-session> --cron <expr>|--event <pattern> (--prompt <text>|--prompt-file <path>) [--enable] [其他flag]
+  set ...  (create 的兼容别名)
   update [--agent <aid>] <triggerId> <参数...> [--if-revision <sha256:...>] [--json]
   enable [--agent <aid>] <triggerId>
   disable [--agent <aid>] <triggerId>
   cancel [--agent <aid>] <triggerId>  (disable 的兼容别名)
-  delete [--agent <aid>] <triggerId>
+  delete|remove|rm [--agent <aid>] <triggerId>
   run [--agent <aid>] <triggerId> [--dry-run] [--json]
   template list|show <name> [--json]
 
 Create 参数模式支持:
   --once | --delay <时长> | --at <ISO时间> | --cron <表达式> | --every <时长> | --event <事件模式>
-  --exec <script|trigger-session|target-session>
-  --prompt <文本>
+  --exec <script|trigger-session|target-session>  (必填)
+  --prompt <文本> | --prompt-file <路径>
+    Shell 双引号内的双引号、反引号和变量形式的美元符号都需在前面加反斜杠；trigger 保存的是还原后的原文
   --script-path <路径> --script-runtime <node|python|bash>
-  --feedback <target|origin|silent> (create 参数模式仅支持 target)
+  --script-args <JSON> --script-timeout <时长>
+  --feedback <target>  (origin/silent 仅可通过 --file 导入)
+  --baseagent <name>  (仅 --exec trigger-session)
   --model <模型>  --effort <low|medium|high|xhigh|max>
   --max-runs <次数>  --max-duration <时长: 30s|15m|2h|1d>
   --permission <readonly|auto|request|bypass>（省略则继承当前身份配置）
@@ -95,14 +113,18 @@ Create 参数模式支持:
   --trigger-thread <per-run|by-trigger>
   --name <名称>
 
+通用输出参数:
+  --json | --format json
+
 Update 仅支持常用字段:
   --once | --delay | --at | --cron | --every | --event [--tz]
-  --prompt <文本>  --name <名称>
+  --prompt <文本> | --prompt-file <路径>  --name <名称>
   --model <模型>  --effort <强度>  --permission <权限模式|inherit>（inherit 清除覆盖）
   --max-runs <次数>  --max-duration <时长>
   --concurrency <forbid|replace|allow>  --missed-policy <skip|run-once|run-all>
 
-省略 --agent 时使用当前 agent AID；仅在跨身份操作或无会话上下文时需要显式指定。`);
+省略 --agent 时使用当前 agent AID；无会话上下文或跨身份操作时需要显式指定。
+任务会话中的跨身份操作仅允许目标 Agent 上具备 owner/admin 权限的调用者执行 list/show/history；创建、修改、启停、删除和运行仍只允许当前 Agent。`);
 }
 async function listTriggers(args, json) {
     const agentAid = resolveAgentAid(args);
@@ -120,7 +142,7 @@ async function listTriggers(args, json) {
 }
 async function showTrigger(args, json) {
     const agentAid = resolveAgentAid(args);
-    const triggerId = positional(args, 0, ['--agent']);
+    const triggerId = positional(args, 0, ['--agent', '--format']);
     const res = await request({ type: 'trigger.show', agentAid, triggerId });
     if (json)
         return printJson(res);
@@ -149,6 +171,8 @@ async function showTrigger(args, json) {
         console.log(`limit state: ${parts.join(', ')}`);
     }
     console.log(`execution: ${t.execution.type}`);
+    if (t.execution.type === 'trigger_session')
+        console.log(`baseagent: ${t.execution.baseagent ?? 'legacy/inherit'}`);
     if (t.execution.type === 'script')
         console.log(`script: ${scriptCommandLabel(t.execution.script)}`);
     console.log(`model: ${t.execution.model ?? 'inherit'}`);
@@ -192,10 +216,20 @@ async function showHistory(args, json) {
     }
 }
 async function createTrigger(args, json) {
-    // Support two modes: --file (full JSON) or flags (parser-based)
-    if (hasFlag(args, '--file')) {
+    if (!hasOption(args, '--exec')) {
+        throw new Error('创建 trigger 必须显式指定 --exec script|trigger-session|target-session');
+    }
+    const executionType = executionTypeFromFlag(args);
+    // --file is reserved for full trigger-definition imports.
+    if (hasOption(args, '--file')) {
+        if (hasOption(args, '--prompt-file')) {
+            throw new Error('--file（完整定义导入）与 --prompt-file（prompt 正文）不能同时指定');
+        }
         const file = requireFlag(args, '--file');
         const { definition, files } = loadDefinitionWithFiles(file);
+        if (definition.execution.type !== executionType) {
+            throw new Error(`--exec ${flagValue(args, '--exec')} 与 trigger.json 的 execution.type=${definition.execution.type} 不一致`);
+        }
         const res = await request({
             type: 'trigger.create',
             definition,
@@ -208,9 +242,12 @@ async function createTrigger(args, json) {
         return;
     }
     // Flag mode: use parser
-    const { parseTriggerSet } = await import('../trigger/parser.js');
-    const flagStr = args.filter(a => a !== '--enable' && a !== '--json' && !a.startsWith('--format')).join(' ');
-    const parseResult = parseTriggerSet(flagStr);
+    const usesPromptFile = hasOption(args, '--prompt-file');
+    if (usesPromptFile && executionType === 'script') {
+        throw new Error('--exec script 不接受 --prompt-file；请使用 --script-path 和 --script-runtime');
+    }
+    const { parseTriggerSetArgv } = await import('../trigger/parser.js');
+    const parseResult = parseTriggerSetArgv(withPromptFromFile(triggerCreateArgs(args)), { allowLongPrompt: usesPromptFile });
     if (!parseResult.ok) {
         throw new Error(parseResult.error);
     }
@@ -246,7 +283,10 @@ async function createTrigger(args, json) {
             ...(parsed.model ? { model: parsed.model } : {}),
             ...(parsed.effort ? { effort: parsed.effort } : {}),
             ...(parsed.permissionMode ? { permissionMode: parsed.permissionMode } : {}),
-            ...(parsed.executionType === 'trigger_session' ? { thread: parsed.triggerThread ?? 'by_trigger' } : {}),
+            ...(parsed.executionType === 'trigger_session' ? {
+                thread: parsed.triggerThread ?? 'by_trigger',
+                ...(parsed.baseagent ? { baseagent: parsed.baseagent } : {}),
+            } : {}),
             onError: 'retry',
             noopSentinel: '[[NOOP]]',
         },
@@ -272,6 +312,22 @@ async function createTrigger(args, json) {
         return printJson(res);
     console.log(`✓ created ${res.trigger.id} (${res.trigger.name})`);
 }
+function triggerCreateArgs(args) {
+    const out = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--enable' || arg === '--json')
+            continue;
+        if (arg === '--format') {
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith('--format='))
+            continue;
+        out.push(arg);
+    }
+    return out;
+}
 function sourceFromParsed(parsed) {
     if (parsed.scheduleType === 'once')
         return { type: 'once' };
@@ -291,6 +347,16 @@ function sourceFromParsed(parsed) {
         return { type: 'event', eventPattern: parsed.scheduleValue };
     throw new Error(`unsupported scheduleType: ${parsed.scheduleType}`);
 }
+function executionTypeFromFlag(args) {
+    const value = requireFlag(args, '--exec');
+    if (value === 'script')
+        return 'script';
+    if (value === 'trigger-session' || value === 'trigger_session')
+        return 'trigger_session';
+    if (value === 'target-session' || value === 'target_session')
+        return 'target_session';
+    throw new Error('--exec 只接受 script、trigger-session 或 target-session');
+}
 function limitsFromParsed(parsed) {
     const limits = {};
     if (parsed.maxRuns !== undefined)
@@ -322,9 +388,10 @@ function shellQuoteArg(value) {
 }
 async function updateTrigger(args, json) {
     const agentAid = resolveAgentAid(args);
-    const triggerId = positional(args, 0, ['--agent', '--format', '--if-revision']);
+    const triggerId = positional(args, 0, ['--agent', '--format', '--if-revision', '--prompt-file']);
+    const usesPromptFile = hasOption(args, '--prompt-file');
     const { parseTriggerUpdateArgv } = await import('../trigger/parser.js');
-    const parsed = parseTriggerUpdateArgv(triggerId, triggerUpdateArgs(args));
+    const parsed = parseTriggerUpdateArgv(triggerId, withPromptFromFile(triggerUpdateArgs(args)), { allowLongPrompt: usesPromptFile });
     if (!parsed.ok)
         throw new Error(parsed.error);
     const expectedRevision = flagValue(args, '--if-revision');
@@ -333,6 +400,7 @@ async function updateTrigger(args, json) {
         agentAid,
         triggerId,
         patch: parsed.value,
+        ...(usesPromptFile ? { promptFile: true } : {}),
         ...(expectedRevision ? { expectedRevision } : {}),
     }, 30_000);
     if (json)
@@ -360,9 +428,59 @@ function triggerUpdateArgs(args) {
     }
     return out;
 }
+function withPromptFromFile(args) {
+    const fileIndexes = [];
+    const filePaths = [];
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index];
+        if (arg === '--prompt-file') {
+            const value = args[index + 1];
+            if (!value || value.startsWith('--'))
+                throw new Error('missing --prompt-file');
+            fileIndexes.push(index, index + 1);
+            filePaths.push(value);
+            index += 1;
+        }
+        else if (arg.startsWith('--prompt-file=')) {
+            const value = arg.slice('--prompt-file='.length);
+            if (!value)
+                throw new Error('missing --prompt-file');
+            fileIndexes.push(index);
+            filePaths.push(value);
+        }
+    }
+    if (fileIndexes.length === 0)
+        return args;
+    if (filePaths.length > 1)
+        throw new Error('--prompt-file 只能指定一次');
+    if (hasOption(args, '--prompt'))
+        throw new Error('--prompt-file 与 --prompt 不能同时指定');
+    const filePath = filePaths[0];
+    let stat;
+    try {
+        stat = fs.statSync(filePath);
+    }
+    catch (err) {
+        throw new Error(`无法读取 prompt 文件 ${filePath}: ${err?.message || String(err)}`);
+    }
+    if (!stat.isFile())
+        throw new Error(`prompt 文件必须是普通文件: ${filePath}`);
+    let prompt;
+    try {
+        prompt = fs.readFileSync(filePath, 'utf8').replace(/^\uFEFF/, '');
+    }
+    catch (err) {
+        throw new Error(`无法读取 prompt 文件 ${filePath}: ${err?.message || String(err)}`);
+    }
+    const fileIndexSet = new Set(fileIndexes);
+    return [
+        ...args.filter((_, index) => !fileIndexSet.has(index)),
+        '--prompt', prompt,
+    ];
+}
 async function setEnabled(args, enabled, json) {
     const agentAid = resolveAgentAid(args);
-    const triggerId = positional(args, 0, ['--agent']);
+    const triggerId = positional(args, 0, ['--agent', '--format']);
     const res = await request({ type: 'trigger.setEnabled', agentAid, triggerId, enabled });
     if (json)
         return printJson(res);
@@ -370,7 +488,7 @@ async function setEnabled(args, enabled, json) {
 }
 async function cancelTrigger(args, json) {
     const agentAid = resolveAgentAid(args);
-    const triggerId = positional(args, 0, ['--agent']);
+    const triggerId = positional(args, 0, ['--agent', '--format']);
     const res = await request({ type: 'trigger.cancel', agentAid, triggerId });
     if (json)
         return printJson(res);
@@ -378,7 +496,7 @@ async function cancelTrigger(args, json) {
 }
 async function deleteTrigger(args, json) {
     const agentAid = resolveAgentAid(args);
-    const triggerId = positional(args, 0, ['--agent']);
+    const triggerId = positional(args, 0, ['--agent', '--format']);
     const res = await request({ type: 'trigger.delete', agentAid, triggerId });
     if (json)
         return printJson(res);
@@ -386,7 +504,7 @@ async function deleteTrigger(args, json) {
 }
 async function runTrigger(args, json) {
     const agentAid = resolveAgentAid(args);
-    const triggerId = positional(args, 0, ['--agent']);
+    const triggerId = positional(args, 0, ['--agent', '--format']);
     const res = await request({ type: 'trigger.run', agentAid, triggerId, dryRun: hasFlag(args, '--dry-run') }, 120_000);
     if (json)
         return printJson(res);
@@ -406,7 +524,7 @@ function handleTemplate(args) {
         return;
     }
     if (sub === 'show') {
-        const name = args.find(a => !a.startsWith('-') && a !== 'show');
+        const name = optionalPositional(args.slice(1), 0, ['--format']);
         if (!name)
             throw new Error('missing template name');
         if (json)
@@ -482,6 +600,9 @@ function flagValue(args, name) {
 function hasFlag(args, name) {
     return args.includes(name);
 }
+function hasOption(args, name) {
+    return args.includes(name) || args.some(arg => arg.startsWith(`${name}=`));
+}
 function positional(args, index, flagsWithValue) {
     const value = optionalPositional(args, index, flagsWithValue);
     if (!value)

package/dist/cli/version.js

@@ -5,6 +5,7 @@ import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import { MAIN_PACKAGE_NAME, PRODUCT_DISPLAY_NAME, WEB_PACKAGE_NAME } from '../product.js';
+import { getArgValue, wantsHelp } from './help.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PACKAGE_ROOT = path.resolve(__dirname, '../..');
 const RESET = '\x1b[0m';
@@ -44,7 +45,11 @@ function findInstalledVersion(pkgName) {
     return { name: pkg.name || pkgName, version: pkg.version || '?', buildTs: ts || undefined, path: dir };
 }
 export function handleVersion(args) {
-    const isJson = args.includes('--format') && args.includes('json') || args.includes('--json');
+    if (wantsHelp(args)) {
+        console.log(`用法: ec version [--format json|--json]\n\n显示 EvolCore、EC Web、AUN SDK、WebSocket 与 Node.js 版本。`);
+        return;
+    }
+    const isJson = getArgValue(args, '--format') === 'json' || args.includes('--json');
     // 主包
     const mainPkg = readPkgJson(PACKAGE_ROOT);
     const mainEntry = path.join(PACKAGE_ROOT, 'dist', 'cli', 'index.js');

package/dist/config/access-policy-domain.js

@@ -0,0 +1,38 @@
+import { isValidAid } from '../aun/aid/validation.js';
+export function validAgentOwnerIds(agent) {
+    return [...new Set((agent?.owners ?? [])
+            .map(value => String(value || '').trim())
+            .filter(isValidAid))];
+}
+export function configuredChannelKeys(selfAid, agent) {
+    const keys = (agent?.channels ?? [])
+        .filter(channel => channel && channel.enabled !== false)
+        .map(channel => {
+        const type = String(channel.type || '').trim().toLowerCase();
+        const name = String(channel.name || '').trim();
+        return type && name ? `${type}#${selfAid}#${name}` : '';
+    })
+        .filter(Boolean);
+    keys.push(`aun#${selfAid}#main`);
+    return [...new Set(keys)];
+}
+export function validateAccessPolicyDomain(selfAid, agent) {
+    const access = agent.access;
+    if (!access)
+        return undefined;
+    if (access.policyMode !== 'open' && validAgentOwnerIds(agent).length === 0) {
+        return {
+            code: 'restricted_mode_without_owner',
+            message: `Agent ${selfAid} cannot use ${access.policyMode} without an Owner`,
+        };
+    }
+    const configured = new Set(configuredChannelKeys(selfAid, agent));
+    const unknown = access.allowedGroupChannels.find(channelKey => !configured.has(channelKey));
+    if (unknown) {
+        return {
+            code: 'unknown_group_access_channel',
+            message: `Group access channel is not configured or enabled for ${selfAid}: ${unknown}`,
+        };
+    }
+    return undefined;
+}

package/dist/config/access-policy.js

@@ -0,0 +1,134 @@
+import crypto from 'crypto';
+import { ConfigError, ConfigTarget, mutateConfig, read, validateConfig, } from './config-manager.js';
+import { configuredChannelKeys, validAgentOwnerIds, validateAccessPolicyDomain, } from './access-policy-domain.js';
+export class AccessPolicyError extends Error {
+    code;
+    data;
+    constructor(code, message, data) {
+        super(message);
+        this.code = code;
+        this.data = data;
+        this.name = 'AccessPolicyError';
+    }
+}
+export const DEFAULT_ACCESS_POLICY = Object.freeze({
+    policyMode: 'open',
+    allowedGroupChannels: Object.freeze([]),
+    requestLimit: Object.freeze({ maxTimes: 600, coolDown: 60 * 60 }),
+});
+export function listAgentOwners(selfAid) {
+    const agent = read(ConfigTarget.Agent, { self: selfAid }, { cache: true });
+    return validAgentOwnerIds(agent);
+}
+export function listConfiguredChannelKeys(selfAid) {
+    const agent = read(ConfigTarget.Agent, { self: selfAid }, { cache: true });
+    if (!agent)
+        return [];
+    return configuredChannelKeys(selfAid, agent);
+}
+/** Missing AgentConfig.access uses the compatibility view; malformed Agent config never does. */
+export function readAccessPolicy(selfAid) {
+    return readAccessPolicySnapshot(selfAid).policy;
+}
+export function readAccessPolicySnapshot(selfAid) {
+    const agent = read(ConfigTarget.Agent, { self: selfAid }, { cache: true });
+    return accessPolicySnapshotFromAgent(selfAid, agent);
+}
+/**
+ * Atomically updates AgentConfig.access through Config Manager's file-scoped
+ * mutation path. The callback always receives the newest persisted policy.
+ */
+export function mutateAccessPolicy(input) {
+    try {
+        const result = mutateConfig(ConfigTarget.Agent, { self: input.selfAid }, agent => {
+            const current = accessPolicySnapshotFromAgent(input.selfAid, agent);
+            if (input.expectedAccessRevision !== current.accessRevision) {
+                throw new AccessPolicyError('access_policy_revision_conflict', 'Access policy changed since it was read', {
+                    expectedAccessRevision: input.expectedAccessRevision,
+                    accessRevision: current.accessRevision,
+                });
+            }
+            const next = input.update(clonePolicy(current.policy));
+            assertAccessPolicyWrite(input, agent, current.policy, next);
+            agent.access = clonePolicy(next);
+            return {
+                policy: clonePolicy(next),
+                accessRevision: accessPolicyRevision(next),
+            };
+        });
+        return { ...result.value, changed: result.changed };
+    }
+    catch (error) {
+        if (error instanceof AccessPolicyError)
+            throw error;
+        if (error instanceof ConfigError && error.code === 'LOCK_TIMEOUT') {
+            throw new AccessPolicyError('access_policy_temporarily_unavailable', 'Access policy is temporarily unavailable');
+        }
+        if (error instanceof ConfigError) {
+            throw new AccessPolicyError('invalid_access_policy', error.message);
+        }
+        throw error;
+    }
+}
+function accessPolicySnapshotFromAgent(selfAid, agent) {
+    if (!agent) {
+        throw new AccessPolicyError('invalid_access_policy', `Agent config does not exist: ${selfAid}`);
+    }
+    const errors = validateConfig(ConfigTarget.Agent, agent);
+    if (errors.length > 0) {
+        throw new AccessPolicyError('invalid_access_policy', `Invalid access policy for ${selfAid}: ${errors.join('; ')}`);
+    }
+    const issue = validateAccessPolicyDomain(selfAid, agent);
+    if (issue)
+        throw new AccessPolicyError(issue.code, issue.message);
+    const access = agent.access ?? DEFAULT_ACCESS_POLICY;
+    const policy = clonePolicy(access);
+    return { policy, accessRevision: accessPolicyRevision(policy) };
+}
+function assertAccessPolicyWrite(input, agent, current, policy) {
+    const owners = validAgentOwnerIds(agent);
+    const normalizedActorAid = String(input.actorAid || '').trim();
+    const isOwner = input.actorRole === 'owner' || owners.includes(normalizedActorAid);
+    const isGroupChannelAdmin = input.actorRole === 'admin' && input.resource === 'access.allowedGroupChannels';
+    if (!isOwner && !isGroupChannelAdmin) {
+        if (input.resource === 'access.allowedGroupChannels') {
+            throw new AccessPolicyError('access_policy_manager_required', 'Only an Agent Owner or Admin can change allowed group channels');
+        }
+        throw new AccessPolicyError('access_policy_owner_required', 'Only an Agent Owner can change access policy');
+    }
+    if (isGroupChannelAdmin) {
+        if (current.policyMode !== policy.policyMode
+            || current.requestLimit.maxTimes !== policy.requestLimit.maxTimes
+            || current.requestLimit.coolDown !== policy.requestLimit.coolDown) {
+            throw new AccessPolicyError('access_policy_owner_required', 'An Agent Admin may only change allowed group channels');
+        }
+    }
+    if (policy.policyMode !== 'open' && owners.length === 0) {
+        throw new AccessPolicyError('restricted_mode_without_owner', `Agent ${input.selfAid} cannot use ${policy.policyMode} without an Owner`);
+    }
+    const configured = new Set(configuredChannelKeys(input.selfAid, agent));
+    const unknown = policy.allowedGroupChannels.find(channelKey => !configured.has(channelKey));
+    if (unknown) {
+        throw new AccessPolicyError('unknown_group_access_channel', `Group access channel is not configured or enabled for ${input.selfAid}: ${unknown}`);
+    }
+}
+function clonePolicy(policy) {
+    return {
+        policyMode: policy.policyMode,
+        allowedGroupChannels: [...policy.allowedGroupChannels],
+        requestLimit: { ...policy.requestLimit },
+    };
+}
+function accessPolicyRevision(policy) {
+    return `sha256:${crypto.createHash('sha256').update(stableStringify(policy)).digest('hex')}`;
+}
+function stableStringify(value) {
+    return JSON.stringify(sortValue(value));
+}
+function sortValue(value) {
+    if (Array.isArray(value))
+        return value.map(sortValue);
+    if (!value || typeof value !== 'object')
+        return value;
+    return Object.fromEntries(Object.keys(value).sort().map(key => [key, sortValue(value[key])]));
+}

package/dist/config/builtin-role-templates.js

@@ -1,30 +1,55 @@
-import fs from 'fs';
 import path from 'path';
 import { kitsRoleTemplatesDir } from '../paths.js';
+import { createErrorCapturingReader, fileCache } from '../core/daemon-file-cache.js';
 import { validateRoleConfig } from './role-schema.js';
+import { expectedRoleRank } from './role-ranks.js';
 export const BUILTIN_ROLE_IDS = ['owner', 'admin', 'member', 'visitor'];
-/** Load the versioned package template that defines a built-in role policy. */
-export function readBuiltinRoleTemplate(roleId) {
-    const file = path.join(kitsRoleTemplatesDir(), `${roleId}.json`);
-    let raw;
-    try {
-        raw = JSON.parse(fs.readFileSync(file, 'utf8'));
-    }
-    catch (error) {
-        return {
-            definition: null,
-            file,
-            error: `cannot read built-in role template: ${error instanceof Error ? error.message : String(error)}`,
-        };
-    }
+export function validateBuiltinRoleTemplateDefinition(roleId, raw) {
     const issues = validateRoleConfig(raw);
     if (issues.length) {
         return {
             definition: null,
-            file,
             error: `built-in role template failed validation: ${issues.map(issue => `${issue.field} ${issue.message}`).join('; ')}`,
         };
     }
     const { $schema_version: _schemaVersion, ...definition } = raw;
-    return { definition: definition, file };
+    if (BUILTIN_ROLE_IDS.includes(roleId)) {
+        const expectedRank = expectedRoleRank(roleId);
+        if (definition.rank !== expectedRank) {
+            return {
+                definition: null,
+                error: `built-in role template rank must be ${expectedRank}`,
+            };
+        }
+    }
+    return { definition: definition };
+}
+/**
+ * Load the versioned package template that defines a built-in role policy.
+ *
+ * 模板随包发布、只靠进程重启或 kit 缓存失效刷新 → fileCache 的 on-reload 策略，
+ * 归入 'kits' 组。缓存的是"读盘 + JSON.parse"结果；校验（validateRoleConfig）仍每次现做。
+ */
+export function readBuiltinRoleTemplate(roleId) {
+    const file = path.join(kitsRoleTemplatesDir(), `${roleId}.json`);
+    // 默认 reader 会把所有读盘异常吞成 null（分不清 ENOENT 与 EACCES），
+    // 这里注入带错误捕获的 reader 把真实错误原文带出来，保持与直读时一致的报错。
+    const reader = createErrorCapturingReader();
+    const parsed = fileCache.get(file, (text) => {
+        if (text === null) {
+            return { error: `cannot read built-in role template: ${reader.lastError()}` };
+        }
+        try {
+            return { raw: JSON.parse(text) };
+        }
+        catch (error) {
+            return { error: `cannot read built-in role template: ${error instanceof Error ? error.message : String(error)}` };
+        }
+    }, { policy: 'on-reload', group: 'kits', read: reader.read });
+    if ('error' in parsed)
+        return { definition: null, file, error: parsed.error };
+    // 缓存返回的是同一个对象引用，而 validateBuiltinRoleTemplateDefinition 里的解构
+    // 只隔离顶层——permissions / commandPermissions / usageLimits 等嵌套对象仍会被
+    // 所有调用方共享，任何一处改写都会污染后续读者拿到的授权策略。整份深拷贝后再校验。
+    return { ...validateBuiltinRoleTemplateDefinition(roleId, structuredClone(parsed.raw)), file };
 }