helloagents 3.0.9-beta.1 → 3.0.10-beta.1

package/scripts/cli-lifecycle.mjs

@@ -181,6 +181,17 @@ function runAllHostsLifecycle(action, explicitMode) {
   }
 
   const settings = readSettings(true)
+  if (action === 'update' && !explicitMode) {
+    for (const host of HOSTS) {
+      const mode = resolveHostMode(host, '', settings)
+      const result = runHostLifecycle(runtime, action, host, mode)
+      if (!result.skipped) setTrackedHostMode(settings, host, mode)
+    }
+    writeSettings(settings)
+    runtime.printInstallMsg(settings.install_mode || DEFAULTS.install_mode, 'refresh')
+    return
+  }
+
   const mode = resolveInstallMode(explicitMode, settings)
   if (explicitMode) settings.install_mode = explicitMode
   installAllHosts(runtime, mode)

package/scripts/cli-messages.mjs

@@ -44,8 +44,8 @@ function renderInstallMessage(context, mode, state) {
     }
     return msg(
       refresh
-        ? '  global 模式已刷新。\n  Claude Code / Gemini 请保持插件已安装；Codex 原生本地插件链路已重装并同步最新文件。'
-        : '  所有项目将自动启用完整 HelloAGENTS 规则。\n  Claude Code / Gemini 请手动安装插件；Codex 已自动走原生本地插件链路。',
+        ? '  global 模式已刷新。\n  Claude Code / Gemini 请保持插件已安装；Codex 原生本地插件已重装并同步最新文件。'
+        : '  所有项目将自动启用完整 HelloAGENTS 规则。\n  Claude Code / Gemini 请手动安装插件；Codex 已自动安装原生本地插件。',
       refresh
         ? '  Global mode refreshed.\n  Keep Claude Code / Gemini plugins installed; Codex native local-plugin files were reinstalled and synced.'
         : '  All projects will use full HelloAGENTS rules.\n  Install Claude Code / Gemini plugins manually; Codex now uses the native local-plugin path automatically.',
@@ -92,7 +92,7 @@ ${msg('单 CLI 管理', 'Scoped CLI management')}:
 ${msg('诊断', 'Diagnostics')}:
   helloagents doctor
   helloagents doctor codex --json
-  ${msg('检查 carrier、链接、hooks、配置注入、Codex 插件链路、受管 model_instructions_file 指向与版本漂移', 'Checks carriers, links, hooks, config injections, the Codex plugin chain, managed model_instructions_file targeting, and version drift')}
+  ${msg('检查 carrier、链接、hooks、配置注入、Codex 插件安装、受管 model_instructions_file 指向与版本漂移', 'Checks carriers, links, hooks, config injections, Codex plugin installation, managed model_instructions_file targeting, and version drift')}
 
 ${msg('卸载', 'Uninstall')}:
   helloagents cleanup      ${msg('（推荐先执行，显式清理所有 CLI 注入/链接）', '(recommended first, explicitly cleans CLI injections/links)')}

package/scripts/cli-toml-values.mjs

@@ -0,0 +1,25 @@
+export function getTomlArrayDepthDelta(text) {
+  let depth = 0
+  let quoted = false
+  let escaped = false
+
+  for (const char of String(text || '')) {
+    if (escaped) {
+      escaped = false
+      continue
+    }
+    if (char === '\\' && quoted) {
+      escaped = true
+      continue
+    }
+    if (char === '"') {
+      quoted = !quoted
+      continue
+    }
+    if (quoted) continue
+    if (char === '[') depth += 1
+    if (char === ']') depth -= 1
+  }
+
+  return depth
+}

package/scripts/cli-toml.mjs

@@ -3,6 +3,8 @@
  * Targets the small subset of TOML structures used by Codex CLI config.
  */
 
+import { getTomlArrayDepthDelta } from './cli-toml-values.mjs'
+
 export function isTomlTableHeader(line) {
   const trimmed = String(line || '').trim();
   return trimmed.startsWith('[') && trimmed.endsWith(']');
@@ -62,6 +64,19 @@ function findTopLevelTomlBlock(text, key) {
     const closeIndex = normalized.indexOf('"""', openIndex + 3);
     end = closeIndex >= 0 ? closeIndex + 3 : normalized.length;
   }
+  if (value.startsWith('[')) {
+    let depth = getTomlArrayDepthDelta(firstLine.slice(firstLine.indexOf('=') + 1));
+    let lineStart = firstLineEnd + (normalized[firstLineEnd] === '\n' ? 1 : 0);
+
+    while (depth > 0 && lineStart < normalized.length) {
+      const lineEndIndex = normalized.indexOf('\n', lineStart);
+      const nextLineEnd = lineEndIndex >= 0 ? lineEndIndex : normalized.length;
+      const nextLine = normalized.slice(lineStart, nextLineEnd);
+      depth += getTomlArrayDepthDelta(nextLine);
+      end = nextLineEnd;
+      lineStart = nextLineEnd + 1;
+    }
+  }
 
   while (end < normalized.length && normalized[end] === '\n') {
     end += 1;

package/scripts/guard.mjs

@@ -124,7 +124,7 @@ function buildPostWriteWarnings(data) {
   const filePath = data.tool_input?.file_path || ''
   return [
     ...(detectIdeaBoundaryContext(data)?.zeroSideEffect
-      ? ['~idea 本轮要求只读探索；检测到写入工具落地，请回退到探索输出或升级到 ~plan / ~build / ~prd / ~auto 后再修改文件']
+      ? ['~idea 本轮要求只读探索；检测到写入文件的工具调用，请回到探索输出，或升级到 ~plan / ~build / ~prd / ~auto 后再修改文件']
       : []),
     ...scanUnrequestedFiles(filePath, data.tool_name),
     ...(content ? [...scanForSecrets(content), ...scanDangerousPackages(content, filePath)] : []),
@@ -195,7 +195,7 @@ function handleHighRiskCommand(data, command) {
 function emitShellWarnings(data, command, highRiskWarnings, shellSafetyWarnings) {
   const sections = []
   if (highRiskWarnings.length > 0) {
-    sections.push(`⚠️ [HelloAGENTS 高风险链路提醒] 检测到高风险命令:\n${highRiskWarnings.map((warning) => `  - ${warning}`).join('\n')}\n请确认已完成相应规划/审查并获得必要授权。`)
+    sections.push(`⚠️ [HelloAGENTS 高风险操作提醒] 检测到高风险命令:\n${highRiskWarnings.map((warning) => `  - ${warning}`).join('\n')}\n请确认已完成相应规划/审查并获得必要授权。`)
   }
   if (shellSafetyWarnings.length > 0) {
     sections.push(`⚠️ [HelloAGENTS Shell 安全提醒] 检测到建议调整的命令写法:\n${shellSafetyWarnings.map((warning) => `  - ${warning}`).join('\n')}\n当前仅提示，不中断执行。`)

package/scripts/notify-context.mjs

@@ -74,8 +74,8 @@ export function buildCompactionContext({ payload, pkgRoot, settings, bootstrapFi
   const stateSyncHint = buildStateSyncHint(cwd, workflowOptions);
   if (stateSnapshot.exists && stateSnapshot.content) {
     summaryParts.push('');
-    summaryParts.push(`## 恢复快照（从 ${stateSnapshot.statePath.replace(/\\/g, '/')} 读取，只用于找回上次停在哪）`);
-    summaryParts.push('恢复时先看当前用户消息，确认仍是同一任务再按 STATE.md 接续。');
+    summaryParts.push(`## 状态文件（从 ${stateSnapshot.statePath.replace(/\\/g, '/')} 读取，只用于找回上次停在哪）`);
+    summaryParts.push('恢复时先看当前用户消息；如果仍是同一任务，再参考状态文件。');
     summaryParts.push(stateSnapshot.content);
   }
 
@@ -109,7 +109,7 @@ export function buildCompactionContext({ payload, pkgRoot, settings, bootstrapFi
 
   if (stateSyncHint) {
     summaryParts.push('');
-    summaryParts.push('## STATE.md 提醒');
+    summaryParts.push('## 状态文件提醒');
     summaryParts.push(stateSyncHint);
   }
 
@@ -140,10 +140,10 @@ export function buildInjectContext({ source, bootstrap, settings, pkgRoot, host,
   if (projectStorageBlock) context += `\n\n${projectStorageBlock}`;
   if (workflowHint) context += `\n\n## 当前工作流提示\n${workflowHint}`;
   if (capabilityHint) context += `\n\n## 当前按需能力\n${capabilityHint}`;
-  if (stateSyncHint) context += `\n\n## STATE.md 提醒\n${stateSyncHint}`;
+  if (stateSyncHint) context += `\n\n## 状态文件提醒\n${stateSyncHint}`;
   context += settingsBlock;
   if (source === 'resume' || source === 'compact') {
-    context += `\n\n> ⚠️ 会话已恢复/压缩，请先读取当前 \`state_path\` 指向的 \`${stateSnapshot.statePath.replace(/\\/g, '/')}\` 恢复工作状态；先看当前用户消息确认仍是同一任务，再按 STATE.md 接续。`;
+    context += `\n\n> ⚠️ 会话已恢复/压缩，请先读取 \`state_path\` 指向的 \`${stateSnapshot.statePath.replace(/\\/g, '/')}\`；先看当前用户消息，如果仍是同一任务，再参考状态文件。`;
   }
   return context;
 }
@@ -168,8 +168,8 @@ export function buildSemanticRouteInstruction(cwd, payload = {}) {
   return [
     '当前消息未使用 ~command。',
     '请根据用户请求的真实意图选路，不依赖关键词表。',
-    'Delivery Tier: T0=探索/比较；T1=低风险小改动或显式验证；T2=多文件功能/新项目/需要结构化产物；T3=高风险或不可逆链路。',
-    '路由映射：~idea=只读探索，不创建文件；~build=明确实现；~verify=审查/验证；~plan=结构化规划；~prd=重型规格；~auto=自动编排并自动衔接后续阶段。',
+    'Delivery Tier: T0=探索/比较；T1=低风险小改动或显式验证；T2=多文件功能/新项目/需要结构化产物；T3=高风险或不可逆操作。',
+    '路由映射：~idea=只读探索，不创建文件；~build=明确实现；~verify=审查/验证；~plan=结构化规划；~prd=重型规格；~auto=自动选择并继续执行后续阶段。',
     '若判定为 T3，默认先走 ~plan / ~prd；纯审查/验证请求才优先 ~verify。',
     `涉及 UI 任务时，设计决策优先级：当前活跃 plan / PRD → ${describeProjectStoreFile(cwd, 'DESIGN.md')} → 通用 UI 规则。`,
     projectStorageHint,

package/scripts/notify-events.mjs

@@ -5,11 +5,3 @@ export function shouldIgnoreCodexNotifyClient(client) {
 export function shouldIgnoreFormattedSubagent(lastMsg, outputFormatEnabled) {
   return outputFormatEnabled && !lastMsg.includes('【HelloAGENTS】');
 }
-
-export function claimsTaskComplete(lastMsg) {
-  if (!lastMsg) return false;
-  if (/^✅【HelloAGENTS】- .*(当前任务已完成|任务已完成|已修复|完成交付|done|fixed|completed|finished)/im.test(lastMsg)) {
-    return true;
-  }
-  return /(当前任务已完成|任务已完成|已全部完成|已修复|修复完成|\b(done|fixed|completed|finished)\b)/i.test(lastMsg);
-}

package/scripts/notify-gates.mjs

@@ -0,0 +1,128 @@
+import { existsSync } from 'node:fs'
+import { spawnSync } from 'node:child_process'
+
+function truncateText(value = '') {
+  const text = String(value || '').trim()
+  return text.length > 1000 ? `${text.slice(0, 1000)}\n...(truncated)` : text
+}
+
+function buildGateErrorReason(source, detail = '') {
+  return [
+    `[HelloAGENTS Runtime] ${source} 执行失败，已暂停完成通知。`,
+    detail ? `原因：${detail}` : '',
+    '请修复脚本或重新运行验证后再报告完成。',
+  ].filter(Boolean).join('\n')
+}
+
+function emitGateError({
+  payload,
+  host,
+  source,
+  reason,
+  appendReplayEvent,
+  output,
+}) {
+  appendReplayEvent(payload.cwd || process.cwd(), {
+    host,
+    event: 'runtime_gate_error',
+    source,
+    reason,
+  })
+  output({
+    decision: 'block',
+    reason,
+    suppressOutput: true,
+  })
+  return true
+}
+
+export function runGateScript({
+  payload,
+  host,
+  scriptPath,
+  args = [],
+  source,
+  blockEvent,
+  timeout,
+  appendReplayEvent,
+  output,
+}) {
+  if (!existsSync(scriptPath)) {
+    return emitGateError({
+      payload,
+      host,
+      source,
+      reason: buildGateErrorReason(source, `脚本不存在：${scriptPath}`),
+      appendReplayEvent,
+      output,
+    })
+  }
+
+  const result = spawnSync(process.execPath, [scriptPath, ...args], {
+    input: JSON.stringify(payload),
+    encoding: 'utf-8',
+    timeout,
+  })
+
+  if (result.error) {
+    return emitGateError({
+      payload,
+      host,
+      source,
+      reason: buildGateErrorReason(source, result.error.message),
+      appendReplayEvent,
+      output,
+    })
+  }
+
+  if (result.status !== 0) {
+    const detail = truncateText(`${result.stderr || ''}\n${result.stdout || ''}`) || `退出码 ${result.status}`
+    return emitGateError({
+      payload,
+      host,
+      source,
+      reason: buildGateErrorReason(source, detail),
+      appendReplayEvent,
+      output,
+    })
+  }
+
+  const stdout = String(result.stdout || '').trim()
+  if (!stdout) {
+    return emitGateError({
+      payload,
+      host,
+      source,
+      reason: buildGateErrorReason(source, '脚本未返回有效结果'),
+      appendReplayEvent,
+      output,
+    })
+  }
+
+  let gateOutput
+  try {
+    gateOutput = JSON.parse(stdout)
+  } catch {
+    return emitGateError({
+      payload,
+      host,
+      source,
+      reason: buildGateErrorReason(source, `脚本返回了无法解析的 JSON：${truncateText(stdout)}`),
+      appendReplayEvent,
+      output,
+    })
+  }
+
+  if (gateOutput.decision === 'block') {
+    appendReplayEvent(payload.cwd || process.cwd(), {
+      host,
+      event: blockEvent,
+      source,
+      reason: gateOutput.reason || '',
+    })
+    output(gateOutput)
+    return true
+  }
+
+  return false
+}

package/scripts/notify-ui.mjs

@@ -18,6 +18,7 @@ const NOTIFY_MESSAGES = {
 };
 
 const WIN_APPID = 'HelloAgents.Notification';
+const DISABLE_OS_NOTIFICATIONS = process.env.HELLOAGENTS_DISABLE_OS_NOTIFICATIONS === '1';
 
 function escapeToastText(value = '') {
   return String(value)
@@ -55,6 +56,7 @@ function resolveWav(pkgRoot, event) {
 }
 
 export function playSound(pkgRoot, event) {
+  if (DISABLE_OS_NOTIFICATIONS) return;
   const wav = resolveWav(pkgRoot, event);
   if (!wav) { process.stderr.write('\x07'); return; }
   try {
@@ -83,6 +85,7 @@ function ensureWinAppId(pkgRoot) {
 }
 
 export function desktopNotify(pkgRoot, event, extra) {
+  if (DISABLE_OS_NOTIFICATIONS) return;
   const notification = buildDesktopNotificationContent(event, extra);
   try {
     if (PLAT === 'win32') {

package/scripts/notify.mjs

@@ -4,13 +4,13 @@
 
 import { join, dirname } from 'node:path';
 import { existsSync, readFileSync } from 'node:fs';
-import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 import { playSound as _playSound, desktopNotify as _desktopNotify } from './notify-ui.mjs';
 import { resolveNotificationSource } from './notify-source.mjs';
 import { buildCompactionContext, buildInjectContext, buildRouteInstruction, buildSemanticRouteInstruction, resolveCanonicalCommandSkill } from './notify-context.mjs';
-import { claimsTaskComplete, shouldIgnoreCodexNotifyClient } from './notify-events.mjs';
+import { shouldIgnoreCodexNotifyClient } from './notify-events.mjs';
+import { runGateScript } from './notify-gates.mjs';
 import { handleRouteCommand, resolveBootstrapFile } from './notify-route.mjs';
 import { readSettings, readStdinJson, output, suppressedOutput, emptySuppress } from './notify-shared.mjs';
 import { clearRouteContext, writeRouteContext } from './runtime-context.mjs';
@@ -37,6 +37,17 @@ const EVENT_NAME = {
 const playSound = (event) => _playSound(PKG_ROOT, event);
 const desktopNotify = (event, extra) => _desktopNotify(PKG_ROOT, event, extra);
 
+function normalizeNotifyLevel(value) {
+  const level = Number(value);
+  return [0, 1, 2, 3].includes(level) ? level : 0;
+}
+
+function notifyByLevel(event, extra, settings = getSettings()) {
+  const level = normalizeNotifyLevel(settings.notify_level ?? 0);
+  if (level === 2 || level === 3) playSound(event);
+  if (level === 1 || level === 3) desktopNotify(event, extra);
+}
+
 function buildNotifyExtra(payload = {}, options = {}) {
   const source = resolveNotificationSource({
     host: HOST,
@@ -56,63 +67,30 @@ function getSettings() {
 function runRalphLoop(payload) {
   const settings = getSettings();
   if (settings.ralph_loop_enabled === false) return false;
-  try {
-    const rlPath = join(__dirname, 'ralph-loop.mjs');
-    if (!existsSync(rlPath)) return false;
-    const hostFlag = IS_GEMINI ? ['--gemini'] : HOST === 'codex' ? ['--codex'] : [];
-    const result = spawnSync(process.execPath, [rlPath, ...hostFlag], {
-      input: JSON.stringify(payload),
-      encoding: 'utf-8',
-      timeout: 120_000,
-    });
-    if (result.stdout) {
-      const rlOut = JSON.parse(result.stdout);
-      if (rlOut.decision === 'block') {
-        appendReplayEvent(payload.cwd || process.cwd(), {
-          host: HOST,
-          event: 'verify_gate_blocked',
-          source: 'ralph-loop',
-          reason: rlOut.reason || '',
-        });
-        output(rlOut);
-        return true;
-      }
-    }
-  } catch {}
-  return false;
+  return runGateScript({
+    payload,
+    host: HOST,
+    scriptPath: join(__dirname, 'ralph-loop.mjs'),
+    args: IS_GEMINI ? ['--gemini'] : HOST === 'codex' ? ['--codex'] : [],
+    source: 'ralph-loop',
+    blockEvent: 'verify_gate_blocked',
+    timeout: 120_000,
+    appendReplayEvent,
+    output,
+  });
 }
 
 function runDeliveryGate(payload) {
-  try {
-    const gatePath = join(__dirname, 'delivery-gate.mjs');
-    if (!existsSync(gatePath)) return false;
-    const result = spawnSync(process.execPath, [gatePath], {
-      input: JSON.stringify(payload),
-      encoding: 'utf-8',
-      timeout: 30_000,
-    });
-    if (result.stdout) {
-      const gateOut = JSON.parse(result.stdout);
-      if (gateOut.decision === 'block') {
-        appendReplayEvent(payload.cwd || process.cwd(), {
-          host: HOST,
-          event: 'delivery_gate_blocked',
-          source: 'delivery-gate',
-          reason: gateOut.reason || '',
-        });
-        output(gateOut);
-        return true;
-      }
-    }
-  } catch {}
-  return false;
-}
-
-function readCompletionText(payload = {}) {
-  return payload['last-assistant-message']
-    || payload.last_assistant_message
-    || payload.lastAssistantMessage
-    || '';
+  return runGateScript({
+    payload,
+    host: HOST,
+    scriptPath: join(__dirname, 'delivery-gate.mjs'),
+    source: 'delivery-gate',
+    blockEvent: 'delivery_gate_blocked',
+    timeout: 30_000,
+    appendReplayEvent,
+    output,
+  });
 }
 
 function readMainTurnState(cwd) {
@@ -124,9 +102,9 @@ function consumeMainTurnState(cwd, turnState) {
   if (turnState?.role === 'main') clearTurnState(cwd);
 }
 
-function shouldProcessCloseout(turnState, lastMsg) {
+function shouldProcessCloseout(turnState) {
   if (turnState) return turnState.kind === 'complete';
-  return claimsTaskComplete(lastMsg);
+  return false;
 }
 
 function cmdPreCompact() {
@@ -217,29 +195,24 @@ function cmdInject() {
 
 function cmdStop() {
   const payload = readStdinJson();
-  const lastMsg = readCompletionText(payload);
   const cwd = payload.cwd || process.cwd();
   const turnState = readMainTurnState(cwd);
-  const shouldProcess = shouldProcessCloseout(turnState, lastMsg);
+  const shouldProcess = shouldProcessCloseout(turnState);
   clearRouteContext();
   if (shouldProcess && runRalphLoop(payload)) {
     consumeMainTurnState(cwd, turnState);
-    playSound('warning');
-    desktopNotify('warning', buildNotifyExtra(payload));
+    notifyByLevel('warning', buildNotifyExtra(payload));
     return;
   }
   if (shouldProcess && runDeliveryGate(payload)) {
     consumeMainTurnState(cwd, turnState);
-    playSound('warning');
-    desktopNotify('warning', buildNotifyExtra(payload));
+    notifyByLevel('warning', buildNotifyExtra(payload));
     return;
   }
 
   const settings = getSettings();
-  const level = settings.notify_level ?? 0;
   if (shouldProcess) {
-    if (level === 2 || level === 3) playSound('complete');
-    if (level === 1 || level === 3) desktopNotify('complete', buildNotifyExtra(payload));
+    notifyByLevel('complete', buildNotifyExtra(payload), settings);
   }
   consumeMainTurnState(cwd, turnState);
   emptySuppress();
@@ -262,8 +235,7 @@ function cmdCodexNotify() {
   if (shouldIgnoreCodexNotifyClient(client)) return;
 
   if (type === 'approval-requested') {
-    playSound('confirm');
-    desktopNotify('confirm', buildNotifyExtra(data));
+    notifyByLevel('confirm', buildNotifyExtra(data));
     return;
   }
   if (type !== 'agent-turn-complete') return;
@@ -279,20 +251,16 @@ function cmdCodexNotify() {
   const settings = getSettings();
   if (runRalphLoop(data)) {
     consumeMainTurnState(cwd, turnState);
-    playSound('warning');
-    desktopNotify('warning', buildNotifyExtra(data));
+    notifyByLevel('warning', buildNotifyExtra(data), settings);
     return;
   }
   if (runDeliveryGate(data)) {
     consumeMainTurnState(cwd, turnState);
-    playSound('warning');
-    desktopNotify('warning', buildNotifyExtra(data));
+    notifyByLevel('warning', buildNotifyExtra(data), settings);
     return;
   }
 
-  const level = settings.notify_level ?? 0;
-  if (level === 2 || level === 3) playSound('complete');
-  if (level === 1 || level === 3) desktopNotify('complete', buildNotifyExtra(data));
+  notifyByLevel('complete', buildNotifyExtra(data), settings);
   consumeMainTurnState(cwd, turnState);
 }
 

package/scripts/project-storage.mjs

@@ -277,9 +277,9 @@ export function describeProjectStoreFile(cwd, relativePath = '') {
 export function buildProjectStorageHint(cwd, options = {}) {
   const summary = getProjectStoreSummary(cwd, options)
   const hints = []
-  hints.push(`当前恢复快照统一写入 \`${summary.promptStatePath}\``)
+  hints.push(`当前状态文件写入 \`${summary.promptStatePath}\``)
   if (summary.stateSessionMode === 'default') {
-    hints.push(`当前宿主未提供稳定会话标识，因此落到分支级默认会话槽位 \`${summary.stateSessionToken}\``)
+    hints.push(`当前宿主未提供稳定会话标识，因此使用分支默认位置 \`${summary.stateSessionToken}\``)
   }
   if (summary.usesSharedStore) {
     hints.push(`项目存储：\`project_store_mode=repo-shared\`；本地激活/运行态目录仍是 \`${summary.promptActivationDir}\`，知识库/方案目录改为 \`${summary.promptStoreDir}\``)
@@ -307,12 +307,12 @@ export function buildProjectStorageBlock(cwd, options = {}) {
   }
 
   const explanations = []
-  explanations.push('说明：恢复快照只认 `state_path` 这一个权威路径，不再读写旧的项目级 `.helloagents/STATE.md`。')
+  explanations.push('说明：状态文件只使用 `state_path`。')
   if (summary.stateSessionMode === 'default') {
-    explanations.push('说明：当前宿主未提供稳定会话标识，因此自动使用分支级默认会话槽位，仍保持新目录结构。')
+    explanations.push('说明：当前宿主未提供稳定会话标识，因此使用分支默认位置。')
   }
   if (summary.usesSharedStore) {
-    explanations.push('说明：`STATE.md` 与 `.ralph-*.json` 继续写本地激活目录；`context.md`、`guidelines.md`、`DESIGN.md`、`verify.yaml`、`modules/`、`plans/`、`archive/` 写知识库/方案目录。')
+    explanations.push('说明：状态文件与 `.ralph-*.json` 写本地激活目录；`context.md`、`guidelines.md`、`DESIGN.md`、`verify.yaml`、`modules/`、`plans/`、`archive/` 写知识库/方案目录。')
   } else {
     explanations.push('说明：当前使用项目本地 `.helloagents/` 作为激活目录、知识库目录和方案目录。')
   }

package/scripts/workflow-core.mjs

@@ -16,9 +16,9 @@ export function getTargetPlans(snapshot) {
 
 function describeStateLabel(state) {
   if (state.stateSessionMode === 'default') {
-    return '当前分支默认会话槽位的 `STATE.md`'
+    return '当前分支默认位置的状态文件'
   }
-  return '当前会话的 `STATE.md`'
+  return '当前会话的状态文件'
 }
 export function classifyPlan(plan) {
   if (!plan) {
@@ -140,12 +140,12 @@ export function buildVerifyModeHintFromSnapshot(snapshot) {
 export function buildStateSyncHintFromSnapshot(snapshot) {
   const issues = collectStateSyncIssues(snapshot)
   if (issues.length === 0) return ''
-  return `STATE.md 提醒：${issues.join('；')}；继续项目级流程、收尾或进入压缩前先同步恢复快照。`
+  return `状态文件提醒：${issues.join('；')}；继续项目级流程、收尾或进入压缩前先同步状态文件。`
 }
 
 export function buildStateRoleHintFromSnapshot(snapshot) {
   if (!snapshot.state.exists || snapshot.plans.length > 0) return ''
-  return `恢复约束：当前仅检测到${describeStateLabel(snapshot.state)}；先以当前用户消息、显式命令和代码事实确认主线，STATE.md 只用于找回上次停在哪，不是当前任务的自动授权或唯一判断依据。`
+  return `恢复约束：当前仅检测到${describeStateLabel(snapshot.state)}；先以当前用户消息、显式命令和代码事实确认当前任务。状态文件只用于找回上次停在哪，不是当前任务的自动授权或唯一判断依据。`
 }
 
 export function buildUiContractHint(cwd, snapshot) {
@@ -167,7 +167,7 @@ export function buildUiContractHint(cwd, snapshot) {
   if (visualValidationRequired) {
     extraHints.push('若当前 UI 契约要求视觉验收，收尾前需写 `.helloagents/.ralph-visual.json` 记录关键视口、状态与结论')
   }
-  return `UI 约束提示：如本次属于视觉/交互链路，设计决策优先级固定为：当前活跃 plan.md / prd/03-ui-design.md → ${describeProjectStoreFile(cwd, 'DESIGN.md')} → hello-ui。${extraHints.length > 0 ? ` ${extraHints.join('；')}。` : ''}`
+  return `UI 约束提示：如本次属于视觉/交互任务，设计决策优先级固定为：当前活跃 plan.md / prd/03-ui-design.md → ${describeProjectStoreFile(cwd, 'DESIGN.md')} → hello-ui。${extraHints.length > 0 ? ` ${extraHints.join('；')}。` : ''}`
 }
 
 export { normalizeTaskFile, readStateSnapshot, listPlanPackages, getWorkflowSnapshot }

package/scripts/workflow-recommendation.mjs

@@ -59,7 +59,7 @@ function buildConsolidateAction(recommendation) {
       phase: 'consolidate',
       mode: recommendation.mode,
       routeHint: recommendation.guidance,
-      gateHint: '交付把关：审查与验证证据已满足；先写 `.helloagents/.ralph-closeout.json` 记录需求覆盖与交付清单，再完成 STATE.md / 归档后才可交付。',
+      gateHint: '交付把关：审查与验证证据已满足；先写 `.helloagents/.ralph-closeout.json` 记录需求覆盖与交付清单，再更新 `state_path` 并归档后才可交付。',
     }
   }
 
@@ -67,7 +67,7 @@ function buildConsolidateAction(recommendation) {
     phase: 'consolidate',
     mode: recommendation.mode || 'ready',
     routeHint: recommendation.guidance,
-    gateHint: '交付把关：当前已具备收尾证据；完成 STATE.md、知识沉淀与归档后即可交付。',
+    gateHint: '交付把关：当前已具备收尾证据；更新 `state_path`、知识文件并归档后即可交付。',
   }
 }
 
@@ -239,8 +239,8 @@ function buildClosedRecommendation(scopeLabel, plan, cwd) {
         ? `${scopeLabel} "${plan.planName}" 的任务与交付证据已闭合。`
         : `${scopeLabel} "${plan.planName}" 的任务、审查与验证已闭合。`,
       guidance: closedPlanEvidence.closeoutReady
-        ? '当前进入 CONSOLIDATE：完成 `STATE.md`、知识沉淀与方案归档后即可交付；不要无故重开新的方案包或重新跑一遍无关验证。'
-        : '当前进入 CONSOLIDATE：先写 `.helloagents/.ralph-closeout.json` 记录需求覆盖与交付清单，再同步 `STATE.md` / 归档后交付。',
+        ? '当前进入 CONSOLIDATE：更新 `state_path`、知识文件并归档方案后即可交付；不要无故重开新的方案包或重新跑一遍无关验证。'
+        : '当前进入 CONSOLIDATE：先写 `.helloagents/.ralph-closeout.json` 记录需求覆盖与交付清单，再更新 `state_path` 并归档后交付。',
     }
   }
 

package/scripts/workflow-state.mjs

@@ -58,7 +58,7 @@ function buildCommandRouteMessage(skillName, recommendation, verifyModeHint) {
   if (skillName === 'auto') {
     return recommendation.stage === 'consolidate'
       ? `当前工作流约束：${recommendation.summary} 当前建议下一阶段：CONSOLIDATE。${recommendation.guidance} 若本次明确使用 ~auto，则在未命中阻塞判定时直接完成当前收尾，不再额外停下询问。`
-      : `当前工作流约束：${recommendation.summary} 当前建议主路径：${recommendation.nextPath}。${recommendation.guidance} 若本次明确使用 ~auto，则命中主路径后继续衔接后续阶段，除非触发阻塞判定，否则不要在方案/PRD 阶段额外停下。`
+      : `当前工作流约束：${recommendation.summary} 当前建议主路径：${recommendation.nextPath}。${recommendation.guidance} 若本次明确使用 ~auto，则命中主路径后继续执行后续阶段，除非触发阻塞判定，否则不要在方案/PRD 阶段额外停下。`
   }
   if (skillName === 'plan') {
     if (recommendation.stage === 'consolidate') {