# https://github.com/avivsinai/skills-marketplace 项目说明书
生成时间：2026-06-01 06:44:48 UTC
## 目录
- [项目介绍](#page-intro)
- [快速开始](#page-quickstart)
- [系统架构](#page-arch)
- [插件注册表](#page-registry)
- [插件列表](#page-plugin-list)
- [AMQ插件详解](#page-amq)
- [Langfuse插件详解](#page-langfuse)
- [开发工具插件](#page-devtools)
- [贡献指南](#page-contributing)
- [插件开发规范](#page-plugin-dev)
## 项目介绍
### 相关页面
相关主题：[系统架构](#page-arch), [快速开始](#page-quickstart)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/avivsinai/skills-marketplace/blob/main/README.md)
- [registry/plugins.json](https://github.com/avivsinai/skills-marketplace/blob/main/registry/plugins.json)
- [plugins/amq-cli/skills/amq-cli/references/message-format.md](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/amq-cli/skills/amq-cli/references/message-format.md)
- [plugins/amq-spec/skills/amq-spec/SKILL.md](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/amq-spec/skills/amq-spec/SKILL.md)
- [plugins/shaon/skills/shaon/SKILL.md](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/shaon/skills/shaon/SKILL.md)
- [plugins/langfuse/skills/langfuse/references/tool-reference.md](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/langfuse/skills/langfuse/references/tool-reference.md)
# 项目介绍
## 概述
Skills Marketplace 是一个面向 AI 代理工具的插件市场平台，旨在为 Claude Code 和 Codex CLI 提供可扩展的技能（Skills）生态系统。该项目遵循 [Agent Skills 规范](https://agentskills.io/specification)，确保与多种 Agent Skills 兼容工具的互操作性。
资料来源：[README.md:1-10]()
## 核心定位
该市场平台充当插件注册中心（registry），聚合来自不同来源的插件，并为 Claude Code 和 Codex CLI 用户提供统一的安装和管理体验。
资料来源：[README.md:1-5]()
## 架构设计
### 目录结构
```mermaid
graph TD
A[skills-marketplace] --> B[registry/]
A --> C[plugins/]
A --> D[scripts/]
B --> E[plugins.json]
C --> F[plugin-a/]
C --> G[plugin-b/]
F --> H[SKILL.md]
F --> I[rules/]
F --> J[references/]
F --> K[plugin.json]
```
项目的核心目录结构说明：
| 目录 | 用途 |
|------|------|
| `registry/` | 插件注册表，包含 `plugins.json` 主配置 |
| `plugins/` | 本地插件包，Codex 使用本地 bundle |
| `scripts/` | 工具脚本，如 `generate-manifests.py` |
资料来源：[README.md:15-20]()
### 插件清单机制
插件清单（Manifest）通过 `scripts/generate-manifests.py` 脚本生成，生成的 marketplace catalog 直接指向 GitHub 固定引用（pinned refs）。
```mermaid
graph LR
A[GitHub Repo] --> B[generate-manifests.py]
B --> C[Marketplace Catalog]
C --> D[Claude Code]
C --> E[Codex CLI]
```
资料来源：[README.md:10-15]()
## 插件系统
### 插件结构
每个插件必须包含以下核心文件：
| 文件/目录 | 必需 | 说明 |
|-----------|------|------|
| `.claude-plugin/plugin.json` | 是 | Claude Code 插件清单 |
| `.codex-plugin/plugin.json` | 否 | Codex 插件清单（可选） |
| `plugin.json` | 是 | Codex 插件清单（位于根目录） |
| `skills/` | 是 | 共享技能负载目录 |
资料来源：[README.md:15-20]()
### 插件配置示例
`registry/plugins.json` 中定义的插件条目包含以下字段：
```json
{
"name": "israel-services",
"description": "Access Israeli citizen services...",
"repository": "https://github.com/avivsinai/israel-services",
"source": {
"source": "github",
"repo": "avivsinai/israel-services",
"ref": "main",
"sha": "ce0cd9b5ddceb56dd8f458e20cc93880f5a0ef3d"
},
"version": "ce0cd9b5ddce",
"keywords": ["israel", "health", "banking", "clalit", "poalim"],
"category": "Automation",
"policy": {
"installation": "AVAILABLE",
"authentication": "ON_FIRST_USE"
},
"sync": {
"mode": "main"
}
}
```
资料来源：[registry/plugins.json:50-80]()
### 插件分类
插件按功能领域分类：
| 分类 | 说明 |
|------|------|
| AI Tools | AI 和 LLM 相关工具 |
| Automation | 自动化服务集成 |
| (其他) | 详见 `registry/plugins.json` |
资料来源：[registry/plugins.json:20-45]()
## 技能（Skills）结构
### 技能文档类型
| 类型 | 用途 |
|------|------|
| `SKILL.md` | 技能主文档，定义使用方式和工作流 |
| `references/` | 参考文档，包含 API 引用、工具说明 |
| `rules/` | 规则文档，定义命令行为和输出格式 |
资料来源：[plugins/amq-spec/skills/amq-spec/SKILL.md:1-10]()
### 消息格式规范
AMQ 消息采用 Markdown 文件格式，包含 JSON frontmatter 头部：
```text
---json
{
"schema": 1,
"id": "",
"from": "claude",
"to": ["codex"],
"thread": "p2p/claude__codex",
"subject": "Optional summary",
"kind": "question",
"labels": ["bug", "parser"]
}
---
```
| 字段 | 类型 | 说明 |
|------|------|------|
| `schema` | integer | 模式版本（当前为 1） |
| `id` | string | 全局唯一消息 ID |
| `from` | string | 发送者标识 |
| `to` | array | 接收者列表 |
| `thread` | string | 线程 ID（p2p 格式：`p2p/__`） |
| `kind` | string | 消息类型（如 `review_request`、`brainstorm`） |
| `labels` | array | 标签列表 |
资料来源：[plugins/amq-cli/skills/amq-cli/references/message-format.md:1-30]()
## 自动同步机制
### 同步模式
```mermaid
graph TD
A[主模式插件
registry/plugins.json] --> B[.github/workflows/
sync-releases.yml]
C[子仓库推送] --> D[plugin-update 事件]
D --> B
B --> E[更新 plugins.json]
B --> F[重新生成清单]
F --> G[提交到 main]
```
### 同步规则
| 同步模式 | 行为 |
|----------|------|
| `main` | 自动同步到主分支最新提交 |
| `manual` | 手动同步，需显式更新注册表 |
资料来源：[README.md:25-35]()
### 同步触发条件
1. **事件触发**：子仓库在默认分支推送时触发 `plugin-update` 事件
2. **每周回退同步**：marketplace 执行每周自动同步
3. **手动运行**：支持手动触发同步工作流
资料来源：[README.md:25-30]()
## 工作流规范
### 规范工作流（Spec Workflow）
协作式规范工作流用于多代理设计任务，包含以下阶段：
| 阶段 | 执行者 | 说明 |
|------|--------|------|
| 1. Research | 双方并行 | 独立研究并提交发现 |
| 2. Discuss | 双方 | 讨论差异、对齐架构 |
| 3. Draft | 主代理 | 起草计划 |
| 4. Review | 伙伴代理 | 审查反馈 |
| 5. Present | 主代理 | 向用户展示并等待批准 |
| 6. Execute | 主代理 | 获得批准后执行 |
资料来源：[plugins/amq-spec/skills/amq-spec/SKILL.md:1-20]()
### 消息标签系统
| 阶段标签 | 用途 |
|----------|------|
| `workflow:spec,phase:request` | 问题请求 |
| `workflow:spec,phase:research` | 研究发现 |
| `workflow:spec,phase:discuss` | 讨论分析 |
| `workflow:spec,phase:draft` | 计划草案 |
| `workflow:spec,phase:review` | 审查反馈 |
| `workflow:spec,phase:decision` | 最终决定 |
资料来源：[plugins/amq-spec/skills/amq-spec/references/spec-workflow.md:1-30]()
## 添加新插件
### 前置要求
1. 仓库必须包含 `.claude-plugin/plugin.json`
2. 如需 Codex 支持，还需包含 `.codex-plugin/plugin.json`
3. 插件需符合 Agent Skills 规范
资料来源：[README.md:40-45]()
### 添加流程
```mermaid
graph LR
A[创建插件清单] --> B[添加 entry 到 registry/plugins.json]
B --> C[运行 generate-manifests.py]
C --> D[提交 PR]
D --> E[审核与合并]
```
### 具体步骤
| 步骤 | 命令/操作 |
|------|-----------|
| 1 | 确保仓库有正确的 `plugin.json` |
| 2 | 添加插件条目到 `registry/plugins.json` |
| 3 | 执行 `python3 scripts/generate-manifests.py` |
| 4 | 提交 PR，包含更新的注册表和生成的清单 |
资料来源：[README.md:40-48]()
## 标准与兼容性
### Agent Skills 规范
所有插件遵循 [Agent Skills 规范](https://agentskills.io/specification)，确保与以下工具兼容：
| 工具 | 兼容性 |
|------|--------|
| Claude Code | 完全支持 |
| Codex CLI | 完全支持 |
| 其他 Agent Skills 工具 | 兼容 |
资料来源：[README.md:50-55]()
### 工具链支持
Marketplace 中的技能支持多种工具链集成：
| 工具链 | 功能 |
|--------|------|
| Langfuse | 追踪、可观测性、评分 |
| Bitbucket (bkt) | 构建状态、流水线、Webhook |
| Jenkins (jk) | 测试报告 |
| AMQ | 消息传递、规范工作流 |
资料来源：[plugins/langfuse/skills/langfuse/references/tool-reference.md:1-15]()
## 许可证
本项目采用 MIT 许可证授权。
资料来源：[README.md:57-60]()
## 相关文档
- [贡献指南](./CONTRIBUTING.md) - 详细的插件开发指南
- [Agent Skills 规范](https://agentskills.io/specification) - 官方规范文档
- [registry/plugins.json](./registry/plugins.json) - 插件注册表
---
## 快速开始
### 相关页面
相关主题：[项目介绍](#page-intro), [插件列表](#page-plugin-list)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/avivsinai/skills-marketplace/blob/main/README.md)
- [plugins/amq-cli/skills/amq-cli/references/message-format.md](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/amq-cli/skills/amq-cli/references/message-format.md)
- [plugins/amq-cli/skills/amq-spec/references/spec-workflow.md](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/amq-cli/skills/amq-spec/references/spec-workflow.md)
- [plugins/langfuse/skills/langfuse/references/tool-reference.md](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/langfuse/skills/langfuse/references/tool-reference.md)
- [plugins/bkt/skills/bkt/rules/status.md](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/bkt/skills/bkt/rules/status.md)
- [plugins/jk/skills/jk/rules/run.md](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/jk/skills/jk/rules/run.md)
# 快速开始
本页面帮助新用户快速上手 skills-marketplace（技能市场），了解如何安装、配置和使用平台中的各类插件技能。
## 什么是 Skills Marketplace
Skills Marketplace 是一个基于 Agent Skills 规范的插件市场，为 Claude Code、Codex CLI 等 Agent 工具提供可扩展的技能集合。每个插件都包含一组预定义的命令、参考文档和工作流程，帮助用户完成特定领域的任务。
资料来源：[README.md:1-5]()
## 核心概念
### 插件架构
插件采用标准化的目录结构，包含技能定义、命令规则和参考文档：
```
plugins/
├── plugin.json # Codex 插件清单
└── skills/
└── ... # 共享技能负载
```
资料来源：[README.md:18-22]()
### 工作流程标签系统
平台使用标准 AMQ 消息格式，通过标签（labels）区分不同阶段的工作流程：
```text
workflow:spec,phase:research # 研究阶段
workflow:spec,phase:discuss # 讨论阶段
workflow:spec,phase:draft # 起草阶段
workflow:spec,phase:review # 审查阶段
```
资料来源：[plugins/amq-cli/skills/amq-cli/references/message-format.md:18-20]()
## 快速安装
### 前置要求
| 要求 | 说明 |
|------|------|
| Claude Code 或 Codex CLI | 支持 Agent Skills 的客户端 |
| Git | 用于克隆和更新插件 |
### 安装步骤
1. **克隆仓库**
```bash
git clone https://github.com/avivsinai/skills-marketplace.git
cd skills-marketplace
```
2. **查看可用插件**
查看 `registry/plugins.json` 文件获取所有可用插件列表。
3. **配置插件**
对于 Claude Code，生成的市场目录直接指向固定的 GitHub 引用。资料来源：[README.md:24-25]()
## 常用插件速查
### AMQ 通信插件
用于多 Agent 之间异步通信和协作设计。
**发送消息示例：**
```bash
amq send --to --kind brainstorm \
--labels workflow:spec,phase:research \
--thread spec/ --subject "Research: " \
--body ""
```
资料来源：[plugins/amq-cli/skills/amq-spec/references/spec-workflow.md:12-16]()
**查看线程：**
```bash
amq thread --id spec/ --include-body
```
**监听消息：**
```bash
amq watch --timeout 120s
```
### Bitbucket 插件 (bkt)
检查构建状态和 CI 结果。
| 子命令 | 功能 |
|--------|------|
| `bkt status commit ` | 显示提交的构建状态 |
| `bkt status pr ` | 显示 PR 的构建状态 |
| `bkt status pipeline ` | 显示 Cloud 管道状态 |
| `bkt status rate-limit` | 显示 API 速率限制 |
资料来源：[plugins/bkt/skills/bkt/rules/status.md:4-18]()
**示例：**
```bash
# 显示提交状态
bkt status commit abc1234def5678
# 以 JSON 格式输出
bkt status commit abc1234 --format json
```
### Jenkins 插件 (jk)
与 Jenkins CI 系统交互。
| 子命令 | 功能 |
|--------|------|
| `jk run ls` | 列出最近的运行 |
| `jk run start` | 触发作业运行 |
| `jk run view` | 查看运行详情 |
| `jk queue ls` | 列出队列项 |
| `jk test report` | 显示聚合测试结果 |
资料来源：[plugins/jk/skills/jk/rules/run.md:4-11]()
**示例：**
```bash
# 搜索作业
jk run search --filter "deploy"
# 启动作业并跟踪
jk run start --follow
```
### Langfuse 插件
用于 LLM 应用的可观测性和提示管理。
**追踪工具：**
| 工具 | 功能 |
|------|------|
| `fetch_traces` | 获取追踪列表 |
| `fetch_trace` | 获取单个追踪详情 |
| `find_exceptions` | 查找异常 |
**提示管理：**
| 工具 | 功能 |
|------|------|
| `list_prompts` | 列出提示 |
| `create_text_prompt` | 创建文本提示 |
| `get_prompt` | 获取提示详情 |
资料来源：[plugins/langfuse/skills/langfuse/references/tool-reference.md:1-45]()
## 协作设计工作流程
当使用多 Agent 进行协作设计时，遵循标准化的六阶段流程：
```mermaid
graph TD
A[1. 研究阶段
Research] --> B[2. 讨论阶段
Discuss]
B --> C[3. 起草阶段
Draft]
C --> D[4. 审查阶段
Review]
D --> E[5. 呈现阶段
Present]
E --> F[6. 执行阶段
Execute]
A -->|并行研究| A1[发起方研究]
A -->|并行研究| A2[接收方研究]
```
### 禁止事项
- 独自研究后直接发送完整方案给搭档
- 跳过讨论阶段
- 在用户批准前实施
资料来源：[plugins/amq-cli/skills/amq-spec/references/spec-workflow.md:45-60]()
## 添加新插件
如需为市场贡献新插件，按以下步骤操作：
| 步骤 | 操作 |
|------|------|
| 1 | 确保仓库包含 `.claude-plugin/plugin.json` 和 `.codex-plugin/plugin.json` |
| 2 | 在 `registry/plugins.json` 中添加插件条目 |
| 3 | 运行 `python3 scripts/generate-manifests.py` |
| 4 | 提交包含更新清单的 PR |
资料来源：[README.md:30-37]()
## 同步机制
平台采用多层次自动同步策略：
```mermaid
graph LR
A[主插件
registry/plugins.json] --> B[GitHub Actions
sync-releases.yml]
B --> C{检查更新}
C -->|有新版本| D[更新清单
提交到 main]
C -->|无更新| E[保持当前版本]
```
- 主模式插件由 `.github/workflows/sync-releases.yml` 检查
- 子仓库在默认分支推送时派发 `plugin-update` 事件
- 市场每周进行备用同步
资料来源：[README.md:24-33]()
## 输出格式
大多数工具支持多种输出格式：
| 格式 | 说明 |
|------|------|
| `compact` | 摘要模式，大值被截断（默认） |
| `full_json_string` | 完整 JSON 字符串 |
| `full_json_file` | 保存到文件，返回摘要和路径 |
资料来源：[plugins/langfuse/skills/langfuse/references/tool-reference.md:47-53]()
## 下一步
- 浏览 `plugins/` 目录了解所有可用技能
- 查看 CONTRIBUTING.md 了解贡献指南
- 访问 [Agent Skills 规范](https://agentskills.io/specification) 了解技术标准
---
## 系统架构
### 相关页面
相关主题：[插件注册表](#page-registry)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/avivsinai/skills-marketplace/blob/main/README.md)
- [registry/plugins.json](https://github.com/avivsinai/skills-marketplace/blob/main/registry/plugins.json)
- [plugins/amq-cli/skills/amq-cli/references/message-format.md](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/amq-cli/skills/amq-cli/references/message-format.md)
- [plugins/amq-spec/skills/amq-spec/SKILL.md](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/amq-spec/skills/amq-spec/SKILL.md)
- [plugins/langfuse/skills/langfuse/references/tool-reference.md](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/langfuse/skills/langfuse/references/tool-reference.md)
# 系统架构
## 概述
Skills Marketplace 是一个插件市场仓库，用于托管和分发 Agent Skills 兼容的插件。该项目为 Claude Code 和 Codex CLI 等 Agent Skills 兼容工具提供统一的插件分发机制。
资料来源：[README.md:1-10]()
## 核心架构组件
### 1. 仓库结构
项目采用标准化的目录结构，将插件代码与市场配置分离：
| 目录/文件 | 说明 |
|-----------|------|
| `registry/plugins.json` | 插件注册表，包含所有可用插件的元数据 |
| `plugins/` | 各插件的本地代码包 |
| `.github/workflows/sync-releases.yml` | 自动同步工作流 |
| `scripts/generate-manifests.py` | 清单生成脚本 |
资料来源：[README.md:30-40]()
### 2. 插件组织结构
每个插件在仓库中遵循统一目录结构：
```
plugins/
└── /
└── skills/
└── /
├── SKILL.md # 技能定义
├── references/ # 参考文档
│ └── tool-reference.md
└── rules/ # 规则定义
└── status.md
```
资料来源：[README.md:25-30]()
## 插件注册机制
### registry/plugins.json 结构
注册表是插件市场的核心数据源，记录每个插件的引用信息：
| 字段 | 类型 | 说明 |
|------|------|------|
| `name` | string | 插件名称 |
| `repo` | string | GitHub 仓库地址 |
| `ref` | string | Git 引用 (分支/标签/Commit) |
| `sync.mode` | string | 同步模式 (`auto` 或 `manual`) |
资料来源：[README.md:50-60]()
## 自动同步机制
### 工作流程架构
```mermaid
graph TD
A[插件仓库推送] --> B{sync.mode 判断}
B -->|auto| C[dispatch plugin-update 事件]
B -->|manual| D[等待手动触发]
C --> E[marketplace 接收事件]
E --> F[更新 registry/plugins.json]
F --> G[重新生成清单文件]
G --> H[提交到 main 分支]
I[每周定时同步] --> A
J[手动运行工作流] --> A
```
### 同步模式
| 模式 | 说明 | 触发方式 |
|------|------|----------|
| `auto` | 主模式插件自动同步 | 仓库推送 / 定时任务 / 手动运行 |
| `manual` | 手动模式保持固定版本 | 需显式更新注册表 |
资料来源：[README.md:42-48]()
## 技能系统架构
### Agent Skills 规范
所有插件遵循 [Agent Skills 规范](https://agentskills.io/specification)，确保跨工具兼容性：
```mermaid
graph LR
A[Claude Code] <-->|Agent Skills| B[skills-marketplace]
A <-->|Agent Skills| C[Codex CLI]
B --> D[插件市场分发]
C --> D
```
### 技能组成
| 组件 | 说明 |
|------|------|
| `SKILL.md` | 技能主定义文件 |
| `references/` | 工具参考文档 |
| `rules/` | 命令规则和参数定义 |
## 消息传递架构
某些插件（如 amq-cli、amq-spec）使用 AMQ 消息系统进行代理间通信。
### 消息格式
```mermaid
graph LR
A[发送方] -->|JSON Frontmatter| B[Markdown Body]
A --> C[消息元数据]
C -->|schema| D[版本号]
C -->|id| E[唯一标识]
C -->|from/to| F[路由信息]
C -->|thread| G[会话线程]
C -->|kind| H[消息类型]
C -->|labels| I[标签分类]
```
### 消息字段说明
| 字段 | 必填 | 说明 |
|------|------|------|
| `schema` | 是 | 整数模式版本（当前为1） |
| `id` | 是 | 全局唯一消息ID |
| `from` | 是 | 发送方标识 |
| `to` | 是 | 接收方标识列表 |
| `thread` | 是 | 线程ID字符串 |
| `kind` | 否 | 消息类型 |
| `labels` | 否 | 标签列表 |
| `priority` | 否 | 优先级 |
资料来源：[plugins/amq-cli/skills/amq-cli/references/message-format.md:1-30]()
## 协作工作流
### Spec 工作流阶段
amq-spec 技能实现了多代理协作设计协议：
```mermaid
graph TD
A[Phase 1: Research] -->|并行研究| B[交换研究成果]
B --> C[Phase 2: Discuss]
C -->|ping-pong 讨论| D[达成共识]
D --> E[Phase 3: Draft]
E -->|主代理起草| F[Phase 4: Review]
F -->|合作伙伴审查| G[Phase 5: Present]
G -->|用户批准| H[Phase 6: Execute]
```
### 工作流阶段表
| 阶段 | 执行者 | 说明 |
|------|--------|------|
| Research | 双代理并行 | 独立研究并提交发现 |
| Discuss | 双代理 | 读取对方发现并对齐 |
| Draft | 主代理 | 起草实现方案 |
| Review | 合作伙伴 | 审查并反馈 |
| Present | - | 呈现给用户批准 |
| Execute | - | 用户批准后执行 |
资料来源：[plugins/amq-spec/skills/amq-spec/SKILL.md:1-25]()
## 插件添加流程
### 添加新插件步骤
```mermaid
graph LR
A[创建 plugin.json] --> B[添加 registry 入口]
B --> C[运行生成脚本]
C --> D[提交 PR]
D --> E[合并到 main]
E --> F[自动同步分发]
```
1. 确保仓库包含 `.claude-plugin/plugin.json`
2. 添加插件条目到 `registry/plugins.json`
3. 运行 `python3 scripts/generate-manifests.py`
4. 提交 PR 并等待合并
资料来源：[README.md:52-58]()
## 数据模型
### MCP 工具分类
以 langfuse 插件为例，工具按功能分类：
| 分类 | 工具 |
|------|------|
| Traces | fetch_traces, fetch_trace |
| Observations | fetch_observations, fetch_observation |
| Sessions | fetch_sessions, get_session_details |
| Exceptions | find_exceptions, find_exceptions_in_file |
| Prompts | list_prompts, get_prompt, create_text_prompt* |
| Datasets | list_datasets, get_dataset, create_dataset* |
| Annotation Queues | list_annotation_queues, create_annotation_queue |
| Scores | list_scores_v2, get_score_v2 |
*注：标有 * 的工具在只读模式下禁用。*
资料来源：[plugins/langfuse/skills/langfuse/references/tool-reference.md:1-35]()
## 技术标准
### Agent Skills 兼容性要求
所有插件必须符合 Agent Skills 规范：
| 标准项 | 说明 |
|--------|------|
| 清单格式 | 遵循 `.claude-plugin/plugin.json` 规范 |
| Codex 支持 | 可选包含 `.codex-plugin/plugin.json` |
| 版本控制 | 支持 Git 引用（分支/标签/Commit） |
| 同步机制 | 支持 auto-sync 或 manual 模式 |
资料来源：[README.md:60-62]()
## 许可证
本项目采用 MIT 许可证开源。
资料来源：[README.md:65]()
---
## 插件注册表
### 相关页面
相关主题：[系统架构](#page-arch), [贡献指南](#page-contributing), [插件开发规范](#page-plugin-dev)
相关源码文件
以下源码文件用于生成本页说明：
- [registry/plugins.json](https://github.com/avivsinai/skills-marketplace/blob/main/registry/plugins.json)
- [CONTRIBUTING.md](https://github.com/avivsinai/skills-marketplace/blob/main/CONTRIBUTING.md)
- [README.md](https://github.com/avivsinai/skills-marketplace/blob/main/README.md)
- [.github/workflows/sync-releases.yml](https://github.com/avivsinai/skills-marketplace/blob/main/.github/workflows/sync-releases.yml)
- [scripts/generate-manifests.py](https://github.com/avivsinai/skills-marketplace/blob/main/scripts/generate-manifests.py)
# 插件注册表
## 概述
插件注册表是 skills-marketplace 项目的核心组件，负责管理和维护所有插件的元数据信息。该注册表以 JSON 格式存储于 `registry/plugins.json` 文件中，为 Claude Code 和 Codex CLI 等 Agent Skills 兼容工具提供插件目录服务。
资料来源：[README.md:1-10]()
### 核心职责
| 职责 | 描述 |
|------|------|
| 元数据存储 | 集中管理所有插件的基本信息和版本锁定 |
| 自动同步 | 监测插件仓库变化，自动更新注册表 |
| 清单生成 | 为不同平台（Claude Code、Codex）生成适配的插件清单 |
| 版本控制 | 记录每个插件的 GitHub 固定引用（pinned ref） |
资料来源：[README.md:15-25]()
---
## 架构设计
### 整体架构
```mermaid
graph TD
A[插件仓库] -->|plugin-update 事件| B[sync-releases.yml 工作流]
B --> C{同步模式}
C -->|自动模式| D[更新 registry/plugins.json]
C -->|手动模式| E[保持固定版本]
D --> F[generate-manifests.py]
F --> G[生成插件清单]
G --> H[推送到 main 分支]
H --> I[Marketplace 目录]
J[主模式插件] -->|每周| K[备用同步检查]
K --> B
```
### 组件关系
```mermaid
graph LR
A[.claude-plugin/plugin.json] -->|必需| I[插件清单]
B[.codex-plugin/plugin.json] -->|必需| I
C[registry/plugins.json] -->|注册表| D[Marketplace]
E[sync-releases.yml] -->|自动同步| C
F[generate-manifests.py] -->|生成| D
```
资料来源：[README.md:20-35]()
---
## 注册表文件结构
### plugins.json 结构
注册表文件采用 JSON 格式，主要包含插件数组，每个插件条目包含以下关键字段：
| 字段 | 类型 | 描述 |
|------|------|------|
| `name` | string | 插件名称 |
| `repo` | string | GitHub 仓库路径 |
| `pinned_ref` | string | 固定的 Git 引用（分支/标签/提交） |
| `sync_mode` | string | 同步模式：`auto` 或 `manual` |
| `codex_bundle` | string | Codex CLI 的本地包路径 |
| `metadata` | object | 额外的插件元数据 |
资料来源：[registry/plugins.json:1-50]()
### 同步模式
```mermaid
stateDiagram-v2
[*] --> 自动同步: sync.mode: auto
[*] --> 手动模式: sync.mode: manual
自动同步 --> 检测变更: 仓库推送
检测变更 --> 更新注册表: HEAD 变化
更新注册表 --> 重新生成清单
重新生成清单 --> 提交到 main
手动模式 --> 保持固定版本: 等待手动更新
保持固定版本 --> 更新注册表: 手动触发
```
---
## 添加新插件流程
### 完整工作流
```mermaid
graph LR
A[准备插件文件] --> B[创建 plugin.json]
B --> C[添加条目到 registry]
C --> D[运行生成脚本]
D --> E[提交 PR]
E --> F[合并后自动同步]
```
### 详细步骤
| 步骤 | 操作 | 说明 |
|------|------|------|
| 1 | 创建 `.claude-plugin/plugin.json` | Claude Code 插件清单定义 |
| 2 | 创建 `.codex-plugin/plugin.json` | Codex CLI 插件清单定义（可选但推荐） |
| 3 | 添加条目到 `registry/plugins.json` | 在插件数组中新增条目 |
| 4 | 运行生成脚本 | 执行 `python3 scripts/generate-manifests.py` |
| 5 | 提交 Pull Request | 提交更新的注册表和生成的清单文件 |
资料来源：[CONTRIBUTING.md:1-20]()
### 插件清单要求
插件仓库必须包含以下文件才能被 marketplace 接受：
```
my-plugin-repo/
├── .claude-plugin/
│ └── plugin.json # Claude Code 插件清单（必需）
├── .codex-plugin/
│ └── plugin.json # Codex 插件清单（可选但推荐）
└── skills/
└── ... # 共享的技能负载
```
资料来源：[README.md:40-50]()
---
## 自动同步机制
### 同步触发条件
```mermaid
graph TD
A[仓库推送事件] --> B{仓库类型}
B -->|子仓库| C[分发 plugin-update 事件]
B -->|Marketplace| D[接收事件]
C --> D
D --> E{检查 registry/plugins.json}
E --> F{HOST 变化?}
F -->|是| G[更新 plugins.json]
F -->|否| H[跳过]
G --> I[重新生成清单]
I --> J[提交到 main]
```
### 工作流配置
| 配置项 | 值 | 说明 |
|--------|-----|------|
| 触发事件 | `push` 到默认分支 | 任何代码推送都会触发检查 |
| 同步检查 | `.github/workflows/sync-releases.yml` | 主工作流文件 |
| 备用同步 | 每周自动执行 | 确保不会遗漏任何更新 |
资料来源：[README.md:20-30]()
### 同步模式配置
在 `registry/plugins.json` 中可以为每个插件设置不同的同步模式：
```json
{
"name": "my-plugin",
"repo": "user/my-plugin",
"sync": {
"mode": "auto" // 或 "manual"
}
}
```
| 模式 | 行为 |
|------|------|
| `auto` | 自动检测仓库 HEAD 变化并更新注册表 |
| `manual` | 保持固定版本，需要手动触发更新 |
---
## 清单生成
### 生成脚本
脚本 `scripts/generate-manifests.py` 负责将注册表信息转换为各平台所需的格式。
| 输入 | 处理 | 输出 |
|------|------|------|
| `registry/plugins.json` | 解析插件信息 | Claude Code 清单 |
| `plugins/*/bundles/*` | 打包本地资源 | Codex 插件包 |
| GitHub refs | 固定版本 | 版本锁定配置 |
资料来源：[README.md:25-35]()
### 生成流程
```mermaid
graph LR
A[读取 registry/plugins.json] --> B[获取每个插件的 pinned_ref]
B --> C[下载/打包资源]
C --> D[生成 Claude Code 清单]
D --> E[生成 Codex 插件包]
E --> F[更新本地 plugins/ 目录]
F --> G[提交更改]
```
---
## 与 Agent Skills 规范的兼容性
插件注册表确保所有插件符合 [Agent Skills 规范](https://agentskills.io/specification)，实现跨平台兼容：
| 平台 | 支持状态 | 说明 |
|------|----------|------|
| Claude Code | ✅ 完全支持 | marketplace 目录直接指向固定 GitHub 引用 |
| Codex CLI | ✅ 完全支持 | 仓库包含本地生成的插件包 |
| 其他兼容工具 | ✅ 理论上支持 | 遵循统一规范 |
资料来源：[README.md:50-60]()
---
## 最佳实践
### 插件命名规范
- 使用小写字母和连字符
- 避免使用特殊字符
- 保持名称简洁明了
### 版本管理建议
| 场景 | 推荐同步模式 |
|------|--------------|
| 活跃开发的插件 | `auto` |
| 稳定版插件 | `manual` |
| 生产环境使用 | 固定到特定标签 |
### 提交规范
- 每次更新注册表应包含生成的清单文件
- 提交信息应清晰说明变更内容
- 建议关联相关 Issue 或讨论
---
## 相关文件索引
| 文件路径 | 用途 |
|----------|------|
| `registry/plugins.json` | 插件注册表主文件 |
| `CONTRIBUTING.md` | 贡献指南 |
| `README.md` | 项目说明文档 |
| `.github/workflows/sync-releases.yml` | 自动同步工作流 |
| `scripts/generate-manifests.py` | 清单生成脚本 |
| `plugins/` | 本地插件包目录 |
---
## 插件列表
### 相关页面
相关主题：[快速开始](#page-quickstart), [AMQ插件详解](#page-amq), [Langfuse插件详解](#page-langfuse), [开发工具插件](#page-devtools)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/avivsinai/skills-marketplace/blob/main/README.md)
- [registry/plugins.json](https://github.com/avivsinai/skills-marketplace/blob/main/registry/plugins.json)
- [plugins/amq-cli/skills/amq-cli/references/message-format.md](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/amq-cli/skills/amq-cli/references/message-format.md)
- [plugins/langfuse/skills/langfuse/references/tool-reference.md](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/langfuse/skills/langfuse/references/tool-reference.md)
- [plugins/bkt/skills/bkt/rules/status.md](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/bkt/skills/bkt/rules/status.md)
- [plugins/jk/skills/jk/rules/run.md](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/jk/skills/jk/rules/run.md)
# 插件列表
## 概述
插件列表（Plugin List）是 skills-marketplace 仓库的核心组件，定义了所有可用 Agent Skills 插件的元数据、版本信息和同步配置。该仓库作为一个集中化的插件市场，为 Claude Code 和 Codex CLI 提供插件分发服务。
插件市场遵循 [Agent Skills 规范](https://agentskills.io/specification)，确保与多种 Agent Tools 兼容。资料来源：[README.md:1-5]()
## 仓库结构
```
skills-marketplace/
├── registry/
│ ├── plugins.json # 插件注册表（主清单）
│ └── ... # 其他注册相关文件
├── plugins/ # 本地生成的插件包（Codex 使用）
│ ├── amq-cli/ # AMQ CLI 插件
│ ├── amq-spec/ # AMQ 规范插件
│ ├── langfuse/ # Langfuse 追踪插件
│ ├── bkt/ # Bitbucket 插件
│ ├── jk/ # Jenkins 插件
│ └── shaon/ # Hilan 考勤系统插件
├── scripts/
│ └── generate-manifests.py # 清单生成脚本
└── .github/workflows/ # GitHub Actions 工作流
```
## 插件注册机制
### 注册表文件格式
`registry/plugins.json` 是插件市场的主清单文件，包含所有插件的详细配置：
```json
{
"plugins": [
{
"name": "插件名称",
"version": "版本号",
"repo": "GitHub 仓库地址",
"sync": {
"mode": "auto | manual"
}
}
]
}
```
### 插件配置项
| 配置项 | 类型 | 描述 | 可选值 |
|--------|------|------|--------|
| name | string | 插件唯一标识名称 | - |
| version | string | 语义化版本号 | x.y.z |
| repo | string | 插件 GitHub 仓库 URL | - |
| sync.mode | string | 同步模式 | "auto", "manual" |
## 现有插件列表
当前市场中包含以下官方插件：
| 插件名称 | 描述 | 主要功能 |
|----------|------|----------|
| amq-cli | AMQ 命令行接口 | 消息队列通信、P2P 消息交换 |
| amq-spec | AMQ 协作规范 | 多代理设计任务的协作流程 |
| langfuse | Langfuse 追踪集成 | LLM 调用追踪、观察和评分 |
| bkt | Bitbucket CLI | 提交状态、PR 状态、流水线查看 |
| jk | Jenkins CLI | 构建队列、任务运行、测试报告 |
| shaon | Hilan 考勤系统 | 考勤打卡、工资单、考勤报告 |
资料来源：[README.md:8-20]()
## 插件架构
### 插件内部结构
每个插件遵循统一的目录结构：
```
plugin-name/
├── plugin.json # Codex 插件清单
├── skills/
│ ├── skill-name/
│ │ ├── SKILL.md # 技能主文档
│ │ ├── references/ # 参考文档
│ │ │ ├── tool-reference.md
│ │ │ └── message-format.md
│ │ └── rules/ # 规则定义
│ │ ├── status.md
│ │ └── run.md
```
### 插件类型分类
```mermaid
graph TD
A[插件类型] --> B[通信类]
A --> C[CI/CD 集成类]
A --> D[LLM 观测类]
A --> E[业务系统类]
B --> B1[amq-cli]
B --> B2[amq-spec]
C --> C1[bkt]
C --> C2[jk]
D --> D1[langfuse]
E --> E1[shaon]
```
## AMQ 通信插件
### amq-cli 插件
amq-cli 插件提供点对点（P2P）消息通信能力，支持多代理之间的任务协调和状态同步。资料来源：[plugins/amq-cli/skills/amq-cli/references/message-format.md:1-30]()
**消息格式规范：**
AMQ 消息采用 Markdown 文件格式，包含 JSON frontmatter 元数据头：
```
---json
{
"schema": 1,
"id": "<消息ID>",
"from": "发送者",
"to": ["接收者"],
"thread": "线程ID",
"kind": "消息类型",
"labels": ["标签列表"]
}
---
```
| 字段 | 必填 | 描述 |
|------|------|------|
| schema | 是 | 模式版本（当前为 1） |
| id | 是 | 全局唯一消息标识符 |
| from | 是 | 发送者句柄 |
| to | 是 | 接收者句柄列表 |
| thread | 是 | 线程 ID（p2p/格式） |
| kind | 否 | 消息类型（brainstorm/question/review_request 等） |
| labels | 否 | 标签列表（用于工作流阶段标识） |
### amq-spec 插件
amq-spec 插件实现多代理协作的设计工作流程，定义规范开发的标准化阶段。资料来源：[plugins/amq-spec/skills/amq-spec/SKILL.md:1-40]()
**规范工作流程阶段：**
```mermaid
graph LR
A[Phase 1: Research] --> B[Phase 2: Discuss]
B --> C[Phase 3: Draft]
C --> D[Phase 4: Review]
D --> E[Phase 5: Present]
E --> F[Phase 6: Execute]
```
| 阶段 | 执行者 | 门控条件 |
|------|--------|----------|
| Research | 双方并行 | 两方研究提交完成 |
| Discuss | 双方 | 达成共识 |
| Draft | 主代理 | 草稿完成 |
| Review | 协作代理 | 评审通过 |
| Present | 主代理 | 用户批准 |
| Execute | 实现代理 | 执行完成 |
## CI/CD 集成插件
### bkt 插件（Bitbucket）
bkt 插件提供 Bitbucket Data Center 和 Cloud 平台的命令行接口，支持构建状态检查、流水线管理和问题追踪。资料来源：[plugins/bkt/skills/bkt/rules/status.md:1-60]()
**主要子命令：**
| 子命令 | 功能 | 平台支持 |
|--------|------|----------|
| status commit | 显示提交构建状态 | Data Center |
| status pr | 显示 PR 头提交状态 | Data Center |
| status pipeline | 显示 Cloud 流水线运行 | Cloud |
| status rate-limit | API 速率限制遥测 | 通用 |
### jk 插件（Jenkins）
jk 插件提供 Jenkins 构建系统的交互接口，支持构建队列管理、任务触发和测试报告查看。资料来源：[plugins/jk/skills/jk/rules/run.md:1-30]()
**核心功能：**
| 功能 | 命令 | 描述 |
|------|------|------|
| 取消任务 | jk run cancel | 终止正在运行的任务 |
| 列表运行 | jk run ls | 列出最近的运行记录 |
| 参数发现 | jk run params | 发现任务参数定义 |
| 重跑任务 | jk run rerun | 使用上次参数重新运行 |
| 搜索任务 | jk run search | 跨文件夹搜索 Jenkins 任务 |
| 触发任务 | jk run start | 触发新任务运行 |
| 查看详情 | jk run view | 查看运行详细信息 |
| 构建队列 | jk queue ls | 列出排队项目 |
| 测试报告 | jk test report | 显示聚合测试结果 |
## LLM 观测插件
### langfuse 插件
langfuse 插件集成 Langfuse 平台，提供 LLM 应用的追踪、观察、提示管理和评分功能。资料来源：[plugins/langfuse/skills/langfuse/references/tool-reference.md:1-80]()
**工具分类：**
| 类别 | 工具 |
|------|------|
| 追踪 | fetch_traces, fetch_trace |
| 观察 | fetch_observations, fetch_observation |
| 会话 | fetch_sessions, get_session_details |
| 异常 | find_exceptions, get_exception_details |
| 提示 | list_prompts, get_prompt, create_text_prompt, create_chat_prompt |
| 数据集 | list_datasets, get_dataset, create_dataset |
| 评分队列 | list_annotation_queues, create_annotation_queue |
| 分数 | list_scores_v2, get_score_v2 |
**输出模式：**
| 模式 | 描述 |
|------|------|
| compact | 摘要模式，大值被截断（默认） |
| full_json_string | 完整 JSON 字符串 |
| full_json_file | 保存到文件，返回摘要和路径 |
## 自动同步机制
### 同步工作流
```mermaid
graph TD
A[子仓库推送] --> B{同步模式}
B -->|auto| C[触发 plugin-update 事件]
B -->|manual| D[等待手动触发]
C --> E[Marketplace 接收事件]
E --> F[检查主分支 HEAD]
F --> G{HEAD 是否变化?}
G -->|是| H[更新 registry/plugins.json]
G -->|否| I[跳过更新]
H --> J[重新生成清单]
J --> K[提交到 main 分支]
D --> L[手动运行同步]
L --> E
```
### 同步配置
插件支持两种同步模式：
| 模式 | 行为 |
|------|------|
| auto | 每次主分支推送时自动更新清单 |
| manual | 保持固定版本，直到手动更新注册表 |
自动同步由 `.github/workflows/sync-releases.yml` 工作流管理。此外，市场还执行每周一次的回退同步和手动运行。资料来源：[README.md:30-45]()
## 添加新插件
### 前置要求
1. 仓库必须包含 `.claude-plugin/plugin.json`（Claude Code 支持）
2. 仓库必须包含 `.codex-plugin/plugin.json`（Codex CLI 支持）
### 添加流程
```mermaid
graph LR
A[准备插件仓库] --> B[创建 plugin.json]
B --> C[添加到 registry/plugins.json]
C --> D[运行 generate-manifests.py]
D --> E[提交 PR]
E --> F[合并到 main]
```
### 详细步骤
| 步骤 | 操作 | 命令/说明 |
|------|------|----------|
| 1 | 创建插件清单 | 在仓库根目录创建 `.claude-plugin/plugin.json` |
| 2 | 更新注册表 | 编辑 `registry/plugins.json` 添加插件条目 |
| 3 | 生成清单 | 运行 `python3 scripts/generate-manifests.py` |
| 4 | 提交 PR | 将更新的注册表和生成的文件提交到 PR |
详细流程参见 [CONTRIBUTING.md](CONTRIBUTING.md)。资料来源：[README.md:50-60]()
## 插件清单生成
`scripts/generate-manifests.py` 脚本负责从注册表和远程仓库生成最终的插件清单。
**生成物：**
| 输出 | 用途 | 使用者 |
|------|------|--------|
| registry/plugins.json | 市场主清单 | Marketplace 消费者 |
| plugins/*/plugin.json | Codex 本地包 | Codex CLI |
| 生成的文档 | 参考文档 | 开发者和用户 |
## 合规性与标准
所有插件遵循 [Agent Skills 规范](https://agentskills.io/specification)，确保兼容性：
- Claude Code
- Codex CLI
- 其他 Agent Skills 兼容工具
资料来源：[README.md:62-65]()
## 相关文档
- [Agent Skills 规范](https://agentskills.io/specification) - 插件技术规范
- [CONTRIBUTING.md](CONTRIBUTING.md) - 贡献指南
- [.github/workflows/sync-releases.yml](.github/workflows/sync-releases.yml) - 同步自动化
---
## AMQ插件详解
### 相关页面
相关主题：[插件列表](#page-plugin-list)
相关源码文件
以下源码文件用于生成本页说明：
- [plugins/amq-cli/skills/amq-cli/SKILL.md](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/amq-cli/skills/amq-cli/SKILL.md)
- [plugins/amq-cli/skills/amq-cli/references/message-format.md](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/amq-cli/skills/amq-cli/references/message-format.md)
- [plugins/amq-cli/skills/amq-cli/references/integrations.md](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/amq-cli/skills/amq-cli/references/integrations.md)
- [plugins/amq-spec/skills/amq-spec/SKILL.md](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/amq-spec/skills/amq-spec/SKILL.md)
- [plugins/amq-spec/skills/amq-spec/references/spec-workflow.md](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/amq-spec/skills/amq-spec/references/spec-workflow.md)
# AMQ插件详解
## 概述
AMQ（Agent Message Queue）插件是一个基于消息队列的多智能体协作框架，用于在AI代理之间实现结构化的通信与协作。该插件是技能市场（Skills Marketplace）项目的重要组成部分，为代理提供了一套完整的通信原语，支持双人协作（Coop Mode）、群体协作（Swarm Mode）以及跨项目通信等场景。
AMQ的核心设计理念是通过标准化的消息格式和工作流规范，使多个AI代理能够高效地分工协作，同时保持通信的清晰性和可追溯性。
资料来源：[plugins/amq-cli/skills/amq-cli/SKILL.md]()
## 核心通信原语
AMQ提供了三个基础命令作为通信原语，所有协作功能都建立在这三个原语之上。
### 命令概览
| 命令 | 功能描述 |
|------|----------|
| `amq send` | 发送消息到指定代理 |
| `amq thread` | 读取线程中的消息历史 |
| `amq drain` | 消费队列中的消息 |
资料来源：[plugins/amq-spec/skills/amq-spec/SKILL.md]()
### amq send
发送消息是最基础的通信操作，支持丰富的元数据配置：
```bash
amq send --to --kind brainstorm \
--labels workflow:spec,phase:research \
--thread spec/ --subject "Research: " \
--body ""
```
关键参数说明：
| 参数 | 必需 | 说明 |
|------|------|------|
| `--to` | 是 | 接收消息的代理标识 |
| `--kind` | 是 | 消息类型，值包括：question、brainstorm、review_request、review_response、decision、status、todo |
| `--labels` | 否 | 标签列表，用于标识工作流阶段和类别 |
| `--thread` | 否 | 线程ID，用于关联相关消息 |
| `--subject` | 否 | 消息主题摘要 |
| `--body` | 是 | 消息正文内容 |
资料来源：[plugins/amq-spec/skills/amq-spec/SKILL.md]()
### amq thread
用于查看线程中的完整消息历史：
```bash
amq thread --id spec/ --include-body
```
| 参数 | 说明 |
|------|------|
| `--id` | 线程唯一标识 |
| `--include-body` | 是否包含完整消息正文 |
### amq drain 与 amq watch
队列消费命令，用于接收消息：
```bash
amq drain --include-body
amq watch --timeout 120s
```
| 命令 | 功能 |
|------|------|
| `amq drain` | 消费队列中所有待处理消息 |
| `amq watch` | 持续监听队列，支持超时设置 |
## 消息格式规范
AMQ消息采用Markdown格式，消息头部包含JSON格式的元数据。
### 消息结构
```text
---json
{
"schema": 1,
"id": "",
"from": "claude",
"to": ["codex"],
"thread": "p2p/claude__codex",
"subject": "Optional summary",
"created": "",
"refs": [""],
"priority": "normal",
"kind": "question",
"labels": ["bug", "parser"],
"context": {"paths": ["internal/cli/send.go"], "focus": "error handling"},
"reply_to": "claude@collab",
"reply_project": "my-project",
"from_project": "my-project"
}
---
```
### 字段说明
| 字段 | 类型 | 说明 |
|------|------|------|
| `schema` | integer | 模式版本号，当前为1 |
| `id` | string | 全局唯一消息ID，也是磁盘上的文件名 |
| `from` | string | 发送者标识 |
| `to` | array | 接收者标识列表 |
| `thread` | string | 线程ID，用于P2P通信时使用`p2p/__`格式（按字典序排列） |
| `subject` | string | 可选的主题摘要 |
| `created` | string | RFC3339格式的时间戳 |
| `refs` | array | 关联消息ID列表 |
| `priority` | string | 优先级：`urgent`、`normal`、`low` |
| `kind` | string | 消息类型：question、answer、brainstorm、review_request、review_response、decision、status、todo |
| `labels` | array | 标签列表，用于分类和阶段标识 |
| `context` | object | 上下文信息，包含paths和focus等 |
| `reply_to` | string | 回复地址 |
| `reply_project` | string | 回复目标项目 |
| `from_project` | string | 消息来源项目 |
资料来源：[plugins/amq-cli/skills/amq-cli/references/message-format.md]()
## 工作流模式
### 协作模式（Coop Mode）
协作模式适用于两个代理之间的双人协作场景。在该模式下，两个代理可以分工处理复杂任务，通过消息传递实现工作交接和信息共享。
主要特点：
- P2P通信架构，线程ID使用`p2p/__`格式
- 支持同步和异步两种通信方式
- 消息类型丰富，包括question、brainstorm、review_request、review_response等
### Swarm模式（Swarm Mode）
Swarm模式支持多个代理同时参与一个任务，实现群体协作。该模式下消息广播和订阅机制更加灵活，适合复杂的多代理协调场景。
主要特点：
- 支持多个参与者
- 消息路由更加复杂
- 适合需要多方输入的聚合任务
### 跨项目通信（Cross-Project）
跨项目通信允许不同项目空间中的代理进行协作，适用于大型组织中跨团队协作的场景。
## Spec工作流
Spec工作流是AMQ插件中最重要的协作规范之一，专门用于多代理设计任务的协作。
### 工作流阶段
```
研究(并行) -> 讨论(乒乓球式) -> 起草(主代理) -> 审查(伙伴) -> 呈现(用户) -> 执行
```
| 阶段 | 参与者 | 说明 | 门控条件 |
|------|--------|------|----------|
| 1. 研究 | 双方并行 | 发起者发送问题陈述，双方独立研究并提交发现 | 双方研究提交完毕 |
| 2. 讨论 | 双方 | 阅读彼此发现，对齐架构、权衡和范围 | 达成一致 |
| 3. 起草 | 主代理 | 主代理起草方案 | - |
| 4. 审查 | 伙伴代理 | 伙伴代理审查并反馈 | - |
| 5. 呈现 | 主代理 | 向用户呈现最终方案 | 用户明确批准 |
| 6. 执行 | - | 开始实施 | 用户批准后 |
资料来源：[plugins/amq-spec/skills/amq-spec/references/spec-workflow.md]()
### 阶段详细说明
#### 阶段1：研究
**发起代理：**
```bash
# 1) 立即进行独立研究
# - 探索代码库/文件/模式/约束
# - 必要时查阅外部文档
# 2) 提交发现
amq send --to --kind brainstorm \
--labels workflow:spec,phase:research \
--thread spec/ --subject "Research: " \
--body ""
# 3) 等待伙伴的发现
amq watch --timeout 120s
```
**接收代理：**
```bash
# 1) 首先进行独立研究
# - 阅读发起的问题陈述
# - 暂不阅读伙伴的研究
# 2) 提交发现
amq send --to --kind brainstorm \
--labels workflow:spec,phase:research \
--thread spec/ --subject "Research: " \
--body ""
# 3) 然后阅读完整线程
amq thread --id spec/ --include-body
```
#### 阶段2：讨论
```bash
# 阅读两份研究提交
amq thread --id spec/ --include-body
# 讨论差异、权衡和决策
amq send --to --kind brainstorm \
--labels workflow:spec,phase:discuss \
--thread spec/ --subject "Discussion: " \
--body ""
# 持续轮次直到对齐
amq watch --timeout 120s
amq drain --include-body
```
#### 阶段3：起草
```bash
amq send --to --kind review_request \
--labels workflow:spec,phase:draft \
--thread spec/ --subject "Plan: " \
--body ""
```
#### 阶段4：审查
```bash
amq send --to --kind review_response \
--labels workflow:spec,phase:review \
--thread spec/ --subject "Review: " \
--body ""
# 如需要：主代理修订并重新发送草案
```
#### 阶段5：向用户呈现
主代理必须：
1. 综合讨论和审查形成最终方案
2. 直接在聊天中向用户呈现
3. 等待明确批准
4. 获得批准前不实施
#### 阶段6：执行
### 禁止事项
工作流明确规定了以下禁止行为：
- 独自研究后向伙伴发送完成的规范
- 使用无效的消息类型（仅允许question、brainstorm、review_request等通用类型）
- 跳过讨论阶段
- 在双方未交换研究之前发送草案
- 在用户批准之前实施
## 消息类型参考
| 类型 | 用途 | 典型使用场景 |
|------|------|-------------|
| `question` | 提出问题 | 请求澄清或信息 |
| `answer` | 回复问题 | 提供答案或解释 |
| `brainstorm` | 头脑风暴 | 研究发现、讨论分析 |
| `review_request` | 请求审查 | 提交草案供审查 |
| `review_response` | 审查响应 | 提供审查反馈 |
| `decision` | 决策 | 记录最终决策 |
| `status` | 状态更新 | 报告进度或状态 |
| `todo` | 待办事项 | 分配或跟踪任务 |
## 标签系统
标签用于标识消息的类别和工作流阶段。常见标签包括：
| 标签前缀 | 说明 | 示例 |
|----------|------|------|
| `workflow:spec` | 规范工作流相关 | workflow:spec,phase:research |
| `phase:research` | 研究阶段 | - |
| `phase:discuss` | 讨论阶段 | - |
| `phase:draft` | 起草阶段 | - |
| `phase:review` | 审查阶段 | - |
| `phase:decision` | 决策阶段 | - |
## 线程管理
### 线程ID格式
| 类型 | 格式 | 说明 |
|------|------|------|
| P2P通信 | `p2p/__` | 两个代理间通信，a和b按字典序排列 |
| 规范主题 | `spec/` | 特定规范讨论的主题 |
### 线程操作
```bash
# 查看线程内容
amq thread --id --include-body
# 监听新消息
amq watch --timeout
# 消费所有消息
amq drain --include-body
```
## 集成与扩展
AMQ插件支持与外部系统的集成，包括Symphony事件和Cline Kanban桥接等。
### Symphony事件
```bash
amq integration symphony emit --event before_run --me codex
amq integration symphony emit --event after_run --me codex
amq integration symphony emit --event before_remove --me codex
```
### Cline Kanban桥接
```bash
amq integration kanban bridge --me codex
amq integration kanban bridge --me codex --workspace-id my-workspace
```
默认配置：
- URL: `ws://127.0.0.1:3484/api/runtime/ws`
- 重连延迟: `3s`
### 运行时诊断
```bash
amq doctor --ops
amq doctor --ops --json
```
`doctor --ops` 在基础检查之上增加了队列深度、最早未读消息年龄、DLQ状态、在线状态新鲜度和集成提示等信息。
## 架构图
### 消息流转架构
```mermaid
graph TD
A[代理A] -->|amq send| B[消息队列]
C[代理B] -->|amq send| B
B -->|amq drain| D[代理C]
B -->|amq watch| E[代理D]
F[线程存储] <--> B
```
### Spec工作流状态图
```mermaid
stateDiagram-v2
[*] --> 研究阶段
研究阶段 --> 研究阶段: 双方并行研究
研究阶段 --> 讨论阶段: 研究提交完毕
讨论阶段 --> 讨论阶段: 持续轮次
讨论阶段 --> 起草阶段: 达成一致
讨论阶段 --> 研究阶段: 需要更多信息
起草阶段 --> 审查阶段: 提交草案
审查阶段 --> 起草阶段: 需要修订
审查阶段 --> 呈现阶段: 审查通过
呈现阶段 --> 执行阶段: 用户批准
呈现阶段 --> 讨论阶段: 用户要求修改
执行阶段 --> [*]
```
## 最佳实践
1. **独立研究原则**：在讨论之前，每个代理都应独立完成自己的研究，避免先入为主。
2. **消息类型选择**：根据消息的实际目的选择合适的类型，不要混用。
3. **标签使用**：正确使用标签标识工作流阶段，便于消息追踪和过滤。
4. **线程管理**：为相关讨论使用统一的线程ID，便于历史追溯。
5. **用户审批流程**：任何实施方案都必须在获得用户明确批准后才能执行。
## 总结
AMQ插件为多智能体协作提供了一个结构化、可追溯的通信框架。通过标准化的消息格式、明确的工作流阶段和丰富的通信原语，代理之间可以实现高效的设计协作和问题解决。规范工作流确保了协作的质量和完整性，而灵活的集成机制则保证了与其他系统的良好兼容性。
---
## Langfuse插件详解
### 相关页面
相关主题：[插件列表](#page-plugin-list)
相关源码文件
以下源码文件用于生成本页说明：
- [plugins/langfuse/skills/langfuse/SKILL.md](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/langfuse/skills/langfuse/SKILL.md)
- [plugins/langfuse/skills/langfuse/references/setup.md](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/langfuse/skills/langfuse/references/setup.md)
- [plugins/langfuse/skills/langfuse/references/tool-reference.md](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/langfuse/skills/langfuse/references/tool-reference.md)
# Langfuse插件详解
## 概述
Langfuse插件是一个基于MCP（Model Context Protocol）的AI可观测性工具，用于调试AI代理和LLM应用程序。它通过Langfuse平台提供追踪、异常发现、会话管理、提示词版本控制等功能，帮助开发者深入分析AI应用的运行状态和性能瓶颈。
该插件是`langfuse-mcp`的面向代理伴侣，为Claude Code和Codex提供何时使用Langfuse、首先调用哪个MCP工具、以及如何从广泛的追踪发现到具体根因假设的完整指导。
资料来源：[plugins/langfuse/skills/langfuse/SKILL.md:1-20](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/langfuse/skills/langfuse/SKILL.md)
### 兼容性
| 平台 | 兼容性 |
|------|--------|
| Claude Code | ✅ 支持 |
| Codex CLI | ✅ 支持 |
资料来源：[plugins/langfuse/skills/langfuse/SKILL.md:6-7](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/langfuse/skills/langfuse/SKILL.md)
## 触发条件
Langfuse插件会在以下关键词或短语出现时自动激活：
| 触发词 | 场景描述 |
|--------|----------|
| `langfuse` | 直接请求Langfuse功能 |
| `traces` | 追踪相关查询 |
| `debug AI` | AI调试需求 |
| `find exceptions` | 异常查找 |
| `what went wrong` | 问题诊断 |
| `why is it slow` | 性能分析 |
| `datasets` | 数据集操作 |
| `evaluation sets` | 评估集管理 |
资料来源：[plugins/langfuse/skills/langfuse/SKILL.md:14-15](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/langfuse/skills/langfuse/SKILL.md)
## 安装配置
### 环境变量配置
Langfuse插件通过环境变量进行配置，主要配置项如下：
| 环境变量 | 必需 | 说明 |
|----------|------|------|
| `LANGFUSE_PUBLIC_KEY` | 是 | API公钥（以`pk-`开头） |
| `LANGFUSE_SECRET_KEY` | 是 | API密钥（以`sk-`开头） |
| `LANGFUSE_HOST` | 否 | Langfuse实例URL |
| `LANGFUSE_TIMEOUT` | 否 | API超时时间（默认30秒） |
| `LANGFUSE_MCP_TOOLS` | 否 | 逗号分隔的工具组 |
| `LANGFUSE_MCP_LOG_FILE` | 否 | 日志文件路径（默认`/tmp/langfuse_mcp.log`） |
| `LANGFUSE_MCP_READ_ONLY` | 否 | 设为`true`则禁用写入工具 |
| `LANGFUSE_MCP_DEFAULT_OUTPUT_MODE` | 否 | 默认输出模式 |
资料来源：[plugins/langfuse/skills/langfuse/references/setup.md:1-12](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/langfuse/skills/langfuse/references/setup.md)
### 安装范围
| 范围 | Claude Code路径 | Codex CLI路径 |
|------|-----------------|---------------|
| 项目级 | `.claude/skills/langfuse/` | `.codex/skills/langfuse/` |
| 用户/全局 | `~/.claude/skills/langfuse/` | `~/.codex/skills/langfuse/` |
全局安装命令：
```bash
cp -r skills/langfuse ~/.claude/skills/ # Claude Code
cp -r skills/langfuse ~/.codex/skills/ # Codex CLI
```
资料来源：[plugins/langfuse/skills/langfuse/references/setup.md:14-23](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/langfuse/skills/langfuse/references/setup.md)
## MCP工具分类
Langfuse MCP提供了丰富的工具集，按功能分为以下类别：
| 类别 | 工具数量 | 核心工具 |
|------|----------|----------|
| Traces | 2 | fetch_traces, fetch_trace |
| Observations | 2 | fetch_observations, fetch_observation |
| Sessions | 3 | fetch_sessions, get_session_details, get_user_sessions |
| Exceptions | 4 | find_exceptions, find_exceptions_in_file, get_exception_details, get_error_count |
| Prompts | 8 | list_prompts, get_prompt, get_prompt_unresolved, create_text_prompt, create_chat_prompt, update_prompt_labels |
| Datasets | 8 | list_datasets, get_dataset, list_dataset_items, get_dataset_item, create_dataset, create_dataset_item, delete_dataset_item |
| Annotation Queues | 12 | 注释队列相关操作 |
| Scores | 2 | list_scores_v2, get_score_v2 |
| Schema | 1 | get_data_schema |
资料来源：[plugins/langfuse/skills/langfuse/references/tool-reference.md:6-25](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/langfuse/skills/langfuse/references/tool-reference.md)
### 只读模式
部分工具在只读模式下会被禁用（当设置`--read-only`或`LANGFUSE_MCP_READ_ONLY=true`时）：
| 工具 | 操作类型 |
|------|----------|
| `create_text_prompt` | 创建提示 |
| `create_chat_prompt` | 创建聊天提示 |
| `update_prompt_labels` | 更新标签 |
资料来源：[plugins/langfuse/skills/langfuse/references/tool-reference.md:24-25](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/langfuse/skills/langfuse/references/tool-reference.md)
## 输出模式
部分工具支持通过`output_mode`参数控制输出格式：
| 模式 | 描述 |
|------|------|
| `compact` | 摘要形式，大值会被截断（默认） |
| `full_json_string` | 完整JSON数据，返回字符串而非对象 |
| `full_json_file` | 保存到文件，返回摘要和路径 |
资料来源：[plugins/langfuse/skills/langfuse/references/tool-reference.md:27-36](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/langfuse/skills/langfuse/references/tool-reference.md)
## 提示词管理
### 创建文本提示
```json
{
"name": "prompt_name",
"prompt": "Hello {{name}}, welcome to {{app}}!",
"labels": ["staging"],
"config": {
"model": "gpt-4",
"temperature": 0.7,
"max_tokens": 1000,
"top_p": 1.0
},
"tags": ["production"],
"commit_message": "feat: add personalized greeting"
}
```
| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `name` | string | 是 | 提示词名称 |
| `prompt` | string | 是 | 提示词内容（支持`{{variables}}`） |
| `labels` | list[string] | 否 | 分配标签 |
| `config` | object | 否 | 模型配置 |
| `tags` | list[string] | 否 | 组织标签 |
| `commit_message` | string | 否 | 提交描述 |
资料来源：[plugins/langfuse/skills/langfuse/references/tool-reference.md:38-72](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/langfuse/skills/langfuse/references/tool-reference.md)
### 重要特性
**提示词不可变性**：提示词一旦创建不可修改，创建新版本是更新内容的唯一方式。
**标签唯一性**：标签在整个版本中是唯一的，在此分配标签会从其他版本移除。
资料来源：[plugins/langfuse/skills/langfuse/references/tool-reference.md:67-70](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/langfuse/skills/langfuse/references/tool-reference.md)
## 调试工作流
### 异常排查流程
```mermaid
graph TD
A[发现异常报告] --> B[find_exceptions查找异常]
B --> C[get_exception_details获取详情]
C --> D[分析根因]
D --> E[定位问题代码]
F[文件级异常] --> G[find_exceptions_in_file]
G --> C
```
### 追踪分析流程
```mermaid
graph TD
A[开始调试] --> B[fetch_traces获取追踪列表]
B --> C[筛选相关追踪]
C --> D[fetch_trace获取详细信息]
D --> E[fetch_observations获取观测点]
E --> F[定位性能瓶颈或错误]
```
### 数据集管理流程
```mermaid
graph LR
A[list_datasets] --> B[get_dataset]
B --> C[list_dataset_items]
C --> D[get_dataset_item]
D --> E[分析数据集项]
```
## 安全注意事项
| 安全措施 | 说明 |
|----------|------|
| 凭证管理 | 切勿将`.mcp.json`与真实凭证一起提交 |
| 密钥轮换 | 密钥泄露后立即轮换 |
| 数据保护 | `full_json_file`导出可能包含敏感用户数据 |
| CI/CD集成 | 优先使用环境变量注入而非硬编码值 |
资料来源：[plugins/langfuse/skills/langfuse/references/setup.md:25-30](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/langfuse/skills/langfuse/references/setup.md)
## 版本信息
| 属性 | 值 |
|------|-----|
| 插件名称 | langfuse |
| 版本号 | 0.9.1 |
| 短描述 | Langfuse observability via MCP |
资料来源：[plugins/langfuse/skills/langfuse/SKILL.md:1-7](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/langfuse/skills/langfuse/SKILL.md)
---
## 开发工具插件
### 相关页面
相关主题：[插件列表](#page-plugin-list)
相关源码文件
以下源码文件用于生成本页说明：
- [plugins/bkt/skills/bkt/SKILL.md](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/bkt/skills/bkt/SKILL.md)
- [plugins/bkt/skills/bkt/rules/status.md](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/bkt/skills/bkt/rules/status.md)
- [plugins/bkt/skills/bkt/rules/webhook.md](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/bkt/skills/bkt/rules/webhook.md)
- [plugins/bkt/skills/bkt/rules/issue.md](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/bkt/skills/bkt/rules/issue.md)
- [plugins/jk/skills/jk/SKILL.md](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/jk/skills/jk/SKILL.md)
- [plugins/jk/skills/jk/rules/queue.md](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/jk/skills/jk/rules/queue.md)
- [plugins/jk/skills/jk/rules/run.md](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/jk/skills/jk/rules/run.md)
- [plugins/jk/skills/jk/rules/test.md](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/jk/skills/jk/rules/test.md)
- [plugins/yoetz/skills/yoetz/SKILL.md](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/yoetz/skills/yoetz/SKILL.md)
# 开发工具插件
开发工具插件是 skills-marketplace 仓库中的核心组件，为 AI 代理提供与外部开发工具链集成的能力。这些插件通过标准化接口连接代码托管平台（Bitbucket）、持续集成系统（Jenkins）以及其他开发辅助工具，使 AI 代理能够在代码开发、审查、部署等环节中执行自动化任务。
## 插件架构概述
skills-marketplace 采用插件化架构，每个插件包含独立的 SKILL.md 定义文件和规则集。插件通过统一的命令行工具前缀（bkt、jk、yoetz 等）暴露功能，遵循 Agent Skills 规范，确保与 Claude Code、Codex CLI 等工具的兼容性。
```mermaid
graph TB
subgraph "skills-marketplace 插件生态"
subgraph "Bitbucket 插件"
BKT["bkt 插件"]
BKT_STATUS["bkt status"]
BKT_WEBHOOK["bkt webhook"]
BKT_ISSUE["bkt issue"]
end
subgraph "Jenkins 插件"
JK["jk 插件"]
JK_QUEUE["jk queue"]
JK_RUN["jk run"]
JK_TEST["jk test"]
end
subgraph "AI 辅助插件"
YOETZ["yoetz 插件"]
end
end
BKT --> BKT_STATUS
BKT --> BKT_WEBHOOK
BKT --> BKT_ISSUE
JK --> JK_QUEUE
JK --> JK_RUN
JK --> JK_TEST
```
## Bitbucket 工具插件（bkt）
bkt 插件提供与 Bitbucket Cloud 和 Data Center 的交互能力，支持查看构建状态、管理 Webhook、查看问题等操作。该插件针对不同 Bitbucket 部署类型（Cloud 和 Data Center）提供差异化的功能支持。
### 功能模块
| 模块 | 功能描述 | 部署类型支持 |
|------|----------|--------------|
| status | 查看提交和 PR 的构建状态 | Data Center / Cloud |
| webhook | 测试和管理 Webhook | Data Center |
| issue | 查看和管理 Bitbucket 问题 | Cloud |
### bkt status 子命令
`bkt status` 命令用于检查与提交和拉取请求关联的构建和 CI 状态，支持 Data Center 提交状态、PR head-commit 状态以及 Cloud pipeline 运行状态查询。
**主要子命令：**
| 子命令 | 描述 | 关键参数 |
|--------|------|----------|
| commit | 显示特定提交的构建状态 | `` 提交哈希 |
| pipeline | 显示 Cloud pipeline 运行状态 | `--repo`, `--workspace` |
| pr | 显示 PR head-commit 的构建状态 | `--project`, `--repo` |
| rate-limit | 显示活跃上下文的 API 速率限制遥测 | - |
**Usage 示例：**
```bash
# 查看提交的构建状态（Data Center）
bkt status commit abc1234
# 查看特定 SHA 的完整构建状态
bkt status commit 6f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a
# 查看 Cloud pipeline 运行
bkt status pipeline {pipeline-uuid}
# 检查 API 速率限制
bkt status rate-limit
```
**通用参数：**
| 参数 | 简写 | 描述 |
|------|------|------|
| `--context` | `-c` | 活跃的 Bitbucket 上下文名称 |
| `--format` | - | 输出格式：json 或 yaml |
| `--jq` | - | 对 JSON 输出应用 jq 表达式 |
| `--json` | - | 以 JSON 格式输出 |
| `--template` | - | 使用 Go 模板渲染输出 |
| `--yaml` | - | 以 YAML 格式输出 |
资料来源：[plugins/bkt/skills/bkt/rules/status.md:1-50]()
### bkt webhook 子命令
`bkt webhook` 命令用于测试 Webhook 功能，支持指定项目或仓库进行测试。
**Usage 示例：**
```bash
# 通过 ID 测试 Webhook
bkt webhook test 42
# 在特定仓库中测试 Webhook
bkt webhook test 7 --project MYPROJ --repo my-repo
```
**参数说明：**
| 参数 | 描述 |
|------|------|
| `--project` | Bitbucket 项目 key 覆盖 |
| `--repo` | 仓库 slug 覆盖 |
资料来源：[plugins/bkt/skills/bkt/rules/webhook.md:1-30]()
### bkt issue 子命令
`bkt issue` 命令用于管理 Bitbucket Cloud 问题，支持查看问题状态和详细信息。
**主要子命令：**
| 子命令 | 描述 |
|--------|------|
| status | 显示当前用户的问题列表 |
| view | 显示问题的详细信息 |
**bkt issue view 参数：**
| 参数 | 简写 | 描述 |
|------|------|------|
| `--comments` | - | 显示评论 |
| `--repo` | - | 仓库 slug |
| `--web` | `-w` | 在浏览器中打开 |
| `--workspace` | - | Bitbucket workspace |
**Usage 示例：**
```bash
# 显示当前用户的问题
bkt issue status
# 显示问题详情（包含评论）
bkt issue view 123 --comments
# 在浏览器中打开问题
bkt issue view 123 --web
```
资料来源：[plugins/bkt/skills/bkt/rules/issue.md:1-40]()
## Jenkins 工具插件（jk）
jk 插件提供与 Jenkins CI/CD 系统的交互能力，支持构建队列管理、运行控制、测试结果检查等功能。该插件支持通过上下文配置连接不同的 Jenkins 实例。
### 功能模块
| 模块 | 功能描述 | 关键参数 |
|------|----------|----------|
| queue | 管理构建队列（列出/取消） | `--context` |
| run | 控制任务运行（启动/取消/重跑） | `--context`, `--follow` |
| test | 检查聚合测试结果 | `--format`, `--json` |
| params | 发现任务参数定义 | `--limit-runs`, `--source` |
### jk queue 子命令
`jk queue` 命令用于检查和管理 Jenkins 构建队列。
| 子命令 | 描述 |
|--------|------|
| cancel | 取消排队的项目 |
| ls | 列出排队的项目 |
**Usage 示例：**
```bash
# 列出排队的项目
jk queue ls
# 取消特定队列项
jk queue cancel
```
**通用参数：**
| 参数 | 简写 | 描述 |
|------|------|------|
| `--context` | `-c` | Jenkins 上下文名称（或 JK_CONTEXT 环境变量） |
| `--format` | - | 输出格式：json, yaml |
| `--jq` | - | 使用 jq 表达式过滤 JSON 输出 |
| `--json` | - | 以 JSON 格式输出 |
| `--quiet` | `-q` | 抑制非必要输出 |
| `--template` | `-t` | 使用 Go 模板格式化输出 |
| `--yaml` | - | 以 YAML 格式输出 |
资料来源：[plugins/jk/skills/jk/rules/queue.md:1-45]()
### jk run 子命令
`jk run` 命令用于与任务运行进行交互，是 Jenkins 插件中最核心的功能模块。
| 子命令 | 描述 | 关键参数 |
|--------|------|----------|
| cancel | 取消正在运行的作业 | `--mode` |
| ls | 列出最近的运行 | `--agg`, `--cursor`, `--filter`, `--group-by` |
| params | 发现任务参数定义 | `--limit-runs`, `--source` |
| rerun | 使用之前的参数重新运行 | `--follow`, `--follow-interval`, `--interval`, `--result` |
| search | 跨文件夹搜索 Jenkins 作业和运行 | `--filter`, `--folder`, `--job-glob`, `--limit` |
| start | 触发任务运行 | `--follow`, `--follow-interval`, `--fuzzy`, `--interval` |
| view | 查看运行详情 | `--exit-status`, `--interval`, `--result`, `--summary` |
**Usage 示例：**
```bash
# 取消正在运行的作业
jk run cancel --mode kill
# 列出最近的运行
jk run ls --filter "branch=main"
# 搜索作业
jk run search --job-glob "*/deploy-*"
# 触发新运行并跟踪
jk run start my-job --follow
# 查看运行详情
jk run view --summary
```
资料来源：[plugins/jk/skills/jk/rules/run.md:1-50]()
### jk test 子命令
`jk test` 命令用于检查聚合测试结果。
| 子命令 | 描述 |
|--------|------|
| report | 显示聚合测试结果 |
**Usage 示例：**
```bash
# 显示聚合测试报告
jk test report
```
资料来源：[plugins/jk/skills/jk/rules/test.md:1-30]()
## AI 辅助工具插件（yoetz）
yoetz 插件提供 AI 辅助开发功能，包括代码审查、差异对比、文件打包、图像生成、定价估算和浏览器操作等能力。该插件支持多模型协作（Council）功能，可以并行获取多个 LLM 的意见。
### 核心功能
| 功能 | 命令示例 | 说明 |
|------|----------|------|
| 代码审查 | `yoetz review diff --staged` | 审查暂存的差异 |
| 文件审查 | `yoetz review file --path src/main.rs` | 审查特定文件 |
| 文件打包 | `yoetz bundle -p "context" -f src/**/*.rs` | 打包相关文件 |
| 图像生成 | `yoetz generate image -p "description"` | 使用 AI 生成图像 |
| 成本估算 | `yoetz pricing estimate --model MODEL_ID` | 估算模型使用成本 |
| 浏览器操作 | `yoetz browser check/attach/login` | 浏览器自动化 |
### 多模型协作（Council）
yoetz 支持通过 `--models` 参数并行调用多个 LLM 提供者，获取不同模型的共识意见。
```bash
yoetz council \
-p "Should we use async traits or callbacks for this API?" \
-f src/lib.rs -f src/api/*.rs \
--models openai/gpt-5.4,gemini/gemini-3.1-pro-preview,openrouter/xai/grok-4.20-multi-agent-beta \
--format json
```
**模型指定说明：**
- 模型 ID 通过 `yoetz models frontier` 或 `yoetz models resolve` 命令获取
- 支持跨提供者组合：`openai/,gemini/`
### 输出格式
yoetz 支持多种输出格式，通过 `--format` 参数指定：
| 格式 | 说明 |
|------|------|
| json | 结构化 JSON 输出 |
| 表格 | 人类可读的表格形式 |
| 原始 | 原始文本输出 |
资料来源：[plugins/yoetz/skills/yoetz/SKILL.md:1-50]()
## 通用参数体系
所有开发工具插件遵循统一的参数规范，确保跨插件使用体验的一致性。
### 输出格式参数
| 参数 | 说明 | 适用插件 |
|------|------|----------|
| `--format json` | 输出完整 JSON 数据 | 所有插件 |
| `--format yaml` | 输出 YAML 格式 | 所有插件 |
| `--jq ` | 使用 jq 表达式过滤输出 | bkt, jk |
| `--template ` | 使用 Go 模板自定义输出 | bkt |
| `--quiet` / `-q` | 抑制非必要输出 | jk |
### 上下文管理
| 参数 | 简写 | 环境变量 | 说明 |
|------|------|----------|------|
| `--context` | `-c` | JK_CONTEXT | 活跃的外部服务上下文 |
```mermaid
graph LR
A[用户命令] --> B{--context 参数}
B -->|指定上下文| C[使用指定上下文]
B -->|未指定| D{环境变量}
D -->|存在| E[使用环境变量上下文]
D -->|不存在| F[使用默认上下文]
C --> G[连接到对应服务实例]
E --> G
F --> G
```
## 插件配置与管理
### 上下文配置
开发工具插件通过上下文配置连接不同的服务实例。例如，Jenkins 插件可以通过以下方式配置多个 Jenkins 实例：
```bash
# 设置 Jenkins 上下文
export JK_CONTEXT=production
# 或者通过命令行覆盖
jk run start my-job --context staging
```
### 插件清单结构
每个插件在仓库中遵循统一的目录结构：
```
plugins//
├── plugin.json # Codex 插件清单
└── skills/
└── /
├── SKILL.md # 主技能定义
└── rules/ # 子命令规则文档
├── .md
└── .md
```
资料来源：[README.md:1-60]()
## 工作流集成示例
### CI/CD 状态检查工作流
```mermaid
graph TD
A[代码提交触发 CI] --> B[CI 系统更新 Bitbucket 状态]
B --> C{bkt status commit}
C -->|查看状态| D[SUCCESS/FAILED/INPROGRESS]
D --> E{状态检查结果}
E -->|失败| F[触发告警]
E -->|成功| G[继续部署流程]
```
### Jenkins 构建管理流程
```mermaid
graph LR
A[jk queue ls] --> B{队列中有任务?}
B -->|是| C[查看队列详情]
B -->|否| D[等待]
C --> E{需要取消?}
E -->|是| F[jk queue cancel]
E -->|否| G[jk run view]
G --> H{需要重跑?}
H -->|是| I[jk run rerun --follow]
H -->|否| J[查看构建日志]
```
## 技术规范与标准
所有开发工具插件遵循 Agent Skills 规范，确保跨平台兼容性：
- **Claude Code 兼容**：通过 marketplace 目录直接指向固定的 GitHub refs
- **Codex CLI 兼容**：通过 `plugins/` 目录下的本地 bundle 支持
- **自动同步**：主模式插件通过 `.github/workflows/sync-releases.yml` 自动检查更新
- **手动模式**：可通过 `sync.mode: "manual"` 设置保持固定版本
资料来源：[README.md:1-60]()
## 总结
开发工具插件为 AI 代理提供了与外部开发系统集成的标准化能力。通过 bkt 插件连接 Bitbucket 平台实现代码状态和问题的管理，通过 jk 插件连接 Jenkins 实现 CI/CD 流程的控制，通过 yoetz 插件提供 AI 辅助开发功能。这些插件共同构成了一个完整的开发辅助工具链，支持从代码提交到部署的完整流程自动化。
---
## 贡献指南
### 相关页面
相关主题：[插件注册表](#page-registry), [插件开发规范](#page-plugin-dev)
相关源码文件
以下源码文件用于生成本页说明：
- [CONTRIBUTING.md](https://github.com/avivsinai/skills-marketplace/blob/main/CONTRIBUTING.md)
- [README.md](https://github.com/avivsinai/skills-marketplace/blob/main/README.md)
# 贡献指南
本文档面向希望为 skills-marketplace 项目贡献插件的开发者。通过遵循本指南，您可以确保插件与 marketplace 生态系统无缝集成，并获得自动同步支持。
## 概述
skills-marketplace 是一个 Agent Skills 插件市场，用于托管和分发兼容的插件。该项目支持两种目标平台：
| 平台 | 说明 |
|------|------|
| Claude Code | 通过 marketplace catalog 指向固定 GitHub 引用 |
| Codex CLI | 支持本地插件包（位于 `plugins/` 目录） |
所有插件遵循 [Agent Skills 规范](https://agentskills.io/specification)，确保跨平台兼容性。
## 目录结构
```
skills-marketplace/
├── registry/
│ └── plugins.json # 插件注册表
├── plugins/ # Codex 本地插件包
│ ├── /
│ │ ├── plugin.json # Codex 插件清单
│ │ └── skills/ # 共享技能负载
│ └── ...
└── scripts/
└── generate-manifests.py # 清单生成脚本
```
## 添加新插件
### 前置条件
在提交插件之前，请确保满足以下要求：
1. 仓库必须包含 `.claude-plugin/plugin.json` 文件
2. 如需 Codex 支持，还需包含 `.codex-plugin/plugin.json` 文件
3. 插件必须遵循 Agent Skills 规范
### 操作流程
将插件添加到 marketplace 需要以下步骤：
```mermaid
graph TD
A[准备插件仓库] --> B[创建 plugin.json 清单]
C[添加插件条目到 registry/plugins.json] --> D[生成清单和产物]
B --> C
D --> E[提交 PR]
E --> F[等待审核合并]
```
#### 详细步骤
| 步骤 | 命令/操作 | 说明 |
|------|----------|------|
| 1 | 创建/准备插件仓库 | 确保包含必需清单文件 |
| 2 | 编辑 `registry/plugins.json` | 添加插件条目 |
| 3 | 生成清单 | 运行 `python3 scripts/generate-manifests.py` |
| 4 | 提交 PR | 包含更新的注册表和生成的产物 |
资料来源：[README.md:1-20]()
### plugin.json 清单格式
插件清单是插件的核心描述文件，包含以下关键字段：
| 字段 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `name` | string | 是 | 插件名称 |
| `version` | string | 是 | 版本号（语义化版本） |
| `description` | string | 否 | 插件描述 |
| `skills` | array | 是 | 技能列表 |
## 自动同步机制
### 同步模式
marketplace 支持两种同步模式：
| 模式 | 说明 | 配置方式 |
|------|------|----------|
| 自动同步 | 主模式插件在 `.github/workflows/sync-releases.yml` 中检查 | 默认 |
| 手动同步 | 插件保持固定版本 | `sync.mode: "manual"` |
资料来源：[README.md:22-30]()
### 同步触发条件
自动同步在以下情况下触发：
```mermaid
graph LR
A[子仓库推送] -->|dispatch plugin-update| B[Marketplace 接收事件]
C[每周定时任务] --> B
D[手动触发] --> B
B --> E[更新 registry/plugins.json]
E --> F[重新生成清单]
F --> G[提交到 main 分支]
```
1. **事件驱动**：子仓库推送时触发 `plugin-update` 事件
2. **定时同步**：每周执行一次备用同步
3. **手动执行**：支持按需手动触发
### 同步流程
当仓库 HEAD 发生变更时，同步流程执行以下操作：
1. 更新 `registry/plugins.json` 中的插件引用
2. 重新生成插件清单和产物
3. 直接提交到 `main` 分支
## 插件标准
所有提交到 marketplace 的插件必须符合以下标准：
| 标准 | 要求 | 验证方式 |
|------|------|----------|
| Agent Skills 规范 | 完整实现规范定义 | 工具兼容性测试 |
| Claude Code 兼容 | 通过 marketplace catalog 分发 | CI 验证 |
| Codex CLI 兼容 | 支持本地 bundle | 本地测试 |
| 清单文件完整 | 包含所有必需字段 | generate-manifests.py 验证 |
## 常见问题
### 如何手动更新固定版本插件？
对于 `sync.mode: "manual"` 的插件，需要手动更新注册表：
1. 编辑 `registry/plugins.json` 中的版本引用
2. 运行 `python3 scripts/generate-manifests.py`
3. 提交更改到仓库
### 生成的产物包含哪些内容？
运行清单生成脚本后会创建：
- Codex 插件本地包（位于 `plugins/`）
- 更新的注册表条目
- 元数据缓存文件
### 同步失败怎么办？
检查以下事项：
1. 触发仓库是否有推送事件
2. 工作流权限是否足够
3. `registry/plugins.json` 格式是否正确
## 相关资源
- [Agent Skills 规范](https://agentskills.io/specification)
- [CONTRIBUTING.md](https://github.com/avivsinai/skills-marketplace/blob/main/CONTRIBUTING.md)
- [同步工作流源码](https://github.com/avivsinai/skills-marketplace/blob/main/.github/workflows/sync-releases.yml)
---
## 插件开发规范
### 相关页面
相关主题：[贡献指南](#page-contributing), [插件注册表](#page-registry)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/avivsinai/skills-marketplace/blob/main/README.md)
- [CONTRIBUTING.md](https://github.com/avivsinai/skills-marketplace/blob/main/CONTRIBUTING.md)
- [registry/plugins.json](https://github.com/avivsinai/skills-marketplace/blob/main/registry/plugins.json)
- [plugins/langfuse/skills/langfuse/references/tool-reference.md](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/langfuse/skills/langfuse/references/tool-reference.md)
- [plugins/bkt/skills/bkt/rules/status.md](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/bkt/skills/bkt/rules/status.md)
- [plugins/jk/skills/jk/rules/run.md](https://github.com/avivsinai/skills-marketplace/blob/main/plugins/jk/skills/jk/rules/run.md)
# 插件开发规范
本文档定义了 skills-marketplace 仓库中插件（Plugin）的开发标准与提交流程。所有插件遵循 [Agent Skills 规范](https://agentskills.io/specification)，确保与 Claude Code、Codex CLI 及其他 Agent Skills 兼容工具的互操作性。
---
## 1. 概述
skills-marketplace 是 Agent Skills 的插件市场仓库，用于托管和分发各种工具插件。每个插件封装特定功能（如 Jenkins 任务管理、Bitbucket 状态查询、LLM 观测等），通过标准化的技能（Skill）结构向外提供命令、规则和参考文档。
**核心职责：**
- 集中管理插件元数据与注册信息
- 提供插件目录结构与清单格式规范
- 定义插件提交流程与自动同步机制
资料来源：[README.md:1-10]()
---
## 2. 插件目录结构
每个插件遵循统一的目录层级：
```text
plugins/
└── / # 插件根目录
├── plugin.json # Codex 插件清单
└── skills/
└── / # 技能子目录
├── SKILL.md # 技能主说明文件
├── references/ # 参考文档（API、命令格式等）
│ └── *.md
└── rules/ # 规则文件（子命令定义）
└── *.md
```
**目录说明：**
| 目录/文件 | 必需 | 描述 |
|---|---|---|
| `plugin.json` | 是 | Codex 插件清单，定义插件元数据 |
| `skills/` | 是 | 共享技能有效载荷目录 |
| `SKILL.md` | 是 | 技能入口文档，包含命令示例 |
| `references/` | 否 | API 参考、消息格式等补充文档 |
| `rules/` | 否 | 规则文件，定义子命令参数与用法 |
资料来源：[README.md:10-17]()
---
## 3. 插件清单格式
### 3.1 Claude Plugin 清单
每个插件根目录需包含 `.claude-plugin/plugin.json`，定义插件基本信息：
```json
{
"name": "插件名称",
"version": "1.0.0",
"description": "插件功能描述",
"author": "作者信息",
"commands": [
{
"name": "命令名",
"description": "命令说明",
"path": "skills/xxx/SKILL.md"
}
]
}
```
### 3.2 Codex Plugin 清单
Codex 支持需额外提供 `.codex-plugin/plugin.json` 和生成的本地 bundle：
```text
plugins/
└── /
└── plugin.json # Codex 插件清单
```
Claude Code 市场目录直接指向 GitHub 固定引用；Codex 版本额外携带生成的本地 bundle。
资料来源：[README.md:10-17]()
---
## 4. 技能（Skill）结构
### 4.1 技能主文件 (SKILL.md)
`SKILL.md` 是技能的入口文档，应包含：
- **命令摘要表格**：将自然语言映射到具体命令
- **命令示例**：每个主要命令的用法
- **参数说明**：必选/可选参数及格式要求
**示例格式：**
```markdown
| 用户意图 | 命令 |
|---|---|
| 查看构建状态 | `bkt status commit ` |
| 列出任务队列 | `jk queue ls` |
| 创建文本提示 | `langfuse create_text_prompt --name xxx --prompt "..."` |
```
### 4.2 参考文档 (references/)
参考文档存放 API 规格、消息格式等补充技术说明：
| 文件类型 | 用途 |
|---|---|
| `*-reference.md` | API 工具参考 |
| `message-format.md` | 消息格式说明 |
| `spec-workflow.md` | 工作流协议定义 |
**消息格式规范（AMQ 消息）：**
```yaml
schema: 1
id: ""
from: "sender"
to: ["receiver"]
thread: "p2p/__"
kind: "question|answer|review_request|..."
labels: ["workflow:spec", "phase:research"]
```
资料来源：[plugins/amq-cli/skills/amq-cli/references/message-format.md:1-25]()
### 4.3 规则文件 (rules/)
规则文件定义子命令的参数、标志位和用法示例：
```markdown
#
<命令描述>
## Subcommands
| 子命令 | 描述 | 关键标志 |
|---|---|---|
| | | |
##
<子命令详细说明>
### Flags
| 标志 | 简写 | 描述 |
|---|---|---|
| --flag | -f | 参数说明 |
### Examples
```bash
--flag value
```
```
资料来源：[plugins/bkt/skills/bkt/rules/status.md:1-20]()
---
## 5. 插件提交流程
将插件添加到市场的标准流程：
```mermaid
graph TD
A[准备插件仓库] --> B[创建 plugin.json 清单]
B --> C[添加到 registry/plugins.json]
C --> D[运行生成脚本]
D --> E[提交 Pull Request]
E --> F[等待审核与合并]
```
### 5.1 前提条件
插件仓库必须满足：
1. 包含 `.claude-plugin/plugin.json` 文件
2. 包含 `.codex-plugin/plugin.json` 文件（Codex 支持需要）
3. 符合 Agent Skills 规范要求
### 5.2 提交流骤
| 步骤 | 操作 | 说明 |
|---|---|---|
| 1 | 创建清单文件 | 在仓库根目录创建 `.claude-plugin/plugin.json` |
| 2 | 注册插件 | 将插件条目添加到 `registry/plugins.json` |
| 3 | 生成清单 | 执行 `python3 scripts/generate-manifests.py` |
| 4 | 提交 PR | 将更新的注册表和生成的清单提交为 Pull Request |
**关键命令：**
```bash
# 添加插件条目后，生成所有清单文件
python3 scripts/generate-manifests.py
```
资料来源：[README.md:25-30]()
---
## 6. 自动同步机制
主模式（main-mode）插件通过 GitHub Actions 自动同步：
```mermaid
graph LR
A[子仓库推送] --> B[dispatch plugin-update 事件]
B --> C[市场仓库同步工作流]
C --> D[更新 registry/plugins.json]
D --> E[重新生成清单]
E --> F[提交到 main 分支]
```
### 6.1 同步触发条件
| 触发类型 | 说明 |
|---|---|
| 子仓库推送 | 派生子仓库在默认分支推送时触发 |
| 每周回退同步 | marketplace 每周自动执行一次完整同步 |
| 手动运行 | 支持手动触发同步工作流 |
### 6.2 同步行为
- 当仓库 HEAD 发生变化时，工作流自动更新 `registry/plugins.json`
- 自动重新生成清单文件
- 直接提交到 `main` 分支
### 6.3 手动模式
插件可通过设置 `sync.mode: "manual"` 禁用自动同步，保持固定版本：
```json
{
"name": "my-plugin",
"sync": {
"mode": "manual"
}
}
```
资料来源：[README.md:19-24]()
---
## 7. registry/plugins.json 注册表
`registry/plugins.json` 是插件市场的中央注册表，定义所有可用插件：
```json
{
"plugins": [
{
"name": "langfuse",
"repo": "github.com/xxx/langfuse-plugin",
"version": "1.0.0",
"skills": ["tool-reference"]
},
{
"name": "bkt",
"repo": "github.com/xxx/bkt-plugin",
"version": "2.0.0"
}
]
}
```
**注册表字段说明：**
| 字段 | 类型 | 必需 | 描述 |
|---|---|---|---|
| `name` | string | 是 | 插件唯一名称 |
| `repo` | string | 是 | GitHub 仓库地址 |
| `version` | string | 是 | 当前版本号 |
| `skills` | array | 否 | 包含的技能列表 |
---
## 8. 插件类型示例
### 8.1 MCP 工具插件 (langfuse)
专注于 LLM 观测与提示管理：
| 工具类别 | 工具 |
|---|---|
| Traces | `fetch_traces`, `fetch_trace` |
| Prompts | `create_text_prompt`, `create_chat_prompt`, `list_prompts` |
| Datasets | `list_datasets`, `create_dataset`, `create_dataset_item` |
| Scores | `list_scores_v2`, `get_score_v2` |
资料来源：[plugins/langfuse/skills/langfuse/references/tool-reference.md:1-50]()
### 8.2 CI/CD 集成插件 (bkt, jk)
**bkt (Bitbucket)：**
| 子命令 | 功能 |
|---|---|
| `bkt status commit` | 查看提交构建状态 |
| `bkt status pipeline` | 查看 Cloud 流水线状态 |
| `bkt status rate-limit` | 查看 API 速率限制 |
**jk (Jenkins)：**
| 子命令 | 功能 |
|---|---|
| `jk run ls` | 列出最近运行 |
| `jk run start` | 触发任务运行 |
| `jk queue ls` | 列出队列项 |
| `jk test report` | 显示聚合测试结果 |
资料来源：[plugins/bkt/skills/bkt/rules/status.md:1-50]()
### 8.3 工作流协作插件 (amq-spec)
定义多代理设计任务的协作规范：
```mermaid
graph TD
A[Research 阶段] --> B[Discuss 阶段]
B --> C[Draft 阶段]
C --> D[Review 阶段]
D --> E[Present 阶段]
E --> F[Execute 阶段]
```
**阶段定义：**
| 阶段 | 执行者 | 说明 |
|---|---|---|
| Research | 双方并行 | 独立研究后提交发现 |
| Discuss | 双方 | 读取对方研究，对齐架构与权衡 |
| Draft | 主代理 | 根据对齐结果起草方案 |
| Review | 伙伴代理 | 审查草案并提供反馈 |
| Present | 主代理 | 向用户呈现最终方案 |
| Execute | — | 用户批准后执行 |
资料来源：[plugins/amq-spec/skills/amq-spec/references/spec-workflow.md:1-40]()
---
## 9. 兼容性标准
所有插件遵循 **Agent Skills 规范** (https://agentskills.io/specification)，确保跨工具兼容：
| 兼容工具 | 支持方式 |
|---|---|
| Claude Code | 市场目录指向 GitHub 固定引用 |
| Codex CLI | 额外生成本地 bundle |
| 其他兼容工具 | 遵循统一规范即可接入 |
资料来源：[README.md:30-35]()
---
## 10. 常见问题
**Q: 插件提交后多久生效？**
A: PR 合并后，通过自动同步机制在下次触发时更新市场注册表。
**Q: 如何指定插件不自动更新？**
A: 在 `registry/plugins.json` 中设置 `"sync": { "mode": "manual" }`。
**Q: 一个插件可以包含多个技能吗？**
A: 可以，每个技能放置在 `skills//` 目录下即可。
**Q: 规则文件是必需的吗？**
A: 不是必需项，但建议包含以提供完整的命令参考文档。
---
---
## Doramagic 踩坑日志
项目：avivsinai/skills-marketplace
摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。
## 1. 身份坑 · 仓库名和安装名不一致
- 严重度：medium
- 证据强度：runtime_trace
- 发现：仓库名 `skills-marketplace` 与安装入口 `skills` 不完全一致。
- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。
- 复现命令：`npx skills`
- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。
- 证据：identity.distribution | github_repo:1122660400 | https://github.com/avivsinai/skills-marketplace | repo=skills-marketplace; install=skills
## 2. 配置坑 · 可能修改宿主 AI 配置
- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
- 证据：capability.host_targets | github_repo:1122660400 | https://github.com/avivsinai/skills-marketplace | host_targets=mcp_host, claude, claude_code
## 3. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:1122660400 | https://github.com/avivsinai/skills-marketplace | README/documentation is current enough for a first validation pass.
## 4. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:1122660400 | https://github.com/avivsinai/skills-marketplace | last_activity_observed missing
## 5. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:1122660400 | https://github.com/avivsinai/skills-marketplace | no_demo; severity=medium
## 6. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:1122660400 | https://github.com/avivsinai/skills-marketplace | no_demo; severity=medium
## 7. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:1122660400 | https://github.com/avivsinai/skills-marketplace | issue_or_pr_quality=unknown
## 8. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:1122660400 | https://github.com/avivsinai/skills-marketplace | release_recency=unknown