helloloop 0.2.0 → 0.3.1

package/README.md

@@ -1,414 +1,357 @@
 # HelloLoop
 
-`HelloLoop` 是一个面向 `Codex CLI`、`Claude Code`、`Gemini CLI` 的多宿主开发工作流插件，用来把“根据开发文档持续接续开发”变成一条可分析、可确认、可验证、可追踪的标准流程。
+`HelloLoop` 是一个面向 `Codex CLI`、`Claude Code`、`Gemini CLI` 的多宿主开发工作流插件，用来把“根据开发文档持续接续开发、测试、验收直到最终目标完成”收敛成一条统一、可确认、可追踪的标准流程。
 
-它有两层定位：
+它的定位很明确：
 
 - `Codex CLI`：首发平台、参考实现、最佳体验路径
 - `Claude Code` / `Gemini CLI`：各自按原生 agent 逻辑执行，但共享同一套 `.helloloop/` 工作流规范
+- 三家都能安装、都能用、都原生执行开发，不是让一家的 CLI 去伪装成另一家
 
-Codex 路径的主工作流只有两种 CLI 入口：
+## 核心价值
 
-```bash
-npx helloloop
-npx helloloop <PATH>
-```
-
-无论从哪个宿主进入，`HelloLoop` 都遵循同一条主线：
+- **一条主命令**：优先只用 `npx helloloop` 或 `npx helloloop <PATH>`
+- **自动补全上下文**：自动识别开发文档、项目仓库、当前进度和偏差
+- **先确认再执行**：真正改代码前先输出中文执行确认单
+- **持续推进到底**：确认后继续开发、测试、验收，直到完成最终目标或遇到硬阻塞
+- **跨宿主统一状态**：运行状态统一写入目标仓库根目录的 `.helloloop/`
+- **跨平台安全**：兼容 Windows / macOS / Linux，Windows 不回退到 `cmd.exe`
 
-1. 自动识别项目仓库与开发文档
-2. 分析当前代码与文档目标的真实差距
-3. 生成或刷新目标仓库根目录下的 `.helloloop/`
-4. 输出中文执行确认单
-5. 用户确认后，继续按当前宿主的原生 agent 逻辑推进开发、测试和验收
+## 支持矩阵
 
-## 目录
+| 宿主 | 安装方式 | 原生入口 | 执行方式 |
+| --- | --- | --- | --- |
+| `Codex CLI` | `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 |
 
-- [核心流程](#核心流程)
-- [支持矩阵](#支持矩阵)
-- [安装](#安装)
-- [快速开始](#快速开始)
-- [自动发现规则](#自动发现规则)
-- [自动执行边界](#自动执行边界)
-- [Doctor 检查](#doctor-检查)
-- [命令速查](#命令速查)
-- [状态目录](#状态目录)
-- [Skill 用法](#skill-用法)
-- [在 Codex 中使用](#在-codex-中使用)
-- [跨平台与安全](#跨平台与安全)
-- [仓库结构](#仓库结构)
-- [许可证](#许可证)
+## 默认工作流
 
-## 核心流程
+无论从哪个宿主进入，`HelloLoop` 都遵循同一条主线：
 
-`HelloLoop` 的默认流程固定为 5 步：
+1. 自动识别目标项目仓库与开发文档
+2. 分析“代码当前做到哪里了”“与文档目标是否有偏差”“当前项目是否匹配文档目标”
+3. 在目标仓库根目录创建或刷新 `.helloloop/`
+4. 输出中文执行确认单
+5. 用户确认后，按当前宿主的原生 agent 逻辑继续推进开发、测试和验收
 
-1. 自动发现项目仓库与开发文档
-2. 对比文档目标与当前代码，识别当前进度和偏差
-3. 生成或刷新目标仓库根目录下的 `.helloloop/`
-4. 输出执行确认单，明确展示仓库、文档、当前进度、待办任务、验证命令和执行边界
-5. 用户确认后，自动推进后续开发、测试和验收，直到全部完成或遇到硬阻塞
+如果分析发现当前实现已经偏离开发文档，`HelloLoop` 会优先先收口偏差，再继续后面的 backlog。
 
-如果分析识别出偏差修正任务，`HelloLoop` 会优先先收口偏差，再继续后面的开发任务。
+## 最短使用方式
 
-工作流统一，但执行器分为两类：
+推荐优先只记住下面两条：
 
-- `Codex CLI`：通过 `npx helloloop` / `$helloloop` 进入，使用当前仓库内的 Node CLI 与 Codex 插件链路
-- `Claude Code` / `Gemini CLI`：通过 `/helloloop` 进入，使用各自原生插件 / 扩展与 agent 工具链
+```bash
+npx helloloop
+npx helloloop <PATH>
+```
 
-## 支持矩阵
+也支持在命令后继续附带路径和自然语言要求：
 
-| 宿主 | 安装方式 | 原生使用入口 | 当前定位 |
-| --- | --- | --- | --- |
-| `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 原生扩展工作流 |
+```bash
+npx helloloop <PATH> <补充说明>
+```
 
-如果你希望一次性装好三家宿主：
+例如：
 
 ```bash
-npx helloloop install --host all
+npx helloloop docs/plan.md ./demo-app 接续完成剩余开发内容，并严格执行测试和验收
 ```
 
-## 安装
+这里的 `<PATH>` 可以是：
 
-### npm / npx
+- 项目仓库路径
+- 开发文档目录
+- 开发文档文件
 
-默认安装 `Codex` 宿主：
+这里的 `<补充说明>` 可以是：
 
-```bash
-npx helloloop install --codex-home <CODEX_HOME>
-```
+- 第二个显式路径
+- 本次执行的额外要求
+- 偏差修正、质量要求、交付目标等自然语言说明
 
-安装到指定宿主：
+## 自动发现与交互逻辑
 
-```bash
-npx helloloop install --host codex
-npx helloloop install --host claude
-npx helloloop install --host gemini
-npx helloloop install --host all
-```
+### 1. 只输入 `npx helloloop`
 
-可选 home 参数：
+如果你只输入：
 
 ```bash
---codex-home <CODEX_HOME>
---claude-home <CLAUDE_HOME>
---gemini-home <GEMINI_HOME>
+npx helloloop
 ```
 
-### 源码仓库
+`HelloLoop` 会先快速扫描当前目录：
 
-```bash
-node ./scripts/helloloop.mjs install --codex-home <CODEX_HOME>
-```
+- 当前目录本身就是项目仓库或开发文档目录时，直接进入分析
+- 当前目录更像“工作区”时，优先尝试使用顶层开发文档，再提示选择候选项目目录
+- 当前目录没有明确开发文档时，不会直接报错，而是先列出：
+  - 顶层文档文件
+  - 顶层目录
+  - 疑似项目目录
+  然后再询问开发文档路径
 
-Windows PowerShell 也可以直接运行：
+### 2. 项目路径只问一次
 
-```powershell
-pwsh -NoLogo -NoProfile -File .\scripts\install-home-plugin.ps1 -CodexHome <CODEX_HOME>
-```
+对外只有“项目路径”这一个概念，不单独再追问“新项目路径”。
 
-安装完成后：
+- 你输入已有目录 → 按现有项目继续分析
+- 你输入不存在的目录 → 视为准备创建的新项目目录
 
-- Codex 会写入 `<CODEX_HOME>/plugins/helloloop`
-- Claude 会写入 `<CLAUDE_HOME>/marketplaces/helloloop-local`
-- Gemini 会写入 `<GEMINI_HOME>/extensions/helloloop`
+也就是说，用户只需要提供一次项目路径。
 
-如果你想在安装后做一次全宿主环境检查：
+### 3. 文档和项目缺一不可时会停下询问
 
-```bash
-npx helloloop doctor --host all
-```
+以下情况不会硬猜：
 
-## 快速开始
+- 给了开发文档，但无法定位项目仓库
+- 给了项目路径，但无法定位开发文档
+- 同时出现多个冲突的文档路径或项目路径
 
-### 1. 选择宿主入口
+此时 `HelloLoop` 会暂停，并要求用户补充正确信息。
 
-```text
-Codex   -> $helloloop / npx helloloop
-Claude  -> /helloloop
-Gemini  -> /helloloop
-```
+### 4. 命令 + 自然语言会一起分析
 
-说明：
+`HelloLoop` 不依赖固定中文关键词来做硬编码分流。
 
-- `Codex` 路径下，`$helloloop` 与 `npx helloloop` 对齐同一主流程
-- `Claude` 与 `Gemini` 路径下，`/helloloop` 会走各自原生 agent 执行逻辑
-- 三家都会维护同一个 `.helloloop/` 状态目录规范
+命令里的：
 
-### 2. 进入项目仓库或开发文档目录
+- 显式路径
+- 中文自然语言
+- 英文自然语言
+- 其他语言的补充要求
 
-最短命令：
+都会一起进入分析与确认单，不会因为语言不同被静默忽略。
 
-```bash
-npx helloloop
-```
+### 5. 现有项目与文档目标冲突时
+
+如果当前项目目录已存在，但分析认为它与开发文档目标明显冲突，`HelloLoop` 不会直接清空目录，而是先提示你选择：
+
+1. 继续在当前项目上尝试接续
+2. 清理当前项目内容后按文档目标重建
+3. 取消本次执行
 
-如果你只知道一个路径，也可以只传一个：
+如果你明确希望非交互模式下直接重建，可以使用：
 
 ```bash
-npx helloloop <PATH>
+npx helloloop --rebuild-existing
 ```
 
-这里的 `<PATH>` 可以是：
+重建时会保留必要的仓库元数据和状态目录，例如 `.git`、`.gitignore`、`.gitattributes`、`.helloagents`、`.helloloop`。
 
-- 项目仓库路径
-- 开发文档目录
-- 开发文档文件
+## 执行确认单
 
-### 3. 查看执行确认单
+真正开始开发前，`HelloLoop` 会先输出中文执行确认单。当前确认单至少包含：
 
-分析完成后，`HelloLoop` 会展示一份执行确认单，至少包含：
-
-- 识别出的目标仓库
-- 识别出的开发文档
-- 当前进度摘要
+- 路径判断与判断依据
+- 本次命令补充输入
+- 需求语义理解
+- 项目匹配判断
+- 目标仓库
+- 开发文档
+- 当前进度
 - 已实现事项
 - 待完成事项
 - 任务统计
 - 首个待执行任务
 - 验证命令预览
-- 自动推进边界
-
-### 4. 确认后自动继续执行
+- 自动执行停止条件
 
-你确认后，`HelloLoop` 会：
+未确认前，不会正式修改代码。
 
-- 按 backlog 顺序自动推进
-- 每个任务都走当前宿主的原生 agent 执行与验证
-- 遇到失败、风险超阈值、依赖未满足或环境硬阻塞时立即停下
-- 把分析结果、状态和运行记录都写进目标仓库的 `.helloloop/`
+## 安装
 
-如果你已经做了全局安装，也可以把 `npx helloloop` 简写成 `helloloop`。
+### npm / npx
 
-如果你想手动查看或接管某一步，也可以使用：
+默认安装到 `Codex`：
 
 ```bash
-npx helloloop status
-npx helloloop next
-npx helloloop run-once
+npx helloloop install --codex-home <CODEX_HOME>
 ```
 
-## 自动发现规则
-
-- 不传路径：默认分析当前目录
-- 只传一个路径：自动判断它是仓库路径还是开发文档路径
-- 当前目录是仓库：自动查找开发文档
-- 当前目录是文档目录：自动尝试反推目标仓库
-- 只给开发文档但无法推断仓库：停止并提示补充 `--repo`
-- 只给仓库但找不到开发文档：停止并提示补充 `--docs`
-
-推荐始终优先使用：
+安装到指定宿主：
 
 ```bash
-npx helloloop
-npx helloloop <PATH>
+npx helloloop install --host codex
+npx helloloop install --host claude
+npx helloloop install --host gemini
+npx helloloop install --host all
 ```
 
-只有自动发现无法收敛时，再补充高级参数：
+可选 home 参数：
 
 ```bash
-npx helloloop --repo <REPO_ROOT> --docs <DOCS_PATH>
+--codex-home <CODEX_HOME>
+--claude-home <CLAUDE_HOME>
+--gemini-home <GEMINI_HOME>
 ```
 
-## 自动执行边界
-
-默认主命令会在确认后尽量自动完成整轮 backlog，而不是只跑一个任务。
-
-### 常用执行模式
+### 从源码仓库安装
 
 ```bash
-npx helloloop
-npx helloloop <PATH>
-npx helloloop --dry-run
-npx helloloop -y
+node ./scripts/helloloop.mjs install --host codex
 ```
 
-含义如下：
-
-- `npx helloloop`：分析 → 展示确认单 → 等待你确认 → 自动执行
-- `npx helloloop <PATH>`：同上，但先用你给的单一路径做自动识别
-- `npx helloloop --dry-run`：只分析并输出确认单，不真正开始执行
-- `npx helloloop -y`：跳过交互确认，分析后直接自动执行
-
-### 停止条件
-
-出现以下情况时，`HelloLoop` 会停止并保留现场，而不是静默降级：
-
-- 无法自动确定目标仓库或开发文档
-- backlog 已存在失败任务、阻塞任务或未满足依赖
-- 后续任务风险超出自动阈值，且你没有显式加 `--allow-high-risk`
-- 验证命令失败
-- 当前宿主 CLI、插件资产或 shell 环境不可安全执行
+Windows PowerShell 也可以直接运行：
 
-## Doctor 检查
+```powershell
+pwsh -NoLogo -NoProfile -File .\scripts\install-home-plugin.ps1 -CodexHome <CODEX_HOME>
+```
 
-你可以用 `doctor` 检查当前宿主是否已具备基本运行条件。
+### 升级、重装、切换分支
 
-### 只检查 Codex
+如果你已经安装过，但刚拉取了新版本、切换了分支、或想覆盖旧安装，直接重新执行：
 
 ```bash
-npx helloloop doctor
+npx helloloop install --host codex --force
+npx helloloop install --host all --force
 ```
 
-### 检查全部宿主
+### 卸载
 
 ```bash
-npx helloloop doctor --host all
+npx helloloop uninstall --host codex
+npx helloloop uninstall --host claude
+npx helloloop uninstall --host gemini
+npx helloloop uninstall --host all
 ```
 
-### 检查已安装目录
+### 安装结果
 
-```bash
-npx helloloop doctor --host all --codex-home <CODEX_HOME> --claude-home <CLAUDE_HOME> --gemini-home <GEMINI_HOME>
-```
+安装完成后，运行时资产会写入：
 
-`doctor` 当前可检查：
+- `Codex`：`<CODEX_HOME>/plugins/helloloop`
+- `Claude`：`<CLAUDE_HOME>/plugins/marketplaces/helloloop-local` 与 `plugins/cache/helloloop-local/helloloop/<VERSION>`
+- `Gemini`：`<GEMINI_HOME>/extensions/helloloop`
 
-- 宿主 CLI 是否存在
-- 本地运行时资产是否齐全
-- 目标仓库 `.helloloop/` 基础文件是否存在
-- 已安装宿主目录是否已写入对应插件 / 扩展
+源码仓库里的 `docs/` 与 `tests/` 不会复制进运行时安装包。
 
-## 命令速查
+## 使用入口
 
-| 命令 | 作用 |
-| --- | --- |
-| `analyze` | 主工作流；分析并输出确认单，确认后自动接续执行 |
-| `status` | 查看 backlog 汇总与当前状态 |
-| `next` | 预览下一任务，不真正执行 |
-| `run-once` | 手动执行一个任务 |
-| `run-loop` | 手动连续执行多个任务 |
-| `doctor` | 检查所选宿主、运行时资产与目标仓库是否满足运行条件 |
-| `init` | 手动初始化 `.helloloop/` 模板 |
-| `install` | 安装插件到所选宿主目录 |
-
-### 常用选项
-
-| 选项 | 说明 |
-| --- | --- |
-| `-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` 始终把运行状态写入目标仓库根目录，而不是插件目录自身。
-
-默认目录：
+### Codex CLI
 
 ```text
-.helloloop/
-├── backlog.json
-├── policy.json
-├── project.json
-├── status.json
-├── STATE.md
-└── runs/
+$helloloop
 ```
 
-其中：
+或：
 
-- `backlog.json`：分析后生成的任务队列
-- `policy.json`：自动推进策略、重试上限和 Codex 参数
-- `project.json`：开发文档入口和全局约束
-- `status.json`：最近一次运行状态
-- `STATE.md`：面向人的进度摘要
-- `runs/`：提示词、stdout、stderr、验证日志等留痕
+```bash
+npx helloloop
+npx helloloop <PATH>
+```
 
-## Skill 用法
+`$helloloop` 的推荐行为与主命令保持一致：优先进入 `npx helloloop` 主流程，而不是在对话里手工模拟分析和续跑。
 
-如果你已经把 `HelloLoop` 安装成 Codex 插件，也可以直接在 Codex 里调用：
+如果你显式使用技能名，也可以写：
 
 ```text
-$helloloop
+helloloop:helloloop
 ```
 
-或：
+### Claude Code / Gemini CLI
 
 ```text
-helloloop:helloloop
+/helloloop
 ```
 
-此时推荐理解为：
+它们会按各自 CLI 的原生 agent 逻辑执行，但共享同一套 `.helloloop/` 工作流规范。
 
-- `$helloloop` 是插件入口
-- `npx helloloop` / `npx helloloop <PATH>` 是实际执行入口
+## 命令速查
 
-也就是说，用户显式调用 `$helloloop` 时，目标行为应当与主命令保持一致：
+| 命令 | 作用 |
+| --- | --- |
+| `helloloop` / `analyze` | 自动分析、展示确认单，并在确认后继续接续开发 |
+| `install` | 安装运行时 bundle 到指定宿主 |
+| `uninstall` | 从指定宿主卸载运行时 bundle 与注册信息 |
+| `doctor` | 检查宿主环境、插件资产与目标仓库状态 |
+| `init` | 手动初始化 `.helloloop/` 模板 |
+| `status` | 查看 backlog 摘要和当前状态 |
+| `next` | 生成下一任务的干跑预览 |
+| `run-once` | 执行一个任务 |
+| `run-loop` | 连续执行多个任务 |
 
-1. 先自动识别仓库和开发文档
-2. 再分析当前代码与文档目标
-3. 再展示执行确认单
-4. 最后在你确认后自动接续执行
+常用选项：
 
-如果当前目录无法判断目标仓库、缺少开发文档，或者你明确只想先讲解不执行，`HelloLoop` 才应该先停下来问你，而不是直接启动执行。
+| 选项 | 作用 |
+| --- | --- |
+| `--dry-run` | 只分析并输出确认单，不开始自动执行 |
+| `-y` / `--yes` | 跳过交互确认，分析后直接执行 |
+| `--repo <dir>` | 高级覆盖：显式指定项目仓库 |
+| `--docs <dir|file>` | 高级覆盖：显式指定开发文档 |
+| `--rebuild-existing` | 项目与文档冲突时，自动清理现有项目后重建 |
+| `--host <name>` | 宿主：`codex` / `claude` / `gemini` / `all` |
+| `--config-dir <dir>` | 状态目录名，默认 `.helloloop` |
 
-如果你安装的是 Claude 或 Gemini 宿主，则推荐直接使用：
+手动控制示例：
 
-```text
-/helloloop
+```bash
+npx helloloop status
+npx helloloop next
+npx helloloop run-once
 ```
 
-它们会按各自 CLI 的原生 agent 逻辑执行，但共享同一套 `.helloloop/` 工作流规范。
+## Doctor 检查
 
-## 在 Codex 中使用
+检查默认宿主：
 
-可以直接在当前 Codex 会话里运行：
+```bash
+npx helloloop doctor
+```
+
+检查全部宿主：
 
 ```bash
-npx helloloop
+npx helloloop doctor --host all
+```
+
+检查指定安装目录：
+
+```bash
+npx helloloop doctor --host all --codex-home <CODEX_HOME> --claude-home <CLAUDE_HOME> --gemini-home <GEMINI_HOME>
 ```
 
-不需要重开终端。
+`doctor` 的检查范围分两类：
 
-如果你使用的是全局安装后的 `helloloop` 短命令，是否立刻可用取决于当前 shell 是否已经刷新 PATH。
+- 在插件源码仓库中运行：主要检查 CLI、bundle 资产和宿主安装资产
+- 在目标项目仓库中运行，或显式传入 `--repo`：还会检查 `.helloloop/backlog.json`、`project.json`、`policy.json`、`verify.yaml`
 
-安装为 Codex 插件后，推荐显式使用的 skill 名称是：
+## `.helloloop/` 状态目录
+
+`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 +359,8 @@ helloloop:helloloop
 helloloop/
 ├── .claude-plugin/
 ├── .codex-plugin/
+├── .github/
+├── .helloagents/
 ├── bin/
 ├── docs/
 ├── hosts/
@@ -423,18 +368,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`。

package/hosts/claude/marketplace/.claude-plugin/marketplace.json

@@ -3,10 +3,12 @@
   "owner": {
     "name": "HelloLoop"
   },
+  "metadata": {
+    "description": "HelloLoop 的 Claude Code 本地 marketplace，提供基于开发文档的分析、确认与自动接续开发工作流。"
+  },
   "plugins": [
     {
       "name": "helloloop",
-      "displayName": "HelloLoop",
       "description": "基于开发文档分析当前进度、展示确认单，并在确认后继续接续开发的 Claude Code 原生插件。",
       "source": "./plugins/helloloop"
     }