spikes

---

这是什么？

Spikes 是一款面向 AI 辅助开发的反馈工具。它让评审者可以直接在网页上针对特定元素留下反馈——无需截图，无需说“那边的那个按钮”，也不会丢失上下文。

点击任意元素。评分。评论。Spikes 会捕获精确的 CSS 选择器、边界框和页面上下文。你的 AI Agent 会收到可立即采取行动的结构化 JSON。

无需账户。无需构建步骤。适用于 file://、localhost 和任何地方。

---

快速开始

1. 安装 CLI

curl -fsSL https://spikes.sh/install.sh | sh
# Or: cargo install spikes

2. 初始化项目

spikes init                     # Defaults to hosted spikes.sh
# spikes init --self-host       # Opt out — scaffold a self-hosted config instead

默认情况下，spikes init 会创建 .spikes/config.toml，其中包含指向 https://spikes.sh 的 [remote] 配置段。传入 --self-host（或在提示时输入 s）即可跳过托管默认设置。

3. 将 widget 添加到 HTML

spikes inject ./mockups/        # Injects widget script tag (uses configured endpoint)
spikes serve                    # http://localhost:3847

4. 收集并使用反馈

spikes list                     # See all feedback
spikes list --json              # Feed to your agent
spikes list --rating no         # Find problems
spikes hotspots                 # Elements with most feedback
spikes resolve <id>             # Mark items done

---

CLI 命令

命令	说明
spikes init	创建包含配置的 .spikes/ 目录（默认使用托管服务；传入 --self-host 可选择退出）
spikes list	列出反馈（--json、--page、--reviewer、--rating、--unresolved）
spikes show <id>	显示单条 spike 的详情
spikes export	导出为 JSON/CSV/JSONL/Cursor/Claude 上下文
spikes hotspots	列出反馈最多的元素
spikes reviewers	列出所有评审者
spikes inject <dir>	在 HTML 文件中添加/移除 widget（--endpoint <url> 可覆盖已配置的端点）
spikes serve	本地开发服务（--port、--marked、--cors-allow-origin）
spikes mcp serve	启动用于集成 AI Agent 的 MCP 服务
spikes pull/push/sync	与远程端点同步
spikes share <dir>	上传到 spikes.sh，即刻分享
spikes login/logout/whoami	身份验证管理
spikes upgrade/billing	通过 Stripe 订阅 Pro 级别
spikes deploy cloudflare	搭建自托管 Worker + D1

所有命令都支持用于脚本编写的 --json。请参阅完整 CLI 参考。

查看托管项目的 spikes：

托管仪表板 https://spikes.sh/dashboard 会列出你拥有的所有项目，并允许你查看各条 spike 的详情（可按页面、评分和已解决状态筛选，也可直接切换 resolved）。直接在浏览器中登录：点击 登录，打开验证页面，然后通过发送到你邮箱的魔法链接进行确认——无需使用 CLI。

你也可以使用持有者令牌（spikes login 获取的 $SPIKES_TOKEN）直接调用 JSON API：

# GET /me/projects
# List all projects you own (with spike_count + last_activity)
curl -H "Authorization: Bearer $SPIKES_TOKEN" \
  https://spikes.sh/me/projects

# GET /me/projects/:key/spikes
# List spikes for one of your projects (paginated, filterable: page, per_page,
# filter_page, filter_rating, filter_resolved)
curl -H "Authorization: Bearer $SPIKES_TOKEN" \
  "https://spikes.sh/me/projects/my-project/spikes?page=1&per_page=50"

# PATCH /me/projects/:key/spikes/:id
# Toggle the `resolved` flag on one spike
curl -X PATCH -H "Authorization: Bearer $SPIKES_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"resolved": true}' \
  https://spikes.sh/me/projects/my-project/spikes/<spike_id>

# POST /projects
# Create a new project (user bearer only)
curl -X POST -H "Authorization: Bearer $SPIKES_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key": "my-project", "allowed_origins": ["https://example.com"]}' \
  https://spikes.sh/projects

# Single-line variant (copy-paste friendly)
curl -H "Authorization: Bearer $SPIKES_TOKEN" https://spikes.sh/me/projects

所有 /me/* 端点都限定于用户范围：你只能查看自己拥有的项目和 spikes。跨租户请求会返回 404 PROJECT_NOT_FOUND（防枚举）。

安全说明： /me/* 端点或 POST /projects 不接受 API 密钥（sk_spikes_*）和管理员 SPIKES_TOKEN——这些请求必须使用通过 spikes login 获取的用户持有者令牌。POST /spikes 收集端点会强制执行每个项目的来源允许列表和速率限制；被拒绝的 widget 请求会在 widget 按钮上显示一个小的红色 #spikes-error-dot 指示标记（404 / 403 / 429）。

---

AI Agent 集成

Spikes 原生支持 Agent。你的 AI 编码助手无需离开工作流，即可读取、编写和管理反馈。

npx spikes-mcp            # Zero-install MCP server — just works
# or: spikes mcp serve    # If you have the CLI installed

MCP 服务 — 16 个工具

spikes mcp serve 会启动一个 Model Context Protocol 服务，提供 16 个工具：

工具	用途
get_spikes	使用筛选条件（页面、评分、未解决、url_prefix、since）列出反馈
get_element_feedback	获取特定 CSS 选择器对应的反馈
get_hotspots	查找反馈最多的元素
submit_spike	以编程方式创建反馈
resolve_spike	将反馈标记为已处理
delete_spike	删除一条 spike
create_share	上传文件并获取可分享的 URL
list_shares	查看当前有效的分享
get_usage	查看使用统计、限额和支出
reply_to_spike	在页面上回复审核者，可选择设置状态和版本（托管版）
set_spike_status	将 spike 标记为待处理、已处理或不予处理（托管版）
list_versions / add_version	声明审核版本并查看每个版本的数量（托管版）
list_questions / ask_question / get_question_answers	向审核者提问并查看答案（托管版）

支持 stdio 和 HTTP 传输方式，以及 本地 和 远程 数据模式：

spikes mcp serve                              # stdio, local JSONL
spikes mcp serve --remote                     # stdio, hosted API
spikes mcp serve --transport http --port 3848 # HTTP for sandboxed agents

API 密钥

Agent 拥有各自的身份。无需邮箱、魔法链接或人工操作：

spikes auth create-key --name "my-agent"   # → sk_spikes_...
spikes auth list-keys                       # See all keys
spikes auth revoke-key <key_id>            # Revoke

密钥支持读取、写入和完全访问权限范围，并可选设置预算上限。

Agent 分级计费

按使用量计费，适合 Agent 级别的使用。按 spike 付费，而非按席位付费：

spikes usage    # See current spend and limits

达到上限时，预算限制会返回 429 BUDGET_EXCEEDED——Agent 可以在消耗预算前先检查。

上下文导出

导出经过结构化、针对 Agent 使用优化的 Markdown：

spikes export --format cursor-context > cursor-feedback.md
spikes export --format claude-context > claude-feedback.md

发现

• llms.txt — 全部 9 个 MCP 工具、参数和 Agent 快速入门
• agents.md — 面向 Agent 的机器可读首页
• Smithery — 已列入 MCP 服务注册表
• spikes mcp install — 为 Claude Desktop / Cursor 生成配置

完整详情：llms.txt · agents.md

---

GitHub Action

根据反馈质量控制 CI。当未解决的负面反馈超过阈值时，spikes-action 会使构建失败。

name: CI
on: [push, pull_request]

jobs:
  feedback-gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: bierlingm/spikes/[email protected]
        with:
          threshold: 0           # Fail if any blocking spikes
          ignore-paths: ""     # Optional: pages to ignore
          require-resolution: false

完整文档请参阅 action/README.md。

---

Widget 属性

简单设置 — 只需添加项目密钥，即可开始收集反馈：

<script src="https://spikes.sh/spikes.js" data-project="my-app"></script>

设置 data-project 后，反馈会自动同步到 https://spikes.sh/spikes。除非采用可自托管部署，否则无需配置端点。

完整配置 — 所有可用属性：

<script src="https://spikes.sh/spikes.js"
  data-project="my-app"
  data-position="bottom-right"
  data-color="#e74c3c"
  data-theme="dark"
  data-reviewer="Pat"
  data-collect-email="true"
  data-admin="true">
</script>

自托管 — 指向你自己的后端：

<script src="/spikes.js"
  data-project="my-app"
  data-endpoint="https://my-worker.workers.dev/spikes">
</script>

属性	说明	默认值
data-project	按项目密钥对反馈分组	location.hostname
data-position	按钮所在角落：bottom-right、bottom-left、top-right、top-left	bottom-right
data-color	强调色（任意 CSS 颜色）	#e74c3c
data-theme	模态框主题：dark 或 light	dark
data-reviewer	预设审核者姓名	（提示用户输入）
data-endpoint	用于多审核者同步的后端 URL。可选 — 设置 data-project 时默认为 https://spikes.sh/spikes。	https://spikes.sh/spikes（设置 data-project 时），/spikes（本地开发）
data-collect-email	在提示词中显示邮箱字段	false
data-admin	启用审核模式功能	false
data-offset-x/y	按钮与边缘的偏移量	—

完整文档请参阅 Widget 属性参考。

---

架构

Spikes 由三个可协同工作或独立运行的组件组成：

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   CLI       │────▶│   Widget    │◄────│   Worker    │
│  (Rust)     │     │  (Vanilla   │     │ (Cloudflare │
│             │     │    JS)      │     │  + D1)      │
└─────────────┘     └─────────────┘     └─────────────┘
     │                                            │
     │          spikes.sh (hosted)                │
     └────────────────────────────────────────────┘

CLI — 用于本地开发、管理和部署 spike 的 Rust 二进制程序。将 spike 存储在 ~/.local/share/spikes/ 中。

Widget — 经过 gzip 压缩后仅 14KB 的原生 JavaScript。用于捕获元素选择器、边界框、评分和评论。通过 localStorage 离线运行。

Worker — 可选的 Cloudflare Worker + D1 后端，用于多评审者同步、分享和托管部署。位于 spikes-hosted/ 中。

---

开发

CLI

cd cli
cargo build --release
cargo test              # 160+ tests
cargo run -- --help

Widget

cd widget
# Edit src/spikes.js
# Test by running: spikes serve from the project root

Widget 回归测试

用于捕获静默数据丢失类问题的 CI 测试套件（例如，Widget 在不允许的来源上加载后无法同步，且未显示错误）：

cd tests/widget
npm install
npx playwright install chromium    # one-time
npm test                           # 23 tests: marker checks + happy/reverse/boundary specs (<60s)

也已接入本地 agent-ci：

npx agent-ci run --workflow workflows-local/widget.yml

Worker

Worker 后端位于私有的 spikes-hosted 仓库中。测试方法如下：

cd ../spikes-hosted/worker
npm test              # Worker test suite (vitest)
npx wrangler dev

---

自托管

想要使用自己的后端？只需一条命令：

spikes deploy cloudflare    # Creates spikes-worker/ directory
cd spikes-worker && npx wrangler deploy

有关 D1 数据库、身份验证和 Stripe 账单集成的完整设置说明，请参阅自托管指南。

Share 还是 Deploy Cloudflare：该如何选择？

如果你想立即分享而无需任何设置，请使用 spikes share — 文件会上传到 spikes.sh，并通过我们的基础设施提供服务。适合快速评审、收集客户反馈，或不想管理后端的情况。

如果你需要数据隔离（反馈保存在自己的 Cloudflare 账户中）、自定义域名，或想全面掌控基础设施，请使用 spikes deploy cloudflare。自托管需要 Cloudflare 账户和一次性部署设置。

---

近期重大更新

• 安全性：PBKDF2 密码哈希、路径遍历修复、XSS 防护
• 身份验证：魔法链接身份验证（无需记忆密码）
• 账单：集成 Stripe，支持 Pro 套餐
• 测试：CLI 测试套件（Rust）+ Worker 测试套件（位于 ../spikes-hosted/worker）
• 架构：模块化 Worker，职责划分清晰
• CI/CD：自动化测试和部署流水线

---

详细文档

• CLI 参考 — 完整的命令文档
• Widget 属性 — 所有配置选项
• 自托管指南 — 部署自己的后端
• API 参考 — REST API 文档
• 回滚指南 — 紧急操作流程

---

为什么选择 Spikes

零门槛	只需一个 script 标签，无需注册，无需构建
随处可用	file://、localhost、任何域名
精准	针对元素提供反馈，并包含准确的 CSS 选择器
原生适配 Agent	全面使用 JSON、支持管道、CLI 可查询
使用自己的基础设施	可自托管，也可使用托管服务 — 由你选择
轻巧	Widget 经过 gzip 压缩后仅 14KB
隐私保护	不跟踪，你的数据归你所有

---

定价

	免费版	Pro
价格	永久 $0	按能力付费
分享数量	5	无限制
每次分享的 spike 数量	1,000	无限制
Widget + CLI	完整功能	完整功能
自托管	是	是
密码保护	—	是
Webhooks	—	是
移除徽章	—	是

---