agentscope-ai / agentscope-ai/QwenPaw

[Feature]: Add a unified backend diagnostics API for the future Console debug page

Abierto
#2,383 1 comentario 0 reacciones 0 asignados Ver en GitHub
enhancement
Lenguaje dominante
Python
Estrellas
34.9k
Forks
3.1k
Merge medio
1 d 15 h
PR fusionados (30 d)
225

Descripción

## Summary

This issue proposes a unified backend diagnostics API as the first step for Task 10 (“add a debug page to the Console for easier error tracking”) in #2291. Since the frontend is currently under a large refactor, I would like to align on a backend-first MVP before implementing any Console UI.

## Component(s) Affected

- [x] Core / Backend (app, agents, config, providers, utils, local_models)
- [ ] Console (frontend web UI)
- [ ] Channels (DingTalk, Feishu, QQ, Discord, iMessage, etc.)
- [ ] Skills
- [x] CLI
- [x] Tests
- [ ] Documentation (website)
- [ ] CI/CD
- [ ] Scripts / Deploy

## Problem / Motivation

After reviewing the latest codebase, CoPaw already has several useful diagnostic pieces, but they are currently scattered and not exposed as a stable backend contract for the Console:

- `/api/version` already exists
- `/api/auth/status` already exists
- `/api/agent/local-whisper-status` already exists
- daemon helpers already provide `status`, `version`, and `logs`
- runner exceptions already write structured debug dump files

However, there is still no unified backend diagnostics API that a future Console debug page can consume.

Current gaps I noticed:

1. The existing daemon diagnostic helpers are text/Markdown-oriented, not JSON API-oriented.
2. Query error dumps are written to temp files, but there is no backend index or “recent errors” endpoint.
3. The log file is currently global (`WORKING_DIR/copaw.log`), so the diagnostics scope (global vs agent-scoped) is not yet explicit.
4. The frontend already has some diagnostic-related API expectations such as `healthCheck()` in `console/src/api/modules/agent.ts`, but the backend contract is incomplete / inconsistent.

Because of this, implementing the UI first would likely create extra coupling and refactor conflicts. A backend-first design seems safer and easier to review.

## Proposed Solution

Add a small unified backend diagnostics API for the future Console debug page.

### Proposed MVP

1. `GET /api/debug/summary`
Returns a compact JSON summary such as:
- CoPaw version
- auth enabled / has users
- working directory
- log file path
- active agent or selected diagnostics scope
- basic runtime attachment info (for example whether memory manager / manager is available)
- recent captured error count

2. `GET /api/debug/logs?lines=200`
Returns the last N lines of the current log file.
This should reuse the existing log tail logic from daemon helpers.

3. `GET /api/debug/errors`
Returns recent structured error summaries, for example:
- id
- timestamp
- exception type
- message
- session_id
- channel
- debug_dump_path

4. Optional: `GET /api/debug/errors/{id}`
Returns detailed error information for drill-down support later.

### Implementation direction

- Reuse existing diagnostic logic instead of creating a separate subsystem from scratch.
- Refactor reusable parts of `daemon_commands` into JSON-oriented helpers where appropriate.
- Introduce a lightweight in-memory ring buffer for recent error summaries.
- Continue writing structured dump files on runner exceptions, but also register them in the in-memory diagnostics store.
- Keep the Console UI out of scope for this first step.

### Non-goals for the first iteration

- No full debug page UI yet
- No live log streaming yet
- No persistent diagnostics database
- No broad refactor of all existing logging paths
- No attempt to solve all channel / MCP / config diagnostics in one PR

## Additional Context

Relevant existing code paths:

- version endpoint:
- `src/copaw/app/_app.py`
- auth status endpoint:
- `src/copaw/app/routers/auth.py`
- agent / transcription diagnostics:
- `src/copaw/app/routers/agent.py`
- daemon diagnostics helpers:
- `src/copaw/app/runner/daemon_commands.py`
- structured query error dump:
- `src/copaw/app/runner/runner.py`
- `src/copaw/app/runner/query_error_dump.py`
- frontend diagnostic API expectations:
- `console/src/api/modules/agent.ts`

Questions I would like to confirm before implementation:

1. Should this diagnostics API be global-instance level, agent-scoped, or support both?
2. Is `summary + logs + recent errors` a good backend MVP?
3. Is an in-memory recent error store acceptable for the first version?
4. Should debug dump files remain in temp storage, or be moved under the working directory for easier inspection?
5. For the first iteration, should the API focus only on runner/query errors, or should channel / MCP / config errors also be included?

Note: I intentionally scope this proposal to diagnostics rather than full tracing. Tracing is valuable, but it likely needs a separate design for trace IDs, event granularity, storage, and cross-component propagation. For this MVP, I suggest focusing on logs, structured recent errors, and backend status summaries first, while keeping the API extensible for tracing later.

## Willing to Contribute

- [x] I am willing to open a PR for this feature (after discussion).

Guía de contribución

Abrir la guía de contribución

Evaluación

Este issue todavía no se ha evaluado.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.