SDD规范驱动开发-与prompt区别-Agent业务场景示例-开发者社区

和prompt区别在于用途：
prompt 是“你现在想让我怎么做”，控制的是输出风格/内容倾向
但是 SDD 是“被允许、被约束、被评估要怎么做”，行为边界/决策空间/成功标准

Spec-Driven Development 规格驱动开发

先写“清晰、可执行、可验证的规格（Spec）“，再让系统按规格完成

行为先行、目标先行、约束先行

方法	核心关注点	问题解决方向
TDD	测试用例	代码正确性
DDD	领域模型	复杂业务建模
SDD	行为规格 / 约束	复杂系统协作 & Agent 行为一致性

SDD 更适合 AI Agent 、自动化系统、复杂流程编排

用于解决 Agent到底应该做什么、不应该做什么、做到什么程度算成功

为什么 Agent 需要 SDD

传统程序

输入 → 程序 → 输出

Agent 系统

目标 → 规划 → 推理 → 工具调用 → 状态变化 → 反馈 → 再决策

Agent 是有决策权的执行体，如果没有清晰规格会出现

行为发散
输出不可控
同一任务不同轮次表现不一致
多 Agent 协作互相踩踏

SDD就在Agent中定义了

目标
输入 / 可感知信息
决策约束
允许使用的工具
输出格式
禁止行为
成功条件

SDD 核心组成

1. Goal 目标定义

Goal: 帮助用户将自然语言需求转化为可执行的前端组件代码

2. Inputs 输入

Inputs: - 用户自然语言描述 - 当前项目技术栈（React + Tailwind） - 组件约束（是否可复用）

3. Contrains 约束

Constraints: - 只能输出 JSX + Tailwind - 不允许引入第三方 UI 库 - 不修改已有 API

4. Tools / Actions 能力边界

Allowed Actions: - generate_component - refactor_code - explain_design

5. Output Spec 输出规格

Output: - 类型: Markdown - 包含: - 组件代码 - Props 定义 - 使用示例

6. 成功判定

Success: - 代码可直接运行 - 不报 TS 错误 - UI 与描述一致

业务示例

在我的业务场景中需要支持系统的国际化全域支持，就需要编写SDD进行规范Agent调用MCP进行自动化替换文案

--- ruleType: Manual description: 软件设计文档（SDD）- i18n 国际化翻译工具 --- # 软件设计文档（SDD）— i18n 国际化翻译工具 ## 行为规范说明（Spec-Driven Development） 本工具基于 **Spec-Driven Development（SDD）** 进行设计，作为一套**可执行、可验证、可复用**的工程级规格说明文档。 所有功能模块均遵循以下原则： - 明确定义 **输入 / 输出 / 行为边界** - 所有流程具备 **可自动校验的成功标准** - 支持失败重试与错误回滚 - MCP 仅作为 **受控执行器**，不参与业务决策 --- ## 1. 概述 ### 1.1 目的 本文档描述了 MoneyMaster 项目中 **i18n 国际化翻译工具** 的整体设计与实现方案。 该工具用于自动化处理多端项目中的硬编码中文文案，实现多语言动态化支持，并降低国际化改造成本。 ### 1.2 范围 - 中文文本自动扫描与收集 - 翻译 Key 生成与可读性优化 - 存量翻译复用与去重 - 多语言批量翻译（英文 / 繁体中文 / 葡萄牙语） - 翻译结果导出与平台对接 - 源代码自动替换 - monorepo 架构下的跨端支持 ### 1.3 术语定义 - **i18n**：Internationalization（国际化） - **MCP**：Model Context Protocol（模型上下文协议） - **SDD**：Software Design Document - **Key**：国际化文案的唯一标识 --- ## 2. 系统架构 ### 2.1 整体架构

┌─────────────────────────────────────────────────┐
│ 用户交互层 │
│ (指定目录 → 执行翻译 → 获取结果) │
└──────────────────┬──────────────────────────────┘
│
┌──────────────────▼──────────────────────────────┐
│ 业务流程层 │
│ ┌──────────────────────────────────────────┐ │
│ │ 1. 文本收集 → collect_chinese_text │ │
│ │ 2. Key优化 → AI生成可读key │ │
│ │ 3. 去重复用 → 对比已有翻译 │ │
│ │ 4. 批量翻译 → merge_batch_translation │ │
│ │ 5. 导出Excel → generate_excel_table │ │
│ │ 6. 合并文件 → 写入locales目录 │ │
│ │ 7. 代码替换 → replace_with_i18n │ │
│ │ 8. 清理临时 → 删除中间文件 │ │
│ └──────────────────────────────────────────┘ │
└──────────────────┬──────────────────────────────┘
│
┌──────────────────▼──────────────────────────────┐
│ 工具服务层 │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │MCP工具集 │ │Node.js │ │文件系统 │ │
│ │(翻译API) │ │工具方法 │ │操作 │ │
│ └──────────┘ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────────┘

### 2.2 核心模块 #### 2.2.1 文本收集模块 **职责**: 扫描指定目录，提取所有中文文本 **输入**: - 目标目录路径 - key前缀 (默认: `fe`) **输出**: - `zh.json` - 包含所有中文文本及其唯一key **成功标准** - 所有中文文案被完整提取 - 生成的 Key 全部唯一 **关键逻辑**: ```typescript interface CollectedText { [key: string]: string; // key格式: fe_[描述]_[8位hash] }

2.2.2 Key优化模块

职责: 为翻译key生成可读性描述

规则:

文案 ≤8字: 在fe和8位hash之间插入英文描述（大驼峰，≤20字符）
文案 >8字: 保持key不变
连接符: 使用下划线_

成功标准

不改变文案语义
Key 稳定、可复现

示例:

{"fe_11e01543":"请输入",// 短文案"fe_InputPrompt_11e01543":"请输入",// 优化后"fe_22f02654":"这是一段很长的描述文本超过八个字",// 长文案"fe_22f02654":"这是一段很长的描述文本超过八个字"// 保持不变}

2.2.3 去重复用模块

职责: 检测并复用已有翻译

流程:

读取zh.json和packages/business/src/asset/locales/zh/expense.json
对比内容（忽略非fe_开头的key）
重复内容优先使用expense.json的key
生成zh_duplicated.json记录重复key
更新zh.json

数据结构:

interfaceDuplicatedKeys{duplicated_keys:string[];// ["fe_xxx", "fe_xx2"]}

2.2.4 批量翻译模块

职责: 调用MCP工具完成多语言翻译

目标语言:

英文 (en.json)
繁体中文 (zh-HK.json)
葡萄牙语 (pt-BR.json)

API调用:

// 伪代码awaitmcpTool.merge_batch_translation({source:'zh.json',targets:['en','zh-HK','pt-BR']});

2.2.5 Excel导出模块

职责: 生成可导入美团i18n平台的Excel表格

表格结构:

Key	中文	英文	繁体	葡语
fe_xxx	xxx	xxx	xxx	xxx

2.2.6 文件合并模块

职责: 将翻译结果合并到项目locales目录

目标路径:

packages/business/src/asset/locales/ ├── zh/expense.json ├── en/expense.json ├── zh-HK/expense.json └── pt-BR/expense.json

合并策略: 追加新key，保留原有key

2.2.7 代码替换模块

职责: 将硬编码中文替换为i18n函数调用

替换模式:

// 替换前constmessage="请输入业务申请单号";// 替换后import{i18nClient}from'@sailor/i18n-web';constmessage=i18nClient.t('fe_InputPrompt_11e01543','请输入业务申请单号');

2.2.8 清理模块

职责: 删除临时文件，保留最终产物

保留:translations.xlsx
删除:zh.json,en.json,zh-HK.json,pt-BR.json,zh_duplicated.json, 临时工具脚本

3. 数据流

[指定目录] ↓ [扫描中文文本] → zh.json (原始) ↓ [优化Key] → zh.json (优化后) ↓ [去重复用] → zh.json (去重) + zh_duplicated.json ↓ [批量翻译] → en.json, zh-HK.json, pt-BR.json ↓ [生成Excel] → translations.xlsx ↓ [合并文件] → locales/*/expense.json ↓ [代码替换] → 源代码文件更新 ↓ [清理临时文件] → 仅保留Excel

4. 接口设计

4.1 MCP工具接口

collect_chinese_text

interfaceCollectChineseTextParams{directory:string;// 扫描目录prefix:string;// key前缀outputFile:string;// 输出文件路径}

merge_batch_translation

interfaceMergeBatchTranslationParams{sourceFile:string;// 源文件 (zh.json)targetLanguages:string[];// 目标语言数组}

generate_excel_table

interfaceGenerateExcelTableParams{jsonFiles:string[];// 所有语言的json文件outputFile:string;// 输出Excel路径}

replace_with_i18n

interfaceReplaceWithI18nParams{directory:string;// 目标代码目录translationFile:string;// zh.jsonimportStatement:string;// i18n导入语句}

4.2 Node.js工具方法

compareAndReuse

functioncompareAndReuse(newTranslations:Record<string,string>,existingTranslations:Record<string,string>):{updated:Record<string,string>;duplicated:string[];}

removeDuplicateKeys

functionremoveDuplicateKeys(translations:Record<string,string>,duplicatedKeys:string[]):Record<string,string>

5. 错误处理

5.1 常见错误场景

错误类型	描述	处理策略
目录不存在	指定的扫描目录无效	提示用户检查路径
文件读写失败	json文件操作失败	记录错误日志，回滚操作
MCP工具调用失败	翻译API异常	重试3次，失败后人工介入
Key冲突	生成的key已存在	重新生成hash
合并冲突	locales文件格式不匹配	备份原文件，记录冲突

5.2 日志记录

每步操作记录开始/结束时间
记录处理的文件数量和key数量
记录所有错误和警告信息

6. 性能考虑

6.1 优化点

批量处理: 一次性提交所有翻译请求
增量更新: 只翻译新增的文本
缓存机制: 复用已有翻译结果
并行处理: 多语言翻译可并行执行

6.2 性能指标

单次翻译处理: 1000条文本 < 5分钟
文件操作: < 1秒
Excel生成: < 3秒

7. 安全性

文件备份: 修改locales文件前自动备份
权限检查: 确保有文件读写权限
数据校验: 验证json格式正确性
敏感信息: 不翻译包含敏感词的文本

8. 测试策略

8.1 单元测试

Key生成逻辑
去重算法
文件合并逻辑

8.2 集成测试

完整流程端到端测试
各MCP工具调用测试

8.3 测试用例

describe('i18n翻译工具',()=>{it('应该正确收集中文文本',()=>{});it('应该为短文案生成可读key',()=>{});it('应该识别并复用重复翻译',()=>{});it('应该生成正确格式的Excel',()=>{});it('应该正确替换代码中的硬编码',()=>{});});

9. 部署与维护

9.1 依赖

Node.js >= 16
MCP工具集
Excel生成库 (如 exceljs)

9.2 配置

{"keyPrefix":"fe","localesPath":"packages/business/src/asset/locales","tempDir":".i18n","backupEnabled":true,"maxRetries":3}

9.3 维护检查清单

定期更新MCP工具版本
检查翻译质量
清理过期备份文件
监控翻译API额度

10. 未来扩展

增量翻译: 支持只翻译变更部分
翻译审核: 添加人工审核流程
多项目支持: 支持批量处理多个项目
可视化界面: 提供Web界面操作
翻译记忆库: 建立跨项目的翻译库

文档版本: v1.0.0
创建日期: 2025-12-13
维护者: ceilf6

## 分析 1. 架构设计 - 用户交互层 - 业务流程层 - 工具服务层 - MCP 1. Key策略 - hash确保稳定性 - 短文案提升可读性 - 长文案避免误导 1. 去重复用模块 考虑到作为平台级别的i18n - 重复内容优先使用既有key 1. MCP 明确MCP的输入输出 明确失败重试 明确是工具接口 1. 行为规范 SDD → Agent SDD 1. 每个模块的成功判定 1. “MCP 工具仅作为受控执行通道，不参与业务决策。**”** 架构安全意识 [Spec-Hub MCP - SDD 流程编排](https://www.notion.so/Spec-Hub-MCP-SDD-2c30f8d8d1fd802a8252ccdfc17fea5b?pvs=21) [Spec Coding 研发范式应用（spec-kit、BMAD-METHOD、OpenSpec）](https://www.notion.so/Spec-Coding-spec-kit-BMAD-METHOD-OpenSpec-2c30f8d8d1fd80139396f94c884e87d2?pvs=21) [业务需求 Spec Coding 实践路径](https://www.notion.so/Spec-Coding-2c30f8d8d1fd80488edbeca1d57e39b8?pvs=21)