helloloop 0.2.1 → 0.6.1

package/README.md

@@ -1,414 +1,433 @@
 # HelloLoop
 
-`HelloLoop` 是一个面向 `Codex CLI`、`Claude Code`、`Gemini CLI` 的多宿主开发工作流插件，用来把“根据开发文档持续接续开发”变成一条可分析、可确认、可验证、可追踪的标准流程。
+`HelloLoop` 是一个面向 `Codex CLI`、`Claude Code`、`Gemini CLI` 的多宿主开发工作流插件，用来把“根据开发文档持续接续开发、测试、验收，直到最终目标完成”收敛成一条统一、可确认、可追踪的标准流程。
 
-它有两层定位：
+它的核心原则很简单：
 
-- `Codex CLI`：首发平台、参考实现、最佳体验路径
-- `Claude Code` / `Gemini CLI`：各自按原生 agent 逻辑执行，但共享同一套 `.helloloop/` 工作流规范
+- 三家都能安装、都能用、都按各自原生 agent 逻辑执行
+- `Codex CLI` 仍然是首发平台、参考实现和最佳体验路径
+- 运行状态统一写入目标仓库根目录的 `.helloloop/`
+- 真正执行前先分析、先确认，执行中不静默失败、不静默切换
 
-Codex 路径的主工作流只有两种 CLI 入口：
+## 宿主与执行引擎
+
+`HelloLoop` 区分两个概念：
+
+- **宿主**：你从哪里进入，例如终端、`Codex`、`Claude`、`Gemini`
+- **执行引擎**：真正负责本轮分析 / 开发 / 测试推进的 CLI
+
+这意味着：
+
+- 无论在终端还是在 `Codex` / `Claude` / `Gemini` 宿主内，只要用户未明确指定引擎，`HelloLoop` 都会先询问本轮执行引擎
+- 当前宿主、项目历史、用户历史只作为推荐依据，不会自动替你选中引擎
+- 如果你已经显式指定，或已经在首轮确认中明确选定了引擎，本轮就固定按该引擎执行
+- 如果后续因为登录、配额、限流等问题需要改用别的引擎，`HelloLoop` 也会先询问，不会静默切换
+
+## 支持矩阵
+
+| 宿主 | 安装方式 | 原生入口 | 说明 |
+| --- | --- | --- | --- |
+| `Codex CLI` | `helloloop install` / `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 |
+
+## 最短使用方式
+
+推荐先记住下面四种：
 
 ```bash
 npx helloloop
 npx helloloop <PATH>
+npx helloloop claude
+npx helloloop gemini <PATH> 接续完成剩余开发
 ```
 
-无论从哪个宿主进入，`HelloLoop` 都遵循同一条主线：
+其中：
 
-1. 自动识别项目仓库与开发文档
-2. 分析当前代码与文档目标的真实差距
-3. 生成或刷新目标仓库根目录下的 `.helloloop/`
-4. 输出中文执行确认单
-5. 用户确认后，继续按当前宿主的原生 agent 逻辑推进开发、测试和验收
+- `<PATH>` 可以是项目仓库路径、开发文档目录、开发文档文件
+- 命令后可以继续追加自然语言要求
+- 不确定时，优先只输入 `npx helloloop`
 
-## 目录
+## 执行引擎选择规则
 
-- [核心流程](#核心流程)
-- [支持矩阵](#支持矩阵)
-- [安装](#安装)
-- [快速开始](#快速开始)
-- [自动发现规则](#自动发现规则)
-- [自动执行边界](#自动执行边界)
-- [Doctor 检查](#doctor-检查)
-- [命令速查](#命令速查)
-- [状态目录](#状态目录)
-- [Skill 用法](#skill-用法)
-- [在 Codex 中使用](#在-codex-中使用)
-- [跨平台与安全](#跨平台与安全)
-- [仓库结构](#仓库结构)
-- [许可证](#许可证)
+执行规则如下：
 
-## 核心流程
+1. 命令首参数显式引擎：`codex` / `claude` / `gemini`
+2. 自然语言中明确且不歧义地指定了引擎
+3. 如果前两步仍未明确，先停下来询问本轮执行引擎；当前宿主、项目上次 / 默认、用户上次 / 默认只作为推荐依据
+4. `-y` / `--yes` 等非交互模式下，如果你没有显式指定引擎，`HelloLoop` 会直接停止并要求补充引擎
 
-`HelloLoop` 的默认流程固定为 5 步：
+补充说明：
 
-1. 自动发现项目仓库与开发文档
-2. 对比文档目标与当前代码，识别当前进度和偏差
-3. 生成或刷新目标仓库根目录下的 `.helloloop/`
-4. 输出执行确认单，明确展示仓库、文档、当前进度、待办任务、验证命令和执行边界
-5. 用户确认后，自动推进后续开发、测试和验收，直到全部完成或遇到硬阻塞
+- 首参只有第一个裸词会被解释为引擎；如果你真要把 `claude` 当目录名，请写成 `./claude`、`.\claude` 或绝对路径
+- 命令后的自然语言如果明确提到 `codex`、`claude`、`gemini`，也会纳入意图判断
+- 当前宿主、项目历史、用户历史不会触发自动选中，只会影响“推荐项”
+- `已安装` 不等于 `可继续执行`；如果当前引擎在运行中遇到 429、5xx、网络抖动、流中断、长时间卡死等问题，`HelloLoop` 会先按无人值守策略做同引擎自动恢复，不会中途停下来询问
 
-如果分析识别出偏差修正任务，`HelloLoop` 会优先先收口偏差，再继续后面的开发任务。
+## 默认工作流
 
-工作流统一，但执行器分为两类：
+无论从哪个宿主进入，都遵循同一条主线：
 
-- `Codex CLI`：通过 `npx helloloop` / `$helloloop` 进入，使用当前仓库内的 Node CLI 与 Codex 插件链路
-- `Claude Code` / `Gemini CLI`：通过 `/helloloop` 进入，使用各自原生插件 / 扩展与 agent 工具链
+1. 自动识别目标项目仓库与开发文档
+2. 分析当前代码进度、偏差和项目匹配性
+3. 在目标仓库根目录创建或刷新 `.helloloop/`
+4. 输出中文执行确认单
+5. 用户确认后，按选中的执行引擎持续推进开发、测试、验收
+6. 每个任务完成后，自动做一次“任务完成复核”
+7. backlog 暂时清空后，自动做一次“主线终态复核”
 
-## 支持矩阵
+如果分析发现当前实现已经偏离开发文档，`HelloLoop` 会优先先收口偏差，再继续后面的 backlog。
 
-| 宿主 | 安装方式 | 原生使用入口 | 当前定位 |
-| --- | --- | --- | --- |
-| `Codex CLI` | `helloloop install --host codex` | `$helloloop` / `npx helloloop` | 首发平台、参考实现、最佳体验 |
-| `Claude Code` | `helloloop install --host claude` | `/helloloop` | Claude 原生插件工作流 |
-| `Gemini CLI` | `helloloop install --host gemini` | `/helloloop` | Gemini 原生扩展工作流 |
+这意味着：
 
-如果你希望一次性装好三家宿主：
+- 不会因为执行引擎自己一句“已完成”就直接结束
+- 如果只是部分完成，`HelloLoop` 会继续当前主线任务，而不是跳去做模型随口建议的别的事
+- 如果 backlog 清空了，但主线终态复核仍发现文档目标还有缺口，`HelloLoop` 会自动重新分析并继续推进
+- 如果模型只做了一半就想停下来给“下一步建议”，`HelloLoop` 会优先按主线目标继续推进，而不是把半成品当完成
 
-```bash
-npx helloloop install --host all
-```
+## 无人值守恢复
 
-## 安装
+`HelloLoop` 的设计目标不是“跑一轮停一轮”，而是启动前确认一次，启动后持续无人值守推进。
 
-### npm / npx
+因此运行中的默认策略是：
 
-默认安装 `Codex` 宿主：
+- 普通运行故障不再中途提问：不会因为 429、5xx、网络抖动、结果流中断、短时空输出就停下来问用户
+- 同引擎优先恢复：默认不会自动切换引擎，也不会偷偷改用别的 CLI
+- 保留主线上下文恢复：同引擎恢复时会生成恢复记录与恢复 prompt，要求新一轮执行直接基于当前仓库状态继续，而不是从头另起一套
+- 定时心跳检查：运行中会持续写入心跳与恢复状态，用于判断当前阶段是否还在正常推进
+- 先预警再终止：默认每 60 秒刷新一次心跳；若长时间没有可见进展，先标记为疑似卡住；达到更长的自动恢复阈值后，才会终止当前进程并做同引擎恢复
+- 硬错误直接停止：如果识别为 400 请求错误、登录/鉴权/订阅问题、本地 CLI 缺失或权限错误，不会盲目重试
 
-```bash
-npx helloloop install --codex-home <CODEX_HOME>
-```
+默认恢复节奏：
 
-安装到指定宿主：
+- 心跳间隔：60 秒
+- 疑似卡住预警：15 分钟无可见进展
+- 自动恢复阈值：45 分钟无可见进展
+- 同阶段最多自动恢复：4 次
+- 恢复等待：2 分钟 → 5 分钟 → 15 分钟 → 30 分钟
 
-```bash
-npx helloloop install --host codex
-npx helloloop install --host claude
-npx helloloop install --host gemini
-npx helloloop install --host all
-```
+如果你明确指定或确认了本轮引擎，`HelloLoop` 在自动恢复阶段也会继续锁定该引擎，不会擅自切换。
 
-可选 home 参数：
+## 自动发现与交互逻辑
 
-```bash
---codex-home <CODEX_HOME>
---claude-home <CLAUDE_HOME>
---gemini-home <GEMINI_HOME>
-```
+### 1. 只输入 `npx helloloop`
 
-### 源码仓库
+如果你只输入：
 
 ```bash
-node ./scripts/helloloop.mjs install --codex-home <CODEX_HOME>
+npx helloloop
 ```
 
-Windows PowerShell 也可以直接运行：
+`HelloLoop` 会先明确执行引擎，再快速扫描当前目录：
 
-```powershell
-pwsh -NoLogo -NoProfile -File .\scripts\install-home-plugin.ps1 -CodexHome <CODEX_HOME>
-```
+- 当前目录本身就是项目仓库或开发文档目录时，直接进入分析
+- 当前目录更像工作区时，优先利用顶层文档，再提示选择候选项目目录
+- 当前目录没有明确开发文档时，不会直接报错，而是先列出：
+  - 顶层文档文件
+  - 顶层目录
+  - 疑似项目目录
+  然后再询问开发文档路径
 
-安装完成后：
+### 2. 项目路径只问一次
 
-- Codex 会写入 `<CODEX_HOME>/plugins/helloloop`
-- Claude 会写入 `<CLAUDE_HOME>/plugins/marketplaces/helloloop-local`，并生成 `<CLAUDE_HOME>/plugins/cache/helloloop-local/helloloop/<VERSION>`
-- Gemini 会写入 `<GEMINI_HOME>/extensions/helloloop`
+对外只有“项目路径”这一个概念：
 
-如果你想在安装后做一次全宿主环境检查：
+- 输入已有目录 → 按现有项目继续分析
+- 输入不存在的目录 → 视为准备创建的新项目目录
 
-```bash
-npx helloloop doctor --host all
-```
+不会再额外追问一个“新项目路径”。
 
-## 快速开始
+### 3. 文档和项目缺一不可时会停下询问
 
-### 1. 选择宿主入口
+以下情况不会硬猜：
 
-```text
-Codex   -> $helloloop / npx helloloop
-Claude  -> /helloloop
-Gemini  -> /helloloop
-```
+- 给了开发文档，但无法定位项目仓库
+- 给了项目路径，但无法定位开发文档
+- 同时出现多个冲突的文档路径或项目路径
 
-说明：
+### 4. 命令 + 自然语言会一起分析
 
-- `Codex` 路径下，`$helloloop` 与 `npx helloloop` 对齐同一主流程
-- `Claude` 与 `Gemini` 路径下，`/helloloop` 会走各自原生 agent 执行逻辑
-- 三家都会维护同一个 `.helloloop/` 状态目录规范
+`HelloLoop` 不依赖固定中文关键词做硬编码分流。
 
-### 2. 进入项目仓库或开发文档目录
+命令里的：
 
-最短命令：
+- 显式路径
+- 中文自然语言
+- 英文自然语言
+- 其他语言的补充要求
 
-```bash
-npx helloloop
-```
+都会一起进入分析和确认单，不会因为语言不同被静默忽略。
 
-如果你只知道一个路径，也可以只传一个：
+### 5. 现有项目与文档目标冲突时
 
-```bash
-npx helloloop <PATH>
-```
+如果当前项目目录已存在，但分析认为它与开发文档目标明显冲突，`HelloLoop` 不会直接清空目录，而是先提示你选择：
 
-这里的 `<PATH>` 可以是：
+1. 继续在当前项目上尝试接续
+2. 清理当前项目内容后按文档目标重建
+3. 取消本次执行
 
-- 项目仓库路径
-- 开发文档目录
-- 开发文档文件
+如果你明确希望非交互模式下直接重建，可以使用：
 
-### 3. 查看执行确认单
+```bash
+npx helloloop --rebuild-existing
+```
 
-分析完成后，`HelloLoop` 会展示一份执行确认单，至少包含：
+## 执行确认单
 
-- 识别出的目标仓库
-- 识别出的开发文档
-- 当前进度摘要
+真正开始开发前，`HelloLoop` 会先输出中文执行确认单，至少包含：
+
+- 路径判断与判断依据
+- 本次命令补充输入
+- 执行引擎
+- 需求语义理解
+- 项目匹配判断
+- 目标仓库
+- 开发文档
+- 当前进度
 - 已实现事项
 - 待完成事项
 - 任务统计
 - 首个待执行任务
 - 验证命令预览
-- 自动推进边界
+- 自动执行停止条件
 
-### 4. 确认后自动继续执行
+未确认前，不会正式修改代码。
 
-你确认后，`HelloLoop` 会：
+确认后，默认行为不是“跑一轮就停”，而是：
 
-- 按 backlog 顺序自动推进
-- 每个任务都走当前宿主的原生 agent 执行与验证
-- 遇到失败、风险超阈值、依赖未满足或环境硬阻塞时立即停下
-- 把分析结果、状态和运行记录都写进目标仓库的 `.helloloop/`
+- 先按 backlog 执行当前颗粒度任务
+- 每个任务完成后复核其验收是否真的闭合
+- backlog 清空后再复核一次整个主线目标
+- 只有“任务验收闭合 + 主线目标闭合 + 验证通过”才算真正结束
+- 运行中若出现可恢复的 CLI 故障，则按无人值守策略自动恢复，不打断主线
 
-如果你已经做了全局安装，也可以把 `npx helloloop` 简写成 `helloloop`。
+## 安装
 
-如果你想手动查看或接管某一步，也可以使用：
+### 通过 npm / npx
+
+默认安装到 `Codex`：
 
 ```bash
-npx helloloop status
-npx helloloop next
-npx helloloop run-once
+npx helloloop install
+npx helloloop install --codex-home <CODEX_HOME>
 ```
 
-## 自动发现规则
+安装到指定宿主：
 
-- 不传路径：默认分析当前目录
-- 只传一个路径：自动判断它是仓库路径还是开发文档路径
-- 当前目录是仓库：自动查找开发文档
-- 当前目录是文档目录：自动尝试反推目标仓库
-- 只给开发文档但无法推断仓库：停止并提示补充 `--repo`
-- 只给仓库但找不到开发文档：停止并提示补充 `--docs`
+```bash
+npx helloloop install --host codex
+npx helloloop install --host claude
+npx helloloop install --host gemini
+npx helloloop install --host all
+```
 
-推荐始终优先使用：
+可选 home 参数：
 
 ```bash
-npx helloloop
-npx helloloop <PATH>
+--codex-home <CODEX_HOME>
+--claude-home <CLAUDE_HOME>
+--gemini-home <GEMINI_HOME>
 ```
 
-只有自动发现无法收敛时，再补充高级参数：
+### 从源码仓库安装
 
 ```bash
-npx helloloop --repo <REPO_ROOT> --docs <DOCS_PATH>
+node ./scripts/helloloop.mjs install --host codex
 ```
 
-## 自动执行边界
+Windows PowerShell 也可以直接运行：
 
-默认主命令会在确认后尽量自动完成整轮 backlog，而不是只跑一个任务。
+```powershell
+pwsh -NoLogo -NoProfile -File .\scripts\install-home-plugin.ps1 -CodexHome <CODEX_HOME>
+```
 
-### 常用执行模式
+### 升级、重装、切换分支
 
 ```bash
-npx helloloop
-npx helloloop <PATH>
-npx helloloop --dry-run
-npx helloloop -y
+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
 ```
 
-含义如下：
+说明：
 
-- `npx helloloop`：分析 → 展示确认单 → 等待你确认 → 自动执行
-- `npx helloloop <PATH>`：同上，但先用你给的单一路径做自动识别
-- `npx helloloop --dry-run`：只分析并输出确认单，不真正开始执行
-- `npx helloloop -y`：跳过交互确认，分析后直接自动执行
+- `--force` 会清理当前宿主里旧分支 / 旧版本残留的 `helloloop` 安装目录后再重装
+- `Codex` 会刷新插件目录和 marketplace 条目
+- `Claude` 会刷新 marketplace、缓存插件目录，以及 `settings.json` / `known_marketplaces.json` / `installed_plugins.json` 中的 `helloloop` 条目
+- `Gemini` 会刷新 `extensions/helloloop/`，不会动同目录下其他扩展
 
-### 停止条件
+### 卸载
 
-出现以下情况时，`HelloLoop` 会停止并保留现场，而不是静默降级：
+```bash
+npx helloloop uninstall --host codex
+npx helloloop uninstall --host claude
+npx helloloop uninstall --host gemini
+npx helloloop uninstall --host all
+```
 
-- 无法自动确定目标仓库或开发文档
-- backlog 已存在失败任务、阻塞任务或未满足依赖
-- 后续任务风险超出自动阈值，且你没有显式加 `--allow-high-risk`
-- 验证命令失败
-- 当前宿主 CLI、插件资产或 shell 环境不可安全执行
+卸载是定向清理：
 
-## Doctor 检查
+- 只删除 `helloloop` 自己的安装目录和注册条目
+- 不会顺带删除别的插件、marketplace、扩展或自定义配置
+- 即使某个宿主当前未安装 `helloloop`，也会安全退出，不做破坏性清理
 
-你可以用 `doctor` 检查当前宿主是否已具备基本运行条件。
+## 使用入口
 
-### 只检查 Codex
+### 终端
 
 ```bash
-npx helloloop doctor
+npx helloloop
+npx helloloop <PATH>
+npx helloloop codex <PATH>
+npx helloloop claude <PATH>
+npx helloloop gemini <PATH> <补充说明>
 ```
 
-### 检查全部宿主
+如果已经做了全局安装，也可以把 `npx helloloop` 简写为 `helloloop`。是否立刻可用取决于当前 shell 是否已经刷新 `PATH`。
 
-```bash
-npx helloloop doctor --host all
+### Codex CLI
+
+```text
+$helloloop
+helloloop:helloloop
 ```
 
-### 检查已安装目录
+在 `Codex` 中也可以直接执行：
 
 ```bash
-npx helloloop doctor --host all --codex-home <CODEX_HOME> --claude-home <CLAUDE_HOME> --gemini-home <GEMINI_HOME>
+npx helloloop
 ```
 
-`doctor` 当前可检查：
+如果你在 `Codex` 中直接使用 `$helloloop` 或 `npx helloloop`，但没有明确指定引擎，`HelloLoop` 仍会先让你确认本轮引擎；`Codex` 只会作为推荐项，不会被自动选中。
 
-- 宿主 CLI 是否存在
-- 本地运行时资产是否齐全
-- 目标仓库 `.helloloop/` 基础文件是否存在
-- 已安装宿主目录是否已写入对应插件 / 扩展
+### Claude Code / Gemini CLI
 
-## 命令速查
+```text
+/helloloop
+```
+
+它们会按各自 CLI 的原生 agent 逻辑执行，但共享同一套 `.helloloop/` 工作流规范。
+
+## 常用命令
 
 | 命令 | 作用 |
 | --- | --- |
-| `analyze` | 主工作流；分析并输出确认单，确认后自动接续执行 |
-| `status` | 查看 backlog 汇总与当前状态 |
-| `next` | 预览下一任务，不真正执行 |
-| `run-once` | 手动执行一个任务 |
-| `run-loop` | 手动连续执行多个任务 |
-| `doctor` | 检查所选宿主、运行时资产与目标仓库是否满足运行条件 |
+| `helloloop` / `analyze` | 自动分析、展示确认单，并在确认后持续接续开发，直到主线目标闭合或遇到硬阻塞 |
+| `install` | 安装运行时 bundle 到指定宿主 |
+| `uninstall` | 从指定宿主卸载运行时 bundle 与注册信息 |
+| `doctor` | 检查宿主环境、插件资产与目标仓库状态 |
 | `init` | 手动初始化 `.helloloop/` 模板 |
-| `install` | 安装插件到所选宿主目录 |
+| `status` | 查看 backlog 摘要和当前状态 |
+| `next` | 生成下一任务的干跑预览 |
+| `run-once` | 执行一个任务 |
+| `run-loop` | 连续执行多个任务 |
 
-### 常用选项
+常用选项：
 
-| 选项 | 说明 |
+| 选项 | 作用 |
 | --- | --- |
-| `-y`, `--yes` | 跳过交互确认，分析后直接开始执行 |
-| `--dry-run` | 只分析并输出确认单，不真正开始执行 |
-| `--host <name>` | 选择安装宿主：`codex`、`claude`、`gemini`、`all` |
-| `--repo <dir>` | 高级选项：显式指定项目仓库根目录 |
-| `--docs <dir\|file>` | 高级选项：显式指定开发文档目录或文件 |
-| `--allow-high-risk` | 允许执行 `medium` 及以上风险任务 |
-| `--max-tasks <n>` | 限制手动 `run-loop` 的最大任务数 |
-| `--max-attempts <n>` | 单策略最大重试次数 |
-| `--max-strategies <n>` | 单任务最大换路次数 |
-| `--required-doc <path>` | 追加全局必读文档 |
-| `--constraint <text>` | 追加全局实现约束 |
-| `--codex-home <dir>` | 指定 Codex Home |
-| `--claude-home <dir>` | 指定 Claude Home |
-| `--gemini-home <dir>` | 指定 Gemini Home |
-| `--config-dir <dir>` | 指定状态目录名，默认 `.helloloop` |
-| `--force` | 覆盖已有安装目录 |
-
-## 状态目录
-
-`HelloLoop` 始终把运行状态写入目标仓库根目录，而不是插件目录自身。
-
-默认目录：
-
-```text
-.helloloop/
-├── backlog.json
-├── policy.json
-├── project.json
-├── status.json
-├── STATE.md
-└── runs/
-```
+| `codex` / `claude` / `gemini` | 作为 `analyze` 模式的命令首参数，显式指定执行引擎 |
+| `--dry-run` | 只分析并输出确认单，不开始自动执行 |
+| `-y` / `--yes` | 跳过执行确认直接开始；但如果未显式指定引擎，会直接报错而不是自动选引擎 |
+| `--repo <dir>` | 高级覆盖：显式指定项目仓库 |
+| `--docs <dir|file>` | 高级覆盖：显式指定开发文档 |
+| `--rebuild-existing` | 项目与文档冲突时，自动清理现有项目后重建 |
+| `--host <name>` | 安装宿主：`codex` / `claude` / `gemini` / `all` |
+| `--config-dir <dir>` | 状态目录名，默认 `.helloloop` |
 
-其中：
+手动控制示例：
 
-- `backlog.json`：分析后生成的任务队列
-- `policy.json`：自动推进策略、重试上限和 Codex 参数
-- `project.json`：开发文档入口和全局约束
-- `status.json`：最近一次运行状态
-- `STATE.md`：面向人的进度摘要
-- `runs/`：提示词、stdout、stderr、验证日志等留痕
+```bash
+npx helloloop status
+npx helloloop next
+npx helloloop run-once
+```
 
-## Skill 用法
+## Doctor
 
-如果你已经把 `HelloLoop` 安装成 Codex 插件，也可以直接在 Codex 里调用：
+检查默认宿主：
 
-```text
-$helloloop
+```bash
+npx helloloop doctor
 ```
 
-或：
+检查全部宿主：
 
-```text
-helloloop:helloloop
+```bash
+npx helloloop doctor --host all
 ```
 
-此时推荐理解为：
-
-- `$helloloop` 是插件入口
-- `npx helloloop` / `npx helloloop <PATH>` 是实际执行入口
+检查指定安装目录：
 
-也就是说，用户显式调用 `$helloloop` 时，目标行为应当与主命令保持一致：
+```bash
+npx helloloop doctor --host all --codex-home <CODEX_HOME> --claude-home <CLAUDE_HOME> --gemini-home <GEMINI_HOME>
+```
 
-1. 先自动识别仓库和开发文档
-2. 再分析当前代码与文档目标
-3. 再展示执行确认单
-4. 最后在你确认后自动接续执行
+## 宿主写入范围
 
-如果当前目录无法判断目标仓库、缺少开发文档，或者你明确只想先讲解不执行，`HelloLoop` 才应该先停下来问你，而不是直接启动执行。
+为了方便排查安装 / 更新 / 卸载问题，下面是默认写入位置：
 
-如果你安装的是 Claude 或 Gemini 宿主，则推荐直接使用：
+### `Codex CLI`
 
-```text
-/helloloop
-```
+- 插件目录：`~/.codex/plugins/helloloop/`
+- 注册文件：`~/.codex/.agents/plugins/marketplace.json`
 
-它们会按各自 CLI 的原生 agent 逻辑执行，但共享同一套 `.helloloop/` 工作流规范。
+### `Claude Code`
 
-## 在 Codex 中使用
+- 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`
 
-可以直接在当前 Codex 会话里运行：
+### `Gemini CLI`
 
-```bash
-npx helloloop
-```
+- 扩展目录：`~/.gemini/extensions/helloloop/`
 
-不需要重开终端。
+`HelloLoop` 只维护自己的目录和自己的注册项，不会重写别的插件条目。
 
-如果你使用的是全局安装后的 `helloloop` 短命令，是否立刻可用取决于当前 shell 是否已经刷新 PATH。
+## `.helloloop/` 状态目录
 
-安装为 Codex 插件后，推荐显式使用的 skill 名称是：
+`HelloLoop` 的 backlog、状态和运行记录始终写入目标仓库根目录下的：
 
 ```text
-helloloop:helloloop
+.helloloop/
+├── backlog.json
+├── policy.json
+├── project.json
+├── status.json
+├── STATE.md
+└── runs/
 ```
 
-## 跨平台与安全
-
-`HelloLoop` 默认兼容 Windows、macOS 和 Linux。
+不会写回插件目录自身。
 
-### shell 策略
+## 跨平台与安全
 
-- Windows：`pwsh` → `bash`（如 Git Bash）→ `powershell`
-- macOS / Linux：`bash` → `sh`
-- Windows 不会回退到 `cmd.exe`
+### Windows
 
-说明：
+- 优先使用 `pwsh`
+- 也支持 `bash`（如 Git Bash）与 `powershell`
+- 不回退到 `cmd.exe`
+- 避免危险的嵌套命令、路径拼接删除和 `cmd` 风格破坏性流程
 
-- `Codex` 路径由当前 Node CLI 严格控制 shell 选择
-- `Claude` / `Gemini` 路径走各自原生插件 / 扩展，但仍应遵守 `HelloLoop` 的安全约束
+### macOS / Linux
 
-### 内建兜底规则
+- 优先使用 `bash`
+- 如果没有 `bash`，回退到 `sh`
 
-当开发文档没有给出足够约束时，`HelloLoop` 会自动附加一层最低安全边界，包括但不限于：
+### 通用安全边界
 
-- 代码是事实源
-- 验证必须执行
-- 不能静默失败
-- 不能吞掉错误
-- 危险命令必须阻断
-- 路径与 shell 调用必须按跨平台安全方式执行
+- 不静默失败
+- 不静默回退
+- 不静默切换执行引擎
+- 不吞掉错误
+- 真正执行前先确认
+- 真正结束前先验证
+- 不轻信执行引擎口头“已完成”
+- 不接受“先做一半再停下来问要不要继续”
 
 ## 仓库结构
 
@@ -416,6 +435,8 @@ helloloop:helloloop
 helloloop/
 ├── .claude-plugin/
 ├── .codex-plugin/
+├── .github/
+├── .helloagents/
 ├── bin/
 ├── docs/
 ├── hosts/
@@ -423,18 +444,22 @@ helloloop/
 ├── skills/
 ├── src/
 ├── templates/
-└── tests/
+├── tests/
+├── LICENSE
+├── package.json
+└── README.md
 ```
 
 其中：
 
-- `.claude-plugin/`：Claude plugin 元数据
-- `.codex-plugin/`：Codex plugin 元数据
-- `hosts/`：Claude marketplace/plugin 与 Gemini extension 的运行时资产
-- `src/`：核心实现，例如路径发现、分析提示词、任务调度、执行与安装
-- `tests/`：回归测试，覆盖 CLI、安装链路、bundle 结构和关键流程
-- `templates/`：初始化目标仓库 `.helloloop/` 时写入的模板
+- `.codex-plugin/`：Codex 插件 manifest
+- `.claude-plugin/`：Claude plugin manifest
+- `hosts/`：Claude marketplace / Gemini extension 资产
+- `skills/`：Codex 插件技能说明
+- `src/`：发现、分析、执行、安装、卸载、doctor 等核心实现
+- `templates/`：初始化目标仓库 `.helloloop/` 的模板
+- `docs/` 与 `tests/`：源码仓库维护资料，不进入运行时安装包
 
 ## 许可证
 
-`HelloLoop` 使用 `Apache-2.0`，许可证文件位于仓库根目录 `LICENSE`。
+`HelloLoop` 使用 `Apache-2.0`，许可证文件位于仓库根目录的 `LICENSE`。