docs: reorganize markdown files — keep 4 in root, move 7 to docs/

Root (project entry points):
  README.md, CONTRIBUTING.md, QUICK_START.md, ENGINEERING_GAP_ANALYSIS.md

Moved to docs/:
  cli-usage.md, usage.md, from-config-spec.md, runtime-spec.md,
  idea.md, hook-system.md, assistant-feasibility.md

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

docs/assistant-feasibility.md

@@ -0,0 +1,381 @@
+# 个人电脑助手 & 编程助手 — 可行性分析
+
+> 对标 Claude Code 的 60+ 内置工具，分析 lambdagentpaas 平台实现同等能力所需的工作。
+
+---
+
+## 一、Claude Code 能力全景 vs 平台现状
+
+### 1. 工具能力对照
+
+| 能力域 | Claude Code 工具 | lambdagentpaas 现状 | 差距 |
+|--------|-----------------|---------------------|------|
+| **文件读取** | `Read` (行号、分页、PDF、图片、Notebook) | ShellTool(`cat`/`head`) | **大** — 无结构化读取、无二进制文件支持 |
+| **文件编辑** | `Edit` (精确字符串替换、replace_all) | ShellTool(`sed`) | **大** — 无原子替换、无唯一性校验 |
+| **文件写入** | `Write` (覆盖写入、自动创建目录) | ShellTool(`echo >`) | **中** — 可用但无安全检查 |
+| **文件搜索** | `Glob` (ripgrep 驱动、按修改时间排序) | ShellTool(`find`) | **中** — 性能和输出格式差距 |
+| **内容搜索** | `Grep` (ripgrep、正则、多行、上下文、类型过滤) | ShellTool(`grep`/`rg`) | **中** — 功能等价但无结构化输出 |
+| **Shell 执行** | `Bash` (沙盒、超时、后台运行) | ShellTool + SandboxedTool | **小** — 核心能力已有 |
+| **Git 操作** | 内置 commit/PR/branch 流程 | ShellTool(`git`) | **中** — 命令可用但无流程封装 |
+| **Notebook** | `NotebookEdit` (cell 级编辑) | 无 | **大** — 完全缺失 |
+| **Web 搜索** | `WebSearch` | MCP 可扩展 | **中** — 需 MCP 服务器 |
+| **Web 获取** | `WebFetch` (HTML→Markdown) | MCP 可扩展 | **中** — 需 MCP 服务器 |
+| **子任务代理** | `Agent` (Worktree 隔离、并行) | AsyncPar + IsolatedWorkspace | **小** — 基础设施已有 |
+| **任务管理** | `TaskCreate/Update/List` | 无 | **中** — 需新建模块 |
+| **上下文管理** | 自动压缩、History snip | ContextManager (Phase 2) | **小** — 已实现基础版 |
+| **流式输出** | 全链路 streaming | AsyncExecutor + LLM stream | **小** — 已实现 |
+| **取消机制** | AbortController 层级 | CancellationToken | **小** — 已实现 |
+
+### 2. 非工具能力对照
+
+| 能力 | Claude Code | lambdagentpaas | 差距 |
+|------|-------------|----------------|------|
+| **权限系统** | 用户审批每次工具调用 | ToolGateway 风险分级 + 审计 | **小** — 架构不同但等效 |
+| **Hook 系统** | pre/post 钩子、用户自定义 | 无 | **大** — 完全缺失 |
+| **CLAUDE.md** | 项目级持久化指令 | Memory + Checkpoint | **中** — 机制不同 |
+| **Memory** | 文件系统持久化记忆 | Memory Term + MemoryBackend | **小** — 已有 |
+| **多模型** | 自动 fallback model | LLMAdapter 多 Provider | **中** — 无自动 fallback |
+| **IDE 集成** | VS Code / JetBrains 扩展 | 无 | **大** — 完全缺失 |
+| **OAuth/MCP** | 内置 MCP 服务器管理 | MCPServer + MCPTool | **小** — 基础已有 |
+
+---
+
+## 二、目标产品形态
+
+### 形态 A：个人电脑助手
+
+> 面向普通用户，管理文件、自动化日常任务、信息检索。
+
+核心场景：
+- "帮我整理下载文件夹，按类型分类"
+- "找到所有大于 100MB 的文件"
+- "把这个 PDF 的内容总结一下"
+- "搜索邮件中关于项目 X 的讨论"
+- "设置一个定时提醒"
+
+### 形态 B：编程助手
+
+> 面向开发者，等价于 Claude Code 的能力。
+
+核心场景：
+- "阅读这个项目的代码结构"
+- "修复这个 bug"（Read → 分析 → Edit → 验证）
+- "写一个新功能并测试"
+- "提交代码并创建 PR"
+- "运行测试并修复失败的用例"
+
+---
+
+## 三、需要实现的能力模块
+
+### Tier 1：基础工具层（必须）
+
+#### 1.1 结构化文件操作工具集
+
+**需要新建**: `lambdagent/builtin_tools/file_tools.py`
+
+| 工具 | 功能 | 复杂度 | 说明 |
+|------|------|--------|------|
+| `ReadFile` | 读取文件（行号、offset、limit、PDF、图片描述） | 中 | 核心能力，需处理编码、大文件、二进制 |
+| `EditFile` | 精确字符串替换（old_string→new_string） | 中 | 需唯一性校验、原子操作、备份 |
+| `WriteFile` | 创建/覆盖写入 | 小 | 需自动创建目录、权限检查 |
+| `ListFiles` | 按 glob 模式搜索文件 | 小 | 需按修改时间排序、忽略 .git 等 |
+| `SearchContent` | 正则搜索文件内容 | 中 | 需上下文行、类型过滤、多行模式 |
+
+**可行性**: **高** — 纯 Python 实现，无外部依赖。
+
+**核心设计决策**: 工具作为 `ValidatedTool` 子类实现，自带 Pydantic Schema，通过 ToolGateway 进行权限管控。每个工具是一个 Lambda 项 `λx. file_op(x)`，可自然组合到 ReAct loop 中。
+
+```
+ReadFile  = ValidatedTool("ReadFile",  read_fn,  ReadFileSchema)
+EditFile  = ValidatedTool("EditFile",  edit_fn,  EditFileSchema)
+WriteFile = ValidatedTool("WriteFile", write_fn, WriteFileSchema)
+```
+
+**工作量**: ~3-4 天
+
+#### 1.2 增强 Shell 执行
+
+**需要修改**: `lambdagent/cli/shell_tool.py` + `sandbox.py`
+
+| 能力 | 说明 | 复杂度 |
+|------|------|--------|
+| 后台执行 | `run_in_background=True`，非阻塞 | 中 |
+| 工作目录持久化 | 跨命令保持 CWD | 小 |
+| 环境变量继承 | 继承用户 shell 环境 | 小 |
+| 输出限制 | 智能截断（头尾保留） | 小 |
+| 交互检测 | 拒绝需要交互的命令（如 `vim`） | 小 |
+
+**可行性**: **高** — ShellTool 已存在，增量改进。
+
+**工作量**: ~2 天
+
+#### 1.3 Git 工作流封装
+
+**需要新建**: `lambdagent/builtin_tools/git_tools.py`
+
+| 工具 | 功能 | 复杂度 |
+|------|------|--------|
+| `GitStatus` | 状态查看 + diff | 小 |
+| `GitCommit` | 智能 commit（分析变更、生成消息） | 中 |
+| `GitBranch` | 分支管理 | 小 |
+| `GitLog` | 查看历史 | 小 |
+| `GitDiff` | 查看变更详情 | 小 |
+
+**可行性**: **高** — 封装 `subprocess.run(["git", ...])` 即可，IsolatedWorkspace 已有 git 操作基础。
+
+**工作量**: ~2 天
+
+### Tier 2：智能层（编程助手必须）
+
+#### 2.1 代码理解引擎
+
+**需要新建**: `lambdagent/builtin_tools/code_tools.py`
+
+| 工具 | 功能 | 复杂度 | 说明 |
+|------|------|--------|------|
+| `CodeSearch` | 语义代码搜索（类/函数/变量定义） | 高 | 可基于 tree-sitter 或 ripgrep + 正则 |
+| `ProjectMap` | 项目结构概览（目录树 + 关键文件摘要） | 中 | 递归扫描 + LLM 摘要 |
+| `SymbolLookup` | 查找符号定义和引用 | 高 | 需 AST 解析或 LSP |
+
+**可行性**: **中** — `CodeSearch` 和 `ProjectMap` 可用 ripgrep + glob 实现，`SymbolLookup` 需要 AST 解析器。
+
+**替代方案**: 不做 AST，纯正则 + LLM 理解。80% 的场景足够。
+
+**工作量**: ~4-5 天（无 AST 版本）
+
+#### 2.2 测试运行器
+
+**需要新建**: `lambdagent/builtin_tools/test_tools.py`
+
+| 工具 | 功能 | 复杂度 |
+|------|------|--------|
+| `RunTests` | 执行测试套件（pytest、jest、go test 等） | 中 |
+| `ParseTestOutput` | 解析测试输出，结构化失败信息 | 中 |
+
+**可行性**: **高** — 本质是 ShellTool + 输出解析。
+
+**工作量**: ~2 天
+
+#### 2.3 任务管理系统
+
+**需要新建**: `lambdagent/task_manager.py`
+
+| 工具 | 功能 | 复杂度 |
+|------|------|--------|
+| `TaskCreate` | 创建任务（subject, description） | 小 |
+| `TaskUpdate` | 更新状态（pending → in_progress → completed） | 小 |
+| `TaskList` | 列出所有任务 | 小 |
+
+**可行性**: **高** — 内存数据结构 + JSON 持久化。
+
+**工作量**: ~1 天
+
+### Tier 3：交互层（产品化必须）
+
+#### 3.1 权限审批 UI
+
+**当前**: ToolGateway 的 `confirm_callback` 是空实现。
+
+**需要**: 
+- CLI 模式：终端 prompt 确认（`y/n`）
+- Web 模式：WebSocket 推送 → 前端弹窗 → API 回调
+
+| 组件 | 复杂度 | 说明 |
+|------|--------|------|
+| CLI confirm prompt | 小 | `input("Allow? [y/n]")` |
+| WebSocket confirm | 高 | 需前端配合 |
+| 权限记忆 | 中 | "始终允许 X" / "本次会话允许" |
+
+**可行性**: CLI 版 **高**，Web 版 **中**。
+
+**工作量**: CLI ~1 天，Web ~5 天
+
+#### 3.2 流式终端 UI
+
+**当前**: AsyncReActEngine.run_stream() 已返回 StreamEvent。
+
+**需要**: 终端渲染层（类似 Claude Code 的 rich terminal UI）。
+
+| 组件 | 复杂度 | 说明 |
+|------|--------|------|
+| Token 逐字输出 | 小 | 消费 TokenEvent |
+| Spinner + 状态栏 | 中 | 类似 `rich.live` |
+| 工具调用展示 | 中 | 折叠/展开工具输入输出 |
+| 多 Agent 面板 | 高 | 并行 Agent 的分栏显示 |
+
+**可行性**: 基础版 **高**（用 `rich` 库），完整版 **中**。
+
+**工作量**: 基础 ~3 天，完整 ~8 天
+
+#### 3.3 项目级配置文件
+
+**类似 Claude Code 的 CLAUDE.md**。
+
+**需要**: Agent 启动时自动加载项目目录下的 `.lambdagent.md` 作为额外 system prompt。
+
+**可行性**: **高** — 在 `from_config` 编译时读取并拼接到 systemPrompt。
+
+**工作量**: ~0.5 天
+
+### Tier 4：扩展层（竞争力）
+
+#### 4.1 Hook 系统
+
+**类似 Claude Code 的 pre/post hook。**
+
+| Hook | 触发时机 | 用途 |
+|------|----------|------|
+| `pre_tool_call` | 工具调用前 | 自定义权限检查、日志 |
+| `post_tool_call` | 工具调用后 | 结果过滤、审计 |
+| `pre_llm_call` | LLM 调用前 | prompt 注入、成本控制 |
+| `post_llm_call` | LLM 调用后 | 输出过滤、安全检查 |
+| `on_error` | 出错时 | 自定义恢复逻辑 |
+
+**可行性**: **高** — 在 Executor/AsyncExecutor 的 reduce 方法中插入 hook 点。
+
+**工作量**: ~2 天
+
+#### 4.2 Notebook 编辑
+
+| 组件 | 复杂度 | 说明 |
+|------|--------|------|
+| 读取 .ipynb | 小 | JSON 解析 |
+| Cell 级编辑 | 中 | 按 cell index 增删改 |
+| 执行 cell | 高 | 需 Jupyter kernel 连接 |
+
+**可行性**: 读取/编辑 **高**，执行 **中**（需 `jupyter_client` 依赖）。
+
+**工作量**: ~3 天
+
+#### 4.3 Web 工具
+
+| 工具 | 功能 | 复杂度 | 依赖 |
+|------|------|--------|------|
+| `WebSearch` | 搜索引擎查询 | 中 | SerpAPI / Brave Search API |
+| `WebFetch` | 获取网页内容 → Markdown | 中 | `markdownify` + `requests` |
+
+**可行性**: **高** — 可作为 MCP 服务器实现，也可作为内置 Tool。
+
+**工作量**: ~2 天
+
+---
+
+## 四、技术架构方案
+
+### 整体架构
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Terminal UI (rich)                     │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────┐  │
+│  │ Streaming│  │Permission│  │  Task    │  │ Status │  │
+│  │ Output   │  │ Prompt   │  │ Tracker  │  │  Bar   │  │
+│  └──────────┘  └──────────┘  └──────────┘  └────────┘  │
+├─────────────────────────────────────────────────────────┤
+│              Agent Runtime (AsyncExecutor)                │
+│  ┌────────────────────────────────────────────────────┐  │
+│  │  ReAct Loop (Y combinator)                         │  │
+│  │  think → route → invoke → observe → check          │  │
+│  │       ↓                                             │  │
+│  │  CancellationToken + ContextManager + TokenBudget  │  │
+│  └────────────────────────────────────────────────────┘  │
+├─────────────────────────────────────────────────────────┤
+│                    Built-in Tools                         │
+│  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌──────┐  │
+│  │  File  │ │  Code  │ │  Shell │ │  Git   │ │ Web  │  │
+│  │ R/W/E  │ │ Search │ │  Exec  │ │ Commit │ │Search│  │
+│  └────────┘ └────────┘ └────────┘ └────────┘ └──────┘  │
+│  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐           │
+│  │Notebook│ │  Test  │ │  Task  │ │  MCP   │           │
+│  │ Edit   │ │ Runner │ │ Manage │ │ Tools  │           │
+│  └────────┘ └────────┘ └────────┘ └────────┘           │
+├─────────────────────────────────────────────────────────┤
+│                   Security Layer                         │
+│  ToolGateway → SandboxPolicy → IsolatedWorkspace        │
+│  Hook System → Permission Prompt → Audit Log            │
+├─────────────────────────────────────────────────────────┤
+│                   LLM Providers                          │
+│  Anthropic | OpenAI | DashScope | Ollama | DeepSeek     │
+│  RetryPolicy + CircuitBreaker + RateLimiter             │
+└─────────────────────────────────────────────────────────┘
+```
+
+### 工具注册机制
+
+```python
+# 所有内置工具统一注册为 ValidatedTool + GatewayPolicy
+BUILTIN_TOOLS = {
+    # 文件操作
+    "ReadFile":      ValidatedTool("ReadFile",      read_file,      ReadFileSchema),
+    "EditFile":      ValidatedTool("EditFile",      edit_file,      EditFileSchema),
+    "WriteFile":     ValidatedTool("WriteFile",     write_file,     WriteFileSchema),
+    "ListFiles":     ValidatedTool("ListFiles",     list_files,     ListFilesSchema),
+    "SearchContent": ValidatedTool("SearchContent", search_content, SearchSchema),
+    # Shell
+    "Bash":          ValidatedTool("Bash",          run_bash,       BashSchema),
+    # Git
+    "GitStatus":     ValidatedTool("GitStatus",     git_status,     GitStatusSchema),
+    "GitCommit":     ValidatedTool("GitCommit",     git_commit,     GitCommitSchema),
+    # ...
+}
+
+# from_config 编译时自动注入
+tools = {**BUILTIN_TOOLS, **_compile_mcp_tools(cfg), **overrides.get("tools", {})}
+tools = {name: gateway.wrap(tool) for name, tool in tools.items()}
+```
+
+---
+
+## 五、可行性评估总结
+
+### 分阶段实施路线
+
+| 阶段 | 内容 | 工作量 | 产出形态 |
+|------|------|--------|----------|
+| **MVP** | 文件工具 + Shell 增强 + Git 封装 + 流式 CLI | ~10 天 | 可用的编程助手 CLI |
+| **V1** | + 代码搜索 + 测试运行 + 任务管理 + 权限 UI | ~12 天 | 对标 Claude Code 核心功能 |
+| **V2** | + Hook 系统 + Notebook + Web 工具 + 项目配置 | ~10 天 | 完整个人助手 |
+| **V3** | + IDE 插件 + Web UI + 多 Agent 协作面板 | ~20 天 | 产品化 |
+
+### 核心优势（已有基础设施可复用）
+
+| 已有模块 | 复用于 | 节省工作量 |
+|----------|--------|-----------|
+| `ToolGateway` 5 级风险分类 | 所有工具的权限管控 | ~5 天 |
+| `SandboxedTool` 进程隔离 | Shell/Code 执行安全 | ~3 天 |
+| `IsolatedWorkspace` Git Worktree | 子 Agent 文件隔离 | ~4 天 |
+| `AsyncExecutor` + `CancellationToken` | 异步执行 + 取消 | ~6 天 |
+| `LLMAdapter` 多 Provider | 模型灵活切换 | ~3 天 |
+| `RetryPolicy` + `CircuitBreaker` | 工具调用弹性 | ~2 天 |
+| `ValidatedTool` + Pydantic | 工具输入校验 | ~2 天 |
+| `ContextManager` | 长会话上下文管理 | ~3 天 |
+| `TokenBudget` | 成本控制 | ~1 天 |
+| `RateLimiter` | API 调用限流 | ~1 天 |
+| MCPServer/MCPTool | 第三方工具生态 | ~5 天 |
+
+**已有基础设施可节省约 35 天工作量。**
+
+### 核心风险
+
+| 风险 | 影响 | 缓解策略 |
+|------|------|----------|
+| 文件编辑精度 | EditFile 的字符串匹配不唯一 → 误编辑 | 编辑前备份、唯一性校验、diff 预览 |
+| 安全性 | Agent 可执行任意命令 → 破坏系统 | ToolGateway 已有 50+ 规则；增加 path ACL |
+| 性能 | 大项目文件搜索慢 | 依赖 ripgrep (rg) 而非纯 Python |
+| LLM 成本 | 长会话 token 爆炸 | TokenBudget 已实现；ContextManager 已实现 |
+| macOS 沙盒 | POSIX rlimit 在 macOS 部分失效 | 已有 monkey-patch fallback；可升级到 sandbox-exec(1) |
+
+### 结论
+
+**可行性: 高。**
+
+lambdagentpaas 的 Lambda 演算架构天然适合构建工具组合型助手：
+- 每个工具是一个 Lambda 项 (`λx. tool(x)`)
+- 工具组合是函数组合 (`>>`)
+- ReAct 循环是 Y 组合子
+- 权限控制是依赖类型 (`Guard`)
+
+Phase 1-4 已经建好了异步执行、流式输出、取消机制、重试弹性、安全网关、文件隔离等核心基础设施。**剩余工作主要是"填充工具实现"而非"搭建框架"**——这是最有利的位置。
+
+MVP（文件工具 + Shell + Git + 流式 CLI）预计 **10 天**可交付可用的编程助手原型。

docs/cli-usage.md

@@ -0,0 +1,1339 @@
+# lambdagentpaas CLI 完整使用说明
+
+本文档涵盖两个 CLI 工具：
+
+- **`lambdagent`** — Lambda 演算 Agent DSL 的命令行入口（编译/执行/调试）
+- **`agentpaas`** — Agent Platform as a Service 平台管理（服务/部署/监控）
+
+---
+
+# Part I — lambdagent CLI
+
+> Unix 管道 `|` = 函数组合 `>>`，每条命令 = 一次或多次 β-规约。
+
+## 目录（lambdagent）
+
+- [安装与配置](#安装与配置)
+- [命令总览](#命令总览)
+- [compile — 编译 YAML → Lambda 项](#compile--编译-yaml--lambda-项)
+- [run — 编译 + 执行 Agent](#run--编译--执行-agent)
+- [repl — 交互式会话](#repl--交互式会话)
+- [lint — 静态分析](#lint--静态分析)
+- [trace — 查看 β-规约追踪](#trace--查看-β-规约追踪)
+- [lambda — 导出 Lambda 表达式](#lambda--导出-lambda-表达式)
+- [tools — 列出和测试工具](#tools--列出和测试工具)
+- [version — 版本信息](#version--版本信息)
+- [高级用法](#高级用法)
+- [YAML 配置参考](#yaml-配置参考)
+- [退出码](#退出码)
+
+---
+
+## 安装与配置
+
+```bash
+# 安装依赖
+pip install pyyaml anthropic
+# 可选：pip install openai redis cryptography
+
+# 设置 API Key（至少选一个）
+export ANTHROPIC_API_KEY="sk-ant-..."
+# 或
+export OPENAI_API_KEY="sk-..."
+# 或（阿里云 DashScope）
+export DASHSCOPE_API_KEY="sk-..."
+```
+
+验证安装：
+
+```bash
+python -m lambdagent version
+# lambdagent v2.0.0
+# Lambda Calculus Agent DSL
+# 11 core constructs — strict lambda correspondence
+```
+
+---
+
+## 命令总览
+
+```
+python -m lambdagent <command> [options]
+
+Commands:
+  compile   编译 YAML → Lambda 项（不执行）
+  run       编译 + 执行 Agent
+  repl      交互式 REPL（持久会话）
+  lint      静态分析 Agent 配置
+  trace     查看/回放 β-规约追踪
+  lambda    导出纯 Lambda 表达式
+  tools     列出和测试 MCP/本地工具
+  version   版本信息
+```
+
+---
+
+## compile — 编译 YAML → Lambda 项
+
+将 YAML 配置编译为 Lambda 项结构，不实际执行。用于验证配置正确性。
+
+```bash
+python -m lambdagent compile <config.yml> [--format text|json] [--validate]
+```
+
+### 参数
+
+| 参数 | 说明 |
+|------|------|
+| `config` | YAML 配置文件路径 |
+| `--format text\|json` | 输出格式（默认 `text`） |
+| `--validate` | 同时运行 lint 检查 |
+
+### 示例
+
+```bash
+# 查看编译结构
+python -m lambdagent compile agent-config.yml
+
+# JSON 格式输出
+python -m lambdagent compile agent-config.yml --format json
+
+# 编译 + lint
+python -m lambdagent compile agent-config.yml --validate
+```
+
+输出示例：
+```
+agent-config =
+  # type: react (Y combinator + tool routing)
+  Y_10(λself. λstate.
+    let t = think(state) in
+    CASE (classify t) [
+      ("search", λx. MCP("mcp-server", "search", x))
+      ("terminate", λx. x)    ← base case
+    ] >> λobs.
+    IF (obs = t) THEN t ELSE self(state ⊕ format(t, obs))
+  )
+```
+
+---
+
+## run — 编译 + 执行 Agent
+
+编译 YAML 配置并执行 Agent，输出最终结果。
+
+```bash
+python -m lambdagent run <config.yml> [input] [options]
+```
+
+### 参数
+
+| 参数 | 说明 |
+|------|------|
+| `config` | YAML 配置文件路径 |
+| `input` | 输入文本。使用 `-` 从 stdin 读取 |
+| `--input-file FILE` | 从文件读取输入 |
+| `--model MODEL` | 覆盖模型（如 `claude-sonnet-4-20250514`） |
+| `--temperature FLOAT` | 覆盖温度 |
+| `--max-steps INT` | 覆盖最大步数（ReAct 模式） |
+| `--tool NAME=CMD` | 注入 CLI 工具（可重复使用） |
+| `--timeout INT` | 总超时秒数（默认 300） |
+| `--trace` | 打印 β-规约追踪 |
+| `--trace-file FILE` | 保存追踪到 JSON 文件 |
+| `--format text\|json` | 输出格式 |
+| `--verbose` | 打印所有中间步骤 |
+| `--quiet` | 只输出最终结果 |
+
+### 基本用法
+
+```bash
+# 直接输入
+python -m lambdagent run agent-config.yml "帮我写一个快速排序"
+
+# 从 stdin 读取输入
+echo "分析这段日志" | python -m lambdagent run agent-config.yml -
+
+# 从文件读取输入
+python -m lambdagent run agent-config.yml --input-file question.txt
+```
+
+### 覆盖模型参数
+
+```bash
+# 使用 GPT-4o 替代默认模型
+python -m lambdagent run agent-config.yml "Hello" --model gpt-4o
+
+# 使用高温度（更有创意）
+python -m lambdagent run agent-config.yml "写一首诗" --temperature 0.8
+
+# 限制 ReAct 步数
+python -m lambdagent run agent-config.yml "搜索资料" --max-steps 5
+```
+
+### 注入 CLI 工具
+
+`--tool` 参数将 shell 命令包装为 Agent 可用的工具（Lambda 语义: `λx. exec(cmd, x)`）：
+
+```bash
+# 注入静态命令工具
+python -m lambdagent run agent-config.yml "分析日志" \
+  --tool grep="grep -c ERROR /var/log/app.log"
+
+# 注入参数化工具（{} 被 Agent 输出替换）
+python -m lambdagent run agent-config.yml "搜索代码" \
+  --tool search="grep -r {} src/"
+
+# 注入多个工具
+python -m lambdagent run agent-config.yml "分析项目" \
+  --tool loc="find . -name '*.py' | wc -l" \
+  --tool deps="pip list --format=json"
+```
+
+> **安全说明**：`--tool` 会自动拦截危险命令（`rm -rf /`、`fork bomb` 等），参数化模式下输入会经过 `shlex.quote` 转义。
+
+### 追踪与调试
+
+```bash
+# 打印 β-规约追踪
+python -m lambdagent run agent-config.yml "1+1" --trace
+
+# 保存追踪到文件（后续用 trace 命令分析）
+python -m lambdagent run agent-config.yml "task" --trace-file trace.json
+
+# JSON 输出（含 result + trace + stats）
+python -m lambdagent run agent-config.yml "task" --format json
+
+# 详细模式（打印每步中间结果）
+python -m lambdagent run agent-config.yml "task" --verbose
+```
+
+### Unix 管道组合
+
+```bash
+# 管道输入
+cat article.txt | python -m lambdagent run summarizer.yml -
+
+# 链式处理（CLI 层面的函数组合）
+cat data.csv | \
+  python -m lambdagent run extract.yml - | \
+  python -m lambdagent run analyze.yml - | \
+  python -m lambdagent run report.yml -
+
+# 与其他命令组合
+python -m lambdagent run agent-config.yml "list files" --quiet | xargs wc -l
+```
+
+---
+
+## repl — 交互式会话
+
+启动持久化 REPL 会话，支持多轮对话和内置命令。
+
+```bash
+python -m lambdagent repl <config.yml> [--model MODEL] [--temperature FLOAT] [--tool NAME=CMD]
+```
+
+### 进入 REPL
+
+```bash
+python -m lambdagent repl agent-config.yml
+```
+
+输出：
+```
+lambdagent REPL v2.0
+Agent: my-agent (react, maxSteps=10)
+Lambda: Y_10(λself.λstate. think(state) >> route >> observe)
+Type :help for commands, :quit to exit
+
+λ>
+```
+
+### REPL 内置命令
+
+| 命令 | 说明 |
+|------|------|
+| `:help` | 显示帮助 |
+| `:quit` / `:q` / `:exit` | 退出 REPL |
+| `:trace` | 显示上次执行的 β-规约追踪 |
+| `:trace N` | 显示第 N 步的详细信息 |
+| `:memory` | 显示 Memory 内容 |
+| `:memory clear` | 清空 Memory |
+| `:lambda` | 显示 Agent 的 Lambda 表达式 |
+| `:lint` | 对当前配置运行 lint |
+| `:reload` | 重新加载 YAML 配置（热更新） |
+| `:stats` | 显示会话统计 |
+| `:tools` | 列出可用工具 |
+
+### REPL 会话示例
+
+```
+λ> 帮我写一个冒泡排序
+  [β[0] think 2.3s] 我需要写一个冒泡排序...
+  [β[1] Tool:terminate 0.0s] 返回结果
+
+def bubble_sort(arr):
+    n = len(arr)
+    for i in range(n):
+        for j in range(0, n-i-1):
+            if arr[j] > arr[j+1]:
+                arr[j], arr[j+1] = arr[j+1], arr[j]
+    return arr
+(2 β-reductions, 2.3s)
+
+λ> :trace 0
+  β[0] think
+    Duration: 2312ms
+    Model: claude-sonnet-4-20250514
+    Input:  帮我写一个冒泡排序...
+    Output: 我需要写一个冒泡排序...
+
+λ> :stats
+  Session: 45s
+  Total β-reductions: 2
+  Trace entries: 2
+
+λ> :quit
+Session: 2 β-reductions in 45s
+```
+
+---
+
+## lint — 静态分析
+
+对 Agent 配置进行静态分析，检查 26+ 条规则（含 3 条安全规则 S001-S003）。
+
+```bash
+python -m lambdagent lint <config.yml|directory> [--level error|warn|info] [--format text|json]
+```
+
+### 参数
+
+| 参数 | 说明 |
+|------|------|
+| `config` | YAML 文件路径，或目录（递归扫描 `*.yml`/`*.yaml`） |
+| `--level` | 最低显示级别（默认 `info`，只看错误用 `error`） |
+| `--format` | 输出格式（默认 `text`） |
+
+### 示例
+
+```bash
+# 分析单个文件
+python -m lambdagent lint agent-config.yml
+
+# 只显示错误
+python -m lambdagent lint agent-config.yml --level error
+
+# 扫描目录下所有配置
+python -m lambdagent lint configs/
+
+# JSON 输出（CI/CD 集成）
+python -m lambdagent lint agent-config.yml --format json
+```
+
+输出示例：
+```
+lambdagent lint: agent-config.yml
+============================================================
+  [x] [ERROR] [L004] type=react but no 'terminate' in localTools
+    Lambda: Y combinator has no base case -> infinite loop
+  [!] [WARN ] [S002] Agent has tools but no guard config. Add guard.dangerousCommandBlock for safety.
+    Lambda: Unguarded tool access = untyped β-reduction (no dependent type constraint)
+  [i] [INFO ] [L015] Memory enabled: strategy=redis
+    Lambda: Gamma' = Gamma union store(redis)
+──────────────────────────────────────────────────────
+  1 error(s), 1 warning(s), 1 info(s)
+```
+
+### lint 规则速查
+
+**功能规则 (L001-L026)**
+
+| 规则 | 级别 | 说明 |
+|------|------|------|
+| L001 | ERROR | 缺少 `type` 字段 |
+| L002 | ERROR | 无效的 `type` 值 |
+| L003 | ERROR | 缺少 `systemPrompt` |
+| L004 | ERROR | `react` 类型但无 `terminate` 工具（Y 组合子无 base case） |
+| L005 | WARN | 无 MCP 工具配置 |
+| L010 | INFO | 温度为 0（确定性输出） |
+| L015 | INFO | Memory 策略信息 |
+
+**安全规则 (S001-S003)**
+
+| 规则 | 级别 | 说明 |
+|------|------|------|
+| S001 | ERROR/WARN | `maxSteps` 过大（>1000 ERROR，>100 WARN） |
+| S002 | WARN | 有工具但无 Guard 配置 |
+| S003 | WARN | SandboxPolicy 过于宽松 |
+
+---
+
+## trace — 查看 β-规约追踪
+
+查看和分析之前保存的执行追踪（由 `run --trace-file` 生成）。
+
+```bash
+python -m lambdagent trace <trace.json> [--step N] [--timeline]
+```
+
+### 参数
+
+| 参数 | 说明 |
+|------|------|
+| `file` | trace JSON 文件路径 |
+| `--step N` | 查看第 N 步详情 |
+| `--timeline` | 时间线视图 |
+
+### 默认视图（全部步骤）
+
+```bash
+python -m lambdagent trace trace.json
+```
+
+输出：
+```
+  β[0] think (2312ms): 帮我写快速排序... → 我需要思考...
+  β[1] Tool:search (450ms): 快速排序算法 → 快速排序是一种分治算法...
+  β[2] think (1803ms): 根据搜索结果... → 我来写代码...
+  β[3] Tool:terminate (1ms): 返回最终答案 → def quicksort...
+
+Total: 4 β-reductions, 4.6s
+```
+
+### 查看单步详情
+
+```bash
+python -m lambdagent trace trace.json --step 1
+```
+
+输出：
+```
+β[1] Tool:search
+  Duration: 450ms
+  Model:    N/A
+  Tokens:   N/A
+  Input:    快速排序算法
+  Output:   快速排序是一种分治算法，它选择一个基准元素...
+```
+
+### 时间线视图
+
+```bash
+python -m lambdagent trace trace.json --timeline
+```
+
+输出：
+```
+Time ──────────────────────────────────────────→
+   0.0s ├████████████████████████ think (2312ms)
+   2.3s ├█████ Tool:search (450ms)
+   2.8s ├██████████████████ think (1803ms)
+   4.6s ├ Tool:terminate (1ms)
+   4.6s ┤ END
+```
+
+---
+
+## lambda — 导出 Lambda 表达式
+
+将 YAML 配置导出为形式化的 Lambda 表达式，展示 Agent 的数学结构。
+
+```bash
+python -m lambdagent lambda <config.yml> [--format human|formal|json]
+```
+
+### 参数
+
+| 参数 | 说明 |
+|------|------|
+| `config` | YAML 配置文件路径 |
+| `--format` | `human`（默认，可读），`formal`（形式化），`json` |
+
+### 示例
+
+```bash
+python -m lambdagent lambda agent-config.yml
+```
+
+输出（ReAct Agent）：
+```
+my-agent =
+    Y_10(λself. λstate.
+      let t = (λx. LLM_{anthropic/claude-sonnet-4-20250514, ⊕_0}("You are a helpful..."))(state) in
+      CASE (classify t) [
+        ("search", λx. MCP("mcp-server", "search", x))
+        ("terminate", λx. x)  ← base case
+      ] >> λobs.
+      IF (obs = t) THEN t ELSE self(state ⊕ format(t, obs))
+    )
+```
+
+输出（Chain Agent）：
+```
+report-pipeline =
+    >> Lam("extract", "Extract key facts from the input....")
+    >> Lam("analyze", "Analyze the facts and identify patter...")
+    >> Lam("report", "Write a structured report....")
+```
+
+JSON 格式：
+```bash
+python -m lambdagent lambda agent-config.yml --format json
+```
+
+---
+
+## tools — 列出和测试工具
+
+列出 Agent 配置中的所有可用工具，检查 MCP 服务器连接状态。
+
+```bash
+python -m lambdagent tools <config.yml> [--test TOOL INPUT] [--discover SERVER]
+```
+
+### 参数
+
+| 参数 | 说明 |
+|------|------|
+| `config` | YAML 配置文件路径 |
+| `--test TOOL INPUT` | 测试指定工具 |
+| `--discover SERVER` | 发现 MCP 服务器上的工具 |
+
+### 示例
+
+```bash
+python -m lambdagent tools agent-config.yml
+```
+
+输出：
+```
+Tools for my-agent:
+────────────────────────────────────────────────────────────
+  [MCP]   search                         mcp-server
+  [MCP]   read_file                      mcp-server
+  [Local] terminate                      (λx.x) base case
+
+MCP endpoints:
+  mcp-server: http://localhost:3001/mcp
+    Status: ✓ reachable (23ms)
+```
+
+---
+
+## version — 版本信息
+
+```bash
+python -m lambdagent version
+```
+
+```
+lambdagent v2.0.0
+Lambda Calculus Agent DSL
+11 core constructs — strict lambda correspondence
+```
+
+---
+
+## 高级用法
+
+### 1. JSON 输出用于程序化处理
+
+```bash
+# 完整 JSON 输出（result + trace + stats）
+python -m lambdagent run agent.yml "task" --format json | jq '.stats'
+
+# lint 结果 JSON（CI/CD 中判断是否阻塞部署）
+python -m lambdagent lint agent.yml --format json | jq '[.[] | select(.level=="ERROR")] | length'
+```
+
+### 2. 管道编排 Agent
+
+```bash
+# Agent A 的输出作为 Agent B 的输入（CLI 层面的 >> 组合）
+python -m lambdagent run extract.yml "raw data" --quiet | \
+  python -m lambdagent run analyze.yml - --quiet | \
+  python -m lambdagent run report.yml - --quiet > report.txt
+```
+
+### 3. 批量处理
+
+```bash
+# 对多个输入批量执行
+cat inputs.txt | while read line; do
+  python -m lambdagent run agent.yml "$line" --quiet >> results.txt
+done
+
+# lint 整个目录
+python -m lambdagent lint configs/ --level error
+```
+
+### 4. 工具注入 + ReAct 实战
+
+```bash
+# 日志分析 Agent（注入 grep + wc 工具）
+python -m lambdagent run react-agent.yml "分析今天的错误日志" \
+  --tool grep="grep ERROR /var/log/app.log" \
+  --tool count="wc -l /var/log/app.log" \
+  --tool tail="tail -20 /var/log/app.log" \
+  --trace
+
+# 代码搜索 Agent（参数化工具）
+python -m lambdagent run react-agent.yml "找出所有使用了 deprecated API 的文件" \
+  --tool search="grep -rn {} src/" \
+  --tool find="find src/ -name {} -type f" \
+  --max-steps 15
+```
+
+### 5. 模型对比
+
+```bash
+# 同一任务，不同模型
+python -m lambdagent run agent.yml "写一首关于AI的诗" --model claude-sonnet-4-20250514 --quiet > claude.txt
+python -m lambdagent run agent.yml "写一首关于AI的诗" --model gpt-4o --quiet > gpt4.txt
+diff claude.txt gpt4.txt
+```
+
+---
+
+## YAML 配置参考
+
+### 最小配置
+
+```yaml
+type: simple
+systemPrompt: "You are a helpful assistant."
+model:
+  name: claude-sonnet-4-20250514
+```
+
+### 完整 ReAct Agent
+
+```yaml
+agentId: research-agent
+name: ResearchAgent
+type: react
+systemPrompt: |
+  You are a research assistant. Use tools to find information,
+  then synthesize a comprehensive answer.
+
+model:
+  provider: anthropic
+  name: claude-sonnet-4-20250514
+  temperature: 0.0
+  maxTokens: 4096
+
+react:
+  maxSteps: 15
+  toolTimeout: 30
+  observationEnabled: true
+  verbose: false
+
+mcp:
+  onlineTool:
+    my-server:
+      - search
+      - read_file
+  localTools:
+    - terminate
+  policy:
+    mode: auto           # auto | force | intelligence | disable
+    retryOnFail: 1
+
+guard:
+  dangerousCommandBlock: true
+  highRiskConfirmation: false
+  maxOutputLength: 10000
+  validator: "len(x) > 10"
+  retry: 1
+  fallback: last
+
+memory:
+  enabled: true
+  strategy: local
+  size: 20
+  ttl: 3600
+
+app:
+  mcp:
+    custom:
+      nodes:
+        my-server:
+          url: http://localhost:3001
+          endpoint: /mcp
+          timeout: 30
+```
+
+### Agent 类型速查
+
+| type | Lambda 对应 | 说明 |
+|------|-------------|------|
+| `simple` | `λx. LLM(x)` | 单步 LLM 调用 |
+| `react` | `Y_n(λself.λstate. think >> route >> observe)` | ReAct 循环（工具调用） |
+| `chain` | `f >> g >> h` | 顺序执行管道 |
+| `router` | `CASE (classifier x) [(l₁, a₁), ...]` | 分类器路由 |
+| `parallel` | `(f \| g) >> merge` | 并行执行 + 合并 |
+
+---
+
+## 退出码
+
+| 退出码 | 说明 |
+|--------|------|
+| `0` | 成功 |
+| `1` | 一般错误（输入缺失、工具注入失败等） |
+| `3` | lint 存在 ERROR 级别问题 |
+| `4` | 文件未找到 |
+| `130` | 用户中断（Ctrl+C） |
+
+---
+
+# Part II — agentpaas CLI
+
+> AgentPaaS 平台管理 CLI。管理 API 服务器、租户、Agent 部署、运行监控和 LLM Provider。
+
+## 目录（agentpaas）
+
+- [快速开始](#快速开始)
+- [config — CLI 配置](#config--cli-配置)
+- [serve — 启动 API 服务器](#serve--启动-api-服务器)
+- [create-tenant — 创建租户](#create-tenant--创建租户)
+- [agent — Agent 管理](#agent--agent-管理)
+- [run — 执行 Agent（远程）](#run--执行-agent远程)
+- [status — 平台状态](#status--平台状态)
+- [health — Agent 健康度](#health--agent-健康度)
+- [runs — 运行历史](#runs--运行历史)
+- [trace — 运行追踪](#trace--运行追踪)
+- [key — API Key 管理](#key--api-key-管理)
+- [usage / metrics — 计费与指标](#usage--metrics--计费与指标)
+- [provider — LLM Provider 管理](#provider--llm-provider-管理)
+
+---
+
+## 快速开始
+
+```bash
+# 1. 启动 API 服务器（开发模式）
+python -m agentpaas serve --dev
+
+# 2. 创建租户并获取 API Key
+python -m agentpaas create-tenant --name "My Org"
+# 输出：
+#   Tenant: tn_xxxx
+#   API Key: ap_xxxx
+#   API key saved to config. Ready to use.
+
+# 3. 创建 Agent（从 YAML 配置）
+python -m agentpaas agent create --name my-agent --config agent-config.yml
+
+# 4. 执行 Agent
+python -m agentpaas run ag_xxxx "帮我写快速排序"
+
+# 5. 查看状态
+python -m agentpaas status
+```
+
+---
+
+## config — CLI 配置
+
+配置 CLI 连接参数（服务器地址、API Key）。配置保存在 `~/.agentpaas/config.json`。
+
+```bash
+# 查看当前配置
+python -m agentpaas config show
+
+# 设置服务器地址
+python -m agentpaas config set --server http://your-server:8000
+
+# 设置 API Key
+python -m agentpaas config set --api-key ap_your_api_key_here
+
+# 同时设置
+python -m agentpaas config set --server http://prod:8000 --api-key ap_xxxx
+```
+
+输出示例：
+```
+Server:  http://localhost:8000
+API Key: ap_abcdef12...
+Config:  /Users/you/.agentpaas/config.json
+```
+
+---
+
+## serve — 启动 API 服务器
+
+启动 AgentPaaS FastAPI 服务器。
+
+```bash
+python -m agentpaas serve [--host HOST] [--port PORT] [--dev]
+```
+
+| 参数 | 说明 |
+|------|------|
+| `--host` | 绑定地址（默认 `0.0.0.0`） |
+| `--port` | 端口（默认 `8000`） |
+| `--dev` | 开发模式（热重载） |
+
+### 示例
+
+```bash
+# 开发模式（自动重载）
+python -m agentpaas serve --dev
+
+# 生产模式（需要设置 AGENTPAAS_MASTER_KEY）
+export AGENTPAAS_MASTER_KEY=$(python -c "import secrets; print(secrets.token_hex(32))")
+python -m agentpaas serve --port 8080
+
+# 启动后可访问
+#   API 文档: http://localhost:8000/docs
+#   健康检查: http://localhost:8000/health
+```
+
+---
+
+## create-tenant — 创建租户
+
+直接操作数据库创建租户（不需要 API 服务器运行）。自动生成 admin 用户和 API Key。
+
+```bash
+python -m agentpaas create-tenant --name "组织名" [--plan free|pro] [--email admin@org.com]
+```
+
+| 参数 | 说明 |
+|------|------|
+| `--name` | 租户名称（必填） |
+| `--plan` | 套餐（`free`/`pro`，默认 `free`） |
+| `--email` | 管理员邮箱 |
+
+### 示例
+
+```bash
+python -m agentpaas create-tenant --name "Research Lab" --plan pro --email admin@lab.edu
+```
+
+输出：
+```
+Tenant: tn_a1b2c3d4
+API Key: ap_e5f6g7h8i9j0k1l2m3n4o5p6
+API key saved to config. Ready to use.
+```
+
+> API Key 只显示一次，请安全保存。Key 已自动写入 `~/.agentpaas/config.json`。
+
+---
+
+## agent — Agent 管理
+
+Agent 的完整生命周期管理：创建、查看、更新、删除、版本管理。
+
+### agent list — 列出所有 Agent
+
+```bash
+python -m agentpaas agent list
+```
+
+输出：
+```
+ID               Name                  Ver Status       Updated
+--------------------------------------------------------------------------------
+ag_abc123        ResearchBot             3 active       2026-04-01T10:30:00
+ag_def456        CodeReviewer            1 active       2026-03-28T14:20:00
+```
+
+### agent create — 创建 Agent
+
+```bash
+python -m agentpaas agent create --name <name> [--config <yaml>] [--prompt <text>] [--description <text>] [--tags <t1,t2>]
+```
+
+| 参数 | 说明 |
+|------|------|
+| `--name` | Agent 名称（必填） |
+| `--config` | YAML 配置文件路径 |
+| `--prompt` | 快速创建：直接指定 system prompt（不用 YAML） |
+| `--description` | Agent 描述 |
+| `--tags` | 逗号分隔的标签 |
+
+```bash
+# 从 YAML 创建
+python -m agentpaas agent create --name research-bot --config research-agent.yml --tags "research,rag"
+
+# 快速创建（无需 YAML）
+python -m agentpaas agent create --name quick-helper --prompt "You are a helpful coding assistant."
+```
+
+输出：
+```
+Agent created: ag_abc123
+Version: 1
+Endpoint: /api/v1/agents/ag_abc123
+```
+
+### agent get — 查看 Agent 详情
+
+```bash
+python -m agentpaas agent get ag_abc123
+```
+
+输出（JSON）：
+```json
+{
+  "id": "ag_abc123",
+  "name": "ResearchBot",
+  "current_version": 3,
+  "status": "active",
+  "config": { "type": "react", "systemPrompt": "..." },
+  "tags": ["research", "rag"]
+}
+```
+
+### agent update — 更新配置
+
+```bash
+python -m agentpaas agent update ag_abc123 --config new-config.yml --changelog "增加搜索工具"
+```
+
+> 自动版本递增。如果配置内容未变化，不会创建新版本。
+
+### agent rollback — 回滚版本
+
+```bash
+python -m agentpaas agent rollback ag_abc123 --version 2
+```
+
+### agent versions — 查看版本历史
+
+```bash
+python -m agentpaas agent versions ag_abc123
+```
+
+输出：
+```
+ Ver Current  Created              Changelog
+------------------------------------------------------------
+   3 *        2026-04-01T10:30:00  增加搜索工具
+   2          2026-03-30T09:00:00  优化 prompt
+   1          2026-03-28T14:20:00  Initial version
+```
+
+### agent delete — 删除 Agent
+
+```bash
+python -m agentpaas agent delete ag_abc123
+```
+
+> 软删除，不会物理删除数据。
+
+---
+
+## run — 执行 Agent（远程）
+
+通过 API 远程执行 Agent。
+
+```bash
+python -m agentpaas run <agent_id> [input] [--input-file FILE] [--temperature FLOAT] [--max-steps INT] [--stream]
+```
+
+| 参数 | 说明 |
+|------|------|
+| `agent_id` | Agent ID（如 `ag_abc123`） |
+| `input` | 输入文本 |
+| `--input-file` | 从文件读取输入 |
+| `--temperature` | 覆盖温度 |
+| `--max-steps` | 覆盖最大步数 |
+| `--stream` | 流式输出（预留） |
+
+### 示例
+
+```bash
+# 直接输入
+python -m agentpaas run ag_abc123 "帮我写一个快速排序"
+
+# 从文件读取
+python -m agentpaas run ag_abc123 --input-file task.txt
+
+# 覆盖参数
+python -m agentpaas run ag_abc123 "创意写作" --temperature 0.8 --max-steps 20
+```
+
+输出：
+```
+Running agent ag_abc123...
+
+--- Result (3.2s) ---
+def quicksort(arr):
+    if len(arr) <= 1:
+        return arr
+    pivot = arr[len(arr) // 2]
+    ...
+
+--- Stats ---
+  Run ID:    run_xyz789
+  Tokens:    1523 (in: 423, out: 1100)
+  Steps:     4
+  Duration:  3215ms
+```
+
+---
+
+## status — 平台状态
+
+查看平台总览或单个 Agent 的运行状态。
+
+```bash
+# 平台总览
+python -m agentpaas status
+
+# 所有 Agent 状态（含健康度评分）
+python -m agentpaas status agents [--sort last_run|score|runs]
+
+# 单个 Agent 详情
+python -m agentpaas status ag_abc123
+```
+
+### 平台总览
+
+```bash
+python -m agentpaas status
+```
+
+输出：
+```
+=== AgentPaaS Status ===
+  Active agents:  5
+  Total runs:     1247
+  Running now:    2
+  Success rate:   94.3%
+  Avg latency:    2341ms
+  Total tokens:   4523100
+```
+
+### Agent 状态仪表板
+
+```bash
+python -m agentpaas status agents
+```
+
+输出：
+```
+ID               Name              Score  Runs   Fail  Succ%  Lat(ms) Last Run
+----------------------------------------------------------------------------------------------------
+ag_abc123        ResearchBot       [+] 92    523     12    97.7%     2100 2026-04-01T10:30
+ag_def456        CodeReviewer      [~] 71    200     35    82.5%     4500 2026-04-01T09:15
+ag_ghi789        Translator        [!] 45     50     22    56.0%     8200 2026-03-30T18:00
+```
+
+> 健康度符号: `+` = healthy, `~` = degraded, `!` = warning, `X` = critical
+
+---
+
+## health — Agent 健康度
+
+查看单个 Agent 的详细健康评分和各维度指标。
+
+```bash
+python -m agentpaas health ag_abc123
+```
+
+输出：
+```
+[OK] Agent ag_abc123 health: 92/100 (healthy)
+  success_rate: 97.7%
+  avg_latency_ms: 2100
+  error_rate_1h: 1.2%
+  p99_latency_ms: 5800
+```
+
+---
+
+## runs — 运行历史
+
+查看 Agent 的运行历史记录。
+
+```bash
+python -m agentpaas runs <agent_id> [--limit N]
+```
+
+```bash
+python -m agentpaas runs ag_abc123 --limit 10
+```
+
+输出：
+```
+Run ID           Status      Dur(ms)  Steps   Tokens Created
+--------------------------------------------------------------------------------
+run_001          completed      2100      4     1523 2026-04-01T10:30:00
+run_002          completed      1800      3     1200 2026-04-01T09:15:00
+run_003          failed         5200      7     3100 2026-04-01T08:00:00
+```
+
+---
+
+## trace — 运行追踪
+
+查看单次运行的详细执行追踪（JSON 输出）。
+
+```bash
+python -m agentpaas trace <run_id>
+```
+
+```bash
+python -m agentpaas trace run_001
+```
+
+输出完整的 run 记录（JSON），包含 input、output、status、duration、tokens 等。
+
+---
+
+## key — API Key 管理
+
+### key create — 创建新 Key
+
+```bash
+python -m agentpaas key create --name <name> [--scopes <s1,s2>] [--rate-limit N]
+```
+
+| 参数 | 说明 |
+|------|------|
+| `--name` | Key 名称 |
+| `--scopes` | 权限范围（逗号分隔，默认 `agents:read,agents:execute`） |
+| `--rate-limit` | 每分钟请求限制（默认 60） |
+
+```bash
+# 创建只读 Key
+python -m agentpaas key create --name readonly-key --scopes "agents:read"
+
+# 创建高频 Key
+python -m agentpaas key create --name batch-key --scopes "agents:read,agents:execute" --rate-limit 600
+```
+
+输出：
+```
+Key created: key_abc123
+API Key: ap_xxxxxxxxxxxxxxxxxxxxxxxx
+Store this key securely!
+```
+
+### key list — 列出所有 Key
+
+```bash
+python -m agentpaas key list
+```
+
+输出：
+```
+ID               Prefix     Name             Status   Last Used
+----------------------------------------------------------------------
+key_abc123       ap_abcd    admin            active   2026-04-01T10:30
+key_def456       ap_efgh    readonly-key     active   2026-03-28T14:20
+```
+
+### key revoke — 吊销 Key
+
+```bash
+python -m agentpaas key revoke key_def456
+```
+
+---
+
+## usage / metrics — 计费与指标
+
+### usage — 使用量查询
+
+```bash
+python -m agentpaas usage [--group-by agent|model|day]
+```
+
+```bash
+# 按 Agent 统计
+python -m agentpaas usage --group-by agent
+
+# 按模型统计
+python -m agentpaas usage --group-by model
+
+# 按日统计
+python -m agentpaas usage --group-by day
+```
+
+### metrics — 平台指标
+
+```bash
+python -m agentpaas metrics
+```
+
+输出平台级别的聚合指标（JSON 格式）。
+
+---
+
+## provider — LLM Provider 管理
+
+管理 LLM 服务提供商配置。配置保存在 `~/.agentpaas/providers.json`，本地操作不需要 API 服务器。
+
+### 预置 Provider
+
+| ID | 名称 | 类型 | 环境变量 |
+|-----|------|------|---------|
+| `anthropic` | Anthropic Claude | anthropic | `ANTHROPIC_API_KEY` |
+| `openai` | OpenAI GPT | openai | `OPENAI_API_KEY` |
+| `dashscope` | DashScope (Qwen) | openai_compatible | `DASHSCOPE_API_KEY` |
+| `deepseek` | DeepSeek | openai_compatible | `DEEPSEEK_API_KEY` |
+| `zhipu` | Zhipu AI (GLM) | openai_compatible | `ZHIPU_API_KEY` |
+| `moonshot` | Moonshot (Kimi) | openai_compatible | `MOONSHOT_API_KEY` |
+| `ollama` | Ollama (Local) | openai_compatible | — |
+
+### provider list — 列出所有 Provider
+
+```bash
+python -m agentpaas provider list
+```
+
+输出：
+```
+ID              Name                      Base URL                                      Status
+----------------------------------------------------------------------------------------------------
+anthropic       Anthropic                 https://api.anthropic.com                     [OK]
+openai          OpenAI                    https://api.openai.com/v1                     [NO KEY (OPENAI_API_KEY)]
+dashscope       DashScope (Qwen)          https://dashscope.aliyuncs.com/compatible-mod [OK]
+ollama          Ollama (Local)            http://localhost:11434/v1                      [OK]
+```
+
+### provider add — 添加/更新 Provider
+
+```bash
+python -m agentpaas provider add <id> [--api-key KEY] [--base-url URL] [--name NAME] [--models m1,m2]
+```
+
+```bash
+# 配置 DashScope API Key
+python -m agentpaas provider add dashscope --api-key sk-xxxx
+
+# 添加自定义 Provider
+python -m agentpaas provider add my-llm \
+  --name "My LLM Service" \
+  --base-url https://my-llm.example.com/v1 \
+  --api-key sk-xxxx \
+  --models "my-model-7b,my-model-72b"
+```
+
+### provider test — 测试连接
+
+```bash
+python -m agentpaas provider test <id> [--api-key KEY] [--model MODEL] [--prompt TEXT]
+```
+
+```bash
+# 测试 Anthropic（使用环境变量中的 Key）
+python -m agentpaas provider test anthropic
+
+# 测试指定模型
+python -m agentpaas provider test dashscope --model qwen-max
+
+# 自定义测试 prompt
+python -m agentpaas provider test openai --prompt "Say hello in Chinese"
+```
+
+输出：
+```
+Testing dashscope (qwen3-max-2026-01-23)...
+OK (1.2s): 你好！有什么可以帮助你的吗？
+```
+
+### provider models — 查看可用模型
+
+```bash
+python -m agentpaas provider models <id>
+```
+
+```bash
+python -m agentpaas provider models dashscope
+```
+
+输出（从 API 动态查询）：
+```
+  qwen-max
+  qwen-plus
+  qwen-turbo
+  qwen3-max-2026-01-23
+```
+
+### provider remove — 移除 Provider
+
+```bash
+python -m agentpaas provider remove my-llm
+```
+
+---
+
+## 典型工作流
+
+### 1. 本地开发流程
+
+```bash
+# 启动服务
+python -m agentpaas serve --dev &
+
+# 创建租户
+python -m agentpaas create-tenant --name dev
+
+# 配置 LLM Provider
+python -m agentpaas provider add dashscope --api-key sk-xxxx
+python -m agentpaas provider test dashscope
+
+# 编写 + lint Agent 配置
+python -m lambdagent lint my-agent.yml
+python -m lambdagent compile my-agent.yml --validate
+
+# 本地测试（直接执行，不经过 PaaS）
+python -m lambdagent run my-agent.yml "test input" --trace
+
+# 部署到 PaaS
+python -m agentpaas agent create --name my-agent --config my-agent.yml
+
+# 远程执行
+python -m agentpaas run ag_xxxx "production input"
+
+# 监控
+python -m agentpaas status agents
+python -m agentpaas health ag_xxxx
+```
+
+### 2. 版本迭代流程
+
+```bash
+# 修改配置后更新
+python -m lambdagent lint my-agent-v2.yml
+python -m agentpaas agent update ag_xxxx --config my-agent-v2.yml --changelog "优化 prompt"
+
+# 查看版本
+python -m agentpaas agent versions ag_xxxx
+
+# 测试新版本
+python -m agentpaas run ag_xxxx "test input"
+
+# 如果有问题，回滚
+python -m agentpaas agent rollback ag_xxxx --version 1
+```
+
+### 3. 运维排查流程
+
+```bash
+# 查看整体状态
+python -m agentpaas status
+
+# 找到异常 Agent
+python -m agentpaas status agents --sort score
+
+# 查看健康详情
+python -m agentpaas health ag_xxxx
+
+# 查看最近运行
+python -m agentpaas runs ag_xxxx --limit 5
+
+# 查看失败运行的详情
+python -m agentpaas trace run_failed_xxx
+
+# 查看使用量
+python -m agentpaas usage --group-by agent
+```

docs/hook-system.md

@@ -0,0 +1,377 @@
+# Hook 系统在 Lambdagent 体系下的实现分析
+
+> 基于 Paper10 操作语义框架（`src/lambdagent/`）的设计分析
+> 日期：2026-04-01
+
+---
+
+## 一、Hook 的形式化本质
+
+"Hook" 在操作语义层面是在特定 CEK 转移规则触发的时刻插入额外计算。
+
+更精确地，一个 Hook 是一个 **Term 变换器** $H$：
+
+$$H : \text{Term} \to \text{Term}$$
+
+它将原始 Agent $a$ 包装成 $H(a)$，使得在 $a$ 的 β-规约的某个时刻（之前、之后、或条件判断中），$H$ 注入的计算被执行。
+
+**关键发现**：这个定义与 Lambdagent 的现有原语完全对齐——
+
+| Hook 类型 | 对应 Lambdagent 原语 | CEK 触发规则 |
+|---|---|---|
+| Pre-hook（执行前拦截）| `Compose(Tool(pre_fn), agent)` | C-Comp + C-Tool |
+| Post-hook（执行后处理）| `Compose(agent, Tool(post_fn))` | C-CompRet + C-Tool |
+| Guard-hook（条件拦截/阻断）| `Guard(agent, validator, k)` | C-Guard + C-GuardOK/Retry/Fail |
+| Event-hook（观察但不干预）| CEK Machine 的 Transition trace | 所有规则 |
+
+---
+
+## 二、三种实现策略
+
+### Layer 1：Term-Level Hook（纯 Lambda 演算，零基础设施改动）
+
+Hook 直接编码为现有原语的组合，**今天就能实现**：
+
+```python
+from lambdagent.primitives import Lam, Compose, Tool
+from lambdagent.extensions import Guard
+
+# Pre-hook: 执行前校验/记录
+def pre_hook(fn):
+    """装饰器：在 agent 执行前运行 fn（不修改输入）"""
+    def wrapper(agent):
+        side_effect = Tool("pre_hook", lambda x: (fn(x), x)[1])  # pass-through
+        return Compose(side_effect, agent)
+    return wrapper
+
+# Post-hook: 执行后处理/记录
+def post_hook(fn):
+    """装饰器：在 agent 执行后运行 fn（可修改输出）"""
+    def wrapper(agent):
+        transformer = Tool("post_hook", fn)
+        return Compose(agent, transformer)
+    return wrapper
+
+# Blocking-hook: 条件阻断（等价于 Guard）
+def blocking_hook(predicate, retry=0):
+    """装饰器：输出不满足 predicate 时重试或阻断"""
+    def wrapper(agent):
+        return Guard(agent, predicate, k=retry)
+    return wrapper
+```
+
+**使用示例**：
+
+```python
+import logging
+
+@pre_hook(lambda x: logging.info(f"[PreHook] input={x}"))
+@post_hook(lambda x: x.upper())
+@blocking_hook(lambda x: len(x) < 500, retry=2)
+def my_agent():
+    return Lam("writer", "Write a short summary:", "gpt-4o-mini")
+
+# 展开后等价于：
+# Guard(
+#   Compose(
+#     Tool(log_fn),
+#     Compose(Lam("writer",...), Tool(uppercase))
+#   ),
+#   predicate=lambda x: len(x) < 500,
+#   k=2
+# )
+```
+
+**优点**：符合 Paper10 的操作语义——Hook 就是 Lambda 项，可被形式推理。
+**局限**：无法在 Tool/LLM 调用的**内部**（C-Lam 规则触发的瞬间）插入逻辑。
+
+---
+
+### Layer 2：HookTerm（混合方案，与形式语义完全兼容）
+
+将 Hook 建模为一个**新的 Term**，具有自己的小步规则，在 Paper10 的形式体系内完全可推理：
+
+```python
+class HookTerm(Term):
+    """
+    Hook 作为一等 Lambda 项
+
+    小步规则（新增 E-Hook*）：
+      E-HookPre:  ⟨Hook(a,pre,post) v, E, K, σ, c⟩
+                  → ⟨a v, E, HookK(post, v) :: K, σ, c⟩
+
+      E-HookPost: ⟨v, E, HookK(post, orig) :: K, σ, c⟩
+                  → ⟨post(v), E, K, σ, c⟩
+    """
+    def __init__(
+        self,
+        agent: Term,
+        pre:  Callable | None = None,   # pre(input) → None (side effect only)
+        post: Callable | None = None,   # post(output) → output (可变换输出)
+        event_filter: set[str] | None = None,  # {'llm', 'tool', 'guard', ...}
+    ):
+        super().__init__(f"Hook({agent._name})")
+        self.agent = agent
+        self.pre  = pre  or (lambda x: x)
+        self.post = post or (lambda x: x)
+        self.event_filter = event_filter
+
+    def apply(self, input, ctx=None):
+        ctx = ctx or Context()
+        self.pre(input)                   # E-HookPre fires
+        result = self.agent.apply(input, ctx)
+        return self.post(result)          # E-HookPost fires
+```
+
+对应两条新的小步规则（可写入 Paper10 §4）：
+
+```
+E-HookPre:
+  ⟨Hook(a, pre, post) v, E, K, σ, c⟩
+  —→τ  ⟨a v, E, HookK(post, v) :: K, σ, c⟩
+  (前提: pre(v) 已求值)
+
+E-HookPost:
+  ⟨v', E, HookK(post, orig) :: K, σ, c⟩
+  —→τ  ⟨post(v'), E, K, σ, c⟩
+```
+
+---
+
+### Layer 3：Machine-Level Hook（Observer 模式，扩展 CEK Machine）
+
+在 CEK Machine 的精确位置注入回调，**只需改动 `cek_machine.py` 约 30 行**：
+
+```python
+from dataclasses import dataclass, field
+from typing import Callable, List
+
+@dataclass
+class HookRegistry:
+    """
+    Hook 注册表：在 CEK 转移规则触发点插入回调
+
+    事件类型（对应 CEK 规则）：
+      pre_llm        — C-Lam 触发前（LLM 调用前）
+      post_llm       — C-Lam 完成后（LLM 响应后，可修改输出）
+      pre_tool       — C-Tool 触发前
+      post_tool      — C-Tool 完成后
+      on_guard_ok    — C-GuardOK
+      on_guard_retry — C-GuardRetry
+      on_guard_fail  — C-GuardFail
+      on_loop_unfold — C-LoopUnfold
+      on_step        — 每次 CEK 转移后
+      on_halt        — 机器终止时
+    """
+    pre_llm:        List[Callable] = field(default_factory=list)
+    post_llm:       List[Callable] = field(default_factory=list)
+    pre_tool:       List[Callable] = field(default_factory=list)
+    post_tool:      List[Callable] = field(default_factory=list)
+    on_guard_ok:    List[Callable] = field(default_factory=list)
+    on_guard_retry: List[Callable] = field(default_factory=list)
+    on_guard_fail:  List[Callable] = field(default_factory=list)
+    on_loop_unfold: List[Callable] = field(default_factory=list)
+    on_step:        List[Callable] = field(default_factory=list)
+    on_halt:        List[Callable] = field(default_factory=list)
+
+    def register(self, event: str, fn: Callable):
+        getattr(self, event).append(fn)
+
+    def fire(self, event: str, **kwargs):
+        for fn in getattr(self, event, []):
+            fn(**kwargs)
+```
+
+`_dispatch_app` 中插入钩子点（以 C-Lam 为例）：
+
+```python
+def _dispatch_app(self, op, arg):
+    s = self.state
+
+    if isinstance(op, Lam):
+        # ★ Pre-LLM Hook
+        self.hooks.fire("pre_llm", term=op, input=arg, state=s)
+
+        result = op.apply(arg, ctx)
+
+        # ★ Post-LLM Hook（hook 可通过 dict 修改输出）
+        hook_result = {"value": result}
+        self.hooks.fire("post_llm", term=op, input=arg,
+                        output=hook_result, cost=cost_llm, state=s)
+        result = hook_result["value"]
+
+        s.control = result
+        return "C-Lam", label
+```
+
+**实际使用**：
+
+```python
+registry = HookRegistry()
+
+# 成本审计
+registry.register("post_llm", lambda term, input, output, cost, state:
+    print(f"[Audit] {term._name}: {cost.tokens} tokens"))
+
+# PII 过滤
+import re
+def pii_filter(term, input, output, cost, state):
+    output["value"] = re.sub(r'\b\d{11}\b', '[PHONE]', str(output["value"]))
+registry.register("post_llm", pii_filter)
+
+# Guard 失败报警
+registry.register("on_guard_fail", lambda **kw:
+    send_alert(f"Guard failed: {kw['term']._name}"))
+
+machine = AgentCEKMachine(hooks=registry)
+result = machine.run(my_agent, "input")
+```
+
+---
+
+## 三、三层可以并存（不是三选一）
+
+### 正交性
+
+三层的**作用域完全正交**，分别作用于不同的对象：
+
+```
+Layer 3: Machine-Level Hook
+│  作用域：CEK Machine 的所有转移，全局、跨切面
+│  对象：执行（execution）
+│
+└─► 观察并包含 ↓
+    Layer 2: HookTerm
+    │  作用域：特定 Term 的包装，局部、可复用
+    │  对象：程序结构（term structure）
+    │
+    └─► 展开为 ↓
+        Layer 1: Compose + Tool + Guard
+           作用域：单次、内联的变换
+           对象：Lambda 项的代数组合
+```
+
+Layer 1/2 是"程序长什么样"，Layer 3 是"程序运行时发生了什么"。
+
+### Layer 3 "看到" Layer 2 的内部
+
+当 Layer 2 的 `HookTerm` 执行时，它内部的 `pre_fn` 和 `post_fn` 在 CEK Machine 里触发 `C-Tool` 规则，Layer 3 的 `pre_tool`/`post_tool` 钩子会**同样观察到它们**：
+
+```
+执行 HookTerm(Lam("writer"), pre=log, post=upper) 时：
+
+CEK 序列：
+  C-Hook
+  → C-Tool(log)      ← Layer 3 的 pre_tool hook 也触发
+  → C-Lam(writer)    ← Layer 3 的 pre_llm/post_llm 触发
+  → C-Tool(upper)    ← Layer 3 的 post_tool hook 也触发
+```
+
+### 唯一的危险：重复触发
+
+如果三层对同一事件做同一件事，会触发多次：
+
+```python
+# ❌ 错误：三层都在记录同一个 LLM 的输出
+agent = Compose(Lam("writer", ...), Tool("log1", log_fn))   # Layer 1
+agent = HookTerm(agent, post=log_fn)                         # Layer 2 再记录
+registry.register("post_llm", lambda **kw: log_fn(...))     # Layer 3 再记录
+```
+
+解决方法：**不同层负责不同关切**。
+
+---
+
+## 四、推荐的职责划分
+
+| 层级 | 定位 | 典型用途 | 特点 |
+|---|---|---|---|
+| **Layer 3** | 基础设施层 | 全局 token 审计、限流、OpenTelemetry、异常上报 | 对业务代码透明 |
+| **Layer 2** | 策略层 | PII 过滤、安全沙盒、领域特定 retry 策略 | 作为库主动引用 |
+| **Layer 1** | 业务层 | 一次性输入预处理、快速原型调试打印 | 内联写在业务中 |
+
+---
+
+## 五、并存示例
+
+```python
+# ── Layer 3: 全局基础设施（系统级，一次性配置）──
+registry = HookRegistry()
+registry.register("post_llm", cost_auditor)      # 审计所有 LLM 调用
+registry.register("on_guard_fail", pager_duty)   # 任何 Guard 失败就报警
+machine = AgentCEKMachine(hooks=registry)
+
+# ── Layer 2: 领域策略（库级，按需引用）──
+class MedicalHook(HookTerm):
+    """医疗场景专用：PII 过滤 + HIPAA 合规日志"""
+    def __init__(self, agent):
+        super().__init__(
+            agent,
+            pre=lambda x: verify_patient_consent(x),
+            post=lambda x: strip_pii(x),
+        )
+
+# ── Layer 1: 业务逻辑（业务级，内联）──
+diagnosis_agent = MedicalHook(           # Layer 2 包装
+    Compose(
+        Tool("fetch_ehr", get_records),  # Layer 1 inline
+        Lam("diagnoser", MEDICAL_PROMPT),
+        Tool("format_icd", icd_encoder), # Layer 1 inline
+    )
+)
+
+# Layer 3 的 registry 自动观察整个执行过程
+result = machine.run(diagnosis_agent, patient_id)
+```
+
+执行时每一层做自己该做的事：
+
+```
+Layer 3 看到：fetch_ehr → verify_consent → diagnoser_llm → strip_pii → format_icd
+              └─ cost_auditor 汇总所有 LLM token ─────────────────────────────────┘
+
+Layer 2 做了：verify_consent（pre）和 strip_pii（post）
+
+Layer 1 做了：fetch_ehr 和 format_icd 的数据流组合
+```
+
+---
+
+## 六、与 Claude Code Hook 系统的映射
+
+Claude Code 的 Hook 事件类型与 Lambdagent CEK 规则的精确对应：
+
+| Claude Code Hook | Lambdagent 对应 | CEK 触发点 |
+|---|---|---|
+| `PreToolUse` | `HookTerm(tool, pre=fn)` | C-Tool 之前 |
+| `PostToolUse` | `HookTerm(tool, post=fn)` | C-ToolRet 之后 |
+| `Stop` | `Guard(agent, λv.False, 0)` | C-GuardFail |
+| `Notification` | `Tool(notify_fn)` in trace | on_step callback |
+| `SubagentStop` | Loop bound check | C-LoopBound |
+
+---
+
+## 七、形式化角度：代数效果的三层
+
+这个结构在 PL 理论里对应**代数效果（Algebraic Effects）的处理器栈**：
+
+```
+Effect handlers (Layer 3)   ←  全局 handler，捕获所有 perform
+        ↕
+Effect operations (Layer 2) ←  局部 perform，可复用
+        ↕
+Pure terms (Layer 1)        ←  无效果的纯变换
+```
+
+三层天然并存，因为它们描述的是**同一个计算的不同视角**，不是同一个问题的三个备选解法：
+
+- 选一层 → 只有一个视角
+- 三层并存 → 完整的可观测性（Layer 3）+ 可复用性（Layer 2）+ 灵活性（Layer 1）
+
+---
+
+## 八、结论
+
+> **Hook 系统不是 Lambdagent 体系之外的东西，它本身就是 Lambda 演算的 `Compose`（函数组合）和 `Guard`（依赖类型验证）的特例。**
+
+Claude Code 的 Hook 系统在形式上等价于在 CEK Machine 的 YIELD 点（LLM/Tool 调用前后）插入额外的 β-规约步骤。三层实现策略分别对应 Lambda 演算代数、一等 Term 扩展、执行时观察者三个层次，正交互补，推荐并存使用。

IDEA.md → docs/idea.md

@@ -523,3 +523,516 @@ agent = from_config("agent-cofig.yml")
 result = agent("帮我写一个快速排序", ctx)
 ctx.print_trace()  # 每步 β-规约可见、可调试、可验证
 ```
+
+---
+
+## 附录 A：YAML Agent Configuration Schema 完整参考
+
+> `from_config("agent-config.yml")` 编译器接受的 YAML 配置格式完整说明。
+> 每个字段标注：类型、是否必填、默认值、约束、对应的 Lambda 构造、相关 lint 规则。
+
+### A.1 根级元数据
+
+| 字段 | 类型 | 必填 | 默认值 | Lambda 语义 | 说明 |
+|------|------|------|--------|-------------|------|
+| `agentId` | string | 否 | `"agent"` | Term 标识符 | Agent 唯一标识 |
+| `name` | string | 否 | 同 agentId | Term.name | 显示名称 |
+| `description` | string | 否 | `""` | — | 描述性文本 |
+| `type` | enum | **是** | — | 决定顶层 Lambda 构造 | `simple` \| `react` \| `chain` \| `router` \| `parallel` |
+
+**Schema 规则**: S001 (type 缺失 → ERROR), S002 (type 非法值 → ERROR)
+
+**Lint 规则**: L000 (框架检测, 自动识别 crewai/autogen/langchain/dify/lambdagent)
+
+### A.2 Agent 类型与 Lambda 映射
+
+| type | Lambda 构造 | 公式 | 说明 |
+|------|------------|------|------|
+| `simple` | Lam | `λx. LLM(prompt, x)` | 单次 LLM 调用 |
+| `react` | Loop (Y combinator) | `Y_n(λself.λstate. think >> route >> observe)` | ReAct 循环，n = maxSteps |
+| `chain` | Compose | `λx. step_N(... step_2(step_1(x)))` | 顺序管道 |
+| `router` | Route (CASE) | `λx. CASE(classifier(x)) [(l₁,a₁), (l₂,a₂), ...]` | 条件分派 |
+| `parallel` | Par (PAIR) | `λx. PAIR(a₁(x))(a₂(x))` | 并行执行 |
+
+### A.3 systemPrompt — Lambda 函数体
+
+| 字段 | 类型 | 必填 | 默认值 | Lambda 语义 |
+|------|------|------|--------|-------------|
+| `systemPrompt` | string (多行) | type=simple/react 时**是** | `"You are a helpful assistant."` | `λx. body` 中的 body |
+
+**Schema 规则**: S003 (simple/react 缺失 → ERROR)
+**Lint 规则**: L001 (空 prompt → ERROR, CrewAI 允许用 role+goal+backstory 替代)
+
+```yaml
+systemPrompt: |
+  你是一个编程助手。
+  你能使用工具解决问题。
+```
+
+### A.4 model — LLM 参数 (概率 Lambda 参数)
+
+| 字段 | 类型 | 必填 | 默认值 | Lambda 语义 | 约束 |
+|------|------|------|--------|-------------|------|
+| `model.provider` | string | 否 | `"anthropic"` | LLM 后端选择 | `anthropic` \| `openai` \| `dashscope` \| `ollama` |
+| `model.name` | string | 否 | 按 provider 默认 | 模型 ID | Anthropic 默认 `claude-sonnet-4-20250514`，OpenAI 默认 `gpt-4o`，DashScope 默认 `qwen-max` |
+| `model.temperature` | float | 否 | `0.0` | `⊕_p` 概率参数 | `[0.0, 2.0]` |
+| `model.maxTokens` | int | 否 | `1024` | 输出长度上限 | `> 0` |
+| `model.topP` | float | 否 | — | 核采样参数 | `(0.0, 1.0]` |
+| `model.stopSequences` | list[string] | 否 | `[]` | 停止序列 | — |
+| `model.baseUrl` | string | 否 | `""` | 自定义 API 端点 | 完整 URL |
+
+**Schema 规则**: S009 (temperature 超范围 → WARN)
+**Lint 规则**: L002 (无 model → ERROR), L007 (temperature > 1.5 → WARN), L014 (temperature=0 → INFO)
+
+**Provider 默认模型解析** (`_resolve_model()`):
+```
+provider=anthropic, name="" → "claude-sonnet-4-20250514"
+provider=openai,    name="" → "gpt-4o"
+provider=dashscope, name="" → "qwen-max"
+provider≠anthropic, name有值 → "{provider}/{name}"
+```
+
+**子 Agent 继承**: chain.steps / router.routes / parallel.agents 中的子 Agent 若未指定 model，继承父级 model 配置。
+
+```yaml
+model:
+  provider: dashscope
+  name: qwen3-max-2026-01-23
+  temperature: 0.7
+  maxTokens: 4096
+```
+
+### A.5 react — ReAct 循环配置 (Y 组合子参数)
+
+仅当 `type: react` 时生效。
+
+| 字段 | 类型 | 必填 | 默认值 | Lambda 语义 | 约束 |
+|------|------|------|--------|-------------|------|
+| `react.maxSteps` | int | 否 | `10` | Y 组合子展开上限 `Y_n` | `> 0`，建议 `<= 1000` |
+| `react.observationEnabled` | bool | 否 | `true` | 是否将工具输出注入状态 | — |
+| `react.toolTimeout` | int | 否 | `30` | 单个工具调用超时 (秒) | `> 0` |
+| `react.verbose` | bool | 否 | `false` | 打印每步 β-规约详情 | — |
+
+**Schema 规则**: S004 (maxSteps <= 0 → ERROR)
+**Lint 规则**:
+- L003 (maxSteps=0 → ERROR: `Y_0(g) = ⊥`)
+- L004a (无 terminate 工具且无替代终止 → ERROR)
+- L004b (无 terminate 但有有界回退 → WARN)
+- L004c/d (框架内置终止机制 → INFO)
+- L010 (maxSteps > 50 → WARN: 高成本)
+- L011 (无工具仅 terminate → WARN: 纯推理)
+- L017 (未显式设置 maxSteps → WARN)
+- L018 (maxSteps > 100 → WARN: 近似无界)
+- L022 (有 terminate 但无 maxSteps 回退 → WARN)
+
+**编译行为** (`_compile_react()`):
+1. systemPrompt + model → `Lam("agent.think", prompt, model)`
+2. MCP + localTools → `Dict[str, Tool]` (经 ToolGateway 包装)
+3. 生成 `react_step` 闭包 (包含 state 压缩、隐式终止检测、工具缓存)
+4. 包装为 `Loop(body=react_step, condition=stop_condition, max_steps=N)`
+
+**内置优化**:
+- **P0 状态压缩**: 仅保留最近 3 步完整内容，旧步骤摘要为 action+observation 前 120 字符
+- **P1 隐式终止**: 检测 LLM 输出中的终止信号 ("final answer:", "task complete" 等 11 个中英文模式)
+- **P2 工具缓存**: LRU 缓存 (64 条目)，相同 tool+input 不重复调用
+- **P2 观察截断**: 工具输出超过 800 字符自动截断
+
+```yaml
+react:
+  maxSteps: 20
+  observationEnabled: true
+  toolTimeout: 30
+  verbose: true
+```
+
+### A.6 chain — 管道配置 (函数组合)
+
+仅当 `type: chain` 时生效。
+
+| 字段 | 类型 | 必填 | 默认值 | Lambda 语义 |
+|------|------|------|--------|-------------|
+| `chain.steps` | list[object] | **是** | — | `Compose(step1, step2, ...)` |
+| `chain.steps[].name` | string | 否 | `"step_{i}"` | 步骤名称 |
+| `chain.steps[].prompt` | string | **是** | `""` | `λx. body` |
+| `chain.steps[].model` | object | 否 | 继承父级 | 可覆盖模型 |
+| `chain.steps[].guard` | object | 否 | — | 步骤级 Guard |
+
+**Schema 规则**: S005 (steps 为空 → ERROR)
+**Lint 规则**: L006 (空 steps → ERROR), L024 (重复 agent name → WARN)
+
+```yaml
+type: chain
+chain:
+  steps:
+    - name: researcher
+      prompt: "研究以下主题..."
+    - name: writer
+      prompt: "基于研究结果撰写报告..."
+      model:
+        temperature: 0.8
+```
+
+### A.7 router — 路由配置 (CASE 分派)
+
+仅当 `type: router` 时生效。
+
+| 字段 | 类型 | 必填 | 默认值 | Lambda 语义 |
+|------|------|------|--------|-------------|
+| `router.classifier` | object | **是** | — | 分类器 Lam |
+| `router.classifier.prompt` | string | **是** | `"Classify the input."` | 分类 prompt |
+| `router.classifier.model` | object | 否 | 继承父级 | 可覆盖模型 |
+| `router.routes` | Dict[string, object] | **是** | — | `{label: sub_agent}` |
+| `router.default` | object | 否 | `None` | 默认路由 (未匹配时) |
+
+**Schema 规则**: S006 (routes 为空 → ERROR), S007 (classifier 缺失 → ERROR)
+**Lint 规则**: L005 (空 routes → ERROR), L013 (无 default → WARN), L023 (空 target → ERROR)
+
+```yaml
+type: router
+router:
+  classifier:
+    prompt: "将输入分类为 'code' 或 'writing'"
+  routes:
+    code:
+      type: react
+      systemPrompt: "你是代码专家..."
+    writing:
+      type: simple
+      systemPrompt: "你是写作专家..."
+  default:
+    type: simple
+    systemPrompt: "通用助手..."
+```
+
+### A.8 parallel — 并行配置 (PAIR)
+
+仅当 `type: parallel` 时生效。
+
+| 字段 | 类型 | 必填 | 默认值 | Lambda 语义 |
+|------|------|------|--------|-------------|
+| `parallel.agents` | list[object] | **是** (>=2) | — | `Par(a1, a2, ...)` |
+| `parallel.merge` | enum | 否 | `"tuple"` | 结果合并策略 |
+| `parallel.mergePrompt` | string | 否 | `"Synthesize..."` | merge=custom 时的合并 prompt |
+
+`merge` 取值:
+- `tuple`: 返回原始元组 `(result1, result2, ...)`
+- `concat`: 拼接所有结果 `"\n\n".join(results)`
+- `custom`: 用 mergePrompt 的 Lam 合并 `Par >> format >> Lam(mergePrompt)`
+
+**Schema 规则**: S008 (agents < 2 → ERROR)
+
+```yaml
+type: parallel
+parallel:
+  agents:
+    - type: simple
+      name: analyst
+      systemPrompt: "分析市场趋势..."
+    - type: simple
+      name: researcher
+      systemPrompt: "调研竞品..."
+  merge: custom
+  mergePrompt: "综合以上分析，给出结论..."
+```
+
+### A.9 mcp — 工具配置 (Tool / Oracle)
+
+| 字段 | 类型 | 必填 | 默认值 | Lambda 语义 |
+|------|------|------|--------|-------------|
+| `mcp.onlineTool` | Dict[server, list[tool_name]] | 否 | `{}` | `Tool(name, mcp_caller)` |
+| `mcp.localTools` | list[string] | 否 | `[]` | 本地工具列表 |
+| `mcp.policy.mode` | enum | 否 | `"auto"` | 工具策略 |
+| `mcp.policy.retryOnFail` | int | 否 | `0` | MCP 调用重试次数 |
+
+`mcp.policy.mode` 取值: `auto` \| `force` \| `intelligence` \| `disable`
+`mcp.localTools` 特殊值: `terminate` 编译为 `Tool("terminate", λx.x)` (恒等函数 = Y 组合子基 case)
+
+**Lint 规则**: L004 系列 (react 无 terminate), L011 (无工具仅 terminate), L026 (远程依赖检测)
+
+```yaml
+mcp:
+  onlineTool:
+    example-mcp-server:
+      - search_tool
+      - calculate_tool
+  localTools:
+    - terminate
+  policy:
+    mode: auto
+    retryOnFail: 1
+```
+
+### A.10 app.mcp.custom.nodes — MCP 服务器连接配置
+
+| 字段 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `app.mcp.custom.nodes.{server_name}.url` | string | **是** | `""` | MCP 服务器 URL |
+| `app.mcp.custom.nodes.{server_name}.endpoint` | string | 否 | `""` | API 路径 (拼接在 url 后) |
+| `app.mcp.custom.nodes.{server_name}.headers` | Dict[string, string] | 否 | `{}` | 请求头 (支持 `${ENV_VAR}` 引用) |
+| `app.mcp.custom.nodes.{server_name}.timeout` | int | 否 | `30` | 超时秒数 |
+| `app.mcp.custom.nodes.{server_name}.retry` | int | 否 | `0` | 重试次数 |
+
+```yaml
+app:
+  mcp:
+    custom:
+      nodes:
+        my-server:
+          url: https://mcp.example.com
+          endpoint: /mcp/v1
+          headers:
+            Authorization: "${MCP_AUTH_TOKEN}"
+          timeout: 30
+```
+
+### A.11 memory — 记忆配置 (环境扩展 Γ')
+
+| 字段 | 类型 | 必填 | 默认值 | Lambda 语义 |
+|------|------|------|--------|-------------|
+| `memory.enabled` | bool | 否 | `false` | 是否启用 `Memory(agent, store)` |
+| `memory.strategy` | enum | 否 | `"local"` | 存储后端 |
+| `memory.size` | int | 否 | `20` | 最大条目数 (LRU) |
+| `memory.ttl` | int | 否 | `3600` | 条目过期秒数 |
+
+`memory.strategy` 取值: `local` (内存 dict) \| `redis` (分布式) \| `sqlite` (持久化)
+
+**Lint 规则**:
+- L008 (ttl=0 → WARN: 绑定永不过期)
+- L009 (size=0 → WARN: 记忆无效)
+- L015 (启用 → INFO: 显示策略参数)
+
+**编译行为**: 编译为 `Memory(agent, store)` 包装在最外层（Guard 之后）
+
+```yaml
+memory:
+  enabled: true
+  strategy: redis
+  size: 20
+  ttl: 7200
+```
+
+### A.12 guard — 输出验证 + 安全策略 (依赖类型 `{x:T | P(x)}`)
+
+| 字段 | 类型 | 必填 | 默认值 | Lambda 语义 | 说明 |
+|------|------|------|--------|-------------|------|
+| `guard.validator` | string (Python expr) | 否 | `"True"` | 谓词 `P(x)` | eval 执行，可用变量: `x, len, str, int, float` |
+| `guard.retry` | int | 否 | `0` | 验证失败重试次数 | — |
+| `guard.fallback` | enum | 否 | `"error"` | 最终失败策略 | `error` \| `empty` \| `last` |
+| `guard.maxOutputLength` | int | 否 | `0` (不限) | 输出长度上限 | 超限 → 触发 retry 或 truncate |
+| `guard.dangerousCommandBlock` | bool | 否 | `false` | 启用 ToolGateway | CRITICAL/HIGH 命令自动阻止 |
+| `guard.highRiskConfirmation` | bool | 否 | `false` | HIGH 需确认 | 触发 confirm_callback |
+
+**Lint 规则**: L012 (retry > 5 → WARN), L025 (有 guard 但无 retry → WARN)
+
+**编译行为**:
+1. `dangerousCommandBlock` / `highRiskConfirmation` / `maxOutputLength` → 构建 `ToolGateway(GatewayPolicy)` → 所有 Tool 包装为 `GatedTool`
+2. `validator` / `retry` / `fallback` → 构建 `Guard(agent, validator_fn, retry, on_fail)` 包装在 Memory 之前
+
+**ToolGateway 风险分级** (50+ regex 规则):
+
+| 级别 | 示例命令 | 默认行为 |
+|------|---------|---------|
+| CRITICAL (22 规则) | `rm -rf /`, `curl\|sh`, `cat ~/.ssh/*`, fork bomb | 始终 BLOCK |
+| HIGH (18 规则) | `sudo`, `rm -r`, `pip install`, `kill -9`, `git push --force` | `dangerousCommandBlock` → BLOCK；`highRiskConfirmation` → CONFIRM |
+| MEDIUM (10 规则) | `mv`, `sed -i`, `git rebase`, `cp -r` | LOG_ONLY |
+| LOW | 文件写入, MCP 远程调用 | ALLOW + log |
+| SAFE | `ls`, `cat`, `git status`, `terminate` | ALLOW |
+
+```yaml
+guard:
+  validator: "len(x) > 10 and 'error' not in x.lower()"
+  retry: 2
+  fallback: last
+  maxOutputLength: 3000
+  dangerousCommandBlock: true
+  highRiskConfirmation: true
+```
+
+### A.13 rag — 检索增强生成
+
+| 字段 | 类型 | 必填 | 默认值 | Lambda 语义 |
+|------|------|------|--------|-------------|
+| `rag.enabled` | bool | 否 | `false` | 是否启用 RAG |
+| `rag.source` | string | 否 | `""` | 数据源路径 |
+| `rag.topK` | int | 否 | `5` | 检索返回条数 |
+| `rag.chunkSize` | int | 否 | `500` | 分块大小 |
+| `rag.backend` | enum | 否 | `"simple"` | 向量存储后端 |
+| `rag.minScore` | float | 否 | `0.0` | 最低相关度阈值 |
+
+`rag.backend` 取值: `simple` (TF-IDF, 零依赖) \| `chroma` (ChromaDB)
+
+**Lint 规则**: L016 (启用 → INFO)
+
+```yaml
+rag:
+  enabled: true
+  source: ./docs/
+  topK: 5
+  backend: simple
+```
+
+### A.14 完整示例
+
+```yaml
+# === 完整 Agent 配置示例 ===
+
+agentId: seeCoderManus
+name: SeeCoderManus
+description: 智能编程助手
+type: react
+
+model:
+  provider: dashscope
+  name: qwen3-max-2026-01-23
+  temperature: 0.7
+  maxTokens: 4096
+
+systemPrompt: |
+  你是 SeeCoderManus，一个智能编程助手。
+  你能够帮助用户解决编程问题。
+
+react:
+  maxSteps: 20
+  observationEnabled: true
+  toolTimeout: 30
+  verbose: true
+
+mcp:
+  onlineTool:
+    example-mcp-server:
+      - search_tool
+  localTools:
+    - terminate
+  policy:
+    mode: auto
+
+app:
+  mcp:
+    custom:
+      nodes:
+        example-mcp-server:
+          url: https://mcp.example.com
+          endpoint: /mcp/v1
+          headers:
+            Authorization: "${MCP_AUTH_TOKEN}"
+
+memory:
+  enabled: true
+  strategy: redis
+  size: 20
+  ttl: 7200
+
+guard:
+  dangerousCommandBlock: true
+  highRiskConfirmation: true
+  maxOutputLength: 3000
+  validator: "len(x) > 0"
+  retry: 1
+  fallback: last
+
+rag:
+  enabled: false
+```
+
+### A.15 编译流程总览
+
+```
+YAML 文件
+    │
+    ▼
+[yaml.safe_load()] ← 安全加载，禁止 yaml.load()
+    │
+    ▼
+[validate_schema(cfg)] ← S001-S009 规则
+    │ 有 ERROR → 抛出 SchemaError
+    ▼
+[build_agent(cfg, overrides)]
+    │
+    ├─ [_build_gateway(guard_cfg)] → ToolGateway (如有安全字段)
+    │
+    ├─ 按 type 分派:
+    │   ├─ simple  → _compile_simple()  → Lam
+    │   ├─ react   → _compile_react()   → Loop(react_step, condition, maxSteps)
+    │   ├─ chain   → _compile_chain()   → Compose(*steps)
+    │   ├─ router  → _compile_router()  → Route(classifier, routes, default)
+    │   └─ parallel→ _compile_parallel()→ Par(*agents) [>> merge]
+    │
+    ├─ [_compile_guard(agent, guard_cfg)] → Guard(agent, validator, retry, on_fail)
+    │
+    └─ [_compile_memory(agent, memory_cfg)] → Memory(agent, store)
+    │
+    ▼
+  Term (可执行 Lambda 项)
+```
+
+### A.16 Schema 校验规则汇总
+
+| ID | 级别 | 触发条件 |
+|----|------|---------|
+| S001 | ERROR | 缺失 `type` 字段 |
+| S002 | ERROR | `type` 值不在 simple/react/chain/router/parallel 中 |
+| S003 | ERROR | simple/react 缺失 `systemPrompt` |
+| S004 | ERROR | `react.maxSteps <= 0` |
+| S005 | ERROR | `chain.steps` 为空 |
+| S006 | ERROR | `router.routes` 为空 |
+| S007 | ERROR | `router.classifier` 缺失 |
+| S008 | ERROR | `parallel.agents` 少于 2 个 |
+| S009 | WARN | `temperature` 不在 [0, 2.0] 范围 |
+
+### A.17 Lint 规则汇总 (L001-L026)
+
+| ID | 级别 | 触发条件 | Lambda 含义 |
+|----|------|---------|-------------|
+| L000 | INFO | 始终 | 框架检测结果 |
+| L001 | ERROR | 空 systemPrompt | `λx. ⊥` 函数体未定义 |
+| L002 | ERROR | 无 model 配置 | 无法执行 β-规约 |
+| L003 | ERROR | maxSteps=0 | `Y_0(g) = ⊥` |
+| L004a | ERROR | react 无 terminate 且无替代终止 | Y 组合子无基 case，潜在无限循环 |
+| L004b | WARN | 无 terminate 但有有界回退 | 有回退但无优雅终止 |
+| L004c/d | INFO | 框架内置终止 | 框架运行时提供基 case |
+| L005 | ERROR | router 空 routes | CASE 无分支 |
+| L006 | ERROR | chain 空 steps | 空组合链 |
+| L007 | WARN | temperature > 1.5 | 高熵，输出不稳定 |
+| L008 | WARN | memory.ttl=0 | Γ' 绑定永不回收 |
+| L009 | WARN | memory.size=0 | Γ' = Γ ∪ ∅ = Γ |
+| L010 | WARN | maxSteps > 50 | `Y_{n>50}` 高成本 |
+| L011 | WARN | react 无工具仅 terminate | 纯推理循环 |
+| L012 | WARN | guard.retry > 5 | 过多重试 |
+| L013 | WARN | router 无 default | CASE 不完备 |
+| L014 | INFO | temperature=0 | 确定性 Lambda |
+| L015 | INFO | memory 启用 | 显示策略参数 |
+| L016 | INFO | rag 启用 | 外部知识 Oracle |
+| L017 | WARN | 未显式设置 maxSteps | Y_n 的 n 由框架隐式决定 |
+| L018 | WARN | maxSteps > 100 | `Y_{>100} ≈ Y` 近似无界 |
+| L019 | INFO | is_termination_msg 检测到 | AutoGen 字符串匹配终止 |
+| L020 | WARN | allow_delegation 但无 peer | 委派目标未定义 |
+| L021 | ERROR | 多 Agent 无终止条件 | GroupChat Y 无基 case 且无界 |
+| L022 | WARN | 有 terminate 但无 maxSteps | LLM 不调 terminate 则无限循环 |
+| L023 | ERROR | router 路由目标为空 | CASE 分支 → ⊥ |
+| L024 | WARN | chain 中重复 agent | `f >> g >> f` 冗余组合 |
+| L025 | WARN | guard 无 retry | 验证失败无恢复 |
+| L026 | INFO | 远程依赖检测 | Oracle 依赖外部服务 |
+
+### A.18 运行时覆盖 (overrides)
+
+`from_config(path, **overrides)` 支持以下运行时覆盖：
+
+| Override | 覆盖字段 | 说明 |
+|----------|---------|------|
+| `model="gpt-4o"` | `model.name` | 替换模型 |
+| `temperature=0.5` | `model.temperature` | 替换温度 |
+| `max_steps=30` | `react.maxSteps` | 替换最大步数 |
+| `tools={"search": fn}` | MCP 工具实现 | 注入自定义工具函数 |
+| `memory_store={"key": "val"}` | Memory 初始值 | 注入初始记忆 |
+| `_confirm_callback=fn` | ToolGateway 确认回调 | HIGH-risk 时调用 |
+| `_audit_log_path="audit.jsonl"` | 审计日志路径 | 持久化审计记录 |
+
+```python
+agent = from_config("config.yml",
+    model="gpt-4o",
+    temperature=0.5,
+    max_steps=30,
+    tools={"search": my_search_fn},
+    memory_store={"user_name": "Alice"}
+)
+```