dong90 taiyi-design — 技术设计
进入本阶段前请优先读
.taiyi/changes/<slug>/PHASE-CONTEXT.md（~500 tokens），不要全量加载上游工件。
框架集成
本阶段使用以下框架：
| 框架 | 用途 | 何时加载 |
|---|---|---|
| Harness | 阶段门禁与推进（status → continue --approver；legacy：npx taiyi complete） |
全程 |
| Superpowers | brainstorming — 可选，当多方案对比需要创意发散时加载 |
Options 步骤前 |
| OpenSpec | 将 DESIGN.md 同步到 openspec 格式 | 可选 |
| Spec-Kit | 设计方案遵循 Spec-Kit 规范（≥2 方案、取舍记录） | 全程 |
GStack 和 OMO 在本阶段不涉及。
前置门禁（Pre-flight）
执行以下检查后再开始写 DESIGN.md：
0.1 Brownfield 对齐
- 列出触碰模块、新增模块、禁动清单
- 对齐既有抽象，禁止"顺便引新库"
- 沿用既有模式 vs 引入新模式（须充分理由，记录在 Context 中）
0.2 Profile 设计深度判定
| Profile | 设计深度 | 必含章节 |
|---|---|---|
full |
完整 | Context + Options(表格) + Decision + Architecture + Data Flow + Module Layout + Risks & Mitigations + Verification Checklist + Open Questions |
api |
中等 | Context + Options + Decision + Module Layout + Data Flow，跳过 Verification Checklist |
ui |
中等 | Context + Options + Decision + UI 组件树，跳过 Data Flow / Verification Checklist |
lite |
精简 | 仅 Decision 说明 + Open Questions，可省多方案对比（但至少记录取舍理由） |
micro/spike |
跳过 | 可省略 DESIGN.md（如门禁拦截则写一页 Decision Summary） |
nano |
跳过 | 本阶段可直接过关 |
0.3 前置检查清单
- requirement 阶段已过关（
engineTruth确认） - 影响面已在 CHANGE.md 中声明
- 了解现有架构（至少扫读 docs/ARCHITECTURE.md 或既有 DESIGN.md）
步骤
工件契约
| 层 | 路径 | 职责 |
|---|---|---|
| 语义真源 | design.json |
Zod（src/schemas/design.ts） |
| 生成视图 | DESIGN.md |
hbs（src/templates/design.hbs） |
| 流程 | 本 Skill | ≥2 方案、Brownfield、Verification Checklist 纪律 |
工作流：编辑 json → scripts/taiyi-forge.sh render <slug> design → status → continue --approver "名"。
详见 docs/taiyi/artifact-contract.md。
json 字段（Zod 摘要）
| 字段 | 要求 |
|---|---|
title |
方案设计标题 |
options |
≥2 方案；id / name / pros / cons / cost |
decision |
chosen（方案 id）+ reason + 可选 tradeoffs |
existingArchitecture |
Brownfield：touchedModules / newModules / doNotTouch |
techStack |
可选；选中栈 + 理由 |
modules |
可选；模块清单（name / path / operation / description） |
tradeoffs / blast_radius / security_threats |
可选；取舍与安全 |
evolutionSuggestions |
可选；架构沉淀建议（无则 []） |
dependency_sandbox |
可选；依赖版本与替代方案 |
写作指引（填入 json，render 生成 DESIGN.md）
1. Context（设计上下文）
描述设计的背景和约束条件，让 reviewer 无需回读上游工件即可理解设计出发点。
## Context
**Brownfield**: [现有代码库/项目状态，是否增量修改]
**约束**:
- [技术栈约束，如 Python 3.11+, FastAPI]
- [性能约束，如 P99 < 200ms]
- [安全约束，如必须 JWT 认证]
- [兼容性约束，如向后兼容 API v1]
- [集成约束，如依赖未完成的 change X]
2. Options（方案对比）
格式选择：
| 条件 | 推荐格式 |
|---|---|
| ≥3 方案 或 多维度对比（性能/复杂度/可维护性） | 表格版（| Option | Summary | Pros | Cons | Cost |） |
| 2 方案且决策维度明确 | 章节版（## 方案 A / ## 方案 B） |
表格版示例（适用于复杂变更）：
| Option | Summary | Pros | Cons | Cost |
|--------|---------|------|------|------|
| A | Adapter + Strategy 分层 | 独立测试每层；可替换；新增方向只需加子类 | 文件较多，小项目 over-engineering | ~350 LOC |
| B | 单 Service + 配置驱动 | 文件少（≈3）；定位快 | 方向增多 service 膨胀；切换 LLM 需改代码 | ~200 LOC |
章节版示例（适用于 2 方案）：
## 方案 A：python-jose + slowapi
**架构**: app/middleware/auth.py → JWTAuthMiddleware (FastAPI Depends)
**优点**: 各库职责单一，组合灵活；slowapi 支持多种存储后端
**缺点**: 多个依赖，需协调版本兼容
## 方案 B：FastAPI Users + fastapi-limiter
**架构**: FastAPI Users 认证框架，开箱即用
**优点**: 注册/登录/密码重置开箱即用
**缺点**: 耦合度高，定制困难；非标准 JWT 实现
3. Decision（决策）
## Decision
**选定**: 方案 [标识]
**理由**:
1. [首要理由，关联核心需求 / CHANGE Success Criteria]
2. [其次理由，关联非功能性需求 / 团队能力]
3. [取舍说明：放弃了什么方案/特性，为什么可接受]
- 每条决策记录：备选方案 → 选择理由 → 接受的代价
- 如多个独立决策点（例如：缓存选 Redis vs Memcached + 队列选 Celery vs arq），分别记录各自 Decision
4. Architecture（架构）
4.1 架构图
用 ASCII art 或 Mermaid 展示系统结构：
┌─────────────────────────────────────┐
│ Component Name │
│ ┌──────────┐ ┌──────────┐ │
│ │ Module │ │ Module │ │
│ └────┬─────┘ └────┬─────┘ │
│ │ │ │
│ ┌────▼─────────────▼─────┐ │
│ │ Core │ │
│ └────────────────────────┘ │
└────────────────────────────────────┘
要求：
- 展示模块间依赖方向（
→或─→） - 标注外部服务 / 系统边界
- 体现分层关系（Controller → Service → Adapter）
- 图形不必完美 ASCII，但要清晰表达结构
4.2 数据流
区分场景描述请求/数据流转：
**Data flow — 同步**:
Request → Middleware → Controller → Service → Adapter → Response
**Data flow — 流式/异步**:
Request → Controller → Service
→ async generator → SSE events
- 同步和异步（如有）分别描述
- 标注关键中间步骤（如缓存检查、限流判断、错误重试）
4.3 模块文件树
只列本 change 新增/修改的文件，按项目实际模块结构组织。以下为示意格式，实际路径、文件名、层数按技术栈定：
src/
├── <controller-layer>/ # 路由/控制器（如 controllers/、routes/、handlers/）
│ └── <new-file>.ts # 本 change 新增/修改
├── <service-layer>/ # 业务层（如 services/、use-cases/）
├── <data-layer>/ # 数据层（如 repositories/、models/、db/）
├── <adapter-layer>/ # 外部集成（如 adapters/、clients/、providers/）
└── tests/
└── <test-file>.ts # 对应测试文件
替代写法（直列，适合短列表）：
- src/routes/translate.ts # POST /api/translate（新增）
- src/services/translate.ts # 翻译业务编排（新增）
- src/adapters/llm/openai.ts # OpenAI LLM 调用（修改）
- src/tests/test_translate.py # 单元测试（新增）
要求：
- 只列本 change 新增/修改的文件，不列未改动的既有文件
- 重要文件标注职责（行内注释
#或//） - 文件树边界应与后续 TASK.md
write_files一致 - 层名按项目已有风格（Controller / Handler / UseCase / Service / Repository 等）
5. Risks & Mitigations
| Risk | Likelihood | Impact | Mitigation |
|---|---|---|---|
| OpenAI API key 未配置导致运行时错误 | Medium | High | 启动时校验，缺失时早失败（config.py） |
| SSE 流式被 nginx 缓冲 | Low | Medium | 响应头加 X-Accel-Buffering: no |
| 新增方向需改 factory 逻辑 | Medium | Low | 注册表模式，新增只加注册行不改逻辑 |
- Likelihood（低/中/高）和 Impact（低/中/高）可选但推荐
- 每条 Mitigation 必须是可执行动作，不是"注意"或"小心"
6. Verification Checklist
这是跟 taiyi-test 的衔接契约。每条对应一个可执行的测试验证。
| # | Check | Method | Links to REQUIREMENT |
|---|---|---|---|
| 1 | POST /translate 返回 200 + 正确翻译 | pytest tests/test_controllers.py -k test_sync |
US-1 AC |
| 2 | 未认证请求返回 401 | pytest tests/test_middleware.py -k test_unauthorized |
US-2 AC |
| 3 | 6 个翻译方向均可路由 | pytest tests/test_strategies.py -v |
US-3 AC |
要求：
- Method 列必须是可直接执行的命令（含参数），不是"写测试"这种模糊描述
- Links to REQUIREMENT 列追踪到 REQUIREMENT.md 的 AC 编号
- Verification Checklist 也是 review 阶段确认测试覆盖的依据
7. Open Questions
记录设计阶段无法确定的问题及其结论：
## Open Questions
- [x] API 端口固定或可配置？ → 可配置（config.py）
- [ ] 日志写入文件还是 stdout？ → **待决策：需要 PM 确认**
- 已解决标注
[x]，未解决标注[ ]并标记待谁决策 - 本阶段结束时不应有未解决的高影响 Open Question
8. Architecture 沉淀建议
入选阈值：可复用抽象 / 项目级决策 / 跨模块契约 / 依赖变动。无则写"无建议"。
## Architecture 沉淀建议
- Adapter + Strategy 分层 → 提取为项目级架构模式文档（建议 ADR-003）
过关（Harness）
- 逐项检查
## 质量自检；有未通过项则不要过关。 - 预检：
scripts/taiyi-forge.sh status <slug> --json --compact— 解析engineTruth（qualityReady/blockers）。 - 用户确认后过关：
scripts/taiyi-forge.sh continue <slug> --approver "名"（design 人工门）。 - 过关后再
status --json --compact，读engineTruth；若currentPhase已变为ui-design或task，切换到对应 Skill 并通知用户。
Legacy：npx taiyi complete <slug> design --approver "名" 仍可用；聊天优先 /taiyi:continue。
产出
.taiyi/changes/<slug>/DESIGN.md.taiyi/changes/<slug>/design.json
与下游衔接
| 下游 | 需要 |
|---|---|
taiyi-ui-design |
组件定义 → UI 组件映射；数据流 → States 表；Brownfield 约束 → UI 约束范围 |
taiyi-task |
模块列表 → 切片边界；文件树 → write_files 边界；禁动清单 → 不可修改区；Verification Checklist → 测试任务所需断言 |
异常处理
continue被拒：最常见原因是缺少人工--approver、只有单方案（非 lite 以下 profile）、或 Open Questions 有未解决高影响项。展示原因 → 让用户决定补充方案或确认可接受 → status 再 continue。- Brownfield 对齐检查发现架构冲突：在 Open Questions 中记录冲突，不能在 DESIGN 中预先决定架构变更。
- Profile 判定跳过本阶段但门禁拦截：确认 profile 设置 → 如是 skip profile（
micro/spike/nano），向用户说明并人工放行。 - 误过关本阶段或后续：
scripts/taiyi-forge.sh undo <slug> design。
质量自检
- 前置门禁 3 项全部通过（0.1–0.3）
- Profile 判定已确认，DESIGN.md 深度符合 profile 要求
- Options ≥ 2 方案（full/api/ui profile），或记录了取舍理由（lite）
- 每条决策记录了选择理由和接受的代价
- Architecture 包含架构图 + 数据流（同步 & 异步）+ 文件树（full / api profile）
- Risks & Mitigations 已记录（full profile）
- Verification Checklist 每条均有可执行 Method（full/api profile）
- Open Questions 无未解决的高影响项
- 架构沉淀建议已处理（或写"无建议"）
- 没有写入任务切片或实现细节
引擎门控（自动，无需手动确认）
- Data Flow 强制: api/full profile 必须包含数据流描述（调用链）→ 阻止
- 设计审查: auditDesignApproach 检查方案对比/取舍/模块清单 → 阻止
- 安全威胁: full/api profile 的 security_threats 至少 1 条 → 阻止过关