熱門文章
近期留言
-
站長阿川：非常神奇
網站的 ui for agent 是這樣製作的
---
> 很好 可以投稿＆審核了
> 新增一組 api endpoint
> 讓我的 hermes agent 可以上網找活動、直接投稿 如何呢？
> 問題一、
> 要如何讓 hermes 知道 正確的 api format 比方說欄位、以及可接受內容
> 問題二、
> 如何避免重複投稿 是否提供一個 list all events / registrations 即可
> 對了 找到圖片的話 hermes 會需要 upload to imgur 我也提供一個 api 來支援嗎
> 給我一組 prompt 讓 coding agent 做完上述內容吧
---
# Implement Hermes Agent Submission API
Add a small authenticated API for an external Hermes AI agent to discover the API contract, inspect existing records, and submit new events and registrations for human review.
The existing website already supports normal user submissions and admin review. Reuse the existing domain models, validation rules, enums/constants, image handling, and review workflow wherever possible. Do not create a parallel submission system unless necessary.
Before implementing, inspect the existing:
- `events` / `event_dates`
- `registrations`
- submission flow
- admin review flow
- validation / FormRequest classes
- sport and region constants/enums
- image storage logic
- API documentation setup
- authentication conventions
Keep the implementation simple.
## Goal
Hermes should be able to:
1. Read the API specification and understand valid fields and enum values.
2. Fetch existing events and registrations to avoid duplicate submissions.
3. Submit a new event.
4. Submit a new registration.
5. Provide a remote source image URL when submitting.
6. Have the backend download and store that image using the application's existing image infrastructure.
7. Never publish content directly. All Hermes submissions must enter the existing human review workflow.
---
# Authentication
Create a simple Bearer-token authentication mechanism suitable for one trusted internal agent.
Use environment/configuration rather than storing the token in source code.
For example:
```env
HERMES_API_TOKEN=
```
Expose it through the appropriate config file.
All `/api/agent/*` endpoints must require this authentication.
Return standard JSON `401` responses for invalid authentication.
Do not introduce OAuth, Sanctum, API client management, or other unnecessary infrastructure unless the project already uses it and reuse is clearly simpler.
---
# API endpoints
Implement:
```text
GET /api/agent/events
POST /api/agent/events
GET /api/agent/registrations
POST /api/agent/registrations
```
Also make sure the existing OpenAPI/API documentation exposes these endpoints and their schemas in machine-readable form.
If the project already exposes something like:
```text
/api/openapi.json
```
reuse it.
Otherwise expose the generated OpenAPI JSON in the simplest way consistent with the project's existing API documentation tooling.
---
# GET existing records
These endpoints exist primarily so Hermes can detect previously submitted content before creating another submission.
```text
GET /api/agent/events
GET /api/agent/registrations
```
Return only fields useful for duplicate detection. Do not return the complete models.
Registration should return the equivalent relevant fields.
Include both published records and records currently waiting for review so Hermes does not repeatedly submit something that is already pending.
Past records do not need to be returned if the existing application intentionally hides/removes them from active data.
For the current MVP, returning all relevant records is acceptable. Do not implement pagination, vector search, fuzzy search, embeddings, or a dedicated duplicate-check endpoint yet.
---
# Duplicate protection
Hermes will perform semantic duplicate detection itself by inspecting the GET responses.
The server should additionally implement a cheap deterministic safety check.
At minimum, if the normalized `source_url` already belongs to an existing or pending record of the same domain type, reject the submission with:
```http
409 Conflict
```
Example response:
```json
{
"message": "Possible duplicate submission.",
"existing": {
"public_id": "01K...",
"title": "2026 台灣柔術公開賽"
}
}
```
Normalize URLs reasonably before comparison where appropriate, for example obvious trailing-slash differences.
Do NOT build sophisticated fuzzy duplicate detection.
---
# POST event
Implement:
```text
POST /api/agent/events
```
The request schema should mirror the existing event submission/domain model.
Do not blindly use this example as the authoritative schema.
Inspect the existing Event model, user submission form, migrations, constants/enums, and validation rules first, then make the API consistent with the real application.
The OpenAPI schema must explicitly document:
- required fields
- nullable fields
- types
- date format
- valid `type` values
- valid `sports` values
- valid `region` values
- valid `admission_type` values
- examples where useful
Hermes should be able to construct a valid request from OpenAPI alone.
---
# POST registration
Implement:
```text
POST /api/agent/registrations
```
Follow the same principles.
Inspect the existing Registration model/schema and reuse its actual fields and validation.
Do not force Event-specific fields into Registration if they do not belong there.
---
# Image ingestion
Do NOT expose Imgur or any storage-provider credentials to Hermes.
Do NOT require Hermes to upload the image separately.
The POST endpoints should accept:
```text
thumbnail_source_url
```
This is the public URL of the original image discovered by Hermes.
The backend should:
```text
thumbnail_source_url
↓
download image
↓
validate response / MIME / file size
↓
store using existing application image infrastructure
↓
save resulting thumbnail_path
```
If the project currently uses Imgur, keep Imgur behind this backend abstraction.
Hermes should never need to know whether images are stored on Imgur, S3, R2, local storage, etc.
Reuse existing image upload/storage services if available.
Add reasonable safeguards against bad remote image input:
- only `http` / `https`
- valid image MIME types
- reasonable maximum download size
- request timeout
- reject failed downloads
- do not trust the filename extension
Also protect the remote fetch against obvious SSRF risks: do not allow localhost, loopback, private/internal network addresses, link-local addresses, or other non-public destinations.
Avoid building a large generic media subsystem.
---
# Review workflow
This is important:
**Hermes must never be able to publish an Event or Registration.**
Agent-created records must enter the same pending/draft state used by normal submissions and appear in the existing admin review interface.
The API must NOT accept fields such as:
```text
status
published_at
approved_at
```
from Hermes.
Status must be determined server-side.
Reuse the existing submission/review workflow rather than creating an agent-specific review UI.
---
# Agent attribution
If the existing submission architecture has an appropriate place to identify the submitter/source, record that the submission came from Hermes.
Prefer the smallest clean change consistent with the current architecture.
For example conceptually:
```text
submitted_by_type = agent
submitted_by = hermes
```
Do not add these exact columns blindly if the current schema has a better mechanism.
The admin should ideally be able to tell that a pending submission came from Hermes.
我看 agent 提交的 就讓 user_id null 即可吧
---
# Validation responses
Make validation errors useful to an AI client.
Use standard `422` JSON responses and expose allowed enum values where practical.
Example:
```json
{
"message": "Validation failed.",
"errors": {
"sports.0": [
"Invalid sport. Allowed values: boxing, mma, muay_thai, kickboxing, bjj, wrestling."
]
}
}
```
Do not maintain a second hard-coded list solely for the API. Reuse the application's authoritative constants/enums.
---
# OpenAPI
The OpenAPI document is the authoritative machine-readable contract for Hermes.
Make sure it accurately documents:
```text
GET /api/agent/events
POST /api/agent/events
GET /api/agent/registrations
POST /api/agent/registrations
```
including Bearer authentication.
A fresh agent reading the OpenAPI document should be able to determine:
- which endpoints exist
- authentication requirements
- request fields
- required vs optional fields
- valid enum values
- expected response formats
- validation errors
- duplicate response (`409`)
Avoid maintaining a separate manually duplicated Hermes schema if the existing OpenAPI tooling can derive it from application validation/schema definitions.
---
# Tests
Add focused feature tests covering at least:
```text
unauthenticated request → 401
authenticated GET events → 200
authenticated GET registrations → 200
valid agent event submission → pending/draft record created
valid agent registration submission → pending/draft record created
agent cannot control publication status
duplicate source_url → 409
invalid sport/region/etc → 422
remote image successfully downloaded and stored
invalid remote image → 422 or appropriate client error
private/local thumbnail URL rejected
Hermes-created submission appears in the same review workflow as normal submissions
```
Mock external HTTP/image requests in tests.
---
# Keep the architecture small
This is an MVP for one trusted Hermes agent.
Do NOT add:
- embeddings
- vector databases
- fuzzy duplicate services
- queues unless already needed by existing image handling
- OAuth
- complex API client management
- separate Hermes database tables
- separate agent review system
- separate image upload endpoint
- agent publishing capability
Prefer existing application abstractions and conventions.
After implementation:
1. Run relevant tests.
2. Run formatting/static analysis used by this repository.
3. Show the final endpoint list.
4. Show an example authenticated Event POST request.
5. Show an example Registration POST request.
6. Show where Hermes can retrieve the machine-readable OpenAPI specification.
7. Briefly list files changed and any migrations/config/env variables added.
-
站長阿川：results:
https://www.reddit.com/r/newsokunomoral/comments/1wd2xua/
https://www.reddit.com/r/lowlevelaware/comments/1wd319c/
-
站長阿川：我一人為主
少數情況會跟朋友一起接案 很偶爾 看專案
-
站長阿川：我太久沒碰新潮工具了...
-
站長阿川：首頁排序 ux 我之後有空再研究改善