@nowcrew/daemon 0.6.88-beta.6 → 0.6.88-beta.7

package/dist/local-memory/candidate.js

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import { containsLikelySecret } from "../agent-memory/policy.js";
+const CategorySchema = z.enum([
+    "preferences", "project-rules", "testing", "debugging", "git", "incidents", "lessons",
+]);
+export const LocalMemorySingleLineText = z.string().trim().min(1).max(500).regex(/^[^\r\n]+$/u);
+export const LocalMemoryChangeSchema = z.object({
+    operation: z.enum(["create", "update", "supersede"]),
+    memoryId: LocalMemorySingleLineText.regex(/^[^<>]+$/u).nullable(),
+    baseRevision: z.number().int().nonnegative().nullable(),
+    supersedesMemoryId: LocalMemorySingleLineText.regex(/^[^<>]+$/u).nullable(),
+    title: LocalMemorySingleLineText.max(120),
+    kind: z.enum(["procedural", "semantic", "episodic", "preference"]),
+    summary: LocalMemorySingleLineText,
+    triggers: z.array(LocalMemorySingleLineText.max(80)).min(1).max(16),
+    priority: z.enum(["high", "medium", "low"]),
+    detailCategory: CategorySchema,
+    detailBody: z.string().trim().min(1).max(12_000),
+    reviewAfter: LocalMemorySingleLineText.nullable(),
+}).strict();
+const CONTROL_CHARACTER_PATTERN = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/u;
+const RESERVED_MEMORY_MARKER = /NOWWORK:(?:MEMORY_ENTRY|MEMORY_INDEX):/iu;
+export function validateLocalMemoryChange(change) {
+    const text = [change.title, change.summary, ...change.triggers, change.detailBody].join("\n");
+    if (containsLikelySecret(text))
+        throw new Error("local_memory_secret_candidate");
+    if (CONTROL_CHARACTER_PATTERN.test(text))
+        throw new Error("local_memory_control_character");
+    if (RESERVED_MEMORY_MARKER.test(text))
+        throw new Error("local_memory_reserved_marker");
+    if (change.operation === "create"
+        && (change.memoryId !== null || change.baseRevision !== null || change.supersedesMemoryId !== null)) {
+        throw new Error("local_memory_create_revision_invalid");
+    }
+    if (change.operation === "update"
+        && (change.memoryId === null || change.baseRevision === null || change.supersedesMemoryId !== null)) {
+        throw new Error("local_memory_update_revision_missing");
+    }
+    if (change.operation === "supersede"
+        && (change.memoryId !== null || change.baseRevision === null || change.supersedesMemoryId === null)) {
+        throw new Error("local_memory_supersede_revision_missing");
+    }
+}

package/dist/local-memory/pending-match.js

@@ -0,0 +1,29 @@
+export function normalizePendingQuery(value) {
+    return value.normalize("NFKC").toLocaleLowerCase().replace(/\s+/gu, " ").trim();
+}
+function containsTerm(text, term) {
+    if (!term)
+        return false;
+    const startBoundary = /^[a-z0-9]/u.test(term);
+    const endBoundary = /[a-z0-9]$/u.test(term);
+    let position = text.indexOf(term);
+    while (position >= 0) {
+        const before = text[position - 1] ?? "";
+        const after = text[position + term.length] ?? "";
+        if ((!startBoundary || !/[a-z0-9_-]/u.test(before)) && (!endBoundary || !/[a-z0-9_-]/u.test(after)))
+            return true;
+        position = text.indexOf(term, position + 1);
+    }
+    return false;
+}
+export function pendingRecallScore(item, query) {
+    const normalized = normalizePendingQuery(query);
+    if (!normalized)
+        return 0;
+    const candidate = item.candidate;
+    const terms = normalized.split(/[\s,，、。！？；：:()[\]{}"'`]+/u).filter(Boolean);
+    const text = normalizePendingQuery([candidate.title, candidate.summary, ...candidate.triggers, candidate.detailCategory, candidate.detailBody].join("\n"));
+    const explicit = [candidate.title, ...candidate.triggers].map(normalizePendingQuery);
+    const explicitScore = explicit.reduce((score, term) => score + (containsTerm(normalized, term) ? 10 : 0), 0);
+    return explicitScore + terms.reduce((score, term) => score + (containsTerm(text, term) ? 1 : 0), 0);
+}

package/dist/local-memory/pending-query.js

@@ -0,0 +1,100 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { isRecallablePending, PendingIdSchema } from "./pending-schema.js";
+import { normalizePendingQuery, pendingRecallScore } from "./pending-match.js";
+import { pendingDirectorySnapshot, pendingSourceError, PENDING_FILE_BYTES, readPendingSource } from "./pending-source.js";
+const PAGE_FILES = 128;
+const PAGE_BYTES = 1_000_000;
+const OUTPUT_BYTES = 12 * 1024;
+const CursorSchema = z.object({
+    v: z.literal(1), queryHash: z.string().regex(/^[a-f0-9]{64}$/u), version: z.string().regex(/^[a-f0-9]{64}$/u),
+    after: z.string().min(1).max(255), hadWarnings: z.boolean(),
+}).strict();
+const SearchSchema = z.object({
+    agentDir: z.string().min(1), query: z.string().trim().min(1).max(256),
+    cursor: z.string().max(2048).optional(), limit: z.number().int().min(1).max(40).default(10),
+}).strict();
+const excerpt = (text, cap) => Array.from(text).slice(0, cap).join("");
+export async function searchPendingMemoryPage(input) {
+    const parsed = SearchSchema.safeParse(input);
+    if (!parsed.success)
+        throw new Error("memory_pending_arguments_invalid");
+    const args = parsed.data;
+    const queryHash = createHash("sha256").update(normalizePendingQuery(args.query)).digest("hex");
+    let cursor;
+    if (args.cursor !== undefined) {
+        try {
+            cursor = CursorSchema.parse(JSON.parse(Buffer.from(args.cursor, "base64url").toString("utf8")));
+        }
+        catch {
+            throw new Error("memory_pending_cursor_invalid");
+        }
+        if (cursor.queryHash !== queryHash)
+            throw new Error("memory_pending_cursor_invalid");
+    }
+    const snapshot = await pendingDirectorySnapshot(args.agentDir);
+    if (cursor && cursor.version !== snapshot.version)
+        throw new Error("memory_pending_source_changed");
+    const initial = cursor ? snapshot.names.indexOf(cursor.after) + 1 : 0;
+    if (cursor && initial === 0)
+        throw new Error("memory_pending_cursor_invalid");
+    const matches = [];
+    const warnings = [];
+    let position = initial;
+    let scannedFiles = 0;
+    let scannedBytes = 0;
+    // 为游标、错误与元数据预留空间；达到输出上限前停止消费来源，不跳过未输出的命中。
+    let outputBytes = 1600;
+    while (position < snapshot.names.length && scannedFiles < PAGE_FILES && scannedBytes + PENDING_FILE_BYTES <= PAGE_BYTES) {
+        const name = snapshot.names[position];
+        let source;
+        let warning;
+        try {
+            source = await readPendingSource(args.agentDir, name);
+        }
+        catch (error) {
+            const code = pendingSourceError(error);
+            if (code === "memory_pending_source_changed" || code === "memory_pending_not_found")
+                throw new Error("memory_pending_source_changed");
+            warning = { file: name, code };
+        }
+        const match = source && isRecallablePending(source.candidate) && pendingRecallScore(source.candidate, args.query) > 0
+            ? { pendingId: source.candidate.pendingId, sha256: source.sha256, title: source.candidate.candidate.title,
+                summary: excerpt(source.candidate.candidate.summary, 180), triggers: source.candidate.candidate.triggers.slice(0, 4),
+                operation: "create", state: "capacity_deferred" }
+            : null;
+        const addition = match ?? warning;
+        const size = addition ? Buffer.byteLength(JSON.stringify(addition), "utf8") + 2 : 0;
+        if (outputBytes + size > OUTPUT_BYTES)
+            break;
+        if (match)
+            matches.push(match);
+        if (warning)
+            warnings.push(warning);
+        outputBytes += size;
+        scannedFiles += 1;
+        scannedBytes += source?.bytes ?? PENDING_FILE_BYTES;
+        position += 1;
+        if (matches.length >= args.limit)
+            break;
+    }
+    if ((await pendingDirectorySnapshot(args.agentDir)).version !== snapshot.version)
+        throw new Error("memory_pending_source_changed");
+    const hasMore = position < snapshot.names.length;
+    const hadWarnings = cursor?.hadWarnings === true || warnings.length > 0;
+    const nextCursor = hasMore ? Buffer.from(JSON.stringify({ v: 1, queryHash, version: snapshot.version,
+        after: snapshot.names[position - 1], hadWarnings })).toString("base64url") : null;
+    return { matches, warnings, scannedFiles, scannedBytes, hasMore, nextCursor, complete: !hasMore && !hadWarnings };
+}
+export async function readPendingMemoryBody(input) {
+    if (!PendingIdSchema.safeParse(input.pendingId).success)
+        throw new Error("memory_pending_id_invalid");
+    const source = await readPendingSource(input.agentDir, `${input.pendingId}.json`);
+    if (input.ifHash !== undefined && input.ifHash !== source.sha256)
+        throw new Error("memory_pending_source_changed");
+    if (!isRecallablePending(source.candidate))
+        throw new Error("memory_pending_not_recallable");
+    const candidate = source.candidate.candidate;
+    return { pendingId: source.candidate.pendingId, sha256: source.sha256, title: candidate.title,
+        operation: "create", state: "capacity_deferred", content: candidate.detailBody };
+}

package/dist/local-memory/pending-schema.js

@@ -0,0 +1,29 @@
+import { z } from "zod";
+import { LocalMemoryChangeSchema, validateLocalMemoryChange } from "./candidate.js";
+// 索引会按分隔符展开触发词；16 个最多 80 UTF-16 单元的输入可产生 0..640 项。
+const ArchivedMemoryChangeSchema = LocalMemoryChangeSchema.extend({
+    triggers: z.array(LocalMemoryChangeSchema.shape.triggers.element).max(640)
+        .refine((triggers) => triggers.reduce((length, trigger) => length + trigger.length, 0) <= 16 * 80),
+});
+export const PendingIdSchema = z.string().max(200).regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/u);
+export const PendingMemorySchema = z.object({
+    schemaVersion: z.literal(1), pendingId: PendingIdSchema,
+    createdAt: z.string().min(1).max(100), reason: z.literal("index_over_budget"),
+    source: z.object({ executionId: z.string().min(1).max(500), pruneTraceId: z.string().min(1).max(500).nullable() }).strict(),
+    candidate: ArchivedMemoryChangeSchema,
+}).strict();
+export function parsePendingMemoryCandidate(value) {
+    const parsed = PendingMemorySchema.safeParse(value);
+    if (!parsed.success)
+        throw new Error("local_memory_pending_invalid");
+    validateLocalMemoryChange(parsed.data.candidate);
+    return parsed.data;
+}
+export function isRecallablePending(value) {
+    try {
+        return parsePendingMemoryCandidate(value).candidate.operation === "create";
+    }
+    catch {
+        return false;
+    }
+}

package/dist/local-memory/pending-source.js

@@ -0,0 +1,126 @@
+import { constants } from "node:fs";
+import { lstat, open, opendir, realpath } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { TextDecoder } from "node:util";
+import { parsePendingMemoryCandidate, PendingIdSchema } from "./pending-schema.js";
+export const PENDING_FILE_BYTES = 128 * 1024;
+const DIRECTORY_ENTRY_CAP = 10_000;
+export function pendingSourceError(error) {
+    if (error instanceof Error && /^memory_pending_[a-z_]+$/u.test(error.message))
+        return error.message;
+    return "memory_pending_file_invalid";
+}
+export async function pendingReadDirectory(agentDir) {
+    const root = await realpath(agentDir);
+    let directory = root;
+    for (const part of [".crew", "memory", "pending"]) {
+        directory = join(directory, part);
+        let stat;
+        try {
+            stat = await lstat(directory);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return { root, directory: null };
+            throw new Error("memory_pending_directory_unreadable");
+        }
+        if (!stat.isDirectory() || stat.isSymbolicLink() || await realpath(directory) !== directory) {
+            throw new Error("memory_pending_path_invalid");
+        }
+    }
+    return { root, directory };
+}
+export async function pendingFileNames(directory) {
+    if (directory === null)
+        return [];
+    const names = [];
+    let inspected = 0;
+    try {
+        for await (const item of await opendir(directory)) {
+            if (++inspected > DIRECTORY_ENTRY_CAP)
+                throw new Error("memory_pending_directory_over_budget");
+            if (item.name.endsWith(".json"))
+                names.push(item.name);
+        }
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith("memory_pending_"))
+            throw error;
+        throw new Error("memory_pending_directory_unreadable");
+    }
+    return names.sort();
+}
+function version(stat) {
+    return [stat.dev, stat.ino, stat.mode, stat.size, stat.mtimeMs, stat.ctimeMs].join(":");
+}
+export async function pendingDirectorySnapshot(agentDir) {
+    const location = await pendingReadDirectory(agentDir);
+    const names = await pendingFileNames(location.directory);
+    const digest = createHash("sha256").update(location.root);
+    if (location.directory !== null)
+        digest.update(version(await lstat(location.directory)));
+    for (const name of names) {
+        try {
+            digest.update(JSON.stringify([name, version(await lstat(join(location.directory, name)))]));
+        }
+        catch {
+            throw new Error("memory_pending_source_changed");
+        }
+    }
+    return { ...location, names, version: digest.digest("hex") };
+}
+export async function readPendingSource(agentDir, name, byteBudget = PENDING_FILE_BYTES) {
+    if (!name.endsWith(".json") || !PendingIdSchema.safeParse(name.slice(0, -5)).success) {
+        throw new Error("memory_pending_id_invalid");
+    }
+    const { directory } = await pendingReadDirectory(agentDir);
+    if (directory === null)
+        throw new Error("memory_pending_not_found");
+    const path = join(directory, name);
+    const before = await lstat(path).catch(() => { throw new Error("memory_pending_not_found"); });
+    if (!before.isFile() || before.isSymbolicLink())
+        throw new Error("memory_pending_path_invalid");
+    const limit = Math.min(byteBudget, PENDING_FILE_BYTES);
+    if (before.size > limit)
+        throw new Error("memory_pending_file_over_budget");
+    const handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+    try {
+        const opened = await handle.stat();
+        if (!opened.isFile() || version(opened) !== version(before))
+            throw new Error("memory_pending_source_changed");
+        const chunks = [];
+        let bytes = 0;
+        for (;;) {
+            const chunk = Buffer.alloc(Math.min(16 * 1024, limit + 1 - bytes));
+            const { bytesRead } = await handle.read(chunk, 0, chunk.length, null);
+            if (bytesRead === 0)
+                break;
+            bytes += bytesRead;
+            if (bytes > limit)
+                throw new Error("memory_pending_file_over_budget");
+            chunks.push(chunk.subarray(0, bytesRead));
+        }
+        const after = await handle.stat();
+        const currentDirectory = await pendingReadDirectory(agentDir);
+        const current = await lstat(path);
+        if (currentDirectory.directory !== directory || version(after) !== version(opened) || version(current) !== version(opened)) {
+            throw new Error("memory_pending_source_changed");
+        }
+        const buffer = Buffer.concat(chunks);
+        let parsed;
+        try {
+            const raw = new TextDecoder("utf-8", { fatal: true }).decode(buffer);
+            parsed = parsePendingMemoryCandidate(JSON.parse(raw));
+        }
+        catch {
+            throw new Error("memory_pending_file_invalid");
+        }
+        if (`${parsed.pendingId}.json` !== name)
+            throw new Error("memory_pending_id_invalid");
+        return { candidate: parsed, bytes, sha256: createHash("sha256").update(buffer).digest("hex") };
+    }
+    finally {
+        await handle.close();
+    }
+}

package/dist/local-memory/pending.js

@@ -1,34 +1,11 @@
 import { randomUUID } from "node:crypto";
-import { lstat, mkdir, readdir, realpath, rename, rm, writeFile, readFile } from "node:fs/promises";
+import { lstat, mkdir, realpath, rename, rm, writeFile } from "node:fs/promises";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
-import { z } from "zod";
+import { isRecallablePending, parsePendingMemoryCandidate } from "./pending-schema.js";
+import { pendingFileNames, pendingReadDirectory, PENDING_FILE_BYTES, readPendingSource } from "./pending-source.js";
+import { pendingRecallScore } from "./pending-match.js";
 export const LOCAL_MEMORY_PENDING_SCAN_FILE_CAP = 128;
 export const LOCAL_MEMORY_PENDING_SCAN_BYTE_CAP = 1_000_000;
-const CandidateSchema = z.object({
-    operation: z.enum(["create", "update", "supersede"]),
-    memoryId: z.string().nullable(),
-    baseRevision: z.number().int().nonnegative().nullable(),
-    supersedesMemoryId: z.string().nullable(),
-    title: z.string().min(1),
-    kind: z.enum(["procedural", "semantic", "episodic", "preference"]),
-    summary: z.string().min(1),
-    triggers: z.array(z.string()).min(1),
-    priority: z.enum(["high", "medium", "low"]),
-    detailCategory: z.enum(["preferences", "project-rules", "testing", "debugging", "git", "incidents", "lessons"]),
-    detailBody: z.string().min(1),
-    reviewAfter: z.string().nullable(),
-}).strict();
-const PendingSchema = z.object({
-    schemaVersion: z.literal(1),
-    pendingId: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/u),
-    createdAt: z.string().min(1),
-    reason: z.literal("index_over_budget"),
-    source: z.object({
-        executionId: z.string().min(1),
-        pruneTraceId: z.string().min(1).nullable(),
-    }).strict(),
-    candidate: CandidateSchema,
-}).strict();
 function within(root, candidate) {
     const path = relative(root, candidate);
     return path === "" || (path !== ".." && !path.startsWith(`..${sep}`));
@@ -122,13 +99,11 @@ async function atomicWrite(path, content) {
     }
 }
 export async function persistPendingMemoryCandidate(input) {
-    const parsed = PendingSchema.safeParse(input.candidate);
-    if (!parsed.success)
-        throw new Error("local_memory_pending_invalid");
+    const parsed = parsePendingMemoryCandidate(input.candidate);
     const directory = await pendingDirectory(input.agentDir);
-    const target = join(directory, `${parsed.data.pendingId}.json`);
+    const target = join(directory, `${parsed.pendingId}.json`);
     await assertRegularFile(target);
-    await atomicWrite(target, `${JSON.stringify(parsed.data, null, 2)}\n`);
+    await atomicWrite(target, `${JSON.stringify(parsed, null, 2)}\n`);
     return target;
 }
 export async function removePendingMemoryCandidate(input) {
@@ -140,73 +115,44 @@ export async function removePendingMemoryCandidate(input) {
     await rm(target, { force: true });
 }
 export async function readPendingMemoryCandidates(input) {
-    const directory = await existingPendingDirectory(input.agentDir);
-    if (directory === null)
-        return [];
-    const names = (await readdir(directory)).filter((name) => name.endsWith(".json")).sort();
+    const { directory } = await pendingReadDirectory(input.agentDir).catch((error) => {
+        if (error instanceof Error && error.message === "memory_pending_path_invalid") {
+            throw new Error("local_memory_pending_path_invalid");
+        }
+        throw error;
+    });
+    const names = await pendingFileNames(directory);
     const maxFiles = Math.max(0, input.maxFiles ?? LOCAL_MEMORY_PENDING_SCAN_FILE_CAP);
     const maxBytes = Math.max(0, input.maxBytes ?? LOCAL_MEMORY_PENDING_SCAN_BYTE_CAP);
     const result = [];
     let scannedBytes = 0;
-    for (const name of names) {
-        if (result.length >= maxFiles || scannedBytes >= maxBytes)
+    for (const name of names.slice(0, maxFiles)) {
+        if (scannedBytes >= maxBytes)
             break;
-        const path = join(directory, name);
         try {
-            await assertRegularFile(path);
-            const stat = await lstat(path);
-            if (!stat.isFile() || stat.isSymbolicLink())
-                throw new Error("local_memory_pending_path_invalid");
-            if (scannedBytes + stat.size > maxBytes)
-                break;
-            const raw = await readFile(path, "utf8");
-            const size = Buffer.byteLength(raw, "utf8");
-            if (scannedBytes + size > maxBytes)
-                break;
-            scannedBytes += size;
-            const parsed = PendingSchema.safeParse(JSON.parse(raw));
-            if (parsed.success && `${parsed.data.pendingId}.json` === name)
-                result.push(parsed.data);
+            const source = await readPendingSource(input.agentDir, name, maxBytes - scannedBytes);
+            scannedBytes += source.bytes;
+            result.push(source.candidate);
         }
         catch {
-            // A damaged pending item is diagnosable and must not hide other candidates.
+            // 失败读取也消耗预算，显式分页命令负责返回诊断和继续扫描。
+            scannedBytes += Math.min(PENDING_FILE_BYTES, maxBytes - scannedBytes);
         }
     }
     return result;
 }
-function normalize(value) {
-    return value.normalize("NFKC").toLocaleLowerCase().replace(/\s+/gu, " ").trim();
-}
 function priorityRank(priority) {
     return priority === "high" ? 0 : priority === "medium" ? 1 : 2;
 }
-function candidateText(candidate) {
-    return [
-        candidate.candidate.title,
-        candidate.candidate.summary,
-        ...candidate.candidate.triggers,
-        candidate.candidate.detailCategory,
-        candidate.candidate.detailBody,
-    ].join("\n");
-}
-function recallScore(candidate, query) {
-    const normalizedQuery = normalize(query);
-    if (normalizedQuery === "")
-        return 1;
-    const text = normalize(candidateText(candidate));
-    if (text.includes(normalizedQuery))
-        return 100;
-    const terms = normalizedQuery.split(/[\s,，、。！？；：:()[\]{}"'`]+/u).filter((term) => term.length > 0);
-    return terms.reduce((score, term) => score + (text.includes(term) ? 1 : 0), 0);
-}
 export async function searchPendingMemoryCandidates(input) {
     const candidates = await readPendingMemoryCandidates({ agentDir: input.agentDir });
     const limit = Math.max(0, input.limit ?? 5);
     if (limit === 0)
         return [];
     return candidates
-        .map((candidate) => ({ candidate, score: recallScore(candidate, input.query) }))
-        .filter((item) => normalize(input.query) === "" || item.score > 0)
+        .filter(isRecallablePending)
+        .map((candidate) => ({ candidate, score: pendingRecallScore(candidate, input.query) }))
+        .filter((item) => item.score > 0)
         .sort((left, right) => right.score - left.score
         || priorityRank(left.candidate.candidate.priority) - priorityRank(right.candidate.candidate.priority)
         || right.candidate.createdAt.localeCompare(left.candidate.createdAt)
@@ -218,25 +164,29 @@ function truncateCodePoints(value, maxCodePoints) {
     return Array.from(value).slice(0, Math.max(0, maxCodePoints)).join("");
 }
 export function renderPendingMemoryContext(candidates, maxCodePoints = 2_000) {
-    if (candidates.length === 0 || maxCodePoints <= 0)
+    const recallable = candidates.filter(isRecallablePending);
+    if (recallable.length === 0 || maxCodePoints <= 0)
         return "";
-    const header = `\n\n## Archived memory candidates (daemon-managed)\n这些记忆已持久化，但尚未进入常驻热索引；只在当前请求相关时参考，必要时再由 memory-prune 提升。\n`;
+    const header = `\n\n## Archived memory candidates (daemon-managed)\n容量暂存的新增资料，仅为部分预览，不代表完整检索；可参考但不能覆盖现行规则，未包含内容请按需查询。\n`;
     let remaining = maxCodePoints - Array.from(header).length;
     if (remaining <= 0)
         return truncateCodePoints(header, maxCodePoints);
     const sections = [];
-    for (const item of candidates) {
+    for (const item of recallable) {
         const change = item.candidate;
         const prefix = `\n### ${change.title}\n`
-            + `- pending_file: .crew/memory/pending/${item.pendingId}.json\n`
+            + `- pending_id: ${item.pendingId}\n`
             + `- summary: ${change.summary}\n`
             + `- triggers: ${change.triggers.join(", ")}\n`
             + "- detail: ";
         const prefixLength = Array.from(prefix).length;
         if (prefixLength + 1 > remaining)
             break;
-        const detail = truncateCodePoints(change.detailBody, remaining - prefixLength - 1);
-        const section = `${prefix}${detail}\n`;
+        const notice = " [正文未完，请用 read-pending 分页读取]";
+        const available = remaining - prefixLength - 1;
+        const truncated = Array.from(change.detailBody).length > available;
+        const detail = truncateCodePoints(change.detailBody, truncated ? Math.max(0, available - Array.from(notice).length) : available);
+        const section = `${prefix}${detail}${truncated ? truncateCodePoints(notice, available - Array.from(detail).length) : ""}\n`;
         const length = Array.from(section).length;
         sections.push(section);
         remaining -= length;

package/dist/local-memory/prompt.js

@@ -1,6 +1,7 @@
 import { dslog } from "../slog.js";
 import { renderPendingMemoryContext, searchPendingMemoryCandidates } from "./pending.js";
 import { renderLocalMemoryResultInstructions } from "./runtime.js";
+const PENDING_READ_GUIDANCE = "\n\nV2新增资料预览未命中不代表没有资料；先查有效索引，必要时用 crew-memory search-pending --query '关键词'，按 nextCursor 续查；用 read-pending --id ID 分页读正文。容量暂存资料不能覆盖现行规则，未应用修改不作为记忆。用 crew-memory --help 查看参数。\n";
 export async function prepareLocalMemoryPrompt(input) {
     let pending = "";
     if (input.enabled) {
@@ -21,17 +22,18 @@ export async function prepareLocalMemoryPrompt(input) {
     }
     const original = input.renderBase(0);
     const structured = input.resultPath === null ? "" : renderLocalMemoryResultInstructions(input.resultPath);
-    const wakeBytes = Buffer.byteLength(structured, "utf8");
-    const fits = (prompt) => input.maxBytes === undefined || Buffer.byteLength(prompt, "utf8") + wakeBytes <= input.maxBytes;
-    const render = (suffix) => (suffix === "" ? original : input.renderBase(Buffer.byteLength(suffix, "utf8") + wakeBytes)) + suffix;
-    // 系统及当前消息各保留一份契约，避免 resume 沿用旧指令；两份均先占预算，再裁可选预览。
-    const complete = render(pending + structured);
-    if (fits(complete))
-        return { systemPrompt: complete, resultPath: input.resultPath, wakePromptSuffix: structured };
-    if (pending !== "") {
-        const withoutPending = render(structured);
-        if (fits(withoutPending))
-            return { systemPrompt: withoutPending, resultPath: input.resultPath, wakePromptSuffix: structured };
+    const guidance = input.enabled ? PENDING_READ_GUIDANCE : "";
+    // 短命令指引放在当前轮，独立于可舍弃预览；收尾契约仍保持系统与当前轮两份。
+    for (const choice of [
+        { suffix: pending + structured, wake: structured + guidance },
+        { suffix: structured, wake: structured + guidance },
+        { suffix: structured, wake: structured },
+    ]) {
+        const reserved = Buffer.byteLength(choice.suffix + choice.wake, "utf8");
+        const systemPrompt = (reserved === 0 ? original : input.renderBase(reserved)) + choice.suffix;
+        if (input.maxBytes === undefined || Buffer.byteLength(systemPrompt + choice.wake, "utf8") <= input.maxBytes) {
+            return { systemPrompt, resultPath: input.resultPath, wakePromptSuffix: choice.wake };
+        }
     }
     // 强制基础指令与契约本身仍无法共存时，保留既有非结构化兼容回退，不裁基础指令。
     return { systemPrompt: original, resultPath: null, wakePromptSuffix: "" };