pyyus 0.4.1__tar.gz

pyyus-0.4.1/.github/workflows/cli-publish.yml

@@ -0,0 +1,23 @@
+name: CLI Publish
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-22.04
+    name: Build on ubuntu
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build & Publish
+        env:
+          WEB_DAV_URL: ${{ secrets.WEB_DAV_URL }}
+          WEB_DAV_AUTH: ${{ secrets.WEB_DAV_AUTH }}
+        run: bash tools/cli-publish.sh

pyyus-0.4.1/.gitignore

@@ -0,0 +1,50 @@
+/target
+# /.qoder
+/.qoder/skills
+/.openclaude
+/.opencode
+/arms_cache
+**/target/
+**/*.rs.bk
+Cargo.lock
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.zip
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+.pytest_cache/
+.mypy_cache/
+.dmypy.json
+dmypy.json
+*.prof
+.python-version
+.venv/
+venv/
+python/pyyus/libpyyus.dylib.dSYM
+ENV/
+env/
+.idea/
+.vscode/
+*.swp
+*.swo
+*.wasm
+*~
+.DS_Store
+Thumbs.db
+MANIFEST

pyyus-0.4.1/.qoder/repowiki/zh/content/API /345/217/202/350/200/203/API /345/217/202/350/200/203.md"

@@ -0,0 +1,530 @@
+# API 参考
+
+<cite>
+**本文引用的文件**
+- [src/lib.rs](file://src/lib.rs)
+- [python/pyyus/__init__.py](file://python/pyyus/__init__.py)
+- [src/config.rs](file://src/config.rs)
+- [src/runtime.rs](file://src/runtime.rs)
+- [src/io.rs](file://src/io.rs)
+- [src/types.rs](file://src/types.rs)
+- [src/error.rs](file://src/error.rs)
+- [crates/config/src/lib.rs](file://crates/config/src/lib.rs)
+- [crates/config/src/config.rs](file://crates/config/src/config.rs)
+- [crates/runtime/src/lib.rs](file://crates/runtime/src/lib.rs)
+- [crates/runtime/src/prelude.rs](file://crates/runtime/src/prelude.rs)
+- [crates/runtime/src/stream/mod.rs](file://crates/runtime/src/stream/mod.rs)
+- [crates/runtime/src/pipe/mod.rs](file://crates/runtime/src/pipe/mod.rs)
+- [python/pyyus/api.py](file://python/pyyus/api.py)
+- [tests/test_highlevel.py](file://tests/test_highlevel.py)
+- [tests/test_session.py](file://tests/test_session.py)
+- [Cargo.toml](file://Cargo.toml)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖分析](#依赖分析)
+7. [性能考虑](#性能考虑)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本参考文档面向 Python 开发者与系统集成工程师，系统化梳理 Pyyus2 的 Python 绑定 API，覆盖以下核心能力：
+- 初始化与配置：init、AppConfig、RuntimeConfig、WasmConfig
+- 配置构建器模式：AppConfig::build、RuntimeConfig::snap、RuntimeConfigSnap::app、RuntimeConfigSnap::session
+- 应用执行：App.run、App.run_stream、App.run_async、App.run_stream_async
+- 流式 I/O：PagedReader、PagedWriter、pipe
+- 会话式调用：Session（状态保持的 P2 函数调用）
+- 结果模型：RunResult、FunctionResult、ResultTypes、WasmActionType
+- 高级工具：run_wasm、run_wasm_stream
+- 运行时缓存：clear_runtime_cache、runtime_cache_size、precompile_wasm
+- 错误模型：统一的 PyyusError 映射到 Python 异常
+
+本文件提供方法签名、参数说明、返回值类型、使用示例、最佳实践与常见问题处理，并解释 API 之间的关系与调用顺序。
+
+## 项目结构
+- Python 包导出层位于 python/pyyus/__init__.py，提供 run_wasm、run_wasm_stream 等高层封装。
+- Rust 绑定层位于 src/，通过 pyo3 暴露类与函数；核心逻辑委托至 crates/runtime 与 crates/config。
+- crates/runtime 提供 WASM 运行时、流式事件、会话管理等能力。
+- crates/config 提供包级配置初始化与默认路径解析。
+
+```mermaid
+graph TB
+subgraph "Python 层"
+PYAPI["python/pyyus/__init__.py<br/>run_wasm / run_wasm_stream"]
+APIPY["python/pyyus/api.py<br/>高级API封装"]
+end
+subgraph "Rust 绑定层"
+LIBRS["src/lib.rs<br/>模块导出"]
+CONFIGRS["src/config.rs<br/>配置类与构建器"]
+RUNTIMERS["src/runtime.rs<br/>App/Session/StreamingResult"]
+IORS["src/io.rs<br/>PagedReader/PagedWriter/pipe"]
+TYPESRS["src/types.rs<br/>RunResult/FunctionResult/ResultTypes/WasmActionType"]
+ERRORSRS["src/error.rs<br/>PyyusError"]
+end
+subgraph "Rust 运行时库"
+RTLIB["crates/runtime/src/lib.rs"]
+RTPRELUDE["crates/runtime/src/prelude.rs"]
+RTSTREAM["crates/runtime/src/stream/mod.rs"]
+RTPipe["crates/runtime/src/pipe/mod.rs"]
+end
+subgraph "Rust 配置库"
+CFG_LIB["crates/config/src/lib.rs"]
+CFG_RS["crates/config/src/config.rs"]
+end
+PYAPI --> LIBRS
+LIBRS --> CONFIGRS
+LIBRS --> RUNTIMERS
+LIBRS --> IORS
+LIBRS --> TYPESRS
+LIBRS --> ERRORSRS
+RUNTIMERS --> RTLIB
+RTLIB --> RTPRELUDE
+RTPRELUDE --> RTSTREAM
+RTPRELUDE --> RTPipe
+CONFIGRS --> CFG_LIB
+CFG_LIB --> CFG_RS
+APIPY --> CONFIGRS
+APIPY --> RUNTIMERS
+```
+
+**图表来源**
+- [src/lib.rs:1-61](file://src/lib.rs#L1-L61)
+- [python/pyyus/__init__.py:1-128](file://python/pyyus/__init__.py#L1-L128)
+- [python/pyyus/api.py:1-749](file://python/pyyus/api.py#L1-L749)
+- [crates/runtime/src/lib.rs:1-24](file://crates/runtime/src/lib.rs#L1-L24)
+- [crates/runtime/src/prelude.rs:1-5](file://crates/runtime/src/prelude.rs#L1-L5)
+- [crates/runtime/src/stream/mod.rs:1-10](file://crates/runtime/src/stream/mod.rs#L1-L10)
+- [crates/runtime/src/pipe/mod.rs:1-83](file://crates/runtime/src/pipe/mod.rs#L1-L83)
+- [crates/config/src/lib.rs:1-21](file://crates/config/src/lib.rs#L1-L21)
+- [crates/config/src/config.rs:1-419](file://crates/config/src/config.rs#L1-L419)
+
+**章节来源**
+- [src/lib.rs:1-61](file://src/lib.rs#L1-L61)
+- [python/pyyus/__init__.py:1-128](file://python/pyyus/__init__.py#L1-L128)
+- [crates/runtime/src/lib.rs:1-24](file://crates/runtime/src/lib.rs#L1-L24)
+- [crates/config/src/lib.rs:1-21](file://crates/config/src/lib.rs#L1-L21)
+
+## 核心组件
+- 初始化与配置
+  - init(workdir: Optional[str], log_level: Optional[str]) -> None
+  - AppConfig(path: str) / from_toml(path: str) / from_zip(path: str) -> AppConfig
+  - RuntimeConfig(path: str) / from_toml(path: str) / from_zip(path: str) / from_app_config(AppConfig) -> RuntimeConfig
+  - WasmConfig(path: str, name: Optional[str] = None) -> WasmConfig
+- 配置构建器模式
+  - AppConfig::build(rename: Optional[str] = None) -> RuntimeConfig
+  - RuntimeConfig::snap(action: str = "*", args: Optional[List] = None, kwargs: Optional[Dict] = None) -> RuntimeConfigSnap
+  - RuntimeConfigSnap::app() -> App
+  - RuntimeConfigSnap::session(ttl: int = 900, index: Optional[str] = None, force: bool = False) -> Session
+- 应用执行
+  - App(RuntimeConfig) -> App
+  - App.run(action: str = "*", args: List[str] = [], stdin: Optional[bytes] = None) -> RunResult
+  - App.run_stream(action: str = "*", args: List[str] = [], stdin: Optional[bytes] = None, max_chars: int = 4096, max_lines: int = 50) -> StreamingResult
+  - App.run_async(...) -> Awaitable[RunResult]
+  - App.run_stream_async(...) -> Awaitable[StreamingResult]
+- 流式 I/O
+  - PagedWriter -> write(data: bytes), close()
+  - PagedReader -> read_all(), read_all_text(), read_page() -> Optional[str], goto_page(n), content_length, chars, lines, is_closed
+  - pipe(max_chars: int = 4096, max_lines: int = 50) -> (PagedWriter, PagedReader)
+- 会话式调用
+  - Session(RuntimeConfig) -> Session
+  - Session.call(func_name: str, params: Optional[str] = None, data: Optional[bytes] = None) -> FunctionResult
+  - Session.call_async(...)
+  - Session.close(), session_id, is_active
+- 结果模型
+  - RunResult(success: bool, exit_code: Optional[int], error_message: Optional[str], stdout: Optional[bytes], stderr: Optional[bytes])
+  - FunctionResult(success: bool, data: Optional[ResultTypes], error: Optional[str])
+  - ResultTypes(string_val: Optional[str], bytes_val: Optional[bytes], json_val: Optional[json])
+  - WasmActionType 枚举（bin/lib/stream/stream_ext/sse/sse_ext/upstream）
+- 高级工具
+  - run_wasm(wasm_path, action="*", args=None, stdin=None, workdir=None, log_level=None) -> RunResult
+  - run_wasm_stream(wasm_path, action="*", args=None, stdin=None, max_chars=4096, max_lines=50, workdir=None, log_level=None) -> StreamingResult
+- 运行时缓存
+  - precompile_wasm(path: str) -> bytes
+  - clear_runtime_cache() -> None
+  - runtime_cache_size() -> int
+
+**章节来源**
+- [src/config.rs:1-257](file://src/config.rs#L1-L257)
+- [src/runtime.rs:1-600](file://src/runtime.rs#L1-L600)
+- [src/io.rs:1-252](file://src/io.rs#L1-L252)
+- [src/types.rs:1-827](file://src/types.rs#L1-L827)
+- [python/pyyus/__init__.py:52-128](file://python/pyyus/__init__.py#L52-L128)
+- [python/pyyus/api.py:514-749](file://python/pyyus/api.py#L514-L749)
+
+## 架构总览
+下图展示 Python 高层 API 与底层 Rust 实现的交互关系，以及 App.run_stream 的异步流式输出路径。
+
+```mermaid
+sequenceDiagram
+participant Py as "Python 调用方"
+participant API as "run_wasm/run_wasm_stream"
+participant Bind as "Rust 绑定层"
+participant App as "App"
+participant RT as "Tokio 运行时"
+participant Stream as "AppStreamAll/事件流"
+participant Reader as "PagedReader"
+participant Writer as "PagedWriter"
+Py->>API : 调用 run_wasm / run_wasm_stream
+API->>Bind : init(workdir, log_level)
+API->>Bind : 构造 RuntimeConfig / App
+API->>App : 调用 run / run_stream
+App->>RT : block_on(run_app_* 或 spawn(run_app_streaming))
+RT->>Stream : new_bytes_stdin(config, stdin)
+alt 同步模式
+Stream-->>App : 收集 stdout/stderr
+App-->>API : 返回 RunResult
+else 流式模式
+App->>Writer : 写入 stdout/stderr 分页缓冲
+Py->>Reader : read_page()/read_all()
+Reader-->>Py : 返回页面文本
+App-->>API : 返回 StreamingResult可等待最终 RunResult
+end
+API-->>Py : 返回结果
+```
+
+**图表来源**
+- [python/pyyus/__init__.py:52-128](file://python/pyyus/__init__.py#L52-L128)
+- [python/pyyus/api.py:514-749](file://python/pyyus/api.py#L514-L749)
+- [src/runtime.rs:357-408](file://src/runtime.rs#L357-L408)
+- [src/runtime.rs:410-476](file://src/runtime.rs#L410-L476)
+- [src/io.rs:69-242](file://src/io.rs#L69-L242)
+
+## 详细组件分析
+
+### 初始化与配置 API
+- init(workdir: Optional[str], log_level: Optional[str]) -> None
+  - 作用：初始化日志级别与包级配置（工作目录、应用目录、存储目录等）。
+  - 注意：首次使用需先调用 init。
+- AppConfig
+  - 构造：from_wasm_path(path: str) 或 from_toml(path: str) 或 from_zip(path: str)
+  - 方法：add_env(key: str, value: str), add_mount(host_dir: str, guest_dir: str)
+  - 属性：domain() -> str
+  - **新增**：build(rename: Optional[str] = None) -> RuntimeConfig
+    - 作用：将 AppConfig 转换为 RuntimeConfig，支持重命名应用域
+    - 参数：rename - 可选的新应用域名
+- RuntimeConfig
+  - 构造：from_wasm_path(path: str) 或 from_toml(path: str) 或 from_zip(path: str) 或 from_app_config(AppConfig)
+  - 方法：add_env(key: str, value: str), set_host_workdir(path: str)
+  - 属性：domain() -> str
+  - **新增**：snap(action: str = "*", args: Optional[List] = None, kwargs: Optional[Dict] = None) -> RuntimeConfigSnap
+    - 作用：创建特定动作、参数组合的配置快照
+    - 参数：action - 动作名称，默认"*"；args - 位置参数列表；kwargs - 关键字参数字典
+- WasmConfig
+  - 构造：new(path: str, name: Optional[str] = None)
+  - 属性：name() -> str, path() -> str
+
+最佳实践
+- 在脚本开头调用 init，确保日志与工作目录已就绪。
+- 使用 from_toml/from_zip 管理复杂应用配置；仅单文件场景可用 from_wasm_path。
+- 通过 add_env/add_mount 注入环境变量与挂载点，避免硬编码路径。
+- **新增**：使用 AppConfig::build 和 RuntimeConfig::snap 实现配置构建器模式，提高代码可读性和类型安全性。
+
+**章节来源**
+- [src/config.rs:14-257](file://src/config.rs#L14-L257)
+- [crates/config/src/config.rs:82-214](file://crates/config/src/config.rs#L82-L214)
+- [crates/config/src/config.rs:310-410](file://crates/config/src/config.rs#L310-L410)
+
+### 配置构建器模式 API
+- AppConfig::build(rename: Optional[str] = None) -> RuntimeConfig
+  - 作用：将 AppConfig 转换为 RuntimeConfig，支持重命名应用域
+  - 参数：rename - 可选的新应用域名，用于覆盖原始配置中的域名
+  - 返回：新的 RuntimeConfig 实例
+- RuntimeConfig::snap(action: str = "*", args: Optional[List] = None, kwargs: Optional[Dict] = None) -> RuntimeConfigSnap
+  - 作用：创建特定动作、参数组合的配置快照
+  - 参数：action - 动作名称，默认"*"；args - 位置参数列表；kwargs - 关键字参数字典
+  - 返回：RuntimeConfigSnap 实例，可用于创建 App 或 Session
+- RuntimeConfigSnap::app() -> App
+  - 作用：从配置快照创建 App 实例
+  - 返回：App 实例，直接用于执行 WASM 应用
+- RuntimeConfigSnap::session(ttl: int = 900, index: Optional[str] = None, force: bool = False) -> Session
+  - 作用：从配置快照创建 Session 实例
+  - 参数：ttl - 会话生存时间（秒），0 表示永久；index - 会话索引；force - 是否强制覆盖现有会话
+  - 返回：Session 实例，用于状态保持的函数调用
+
+使用示例
+```python
+# 使用构建器模式创建配置
+app_cfg = pyyus.AppConfig.from_toml("config.toml").build("my-app")
+runtime_cfg = pyyus.RuntimeConfig.from_toml("runtime.toml")
+snap = runtime_cfg.snap("process", ["arg1"], {"key": "value"})
+
+# 从快照创建 App 和 Session
+app = snap.app()
+session = snap.session(ttl=1800, index="worker-1")
+
+# 直接使用快照执行
+result = app.run()
+session_result = session.call("process", ["arg1"], {"key": "value"})
+```
+
+**章节来源**
+- [src/config.rs:107-256](file://src/config.rs#L107-L256)
+
+### 应用执行 API（App）
+- App(RuntimeConfig)
+  - 作用：承载 WASM 应用的生命周期与执行。
+- App.run(action: str = "*", args: List[str] = [], stdin: Optional[bytes] = None) -> RunResult
+  - 作用：同步执行 WASM 应用，返回 RunResult（包含 stdout/stderr/退出码/错误信息）。
+- App.run_stream(..., max_chars: int = 4096, max_lines: int = 50) -> StreamingResult
+  - 作用：启动异步流式执行，返回 StreamingResult，内部维护 stdout/stderr 的 PagedReader。
+- App.run_async(...) -> Awaitable[RunResult]
+  - 作用：返回协程对象，可在事件循环中 await。
+- App.run_stream_async(...) -> Awaitable[StreamingResult]
+  - 作用：返回协程对象，可在事件循环中 await。
+
+调用顺序与注意事项
+- 先 init，再构造 RuntimeConfig/AppConfig，再实例化 App。
+- run_stream 会立即返回 StreamingResult，随后可通过 PagedReader 逐步读取输出。
+- 若需等待最终结果，可使用 StreamingResult.wait/wait_async 或读取其 result 字段。
+
+**章节来源**
+- [src/runtime.rs:18-121](file://src/runtime.rs#L18-L121)
+- [src/runtime.rs:357-408](file://src/runtime.rs#L357-L408)
+- [src/runtime.rs:410-476](file://src/runtime.rs#L410-L476)
+
+### 流式 I/O API（PagedReader/PagedWriter/pipe）
+- PagedWriter
+  - new() -> (PagedWriter, UnboundedReceiver<Vec<u8>>)
+  - 方法：write(data: bytes), close()
+  - 用途：将 WASM 输出写入内部缓冲并通过通道发送给 PagedReader。
+- PagedReader
+  - new(data: bytes, max_chars: int = 4096, max_lines: int = 50)
+  - 方法：read_all() -> bytes, read_all_text() -> str, read_page() -> Optional[str], goto_page(n) -> Optional[str]
+  - 属性：content_length, chars, lines, is_closed
+  - 用途：按页读取输出，支持字符数与行数限制。
+- pipe(max_chars: int = 4096, max_lines: int = 50) -> (PagedWriter, PagedReader)
+  - 用途：便捷创建一对 writer-reader。
+
+分页策略
+- 优先按字符数（max_chars）截断；当超过行数上限（max_lines）时停止。
+- 末尾换行保留，避免截断中间字符。
+
+**章节来源**
+- [src/io.rs:6-252](file://src/io.rs#L6-L252)
+
+### 会话式调用 API（Session）
+- Session(RuntimeConfig)
+  - 作用：建立长连接式的 WASM P2 会话，复用运行时状态。
+- Session.call(func_name: str, params: Optional[str] = None, data: Optional[bytes] = None) -> FunctionResult
+  - 作用：同步调用 WASM 函数，返回 FunctionResult（包含成功标志、数据或错误）。
+- Session.call_async(...)
+  - 作用：返回协程对象，可在事件循环中 await。
+- Session.close() -> None
+  - 作用：关闭会话并释放资源。
+- 属性：session_id -> str, is_active -> bool
+- 上下文管理：with 语句自动关闭。
+
+最佳实践
+- 多次调用同一 Session 可减少启动成本。
+- 使用 params 传递查询参数，data 传递二进制输入。
+- 会话关闭后不可再次调用。
+
+**章节来源**
+- [src/runtime.rs:194-600](file://src/runtime.rs#L194-L600)
+
+### 结果模型 API
+- RunResult
+  - 字段：success, exit_code, error_message, stdout, stderr
+  - 方法：to_dict() -> Dict
+  - 行为：__bool__ 返回 success
+- FunctionResult
+  - 字段：success, data: Optional[ResultTypes], error: Optional[str]
+  - 方法：to_json() -> Optional[str]
+- ResultTypes
+  - 字段：string_val, bytes_val, json_val
+  - 方法：try_to_string/bytes/json -> Result
+- WasmActionType
+  - 枚举：Bin, Lib, Stream, StreamExt, Sse, SseExt, UpStream
+  - 方法：is_binary(), need_pipe(), has_ext_data()
+
+使用建议
+- 优先使用 ResultTypes 的 try_to_* 方法进行类型安全转换。
+- FunctionResult.data 为空时，检查 error 字段获取错误信息。
+
+**章节来源**
+- [src/types.rs:7-827](file://src/types.rs#L7-L827)
+
+### 高级工具 API
+- run_wasm(wasm_path: str, action: str = "*", args: Optional[List[str]] = None, stdin: Optional[bytes] = None, workdir: Optional[str] = None, log_level: Optional[str] = None) -> RunResult
+  - 作用：一次性运行 WASM 并返回完整结果。
+- run_wasm_stream(wasm_path: str, action: str = "*", args: Optional[List[str]] = None, stdin: Optional[bytes] = None, max_chars: int = 4096, max_lines: int = 50, workdir: Optional[str] = None, log_level: Optional[str] = None) -> StreamingResult
+  - 作用：流式读取输出，适合长输出或实时日志。
+
+使用示例（路径）
+- run_wasm 示例：[python/pyyus/__init__.py:52-128](file://python/pyyus/__init__.py#L52-L128)
+- run_wasm_stream 示例：[python/pyyus/api.py:514-749](file://python/pyyus/api.py#L514-L749)
+
+**章节来源**
+- [python/pyyus/__init__.py:52-128](file://python/pyyus/__init__.py#L52-L128)
+- [python/pyyus/api.py:514-749](file://python/pyyus/api.py#L514-L749)
+
+### 运行时缓存与预编译
+- precompile_wasm(path: str) -> bytes
+  - 作用：对 WASM 文件进行预编译，返回字节码以便加速后续启动。
+- clear_runtime_cache() -> None
+  - 作用：清空运行时配置缓存。
+- runtime_cache_size() -> int
+  - 作用：返回当前缓存条目数量。
+
+最佳实践
+- 在部署阶段对常用 WASM 文件调用 precompile_wasm，保存产物并在运行时加载。
+- 定期调用 clear_runtime_cache 释放内存占用。
+
+**章节来源**
+- [src/runtime.rs:327-353](file://src/runtime.rs#L327-L353)
+
+## 依赖分析
+- Python 层依赖
+  - pyo3（0.28，启用 abi3-py39 与 tokio 运行时）
+  - tokio（full 特性）、tokio-stream、tokio-util、futures、bytes
+  - reqwest（带 rustls-native-roots、blocking、stream）
+  - serde/serde_json、anyhow、log/env_logger、clap、cfg-if、parking_lot、thiserror
+- Rust 工作区
+  - yus-config、yus-runtime、yus-utils 作为成员 crate
+  - 通过 features 控制组件开关（如 components、com-http/com-redis/com-pg/com-blob）
+
+```mermaid
+graph TB
+PY["pyproject.toml / Cargo.toml 依赖声明"]
+PYO3["pyo3 0.28"]
+TOKIO["tokio / tokio-stream / tokio-util / futures / bytes"]
+REQ["reqwest"]
+SERDE["serde / serde_json"]
+ANY["anyhow / log / env_logger / clap / cfg-if / parking_lot / thiserror"]
+PY --> PYO3
+PY --> TOKIO
+PY --> REQ
+PY --> SERDE
+PY --> ANY
+```
+
+**图表来源**
+- [Cargo.toml:63-85](file://Cargo.toml#L63-L85)
+- [Cargo.toml:31-55](file://Cargo.toml#L31-L55)
+
+**章节来源**
+- [Cargo.toml:1-106](file://Cargo.toml#L1-L106)
+
+## 性能考虑
+- 预编译：对热点 WASM 文件调用 precompile_wasm，显著降低启动延迟。
+- 流式 I/O：run_stream 配合 PagedReader 分页读取，避免一次性加载大输出导致内存峰值。
+- 会话复用：Session 复用运行时状态，减少重复初始化成本。
+- 缓存管理：定期清理 runtime_cache，避免长期运行内存膨胀。
+- 日志级别：合理设置 log_level，生产环境建议 info 或更高。
+- **新增**：配置构建器模式减少了重复配置创建的成本，提高了代码执行效率。
+
+## 故障排查指南
+常见错误与处理
+- 未初始化：调用 Pyyus API 前必须先 init。若出现"未初始化"错误，请先调用 init。
+- 配置错误：from_toml/from_zip 失败多因路径不存在或格式不正确。检查路径与 TOML/ZIP 格式。
+- 运行时错误：App.run/run_stream 抛出 RuntimeError，查看 RunResult.error_message 或 FunctionResult.error 获取详细信息。
+- 流关闭：PagedReader 在通道断开后标记为 closed，继续读取将返回 None。请在 is_closed 为真时停止读取。
+- 参数类型：ResultTypes 的 try_to_* 转换失败通常表示数据类型与期望不符，检查上游输出类型。
+- **新增**：配置构建器模式错误：确保在调用 build() 之前正确设置 AppConfig，在调用 snap() 之前正确设置 RuntimeConfig。
+
+异常映射
+- PyyusError -> PyErr：根据错误类型映射为 PyIOError、PyRuntimeError、PyValueError、PyTypeError、PyEOFError 等。
+
+**章节来源**
+- [src/error.rs:4-69](file://src/error.rs#L4-L69)
+- [src/io.rs:180-214](file://src/io.rs#L180-L214)
+
+## 结论
+Pyyus2 提供了从 Python 侧直接运行与流式消费 WASM 应用的能力，配合会话式调用与预编译优化，适用于高并发与低延迟场景。新增的配置构建器模式进一步提升了 API 的易用性和类型安全性。建议在生产环境中结合预编译、缓存清理与合理的日志级别，获得稳定且高性能的运行体验。
+
+## 附录
+
+### API 关系与调用顺序图
+```mermaid
+flowchart TD
+Start(["开始"]) --> Init["调用 init(workdir, log_level)"]
+Init --> Cfg["构建 RuntimeConfig/AppConfig/WasmConfig"]
+Cfg --> Builder{"使用构建器模式?"}
+Builder --> |是| Build["AppConfig.build() / RuntimeConfig.snap()"]
+Builder --> |否| AppNew["实例化 App / Session"]
+Build --> Snap["RuntimeConfigSnap"]
+Snap --> AppNew["App/RuntimeConfigSnap.app()"]
+AppNew --> Mode{"选择模式"}
+Mode --> |同步| Run["App.run(...) -> RunResult"]
+Mode --> |流式| RunStream["App.run_stream(...) -> StreamingResult"]
+Mode --> |会话| SessionCall["Session.call(...) -> FunctionResult"]
+RunStream --> Read["PagedReader.read_page()/read_all()"]
+SessionCall --> End(["结束"])
+Run --> End
+Read --> End
+```
+
+**图表来源**
+- [python/pyyus/__init__.py:52-128](file://python/pyyus/__init__.py#L52-L128)
+- [python/pyyus/api.py:514-749](file://python/pyyus/api.py#L514-L749)
+- [src/config.rs:107-256](file://src/config.rs#L107-L256)
+- [src/runtime.rs:18-121](file://src/runtime.rs#L18-L121)
+- [src/io.rs:69-242](file://src/io.rs#L69-L242)
+
+### 数据模型类图
+```mermaid
+classDiagram
+class RunResult {
++bool success
++int exit_code
++string error_message
++bytes stdout
++bytes stderr
++to_dict() Dict
+}
+class FunctionResult {
++bool success
++ResultTypes data
++string error
++to_json() string
+}
+class ResultTypes {
++string string_val
++bytes bytes_val
++json json_val
++try_to_string() Result<string>
++try_to_bytes() Result<bytes>
++try_to_json() Result<json>
+}
+class WasmActionType {
++Bin
++Lib
++Stream
++StreamExt
++Sse
++SseExt
++UpStream
++is_binary() bool
++need_pipe() bool
++has_ext_data() bool
+}
+FunctionResult --> ResultTypes : "包含"
+```
+
+**图表来源**
+- [src/types.rs:7-827](file://src/types.rs#L7-L827)
+
+### 配置构建器模式使用示例
+```python
+# 方式1：传统方式
+app_cfg = pyyus.AppConfig.from_toml("config.toml")
+runtime_cfg = app_cfg.build("renamed-app")
+snap = runtime_cfg.snap("process", ["arg1"], {"key": "value"})
+app = snap.app()
+
+# 方式2：链式构建器
+app_cfg = pyyus.AppConfig.from_toml("config.toml").build("renamed-app")
+snap = app_cfg.snap("process", ["arg1"], {"key": "value"})
+session = snap.session(ttl=1800, index="worker-1")
+```
+
+**章节来源**
+- [src/config.rs:107-256](file://src/config.rs#L107-L256)
+- [tests/test_highlevel.py:151-179](file://tests/test_highlevel.py#L151-L179)
+- [tests/test_session.py:45-108](file://tests/test_session.py#L45-L108)