specleaf 1.1.2 → 1.2.0

package/README.md

@@ -23,6 +23,50 @@ npx specleaf ./openapi.yaml
 
 安装包已包含编译后的 CLI 和界面资源。用户安装与运行均不需要 Vite、React、TypeScript 或前端构建步骤，支持 `--ignore-scripts` 安装。
 
+已安装的用户可按安装方式升级到最新版本：
+
+```bash
+# 全局升级
+npm install -g specleaf@latest
+
+# 项目内升级（在项目目录执行）
+npm install -D specleaf@latest
+```
+
+## 安装 Agent skill
+
+SpecLeaf **1.2.0+** 随 npm 包提供同一份 `specleaf` skill，可安装给 Codex、Claude Code 和 OpenCode，让 Agent 按自然语言请求选择本地契约、生成或更新离线 HTML，并定位生成失败。
+
+```bash
+# 安装到当前目录，支持三个工具；也可用 npx specleaf install skill
+specleaf install skill
+
+# 只安装给指定工具；--agent 可重复，也可用逗号分隔
+specleaf install skill --agent codex
+specleaf install skill --agent claude,opencode
+
+# 安装到用户目录，供所有项目使用
+specleaf install skill --global
+
+# 更新已有且内容不同的 skill 文件，保留其他文件
+specleaf install skill --force
+specleaf install skill --help
+```
+
+默认安装范围为**调用目录**，可在目标项目根目录执行；不会自动切换到 Git 根目录。`--global` 使用当前用户的主目录：
+
+| 工具 | 项目安装 | 用户安装（`--global`） |
+| --- | --- | --- |
+| Codex | `.agents/skills/specleaf/` | `~/.agents/skills/specleaf/` |
+| Claude Code | `.claude/skills/specleaf/` | `~/.claude/skills/specleaf/` |
+| OpenCode | `.agents/skills/specleaf/` | `~/.agents/skills/specleaf/` |
+
+OpenCode 使用其支持的 `.agents/skills` 兼容目录，与 Codex 共用一份安装。目录约定见 [Codex 官方文档](https://learn.chatgpt.com/docs/build-skills#where-codex-loads-local-skills)、[Claude Code 官方文档](https://code.claude.com/docs/en/skills#choose-where-skills-load)、[OpenCode 官方文档](https://opencode.ai/docs/skills/#place-files)。
+
+安装直接复制包内 skill，无需联网，也不要求三个 Agent 工具已安装。重复安装时跳过内容相同的文件；已有文件内容不同时，先报告冲突且不写入任何目标，使用 `--force` 可更新随包提供的文件。额外文件会保留；安装路径中的符号链接及非预期文件类型会被拒绝。`specleaf.json` 记录安装时的 CLI 版本，供 Agent 在需要临时调用 npm 包时固定版本。通过 npx 首次获取 SpecLeaf 仍可能需要联网。
+
+安装后可在 Agent 中请求“把 docs/apis 下的接口契约生成为离线 HTML”。Codex 可通过 `$specleaf` 显式调用，Claude Code 可通过 `/specleaf` 调用；未发现新增 skill 时重新打开会话。skill 聚焦已有契约的生成、更新和错误诊断，生成时源契约只读。
+
 ## 生成单个 HTML
 
 以下命令用于已经安装的 CLI：
@@ -133,14 +177,14 @@ npm pack
 mkdir ../specleaf-consumer
 cd ../specleaf-consumer
 npm init -y
-npm install --omit=dev --ignore-scripts ../specleaf/specleaf-1.1.2.tgz
+npm install --omit=dev --ignore-scripts ../specleaf/specleaf-1.2.0.tgz
 npm exec -- specleaf ../specleaf/examples/minimal.json -o ./api.html
 npx specleaf --version
 ```
 
 把上面的 `../specleaf` 替换为实际源码目录。`npm run test:package` 自动在临时独立目录执行真实 `npm pack`、生产依赖安装、npm scripts、npm exec、npx 临时安装和临时全局安装，再验收文件保护、错误退出与特殊字符。验收后自动删除临时目录，不修改系统全局安装。
 
-`build:package` 只生成 `lib/cli.js` 和 `lib/assets/`；`files` 白名单仅分发这些产物、README、LICENSE 和 npm 必需的包元信息。公开接口为 `specleaf` CLI。
+`build:package` 只生成 `lib/cli.js` 和 `lib/assets/`；`files` 白名单分发这些产物、`skills/specleaf/`、README、LICENSE 和 npm 必需的包元信息。公开接口为 `specleaf` CLI，包含 HTML 生成及 `install skill` 子命令。
 
 ## 阅读功能
 
@@ -148,7 +192,8 @@ npx specleaf --version
 - 使用方法和路径生成稳定 Hash，支持复制、刷新、前进和后退。右侧页内目录随滚动高亮；提供空契约、无结果和无效链接状态。
 - 展示 Path / Query / Header / Cookie 参数、鉴权、响应状态码、响应头和扩展策略。操作参数覆盖同名同位置的路径参数。
 - 接口目录用彩色圆点展示接口状态，并提供中文状态说明；详情页展示对应的中文徽标。
-- 字段树保留递归引用、数组、空值、布尔 Schema、`allOf` / `oneOf` / `anyOf` 分支、必填及常用约束，最多展开 32 层。常用约束以简短中文展示，长度与数量范围合并；正则与原始 Schema 约束收在默认折叠的“详细校验规则”中，导出的契约保留完整规则。
+- 参数、请求体和响应的字段树统一合并展示 `allOf`：字段按首次出现的顺序排列，同名字段只显示一行，必填集合取并集，子属性和数组元素继续合并，非重复说明与校验约束均保留。可直接表达的结构显示为普通对象、数组或字段；依赖原分支作用域、存在冲突或无法安全归并的规则，使用中文说明并保留所有来源，收在默认折叠的“组合约束”中。
+- 字段树保留 `oneOf` / `anyOf` 备选分支、递归引用、数组、空值、布尔 Schema、必填及常用约束，沿各分支引用路径检测循环，最多展开 32 层。常用约束以简短中文展示，长度与数量范围合并；正则与原始 Schema 约束收在默认折叠的“详细校验规则”中。合并仅用于展示，原始示例、引用解析、CLI 接口和导出的契约结构保持原样。
 - 请求与响应可切换媒体类型和多个**原始示例**。JSON、纯文本和 YAML 按原始值展示，无示例时明确提示；不根据 Schema 编造数据。
 - 可复制接口路径、分享链接、示例和 cURL，导出合并后的 OpenAPI JSON。Clipboard API 不可用或拒绝访问时会尝试备用复制；仍失败则提供自动选中的文本供手动复制。
 
@@ -179,7 +224,7 @@ paths:
 
 当前 Operation 的标准字段 `deprecated: true` 优先显示“已弃用”，即使 `x-api-status` 是其他值，也只显示一个状态徽标。否则只识别表中的小写字符串；缺失、未知值、大小写不符或类型错误时均不显示状态标记。状态不从文档根级、路径或 tag 继承，也不映射其他工具的状态字段。
 
-“操作策略”以“接口状态”为标题，保留 `x-api-status` 原字段名和值。状态解析只用于展示，导出的合并契约保留原值，不自动补写 `deprecated`。`x-design-status` 仍表示设计状态，在操作策略中展示；文档根级的 `x-contract-status` 仍用于概览中的契约状态说明，两者均不作为接口状态来源。
+接口状态在详情页标题区域展示，“操作策略”不再重复展示 `x-api-status`。状态解析只用于展示，导出的合并契约保留原值，不自动补写 `deprecated`。`x-design-status` 仍表示设计状态，在操作策略中展示；文档根级的 `x-contract-status` 仍用于概览中的契约状态说明，两者均不作为接口状态来源。
 
 `examples/openapi.yaml` 演示五种状态，`examples/minimal.json` 演示未指定接口状态的契约。
 
@@ -222,12 +267,14 @@ build/serialize.ts       HTML JSON 数据块的安全序列化
 build/package.ts         预编译 ESM CLI、通用 IIFE、CSS 和图标
 build/generate.ts        读取包内资源、HTML 内嵌与原子写入
 build/cli.ts             specleaf 命令、帮助和版本
+build/skills.ts          skill 安装、目标目录选择及已有文件保护
 build/build.ts            默认生产构建
 src/lib/openapi.ts        引用、接口、Schema、示例和 cURL 处理
 src/lib/documentation.ts  模块集合类型、标题与模块路由
 src/components.tsx        字段树、参数表、Markdown、示例与复制
 src/App.tsx               目录、概览与接口详情
 examples/                 独立 YAML、JSON 和跨文件模型示例
+skills/specleaf/           随 npm 包分发的跨工具 skill
 tests/                    单元、命令及浏览器测试
 ```