hamster-wheel-cli 0.1.0 → 0.2.0-beta.1

package/docs/ai-workflow.md

@@ -8,42 +8,33 @@
 - 与 git/PR 相关的操作仅使用 `gh` 命令（查看 PR、创建 PR、查看 Actions 失败记录）。
 - 默认测试命令：单元测试 `yarn test`，e2e 测试 `yarn e2e`，如需调整请在 plan 中显式写出新的命令。
 
-## 步骤 1：完善需求
-- 复述并澄清任务，标出输入、输出、约束、验收标准。
-- 列出不确定点并自行做出合理假设（在 notes 记录假设）。
-- 产出：需求摘要（要写入 notes）。
-
-## 步骤 2：生成计划
-- 形成分阶段的任务树：需求澄清 → 设计 → 开发 → 自审 → 测试 → PR。
-- 为每个阶段列出可执行子任务、负责人（默认 AI）、预计产出、检查点。
-- 将计划写入 `plan` 文件，保持随迭代更新，已完成项用 ✅ 标记。
-
-## 步骤 3：设计与开发
-- 先给出技术方案：文件/模块变更列表、数据结构、关键算法、外部依赖、潜在风险。
-- 直接生成或修改代码；若需脚手架/依赖，请写出命令并在可行时直接执行。
-- 代码须符合 TypeScript 严格类型（避免 any），遵循项目现有规范。
-
-## 步骤 4：代码自审
-- 自检清单：
-  - 需求覆盖与边界条件是否完整。
-  - 类型安全、错误处理、日志可读性。
-  - 与 git worktree 兼容性、命令幂等性。
-- 产出：风险与改进列表，写入 notes。
-
-## 步骤 5：生成与执行测试
-- 至少输出：
-  - 单元测试范围与用例表。
-  - e2e 场景与前置条件。
-  - 对应的命令行（可直接运行）。
-- 在环境允许时直接执行测试命令，收集结果与失败原因写入 notes。
-
-## 步骤 6：推送并提交 PR
-- 检查 git 状态，准备提交信息（建议格式：`chore: <任务概要>`）。
-- 使用 `gh pr create --head <branch> --title "<标题>" --body-file <path>`（或 `--body "<正文>"`）创建 PR，正文应包含：
-  - 变更摘要（bullet 列表）
-  - 测试结果（含失败原因）
-  - 风险与回滚方案
-- 若已有 PR，使用 `gh pr view <branch>` 获取链接；查看 Actions 失败可运行 `gh run list --branch <branch>`。
+## 步骤 1：初始化与计划
+- 新建 AI session，基于 `-t` 任务生成规范分支名（<type>/<slug>），并写入 notes。
+- 生成或优化 `plan.md`：
+  - 计划仅包含开发相关事项（设计/实现/重构/配置/文档更新），不包含测试、代码质量检查、PR 等环节。
+  - 若已有 plan.md 且合理则不改，不合理则优化或重写。
+  - 已完成项用 ✅ 标记。
+
+## 步骤 2：执行计划循环
+- 每次循环仅执行 plan 中最后一条未完成项。
+- 完成后立即在 plan.md 中标记 ✅，并将进展写入 notes。
+- 当所有计划项完成时结束循环。
+
+## 步骤 3：代码质量审查
+- 新建 AI session，读取项目配置并执行可用的代码质量检查（如 lint/typecheck）。
+- 若 AGENTS.md 明确要求跳过，或命令行指定跳过该环节，则直接跳过并记录原因。
+- 若检查失败：结束当前 session，创建新的 AI session 进行修复；修复后重新执行质量检查，直到通过。
+
+## 步骤 4：测试
+- 新建 AI session，执行单元测试与 e2e 测试。
+- 若测试失败：结束当前 session，创建新的 AI session 进行修复；修复后重新执行测试，直到通过。
+
+## 步骤 5：文档更新
+- 更新版本号、CHANGELOG、README、docs 等必要文档，并记录到 notes。
+
+## 步骤 6：提交与 PR
+- 如参数允许：`git add` → AI 总结变更 → `git commit` → `git push` → `gh pr create`。
+- PR 标题/正文使用 AI 总结生成的内容；如配置自动合并则在检查通过后合并。
 
 ## 步骤 7：持久化记忆与对话续航
 - 每轮结束必须向 notes 追加：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hamster-wheel-cli",
-  "version": "0.1.0",
+  "version": "0.2.0-beta.1",
   "description": "基于 AI CLI 的持续迭代开发工具，封装工作流、git worktree 与 gh PR 协作",
   "main": "dist/index.js",
   "keywords": [

package/src/ai.ts

@@ -39,6 +39,334 @@ export function buildPrompt(input: PromptInput): string {
   return sections.join('\n\n');
 }
 
+function compactLine(text: string): string {
+  return text.replace(/\s+/g, ' ').trim();
+}
+
+interface BranchNamePromptInput {
+  readonly task: string;
+}
+
+/**
+ * 构建分支名生成提示。
+ */
+export function buildBranchNamePrompt(input: BranchNamePromptInput): string {
+  return [
+    '# 角色',
+    '你是资深工程师，需要根据任务生成规范的 git 分支名。',
+    '# 规则',
+    '- 输出格式仅限严格 JSON（不要 markdown、不要代码块、不要解释）。',
+    '- 分支名格式：<type>/<slug>。',
+    '- type 可选：feat、fix、docs、refactor、chore、test。',
+    '- slug 使用小写英文、数字、连字符，长度 3~40，避免空格与中文。',
+    '# 输出 JSON',
+    '{"branch":"..."}',
+    '# 任务描述',
+    compactLine(input.task) || '（空）'
+  ].join('\n\n');
+}
+
+interface PlanningPromptInput {
+  readonly task: string;
+  readonly workflowGuide: string;
+  readonly plan: string;
+  readonly notes: string;
+  readonly branchName?: string;
+}
+
+/**
+ * 构建计划生成提示。
+ */
+export function buildPlanningPrompt(input: PlanningPromptInput): string {
+  return [
+    '# 背景任务',
+    input.task,
+    '# 分支信息',
+    input.branchName ? `计划使用分支：${input.branchName}` : '未指定分支名，请按任务语义给出建议',
+    '# 工作流程基线（供 AI 自主执行）',
+    input.workflowGuide,
+    '# 当前计划',
+    input.plan || '（暂无计划）',
+    '# 历史记忆',
+    input.notes || '（暂无历史）',
+    '# 本轮执行要求',
+    [
+      '1. 分析任务输入/输出/约束/验收标准，必要时补充合理假设（写入 notes）。',
+      '2. 若 plan.md 已存在，请判断是否合理；合理则不修改，不合理则优化或重写。',
+      '3. 计划只包含开发相关任务（设计/实现/重构/配置/文档更新），不要包含测试、自审、PR、提交等内容。',
+      '4. 计划项需可执行、颗粒度清晰，已完成项使用 ✅ 标记。',
+      '5. 更新 memory/plan.md 与 memory/notes.md 后结束本轮。'
+    ].join('\n')
+  ].join('\n\n');
+}
+
+interface PlanItemPromptInput {
+  readonly task: string;
+  readonly workflowGuide: string;
+  readonly plan: string;
+  readonly notes: string;
+  readonly item: string;
+}
+
+/**
+ * 构建单条计划执行提示。
+ */
+export function buildPlanItemPrompt(input: PlanItemPromptInput): string {
+  return [
+    '# 背景任务',
+    input.task,
+    '# 工作流程基线（供 AI 自主执行）',
+    input.workflowGuide,
+    '# 当前计划',
+    input.plan || '（暂无计划）',
+    '# 历史记忆',
+    input.notes || '（暂无历史）',
+    '# 本轮要执行的计划项（仅此一条）',
+    input.item,
+    '# 本轮执行要求',
+    [
+      '1. 只执行上述计划项，避免提前处理其它计划项。',
+      '2. 完成后立即在 plan.md 中将该项标记为 ✅。',
+      '3. 必要时可对计划项进行微调，但仍需确保当前项完成。',
+      '4. 本轮不执行测试或质量检查。',
+      '5. 将进展、关键改动与风险写入 notes。'
+    ].join('\n')
+  ].join('\n\n');
+}
+
+interface QualityPromptInput {
+  readonly task: string;
+  readonly workflowGuide: string;
+  readonly plan: string;
+  readonly notes: string;
+  readonly commands: string[];
+  readonly results?: string;
+}
+
+/**
+ * 构建质量检查提示。
+ */
+export function buildQualityPrompt(input: QualityPromptInput): string {
+  return [
+    '# 背景任务',
+    input.task,
+    '# 工作流程基线（供 AI 自主执行）',
+    input.workflowGuide,
+    '# 当前计划',
+    input.plan || '（暂无计划）',
+    '# 历史记忆',
+    input.notes || '（暂无历史）',
+    '# 本轮代码质量检查',
+    input.commands.length > 0 ? input.commands.map(cmd => `- ${cmd}`).join('\n') : '未检测到可执行的质量检查命令。',
+    input.results ? `# 命令执行结果\n${input.results}` : '',
+    '# 本轮执行要求',
+    [
+      '1. 本轮仅进行代码质量检查，不要修复问题。',
+      '2. 若出现失败，记录失败要点，等待下一轮修复。',
+      '3. 将结论与风险写入 notes。'
+    ].join('\n')
+  ].filter(Boolean).join('\n\n');
+}
+
+interface FixPromptInput {
+  readonly task: string;
+  readonly workflowGuide: string;
+  readonly plan: string;
+  readonly notes: string;
+  readonly stage: string;
+  readonly errors: string;
+}
+
+/**
+ * 构建问题修复提示（质量检查 / 测试）。
+ */
+export function buildFixPrompt(input: FixPromptInput): string {
+  return [
+    '# 背景任务',
+    input.task,
+    '# 工作流程基线（供 AI 自主执行）',
+    input.workflowGuide,
+    '# 当前计划',
+    input.plan || '（暂无计划）',
+    '# 历史记忆',
+    input.notes || '（暂无历史）',
+    `# 需要修复的问题（${input.stage}）`,
+    input.errors || '（无错误信息）',
+    '# 本轮执行要求',
+    [
+      '1. 聚焦修复当前问题，不要扩展范围。',
+      '2. 修复完成后更新 notes，说明修改点与影响。',
+      '3. 如需调整计划，请同步更新 plan.md。'
+    ].join('\n')
+  ].join('\n\n');
+}
+
+interface TestPromptInput {
+  readonly task: string;
+  readonly workflowGuide: string;
+  readonly plan: string;
+  readonly notes: string;
+  readonly commands: string[];
+  readonly results?: string;
+}
+
+/**
+ * 构建测试执行提示。
+ */
+export function buildTestPrompt(input: TestPromptInput): string {
+  return [
+    '# 背景任务',
+    input.task,
+    '# 工作流程基线（供 AI 自主执行）',
+    input.workflowGuide,
+    '# 当前计划',
+    input.plan || '（暂无计划）',
+    '# 历史记忆',
+    input.notes || '（暂无历史）',
+    '# 本轮测试命令',
+    input.commands.length > 0 ? input.commands.map(cmd => `- ${cmd}`).join('\n') : '未配置测试命令。',
+    input.results ? `# 测试结果\n${input.results}` : '',
+    '# 本轮执行要求',
+    [
+      '1. 本轮仅执行测试，不要修复问题。',
+      '2. 若出现失败，记录失败要点，等待下一轮修复。',
+      '3. 将测试结论写入 notes。'
+    ].join('\n')
+  ].filter(Boolean).join('\n\n');
+}
+
+interface DocsPromptInput {
+  readonly task: string;
+  readonly workflowGuide: string;
+  readonly plan: string;
+  readonly notes: string;
+}
+
+/**
+ * 构建文档更新提示。
+ */
+export function buildDocsPrompt(input: DocsPromptInput): string {
+  return [
+    '# 背景任务',
+    input.task,
+    '# 工作流程基线（供 AI 自主执行）',
+    input.workflowGuide,
+    '# 当前计划',
+    input.plan || '（暂无计划）',
+    '# 历史记忆',
+    input.notes || '（暂无历史）',
+    '# 本轮执行要求',
+    [
+      '1. 根据本次改动更新版本号、CHANGELOG、README、docs 等相关文档。',
+      '2. 仅更新确有变化的文档，保持中文说明。',
+      '3. 将更新摘要写入 notes。'
+    ].join('\n')
+  ].join('\n\n');
+}
+
+function extractJson(text: string): string | null {
+  const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  if (fenced?.[1]) return fenced[1].trim();
+  const start = text.indexOf('{');
+  const end = text.lastIndexOf('}');
+  if (start >= 0 && end > start) {
+    return text.slice(start, end + 1).trim();
+  }
+  return null;
+}
+
+const BRANCH_TYPES = ['feat', 'fix', 'docs', 'refactor', 'chore', 'test'] as const;
+type BranchType = typeof BRANCH_TYPES[number];
+
+const BRANCH_TYPE_ALIASES: Record<string, BranchType> = {
+  feature: 'feat',
+  features: 'feat',
+  bugfix: 'fix',
+  hotfix: 'fix',
+  doc: 'docs',
+  documentation: 'docs',
+  refactoring: 'refactor',
+  chores: 'chore',
+  tests: 'test'
+};
+
+function isBranchType(value: string): value is BranchType {
+  return BRANCH_TYPES.includes(value as BranchType);
+}
+
+function normalizeBranchType(value: string): BranchType | null {
+  const trimmed = value.trim().toLowerCase();
+  if (!trimmed) return null;
+  if (isBranchType(trimmed)) return trimmed;
+  return BRANCH_TYPE_ALIASES[trimmed] ?? null;
+}
+
+function normalizeBranchSlug(value: string): string | null {
+  const cleaned = value
+    .toLowerCase()
+    .replace(/\s+/g, '-')
+    .replace(/_/g, '-')
+    .replace(/[^a-z0-9-]/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  if (!cleaned) return null;
+  const trimmed = cleaned.slice(0, 40);
+  if (trimmed.length < 3) return null;
+  return trimmed;
+}
+
+function normalizeBranchNameCandidate(value: string): string | null {
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  const lowered = trimmed.toLowerCase();
+  const parts = lowered.split('/').filter(part => part.length > 0);
+  const hasExplicitType = lowered.includes('/') && parts.length >= 2;
+  const rawType = hasExplicitType ? parts.shift() ?? '' : '';
+  const rawSlug = hasExplicitType ? parts.join('-') : lowered;
+
+  const type = rawType ? normalizeBranchType(rawType) : 'feat';
+  if (!type) return null;
+
+  const slug = normalizeBranchSlug(rawSlug);
+  if (!slug) return null;
+
+  return `${type}/${slug}`;
+}
+
+/**
+ * 解析 AI 输出中的分支名。
+ */
+export function parseBranchName(output: string): string | null {
+  const jsonText = extractJson(output);
+  if (jsonText) {
+    try {
+      const parsed = JSON.parse(jsonText) as Record<string, unknown>;
+      const raw = typeof parsed.branch === 'string'
+        ? parsed.branch
+        : typeof parsed.branchName === 'string'
+          ? parsed.branchName
+          : typeof parsed['分支'] === 'string'
+            ? (parsed['分支'] as string)
+            : typeof parsed['分支名'] === 'string'
+              ? (parsed['分支名'] as string)
+              : null;
+      if (raw) {
+        const normalized = normalizeBranchNameCandidate(raw);
+        if (normalized) return normalized;
+      }
+    } catch {
+      // 忽略解析失败，回退到文本匹配
+    }
+  }
+
+  const lineMatch = output.match(/(?:branch(?:name)?|分支名|分支)\s*[:：]\s*([^\s]+)/i);
+  if (lineMatch?.[1]) {
+    const normalized = normalizeBranchNameCandidate(lineMatch[1]);
+    if (normalized) return normalized;
+  }
+  return null;
+}
+
 function pickNumber(pattern: RegExp, text: string): number | undefined {
   const match = pattern.exec(text);
   if (!match || match.length < 2) return undefined;
@@ -139,8 +467,11 @@ export async function runAi(prompt: string, ai: AiCliConfig, logger: Logger, cwd
  * 生成 notes 迭代记录文本。
  */
 export function formatIterationRecord(record: IterationRecord): string {
+  const title = record.stage
+    ? `### 迭代 ${record.iteration} ｜ ${record.timestamp} ｜ ${record.stage}`
+    : `### 迭代 ${record.iteration} ｜ ${record.timestamp}`;
   const lines = [
-    `### 迭代 ${record.iteration} ｜ ${record.timestamp}`,
+    title,
     '',
     '#### 提示上下文',
     '```',
@@ -154,6 +485,20 @@ export function formatIterationRecord(record: IterationRecord): string {
     ''
   ];
 
+  if (record.checkResults && record.checkResults.length > 0) {
+    lines.push('#### 质量检查结果');
+    record.checkResults.forEach(result => {
+      const status = result.success ? '✅ 通过' : '❌ 失败';
+      lines.push(`${status} ｜ ${result.name} ｜ 命令: ${result.command} ｜ 退出码: ${result.exitCode}`);
+      if (!result.success) {
+        lines.push('```');
+        lines.push(result.stderr || result.stdout || '（无输出）');
+        lines.push('```');
+        lines.push('');
+      }
+    });
+  }
+
   if (record.testResults && record.testResults.length > 0) {
     lines.push('#### 测试结果');
     record.testResults.forEach(result => {

package/src/alias-viewer.ts

@@ -0,0 +1,221 @@
+import fs from 'fs-extra';
+import { AliasEntry, getGlobalConfigPath, parseAliasEntries } from './global-config';
+
+interface AliasViewerState {
+  aliases: AliasEntry[];
+  selectedIndex: number;
+  listOffset: number;
+  missingConfig: boolean;
+  lastError?: string;
+}
+
+function getTerminalSize(): { rows: number; columns: number } {
+  const rows = process.stdout.rows ?? 24;
+  const columns = process.stdout.columns ?? 80;
+  return { rows, columns };
+}
+
+function truncateLine(line: string, width: number): string {
+  if (width <= 0) return '';
+  if (line.length <= width) return line;
+  return line.slice(0, width);
+}
+
+function getPageSize(rows: number): number {
+  return Math.max(1, rows - 2);
+}
+
+function buildAliasLabel(entry: AliasEntry): string {
+  if (entry.source === 'shortcut') {
+    return `${entry.name}（shortcut）`;
+  }
+  return entry.name;
+}
+
+function buildHeader(state: AliasViewerState, columns: number): string {
+  const total = state.aliases.length;
+  const title = `别名列表（${total} 条）｜↑/↓ 选择  q 退出`;
+  return truncateLine(title, columns);
+}
+
+function buildStatus(state: AliasViewerState, columns: number): string {
+  if (state.aliases.length === 0) {
+    if (state.lastError) {
+      return truncateLine(`读取失败：${state.lastError}`, columns);
+    }
+    if (state.missingConfig) {
+      return truncateLine(`未找到配置文件：${getGlobalConfigPath()}`, columns);
+    }
+    return truncateLine('未发现 alias 配置', columns);
+  }
+
+  const entry = state.aliases[state.selectedIndex];
+  const sourceText = entry.source === 'shortcut' ? '（shortcut）' : '';
+  return truncateLine(`命令${sourceText}：${entry.command}`, columns);
+}
+
+function buildListLine(entry: AliasEntry, selected: boolean, columns: number): string {
+  const marker = selected ? '>' : ' ';
+  return truncateLine(`${marker} ${buildAliasLabel(entry)}`, columns);
+}
+
+function ensureListOffset(state: AliasViewerState, pageSize: number): void {
+  const total = state.aliases.length;
+  if (total === 0) {
+    state.listOffset = 0;
+    state.selectedIndex = 0;
+    return;
+  }
+  const maxOffset = Math.max(0, total - pageSize);
+  if (state.selectedIndex < state.listOffset) {
+    state.listOffset = state.selectedIndex;
+  }
+  if (state.selectedIndex >= state.listOffset + pageSize) {
+    state.listOffset = state.selectedIndex - pageSize + 1;
+  }
+  state.listOffset = Math.min(Math.max(state.listOffset, 0), maxOffset);
+}
+
+function render(state: AliasViewerState): void {
+  const { rows, columns } = getTerminalSize();
+  const pageSize = getPageSize(rows);
+  const header = buildHeader(state, columns);
+  ensureListOffset(state, pageSize);
+
+  if (state.aliases.length === 0) {
+    const filler = Array.from({ length: pageSize }, () => '');
+    const status = buildStatus(state, columns);
+    const content = [header, ...filler, status].join('\n');
+    process.stdout.write(`\u001b[2J\u001b[H${content}`);
+    return;
+  }
+
+  const start = state.listOffset;
+  const slice = state.aliases.slice(start, start + pageSize);
+  const lines = slice.map((entry, index) => {
+    const selected = start + index === state.selectedIndex;
+    return buildListLine(entry, selected, columns);
+  });
+  while (lines.length < pageSize) {
+    lines.push('');
+  }
+  const status = buildStatus(state, columns);
+  const content = [header, ...lines, status].join('\n');
+  process.stdout.write(`\u001b[2J\u001b[H${content}`);
+}
+
+function shouldExit(input: string): boolean {
+  if (input === '\u0003') return true;
+  if (input.toLowerCase() === 'q') return true;
+  return false;
+}
+
+function isArrowUp(input: string): boolean {
+  return input.includes('\u001b[A');
+}
+
+function isArrowDown(input: string): boolean {
+  return input.includes('\u001b[B');
+}
+
+function setupCleanup(cleanup: () => void): void {
+  const exitHandler = (): void => {
+    cleanup();
+  };
+  const signalHandler = (): void => {
+    cleanup();
+    process.exit(0);
+  };
+  process.on('SIGINT', signalHandler);
+  process.on('SIGTERM', signalHandler);
+  process.on('exit', exitHandler);
+}
+
+function clampIndex(value: number, total: number): number {
+  if (total <= 0) return 0;
+  return Math.min(Math.max(value, 0), total - 1);
+}
+
+/**
+ * 启动 alias 浏览界面。
+ */
+export async function runAliasViewer(): Promise<void> {
+  if (!process.stdout.isTTY || !process.stdin.isTTY) {
+    console.log('当前终端不支持交互式 alias。');
+    return;
+  }
+
+  const state: AliasViewerState = {
+    aliases: [],
+    selectedIndex: 0,
+    listOffset: 0,
+    missingConfig: false
+  };
+
+  let cleaned = false;
+  const cleanup = (): void => {
+    if (cleaned) return;
+    cleaned = true;
+    if (process.stdin.isTTY) {
+      process.stdin.setRawMode(false);
+      process.stdin.pause();
+    }
+    process.stdout.write('\u001b[?25h');
+  };
+
+  setupCleanup(cleanup);
+  process.stdout.write('\u001b[?25l');
+  process.stdin.setRawMode(true);
+  process.stdin.resume();
+
+  const loadAliases = async (): Promise<void> => {
+    const filePath = getGlobalConfigPath();
+    const exists = await fs.pathExists(filePath);
+    if (!exists) {
+      state.aliases = [];
+      state.selectedIndex = 0;
+      state.lastError = undefined;
+      state.missingConfig = true;
+      return;
+    }
+
+    try {
+      const content = await fs.readFile(filePath, 'utf8');
+      state.aliases = parseAliasEntries(content);
+      state.selectedIndex = clampIndex(state.selectedIndex, state.aliases.length);
+      state.lastError = undefined;
+      state.missingConfig = false;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      state.aliases = [];
+      state.selectedIndex = 0;
+      state.lastError = message;
+      state.missingConfig = false;
+    }
+  };
+
+  await loadAliases();
+  render(state);
+
+  process.stdin.on('data', (data: Buffer) => {
+    const input = data.toString('utf8');
+    if (shouldExit(input)) {
+      cleanup();
+      process.exit(0);
+    }
+
+    if (isArrowUp(input)) {
+      state.selectedIndex = clampIndex(state.selectedIndex - 1, state.aliases.length);
+      render(state);
+      return;
+    }
+    if (isArrowDown(input)) {
+      state.selectedIndex = clampIndex(state.selectedIndex + 1, state.aliases.length);
+      render(state);
+    }
+  });
+
+  process.stdout.on('resize', () => {
+    render(state);
+  });
+}