@tec-explorer/skillpot 0.4.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +56 -0
- package/LICENSE +21 -0
- package/README.md +142 -0
- package/dist/cli.mjs +45972 -0
- package/package.json +61 -0
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
所有显著变更记录于此。格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
|
|
4
|
+
版本号遵循 [SemVer](https://semver.org/lang/zh-CN/)。
|
|
5
|
+
|
|
6
|
+
## [0.4.1] - 2026-09-04
|
|
7
|
+
|
|
8
|
+
### Added
|
|
9
|
+
- npm 分发支持：`prepare` 钩子（`npm install` / GitHub 直装 / `npm pack` 时自动构建 `dist`）与 `prepublishOnly` 钩子（发布前强制构建 + 测试，失败中断）
|
|
10
|
+
- GitHub Actions 发布流水线：push `v*` 标签自动构建、测试并发布到 npm（带 provenance，需仓库配置 `NPM_TOKEN` secret）
|
|
11
|
+
|
|
12
|
+
### Changed
|
|
13
|
+
- npm 包名改为 `@tec-explorer/skillpot`（挂 tec-explorer 组织 scope），`publishConfig.access: public` 保证 scope 包默认公开发布；bin 命令名 `skillpot` / `spot` 不变
|
|
14
|
+
- `package.json` `repository.url` 修正为实际仓库地址 `tec-explorer/skillpot`
|
|
15
|
+
- npm 包内容补充 `CHANGELOG.md`
|
|
16
|
+
- README 安装说明补充 GitHub 直装 / npx / 源码三种方式
|
|
17
|
+
|
|
18
|
+
## [0.4.0] - 2026-09-03
|
|
19
|
+
|
|
20
|
+
### Added
|
|
21
|
+
- `adopt --move` 移动模式：内容拷入中央仓库后，把来源 Agent 目录下的原目录替换为 symlink（来源 Agent 自动开放）
|
|
22
|
+
- `init` 空仓库检测提醒：自动扫描各已安装 Agent 的已有 skill，TTY 下交互询问是否移入
|
|
23
|
+
- 对 `init`/`adopt` 等命令的收编来源标记（`adopt:<agent>:<path>`）
|
|
24
|
+
|
|
25
|
+
### Fixed
|
|
26
|
+
- commander 静默吞掉多余位置参数（连接符打错时 adopt 被忽略且无提示）→ 现在显式报错
|
|
27
|
+
- 表格按 ANSI 剥离后的可见宽度对齐（修复彩色单元格错位）
|
|
28
|
+
- **symlink 解引用**：拷贝/_checksum 此前不解引用符号链接，导致仓库出现外部链接与空内容哈希；现在仓库自包含只存真实内容
|
|
29
|
+
|
|
30
|
+
### Changed
|
|
31
|
+
- MCP `serverInfo.version` 与包版本同步维护
|
|
32
|
+
|
|
33
|
+
## [0.3.0] - 2026-09-03
|
|
34
|
+
|
|
35
|
+
### Added
|
|
36
|
+
- `skillpot tui` 交互式开关矩阵（skill × Agent）：方向键移动、空格切换、整行开关、`--once` 静态输出；无 TTY 自动降级
|
|
37
|
+
|
|
38
|
+
### Changed
|
|
39
|
+
- 构建从 tsc 直出 CJS 切换为 esbuild 单文件 ESM 打包（`dist/cli.mjs`，内联 ink/react）；tsc 退为纯类型检查
|
|
40
|
+
|
|
41
|
+
## [0.2.0] - 2026-09-03
|
|
42
|
+
|
|
43
|
+
### Added
|
|
44
|
+
- `adopt` 收编：把各 Agent 目录下已有 skill 拷入中央仓库（`--dry-run` 预览、`--for` 导入即开放）
|
|
45
|
+
- `lint` 安全扫描：frontmatter 完整性 + 脚本高危模式（`rm -rf`、`curl|sh` 等）；`add` 自动执行
|
|
46
|
+
- `update [--check]` + `skillspot.lock.json`：git 来源版本比对与原位替换
|
|
47
|
+
- `skillpot mcp`：零依赖 stdio MCP server（`skillpot_list/read/search`），遵循开关矩阵过滤
|
|
48
|
+
- enable/disable 输出"重启示例会话后生效"提示
|
|
49
|
+
|
|
50
|
+
## [0.1.0] - 2026-09-03
|
|
51
|
+
|
|
52
|
+
### Added
|
|
53
|
+
- M1 MVP：`init / agents / add / list / enable / disable / remove / doctor`
|
|
54
|
+
- 中央仓库 `~/.skillpot`（唯一真身 + config.yaml 开关矩阵 + state.json 链接台账）
|
|
55
|
+
- 五家 Agent 适配器：Claude Code / ZCode / Codex CLI / OpenCode / Gemini CLI（symlink 落地策略）
|
|
56
|
+
- symlink 跨 Agent 发现经 Claude Code 实测验证（M0）
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 zhangmingyong
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
# SkillPot
|
|
2
|
+
|
|
3
|
+
[](LICENSE)
|
|
4
|
+
[](package.json)
|
|
5
|
+
[](https://github.com/zhangmingyong/skillpot/actions)
|
|
6
|
+
|
|
7
|
+
**跨编程 Agent 的 Skill 管理器 —— 一处安装，按 Agent 开关，一处更新。**
|
|
8
|
+
*Cross-agent skill manager for coding agents: install once, expose per agent, update once.*
|
|
9
|
+
|
|
10
|
+
> 编程 Agent（Claude Code、ZCode、Codex、OpenCode、Gemini CLI…）已收敛到同一套 `SKILL.md` 开放标准，但发现路径各自为政：装进 `~/.claude/skills` 就只对 Claude Code 生效。SkillPot 把 skill 收进一个中央仓库，按 Agent 粒度开关暴露，并提供冲突体检与安全扫描。
|
|
11
|
+
|
|
12
|
+
## 特性
|
|
13
|
+
|
|
14
|
+
- **一处安装**：中央仓库 `~/.skillpot/skills/` 存唯一真身，自带 checksum 与 lockfile
|
|
15
|
+
- **按 Agent 开关**：`config.yaml` 里的 skill × Agent 矩阵 + symlink 同步引擎；TUI 矩阵可视化切换
|
|
16
|
+
- **一处更新**：git 来源 skill 的 `update / --check`，原位替换、无需重连
|
|
17
|
+
- **收编（adopt）**：一键迁移散落在各 Agent 目录里的既有 skill，拷贝 / 移动两种模式
|
|
18
|
+
- **安全**：`lint` 安装前扫描（frontmatter 完整性 + 脚本高危模式）、默认最小暴露、台账化安全卸载
|
|
19
|
+
- **MCP bridge**：任何支持 MCP 的 Agent 都能消费中央仓库，同样受开关矩阵约束
|
|
20
|
+
- **doctor 体检**：断链 / 漂移 / 同名遮蔽 / 孤儿链接，`--fix` 自动修复
|
|
21
|
+
|
|
22
|
+
## 工作原理
|
|
23
|
+
|
|
24
|
+
```
|
|
25
|
+
~/.skillpot/
|
|
26
|
+
├── skills/<name>/SKILL.md # 中央仓库：唯一真身（自包含，symlink 已解引用）
|
|
27
|
+
├── config.yaml # 来源/版本/校验和 + skill×Agent 开关矩阵
|
|
28
|
+
├── state.json # 本工具创建的链接台账（卸载只动台账内文件）
|
|
29
|
+
└── skillspot.lock.json # 机器可读快照（团队共享/审计用）
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
`enable` 在目标 Agent 的用户级 skills 目录创建指向中央仓库的 **symlink**（Agent 启动扫描目录时即被发现）；`disable` 撤下该 symlink。只动台账内的链接，绝不碰用户自建内容；遇到真实同名目录一律跳过并告警。
|
|
33
|
+
|
|
34
|
+
## 快速开始
|
|
35
|
+
|
|
36
|
+
要求 Node ≥ 18。
|
|
37
|
+
|
|
38
|
+
**安装 skillpot 本体**（三选一）：
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
npm install -g @tec-explorer/skillpot # npm registry 安装（tec-explorer 组织 scope）；短别名 spot，或免安装 npx @tec-explorer/skillpot
|
|
42
|
+
npm install -g github:tec-explorer/skillpot # GitHub 直装（安装时自动构建，无需等 npm 发布）
|
|
43
|
+
npx github:tec-explorer/skillpot init # 免安装直接运行
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
**常用命令**：
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
skillpot init # 初始化 ~/.skillpot 并检测本机 Agent
|
|
50
|
+
# （仓库为空时会扫描各 Agent 已有 skill，交互询问是否移入）
|
|
51
|
+
skillpot adopt --dry-run # 预览：各 Agent 目录下有哪些 skill 可收编
|
|
52
|
+
skillpot adopt --move # 收编并以移动模式部署（原目录替换为 symlink）
|
|
53
|
+
spot tui # 交互式开关矩阵：↑↓←→ 移动，空格切换，a 整行
|
|
54
|
+
skillpot add ~/path/to/my-skill # 安装新 skill（默认不对任何 Agent 开放）
|
|
55
|
+
skillpot enable my-skill --for claude-code,zcode
|
|
56
|
+
skillpot doctor # 体检：断链/漂移/同名冲突
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
> Agent 在会话启动时扫描 skill 目录，enable/disable 后重启示例会话生效。
|
|
60
|
+
|
|
61
|
+
**安装 skill 来源**：`skillpot add https://github.com/owner/skills.git#subdir`（浅克隆，`#` 后定位子目录；也支持 `file://` 本地仓库）。
|
|
62
|
+
|
|
63
|
+
**从源码运行**（开发模式）：clone 后 `npm install`（自动构建），再 `npm link` 即可全局使用 `skillpot`。
|
|
64
|
+
|
|
65
|
+
## 命令
|
|
66
|
+
|
|
67
|
+
| 命令 | 说明 |
|
|
68
|
+
|---|---|
|
|
69
|
+
| `init` | 初始化中央仓库 + Agent 检测（空仓库时触发收编提醒） |
|
|
70
|
+
| `agents [--json]` | 检测本机编程 Agent（PATH 二进制 + 配置目录指纹） |
|
|
71
|
+
| `add <dir\|git[#subdir]> [-n 名字]` | 安装 skill（自动 lint） |
|
|
72
|
+
| `list [-a agent]` | 开关矩阵 / 某 Agent 的可见列表 |
|
|
73
|
+
| `enable <skill> -f a,b\|all` | 开放（建 symlink） |
|
|
74
|
+
| `disable <skill> -f a,b\|all` | 关闭（撤 symlink） |
|
|
75
|
+
| `adopt [--from agents] [-f agents] [--move] [--dry-run]` | 收编已有 skill；`--move` 移动模式 |
|
|
76
|
+
| `remove <skill>` | 卸载（撤下所有链接 + 删除文件） |
|
|
77
|
+
| `doctor [--fix]` | 体检与自动修复 |
|
|
78
|
+
| `lint [skill] [--strict]` | 安全与质量检查：frontmatter + 脚本高危模式 |
|
|
79
|
+
| `update [skill] [--check]` | 检查/应用 git 来源 skill 的更新 |
|
|
80
|
+
| `mcp` | 以 MCP server (stdio) 运行，供支持 MCP 的 Agent 消费 |
|
|
81
|
+
| `tui [--once]` | 交互式开关矩阵；无 TTY 自动降级静态输出 |
|
|
82
|
+
|
|
83
|
+
## 支持的 Agent
|
|
84
|
+
|
|
85
|
+
| Agent | 用户级 skills 目录 | 验证依据 |
|
|
86
|
+
|---|---|---|
|
|
87
|
+
| Claude Code | `~/.claude/skills` | live 实测（symlink 探针经 `claude -p` 确认） |
|
|
88
|
+
| ZCode | `~/.zcode/skills` | 官方配置文档 |
|
|
89
|
+
| Codex CLI | `~/.codex/skills` | 同规范样例确认（`.system` 内置 skill） |
|
|
90
|
+
| OpenCode | `~/.config/opencode/skill` | 官方文档，待实机确认 |
|
|
91
|
+
| Gemini CLI | `~/.gemini/skills` | 官方支持 Agent Skills，待实机确认 |
|
|
92
|
+
|
|
93
|
+
其他支持 MCP 的 Agent（Cursor、Qoder、私有 harness…）可走 [MCP bridge](#mcp-bridgec-档兜底)。新增适配器方法见 [docs/design/agent-adapters.md](./docs/design/agent-adapters.md)。
|
|
94
|
+
|
|
95
|
+
## MCP bridge（C 档兜底）
|
|
96
|
+
|
|
97
|
+
无原生 skills 目录的 Agent 可通过 MCP 消费中央仓库：把 `skillpot mcp`（stdio）注册为其 MCP server，即获得 `skillpot_list / skillpot_read / skillpot_search` 三个工具；用 `SKILLPOT_AGENT=<agentId>` 环境变量或 `agent` 参数按开关矩阵过滤，`disable` 对 MCP 通道同样即时生效。设计说明见 [docs/design/mcp-bridge.md](./docs/design/mcp-bridge.md)。
|
|
98
|
+
|
|
99
|
+
## 安全
|
|
100
|
+
|
|
101
|
+
Skill 是注入模型上下文的指令 + 可携带可执行脚本。SkillPot 的默认安全姿态：
|
|
102
|
+
|
|
103
|
+
- `add` / `adopt` 之后**不开放给任何 Agent**，由用户显式选择
|
|
104
|
+
- 安装时自动 `lint`：frontmatter 完整性、脚本高危模式（`rm -rf`、`curl|sh`、`sudo`…）
|
|
105
|
+
- 卸载/禁用只动 `state.json` 台账内的链接，绝不触碰用户自建内容
|
|
106
|
+
- 拷贝解引用 symlink，仓库自包含，不依赖来源机器的链接目标
|
|
107
|
+
|
|
108
|
+
漏洞报告请走 [SECURITY.md](./SECURITY.md)，勿用公开 Issue。
|
|
109
|
+
|
|
110
|
+
## 常见问题
|
|
111
|
+
|
|
112
|
+
**为什么用 symlink 而不是复制到每个 Agent？**
|
|
113
|
+
复制会产生 56 份副本，更新与关闭都不可控。symlink 只有一份真身：`disable` 即撤链接，`update` 原位替换即全部生效。
|
|
114
|
+
|
|
115
|
+
**Windows 支持吗？**
|
|
116
|
+
符号链接在 Windows 需要开发者模式或管理员权限，目前未测试，欢迎 PR。
|
|
117
|
+
|
|
118
|
+
**和 skill registry（skills.sh 等）是什么关系？**
|
|
119
|
+
Registry 解决"从哪找 skill"，SkillPot 解决"装到哪、给谁用、怎么停、怎么更新"——管理层。两者互补，registry 可作为 `add` 的上游来源。
|
|
120
|
+
|
|
121
|
+
## 开发
|
|
122
|
+
|
|
123
|
+
```bash
|
|
124
|
+
npm install
|
|
125
|
+
npm test # vitest 单元测试（沙箱隔离，不碰真实 HOME）
|
|
126
|
+
npm run test:e2e # 沙箱端到端冒烟
|
|
127
|
+
npm run build # tsc 类型检查 + esbuild 打包为单文件 ESM（dist/cli.mjs，含 TUI）
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
测试与沙箱通过 `SKILLPOT_HOME` / `SKILLPOT_AGENT_HOME` 环境变量隔离。贡献流程见 [CONTRIBUTING.md](./CONTRIBUTING.md)。
|
|
131
|
+
|
|
132
|
+
## 文档
|
|
133
|
+
|
|
134
|
+
全部文档在 [docs/](./docs/README.md)（索引）：[产品规划](./docs/product/product-plan.md) ｜ [设计：适配器与落地策略](./docs/design/agent-adapters.md) ｜ [设计：MCP bridge](./docs/design/mcp-bridge.md) ｜ [里程碑执行报告](./docs/reports/) ｜ [CHANGELOG](./CHANGELOG.md)
|
|
135
|
+
|
|
136
|
+
## 贡献
|
|
137
|
+
|
|
138
|
+
Issue / PR 均欢迎，流程见 [CONTRIBUTING.md](./CONTRIBUTING.md)，行为准则见 [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)。
|
|
139
|
+
|
|
140
|
+
## License
|
|
141
|
+
|
|
142
|
+
[MIT](./LICENSE)
|