docs: update audit report — mark DESIGN-01/07/08 fixed, add instance/workspace architecture

Fixed items:
- DESIGN-01: PassthroughHandler base class (was: implicit isinstance checks)
- DESIGN-07: Effect inference covers all multi-agent constructs
- DESIGN-08: validate_cost() cross-validates predicted vs actual

New sections:
- §10: Post-audit updates — fixed items table + instance mechanism + run workspace
- §11: Updated summary (C+ → B-)

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

PROJECT_AUDIT_2026Q2.md

@@ -0,0 +1,370 @@
+# 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 层的安全漏洞。