Trae-CN + OpenSpec-CN 实战:中文环境下 Java 项目的规范驱动开发全流程

原创2026-10-10 13:23:472,226 阅读
文章标签:开发工具CLIAI 技能代码智能体需求管理

Trae-CN + OpenSpec-CN 实战:中文环境下 Java 项目的规范驱动开发全流程

"AI 写完就改、改完就跑偏、跑偏就返工"——这是过去两年 AI 编程最典型的失速点。OpenSpec 给出的答案不是换一个更强的模型,而是把开发流程本身结构化成规范:先让 AI 产出 proposal、spec、design、tasks 四类产物,人审阅通过后才允许动代码。而 Trae-CN(字节跳动的 AI IDE)恰好是 OpenSpec 官方支持矩阵里对中文开发者最友好的一环:openspec init --tools trae 一条命令,就能把整套 /opsx:* 工作流装进 IDE 的 Skills 与 Commands 体系。本文以 Java + SpringBoot 项目为对象,完整跑一遍"环境准备 → 规则与技能自定义 → 规范驱动开发 → 中文乱码修复"的全流程,所有细节均对照仓库真实源码。

环境准备:Node.js / JDK / Maven 版本组合

OpenSpec 是一个运行在 Node.js 上的 CLI(package.json 中 bin 字段指向 ./bin/openspec.js),它对运行时版本有硬性要求。在 docs/installation.md 与 package.json 的 engines 字段中可以交叉验证:

"engines": {
  "node": ">=20.19.0"
}

Node.js 20.19.0 以下版本无法可靠运行,安装前先执行 node --version 确认。全局安装与项目初始化各一条命令:

npm install -g @fission-ai/openspec@latest
cd your-java-project && openspec init --tools trae

JDK 与 Maven 的选型与 OpenSpec 本身无关,但决定了 AI 生成代码的编译基线。中文团队最常见的是两套组合:

组合 JDK Maven SpringBoot 适用场景
兼容老栈 JDK 8 Maven 3.6+ 2.x 存量系统、依赖老中间件
现代栈 JDK 17/21 Maven 3.9+ 3.x 新项目、云原生

强烈建议把 JDK/Maven 版本写进 OpenSpec 的项目配置(见下一节),否则 AI 会按自己的默认假设生成 javax.* 或 jakarta.* 包名,编译期才发现整套不匹配。

规则与技能自定义:.trae-rules 与 .trae-skills 的落地方式

Trae-CN 与 OpenSpec 的集成不是插件商店式的黑盒,而是文件即接口:openspec init 会在项目里生成 .trae/skills/openspec-*/SKILL.md 与 .trae/commands/opsx-<id>.md。这在 docs/supported-tools.md 的 Tool Directory Reference 里有明确登记:

| Trae (`trae`) | `.trae/skills/openspec-*/SKILL.md` | `.trae/commands/opsx-<id>.md` |

对应的生成逻辑在源码 src/core/config.ts 中,Trae 的工具元数据为 skillsDir: '.trae' 且 requiresIdeRestart: true(生成后需重启 IDE 让 Skills 生效);命令文件的格式则由 src/core/command-generation/adapters/trae.ts 定义——opsx-<id>.md 带 name/description frontmatter,这也是为什么你在 Trae 聊天框里输入的是 /opsx-propose 而不是 /opsx:propose(后者是 Claude Code 的命名空间风格,详见 docs/how-commands-work.md)。

所谓"自定义",真正的主战场是 openspec/config.yaml。仓库自带示例 openspec/config.yaml 展示了核心字段:schema 声明工作流模型,context 注入项目背景,rules 按 artifact 类型追加约束。对 Java 项目,可以这样写:

schema: spec-driven

context: |
  语言:中文(简体)
  所有产出物必须用简体中文撰写,保留 OpenSpec 结构性标题与 SHALL/MUST 关键字为英文。

  Tech stack: Java 17, Spring Boot 3.2, Maven 3.9
  Package naming: com.example.ordersvc
  API conventions: RESTful, JSON responses, snake_case fields
  Database: MySQL 8, MyBatis-Plus
  Encoding: 所有源文件 UTF-8,禁止 GBK

rules:
  specs:
    - 每个需求必须包含可测试的 WHEN/THEN 场景
  design:
    - 涉及第三方依赖时必须给出选型理由与备选方案
  tasks:
    - 每个任务必须写明验证方式(编译命令或测试用例)

这套机制的生效逻辑在 docs/opsx.md 有完整说明:context 会被包裹进 <context>...</context> 标签、前置注入到每一个 artifact 的生成指令中;rules 只在匹配的 artifact 生成时注入,位于 context 之后、模板之前。中文场景下的关键配置参考 docs/multi-language.md:

context: |
  语言:中文(简体)
  所有产出物必须用简体中文撰写。

注意一个纪律:结构性标题与 SHALL/MUST 规范关键字保持英文——因为 openspec validate 依赖这些关键字做解析校验。中文只作用于需求与场景的叙述文字,这是"中文产出"与"机器可校验"之间的安全边界。

规范驱动开发的四类产物与真实样例

配置就绪后,在 Trae 聊天框输入 /opsx-propose,AI 会按 schemas/spec-driven/schema.yaml 定义的依赖图依次生成四类 artifact:proposal → specs → design → tasks,apply 阶段依赖 tasks 才能开始。仓库里大量真实变更可以作为参照,例如 openspec/changes/add-amp-support/proposal.md 的 Why / What Changes / Capabilities / Impact 结构,以及 openspec/changes/add-amp-support/specs/ai-tool-paths/spec.md 的 Delta 规范:

## ADDED Requirements

### Requirement: Amp skills integration
OpenSpec SHALL expose Amp as a supported skills-only tool...

#### Scenario: Selecting Amp
- **WHEN** the user selects Amp in `openspec init` or passes `--tools amp`
- **THEN** OpenSpec SHALL generate the active profile's skills under `.agents/skills/`

这就是规范驱动开发的核心形态:需求先以"可测试的行为契约"固化下来,AI 只负责把契约翻译成代码。任务分解则由 openspec/changes/add-amp-support/tasks.md 展示——- [ ] X.Y 描述 的 checkbox 是 apply 阶段解析进度的真实依据(schemas/spec-driven/schema.yaml 中 apply.tracks: tasks.md 明确指定了这一点)。

SpringBoot 项目实战:从提案到归档

在 Trae 中,完整闭环是四步节奏(对应 docs/getting-started.md 的 core profile 流程):

/opsx-explore     # 可选:先和 AI 把需求聊清楚
/opsx-propose     # 生成 proposal + specs + design + tasks
/opsx-apply       # AI 按 tasks.md 逐项实现并勾选
/opsx-archive     # 变更归档,delta spec 合并进主规范

以一个"订单查询接口"为例,/opsx-propose 会产出 openspec/changes/add-order-query/,其中 specs/order-query/spec.md 定义接口契约,tasks.md 拆解为"1. 实体与 Mapper、2. 服务层、3. Controller、4. 集成测试"若干组。/opsx-apply 阶段 AI 每完成一项就勾选一项,遇到实现与规范冲突时,正确姿势是回头修 artifact(/opsx-update)而不是让代码偏离规范——这正是"规范即真相"的含义。

整个开发状态可以通过终端侧的 CLI 随时检视:

openspec status --change add-order-query --json   # 查看各 artifact 进度
openspec validate --all                           # 全量校验
openspec list                                     # 浏览在途变更

需要说明的是,OpenSpec 对 Java 生态没有特殊适配层,它的威力在于把语言无关的需求契约固化下来:Controller 的入参校验、异常码、分页语义写进 spec,AI 无论换成哪个模型都按同一份契约生成,团队评审的也是同一份契约。这正是社区实践中"需求还原失真、代码反复返工"痛点的直接解药。

中文乱码修复:一条从解析器到构建工具链的排查路径

中文环境下最隐蔽的坑不是代码逻辑,而是编码。乱码通常出现在两个层面,对应两条不同的修复路径。

路径一:OpenSpec 解析器层的 UTF-8 BOM 处理

Windows 上的编辑器(尤其记事本)保存 UTF-8 文件时会前置 BOM(EF BB BF),PowerShell 重定向输出同样会加。BOM 会让 Markdown 首行的 ## ADDED Requirements 匹配失败——需求标题解析不出来,openspec validate 就会报结构错误,表现为"规范看着没问题却校验不过"。

OpenSpec 在解析层已经内置了 BOM 清理:在 src/core/parsers/markdown-parser.ts 中,normalizeContent 会先 content.replace(/^\uFEFF/, '') 再统一换行符;src/core/parsers/requirement-blocks.ts 的 normalizeLineEndings 同样如此,并注释了原因:"Windows editors and PowerShell redirects prepend one"。因此规范文件务必保存为 UTF-8(无 BOM),或用 Git 配置统一转换:

git config core.autocrlf input

路径二:Java 构建与运行链的编码统一

乱码在 SpringBoot 应用里通常分三处排查,且必须统一为 UTF-8:

Maven 编译编码——pom.xml 缺失或平台默认编码不同会导致中文注释、properties 乱码:

<properties>
  <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
</properties>

JVM 运行时编码——JDK 18 之前默认 file.encoding 取决于平台 locale,中文 Windows 上常落到 GBK。启动参数显式指定:

java -Dfile.encoding=UTF-8 -jar target/ordersvc.jar

HTTP 请求/响应编码——SpringBoot 中显式声明:

server.servlet.encoding.charset=UTF-8
server.servlet.encoding.enabled=true
server.servlet.encoding.force=true

这三处统一后,接口返回中文不再出现 ??? 或 锟斤拷。同样的纪律要写回 openspec/config.yaml 的 context——把"所有源文件 UTF-8、构建链强制 UTF-8"作为规则注入,AI 生成的代码与配置天然继承这套约定,乱码问题就在源头被消灭。

复盘:这套流程到底解决了什么

把整条链路串起来看,Trae-CN + OpenSpec-CN 的价值不在某个单点功能,而在于三个可验证的转变:

  1. 从对话到契约:需求先沉淀为 proposal/spec/tasks 三类产物,AI 的"脑补"空间被压缩到最小;仓库内 openspec/specs 与 openspec/changes 的长期积累,本身就是团队的活文档。
  2. 从黑盒到可审:/opsx-propose 只做规划、/opsx-apply 才动代码,人在回路中的每个节点都有产物可评审、有 validate 可校验。
  3. 从个人习惯到团队约定:一套 config.yaml + 规则注入,让多个 AI 助手、多个成员按同一标准产出;中文语境通过 context 注入,编码规范通过 rules 固化,规范驱动开发才真正在中文团队落地。

对于 Java 存量项目(棕地),这套流程同样适用——delta spec 机制天然支持在既有规范上做增量变更,不必推倒重来。先从一个接口、一个变更开始,把"先定规范、再写代码"的节奏跑顺,再逐步铺开到整个团队。

登录后查看全文
OpenSpec