helloagents 3.0.15-beta.1 → 3.0.16-beta.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "helloagents",
-  "version": "3.0.15-beta.1",
+  "version": "3.0.16-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.15-beta.1",
+  "version": "3.0.16-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.15-orange.svg)](./package.json)
+[![Version](https://img.shields.io/badge/version-3.0.16-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,7 @@
 ## Contents
 
 - [What HelloAGENTS Does](#what-helloagents-does)
-- [What Changed Since v3.0.12](#what-changed-since-v3012)
+- [What Changed Since v3.0.15](#what-changed-since-v3015)
 - [Core Features](#core-features)
 - [Quick Start](#quick-start)
 - [CLI Management](#cli-management)
@@ -77,20 +77,17 @@ 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.12
+## What Changed Since v3.0.15
 
-These are the main user-visible changes in `v3.0.15`, compared with `v3.0.12`:
+These are the main user-visible changes in `v3.0.16`, compared with `v3.0.15 beta`:
 
-- Install, update, uninstall, and branch switching now work through npm scripts and one-shot scripts, so host sync no longer depends on a stale `helloagents` executable during package updates.
-- Standby mode now reads from the stable runtime root `~/.helloagents/helloagents`; managed hooks use the `helloagents-js` entrypoint, and skills, templates, and runtime scripts no longer point at Node versioned global package paths.
-- Global mode now attempts Claude Code plugin and Gemini extension installation automatically, while Codex keeps using the managed local-plugin chain with marketplace and cache refresh.
-- Structured turn-state gating is stricter for `~auto` and `~loop`, so incomplete hand-offs must include concrete blocker evidence before the runtime accepts a pause.
-- Runtime state now uses session capsules under `.helloagents/sessions/<branch>/<session>/`, separating turn state, events, and delivery artifacts for concurrent CLI windows and worktrees.
-- Runtime state is written only when a workflow needs it, using the stable `helloagents-turn-state write --kind complete --role main` entrypoint instead of package script paths.
-- Codex standby refresh and cleanup preserve user-owned config content while refreshing managed carriers, local plugin files, marketplace entries, and doctor checks.
-- Output-format settings stay aligned across carriers and runtime injection, reducing cases where the final closeout layout is missed.
-- Debugging, testing, verification, and planning flows now include feedback loops, vertical-slice TDD, domain language, and AFK/HITL task markers while reusing the existing skills and templates.
-- Runtime prompts now use more consistent wording, and the docs explicitly state that AI CLI sessions must be restarted after reinstalling, refreshing, or switching modes.
+- Codex notifications now handle both Codex TUI and `codex exec` completion events, so turn-state gates, delivery checks, and completion notifications stay consistent across Codex entrypoints.
+- Codex on Windows now writes the managed notify command through the command shim, reducing failures caused by direct script paths or shell-specific resolution.
+- Runtime configuration reads now reuse the current session cache when available, reducing repeated `~/.helloagents/helloagents.json` reads while preserving explicit refresh behavior.
+- Persistent carrier files no longer snapshot user settings; runtime injection and final output formatting resolve current settings at execution time.
+- Install tracking is stricter after partial host setup, so `helloagents update --all` can preserve each CLI’s detected or tracked mode more reliably.
+- UI rule boundaries are clearer: the shared UI baseline is the minimum quality line, and `hello-ui` adds concrete design, implementation, and visual validation rules in global mode, activated projects, or explicit UI workflows.
+- One-shot installers now support `HELLOAGENTS_ACTION=cleanup` for host cleanup without uninstalling the package.
 
 ## Core Features
 
@@ -116,7 +113,7 @@ HelloAGENTS includes 14 `hello-*` skills. They are loaded only when the current
 | `hello-reflect` | reusable lessons and knowledge updates |
 
 All UI work first follows the shared UI quality baseline.
-In activated projects or explicit UI workflows, `hello-ui` adds deeper design-contract execution, design-system mapping, and visual validation.
+In global mode, activated projects, or explicit UI workflows, `hello-ui` adds deeper design-contract execution, design-system mapping, and visual validation on top of that baseline.
 When visual evidence is required, HelloAGENTS records it in the current session `artifacts/visual.json`.
 
 ### 2) Commands for different work styles
@@ -386,6 +383,9 @@ HELLOAGENTS=claude:standby HELLOAGENTS_ACTION=update curl -fsSL https://raw.gith
 # Switch branch
 HELLOAGENTS=all:global HELLOAGENTS_ACTION=switch-branch HELLOAGENTS_BRANCH=beta curl -fsSL https://raw.githubusercontent.com/hellowind777/helloagents/main/install.sh | sh
 
+# Cleanup host integration without uninstalling the package
+HELLOAGENTS=codex:standby HELLOAGENTS_ACTION=cleanup curl -fsSL https://raw.githubusercontent.com/hellowind777/helloagents/main/install.sh | sh
+
 # Uninstall
 HELLOAGENTS=gemini HELLOAGENTS_ACTION=uninstall curl -fsSL https://raw.githubusercontent.com/hellowind777/helloagents/main/install.sh | sh
 ```
@@ -402,6 +402,9 @@ $env:HELLOAGENTS="claude:standby"; $env:HELLOAGENTS_ACTION="update"; irm https:/
 # Switch branch
 $env:HELLOAGENTS="all:global"; $env:HELLOAGENTS_ACTION="switch-branch"; $env:HELLOAGENTS_BRANCH="beta"; irm https://raw.githubusercontent.com/hellowind777/helloagents/main/install.ps1 | iex
 
+# Cleanup host integration without uninstalling the package
+$env:HELLOAGENTS="codex:standby"; $env:HELLOAGENTS_ACTION="cleanup"; irm https://raw.githubusercontent.com/hellowind777/helloagents/main/install.ps1 | iex
+
 # Uninstall
 $env:HELLOAGENTS="gemini"; $env:HELLOAGENTS_ACTION="uninstall"; irm https://raw.githubusercontent.com/hellowind777/helloagents/main/install.ps1 | iex
 ```
@@ -561,8 +564,7 @@ UI work follows this priority:
 
 1. current `plan.md` or PRD UI decisions
 2. `.helloagents/DESIGN.md`
-3. shared UI quality baseline
-4. `hello-ui` implementation and validation rules
+3. `hello-ui` implementation and validation rules, together with the shared UI quality baseline
 
 For heavier UI work, `contract.json` can require:
 
@@ -589,7 +591,7 @@ Config file:
 ~/.helloagents/helloagents.json
 ```
 
-Default shape:
+Default shape. `host_install_modes` is added when per-CLI modes are tracked:
 
 ```json
 {
@@ -601,7 +603,8 @@ Default shape:
   "kb_create_mode": 1,
   "project_store_mode": "local",
   "commit_attribution": "",
-  "install_mode": "standby"
+  "install_mode": "standby",
+  "host_install_modes": {}
 }
 ```
 
@@ -616,6 +619,7 @@ Default shape:
 | `project_store_mode` | `"local"` | `local` or `repo-shared` |
 | `commit_attribution` | `""` | optional text appended to commit messages |
 | `install_mode` | `"standby"` | current default install mode |
+| `host_install_modes` | `{}` | managed per-CLI mode map, such as `{ "codex": "standby" }`; used before falling back to `install_mode` |
 
 ## How Each CLI Is Integrated
 
@@ -665,6 +669,10 @@ The current test suite covers:
 
 ## FAQ
 
+### What is the role of `docs/`?
+
+`docs/` is reference material for users and AI agents. It may lag behind implementation; runtime behavior is defined by source code, bootstrap files, skills, templates, and tests.
+
 ### Is this a CLI tool or a prompt framework?
 
 Both.

package/README_CN.md

@@ -8,7 +8,7 @@
 
 **面向 AI 编码 CLI 的工作流层：技能、知识库、交付检查、更安全的配置写入，以及可恢复的执行流程。**
 
-[![Version](https://img.shields.io/badge/version-3.0.15-orange.svg)](./package.json)
+[![Version](https://img.shields.io/badge/version-3.0.16-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,7 @@
 ## 目录
 
 - [HelloAGENTS 做什么](#helloagents-做什么)
-- [相对 v3.0.12 的真实变化](#相对-v3012-的真实变化)
+- [相对 v3.0.15 的真实变化](#相对-v3015-的真实变化)
 - [核心功能](#核心功能)
 - [快速开始](#快速开始)
 - [CLI 管理](#cli-管理)
@@ -77,20 +77,17 @@ HelloAGENTS 叠加在 Claude Code、Gemini CLI 和 Codex CLI 之上，帮助模
 | 完成态模糊 | 自然语言说“完成” | 按状态、证据和验证结果交付 |
 | 配置容易漂移 | CLI 文件可能不一致 | 安装、更新、清理和 doctor 会检查受管文件 |
 
-## 相对 v3.0.12 的真实变化
+## 相对 v3.0.15 的真实变化
 
-下面是当前 `v3.0.15` 相对 `v3.0.12` 的主要可见变化：
+下面是当前 `v3.0.16` 相对 `v3.0.15 beta` 的主要可见变化：
 
-- 安装、更新、卸载和切换分支支持通过 npm scripts 与一键脚本完成，更新过程中不再依赖可能已经失效的旧 `helloagents` 可执行文件。
-- 标准模式统一读取稳定运行根目录 `~/.helloagents/helloagents`，受管 hooks 使用 `helloagents-js` 入口，skills、templates 和运行时脚本不再指向带 Node 版本号的全局包路径。
-- 全局模式会自动尝试安装 Claude Code 插件和 Gemini 扩展；Codex 继续使用受管本地插件链路，并刷新 marketplace 与缓存副本。
-- `~auto` 和 `~loop` 的结构化停顿门控更严格；流程确需暂停时，必须写明具体阻塞证据。
-- 运行态状态收敛到 `.helloagents/sessions/<branch>/<session>/` 下的会话胶囊，分别记录 turn-state、事件和交付证据，兼容多 CLI 窗口与多 worktree。
-- 仅在工作流需要运行时状态时，通过稳定入口 `helloagents-turn-state write --kind complete --role main` 写入，不再解析或拼接包内脚本路径。
-- Codex 标准模式刷新和清理会保留用户自有配置，同时更新受管 carrier、本地插件文件、marketplace 条目和 doctor 检查。
-- 输出格式配置在 carrier 与运行时注入中保持一致，减少收尾格式偶发不生效的问题。
-- 调试、测试、验证和规划流程补充反馈循环、垂直切片 TDD、领域语言和 AFK/HITL 任务标记，仍复用现有 skills 与模板体系。
-- 运行时提示统一为更自然的中文表述，并明确重装、刷新或切换模式后需要重启 AI CLI 或新开会话。
+- Codex 通知现在同时覆盖 Codex TUI 与 `codex exec` 的完成事件，turn-state 门控、交付检查和完成通知在不同入口下保持一致。
+- Windows 下的 Codex 受管通知命令改用命令 shim，减少直接脚本路径或 shell 解析差异导致的失败。
+- 运行时配置读取会优先复用当前会话缓存，减少重复读取 `~/.helloagents/helloagents.json`，同时保留显式刷新行为。
+- 持久 carrier 文件不再快照用户设置；运行时注入和最终输出格式在执行时解析当前配置。
+- 部分宿主安装成功后，安装追踪更严格，`helloagents update --all` 可以更可靠地保留每个 CLI 的检测模式或追踪模式。
+- UI 规则边界更清晰：共享 UI 基线是最低质量线；在全局模式、已激活项目或显式 UI 工作流中，`hello-ui` 补充具体设计、实现和视觉验收规则。
+- 一键安装脚本新增 `HELLOAGENTS_ACTION=cleanup`，可只清理宿主集成而不卸载包。
 
 ## 核心功能
 
@@ -116,7 +113,7 @@ HelloAGENTS 内置 14 个 `hello-*` 技能。技能只在当前阶段需要时
 | `hello-reflect` | 可复用经验和知识更新 |
 
 所有 UI 任务都会先受共享的 UI 质量基线约束。
-在已激活项目或明确的 UI 工作流里，`hello-ui` 会进一步补充设计契约执行、设计系统映射与视觉验收。
+在全局模式、已激活项目或明确的 UI 工作流里，`hello-ui` 会在该基线之上补充设计契约执行、设计系统映射与视觉验收。
 当需要视觉证据时，HelloAGENTS 会写入当前会话的 `artifacts/visual.json`。
 
 ### 2）面向不同工作方式的命令
@@ -386,6 +383,9 @@ HELLOAGENTS=claude:standby HELLOAGENTS_ACTION=update curl -fsSL https://raw.gith
 # 切换分支
 HELLOAGENTS=all:global HELLOAGENTS_ACTION=switch-branch HELLOAGENTS_BRANCH=beta curl -fsSL https://raw.githubusercontent.com/hellowind777/helloagents/main/install.sh | sh
 
+# 只清理宿主集成，不卸载包
+HELLOAGENTS=codex:standby HELLOAGENTS_ACTION=cleanup curl -fsSL https://raw.githubusercontent.com/hellowind777/helloagents/main/install.sh | sh
+
 # 卸载
 HELLOAGENTS=gemini HELLOAGENTS_ACTION=uninstall curl -fsSL https://raw.githubusercontent.com/hellowind777/helloagents/main/install.sh | sh
 ```
@@ -402,6 +402,9 @@ $env:HELLOAGENTS="claude:standby"; $env:HELLOAGENTS_ACTION="update"; irm https:/
 # 切换分支
 $env:HELLOAGENTS="all:global"; $env:HELLOAGENTS_ACTION="switch-branch"; $env:HELLOAGENTS_BRANCH="beta"; irm https://raw.githubusercontent.com/hellowind777/helloagents/main/install.ps1 | iex
 
+# 只清理宿主集成，不卸载包
+$env:HELLOAGENTS="codex:standby"; $env:HELLOAGENTS_ACTION="cleanup"; irm https://raw.githubusercontent.com/hellowind777/helloagents/main/install.ps1 | iex
+
 # 卸载
 $env:HELLOAGENTS="gemini"; $env:HELLOAGENTS_ACTION="uninstall"; irm https://raw.githubusercontent.com/hellowind777/helloagents/main/install.ps1 | iex
 ```
@@ -439,7 +442,7 @@ npm uninstall -g helloagents
 |-----|----------|----------|
 | Claude Code | 原生插件安装 | 由 Claude Code 插件系统管理 |
 | Gemini CLI | 原生扩展安装 | 由 Gemini 扩展系统管理 |
-| Codex CLI | 原生本地插件链路 | `~/.agents/plugins/marketplace.json`、`~/plugins/helloagents/`、`~/.codex/plugins/cache/local-plugins/helloagents/local/`、`~/.codex/config.toml`、`~/.codex/helloagents -> ~/plugins/helloagents` |
+| Codex CLI | 原生本地插件流程 | `~/.agents/plugins/marketplace.json`、`~/plugins/helloagents/`、`~/.codex/plugins/cache/local-plugins/helloagents/local/`、`~/.codex/config.toml`、`~/.codex/helloagents -> ~/plugins/helloagents` |
 
 全局模式下，HelloAGENTS 会自动尝试宿主原生命令。若宿主命令不可用，再手动执行：
 
@@ -563,8 +566,7 @@ UI 任务遵循以下优先级：
 
 1. 当前 `plan.md` 或 PRD 中的 UI 决策
 2. `.helloagents/DESIGN.md`
-3. 共享 UI 质量基线
-4. `hello-ui` 的实现和验收规则
+3. `hello-ui` 的实现和验收规则，与共享 UI 质量基线共同生效
 
 更重的 UI 任务可以通过 `contract.json` 要求：
 
@@ -591,7 +593,7 @@ UI 任务遵循以下优先级：
 ~/.helloagents/helloagents.json
 ```
 
-默认结构：
+默认结构。`host_install_modes` 会在需要记录单个 CLI 模式时写入：
 
 ```json
 {
@@ -603,7 +605,8 @@ UI 任务遵循以下优先级：
   "kb_create_mode": 1,
   "project_store_mode": "local",
   "commit_attribution": "",
-  "install_mode": "standby"
+  "install_mode": "standby",
+  "host_install_modes": {}
 }
 ```
 
@@ -618,6 +621,7 @@ UI 任务遵循以下优先级：
 | `project_store_mode` | `"local"` | `local` 或 `repo-shared` |
 | `commit_attribution` | `""` | 提交信息附加署名 |
 | `install_mode` | `"standby"` | 当前默认安装模式 |
+| `host_install_modes` | `{}` | 受管的单 CLI 模式记录，如 `{ "codex": "standby" }`；优先于 `install_mode` |
 
 ## 各 CLI 集成方式
 
@@ -643,7 +647,7 @@ Codex 默认走规则文件驱动。
 - 标准模式写入受管 `model_instructions_file = "~/.codex/AGENTS.md"`
 - 标准模式写入受管 `notify = ["helloagents-js", "codex-notify"]` 命令用于收尾通知
 - 标准模式创建 `~/.codex/helloagents -> ~/.helloagents/helloagents`
-- 全局模式安装原生本地插件链路
+- 全局模式安装原生本地插件流程
 - HelloAGENTS 默认不启用 Codex hooks
 
 ## 验证
@@ -667,6 +671,10 @@ npm test
 
 ## FAQ
 
+### `docs/` 的作用是什么？
+
+`docs/` 只作为用户和 AI 理解项目的参考材料，可能滞后于实现。运行时行为以源码、bootstrap 文件、skills、templates 和测试为准。
+
 ### 这是 CLI 工具还是提示词框架？
 
 两者都是。

package/bootstrap-lite.md

@@ -4,11 +4,10 @@
 
 ## 配置
 配置文件: ~/.helloagents/helloagents.json
-如果当前上下文中已包含"当前用户设置"且包含本轮所需配置项，视为配置已完成读取，本轮直接复用。
-否则，当本轮首次遇到受配置影响的行为时，再读取一次配置文件并复用本轮结果；不要为了展示、确认或同一结论重复读取。
-输出格式判定属于受配置影响的行为；上下文没有"当前用户设置"时，最终收尾前必须读取一次该配置。
-同一轮内对同一配置文件、模块、SKILL、模板只读取一次，后续直接复用已得结论，不要重复探测或重复读取同一路径。
-在受限 CLI（如工作区限制导致家目录不可读）中，确需读取但失败时必须明确说明，并按默认值或当前已知设置执行；禁止静默回退或假装读取成功。
+`output_language` 非空时，所有用户可见文本使用该语言；为空则跟随用户当前语言。
+会话级缓存优先：当前上下文已有"当前用户设置"、原始 JSON 或读取摘要，且覆盖所需配置项时，直接复用。
+仅在缺少所需项、用户要求刷新，或本轮修改后需要核验时读取；输出格式只在缺少 `output_format` 已知值时触发读取。
+同一会话内，同一路径的配置文件、模块、SKILL、模板只读一次并跨轮复用；读取失败必须明示，并按默认值或已知设置执行。
 
 ## 编码原则
 - 代码是唯一判断依据，文档与代码不一致时以代码为准
@@ -55,8 +54,8 @@
 - 项目已有技术栈、设计系统或方案包时必须遵循既有决策
 
 ### UI 质量基线（涉及视觉/交互任务时，全阶段生效）
-任务涉及界面视觉、交互体验、页面结构、组件外观、信息呈现或设计需求时，统一遵循以下基线；适用于标准模式、标准模式+已激活项目与全局模式。
-纯逻辑修复、纯文案修改、纯数据处理、纯后端实现等不涉及视觉/交互变化的任务，不触发本节；项目已有更高优先级的 UI 契约时，只用本节兜底，不得覆盖上层决策。
+任务涉及界面视觉、交互体验、页面结构、组件外观、信息呈现或设计需求时，统一遵循以下基线；适用于标准模式未激活项目、标准模式已激活项目与全局模式。
+纯逻辑修复、纯文案修改、纯数据处理、纯后端实现等不涉及视觉/交互变化的任务，不触发本节。本基线是最低质量线；已有 `plan.md` / PRD、`DESIGN.md` 或 `hello-ui` 约束时，与其共同生效，不覆盖上层决策。
 
 - 先判断本次视觉变更是延续既有风格、演进式优化还是探索性方案，再形成简短但明确的内部设计简报：界面目的、目标用户与场景、主要视口、情绪方向、记忆点；不得直接滑入泛化风格标签或模型默认审美
 - 已有项目优先复用现有组件、token、品牌资产、内容语气与交互模式；先建立最小设计系统：至少明确背景/表面/正文/弱化/强调/语义色，以及 display/headline/body/caption 等排版角色；缺少关键设计上下文时明确说明，不凭空发明视觉语言
@@ -207,7 +206,7 @@
 路径: {CWD}/.helloagents/
 所有文件的创建和更新必须按 templates/ 目录中对应模板的格式执行，不可自由发挥格式。
 说明：
-- `.helloagents/` 表示项目级存储路径，也是 standby 模式的激活信号
+- `.helloagents/` 表示项目级存储路径，也是标准模式的项目激活信号
 - `state_path` 指向的状态文件、当前会话 `capsule.json`、`events.jsonl`、`artifacts/*.json`、`artifacts/loop-results.tsv` 等运行态文件始终保留在项目本地 `.helloagents/sessions/{branch}/{session}/`
 - `state_path` 是状态文件的唯一位置。宿主提供会话标识时，写入 `.helloagents/sessions/{branch}/{session}/STATE.md`；没有稳定会话标识时，写入 `.helloagents/sessions/{branch}/default/STATE.md`
 - 若 helloagents.json 中 `project_store_mode = "repo-shared"`，`context.md`、`guidelines.md`、`CHANGELOG.md`、`verify.yaml`、`DESIGN.md`、`modules/`、`plans/`、`archive/` 改按当前上下文中已注入的“当前项目存储”/“项目知识/方案目录”解析；未注入具体路径时，按当前存储模式自行解析，不要假定这些文件一定实际位于当前工作树中

package/bootstrap.md

@@ -4,11 +4,10 @@
 
 ## 配置
 配置文件: ~/.helloagents/helloagents.json
-如果当前上下文中已包含"当前用户设置"且包含本轮所需配置项，视为配置已完成读取，本轮直接复用。
-否则，当本轮首次遇到受配置影响的行为时，再读取一次配置文件并复用本轮结果；不要为了展示、确认或同一结论重复读取。
-输出格式判定属于受配置影响的行为；上下文没有"当前用户设置"时，最终收尾前必须读取一次该配置。
-同一轮内对同一配置文件、模块、SKILL、模板只读取一次，后续直接复用已得结论，不要重复探测或重复读取同一路径。
-在受限 CLI（如工作区限制导致家目录不可读）中，确需读取但失败时必须明确说明，并按默认值或当前已知设置执行；禁止静默回退或假装读取成功。
+`output_language` 非空时，所有用户可见文本使用该语言；为空则跟随用户当前语言。
+会话级缓存优先：当前上下文已有"当前用户设置"、原始 JSON 或读取摘要，且覆盖所需配置项时，直接复用。
+仅在缺少所需项、用户要求刷新，或本轮修改后需要核验时读取；输出格式只在缺少 `output_format` 已知值时触发读取。
+同一会话内，同一路径的配置文件、模块、SKILL、模板只读一次并跨轮复用；读取失败必须明示，并按默认值或已知设置执行。
 
 ## 编码原则
 - 代码是唯一判断依据，文档与代码不一致时以代码为准
@@ -55,8 +54,8 @@
 - 项目已有技术栈、设计系统或方案包时必须遵循既有决策
 
 ### UI 质量基线（涉及视觉/交互任务时，全阶段生效）
-任务涉及界面视觉、交互体验、页面结构、组件外观、信息呈现或设计需求时，统一遵循以下基线；适用于标准模式、标准模式+已激活项目与全局模式。
-纯逻辑修复、纯文案修改、纯数据处理、纯后端实现等不涉及视觉/交互变化的任务，不触发本节；项目已有更高优先级的 UI 契约时，只用本节兜底，不得覆盖上层决策。
+任务涉及界面视觉、交互体验、页面结构、组件外观、信息呈现或设计需求时，统一遵循以下基线；适用于标准模式未激活项目、标准模式已激活项目与全局模式。
+纯逻辑修复、纯文案修改、纯数据处理、纯后端实现等不涉及视觉/交互变化的任务，不触发本节。本基线是最低质量线；已有 `plan.md` / PRD、`DESIGN.md` 或 `hello-ui` 约束时，与其共同生效，不覆盖上层决策。
 
 - 先判断本次视觉变更是延续既有风格、演进式优化还是探索性方案，再形成简短但明确的内部设计简报：界面目的、目标用户与场景、主要视口、情绪方向、记忆点；不得直接滑入泛化风格标签或模型默认审美
 - 已有项目优先复用现有组件、token、品牌资产、内容语气与交互模式；先建立最小设计系统：至少明确背景/表面/正文/弱化/强调/语义色，以及 display/headline/body/caption 等排版角色；缺少关键设计上下文时明确说明，不凭空发明视觉语言
@@ -276,7 +275,7 @@ hello-* 技能读取路径：`{HELLOAGENTS_READ_ROOT}/skills/{技能名}/SKILL.m
 路径: {CWD}/.helloagents/
 所有文件的创建和更新必须按 templates/ 目录中对应模板的格式执行，不可自由发挥格式。
 说明：
-- `.helloagents/` 表示项目级存储路径，也是 standby 模式的激活信号
+- `.helloagents/` 表示项目级存储路径，也是标准模式的项目激活信号
 - `state_path` 指向的状态文件、当前会话 `capsule.json`、`events.jsonl`、`artifacts/*.json`、`artifacts/loop-results.tsv` 等运行态文件始终保留在项目本地 `.helloagents/sessions/{branch}/{session}/`
 - `state_path` 是状态文件的唯一位置。宿主提供会话标识时，写入 `.helloagents/sessions/{branch}/{session}/STATE.md`；没有稳定会话标识时，写入 `.helloagents/sessions/{branch}/default/STATE.md`
 - 若 helloagents.json 中 `project_store_mode = "repo-shared"`，`context.md`、`guidelines.md`、`CHANGELOG.md`、`verify.yaml`、`DESIGN.md`、`modules/`、`plans/`、`archive/` 改按当前上下文中已注入的“当前项目存储”/“项目知识/方案目录”解析；未注入具体路径时，按当前存储模式自行解析，不要假定这些文件一定实际位于当前工作树中

package/gemini-extension.json

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

package/install.ps1

@@ -2,7 +2,7 @@
 #
 # Environment:
 #   HELLOAGENTS=all|claude|gemini|codex[:standby|global]
-#   HELLOAGENTS_ACTION=install|update|uninstall|switch-branch|branch
+#   HELLOAGENTS_ACTION=install|update|cleanup|uninstall|switch-branch|branch
 #   HELLOAGENTS_TARGET=all|claude|gemini|codex
 #   HELLOAGENTS_MODE=standby|global
 #   HELLOAGENTS_BRANCH=main|beta|...
@@ -97,6 +97,9 @@ switch ($Action) {
         }
         Sync-Hosts
     }
+    "cleanup" {
+        Cleanup-Hosts
+    }
     "switch-branch" {
         if (-not $Branch -and -not $env:HELLOAGENTS_PACKAGE) {
             throw "HELLOAGENTS_BRANCH or HELLOAGENTS_PACKAGE is required for switch-branch"

package/install.sh

@@ -5,7 +5,7 @@ set -eu
 #
 # Environment:
 #   HELLOAGENTS=all|claude|gemini|codex[:standby|global]
-#   HELLOAGENTS_ACTION=install|update|uninstall|switch-branch|branch
+#   HELLOAGENTS_ACTION=install|update|cleanup|uninstall|switch-branch|branch
 #   HELLOAGENTS_TARGET=all|claude|gemini|codex
 #   HELLOAGENTS_MODE=standby|global
 #   HELLOAGENTS_BRANCH=main|beta|...
@@ -97,6 +97,9 @@ case "$ACTION" in
     fi
     sync_hosts
     ;;
+  cleanup)
+    cleanup_hosts
+    ;;
   switch-branch|branch)
     if [ -z "$BRANCH" ] && [ -z "${HELLOAGENTS_PACKAGE:-}" ]; then
       echo "HELLOAGENTS_BRANCH or HELLOAGENTS_PACKAGE is required for switch-branch" >&2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "helloagents",
-  "version": "3.0.15-beta.1",
+  "version": "3.0.16-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/capability-registry.mjs

@@ -39,7 +39,7 @@ export function selectCapabilities({ cwd, skillName = '', options = {} }) {
   if (plan?.contract?.ui?.required || existsSync(getProjectDesignContractPath(cwd))) {
     capabilities.push({
       id: 'design-contract',
-      description: `UI 契约：仅在 UI 场景按需读取当前 plan.md / prd/03-ui-design.md、${describeProjectStoreFile(cwd, 'DESIGN.md')} 与 hello-ui，不全局常驻。`,
+      description: `UI 契约：仅在 UI 场景按需读取当前 plan.md / prd/03-ui-design.md、${describeProjectStoreFile(cwd, 'DESIGN.md')} 与 hello-ui，并与 UI 质量基线共同生效。`,
     })
   }
   if (visualRequirement.required) {

package/scripts/cli-codex-config.mjs

@@ -7,7 +7,10 @@ import {
 export const CODEX_PLUGIN_CONFIG_HEADER = '[plugins."helloagents@local-plugins"]'
 export const CODEX_MANAGED_TOML_COMMENT = '# helloagents-managed'
 export const CODEX_MANAGED_MODEL_INSTRUCTIONS_PATH = '~/.codex/AGENTS.md'
-export const CODEX_MANAGED_NOTIFY_VALUE = '["helloagents-js", "codex-notify"]'
+export const CODEX_MANAGED_NOTIFY_COMMAND = process.platform === 'win32'
+  ? 'helloagents-js.cmd'
+  : 'helloagents-js'
+export const CODEX_MANAGED_NOTIFY_VALUE = `["${CODEX_MANAGED_NOTIFY_COMMAND}", "codex-notify"]`
 
 function normalizePath(value = '') {
   return String(value || '').replace(/\\/g, '/')

package/scripts/cli-lifecycle-hosts.mjs

@@ -33,8 +33,9 @@ function runHostCommand(command, args) {
 }
 
 function buildNativeResult(result, successCN, successEN, manualCN, manualEN) {
-  if (result.ok) return { noteCN: successCN, noteEN: successEN }
+  if (result.ok) return { ok: true, noteCN: successCN, noteEN: successEN }
   return {
+    ok: false,
     noteCN: `${manualCN}${result.output ? `；原因：${result.output}` : ''}`,
     noteEN: `${manualEN}${result.output ? `; reason: ${result.output}` : ''}`,
   }
@@ -64,6 +65,8 @@ function reportHostAction(runtime, action, host, mode, result = {}) {
   const isCleanup = action === 'cleanup' || action === 'uninstall'
   if (result.skipped) {
     console.log(runtime.msg(`  - ${label} 未检测到，跳过`, `  - ${label} not detected, skipped`))
+  } else if (result.ok === false && !isCleanup) {
+    console.log(runtime.msg(`  - ${label} 自动配置未完成`, `  - ${label} automatic setup did not complete`))
   } else if (isCleanup) {
     runtime.ok(runtime.msg(`${label} 已清理（${mode} 模式）`, `${label} cleaned (${mode} mode)`))
   } else if (mode === 'standby') {
@@ -151,24 +154,43 @@ function cleanupHostGlobal(runtime, host) {
 }
 
 function installStandby(runtime) {
-  if (installClaudeStandby(runtime.home, runtime.pkgRoot)) runtime.ok(runtime.msg('Claude Code 已配置（standby 模式）', 'Claude Code configured (standby mode)'))
-  if (installGeminiStandby(runtime.home, runtime.pkgRoot)) runtime.ok(runtime.msg('Gemini CLI 已配置（standby 模式）', 'Gemini CLI configured (standby mode)'))
+  const results = {}
+  if (installClaudeStandby(runtime.home, runtime.pkgRoot)) {
+    runtime.ok(runtime.msg('Claude Code 已配置（standby 模式）', 'Claude Code configured (standby mode)'))
+    results.claude = {}
+  } else {
+    results.claude = { skipped: true }
+  }
+  if (installGeminiStandby(runtime.home, runtime.pkgRoot)) {
+    runtime.ok(runtime.msg('Gemini CLI 已配置（standby 模式）', 'Gemini CLI configured (standby mode)'))
+    results.gemini = {}
+  } else {
+    results.gemini = { skipped: true }
+  }
   if (installCodexStandby(runtime.home, runtime.pkgRoot)) {
     cleanupCodexGlobalResidueForStandby(runtime.home)
     runtime.ok(runtime.msg('Codex CLI 已配置（standby 模式）', 'Codex CLI configured (standby mode)'))
+    results.codex = {}
+  } else {
+    console.log(runtime.msg('  - Codex CLI 未检测到，跳过', '  - Codex CLI not detected, skipped'))
+    results.codex = { skipped: true }
   }
-  else console.log(runtime.msg('  - Codex CLI 未检测到，跳过', '  - Codex CLI not detected, skipped'))
+  return results
 }
 
 function installGlobal(runtime) {
+  const results = {}
   for (const host of ['claude', 'gemini', 'codex']) {
-    reportHostAction(runtime, 'install', host, 'global', installHostGlobal(runtime, host))
+    const result = installHostGlobal(runtime, host)
+    reportHostAction(runtime, 'install', host, 'global', result)
+    results[host] = result
   }
+  return results
 }
 
 export function installAllHosts(runtime, mode) {
-  if (mode === 'global') installGlobal(runtime)
-  else installStandby(runtime)
+  if (mode === 'global') return installGlobal(runtime)
+  return installStandby(runtime)
 }
 
 export function uninstallAllHosts(runtime) {

package/scripts/cli-lifecycle.mjs

@@ -115,7 +115,6 @@ function resolveHostMode(host, explicitMode, settings) {
   if (explicitMode) return explicitMode
   return detectHostMode(host)
     || getTrackedHostMode(settings, host)
-    || (!hasTrackedHostModes(settings) ? (settings.install_mode || '') : '')
     || DEFAULTS.install_mode
 }
 
@@ -183,21 +182,31 @@ function runAllHostsLifecycle(action, explicitMode) {
   }
 
   const settings = readSettings(true)
-  if (action === 'update' && !explicitMode) {
+  if (!explicitMode) {
     for (const host of HOSTS) {
       const mode = resolveHostMode(host, '', settings)
       const result = runHostLifecycle(runtime, action, host, mode)
-      if (!result.skipped) setTrackedHostMode(settings, host, mode)
+      if (!result.skipped && result.ok !== false) setTrackedHostMode(settings, host, mode)
+      else clearTrackedHostMode(settings, host)
     }
     writeSettings(settings)
-    runtime.printInstallMsg(settings.install_mode || DEFAULTS.install_mode, 'refresh')
+    const modes = Object.values(settings.host_install_modes || {})
+    const displayMode = modes.length && modes.every((mode) => mode === modes[0])
+      ? modes[0]
+      : settings.install_mode || DEFAULTS.install_mode
+    runtime.printInstallMsg(displayMode, action === 'update' ? 'refresh' : 'install')
     return
   }
 
   const mode = resolveInstallMode(explicitMode, settings)
   if (explicitMode) settings.install_mode = explicitMode
-  installAllHosts(runtime, mode)
-  setAllTrackedHostModes(settings, mode)
+  const results = installAllHosts(runtime, mode)
+  settings.host_install_modes = {}
+  for (const host of HOSTS) {
+    if (!results?.[host]?.skipped && results?.[host]?.ok !== false) {
+      settings.host_install_modes[host] = mode
+    }
+  }
   writeSettings(settings)
   runtime.printInstallMsg(mode, action === 'update' ? 'refresh' : 'install')
 }

package/scripts/cli-runtime-carrier.mjs

@@ -1,36 +1,15 @@
 import { join } from 'node:path'
 
-import { DEFAULTS } from './cli-config.mjs'
 import { safeJson } from './cli-utils.mjs'
 
-const CARRIER_SETTING_KEYS = [
-  'output_language',
-  'output_format',
-  'notify_level',
-  'ralph_loop_enabled',
-  'guard_enabled',
-  'kb_create_mode',
-  'project_store_mode',
-  'commit_attribution',
-]
-
-function pickCarrierSettings(settings) {
-  const merged = { ...DEFAULTS, ...(settings || {}) }
-  return Object.fromEntries(CARRIER_SETTING_KEYS.map((key) => [key, merged[key]]))
-}
-
 export function readCarrierSettings(home) {
-  return pickCarrierSettings(safeJson(join(home, '.helloagents', 'helloagents.json')) || {})
+  return safeJson(join(home, '.helloagents', 'helloagents.json')) || {}
 }
 
 export function buildRuntimeCarrier(bootstrapContent, settings = {}) {
+  void settings
   const normalized = String(bootstrapContent || '').trim()
   if (!normalized) return ''
 
-  const carrierSettings = pickCarrierSettings(settings)
-  const snapshot = Object.keys(carrierSettings).length
-    ? `\n\n## 当前用户设置\n\`\`\`json\n${JSON.stringify(carrierSettings, null, 2)}\n\`\`\``
-    : ''
-
-  return `${normalized}${snapshot}\n`
+  return `${normalized}\n`
 }

package/scripts/notify-events.mjs

@@ -1,5 +1,7 @@
 export function shouldIgnoreCodexNotifyClient(client) {
-  return !!client && client !== 'codex-tui';
+  if (!client) return false;
+  const normalized = String(client).trim().toLowerCase().replace(/[_\s]+/g, '-');
+  return normalized !== 'codex' && !normalized.startsWith('codex-');
 }
 
 export function shouldIgnoreFormattedSubagent(lastMsg, outputFormatEnabled) {

package/scripts/notify-route.mjs

@@ -11,7 +11,7 @@ function shouldBypassRoute(prompt) {
 
 function buildHelpExtraRules(skillName) {
   if (skillName !== 'help') return ''
-  return ' 这是 HelloAGENTS 的帮助命令，不是宿主 CLI 的内置帮助。仅显示 HelloAGENTS 的帮助和当前设置；优先使用当前上下文中已注入的“当前用户设置”，上下文不存在或缺少要展示的配置项时才读取 ~/.helloagents/helloagents.json；自动激活技能说明仅在全局模式或已激活项目中生效。不要调用宿主 CLI 的帮助工具（如 cli_help 或 /help），不要使用子代理，不要读取项目文件；若受工作区限制无法读取配置，必须明确说明并按已知默认值或已注入设置展示。'
+  return ' 这是 HelloAGENTS 的帮助命令，不是宿主 CLI 的内置帮助。仅显示 HelloAGENTS 的帮助和当前设置；优先使用当前会话上下文中已注入的“当前用户设置”、配置文件原始 JSON 或此前读取结果摘要，上下文不存在或缺少要展示的配置项时才读取一次 ~/.helloagents/helloagents.json；自动激活技能说明仅在全局模式或已激活项目中生效。不要调用宿主 CLI 的帮助工具（如 cli_help 或 /help），不要使用子代理，不要读取项目文件；若受工作区限制无法读取配置，必须明确说明并按已知默认值或已注入设置展示。'
 }
 
 function routeExplicitCommand({

package/scripts/notify-ui.mjs

@@ -5,7 +5,7 @@
 import { platform } from 'node:os';
 import { join } from 'node:path';
 import { existsSync } from 'node:fs';
-import { spawn } from 'node:child_process';
+import { spawnSync } from 'node:child_process';
 
 const PLAT = platform();
 
@@ -55,16 +55,13 @@ function resolveWav(pkgRoot, event) {
   return existsSync(p) ? p : null;
 }
 
-function spawnDetached(command, args) {
+function runSync(command, args) {
   try {
-    const child = spawn(command, args, {
-      detached: true,
+    const result = spawnSync(command, args, {
       stdio: 'ignore',
       windowsHide: true,
     });
-    child.on('error', () => {});
-    child.unref();
-    return true;
+    return !result.error && result.status === 0;
   } catch {
     return false;
   }
@@ -76,15 +73,15 @@ export function playSound(pkgRoot, event) {
   if (!wav) { process.stderr.write('\x07'); return; }
   try {
     if (PLAT === 'win32') {
-      spawnDetached('powershell', [
+      runSync('powershell', [
         '-NoProfile',
         '-c',
         `(New-Object Media.SoundPlayer '${wav.replace(/'/g, "''")}').PlaySync()`,
       ]);
     } else if (PLAT === 'darwin') {
-      spawnDetached('afplay', [wav]);
+      runSync('afplay', [wav]);
     } else {
-      spawnDetached('aplay', ['-q', wav]) || spawnDetached('paplay', [wav]);
+      if (!runSync('aplay', ['-q', wav]) && !runSync('paplay', [wav])) process.stderr.write('\x07');
     }
   } catch { process.stderr.write('\x07'); }
 }
@@ -127,16 +124,16 @@ export function desktopNotify(pkgRoot, event, extra) {
   try {
     if (PLAT === 'win32') {
       const iconPath = join(pkgRoot, 'assets', 'icons', 'icon.png').replace(/\//g, '\\');
-      spawnDetached('powershell', ['-NoProfile', '-c', buildWindowsToastScript(notification, iconPath)]);
+      runSync('powershell', ['-NoProfile', '-c', buildWindowsToastScript(notification, iconPath)]);
     } else if (PLAT === 'darwin') {
       const subtitle = notification.sourceLabel
         ? ` subtitle "${escapeAppleScriptText(notification.sourceLabel)}"`
         : '';
-      spawnDetached('osascript', ['-e',
+      runSync('osascript', ['-e',
         `display notification "${escapeAppleScriptText(notification.message)}" with title "${escapeAppleScriptText(notification.title)}"${subtitle}`],
       );
     } else {
-      spawnDetached('notify-send', [notification.title, notification.body]);
+      if (!runSync('notify-send', [notification.title, notification.body])) process.stderr.write('\x07');
     }
   } catch { process.stderr.write('\x07'); }
 }

package/scripts/notify.mjs

@@ -47,8 +47,12 @@ function normalizeNotifyLevel(value) {
 
 function notifyByLevel(event, extra, settings = getSettings()) {
   const level = normalizeNotifyLevel(settings.notify_level ?? 0);
-  if (level === 2 || level === 3) playSound(event);
-  if (level === 1 || level === 3) desktopNotify(event, extra);
+  if (level === 1) desktopNotify(event, extra);
+  if (level === 2) playSound(event);
+  if (level === 3) {
+    desktopNotify(event, extra);
+    playSound(event);
+  }
 }
 
 function buildNotifyExtra(payload = {}, options = {}) {
@@ -254,7 +258,7 @@ function cmdStop() {
   }
 
   const settings = getSettings();
-  if (shouldProcess) {
+  if (shouldProcess || !turnState) {
     notifyByLevel('complete', buildNotifyExtra(payload), settings);
   }
   consumeMainTurnState(cwd, turnState, turnPayload);
@@ -291,7 +295,11 @@ function cmdCodexNotify() {
     if (turnState && turnState.kind !== 'complete') consumeMainTurnState(cwd, turnState, turnPayload);
     return;
   }
-  if (!turnState) return;
+  if (!turnState) {
+    notifyByLevel('complete', buildNotifyExtra(data), getSettings());
+    clearRouteContext({ cwd, payload: turnPayload });
+    return;
+  }
   if (turnState.kind !== 'complete') {
     consumeMainTurnState(cwd, turnState, turnPayload);
     clearRouteContext({ cwd, payload: turnPayload });

package/scripts/workflow-core.mjs

@@ -167,7 +167,7 @@ export function buildUiContractHint(cwd, snapshot) {
   if (visualValidationRequired) {
     extraHints.push('若当前 UI 契约要求视觉验收，收尾前需写当前会话 `artifacts/visual.json` 记录关键视口、状态与结论')
   }
-  return `UI 约束提示：如本次属于视觉/交互任务，设计决策优先级固定为：当前活跃 plan.md / prd/03-ui-design.md → ${describeProjectStoreFile(cwd, 'DESIGN.md')} → hello-ui。${extraHints.length > 0 ? ` ${extraHints.join('；')}。` : ''}`
+  return `UI 约束提示：如本次属于视觉/交互任务，设计决策优先级固定为：当前活跃 plan.md / prd/03-ui-design.md → ${describeProjectStoreFile(cwd, 'DESIGN.md')} → hello-ui，并与 UI 质量基线共同生效。${extraHints.length > 0 ? ` ${extraHints.join('；')}。` : ''}`
 }
 
 export { normalizeTaskFile, readStateSnapshot, listPlanPackages, getWorkflowSnapshot }

package/skills/commands/commit/SKILL.md

@@ -15,7 +15,7 @@ Trigger: ~commit [message]
 3. 生成 conventional commit message（如未提供）
    - 格式: type(scope): description
    - type: feat|fix|refactor|docs|test|chore|style|perf
-4. 先一次性解析本轮设置：优先使用当前上下文中已注入的“当前用户设置”；上下文不存在或缺少 `commit_attribution` / `kb_create_mode` 时，读取一次 `~/.helloagents/helloagents.json`
+4. 先一次性解析会话中已知设置：优先使用当前会话上下文中已注入的“当前用户设置”、该配置文件原始 JSON 或此前读取结果摘要；上下文不存在或缺少 `commit_attribution` / `kb_create_mode` 时，才读取一次 `~/.helloagents/helloagents.json`
 5. 复用上一步已解析的设置获取 `commit_attribution`：
    - ""（空，默认）→ 不添加归属
    - 有内容（如 "Co-Authored-By: HelloAGENTS"）→ 添加该内容到 commit message

package/skills/commands/help/SKILL.md

@@ -39,7 +39,7 @@ Trigger: ~help
 完成时：hello-verify, hello-reflect
 
 ### 当前设置
-优先使用当前上下文中已注入的“当前用户设置”显示；若上下文不存在该信息，或缺少下表任一配置项，读取一次 `~/.helloagents/helloagents.json`。
+优先使用当前会话上下文中已注入的“当前用户设置”、该配置文件原始 JSON 或此前读取结果摘要显示；若会话上下文不存在该信息，或缺少下表任一配置项，才读取一次 `~/.helloagents/helloagents.json`，并在后续轮次复用。
 如果当前 CLI 存在工作区限制导致家目录不可读，则明确说明“无法直接读取配置文件，以下按已注入设置或默认值展示”，不要改用无关工具或伪造已读取结果。
 | 配置项 | 默认值 | 作用 | 适用 CLI |
 |--------|-------|------|---------|
@@ -51,3 +51,5 @@ Trigger: ~help
 | 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 |
 | commit_attribution | "" | 空=不添加/填写内容则添加到 commit message | Claude Code + Gemini CLI + Codex CLI |
+| install_mode | "standby" | 当前默认安装模式 | Claude Code + Gemini CLI + Codex CLI |
+| host_install_modes | {} | 单 CLI 模式记录，优先于 install_mode | Claude Code + Gemini CLI + Codex CLI |

package/skills/hello-ui/SKILL.md

@@ -1,20 +1,20 @@
 ---
 name: hello-ui
-description: 已进入显式 UI 工作流、已激活项目的视觉变更、设计系统改造或需要视觉验收时使用；在通用 UI 基线之上补充项目契约执行、设计系统映射与视觉验证。
+description: 已进入显式 UI 工作流、全局模式中的 UI 任务、已激活项目的视觉变更、设计系统改造或需要视觉验收时使用；在通用 UI 基线之上补充项目契约执行、设计系统映射与视觉验证。
 ---
 
 本 skill 不是 UI 质量的唯一来源。当前已加载 bootstrap 中的 UI 质量基线负责所有 UI 任务的基础水准；本 skill 在显式 UI 工作流和复杂 UI 任务中，补充更明确的契约执行、实现映射与视觉验收。
 `.helloagents/` 在本 skill 中统一按项目级存储路径理解：会话证据使用当前 `state_path` 所在目录下的 `artifacts/*.json`；若 `project_store_mode=repo-shared`，`DESIGN.md` 与方案包按当前上下文中已注入的项目知识/方案目录解析。
 
 ## 适用边界
-已进入显式 UI 规划/实现/验证路径，或当前项目已激活且任务涉及整页新建、跨多个组件的视觉重做、设计系统改造、需要截图验收的界面任务时，读取本 skill。
+已进入显式 UI 规划/实现/验证路径、全局模式中的 UI 任务，或当前项目已激活且任务涉及整页新建、跨多个组件的视觉重做、设计系统改造、需要截图验收的界面任务时，读取本 skill。
 标准模式未激活项目中的普通 UI 请求，仍只受当前 bootstrap 的 UI 质量基线约束；修复 bug、调整文案、改业务逻辑等不涉及视觉变更的任务，不读取本 skill。在已有设计系统中工作时，保留已建立的模式、结构和视觉语言。
 
 ## 设计契约优先级
 进入 UI 相关的规划、实现、验证时，按以下顺序做设计决策：
 1. 当前活跃方案包 `plan.md` 或 PRD 中已确认的 UI 决策
 2. `.helloagents/DESIGN.md`（按当前项目存储模式解析）
-3. 本 skill 的通用规则
+3. 本 skill 的具体 UI 审美与实现规则，并与 UI 质量基线共同生效
 缺少上层产物时，才直接依赖下层规则；不得用通用审美覆盖已确认的项目契约。
 
 ## 核心职责

package/skills/helloagents/SKILL.md

@@ -23,7 +23,7 @@ description: 按任务类型适用 — 建立质量驱动工作流，通过技
 ### 流程纪律（执行时）
 - 执行 command skill 时，公共阶段边界以当前已加载 bootstrap 为准；command skill 只补充该命令的专属动作和边界
 - 统一执行流程的六个阶段（ROUTE/TIER→SPEC→PLAN→BUILD→VERIFY→CONSOLIDATE）按当前 Delivery Tier 和实际任务推进；未进入的阶段不强行补齐，已进入的阶段不可跳过
-- 所有 UI 任务先受当前 bootstrap 的 UI 质量基线约束；已激活项目或显式 UI 工作流中的设计约束优先级固定为：当前 `plan.md` / PRD UI 决策 → `.helloagents/DESIGN.md`（按当前项目存储模式解析） → `hello-ui` 深层规则
+- 所有 UI 任务先受当前 bootstrap 的 UI 质量基线约束；已激活项目、全局模式或显式 UI 工作流中的设计约束优先级固定为：当前 `plan.md` / PRD UI 决策 → `.helloagents/DESIGN.md`（按当前项目存储模式解析） → `hello-ui` 具体 UI 审美与实现规则，并与 UI 质量基线共同生效
 - 方案包存在 `contract.json` 时，验证分流、reviewer / tester 关注边界、可选 style advisor / visual validation 与交付检查优先按它执行，不再从自然语言总结里回推
 - 因阻塞判定而必须等待用户输入时，遵循当前 bootstrap 的等待输入规则，不得把等待输入包装成完成态
 - ~plan 的需求澄清与方案确认不可跳过，不可一个问题就出方案
@@ -57,7 +57,7 @@ Layer 3 — 资源文件（技能内引用时读取）：
 禁止行为：
 - 禁止在 ROUTE / TIER / SPEC 阶段读取实现类技能（hello-ui/hello-test/hello-verify 等）
 - 禁止因为"可能用到"就提前读取技能文件——等到真正需要时再读
-- 同一轮内对同一配置文件、模块、SKILL、模板只读取一次，后续直接复用已得结论，不重复探测或重复读取同一路径
+- 同一会话内，同一路径的配置文件、模块、SKILL、模板只读一次并跨轮复用；缺少所需内容、读取失败、用户要求刷新或本轮修改后才重新读取
 - ~command 命令只读取对应的 command SKILL.md，不连带读取其他技能
 
 ## 技能查找路径