helloagents 3.0.19 → 3.0.20-beta.1

package/scripts/runtime-scope.mjs

@@ -1,20 +1,22 @@
 import { execFileSync } from 'node:child_process'
 import { createHash, randomUUID } from 'node:crypto'
-import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs'
 import { dirname, join, normalize, resolve } from 'node:path'
 import { homedir } from 'node:os'
 
 import { resolveSessionToken } from './session-token.mjs'
 import { USER_RUNTIME_MAX_AGE_MS } from './runtime-ttl.mjs'
+import { cleanupUserRuntimeRoot, getUserRuntimeRoot } from './runtime-user-cleanup.mjs'
 
 export const PROJECT_DIR_NAME = '.helloagents'
 export const PROJECT_SESSIONS_DIR_NAME = 'sessions'
 export const PROJECT_ARTIFACTS_DIR_NAME = 'artifacts'
 export const CAPSULE_FILE_NAME = 'capsule.json'
 export const EVENTS_FILE_NAME = 'events.jsonl'
+export const ACTIVE_SESSION_FILE_NAME = 'active.json'
 export const DEFAULT_STATE_SESSION_TOKEN = 'default'
 export const USER_RUNTIME_DIR_NAME = 'runtime'
-export { USER_RUNTIME_MAX_AGE_MS }
+export { cleanupUserRuntimeRoot, getUserRuntimeRoot, USER_RUNTIME_MAX_AGE_MS }
 
 function normalizePath(filePath = '') {
   return filePath ? normalize(resolve(filePath)) : ''
@@ -68,6 +70,22 @@ function resolveGitBranchName(cwd) {
   return symbolicName && symbolicName !== 'HEAD' ? symbolicName : ''
 }
 
+function resolveGitShortHead(cwd) {
+  return runGit(cwd, ['rev-parse', '--short', 'HEAD'])
+}
+
+function resolveWorkspaceName(cwd) {
+  const branchName = resolveGitBranchName(cwd)
+  if (branchName) return sanitizeRuntimeSegment(branchName, 'workspace')
+
+  if (resolveGitTopLevel(cwd)) {
+    const shortHead = sanitizeRuntimeSegment(resolveGitShortHead(cwd), '')
+    return shortHead ? `detached-${shortHead}` : 'detached'
+  }
+
+  return 'workspace'
+}
+
 export function sanitizeRuntimeSegment(value = '', fallback = '') {
   const normalized = String(value)
     .trim()
@@ -101,10 +119,6 @@ export function getProjectRoot(cwd) {
   return activeDir ? dirname(activeDir) : normalizePath(cwd || process.cwd())
 }
 
-export function getUserRuntimeRoot(home = getHomeDir()) {
-  return join(home, PROJECT_DIR_NAME, USER_RUNTIME_DIR_NAME)
-}
-
 function isUserHomeHelloagentsDir(dirPath) {
   const homeCandidates = [
     getHomeDir(),
@@ -151,57 +165,19 @@ function findProjectActivationDir(cwd) {
   return ''
 }
 
-function removePathIfExists(filePath, result, bucket) {
-  if (!existsSync(filePath)) return
-  try {
-    rmSync(filePath, { recursive: true, force: true })
-    result[bucket].push(filePath)
-  } catch (error) {
-    result.errors.push(`${filePath}: ${error.message}`)
-  }
-}
-
-export function cleanupUserRuntimeRoot({
-  home = getHomeDir(),
-  now = Date.now(),
-  maxAgeMs = USER_RUNTIME_MAX_AGE_MS,
-} = {}) {
-  const root = getUserRuntimeRoot(home)
-  const result = {
-    root,
-    removedExpiredDirs: [],
-    errors: [],
-  }
-
-  if (!existsSync(root)) return result
-
-  let entries = []
-  try {
-    entries = readdirSync(root, { withFileTypes: true })
-  } catch (error) {
-    result.errors.push(`${root}: ${error.message}`)
-    return result
-  }
-
-  for (const entry of entries) {
-    if (!entry.isDirectory()) continue
-    const dirPath = join(root, entry.name)
-    try {
-      if (now - statSync(dirPath).mtimeMs > maxAgeMs) {
-        removePathIfExists(dirPath, result, 'removedExpiredDirs')
-      }
-    } catch (error) {
-      result.errors.push(`${dirPath}: ${error.message}`)
-    }
-  }
-
-  return result
+function resolvePayloadSessionToken(payload = {}) {
+  if (payload?._helloagentsSessionAlias) return ''
+  return resolveSessionToken({
+    payload,
+    env: {},
+    ppid: 0,
+    allowPpidFallback: false,
+  })
 }
 
-function resolveStableSessionToken({ payload = {}, env = process.env, ppid = process.ppid } = {}) {
-  void ppid
+function resolveEnvSessionToken(env = process.env) {
   return resolveSessionToken({
-    payload,
+    payload: {},
     env,
     ppid: 0,
     allowPpidFallback: false,
@@ -217,29 +193,122 @@ function resolveTransientSessionToken({ payload = {}, env = process.env, ppid =
   })
 }
 
+function getActiveSessionPath(activationDir) {
+  return join(activationDir, PROJECT_SESSIONS_DIR_NAME, ACTIVE_SESSION_FILE_NAME)
+}
+
+function resolveActiveSessionToken({ activationDir, projectRoot, workspace, now = Date.now() } = {}) {
+  const active = readJsonFile(getActiveSessionPath(activationDir), null)
+  if (!active || typeof active !== 'object') return ''
+  if (active.cwd && !samePath(active.cwd, projectRoot)) return ''
+
+  const activeWorkspace = sanitizeRuntimeSegment(active.workspace || active.branch || '', '')
+  if (activeWorkspace && activeWorkspace !== workspace) return ''
+
+  const updatedAt = Date.parse(active.updatedAt || '')
+  if (!Number.isFinite(updatedAt) || now - updatedAt > USER_RUNTIME_MAX_AGE_MS) return ''
+
+  return sanitizeRuntimeSegment(active.session, '')
+}
+
+function resolveActiveAliasSession({ activationDir, projectRoot, workspace, alias, now = Date.now() } = {}) {
+  if (!alias) return ''
+  const active = readJsonFile(getActiveSessionPath(activationDir), null)
+  if (!active || typeof active !== 'object') return ''
+  if (active.cwd && !samePath(active.cwd, projectRoot)) return ''
+
+  const activeWorkspace = sanitizeRuntimeSegment(active.workspace || active.branch || '', '')
+  if (activeWorkspace && activeWorkspace !== workspace) return ''
+
+  const updatedAt = Date.parse(active.updatedAt || '')
+  if (!Number.isFinite(updatedAt) || now - updatedAt > USER_RUNTIME_MAX_AGE_MS) return ''
+
+  const aliases = active.aliases && typeof active.aliases === 'object' ? active.aliases : {}
+  return sanitizeRuntimeSegment(aliases[alias], '')
+}
+
+export function writeActiveProjectSession(scope, { host = '', source = '', env = process.env } = {}) {
+  if (!scope?.active || !scope.activationDir || !scope.session) return ''
+
+  const activePath = getActiveSessionPath(scope.activationDir)
+  const current = readJsonFile(activePath, null) || {}
+  const aliases = current.aliases && typeof current.aliases === 'object' ? current.aliases : {}
+  const envToken = sanitizeRuntimeSegment(resolveEnvSessionToken(env), '')
+  if (envToken && envToken !== scope.session) aliases[envToken] = scope.session
+
+  writeJsonFileAtomic(activePath, {
+    version: 1,
+    cwd: scope.cwd,
+    workspace: scope.workspace || scope.branch,
+    session: scope.session,
+    sessionMode: scope.sessionMode,
+    host,
+    source,
+    aliases,
+    updatedAt: new Date().toISOString(),
+  })
+  return activePath
+}
+
+function chooseProjectSession({ payload, env, activationDir, projectRoot, workspace }) {
+  const payloadToken = sanitizeRuntimeSegment(resolvePayloadSessionToken(payload), '')
+  if (payloadToken) return { session: payloadToken, sessionMode: 'host-session' }
+
+  const payloadAlias = sanitizeRuntimeSegment(payload?._helloagentsSessionAlias, '')
+  const payloadAliasToken = resolveActiveAliasSession({
+    activationDir,
+    projectRoot,
+    workspace,
+    alias: payloadAlias,
+  })
+  if (payloadAliasToken) return { session: payloadAliasToken, sessionMode: 'active-session' }
+
+  const envToken = sanitizeRuntimeSegment(resolveEnvSessionToken(env), '')
+  const aliasToken = resolveActiveAliasSession({
+    activationDir,
+    projectRoot,
+    workspace,
+    alias: envToken,
+  })
+  if (aliasToken) return { session: aliasToken, sessionMode: 'active-session' }
+
+  if (envToken) return { session: envToken, sessionMode: 'host-session' }
+
+  const activeToken = resolveActiveSessionToken({ activationDir, projectRoot, workspace })
+  if (activeToken) return { session: activeToken, sessionMode: 'active-session' }
+
+  return { session: DEFAULT_STATE_SESSION_TOKEN, sessionMode: 'default' }
+}
+
 export function getProjectSessionScope(cwd, options = {}) {
   const normalizedCwd = normalizePath(cwd || process.cwd())
   const projectRoot = getProjectRoot(normalizedCwd)
-  const { payload = {}, env = process.env, ppid = process.ppid } = normalizeRuntimeOptions(options)
-  const stableToken = resolveStableSessionToken({ payload, env, ppid })
-  const branch = sanitizeRuntimeSegment(resolveGitBranchName(projectRoot), 'detached')
-  const session = sanitizeRuntimeSegment(stableToken, DEFAULT_STATE_SESSION_TOKEN)
+  const { payload = {}, env = process.env } = normalizeRuntimeOptions(options)
   const activationDir = getProjectActivationDir(projectRoot)
-  const sessionDir = join(activationDir, PROJECT_SESSIONS_DIR_NAME, branch, session)
+  const workspace = resolveWorkspaceName(projectRoot)
+  const { session, sessionMode } = chooseProjectSession({
+    payload,
+    env,
+    activationDir,
+    projectRoot,
+    workspace,
+  })
+  const sessionDir = join(activationDir, PROJECT_SESSIONS_DIR_NAME, workspace, session)
 
   return {
     cwd: projectRoot,
     active: isProjectRuntimeActive(projectRoot),
-    branch,
+    branch: workspace,
+    workspace,
     session,
-    sessionMode: stableToken ? 'host-session' : 'default',
+    sessionMode,
     activationDir,
     sessionDir,
     statePath: join(sessionDir, 'STATE.md'),
     capsulePath: join(sessionDir, CAPSULE_FILE_NAME),
     eventsPath: join(sessionDir, EVENTS_FILE_NAME),
     artifactsDir: join(sessionDir, PROJECT_ARTIFACTS_DIR_NAME),
-    key: `${normalizedCwd}::${branch}::${session}`,
+    key: `${projectRoot}::${workspace}::${session}`,
   }
 }
 
@@ -259,6 +328,7 @@ function buildTransientRuntimeDir(cwd, options = {}) {
   return {
     cwd: normalizedCwd,
     branch: 'transient',
+    workspace: 'transient',
     session: token,
     sessionMode: token === DEFAULT_STATE_SESSION_TOKEN ? 'default' : 'transient-session',
     sessionDir: join(getUserRuntimeRoot(), hash),

package/scripts/runtime-user-cleanup.mjs

@@ -0,0 +1,63 @@
+import { existsSync, readdirSync, rmSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+
+import { USER_RUNTIME_MAX_AGE_MS } from './runtime-ttl.mjs'
+
+const PROJECT_DIR_NAME = '.helloagents'
+const USER_RUNTIME_DIR_NAME = 'runtime'
+
+function getHomeDir(env = process.env) {
+  return env.HOME || env.USERPROFILE || homedir()
+}
+
+export function getUserRuntimeRoot(home = getHomeDir()) {
+  return join(home, PROJECT_DIR_NAME, USER_RUNTIME_DIR_NAME)
+}
+
+function removePathIfExists(filePath, result, bucket) {
+  if (!existsSync(filePath)) return
+  try {
+    rmSync(filePath, { recursive: true, force: true })
+    result[bucket].push(filePath)
+  } catch (error) {
+    result.errors.push(`${filePath}: ${error.message}`)
+  }
+}
+
+export function cleanupUserRuntimeRoot({
+  home = getHomeDir(),
+  now = Date.now(),
+  maxAgeMs = USER_RUNTIME_MAX_AGE_MS,
+} = {}) {
+  const root = getUserRuntimeRoot(home)
+  const result = {
+    root,
+    removedExpiredDirs: [],
+    errors: [],
+  }
+
+  if (!existsSync(root)) return result
+
+  let entries = []
+  try {
+    entries = readdirSync(root, { withFileTypes: true })
+  } catch (error) {
+    result.errors.push(`${root}: ${error.message}`)
+    return result
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue
+    const dirPath = join(root, entry.name)
+    try {
+      if (now - statSync(dirPath).mtimeMs > maxAgeMs) {
+        removePathIfExists(dirPath, result, 'removedExpiredDirs')
+      }
+    } catch (error) {
+      result.errors.push(`${dirPath}: ${error.message}`)
+    }
+  }
+
+  return result
+}

package/scripts/session-capsule.mjs

@@ -6,6 +6,7 @@ import {
   getRuntimeScope,
   readJsonFile,
   removeRuntimeFile,
+  writeActiveProjectSession,
   writeJsonFileAtomic,
 } from './runtime-scope.mjs'
 
@@ -18,6 +19,7 @@ function buildEmptyCapsule(scope) {
     key: scope.key,
     cwd: scope.cwd,
     branch: scope.branch,
+    workspace: scope.workspace || scope.branch,
     session: scope.session,
     sessionMode: scope.sessionMode,
     updatedAt: new Date().toISOString(),
@@ -36,6 +38,10 @@ function normalizeOptions(options = {}) {
   }
 }
 
+function getEventSessionAlias(eventPayload = {}) {
+  return eventPayload.sessionId || eventPayload.session_id || eventPayload['session-id'] || ''
+}
+
 function getScope(cwd, options = {}) {
   const normalizedOptions = normalizeOptions(options)
   if (normalizedOptions.project === true) {
@@ -66,7 +72,7 @@ export function getSessionArtifactPath(cwd, fileName, options = {}) {
 export function getSessionArtifactRelativePath(cwd, fileName, options = {}) {
   const scope = getScope(cwd, options)
   if (scope.scope === 'project-session') {
-    return `.helloagents/sessions/${scope.branch}/${scope.session}/artifacts/${fileName}`
+    return `.helloagents/sessions/${scope.workspace || scope.branch}/${scope.session}/artifacts/${fileName}`
   }
   return `~/.helloagents/runtime/${basename(scope.sessionDir)}/artifacts/${fileName}`
 }
@@ -82,6 +88,7 @@ export function readSessionCapsule(cwd = process.cwd(), options = {}) {
     key: scope.key,
     cwd: scope.cwd,
     branch: scope.branch,
+    workspace: scope.workspace || scope.branch,
     session: scope.session,
     sessionMode: scope.sessionMode,
   }
@@ -96,11 +103,15 @@ export function writeSessionCapsule(cwd, capsule, options = {}) {
     key: scope.key,
     cwd: scope.cwd,
     branch: scope.branch,
+    workspace: scope.workspace || scope.branch,
     session: scope.session,
     sessionMode: scope.sessionMode,
     updatedAt: new Date().toISOString(),
   }
   writeJsonFileAtomic(scope.capsulePath, nextCapsule)
+  writeActiveProjectSession(scope, {
+    env: normalizeOptions(options).env,
+  })
   return nextCapsule
 }
 
@@ -138,7 +149,18 @@ export function clearCapsuleSection(cwd, section, options = {}) {
 }
 
 export function appendSessionEvent(cwd, eventPayload, options = {}) {
-  const scope = getScope(cwd, options)
+  const normalizedOptions = normalizeOptions(options)
+  const sessionAlias = getEventSessionAlias(eventPayload)
+  const scopedOptions = sessionAlias
+    ? {
+      ...normalizedOptions,
+      payload: {
+        ...(normalizedOptions.payload || {}),
+        _helloagentsSessionAlias: sessionAlias,
+      },
+    }
+    : normalizedOptions
+  const scope = getScope(cwd, scopedOptions)
   if (scope.scope === 'project-session' && !scope.active) return ''
   const eventName = eventPayload?.event || ''
   if (!eventName) return ''
@@ -155,6 +177,11 @@ export function appendSessionEvent(cwd, eventPayload, options = {}) {
     encoding: 'utf-8',
     flag: 'a',
   })
+  writeActiveProjectSession(scope, {
+    host: eventPayload.host || '',
+    source: eventPayload.source || eventName,
+    env: scopedOptions.env,
+  })
   return scope.eventsPath
 }
 

package/scripts/session-token.mjs

@@ -15,8 +15,6 @@ const PAYLOAD_SESSION_KEYS = [
   'tabId',
   'tab_id',
   'tab',
-  'requestId',
-  'request_id',
 ]
 
 const ENV_SESSION_KEYS = [

package/scripts/workflow-core.mjs

@@ -16,7 +16,7 @@ export function getTargetPlans(snapshot) {
 
 function describeStateLabel(state) {
   if (state.stateSessionMode === 'default') {
-    return '当前分支默认位置的状态文件'
+    return '当前工作区默认位置的状态文件'
   }
   return '当前会话的状态文件'
 }

package/scripts/workflow-plan-files.mjs

@@ -187,7 +187,7 @@ export function readStateSnapshot(cwd, options = {}) {
     stateScope: stateScope.stateScope,
     stateSessionToken: stateScope.stateSessionToken,
     stateSessionMode: stateScope.stateSessionMode,
-    stateBranch: stateScope.stateBranch,
+    stateWorkspace: stateScope.stateWorkspace,
     sessionScoped: stateScope.stateScope === 'session',
     exists,
     content,

package/skills/commands/auto/SKILL.md

@@ -7,14 +7,14 @@ policy:
 Trigger: ~auto <任务描述>
 
 `~auto` 是自动执行命令。它根据任务类型、复杂度、风险等级与项目状态，在 `~idea`、`~plan`、`~build`、`~verify`、`~prd` 之间选择合适主路径，并连续推进。
-`~auto` 不止做一次选路；主路径一旦确定，就按需要继续执行后续阶段，默认持续推进直到完成交付，只有命中 bootstrap 的阻塞判定时才停下。
+`~auto` 不止做一次选路；主路径一旦确定，就按需要继续执行后续阶段，默认持续推进直到完成交付，只有命中 HelloAGENTS 阻塞判定时才停下。
 
 ## 铁律
 - 不为了“自动化”而强行走重流程
 - 复杂度与风险不足以支撑更重路径时，优先选更轻但能保证质量的路线
 - `T3` 高风险或不可逆操作默认不直接进入 `~build`；优先先走 `~plan` 或 `~prd`，纯审查/纯验证请求才可先进入 `~verify`
 - 主路径一旦确定，立即读取对应 command skill，并在阶段完成后继续执行后续阶段，避免同一任务重复探索或重复等待
-- 选路不替代授权；涉及外部副作用或高风险不可逆操作时，仍遵守 bootstrap 的阻塞判定与确认规则
+- 选路不替代授权；涉及外部副作用或高风险不可逆操作时，仍遵守 HelloAGENTS 阻塞判定与确认规则
 - 用户显式使用 `~auto`，表示已授权在当前任务边界内沿选定主路径持续执行；若本轮运行在 Codex `/goal` 下，`/goal` 只提供长程续跑与预算，`~auto` 仍按方案包、`state_path` 与验证契约推进；`~plan` / `~prd` 作为中间阶段时，不再额外询问“是否开始执行”，除非仍有真实阻塞；不得把 `🔄 下一步` 当作阶段交接或继续执行占位
 - 优先消费当前上下文中已注入的 ROUTE / TIER、当前工作流约束与项目状态；不要在 `~auto` 内另建一套关键词路由表
 
@@ -69,6 +69,6 @@ Trigger: ~auto <任务描述>
 
 ### 5. 何时允许停下
 
-- 仅在 bootstrap 的阻塞判定成立时停下：真实歧义、缺必需信息/文件/凭据、未授权外部副作用、高风险或不可逆操作
+- 仅在 HelloAGENTS 阻塞判定成立时停下：真实歧义、缺必需信息/文件/凭据、未授权外部副作用、高风险或不可逆操作
 - 不得把 `~plan` / `~prd` 中“是否进入执行”的默认询问原样带入 `~auto` 流程
 - 不得把“给出方案”“给出任务列表”“未执行修改”“等待下一步确认”“给出建议下一步”当作 `~auto` 的默认完成态；用户显式要求 `~auto` 时，默认目标是把当前任务推进到可交付完成

package/skills/commands/build/SKILL.md

@@ -7,7 +7,7 @@ policy:
 Trigger: ~build [description]
 
 `~build` 是执行实现命令。它负责读取现有需求、方案包与项目上下文，完成实现、局部验证、修复循环，并把结果交给后续验证与收尾。
-执行 `~build` 时，通用阶段边界按当前已加载 bootstrap 执行；本 skill 负责补充实现前定位、实现约束，以及进入 `~verify` / 收尾前的实现边界。
+执行 `~build` 时，通用阶段边界按当前已加载的 HelloAGENTS 规则执行；本 skill 负责补充实现前定位、实现约束，以及进入 `~verify` / 收尾前的实现边界。
 `.helloagents/` 在本 skill 中统一按项目级存储路径理解：状态文件只使用 `state_path`；会话证据使用当前 `state_path` 所在目录下的 `artifacts/*.json`；若 `project_store_mode=repo-shared`，知识库、`DESIGN.md`、`verify.yaml` 与方案包按当前上下文中已注入的项目知识/方案目录解析。
 
 ## 铁律
@@ -20,7 +20,7 @@ Trigger: ~build [description]
 
 ### 1. 恢复与定位
 
-- 优先按当前已加载 bootstrap 的“.helloagents/ 文件读取优先级”恢复当前任务；若当前消息明确要继续上次任务、会话刚经历恢复 / 压缩，或本轮运行在 Codex active goal 下，先读取 `state_path`，再用当前用户消息、活跃方案包 / PRD 与代码事实确认当前任务
+- 优先按当前已加载的 HelloAGENTS 规则恢复当前任务，并遵循“.helloagents/ 文件读取优先级”；若当前消息明确要继续上次任务、会话刚经历恢复 / 压缩，或本轮运行在 Codex active goal 下，先读取 `state_path`，再用当前用户消息、活跃方案包 / PRD 与代码事实确认当前任务
 - 若存在最近的活跃方案包，读取对应的：
   - `requirements.md`
   - `plan.md`
@@ -30,12 +30,12 @@ Trigger: ~build [description]
   - `contract.json` 存在时，优先按其中的 `verifyMode`、`reviewerFocus`、`testerFocus` 理解后续验证边界
 - 若本轮运行在 Codex active goal 下，按 `tasks.md` 未完成项、`contract.json` 与 `state_path` 恢复实现位置；不要自动创建新 goal，也不要把 goal 目标原文替代方案包
 - 若当前上下文中已注入“当前工作流约束”或“当前建议下一命令”，先服从它；只有推荐仍为 `~build`，或用户明确提出新增实现范围时，才继续 `~build`
-- 其余项目知识库与相关代码文件，按 bootstrap 的项目上下文规则按需读取
+- 其余项目知识库与相关代码文件，按 HelloAGENTS 项目上下文要求读取
 - 若任务涉及 UI，按以下优先级读取并遵循：当前活跃 `plan.md` / PRD 中的 UI 决策 > 逻辑 `.helloagents/DESIGN.md`（实际路径按当前项目存储模式解析） > `hello-ui` 通用规则
 - 若已激活项目且当前任务属于整页新建、设计系统改造、或跨多个组件的视觉重做，但逻辑 `.helloagents/DESIGN.md` 不存在，先按模板创建最小设计契约，再继续大规模实现
 
 如果 `.helloagents/` 不存在：
-- 按当前已加载 bootstrap 的 `.helloagents/` 与流程状态规则创建最小项目状态
+- 按当前已加载的 HelloAGENTS 规则创建 `.helloagents/` 与最小流程状态
 - 仅补足执行当前任务所需的最小状态，不自动展开完整知识库
 
 ### 2. 需求与范围确认
@@ -65,5 +65,5 @@ Trigger: ~build [description]
 - 有方案包时，只同步本次实现直接影响的任务状态；未完成项保持打开
 - 当前实现已闭合、且需要进入交付或收尾时，转入 `~verify`
 - 若 Codex active goal 仍有未完成 AFK 任务，继续下一项可执行任务；若目标已满足，先转入 `~verify` 与 HelloAGENTS 收尾，再标记 goal complete
-- 状态文件、知识库、`CHANGELOG.md`、modules 文档与归档边界，按当前已加载 bootstrap 的 VERIFY / CONSOLIDATE 规则执行
+- 状态文件、知识库、`CHANGELOG.md`、modules 文档与归档边界，按当前已加载的 HelloAGENTS 规则进入 VERIFY / CONSOLIDATE
 - 不在 `~build` 内把仍未闭合的方案包整体报告为已完成

package/skills/commands/clean/SKILL.md

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

package/skills/commands/commit/SKILL.md

@@ -6,7 +6,7 @@ policy:
 ---
 Trigger: ~commit [message]
 
-执行 `~commit` 时，知识库同步与状态文件更新范围按当前已加载 bootstrap 的 CONSOLIDATE / 流程状态规则执行；本命令只负责生成提交信息、读取提交归属配置并完成提交动作。
+执行 `~commit` 时，知识库同步与状态文件更新范围按当前已加载的 HelloAGENTS CONSOLIDATE / 流程状态要求执行；本命令只负责生成提交信息、读取提交归属配置并完成提交动作。
 
 ## 流程
 
@@ -20,11 +20,11 @@ Trigger: ~commit [message]
    - ""（空，默认）→ 不添加归属
    - 有内容（如 "Co-Authored-By: HelloAGENTS"）→ 添加该内容到 commit message
 6. 执行 git commit
-7. 若 `state_path` 已存在，按 bootstrap 的“已有则更新”规则同步当前已提交状态
+7. 若 `state_path` 已存在，按 HelloAGENTS“已有则更新”要求同步当前已提交状态
 
 ## 知识库同步
 提交后，继续复用上方已解析的同一份设置获取 `kb_create_mode`，不要再次读取 `~/.helloagents/helloagents.json`：
 - 0 = 跳过
 - 1 = 编码任务自动同步（默认）
 - 2 = 始终同步
-同步范围与更新格式按当前已加载 bootstrap 的 CONSOLIDATE 阶段执行。
+同步范围与更新格式按当前已加载的 HelloAGENTS CONSOLIDATE 阶段执行。

package/skills/commands/init/SKILL.md

@@ -7,7 +7,7 @@ policy:
 Trigger: ~init
 
 ~init 是用户显式命令，创建完整知识库，不受 kb_create_mode 限制。
-执行 `~init` 时，`.helloagents/` 目录结构、模板格式和状态文件规则按当前已加载 bootstrap 执行；本命令额外负责项目级规则文件和各宿主项目级 HelloAGENTS 包根链接。
+执行 `~init` 时，`.helloagents/` 目录结构、模板格式和状态文件规则按当前已加载的 HelloAGENTS 规则执行；本命令额外负责项目级规则文件和各宿主项目级 HelloAGENTS 包根链接。
 `.helloagents/` 在本 skill 中统一按项目级存储路径理解：项目本地 `.helloagents/` 继续承担激活目录；状态文件只使用 `state_path`；若 `project_store_mode=repo-shared`，知识库、`DESIGN.md` 与方案包按当前上下文中已注入的项目知识/方案目录写入。
 
 ## 流程
@@ -15,13 +15,13 @@ Trigger: ~init
 ### 阶段 1：环境搭建（必做）
 
 1. 创建 `.helloagents/` 目录 + `state_path`（按 templates/STATE.md 格式，初始“主线目标”写当前初始化任务，初始状态为空闲）
-2. 定位插件根目录：优先读取当前上下文中已注入的“当前 HelloAGENTS 包根目录”；若上下文未提供，再根据当前已加载的规则文件反推，禁止猜测其他目录
+2. 定位插件根目录：优先读取当前上下文中已注入的“当前 HelloAGENTS 包根目录”；若上下文未提供，再根据当前已加载的 HelloAGENTS 规则来源反推，禁止猜测其他目录
 3. 刷新各宿主项目级 HelloAGENTS 包根链接（删除旧的重建）：
    - `.claude/skills/helloagents` symlink → `{插件根目录}/`
    - `.gemini/skills/helloagents` symlink → `{插件根目录}/`
    - `.codex/skills/helloagents` symlink → `{插件根目录}/`
    这些链接用于项目级规则定位 HelloAGENTS 的 `skills/`、`templates/` 和 `scripts/`；宿主若支持递归发现 `SKILL.md`，也可直接识别包内 skills。
-4. 读取 `{插件根目录}/bootstrap.md`，用 `<!-- HELLOAGENTS_START -->` / `<!-- HELLOAGENTS_END -->` 标记包裹后写入：
+4. 读取 `{插件根目录}` 中的全量规则模板，用 `<!-- HELLOAGENTS_START -->` / `<!-- HELLOAGENTS_END -->` 标记包裹后写入：
    - `AGENTS.md`（项目根目录，Codex 读取）
    - `CLAUDE.md`（项目根目录，Claude Code 读取）
    - `.gemini/GEMINI.md`（Gemini CLI 读取，需先创建 .gemini/ 目录）

package/skills/commands/loop/SKILL.md

@@ -22,7 +22,7 @@ Trigger: ~loop <目标描述> [--iterations N] [--metric "命令"] [--direction
 2. 确保 `.helloagents/` 目录和 `state_path` 存在；文件不存在时按 `templates/STATE.md` 创建。`~loop` 必须维护这个状态文件，不受 `kb_create_mode` 控制；“主线目标”固定写本次优化目标，避免混入其他任务
 3. 运行指标命令获取基线值，记录到 results log
 4. 如有守卫命令，运行确认基线通过
-5. 创建当前会话的 `.helloagents/sessions/{branch}/{session}/artifacts/loop-results.tsv`
+5. 创建当前会话的 `.helloagents/sessions/{workspace}/{session}/artifacts/loop-results.tsv`
 6. 根据优化目标标记可能需要的 hello-* 质量技能（如性能优化标记 hello-perf，UI 优化标记 hello-ui）
 7. 重写 `state_path`：记录主线目标=当前优化目标、基线指标、守卫命令、下一步设为第一轮迭代的具体动作
 
@@ -36,7 +36,7 @@ iteration	commit	metric	delta	guard	status	description
 ## 八阶段循环
 
 `~loop` 的八阶段循环是统一执行流程（ROUTE/TIER→SPEC→PLAN→BUILD→VERIFY→CONSOLIDATE）在迭代优化场景下的特化形式。每轮迭代的“修改”阶段遵循已标记的 hello-* 质量技能规范，“验证”阶段遵循 hello-verify 的验证规范。
-执行 `~loop` 时，涉及公共阶段边界、阻塞判定与收尾要求的部分，仍按当前已加载 bootstrap 执行；本 skill 负责补充 loop 场景的迭代顺序与回滚规则。
+执行 `~loop` 时，涉及公共阶段边界、阻塞判定与收尾要求的部分，仍按当前已加载的 HelloAGENTS 规则执行；本 skill 负责补充 loop 场景的迭代顺序与回滚规则。
 若本轮运行在 Codex `/goal` 下，`/goal` 只作为外层长程续跑与预算控制；`~loop` 仍负责指标、守卫、实验提交、keep/revert、results log、`state_path` 与收尾验证，不把 `/goal` 当成循环逻辑本身。
 
 除非达到迭代上限或命中阻塞判定，否则继续执行，不额外询问是否继续，也不把 `🔄 下一步` 当作单轮结果或继续执行占位。