@niujiajie/freespec 1.15.1 → 1.16.0

package/README.md

@@ -1,59 +1,204 @@
 # FreeSpec
 
-AI 原生的规格驱动开发（spec-driven development）命令行工具（[@niujiajie/freespec](https://gitee.com/niu_jiajie/openspec.git)）。核心思路：先在 `freespec/` 目录下为每次变更写规格文档（需求、设计、任务清单、用例），再由 AI 编码工具按文档实现，文档与实现互相约束。
+> 自由的规范。给 AI 编码用的一套中文技能，包名是 [@niujiajie/freespec](https://www.npmjs.com/package/@niujiajie/freespec)。
 
-## 工作流
+---
 
-- 变更目录在 `freespec/<名称>变更/`，默认 schema 是 `默认`。
-- `默认` schema（见 [schema.yaml](schemas/默认/schema.yaml)）定义四份可选的中文文档，无先后依赖，可单独写：
-  - `需求文档.md` —— 给人看的需求说明；
-  - `设计文档.md` —— 按章写的设计说明，由 `scripts/check-design.mjs` 校验；
-  - `任务清单.md` —— 可勾选（`- [ ]` / `- [x]`）的执行清单；
-  - `测试用例.md` —— 输入、操作、期望三段式用例，不写具体语言的测试代码。
-- 每份文档都有配套模板（[schemas/默认/templates/](schemas/默认/templates/)）和给 AI 的写作指令。
-- `apply` 阶段：以已有文档为上下文实现代码，有用例时先落成失败的测试再写实现。
+## 📘 一、什么是 FreeSpec
 
-## 命令
+FreeSpec 是一套给 AI 编码用的中文技能，意思是「自由的规范」。它从 OpenSpec 长出来。一次改动先想清楚，写进 `freespec/` 下面的变更目录，再按你在对话里输入的技能往下做。
 
-终端里的全局 `freespec` 若是旧版本，请统一用本仓库编出来的命令：
+OpenSpec 要求提案、规范、设计、任务按先后顺序做完，后一步要等前一步。做完还要把这次写下的规范合并回原来的总规格，再把这次变更归档，表示已经结束。
 
-```powershell
-node bin/freespec.js init --tools cursor --profile core --no-animation
-node bin/freespec.js new change 登录改造
+FreeSpec 不再把这几份文档绑成必须按顺序做完的一条链。规范和归档实际用不上，也不会让 AI 更聪明，就拿掉了。
+
+**为什么做 FreeSpec？** 理由如下：
+
+### 1. 💬 中文友好
+
+技能、目录、文档都用中文。对话里打 `/freespec-深思`，目录是 `freespec/登录改造变更/`，中文名字看一眼就知道这一步在干什么，比OpenSpec那一套英文命令、英文技能更方便理解。
+
+### 2. 🛠️ 每个技能都按实际开发增强过
+
+每个技能都加了更贴日常开发的约束和能力。例如深思要把提到的页面、数据库表、接口和仓库里的实际代码对一遍，对不上就要问用户，AI 不会擅自决定。答案写进变更目录的 `深思/`。这次对话断了以后，换一个新对话把这份记录读进去，还能接着上次的问题继续。
+
+需求、设计、任务、用例都按固定的章节来写，写得更全。另外新增了文档审查和代码审查，用来检查 AI 写下的文档和代码。
+
+### 3. 🧩 技能调用更灵活
+
+十个技能是一套工具，想用哪件用哪件。如果问题还不明朗，可以先深思把需求想清楚。
+
+如果想把需求进一步理顺、理清楚，可以写需求、设计、用例文档，如果觉得任务比较大，可以拆分任务，这样AI按任务顺序一步一步做下去，避免有遗漏。
+
+如果想直接动手，深思想完就可以写Java程序。总之按推荐顺序走一遍可以，中间抽几步来用也可以，整套流程既适用复杂业务又可以实现简单业务。
+
+### 4. 🧪 开发前先写用例
+
+这里借了测试驱动开发的做法：先写用例，再写实现。`测试用例.md` 只描述输入、操作、期望，不写某种语言的测试代码。
+
+轮到写 Java 时，先把这些用例写成现在运行会失败的测试，再写实现，直到测试通过。没有用例也可以直接写。有用例的话，就按用例里写明的期望来写。
+
+### 5. 🔌 语言可以继续加
+
+现在已经做好的是写 Java、审 Java。技能按语言分开。需求、设计、任务、用例不跟某一种语言绑在一起。
+
+如果后面要写 C++、写 Python，按同样的样子再加一对技能就行。这样每一种语言可以分开来管。
+
+---
+
+## 🗂️ 二、技能介绍
+
+十个技能全部用中文命名。它们和 OpenSpec 的对照、每个技能自己的作用，见下面两张表。
+
+### 1. 🔀 新技能变化
+
+| OpenSpec 技能 | FreeSpec 技能 | 改了什么 |
+| --- | --- | --- |
+| `/opsx:new` | `/freespec-新建` | 只新建本次变更的目录结构，后续的需求、设计都在这个目录下写清楚 |
+| `/opsx:propose` | `/freespec-需求` | 按固定模板生成 `需求文档.md`，更贴合用户的阅读习惯 |
+| `/opsx:explore` | `/freespec-深思` | OpenSpec 只在对话里想清楚，聊完就丢；<br>FreeSpec 把答案写进 `深思/记录.md`，换了会话还能接着之前的问题继续 |
+| `design.md` | `/freespec-设计` | 按固定模板生成 `设计文档.md`，新增原型图、流程图等图表来呈现本次变更要改动的内容，更贴合用户的阅读习惯；<br>模板从数据库表写到接口设计，该有的章节都有，比 OpenSpec 更细致 |
+| `tasks.md` | `/freespec-任务` | 把要做的事拆成一条条任务，让 AI 按任务清单逐步完成，避免遗漏 |
+| 无 | `/freespec-用例` | 新增。<br>先想清楚每个功能点要验证什么，不用等到写任务和写代码时再猜；<br>写代码之前先写清输入、操作、期望。这是先写测试、再写实现的做法，让写出来的结果更符合你的预期 |
+| 无 | `/freespec-审文档` | 新增。<br>从写完文档到开始写代码之间，多做一次只看、不改的检查。写 Java 之前，先看几份文档有没有互相矛盾的地方 |
+| `/opsx:apply` | `/freespec-写Java` | 更贴合 Java 开发的实际，引入 Java 程序员常用的编码习惯和风格，避开常见的代码错误 |
+| 无 | `/freespec-审Java` | 新增。<br>写完 Java 后再审一次，检查代码习惯、写法和常见错误，避免代码越写越臃肿 |
+| `/opsx:verify` | `/freespec-验收` | 对照已经存在的任务清单或者商量好的内容和代码，核验有没有漏掉的任务，避免丢功能 |
+| `/opsx:sync` | 无 | 丢掉。<br>做完不用再把这次新增的规范合并回原来的总规格。这些规范下次用不上，也不会让 AI 更聪明 |
+| `/opsx:archive` `/opsx:bulk-archive` | 无 | 丢掉。<br>归档的规范数据下次同样用不上，做完目录留在原地就能查 |
+| `/opsx:continue` `/opsx:ff` | 无 | 丢掉必须按顺序往下做的要求。<br>不再要求前一份文档没写完就不能做下一步。你点哪个技能，就做哪一件事 |
+| `/opsx:update` `/opsx:onboard` | 无 | 丢掉。<br>文档要改，重新做对应的那一步就行；<br>怎么开始用，直接写在这份 README 里 |
+
+### 2. 🎯 FreeSpec 技能作用
+
+| 技能名称 | 技能指令 | 作用 | 亮点特性 |
+| --- | --- | --- | --- |
+| 📁 新建 | `/freespec-新建` | 只创建 `freespec/<名称>变更/` 目录，先把这次变更的文件夹建好。<br>后面的需求、设计、任务、用例都写在这个目录里，所以这一步只建目录，文档留给后面的技能再写。 | 1. 目录已经存在时，会先问你怎么处理。<br>2. 名称里没有「变更」时会自动补上，所以 `登录改造` 和 `登录改造变更` 会进入同一个目录。<br>3. 做完只告诉你目录在哪，下一步用哪个技能由你来选。 |
+| 💭 深思 | `/freespec-深思` | 开工前，把没说清楚的、说漏的、以及和仓库里现有代码对不上的地方补上。<br>因为后面的文档和代码都会按这里的答案往下写，所以先问清楚，避免凭猜测去写。 | 1. 把提到的页面、数据库表、接口，和仓库里的实际代码对一遍。对不上的地方，每一处单独问一个问题。<br>2. 如果某个问题的答案会改掉已经写下的结论，就做成选择题，一次一起问完。<br>3. 答案写进 `深思/记录.md`。这次对话断了以后，换一个新对话把这份记录读进去，还能接着上次的问题继续。 |
+| 📋 需求 | `/freespec-需求` | 按固定模板写 `需求文档.md`。<br>它既要让人单独看懂这次要做什么，又给后面的设计、任务、用例一份可以照着写的依据。 | 1. 四个标题是固定的：需求背景、需求描述、需求功能点拆分、需求待定。读的人知道每一段在讲什么。<br>2. 每条功能点用动词开头，一条只写一件事。后面写任务和用例时，可以按功能点逐条对应。<br>3. 写完要跑脚本做检查。检查不通过，就不能结束这一步。 |
+| 📐 设计 | `/freespec-设计` | 写 `设计文档.md`，把这次要怎么改写清楚。<br>后面的任务清单和写 Java 会按这些章节来做，所以写进文档的章节要能直接变成一条条任务。 | 1. 先判断这次改动涉及前端、后端、数据里的哪几块。只有这次用到的章节才写进文档。<br>2. 没有需求文档也能写。这时按对话里已经说清楚的内容来写。<br>3. 改动清单里写到的页面、数据库表、接口，要先写清它们各自对应仓库里的哪一处。这些对应关系写完，才能写后面的章节。 |
+| ☑️ 任务 | `/freespec-任务` | 写可以打勾的 `任务清单.md`，把要做的事拆成一条条任务，每条做完就能在前面打勾。<br>写 Java 时从第一条还没打勾的任务做起，一次做一条，所以拆细了才不会漏掉某件事。 | 1. 一条任务只写一件能做完的事：一个接口连同它背后的服务、一张数据库表，或一个页面。不要写「实现某模块」这种看不出具体做什么的句子。<br>2. 没有需求文档或设计文档也能写。这时按对话里已经说清楚的内容来拆成任务。 |
+| 🧪 用例 | `/freespec-用例` | 写 `测试用例.md`，先写清每件事的输入是什么、要做什么、期望看到什么。<br>写 Java 时，会先把这些用例写成现在运行会失败的测试，再写实现。这样写出来的代码，就按这些期望来验证。 | 1. 一种行为写一条用例，每条只写输入、操作、期望。<br>2. 涉及接口时，正常情况、业务上不允许、参数不合法，这三种分开写。<br>3. 先列一张对照表，写明每个功能点对应哪几条用例，看有没有功能点还没写到。 |
+| 🔎 审文档 | `/freespec-审文档` | 只看、不改，评审已经写好的需求、设计、任务、用例。<br>因为后面写代码会按这些文档来写，所以写代码之前先看这几份之间有没有互相矛盾。这一步只给出意见，不改文件。 | 1. 从七个方面给结论：是否合理、有没有写全、几份之间是否一致、是否好懂、能不能据此写测试、每条内容能不能找到依据、以后改起来方不方便。<br>2. 哪份文件还没有，就写出它的名字。缺了文件只说明缺了，不因此把这次评审判成不通过。 |
+| ☕ 写Java | `/freespec-写Java` | 把文档或对话里已经说清楚的事写成 Java 代码。<br>有测试用例时，先写成 Java 测试并运行。功能还没写，这次运行应当失败；看到失败后再写实现，直到测试通过。<br>有任务清单时，一次只做最前面那条还没打勾的。 | 1. 功能还没写时，测试应当失败。要先运行并看到这次失败，才开始写实现。看到失败，说明测试确实在检查这件事。如果测试一开始就通过，就停下来问，不接着写实现。<br>2. 有任务清单时，一次只做最前面一条还没打勾的。做完把 `- [ ]` 改成 `- [x]`。<br>3. 某个方法只有名字、没有步骤时，停下来问你，不自己编出一套做法。 |
+| 🛡️ 审Java | `/freespec-审Java` | 只看、不改，评审这次的 Java 改动，和写 Java 分成两次做。<br>写完马上自己审，容易把刚写下的问题当成没问题，所以这一步只给结论，不改代码。 | 1. 改动里出现 SQL、事务、循环或并发时，再多查这一类特有的问题。例如 SQL 会不会误改整张表，事务失败后能不能回滚，循环里会不会一次次查库，并发时会不会几处同时改同一份数据。<br>2. 只评审，不改代码。结论只写三种：通过、有条件通过、不通过。 |
+| ✅ 验收 | `/freespec-验收` | 对照已经有的需求、设计、任务、用例、测试和代码，看这件事做完没有。<br>结论既给写代码的人看，也让不写代码的人能看懂。 | 1. 任务前面打了勾，但代码里找不到对应的改动，不算做完。<br>2. 哪份文件还没有，就写出它的名字。缺了文件不算这次验收失败，缺的那一部分也不算已经做完。 |
+
+### 3. 📏 各技能共用的约束
+
+- ✍️ 写进文档的内容和对话都用简体中文，用平常的说法来写。先写结论，再写原因。
+- 🚫 不要用只有自己懂的词，不要自造简称，也不要把一句话压成几个词。每句要写清是谁、做什么，读者不看后文也能懂。这些词不要用：优化、提升、赋能、闭环、拉通、完善、大概、可能、后续再看。
+- 📌 必须做到的要求写在该技能的 `护栏.md` 里。做到哪一步，就检查这一步，不用回头把整份清单再翻一遍。尽量做到的要求写在 `约束.md` 里。做不到时，在对话里说明。
+- 🏁 每一步结束时都要说清三件事：写到了哪个文件，还有什么没定或没做，请你看过之后再决定下一步。
+
+---
+
+## 🗺️ 三、推荐的使用顺序
+
+技能不会自动接着跑下一个。下面四种是常用用法，每一步都要你自己在对话里输入。
+
+### 1. ⚡ 想清楚之后直接写代码
+
+问题已经想清楚了。文档可以以后再补，也可以这次不写。
+
+```text
+/freespec-深思
+  → /freespec-写Java
+  → /freespec-审Java
+  → /freespec-验收
+```
+
+如果这次变更的文件夹还不存在，深思会自己建好。写 Java 时如果还没有任务清单和测试用例，就按对话里已经说清楚的内容来写，并写明哪些前提只在对话里定过、文档里还没有。
+
+### 2. 🧭 从深思一直做到验收
+
+这次要留下需求文档、设计文档、任务清单和测试用例，然后再写代码。
+
+```text
+/freespec-深思
+  → /freespec-需求
+  → /freespec-设计
+  → /freespec-任务
+  → /freespec-用例
+  → /freespec-审文档
+  → /freespec-写Java
+  → /freespec-审Java
+  → /freespec-验收
 ```
 
-已有项目在项目目录里执行 `node bin/freespec.js update` 更新指令文件。装完后重启 Cursor，入口是 `/freespec-新建` 等斜杠命令（技能见 [skill-files/](skill-files/)：新建、需求、设计、任务、用例、写Java、审Java、审文档、深思、验收）。
+审文档放在写 Java 之前，用来看这几份文档之间有没有互相矛盾。审 Java 和验收都只看、不改文件。写完代码后，想检查代码就输入审 Java；想核对这件事做完没有，再输入验收。
 
-| 命令 | 说明 |
-| --- | --- |
-| `init [path]` | 初始化项目，为指定 AI 工具生成指令文件和技能 |
-| `update [path]` | 更新已生成文件，支持 `--dry-run` / `--json` |
-| `new change <name>` | 新建变更目录，支持 `--schema`、`--json` |
-| `list` | 列出 `freespec/` 下的变更目录，支持 `--sort` / `--json` |
-| `status` | 查看变更产物完成度，支持 `--change`、`--all`、`--json` |
-| `instructions [artifact]` | 输出某产物或 `apply` 的增强指令 |
+### 3. 📝 这一次只写文档
 
-## 支持的 AI 工具
+这一次不写代码。
+
+```text
+/freespec-新建
+  → /freespec-深思
+  → /freespec-需求
+  → /freespec-设计
+  → /freespec-任务
+  → /freespec-用例
+  → /freespec-审文档
+```
 
-`--tools` 可选 `all`、`none` 或逗号分隔列表，覆盖 50+ 工具（定义在 [config.ts](src/core/config.ts)），包括 Cursor、Claude Code、Codex、Gemini CLI、GitHub Copilot、Trae、Qwen Code、OpenCode 等，以及通用的 `.agents` 共享技能目录。
+新建这一步可以不做。深思、需求、设计、任务、用例发现文件夹还不存在时，都会先把文件夹建好。
 
-## 目录结构
+### 4. 💻 文档已经有了，只写代码
 
+```text
+/freespec-写Java
+  → /freespec-审Java
+  → /freespec-验收
 ```
-bin/            CLI 入口（freespec.js）
-src/cli/        Commander 命令定义
-src/commands/   命令实现（workflow：new-change、status、instructions）
-src/core/       核心逻辑（init、update、change-layout、profiles、config 等）
-schemas/        工作流 schema 与文档模板（默认 schema：默认）
-skill-files/    生成到各 AI 工具的技能源文件
-scripts/        构建与校验脚本
-dist/           构建产物（tsc 输出）
+
+有测试用例时，写 Java 会先把用例写成 Java 测试并运行。功能还没写，这次运行应当失败；看到失败后再写实现。有任务清单时，一次只做最前面一条还没打勾的，做完就在前面打勾。
+
+> 上面每一步都可以单独使用。只做深思，或只审文档，都可以。
+
+---
+
+## 📦 四、怎么安装
+
+### 1. ⬇️ 安装命令
+
+需要 Node.js 20.19 或更高版本。
+
+```bash
+npm install -g @niujiajie/freespec
 ```
 
-## 开发
+装完执行下面这句，能打出版本号即可：
+
+```bash
+freespec --version
+```
+
+### 2. 📂 在项目里初始化
+
+进入要让 AI 改代码的项目目录，执行：
+
+```bash
+freespec init --tools cursor
+```
+
+`--tools` 换成你实际用的工具。Cursor 写 `cursor`，Claude Code 写 `claude`，Codex 写 `codex`。多个用逗号隔开，全部装上写 `all`。默认会装上全部十个技能。
+
+这个项目以前装过 FreeSpec 时，改用：
+
+```bash
+freespec update
+```
+
+### 3. 🔄 重启 Cursor
+
+> 装完后重启 Cursor。以 `/` 开头的技能命令是编辑器启动时加载的，不重启就不会出现。
+
+### 4. ▶️ 开始用
+
+在 Cursor 对话里输入技能名，例如：
 
-- Node.js >= 20.19，pnpm 包管理，ESM + TypeScript。
-- `pnpm build`：清理 `dist/` 并用本地 tsc 编译（[build.js](build.js)）。
-- `pnpm dev`：tsc watch；`pnpm dev:cli`：构建后直接跑本地 CLI。
-- `pnpm lint`：ESLint 检查 `src/`。
-- 命令实现全部按需 `import()` 懒加载（见 [cli/index.ts](src/cli/index.ts)），`--version`、`--help` 不加载其他命令的实现，启动零开销。
+- `/freespec-新建`
+- `/freespec-深思`
+- `/freespec-需求`
+- `/freespec-写Java`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@niujiajie/freespec",
-  "version": "1.15.1",
+  "version": "1.16.0",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "freespec",
@@ -17,7 +17,6 @@
   "license": "MIT",
   "author": "FreeSpec Contributors",
   "type": "module",
-  "packageManager": "pnpm@10.34.5",
   "publishConfig": {
     "access": "public"
   },
@@ -39,16 +38,6 @@
     "!dist/**/__tests__",
     "!dist/**/*.map"
   ],
-  "scripts": {
-    "lint": "eslint src/",
-    "build": "node build.js",
-    "generate:skills": "node scripts/generate-skillssh.mjs",
-    "dev": "tsc --watch",
-    "dev:cli": "pnpm build && node bin/freespec.js",
-    "prepare": "node build.js",
-    "prepublishOnly": "pnpm run build",
-    "check:pack-version": "node scripts/pack-version-check.mjs"
-  },
   "engines": {
     "node": ">=20.19.0"
   },
@@ -72,5 +61,13 @@
     "tinyglobby": "^0.2.17",
     "yaml": "^2.8.3",
     "zod": "^4.4.3"
+  },
+  "scripts": {
+    "lint": "eslint src/",
+    "build": "node build.js",
+    "generate:skills": "node scripts/generate-skillssh.mjs",
+    "dev": "tsc --watch",
+    "dev:cli": "pnpm build && node bin/freespec.js",
+    "check:pack-version": "node scripts/pack-version-check.mjs"
   }
-}
+}