# 贡献指南 — SkillMesh / 插台

> 感谢你对 SkillMesh / 插台（能力通约网络）的关注！本指南将帮助你提交能力锚点、改进协议或参与代码贡献。

---

## 一、贡献方式概览

| 贡献类型               | 方式                   | 适合人群       |
| ---------------------- | ---------------------- | -------------- |
| 提交一个新的能力锚点   | GitHub Issue 表单      | 所有人         |
| 修正现有能力锚点的信息 | Pull Request           | 有 GitHub 基础 |
| 改进协议 Schema        | GitHub Discussion → PR | 技术贡献者     |
| 改进前端代码           | Fork → PR              | 前端开发者     |
| 翻译与本地化           | PR                     | 多语言使用者   |

---

## 二、能力锚点提交规范

### 2.1 提交前检查

在提交新的能力锚点之前，请确认：

1. **该能力锚点尚未被收录**：在 [插台首页](https://skillmesh.礼字号.中国) 搜索关键词，确认不存在重复。
2. **该能力具有可调用的端点**：必须有一个真实可用的 API 地址、MCP 端点、命令行工具或 Prompt 模板。
3. **该能力有真实来源**：`provenance` 字段必须指向真实存在的 GitHub 仓库或项目官网。
4. **该能力不包含恶意代码**：提交者需对所提交内容的真实性负责。

### 2.2 字段填写规范

#### 必填字段

```javascript
{
  id: "{name-en}-{seq}",           // 格式：英文短名-三位序号，如 "pdf-extract-text-001"
  name: "中文能力名称",             // 简洁、准确描述能力
  name_en: "English Capability Name",
  desc: "中文能力描述（一句话说明该能力做什么）",
  desc_en: "English capability description",
  input: "输入参数说明（调用方需要提供什么）",
  input_en: "Input parameter description",
  output: "输出承诺说明（调用方将获得什么）",
  output_en: "Output promise description",
  endpoint: "mcp://server/method",  // 调用端点 URI
  endpointType: "mcp",              // http | mcp | command | prompt | workflow
  category: "ai",                   // ai | data | media | language | dev
  provenance: "https://github.com/org/repo"  // 真实源码链接
}
```

#### 分类说明

| 分类     | 标识       | 适用场景                              |
| -------- | ---------- | ------------------------------------- |
| AI 智能  | `ai`       | AI/ML 模型推理、NLP、代码生成、搜索等 |
| 数据处理 | `data`     | 数据提取、转换、查询、格式转换等      |
| 媒体处理 | `media`    | 图像、音视频、文档处理等              |
| 语言服务 | `language` | 翻译、摘要、情感分析等                |
| 开发工具 | `dev`      | 代码执行、测试、构建等                |

#### 调用方式类型

| 类型     | 标识       | 端点格式                         |
| -------- | ---------- | -------------------------------- |
| HTTP API | `http`     | `https://api.example.com/v1/...` |
| MCP 协议 | `mcp`      | `mcp://server-name/method`       |
| 命令行   | `command`  | `command://tool-name --arg`      |
| 提示词   | `prompt`   | `prompt://action?param={value}`  |
| 工作流   | `workflow` | `workflow://pipeline/name`       |

### 2.3 信任维度填写说明

信任向量是 CCP 协议的核心创新。请基于以下标准填写：

| 维度         | 字段             | 填写依据                   | 评分参考                                                                        |
| ------------ | ---------------- | -------------------------- | ------------------------------------------------------------------------------- |
| 源码可验证性 | `trustSource`    | 源码是否公开可访问、可审计 | 0.9+：GitHub 公开仓库且有 LICENSE；0.5-0.8：有文档但源码不完整；0-0.4：黑盒服务 |
| 使用痕迹     | `trustUsage`     | 原始调用次数（可为近似值） | 如实填写                                                                        |
| 使用痕迹率   | `trustUsageRate` | 归一化使用热度             | 0.8+：生态顶流；0.3-0.7：中等活跃；0-0.2：小众                                  |
| 成功率       | `trustSuccess`   | 历史调用成功率             | 0.95+：极稳定；0.85-0.94：偶有故障；0.7-0.84：需注意                            |
| 依赖风险     | `trustRisk`      | 依赖链复杂度（越低越好）   | 0-0.1：零依赖；0.1-0.2：少量依赖；0.2+：重型依赖                                |
| 时效性       | `trustTime`      | 数据的新鲜度               | 0.9+：最近更新；0.5-0.8：半年内；0-0.4：超过一年                                |
| 最后更新     | `lastUpdated`    | ISO 日期字符串             | `"2026-08-28"`                                                                  |

#### 证据层填写

```javascript
evidence: {
  count: 1240,       // 累计调用/验证次数（真实性优先，可近似）
  uncertainty: 0.24  // 不确定性（1/(1+log10(count))，可微调）
}
```

- `count`：真实累计调用次数。如果无法获得精确值，可填写 GitHub Stars 数、API 文档浏览量等近似指标。
- `uncertainty`：`u ≈ 1 / (1 + log10(count))`。count=100 → u≈0.33；count=1000 → u≈0.25；count=10000 → u≈0.20。

### 2.4 可选字段

```javascript
{
  features: ["特性1", "特性2", "特性3"],       // 中文功能特性
  features_en: ["Feature 1", "Feature 2"],      // 英文功能特性
  usageGuide: "使用说明（自然语言）",           // 中文使用说明
  usageGuide_en: "Usage guide",                 // 英文使用说明
  codeExample: '{ "method": "tools/call", ... }', // JSON格式调用示例
  tags: ["tag1", "tag2"],                       // 语义标签
  dependencies: [],                              // 依赖的能力锚点ID
  version: "1.0.0",                              // SemVer版本号
  status: "active"                               // active | deprecated | experimental
}
```

---

## 三、代码贡献流程

### 3.1 环境准备

1. Fork 本仓库
2. Clone 你的 Fork：`git clone https://github.com/aidulibrary/skillmesh-index.git`
3. 本项目为纯静态 HTML/CSS/JS，无需安装依赖，直接在浏览器中打开 `index.html` 即可预览。

### 3.2 开发约定

- **代码风格**：遵循已有代码风格。JS 使用 IIFE 模块模式，CSS 使用 BEM 命名风格，HTML 使用语义化标签。
- **文件结构**：
  ```
  index.html          # 页面骨架
  css/style.css       # 全局样式
  js/i18n.js          # 国际化文案
  js/data.js          # 能力锚点数据
  js/app.js           # 应用逻辑
  docs/CCP-v0.1.md    # 协议规范
  CONTRIBUTING.md     # 贡献指南
  README.md           # 项目说明
  ```
- **浏览器兼容**：支持 Chrome、Firefox、Safari、Edge 最新两个大版本。
- **响应式**：移动端单列、平板双列、桌面三列布局。
- **无障碍**：使用语义化 HTML、ARIA 属性、键盘可操作。

### 3.3 提交规范

1. **分支命名**：`feat/xxx`（新功能）、`fix/xxx`（修复）、`docs/xxx`（文档）、`refactor/xxx`（重构）。
2. **Commit 信息**：使用中文，格式 `{类型}: {简短描述}`。例如：`feat: 新增语义搜索支持`。
3. **PR 描述**：说明做了什么、为什么这样做、如何验证。

### 3.4 验证清单

提交 PR 前，请确认：

- [ ] `node --check js/app.js` 通过
- [ ] `node --check js/data.js` 通过
- [ ] `node --check js/i18n.js` 通过
- [ ] 在浏览器中打开 `index.html`，所有功能正常
- [ ] 中英文切换正常
- [ ] 搜索和分类筛选正常
- [ ] 模态框打开和关闭正常
- [ ] 移动端布局正常（Chrome DevTools 模拟）
- [ ] 新增的能力锚点数据无占位符（无 `example.com`）

---

## 四、协议改进流程

CCP 协议本身的改进遵循以下流程：

1. **发起讨论**：在 GitHub Discussions 中创建"Protocol Enhancement Proposal"话题。
2. **社区讨论**：至少 7 天讨论期，收集反馈。
3. **草案编写**：讨论达成共识后，编写协议修改草案。
4. **PR 提交**：将修改提交到 `docs/CCP-v0.1.md`。
5. **合并**：至少 2 位维护者 Review 通过后合并。

---

## 五、行为准则

- 尊重所有贡献者，无论其技术水平、经验或背景。
- 建设性反馈，专注于改进而非批评。
- 能力锚点数据必须真实可验证，禁止提交虚假或误导性信息。
- 信任向量数据应基于可验证的证据，而非主观臆断。

---

## 六、许可

所有贡献（代码、数据、文档）均采用与项目一致的许可：

- **代码**：[MIT License](https://opensource.org/licenses/MIT)
- **协议文档**：[CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)

贡献即表示你同意在上述许可下发布你的贡献。

---

> **相关链接**：
>
> - [CCP 协议规范](./docs/CCP-v0.1.md)
> - [项目说明](./README.md)
> - [SkillMesh 首页](https://skillmesh.礼字号.中国)