Agent-Insight社区贡献指南如何参与这个开源Agent观测平台的建设【免费下载链接】agent-insightThe agent-insight is a precise and easy-to-use Skill Engineering platform that provides automatic generation and optimization of Skills, multi-dimensional comparison, and in-depth analysis capabilities.项目地址: https://gitcode.com/openeuler/agent-insight前往项目官网免费下载https://ar.openeuler.org/ar/Agent-Insight是一个面向Agent全生命周期的开源工程平台专注于Agent观测、评测和Skill优化。作为openEuler社区的明星项目它让每一个AI Agent都可被观测、可被评估、可自我进化。如果你对AI Agent开发、可观测性工程或开源协作感兴趣这份终极指南将带你快速上手成为Agent-Insight社区的重要贡献者为什么选择Agent-Insight在AI Agent快速发展的今天开发者面临三大核心痛点Agent运行过程如同黑盒难以定位问题、Skill质量参差不齐缺乏评测标准、Agent经验无法沉淀复用。Agent-Insight正是为解决这些问题而生它提供框架无关的观测能力支持OpenCode、Claude Code、Hermes、OpenClaw等多种框架接入。Agent-Insight的核心能力包括Agent观测与自进化- 从数据采集到智能决策的完整闭环️Skill开发与自进化- 全生命周期管理能力智能A/B测评- 结构化工作流支持一键对比智能诊断- 基于链路自动定位异常根因框架无关- 基于OpenTelemetry标准协议完全自托管- 数据完全自主可控准备工作环境配置与代码获取第一步签署CLA协议在开始贡献代码前每位贡献者都需要签署openEuler社区CLA协议。这是参与openEuler社区项目的基本要求确保你的贡献符合开源协议规范。第二步克隆仓库git clone https://gitcode.com/openeuler/agent-insight.git cd agent-insight第三步配置开发环境Agent-Insight基于现代Web技术栈构建Node.js≥ 20.0.0TypeScriptNext.js 16(App Router)React 19Tailwind CSSPrismaSQLite/OpenGauss安装依赖npm install第四步了解项目结构Agent-Insight采用标准的Next.js项目结构但有几个特殊目录需要特别关注目录用途说明src/app/前端页面与API路由遵循Next.js App Router规范src/components/可复用UI组件使用统一的设计系统src/lib/核心业务逻辑引擎、存储、工具函数等prisma/数据库Schema与迁移使用Prisma ORMskills/内置Skill定义每个Skill一个子目录含SKILL.mddocs/design/需求设计文档按三阶段组织分析→设计→计划docs/developer-guide/开发者指南架构、模块、API契约等docs/user-guide/用户操作指南面向终端用户的使用文档贡献流程从零到PR的完整路径1. 理解分支策略Agent-Insight采用双remote协作模式fork remote- 你的个人fork仓库team remote- 团队合并管理仓gyctl/witty-skill-insight重要提示在开始前务必运行git remote -v确认你的remote配置2. 标准贡献流程遵循以下步骤确保你的贡献能被顺利接纳从team remote同步最新代码git fetch upstream # 假设upstream是team remote git checkout -b feature/your-feature-name upstream/new_src开发与本地测试启动开发服务器bash scripts/develop_start.sh运行测试npm run test代码检查npm run lint提交代码使用Conventional Commits规范git add . git commit -m feat: 添加新的框架适配器 git commit -m fix: 修复Skill生成中的空指针异常 git commit -m docs: 更新用户指南中的安装步骤推送到你的fork仓库git push -u origin feature/your-feature-name创建Pull Request访问gitcode上的个人fork仓库点击新建合并请求关键步骤将目标分支改为gyctl/witty-skill-insight的new_src填写清晰的PR描述说明改动内容和测试情况3. 代码质量要求Agent-Insight对代码质量有严格标准UI设计规范使用统一的设计令牌不要创建局部色板优先使用src/components/ui中的组件页面布局使用PageContainer组件使用sonnertoast替代window.alertSkill命名约定对外API使用name而非id路由格式/skill-opt/[name]/[version]API路径/api/skills/:name/...数据模型约定Skill重命名会导致URL失效这是设计选择多Agent执行树通过parentExecutionId/rootExecutionId关联JSON字段在存储边界处解析/序列化不同类型的贡献方式1. 文档贡献新手友好文档是开源项目的重要组成部分。Agent-Insight有两套文档系统用户指南(docs/user-guide/) - 面向终端用户开发者指南(docs/developer-guide/) - 面向开发者文档更新原则任何影响用户感知或架构理解的改动都必须同步更新对应文档。2. Bug修复如果你发现了bug可以按照以下流程修复在issue中确认问题或创建新issue编写最小复现用例修复并添加测试提交PR并关联issue3. 功能开发对于新功能开发Agent-Insight有严格的流程要求需要设计文档的情况涉及Prisma schema变更新增API路由重大架构调整设计文档需要放在docs/design/topic/目录按三阶段组织phase1-requirements-analysis.md- 需求分析phase2-requirements-design.md- 需求设计phase3-development-plan.md- 开发计划需要先对齐思路的情况实现路径有多种合理选择涉及跨多个模块的改动需要引入新的抽象层感觉这件事不止改几行代码4. 框架适配器开发Agent-Insight的核心优势是框架无关性。如果你要为新的Agent框架添加支持在src/lib/ingest/下创建适配器实现FrameworkAdapter接口在注册表中注册适配器提供安装脚本如果需要示例结构src/lib/ingest/ ├── adapters/ │ └── your-framework-adapter.ts └── your-framework-parser.ts5. 评测器扩展Agent-Insight支持自定义评测器使用LlmEvaluatorConfig或CodeEvaluatorConfig建模通过src/server/user_evaluators_storage.ts持久化集成到评测引擎中开发最佳实践1. 前端开发规范样式使用CSS变量和设计令牌不要硬编码颜色值组件优先复用现有组件不要重复造轮子状态管理使用React Context和自定义hooksAPI调用使用统一的apiFetch函数2. 后端开发规范API路由在src/app/api/group/name/route.ts中创建鉴权先调用resolveUser(request)验证权限错误处理使用统一的错误响应格式日志记录使用结构化的日志格式3. 数据库操作规范不使用裸SQL所有持久化都通过Prisma进行事务处理复杂操作使用事务保证一致性迁移管理Schema变更需要创建迁移文件4. 测试策略Agent-Insight采用分层测试策略单元测试核心逻辑和工具函数集成测试API端点和数据库操作E2E测试关键用户流程运行测试# 运行所有测试 npm run test # 运行Skill相关测试 npm run test:skill # 运行特定测试文件 npm test -- test/path/to/test.test.ts常见贡献场景详解场景一修复UI样式问题步骤确认问题是否与设计系统相关检查src/app/globals.css中的设计令牌使用正确的CSS变量进行修复提供亮色和暗色两种模式的截图场景二添加新的LLM提供商步骤扩展src/lib/llm-providers.ts中的注册表实现对应的Provider接口在模型注册页面添加支持更新相关文档场景三优化Skill生成算法步骤分析现有算法的瓶颈在src/lib/engine/skill-generation/下实现优化添加性能对比测试更新Skill生成的相关文档场景四改进错误处理步骤识别需要改进的错误场景在src/lib/utils/error-handling.ts中添加处理逻辑提供有意义的错误消息确保错误不会泄露敏感信息协作与沟通指南1. Issue处理流程报告bug提供复现步骤、环境信息、期望行为与实际行为功能请求描述使用场景、预期效果、可能的实现方案问题讨论先搜索现有issue避免重复2. PR审查要点提交PR时请确保✅ 代码通过所有测试✅ 遵循项目代码风格✅ 更新了相关文档✅ 提供了必要的测试用例✅ 没有引入安全漏洞✅ UI改动包含亮色和暗色截图3. 沟通渠道邮件intelligenceopeneuler.orgIssue跟踪在gitcode仓库提交issue代码审查通过PR评论进行技术讨论高级贡献参与架构演进1. 理解核心架构Agent-Insight采用以领域引擎为核心的分层架构边缘/交付层 (pages, api, clients) ↓ 领域引擎层 (engine/*) ↓ 存储抽象层 (DatabaseAdapter) ↓ 数据存储层 (SQLite/OpenGauss)2. 关键扩展点新增API端点在src/app/api/下创建route handler新增页面在src/app/(main)/下创建page组件新增引擎能力在src/lib/engine/area/下实现新增存储后端实现DatabaseAdapter接口3. 性能优化建议避免在循环中执行数据库查询使用适当的索引优化查询性能实现分页加载大数据集缓存频繁访问的数据故障排除与调试1. 常见开发问题问题开发服务器启动失败解决检查端口3000是否被占用或尝试bash scripts/restart_dev.sh问题数据库迁移失败解决运行npx prisma migrate reset重置数据库问题TypeScript类型错误解决检查tsconfig.json配置确保导入路径正确2. 调试技巧使用console.log进行快速调试利用浏览器的开发者工具检查网络请求查看服务端日志npx agent-insight logs使用Prisma Studio查看数据库npx prisma studio3. 性能分析使用Chrome DevTools的Performance面板监控API响应时间分析数据库查询性能成为核心贡献者1. 成长路径新手期从文档和bug修复开始熟悉期参与小型功能开发贡献期独立负责模块开发核心期参与架构设计和代码审查2. 学习资源官方文档docs/目录下的完整指南代码示例查看现有实现学习最佳实践设计文档docs/design/中的需求分析社区讨论通过issue参与技术讨论3. 获得认可持续的高质量贡献积极参与代码审查帮助其他贡献者解决问题推动项目技术演进总结与下一步行动Agent-Insight作为openEuler社区的重要项目为AI Agent开发者提供了强大的观测和优化能力。参与这个项目不仅能提升你的技术能力还能为开源社区做出实实在在的贡献。立即行动签署CLA协议Fork仓库并设置开发环境从good first issue开始加入社区讨论记住每一次贡献无论大小都在推动AI Agent技术的发展。Agent-Insight期待你的加入让我们一起构建更好的AI Agent生态系统温馨提示在提交任何重大改动前请务必阅读AGENTS.md中的完整协作规范确保你的贡献符合项目要求。如果有任何疑问不要犹豫直接在issue中提问社区成员会很乐意帮助你。【免费下载链接】agent-insightThe agent-insight is a precise and easy-to-use Skill Engineering platform that provides automatic generation and optimization of Skills, multi-dimensional comparison, and in-depth analysis capabilities.项目地址: https://gitcode.com/openeuler/agent-insight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考