系统架构设计

async function agentLoop(input: string, session: Session): Promise<void> {
  const context = contextManager.build(session, input);
  permission.checkInput(input);

  while (true) {
    const response = await queryEngine.stream({
      model: session.config.model,
      messages: context.messages,
      tools: toolRegistry.getSchemas(),
    });

    if (response.type === 'text') {
      output.print(response.content);
      session.addMessage({ role: 'assistant', content: response.content });
      break;
    }

    if (response.type === 'tool_use') {
      for (const toolCall of response.toolCalls) {
        const result = await dispatcher.execute(toolCall, session);
        context.addToolResult(toolCall.id, result);
      }
      // 继续循环，把 tool result 回传给模型
    }
  }

  sessionManager.save(session);
}

interface LLMProvider {
  name: string;
  stream(params: StreamParams): AsyncIterable<StreamChunk>;
  countTokens(messages: Message[]): number;
}

interface StreamParams {
  model: string;
  messages: Message[];
  tools?: ToolSchema[];
  maxTokens?: number;
  temperature?: number;
}

type StreamChunk =
  | { type: 'text_delta'; content: string }
  | { type: 'tool_use_start'; id: string; name: string }
  | { type: 'tool_use_delta'; input: string }
  | { type: 'tool_use_end' }
  | { type: 'message_end'; usage: TokenUsage };

interface Tool<TInput, TOutput> {
  name: string;
  description: string;
  schema: JSONSchema;        // 参数的 JSON Schema
  execute(input: TInput, ctx: ToolContext): Promise<TOutput>;
}

interface ToolContext {
  session: Session;
  permission: PermissionGate;
  hooks: HookPipeline;
  abortSignal: AbortSignal;
}

class ToolRegistry {
  private tools = new Map<string, Tool>();

  register(tool: Tool): void;
  getSchemas(): ToolSchema[];           // 给 LLM 的 tool 列表
  resolve(name: string): Tool;          // 按名称找 tool
  list(): ToolMetadata[];               // 列出所有 tool（不含实现）
}

async function dispatch(toolCall: ToolCall, session: Session): Promise<ToolResult> {
  const tool = registry.resolve(toolCall.name);

  // 1. Pre-tool hooks
  await hooks.runPre(toolCall, session);

  // 2. Permission check
  permission.checkTool(toolCall);

  // 3. Execute
  const result = await tool.execute(toolCall.input, {
    session, permission, hooks, abortSignal: session.abortController.signal
  });

  // 4. Post-tool hooks
  await hooks.runPost(toolCall, result, session);

  return { toolCallId: toolCall.id, content: JSON.stringify(result) };
}

interface ContextManager {
  build(session: Session, input: string): ContextWindow;
  addToolResult(id: string, result: ToolResult): void;
  compact(): void;            // 手动触发压缩
  autoCompact(): void;        // 接近 token 上限时自动压缩
  getTokenCount(): number;
  getBudget(): TokenBudget;
}

interface ContextWindow {
  messages: Message[];
  systemPrompt: string;
  tokenCount: number;
  maxTokens: number;
}

interface MemoryStore {
  create(type: MemoryType, key: string, value: unknown): void;
  retrieve(query: string, opts?: { type?: MemoryType; limit?: number }): Memory[];
  update(id: string, value: unknown): void;
  delete(id: string): void;
  getProfile(): UserProfile;
  updateProfile(patch: Partial<UserProfile>): void;
}

type RiskLevel = 'low' | 'medium' | 'high' | 'critical';

interface PermissionRule {
  pattern: string | RegExp;   // 匹配 tool name 或参数
  level: RiskLevel;
  action: 'allow' | 'confirm' | 'deny';
  reason: string;
}

interface PermissionGate {
  checkTool(toolCall: ToolCall): Promise<PermissionResult>;
  checkInput(input: string): void;
  addRule(rule: PermissionRule): void;
  getRules(): PermissionRule[];
}

// confirm 时调用 human-in-the-loop
interface PermissionResult {
  allowed: boolean;
  reason?: string;
  confirmedBy?: 'rule' | 'user';
}

type HookTiming = 'pre-tool' | 'post-tool';

interface Hook {
  name: string;
  timing: HookTiming;
  priority: number;           // 越小越先执行
  execute(ctx: HookContext): Promise<void>;
}

interface HookContext {
  toolCall: ToolCall;
  result?: ToolResult;        // post-tool 才有
  session: Session;
  metadata: Record<string, unknown>;  // hook 间传递数据
}

class HookPipeline {
  register(hook: Hook): void;
  async runPre(toolCall: ToolCall, session: Session): Promise<void>;
  async runPost(toolCall: ToolCall, result: ToolResult, session: Session): Promise<void>;
}

interface Command {
  name: string;
  aliases?: string[];
  description: string;
  args?: ArgumentSchema[];
  execute(args: ParsedArgs, session: Session): Promise<void>;
}

class CommandParser {
  register(cmd: Command): void;
  parse(input: string): { command: Command; args: ParsedArgs } | null;
  isCommand(input: string): boolean;  // 以 / 开头
  listCommands(): CommandMetadata[];
}

interface SubAgent {
  id: string;
  name: string;
  tools: string[];            // 该子 agent 可用的 tool 名称
  systemPrompt: string;       // 子 agent 专属 system prompt
  contextBoundary: string[];  // 传入的上下文字段
}

interface Orchestrator {
  spawn(agent: SubAgent, input: string): Promise<AgentResult>;
  parallel(agents: SubAgent[], inputs: string[]): Promise<AgentResult[]>;
  aggregate(results: AgentResult[]): DiagnosisReport;
}