# 安装 mccharts Agent Skill

此包为 mccharts 3.0.0 的 Agent 开发指南，Skill 版本 1.0.0。
包含接入、选项、控制器与已知边界；不包含图表 HAR、鸿蒙 SDK 或 Agent 客户端。
核心采用 [Agent Skills 标准](https://agentskills.io/specification)，不依赖专有 MCP、账号或联网服务。

## 下载后安装

1. 解压 `mccharts-skill.zip`，保留整个 `mccharts/` 目录。
2. 在它的上级目录打开终端。使用 Node.js 18 或更高版本执行：

```sh
node mccharts/scripts/install.mjs --agent codex --project /path/to/your-project
```

Windows 路径示例：

```powershell
node mccharts/scripts/install.mjs --agent claude --project "D:\My App"
```

`--project .` 表示当前终端目录，应是希望启用技能的项目；不想移动下载文件时，使用安装器的绝对路径。
默认只安装到所选项目。个人全局安装需明确指定 `--global`：

```sh
node mccharts/scripts/install.mjs --agent cursor --global
node mccharts/scripts/install.mjs --agent codex --project /path/to/project --dry-run
```

安装器只复制此 Skill，不改现有 Agent 配置、不安装图表库、不联网。
同内容重复安装不会修改文件；已有不同版本会拒绝覆盖。更新时先将旧 `mccharts/` 移到技能目录以外备份，再安装新版本。

## npm 分发方式

`mccharts-skill` 的 npm 包用于分发同一份技能。确认该版本已发布到 npm 后，可在目标项目根目录执行：

```sh
npx mccharts-skill@1.0.0 --agent codex --project .
npx mccharts-skill@1.0.0 --agent claude --global
```

`npx` 会通过 npm 下载并启动安装器；参数与 ZIP 中的安装器相同，不要求事先解压。
如果 npm 返回 E404，表示目标版本尚不可获取，请使用官网 ZIP，不要改装名称相近的包。
`mccharts-skill` 是 Agent 技能分发包；鸿蒙图表组件 `@mcui/mccharts` 仍使用 OHPM。
使用方式参见 [npm exec / npx 官方文档](https://docs.npmjs.com/cli/v11/commands/npm-exec/)。

## 客户端目录与手动复制

手动安装无需 Node.js：将完整 `mccharts/` 文件夹复制到下列目录。`~` 是当前用户的主目录。

| `--agent` | 客户端 | 项目目录 | 个人全局目录 |
| --- | --- | --- | --- |
| `codex` | Codex | `.agents/skills/` | `~/.agents/skills/` |
| `claude` | Claude Code | `.claude/skills/` | `~/.claude/skills/` |
| `cursor` | Cursor | `.cursor/skills/` | `~/.cursor/skills/` |
| `opencode` | OpenCode | `.opencode/skills/` | `~/.config/opencode/skills/` |
| `copilot` | GitHub Copilot | `.github/skills/` | `~/.copilot/skills/` |
| `windsurf` | Windsurf / Cascade | `.windsurf/skills/` | `~/.codeium/windsurf/skills/` |
| `gemini` | Gemini CLI | `.gemini/skills/` | `~/.gemini/skills/` |
| `universal` | 通用目录 / 手动加载 | `.agents/skills/` | `~/.agents/skills/` |

OpenCode 设置 `XDG_CONFIG_HOME` 时，全局安装使用该目录下的 `opencode/skills/`。
Windsurf 的新版 Cascade 文档使用 `.devin/skills/`，并明确继续读取 `.windsurf/skills/`。
云端会话通常不能直接读取本机全局文件，应按该客户端的仓库或云端技能安装流程操作。
不同客户端版本、信任设置和管理员策略会影响自动加载。这是按官方目录适配，不代表每个客户端都完成了端到端实测。

## 其他 Agent 或自定义目录

自定义技能父目录（安装器会在其下创建 `mccharts/`）：

```sh
node mccharts/scripts/install.mjs --path /path/to/skills
```

未提供专用安装项的 Agent（例如 Trae、Qoder、CodeBuddy、Cline 或自定义助手），只要能读取项目文件，就可以使用 `universal` 安装后手动加载；自动发现目录以各客户端文档为准。发送：

> 请读取 `.agents/skills/mccharts/SKILL.md`，按里面的参考资料，在当前 HarmonyOS 项目中接入 mccharts 3.0.0，实现可更新数据的折线图，并说明完成了哪些验证。

也可直接引用解压后的 `mccharts/SKILL.md`。如需要持久加载，将这个路径引用合并到该 Agent 支持的项目规则文件；保留原有规则。
只能收取附件的聊天工具可上传整个技能目录（如果支持 ZIP），或连同本次任务相关的 `references/` 文件一起提供。不能读文件、不能加载附件或没有项目工具的 Agent 只能提供建议，不能因此获得本地执行能力。

## 检查安装

重新打开项目会话或刷新客户端的技能列表，查找 `mccharts`。也可以明确要求读取安装路径下的 `SKILL.md`。
让 Agent 根据当前任务按需读参考文档即可，不需要每次载入整个包。
如果需要验证下载文件，将其 SHA-256 与官网同目录的 `mccharts-skill.sha256` 对比：

```powershell
Get-FileHash -Algorithm SHA256 .\mccharts-skill.zip
```

```sh
shasum -a 256 mccharts-skill.zip
```

## 适配依据

目录按 2026-10-25 查阅的官方文档整理：
[Codex](https://learn.chatgpt.com/docs/build-skills)、
[Claude Code](https://code.claude.com/docs/en/skills)、
[Cursor](https://cursor.com/docs/skills)、
[OpenCode](https://opencode.ai/docs/skills/)、
[GitHub Copilot](https://docs.github.com/en/copilot/concepts/customizations/agent-skills)、
[Windsurf / Cascade](https://docs.devin.ai/desktop/cascade/skills)、
[Gemini CLI](https://geminicli.com/docs/cli/skills/)。