helloloop 0.3.1 → 0.7.0

package/hosts/gemini/extension/commands/helloloop.toml

@@ -1,17 +1,20 @@
-description = "根据开发文档分析当前进度、生成确认单，并在确认后继续接续开发"
+description = "仅在用户显式调用 `/helloloop` 后，根据开发文档分析当前进度、生成确认单，并在确认后继续接续开发"
 prompt = """
 你现在正在执行 HelloLoop 的 Gemini CLI 原生工作流。
 
 执行要求：
 
-1. 自动识别目标仓库与开发文档；如果用户在命令后提供了参数，必须同时保留其中的显式路径和自然语言补充要求，不要靠固定关键词硬编码判断。
-2. 如果当前目录没有明确开发文档，应先展示顶层文档文件、顶层目录和疑似项目目录，再询问用户开发文档路径。
-3. 项目路径对外只有一个概念；如果用户给出的项目路径不存在，直接按新项目路径处理，不要再单独追问“新项目路径”。
-4. 分析当前代码与开发文档之间的真实进度和偏差，并判断当前项目目录与开发文档目标是否匹配。
-5. 在目标仓库根目录创建或刷新 `.helloloop/`，至少维护 `backlog.json`、`project.json`、`status.json`、`STATE.md` 与 `runs/`。
-6. 在真正开发前，必须输出中文执行确认单，至少包含：
+1. 只有当用户显式调用 `/helloloop`，或明确要求“使用 HelloLoop / 走 HelloLoop 流程”时，才进入当前工作流；不要接管普通 Gemini 会话。
+2. 自动识别目标仓库与开发文档；如果用户在命令后提供了参数，必须同时保留其中的显式路径和自然语言补充要求，不要靠固定关键词硬编码判断。
+3. 当前宿主是 `Gemini`；如果用户未明确指定执行引擎，必须先确认本轮引擎，`Gemini` 只可作为推荐项，不允许自动选中；如果用户明确要求改用 `Codex` 或 `Claude`，必须先确认，不允许静默切换。
+3. 如果当前目录没有明确开发文档，应先展示顶层文档文件、顶层目录和疑似项目目录，再询问用户开发文档路径。
+4. 项目路径对外只有一个概念；如果用户给出的项目路径不存在，直接按新项目路径处理，不要再单独追问“新项目路径”。
+5. 分析当前代码与开发文档之间的真实进度和偏差，并判断当前项目目录与开发文档目标是否匹配。
+6. 在目标仓库根目录创建或刷新 `.helloloop/`，至少维护 `backlog.json`、`project.json`、`status.json`、`STATE.md` 与 `runs/`。
+7. 在真正开发前，必须输出中文执行确认单，至少包含：
    - 路径判断与判断依据
    - 本次命令补充输入
+   - 执行引擎
    - 需求语义理解
    - 项目匹配判断
    - 目标仓库
@@ -23,9 +26,11 @@ prompt = """
    - 首个待执行任务
    - 验证命令预览
    - 自动执行停止条件
-7. 如果当前项目目录已存在，但分析认为它与开发文档目标明显冲突，必须先明确提示用户，并确认是继续现有项目、还是清理后按文档重建。
-8. 用户未确认前，不要开始正式修改代码。
-9. 用户确认后，继续用 Gemini CLI 原生工具推进 backlog，直到开发文档的最终目标完成，且相关测试、验证、验收都已通过；遇到硬阻塞或需要用户补充关键信息时再停下。
-10. 如果用户给了开发文档但找不到项目仓库，或给了项目路径但找不到开发文档，必须停下来询问。
-11. Windows 上优先用安全的文件与 shell 操作；禁止危险删除、硬重置、强推和其他破坏性命令。
+8. 如果当前项目目录已存在，但分析认为它与开发文档目标明显冲突，必须先明确提示用户，并确认是继续现有项目、还是清理后按文档重建。
+9. 用户未确认前，不要开始正式修改代码。
+10. 用户确认后，继续用当前确认的执行引擎原生工具推进 backlog；每个任务完成后还要再做任务完成复核，backlog 清空后还要再做主线终态复核，直到开发文档的最终目标完成，且相关测试、验证、验收都已通过；遇到硬阻塞或需要用户补充关键信息时再停下。
+11. 如果当前引擎在运行中遇到 400、鉴权、余额、429、5xx、网络抖动、流中断或长时间卡死，必须优先按无人值守策略做同引擎“健康探测 + 条件恢复”，不要中途停下来询问用户，也不要自动切换引擎；只有自动恢复额度真正用尽时才停止。
+12. 如果用户给了开发文档但找不到项目仓库，或给了项目路径但找不到开发文档，必须停下来询问。
+13. 用户需求明确且当前任务可直接完成时，必须一次性完成本轮应交付的全部工作；禁止做一半后用“如果你要”“是否继续”之类的话术停下，也禁止用“希望这对你有帮助”等套话收尾。
+14. Windows 上优先用安全的文件与 shell 操作；禁止危险删除、硬重置、强推和其他破坏性命令。
 """

package/hosts/gemini/extension/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "helloloop",
-  "version": "0.3.1",
+  "version": "0.7.0",
   "description": "HelloLoop 的 Gemini CLI 原生扩展，用于按开发文档接续推进项目开发。",
   "contextFileName": "GEMINI.md",
   "excludeTools": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "helloloop",
-  "version": "0.3.1",
+  "version": "0.7.0",
   "description": "面向 Codex CLI、Claude Code、Gemini CLI 的多宿主开发工作流插件",
   "author": "HelloLoop",
   "license": "Apache-2.0",
@@ -30,7 +30,7 @@
     "templates"
   ],
   "scripts": {
-    "test": "node --test tests/analyze_cli.test.mjs tests/analyze_intent_cli.test.mjs tests/cli_surface.test.mjs tests/install_script.test.mjs tests/process_shell.test.mjs tests/prompt_guardrails.test.mjs tests/ralph_loop.test.mjs tests/plugin_bundle.test.mjs"
+    "test": "node --test tests/analyze_cli.test.mjs tests/analyze_intent_cli.test.mjs tests/engine_selection_cli.test.mjs tests/cli_surface.test.mjs tests/cli_doctor_surface.test.mjs tests/host_lifecycle_integrity.test.mjs tests/host_single_host_integrity.test.mjs tests/install_script.test.mjs tests/mainline_continuation.test.mjs tests/multi_host_runtime.test.mjs tests/process_shell.test.mjs tests/prompt_guardrails.test.mjs tests/ralph_loop.test.mjs tests/runtime_recovery.test.mjs tests/plugin_bundle.test.mjs"
   },
   "engines": {
     "node": ">=20"

package/skills/helloloop/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: helloloop
-description: 当用户希望 Codex 先分析仓库当前进度、生成确认单，再自动按 backlog 持续接续开发时使用。
+description: 仅当用户显式调用 `$helloloop` / `#helloloop` / `helloloop:helloloop`，或明确要求使用 HelloLoop 按开发文档持续接续开发时使用。
 ---
 
 # HelloLoop
@@ -9,7 +9,9 @@ description: 当用户希望 Codex 先分析仓库当前进度、生成确认单
 
 ## 强制入口规则
 
-- 用户显式调用 `$helloloop` / `#helloloop` / `helloloop:helloloop` 时，默认必须优先执行 `npx helloloop` 或 `npx helloloop <PATH>`。
+- 未显式调用 `helloloop`，且用户也没有明确要求“使用 HelloLoop / 使用 helloloop 插件 / 走 HelloLoop 流程”时，不允许接管普通 Codex 会话。
+- 用户显式调用 `$helloloop` / `#helloloop` / `helloloop:helloloop` 时，默认必须优先执行 `npx helloloop` 或 `npx helloloop <PATH>`；如果用户又明确指定了执行引擎，也允许使用 `npx helloloop codex|claude|gemini ...`。
+- 用户没有明确指定执行引擎时，不允许由 skill 自行补成 `codex` / `claude` / `gemini`；必须让 `HelloLoop` 先完成引擎确认。
 - 不允许在对话里手工模拟 `HelloLoop` 的分析、确认单、backlog 编排和自动续跑流程来代替 CLI。
 - 只有在以下情况，才允许先停下来问用户而不是直接执行 CLI：
   1. 用户既没有给路径，当前目录也无法判断项目仓库或开发文档
@@ -19,10 +21,12 @@ description: 当用户希望 Codex 先分析仓库当前进度、生成确认单
 
 ## `$helloloop` 的默认执行映射
 
-- 当前目录已经是目标项目仓库或开发文档目录 → 先执行 `npx helloloop`
-- 用户给了单一路径 → 先执行 `npx helloloop <PATH>`
+- 当前目录已经是目标项目仓库或开发文档目录 → 先执行 `npx helloloop --host-context codex`
+- 用户给了单一路径 → 先执行 `npx helloloop --host-context codex <PATH>`
 - 用户明确只想先看分析和确认单 → 执行 `npx helloloop --dry-run`
 - 用户明确要求跳过确认直接开始 → 执行 `npx helloloop -y`
+- 用户未明确指定执行引擎 → 保持命令里不带引擎首参数，让 `HelloLoop` 先做引擎确认；当前宿主只作为推荐依据
+- 用户明确指定执行引擎 → 保留该引擎首参数；如果在 `Codex` 宿主内要求改用 `Claude` / `Gemini`，先确认，不允许静默切换
 - 用户在命令后附带了额外路径或自然语言要求 → 必须把这些附加内容一并传给主 CLI，不允许丢弃或手工改写
 
 ## 附加输入处理规则
@@ -57,7 +61,7 @@ description: 当用户希望 Codex 先分析仓库当前进度、生成确认单
 2. 打开目标项目仓库目录，或者打开开发文档所在目录。
 3. 运行 `npx helloloop` 或 `npx helloloop <PATH>`。
 4. 命中 `$helloloop` 后，优先按上面的默认执行映射直接调用 CLI。
-5. `HelloLoop` 会先自动分析，再输出执行确认单。
+5. `HelloLoop` 会先明确执行引擎，再自动分析并输出执行确认单。
 6. 用户确认后，`HelloLoop` 才开始正式自动执行。
 
 如果无法自动判断仓库路径或开发文档路径，就停下来提示用户补充；`--repo` 和 `--docs` 只作为显式覆盖选项使用。
@@ -67,14 +71,21 @@ description: 当用户希望 Codex 先分析仓库当前进度、生成确认单
 - 代码是事实源，开发文档是目标源。
 - `HelloLoop` 会先分析当前真实进度，再生成或刷新 `.helloloop/backlog.json`。
 - 分析后会展示中文执行确认单，明确告知路径判断、语义理解、项目匹配、当前进度、待办任务、验证命令和执行边界。
-- 用户确认后，默认会持续执行到 backlog 清空，或开发文档的最终目标完成且测试、验收通过，或遇到硬阻塞。
-- 真正的代码分析与实现仍由本机 `codex` CLI 完成。
+- 用户确认后，默认会持续执行到 backlog 清空且主线终态复核通过，或开发文档的最终目标完成且测试、验收通过，或遇到硬阻塞。
+- 每个任务在执行引擎声称“完成”后，还必须再过一层任务完成复核；如果只是部分完成，继续当前主线任务，不直接结束。
+- 用户需求明确且当前任务可直接完成时，必须一次性完成本轮应交付的全部工作；禁止做一半后用“如果你要”“是否继续”之类的话术停下，也禁止用客套套话收尾。
+- 真正的代码分析与实现由本轮选中的 `codex` / `claude` / `gemini` CLI 原生完成。
+- 如果当前引擎在运行中遇到 400、鉴权、余额、429、5xx、网络抖动、流中断或长时间卡死，必须优先按无人值守策略做同引擎“健康探测 + 条件恢复”，不要中途停下来询问用户，也不要自动切换引擎。
+- 只有当硬阻塞或软阻塞的自动恢复额度真正用尽时，才允许结束本轮自动执行；若用户已在 `~/.helloloop/settings.json` 配置邮箱通知，则结束前发送告警邮件。
 - `$helloloop` 的职责是把用户请求路由到主 CLI 流程，而不是在对话里手工复刻一套平行流程。
 
 ## 核心命令
 
 - `npx helloloop`
 - `npx helloloop <PATH>`
+- `npx helloloop codex`
+- `npx helloloop claude <PATH>`
+- `npx helloloop gemini <PATH> <补充说明>`
 - `npx helloloop <PATH> <补充说明>`
 - `npx helloloop --dry-run`
 - `npx helloloop -y`

package/src/analyze_confirmation.mjs

@@ -3,6 +3,7 @@ import path from "node:path";
 import { renderInputIssueLines, renderUserIntentLines } from "./analyze_user_input.mjs";
 import { analyzeExecution, summarizeBacklog } from "./backlog.mjs";
 import { loadPolicy, loadVerifyCommands } from "./config.mjs";
+import { getEngineDisplayName } from "./engine_metadata.mjs";
 
 function toDisplayPath(repoRoot, targetPath) {
   const absolutePath = path.resolve(targetPath);
@@ -133,15 +134,35 @@ function renderRepoDecisionLines(analysis) {
   ];
 }
 
+function renderEngineResolutionLines(engineResolution) {
+  if (!engineResolution?.engine) {
+    return [];
+  }
+
+  const availableDisplay = Array.isArray(engineResolution.availableEngines) && engineResolution.availableEngines.length
+    ? engineResolution.availableEngines.map((engine) => getEngineDisplayName(engine)).join("、")
+    : "未检测到其他可用引擎";
+  const basisText = Array.isArray(engineResolution.basis) && engineResolution.basis.length
+    ? engineResolution.basis.join("；")
+    : "无";
+
+  return [
+    "执行引擎：",
+    `- 当前宿主：${engineResolution.hostDisplayName || "终端"}`,
+    `- 本次引擎：${engineResolution.displayName || getEngineDisplayName(engineResolution.engine)}`,
+    `- 选择来源：${engineResolution.sourceLabel || "自动判断"}`,
+    `- 选择依据：${basisText}`,
+    `- 当前可用：${availableDisplay}`,
+    "- 故障处理：运行中若遇到 429、5xx、网络抖动、流中断或长时间卡死，HelloLoop 会优先按无人值守策略做同引擎自动恢复；只有明确硬阻塞才停止",
+  ];
+}
+
 export function resolveAutoRunMaxTasks(backlog, options = {}) {
   const explicitMaxTasks = Number(options.maxTasks);
   if (Number.isFinite(explicitMaxTasks) && explicitMaxTasks > 0) {
     return explicitMaxTasks;
   }
-
-  const summary = summarizeBacklog(backlog);
-  const pendingTotal = summary.pending + summary.inProgress;
-  return Math.max(1, pendingTotal);
+  return 0;
 }
 
 export function renderAnalyzeConfirmation(context, analysis, backlog, options = {}, discovery = {}) {
@@ -162,6 +183,7 @@ export function renderAnalyzeConfirmation(context, analysis, backlog, options =
     ...renderResolutionLines(discovery, context, docsDisplay),
     ...(userIntentLines.length ? ["", "本次命令补充输入：", ...formatList(userIntentLines)] : []),
     ...(inputIssueLines.length ? ["", "输入提示：", ...inputIssueLines] : []),
+    ...(renderEngineResolutionLines(options.engineResolution).length ? ["", ...renderEngineResolutionLines(options.engineResolution)] : []),
     ...(renderRequestInterpretationLines(analysis).length ? ["", ...renderRequestInterpretationLines(analysis)] : []),
     ...(renderRepoDecisionLines(analysis).length ? ["", ...renderRepoDecisionLines(analysis)] : []),
     "",
@@ -192,7 +214,9 @@ export function renderAnalyzeConfirmation(context, analysis, backlog, options =
       ? `- 当前阻塞：${execution.blockedReason}`
       : "- 当前阻塞：无",
     "- 偏差修正：按 backlog 优先级执行；如果分析识别出偏差修正任务，会先收口再继续后续开发",
-    `- 自动推进：最多 ${autoRunMaxTasks} 个任务，直到 backlog 清空或遇到硬阻塞`,
+    autoRunMaxTasks > 0
+      ? `- 自动推进：最多 ${autoRunMaxTasks} 个任务；若主线终态复核仍发现缺口，则到达上限后暂停`
+      : "- 自动推进：持续执行，直到 backlog 清空且主线终态复核通过，或遇到硬阻塞",
     `- 单任务重试：每种策略最多 ${policy.maxTaskAttempts} 次，共 ${policy.maxTaskStrategies} 轮策略`,
     "",
     "待执行任务预览：",

package/src/analyze_prompt.mjs

@@ -3,6 +3,7 @@ import { renderUserIntentLines } from "./analyze_user_input.mjs";
 import {
   hasCustomProjectConstraints,
   listMandatoryGuardrails,
+  listMandatoryEngineeringPrinciples,
   resolveProjectConstraints,
 } from "./guardrails.mjs";
 
@@ -40,6 +41,7 @@ export function buildAnalysisPrompt({
   userIntent = {},
 }) {
   const mandatoryGuardrails = listMandatoryGuardrails();
+  const mandatoryEngineeringPrinciples = listMandatoryEngineeringPrinciples();
   const effectiveConstraints = resolveProjectConstraints(existingProjectConstraints);
   const usingFallbackConstraints = !hasCustomProjectConstraints(existingProjectConstraints);
   const userIntentLines = renderUserIntentLines(userIntent);
@@ -62,6 +64,7 @@ export function buildAnalysisPrompt({
     listSection("本次命令补充输入", userIntentLines),
     existingStateText ? section("已有状态摘要", existingStateText) : "",
     listSection("内建安全底线", mandatoryGuardrails),
+    listSection("强制编码与产出基线", mandatoryEngineeringPrinciples),
     listSection(usingFallbackConstraints ? "默认工程约束（文档未明确时也必须遵守）" : "已有项目约束", effectiveConstraints),
     existingBacklogText ? section("已有 backlog（供参考，可重组）", existingBacklogText) : "",
     section("文档内容摘录", renderDocPackets(docPackets)),
@@ -71,7 +74,7 @@ export function buildAnalysisPrompt({
       "3. `summary.implemented` 写已确认完成的关键能力。",
       "4. `summary.remaining` 写尚未完成的关键缺口。",
       "5. `summary.nextAction` 写最合理的下一步。",
-      "6. `tasks` 总数控制在 4 到 12 个之间，优先覆盖真正剩余工作。",
+      "6. `tasks` 总数控制在 0 到 12 个之间；如果最终目标已经完成且没有剩余缺口，允许输出空数组。",
       "7. 每个任务必须包含：id、title、status、priority、risk、goal、docs、paths、acceptance。",
       "8. `status` 只能是 `done`、`pending`、`blocked`，不要输出 `in_progress` 或 `failed`。",
       "9. `docs` 必须引用本次文档入口中的相关路径；`paths` 必须写当前仓库内的实际目录或文件模式。",
@@ -82,6 +85,7 @@ export function buildAnalysisPrompt({
       "14. 当当前项目目录已存在，但代码结构/产品方向与开发文档目标明显冲突，且更合理的路径是清理后重建时，`repoDecision.compatibility` 设为 `conflict`，`repoDecision.action` 设为 `confirm_rebuild`。",
       "15. 当当前项目目录与开发文档目标一致或可以直接接续时，`repoDecision.compatibility` 设为 `compatible`，`repoDecision.action` 设为 `continue_existing`。",
       "16. 当本次项目目录原本不存在，或文档目标明显是从零开始新建项目时，`repoDecision.action` 可设为 `start_new`。",
+      "17. 只有在文档最终目标、关键能力与验收范围都已闭合时，才能输出空 `tasks`；此时 `summary.remaining` 也必须为空。",
     ].join("\n")),
   ].filter(Boolean).join("\n");
 }

package/src/analyze_user_input.mjs

@@ -1,6 +1,7 @@
 import path from "node:path";
 
 import { classifyExplicitPath, pathExists, resolveAbsolute } from "./discovery_paths.mjs";
+import { normalizeEngineName } from "./engine_metadata.mjs";
 
 const DOC_SUFFIX = new Set([
   ".md",
@@ -145,7 +146,8 @@ export function normalizeAnalyzeOptions(rawOptions = {}, cwd = process.cwd()) {
     requiredDocs: Array.isArray(rawOptions.requiredDocs) ? [...rawOptions.requiredDocs] : [],
     constraints: Array.isArray(rawOptions.constraints) ? [...rawOptions.constraints] : [],
   };
-  const positionals = Array.isArray(rawOptions.positionalArgs) ? rawOptions.positionalArgs : [];
+  const rawPositionals = Array.isArray(rawOptions.positionalArgs) ? rawOptions.positionalArgs : [];
+  const positionals = [...rawPositionals];
   const explicitRefs = [];
   const requestTokens = [];
   const issues = {
@@ -160,6 +162,18 @@ export function normalizeAnalyzeOptions(rawOptions = {}, cwd = process.cwd()) {
   let repoRoot = options.repoRoot ? resolveAbsolute(options.repoRoot, cwd) : "";
   let inputPath = options.inputPath ? resolveAbsolute(options.inputPath, cwd) : "";
   let allowNewRepoRoot = Boolean(options.allowNewRepoRoot);
+  let engine = normalizeEngineName(options.engine);
+  let engineSource = options.engineSource || (engine ? "flag" : "");
+
+  if (!engine && positionals.length) {
+    const firstToken = String(positionals[0] || "").trim();
+    const leadingEngine = normalizeEngineName(firstToken);
+    if (leadingEngine && firstToken.toLowerCase() === leadingEngine) {
+      engine = leadingEngine;
+      engineSource = "leading_positional";
+      positionals.shift();
+    }
+  }
 
   if (docsPath) {
     ensureSelectionSource(selectionSources, "docs", rawOptions.selectionSources?.docs || "flag");
@@ -246,15 +260,19 @@ export function normalizeAnalyzeOptions(rawOptions = {}, cwd = process.cwd()) {
   options.repoRoot = repoRoot;
   options.inputPath = inputPath;
   options.allowNewRepoRoot = allowNewRepoRoot;
+  options.engine = engine;
+  options.engineSource = engineSource;
   options.selectionSources = selectionSources;
   options.userRequestText = userRequestText;
   options.inputIssues = issues;
   options.userIntent = {
-    rawPositionals: positionals,
+    rawPositionals,
     explicitRefs,
     requestText: userRequestText,
     issues,
     selectionSources,
+    explicitEngine: engine,
+    explicitEngineSource: engineSource,
   };
 
   return options;

package/src/analyzer.mjs

@@ -6,7 +6,11 @@ import { loadPolicy, loadProjectConfig, scaffoldIfMissing, writeStateMarkdown, w
 import { createContext } from "./context.mjs";
 import { discoverWorkspace } from "./discovery.mjs";
 import { readDocumentPackets } from "./doc_loader.mjs";
-import { runCodexTask } from "./process.mjs";
+import {
+  rememberEngineSelection,
+  resolveEngineSelection,
+} from "./engine_selection.mjs";
+import { runEngineTask } from "./process.mjs";
 import { buildAnalysisPrompt } from "./analyze_prompt.mjs";
 
 function renderAnalysisState(context, backlog, analysis) {
@@ -45,14 +49,20 @@ function sanitizeTask(task) {
 }
 
 function normalizeAnalysisPayload(payload, docsEntries) {
+  const summary = {
+    currentState: String(payload?.summary?.currentState || "").trim() || "已完成接续分析。",
+    implemented: Array.isArray(payload?.summary?.implemented) ? payload.summary.implemented.map((item) => String(item || "").trim()).filter(Boolean) : [],
+    remaining: Array.isArray(payload?.summary?.remaining) ? payload.summary.remaining.map((item) => String(item || "").trim()).filter(Boolean) : [],
+    nextAction: String(payload?.summary?.nextAction || "").trim() || "查看下一任务。",
+  };
   const tasks = Array.isArray(payload.tasks)
     ? payload.tasks.map((task) => sanitizeTask(task)).filter((task) => (
       task.id && task.title && task.goal && task.acceptance.length
     ))
     : [];
 
-  if (!tasks.length) {
-    throw new Error("Codex 分析结果无效：未生成可用任务。");
+  if (!tasks.length && summary.remaining.length) {
+    throw new Error("分析结果无效：仍存在剩余工作，但未生成可用任务。");
   }
 
   const requestInterpretation = payload?.requestInterpretation && typeof payload.requestInterpretation === "object"
@@ -80,12 +90,7 @@ function normalizeAnalysisPayload(payload, docsEntries) {
 
   return {
     project: String(payload.project || "").trim() || "helloloop-project",
-    summary: {
-      currentState: String(payload?.summary?.currentState || "").trim() || "已完成接续分析。",
-      implemented: Array.isArray(payload?.summary?.implemented) ? payload.summary.implemented.map((item) => String(item || "").trim()).filter(Boolean) : [],
-      remaining: Array.isArray(payload?.summary?.remaining) ? payload.summary.remaining.map((item) => String(item || "").trim()).filter(Boolean) : [],
-      nextAction: String(payload?.summary?.nextAction || "").trim() || "查看下一任务。",
-    },
+    summary,
     constraints: Array.isArray(payload.constraints)
       ? payload.constraints.map((item) => String(item || "").trim()).filter(Boolean)
       : [],
@@ -104,7 +109,7 @@ function normalizeAnalysisPayload(payload, docsEntries) {
   };
 }
 
-function buildAnalysisSummaryText(context, analysis, backlog) {
+function buildAnalysisSummaryText(context, analysis, backlog, engineResolution) {
   const summary = summarizeBacklog(backlog);
   const nextTask = selectNextTask(backlog);
 
@@ -112,6 +117,7 @@ function buildAnalysisSummaryText(context, analysis, backlog) {
     "HelloLoop 已完成接续分析。",
     `项目仓库：${context.repoRoot}`,
     `开发文档：${analysis.requiredDocs.join(", ")}`,
+    `执行引擎：${engineResolution?.displayName || "未记录"}`,
     "",
     "当前进度：",
     analysis.summary.currentState,
@@ -125,31 +131,27 @@ function buildAnalysisSummaryText(context, analysis, backlog) {
   ].join("\n");
 }
 
-export async function analyzeWorkspace(options = {}) {
-  const discovery = discoverWorkspace({
-    cwd: options.cwd,
-    inputPath: options.inputPath,
-    repoRoot: options.repoRoot,
-    docsPath: options.docsPath,
-    configDirName: options.configDirName,
-    allowNewRepoRoot: options.allowNewRepoRoot,
-  });
-
-  if (!discovery.ok) {
+async function analyzeResolvedWorkspace(context, discovery, options = {}) {
+  scaffoldIfMissing(context);
+  const policy = loadPolicy(context);
+  let engineResolution = options.engineResolution?.ok
+    ? options.engineResolution
+    : await resolveEngineSelection({
+      context,
+      policy,
+      options,
+      interactive: !options.yes,
+    });
+  if (!engineResolution.ok) {
     return {
       ok: false,
-      code: discovery.code,
-      summary: discovery.message,
+      code: engineResolution.code,
+      summary: engineResolution.message,
       discovery,
+      engineResolution,
     };
   }
 
-  const context = createContext({
-    repoRoot: discovery.repoRoot,
-    configDirName: options.configDirName,
-  });
-  scaffoldIfMissing(context);
-
   const existingProjectConfig = loadProjectConfig(context);
   const existingStateText = readTextIfExists(context.stateFile, "");
   const existingBacklogText = readTextIfExists(context.backlogFile, "");
@@ -170,38 +172,39 @@ export async function analyzeWorkspace(options = {}) {
   });
 
   const runDir = path.join(context.runsDir, `${nowIso().replaceAll(":", "-").replaceAll(".", "-")}-analysis`);
-  const policy = loadPolicy(context);
   const schemaFile = path.join(context.templatesDir, "analysis-output.schema.json");
-  const codexResult = await runCodexTask({
+  let analysisResult = await runEngineTask({
+    engine: engineResolution.engine,
     context,
     prompt,
     runDir,
-    model: policy.codex.model,
-    executable: policy.codex.executable,
-    sandbox: policy.codex.sandbox,
-    dangerouslyBypassSandbox: policy.codex.dangerouslyBypassSandbox,
+    policy,
+    executionMode: "analyze",
     outputSchemaFile: schemaFile,
-    outputPrefix: "analysis",
-    jsonOutput: false,
+    outputPrefix: `${engineResolution.engine}-analysis`,
     skipGitRepoCheck: true,
   });
 
-  if (!codexResult.ok) {
+  if (!analysisResult.ok) {
     return {
       ok: false,
       code: "analysis_failed",
-      summary: codexResult.stderr || codexResult.stdout || "Codex 接续分析失败。",
+      summary: analysisResult.stderr || analysisResult.stdout || `${engineResolution.displayName} 接续分析失败。`,
+      engineResolution,
+      discovery,
     };
   }
 
   let payload;
   try {
-    payload = JSON.parse(codexResult.finalMessage);
+    payload = JSON.parse(analysisResult.finalMessage);
   } catch (error) {
     return {
       ok: false,
       code: "invalid_analysis_json",
-      summary: `Codex 分析结果无法解析为 JSON：${String(error?.message || error || "")}`,
+      summary: `${engineResolution.displayName} 分析结果无法解析为 JSON：${String(error?.message || error || "")}`,
+      engineResolution,
+      discovery,
     };
   }
 
@@ -216,11 +219,14 @@ export async function analyzeWorkspace(options = {}) {
   const projectConfig = {
     requiredDocs: analysis.requiredDocs,
     constraints: analysis.constraints.length ? analysis.constraints : existingProjectConfig.constraints,
+    defaultEngine: existingProjectConfig.defaultEngine,
+    lastSelectedEngine: engineResolution.engine,
     planner: existingProjectConfig.planner,
   };
 
   writeJson(context.backlogFile, backlog);
   writeJson(context.projectFile, projectConfig);
+  rememberEngineSelection(context, engineResolution, options);
   writeStateMarkdown(context, renderAnalysisState(context, backlog, analysis));
   writeStatus(context, {
     ok: true,
@@ -231,16 +237,97 @@ export async function analyzeWorkspace(options = {}) {
     summary: summarizeBacklog(backlog),
     message: analysis.summary.currentState,
   });
-  writeText(path.join(runDir, "analysis-summary.txt"), buildAnalysisSummaryText(context, analysis, backlog));
+  writeText(path.join(runDir, "analysis-summary.txt"), buildAnalysisSummaryText(context, analysis, backlog, engineResolution));
 
   return {
     ok: true,
     code: "analyzed",
     context,
     runDir,
+    engineResolution,
     analysis,
     backlog,
-    summary: buildAnalysisSummaryText(context, analysis, backlog),
+    summary: buildAnalysisSummaryText(context, analysis, backlog, engineResolution),
     discovery,
   };
 }
+
+function buildCurrentWorkspaceDiscovery(context, docsEntries) {
+  return {
+    ok: true,
+    repoRoot: context.repoRoot,
+    docsEntries,
+    resolvedDocs: docsEntries,
+    resolution: {
+      repo: {
+        source: "current_repo",
+        sourceLabel: "当前项目",
+        confidence: "high",
+        confidenceLabel: "高",
+        path: context.repoRoot,
+        exists: true,
+        basis: [
+          "已在当前项目基础上执行主线终态复核。",
+        ],
+      },
+      docs: {
+        source: "existing_state",
+        sourceLabel: "已有 .helloloop 配置",
+        confidence: "high",
+        confidenceLabel: "高",
+        entries: docsEntries,
+        basis: [
+          "已复用 `.helloloop/project.json` 中记录的 requiredDocs。",
+        ],
+      },
+    },
+  };
+}
+
+export async function reanalyzeCurrentWorkspace(context, options = {}) {
+  const existingProjectConfig = loadProjectConfig(context);
+  const docsEntries = Array.isArray(options.requiredDocs) && options.requiredDocs.length
+    ? options.requiredDocs
+    : existingProjectConfig.requiredDocs;
+
+  if (!docsEntries.length) {
+    return {
+      ok: false,
+      code: "missing_docs",
+      summary: "当前 `.helloloop/project.json` 未记录 requiredDocs，无法执行主线终态复核。",
+      discovery: null,
+    };
+  }
+
+  return analyzeResolvedWorkspace(
+    context,
+    buildCurrentWorkspaceDiscovery(context, docsEntries),
+    options,
+  );
+}
+
+export async function analyzeWorkspace(options = {}) {
+  const discovery = discoverWorkspace({
+    cwd: options.cwd,
+    inputPath: options.inputPath,
+    repoRoot: options.repoRoot,
+    docsPath: options.docsPath,
+    configDirName: options.configDirName,
+    allowNewRepoRoot: options.allowNewRepoRoot,
+  });
+
+  if (!discovery.ok) {
+    return {
+      ok: false,
+      code: discovery.code,
+      summary: discovery.message,
+      discovery,
+    };
+  }
+
+  const context = createContext({
+    repoRoot: discovery.repoRoot,
+    configDirName: options.configDirName,
+  });
+  return analyzeResolvedWorkspace(context, discovery, options);
+}