harmonyos-guides-mcp 0.2.0 → 0.2.2
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/README.md +72 -8
- package/data/INDEX.md +5514 -0
- package/data/{docs/_crawl_log.txt → index_log.txt} +1 -1
- package/data/synonyms.json +58 -0
- package/dist/data.js +13 -5
- package/dist/index.js +20 -0
- package/dist/search.js +180 -25
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -2,16 +2,26 @@
|
|
|
2
2
|
|
|
3
3
|
把鸿蒙官方开发指南(5489 篇)封装成 MCP 检索服务,供 Claude Code / opencode / Cursor / Cline 等客户端在开发时查 API/Kit 用法。**文档(52MB)随包发布,装包即用、零配置。**
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
与姊妹项目分工互补:
|
|
6
|
+
|
|
7
|
+
| | 本项目(guides) | best-practices | api-references | ui-design-guides |
|
|
8
|
+
|---|---|---|---|---|
|
|
9
|
+
| 查什么 | **API 用法、调用流程** | **场景最佳实践 + 参考代码** | **接口精确定义**(参数/枚举) | **设计怎么做**(视觉/交互/控件设计规范) |
|
|
10
|
+
| 数据 | 5489 篇指南 | 452 篇 + 186 代码仓库 | 4495 篇 API 参考 | 166 篇设计指南 |
|
|
11
|
+
| 适用 | "AVPlayer 怎么初始化" | "长列表丢帧优化" | "AudioCapturer 方法签名" | "底部页签设计规范" |
|
|
12
|
+
|
|
13
|
+
四者并列:guides 讲 API 用法、best-practices 给场景实践与参考代码、api-references 查精确签名、ui-design-guides 定设计规范。
|
|
6
14
|
|
|
7
15
|
## 提供的工具
|
|
8
16
|
|
|
9
17
|
| 工具 | 作用 |
|
|
10
18
|
|------|------|
|
|
11
|
-
| `search_guides({query, limit?})` | 全文检索指南(
|
|
19
|
+
| `search_guides({query, limit?})` | 全文检索指南(BM25 + CJK 权重 + 同义词扩展,中文友好),返回相关度排序的文档列表(含标题、分类路径) |
|
|
12
20
|
| `get_guide({name})` | 读取指定指南(docId)的完整 Markdown 正文 |
|
|
13
21
|
| `list_guides_by_topic({topic?})` | 按分类路径浏览;支持多级下钻(如 `媒体` → `媒体 / Audio Kit`) |
|
|
14
22
|
|
|
23
|
+
**检索算法**:BM25 排序(TF 饱和 + 文档长度归一化 + IDF)→ CJK 单字×0.3 / 双字 bigram×0.5 降权(抑制跨词边界噪声)→ 域内同义词软 OR 扩展(`data/synonyms.json` 驱动)。同义词词典数据驱动,编辑 JSON 即可扩展,无需改代码。
|
|
24
|
+
|
|
15
25
|
数据规模:5489 篇指南,顶级类含 基础入门(34)、应用框架(835)、系统(778)、媒体(295)、图形(182)、应用服务(710) 等。
|
|
16
26
|
|
|
17
27
|
## 安装(最终用户)
|
|
@@ -23,19 +33,32 @@
|
|
|
23
33
|
"mcpServers": {
|
|
24
34
|
"harmonyos-guides": {
|
|
25
35
|
"command": "npx",
|
|
26
|
-
"args": ["-y", "harmonyos-guides-mcp"]
|
|
36
|
+
"args": ["-y", "harmonyos-guides-mcp@latest"]
|
|
27
37
|
}
|
|
28
38
|
}
|
|
29
39
|
}
|
|
30
40
|
```
|
|
31
41
|
|
|
32
|
-
|
|
42
|
+
> `@latest` 每次启动联网拉最新版;也可固定版本如 `@0.2.1` 避免版本漂移与启动联网。或全局安装:`npm install -g harmonyos-guides-mcp`。任何支持 stdio 的 MCP 客户端(opencode / Cursor / Cline / Continue)同样配置。
|
|
33
43
|
|
|
34
44
|
### 环境变量
|
|
35
45
|
|
|
36
46
|
| 变量 | 默认 | 说明 |
|
|
37
47
|
|------|------|------|
|
|
38
48
|
| `BP_DOCS_DIR` | 包内 `data/docs` | 文档目录(一般无需改) |
|
|
49
|
+
| `BP_LOG` | 包内 `data/index_log.txt` | 分类日志(驱动文档分类,缺失会报错;一般无需改) |
|
|
50
|
+
|
|
51
|
+
> `data/synonyms.json` 为同义词词典(随包),缺失时检索退化为无同义词扩展,不影响正常使用。`data/INDEX.md` 是人读文档索引(代码不读)。
|
|
52
|
+
|
|
53
|
+
### 数据布局(包内 `data/`)
|
|
54
|
+
|
|
55
|
+
```
|
|
56
|
+
data/
|
|
57
|
+
├── docs/ # 纯 .md 文档(5489 篇)
|
|
58
|
+
├── index_log.txt # 分类日志(机器读,驱动分类)
|
|
59
|
+
├── synonyms.json # 同义词词典(检索用,可编辑扩展)
|
|
60
|
+
└── INDEX.md # 人读文档索引(按大类分组,代码不读)
|
|
61
|
+
```
|
|
39
62
|
|
|
40
63
|
## 更新
|
|
41
64
|
|
|
@@ -62,24 +85,65 @@ npm ls -g harmonyos-guides-mcp # 本地已装版本
|
|
|
62
85
|
```
|
|
63
86
|
或看客户端 MCP 面板里服务器的 `version` 字段。
|
|
64
87
|
|
|
65
|
-
##
|
|
88
|
+
## 四者并列使用
|
|
89
|
+
|
|
90
|
+
### OpenCode 示例
|
|
66
91
|
|
|
67
92
|
```json
|
|
68
93
|
{
|
|
69
94
|
"mcp": {
|
|
70
95
|
"harmonyos-best-practices": {
|
|
71
96
|
"type": "local",
|
|
72
|
-
"command": ["npx", "-y", "harmonyos-best-practices-mcp"]
|
|
97
|
+
"command": ["npx", "-y", "harmonyos-best-practices-mcp@latest"],
|
|
98
|
+
"environment": { "BP_CODE_DIR": "/abs/path/to/best_practices_code" }
|
|
73
99
|
},
|
|
74
100
|
"harmonyos-guides": {
|
|
75
101
|
"type": "local",
|
|
76
|
-
"command": ["npx", "-y", "harmonyos-guides-mcp"]
|
|
102
|
+
"command": ["npx", "-y", "harmonyos-guides-mcp@latest"]
|
|
103
|
+
},
|
|
104
|
+
"harmonyos-api-references": {
|
|
105
|
+
"type": "local",
|
|
106
|
+
"command": ["npx", "-y", "harmonyos-api-references-mcp@latest"]
|
|
107
|
+
},
|
|
108
|
+
"harmonyos-ui-design-guides": {
|
|
109
|
+
"type": "local",
|
|
110
|
+
"command": ["npx", "-y", "harmonyos-ui-design-guides-mcp@latest"]
|
|
77
111
|
}
|
|
78
112
|
}
|
|
79
113
|
}
|
|
80
114
|
```
|
|
81
115
|
|
|
82
|
-
|
|
116
|
+
### Claude Code 示例
|
|
117
|
+
|
|
118
|
+
```json
|
|
119
|
+
{
|
|
120
|
+
"mcpServers": {
|
|
121
|
+
"harmonyos-best-practices": {
|
|
122
|
+
"command": "npx",
|
|
123
|
+
"args": ["-y", "harmonyos-best-practices-mcp@latest"],
|
|
124
|
+
"env": { "BP_CODE_DIR": "/abs/path/to/best_practices_code" }
|
|
125
|
+
},
|
|
126
|
+
"harmonyos-guides": {
|
|
127
|
+
"command": "npx",
|
|
128
|
+
"args": ["-y", "harmonyos-guides-mcp@latest"]
|
|
129
|
+
},
|
|
130
|
+
"harmonyos-api-references": {
|
|
131
|
+
"command": "npx",
|
|
132
|
+
"args": ["-y", "harmonyos-api-references-mcp@latest"]
|
|
133
|
+
},
|
|
134
|
+
"harmonyos-ui-design-guides": {
|
|
135
|
+
"command": "npx",
|
|
136
|
+
"args": ["-y", "harmonyos-ui-design-guides-mcp@latest"]
|
|
137
|
+
}
|
|
138
|
+
}
|
|
139
|
+
}
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
### BP_CODE_DIR 设置
|
|
143
|
+
|
|
144
|
+
> **`BP_CODE_DIR`(仅 best-practices 可选)**:指向本地 `best_practices_code/` 目录(从 GitHub Release 下载 `harmonyos-best-practices-code.tar.gz` 解压得到)。配置后 `get_code_example` 会返回本地仓库路径与入口 `.ets` 文件,AI 可直接读取真实官方示例代码;**不配则只返回 gitcode 远程 URL**。Windows 路径用正斜杠更稳(如 `C:/path/to/best_practices_code`)。其余三个 MCP 是纯文档,无需此变量。
|
|
145
|
+
|
|
146
|
+
搭配各自的 Skill(`harmonyos-best-practices` / `harmonyos-guides` / `harmonyos-api-references` / `harmonyos-ui-design-guides`),AI 可据需求选用:guides 查 API 用法、best-practices 查场景实践与参考代码、api-references 查精确签名、ui-design-guides 查设计规范。
|
|
83
147
|
|
|
84
148
|
## 开发与发布(维护者)
|
|
85
149
|
|