@lynn123411/dsh-web-auth-url 0.1.1 → 0.1.3

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.1",
+  "version": "0.1.3",
   "description": "把当前 Web 实例的带 token 访问地址交给模型与 shell：托管 DSH_WEB_AUTH_URL（每次 shell 调用即时解析，跟随重启后的 token 轮换），并贡献一段紧随 web-surface 的提示词说明 cookie jar 用法，secret 不进提示词与 transcript。",
   "type": "module",
   "main": "lib/index.js",
@@ -34,18 +34,23 @@
     "check": "node scripts/smoke-host.mjs"
   },
   "dependencies": {
-    "@deepseek-ai/schemastery": "^3.18.2"
+    "@deepseek-ai/schemastery": "^3.18.4"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@deepseek-ai/cordis": "^4.0.4"
   },
   "peerDependenciesMeta": {
     "@deepseek-ai/cordis": {
       "optional": true
     }
   },
+  "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"
+  },
   "engines": {
-    "dsh": "0.1.6-alpha.2",
+    "dsh": "0.1.7-rc.2",
     "node": "^22.19 || >=24"
   },
   "publishConfig": {

package/scripts/smoke-host.mjs

@@ -1,150 +1,250 @@
 /**
- * 宿主半边装配自检：用带守卫的假上下文真跑一遍 apply()，断言登记形状、
- * 即时解析的地址，以及三种 prompt 模式各自的段落文本。
+ * 宿主半边自检：把两个承重点放在 **真实的 0.1.7-rc.2 内核服务** 上跑，而不是桩件——
+ * 这两条断言的全部意义就是「DSH 换了实现，本插件立刻挂」：
  *
- * 守卫必须真的抛错（末尾有反例断言），否则「未声明的服务」这类断言全是空转。
+ * 1. 托管环境变量：真实 `ctx.shellEnv`（@deepseek-ai/dsh-shell-env）的
+ *    `collect()` 每次调用都重新执行本插件的 `resolve`，所以 token 轮换后
+ *    下一次 shell 调用拿到新地址。桩件只能证明我们自己的闭包新鲜，证不了这一点。
+ * 2. 段落锚点：真实 `ctx.systemPrompt`（@deepseek-ai/dsh-system-prompt）里
+ *    `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 拿服务」
+ * 才不是装饰。
+ *
+ * 跑法：pnpm test / node scripts/smoke-host.mjs
  */
 
 import assert from 'node:assert/strict';
-import { registerHooks } from 'node:module';
-import { existsSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { join } from 'node:path';
-import { pathToFileURL } from 'node:url';
-
-// lib/index.js 依赖 @deepseek-ai/schemastery；仓库检出里没有 node_modules，而 DSH 运行目录带一份。
-// 把该名字路由到运行目录里的真实实现——自检要真跑 schema 校验，不能用桩件假造它的行为。
-const dshHome = process.env.DSH_HOME ?? join(homedir(), '.dsh');
-const schemasteryEntry = join(dshHome, 'profiles', 'node_modules', '@deepseek-ai', 'schemastery', 'lib', 'index.mjs');
-if (!existsSync(schemasteryEntry)) {
-  throw new Error(`schemastery 未找到：${schemasteryEntry}（把 DSH_HOME 指向 DSH 主目录后重试）`);
-}
-const schemasteryUrl = pathToFileURL(schemasteryEntry).href;
-registerHooks({
-  resolve(specifier, context, nextResolve) {
-    if (specifier === '@deepseek-ai/schemastery') return { url: schemasteryUrl, shortCircuit: true };
-    return nextResolve(specifier, context);
-  },
-});
+import { createRequire } from 'node:module';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
-const { apply, Config, inject, name } = await import('../lib/index.js');
+import { Context } from '@deepseek-ai/cordis';
+import SystemPrompt, { renderPrompt } from '@deepseek-ai/dsh-system-prompt';
+import * as ShellEnv from '@deepseek-ai/dsh-shell-env';
+
+const require = createRequire(import.meta.url);
+const here = dirname(fileURLToPath(import.meta.url));
+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';
 const CLEAN_URL = `http://127.0.0.1:${PORT}`;
 const AUTH_URL = `${CLEAN_URL}/?token=${TOKEN}`;
 
-/**
- * 造一个假上下文。
- * @param services - 树上可读到的服务。
- * @param declared - 本上下文已 inject 的服务名。
- * @returns 读未声明服务即抛 cordis 同款错误的上下文。
- */
-function makeContext(services, declared = new Set()) {
-  const base = {
-    get: (key) => services[key],
-    inject: (names, callback) => {
-      for (const key of names) {
-        if (!(key in services)) throw new Error(`fake tree is missing service "${key}"`);
-      }
-      callback(makeContext(services, new Set(names)));
-    },
-  };
-  return new Proxy(base, {
-    get(target, property, receiver) {
-      if (typeof property === 'symbol' || property in target) return Reflect.get(target, property, receiver);
-      if (!declared.has(property)) throw new Error(`cannot get property "${property}" without inject`);
-      return services[property];
-    },
-  });
+/** 本插件贡献的段落名。 */
+const SECTION_NAME = 'app:web-auth-url';
+/** 0.1.7-rc.2 `SECTION_ORDERS.WEB_SURFACE` 的实际取值，锚点漂了必须当场失败。 */
+const ANCHOR_ORDER = 10100;
+
+/** 读一个已安装包的真实版本号（沿解析出的入口向上找同名 package.json）。 */
+function installedVersion(pkg) {
+  let dir = dirname(require.resolve(pkg));
+  while (dirname(dir) !== dir) {
+    const candidate = join(dir, 'package.json');
+    if (existsSync(candidate)) {
+      const found = JSON.parse(readFileSync(candidate, 'utf8'));
+      if (found.name === pkg) return found.version;
+    }
+    dir = dirname(dir);
+  }
+  throw new Error(`已安装包 ${pkg} 的 package.json 未找到`);
 }
 
-/** 一套带 web 部署的服务桩。 */
-function webServices() {
-  return {
-    webServer: { port: PORT },
-    connection: { authenticatedUrl: (baseUrl) => `${baseUrl}/?token=${TOKEN}` },
-    shellEnv: { register: () => () => {} },
-    systemPrompt: { section: () => () => {}, getSectionOrder: (order) => (order === 'WEB_SURFACE' ? 10100 : Number.NaN) },
-  };
+/**
+ * 装配一套真实的宿主树：真 systemPrompt + 真 shellEnv，web 侧用最小桩供给
+ * `webServer.port` 与 `connection.authenticatedUrl`（dsh-web-app 依赖同样的两个面）。
+ * @param {{token?: string, web?: boolean}} [options] - token 初值与是否提供 web 部署。
+ * @returns {Promise<{ctx: object, state: {token: string}}>} 上下文与可轮换的 token 状态。
+ */
+async function host({ token = TOKEN, web = true } = {}) {
+  const ctx = new Context();
+  await ctx.plugin(SystemPrompt, {});
+  await ctx.plugin(ShellEnv, { dshHome: join(tmpdir(), 'dsh-web-auth-url-smoke') });
+  const state = { token };
+  if (web) {
+    ctx.provide('webServer', { port: PORT });
+    ctx.provide('connection', { authenticatedUrl: (baseUrl) => `${baseUrl}/?token=${state.token}` });
+  }
+  return { ctx, state };
 }
 
-/** 捕获一次 apply() 的登记结果。 */
-function load(config, services = webServices()) {
-  const captured = { contributor: undefined, section: undefined };
-  services.shellEnv.register = (contributor) => {
-    captured.contributor = contributor;
-    return () => {};
-  };
-  services.systemPrompt.section = (section) => {
-    captured.section = section;
-    return () => {};
-  };
-  apply(makeContext(services), config);
-  return { captured, services };
+/**
+ * 把本插件应用到真实上下文。依赖齐备时 `ctx.inject` 的登记回调同步执行；
+ * 这里仍 await 一次 fiber，是为了让「将来改成异步注册」变成失败而不是静默漏断言。
+ */
+async function mount(ctx, config) {
+  apply(ctx, config);
+  await ctx.fiber.await();
+  return ctx;
 }
 
-// --- 插件身份 -------------------------------------------------------------
+// --- 插件身份与清单口径 ---------------------------------------------------
 assert.equal(name, 'dsh-web-auth-url');
 assert.deepEqual(inject, [], '插件必须声明零硬依赖，web 缺失时靠 ctx.get 降级');
 assert.equal(Config({}).prompt, 'env', 'prompt 默认必须是 env（token 不进提示词）');
 assert.equal(Config({ prompt: 'inline' }).prompt, 'inline');
+assert.equal(Config({ prompt: 'off' }).prompt, 'off');
 assert.throws(() => Config({ prompt: 'nope' }), '非法 prompt 必须被 schema 拒绝');
 
-// --- 环境变量 -------------------------------------------------------------
-{
-  const { captured } = load({ prompt: 'env' });
-  const contributor = captured.contributor;
-  assert.equal(contributor.name, 'dsh-web-auth-url');
-  assert.deepEqual(Object.keys(contributor.variables), ['DSH_WEB_AUTH_URL']);
-  assert.ok(contributor.variables.DSH_WEB_AUTH_URL.description.trim().length > 0, '登记的变量必须有描述');
-  assert.deepEqual(contributor.resolve({}), { DSH_WEB_AUTH_URL: AUTH_URL }, 'resolve 必须给出带 token 的当前地址');
+// --- 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 必须是精确的目标版本');
+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 必须对齐安装版本');
+for (const pkg of ['@deepseek-ai/dsh-system-prompt', '@deepseek-ai/dsh-shell-env']) {
+  assert.equal(
+    installedVersion(pkg),
+    manifest.engines.dsh,
+    `${pkg} 的 devDependency 必须与 engines.dsh 同版本，否则自检跑的不是目标版本`,
+  );
 }
 
-// --- token 轮换：每次 resolve 重新解析 -------------------------------------
+// --- 承重点一：真 shellEnv，每次 collect 即时解析 --------------------------
 {
-  const { captured, services } = load({ prompt: 'env' });
-  services.connection.authenticatedUrl = (baseUrl) => `${baseUrl}/?token=rotated`;
-  assert.deepEqual(captured.contributor.resolve({}), { DSH_WEB_AUTH_URL: `${CLEAN_URL}/?token=rotated` });
+  const { ctx, state } = await host();
+  await mount(ctx, { prompt: 'env' });
+
+  const first = ctx.shellEnv.collect({});
+  assert.equal(first.DSH_WEB_AUTH_URL, AUTH_URL, '真实 shellEnv.collect 必须给出带 token 的当前地址');
+
+  state.token = 'rotated-token';
+  const second = ctx.shellEnv.collect({});
+  assert.equal(
+    second.DSH_WEB_AUTH_URL,
+    `${CLEAN_URL}/?token=rotated-token`,
+    'token 轮换后下一次 collect 必须重新解析（每次 shell 调用即时解析）',
+  );
+
+  const declared = ctx.shellEnv.list().find((variable) => variable.key === 'DSH_WEB_AUTH_URL');
+  assert.equal(declared?.contributor, 'dsh-web-auth-url', '变量必须以本插件名登记，真实注册表校验名字与键唯一性');
+  assert.ok(declared.description.trim().length > 0, '登记的变量必须有描述（真实注册表会拒绝空描述）');
 }
 
-// --- 无 web 部署：不报错、不贡献值 -----------------------------------------
+// --- 承重点二：真 systemPrompt，段落紧贴 app:web-surface --------------------
 {
-  const services = webServices();
-  delete services.connection;
-  delete services.webServer;
-  const { captured } = load({ prompt: 'env' }, services);
-  assert.deepEqual(captured.contributor.resolve({}), {}, '缺 connection 时 resolve 必须返回空');
-  assert.equal(captured.section.text(), '', '缺 connection 时段落必须渲染成空串');
+  const { ctx } = await host();
+  await mount(ctx, { prompt: 'env' });
+
+  const anchorOrder = ctx.systemPrompt.getSectionOrder('WEB_SURFACE');
+  assert.ok(
+    Number.isFinite(anchorOrder),
+    "真实 systemPrompt 必须仍认识 'WEB_SURFACE' 位置——返回 undefined 时本插件算出 NaN，真实 section() 会抛错",
+  );
+  assert.equal(anchorOrder, ANCHOR_ORDER, 'WEB_SURFACE 位置值变了，+10 的紧邻关系必须重新核对');
+
+  /**
+   * 复刻 dsh-web-app 的锚点：它在 0.1.7-rc.2 以
+   * `section({ name: 'app:web-surface', order: getSectionOrder('WEB_SURFACE') })` 注册
+   * （安装副本 `lib/index.js` 第 180-184 行）。它不在本插件的依赖里，所以只能照同样的
+   * 两件事复刻一个再断言紧邻；「这个名字对得上 dsh-web-app」靠读那一处源码保证，不是
+   * 这条断言证明的。名字与期望值都写死成字面量，改任何一处都得同时面对另一处。
+   */
+  ctx.systemPrompt.section({ name: 'app:web-surface', order: anchorOrder, text: () => 'web surface' });
+  const assembly = await ctx.systemPrompt.assemble({});
+  const names = assembly.sections.map((section) => section.name);
+  const mine = names.indexOf(SECTION_NAME);
+  assert.notEqual(mine, -1, '段落必须注册进真实 systemPrompt');
+  assert.deepEqual(
+    names.slice(mine - 1, mine + 1),
+    ['app:web-surface', SECTION_NAME],
+    '本段落必须紧跟 app:web-surface',
+  );
+
+  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('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 { captured } = load({ prompt: 'env' });
-  assert.equal(captured.section.name, 'app:web-auth-url');
-  assert.equal(captured.section.order, 10110, '段落必须紧跟 WEB_SURFACE（10100）');
-  const text = captured.section.text();
-  assert.ok(text.includes('DSH_WEB_AUTH_URL'), 'env 模式必须报出变量名');
-  assert.ok(!text.includes(TOKEN), 'env 模式绝不能把 token 写进提示词');
-  assert.ok(text.includes('401') && text.includes('303') && text.includes('$JAR'), 'env 模式必须交代 401 / 303 / cookie jar 用法');
+  const { ctx } = await host();
+  await mount(ctx, { prompt: 'inline' });
+  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 档仍须托管环境变量');
 }
 {
-  const { captured } = load({ prompt: 'inline' });
-  const text = captured.section.text();
-  assert.ok(text.includes(AUTH_URL), 'inline 模式必须把带 token 的地址写进段落');
-  assert.ok(!text.includes('DSH_WEB_AUTH_URL'), 'inline 模式不再报变量名');
+  const { ctx } = await host();
+  await mount(ctx, { prompt: 'off' });
+  const sections = (await ctx.systemPrompt.assemble({})).sections;
+  assert.ok(!sections.some((section) => section.name === SECTION_NAME), 'off 档不得注册段落');
+  assert.equal(ctx.shellEnv.collect({}).DSH_WEB_AUTH_URL, AUTH_URL, 'off 档仍须托管环境变量');
 }
+
+// --- 无 web 部署：注册照常、值与段落都为空 --------------------------------
 {
-  const { captured } = load({ prompt: 'off' });
-  assert.equal(captured.section, undefined, 'off 模式不得注册段落');
-  assert.ok(captured.contributor !== undefined, 'off 模式仍须登记环境变量');
+  const { ctx } = await host({ web: false });
+  await mount(ctx, { prompt: 'env' });
+
+  assert.equal('DSH_WEB_AUTH_URL' in ctx.shellEnv.collect({}), false, '缺 connection 时不得注入该变量');
+
+  const assembly = await ctx.systemPrompt.assemble({});
+  const mine = assembly.sections.find((section) => section.name === SECTION_NAME);
+  assert.notEqual(mine, undefined, '段落注册不依赖 web 部署，照常完成');
+  assert.equal(mine.text, '', '缺 connection 时段落必须渲染成空串');
+  assert.ok(
+    !renderPrompt(assembly).includes('needs auth'),
+    '空段落由真实 renderPrompt 过滤，系统提示词里不留痕迹',
+  );
 }
 
-// --- 守卫自身的反例断言（守卫失效即失败） ---------------------------------
+// --- 守卫反例：cordis 真的拒绝未声明服务的属性读取 ------------------------
 {
-  const ctx = makeContext(webServices());
-  assert.throws(() => ctx.shellEnv, /without inject/, '读未声明服务必须抛错，否则上面的断言全是空转');
+  const ctx = new Context();
+  await ctx.plugin(ShellEnv, { dshHome: join(tmpdir(), 'dsh-web-auth-url-smoke') });
+  await assert.rejects(
+    async () => {
+      await ctx.plugin({ name: 'guarded', apply: (guardedCtx) => void guardedCtx.shellEnv });
+    },
+    /cannot get property "shellEnv" without inject/,
+    '未声明服务必须抛错，否则本插件用 ctx.inject([...]) 取服务就不是必需的了',
+  );
   assert.equal(ctx.get('shellEnv') !== undefined, true, 'ctx.get 不抛错，可选能力走它');
 }
 
-console.log('smoke-host: ok');
+console.log('smoke-host: ok');