mzaxd/agent-park
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
cae5686d2d0011ef37e24c72c8abdf48c1c1f95e
agent-park/specs/001-ai-project-navigator/spec.md
T
mzaxdandClaude c5a8de8cf0 chore: 初始化 Agent Park v2 项目 
- 更新项目章程，从模板更新为完整版本，包含 TypeScript 严格模式、组件优先架构和 TDD 原则
- 添加项目配置文件（.claude/settings.json、.gitignore、CLAUDE.md）
- 添加完整的 specs 目录，包含需求、契约和文档

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-12-25 14:21:35 +08:00

11 KiB
Raw Blame History

功能规范: Agent Park - AI项目导航网站

功能分支: 001-ai-project-navigator 创建时间: 2025-12-25 状态: 草稿 输入: 用户描述: "构建一个名为agent-park的全网ai项目导航网站，用户可以搜索和浏览各种领域 查看相关的ai项目 项目详情页需要包括项目的大致情况介绍 和相关网站来源的跳转链接（官网，github等）关于数据来源 需要定期从n8n的相关流程中获取(前期用假数据先把网站搭建起来）我希望风格是 anthropic claude的风格"

Clarifications

Session 2025-12-25

  • Q: n8n数据更新频率如何配置？ → A: 后台维护一个n8n流程列表，每个流程可以获取不同类型的数据，可以自定义每个定时任务的执行周期
  • Q: 搜索功能范围和排序方式？ → A: 全域搜索（名称+描述+标签）+ 按相关性和收录时间排序
  • Q: 初始假数据规模？ → A: 20-30个项目，最小化前期工作量，快速验证核心功能
  • Q: 项目分类体系如何设计？ → A: 采用标签系统而非固定分类，按标签和相关性进行灵活分组，适应AI领域快速变化的特点
  • Q: 支持哪些外部链接类型？ → A: 官网、GitHub、HuggingFace、论文链接四种类型，覆盖主流AI项目场景
  • Q: n8n数据集成方式如何设计？ → A: n8n执行完成后主动推送数据到本系统的webhook接口，由本系统定义数据字段结构，定时任务由n8n管理
  • Q: 技术栈如何选择？ → A: Next.js全栈方案，使用React组件开发，利用API Routes构建webhook接口
  • Q: webhook接口如何进行身份认证？ → A: 使用API Key认证，n8n在请求头中携带预共享密钥进行身份验证
  • Q: 项目数据的必填字段有哪些？ → A: name、description、tags、至少一个link为必填字段，确保项目信息的完整性和可用性
  • Q: 日志和监控策略如何设计？ → A: 使用简单控制台日志，区分不同日志级别，前期不实现告警机制
  • Q: 当webhook接口接收大量项目数据更新时，前端如何展示数据刷新进度给用户？ → A: 不展示更新状态，下次访问时自然生效
  • Q: 当webhook接收到的项目数据中部分项目验证失败（如缺少必填字段），但其他项目有效时，系统应如何处理？ → A: 部分成功模式，有效的入库，失败记录日志

用户场景与测试 (必填)

用户故事 1 - 浏览和搜索AI项目 (优先级: P1)

用户访问网站后，可以通过浏览不同分类或使用搜索功能，快速找到感兴趣的AI项目。

优先级原因: 这是网站的核心功能，用户需要能够发现和查找AI项目，否则整个网站失去价值。

独立测试: 可以通过浏览预设的分类列表，或使用搜索框输入关键词，验证项目列表能够正确显示和过滤。

验收场景:

  1. 给定 用户访问网站首页，当 查看页面时，那么 应看到热门标签云和精选项目展示
  2. 给定 用户在搜索框输入关键词，当 提交搜索时，那么 应显示包含该关键词的相关项目
  3. 给定 用户点击某个标签，当 选择标签时，那么 应只显示带该标签的项目
  4. 给定 用户组合多个标签筛选，当 应用时，那么 应显示同时满足所有标签条件的项目
  5. 给定 项目列表很长，当 用户滚动时，那么 应支持分页或无限滚动加载更多项目

用户故事 2 - 查看项目详细信息 (优先级: P1)

用户点击某个项目后，可以查看该项目的详细信息，包括项目介绍、官方网站链接、GitHub仓库等。

优先级原因: 用户需要了解项目的具体信息才能决定是否进一步探索，详情页是信息获取的关键环节。

独立测试: 点击任意项目卡片，验证详情页正确显示项目描述、外部链接等信息。

验收场景:

  1. 给定 用户点击某个项目卡片，当 进入详情页时，那么 应显示项目名称、描述、相关标签
  2. 给定 用户在项目详情页，当 查看时，那么 应看到官网、GitHub、HuggingFace、论文链接等外部来源的跳转链接
  3. 给定 用户点击外部链接，当 访问时，那么 应在新标签页中打开对应的官方网站或代码仓库
  4. 给定 某个项目缺少部分信息，当 显示时，那么 应合理隐藏或提示"暂无信息"

用户故事 3 - 响应式设计体验 (优先级: P2)

用户在不同设备（桌面、平板、手机）上访问网站，都能获得良好的浏览体验。

优先级原因: 现代用户使用多种设备访问网站，响应式设计确保所有用户都能正常使用。

独立测试: 在不同屏幕尺寸下访问网站，验证布局自动调整且所有功能可用。

验收场景:

  1. 给定 用户使用手机访问，当 查看首页时，那么 导航和内容应适配竖屏布局
  2. 给定 用户使用平板横屏访问，当 浏览时，那么 项目卡片应合理排列且易于点击
  3. 给定 用户使用桌面大屏访问，当 浏览时，那么 应充分利用屏幕空间展示更多内容

用户故事 4 - 数据更新和管理 (优先级: P3)

n8n工作流程在执行完成后主动推送最新的AI项目数据到本系统的webhook接口，更新网站内容。

优先级原因: 这是后台功能，对用户体验影响较小，可以后期实现。前期使用静态数据即可满足需求。

独立测试: 通过模拟n8n推送请求，验证新数据能够正确更新到网站。

验收场景:

  1. 给定 n8n工作流程执行完成，当 主动推送数据到webhook接口时，那么 数据更新在后台静默执行，用户下次访问时自然看到最新内容
  2. 给定 某些项目不再维护，当 n8n推送更新数据时，那么 这些项目应被标记或移除
  3. 给定 webhook接收数据失败，当 发生错误时，那么 应返回明确错误信息给n8n并记录日志，现有数据不受影响
  4. 给定 n8n推送的数据格式不符合要求，当 验证时，那么 应拒绝请求并返回具体错误信息
  5. 给定 请求缺少有效的API Key，当 验证时，那么 应返回401未授权错误并记录日志
  6. 给定 推送的数据中部分项目验证失败，当 处理时，那么 有效项目正常入库，失败项目记录详细错误信息

边界情况

  • 当搜索无结果时，应显示友好提示并建议用户尝试其他关键词
  • 当外部链接失效（404）时，应在页面上标注"链接可能失效"但仍保留入口
  • 当数据加载缓慢时，应显示加载动画或骨架屏提升体验
  • 当用户输入特殊字符搜索时，应正确处理并防止XSS攻击
  • 当同时有大量用户访问时，网站应保持稳定响应

需求 (必填)

功能需求

  • FR-001: 网站首页必须展示热门标签云和精选项目列表
  • FR-002: 用户必须能够通过搜索框输入关键词查找相关项目，搜索范围覆盖项目名称、描述和标签，结果按相关性优先、收录时间次之排序
  • FR-003: 用户必须能够通过点击标签筛选项目，支持多标签组合筛选
  • FR-004: 每个项目必须显示至少包含：项目名称、简短描述、相关标签
  • FR-005: 项目详情页必须显示项目的完整介绍和外部来源链接（官网、GitHub、HuggingFace、论文链接四种类型）
  • FR-006: 外部链接必须在新标签页中打开，确保用户不会离开导航网站
  • FR-007: 网站必须支持响应式设计，适配桌面、平板、手机等设备
  • FR-008: 网站设计风格应参考Anthropic Claude官网，采用简洁、现代、优雅的视觉风格
  • FR-009: 前期使用静态假数据构建网站，提供webhook接口接收n8n推送的数据
  • FR-010: 系统必须提供webhook API接口，接收n8n工作流程推送的项目数据
  • FR-011: webhook接口必须验证推送数据的格式和必填字段，拒绝不符合规范的数据请求
  • FR-012: webhook接口必须支持部分成功模式，当批量数据中部分项目验证失败时，有效项目正常入库，失败项目记录详细错误信息
  • FR-013: webhook接口必须使用API Key进行身份认证，n8n在请求头中携带预共享密钥
  • FR-014: 系统必须实现控制台日志记录，区分info、warn、error级别，记录webhook请求和错误信息

关键实体 (如果功能涉及数据则包含)

  • AI项目 (Project): 代表一个AI工具或应用
    • 必填字段: name（项目名称）、description（详细描述）、tags（标签集合）、links（至少一个外部链接）
    • 可选字段: status（项目状态：活跃/停更，默认活跃）、createdAt（收录时间，默认当前时间）、source（数据来源标识）
  • 标签 (Tag): 代表AI项目的特征标记，采用灵活的标签系统而非固定分类，如"图像生成"、"代码助手"、"数据分析"等，一个项目可以有多个标签
  • 外部链接 (ExternalLink): 代表项目的来源网站，包含链接类型（官网/GitHub/HuggingFace/论文）和对应的URL

成功标准 (必填)

可衡量的结果

  • SC-001: 用户可以在5秒内找到目标AI项目（通过搜索或分类浏览）
  • SC-002: 95%的用户能够成功从项目详情页跳转到外部来源网站
  • SC-003: 网站首屏加载时间在2秒以内，确保良好的用户体验
  • SC-004: 网站在主流浏览器（Chrome、Firefox、Safari、Edge）的最新两个版本中正常显示和运行
  • SC-005: 移动设备上的用户能够单手完成项目搜索和查看的完整流程
  • SC-006: 网站能够支持至少100个并发用户访问而不出现性能明显下降
  • SC-007: 用户对网站视觉设计的满意度评分达到4分以上（5分制）

假设 (必填)

技术假设

  • 使用Next.js全栈框架，React组件开发，API Routes构建webhook接口
  • 前期数据存储为JSON格式或静态文件，后期可迁移到数据库
  • 本系统提供webhook API接口接收n8n推送的项目数据
  • n8n按照本系统定义的数据字段结构推送JSON格式数据
  • 网站部署在Vercel或支持Next.js的服务器上

内容假设

  • 前期使用20-30个假项目数据进行开发和测试，覆盖主要标签类型
  • AI项目数据由人工审核和整理，确保质量和准确性
  • 项目标签参考主流AI社区的标记方式（如HuggingFace、Papers with Code），保持灵活性
  • 外部链接的维护责任在于对应项目方，网站仅提供导航服务

用户假设

  • 用户具备基本的网页浏览和搜索技能
  • 用户主要使用中文进行搜索和浏览
  • 用户希望在发现有趣项目后能够快速访问官方来源获取更多信息

约束

  • 网站设计应避免过度使用动画效果，保持简洁快速
  • 不需要用户注册登录功能，所有内容公开可访问
  • 前期不包含用户评论、评分等社交功能，专注于导航展示

范围外 (明确不包含的内容)

  • 用户账户系统和个性化推荐
  • 项目评论、评分、收藏等社交功能
  • 用户提交新项目的功能（全部由管理员从n8n导入）
  • 多语言支持（专注于中文用户体验）
  • 实时通知或更新提醒功能
  • 付费内容或高级会员功能
Reference in New Issue View Git Blame Copy Permalink