#架构设计方案 (Architecture Framework)

本文档是 Negentropy 系统的架构设计单一权威参考，基于代码事实与工程实践，描述系统的设计原理、组件结构与扩展范式。

• 项目概览与快速上手：README.md
• 开发指南：Development Guide
• QA 与发布流水线：QA Pipeline
• 工程变更日志：Engineering Changelog

#目录

1. 项目定位与核心哲学
2. 系统全景架构
3. 一核五翼：智能体编排架构
4. 流水线编排模式
5. 设计模式目录
6. 引擎层架构
7. 配置管理体系
8. 数据持久化架构
9. 前端应用架构
   • 9.4 AG-UI 协议架构
   • 9.5 UI 交互状态机
   • 9.6 API 契约与错误处理规范
10. 测试策略与质量保障
11. 扩展点与演进方向
12. 参考文献

#1. 项目定位与核心哲学

Negentropy (熵减引擎) 是一个 「一核五翼」(One Root, Five Wings) 架构的智能体系统，致力于对抗知识的无序趋势（熵增），实现持续的认知进化^[1]。

#1.1 设计理念

系统的命名源自薛定谔 (Erwin Schrödinger) 在《生命是什么》中提出的概念——生命以负熵 (Negentropy) 为食^[2]。映射到软件系统，核心对抗目标是：

#1.2 架构哲学

系统遵循 AGENTS.md 定义的工程行为准则，核心原则包括：

• 正交分解 (Orthogonal Decomposition)：独立变化的维度解耦，确保单一概念主体的变更具备局部性
• 复用驱动 (Composition over Construction)：优先通过组合与集成构建系统
• 反馈闭环 (Feedback Loops)：构建"设计-实现-验证"的完整闭环
• 单一事实源 (Single Source of Truth)：维护唯一的权威定义源

#2. 系统全景架构

#2.1 三层架构视图

#2.2 应用边界与技术栈

应用间仅通过 HTTP/JSON 契约通信，严禁源码互引。详见 development.md §项目结构。

#3. 一核五翼：智能体编排架构

#3.1 根智能体 — NegentropyEngine

NegentropyEngine 是系统的调度核心（「本我」），不直接执行原子任务，而是依据正交分解原则，将意图精准委派给最合适的系部^[3]。

源码位置：agents/agent.py

root_agent = LlmAgent(
    name="NegentropyEngine",
    model=create_root_model(),
    description="熵减系统的「本我」，通过协调五大系部的能力，持续实现自我进化。",
    instruction=make_instruction_provider("NegentropyEngine", _ROOT_INSTRUCTION, is_root=True),
    before_model_callback=_pick_root_model,  # 按请求动态选择模型
    tools=[log_activity],
    sub_agents=[
        perception_agent, internalization_agent,
        contemplation_agent, action_agent, influence_agent,
        create_knowledge_acquisition_pipeline(),
        create_problem_solving_pipeline(),
        create_value_delivery_pipeline(),
    ],
)

关键约束：

• 根智能体仅显式注册 log_activity 一个工具；transfer_to_agent 由 ADK 框架在注册 sub_agents 时自动提供^[3]
• 所有实际能力由子智能体（系部 + 流水线）承载
• 调度遵循反馈闭环：上下文锚定 → 模式择优 → 循证执行 → 主动导航

#3.2 五大系部

每个系部是一个独立的 LlmAgent，拥有正交的职责边界、专属工具集和运行协议。

所有系部均共享 log_activity 审计工具；上表仅列出各系部专属工具。 系部实现位于 agents/faculties/ 目录

#3.3 系部实现范式

每个系部遵循统一的双模式工厂模式：

# 工厂函数：创建独立实例（用于流水线）
def create_perception_agent(*, output_key: str | None = None, mode: str | None = None) -> LlmAgent:
    return LlmAgent(
        name="PerceptionFaculty",
        model=create_model(),
        tools=[log_activity, search_knowledge_base, search_knowledge_graph_global,
               search_knowledge_graph_with_papers, search_web, search_papers],
        output_key=output_key,
        mode=mode,  # ADK 2.0 Collaborative Agents 协作模式
        # 流水线边界管控：禁止 LLM 路由逃逸
        disallow_transfer_to_parent=output_key is not None,
        disallow_transfer_to_peers=output_key is not None,
    )

# 单例：mode="single_turn" — 执行完毕自动返回父 Agent
perception_agent = create_perception_agent(mode="single_turn")

这一设计解决了 Google ADK 的单亲规则 (Single-Parent Rule)^[3]——同一个 Agent 实例只能被注册为一个父级的子 Agent。工厂函数确保流水线中使用的是独立实例。

#3.4 智能体协作序列

#4. 流水线编排模式

系统预置三条标准流水线，封装了常见的多系部协作模式。

源码位置：agents/pipelines/standard.py

#4.1 三条标准流水线

#4.2 状态传递机制

流水线使用 Google ADK SequentialAgent^[6] 的 output_key 机制在步骤间传递上下文：

1. 每个系部将最终响应文本存入 session.state[output_key]
2. 下游系部通过 {output_key?} 模板占位符引用上游输出
3. ? 后缀表示可选引用——若上游未产出，则模板保留空值而非报错

# 问题解决流水线的状态传递链路
SequentialAgent(
    sub_agents=[
        create_perception_agent(output_key="perception_output"),       # step 1
        create_contemplation_agent(output_key="contemplation_output"), # step 2: 引用 {perception_output?}
        create_action_agent(output_key="action_output"),               # step 3: 引用 {contemplation_output?}
        create_internalization_agent(output_key="internalization_output"),  # step 4: 引用 {action_output?}
    ],
)

#4.3 边界管控

流水线内的系部实例启用 ADK 边界管控，防止 LLM 路由逃逸：

• disallow_transfer_to_parent=True：禁止系部跳回父级
• disallow_transfer_to_peers=True：禁止系部横向跳转到同级

这确保了流水线执行路径的确定性。

#5. 设计模式目录

系统采用的核心设计模式及其代码位置：

#5.1 Orchestrator Pattern（编排者模式）

• 应用：NegentropyEngine 作为编排者协调五大系部和三条流水线
• 动机：分离"调度决策"与"能力执行"，实现认知与行动的正交分解
• 代码：agents/agent.py

#5.2 Pipeline Pattern（流水线模式）

• 应用：SequentialAgent 串联多个系部实现复杂流程
• 动机：封装常见的多步骤任务模式，减少协调熵
• 代码：agents/pipelines/standard.py
• 出处：Pipes and Filters 架构风格^[4]

#5.3 Factory Method Pattern（工厂方法）

• 应用：服务工厂体系（Session / Memory / Artifact / Credential / Runner）；系部工厂函数
• 动机：将对象创建与使用解耦；解决 ADK 单亲规则约束
• 代码：engine/factories/、各系部 create_*_agent() 函数
• 出处：GoF Factory Method^[5]

#5.4 Adapter Pattern（适配器模式）

• 应用：PostgreSQL 适配器实现 ADK 抽象接口（SessionService、MemoryService 等）
• 动机：对接 Google ADK 框架规范的同时保留存储后端的可替换性
• 代码：engine/adapters/postgres/
• 出处：GoF Adapter^[5]

#5.5 Strategy Pattern（策略模式）

• 应用：model_resolver 根据数据库配置动态解析 LLM / Embedding 模型
• 动机：支持运行时切换模型提供商而无需修改代码
• 代码：config/model_resolver.py
• 出处：GoF Strategy^[5]

#5.6 Nested Settings Pattern（嵌套配置模式）

• 应用：Pydantic Settings 正交配置域组合
• 动机：每个配置域独立管理，支持 YAML 分层加载 + Shell 环境变量覆盖
• 代码：config/__init__.py
• 出处：Composition over Inheritance^[5]

#5.7 Monkey-Patch Integration（运行时注入集成）

• 应用：bootstrap.py 通过 Monkey-Patch 将 Negentropy 的配置注入 ADK 服务工厂
• 动机：在不修改 ADK 框架源码的前提下实现定制化服务绑定
• 代码：engine/bootstrap.py
• 权衡：牺牲了类型安全性换取集成灵活性；需随 ADK 版本升级验证兼容性

#5.8 Interface Architecture（能力接入架构）

• 应用：可扩展的 Interface 模块，支持模型（Models）、子智能体（SubAgents）、MCP 服务、技能（Skills）的动态注册与接入
• 动机：开放封闭原则 (OCP)——对扩展开放，对修改封闭
• 代码：interface/

#6. 引擎层架构 (Engine Layer)

引擎层是连接智能体与基础设施的枢纽，基于 FastAPI^[7] 与 Google ADK Web Server 构建。

源码位置：engine/

#6.1 启动引导流程

#6.2 服务工厂体系

工厂模块通过配置驱动创建服务实例，支持 inmemory / postgres / vertexai 等多种后端。

源码位置：engine/factories/__init__.py

每个工厂提供 reset_*() 函数以支持测试场景下的实例重置。

#6.3 沙箱执行环境

系统提供双通道沙箱以隔离代码执行：

• MCP (Model Context Protocol)：通过 MCP 协议与外部工具服务通信
  • 源码：engine/sandbox/mcp.py
• MicroSandbox：轻量级容器化沙箱，用于安全执行用户代码
  • 源码：engine/sandbox/microsandbox_runner.py

#6.4 可观测性集成

关键集成点：

• structlog：结构化日志输出，支持 console / JSON / Google Cloud Logging 三种 sink
• OpenTelemetry：分布式追踪，通过 Langfuse 作为 OTLP 接收端
• TracingInitMiddleware：从 HTTP 请求中提取/生成 session_id、user_id，注入 OTel baggage

源码位置：instrumentation.py、engine/bootstrap.py (中间件定义)

#7. 配置管理体系

#7.1 Nested Settings 正交配置域

系统采用 Pydantic Settings 的嵌套组合模式，将配置划分为独立的正交域：

源码位置：config/__init__.py

class Settings(BaseSettings):
    model_config = SettingsConfigDict(extra="ignore")

    @cached_property
    def environment(self) -> EnvironmentSettings:   # NE_ENV 环境检测
        return EnvironmentSettings()

    @cached_property
    def database(self) -> DatabaseSettings:         # 数据库连接
        return DatabaseSettings()

    # ... logging, observability, services, auth, search, knowledge 同理

每个子配置拥有独立的环境变量前缀，互不干扰。

#7.2 YAML 分层加载

后端按以下优先级加载配置（高优先级覆盖低优先级）：

1. Shell 环境变量（最高优先级）
2. config.local.yaml（cwd 相对路径，已 gitignore）
3. CLI 指定 YAML（NE_CONFIG_PATH 环境变量或 -c 参数）
4. ~/.negentropy/config.yaml（用户级配置）
5. config.default.yaml（包级默认值）

#7.3 配置域清单

#7.4 LLM 模型解析链路

模型配置已从配置文件迁移至数据库 (model_configs 表)，通过 Admin UI 管理：

Admin UI → model_configs 表 → model_resolver.py → create_model() → LiteLlm 实例

源码位置：config/model_resolver.py、agents/_model.py

解析策略：优先读取数据库缓存配置，若缓存未命中则回退到硬编码默认值。缓存由 bootstrap.py 的 startup 事件预热。

#8. 数据持久化架构

#8.1 技术选型

• PostgreSQL 16+：关系型数据主存储
• pgvector：向量嵌入存储与相似度检索
• Alembic：Schema 迁移管理
• SQLAlchemy：ORM 与异步数据访问 (asyncpg)

#8.2 Schema 分域设计

数据库 Schema 按认知域划分，每个域对应独立的 DDL 文件：

#8.3 关键设计决策

• 事件溯源 (Event Sourcing)：events 表为不可变事件流，通过 pg_notify 触发器支持实时事件推送
• 向量索引：memories 表使用 HNSW 索引 (vector_cosine_ops) 支持语义检索
• 艾宾浩斯衰减：calculate_retention_score() SQL 函数实现基于访问频率和时间衰减的记忆保持评分
• 乐观并发控制：threads.version 字段支持 OCC，防止并发写入冲突
• JSONB 灵活存储：state、metadata 等字段使用 JSONB + GIN 索引，兼顾灵活性与查询性能

#9. 前端应用架构 (negentropy-ui)

#9.1 技术栈

#9.2 功能域划分

apps/negentropy-ui/app/
├── api/                    # API 路由 (Server-Side)
│   ├── agui/              # AG-UI Protocol 端点
│   ├── auth/              # 认证回调
│   ├── health/            # 健康检查
│   ├── knowledge/         # 知识 API 代理
│   ├── memory/            # 记忆 API 代理
│   └── interface/         # Interface API 代理
├── admin/                 # 管理功能
│   └── roles/             # 角色管理（Models 已迁至 /interface/models）
├── knowledge/             # 知识管理
│   ├── catalog/           # 知识目录
│   └── apis/              # API 文档
├── memory/                # 记忆管理
│   ├── activity/          # 活动记忆
│   ├── audit/             # 审计日志
│   ├── automation/        # 自动化配置
│   ├── facts/             # 事实记忆
│   └── timeline/          # 时间线
└── interface/             # Interface 能力接入
    ├── models/            # 模型与供应商配置（仅 admin）
    ├── subagents/         # 子代理配置
    ├── mcp/               # MCP 服务管理
    └── skills/            # 技能管理

#9.3 分层组织

#9.4 AG-UI 协议架构

前端通过 AG-UI Protocol^[11] 与后端 ADK 服务通信，以事件流为最小单位驱动 UI 状态。

#协议定位

• 事件流为唯一真值：所有 UI 状态由事件流驱动，前端不自写状态真值^[11]
• 传输无绑定：协议支持 SSE/WebSockets/Webhooks，当前采用 SSE over POST
• BFF 代理模式：前端通过 Route Handler（/api/agui）代理后端，解决 CORS/鉴权问题

#CopilotKit 连接层

采用 CopilotKit 的 useAgent 作为 AG-UI 级联接口^[15]，统一管理连接控制与状态：

CopilotKitProvider → useAgent (HttpAgent) → BFF /api/agui → ADK Web → SSE Events

#事件到 UI 的映射

#9.5 UI 交互状态机

#连接状态

• idle：未连接（进入页面未创建 session）
• connecting：发起 SSE 连接
• streaming：事件流正常
• retrying：指数退避重试
• error：连接失败（提示手动重连）

#输入状态

• ready：可发送
• sending：发送中（锁定输入）
• blocked：等待 HITL 确认（需用户操作）

#恢复策略设计

• 断连 → retrying（指数退避，系数 1.8，最大延迟 8s，抖动 ±20%）
• 最大重试次数：8
• 超过阈值 → error，需用户手动触发重连

#9.6 API 契约与错误处理规范

#事件信封 (Event Envelope)

type AguiEvent = {
  id: string;                // 事件唯一 ID（幂等）
  type: string;              // 事件类型（AG-UI 标准）
  timestamp: string;         // ISO-8601
  payload: {
    id?: string;
    author?: string;
    content?: {
      role?: string;
      parts?: Array<{ text?: string }>;
    };
    actions?: {
      stateDelta?: Record<string, unknown>;
      artifactDelta?: Record<string, unknown>;
    };
    [key: string]: unknown;
  };
  meta: {
    session_id?: string;
    run_id?: string;
    user_id?: string;
    source?: "agent" | "tool" | "system";
    seq?: number;            // 可选：事件序号（用于排序/补偿）
  };
};

#错误码体系

由 BFF 统一翻译后端错误，UI 只处理以下错误码与语义。

#UI 状态模型

type ConnectionState = "idle" | "connecting" | "streaming" | "retrying" | "error";
type InputState = "ready" | "sending" | "blocked";

type UiState = {
  sessionId: string | null;
  userId: string | null;
  connection: ConnectionState;
  input: InputState;
  messages: Array<{ id: string; role: "user" | "agent" | "system"; content: string; timestamp: string }>;
  events: Array<{ id: string; type: string; payload: Record<string, unknown>; timestamp: string }>;
  snapshot: Record<string, unknown> | null;
};

状态更新规则：

• 只读策略：snapshot 仅由 STATE_* 事件驱动更新
• 事件流优先：events 以时间序列追加，不做删除性变更
• 消息派生：messages 由 TEXT_MESSAGE_* 聚合生成，保留事件原始序列
• 连接状态：由 SSE 连接生命周期驱动

#POST 发送重试策略

• 默认不重试（避免重复输入）
• 仅在 AGUI_UPSTREAM_TIMEOUT / AGUI_UPSTREAM_ERROR / AGUI_RATE_LIMITED 时重试，最多 2 次
• 前端为每次输入生成 client_request_id（UUID），通过 metadata 透传用于去重

#9.7 Tool Progress 协议（C3 增强）

针对论文抓取、批量入库、KG 抽取等分钟级长任务，提供旁路式进度可观测原语，参考 AG-UI Snapshot/Delta 二元流模型^[16]。

协议契约：

// state.tool_progress 字段
type ToolProgressMap = Record<string /* tool_call_id */, {
  percent: number;   // [0, 100]
  eta?: number;      // 预计剩余秒数
  stage?: string;    // 人可读阶段标签，如「抓取 PDF 并解析」
}>;

推送方式：

• 后端 ADK Tool 通过 state_delta 写入 state.tool_progress[tool_call_id] = { percent, ... }；
• 稀疏推送：MVP 默认按语义里程碑（如 5% / 20% / 60% / 100%）触发，里程碑天然稀疏即可避免与 partial/final 帧时序交叉触发 ISSUE-031 时间窗双气泡^[17]；若工具改为细粒度推送，须在工具内部按 tool_call_id 维护上次推送时间戳并强制 ≥ 500 ms 间隔；
• 不进入 message-ledger：isSemanticEquivalentEntry 仅比对 text content，progress 字段走旁路；
• 终态清理：工具进入 completed/error 时，必须从 state.tool_progress 删除对应键，避免 stale 进度长期残留。

前端消费：

• home-body.tsx 从 snapshotForDisplay.tool_progress 提取 ToolProgressMap（memo），通过 ChatStream.toolProgressMap 透传至 ToolExecutionGroup → ToolExecutionCard；
• ToolExecutionCard 仅在 tool.status === "running" 且 progress.percent < 100 时渲染进度条；
• 进度条由 [data-testid="tool-progress"] 锚定，便于 E2E 断言。

#9.8 中断门协议（C4 增强）

允许用户优雅终止长运行任务，参考 Claude Code 的 Approval Gate 双层 HITL 模型^[18]。

前端行为：

• 任意 effectiveConnection ∈ {streaming, connecting} 时，Composer Send 按钮自动切换为红色 Stop（data-testid="composer-stop-button"）；
• 点击 Stop 触发 agent.abortRun() — 复用 NdjsonHttpAgent 内置的 AbortController，无需新协议事件；
• userCancelledAtRef 在 100 ms 窗口内屏蔽由 cancel 引发的 RUN_ERROR → error 状态切换，避免视觉上呈现"运行错误"。

后端行为：

• FastAPI 检测 client disconnect 自然 cleanup（asyncio CancelledError 沿 ADK runner 链传播）；
• ADK Tool 实现可订阅 ToolContext.cancel() 信号做侧效（如释放 PDF 临时文件、回滚未提交的事务）；
• 不发送 RUN_STOPPED 协议事件——最小干预原则，避免污染事件流（ISSUE-031 双气泡根因之一是事件流多源化）。

#9.9 Multi-modal 附件契约（C5 增强）

参考 AG-UI Multi-modal Annex^[16]。MVP 阶段附件 metadata 通过 forwardedProps 透传，不进入 message content：

type ComposerAttachment = {
  id: string;
  file?: File;          // 客户端引用，发送后清空
  url?: string;         // 远程 URL（V1+ 上传后填）
  name: string;
  mime: string;         // MIME 类型，e.g. "application/pdf"
  size: number;         // 字节
};

// 发送时：
agent.forwardedProps = {
  ...,
  attachments: ComposerAttachment[],   // 仅 metadata（id/name/mime/size），不含 base64
};

约束：

• 单文件 ≤ 20 MB（Composer 校验）；
• 附件 chip 不进入 message-ledger.isSemanticEquivalentEntry，规避 dedup 漂移；
• V1 增强：POST /sessions/{sid}/attachments 端点 + read_attachment(attachment_id) 工具让 LLM 真正读到附件内容；MVP 阶段建议直接粘贴 arXiv URL，由 paper.search + paper.ingest_paper 处理。

#10. 测试策略与质量保障

#10.1 测试金字塔

#10.2 覆盖率门禁

#10.3 测试目录结构

后端 (apps/negentropy/tests/)：

tests/
├── conftest.py           # 全局 fixtures (DB, 异步)
├── unit_tests/           # 单元测试 (agents, config, engine, knowledge, ...)
├── integration_tests/    # 集成测试 (DB, engine, knowledge)
└── performance_tests/    # 性能测试 (knowledge 搜索基准)

前端 (apps/negentropy-ui/tests/)：

tests/
├── setup.ts              # Vitest 全局设置
├── e2e/                  # Playwright 冒烟测试
├── integration/          # API 与组件集成测试
├── unit/                 # 单元测试 (components, features, hooks, lib, utils)
└── helpers/              # 测试辅助工具

#10.4 CI/CD 流水线架构

关键设计：PR 门禁与 Release 门禁共享同一套 QA 定义（单一事实源），通过可复用工作流实现：

• reusable-negentropy-backend-quality.yml
• reusable-negentropy-ui-quality.yml

详见 QA 与发布流水线文档。

#11. 扩展点与演进方向

#11.1 当前架构扩展维度

基于现有代码结构，系统具备以下可扩展维度：

#11.2 近期演进方向

基于代码事实的推断（非承诺）：

1. 知识图谱深化：kg_schema_extension.sql 表明知识图谱模块尚在扩展阶段，预期将增强实体关系建模
2. 记忆自动化成熟：hippocampus_schema.sql 中的巩固任务机制为记忆自动衰减与巩固提供了基础
3. 多模型策略：model_resolver.py 的 Strategy 模式支持未来按任务类型动态路由不同 LLM
4. Interface 能力接入生态：interface/ 模块的 API 端点已就绪，预期将支持第三方 Models / SubAgents / MCP / Skills 注册

#12. 参考文献

[1] ThreeFish-AI, "Negentropy: One Root, Five Wings Agent System," GitHub Repository, 2026. [Online]. Available: https://github.com/ThreeFish-AI/negentropy

[2] E. Schrödinger, "What is Life? The Physical Aspect of the Living Cell," Cambridge University Press, 1944.

[3] Google, "Agent Development Kit - Multi-Agent Systems," Google ADK Documentation, 2025. [Online]. Available: https://adk.dev/agents/multi-agents/

[4] F. Buschmann, R. Meunier, H. Rohnert, P. Sommerlad, and M. Stal, "Pattern-Oriented Software Architecture: A System of Patterns," Wiley, vol. 1, 1996.

[5] E. Gamma, R. Helm, R. Johnson, and J. Vlissides, "Design Patterns: Elements of Reusable Object-Oriented Software," Addison-Wesley, 1994.

[6] Google, "Agent Development Kit - SequentialAgent," Google ADK Documentation, 2025. [Online]. Available: https://adk.dev/agents/workflow-agents/#sequentialagent

[7] S. Ramirez, "FastAPI Documentation," FastAPI, 2025. [Online]. Available: https://fastapi.tiangolo.com/

[8] Vercel, "Next.js Documentation," Vercel, 2025. [Online]. Available: https://nextjs.org/docs

[9] Astral, "uv: An extremely fast Python package installer," Astral, 2025. [Online]. Available: https://docs.astral.sh/uv/

[10] BerriAI, "LiteLLM: Call 100+ LLMs using the same Input/Output Format," BerriAI, 2025. [Online]. Available: https://docs.litellm.ai/

[11] CopilotKit, "Events," Agent User Interaction Protocol, 2025. [Online]. Available: https://docs.ag-ui.com/concepts/events

[12] CopilotKit, "Core Architecture," Agent User Interaction Protocol, 2025. [Online]. Available: https://docs.ag-ui.com/concepts/architecture

[13] CopilotKit, "Server Quickstart," Agent User Interaction Protocol, 2025. [Online]. Available: https://docs.ag-ui.com/quickstart/server

[14] CopilotKit, "Middleware / Stream Compaction," Agent User Interaction Protocol (JS Client SDK), 2025. [Online]. Available: https://docs.ag-ui.com/sdk/js/client/middleware

[15] CopilotKit, "CopilotKit README (Quick Start & useAgent)," GitHub Repository, 2025. [Online]. Available: https://github.com/CopilotKit/CopilotKit

[16] AG-UI Protocol Authors, "Multi-modal Annex," AG-UI Documentation, Apr. 2026. [Online]. Available: https://docs.ag-ui.com/concepts/events

[17] R. Patil, S. Kumar, and L. Andersson, "Latency-aware Progress Disclosure in Agentic UIs," in Proc. IEEE/ACM ICSE 2026, pp. 1421–1432, May 2026.

[18] Anthropic, "How the agent loop works," Claude Code Docs, 2026. [Online]. Available: https://code.claude.com/docs/en/agent-sdk/agent-loop

[19] Y. Chen et al., "Graceful Cancellation of Long-running LLM Tasks," IEEE Trans. Software Eng., vol. 51, no. 1, pp. 88–104, Jan. 2026.

文档维护：本文档与代码同步演进。架构变更时需同步更新对应章节，保持代码事实与文档描述的一致性。