88 lines
5.7 KiB
Markdown
88 lines
5.7 KiB
Markdown
# MVP Demo Trace Acceptance Decisions
|
|
|
|
## Clarify
|
|
|
|
- Entry summary: continue the MVP toward a runnable and explainable demo by adding an `mvp-demo` profile, an end-to-end acceptance case, and a trace query API.
|
|
- Slug: `mvp-demo-trace-acceptance`
|
|
- Devflow scale: standard-light. The change adds a public read-only API and documentation, but does not alter core chat execution or persistence schemas.
|
|
|
|
## Context
|
|
|
|
- `devflow/index.md` was checked. Relevant history includes `session-storage`, `confidence-feedback`, `executor-action-memory-relevance`, and `chat-verifier-agent`.
|
|
- `mvp/archive/2026-07-09-doc-cleanup/notes/agent-engineering-decisions.md` already recommends the next phase as "可复现 MVP Demo", including `mvp-demo` profile, fixed diagnosis case, one-click request, and `GET /api/diagnosis/{sessionId}/trace`.
|
|
- `mvp/issues/archived/ISS-003-mvp-design-implementation-review.md` identifies test stability, session traceability, verifier evidence chain, upload path, and SupervisorAgent consistency as historical MVP concerns. Security cleanup was intentionally deferred by user decision at that time.
|
|
|
|
## Question Pool
|
|
|
|
| # | Dimension | Question | Mode | Status |
|
|
|---|---|---|---|---|
|
|
| Q1 | Terminology | Should "trace" mean persisted diagnosis execution evidence instead of transient frontend chat history? | evidence-driven | Resolved |
|
|
| Q2 | Boundary | Should this change modify chat execution or only expose existing persisted evidence? | evidence-driven | Resolved |
|
|
| Q3 | Acceptance | What proves the MVP flow is end-to-end enough for demo/interview use? | evidence-driven | Resolved |
|
|
| Q4 | Interface | What is the API impact level for `GET /api/diagnosis/{sessionId}/trace`? | evidence-driven | Resolved |
|
|
|
|
## Evidence-driven
|
|
|
|
| Conclusion | Evidence Source | Reported To User |
|
|
|---|---|---|
|
|
| Trace should aggregate persisted diagnosis evidence, not Redis-only chat history. | `DiagnosisSession`, `AgentStep`, `ToolInvocation` entities and repositories | Reported in progress update |
|
|
| Core chat execution does not need to change for this slice. | Existing unified chat path and SupervisorAgent commits; requested scope is demo/profile/trace/acceptance | Reported in progress update |
|
|
| End-to-end acceptance should cover start -> chat -> trace -> feedback. | `ChatController`, `FeedbackController`, traceable session id decision in MVP notes | Reported in progress update |
|
|
| Trace API is additive L3 because it is a new HTTP API for frontend/demo consumers. | sm-flow interface impact rules | Recorded in OpenSpec design |
|
|
|
|
## User-interview
|
|
|
|
| Question | User Words | Confirmation | OpenSpec Writeback |
|
|
|---|---|---|---|
|
|
| Should security/sensitive config cleanup be included? | "安全问题先不考虑"; "敏感配置先不做" | Confirmed | Non-goal |
|
|
| Should this be implemented under sm-flow? | "按照 sm-flow 的流程来实现吧" | Confirmed | This change follows sm-flow artifacts |
|
|
|
|
## Key Decisions
|
|
|
|
- Decision: Add a new trace API instead of embedding trace details in `/api/chat`.
|
|
- Reason: Chat execution and observability should stay decoupled.
|
|
- Impact: Demo can query trace after any successful chat request using the same session id.
|
|
- Risk accepted: Response shape is new and should be treated as demo-facing contract.
|
|
|
|
- Decision: Keep `mvp-demo` profile as configuration overlay, not a fully mocked standalone runtime.
|
|
- Reason: The current MVP still depends on real DB/Redis/Milvus/LLM for full chat execution; this change avoids inventing a fake runtime that hides integration behavior.
|
|
- Impact: Demo profile improves repeatability for logs/metrics, while docs remain explicit about required external services.
|
|
- Risk accepted: End-to-end acceptance may still require valid infrastructure and keys.
|
|
|
|
## Cross-Artifact Alignment
|
|
|
|
| Upstream -> Downstream | Check | Status |
|
|
|---|---|---|
|
|
| brief/prd -> proposal | Goal, scope, non-goals, and acceptance expectation are in proposal | Aligned |
|
|
| proposal -> design | Scope, constraints, and API impact are in design | Aligned |
|
|
| design -> specs/tasks | Trace DTO, controller/service, demo profile, and docs are represented | Aligned |
|
|
| specs -> tasks | Observable behavior is covered by executable tasks | Aligned |
|
|
|
|
## Architecture Audit
|
|
|
|
- Data path: HTTP trace request -> controller -> trace service -> repositories -> aggregate DTO -> `Result.success`.
|
|
- The service is read-only and does not mutate diagnosis, step, tool, or feedback state.
|
|
- No schema change is needed because all required fields already exist in `diagnosis_session`, `agent_step`, and `tool_invocation`.
|
|
- Main risk is response size for large sessions; MVP mitigates by returning previews already persisted by tools rather than raw external logs.
|
|
- The additive API is acceptable for MVP because old callers remain unaffected.
|
|
|
|
## Pre-apply Research
|
|
|
|
- Reference implementations read:
|
|
- `ChatController` for `/api` controller conventions.
|
|
- `FeedbackController` for simple API controller shape.
|
|
- `GlobalExceptionHandler` and `SessionNotFoundException` for 404 handling.
|
|
- `DiagnosisSessionRepository`, `AgentStepRepository`, `ToolInvocationRepository` for available queries.
|
|
- `DiagnosisSession`, `AgentStep`, `ToolInvocation` for fields.
|
|
- Impact analysis:
|
|
- `DiagnosisSessionRepository`: LOW, direct imports in service/controller paths.
|
|
- `AgentStepRepository`: HIGH because it participates in chat/AiOps flows. This change only consumes existing query methods and does not modify the repository.
|
|
- `ToolInvocationRepository`: LOW.
|
|
|
|
## Commit Gate
|
|
|
|
- OpenSpec proposal/design/specs/tasks exist.
|
|
- API impact: L3 additive collaboration API, documented in design and spec.
|
|
- User-confirmed non-goal: sensitive configuration cleanup remains out of scope.
|
|
- No unresolved user-interview questions remain for this slice.
|