Internal Design Deep Dive
This guide summarizes the internal architecture across the client and server packages for contributors modifying core behavior.
1. Startup & Composition Root (internal/cmd → internal/app)
- CLI Pre-Run (
internal/cmd/root.go):- Stateless commands (
version,help,completion,__complete) skip~/.aistinitialization completely. - All other commands run
state.EnsureRoot("")(0700dirs) andpreferences.Store.LoadOrInit()(ensuring~/.aist/preferences.jsonexists with inferredzhoren; skipped only whenaist lang <zh|en>is explicitly overwriting it). - Lightweight commands (
login,logout,whoami,lang) stop beforeapp.Newso they work offline and without an active login.
- Stateless commands (
- Application Wiring (
internal/app/app.go):- Ensures
*state.Root, loadspreferences.Data, refreshes auth viaaccount.Startup(ctx)(POST /api/collections/users/auth-refresh), mapsremote.AccountConfig→config.Settings, normalizes/validates, and constructsi18n,llm.ServerModel,memory.Manager,prompt.Builder,commandguard.Guard,fileedit.Editor,executor.CommandRouter, andsession.Repository.
- Ensures
2. Prompt Layering (internal/prompt & internal/tools)
- English Base Instructions + Dynamic Reply Language: All static system prompts (
Interactive,PipeAnalysis,Compaction,FollowUpLimit), tool schemas, and tool result headers (Status,Target,Exit Code,Detail) are authored in English for cross-model instruction stability.prompt.Builderappends the explicit reply-language directive (Chinese (Simplified)vsEnglish) frompreferences.jsonontoInteractiveandPipeAnalysisprompts (Compactionstays pure English). - Context Placeholders:
: replaced bymemory.CatalogProvider.PromptBlock()(up to32 KiBofName,Type,Summary,Modified; full entry text is fetched on demand viamemory_search).: replaced by<command_blacklist>(up to4 KiBwhen non-empty; zero token overhead when empty).
3. Session Model, Token Estimation & Compaction (internal/session)
- Language-Neutral Persistence:
messages.jsonlstoresToolOutcome(success/failed/skipped/rejected) and raw tool call JSON;tools.DecodeInvocation+i18nrender historical tool lines dynamically in the active language duringaist sessionsreplay. - Protocol Repair: Before every model call,
ModelMessages()pairsassistant.tool_callswithrole=toolresponses (synthesizing placeholder tool messages if interrupted mid-batch, dropping orphan/duplicate tool messages, and merging adjacent user messages). - Heuristic Token Estimator: Estimates tokens without bundling large tokenizer tables by classifying messages into natural vs structured text (
>= 25%symbol ratio or tool payloads) with per-character weights (ASCII letters, digits, punctuation, CJK), anchored to the latest upstreamusage.total_tokens(TokenAnchor). - Turn-Boundary Compaction (
planner.go): Groups messages by realuserturns, protects leadingsystemmessages and trailing turns up tokeep_tokens(always keeping the latest turn), summarizes middle turns into<compressed_history priority="high">, and records acompactionevent inmessages.jsonl.
4. Tool Result Prefix-First Format & Server Audit (internal/interactive → internal/server/audit.go)
- Client
renderToolResultplaces short structured metadata lines (Status,Target,Exit Code,Error,Command/Path/Sudo,Detail) before[Output]. - On
POST /v1/proxy/chat/completions,recordToolAuditinspects onlyrole=toolmessages after the finalassistantmessage, pairs them bytool_call_id, truncates UTF-8 prefixes per field (result6000 B,command/old/new4000 B), and enforces a14 KBserialized JSON ceiling (limitAuditAttrs) so PocketBase's16 KBMaxDataSizenever drops alphabetically trailing keys liketype,tool, oruserIP.
5. Server Candidate Routing (internal/server/proxy.go & model_availability.go)
- Authenticates user via PocketBase
apis.RequireAuth("users")(e.Auth). - Records tool audit logs once before candidate retries.
- Enforces
weekly_token_quotaagainst UTC Monday00:00sum indaily_model_usage. - Loads enabled
allowed_modelswhose parentupstream_providersare enabled, sorted by(priority ASC, provider ASC, model ASC), skipping models blocked byauthor activeunavailable_until > now. - Clamps
max_tokensper candidate, forwards upstream, classifies errors (quota,rate_limit,auth,400,5xx), updates cooldown state or clears expired cooldowns on2xx, and atomically incrementsdaily_model_usage.