ソースを参照

docs: align docs/agentpaas.md + SPEC.md with code (audit #74 #75)

Phase 4 之后剩下的几条 "技术参考" 类文档漂移, 4 个点位修齐。

## docs/agentpaas.md 架构图

  agentpaas/api/app.py  →  agentpaas/src/agentpaas/api/app.py

Phase 1 src-layout 之后 .py 实际路径是 src/agentpaas/。架构图里仍指
旧路径,新人按图找文件会 404。

## agentpaas/SPEC.md §3.3.1 同步执行 response (audit #75)

Response 示例曾包含两个字段:
  - `usage.estimated_cost_usd`
  - 顶层 `trace_id`

实测 agents.py 的 /run 响应构造 (commit 63ea55b 后的路径) 从来没填
过这两个字段。`workspace_path` 倒是实际返回的, SPEC 里反而没写。

修法: 删掉 `estimated_cost_usd` + `trace_id` (避免承诺空头支票),
加上真实返回的 `workspace_path`, 用 blockquote 标注两个删字段已列入
v1.1 backlog 并指向各自的实现依赖 (cost_grade / OTel trace 注入)。

## agentpaas/SPEC.md §3.3.3 流式 URL (audit #74)

  POST /api/v1/agents/{agent_id}/stream
  →
  POST /api/v1/agents/{agent_id}/run/stream

代码实际路由在 `@router.post("/{agent_id}/run/stream")`
(agentpaas/src/agentpaas/api/v1/agents.py:443)。SPEC 里少了 `/run`。
RAG_V2_PLAN 风格的客户端按 SPEC 接入会 404。

## agentpaas/SPEC.md §3.3.4 WebSocket — 标 planned

WS endpoint 在 v1.0 没实现, SPEC 里却作为 spec 写出来。改为 "planned —
未在 v1.0 实现" + blockquote 说明 SSE 已覆盖, WS 不立项, 客户端不
要按 SPEC 接 (否则连不上)。

## 验证

  $ grep "agents/{agent_id}/stream$" agentpaas/SPEC.md
  (empty — 已无遗留旧路径)

  $ grep '"workspace_path":' agentpaas/src/agentpaas/api/v1/agents.py
  795, 1035, 1048, 1523  (确认实际返回)

  $ grep '"trace_id":' agentpaas/src/agentpaas/api/v1/agents.py
  (empty — SPEC 删字段是正确选择)

## audit 进度 (this commit)

闭掉: high #74 + high #75 + 1 处 src-layout 路径漂移。
累计: 5 critical + 11 high 关闭 (Phase 0-5 + 本 commit)。

剩余 audit 文档漂移 ~7 条 (docs/from-config-spec.md 的 YAML schema /
type 数量 / _compile_chain 行为, IDEA.md 等), 后续按需再扫。

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
kenny67nju 3 ヶ月 前
コミット
5e4688b5d8
2 ファイル変更17 行追加7 行削除
  1. 16 6
      agentpaas/SPEC.md
  2. 1 1
      docs/agentpaas.md

+ 16 - 6
agentpaas/SPEC.md

@@ -184,13 +184,18 @@ Response: 200 OK
         "output_tokens": 380,
         "total_tokens": 1630,
         "steps": 3,
-        "duration_ms": 4520,
-        "estimated_cost_usd": 0.0082
+        "duration_ms": 4520
     },
-    "trace_id": "tr_a1b2c3"
+    "workspace_path": "/var/agentpaas/agents/.../workspace/run_20260606_143000"
 }
 ```
 
+> **v1.0 实现说明:** `usage.estimated_cost_usd` 和顶层 `trace_id` 字段曾
+> 在设计草案里出现, 但 `agentpaas/src/agentpaas/api/v1/agents.py` 当前
+> 的响应构造没有填充它们。前者依赖 `lambdagent.cost_grade` 的接入,
+> 后者需要 OpenTelemetry trace 注入到 response 包装层——都列入 v1.1
+> backlog (审计 docs/AUDIT_2026-06-05.md #75)。
+
 #### 3.3.2 异步执行
 
 ```
@@ -223,7 +228,7 @@ POST /api/v1/jobs/{job_id}/cancel                  // 取消任务
 #### 3.3.3 流式执行 (SSE)
 
 ```
-POST /api/v1/agents/{agent_id}/stream
+POST /api/v1/agents/{agent_id}/run/stream
 Accept: text/event-stream
 
 SSE 事件流:
@@ -243,10 +248,15 @@ event: done
 data: {"run_id": "run_7d9e4f", "usage": {...}}
 ```
 
-#### 3.3.4 WebSocket 交互
+#### 3.3.4 WebSocket 交互 (planned — 未在 v1.0 实现)
+
+> **v1.0 状态:** 此端点为设计文档, 代码侧暂未实现。v1.0 的实时交互
+> 通过 §3.3.3 的 SSE 流式端点完成, SSE 已经覆盖了大多数 WS 想解决的
+> 场景。在确定真实需求 (双向 / 多轮持续会话) 之前, WS 实现暂不立项。
+> 审计参见 docs/AUDIT_2026-06-05.md #74。
 
 ```
-WS /api/v1/agents/{agent_id}/ws
+WS /api/v1/agents/{agent_id}/ws    (planned)
 
 → Client:  {"type": "message", "input": "查询订单 #12345"}
 ← Server:  {"type": "thinking", "content": "正在分析..."}

+ 1 - 1
docs/agentpaas.md

@@ -10,7 +10,7 @@ AgentPaaS is a Platform-as-a-Service for deploying, managing, and running Lambda
                     CLI / HTTP Client
                           |
                     ┌─────▼─────┐
-                    │  FastAPI   │   agentpaas/api/app.py
+                    │  FastAPI   │   agentpaas/src/agentpaas/api/app.py
                     │  Server    │   (serve --dev)
                     └─────┬─────┘
                           |