如何参与 AgentScope Studio 开源贡献？从 Issue 认领到 Conventional Commits 的开发者完整指南

发布时间：2026/11/5 6:44:01

人工智能
AI 应用
可观测性
链路追踪
数据可视化
AI 评测
前端
后端

【免费下载链接】agentscope-studio

A development-oriented visualization toolkit

项目地址：https://gitcode.com/gh_mirrors/ag/agentscope-studio

AgentScope Studio 是一个面向 AgentScope 智能体开发的本地可视化开发工具，提供项目管理、运行实时可视化、基于 OpenTelemetry 的追踪和内置 Copilot（Friday）等能力。想为它做开源贡献？这份指南将带你从认领 Issue、一键搭建本地开发环境，到遵循Conventional Commits提交规范与项目代码风格，完整走通从新手到贡献者的每一步。

为什么值得为 AgentScope Studio 贡献？

AgentScope Studio 于 2025 年 8 月正式开源（Apache-2.0 许可证），正处于快速演进阶段，社区非常欢迎任何形态的贡献：修 bug、加功能、补文档、优化体验。项目采用 TypeScript + React 前端、Node.js + Express 后端、SQLite 数据库的轻量架构，上手门槛低、模块边界清晰，非常适合新手切入。

官方贡献指南（contributing.md）明确写道："无论是修复 bug、添加新功能、改进文档，还是分享想法，你的贡献都能让 AgentScope Studio 变得更好。"

贡献前必做：先认领 Issue 再动手

社区协作的核心是避免重复劳动。在写第一行代码之前，请先确认任务来源：

优先认领已有 Issue
- 查看项目 Roadmap 中带roadmap标签的开放 Issues；
- 若某条 Issue 尚未被分配，请在该 Issue 下评论留言表达认领意愿，便于维护者协调排期。
没有合适 Issue？那就新建一个
- 描述你建议的功能或修复方案；
- 维护者会及时回复、给出反馈与方向，帮助你把想法落成可执行的任务。

💡小贴士：重大改动请务必先开 Issue 讨论，再提交 PR。"突然冒出的大型 PR" 是贡献清单里最典型的反面案例。

一键搭建本地开发环境：3 步跑起来

本地跑通项目是你提交第一个 PR 的前提。整个流程只需 3 步。

第 1 步：准备前置依赖

依赖	版本要求	说明
Node.js	≥ 20.0.0	使用 nvm 时可`nvm use`切换
npm	≥ 10.0.0	包管理器
Docker	可选	用于容器化部署调试

版本检查：

node --version # 应显示 v20.x.x 或更高 npm --version # 应显示 10.x.x 或更高

第 2 步：克隆仓库并安装依赖

git clone https://gitcode.com/gh_mirrors/ag/agentscope-studio cd agentscope-studio npm install

第 3 步：以开发模式启动

npm run dev

该命令会并行拉起前端与后端（对应 package.json 中的dev:client与dev:server），默认监听3000端口、OTel gRPC 端口4317（配置项见 server.ts）。浏览器访问http://localhost:3000即可看到界面：

需要容器化调试时，可参考 docker/README.md 中提供的docker-compose方案。

熟悉仓库结构：packages 目录快速地图

AgentScope Studio 是一个npm workspaces 单体仓库，核心代码全部位于packages/下，理解这张"地图"能帮你快速定位要改哪个文件。

目录	职责	技术栈
`packages/client/`	前端 UI	React + TypeScript + Vite + TailwindCSS
`packages/server/`	后端服务（API、数据库、追踪接收器）	Node.js + Express + tRPC + TypeORM + SQLite
`packages/shared/`	前后端共享的常量、类型、工具函数	TypeScript
`packages/app/friday/`	内置 Copilot「Friday」的 Python 智能体实现	Python
`docs/`	基于 VitePress 的教程文档（中/英双版本）	Markdown

关键子目录速查（更完整说明见 contributing.md）：

前端：components/ 负责 UI、context/ 负责状态管理与数据获取、pages/ 负责路由页面。
后端：dao/ 是数据库访问层、models/ 是 ORM 模型、trpc/ 是 tRPC 路由、otel/ 是 OpenTelemetry gRPC 接收器。
共享层：config/ 定义前后端共用的端口、常量与默认配置。

🧭经验法则：想改 UI → 找client/src/pages+client/src/components；想加接口 → 找server/src/trpc；想改数据库 → 找server/src/dao+server/src/models+server/src/migrations。

前端与后端贡献规范：写代码前必读

1. 提交前必跑格式化命令

项目使用Prettier + ESLint统一代码风格，提交前必须执行：

npm run format

该命令会自动格式化所有 TS/JS/TSX 文件并修复 ESLint 报告的问题（脚本定义见 package.json）。跳过这一步的 PR 大概率会被打回。

2. 前端架构原则：关注点分离

前端（React/TypeScript）贡献时必须遵守两条硬性原则：

状态管理与 UI 组件分离：数据获取和状态逻辑放到 context/ 中的 Context Provider，UI 组件只负责渲染与交互。例如 ProjectRoomContext.tsx 就是典型的状态 Provider。
样式一律使用 Tailwind CSS 工具类：避免内联style和组件级单独 CSS 文件。

3. 后端与数据库

新增字段或表结构变更时，记得同步更新 models/ 并在 migrations/ 下新增迁移脚本，保证 SQLite 数据库（database.ts）平滑升级。

Conventional Commits 提交规范速查表

项目严格遵循 Conventional Commits 规范，提交信息格式为<type>(<scope>): <subject>。规范化的提交历史能让 CHANGELOG 自动生成更整洁。

Type	用途	示例
`feat`	新增功能	`feat(trpc): add run export endpoint`
`fix`	修复 bug	`fix(tracing): resolve token count overflow`
`docs`	仅文档变更	`docs(readme): update installation steps`
`style`	不影响逻辑的样式/格式调整	`style(client): prettier reformat`
`refactor`	既不加功能也不修 bug 的重构	`refactor(context): extract socket helper`
`perf`	性能优化	`perf(trace): batch span writes`
`test`	补充或修复测试	`test(dao): add Reply DAO unit tests`
`chore`	构建、CI 与辅助工具变更	`chore(ci): bump node to 20`

scope建议填写受影响的模块名，例如trpc、tracing、client、server、friday、docs。

该做 vs 不该做：贡献清单

✅ 该做	❌ 不该做
从小任务切入，逐步熟悉代码库	突然提交大型、无预沟通的 PR
重大改动先在 Issue 讨论	忽略 CI 失败
为改动补充测试	一个 PR 混杂多种关注点
为复杂逻辑补充文档	破坏现有 API 兼容性
使用规范的 Conventional Commit 信息	引入不必要的第三方依赖
对社区保持尊重，不懂就问	绕过 Issue 直接提交

卡住了？快速求助渠道

💬 想聊设计思路？开一条Discussion或直接在对应 Issue 下评论。
🐛 发现 bug？按模板新建Issue，附上复现步骤与日志。
📖 文档类问题？可查阅 docs/tutorial/zh_CN/tutorial/overview.md 与 Friday 文档了解项目全貌。

结语

从认领一条good first issue、跑通本地npm run dev、到以feat:/fix:规范提交第一条 commit——你的第一步，就是 AgentScope Studio 社区欢迎你加入的开始。保持小步快跑、先沟通后动手，你会发现自己很快就能在这个可视化开发工具的核心代码里留下名字。🚀