replicate-issue

复现 GitHub Issue

系统地在运行中的 Archon 应用中复现并验证 GitHub Issue。 目标是确定报告的问题是否真实存在，找出确切的复现步骤，发现任何相关问题，并提供可执行的修复建议。

Issue 编号：$ARGUMENTS

如果 $ARGUMENTS 为空，请在继续之前向用户询问 Issue 编号。

---

阶段 0：准备环境

0.1 切换到 Main 分支并拉取最新代码

确保基于 main 上的最新代码进行测试，以确保结果准确。

cd /path/to/archon

# Stash any local changes to avoid conflicts
git stash 2>/dev/null || true

# Switch to main and pull latest
git checkout main
git pull origin main

echo "On branch: $(git branch --show-current)"
echo "Latest commit: $(git log --oneline -1)"

0.2 终止现有 Archon 进程

释放端口 3090（后端）和 5173（前端），以便干净地启动 Archon。

pkill -f "bun.*dev:server" 2>/dev/null || true
pkill -f "bun.*dev:web" 2>/dev/null || true
pkill -f "bun.*packages/server" 2>/dev/null || true
pkill -f "bun.*packages/web" 2>/dev/null || true
fuser -k 3090/tcp 2>/dev/null || true
fuser -k 5173/tcp 2>/dev/null || true
sleep 2

# Verify ports are free
! fuser 3090/tcp 2>/dev/null && ! fuser 5173/tcp 2>/dev/null && echo "Ports 3090 and 5173 are free" || echo "WARNING: Ports still in use"

0.3 启动 Archon 后端和前端

cd /path/to/archon

# Start both backend and frontend together
bun run dev &
sleep 8

# Verify backend is healthy
curl -s http://localhost:3090/api/health | head -c 200
echo ""

# Verify frontend is serving (port may vary if 5173 is taken)
curl -s http://localhost:5173 | head -c 100 || curl -s http://localhost:5174 | head -c 100

注意：如果端口 5173 被占用，Vite 会自动递增端口号（5174、5175 等）。检查 bun run dev 的输出，确认实际的前端端口，并在整个过程中使用该端口。

---

阶段 1：分析 Issue

1.1 阅读 GitHub Issue

gh issue view $ARGUMENTS --json title,body,labels,comments,state

仔细解析 Issue，提取以下信息：

• 标题和摘要：报告的问题是什么？
• 复现步骤：哪些具体操作会触发 Bug？
• 预期行为：应该发生什么？
• 实际行为：实际发生了什么？
• 环境详情：是否有特定条件（浏览器、操作系统、时机）？
• 标签和优先级：问题有多严重？
• 评论：是否有其他背景信息、解决方法或相关问题？

1.2 制定测试计划

根据 Issue 内容，创建一份具体的测试清单。 针对 Issue 中描述的每种症状，明确：

1. 复现问题的准确用户操作流程
2. 需要观察的内容（预期结果与实际结果）
3. 需要捕获哪些截图作为证据

---

阶段 2：使用浏览器自动化进行复现

所有浏览器交互均使用 agent-browser CLI（而非 Playwright）。

核心工作流

# 1. Navigate to the page
agent-browser open http://localhost:5173

# 2. Get interactive elements
agent-browser snapshot -i

# 3. Interact using refs from the snapshot
agent-browser click @e1
agent-browser fill @e2 "text"

# 4. Re-snapshot after navigation or DOM changes
agent-browser snapshot -i

# 5. Take screenshots at every significant point
agent-browser screenshot /tmp/issue-$ARGUMENTS-{step-name}.png

测试指南

• 多截取截图——每次操作前后都要截图，并保存到 /tmp/issue-$ARGUMENTS-*.png
• 读取每张截图——使用 Read 工具直观检查每张截图，并核实所见内容
• 先测试正常流程——在测试 Bug 之前，确认功能在正常情况下可以运行
• 严格遵循 Issue 中的复现步骤——不要走捷径
• 测试不同情况——尝试略有差异的相同流程（不同数据、不同时间、刷新页面）
• 测试相邻流程——如果问题涉及工作流 X，也要检查工作流 Y 和 Z 是否存在类似问题
• 使用 curl 验证 API——将 UI 状态与直接 API 调用进行交叉核对，以确认数据准确性
• 页面刷新后进行检查——许多 SSE／实时 Bug 只会在导航或刷新后出现
• 检查不同对话——如果问题涉及对话，请使用多个已打开的对话进行测试
• 等待异步操作——对依赖网络的操作使用 agent-browser wait 命令

触发工作流（如有需要）

如果问题涉及工作流执行，请使用 REST API 触发后台工作流：

# Create a conversation
CONV_ID=$(curl -s -X POST http://localhost:3090/api/conversations \
  -H "Content-Type: application/json" -d '{}' | jq -r '.conversationId')

# Trigger a workflow (archon-assist is a good general-purpose one)
curl -s -X POST http://localhost:3090/api/workflows/archon-assist/run \
  -H "Content-Type: application/json" \
  -d "{\"conversationId\":\"$CONV_ID\",\"message\":\"Your test message here\"}"

触发聊天消息（如有需要）

curl -s -X POST "http://localhost:3090/api/conversations/$CONV_ID/message" \
  -H "Content-Type: application/json" \
  -d '{"message":"Your test message"}'

---

阶段 3：记录发现

针对 Issue 中的每种症状，记录：

症状	是否复现？	证据	备注
{issue 中的症状}	是 / 否 / 部分	截图路径	{详情}

严重程度分类

• 已确认（可复现）：已复现 Issue 中描述的确切 Bug
• 部分确认：出现了该症状，但触发条件与描述不同
• 未复现：尽管遵循了所述步骤，仍无法复现
• 发现相关问题：测试期间发现了不同但相关的问题

---

阶段 4：调查根本原因（如果问题已复现）

如果问题已复现，请针对代码库进行分析：

1. 确定受影响的组件 — 涉及哪些文件、钩子或组件？
2. 阅读相关源代码 — 了解当前实现
3. 追踪数据流 — 数据来自哪里？SSE？REST？React Query？useState？
4. 确定根本原因 — 是什么具体导致了观察到的行为？
5. 检查类似模式 — 其他组件是否也存在相同问题？

---

阶段 5：提出建议

提供多个修复方案并说明各自的权衡：

方案格式

对于每条建议：

### Option N: {Short title}

**Approach**: {1-2 sentence description}

**Changes required**:
- {file}: {what changes}
- {file}: {what changes}

**Pros**:
- {benefit}

**Cons**:
- {drawback}

**Complexity**: Low / Medium / High
**Risk**: Low / Medium / High

至少提供 2-3 个方案，涵盖从快速修复到全面解决方案。

---

阶段 6：清理

# Close the browser
agent-browser close

# Stop Archon (optional — leave running if user wants to continue testing)
# fuser -k 3090/tcp 2>/dev/null
# fuser -k 5173/tcp 2>/dev/null

---

阶段 7：总结报告

向用户提交最终总结：

# Issue #$ARGUMENTS Replication Report

## Issue: {title}
**Status**: Reproduced / Not Reproduced / Partially Reproduced
**Tested on**: main @ {commit hash}

## Reproduction Summary
{2-3 sentences describing what was tested and the outcome}

## Findings
{Detailed findings with screenshot references}

## Root Cause
{If identified — what causes the bug and why}

## Related Issues Discovered
{Any additional problems found during testing}

## Recommendations
{Summary of fix options with recommended approach}

---

执行说明

• 始终使用 agent-browser（Vercel Agent Browser CLI），不要使用 Playwright
• 如需查阅命令参考，请加载 /agent-browser 技能
• 在每个重要测试节点都截取屏幕截图，作为证据
• 使用 Read 工具查看截图，直观确认 UI 显示的内容
• 如果复现需要长时间运行的操作，请耐心等待工作流完成
• 将浏览器状态与 API 响应（curl）交叉比对，以区分 UI 问题和后端问题
• 如果无法复现问题，请记录尝试过的操作，并说明可能的原因
• 完成后关闭浏览器：agent-browser close