yzw-openspec-cn

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

前置依赖

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

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

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

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

初始化配置

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

① 项目基础

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

③ 数据库

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

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

④ Elasticsearch

⑤ SSO 认证

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

⑥ 应用配置

管道模式（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

配置归属原则

初始化后生成什么

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 工具：

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

AI 工作流

会话初始化与前置动作

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

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

工作流命令

归档自动知识总结

执行 /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 配置差异

发布

npm login
npm publish

许可

MIT