@dsh-gis/dsh-opengis-skill 0.5.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.
- package/CHANGELOG.md +31 -0
- package/README.md +28 -21
- package/adaptations/common.md +5 -4
- package/adaptations/gdal.md +1 -1
- package/adaptations/grass-gis.md +1 -1
- package/docs/DETAIL.md +18 -0
- package/lib/adaptations.js +97 -27
- package/lib/index.d.ts +51 -5
- package/lib/index.js +142 -61
- package/lib/markdown-links.js +9 -2
- package/lib/taxonomy.js +40 -3
- package/locale/en.json +1 -0
- package/locale/zh.json +1 -0
- package/package.json +3 -2
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,37 @@ All notable changes to this project are documented in this file.
|
|
|
5
5
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
6
|
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
7
|
|
|
8
|
+
## [0.5.1] - 2026-11-19
|
|
9
|
+
|
|
10
|
+
### Fixed — DeepSeek Harness 0.2.2 compatibility
|
|
11
|
+
|
|
12
|
+
- **`get()` 现在按注册表契约返回 `undefined`**(`lib/index.js`):候选不在本 provider 目录内、已被配置过滤掉、或 `SKILL.md` 在发现与加载之间被删除时,返回 `undefined` 让宿主报告「unknown or no longer available」;此前抛出的 `unknown skill` / `ENOENT` 会把一次普通查找变成工具失败。类型声明同步为 `Promise<OpenGisSkillDefinition | undefined>`(`lib/index.d.ts`)。
|
|
13
|
+
- **取消不再被误报成安装损坏**(`lib/adaptations.js`):`readFile` 取消时拒绝的是 `signal.reason` 而不是 `AbortError`,旧代码因此把取消包装成「missing DSH adaptation … run npm run validate」。新增 `isAbort()`(同时看 `signal.aborted`、`ABORT_ERR` 与 `AbortError`/`TimeoutError`),取消原样抛出;其余读取失败的错误信息带上错误码(`ENOENT`/`EACCES`),不再一律说成「缺文件」。
|
|
14
|
+
- **注册表生命周期信号接入加载路径**:`apply()` 把 `registerProvider` 的 `control.signal` 传进 provider,与调用方 `options.signal` 合并(`AbortSignal.any`),插件卸载时正在进行的 `get()` 会及时收敛。
|
|
15
|
+
- **工具清单按 0.2.2-rc.5 的真实来源重分**:`CORE_TOOLS` 改为官方分发自带的工具(`bash`、`pwsh`、文件与检索、`job_*`、`subagent` 家族、`skill`、`present`、`todo_write`、Web、`working_directory`、`ask_user_question`、目标与 Agent Teams 等,已对照 `dsh-base` 与 web 预设的行清单核实),`ops_bash`、`run_code`、`load_workspace_dependencies` 移到 `OPTIONAL_TOOLS`——它们分别来自第三方 Ops 插件、PTC 预设与 web 预设,并非每个构建都有。45 个适配文件仍各自引用不少于 2 个核心工具,`common.md` 引用 14 个,门槛不变。
|
|
16
|
+
- **可选工具兜底措辞**:`common.md` 新增「shell 工具名」一条,说明 `ops_bash` 与官方 `bash` 是同一消费者的两种暴露方式、没有插件时替换即可;`load_workspace_dependencies` 缺失时按平台自探解释器路径。两处都带退路,`commonProblems` 的兜底约束得以通过。
|
|
17
|
+
- **未完成标记检查对中文生效**(`lib/adaptations.js`):旧正则把 `TODO/FIXME/TBD` 与 `待补充/占位` 放在同一组、外面套 ASCII 词边界符,中英文分支因此永远命不中中文文本。改为 ASCII 分支保留词边界、中文分支直接匹配,并排除合法词「占位符」;残留的 `待补充`/`占位` 现在会被 `npm run validate` 拒绝。
|
|
18
|
+
|
|
19
|
+
### Fixed — routing, links, diagnostics
|
|
20
|
+
|
|
21
|
+
- **路由打分改为整词匹配**(`lib/taxonomy.js`):描述里的拉丁词此前用裸 `includes`,`geos` 会命中 `GeoServer`、`jts` 会命中版本号。新增 `containsTerm()` 对含拉丁字母的词要求前后非字母数字边界,纯中文关键词仍按子串匹配;给 `pyqgis` 补 `QGIS 环境`、`initQgis` 两个请求原话,中文用例仍全部命中前三。
|
|
22
|
+
- **Markdown 链接正则支持一层成对括号**(`lib/markdown-links.js`):形如 `x → reference/foo_(bar).md` 的链接不再被截成 `reference/foo_(bar`,目标也不再跨行;资产里当前没有这类链接,属于失败即报错的健壮性修复。
|
|
23
|
+
- **`list()` 每次返回新数组**:元素仍冻结,但调用方排序或截断不再可能改到 provider 内部目录。
|
|
24
|
+
- **`check-citations.mjs` 版本号按整词比对**:`3.9` 不再被 `13.9`/`3.9.1` 误命中,真实漂移不再被掩盖。
|
|
25
|
+
- **`check-adaptations.mjs` 不再重复报标题错误**:`adaptationProblems` 已报「must start with」时不再追加一条 `wrong heading`。
|
|
26
|
+
|
|
27
|
+
### Added
|
|
28
|
+
|
|
29
|
+
- **`test/dsh-contract.test.mjs`**:按 `@deepseek-ai/dsh-skill` 0.2.2-rc.5 的 `validateCandidate`/`validateDefinition` 规则回归 45 个候选与 45 份正文(kebab-case 名称、非空描述、布尔 invocation、字符串 source/provider、有限 rank、provider 与注册名一致、`locator` 存在、可选 `path`/`whenToUse`/`resourceBase`、定义名与候选一致、`content` 为字符串),并覆盖 `list()` 返回新数组、`get()` 对未知候选与已过滤候选返回 `undefined`。
|
|
30
|
+
- **`test/dsh-integration.test.mjs`**:自动探测本机安装的 DeepSeek Harness,用 `ELECTRON_RUN_AS_NODE` 在真实的 `@deepseek-ai/dsh-skill` 注册表里跑 provider(45 个候选、加载 `gdal`、未知技能返回 `undefined`、取消传播、重名 provider 被拒);没有安装或设置 `DSH_SKIP_INTEGRATION=1` 时跳过。
|
|
31
|
+
- **`plugin.test.mjs` 新增「文件消失」用例**:用临时夹具验证发现之后删除 `SKILL.md` 返回 `undefined`。
|
|
32
|
+
- **`npm run check` 与 CI 纳入 `check:adaptations`**:此前 `check` 只有 validate/citations/test,适配层的独立校验脚本不在发布门禁里。
|
|
33
|
+
|
|
34
|
+
### Changed
|
|
35
|
+
|
|
36
|
+
- **README 兼容性声明改为可核查的表述**:删掉「契约在 0.2.0-rc.2 与 0.2.1-rc.2 之间字节一致」这类无证据断言,明确「已实测 `0.2.2-rc.5`」;同时修正 `metadata` 对模型不可见(目录只渲染名称与描述)、`ops_bash`/`run_code` 的真实来源、`spillPath` 已删除、包体积按实测写、示例路径去个人化。
|
|
37
|
+
- **`common.md` 不再让模型去看 `metadata.keywords`/`groups`**:DSH 的模型侧目录只给名称与描述,那条指引不可执行;改为「按名称与描述判断,加载后按正文切换」。
|
|
38
|
+
- **新增 Plugins 详情文档**:`docs/DETAIL.md` 由 `locale/{en,zh}.json` 的 `meta.detail` 指向,插件详情页不再退回渲染 48 KB 的 README;`files` 相应加上 `docs/`。
|
|
8
39
|
## [0.5.0] - 2026-11-17
|
|
9
40
|
|
|
10
41
|
### Added
|
package/README.md
CHANGED
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
> `reference/*.md` files are loaded on demand. Vendored bodies stay byte-identical to
|
|
7
7
|
> upstream, and a separate `adaptations/` layer is appended when a skill is loaded —
|
|
8
8
|
> one DeepSeek Harness guidance block per skill plus a shared one (tool mapping,
|
|
9
|
-
> Windows rewrites, background jobs,
|
|
9
|
+
> Windows rewrites, background jobs, artifact verification, consent gates,
|
|
10
10
|
> sandbox semantics, optional-plugin fallbacks). A per-skill block must name at least
|
|
11
11
|
> two *core* harness tools and give a concrete probe command and a concrete verification
|
|
12
12
|
> command, so the layer stays about *this* harness instead of repeating tool-agnostic
|
|
@@ -16,7 +16,8 @@
|
|
|
16
16
|
> frontmatter) is exposed on the provider candidate. Zero runtime dependencies: every
|
|
17
17
|
> asset ships inside the npm package.
|
|
18
18
|
>
|
|
19
|
-
> Compatibility: DeepSeek Harness `>=0.2.0-rc.2 <0.3.0-0
|
|
19
|
+
> Compatibility: DeepSeek Harness `>=0.2.0-rc.2 <0.3.0-0` (verified end to end against
|
|
20
|
+
> `0.2.2-rc.5`, the current desktop/nightly build); Node.js `>=22` for development
|
|
20
21
|
> only. MIT licensed.
|
|
21
22
|
|
|
22
23
|
DeepSeek Harness 的 **OpenGIS 技能包插件**:把 [opengis-skills](https://github.com/znlgis/opengis-skills) 中 `gis/` 分类的 GIS 技能打包成可安装、可启停的 DSH bundle。会话技能目录只列出名称与描述,技能正文与参考资料按需加载。
|
|
@@ -25,21 +26,21 @@ DeepSeek Harness 的 **OpenGIS 技能包插件**:把 [opengis-skills](https://
|
|
|
25
26
|
|
|
26
27
|
- **覆盖 GIS 全链路(45 个技能)**:GDAL、GDAL API、QGIS(qgis_process / PyQGIS / QGIS Server)、GeoServer(含 REST API 与 Cloud)、GeoNode、MapServer、PostGIS、DuckDB Spatial、SpatiaLite、PROJ、ProjNet4GeoAPI、PDAL、GRASS GIS、WhiteboxTools、JTS、NetTopologySuite、Esri Geometry API(Java/.NET)、GEOS、Shapely、GeoPandas、GeoPipeAgent、OpenGisDAF、CesiumJS、OpenLayers、Leaflet、BruTile、Mapbox GL JS、MapLibre GL JS、MapLibre Native、deck.gl、Kepler.gl、GeoLibre、OpenDroneMap、STAC/COG/TiTiler、SharpMap、Mapsui、GeoTools、OpenGIS Utils(Java/.NET),以及 `opengis-all` 全流程索引。
|
|
27
28
|
- **按需加载**:注册的是 skill provider(`ctx.skills.registerProvider`),发现阶段只读 frontmatter;正文每次加载时读取,参考资料(`reference/*.md`)通过技能目录(resource base)相对解析。
|
|
28
|
-
- **零运行时依赖**:只用 Node 内置模块,不 import DSH 内部包;全部资产与适配文件随 npm 包分发,整个包解包后约 1.24 MB(其中技能资产 910 kB
|
|
29
|
+
- **零运行时依赖**:只用 Node 内置模块,不 import DSH 内部包;全部资产与适配文件随 npm 包分发,整个包解包后约 1.24 MB(其中技能资产 910 kB、适配层约 150 kB),npm tarball 约 470 kB(141 个文件)。
|
|
29
30
|
- **可同步上游**:`npm run sync` 从 opengis-skills 检出复制资产,记录上游 commit 与每个文件的 SHA-256 到 `upstream.json`,并重新生成本文下方技能清单。
|
|
30
31
|
- **可启停**:单包同时是 bundle 与插件(`dsh.bundle.patch` 插入自身行),在 Plugins 里启用/停用即可。
|
|
31
|
-
- **分层适配 DSH**:`assets/` 保持上游逐字节快照(SHA-256 清单可校验),DSH 专属建议单独放在 `adaptations/`:`common.md` 是通用执行约定(技能加载与索引型入口、引用分段读取、长任务与后台作业、Windows 改写、随包运行时没有 GIS 绑定、先探测再执行、多步编排、可选插件能力、GUI 验证边界、产物验证、`present` 交付、`ask_user_question`
|
|
32
|
-
- **适配层强制体现 harness**:每个 `<skill>.md` 必须 900–4000 字符、含 5 个固定要点(加载与引用 / 执行环境 / 先探测版本 / 验证产物 / 风险与权限),至少点名 **2 个核心工具**(`
|
|
32
|
+
- **分层适配 DSH**:`assets/` 保持上游逐字节快照(SHA-256 清单可校验),DSH 专属建议单独放在 `adaptations/`:`common.md` 是通用执行约定(技能加载与索引型入口、引用分段读取、长任务与后台作业、Windows 改写、随包运行时没有 GIS 绑定、先探测再执行、多步编排、可选插件能力、GUI 验证边界、产物验证、`present` 交付、`ask_user_question` 确认、沙箱与审批、外部资料、失败定位)。命令执行分工与输出截断说明直接指向宿主工具描述,不在这里重述。`<skill>.md` 是该技能的执行建议(按需读哪个 reference、命令跑在哪、先探测什么版本、产物怎么验证、哪些操作要先确认)。加载技能时由 provider 把两段拼到正文之后,技能正文保持原样。
|
|
33
|
+
- **适配层强制体现 harness**:每个 `<skill>.md` 必须 900–4000 字符、含 5 个固定要点(加载与引用 / 执行环境 / 先探测版本 / 验证产物 / 风险与权限),至少点名 **2 个核心工具**(`skill`、`bash`、`read`、`job_output`、`read_image`、`ask_user_question` 等官方分发自带工具),并且「先探测版本」「验证产物」两条必须各带一条反引号命令——只写「检查一下」会被 `npm run validate` 拒绝。工具白名单按来源拆成 `CORE_TOOLS`(DSH 官方分发自带的工具)与 `OPTIONAL_TOOLS`(第三方插件如 `ops_bash`、PTC 专属的 `run_code`、桌面控制、定时任务、MCP 资源等),可选工具不计入最低数,且必须与「没有就退回」的备份方案一起写。
|
|
33
34
|
- **可用性靠结构而不是篇幅**:每个 `<skill>.md` 至少 4 个要点必须拆成两格缩进的子条目、全文至少 8 条子条目(`MIN_NESTED_LABELS` / `MIN_NESTED_BULLETS`)。一条 600 字的段落在模型眼里是一整块,拆成「先查什么 → 怎么判 → 失败怎么办」的子条目才用得起来。`common.md` 里点名的每个可选工具,所在行必须同时给出没有该插件时的退路。
|
|
34
|
-
- **上游路由元数据透出**:provider 解析上游六字段 frontmatter 里的 `metadata.category` 与 `metadata.tags
|
|
35
|
-
-
|
|
35
|
+
- **上游路由元数据透出**:provider 解析上游六字段 frontmatter 里的 `metadata.category` 与 `metadata.tags`,连同本地 groups 与 keywords 一起作为 candidate 的 `metadata` 交给宿主(`SkillCandidate.metadata`)。DSH 的注册表把它当作 provider 私有数据原样保存、不渲染进模型目录,因此模型可见的路由依据始终只有名称与 `description`;解析器同时保留字段顺序,供校验确认没有引入规范外字段。
|
|
36
|
+
- **中文触发词与分组**:本地 `lib/taxonomy.js` 为每个技能维护 3–6 个请求原话(「格式转换」「洼地填充」「移动端地图」),作为 `metadata.keywords` 交给宿主;`metadata.groups` 同时给出技能分组并驱动插件配置过滤(`groups`)。这两个键是本包添加的,宿主不认也只是忽略;模型侧命中的仍是英文 `description`,因此路由测试衡量的是「描述 + 触发词」这层判据是否还分得开,而不是网关真的按关键词排序。
|
|
36
37
|
- **可裁剪目录**:插件配置支持 `groups` / `skills` / `exclude` 三个字段,写错的组名或技能名会直接报错而不是静默返回错误的目录。浏览器地图会话可以只留 `web`,不必为 GeoServer 与 PostGIS 的描述付上下文。
|
|
37
38
|
- **交叉引用校验**:`npm run check:citations` 检查适配层指向的技能确实存在(`加载 `x`` 与 `skill({ name: "x" })` 两种写法)、以及引用的三段式版本号能在该技能正文里找到——上游重同步后最容易出现的就是这两类悬空引用。
|
|
38
39
|
|
|
39
40
|
## 兼容性
|
|
40
41
|
|
|
41
|
-
- **DeepSeek Harness**:`>=0.2.0-rc.2 <0.3.0-0`(`package.json` 的 `engines.dsh`)。本包通过 Host 提供的 `ctx.skills` 注册 provider,遵循 `@deepseek-ai/dsh-skill` 的 registry API 与 candidate/definition
|
|
42
|
-
- **candidate `metadata`**:宿主契约里的 `SkillCandidate` 与 `SkillDefinition` 都声明了可选的 `metadata
|
|
42
|
+
- **DeepSeek Harness**:`>=0.2.0-rc.2 <0.3.0-0`(`package.json` 的 `engines.dsh`)。本包通过 Host 提供的 `ctx.skills` 注册 provider,遵循 `@deepseek-ai/dsh-skill` 的 registry API 与 candidate/definition 契约。**已实测版本:`0.2.2-rc.5`**(当前桌面/nightly 发行版)——其中 `registerProvider((control) => provider)`、`list()` 的完整数组简写、`get()` 的 `SkillDefinition | undefined` 返回值、`BUNDLED_SKILL_RANK = 600` 与本包实现一致;更早的 `0.2.x` 版本只在 `engines.dsh` 声明的范围内被假定兼容,未逐一验证。
|
|
43
|
+
- **candidate `metadata`**:宿主契约里的 `SkillCandidate` 与 `SkillDefinition` 都声明了可选的 `metadata`。本包**有意只放在 candidate 上**:registry 的 `toSummary()` 会把它从 `list()` 摘要中丢弃,`skill` 工具渲染也只读名称、描述与正文,所以 definition 不携带它是设计选择而非契约限制;多带一个字段只会增加无谓的载荷。
|
|
43
44
|
- **Node.js**:`>=22`(`engines.node`)。仅开发脚本与测试需要,插件本身运行在 DSH 内。
|
|
44
45
|
- **运行时依赖**:无。`dependencies` 为空,只使用 Node 内置模块,不 import DSH 内部包。
|
|
45
46
|
|
|
@@ -104,7 +105,7 @@ DeepSeek Harness 的 **OpenGIS 技能包插件**:把 [opengis-skills](https://
|
|
|
104
105
|
### 方式一:Plugins 界面(本地目录,适合开发)
|
|
105
106
|
|
|
106
107
|
1. 在 DSH 中打开 **Plugins / 插件** 页面,选择安装 bundle(本地目录方式)。
|
|
107
|
-
2. 目标填**包根目录**的绝对路径,也就是包含 `package.json`
|
|
108
|
+
2. 目标填**包根目录**的绝对路径,也就是包含 `package.json` 的目录,例如 `D:\path\to\dsh-opengis-skill`。
|
|
108
109
|
3. 安装后在列表中找到 **OpenGIS 技能包** 并启用;记录写入当前所选 profile 的插件配置。
|
|
109
110
|
4. 本地目录方式直接引用源码目录,改动会随重载生效,适合开发与试用;正式使用建议走下面的 npm 方式,便于升级与版本校验。
|
|
110
111
|
|
|
@@ -142,7 +143,9 @@ dsh plugin --profile <profile> remove @dsh-gis/dsh-opengis-skill
|
|
|
142
143
|
|
|
143
144
|
## 配置(裁剪目录)
|
|
144
145
|
|
|
145
|
-
技能目录里的 45 条描述每轮对话都在上下文里,约 4226 token。插件配置可以把它裁剪成当前项目真正需要的子集,配置在 bundle
|
|
146
|
+
技能目录里的 45 条描述每轮对话都在上下文里,约 4226 token。插件配置可以把它裁剪成当前项目真正需要的子集,配置在 bundle 的插件行上。
|
|
147
|
+
|
|
148
|
+
这三个字段由 provider 自己在 `apply()` 里校验(不导出 schemastery `Config`,也不会向宿主注册配置 schema):宿主因此只负责传递配置,写错的组名、技能名或「筛完为空」会在插件激活时报错并出现在启动诊断里,而不是静默返回半份目录:
|
|
146
149
|
|
|
147
150
|
```yaml
|
|
148
151
|
- insert:
|
|
@@ -177,11 +180,11 @@ dsh plugin --profile <profile> remove @dsh-gis/dsh-opengis-skill
|
|
|
177
180
|
- **分层存放**:`assets/<skill>/SKILL.md` 是上游逐字节快照;`adaptations/common.md` 是每个技能都会读到的通用约定(技能加载与兄弟技能、reference 分段读取、`ops_bash`/`pwsh`/`run_code` 分工、Windows 改写、后台作业、`present` 交付、`ask_user_question` 确认、沙箱与审批、外部资料);`adaptations/<skill>.md` 是该技能独有的执行建议(先读哪个 reference、命令跑在哪、探测什么版本、怎么验证、哪些操作要先确认)。
|
|
178
181
|
- **加载时拼接**:provider 的 `get` 把「上游正文 + `## DeepSeek Harness 使用建议` + `## DeepSeek Harness 通用约定`」拼成一次加载结果,正文与 `reference/*.md` 的相对链接仍以技能目录为基准解析,不需要额外配置。
|
|
179
182
|
- **硬约束保证「确实是 DSH」**:`<skill>.md` 必须 900–4000 字符、含 5 个固定要点、至少点名 2 个核心工具,「先探测版本」「验证产物」两条必须各带一条反引号命令,并且至少 4 个要点要拆成子条目、全文至少 8 条子条目;`common.md` 至少 14 条要点、覆盖 8 个以上核心工具。工具名从固定白名单里数,所以「读一下文件」这种泛泛叙述不算数。
|
|
180
|
-
-
|
|
183
|
+
- **能力按来源分级**:`lib/adaptations.js` 把工具白名单拆成 `CORE_TOOLS`(DSH 官方分发自带的工具:`bash`/`pwsh`、文件与检索、`job_*`、`subagent` 家族、`skill`、`present`、`todo_write`、Web、`working_directory`、`ask_user_question`、目标与 Agent Teams 等,已对照 `0.2.2-rc.5` 的 `dsh-base` 与 web 预设核实)与 `OPTIONAL_TOOLS`(第三方插件与可选预设:`ops_bash`、`run_code`、`load_workspace_dependencies`、桌面控制、定时任务、MCP 资源、配置管理等);最低引用数只算核心工具,可选工具必须写成「会话提供时……否则退回……」的形态,避免在没有该插件的会话里给出无法执行的指引。
|
|
181
184
|
- **不随上游漂移**:同步只覆盖 `assets/` 与 `upstream.json`,不会碰 `adaptations/`;上游新增技能时 `npm run validate` 会点名缺少适配文件的技能,补齐后再发布,避免悄悄发布一个没有 DSH 指南的技能。
|
|
182
|
-
- **只写这个 harness 里才成立的事实**:通用约定按 DSH 的真实行为写,而不是泛泛的「用终端跑」——前台命令超时会被提升成后台作业并返回 `jobId
|
|
185
|
+
- **只写这个 harness 里才成立的事实**:通用约定按 DSH 的真实行为写,而不是泛泛的「用终端跑」——前台命令超时会被提升成后台作业并返回 `jobId`(不要重跑)、随包 Python 有 numpy/pandas/Pillow 但没有 GDAL/Shapely/GeoPandas 绑定(`load_workspace_dependencies` 只用来取解释器与 Node 路径)、Agent Teams/桌面控制/定时任务属于可选插件(会话里没有就退回 `todo_write` + 后台作业 + `subagent`)、`ops_bash` 与官方 `bash` 是同一个 shell 消费者的两种暴露方式(没有插件时把正文里的 `ops_bash` 换成 `bash`)。
|
|
183
186
|
- **自检**:`npm run check:adaptations` 只校验适配层(可传入技能名);`npm run validate` 会同时校验适配层的结构、长度、工具覆盖、子条目、相对链接,以及适配文件里用反引号提到的 `reference/*.md` 是否真的存在于该技能目录。`npm run check:citations` 再往前一步:校验适配层指向的技能确实存在、引用的三段式版本号能在该技能正文里找到。
|
|
184
|
-
- 命令统一走 DSH 的 shell
|
|
187
|
+
- 命令统一走 DSH 的 shell 工具:官方发行版叫 `bash`,装了 Ops 类插件的部署把它包装成 `ops_bash`,两者参数与行为一致(本包正文默认写 `ops_bash`,没有该插件时换成 `bash`);Windows 的 Bash 是 MSYS,Windows 原生命令用 `pwsh`;只暴露 `run_code` 的 PTC 会话在 TypeScript 程序里按生成的 SDK 调用同名工具。
|
|
185
188
|
- 文件与日志优先用 `read`(分段)/ `grep` / `glob`;大输出先落盘,长任务放后台作业并用 `job_output` 收日志。技能目录与运行时是只读资源,脚本与产物写到会话工作区。
|
|
186
189
|
- 技能正文标注的是上游核验时点的版本(例如 GeoServer 3.0.2、GeoTools 35.2、QGIS 4.2.3 / LTR 3.44.15、GDAL 3.13.3)。实际环境版本不同时,先探测版本,再按“低版本降级”或“高版本新增 API”说明差异,不要照搬不存在的命令。
|
|
187
190
|
- 技能只是领域知识与执行约定,不会替你安装工具、绕过沙箱或读取凭据;安装依赖、启动服务、覆盖数据、执行破坏性 SQL 前先向用户确认,命令与回答中不要回显密码与 token。
|
|
@@ -200,7 +203,7 @@ npm run sync:check -- --from ../opengis-skills
|
|
|
200
203
|
|
|
201
204
|
同步脚本会:逐文件复制 `gis/<skill>/`(文本统一为 LF,保证与上游 git blob 跨平台字节一致)、校验 frontmatter(name 必须为 kebab-case 且与目录同名)、清理上游已删除的技能目录、更新 `upstream.json`,并重新生成 README 中的技能数量与技能表(生成区域由 `<!-- skills:count:* -->` 与 `<!-- skills:* -->` 标记界定)。
|
|
202
205
|
|
|
203
|
-
|
|
206
|
+
当前快照对应上游提交 `upstream.json` 中记录的 `commit`(本版为 `55b87f4`,45 个技能、71 个文件,摘要以清单为准):在上次同步的 `e47ff34` 基础上新增 GEOS、MapLibre GL JS、MapLibre Native、OpenDroneMap、STAC/COG/TiTiler 五个技能,并刷新了 GDAL 统一 CLI 写法、GeoPandas 1.2 的 `make_grid`/`read_file_info`/GeoParquet 2.0、Shapely 2.2 的新函数、PDAL 2.10 的新 stage、GRASS 8.5 的 JSON 输出与 `grass.tools`、MapServer 的 `map2img` 更名、DuckDB 的 GEOMETRY 内置类型等 20 余处正文。上游仍使用 Agent Skills 规范的六字段(`name` / `description` / `license` / `metadata{category,tags}`,另有可选的 `compatibility` 与 `allowed-tools`);本包的解析器认识这层嵌套结构,校验脚本会拒绝规范外字段,因此上游若再改 frontmatter 形状,`npm run validate` 会在发布前报错而不是悄悄丢字段。`sync:check` 做双向比较:既检查已同步文件是否漂移,也检查上游新增/删除的技能是否遗漏。**`adaptations/` 不参与同步**:它属于本仓库的 DSH 适配层,同步只覆盖资产快照;上游新增技能后需要手工补一个 `adaptations/<skill>.md`,否则校验失败。
|
|
204
207
|
|
|
205
208
|
为避免伪造来源,`npm run sync` 要求 `--from` 指向 opengis-skills 的 **git 检出根目录**:脚本用 `git rev-parse --show-toplevel` 校验该目录就是仓库根,避免把外层仓库的 HEAD 误记成上游 commit;无法证明 commit 时同步直接失败。上游 `gis/` 下若出现没有 `SKILL.md` 的目录,同步会报错而不是静默跳过(否则上游改名会静默丢技能);`gis/` 根目录的普通文件(上游分类索引 `gis/SKILL.md` 等)不参与同步,也不会被当作技能打包。
|
|
206
209
|
|
|
@@ -211,11 +214,11 @@ npm run sync:check -- --from ../opengis-skills
|
|
|
211
214
|
需要 Node.js 22+。
|
|
212
215
|
|
|
213
216
|
```bash
|
|
214
|
-
npm run check # validate + check:citations + test,发布前必跑(也是 prepublishOnly)
|
|
217
|
+
npm run check # validate + check:adaptations + check:citations + test,发布前必跑(也是 prepublishOnly)
|
|
215
218
|
npm run check:adaptations [skill...] # 只校验 DSH 适配层,可指定技能
|
|
216
219
|
npm run check:citations # 校验适配层指向的技能与版本号是否仍然存在
|
|
217
220
|
npm run validate # 资产、六字段 frontmatter、内容质量、bundle 接线、完整性清单、分类法与 DSH 适配层
|
|
218
|
-
npm test # Node
|
|
221
|
+
npm test # Node 内置测试运行器(本机装了 DSH 时额外跑真实注册表集成用例)
|
|
219
222
|
npm pack --dry-run # 查看实际发布内容
|
|
220
223
|
```
|
|
221
224
|
|
|
@@ -241,6 +244,7 @@ dsh-opengis-skill/
|
|
|
241
244
|
│ └── <skill>.md # 该技能专属的执行建议
|
|
242
245
|
├── locale/{en,zh}.json # Plugins 里显示的标题与描述
|
|
243
246
|
├── icon.svg # bundle 图标
|
|
247
|
+
├── docs/DETAIL.md # Plugins 详情页正文(locale 的 meta.detail 指向它)
|
|
244
248
|
├── scripts/
|
|
245
249
|
│ ├── sync-opengis-skills.mjs # 上游同步(assets/、upstream.json、README 生成区域)
|
|
246
250
|
│ ├── check-adaptations.mjs # 单独的 DSH 适配层校验(可指定技能)
|
|
@@ -253,7 +257,9 @@ dsh-opengis-skill/
|
|
|
253
257
|
│ ├── catalog.test.mjs # 目录构建与 README 生成区域
|
|
254
258
|
│ ├── markdown-links.test.mjs # 相对链接解析与断链检测
|
|
255
259
|
│ ├── taxonomy.test.mjs # 分类法覆盖与插件配置过滤
|
|
256
|
-
│ ├── routing.test.mjs #
|
|
260
|
+
│ ├── routing.test.mjs # 中文请求的路由判据命中率回归
|
|
261
|
+
│ ├── dsh-contract.test.mjs # 按 DSH 注册表的校验规则回归 candidate/definition
|
|
262
|
+
│ ├── dsh-integration.test.mjs # 在本机已安装的 DSH 注册表里跑一遍 provider(找不到安装则跳过)
|
|
257
263
|
│ └── scripts.test.mjs # 同步/校验脚本(临时目录夹具)
|
|
258
264
|
├── .editorconfig # 编辑器默认值
|
|
259
265
|
├── CHANGELOG.md # 版本变更记录
|
|
@@ -265,11 +271,12 @@ dsh-opengis-skill/
|
|
|
265
271
|
|
|
266
272
|
- **规范注册**:`apply` 时调用 `ctx.skills.registerProvider(() => provider)`;返回的 disposer 由调用方 fiber 拥有,卸载时自动清理,因此**不需要**再套一层 `ctx.effect(...)`。
|
|
267
273
|
- provider 名为 `opengis`,`source` 为 `opengis`,候选 rank 为 600(即 `BUNDLED_SKILL_RANK`,与官方内置技能包一致),`invocation` 为模型与用户均可调用。
|
|
268
|
-
- `list` 只返回元数据(名称、描述、rank、source、`locator`/`path`、`resourceBase`、来自上游 frontmatter 的 `metadata
|
|
269
|
-
- **元数据只放 candidate
|
|
274
|
+
- `list` 只返回元数据(名称、描述、rank、source、`locator`/`path`、`resourceBase`、来自上游 frontmatter 的 `metadata`),每次调用返回一个新数组、元素冻结,调用方排序或截断不会改到 provider 的目录;`get` 每次重新读盘并解析正文与 `adaptations/<skill>.md`,因此编辑资产或适配文件后重新加载插件即可生效。`adaptations/common.md` 在**一个 provider 实例内**缓存一次成功读取的结果(失败的读取不缓存,调用方取消也不会污染共享缓存),避免每加载一个技能重复读同一文件;改动它需要重载插件(或重启 DSH),而不是只重读技能正文。插件不注册工具、不注入提示段、不写会话状态。
|
|
275
|
+
- **元数据只放 candidate**:`metadata.category`/`metadata.tags`/`metadata.groups`/`metadata.keywords` 只出现在 `list` 结果上,`get` 结果保持干净。宿主的两份契约都允许 definition 携带 `metadata`,但 registry 的 `toSummary()` 与 `skill` 工具都不会读它,返回它只是增加载荷;description 始终用上游原文,不因元数据改动而偏移。groups 与 keywords 来自本地 `lib/taxonomy.js`,与上游无关。
|
|
270
276
|
- **目录可裁剪**:`apply(ctx, config)` 读 `groups`/`skills`/`exclude` 三个字段并交给 `selectSkills`;未知组名、未知技能名、筛完为空都直接抛错,因为一次拼错的过滤会静默返回一半目录,比启动失败更难发现。
|
|
271
|
-
-
|
|
277
|
+
- **路由判据有回归**:`test/routing.test.mjs` 给每个技能准备两条中文请求,用关键词命中(×3)与描述里的拉丁词命中(×1)打分,要求 90% 以上命中第一名、全部命中前三名。拉丁词按整词匹配(`geos` 不再命中 `geoserver`),因此这是对「英文描述 + 中文触发词」这层判据的可执行断言:改动关键词或重新同步上游后会立刻报出退步。注意 DSH 的模型侧目录只渲染名称与描述,所以该测试衡量的是判据是否分得开,不是网关真的按关键词排序。
|
|
272
278
|
- **不设 `whenToUse`**:宿主虽然接受这个可选路由字段,但它只在网关的 user-invocable 技能列表(`/` 命令面板)里透出,模型可见的技能目录只渲染 `description`;上游 description 已经按「Use when … / Also for …」写好,再补一份 whenToUse 只会产生第二套会漂移的文案,因此本包不引入。
|
|
279
|
+
- **兼容性有两层回归**:`test/dsh-contract.test.mjs` 按 0.2.2-rc.5 的 `validateCandidate`/`validateDefinition` 规则校验 45 个候选与正文;`test/dsh-integration.test.mjs` 自动探测本机安装的 DeepSeek Harness,用 `ELECTRON_RUN_AS_NODE` 把 provider 装进真实的 `SkillRegistry` 跑一遍(列表、加载、未知技能、取消、重名 provider),找不到安装或设置 `DSH_SKIP_INTEGRATION=1` 时跳过。CI 没有 DSH 时只跑前者,开发机两者都跑。
|
|
273
280
|
- **校验分层**:`npm run validate` 把「会破坏下游契约或让内容不可发现」的问题设为错误(规范外 frontmatter 字段、license 不是 MIT、`metadata.category` 不是 `gis`、tags 数量或语法不对、description 超 500 字符/不以 `Use when` 开头/含尖括号或中文/重复、SKILL.md 超 500 行、`reference/` 有孤儿文件、分类法与技能目录不一致、适配层不达标),把「上游编辑口味」设为警告(缺「截至 YYYY-MM」时效标记、FAQ 少于 5 行、reference 超 100 行没有目录、代码围栏没语言、正文含 emoji),警告不会阻塞发布。
|
|
274
281
|
- **适配层拼接**:`get` 返回的 `content` 是「上游正文 + 分隔线 + `adaptations/<skill>.md` + `adaptations/common.md`」。正文首部保持上游原样,所以 `reference/*.md` 与 `../<skill>/SKILL.md` 的相对链接仍按技能目录解析;共用约定放在最后,保证读到的最后一段是安全与平台约束。适配文件缺失或首行标题不对会直接报错并指出期望路径,而不是静默返回一个没有 DSH 指南的技能。
|
|
275
282
|
- **运行时加固**:frontmatter 解析严格且容忍 UTF-8 BOM(`name` 必须为 kebab-case、`description` 必填,块标量与未闭合引号会报可读错误);上游部分 `description` 存在**未转义的内层双引号**(非法 YAML 但语义明确),解析器按“首尾引号之间全部内容”宽容读取,未知转义保持字面,从而继续与上游字节一致而不必改写快照;`assets/` 缺失时报错会指明期望的资产根目录;`resourceBase` 在 Windows 上也统一输出为正斜杠,跨平台链接一致。
|
package/adaptations/common.md
CHANGED
|
@@ -3,18 +3,19 @@
|
|
|
3
3
|
本节只解决一件事:把上面的 GIS 知识放进 DSH 会话里跑起来。命令细节以技能正文与 `reference/*.md` 为准;本节讲的是技能与 shell 描述、工具说明里没写、但 GIS 任务实际会踩到的部分。
|
|
4
4
|
|
|
5
5
|
- **技能加载**:会话技能目录只给名称与描述,判断匹配就先用 `skill` 按名加载再动手,不要凭目录摘要臆测内容;同一任务里同一个技能不要重复加载。需要相邻技能时同样用 `skill` 加载,而不是用 `read` 读兄弟目录的 `SKILL.md`——两条路径加载到的不一定是同一份内容。`opengis-all` 是索引型入口,先由它定位阶段,再加载具体技能。
|
|
6
|
-
-
|
|
6
|
+
- 判断只看会话技能目录里给出的**名称与描述**:目录不展示候选的 `metadata.keywords`/`groups`,那是宿主侧的路由字段,模型看不到也不该依赖。名称或描述命中就加载,加载后再按正文判断是否切到相邻技能。
|
|
7
7
|
- 本项目只带知识不带能力:装了 MCP 桥(qgis_mcp、gis-mcp、geoserver-mcp 之类)的会话优先调工具,没有桥就用本机 CLI,两者都不要假装已经执行。
|
|
8
8
|
- **引用资料**:加载结果会给出该技能的 Base directory,正文里的 `reference/*.md` 相对它解析。
|
|
9
9
|
- 先用 `read` 读该文件开头的 `## Contents` 定位小节,再按 `offset`/`limit` 分段取用,或用 `grep` 搜关键词、`glob` 找同目录还有哪些文件。
|
|
10
10
|
- 不要把整套参考一次读进上下文;多数任务只需要一个参考文件的两三节。
|
|
11
|
-
-
|
|
11
|
+
- **shell 工具名**:本包正文里的 `ops_bash` 指"会话提供的 Bash 工具"。装了 Ops 类插件的会话叫 `ops_bash`;只装了官方工具的会话叫 `bash`,参数与行为一致——没有 `ops_bash` 时就把正文里的 `ops_bash` 换成 `bash`。两者都是 Windows 下的 MSYS Bash,Windows 原生命令仍走 `pwsh`。只暴露 `run_code` 的 PTC 会话则在 TypeScript 程序里按生成的 SDK 调同名工具。
|
|
12
|
+
- **长任务与后台作业**:启动服务、全库导入、整目录镶嵌、源码编译、大文件重投影这类几分钟以上的活,用 shell 工具的 `run_in_background` 起作业——有 `ops_bash` 就用它,没有 `ops_bash` 时用官方 `bash`,两者都把进程登记成作业。
|
|
12
13
|
- 拿 `jobId` 后用 `job_output`(可带 wait)收日志、`job_kill` 收尾;前台调用超时会被提升成后台作业,这不是失败,别重复再跑一遍。
|
|
13
14
|
- 轮询期间先做别的独立步骤,不要空等;启动类任务等的是就绪日志行,不是固定 sleep。
|
|
14
15
|
- **Windows 改写**:正文里的 `sudo`、`apt-get`、`/tmp`、`export VAR=`、heredoc 都是 Linux 写法。
|
|
15
16
|
- Windows 没有 `sudo`/`apt`,改用官方安装包、conda-forge 或 Docker;环境变量在 `pwsh` 里写 `$env:VAR = "value"`,在 bash 里只能写成单条命令前缀 `VAR=value cmd`。
|
|
16
|
-
- 临时目录用会话工作区;含空格的路径必须整体加引号。装了 OSGeo4W 的机器上 GDAL/MapServer/QGIS 都在 `C
|
|
17
|
-
- **随包运行时**:`load_workspace_dependencies` 返回本机随包 Python/Node
|
|
17
|
+
- 临时目录用会话工作区;含空格的路径必须整体加引号。装了 OSGeo4W 的机器上 GDAL/MapServer/QGIS 都在 `C:\OSGeo4W\bin`(bash 里写 `/c/OSGeo4W/bin`),优先用绝对路径调用,避免 PATH 里残留旧版本。
|
|
18
|
+
- **随包运行时**:`load_workspace_dependencies` 返回本机随包 Python/Node 的绝对路径与随包库清单;没有这个工具时按平台自己探(`python -c "import sys; print(sys.executable)"`、`node -p "process.execPath"`),结论一样。
|
|
18
19
|
- 这套 Python 带 numpy/pandas/Pillow/python-docx/openpyxl,但**没有** GDAL、Shapely、GeoPandas、rasterio、pyproj 绑定,GIS 计算仍要真的装对应发行版或走 OSGeo4W/conda/Docker。
|
|
19
20
|
- 不要拿着随包解释器反复试 import;需要连解释器时用返回的绝对路径,并先 `print(sys.executable)` 确认不是 QGIS/GDAL 自带的那份。
|
|
20
21
|
- **先探测再执行**:先跑版本与可用性探测(`--version`、`ls -l`、`docker --version`、`npm ls <pkg>`),再按实际版本挑命令。
|
package/adaptations/gdal.md
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
- 一次格式转换通常只需要 vector 参考,不要三个文件全读。
|
|
6
6
|
- 需要坐标转换知识时用 `skill` 加载 `proj`,导入后的发布用 `skill` 加载 `geoserver`
|
|
7
7
|
- **执行环境**:命令走 `ops_bash`。
|
|
8
|
-
- Windows 上 `apt-get`/`sudo` 不可用:本机装了 OSGeo4W 时直接调绝对路径(如 `/c/OSGeo4W/bin/ogr2ogr.exe`)或把 `C
|
|
8
|
+
- Windows 上 `apt-get`/`sudo` 不可用:本机装了 OSGeo4W 时直接调绝对路径(如 `/c/OSGeo4W/bin/ogr2ogr.exe`)或把 `C:\OSGeo4W\bin`(bash 里 `/c/OSGeo4W/bin`)加进 `PATH`,否则用 conda-forge(`conda install -c conda-forge gdal`)或容器 `docker run --rm -v "$PWD:/data" -w /data osgeo/gdal:latest`(容器内写成 `/data/...`,别把宿主 `D:\...` 路径直接传进去)。
|
|
9
9
|
- 批量任务前先 `todo_write` 列出「探测版本 → 转换 → 抽检」,千级文件以上分批跑
|
|
10
10
|
- 整目录镶嵌、多源重投影这类几分钟以上的活放后台作业(`run_in_background`),再用 `job_output` 跟进度、`job_kill` 收尾,别让一次调用卡住会话。
|
|
11
11
|
- **先探测版本**:`gdalinfo --version`、`ogrinfo --version` 一次拿到实际版本
|
package/adaptations/grass-gis.md
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
- 正文按 GRASS GIS 8.5.0(8.4 LTR 最新补丁 8.4.2)编写,按任务跳「grass 启动器与无头执行」「g.region 计算区域管理」「数据导入导出」,Python 脚本化看「Python 脚本化」一节。
|
|
5
5
|
- 本技能几乎不需要 `read` 参考文件,但和 `gdal`(`r.out.gdal` 后的格式与元数据核对)、`qgis-process` 经常连用,用 `skill` 按名加载,别去读兄弟目录的 SKILL.md
|
|
6
6
|
- **执行环境**:命令走 `ops_bash`(Windows 下是 MSYS bash)。
|
|
7
|
-
- 正文的 `sudo apt install grass` 在 Windows 不存在:先探测 `grass --version`,没有就走 OSGeo4W 安装器(装好后在 OSGeo4W Shell 里用),或 `conda install -c conda-forge grass`,再不行 `docker run --rm -v "$PWD:/data" -w /data osgeo/grass-gis:latest grass ...`(容器内路径写 `/data`,别把 `D
|
|
7
|
+
- 正文的 `sudo apt install grass` 在 Windows 不存在:先探测 `grass --version`,没有就走 OSGeo4W 安装器(装好后在 OSGeo4W Shell 里用),或 `conda install -c conda-forge grass`,再不行 `docker run --rm -v "$PWD:/data" -w /data osgeo/grass-gis:latest grass ...`(容器内路径写 `/data`,别把 `D:\...` 传进去)。
|
|
8
8
|
- `$HOME/grassdata` 换成会话工作区里的固定目录,避免每次换路径。
|
|
9
9
|
- 正文 `--exec sh -c '...'` 的多行引用在 Windows 上不可靠,改写成单个 `.py` 脚本再用 `grass --tmp-project EPSG:3857 --exec python3 analysis.py`。
|
|
10
10
|
- 整条地形分析链(import → slope → 导出)是长任务,用 `ops_bash` 的 `run_in_background` 跑,`job_output` 看日志。
|
package/docs/DETAIL.md
ADDED
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
# OpenGIS 技能包(@dsh-gis/dsh-opengis-skill)
|
|
2
|
+
|
|
3
|
+
把 [opengis-skills](https://github.com/znlgis/opengis-skills) 的 `gis/` 技能打包成 DeepSeek Harness 的 bundle:**45 个 GIS 技能**,从 GDAL、QGIS、GeoServer、PostGIS 到 CesiumJS、OpenLayers、deck.gl、OpenDroneMap 与 STAC/COG。
|
|
4
|
+
|
|
5
|
+
## 它做什么
|
|
6
|
+
|
|
7
|
+
- **按需加载**:注册 `ctx.skills` provider;会话技能目录只列出名称与描述,正文与 `reference/*.md` 在调用 `skill` 时读取。
|
|
8
|
+
- **只加这层 harness 需要的东西**:上游正文逐字节保留,`adaptations/` 里的 DSH 执行约定(工具映射、Windows 改写、后台作业、产物验证、风险与权限、可选插件退路)在加载时追加。
|
|
9
|
+
- **可裁剪**:插件配置 `groups` / `skills` / `exclude` 把目录裁到当前任务需要的范围,浏览器地图会话不必为服务端与数据库技能付上下文。
|
|
10
|
+
- **可启停**:单包同时是 bundle 与插件(`dsh.bundle.patch`),在 **Plugins** 里启用或停用即可。
|
|
11
|
+
|
|
12
|
+
## 适合谁
|
|
13
|
+
|
|
14
|
+
需要在本机真正跑 GIS 工作流、又想让会话带着领域约定的使用者:数据转换与重投影、服务发布、空间数据库、几何运算、三维与 Web 地图、无人机重建、影像编目。
|
|
15
|
+
|
|
16
|
+
## 不做什么
|
|
17
|
+
|
|
18
|
+
它只提供知识与执行约定,**不会**替你安装 GDAL/QGIS/GeoServer,也不绕过沙箱与审批;缺工具时会告诉你缺什么、怎么装。
|
package/lib/adaptations.js
CHANGED
|
@@ -83,23 +83,31 @@ export const MIN_NESTED_BULLETS = 8;
|
|
|
83
83
|
const FALLBACK = /退回|没有|不一定|可选插件|未启用|不存在/u;
|
|
84
84
|
|
|
85
85
|
/**
|
|
86
|
-
* DeepSeek Harness tools that
|
|
87
|
-
* depend on
|
|
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.
|
|
88
96
|
*/
|
|
89
97
|
export const CORE_TOOLS = Object.freeze([
|
|
90
98
|
"skill",
|
|
91
|
-
"
|
|
99
|
+
"bash",
|
|
92
100
|
"pwsh",
|
|
93
|
-
"run_code",
|
|
94
101
|
"read",
|
|
95
|
-
"grep",
|
|
96
|
-
"glob",
|
|
97
102
|
"write",
|
|
98
103
|
"edit",
|
|
104
|
+
"grep",
|
|
105
|
+
"glob",
|
|
99
106
|
"read_image",
|
|
100
107
|
"present",
|
|
101
108
|
"todo_write",
|
|
102
109
|
"subagent",
|
|
110
|
+
"subagent_fork",
|
|
103
111
|
"ask_user_question",
|
|
104
112
|
"job_output",
|
|
105
113
|
"job_kill",
|
|
@@ -107,30 +115,53 @@ export const CORE_TOOLS = Object.freeze([
|
|
|
107
115
|
"web_fetch",
|
|
108
116
|
"web_search",
|
|
109
117
|
"working_directory",
|
|
110
|
-
"load_workspace_dependencies"
|
|
111
|
-
]);
|
|
112
|
-
|
|
113
|
-
/**
|
|
114
|
-
* DeepSeek Harness tools that arrive with an optional plugin: Agent Teams,
|
|
115
|
-
* desktop control, scheduled tasks, derived "subagent" branches, and MCP
|
|
116
|
-
* resource reads. Guidance may name them, but only together with the fallback
|
|
117
|
-
* that applies when the session does not expose them.
|
|
118
|
-
*/
|
|
119
|
-
export const OPTIONAL_TOOLS = Object.freeze([
|
|
120
|
-
"spawn_teammate",
|
|
121
118
|
"send_message",
|
|
122
119
|
"wait_agent",
|
|
120
|
+
"list_agents",
|
|
121
|
+
"interrupt_agent",
|
|
123
122
|
"team_task_create",
|
|
124
123
|
"team_task_list",
|
|
125
124
|
"team_task_get",
|
|
126
125
|
"team_task_update",
|
|
127
|
-
"
|
|
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",
|
|
128
149
|
"windows_desktop",
|
|
129
150
|
"schedule_create",
|
|
130
151
|
"schedule_list",
|
|
131
152
|
"schedule_edit",
|
|
153
|
+
"schedule_view",
|
|
132
154
|
"list_mcp_resources",
|
|
133
|
-
"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"
|
|
134
165
|
]);
|
|
135
166
|
|
|
136
167
|
/** Every tool name the guidance may cite; the union of both lists. */
|
|
@@ -157,8 +188,16 @@ const SKILL_MIN_CHARACTERS = 900;
|
|
|
157
188
|
/** Maximum characters in one per-skill guidance file. */
|
|
158
189
|
const SKILL_MAX_CHARACTERS = 4000;
|
|
159
190
|
|
|
160
|
-
/**
|
|
161
|
-
|
|
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;
|
|
162
201
|
|
|
163
202
|
/**
|
|
164
203
|
* Build the path of one per-skill adaptation file.
|
|
@@ -205,7 +244,7 @@ export function readAdaptationSync(root, name) {
|
|
|
205
244
|
try {
|
|
206
245
|
text = readFileSync(file, "utf8");
|
|
207
246
|
} catch (cause) {
|
|
208
|
-
throw new Error('
|
|
247
|
+
throw new Error('cannot read the DSH adaptation for skill "' + name + '": ' + file + " (" + describeCause(cause) + "; run npm run validate)", { cause });
|
|
209
248
|
}
|
|
210
249
|
return assertAdaptation(name, normalizeAdaptation(text));
|
|
211
250
|
}
|
|
@@ -223,7 +262,7 @@ export function readCommonSync(root) {
|
|
|
223
262
|
try {
|
|
224
263
|
text = readFileSync(file, "utf8");
|
|
225
264
|
} catch (cause) {
|
|
226
|
-
throw new Error("
|
|
265
|
+
throw new Error("cannot read the shared DSH adaptation: " + file + " (" + describeCause(cause) + "; run npm run validate)", { cause });
|
|
227
266
|
}
|
|
228
267
|
return assertCommon(normalizeAdaptation(text));
|
|
229
268
|
}
|
|
@@ -243,8 +282,8 @@ export async function readAdaptation(root, name, signal) {
|
|
|
243
282
|
try {
|
|
244
283
|
text = await readFile(file, { encoding: "utf8", signal });
|
|
245
284
|
} catch (cause) {
|
|
246
|
-
if (cause
|
|
247
|
-
throw new Error('
|
|
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 });
|
|
248
287
|
}
|
|
249
288
|
return assertAdaptation(name, normalizeAdaptation(text));
|
|
250
289
|
}
|
|
@@ -263,12 +302,43 @@ export async function readCommon(root, signal) {
|
|
|
263
302
|
try {
|
|
264
303
|
text = await readFile(file, { encoding: "utf8", signal });
|
|
265
304
|
} catch (cause) {
|
|
266
|
-
if (cause
|
|
267
|
-
throw new Error("
|
|
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 });
|
|
268
307
|
}
|
|
269
308
|
return assertCommon(normalizeAdaptation(text));
|
|
270
309
|
}
|
|
271
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
|
+
|
|
272
342
|
/**
|
|
273
343
|
* List the adaptation file names (without the ".md" suffix), sorted.
|
|
274
344
|
*
|
package/lib/index.d.ts
CHANGED
|
@@ -16,7 +16,15 @@ export interface OpenGisResourceBase {
|
|
|
16
16
|
path: string;
|
|
17
17
|
}
|
|
18
18
|
|
|
19
|
-
/**
|
|
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;
|
|
@@ -28,7 +36,7 @@ export interface OpenGisSkillMetadata {
|
|
|
28
36
|
keywords: string[];
|
|
29
37
|
}
|
|
30
38
|
|
|
31
|
-
/** One skill summary returned by the provider catalog. */
|
|
39
|
+
/** One skill summary returned by the provider catalog. Frozen; treat as readonly. */
|
|
32
40
|
export interface OpenGisSkillCandidate {
|
|
33
41
|
name: string;
|
|
34
42
|
description: string;
|
|
@@ -54,11 +62,25 @@ export interface OpenGisSkillDefinition {
|
|
|
54
62
|
content: string;
|
|
55
63
|
}
|
|
56
64
|
|
|
57
|
-
/**
|
|
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
|
+
*/
|
|
58
80
|
export interface OpenGisSkillProvider {
|
|
59
81
|
name: string;
|
|
60
|
-
list(options?:
|
|
61
|
-
get(candidate: OpenGisSkillCandidate, options?:
|
|
82
|
+
list(options?: OpenGisSkillLookupOptions): Promise<readonly OpenGisSkillCandidate[]>;
|
|
83
|
+
get(candidate: Pick<OpenGisSkillCandidate, "name">, options?: OpenGisSkillLookupOptions): Promise<OpenGisSkillDefinition | undefined>;
|
|
62
84
|
}
|
|
63
85
|
|
|
64
86
|
/** Plugin config: trim the bundled catalog without editing the package. */
|
|
@@ -70,3 +92,27 @@ export interface OpenGisSkillConfig {
|
|
|
70
92
|
/** Skill deny list, applied last. */
|
|
71
93
|
exclude?: string[];
|
|
72
94
|
}
|
|
95
|
+
|
|
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;
|
package/lib/index.js
CHANGED
|
@@ -21,6 +21,11 @@
|
|
|
21
21
|
* and database skills.
|
|
22
22
|
* - Loading appends the DSH guidance, so the upstream body stays byte-identical.
|
|
23
23
|
*
|
|
24
|
+
* The provider follows the "dsh-skill" contract at the version declared by
|
|
25
|
+
* "engines.dsh": "list()" resolves a complete array of candidates, "get()"
|
|
26
|
+
* resolves the full definition or "undefined" when the instruction file is no
|
|
27
|
+
* longer loadable, and both settle promptly when their abort signal fires.
|
|
28
|
+
*
|
|
24
29
|
* @module @dsh-gis/dsh-opengis-skill
|
|
25
30
|
*/
|
|
26
31
|
|
|
@@ -53,32 +58,41 @@ const name = "opengis-skill";
|
|
|
53
58
|
const inject = ["skills"];
|
|
54
59
|
|
|
55
60
|
/** The invocation policy every bundled skill uses: model and user may load it. */
|
|
56
|
-
const INVOCATION = { modelInvocable: true, userInvocable: true };
|
|
61
|
+
const INVOCATION = Object.freeze({ modelInvocable: true, userInvocable: true });
|
|
62
|
+
|
|
63
|
+
/** File-system error codes that mean "the skill is gone" rather than "the read failed". */
|
|
64
|
+
const MISSING_FILE_CODES = new Set(["ENOENT", "ENOTDIR", "EISDIR"]);
|
|
57
65
|
|
|
58
66
|
/**
|
|
59
|
-
*
|
|
67
|
+
* Report whether one read failure means the instruction file no longer exists.
|
|
68
|
+
*
|
|
69
|
+
* The registry contract asks a provider to resolve "undefined" when a listed
|
|
70
|
+
* candidate can no longer be loaded, so a skill directory removed between
|
|
71
|
+
* discovery and load must not surface as a tool failure.
|
|
60
72
|
*
|
|
61
|
-
*
|
|
62
|
-
*
|
|
63
|
-
* cached: a transient failure must not poison the provider for the rest of the
|
|
64
|
-
* session, and a caller-supplied abort signal must not cancel a shared read
|
|
65
|
-
* that other callers are waiting on.
|
|
73
|
+
* @param cause - the rejection reason from readFile.
|
|
74
|
+
* @returns whether the failure is a missing path.
|
|
66
75
|
*/
|
|
67
|
-
|
|
76
|
+
function isMissingFile(cause) {
|
|
77
|
+
const code = cause?.code;
|
|
78
|
+
return typeof code === "string" && MISSING_FILE_CODES.has(code);
|
|
79
|
+
}
|
|
68
80
|
|
|
69
81
|
/**
|
|
70
|
-
*
|
|
82
|
+
* Combine the registration lifecycle signal with one caller signal.
|
|
83
|
+
*
|
|
84
|
+
* The registry aborts "control.signal" when the exact provider registration is
|
|
85
|
+
* disposed, while "options.signal" cancels one lookup. Either one must settle
|
|
86
|
+
* the read, so the provider races both.
|
|
71
87
|
*
|
|
72
|
-
* @
|
|
88
|
+
* @param signals - the optional signals to race; omitted entries are ignored.
|
|
89
|
+
* @returns the combined signal, or undefined when no signal applies.
|
|
73
90
|
*/
|
|
74
|
-
function
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
});
|
|
80
|
-
}
|
|
81
|
-
return commonContent;
|
|
91
|
+
function combineSignals(...signals) {
|
|
92
|
+
const active = signals.filter((signal) => signal !== undefined);
|
|
93
|
+
if (active.length === 0) return undefined;
|
|
94
|
+
if (active.length === 1) return active[0];
|
|
95
|
+
return AbortSignal.any(active);
|
|
82
96
|
}
|
|
83
97
|
|
|
84
98
|
/**
|
|
@@ -92,71 +106,122 @@ function sharedGuidance() {
|
|
|
92
106
|
* simply ignores the keys.
|
|
93
107
|
*
|
|
94
108
|
* @param skill - the parsed catalog entry.
|
|
95
|
-
* @returns the metadata object carried on the candidate.
|
|
109
|
+
* @returns the frozen metadata object carried on the candidate.
|
|
96
110
|
*/
|
|
97
111
|
function candidateMetadata(skill) {
|
|
98
112
|
const tags = Array.isArray(skill.metadata?.tags) ? skill.metadata.tags : [];
|
|
99
|
-
const metadata = { tags, groups: groupsOf(skill.name), keywords: keywordsOf(skill.name) };
|
|
113
|
+
const metadata = { tags: Object.freeze([...tags]), groups: Object.freeze(groupsOf(skill.name)), keywords: Object.freeze(keywordsOf(skill.name)) };
|
|
100
114
|
if (skill.metadata?.category !== undefined) metadata.category = skill.metadata.category;
|
|
101
|
-
return metadata;
|
|
115
|
+
return Object.freeze(metadata);
|
|
102
116
|
}
|
|
103
117
|
|
|
104
118
|
/**
|
|
105
119
|
* Read and validate the packaged skill catalog, annotating asset failures with
|
|
106
120
|
* the plugin name so a broken installation is diagnosable from the host log.
|
|
107
121
|
*
|
|
122
|
+
* @param assetRoot - absolute directory holding one subdirectory per skill.
|
|
108
123
|
* @returns the validated catalog sorted by name.
|
|
109
124
|
* @throws when the packaged assets are missing or malformed.
|
|
110
125
|
*/
|
|
111
|
-
function loadSkills() {
|
|
126
|
+
function loadSkills(assetRoot) {
|
|
112
127
|
try {
|
|
113
|
-
return readSkillCatalog(
|
|
128
|
+
return readSkillCatalog(assetRoot);
|
|
114
129
|
} catch (cause) {
|
|
115
|
-
throw new Error("opengis-skill: cannot load skill assets from " +
|
|
130
|
+
throw new Error("opengis-skill: cannot load skill assets from " + assetRoot + ": " + cause.message, { cause });
|
|
116
131
|
}
|
|
117
132
|
}
|
|
118
133
|
|
|
119
134
|
/**
|
|
120
|
-
*
|
|
135
|
+
* Create the skill provider over one asset root.
|
|
121
136
|
*
|
|
122
|
-
*
|
|
123
|
-
*
|
|
137
|
+
* This is the testable core of {@link apply}: the packaged entry point only
|
|
138
|
+
* supplies the module-relative roots and the registration-lived abort signal,
|
|
139
|
+
* while a test can point it at a fixture tree.
|
|
124
140
|
*
|
|
125
|
-
* @param
|
|
126
|
-
*
|
|
127
|
-
*
|
|
128
|
-
*
|
|
141
|
+
* @param options - optional overrides: "assetRoot", "adaptationRoot", "config"
|
|
142
|
+
* (the plugin config) and "signal" (the registration lifecycle signal).
|
|
143
|
+
* @returns the provider object the skill registry holds.
|
|
144
|
+
* @throws when the assets are missing or the configuration names an unknown
|
|
145
|
+
* group or skill.
|
|
129
146
|
*/
|
|
130
|
-
function
|
|
131
|
-
const
|
|
132
|
-
const
|
|
147
|
+
export function createProvider(options = {}) {
|
|
148
|
+
const assetRoot = options.assetRoot ?? ASSET_ROOT;
|
|
149
|
+
const adaptationRoot = options.adaptationRoot ?? ADAPTATION_ROOT;
|
|
150
|
+
const lifecycleSignal = options.signal;
|
|
151
|
+
const skills = loadSkills(assetRoot);
|
|
152
|
+
const visible = selectSkills(skills, normalizeSelection(options.config, skills));
|
|
133
153
|
const byName = new Map(visible.map((skill) => [skill.name, skill]));
|
|
134
|
-
const candidates =
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
154
|
+
const candidates = Object.freeze(
|
|
155
|
+
visible.map((skill) =>
|
|
156
|
+
Object.freeze({
|
|
157
|
+
name: skill.name,
|
|
158
|
+
description: skill.description,
|
|
159
|
+
invocation: INVOCATION,
|
|
160
|
+
source: SOURCE,
|
|
161
|
+
provider: PROVIDER_NAME,
|
|
162
|
+
rank: RANK,
|
|
163
|
+
locator: skill.path,
|
|
164
|
+
path: skill.path,
|
|
165
|
+
resourceBase: Object.freeze(resourceBaseOf(skill.directory)),
|
|
166
|
+
// Routing metadata rides on the candidate only. The registry and the
|
|
167
|
+
// "skill" tool never read it (the model-facing catalog renders name and
|
|
168
|
+
// description), so a definition would only carry dead payload. Absent
|
|
169
|
+
// values are omitted rather than emitted as undefined keys.
|
|
170
|
+
metadata: candidateMetadata(skill)
|
|
171
|
+
})
|
|
172
|
+
)
|
|
173
|
+
);
|
|
174
|
+
|
|
175
|
+
/**
|
|
176
|
+
* Cached shared-guidance read.
|
|
177
|
+
*
|
|
178
|
+
* "common.md" is appended to every loaded skill and never changes while the
|
|
179
|
+
* provider runs, so it is read once and reused. Only a successful read is
|
|
180
|
+
* cached: a transient failure must not poison the provider for the rest of
|
|
181
|
+
* the session, and a caller-supplied abort signal must not cancel a shared
|
|
182
|
+
* read that other callers are waiting on.
|
|
183
|
+
*/
|
|
184
|
+
let commonContent;
|
|
185
|
+
|
|
186
|
+
/**
|
|
187
|
+
* Read the shared DSH guidance, memoizing the successful result.
|
|
188
|
+
*
|
|
189
|
+
* @returns the normalized guidance text.
|
|
190
|
+
*/
|
|
191
|
+
function sharedGuidance() {
|
|
192
|
+
if (commonContent === undefined) {
|
|
193
|
+
commonContent = readCommon(adaptationRoot).catch((cause) => {
|
|
194
|
+
commonContent = undefined;
|
|
195
|
+
throw cause;
|
|
196
|
+
});
|
|
197
|
+
}
|
|
198
|
+
return commonContent;
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
return Object.freeze({
|
|
150
202
|
name: PROVIDER_NAME,
|
|
151
|
-
|
|
152
|
-
|
|
203
|
+
// A fresh array per call: the elements stay frozen, but a consumer that
|
|
204
|
+
// sorts or splices the result cannot corrupt the provider's catalog.
|
|
205
|
+
list: () => Promise.resolve([...candidates]),
|
|
206
|
+
async get(candidate, lookup) {
|
|
207
|
+
// A candidate this provider did not list, or one the configuration no
|
|
208
|
+
// longer selects, is "no longer loadable": the registry contract resolves
|
|
209
|
+
// undefined so the caller can report it as unknown instead of failing the
|
|
210
|
+
// whole lookup with a provider-specific error.
|
|
153
211
|
const skill = byName.get(candidate.name);
|
|
154
|
-
if (skill === undefined)
|
|
212
|
+
if (skill === undefined) return undefined;
|
|
213
|
+
const signal = combineSignals(lifecycleSignal, lookup?.signal);
|
|
155
214
|
const [raw, adaptation, common] = await Promise.all([
|
|
156
|
-
readFile(skill.path, { encoding: "utf8", signal
|
|
157
|
-
|
|
215
|
+
readFile(skill.path, { encoding: "utf8", signal }).catch((cause) => {
|
|
216
|
+
// A listed skill whose directory disappeared is "no longer loadable";
|
|
217
|
+
// the registry contract reports that as undefined, not as a failure.
|
|
218
|
+
if (isMissingFile(cause)) return undefined;
|
|
219
|
+
throw cause;
|
|
220
|
+
}),
|
|
221
|
+
readAdaptation(adaptationRoot, skill.name, signal),
|
|
158
222
|
sharedGuidance()
|
|
159
223
|
]);
|
|
224
|
+
if (raw === undefined) return undefined;
|
|
160
225
|
let parsed;
|
|
161
226
|
try {
|
|
162
227
|
parsed = parseSkillFile(raw, skill.path);
|
|
@@ -166,19 +231,35 @@ function apply(ctx, config) {
|
|
|
166
231
|
if (parsed.name !== candidate.name) {
|
|
167
232
|
throw new Error("opengis-skill: " + skill.path + ' now declares "' + parsed.name + '" but was listed as "' + candidate.name + '"');
|
|
168
233
|
}
|
|
169
|
-
return {
|
|
234
|
+
return Object.freeze({
|
|
170
235
|
name: parsed.name,
|
|
171
236
|
description: parsed.description,
|
|
172
|
-
invocation:
|
|
237
|
+
invocation: INVOCATION,
|
|
173
238
|
source: SOURCE,
|
|
174
239
|
provider: PROVIDER_NAME,
|
|
175
|
-
resourceBase: resourceBaseOf(skill.directory),
|
|
240
|
+
resourceBase: Object.freeze(resourceBaseOf(skill.directory)),
|
|
176
241
|
path: skill.path,
|
|
177
242
|
content: composeSkillContent(parsed.content, adaptation, common)
|
|
178
|
-
};
|
|
243
|
+
});
|
|
179
244
|
}
|
|
180
|
-
};
|
|
181
|
-
|
|
245
|
+
});
|
|
246
|
+
}
|
|
247
|
+
|
|
248
|
+
/**
|
|
249
|
+
* Register the bundled OpenGIS skill provider on "ctx.skills".
|
|
250
|
+
*
|
|
251
|
+
* The returned disposer of "registerProvider" is owned by the calling fiber,
|
|
252
|
+
* so plugin unload removes the provider without an extra "ctx.effect" wrapper.
|
|
253
|
+
* The registration-scoped abort signal reaches every load, so an unload cannot
|
|
254
|
+
* leave a half-read skill behind.
|
|
255
|
+
*
|
|
256
|
+
* @param ctx - Cordis context carrying the skill registry.
|
|
257
|
+
* @param config - optional plugin config: "groups" (string[]), "skills"
|
|
258
|
+
* (string[] allow list) and "exclude" (string[] deny list). Unknown names are
|
|
259
|
+
* rejected so a typo cannot silently return the wrong catalog.
|
|
260
|
+
*/
|
|
261
|
+
function apply(ctx, config) {
|
|
262
|
+
ctx.skills.registerProvider((control) => createProvider({ config, signal: control?.signal }));
|
|
182
263
|
}
|
|
183
264
|
|
|
184
265
|
export { apply, inject, name };
|
package/lib/markdown-links.js
CHANGED
|
@@ -11,8 +11,15 @@
|
|
|
11
11
|
import { existsSync } from "node:fs";
|
|
12
12
|
import { dirname, resolve, sep } from "node:path";
|
|
13
13
|
|
|
14
|
-
/**
|
|
15
|
-
|
|
14
|
+
/**
|
|
15
|
+
* One inline markdown link target, as written.
|
|
16
|
+
*
|
|
17
|
+
* The target may not span a line break, and it may contain one level of
|
|
18
|
+
* balanced parentheses: a path such as "reference/foo_(bar).md" is a legal
|
|
19
|
+
* markdown destination, while the naive "[^)]+" would stop at the inner ")" and
|
|
20
|
+
* report a broken link.
|
|
21
|
+
*/
|
|
22
|
+
const LINK = /\]\(((?:[^()\n]|\([^()\n]*\))+)\)/gu;
|
|
16
23
|
|
|
17
24
|
/** A link with a URI scheme or a fragment-only target is not a file link. */
|
|
18
25
|
const NON_FILE_LINK = /^(?:[a-z][a-z0-9+.-]*:|#)/iu;
|
package/lib/taxonomy.js
CHANGED
|
@@ -143,7 +143,7 @@ const SKILL_KEYWORDS = Object.freeze({
|
|
|
143
143
|
postgis: ["PostGIS", "空间数据库", "空间索引", "几何字段"],
|
|
144
144
|
proj: ["PROJ", "坐标转换", "投影参数", "EPSG"],
|
|
145
145
|
projnet4geoapi: ["ProjNet", "坐标转换", "EPSG 解析"],
|
|
146
|
-
pyqgis: ["PyQGIS", "QGIS 脚本", "图层自动化"],
|
|
146
|
+
pyqgis: ["PyQGIS", "QGIS 脚本", "QGIS 环境", "initQgis", "图层自动化"],
|
|
147
147
|
"qgis-process": ["qgis_process", "命令行算法", "无界面运行"],
|
|
148
148
|
"qgis-server": ["QGIS Server", "fcgi", "服务参数调优"],
|
|
149
149
|
shapely: ["Shapely", "缓冲区", "相交判断", "有效性修复"],
|
|
@@ -176,15 +176,52 @@ export function keywordScores(skills, query) {
|
|
|
176
176
|
return skills.map((skill) => {
|
|
177
177
|
let score = 0;
|
|
178
178
|
for (const keyword of keywordsOf(skill.name)) {
|
|
179
|
-
if (query
|
|
179
|
+
if (containsTerm(query, keyword)) score += 3;
|
|
180
180
|
}
|
|
181
181
|
for (const token of descriptionTokens(skill.description)) {
|
|
182
|
-
if (query
|
|
182
|
+
if (containsTerm(query, token)) score += 1;
|
|
183
183
|
}
|
|
184
184
|
return { name: skill.name, score };
|
|
185
185
|
});
|
|
186
186
|
}
|
|
187
187
|
|
|
188
|
+
/**
|
|
189
|
+
* Report whether one lowercased query contains a term as a whole word.
|
|
190
|
+
*
|
|
191
|
+
* A bare "includes" match is a substring test: "geos" fires inside
|
|
192
|
+
* "geoserver" and "jts" inside a version string, which makes two neighbouring
|
|
193
|
+
* skills score identically and turns routing into a coin flip. A term is
|
|
194
|
+
* therefore required to start and end at a non-alphanumeric boundary. The
|
|
195
|
+
* keywords are mostly Chinese, where word boundaries do not exist, so the
|
|
196
|
+
* check keeps the plain substring test whenever the term has no ASCII letter.
|
|
197
|
+
*
|
|
198
|
+
* @param query - the lowercased request text.
|
|
199
|
+
* @param term - the keyword or description token to look for.
|
|
200
|
+
* @returns whether the term occurs in the query.
|
|
201
|
+
*/
|
|
202
|
+
function containsTerm(query, term) {
|
|
203
|
+
const needle = term.toLowerCase();
|
|
204
|
+
if (!/[a-z]/u.test(needle)) return query.includes(needle);
|
|
205
|
+
let index = query.indexOf(needle);
|
|
206
|
+
while (index !== -1) {
|
|
207
|
+
const before = index === 0 ? "" : query[index - 1];
|
|
208
|
+
const after = query[index + needle.length] ?? "";
|
|
209
|
+
if (!isTermCharacter(before) && !isTermCharacter(after)) return true;
|
|
210
|
+
index = query.indexOf(needle, index + 1);
|
|
211
|
+
}
|
|
212
|
+
return false;
|
|
213
|
+
}
|
|
214
|
+
|
|
215
|
+
/**
|
|
216
|
+
* Report whether one character continues a Latin term.
|
|
217
|
+
*
|
|
218
|
+
* @param character - one character, or the empty string at an edge.
|
|
219
|
+
* @returns whether the character is an ASCII letter or digit.
|
|
220
|
+
*/
|
|
221
|
+
function isTermCharacter(character) {
|
|
222
|
+
return character.length > 0 && /[a-z0-9]/u.test(character);
|
|
223
|
+
}
|
|
224
|
+
|
|
188
225
|
/**
|
|
189
226
|
* Extract the Latin tokens of one description.
|
|
190
227
|
*
|
package/locale/en.json
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"meta": {
|
|
3
|
+
"detail": "docs/DETAIL.md",
|
|
3
4
|
"title": "OpenGIS Skills",
|
|
4
5
|
"description": "45 GIS skills from opengis-skills (GDAL, QGIS, GeoServer, PostGIS, DuckDB Spatial, JTS, GEOS, CesiumJS, OpenLayers, MapLibre, OpenDroneMap, STAC/COG and more) loaded on demand, each extended with a DeepSeek Harness execution layer: tool mapping, background jobs, artifact verification and consent gates."
|
|
5
6
|
}
|
package/locale/zh.json
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"meta": {
|
|
3
|
+
"detail": "docs/DETAIL.md",
|
|
3
4
|
"title": "OpenGIS 技能包",
|
|
4
5
|
"description": "来自 opengis-skills 的 45 个 GIS 技能:GDAL、QGIS、GeoServer、PostGIS、DuckDB Spatial、JTS、GEOS、CesiumJS、OpenLayers、MapLibre、OpenDroneMap、STAC/COG 等。正文与参考资料按需加载,并附带 DeepSeek Harness 执行层(工具映射、后台作业、产物验证、权限确认)。"
|
|
5
6
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@dsh-gis/dsh-opengis-skill",
|
|
3
|
-
"version": "0.5.
|
|
3
|
+
"version": "0.5.1",
|
|
4
4
|
"description": "OpenGIS skill pack for DeepSeek Harness: the 45 gis/ skills from opengis-skills, vendored byte-for-byte and loaded on demand, plus a DeepSeek Harness execution layer (tool mapping, background jobs, verification, consent, upstream routing metadata) appended at load time.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "lib/index.js",
|
|
@@ -23,6 +23,7 @@
|
|
|
23
23
|
"files": [
|
|
24
24
|
"lib",
|
|
25
25
|
"assets",
|
|
26
|
+
"docs",
|
|
26
27
|
"adaptations",
|
|
27
28
|
"cordis.patch.yml",
|
|
28
29
|
"locale/*.json",
|
|
@@ -49,7 +50,7 @@
|
|
|
49
50
|
"check:adaptations": "node scripts/check-adaptations.mjs",
|
|
50
51
|
"check:citations": "node scripts/check-citations.mjs",
|
|
51
52
|
"test": "node --test",
|
|
52
|
-
"check": "npm run validate && npm run check:citations && npm test",
|
|
53
|
+
"check": "npm run validate && npm run check:adaptations && npm run check:citations && npm test",
|
|
53
54
|
"prepublishOnly": "npm run check"
|
|
54
55
|
},
|
|
55
56
|
"repository": {
|