helloagents 2.3.8 → 3.0.1-beta.1

package/scripts/ralph-loop.mjs

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+/**
+ * HelloAGENTS Ralph Loop — Quality verification gate
+ * Runs on SubagentStop (Claude Code) and Stop (Codex CLI).
+ * Auto-detects lint/test commands and blocks if they fail.
+ */
+import { readFileSync, existsSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { execSync } from 'node:child_process';
+import { homedir } from 'node:os';
+
+const CONFIG_FILE = join(homedir(), '.helloagents', 'helloagents.json');
+const CMD_TIMEOUT = 60_000; // 60s
+
+// Hook event name: read from env or infer from CLI mode + --gemini flag.
+// Claude: SubagentStop/Stop, Gemini: AfterAgent/SessionEnd.
+const IS_SUBAGENT = (process.argv[2] || '') === 'subagent';
+const IS_GEMINI = process.argv.includes('--gemini');
+const HOOK_EVENT = process.env.HELLOAGENTS_HOOK_EVENT
+  || (IS_SUBAGENT ? (IS_GEMINI ? 'AfterAgent' : 'SubagentStop') : (IS_GEMINI ? 'SessionEnd' : 'Stop'));
+
+// ── Settings ──────────────────────────────────────────────────────────
+function readSettings() {
+  try { return JSON.parse(readFileSync(CONFIG_FILE, 'utf-8')); } catch {}
+  return {};
+}
+
+// ── Detect verification commands ──────────────────────────────────────
+function loadVerifyYaml(cwd) {
+  const f = join(cwd, '.helloagents', 'verify.yaml');
+  if (!existsSync(f)) return null;
+  try {
+    const content = readFileSync(f, 'utf-8');
+    const cmds = [];
+    let inCmds = false;
+    for (const line of content.split('\n')) {
+      const s = line.trim();
+      if (s.startsWith('commands:')) { inCmds = true; continue; }
+      if (inCmds) {
+        if (s.startsWith('- ') && !s.startsWith('# ')) {
+          const cmd = s.slice(2).trim().replace(/^["']|["']$/g, '');
+          if (cmd && !cmd.startsWith('#')) cmds.push(cmd);
+        } else if (s && !s.startsWith('#')) break;
+      }
+    }
+    return cmds.length ? cmds : null;
+  } catch { return null; }
+}
+
+function detectFromPackageJson(cwd) {
+  const f = join(cwd, 'package.json');
+  if (!existsSync(f)) return [];
+  try {
+    const scripts = JSON.parse(readFileSync(f, 'utf-8')).scripts || {};
+    return ['lint', 'typecheck', 'type-check', 'test', 'build']
+      .filter(k => k in scripts)
+      .map(k => `npm run ${k}`);
+  } catch { return []; }
+}
+
+function detectFromPyproject(cwd) {
+  const f = join(cwd, 'pyproject.toml');
+  if (!existsSync(f)) return [];
+  try {
+    const content = readFileSync(f, 'utf-8');
+    const cmds = [];
+    if (content.includes('[tool.ruff')) cmds.push('ruff check .');
+    if (content.includes('[tool.mypy')) cmds.push('mypy .');
+    if (content.includes('[tool.pytest')) cmds.push('pytest --tb=short -q');
+    return cmds;
+  } catch { return []; }
+}
+
+function detectCommands(cwd) {
+  const yaml = loadVerifyYaml(cwd);
+  if (yaml?.length) return yaml;
+  const pkg = detectFromPackageJson(cwd);
+  if (pkg.length) return pkg;
+  return detectFromPyproject(cwd);
+}
+
+// ── Circuit Breaker (consecutive failure tracking) ───────────────────
+const BREAKER_FILE_NAME = '.ralph-breaker.json';
+
+function getBreakerPath(cwd) {
+  return join(cwd, '.helloagents', BREAKER_FILE_NAME);
+}
+
+function readBreaker(cwd) {
+  try {
+    return JSON.parse(readFileSync(getBreakerPath(cwd), 'utf-8'));
+  } catch {
+    return { consecutive_failures: 0, last_failure: null };
+  }
+}
+
+function writeBreaker(cwd, state) {
+  const dir = join(cwd, '.helloagents');
+  try { mkdirSync(dir, { recursive: true }); } catch {}
+  writeFileSync(getBreakerPath(cwd), JSON.stringify(state, null, 2));
+}
+
+function resetBreaker(cwd) {
+  writeBreaker(cwd, { consecutive_failures: 0, last_failure: null });
+}
+
+// ── Progress Detection (git diff check) ──────────────────────────────
+
+function hasGitChanges(cwd) {
+  try {
+    const diff = execSync('git diff --stat HEAD', {
+      cwd, encoding: 'utf-8', timeout: 10_000, stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+    if (diff) return true;
+    // Also check staged changes
+    const staged = execSync('git diff --stat --cached', {
+      cwd, encoding: 'utf-8', timeout: 10_000, stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+    return !!staged;
+  } catch {
+    return true; // If git fails, assume changes exist (don't block on git errors)
+  }
+}
+
+// ── Run verification ──────────────────────────────────────────────────
+const SHELL_OPERATORS = /[;&|`$(){}\n\r]/;
+
+function runVerify(commands, cwd) {
+  const failures = [];
+  for (const cmd of commands) {
+    if (SHELL_OPERATORS.test(cmd)) {
+      failures.push({ cmd, output: 'Blocked: shell operators not allowed in verify commands' });
+      continue;
+    }
+    try {
+      execSync(cmd, { cwd, encoding: 'utf-8', timeout: CMD_TIMEOUT, stdio: ['pipe', 'pipe', 'pipe'] });
+    } catch (err) {
+      // ENOENT = command or dependency not installed, skip instead of failing
+      if (err.code === 'ENOENT' || (err.stderr && /ENOENT|not found|command not found/i.test(err.stderr))) {
+        continue;
+      }
+      let output = ((err.stdout || '') + (err.stderr || '')).trim();
+      if (output.length > 1000) output = output.slice(0, 1000) + '\n...(truncated)';
+      failures.push({ cmd, output: output || `exit code ${err.status}` });
+    }
+  }
+  return failures;
+}
+
+// ── Result Handlers ──────────────────────────────────────────────────
+
+function handleSuccess(cwd, isSubagent) {
+  resetBreaker(cwd);
+
+  if (isSubagent) {
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: HOOK_EVENT,
+        additionalContext: '子代理快速验证通过（lint/typecheck）。请控制器审查变更后继续。',
+      },
+      suppressOutput: true,
+    }));
+    return;
+  }
+
+  // Progress detection: warn if claiming done but no git changes
+  if (!hasGitChanges(cwd)) {
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: HOOK_EVENT,
+        additionalContext: '⚠️ [Ralph Loop] 验证通过但未检测到代码变更（git diff 为空）。如果确实完成了编码任务，请确认变更已保存。',
+      },
+      suppressOutput: true,
+    }));
+  } else {
+    process.stdout.write(JSON.stringify({ suppressOutput: true }));
+  }
+}
+
+function handleFailure(failures, cwd) {
+  const breaker = readBreaker(cwd);
+  breaker.consecutive_failures += 1;
+  breaker.last_failure = new Date().toISOString();
+  writeBreaker(cwd, breaker);
+
+  const breakerWarning = breaker.consecutive_failures >= 3
+    ? `\n\n⚠️ [断路器] 已连续 ${breaker.consecutive_failures} 次验证失败。当前修复思路可能有误，建议：\n  1. 重新分析根因，不要继续在同一方向上硬修\n  2. 检查是否存在架构层面的问题\n  3. 考虑回退到上一个正常状态重新开始`
+    : '';
+
+  const details = failures.map(f => `\u2717 ${f.cmd}\n${f.output}`).join('\n\n');
+  process.stdout.write(JSON.stringify({
+    decision: 'block',
+    reason: `[Ralph Loop] Verification failed:\n\n${details}\n\nFix the issues above before completing.${breakerWarning}`,
+    suppressOutput: true,
+  }));
+}
+
+/** Filter commands to fast checks only for subagent mode. Returns null if no fast commands found. */
+function filterSubagentCommands(commands) {
+  const fast = commands.filter(cmd =>
+    /lint|typecheck|type-check|ruff check|mypy|eslint|tsc/.test(cmd)
+  );
+  if (fast.length === 0) {
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: HOOK_EVENT,
+        additionalContext: '子代理完成。未找到快速验证命令，请控制器手动审查变更。',
+      },
+      suppressOutput: true,
+    }));
+    return null;
+  }
+  return fast;
+}
+
+// ── Main ──────────────────────────────────────────────────────────────
+async function main() {
+  const settings = readSettings();
+  if (settings.ralph_loop_enabled === false) {
+    process.stdout.write(JSON.stringify({ suppressOutput: true }));
+    return;
+  }
+
+  let data = {};
+  try { data = JSON.parse(readFileSync(0, 'utf-8')); } catch {}
+  const cwd = data.cwd || process.cwd();
+
+  let commands = detectCommands(cwd);
+  if (!commands?.length) {
+    process.stdout.write(JSON.stringify({ suppressOutput: true }));
+    return;
+  }
+
+  if (IS_SUBAGENT) {
+    commands = filterSubagentCommands(commands);
+    if (!commands) return;
+  }
+
+  const failures = runVerify(commands, cwd);
+  if (failures.length === 0) handleSuccess(cwd, IS_SUBAGENT);
+  else handleFailure(failures, cwd);
+}
+
+main().catch(() => {
+  process.stdout.write(JSON.stringify({ suppressOutput: true }));
+});

package/skills/_meta/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: helloagents-meta
+description: HelloAGENTS 技能系统规范
+policy:
+  allow_implicit_invocation: false
+---
+
+## Skill 系统
+Skills 是带 YAML frontmatter 的 Markdown 文件。
+- helloagents: 检查清单驱动的质量门控（每次对话自动加载）
+- hello-*: 质量技能（根据任务自动激活，提供实现标准和交付检查清单）
+- commands/*: 用户通过 ~command 调用
+
+Skills 按需加载，不预加载。
+
+## Frontmatter 字段
+- name: 技能名称（必填）
+- description: 技能描述，用于元数据层判断是否相关（必填）
+- policy.allow_implicit_invocation: 是否允许隐式激活（false = 仅显式调用）。缺省时默认 true（hello-* 质量技能根据任务自动激活）。commands/* 必须显式设为 false（仅通过 ~command 调用）

package/skills/commands/auto/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: ~auto
+description: ~design 的全自动版本 — AI 自主完成需求分析、方案设计和执行，流程与 ~design 一致（~auto 命令）
+policy:
+  allow_implicit_invocation: false
+---
+Trigger: ~auto <任务描述>
+
+~auto 是 ~design 的全自动版本。区别仅在于：需求分析和方案探索由 AI 自主决策（不确定的关键决策点仍向用户确认）。简单任务可跳过方案设计直接执行。
+
+本 skill 自包含，不依赖再读取 `~design` 的 command skill。只有在本 skill 明确要求时，才继续读取对应的 hello-* 技能。
+
+## 铁律
+- 在确认方案之前，禁止编写实现代码、创建实现文件或执行实现操作；仅当任务被判定为简单任务时，才可跳过方案设计直接进入执行
+- 需求分析阶段不读取实现类技能（hello-ui/hello-test/hello-verify 等），需求明确后再按需读取
+- 不因为 `~auto` 与 `~design` 相似，就额外读取 `~design` 的 SKILL.md
+
+## 流程
+
+### 1. 上下文收集（ORIENT）
+
+已有项目：
+- 读取 .helloagents/context.md 获取项目上下文和模块索引
+- 读取 .helloagents/guidelines.md 获取项目约定
+- 扫描相关代码文件理解现有架构
+
+全新项目（无 .helloagents/ 目录）：
+- 跳过，直接进入需求分析
+
+### 2. 需求分析（CLARIFY，AI 自主判断）
+
+快速评估任务复杂度：
+1. 影响范围（单文件 vs 多文件）
+2. 是否涉及架构决策
+3. 复杂度信号：文件数 / 跨模块数 / 新增依赖 / 数据库变更
+
+简单任务（单文件修改/明确修复）→ 跳过方案设计，直接进入当前已加载 bootstrap 中定义的统一执行流程。
+
+复杂任务 → AI 自主分析三个方向（目的、约束、成功标准），不确定的关键决策点仍向用户确认。
+涉及视觉/交互/体验的决策：必须体现当前前沿设计水准。若当前已加载 bootstrap 含审美/体验规则则遵循其要求；否则至少给出具体、可执行、非泛化的视觉特征，不确定时主动搜索查阅最新设计案例和技术能力。
+
+大项目检测：如果任务涉及多个独立子系统，先分解为子项目，每个子项目走独立的设计→计划→实施循环。
+
+**假设模式**（已有代码库，优先使用）：
+- 基于代码证据自主判断目的、约束和成功标准
+- 不确定的关键决策点仍向用户确认
+
+**委托模式**（全新项目，对应 ~design 交互模式的自动化版本）：
+- 基于任务描述自主推断目的、约束和成功标准
+- 不确定的关键决策点仍向用户确认
+
+### 3. 方案探索（PLAN）
+
+基于需求分析结果，评估 2-3 个可行方案，自主选择最佳方案（与 ~design 一致，但由 AI 决策）。
+涉及 UI 的方案：此时读取 hello-ui SKILL.md 获取设计规范。
+
+### 4. 方案细化
+
+自主完成完整方案细化：
+- 架构与文件结构
+- 涉及 UI 时：按 hello-ui 的设计思维规范展开
+- 数据流与错误处理
+- 测试策略
+
+### 5. 写入方案包
+
+复杂任务将确认的方案写入本地项目：
+- 全新项目（无 .helloagents/ 目录）：先创建 .helloagents/ 和 STATE.md（按 templates/STATE.md 格式）。这是方案包写入的前置操作，不受 kb_create_mode 开关控制
+- 创建 .helloagents/plans/YYYYMMDDHHMM_{feature}/
+- 按 templates/plans/ 的模板格式写入 requirements.md、design.md、tasks.md
+- 涉及 UI 的项目：生成或更新 .helloagents/DESIGN.md
+- 重写 .helloagents/STATE.md（正在做什么、关键上下文含需求摘要和方案决策、下一步设为第一个待执行任务）
+
+### 6. 执行决策
+
+展示方案摘要后，仅在是否进入执行仍构成阻塞决策时才询问用户：
+- 开始执行 → 重写 STATE.md（下一步设为第一个任务的具体动作）
+- 修改方案 → 回到方案细化
+- 暂不执行，保留方案 → 重写 STATE.md（下一步设为“方案已确认；执行需用户明确启动”）
+
+如果用户已对当前方案或继续执行作出明确同意，视为执行授权成立，直接进入执行，不再追加确认环节。
+简单任务跳过方案设计时，直接进入执行，无需额外确认。
+
+### 7. 执行
+
+按 tasks.md 逐项完成，每项进入当前已加载 bootstrap 中定义的统一执行流程，完成后同步重写 STATE.md。
+任务状态标记仅写入 tasks.md、验收清单或验证结果；普通说明、方案解释、状态汇报不用 [√] / [-] / [ ]。
+所有任务完成后进入当前已加载 bootstrap 中定义的 VALIDATE 阶段。
+可并行的任务标记后用子代理并行执行（不同子代理不改同一文件）。
+执行过程中遇到阻塞（依赖缺失、指令不清、验证反复失败）→ 立即停下询问用户，不猜测。
+执行过程中遇到高风险操作（删除文件/修改配置/数据库变更）→ 暂停确认。

package/skills/commands/clean/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: ~clean
+description: 清理临时文件、缓存和归档已完成方案包（~clean 命令）
+policy:
+  allow_implicit_invocation: false
+---
+Trigger: ~clean
+
+## 流程
+
+1. 扫描 .helloagents/plans/ 下的方案包
+2. 判定完成状态：tasks.md 中所有任务已标记 [√]（该标记仅用于任务列表/验收清单）或 STATE.md "正在做什么"表明已完成
+3. 已完成的方案包 → 将整个 plans/{feature}/ 目录归档到 .helloagents/archive/YYYY-MM/
+4. 更新 .helloagents/archive/_index.md（按 templates/archive/_index.md 格式追加一行）
+5. 清理临时文件：.helloagents/loop-results.tsv、.helloagents/.ralph-breaker.json
+6. 重写 STATE.md（清空已归档的方案路径；这是强制更新，但不要求为仅执行 `~clean` 的场景首次创建）
+7. 输出清理摘要（归档了几个方案包、清理了哪些文件）
+
+## 不删除
+流程状态：STATE.md、DESIGN.md
+知识沉淀：context.md、guidelines.md、verify.yaml、CHANGELOG.md、modules/

package/skills/commands/commit/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: ~commit
+description: 规范化 Git 提交 + 知识库同步（~commit 命令）
+policy:
+  allow_implicit_invocation: false
+---
+Trigger: ~commit [message]
+
+## 流程
+
+1. 检查 staged changes（git diff --staged）
+2. 如果没有 staged changes，提示用户先 git add
+3. 生成 conventional commit message（如未提供）
+   - 格式: type(scope): description
+   - type: feat|fix|refactor|docs|test|chore|style|perf
+4. 优先使用当前上下文中已注入的“当前用户设置”获取 `commit_attribution`；只有上下文不存在时才读取 `~/.helloagents/helloagents.json`：
+   - ""（空，默认）→ 不添加归属
+   - 有内容（如 "Co-Authored-By: HelloAGENTS"）→ 添加该内容到 commit message
+5. 执行 git commit
+
+## 知识库同步
+提交后，优先使用当前上下文中已注入的“当前用户设置”获取 `kb_create_mode`；只有上下文不存在时才读取 `~/.helloagents/helloagents.json`：
+- 0 = 跳过
+- 1 = 编码任务自动同步（默认）
+- 2 = 始终同步
+同步内容（仅知识库文件，规则同当前已加载 bootstrap 的 VALIDATE 阶段中的知识库同步）。

package/skills/commands/design/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: ~design
+description: 深度设计工作流 — 交互式需求挖掘、方案设计和执行（~design 命令）
+policy:
+  allow_implicit_invocation: false
+---
+Trigger: ~design [description]
+
+~design 覆盖统一执行流程的 ORIENT、CLARIFY 和 PLAN 阶段（上下文收集+深度需求挖掘+方案设计），执行阶段进入统一执行流程。
+
+## 铁律
+- 在用户确认方案之前，禁止编写任何实现代码、创建任何文件、或执行任何实现操作。
+- "这个太简单不需要设计" → 简单项目设计也简单，跳过设计的项目返工更多。
+- 需求挖掘阶段不读取实现类技能（hello-ui/hello-test/hello-verify 等），需求明确后再按需读取。
+
+## 流程
+
+### 1. 上下文收集（ORIENT）
+
+已有项目：
+- 读取 .helloagents/context.md 获取项目上下文和模块索引
+- 读取 .helloagents/guidelines.md 获取项目约定
+- 扫描相关代码文件理解现有架构
+
+全新项目（无 .helloagents/ 目录）：
+- 跳过，直接进入需求挖掘
+
+### 2. 需求挖掘（CLARIFY，交互式，核心阶段）
+
+目标：通过自然对话理解用户想要什么，聚焦三个方向——目的（为什么做、给谁用）、约束（平台、技术、时间）、成功标准（做到什么程度算完成）。
+
+根据项目类型选择挖掘模式：
+
+**假设模式**（已有代码库的项目，优先使用）：
+a. 先读取 5-15 个相关代码文件，理解现有架构和模式
+b. 基于代码证据形成假设列表，每个假设标注置信度（高/中/低）
+c. 向用户展示假设，请求确认/修正（通常 2-4 轮即可完成）
+d. 低置信度假设必须明确询问，高置信度假设可批量确认
+
+**交互模式**（全新项目，或假设模式信息不足时）：
+a. 理解用户的初始描述，识别已知和缺失信息
+b. 每次只问一个问题，偏好选择题，根据回答动态决定下一个问题
+c. 只问影响整体方向的决策，实现细节由 AI 自主决策
+d. 每个问题给出推荐选择和理由，让用户快速决策
+e. 每确认一个决策点就总结已确认内容
+f. 当目的、约束、成功标准都已明确，输出完整需求摘要，请用户确认
+
+选项质量要求：
+- 涉及视觉/交互/体验的问题时，选项必须体现当前前沿设计水准；若当前已加载 bootstrap 含审美/体验规则则遵循其要求，否则至少给出具体、可执行、非泛化的视觉特征
+- 不确定当前前沿趋势时，主动搜索查阅最新设计案例和技术能力后再给出选项
+- 每个选项必须包含具体的视觉特征描述，不接受泛化标签
+
+大项目检测：如果任务描述涉及多个独立子系统，先帮用户分解为子项目，每个子项目走独立的设计→计划→实施循环。
+
+用户说"就这样"或"开始设计"时，进入下一阶段。
+
+### 3. 方案探索（PLAN）
+
+基于已确认的完整需求，提出 2-3 个可行方案：
+- 每个方案简要描述架构思路和关键取舍
+- 标注推荐方案及推荐理由
+- 让用户选择或提出自己的想法
+
+涉及 UI 的方案：此时读取 hello-ui SKILL.md 获取设计规范。
+
+### 4. 方案细化
+
+用户选定方案后，一次性展示完整设计（按复杂度缩放篇幅：简单项目几段话，复杂项目详细展开）：
+- 架构与文件结构
+- 涉及 UI 时：按 hello-ui 的设计思维规范展开
+- 数据流与错误处理
+- 测试策略
+
+展示完成后集中收敛反馈；仅在方案仍未确认时收集一次性修改意见，不逐段停顿。
+
+### 5. 写入方案包
+
+将确认的方案写入本地项目：
+- 全新项目（无 .helloagents/ 目录）：先创建 .helloagents/ 和 STATE.md（按 templates/STATE.md 格式）。这是方案包写入的前置操作，不受 kb_create_mode 开关控制（方案包是流程状态，不是知识沉淀）
+- 创建 .helloagents/plans/YYYYMMDDHHMM_{feature}/
+- 按 templates/plans/ 的模板格式写入 requirements.md、design.md、tasks.md
+- 涉及 UI 的项目：生成或更新 .helloagents/DESIGN.md
+- 重写 .helloagents/STATE.md（正在做什么、关键上下文含已确认的需求摘要、下一步设为"处理方案反馈或进入执行决策"、方案路径）
+
+知识库的完整创建和方案包归档由当前已加载 bootstrap 中的 VALIDATE 规则统一管理。
+
+### 6. 执行决策
+
+展示方案摘要后，仅在是否进入执行仍构成阻塞决策时才询问用户：
+- 开始执行 → 重写 STATE.md（正在做什么、关键上下文、下一步设为第一个任务的具体动作）
+- 修改方案
+- 暂不执行，保留方案 → 重写 STATE.md（下一步设为"方案已确认；执行需用户明确启动"）
+
+如果用户已对当前方案或继续执行作出明确同意，视为执行授权成立，直接进入执行，不再追加确认环节。
+
+### 7. 执行
+
+按 tasks.md 逐项完成，每项进入当前已加载 bootstrap 中定义的统一执行流程，完成后同步重写 STATE.md。任务状态标记仅写入 tasks.md、验收清单或验证结果；普通说明、方案解释、状态汇报不用 [√] / [-] / [ ]。
+所有任务完成后进入当前已加载 bootstrap 中定义的 VALIDATE 阶段。
+可并行的任务标记后用子代理并行执行（不同子代理不改同一文件）。
+执行过程中遇到阻塞（依赖缺失、指令不清、验证反复失败）→ 立即停下询问用户，不猜测。
+执行过程中遇到高风险操作（删除文件/修改配置/数据库变更）→ 暂停确认。
+
+任务分解原则：
+- 每个任务是一个原子操作（单一关注点，可独立完成和验证）
+- 每个任务包含：具体文件路径、预期变更、验证方式
+- 每个任务独立可验证
+- 任务之间有明确的依赖顺序

package/skills/commands/help/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: ~help
+description: 显示 HelloAGENTS 可用命令和当前设置（~help 命令）
+policy:
+  allow_implicit_invocation: false
+---
+Trigger: ~help
+
+## 显示内容
+
+### 可用命令
+| 命令 | 说明 |
+|------|------|
+| ~auto | 全自动执行：AI 自主分析需求、设计方案并执行 |
+| ~design | 深度设计：交互式需求挖掘 + 方案设计 + 方案包 |
+| ~prd | 完整 PRD：头脑风暴式逐维度挖掘，生成现代产品需求文档 |
+| ~loop | 自主迭代优化：设定目标和指标，循环修改-验证-保留/回滚 |
+| ~init | 初始化项目知识库和配置 |
+| ~test | 为指定模块或最近变更编写完整测试 |
+| ~verify | 运行所有验证命令并报告结果 |
+| ~review | 代码审查 |
+| ~commit | 规范化提交 + 知识库同步 |
+| ~clean | 清理临时文件和归档方案包 |
+| ~help | 显示此帮助 |
+
+### 自动激活技能
+适用条件：以下技能仅在全局模式，或当前项目已通过 `~init` 激活后自动激活：
+排除条件：纯标准模式未激活项目不会自动触发。
+
+编码时：hello-ui, hello-api, hello-data, hello-security, hello-errors, hello-perf, hello-arch, hello-test
+特定场景：hello-debug, hello-subagent, hello-write, hello-review
+完成时：hello-verify, hello-reflect
+
+### 当前设置
+适用条件：优先使用当前上下文中已注入的“当前用户设置”显示；仅在上下文不存在该信息时，才尝试读取 `~/.helloagents/helloagents.json`。
+排除条件：如果当前 CLI 存在工作区限制导致家目录不可读，则明确说明“无法直接读取配置文件，以下按已注入设置或默认值展示”，不要改用无关工具或伪造已读取结果。
+| 配置项 | 默认值 | 作用 | 适用 CLI |
+|--------|-------|------|---------|
+| output_language | "" | 空=跟随用户语言/填写则指定（如 zh-CN、en） | Claude Code + Gemini CLI + Codex CLI |
+| output_format | true | true=适用条件：仅主代理在流式结束后的最终收尾回复可使用 HelloAGENTS 格式；排除条件：所有流式/中间输出及所有子代理输出保持自然；false=自然输出 | Claude Code + Gemini CLI + Codex CLI |
+| notify_level | 0 | 0=关闭/1=桌面通知/2=声音/3=两者 | Claude Code + Gemini CLI + Codex CLI |
+| ralph_loop_enabled | true | 自动验证循环（任务完成时触发 lint/test/build） | Claude Code + Gemini CLI + Codex CLI |
+| guard_enabled | true | 阻断危险命令与写入后的安全扫描 | Claude Code + Gemini CLI + Codex CLI |
+| kb_create_mode | 1 | 0=关闭/1=编码自动/2=始终 | Claude Code + Gemini CLI + Codex CLI |
+| commit_attribution | "" | 空=不添加/填写内容则添加到 commit message | Claude Code + Gemini CLI + Codex CLI |

package/skills/commands/init/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: ~init
+description: 初始化项目知识库和配置（~init 命令）
+policy:
+  allow_implicit_invocation: false
+---
+Trigger: ~init
+
+~init 是用户显式命令，创建完整知识库，不受 kb_create_mode 限制。
+
+## 流程
+
+### 阶段 1：环境搭建（必做）
+
+1. 创建 `.helloagents/` 目录 + STATE.md（按 templates/STATE.md 格式，初始为空闲）
+2. 定位插件根目录：优先读取当前会话中注入的“当前 HelloAGENTS 包根目录”；若上下文未提供，再根据当前已加载载体和规则反推，禁止猜测其他目录
+3. 创建 `skills/helloagents` symlink → `{插件根目录}/`
+4. 读取 `{插件根目录}/bootstrap.md`，用 `<!-- HELLOAGENTS_START -->` / `<!-- HELLOAGENTS_END -->` 标记包裹后写入：
+   - `AGENTS.md`（项目根目录，Codex 读取）
+   - `CLAUDE.md`（项目根目录，Claude Code 读取）
+   - `.gemini/GEMINI.md`（Gemini CLI 读取，需先创建 .gemini/ 目录）
+   注意：如果文件已存在且包含标记，替换标记内的内容；如果文件已存在但无标记，追加到末尾；如果文件不存在，创建新文件
+5. 追加 `.gitignore`（如果对应行不存在）：
+   ```
+   .helloagents/
+   skills/helloagents
+   AGENTS.md
+   CLAUDE.md
+   .gemini/GEMINI.md
+   ```
+
+### 阶段 2：知识库创建（条件性）
+
+检查项目是否有实际代码文件（非空项目）：
+- 有代码文件 → 执行完整知识库创建（下方流程）
+- 空项目 → 跳过，告知用户"项目为空，知识库将在后续开发中创建"
+
+知识库创建流程（与原 ~init 一致）：
+1. 按 templates/ 目录的模板格式，分析项目代码库后生成：
+   - context.md — 按 templates/context.md 格式，填入项目概述、技术栈、架构、目录结构、模块链接
+   - guidelines.md — 按 templates/guidelines.md 格式，从现有代码推断编码约定
+   - verify.yaml — 验证命令（从 package.json/pyproject.toml 检测）
+   - CHANGELOG.md — 按 templates/CHANGELOG.md 格式，初始版本
+   - DESIGN.md — 如果项目包含 UI 代码，按 templates/DESIGN.md 格式提取设计系统
+2. 创建 modules/ 目录，按 templates/modules/module.md 格式为主要模块生成文档
+3. 不覆盖已存在的文件
+
+## verify.yaml 格式
+```yaml
+commands:
+  - npm run lint
+  - npm run test
+```
+
+## 幂等性
+重复执行 ~init 是安全的：
+- 已存在的 .helloagents/ 文件不覆盖
+- symlink 刷新（删除旧的重建）
+- AGENTS.md/CLAUDE.md/GEMINI.md 中标记内容替换更新
+- .gitignore 只追加缺失行