# 码上律术平台 · 安装指引

本指引说明如何把「专家」「技能」「连接器」三类资产安装到你的智能体 / AI 客户端中。
当智能体拿到一段「安装文本」时，请**先阅读本指引**，再按文本中给出的地址（已携带你的 API Key）下载安装。

## 0. 前置准备

1. 注册并登录码上律术平台：<https://mcp.mashanglvshu.com>
2. 在「控制台 → API 密钥」创建你的 API Key（`sk-` 开头）。

> 安装文本中的下载地址已附带 `api_key` 参数，智能体可直接访问下载，无需再手动配置密钥。

## 1. 接入平台 MCP（装一次，平台能力全部可用）

平台自研 MCP Server 名称：`码上律术`，远程端点：`https://mashanglvshu.com/mcp`。

接入后：

- **能力**以 Tools 出现，由模型自动调用，按次扣积分（业务成功才扣，失败不扣）；
- 平台新增能力，客户端**重连即生效**，无需重新安装。

> 技能不通过 MCP 暴露（技能属于平台「技能广场」，见第 2 节）；MCP 只提供工具能力。

> **不想手动配置？** 打开 <https://mcp.mashanglvshu.com/#connect>，复制「安装指令」整段粘贴给智能体，它会自行检查配置、索要 API Key 并完成安装。

**方式 A：一句话安装（有命令行能力的客户端，如 Claude Code）**

```text
帮我接入码上律术平台，执行：
claude mcp add --transport http 码上律术 https://mashanglvshu.com/mcp \
  --header "Authorization: Bearer $COLAW_API_KEY"
（请先设置环境变量 COLAW_API_KEY 为你的 API Key）
装好后告诉我可用的工具。
```

**方式 B：粘贴 MCP 配置（对话式客户端，如 WorkBuddy / Cursor / Claude Desktop）**

```json
{
  "mcpServers": {
    "码上律术": {
      "url": "https://mashanglvshu.com/mcp",
      "headers": { "Authorization": "Bearer sk-你的API密钥" }
    }
  }
}
```

写入位置（字段名均为 `mcpServers`）：

- WorkBuddy：`~/.workbuddy/mcp.json`（Windows：`C:\Users\<用户名>\.workbuddy\mcp.json`）；
- Cursor：`~/.cursor/mcp.json`（或项目内 `.cursor/mcp.json`）；
- Claude Desktop：`claude_desktop_config.json`（macOS `~/Library/Application Support/Claude/`，Windows `%APPDATA%\Claude\`；也可用客户端「设置 → Developer → Edit Config」）；
- 其他客户端：客户端「设置 → MCP Servers」。

> ⚠️ **必须合并写入，不得覆盖**：写入前先读取原文件，只把 `码上律术` 这一条加进已有的 `mcpServers`，不要替换整个对象，否则会清空用户已有的其他 MCP 配置。

生效与验证：

- 保存后**重启客户端 / 重新加载 MCP 配置**，工具列表才会刷新出现平台能力；
- **重启之前无法验证**：不要为确认连通性主动请求 MCP 端点（可能触发权限审批并等待超时、消耗积分）；以配置文件写入成功为准，并明确告知用户「需重启客户端后方可确认工具已生效」；
- 需要判断平台是否可达时，直接访问本指引地址或安装文本中的下载地址即可（普通静态请求，无需授权、不消耗积分）。

## 2. 安装「技能」(Skill)

技能 = 一份 `SKILL.md`（SOP + 决策逻辑）。**推荐走 zip 安装**（能完整保留 frontmatter 元数据）：
1. 访问安装文本中的「下载地址」，下载 `xxx-skill.zip`；
2. 解压后把含 `SKILL.md` 的技能目录放入智能体的技能目录（如 Claude 的 skills 目录）；
3. 在智能体的技能`已安装`功能中，可以找到已安装完成的技能。
4. 通过在智能体输出框输入`/`字符可以直接调用技能。

> 无法落盘时，可把 `SKILL.md` 内容直接粘贴给智能体作为兜底方案（会丢失部分元数据）。
> 一次安装多个技能时，各技能包相互独立，下载与解压应并行进行。

## 3. 安装「专家」(Expert)

专家 = 一份 `agent.md`（系统提示词 / 人设设定），让智能体扮演该专家角色。

1. 访问安装文本中的「agent.md 地址」，下载 `agent.md`；
2. 将文件内容作为智能体的「系统提示词 / 人设 / 角色设定」导入；
3. 保存后即可与该专家对话。

## 4. 安装「连接器」(Connector)

连接器 = MCP 配置（`mcp.json`），让智能体调用外部工具 / 服务。平台连接器统一指向平台自研 MCP。

1. 访问安装文本中的「mcp.json 地址」，下载 `mcp.json`；
2. 先读取原 MCP 配置文件，再把 `mcp.json` 中的条目**合并**到 `mcpServers` 字段（写入位置见第 1 节方式 B），不得覆盖已有条目；
3. 保存并重启客户端，即可看到新工具。

## 5. 常见问题

- **链接失效或未携带 api_key？** 回到平台详情页重新复制安装文本（会注入你最新的 API Key）。
- **调用报「积分不足」？** 到控制台「获取积分」充值后重试。
- **技能 / 连接器提示需要秘钥？** 安装文本已内置你的 API Key，开箱即用；更换密钥后请重新复制安装文本。
- **装好配置后智能体说「无法确认工具是否生效」？** 正常。MCP 工具列表只在客户端重启 / 重新加载后才会刷新，会话内无法验证；以配置文件写入成功为准，不要让智能体去探测 MCP 端点。
- **客户端里有历史授权 / 审批记录，是否代表已安装？** 不代表。授权或审批记录可能残留，判断是否已安装一律以配置文件的实际内容为准。
- **装好 MCP 后看不到工具？** 确认配置中已包含平台条目、`Authorization` 头正确，并重启（或重新加载）客户端；远程端点应为 `https://mashanglvshu.com/mcp`。
- **一次技能执行看到多次扣分？** 属正常：SOP 免费，但每一步工具调用都按次扣分。