算法可视化 | Algorithm Visualizations

一个多 Agent 驱动的算法可视化项目：网站提供交互式算法动画，也提供需求入口，让 PM、算法工程师、前端可视化专家、QA 四个 Claude Code Agent 自动完成“接需求 -> 写 PRD -> 写算法 -> 做可视化 -> 测试 -> 发 PR”的开发流程。

🔗 在线预览: https://alg.102465.xyz/

多 Agent 自动开发

自动开发链路：

/submit 表单
  -> Cloudflare Pages Function 创建 auto-dev Issue
  -> Cloudflare Pages Function dispatch Auto Dev Agents workflow
  -> scripts/start.sh 启动 Claude Code
  -> PM / algorithm / frontend / QA 四个 agent 点对点协作
  -> QA 通过后创建 auto-dev/issue-N 分支和 PR

现有动画修复链路：

动画页 Auto-Fix 表单
  -> /api/fix 创建 auto-fix Issue
  -> Cloudflare Pages Function dispatch Auto Fix Agents workflow
  -> PM 判断是否直接交给 frontend 或先交给 algorithm
  -> Agent 修改现有动画页面
  -> QA 检查交互 bug 和冗余控件
  -> QA 通过后创建 auto-fix/issue-N 分支和 PR

关键设计：

无后端服务：网站仍是 Cloudflare Pages SPA，API 只用 Pages Functions。
无中央 orchestrator agent：scripts/start.sh 是 shell supervisor，按 status JSON 启动各角色；agent 只负责产物和 handoff 状态，PR 创建由 finalizer 统一收口。
分离入口：新算法开发使用 auto-dev label 和 Auto Dev Agents workflow；现有动画修复使用 auto-fix label 和 Auto Fix Agents workflow。两个 workflow 都由 Pages Function 精确 dispatch，不再监听同一个 issues.labeled 事件。
降低 PR 冲突：workflow concurrency 只按单个 issue 去重，不再使用全局串行队列，避免 GitHub Actions 在 pending 过多时取消旧任务；新动画通过 src/animations/<slug>/meta.js 和 index.jsx 自动注册，不需要改 src/App.jsx。
三路可观测性：.auto-dev/status/issue-N.json、带 PRD / QA 报告折叠预览的 Issue sticky comment、网站 /status 页面。
实时通知：阶段切换、handoff、失败会通过飞书机器人广播。
QA 交互审计：QA 会检查无用/冗余按钮、死按钮、播放控制边界、文案行为一致性和潜在交互 bug。
Auto-Fix 入口：每个算法动画页底部都可以提交对当前动画的修复或优化建议。
继续修复入口：/status 页的 auto-fix 任务支持继续修复，会自动引用原 Issue / PR 和目标动画信息。
LLM 调用统一入口：所有模型调用都由 Claude Code 完成，workflow 通过 MiMo Anthropic 兼容网关注入 ANTHROPIC_BASE_URL。

技术栈

框架: React 18 + Vite
路由: React Router v6
样式: Tailwind CSS
动画: Framer Motion
部署: Cloudflare Pages
自动开发: GitHub Actions + Claude Code Agents + Cloudflare Pages Functions

快速开始

环境要求

Node.js >= 18
npm >= 9

安装依赖

npm install

本地开发

npm run dev

应用将在 http://localhost:5173 启动，支持热更新。

生产构建

npm run build

构建产物输出到 dist/ 目录。

预览构建产物

npm run preview

项目结构

├── public/                        # 静态资源
│   └── _redirects                 # Cloudflare Pages SPA 路由回退规则
├── functions/
│   └── api/                       # Cloudflare Pages Functions
│       ├── submit.js              # 自动开发需求提交接口
│       ├── fix.js                 # 现有动画 auto-fix 提交接口
│       └── status.js              # 自动开发状态聚合接口
├── .claude/
│   ├── agents/                    # Claude Code 子 agent 定义
│   └── context/                   # 自动开发团队共享上下文
├── .github/
│   └── workflows/
│       ├── auto-dev.yml           # auto-dev Issue 触发的新算法开发 workflow
│       └── auto-fix.yml           # auto-fix Issue 触发的现有动画修复 workflow
├── .auto-dev/
│   ├── issues/                    # 每个 Issue 的 PRD、QA 报告、决策说明
│   └── status/                    # 自动开发状态 JSON，随 PR 入仓
├── scripts/
│   ├── start.sh                   # 自动开发入口，启动 PM agent
│   ├── update-status.sh           # 更新 status JSON 和 Issue sticky comment
│   └── feishu.sh                  # 飞书状态与 handoff 通知
├── src/
│   ├── main.jsx                   # 应用入口
│   ├── App.jsx                    # 根组件（首页 + 路由配置）
│   ├── index.css                  # Tailwind 基础样式
│   ├── pages/                     # 站点页面
│   │   ├── Submit.jsx             # 自动开发需求入口
│   │   └── Status.jsx             # 自动开发状态总览
│   ├── components/ui/             # 通用 UI 组件
│   │   ├── button.jsx             # Button 组件
│   │   └── card.jsx               # Card 组件
│   └── animations/                # 算法动画页面
│       ├── pagerank_process_animation.jsx
│       └── pagerank/
│           ├── index.jsx          # 动画入口组件
│           └── meta.js            # 首页卡片与路由元数据
├── index.html                     # HTML 入口
├── vite.config.js                 # Vite 配置
├── tailwind.config.js             # Tailwind CSS 配置
├── wrangler.toml                  # Cloudflare Pages 部署配置
└── package.json

添加新的算法动画

创建动画目录

在 src/animations/ 下创建独立目录，例如：

// src/animations/dijkstra/index.jsx
export default function DijkstraAnimation() {
  return (
    <div className="min-h-screen bg-slate-50 p-6">
      <h1 className="text-3xl font-bold">Dijkstra 最短路径</h1>
      {/* 你的可视化逻辑 */}
    </div>
  )
}

添加元数据

在同一目录添加 meta.js：

// src/animations/dijkstra/meta.js
export const title = 'Dijkstra 最短路径'
export const description = '可视化贪心策略下的单源最短路径求解过程。'
export const path = '/animations/dijkstra'
export const category = 'graph'

完成

src/App.jsx 会通过 Vite import.meta.glob 自动发现动画，不需要手动改共享入口文件。首页会自动按 category 分组展示新卡片，路由和导航栏均已配置完毕。

当前支持的分类 key：
- sorting：排序算法
- search：查找算法
- graph：图算法
- dynamic：动态规划
- dataStructure：数据结构
- other：其他算法

部署教程

1. GitHub 仓库准备

确认仓库已推送到 GitHub，例如 fengwm64/AlgorithmVisualizations。
创建 Issue label：auto-dev 和 auto-fix。
在仓库设置中启用 Actions：
- Settings -> Actions -> General
- 确认允许 workflow 运行。
- Workflow permissions 选择 Read and write permissions，并允许 GitHub Actions 创建 PR。

2. 配置 GitHub Actions Secrets

进入 Settings -> Secrets and variables -> Actions -> New repository secret，添加：

Secret	说明
`ANTHROPIC_BASE_URL`	MiMo Anthropic 兼容网关地址，例如 `https://token-plan-cn.xiaomimimo.com/anthropic`
`ANTHROPIC_API_KEY`	MiMo 网关 API Key
`ANTHROPIC_MODEL`	MiMo 模型 ID，推荐填 `mimo-v2.5-pro`。注意这是接口 ID，不是展示名 `MiMo-V2.5-Pro`
`FEISHU_WEBHOOK`	飞书自定义机器人 webhook

GH_TOKEN 不需要手动配置，workflow 使用 GitHub Actions 内置 token。workflow 会把 ANTHROPIC_API_KEY 同时映射成 Claude Code 使用的 ANTHROPIC_AUTH_TOKEN。scripts/start.sh 会把 Sonnet / Opus / Haiku / Subagent 默认模型都指向同一个 MiMo 模型，并在日志中打印安全诊断信息。

3. 创建 GitHub Token 给 Cloudflare Pages Function

/api/submit 需要从网站创建 GitHub Issue，因此 Cloudflare 侧需要一个 GitHub fine-grained token：

打开 GitHub Settings -> Developer settings -> Personal access tokens -> Fine-grained tokens。
选择目标仓库 fengwm64/AlgorithmVisualizations。
Repository permissions 至少开启：
- Issues: Read and write
- Actions: Read and write
- Metadata: Read-only
生成 token，后续填到 Cloudflare Pages 环境变量 GITHUB_TOKEN。

4. 部署 Cloudflare Pages

推荐使用 Git 集成：

登录 Cloudflare Dashboard。
进入 Workers & Pages -> Pages -> Create a project。
连接 GitHub 仓库。
构建设置：
- Framework preset: Vite
- Build command: npm run build
- Build output directory: dist
- Root directory: 留空
环境变量添加：

Variable	作用
`GITHUB_TOKEN`	Pages Function 创建 Issue 使用的 fine-grained token

保存并部署。

Cloudflare Pages 会自动识别 functions/api/submit.js、functions/api/fix.js 和 functions/api/status.js：

POST /api/submit：创建带 auto-dev label 的 GitHub Issue。
POST /api/fix：为现有动画创建带 auto-fix label 的修复/优化 Issue。
GET /api/status：聚合 auto-dev 和 auto-fix 状态供 /status 页面轮询。

/api/submit 和 /api/fix 创建 Issue 后会直接调用 GitHub Actions workflow dispatch API。不要再依赖手动给 Issue 加 label 来启动 workflow；label 只用于任务分类、筛选和状态展示。

Issue 标题约定：

新算法需求：[auto-dev] <算法名称>
现有动画修复：[auto-fix] <动画标题>: <修改标题>

public/_redirects 已配置 SPA 路由回退规则，确保刷新页面不会 404；Cloudflare Pages Functions 的 /api/* 路径优先级高于 SPA fallback。

5. 验证普通站点部署

本地先跑：

npm ci
npm run build

部署后检查：

首页能打开。
/animations/pagerank 能打开。
/submit 能打开表单。
/status 能打开总览页。

6. 验证自动开发链路

访问 /submit。
提交一个小需求，例如“二分查找可视化”。
确认 GitHub 出现新 Issue，并带 auto-dev label。
确认 GitHub Actions 自动启动 Auto Dev Agents workflow。
在飞书群里确认收到 [#issue] 前缀的状态消息。
等待 workflow 结束后检查：
- Issue sticky comment 有状态表。
- Issue sticky comment 里能展开查看当前 issue 的 PRD 和 QA 报告预览。
- PR 分支名类似 auto-dev/issue-N。
- PR 中包含 .auto-dev/status/issue-N.json、.auto-dev/issues/issue-N/prd.md、.auto-dev/issues/issue-N/qa-report.md 和动画代码。
- /status 页面能看到当前阶段和 PR 链接。

7. 验证 Auto-Fix 链路

打开任意动画页面，例如 /animations/pagerank。
在页面底部 Auto-Fix 表单提交一个具体修复建议。
确认 GitHub 出现新 Issue，并带 auto-fix label。
确认 GitHub Actions 自动启动 Auto Fix Agents workflow。
workflow 结束后检查：
- PR 分支名类似 auto-fix/issue-N。
- PR 只修改目标现有动画或必要的共享文件。
- /status 页面能区分显示“新算法”和“修复优化”。
如果修复后仍未解决且修复 PR 仍处于打开状态，在 /status 对应 auto-fix 行点击“继续修复”，填写新的复现步骤；系统会创建新的 auto-fix Issue，并自动引用原 Issue / PR。新 Issue 创建后会评论原 Issue / PR；新的修复 PR 创建成功后会自动关闭被接管的旧 Issue 和旧 PR，避免误合并或继续跟踪旧入口。没有 PR、已关闭或已合并的修复不会显示“继续修复”入口，应从动画页提交新的 Auto-Fix。

8. 常见问题

如果 /api/submit 或 /api/fix 返回 GitHub 错误，先确认 Cloudflare Pages 的 GITHUB_TOKEN 是否存在，且 token 对目标仓库有 Issues: Read and write 和 Actions: Read and write 权限。
如果 Issue 创建失败并提示 label 相关错误，确认仓库中已存在 auto-dev 和 auto-fix 两个 label。
如果 workflow 没启动，确认 Cloudflare GITHUB_TOKEN 有 Actions: Read and write 权限，且 .github/workflows/auto-dev.yml / .github/workflows/auto-fix.yml 已在默认分支。
如果多个 auto-dev / auto-fix Issue 同时提交，它们可以并行运行；同一个 issue 被重复 dispatch 时会按 issue 级 concurrency 去重。若多个 PR 修改同一动画文件，最终以 GitHub PR 的合并冲突提示为准。
如果 Claude Code 报 Not supported model ***，把 GitHub Secret ANTHROPIC_MODEL 改成小写接口 ID，例如 mimo-v2.5-pro。MiMo-V2.5-Pro 是展示名，网关会拒绝。
如果 Claude Code 报 sandbox 阻止 npm 或 git，确认 workflow 已更新到使用 --permission-mode bypassPermissions，并且 QA agent 不再直接执行 git；最终 PR 应由 scripts/start.sh finalizer 创建。
如果日志里没有 Claude Code environment diagnostics 分组，说明 workflow 还没有运行到包含诊断逻辑的最新提交。
Claude Code environment diagnostics 只打印 ANTHROPIC_BASE_URL 的 protocol / host / path，以及 token 是否存在，不会打印 API Key。
如果 Claude Code 无法调用模型，确认 GitHub Secrets 中的 ANTHROPIC_BASE_URL、ANTHROPIC_API_KEY、ANTHROPIC_MODEL 已配置；Token Plan 用户的 Base URL 以订阅控制台显示为准。
如果没有飞书消息，确认 FEISHU_WEBHOOK 是 GitHub Actions Secret，而不是 Cloudflare Pages 环境变量。
如果 /status 暂时看不到 PR 状态，先看 Issue sticky comment；/status 会依次尝试 main 分支、对应 pipeline 分支（auto-dev/issue-N 或 auto-fix/issue-N）和 sticky comment。

9. Wrangler 手动部署

如需不用 Git 集成，也可以手动部署：

npm ci
npm run build
npm install -g wrangler
wrangler login
wrangler pages deploy dist

手动部署后仍需在 Cloudflare Pages 项目里配置 GITHUB_TOKEN，否则 /api/submit 和 /api/fix 无法创建 Issue。

已有可视化

算法	路径	说明
PageRank	`/animations/pagerank`	有向图上的 PageRank 迭代传播与收敛过程

贡献

欢迎提交 Issue 或 PR 来添加新的算法可视化！

License

MIT

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

算法可视化 | Algorithm Visualizations

多 Agent 自动开发

技术栈

快速开始

环境要求

安装依赖

本地开发

生产构建

预览构建产物

项目结构

添加新的算法动画

部署教程

1. GitHub 仓库准备

2. 配置 GitHub Actions Secrets

3. 创建 GitHub Token 给 Cloudflare Pages Function

4. 部署 Cloudflare Pages

5. 验证普通站点部署

6. 验证自动开发链路

7. 验证 Auto-Fix 链路

8. 常见问题

9. Wrangler 手动部署

已有可视化

贡献

License

About

Uh oh!

Contributors

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 112 Commits
.auto-dev		.auto-dev
.claude		.claude
.github/workflows		.github/workflows
functions/api		functions/api
public		public
scripts		scripts
src		src
.gitignore		.gitignore
README.md		README.md
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.js		tailwind.config.js
vite.config.js		vite.config.js
wrangler.toml		wrangler.toml

Folders and files

Latest commit

History

Repository files navigation

算法可视化 | Algorithm Visualizations

多 Agent 自动开发

技术栈

快速开始

环境要求

安装依赖

本地开发

生产构建

预览构建产物

项目结构

添加新的算法动画

部署教程

1. GitHub 仓库准备

2. 配置 GitHub Actions Secrets

3. 创建 GitHub Token 给 Cloudflare Pages Function

4. 部署 Cloudflare Pages

5. 验证普通站点部署

6. 验证自动开发链路

7. 验证 Auto-Fix 链路

8. 常见问题

9. Wrangler 手动部署

已有可视化

贡献

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Contributors

Uh oh!

Languages