evolcore 0.0.34 → 0.0.35

package/dist/core/thread/thread-service.js

@@ -3,12 +3,29 @@ import fs from 'fs';
 import path from 'path';
 import { agentSessionsDir, agentDir, agentThreadIndexPath, agentThreadSummariesDir, agentThreadSummaryPath } from '../../paths.js';
 import { atomicWriteJson, atomicReadJson } from '../../utils/atomic-write.js';
-import { appendJsonl, appendJsonlDurable, readAllJsonlLines, readLastJsonlLine, readLastJsonlLineStrict, chatDirPath, tryParseChannelSessionKey } from '../session/session-fs-store.js';
-import { sanitizeSessionTitle } from '../session/session-title.js';
+import { appendJsonl, appendJsonlDurable, readAllJsonlLines, readLastJsonlLine, readLastJsonlLineStrict, chatDirPath, scanChatDirs, tryParseChannelSessionKey } from '../session/session-fs-store.js';
+import { sanitizeSessionTitle, SESSION_TITLE_MAX_LEN, SESSION_TITLE_STORED_MAX_LEN, SESSION_TITLE_ELLIPSIS } from '../session/session-title.js';
 import { ThreadContextStorage } from './thread-context-storage.js';
 const THREAD_ID_RE = /^thread-[0-9]+-[0-9a-f]{4}-[0-9a-f]{4}$/;
 const RESERVED_THREAD_IDS = new Set(['current', 'main', 'all']);
-const THREAD_NAME_MAX_LEN = 80;
+/**
+ * 话题名长度校验：自动生成与手动改名共用 `session-title.ts` 的两个常量。
+ *
+ * - `SESSION_TITLE_MAX_LEN`（80）：正文上限，`sanitizeSessionTitle` 按它截断并补省略号；
+ * - `SESSION_TITLE_STORED_MAX_LEN`（83）：80 字符正文 + `...`，落盘上限。
+ *
+ * 校验按落盘上限而不是正文上限：系统自动生成的话题名最长就是 83 字符，
+ * 按 80 拒绝会让这些名字「改不回去」。超过 83 的直接拒绝并报出当前长度，
+ * 不静默截断——让调用方以为完整名称生效了比报错更糟。
+ */
+function assertThreadNameLength(rawName, sanitized) {
+    const raw = rawName.trim();
+    if (raw.length <= SESSION_TITLE_STORED_MAX_LEN)
+        return;
+    throw new ThreadServiceError(`话题名称超过 ${SESSION_TITLE_STORED_MAX_LEN} 字符上限（当前 ${raw.length} 字符，含标点；`
+        + `其中前 ${SESSION_TITLE_MAX_LEN} 字符为正文，末尾可带 ${SESSION_TITLE_ELLIPSIS} 省略号）。`
+        + `请缩写后重试`, 'NAME_TOO_LONG');
+}
 const LIST_DEFAULT_LIMIT = 10;
 const LIST_MAX_LIMIT = 200;
 export class ThreadServiceError extends Error {
@@ -25,12 +42,41 @@ function newThreadId() {
     const rand = crypto.randomBytes(2).toString('hex');
     return `thread-${ms}-${seq}-${rand}`;
 }
+/**
+ * 读取话题索引，兼容 4d938a6f（话题数据目录收敛）之前的旧路径。
+ *
+ * 旧文件位于 `data/thread-index.json`，新路径是 `data/threads/index.json`。
+ * 那次改动只搬了路径、没写迁移，导致老 agent 的索引在新路径上不存在，
+ * 依赖索引的命令（peers / list / rename ...）看着像"没有话题"。
+ *
+ * 新索引缺失或为空时回退读旧文件，转换后写回新路径。写回是幂等的：
+ * 成功一次之后新索引存在，后续不会再走旧文件；旧文件保持原样，不删除。
+ */
 function readIndex(indexPath) {
     const raw = atomicReadJson(indexPath);
-    if (!raw || !Array.isArray(raw.threads)) {
-        return { version: 1, threads: [] };
+    if (raw && Array.isArray(raw.threads) && raw.threads.length > 0) {
+        return raw;
+    }
+    const legacyPath = path.join(path.dirname(path.dirname(indexPath)), 'thread-index.json');
+    if (legacyPath !== indexPath) {
+        const legacy = atomicReadJson(legacyPath);
+        if (legacy && Array.isArray(legacy.threads) && legacy.threads.length > 0) {
+            const migrated = {
+                version: 1,
+                threads: legacy.threads,
+            };
+            // 顺手落盘；失败不影响本次读取（例如目录只读），下次仍能走回退。
+            try {
+                fs.mkdirSync(path.dirname(indexPath), { recursive: true });
+                atomicWriteJson(indexPath, migrated);
+            }
+            catch { /* 写失败不阻断读取 */ }
+            return migrated;
+        }
     }
-    return raw;
+    if (raw && Array.isArray(raw.threads))
+        return raw;
+    return { version: 1, threads: [] };
 }
 /**
  * 把用户传入的 peer 归一成索引里实际存储的形态（对端在该渠道下的原生 ID）。
@@ -117,9 +163,7 @@ export class ThreadService {
         const sanitized = sanitizeSessionTitle(name);
         if (!sanitized)
             throw new ThreadServiceError('话题名称不能为空', 'INVALID_NAME');
-        if (sanitized.length > THREAD_NAME_MAX_LEN) {
-            throw new ThreadServiceError(`话题名称超过 ${THREAD_NAME_MAX_LEN} 字符`, 'NAME_TOO_LONG');
-        }
+        assertThreadNameLength(name, sanitized);
         // Check for duplicate name on same peer
         const index = this.readThreadIndex(selfAid);
         const dup = index.threads.find(t => t.peer === peer && t.name === sanitized);
@@ -176,8 +220,20 @@ export class ThreadService {
         const sanitized = sanitizeSessionTitle(name);
         if (!sanitized)
             throw new ThreadServiceError('话题名称不能为空', 'INVALID_NAME');
-        if (sanitized.length > THREAD_NAME_MAX_LEN) {
-            throw new ThreadServiceError(`话题名称超过 ${THREAD_NAME_MAX_LEN} 字符`, 'NAME_TOO_LONG');
+        assertThreadNameLength(name, sanitized);
+        // 主会话（threadId 为空）从不进话题索引，它由会话文件产生。
+        // 改名直接落到 active session 上，不走索引与快照。
+        // 群里主会话名只有 admin/owner 能改，且在授权层已经拦过；这里照常落本地。
+        if (!threadId) {
+            const main = await this.showMainSession(selfAid, peer);
+            if (!main)
+                throw new ThreadServiceError(`与 ${peer} 无活跃主会话`, 'TOPIC_NOT_FOUND');
+            if ((main.name ?? '') === sanitized)
+                return { changed: false, name: sanitized };
+            const renamed = await this.sessionManager.renameSession(main.sessionId, sanitized);
+            if (!renamed)
+                throw new ThreadServiceError(`主会话改名失败: ${main.sessionId}`, 'RENAME_FAILED');
+            return { changed: true, name: sanitized, nameUpdatedAt: Date.now() };
         }
         const index = this.readThreadIndex(selfAid);
         const entry = index.threads.find(t => t.peer === peer && t.threadId === threadId);
@@ -185,8 +241,10 @@ export class ThreadService {
             throw new ThreadServiceError(`话题不存在: ${threadId}`, 'TOPIC_NOT_FOUND');
         if (entry.name === sanitized)
             return { changed: false, name: sanitized };
+        const nameUpdatedAt = Date.now();
         entry.name = sanitized;
-        entry.lastActiveAt = Date.now();
+        entry.nameUpdatedAt = nameUpdatedAt;
+        entry.lastActiveAt = nameUpdatedAt;
         this.writeThreadIndex(selfAid, index);
         this.appendThreadSnapshot(selfAid, entry);
         // Sync to session
@@ -194,7 +252,50 @@ export class ThreadService {
         if (session) {
             await this.sessionManager.renameSession(session.id, sanitized);
         }
-        return { changed: true, name: sanitized };
+        return { changed: true, name: sanitized, nameUpdatedAt };
+    }
+    /**
+     * 应用对端发来的改名通知（`topic-renamed`）。
+     *
+     * 判据是最新更新时间先到先赢：通知里的 `nameUpdatedAt` 只有**严格大于**本地
+     * 记录时才生效。对端尚未建档时按通知内容建条目（与会话自动建档一致），
+     * 这样后续跨话题交互能看到对端已命名的话题。
+     */
+    async applyRemoteRename(input) {
+        const sanitized = sanitizeSessionTitle(input.name);
+        if (!sanitized || !input.threadId)
+            return { applied: false, reason: 'invalid' };
+        const peer = normalizeThreadPeer(input.peer) ?? input.peer;
+        const index = this.readThreadIndex(input.selfAid);
+        const entry = index.threads.find(t => t.peer === peer && t.threadId === input.threadId);
+        const current = entry?.nameUpdatedAt ?? 0;
+        if (input.nameUpdatedAt <= current)
+            return { applied: false, reason: 'stale' };
+        if (!entry) {
+            index.threads.push({
+                threadId: input.threadId,
+                sessionId: '',
+                peer,
+                channelType: 'aun',
+                peerKind: input.peerKind ?? 'private',
+                name: sanitized,
+                nameUpdatedAt: input.nameUpdatedAt,
+                label: null,
+                topicStatus: 'pending',
+                createdAt: input.nameUpdatedAt,
+                lastActiveAt: input.nameUpdatedAt,
+            });
+            this.writeThreadIndex(input.selfAid, index);
+            return { applied: true };
+        }
+        entry.name = sanitized;
+        entry.nameUpdatedAt = input.nameUpdatedAt;
+        this.writeThreadIndex(input.selfAid, index);
+        this.appendThreadSnapshot(input.selfAid, entry);
+        const session = await this.sessionManager.getThreadSession(entryChannelType(entry), entry.peer, input.threadId, input.selfAid);
+        if (session)
+            await this.sessionManager.renameSession(session.id, sanitized);
+        return { applied: true };
     }
     // ── P1a.1.6: 话题标签 ──
     async labelThread(input) {
@@ -237,6 +338,10 @@ export class ThreadService {
      * 活跃时间取自该对端消息日志的最后一行，读尾行（不整文件加载）；
      * 无消息日志或读取失败时退回索引里的管理动作时间。
      * 内部话题（daemon 命名空间的会话记录）不是真实联系人，不在此列。
+     *
+     * 候选集 = 索引条目 ∪ 磁盘上真实存在的 chat 目录：
+     * 主会话从不进索引（它由会话文件而非 createThread 产生），只靠索引会漏掉
+     * "只聊过主会话"的对端。磁盘扫描兜住这一类，threadCount 至少记 1。
      */
     listPeers(selfAid) {
         const index = this.readThreadIndex(selfAid);
@@ -252,6 +357,7 @@ export class ThreadService {
                     threadCount: 1,
                     lastActiveAt: entry.lastActiveAt,
                     channelType: entryChannelType(entry),
+                    indexed: true,
                 });
             }
             else {
@@ -260,6 +366,45 @@ export class ThreadService {
                     existing.lastActiveAt = entry.lastActiveAt;
             }
         }
+        // 索引之外的兜底：磁盘上真实存在、且有消息或会话存档的 chat 目录。
+        // 只加索引里没有的对端——索引已经有了的，子话题数已算过，不再重复计主会话。
+        // 从目录名解析 peer 与 channelType，避免信赖可能过期的索引字段。
+        try {
+            const agentsRoot = path.dirname(agentDir(selfAid));
+            for (const chat of scanChatDirs(agentsRoot)) {
+                if (chat.selfAID !== selfAid)
+                    continue;
+                const peer = chat.channelId;
+                if (!peer || isInternalThreadPeer(peer))
+                    continue;
+                const existing = map.get(peer);
+                if (existing) {
+                    // 索引里有的对端：只更正渠道类型（索引历史条目可能缺字段）
+                    if (!existing.channelType)
+                        existing.channelType = chat.channelType;
+                    continue;
+                }
+                // 无消息、无会话存档的空目录不算对端
+                const hasPayload = fs.existsSync(path.join(chat.dirPath, 'messages.jsonl'))
+                    || fs.existsSync(path.join(chat.dirPath, 'active.json'));
+                if (!hasPayload)
+                    continue;
+                // 用当前主会话判定群/私聊；没有会话文件时按目录名兜底为私聊
+                const active = this.sessionManager
+                    ? this.sessionManager.getActiveSessionSync(chat.channelType, peer, chat.channelType, selfAid)
+                    : undefined;
+                map.set(peer, {
+                    peerKind: active?.chatType === 'group' ? 'group' : 'private',
+                    threadCount: 1,
+                    lastActiveAt: active?.updatedAt ?? 0,
+                    channelType: chat.channelType,
+                    indexed: false,
+                });
+            }
+        }
+        catch {
+            // 扫描失败不影响索引结果
+        }
         return Array.from(map.entries())
             .map(([peer, v]) => {
             // 真实活跃时间 = 消息日志末行的时间戳。
@@ -296,6 +441,55 @@ export class ThreadService {
                 return false;
             return true;
         });
+        // 主会话是 threadId 为 `''` 的话题：它由会话文件而非 createThread 产生，
+        // 所以从不进话题索引。只列子话题会让「和某对端聊过什么」在列表里看不到主线，
+        // 而 `history <peer>` 不传 threadId 读的恰恰是主会话消息。指定对端时补一条
+        // 合成记录，让 list 与 history 的口径一致。
+        if (peer) {
+            const hasMain = threads.some(t => !t.threadId);
+            if (!hasMain) {
+                const chatDir = this.chatDirFor(selfAid, peer);
+                const logPath = path.join(chatDir, 'messages.jsonl');
+                let lastTs = 0;
+                if (fs.existsSync(logPath)) {
+                    try {
+                        for (const m of readAllJsonlLines(logPath)) {
+                            if (!m.threadId && typeof m.ts === 'number' && m.ts > lastTs)
+                                lastTs = m.ts;
+                        }
+                    }
+                    catch { /* skip corrupt file */ }
+                }
+                // 群标识与私聊 AID 语法相同，只能靠会话记录里的 chatType 判定；
+                // 没有会话文件时退回私聊（`ec thread list <peer>` 的常见用法）。
+                const active = this.sessionManager.getActiveSessionSync('aun', peer, 'aun', selfAid);
+                const peerKind = active?.chatType === 'group' ? 'group' : 'private';
+                const synthetic = {
+                    threadId: '',
+                    sessionId: active?.id ?? '',
+                    peer,
+                    channelType: 'aun',
+                    peerKind,
+                    // 主会话有自己的名字（创建时写 `默认会话`，可经 ec thread rename 修改）。
+                    // 读真实值而不是写死 `主会话`：否则列表里的名字和会话存档对不上，
+                    // 用户也没法从列表确认改名是否生效。`[主会话]` 前缀由 CLI 渲染。
+                    name: active?.name || '主会话',
+                    label: null,
+                    topicStatus: 'pending',
+                    createdAt: lastTs,
+                    lastActiveAt: lastTs,
+                    mainSession: true,
+                    internal: false,
+                    msgTotal: 0,
+                    msg24h: 0,
+                    lastMsgSnippet: '',
+                };
+                // 该对端没有任何主会话往来时不造空行；状态/标签过滤对主会话也无意义，
+                // 只在未过滤时加入。
+                if (lastTs > 0 && !status && !label && !unlabeled)
+                    threads = [synthetic, ...threads];
+            }
+        }
         // 先读消息日志并派生真实活跃时间，再排序、再分页——
         // 否则 recent 排序用的是索引里的管理动作时间，与实际展示的活跃时间不一致。
         const ts24h = Date.now() - 86400000;
@@ -315,7 +509,7 @@ export class ThreadService {
                                 ? (payload.text ?? payload.content ?? '')
                                 : (m.content ?? '');
                             msgs.push({
-                                threadId: m.threadId ?? null,
+                                threadId: m.threadId ?? '',
                                 ts: m.ts ?? 0,
                                 snippet: String(text).replace(/\n/g, ' ').slice(0, 50),
                             });
@@ -332,10 +526,12 @@ export class ThreadService {
         const lastMsgOf = new Map();
         for (const t of threads) {
             const msgs = (peerMessages.get(`${entryChannelType(t)}\u0000${t.peer}`) ?? [])
-                .filter(m => m.threadId === t.threadId);
+                .filter(m => (m.threadId ?? '') === (t.threadId ?? ''));
             const lastMsg = msgs.reduce((acc, m) => (!acc || m.ts > acc.ts) ? m : acc, null);
+            // 合成的主会话条目用 `main` 作 threadId，日志里主会话记的是 null。
+            const key = t.threadId ?? '';
             if (lastMsg)
-                lastMsgOf.set(t.threadId, lastMsg);
+                lastMsgOf.set(key, lastMsg);
         }
         if (sort === 'created') {
             threads.sort((a, b) => b.createdAt - a.createdAt);
@@ -349,10 +545,10 @@ export class ThreadService {
         threads = threads.slice(offset, offset + limit);
         threads = threads.map(t => {
             const msgs = (peerMessages.get(`${entryChannelType(t)}\u0000${t.peer}`) ?? [])
-                .filter(m => m.threadId === t.threadId);
+                .filter(m => (m.threadId ?? '') === (t.threadId ?? ''));
             const msgTotal = msgs.length;
             const msg24h = msgs.filter(m => m.ts >= ts24h).length;
-            const lastMsg = lastMsgOf.get(t.threadId);
+            const lastMsg = lastMsgOf.get(t.threadId ?? '');
             const lastActiveAt = lastMsg?.ts || t.lastActiveAt;
             // 读该话题的 summary（当前最新版本）
             const summaryEntry = this.showSummary(selfAid, t.sessionId);
@@ -409,11 +605,11 @@ export class ThreadService {
             return { peer, messages: [] };
         const messages = readAllJsonlLines(logPath)
             .filter((m) => {
-            // threadId 为 undefined/null 时读主会话消息（threadId === null 的行），
-            // 否则按 threadId 精确匹配子话题消息。
+            // 不传 threadId 时读主会话消息：主会话的行 threadId 为 ''（历史残留 null
+            // 也按主会话处理），否则按 threadId 精确匹配子话题消息。
             if (threadId)
                 return m.threadId === threadId;
-            return m.threadId == null;
+            return !m.threadId;
         })
             .map((m) => {
             // 消息体优先取 payloadSummary.text（加密消息的明文摘要），
@@ -695,16 +891,16 @@ export class ThreadService {
      * 作为"这条摘要覆盖到哪"的游标。下次总结时用它作 `history --after` 起点，
      * 只读增量。话题为空（或主会话无消息）时不记录该字段。
      */
-    setSummary(selfAid, sessionId, content, ifRev) {
+    async setSummary(selfAid, sessionId, content, ifRev) {
         const dir = agentThreadSummariesDir(selfAid);
         fs.mkdirSync(dir, { recursive: true });
         const filePath = agentThreadSummaryPath(selfAid, sessionId);
-        const existing = this._readSummaryLines(filePath);
+        const coveredThroughTs = await this.resolveCoveredThroughTs(selfAid, sessionId);
+        const existing = this._readAllSummaryLines(filePath);
         const currentRev = existing.length;
         if (ifRev !== undefined && ifRev !== currentRev) {
             throw new ThreadServiceError(`summary CAS 冲突：期望版本 ${ifRev}，当前版本 ${currentRev}`, 'SUMMARY_CAS_CONFLICT');
         }
-        const coveredThroughTs = this.resolveCoveredThroughTs(selfAid, sessionId);
         const entry = {
             rev: currentRev + 1,
             content,
@@ -719,12 +915,25 @@ export class ThreadService {
      *
      * 话题内总结时这就是"当前消息"，跨话题总结时（先读全增量再写）也是同一语义。
      * 话题不存在或无消息时返回 undefined——此时摘要没有游标，下次总结只能全量读。
+     *
+     * 主会话不进话题索引（它由会话文件产生），索引里查不到时按 sessionId 回退到
+     * session 本身：peer 取 channelId，threadId 取 session.threadId（主会话为空串）。
+     * 不回退的话主会话摘要永远没有游标，增量总结在主会话上不成立。
      */
-    resolveCoveredThroughTs(selfAid, sessionId) {
+    async resolveCoveredThroughTs(selfAid, sessionId) {
         const entry = this.readThreadIndex(selfAid).threads.find(t => t.sessionId === sessionId);
-        if (!entry)
+        let peer = entry?.peer;
+        let threadId = entry?.threadId;
+        if (!entry) {
+            const session = await this.sessionManager.getSessionById(sessionId);
+            if (!session)
+                return undefined;
+            peer = session.channelId;
+            threadId = session.threadId ?? '';
+        }
+        if (!peer)
             return undefined;
-        const { messages } = this._readThreadMessages(selfAid, entry.peer, entry.threadId);
+        const { messages } = this._readThreadMessages(selfAid, peer, threadId);
         if (messages.length === 0)
             return undefined;
         return messages[messages.length - 1].timestamp;
@@ -753,18 +962,23 @@ export class ThreadService {
      */
     clearSummary(selfAid, sessionId) {
         const filePath = agentThreadSummaryPath(selfAid, sessionId);
-        const existing = this._readSummaryLines(filePath);
+        // 计数必须含墓碑：rev 是文件行序号，过滤后会与已有墓碑撞号。
+        const existing = this._readAllSummaryLines(filePath);
         if (existing.length === 0)
             return; // 已无内容，幂等
         const dir = agentThreadSummariesDir(selfAid);
         fs.mkdirSync(dir, { recursive: true });
         appendJsonl(filePath, { rev: existing.length + 1, content: null, updatedAt: Date.now() });
     }
-    _readSummaryLines(filePath) {
+    /** 全部记录，含 clear 墓碑（content=null）。rev/CAS 计数一律基于这个。 */
+    _readAllSummaryLines(filePath) {
         if (!fs.existsSync(filePath))
             return [];
-        const all = readAllJsonlLines(filePath);
-        // 过滤掉 clear 墓碑（content=null），只返回实际写入的版本
-        return all.filter(l => l.content !== null);
+        return readAllJsonlLines(filePath);
+    }
+    /** 只含实际写入的版本，不含 clear 墓碑。仅用于展示历史。 */
+    _readSummaryLines(filePath) {
+        return this._readAllSummaryLines(filePath)
+            .filter(l => l.content !== null);
     }
 }

package/dist/utils/cross-platform.js

@@ -344,9 +344,9 @@ export async function launchMonitorAndConfirm(args, env, isAliveInRegistry, hasO
  * in a checkout: `npm install -g` swaps the whole package directory, and the
  * monitor has ~170 lazy `await import()` sites, so a module it has not loaded
  * yet would come from the new version while the rest is still the old one.
- * Staging `dist/` elsewhere keeps its module graph on one consistent version.
+ * Staging `dist/` and `bin/` keeps the package-owned code on one version.
  *
- * Only `dist/` and `package.json` are copied (a few MB). `node_modules` is
+ * Only `dist/`, `bin/` and `package.json` are copied (a few MB). `node_modules` is
  * linked, because copying it is hundreds of MB. The link degrades in steps so
  * that no platform is left without a path forward:
  *
@@ -379,6 +379,9 @@ export function prepareMonitorStage(packageRoot, stageParent) {
     try {
         fs.mkdirSync(stageDir, { recursive: true });
         fs.cpSync(distSource, path.join(stageDir, 'dist'), { recursive: true });
+        const binSource = path.join(packageRoot, 'bin');
+        if (fs.existsSync(binSource))
+            fs.cpSync(binSource, path.join(stageDir, 'bin'), { recursive: true });
         const pkgJson = path.join(packageRoot, 'package.json');
         if (fs.existsSync(pkgJson))
             fs.copyFileSync(pkgJson, path.join(stageDir, 'package.json'));
@@ -388,7 +391,7 @@ export function prepareMonitorStage(packageRoot, stageParent) {
             fs.rmSync(stageDir, { recursive: true, force: true });
         }
         catch { }
-        return { stageDir: null, linkMode: 'none', note: `复制 dist/ 失败：${error.message}` };
+        return { stageDir: null, linkMode: 'none', note: `复制 monitor 运行文件失败：${error.message}` };
     }
     if (!fs.existsSync(modulesSource)) {
         // Dependencies hoisted elsewhere; nothing to link, node resolves upward.

package/kits/docs/evolcore/fs-architecture.md

@@ -650,7 +650,7 @@ lrwxrwxrwx slides.pdf → /private/q2/slides.pdf r-- public
 ```bash
 ec fs ls --pending <AID>:                      # 查看待审批
 ec fs approve <AID>: --request-id req_xxx
-ec fs reject  <AID>: --request-id req_xxx --note "需脱敏"
+ec fs reject  <AID>: --request-id req_xxx --note '需脱敏'
 ```
 
 ---
@@ -1118,20 +1118,20 @@ forward 历史全部保留，任何时候都能再前滚。
 ec collab submit alice.aid.pub:/projects/myapp schema.json ./schema.json --base-version 1
 
 # alice 打快照——只动了内容，自动 PATCH
-ec collab snapshot create alice.aid.pub:/projects/myapp -m "修正 schema 字段"
+ec collab snapshot create alice.aid.pub:/projects/myapp -m '修正 schema 字段'
 # → 2.3.1 (bump=patch, changed=[schema.json])
 
 # alice 新增 deploy.md（doc 集合变化）后打快照——自动 MINOR
 ec collab create alice.aid.pub:/projects/myapp deploy.md ./deploy.md
-ec collab snapshot create alice.aid.pub:/projects/myapp -m "加部署文档"
+ec collab snapshot create alice.aid.pub:/projects/myapp -m '加部署文档'
 # → 2.4.0 (bump=minor)
 
 # 里程碑，手动标大版本
-ec collab snapshot create alice.aid.pub:/projects/myapp --major -m "v3 设计定稿"
+ec collab snapshot create alice.aid.pub:/projects/myapp --major -m 'v3 设计定稿'
 # → 3.0.0
 
 # 方向错了，非破坏回滚到 2.3.1
-ec collab snapshot restore alice.aid.pub:/projects/myapp 2.3.1 -m "回退到 schema 修正版"
+ec collab snapshot restore alice.aid.pub:/projects/myapp 2.3.1 -m '回退到 schema 修正版'
 # → 各 @current 重指回 2.3.1 的 target；deploy.md 的 @current 撤下（版本文件仍在）
 #   追加新快照 3.0.1，记录 "restored from 2.3.1"；3.0.0 历史保留
 

package/kits/docs/evolcore/fs.md

@@ -77,7 +77,7 @@ ec fs ln -s alice.agentid.pub:/private/report.md alice.agentid.pub:/public/repor
 ec fs chmod +r alice.agentid.pub:/public/report.md
 ec fs setfacl alice.agentid.pub:/private/report.md -m aid:bob.agentid.pub:r
 ec fs token issue alice.agentid.pub:/public/report.md --expires 2026-12-31
-ec fs find alice.agentid.pub:/private/ --name "*.md"
+ec fs find alice.agentid.pub:/private/ --name '*.md'
 ec fs rm alice.agentid.pub:/private/report.md
 ec fs df alice.agentid.pub:
 ```

package/kits/docs/evolcore/group-collaboration.md

@@ -46,7 +46,7 @@
 群名称必填。创建前根据群名称确定一个简短、唯一的 group AID（同样使用 `{name}.{issuer}`，不要四级域名），并给出一句群简介；名称、AID 和简介应能体现协作目标。推荐默认使用私有群和 `invite_only`，先建群再按名单邀请：
 
 ```bash
-ec group create coordinator.agentid.pub "Project Alpha 协作" \
+ec group create coordinator.agentid.pub 'Project Alpha 协作' \
   --visibility private \
   --description "Project Alpha 的设计、实现和复核协作群" \
   --join-mode invite_only

package/kits/docs/evolcore/group.md

@@ -33,7 +33,7 @@ ec group ack <from> <group-id> <seq> [--app <name>]
 ```
 
 @ 成员：
-- `--mention '<aid1>,<aid2>'` — @ 某个成员。写法固定为单引号包住、逗号分隔，可多次传入，每个 aid 都过格式校验
+- `--mention '<aid1>,<aid2>'` — @ 某个成员。单引号包住、逗号分隔，可多次传入，每个 aid 都过格式校验
 - `--mention-all` — @ 所有人
 
 ```bash
@@ -92,10 +92,10 @@ ec group create <from> '<name>' [--visibility public|private] [--description '<d
 
 # 不指定 --group-id 时，默认名称为 g- 加五位随机数字（10000–99999）
 # 例如返回 g-12345.agentid.cn；issuer 以群服务实际返回为准
-ec group create <from> "研讨群" --visibility private
+ec group create <from> '研讨群' --visibility private
 
 # 自定义群 AID；g- 若出现，是名称的一部分，会完整保留
-ec group create <from> "本体研讨" --group-id ontology.agentid.cn
+ec group create <from> '本体研讨' --group-id ontology.agentid.cn
 
 # 列出我加入的群
 ec group list <from> [--size <N>]
@@ -190,6 +190,8 @@ ec group invite <from> <group-id> <member-aid> [<member-aid>...]
 ec group kick <from> <group-id> <member-aid>
 
 # 列出群成员
+# 参数顺序固定为「先发送方 AID，后群 AID」——群 ID 永远在第 2 个位置。
+# 写反时命令会直接指出，并给出可复制的正确写法。
 ec group members <from> <group-id> [--page <N>] [--size <N>]
 
 # 查看在线成员

package/kits/docs/evolcore/memory-consolidation.md

@@ -245,8 +245,7 @@ daemon 按整理会话的模式校验 `--scope`：
 |---|---|---|
 | 12 | `memory` | 与主会话共用的 `$KITS_FRAGMENTS/memory.md`，按 `sessionType=memory` 渲染整理分支：三个写命令、模式权限、禁止事项 |
 | 20 | `memory-workflow` | 整理流程：读上下文、查重、取舍、update 与 create --replaces 的选择、收尾 |
-| 25 | `persona` | 当前 agent 的人格 |
-| 26 | `personal-profile` | 当前 agent 的个人资料与工作背景 |
+| 25 | `persona` | 当前 agent 的人格与个人资料（合并自原 `personal-profile` 段） |
 | 27 | `peer-profile` | **当前对端画像**（`profile` 标签的记忆） |
 | 31 | `memory-mode-*` | 五份模式手册，按 `memoryMode` 五选一 |
 | 36/37/38 | 三份记忆索引 | agent / owner / relation |

package/kits/docs/evolcore/memory-tags.md

@@ -55,7 +55,7 @@ tags: [important, long-term, rule, verified]
 
 **打标的地方**：整理会话写正式记忆（`ec memory create --tags 'a,b'`，事后用 `ec memory update --tags 'a,b'` 整体替换），主会话写 note（`ec memory note --tags 'a,b'`）。note 的标签是临时的，整理会话读取后决定去留。
 
-写法固定为单引号包住、逗号分隔：`--tags 'to-generalize,urgent'`。
+写法为单引号包住、逗号分隔：`--tags 'to-generalize,urgent'`。
 
 **清标的两种方式**：
 

package/kits/docs/evolcore/memory.md

@@ -21,8 +21,8 @@ ec memory note --slug <slug> [--tags '<tag1>,<tag2>'] [--speakers '<id1>,<id2>']
 | 参数 | 说明 |
 |------|------|
 | `--slug` | **必填**。字母/数字/连字符，1-64 字符，当前关系内唯一，后续 update / drop 靠它定位 |
-| `--tags` | 可选。写法固定为 `--tags 'tag1,tag2'`：单引号包住，逗号分隔。取值见 `$KITS_DOCS/evolcore/memory-tags.md` |
-| `--speakers` | 可选，**群聊专用**。写法固定为 `--speakers '<aid1>,<aid2>'`：单引号包住，逗号分隔。填本条 note 涉及的发言人 AID 或渠道原生 ID。整理会话会据此把发言人相关信息分流写入各发言人自己的 relation 记忆，而不是只落在群的 relation 下。私聊场景无需填写。 |
+| `--tags` | 可选。`--tags 'tag1,tag2'`：单引号包住，逗号分隔。取值见 `$KITS_DOCS/evolcore/memory-tags.md` |
+| `--speakers` | 可选，**群聊专用**。`--speakers '<aid1>,<aid2>'`：单引号包住，逗号分隔。填本条 note 涉及的发言人 AID 或渠道原生 ID。整理会话会据此把发言人相关信息分流写入各发言人自己的 relation 记忆，而不是只落在群的 relation 下。私聊场景无需填写。 |
 | 正文 | 必填。写清事实本身即可，不用组织成索引描述 |
 
 ```bash

package/kits/docs/evolcore/stats.md

@@ -67,7 +67,7 @@ ec stats --rebuild
 ## 直接 SQL 查询
 
 ```bash
-ec stats --sql "SELECT model, COUNT(*) AS cnt FROM usage_events GROUP BY model"
+ec stats --sql 'SELECT model, COUNT(*) AS cnt FROM usage_events GROUP BY model'
 ```
 
 仅允许 SELECT 查询（只读安全）。