From 42906f1383c016db5c2cb3cf4cc04d12c4c2eedb Mon Sep 17 00:00:00 2001 From: lanyuanxiaoyao Date: Sun, 7 Jun 2026 09:16:52 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E5=88=9D=E5=A7=8B=E5=8C=96=E9=A1=B9?= =?UTF-8?q?=E7=9B=AE=EF=BC=8C=E6=B7=BB=E5=8A=A0=20OpenSpec=20=E5=AD=90?= =?UTF-8?q?=E6=A8=A1=E5=9D=97=E5=92=8C=20fast-drive=20=E8=87=AA=E5=AE=9A?= =?UTF-8?q?=E4=B9=89=20schema?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitattributes | 32 +++ .gitignore | 412 +++++++++++++++++++++++++++++++++ .gitmodules | 3 + OpenSpec | 1 + README.md | 80 +++++++ fast-drive/schema.yaml | 150 ++++++++++++ fast-drive/templates/design.md | 77 ++++++ fast-drive/templates/tasks.md | 19 ++ 8 files changed, 774 insertions(+) create mode 100644 .gitattributes create mode 100644 .gitignore create mode 100644 .gitmodules create mode 160000 OpenSpec create mode 100644 README.md create mode 100644 fast-drive/schema.yaml create mode 100644 fast-drive/templates/design.md create mode 100644 fast-drive/templates/tasks.md diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..54ace9e --- /dev/null +++ b/.gitattributes @@ -0,0 +1,32 @@ +# 跨平台行尾规范 +# 所有文本文件统一用 LF（Unix 风格），避免 CRLF/LF 混用 +* text=auto eol=lf + +# 二进制文件不转换行尾 +*.png binary +*.jpg binary +*.jpeg binary +*.gif binary +*.ico binary +*.svg binary +*.pdf binary +*.zip binary +*.gz binary +*.tar binary +*.woff binary +*.woff2 binary +*.ttf binary +*.eot binary +*.mp4 binary +*.mov binary +*.mp3 binary + +# Shell 脚本必须 LF +*.sh text eol=lf + +# Windows 批处理必须 CRLF +*.bat text eol=crlf +*.cmd text eol=crlf + +# 锁定文件（如 package-lock.json）保持 LF +*.lock text eol=lf diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..8a58bfe --- /dev/null +++ b/.gitignore @@ -0,0 +1,412 @@ +### Git.gitignore ### +# Created by git for backups. To disable backups in Git: +# $ git config --global mergetool.keepBackup false +*.orig + +# Created by git when using merge tools for conflicts +*.BACKUP.* +*.BASE.* +*.LOCAL.* +*.REMOTE.* +*_BACKUP_*.txt +*_BASE_*.txt +*_LOCAL_*.txt +*_REMOTE_*.txt + +### Go.gitignore ### +# Binaries for programs and plugins +*.exe +*.exe~ +*.dll +*.so +*.dylib + +# Test binary, built with `go test -c` +*.test + +# Output of the go coverage tool, specifically when used with LiteIDE +*.out + +# Dependency directories (remove the comment below to include it) +# vendor/ + +### Go.patch ### +/vendor/ +/Godeps/ + +### JetBrains+all.gitignore ### +# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio, WebStorm and Rider +# Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839 + +# User-specific stuff +.idea/**/workspace.xml +.idea/**/tasks.xml +.idea/**/usage.statistics.xml +.idea/**/dictionaries +.idea/**/shelf + +# Generated files +.idea/**/contentModel.xml + +# Sensitive or high-churn files +.idea/**/dataSources/ +.idea/**/dataSources.ids +.idea/**/dataSources.local.xml +.idea/**/sqlDataSources.xml +.idea/**/dynamic.xml +.idea/**/uiDesigner.xml +.idea/**/dbnavigator.xml + +# Gradle +.idea/**/gradle.xml +.idea/**/libraries + +# Gradle and Maven with auto-import +# When using Gradle or Maven with auto-import, you should exclude module files, +# since they will be recreated, and may cause churn. Uncomment if using +# auto-import. +# .idea/artifacts +# .idea/compiler.xml +# .idea/jarRepositories.xml +# .idea/modules.xml +# .idea/*.iml +# .idea/modules +# *.iml +# *.ipr + +# CMake +cmake-build-*/ + +# Mongo Explorer plugin +.idea/**/mongoSettings.xml + +# File-based project format +*.iws + +# IntelliJ +out/ + +# mpeltonen/sbt-idea plugin +.idea_modules/ + +# JIRA plugin +atlassian-ide-plugin.xml + +# Cursive Clojure plugin +.idea/replstate.xml + +# Crashlytics plugin (for Android Studio and IntelliJ) +com_crashlytics_export_strings.xml +crashlytics.properties +crashlytics-build.properties +fabric.properties + +# Editor-based Rest Client +.idea/httpRequests + +# Android studio 3.1+ serialized cache file +.idea/caches/build_file_checksums.ser + +### JetBrains+all.patch ### +# Ignores the whole .idea folder and all .iml files +# See https://github.com/joeblau/gitignore.io/issues/186 and https://github.com/joeblau/gitignore.io/issues/360 + +.idea/ + +# Reason: https://github.com/joeblau/gitignore.io/issues/186#issuecomment-249601023 + +*.iml +modules.xml +.idea/misc.xml +*.ipr + +# Sonarlint plugin +.idea/sonarlint + +### Linux.gitignore ### +*~ + +# temporary files which can be created if a process still has a handle open of a deleted file +.fuse_hidden* + +# KDE directory preferences +.directory + +# Linux trash folder which might appear on any partition or disk +.Trash-* + +# .nfs files are created when an open file is removed but is still being accessed +.nfs* + +### Node.gitignore ### +# Logs +logs +*.log +npm-debug.log* +yarn-debug.log* +yarn-error.log* +lerna-debug.log* + +# Diagnostic reports (https://nodejs.org/api/report.html) +report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json + +# Runtime data +pids +*.pid +*.seed +*.pid.lock + +# Directory for instrumented libs generated by jscoverage/JSCover +lib-cov + +# Coverage directory used by tools like istanbul +coverage +*.lcov + +# nyc test coverage +.nyc_output + +# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files) +.grunt + +# Bower dependency directory (https://bower.io/) +bower_components + +# node-waf configuration +.lock-wscript + +# Compiled binary addons (https://nodejs.org/api/addons.html) +build/Release + +# Dependency directories +node_modules/ +jspm_packages/ + +# Test +playwright-report +test-results + +# TypeScript v1 declaration files +typings/ + +# TypeScript cache +*.tsbuildinfo + +# Optional npm cache directory +.npm + +# Optional eslint cache +.eslintcache + +# Microbundle cache +.rpt2_cache/ +.rts2_cache_cjs/ +.rts2_cache_es/ +.rts2_cache_umd/ + +# Optional REPL history +.node_repl_history + +# Output of 'npm pack' +*.tgz + +# Yarn Integrity file +.yarn-integrity + +# dotenv environment variables file +.env +.env.test + +# parcel-bundler cache (https://parceljs.org/) +.cache + +# Next.js build output +.next + +# Nuxt.js build / generate output +.nuxt +dist + +# Gatsby files +.cache/ +# Comment in the public line in if your project uses Gatsby and not Next.js +# https://nextjs.org/blog/next-9-1#public-directory-support +# public + +# vuepress build output +.vuepress/dist + +# Serverless directories +.serverless/ + +# FuseBox cache +.fusebox/ + +# DynamoDB Local files +.dynamodb/ + +# TernJS port file +.tern-port + +# Stores VSCode versions used for testing VSCode extensions +.vscode-test + +### VisualStudioCode.gitignore ### +.vscode/* +!.vscode/settings.json +!.vscode/tasks.json +!.vscode/launch.json +!.vscode/extensions.json +*.code-workspace + +### VisualStudioCode.patch ### +# Ignore all local history of files +.history + +### Windows.gitignore ### +# Windows thumbnail cache files +Thumbs.db +Thumbs.db:encryptable +ehthumbs.db +ehthumbs_vista.db + +# Dump file +*.stackdump + +# Folder config file +[Dd]esktop.ini + +# Recycle Bin used on file shares +$RECYCLE.BIN/ + +# Windows Installer files +*.cab +*.msi +*.msix +*.msm +*.msp + +# Windows shortcuts +*.lnk + +### macOS.gitignore ### +# General +.DS_Store +.AppleDouble +.LSOverride + +# Icon must end with two \r +Icon + +# Thumbnails +._* + +# Files that might appear in the root of a volume +.DocumentRevisions-V100 +.fseventsd +.Spotlight-V100 +.TemporaryItems +.Trashes +.VolumeIcon.icns +.com.apple.timemachine.donotpresent + +# Directories potentially created on remote AFP share +.AppleDB +.AppleDesktop +Network Trash Folder +Temporary Items +.apdisk + +### Python.gitignore ### +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +*.egg-info/ +.installed.cfg +*.egg + +# PyInstaller +*.manifest +*.spec + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.nox/ +.coverage +.coverage.* +nosetests.xml +coverage.xml +*.cover +*.py,cover +.hypothesis/ +.pytest_cache/ + +# Translations +*.mo +*.pot + +# Environments +.venv/ +venv/ +ENV/ +env/ +.python-version + +# Spyder project settings +.spyderproject +.spyproject + +# Rope project settings +.ropeproject + +# mkdocs documentation +/site + +# mypy +.mypy_cache/ + +# Pyre +.pyre/ + +# pytype +.pytype/ + +# Cython debug symbols +cython_debug/ + +# Custom +.opencode +.claude +.codex +.pi +.agents +.worktrees +temp + +# Bun +.build/ +*.bun-build diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..e0d3415 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "OpenSpec"] + path = OpenSpec + url = https://github.com/Fission-AI/OpenSpec.git diff --git a/OpenSpec b/OpenSpec new file mode 160000 index 0000000..1b06fdd --- /dev/null +++ b/OpenSpec @@ -0,0 +1 @@ +Subproject commit 1b06fddd59d8e592d5b5794a1970b22867e85b1f diff --git a/README.md b/README.md new file mode 100644 index 0000000..ffb5b61 --- /dev/null +++ b/README.md @@ -0,0 +1,80 @@ +# OpenSpec Schema + +当前项目用于开发 OpenSpec 工具的自定义 schema 流程。 + +## 项目结构 + +``` +openspec-schema/ +├── OpenSpec/ # OpenSpec 工具源码（Git 子模块） +├── fast-drive/ # 自定义 workflow schema +│ ├── schema.yaml # workflow 定义文件 +│ └── templates/ # artifact 模板 +│ ├── design.md # 设计文档模板 +│ └── tasks.md # 任务清单模板 +├── .gitignore +└── .gitattributes +``` + +## 关于 OpenSpec + +OpenSpec 是一款用于在 AI 编程工具中实践 SDD（Specification-Driven Development）开发流程的工具。工具源码位于 `OpenSpec` 目录下（以 Git 子模块形式引用）。 + +## fast-drive Schema + +`fast-drive` 是一个简化版的 OpenSpec workflow，采用 **design → tasks → apply** 的精简流程： + +### 特点 + +- **跳过 proposal 和 specs 阶段**：直接从 design.md 开始 +- **中文支持**：design.md 和 tasks.md 使用中文章节标题和正文 +- **自包含设计**：design.md 包含所有必要信息，即使跨会话也能继续执行 +- **结构化任务管理**：tasks.md 使用 checkbox 格式跟踪执行进度 + +### 工作流程 + +1. **design** - 创建 design.md，记录变更的背景、需求、决策和执行计划 +2. **tasks** - 从 design.md 派生可执行的任务清单 +3. **apply** - 按依赖顺序执行任务并标记完成 + +### 使用方法 + +在 OpenSpec 项目中使用 fast-drive workflow： + +```bash +# 初始化 OpenSpec 项目（如果尚未初始化） +openspec init + +# 使用 fast-drive workflow 创建新变更 +/opsx:propose "your-change-description" --schema fast-drive +``` + +## 开发说明 + +### 添加新的自定义 Schema + +1. 在项目根目录创建新的 schema 目录（如 `my-schema/`） +2. 创建 `schema.yaml` 定义 workflow 结构 +3. 在 `templates/` 目录下添加 artifact 模板 +4. 参考 `fast-drive/` 的结构和 OpenSpec 的 schema 规范 + +### 更新 OpenSpec 子模块 + +```bash +# 更新到最新版本 +git submodule update --remote OpenSpec + +# 或者进入子模块目录切换到特定版本 +cd OpenSpec +git checkout +cd .. +``` + +## 相关链接 + +- [OpenSpec 官方文档](https://github.com/Fission-AI/OpenSpec) +- [OpenSpec Schema 规范](https://github.com/Fission-AI/OpenSpec/tree/main/docs/customization.md) + +## License + +MIT diff --git a/fast-drive/schema.yaml b/fast-drive/schema.yaml new file mode 100644 index 0000000..9bf1f29 --- /dev/null +++ b/fast-drive/schema.yaml @@ -0,0 +1,150 @@ +name: fast-drive +version: 1 +description: 快速 OpenSpec workflow - design -> tasks -> apply +artifacts: + - id: design + generates: design.md + description: 自包含的方案说明和执行计划 + template: design.md + instruction: | + 创建 design.md，作为本次变更“改什么、为什么改、如何执行”的自包含事实来源。 + + 本 workflow 不使用 proposal 或 specs artifacts。design.md MUST 保留前序探索和用户讨论中的重要结论，确保后续 apply 阶段即使经历上下文压缩或进入新会话，也能正确继续执行。 + + 语言规则（强制）： + + - fast-drive 的 design.md 使用中文章节标题和中文正文；仅文件名、OpenSpec 术语、schema 字段名、命令、代码符号和必要技术名词保留英文 + + - 最终 design.md 不得残留英文模板句子或英文占位内容，除非该英文是 OpenSpec 术语、文件名、schema 字段名、代码符号、命令或必要技术名词 + + 面向看不到早期对话的人编写。简单变更保持精炼，但必须包含足够细节让执行无歧义。遇到以下情况时增加细节： + + - 跨多个系统、团队、工作流或 artifacts 的横切变更 + + - 新增依赖、集成、供应商、工具、策略或外部输入 + + - 重要的信息模型、流程模型、数据模型或归属关系变化 + + - 涉及安全、隐私、合规、性能、运维或迁移复杂度 + + - 执行前需要先做决策才能降低歧义 + + - 前序讨论已经确认非显而易见的需求、约束或被否决方案 + + 必需章节（建议使用以下中文章节标题）： + + - **背景**：问题、当前状态、相关参考资料，以及触发本次变更的用户请求 + + - **讨论记录**：探索或前序讨论中必须保留的关键点，包括已确认结论、用户偏好、约束和重要的被否决方案 + + - **需求**：预期结果、行为/流程/接口/内容变化、连续性要求和验收标准 + + - **目标 / 非目标**：本次变更要达成的目标，以及明确不在范围内的内容 + + - **执行约束**：必须遵守的约束、禁止的做法、需保持的行为/流程、依赖限制，以及项目或 workflow 特有边界 + + - **影响范围**：与本次变更相关的具体 artifacts、参考资料、相关方、系统、工作流、文档、配置、资产或交接事项 + + - **决策**：关键选择及理由（为什么选 X 而不是 Y）。每个重要决策都要包含考虑过的替代方案，以及未选择它们的原因 + + - **执行计划**：主要工作流或待修改 artifacts、集成或交接点、执行顺序，以及必要的发布/落地说明 + + - **验证计划**：用于证明变更完成所需的验证检查、审查、批准、验收检查、文档检查、沟通检查和人工检查 + + - **风险 / 权衡**：已知限制和可能出错的事项 + 格式：[风险] -> 缓解措施 + + - **待解决问题**：执行前仍需解决的决策、假设或未知项。必须区分会阻塞 apply 的问题和非阻塞后续问题。没有未决问题时使用“无” + + 可选章节（相关时添加，建议使用中文章节标题）： + + - **迁移 / 发布计划**：发布步骤、沟通安排、归属、回滚或连续性策略 + + 聚焦保留需求、理由、约束和方案。除非某个细节是讨论中明确做出的决策，否则避免逐行或逐步骤展开。 + + 优先写可长期使用的摘要，而不是聊天记录转写。当具体 artifact 名称、数据/信息形状、示例、相关方、归属和边界场景会影响执行时，必须写清楚。 + + 不要在 design.md 使用任务 checkbox；checkbox 只属于 tasks.md。 + + 最终 design.md 不得包含未解决的模板注释、空表格行或占位文本。 + + 如果信息缺失，写明假设和待解决问题，不要编造隐藏需求。不要依赖未写入文档的聊天上下文。 + requires: [] + - id: tasks + generates: tasks.md + description: 从 design.md 派生的可跟踪执行清单 + template: tasks.md + instruction: | + 创建 tasks.md，将 design.md 拆解为可执行工作项。 + + **重要：必须遵守以下模板中的 checkbox 行格式。** apply 阶段会解析 checkbox 格式跟踪进度。未使用 `- [ ]` 的任务不会被跟踪。 + + 语言规则（强制）： + + - fast-drive 的 tasks.md 使用中文分组标题和中文任务描述；仅文件名、OpenSpec 术语、schema 字段名、命令、代码符号和必要技术名词保留英文 + + - 每个可跟踪任务必须保留 OpenSpec CLI 可解析的单行 checkbox 格式，例如 `- [ ] 1.1 任务描述` 或 `- [x] 1.1 已完成任务描述` + + - 最终 tasks.md 不得残留英文模板任务或英文占位内容，除非该英文是 OpenSpec 术语、文件名、schema 字段名、代码符号、命令或必要技术名词 + + 编写规则： + + - 任务必须从 design.md 派生。不要依赖 proposal.md 或 specs artifacts；任何相关前序讨论都必须已经记录在 design.md 中 + + - 相关任务按 `##` 编号标题分组，分组标题使用中文 + + - 每个任务 MUST 是单行 checkbox：`- [ ] X.Y 任务描述` + + - 任务粒度应足够小，能在一个会话内完成 + + - 按依赖顺序排序（先做必须先完成的事项） + + - 当执行依赖执行约束、影响范围或待解决问题时，从上下文审查任务开始 + + - 需要时包含验证任务，覆盖检查、审查、批准、验收、文档、沟通和人工检查 + + - 除非仓库、版本控制或发布操作明确属于本次变更范围，否则不要包含这类任务 + + - 最终 tasks.md 不得包含未解决的模板注释、空表格行或占位任务文本 + + 示例： + + ``` + ## 1. 上下文审查 + + - [ ] 1.1 阅读 design.md，识别范围、需求、决策、执行约束和待解决问题 + - [ ] 1.2 审查“影响范围”中列出的相关 artifacts 和参考资料 + + ## 2. 执行 + + - [ ] 2.1 执行 design.md 中的第一个具体工作项 + - [ ] 2.2 执行 design.md 中的下一个具体工作项 + + ## 3. 验证 + + - [ ] 3.1 执行“验证计划”中要求的验证 + - [ ] 3.2 执行项目或 workflow 要求的质量检查 + - [ ] 3.3 执行“验证计划”中要求的人工审查或验收检查 + + ## 4. 文档 / 沟通 + + - [ ] 4.1 如果行为、流程、接口、配置或使用方式发生变化，更新相关文档、runbook、沟通材料或项目参考资料 + ``` + + 以 design.md 中的范围、需求、决策、执行方向和验证预期为依据。 + + 每个任务都应可验证：必须能明确判断任务何时完成。 + requires: + - design +apply: + requires: + - design + - tasks + tracks: tasks.md + instruction: | + 先阅读 design.md，再阅读 tasks.md。 + 同时遵守 workflow context/configuration，例如存在时读取 openspec/config.yaml，以及 design.md 引用的相关项目或 workflow 文档。 + 将 design.md 视为范围、需求、决策、执行约束、执行方向和验证预期的事实来源。 + 按依赖顺序处理待办任务，并在完成后及时标记。 + 只有任务执行完成且必要验证完成后，才能标记任务完成。 + 如果 tasks 与 design.md 冲突、design.md 存在阻塞性待解决问题，或需要澄清，必须暂停。 diff --git a/fast-drive/templates/design.md b/fast-drive/templates/design.md new file mode 100644 index 0000000..34647c2 --- /dev/null +++ b/fast-drive/templates/design.md @@ -0,0 +1,77 @@ +## 背景 + + + +## 讨论记录 + + + +- 已确认结论： +- 用户偏好： +- 约束： +- 被否决方案： + +## 需求 + + + +| 需求 | 验收标准 | +| ---- | -------- | +| | | + +## 目标 / 非目标 + +**目标：** + + +**非目标：** + + +## 执行约束 + + + +- 依赖限制： +- 约束： +- 质量门禁： +- 相关方： +- 文档 / 沟通： +- 兼容性 / 连续性： + +## 影响范围 + + + +| 范围 | Artifacts / 参考资料 | 预期变更 | 备注 | +| ---- | -------------------- | -------- | ---- | +| | | | | + +## 决策 + + + +| 决策 | 理由 | 已否决替代方案 | +| ---- | ---- | ---------------- | +| | | | + +## 执行计划 + + + +## 验证计划 + + + +| 需求 / 风险 | 验证方式 | +| ----------- | -------- | +| | | + +## 风险 / 权衡 + + + +## 待解决问题 + +| 状态 | 问题 | 所需决策 | +| ---- | ---- | -------- | +| 无 | 无待解决问题。 | 无需决策 | diff --git a/fast-drive/templates/tasks.md b/fast-drive/templates/tasks.md new file mode 100644 index 0000000..465c63e --- /dev/null +++ b/fast-drive/templates/tasks.md @@ -0,0 +1,19 @@ +## 1. 上下文审查 + +- [ ] 1.1 阅读 design.md，识别范围、需求、决策、执行约束和待解决问题 +- [ ] 1.2 审查“影响范围”中列出的相关 artifacts 和参考资料 + +## 2. 执行 + +- [ ] 2.1 执行 design.md 中的第一个具体工作项 +- [ ] 2.2 执行 design.md 中的下一个具体工作项 + +## 3. 验证 + +- [ ] 3.1 执行“验证计划”中要求的验证 +- [ ] 3.2 执行项目或 workflow 要求的质量检查 +- [ ] 3.3 执行“验证计划”中要求的人工审查或验收检查 + +## 4. 文档 / 沟通 + +- [ ] 4.1 如果行为、流程、接口、配置或使用方式发生变化，更新相关文档、runbook、沟通材料或项目参考资料