@feng0531/dsh-code-review 0.83.1 → 0.85.0

package/src/review.mjs

@@ -1,6 +1,7 @@
 import { REVIEW_INSTRUCTIONS, PROJECT_REVIEW_INSTRUCTIONS } from './prompts.mjs';
 import { reviewRounds } from './review-rounds.mjs';
 import { correctAnchor } from './anchor-correction.mjs';
+import { correctedResponse } from './response-correction.mjs';
 import { validateBusinessRequirement } from './business-requirement.mjs';
 import { riskReadCoverage } from './risk-read-coverage.mjs';
 import { BUSINESS_GROUP_INSTRUCTIONS, localBusinessGroups, prepareBusinessGroups, validateBusinessGroups } from './business-groups.mjs';
@@ -21,11 +22,13 @@ import { createRetrievalScope } from './retrieval-scope.mjs';
 import { retrievalLoop } from './retrieval-loop.mjs';
 import { preparePrimaryInput } from './primary-input.mjs';
 import { validateAttribution } from './attribution.mjs';
+import { changeScopeLabel } from './git-change-scope.mjs';
 
 export { REVIEW_INSTRUCTIONS };
 export { PROJECT_REVIEW_INSTRUCTIONS };
 const nonempty = value => typeof value === 'string' && value.trim().length > 0 && value.length <= 8000;
 const lines = text => text.replaceAll('\r\n', '\n').split('\n');
+const protocolError = (code, message) => Object.assign(new Error(message), { code });
 
 export function validateFindings(response, file) {
   return validateResponse(response, file);
@@ -34,20 +37,21 @@ export function validateFindings(response, file) {
 function validateResponse(response, file, knownChanges) {
   if (Buffer.byteLength(typeof response === 'string' ? response : JSON.stringify(response) ?? '') > 128 * 1024) throw new Error('Review response too large');
   if (typeof response === 'string') response = JSON.parse(response);
-  if (!response || !Array.isArray(response.findings) || response.findings.length > 50 || !Array.isArray(response.limitations) || response.limitations.length > 50 || response.limitations.some(s => !nonempty(s))) throw new Error('Invalid review response');
+  if (!response || !Array.isArray(response.findings) || response.findings.length > 50 || !Array.isArray(response.limitations) || response.limitations.length > 50 || response.limitations.some(s => !nonempty(s))) throw protocolError('MODEL_INVALID_REVIEW_RESPONSE', 'Invalid review response');
   const changes = knownChanges ?? changeMap(file.left.text, file.right.text);
   const findings = response.findings.map(raw => {
-    if (!raw || raw.fileId !== file.id || !['critical', 'high', 'medium', 'low'].includes(raw.severity)) throw new Error('Invalid finding identity or severity');
-    for (const key of ['title', 'evidence', 'trigger', 'impact', 'suggestion']) if (!nonempty(raw[key])) throw new Error('Missing finding field: ' + key);
+    if (!raw || raw.fileId !== file.id) throw protocolError('MODEL_INVALID_FINDING_IDENTITY', 'Invalid finding identity or severity');
+    if (!['critical', 'high', 'medium', 'low'].includes(raw.severity)) throw protocolError('MODEL_INVALID_FINDING_SEVERITY', 'Invalid finding identity or severity');
+    for (const key of ['title', 'evidence', 'trigger', 'impact', 'suggestion']) if (!nonempty(raw[key])) throw protocolError('MODEL_MISSING_FINDING_FIELD', 'Missing finding field: ' + key);
     const anchor = raw.anchor;
     if(file.reviewMode==='project'&&(anchor?.side==='old'||anchor?.kind==='property'))throw new Error('Project findings require current source evidence');
-    if (!anchor || !['line', 'property', 'file'].includes(anchor.kind)) throw new Error('Invalid anchor');
+    if (!anchor || !['line', 'property', 'file'].includes(anchor.kind)) throw protocolError('MODEL_INVALID_ANCHOR', 'Invalid anchor');
     let validated;
     if (anchor.kind === 'line') {
       const side = anchor.side === 'old' ? file.left : anchor.side === 'new' ? file.right : null;
-      if (!side || !Number.isSafeInteger(anchor.start) || !Number.isSafeInteger(anchor.end) || anchor.start < 1 || anchor.end < anchor.start || !nonempty(anchor.snippet)) throw new Error('Invalid line anchor');
+      if (!side || !Number.isSafeInteger(anchor.start) || !Number.isSafeInteger(anchor.end) || anchor.start < 1 || anchor.end < anchor.start || !nonempty(anchor.snippet)) throw protocolError('MODEL_INVALID_ANCHOR', 'Invalid line anchor');
       const source = lines(side.text);
-      if (anchor.end > source.length || source.slice(anchor.start - 1, anchor.end).join('\n') !== anchor.snippet.replaceAll('\r\n', '\n')) throw new Error('Finding snippet does not match snapshot');
+      if (anchor.end > source.length || source.slice(anchor.start - 1, anchor.end).join('\n') !== anchor.snippet.replaceAll('\r\n', '\n')) throw protocolError('MODEL_ANCHOR_MISMATCH', 'Finding snippet does not match snapshot');
       validated = { kind: 'line', side: anchor.side, start: anchor.start, end: anchor.end, snippet: anchor.snippet };
     } else if (anchor.kind === 'property') {
       if (!file.properties.some(p => p.name === anchor.name)) throw new Error('Unknown changed property');
@@ -111,6 +115,7 @@ export async function reviewSnapshot(snapshot, model, options = {}) {
   }
   if(input.projectScope)report.projectScope=structuredClone(input.projectScope);
   if (input.history) report.history = structuredClone(input.history);
+  if (input.changeScope) report.changeScope = input.changeScope;
   if (input.mergeSources) report.mergeSources = structuredClone(input.mergeSources);
   if(input.workingScope)report.workingScope=structuredClone(input.workingScope);
   if(input.effectiveMergeSources)report.effectiveMergeSources=structuredClone(input.effectiveMergeSources);
@@ -126,7 +131,7 @@ export async function reviewSnapshot(snapshot, model, options = {}) {
     await options.onProgress?.({stage:'file-started',snapshotId:input.id,fileId:file.id,path:file.path,status:state.status});
     if (state.status !== 'pending') continue;
     if (signal?.aborted) { state.status = 'cancelled'; state.reason = '用户取消'; continue; }
-    if (report.modelCalls >= maxCalls) { state.reason = '模型调用预算耗尽'; continue; }
+    if (report.modelCalls >= maxCalls || options.remainingCalls?.() <= 0) { state.reason = '模型调用预算耗尽'; continue; }
     const prepared = preparePrimaryInput(input, file, { instructions, scope, grouping: report.grouping, maxInputBytes });
     const { changes, payload } = prepared;
     Object.assign(state, prepared.metadata);
@@ -139,13 +144,20 @@ export async function reviewSnapshot(snapshot, model, options = {}) {
     if (state.groupFallback) report.limitations.push({ fileId: file.id, text: '关联组上下文超过输入预算，回退单文件审查' });
     if (state.initialInputBytes > maxInputBytes) { state.status = 'blocked'; state.reason = '输入超过预算，未截断或提交模型'; continue; }
     try {
-      const beforeCall = () => {
+      const beforeCall = ({ reserved = false } = {}) => {
+        if (!reserved && options.remainingCalls?.() <= 0) throw Object.assign(new Error('Shared project model call limit exceeded'), { code: 'PROJECT_MODEL_CALL_LIMIT' });
         if (report.modelCalls >= maxCalls) throw new Error('Model call budget exceeded');
         report.modelCalls++;
       };
-      const trackedModel=request=>model({...request,onProtocolEvent:async info=>{await options.onProgress?.({stage:'protocol-correction',fileId:file.id,path:file.path,...info});},onProtocolCorrection:async info=>{beforeCall();await request.onProtocolCorrection?.(info);await options.onProgress?.({stage:'protocol-correction',fileId:file.id,path:file.path,...info});}});
+      const onBudgetLimited = info => {
+        state.retrievalLimited = true;
+        (state.retrievalLimits ??= []).push(info);
+        report.limitations.push({ fileId: file.id, text: '检索预算受限，已保留现有结果但不能视为完整审查：' + info.reason });
+      };
+      const onProtocolEvent = async info => { await options.onProgress?.({ stage: 'protocol-correction', fileId: file.id, path: file.path, ...info }); };
+      const trackedModel=request=>model({...request,onProtocolEvent,onProtocolCorrection:async info=>{beforeCall({ reserved: true });await request.onProtocolCorrection?.(info);await options.onProgress?.({stage:'protocol-correction',fileId:file.id,path:file.path,...info});}});
       const executor = scope
-        ? request => retrievalLoop(trackedModel, request, scope, { correctProtocol:options.correctProtocol===true,maxInputBytes, beforeCall, onRetrieved: records => {
+        ? (request, onLimited = () => {}) => retrievalLoop(trackedModel, { ...request, onProtocolEvent }, scope, { correctProtocol:options.correctProtocol===true,maxInputBytes, beforeCall, onBudgetLimited: info => { onBudgetLimited(info); onLimited(info); }, onRetrieved: records => {
           (state.retrievalAudit ??= []).push(...records);
         }, onTruncated: () => {
           if (!state.retrievalTruncated) report.limitations.push({ fileId: file.id, text: '检索结果达到数量上限，部分匹配未提供给模型' });
@@ -162,7 +174,7 @@ export async function reviewSnapshot(snapshot, model, options = {}) {
             const groupInput = prepareBusinessGroups(input.files);
             if (Buffer.byteLength(groupInput) + Buffer.byteLength(BUSINESS_GROUP_INSTRUCTIONS) > maxInputBytes) throw new Error('Business grouping input budget exceeded');
             beforeCall();
-            const response = await model({ ...enclosingRequest, instructions: BUSINESS_GROUP_INSTRUCTIONS, input: groupInput });
+            const response = await trackedModel({ ...enclosingRequest, instructions: BUSINESS_GROUP_INSTRUCTIONS, input: groupInput });
             enclosingRequest.signal.throwIfAborted();
             grouped = validateBusinessGroups(response, input.files);
             }
@@ -216,30 +228,48 @@ export async function reviewSnapshot(snapshot, model, options = {}) {
         if(report.modelCalls>=maxCalls)throw new Error('Model call budget exceeded before next review pass');
         if(rounds>1) state.reviewPasses[batchIndex].status='running';
         const request = { ...enclosingRequest, input: batchPayload };
-        const auditStart = state.retrievalAudit?.length ?? 0;
-        let response = await executor(request);
-        if (options.enableAnchorCorrection === true) {
-          if (Buffer.byteLength(typeof response === 'string' ? response : JSON.stringify(response)) > 128 * 1024) throw new Error('Review response too large');
-          const decoded = typeof response === 'string' ? JSON.parse(response) : structuredClone(response);
-          if (Array.isArray(decoded?.findings) && decoded.findings.length <= 50) {
-            decoded.findings = decoded.findings.map(raw => {
-              const target = batch.interaction ? input.files.find(f => f.id === raw?.fileId && batch.interaction.fileIds.includes(f.id) && f.eligibility === 'reviewable') : file;
-              if (!target) return raw;
-              const correction = correctAnchor(raw, target, target === file ? changes : changeMap(target.left.text,target.right.text), { signal: request.signal });
-              if (!['unchanged','not-applicable'].includes(correction.status)) (state.anchorCorrections ??= []).push(correction);
-              return correction.status === 'corrected' ? correction.candidate : raw;
-            });
-            response = decoded;
+        let auditStart = state.retrievalAudit?.length ?? 0;
+        let finalResponseOnly = false;
+        const generate = async attempt => {
+          if (!initialInputBudget(attempt, scope, maxInputBytes).fits) throw new Error('Review correction input budget exceeded');
+          return executor(attempt, () => { finalResponseOnly = true; });
+        };
+        const validate = response => {
+          if (options.enableAnchorCorrection === true) {
+            if (Buffer.byteLength(typeof response === 'string' ? response : JSON.stringify(response) ?? '') > 128 * 1024) throw new Error('Review response too large');
+            const decoded = typeof response === 'string' ? JSON.parse(response) : structuredClone(response);
+            if (Array.isArray(decoded?.findings) && decoded.findings.length <= 50) {
+              decoded.findings = decoded.findings.map(raw => {
+                const target = batch.interaction ? input.files.find(f => f.id === raw?.fileId && batch.interaction.fileIds.includes(f.id) && f.eligibility === 'reviewable') : file;
+                if (!target) return raw;
+                const correction = correctAnchor(raw, target, target === file ? changes : changeMap(target.left.text,target.right.text), { signal: request.signal });
+                if (!['unchanged','not-applicable'].includes(correction.status)) (state.anchorCorrections ??= []).push(correction);
+                return correction.status === 'corrected' ? correction.candidate : raw;
+              });
+              response = decoded;
+            }
           }
-        }
+          const generated = batch.interaction ? validateInteractionFindings(response, input, batch.interaction, (state.retrievalAudit ?? []).slice(auditStart), scope.catalog()) : validateResponse(response, file, changes);
+          if (batch.synthesis) validateSynthesisReads(generated.findings, changes, (state.retrievalAudit ?? []).slice(auditStart), scope.catalog(), file.id, input.id);
+          if (!batch.interaction && state.sourceMode === 'change-windows') validateWindowFindings(generated.findings, batch.synthesis ? prepared.synthesis.windows : JSON.parse(batch.payload).windows, batch.synthesis === true);
+          return generated;
+        };
+        const generated = await correctedResponse(generate, validate, request, {
+          enabled: options.correctProtocol === true,
+          canCorrect: () => !finalResponseOnly,
+          onCorrection: async info => {
+            // A fresh generation must establish its own synthesis/interaction read evidence.
+            auditStart = state.retrievalAudit?.length ?? 0;
+            (state.responseCorrections ??= []).push({ code: info.code, round: batch.round, phase });
+            report.limitations.push({ fileId: file.id, text: '主审响应校验失败，已请求一次显式纠正；原响应未接受，纠正不证明缺陷成立。' });
+            await options.onProgress?.({ stage: 'protocol-correction', fileId: file.id, path: file.path, ...info });
+          },
+        });
         if (options.enableRiskPlanning === true && !batch.synthesis && batch.round === 1) {
           const entry=state.riskPlans.at(-1);
           entry.sourceReadCoverage=riskReadCoverage(entry.risks,(state.retrievalAudit??[]).slice(auditStart),scope?.catalog()??[],input.id);
           if(entry.sourceReadCoverage.some(c=>c.unreadSourceIds.length)) report.limitations.push({fileId:file.id,text:'风险计划请求的部分来源未在本次生成阶段读取；不能视为已核查风险条件或排除问题'});
         }
-        const generated = batch.interaction ? validateInteractionFindings(response, input, batch.interaction, (state.retrievalAudit ?? []).slice(auditStart), scope.catalog()) : validateResponse(response, file, changes);
-        if (batch.synthesis) validateSynthesisReads(generated.findings, changes, (state.retrievalAudit ?? []).slice(auditStart), scope.catalog(), file.id, input.id);
-        if (!batch.interaction && state.sourceMode === 'change-windows') validateWindowFindings(generated.findings, batch.synthesis ? prepared.synthesis.windows : JSON.parse(batch.payload).windows, batch.synthesis === true);
         request.signal.throwIfAborted();
         if(rounds>1)generated.findings.forEach(f=>{f.reviewRound=batch.round;});
         report.findings.push(...generated.findings);
@@ -248,8 +278,8 @@ export async function reviewSnapshot(snapshot, model, options = {}) {
         if (options.enableVerification === true && generated.findings.length) {
           for (const finding of generated.findings) finding.verification = { status: 'pending', causality: 'unverified' };
           try {
-            const verdicts = await verificationLoop(trackedModel, request, generated.findings, scope, {
-              correctProtocol:options.correctProtocol===true,maxInputBytes, beforeCall,
+            const verdicts = await verificationLoop(trackedModel, { ...request, onProtocolEvent }, generated.findings, scope, {
+              correctProtocol:options.correctProtocol===true,maxInputBytes, beforeCall, onBudgetLimited,
               onRetrieved: records => { (state.retrievalAudit ??= []).push(...records); },
               onTruncated: () => { report.limitations.push({ fileId: file.id, text: '复核检索结果达到数量上限' }); },
             });
@@ -290,15 +320,17 @@ export async function reviewSnapshot(snapshot, model, options = {}) {
       }, { instructions, input: payload }, timeoutMs, signal);
       if (signal?.aborted) throw signal.reason;
 
-      state.status = 'completed';
+      state.status = state.retrievalLimited ? 'pending' : 'completed';
+      if (state.retrievalLimited) state.reason = '检索预算受限，未完成完整审查；已有发现保留，不表示通过';
 
     } catch (error) {
-      state.status = signal?.aborted ? 'cancelled' : 'failed';
+      state.status = signal?.aborted ? 'cancelled' : error?.code === 'PROJECT_MODEL_CALL_LIMIT' ? 'pending' : 'failed';
       state.reason = error?.message ?? String(error);
       if(error.attempts)state.protocolAttempts=error.attempts;
+      if(error.responseAttempts)state.responseAttempts=error.responseAttempts;
       if(error.diagnostic)state.protocolDiagnostic=error.diagnostic;
       for(const pass of state.reviewPasses??[])if(pass.status==='running')pass.status=signal?.aborted?'cancelled':'failed';
-      state.failureCode = signal?.aborted ? 'CANCELLED' : ['MODEL_INVALID_JSON','MODEL_INCOMPLETE_OUTPUT','MODEL_TIMEOUT','MODEL_INVALID_READ_REQUEST'].includes(error?.code) ? error.code : 'REVIEW_EXECUTION_FAILED';
+      state.failureCode = signal?.aborted ? 'CANCELLED' : ['MODEL_INVALID_JSON','MODEL_INCOMPLETE_OUTPUT','MODEL_TIMEOUT','MODEL_INVALID_READ_REQUEST','MODEL_OUTPUT_LIMIT','MODEL_PROTOCOL_ERROR','MODEL_INVALID_REVIEW_RESPONSE','MODEL_INVALID_FINDING_IDENTITY','MODEL_INVALID_FINDING_SEVERITY','MODEL_MISSING_FINDING_FIELD','MODEL_INVALID_ANCHOR','MODEL_ANCHOR_MISMATCH','READER_CALL_BUDGET_EXCEEDED','READER_OUTPUT_BUDGET_EXCEEDED','RETRIEVAL_ROUND_BUDGET_EXCEEDED','RETRIEVAL_FINAL_RESPONSE_REQUIRED','PROJECT_MODEL_CALL_LIMIT'].includes(error?.code) ? error.code : 'REVIEW_EXECUTION_FAILED';
     }
   }
   await options.onProgress?.({stage:'batch-complete',snapshotId:input.id,files:report.files,findings:report.findings,limitations:report.limitations});
@@ -367,6 +399,7 @@ export function markdownReport(report) {
   if(report.businessRequirement)output.push('- 业务需求：SHA256 '+safe(report.businessRequirement.hash)+' · '+report.businessRequirement.bytes+' bytes；不可信约束，不是证据或权限，全文不在报告重复。');
   for (const file of report.files) for (const correction of file.anchorCorrections ?? []) output.push('- 定位纠正：' + safe(correction.originalCandidate.fileId) + ' · ' + safe(correction.status) + ' · ' + safe(correction.reason) + '；原完整候选保留JSON，仅定位不证明因果');
   if (report.history) output.push('- Git历史审查：' + safe(report.history.mode) + ' · ' + safe(report.history.base ?? 'empty') + ' → ' + safe(report.history.target) + '；精确端点树差异，重命名按增删，不含工作树');
+  if (report.changeScope) output.push('- Git审查范围：' + safe(changeScopeLabel(report.changeScope)) + '；其他范围未审查，未跟踪文件仍默认排除。');
   if (report.businessGrouping) output.push('- 业务分组：' + safe(report.businessGrouping.status) + (report.businessGrouping.reason ? ' — ' + safe(report.businessGrouping.reason) : '') + '；仅调度假设，不证明依赖或覆盖');
   for (const file of report.files) for (const plan of file.riskPlans ?? []) output.push('- 风险计划：' + safe(file.path) + ' · ' + safe(plan.status) + ' · ' + plan.risks.length + '项待证假设；不表示缺陷成立或覆盖完成');
   for (const file of report.files) if(file.reviewPasses)output.push('- 独立审查轮次 '+safe(file.path)+'：'+file.reviewPasses.filter(p=>p.status==='completed').length+'/'+file.reviewPasses.length+'阶段完成；同一生命周期预算，后续轮无首轮计划；不证明代码正确。');

package/src/service.mjs

@@ -5,6 +5,7 @@ import { reviewRounds as validateReviewRounds } from './review-rounds.mjs';
 import { validateCallerScopes } from './caller-index.mjs';
 import { validateBusinessRequirement } from './business-requirement.mjs';
 import { hash } from './content.mjs';
+import { changeScopePreviewNotice } from './git-change-scope.mjs';
 import { resolveWorkspaceRepository } from './workspace-repository.mjs';
 import { randomUUID } from 'node:crypto';
 import { buildCoveragePlan } from './coverage-plan.mjs';
@@ -44,7 +45,8 @@ function describeFile(file, snapshot) {
 
 /** Compose the user-facing preview notice; text is verbatim from the original rules. */
 function buildPreviewNotice(snapshot, options, enableRiskPlanning) {
-  return (snapshot.history?.vcs==='svn'&&options.autoContext===true?'SVN历史autoContext为精确依赖定位读取固定版本父目录有界清单，包含同目录非匹配名字元数据；仅匹配捕获正文发送模型，不扫描全仓，不用工作树替代历史版本。':'') + (options.oldContextPaths !== undefined ? 'oldContextPaths仅为baseline旧侧正文，无目标侧替代；选中变更复用原old身份，旧侧不能证明新侧行为。' : '') + (snapshot.callerDiscovery ? 'callerScopePaths已授权预览读取限定目录内tracked候选正文，包括不匹配文件；非匹配正文不发送模型，匹配捕获上下文会发送。仅字面引用导航，不是函数调用或完整调用覆盖。' : '') + (enableRiskPlanning ? '执行按plan阈值决定风险假设规划，小变更可跳过独立规划但仍主审并复核；计划不是证据，所有阶段共享原预算。' : '') + '执行会向上述模型提供方发送可审查文件两侧内容、预览列出的显式/自动上下文、所选项目规则全文及预览业务需求文本。模型可在该快照范围内多轮只读检索，不读取范围外文件；候选生成后会进行证据与反证复核，两阶段各最多3轮检索，不设插件内部默认时间或总模型调用次数截止，遵循宿主/用户取消；输入字节和检索轮次保护仍保留；复核不能证明缺陷成立。plan.reviewRounds为独立审查工作量，非模型reasoning effort；后续轮不带首轮风险计划，所有轮共享原超时与预算。plan仅预检初始输入，ready不代表已审查；minimumCalls不含后续检索/复核/动态业务综合；多文件可先进行业务分组，分组失败保留原组并记录限制，动态综合数执行前未知，实际预算可能不足。请先向用户展示范围，获得确认后执行。';
+  const scopeNotice = options.changeScope !== undefined && options.changeScope !== 'worktree' ? changeScopePreviewNotice(options.changeScope) : '';
+  return scopeNotice + (snapshot.history?.vcs==='svn'&&options.autoContext===true?'SVN历史autoContext为精确依赖定位读取固定版本父目录有界清单，包含同目录非匹配名字元数据；仅匹配捕获正文发送模型，不扫描全仓，不用工作树替代历史版本。':'') + (options.oldContextPaths !== undefined ? 'oldContextPaths仅为baseline旧侧正文，无目标侧替代；选中变更复用原old身份，旧侧不能证明新侧行为。' : '') + (snapshot.callerDiscovery ? 'callerScopePaths已授权预览读取限定目录内tracked候选正文，包括不匹配文件；非匹配正文不发送模型，匹配捕获上下文会发送。仅字面引用导航，不是函数调用或完整调用覆盖。' : '') + (enableRiskPlanning ? '执行按plan阈值决定风险假设规划，小变更可跳过独立规划但仍主审并复核；计划不是证据，所有阶段共享原预算。' : '') + '执行会向上述模型提供方发送可审查文件两侧内容、预览列出的显式/自动上下文、所选项目规则全文及预览业务需求文本。模型可在该快照范围内多轮只读检索，不读取范围外文件；候选生成后会进行证据与反证复核，两阶段各最多3轮检索，不设插件内部默认时间或总模型调用次数截止，遵循宿主/用户取消；输入字节和检索轮次保护仍保留；复核不能证明缺陷成立。plan.reviewRounds为独立审查工作量，非模型reasoning effort；后续轮不带首轮风险计划，所有轮共享原超时与预算。plan仅预检初始输入，ready不代表已审查；minimumCalls不含后续检索/复核/动态业务综合；多文件可先进行业务分组，分组失败保留原组并记录限制，动态综合数执行前未知，实际预算可能不足。请先向用户展示范围，获得确认后执行。';
 }
 
 function createSessionReviewService(llm, { capture = captureSnapshot, now = Date.now, ttlMs = 300000, maxPreviews = 8, allowModelSending = false, enableRiskPlanning = false, skipSmallRiskPlans = true, reviewRounds = 1, enableBusinessGrouping = false, enableAnchorCorrection = false, authorize = async () => false } = {}) {
@@ -59,7 +61,7 @@ function createSessionReviewService(llm, { capture = captureSnapshot, now = Date
       exec = bind(exec);
       exec.signal.throwIfAborted();
       if (busy) throw new Error('Review service busy');
-      if (!args || Object.keys(args).some(k => !['repositoryPath', 'selectedPaths', 'contextPaths', 'rulePaths', 'autoContext', 'commit', 'baseRevision', 'targetRevision','businessRequirement','callerScopePaths','oldContextPaths','reviewRounds','svnRevision','svnBaseRevision','svnTargetRevision','svnAllowNetwork','svnEffectiveMergeinfo','svnBasePath','svnTargetPath','svnReplacementBaseRevision','svnReplacementAllowNetwork'].includes(k))) throw new Error('Unknown preview argument');
+      if (!args || Object.keys(args).some(k => !['repositoryPath', 'selectedPaths', 'contextPaths', 'rulePaths', 'autoContext', 'commit', 'baseRevision', 'targetRevision','businessRequirement','callerScopePaths','oldContextPaths','reviewRounds','svnRevision','svnBaseRevision','svnTargetRevision','svnAllowNetwork','svnEffectiveMergeinfo','svnBasePath','svnTargetPath','svnReplacementBaseRevision','svnReplacementAllowNetwork','changeScope'].includes(k))) throw new Error('Unknown preview argument');
       if (args.autoContext !== undefined && typeof args.autoContext !== 'boolean') throw new Error('Invalid autoContext option');
       for (const key of ['selectedPaths', 'contextPaths', 'rulePaths', 'oldContextPaths']) if (args[key] !== undefined && (!Array.isArray(args[key]) || args[key].length > (key === 'rulePaths' ? 4 : key === 'oldContextPaths' ? 20 : 200) || args[key].some(p => typeof p !== 'string'))) throw new Error('Invalid path list');
       const rounds=validateReviewRounds(args.reviewRounds === undefined ? reviewRounds : args.reviewRounds);
@@ -87,6 +89,7 @@ function createSessionReviewService(llm, { capture = captureSnapshot, now = Date
   snapshotId: snapshot.id,
   repositoryRoot: snapshot.root,
   vcs: snapshot.vcs,
+  ...(snapshot.changeScope ? { changeScope: snapshot.changeScope } : options.changeScope !== undefined ? { changeScope: options.changeScope } : {}),
   ...(snapshot.workingScope ? { workingScope: snapshot.workingScope } : {}),
   ...(snapshot.history ? { history: snapshot.history } : {}),
   ...(snapshot.mergeSources ? { mergeSources: snapshot.mergeSources } : {}),

package/src/snapshot-reader.mjs

@@ -14,6 +14,12 @@ function validQuery(query, limit) {
   return typeof query === 'string' && query.length > 0 && query.length <= 256 && !/[\r\n]/.test(query) && Number.isSafeInteger(limit) && limit >= 1 && limit <= 100;
 }
 
+function budgetError(kind) {
+  const error = new Error('Reader ' + kind + ' budget exceeded');
+  error.code = kind === 'call' ? 'READER_CALL_BUDGET_EXCEEDED' : 'READER_OUTPUT_BUDGET_EXCEEDED';
+  return error;
+}
+
 // This capability reads only caller-approved text entries, never the filesystem.
 export function createSnapshotReader(snapshotId, entries, { maxBytes = 4 * 1024 * 1024, maxCalls = 50, maxOutputBytes = 256 * 1024, signal } = {}) {
   if (typeof snapshotId !== 'string' || !snapshotId || snapshotId.length > 200) throw new Error('Invalid snapshot identity');
@@ -24,16 +30,21 @@ export function createSnapshotReader(snapshotId, entries, { maxBytes = 4 * 1024
   }
   signal?.throwIfAborted();
 
-  let calls = 0, outputBytes = 0;
+  let calls = 0, outputBytes = 0, inTransaction = false;
   const begin = () => {
     signal?.throwIfAborted();
-    if (calls >= maxCalls) throw new Error('Reader call budget exceeded');
+    if (calls >= maxCalls) throw budgetError('call');
     calls++;
   };
+  const resultSize = result => {
+    const size = Buffer.byteLength(JSON.stringify(result));
+    if (size > 64 * 1024) throw budgetError('output');
+    return size;
+  };
   const finish = result => {
     signal?.throwIfAborted();
-    const size = Buffer.byteLength(JSON.stringify(result));
-    if (size > 64 * 1024 || outputBytes + size > maxOutputBytes) throw new Error('Reader output budget exceeded');
+    const size = resultSize(result);
+    if (outputBytes + size > maxOutputBytes) throw budgetError('output');
     outputBytes += size;
     return result;
   };
@@ -47,55 +58,91 @@ export function createSnapshotReader(snapshotId, entries, { maxBytes = 4 * 1024
     sources.set(entry.id, { path: entry.path, side: entry.side, text: entry.text, hash: createHash('sha256').update(entry.text).digest('hex') });
   }
 
+  const find = ({ query, limit = 20 }) => {
+    if (!validQuery(query, limit)) throw new Error('Invalid find request');
+    const matches = [];
+    for (const [id, source] of sources) {
+      signal?.throwIfAborted();
+      if (typeof source.path !== 'string' || !source.path.includes(query)) continue;
+      if (matches.length === limit) return { snapshotId, matches, truncated: true };
+      matches.push({ sourceId: id, path: source.path, side: source.side, hash: source.hash });
+    }
+    return { snapshotId, matches, truncated: false };
+  };
+  const search = ({ query, limit = 20, sourceIds }) => {
+    if (!validQuery(query, limit)) throw new Error('Invalid search request');
+    if (sourceIds !== undefined && (!Array.isArray(sourceIds) || !sourceIds.length || sourceIds.length > 20 || new Set(sourceIds).size !== sourceIds.length || sourceIds.some(id => !sources.has(id)))) throw new Error('Invalid search source filter');
+    const selected = sourceIds === undefined ? null : new Set(sourceIds);
+    const matches = [];
+    for (const [id, source] of sources) {
+      if (selected && !selected.has(id)) continue;
+      signal?.throwIfAborted();
+      for (const range of lineRanges(source.text)) {
+        if (!source.text.slice(range.start, range.end).includes(query)) continue;
+        if (matches.length === limit) return { snapshotId, matches, truncated: true };
+        matches.push({ sourceId: id, hash: source.hash, line: range.line });
+      }
+    }
+    return { snapshotId, matches, truncated: false };
+  };
+  const read = ({ id, start, count }) => {
+    if (!sources.has(id)) throw new Error('Source not authorized');
+    if (!Number.isSafeInteger(start) || start < 1 || !Number.isSafeInteger(count) || count < 1 || count > 200) throw new Error('Invalid line range');
+    const source = sources.get(id);
+    let beginOffset = -1, endOffset = 0, selectedCount = 0;
+    for (const range of lineRanges(source.text)) {
+      if (range.line < start) continue;
+      if (beginOffset < 0) beginOffset = range.start;
+      endOffset = range.end;
+      selectedCount++;
+      if (selectedCount === count) break;
+    }
+    if (beginOffset < 0) throw new Error('Line range outside source');
+    const text = source.text.slice(beginOffset, endOffset);
+    if (Buffer.byteLength(text) > 64 * 1024) throw budgetError('output');
+    return { snapshotId, sourceId: id, hash: source.hash, start, count: selectedCount, text, endOfSource: endOffset === source.text.length };
+  };
+
   return Object.freeze({
     usage: () => ({ calls, outputBytes }),
-    find({ query, limit = 20 }) {
-      begin();
-      if (!validQuery(query, limit)) throw new Error('Invalid find request');
-      const matches = [];
-      for (const [id, source] of sources) {
+    budget: () => ({ maxCalls, maxOutputBytes, remainingCalls: maxCalls - calls, remainingOutputBytes: maxOutputBytes - outputBytes, maxResultBytes: 64 * 1024 }),
+    // A synchronous host-only batch commits its ledger only as a whole. This
+    // also covers decorated response bytes that preflight cannot predict.
+    // Callers must not publish results/audit records before this returns.
+    transaction(execute) {
+      signal?.throwIfAborted();
+      if (inTransaction || typeof execute !== 'function') throw new Error('Invalid reader transaction');
+      const previousCalls = calls, previousBytes = outputBytes;
+      inTransaction = true;
+      try {
+        const result = execute();
+        if (result && typeof result.then === 'function') throw new Error('Invalid asynchronous reader transaction');
         signal?.throwIfAborted();
-        if (typeof source.path !== 'string' || !source.path.includes(query)) continue;
-        if (matches.length === limit) return finish({ snapshotId, matches, truncated: true });
-        matches.push({ sourceId: id, path: source.path, side: source.side, hash: source.hash });
-      }
-      return finish({ snapshotId, matches, truncated: false });
+        return result;
+      } catch (error) {
+        calls = previousCalls; outputBytes = previousBytes;
+        throw error;
+      } finally { inTransaction = false; }
     },
-    search({ query, limit = 20, sourceIds }) {
-      begin();
-      if (!validQuery(query, limit)) throw new Error('Invalid search request');
-      if (sourceIds !== undefined && (!Array.isArray(sourceIds) || !sourceIds.length || sourceIds.length > 20 || new Set(sourceIds).size !== sourceIds.length || sourceIds.some(id => !sources.has(id)))) throw new Error('Invalid search source filter');
-      const selected = sourceIds === undefined ? null : new Set(sourceIds);
-      const matches = [];
-      for (const [id, source] of sources) {
-        if (selected && !selected.has(id)) continue;
-        signal?.throwIfAborted();
-        for (const range of lineRanges(source.text)) {
-          if (!source.text.slice(range.start, range.end).includes(query)) continue;
-          if (matches.length === limit) return finish({ snapshotId, matches, truncated: true });
-          matches.push({ sourceId: id, hash: source.hash, line: range.line });
-        }
-      }
-      return finish({ snapshotId, matches, truncated: false });
+    // Host-only dry run. Validate ALL ranges and sources before charging anything.
+    // No evidence or receipts escape this preflight. Decorated reads are still
+    // measured by finish; this never reserves or increases the shared budget.
+    preflight(requests) {
+      signal?.throwIfAborted();
+      if (!Array.isArray(requests) || !requests.length || requests.length > 8) throw new Error('Invalid retrieval batch');
+      const results = requests.map(request => {
+        if (request?.kind === 'read') return read(request);
+        if (request?.kind === 'find') return find(request);
+        if (request?.kind === 'search') return search(request);
+        throw new Error('Unsupported retrieval operation');
+      });
+      if (calls + requests.length > maxCalls) throw budgetError('call');
+      const size = results.reduce((sum, result) => sum + resultSize(result), 0);
+      if (outputBytes + size > maxOutputBytes) throw budgetError('output');
     },
+    find(request) { begin(); return finish(find(request)); },
+    search(request) { begin(); return finish(search(request)); },
     // decorate is a host-only callback; model requests never supply it.
-    read({ id, start, count }, decorate = value => value) {
-      begin();
-      if (!sources.has(id)) throw new Error('Source not authorized');
-      if (!Number.isSafeInteger(start) || start < 1 || !Number.isSafeInteger(count) || count < 1 || count > 200) throw new Error('Invalid line range');
-      const source = sources.get(id);
-      let beginOffset = -1, endOffset = 0, selectedCount = 0;
-      for (const range of lineRanges(source.text)) {
-        if (range.line < start) continue;
-        if (beginOffset < 0) beginOffset = range.start;
-        endOffset = range.end;
-        selectedCount++;
-        if (selectedCount === count) break;
-      }
-      if (beginOffset < 0) throw new Error('Line range outside source');
-      const text = source.text.slice(beginOffset, endOffset);
-      if (Buffer.byteLength(text) > 64 * 1024) throw new Error('Reader output budget exceeded');
-      return finish(decorate({ snapshotId, sourceId: id, hash: source.hash, start, count: selectedCount, text, endOfSource: endOffset === source.text.length }));
-    },
+    read(request, decorate = value => value) { begin(); return finish(decorate(read(request))); },
   });
 }

package/src/snapshot.mjs

@@ -16,6 +16,7 @@ import { captureProjectRules } from './project-rules.mjs';
 import { captureSvn } from './svn.mjs';
 import { captureSvnHistory } from './svn-history.mjs';
 import { readLocal, relativePath, hash } from './content.mjs';
+import { CHANGE_SCOPES } from './git-change-scope.mjs';
 
 export async function detectVcs(cwd) {
   let current = await realpath(cwd);
@@ -50,6 +51,11 @@ export async function captureSnapshot(cwd, options = {}) {
   const { rulePaths, contextPaths, maxContextFiles, maxSnapshotBytes } = validateSnapshotOptions(options);
 
   const type = await detectVcs(cwd);
+  if (options.changeScope !== undefined) {
+    if (typeof options.changeScope !== 'string' || !CHANGE_SCOPES.includes(options.changeScope)) throw new Error('Invalid changeScope; expected worktree, staged or unstaged');
+    if (['commit', 'baseRevision', 'targetRevision', 'svnRevision', 'svnBaseRevision', 'svnTargetRevision', 'svnBasePath', 'svnTargetPath'].some(key => options[key] !== undefined)) throw new Error('changeScope applies to Git working-copy comparison only');
+    if (type !== 'git') throw new Error('changeScope requires a Git working copy');
+  }
   const replacementOptions = options.svnReplacementBaseRevision !== undefined || options.svnReplacementAllowNetwork !== undefined;
   if (replacementOptions) {
     if (type !== 'svn' || ['svnRevision', 'svnBaseRevision', 'svnTargetRevision', 'svnBasePath', 'svnTargetPath', 'commit', 'baseRevision', 'targetRevision'].some(key => options[key] !== undefined)) throw new Error('Replacement repository baseline requires SVN working-copy mode');