evolcore 0.0.11 → 0.0.13

package/dist/agents/ecagent-runner.js

@@ -9,6 +9,7 @@ import { requestDangerousCommandPermission } from '../core/permission/approval-g
 import { normalizePermissionMode } from '../core/permission/mode.js';
 import { checkDangerousCommand, checkReadonly, evaluateToolPreflight } from '../core/permission/tool-policy.js';
 import { logger } from '../utils/logger.js';
+import { summarizeToolInputForAudit } from '../utils/tool-summary.js';
 import { resolveEcagentConfig } from './baseagent.js';
 import { buildModelRequestHeaders } from './request-identity.js';
 const PROVIDER_ID = 'evolcore-gateway';
@@ -957,9 +958,31 @@ export class EcagentRunner {
     }
     async authorizeTool(sessionId, projectPath, mode, toolName, input) {
         const permissionContext = this.permissionContexts.get(sessionId);
+        const recordBlockedOperation = async (policyCode, operationInput = input) => {
+            try {
+                await permissionContext?.recordExecutionAnomaly?.({
+                    code: 'operation_blocked',
+                    severity: 'warning',
+                    phase: 'execution',
+                    occurredAt: Date.now(),
+                    toolName,
+                    policyCode,
+                    decisionSource: 'policy',
+                    agentAid: permissionContext?.selfAid,
+                    permissionMode: mode,
+                    summary: summarizeToolInputForAudit(toolName, operationInput).slice(0, 512),
+                    effect: 'operation_skipped',
+                });
+            }
+            catch (error) {
+                logger.warn(`[EcagentRunner] failed to record blocked operation: session=${sessionId} tool=${toolName} code=${policyCode} error=${error instanceof Error ? error.message : String(error)}`);
+            }
+        };
         const policy = permissionContext?.policyHook?.(toolName, input);
-        if (policy?.block)
+        if (policy?.block) {
+            await recordBlockedOperation(policy.policyCode ?? 'session_policy_hook');
             return { block: true, reason: policy.reason || '当前会话策略拒绝此工具调用' };
+        }
         const preflight = evaluateToolPreflight(toolName, input, {
             sessionId,
             selfAid: permissionContext?.selfAid,
@@ -969,8 +992,12 @@ export class EcagentRunner {
             permissionMode: mode,
             projectPath,
         });
-        if (preflight.behavior === 'deny')
+        if (preflight.behavior === 'deny') {
+            if (preflight.policyCode) {
+                await recordBlockedOperation(preflight.policyCode, input);
+            }
             return { block: true, reason: preflight.message };
+        }
         if (preflight.behavior === 'allow')
             return {};
         const checkedInput = preflight.input;
@@ -978,11 +1005,19 @@ export class EcagentRunner {
             const decision = checkReadonly(toolName, checkedInput, projectPath, {
                 sessionId, channel: permissionContext?.channel, peerId: permissionContext?.userId, role: permissionContext?.role,
             });
-            return decision.behavior === 'deny' ? { block: true, reason: decision.message } : {};
+            if (decision.behavior === 'deny') {
+                await recordBlockedOperation(decision.policyCode ?? 'readonly_mode', checkedInput);
+                return { block: true, reason: decision.message };
+            }
+            return {};
         }
         const dangerous = checkDangerousCommand(toolName, checkedInput);
         if (mode === 'auto') {
-            return dangerous.isDangerous ? { block: true, reason: `危险操作已由 auto 模式拒绝：${dangerous.reason}` } : {};
+            if (dangerous.isDangerous) {
+                await recordBlockedOperation('auto_dangerous_command', checkedInput);
+                return { block: true, reason: `危险操作已由 auto 模式拒绝：${dangerous.reason}` };
+            }
+            return {};
         }
         const prompt = permissionContext?.sendPrompt ?? this.sendPromptFn;
         const decision = await requestDangerousCommandPermission(this.permissionGateway, sessionId, toolName, checkedInput, prompt, permissionContext, `ecagent:${mode}`, mode);

package/dist/agents/gemini-runner.js

@@ -344,6 +344,7 @@ export class GeminiRunner {
             cwd: projectPath,
             stdio: ['pipe', 'pipe', 'pipe'],
             env,
+            windowsHide: process.platform === 'win32',
         });
         this.activeProcesses.set(sessionId, child);
         // Log stderr

package/dist/aun/aid/client.js

@@ -1,8 +1,6 @@
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
-import { execFileSync } from 'child_process';
-import { isWindows } from '../../utils/cross-platform.js';
 /**
  * Suppress SDK console logs (DEBUG/INFO/WARN) in CLI context.
  * Call once at CLI entry point — NOT at module load time, to avoid
@@ -40,10 +38,9 @@ export function suppressSdkLogs() {
         return _origStderrWrite(chunk, encoding, callback);
     };
 }
-// ==================== Constants ====================
-export const MIN_AUN_CORE_SDK = [0, 4, 3];
+// ==================== SDK package ====================
+export const MIN_AUN_CORE_SDK = [0, 5, 6];
 export const AUN_CORE_SDK_PKG = '@agentunion/fastaun';
-// ==================== SDK & Environment ====================
 function compareVersion(a, min) {
     const parts = a.split('.').map(n => parseInt(n, 10));
     if (parts.length < 3 || parts.some(isNaN))
@@ -57,6 +54,7 @@ function compareVersion(a, min) {
 export function isAunSdkVersionOk(version) {
     return compareVersion(version, MIN_AUN_CORE_SDK);
 }
+/** Resolve only the SDK bundled in EvolCore's own dependency tree. */
 export function resolveAunCoreSdkPkg() {
     try {
         let dir = path.dirname(fileURLToPath(import.meta.url));
@@ -73,28 +71,20 @@ export function resolveAunCoreSdkPkg() {
             dir = parent;
         }
     }
-    catch { /* fall through */ }
-    try {
-        const npmCmd = isWindows ? 'npm.cmd' : 'npm';
-        const globalRoot = execFileSync(npmCmd, ['root', '-g'], {
-            encoding: 'utf-8', timeout: 10000, shell: isWindows,
-        }).trim();
-        const pkgPath = path.join(globalRoot, AUN_CORE_SDK_PKG, 'package.json');
-        if (fs.existsSync(pkgPath)) {
-            const data = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
-            return { version: data.version, path: pkgPath };
-        }
-    }
-    catch { /* not found */ }
+    catch { /* invalid or missing package metadata */ }
     return null;
 }
+/**
+ * Compatibility guard retained for callers that explicitly check SDK readiness.
+ * The SDK is bundled with EvolCore and must never be installed independently.
+ */
 export async function ensureAunSdk() {
     const installed = resolveAunCoreSdkPkg();
     if (installed && isAunSdkVersionOk(installed.version))
         return;
-    const { npmInstallGlobal } = await import('../../utils/npm-ops.js');
-    console.log(`正在安装 ${AUN_CORE_SDK_PKG}@latest...`);
-    await npmInstallGlobal(`${AUN_CORE_SDK_PKG}@latest`);
+    const expected = MIN_AUN_CORE_SDK.join('.');
+    const detected = installed?.version ?? 'missing';
+    throw new Error(`${AUN_CORE_SDK_PKG} ${detected} is not the bundled SDK expected by EvolCore (>= ${expected}); reinstall or upgrade EvolCore`);
 }
 export function isAunSdkReady() {
     const installed = resolveAunCoreSdkPkg();

package/dist/aun/aid/control-aid.js

@@ -62,7 +62,8 @@ async function candidateExists(store, candidate) {
     throw new Error(`Gateway 不可达，无法查重控制 AID：${r.error?.message ?? 'unknown'}`);
 }
 /**
- * 生成控制 AID：循环候选 → candidateExists 查重（权威 PKI 判据）→ 不冲突则 aidCreate。
+ * 生成控制 AID：循环候选 → candidateExists 查重（权威 PKI 判据）→ 不冲突则 aidCreate；
+ * 查重通过但注册失败时也换候选重试，覆盖查重与注册之间的竞态。
  * - 查重走 GET 证书（见 candidateExists；不拉 agent.md，控制 AID 本就不传 agent.md）
  * - fail-fast：查重探测失败（网关不可达）立即抛错，不掩盖成"均冲突"
  * - agent.md 不上传：aidCreate 仅注册身份 + 写私钥，不调 agentmdPut
@@ -72,6 +73,7 @@ export async function generateControlAid(aidDomain) {
         ? resolveControlAidDomain()
         : normalizeAidDomain(aidDomain, 'aidDomain');
     const store = await getAidStore({ slotId: SLOT.cli });
+    let lastRegistrationError;
     try {
         for (let i = 0; i < MAX_ATTEMPTS; i++) {
             const candidate = candidateAid(finalAidDomain);
@@ -79,22 +81,43 @@ export async function generateControlAid(aidDomain) {
                 logger.info(`[control-aid] ${candidate} 已注册，重试 (${i + 1}/${MAX_ATTEMPTS})`);
                 continue;
             }
-            const created = await aidCreate(candidate);
-            // 清理 aidCreate 内部另开的 client/store——关闭失败不可丢弃已注册的 AID（否则下次 init
-            // 会把它当冲突，白白消耗一次重试）。close 异常降级为 warn。
             try {
-                await created.client?.close?.();
+                const created = await aidCreate(candidate);
+                // 清理 aidCreate 内部另开的 client/store——关闭失败不可丢弃已注册的 AID（否则下次 init
+                // 会把它当冲突，白白消耗一次重试）。close 异常降级为 warn。
+                try {
+                    await created.client?.close?.();
+                }
+                catch (e) {
+                    logger.warn(`[control-aid] client.close() 失败（非致命）: ${e}`);
+                }
+                try {
+                    await created.store?.close?.();
+                }
+                catch (e) {
+                    logger.warn(`[control-aid] store.close() 失败（非致命）: ${e}`);
+                }
+                return { aid: created.aid, gateway: created.gateway };
             }
             catch (e) {
-                logger.warn(`[control-aid] client.close() 失败（非致命）: ${e}`);
+                // 查重与实际注册之间存在 TOCTOU 竞态；注册接口也可能因服务端暂时失败而拒绝，
+                // 这些情况都换一个候选继续尝试。查重阶段的网关错误仍在 candidateExists 中 fail-fast。
+                lastRegistrationError = e;
+                const reason = e instanceof Error ? e.message : String(e);
+                logger.warn(`[control-aid] ${candidate} 注册失败: ${reason}，重试 (${i + 1}/${MAX_ATTEMPTS})`);
             }
-            try {
-                await created.store?.close?.();
-            }
-            catch (e) {
-                logger.warn(`[control-aid] store.close() 失败（非致命）: ${e}`);
-            }
-            return { aid: created.aid, gateway: created.gateway };
+        }
+        if (lastRegistrationError !== undefined) {
+            const reason = lastRegistrationError instanceof Error
+                ? lastRegistrationError.message
+                : String(lastRegistrationError);
+            const error = new Error(`无法生成控制 AID：连续 ${MAX_ATTEMPTS} 次注册尝试失败；最后错误：${reason}`, {
+                cause: lastRegistrationError,
+            });
+            const code = lastRegistrationError?.code;
+            if (typeof code === 'string')
+                error.code = code;
+            throw error;
         }
         throw new Error(`无法生成控制 AID：连续 ${MAX_ATTEMPTS} 次候选均冲突`);
     }

package/dist/aun/aid/managed-operation.js

@@ -0,0 +1,107 @@
+import fs from 'fs';
+import path from 'path';
+import { resolveRoot } from '../../paths.js';
+import { agentmdGet, agentmdPut } from './agentmd.js';
+import { aidLookup, aidShow } from './identity.js';
+import { isValidAid } from './validation.js';
+export class ManagedAidOperationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'ManagedAidOperationError';
+    }
+}
+function normalizeAid(value) {
+    const aid = String(value || '').trim();
+    return aid.startsWith('@') ? aid.slice(1) : aid;
+}
+function hasOnlyOptionalJsonFormat(args, aidIndex) {
+    const suffix = args.slice(aidIndex + 1);
+    return suffix.length === 0 || (suffix.length === 2 && suffix[0] === '--format' && suffix[1] === 'json');
+}
+function parseAid(value) {
+    const aid = normalizeAid(value);
+    if (!aid)
+        return { ok: false, code: 'INVALID_ARGUMENT', reason: 'missing AID' };
+    if (!isValidAid(aid))
+        return { ok: false, code: 'INVALID_AID', reason: `invalid AID: ${aid}` };
+    return { ok: true, aid };
+}
+/**
+ * The daemon accepts only the self-scoped AID commands exposed to managed
+ * tasks. Parsing here is deliberately narrower than the standalone CLI.
+ */
+export function resolveManagedAidOperation(argv) {
+    const args = argv[0] === 'aid' ? argv.slice(1) : argv;
+    const subcommand = args[0];
+    if ((subcommand === 'show' || subcommand === 'lookup') && hasOnlyOptionalJsonFormat(args, 1)) {
+        const parsedAid = parseAid(args[1]);
+        if (!parsedAid.ok)
+            return parsedAid;
+        return {
+            ok: true,
+            command: {
+                kind: subcommand,
+                aid: parsedAid.aid,
+                operationId: `ec.aid.${subcommand}`,
+                canonicalArgv: ['aid', subcommand, parsedAid.aid],
+            },
+        };
+    }
+    if (subcommand === 'agentmd' && (args[1] === 'get' || args[1] === 'put') && hasOnlyOptionalJsonFormat(args, 2)) {
+        const parsedAid = parseAid(args[2]);
+        if (!parsedAid.ok)
+            return parsedAid;
+        const kind = `agentmd.${args[1]}`;
+        return {
+            ok: true,
+            command: {
+                kind,
+                aid: parsedAid.aid,
+                operationId: `ec.aid.${kind}`,
+                canonicalArgv: ['aid', 'agentmd', args[1], parsedAid.aid],
+            },
+        };
+    }
+    return {
+        ok: false,
+        code: 'NOT_ALLOWED',
+        reason: 'Managed AID operations only allow exact self-scoped show, lookup, agentmd get, or agentmd put commands with an optional --format json suffix',
+    };
+}
+const defaultDependencies = () => ({
+    root: resolveRoot(),
+    aidShow,
+    aidLookup,
+    agentmdGet,
+    agentmdPut,
+    existsSync: fs.existsSync,
+    readFileSync: fs.readFileSync,
+});
+/** Execute a validated AID operation from the daemon-owned host filesystem. */
+export async function executeManagedAidOperation(command, overrides = {}) {
+    const deps = { ...defaultDependencies(), ...overrides };
+    const aunPath = deps.root;
+    switch (command.kind) {
+        case 'show':
+            return { kind: command.kind, aid: command.aid, value: await deps.aidShow(command.aid, { aunPath }) };
+        case 'lookup':
+            return { kind: command.kind, aid: command.aid, value: await deps.aidLookup(command.aid) };
+        case 'agentmd.get':
+            return {
+                kind: command.kind,
+                aid: command.aid,
+                value: await deps.agentmdGet(command.aid, { aunPath, withVerification: true }),
+            };
+        case 'agentmd.put': {
+            const localPath = path.join(aunPath, 'AIDs', command.aid, 'agent.md');
+            if (!deps.existsSync(localPath)) {
+                throw new ManagedAidOperationError('LOCAL_AGENTMD_MISSING', `local agent.md not found: ${command.aid}`);
+            }
+            const content = deps.readFileSync(localPath, 'utf-8');
+            await deps.agentmdPut(content, { aid: command.aid, aunPath });
+            return { kind: command.kind, aid: command.aid, path: localPath };
+        }
+    }
+}

package/dist/aun/aid/store.js

@@ -7,21 +7,27 @@ import { AUN_KEYSTORE_ENCRYPTION_SEED } from './encryption-seed-policy.js';
  * slotIsolationKey 取第一个分隔符（空格/'/'/':'）之前的部分作为隔离键，
  * 隔离键相同 = 共享消费通道（token / seq 游标 / 消息过滤）。
  *
- *   'evolcore daemon'   → 隔离键 'evolcore'   ┐
- *   'evolcore cli'      → 隔离键 'evolcore'   ├ 共享 evolcore 消费通道
- *   'evolcore netcheck' → 隔离键 'evolcore'   ┘
+ *   'evolcore daemon'   → 隔离键 'evolcore'
+ *   'evolcore-cli'      → 隔离键 'evolcore-cli'
+ *   'evolcore-netcheck' → 隔离键 'evolcore-netcheck'
+ *   'evolcore-group-rules' → 隔离键 'evolcore-group-rules'
  *   'evolcore-bench'    → 隔离键 'evolcore-bench'（连字符非分隔符）→ 独立通道
  *
  * 设计意图：
- *  - daemon 长连接 + cli 短连接共存于 evolcore 通道（1 长 + N 短，短连接不踢长连接）
- *  - netcheck 长连接抢 evolcore 长连接位 → 踢掉 daemon（用于踢人/extra_info 测试）
+ *  - daemon 保留历史 slot 值；slot_id 是网关上的消费游标身份，不可改名。
+ *  - CLI / ecweb 查询使用新的独立 slot，不能共享 daemon 的 token 或 seq 游标。
+ *  - netcheck 使用独立消费者，不得因诊断连接影响 daemon 的入站顺序。
+ *  - 群规则同步是短连接 RPC，也必须使用独立 slot，避免触碰 daemon 消费游标。
  *  - bench 各并发单元用 evolcore-bench-<N>，各自独立隔离键，互不干扰
  */
 export const SLOT = {
+    // Wire-compatibility contract: changing this creates a new gateway cursor
+    // and can replay retained history into the daemon.
     daemon: 'evolcore daemon',
-    cli: 'evolcore cli',
+    cli: 'evolcore-cli',
+    groupRules: 'evolcore-group-rules',
     bench: 'evolcore-bench',
-    netcheck: 'evolcore netcheck',
+    netcheck: 'evolcore-netcheck',
 };
 /** 加载身份失败时抛出，携带 SDK 的错误码与消息。 */
 export class AidLoadError extends Error {

package/dist/aun/group-fs-download.js

@@ -0,0 +1,56 @@
+import { createHash } from 'node:crypto';
+export class GroupFsDownloadError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'GroupFsDownloadError';
+    }
+}
+/** Download a group file into memory through the ticket/data plane. */
+export async function downloadGroupFsBytes(client, path) {
+    const ticketValue = await client.call('group.fs.create_download_ticket', { path });
+    if (!isRecord(ticketValue)) {
+        throw new GroupFsDownloadError('INVALID_TICKET', 'group.fs.create_download_ticket returned invalid response');
+    }
+    const downloadUrl = stringField(ticketValue, ['download_url', 'url']);
+    if (!downloadUrl) {
+        throw new GroupFsDownloadError('MISSING_DOWNLOAD_URL', 'group.fs.create_download_ticket did not return download_url');
+    }
+    const bytes = await client.group.fs.lowlevel.httpGet(downloadUrl, bearerHeaders(client));
+    const expectedSha = stringField(ticketValue, ['sha256']);
+    if (expectedSha && sha256Hex(bytes).toLowerCase() !== expectedSha.toLowerCase()) {
+        throw new GroupFsDownloadError('HASH_MISMATCH', 'download hash verification failed');
+    }
+    return { bytes, ticket: ticketValue };
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function stringField(value, keys) {
+    for (const key of keys) {
+        const field = value[key];
+        if (typeof field === 'string' && field.trim())
+            return field;
+    }
+    return undefined;
+}
+function sha256Hex(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+function bearerHeaders(client) {
+    const anyClient = client;
+    if (typeof anyClient.getAccessToken === 'function') {
+        const token = stringValue(anyClient.getAccessToken());
+        if (token)
+            return { Authorization: `Bearer ${token}` };
+    }
+    const token = stringValue(anyClient.accessToken)
+        || stringValue(anyClient.access_token)
+        || stringValue(anyClient._identity?.access_token)
+        || stringValue(anyClient._sessionParams?.access_token);
+    return token ? { Authorization: `Bearer ${token}` } : undefined;
+}
+function stringValue(value) {
+    return value === undefined || value === null ? '' : String(value).trim();
+}

package/dist/aun/group-identity.js

@@ -5,6 +5,5 @@ export function isExplicitGroupId(value) {
     return (id.startsWith('group.') && id.includes('/'))
         || /^\d+\.[a-z0-9.-]+$/i.test(id)
         || /^grp_[a-z0-9_-]+$/i.test(id)
-        || /^g-[a-z0-9_-]+(?:[.@][a-z0-9.-]+)?$/i.test(id)
-        || /(?:^|\.)groupid\.pub$/i.test(id);
+        || /^g-[a-z0-9_-]+(?:[.@][a-z0-9.-]+)?$/i.test(id);
 }

package/dist/aun/msg/group.js

@@ -13,6 +13,8 @@ import { readBestTaskRuntimeContext } from '../../cli/task-context.js';
 import { ipcQuery } from '../../ipc.js';
 import { resolvePaths } from '../../paths.js';
 import { AGENT_DELEGATION_TOKEN_ENV } from '../../core/auth/agent-delegation.js';
+import { normalizeAunMentionEntries } from './mention-schema.js';
+import { downloadGroupFsBytes } from '../group-fs-download.js';
 function buildGroupPayload(body) {
     return body.mode === 'text' ? { type: 'text', text: body.text } : { ...body.payload };
 }
@@ -129,17 +131,18 @@ async function daemonGroupSendResult(args, payload, runtimeContext, result) {
             status: result.status,
         };
     }
-    if (!result.group_id || !result.message) {
+    const messageId = result.message_id
+        ?? (typeof result.message?.message_id === 'string' ? result.message.message_id : undefined);
+    if (!result.group_id || !messageId) {
         return { ok: false, error: 'daemon AUN group send returned no group message' };
     }
-    const messageId = result.message_id
-        ?? (typeof result.message.message_id === 'string' ? result.message.message_id : undefined);
     if (messageId && !result.log_written) {
         appendGroupSendOutboundLog(args, messageId, payload, runtimeContext, result.encrypt ?? resolveAunMessageEncrypt(args.encrypt));
     }
     return {
         ok: true,
         group_id: result.group_id || args.groupId,
+        message_id: messageId,
         message: result.message,
         event: result.event,
     };
@@ -189,8 +192,18 @@ export async function groupSend(args) {
                 break;
             }
         }
-        if (args.mentions && args.mentions.length > 0) {
-            payload.mentions = args.mentions;
+        const payloadMentions = Object.prototype.hasOwnProperty.call(payload, 'mentions')
+            ? normalizeAunMentionEntries(payload.mentions)
+            : undefined;
+        if (args.mentions !== undefined) {
+            const normalizedMentions = normalizeAunMentionEntries(args.mentions);
+            if (normalizedMentions.length > 0)
+                payload.mentions = normalizedMentions;
+            else if (payloadMentions !== undefined)
+                payload.mentions = payloadMentions;
+        }
+        else if (payloadMentions !== undefined) {
+            payload.mentions = payloadMentions;
         }
         applyGroupRoutingPayloadFields(payload, args, runtimeContext);
         const encrypt = resolveAunMessageEncrypt(args.encrypt);
@@ -305,8 +318,9 @@ export async function groupInfo(args) {
     }
 }
 export async function groupList(args) {
-    const conn = await createShortConnection(args.from, { aunPath: args.aunPath, slotId: args.slotId });
+    let conn;
     try {
+        conn = await createShortConnection(args.from, { aunPath: args.aunPath, slotId: args.slotId });
         const params = {};
         if (args.size !== undefined)
             params.size = args.size;
@@ -329,7 +343,8 @@ export async function groupList(args) {
         return formatRpcError(e);
     }
     finally {
-        await conn.close();
+        if (conn)
+            await conn.close();
     }
 }
 export async function groupUpdate(args) {
@@ -675,7 +690,7 @@ export async function groupUpdateRules(args) {
     }
 }
 const GROUP_RULES_FILE_PATH = '/rules.md';
-const MAX_GROUP_RULES_BYTES = 4 * 1024;
+export const MAX_GROUP_RULES_BYTES = 4 * 1024;
 const MTIME_TOLERANCE_MS = 1;
 export async function groupRulesFileGet(args) {
     return withAunClient(args.from, args, async (client) => {
@@ -742,13 +757,26 @@ export async function groupRulesFileGet(args) {
 }
 export async function groupRulesFileSet(args) {
     return withAunClient(args.from, args, async (client) => {
-        assertLocalRulesFile(args.filePath);
-        const upload = await client.group.fs.cp(args.filePath, `${args.groupId}:${GROUP_RULES_FILE_PATH}`, {
-            force: true,
-            overwrite: true,
-            parents: true,
-            contentType: 'text/markdown; charset=utf-8',
-        });
+        if ((args.filePath === undefined) === (args.content === undefined)) {
+            throw new Error('规则文件必须且只能提供 filePath 或 content');
+        }
+        let upload;
+        if (args.content !== undefined) {
+            const bytes = Buffer.from(args.content, 'utf8');
+            if (!args.content || bytes.byteLength > MAX_GROUP_RULES_BYTES || bytes.toString('utf8') !== args.content) {
+                throw new Error(`规则内容必须是非空 UTF-8，且不超过 ${MAX_GROUP_RULES_BYTES} bytes`);
+            }
+            upload = await uploadGroupRulesBytes(client, args.groupId, bytes);
+        }
+        else {
+            assertLocalRulesFile(args.filePath);
+            upload = await client.group.fs.cp(args.filePath, `${args.groupId}:${GROUP_RULES_FILE_PATH}`, {
+                force: true,
+                overwrite: true,
+                parents: true,
+                contentType: 'text/markdown; charset=utf-8',
+            });
+        }
         const published = await publishCurrentRulesFile(client, args.groupId, args.from);
         return { ...published, upload };
     });
@@ -984,22 +1012,52 @@ function assertLocalRulesFile(filePath) {
         throw new Error(`规则文件不是有效 UTF-8: ${errorMessage(e)}`);
     }
 }
-async function readGroupRulesBytes(client, groupId) {
-    const remoteRef = `${groupId}:${GROUP_RULES_FILE_PATH}`;
-    const ticket = await client.call('group.fs.create_download_ticket', { path: remoteRef });
-    if (!isRecord(ticket)) {
-        throw new Error('group.fs.create_download_ticket returned invalid response');
+async function uploadGroupRulesBytes(client, groupId, bytes) {
+    const remotePath = `${groupId}:${GROUP_RULES_FILE_PATH}`;
+    const base = {
+        path: remotePath,
+        size_bytes: bytes.byteLength,
+        sha256: sha256Hex(bytes),
+        content_type: 'text/markdown; charset=utf-8',
+        force: true,
+        parents: true,
+    };
+    const check = await client.call('group.fs.check_upload', base);
+    if (isRecord(check) && check.within_limit === false) {
+        throw new Error('规则文件超过 group.fs 上传限制');
+    }
+    if (isRecord(check) && (check.instant === true || check.dedup_hit === true || check.skip_upload === true)) {
+        return client.call('group.fs.complete_upload', {
+            ...base,
+            skip_blob: true,
+            ...(check.session_id !== undefined ? { session_id: check.session_id } : {}),
+        });
     }
-    const downloadUrl = stringField(ticket, ['download_url', 'url']);
-    if (!downloadUrl) {
-        throw new Error('group.fs.create_download_ticket did not return download_url');
+    const session = await client.call('group.fs.create_upload_session', base);
+    if (!isRecord(session))
+        throw new Error('group.fs.create_upload_session returned invalid response');
+    const uploadUrl = stringField(session, ['upload_url', 'url']);
+    if (!uploadUrl)
+        throw new Error('group.fs.create_upload_session did not return upload_url');
+    const headers = {};
+    if (isRecord(session.headers)) {
+        for (const [key, value] of Object.entries(session.headers)) {
+            if (value !== undefined && value !== null)
+                headers[key] = String(value);
+        }
     }
-    const bytes = await client.group.fs.lowlevel.httpGet(downloadUrl, bearerHeaders(client));
-    const expectedSha = stringField(ticket, ['sha256']);
-    if (expectedSha && sha256Hex(bytes).toLowerCase() !== expectedSha.toLowerCase()) {
-        throw new Error('download hash verification failed');
+    if (!Object.keys(headers).some(key => key.toLowerCase() === 'content-type')) {
+        headers['Content-Type'] = base.content_type;
     }
-    return bytes;
+    await client.group.fs.lowlevel.httpPut(uploadUrl, bytes, headers);
+    return client.call('group.fs.complete_upload', {
+        ...base,
+        ...((session.session_id ?? session.id) !== undefined ? { session_id: session.session_id ?? session.id } : {}),
+    });
+}
+async function readGroupRulesBytes(client, groupId) {
+    const remoteRef = `${groupId}:${GROUP_RULES_FILE_PATH}`;
+    return (await downloadGroupFsBytes(client, remoteRef)).bytes;
 }
 function decodeRulesText(bytes) {
     return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
@@ -1057,22 +1115,6 @@ function groupIndexEtagFromUpdate(result, groupId) {
 function sha256Hex(bytes) {
     return createHash('sha256').update(bytes).digest('hex');
 }
-function bearerHeaders(client) {
-    const token = accessTokenFromClient(client);
-    return token ? { Authorization: `Bearer ${token}` } : undefined;
-}
-function accessTokenFromClient(client) {
-    const anyClient = client;
-    if (typeof anyClient.getAccessToken === 'function') {
-        const token = stringValue(anyClient.getAccessToken());
-        if (token)
-            return token;
-    }
-    return stringValue(anyClient.accessToken)
-        || stringValue(anyClient.access_token)
-        || stringValue(anyClient._identity?.access_token)
-        || stringValue(anyClient._sessionParams?.access_token);
-}
 function stringField(obj, keys) {
     for (const key of keys) {
         const value = obj[key];
@@ -1120,6 +1162,11 @@ function rulesFileStatusFromError(error) {
     if (tagged)
         return tagged;
     const haystack = errorHaystack(error);
+    // A peer cache miss means signer discovery failed; it does not establish
+    // that the group's rules file is absent.
+    if (/peer\s+not\s+found\s+in\s+cache/i.test(haystack)) {
+        return 'unreadable';
+    }
     if (/(forbidden|unauthorized|permission|denied|no_permission|permission_denied|无权限|权限|拒绝|\b401\b|\b403\b)/i.test(haystack)) {
         return 'forbidden';
     }

package/dist/aun/msg/index.js

@@ -1,5 +1,4 @@
 export { msgSend, msgPull, msgAck, msgRecall, msgOnline, } from './p2p.js';
 export { msgHistory, MAX_MSG_HISTORY_LIMIT } from './history.js';
 export { groupSend, groupPull, groupAck, groupCreate, groupInfo, groupList, groupUpdate, groupDissolve, groupSuspend, groupResume, groupJoin, groupLeave, groupInvite, groupKick, groupMembers, groupOnline, groupSetRole, groupTransferOwner, groupBan, groupUnban, groupBanlist, groupRules, groupUpdateRules, groupRulesFileGet, groupRulesFileSet, groupRulesFilePublish, } from './group.js';
-export { uploadFileAndBuildPayload } from './upload.js';
-export { inferPayloadType, isValidPayloadType } from './payload-type.js';
+export { uploadFileAndBuildPayload, inferPayloadType, isValidPayloadType } from './upload.js';