helloagents 3.0.29 → 3.0.31

package/scripts/replay-state.mjs

@@ -2,10 +2,11 @@ import { dirname } from 'node:path'
 
 import {
   appendSessionEvent,
+  getRuntimeScope,
   getSessionEventsPath,
   resetSessionEvents,
 } from './session-capsule.mjs'
-import { getProjectSessionScope } from './runtime-scope.mjs'
+import { ensureProjectLocalRuntime, getProjectSessionScope } from './runtime-scope.mjs'
 
 function sanitizeReplayValue(value) {
   if (typeof value === 'string') {
@@ -60,10 +61,27 @@ export function startReplaySession(cwd, {
   bootstrapFile = '',
   installMode = '',
   payload = {},
+  ensureProjectLocal = false,
   env,
   ppid,
 } = {}) {
-  const scope = getProjectSessionScope(cwd, { payload, env, ppid })
+  const scope = ensureProjectLocal
+    ? {
+      ...ensureProjectLocalRuntime(cwd, {
+        payload,
+        env,
+        ppid,
+        stateSeed: {
+          goal: '进入当前项目级执行流程',
+          doing: '正在初始化当前会话运行态',
+          context: '由运行时自动创建；后续按实际任务重写',
+          next: '根据当前用户请求继续执行当前流程',
+        },
+      }),
+      active: true,
+      scope: 'project-session',
+    }
+    : getProjectSessionScope(cwd, { payload, env, ppid })
   if (!scope.active) return ''
 
   const filePath = resetSessionEvents(cwd, { payload, env, ppid })
@@ -95,8 +113,8 @@ export function appendReplayEvent(cwd, {
   env,
   ppid,
 } = {}) {
-  const scope = getProjectSessionScope(cwd, { payload, env, ppid })
-  if (!scope.active || !event) return ''
+  const scope = getRuntimeScope(cwd, { payload, env, ppid })
+  if (scope.scope !== 'project-session' || !scope.active || !event) return ''
 
   return appendSessionEvent(cwd, sanitizeReplayValue({
     event,

package/scripts/runtime-context.mjs

@@ -78,7 +78,8 @@ export function clearRouteContext(options = {}) {
 }
 
 export function writeRouteContext({ cwd, skillName, sourceSkillName = skillName, payload = {}, env, ppid }) {
-  const scope = getRuntimeScope(cwd, { payload, env, ppid })
+  const shouldEnsureProjectLocal = skillName !== 'idea' && skillName !== 'help'
+  const scope = getRuntimeScope(cwd, { payload, env, ppid, ensureProjectLocal: shouldEnsureProjectLocal })
   const context = {
     cwd: normalizePath(cwd),
     skillName,
@@ -91,7 +92,18 @@ export function writeRouteContext({ cwd, skillName, sourceSkillName = skillName,
     key: scope.key,
     updatedAt: Date.now(),
   }
-  writeCapsuleSection(cwd, 'route', context, { payload, env, ppid })
+  writeCapsuleSection(cwd, 'route', context, {
+    payload,
+    env,
+    ppid,
+    ensureProjectLocal: shouldEnsureProjectLocal,
+    stateSeed: {
+      goal: `执行 ~${sourceSkillName}`,
+      doing: `已进入 ~${sourceSkillName} 路由`,
+      context: '由运行时首次进入非只读命令时创建；后续按实际任务重写',
+      next: `读取并执行 ~${skillName} 对应流程`,
+    },
+  })
 }
 
 export function readRouteContext(options = {}) {

package/scripts/runtime-scope.mjs

@@ -7,6 +7,7 @@ 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'
+import { FULL_CARRIER_PROFILE_MARKER } from './cli-utils.mjs'
 
 export const PROJECT_DIR_NAME = '.helloagents'
 export const PROJECT_SESSIONS_DIR_NAME = 'sessions'
@@ -143,6 +144,138 @@ export function getProjectRoot(cwd) {
   return activeDir ? dirname(activeDir) : normalizePath(cwd || process.cwd())
 }
 
+function getCarrierPathForRoot(root, host = '') {
+  if (!root) return ''
+  if (host === 'codex') return join(root, 'AGENTS.md')
+  if (host === 'gemini') return join(root, '.gemini', 'GEMINI.md')
+  return join(root, 'CLAUDE.md')
+}
+
+function getCarrierCandidatePaths(root, host = '', { anyHost = false } = {}) {
+  if (!root) return []
+  if (!anyHost) return [getCarrierPathForRoot(root, host)]
+  return [
+    join(root, 'AGENTS.md'),
+    join(root, 'CLAUDE.md'),
+    join(root, '.gemini', 'GEMINI.md'),
+  ]
+}
+
+function hasFullCarrierMarker(filePath = '') {
+  if (!filePath || !existsSync(filePath)) return false
+  try {
+    return readFileSync(filePath, 'utf-8').includes(FULL_CARRIER_PROFILE_MARKER)
+  } catch {
+    return false
+  }
+}
+
+function findProjectCarrierRoot(cwd, host = '', options = {}) {
+  const normalizedCwd = normalizePath(cwd || process.cwd())
+  const gitRoot = resolveGitTopLevel(normalizedCwd)
+  const requireFullProfile = options.requireFullProfile === true
+  const anyHost = options.anyHost === true
+  let current = normalizedCwd
+
+  while (current) {
+    const candidates = getCarrierCandidatePaths(current, host, { anyHost })
+    const matched = candidates.some((filePath) =>
+      requireFullProfile ? hasFullCarrierMarker(filePath) : existsSync(filePath))
+    if (matched) return current
+    if (isUserHomeDir(current)) break
+    if (gitRoot && samePath(current, gitRoot)) break
+
+    const parent = dirname(current)
+    if (!parent || parent === current) break
+    current = parent
+  }
+
+  return ''
+}
+
+export function getProjectLocalRoot(cwd) {
+  const normalizedCwd = normalizePath(cwd || process.cwd())
+  const activeDir = findProjectActivationDir(normalizedCwd)
+  if (activeDir) return dirname(activeDir)
+
+  const fullCarrierRoot = findProjectCarrierRoot(normalizedCwd, '', {
+    anyHost: true,
+    requireFullProfile: true,
+  })
+  return fullCarrierRoot || resolveGitTopLevel(normalizedCwd) || normalizedCwd
+}
+
+export function getProjectLocalDir(cwd) {
+  return join(getProjectLocalRoot(cwd), PROJECT_DIR_NAME)
+}
+
+export function getProjectCarrierRoot(cwd) {
+  const normalizedCwd = normalizePath(cwd || process.cwd())
+  return findProjectCarrierRoot(normalizedCwd, '', { anyHost: true })
+    || resolveGitTopLevel(normalizedCwd)
+    || getProjectRoot(normalizedCwd)
+}
+
+export function getProjectCarrierPath(cwd, host = '') {
+  const normalizedCwd = normalizePath(cwd || process.cwd())
+  const carrierRoot = findProjectCarrierRoot(normalizedCwd, host, {
+    requireFullProfile: true,
+  }) || findProjectCarrierRoot(normalizedCwd, host)
+    || getProjectCarrierRoot(normalizedCwd)
+  return getCarrierPathForRoot(carrierRoot, host)
+}
+
+export function hasProjectFullCarrier(cwd, host = '') {
+  const carrierPath = getProjectCarrierPath(cwd, host)
+  return hasFullCarrierMarker(carrierPath)
+}
+
+function buildInitialStateSnapshot({
+  goal = '继续当前非只读任务',
+  doing = '已进入当前任务执行流程',
+  context = '由运行时自动创建；后续按实际任务重写',
+  next = '根据当前用户请求继续执行，并按实际任务重写本状态文件',
+} = {}) {
+  return [
+    '# 恢复快照',
+    '',
+    '## 主线目标',
+    goal,
+    '',
+    '## 正在做什么',
+    doing,
+    '',
+    '## 关键上下文',
+    context,
+    '',
+    '## 下一步',
+    next,
+    '',
+    '## 阻塞项',
+    '（无）',
+    '',
+    '## 方案',
+    '',
+    '## 已标记技能',
+    '',
+  ].join('\n')
+}
+
+export function ensureProjectLocalRuntime(cwd, options = {}) {
+  const normalizedCwd = normalizePath(cwd || process.cwd())
+  const localDir = getProjectLocalDir(normalizedCwd)
+  mkdirSync(localDir, { recursive: true })
+
+  const scope = getProjectSessionScope(normalizedCwd, options)
+  mkdirSync(dirname(scope.statePath), { recursive: true })
+
+  if (!existsSync(scope.statePath)) {
+    writeFileSync(scope.statePath, `${buildInitialStateSnapshot(options.stateSeed || {})}\n`, 'utf-8')
+  }
+
+  return scope
+}
+
 function isUserHomeHelloagentsDir(dirPath) {
   const homeCandidates = [
     getHomeDir(),
@@ -368,7 +501,16 @@ function buildTransientRuntimeDir(cwd, options = {}) {
 }
 
 export function getRuntimeScope(cwd = process.cwd(), options = {}) {
-  const projectScope = getProjectSessionScope(cwd, options)
+  const normalizedOptions = normalizeRuntimeOptions(options)
+  if (normalizedOptions.ensureProjectLocal === true) {
+    return {
+      ...ensureProjectLocalRuntime(cwd, normalizedOptions),
+      active: true,
+      scope: 'project-session',
+    }
+  }
+
+  const projectScope = getProjectSessionScope(cwd, normalizedOptions)
   if (projectScope.active) {
     return {
       ...projectScope,
@@ -377,7 +519,7 @@ export function getRuntimeScope(cwd = process.cwd(), options = {}) {
   }
 
   return {
-    ...buildTransientRuntimeDir(cwd, options),
+    ...buildTransientRuntimeDir(cwd, normalizedOptions),
     active: false,
     scope: 'user-runtime',
   }

package/scripts/session-capsule.mjs

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'
 import { basename, dirname, join } from 'node:path'
 
 import {
+  ensureProjectLocalRuntime,
   getProjectSessionScope,
   getRuntimeScope,
   readJsonFile,
@@ -44,6 +45,19 @@ function getEventSessionAlias(eventPayload = {}) {
 
 function getScope(cwd, options = {}) {
   const normalizedOptions = normalizeOptions(options)
+  const stateSeed = normalizedOptions.stateSeed && typeof normalizedOptions.stateSeed === 'object'
+    ? normalizedOptions.stateSeed
+    : {}
+  if (normalizedOptions.ensureProjectLocal === true) {
+    return {
+      ...ensureProjectLocalRuntime(cwd, {
+        ...normalizedOptions,
+        stateSeed,
+      }),
+      active: true,
+      scope: 'project-session',
+    }
+  }
   if (normalizedOptions.project === true) {
     return {
       ...getProjectSessionScope(cwd, normalizedOptions),

package/scripts/turn-state.mjs

@@ -119,6 +119,13 @@ export function writeTurnState(cwd = process.cwd(), input = {}) {
     payload: input.payload && typeof input.payload === 'object' ? input.payload : input,
     env: input.env || process.env,
     ppid: input.ppid ?? process.ppid,
+    ensureProjectLocal: true,
+    stateSeed: {
+      goal: '记录当前非只读任务状态',
+      doing: '正在写入 turn-state',
+      context: '由运行时在需要识别完成、等待或阻塞时自动创建',
+      next: '根据当前 turn-state 继续或等待后续动作',
+    },
   }
   const scope = getRuntimeScope(cwd, runtimeOptions)
   const normalized = normalizeTurnState(input)

package/scripts/turn-stop-gate.mjs

@@ -39,7 +39,7 @@ function buildBlockReason(routeContext, detail, cwd) {
   const commandLabel = `~${routeContext.skillName}`
   const workflowHint = buildWorkflowHint(cwd)
   return [
-    `[HelloAGENTS Runtime] 显式 ${commandLabel} 本轮不应直接停下。`,
+    `[HelloAGENTS Runtime] 显式 ${commandLabel} 当前对话不应直接停下。`,
     detail,
     workflowHint,
     '若无真实阻塞，请继续沿当前路径执行。',
@@ -74,7 +74,7 @@ function validateFormattedCloseoutMessage(routeContext, payload, cwd) {
   if (!firstNonEmptyLine || !/^[💡⚡🔵✅❓⚠️❌]【HelloAGENTS】- /.test(firstNonEmptyLine)) {
     return buildBlockReason(
       routeContext,
-      '最终收尾消息使用了 HelloAGENTS 外层格式，但首个非空行不是规范标题行。',
+      '最终回复使用了 HelloAGENTS 外层格式，但首个非空行不是规范标题行。',
       cwd,
     )
   }
@@ -82,7 +82,7 @@ function validateFormattedCloseoutMessage(routeContext, payload, cwd) {
   if (countMatches(message, /[💡⚡🔵✅❓⚠️❌]【HelloAGENTS】-/g) > 1) {
     return buildBlockReason(
       routeContext,
-      '最终收尾消息重复输出了 HelloAGENTS 标题；请把所有内容合并到同一个外层块内。',
+      '最终回复重复输出了 HelloAGENTS 标题；请把所有内容合并到同一个外层块内。',
       cwd,
     )
   }
@@ -90,7 +90,7 @@ function validateFormattedCloseoutMessage(routeContext, payload, cwd) {
   if (countMatches(message, /^🔄 下一步:/gm) > 1) {
     return buildBlockReason(
       routeContext,
-      '最终收尾消息重复输出了 `🔄 下一步`；请只保留一个真实下一步。',
+      '最终回复重复输出了 `🔄 下一步`；请只保留一个真实下一步。',
       cwd,
     )
   }
@@ -140,7 +140,7 @@ function validateTurnState(routeContext, turnState, cwd, payload = {}) {
       cwd,
     )
   }
-  return buildBlockReason(routeContext, `当前 turn-state 为 \`${turnState.kind}\`，不能作为本轮结束状态。`, cwd)
+  return buildBlockReason(routeContext, `当前 turn-state 为 \`${turnState.kind}\`，不能作为当前对话结束状态。`, cwd)
 }
 
 export function evaluateTurnStopGate(payload = {}) {

package/skills/commands/auto/SKILL.md

@@ -15,7 +15,7 @@ Trigger: ~auto <任务描述>
 - `T3` 高风险或不可逆操作默认不直接进入 `~build`；优先先走 `~plan` 或 `~prd`，纯审查/纯验证请求才可先进入 `~verify`
 - 主路径一旦确定，立即读取对应 command skill，并在阶段完成后继续执行后续阶段，避免同一任务重复探索或重复等待
 - 选路不替代授权；涉及外部副作用或高风险不可逆操作时，仍遵守 HelloAGENTS 阻塞判定与确认规则
-- 用户显式使用 `~auto`，表示已授权在当前任务边界内沿选定主路径持续执行；若本轮运行在 Codex `/goal` 下，`/goal` 只提供长程续跑与预算，`~auto` 仍按方案包、`state_path` 与验证契约推进；`~plan` / `~prd` 作为中间阶段时，不再额外询问“是否开始执行”，除非仍有真实阻塞；不得把 `🔄 下一步` 当作阶段交接或继续执行占位
+- 用户显式使用 `~auto`，表示已授权在当前任务边界内沿选定主路径持续执行；若当前运行在 Codex `/goal` 下，`/goal` 只提供长程续跑与预算，`~auto` 仍按方案包、`state_path` 与验证契约推进；`~plan` / `~prd` 作为中间阶段时，不再额外询问“是否开始执行”，除非仍有真实阻塞；不得把 `🔄 下一步` 当作阶段交接或继续执行占位
 - 优先消费当前上下文中已注入的 ROUTE / TIER、当前工作流约束与项目状态；不要在 `~auto` 内另建一套关键词路由表
 
 ## 流程
@@ -33,7 +33,7 @@ Trigger: ~auto <任务描述>
 ### 1. 选路
 
 - 先按当前上下文里已注入的 ROUTE / TIER 语义约束判断，不依赖关键词命中做机械分流
-- 若本轮没有足够的注入约束，再结合以下信号补足判断：影响范围、风险等级、是否需要结构化产物、是否已有活跃方案包、用户是否只想先比较方向
+- 若当前上下文没有足够的注入约束，再结合以下信号补足判断：影响范围、风险等级、是否需要结构化产物、是否已有活跃方案包、用户是否只想先比较方向
 - 选路优先级：
   - 纯探索 / 点子 / 方向比较 → `~idea`
   - 明确要求验证 / 审查 / 跑检查 → `~verify`

package/skills/commands/build/SKILL.md

@@ -20,19 +20,19 @@ Trigger: ~build [description]
 
 ### 1. 恢复与定位
 
-- 优先按当前已加载的 HelloAGENTS 规则恢复当前任务，并遵循“.helloagents/ 文件读取优先级”；若当前消息明确要继续上次任务、会话刚经历恢复 / 压缩，或本轮运行在 Codex active goal 下，先读取 `state_path`，再用当前用户消息、活跃方案包 / PRD 与代码事实确认当前任务
+- 优先按当前已加载的 HelloAGENTS 规则恢复当前任务，并遵循“.helloagents/ 文件读取优先级”；若当前消息明确要继续上次任务、会话刚经历恢复 / 压缩，或当前运行在 Codex active goal 下，先读取 `state_path`，再用当前用户消息、活跃方案包 / PRD 与代码事实确认当前任务
 - 若存在最近的活跃方案包，读取对应的：
   - `requirements.md`
   - `plan.md`
   - `tasks.md`
   - `contract.json`
-  - 实现时优先把 `tasks.md` 中每个任务的“完成标准”当作本轮实现约束，不要只按任务标题猜测范围
+  - 实现时优先把 `tasks.md` 中每个任务的“完成标准”当作本次实现约束，不要只按任务标题猜测范围
   - `contract.json` 存在时，优先按其中的 `verifyMode`、`reviewerFocus`、`testerFocus` 理解后续验证边界
-- 若本轮运行在 Codex active goal 下，按 `tasks.md` 未完成项、`contract.json` 与 `state_path` 恢复实现位置；不要自动创建新 goal，也不要把 goal 目标原文替代方案包
+- 若当前运行在 Codex active goal 下，按 `tasks.md` 未完成项、`contract.json` 与 `state_path` 恢复实现位置；不要自动创建新 goal，也不要把 goal 目标原文替代方案包
 - 若当前上下文中已注入“当前工作流约束”或“当前推荐下一命令”，先服从它；只有推荐仍为 `~build`，或用户明确提出新增实现范围时，才继续 `~build`
 - 其余项目知识库与相关代码文件，按 HelloAGENTS 项目上下文要求读取
 - 若任务涉及 UI，按以下优先级读取并遵循：当前活跃 `plan.md` / PRD 中的 UI 决策 > 逻辑 `.helloagents/DESIGN.md`（实际路径按当前项目存储模式解析） > 已读取的 `hello-ui` 规则；同时所有 UI 任务都必须满足 UI 质量基线
-- 若已激活项目且当前任务属于整页新建、设计系统改造、或跨多个组件的视觉重做，但逻辑 `.helloagents/DESIGN.md` 不存在，先按模板创建最小设计契约，再继续大规模实现
+- 若当前项目已有本地项目存储，且当前任务属于整页新建、设计系统改造、或跨多个组件的视觉重做，但逻辑 `.helloagents/DESIGN.md` 不存在，先按模板创建最小设计契约，再继续大规模实现
 
 如果 `.helloagents/` 不存在：
 - 按当前已加载的 HelloAGENTS 规则创建 `.helloagents/` 与最小流程状态

package/skills/commands/commit/SKILL.md

@@ -26,6 +26,6 @@ Trigger: ~commit [message]
 ## 知识库同步
 提交后，继续复用上方已解析的同一份设置获取 `kb_create_mode`，不要再次读取 `~/.helloagents/helloagents.json`：
 - 0 = 跳过
-- 1 = 编码任务自动同步（默认）
-- 2 = 始终同步
+- 1 = 知识库已存在时自动同步（默认）
+- 2 = 编码任务在知识库已存在或全局模式下自动创建或同步
 同步范围与更新格式按当前已加载的 HelloAGENTS CONSOLIDATE 阶段执行。

package/skills/commands/global/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: ~global
+description: 初始化项目级全局模式（~global 命令）
+policy:
+  allow_implicit_invocation: false
+---
+Trigger: ~global
+
+`~global` 是用户显式命令，用来初始化项目级全局模式。
+
+`~global` 不受 `kb_create_mode` 限制。
+执行 `~global` 时，`.helloagents/` 目录结构、模板格式和状态文件规则按当前已加载的 HelloAGENTS 规则执行；本命令额外负责项目级规则文件和各宿主项目级 HelloAGENTS 包根链接。
+`.helloagents/` 在本 skill 中统一按项目级存储路径理解：项目本地 `.helloagents/` 继续承担项目本地存储目录；状态文件只使用 `state_path`；若 `project_store_mode=repo-shared`，知识库、`DESIGN.md` 与方案包按当前上下文中已注入的项目知识/方案目录写入。
+
+## 流程
+
+### 阶段 1：环境搭建（必做）
+
+1. 创建 `.helloagents/` 目录 + `state_path`（按 templates/STATE.md 格式，初始“主线目标”写当前初始化任务，初始状态为空闲）
+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. 读取 `{插件根目录}` 中的全量规则模板，在受管内容第一行写入 `<!-- HELLOAGENTS_PROFILE: full -->`，再用 `<!-- HELLOAGENTS_START -->` / `<!-- HELLOAGENTS_END -->` 标记包裹后写入：
+   - `AGENTS.md`（项目根目录，Codex 读取）
+   - `CLAUDE.md`（项目根目录，Claude Code 读取）
+   - `.gemini/GEMINI.md`（Gemini CLI 读取，需先创建 .gemini/ 目录）
+   注意：如果文件已存在且包含标记，替换标记内的内容；如果文件已存在但无标记，追加到末尾；如果文件不存在，创建新文件
+5. 追加 `.gitignore`（如果对应行不存在）：
+   ```
+   .helloagents/
+   .claude/skills/helloagents
+   .gemini/skills/helloagents
+   .codex/skills/helloagents
+   AGENTS.md
+   CLAUDE.md
+   .gemini/GEMINI.md
+   ```
+
+### 阶段 2：知识库创建（条件性）
+
+检查项目是否有实际代码文件（非空项目）：
+- 有代码文件 → 执行完整知识库创建（下方流程）
+- 空项目 → 跳过，告知用户"项目为空，知识库将在后续开发中创建"
+
+知识库创建流程（与原 ~global 一致；逻辑写入 `.helloagents/`，`project_store_mode=repo-shared` 时实际落在共享知识目录）：
+1. 按 templates/ 目录的模板格式，分析项目代码库后生成：
+   - context.md — 按 templates/context.md 格式，填入项目概述、技术栈、架构、目录结构、模块链接
+   - guidelines.md — 按 templates/guidelines.md 格式，从现有代码推断编码约定
+   - verify.yaml — 验证命令（从 package.json/pyproject.toml 检测）
+   - CHANGELOG.md — 按 templates/CHANGELOG.md 格式，初始版本
+   - DESIGN.md — 如果项目包含 UI 代码，按 templates/DESIGN.md 格式提取项目级设计契约（产品表面、设计 token、组件与模式、状态覆盖、无障碍要求、禁止事项等）
+2. 创建 modules/ 目录，按 templates/modules/module.md 格式为主要模块生成文档
+3. 不覆盖已存在的文件
+
+## verify.yaml 格式
+```yaml
+commands:
+  - npm run lint
+  - npm run test
+```
+
+## 幂等性
+重复执行 ~global 是安全的：
+- 已存在的 .helloagents/ 文件不覆盖
+- `state_path` 只记录当前初始化任务；后续进入其他任务时必须按新任务重写
+- 各宿主项目级 HelloAGENTS 包根链接会刷新（删除旧的重建）
+- AGENTS.md/CLAUDE.md/GEMINI.md 中标记内容替换更新
+- .gitignore 只追加缺失行

package/skills/commands/help/SKILL.md

@@ -17,8 +17,9 @@ Trigger: ~help
 | ~build | 执行实现：按需求或方案包完成实现与验证 |
 | ~prd | 完整 PRD：头脑风暴式逐维度挖掘，生成现代产品需求文档 |
 | ~loop | 自主迭代优化：设定目标和指标，循环修改-验证-保留/回滚 |
-| ~wiki | 仅创建/同步项目知识库（`.helloagents/`） |
-| ~init | 完整初始化项目：知识库 + 项目级规则文件配置 |
+| ~wiki | 仅创建/同步项目知识库 |
+| ~init | 同 `~wiki` |
+| ~global | 初始化项目级全局模式 |
 | ~test | 为指定模块或最近变更编写完整测试 |
 | ~verify | 验证总入口：审查 + 运行验证命令 + 修复循环 |
 | ~commit | 规范化提交 + 知识库同步 |
@@ -31,8 +32,8 @@ Trigger: ~help
 - `~review` → 等同 `~verify` 的审查优先模式
 
 ### 自动激活技能
-以下技能仅在全局模式或已激活项目中自动激活（例如执行过 `~wiki`、`~init`，或已处于项目级连续流程）。
-纯标准模式未激活项目不会自动触发这些技能；但涉及 UI 的任务仍受 UI 质量基线约束。
+以下技能仅在全局模式或已初始化项目时自动激活（例如执行过 `~global`，或当前项目级规则文件已包含 `<!-- HELLOAGENTS_PROFILE: full -->`）。
+纯标准模式、且项目未初始化时不会自动触发这些技能；但涉及 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
@@ -44,12 +45,12 @@ Trigger: ~help
 | 配置项 | 默认值 | 作用 | 适用 CLI |
 |--------|-------|------|---------|
 | output_language | "" | 空=跟随用户语言/填写则指定（如 zh-CN、en） | Claude Code + Gemini CLI + Codex CLI |
-| output_format | true | true=主代理最终收尾必须使用 HelloAGENTS 格式，流式/中间输出及子代理输出保持自然；false=自然输出 | Claude Code + Gemini CLI + Codex CLI |
+| output_format | true | true=主代理最终回复必须使用 HelloAGENTS 格式，流式/中间输出及子代理输出保持自然；false=自然输出 | Claude Code + Gemini CLI + Codex CLI |
 | notify_level | 0 | 0=关闭/1=桌面通知/2=声音/3=两者 | Claude Code + Gemini CLI + Codex CLI |
 | ralph_loop_enabled | true | 自动验证循环（显式 ~verify / ~loop 或收尾要求时触发 lint/test/build） | Claude Code + Gemini CLI + Codex CLI |
 | guard_enabled | true | 阻断危险命令与写入后的安全扫描 | Claude Code + Gemini CLI + Codex CLI |
-| kb_create_mode | 1 | 0=关闭/1=已激活项目或全局模式中编码自动/2=已激活项目或全局模式中始终 | Claude Code + Gemini CLI + Codex CLI |
-| project_store_mode | "local" | "local"=知识库/方案包保留在项目本地 `.helloagents/`；"repo-shared"=本地 `.helloagents/` 仅保留激活/STATE/运行态，知识库与方案包改写到 `~/.helloagents/projects/<repo-key>/` | Claude Code + Gemini CLI + Codex CLI |
+| kb_create_mode | 1 | 0=关闭/1=知识库已存在时自动同步/2=编码任务在知识库已存在或全局模式下自动创建或同步 | Claude Code + Gemini CLI + Codex CLI |
+| project_store_mode | "local" | "local"=知识库/方案包保留在项目本地 `.helloagents/`；"repo-shared"=本地 `.helloagents/` 仅保留项目本地状态/运行态，知识库与方案包改写到 `~/.helloagents/projects/<repo-key>/` | Claude Code + Gemini CLI + Codex CLI |
 | auto_commit_enabled | true | true=验证完成且有变更时自动执行本地提交；false=跳过自动提交，仍可手动用 `~commit` | Claude Code + Gemini CLI + Codex CLI |
 | commit_attribution | "" | 空=不添加/填写内容则添加到 commit message | Claude Code + Gemini CLI + Codex CLI |
 | install_mode | "standby" | 当前默认安装模式 | Claude Code + Gemini CLI + Codex CLI |

package/skills/commands/init/SKILL.md

@@ -1,49 +1,33 @@
 ---
 name: ~init
-description: 初始化项目知识库与项目级规则文件（~init 命令）
+description: 初始化或同步项目知识库（与 ~wiki 同义）
 policy:
   allow_implicit_invocation: false
 ---
 Trigger: ~init
 
-~init 是用户显式命令，创建完整知识库，不受 kb_create_mode 限制。
-执行 `~init` 时，`.helloagents/` 目录结构、模板格式和状态文件规则按当前已加载的 HelloAGENTS 规则执行；本命令额外负责项目级规则文件和各宿主项目级 HelloAGENTS 包根链接。
-`.helloagents/` 在本 skill 中统一按项目级存储路径理解：项目本地 `.helloagents/` 继续承担激活目录；状态文件只使用 `state_path`；若 `project_store_mode=repo-shared`，知识库、`DESIGN.md` 与方案包按当前上下文中已注入的项目知识/方案目录写入。
+`~init` 是用户显式命令，仅创建、补全或同步项目知识库。
+`~init` 与 `~wiki` 同义，不受 `kb_create_mode` 限制。
+执行 `~init` 时，`.helloagents/` 目录结构、模板格式和状态文件重写规则按当前已加载的 HelloAGENTS 规则执行；不写入项目级规则文件，也不创建项目级 HelloAGENTS 包根链接。
+`.helloagents/` 在本 skill 中统一按项目级存储路径理解：项目本地 `.helloagents/` 继续承担项目本地存储目录；状态文件只使用 `state_path`；若 `project_store_mode=repo-shared`，知识库、`DESIGN.md` 与方案包按当前上下文中已注入的项目知识/方案目录写入。
 
 ## 流程
 
-### 阶段 1：环境搭建（必做）
+### 阶段 1：基础准备（必做）
 
-1. 创建 `.helloagents/` 目录 + `state_path`（按 templates/STATE.md 格式，初始“主线目标”写当前初始化任务，初始状态为空闲）
-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. 读取 `{插件根目录}` 中的全量规则模板，用 `<!-- HELLOAGENTS_START -->` / `<!-- HELLOAGENTS_END -->` 标记包裹后写入：
-   - `AGENTS.md`（项目根目录，Codex 读取）
-   - `CLAUDE.md`（项目根目录，Claude Code 读取）
-   - `.gemini/GEMINI.md`（Gemini CLI 读取，需先创建 .gemini/ 目录）
-   注意：如果文件已存在且包含标记，替换标记内的内容；如果文件已存在但无标记，追加到末尾；如果文件不存在，创建新文件
-5. 追加 `.gitignore`（如果对应行不存在）：
+1. 创建 `.helloagents/` 目录 + `state_path`（按 templates/STATE.md 格式，初始“主线目标”写当前知识库初始化 / 同步任务，初始状态为空闲）
+2. 追加 `.gitignore`（如果对应行不存在）：
    ```
    .helloagents/
-   .claude/skills/helloagents
-   .gemini/skills/helloagents
-   .codex/skills/helloagents
-   AGENTS.md
-   CLAUDE.md
-   .gemini/GEMINI.md
    ```
 
-### 阶段 2：知识库创建（条件性）
+### 阶段 2：知识库创建或补全（条件性）
 
 检查项目是否有实际代码文件（非空项目）：
 - 有代码文件 → 执行完整知识库创建（下方流程）
 - 空项目 → 跳过，告知用户"项目为空，知识库将在后续开发中创建"
 
-知识库创建流程（与原 ~init 一致；逻辑写入 `.helloagents/`，`project_store_mode=repo-shared` 时实际落在共享知识目录）：
+知识库创建/补全流程（统一写入 `.helloagents/` 对应的项目级存储路径；`project_store_mode=repo-shared` 时实际落在共享知识目录）：
 1. 按 templates/ 目录的模板格式，分析项目代码库后生成：
    - context.md — 按 templates/context.md 格式，填入项目概述、技术栈、架构、目录结构、模块链接
    - guidelines.md — 按 templates/guidelines.md 格式，从现有代码推断编码约定
@@ -62,8 +46,7 @@ commands:
 
 ## 幂等性
 重复执行 ~init 是安全的：
-- 已存在的 .helloagents/ 文件不覆盖
-- `state_path` 只记录当前初始化任务；后续进入其他任务时必须按新任务重写
-- 各宿主项目级 HelloAGENTS 包根链接会刷新（删除旧的重建）
-- AGENTS.md/CLAUDE.md/GEMINI.md 中标记内容替换更新
-- .gitignore 只追加缺失行
+- `.helloagents/` 缺失时创建，已存在时复用
+- `state_path` 按当前任务状态重写，不追加历史；它只记录当前知识库任务，不承担项目的长期记忆
+- 知识库文件缺失时补全，已存在时按模板增量更新
+- `.gitignore` 只追加缺失行

package/skills/commands/loop/SKILL.md

@@ -37,7 +37,7 @@ iteration	commit	metric	delta	guard	status	description
 
 `~loop` 的八阶段循环是统一执行流程（ROUTE/TIER→SPEC→PLAN→BUILD→VERIFY→CONSOLIDATE）在迭代优化场景下的特化形式。每轮迭代的“修改”阶段遵循已标记的 hello-* 质量技能规范，“验证”阶段遵循 hello-verify 的验证规范。
 执行 `~loop` 时，涉及公共阶段边界、阻塞判定与收尾要求的部分，仍按当前已加载的 HelloAGENTS 规则执行；本 skill 负责补充 loop 场景的迭代顺序与回滚规则。
-若本轮运行在 Codex `/goal` 下，`/goal` 只作为外层长程续跑与预算控制；`~loop` 仍负责指标、守卫、实验提交、keep/revert、results log、`state_path` 与收尾验证，不把 `/goal` 当成循环逻辑本身。
+若当前运行在 Codex `/goal` 下，`/goal` 只作为外层长程续跑与预算控制；`~loop` 仍负责指标、守卫、实验提交、keep/revert、results log、`state_path` 与收尾验证，不把 `/goal` 当成循环逻辑本身。
 
 除非达到迭代上限或命中阻塞判定，否则继续执行，不额外询问是否继续，也不把 `🔄 下一步` 当作单轮结果或继续执行占位。
 每轮迭代必须完整走完以下八个阶段：

package/skills/commands/plan/SKILL.md

@@ -102,7 +102,7 @@ Trigger: ~plan [description]
 
 如果用户已明确表示继续执行，则视为授权成立，可直接继续执行。
 如果当前任务来自 `~auto`，且方案包已足够支撑实现、也未命中阻塞判定，则默认直接进入 `~build`，不再追加一次“是否开始执行”的询问。
-如果当前任务是显式 `~plan` 或 `~design`，且尚未获得执行授权，最终收尾按通用输出格式使用等待输入态：正文说明方案包与验证结果，`🔄 下一步` 写清待确认动作。
+如果当前任务是显式 `~plan` 或 `~design`，且尚未获得执行授权，最终回复按通用输出格式使用等待输入态：正文说明方案包与验证结果，`🔄 下一步` 写清待确认动作。
 
 ## 方案包要求
 

package/skills/commands/prd/SKILL.md

@@ -121,7 +121,7 @@ c. AI 总结该维度的决策结果，进入下一个维度
 
 如果用户已对当前 PRD 或继续执行作出明确同意，视为执行授权成立，可直接进入执行，或按需先补一轮 `~plan` 明确实现方案。
 如果当前任务来自 `~auto`，且 PRD 已整理成可执行任务、也未命中阻塞判定，则默认继续进入 `~build`，必要时先补一轮轻量 `~plan`，不再额外询问一次“是否开始执行”。
-如果当前任务是显式 `~prd`，且尚未获得执行授权，最终收尾按通用输出格式使用等待输入态：正文说明 PRD / 任务 / 契约结果，`🔄 下一步` 写清待确认动作。
+如果当前任务是显式 `~prd`，且尚未获得执行授权，最终回复按通用输出格式使用等待输入态：正文说明 PRD / 任务 / 契约结果，`🔄 下一步` 写清待确认动作。
 
 ### 6. 继续执行
 

package/skills/commands/test/SKILL.md

@@ -11,7 +11,7 @@ Trigger: ~test [scope]
 1. 确定测试范围：
    - 无参数：为最近变更的文件编写测试
    - 指定文件/模块：为指定范围编写测试
-   - Codex active goal 下无参数：从 `tasks.md` 未完成项、`contract.json` 与 `state_path` 推导本轮测试范围
+   - Codex active goal 下无参数：从 `tasks.md` 未完成项、`contract.json` 与 `state_path` 推导本次测试范围
 2. 按 hello-* 技能查找路径读取 hello-test SKILL.md，按其 TDD 规范和边界用例要求编写测试
 3. 运行测试确认全部通过
 4. 同步直接相关的任务状态，报告覆盖情况和遗漏；测试通过只作为 goal 交付证据，不直接标记 goal complete