helloloop 0.2.1 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (25) hide show
  1. package/.claude-plugin/plugin.json +1 -1
  2. package/.codex-plugin/plugin.json +1 -1
  3. package/README.md +228 -279
  4. package/hosts/claude/marketplace/plugins/helloloop/.claude-plugin/plugin.json +1 -1
  5. package/hosts/claude/marketplace/plugins/helloloop/commands/helloloop.md +16 -9
  6. package/hosts/claude/marketplace/plugins/helloloop/skills/helloloop/SKILL.md +4 -1
  7. package/hosts/gemini/extension/GEMINI.md +8 -4
  8. package/hosts/gemini/extension/commands/helloloop.toml +15 -8
  9. package/hosts/gemini/extension/gemini-extension.json +1 -1
  10. package/package.json +2 -2
  11. package/scripts/uninstall-home-plugin.ps1 +25 -0
  12. package/skills/helloloop/SKILL.md +28 -3
  13. package/src/analyze_confirmation.mjs +79 -3
  14. package/src/analyze_prompt.mjs +12 -0
  15. package/src/analyze_user_input.mjs +303 -0
  16. package/src/analyzer.mjs +38 -0
  17. package/src/cli.mjs +211 -25
  18. package/src/cli_support.mjs +90 -23
  19. package/src/discovery.mjs +243 -9
  20. package/src/discovery_inference.mjs +62 -18
  21. package/src/discovery_paths.mjs +143 -8
  22. package/src/discovery_prompt.mjs +298 -0
  23. package/src/install.mjs +153 -0
  24. package/src/rebuild.mjs +116 -0
  25. package/templates/analysis-output.schema.json +58 -0
package/README.md CHANGED
@@ -1,414 +1,357 @@
1
1
  # HelloLoop
2
2
 
3
- `HelloLoop` 是一个面向 `Codex CLI`、`Claude Code`、`Gemini CLI` 的多宿主开发工作流插件，用来把“根据开发文档持续接续开发”变成一条可分析、可确认、可验证、可追踪的标准流程。
3
+ `HelloLoop` 是一个面向 `Codex CLI`、`Claude Code`、`Gemini CLI` 的多宿主开发工作流插件，用来把“根据开发文档持续接续开发、测试、验收直到最终目标完成”收敛成一条统一、可确认、可追踪的标准流程。
4
4
 
5
- 它有两层定位：
5
+ 它的定位很明确：
6
6
 
7
7
  - `Codex CLI`：首发平台、参考实现、最佳体验路径
8
8
  - `Claude Code` / `Gemini CLI`：各自按原生 agent 逻辑执行，但共享同一套 `.helloloop/` 工作流规范
9
+ - 三家都能安装、都能用、都原生执行开发，不是让一家的 CLI 去伪装成另一家
9
10
 
10
- Codex 路径的主工作流只有两种 CLI 入口：
11
+ ## 核心价值
11
12
 
12
- ```bash
13
- npx helloloop
14
- npx helloloop <PATH>
15
- ```
16
-
17
- 无论从哪个宿主进入，`HelloLoop` 都遵循同一条主线：
13
+ - **一条主命令**：优先只用 `npx helloloop` 或 `npx helloloop <PATH>`
14
+ - **自动补全上下文**：自动识别开发文档、项目仓库、当前进度和偏差
15
+ - **先确认再执行**：真正改代码前先输出中文执行确认单
16
+ - **持续推进到底**：确认后继续开发、测试、验收，直到完成最终目标或遇到硬阻塞
17
+ - **跨宿主统一状态**：运行状态统一写入目标仓库根目录的 `.helloloop/`
18
+ - **跨平台安全**：兼容 Windows / macOS / Linux，Windows 不回退到 `cmd.exe`
18
19
 
19
- 1. 自动识别项目仓库与开发文档
20
- 2. 分析当前代码与文档目标的真实差距
21
- 3. 生成或刷新目标仓库根目录下的 `.helloloop/`
22
- 4. 输出中文执行确认单
23
- 5. 用户确认后，继续按当前宿主的原生 agent 逻辑推进开发、测试和验收
20
+ ## 支持矩阵
24
21
 
25
- ## 目录
22
+ | 宿主 | 安装方式 | 原生入口 | 执行方式 |
23
+ | --- | --- | --- | --- |
24
+ | `Codex CLI` | `helloloop install --host codex` | `$helloloop` / `npx helloloop` | Codex 原生插件 + CLI |
25
+ | `Claude Code` | `helloloop install --host claude` | `/helloloop` | Claude 原生 marketplace / plugin |
26
+ | `Gemini CLI` | `helloloop install --host gemini` | `/helloloop` | Gemini 原生 extension |
26
27
 
27
- - [核心流程](#核心流程)
28
- - [支持矩阵](#支持矩阵)
29
- - [安装](#安装)
30
- - [快速开始](#快速开始)
31
- - [自动发现规则](#自动发现规则)
32
- - [自动执行边界](#自动执行边界)
33
- - [Doctor 检查](#doctor-检查)
34
- - [命令速查](#命令速查)
35
- - [状态目录](#状态目录)
36
- - [Skill 用法](#skill-用法)
37
- - [在 Codex 中使用](#在-codex-中使用)
38
- - [跨平台与安全](#跨平台与安全)
39
- - [仓库结构](#仓库结构)
40
- - [许可证](#许可证)
28
+ ## 默认工作流
41
29
 
42
- ## 核心流程
30
+ 无论从哪个宿主进入，`HelloLoop` 都遵循同一条主线：
43
31
 
44
- `HelloLoop` 的默认流程固定为 5 步：
32
+ 1. 自动识别目标项目仓库与开发文档
33
+ 2. 分析“代码当前做到哪里了”“与文档目标是否有偏差”“当前项目是否匹配文档目标”
34
+ 3. 在目标仓库根目录创建或刷新 `.helloloop/`
35
+ 4. 输出中文执行确认单
36
+ 5. 用户确认后，按当前宿主的原生 agent 逻辑继续推进开发、测试和验收
45
37
 
46
- 1. 自动发现项目仓库与开发文档
47
- 2. 对比文档目标与当前代码，识别当前进度和偏差
48
- 3. 生成或刷新目标仓库根目录下的 `.helloloop/`
49
- 4. 输出执行确认单，明确展示仓库、文档、当前进度、待办任务、验证命令和执行边界
50
- 5. 用户确认后，自动推进后续开发、测试和验收，直到全部完成或遇到硬阻塞
38
+ 如果分析发现当前实现已经偏离开发文档，`HelloLoop` 会优先先收口偏差，再继续后面的 backlog。
51
39
 
52
- 如果分析识别出偏差修正任务，`HelloLoop` 会优先先收口偏差，再继续后面的开发任务。
40
+ ## 最短使用方式
53
41
 
54
- 工作流统一，但执行器分为两类：
42
+ 推荐优先只记住下面两条：
55
43
 
56
- - `Codex CLI`：通过 `npx helloloop` / `$helloloop` 进入，使用当前仓库内的 Node CLI 与 Codex 插件链路
57
- - `Claude Code` / `Gemini CLI`：通过 `/helloloop` 进入，使用各自原生插件 / 扩展与 agent 工具链
44
+ ```bash
45
+ npx helloloop
46
+ npx helloloop <PATH>
47
+ ```
58
48
 
59
- ## 支持矩阵
49
+ 也支持在命令后继续附带路径和自然语言要求：
60
50
 
61
- | 宿主 | 安装方式 | 原生使用入口 | 当前定位 |
62
- | --- | --- | --- | --- |
63
- | `Codex CLI` | `helloloop install --host codex` | `$helloloop` / `npx helloloop` | 首发平台、参考实现、最佳体验 |
64
- | `Claude Code` | `helloloop install --host claude` | `/helloloop` | Claude 原生插件工作流 |
65
- | `Gemini CLI` | `helloloop install --host gemini` | `/helloloop` | Gemini 原生扩展工作流 |
51
+ ```bash
52
+ npx helloloop <PATH> <补充说明>
53
+ ```
66
54
 
67
- 如果你希望一次性装好三家宿主：
55
+ 例如：
68
56
 
69
57
  ```bash
70
- npx helloloop install --host all
58
+ npx helloloop docs/plan.md ./demo-app 接续完成剩余开发内容，并严格执行测试和验收
71
59
  ```
72
60
 
73
- ## 安装
61
+ 这里的 `<PATH>` 可以是：
74
62
 
75
- ### npm / npx
63
+ - 项目仓库路径
64
+ - 开发文档目录
65
+ - 开发文档文件
76
66
 
77
- 默认安装 `Codex` 宿主：
67
+ 这里的 `<补充说明>` 可以是：
78
68
 
79
- ```bash
80
- npx helloloop install --codex-home <CODEX_HOME>
81
- ```
69
+ - 第二个显式路径
70
+ - 本次执行的额外要求
71
+ - 偏差修正、质量要求、交付目标等自然语言说明
82
72
 
83
- 安装到指定宿主：
73
+ ## 自动发现与交互逻辑
84
74
 
85
- ```bash
86
- npx helloloop install --host codex
87
- npx helloloop install --host claude
88
- npx helloloop install --host gemini
89
- npx helloloop install --host all
90
- ```
75
+ ### 1. 只输入 `npx helloloop`
91
76
 
92
- 可选 home 参数：
77
+ 如果你只输入：
93
78
 
94
79
  ```bash
95
- --codex-home <CODEX_HOME>
96
- --claude-home <CLAUDE_HOME>
97
- --gemini-home <GEMINI_HOME>
80
+ npx helloloop
98
81
  ```
99
82
 
100
- ### 源码仓库
83
+ `HelloLoop` 会先快速扫描当前目录：
101
84
 
102
- ```bash
103
- node ./scripts/helloloop.mjs install --codex-home <CODEX_HOME>
104
- ```
85
+ - 当前目录本身就是项目仓库或开发文档目录时，直接进入分析
86
+ - 当前目录更像“工作区”时，优先尝试使用顶层开发文档，再提示选择候选项目目录
87
+ - 当前目录没有明确开发文档时，不会直接报错，而是先列出：
88
+ - 顶层文档文件
89
+ - 顶层目录
90
+ - 疑似项目目录
91
+ 然后再询问开发文档路径
105
92
 
106
- Windows PowerShell 也可以直接运行：
93
+ ### 2. 项目路径只问一次
107
94
 
108
- ```powershell
109
- pwsh -NoLogo -NoProfile -File .\scripts\install-home-plugin.ps1 -CodexHome <CODEX_HOME>
110
- ```
95
+ 对外只有“项目路径”这一个概念，不单独再追问“新项目路径”。
111
96
 
112
- 安装完成后：
97
+ - 你输入已有目录 → 按现有项目继续分析
98
+ - 你输入不存在的目录 → 视为准备创建的新项目目录
113
99
 
114
- - Codex 会写入 `<CODEX_HOME>/plugins/helloloop`
115
- - Claude 会写入 `<CLAUDE_HOME>/plugins/marketplaces/helloloop-local`，并生成 `<CLAUDE_HOME>/plugins/cache/helloloop-local/helloloop/<VERSION>`
116
- - Gemini 会写入 `<GEMINI_HOME>/extensions/helloloop`
100
+ 也就是说，用户只需要提供一次项目路径。
117
101
 
118
- 如果你想在安装后做一次全宿主环境检查：
102
+ ### 3. 文档和项目缺一不可时会停下询问
119
103
 
120
- ```bash
121
- npx helloloop doctor --host all
122
- ```
104
+ 以下情况不会硬猜：
123
105
 
124
- ## 快速开始
106
+ - 给了开发文档，但无法定位项目仓库
107
+ - 给了项目路径，但无法定位开发文档
108
+ - 同时出现多个冲突的文档路径或项目路径
125
109
 
126
- ### 1. 选择宿主入口
110
+ 此时 `HelloLoop` 会暂停，并要求用户补充正确信息。
127
111
 
128
- ```text
129
- Codex -> $helloloop / npx helloloop
130
- Claude -> /helloloop
131
- Gemini -> /helloloop
132
- ```
112
+ ### 4. 命令 + 自然语言会一起分析
133
113
 
134
- 说明：
114
+ `HelloLoop` 不依赖固定中文关键词来做硬编码分流。
135
115
 
136
- - `Codex` 路径下，`$helloloop` 与 `npx helloloop` 对齐同一主流程
137
- - `Claude` 与 `Gemini` 路径下，`/helloloop` 会走各自原生 agent 执行逻辑
138
- - 三家都会维护同一个 `.helloloop/` 状态目录规范
116
+ 命令里的：
139
117
 
140
- ### 2. 进入项目仓库或开发文档目录
118
+ - 显式路径
119
+ - 中文自然语言
120
+ - 英文自然语言
121
+ - 其他语言的补充要求
141
122
 
142
- 最短命令：
123
+ 都会一起进入分析与确认单，不会因为语言不同被静默忽略。
143
124
 
144
- ```bash
145
- npx helloloop
146
- ```
125
+ ### 5. 现有项目与文档目标冲突时
126
+
127
+ 如果当前项目目录已存在，但分析认为它与开发文档目标明显冲突，`HelloLoop` 不会直接清空目录，而是先提示你选择：
128
+
129
+ 1. 继续在当前项目上尝试接续
130
+ 2. 清理当前项目内容后按文档目标重建
131
+ 3. 取消本次执行
147
132
 
148
- 如果你只知道一个路径，也可以只传一个：
133
+ 如果你明确希望非交互模式下直接重建，可以使用：
149
134
 
150
135
  ```bash
151
- npx helloloop <PATH>
136
+ npx helloloop --rebuild-existing
152
137
  ```
153
138
 
154
- 这里的 `<PATH>` 可以是：
139
+ 重建时会保留必要的仓库元数据和状态目录，例如 `.git`、`.gitignore`、`.gitattributes`、`.helloagents`、`.helloloop`。
155
140
 
156
- - 项目仓库路径
157
- - 开发文档目录
158
- - 开发文档文件
141
+ ## 执行确认单
159
142
 
160
- ### 3. 查看执行确认单
143
+ 真正开始开发前，`HelloLoop` 会先输出中文执行确认单。当前确认单至少包含：
161
144
 
162
- 分析完成后，`HelloLoop` 会展示一份执行确认单，至少包含：
163
-
164
- - 识别出的目标仓库
165
- - 识别出的开发文档
166
- - 当前进度摘要
145
+ - 路径判断与判断依据
146
+ - 本次命令补充输入
147
+ - 需求语义理解
148
+ - 项目匹配判断
149
+ - 目标仓库
150
+ - 开发文档
151
+ - 当前进度
167
152
  - 已实现事项
168
153
  - 待完成事项
169
154
  - 任务统计
170
155
  - 首个待执行任务
171
156
  - 验证命令预览
172
- - 自动推进边界
173
-
174
- ### 4. 确认后自动继续执行
157
+ - 自动执行停止条件
175
158
 
176
- 你确认后，`HelloLoop` 会：
159
+ 未确认前，不会正式修改代码。
177
160
 
178
- - 按 backlog 顺序自动推进
179
- - 每个任务都走当前宿主的原生 agent 执行与验证
180
- - 遇到失败、风险超阈值、依赖未满足或环境硬阻塞时立即停下
181
- - 把分析结果、状态和运行记录都写进目标仓库的 `.helloloop/`
161
+ ## 安装
182
162
 
183
- 如果你已经做了全局安装，也可以把 `npx helloloop` 简写成 `helloloop`。
163
+ ### npm / npx
184
164
 
185
- 如果你想手动查看或接管某一步，也可以使用：
165
+ 默认安装到 `Codex`：
186
166
 
187
167
  ```bash
188
- npx helloloop status
189
- npx helloloop next
190
- npx helloloop run-once
168
+ npx helloloop install --codex-home <CODEX_HOME>
191
169
  ```
192
170
 
193
- ## 自动发现规则
194
-
195
- - 不传路径：默认分析当前目录
196
- - 只传一个路径：自动判断它是仓库路径还是开发文档路径
197
- - 当前目录是仓库：自动查找开发文档
198
- - 当前目录是文档目录：自动尝试反推目标仓库
199
- - 只给开发文档但无法推断仓库：停止并提示补充 `--repo`
200
- - 只给仓库但找不到开发文档：停止并提示补充 `--docs`
201
-
202
- 推荐始终优先使用：
171
+ 安装到指定宿主：
203
172
 
204
173
  ```bash
205
- npx helloloop
206
- npx helloloop <PATH>
174
+ npx helloloop install --host codex
175
+ npx helloloop install --host claude
176
+ npx helloloop install --host gemini
177
+ npx helloloop install --host all
207
178
  ```
208
179
 
209
- 只有自动发现无法收敛时，再补充高级参数：
180
+ 可选 home 参数：
210
181
 
211
182
  ```bash
212
- npx helloloop --repo <REPO_ROOT> --docs <DOCS_PATH>
183
+ --codex-home <CODEX_HOME>
184
+ --claude-home <CLAUDE_HOME>
185
+ --gemini-home <GEMINI_HOME>
213
186
  ```
214
187
 
215
- ## 自动执行边界
216
-
217
- 默认主命令会在确认后尽量自动完成整轮 backlog，而不是只跑一个任务。
218
-
219
- ### 常用执行模式
188
+ ### 从源码仓库安装
220
189
 
221
190
  ```bash
222
- npx helloloop
223
- npx helloloop <PATH>
224
- npx helloloop --dry-run
225
- npx helloloop -y
191
+ node ./scripts/helloloop.mjs install --host codex
226
192
  ```
227
193
 
228
- 含义如下：
229
-
230
- - `npx helloloop`：分析 → 展示确认单 → 等待你确认 → 自动执行
231
- - `npx helloloop <PATH>`：同上，但先用你给的单一路径做自动识别
232
- - `npx helloloop --dry-run`：只分析并输出确认单，不真正开始执行
233
- - `npx helloloop -y`：跳过交互确认，分析后直接自动执行
234
-
235
- ### 停止条件
236
-
237
- 出现以下情况时，`HelloLoop` 会停止并保留现场，而不是静默降级：
238
-
239
- - 无法自动确定目标仓库或开发文档
240
- - backlog 已存在失败任务、阻塞任务或未满足依赖
241
- - 后续任务风险超出自动阈值，且你没有显式加 `--allow-high-risk`
242
- - 验证命令失败
243
- - 当前宿主 CLI、插件资产或 shell 环境不可安全执行
194
+ Windows PowerShell 也可以直接运行：
244
195
 
245
- ## Doctor 检查
196
+ ```powershell
197
+ pwsh -NoLogo -NoProfile -File .\scripts\install-home-plugin.ps1 -CodexHome <CODEX_HOME>
198
+ ```
246
199
 
247
- 你可以用 `doctor` 检查当前宿主是否已具备基本运行条件。
200
+ ### 升级、重装、切换分支
248
201
 
249
- ### 只检查 Codex
202
+ 如果你已经安装过，但刚拉取了新版本、切换了分支、或想覆盖旧安装，直接重新执行：
250
203
 
251
204
  ```bash
252
- npx helloloop doctor
205
+ npx helloloop install --host codex --force
206
+ npx helloloop install --host all --force
253
207
  ```
254
208
 
255
- ### 检查全部宿主
209
+ ### 卸载
256
210
 
257
211
  ```bash
258
- npx helloloop doctor --host all
212
+ npx helloloop uninstall --host codex
213
+ npx helloloop uninstall --host claude
214
+ npx helloloop uninstall --host gemini
215
+ npx helloloop uninstall --host all
259
216
  ```
260
217
 
261
- ### 检查已安装目录
218
+ ### 安装结果
262
219
 
263
- ```bash
264
- npx helloloop doctor --host all --codex-home <CODEX_HOME> --claude-home <CLAUDE_HOME> --gemini-home <GEMINI_HOME>
265
- ```
220
+ 安装完成后，运行时资产会写入：
266
221
 
267
- `doctor` 当前可检查：
222
+ - `Codex`：`<CODEX_HOME>/plugins/helloloop`
223
+ - `Claude`：`<CLAUDE_HOME>/plugins/marketplaces/helloloop-local` 与 `plugins/cache/helloloop-local/helloloop/<VERSION>`
224
+ - `Gemini`：`<GEMINI_HOME>/extensions/helloloop`
268
225
 
269
- - 宿主 CLI 是否存在
270
- - 本地运行时资产是否齐全
271
- - 目标仓库 `.helloloop/` 基础文件是否存在
272
- - 已安装宿主目录是否已写入对应插件 / 扩展
226
+ 源码仓库里的 `docs/` 与 `tests/` 不会复制进运行时安装包。
273
227
 
274
- ## 命令速查
228
+ ## 使用入口
275
229
 
276
- | 命令 | 作用 |
277
- | --- | --- |
278
- | `analyze` | 主工作流；分析并输出确认单，确认后自动接续执行 |
279
- | `status` | 查看 backlog 汇总与当前状态 |
280
- | `next` | 预览下一任务，不真正执行 |
281
- | `run-once` | 手动执行一个任务 |
282
- | `run-loop` | 手动连续执行多个任务 |
283
- | `doctor` | 检查所选宿主、运行时资产与目标仓库是否满足运行条件 |
284
- | `init` | 手动初始化 `.helloloop/` 模板 |
285
- | `install` | 安装插件到所选宿主目录 |
286
-
287
- ### 常用选项
288
-
289
- | 选项 | 说明 |
290
- | --- | --- |
291
- | `-y`, `--yes` | 跳过交互确认，分析后直接开始执行 |
292
- | `--dry-run` | 只分析并输出确认单，不真正开始执行 |
293
- | `--host <name>` | 选择安装宿主：`codex`、`claude`、`gemini`、`all` |
294
- | `--repo <dir>` | 高级选项：显式指定项目仓库根目录 |
295
- | `--docs <dir\|file>` | 高级选项：显式指定开发文档目录或文件 |
296
- | `--allow-high-risk` | 允许执行 `medium` 及以上风险任务 |
297
- | `--max-tasks <n>` | 限制手动 `run-loop` 的最大任务数 |
298
- | `--max-attempts <n>` | 单策略最大重试次数 |
299
- | `--max-strategies <n>` | 单任务最大换路次数 |
300
- | `--required-doc <path>` | 追加全局必读文档 |
301
- | `--constraint <text>` | 追加全局实现约束 |
302
- | `--codex-home <dir>` | 指定 Codex Home |
303
- | `--claude-home <dir>` | 指定 Claude Home |
304
- | `--gemini-home <dir>` | 指定 Gemini Home |
305
- | `--config-dir <dir>` | 指定状态目录名，默认 `.helloloop` |
306
- | `--force` | 覆盖已有安装目录 |
307
-
308
- ## 状态目录
309
-
310
- `HelloLoop` 始终把运行状态写入目标仓库根目录，而不是插件目录自身。
311
-
312
- 默认目录：
230
+ ### Codex CLI
313
231
 
314
232
  ```text
315
- .helloloop/
316
- ├── backlog.json
317
- ├── policy.json
318
- ├── project.json
319
- ├── status.json
320
- ├── STATE.md
321
- └── runs/
233
+ $helloloop
322
234
  ```
323
235
 
324
- 其中：
236
+ 或：
325
237
 
326
- - `backlog.json`：分析后生成的任务队列
327
- - `policy.json`：自动推进策略、重试上限和 Codex 参数
328
- - `project.json`：开发文档入口和全局约束
329
- - `status.json`：最近一次运行状态
330
- - `STATE.md`：面向人的进度摘要
331
- - `runs/`：提示词、stdout、stderr、验证日志等留痕
238
+ ```bash
239
+ npx helloloop
240
+ npx helloloop <PATH>
241
+ ```
332
242
 
333
- ## Skill 用法
243
+ `$helloloop` 的推荐行为与主命令保持一致：优先进入 `npx helloloop` 主流程，而不是在对话里手工模拟分析和续跑。
334
244
 
335
- 如果你已经把 `HelloLoop` 安装成 Codex 插件，也可以直接在 Codex 里调用：
245
+ 如果你显式使用技能名，也可以写：
336
246
 
337
247
  ```text
338
- $helloloop
248
+ helloloop:helloloop
339
249
  ```
340
250
 
341
- 或：
251
+ ### Claude Code / Gemini CLI
342
252
 
343
253
  ```text
344
- helloloop:helloloop
254
+ /helloloop
345
255
  ```
346
256
 
347
- 此时推荐理解为：
257
+ 它们会按各自 CLI 的原生 agent 逻辑执行，但共享同一套 `.helloloop/` 工作流规范。
348
258
 
349
- - `$helloloop` 是插件入口
350
- - `npx helloloop` / `npx helloloop <PATH>` 是实际执行入口
259
+ ## 命令速查
351
260
 
352
- 也就是说，用户显式调用 `$helloloop` 时，目标行为应当与主命令保持一致：
261
+ | 命令 | 作用 |
262
+ | --- | --- |
263
+ | `helloloop` / `analyze` | 自动分析、展示确认单，并在确认后继续接续开发 |
264
+ | `install` | 安装运行时 bundle 到指定宿主 |
265
+ | `uninstall` | 从指定宿主卸载运行时 bundle 与注册信息 |
266
+ | `doctor` | 检查宿主环境、插件资产与目标仓库状态 |
267
+ | `init` | 手动初始化 `.helloloop/` 模板 |
268
+ | `status` | 查看 backlog 摘要和当前状态 |
269
+ | `next` | 生成下一任务的干跑预览 |
270
+ | `run-once` | 执行一个任务 |
271
+ | `run-loop` | 连续执行多个任务 |
353
272
 
354
- 1. 先自动识别仓库和开发文档
355
- 2. 再分析当前代码与文档目标
356
- 3. 再展示执行确认单
357
- 4. 最后在你确认后自动接续执行
273
+ 常用选项：
358
274
 
359
- 如果当前目录无法判断目标仓库、缺少开发文档，或者你明确只想先讲解不执行，`HelloLoop` 才应该先停下来问你，而不是直接启动执行。
275
+ | 选项 | 作用 |
276
+ | --- | --- |
277
+ | `--dry-run` | 只分析并输出确认单，不开始自动执行 |
278
+ | `-y` / `--yes` | 跳过交互确认，分析后直接执行 |
279
+ | `--repo <dir>` | 高级覆盖：显式指定项目仓库 |
280
+ | `--docs <dir|file>` | 高级覆盖：显式指定开发文档 |
281
+ | `--rebuild-existing` | 项目与文档冲突时，自动清理现有项目后重建 |
282
+ | `--host <name>` | 宿主：`codex` / `claude` / `gemini` / `all` |
283
+ | `--config-dir <dir>` | 状态目录名，默认 `.helloloop` |
360
284
 
361
- 如果你安装的是 Claude 或 Gemini 宿主，则推荐直接使用：
285
+ 手动控制示例：
362
286
 
363
- ```text
364
- /helloloop
287
+ ```bash
288
+ npx helloloop status
289
+ npx helloloop next
290
+ npx helloloop run-once
365
291
  ```
366
292
 
367
- 它们会按各自 CLI 的原生 agent 逻辑执行，但共享同一套 `.helloloop/` 工作流规范。
293
+ ## Doctor 检查
368
294
 
369
- ## 在 Codex 中使用
295
+ 检查默认宿主：
370
296
 
371
- 可以直接在当前 Codex 会话里运行：
297
+ ```bash
298
+ npx helloloop doctor
299
+ ```
300
+
301
+ 检查全部宿主：
372
302
 
373
303
  ```bash
374
- npx helloloop
304
+ npx helloloop doctor --host all
305
+ ```
306
+
307
+ 检查指定安装目录：
308
+
309
+ ```bash
310
+ npx helloloop doctor --host all --codex-home <CODEX_HOME> --claude-home <CLAUDE_HOME> --gemini-home <GEMINI_HOME>
375
311
  ```
376
312
 
377
- 不需要重开终端。
313
+ `doctor` 的检查范围分两类：
378
314
 
379
- 如果你使用的是全局安装后的 `helloloop` 短命令，是否立刻可用取决于当前 shell 是否已经刷新 PATH。
315
+ - 在插件源码仓库中运行：主要检查 CLI、bundle 资产和宿主安装资产
316
+ - 在目标项目仓库中运行，或显式传入 `--repo`：还会检查 `.helloloop/backlog.json`、`project.json`、`policy.json`、`verify.yaml`
380
317
 
381
- 安装为 Codex 插件后，推荐显式使用的 skill 名称是：
318
+ ## `.helloloop/` 状态目录
319
+
320
+ `HelloLoop` 的 backlog、状态和运行记录始终写入目标仓库根目录下的：
382
321
 
383
322
  ```text
384
- helloloop:helloloop
323
+ .helloloop/
324
+ ├── backlog.json
325
+ ├── policy.json
326
+ ├── project.json
327
+ ├── status.json
328
+ ├── STATE.md
329
+ └── runs/
385
330
  ```
386
331
 
387
- ## 跨平台与安全
332
+ 不会写回插件目录自身。
388
333
 
389
- `HelloLoop` 默认兼容 Windows、macOS 和 Linux。
390
-
391
- ### shell 策略
334
+ ## 跨平台与安全
392
335
 
393
- - Windows：`pwsh` → `bash`（如 Git Bash）→ `powershell`
394
- - macOS / Linux：`bash` → `sh`
395
- - Windows 不会回退到 `cmd.exe`
336
+ ### Windows
396
337
 
397
- 说明：
338
+ - 优先使用 `pwsh`
339
+ - 也支持 `bash`（如 Git Bash）与 `powershell`
340
+ - 不回退到 `cmd.exe`
341
+ - 避免危险的嵌套命令、路径拼接删除和 `cmd` 风格破坏性流程
398
342
 
399
- - `Codex` 路径由当前 Node CLI 严格控制 shell 选择
400
- - `Claude` / `Gemini` 路径走各自原生插件 / 扩展，但仍应遵守 `HelloLoop` 的安全约束
343
+ ### macOS / Linux
401
344
 
402
- ### 内建兜底规则
345
+ - 优先使用 `bash`
346
+ - 如果没有 `bash`，回退到 `sh`
403
347
 
404
- 当开发文档没有给出足够约束时，`HelloLoop` 会自动附加一层最低安全边界，包括但不限于：
348
+ ### 通用安全边界
405
349
 
406
- - 代码是事实源
407
- - 验证必须执行
408
- - 不能静默失败
409
- - 不能吞掉错误
410
- - 危险命令必须阻断
411
- - 路径与 shell 调用必须按跨平台安全方式执行
350
+ - 不静默失败
351
+ - 不静默回退
352
+ - 不吞掉错误
353
+ - 真正执行前先确认
354
+ - 真正结束前先验证
412
355
 
413
356
  ## 仓库结构
414
357
 
@@ -416,6 +359,8 @@ helloloop:helloloop
416
359
  helloloop/
417
360
  ├── .claude-plugin/
418
361
  ├── .codex-plugin/
362
+ ├── .github/
363
+ ├── .helloagents/
419
364
  ├── bin/
420
365
  ├── docs/
421
366
  ├── hosts/
@@ -423,18 +368,22 @@ helloloop/
423
368
  ├── skills/
424
369
  ├── src/
425
370
  ├── templates/
426
- └── tests/
371
+ ├── tests/
372
+ ├── LICENSE
373
+ ├── package.json
374
+ └── README.md
427
375
  ```
428
376
 
429
377
  其中：
430
378
 
431
- - `.claude-plugin/`：Claude plugin 元数据
432
- - `.codex-plugin/`：Codex plugin 元数据
433
- - `hosts/`：Claude marketplace/plugin 与 Gemini extension 的运行时资产
434
- - `src/`：核心实现，例如路径发现、分析提示词、任务调度、执行与安装
435
- - `tests/`：回归测试，覆盖 CLI、安装链路、bundle 结构和关键流程
436
- - `templates/`：初始化目标仓库 `.helloloop/` 时写入的模板
379
+ - `.codex-plugin/`：Codex 插件 manifest
380
+ - `.claude-plugin/`：Claude plugin manifest
381
+ - `hosts/`：Claude marketplace / Gemini extension 资产
382
+ - `skills/`：Codex 插件技能说明
383
+ - `src/`：发现、分析、执行、安装、卸载、doctor 等核心实现
384
+ - `templates/`：初始化目标仓库 `.helloloop/` 的模板
385
+ - `docs/` 与 `tests/`：源码仓库维护资料，不进入运行时安装包
437
386
 
438
387
  ## 许可证
439
388
 
440
- `HelloLoop` 使用 `Apache-2.0`，许可证文件位于仓库根目录 `LICENSE`。
389
+ `HelloLoop` 使用 `Apache-2.0`，许可证文件位于仓库根目录的 `LICENSE`。
package/hosts/claude/marketplace/plugins/helloloop/.claude-plugin/plugin.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "helloloop",
3
- "version": "0.2.1",
3
+ "version": "0.3.1",
4
4
  "description": "HelloLoop 的 Claude Code 原生插件。",
5
5
  "author": {
6
6
  "name": "HelloLoop"