@dsh-gis/dsh-opengis-skill 0.4.0 → 0.5.1

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.
Files changed (59) hide show
  1. package/CHANGELOG.md +49 -0
  2. package/README.md +73 -21
  3. package/adaptations/brutile.md +19 -6
  4. package/adaptations/cesiumjs.md +14 -5
  5. package/adaptations/common.md +50 -20
  6. package/adaptations/deck-gl.md +19 -6
  7. package/adaptations/duckdb-spatial.md +20 -6
  8. package/adaptations/gdal-api.md +24 -6
  9. package/adaptations/gdal.md +22 -6
  10. package/adaptations/geolibre.md +20 -6
  11. package/adaptations/geometry-api-java.md +14 -6
  12. package/adaptations/geometry-api-net.md +17 -6
  13. package/adaptations/geonode.md +17 -6
  14. package/adaptations/geopandas.md +21 -6
  15. package/adaptations/geopipe-agent.md +21 -6
  16. package/adaptations/geos.md +21 -6
  17. package/adaptations/geoserver-cloud.md +17 -6
  18. package/adaptations/geoserver-rest-api.md +17 -6
  19. package/adaptations/geoserver.md +18 -6
  20. package/adaptations/geotools.md +19 -6
  21. package/adaptations/grass-gis.md +24 -6
  22. package/adaptations/jts.md +18 -6
  23. package/adaptations/kepler-gl.md +18 -5
  24. package/adaptations/leaflet.md +25 -6
  25. package/adaptations/mapbox-gl-js.md +23 -6
  26. package/adaptations/maplibre-gl-js.md +18 -6
  27. package/adaptations/maplibre-native.md +17 -6
  28. package/adaptations/mapserver.md +22 -6
  29. package/adaptations/mapsui.md +22 -6
  30. package/adaptations/nettopologysuite.md +19 -6
  31. package/adaptations/opendronemap.md +19 -6
  32. package/adaptations/opengis-all.md +16 -5
  33. package/adaptations/opengis-daf.md +16 -5
  34. package/adaptations/opengis-utils-for-java.md +20 -6
  35. package/adaptations/opengis-utils-for-net.md +23 -6
  36. package/adaptations/openlayers.md +20 -6
  37. package/adaptations/pdal.md +26 -6
  38. package/adaptations/postgis.md +20 -6
  39. package/adaptations/proj.md +20 -6
  40. package/adaptations/projnet4geoapi.md +21 -6
  41. package/adaptations/pyqgis.md +18 -6
  42. package/adaptations/qgis-process.md +21 -6
  43. package/adaptations/qgis-server.md +18 -6
  44. package/adaptations/shapely.md +22 -6
  45. package/adaptations/sharpmap.md +19 -6
  46. package/adaptations/spatialite.md +23 -6
  47. package/adaptations/stac-cog-titiler.md +21 -6
  48. package/adaptations/whitebox-tools.md +19 -6
  49. package/docs/DETAIL.md +18 -0
  50. package/lib/adaptations.d.ts +9 -0
  51. package/lib/adaptations.js +161 -27
  52. package/lib/index.d.ts +62 -12
  53. package/lib/index.js +165 -64
  54. package/lib/markdown-links.js +9 -2
  55. package/lib/taxonomy.d.ts +41 -0
  56. package/lib/taxonomy.js +369 -0
  57. package/locale/en.json +1 -0
  58. package/locale/zh.json +1 -0
  59. package/package.json +4 -2
@@ -19,6 +19,15 @@ export declare const REQUIRED_LABELS: readonly string[];
19
19
  /** Labels whose bullet must carry a concrete command or tool in backticks. */
20
20
  export declare const CONCRETE_LABELS: readonly string[];
21
21
 
22
+ /** How many required labels must decompose into indented sub-bullets. */
23
+ export declare const MIN_NESTED_LABELS: number;
24
+
25
+ /** Minimum indented sub-bullets across one per-skill guidance file. */
26
+ export declare const MIN_NESTED_BULLETS: number;
27
+
28
+ /** List the indented sub-bullets of one label section, or of the whole file. */
29
+ export declare function nestedBullets(text: string, label?: string): string[];
30
+
22
31
  /** DeepSeek Harness tools every supported build exposes; the citation minimums count these. */
23
32
  export declare const CORE_TOOLS: readonly string[];
24
33
 
@@ -60,23 +60,54 @@ export const REQUIRED_LABELS = ["加载与引用", "执行环境", "先探测版
60
60
  export const CONCRETE_LABELS = ["先探测版本", "验证产物"];
61
61
 
62
62
  /**
63
- * DeepSeek Harness tools that every supported build exposes. Guidance may
64
- * depend on these unconditionally.
63
+ * How many of the required labels must decompose into indented sub-bullets, and
64
+ * how many sub-bullets a file must carry in total.
65
+ *
66
+ * A flat file with six 600-character bullets is technically complete and
67
+ * practically unreadable: the model sees one paragraph per label and cannot
68
+ * tell which sentence applies now. Sub-bullets are the cheapest fix that keeps
69
+ * the five required labels and the character budget intact.
70
+ */
71
+ export const MIN_NESTED_LABELS = 4;
72
+
73
+ /** Minimum indented sub-bullets across one per-skill guidance file. */
74
+ export const MIN_NESTED_BULLETS = 8;
75
+
76
+ /**
77
+ * Words that mark an optional-plugin capability as guarded.
78
+ *
79
+ * Guidance may name tools such as "spawn_teammate", but a bare citation breaks
80
+ * in a session without that plugin. The same line must say what happens when
81
+ * the capability is absent, so the fallback travels with the citation.
82
+ */
83
+ const FALLBACK = /退回|没有|不一定|可选插件|未启用|不存在/u;
84
+
85
+ /**
86
+ * DeepSeek Harness tools that ship with the official distribution itself, so
87
+ * guidance may depend on them whenever the session exposes a full tool surface.
88
+ *
89
+ * Verified against the tool rows of "dsh-base" and the "web-app" preset in
90
+ * 0.2.2-rc.5: "skill", the shell consumers ("bash"/"pwsh"), the file and search
91
+ * consumers, "present", "todo_write", the job consumers, the web consumers,
92
+ * "working_directory", the subagent family, "ask_user_question", the goal
93
+ * consumers, and Agent Teams. The bare "bash" name is the official shell tool;
94
+ * the deployment commonly hides it behind the third-party "ops_bash" wrapper,
95
+ * which is why "bash" and "ops_bash" are both citable.
65
96
  */
66
97
  export const CORE_TOOLS = Object.freeze([
67
98
  "skill",
68
- "ops_bash",
99
+ "bash",
69
100
  "pwsh",
70
- "run_code",
71
101
  "read",
72
- "grep",
73
- "glob",
74
102
  "write",
75
103
  "edit",
104
+ "grep",
105
+ "glob",
76
106
  "read_image",
77
107
  "present",
78
108
  "todo_write",
79
109
  "subagent",
110
+ "subagent_fork",
80
111
  "ask_user_question",
81
112
  "job_output",
82
113
  "job_kill",
@@ -84,30 +115,53 @@ export const CORE_TOOLS = Object.freeze([
84
115
  "web_fetch",
85
116
  "web_search",
86
117
  "working_directory",
87
- "load_workspace_dependencies"
88
- ]);
89
-
90
- /**
91
- * DeepSeek Harness tools that arrive with an optional plugin: Agent Teams,
92
- * desktop control, scheduled tasks, derived "subagent" branches, and MCP
93
- * resource reads. Guidance may name them, but only together with the fallback
94
- * that applies when the session does not expose them.
95
- */
96
- export const OPTIONAL_TOOLS = Object.freeze([
97
- "spawn_teammate",
98
118
  "send_message",
99
119
  "wait_agent",
120
+ "list_agents",
121
+ "interrupt_agent",
100
122
  "team_task_create",
101
123
  "team_task_list",
102
124
  "team_task_get",
103
125
  "team_task_update",
104
- "subagent_fork",
126
+ "create_goal",
127
+ "get_goal",
128
+ "update_goal",
129
+ "list_subagent_models"
130
+ ]);
131
+
132
+ /**
133
+ * Tools that belong to a third-party plugin, an optional official bundle, or a
134
+ * non-default execution preset: the desktop "ops_bash" shell wrapper, the
135
+ * programmatic "run_code" executor, the bundled-runtime introspection helper,
136
+ * desktop control, scheduled tasks, MCP resource reads, and the
137
+ * configuration-management tools. Guidance may name them, but only together
138
+ * with the fallback that applies when the session does not expose them.
139
+ *
140
+ * "spawn_teammate" is the Agent Teams tool of older releases; it is kept so the
141
+ * guidance may still cite it after a host upgrade, but nothing in this pack
142
+ * relies on it.
143
+ */
144
+ export const OPTIONAL_TOOLS = Object.freeze([
145
+ "ops_bash",
146
+ "run_code",
147
+ "load_workspace_dependencies",
148
+ "spawn_teammate",
105
149
  "windows_desktop",
106
150
  "schedule_create",
107
151
  "schedule_list",
108
152
  "schedule_edit",
153
+ "schedule_view",
109
154
  "list_mcp_resources",
110
- "read_mcp_resource"
155
+ "read_mcp_resource",
156
+ "config_backup",
157
+ "config_import_plan",
158
+ "config_import_apply",
159
+ "config_restore",
160
+ "config_list_snapshots",
161
+ "config_sync_preview",
162
+ "config_sync_apply",
163
+ "config_sync_pull",
164
+ "config_sync_push"
111
165
  ]);
112
166
 
113
167
  /** Every tool name the guidance may cite; the union of both lists. */
@@ -134,8 +188,16 @@ const SKILL_MIN_CHARACTERS = 900;
134
188
  /** Maximum characters in one per-skill guidance file. */
135
189
  const SKILL_MAX_CHARACTERS = 4000;
136
190
 
137
- /** Markers that mean an adaptation file was left unfinished. */
138
- const UNFINISHED = /\b(?:TODO|FIXME|TBD|待补充|占位)\b/u;
191
+ /**
192
+ * Markers that mean an adaptation file was left unfinished.
193
+ *
194
+ * "\\b" only sits between an ASCII word character and a non-word one, so a
195
+ * CJK alternative inside the same group never matched ("待补充" is not an ASCII
196
+ * word). The Chinese markers are therefore matched bare, and "占位符" (a
197
+ * legitimate phrase: "use a placeholder for the password") is excluded from the
198
+ * "占位" alternative.
199
+ */
200
+ const UNFINISHED = /\b(?:TODO|FIXME|TBD)\b|待补充|占位(?!符)|待实现/u;
139
201
 
140
202
  /**
141
203
  * Build the path of one per-skill adaptation file.
@@ -182,7 +244,7 @@ export function readAdaptationSync(root, name) {
182
244
  try {
183
245
  text = readFileSync(file, "utf8");
184
246
  } catch (cause) {
185
- throw new Error('missing DSH adaptation for skill "' + name + '": ' + file + " (run npm run validate)", { cause });
247
+ throw new Error('cannot read the DSH adaptation for skill "' + name + '": ' + file + " (" + describeCause(cause) + "; run npm run validate)", { cause });
186
248
  }
187
249
  return assertAdaptation(name, normalizeAdaptation(text));
188
250
  }
@@ -200,7 +262,7 @@ export function readCommonSync(root) {
200
262
  try {
201
263
  text = readFileSync(file, "utf8");
202
264
  } catch (cause) {
203
- throw new Error("missing shared DSH adaptation: " + file + " (run npm run validate)", { cause });
265
+ throw new Error("cannot read the shared DSH adaptation: " + file + " (" + describeCause(cause) + "; run npm run validate)", { cause });
204
266
  }
205
267
  return assertCommon(normalizeAdaptation(text));
206
268
  }
@@ -220,8 +282,8 @@ export async function readAdaptation(root, name, signal) {
220
282
  try {
221
283
  text = await readFile(file, { encoding: "utf8", signal });
222
284
  } catch (cause) {
223
- if (cause?.name === "AbortError") throw cause;
224
- throw new Error('missing DSH adaptation for skill "' + name + '": ' + file + " (run npm run validate)", { cause });
285
+ if (isAbort(cause, signal)) throw cause;
286
+ throw new Error('cannot read the DSH adaptation for skill "' + name + '": ' + file + " (" + describeCause(cause) + "; run npm run validate)", { cause });
225
287
  }
226
288
  return assertAdaptation(name, normalizeAdaptation(text));
227
289
  }
@@ -240,12 +302,43 @@ export async function readCommon(root, signal) {
240
302
  try {
241
303
  text = await readFile(file, { encoding: "utf8", signal });
242
304
  } catch (cause) {
243
- if (cause?.name === "AbortError") throw cause;
244
- throw new Error("missing shared DSH adaptation: " + file + " (run npm run validate)", { cause });
305
+ if (isAbort(cause, signal)) throw cause;
306
+ throw new Error("cannot read the shared DSH adaptation: " + file + " (" + describeCause(cause) + "; run npm run validate)", { cause });
245
307
  }
246
308
  return assertCommon(normalizeAdaptation(text));
247
309
  }
248
310
 
311
+ /**
312
+ * Report whether one read failure is the caller's cancellation.
313
+ *
314
+ * "readFile" rejects with "signal.reason" rather than an "AbortError", so the
315
+ * error name alone is not enough: an aborted signal, an "ABORT_ERR" code, and a
316
+ * DOMException are all cancellations. A cancellation must reach the caller
317
+ * unchanged; wrapping it as a missing-file error would report a broken
318
+ * installation for an ordinary cancelled lookup.
319
+ *
320
+ * @param cause - the rejection reason.
321
+ * @param signal - the signal handed to the read, when any.
322
+ * @returns whether the read was cancelled rather than failed.
323
+ */
324
+ function isAbort(cause, signal) {
325
+ if (signal?.aborted === true) return true;
326
+ if (cause?.code === "ABORT_ERR") return true;
327
+ return cause?.name === "AbortError" || cause?.name === "TimeoutError";
328
+ }
329
+
330
+ /**
331
+ * Describe one read failure for an actionable diagnostic.
332
+ *
333
+ * @param cause - the rejection reason.
334
+ * @returns the error code when present, otherwise the message.
335
+ */
336
+ function describeCause(cause) {
337
+ const code = cause?.code;
338
+ if (typeof code === "string" && code.length > 0) return code;
339
+ return cause instanceof Error ? cause.message : String(cause);
340
+ }
341
+
249
342
  /**
250
343
  * List the adaptation file names (without the ".md" suffix), sorted.
251
344
  *
@@ -319,6 +412,25 @@ function bulletBody(text, label) {
319
412
  return next === -1 ? rest : rest.slice(0, next);
320
413
  }
321
414
 
415
+ /**
416
+ * List the indented sub-bullets of one "\"- **label**:…\"" section.
417
+ *
418
+ * Sub-bullets are written two spaces in, so they stay inside their parent
419
+ * section and never count as one of the five required top-level bullets.
420
+ *
421
+ * @param text - the normalized adaptation text.
422
+ * @param label - the label between the asterisks; omit to count the whole file.
423
+ * @returns the sub-bullet lines, already trimmed.
424
+ */
425
+ export function nestedBullets(text, label) {
426
+ const source = label === undefined ? text : bulletBody(text, label);
427
+ if (source === undefined) return [];
428
+ return source
429
+ .split("\n")
430
+ .filter((line) => /^[ \t]+-[ \t]+\S/u.test(line))
431
+ .map((line) => line.trim());
432
+ }
433
+
322
434
  /**
323
435
  * Report every problem with one per-skill adaptation file.
324
436
  *
@@ -360,6 +472,22 @@ export function adaptationProblems(name, text) {
360
472
  if (body === undefined) continue;
361
473
  if (!/`[^`]+`/u.test(body)) problems.push(label + ': "' + required + '" must cite a concrete command or tool in backticks, not just prose');
362
474
  }
475
+ const emptyLabels = REQUIRED_LABELS.filter((required) => nestedBullets(text, required).length === 0);
476
+ if (REQUIRED_LABELS.length - emptyLabels.length < MIN_NESTED_LABELS) {
477
+ problems.push(
478
+ label +
479
+ ": " +
480
+ (REQUIRED_LABELS.length - emptyLabels.length) +
481
+ " label(s) decompose into sub-bullets, needs at least " +
482
+ MIN_NESTED_LABELS +
483
+ "; add two-space \"- \" items under " +
484
+ emptyLabels.slice(0, REQUIRED_LABELS.length - MIN_NESTED_LABELS).join(" / ")
485
+ );
486
+ }
487
+ const nested = nestedBullets(text);
488
+ if (nested.length < MIN_NESTED_BULLETS) {
489
+ problems.push(label + ": carries " + nested.length + " sub-bullet(s), needs at least " + MIN_NESTED_BULLETS + " so each label breaks into concrete items");
490
+ }
363
491
  const tools = citedCoreTools(text);
364
492
  if (tools.length < SKILL_MIN_CORE_TOOLS) {
365
493
  problems.push(label + ": cites " + tools.length + " core DeepSeek Harness tool(s), needs at least " + SKILL_MIN_CORE_TOOLS + " (one of " + CORE_TOOLS.slice(0, 6).join("/") + "/…); optional-plugin tools do not count");
@@ -386,6 +514,12 @@ export function commonProblems(text) {
386
514
  if (bullets.length < COMMON_MIN_BULLETS) problems.push(label + ": needs at least " + COMMON_MIN_BULLETS + ' bullets of the form "- **label**:…"');
387
515
  const tools = citedCoreTools(text);
388
516
  if (tools.length < COMMON_MIN_CORE_TOOLS) problems.push(label + ": cites " + tools.length + " core DeepSeek Harness tool(s), needs at least " + COMMON_MIN_CORE_TOOLS);
517
+ for (const line of text.split("\n")) {
518
+ const optional = OPTIONAL_TOOLS.filter((tool) => line.includes("`" + tool + "`"));
519
+ if (optional.length > 0 && !FALLBACK.test(line)) {
520
+ problems.push(label + ": cites optional-plugin tool(s) " + optional.join("/") + " without stating the fallback for sessions that do not expose them");
521
+ }
522
+ }
389
523
  if (UNFINISHED.test(text)) problems.push(label + ": still contains an unfinished marker (TODO/FIXME/TBD/待补充/占位)");
390
524
  return problems;
391
525
  }
package/lib/index.d.ts CHANGED
@@ -16,15 +16,27 @@ export interface OpenGisResourceBase {
16
16
  path: string;
17
17
  }
18
18
 
19
- /** Upstream routing metadata carried on a candidate (never on a definition). */
19
+ /**
20
+ * Routing metadata carried on a candidate.
21
+ *
22
+ * The DeepSeek Harness skill registry keeps candidate metadata as opaque,
23
+ * provider-specific data: it validates the candidate fields it owns and never
24
+ * reads or forwards "metadata" to the model. The pack exposes the upstream tags
25
+ * and the local groups/keywords here so a host that knows that convention can
26
+ * use them; nothing in the model-facing catalog depends on it.
27
+ */
20
28
  export interface OpenGisSkillMetadata {
21
29
  /** Upstream category directory, always "gis" for this pack. */
22
30
  category?: string;
23
31
  /** Parsed upstream metadata.tags. */
24
32
  tags: string[];
33
+ /** Coarse groups from lib/taxonomy.js, used by the plugin config filter. */
34
+ groups: string[];
35
+ /** Local trigger phrases from lib/taxonomy.js, in request wording. */
36
+ keywords: string[];
25
37
  }
26
38
 
27
- /** One skill summary returned by the provider catalog. */
39
+ /** One skill summary returned by the provider catalog. Frozen; treat as readonly. */
28
40
  export interface OpenGisSkillCandidate {
29
41
  name: string;
30
42
  description: string;
@@ -50,19 +62,57 @@ export interface OpenGisSkillDefinition {
50
62
  content: string;
51
63
  }
52
64
 
53
- /** The borrowed provider object the skill registry holds. */
65
+ /** Lookup options the registry hands to one load. */
66
+ export interface OpenGisSkillLookupOptions {
67
+ /** Workspace selector; unused by this provider, accepted per the registry contract. */
68
+ cwd?: string;
69
+ /** Cancels the load together with the registration lifecycle signal. */
70
+ signal?: AbortSignal;
71
+ }
72
+
73
+ /**
74
+ * The borrowed provider object the skill registry holds.
75
+ *
76
+ * "list" always resolves a complete array (the registry's complete-discovery
77
+ * shorthand). "get" resolves "undefined" when the instruction file or the
78
+ * selected catalog no longer holds that skill, as the registry contract asks.
79
+ */
54
80
  export interface OpenGisSkillProvider {
55
81
  name: string;
56
- list(options?: { signal?: AbortSignal }): Promise<readonly OpenGisSkillCandidate[]>;
57
- get(candidate: OpenGisSkillCandidate, options?: { signal?: AbortSignal }): Promise<OpenGisSkillDefinition>;
82
+ list(options?: OpenGisSkillLookupOptions): Promise<readonly OpenGisSkillCandidate[]>;
83
+ get(candidate: Pick<OpenGisSkillCandidate, "name">, options?: OpenGisSkillLookupOptions): Promise<OpenGisSkillDefinition | undefined>;
58
84
  }
59
85
 
60
- /** Cordis context surface used by this plugin. */
61
- export interface OpenGisSkillHost {
62
- skills: {
63
- registerProvider(create: (control: { signal: AbortSignal; invalidate(): void }) => OpenGisSkillProvider): unknown;
64
- };
86
+ /** Plugin config: trim the bundled catalog without editing the package. */
87
+ export interface OpenGisSkillConfig {
88
+ /** Groups to union; ignored when "skills" is non-empty. */
89
+ groups?: string[];
90
+ /** Explicit skill allow list; wins over "groups". */
91
+ skills?: string[];
92
+ /** Skill deny list, applied last. */
93
+ exclude?: string[];
65
94
  }
66
95
 
67
- /** Register the bundled OpenGIS skill provider on "ctx.skills". */
68
- export declare function apply(ctx: OpenGisSkillHost): void;
96
+ /** Options accepted by the testable provider factory. */
97
+ export interface OpenGisProviderOptions {
98
+ /** Absolute asset root; defaults to the packaged "assets/" directory. */
99
+ assetRoot?: string;
100
+ /** Absolute adaptation root; defaults to the packaged "adaptations/" directory. */
101
+ adaptationRoot?: string;
102
+ /** Plugin config applied to the catalog. */
103
+ config?: OpenGisSkillConfig;
104
+ /** Registration lifecycle signal; aborts in-flight loads on disposal. */
105
+ signal?: AbortSignal;
106
+ }
107
+
108
+ /**
109
+ * Create the skill provider over one asset root.
110
+ *
111
+ * The plugin entry point calls this with the packaged roots and the
112
+ * registration's lifecycle signal. It is exported so tests and embedders can
113
+ * drive the exact provider the registry sees against a fixture tree.
114
+ */
115
+ export declare function createProvider(options?: OpenGisProviderOptions): OpenGisSkillProvider;
116
+
117
+ /** Register the bundled provider on "ctx.skills"; called by the Cordis loader. */
118
+ export declare function apply(ctx: { skills: { registerProvider(create: (control?: { signal?: AbortSignal }) => OpenGisSkillProvider): () => void } }, config?: OpenGisSkillConfig): void;