mirror of
https://github.com/tiennm99/goclaw.git
synced 2026-10-14 14:17:40 +00:00
docs: final consistency sweep and normalization
- Fix prose body citation in 15-core-skills-system (removed :410 line ref) - Normalize File Reference schema in 08-scheduling-cron and 10-tracing-observability to Module/Path/Purpose format - Add missing hint line to 03-tools-system File Reference section - Clean Go method-call symbols from 01-agent-loop Mermaid diagrams (Router + Resolver)
This commit is contained in:
viettranx committed
1 parent
b6a7e7d754
commit
7f7cf99da1
5 files changed
+26
-56
No files matched your search
@@ -560,11 +560,11 @@ The Agent Router manages Loop instances with a cache layer. It supports lazy res
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
GET["Router.Get(agentID)"] --> CACHE{"Cache hit<br/>and TTL valid?"}
|
||||
GET["Router: get agent"] --> CACHE{"Cache hit<br/>and TTL valid?"}
|
||||
CACHE -->|Yes| RETURN[Return cached Loop]
|
||||
CACHE -->|No or Expired| RESOLVE{"Resolver configured?"}
|
||||
RESOLVE -->|No| ERR["Error: agent not found"]
|
||||
RESOLVE -->|Yes| DB["Resolver.Resolve(agentID)<br/>Load from DB, create Loop"]
|
||||
RESOLVE -->|Yes| DB["Resolver: load from DB, create Loop"]
|
||||
DB --> STORE[Store in cache with TTL]
|
||||
STORE --> RETURN
|
||||
```
|
||||
@@ -589,12 +589,12 @@ The Resolver lazy-creates Loop instances from PostgreSQL data when the Router en
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
MISS["Router cache miss"] --> LOAD["Step 1: Load agent from DB<br/>AgentStore.GetByKey(agentKey)"]
|
||||
LOAD --> PROV["Step 2: Resolve provider<br/>ProviderRegistry.Get(provider)<br/>Fallback: first provider in registry"]
|
||||
PROV --> BOOT["Step 3: Load bootstrap files<br/>bootstrap.LoadFromStore(agentID)"]
|
||||
BOOT --> DEFAULTS["Step 4: Apply defaults<br/>contextWindow <= 0 then 200K<br/>maxIterations <= 0 then 20"]
|
||||
DEFAULTS --> CREATE["Step 5: Create Loop<br/>NewLoop(LoopConfig)"]
|
||||
CREATE --> WIRE["Step 6: Wire hooks<br/>EnsureUserFilesFunc, ContextFileLoaderFunc"]
|
||||
MISS["Router cache miss"] --> LOAD["Step 1: Load agent from DB"]
|
||||
LOAD --> PROV["Step 2: Resolve provider<br/>Fallback: first provider in registry"]
|
||||
PROV --> BOOT["Step 3: Load bootstrap files from store"]
|
||||
BOOT --> DEFAULTS["Step 4: Apply defaults<br/>contextWindow: 200K, maxIterations: 20"]
|
||||
DEFAULTS --> CREATE["Step 5: Create Loop with resolved config"]
|
||||
CREATE --> WIRE["Step 6: Wire hooks<br/>(user files, context file loader)"]
|
||||
WIRE --> DONE["Return Loop to Router for caching"]
|
||||
```
|
||||
|
||||
|
||||
@@ -517,3 +517,5 @@ Subagents share the same `SecureCLIStore` as their parent — the credentialed b
|
||||
| MCP bridge | `internal/mcp/` | MCP server connections, tool bridge, access grants |
|
||||
| Custom tools | `internal/tools/` (`dynamic_loader.go`, `dynamic_tool.go`) | Runtime shell-based custom tool loading and execution |
|
||||
| Team tools | `internal/tools/` (`team_tasks_tool.go`, `team_tool_*.go`) | Task board backend, team tool dispatch and cache |
|
||||
|
||||
Use `grep` or your editor's symbol search for specific files.
|
||||
@@ -204,40 +204,14 @@ Both jobs run with 5-minute timeout and tenant-scoped context. Failed analyses l
|
||||
|
||||
## File Reference
|
||||
|
||||
### Scheduler (Lane-Based Concurrency)
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| `internal/scheduler/lanes.go` | Lane and LaneManager (semaphore-based worker pools) |
|
||||
| `internal/scheduler/queue.go` | SessionQueue, Scheduler, drop policies, debounce, cancel mechanics |
|
||||
| `internal/scheduler/scheduler.go` | Scheduler top-level API, draining mode for graceful shutdown |
|
||||
| `internal/scheduler/errors.go` | Error types: ErrQueueFull, ErrQueueDropped, ErrMessageStale, ErrGatewayDraining, ErrLaneCleared |
|
||||
| Module | Path | Purpose |
|
||||
|---|---|---|
|
||||
| Scheduler | `internal/scheduler/` | Lane-based concurrency (lanes, queue, drop policies, debounce, cancel, draining) |
|
||||
| Cron service | `internal/cron/` | In-memory run loop (1s tick), job CRUD, retry with backoff, schedule parsing, types |
|
||||
| Cron store | `internal/store/pg/cron*.go`, `internal/store/cron_store.go` | CronStore interface + PostgreSQL persistence (create, list, update, delete, execution, scanning) |
|
||||
| Gateway wiring | `cmd/gateway_cron.go`, `internal/gateway/methods/cron.go` | Scheduler lane routing, RPC handlers (list, create, update, delete, toggle, run, runs) |
|
||||
|
||||
### Cron Service (In-Memory)
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| `internal/cron/service.go` | Cron service lifecycle (start/stop), job CRUD |
|
||||
| `internal/cron/service_execution.go` | Run loop (every 1s), job execution, schedule parsing, persistence |
|
||||
| `internal/cron/retry.go` | Retry with exponential backoff + jitter, output truncation |
|
||||
| `internal/cron/types.go` | Job, Schedule, JobState, RunLogEntry types |
|
||||
|
||||
### Cron Persistence (PostgreSQL)
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| `internal/store/cron_store.go` | CronStore interface (jobs + run logs) |
|
||||
| `internal/store/pg/cron.go` | PostgreSQL cron operations (create, list, update, delete) |
|
||||
| `internal/store/pg/cron_crud.go` | CRUD helpers for job mutations |
|
||||
| `internal/store/pg/cron_scheduler.go` | PG job cache, due-job detection, execution |
|
||||
| `internal/store/pg/cron_exec.go` | Execution flow and result recording |
|
||||
| `internal/store/pg/cron_scan.go` | Row scanning for jobs and run logs |
|
||||
| `internal/store/pg/cron_update.go` | Job state updates in PostgreSQL |
|
||||
|
||||
### Gateway Integration
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| `cmd/gateway_cron.go` | makeCronJobHandler (routes cron execution to scheduler) |
|
||||
| `cmd/gateway_evolution_cron.go` | Evolution daily/weekly background jobs (v3 suggestion analysis + rollback evaluation) |
|
||||
| `cmd/gateway_agents.go` | Agent initialization and run loop setup |
|
||||
| `internal/gateway/methods/cron.go` | RPC method handlers (list, create, update, delete, toggle, run, runs) |
|
||||
Use `grep` or your editor's symbol search for specific files.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -218,20 +218,14 @@ Delegation history is automatically recorded by `DelegateManager.saveDelegationH
|
||||
|
||||
## File Reference
|
||||
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| `internal/tracing/collector.go` | Collector buffer-flush, EmitSpan, FinishTrace, verbose mode |
|
||||
| `internal/tracing/context.go` | Trace context propagation (TraceID, ParentSpanID, DelegateParentTraceID) |
|
||||
| `internal/tracing/cost.go` | Cost calculation and pricing lookup |
|
||||
| `internal/tracing/snapshot_worker.go` | Hourly usage aggregation into snapshots |
|
||||
| `internal/tracing/otelexport/exporter.go` | OTel OTLP exporter (gRPC + HTTP) |
|
||||
| `internal/store/tracing_store.go` | TracingStore interface, span/trace type constants |
|
||||
| `internal/store/pg/tracing.go` | PostgreSQL trace/span persistence + aggregation |
|
||||
| `internal/http/traces.go` | Trace HTTP API handler (GET /v1/traces) |
|
||||
| `internal/agent/loop_tracing.go` | Span emission from agent loop (LLM, tool, agent spans) |
|
||||
| `internal/http/delegations.go` | Delegation history HTTP API handler |
|
||||
| `internal/gateway/methods/delegations.go` | Delegation history RPC handlers |
|
||||
| `internal/pipeline/` | v3 agent loop pipeline (stages route to agent loop for span emission) |
|
||||
| Module | Path | Purpose |
|
||||
|---|---|---|
|
||||
| Tracing engine | `internal/tracing/` | Collector (buffer-flush, EmitSpan, FinishTrace), context propagation, cost calculation, OTel OTLP exporter |
|
||||
| Store & snapshots | `internal/store/tracing_store.go`, `internal/store/pg/tracing.go`, `internal/tracing/snapshot_worker.go` | TracingStore interface, PostgreSQL persistence + aggregation, hourly usage snapshots |
|
||||
| Agent & pipeline integration | `internal/agent/loop_tracing.go`, `internal/pipeline/` | Span emission from agent loop (LLM, tool, agent spans), pipeline stage tracing |
|
||||
| HTTP & RPC handlers | `internal/http/traces.go`, `internal/http/delegations.go`, `internal/gateway/methods/delegations.go` | GET /v1/traces, delegation history HTTP + RPC handlers |
|
||||
|
||||
Use `grep` or your editor's symbol search for specific files.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -124,7 +124,7 @@ Supported frontmatter fields:
|
||||
|
||||
## 5. Hash-Based Change Detection (UpsertSystemSkill)
|
||||
|
||||
`UpsertSystemSkill` (`internal/store/pg/skills.go:410`) prevents unnecessary DB version bumps:
|
||||
`UpsertSystemSkill` (`internal/store/pg/`) prevents unnecessary DB version bumps:
|
||||
|
||||
```
|
||||
SELECT id, file_hash, file_path FROM skills WHERE slug = $1
|
||||
|
||||
Reference in new issue
Block a user