helloloop

# HelloLoop 当任务目标不是单轮对话里改一点代码，而是要基于开发文档持续推进整个仓库时，使用这个插件。 ## 强制入口规则 - 只有用户显式调用 `$helloloop` / `#helloloop` / `helloloop:helloloop` 时，才允许进入 HelloLoop；未显式调用时，不允许接管普通 Codex 会话。 - 仅仅提到 `helloloop` 仓库、插件名、README、代码、测试、issue、release、npm 包名，都不算调用 HelloLoop。 - 用户显式调用 `$helloloop` / `#helloloop` / `helloloop:helloloop` 时，默认必须优先执行 `npx helloloop` 或 `npx helloloop <PATH>`；如果用户又明确指定了执行引擎，也允许使用 `npx helloloop codex|claude|gemini ...`。 - 用户没有明确指定执行引擎时，不允许由 skill 自行补成 `codex` / `claude` / `gemini`；必须让 `HelloLoop` 先完成引擎确认。 - 不允许在对话里手工模拟 `HelloLoop` 的分析、确认单、backlog 编排和自动续跑流程来代替 CLI。 - 只有在以下情况，才允许先停下来问用户而不是直接执行 CLI： 1. 用户既没有给路径，当前目录也无法判断项目仓库或开发文档 2. 用户给了开发文档，但无法定位目标项目仓库 3. 用户给了项目路径，但无法找到开发文档 4. 用户明确要求先只讲解、不执行 ## `$helloloop` 的默认执行映射 - 当前目录已经是目标项目仓库或开发文档目录 → 先执行 `npx helloloop --host-context codex` - 用户给了单一路径 → 先执行 `npx helloloop --host-context codex <PATH>` - 用户明确只想先看分析和确认单 → 执行 `npx helloloop --dry-run` - 用户明确要求跳过确认直接开始 → 执行 `npx helloloop -y` - 用户未明确指定执行引擎 → 保持命令里不带引擎首参数，让 `HelloLoop` 先做引擎确认；当前宿主只作为推荐依据 - 用户明确指定执行引擎 → 保留该引擎首参数；如果在 `Codex` 宿主内要求改用 `Claude` / `Gemini`，先确认，不允许静默切换 - 用户在命令后附带了额外路径或自然语言要求 → 必须把这些附加内容一并传给主 CLI，不允许丢弃或手工改写 ## 附加输入处理规则 - 命令后的显式路径优先于自动发现结果。 - 命令后的非路径文本不靠关键词硬编码分流，而是作为“本次用户意图”原样传给 `HelloLoop` 的确认单与分析 prompt。 - 如果附加输入里同时包含文档路径、项目路径和额外要求，优先保留全部信息，再由 CLI 输出确认单统一确认。 - 不允许因为语言不同（中文 / 英文 / 其他语言）就忽略附加要求。 ## 路径发现与提问规则 - 如果当前目录看起来像普通项目目录，默认直接把当前目录当作项目目录；只有明显是工作区或用户主目录时才额外询问项目目录。 - 如果当前项目目录里没有自动识别到明确开发文档，只补充询问开发文档，不展示“顶层文档文件 / 顶层目录 / 疑似项目目录”之类内部扫描分类。 - 项目路径对外只有一个概念，不要单独追问“新项目路径”。 - 如果用户输入的项目路径不存在，应直接把它视为准备创建的新项目目录。 - 如果自动发现同时出现多个冲突的文档路径或项目路径，不允许替用户猜测，必须停下来确认。 ## 项目冲突规则 - 如果分析认为“当前项目目录已存在，但与开发文档目标明显冲突”，必须先提示用户选择继续、重建还是取消。 - 非交互模式下，只有显式追加 `--rebuild-existing`，才允许直接清理当前项目后重建。 - 未经确认，不允许默认清空现有项目目录。 ## 插件边界 - 当前 bundle 根目录就是 `HelloLoop` 的官方插件目录。 - 插件元数据位于 `.codex-plugin/plugin.json`，执行逻辑位于 `skills/`、`bin/`、`scripts/`、`src/`、`templates/`。 - 运行状态统一写入目标仓库根目录下的 `.helloloop/`。 ## 使用前准备 1. 先通过 `npx helloloop install --codex-home <CODEX_HOME>` 或 `scripts/install-home-plugin.ps1` 安装插件。 2. 打开目标项目仓库目录，或者打开开发文档所在目录。 3. 运行 `npx helloloop` 或 `npx helloloop <PATH>`。 4. 命中 `$helloloop` 后，优先按上面的默认执行映射直接调用 CLI。 5. `HelloLoop` 会先明确执行引擎，再自动分析并输出执行确认单。 6. 用户确认后，`HelloLoop` 才开始正式自动执行。 如果无法自动判断仓库路径或开发文档路径，就停下来提示用户补充；`--repo` 和 `--docs` 只作为显式覆盖选项使用。 ## 工作模式 - 代码是事实源，开发文档是目标源。 - `HelloLoop` 会先分析当前真实进度，再生成或刷新 `.helloloop/backlog.json`。 - 分析后会展示中文执行确认单，明确告知路径判断、语义理解、项目匹配、当前进度、待办任务、验证命令和执行边界。 - 用户确认后，默认会持续执行到 backlog 清空且主线终态复核通过，或开发文档的最终目标完成且测试、验收通过，或遇到硬阻塞。 - 每个任务在执行引擎声称“完成”后，还必须再过一层任务完成复核；如果只是部分完成，继续当前主线任务，不直接结束。 - 用户需求明确且当前任务可直接完成时，必须一次性完成本轮应交付的全部工作；禁止做一半后用“如果你要”“是否继续”之类的话术停下，也禁止用客套套话收尾。 - 真正的代码分析与实现由本轮选中的 `codex` / `claude` / `gemini` CLI 原生完成。 - 如果当前引擎在运行中遇到 400、鉴权、余额、429、5xx、网络抖动、流中断或长时间卡死，必须优先按无人值守策略做同引擎“健康探测 + 条件恢复”，不要中途停下来询问用户，也不要自动切换引擎。 - 只有当硬阻塞或软阻塞的自动恢复额度真正用尽时，才允许结束本轮自动执行；若用户已在 `~/.helloloop/settings.json` 配置邮箱通知，则结束前发送告警邮件。 - `$helloloop` 的职责是把用户请求路由到主 CLI 流程，而不是在对话里手工复刻一套平行流程。 ## 核心命令 - `npx helloloop` - `npx helloloop <PATH>` - `npx helloloop codex` - `npx helloloop claude <PATH>` - `npx helloloop gemini <PATH> <补充说明>` - `npx helloloop <PATH> <补充说明>` - `npx helloloop --dry-run` - `npx helloloop -y` - `npx helloloop --rebuild-existing` ## 手动控制命令 - `npx helloloop status` - `npx helloloop next` - `npx helloloop run-once` - `npx helloloop run-loop --max-tasks <n>` - `npx helloloop doctor` - `npx helloloop init` - `npx helloloop install --host all` - `npx helloloop uninstall --host all` ## 调用方式 - 在官方 Codex 插件模式下，明确的 skill 名称是 `helloloop:helloloop`。 - 在对话里显式提到 `helloloop` 插件，也会帮助 Codex 更准确地命中这个 skill。 ## 参考文档 - 主说明：`README.md` - 安装说明：`docs/install.md` - Bundle 说明：`docs/README.md` - 插件标准映射：`docs/plugin-standard.md`