java-openspec

English

从 Java Spring Cloud 项目自动生成 OpenSpec store 的 CLI 工具。

功能

• 自动检测 Maven 多模块项目中的 Spring Boot 微服务模块
• 基于 CodeGraph AST 分析提取项目结构、命名规范、代码模式
• 使用 LLM 生成规范文档（项目总览、编码规范、架构规范、安全规范），或无 LLM 模式输出原始分析数据
• 按服务生成 business-domains.md（方法级表格）+ 全局领域导航索引
• 按服务生成 api-contracts.md（完整端点信息）
• 使用 Mermaid 生成 C4 架构图 + 业务时序图（角色感知，动态构建）
• 输出为 OpenSpec 1.7.0 store，自动注册

前置条件

| 工具 | 最低版本 | 用途 | 检查命令 | |------|---------|------|---------| | Bun | 1.3 | 运行时 | bun --version | | CodeGraph | 1.5 | Java AST 分析 | codegraph --version | | OpenSpec | 1.7 | Store 创建与注册 | openspec --version |

安装 CodeGraph

codegraph --version

安装 OpenSpec

npm install -g @fission-ai/openspec@latest
openspec --version

安装

# 通过 npm 安装
npm install -g java-openspec

# 或通过 Bun 安装
bun add -g java-openspec

# 验证
java-openspec --version

配置 LLM

.env 文件按以下优先级查找：

1. $JAVA_OPENSPEC_ENV - 显式指定路径
2. $PWD/.env - 当前工作目录
3. ~/.config/java-openspec/.env - XDG 全局配置

# 全局配置 (推荐)
mkdir -p ~/.config/java-openspec
cp .env.example ~/.config/java-openspec/.env

支持两种 LLM 后端：

OpenAI 模式（默认）

使用 OpenAI API 格式，兼容任何 OpenAI-compatible 服务。需要 OPENAI_API_KEY。

# .env 示例 - OpenAI
OPENAI_API_KEY=sk-xxx
LLM_MODEL=gpt-4o-mini
LLM_BASE_URL=https://api.openai.com/v1

ACP 模式（无需 API key）

当 OPENAI_API_KEY 未设置时，java-openspec 可通过 ACP (Agent Client Protocol) 连接已有的 AI agent。agent 使用自己的 LLM 凭证处理调用，无需额外 API key。

# .env 示例 - ACP 模式
ACP_AGENT_CMD=opencode acp

# 其他兼容 agent：
# ACP_AGENT_CMD=claude-code-acp
# ACP_AGENT_CMD=gemini --experimental-acp

ACP 模式行为：

• 权限控制：agent 可以读文件（fs/read_text_file），但不能写文件或执行终端命令
• Token 报告：显示 N/A (ACP mode)，因为 agent 不一定返回 token 用量
• 并发：使用多 session 并行（一个 agent 进程，多个 ACP session）

LLM Provider 架构

flowchart TB
    GD["generateDocs()"] --> CP{"createProvider()"}

    CP -->|"OPENAI_API_KEY 存在"| OAI["OpenAIProvider<br/>HTTP API + API key"]
    CP -->|"无 key, ACP_AGENT_CMD 存在"| ACP["ACPProvider<br/>stdio + agent 子进程"]
    CP -->|"都没有"| NL["无 LLM 模式<br/>输出原始分析数据"]

    OAI -->|"4+N 并行 HTTP 请求"| API["OpenAI-compatible API"]
    ACP -->|"4+N 并行 session"| AGENT["ACP Agent<br/>opencode acp / claude-code-acp / ..."]
    NL -->|"直接提取"| RAW["内置模板 + 前缀映射"]

Provider 抽象层（src/providers/）将 LLM 调用与 pipeline 解耦。无 LLM 配置时自动降级为无 LLM 模式，直接输出结构化分析数据。

用法

单项目模式

java-openspec init /path/to/mall-swarm

多路径模式

不同微服务分布在不同目录时，使用配置文件：

# java-openspec.yml
name: mall-specs             # 可选，store 名称（默认: workspace-specs）
exclude:                     # 可选，要跳过的模块（精确名称匹配）
  - mall-demo
services:
  mall-admin: /home/liyf/gitrepo/mall-admin
  mall-portal: /home/liyf/gitrepo/mall-portal
  mall-common: /home/liyf/gitrepo/mall-common

# 与 --config 配合时 project-path 可省略（默认为当前目录）
java-openspec init --config java-openspec.yml

# 或显式指定输出目录
java-openspec init --config java-openspec.yml --output /path/to/store

输出

<project>-specs/
├── .openspec-store/
│   └── store.yaml               # Store 元数据 + remote URL
└── openspec/
    ├── config.yaml              # 自动填充 context + rules（供 AI 工具使用）
    ├── specs/                   # OpenSpec 需求规格（免 LLM 生成）
    │   ├── coding-conventions/spec.md
    │   ├── service-architecture/spec.md
    │   └── security-patterns/spec.md
    └── docs/
        ├── overview.md           # 全局项目总览（含交叉引用）
        ├── coding-style.md       # 全局编码规范（LLM 或原始数据）
        ├── architecture.md       # 全局架构规范（LLM 或原始数据）
        ├── security.md           # 全局安全规范（LLM 或原始数据）
        ├── business-domains.md   # 领域导航索引（免 LLM，自动生成）
        ├── diagrams/
        │   ├── context.mmd               # C4 System Context
        │   ├── data-flow.mmd             # 数据流图
        │   ├── <service>-container.mmd   # C4 Container（角色感知）
        │   └── <service>-flow.mmd        # 业务时序图
        └── <service>/
            ├── architecture.md
            ├── business-domains.md       # 按服务方法级业务域概览
            └── api-contracts.md          # 按服务 API 端点 + Feign 客户端

工作流程

detect → analyze → generate-diagrams → generate-docs → create-store → validate

1. detect — 扫描 pom.xml，识别微服务模块与公共库模块
2. analyze — CodeGraph 索引 + 文件扫描，提取命名模式、调用路径、安全模式
3. generate-diagrams — Mermaid flowchart/sequenceDiagram 生成（角色感知，动态构建）
4. generate-docs — LLM 或无 LLM 根据分析结果 + 模板生成 spec 文档
5. create-store — 调用 openspec CLI 创建 store、注册并校验
6. validate — openspec store doctor 校验输出

项目结构

src/
├── index.ts              # CLI 入口
├── pipeline.ts           # 主流程编排
├── detect.ts             # Maven 项目检测
├── analyze.ts            # CodeGraph 分析（通过 codegraph explore 提取注解）
├── generate-diagrams.ts  # Mermaid 图表生成（角色感知，动态构建）
├── generate-docs.ts      # LLM / 无 LLM 文档生成
├── providers/            # LLM provider 抽象层
│   ├── index.ts          # createProvider() 选择逻辑
│   ├── openai-provider.ts # OpenAI 后端
│   └── acp-provider.ts   # ACP (Agent Client Protocol) 后端
├── create-store.ts       # OpenSpec store 创建 + spec 生成
├── postprocess.ts        # LLM 输出后处理
├── env.ts                # .env 加载
├── pricing.ts            # Token 费用估算
├── i18n.ts               # 中英文国际化
└── types.ts              # 类型定义
templates/                # LLM prompt 模板（zh/en）
spec-templates/           # Spec 结构校验 schema
test/                     # 单元测试

技术栈

• 运行时: Bun + TypeScript
• LLM: OpenAI-compatible API 或 ACP (Agent Client Protocol)
• 分析: CodeGraph + 文件扫描
• 图表: Mermaid (flowchart + sequenceDiagram，角色感知)
• 文档校验: unified + remark-parse (Markdown AST)
• 配置: YAML (js-yaml)