forked from EduCraft/curriculum-project-hub
hongjr03
082562ca08
放弃 provider-agnostic,用 @anthropic-ai/claude-agent-sdk。代价:不能走 OpenRouter(GLM 等),需 Anthropic API key。收益:compaction、工具审批、 partial message 流式、Claude-to-IM 原生兼容。迁移路径:如果将来需要 provider-agnostic,用 streamText + SSE 转换层(~100 行)替回 query()。
54 lines
2.5 KiB
Markdown
54 lines
2.5 KiB
Markdown
# ADR 0017: Agent Runtime — Claude Code SDK
|
|
|
|
## Status
|
|
|
|
Accepted — supersedes the original ADR-0017 (provider-agnostic session).
|
|
|
|
## Context
|
|
|
|
The original ADR-0017 mandated a provider-agnostic agent layer: any
|
|
OpenAI-compatible model via OpenRouter, custom agent loop built on Vercel AI
|
|
SDK's `streamText`. The motivation was to avoid vendor lock-in.
|
|
|
|
In practice, the hand-rolled agent loop lacked capabilities that a production
|
|
agent needs: context compaction (long conversations), tool approval flows,
|
|
partial-message streaming, and a battle-tested multi-turn loop. Building these
|
|
ourselves meant re-implementing what the Claude Code SDK already provides.
|
|
|
|
The Feishu integration also proved costly to hand-roll — card schema quirks,
|
|
patch limitations, file support — each API quirk cost a round-trip. The
|
|
Claude-to-IM library (2.7K stars) has already solved these, but its
|
|
LLMProvider interface expects Claude Code SDK's SSE event format. Using it with
|
|
a generic provider would require a conversion layer.
|
|
|
|
## Decision
|
|
|
|
Adopt `@anthropic-ai/claude-agent-sdk` as the agent runtime. The SDK's `query()`
|
|
function owns the agent loop (tool dispatch, compaction, streaming). Built-in
|
|
tools (Read, Write, Bash, Glob, Grep) cover the entire tool surface — no custom
|
|
tools needed. `cph check` / `cph build` run via Bash.
|
|
|
|
This means:
|
|
- The agent layer is **Anthropic-specific**, not provider-agnostic. Claude Code
|
|
SDK speaks the Anthropic Messages API and cannot be pointed at OpenRouter
|
|
(which is OpenAI-compatible).
|
|
- An Anthropic API key (or OAuth via Claude Pro/Max) is required.
|
|
- Model selection is within the Anthropic model family (Sonnet, Haiku, Opus),
|
|
not across vendors.
|
|
|
|
## Consequences
|
|
|
|
- We lose the ability to route to GLM or other non-Anthropic models via
|
|
OpenRouter. This is the accepted cost of getting a mature agent loop.
|
|
- The Vercel AI SDK dependency is dropped.
|
|
- Custom tools (read_file, write_file, cph_check, cph_build) are replaced by
|
|
the SDK's built-in Read/Write/Bash/Glob/Grep.
|
|
- The SSE event format matches Claude-to-IM's expected protocol natively —
|
|
adopting Claude-to-IM for Feishu integration is a direct fit, no conversion.
|
|
- Per-run model selection still works (role→model mapping), but models are
|
|
Anthropic aliases, not OpenRouter routing IDs.
|
|
- If provider-agnosticism becomes a hard requirement again, the migration path
|
|
is: replace `query()` with a Vercel AI SDK `streamText` call + an SSE format
|
|
converter (~100 lines). The rest of the architecture (trigger, lock,
|
|
permission, Feishu client) is provider-agnostic already.
|