初始化仓库
This commit is contained in:
@@ -0,0 +1,155 @@
|
||||
# Usage Command Implementation Plan
|
||||
|
||||
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
|
||||
|
||||
**Goal:** Add a built-in `/usage` command with a generic agent usage-reporting interface, and implement the first provider-backed version for Codex using ChatGPT OAuth quota data.
|
||||
|
||||
**Architecture:** The engine gains a new built-in command that depends only on an optional `UsageReporter` interface. Agents that implement the interface return a generic `UsageReport`; the engine formats that into text. The Codex agent reads ChatGPT OAuth credentials from `~/.codex/auth.json`, calls the `wham/usage` endpoint, and maps the response into the generic structure.
|
||||
|
||||
**Tech Stack:** Go, built-in command dispatch in `core/engine.go`, optional agent interfaces in `core/interfaces.go`, HTTP/JSON via Go standard library, table-driven tests.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Add generic usage-reporting types
|
||||
|
||||
**Files:**
|
||||
- Modify: `core/interfaces.go`
|
||||
|
||||
**Step 1: Add the failing interface usage surface**
|
||||
|
||||
Define:
|
||||
|
||||
- `UsageReporter`
|
||||
- `UsageReport`
|
||||
- `UsageBucket`
|
||||
- `UsageWindow`
|
||||
- `UsageCredits`
|
||||
|
||||
The structure should cover provider identity, plan/tier, generic allowed/limit-reached flags, one or more windows, and credits metadata.
|
||||
|
||||
**Step 2: Run targeted compile check**
|
||||
|
||||
Run: `go test ./core/...`
|
||||
Expected: compile failures in engine/tests until the command layer is wired.
|
||||
|
||||
**Step 3: Keep the types minimal**
|
||||
|
||||
Do not add provider-specific fields unless they are broadly useful.
|
||||
|
||||
**Step 4: Re-run compile check**
|
||||
|
||||
Run: `go test ./core/...`
|
||||
Expected: still failing only because `/usage` command is not yet fully integrated.
|
||||
|
||||
### Task 2: Add `/usage` built-in command and output formatter
|
||||
|
||||
**Files:**
|
||||
- Modify: `core/engine.go`
|
||||
- Modify: `core/i18n.go`
|
||||
- Test: `core/engine_test.go`
|
||||
|
||||
**Step 1: Write/extend failing tests**
|
||||
|
||||
Add tests for:
|
||||
|
||||
- `/usage` dispatch to a supporting agent
|
||||
- unsupported-agent message
|
||||
- successful output formatting with representative report data
|
||||
|
||||
**Step 2: Run the targeted tests**
|
||||
|
||||
Run: `go test ./core/... -run 'Test.*Usage|TestHandleCommand'`
|
||||
Expected: FAIL because the command is not registered yet.
|
||||
|
||||
**Step 3: Implement command plumbing**
|
||||
|
||||
Update:
|
||||
|
||||
- built-in command registration
|
||||
- command dispatch switch
|
||||
- bot command listing
|
||||
- help/i18n text
|
||||
|
||||
Add a `cmdUsage` implementation that:
|
||||
|
||||
- type-asserts `UsageReporter`
|
||||
- fetches usage with timeout
|
||||
- formats a concise text response
|
||||
|
||||
**Step 4: Run the targeted tests again**
|
||||
|
||||
Run: `go test ./core/... -run 'Test.*Usage|TestHandleCommand'`
|
||||
Expected: PASS
|
||||
|
||||
### Task 3: Implement Codex usage retrieval against ChatGPT OAuth
|
||||
|
||||
**Files:**
|
||||
- Modify: `agent/codex/codex.go`
|
||||
- Add or Modify: `agent/codex/usage.go`
|
||||
- Test: `agent/codex/usage_test.go`
|
||||
|
||||
**Step 1: Write failing tests for the mapper/fetcher**
|
||||
|
||||
Cover:
|
||||
|
||||
- successful parsing of a representative `wham/usage` payload
|
||||
- missing `auth.json`
|
||||
- missing token/account fields
|
||||
- HTTP error response
|
||||
|
||||
**Step 2: Run the targeted tests**
|
||||
|
||||
Run: `go test ./agent/codex -run 'Test.*Usage'`
|
||||
Expected: FAIL because the implementation does not exist yet.
|
||||
|
||||
**Step 3: Implement minimal production code**
|
||||
|
||||
Add:
|
||||
|
||||
- auth file path resolver
|
||||
- auth JSON loader
|
||||
- HTTP request builder
|
||||
- response DTOs
|
||||
- mapping into `core.UsageReport`
|
||||
|
||||
Prefer dependency injection for:
|
||||
|
||||
- auth file path / reader
|
||||
- HTTP client / transport
|
||||
|
||||
So tests avoid live network and real user files.
|
||||
|
||||
**Step 4: Run the targeted tests again**
|
||||
|
||||
Run: `go test ./agent/codex -run 'Test.*Usage'`
|
||||
Expected: PASS
|
||||
|
||||
### Task 4: End-to-end verification and cleanup
|
||||
|
||||
**Files:**
|
||||
- Modify: `README.md`
|
||||
- Modify: `README.zh-CN.md`
|
||||
- Modify: `CHANGELOG.md`
|
||||
|
||||
**Step 1: Document the new command**
|
||||
|
||||
Add `/usage` to command lists and a short explanation that support depends on the current agent.
|
||||
|
||||
**Step 2: Run focused test suites**
|
||||
|
||||
Run: `go test ./core/... ./agent/codex`
|
||||
Expected: PASS
|
||||
|
||||
**Step 3: Run broader verification**
|
||||
|
||||
Run: `go test ./...`
|
||||
Expected: PASS, or identify unrelated pre-existing failures clearly.
|
||||
|
||||
**Step 4: Commit**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
git add core/interfaces.go core/engine.go core/i18n.go core/engine_test.go agent/codex/codex.go agent/codex/usage.go agent/codex/usage_test.go README.md README.zh-CN.md CHANGELOG.md docs/plans/2026-03-12-usage-design.md docs/plans/2026-03-12-usage.md
|
||||
git commit -m "feat: add usage command for codex oauth"
|
||||
```
|
||||
Reference in New Issue
Block a user