helloloop 0.3.1 → 0.7.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "helloloop",
-  "version": "0.3.1",
+  "version": "0.7.0",
   "description": "HelloLoop 的 Claude Code 原生插件元数据，用于多 CLI 宿主分发。",
   "author": {
     "name": "HelloLoop"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "helloloop",
-  "version": "0.3.1",
+  "version": "0.7.0",
   "description": "面向 Codex CLI、Claude Code、Gemini CLI 的多宿主开发工作流插件，Codex 路径为首发与参考实现。",
   "author": {
     "name": "HelloLoop"
@@ -16,8 +16,8 @@
   "skills": "./skills/",
   "interface": {
     "displayName": "HelloLoop",
-    "shortDescription": "基于 backlog 的持续仓库开发与验证循环",
-    "longDescription": "HelloLoop 把基于 backlog 的持续开发能力封装为官方 Codex 插件 bundle。显式调用 helloloop skill 时，默认优先进入 npx helloloop 主 CLI 流程：先分析、再展示确认单、确认后自动接续推进。",
+    "shortDescription": "显式调用后按 backlog 持续开发与验证",
+    "longDescription": "HelloLoop 把基于 backlog 的持续开发能力封装为官方 Codex 插件 bundle。只有在用户显式调用 helloloop skill，或明确要求使用 HelloLoop 时才应介入；进入后默认优先走 npx helloloop 主 CLI 流程：支持 npx helloloop、npx helloloop <PATH>、npx helloloop codex|claude|gemini ...，先分析、再展示确认单、确认后自动接续推进；运行中按无人值守自动恢复持续推进主线。",
     "developerName": "HelloLoop",
     "category": "Coding",
     "capabilities": [
@@ -25,7 +25,7 @@
       "Write"
     ],
     "defaultPrompt": [
-      "使用 HelloLoop 时，优先执行 npx helloloop 或 npx helloloop <PATH> 主流程，而不是在对话里手工模拟分析与续跑。"
+      "只有当用户显式调用 $helloloop / #helloloop / helloloop:helloloop，或明确要求使用 HelloLoop 时，才进入 npx helloloop 主 CLI 流程；普通 Codex 会话不要自动接管。进入后优先执行 npx helloloop 或 npx helloloop <PATH>；如果用户明确指定执行引擎，也允许使用 npx helloloop codex|claude|gemini ...。启动前确认一次，启动后按无人值守自动恢复与主线续跑执行，不要在对话里手工模拟流程。"
     ],
     "brandColor": "#0F766E"
   }

package/README.md

@@ -1,74 +1,147 @@
 # HelloLoop
 
-`HelloLoop` 是一个面向 `Codex CLI`、`Claude Code`、`Gemini CLI` 的多宿主开发工作流插件，用来把“根据开发文档持续接续开发、测试、验收直到最终目标完成”收敛成一条统一、可确认、可追踪的标准流程。
+`HelloLoop` 是一个面向 `Codex CLI`、`Claude Code`、`Gemini CLI` 的多宿主开发工作流插件，用来把“根据开发文档持续接续开发、测试、验收，直到最终目标完成”收敛成一条统一、可确认、可追踪的标准流程。
 
-它的定位很明确：
+它的核心原则很简单：
 
-- `Codex CLI`：首发平台、参考实现、最佳体验路径
-- `Claude Code` / `Gemini CLI`：各自按原生 agent 逻辑执行，但共享同一套 `.helloloop/` 工作流规范
-- 三家都能安装、都能用、都原生执行开发，不是让一家的 CLI 去伪装成另一家
+- 三家都能安装、都能用、都按各自原生 agent 逻辑执行
+- `Codex CLI` 仍然是首发平台、参考实现和最佳体验路径
+- 运行状态统一写入目标仓库根目录的 `.helloloop/`
+- 真正执行前先分析、先确认，执行中不静默失败、不静默切换
 
-## 核心价值
+## 宿主与执行引擎
 
-- **一条主命令**：优先只用 `npx helloloop` 或 `npx helloloop <PATH>`
-- **自动补全上下文**：自动识别开发文档、项目仓库、当前进度和偏差
-- **先确认再执行**：真正改代码前先输出中文执行确认单
-- **持续推进到底**：确认后继续开发、测试、验收，直到完成最终目标或遇到硬阻塞
-- **跨宿主统一状态**：运行状态统一写入目标仓库根目录的 `.helloloop/`
-- **跨平台安全**：兼容 Windows / macOS / Linux，Windows 不回退到 `cmd.exe`
+`HelloLoop` 区分两个概念：
+
+- **宿主**：你从哪里进入，例如终端、`Codex`、`Claude`、`Gemini`
+- **执行引擎**：真正负责本轮分析 / 开发 / 测试推进的 CLI
+
+这意味着：
+
+- 三宿主都只在用户显式调用 `helloloop` 时介入；普通会话不会被 HelloLoop 自动接管
+- 无论在终端还是在 `Codex` / `Claude` / `Gemini` 宿主内，只要用户未明确指定引擎，`HelloLoop` 都会先询问本轮执行引擎
+- 当前宿主、项目历史、用户历史只作为推荐依据，不会自动替你选中引擎
+- 如果你已经显式指定，或已经在首轮确认中明确选定了引擎，本轮就固定按该引擎执行
+- 如果后续因为登录、配额、限流等问题需要改用别的引擎，`HelloLoop` 也会先询问，不会静默切换
 
 ## 支持矩阵
 
-| 宿主 | 安装方式 | 原生入口 | 执行方式 |
+| 宿主 | 安装方式 | 原生入口 | 说明 |
 | --- | --- | --- | --- |
-| `Codex CLI` | `helloloop install --host codex` | `$helloloop` / `npx helloloop` | Codex 原生插件 + CLI |
-| `Claude Code` | `helloloop install --host claude` | `/helloloop` | Claude 原生 marketplace / plugin |
-| `Gemini CLI` | `helloloop install --host gemini` | `/helloloop` | Gemini 原生 extension |
+| `Codex CLI` | `helloloop install` / `helloloop install --host codex` | `$helloloop` / `npx helloloop` | 仅在显式调用时进入 HelloLoop |
+| `Claude Code` | `helloloop install --host claude` | `/helloloop` | 仅在显式调用时进入 HelloLoop |
+| `Gemini CLI` | `helloloop install --host gemini` | `/helloloop` | 仅在显式调用时进入 HelloLoop |
+
+## 最短使用方式
+
+推荐先记住下面四种：
+
+```bash
+npx helloloop
+npx helloloop <PATH>
+npx helloloop claude
+npx helloloop gemini <PATH> 接续完成剩余开发
+```
+
+其中：
+
+- `<PATH>` 可以是项目仓库路径、开发文档目录、开发文档文件
+- 命令后可以继续追加自然语言要求
+- 不确定时，优先只输入 `npx helloloop`
+
+## 执行引擎选择规则
+
+执行规则如下：
+
+1. 命令首参数显式引擎：`codex` / `claude` / `gemini`
+2. 自然语言中明确且不歧义地指定了引擎
+3. 如果前两步仍未明确，先停下来询问本轮执行引擎；当前宿主、项目上次 / 默认、用户上次 / 默认只作为推荐依据
+4. `-y` / `--yes` 等非交互模式下，如果你没有显式指定引擎，`HelloLoop` 会直接停止并要求补充引擎
+
+补充说明：
+
+- 首参只有第一个裸词会被解释为引擎；如果你真要把 `claude` 当目录名，请写成 `./claude`、`.\claude` 或绝对路径
+- 命令后的自然语言如果明确提到 `codex`、`claude`、`gemini`，也会纳入意图判断
+- 当前宿主、项目历史、用户历史不会触发自动选中，只会影响“推荐项”
+- `已安装` 不等于 `可继续执行`；如果当前引擎在运行中遇到 400、鉴权、欠费、429、5xx、网络抖动、流中断、长时间卡死等问题，`HelloLoop` 会先按无人值守策略做同引擎“健康探测 + 条件恢复”，不会中途停下来询问
 
 ## 默认工作流
 
-无论从哪个宿主进入，`HelloLoop` 都遵循同一条主线：
+无论从哪个宿主进入，都遵循同一条主线：
 
 1. 自动识别目标项目仓库与开发文档
-2. 分析“代码当前做到哪里了”“与文档目标是否有偏差”“当前项目是否匹配文档目标”
+2. 分析当前代码进度、偏差和项目匹配性
 3. 在目标仓库根目录创建或刷新 `.helloloop/`
 4. 输出中文执行确认单
-5. 用户确认后，按当前宿主的原生 agent 逻辑继续推进开发、测试和验收
+5. 用户确认后，按选中的执行引擎持续推进开发、测试、验收
+6. 每个任务完成后，自动做一次“任务完成复核”
+7. backlog 暂时清空后，自动做一次“主线终态复核”
 
 如果分析发现当前实现已经偏离开发文档，`HelloLoop` 会优先先收口偏差，再继续后面的 backlog。
 
-## 最短使用方式
+这意味着：
 
-推荐优先只记住下面两条：
+- 不会因为执行引擎自己一句“已完成”就直接结束
+- 如果只是部分完成，`HelloLoop` 会继续当前主线任务，而不是跳去做模型随口建议的别的事
+- 如果 backlog 清空了，但主线终态复核仍发现文档目标还有缺口，`HelloLoop` 会自动重新分析并继续推进
+- 如果模型只做了一半就想停下来给“下一步建议”，`HelloLoop` 会优先按主线目标继续推进，而不是把半成品当完成
 
-```bash
-npx helloloop
-npx helloloop <PATH>
-```
+## 无人值守恢复
 
-也支持在命令后继续附带路径和自然语言要求：
+`HelloLoop` 的设计目标不是“跑一轮停一轮”，而是启动前确认一次，启动后持续无人值守推进。
 
-```bash
-npx helloloop <PATH> <补充说明>
-```
+- 因此运行中的默认策略是：
 
-例如：
+- 普通运行故障不再中途提问：不会因为 429、5xx、网络抖动、结果流中断、短时空输出就停下来问用户
+- 同引擎优先恢复：默认不会自动切换引擎，也不会偷偷改用别的 CLI
+- 先探测、后续跑：重试前会先做最小健康探测；只有探测通过后，才会恢复主线任务，而不是盲目把完整任务再跑一遍
+- 保留主线上下文恢复：同引擎恢复时会生成恢复记录与恢复 prompt，要求新一轮执行直接基于当前仓库状态继续，而不是从头另起一套
+- 定时心跳检查：运行中会持续写入心跳与恢复状态，用于判断当前阶段是否还在正常推进
+- 最终停止会告警：如果自动恢复额度真正用尽，且已配置全局邮箱，`HelloLoop` 会把错误类型与具体内容发到指定邮箱
 
-```bash
-npx helloloop docs/plan.md ./demo-app 接续完成剩余开发内容，并严格执行测试和验收
-```
+默认恢复节奏：
 
-这里的 `<PATH>` 可以是：
+- 心跳间隔：60 秒
+- 疑似卡住预警：15 分钟无可见进展
+- 自动终止阈值：45 分钟无可见进展
+- 硬阻塞：每 15 分钟探测 1 次，共 5 次；仍失败则暂停等待人工介入
+- 软阻塞：先每 15 分钟探测 5 次，再 30 分钟 2 次，再按 60 / 90 / 120 / 150 / 180 分钟各探测 1 次；仍失败则暂停等待人工介入
 
-- 项目仓库路径
-- 开发文档目录
-- 开发文档文件
+如果你明确指定或确认了本轮引擎，`HelloLoop` 在自动恢复阶段也会继续锁定该引擎，不会擅自切换。
 
-这里的 `<补充说明>` 可以是：
+## 全局告警配置
 
-- 第二个显式路径
-- 本次执行的额外要求
-- 偏差修正、质量要求、交付目标等自然语言说明
+如果希望在“自动恢复彻底停止”后收到邮件告警，可在：
+
+```text
+~/.helloloop/settings.json
+```
+
+中配置邮件通知，例如：
+
+```json
+{
+  "notifications": {
+    "email": {
+      "enabled": true,
+      "to": ["you@example.com"],
+      "from": "helloloop@example.com",
+      "smtp": {
+        "host": "smtp.example.com",
+        "port": 465,
+        "secure": true,
+        "username": "helloloop@example.com",
+        "passwordEnv": "HELLOLOOP_SMTP_PASSWORD"
+      }
+    }
+  }
+}
+```
+
+说明：
+
+- 建议把 SMTP 密码放在环境变量里，不要明文写进配置文件
+- 邮件只在“本轮不再继续自动重试”时发送，不会每次失败都刷屏
 
 ## 自动发现与交互逻辑
 
@@ -80,10 +153,10 @@ npx helloloop docs/plan.md ./demo-app 接续完成剩余开发内容，并严格
 npx helloloop
 ```
 
-`HelloLoop` 会先快速扫描当前目录：
+`HelloLoop` 会先明确执行引擎，再快速扫描当前目录：
 
 - 当前目录本身就是项目仓库或开发文档目录时，直接进入分析
-- 当前目录更像“工作区”时，优先尝试使用顶层开发文档，再提示选择候选项目目录
+- 当前目录更像工作区时，优先利用顶层文档，再提示选择候选项目目录
 - 当前目录没有明确开发文档时，不会直接报错，而是先列出：
   - 顶层文档文件
   - 顶层目录
@@ -92,12 +165,12 @@ npx helloloop
 
 ### 2. 项目路径只问一次
 
-对外只有“项目路径”这一个概念，不单独再追问“新项目路径”。
+对外只有“项目路径”这一个概念：
 
-- 你输入已有目录 → 按现有项目继续分析
-- 你输入不存在的目录 → 视为准备创建的新项目目录
+- 输入已有目录 → 按现有项目继续分析
+- 输入不存在的目录 → 视为准备创建的新项目目录
 
-也就是说，用户只需要提供一次项目路径。
+不会再额外追问一个“新项目路径”。
 
 ### 3. 文档和项目缺一不可时会停下询问
 
@@ -107,11 +180,9 @@ npx helloloop
 - 给了项目路径，但无法定位开发文档
 - 同时出现多个冲突的文档路径或项目路径
 
-此时 `HelloLoop` 会暂停，并要求用户补充正确信息。
-
 ### 4. 命令 + 自然语言会一起分析
 
-`HelloLoop` 不依赖固定中文关键词来做硬编码分流。
+`HelloLoop` 不依赖固定中文关键词做硬编码分流。
 
 命令里的：
 
@@ -120,7 +191,7 @@ npx helloloop
 - 英文自然语言
 - 其他语言的补充要求
 
-都会一起进入分析与确认单，不会因为语言不同被静默忽略。
+都会一起进入分析和确认单，不会因为语言不同被静默忽略。
 
 ### 5. 现有项目与文档目标冲突时
 
@@ -136,14 +207,13 @@ npx helloloop
 npx helloloop --rebuild-existing
 ```
 
-重建时会保留必要的仓库元数据和状态目录，例如 `.git`、`.gitignore`、`.gitattributes`、`.helloagents`、`.helloloop`。
-
 ## 执行确认单
 
-真正开始开发前，`HelloLoop` 会先输出中文执行确认单。当前确认单至少包含：
+真正开始开发前，`HelloLoop` 会先输出中文执行确认单，至少包含：
 
 - 路径判断与判断依据
 - 本次命令补充输入
+- 执行引擎
 - 需求语义理解
 - 项目匹配判断
 - 目标仓库
@@ -158,13 +228,22 @@ npx helloloop --rebuild-existing
 
 未确认前，不会正式修改代码。
 
+确认后，默认行为不是“跑一轮就停”，而是：
+
+- 先按 backlog 执行当前颗粒度任务
+- 每个任务完成后复核其验收是否真的闭合
+- backlog 清空后再复核一次整个主线目标
+- 只有“任务验收闭合 + 主线目标闭合 + 验证通过”才算真正结束
+- 运行中若出现可恢复的 CLI 故障，则按无人值守策略自动恢复，不打断主线
+
 ## 安装
 
-### npm / npx
+### 通过 npm / npx
 
 默认安装到 `Codex`：
 
 ```bash
+npx helloloop install
 npx helloloop install --codex-home <CODEX_HOME>
 ```
 
@@ -199,13 +278,21 @@ pwsh -NoLogo -NoProfile -File .\scripts\install-home-plugin.ps1 -CodexHome <CODE
 
 ### 升级、重装、切换分支
 
-如果你已经安装过，但刚拉取了新版本、切换了分支、或想覆盖旧安装，直接重新执行：
-
 ```bash
+npx helloloop install --force
+npx helloloop install --host claude --force
+npx helloloop install --host gemini --force
 npx helloloop install --host codex --force
 npx helloloop install --host all --force
 ```
 
+说明：
+
+- `--force` 会清理当前宿主里已有安装残留的 `helloloop` 目录后再重装
+- `Codex` 会刷新插件目录和 marketplace 条目
+- `Claude` 会刷新 marketplace、缓存插件目录，以及 `settings.json` / `known_marketplaces.json` / `installed_plugins.json` 中的 `helloloop` 条目
+- `Gemini` 会刷新 `extensions/helloloop/`，不会动同目录下其他扩展
+
 ### 卸载
 
 ```bash
@@ -215,38 +302,41 @@ npx helloloop uninstall --host gemini
 npx helloloop uninstall --host all
 ```
 
-### 安装结果
+卸载是定向清理：
 
-安装完成后，运行时资产会写入：
+- 只删除 `helloloop` 自己的安装目录和注册条目
+- 不会顺带删除别的插件、marketplace、扩展或自定义配置
+- 即使某个宿主当前未安装 `helloloop`，也会安全退出，不做破坏性清理
 
-- `Codex`：`<CODEX_HOME>/plugins/helloloop`
-- `Claude`：`<CLAUDE_HOME>/plugins/marketplaces/helloloop-local` 与 `plugins/cache/helloloop-local/helloloop/<VERSION>`
-- `Gemini`：`<GEMINI_HOME>/extensions/helloloop`
+## 使用入口
 
-源码仓库里的 `docs/` 与 `tests/` 不会复制进运行时安装包。
+### 终端
 
-## 使用入口
+```bash
+npx helloloop
+npx helloloop <PATH>
+npx helloloop codex <PATH>
+npx helloloop claude <PATH>
+npx helloloop gemini <PATH> <补充说明>
+```
+
+如果已经做了全局安装，也可以把 `npx helloloop` 简写为 `helloloop`。是否立刻可用取决于当前 shell 是否已经刷新 `PATH`。
 
 ### Codex CLI
 
 ```text
 $helloloop
+helloloop:helloloop
 ```
 
-或：
+在 `Codex` 中也可以直接执行：
 
 ```bash
 npx helloloop
-npx helloloop <PATH>
 ```
 
-`$helloloop` 的推荐行为与主命令保持一致：优先进入 `npx helloloop` 主流程，而不是在对话里手工模拟分析和续跑。
-
-如果你显式使用技能名，也可以写：
-
-```text
-helloloop:helloloop
-```
+如果你在 `Codex` 中直接使用 `$helloloop` 或 `npx helloloop`，但没有明确指定引擎，`HelloLoop` 仍会先让你确认本轮引擎；`Codex` 只会作为推荐项，不会被自动选中。
+未显式调用 `$helloloop`、`helloloop:helloloop` 或 `npx helloloop` 时，普通 `Codex` 会话不会被 HelloLoop 自动接管。
 
 ### Claude Code / Gemini CLI
 
@@ -255,12 +345,13 @@ helloloop:helloloop
 ```
 
 它们会按各自 CLI 的原生 agent 逻辑执行，但共享同一套 `.helloloop/` 工作流规范。
+只有在你显式调用 `/helloloop` 时，它们才会进入 HelloLoop 工作流；普通 Claude / Gemini 会话不会被自动接管。
 
-## 命令速查
+## 常用命令
 
 | 命令 | 作用 |
 | --- | --- |
-| `helloloop` / `analyze` | 自动分析、展示确认单，并在确认后继续接续开发 |
+| `helloloop` / `analyze` | 自动分析、展示确认单，并在确认后持续接续开发，直到主线目标闭合或遇到硬阻塞 |
 | `install` | 安装运行时 bundle 到指定宿主 |
 | `uninstall` | 从指定宿主卸载运行时 bundle 与注册信息 |
 | `doctor` | 检查宿主环境、插件资产与目标仓库状态 |
@@ -274,12 +365,13 @@ helloloop:helloloop
 
 | 选项 | 作用 |
 | --- | --- |
+| `codex` / `claude` / `gemini` | 作为 `analyze` 模式的命令首参数，显式指定执行引擎 |
 | `--dry-run` | 只分析并输出确认单，不开始自动执行 |
-| `-y` / `--yes` | 跳过交互确认，分析后直接执行 |
+| `-y` / `--yes` | 跳过执行确认直接开始；但如果未显式指定引擎，会直接报错而不是自动选引擎 |
 | `--repo <dir>` | 高级覆盖：显式指定项目仓库 |
 | `--docs <dir|file>` | 高级覆盖：显式指定开发文档 |
 | `--rebuild-existing` | 项目与文档冲突时，自动清理现有项目后重建 |
-| `--host <name>` | 宿主：`codex` / `claude` / `gemini` / `all` |
+| `--host <name>` | 安装宿主：`codex` / `claude` / `gemini` / `all` |
 | `--config-dir <dir>` | 状态目录名，默认 `.helloloop` |
 
 手动控制示例：
@@ -290,7 +382,7 @@ npx helloloop next
 npx helloloop run-once
 ```
 
-## Doctor 检查
+## Doctor
 
 检查默认宿主：
 
@@ -310,10 +402,28 @@ npx helloloop doctor --host all
 npx helloloop doctor --host all --codex-home <CODEX_HOME> --claude-home <CLAUDE_HOME> --gemini-home <GEMINI_HOME>
 ```
 
-`doctor` 的检查范围分两类：
+## 宿主写入范围
+
+为了方便排查安装 / 更新 / 卸载问题，下面是默认写入位置：
+
+### `Codex CLI`
+
+- 插件目录：`~/.codex/plugins/helloloop/`
+- 注册文件：`~/.codex/.agents/plugins/marketplace.json`
+
+### `Claude Code`
+
+- marketplace：`~/.claude/plugins/marketplaces/helloloop-local/`
+- 已安装插件缓存：`~/.claude/plugins/cache/helloloop-local/helloloop/<VERSION>/`
+- 用户配置：`~/.claude/settings.json`
+- marketplace 索引：`~/.claude/plugins/known_marketplaces.json`
+- 已安装插件索引：`~/.claude/plugins/installed_plugins.json`
+
+### `Gemini CLI`
+
+- 扩展目录：`~/.gemini/extensions/helloloop/`
 
-- 在插件源码仓库中运行：主要检查 CLI、bundle 资产和宿主安装资产
-- 在目标项目仓库中运行，或显式传入 `--repo`：还会检查 `.helloloop/backlog.json`、`project.json`、`policy.json`、`verify.yaml`
+`HelloLoop` 只维护自己的目录和自己的注册项，不会重写别的插件条目。
 
 ## `.helloloop/` 状态目录
 
@@ -349,9 +459,12 @@ npx helloloop doctor --host all --codex-home <CODEX_HOME> --claude-home <CLAUDE_
 
 - 不静默失败
 - 不静默回退
+- 不静默切换执行引擎
 - 不吞掉错误
 - 真正执行前先确认
 - 真正结束前先验证
+- 不轻信执行引擎口头“已完成”
+- 不接受“先做一半再停下来问要不要继续”
 
 ## 仓库结构
 

package/hosts/claude/marketplace/plugins/helloloop/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "helloloop",
-  "version": "0.3.1",
+  "version": "0.7.0",
   "description": "HelloLoop 的 Claude Code 原生插件。",
   "author": {
     "name": "HelloLoop"

package/hosts/claude/marketplace/plugins/helloloop/commands/helloloop.md

@@ -1,5 +1,5 @@
 ---
-description: 根据开发文档分析当前进度、生成确认单，并在确认后继续接续开发
+description: 仅在用户显式调用 `/helloloop` 后，根据开发文档分析当前进度、生成确认单，并在确认后继续接续开发
 argument-hint: [PATH]
 ---
 
@@ -7,15 +7,17 @@ argument-hint: [PATH]
 
 规则如下：
 
-1. 将当前代码视为事实源，将开发文档视为目标源。
-2. 如果用户在命令后提供了 `$ARGUMENTS`，必须同时保留其中的显式路径和自然语言补充要求，不要依赖固定关键词硬编码决策。
+1. 只有当用户显式调用 `/helloloop`，或明确要求“使用 HelloLoop / 走 HelloLoop 流程”时，才进入当前工作流；不要接管普通 Claude 会话。
+2. 将当前代码视为事实源，将开发文档视为目标源。
+3. 如果用户在命令后提供了 `$ARGUMENTS`，必须同时保留其中的显式路径和自然语言补充要求，不要依赖固定关键词硬编码决策。
 3. 自动识别目标仓库与开发文档，并先分析“当前代码做到哪里了”“与文档目标是否存在偏差”“当前项目与文档目标是否匹配”。
-4. 如果当前目录没有明确开发文档，先展示顶层文档文件、顶层目录和疑似项目目录，再询问用户开发文档路径。
-5. 项目路径对外只有一个概念；如果用户输入的项目路径不存在，就把它视为准备创建的新项目目录，不要再单独追问“新项目路径”。
-6. 在目标仓库根目录创建或刷新 `.helloloop/`，至少维护 `backlog.json`、`project.json`、`status.json`、`STATE.md` 与 `runs/`。
-7. 如果用户给了开发文档但无法定位项目仓库，或者给了项目路径但无法定位开发文档，必须停下来询问用户，而不是猜测。
-8. 如果当前项目目录已存在，但分析认为它与开发文档目标明显冲突，必须先明确提示用户，并确认是继续现有项目、还是清理后按文档重建。
-9. 在真正执行开发前，必须输出一份中文执行确认单，至少包含：
+4. 当前宿主是 `Claude`；如果用户未明确指定执行引擎，必须先确认本轮引擎，`Claude` 只可作为推荐项，不允许自动选中；如果用户明确要求改用 `Codex` 或 `Gemini`，必须先确认，不允许静默切换。
+5. 如果当前目录没有明确开发文档，先展示顶层文档文件、顶层目录和疑似项目目录，再询问用户开发文档路径。
+6. 项目路径对外只有一个概念；如果用户输入的项目路径不存在，就把它视为准备创建的新项目目录，不要再单独追问“新项目路径”。
+7. 在目标仓库根目录创建或刷新 `.helloloop/`，至少维护 `backlog.json`、`project.json`、`status.json`、`STATE.md` 与 `runs/`。
+8. 如果用户给了开发文档但无法定位项目仓库，或者给了项目路径但无法定位开发文档，必须停下来询问用户，而不是猜测。
+9. 如果当前项目目录已存在，但分析认为它与开发文档目标明显冲突，必须先明确提示用户，并确认是继续现有项目、还是清理后按文档重建。
+10. 在真正执行开发前，必须输出一份中文执行确认单，至少包含：
    - 路径判断与判断依据
    - 本次命令补充输入
    - 需求语义理解
@@ -29,7 +31,9 @@ argument-hint: [PATH]
    - 首个待执行任务
    - 验证命令预览
    - 自动执行停止条件
-10. 未经用户确认，不要开始正式修改代码。
-11. 用户确认后，使用 Claude Code 的原生工具持续推进 backlog，直到开发文档的最终目标完成，且相关测试、验证、验收都已通过；遇到硬阻塞或需要用户补充关键信息时再停下。
-12. 始终优先使用安全 shell 与原生文件工具；在 Windows 上避免危险的嵌套命令、路径拼接删除和 `cmd` 风格破坏性命令。
-13. 不要调用外部 `npx helloloop` 来替代这个原生工作流；你现在就在 HelloLoop 的 Claude Code 原生模式中。
+11. 未经用户确认，不要开始正式修改代码。
+12. 用户确认后，使用当前确认的执行引擎原生工具持续推进 backlog；每个任务完成后还要再做任务完成复核，backlog 清空后还要再做主线终态复核，直到开发文档的最终目标完成，且相关测试、验证、验收都已通过；遇到硬阻塞或需要用户补充关键信息时再停下。
+13. 如果当前引擎在运行中遇到 400、鉴权、余额、429、5xx、网络抖动、流中断或长时间卡死，必须优先按无人值守策略做同引擎“健康探测 + 条件恢复”，不要中途停下来询问用户，也不要自动切换引擎；只有自动恢复额度真正用尽时才停止。
+14. 用户需求明确且当前任务可直接完成时，必须一次性完成本轮应交付的全部工作；禁止做一半后用“如果你要”“是否继续”之类的话术停下，也禁止用“希望这对你有帮助”等套话收尾。
+15. 始终优先使用安全 shell 与原生文件工具；在 Windows 上避免危险的嵌套命令、路径拼接删除和 `cmd` 风格破坏性命令。
+16. 不要调用外部 `npx helloloop` 来替代这个原生工作流；你现在就在 HelloLoop 的 Claude Code 原生模式中。

package/hosts/claude/marketplace/plugins/helloloop/skills/helloloop/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: helloloop
-description: 当用户希望 Claude Code 按开发文档先分析当前进度，再展示确认单，并在确认后持续接续开发时使用。
+description: 仅当用户显式调用 `/helloloop`，或明确要求使用 HelloLoop 时，Claude Code 才按开发文档先分析当前进度，再展示确认单，并在确认后持续接续开发。
 ---
 
 # HelloLoop for Claude Code
@@ -9,21 +9,28 @@ description: 当用户希望 Claude Code 按开发文档先分析当前进度，
 
 ## 默认流程
 
+0. 仅在用户显式调用 `/helloloop`，或明确要求使用 HelloLoop 时才介入；不要接管普通 Claude 会话
 1. 自动识别目标仓库与开发文档
-2. 分析当前代码与文档目标之间的真实进度和偏差
-3. 在目标仓库根目录创建或刷新 `.helloloop/`
-4. 输出中文执行确认单
-5. 用户确认后，继续用 Claude Code 原生工具接续开发、测试和验收，直到最终目标完成
+2. 如果用户未明确指定执行引擎，先确认本轮引擎；`Claude` 只作为推荐项，不自动选中；如果用户明确要求改用 `Codex` / `Gemini`，先确认再切换
+3. 分析当前代码与文档目标之间的真实进度和偏差
+4. 在目标仓库根目录创建或刷新 `.helloloop/`
+5. 输出中文执行确认单
+6. 用户确认后，继续用当前确认的执行引擎原生工具接续开发、测试和验收；每个任务完成后都要复核任务是否真正闭合，backlog 清空后还要复核主线目标是否真正闭合，直到最终目标完成
 
 ## 关键规则
 
+- 未显式调用 `helloloop` 且用户也没有明确要求使用 HelloLoop 时，不允许接管普通 Claude 会话。
 - 如果缺少目标仓库或开发文档，必须停下来询问用户。
 - 如果当前目录没有明确开发文档，应先展示顶层文档文件、顶层目录和疑似项目目录，再询问文档路径。
 - 项目路径对外只有一个概念；如果用户提供的项目路径不存在，直接按新项目路径处理，不要再追问“新项目路径”。
 - 如果当前项目与开发文档目标明显冲突，必须先确认是继续现有项目、清理后重建，还是取消。
+- 如果当前引擎在运行中遇到 400、鉴权、余额、429、5xx、网络抖动、流中断或长时间卡死，必须优先按无人值守策略做同引擎“健康探测 + 条件恢复”，不要中途停下来询问用户，也不要自动切换引擎。
+- 只有识别为 400 请求错误、登录/鉴权/订阅问题、本地 CLI 缺失或权限错误等硬阻塞时，才允许结束本轮自动执行。
 - 不允许跳过执行确认单直接开始正式开发。
 - 不允许把开发文档整体压成一个大任务；需要输出足够细的 backlog。
 - 代码是事实源，开发文档是目标源。
+- 不允许因为执行引擎一句“已完成”就直接结束；必须经过任务复核和主线终态复核。
+- 用户需求明确且当前任务可直接完成时，必须一次性完成本轮应交付的全部工作；禁止做一半后用“如果你要”“是否继续”之类的话术停下，也禁止用客套套话收尾。
 - 遇到失败、阻塞、依赖未满足或风险超出自动阈值时，必须明确说明当前状态。
 
 ## `.helloloop/` 最低要求

package/hosts/gemini/extension/GEMINI.md

@@ -8,22 +8,29 @@
 
 ## 默认流程
 
+0. 仅在用户显式调用 `/helloloop`，或明确要求使用 HelloLoop 时才介入；不要接管普通 Gemini 会话
 1. 自动识别项目仓库与开发文档
-2. 如果当前目录没有明确开发文档，先展示顶层文档文件、顶层目录和疑似项目目录，再询问文档路径
-3. 项目路径对外只有一个概念；若用户输入的路径不存在，直接按新项目路径处理
-4. 分析当前代码与开发文档的差距，并判断当前项目与文档目标是否匹配
-5. 在目标仓库根目录创建或刷新 `.helloloop/`
-6. 输出中文执行确认单（含路径判断、语义理解、项目匹配判断）
-7. 若当前项目与开发文档目标明显冲突，先确认是继续现有项目还是清理后重建
-8. 用户确认后，再继续执行后续开发任务，直到最终目标完成且测试、验收全部通过
+2. 如果用户未明确指定执行引擎，先确认本轮引擎；`Gemini` 只作为推荐项，不自动选中；如果用户明确要求改用 `Codex` / `Claude`，先确认再切换
+3. 如果当前目录没有明确开发文档，先展示顶层文档文件、顶层目录和疑似项目目录，再询问文档路径
+4. 项目路径对外只有一个概念；若用户输入的路径不存在，直接按新项目路径处理
+5. 分析当前代码与开发文档的差距，并判断当前项目与文档目标是否匹配
+6. 在目标仓库根目录创建或刷新 `.helloloop/`
+7. 输出中文执行确认单（含路径判断、执行引擎、语义理解、项目匹配判断）
+8. 若当前项目与开发文档目标明显冲突，先确认是继续现有项目还是清理后重建
+9. 用户确认后，再继续执行后续开发任务；每个任务完成后复核任务是否真正闭合，backlog 清空后再复核主线目标是否真正闭合，直到最终目标完成且测试、验收全部通过
 
 ## 强制规则
 
+- 未显式调用 `helloloop` 且用户也没有明确要求使用 HelloLoop 时，不允许接管普通 Gemini 会话。
 - 代码是事实源，开发文档是目标源。
 - 开发前必须先输出执行确认单。
 - 如果无法识别目标仓库或开发文档，必须停下来询问用户。
 - 不要单独追问“新项目路径”；项目路径只需要用户给一次。
 - 如果识别到偏差修正任务，优先收口偏差，再推进后续 backlog。
+- 如果当前引擎在运行中遇到 400、鉴权、余额、429、5xx、网络抖动、流中断或长时间卡死，必须优先按无人值守策略做同引擎“健康探测 + 条件恢复”，不要中途停下来询问用户，也不要自动切换引擎。
+- 只有识别为 400 请求错误、登录/鉴权/订阅问题、本地 CLI 缺失或权限错误等硬阻塞时，才允许结束本轮自动执行。
+- 不允许因为执行引擎一句“已完成”就直接结束；必须经过任务复核和主线终态复核。
+- 用户需求明确且当前任务可直接完成时，必须一次性完成本轮应交付的全部工作；禁止做一半后用“如果你要”“是否继续”之类的话术停下，也禁止用客套套话收尾。
 - 真正执行前确认，真正结束前验证。
 
 ## Windows 安全