aweskill 0.1.8 → 0.2.1

package/README.zh-CN.md

@@ -3,7 +3,7 @@
   <h1>aweskill：为所有编码代理准备的一套 Skill 中央仓库</h1>
   <p><strong>面向 AI 编码代理的本地 Skill 编排命令行工具。</strong></p>
   <p>
-    <a href="https://github.com/mugpeng/aweskill/releases"><img src="https://img.shields.io/badge/version-0.1.8-7C3AED?style=flat-square" alt="Version"></a>
+    <a href="https://github.com/mugpeng/aweskill/releases"><img src="https://img.shields.io/badge/version-0.2.0-7C3AED?style=flat-square" alt="Version"></a>
     <a href="https://github.com/mugpeng/aweskill"><img src="https://img.shields.io/badge/node-%E2%89%A520-0EA5E9?style=flat-square" alt="Node"></a>
     <a href="https://github.com/mugpeng/aweskill/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MPL--2.0-22C55E?style=flat-square" alt="License"></a>
     <a href="./README.md"><img src="https://img.shields.io/badge/README-English-64748B?style=flat-square" alt="English README"></a>
@@ -12,10 +12,14 @@
     <img src="https://img.shields.io/badge/status-beta-c96a3d?style=flat-square" alt="Status">
     <img src="https://img.shields.io/badge/agents-47_supported-0ea5a4?style=flat-square" alt="Supported agents">
     <img src="https://img.shields.io/badge/projection-symlink-1f2328?style=flat-square" alt="Projection mode">
+    <img src="https://img.shields.io/badge/OS-windows%20%26%20macOS-0078D4?style=flat-square" alt="Windows and macOS">
+    <img src="https://img.shields.io/npm/dt/aweskill?style=flat-square" alt="npm downloads">
+    <img src="https://img.shields.io/github/stars/mugpeng/aweskill?style=flat-square" alt="GitHub stars">
     <img src="https://img.shields.io/badge/platform-local%20CLI-334155?style=flat-square" alt="Local CLI">
   </p>
 </div>
 
+
 `aweskill` 是一个本地 CLI，用来在多个 AI 编码代理之间管理、组织和投影技能。
 
 你不需要再把同一套 skill 文件夹手动复制到每个工具里。`aweskill` 会把 `~/.aweskill/skills/` 作为唯一事实来源，再按目标 agent 的要求，把 skill 以 `symlink` 或 `copy` 的形式投影到对应目录。
@@ -42,7 +46,7 @@ aweskill --help
 固定到某一版本：
 
 ```bash
-npm install -g aweskill@0.1.8
+npm install -g aweskill@0.2.0
 ```
 
 包主页：[npmjs.com/package/aweskill](https://www.npmjs.com/package/aweskill)
@@ -68,7 +72,7 @@ aweskill --help
 ```bash
 npm install
 npm pack
-npm install -g ./aweskill-0.1.8.tgz
+npm install -g ./aweskill-0.2.0.tgz
 ```
 
 ## 快速开始
@@ -77,37 +81,52 @@ npm install -g ./aweskill-0.1.8.tgz
 # 1. 初始化 aweskill 家目录
 aweskill store init
 
-# 2. 扫描已有 agent 的 skill 目录
-aweskill skill scan
+# 2. 查看 aweskill store 在哪里
+aweskill store where --verbose
+
+# 3. 扫描已有 agent 的 skill 目录
+aweskill store scan
 
-# 3. 导入一个 skills 根目录或单个 skill
-aweskill skill import ~/.agents/skills
-# aweskill skill import /path/to/my-skill --mode cp
+# 4. 把扫描到的 agent skill 导入中央仓库
+aweskill store import --scan
 
-# 4. 创建 bundle
+# 5. 导入一个 skills 根目录或单个 skill
+aweskill store import ~/.agents/skills
+# aweskill store import /path/to/my-skill --link-source
+
+# 6. 创建 bundle
 aweskill bundle create frontend
 aweskill bundle add frontend my-skill
 
-# 5. 为一个 agent 启用这个 bundle
+# 7. 为一个 agent 启用这个 bundle
 aweskill agent add bundle frontend --global --agent claude-code
 
-# 6. 查看当前投影状态
+# 8. 查看当前投影状态
 aweskill agent list
 ```
 
-## 核心模型
+## Windows
+
+`aweskill` 现在已经支持 Windows 原生使用。
+
+- 需要 Node.js 20 及以上
+- 推荐使用 PowerShell 执行命令
+- 在 Windows 上，agent 投影会优先使用目录 junction；如果系统不允许创建链接，会回退到受管 copy
+- `store backup` 和 `store restore` 不再依赖系统自带 `tar`
+
+示例：
 
-`aweskill` 的模型很简单：
+```powershell
+aweskill store init
+aweskill store scan
+aweskill agent add bundle frontend --global --agent codex
+```
 
-1. Skill 统一保存在 `~/.aweskill/skills/<skill-name>/`
-2. Bundle 是 `~/.aweskill/bundles/<bundle>.yaml` 下的普通 YAML 文件
-3. `agent add` 会把选定的 skill 投影到各 agent 自己的 skills 目录
+如果你在 Windows 上遇到路径、权限或投影问题，建议带上 shell、Node 版本和目标 agent 信息来提 issue。
 
-投影状态就是启用状态：
+## 核心模型
 
-- 有托管的 symlink，就表示启用
-- 没有，就表示停用
-- 不存在额外的全局 activation 注册表
+`aweskill` 会把 `~/.aweskill/skills/` 作为唯一技能中央仓库，用 bundle 组织可复用 skill 集合，再把选中的 skill 投影到各个 agent 的技能目录。投影后的文件系统状态本身就是启用状态。
 
 ## 支持范围
 
@@ -121,57 +140,109 @@ aweskill agent list
 - 重复项暂存区：`~/.aweskill/dup_skills/`
 - 备份目录：`~/.aweskill/backup/`
 - Bundle 文件：`~/.aweskill/bundles/*.yaml`
-- 仓库资源目录：`resources/bundle_templates/` 和 `resources/skill_archives/`
+- 内置 skill：`skills/aweskill/`、`skills/aweskill-advanced/`、`skills/aweskill-doctor/`
 
 ## 常见工作流
 
 ### 把现有 skill 导入中央仓库
 
 ```bash
-aweskill skill import ~/.agents/skills
-aweskill skill import ~/Downloads/pr-review --mode cp
-aweskill skill import --scan
+# 从现有 agent skill 目录导入
+aweskill store import ~/.agents/skills
+
+# 导入外部 skill 目录，并保留原目录不变
+aweskill store import ~/Downloads/pr-review
+
+# 导入外部 skill 目录，并把原目录替换成 aweskill 托管投影
+aweskill store import ~/Downloads/pr-review --link-source
+
+# 导入扫描到的 agent skill，默认回写成 aweskill 托管投影
+aweskill store import --scan
+
+# 导入扫描到的 agent skill，但保留原 agent 目录不变
+aweskill store import --scan --keep-source
 ```
 
 ### 构建可复用 bundle
 
 ```bash
+# 创建一个可复用 bundle
 aweskill bundle create backend
+
+# 给 bundle 添加多个 skill
 aweskill bundle add backend api-design,db-schema
+
+# 查看 bundle 内容
 aweskill bundle show backend
 ```
 
 ### 把 skill 投影到多个 agent
 
 ```bash
+# 把一个 skill 投影到检测到的全局 agent 目录
 aweskill agent add skill biopython
+
+# 把多个 skill 投影到指定 agent 的全局目录
 aweskill agent add skill biopython,scanpy --global --agent codex
+
+# 把整个 bundle 投影到所有检测到的全局 agent
 aweskill agent add bundle backend --global --agent all
+
+# 把托管 symlink 恢复为完整目录
+aweskill agent recover --global --agent codex
 ```
 
 ### 维护本地仓库
 
 ```bash
-aweskill store backup --both
-aweskill agent sync
-aweskill agent recover --global --agent codex
-aweskill doctor dedupe --fix
+# 查看中央仓库位置和目录统计
+aweskill store where --verbose
+
+# 备份当前 store
+aweskill store backup
+
+# 恢复备份归档
+aweskill store restore ~/Downloads/aweskill-backup.tar.gz
+
+# 查看 agent 条目分类
+aweskill agent list
+
+# 清理中央仓库里的可疑条目
+aweskill doctor clean
+
+# 把中央仓库里的重复 skill 移到 dup_skills
+aweskill doctor dedup --apply
+
+# 先看某个 agent 下有哪些可修项
+aweskill doctor sync --global --agent codex
+
+# 修复某个 agent 下的 broken / duplicate / matched 条目
+aweskill doctor sync --global --agent codex --apply
+
+# 只有显式指定时才删除 suspicious agent 条目
+aweskill doctor sync --global --agent codex --apply --remove-suspicious
 ```
 
-默认情况下，`store backup` 和 `store restore` 只处理 `skills/`。加上 `--both` 会同时处理 `bundles/`；如果想导出到指定位置，也可以给 `store backup` 传一个可选的 archive 路径。
+所有 `doctor` 命令默认为 dry run，加上 `--apply` 才会真正修改。
 
 ## 命令面
 
+核心命令：`store init`、`store where`、`store import`、`bundle create`、`agent add`、`doctor clean`
+
+<details>
+<summary>全部命令</summary>
+
 | 命令 | 说明 |
 | --- | --- |
 | `aweskill store init [--scan] [--verbose]` | 初始化 `~/.aweskill` 布局 |
-| `aweskill store backup [archive] [--both]` | 归档中央 skill 仓库，也可导出到指定路径 |
-| `aweskill store restore <archive> [--override] [--both]` | 从备份恢复 |
-| `aweskill skill scan [--verbose]` | 扫描支持的 agent skill 目录 |
-| `aweskill skill import <path> [--mode cp\|mv] [--override]` | 导入单个 skill 或整个 skills 根目录 |
-| `aweskill skill import --scan [--mode cp\|mv] [--override]` | 导入当前扫描结果 |
-| `aweskill skill list [--verbose]` | 列出中央仓库中的 skill |
-| `aweskill skill remove <skill> [--force]` | 从中央仓库删除一个 skill |
+| `aweskill store where [--verbose]` | 显示 `~/.aweskill` 位置，并汇总核心 store 目录 |
+| `aweskill store backup [archive] [--skills-only]` | 归档中央仓库；默认同时包含 skills 和 bundles |
+| `aweskill store restore <archive-or-dir> [--override] [--skills-only]` | 从备份归档或已解包目录恢复 |
+| `aweskill store scan [--global\|--project [dir]] [--agent <agent>] [--verbose]` | 按指定 scope 和 agent 集合扫描支持的 agent skill 目录 |
+| `aweskill store import <path> [--keep-source\|--link-source] [--override]` | 导入单个 skill 或整个 skills 根目录；外部路径默认保留原目录 |
+| `aweskill store import --scan [--global\|--project [dir]] [--agent <agent>] [--keep-source\|--link-source] [--override]` | 按指定 scope 和 agent 集合导入当前扫描结果；扫描到的 agent 路径默认会回写为 aweskill 托管投影 |
+| `aweskill store list [--verbose]` | 列出中央仓库中的 skill |
+| `aweskill store remove <skill> [--force]` | 从中央仓库删除一个 skill |
 | `aweskill bundle list [--verbose]` | 列出 bundle |
 | `aweskill bundle create <name>` | 创建 bundle |
 | `aweskill bundle add <bundle> <skill>` | 向 bundle 增加一个或多个 skill |
@@ -179,84 +250,48 @@ aweskill doctor dedupe --fix
 | `aweskill bundle show <name>` | 查看 bundle 内容 |
 | `aweskill bundle template list [--verbose]` | 列出内置 bundle 模板 |
 | `aweskill bundle template import <name>` | 把内置模板复制到本地仓库 |
-| `aweskill agent supported` | 列出支持的 agent id 和显示名 |
+| `aweskill agent supported` | 列出全部支持的 agent id，用 `✓` / `x` 标记 global 安装状态，并显示已检测到的 global skills 路径 |
 | `aweskill agent add bundle\|skill ...` | 把托管 skill 投影到 agent 目录 |
 | `aweskill agent remove bundle\|skill ... [--force]` | 删除托管投影 |
-| `aweskill agent list [...]` | 检查 `linked`、`duplicate`、`new` 状态 |
-| `aweskill agent sync` | 删除失效托管投影 |
+| `aweskill agent list [--global\|--project [dir]] [--agent <agent>] [--verbose]` | `doctor sync` 的只读 dry-run 视图：检查 `linked`、`broken`、`duplicate`、`matched`、`new`、`suspicious` 状态；省略 `--agent` 时，先输出当前 scope 检测到的 agent 集合，再输出分组结果 |
+| `aweskill doctor sync [--apply] [--remove-suspicious] [--global\|--project [dir]] [--agent <agent>] [--verbose]` | 默认 dry run；加上 `--apply` 修复 broken 并重连 duplicate / matched，`--apply --remove-suspicious` 额外删除 suspicious；省略 `--agent` 时，先输出当前 scope 检测到的 agent 集合 |
 | `aweskill agent recover` | 把托管 symlink 恢复为完整目录 |
-| `aweskill doctor dedupe [--fix] [--delete]` | 查找并清理重复 skill |
-
-## 设计取舍
+| `aweskill doctor clean [--apply] [--skills-only] [--bundles-only] [--verbose]` | 按 `skills` / `bundles` 分组查找不规范的 store 条目，并可选清理 |
+| `aweskill doctor dedup [--apply] [--delete]` | 查找重复 skill，并可选移动或删除 |
 
-### 没有全局 activation 文件
-
-`aweskill` 直接把投影后的文件系统状态当作事实来源。这样模型更简单，也避免额外的一层 activation 元数据和实际目录状态漂移。
-
-### Bundle 是展开集合
-
-`agent add bundle <name>` 会把 bundle 展开为多个 skill 名，再逐个投影。投影完成后，不存在一个额外长期保存的“bundle 激活对象”。
-
-### 只删除托管项
-
-`aweskill` 只删除它能够明确识别为自己创建的托管 symlink，不会盲删任意 skill 目录。
+</details>
 
-## Bundle 文件格式
+## 内置 Skill
 
-Bundle 是 `~/.aweskill/bundles/<name>.yaml` 下的普通 YAML 文件：
+`aweskill` 内置了三个 meta-skill，用来教 AI 编码代理直接操作 CLI。把它们导入中央仓库后，Codex、Claude Code、Cursor 等 agent 就能自动运行 aweskill 命令，无需人工介入。
 
-```yaml
-name: frontend
-skills:
-  - pr-review
-  - frontend-design
+```bash
+aweskill store import skills/aweskill
+aweskill store import skills/aweskill-advanced
+aweskill store import skills/aweskill-doctor
 ```
 
-## 投影模型
-
-1. **Skill 内容的唯一事实来源**：`~/.aweskill/skills/<skill-name>/`
-2. **`agent add`** 会在指定 agent 和支持的 scope 下创建一个指向中央仓库的 **symlink**
-3. **`agent remove`** 只会删除能识别为 `aweskill` 托管的条目
-4. **`agent sync`** 会移除中央 skill 已不存在时留下的失效托管投影
-
-**不会**基于某个全局 YAML activation 列表做 reconcile。
-
-导入行为：
-
-- 默认 `skill import --scan` 和批量 `skill import` 只补缺失文件；`--override` 才会覆盖
-- 如果导入源是 symlink，aweskill 会从真实路径复制，并在需要时给出 warning
-- 批量导入遇到坏掉的 symlink 会继续处理其他项
-- `restore` 在恢复前会自动备份当前 `skills/`
-
-显示行为：
-
-- `skill list` 默认显示预览，`--verbose` 才显示全部
-- `skill scan` 默认显示每个 agent 的统计，`--verbose` 才列出具体 skill
-- `agent list` 会把条目分成 `linked`、`duplicate`、`new`
-- `doctor dedupe` 会把 `name`、`name-2`、`name-1.2.3` 视为同一重复族，只有传 `--fix` 才真正改文件
-
-投影示例：
-
-```bash
-# 全局范围为一个 agent 建立投影
-aweskill agent add skill biopython --global --agent codex
+| Skill | 面向 | 何时使用 |
+| --- | --- | --- |
+| `aweskill` | 操作面 | 日常：init、scan、import、list、remove、bundle 增删改查、基础 agent 投影 |
+| `aweskill-advanced` | 维护面 | 低频：跨 agent 投影策略、bundle 模板、recover 流程、多 scope 规划 |
+| `aweskill-doctor` | 诊断面 | 修复：`doctor clean`、`doctor dedup`、`doctor sync`，解读 broken/duplicate/suspicious |
 
-# 项目范围为一个 agent 建立投影
-aweskill agent add skill pr-review --project /path/to/repo --agent cursor
+skill 目录结构与设计原则见 [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md)。
 
-# bundle 的启用/禁用本质上都是展开成 skill 投影
-aweskill agent add bundle backend --global --agent codex
-aweskill agent remove bundle backend --global --agent codex
+## 贡献
 
-# 把 symlink 投影恢复成完整目录
-aweskill agent recover --global --agent codex
-```
+如果你想参与开发，请看 [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md)。
 
-## 模板与归档
+那里现在集中说明了：
 
-内置 bundle 模板现在位于 [resources/bundle_templates/K-Dense-AI-scientific-skills.yaml](/Users/peng/Desktop/Project/aweskills/resources/bundle_templates/K-Dense-AI-scientific-skills.yaml)。运行时 bundle 仍然位于 `~/.aweskill/bundles/`。
+- 设计取舍
+- bundle 文件格式
+- 投影模型
+- 内置 skill 结构与设计原则
+- 开发流程与测试要求
 
-`resources/skill_archives/` 预留给你手动维护的整仓库 `tar.gz` 归档，用于随仓库分发给其他用户。`aweskill` 不会自动生成或恢复这些归档。
+欢迎提交文档改进、测试补充和小而聚焦的功能改进。
 
 如果你希望使用一个独立于本仓库、可直接分享给其他用户的技能归档集合，可以参考 [oh-my-skills](https://github.com/mugpeng/oh-my-skills)。它是一个单独维护的备份仓库，用来存放可分发的 bundle 和整库快照归档。
 
@@ -337,7 +372,7 @@ aweskill agent recover --global --agent codex
 
 </details>
 
-## 开发
+## 开发命令
 
 ```bash
 npm install