replicate-issue

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Replicate GitHub Issue

复现GitHub Issue

Systematically reproduce and validate a GitHub issue against the live Archon application. The goal: determine whether the reported behavior is real, identify exact reproduction steps, discover any related issues, and provide actionable fix recommendations.

Issue number:

$ARGUMENTS

$ARGUMENTS

is empty, ask the user for the issue number before proceeding.

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

Issue编号：

$ARGUMENTS

如果

$ARGUMENTS

为空，请先向用户询问Issue编号再继续。

Phase 0: Prepare Environment

阶段0：准备环境

0.1 Switch to Main Branch and Pull Latest

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

Ensure you are testing against the latest code on

main

so results are accurate.

bash

cd /path/to/archon

确保你基于

main

分支的最新代码进行测试，以保证结果准确。

bash

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)"

undefined

git checkout main git pull origin main

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

undefined

0.2 Kill Existing Archon Processes

0.2 终止现有Archon进程

Free up ports 3090 (backend) and 5173 (frontend) so Archon starts cleanly.

bash

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

释放端口3090（后端）和5173（前端），确保Archon可以干净启动。

bash

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"

undefined

! 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"

undefined

0.3 Start Archon Backend + Frontend

0.3 启动Archon后端+前端

bash

cd /path/to/archon

bash

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


**Note**: If port 5173 is taken, Vite auto-increments (5174, 5175, etc.). Check the `bun run dev` output for the actual frontend port and use that throughout.

---

curl -s http://localhost:5173 | head -c 100 || curl -s http://localhost:5174 | head -c 100


**注意**：如果端口5173被占用，Vite会自动递增端口（5174、5175等）。请查看`bun run dev`的输出获取实际前端端口，并在后续操作中使用该端口。

---

Phase 1: Analyze the Issue

阶段1：分析问题

1.1 Read the GitHub Issue

1.1 读取GitHub Issue

bash

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

Parse the issue carefully. Extract:

Title and summary: What is the reported problem?
Reproduction steps: What specific actions trigger the bug?
Expected behavior: What should happen?
Actual behavior: What happens instead?
Environment details: Any specific conditions (browser, OS, timing)?
Labels and priority: How severe is this?
Comments: Any additional context, workarounds, or related issues?

bash

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

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

标题和摘要：报告的问题是什么？
复现步骤：哪些具体操作会触发Bug？
预期行为：应该发生什么？
实际行为：实际发生了什么？
环境细节：是否有特定条件（浏览器、操作系统、时机）？
标签和优先级：问题的严重程度如何？
评论：是否有额外上下文、临时解决方案或相关问题？

1.2 Build a Test Plan

1.2 制定测试计划

Based on the issue content, create a checklist of specific things to test. For each symptom described in the issue, define:

The exact user journey to reproduce it
What to look for (expected vs actual)
Screenshots to capture as evidence

基于Issue内容，创建具体的测试检查清单。针对Issue中描述的每个症状，定义：

复现该症状的完整用户流程
需要验证的内容（预期vs实际）
需要捕获的截图作为证据

Phase 2: Reproduce with Browser Automation

阶段2：通过浏览器自动化复现

Use the

agent-browser

CLI (NOT Playwright) for all browser interactions.

所有浏览器交互均使用

agent-browser

CLI（请勿使用Playwright）。

Core Workflow

核心工作流

bash

undefined

bash

undefined

1. Navigate to the page

1. 导航到页面

agent-browser open http://localhost:5173

2. Get interactive elements

2. 获取交互元素

agent-browser snapshot -i

3. Interact using refs from the snapshot

3. 使用快照中的引用进行交互

agent-browser click @e1 agent-browser fill @e2 "text"

4. Re-snapshot after navigation or DOM changes

4. 导航或DOM变更后重新快照

agent-browser snapshot -i

5. Take screenshots at every significant point

5. 在每个重要节点截图

agent-browser screenshot /tmp/issue-$ARGUMENTS-{step-name}.png

undefined

agent-browser screenshot /tmp/issue-$ARGUMENTS-{step-name}.png

undefined

Testing Guidelines

测试指南

Take screenshots liberally — before and after each action, save to
```
/tmp/issue-$ARGUMENTS-*.png
```
Read every screenshot — use the Read tool to visually inspect each screenshot and verify what you see
Test the happy path first — confirm the feature works under normal conditions before testing the bug
Follow the exact reproduction steps from the issue — don't shortcut
Test variations — try the same flow with slight differences (different data, different timing, page refresh)
Test adjacent flows — if the issue is about workflow X, also check workflows Y and Z for similar problems
Use curl for API verification — cross-reference UI state with direct API calls to confirm data accuracy
Check after page refresh — many SSE/real-time bugs only manifest after navigation or refresh
Check across conversations — if the issue involves conversations, test with multiple open conversations
Wait for async operations — use
```
agent-browser wait
```
commands for network-dependent operations

大量截图 —— 每个操作前后都要截图，保存到
```
/tmp/issue-$ARGUMENTS-*.png
```
查看每张截图 —— 使用读取工具视觉检查每张截图，验证显示内容
先测试正常流程 —— 在测试Bug前，先确认功能在正常条件下可以工作
严格遵循Issue中的复现步骤 —— 不要简化步骤
测试变体 —— 尝试流程的微小变化（不同数据、不同时机、页面刷新）
测试相邻流程 —— 如果问题与流程X相关，同时检查流程Y和Z是否存在类似问题
使用curl验证API —— 将UI状态与直接API调用交叉对比，确认数据准确性
页面刷新后检查 —— 许多SSE/实时Bug仅在导航或刷新后出现
跨对话检查 —— 如果问题涉及对话，测试多个打开的对话场景
等待异步操作 —— 对依赖网络的操作使用
```
agent-browser wait
```
命令

Triggering Workflows (if needed)

触发工作流（如有需要）

If the issue involves workflow execution, use the REST API to trigger background workflows:

bash

undefined

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

bash

undefined

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)

触发工作流（archon-assist是通用型工作流）

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"}"

undefined

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"}"

undefined

Triggering Chat Messages (if needed)

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

bash

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

bash

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

Phase 3: Document Findings

阶段3：记录调查结果

For each symptom in the issue, record:

Symptom	Reproduced?	Evidence	Notes
{symptom from issue}	YES / NO / PARTIAL	Screenshot path	{details}

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

症状	是否复现？	证据	备注
{Issue中的症状}	是 / 否 / 部分	截图路径	{详细信息}

Severity Classification

严重程度分类

Confirmed (Reproducible): The exact bug described in the issue was reproduced
Partially Confirmed: The symptom appears but under different conditions than described
Not Reproduced: Could not reproduce despite following the described steps
Related Issue Found: A different but related problem was discovered during testing

已确认（可复现）：Issue中描述的Bug已被准确复现
部分确认：症状出现，但条件与描述不同
未复现：遵循描述步骤后仍无法复现
发现相关问题：测试过程中发现了不同但相关的问题

Phase 4: Investigate Root Cause (if reproduced)

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

If the issue was reproduced, do a targeted codebase analysis:

Identify the affected components — which files/hooks/components are involved?
Read the relevant source code — understand the current implementation
Trace the data flow — where does the data come from? SSE? REST? React Query? useState?
Identify the root cause — what specifically causes the observed behavior?
Check for similar patterns — are other components vulnerable to the same issue?

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

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

Phase 5: Recommendations

阶段5：修复建议

Provide multiple fix options with trade-offs:

提供多种修复方案并说明利弊：

Option Format

方案格式

For each recommendation:

markdown

undefined

每个建议遵循以下格式：

markdown

undefined

Option N: {Short title}

方案N：{简短标题}

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


Provide at least 2-3 options ranging from quick fix to comprehensive solution.

---

方法：{1-2句话描述}

所需变更:

{文件}: {变更内容}
{文件}: {变更内容}

优点:

{好处}

缺点:

{弊端}

复杂度：低 / 中 / 高风险：低 / 中 / 高


提供至少2-3种方案，从快速修复到全面解决方案不等。

---

Phase 6: Cleanup

阶段6：清理

bash

undefined

bash

undefined

Close the browser

关闭浏览器

agent-browser close

Stop Archon (optional — leave running if user wants to continue testing)

停止Archon（可选 —— 如果用户想继续测试则保持运行）

fuser -k 3090/tcp 2>/dev/null

fuser -k 5173/tcp 2>/dev/null

---

---

Phase 7: Summary Report

阶段7：总结报告

Present a final summary to the user:

markdown

undefined

向用户呈现最终总结：

markdown

undefined

Issue #$ARGUMENTS Replication Report

Issue #$ARGUMENTS 复现报告

Issue: {title}

Issue：{标题}

Status: Reproduced / Not Reproduced / Partially Reproduced Tested on: main @ {commit hash}

状态：已复现 / 未复现 / 部分复现 测试版本：main @ {提交哈希}

Reproduction Summary

复现总结

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

{2-3句话描述测试内容和结果}

Findings

调查结果

{Detailed findings with screenshot references}

{详细结果，包含截图引用}

Root Cause

根本原因

{If identified — what causes the bug and why}

{如果已确定 —— Bug的成因及原因}

Related Issues Discovered

发现的相关问题

{Any additional problems found during testing}

{测试过程中发现的其他问题}

Recommendations

修复建议

{Summary of fix options with recommended approach}

---

{修复方案摘要及推荐方案}

---

Execution Notes

执行注意事项

Always use
```
agent-browser
```
(Vercel Agent Browser CLI), NOT Playwright
Load the
```
/agent-browser
```
skill if you need a command reference
Take screenshots at EVERY significant test point — these are your evidence
Read screenshots with the Read tool to visually verify what the UI shows
If reproduction requires long-running operations, be patient — wait for workflows to complete
Cross-reference browser state with API responses (
```
curl
```
) to distinguish UI bugs from backend bugs
If the issue cannot be reproduced, document what you tried and suggest possible reasons
Close the browser when finished:
```
agent-browser close
```

始终使用
```
agent-browser
```
（Vercel Agent Browser CLI），请勿使用Playwright
如果需要命令参考，请加载
```
/agent-browser
```
技能
在每个重要测试节点都要截图 —— 这些是你的证据
使用读取工具查看截图，视觉验证UI显示内容
如果复现需要长时间运行的操作，请耐心等待 —— 等待工作流完成
将浏览器状态与API响应（
```
curl
```
）交叉对比，区分UI Bug和后端Bug
如果无法复现问题，请记录尝试的操作并建议可能的原因
完成后关闭浏览器：
```
agent-browser close
```