@renxqoo/renx-code 0.0.4 → 0.0.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +82 -51
- package/bin/renx.cjs +16 -0
- package/package.json +2 -45
- package/src/agent/runtime/runtime.context-usage.test.ts +4 -5
- package/src/agent/runtime/runtime.error-handling.test.ts +4 -5
- package/src/agent/runtime/runtime.test.ts +7 -4
- package/src/agent/runtime/runtime.ts +3 -9
- package/src/agent/runtime/runtime.usage-forwarding.test.ts +4 -5
- package/src/agent/runtime/source-modules.test.ts +16 -35
- package/src/agent/runtime/source-modules.ts +17 -0
- package/vendor/agent-root/src/agent/ENTERPRISE_ACCEPTANCE_CHECKLIST.md +95 -0
- package/vendor/agent-root/src/agent/ENTERPRISE_REALTIME.html +1345 -0
- package/vendor/agent-root/src/agent/ENTERPRISE_REALTIME.md +1353 -0
- package/vendor/agent-root/src/agent/ERROR_CONTRACT.md +60 -0
- package/vendor/agent-root/src/agent/TEST_COVERAGE_ANALYSIS.md +278 -0
- package/vendor/agent-root/src/agent/__test__/error-contract.test.ts +72 -0
- package/vendor/agent-root/src/agent/__test__/types.test.ts +137 -0
- package/vendor/agent-root/src/agent/agent/__test__/abort-runtime.test.ts +83 -0
- package/vendor/agent-root/src/agent/agent/__test__/callback-safety.test.ts +34 -0
- package/vendor/agent-root/src/agent/agent/__test__/compaction.test.ts +323 -0
- package/vendor/agent-root/src/agent/agent/__test__/concurrency.test.ts +290 -0
- package/vendor/agent-root/src/agent/agent/__test__/error-normalizer.test.ts +377 -0
- package/vendor/agent-root/src/agent/agent/__test__/error.test.ts +212 -0
- package/vendor/agent-root/src/agent/agent/__test__/fault-injection.test.ts +295 -0
- package/vendor/agent-root/src/agent/agent/__test__/index.test.ts +3607 -0
- package/vendor/agent-root/src/agent/agent/__test__/logger.test.ts +35 -0
- package/vendor/agent-root/src/agent/agent/__test__/message-utils.test.ts +517 -0
- package/vendor/agent-root/src/agent/agent/__test__/telemetry.test.ts +97 -0
- package/vendor/agent-root/src/agent/agent/__test__/timeout-budget.test.ts +479 -0
- package/vendor/agent-root/src/agent/agent/__test__/tool-call-merge.test.ts +80 -0
- package/vendor/agent-root/src/agent/agent/__test__/tool-execution-ledger.test.ts +76 -0
- package/vendor/agent-root/src/agent/agent/__test__/write-buffer.test.ts +173 -0
- package/vendor/agent-root/src/agent/agent/__test__/write-file-session.test.ts +109 -0
- package/vendor/agent-root/src/agent/agent/abort-runtime.ts +71 -0
- package/vendor/agent-root/src/agent/agent/callback-safety.ts +33 -0
- package/vendor/agent-root/src/agent/agent/compaction.ts +291 -0
- package/vendor/agent-root/src/agent/agent/concurrency.ts +103 -0
- package/vendor/agent-root/src/agent/agent/error-normalizer.ts +190 -0
- package/vendor/agent-root/src/agent/agent/error.ts +198 -0
- package/vendor/agent-root/src/agent/agent/index.ts +1772 -0
- package/vendor/agent-root/src/agent/agent/logger.ts +65 -0
- package/vendor/agent-root/src/agent/agent/message-utils.ts +101 -0
- package/vendor/agent-root/src/agent/agent/stream-events.ts +61 -0
- package/vendor/agent-root/src/agent/agent/telemetry.ts +123 -0
- package/vendor/agent-root/src/agent/agent/timeout-budget.ts +227 -0
- package/vendor/agent-root/src/agent/agent/tool-call-merge.ts +111 -0
- package/vendor/agent-root/src/agent/agent/tool-execution-ledger.ts +164 -0
- package/vendor/agent-root/src/agent/agent/write-buffer.ts +188 -0
- package/vendor/agent-root/src/agent/agent/write-file-session.ts +238 -0
- package/vendor/agent-root/src/agent/app/__test__/agent-app-service.test.ts +1053 -0
- package/vendor/agent-root/src/agent/app/__test__/minimal-agent-application.test.ts +158 -0
- package/vendor/agent-root/src/agent/app/__test__/sqlite-agent-app-store.test.ts +437 -0
- package/vendor/agent-root/src/agent/app/agent-app-service.ts +748 -0
- package/vendor/agent-root/src/agent/app/contracts.ts +109 -0
- package/vendor/agent-root/src/agent/app/index.ts +5 -0
- package/vendor/agent-root/src/agent/app/minimal-agent-application.ts +151 -0
- package/vendor/agent-root/src/agent/app/ports.ts +72 -0
- package/vendor/agent-root/src/agent/app/sqlite-agent-app-store.ts +1182 -0
- package/vendor/agent-root/src/agent/app/sqlite-client.ts +177 -0
- package/vendor/agent-root/src/agent/docs/cli-app-layer/00-README.md +36 -0
- package/vendor/agent-root/src/agent/docs/cli-app-layer/01-scope-and-goals.md +33 -0
- package/vendor/agent-root/src/agent/docs/cli-app-layer/02-architecture-overview.md +40 -0
- package/vendor/agent-root/src/agent/docs/cli-app-layer/03-domain-model-and-contracts.md +91 -0
- package/vendor/agent-root/src/agent/docs/cli-app-layer/04-ports-and-interfaces.md +116 -0
- package/vendor/agent-root/src/agent/docs/cli-app-layer/05-run-orchestration-and-state-machine.md +52 -0
- package/vendor/agent-root/src/agent/docs/cli-app-layer/06-cli-commands-and-ux.md +53 -0
- package/vendor/agent-root/src/agent/docs/cli-app-layer/07-storage-design-local.md +52 -0
- package/vendor/agent-root/src/agent/docs/cli-app-layer/08-error-and-observability.md +40 -0
- package/vendor/agent-root/src/agent/docs/cli-app-layer/09-security-and-policy-boundary.md +19 -0
- package/vendor/agent-root/src/agent/docs/cli-app-layer/10-test-plan-and-acceptance.md +28 -0
- package/vendor/agent-root/src/agent/docs/cli-app-layer/11-implementation-phases.md +26 -0
- package/vendor/agent-root/src/agent/docs/cli-app-layer/12-open-questions-and-risks.md +30 -0
- package/vendor/agent-root/src/agent/docs/cli-app-layer/13-sqlite-schema-fields-and-rationale.md +567 -0
- package/vendor/agent-root/src/agent/docs/cli-app-layer/14-project-flow-mermaid.md +583 -0
- package/vendor/agent-root/src/agent/docs/cli-app-layer/15-openclaw-style-project-blueprint.md +972 -0
- package/vendor/agent-root/src/agent/error-contract.ts +154 -0
- package/vendor/agent-root/src/agent/prompts/system.ts +246 -0
- package/vendor/agent-root/src/agent/prompts/system1.ts +208 -0
- package/vendor/agent-root/src/agent/storage/__test__/file-history-store.test.ts +98 -0
- package/vendor/agent-root/src/agent/storage/file-history-store.ts +313 -0
- package/vendor/agent-root/src/agent/storage/file-storage-config.ts +94 -0
- package/vendor/agent-root/src/agent/storage/file-system.ts +31 -0
- package/vendor/agent-root/src/agent/storage/file-write-service.ts +21 -0
- package/vendor/agent-root/src/agent/tool/__test__/base-tool.test.ts +413 -0
- package/vendor/agent-root/src/agent/tool/__test__/bash-policy.test.ts +356 -0
- package/vendor/agent-root/src/agent/tool/__test__/bash.mocked-coverage.test.ts +375 -0
- package/vendor/agent-root/src/agent/tool/__test__/bash.test.ts +372 -0
- package/vendor/agent-root/src/agent/tool/__test__/error.test.ts +108 -0
- package/vendor/agent-root/src/agent/tool/__test__/file-edit-tool.test.ts +258 -0
- package/vendor/agent-root/src/agent/tool/__test__/file-history-tools.test.ts +121 -0
- package/vendor/agent-root/src/agent/tool/__test__/file-read-tool.test.ts +210 -0
- package/vendor/agent-root/src/agent/tool/__test__/glob.test.ts +139 -0
- package/vendor/agent-root/src/agent/tool/__test__/grep.mocked-coverage.test.ts +456 -0
- package/vendor/agent-root/src/agent/tool/__test__/grep.test.ts +192 -0
- package/vendor/agent-root/src/agent/tool/__test__/lsp.test.ts +300 -0
- package/vendor/agent-root/src/agent/tool/__test__/outside-workspace-confirmation.test.ts +214 -0
- package/vendor/agent-root/src/agent/tool/__test__/path-security.test.ts +336 -0
- package/vendor/agent-root/src/agent/tool/__test__/skill-loader.test.ts +494 -0
- package/vendor/agent-root/src/agent/tool/__test__/skill-parser.test.ts +543 -0
- package/vendor/agent-root/src/agent/tool/__test__/skill-tool.test.ts +172 -0
- package/vendor/agent-root/src/agent/tool/__test__/task-concurrency-and-version.test.ts +116 -0
- package/vendor/agent-root/src/agent/tool/__test__/task-create-get-list-update.test.ts +267 -0
- package/vendor/agent-root/src/agent/tool/__test__/task-create.test.ts +519 -0
- package/vendor/agent-root/src/agent/tool/__test__/task-errors.test.ts +225 -0
- package/vendor/agent-root/src/agent/tool/__test__/task-output-blocking.test.ts +223 -0
- package/vendor/agent-root/src/agent/tool/__test__/task-output.test.ts +184 -0
- package/vendor/agent-root/src/agent/tool/__test__/task-parent-abort.test.ts +287 -0
- package/vendor/agent-root/src/agent/tool/__test__/task-real-runner-adapter.test.ts +190 -0
- package/vendor/agent-root/src/agent/tool/__test__/task-run-lifecycle.test.ts +352 -0
- package/vendor/agent-root/src/agent/tool/__test__/task-store-runner-branches.test.ts +395 -0
- package/vendor/agent-root/src/agent/tool/__test__/task-store.test.ts +391 -0
- package/vendor/agent-root/src/agent/tool/__test__/task-subagent-config-integration.test.ts +176 -0
- package/vendor/agent-root/src/agent/tool/__test__/task-subagent-config.test.ts +68 -0
- package/vendor/agent-root/src/agent/tool/__test__/task-tools-core-edges.test.ts +630 -0
- package/vendor/agent-root/src/agent/tool/__test__/task-tools-runtime-edges.test.ts +732 -0
- package/vendor/agent-root/src/agent/tool/__test__/task-types.test.ts +494 -0
- package/vendor/agent-root/src/agent/tool/__test__/task-utils-branches.test.ts +175 -0
- package/vendor/agent-root/src/agent/tool/__test__/tool-manager.test.ts +505 -0
- package/vendor/agent-root/src/agent/tool/__test__/types.test.ts +55 -0
- package/vendor/agent-root/src/agent/tool/__test__/web-fetch.test.ts +244 -0
- package/vendor/agent-root/src/agent/tool/__test__/web-search.test.ts +290 -0
- package/vendor/agent-root/src/agent/tool/__test__/write-file.test.ts +368 -0
- package/vendor/agent-root/src/agent/tool/base-tool.ts +345 -0
- package/vendor/agent-root/src/agent/tool/bash-policy.ts +636 -0
- package/vendor/agent-root/src/agent/tool/bash.ts +688 -0
- package/vendor/agent-root/src/agent/tool/error.ts +131 -0
- package/vendor/agent-root/src/agent/tool/file-edit-tool.ts +264 -0
- package/vendor/agent-root/src/agent/tool/file-history-list.ts +103 -0
- package/vendor/agent-root/src/agent/tool/file-history-restore.ts +149 -0
- package/vendor/agent-root/src/agent/tool/file-read-tool.ts +211 -0
- package/vendor/agent-root/src/agent/tool/glob.ts +171 -0
- package/vendor/agent-root/src/agent/tool/grep.ts +496 -0
- package/vendor/agent-root/src/agent/tool/lsp.ts +481 -0
- package/vendor/agent-root/src/agent/tool/path-security.ts +117 -0
- package/vendor/agent-root/src/agent/tool/search/common.ts +153 -0
- package/vendor/agent-root/src/agent/tool/skill/index.ts +13 -0
- package/vendor/agent-root/src/agent/tool/skill/loader.ts +229 -0
- package/vendor/agent-root/src/agent/tool/skill/parser.ts +124 -0
- package/vendor/agent-root/src/agent/tool/skill/types.ts +27 -0
- package/vendor/agent-root/src/agent/tool/skill-tool.ts +143 -0
- package/vendor/agent-root/src/agent/tool/task-create.ts +186 -0
- package/vendor/agent-root/src/agent/tool/task-errors.ts +42 -0
- package/vendor/agent-root/src/agent/tool/task-get.ts +116 -0
- package/vendor/agent-root/src/agent/tool/task-graph.ts +78 -0
- package/vendor/agent-root/src/agent/tool/task-list.ts +141 -0
- package/vendor/agent-root/src/agent/tool/task-mock-runner-adapter.ts +232 -0
- package/vendor/agent-root/src/agent/tool/task-output.ts +223 -0
- package/vendor/agent-root/src/agent/tool/task-parent-abort.ts +115 -0
- package/vendor/agent-root/src/agent/tool/task-real-runner-adapter.ts +336 -0
- package/vendor/agent-root/src/agent/tool/task-runner-adapter.ts +55 -0
- package/vendor/agent-root/src/agent/tool/task-stop.ts +187 -0
- package/vendor/agent-root/src/agent/tool/task-store.ts +217 -0
- package/vendor/agent-root/src/agent/tool/task-subagent-config.ts +149 -0
- package/vendor/agent-root/src/agent/tool/task-types.ts +264 -0
- package/vendor/agent-root/src/agent/tool/task-update.ts +315 -0
- package/vendor/agent-root/src/agent/tool/task.ts +209 -0
- package/vendor/agent-root/src/agent/tool/tool-manager.ts +362 -0
- package/vendor/agent-root/src/agent/tool/tool-prompts.ts +242 -0
- package/vendor/agent-root/src/agent/tool/types.ts +116 -0
- package/vendor/agent-root/src/agent/tool/web-fetch.ts +227 -0
- package/vendor/agent-root/src/agent/tool/web-search.ts +208 -0
- package/vendor/agent-root/src/agent/tool/write-file.ts +497 -0
- package/vendor/agent-root/src/agent/types.ts +232 -0
- package/vendor/agent-root/src/agent/utils/__tests__/index.test.ts +18 -0
- package/vendor/agent-root/src/agent/utils/__tests__/message-utils.test.ts +610 -0
- package/vendor/agent-root/src/agent/utils/__tests__/message.test.ts +223 -0
- package/vendor/agent-root/src/agent/utils/__tests__/token.test.ts +42 -0
- package/vendor/agent-root/src/agent/utils/index.ts +16 -0
- package/vendor/agent-root/src/agent/utils/message.ts +171 -0
- package/vendor/agent-root/src/agent/utils/token.ts +28 -0
- package/vendor/agent-root/src/config/__tests__/load-config-to-env.test.ts +129 -0
- package/vendor/agent-root/src/config/__tests__/loader.test.ts +247 -0
- package/vendor/agent-root/src/config/__tests__/runtime.test.ts +88 -0
- package/vendor/agent-root/src/config/index.ts +54 -0
- package/vendor/agent-root/src/config/loader.ts +431 -0
- package/vendor/agent-root/src/config/paths.ts +30 -0
- package/vendor/agent-root/src/config/runtime.ts +163 -0
- package/vendor/agent-root/src/config/types.ts +70 -0
- package/vendor/agent-root/src/logger/index.ts +57 -0
- package/vendor/agent-root/src/logger/logger.ts +819 -0
- package/vendor/agent-root/src/logger/types.ts +150 -0
- package/vendor/agent-root/src/providers/__tests__/errors.test.ts +441 -0
- package/vendor/agent-root/src/providers/__tests__/index.test.ts +16 -0
- package/vendor/agent-root/src/providers/__tests__/openai-compatible.options.test.ts +318 -0
- package/vendor/agent-root/src/providers/__tests__/openai-compatible.test.ts +600 -0
- package/vendor/agent-root/src/providers/__tests__/registry.test.ts +449 -0
- package/vendor/agent-root/src/providers/__tests__/responses-adapter.test.ts +298 -0
- package/vendor/agent-root/src/providers/adapters/__tests__/anthropic.test.ts +354 -0
- package/vendor/agent-root/src/providers/adapters/__tests__/kimi.test.ts +58 -0
- package/vendor/agent-root/src/providers/adapters/__tests__/standard.test.ts +261 -0
- package/vendor/agent-root/src/providers/adapters/anthropic.ts +572 -0
- package/vendor/agent-root/src/providers/adapters/base.ts +131 -0
- package/vendor/agent-root/src/providers/adapters/kimi.ts +48 -0
- package/vendor/agent-root/src/providers/adapters/responses.ts +732 -0
- package/vendor/agent-root/src/providers/adapters/standard.ts +120 -0
- package/vendor/agent-root/src/providers/http/__tests__/client.timeout.test.ts +313 -0
- package/vendor/agent-root/src/providers/http/client.ts +289 -0
- package/vendor/agent-root/src/providers/http/stream-parser.ts +109 -0
- package/vendor/agent-root/src/providers/index.ts +76 -0
- package/vendor/agent-root/src/providers/kimi-headers.ts +177 -0
- package/vendor/agent-root/src/providers/openai-compatible.ts +387 -0
- package/vendor/agent-root/src/providers/registry/model-config.ts +230 -0
- package/vendor/agent-root/src/providers/registry/provider-factory.ts +123 -0
- package/vendor/agent-root/src/providers/registry.ts +135 -0
- package/vendor/agent-root/src/providers/types/api.ts +284 -0
- package/vendor/agent-root/src/providers/types/config.ts +58 -0
- package/vendor/agent-root/src/providers/types/errors.ts +323 -0
- package/vendor/agent-root/src/providers/types/index.ts +72 -0
- package/vendor/agent-root/src/providers/types/provider.ts +45 -0
- package/vendor/agent-root/src/providers/types/registry.ts +88 -0
|
@@ -0,0 +1,583 @@
|
|
|
1
|
+
# 14. 项目流程图(Mermaid,详细版)
|
|
2
|
+
|
|
3
|
+
本文给出 CLI 应用层基于 `StatelessAgent` 的完整流程图,重点回答:
|
|
4
|
+
|
|
5
|
+
- 什么时候做什么
|
|
6
|
+
- 每一步写哪些表
|
|
7
|
+
- 终态如何收敛
|
|
8
|
+
- 异步索引何时触发
|
|
9
|
+
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
## 1. 端到端总流程(含命令分支)
|
|
13
|
+
|
|
14
|
+
```mermaid
|
|
15
|
+
flowchart TD
|
|
16
|
+
A["CLI Process Start"] --> B["Load Config + Init Ports/Adapters"]
|
|
17
|
+
B --> C{"Command Type?"}
|
|
18
|
+
|
|
19
|
+
C -->|"agent run"| D["Resolve conversationId/executionId"]
|
|
20
|
+
C -->|"agent run-status"| Q1["Query runs by executionId"]
|
|
21
|
+
C -->|"agent run-list"| Q2["Query runs by conversationId"]
|
|
22
|
+
|
|
23
|
+
Q1 --> Q3["Render status output"]
|
|
24
|
+
Q2 --> Q4["Render run list output"]
|
|
25
|
+
Q3 --> Z["Exit"]
|
|
26
|
+
Q4 --> Z
|
|
27
|
+
|
|
28
|
+
D --> E["ExecutionStore.create status=CREATED"]
|
|
29
|
+
E --> F["EventStore.append user_message event"]
|
|
30
|
+
F --> G["MessageProjection.upsertFromEvent"]
|
|
31
|
+
G --> H["ExecutionStore.patch status=RUNNING"]
|
|
32
|
+
H --> I["Build AgentInput and start runStream"]
|
|
33
|
+
I --> I1["Listen agent tool_chunk emitter"]
|
|
34
|
+
I1 --> I2["Normalize tool_chunk -> tool_stream envelope"]
|
|
35
|
+
I2 --> K["EventStore.append(event envelope)"]
|
|
36
|
+
|
|
37
|
+
I --> J{"Stream Event Received?"}
|
|
38
|
+
J -->|"chunk/reasoning_chunk/tool_call/progress/checkpoint/compaction/tool_result"| K["EventStore.append(event envelope)"]
|
|
39
|
+
J -->|"done"| K1["EventStore.append(done event)"]
|
|
40
|
+
J -->|"error"| K2["EventStore.append(error event)"]
|
|
41
|
+
K --> L["EventSink.publish to CLI"]
|
|
42
|
+
K1 --> L1["EventSink.publish done"]
|
|
43
|
+
K2 --> L2["EventSink.publish error"]
|
|
44
|
+
L --> M{"Need Projection/State Update?"}
|
|
45
|
+
|
|
46
|
+
M -->|"message-like event"| N["MessageProjection.upsertFromEvent"]
|
|
47
|
+
M -->|"progress"| O["ExecutionStore.patch stepIndex"]
|
|
48
|
+
M -->|"checkpoint"| P["CheckpointStore.save + patch stepIndex"]
|
|
49
|
+
M -->|"compaction"| R["SummaryStore.append (if enabled)"]
|
|
50
|
+
M -->|"no"| S["Continue stream loop"]
|
|
51
|
+
|
|
52
|
+
N --> S
|
|
53
|
+
O --> S
|
|
54
|
+
P --> S
|
|
55
|
+
R --> S
|
|
56
|
+
S --> J
|
|
57
|
+
|
|
58
|
+
L1 --> T["Map done.finishReason -> COMPLETED"]
|
|
59
|
+
L2 --> U["Map errorCode -> FAILED/CANCELLED + terminalReason"]
|
|
60
|
+
|
|
61
|
+
T --> V["ExecutionStore.patch terminal fields + completedAt"]
|
|
62
|
+
U --> V
|
|
63
|
+
V --> W["Optional RunLogStore.append warn/error"]
|
|
64
|
+
W --> X["Trigger async indexing job"]
|
|
65
|
+
X --> Y["Render final summary to CLI"]
|
|
66
|
+
Y --> Z
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
---
|
|
70
|
+
|
|
71
|
+
## 2. 运行时序图(谁在什么时候做什么)
|
|
72
|
+
|
|
73
|
+
```mermaid
|
|
74
|
+
sequenceDiagram
|
|
75
|
+
autonumber
|
|
76
|
+
actor User
|
|
77
|
+
participant CLI as CLI Command
|
|
78
|
+
participant App as AgentAppService
|
|
79
|
+
participant Orch as RunOrchestrator
|
|
80
|
+
participant Agent as StatelessAgent.runStream
|
|
81
|
+
participant Exec as ExecutionStore
|
|
82
|
+
participant Event as EventStore
|
|
83
|
+
participant Proj as MessageProjectionStore
|
|
84
|
+
participant Sum as SummaryStore
|
|
85
|
+
participant Ckpt as CheckpointStore
|
|
86
|
+
participant Sink as EventSink(CLI)
|
|
87
|
+
participant Log as RunLogStore
|
|
88
|
+
participant Idx as Indexer
|
|
89
|
+
|
|
90
|
+
User->>CLI: agent run --conversation --message
|
|
91
|
+
CLI->>App: runForeground(request)
|
|
92
|
+
App->>Orch: start(request)
|
|
93
|
+
Orch->>Exec: create(CREATED)
|
|
94
|
+
Orch->>Event: append(user_message)
|
|
95
|
+
Orch->>Proj: upsertFromEvent(user_message)
|
|
96
|
+
Orch->>Exec: patch(RUNNING)
|
|
97
|
+
Orch->>Agent: runStream(input)
|
|
98
|
+
|
|
99
|
+
loop For each StreamEvent
|
|
100
|
+
Agent-->>Orch: event(type,data)
|
|
101
|
+
Orch->>Event: append(event envelope)
|
|
102
|
+
Orch->>Sink: publish(event)
|
|
103
|
+
alt event=progress
|
|
104
|
+
Orch->>Exec: patch(stepIndex)
|
|
105
|
+
else event=checkpoint
|
|
106
|
+
Orch->>Ckpt: save(checkpoint)
|
|
107
|
+
Orch->>Exec: patch(stepIndex)
|
|
108
|
+
else event=chunk/reasoning_chunk/tool_call/tool_result
|
|
109
|
+
Orch->>Proj: upsertFromEvent(event)
|
|
110
|
+
else event=compaction
|
|
111
|
+
Orch->>Sum: append(summary projection)
|
|
112
|
+
end
|
|
113
|
+
end
|
|
114
|
+
|
|
115
|
+
par Tool chunk bridge
|
|
116
|
+
Agent-->>Orch: emit(tool_chunk)
|
|
117
|
+
Orch->>Event: append(tool_stream envelope)
|
|
118
|
+
Orch->>Sink: publish(tool_stream)
|
|
119
|
+
end
|
|
120
|
+
|
|
121
|
+
alt Terminal done
|
|
122
|
+
Orch->>Exec: patch(status=COMPLETED, terminalReason)
|
|
123
|
+
Orch->>Log: append(info sampled)
|
|
124
|
+
else Terminal error
|
|
125
|
+
Orch->>Exec: patch(status=FAILED/CANCELLED, terminalReason,errorCode)
|
|
126
|
+
Orch->>Log: append(warn/error)
|
|
127
|
+
end
|
|
128
|
+
|
|
129
|
+
Orch->>Idx: enqueue/reindex(conversation scope)
|
|
130
|
+
Orch-->>App: RunResult
|
|
131
|
+
App-->>CLI: Final output
|
|
132
|
+
CLI-->>User: Exit
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
---
|
|
136
|
+
|
|
137
|
+
## 3. 执行状态机(终止语义)
|
|
138
|
+
|
|
139
|
+
```mermaid
|
|
140
|
+
stateDiagram-v2
|
|
141
|
+
[*] --> CREATED
|
|
142
|
+
CREATED --> RUNNING: run started
|
|
143
|
+
RUNNING --> COMPLETED: done(stop|max_steps)
|
|
144
|
+
RUNNING --> FAILED: error(timeout|max_retries|other)
|
|
145
|
+
RUNNING --> CANCELLED: error(AGENT_ABORTED)
|
|
146
|
+
COMPLETED --> [*]
|
|
147
|
+
FAILED --> [*]
|
|
148
|
+
CANCELLED --> [*]
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
---
|
|
152
|
+
|
|
153
|
+
## 4. 触发点 -> 动作 -> 写表(详细)
|
|
154
|
+
|
|
155
|
+
| 阶段 | 触发点 | 动作 | 主要写表 |
|
|
156
|
+
|---|---|---|---|
|
|
157
|
+
| 初始化 | `agent run` 启动 | 建立运行记录 | `runs` |
|
|
158
|
+
| 输入入库 | 用户消息进入 | 写事实事件并更新投影 | `events`, `messages` |
|
|
159
|
+
| 进入运行 | runStream 开始 | 状态置为运行中 | `runs` |
|
|
160
|
+
| 流式过程 | 每个 stream event | 先写事件,再发布到 CLI | `events` |
|
|
161
|
+
| 工具流桥接 | `tool_chunk` emitter | 归一化为 `tool_stream` 并发布 | `events` |
|
|
162
|
+
| 过程同步 | `progress` | 更新 stepIndex | `runs` |
|
|
163
|
+
| 过程同步 | `checkpoint` | 保存断点与步数 | `checkpoints`, `runs` |
|
|
164
|
+
| 消息投影 | `chunk/reasoning/tool_*` | 更新消息读模型 | `messages` |
|
|
165
|
+
| 压缩阶段 | `compaction` | 事件已在统一入口落库,此处仅落摘要(若启用) | `summaries` |
|
|
166
|
+
| 工具幂等 | tool executeOnce | 防重放副作用 | `tool_ledger` |
|
|
167
|
+
| 错误诊断 | warn/error | 记录技术日志(可选) | `run_logs` |
|
|
168
|
+
| 终态收敛 | `done/error` | 写终态、终止原因、错误包 | `runs` |
|
|
169
|
+
| 后台索引 | run 结束后异步 | 更新检索索引 | `files`, `chunks`, `chunks_fts`, `chunks_vec`, `embedding_cache` |
|
|
170
|
+
|
|
171
|
+
---
|
|
172
|
+
|
|
173
|
+
## 5. 异步索引流程(run 结束后)
|
|
174
|
+
|
|
175
|
+
```mermaid
|
|
176
|
+
flowchart LR
|
|
177
|
+
A["Run Terminal"] --> B["Collect changed message ranges"]
|
|
178
|
+
B --> C["Materialize virtual files: conversation/{id}/seq-range"]
|
|
179
|
+
C --> D["Chunking text"]
|
|
180
|
+
D --> E["Embedding compute (with embedding_cache lookup)"]
|
|
181
|
+
E --> F["Upsert files + chunks"]
|
|
182
|
+
F --> G{"FTS enabled?"}
|
|
183
|
+
G -->|"Yes"| H["Upsert chunks_fts"]
|
|
184
|
+
G -->|"No"| I["Skip FTS"]
|
|
185
|
+
H --> J{"Vector enabled?"}
|
|
186
|
+
I --> J
|
|
187
|
+
J -->|"Yes"| K["Upsert chunks_vec"]
|
|
188
|
+
J -->|"No"| L["Skip Vec"]
|
|
189
|
+
K --> M["Index done"]
|
|
190
|
+
L --> M
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
---
|
|
194
|
+
|
|
195
|
+
## 6. 落地顺序建议(与流程图一致)
|
|
196
|
+
|
|
197
|
+
1. 先实现运行主链路:`runs + events + messages + checkpoints`
|
|
198
|
+
2. 再接入 `tool_ledger`(幂等)与 `run_logs`(可选)
|
|
199
|
+
3. 最后实现异步索引链路:`files/chunks/fts/vec/cache`
|
|
200
|
+
|
|
201
|
+
---
|
|
202
|
+
|
|
203
|
+
## 7. 单次 `agent run` 详细时间线(何时写什么)
|
|
204
|
+
|
|
205
|
+
```mermaid
|
|
206
|
+
sequenceDiagram
|
|
207
|
+
autonumber
|
|
208
|
+
actor User
|
|
209
|
+
participant CLI as CLI
|
|
210
|
+
participant App as AppService
|
|
211
|
+
participant Orch as RunOrchestrator
|
|
212
|
+
participant Agent as StatelessAgent
|
|
213
|
+
participant DB as SQLite(agent.db)
|
|
214
|
+
participant Worker as Index Worker
|
|
215
|
+
|
|
216
|
+
User->>CLI: 输入命令与用户消息
|
|
217
|
+
CLI->>App: runForeground(request)
|
|
218
|
+
App->>Orch: start(request)
|
|
219
|
+
|
|
220
|
+
Orch->>DB: INSERT runs(status=CREATED)
|
|
221
|
+
Note over DB: 表: runs
|
|
222
|
+
|
|
223
|
+
Orch->>DB: INSERT events(type=user_message, seq=1)
|
|
224
|
+
Orch->>DB: UPSERT messages(投影用户消息)
|
|
225
|
+
Note over DB: 表: events, messages
|
|
226
|
+
|
|
227
|
+
Orch->>DB: UPDATE runs(status=RUNNING, started_at)
|
|
228
|
+
Orch->>Agent: runStream(input)
|
|
229
|
+
|
|
230
|
+
loop 每个 StreamEvent
|
|
231
|
+
Agent-->>Orch: event(type, payload)
|
|
232
|
+
Orch->>DB: INSERT events(seq+1, event envelope)
|
|
233
|
+
alt type = chunk/reasoning_chunk/tool_call/tool_result
|
|
234
|
+
Orch->>DB: UPSERT messages(assistant/tool 投影)
|
|
235
|
+
Note over DB: 表: messages
|
|
236
|
+
else type = progress
|
|
237
|
+
Orch->>DB: UPDATE runs(step_index)
|
|
238
|
+
Note over DB: 表: runs
|
|
239
|
+
else type = checkpoint
|
|
240
|
+
Orch->>DB: INSERT checkpoints(step, blob)
|
|
241
|
+
Orch->>DB: UPDATE runs(last_checkpoint_seq, step_index)
|
|
242
|
+
Note over DB: 表: checkpoints, runs
|
|
243
|
+
else type = compaction
|
|
244
|
+
Orch->>DB: INSERT summaries(覆盖区间、版本、token)
|
|
245
|
+
Note over DB: 表: summaries(compaction 事件已在统一入口写入 events)
|
|
246
|
+
else type = tool_call + tool_result(副作用工具)
|
|
247
|
+
Orch->>DB: UPSERT tool_ledger(idempotency_key,status,pending_expires_at_ms)
|
|
248
|
+
Note over DB: 表: tool_ledger
|
|
249
|
+
end
|
|
250
|
+
end
|
|
251
|
+
|
|
252
|
+
alt Terminal = done
|
|
253
|
+
Orch->>DB: UPDATE runs(status=COMPLETED, terminal_reason, completed_at)
|
|
254
|
+
else Terminal = error
|
|
255
|
+
Orch->>DB: UPDATE runs(status=FAILED/CANCELLED, terminal_reason, error_code, completed_at)
|
|
256
|
+
Orch->>DB: INSERT run_logs(level=warn/error, message)
|
|
257
|
+
Note over DB: 表: run_logs
|
|
258
|
+
end
|
|
259
|
+
|
|
260
|
+
Orch->>Worker: 触发异步索引任务(conversation scope)
|
|
261
|
+
Worker->>DB: UPSERT files/chunks/chunks_fts/chunks_vec/embedding_cache
|
|
262
|
+
Note over DB: 表: files, chunks, chunks_fts, chunks_vec, embedding_cache
|
|
263
|
+
|
|
264
|
+
App-->>CLI: 返回 RunResult + 最终摘要
|
|
265
|
+
CLI-->>User: 渲染退出
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
---
|
|
269
|
+
|
|
270
|
+
## 8. 失败重试与恢复执行(`agent resume`)
|
|
271
|
+
|
|
272
|
+
说明:
|
|
273
|
+
- **单次 run 内重试**由内核处理(`terminalReason=max_retries` 表示内核预算耗尽)。
|
|
274
|
+
- **跨 run 恢复**由 CLI 应用层处理(`agent resume` 创建新 `run_id`)。
|
|
275
|
+
|
|
276
|
+
### 8.1 恢复决策流程(何时恢复、何时冷启动)
|
|
277
|
+
|
|
278
|
+
```mermaid
|
|
279
|
+
flowchart TD
|
|
280
|
+
A["Trigger: agent resume or retry policy"] --> B["Load previous run + context facts"]
|
|
281
|
+
B --> B1["Read runs/events/messages/summaries/checkpoints"]
|
|
282
|
+
B1 --> C{"Recoverable state exists?"}
|
|
283
|
+
|
|
284
|
+
C -->|"No"| D["Create new run as cold start"]
|
|
285
|
+
C -->|"Yes"| E["Pick restore point from checkpoint/seq"]
|
|
286
|
+
|
|
287
|
+
D --> F["Build AgentInput from latest context window"]
|
|
288
|
+
E --> F1["Build AgentInput from restore point + delta"]
|
|
289
|
+
F1 --> F
|
|
290
|
+
|
|
291
|
+
F --> G["INSERT runs(status=created)"]
|
|
292
|
+
G --> H["INSERT events(type=resume_requested)"]
|
|
293
|
+
H --> I["UPDATE runs(status=running, started_at)"]
|
|
294
|
+
I --> J["Start runStream"]
|
|
295
|
+
|
|
296
|
+
J --> K{"Terminal?"}
|
|
297
|
+
K -->|"done(stop|max_steps)"| L["UPDATE runs -> completed"]
|
|
298
|
+
K -->|"error(aborted/timeout/max_retries/other)"| M["UPDATE runs -> failed/cancelled + error_json"]
|
|
299
|
+
|
|
300
|
+
L --> N["Trigger async indexing + return summary"]
|
|
301
|
+
M --> O["INSERT run_logs(warn/error)"]
|
|
302
|
+
O --> P{"Retryable and budget left?"}
|
|
303
|
+
P -->|"Yes"| Q["Suggest next resume (new run)"]
|
|
304
|
+
P -->|"No"| R["Stop and surface error"]
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
### 8.2 恢复执行时序(写表顺序)
|
|
308
|
+
|
|
309
|
+
```mermaid
|
|
310
|
+
sequenceDiagram
|
|
311
|
+
autonumber
|
|
312
|
+
actor User
|
|
313
|
+
participant CLI as CLI
|
|
314
|
+
participant App as AppService
|
|
315
|
+
participant DB as SQLite(agent.db)
|
|
316
|
+
participant Agent as StatelessAgent
|
|
317
|
+
participant Worker as Index Worker
|
|
318
|
+
|
|
319
|
+
User->>CLI: agent resume --conversation <id>
|
|
320
|
+
CLI->>App: resumeForeground(request)
|
|
321
|
+
|
|
322
|
+
App->>DB: SELECT runs(最近终态)
|
|
323
|
+
App->>DB: SELECT checkpoints(最新可用断点)
|
|
324
|
+
App->>DB: SELECT messages/summaries(恢复上下文)
|
|
325
|
+
App->>App: 计算 restore point 与输入窗口
|
|
326
|
+
|
|
327
|
+
App->>DB: INSERT runs(status=CREATED, request_json含resume来源)
|
|
328
|
+
App->>DB: INSERT events(type=resume_requested)
|
|
329
|
+
App->>DB: UPDATE runs(status=RUNNING)
|
|
330
|
+
App->>Agent: runStream(input)
|
|
331
|
+
|
|
332
|
+
loop 每个 StreamEvent
|
|
333
|
+
Agent-->>App: event(type, payload)
|
|
334
|
+
App->>DB: INSERT events(event envelope)
|
|
335
|
+
alt type = chunk/reasoning_chunk/tool_call/tool_result
|
|
336
|
+
App->>DB: UPSERT messages
|
|
337
|
+
else type = progress
|
|
338
|
+
App->>DB: UPDATE runs(step_index)
|
|
339
|
+
else type = checkpoint
|
|
340
|
+
App->>DB: INSERT checkpoints
|
|
341
|
+
App->>DB: UPDATE runs(last_checkpoint_seq, step_index)
|
|
342
|
+
else type = compaction
|
|
343
|
+
App->>DB: INSERT summaries
|
|
344
|
+
end
|
|
345
|
+
end
|
|
346
|
+
|
|
347
|
+
alt done
|
|
348
|
+
App->>DB: UPDATE runs(status=COMPLETED, terminal_reason, completed_at)
|
|
349
|
+
App->>Worker: 触发索引更新
|
|
350
|
+
else error
|
|
351
|
+
App->>DB: UPDATE runs(status=FAILED/CANCELLED, terminal_reason, error_json, completed_at)
|
|
352
|
+
App->>DB: INSERT run_logs(level=warn/error)
|
|
353
|
+
end
|
|
354
|
+
|
|
355
|
+
App-->>CLI: ResumeResult
|
|
356
|
+
CLI-->>User: 输出恢复结果
|
|
357
|
+
```
|
|
358
|
+
|
|
359
|
+
---
|
|
360
|
+
|
|
361
|
+
## 9. 并发冲突与幂等(`tool_ledger` 原子化)
|
|
362
|
+
|
|
363
|
+
目标:
|
|
364
|
+
- 同一 `run_id + tool_call_id` 在并发情况下只允许一次副作用执行。
|
|
365
|
+
- 其余并发请求返回已存在结果或等待执行完成。
|
|
366
|
+
|
|
367
|
+
### 9.1 `executeOnce` 原子流程(推荐实现)
|
|
368
|
+
|
|
369
|
+
```mermaid
|
|
370
|
+
flowchart TD
|
|
371
|
+
A["Receive tool_call(run_id, tool_call_id)"] --> B["BEGIN IMMEDIATE TRANSACTION"]
|
|
372
|
+
B --> C{"INSERT tool_ledger(status='pending', pending_expires_at_ms) success?"}
|
|
373
|
+
|
|
374
|
+
C -->|"Yes (winner)"| D["Commit lock row"]
|
|
375
|
+
D --> E["Execute side-effect tool once"]
|
|
376
|
+
E --> F["BEGIN IMMEDIATE TRANSACTION"]
|
|
377
|
+
F --> G["UPDATE tool_ledger SET status='success/failed', result_json, updated_at_ms"]
|
|
378
|
+
G --> H["COMMIT"]
|
|
379
|
+
H --> I["Return fresh tool_result"]
|
|
380
|
+
|
|
381
|
+
C -->|"No (conflict)"| J["SELECT existing ledger row"]
|
|
382
|
+
J --> K{"status is success/failed?"}
|
|
383
|
+
K -->|"Yes"| L["Return stored result_json directly"]
|
|
384
|
+
K -->|"No (pending)"| M["Backoff + poll by key;若 pending 过期可抢占"]
|
|
385
|
+
M --> N{"Reached timeout?"}
|
|
386
|
+
N -->|"No"| J
|
|
387
|
+
N -->|"Yes"| O["Return retryable timeout error"]
|
|
388
|
+
```
|
|
389
|
+
|
|
390
|
+
### 9.2 两个并发请求竞争同一工具调用
|
|
391
|
+
|
|
392
|
+
```mermaid
|
|
393
|
+
sequenceDiagram
|
|
394
|
+
autonumber
|
|
395
|
+
participant W1 as Worker-1
|
|
396
|
+
participant W2 as Worker-2
|
|
397
|
+
participant DB as SQLite tool_ledger
|
|
398
|
+
participant Tool as Side-effect Tool
|
|
399
|
+
|
|
400
|
+
W1->>DB: BEGIN IMMEDIATE + INSERT (run_id,tool_call_id,status=pending,pending_expires_at_ms)
|
|
401
|
+
DB-->>W1: OK (winner)
|
|
402
|
+
|
|
403
|
+
W2->>DB: BEGIN IMMEDIATE + INSERT same key
|
|
404
|
+
DB-->>W2: UNIQUE CONFLICT
|
|
405
|
+
W2->>DB: SELECT by (run_id,tool_call_id)
|
|
406
|
+
DB-->>W2: status=pending
|
|
407
|
+
W2->>W2: backoff polling
|
|
408
|
+
|
|
409
|
+
W1->>Tool: execute()
|
|
410
|
+
Tool-->>W1: result/error
|
|
411
|
+
W1->>DB: UPDATE status=success/failed, result_json, updated_at_ms
|
|
412
|
+
DB-->>W1: committed
|
|
413
|
+
|
|
414
|
+
W2->>DB: SELECT by key (after backoff)
|
|
415
|
+
DB-->>W2: status=success/failed + result_json
|
|
416
|
+
W2-->>W2: return stored result (no second execution)
|
|
417
|
+
```
|
|
418
|
+
|
|
419
|
+
### 9.3 触发点 -> 动作 -> 写表(幂等专题)
|
|
420
|
+
|
|
421
|
+
| 场景 | 触发点 | 动作 | 写表 |
|
|
422
|
+
|---|---|---|---|
|
|
423
|
+
| 首次执行 | 未命中账本 | 插入 `pending + pending_expires_at_ms` 占位并成为执行者 | `tool_ledger` |
|
|
424
|
+
| 并发冲突 | 主键冲突 | 读取已有记录;若 `pending` 则轮询或按过期租约抢占 | `tool_ledger` |
|
|
425
|
+
| 执行成功 | 工具返回成功 | 更新状态为 `success` 并落结果 | `tool_ledger` |
|
|
426
|
+
| 执行失败 | 工具返回失败 | 更新状态为 `failed` 并落错误包 | `tool_ledger` |
|
|
427
|
+
| 读取复用 | 命中 `success/failed` | 直接返回已有 `result_json` | 仅读取 |
|
|
428
|
+
| 轮询超时 | 长时间 `pending` | 返回可重试错误并记日志 | `run_logs`(可选) |
|
|
429
|
+
|
|
430
|
+
### 9.4 与主流程的拼接点
|
|
431
|
+
|
|
432
|
+
```mermaid
|
|
433
|
+
flowchart LR
|
|
434
|
+
A["Stream event: tool_call"] --> B["IdempotentExecutor.executeOnce"]
|
|
435
|
+
B --> C{"winner?"}
|
|
436
|
+
C -->|"Yes"| D["真实执行工具 + 回写 ledger"]
|
|
437
|
+
C -->|"No"| E["读取/等待 ledger 结果"]
|
|
438
|
+
D --> F["Emit tool_result event"]
|
|
439
|
+
E --> F
|
|
440
|
+
F --> G["EventStore.append + MessageProjection.upsert"]
|
|
441
|
+
```
|
|
442
|
+
|
|
443
|
+
---
|
|
444
|
+
|
|
445
|
+
## 10. 终态分流与 CLI 输出策略
|
|
446
|
+
|
|
447
|
+
### 10.1 终态分流(`done/error` -> 状态/退出码/展示)
|
|
448
|
+
|
|
449
|
+
```mermaid
|
|
450
|
+
flowchart TD
|
|
451
|
+
A["Receive terminal stream event"] --> A1["INSERT events(type=done/error)"]
|
|
452
|
+
A1 --> B{"event.type"}
|
|
453
|
+
|
|
454
|
+
B -->|"done"| C{"finishReason"}
|
|
455
|
+
C -->|"stop"| C1["status=COMPLETED terminalReason=stop exit=0"]
|
|
456
|
+
C -->|"max_steps"| C2["status=COMPLETED terminalReason=max_steps exit=0 + show budget hint"]
|
|
457
|
+
|
|
458
|
+
B -->|"error"| D{"errorCode"}
|
|
459
|
+
D -->|"AGENT_ABORTED"| D1["status=CANCELLED terminalReason=aborted exit=130"]
|
|
460
|
+
D -->|"AGENT_TIMEOUT_BUDGET_EXCEEDED"| D2["status=FAILED terminalReason=timeout exit=1"]
|
|
461
|
+
D -->|"AGENT_MAX_RETRIES_REACHED"| D3["status=FAILED terminalReason=max_retries exit=1"]
|
|
462
|
+
D -->|"other"| D4["status=FAILED terminalReason=error exit=1"]
|
|
463
|
+
|
|
464
|
+
C1 --> E["UPDATE runs terminal fields + completed_at"]
|
|
465
|
+
C2 --> E
|
|
466
|
+
D1 --> E
|
|
467
|
+
D2 --> E
|
|
468
|
+
D3 --> E
|
|
469
|
+
D4 --> E
|
|
470
|
+
|
|
471
|
+
E --> G{"need log?"}
|
|
472
|
+
G -->|"warn/error or sampled info"| H["INSERT run_logs"]
|
|
473
|
+
G -->|"no"| I["skip run_logs"]
|
|
474
|
+
H --> J["Render final summary and exit"]
|
|
475
|
+
I --> J
|
|
476
|
+
```
|
|
477
|
+
|
|
478
|
+
### 10.2 用户中断(SIGINT)路径
|
|
479
|
+
|
|
480
|
+
```mermaid
|
|
481
|
+
sequenceDiagram
|
|
482
|
+
autonumber
|
|
483
|
+
actor User
|
|
484
|
+
participant CLI as CLI
|
|
485
|
+
participant Orch as RunOrchestrator
|
|
486
|
+
participant Agent as StatelessAgent
|
|
487
|
+
participant DB as SQLite(agent.db)
|
|
488
|
+
|
|
489
|
+
User->>CLI: Ctrl+C (SIGINT)
|
|
490
|
+
CLI->>Orch: requestAbort(executionId)
|
|
491
|
+
Orch->>Agent: abort signal
|
|
492
|
+
Agent-->>Orch: error(errorCode=AGENT_ABORTED)
|
|
493
|
+
Orch->>DB: INSERT events(type=error,payload_json)
|
|
494
|
+
Orch->>DB: UPDATE runs(status=CANCELLED,terminal_reason=aborted,completed_at)
|
|
495
|
+
Orch->>DB: INSERT run_logs(level=warn,code=AGENT_ABORTED)
|
|
496
|
+
Orch-->>CLI: terminal result(cancelled)
|
|
497
|
+
CLI-->>User: 输出取消摘要 + exit 130
|
|
498
|
+
```
|
|
499
|
+
|
|
500
|
+
### 10.3 终态输出矩阵(速查)
|
|
501
|
+
|
|
502
|
+
| 终态来源 | status | terminalReason | CLI 退出码 | 用户可见提示 |
|
|
503
|
+
|---|---|---|---|---|
|
|
504
|
+
| `done.stop` | `COMPLETED` | `stop` | `0` | 正常完成 |
|
|
505
|
+
| `done.max_steps` | `COMPLETED` | `max_steps` | `0` | 达到步数上限(建议 `resume`) |
|
|
506
|
+
| `error.AGENT_ABORTED` | `CANCELLED` | `aborted` | `130` | 用户中断或上层取消 |
|
|
507
|
+
| `error.AGENT_TIMEOUT_BUDGET_EXCEEDED` | `FAILED` | `timeout` | `1` | 预算超时(可重试) |
|
|
508
|
+
| `error.AGENT_MAX_RETRIES_REACHED` | `FAILED` | `max_retries` | `1` | 达到重试上限(建议检查工具/网络) |
|
|
509
|
+
| `error.*` | `FAILED` | `error` | `1` | 未分类失败(查看 `errorCode`) |
|
|
510
|
+
|
|
511
|
+
---
|
|
512
|
+
|
|
513
|
+
## 11. 查询命令流程(`run-status` / `run-list`)
|
|
514
|
+
|
|
515
|
+
说明:
|
|
516
|
+
- 两个命令是**只读路径**,不写 `events/messages/runs`。
|
|
517
|
+
- 默认直接查投影表(`runs`),`--verbose` 再补查 `execution_steps/events`。
|
|
518
|
+
|
|
519
|
+
### 11.1 `agent run-status --execution <id>`
|
|
520
|
+
|
|
521
|
+
```mermaid
|
|
522
|
+
flowchart TD
|
|
523
|
+
A["CLI receive run-status"] --> B["Parse args + validate executionId"]
|
|
524
|
+
B --> C["SELECT * FROM runs WHERE run_id=?"]
|
|
525
|
+
C --> D{"Found?"}
|
|
526
|
+
D -->|"No"| E["Render not found + exit 2"]
|
|
527
|
+
D -->|"Yes"| F["Render core fields(status,terminalReason,stepIndex,timestamps)"]
|
|
528
|
+
F --> G{"--verbose ?"}
|
|
529
|
+
G -->|"No"| H["Exit 0"]
|
|
530
|
+
G -->|"Yes"| I["SELECT execution_steps ORDER BY step_index DESC LIMIT N"]
|
|
531
|
+
I --> J["SELECT events ORDER BY seq DESC LIMIT M"]
|
|
532
|
+
J --> K["Render detail blocks + exit 0"]
|
|
533
|
+
```
|
|
534
|
+
|
|
535
|
+
### 11.2 `agent run-status --watch` 轮询路径
|
|
536
|
+
|
|
537
|
+
```mermaid
|
|
538
|
+
sequenceDiagram
|
|
539
|
+
autonumber
|
|
540
|
+
actor User
|
|
541
|
+
participant CLI as CLI
|
|
542
|
+
participant DB as SQLite(agent.db)
|
|
543
|
+
|
|
544
|
+
User->>CLI: agent run-status --execution <id> --watch
|
|
545
|
+
loop 每 interval_ms
|
|
546
|
+
CLI->>DB: SELECT status,step_index,terminal_reason,updated_at_ms FROM runs WHERE run_id=?
|
|
547
|
+
DB-->>CLI: row
|
|
548
|
+
CLI-->>User: 刷新单行进度
|
|
549
|
+
alt status in completed/failed/cancelled
|
|
550
|
+
CLI-->>User: 输出终态摘要
|
|
551
|
+
CLI-->>User: 退出
|
|
552
|
+
end
|
|
553
|
+
end
|
|
554
|
+
```
|
|
555
|
+
|
|
556
|
+
### 11.3 `agent run-list --conversation <id>`
|
|
557
|
+
|
|
558
|
+
```mermaid
|
|
559
|
+
flowchart TD
|
|
560
|
+
A["CLI receive run-list"] --> B["Parse filters(status/limit/cursor)"]
|
|
561
|
+
B --> C["SELECT conversation exists?"]
|
|
562
|
+
C --> D{"Exists?"}
|
|
563
|
+
D -->|"No"| E["Render empty/not-found + exit 0"]
|
|
564
|
+
D -->|"Yes"| F["SELECT runs WHERE conversation_id=? AND status filter"]
|
|
565
|
+
F --> G["ORDER BY updated_at_ms DESC LIMIT page_size+1"]
|
|
566
|
+
G --> H{"Has more?"}
|
|
567
|
+
H -->|"Yes"| I["Build next_cursor from last row"]
|
|
568
|
+
H -->|"No"| J["next_cursor = null"]
|
|
569
|
+
I --> K["Render list rows + next_cursor"]
|
|
570
|
+
J --> K
|
|
571
|
+
K --> L{"--verbose ?"}
|
|
572
|
+
L -->|"No"| M["Exit 0"]
|
|
573
|
+
L -->|"Yes"| N["Batch SELECT latest step per run (execution_steps)"]
|
|
574
|
+
N --> O["Render enriched rows + exit 0"]
|
|
575
|
+
```
|
|
576
|
+
|
|
577
|
+
### 11.4 查询命令读表矩阵(速查)
|
|
578
|
+
|
|
579
|
+
| 命令 | 默认读取表 | `--verbose` 补充读取 | 写表 |
|
|
580
|
+
|---|---|---|---|
|
|
581
|
+
| `run-status` | `runs` | `execution_steps`, `events` | 无 |
|
|
582
|
+
| `run-status --watch` | `runs`(轮询) | - | 无 |
|
|
583
|
+
| `run-list` | `conversations`, `runs` | `execution_steps`(批量) | 无 |
|