@xuanling-rs/xuanling-dsh-tools 0.6.1 → 0.8.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/README-ZH.md +96 -18
- package/README.md +104 -27
- package/package.json +4 -4
package/README-ZH.md
CHANGED
|
@@ -2,31 +2,109 @@
|
|
|
2
2
|
|
|
3
3
|
[English](README.md) | 简体中文
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
5
|
+
**完整 XuanLing MCP catalog 的增量式 DeepSeek Harness bundle：在 DSH 原生工具
|
|
6
|
+
之外增加全部 43 个带类型工具。** Package：
|
|
7
|
+
`@xuanling-rs/xuanling-dsh-tools@0.8.1`。
|
|
8
|
+
|
|
9
|
+
## 这是什么
|
|
10
|
+
|
|
11
|
+
以 `mcp__xuanling__` 前缀提供完整 catalog，同时保留全部 Harness 原生工具：
|
|
12
|
+
|
|
13
|
+
- **Core（3）：** `system_info`、`path_resolve`、`path_relative`。
|
|
14
|
+
- **Filesystem（17）：** `fs_stat`、`fs_list`、`fs_read_text`、
|
|
15
|
+
`fs_read_bytes`、`fs_search`、`fs_glob`、`fs_hash`、`fs_mkdir`、
|
|
16
|
+
`fs_write_text`、`fs_replace_text`、`fs_patch`、`fs_edit_preview`、
|
|
17
|
+
`fs_edit`、`fs_edit_batch`、`fs_copy`、`fs_move`、`fs_remove`。
|
|
18
|
+
- **Process and project（5）：** `process_run`、`process_which`、
|
|
19
|
+
`project_detect`、`project_command`、`project_run`。
|
|
20
|
+
- **Memory v2（9）与 Advanced（9）：** 完整 Memory 生命周期，以及 artifact、
|
|
21
|
+
ChangeSet、pipeline 和 session。
|
|
22
|
+
|
|
23
|
+
Server 使用默认的 `all` catalog；本 bundle 没有更小的 profile 开关。
|
|
24
|
+
|
|
25
|
+
## 为什么用它
|
|
26
|
+
|
|
27
|
+
- **适合**：需要 XuanLing 文件系统族、直接进程执行、项目探测/执行、artifact、
|
|
28
|
+
ChangeSet、pipeline 或 session。
|
|
29
|
+
- **只需要 Memory**：改用 `xuanling-dsh-memory`，那是更精简的推荐日常配置。
|
|
30
|
+
- **只想要原生命名下的 XuanLing 文件语义**：改用
|
|
31
|
+
`xuanling-dsh-tools-replace`。
|
|
32
|
+
- 每个 profile 只装一个 XuanLing runtime bundle；详见
|
|
33
|
+
[bundle 指南](../README-ZH.md)。
|
|
34
|
+
|
|
35
|
+
## 环境要求
|
|
36
|
+
|
|
37
|
+
- 已安装 DSH，并使用内置的 `web` 或 `headless` profile。
|
|
38
|
+
- Node.js 22.14 或更高版本。
|
|
39
|
+
- DSH 在 `0.2.1-rc.2` 能力频道上提供 `@deepseek-ai/dsh-mcp-client`。
|
|
40
|
+
- 在启动 DSH 的环境中把 `XUANLING_WORKSPACE_ROOT` 设为已确认的绝对 workspace
|
|
41
|
+
路径；缺失时启动失败。
|
|
42
|
+
- macOS ARM64、glibc 2.35+ 的 Linux x64，或带 MSVC runtime 的 Windows x64。
|
|
43
|
+
|
|
44
|
+
## 安装
|
|
7
45
|
|
|
8
46
|
```sh
|
|
9
|
-
|
|
47
|
+
export XUANLING_WORKSPACE_ROOT=/absolute/path/to/project
|
|
48
|
+
dsh plugin --profile web add @xuanling-rs/xuanling-dsh-tools@0.8.1
|
|
49
|
+
dsh --profile web --dump-config
|
|
10
50
|
```
|
|
11
51
|
|
|
12
|
-
|
|
13
|
-
|
|
52
|
+
请让启动 DSH 的每个进程都能看到该变量。内置 headless profile 使用
|
|
53
|
+
`--profile headless`；自定义的新 profile 名称只会从 base bundle 起步。该命令会
|
|
54
|
+
把 `@xuanling-rs/xuanling-mcp@0.8.1` 装进 profile；不需要全局 package 或 `npx`。
|
|
55
|
+
|
|
56
|
+
## 快速开始
|
|
57
|
+
|
|
58
|
+
1. 重启该 profile，然后刷新 DSH。
|
|
59
|
+
2. 让模型检索 `mcp_catalog__xuanling` 中的 `system_info` 并激活它；调用
|
|
60
|
+
`mcp__xuanling__system_info`，确认 `xuanling_version` 为 `0.8.1`。
|
|
61
|
+
3. 再激活一个文件系统工具，例如 `fs_stat`，读取 `XUANLING_WORKSPACE_ROOT` 内的
|
|
62
|
+
路径。根目录之外的路径会被有意拒绝。
|
|
63
|
+
|
|
64
|
+
## 配置
|
|
65
|
+
|
|
66
|
+
- `XUANLING_WORKSPACE_ROOT` 必填且必须是绝对路径，是文件系统 capability root；
|
|
67
|
+
DSH 进程工作目录永远不是授权来源。
|
|
68
|
+
- Memory 族使用共享默认库 `~/.xuanling/memory.db`，在第一次有效 Memory 调用时
|
|
69
|
+
才延迟打开。
|
|
70
|
+
- 模型起初只能看到 `mcp_catalog__xuanling`。检索它，每次调用只激活一个精确
|
|
71
|
+
raw name，下一次请求才会出现对应工具；不要预先激活整个 catalog。
|
|
72
|
+
- 单次工具调用预算 120 秒。长构建和 watch 进程应交给 Harness 后台 job。
|
|
73
|
+
- 进程工具以显式 program + argv 运行且不经过 shell，默认使用最小环境
|
|
74
|
+
（`inherit_env: false`）。
|
|
75
|
+
- server name 固定为 `xuanling`；模型可见工具名是 `mcp__xuanling__*`。
|
|
14
76
|
|
|
15
|
-
|
|
16
|
-
启动；不需要也不会使用全局 npm package。启动 DSH 前必须把 `XUANLING_WORKSPACE_ROOT` 设置为
|
|
17
|
-
已确认的绝对 workspace；缺失时 bundle 会启动失败，DSH 进程工作目录不会被当成用户授权。
|
|
77
|
+
## 限制与安全边界
|
|
18
78
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
79
|
+
- **能力重叠确实存在。** 原生工具与 XuanLing 工具在文件、进程和项目操作上高度
|
|
80
|
+
重叠；每次操作要有意识地选一族。
|
|
81
|
+
- **文件系统受限。** XuanLing 文件系统工具在 `XUANLING_WORKSPACE_ROOT` 下执行
|
|
82
|
+
pathname capability；越界路径会被拒绝。
|
|
83
|
+
- **进程执行不是沙箱。** 不可信代码仍需宿主审批和 OS sandbox；默认使用最小
|
|
84
|
+
环境。
|
|
85
|
+
- **共享存储。** `~/.xuanling/memory.db` 与其他 XuanLing 部署共享；不要在其中
|
|
86
|
+
保存 secret 或用户私密内容。
|
|
87
|
+
- **Lazy 激活有成本。** 每个新工具都要多一步激活和一轮模型请求，激活集合不会跨
|
|
88
|
+
重启保留。
|
|
89
|
+
- **平台限制。** 不支持的 OS、CPU 或 libc 组合会由 launcher 明确报错。
|
|
22
90
|
|
|
23
|
-
|
|
24
|
-
意外文本块。
|
|
91
|
+
## 排错
|
|
25
92
|
|
|
26
|
-
|
|
27
|
-
|
|
93
|
+
- **启动因缺少 `XUANLING_WORKSPACE_ROOT` 失败。** 在 DSH 进程的环境中 export
|
|
94
|
+
已确认的绝对路径后重启。
|
|
95
|
+
- **只看到 `mcp_catalog__xuanling`。** 正常。检索并激活精确 raw name；激活时
|
|
96
|
+
不要带 `mcp__xuanling__` 前缀。
|
|
97
|
+
- **工具调用触到 120 秒预算。** 把长任务移到 Harness 后台 job，再用后续调用
|
|
98
|
+
继续。
|
|
99
|
+
- **`inherit_env: false` 下找不到程序。** 只有明确可接受继承登录环境时才用
|
|
100
|
+
`inherit_env: true` 重试。
|
|
101
|
+
- **launcher 或版本不一致。** 重装精确的 `0.8.1` 版本；不要在同一个 profile 内
|
|
102
|
+
混用版本，并移除其他 XuanLing runtime bundle。
|
|
28
103
|
|
|
29
|
-
|
|
30
|
-
`@xuanling-rs/xuanling-dsh-memory`。不要在同一 profile 内安装多个 XuanLing 工具 bundle。
|
|
104
|
+
## 链接
|
|
31
105
|
|
|
32
|
-
|
|
106
|
+
- [XuanLing for DeepSeek Harness：bundle 指南与运行配置](../README-ZH.md)
|
|
107
|
+
- [XuanLing Blueprint：可视化工作流编辑器与可持久运行](../xuanling-blueprint/README-ZH.md)
|
|
108
|
+
- [XuanLing MCP server 项目](../../../README-ZH.md)
|
|
109
|
+
- [npm package](https://www.npmjs.com/package/@xuanling-rs/xuanling-dsh-tools)
|
|
110
|
+
- [Issues](https://github.com/umbrella22/xuanling/issues)
|
package/README.md
CHANGED
|
@@ -2,40 +2,117 @@
|
|
|
2
2
|
|
|
3
3
|
English | [Simplified Chinese](README-ZH.md)
|
|
4
4
|
|
|
5
|
-
Additive DeepSeek Harness bundle for the complete XuanLing MCP catalog
|
|
6
|
-
|
|
7
|
-
|
|
5
|
+
**Additive DeepSeek Harness bundle for the complete XuanLing MCP catalog: all
|
|
6
|
+
43 typed tools, added next to DSH's native tools.** Package
|
|
7
|
+
`@xuanling-rs/xuanling-dsh-tools@0.8.1`.
|
|
8
|
+
|
|
9
|
+
## What it is
|
|
10
|
+
|
|
11
|
+
Adds the full catalog under the `mcp__xuanling__` prefix while keeping every
|
|
12
|
+
native Harness tool:
|
|
13
|
+
|
|
14
|
+
- **Core (3):** `system_info`, `path_resolve`, `path_relative`.
|
|
15
|
+
- **Filesystem (17):** `fs_stat`, `fs_list`, `fs_read_text`, `fs_read_bytes`,
|
|
16
|
+
`fs_search`, `fs_glob`, `fs_hash`, `fs_mkdir`, `fs_write_text`,
|
|
17
|
+
`fs_replace_text`, `fs_patch`, `fs_edit_preview`, `fs_edit`, `fs_edit_batch`,
|
|
18
|
+
`fs_copy`, `fs_move`, `fs_remove`.
|
|
19
|
+
- **Process and project (5):** `process_run`, `process_which`,
|
|
20
|
+
`project_detect`, `project_command`, `project_run`.
|
|
21
|
+
- **Memory v2 (9) and Advanced (9):** the full Memory lifecycle, plus artifacts,
|
|
22
|
+
ChangeSets, pipelines, and sessions.
|
|
23
|
+
|
|
24
|
+
The server runs its default `all` catalog; this bundle has no smaller profile
|
|
25
|
+
switch.
|
|
26
|
+
|
|
27
|
+
## Why use it
|
|
28
|
+
|
|
29
|
+
- **Use it** when you need the XuanLing filesystem family, direct processes,
|
|
30
|
+
project detection/execution, artifacts, ChangeSets, pipelines, or sessions.
|
|
31
|
+
- **Use `xuanling-dsh-memory`** for the smaller recommended Memory-only setup.
|
|
32
|
+
- **Use `xuanling-dsh-tools-replace`** for XuanLing semantics under native
|
|
33
|
+
`read`/`write`/`edit` names.
|
|
34
|
+
- Install exactly one XuanLing runtime bundle per profile; see the
|
|
35
|
+
[bundle guide](../README.md).
|
|
36
|
+
|
|
37
|
+
## Requirements
|
|
38
|
+
|
|
39
|
+
- DSH with the shipped `web` or `headless` profile.
|
|
40
|
+
- Node.js 22.14 or newer.
|
|
41
|
+
- A DSH build that provides `@deepseek-ai/dsh-mcp-client` from the
|
|
42
|
+
`0.2.1-rc.2` capability channel.
|
|
43
|
+
- `XUANLING_WORKSPACE_ROOT` set to the confirmed absolute workspace in the
|
|
44
|
+
environment that launches DSH; startup fails when it is missing.
|
|
45
|
+
- macOS ARM64, Linux x64 with glibc 2.35+, or Windows x64 with MSVC.
|
|
46
|
+
|
|
47
|
+
## Install
|
|
8
48
|
|
|
9
49
|
```sh
|
|
10
|
-
|
|
50
|
+
export XUANLING_WORKSPACE_ROOT=/absolute/path/to/project
|
|
51
|
+
dsh plugin --profile web add @xuanling-rs/xuanling-dsh-tools@0.8.1
|
|
52
|
+
dsh --profile web --dump-config
|
|
11
53
|
```
|
|
12
54
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
55
|
+
Keep the variable in the environment of every process that starts DSH. Use
|
|
56
|
+
`--profile headless` for the headless profile; a custom new profile name starts
|
|
57
|
+
from the base bundle only. The profile gets
|
|
58
|
+
`@xuanling-rs/xuanling-mcp@0.8.1`; no global package or `npx` is needed.
|
|
59
|
+
|
|
60
|
+
## Quickstart
|
|
61
|
+
|
|
62
|
+
1. Restart the profile and refresh DSH.
|
|
63
|
+
2. Ask the model to search `mcp_catalog__xuanling` for `system_info` and
|
|
64
|
+
activate it; call `mcp__xuanling__system_info` and check that
|
|
65
|
+
`xuanling_version` is `0.8.1`.
|
|
66
|
+
3. Activate one filesystem tool, for example `fs_stat`, and read a path inside
|
|
67
|
+
`XUANLING_WORKSPACE_ROOT`. Paths outside the root are denied by design.
|
|
68
|
+
|
|
69
|
+
## Configuration
|
|
70
|
+
|
|
71
|
+
- `XUANLING_WORKSPACE_ROOT` is required, absolute, and is the filesystem
|
|
72
|
+
capability root; the DSH process working directory is never authorization.
|
|
73
|
+
- The Memory family uses the shared default `~/.xuanling/memory.db`, opened
|
|
74
|
+
lazily on the first valid Memory call.
|
|
75
|
+
- Only `mcp_catalog__xuanling` is visible initially. Search it and activate one
|
|
76
|
+
exact raw name per call; the tool appears on the next request. Do not
|
|
77
|
+
activate the whole catalog speculatively.
|
|
78
|
+
- Tool-call budget: 120 seconds. Long builds and watch processes belong to
|
|
79
|
+
Harness background jobs.
|
|
80
|
+
- Process tools run explicit program + argv without a shell and use a minimal
|
|
81
|
+
environment by default (`inherit_env: false`).
|
|
82
|
+
- The server name is fixed to `xuanling`; public names are `mcp__xuanling__*`.
|
|
16
83
|
|
|
17
|
-
|
|
18
|
-
through its verified JS launcher. A global npm package is neither required nor
|
|
19
|
-
used. Set `XUANLING_WORKSPACE_ROOT` to the confirmed absolute workspace before
|
|
20
|
-
starting DSH; the bundle fails startup when it is absent and never treats the
|
|
21
|
-
DSH process working directory as user authorization.
|
|
84
|
+
## Limits and safety
|
|
22
85
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
not
|
|
86
|
+
- **Capability overlap is real.** Native and XuanLing tools cover similar file,
|
|
87
|
+
process, and project work; pick one family per operation deliberately.
|
|
88
|
+
- **Filesystem confinement.** XuanLing filesystem tools enforce pathname
|
|
89
|
+
capabilities under `XUANLING_WORKSPACE_ROOT`; escaping paths are denied.
|
|
90
|
+
- **Process execution is not a sandbox.** Untrusted code still needs host
|
|
91
|
+
approval and an OS sandbox; minimal environments are the default.
|
|
92
|
+
- **Shared store.** `~/.xuanling/memory.db` is shared with other XuanLing
|
|
93
|
+
deployments; never put secrets or private user content in it.
|
|
94
|
+
- **Lazy activation has a cost.** Each new tool costs an activation step and an
|
|
95
|
+
extra model turn, and activation sets do not survive a restart.
|
|
96
|
+
- **Platform limits.** Unsupported OS, CPU, or libc combinations fail with an
|
|
97
|
+
explicit launcher error.
|
|
28
98
|
|
|
29
|
-
|
|
30
|
-
removes only accidental duplicate text blocks that exactly repeat
|
|
31
|
-
`structuredContent`.
|
|
99
|
+
## Troubleshooting
|
|
32
100
|
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
101
|
+
- **Startup fails with a missing `XUANLING_WORKSPACE_ROOT`.** Export the
|
|
102
|
+
confirmed absolute path in the environment of the DSH process, then restart.
|
|
103
|
+
- **Only `mcp_catalog__xuanling` is visible.** Expected. Search and activate
|
|
104
|
+
exact raw names; use the name without the `mcp__xuanling__` prefix.
|
|
105
|
+
- **A tool call hits the 120-second budget.** Move the long work to a Harness
|
|
106
|
+
background job and resume with a follow-up call.
|
|
107
|
+
- **A program is not found with `inherit_env: false`.** Retry with
|
|
108
|
+
`inherit_env: true` only when inheriting the login environment is acceptable.
|
|
109
|
+
- **Launcher or version mismatch.** Reinstall the exact `0.8.1` version; do not
|
|
110
|
+
mix versions in one profile, and remove any other XuanLing runtime bundle.
|
|
36
111
|
|
|
37
|
-
|
|
38
|
-
`@xuanling-rs/xuanling-dsh-memory` for the smaller daily tool surface. Do not install this
|
|
39
|
-
package with another XuanLing tool bundle in the same profile.
|
|
112
|
+
## Links
|
|
40
113
|
|
|
41
|
-
|
|
114
|
+
- [XuanLing for DeepSeek Harness: bundle guide and runtime configuration](../README.md)
|
|
115
|
+
- [XuanLing Blueprint: visual workflow editor and durable runs](../xuanling-blueprint/README.md)
|
|
116
|
+
- [XuanLing MCP server project](../../../README.md)
|
|
117
|
+
- [npm package](https://www.npmjs.com/package/@xuanling-rs/xuanling-dsh-tools)
|
|
118
|
+
- [Issues](https://github.com/umbrella22/xuanling/issues)
|
package/package.json
CHANGED
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@xuanling-rs/xuanling-dsh-tools",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.8.1",
|
|
4
4
|
"description": "DeepSeek Harness bundle: lazily mount XuanLing through a bundle-owned wrapper around the official MCP bridge. Additive variant: built-in tools stay enabled.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"private": false,
|
|
7
7
|
"dependencies": {
|
|
8
|
-
"@deepseek-ai/dsh-mcp-client": "^0.1
|
|
9
|
-
"@xuanling-rs/xuanling-mcp": "0.
|
|
8
|
+
"@deepseek-ai/dsh-mcp-client": "^0.2.1-rc.2",
|
|
9
|
+
"@xuanling-rs/xuanling-mcp": "0.8.1"
|
|
10
10
|
},
|
|
11
11
|
"files": [
|
|
12
12
|
"LICENSE",
|
|
@@ -39,6 +39,6 @@
|
|
|
39
39
|
"registry": "https://registry.npmjs.org"
|
|
40
40
|
},
|
|
41
41
|
"xuanlingRelease": {
|
|
42
|
-
"sourceCommit": "
|
|
42
|
+
"sourceCommit": "300ddda8cd8ac2876f34b86840733cfe9f6cc8ce"
|
|
43
43
|
}
|
|
44
44
|
}
|