helloloop 0.8.6 → 0.10.0

package/README.md

@@ -1,649 +1,381 @@
 # HelloLoop
 
 > [!WARNING]
-> **风险提示**
-> 使用 `HelloLoop` 执行持续 / 持久型任务仍存在不可完全控制的风险。虽然项目已经加入高危行为管控与防护策略，但仍不能排除误删数据、误改文件、异常覆盖或其他不可预期后果。请在使用前务必先备份重要数据，并自行通过人工或借助 AI 对 `HelloLoop` 的安全风险做评估与审计；因使用本插件造成的数据丢失或其他损失，项目方不承担责任。
+> `HelloLoop` 适合“持续推进型”的自动开发任务，不适合在未备份的重要仓库上直接盲跑。请先备份关键数据，并对自动修改结果进行人工复核。
 
-`HelloLoop` 是一个面向 `Codex CLI`、`Claude Code`、`Gemini CLI` 的多宿主开发工作流插件，用来把“根据开发文档持续接续开发、测试、验收，直到最终目标完成”收敛成一条统一、可确认、可追踪的标准流程。
+`HelloLoop` 是一个面向 `Codex CLI`、`Claude Code`、`Gemini CLI` 的持续开发工作流插件。
 
-它的核心原则很简单：
+它解决的不是“问一次、答一次”的问题，而是这类场景：
 
-- 三家都能安装、都能用、都按各自原生 agent 逻辑执行
-- `Codex CLI` 仍然是首发平台、参考实现和最佳体验路径
-- 运行状态统一写入目标仓库根目录的 `.helloloop/`
-- 真正执行前先分析、先确认，执行中不静默失败、不静默切换
+- 根据开发文档持续推进一个仓库，直到 backlog 清空
+- 先分析当前代码进度，再补齐缺口，而不是从头乱做
+- 中途遇到宿主中断、限流、网络抖动后还能继续接上
+- 同时查看多个仓库的任务状态与执行进度
 
-## 宿主与执行引擎
+---
 
-`HelloLoop` 区分两个概念：
+## 1. HelloLoop 能做什么
 
-- **宿主**：你从哪里进入，例如终端、`Codex`、`Claude`、`Gemini`
-- **执行引擎**：真正负责本轮分析 / 开发 / 测试推进的 CLI
+把“开发文档 + 现有代码 + 持续执行 + 可视化跟踪”收口成一条标准流程：
 
-这意味着：
+1. 自动识别项目仓库与开发文档
+2. 分析当前进度、偏差和剩余任务
+3. 生成 / 刷新 `.helloloop/backlog.json`
+4. 输出中文确认单
+5. 确认后持续执行、验证、复核
+6. 中断后支持继续接续，而不是重新来一遍
 
-- 三宿主都只在用户显式调用 `helloloop` 时介入；普通会话不会被 HelloLoop 自动接管
-- 在 `Codex` 中，只有显式输入 `$helloloop` / `#helloloop` / `helloloop:helloloop` 才算调用；仅仅提到 `helloloop` 仓库、README、代码、测试、release、npm 包名，都不算调用
-- 无论在终端还是在 `Codex` / `Claude` / `Gemini` 宿主内，只要用户未明确指定引擎，`HelloLoop` 都会先询问本轮执行引擎
-- 当前宿主、项目历史、用户历史只作为推荐依据，不会自动替你选中引擎
-- 如果你已经显式指定，或已经在首轮确认中明确选定了引擎，本轮就固定按该引擎执行
-- 如果后续因为登录、配额、限流等问题需要改用别的引擎，`HelloLoop` 也会先询问，不会静默切换
+---
 
-## 支持矩阵
+## 2. 最适合的使用场景
 
-| 宿主 | 安装方式 | 原生入口 | 说明 |
-| --- | --- | --- | --- |
-| `Codex CLI` | `helloloop install` / `helloloop install --host codex` | `Codex` 内：`$helloloop`；终端：`npx helloloop` | 仅在显式调用时进入 HelloLoop |
-| `Claude Code` | `helloloop install --host claude` | `/helloloop` | 仅在显式调用时进入 HelloLoop |
-| `Gemini CLI` | `helloloop install --host gemini` | `/helloloop` | 仅在显式调用时进入 HelloLoop |
+- 按架构文档、PRD、任务拆解持续完成仓库开发
+- 多仓并行推进，需要统一看板跟踪
+- 任务需要跑很久，不希望因为一次中断就全部停掉
+- 需要让主终端、TUI 看板、Web 看板都能看到当前状态
+- 需要在 `Codex CLI` / `Claude Code` / `Gemini CLI` 之间保持一致体验
 
-补充说明：
+不适合的场景：
 
-- `install --host codex` 只会把 `HelloLoop` 注册成 `Codex` 插件，不会把 `helloloop` 写进系统 `PATH`
-- 终端里的 `npx helloloop` 始终是 npm CLI 入口；如果本机未全局安装，首次执行出现 `Need to install the following packages` 属正常行为
-- `Codex` 安装完成后，建议重启 `Codex` 或新开一个会话，再检查 `$helloloop`
+- 只改一个很小的文件
+- 单轮对话就能完成的简单问答
+- 不允许自动修改文件、只想人工讨论方案
 
-## 最短使用方式
+---
 
-推荐先记住下面四种：
+## 3. 核心能力
 
-```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` 会先按无人值守策略做同引擎“健康探测 + 条件恢复”，不会中途停下来询问
-
-## 默认工作流
-
-无论从哪个宿主进入，都遵循同一条主线：
-
-1. 自动识别目标项目仓库与开发文档
-2. 分析当前代码进度、偏差和项目匹配性
-3. 在目标仓库根目录创建或刷新 `.helloloop/`
-4. 输出中文执行确认单
-5. 用户确认后，按选中的执行引擎持续推进开发、测试、验收
-6. 每个任务完成后，自动做一次“任务完成复核”
-7. backlog 暂时清空后，自动做一次“主线终态复核”
-
-如果分析发现当前实现已经偏离开发文档，`HelloLoop` 会优先先收口偏差，再继续后面的 backlog。
-
-这意味着：
-
-- 不会因为执行引擎自己一句“已完成”就直接结束
-- 如果只是部分完成，`HelloLoop` 会继续当前主线任务，而不是跳去做模型随口建议的别的事
-- 如果 backlog 清空了，但主线终态复核仍发现文档目标还有缺口，`HelloLoop` 会自动重新分析并继续推进
-- 如果模型只做了一半就想停下来给“下一步建议”，`HelloLoop` 会优先按主线目标继续推进，而不是把半成品当完成
-
-## 后台监督执行
-
-从当前版本开始，`HelloLoop` 的自动执行主线统一走 **detached supervisor + host lease** 模式：
-
-- `analyze` 确认后的自动执行、`run-once`、`run-loop` 都默认切到后台 supervisor
-- 当前对话 turn 就算被误按 `Esc`、被宿主暂停、或当前工具调用被中断，后台 supervisor 仍会继续
-- 原有的 15 分钟级恢复、健康探测、同引擎自动恢复，也会继续由这个后台 supervisor 接管
-- 这不是“当前进程死掉后每 15 分钟重新拉起一遍主进程”，而是 supervisor 本身持续存活，所以恢复链不会因为当前 turn 消失而断掉
-- 真正的停止边界改成 **宿主租约**：只要宿主 CLI 窗口 / 进程还活着，任务就继续；如果宿主窗口真的关闭，HelloLoop 才会停止当前子进程并把任务回退为 `pending`
-
-常见场景：
-
-- 在 `Codex` / `Claude` / `Gemini` 宿主里运行 `helloloop`：确认后默认转入后台执行，可用 `helloloop status` 查看进度
-- 在普通终端里运行 `npx helloloop`、`npx helloloop run-once`、`npx helloloop run-loop`：默认也会转入后台执行
-- `--supervised` 仍然保留，但现在只是兼容参数，不再是开启后台 supervisor 的前提
-
-## 无人值守恢复
-
-`HelloLoop` 的设计目标不是“跑一轮停一轮”，而是启动前确认一次，启动后持续无人值守推进。
-
-- 因此运行中的默认策略是：
-
-- 普通运行故障不再中途提问：不会因为 429、5xx、网络抖动、结果流中断、短时空输出就停下来问用户
-- 同引擎优先恢复：默认不会自动切换引擎，也不会偷偷改用别的 CLI
-- 先探测、后续跑：重试前会先做最小健康探测；只有探测通过后，才会恢复主线任务，而不是盲目把完整任务再跑一遍
-- 保留主线上下文恢复：同引擎恢复时会生成恢复记录与恢复 prompt，要求新一轮执行直接基于当前仓库状态继续，而不是从头另起一套
-- 定时心跳检查：运行中会持续写入心跳与恢复状态，用于判断当前阶段是否还在正常推进
-- 最终停止会告警：如果自动恢复额度真正用尽，且已配置全局邮箱，`HelloLoop` 会把错误类型与具体内容发到指定邮箱
-
-默认恢复节奏：
-
-- 心跳间隔：60 秒
-- 疑似卡住预警：15 分钟无可见进展
-- 自动终止阈值：45 分钟无可见进展
-- 硬阻塞：每 15 分钟探测 1 次，共 5 次；仍失败则暂停等待人工介入
-- 软阻塞：先每 15 分钟探测 5 次，再 30 分钟 2 次，再按 60 / 90 / 120 / 150 / 180 分钟各探测 1 次；仍失败则暂停等待人工介入
-
-如果你明确指定或确认了本轮引擎，`HelloLoop` 在自动恢复阶段也会继续锁定该引擎，不会擅自切换。
-
-但要特别注意：
-
-- 在 `Codex` / `Claude` / `Gemini` 宿主里，当前 turn 被误按 `Esc`、当前工具调用被取消，或当前会话暂时暂停时，只要宿主窗口本身还活着，后台 supervisor 仍会继续，原有自动恢复节奏也会继续生效
-- 如果真正关闭了宿主 CLI 窗口、终端进程结束，或宿主租约已经失效，HelloLoop 会停止当前子进程，并把未完成任务回退为 `pending`
-- 也就是说：**当前 turn 取消 ≠ 停止 HelloLoop；关闭宿主窗口 = 停止 HelloLoop**
-- 宿主窗口已经关闭后，HelloLoop 不会再脱离宿主自行无限后台驻留；这时需要你重新打开宿主并再次显式调用 `helloloop` 来接续
+- 显式调用才接管，不会默默劫持普通对话
+- 自动对齐“开发文档目标”与“当前代码事实”
+- 分析、执行、验证、任务复核、主线终态复核一体化
+- 默认后台执行，但当前终端可以继续实时观察
+- 宿主中断后可输出自然语言续跑提示
+- 提供终端 TUI 总控台
+- 提供本地 Web 看板
+- 提供结构化 JSON 状态流，方便上层程序消费
+- Windows 下尽量隐藏后台控制台，避免频繁弹窗 / 闪烁
 
-## 全局告警配置
+---
 
-如果希望在“自动恢复彻底停止”后收到邮件告警，可在：
+## 4. 支持的宿主
 
-```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"
-      }
-    }
-  }
-}
-```
+| 宿主 | 调用方式 |
+| --- | --- |
+| `Codex CLI` | `Codex` 内输入 `$helloloop` / `#helloloop` / `helloloop:helloloop` |
+| `Claude Code` | `/helloloop` |
+| `Gemini CLI` | `/helloloop` |
+| 普通终端 | `npx helloloop` |
 
 说明：
 
-- 建议把 SMTP 密码放在环境变量里，不要明文写进配置文件
-- 邮件只在“本轮不再继续自动重试”时发送，不会每次失败都刷屏
+- 只有用户显式调用时才进入 HelloLoop
+- 只是在对话里提到 `helloloop` 仓库、README、命令示例，不算调用
 
-## 终端并发上限
+---
 
-`HelloLoop` 不会主动再额外弹出一堆可见终端窗口；这里的：
+## 5. 安装
 
-- **显示终端** 指当前前台运行中的 `helloloop` 会话
-- **背景终端** 指 detached supervisor 后台会话
+### 安装到 Codex
 
-默认限制为：
-
-- 显示终端最多 `8`
-- 背景终端最多 `8`
-- 显示 + 背景合计最多 `8`
+```bash
+npx helloloop install --host codex
+```
 
-可在：
+### 安装到 Claude Code
 
-```text
-~/.helloloop/settings.json
+```bash
+npx helloloop install --host claude
 ```
 
-中自行调整，例如：
-
-```json
-{
-  "runtime": {
-    "terminalConcurrency": {
-      "enabled": true,
-      "visibleMax": 8,
-      "backgroundMax": 8,
-      "totalMax": 8
-    }
-  }
-}
+### 安装到 Gemini CLI
+
+```bash
+npx helloloop install --host gemini
 ```
 
-说明：
+### 一次装到全部宿主
 
-- 只要合计并发达到 `totalMax`，新前台会话或新的后台 supervisor 都不会再继续启动
-- 如果只是想临时完全关闭这个保护，可把 `enabled` 设为 `false`
-- 这个限制主要用于避免同时占用过多本机终端资源，或因为并发过高触发模型 / API 限速
+```bash
+npx helloloop install --host all
+```
 
-## 自动发现与交互逻辑
+---
 
-### 1. 只输入 `npx helloloop`
+## 6. 最快上手
 
-如果你只输入：
+### 只让 HelloLoop 自己判断
 
 ```bash
 npx helloloop
 ```
 
-`HelloLoop` 会先明确执行引擎，再快速扫描当前目录：
-
-- 当前目录本身就是开发文档目录时，会先尝试从文档反推项目目录
-- 当前目录看起来像普通项目目录时，默认直接把当前目录作为项目目录
-- 当前目录更像工作区或用户主目录时，才会额外询问项目目录
-- 如果当前项目目录下没有明确开发文档，会只提示补充“开发文档”这一项，并说明已检查的常见位置
-
-### 2. 项目路径只问一次
-
-对外只有“项目路径”这一个概念：
-
-- 输入已有目录 → 按现有项目继续分析
-- 输入不存在的目录 → 视为准备创建的新项目目录
-
-不会再额外追问一个“新项目路径”。
-
-### 3. 缺什么就只问什么
-
-正常情况下只需要两项信息：
-
-- 项目目录
-- 开发文档
-
-其中：
-
-- 项目目录默认优先使用当前打开的目录
-- 当前目录明显不是项目目录时，才会额外询问项目目录
-- 开发文档缺失时，只会询问开发文档
-
-以下情况不会硬猜：
+### 指定开发文档或项目路径
 
-- 给了开发文档，但仍无法定位项目目录
-- 给了项目路径，但无法定位开发文档
-- 同时出现多个冲突的文档路径或项目路径
-
-### 4. 命令 + 自然语言会一起分析
-
-`HelloLoop` 不依赖固定中文关键词做硬编码分流。
-
-命令里的：
-
-- 显式路径
-- 中文自然语言
-- 英文自然语言
-- 其他语言的补充要求
-
-都会一起进入分析和确认单，不会因为语言不同被静默忽略。
-
-### 5. 现有项目与文档目标冲突时
+```bash
+npx helloloop <PATH>
+```
 
-如果当前项目目录已存在，但分析认为它与开发文档目标明显冲突，`HelloLoop` 不会直接清空目录，而是先提示你选择：
+`<PATH>` 可以是：
 
-1. 继续在当前项目上尝试接续
-2. 清理当前项目内容后按文档目标重建
-3. 取消本次执行
+- 项目仓库目录
+- 开发文档目录
+- 开发文档文件
 
-如果你明确希望非交互模式下直接重建，可以使用：
+### 明确指定执行引擎
 
 ```bash
-npx helloloop --rebuild-existing
+npx helloloop codex
+npx helloloop claude
+npx helloloop gemini
 ```
 
-## 执行确认单
-
-真正开始开发前，`HelloLoop` 会先输出中文执行确认单，至少包含：
-
-- 路径判断与判断依据
-- 本次命令补充输入
-- 执行引擎
-- 需求语义理解
-- 项目匹配判断
-- 项目目录
-- 开发文档
-- 当前进度
-- 已实现事项
-- 待完成事项
-- 任务统计
-- 首个待执行任务
-- 验证命令预览
-- 自动执行停止条件
+### 跳过确认直接开始
 
-未确认前，不会正式修改代码。
+```bash
+npx helloloop -y
+```
 
-确认后，默认行为不是“跑一轮就停”，而是：
+### 只分析，不执行
 
-- 先按 backlog 执行当前颗粒度任务
-- 每个任务完成后复核其验收是否真的闭合
-- backlog 清空后再复核一次整个主线目标
-- 只有“任务验收闭合 + 主线目标闭合 + 验证通过”才算真正结束
-- 运行中若出现可恢复的 CLI 故障，则按无人值守策略自动恢复，不打断主线
+```bash
+npx helloloop --dry-run
+```
 
-## 安装
+---
 
-### 通过 npm / npx
+## 7. 常见使用方式
 
-默认安装到 `Codex`：
+### 场景 A：根据文档持续完成一个仓库
 
 ```bash
-npx helloloop install
-npx helloloop install --codex-home <CODEX_HOME>
+npx helloloop "D:\GitHub\dev\hellomind-codex\docs"
 ```
 
-安装到指定宿主：
+### 场景 B：指定仓库并补充自然语言要求
 
 ```bash
-npx helloloop install --host codex
-npx helloloop install --host claude
-npx helloloop install --host gemini
-npx helloloop install --host all
+npx helloloop "D:\GitHub\dev\repo" 先对齐开发文档，再继续完成剩余任务
 ```
 
-可选 home 参数：
+### 场景 C：强制某个引擎继续推进
 
 ```bash
---codex-home <CODEX_HOME>
---claude-home <CLAUDE_HOME>
---gemini-home <GEMINI_HOME>
+npx helloloop codex "D:\GitHub\dev\repo" 接着做，不要重新分析无关内容
 ```
 
-### 从源码仓库安装
+### 场景 D：宿主中断后继续接上
 
 ```bash
-node ./scripts/helloloop.mjs install --host codex
+helloloop resume-host
 ```
 
-Windows PowerShell 也可以直接运行：
+如果要让上层程序读取结构化结果：
 
-```powershell
-pwsh -NoLogo -NoProfile -File .\scripts\install-home-plugin.ps1 -CodexHome <CODEX_HOME>
+```bash
+helloloop resume-host --json
 ```
 
-### 升级、重装、切换分支
+---
 
-```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
-```
+## 8. 后台执行与继续观察
 
-说明：
+`HelloLoop` 的默认体验是：
 
-- `--force` 会清理当前宿主里已有安装残留的 `helloloop` 目录后再重装
-- `Codex` 会刷新 home 根下的插件源码目录、已安装缓存、`config.toml` 启用项和 marketplace 条目
-- `Claude` 会刷新 marketplace、缓存插件目录，以及 `settings.json` / `known_marketplaces.json` / `installed_plugins.json` 中的 `helloloop` 条目
-- `Gemini` 会刷新 `extensions/helloloop/`，不会动同目录下其他扩展
-- 安装 / 升级 / 重装时，会同步校准 `~/.helloloop/settings.json` 的当前版本结构：补齐缺失项、清理未知项、保留已知项现有值
-- 如果 `~/.helloloop/settings.json` 被确认不是合法 JSON，会先备份原文件，再按当前版本结构重建
-- 如果只是首次读取时出现瞬时异常，但重读后内容合法，则不会误生成备份文件
-- 如果宿主自己的配置 JSON（如 `Codex marketplace.json`、`Claude settings.json`、`known_marketplaces.json`、`installed_plugins.json`）本身已损坏，`HelloLoop` 会先明确报错并停止，不会先清理现有安装再失败
+- 自动执行时切到后台继续跑
+- 当前终端仍可继续观察实时输出
+- 当前 turn 被打断，不等于后台任务立即停止
 
-### 卸载
+如果你稍后想重新看进度：
 
 ```bash
-npx helloloop uninstall --host codex
-npx helloloop uninstall --host claude
-npx helloloop uninstall --host gemini
-npx helloloop uninstall --host all
+helloloop watch
+helloloop status --watch
 ```
 
-卸载是定向清理：
-
-- 只删除 `helloloop` 自己的安装目录和注册条目
-- 不会顺带删除别的插件、marketplace、扩展或自定义配置
-- 即使某个宿主当前未安装 `helloloop`，也会安全退出，不做破坏性清理
-
-## 使用入口
-
-### 终端
+如果你只想后台继续跑，前台命令立即返回：
 
 ```bash
-npx helloloop
-npx helloloop <PATH>
-npx helloloop codex <PATH>
-npx helloloop claude <PATH>
-npx helloloop gemini <PATH> <补充说明>
+helloloop run-loop --detach
+helloloop run-once --detach
 ```
 
-如果已经做了全局安装，也可以把 `npx helloloop` 简写为 `helloloop`。是否立刻可用取决于当前 shell 是否已经刷新 `PATH`。
-
-### Codex CLI
+---
 
-```text
-$helloloop
-helloloop:helloloop
-```
+## 9. 看板与可视化
 
-在终端里（包括 `Codex` 打开的内置终端）也可以直接执行：
+### 终端 TUI 总控台
 
 ```bash
-npx helloloop
+helloloop dashboard
+helloloop tui
+helloloop dash
 ```
 
-如果你在 `Codex` 中直接使用 `$helloloop` 或 `npx helloloop`，但没有明确指定引擎，`HelloLoop` 仍会先让你确认本轮引擎；`Codex` 只会作为推荐项，不会被自动选中。
-未显式调用 `$helloloop`、`helloloop:helloloop` 或 `npx helloloop` 时，普通 `Codex` 会话不会被 HelloLoop 自动接管。
-
-### Claude Code / Gemini CLI
+适合：
 
-```text
-/helloloop
-```
+- 常驻一个终端看多仓任务
+- 在仓库之间快速切换
+- 查看 backlog 的待处理 / 进行中 / 已完成 / 阻塞 / 失败
 
-它们会按各自 CLI 的原生 agent 逻辑执行，但共享同一套 `.helloloop/` 工作流规范。
-只有在你显式调用 `/helloloop` 时，它们才会进入 HelloLoop 工作流；普通 Claude / Gemini 会话不会被自动接管。
+快捷键：
 
-## 常用命令
+- `← / →` 切换仓库
+- `↑ / ↓` 滚动
+- `1-9` 直达仓库
+- `r` 刷新
+- `q` 退出
 
-| 命令 | 作用 |
-| --- | --- |
-| `helloloop` / `analyze` | 自动分析、展示确认单，并在确认后持续接续开发，直到主线目标闭合或遇到硬阻塞 |
-| `install` | 安装运行时 bundle 到指定宿主 |
-| `uninstall` | 从指定宿主卸载运行时 bundle 与注册信息 |
-| `doctor` | 检查宿主环境、插件资产与目标仓库状态 |
-| `init` | 手动初始化 `.helloloop/` 模板 |
-| `status` | 查看 backlog 摘要和当前状态 |
-| `next` | 生成下一任务的干跑预览 |
-| `run-once` | 执行一个任务 |
-| `run-loop` | 连续执行多个任务 |
-
-常用选项：
-
-| 选项 | 作用 |
-| --- | --- |
-| `codex` / `claude` / `gemini` | 作为 `analyze` 模式的命令首参数，显式指定执行引擎 |
-| `--dry-run` | 只分析并输出确认单，不开始自动执行 |
-| `-y` / `--yes` | 跳过执行确认直接开始；但如果未显式指定引擎，会直接报错而不是自动选引擎 |
-| `--repo <dir>` | 高级覆盖：显式指定项目仓库 |
-| `--docs <dir|file>` | 高级覆盖：显式指定开发文档 |
-| `--supervised` | 兼容保留；当前版本默认已启用 detached supervisor |
-| `--rebuild-existing` | 项目与文档冲突时，自动清理现有项目后重建 |
-| `--host <name>` | 安装宿主：`codex` / `claude` / `gemini` / `all` |
-| `--config-dir <dir>` | 状态目录名，默认 `.helloloop` |
-
-手动控制示例：
+### 本地 Web 看板
 
 ```bash
-npx helloloop status
-npx helloloop next
-npx helloloop run-once
+helloloop web
 ```
 
-## Doctor
+默认会启动一个本地 Web 服务，并输出访问地址。
 
-检查默认宿主：
+可选参数：
 
 ```bash
-npx helloloop doctor
+helloloop web --port 3210
+helloloop web --bind 127.0.0.1
+helloloop web --stop
 ```
 
-检查全部宿主：
+适合：
 
-```bash
-npx helloloop doctor --host all
-```
+- 长时间像 Jira 一样挂着看板
+- 多仓泳道 + 任务列跟踪
+- 点击任务查看详情
 
-检查指定安装目录：
+### 给主代理或外部程序消费结构化状态
 
 ```bash
-npx helloloop doctor --host all --codex-home <CODEX_HOME> --claude-home <CLAUDE_HOME> --gemini-home <GEMINI_HOME>
+helloloop dashboard --json
+helloloop dashboard --json --watch
+helloloop dash -j --watch --poll-ms 2000
 ```
 
-## 发布流程
+---
 
-`HelloLoop` 当前采用 **tag 驱动发布**：
+## 10. 常用命令速查
 
-1. 先在源码仓库完成版本号更新（`package.json` 与各宿主 manifest 保持一致）
-2. 本地先执行：
+| 命令 | 作用 |
+| --- | --- |
+| `helloloop` | 分析并进入主流程 |
+| `helloloop status` / `helloloop st` | 查看当前仓库状态 |
+| `helloloop watch` / `helloloop w` | 重新附着后台会话 |
+| `helloloop next` / `helloloop n` | 预览下一任务 |
+| `helloloop run-once` / `helloloop once` | 执行一个任务 |
+| `helloloop run-loop` / `helloloop loop` | 连续执行多个任务 |
+| `helloloop dashboard` / `helloloop dash` | 打开终端总控台 |
+| `helloloop tui` | 显式打开 TUI 看板 |
+| `helloloop web` | 启动本地 Web 看板 |
+| `helloloop resume-host` / `helloloop rh` | 输出宿主续跑提示 |
+| `helloloop doctor` / `helloloop dr` | 诊断安装与运行环境 |
+| `helloloop install` | 安装插件到宿主 |
+| `helloloop uninstall` | 从宿主卸载插件 |
+
+---
+
+## 11. 短命令别名
+
+如果你不想每次打很长：
 
 ```bash
-npm test
-npm pack --dry-run
+helloloop dash
+helloloop tui
+helloloop web
+helloloop st
+helloloop w
+helloloop rh
+helloloop once
+helloloop loop
 ```
 
-3. 推送 Git tag：
+---
 
-```bash
-git tag vX.Y.Z
-git push origin vX.Y.Z
-```
+## 12. 配置文件
 
-或 beta 版本：
+全局设置位于：
 
-```bash
-git tag vX.Y.Z-beta.N
-git push origin vX.Y.Z-beta.N
+```text
+~/.helloloop/settings.json
 ```
 
-随后 GitHub Actions `Publish to npm` 会自动执行：
+常见配置包括：
 
-- tag / 版本一致性校验
-- `npm test`
-- `npm pack --dry-run`
-- `npm publish`
-- GitHub Release
+- 观察层自动重试
+- 后台守护保活
+- 终端并发上限
+- 告警邮箱
 
-补充说明：
+项目级运行状态位于目标仓库：
 
-- 正式版本使用 npm `latest` 渠道，beta 版本使用 npm `beta` 渠道
-- 如果测试、版本校验或打包检查失败，npm 发布与 GitHub Release 都不会继续执行
-- `0.8.6` 起已统一为全流程后台 supervisor：`analyze` 确认后的自动执行、`run-once`、`run-loop` 默认都后台化，不再要求普通终端显式追加 `--supervised`
-- GitHub Release 阶段现已改为使用官方 `gh` CLI + `generate-notes` API 创建 / 更新 release，不再依赖会触发 Node runtime deprecation warning 的第三方 action
-
-## 宿主写入范围
-
-为了方便排查安装 / 更新 / 卸载问题，下面是默认写入位置：
-
-### `Codex CLI`
-
-- 插件源码目录：`~/plugins/helloloop/`
-- 已安装缓存：`~/.codex/plugins/cache/local-plugins/helloloop/local/`
-- marketplace：`~/.agents/plugins/marketplace.json`
-- 启用配置：`~/.codex/config.toml`
-
-### `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`
+```text
+<repo>/.helloloop/
+```
 
-- 扩展目录：`~/.gemini/extensions/helloloop/`
+其中通常会包含：
 
-`HelloLoop` 只维护自己的目录和自己的注册项，不会重写别的插件条目。
+- backlog
+- 运行状态
+- supervisor 状态
+- 宿主续跑信息
+- runs 执行记录
 
-## 用户目录写入范围
+---
 
-全局用户目录 `~/.helloloop/` 只保留一份全局设置：
+## 13. Windows 使用说明
 
-```text
-~/.helloloop/
-└── settings.json
-```
+`HelloLoop` 会尽量把后台启动、内部调度和观察链做成隐藏模式，目标是：
 
-说明：
+- 不弹出空白 PowerShell 窗口
+- 不让后台守护层反复闪烁控制台
+- 主任务在后台继续跑，主终端只负责观察
 
-- 这里不保存项目 backlog、状态、运行记录
-- 安装 / 升级 / 重装时，会对 `settings.json` 做结构校准，但不会校验或篡改你已存在的已知项内容
-- 只有在 `settings.json` 被确认非法时，才会先备份，再重建为当前版本结构
-- 如果只是读取瞬时异常、重读后合法，不会误生成 `.bak`
+但首次安装、系统权限、终端自身限制等因素仍可能影响最终表现。
 
-## `.helloloop/` 状态目录
+如果你主要关心状态可视化，优先使用：
 
-`HelloLoop` 的 backlog、状态和运行记录始终写入目标仓库根目录下的：
+- `helloloop dashboard`
+- `helloloop tui`
+- `helloloop web`
 
-```text
-.helloloop/
-├── backlog.json
-├── policy.json
-├── project.json
-├── status.json
-├── STATE.md
-└── runs/
-```
+---
 
-不会写回插件目录自身。
-也不会写入 `~/.helloloop/`。
+## 14. 边界说明
 
-## 跨平台与安全
+`HelloLoop` 不会做这些事：
 
-### Windows
+- 不会在普通对话里静默接管当前宿主
+- 不会在未确认时默认清空已有项目目录
+- 不会因为一条“已完成”回复就直接宣称任务真正完成
+- 不会在恢复阶段偷偷切换到别的引擎
 
-- 优先使用 `pwsh`
-- 也支持 `bash`（如 Git Bash）与 `powershell`
-- 不回退到 `cmd.exe`
-- 避免危险的嵌套命令、路径拼接删除和 `cmd` 风格破坏性流程
+---
 
-### macOS / Linux
+## 15. 推荐工作方式
 
-- 优先使用 `bash`
-- 如果没有 `bash`，回退到 `sh`
+### 个人开发者
 
-### 通用安全边界
+- 用 `npx helloloop` 或宿主内显式调用开始
+- 用 `watch` 看实时过程
+- 用 `dashboard` / `tui` 看多仓状态
 
-- 不静默失败
-- 不静默回退
-- 不静默切换执行引擎
-- 不吞掉错误
-- 真正执行前先确认
-- 真正结束前先验证
-- 不轻信执行引擎口头“已完成”
-- 不接受“先做一半再停下来问要不要继续”
+### 多仓联动开发
 
-## 仓库结构
+- 每个仓库各自维护 `.helloloop/`
+- 用 `web` 看整体进度
+- 用 `resume-host` 在主代理中断后继续接上
 
-```text
-helloloop/
-├── .claude-plugin/
-├── .codex-plugin/
-├── .github/
-├── .helloagents/
-├── bin/
-├── docs/
-├── hosts/
-├── scripts/
-├── skills/
-├── src/
-├── templates/
-├── tests/
-├── LICENSE
-├── package.json
-└── README.md
-```
+### 长时间任务
 
-其中：
+- 先确认后启动
+- 让后台继续执行
+- 用 `status` / `watch` / `dashboard` / `web` 轮流观察
 
-- `.codex-plugin/`：Codex 插件 manifest
-- `.claude-plugin/`：Claude plugin manifest
-- `hosts/`：Claude marketplace / Gemini extension 资产
-- `skills/`：Codex 插件技能说明
-- `src/`：发现、分析、执行、安装、卸载、doctor 等核心实现
-- `templates/`：初始化目标仓库 `.helloloop/` 的模板
-- `docs/` 与 `tests/`：源码仓库维护资料，不进入运行时安装包
+---
 
-## 许可证
+## 16. 一句话理解
 
-`HelloLoop` 使用 `Apache-2.0`，许可证文件位于仓库根目录的 `LICENSE`。
+如果普通 CLI 像“单次回答助手”，那 `HelloLoop` 更像“持续推进开发任务的执行层 + 观察层 + 续跑层”。