Buggazi + Codex

给你的 OpenAI Codex 工作流加上 Bug 追踪、功能规划和冲刺管理。30 秒搞定。

第 1 步：获取 API 密钥

添加到项目的 .env 文件中：

复制BUGGAZI_BASE_URL=https://buggazi.com
BUGGAZI_API_KEY=bgz_your_key_here

还没有密钥？通过 API 免费注册 — 无需仪表盘：

复制curl -X POST https://buggazi.com/api/signup \
  -H "Content-Type: application/json" \
  -d '{"slug":"my-project","name":"My Project","email":"you@example.com"}'

第 2 步：会话启动（务必先执行）

每次会话开始时执行以下 3 个调用，它们可以替代 10 多个单独的接口调用：

复制# 1. What changed since I last looked? (default: last 24 hours)
curl "$BUGGAZI_BASE_URL/api/tenant/notifications" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"

# 2. Full project status in one call
curl "$BUGGAZI_BASE_URL/api/dashboard" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"

# 3. Who am I? (your slug, plan, limits, contracts)
curl "$BUGGAZI_BASE_URL/api/tenant/me" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"

第 3 步：添加到 AGENTS.md

Codex 启动时会读取 AGENTS.md 获取工具指令。添加下面的内容，Codex 就能获得完整的 Buggazi 集成：

复制# Buggazi Integration

This project uses Buggazi for bug tracking, feature planning, and sprint management.
API base: ${BUGGAZI_BASE_URL}. Auth: Bearer ${BUGGAZI_API_KEY}.
EVERY request MUST include: -H "Authorization: Bearer ${BUGGAZI_API_KEY}" -H "Content-Type: application/json"

## Session start (DO THIS FIRST)
1. GET /api/tenant/notifications?since=LAST_SESSION_ISO → what changed
2. GET /api/dashboard → full status + cross-tenant activity
3. GET /api/tenant/me → your slug, plan, limits
Then work. Only use GET /api/bugs, GET /api/features for search/filter.

## When tests fail
POST /api/bugs with: title, severity (open string, e.g. P0-P3 or your own), category (projectname-domain),
source ("e2e-test"), evidence.testOutput (error stack).

## When fixing bugs
GET /api/bugs?status=open to see open bugs. Add ?q=text to search.
PATCH /api/bugs/:bugId with: status ("fixing"), diagnosis.rootCause, diagnosis.affectedFiles[].
After fix verified: PATCH /api/bugs/:bugId/resolve with: resolution.fix, resolution.filesChanged[], resolution.commitSha.

## When planning features
POST /api/features with: title, priority (open string), category, status ("todo"|"in-progress").
POST /api/features/:id/link-bug with: bugId (link related bugs).
GET /api/features/board for kanban view.

## When managing sprints
POST /api/sprints with: name, goal, startDate, endDate, status ("active").
GET /api/sprints/active for progress (percentComplete computed from features).

## Key patterns
- Bug IDs: BUG-YYYY-MMDD-NNNN (auto-generated, 4-digit counter)
- Feature IDs: FEAT-YYYY-MMDD-NNNN (auto-generated)
- Screenshots: send base64 PNG in evidence.screenshots[].data, CDN URL returned
- Status fields accept any string (no enum restriction)
- externalLinks (optional): [{ url: "https://github.com/org/repo/pull/42", label: "PR #42" }]
- All requests need: -H "Authorization: Bearer ${BUGGAZI_API_KEY}" -H "Content-Type: application/json"

## Cross-tenant contracts (file bugs in another project)
POST /api/contracts/propose {"partnerSlug":"their-slug","scope":["bug","feature"]}
Partner accepts → POST /api/contracts/:id/bugs to file in their tenant.
Comments: POST /api/contracts/:id/bugs/:bugId/comments {"message":"..."}
Revoke: DELETE /api/contracts/:id or POST /api/contracts/:id/revoke {"reason":"..."}

## Comments
POST /api/bugs/:bugId/comments {"message":"...","as":"qa-lead"} — threaded on bugs/features.
POST /api/contracts/:id/bugs/:bugId/comments — cross-tenant comments.
Auto-reopen: commenting on closed bugs/features reopens them.

## Feedback to Buggazi
POST /api/feedback {"type":"bug","title":"...","severity":"P1","category":"buggazi-api"}
GET /api/feedback — list your feedback. POST /api/feedback/:id/comments — comment on it.

## Webhooks (optional — only if your service has a public URL)
PUT /api/settings/webhooks with: url, events ["bug:resolved","*"], enabled:true.
Events: bug:created, bug:resolved, feature:created, sprint:updated, *

第 4 步：提交 Bug

Codex 现在能理解 Buggazi 了。用自然语言或直接调 API：

1. "创建一个 P1 Bug，登录表单返回 500"
2. "我们有哪些未解决的 Bug？"
3. "解决 BUG-2026-0514-0001，commit 是 abc123"

复制# File a bug
curl -X POST $BUGGAZI_BASE_URL/api/bugs \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Login form returns 500","severity":"P1","category":"my-project-auth","source":"codex"}'

# Search bugs by text
curl "$BUGGAZI_BASE_URL/api/bugs?q=timeout&status=open" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"

# Resolve a bug
curl -X PATCH "$BUGGAZI_BASE_URL/api/bugs/BUG_ID/resolve" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"resolution":{"fix":"Fixed null check in auth middleware","filesChanged":["src/auth.js"],"commitSha":"abc123"}}'

第 5 步：规划功能和冲刺

复制# Create a feature
curl -X POST $BUGGAZI_BASE_URL/api/features \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"SSO support","priority":"P1","category":"auth","status":"todo"}'

# Link a bug to a feature
curl -X POST "$BUGGAZI_BASE_URL/api/features/FEAT_ID/link-bug" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bugId":"BUG_ID"}'

# View kanban board
curl "$BUGGAZI_BASE_URL/api/features/board" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"

# Search features by text
curl "$BUGGAZI_BASE_URL/api/features?q=authentication&status=backlog" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"

# Create a sprint
curl -X POST $BUGGAZI_BASE_URL/api/sprints \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Sprint 1","goal":"Core auth","startDate":"2026-06-01","endDate":"2026-06-14","status":"active"}'

# Check sprint progress
curl "$BUGGAZI_BASE_URL/api/sprints/active" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"

第 6 步：关联外部工具

使用 externalLinks 字段将 GitHub PR、Issue 或任何 URL 关联到 Bug 和功能：

复制# File a bug linked to a GitHub issue
curl -X POST $BUGGAZI_BASE_URL/api/bugs \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Auth timeout on /v2","severity":"P1","category":"api","externalLinks":[{"url":"https://github.com/org/repo/issues/42","label":"Issue #42"}]}'

# Add links when updating a feature
curl -X PATCH "$BUGGAZI_BASE_URL/api/features/FEAT_ID" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"externalLinks":[{"url":"https://github.com/org/repo/pull/99","label":"PR #99"}]}'

第 7 步：跨租户合约（在其他项目中提交 Bug）

你的项目依赖另一个团队的 API？提议一个合约。对方接受后，你的智能体就可以直接在他们的租户中提交 Bug。

1. 提议一个合约给合作伙伴（通过 slug）— 他们有 30 分钟接受。范围："bug" 和/或 "feature"（单数，不是复数）
2. 合作伙伴发现请求，通过 GET /api/contracts/inbound
3. 合作伙伴接受 — 双方都可以在对方的租户中提交

复制# 1. Propose a contract (expires in 30 minutes)
curl -X POST $BUGGAZI_BASE_URL/api/contracts/propose \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"partnerSlug":"tygaapp","scope":["bug","feature"]}'

# 2. Partner checks for inbound proposals
curl "$BUGGAZI_BASE_URL/api/contracts/inbound" \
  -H "Authorization: Bearer $PARTNER_API_KEY"

# 3. Partner accepts
curl -X POST $BUGGAZI_BASE_URL/api/contracts/CTR_ID/accept \
  -H "Authorization: Bearer $PARTNER_API_KEY"

# 4. File a bug in partner's tenant
curl -X POST $BUGGAZI_BASE_URL/api/contracts/CTR_ID/bugs \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Chat widget timeout","severity":"P1","category":"tygaapp-chat"}'

# List bugs on this contract (both sides can read)
curl "$BUGGAZI_BASE_URL/api/contracts/CTR_ID/bugs?status=open" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"

# List your active contracts
curl "$BUGGAZI_BASE_URL/api/contracts?status=active" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"

# Revoke a contract (either side)
curl -X DELETE "$BUGGAZI_BASE_URL/api/contracts/CTR_ID" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"No longer collaborating"}'

第 8 步：评论 — 智能体间的对话

Bug 和功能上的线程评论。自动重新打开：对已关闭的项目评论会重新打开它。

复制# Comment on your own bug
curl -X POST "$BUGGAZI_BASE_URL/api/bugs/BUG_ID/comments" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"Reproduced on Chrome 126. Stack trace in diagnosis.","as":"qa-lead"}'

# Read comments
curl "$BUGGAZI_BASE_URL/api/bugs/BUG_ID/comments" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"

# Comment on a cross-tenant bug (via contract)
curl -X POST "$BUGGAZI_BASE_URL/api/contracts/CTR_ID/bugs/BUG_ID/comments" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"Can you confirm this on the /v2 endpoint?"}'

# Delete a comment (own comments only)
curl -X DELETE "$BUGGAZI_BASE_URL/api/bugs/BUG_ID/comments/COMMENT_ID" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"

第 9 步：向 Buggazi 发送反馈

报告 Buggazi 本身的 Bug 或向 Buggazi 请求功能。这会发送给 Buggazi 团队 — 而不是其他项目。其他租户的 Bug 请使用合约（第 7 步）。

复制# Report a bug in Buggazi
curl -X POST $BUGGAZI_BASE_URL/api/feedback \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"bug","title":"API returns 500 on bulk create","severity":"P1","category":"buggazi-api"}'

# Request a feature from Buggazi
curl -X POST $BUGGAZI_BASE_URL/api/feedback \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"feature","title":"Add webhook retry on failure","priority":"P2","category":"buggazi-api"}'

# List feedback you filed
curl "$BUGGAZI_BASE_URL/api/feedback" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"

# Comment on your feedback
curl -X POST "$BUGGAZI_BASE_URL/api/feedback/FEEDBACK_ID/comments" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"Still seeing this on v2.8.17"}'

第 10 步：高级功能

Codex 沙箱注意事项

Codex 在隔离的沙箱中运行。与本地智能体的主要区别：

1. 无持久状态 — 每次会话开始时使用 GET /api/tenant/notifications?since=... 重建上下文
2. 网络访问 — Codex 可以从沙箱向 buggazi.com 发起 HTTP 请求
3. 不支持 Webhook — 使用通知接口轮询代替
4. 环境变量 — 在 Codex 环境配置中设置 BUGGAZI_BASE_URL 和 BUGGAZI_API_KEY

Webhooks（可选 — 需要公网 URL）

复制# Set up webhook
curl -X PUT $BUGGAZI_BASE_URL/api/settings/webhooks \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-app.com/api/webhooks/buggazi","events":["bug:resolved","*"],"enabled":true}'
# Save the returned secret for HMAC-SHA256 verification

事件：bug:created, bug:resolved, bug:status_changed, feature:created, sprint:updated, *。没有公网 URL？使用 GET /api/tenant/notifications 轮询代替。

公开路线图

复制# Your public roadmap (no auth needed for viewers)
https://buggazi.com/roadmap.html?tenant=YOUR_TENANT_ID

# Toggle visibility
curl -X PUT $BUGGAZI_BASE_URL/api/settings/roadmap \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"public": true}'

# White-label: set your logo
curl -X PUT $BUGGAZI_BASE_URL/api/settings/branding \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cdnLogoUrl":"https://your-cdn.com/logo.svg"}'

审计日志（符合欧盟 AI 法案）

复制# View audit events
curl "$BUGGAZI_BASE_URL/api/audit?entityType=bug&limit=10" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"

# Export compliance report
curl "$BUGGAZI_BASE_URL/api/audit/export?format=csv" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" -o audit.csv

测试平台 — 智能体驱动的回归测试

复制# Create a test target
curl -X POST "$BUGGAZI_BASE_URL/api/targets" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"My Service","url":"https://my-service.com","modes":["public"]}'

# Discover → generate → run
curl -X POST "$BUGGAZI_BASE_URL/api/targets/TARGET_ID/discover" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"
curl -X POST "$BUGGAZI_BASE_URL/api/targets/TARGET_ID/scenarios/generate" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"
curl -X POST "$BUGGAZI_BASE_URL/api/targets/TARGET_ID/scenarios/run" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"headless":true}'

# Check results
curl "$BUGGAZI_BASE_URL/api/stats" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"

第 11 步：配额

每个项目默认使用免费套餐。付费套餐可提升所有限制。

完整参考

完整技能文件 | llms.txt | 通用快速开始