helloloop 0.2.0 → 0.3.1

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

@@ -1,6 +1,6 @@
 {
   "name": "helloloop",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "HelloLoop 的 Claude Code 原生插件。",
   "author": {
     "name": "HelloLoop"

package/hosts/claude/marketplace/plugins/helloloop/commands/helloloop.md

@@ -8,11 +8,18 @@ argument-hint: [PATH]
 规则如下：
 
 1. 将当前代码视为事实源，将开发文档视为目标源。
-2. 如果用户在命令后提供了 `$ARGUMENTS`，只把它解释为一个路径；该路径可能是项目仓库、开发文档目录或开发文档文件。
-3. 自动识别目标仓库与开发文档，并先分析“当前代码做到哪里了”“与文档目标是否存在偏差”。
-4. 在目标仓库根目录创建或刷新 `.helloloop/`，至少维护 `backlog.json`、`project.json`、`status.json`、`STATE.md` 与 `runs/`。
-5. 如果用户给了开发文档但无法定位项目仓库，或者给了项目路径但无法定位开发文档，必须停下来询问用户，而不是猜测。
-6. 在真正执行开发前，必须输出一份中文执行确认单，至少包含：
+2. 如果用户在命令后提供了 `$ARGUMENTS`，必须同时保留其中的显式路径和自然语言补充要求，不要依赖固定关键词硬编码决策。
+3. 自动识别目标仓库与开发文档，并先分析“当前代码做到哪里了”“与文档目标是否存在偏差”“当前项目与文档目标是否匹配”。
+4. 如果当前目录没有明确开发文档，先展示顶层文档文件、顶层目录和疑似项目目录，再询问用户开发文档路径。
+5. 项目路径对外只有一个概念；如果用户输入的项目路径不存在，就把它视为准备创建的新项目目录，不要再单独追问“新项目路径”。
+6. 在目标仓库根目录创建或刷新 `.helloloop/`，至少维护 `backlog.json`、`project.json`、`status.json`、`STATE.md` 与 `runs/`。
+7. 如果用户给了开发文档但无法定位项目仓库，或者给了项目路径但无法定位开发文档，必须停下来询问用户，而不是猜测。
+8. 如果当前项目目录已存在，但分析认为它与开发文档目标明显冲突，必须先明确提示用户，并确认是继续现有项目、还是清理后按文档重建。
+9. 在真正执行开发前，必须输出一份中文执行确认单，至少包含：
+   - 路径判断与判断依据
+   - 本次命令补充输入
+   - 需求语义理解
+   - 项目匹配判断
    - 目标仓库
    - 开发文档
    - 当前进度
@@ -22,7 +29,7 @@ argument-hint: [PATH]
    - 首个待执行任务
    - 验证命令预览
    - 自动执行停止条件
-7. 未经用户确认，不要开始正式修改代码。
-8. 用户确认后，使用 Claude Code 的原生工具持续推进 backlog，直到完成、遇到硬阻塞或需要用户补充关键信息。
-9. 始终优先使用安全 shell 与原生文件工具；在 Windows 上避免危险的嵌套命令、路径拼接删除和 `cmd` 风格破坏性命令。
-10. 不要调用外部 `npx helloloop` 来替代这个原生工作流；你现在就在 HelloLoop 的 Claude Code 原生模式中。
+10. 未经用户确认，不要开始正式修改代码。
+11. 用户确认后，使用 Claude Code 的原生工具持续推进 backlog，直到开发文档的最终目标完成，且相关测试、验证、验收都已通过；遇到硬阻塞或需要用户补充关键信息时再停下。
+12. 始终优先使用安全 shell 与原生文件工具；在 Windows 上避免危险的嵌套命令、路径拼接删除和 `cmd` 风格破坏性命令。
+13. 不要调用外部 `npx helloloop` 来替代这个原生工作流；你现在就在 HelloLoop 的 Claude Code 原生模式中。

package/hosts/claude/marketplace/plugins/helloloop/skills/helloloop/SKILL.md

@@ -13,11 +13,14 @@ description: 当用户希望 Claude Code 按开发文档先分析当前进度，
 2. 分析当前代码与文档目标之间的真实进度和偏差
 3. 在目标仓库根目录创建或刷新 `.helloloop/`
 4. 输出中文执行确认单
-5. 用户确认后，继续用 Claude Code 原生工具接续开发、测试和验收
+5. 用户确认后，继续用 Claude Code 原生工具接续开发、测试和验收，直到最终目标完成
 
 ## 关键规则
 
 - 如果缺少目标仓库或开发文档，必须停下来询问用户。
+- 如果当前目录没有明确开发文档，应先展示顶层文档文件、顶层目录和疑似项目目录，再询问文档路径。
+- 项目路径对外只有一个概念；如果用户提供的项目路径不存在，直接按新项目路径处理，不要再追问“新项目路径”。
+- 如果当前项目与开发文档目标明显冲突，必须先确认是继续现有项目、清理后重建，还是取消。
 - 不允许跳过执行确认单直接开始正式开发。
 - 不允许把开发文档整体压成一个大任务；需要输出足够细的 backlog。
 - 代码是事实源，开发文档是目标源。

package/hosts/gemini/extension/GEMINI.md

@@ -9,16 +9,20 @@
 ## 默认流程
 
 1. 自动识别项目仓库与开发文档
-2. 分析当前代码与开发文档的差距
-3. 在目标仓库根目录创建或刷新 `.helloloop/`
-4. 输出中文执行确认单
-5. 用户确认后，再继续执行后续开发任务
+2. 如果当前目录没有明确开发文档，先展示顶层文档文件、顶层目录和疑似项目目录，再询问文档路径
+3. 项目路径对外只有一个概念；若用户输入的路径不存在，直接按新项目路径处理
+4. 分析当前代码与开发文档的差距，并判断当前项目与文档目标是否匹配
+5. 在目标仓库根目录创建或刷新 `.helloloop/`
+6. 输出中文执行确认单（含路径判断、语义理解、项目匹配判断）
+7. 若当前项目与开发文档目标明显冲突，先确认是继续现有项目还是清理后重建
+8. 用户确认后，再继续执行后续开发任务，直到最终目标完成且测试、验收全部通过
 
 ## 强制规则
 
 - 代码是事实源，开发文档是目标源。
 - 开发前必须先输出执行确认单。
 - 如果无法识别目标仓库或开发文档，必须停下来询问用户。
+- 不要单独追问“新项目路径”；项目路径只需要用户给一次。
 - 如果识别到偏差修正任务，优先收口偏差，再推进后续 backlog。
 - 真正执行前确认，真正结束前验证。
 

package/hosts/gemini/extension/commands/helloloop.toml

@@ -4,10 +4,16 @@ prompt = """
 
 执行要求：
 
-1. 自动识别目标仓库与开发文档；如果用户在命令后提供了参数，只把它解释为一个路径。
-2. 分析当前代码与开发文档之间的真实进度和偏差。
-3. 在目标仓库根目录创建或刷新 `.helloloop/`，至少维护 `backlog.json`、`project.json`、`status.json`、`STATE.md` 与 `runs/`。
-4. 在真正开发前，必须输出中文执行确认单，至少包含：
+1. 自动识别目标仓库与开发文档；如果用户在命令后提供了参数，必须同时保留其中的显式路径和自然语言补充要求，不要靠固定关键词硬编码判断。
+2. 如果当前目录没有明确开发文档，应先展示顶层文档文件、顶层目录和疑似项目目录，再询问用户开发文档路径。
+3. 项目路径对外只有一个概念；如果用户给出的项目路径不存在，直接按新项目路径处理，不要再单独追问“新项目路径”。
+4. 分析当前代码与开发文档之间的真实进度和偏差，并判断当前项目目录与开发文档目标是否匹配。
+5. 在目标仓库根目录创建或刷新 `.helloloop/`，至少维护 `backlog.json`、`project.json`、`status.json`、`STATE.md` 与 `runs/`。
+6. 在真正开发前，必须输出中文执行确认单，至少包含：
+   - 路径判断与判断依据
+   - 本次命令补充输入
+   - 需求语义理解
+   - 项目匹配判断
    - 目标仓库
    - 开发文档
    - 当前进度
@@ -17,8 +23,9 @@ prompt = """
    - 首个待执行任务
    - 验证命令预览
    - 自动执行停止条件
-5. 用户未确认前，不要开始正式修改代码。
-6. 用户确认后，继续用 Gemini CLI 原生工具推进 backlog，直到完成、遇到硬阻塞，或需要用户补充关键信息。
-7. 如果用户给了开发文档但找不到项目仓库，或给了项目路径但找不到开发文档，必须停下来询问。
-8. Windows 上优先用安全的文件与 shell 操作；禁止危险删除、硬重置、强推和其他破坏性命令。
+7. 如果当前项目目录已存在，但分析认为它与开发文档目标明显冲突，必须先明确提示用户，并确认是继续现有项目、还是清理后按文档重建。
+8. 用户未确认前，不要开始正式修改代码。
+9. 用户确认后，继续用 Gemini CLI 原生工具推进 backlog，直到开发文档的最终目标完成，且相关测试、验证、验收都已通过；遇到硬阻塞或需要用户补充关键信息时再停下。
+10. 如果用户给了开发文档但找不到项目仓库，或给了项目路径但找不到开发文档，必须停下来询问。
+11. Windows 上优先用安全的文件与 shell 操作；禁止危险删除、硬重置、强推和其他破坏性命令。
 """

package/hosts/gemini/extension/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "helloloop",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "HelloLoop 的 Gemini CLI 原生扩展，用于按开发文档接续推进项目开发。",
   "contextFileName": "GEMINI.md",
   "excludeTools": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "helloloop",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "面向 Codex CLI、Claude Code、Gemini CLI 的多宿主开发工作流插件",
   "author": "HelloLoop",
   "license": "Apache-2.0",
@@ -30,7 +30,7 @@
     "templates"
   ],
   "scripts": {
-    "test": "node --test tests/analyze_cli.test.mjs tests/cli_surface.test.mjs tests/install_script.test.mjs tests/process_shell.test.mjs tests/prompt_guardrails.test.mjs tests/ralph_loop.test.mjs tests/plugin_bundle.test.mjs"
+    "test": "node --test tests/analyze_cli.test.mjs tests/analyze_intent_cli.test.mjs tests/cli_surface.test.mjs tests/install_script.test.mjs tests/process_shell.test.mjs tests/prompt_guardrails.test.mjs tests/ralph_loop.test.mjs tests/plugin_bundle.test.mjs"
   },
   "engines": {
     "node": ">=20"

package/scripts/uninstall-home-plugin.ps1

@@ -0,0 +1,25 @@
+[CmdletBinding()]
+param(
+  [string]$CodexHome = (Join-Path $HOME ".codex")
+)
+
+$sourceRoot = Split-Path -Parent $PSScriptRoot
+$cliEntry = Join-Path $sourceRoot "scripts\helloloop.mjs"
+
+if (-not (Test-Path $cliEntry)) {
+  throw "未找到 CLI 入口：$cliEntry"
+}
+
+if (-not (Get-Command node -ErrorAction SilentlyContinue)) {
+  throw "未找到 node，可先安装 Node.js 20+ 后再运行。"
+}
+
+$arguments = @(
+  $cliEntry,
+  "uninstall",
+  "--codex-home",
+  $CodexHome
+)
+
+& node @arguments
+exit $LASTEXITCODE

package/skills/helloloop/SKILL.md

@@ -9,7 +9,7 @@ description: 当用户希望 Codex 先分析仓库当前进度、生成确认单
 
 ## 强制入口规则
 
-- 用户显式调用 `$helloloop` / `helloloop:helloloop` 时，默认必须优先执行 `npx helloloop` 或 `npx helloloop <PATH>`。
+- 用户显式调用 `$helloloop` / `#helloloop` / `helloloop:helloloop` 时，默认必须优先执行 `npx helloloop` 或 `npx helloloop <PATH>`。
 - 不允许在对话里手工模拟 `HelloLoop` 的分析、确认单、backlog 编排和自动续跑流程来代替 CLI。
 - 只有在以下情况，才允许先停下来问用户而不是直接执行 CLI：
   1. 用户既没有给路径，当前目录也无法判断项目仓库或开发文档
@@ -23,6 +23,27 @@ description: 当用户希望 Codex 先分析仓库当前进度、生成确认单
 - 用户给了单一路径 → 先执行 `npx helloloop <PATH>`
 - 用户明确只想先看分析和确认单 → 执行 `npx helloloop --dry-run`
 - 用户明确要求跳过确认直接开始 → 执行 `npx helloloop -y`
+- 用户在命令后附带了额外路径或自然语言要求 → 必须把这些附加内容一并传给主 CLI，不允许丢弃或手工改写
+
+## 附加输入处理规则
+
+- 命令后的显式路径优先于自动发现结果。
+- 命令后的非路径文本不靠关键词硬编码分流，而是作为“本次用户意图”原样传给 `HelloLoop` 的确认单与分析 prompt。
+- 如果附加输入里同时包含文档路径、项目路径和额外要求，优先保留全部信息，再由 CLI 输出确认单统一确认。
+- 不允许因为语言不同（中文 / 英文 / 其他语言）就忽略附加要求。
+
+## 路径发现与提问规则
+
+- 如果当前目录没有自动识别到明确开发文档，应先展示顶层文档文件、顶层目录和疑似项目目录，再要求用户补充文档路径。
+- 项目路径对外只有一个概念，不要单独追问“新项目路径”。
+- 如果用户输入的项目路径不存在，应直接把它视为准备创建的新项目目录。
+- 如果自动发现同时出现多个冲突的文档路径或项目路径，不允许替用户猜测，必须停下来确认。
+
+## 项目冲突规则
+
+- 如果分析认为“当前项目目录已存在，但与开发文档目标明显冲突”，必须先提示用户选择继续、重建还是取消。
+- 非交互模式下，只有显式追加 `--rebuild-existing`，才允许直接清理当前项目后重建。
+- 未经确认，不允许默认清空现有项目目录。
 
 ## 插件边界
 
@@ -45,8 +66,8 @@ description: 当用户希望 Codex 先分析仓库当前进度、生成确认单
 
 - 代码是事实源，开发文档是目标源。
 - `HelloLoop` 会先分析当前真实进度，再生成或刷新 `.helloloop/backlog.json`。
-- 分析后会展示执行确认单，明确告知当前进度、待办任务、验证命令和执行边界。
-- 用户确认后，默认会持续执行到 backlog 清空或遇到硬阻塞。
+- 分析后会展示中文执行确认单，明确告知路径判断、语义理解、项目匹配、当前进度、待办任务、验证命令和执行边界。
+- 用户确认后，默认会持续执行到 backlog 清空，或开发文档的最终目标完成且测试、验收通过，或遇到硬阻塞。
 - 真正的代码分析与实现仍由本机 `codex` CLI 完成。
 - `$helloloop` 的职责是把用户请求路由到主 CLI 流程，而不是在对话里手工复刻一套平行流程。
 
@@ -54,8 +75,10 @@ description: 当用户希望 Codex 先分析仓库当前进度、生成确认单
 
 - `npx helloloop`
 - `npx helloloop <PATH>`
+- `npx helloloop <PATH> <补充说明>`
 - `npx helloloop --dry-run`
 - `npx helloloop -y`
+- `npx helloloop --rebuild-existing`
 
 ## 手动控制命令
 
@@ -65,6 +88,8 @@ description: 当用户希望 Codex 先分析仓库当前进度、生成确认单
 - `npx helloloop run-loop --max-tasks <n>`
 - `npx helloloop doctor`
 - `npx helloloop init`
+- `npx helloloop install --host all`
+- `npx helloloop uninstall --host all`
 
 ## 调用方式
 

package/src/analyze_confirmation.mjs

@@ -1,5 +1,6 @@
 import path from "node:path";
 
+import { renderInputIssueLines, renderUserIntentLines } from "./analyze_user_input.mjs";
 import { analyzeExecution, summarizeBacklog } from "./backlog.mjs";
 import { loadPolicy, loadVerifyCommands } from "./config.mjs";
 
@@ -62,6 +63,76 @@ function resolvePreviewVerifyCommands(context, execution) {
   return loadVerifyCommands(context);
 }
 
+function renderResolutionLines(discovery, context, docsDisplay) {
+  const repoResolution = discovery?.resolution?.repo;
+  const docsResolution = discovery?.resolution?.docs;
+  const repoBasis = Array.isArray(repoResolution?.basis) && repoResolution.basis.length
+    ? repoResolution.basis.join("；")
+    : "无";
+  const docsBasis = Array.isArray(docsResolution?.basis) && docsResolution.basis.length
+    ? docsResolution.basis.join("；")
+    : "无";
+  const repoState = repoResolution?.exists === false
+    ? "当前目录不存在，将按新项目创建"
+    : "已存在项目目录";
+
+  return [
+    "路径判断：",
+    `- 开发文档：${docsDisplay.length ? docsDisplay.join("，") : "未识别"}`,
+    `- 文档来源：${docsResolution?.sourceLabel || "自动判断"}`,
+    `- 文档把握：${docsResolution?.confidenceLabel || "中"}`,
+    `- 文档依据：${docsBasis}`,
+    `- 目标仓库：${context.repoRoot.replaceAll("\\", "/")}`,
+    `- 项目状态：${repoState}`,
+    `- 仓库来源：${repoResolution?.sourceLabel || "自动判断"}`,
+    `- 仓库把握：${repoResolution?.confidenceLabel || "中"}`,
+    `- 仓库依据：${repoBasis}`,
+  ];
+}
+
+function renderRequestInterpretationLines(analysis) {
+  const interpretation = analysis?.requestInterpretation;
+  if (!interpretation) {
+    return [];
+  }
+
+  return [
+    "需求语义理解：",
+    `- 总结：${interpretation.summary || "无"}`,
+    ...(interpretation.priorities.length
+      ? interpretation.priorities.map((item) => `- 优先关注：${item}`)
+      : ["- 优先关注：无"]),
+    ...(interpretation.cautions.length
+      ? interpretation.cautions.map((item) => `- 特别注意：${item}`)
+      : ["- 特别注意：无"]),
+  ];
+}
+
+function renderRepoDecisionLines(analysis) {
+  const decision = analysis?.repoDecision;
+  if (!decision) {
+    return [];
+  }
+
+  const compatibilityMap = {
+    compatible: "兼容，可直接接续",
+    conflict: "明显冲突",
+    uncertain: "存在不确定性",
+  };
+  const actionMap = {
+    continue_existing: "继续在当前项目上接续",
+    confirm_rebuild: "先确认是否清理当前项目后重建",
+    start_new: "按新项目路径继续推进",
+  };
+
+  return [
+    "项目匹配判断：",
+    `- 匹配结论：${compatibilityMap[decision.compatibility] || decision.compatibility}`,
+    `- 建议动作：${actionMap[decision.action] || decision.action}`,
+    `- 判断依据：${decision.reason}`,
+  ];
+}
+
 export function resolveAutoRunMaxTasks(backlog, options = {}) {
   const explicitMaxTasks = Number(options.maxTasks);
   if (Number.isFinite(explicitMaxTasks) && explicitMaxTasks > 0) {
@@ -73,7 +144,7 @@ export function resolveAutoRunMaxTasks(backlog, options = {}) {
   return Math.max(1, pendingTotal);
 }
 
-export function renderAnalyzeConfirmation(context, analysis, backlog, options = {}) {
+export function renderAnalyzeConfirmation(context, analysis, backlog, options = {}, discovery = {}) {
   const summary = summarizeBacklog(backlog);
   const execution = analyzeExecution(backlog, options);
   const policy = loadPolicy(context);
@@ -82,12 +153,17 @@ export function renderAnalyzeConfirmation(context, analysis, backlog, options =
   const docsDisplay = analysis.requiredDocs.map((entry) => (
     toDisplayPath(context.repoRoot, path.resolve(context.repoRoot, entry))
   ));
+  const userIntentLines = renderUserIntentLines(options.userIntent);
+  const inputIssueLines = renderInputIssueLines(options.inputIssues);
 
   return [
     "执行确认单",
     "============",
-    `目标仓库：${context.repoRoot.replaceAll("\\", "/")}`,
-    `开发文档：${docsDisplay.length ? docsDisplay.join("，") : "未识别"}`,
+    ...renderResolutionLines(discovery, context, docsDisplay),
+    ...(userIntentLines.length ? ["", "本次命令补充输入：", ...formatList(userIntentLines)] : []),
+    ...(inputIssueLines.length ? ["", "输入提示：", ...inputIssueLines] : []),
+    ...(renderRequestInterpretationLines(analysis).length ? ["", ...renderRequestInterpretationLines(analysis)] : []),
+    ...(renderRepoDecisionLines(analysis).length ? ["", ...renderRepoDecisionLines(analysis)] : []),
     "",
     "当前进度：",
     `- ${analysis.summary.currentState}`,

package/src/analyze_prompt.mjs

@@ -1,4 +1,5 @@
 import { formatList } from "./common.mjs";
+import { renderUserIntentLines } from "./analyze_user_input.mjs";
 import {
   hasCustomProjectConstraints,
   listMandatoryGuardrails,
@@ -30,15 +31,18 @@ function renderDocPackets(docPackets) {
 
 export function buildAnalysisPrompt({
   repoRoot,
+  repoOriginallyExisted = true,
   docsEntries,
   docPackets,
   existingStateText = "",
   existingBacklogText = "",
   existingProjectConstraints = [],
+  userIntent = {},
 }) {
   const mandatoryGuardrails = listMandatoryGuardrails();
   const effectiveConstraints = resolveProjectConstraints(existingProjectConstraints);
   const usingFallbackConstraints = !hasCustomProjectConstraints(existingProjectConstraints);
+  const userIntentLines = renderUserIntentLines(userIntent);
 
   return [
     "你要为一个本地代码仓库做“接续开发分析”。",
@@ -50,9 +54,12 @@ export function buildAnalysisPrompt({
     "3. 生成的任务必须颗粒度足够，能直接进入开发，不允许输出“继续开发”这类空泛任务。",
     "4. 只关注当前目标仓库，不要把其他仓库的任务混进来；如果文档覆盖多仓库，只提取当前仓库相关任务。",
     "5. 如果某项工作依赖其他仓库或外部输入，允许输出 `blocked` 任务，但必须明确阻塞原因。",
+    "6. 如果“本次命令补充输入”中包含自然语言要求，无论中文、英文还是混合输入，都必须按语义理解并体现在后续任务中，不要依赖固定关键词。",
     "",
     section("目标仓库", `- 路径：${repoRoot.replaceAll("\\", "/")}`),
+    section("仓库初始状态", `- 该项目目录在本次分析前${repoOriginallyExisted ? "已经存在" : "尚不存在，将按新项目处理"}`),
     section("开发文档入口", docsEntries.map((item) => `- ${item}`).join("\n")),
+    listSection("本次命令补充输入", userIntentLines),
     existingStateText ? section("已有状态摘要", existingStateText) : "",
     listSection("内建安全底线", mandatoryGuardrails),
     listSection(usingFallbackConstraints ? "默认工程约束（文档未明确时也必须遵守）" : "已有项目约束", effectiveConstraints),
@@ -70,6 +77,11 @@ export function buildAnalysisPrompt({
       "9. `docs` 必须引用本次文档入口中的相关路径；`paths` 必须写当前仓库内的实际目录或文件模式。",
       "10. `acceptance` 必须可验证，不要写空话。",
       "11. `constraints` 只写从项目文档或现有项目配置中提炼出的项目特有约束；不要重复内建安全底线。",
+      "12. 如果存在命令补充输入，请额外输出 `requestInterpretation`：包含 `summary`、`priorities`、`cautions`，用于总结你对用户补充要求的语义理解。",
+      "13. 额外输出 `repoDecision`：包含 `compatibility`、`action`、`reason`，用于判断当前项目目录与开发文档目标是否匹配。",
+      "14. 当当前项目目录已存在，但代码结构/产品方向与开发文档目标明显冲突，且更合理的路径是清理后重建时，`repoDecision.compatibility` 设为 `conflict`，`repoDecision.action` 设为 `confirm_rebuild`。",
+      "15. 当当前项目目录与开发文档目标一致或可以直接接续时，`repoDecision.compatibility` 设为 `compatible`，`repoDecision.action` 设为 `continue_existing`。",
+      "16. 当本次项目目录原本不存在，或文档目标明显是从零开始新建项目时，`repoDecision.action` 可设为 `start_new`。",
     ].join("\n")),
   ].filter(Boolean).join("\n");
 }