helloagents 3.0.9-beta.1 → 3.0.10

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') {

package/skills/commands/auto/SKILL.md

@@ -1,19 +1,19 @@
 ---
 name: ~auto
-description: 自动编排命令 — 自动选择并串联 ~idea / ~plan / ~build / ~verify / ~prd，默认持续推进直到交付完成（~auto 命令）
+description: 自动执行命令 — 自动选择并依次执行 ~idea / ~plan / ~build / ~verify / ~prd，默认持续推进直到交付完成（~auto 命令）
 policy:
   allow_implicit_invocation: false
 ---
 Trigger: ~auto <任务描述>
 
-`~auto` 是自动编排命令。它根据任务类型、复杂度、风险等级与项目状态，自动在 `~idea`、`~plan`、`~build`、`~verify`、`~prd` 之间选择合适主路径，并把这些阶段串成一条连续交付链路。
-`~auto` 不止做一次选路；主路径一旦确定，就按需要继续衔接后续阶段，默认持续推进直到完成交付，只有命中 bootstrap 的阻塞判定时才停下。
+`~auto` 是自动执行命令。它根据任务类型、复杂度、风险等级与项目状态，在 `~idea`、`~plan`、`~build`、`~verify`、`~prd` 之间选择合适主路径，并连续推进。
+`~auto` 不止做一次选路；主路径一旦确定，就按需要继续执行后续阶段，默认持续推进直到完成交付，只有命中 bootstrap 的阻塞判定时才停下。
 
 ## 铁律
 - 不为了“自动化”而强行走重流程
 - 复杂度与风险不足以支撑更重路径时，优先选更轻但能保证质量的路线
-- `T3` 高风险或不可逆链路默认不直接进入 `~build`；优先先走 `~plan` 或 `~prd`，纯审查/纯验证请求才可先进入 `~verify`
-- 主路径一旦确定，立即读取对应 command skill，并在阶段完成后继续衔接后续阶段，避免同一任务重复探索或重复等待
+- `T3` 高风险或不可逆操作默认不直接进入 `~build`；优先先走 `~plan` 或 `~prd`，纯审查/纯验证请求才可先进入 `~verify`
+- 主路径一旦确定，立即读取对应 command skill，并在阶段完成后继续执行后续阶段，避免同一任务重复探索或重复等待
 - 选路不替代授权；涉及外部副作用或高风险不可逆操作时，仍遵守 bootstrap 的阻塞判定与确认规则
 - 用户显式使用 `~auto`，表示已授权在当前任务边界内沿选定主路径持续执行；`~plan` / `~prd` 作为中间阶段时，不再额外询问“是否开始执行”，除非仍有真实阻塞
 - 优先消费当前上下文中已注入的 ROUTE / TIER、当前工作流约束与项目状态；不要在 `~auto` 内另建一套关键词路由表
@@ -38,13 +38,13 @@ Trigger: ~auto <任务描述>
   - 明确要求验证 / 审查 / 跑检查 → `~verify`
   - 0 到 1 / 产品级 / 多维规格 → `~prd`
   - 多文件功能 / 架构变更 / 新项目规划 → `~plan`
-  - 明确修复 / 小范围实现 / 现有方案落地 → `~build`
+  - 明确修复 / 小范围实现 / 按现有方案实现 → `~build`
 
 ### 2. 按 Tier 校正
 
 - `T0` → 保持在 `~idea`，不创建项目文件
 - `T1` → 在 `~build` / `~verify` 间选择最短可交付路径
-- `T2` → 需要结构化产物或范围未完全收敛时优先 `~plan`
+- `T2` → 需要结构化产物或范围未完全明确时优先 `~plan`
 - `T3` → 纯审查/验真走 `~verify`；其余默认 `~plan` 或 `~prd`，待方案与风险边界明确后再进入实现
 
 ### 3. 读取对应命令并执行主路径
@@ -57,16 +57,16 @@ Trigger: ~auto <任务描述>
 
 不要额外读取未选中的 command skill。
 
-### 4. 自动衔接直到完成
+### 4. 持续执行直到完成
 
-- 若主路径是 `~build` → 完成实现后继续进入 `~verify`，再按当前链路进入收尾
-- 若主路径是 `~plan` → 方案包落地后，若当前链路来自 `~auto` 且未命中阻塞判定，直接继续进入 `~build`，不要把“方案已形成”当作最终停点
-- 若主路径是 `~prd` → PRD / 任务 / 契约落地后，若当前链路来自 `~auto` 且未命中阻塞判定，按收敛结果继续进入 `~build`，必要时先补一轮轻量 `~plan`
+- 若主路径是 `~build` → 完成实现后继续进入 `~verify`，再进入收尾
+- 若主路径是 `~plan` → 方案包写入后，若当前任务来自 `~auto` 且未命中阻塞判定，直接继续进入 `~build`，不要把“方案已形成”当作最终停点
+- 若主路径是 `~prd` → PRD / 任务 / 契约写入后，若当前任务来自 `~auto` 且未命中阻塞判定，按当前结果继续进入 `~build`，必要时先补一轮轻量 `~plan`
 - 若主路径是 `~verify` → 完成审查 / 验证 / 收尾后结束
-- 若主路径是 `~idea`，且用户本意就是探索/比较，则在探索输出后结束；若探索后已收敛成明确方向且当前任务仍要求落地，则继续进入 `~plan` 或 `~build`
+- 若主路径是 `~idea`，且用户本意就是探索/比较，则在探索输出后结束；若探索后已有明确方向且当前任务仍要求写文件或改代码，则继续进入 `~plan` 或 `~build`
 
 ### 5. 何时允许停下
 
 - 仅在 bootstrap 的阻塞判定成立时停下：真实歧义、缺必需信息/文件/凭据、未授权外部副作用、高风险或不可逆操作
-- 不得把 `~plan` / `~prd` 中“是否进入执行”的默认询问原样带入 `~auto` 链路
+- 不得把 `~plan` / `~prd` 中“是否进入执行”的默认询问原样带入 `~auto` 流程
 - 不得把“给出方案”“给出任务列表”“给出建议下一步”当作 `~auto` 的默认完成态；用户显式要求 `~auto` 时，默认目标是把当前任务推进到可交付完成

package/skills/commands/build/SKILL.md

@@ -6,9 +6,9 @@ policy:
 ---
 Trigger: ~build [description]
 
-`~build` 是执行实现命令。它负责读取现有需求、方案包与项目上下文，完成实现、局部验证、修复循环，并把结果衔接到后续验证与收尾。
+`~build` 是执行实现命令。它负责读取现有需求、方案包与项目上下文，完成实现、局部验证、修复循环，并把结果交给后续验证与收尾。
 执行 `~build` 时，通用阶段边界按当前已加载 bootstrap 执行；本 skill 负责补充实现前定位、实现约束，以及进入 `~verify` / 收尾前的实现边界。
-`.helloagents/` 在本 skill 中统一按项目级存储路径理解：`STATE.md` 与 `.ralph-*.json` 保持项目本地；若当前上下文中的“当前项目存储”给出 `state_path`，本轮恢复快照统一读写该路径；若 `project_store_mode=repo-shared`，知识库、`DESIGN.md`、`verify.yaml` 与方案包按当前上下文中已注入的项目知识/方案目录解析。
+`.helloagents/` 在本 skill 中统一按项目级存储路径理解：状态文件只使用 `state_path`，`.ralph-*.json` 保持项目本地；若 `project_store_mode=repo-shared`，知识库、`DESIGN.md`、`verify.yaml` 与方案包按当前上下文中已注入的项目知识/方案目录解析。
 
 ## 铁律
 - 默认先定位上下文与范围，再修改代码
@@ -20,7 +20,7 @@ Trigger: ~build [description]
 
 ### 1. 恢复与定位
 
-- 优先按当前已加载 bootstrap 的“.helloagents/ 文件读取优先级”恢复当前链路；若当前消息显式继续既有链路，或会话刚经历恢复 / 压缩，先读取 `.helloagents/STATE.md` 作为恢复快照（若当前项目存储给出 `state_path`，则优先读取该当前会话的 `STATE.md`），再用当前用户消息、活跃方案包 / PRD 与代码事实校正主线
+- 优先按当前已加载 bootstrap 的“.helloagents/ 文件读取优先级”恢复当前任务；若当前消息明确要继续上次任务，或会话刚经历恢复 / 压缩，先读取 `state_path`，再用当前用户消息、活跃方案包 / PRD 与代码事实确认当前任务
 - 若存在最近的活跃方案包，读取对应的：
   - `requirements.md`
   - `plan.md`
@@ -46,7 +46,7 @@ Trigger: ~build [description]
 ### 3. 执行实现
 
 - 根据任务拆解逐步修改
-- 读取 PLAN 阶段所需的 hello-* 技能并遵循其规范
+- 按当前实现需要读取对应的 hello-* 技能，并遵循其规范
 - 编码任务遵循：
   - 先补测试或最小验证手段，再写实现
   - 每次编辑后主动跑确定性检查
@@ -59,9 +59,9 @@ Trigger: ~build [description]
 - 若失败，修复后重跑
 - 若涉及 review 场景，可按需读取 `hello-review`
 
-### 5. 交付衔接
+### 5. 交付前处理
 
 - 有方案包时，只同步本次实现直接影响的任务状态；未完成项保持打开
 - 当前实现已闭合、且需要进入交付或收尾时，转入 `~verify`
-- `STATE.md`、知识库、`CHANGELOG.md`、modules 文档与归档边界，按当前已加载 bootstrap 的 VERIFY / CONSOLIDATE 规则执行
+- 状态文件、知识库、`CHANGELOG.md`、modules 文档与归档边界，按当前已加载 bootstrap 的 VERIFY / CONSOLIDATE 规则执行
 - 不在 `~build` 内把仍未闭合的方案包整体报告为已完成

package/skills/commands/clean/SKILL.md

@@ -6,18 +6,18 @@ policy:
 ---
 Trigger: ~clean
 
-执行 `~clean` 时，方案包归档、临时文件清理和 `STATE.md` 更新边界按当前已加载 bootstrap 执行；本命令只负责判定哪些方案包可以清理，以及输出清理摘要。
-`.helloagents/` 在本 skill 中统一按项目级存储路径理解：`STATE.md` 和临时运行态文件保持项目本地；若当前上下文中的“当前项目存储”给出 `state_path`，本轮恢复快照统一读写该路径；若 `project_store_mode=repo-shared`，`plans/` 与 `archive/` 按当前上下文中已注入的项目知识/方案目录解析。
+执行 `~clean` 时，方案包归档、临时文件清理和状态文件更新范围按当前已加载 bootstrap 执行；本命令只负责判定哪些方案包可以清理，以及输出清理摘要。
+`.helloagents/` 在本 skill 中统一按项目级存储路径理解：状态文件只使用 `state_path`，临时运行态文件保持项目本地；若 `project_store_mode=repo-shared`，`plans/` 与 `archive/` 按当前上下文中已注入的项目知识/方案目录解析。
 
 ## 流程
 
 1. 扫描 `.helloagents/plans/` 下的方案包（按当前项目存储模式解析；`project_store_mode=repo-shared` 时使用共享知识/方案目录）
-2. 判定完成状态：优先以 tasks.md 中所有任务已标记 [√] 为准；只有任务清单无法判断时，才把 `STATE.md` 中与当前方案一致的“主线目标”+“正在做什么”作为辅助信号，避免把旧恢复快照误当当前主线
+2. 判定完成状态：优先以 tasks.md 中所有任务已标记 [√] 为准；只有任务清单无法判断时，才读取 `state_path` 中与当前方案一致的“主线目标”+“正在做什么”作为辅助信息
 3. 已完成的方案包 → 按 bootstrap 的归档规则移入 `.helloagents/archive/YYYY-MM/`（按当前项目存储模式解析），并同步更新 `.helloagents/archive/_index.md`
 4. 清理 bootstrap 中定义的临时文件
-5. 按 bootstrap 的流程状态规则更新 `STATE.md`；若当前状态指向已归档方案包，则清空对应方案路径
+5. 按 bootstrap 的流程状态规则更新 `state_path`；若当前状态指向已归档方案包，则清空对应方案路径
 7. 输出清理摘要（归档了几个方案包、清理了哪些文件）
 
 ## 不删除
-- 除按流程状态规则必须重写的 `STATE.md` 外，不删除流程状态文件
-- 不删除知识沉淀文件或项目级设计契约
+- 除按流程状态规则必须重写的 `state_path` 外，不删除流程状态文件
+- 不删除知识文件或项目级设计契约

package/skills/commands/commit/SKILL.md

@@ -6,7 +6,7 @@ policy:
 ---
 Trigger: ~commit [message]
 
-执行 `~commit` 时，知识库同步与 `STATE.md` 更新边界按当前已加载 bootstrap 的 CONSOLIDATE / 流程状态规则执行；本命令只负责生成提交信息、读取提交归属配置并完成提交动作。
+执行 `~commit` 时，知识库同步与状态文件更新范围按当前已加载 bootstrap 的 CONSOLIDATE / 流程状态规则执行；本命令只负责生成提交信息、读取提交归属配置并完成提交动作。
 
 ## 流程
 
@@ -20,7 +20,7 @@ Trigger: ~commit [message]
    - ""（空，默认）→ 不添加归属
    - 有内容（如 "Co-Authored-By: HelloAGENTS"）→ 添加该内容到 commit message
 6. 执行 git commit
-7. 若当前 `STATE.md` 已存在（优先取当前项目存储中的 `state_path`，未注入时回退 `.helloagents/STATE.md`），按 bootstrap 的“已有则更新”规则同步当前已提交状态
+7. 若 `state_path` 已存在，按 bootstrap 的“已有则更新”规则同步当前已提交状态
 
 ## 知识库同步
 提交后，继续复用上方已解析的同一份设置获取 `kb_create_mode`，不要再次读取 `~/.helloagents/helloagents.json`：

package/skills/commands/help/SKILL.md

@@ -12,8 +12,8 @@ Trigger: ~help
 | 命令 | 说明 |
 |------|------|
 | ~idea | 轻量点子探索与方向比较 |
-| ~auto | 自动编排：自动选主路径并持续衔接到执行 / 验证 / 收尾，除非命中真实阻塞 |
-| ~plan | 结构化规划：需求澄清 + 方案收敛 + 方案包 |
+| ~auto | 自动执行：自动选主路径并持续推进到执行 / 验证 / 收尾，除非命中真实阻塞 |
+| ~plan | 结构化规划：需求澄清 + 方案确认 + 方案包 |
 | ~build | 执行实现：按需求或方案包完成实现与验证 |
 | ~prd | 完整 PRD：头脑风暴式逐维度挖掘，生成现代产品需求文档 |
 | ~loop | 自主迭代优化：设定目标和指标，循环修改-验证-保留/回滚 |
@@ -32,7 +32,7 @@ Trigger: ~help
 
 ### 自动激活技能
 以下技能仅在全局模式或已激活项目中自动激活（例如执行过 `~wiki`、`~init`，或已处于项目级连续流程）。
-纯标准模式未激活项目不会自动触发这些深层技能；但涉及 UI 的任务仍受 UI 质量基线约束。
+纯标准模式未激活项目不会自动触发这些技能；但涉及 UI 的任务仍受 UI 质量基线约束。
 
 编码时：hello-ui, hello-api, hello-data, hello-security, hello-errors, hello-perf, hello-arch, hello-test
 特定场景：hello-debug, hello-subagent, hello-write, hello-review

package/skills/commands/idea/SKILL.md

@@ -6,12 +6,12 @@ policy:
 ---
 Trigger: ~idea [description]
 
-`~idea` 是轻量探索命令，用于在不落盘、不进入执行、不激活完整项目流程的前提下，帮用户快速比较方向、生成点子、收敛方案。
+`~idea` 是轻量探索命令，用于在不写文件、不进入执行、不激活完整项目流程的前提下，帮用户快速比较方向、生成点子、明确方案。
 
 ## 铁律
 - 只讨论，不编写实现代码，不创建项目文件，不执行实现操作
 - 不创建 `.helloagents/`
-- 不创建或更新 `.helloagents/STATE.md`；若当前项目存储给出 `state_path`，同样禁止更新该当前 `STATE.md`、知识库文件、方案包或项目级规则文件
+- 不创建或更新当前项目存储中的 `state_path`；同样禁止更新知识库文件、方案包或项目级规则文件
 - 不生成方案包
 - 不执行会改变工作区或外部状态的命令
 - 不默认使用子代理
@@ -45,11 +45,11 @@ Trigger: ~idea [description]
   - 想形成结构化方案 → `~plan`
   - 想直接进入实现 → `~build`
   - 需要重型产品规格 → `~prd`
-  - 想让 AI 自动编排完整链路 → `~auto`
-- 如果用户在 `~idea` 过程中转而明确要求写文件、改代码、创建知识库或执行命令，不在 `~idea` 内偷偷落地；改为按最合适的升级路径继续
+  - 想让 AI 自动执行完整流程 → `~auto`
+- 如果用户在 `~idea` 过程中转而明确要求写文件、改代码、创建知识库或执行命令，不在 `~idea` 内偷偷写文件；改为按最合适的升级路径继续
 
 ## 输出要求
 
-- 允许发散，但必须收敛
+- 允许发散，但必须给出明确结论
 - 不做“点子堆砌”
 - 不把尚未决定的探索结果伪装成已确认方案

package/skills/commands/init/SKILL.md

@@ -7,14 +7,14 @@ policy:
 Trigger: ~init
 
 ~init 是用户显式命令，创建完整知识库，不受 kb_create_mode 限制。
-执行 `~init` 时，`.helloagents/` 目录结构、模板格式和 `STATE.md` 规则按当前已加载 bootstrap 执行；本命令额外负责项目级规则文件和各宿主项目级原生 skills 链接。
-`.helloagents/` 在本 skill 中统一按项目级存储路径理解：项目本地 `.helloagents/` 继续承担激活目录与 `STATE.md`；若当前上下文中的“当前项目存储”给出 `state_path`，本轮恢复快照统一读写该路径；若 `project_store_mode=repo-shared`，知识库、`DESIGN.md` 与方案包按当前上下文中已注入的项目知识/方案目录写入。
+执行 `~init` 时，`.helloagents/` 目录结构、模板格式和状态文件规则按当前已加载 bootstrap 执行；本命令额外负责项目级规则文件和各宿主项目级原生 skills 链接。
+`.helloagents/` 在本 skill 中统一按项目级存储路径理解：项目本地 `.helloagents/` 继续承担激活目录；状态文件只使用 `state_path`；若 `project_store_mode=repo-shared`，知识库、`DESIGN.md` 与方案包按当前上下文中已注入的项目知识/方案目录写入。
 
 ## 流程
 
 ### 阶段 1：环境搭建（必做）
 
-1. 创建 `.helloagents/` 目录 + 当前 `STATE.md`（优先取当前项目存储中的 `state_path`，未注入时回退 `.helloagents/STATE.md`；按 templates/STATE.md 格式，初始“主线目标”写当前初始化链路，初始状态为空闲）
+1. 创建 `.helloagents/` 目录 + `state_path`（按 templates/STATE.md 格式，初始“主线目标”写当前初始化任务，初始状态为空闲）
 2. 定位插件根目录：优先读取当前上下文中已注入的“当前 HelloAGENTS 包根目录”；若上下文未提供，再根据当前已加载的规则文件反推，禁止猜测其他目录
 3. 刷新各宿主项目级原生 skills 链接（删除旧的重建）：
    - `.claude/skills/helloagents` symlink → `{插件根目录}/`
@@ -62,7 +62,7 @@ commands:
 ## 幂等性
 重复执行 ~init 是安全的：
 - 已存在的 .helloagents/ 文件不覆盖
-- `STATE.md` 只作为当前初始化链路的恢复快照；后续进入其他主线任务时必须按新主线重写
+- `state_path` 只记录当前初始化任务；后续进入其他任务时必须按新任务重写
 - 各宿主项目级原生 skills 链接会刷新（删除旧的重建）
 - AGENTS.md/CLAUDE.md/GEMINI.md 中标记内容替换更新
 - .gitignore 只追加缺失行

package/skills/commands/loop/SKILL.md

@@ -19,12 +19,12 @@ Trigger: ~loop <目标描述> [--iterations N] [--metric "命令"] [--direction
 ## 初始化
 
 1. 确认 git 工作区干净（有未提交变更则先提醒用户处理）
-2. 确保 `.helloagents/` 目录和当前会话的 `STATE.md` 存在；优先使用当前项目存储中的 `state_path`，未注入时回退 `.helloagents/STATE.md`；文件不存在时按 `templates/STATE.md` 创建。这是 `~loop` 的强制恢复快照，不受 `kb_create_mode` 控制；“主线目标”固定写本次优化目标，避免被旧任务主线污染
+2. 确保 `.helloagents/` 目录和 `state_path` 存在；文件不存在时按 `templates/STATE.md` 创建。`~loop` 必须维护这个状态文件，不受 `kb_create_mode` 控制；“主线目标”固定写本次优化目标，避免混入其他任务
 3. 运行指标命令获取基线值，记录到 results log
 4. 如有守卫命令，运行确认基线通过
 5. 创建 `.helloagents/loop-results.tsv`，并确保 .gitignore 包含该文件
 6. 根据优化目标标记可能需要的 hello-* 质量技能（如性能优化标记 hello-perf，UI 优化标记 hello-ui）
-7. 重写当前会话的 `STATE.md`：记录主线目标=当前优化目标、基线指标、守卫命令、下一步设为第一轮迭代的具体动作
+7. 重写 `state_path`：记录主线目标=当前优化目标、基线指标、守卫命令、下一步设为第一轮迭代的具体动作
 
 results log 格式：
 ```
@@ -35,51 +35,51 @@ iteration	commit	metric	delta	guard	status	description
 
 ## 八阶段循环
 
-`~loop` 的八阶段循环是统一执行流程（ROUTE/TIER→SPEC→PLAN→BUILD→VERIFY→CONSOLIDATE）在迭代优化场景下的特化形式。每轮迭代的 Modify 阶段遵循已标记的 hello-* 质量技能规范，Verify 阶段遵循 hello-verify 的验证规范。
+`~loop` 的八阶段循环是统一执行流程（ROUTE/TIER→SPEC→PLAN→BUILD→VERIFY→CONSOLIDATE）在迭代优化场景下的特化形式。每轮迭代的“修改”阶段遵循已标记的 hello-* 质量技能规范，“验证”阶段遵循 hello-verify 的验证规范。
 执行 `~loop` 时，涉及公共阶段边界、阻塞判定与收尾要求的部分，仍按当前已加载 bootstrap 执行；本 skill 负责补充 loop 场景的迭代顺序与回滚规则。
 
-不要停止。不要询问是否继续。
+除非达到迭代上限或命中阻塞判定，否则继续执行，不额外询问是否继续。
 每轮迭代必须完整走完以下八个阶段：
 
-### Phase 1: Review
+### 第 1 阶段：回顾
 - 读取 results log 最近 10-20 条记录
 - 运行 `git log --oneline -20` 查看最近变更
 - 运行 `git diff HEAD~1` 查看上一次变更
 - 如果 git log 有 results log 中未记录的 experiment commit → 上轮可能中断，先运行指标命令补录结果
 - 识别：什么有效、什么无效、什么还没试过
 
-### Phase 2: Ideate
+### 第 2 阶段：构思
 - 基于 review 结果，选择下一个改进方向
 - 优先尝试未探索的方向
 - 避免重复已失败的方向（git history 是记忆）
 - 连续 5 次 discard → 升级策略：组合近似成功的尝试、尝试相反方向、考虑架构级变更
 
-### Phase 3: Modify
+### 第 3 阶段：修改
 - 做一个原子修改（单一关注点）
 - 只修改作用范围内的文件
 - 不修改测试文件和守卫命令涉及的文件
 
-### Phase 4: Commit
+### 第 4 阶段：提交
 - 在验证之前提交（便于干净回滚）
 - commit message 格式：`experiment(<scope>): <description>`
 
-### Phase 5: Verify
+### 第 5 阶段：验证
 - 运行指标命令，获取新值
 - 计算 delta（新值 - 基线或上一次保留值）
 - 如有守卫命令，运行守卫检查
 
-### Phase 6: Decide
+### 第 6 阶段：决策
 - IMPROVED（指标改善 + 守卫通过）→ keep
 - SAME/WORSE（指标未改善）→ `git revert HEAD`（保留历史）
 - GUARD FAILED（指标改善但守卫失败）→ 尝试修复（最多 2 次），仍失败则 revert
 - CRASHED（命令执行失败）→ revert + 记录
 
-### Phase 7: Log
+### 第 7 阶段：记录
 - 追加一行到 results log
 - status: baseline / keep / discard / crash / no-op
-- 重写当前会话的 `STATE.md`：保持主线目标=当前优化目标，并记录当前迭代轮次、最近一次决策（keep / discard / crash）、当前最佳指标、下一步动作
+- 重写 `state_path`：保持主线目标=当前优化目标，并记录当前迭代轮次、最近一次决策（keep / discard / crash）、当前最佳指标、下一步动作
 
-### Phase 8: Repeat
+### 第 8 阶段：继续
 - 如果 iterations > 0 且 current_iteration >= max_iterations → 输出总结并停止
 - 否则 → 回到 Phase 1
 
@@ -90,7 +90,7 @@ iteration	commit	metric	delta	guard	status	description
 - 总迭代次数 / 保留次数 / 丢弃次数
 - 最有效的 3 个改进
 - results log 路径
-- 重写当前会话的 `STATE.md`：将“主线目标”保留为本次优化目标，“正在做什么”更新为已完成，保留最终结论摘要，清空阻塞项，并给出可立即执行的下一步（如继续优化、停止、切换目标）
+- 重写 `state_path`：将“主线目标”保留为本次优化目标，“正在做什么”更新为已完成，保留最终结论摘要，清空阻塞项，并给出可立即执行的下一步（如继续优化、停止、切换目标）
 
 ## 安全规则
 - 使用 `git revert`（保留历史）而非 `git reset --hard`（丢失历史）