helloagents 3.0.28 → 3.0.30

package/scripts/cli-lifecycle-hosts.mjs

@@ -1,6 +1,15 @@
 import { spawnSync } from 'node:child_process'
 
-import { installClaudeStandby, installGeminiStandby, uninstallClaudeStandby, uninstallGeminiStandby } from './cli-hosts.mjs'
+import {
+  installClaudeStandby,
+  installDeepseekGlobal,
+  installDeepseekStandby,
+  installGeminiStandby,
+  uninstallClaudeStandby,
+  uninstallDeepseekGlobal,
+  uninstallDeepseekStandby,
+  uninstallGeminiStandby,
+} from './cli-hosts.mjs'
 import {
   cleanupCodexGlobalResidueForStandby,
   installCodexGlobal,
@@ -91,6 +100,10 @@ function installHostStandby(runtime, host) {
     installGeminiStandby(runtime.home, runtime.pkgRoot)
     return {}
   }
+  if (host === 'deepseek') {
+    installDeepseekStandby(runtime.home, runtime.pkgRoot)
+    return {}
+  }
   if (!installCodexStandby(runtime.home, runtime.pkgRoot)) return { skipped: true }
   cleanupCodexGlobalResidueForStandby(runtime.home)
   return {}
@@ -117,6 +130,10 @@ function installHostGlobal(runtime, host) {
       'Gemini CLI extension auto-install failed. Run manually: gemini extensions install https://github.com/hellowind777/helloagents',
     )
   }
+  if (host === 'deepseek') {
+    installDeepseekGlobal(runtime.home, runtime.pkgRoot)
+    return {}
+  }
   uninstallCodexStandby(runtime.home)
   return installCodexGlobal(runtime.home, runtime.pkgRoot) ? {} : { skipped: true }
 }
@@ -124,6 +141,7 @@ function installHostGlobal(runtime, host) {
 function cleanupHostStandby(runtime, host) {
   if (host === 'claude') return { skipped: !uninstallClaudeStandby(runtime.home) }
   if (host === 'gemini') return { skipped: !uninstallGeminiStandby(runtime.home) }
+  if (host === 'deepseek') return { skipped: !uninstallDeepseekStandby(runtime.home) }
   const standbyCleaned = uninstallCodexStandby(runtime.home)
   const globalResidueCleaned = uninstallCodexGlobal(runtime.home)
   return { skipped: !(standbyCleaned || globalResidueCleaned) }
@@ -150,6 +168,7 @@ function cleanupHostGlobal(runtime, host) {
       'Gemini CLI extension auto-remove failed. Run manually: gemini extensions uninstall helloagents',
     )
   }
+  if (host === 'deepseek') return { skipped: !uninstallDeepseekGlobal(runtime.home) }
   return { skipped: !uninstallCodexGlobal(runtime.home) }
 }
 
@@ -175,12 +194,18 @@ function installStandby(runtime) {
     console.log(runtime.msg('  - Codex CLI 未检测到，跳过', '  - Codex CLI not detected, skipped'))
     results.codex = { skipped: true }
   }
+  if (installDeepseekStandby(runtime.home, runtime.pkgRoot)) {
+    runtime.ok(runtime.msg('DeepSeek TUI 已配置（standby 模式）', 'DeepSeek TUI configured (standby mode)'))
+    results.deepseek = {}
+  } else {
+    results.deepseek = { skipped: true }
+  }
   return results
 }
 
 function installGlobal(runtime) {
   const results = {}
-  for (const host of ['claude', 'gemini', 'codex']) {
+  for (const host of ['claude', 'gemini', 'codex', 'deepseek']) {
     const result = installHostGlobal(runtime, host)
     reportHostAction(runtime, 'install', host, 'global', result)
     results[host] = result
@@ -198,6 +223,7 @@ export function uninstallAllHosts(runtime) {
   cleanupHostGlobal(runtime, 'gemini')
   uninstallCodexStandby(runtime.home)
   uninstallCodexGlobal(runtime.home)
+  uninstallDeepseekStandby(runtime.home)
 }
 
 export function runHostLifecycle(runtime, action, host, mode) {

package/scripts/cli-lifecycle.mjs

@@ -10,7 +10,7 @@ import {
 import { installAllHosts, runHostLifecycle, uninstallAllHosts } from './cli-lifecycle-hosts.mjs'
 import { ensureDir, safeJson, safeWrite } from './cli-utils.mjs'
 
-export const HOSTS = ['claude', 'gemini', 'codex']
+export const HOSTS = ['claude', 'gemini', 'codex', 'deepseek']
 
 const runtime = {
   home: '',

package/scripts/cli-messages.mjs

@@ -19,6 +19,18 @@ function codexGlobalStatus({ home, msg }) {
     : msg('安装 Codex CLI 后重新运行 npm install -g helloagents', 'Install Codex CLI then re-run npm install -g helloagents')
 }
 
+function deepseekStandbyStatus({ home, msg }) {
+  return existsSync(join(home, '.deepseek'))
+    ? msg('已自动配置（~/.deepseek/AGENTS.md）', 'Auto-configured (~/.deepseek/AGENTS.md)')
+    : msg('安装 DeepSeek TUI 后重新运行 npm install -g helloagents', 'Install DeepSeek TUI then re-run npm install -g helloagents')
+}
+
+function deepseekGlobalStatus({ home, msg }) {
+  return existsSync(join(home, '.deepseek'))
+    ? msg('已自动切到受管全局载体（~/.deepseek/AGENTS.md）', 'Managed global carrier applied (~/.deepseek/AGENTS.md)')
+    : msg('安装 DeepSeek TUI 后重新运行 npm install -g helloagents', 'Install DeepSeek TUI then re-run npm install -g helloagents')
+}
+
 function pluginCommands() {
   return [
     '    Claude Code:  /plugin marketplace add hellowind777/helloagents',
@@ -49,34 +61,34 @@ function renderInstallMessage(context, mode, state) {
   if (mode === 'global') {
     if (install) {
       return msg(
-        `\n  ✅ HelloAGENTS 已安装（global 模式）！\n\n    Claude Code / Gemini CLI: 已自动尝试宿主原生插件/扩展安装\n    Codex:        ${codexGlobalStatus(context)}（~/.agents/plugins/marketplace.json + ~/plugins/helloagents）\n\n  ${restartHint(msg)}\n\n  若宿主命令不可用，请手动执行：\n${pluginCommands()}\n\n  切换模式：\n    helloagents --standby   标准模式（默认，非插件安装）`,
-        `\n  ✅ HelloAGENTS installed (global mode)!\n\n    Claude Code / Gemini CLI: native plugin/extension install attempted automatically\n    Codex:        ${codexGlobalStatus(context)} (~/.agents/plugins/marketplace.json + ~/plugins/helloagents)\n\n  ${restartHint(msg)}\n\n  If a host command is unavailable, run manually:\n${pluginCommands()}\n\n  Switch modes:\n    helloagents --standby   Standby mode (default, non-plugin install)`,
+        `\n  ✅ HelloAGENTS 已安装（global 模式）！\n\n    Claude Code / Gemini CLI: 已自动尝试宿主原生插件/扩展安装\n    Codex:        ${codexGlobalStatus(context)}（~/.agents/plugins/marketplace.json + ~/plugins/helloagents）\n    DeepSeek TUI: ${deepseekGlobalStatus(context)}\n\n  ${restartHint(msg)}\n\n  若宿主命令不可用，请手动执行：\n${pluginCommands()}\n\n  切换模式：\n    helloagents --standby   标准模式（默认，非插件安装）`,
+        `\n  ✅ HelloAGENTS installed (global mode)!\n\n    Claude Code / Gemini CLI: native plugin/extension install attempted automatically\n    Codex:        ${codexGlobalStatus(context)} (~/.agents/plugins/marketplace.json + ~/plugins/helloagents)\n    DeepSeek TUI: ${deepseekGlobalStatus(context)}\n\n  ${restartHint(msg)}\n\n  If a host command is unavailable, run manually:\n${pluginCommands()}\n\n  Switch modes:\n    helloagents --standby   Standby mode (default, non-plugin install)`,
       )
     }
     return msg(
       refresh
-        ? `  global 模式已刷新。\n  Claude Code / Gemini 已自动尝试刷新宿主插件/扩展；Codex 原生本地插件已重装并同步最新文件。\n  ${restartHint(msg)}`
-        : `  所有项目将自动启用完整 HelloAGENTS 规则。\n  Claude Code / Gemini 已自动尝试安装宿主插件/扩展；Codex 已自动安装原生本地插件。\n  ${restartHint(msg)}\n\n若宿主命令不可用，请手动执行：\n${pluginCommands()}`,
+        ? `  global 模式已刷新。\n  Claude Code / Gemini 已自动尝试刷新宿主插件/扩展；Codex 原生本地插件已重装并同步最新文件；DeepSeek TUI 受管全局载体已同步。\n  ${restartHint(msg)}`
+        : `  所有项目将自动启用完整 HelloAGENTS 规则。\n  Claude Code / Gemini 已自动尝试安装宿主插件/扩展；Codex 已自动安装原生本地插件；DeepSeek TUI 已切到受管全局载体。\n  ${restartHint(msg)}\n\n若宿主命令不可用，请手动执行：\n${pluginCommands()}`,
       refresh
-        ? `  Global mode refreshed.\n  Claude Code / Gemini native plugin/extension refresh was attempted automatically; Codex native local-plugin files were reinstalled and synced.\n  ${restartHint(msg)}`
-        : `  All projects will use full HelloAGENTS rules.\n  Claude Code / Gemini native plugin/extension install was attempted automatically; Codex now uses the native local-plugin path automatically.\n  ${restartHint(msg)}\n\nIf a host command is unavailable, run manually:\n${pluginCommands()}`,
+        ? `  Global mode refreshed.\n  Claude Code / Gemini native plugin/extension refresh was attempted automatically; Codex native local-plugin files were reinstalled and synced; the managed DeepSeek TUI global carrier was refreshed.\n  ${restartHint(msg)}`
+        : `  All projects will use full HelloAGENTS rules.\n  Claude Code / Gemini native plugin/extension install was attempted automatically; Codex now uses the native local-plugin path automatically; DeepSeek TUI now uses the managed global carrier.\n  ${restartHint(msg)}\n\nIf a host command is unavailable, run manually:\n${pluginCommands()}`,
     )
   }
 
   if (install) {
     return msg(
-      `\n  ✅ HelloAGENTS 已安装（standby 模式）！\n\n    Claude Code:  已自动配置（~/.claude/CLAUDE.md + hooks）\n    Gemini CLI:   已自动配置（~/.gemini/GEMINI.md）\n    Codex:        ${codexStandbyStatus(context)}\n\n  ${restartHint(msg)}\n\n  standby 模式下，hello-* 技能不会自动触发。\n  在项目中使用 ~wiki 仅创建/同步知识库，或用 ~init 完整初始化项目；也可用 ~command 按需调用。\n\n  切换模式：\n    helloagents --global    全局模式（自动尝试 Claude/Gemini 插件或扩展；Codex 自动装原生本地插件）`,
-      `\n  ✅ HelloAGENTS installed (standby mode)!\n\n    Claude Code:  Auto-configured (~/.claude/CLAUDE.md + hooks)\n    Gemini CLI:   Auto-configured (~/.gemini/GEMINI.md)\n    Codex:        ${codexStandbyStatus(context)}\n\n  ${restartHint(msg)}\n\n  In standby mode, hello-* skills won't auto-trigger.\n  Use ~wiki to create or sync the KB only, or ~init for the full project setup; ~command stays available on demand.\n\n  Switch modes:\n    helloagents --global    Global mode (auto-attempts Claude/Gemini plugins or extensions; native local plugin auto-install for Codex)`,
+      `\n  ✅ HelloAGENTS 已安装（standby 模式）！\n\n    Claude Code:  已自动配置（~/.claude/CLAUDE.md + hooks）\n    Gemini CLI:   已自动配置（~/.gemini/GEMINI.md）\n    Codex:        ${codexStandbyStatus(context)}\n    DeepSeek TUI: ${deepseekStandbyStatus(context)}\n\n  ${restartHint(msg)}\n\n  standby 模式下，hello-* 技能不会自动触发。\n  在项目中使用 ~wiki 或 ~init 仅创建/同步知识库；用 ~global 初始化项目级全局模式；也可用 ~command 按需调用。\n\n  切换模式：\n    helloagents --global    项目级全局模式（自动尝试 Claude/Gemini 插件或扩展；Codex 自动装原生本地插件；DeepSeek 使用受管 AGENTS 载体）`,
+      `\n  ✅ HelloAGENTS installed (standby mode)!\n\n    Claude Code:  Auto-configured (~/.claude/CLAUDE.md + hooks)\n    Gemini CLI:   Auto-configured (~/.gemini/GEMINI.md)\n    Codex:        ${codexStandbyStatus(context)}\n    DeepSeek TUI: ${deepseekStandbyStatus(context)}\n\n  ${restartHint(msg)}\n\n  In standby mode, hello-* skills won't auto-trigger.\n  Use ~wiki or ~init to create or sync the KB only; use ~global to initialize project-level global mode; ~command stays available on demand.\n\n  Switch modes:\n    helloagents --global    Project-level global mode (auto-attempts Claude/Gemini plugins or extensions; native local plugin auto-install for Codex; DeepSeek uses a managed AGENTS carrier)`,
     )
   }
 
   return msg(
     refresh
       ? `  standby 模式已刷新，CLI 注入与链接已同步最新文件。\n  ${restartHint(msg)}\n  ${removeHint(msg)}`
-      : `  项目可通过 ~wiki 创建/同步知识库，或通过 ~init 完整初始化；未激活项目仅注入通用规则。\n  ${restartHint(msg)}\n  ${removeHint(msg)}`,
+      : `  项目可通过 ~wiki 或 ~init 创建/同步知识库；用 ~global 初始化项目级全局模式；未初始化时仅注入轻量规则。\n  ${restartHint(msg)}\n  ${removeHint(msg)}`,
     refresh
       ? `  Standby mode refreshed; injected files and links were synchronized.\n  ${restartHint(msg)}\n  ${removeHint(msg)}`
-      : `  Projects can use ~wiki for KB-only activation or ~init for the full project setup. Unactivated projects get lite rules only.\n  ${restartHint(msg)}\n  ${removeHint(msg)}`,
+      : `  Projects can use ~wiki or ~init to create/sync the KB; use ~global to initialize project-level global mode. Projects that are not initialized get lite rules only.\n  ${restartHint(msg)}\n  ${removeHint(msg)}`,
   )
 }
 
@@ -84,33 +96,34 @@ function renderHelp({ pkgVersion, msg }) {
   return `
 HelloAGENTS v${pkgVersion} — The orchestration kernel for AI CLIs
 
-${msg('安装', 'Install')}:
+  ${msg('安装', 'Install')}:
   npm install -g helloagents  ${msg('（安装命令并同步稳定运行根目录；CLI 部署需显式执行 helloagents install ...）', '(installs the command and syncs the stable runtime root; deploy to CLIs explicitly with helloagents install ...)')}
   HELLOAGENTS=codex:global npm install -g helloagents
   helloagents-js             ${msg('（受管宿主配置的跨平台稳定入口）', '(cross-platform stable entrypoint for managed host configs)')}
 
 ${msg('模式切换', 'Mode switching')}:
-  helloagents --global     ${msg('全局模式（自动尝试 Claude/Gemini 插件或扩展；Codex 自动装原生本地插件）', 'Global mode (auto-attempts Claude/Gemini plugins or extensions; native local plugin auto-install for Codex)')}
+  helloagents --global     ${msg('项目级全局模式（自动尝试 Claude/Gemini 插件或扩展；Codex 自动装原生本地插件；DeepSeek 使用受管 AGENTS 载体）', 'Project-level global mode (auto-attempts Claude/Gemini plugins or extensions; native local plugin auto-install for Codex; DeepSeek uses a managed AGENTS carrier)')}
   helloagents --standby    ${msg('标准模式（非插件安装，hello-* 不自动触发，默认）', "Standby mode (non-plugin install, hello-* won't auto-trigger, default)")}
 
 ${msg('单 CLI 管理', 'Scoped CLI management')}:
   helloagents install codex --standby
+  helloagents install deepseek --standby
   helloagents install --all --global
   helloagents update codex
   helloagents cleanup claude --global
   helloagents uninstall gemini
-  ${msg('支持: claude | gemini | codex | --all；省略模式时优先沿用该 CLI 已记录/已检测的模式，否则回退 standby', 'Hosts: claude | gemini | codex | --all; omit mode to reuse the tracked/detected mode for that CLI, then fall back to standby')}
+  ${msg('支持: claude | gemini | codex | deepseek | --all；省略模式时优先沿用该 CLI 已记录/已检测的模式，否则回退 standby', 'Hosts: claude | gemini | codex | deepseek | --all; omit mode to reuse the tracked/detected mode for that CLI, then fall back to standby')}
 
 ${msg('分支切换', 'Branch switching')}:
   helloagents switch-branch beta
   helloagents switch-branch beta claude --global
-  helloagents branch github:hellowind777/helloagents#beta --all --standby
+  helloagents branch beta --all --standby
   ${msg('先通过 npm 安装指定 ref，再通过 npm 脚本同步宿主 CLI', 'Installs the requested ref with npm first, then syncs host CLIs through npm scripts')}
 
 ${msg('诊断', 'Diagnostics')}:
   helloagents doctor
   helloagents doctor codex --json
-  ${msg('检查 carrier、链接、hooks、配置注入、Codex 插件安装、受管 model_instructions_file 指向、Codex hook trust 本机状态与版本漂移', 'Checks carriers, links, hooks, config injections, Codex plugin installation, managed model_instructions_file targeting, machine-local Codex hook trust state, and version drift')}
+  ${msg('检查 carrier、链接、hooks、配置注入、Codex 插件安装、DeepSeek 原生 doctor 摘要、受管 model_instructions_file 指向、Codex hook trust 本机状态与版本漂移', 'Checks carriers, links, hooks, config injections, Codex plugin installation, DeepSeek native doctor summaries, managed model_instructions_file targeting, machine-local Codex hook trust state, and version drift')}
 
 ${msg('Codex /goal', 'Codex /goal')}:
   helloagents codex goals status

package/scripts/cli-runtime-carrier.mjs

@@ -1,15 +1,15 @@
 import { join } from 'node:path'
 
-import { safeJson } from './cli-utils.mjs'
+import { safeJson, withCarrierProfile } from './cli-utils.mjs'
 
 export function readCarrierSettings(home) {
   return safeJson(join(home, '.helloagents', 'helloagents.json')) || {}
 }
 
-export function buildRuntimeCarrier(bootstrapContent, settings = {}) {
+export function buildRuntimeCarrier(bootstrapContent, settings = {}, options = {}) {
   void settings
   const normalized = String(bootstrapContent || '').trim()
   if (!normalized) return ''
 
-  return `${normalized}\n`
+  return withCarrierProfile(normalized, options.profile || '')
 }

package/scripts/cli-utils.mjs

@@ -54,8 +54,17 @@ export function removeLink(p) {
 
 const MARKER = '<!-- HELLOAGENTS_START -->';
 const MARKER_END = '<!-- HELLOAGENTS_END -->';
+export const FULL_CARRIER_PROFILE_MARKER = '<!-- HELLOAGENTS_PROFILE: full -->';
 const MARKER_RE = new RegExp(`\\n*${MARKER}[\\s\\S]*?${MARKER_END}\\n*`, 'g');
 
+export function withCarrierProfile(content, profile = '') {
+  const normalized = String(content || '').trim();
+  if (!normalized) return '';
+  if (profile !== 'full') return `${normalized}\n`;
+  if (normalized.includes(FULL_CARRIER_PROFILE_MARKER)) return `${normalized}\n`;
+  return `${FULL_CARRIER_PROFILE_MARKER}\n${normalized}\n`;
+}
+
 /** Inject content wrapped in markers, preserving existing content outside markers. */
 export function injectMarkedContent(filePath, content) {
   const existing = safeRead(filePath) || '';

package/scripts/notify-events.mjs

@@ -11,6 +11,7 @@ export function shouldIgnoreFormattedSubagent(lastMsg, outputFormatEnabled) {
 export function resolveNotifyHost(argv = []) {
   const args = Array.from(argv, (value) => String(value || ''));
   const command = args[2] || args[0] || '';
+  if (args.includes('--deepseek')) return 'deepseek';
   if (args.includes('--gemini')) return 'gemini';
   if (args.includes('--codex') || command === 'codex-notify') return 'codex';
   return 'claude';

package/scripts/notify-route.mjs

@@ -1,4 +1,4 @@
-import { isProjectRuntimeActive } from './runtime-scope.mjs'
+import { hasProjectFullCarrier } from './runtime-scope.mjs'
 
 export function resolveRuntimeInstallMode(settings = {}, host = '') {
   if (!settings || typeof settings !== 'object') return 'standby'
@@ -13,8 +13,7 @@ export function resolveBootstrapFile(cwd, settings = {}, host = '') {
   const installMode = typeof settings === 'string'
     ? settings
     : resolveRuntimeInstallMode(settings, host)
-  const isActivated = isProjectRuntimeActive(cwd)
-  return (installMode === 'global' || isActivated) ? 'bootstrap.md' : 'bootstrap-lite.md'
+  return (installMode === 'global' || hasProjectFullCarrier(cwd, host)) ? 'bootstrap.md' : 'bootstrap-lite.md'
 }
 
 function shouldBypassRoute(prompt) {
@@ -23,7 +22,7 @@ function shouldBypassRoute(prompt) {
 
 function buildHelpExtraRules(skillName) {
   if (skillName !== 'help') return ''
-  return ' 这是 HelloAGENTS 的帮助命令，不是宿主 CLI 的内置帮助。仅显示 HelloAGENTS 的帮助和当前设置；优先使用当前会话上下文中已注入的“当前用户设置”、配置文件原始 JSON 或此前读取结果摘要，上下文不存在或缺少要展示的配置项时才读取一次 ~/.helloagents/helloagents.json；自动激活技能说明仅在全局模式或已激活项目中生效。不要调用宿主 CLI 的帮助工具（如 cli_help 或 /help），不要使用子代理，不要读取项目文件；若受工作区限制无法读取配置，必须明确说明并按已知默认值或已注入设置展示。'
+  return ' 这是 HelloAGENTS 的帮助命令，不是宿主 CLI 的内置帮助。仅显示 HelloAGENTS 的帮助和当前设置；优先使用当前会话上下文中已注入的“当前用户设置”、配置文件原始 JSON 或此前读取结果摘要，上下文不存在或缺少要展示的配置项时才读取一次 ~/.helloagents/helloagents.json；自动激活技能说明仅在全局模式或已初始化项目时生效。不要调用宿主 CLI 的帮助工具（如 cli_help 或 /help），不要使用子代理，不要读取项目文件；若受工作区限制无法读取配置，必须明确说明并按已知默认值或已注入设置展示。'
 }
 
 function routeExplicitCommand({

package/scripts/notify-source.mjs

@@ -6,6 +6,7 @@ const HOST_LABELS = {
   codex: 'Codex',
   claude: 'Claude Code',
   gemini: 'Gemini',
+  deepseek: 'DeepSeek TUI',
 }
 
 function normalizePath(filePath = '') {

package/scripts/notify.mjs

@@ -391,6 +391,7 @@ function cmdInject() {
   const cwd = payload.cwd || process.cwd();
   const settings = getSettings();
   const bootstrapFile = resolveBootstrapFile(cwd, settings, HOST);
+  const shouldEnsureProjectLocal = bootstrapFile === 'bootstrap.md' || source === 'resume' || source === 'compact';
 
   startReplaySession(cwd, {
     host: HOST,
@@ -398,6 +399,7 @@ function cmdInject() {
     bootstrapFile,
     installMode: settings.install_mode || '',
     payload,
+    ensureProjectLocal: shouldEnsureProjectLocal,
   });
   if (!IS_SILENT) {
     appendReplayEvent(cwd, {
@@ -413,7 +415,10 @@ function cmdInject() {
     });
   }
   clearRouteContext({ cwd, payload });
-  clearTurnState(cwd, { payload });
+  clearTurnState(cwd, {
+    payload,
+    ensureProjectLocal: shouldEnsureProjectLocal,
+  });
   cleanupProjectSessions(cwd, {
     minIntervalMs: IS_SILENT ? PROJECT_SESSION_CLEANUP_COOLDOWN_MS : 0,
   });

package/scripts/plan-contract.mjs

@@ -5,7 +5,7 @@ import { resolveProjectPlanDir } from './project-storage.mjs'
 
 export const PLAN_CONTRACT_FILE_NAME = 'contract.json'
 const VALID_VERIFY_MODES = new Set(['test-first', 'review-first'])
-const VALID_ADVISOR_SOURCES = new Set(['claude', 'codex', 'gemini'])
+const VALID_ADVISOR_SOURCES = new Set(['claude', 'codex', 'gemini', 'deepseek'])
 
 function normalizeStringArray(values) {
   if (!Array.isArray(values)) return []

package/scripts/project-storage.mjs

@@ -250,7 +250,7 @@ export function buildProjectStorageHint(cwd, options = {}) {
     hints.push(`当前宿主未提供稳定会话标识，因此使用工作区默认位置 \`${summary.stateSessionToken}\``)
   }
   if (summary.usesSharedStore) {
-    hints.push(`项目存储：\`project_store_mode=repo-shared\`；本地激活/会话运行态目录仍是 \`${summary.promptActivationDir}\`，知识库/方案目录改为 \`${summary.promptStoreDir}\``)
+    hints.push(`项目存储：\`project_store_mode=repo-shared\`；项目本地存储/会话运行态目录仍是 \`${summary.promptActivationDir}\`，知识库/方案目录改为 \`${summary.promptStoreDir}\``)
   }
   return hints.join('。') + (hints.length > 0 ? '。' : '')
 }
@@ -263,7 +263,7 @@ export function buildProjectStorageBlock(cwd, options = {}) {
 
   const details = {
     project_store_mode: summary.projectStoreMode,
-    activation_dir: summary.promptActivationDir,
+    project_local_dir: summary.promptActivationDir,
     state_scope: summary.stateScope,
     state_path: summary.promptStatePath,
     state_workspace: summary.stateWorkspace,
@@ -281,9 +281,9 @@ export function buildProjectStorageBlock(cwd, options = {}) {
     explanations.push('说明：当前宿主未提供稳定会话标识，因此使用工作区默认位置。')
   }
   if (summary.usesSharedStore) {
-    explanations.push('说明：状态文件与会话产物写本地激活目录；`context.md`、`guidelines.md`、`DESIGN.md`、`verify.yaml`、`modules/`、`plans/`、`archive/` 写知识库/方案目录。')
+    explanations.push('说明：状态文件与会话产物写项目本地存储目录；`context.md`、`guidelines.md`、`DESIGN.md`、`verify.yaml`、`modules/`、`plans/`、`archive/` 写知识库/方案目录。')
   } else {
-    explanations.push('说明：当前使用项目本地 `.helloagents/` 作为激活目录、知识库目录和方案目录。')
+    explanations.push('说明：当前使用项目本地 `.helloagents/` 作为知识、方案、状态和运行态目录。')
   }
 
   return [

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' || host === 'deepseek') 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)