baozaotumao
df48c36422
把规则从原 ppt-gen 项目泛化为通用脚手架，覆盖 19 个文件： - ddd/architecture/design-discipline/error-codes/communication-* 等： 领域术语、错误码、消息示例、扩展点、状态流统一为「订单」示范域 - agent-dag/agent.md/agent-concurrency/agent-llm-*：DAG 节点、配置、并发、 LLM 适配从「对话→预览→生成→截图→合成」改为「intake→process→validate→finalize」 - backend-db：Session 实体/状态机/ORM/仓储/checkpoint 对齐新流水线 - 移除幻灯片专属依赖与产物：agent 去 playwright/python-pptx， Dockerfile 去 Chromium 系统库，.gitignore 去 *.pptx - 保留合法通用项：ANSI（PTY 处理）、Playwright（E2E 测试工具）、Gemini CLI（真实 provider） 验证：gemini-cli/openai-api 两变体生成退出 0，生成项目零 PPT 残留， backend/agent 骨架均可 import 运行。
46 lines
1.9 KiB
Markdown
46 lines
1.9 KiB
Markdown
---
|
||
paths:
|
||
- "agent/**"
|
||
---
|
||
|
||
# Agent 扩展点规范
|
||
|
||
providers / export / storage / llm 四个扩展点的统一模式：端口（Protocol）+ 适配器多实现 + registry 工厂。
|
||
|
||
## 扩展点规范（providers / export / storage）
|
||
|
||
四个扩展点（含 llm）都遵循同一模式：**端口（Protocol，统一声明于 `domain/ports.py`）+ 适配器多实现 + registry 工厂**。调用方只依赖端口，按配置选实现，新增能力不改调用方。
|
||
|
||
下面端口为**示范**，按项目实际定义：
|
||
|
||
```python
|
||
# domain/ports.py —— 所有端口在此声明（六边形架构：端口属领域核心）
|
||
class Exporter(Protocol):
|
||
async def export(self, data: object, out_path: Path) -> Path: ...
|
||
|
||
class StorageBackend(Protocol):
|
||
async def save(self, key: str, data: bytes) -> None: ...
|
||
async def read(self, key: str) -> bytes: ...
|
||
def url_for(self, key: str) -> str: ...
|
||
|
||
class ExternalProvider(Protocol):
|
||
def build_context(self) -> str: ... # 注入 LLM prompt 的外部上下文
|
||
```
|
||
|
||
**节点必须通过接口调用，禁止硬编码具体实现：**
|
||
|
||
- `finalize` 节点调用 `exporter.export(...)`，不直接调具体导出库
|
||
- 所有文件读写经 `StorageBackend`，不直接碰 `Path.write_bytes`（本地实现内部才碰 FS）
|
||
- 加新导出格式 = 新增 `xxx_exporter.py` 注册到 registry，`finalize` 一行不改
|
||
|
||
## registry 工厂
|
||
|
||
每个扩展点目录提供 `registry.py`，按 `Settings` 配置选择具体实现：
|
||
|
||
- `llm/`：按厂商配置选 `GeminiCliSession` 等 `LLMSession` 实现
|
||
- `providers/`：按配置选具体 `ExternalProvider` 实现（含 `none` 退化态）
|
||
- `export/`：按导出格式选具体 `Exporter` 实现
|
||
- `storage/`：按存储后端选 `local_storage`（未来 `s3_storage`）等 `StorageBackend` 实现
|
||
|
||
新增能力 = 新增一个实现文件 + 在对应 `registry.py` 注册，调用方（DAG 节点）零改动。
|