apiskill 0.1.1 → 0.1.3

package/MCP.md

@@ -2,11 +2,11 @@
 
 The detailed MCP documentation has moved to standalone docs:
 
-- [English MCP documentation](docs/mcp.md)
-- [中文 MCP 文档](docs/mcp.zh.md)
+- [English MCP documentation](https://unpkg.com/apiskill@latest/docs/mcp.md)
+- [中文 MCP 文档](https://unpkg.com/apiskill@latest/docs/mcp.zh.md)
 
 Project overview:
 
-- [README](README.md)
-- [Web app docs](docs/web.md) / [Web 中文文档](docs/web.zh.md)
-- [CLI docs](docs/cli.md) / [CLI 中文文档](docs/cli.zh.md)
+- [README](https://unpkg.com/apiskill@latest/README.md)
+- [Web app docs](https://unpkg.com/apiskill@latest/docs/web.md) / [Web 中文文档](https://unpkg.com/apiskill@latest/docs/web.zh.md)
+- [CLI docs](https://unpkg.com/apiskill@latest/docs/cli.md) / [CLI 中文文档](https://unpkg.com/apiskill@latest/docs/cli.zh.md)

package/README.ja.md

@@ -1,12 +1,12 @@
 # API Skill
 
-[English](README.md) / [中文](README.zh.md) / [한국어](README.ko.md) / [日本語](README.ja.md)
+[English](https://unpkg.com/apiskill@latest/README.md) / [中文](https://unpkg.com/apiskill@latest/README.zh.md) / [한국어](https://unpkg.com/apiskill@latest/README.ko.md) / [日本語](https://unpkg.com/apiskill@latest/README.ja.md)
 
-API Skill は、フロントエンド開発と AI 支援開発のためのローカル OpenAPI/Swagger ワークスペースです。3 つの入口が同じキャッシュ済み API ドキュメントを共有します。
+API Skill は、フロントエンド開発と AI 支援開発のためのローカル OpenAPI/Swagger ワークスペースです。人向けの Web ワークスペースと AI Agent 向けの CLI/MCP インターフェースが、同じキャッシュ済み API ドキュメントを共有します。
 
-- Web アプリ: API ドキュメントのインポート、閲覧、検索、確認、テスト、手動 API 操作の管理。
-- CLI: ターミナルからドキュメントをインポートし、ローカル API バージョンを管理または照会。
-- MCP サーバー: 同じ API コンテキストと保守操作を Codex や他の MCP クライアントへ公開。
+- Web アプリ: 人が API ドキュメントをインポート、閲覧、検索、確認、テストし、バージョンと API 操作を管理するための画面。
+- CLI: AI Agent や自動化処理がドキュメント状態を確認し、必要な API コンテキストを取得・保守するためのコマンド。
+- MCP サーバー: 同じ API の照会・保守機能を Codex や他の AI Agent クライアントへ公開。
 
 ## Web アプリの使い方
 
@@ -92,9 +92,9 @@ Agent ワークフローでは MCP が最も効果的です。コーディング
 
 ## ドキュメント
 
-- Web アプリ: [English](docs/web.md) / [中文](docs/web.zh.md) / [한국어](docs/web.ko.md) / [日本語](docs/web.ja.md)
-- CLI 設定と使い方: [English](docs/cli.md) / [中文](docs/cli.zh.md) / [한국어](docs/cli.ko.md) / [日本語](docs/cli.ja.md)
-- MCP 設定と使い方: [English](docs/mcp.md) / [中文](docs/mcp.zh.md) / [한국어](docs/mcp.ko.md) / [日本語](docs/mcp.ja.md)
+- Web アプリ: [English](https://unpkg.com/apiskill@latest/docs/web.md) / [中文](https://unpkg.com/apiskill@latest/docs/web.zh.md) / [한국어](https://unpkg.com/apiskill@latest/docs/web.ko.md) / [日本語](https://unpkg.com/apiskill@latest/docs/web.ja.md)
+- CLI 設定と使い方: [English](https://unpkg.com/apiskill@latest/docs/cli.md) / [中文](https://unpkg.com/apiskill@latest/docs/cli.zh.md) / [한국어](https://unpkg.com/apiskill@latest/docs/cli.ko.md) / [日本語](https://unpkg.com/apiskill@latest/docs/cli.ja.md)
+- MCP 設定と使い方: [English](https://unpkg.com/apiskill@latest/docs/mcp.md) / [中文](https://unpkg.com/apiskill@latest/docs/mcp.zh.md) / [한국어](https://unpkg.com/apiskill@latest/docs/mcp.ko.md) / [日本語](https://unpkg.com/apiskill@latest/docs/mcp.ja.md)
 
 ## データモデル
 

package/README.ko.md

@@ -1,12 +1,12 @@
 # API Skill
 
-[English](README.md) / [中文](README.zh.md) / [한국어](README.ko.md) / [日本語](README.ja.md)
+[English](https://unpkg.com/apiskill@latest/README.md) / [中文](https://unpkg.com/apiskill@latest/README.zh.md) / [한국어](https://unpkg.com/apiskill@latest/README.ko.md) / [日本語](https://unpkg.com/apiskill@latest/README.ja.md)
 
-API Skill은 프론트엔드 개발과 AI 보조 코딩을 위한 로컬 OpenAPI/Swagger 작업 공간입니다. 세 가지 진입점이 같은 캐시된 API 문서를 공유합니다.
+API Skill은 프론트엔드 개발과 AI 보조 코딩을 위한 로컬 OpenAPI/Swagger 작업 공간입니다. 사람을 위한 Web 작업 공간과 AI Agent를 위한 CLI/MCP 인터페이스가 같은 캐시된 API 문서를 공유합니다.
 
-- Web 앱: API 문서를 가져오고, 탐색하고, 검색하고, 검사하고, 테스트하며, 수동 API 작업을 관리합니다.
-- CLI: 터미널에서 문서를 가져오고 로컬 API 버전을 관리하거나 조회합니다.
-- MCP 서버: 같은 API 컨텍스트와 유지 관리 기능을 Codex 또는 다른 MCP 클라이언트에 제공합니다.
+- Web 앱: 사람이 API 문서를 가져오고, 탐색하고, 검색하고, 검사하고, 테스트하며 버전과 API 작업을 관리합니다.
+- CLI: AI Agent와 자동화 작업이 문서 상태를 확인하고 필요한 API 컨텍스트를 조회하거나 유지 관리합니다.
+- MCP 서버: 같은 API 조회 및 유지 관리 기능을 Codex 또는 다른 AI Agent 클라이언트에 제공합니다.
 
 ## Web 앱 사용
 
@@ -92,9 +92,9 @@ Agent 워크플로는 MCP에서 가장 큰 이점을 얻습니다. 코딩 agent
 
 ## 문서
 
-- Web 앱: [English](docs/web.md) / [中文](docs/web.zh.md) / [한국어](docs/web.ko.md) / [日本語](docs/web.ja.md)
-- CLI 구성 및 사용법: [English](docs/cli.md) / [中文](docs/cli.zh.md) / [한국어](docs/cli.ko.md) / [日本語](docs/cli.ja.md)
-- MCP 구성 및 사용법: [English](docs/mcp.md) / [中文](docs/mcp.zh.md) / [한국어](docs/mcp.ko.md) / [日本語](docs/mcp.ja.md)
+- Web 앱: [English](https://unpkg.com/apiskill@latest/docs/web.md) / [中文](https://unpkg.com/apiskill@latest/docs/web.zh.md) / [한국어](https://unpkg.com/apiskill@latest/docs/web.ko.md) / [日本語](https://unpkg.com/apiskill@latest/docs/web.ja.md)
+- CLI 구성 및 사용법: [English](https://unpkg.com/apiskill@latest/docs/cli.md) / [中文](https://unpkg.com/apiskill@latest/docs/cli.zh.md) / [한국어](https://unpkg.com/apiskill@latest/docs/cli.ko.md) / [日本語](https://unpkg.com/apiskill@latest/docs/cli.ja.md)
+- MCP 구성 및 사용법: [English](https://unpkg.com/apiskill@latest/docs/mcp.md) / [中文](https://unpkg.com/apiskill@latest/docs/mcp.zh.md) / [한국어](https://unpkg.com/apiskill@latest/docs/mcp.ko.md) / [日本語](https://unpkg.com/apiskill@latest/docs/mcp.ja.md)
 
 ## 데이터 모델
 

package/README.md

@@ -1,12 +1,12 @@
 # API Skill
 
-[English](README.md) / [中文](README.zh.md) / [한국어](README.ko.md) / [日本語](README.ja.md)
+[English](https://unpkg.com/apiskill@latest/README.md) / [中文](https://unpkg.com/apiskill@latest/README.zh.md) / [한국어](https://unpkg.com/apiskill@latest/README.ko.md) / [日本語](https://unpkg.com/apiskill@latest/README.ja.md)
 
-API Skill is a local OpenAPI/Swagger workspace for frontend and agent-assisted development. It has three surfaces that share the same cached API documents:
+API Skill is a local OpenAPI/Swagger workspace for frontend and agent-assisted development. It has one human-facing workspace and two agent-facing interfaces that share the same cached API documents:
 
-- Web app: import, browse, search, inspect, test, and manually maintain API operations.
-- CLI: import documents, manage/query local API versions, and start a MOCK server from a terminal.
-- MCP server: expose the same API context and maintenance actions to Codex or other MCP clients.
+- Web app, for people: import, browse, search, inspect, test, version, and manually maintain API operations.
+- CLI, for AI agents and automation: check document availability, retrieve focused API context, maintain documents, and start local services with predictable commands.
+- MCP server, for AI agents: expose the same query and maintenance actions directly to Codex or other MCP clients.
 
 ## Web App Usage
 
@@ -17,28 +17,40 @@ npm install -g apiskill
 apiskill run web
 ```
 
-The web app stores version data in `cache/` under the current directory by default. When developing this repository, you can also start it from the project root:
+Global npm installations store version data in the user-writable `~/.apiskill/cache` directory by default. Use `--cwd` for a project-local `<cwd>/cache`, or `--cache-dir` for a custom location. When developing this repository, you can also start it from the project root:
 
 ```bash
 npm install
 npm run dev
 ```
 
-Open the local URL shown in the terminal. The web app can import API documents from a direct OpenAPI JSON/YAML URL, crawl a Swagger UI / Knife4j / Redoc page, upload a local file, execute a curl command that returns an OpenAPI document, or create a blank document from scratch.
+Open the local URL shown in the terminal. The New Document dialog can import a direct OpenAPI JSON/YAML URL, crawl a Swagger UI / Knife4j / Redoc page, upload a local file, execute a curl command that returns an OpenAPI document, or create a blank document from scratch.
 
 After importing or creating a blank document, use the version selector to switch cached documents, search endpoints by path, summary, tag, method, or parameter text, and open endpoint tabs to inspect request parameters, request bodies, response fields, AI-ready context, and raw JSON. You can also add, edit, or delete manual API operations; those changes are saved as local cached versions.
 
 After API document data exists, click Start MOCK Service in the web app or run `apiskill mock` in CLI to start a local random-data MOCK API server from the current interface definitions.
 
-For CLI and MCP usage, run the built-in checks first:
+### AI Agent Quick Start
 
 ```bash
-npm run cli -- check
-```
+# 1. Check whether API documentation is ready
+apiskill check
+
+# 2. Initialize the cache when no document exists
+apiskill import https://example.com/openapi.json
+apiskill crawl https://example.com/swagger
+apiskill import-file ./openapi.yaml
+apiskill document create --title "My API" --doc-version 1.0.0
 
-After npm installation, the equivalent command is `apiskill check`.
+# 3. Retrieve only the API context needed for the current coding task
+apiskill versions
+apiskill query /api/v1/users --method GET
+
+# 4. Start a local random-data API from the active document
+apiskill mock
+```
 
-To start from zero in CLI, run `npm run cli -- document create --title "My API" --doc-version 1.0.0`, then add endpoints with `api create`. In MCP clients, call `apiskill_check` to verify the cache, `apiskill_create_document` to create a blank document when no upstream docs exist, and `apiskill_help` to list available tools.
+CLI and MCP are primarily designed for AI coding agents. Agents should check the cache first, initialize it only when needed, and query a focused endpoint instead of reading the entire OpenAPI document. Run `apiskill --help` for all CLI commands. In MCP clients, start with `apiskill_check`, use `apiskill_search_endpoints` or `apiskill_query_api` to locate an API, and call `apiskill_help` for the complete tool list.
 
 ## Why This Tool Exists
 
@@ -103,9 +115,9 @@ Agent workflows benefit most from MCP. A coding agent can call `apiskill_search_
 
 ## Documentation
 
-- Web app: [English](docs/web.md) / [中文](docs/web.zh.md) / [한국어](docs/web.ko.md) / [日本語](docs/web.ja.md)
-- CLI configuration and usage: [English](docs/cli.md) / [中文](docs/cli.zh.md) / [한국어](docs/cli.ko.md) / [日本語](docs/cli.ja.md)
-- MCP configuration and usage: [English](docs/mcp.md) / [中文](docs/mcp.zh.md) / [한국어](docs/mcp.ko.md) / [日本語](docs/mcp.ja.md)
+- Web app: [English](https://unpkg.com/apiskill@latest/docs/web.md) / [中文](https://unpkg.com/apiskill@latest/docs/web.zh.md) / [한국어](https://unpkg.com/apiskill@latest/docs/web.ko.md) / [日本語](https://unpkg.com/apiskill@latest/docs/web.ja.md)
+- CLI configuration and usage: [English](https://unpkg.com/apiskill@latest/docs/cli.md) / [中文](https://unpkg.com/apiskill@latest/docs/cli.zh.md) / [한국어](https://unpkg.com/apiskill@latest/docs/cli.ko.md) / [日本語](https://unpkg.com/apiskill@latest/docs/cli.ja.md)
+- MCP configuration and usage: [English](https://unpkg.com/apiskill@latest/docs/mcp.md) / [中文](https://unpkg.com/apiskill@latest/docs/mcp.zh.md) / [한국어](https://unpkg.com/apiskill@latest/docs/mcp.ko.md) / [日本語](https://unpkg.com/apiskill@latest/docs/mcp.ja.md)
 
 ## Data Model
 

package/README.zh.md

@@ -1,12 +1,12 @@
 # API Skill
 
-[English](README.md) / [中文](README.zh.md) / [한국어](README.ko.md) / [日本語](README.ja.md)
+[English](https://unpkg.com/apiskill@latest/README.md) / [中文](https://unpkg.com/apiskill@latest/README.zh.md) / [한국어](https://unpkg.com/apiskill@latest/README.ko.md) / [日本語](https://unpkg.com/apiskill@latest/README.ja.md)
 
-API Skill 是一个本地 OpenAPI/Swagger 工作区，面向前端开发和 AI 辅助编码。它提供三种入口，并共享同一份本地缓存接口文档：
+API Skill 是一个本地 OpenAPI/Swagger 工作区，面向前端开发和 AI 辅助编码。它提供一个面向人的工作台和两个面向 AI Agent 的接口，并共享同一份本地缓存接口文档：
 
-- Web 端：导入、浏览、搜索、查看、测试和手动维护接口。
-- CLI：在终端里导入文档、管理版本、查询和维护本地接口，并启动 MOCK 服务。
-- MCP 服务：把同一套接口上下文和维护能力暴露给 Codex 或其他 MCP 客户端。
+- Web 端，主要给人使用：导入、浏览、搜索、查看、测试、版本管理和手动维护接口。
+- CLI，主要给 AI Agent 和自动化任务使用：检查文档状态、按需获取接口上下文、维护文档并启动本地服务。
+- MCP 服务，主要给 AI Agent 使用：把同一套查询和维护能力直接暴露给 Codex 或其他 MCP 客户端。
 
 ## Web 端使用
 
@@ -17,28 +17,40 @@ npm install -g apiskill
 apiskill run web
 ```
 
-Web 端默认使用当前目录下的 `cache/` 保存版本数据。开发本仓库时也可以在项目根目录启动：
+通过 npm 全局安装时，Web 端默认使用用户可写的 `~/.apiskill/cache` 保存版本数据。使用 `--cwd` 可切换为项目目录下的 `<cwd>/cache`，使用 `--cache-dir` 可指定其他位置。开发本仓库时也可以在项目根目录启动：
 
 ```bash
 npm install
 npm run dev
 ```
 
-打开终端输出的本地地址。Web 端可以导入直接的 OpenAPI JSON/YAML 地址，爬取 Swagger UI / Knife4j / Redoc 页面，上传本地文件，执行返回 OpenAPI 文档的 curl 命令，也可以从零新建空白文档。
+打开终端输出的本地地址。“新建文档”弹窗可以导入直接的 OpenAPI JSON/YAML 地址，爬取 Swagger UI / Knife4j / Redoc 页面，上传本地文件，执行返回 OpenAPI 文档的 curl 命令，也可以从零新建空白文档。
 
 导入或新建文档后，可以用版本选择器切换缓存文档，按路径、摘要、tag、method 或参数文本搜索接口，并打开接口 tab 查看请求参数、请求体、响应字段、AI 友好的上下文和原始 JSON。也可以新增、编辑、删除手动接口；这些改动会保存为本地缓存版本。
 
 已有 API 文档数据后，可以在 Web 端点击“启动MOCK服务”，或在 CLI 里运行 `apiskill mock`，根据当前接口定义启动本地随机数据 MOCK API 服务。
 
-CLI 和 MCP 使用前建议先运行内置检查：
+### AI Agent 快速使用
 
 ```bash
-npm run cli -- check
-```
+# 1. 检查 API 文档是否可用
+apiskill check
+
+# 2. 没有文档时初始化缓存
+apiskill import https://example.com/openapi.json
+apiskill crawl https://example.com/swagger
+apiskill import-file ./openapi.yaml
+apiskill document create --title "My API" --doc-version 1.0.0
 
-npm 安装后的等价命令是 `apiskill check`。
+# 3. 只获取当前开发任务需要的接口上下文
+apiskill versions
+apiskill query /api/v1/users --method GET
+
+# 4. 根据当前文档启动本地随机数据接口
+apiskill mock
+```
 
-如果要通过 CLI 从零开始，运行 `npm run cli -- document create --title "My API" --doc-version 1.0.0` 创建空白文档，再用 `api create` 追加接口。在 MCP 客户端里，先调用 `apiskill_check` 检查缓存；没有上游文档时调用 `apiskill_create_document` 创建空白文档；再调用 `apiskill_help` 查看可用工具。
+CLI 和 MCP 主要面向 AI 编码 Agent。Agent 应先检查缓存，只在缺少文档时初始化，然后按当前任务精确查询接口，避免每次读取整份 OpenAPI 文档。运行 `apiskill --help` 可以查看全部 CLI 命令；在 MCP 客户端中先调用 `apiskill_check`，再使用 `apiskill_search_endpoints` 或 `apiskill_query_api` 定位接口，调用 `apiskill_help` 可查看完整工具列表。
 
 ## 为什么开发这个工具
 
@@ -103,9 +115,9 @@ Agent 工作流最适合接入 MCP。编码 agent 可以先调用 `apiskill_sear
 
 ## 文档
 
-- Web 端：[English](docs/web.md) / [中文](docs/web.zh.md) / [한국어](docs/web.ko.md) / [日本語](docs/web.ja.md)
-- CLI 配置和使用：[English](docs/cli.md) / [中文](docs/cli.zh.md) / [한국어](docs/cli.ko.md) / [日本語](docs/cli.ja.md)
-- MCP 配置和使用：[English](docs/mcp.md) / [中文](docs/mcp.zh.md) / [한국어](docs/mcp.ko.md) / [日本語](docs/mcp.ja.md)
+- Web 端：[English](https://unpkg.com/apiskill@latest/docs/web.md) / [中文](https://unpkg.com/apiskill@latest/docs/web.zh.md) / [한국어](https://unpkg.com/apiskill@latest/docs/web.ko.md) / [日本語](https://unpkg.com/apiskill@latest/docs/web.ja.md)
+- CLI 配置和使用：[English](https://unpkg.com/apiskill@latest/docs/cli.md) / [中文](https://unpkg.com/apiskill@latest/docs/cli.zh.md) / [한국어](https://unpkg.com/apiskill@latest/docs/cli.ko.md) / [日本語](https://unpkg.com/apiskill@latest/docs/cli.ja.md)
+- MCP 配置和使用：[English](https://unpkg.com/apiskill@latest/docs/mcp.md) / [中文](https://unpkg.com/apiskill@latest/docs/mcp.zh.md) / [한국어](https://unpkg.com/apiskill@latest/docs/mcp.ko.md) / [日本語](https://unpkg.com/apiskill@latest/docs/mcp.ja.md)
 
 ## 数据模型