news 2026/4/18 10:43:01

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

作者头像

张小明

前端开发工程师

1.2k 24
文章封面图
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 去重复用模块

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

流程:

  1. 读取zh.json和packages/business/src/asset/locales/zh/expense.json
  2. 对比内容（忽略非fe_开头的key）
  3. 重复内容优先使用expense.json的key
  4. 生成zh_duplicated.json记录重复key
  5. 更新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_xxxxxxxxxxxxxxx
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 优化点

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

6.2 性能指标

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

7. 安全性

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

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. 未来扩展

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

文档版本: 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)
版权声明: 本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：809451989@qq.com进行投诉反馈，一经查实，立即删除！
网站建设 2026/4/18 3:25:36

Wan2.1-I2V图生视频模型：140亿参数驱动静态图像动态化革命

Wan2.1-I2V图生视频模型&#xff1a;140亿参数驱动静态图像动态化革命 【免费下载链接】Wan2.1-I2V-14B-480P 项目地址: https://ai.gitcode.com/hf_mirrors/Wan-AI/Wan2.1-I2V-14B-480P 行业背景&#xff1a;多模态AI进入视频生成新阶段 随着人工智能技术的快速发展&…

作者头像 李华
网站建设 2026/4/17 20:36:12

FunASR完整使用指南：如何快速搭建高精度语音识别系统

FunASR完整使用指南&#xff1a;如何快速搭建高精度语音识别系统 【免费下载链接】FunASR A Fundamental End-to-End Speech Recognition Toolkit and Open Source SOTA Pretrained Models, Supporting Speech Recognition, Voice Activity Detection, Text Post-processing et…

作者头像 李华
网站建设 2026/4/17 15:54:13

快速上手SO-100双臂机器人：从零构建高精度同步控制系统

快速上手SO-100双臂机器人&#xff1a;从零构建高精度同步控制系统 【免费下载链接】SO-ARM100 Standard Open Arm 100 项目地址: https://gitcode.com/GitHub_Trending/so/SO-ARM100 当你面对双臂协作机器人的开发挑战时&#xff0c;是否曾为同步精度不足、硬件兼容性差…

作者头像 李华
网站建设 2026/4/18 2:42:31

RPCS3模拟器游戏汉化完整教程：从零到精通的终极指南

RPCS3模拟器游戏汉化完整教程&#xff1a;从零到精通的终极指南 【免费下载链接】rpcs3 PS3 emulator/debugger 项目地址: https://gitcode.com/GitHub_Trending/rp/rpcs3 想要在RPCS3模拟器上畅玩中文版PS3独占游戏&#xff1f;语言障碍不再是问题&#xff01;本教程将…

作者头像 李华
网站建设 2026/4/18 3:29:41

RuoYi动态数据源终极指南：企业级多数据库切换技术深度解析

RuoYi动态数据源终极指南&#xff1a;企业级多数据库切换技术深度解析 【免费下载链接】RuoYi &#x1f389; 基于SpringBoot的权限管理系统 易读易懂、界面简洁美观。 核心技术采用Spring、MyBatis、Shiro没有任何其它重度依赖。直接运行即可用 项目地址: https://gitcode.c…

作者头像 李华
网站建设 2026/4/18 5:23:24

1Panel面板OpenResty安装失败：5步快速解决方案指南

1Panel面板OpenResty安装失败&#xff1a;5步快速解决方案指南 【免费下载链接】1Panel 新一代的 Linux 服务器运维管理面板 项目地址: https://gitcode.com/feizhiyun/1Panel 1Panel作为新一代Linux服务器运维管理面板&#xff0c;为用户提供了便捷的应用部署体验。然而…

作者头像 李华