helloagents 3.0.8-beta.1 → 3.0.10-beta.1

package/scripts/workflow-core.mjs

@@ -13,6 +13,13 @@ import { describeProjectStoreFile, getProjectDesignContractPath } from './projec
 export function getTargetPlans(snapshot) {
   return snapshot.activePlans.length > 0 ? snapshot.activePlans : snapshot.plans
 }
+
+function describeStateLabel(state) {
+  if (state.stateSessionMode === 'default') {
+    return '当前分支默认位置的状态文件'
+  }
+  return '当前会话的状态文件'
+}
 export function classifyPlan(plan) {
   if (!plan) {
     return {
@@ -97,27 +104,28 @@ function collectStateSyncIssues(snapshot) {
   const issues = []
   const hasPlans = snapshot.plans.length > 0
   const state = snapshot.state
+  const stateLabel = describeStateLabel(state)
 
   if (!hasPlans) {
     return issues
   }
 
   if (!state.exists) {
-    issues.push('当前已存在方案包，但 `.helloagents/STATE.md` 缺失')
+    issues.push(`当前已存在方案包，但${stateLabel} 缺失`)
     return issues
   }
 
   if (!state.referencedPlanDir) {
-    issues.push('当前已存在方案包，但 `STATE.md` 未记录活跃方案路径')
+    issues.push(`${stateLabel} 未记录活跃方案路径`)
   }
   if (!state.sections['主线目标']) {
-    issues.push('`STATE.md` 缺少“主线目标”')
+    issues.push(`${stateLabel} 缺少“主线目标”`)
   }
   if (!state.sections['正在做什么']) {
-    issues.push('`STATE.md` 缺少“正在做什么”')
+    issues.push(`${stateLabel} 缺少“正在做什么”`)
   }
   if (!state.sections['下一步']) {
-    issues.push('`STATE.md` 缺少“下一步”')
+    issues.push(`${stateLabel} 缺少“下一步”`)
   }
 
   return issues
@@ -132,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 '恢复约束：当前仅检测到 `.helloagents/STATE.md`；先以当前用户消息、显式命令和代码事实确认主线，STATE.md 只用于找回上次停在哪，不是当前任务的自动授权或唯一判断依据。'
+  return `恢复约束：当前仅检测到${describeStateLabel(snapshot.state)}；先以当前用户消息、显式命令和代码事实确认当前任务。状态文件只用于找回上次停在哪，不是当前任务的自动授权或唯一判断依据。`
 }
 
 export function buildUiContractHint(cwd, snapshot) {
@@ -159,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-plan-files.mjs

@@ -2,7 +2,11 @@ import { existsSync, readdirSync, readFileSync } from 'node:fs'
 import { isAbsolute, join, normalize } from 'node:path'
 
 import { getPlanContractIssues, readPlanContract } from './plan-contract.mjs'
-import { getProjectPlansDir, getProjectStatePath, resolveProjectPlanDir } from './project-storage.mjs'
+import {
+  getProjectPlansDir,
+  getProjectSessionStateScope,
+  resolveProjectPlanDir,
+} from './project-storage.mjs'
 
 const PLAN_TEMPLATE_MARKERS = {
   'requirements.md': [
@@ -170,15 +174,22 @@ function comparePlanEntries(a, b) {
   return a.planName.localeCompare(b.planName)
 }
 
-export function readStateSnapshot(cwd) {
-  const statePath = getProjectStatePath(cwd)
+export function readStateSnapshot(cwd, options = {}) {
+  const stateScope = getProjectSessionStateScope(cwd, options)
+  const statePath = stateScope.statePath
+  const exists = existsSync(statePath)
   const content = readText(statePath)
   const sections = parseMarkdownSections(content)
   const referencedPlanDir = resolvePlanDir(cwd, sections['方案'])
 
   return {
     statePath,
-    exists: existsSync(statePath),
+    stateScope: stateScope.stateScope,
+    stateSessionToken: stateScope.stateSessionToken,
+    stateSessionMode: stateScope.stateSessionMode,
+    stateBranch: stateScope.stateBranch,
+    sessionScoped: stateScope.stateScope === 'session',
+    exists,
     content,
     sections,
     referencedPlanDir,
@@ -230,8 +241,8 @@ export function listPlanPackages(cwd) {
     .sort(comparePlanEntries)
 }
 
-export function getWorkflowSnapshot(cwd) {
-  const state = readStateSnapshot(cwd)
+export function getWorkflowSnapshot(cwd, options = {}) {
+  const state = readStateSnapshot(cwd, options)
   const plans = listPlanPackages(cwd).map((entry) => ({
     ...entry,
     referencedByState: state.referencedPlanDir ? normalize(entry.dirPath) === normalize(state.referencedPlanDir) : false,

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

@@ -16,27 +16,27 @@ import {
   buildRecommendation,
 } from './workflow-recommendation.mjs'
 
-export function getDeliveryAction(cwd) {
-  const snapshot = getWorkflowSnapshot(cwd)
+export function getDeliveryAction(cwd, options = {}) {
+  const snapshot = getWorkflowSnapshot(cwd, options)
   const recommendation = buildRecommendation(snapshot, cwd)
   return buildDeliveryActionFromSnapshot(snapshot, cwd, recommendation)
 }
 
-export function getWorkflowRecommendation(cwd) {
-  return buildRecommendation(getWorkflowSnapshot(cwd), cwd)
+export function getWorkflowRecommendation(cwd, options = {}) {
+  return buildRecommendation(getWorkflowSnapshot(cwd, options), cwd)
 }
 
-export function buildStateSyncHint(cwd) {
-  return buildStateSyncHintFromSnapshot(getWorkflowSnapshot(cwd))
+export function buildStateSyncHint(cwd, options = {}) {
+  return buildStateSyncHintFromSnapshot(getWorkflowSnapshot(cwd, options))
 }
 
-export function buildDeliveryGateHint(cwd) {
-  const snapshot = getWorkflowSnapshot(cwd)
+export function buildDeliveryGateHint(cwd, options = {}) {
+  const snapshot = getWorkflowSnapshot(cwd, options)
   return buildDeliveryGateHintFromSnapshot(snapshot, cwd, buildRecommendation(snapshot, cwd))
 }
 
-export function buildWorkflowRouteHint(cwd) {
-  const snapshot = getWorkflowSnapshot(cwd)
+export function buildWorkflowRouteHint(cwd, options = {}) {
+  const snapshot = getWorkflowSnapshot(cwd, options)
   const recommendation = buildRecommendation(snapshot, cwd)
   const stateSyncHint = buildStateSyncHintFromSnapshot(snapshot)
   const stateRoleHint = buildStateRoleHintFromSnapshot(snapshot)
@@ -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') {
@@ -87,8 +87,8 @@ function buildCommandRouteMessage(skillName, recommendation, verifyModeHint) {
   return `当前工作流约束：${recommendation.summary} 当前建议下一命令：~${recommendation.nextCommand}。${recommendation.guidance}`
 }
 
-export function buildCommandRouteHint(skillName, cwd) {
-  const snapshot = getWorkflowSnapshot(cwd)
+export function buildCommandRouteHint(skillName, cwd, options = {}) {
+  const snapshot = getWorkflowSnapshot(cwd, options)
   const recommendation = buildRecommendation(snapshot, cwd)
   const contextHints = [
     buildStateRoleHintFromSnapshot(snapshot),

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` 保持项目本地；若 `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` 作为恢复快照，再用当前用户消息、活跃方案包 / PRD 与代码事实校正主线
+- 优先按当前已加载 bootstrap 的“.helloagents/ 文件读取优先级”恢复当前任务；若当前消息明确要继续上次任务，或会话刚经历恢复 / 压缩，先读取 `state_path`，再用当前用户消息、活跃方案包 / PRD 与代码事实确认当前任务
 - 若存在最近的活跃方案包，读取对应的：
   - `requirements.md`
   - `plan.md`
@@ -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` 和临时运行态文件保持项目本地；若 `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. 若项目已有 `.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 | 自主迭代优化：设定目标和指标，循环修改-验证-保留/回滚 |

package/skills/commands/idea/SKILL.md

@@ -6,12 +6,12 @@ policy:
 ---
 Trigger: ~idea [description]
 
-`~idea` 是轻量探索命令，用于在不落盘、不进入执行、不激活完整项目流程的前提下，帮用户快速比较方向、生成点子、收敛方案。
+`~idea` 是轻量探索命令，用于在不写文件、不进入执行、不激活完整项目流程的前提下，帮用户快速比较方向、生成点子、明确方案。
 
 ## 铁律
 - 只讨论，不编写实现代码，不创建项目文件，不执行实现操作
 - 不创建 `.helloagents/`
-- 不创建或更新 `.helloagents/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`；若 `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`（按 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/` 目录和 `.helloagents/STATE.md` 存在；目录不存在时先创建，`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. 重写 `.helloagents/STATE.md`：记录主线目标=当前优化目标、基线指标、守卫命令、下一步设为第一轮迭代的具体动作
+7. 重写 `state_path`：记录主线目标=当前优化目标、基线指标、守卫命令、下一步设为第一轮迭代的具体动作
 
 results log 格式：
 ```
@@ -77,7 +77,7 @@ iteration	commit	metric	delta	guard	status	description
 ### Phase 7: Log
 - 追加一行到 results log
 - status: baseline / keep / discard / crash / no-op
-- 重写 `.helloagents/STATE.md`：保持主线目标=当前优化目标，并记录当前迭代轮次、最近一次决策（keep / discard / crash）、当前最佳指标、下一步动作
+- 重写 `state_path`：保持主线目标=当前优化目标，并记录当前迭代轮次、最近一次决策（keep / discard / crash）、当前最佳指标、下一步动作
 
 ### Phase 8: Repeat
 - 如果 iterations > 0 且 current_iteration >= max_iterations → 输出总结并停止
@@ -90,7 +90,7 @@ iteration	commit	metric	delta	guard	status	description
 - 总迭代次数 / 保留次数 / 丢弃次数
 - 最有效的 3 个改进
 - results log 路径
-- 重写 `.helloagents/STATE.md`：将“主线目标”保留为本次优化目标，“正在做什么”更新为已完成，保留最终结论摘要，清空阻塞项，并给出可立即执行的下一步（如继续优化、停止、切换目标）
+- 重写 `state_path`：将“主线目标”保留为本次优化目标，“正在做什么”更新为已完成，保留最终结论摘要，清空阻塞项，并给出可立即执行的下一步（如继续优化、停止、切换目标）
 
 ## 安全规则
 - 使用 `git revert`（保留历史）而非 `git reset --hard`（丢失历史）

package/skills/commands/plan/SKILL.md

@@ -1,20 +1,20 @@
 ---
 name: ~plan
-description: 结构化规划工作流 — 需求澄清、方案收敛、任务分解与方案包生成（~plan 命令）
+description: 结构化规划工作流 — 需求澄清、方案确认、任务分解与方案包生成（~plan 命令）
 policy:
   allow_implicit_invocation: false
 ---
 Trigger: ~plan [description]
 
-`~plan` 是实现前的主规划命令。它负责需求澄清、方案设计、任务拆解与方案落盘；直接显式执行 `~plan` 时，默认停在“形成可执行方案”，只有用户明确授权继续时才衔接执行。
-执行 `~plan` 时，通用阶段边界按当前已加载 bootstrap 执行；本 skill 负责补充 `~plan` 的需求澄清、方案收敛、方案包写入与执行衔接要求。
-`.helloagents/` 在本 skill 中统一按项目级存储路径理解：`STATE.md` 与 `.ralph-*.json` 保持项目本地；若 `project_store_mode=repo-shared`，知识库、`DESIGN.md` 与 `plans/` / `archive/` 按当前上下文中已注入的项目知识/方案目录解析。
+`~plan` 是实现前的主规划命令。它负责需求澄清、方案设计、任务拆解与方案写入；直接显式执行 `~plan` 时，默认停在“形成可执行方案”，只有用户明确授权继续时才继续执行。
+执行 `~plan` 时，通用阶段边界按当前已加载 bootstrap 执行；本 skill 负责补充 `~plan` 的需求澄清、方案确认、方案包写入与继续执行要求。
+`.helloagents/` 在本 skill 中统一按项目级存储路径理解：状态文件只使用 `state_path`，`.ralph-*.json` 保持项目本地；若 `project_store_mode=repo-shared`，知识库、`DESIGN.md` 与 `plans/` / `archive/` 按当前上下文中已注入的项目知识/方案目录解析。
 
 ## 铁律
 - 在用户确认方案之前，禁止编写任何实现代码、创建任何实现文件、或执行任何实现操作
 - 需求澄清阶段不读取实现类技能（hello-ui / hello-test / hello-verify 等），需求明确后再按需读取
-- 方案必须收敛为可执行产物，不停留在泛化建议
-- 若当前链路来自 `~auto`，则“开始执行”视为已包含在 `~auto` 授权内；方案包落地后默认继续衔接执行，只有命中阻塞判定时才停下
+- 方案必须整理为可执行产物，不停留在泛化建议
+- 若当前任务来自 `~auto`，则“开始执行”视为已包含在 `~auto` 授权内；方案包写入后默认继续执行，只有命中阻塞判定时才停下
 - 涉及 UI 时，当前方案包中的 UI 决策优先于 `.helloagents/DESIGN.md`；`.helloagents/DESIGN.md`（按当前项目存储模式解析）优先于通用 UI 规则
 
 ## 流程
@@ -22,7 +22,7 @@ Trigger: ~plan [description]
 ### 1. 上下文收集与需求澄清准备
 
 已有项目：
-- 按当前已加载 bootstrap 的“.helloagents/ 文件读取优先级”和“项目文件”规则恢复上下文；若当前消息显式继续既有链路，或会话刚经历恢复 / 压缩，先把 `.helloagents/STATE.md` 当恢复快照使用，再用当前用户消息、显式命令、活跃方案包 / PRD 与代码事实校正主线
+- 按当前已加载 bootstrap 的“.helloagents/ 文件读取优先级”和“项目文件”规则恢复上下文；若当前消息明确要继续上次任务，或会话刚经历恢复 / 压缩，先读取 `state_path`，再用当前用户消息、显式命令、活跃方案包 / PRD 与代码事实确认当前任务
 - 在需求澄清前，至少确认 `.helloagents/context.md`、`.helloagents/guidelines.md`（按当前项目存储模式解析）；涉及 UI 时，如存在 `.helloagents/DESIGN.md`（按当前项目存储模式解析），一并读取现有设计契约
 - 只扫描与当前需求直接相关的代码文件，用于形成假设和识别约束
 
@@ -49,7 +49,7 @@ Trigger: ~plan [description]
 - 选项必须体现当前前沿水准
 - 每个选项都要有具体、可执行的视觉特征描述
 
-### 3. 方案收敛
+### 3. 方案确认
 
 基于已确认需求，给出 2-3 个可行方案：
 - 每个方案说明架构思路与关键取舍
@@ -81,12 +81,12 @@ Trigger: ~plan [description]
   - `tasks.md`
   - `contract.json`
 - 写 `contract.json` 时，至少落成以下字段：`verifyMode`、`reviewerFocus`、`testerFocus`；涉及 UI 时再写 `ui.required`、`ui.designContract` 与 `ui.sourcePriority`
-- 只有在 UI 方向确需前置收敛时，才额外写 `ui.styleAdvisor.required`、`ui.styleAdvisor.reason` 与 `ui.styleAdvisor.focus`；它复用 `.helloagents/.ralph-advisor.json`，不是默认常驻步骤
+- 只有在 UI 方向确需先明确时，才额外写 `ui.styleAdvisor.required`、`ui.styleAdvisor.reason` 与 `ui.styleAdvisor.focus`；它复用 `.helloagents/.ralph-advisor.json`，不是默认常驻步骤
 - 只有在 UI 验收确有收益时，才额外写 `ui.visualValidation.required`、`ui.visualValidation.reason`、`ui.visualValidation.screens` 与 `ui.visualValidation.states`；不要把视觉验收扩成所有 UI 任务的固定步骤
 - 只有在 `T3`、非 UI 的高风险审查或确需额外跨模型建议时，才写 `advisor.required`、`advisor.reason`、`advisor.focus` 与 `advisor.preferredSources`；不要把 advisor 变成默认常驻流程
 - 使用 `scripts/plan-contract.mjs write` 写 `contract.json`，不要让后续检查脚本再从 `plan.md` 的自然语言说明里猜验证主路径
 - 涉及 UI 的项目：生成或更新 `.helloagents/DESIGN.md`（按当前项目存储模式解析）；若原文件不存在，先按模板建立最小设计契约，再写入已确认的稳定设计决策
-- 重写 `.helloagents/STATE.md`，其中“主线目标”写当前规划链路真正要完成的目标，不把旧任务残留为当前主线
+- 重写 `state_path`，其中“主线目标”写本次规划要完成的目标，不保留其他任务的内容
 
 知识库完整创建与归档按当前已加载 bootstrap 的后续规则执行。
 
@@ -95,10 +95,10 @@ Trigger: ~plan [description]
 展示方案摘要后，仅在是否进入执行仍构成阻塞决策时才询问用户：
 - 开始执行 → 继续进入 `~build`
 - 修改方案 → 返回方案细化
-- 暂不执行，保留方案 → 更新 `STATE.md`；“主线目标”写当前已确认方案要解决的问题，下一步写为“方案已确认；执行需用户明确启动”
+- 暂不执行，保留方案 → 更新 `state_path`；“主线目标”写当前已确认方案要解决的问题，下一步写为“方案已确认；执行需用户明确启动”
 
-如果用户已明确表示继续执行，则视为授权成立，可直接衔接执行。
-如果当前链路来自 `~auto`，且方案包已足够支撑实现、也未命中阻塞判定，则默认直接进入 `~build`，不再追加一次“是否开始执行”的询问。
+如果用户已明确表示继续执行，则视为授权成立，可直接继续执行。
+如果当前任务来自 `~auto`，且方案包已足够支撑实现、也未命中阻塞判定，则默认直接进入 `~build`，不再追加一次“是否开始执行”的询问。
 
 ## 方案包要求
 

package/skills/commands/prd/SKILL.md

@@ -7,16 +7,16 @@ policy:
 Trigger: ~prd [description]
 
 执行 `~prd` 时，不读取 `~plan` 的 command skill；只有当前流程明确需要时，才继续读取对应的 hello-* 技能。
-执行 `~prd` 时，通用阶段边界按当前已加载 bootstrap 执行；本 skill 负责补充规格探索、PRD 落盘与执行衔接要求。
-`.helloagents/` 在本 skill 中统一按项目级存储路径理解：`STATE.md` 与 `.ralph-*.json` 保持项目本地；若 `project_store_mode=repo-shared`，知识库、`DESIGN.md` 与 `plans/` / `archive/` 按当前上下文中已注入的项目知识/方案目录解析。
+执行 `~prd` 时，通用阶段边界按当前已加载 bootstrap 执行；本 skill 负责补充规格探索、PRD 写入与继续执行要求。
+`.helloagents/` 在本 skill 中统一按项目级存储路径理解：状态文件只使用 `state_path`，`.ralph-*.json` 保持项目本地；若 `project_store_mode=repo-shared`，知识库、`DESIGN.md` 与 `plans/` / `archive/` 按当前上下文中已注入的项目知识/方案目录解析。
 
 ## 铁律
 - 在用户确认方案之前，禁止编写任何实现代码、创建任何文件、或执行任何实现操作。
 - 每个维度的选项必须体现当前前沿水准。若当前已加载 bootstrap 含审美/体验规则则遵循其要求；否则至少给出具体、可执行、非泛化的视觉特征，不确定时主动搜索查阅。
 - 用户说"跳过"某维度 → 跳过，不生成该文件。不强迫用户讨论不关心的维度。
 - 大项目检测：涉及多个独立子系统时，先帮用户分解为子项目，每个子项目走独立的 ~prd 循环。
-- 若当前链路来自 `~auto`，则 PRD / 任务 / 契约落地后默认继续衔接后续执行；只有真实阻塞时才停在规格阶段。
-- 涉及 UI 时，`prd/03-ui-design.md` 负责沉淀本次产品/功能的 UI 决策；项目级稳定设计契约同步写入 `.helloagents/DESIGN.md`（按当前项目存储模式解析）
+- 若当前任务来自 `~auto`，则 PRD / 任务 / 契约写入后默认继续执行；只有真实阻塞时才停在规格阶段。
+- 涉及 UI 时，`prd/03-ui-design.md` 负责记录本次产品/功能的 UI 决策；项目级稳定设计契约同步写入 `.helloagents/DESIGN.md`（按当前项目存储模式解析）
 
 ## PRD 维度清单
 
@@ -58,7 +58,7 @@ Trigger: ~prd [description]
 ### 1. 上下文收集
 
 已有项目：
-- 按当前已加载 bootstrap 的“.helloagents/ 文件读取优先级”和“项目文件”规则恢复上下文；若当前消息显式继续既有链路，或会话刚经历恢复 / 压缩，先把 `.helloagents/STATE.md` 当恢复快照使用，再用当前用户消息、显式命令、活跃方案包 / PRD 与代码事实校正主线
+- 按当前已加载 bootstrap 的“.helloagents/ 文件读取优先级”和“项目文件”规则恢复上下文；若当前消息明确要继续上次任务，或会话刚经历恢复 / 压缩，先读取 `state_path`，再用当前用户消息、显式命令、活跃方案包 / PRD 与代码事实确认当前任务
 - 在进入维度探索前，至少确认 `.helloagents/context.md`、`.helloagents/guidelines.md`，并只扫描与当前产品范围直接相关的代码和配置
 
 全新项目（无 .helloagents/ 目录）：
@@ -102,26 +102,26 @@ c. AI 总结该维度的决策结果，进入下一个维度
 - 按 templates/plans/prd/ 的模板格式，仅写入用户未跳过的维度文件
 - 生成 tasks.md（每个任务包含具体文件路径、预期变更、完成标准、验证方式；任务独立可验证；依赖顺序明确）
 - 生成 decisions.md（贯穿全程的决策日志）
-- 生成 `contract.json`（至少包含 `verifyMode`、`reviewerFocus`、`testerFocus`；涉及 UI 时补 `ui.required`、`ui.designContract`、`ui.sourcePriority`；仅在确需前置审美收敛时再补 `ui.styleAdvisor.required`、`ui.styleAdvisor.reason`、`ui.styleAdvisor.focus`；仅在确需视觉验收时再补 `ui.visualValidation.required`、`ui.visualValidation.reason`、`ui.visualValidation.screens`、`ui.visualValidation.states`；仅在确需独立 advisor 时，再补 `advisor.required`、`advisor.reason`、`advisor.focus`、`advisor.preferredSources`）
+- 生成 `contract.json`（至少包含 `verifyMode`、`reviewerFocus`、`testerFocus`；涉及 UI 时补 `ui.required`、`ui.designContract`、`ui.sourcePriority`；仅在确需先明确审美方向时再补 `ui.styleAdvisor.required`、`ui.styleAdvisor.reason`、`ui.styleAdvisor.focus`；仅在确需视觉验收时再补 `ui.visualValidation.required`、`ui.visualValidation.reason`、`ui.visualValidation.screens`、`ui.visualValidation.states`；仅在确需独立 advisor 时，再补 `advisor.required`、`advisor.reason`、`advisor.focus`、`advisor.preferredSources`）
 - 使用 `scripts/plan-contract.mjs write` 写 `contract.json`，不要只把验证路径留在自然语言说明里
 - 涉及 UI 的项目：生成或更新 `.helloagents/DESIGN.md`（按当前项目存储模式解析）；若原文件不存在，先按模板建立最小设计契约，再同步已确认的稳定 UI 决策
-- 重写 `.helloagents/STATE.md`，其中“主线目标”写当前 PRD 链路真正要完成的产品 / 功能目标，不延续无关旧主线
+- 重写 `state_path`，其中“主线目标”写本次 PRD 要完成的产品 / 功能目标，不保留其他任务的内容
 
 输出 PRD 完整度摘要：已覆盖 N/13 个维度，建议后续补充的维度（如有）。
 
 ### 5. 执行决策
 
 展示 PRD 摘要后，仅在是否进入执行仍构成阻塞决策时才询问用户：
-- 开始执行 → 重写 `STATE.md`（“主线目标”保持当前 PRD 目标，下一步设为第一个任务的具体动作）
+- 开始执行 → 重写 `state_path`（“主线目标”保持当前 PRD 目标，下一步设为第一个任务的具体动作）
 - 修改 PRD / 补充维度 → 回到对应维度继续讨论
-- 暂不执行，保留方案 → 重写 `STATE.md`（“主线目标”保持当前 PRD 目标，下一步设为“方案已确认；执行需用户明确启动”）
+- 暂不执行，保留方案 → 重写 `state_path`（“主线目标”保持当前 PRD 目标，下一步设为“方案已确认；执行需用户明确启动”）
 
-如果用户已对当前 PRD 或继续执行作出明确同意，视为执行授权成立，可直接进入执行，或按需先补一轮 `~plan` 收敛实现方案。
-如果当前链路来自 `~auto`，且 PRD 已收敛到可执行任务、也未命中阻塞判定，则默认继续进入 `~build`，必要时先补一轮轻量 `~plan`，不再额外询问一次“是否开始执行”。
+如果用户已对当前 PRD 或继续执行作出明确同意，视为执行授权成立，可直接进入执行，或按需先补一轮 `~plan` 明确实现方案。
+如果当前任务来自 `~auto`，且 PRD 已整理成可执行任务、也未命中阻塞判定，则默认继续进入 `~build`，必要时先补一轮轻量 `~plan`，不再额外询问一次“是否开始执行”。
 
-### 6. 执行衔接
+### 6. 继续执行
 
-按 tasks.md 逐项完成，每项进入当前已加载 bootstrap 中定义的统一执行流程，完成后同步重写 STATE.md。
+按 tasks.md 逐项完成，每项进入当前已加载 bootstrap 中定义的统一执行流程，完成后同步重写 `state_path`。
 任务状态标记仅写入 tasks.md、验收清单或验证结果；普通说明、方案解释、状态汇报不用 [√] / [-] / [ ]。
 所有任务完成后进入当前已加载 bootstrap 中定义的 VERIFY / CONSOLIDATE 收尾阶段。
 可并行的任务标记后用子代理并行执行（不同子代理不改同一文件）。