helloagents 3.0.17-beta.1 → 3.0.18-beta.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "helloagents",
-  "version": "3.0.17-beta.1",
+  "version": "3.0.18-beta.1",
   "description": "HelloAGENTS — The orchestration kernel that makes any AI CLI smarter. Adds intelligent routing, quality verification (Ralph Loop), safety guards, and notifications.",
   "author": {
     "name": "HelloWind",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "helloagents",
-  "version": "3.0.17-beta.1",
+  "version": "3.0.18-beta.1",
   "description": "HelloAGENTS — Quality-driven orchestration kernel for AI CLIs with intelligent routing, quality verification (Ralph Loop), safety guards, and notifications.",
   "author": {
     "name": "HelloWind",

package/README.md

@@ -8,7 +8,7 @@
 
 **A workflow layer for AI coding CLIs: skills, project knowledge, delivery checks, safer config writes, and resumable execution.**
 
-[![Version](https://img.shields.io/badge/version-3.0.17-orange.svg)](./package.json)
+[![Version](https://img.shields.io/badge/version-3.0.18-orange.svg)](./package.json)
 [![npm](https://img.shields.io/npm/v/helloagents.svg)](https://www.npmjs.com/package/helloagents)
 [![Node](https://img.shields.io/badge/node-%3E%3D18-339933.svg)](./package.json)
 [![Skills](https://img.shields.io/badge/skills-14-6366f1.svg)](./skills)
@@ -30,7 +30,6 @@
 ## Contents
 
 - [What HelloAGENTS Does](#what-helloagents-does)
-- [What Changed Since v3.0.16](#what-changed-since-v3016)
 - [Core Features](#core-features)
 - [Quick Start](#quick-start)
 - [CLI Management](#cli-management)
@@ -77,16 +76,6 @@ HelloAGENTS adds a workflow layer on top of Claude Code, Gemini CLI, and Codex C
 | Completion is vague | Natural language says “done” | Delivery checks use state, evidence, and verification |
 | Config writes are risky | CLI files can drift | Install, update, cleanup, and doctor flows check managed files |
 
-## What Changed Since v3.0.16
-
-These are the main user-visible changes in `v3.0.17`, compared with `v3.0.16 beta`:
-
-- Managed host configuration now uses `helloagents-js.cmd` as the single stable entrypoint across Windows, macOS, and Linux.
-- Codex `notify` now writes `notify = ["helloagents-js.cmd", "codex-notify"]`, so a synced `config.toml` no longer needs OS-specific command names.
-- Claude Code and Gemini CLI standby hooks now use the same managed entrypoint as Codex, keeping host configuration wording and behavior consistent.
-- The package exposes `helloagents-js.cmd` as an npm bin alias while keeping the runtime command path independent of Node global package locations.
-- Runtime-root refresh now retries transient Windows filesystem rename errors, reducing occasional update/install failures when files are still being released.
-
 ## Core Features
 
 ### 1) 14 task-aware quality skills
@@ -127,7 +116,7 @@ Commands run inside the AI CLI chat with a `~` prefix. The command skill is read
 | `~prd` | Modern product requirements document through guided dimension-by-dimension exploration |
 | `~loop` | Iterative improvement with metric, guard command, keep/revert decisions |
 | `~wiki` | Create or sync only the project knowledge base |
-| `~init` | Full project bootstrap: knowledge base plus project-level rule files and skill links |
+| `~init` | Full project bootstrap: knowledge base plus project-level rule files and package-root links |
 | `~test` | Write tests for a target module or recent change |
 | `~verify` | Review, run verification commands, fix failures, and close out |
 | `~commit` | Generate a conventional commit message and sync knowledge |
@@ -159,7 +148,7 @@ The knowledge base helps future turns understand the repo without re-discovering
 
 `~wiki` creates or updates the knowledge base only.
 
-`~init` does more: it creates or updates the knowledge base, writes project-level rule files, and refreshes host-native project skill links for supported hosts.
+`~init` does more: it creates or updates the knowledge base, writes project-level rule files, and refreshes project-level HelloAGENTS package-root links for supported hosts.
 
 ### 4) Structured plan packages
 
@@ -523,7 +512,7 @@ This only stores short-lived `capsule.json`, `events.jsonl`, and `artifacts/`. I
 | Command or setting | Behavior |
 |--------------------|----------|
 | `~wiki` | creates or syncs the knowledge base only |
-| `~init` | creates knowledge base plus project-level rule files and skill links |
+| `~init` | creates knowledge base plus project-level rule files and package-root links |
 | `kb_create_mode = 0` | disables automatic knowledge updates |
 | `kb_create_mode = 1` | updates knowledge automatically for coding tasks in activated projects or global mode |
 | `kb_create_mode = 2` | updates knowledge more aggressively in activated projects or global mode |
@@ -589,7 +578,7 @@ Config file:
 ~/.helloagents/helloagents.json
 ```
 
-Default shape. `host_install_modes` is added when per-CLI modes are tracked:
+Default shape:
 
 ```json
 {
@@ -684,7 +673,7 @@ Both.
 
 Use `~wiki` when you only want project knowledge.
 
-Use `~init` when you also want project-level rule files and host-native project skill links.
+Use `~init` when you also want project-level rule files and project-level HelloAGENTS package-root links.
 
 ### What is the difference between standby and global?
 

package/README_CN.md

@@ -8,7 +8,7 @@
 
 **面向 AI 编码 CLI 的工作流层：技能、知识库、交付检查、更安全的配置写入，以及可恢复的执行流程。**
 
-[![Version](https://img.shields.io/badge/version-3.0.17-orange.svg)](./package.json)
+[![Version](https://img.shields.io/badge/version-3.0.18-orange.svg)](./package.json)
 [![npm](https://img.shields.io/npm/v/helloagents.svg)](https://www.npmjs.com/package/helloagents)
 [![Node](https://img.shields.io/badge/node-%3E%3D18-339933.svg)](./package.json)
 [![Skills](https://img.shields.io/badge/skills-14-6366f1.svg)](./skills)
@@ -30,7 +30,6 @@
 ## 目录
 
 - [HelloAGENTS 做什么](#helloagents-做什么)
-- [相对 v3.0.16 的真实变化](#相对-v3016-的真实变化)
 - [核心功能](#核心功能)
 - [快速开始](#快速开始)
 - [CLI 管理](#cli-管理)
@@ -77,16 +76,6 @@ HelloAGENTS 叠加在 Claude Code、Gemini CLI 和 Codex CLI 之上，帮助模
 | 完成态模糊 | 自然语言说“完成” | 按状态、证据和验证结果交付 |
 | 配置容易漂移 | CLI 文件可能不一致 | 安装、更新、清理和 doctor 会检查受管文件 |
 
-## 相对 v3.0.16 的真实变化
-
-下面是当前 `v3.0.17` 相对 `v3.0.16 beta` 的主要可见变化：
-
-- 受管宿主配置统一使用 `helloagents-js.cmd` 作为 Windows、macOS 和 Linux 三端稳定入口。
-- Codex `notify` 统一写入 `notify = ["helloagents-js.cmd", "codex-notify"]`，同步同一份 `config.toml` 时不再需要区分系统。
-- Claude Code 与 Gemini CLI 的标准模式 hooks 也使用同一受管入口，与 Codex 的配置行为和文档表述保持一致。
-- npm 包新增 `helloagents-js.cmd` bin alias，同时保持运行命令不依赖 Node 全局包的实际安装路径。
-- 稳定运行根目录刷新增加 Windows 临时文件系统重试，减少文件释放延迟导致的偶发更新/安装失败。
-
 ## 核心功能
 
 ### 1）14 个按任务使用的质量技能
@@ -127,7 +116,7 @@ HelloAGENTS 内置 14 个 `hello-*` 技能。技能只在当前阶段需要时
 | `~prd` | 通过逐维度讨论生成现代产品需求文档 |
 | `~loop` | 设置指标和守卫命令，循环改进、保留或回滚 |
 | `~wiki` | 只创建或同步项目知识库 |
-| `~init` | 完整项目初始化：知识库、项目级规则文件和 skills 链接 |
+| `~init` | 完整项目初始化：知识库、项目级规则文件和包根链接 |
 | `~test` | 为指定模块或最近变更编写测试 |
 | `~verify` | 审查、运行验证命令、修复失败并收尾 |
 | `~commit` | 生成规范化提交信息并同步知识库 |
@@ -159,7 +148,7 @@ HelloAGENTS 可以在 `.helloagents/` 下创建和维护项目知识库。
 
 `~wiki` 只创建或更新知识库。
 
-`~init` 做得更多：创建或更新知识库、写入项目级规则文件，并刷新各宿主项目级原生 skills 链接。
+`~init` 做得更多：创建或更新知识库、写入项目级规则文件，并刷新各宿主项目级 HelloAGENTS 包根链接。
 
 ### 4）结构化方案包
 
@@ -525,7 +514,7 @@ Codex 全局模式由 HelloAGENTS 通过本地插件路径自动安装。
 | 命令或配置 | 行为 |
 |------------|------|
 | `~wiki` | 只创建或同步知识库 |
-| `~init` | 创建知识库，同时写入项目级规则文件和 skills 链接 |
+| `~init` | 创建知识库，同时写入项目级规则文件和包根链接 |
 | `kb_create_mode = 0` | 关闭自动知识更新 |
 | `kb_create_mode = 1` | 已激活项目或全局模式中，编码任务自动更新知识 |
 | `kb_create_mode = 2` | 已激活项目或全局模式中，更积极地更新知识 |
@@ -591,7 +580,7 @@ UI 任务遵循以下优先级：
 ~/.helloagents/helloagents.json
 ```
 
-默认结构。`host_install_modes` 会在需要记录单个 CLI 模式时写入：
+默认结构：
 
 ```json
 {
@@ -686,7 +675,7 @@ npm test
 
 只想创建项目知识库，用 `~wiki`。
 
-还想写入项目级规则文件和宿主原生 skills 链接，用 `~init`。
+还想写入项目级规则文件和宿主项目级 HelloAGENTS 包根链接，用 `~init`。
 
 ### standby 和 global 有什么区别？
 

package/bootstrap-lite.md

@@ -116,7 +116,7 @@
 图标：💡直接响应 | ⚡快速执行 | 🔵规划流程 | ✅完成 | ❓等待输入 | ⚠️警告 | ❌错误
 
 使用约束：
-- 状态图标与收尾内容必须一致。正文仍在等待用户输入、确认、授权或补充信息（含确认是否执行已给出的方案）时，只能使用 `❓等待输入`；仅在本轮执行已完成且不存在待确认动作时，才能使用 `✅完成`。
+- 首行必须保留 `【HelloAGENTS】` 和连字符 `-`，不得省略；状态图标与收尾内容必须一致。正文仍在等待用户输入、确认、授权或补充信息（含确认是否执行已给出的方案）时，只能使用 `❓等待输入`；仅在本轮执行已完成且不存在待确认动作时，才能使用 `✅完成`。
 - `🔄 下一步` 必须写真实下一步，不改写成条件式能力表述或空泛询问。若正在等待确认，写清待确认动作；若存在自然后续动作，直接给出明确引导；若当前任务已完整结束且确无合理后续，可填写“当前任务已完成；无后续动作。”
 
 ### 收尾状态信号

package/bootstrap.md

@@ -116,7 +116,7 @@
 图标：💡直接响应 | ⚡快速执行 | 🔵规划流程 | ✅完成 | ❓等待输入 | ⚠️警告 | ❌错误
 
 使用约束：
-- 状态图标与收尾内容必须一致。正文仍在等待用户输入、确认、授权或补充信息（含确认是否执行已给出的方案）时，只能使用 `❓等待输入`；仅在本轮执行已完成且不存在待确认动作时，才能使用 `✅完成`。
+- 首行必须保留 `【HelloAGENTS】` 和连字符 `-`，不得省略；状态图标与收尾内容必须一致。正文仍在等待用户输入、确认、授权或补充信息（含确认是否执行已给出的方案）时，只能使用 `❓等待输入`；仅在本轮执行已完成且不存在待确认动作时，才能使用 `✅完成`。
 - `🔄 下一步` 必须写真实下一步，不改写成条件式能力表述或空泛询问。若正在等待确认，写清待确认动作；若存在自然后续动作，直接给出明确引导；若当前任务已完整结束且确无合理后续，可填写“当前任务已完成；无后续动作。”
 
 ### 收尾状态信号

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "helloagents",
-  "version": "3.0.17-beta.1",
+  "version": "3.0.18-beta.1",
   "description": "Quality-driven orchestration kernel for AI CLIs",
   "contextFileName": "bootstrap.md",
   "author": "HelloWind",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "helloagents",
-  "version": "3.0.17-beta.1",
+  "version": "3.0.18-beta.1",
   "type": "module",
   "description": "HelloAGENTS — The orchestration kernel that makes any AI CLI smarter. Adds intelligent routing, quality verification (Ralph Loop), safety guards, and notifications.",
   "author": "HelloWind",

package/scripts/cli-config.mjs

@@ -10,6 +10,7 @@ export const DEFAULTS = {
   project_store_mode: 'local',
   commit_attribution: '',
   install_mode: 'standby',
+  host_install_modes: {},
 };
 
 export function loadPackageVersion(pkgRoot) {

package/scripts/notify-events.mjs

@@ -7,3 +7,11 @@ export function shouldIgnoreCodexNotifyClient(client) {
 export function shouldIgnoreFormattedSubagent(lastMsg, outputFormatEnabled) {
   return outputFormatEnabled && !lastMsg.includes('【HelloAGENTS】');
 }
+
+export function resolveNotifyHost(argv = []) {
+  const args = Array.from(argv, (value) => String(value || ''));
+  const command = args[2] || args[0] || '';
+  if (args.includes('--gemini')) return 'gemini';
+  if (args.includes('--codex') || command === 'codex-notify') return 'codex';
+  return 'claude';
+}

package/scripts/notify-route.mjs

@@ -1,6 +1,18 @@
 import { isProjectRuntimeActive } from './runtime-scope.mjs'
 
-export function resolveBootstrapFile(cwd, installMode) {
+export function resolveRuntimeInstallMode(settings = {}, host = '') {
+  if (!settings || typeof settings !== 'object') return 'standby'
+  const hostModes = settings.host_install_modes
+  const trackedMode = hostModes && typeof hostModes === 'object' && !Array.isArray(hostModes)
+    ? hostModes[host] || ''
+    : ''
+  return trackedMode || settings.install_mode || 'standby'
+}
+
+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'
 }
@@ -97,7 +109,7 @@ export function handleRouteCommand({
     return
   }
 
-  const bootstrapFile = resolveBootstrapFile(cwd, settings.install_mode)
+  const bootstrapFile = resolveBootstrapFile(cwd, settings, host)
   if (bootstrapFile === 'bootstrap.md') {
     clearRouteContext({ cwd, payload })
     appendReplayEvent(cwd, {

package/scripts/notify.mjs

@@ -9,7 +9,7 @@ import { homedir } from 'node:os';
 import { playSound as _playSound, desktopNotify as _desktopNotify } from './notify-ui.mjs';
 import { resolveNotificationSource } from './notify-source.mjs';
 import { buildCompactionContext, buildInjectContext, buildRouteInstruction, buildSemanticRouteInstruction, resolveCanonicalCommandSkill } from './notify-context.mjs';
-import { shouldIgnoreCodexNotifyClient } from './notify-events.mjs';
+import { resolveNotifyHost, shouldIgnoreCodexNotifyClient } from './notify-events.mjs';
 import { runGateScript } from './notify-gates.mjs';
 import { handleRouteCommand, resolveBootstrapFile } from './notify-route.mjs';
 import { readSettings, readStdinJson, output, suppressedOutput, emptySuppress } from './notify-shared.mjs';
@@ -24,11 +24,8 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const PKG_ROOT = join(__dirname, '..');
 const CONFIG_FILE = join(homedir(), '.helloagents', 'helloagents.json');
-const HOST = process.argv.includes('--gemini')
-  ? 'gemini'
-  : process.argv.includes('--codex')
-    ? 'codex'
-    : 'claude';
+const cmd = process.argv[2] || '';
+const HOST = resolveNotifyHost(process.argv);
 const IS_GEMINI = HOST === 'gemini';
 const EVENT_NAME = {
   SessionStart: 'SessionStart',
@@ -151,7 +148,7 @@ function cmdPreCompact() {
   const payload = readStdinJson();
   const cwd = payload.cwd || process.cwd();
   const settings = getSettings();
-  const bootstrapFile = resolveBootstrapFile(cwd, settings.install_mode);
+  const bootstrapFile = resolveBootstrapFile(cwd, settings, HOST);
   const context = buildCompactionContext({
     payload,
     pkgRoot: PKG_ROOT,
@@ -197,7 +194,7 @@ function cmdInject() {
   const source = payload.source || 'startup';
   const cwd = payload.cwd || process.cwd();
   const settings = getSettings();
-  const bootstrapFile = resolveBootstrapFile(cwd, settings.install_mode);
+  const bootstrapFile = resolveBootstrapFile(cwd, settings, HOST);
 
   let bootstrap = '';
   try {
@@ -323,8 +320,6 @@ function cmdCodexNotify() {
   clearRouteContext({ cwd, payload: turnPayload });
 }
 
-const cmd = process.argv[2] || '';
-
 switch (cmd) {
   case 'inject':        cmdInject(); break;
   case 'stop':          cmdStop(); break;

package/skills/commands/init/SKILL.md

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

package/skills/commands/wiki/SKILL.md

@@ -9,7 +9,7 @@ Trigger: ~wiki
 `~wiki` 是用户显式命令，仅创建、补全或同步项目知识库。
 
 `~wiki` 是显式知识库命令，不受 `kb_create_mode` 限制。
-执行 `~wiki` 时，`.helloagents/` 目录结构、模板格式和状态文件重写规则按当前已加载 bootstrap 执行；不写入项目级规则文件，也不创建项目级原生 skills 链接。
+执行 `~wiki` 时，`.helloagents/` 目录结构、模板格式和状态文件重写规则按当前已加载 bootstrap 执行；不写入项目级规则文件，也不创建项目级 HelloAGENTS 包根链接。
 `.helloagents/` 在本 skill 中统一按项目级存储路径理解：状态文件只使用 `state_path`；若 `project_store_mode=repo-shared`，`context.md`、`guidelines.md`、`verify.yaml`、`CHANGELOG.md`、`DESIGN.md`、`modules/` 改按当前上下文中已注入的项目知识目录写入。
 
 ## 流程
@@ -23,7 +23,7 @@ Trigger: ~wiki
    ```
 3. 明确不执行以下操作：
    - 不创建或更新项目级规则文件（`AGENTS.md`、`CLAUDE.md`、`.gemini/GEMINI.md`）
-   - 不创建项目级原生 skills 链接
+   - 不创建项目级 HelloAGENTS 包根链接
 
 ### 阶段 2：知识库创建或补全（条件性）
 
@@ -54,4 +54,4 @@ commands:
 - `state_path` 按当前任务状态重写，不追加历史；它只记录当前知识库任务，不承担项目的长期记忆
 - 知识库文件缺失时补全，已存在时按模板增量更新
 - `.gitignore` 只追加缺失行
-- 永不写入项目级规则文件，也不创建任何项目级原生 skills 链接
+- 永不写入项目级规则文件，也不创建任何项目级 HelloAGENTS 包根链接