插件面向 OpenCode V2,在运行时注册 commands / skills,并为会话提供工作流提示。
需要 OpenCode V2。在项目根目录的 opencode.json 中加入:
{
"$schema": "https://opencode.ai/config.json",
"plugins": ["@devcxl/opencode-spec"]
}前置条件:OpenCode 所使用的 shell 必须能直接执行 node。
原因:skills 会调用 JavaScript 参考脚本,这些脚本通过 node 执行。
OpenSpec 默认输出到项目根下的 openspec/ 目录。如需自定义,使用 V2 插件选项传入 directory:
{
"$schema": "https://opencode.ai/config.json",
"plugins": [
{ "package": "@devcxl/opencode-spec", "options": { "directory": "docs" } }
]
}也可通过环境变量 OPENSPEC_DIR 指定,优先级高于配置。
首次接入时,直接从 /opsx-propose 开始,或让 Agent 调用 openspec-propose skill;脚本会自动创建 OpenSpec 所需目录结构。
推荐工作流:
proposeapplyarchiveexplore(可选,随时使用)
建议这样理解:
propose:创建 change,并生成 proposal / specs / design / tasksapply:按任务推进实现并回写状态archive:在验证完成后归档这次变更explore:只做需求澄清与方案探索,不实现功能
常用入口:
- commands(12 个核心命令,支持 6 个标准简写别名):
/opsx-propose、/opsx-explore、/opsx-apply、/opsx-archive,以及标准简写/opsx-new、/opsx-continue、/opsx-ff、/opsx-update、/opsx-sync、/opsx-verify(同时完全兼容原/opsx-*-change命名) - skills(12 个核心技能,支持上游标准别名):
openspec-propose、openspec-explore、openspec-apply(及openspec-apply-change)、openspec-archive(及openspec-archive-change)及 8 个扩展技能
如果你希望:
- 让 Agent 按预设提示组织流程:优先用 commands / skills
- 显式执行底层脚本:skills 的 SKILL.md 中已内置脚本调用指引
命令对照表:
| 命令 | 别名 | Skill | 功能 |
|---|---|---|---|
/opsx-propose |
— | openspec-propose |
创建 change 并生成 proposal/specs/design/tasks |
/opsx-explore |
— | openspec-explore |
探索问题、澄清需求 |
/opsx-apply |
— | openspec-apply |
按 tasks 执行实现 |
/opsx-archive |
— | openspec-archive |
归档完成的 change |
/opsx-new-change |
/opsx-new |
openspec-new-change |
启动新变更,逐步创建 artifact |
/opsx-continue-change |
/opsx-continue |
openspec-continue-change |
继续创建下一个 artifact |
/opsx-ff-change |
/opsx-ff |
openspec-ff-change |
快速生成全部 planning artifacts |
/opsx-update-change |
/opsx-update |
openspec-update-change |
更新 planning artifacts 并保持一致性 |
/opsx-sync-specs |
/opsx-sync |
openspec-sync-specs |
同步 delta specs 到 main specs |
/opsx-verify-change |
/opsx-verify |
openspec-verify-change |
验证实现与 artifact 匹配 |
/opsx-bulk-archive |
— | openspec-bulk-archive-change |
批量归档多个变更 |
/opsx-onboard |
— | openspec-onboard |
引导式完整工作流教学 |
插件通过 OpenCode V2 接口在运行时注册 commands 和 skills,不向项目 .opencode/ 目录写入任何文件:
- commands:解析
assets/commands/并运行时注册,无需文件同步即可被/触发 - skills:直接从插件包的
assets/skills/读取,注册时在内存中替换 SKILL.md 的脚本路径;不创建临时副本或写入项目目录 - 会话提示:通过 V2 会话钩子提供 OpenSpec 工作流引导
这意味着无需重启 OpenCode 即可立即使用 commands 和 skills。
详细使用示例见 docs/zh/usage.md。
这个插件的核心思路是“纯运行时注入”——不向项目目录同步文件,而是通过 V2 插件接口在启动时注册能力:
- commands 运行时注册,模板中引用脚本路径在解析时完成路径替换
- skills 从插件包资源直接运行时注册,脚本路径在内存中改写,不需要临时目录或卸载清理
- 会话钩子提供工作流引导,告知可用命令和推荐流程
这样做的优势是隔离性强、无残留、升级即生效。
更详细的实现说明见 docs/zh/architecture.md。
npm installnpm test
npm run typecheck
npm run build其中:
npm test:运行 Vitestnpm run typecheck:执行 TypeScript 类型检查npm run build:编译到dist/
本项目的工作流设计受到 OpenSpec 启发。感谢 OpenSpec 提供清晰的规格驱动开发思路,让 opencode-spec 可以把这套流程更自然地接入 OpenCode。
README.en.md:English READMEdocs/zh/usage.md:中文使用指南docs/zh/reference.md:中文参考文档docs/zh/architecture.md:中文实现原理docs/zh/release.md:中文发布文档docs/en/usage.md:English usage guidedocs/en/reference.md:English referencedocs/en/architecture.md:English architecturedocs/en/release.md:English release guide