# lambdagentpaas 项目全面审计报告 (2026 Q2)

> **Date**: 2026-04-05
> **Scope**: Core kernel (lambdagent/) + PaaS layer (agentpaas/) + Tests + Docs
> **Method**: 三路并行代码审计 (核心内核 / PaaS+运行时 / 测试+文档)
> **Finding**: 40+ 代码缺陷, 57 项未完成 TODO, 30 个模块无测试覆盖

---

## 一、项目现状总览

| 维度 | 现状 | 评级 |
|------|------|------|
| 理论基础 | 三篇论文, λA 类型系统, CEK Machine, 效果代数 | **A+** |
| 核心 DSL | 11 构造 + 5 多智能体扩展, 全部实现 | **A** |
| 测试覆盖 | 402 个测试, 16 个测试文件, **30 个核心模块无测试** | **C** |
| PaaS 层 | 28 个端点, 多租户, RBAC, 但**追踪断裂/安全漏洞** | **D+** |
| 文档 | 500KB+, 21 个文件, **4 个是空 stub** | **B-** |
| 生产就绪度 | 基础设施完成, **关键集成断裂** | **Not Ready** |

### 完成度

```
Phase 1 (P0 生存基础):      12/12  ✅ 100%
Phase 2 (P1 可靠运行):       5/5   ✅ 100%
Phase 3 (P2 竞争力):         5/5   ✅ 100%
Phase 4 (安全加固):          18/34  ⚠️ 53%
Phase 5 (助手工具):          28/38  ⚠️ 74%
Phase 6 (PaaS 服务):         8/8   ✅ 100%
Phase 6.5 (双引擎):          5/7   ⚠️ 71%
Phase 7 (集成层):             0/17  ❌ 0%
Phase 8 (Provider):           0/5   ❌ 0%
Research P2:                  0/12  ❌ 0%
─────────────────────────────────────
总计: 81/143 完成 (57%)
```

---

## 二、功能缺陷 (Bugs — 运行时会崩溃)

### BUG-01: Context.fork() 浅拷贝导致并行数据竞争 [严重]

**文件**: `core.py` L99-112
```python
def fork(self) -> Context:
    return Context(
        bindings=dict(self.bindings),  # 浅拷贝! 嵌套 dict/list 共享引用
        memory=dict(self.memory),       # 浅拷贝!
    )
```
**影响**: Par/AsyncPar 并行分支修改嵌套对象时互相干扰, 违反 Paper II Proposition 30
**修复**: 改用 `copy.deepcopy()` 或 frozen dict

### BUG-02: Guard 调用 `If._is_truthy()` 时可能 NameError [严重]

**文件**: `extensions.py` L178
```python
valid = If._is_truthy(valid) if isinstance(valid, str) else bool(valid)
```
**影响**: 循环导入场景下 `If` 未定义, Guard validator 返回字符串时崩溃
**修复**: 内联 truthy 检查逻辑, 不依赖 If 类

### BUG-03: Fst/Snd 无类型检查直接索引 [中等]

**文件**: `primitives.py` L345-360
```python
class Fst(Term):
    def apply(self, input, ctx=None):
        return input[0]  # input 非 tuple 时 IndexError
```
**修复**: 添加 `if not isinstance(input, (tuple, list)) or len(input) < 2: raise TypeError(...)`

### BUG-04: CEK Machine 不处理 Term 闭包环境 [中等]

**文件**: `cek_machine.py` L295
**影响**: 带捕获绑定的 Term 在 CEK 中执行时丢失环境
**修复**: `load()` 时从 Term 提取绑定注入 `env`

### BUG-05: 类型系统 `is_subtype(T_INT, T_JSON())` 返回 False [中等]

**文件**: `types.py` L223-225
**影响**: Paper III 说 `Num <: Json(untyped)` 成立, 但实现返回 False, 类型检查器误报
**修复**: 无 schema 的 `T_JSON()` 应接受所有基础类型

### BUG-06: PaaS 追踪断裂 — ctx.trace 从未被填充 [严重]

**文件**: `agentruntime/runtime.py` L81-97, `react_engine.py` L128-220
**影响**: Executor 和 ReActEngine 各维护独立 trace, 互不通信; PaaS API 返回空 trace
**修复**: 统一 trace 路径, 所有引擎必须写入 `ctx.trace`

### BUG-07: PaaS 数据库无索引 [严重]

**文件**: `agentpaas/db/models.py` L43-151
**影响**: 所有查询全表扫描, >1000 agent 时不可接受
**修复**: 添加 `CREATE INDEX idx_agents_tenant ON agents(tenant_id)` 等

---

## 三、设计缺陷 (Design Smells — 工作但设计不良)

### ~~DESIGN-01: Handler 类型检测是隐式的~~ ✅ 已修复

已引入 `PassthroughHandler` 基类。`ProductionHandler` 和 `TraceHandler` 继承 `PassthroughHandler`，Lam/Tool/CEK 统一通过 `isinstance(handler, PassthroughHandler)` 判断是否透传。新增 handler 只需决定是否继承 `PassthroughHandler`。

### DESIGN-02: Lam 模型检测做网络调用 [高]

`_detect_provider()` 在检测 Ollama 时 `urllib.request.urlopen("http://localhost:11434")`, 有副作用.

**改进**: 不做 auto-detection, 要求显式配置 `provider` 字段

### DESIGN-03: Memory 注入用字符串拼接 [中]

```python
augmented = f"[Memory]\n{memory_str}\n\n[Input]\n{input}"
```
无转义, 如果 input 包含 `[Memory]` 标记会混淆 LLM.

**改进**: 让 Lam 的 prompt template 处理 memory 注入, 不在 Memory 层硬编码格式

### DESIGN-04: Route 模糊匹配过于宽松 [中]

```python
if key.lower() in label:  # "code" 匹配 "code_review"
```
多个路由键可能同时匹配, 取第一个(dict 迭代序).

**改进**: 优先精确匹配, 模糊匹配仅在无精确匹配时启用, 有歧义时报错

### DESIGN-05: GroupChat 上下文窗口用魔术数字 [中]

`tail_size = 3 * len(self.agent_list)` 无依据, 且 `conversation.index(m)` 在循环内导致 O(n^2)

### DESIGN-06: Guard 重试用相同输入 [中]

CEK `GuardK` 重试时 `_AppTerm(k.agent_term, k.input_val)` — 同一个输入给 LLM, 大概率得到相同无效输出.

**改进**: 重试时增加 temperature 或在 prompt 中注入验证失败原因

### ~~DESIGN-07: 效果推断不覆盖多智能体构造~~ ✅ 已修复

`infer_effect_for_term()` 现已覆盖 GroupChat（iterate(parallel(...), n)）、AsyncPar（parallel(...)）、Handoff（serial(...)）、Send（serial(inner, state)）、Receive（serial(state, handler)）。

### ~~DESIGN-08: 成本估算与成本追踪完全脱节~~ ✅ 已修复

新增 `validate_cost(predicted, actual_tokens, actual_money)` 函数，交叉验证预测 CostGrade 与实际 CostVector，偏差 >2x 时返回 `COST_ANOMALY` 告警。

---

## 四、安全漏洞

| ID | 描述 | 严重度 |
|----|------|--------|
| SEC-01 | API Key PBKDF2 用固定 salt (从 key 前缀派生) | **高** |
| SEC-02 | Tool output 原样注入 prompt, 无转义 (prompt injection) | **高** |
| SEC-03 | `/api/v1/agents/{id}/run` 无速率限制 | **高** |
| SEC-04 | RBAC 未在 API 层执行 (viewer 可调 PUT) | **中** |
| SEC-05 | SQLite `check_same_thread=False` 无锁保护 | **中** |
| SEC-06 | 异常日志可能泄露 API Key | **中** |
| SEC-07 | 流式端点 Queue 无上限, 慢客户端导致 OOM | **中** |
| SEC-08 | sub-agent 编译无递归深度限制 (A→B→C→A 死循环) | **中** |

---

## 五、性能问题

| ID | 描述 | 影响 |
|----|------|------|
| PERF-01 | Par 每次调用创建新 ThreadPoolExecutor | 线程创建开销 |
| PERF-02 | trace merge 在循环内逐个 extend → O(n^2) | 多 agent 时慢 |
| PERF-03 | GroupChat 上下文构建 O(n^2) (循环内 list.index) | 长对话时慢 |
| PERF-04 | 数据库全表扫描 (无索引) | >1000 agent 不可用 |

---

## 六、测试覆盖缺口

**30 个核心模块无专属测试文件**. 最高优先级:

| 模块 | 重要度 | 测试难度 | 建议 |
|------|--------|---------|------|
| `core.py` | 基石 | 低 | Context.fork 深拷贝验证 |
| `primitives.py` | 基石 | 低 | 每个 apply() 的边界条件 |
| `multiagent.py` | 高 | 中 | GroupChat/Handoff/Channel 并发 |
| `async_core.py` | 高 | 中 | 取消传播, 并行收集 |
| `isolation.py` | 高 | 高 | Worktree 创建/清理/合并 |
| `compiler.py` | 高 | 中 | 各种 YAML 格式编译正确性 |

---

## 七、文档缺口

| 文件 | 状态 | 需要 |
|------|------|------|
| `docs/theory.md` | 空 stub (71 bytes) | 论文摘要 + 形式化定义 |
| `docs/multi-agent.md` | 空 stub (242 bytes) | GroupChat/Channel 示例 |
| `docs/api.md` | 极简 (1.6 KB) | REST API 完整参考 |
| `docs/constructs.md` | 仅表格 (1.2 KB) | 叙述说明 + 代码示例 |

---

## 八、全部未实现功能 — 优先级排序

### Tier 0: 修 Bug (立即, ~5 人天)

| ID | 任务 | 工作量 |
|----|------|--------|
| FIX-01 | Context.fork() 改用 deepcopy | 0.5d |
| FIX-02 | Guard truthy 检查内联 | 0.5d |
| FIX-03 | Fst/Snd 添加类型检查 | 0.5d |
| FIX-04 | is_subtype 修复基础类型 → 无 schema JSON | 0.5d |
| FIX-05 | PaaS 追踪断裂修复 (统一 ctx.trace) | 1d |
| FIX-06 | 数据库添加索引 | 0.5d |
| FIX-07 | __init__.py 导出 Phase 6.5 Engine 类 | 0.1d |
| FIX-08 | API Key salt 改为随机生成 | 0.5d |
| FIX-09 | 流式 Queue 加 maxsize=1000 | 0.2d |
| FIX-10 | sub-agent 编译加递归深度限制 | 0.5d |

### Tier 1: 安全加固 (~15 人天)

| ID | 任务 | 来源 | 工作量 |
|----|------|------|--------|
| S13 | Checkpoint 加密 AES-256-GCM | Phase 4 | 1d |
| S14 | Memory 按 Agent/Tenant 隔离 | Phase 4 | 2d |
| S15 | Channel 访问控制 | Phase 4 | 1d |
| S17 | Token 硬限制 | Phase 4 | 1d |
| S18 | ToolGateway 路径 ACL | Phase 4 | 2d |
| S19 | ToolGateway 网络 ACL | Phase 4 | 1d |
| SEC-03 | API 速率限制 (run 端点) | 审计 | 1d |
| SEC-04 | RBAC 在 API 层执行 | 审计 | 1d |
| S21 | 安全审计日志 | Phase 4 | 2d |
| S28 | YAML parser fuzz 测试 | Phase 4 | 2d |
| SEC-02 | Tool output prompt injection 防护 | 审计 | 1d |

### Tier 2: 双引擎 + Provider 完成 (~12 人天)

| ID | 任务 | 来源 | 工作量 |
|----|------|------|--------|
| E06 | AdaptiveEngine 自动选择 | Phase 6.5 | 1d |
| E07 | 双引擎 125+60 一致性测试 | Phase 6.5 | 1d |
| L01 | LLMProvider 统一接口 | Phase 8 | 1d |
| L02 | 4 个 Provider 实现 | Phase 8 | 2d |
| L03 | ConversationLam 对话持久化 | Phase 8 | 2d |
| L04 | from_config 编译器集成 | Phase 8 | 1d |
| L05 | 端到端验证 | Phase 8 | 1d |
| DESIGN-01 | Handler 类型体系重构 | 审计 | 1d |
| DESIGN-07 | 效果推断覆盖多智能体 | 审计 | 1d |
| DESIGN-08 | 成本估算 vs 实际追踪交叉验证 | 审计 | 1d |

### Tier 3: 集成层 — MCP + GitHub Action (~10 人天)

| ID | 任务 | 来源 | 工作量 |
|----|------|------|--------|
| I01 | MCP Server 实现 (4 个工具) | Phase 7a | 2d |
| I02 | MCP Server PyPI 发布 | Phase 7a | 1d |
| I03 | 成本异常运行时检测 | Phase 7a | 1d |
| I04 | GitHub Action 实现 | Phase 7b | 2d |
| I05 | GitHub Marketplace 发布 | Phase 7b | 1d |
| I15 | REST API /analyze/* 端点 | Phase 7e | 1d |
| API-01 | 统一错误响应格式 | 审计 | 1d |
| API-03 | 幂等 key 支持 | 审计 | 1d |

### Tier 4: 集成层 — 框架提取器 + 运行时守卫 (~18 人天)

| ID | 任务 | 来源 | 工作量 |
|----|------|------|--------|
| I06 | 提取器接口 | Phase 7c | 0.5d |
| I07 | LangChain 提取器 | Phase 7c | 2d |
| I08 | CrewAI 提取器 | Phase 7c | 2d |
| I09 | AutoGen 提取器 | Phase 7c | 2d |
| I10 | lambdagent-guard 核心 | Phase 7d | 2d |
| I11 | LangChain 守卫 | Phase 7d | 2d |
| I12 | CrewAI 守卫 | Phase 7d | 2d |
| I13 | AutoGen 守卫 | Phase 7d | 2d |
| I14 | lambdagent-guard PyPI 发布 | Phase 7d | 1d |
| FEAT-02 | PaaS 异步 Job API | 审计 | 2d |

### Tier 5: 助手工具补全 (~16 人天)

| ID | 任务 | 来源 | 工作量 |
|----|------|------|--------|
| A18 | NotebookEdit 工具 | Phase 5 | 3d |
| A19 | WebSearch 工具 | Phase 5 | 1d |
| A20 | WebFetch 工具 | Phase 5 | 1.5d |
| A21 | 模型 auto-fallback | Phase 5 | 1.5d |
| A24 | LSP 代码智能 | Phase 5 | 5d |
| I16 | VS Code 扩展 | Phase 7f | 3d |
| I17 | Marketplace 发布 | Phase 7f | 1d |

### Tier 6: 高级功能 + 研究 (~35 人天)

| ID | 任务 | 来源 | 工作量 |
|----|------|------|--------|
| A25-A33 | 用户交互/规划模式/Worktree/团队等 | Phase 5 Tier 4 | 20d |
| S27 | L2 容器沙箱 | Phase 4 | 5d |
| S30 | macOS sandbox-exec | Phase 4 | 3d |
| Research P2 | 概率预言机/互模拟/Coq 等 12 项 | Research | 不定 |

### Tier 7: 测试 + 文档补全 (~12 人天)

| ID | 任务 | 工作量 |
|----|------|--------|
| TEST-01 | core.py + primitives.py 测试 | 2d |
| TEST-02 | multiagent.py 测试 | 2d |
| TEST-03 | async_core.py + isolation.py 测试 | 2d |
| TEST-04 | compiler.py + lint.py 测试 | 2d |
| DOC-01 | theory.md 完善 | 1d |
| DOC-02 | multi-agent.md 完善 | 1d |
| DOC-03 | api.md REST 参考 | 1d |
| DOC-04 | constructs.md 示例 | 1d |

---

## 九、推荐执行顺序

```
Week 1:   Tier 0 (修 Bug)           ~5d   ← 立即
Week 2-3: Tier 1 (安全)             ~15d  ← 生产阻塞
Week 3-4: Tier 2 (双引擎+Provider)  ~12d  ← 核心完成
Week 5:   Tier 3 (MCP+Action)       ~10d  ← 最高商业价值
Week 6-7: Tier 4 (框架守卫)         ~18d  ← 生态扩展
Week 8:   Tier 7 (测试+文档)        ~12d  ← 质量保证
Week 9+:  Tier 5-6 (工具+高级)      ~51d  ← 功能丰富

总计: ~123 人天 (未完成部分)
已完成: ~89 人天 (81 项)
```

---

## 十、2026-04-06 后续更新

### 已修复的审计项 (P0+P1 实现期间)

| ID | 状态 | 修复方式 |
|----|------|---------|
| DESIGN-01 | ✅ | `PassthroughHandler` 基类 (`handlers.py`) |
| DESIGN-07 | ✅ | `infer_effect_for_term()` 覆盖全部多智能体构造 (`effects.py`) |
| DESIGN-08 | ✅ | `validate_cost()` 交叉验证预测 vs 实际 (`cost_grade.py`) |

### 新增架构: Agent Instance 机制

**Agent 是函数定义，Instance 是函数调用。** 一份 agent 模板可被多个领域实例化。

```
agentexample/qaagent67wiki/          ← 模板（版本控制）
    agent-config.yml                  ← 默认配置（相对路径）
    agents/, skills/

agentexample/instances/maritime/     ← 实例（数据不跟踪）
    instance.yml                      ← 路径覆盖（跟踪）
    wiki/                             ← 累积知识（不跟踪）
    knowledge/                        ← 原始文件（不跟踪）
    workspace/                        ← per-run 数据（不跟踪）
```

关键文件:
- `agentpaas/engine/instance.py` — `load_instance()`, `create_instance()`, `_deep_merge()`
- DB: agents 表新增 `agent_template`, `instance_dir` 列
- API: `CreateAgentRequest` 接受 `instance_dir` / `agent_template`

### 新增架构: Run Workspace

每次 `POST /agents/{id}/run` 在 `{agent_dir}/workspace/run_{YYYYMMDD_HHMMSS}/` 创建隔离目录，保存 input/output/trace/config/cost，保留所有历史 run 不删除。

---

## 十一、一句话总结

**理论层 A+, 工程层 C+ → B-.** P0+P1 修复了 DESIGN-01/07/08，新增了 175 测试和 Instance 机制。最关键的剩余问题是**追踪链路三路分叉**和 PaaS 层的安全漏洞。