feat: Agent 集成增强 - Session-First 架构、MCP Server 和技能库支持

[w31r4]

概述

本次重构实现了三大核心功能，为 AI Agent 提供完整的沙箱执行环境：

1. Session-First 架构重构

• 1:1 Session-Ship 绑定: 每个会话独占一个容器，简化状态管理
• Warm Pool 预热池: 弥补冷启动延迟，提升用户体验
• 执行历史记录: 支持 Agent 技能库构建（受 VOYAGER 论文启发）

2. MCP Server 集成

• 标准 MCP 协议: 兼容 Claude Desktop、ChatGPT、Cursor、VS Code 等客户端
• 双传输模式: stdio（桌面应用）和 HTTP（远程部署）
• HTTP 模式会话隔离: 每个 MCP 客户端获得独立的 Sandbox
• npm 包发布: shipyard-mcp 支持快速安装

3. SDK 架构优化

• 新增 Sandbox 类: 统一简洁的入口接口
• MCP Server 内部复用 SDK: 避免代码重复
• 保留 ShipyardClient: 作为低级 API 供高级用户使用

4. 技能库增强（Skill Library）

基于 VOYAGER、Reflexion、LearnAct 论文需求，新增执行记录管理功能：

新增 MCP 工具:

• get_execution(execution_id) - 按 ID 查询执行记录
• get_last_execution(exec_type) - 获取最近执行
• annotate_execution(execution_id, description, tags, notes) - 标注执行记录

增强的工具参数:

• execute_python/execute_shell: 新增 include_code, description, tags
• get_execution_history: 新增 tags, has_notes, has_description 过滤

数据模型扩展:

• ExecutionHistory 新增 description, tags, notes 字段
• ExecResult 新增 execution_id 字段

文件变更

目录	变更
pkgs/bay/	Bay 服务端核心逻辑、MCP Server、数据库模型
pkgs/mcp-server/	独立 npm 包 MCP Server
pkgs/ship/	执行时间记录支持
shipyard_python_sdk/	新增 Sandbox 类、Session-First API
docs/	CHANGELOG 文档

测试

• 13 个 MCP HTTP 会话隔离集成测试全部通过
• 单元测试更新以匹配新架构

参考文献

• VOYAGER (2023) - 技能库自动构建
• Reflexion (2023) - 执行反馈用于 Agent 自我改进
• LearnAct (2024) - 从执行历史中学习可复用技能

🤖 Generated with Claude Code

[sourcery-ai]

Sorry @w31r4, your pull request is larger than the review limit of 150000 diff characters

[w31r4]

Code review

Found 1 issue:

1. FastAPI Route Ordering Bug - /sessions/{session_id}/history/last is defined after /sessions/{session_id}/history/{execution_id}. Since FastAPI matches routes in definition order, requests to /history/last will be matched by the parameterized route first (treating "last" as an execution_id), so the /history/last endpoint will never be reached.

shipyard/pkgs/bay/app/routes/sessions.py

Lines 269 to 296 in 165aa77

	@router.get("/sessions/{session_id}/history/{execution_id}", response_model=ExecutionHistoryEntry)
	async def get_execution_by_id(
	session_id: str,
	execution_id: str,
	token: str = Depends(verify_token),
	):
	"""Get a specific execution record by ID.
	Args:
	session_id: The session ID
	execution_id: The execution history ID
	"""
	entry = await db_service.get_execution_by_id(session_id, execution_id)
	if not entry:
	raise HTTPException(
	status_code=status.HTTP_404_NOT_FOUND,
	detail="Execution not found"
	)
	return ExecutionHistoryEntry.model_validate(entry)
	@router.get("/sessions/{session_id}/history/last", response_model=ExecutionHistoryEntry)
	async def get_last_execution(
	session_id: str,
	exec_type: Optional[str] = None,

Fix: Move the /history/last route definition before /history/{execution_id} so specific routes are matched before parameterized ones.

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}