feat(graph): add diagnosis routing skeleton
This commit is contained in:
zhuyongxin
@@ -0,0 +1,154 @@
|
||||
# chat-diagnosis-stategraph-routing-skeleton Specification
|
||||
|
||||
## Purpose
|
||||
提供未接生产入口的 Diagnosis StateGraph 状态、config-aware Node ports、确定性条件边、有限重试、编排事件和 trace 构造能力，并以 Fake Node 测试锁定 Graph Core 1.1.2.0 的实际行为。
|
||||
## Requirements
|
||||
### Requirement: Diagnosis Graph skeleton SHALL compile against the locked Graph API
|
||||
|
||||
The system SHALL provide an internal Diagnosis StateGraph skeleton using Graph Core 1.1.2.0 config-aware node actions, conditional edges, explicit key strategies, and a recursion limit of 32. The skeleton SHALL NOT be wired to the current production Chat path.
|
||||
|
||||
#### Scenario: Skeleton is compiled
|
||||
|
||||
- **WHEN** valid node action ports are supplied
|
||||
- **THEN** the Graph SHALL compile with all frozen nodes and conditional edges
|
||||
- **AND** `orchestration_events` SHALL use Append semantics while all other state uses Replace semantics
|
||||
- **AND** the compiled Graph SHALL enforce recursion limit 32
|
||||
|
||||
#### Scenario: Run config is supplied
|
||||
|
||||
- **WHEN** a Fake Node Graph is invoked with a `RunnableConfig.threadId`
|
||||
- **THEN** config-aware node ports SHALL receive that config
|
||||
- **AND** the final state SHALL remain scoped to that invocation
|
||||
|
||||
#### Scenario: Production path is inspected
|
||||
|
||||
- **WHEN** stage 1 is accepted
|
||||
- **THEN** ChatService, real Agents, Gatekeeper service, database, and Trace API SHALL NOT invoke the new skeleton
|
||||
|
||||
### Requirement: Planner routing SHALL allow one technical retry per Planner stage
|
||||
|
||||
The skeleton SHALL route Planner COMPLETED to Executor. INVALID_OUTPUT and RETRYABLE_FAILED SHALL self-retry only while `planner_retry_count=0`; NON_RETRYABLE_FAILED, unknown status, or a second technical failure SHALL route to Fallback.
|
||||
|
||||
#### Scenario: Planner first technical failure
|
||||
|
||||
- **WHEN** Planner first returns INVALID_OUTPUT or RETRYABLE_FAILED
|
||||
- **THEN** only Planner SHALL run again
|
||||
- **AND** the re-entered Planner state SHALL have `planner_retry_count=1`
|
||||
|
||||
#### Scenario: Planner retry is exhausted
|
||||
|
||||
- **WHEN** Planner returns a technical failure after retry count reaches 1
|
||||
- **THEN** the Graph SHALL route to Fallback
|
||||
- **AND** Executor SHALL NOT run
|
||||
|
||||
#### Scenario: Planner fails non-retryably
|
||||
|
||||
- **WHEN** Planner returns NON_RETRYABLE_FAILED or an unknown status
|
||||
- **THEN** the Graph SHALL route directly to Fallback
|
||||
|
||||
### Requirement: Executor and Gatekeeper routing SHALL fail closed
|
||||
|
||||
Executor SHALL route only COMPLETED output to Gatekeeper and SHALL never retry. Gatekeeper SHALL route PASS and LOW_CONFID with verified bindings to Verified Input; REJECT, unknown status, or LOW_CONFID with zero bindings SHALL route to Fallback.
|
||||
|
||||
#### Scenario: Executor completes legal output
|
||||
|
||||
- **WHEN** Executor returns COMPLETED, including a legal no-evidence output or legal output after tool errors
|
||||
- **THEN** Gatekeeper SHALL run exactly once
|
||||
|
||||
#### Scenario: Executor cannot complete contract
|
||||
|
||||
- **WHEN** Executor returns INVALID_OUTPUT, TOOL_BLOCKED, FAILED, or unknown status
|
||||
- **THEN** the Graph SHALL route directly to Fallback
|
||||
- **AND** Gatekeeper and Verifier SHALL NOT run
|
||||
|
||||
#### Scenario: Gatekeeper permits verification
|
||||
|
||||
- **WHEN** Gatekeeper returns PASS or LOW_CONFID with `verified_binding_count>0`
|
||||
- **THEN** Verified Input SHALL run before Verifier
|
||||
|
||||
#### Scenario: Gatekeeper blocks verification
|
||||
|
||||
- **WHEN** Gatekeeper returns REJECT, unknown status, or LOW_CONFID with zero verified bindings
|
||||
- **THEN** the Graph SHALL route to Fallback
|
||||
- **AND** Verifier SHALL NOT run
|
||||
|
||||
### Requirement: Verifier routing SHALL separate technical retry from evidence retry
|
||||
|
||||
Verifier INVALID_OUTPUT and RETRYABLE_FAILED SHALL self-retry once with the same verified input. COMPLETED PASS or REJECT SHALL route to Composer. COMPLETED LOW_CONFID SHALL route to one Evidence Retry only when all frozen guards are true; otherwise it SHALL route to Composer. Other outcomes SHALL fail closed.
|
||||
|
||||
#### Scenario: Verifier first technical failure
|
||||
|
||||
- **WHEN** Verifier first returns INVALID_OUTPUT or RETRYABLE_FAILED
|
||||
- **THEN** only Verifier SHALL run again
|
||||
- **AND** Gatekeeper, Executor, and tools SHALL NOT rerun
|
||||
|
||||
#### Scenario: Verifier retry is exhausted
|
||||
|
||||
- **WHEN** Verifier returns a technical failure after `verifier_retry_count=1`
|
||||
- **THEN** the Graph SHALL route to Fallback
|
||||
|
||||
#### Scenario: Verifier verdict reaches Composer
|
||||
|
||||
- **WHEN** Verifier completes with effective PASS or REJECT
|
||||
- **THEN** Composer SHALL run
|
||||
|
||||
#### Scenario: LOW_CONFID qualifies for evidence retry
|
||||
|
||||
- **WHEN** Verifier completes LOW_CONFID with ceiling PASS, valid no_evidence or indirect_support facts, and `evidence_retry_count=0`
|
||||
- **THEN** Evidence Retry SHALL run once and return to a new Planner stage
|
||||
- **AND** `planner_retry_count` SHALL reset to 0
|
||||
- **AND** `evidence_retry_count` SHALL become 1
|
||||
|
||||
#### Scenario: LOW_CONFID does not qualify for evidence retry
|
||||
|
||||
- **WHEN** ceiling is LOW_CONFID, facts contain no valid gap, or evidence retry count is already 1
|
||||
- **THEN** Composer SHALL run without another Planner cycle
|
||||
|
||||
### Requirement: Composer routing SHALL allow one technical retry and then terminate safely
|
||||
|
||||
Composer COMPLETED SHALL terminate at END. INVALID_OUTPUT and RETRYABLE_FAILED SHALL self-retry once; NON_RETRYABLE_FAILED, unknown status, or a second technical failure SHALL route to Fallback and then END.
|
||||
|
||||
#### Scenario: Composer first technical failure
|
||||
|
||||
- **WHEN** Composer first returns INVALID_OUTPUT or RETRYABLE_FAILED
|
||||
- **THEN** only Composer SHALL run again
|
||||
- **AND** Verifier and preceding nodes SHALL NOT rerun
|
||||
|
||||
#### Scenario: Composer retry is exhausted
|
||||
|
||||
- **WHEN** Composer fails technically after `composer_retry_count=1`
|
||||
- **THEN** Fallback SHALL run exactly once
|
||||
- **AND** the Graph SHALL terminate
|
||||
|
||||
#### Scenario: Composer succeeds
|
||||
|
||||
- **WHEN** Composer returns COMPLETED
|
||||
- **THEN** the Graph SHALL terminate without invoking Fallback
|
||||
|
||||
### Requirement: Orchestration events SHALL produce an exact bounded trace
|
||||
|
||||
Each node attempt SHALL append one terminal orchestration event. The trace builder SHALL derive transitions from adjacent events, final node and termination reason from the last event, degraded state from Fallback termination, and evidence retry count from state.
|
||||
|
||||
#### Scenario: Normal path trace is built
|
||||
|
||||
- **WHEN** Fake nodes execute Planner, Executor, Gatekeeper, Verified Input, Verifier, and Composer
|
||||
- **THEN** events and transitions SHALL preserve that exact order
|
||||
- **AND** the trace SHALL terminate at Composer without degradation
|
||||
|
||||
#### Scenario: Fallback path trace is built
|
||||
|
||||
- **WHEN** a route terminates through Fallback
|
||||
- **THEN** the trace final node SHALL be Fallback
|
||||
- **AND** `degraded` SHALL be true
|
||||
- **AND** its termination reason SHALL come from the Fallback event
|
||||
|
||||
#### Scenario: Trace input is invalid
|
||||
|
||||
- **WHEN** no events exist or an event has blank node, outcome, reason code, or attempt below 1
|
||||
- **THEN** trace construction SHALL fail explicitly rather than fabricate a path
|
||||
|
||||
#### Scenario: Event payload is inspected
|
||||
|
||||
- **WHEN** orchestration events and trace maps are produced
|
||||
- **THEN** they SHALL contain only routing metadata
|
||||
- **AND** they SHALL NOT contain Prompt, model reasoning, tool output, or Graph State snapshots
|
||||
Reference in New Issue
Block a user