specstory-project-stats

用途

SpecStory Project Stats 用于从 SpecStory Cloud 获取项目的统计数据，展示贡献者数量、会话活动以及其他项目指标。当用户说“get project stats”“show SpecStory stats”“project statistics”“how many sessions”等时运行。

主要能力

该技能可以获取并返回以下项目统计信息：

会话数据：总会话数、最近 30 天会话数、最近 7 天会话数
贡献者数据：贡献者总数、最近 30 天活跃贡献者数
活动数据：首次会话日期、最近一次会话日期、平均每周会话数

输出为 JSON 格式，并会整理成友好的可读摘要展示给用户。

使用方式

斜杠命令

用户输入 /specstory-project-stats 即可获取当前项目的统计数据，无需参数。

直接运行脚本

# Fetch stats for current project
node skills/specstory-project-stats/scripts/get-stats.js

# With custom API endpoint (for development)
SPECSTORY_API_URL=http://localhost:5173 node skills/specstory-project-stats/scripts/get-stats.js

项目 ID 解析顺序

脚本按以下顺序确定项目 ID：

.specstory/.project.json —— 使用 git_id 或 workspace_id 字段
Git remote —— 从 origin remote URL 提取仓库名
文件夹名 —— 回退到当前目录名

环境变量

变量	默认值	说明
SPECSTORY_API_URL	https://cloud.specstory.com	API 端点

输出示例

脚本输出的 JSON 包含项目统计信息：

{
  "project_id": "specstoryai/agent-skills",
  "sessions": {
    "total": 156,
    "last_30_days": 47,
    "last_7_days": 12
  },
  "contributors": {
    "total": 5,
    "active_last_30_days": 3
  },
  "activity": {
    "first_session": "2025-10-15",
    "last_session": "2026-01-28",
    "avg_sessions_per_week": 8.2
  }
}

适用场景

查看项目在 SpecStory Cloud 上的会话活跃度和趋势
了解贡献者参与情况
快速获取项目统计摘要，用于团队回顾或汇报

前提条件

项目必须已同步到 SpecStory Cloud
必须提供 Node.js 才能运行脚本

限制与错误处理

统计数据来自 SpecStory Cloud，而非本地历史记录
项目必须有已同步的会话，才能显示有意义的统计数据
基础统计 API 为公开接口，无需认证

错误处理：

错误	含义	操作
404	项目未找到	项目需要先同步到 SpecStory Cloud
401	未授权	API 端点可能需要认证
网络错误	无法访问 API	检查网络连接

遇到 404 时，可参考以下步骤：确认已安装 SpecStory，运行 specstory sync 将本地会话推送到云端，然后重试命令。帮助文档见 https://docs.specstory.com