不可违反的硬约束。任何 Agent 在编码前必须阅读。 最后更新：2026-04-16
以下约束在 MVP 阶段绝对不可突破：
| 维度 | 约束 |
|---|---|
| 入站协议 | 仅支持 OpenAI 兼容格式 (POST /v1/chat/completions) |
| 出站厂商 | 第一个版本仅 DeepSeek V3.2（通过 OpenAI 兼容接口）。Anthropic / OpenAI 等通过预留的 OutboundAdapter 接口后续接入 |
| 架构形态 | 单体 Go 服务，编译为单一二进制 |
| 状态设计 | 完全无状态。不维护任何 session、对话历史、用户上下文 |
| 分块策略 | 静态四分块（System / Tool / History / Query）。禁止引入动态前缀优化算法 |
| 缓存策略 | 静态缓存注入（Anthropic cache_control）。无动态模板选择 |
| 去重范围 | 仅对非流式请求 (stream=false) 做并发去重 |
| 路由策略 | 按 model 名称做固定映射。禁止成本最优路由、智能路由 |
| 语义处理 | 不解析 content 语义，不做语义缓存，不做 embedding 匹配 |
- Anthropic / Google 原生入站接口
- 对话历史托管（session 状态）
- 流式请求去重
- 动态分块（Observer / Clusterer / 模板池）
- 语义缓存
- 复杂能力协商（function calling 格式自动转换）
- 多地域部署
- 团队/组织管理、SSO
- 商业化功能（支付、订阅、发票）
当前项目处于文档先行阶段。Go 代码文件尚未存在。
- 所有文档中对
项目结构、文件路径、代码示例的描述均为设计意图，不代表文件已存在。 - Agent 在实施编码任务时，必须根据文档从零创建文件，而不是假设文件已存在并尝试修改。
cmd/server/main.go、go.mod、.env.example、Makefile等文件目前均不存在，需要时由 Agent 创建。
| 红线 | 说明 |
|---|---|
| 新增外部依赖 | 任何新的第三方库引入必须经过 ADR 流程或记录在 PRD 技术栈中 |
| ADR 保护 | ADR 文档只记录决策结论，不记录实现细节。禁止因代码变更而修改 ADR |
| Archive 保护 | docs/archive/adapter-design.md 为历史归档文档，禁止删除 |
| Phase 2 文档隔离 | 所有 Phase 2/3 算法文档必须放在 docs/research/ 目录下，不得进入 MVP 执行路径 |
| 接口文档同步 | 新增/修改 interface 后，必须同步更新 CODE_WIKI.md |
| API 契约同步 | 新增/修改 HTTP 端点后，必须同步更新 API_CONTRACT.md |
- KV Cache 命中率 > 40%（MVP 目标，通过 DeepSeek
prompt_cache_hit_tokens度量） - P99 延迟增加 < 100ms（不含厂商响应时间）
- 吞吐量 > 500 req/s（MVP 目标，标准负载：10 条 messages，5 个 tools，~2000 tokens）
- 首 Token 延迟增加 < 50ms
| 模块 | 最低覆盖率 | 备注 |
|---|---|---|
| Canonicalizer | 100% | 字节级确定性必须严格保证 |
| Chunker | 80% | |
| Arranger | 80% | |
| Hasher | 80% | |
| Outbound Adapters | 70% |
- 所有外部 I/O 调用必须处理
error，禁止吞掉错误 - 并发访问共享状态必须使用
sync.RWMutex或 channel 保护 - 所有测试必须是表格驱动（table-driven）
- 禁止使用
interface{}传递业务数据（配置解析除外） - 禁止在
internal/之外编写业务逻辑
// 正确：wrap 错误并带上模块前缀
blocks, err := chunker.Chunk(env)
if err != nil {
return fmt.Errorf("chunker: %w", err)
}
// 禁止：吞掉错误
blocks, _ := chunker.Chunk(env)- 使用 Zap 结构化日志
- key 使用 snake_case
- 错误日志必须包含
error字段
- 所有配置项通过环境变量注入
pkg/config/为统一加载入口- 默认值应在代码中显式声明，不依赖隐式零值
- 优先 TDD：先写测试再写实现
- Mock 策略：Mock 接口，不 Mock 具体实现
- 集成测试必须使用
httptest.Server