@lynn123411/dsh-web-auth-url 0.1.2 → 0.1.4

package/README.md

@@ -5,10 +5,11 @@ DSH Web GUI 的访问鉴权补位：把当前实例**带 token 的访问地址**
 ## 特性
 
 - **`DSH_WEB_AUTH_URL` 托管环境变量**：每次 shell 调用即时解析的带 token 回环地址（`http://127.0.0.1:<port>/?token=…`），DSH 重启换 token 后自动跟随；不缓存、不落盘。
-- **提示词段落 `app:web-auth-url`**：紧随 `app:web-surface`（order + 10）贡献一段说明——只报变量名、不报值，并交代必需用法：第一次请求 `curl -c "$JAR" -b "$JAR" "$DSH_WEB_AUTH_URL"` 拿到 303 并种下 cookie，之后复用同一个 jar 即已授权。
-- **`prompt` 三档**：`env`（默认）只报变量名，token 不进提示词与 transcript；`inline` 把带 token 的地址直接写进段落（地址每次装配即时解析，重启后不过期，但 token 会随请求发给模型服务商并落盘进 session）；`off` 只保留环境变量。
+- **提示词段落 `app:web-auth-url`**：紧随 `app:web-surface`（order + 10）贡献一段说明——只报变量名、不报值，并交代必需用法：第一次请求 `curl -s -c "$JAR" -b "$JAR" -o /dev/null -w '%{http_code}' "$DSH_WEB_AUTH_URL"` 拿到 303 并种下 cookie，**之后复用同一个 jar、不再带 token**（token 只对 `GET /` 有效，其余路径带它一律 401）。
+- **`prompt` 三档**：`env`（默认）只报变量名，token 不进提示词与 transcript；`inline` 把带 token 的地址直接写进段落（地址每次装配即时解析，重启后不过期，但 token 会随请求发给模型服务商并落盘进 session）；`off` 只保留环境变量。两档共用同一份句式，只有地址那处被替换。
 - **无 web 部署静默降级**：CLI / TUI / 缺 `connection` 的组合下注册照常完成，但 `resolve` 返回空、段落渲染成空串，而空段落由内核 `renderPrompt` 过滤，系统提示词里不留痕迹。
 - **不新增端口、不新增凭据**：token 取自已装载的 `connection` 服务，与启动时打印到 stdout 的是同一个。
+- **`selfDir()`**：本插件自身安装目录的真实路径（预留工具，当前无调用方）。开发副本是 `link:` 软链接且 `~/.dsh` 与仓库常在不同卷，`ctx.pluginPackages.packageOf(...)` 会返回链接路径；`selfDir()` 走 Node 解析器 + `realpath`，正常发布安装下两者相同。
 
 ## 安装
 

package/lib/index.js

@@ -1,34 +1,31 @@
 /**
  * @lynn123411/dsh-web-auth-url — 宿主半区（node）。
  *
- * Web GUI 的每个请求都要过 connection 的浏览器会话鉴权，而鉴权的入口只有
- * 一个：带本进程 launch token 的根地址。干净地址 `http://127.0.0.1:<port>`
- * 一律 401，而且这是 `dsh-web-app` 有意为之——它把干净地址交给模型
- * （`app:web-surface` 段落）和 shell（`DSH_WEB_URL`），带 token 的地址只
- * 打印到 stdout、交给默认浏览器。
+ * connection 的浏览器会话鉴权只有一个入口：带本进程 launch token 的根地址；
+ * `dsh-web-app` 有意只把干净地址交给模型与 shell，带 token 的地址仅打印到
+ * stdout。于是模型自测这个 GUI 时第一枪必然 401。本插件补上这个缺口而不把
+ * secret 放进提示词或 transcript：托管 `DSH_WEB_AUTH_URL`（每次 shell 调用
+ * 即时解析，跟随重启后的 token 轮换），并紧随 `app:web-surface` 说明它的
+ * 用法——只报变量名，`prompt: 'inline'` 才把地址写进段落。
  *
- * 代价是模型想自测这个 GUI（抓页面、探路由、确认客户端插件有没有生效）时
- * 第一枪必然 401，只能翻启动器日志找 token。本插件补上这个缺口，同时不把
- * secret 放进提示词或 transcript：
- *
- * 1. `DSH_WEB_AUTH_URL` —— 每次 shell 调用**即时解析**的带 token 地址，
- *    因此 DSH 重启换 token 后自动跟随（静态字符串做不到这一点）。
- * 2. 紧随 `app:web-surface`（order + 10）的一段提示词，说明该地址存在，
- *    以及「第一次请求 303 换 cookie、之后复用同一个 jar」这个必需用法——
- *    只报变量名，不报值；`prompt: 'inline'` 才把地址直接写进段落。
- *
- * 没有 web 部署的宿主（CLI / TUI / 缺 connection 的组合）不是错误路径：注册
- * 照常完成，`resolve` 返回空、段落渲染成空串，而空段落会被 renderPrompt
- * 过滤掉，系统提示词里不留痕迹。
+ * 没有 web 部署的宿主不是错误路径：注册照常完成，值解析为空、段落渲染成空
+ * 串，而空段落会被 renderPrompt 过滤掉。
  *
  * @module dsh-web-auth-url
  */
 
 import z from '@deepseek-ai/schemastery'
 
+import { realpathSync } from 'node:fs'
+import { basename, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
 /** Cordis 插件名（= patch 行 id）。 */
 export const name = 'dsh-web-auth-url'
 
+/** npm 包名：{@link selfDir} 靠它从本模块 URL 解析自身安装位置。 */
+const PKG_NAME = '@lynn123411/dsh-web-auth-url'
+
 /** 本插件不硬依赖任何服务：web 服务缺失时静默降级，见模块头。 */
 export const inject = []
 
@@ -38,9 +35,6 @@ const LOOPBACK_HOST = '127.0.0.1'
 /** 本插件唯一登记的托管环境变量。 */
 const AUTH_URL_KEY = 'DSH_WEB_AUTH_URL'
 
-/** web-app 交给 shell 的干净地址，只在提示词里做对照。 */
-const CLEAN_URL_KEY = 'DSH_WEB_URL'
-
 /** shellEnv 贡献者名。 */
 const CONTRIBUTOR_NAME = 'dsh-web-auth-url'
 
@@ -50,6 +44,26 @@ const SECTION_NAME = 'app:web-auth-url'
 /** 段落排在 `app:web-surface` 之后，紧挨着它所补充的那段话。 */
 const SECTION_OFFSET = 10
 
+/** 段落里出现 token 地址的位置（`env` 档保留字面量，`inline` 档换成实址）。 */
+const URL_PLACEHOLDER = `$${AUTH_URL_KEY}`
+
+/**
+ * 段落模板：两档共用一份句式，只替换地址，文案不会各自漂移。
+ *
+ * 首句借 `$DSH_WEB_URL` 把这段挂到 `app:web-surface` 刚报的那台 GUI 上（那
+ * 段不提 token / 401 / cookie，两段不重复）；末句点明「token 只用于第一次
+ * 换 cookie」——connection 的 token 分支要求 `GET /` 且 pathname 恰为 `/`，
+ * 其余路径带 token 一律 401，不点破模型会继续在 `/api` 上挂 `?token=`。
+ *
+ * 地址一律加引号：token 是 base64url，理论上无外壳元字符，但两条分支用同
+ * 一种写法才不会有后加字符时的分叉。
+ */
+const SECTION_TEMPLATE = [
+  'The Web GUI at `$DSH_WEB_URL` needs auth: its URL and every request carry `$DSH_WEB_AUTH_URL`.',
+  'First `curl -s -c "$JAR" -b "$JAR" -o /dev/null -w \'%{http_code}\' "$DSH_WEB_AUTH_URL"` answers 303',
+  'and sets the session cookie; reuse that jar, not the token, afterwards.',
+].join(' ')
+
 /** 插件配置。 */
 export const Config = z.object({
   /**
@@ -79,7 +93,7 @@ function resolveAuthenticatedUrl(ctx) {
 }
 
 /**
- * 渲染提示词段落。
+ * 渲染提示词段落：一份模板，只换地址那处。
  * @param ctx - 装配用的上下文。
  * @param mode - 已解析的 `prompt` 配置。
  * @returns 段落文本；地址不可解析时返回空串（等于不贡献段落）。
@@ -87,18 +101,35 @@ function resolveAuthenticatedUrl(ctx) {
 function promptText(ctx, mode) {
   const url = resolveAuthenticatedUrl(ctx)
   if (url === undefined) return ''
-  const inline = mode === 'inline'
-  const address = inline
-    ? url
-    : `\`$${AUTH_URL_KEY}\` (\`$${CLEAN_URL_KEY}\` is the same origin without the token)`
-  const target = inline ? url : `"$${AUTH_URL_KEY}"`
-  return [
-    'Shell access to this Web GUI is authenticated: an unauthenticated request to the clean URL answers 401,',
-    "because the browser session is a signed cookie minted from this process's launch token.",
-    `The authenticated address is ${address}.`,
-    `Exchange the token once and keep the jar — \`curl -s -c "$JAR" -b "$JAR" -o /dev/null -w '%{http_code}' ${target}\` answers 303 and sets the cookie;`,
-    'every later request through that jar is authorized.',
-  ].join(' ')
+  return mode === 'inline'
+    ? SECTION_TEMPLATE.replaceAll(URL_PLACEHOLDER, url)
+    : SECTION_TEMPLATE
+}
+
+/**
+ * 本插件自身安装目录的真实路径（预留工具，当前没有调用方）。
+ *
+ * 用它，不要用 `ctx.pluginPackages.packageOf(...)`：`packageOf` 只把 specifier
+ * 解析成包名并读 `<node_modules>/<包名>/package.json`，返回的可能是**软链接
+ * 路径**——开发副本里 `~/.dsh/profiles/web/node_modules/@lynn123411/dsh-*` 正是
+ * `link:` 到仓库，跨卷时 Node 的 realpath 不穿透，dirname 出来的是仓库外的
+ * 路径。这里走 Node 自己的解析器再 realpath：正常发布安装下两者相同。
+ *
+ * 宿主半边运行时**不能**用 `import.meta.resolve`（Cordis 装载的模块拿不到该
+ * 能力），所以按包名从自己的 URL 解析，再退回自身目录。
+ *
+ * @returns 本包目录的绝对路径；解析失败时退回本模块所在目录。
+ */
+export function selfDir() {
+  const fallback = dirname(fileURLToPath(import.meta.url))
+  try {
+    const entry = fileURLToPath(import.meta.resolve(`${PKG_NAME}`, import.meta.url))
+    let dir = dirname(entry)
+    if (basename(dir) === 'lib') dir = dirname(dir)
+    return realpathSync(dir)
+  } catch {
+    return fallback
+  }
 }
 
 /**
@@ -114,7 +145,7 @@ export function apply(ctx, config) {
       name: CONTRIBUTOR_NAME,
       variables: {
         [AUTH_URL_KEY]: {
-          description: 'Canonical local URL of the DeepSeek Harness Web GUI serving this session, carrying this process launch token for the browser-session exchange.',
+          description: 'Authenticated URL of this Web GUI; GET it once with a cookie jar to log in, then reuse the jar.',
         },
       },
       resolve: () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lynn123411/dsh-web-auth-url",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "把当前 Web 实例的带 token 访问地址交给模型与 shell：托管 DSH_WEB_AUTH_URL（每次 shell 调用即时解析，跟随重启后的 token 轮换），并贡献一段紧随 web-surface 的提示词说明 cookie jar 用法，secret 不进提示词与 transcript。",
   "type": "module",
   "main": "lib/index.js",
@@ -46,11 +46,11 @@
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "4.0.4",
-    "@deepseek-ai/dsh-shell-env": "0.1.7-rc.2",
-    "@deepseek-ai/dsh-system-prompt": "0.1.7-rc.2"
+    "@deepseek-ai/dsh-shell-env": ">=0.1.7-rc.2",
+    "@deepseek-ai/dsh-system-prompt": ">=0.1.7-rc.2"
   },
   "engines": {
-    "dsh": "0.1.7-rc.2",
+    "dsh": ">=0.1.7-rc.2",
     "node": "^22.19 || >=24"
   },
   "publishConfig": {

package/scripts/smoke-host.mjs

@@ -9,6 +9,9 @@
  *    `app:web-auth-url` 必须紧跟 `app:web-surface`。`getSectionOrder('WEB_SURFACE')`
  *    返回 undefined 时本插件算出的 order 是 NaN，真实 `section()` 会直接抛错。
  *
+ * 文案断言只钉**承重的那几件事**（两档都带引号的 curl 管道、env 档不出现 token、
+ * 末句的「别再用 token」），不钉整句子：段落文案今后再压也不该动自检。
+ *
  * 两个内核包是本插件的 devDependencies（与 engines.dsh 同版本），因此自检不需要
  * 指向任何 DSH 安装副本，`pnpm install` 后即可离线跑。文件末尾另有一段守卫
  * 反例：cordis 对未声明服务的属性读取真的抛错，上面的「用 ctx.inject 拿服务」
@@ -19,7 +22,7 @@
 
 import assert from 'node:assert/strict';
 import { createRequire } from 'node:module';
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -30,8 +33,9 @@ import * as ShellEnv from '@deepseek-ai/dsh-shell-env';
 
 const require = createRequire(import.meta.url);
 const here = dirname(fileURLToPath(import.meta.url));
-const manifest = JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf8'));
-const { apply, Config, inject, name } = await import('../lib/index.js');
+const packageDir = realpathSync(join(here, '..'));
+const manifest = JSON.parse(readFileSync(join(packageDir, 'package.json'), 'utf8'));
+const { apply, Config, inject, name, selfDir } = await import('../lib/index.js');
 
 const PORT = 3080;
 const TOKEN = 'launch-token-example';
@@ -93,16 +97,31 @@ assert.equal(Config({ prompt: 'inline' }).prompt, 'inline');
 assert.equal(Config({ prompt: 'off' }).prompt, 'off');
 assert.throws(() => Config({ prompt: 'nope' }), '非法 prompt 必须被 schema 拒绝');
 
-assert.equal(manifest.engines.dsh, '0.1.7-rc.2', 'engines.dsh 必须是精确的目标版本');
+// --- selfDir：本插件自身安装目录（预留工具） ------------------------------
+// 钉「realpath 后的落点 = 本包目录」：开发副本下包名会被解析到 profiles 里的
+// 链接路径，只有 realpath 之后才回到仓库。不 realpath 的实现在开发副本当场挂。
+assert.equal(selfDir(), packageDir, 'selfDir 必须 realpath 回本包目录');
+assert.equal(realpathSync(selfDir()), selfDir(), 'selfDir 必须已经是 realpath，调用方不必再处理链接');
+assert.equal(existsSync(join(selfDir(), manifest.main)), true, 'selfDir 必须能拼出真实入口文件');
+assert.equal(existsSync(join(selfDir(), 'cordis.patch.yml')), true, 'selfDir 必须能拼出随包文件');
+
+assert.equal(manifest.engines.dsh, '>=0.1.7-rc.2', 'engines.dsh 必须声明不低于基线 0.1.7-rc.2 的支持范围');
 assert.equal(manifest.peerDependencies['@deepseek-ai/cordis'], '^4.0.4');
 assert.equal(installedVersion('@deepseek-ai/cordis'), '4.0.4', 'cordis 必须对齐安装版本');
 assert.equal(manifest.dependencies['@deepseek-ai/schemastery'], '^3.18.4');
 assert.equal(installedVersion('@deepseek-ai/schemastery'), '3.18.4', 'schemastery 必须对齐安装版本');
+// engines.dsh 自 0.1.7-rc.2 起写成 >=0.1.7-rc.2（大于等于当前版本），而 devDependencies
+// 仍定向安装基线版本 0.1.7-rc.2，两者刻意不同：声明层必须写同一个范围，安装层必须钉住基线。
 for (const pkg of ['@deepseek-ai/dsh-system-prompt', '@deepseek-ai/dsh-shell-env']) {
   assert.equal(
-    installedVersion(pkg),
+    manifest.devDependencies[pkg],
     manifest.engines.dsh,
-    `${pkg} 的 devDependency 必须与 engines.dsh 同版本，否则自检跑的不是目标版本`,
+    `${pkg} 的 devDependency 必须与 engines.dsh 写同一个版本范围`,
+  );
+  assert.equal(
+    installedVersion(pkg),
+    '0.1.7-rc.2',
+    '自检跑的内核包必须仍是基线版本 0.1.7-rc.2',
   );
 }
 
@@ -159,24 +178,41 @@ for (const pkg of ['@deepseek-ai/dsh-system-prompt', '@deepseek-ai/dsh-shell-env
 
   const text = assembly.sections[mine].text;
   assert.ok(text.includes('DSH_WEB_AUTH_URL'), 'env 档必须报出变量名');
+  assert.ok(text.includes('DSH_WEB_URL'), '首句必须点到干净地址，才挂得上 app:web-surface 刚报的那台 GUI');
   assert.ok(!text.includes(TOKEN), 'env 档绝不能把 token 写进段落');
 
   const rendered = renderPrompt(assembly);
   assert.ok(rendered.includes('DSH_WEB_AUTH_URL'), 'env 档渲染后的系统提示词必须交代变量名');
   assert.ok(!rendered.includes(TOKEN), 'env 档渲染后的系统提示词里绝不能出现 token');
   assert.ok(
-    text.includes('401') && text.includes('303') && text.includes('$JAR'),
-    'env 档必须交代 401 / 303 / cookie jar 用法',
+    text.includes('curl -s -c "$JAR" -b "$JAR" -o /dev/null -w \'%{http_code}\' "$DSH_WEB_AUTH_URL"'),
+    'env 档必须给出带引号的 cookie jar 管道，且地址用变量引用的写法',
+  );
+  assert.ok(text.includes('303'), 'env 档必须交代第一次请求拿 303 种下 cookie');
+  assert.ok(
+    /reuse that jar, not the token/.test(text),
+    'env 档必须点明 token 只用于换 cookie——其余路径带 token 一律 401',
   );
+  assert.ok(text.length < 320, `段落已压到 ${String(text.length)} 字符，再涨就该走回那段解释性文案了`);
 }
 
 // --- inline / off 两档 ----------------------------------------------------
 {
   const { ctx } = await host();
   await mount(ctx, { prompt: 'inline' });
-  const rendered = renderPrompt(await ctx.systemPrompt.assemble({}));
+  const assembly = await ctx.systemPrompt.assemble({});
+  const text = assembly.sections.find((section) => section.name === SECTION_NAME).text;
+  const rendered = renderPrompt(assembly);
   assert.ok(rendered.includes(AUTH_URL), 'inline 档必须把带 token 的地址写进段落');
   assert.ok(!rendered.includes('DSH_WEB_AUTH_URL'), 'inline 档不再报变量名');
+  assert.ok(
+    text.includes(`"${AUTH_URL}"`),
+    'inline 档的地址也要带引号：两档共用同一份模板，只有地址被替换',
+  );
+  assert.ok(
+    /reuse that jar, not the token/.test(text),
+    'inline 档与 env 档同句式，收尾那句同样要在',
+  );
   assert.equal(ctx.shellEnv.collect({}).DSH_WEB_AUTH_URL, AUTH_URL, 'inline 档仍须托管环境变量');
 }
 {
@@ -199,7 +235,7 @@ for (const pkg of ['@deepseek-ai/dsh-system-prompt', '@deepseek-ai/dsh-shell-env
   assert.notEqual(mine, undefined, '段落注册不依赖 web 部署，照常完成');
   assert.equal(mine.text, '', '缺 connection 时段落必须渲染成空串');
   assert.ok(
-    !renderPrompt(assembly).includes('Shell access to this Web GUI'),
+    !renderPrompt(assembly).includes('needs auth'),
     '空段落由真实 renderPrompt 过滤，系统提示词里不留痕迹',
   );
 }