@co0ontty/wand 4.71.2 → 4.72.0-beta.gfc56736

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
-  "commit": "1a04a06e5944858ecf2a357251d46aafdc943e32",
-  "builtAt": "2026-09-20T16:00:19.154Z",
-  "version": "4.71.2",
-  "channel": "stable"
+  "commit": "fc5673635615d567540a2a3e636041a4a3422cad",
+  "builtAt": "2026-09-21T22:39:08.943Z",
+  "version": "4.72.0-beta.gfc56736",
+  "channel": "beta"
 }

package/dist/git-quick-commit.d.ts

@@ -2,7 +2,7 @@ import { GitStatusResult, PushResult, QuickCommitResult, SessionProvider, Sessio
 export type QuickCommitErrorCode = "CWD_MISSING" | "NO_CWD" | "NOT_A_GIT_REPO" | "NO_COMMIT" | "NOTHING_TO_COMMIT" | "NOTHING_TO_PUSH" | "EMPTY_MESSAGE" | "EMPTY_TAG" | "EMPTY_AI_MESSAGE" | "AI_FALLBACK_FAILED" | "INVALID_AI_TAG" | "TAG_EXISTS" | "GIT_ADD_FAILED" | "GIT_DIFF_FAILED" | "GIT_COMMIT_FAILED" | "GIT_TAG_FAILED" | "CLAUDE_CLI_MISSING" | "CLAUDE_CLI_FAILED" | "CLAUDE_TIMEOUT";
 /** Non-blocking status implementation used by HTTP routes. */
 export declare function getGitStatusAsync(cwd: string): Promise<GitStatusResult>;
-interface QuickCommitOptions {
+interface QuickCommitOptions extends CommitInputOptions {
     cwd: string;
     language: string;
     provider?: SessionProvider;
@@ -33,6 +33,16 @@ export declare class QuickCommitError extends Error {
     readonly code: QuickCommitErrorCode;
     constructor(message: string, code: QuickCommitErrorCode);
 }
+/**
+ * 生成 commit message / tag 的输入源。
+ *   - iterationDigest：本轮迭代的提示词标题清单（默认输入，省 token、不读代码）；
+ *   - includeDiff：仍然附上完整 diff，用于提示词不够、需要逐行核对时；
+ *   - 两个都没有时保持旧行为：直接读 diff。
+ */
+export interface CommitInputOptions {
+    iterationDigest?: string;
+    includeDiff?: boolean;
+}
 /**
  * Run a lightweight AI request through the selected Commit source. API mode
  * exhausts its profile chain and then falls back once to the current-session
@@ -44,7 +54,7 @@ export interface GenerateCommitMessageResult {
     /** AI-suggested next tag derived from the staged diff and the latest existing tag. */
     suggestedTag?: string;
 }
-export declare function generateCommitMessageOnly(cwd: string, language: string, ai?: QuickCommitAiOptions): Promise<GenerateCommitMessageResult>;
+export declare function generateCommitMessageOnly(cwd: string, language: string, ai?: QuickCommitAiOptions, options?: CommitInputOptions): Promise<GenerateCommitMessageResult>;
 interface TagHeadOptions {
     cwd: string;
     language: string;

package/dist/git-quick-commit.js

@@ -23,6 +23,8 @@ const CODEX_MESSAGE_TIMEOUT_MS = 60_000;
 const DIRECT_API_PROFILE_TIMEOUT_MS = 20_000;
 const QUICK_COMMIT_CLI_TIMEOUT_MS = 120_000;
 const MAX_DIFF_FOR_AI = 100_000;
+// 迭代提示词模式下只给文件清单做核对，不需要完整 diff：单次上限比 diff 小一个量级。
+const MAX_WORKTREE_SUMMARY_FOR_AI = 4_000;
 const GIT_MAX_BUFFER = 16 * 1024 * 1024;
 function runGitAsync(args, cwd, timeoutMs = GIT_TIMEOUT_MS) {
     return runGitAsyncBase(args, cwd, { timeout: timeoutMs, maxBuffer: GIT_MAX_BUFFER });
@@ -639,10 +641,71 @@ async function collectWorkingTreeDiff(cwd) {
     }
     return diff;
 }
-async function generateCommitMessage(cwd, language, ai = {}) {
-    const diff = await collectWorkingTreeDiff(cwd);
+/** 有迭代提示词时用的轻量改动清单：只列文件与增删行数，不读任何代码内容。 */
+async function collectWorkingTreeSummary(cwd) {
+    const parts = [];
+    for (const args of [["diff", "HEAD", "--stat"], ["diff", "--cached", "--stat"]]) {
+        try {
+            const stat = await runGitAsync(args, cwd, 5000);
+            if (stat) {
+                parts.push(stat);
+                break;
+            }
+        }
+        catch {
+            // 没有 HEAD（初始仓库）或没有 staged 内容都会走到这里，换下一个候选。
+        }
+    }
+    try {
+        const untracked = await runGitAllowEmptyAsync(["ls-files", "--others", "--exclude-standard"], cwd, 3000);
+        if (untracked.trim())
+            parts.push(`未跟踪文件：\n${untracked.trim()}`);
+    }
+    catch {
+        // 可选信息，取不到就算了：提示词清单已经够模型总结。
+    }
+    if (parts.length === 0)
+        return "(没有可见的文件改动)";
+    const summary = parts.join("\n");
+    return summary.length > MAX_WORKTREE_SUMMARY_FOR_AI
+        ? `${summary.slice(0, MAX_WORKTREE_SUMMARY_FOR_AI)}\n...(文件清单已截断)`
+        : summary;
+}
+/**
+ * 拼出「要总结什么」的输入块。
+ * 有迭代提示词时默认只附文件清单：commit message 要的是「我让你们改了什么」，
+ * 不是逐行 diff，省下的就是真金白银的 token。
+ */
+async function buildCommitPromptInput(cwd, options) {
+    const digest = options.iterationDigest?.trim();
+    if (digest) {
+        const summary = await collectWorkingTreeSummary(cwd);
+        const diff = options.includeDiff ? `\ngit diff：\n${await collectWorkingTreeDiff(cwd)}` : "";
+        return {
+            usedIteration: true,
+            input: [
+                "我这一轮迭代（上次提交之后）发给编码助手的改动提示词，按时间排列：",
+                digest,
+                "",
+                "本次工作区改动清单（仅供核对，不要逐文件罗列）：",
+                summary,
+                diff,
+            ].join("\n"),
+        };
+    }
+    return { usedIteration: false, input: `git diff：\n${await collectWorkingTreeDiff(cwd)}` };
+}
+/** 两种输入源共用的任务描述，只改变如何引导模型读输入。 */
+function commitTaskLine(lang, usedIteration) {
+    const instruction = usedIteration
+        ? `阅读以下迭代提示词与文件清单，用${lang}写一条简洁的 commit message。要求：祈使句，不超过 50 字，描述「做了什么」。只输出 message 本身，不要引号、不要 Markdown 格式、不要任何额外说明。`
+        : `阅读以下 git diff，用${lang}写一条简洁的 commit message。要求：祈使句，不超过 50 字，描述「做了什么」。只输出 message 本身，不要引号、不要 Markdown 格式、不要任何额外说明。`;
+    return instruction;
+}
+async function generateCommitMessage(cwd, language, ai = {}, options = {}) {
+    const { input, usedIteration } = await buildCommitPromptInput(cwd, options);
     const lang = language.trim() || "中文";
-    const prompt = `阅读以下 git diff，用${lang}写一条简洁的 commit message。要求：祈使句，不超过 50 字，描述「做了什么」。只输出 message 本身，不要引号、不要 Markdown 格式、不要任何额外说明。\n\n${diff}`;
+    const prompt = `${commitTaskLine(lang, usedIteration)}\n\n${input}`;
     const raw = await callConfiguredAiText(prompt, cwd, language, ai);
     const message = normalizeAiText(raw);
     if (!message) {
@@ -677,8 +740,8 @@ function sanitizeSuggestedTag(value) {
         return undefined;
     return cleaned;
 }
-async function generateCommitMessageWithTag(cwd, language, ai = {}) {
-    const diff = await collectWorkingTreeDiff(cwd);
+async function generateCommitMessageWithTag(cwd, language, ai = {}, options = {}) {
+    const { input, usedIteration } = await buildCommitPromptInput(cwd, options);
     let latestTag;
     try {
         latestTag = await runGitAsync(["describe", "--tags", "--abbrev=0"], cwd) || undefined;
@@ -690,15 +753,14 @@ async function generateCommitMessageWithTag(cwd, language, ai = {}) {
     const tagHint = latestTag
         ? `当前最新 tag 是 \`${latestTag}\`，请基于它给出下一个版本号（保持原有前缀风格，例如有 \`v\` 就保留 \`v\`）。`
         : `仓库还没有任何 tag，请直接给一个起始版本号（建议 \`v0.0.1\` / \`v0.1.0\` / \`v1.0.0\` 之一，按改动幅度选择）。`;
-    const prompt = `阅读以下 git diff，完成两件事：
+    const prompt = `阅读以下输入，完成两件事：
 1. 用${lang}写一条简洁的 commit message（祈使句，不超过 50 字，描述「做了什么」）。
 2. 根据改动幅度推荐下一个语义化版本 tag（破坏性变更 → 升 major；新增功能 → 升 minor；修复 / 文档 / 重构 / 维护 → 升 patch）。${tagHint}
 
 请严格输出**单行 JSON 对象**，不要 Markdown 代码块、不要任何解释文字、不要多余引号。格式：
 {"message":"...","tag":"v1.2.3"}
 
-git diff:
-${diff}`;
+${input}`;
     const raw = await callConfiguredAiText(prompt, cwd, language, ai);
     const parsed = tryParseJson(raw);
     let message;
@@ -717,12 +779,12 @@ ${diff}`;
     }
     return { message, suggestedTag };
 }
-export async function generateCommitMessageOnly(cwd, language, ai = {}) {
+export async function generateCommitMessageOnly(cwd, language, ai = {}, options = {}) {
     if (!cwd || !existsSync(cwd)) {
         throw new QuickCommitError("工作目录不存在。", "CWD_MISSING");
     }
     // Read the working tree as-is. Generating a message must not stage files.
-    return generateCommitMessageWithTag(cwd, language, ai);
+    return generateCommitMessageWithTag(cwd, language, ai, options);
 }
 /**
  * Ask the session provider for a single tag string. Called from `runQuickCommit` after the commit has
@@ -1123,9 +1185,12 @@ async function collectSubmodulesForPush(cwd) {
 }
 function buildFallbackPrompt(opts, priorError) {
     const lang = opts.language.trim() || "中文";
+    const digest = opts.iterationDigest?.trim();
     const messageLine = opts.autoMessage === false
         ? `- 使用这个 commit message：${(opts.customMessage || "").trim()}`
-        : `- 先根据当前 staged/unstaged diff 生成一条简洁的 ${lang} commit message（祈使句，不超过 50 字）`;
+        : digest
+            ? `- 先依据下面「本轮迭代提示词」总结改动，写一条简洁的 ${lang} commit message（祈使句，不超过 50 字）；不需要逐行读 diff`
+            : `- 先根据当前 staged/unstaged diff 生成一条简洁的 ${lang} commit message（祈使句，不超过 50 字）`;
     const tagLine = opts.tag?.trim()
         ? `- 提交后创建 tag：${opts.tag.trim()}`
         : opts.autoTag
@@ -1150,6 +1215,9 @@ function buildFallbackPrompt(opts, priorError) {
         tagLine,
         pushLine,
         submoduleLine,
+        ...(digest && opts.autoMessage !== false
+            ? ["", "本轮迭代提示词（按时间）：", digest, ...(opts.includeDiff ? [] : ["（文件清单请自行用 git status 查看，不必逐行读 diff）"])]
+            : []),
         "",
         `内置流程失败原因：${priorError}`,
         "",
@@ -1341,7 +1409,7 @@ export async function runQuickCommit(opts) {
     }
     let message;
     if (autoMessage) {
-        message = await generateCommitMessage(cwd, language, ai);
+        message = await generateCommitMessage(cwd, language, ai, opts);
     }
     else {
         message = (customMessage || "").trim();

package/dist/iteration-log.d.ts

@@ -0,0 +1,133 @@
+import type { WandStorage } from "./storage.js";
+import { type WandIterationPrompt, type WandIterationPromptSource } from "./task-types.js";
+/** commit 生成的输入模式：iteration = 只用本轮提示词（默认，省 token）；diff = 读完整 diff。 */
+export type CommitContextMode = "iteration" | "diff";
+/** 用户在上次选择后记住的模式；两条互不影响，互相切不会被覆盖。 */
+export declare const COMMIT_CONTEXT_MODE_PREF_KEY = "pref:commitContextMode";
+export declare function isCommitContextMode(value: unknown): value is CommitContextMode;
+/** 读取记住的模式；没存过 / 存坏了就用默认（提示词优先，省 token）。 */
+export declare function readCommitContextMode(storage: WandStorage, override?: unknown): CommitContextMode;
+/** 记录时用到的会话信息：两个 manager 的 snapshot 都满足这个结构。 */
+export interface IterationPromptSession {
+    id: string;
+    cwd?: string;
+    workspaceId?: string;
+    workspaceTaskId?: string;
+}
+export interface IterationPromptTarget {
+    milestoneId: string;
+    /** 这个迭代的名字；UI 上用来显示「本次迭代：默认迭代」。 */
+    milestoneName: string;
+    isDefaultIteration: boolean;
+    workspaceId: string | null;
+    taskId: string | null;
+    repoKey: string | null;
+}
+/** 单次生成的提示词清单上限：够覆盖一轮迭代，又不至于把 prompt 撑爆。 */
+export declare const MAX_ITERATION_PROMPT_ENTRIES = 120;
+/** 提示词清单的总字符预算，超出后从最旧的开始丢。 */
+export declare const MAX_ITERATION_PROMPT_CHARS = 12000;
+/**
+ * 仓库身份：`git rev-parse --git-common-dir` 的绝对路径。
+ * worktree 与主仓库拿到同一个值，因此「同一项目的并行 worktree」会被算成一个仓库。
+ * 结果按目录缓存；拿不到（不是 git 仓库 / 没有 git）时缓存 null，不反复重试。
+ */
+export declare function repoKeyForCwd(cwd: string | undefined | null): Promise<string | null>;
+/** 测试用：清掉目录 → 仓库身份缓存。 */
+export declare function resetRepoKeyCache(): void;
+/**
+ * 这条提示词应该记到哪个迭代下：
+ *   会话绑定的看板任务 → 它所属工作区的任务 → 都没绑就落到默认迭代。
+ * 只有写路径调用，所以这里会惰性把默认迭代建出来。
+ */
+export declare function resolveIterationPromptTarget(storage: WandStorage, session: IterationPromptSession): IterationPromptTarget;
+/** 提示词摘要清洗：去掉控制字符、压空白；保留用户原话，不做二次总结。 */
+export declare function cleanIterationPromptText(value: string): string;
+/** 本地标题：取提示词第一条有效行，不调模型（省一次调用，也不阻塞输入）。 */
+export declare function iterationPromptTitle(prompt: string): string;
+/** 测试用：等待排队中的记录写入全部落地。 */
+export declare function whenIterationPromptsSettled(): Promise<void>;
+/**
+ * 记录一条提示词。调用点都在用户提交输入的热路径上，所以它：
+ *   - 同步过滤没信息量的输入（y / 单条命令 / 斜杠命令），不产生任何 IO；
+ *   - 把真正的写入排进串行队列，不阻塞输入；
+ *   - 永不抛错（记录失败不该影响会话）。
+ */
+export declare function recordIterationPrompt(storage: WandStorage, session: IterationPromptSession, prompt: string, source?: WandIterationPromptSource, options?: {
+    skipFilter?: boolean;
+}): void;
+/** 任务 / 派发这类没有会话输入的入口：直接用任务标题当记录。 */
+export declare function recordIterationPromptForTask(storage: WandStorage, input: {
+    sessionId?: string | null;
+    cwd?: string;
+    workspaceId?: string | null;
+    milestoneId?: string | null;
+    taskId?: string | null;
+    title: string;
+    detail?: string;
+    source: WandIterationPromptSource;
+}): void;
+/**
+ * 把记录拼成给模型看的清单：按时间正序，附时间、标题与摘要；
+ * 已被上一轮提交用掉的条目会被标出来，方便模型少写重复内容。
+ */
+export declare function iterationPromptDigest(entries: readonly WandIterationPrompt[]): string;
+/** 迭代为空时给模型的一句话，避免它把「没有输入」理解成「没有改动」。 */
+export declare const EMPTY_ITERATION_DIGEST_HINT = "\uFF08\u672C\u8FED\u4EE3\u8FD8\u6CA1\u6709\u8BB0\u5F55\u5230\u63D0\u793A\u8BCD\uFF0C\u6539\u4E3A\u4F9D\u636E\u6587\u4EF6\u6539\u52A8\u5224\u65AD\u3002\uFF09";
+/** 默认迭代的名字；UI 与文档共用，避免各处硬编码。 */
+export declare const DEFAULT_ITERATION_LABEL = "\u9ED8\u8BA4\u8FED\u4EE3";
+/** 面板里的一行：就是一条提示词记录 + 是否已被上一轮提交用掉。 */
+export interface IterationCommitEntry {
+    id: string;
+    title: string;
+    detail: string;
+    createdAt: string;
+    consumed: boolean;
+    consumedCommit: string | null;
+    source: WandIterationPromptSource;
+}
+export interface IterationCommitContext {
+    /** 会话当前所属迭代（未选迭代时就是默认迭代）。 */
+    iteration: {
+        id: string;
+        name: string;
+        isDefault: boolean;
+    };
+    repoKey: string | null;
+    /** 面板可展示的条目，新的在前（从上往下看就是「最近改了什么」）。 */
+    entries: IterationCommitEntry[];
+    /** 默认勾选：还没被上一轮提交用掉的那些（= 上次提交以来的变更），时间正序。 */
+    defaultEntryIds: string[];
+    /** 允许提交的 id 全集（比 entries 宽），用于校验前端传回来的勾选。 */
+    selectableIds: string[];
+    /** 是否还有更早的历史没被取到（面板据此提示「更多历史」）。 */
+    truncated: boolean;
+    /** 默认模式下后端会用哪个输入：有未提交提示词就 iteration，否则 diff。 */
+    effectiveMode: CommitContextMode;
+}
+/**
+ * 组装 commit 生成面板要的上下文：
+ *   - 会话 → 迭代（没选迭代就是默认迭代）；
+ *   - 按仓库隔离（同一仓库的 worktree 共享，不混别的项目）；
+ *   - 默认勾选尚未被提交消费的条目，也就是「两次迭代之间」的提示词。
+ * 纯读操作，不写库。
+ */
+export declare function buildIterationCommitContext(storage: WandStorage, input: {
+    session: IterationPromptSession;
+    milestoneId?: string | null;
+    limit?: number;
+}): Promise<IterationCommitContext>;
+/**
+ * 把用户勾选的条目（不传就是默认的「上次提交以来」）转成给模型的输入。
+ *   - `entryIds`：本次算作已提交的条目（提交成功后由调用方标记，构成下一轮的窗口起点）；
+ *     diff 模式下也返回，因为「提交发生了」是仓库事实，不取决于 message 是谁写的。
+ *   - `digest`：空表示调用方应该退回读 diff（切了 diff 模式、或没有可用提示词）。
+ */
+export declare function resolveCommitContextInput(storage: WandStorage, context: IterationCommitContext, body: {
+    mode?: unknown;
+    entryIds?: unknown;
+}): {
+    mode: CommitContextMode;
+    digest: string;
+    entryIds: string[];
+};

package/dist/iteration-log.js

@@ -0,0 +1,293 @@
+// 迭代提示词记录：把「我这一轮迭代到底让 Agent 改了什么」沉淀成一串提示词标题，
+// 供 commit message / 汇报类生成直接引用，不必每次都让模型读 diff（省 token 也更快）。
+//
+// 两条不变式：
+//   1. 记录一定挂在某个真实迭代上；用户没选迭代时落到全局「默认迭代」（惰性创建）。
+//   2. 记录按仓库隔离（repoKey = git 的 common dir）：同一仓库的 worktree 共享，
+//      别的项目的历史不会混进这次 commit message。
+import path from "node:path";
+import { getErrorMessage } from "./error-utils.js";
+import { runGitAsync } from "./git-utils.js";
+import { shouldGenerateSessionTopicFromInput, summarizeSessionTitleFromInput } from "./session-topic.js";
+import { DEFAULT_ITERATION_NAME, WAND_ITERATION_PROMPT_DETAIL_MAX_LENGTH, WAND_ITERATION_PROMPT_TITLE_MAX_LENGTH, } from "./task-types.js";
+/** 用户在上次选择后记住的模式；两条互不影响，互相切不会被覆盖。 */
+export const COMMIT_CONTEXT_MODE_PREF_KEY = "pref:commitContextMode";
+export function isCommitContextMode(value) {
+    return value === "iteration" || value === "diff";
+}
+/** 读取记住的模式；没存过 / 存坏了就用默认（提示词优先，省 token）。 */
+export function readCommitContextMode(storage, override) {
+    if (isCommitContextMode(override))
+        return override;
+    const stored = storage.getPreference(COMMIT_CONTEXT_MODE_PREF_KEY, "iteration");
+    return isCommitContextMode(stored) ? stored : "iteration";
+}
+/** 单次生成的提示词清单上限：够覆盖一轮迭代，又不至于把 prompt 撑爆。 */
+export const MAX_ITERATION_PROMPT_ENTRIES = 120;
+/** 提示词清单的总字符预算，超出后从最旧的开始丢。 */
+export const MAX_ITERATION_PROMPT_CHARS = 12_000;
+const REPO_KEY_TIMEOUT_MS = 5_000;
+const DUPLICATE_WINDOW_MS = 120_000;
+const repoKeyCache = new Map();
+/**
+ * 仓库身份：`git rev-parse --git-common-dir` 的绝对路径。
+ * worktree 与主仓库拿到同一个值，因此「同一项目的并行 worktree」会被算成一个仓库。
+ * 结果按目录缓存；拿不到（不是 git 仓库 / 没有 git）时缓存 null，不反复重试。
+ */
+export async function repoKeyForCwd(cwd) {
+    const directory = path.resolve(cwd?.trim() || "");
+    if (!cwd?.trim())
+        return null;
+    const cached = repoKeyCache.get(directory);
+    if (cached !== undefined)
+        return cached;
+    let key = null;
+    try {
+        key = await runGitAsync(["rev-parse", "--path-format=absolute", "--git-common-dir"], directory, { timeout: REPO_KEY_TIMEOUT_MS }) || null;
+    }
+    catch {
+        // 老版本 git 不认 --path-format：退回 --show-toplevel，至少能把「同一目录树」聚在一起。
+        try {
+            key = await runGitAsync(["rev-parse", "--show-toplevel"], directory, { timeout: REPO_KEY_TIMEOUT_MS }) || null;
+        }
+        catch {
+            key = null;
+        }
+    }
+    repoKeyCache.set(directory, key ?? null);
+    return key ?? null;
+}
+/** 测试用：清掉目录 → 仓库身份缓存。 */
+export function resetRepoKeyCache() {
+    repoKeyCache.clear();
+}
+/**
+ * 这条提示词应该记到哪个迭代下：
+ *   会话绑定的看板任务 → 它所属工作区的任务 → 都没绑就落到默认迭代。
+ * 只有写路径调用，所以这里会惰性把默认迭代建出来。
+ */
+export function resolveIterationPromptTarget(storage, session) {
+    const workspaceTask = session.workspaceTaskId ? storage.getWorkspaceTask(session.workspaceTaskId) : null;
+    // 会话多数是从侧栏任务起的（有 workspaceTaskId），直接按它反查卡片；没绑时才看 wand_task_sessions。
+    const task = workspaceTask
+        ? storage.getWandTaskByWorkspaceTaskId(workspaceTask.id)
+        : (() => {
+            const taskId = storage.getWandTaskIdForSession(session.id);
+            return taskId ? storage.getWandTask(taskId) : null;
+        })();
+    // 任务上的迭代优先，其次看它所属侧栏任务的迭代，最后兜底默认迭代。
+    const explicitId = task?.milestoneId || workspaceTask?.milestoneId || null;
+    const explicit = explicitId ? storage.getWandMilestone(explicitId) : null;
+    // 只有写路径会走到这里，所以可以惰性把默认迭代建出来。
+    const milestone = explicit ?? storage.ensureDefaultWandMilestone();
+    return {
+        milestoneId: milestone.id,
+        milestoneName: milestone.name,
+        isDefaultIteration: milestone.isDefault,
+        workspaceId: session.workspaceId ?? task?.workspaceId ?? workspaceTask?.workspaceId ?? null,
+        taskId: task?.id ?? null,
+        repoKey: null,
+    };
+}
+/** 提示词摘要清洗：去掉控制字符、压空白；保留用户原话，不做二次总结。 */
+export function cleanIterationPromptText(value) {
+    return value
+        .replace(/[\u0000-\u0008\u000b-\u001f\u007f]/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+function clip(value, maxLength) {
+    return value.length > maxLength ? `${value.slice(0, maxLength - 1).trimEnd()}…` : value;
+}
+/** 本地标题：取提示词第一条有效行，不调模型（省一次调用，也不阻塞输入）。 */
+export function iterationPromptTitle(prompt) {
+    const cleaned = cleanIterationPromptText(prompt);
+    if (!cleaned)
+        return "";
+    return clip(summarizeSessionTitleFromInput(cleaned) || cleaned, WAND_ITERATION_PROMPT_TITLE_MAX_LENGTH);
+}
+let writeChain = Promise.resolve();
+/** 测试用：等待排队中的记录写入全部落地。 */
+export function whenIterationPromptsSettled() {
+    return writeChain;
+}
+/**
+ * 记录一条提示词。调用点都在用户提交输入的热路径上，所以它：
+ *   - 同步过滤没信息量的输入（y / 单条命令 / 斜杠命令），不产生任何 IO；
+ *   - 把真正的写入排进串行队列，不阻塞输入；
+ *   - 永不抛错（记录失败不该影响会话）。
+ */
+export function recordIterationPrompt(storage, session, prompt, source = "session", options = {}) {
+    const raw = prompt?.trim();
+    if (!raw)
+        return;
+    // 与会话标题共用同一把尺子：太短的输入不值得进迭代记录。
+    if (!options.skipFilter && !shouldGenerateSessionTopicFromInput(raw))
+        return;
+    const run = async () => {
+        try {
+            const detail = clip(cleanIterationPromptText(raw), WAND_ITERATION_PROMPT_DETAIL_MAX_LENGTH);
+            const title = iterationPromptTitle(raw) || clip(detail, WAND_ITERATION_PROMPT_TITLE_MAX_LENGTH);
+            if (!title)
+                return;
+            const previous = storage.latestIterationPromptForSession(session.id);
+            if (previous
+                && previous.title === title
+                && previous.detail === detail
+                && Date.now() - Date.parse(previous.createdAt) < DUPLICATE_WINDOW_MS) {
+                return;
+            }
+            const target = resolveIterationPromptTarget(storage, session);
+            const repoKey = await repoKeyForCwd(session.cwd);
+            storage.createIterationPrompt({
+                milestoneId: target.milestoneId,
+                workspaceId: target.workspaceId,
+                sessionId: session.id,
+                taskId: target.taskId,
+                repoKey,
+                cwd: session.cwd ?? "",
+                title,
+                detail,
+                source,
+            });
+        }
+        catch (error) {
+            console.error(`[Iteration] Failed to record prompt for session ${session.id}:`, getErrorMessage(error));
+        }
+    };
+    writeChain = writeChain.then(run, run);
+}
+/** 任务 / 派发这类没有会话输入的入口：直接用任务标题当记录。 */
+export function recordIterationPromptForTask(storage, input) {
+    const raw = input.detail?.trim() || input.title.trim();
+    if (!raw)
+        return;
+    const run = async () => {
+        try {
+            const milestone = input.milestoneId
+                ? storage.getWandMilestone(input.milestoneId)
+                : null;
+            const fallback = milestone ?? storage.ensureDefaultWandMilestone();
+            const repoKey = await repoKeyForCwd(input.cwd);
+            storage.createIterationPrompt({
+                milestoneId: fallback.id,
+                workspaceId: input.workspaceId ?? null,
+                sessionId: input.sessionId ?? null,
+                taskId: input.taskId ?? null,
+                repoKey,
+                cwd: input.cwd ?? "",
+                title: clip(cleanIterationPromptText(input.title), WAND_ITERATION_PROMPT_TITLE_MAX_LENGTH),
+                detail: clip(cleanIterationPromptText(raw), WAND_ITERATION_PROMPT_DETAIL_MAX_LENGTH),
+                source: input.source,
+            });
+        }
+        catch (error) {
+            console.error("[Iteration] Failed to record task prompt:", getErrorMessage(error));
+        }
+    };
+    writeChain = writeChain.then(run, run);
+}
+/** `2026-02-14T09:05:00.000Z` → `02-14 09:05`（UTC，稳定可测）。 */
+function shortStamp(iso) {
+    const match = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})/.exec(iso);
+    return match ? `${match[2]}-${match[3]} ${match[4]}:${match[5]}` : iso;
+}
+/**
+ * 把记录拼成给模型看的清单：按时间正序，附时间、标题与摘要；
+ * 已被上一轮提交用掉的条目会被标出来，方便模型少写重复内容。
+ */
+export function iterationPromptDigest(entries) {
+    let budget = MAX_ITERATION_PROMPT_CHARS;
+    const kept = [];
+    // 从最新的往回装：预算不够时丢掉的总是最早的历史，越新的改动越不会丢。
+    for (let index = entries.length - 1; index >= 0 && budget > 0; index -= 1) {
+        const entry = entries[index];
+        const consumed = entry.consumedAt ? "（上一轮已提交）" : "";
+        // 标题往往是详情被裁短的前缀，这时只给详情，避免同一句话重复两遍。
+        const body = entry.detail && entry.detail !== entry.title && !entry.detail.startsWith(entry.title)
+            ? `${entry.title} — ${entry.detail}`
+            : entry.detail || entry.title;
+        const line = `${shortStamp(entry.createdAt)} ${body}${consumed}`;
+        if (line.length > budget && kept.length > 0)
+            break;
+        kept.unshift(line);
+        budget -= line.length + 1;
+    }
+    return kept.map((line, index) => `${index + 1}. ${line}`).join("\n");
+}
+/** 迭代为空时给模型的一句话，避免它把「没有输入」理解成「没有改动」。 */
+export const EMPTY_ITERATION_DIGEST_HINT = `（本迭代还没有记录到提示词，改为依据文件改动判断。）`;
+/** 默认迭代的名字；UI 与文档共用，避免各处硬编码。 */
+export const DEFAULT_ITERATION_LABEL = DEFAULT_ITERATION_NAME;
+function toCommitEntry(entry) {
+    return {
+        id: entry.id,
+        title: entry.title,
+        detail: entry.detail,
+        createdAt: entry.createdAt,
+        consumed: !!entry.consumedAt,
+        consumedCommit: entry.consumedCommit,
+        source: entry.source,
+    };
+}
+/**
+ * 组装 commit 生成面板要的上下文：
+ *   - 会话 → 迭代（没选迭代就是默认迭代）；
+ *   - 按仓库隔离（同一仓库的 worktree 共享，不混别的项目）；
+ *   - 默认勾选尚未被提交消费的条目，也就是「两次迭代之间」的提示词。
+ * 纯读操作，不写库。
+ */
+export async function buildIterationCommitContext(storage, input) {
+    const explicit = input.milestoneId ? storage.getWandMilestone(input.milestoneId) : null;
+    const target = explicit
+        ? { id: explicit.id, name: explicit.name, isDefault: explicit.isDefault }
+        : (() => {
+            const resolved = resolveIterationPromptTarget(storage, input.session);
+            return { id: resolved.milestoneId, name: resolved.milestoneName, isDefault: resolved.isDefaultIteration };
+        })();
+    // 拿不到仓库身份（不是 git 仓库 / 没装 git）时不按仓库过滤，宁可多给几条也不给空面板。
+    const repoKey = await repoKeyForCwd(input.session.cwd);
+    const displayLimit = Math.max(1, Math.min(200, Math.floor(input.limit ?? 60)));
+    // 取「展示窗口」和「未提交集合」两次：展示只要最近的，默认勾选则要拿全。
+    const rows = storage.listIterationPrompts({
+        milestoneId: target.id,
+        repoKey,
+        includeConsumed: true,
+        limit: 200,
+    });
+    const pending = storage.listIterationPrompts({
+        milestoneId: target.id,
+        repoKey,
+        includeConsumed: false,
+        limit: MAX_ITERATION_PROMPT_ENTRIES,
+    });
+    const defaultEntryIds = pending.map((entry) => entry.id);
+    return {
+        iteration: target,
+        repoKey,
+        entries: rows.slice(-displayLimit).reverse().map(toCommitEntry),
+        defaultEntryIds,
+        selectableIds: rows.map((entry) => entry.id),
+        truncated: rows.length >= 200 || pending.length >= MAX_ITERATION_PROMPT_ENTRIES,
+        effectiveMode: defaultEntryIds.length > 0 ? "iteration" : "diff",
+    };
+}
+/**
+ * 把用户勾选的条目（不传就是默认的「上次提交以来」）转成给模型的输入。
+ *   - `entryIds`：本次算作已提交的条目（提交成功后由调用方标记，构成下一轮的窗口起点）；
+ *     diff 模式下也返回，因为「提交发生了」是仓库事实，不取决于 message 是谁写的。
+ *   - `digest`：空表示调用方应该退回读 diff（切了 diff 模式、或没有可用提示词）。
+ */
+export function resolveCommitContextInput(storage, context, body) {
+    const mode = readCommitContextMode(storage, body.mode);
+    const selected = Array.isArray(body.entryIds)
+        ? body.entryIds.filter((id) => typeof id === "string" && id.trim().length > 0)
+        : null;
+    // 只认这个迭代（而且同仓库）里的条目：前端传错 / 传了别的迭代也不会串味。
+    const allowed = new Set(context.selectableIds);
+    const ids = (selected ?? context.defaultEntryIds).filter((id) => allowed.has(id));
+    if (mode !== "iteration" || ids.length === 0)
+        return { mode, digest: "", entryIds: ids };
+    const digest = iterationPromptDigest(storage.listIterationPromptsByIds(ids));
+    return digest ? { mode, digest, entryIds: ids } : { mode, digest: "", entryIds: ids };
+}

package/dist/milestone-scope.d.ts

@@ -4,3 +4,22 @@ import type { WandStorage } from "./storage.js";
  * 调用方负责先校验 id 是否存在。
  */
 export declare function scopedMilestoneId(storage: WandStorage, milestoneId: string | null | undefined, workspaceId: string | null | undefined): string | null;
+/**
+ * 写路径的迭代兑底：用户没选（或没传）迭代就落到默认迭代，
+ * 这样「每个任务都属于一个迭代」在前端和后续 commit 总结里都成立。
+ */
+export declare function defaultMilestoneIdForWrite(storage: WandStorage): string;
+export interface ResolvedTaskMilestone {
+    /** 要展示 / 回传的迭代 id；任务本身没指定时就是默认迭代的 id。 */
+    milestoneId: string | null;
+    milestone: {
+        id: string;
+        name: string;
+        isDefault: boolean;
+    } | null;
+}
+/**
+ * 读出任务该显示的迭代：库里仍然用 NULL 表示「没单独指定」
+ * （历史数据不动，写入时才开始落默认迭代），读的时候统一兑成默认迭代。
+ */
+export declare function resolvedMilestoneFields(storage: WandStorage, milestoneId: string | null | undefined): ResolvedTaskMilestone;