helloloop 0.1.0 → 0.1.1

package/.codex-plugin/plugin.json

@@ -1,10 +1,9 @@
 {
   "name": "helloloop",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Backlog-driven continuous repository execution for Codex with verification loops and explicit skill and CLI entrypoints.",
   "author": {
-    "name": "HelloWind",
-    "url": "https://github.com/hellowind777"
+    "name": "HelloLoop"
   },
   "license": "MIT",
   "keywords": [
@@ -18,8 +17,8 @@
   "interface": {
     "displayName": "HelloLoop",
     "shortDescription": "Continuous repo execution with backlog and Ralph Loop guards",
-    "longDescription": "HelloLoop packages backlog-driven continuous development for Codex as a pure official plugin bundle. Because current Codex runtime does not load Hook manifests from plugins, this plugin intentionally drops `~helloloop` Hook mode and uses explicit skill and CLI entrypoints instead.",
-    "developerName": "HelloWind",
+    "longDescription": "HelloLoop packages backlog-driven continuous development for Codex as an official plugin bundle with explicit skill and CLI entrypoints.",
+    "developerName": "HelloLoop",
     "category": "Coding",
     "capabilities": [
       "Interactive",

package/README.md

@@ -1,100 +1,91 @@
 # HelloLoop
 
-`HelloLoop` 是一个面向 Codex 的 backlog 驱动开发插件。
+`HelloLoop` 是一个面向 Codex 的独立插件，用来把“按 backlog 持续推进仓库开发”这件事标准化、可追踪、可验证地跑起来。
 
-它把持续开发所需的任务队列、执行策略、验证命令和运行记录集中到目标仓库的 `.helloloop/` 目录里，并通过显式 CLI / skill 入口推动任务逐步落地。
+它不只是在单轮对话里改一段代码，而是把任务队列、必读文档、执行约束、验证命令和运行记录统一放进目标仓库的 `.helloloop/` 目录，让 Codex 可以按明确流程持续接续开发。
+
+命令入口按 `Node.js 20+` 设计，支持 Windows、macOS 和 Linux。
 
 ## 目录
 
 - [HelloLoop 是什么](#helloloop-是什么)
 - [核心能力](#核心能力)
 - [适用场景](#适用场景)
-- [项目结构](#项目结构)
 - [安装](#安装)
 - [快速开始](#快速开始)
-- [命令说明](#命令说明)
+- [命令速查](#命令速查)
 - [状态目录](#状态目录)
-- [任务与执行模型](#任务与执行模型)
-- [发布到 npm](#发布到-npm)
-- [验证](#验证)
+- [工作机制](#工作机制)
+- [仓库结构](#仓库结构)
 - [相关文档](#相关文档)
 
 ## HelloLoop 是什么
 
-`HelloLoop` 解决的是“让 Codex 在同一个仓库里持续推进任务”这个问题。
+`HelloLoop` 解决的是以下问题：
 
-与一次性执行单个改动不同，它围绕一份 backlog 运行：
+- 你的仓库里已经有开发文档、任务拆解或 backlog
+- 你希望 Codex 能按顺序接着做，而不是每次都从头解释背景
+- 你希望每一轮执行前都自动带上项目状态、必读文档和实现约束
+- 你希望每次运行后都留下状态记录、验证结果和运行痕迹
 
-- 先从 backlog 里选择当前最合适的任务
-- 根据项目状态、必读文档和约束生成执行提示
-- 调用 Codex 完成实现
-- 运行验证命令确认结果
-- 失败时按 Ralph Loop 思路重试或换路
-- 把状态、结果和运行产物写回目标仓库
+围绕这个目标，`HelloLoop` 提供了一套明确的仓库内执行模型：
 
-这意味着你可以把 `HelloLoop` 当成一个“面向仓库持续推进”的执行层，而不是单次脚本集合。
+1. 从 backlog 中选择当前可执行任务
+2. 汇总项目上下文、任务目标和约束
+3. 生成面向 Codex 的执行提示
+4. 调用 Codex 完成实现
+5. 执行验证命令
+6. 回写状态、日志和运行记录
 
 ## 核心能力
 
-- **插件安装**：把运行时 bundle 安装到 `~/.codex/plugins/helloloop`
-- **仓库初始化**：为目标仓库生成 `.helloloop/` 初始状态文件
-- **任务选择**：基于优先级、依赖和风险等级选择下一任务
-- **干跑预览**：先生成下一任务提示词和验证列表，再决定是否执行
-- **单轮执行**：执行一个任务并回写状态
-- **循环执行**：连续执行多个任务，直到达到上限或遇到阻塞
-- **验证联动**：优先读取任务自身验证命令，否则回退到仓库 `.helloagents/verify.yaml`
-- **运行留痕**：把每次执行的提示词、日志、验证输出保存到 `runs/`
+- **插件安装**：安装到 Codex Home，作为独立插件使用
+- **仓库初始化**：在目标仓库生成 `.helloloop/` 状态目录
+- **任务调度**：基于优先级、依赖、风险等级挑选下一任务
+- **干跑预览**：先看下一任务、提示词和验证命令，再决定是否执行
+- **单轮执行**：执行一个任务并回写结果
+- **循环执行**：连续执行多个任务，直到完成、阻塞或达到上限
+- **验证联动**：优先使用任务级验证命令，缺省时读取仓库验证配置
+- **运行留痕**：把提示词、stdout、stderr、验证输出沉淀到 `runs/`
 
 ## 适用场景
 
-- 你已经有 backlog，希望 Codex 按队列持续推进
-- 你希望每个任务执行前都自动带上项目状态和文档约束
-- 你希望执行失败后自动进入重试或换路，而不是停在一次失败
-- 你希望把任务状态、验证结果和运行痕迹沉淀在仓库内
-- 你希望通过 npm 分发这个插件，并在 GitHub Tag 发布时自动同步到 npm
-
-## 项目结构
-
-```text
-helloloop/
-├── .codex-plugin/         # Codex 插件 manifest
-├── bin/                   # npm bin 入口
-├── docs/                  # 说明文档
-├── scripts/               # CLI 安装脚本与入口
-├── skills/                # 插件技能
-├── src/                   # 核心实现
-├── templates/             # 初始化模板
-└── tests/                 # 回归测试
-```
-
-源码仓库包含 `docs/` 和 `tests/`，但安装到 Codex Home 时只会复制运行时必需文件。
+- 你有一套开发文档，希望 Codex 接续完成后续开发
+- 你有清晰 backlog，希望 AI 按队列逐项推进
+- 你希望把“任务、约束、验证、结果”都放在仓库里长期维护
+- 你希望执行失败后不是停住，而是能按既定策略继续推进
+- 你希望多人协作时，每个人都能快速看懂当前任务状态
 
 ## 安装
 
-### 方式一：通过 npm / npx 安装
+### 通过 npm / npx 安装
 
 ```powershell
-npx helloloop install --codex-home C:\Users\hellowind\.codex
+npx helloloop install --codex-home <CODEX_HOME>
 ```
 
-### 方式二：从源码仓库安装
+### 从源码仓库安装
 
 ```powershell
-pwsh -NoLogo -NoProfile -File .\scripts\install-home-plugin.ps1 -CodexHome C:\Users\hellowind\.codex
+node ./scripts/helloloop.mjs install --codex-home <CODEX_HOME>
 ```
 
-如果已存在同名安装目录，追加 `-Force` 或 `--force` 覆盖即可。
+如果你在 Windows 上更习惯 PowerShell，也可以使用：
+
+```powershell
+pwsh -NoLogo -NoProfile -File .\scripts\install-home-plugin.ps1 -CodexHome <CODEX_HOME>
+```
 
-安装完成后，运行时文件会位于：
+安装完成后，插件会被放到：
 
 ```text
-C:\Users\hellowind\.codex\plugins\helloloop
+<CODEX_HOME>\plugins\helloloop
 ```
 
-同时会自动更新：
+同时会更新：
 
 ```text
-C:\Users\hellowind\.codex\.agents\plugins\marketplace.json
+<CODEX_HOME>\.agents\plugins\marketplace.json
 ```
 
 ## 快速开始
@@ -102,44 +93,60 @@ C:\Users\hellowind\.codex\.agents\plugins\marketplace.json
 ### 1. 安装插件
 
 ```powershell
-npx helloloop install --codex-home C:\Users\hellowind\.codex
+npx helloloop install --codex-home <CODEX_HOME>
+```
+
+之后的日常命令推荐直接使用：
+
+```powershell
+npx helloloop <command> [options]
 ```
 
-### 2. 在目标仓库初始化状态目录
+如果你已经全局安装过：
 
 ```powershell
-node C:\Users\hellowind\.codex\plugins\helloloop\scripts\helloloop.mjs init --repo D:\GitHub\dev\your-repo
+helloloop <command> [options]
 ```
 
+在 Codex 当前会话里，也可以直接运行同样的 `npx helloloop ...` 命令，不需要重开终端。
+
+### 2. 在目标仓库初始化 `.helloloop/`
+
+```powershell
+npx helloloop init --repo <REPO_ROOT>
+```
+
+初始化完成后，模板会落在目标仓库根目录下的 `.helloloop/`，而不是插件目录本身。
+
 ### 3. 检查运行条件
 
 ```powershell
-node C:\Users\hellowind\.codex\plugins\helloloop\scripts\helloloop.mjs doctor --repo D:\GitHub\dev\your-repo
+npx helloloop doctor --repo <REPO_ROOT>
 ```
 
-### 4. 查看当前状态或下一任务
+### 4. 查看状态与下一任务
 
 ```powershell
-node C:\Users\hellowind\.codex\plugins\helloloop\scripts\helloloop.mjs status --repo D:\GitHub\dev\your-repo
-node C:\Users\hellowind\.codex\plugins\helloloop\scripts\helloloop.mjs next --repo D:\GitHub\dev\your-repo
+npx helloloop status --repo <REPO_ROOT>
+npx helloloop next --repo <REPO_ROOT>
 ```
 
 ### 5. 执行一个任务或连续执行
 
 ```powershell
-node C:\Users\hellowind\.codex\plugins\helloloop\scripts\helloloop.mjs run-once --repo D:\GitHub\dev\your-repo
-node C:\Users\hellowind\.codex\plugins\helloloop\scripts\helloloop.mjs run-loop --repo D:\GitHub\dev\your-repo --max-tasks 2
+npx helloloop run-once --repo <REPO_ROOT>
+npx helloloop run-loop --repo <REPO_ROOT> --max-tasks 2
 ```
 
-## 命令说明
+## 命令速查
 
 | 命令 | 作用 |
 | --- | --- |
-| `install` | 安装插件到 Codex Home，并更新 marketplace |
-| `init` | 初始化目标仓库 `.helloloop/` |
-| `doctor` | 检查 Codex CLI、模板、配置文件和插件文件是否齐备 |
-| `status` | 查看 backlog 汇总与下一任务 |
-| `next` | 干跑生成下一任务预览，不真正调用 Codex |
+| `install` | 安装插件到 Codex Home，并更新插件 marketplace |
+| `init` | 初始化目标仓库的 `.helloloop/` |
+| `doctor` | 检查 Codex、插件文件和目标仓库配置是否齐备 |
+| `status` | 查看 backlog 汇总、当前状态和下一任务 |
+| `next` | 生成下一任务预览，不真正调用 Codex |
 | `run-once` | 执行一个任务 |
 | `run-loop` | 连续执行多个任务 |
 
@@ -147,22 +154,22 @@ node C:\Users\hellowind\.codex\plugins\helloloop\scripts\helloloop.mjs run-loop
 
 | 选项 | 说明 |
 | --- | --- |
-| `--repo <dir>` | 目标仓库根目录 |
+| `--repo <dir>` | 目标仓库根目录，默认当前目录 |
 | `--codex-home <dir>` | 指定 Codex Home |
-| `--config-dir <dir>` | 自定义状态目录，默认 `.helloloop` |
+| `--config-dir <dir>` | 指定状态目录名，默认 `.helloloop` |
 | `--dry-run` | 只生成提示词和预览，不真正调用 Codex |
 | `--task-id <id>` | 指定执行某个任务 |
-| `--max-tasks <n>` | `run-loop` 最多执行多少个任务 |
-| `--max-attempts <n>` | 每种策略内最大重试次数 |
+| `--max-tasks <n>` | `run-loop` 最多执行的任务数 |
+| `--max-attempts <n>` | 每种策略的最大重试次数 |
 | `--max-strategies <n>` | 单任务最大换路次数 |
-| `--allow-high-risk` | 允许执行 `medium` / `high` / `critical` 风险任务 |
+| `--allow-high-risk` | 允许执行 `medium` 及以上风险任务 |
 | `--required-doc <path>` | 追加全局必读文档 |
 | `--constraint <text>` | 追加全局实现约束 |
-| `--force` | 覆盖安装目录 |
+| `--force` | 覆盖已有安装目录 |
 
 ### Skill 名称
 
-安装为 Codex 插件后，可通过插件命名空间使用：
+安装为 Codex 插件后，推荐显式使用：
 
 ```text
 helloloop:helloloop
@@ -170,7 +177,7 @@ helloloop:helloloop
 
 ## 状态目录
 
-`HelloLoop` 在目标仓库内默认使用 `.helloloop/` 保存执行状态。
+`HelloLoop` 默认在目标仓库根目录创建 `.helloloop/`，用来保存 backlog、策略配置、运行状态和执行留痕。
 
 典型结构如下：
 
@@ -184,151 +191,73 @@ helloloop:helloloop
 └── runs/
 ```
 
-### 各文件作用
+各文件作用如下：
 
-- `backlog.json`：任务列表、优先级、风险、验收条件、依赖关系
-- `policy.json`：循环上限、重试次数、Codex 执行参数
-- `project.json`：全局必读文档、实现约束和 planner 配置
-- `status.json`：机器可读的最近运行状态
-- `STATE.md`：给人看的当前状态摘要
-- `runs/`：每次任务执行的提示词、stdout、stderr 和验证记录
+- `backlog.json`：任务列表、优先级、风险、依赖、验收条件
+- `policy.json`：循环上限、重试策略、Codex 执行参数
+- `project.json`：全局必读文档、实现约束、任务规划提示
+- `status.json`：最近一次运行的机器可读状态
+- `STATE.md`：面向人的当前进展摘要
+- `runs/`：每次执行的提示词、日志和验证输出
 
-如果旧仓库仍保留 `.helloagents/helloloop/`，当前版本也会自动识别；你也可以显式传 `--config-dir .helloagents/helloloop`。
+## 工作机制
 
-## 任务与执行模型
+### 任务模型
 
-### backlog 任务字段
-
-`backlog.json` 中的任务通常包含这些字段：
+`backlog.json` 中的任务通常包含以下字段：
 
 - `id`：任务唯一标识
 - `title`：任务标题
-- `status`：`pending` / `in_progress` / `done` / `failed` / `blocked`
+- `status`：`pending`、`in_progress`、`done`、`failed`、`blocked`
 - `priority`：`P0` 到 `P3`
-- `risk`：`low` / `medium` / `high` / `critical`
-- `goal`：任务目标
-- `docs`：执行前必读文档
-- `paths`：主要涉及目录
+- `risk`：`low`、`medium`、`high`、`critical`
+- `goal`：本任务要达成的目标
+- `docs`：执行前必须阅读的文档
+- `paths`：本任务主要涉及的目录
 - `acceptance`：验收条件
 - `dependsOn`：依赖的上游任务
-- `verify`：任务专属验证命令（可选）
+- `verify`：任务专属验证命令
 
 ### 执行流程
 
-`HelloLoop` 的核心执行逻辑如下：
-
-1. 从 backlog 中筛出可执行任务
-2. 按优先级和依赖关系选择下一任务
-3. 读取仓库状态、必读文档和实现约束
-4. 生成 Codex 执行提示词
-5. 调用 `codex exec`
-6. 运行验证命令
-7. 成功则把任务标记为完成
-8. 失败则按 Ralph Loop 记录失败历史并继续重试或换路
+`HelloLoop` 在每一轮执行中会完成这些事情：
 
-### 风险与阻塞规则
+1. 找出当前可执行任务
+2. 读取仓库状态、任务描述和必读文档
+3. 生成清晰的 Codex 执行提示
+4. 运行 Codex 完成开发
+5. 执行验证命令
+6. 更新任务状态和运行记录
 
-- 默认只自动执行 `low` 风险任务
-- `medium` 及以上风险任务需要显式传入 `--allow-high-risk`
-- 如果存在未收束的 `in_progress` 任务，新的自动执行会被阻塞
-- 如果存在 `failed` 或 `blocked` 任务，执行会停下来等待处理
-- 如果依赖任务未完成，相关任务不会被挑选执行
+### 风险控制
 
-## 发布到 npm
+- 默认优先自动执行 `low` 风险任务
+- 较高风险任务需要显式允许
+- 存在未完成依赖时，任务不会被挑选执行
+- 存在未收束的执行状态时，循环会停止并等待处理
 
-仓库已加入自动发布工作流：
+## 仓库结构
 
 ```text
-.github/workflows/publish.yml
-```
-
-这个工作流借鉴了 `helloagents` 的发布结构，并做了适合 `HelloLoop` 的简化与对齐：
-
-- 以 Git Tag 作为发布触发器
-- 发布前校验 `package.json` 版本与 Tag 是否一致
-- 自动运行 `npm test`
-- 自动运行 `npm pack --dry-run`
-- 自动发布到 npm
-- 自动创建 GitHub Release
-
-### 推荐发布方式
-
-#### 正式版
-
-1. 修改 `package.json` 中的 `version`
-2. 提交并推送代码
-3. 创建同版本 Tag
-
-示例：
-
-```powershell
-npm version patch --no-git-tag-version
-git add package.json
-git commit -m "chore: release v0.1.1"
-git push origin main
-git tag v0.1.1
-git push origin v0.1.1
-```
-
-推送 `v0.1.1` 后，Action 会把 `0.1.1` 发布到 npm 的 `latest` 通道。
-
-#### Beta 版
-
-Beta Tag 采用：
-
-```text
-v0.2.0-beta.1
-```
-
-这类 Tag 会发布到 npm 的 `beta` 通道。工作流会要求：
-
-- `package.json` 中的基础版本为 `0.2.0`
-- 实际发布版本为 `0.2.0-beta.1`
-
-### npm Trusted Publishing 配置
-
-为了让 GitHub Actions 无需 `NPM_TOKEN` 直接发布到 npm，建议使用 npm Trusted Publishing。
-
-在 npm 包设置中把以下信息绑定为 Trusted Publisher：
-
-- GitHub 仓库：`hellowind777/helloloop`
-- Workflow 文件：`publish.yml`
-- 触发来源：GitHub-hosted runner
-
-发布工作流已经按 Trusted Publishing 方式准备好：
-
-- `id-token: write`
-- Node 24
-- 升级到最新 npm CLI
-- 直接执行 `npm publish`
-
-### 工作流触发规则
-
-- `push tags: v*`：标准自动发布入口
-- `workflow_dispatch`：手动输入 Tag 重新发布某个版本
-
-## 验证
-
-### 本地回归
-
-```powershell
-npm test
-```
-
-### 打包预检
-
-```powershell
-npm pack --dry-run
+helloloop/
+├── .codex-plugin/         # Codex 插件 manifest 与展示元数据
+├── bin/                   # npm 命令入口
+├── docs/                  # 补充说明文档
+├── scripts/               # 安装脚本与 CLI 入口
+├── skills/                # 插件技能
+├── src/                   # 核心实现
+├── templates/             # 初始化时写入 .helloloop/ 的模板
+└── tests/                 # 回归测试
 ```
 
-### 安装烟测
+其中：
 
-```powershell
-node .\bin\helloloop.mjs install --codex-home C:\Users\hellowind\AppData\Local\Temp\helloloop-smoke --force
-```
+- `src/` 用来放 `HelloLoop` 的实际实现逻辑，例如任务选择、状态加载、执行流程、提示词生成和安装流程
+- `tests/` 用来做回归验证，确保 CLI、模板、插件 bundle 和执行流程没有被改坏
+- `templates/` 是初始化目标仓库时写入 `.helloloop/` 的模板来源
 
 ## 相关文档
 
-- 安装说明：`docs/install.md`
-- 插件主说明：`docs/README.md`
-- 官方标准映射：`docs/plugin-standard.md`
+- `docs/README.md`：插件 bundle 结构补充说明
+- `docs/install.md`：安装说明
+- `docs/plugin-standard.md`：官方插件结构与标准对照

package/package.json

@@ -1,21 +1,17 @@
 {
   "name": "helloloop",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Standalone Codex plugin bundle for backlog-driven repository execution with Ralph Loop guards",
   "type": "module",
   "repository": {
     "type": "git",
-    "url": "https://github.com/hellowind777/helloloop.git"
-  },
-  "homepage": "https://github.com/hellowind777/helloloop#readme",
-  "bugs": {
-    "url": "https://github.com/hellowind777/helloloop/issues"
+    "url": "git+https://github.com/hellowind777/helloloop.git"
   },
   "publishConfig": {
     "access": "public"
   },
   "bin": {
-    "helloloop": "./bin/helloloop.mjs"
+    "helloloop": "bin/helloloop.js"
   },
   "files": [
     ".codex-plugin",
@@ -28,10 +24,9 @@
     "templates"
   ],
   "scripts": {
-    "test": "node --test tests/cli_surface.test.mjs tests/install_script.test.mjs tests/ralph_loop.test.mjs tests/plugin_bundle.test.mjs"
+    "test": "node --test tests/cli_surface.test.mjs tests/install_script.test.mjs tests/process_shell.test.mjs tests/ralph_loop.test.mjs tests/plugin_bundle.test.mjs"
   },
   "engines": {
     "node": ">=20"
   }
 }
-

package/skills/helloloop/SKILL.md

@@ -11,18 +11,17 @@ Use this plugin when the task is continuous repository execution rather than a s
 
 - This bundle root is the official plugin surface for HelloLoop.
 - It ships standard Codex plugin metadata through `.codex-plugin/plugin.json` and a plugin skill through `skills/`.
-- Current Codex runtime does not auto-load Hook handlers from plugins.
-- This plugin therefore does not support `~helloloop` or automatic Stop-hook continuation.
+- This plugin is designed around explicit skill and CLI entrypoints.
 
 ## Setup
 
 1. Install with `npx helloloop install --codex-home <CODEX_HOME>` or use `scripts/install-home-plugin.ps1`.
-2. From the target repository, run `node <helloloop-plugin-root>/scripts/helloloop.mjs doctor --repo <repo-root>`.
-3. From the target repository, run `node <helloloop-plugin-root>/scripts/helloloop.mjs init --repo <repo-root>`.
+2. From the target repository, run `npx helloloop doctor --repo <repo-root>`.
+3. From the target repository, run `npx helloloop init --repo <repo-root>`.
 
 ## Operating Model
 
-- `.helloloop/` is the CLI and backlog state directory.
+- `.helloloop/` is the default CLI and backlog state directory.
 - The installed plugin bundle keeps runtime files such as `src/`, `templates/`, `bin/`, `scripts/`, and `skills/`.
 - Source-only materials such as `docs/` and `tests/` stay in the development repository.
 
@@ -35,15 +34,14 @@ Use this plugin when the task is continuous repository execution rather than a s
 
 ## Primary Commands
 
-- `node <helloloop-plugin-root>/scripts/helloloop.mjs status --repo <repo-root>`
-- `node <helloloop-plugin-root>/scripts/helloloop.mjs next --repo <repo-root>`
-- `node <helloloop-plugin-root>/scripts/helloloop.mjs run-once --repo <repo-root>`
-- `node <helloloop-plugin-root>/scripts/helloloop.mjs run-loop --repo <repo-root>`
+- `npx helloloop status --repo <repo-root>`
+- `npx helloloop next --repo <repo-root>`
+- `npx helloloop run-once --repo <repo-root>`
+- `npx helloloop run-loop --repo <repo-root>`
 
 ## Reporting Rules
 
 - State explicitly that the plugin runs in pure official plugin mode.
-- Call out any request that depends on Hook-only behavior such as `UserPromptSubmit` or `Stop`, because those are intentionally unsupported here.
 - Keep Ralph Loop guardrails and repo verification intact.
 
 ## Docs

package/src/cli.mjs

@@ -7,6 +7,8 @@ import { scaffoldIfMissing } from "./config.mjs";
 import { installPluginBundle } from "./install.mjs";
 import { runLoop, runOnce, renderStatusText } from "./runner.mjs";
 
+const REPO_ROOT_PLACEHOLDER = "<REPO_ROOT>";
+
 function parseArgs(argv) {
   const [command = "status", ...rest] = argv;
   const options = {
@@ -68,6 +70,14 @@ function printHelp() {
   console.log(helpText());
 }
 
+function renderFollowupExamples() {
+  return [
+    "下一步示例：",
+    `npx helloloop doctor --repo ${REPO_ROOT_PLACEHOLDER}`,
+    `如已全局安装，也可直接运行：helloloop doctor --repo ${REPO_ROOT_PLACEHOLDER}`,
+  ].join("\n");
+}
+
 function probeCodexVersion() {
   const codexVersion = process.platform === "win32"
     ? spawnSync("codex --version", {
@@ -171,8 +181,7 @@ export async function runCli(argv) {
     console.log(`HelloLoop 已安装到：${result.targetPluginRoot}`);
     console.log(`Marketplace 已更新：${result.marketplaceFile}`);
     console.log("");
-    console.log("下一步示例：");
-    console.log(`node ${path.join(result.targetPluginRoot, "scripts", "helloloop.mjs")} doctor --repo D:\\GitHub\\dev\\your-repo`);
+    console.log(renderFollowupExamples());
     return;
   }
 
@@ -259,4 +268,4 @@ export async function runCli(argv) {
 
   throw new Error(`未知命令：${command}`);
 }
-
+

package/src/config.mjs

@@ -98,7 +98,7 @@ export function loadVerifyCommands(context) {
 }
 
 export function loadRepoStateText(context) {
-  return readTextIfExists(context.repoStateFile, "").trim();
+  return readTextIfExists(context.stateFile, "").trim();
 }
 
 export function writeStatus(context, status) {
@@ -138,4 +138,4 @@ export function scaffoldIfMissing(context) {
 
   return created;
 }
-
+

package/src/context.mjs

@@ -1,35 +1,16 @@
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { fileExists, resolveFrom } from "./common.mjs";
+import { resolveFrom } from "./common.mjs";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const toolRoot = path.resolve(__dirname, "..");
 const defaultConfigDirName = ".helloloop";
-const legacyConfigDirName = ".helloagents/helloloop";
-
-function resolveConfigDirName(repoRoot, explicitConfigDirName) {
-  if (explicitConfigDirName) {
-    return explicitConfigDirName;
-  }
-
-  const defaultConfigRoot = resolveFrom(repoRoot, ...defaultConfigDirName.split("/"));
-  if (fileExists(defaultConfigRoot)) {
-    return defaultConfigDirName;
-  }
-
-  const legacyConfigRoot = resolveFrom(repoRoot, ...legacyConfigDirName.split("/"));
-  if (fileExists(legacyConfigRoot)) {
-    return legacyConfigDirName;
-  }
-
-  return defaultConfigDirName;
-}
 
 export function createContext(options = {}) {
   const repoRoot = path.resolve(options.repoRoot || process.cwd());
-  const configDirName = resolveConfigDirName(repoRoot, options.configDirName);
+  const configDirName = options.configDirName || defaultConfigDirName;
   const configRoot = resolveFrom(repoRoot, ...configDirName.split("/"));
 
   return {
@@ -49,8 +30,7 @@ export function createContext(options = {}) {
     statusFile: resolveFrom(configRoot, "status.json"),
     stateFile: resolveFrom(configRoot, "STATE.md"),
     runsDir: resolveFrom(configRoot, "runs"),
-    repoStateFile: resolveFrom(repoRoot, ".helloagents", "STATE.md"),
     repoVerifyFile: resolveFrom(repoRoot, ".helloagents", "verify.yaml"),
   };
 }
-
+

package/src/process.mjs

@@ -66,6 +66,57 @@ function buildCmdCommandLine(executable, args) {
   return [quoteForCmd(executable), ...args.map((item) => quoteForCmd(item))].join(" ");
 }
 
+function hasCommand(command, platform = process.platform) {
+  if (platform === "win32") {
+    const result = spawnSync("where.exe", [command], {
+      encoding: "utf8",
+      shell: false,
+    });
+    return result.status === 0;
+  }
+
+  const result = spawnSync("sh", ["-lc", `command -v ${command}`], {
+    encoding: "utf8",
+    shell: false,
+  });
+  return result.status === 0;
+}
+
+export function resolveVerifyShellInvocation(options = {}) {
+  const platform = options.platform || process.platform;
+  const commandExists = options.commandExists || ((command) => hasCommand(command, platform));
+
+  if (platform === "win32") {
+    if (commandExists("pwsh")) {
+      return {
+        command: "pwsh",
+        argsPrefix: ["-NoLogo", "-NoProfile", "-Command"],
+        shell: false,
+      };
+    }
+
+    if (commandExists("powershell")) {
+      return {
+        command: "powershell",
+        argsPrefix: ["-NoLogo", "-NoProfile", "-Command"],
+        shell: false,
+      };
+    }
+
+    return {
+      command: "cmd.exe",
+      argsPrefix: ["/d", "/s", "/c"],
+      shell: false,
+    };
+  }
+
+  return {
+    command: "sh",
+    argsPrefix: ["-lc"],
+    shell: false,
+  };
+}
+
 function resolveCodexExecutable(explicitExecutable = "") {
   if (explicitExecutable) {
     return explicitExecutable;
@@ -214,13 +265,13 @@ export async function runCodexExec({ context, prompt, runDir, policy }) {
 }
 
 export async function runShellCommand(context, commandLine, runDir, index) {
-  const result = await runChild("pwsh", [
-    "-NoLogo",
-    "-NoProfile",
-    "-Command",
+  const shellInvocation = resolveVerifyShellInvocation();
+  const result = await runChild(shellInvocation.command, [
+    ...shellInvocation.argsPrefix,
     commandLine,
   ], {
     cwd: context.repoRoot,
+    shell: shellInvocation.shell,
   });
 
   const prefix = String(index + 1).padStart(2, "0");

package/src/runner.mjs

@@ -338,4 +338,4 @@ export function renderStatusText(context, options = {}) {
     nextTask ? renderTaskSummary(nextTask) : "",
   ].filter(Boolean).join("\n");
 }
-
+

package/templates/STATE.template.md

@@ -9,4 +9,4 @@
 - 当前任务：无
 - 最近结果：HelloLoop 已初始化
 - 下一建议：先完善 backlog.json
-
+

package/templates/status.template.json

@@ -15,4 +15,4 @@
   "message": "HelloLoop 已初始化。",
   "updatedAt": "2026-03-27T00:00:00.000Z"
 }
-
+