yzw-openspec-cn

OpenSpec 脚手架 — 一键初始化 AI 辅助开发工作流，支持 OpenCode 和 ClaudeCode。

前置依赖

| 工具 | 用途 | 安装方式 | |------|------|---------| | Node.js >= 18 | 运行本脚手架 | nodejs.org | | Python 3 | 数据库连接、HTTP 请求、图像处理 | python.org | | opencode CLI | AI 开发工作流引擎（含 CodeGraph） | npm install -g @opencode-ai/cli | | Claude Code | 备用 CLI | npm install -g @anthropic-ai/claude-code |

OpenCode 和 ClaudeCode 二选一即可。

安装

npm install -g yzw-openspec-cn

安装时自动完成以下步骤（均走国内镜像，无需代理）：

1. pip3 install -r requirements.txt → 安装 pymysql / redis / pymongo / requests / pyyaml / playwright / Pillow / pytesseract
2. playwright install chromium → 安装无头浏览器（原型截图）

如安装失败，手动执行：pip3 install -r requirements.txt && playwright install chromium

可选依赖（按需手动安装）

| 工具 | 用途 | macOS | Windows | Linux | |------|------|-------|---------|-------| | tesseract | OCR 文字识别 | brew install tesseract | UB-Mannheim 安装器 | apt-get install tesseract-ocr | | jadx | JAR 反编译 | brew install jadx | GitHub Releases 下载 zip | wget + unzip | | Java 11+ | jadx 运行时依赖 | brew install openjdk | Adoptium | apt-get install openjdk |

tesseract 和 jadx 非必须，不影响 coding/验证等核心流程。原型分析和 JAR 反编译时才需要。

或免安装方式：

npx yzw-openspec-cn

使用

基本命令

yzw-openspec-cn init --cli opencode     # 初始化 OpenCode 项目（默认）
yzw-openspec-cn init --cli claudecode   # 初始化 ClaudeCode 项目
yzw-openspec-cn upgrade                 # 升级已有项目的模板/技能/配置
yzw-openspec-cn upgrade --target /path  # 升级指定目录的项目

升级已有项目

当脚手架发布新版本后，在项目根目录执行：

cd service-{项目名}
yzw-openspec-cn upgrade

升级会更新以下内容（不覆盖用户数据）：

| 会更新 | 不会动 | |--------|--------| | AGENTS.md / CLAUDE.md | .knowledge/config/profile.yaml | | .opencode/ 或 .claude/ 下全部技能和命令 | .knowledge/config/project.yaml | | opencode.json / .mcp.json / settings.json | .knowledge/business/（业务知识） | | 新增知识文件（如 java-coding-standards.md） | .knowledge/tech/db/、api/、ddl/（已积累的知识） | | | .knowledge/risks/（踩坑记录） | | | openspec/changes/（活跃变更） |

初始化配置

按提示依次填写 6 组配置，所有字段有默认值，直接回车跳过即可。

① 项目基础

| 字段 | 说明 | 示例 | |------|------|------| | 项目英文名 | 项目标识，用于目录和包命名 | crp, psc, contract | | 项目中文名 | 用于知识库标题 | 合同管理平台 | | 源码路径 | Java 项目根目录绝对路径 | /home/user/java/crp | | 包前缀 | Java 包名前缀 | cn.yzw.jc.crp | | 目标目录 | 生成的 OpenSpec 项目放在哪 | ./service-crp |

② 构建环境（存入 profile.yaml）

| 字段 | 默认值 | 说明 | |------|--------|------| | JDK 路径 | /path/to/jdk | JDK 安装目录 | | Maven 路径 | /path/to/mvn | mvn 命令路径 | | Maven settings | ~/.m2/settings.xml | Maven 配置文件 | | 代理地址 | http://127.0.0.1:10808 | 网络代理 |

③ 数据库

| 字段 | 默认值 | 说明 | |------|--------|------| | TiDB 主机 | localhost | 数据库地址 | | TiDB 端口 | 4406 | 数据库端口 | | TiDB 用户 | app_user | 数据库用户名 | | TiDB 库名 | {项目名} | 数据库名称 |

| TiDB 密码 | '' | 数据库密码 |

密码可在 CLI 中直接输入，也可初始化后编辑 .knowledge/config/project.yaml → mysql_password。

④ Elasticsearch

| 字段 | 默认值 | 说明 | |------|--------|------| | ES 地址 | localhost:9200 | ES 连接地址 | | ES 用户 | elastic | ES 用户名 | | ES 密码 | '' | ES 密码 |

⑤ SSO 认证

| 字段 | 默认值 | 说明 | |------|--------|------| | SSO 地址 | https://sso.example.com/api/login | 登录接口 | | AppKey | your_app_key | 应用标识 | | 登录名 | admin | SSO 账号 |

SSO 密码不通过 CLI 采集，初始化后编辑 .knowledge/config/profile.yaml → user.sso_password 填写。

⑥ 应用配置

| 字段 | 默认值 | 说明 | |------|--------|------| | 端口 | 8080 | 应用 HTTP 端口 | | Main 类 | Application | 启动主类 | | DevOps | https://devops.example.com | DevOps 平台地址 |

管道模式（CI / 自动化）

printf 'crp\n\n/home/user/java/crp\ncn.yzw.jc.crp\n./service-crp\n\n\n...\n' | yzw-openspec-cn init

每行对应一个字段，空行=使用默认值。

配置文件结构

project.yaml（入库 — 团队共享）

项目全局信息 + 团队共享服务地址/账号（不含密码）。

project:
  name: dup1
  package_prefix: cn.yzw.dup

  build:
    maven_profiles: '-P qa,!prd'  # 团队默认 Maven profile
    java_args: ''                  # JVM 参数（留空）

  services:
    sso_login_url: https://sso.example.com/api/login
    mysql_host: localhost
    mysql_port: 4406
    mysql_user: app_user
    mysql_database: dup1
    es_host: localhost:9200
    es_user: elastic
    redis_host: localhost
    redis_port: 6379

  app:
    port: 8080
    main_class: Application
    health_endpoint: /actuator/health

profile.yaml（gitignore — 每人自填）

个人环境 + 全部密码 + 工具凭据。此文件不入 git。

cp .knowledge/config/profile.yaml.example .knowledge/config/profile.yaml

user:
  name: your.name
  fullName: 你的姓名
  sso_login_name: admin        # SSO 登录名
  sso_password: YOUR_PASSWORD  # SSO 密码（明文，verification 自动 MD5）

env:
  JAVA_HOME: /path/to/jdk
  MAVEN_HOME: /path/to/mvn
  http_proxy: ''               # 默认不填
  https_proxy: ''
  maven_settings: ~/.m2/settings.xml
  maven_repo: ~/.m2/repository
  MAVEN_PROFILES: ''           # 空=用 project 默认
  SPRING_PROFILES: qa
  java_args: ''                # 自定义 JVM 参数，如 -Xmx2g
  source_dir: /path/to/workspace

dingtalk:
  webhook: https://oapi.dingtalk.com/robot/send?access_token=xxx
  secret: YOUR_SECRET

vision:
  provider: dashscope
  api_key: YOUR_API_KEY
  model: qwen-vl-plus

配置归属原则

| 信息类型 | 存放位置 | 入库？ | |---------|---------|--------| | 项目名、包前缀、模块路径 | project.yaml | ✅ | | 服务地址、端口、账号名 | project.yaml | ✅ | | 团队默认 Maven profile | project.yaml | ✅ | | JDK/Maven/代理路径 | profile.yaml | ❌ | | 本地工程路径 | profile.yaml | ❌ | | 所有密码（DB/ES/Redis/MongoDB） | project.yaml | ✅ | | 钉钉/视觉 API 凭据 | profile.yaml | ❌ |

初始化后生成什么

service-{name}/
│
├── AGENTS.md / CLAUDE.md         ← AI 工作流总指令
├── opencode.json                   ← OpenCode 专属配置（MCP + instructions）
├── .mcp.json                       ← ClaudeCode 专属 MCP 配置
│
├── .opencode/ 或 .claude/
│   ├── commands/                   ← 10 个工作流命令
│   │   ├── opsx-explore.md         → 需求探索
│   │   ├── opsx-propose.md         → 提案设计
│   │   ├── opsx-apply.md           → 编码实现
│   │   ├── opsx-verify.md          → 验证
│   │   ├── opsx-deliver.md         → 交付
│   │   ├── opsx-archive.md         → 归档（含知识库总结）
│   │   ├── opsx-learn.md           → 知识学习
│   │   ├── opsx-health.md          → 知识库健康巡检
│   │   ├── opsx-analysis.md        → 需求分析
│   │   └── opsx-clarify.md         → 需求澄清
│   │
│   ├── skills/                     ← 21 个 AI 技能
│   │   ├── openspec-explore/SKILL.md
│   │   ├── openspec-propose/SKILL.md
│   │   ├── openspec-apply-change/SKILL.md
│   │   ├── verification/SKILL.md
│   │   ├── delivery/SKILL.md
│   │   ├── openspec-archive-change/SKILL.md
│   │   ├── openspec-learn/SKILL.md
│   │   ├── knowledge-health/SKILL.md
│   │   ├── demand-analysis/SKILL.md
│   │   ├── demand-clarifier/SKILL.md
│   │   ├── prototype-analyzer/SKILL.md
│   │   ├── design-doc/SKILL.md
│   │   ├── workflow-schedule/SKILL.md
│   │   └── jadx-decompiler/SKILL.md
│   ├── settings.json               ← ClaudeCode 权限配置
│   └── package.json                ← plugin 依赖（仅 OpenCode）
│
├── openspec/
│   ├── config.yaml                 ← 项目全量配置
│   ├── changes/                    ← 活跃变更
│   └── specs/                      ← 主规范
│
├── .knowledge/
│   ├── INDEX.md                    ← 知识索引（开发中持续填充）
│   ├── config/
│   │   ├── profile.yaml            ← ⚠️ 需手动填入凭据（已 gitignore）
│   │   ├── profile.yaml.example    ← 凭据填写模板
│   │   └── project.yaml            ← 项目路径、模块、构建配置
│   ├── business/                   ← 业务领域模型
│   ├── tech/
│   │   ├── java-coding-standards.md   ← Java 编码规范
│   │   ├── database-standards.md      ← 数据库设计规范
│   │   ├── coding-workflow-sop.md     ← 编码工作流 SOP（8 步 22 条）
│   │   ├── knowledge-why-policy.md    ← WHY 记录策略
│   │   ├── api/                       ← API 设计规范
│   │   ├── db/                        ← 数据库表结构
│   │   └── ddl/                       ← DDL 脚本
│   ├── project/                    ← 项目概览
│   ├── ops/                        ← 运维知识
│   └── risks/                      ← 已知风险记录
│
├── scripts/
│   └── install-deps.py             ← 环境安装脚本
└── .gitignore

验证流程（数据库连接）

验证阶段需要连接 QA 环境数据库。所有连接均使用 Python，无需安装系统 CLI 工具：

| 数据库 | 连接方式 | Python 包 | |--------|---------|-----------| | MySQL/TiDB | python3 pymysql | pip3 install pymysql | | Redis | python3 redis | pip3 install redis | | MongoDB | python3 pymongo | pip3 install pymongo | | HTTP 请求 | python3 requests | pip3 install requests |

npm install -g yzw-openspec-cn 时自动安装全部依赖。密码从 project.yaml → services.*_password 读取，地址/账号从 project.yaml → services.* 读取。

AI 工作流

会话初始化与前置动作

每次启动时 AI 自动执行会话初始化（只一次）：读取 profile.yaml 获取源码目录 → 同步 CodeGraph 索引 → 完成。

每次编码任务前执行前置动作（每次）：搜索知识库索引 → 读取编码规范 → 开始实现。新项目的空知识库不会阻断流程。

工作流命令

| 命令 | 用途 | ClaudeCode 写法 | |------|------|----------------| | 需求探索 | 分析原型、澄清需求、输出确认清单 | /opsx:explore | | 提案设计 | 生成 proposal / design / tasks | /opsx:propose | | 编码实现 | 按 tasks.md 逐项编码 | /opsx:apply | | 验证 | 编译检查、接口验证、数据库校验 | /opsx:verify | | 交付 | 提交合并、部署上线、自动生成 checklist | /opsx:deliver | | 归档 | 归档变更、自动总结知识库、更新 INDEX | /opsx:archive | | 知识学习 | 全链路追踪代码，提取结构化知识 | /opsx:learn | | 健康巡检 | 知识库完整性和内容质量检查 | /opsx:health | | 需求分析 | 分析需求文档，提取功能点 | /opsx:analysis | | 需求澄清 | 生成澄清问题，可钉钉发送 | /opsx:clarify |

归档自动知识总结

执行 /opsx-archive 时，AI 会自动：

1. 从 design.md + git diff 提取 API / DB / Model / ES 变更信息
2. 追加到对应的 .knowledge/ 文件
3. 同步更新 INDEX.md
4. 最后问一句业务原因（WHY），可跳过

checklist 自动生成

首次交付时 checklist.md 不存在属正常情况。执行 /opsx-deliver 时 AI 会从 design.md 自动生成上线检查清单，不询问用户是否创建。

新项目空知识库不阻断

新项目初始化后 INDEX.md 为空、CodeGraph 可能索引不完整，均为正常初始状态。AI 不会因此中断任务，会用 grep 兜底继续执行。

OpenCode vs ClaudeCode 配置差异

| 配置项 | OpenCode | ClaudeCode | |--------|----------|------------| | 指令文件 | AGENTS.md | CLAUDE.md | | MCP 配置 | opencode.json 的 mcp 字段 | .mcp.json | | 权限配置 | opencode.json 的 permission 字段 | .claude/settings.json | | 插件目录 | .opencode/ | .claude/ | | 命令前缀 | /opsx-* | /opsx:* |

发布

npm login
npm publish

许可

MIT