@danceiny/gotry 0.0.1-rc.8 → 0.2.0-rc.27

package/dist/scripts/agent-reach-tests.js

@@ -1,38 +1,46 @@
+/**
+ * agent-reach web 读取(readUrl 薄壳)测试:
+ *  readUrl = URL 校验 + 委托上游 WebChannel.read(反射桥) + Title 提取,自身无网络实现。
+ *  上游真读已在 §15 wrapper 测试覆盖;本套只测薄壳行为:
+ *  1. 非法 URL(不带 http) → 拒绝,不抛错,降级返回(离线确定性)
+ *  2. 1ms 超时 → 桥被杀,降级 error(离线确定性)
+ *  3. live 读 example.com → 成功时断言 Title/证据链;网络边界允许降级(不抛错)
+ *
+ * 运行: cd ts && npx tsx scripts/agent-reach-tests.ts
+ */
 import assert from 'node:assert/strict';
 import { readUrl } from '../capabilities/agent-reach.js';
+// 1. 非法 URL(不带 scheme)
 {
-    const r = await readUrl({
-        url: 'example.com'
-    });
+    const r = await readUrl({ url: 'example.com' });
     assert.equal(r.ok, false);
     assert.equal(r.via, 'r.jina.ai-error');
     assert.ok(r.evidence.includes('error'), 'evidence 带 error');
     console.log('1. 非法 URL 拒绝 OK');
-}{
-    const r = await readUrl({
-        url: 'https://example.com',
-        timeoutMs: 1
-    });
+}
+// 2. 超时(1ms 杀掉反射桥进程)
+{
+    const r = await readUrl({ url: 'https://example.com', timeoutMs: 1 });
     assert.equal(r.ok, false);
     assert.equal(r.via, 'r.jina.ai-error');
     assert.ok(r.latencyMs >= 0, '永不抛错');
     console.log('2. 超时降级 OK');
-}{
-    const r = await readUrl({
-        url: 'https://example.com',
-        timeoutMs: 30_000
-    });
+}
+// 3. live 读 example.com(上游 Jina Reader;网络边界允许降级)
+{
+    const r = await readUrl({ url: 'https://example.com', timeoutMs: 30_000 });
     if (r.ok) {
         assert.ok(r.evidence.includes('[agent-reach:web.read@'), '证据链');
         assert.match(r.evidence, /\[agent-reach:web\.read@2\d{3}-\d{2}-\d{2}T/, '证据链带 ISO 时间戳');
         assert.ok(typeof r.content === 'string' && r.content.length > 0, 'content 非空');
+        // live 内容会漂移(example.com 经 Jina 的 Title 曾从 Example Domain 变 Test Document),
+        // 断言结构(非空标题被提取)而非精确文案
         assert.ok(typeof r.title === 'string' && r.title.length > 0, `Title 提取,实际 ${r.title}`);
         console.log(`3. readUrl example.com → ok (title=${r.title}) OK`);
-    } else {
+    }
+    else {
         assert.equal(r.via, 'r.jina.ai-error');
         console.log(`3. readUrl example.com → 降级(${r.error?.slice(0, 60)})(网络边界,合法) OK`);
     }
-}console.log('\nAGENT-REACH TESTS: 3/3 OK(readUrl 薄壳;上游真读见 wrapper 套)');
-
-
-//# sourceURL=/Users/bytedance/work/gotry/ts/scripts/agent-reach-tests.ts
+}
+console.log('\nAGENT-REACH TESTS: 3/3 OK(readUrl 薄壳;上游真读见 wrapper 套)');

package/dist/scripts/agent-reach-wrapper-tests.js

@@ -1,79 +1,79 @@
+/**
+ * agent-reach wrapper 测试(零渠道知识,全部走反射桥):
+ *  1. status: 真 agent-reach doctor 透传(via=agent-reach-cli)
+ *  2. web.read: 真读 example.com(上游 Jina Reader 后端)
+ *  3. v2ex.get_hot_topics: 上游 python 方法真调(网络边界允许降级)
+ *  4. xueqiu.get_stock_quote: 无 cookie → needs-setup 且 setup=上游 check() 原话
+ *  5. 未知渠道 → 自描述错误带回上游渠道清单
+ *  6. 未知方法 → 自描述错误带回上游方法签名清单
+ *  7. 永不抛错: 空 channel/method 降级
+ *
+ * 运行: cd ts && npx tsx scripts/agent-reach-wrapper-tests.ts
+ */
 import assert from 'node:assert/strict';
 import { reach, reachStatus } from '../capabilities/agent-reach.js';
+// 1. status(真 doctor 原样透传;agent-reach 未装时结构化 SKIP——真集成面设备绑定,
+//    与 §17 skills-contract「有凭证真校验,离线 SKIP」同构;CI 装了则全跑 7 断言)
 {
     const st = await reachStatus(90_000);
+    if (!st.ok) {
+        console.log(`SKIP: agent-reach doctor 未就绪(未安装/needs-setup),7 断言整体跳过 — via=${st.via} output=${String(st.output).slice(0, 120)}`);
+        process.exit(0);
+    }
     assert.equal(st.ok, true);
     assert.equal(st.via, 'agent-reach-cli');
     assert.ok(st.output.length > 50, 'doctor 输出非空(上游原样)');
     console.log(`1. status → doctor 透传 (${st.latencyMs}ms) OK`);
-}{
-    const r = await reach({
-        channel: 'web',
-        method: 'read',
-        args: [
-            'https://example.com'
-        ],
-        timeoutMs: 30_000
-    });
+}
+// 2. web.read(上游 WebChannel.read → Jina Reader)
+{
+    const r = await reach({ channel: 'web', method: 'read', args: ['https://example.com'], timeoutMs: 30_000 });
     assert.equal(r.verdict, 'found');
     assert.ok(r.evidence.includes('[agent-reach:web.read@'), '证据链 [agent-reach:web.read@ts]');
+    // live 内容会漂移(同 §13),断言非空 markdown 而非精确文案
     assert.ok(typeof r.data === 'string' && r.data.length > 200, 'content 非空 markdown');
     console.log(`2. web.read example.com → found (${r.latencyMs}ms) OK`);
-}{
-    const r = await reach({
-        channel: 'v2ex',
-        method: 'get_hot_topics',
-        timeoutMs: 30_000
-    });
+}
+// 3. v2ex.get_hot_topics(上游 python 方法;网络边界允许降级不抛错)
+{
+    const r = await reach({ channel: 'v2ex', method: 'get_hot_topics', timeoutMs: 30_000 });
     if (r.ok) {
         assert.ok(Array.isArray(r.data), 'hot topics 是数组');
         console.log(`3. v2ex.get_hot_topics → found (${r.data.length} topics) OK`);
-    } else {
-        assert.ok([
-            'error',
-            'needs-setup'
-        ].includes(r.verdict), '降级合法');
+    }
+    else {
+        assert.ok(['error', 'needs-setup'].includes(r.verdict), '降级合法');
         console.log(`3. v2ex.get_hot_topics → ${r.verdict}(网络边界,降级合法) OK`);
     }
-}{
-    const r = await reach({
-        channel: 'xueqiu',
-        method: 'get_stock_quote',
-        args: [
-            'SH600519'
-        ],
-        timeoutMs: 30_000
-    });
+}
+// 4. xueqiu.get_stock_quote(无 cookie → needs-setup 且 setup 是上游 check() 原话)
+{
+    const r = await reach({ channel: 'xueqiu', method: 'get_stock_quote', args: ['SH600519'], timeoutMs: 30_000 });
     assert.equal(r.verdict, 'needs-setup', `实际 verdict=${r.verdict} error=${r.error}`);
     assert.ok((r.setup ?? '').includes('configure'), 'setup 透传上游 configure 指引(不转述)');
     console.log('4. xueqiu.get_stock_quote → needs-setup(上游原话指引) OK');
-}{
-    const r = await reach({
-        channel: 'nosuch',
-        method: 'foo'
-    });
+}
+// 5. 未知渠道 → 自描述,带回上游渠道清单
+{
+    const r = await reach({ channel: 'nosuch', method: 'foo' });
     assert.equal(r.ok, false);
-    const channels = r.inventory?.channels ?? {};
+    const channels = (r.inventory?.channels ?? {});
     assert.ok(channels.web && channels.xueqiu && channels['exa_search'], 'inventory 带回上游注册表(含 exa_search 真名)');
     console.log(`5. 未知渠道 → 自描述清单(${Object.keys(channels).length} 渠道) OK`);
-}{
-    const r = await reach({
-        channel: 'web',
-        method: 'nosuch'
-    });
+}
+// 6. 未知方法 → 自描述,带回上游方法签名清单
+{
+    const r = await reach({ channel: 'web', method: 'nosuch' });
     assert.equal(r.ok, false);
-    const methods = r.inventory?.methods ?? {};
+    const methods = (r.inventory?.methods ?? {});
     assert.ok(methods.read, 'inventory.methods 带 read 签名');
     console.log(`6. 未知方法 → 自描述清单(${Object.keys(methods).length} 方法) OK`);
-}{
-    const r = await reach({
-        channel: '',
-        method: ''
-    });
+}
+// 7. 永不抛错: 空 channel/method
+{
+    const r = await reach({ channel: '', method: '' });
     assert.equal(r.ok, false);
     assert.equal(r.verdict, 'error');
     console.log('7. 空 channel/method 降级 OK');
-}console.log('\nAGENT-REACH WRAPPER TESTS: 7/7 OK(反射桥 + doctor 透传 + 自描述错误)');
-
-
-//# sourceURL=/Users/bytedance/work/gotry/ts/scripts/agent-reach-wrapper-tests.ts
+}
+console.log('\nAGENT-REACH WRAPPER TESTS: 7/7 OK(反射桥 + doctor 透传 + 自描述错误)');

package/dist/scripts/anything-tests.js

@@ -1,5 +1,20 @@
+/**
+ * Anything 能力层测试(模拟 hbcli):
+ *  1. 真实候选:fake hbcli 按 hotel-be SearchItem wire 形状返 JSON — verdict hit + hits
+ *     (i18n name zh 优先 / region.centerLat / hotel.latlngCoordinator / star / id 逐字段对齐)
+ *  2. 旗标回归:--json 在子命令前(cli.ts 全局旗标预扫描只认子命令前位置)+
+ *     --content-type / parentDestinationId → --destination-id 映射
+ *  3. 空候选:fake hbcli 返 empty JSON — verdict miss
+ *  4. exit≠0:fake hbcli 返 stderr+退出 — verdict error + 不抛错
+ *  5. 旧 CLI「unknown command」:error 带升级指引(issue #195:裸 unknown command 读起来像工具坏了)
+ *  6. 超时:fake hbcli hang — AbortError → verdict error + 不抛错
+ *  7. 关键词为空:不调 hbcli — verdict error
+ *  8. 缺 hbcli(spawn 失败):用户面是人话(不留 `(exit null)`/ENOENT 进程噪音)
+ *
+ * 运行: cd ts && npx tsx scripts/anything-tests.ts
+ */
 import assert from 'node:assert/strict';
-import { mkdtemp, rm, writeFile, chmod } from 'node:fs/promises';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { anythingSearch } from '../capabilities/anything.js';
@@ -8,88 +23,129 @@ try {
     async function fakeBin(name, behaviour) {
         const p = join(tmp, name);
         if (behaviour === 'ok') {
+            // hotel-be SearchItem 真实 wire 形状(2026-09-07 对齐源码):i18n name 对象、
+            // region.coordinates.centerLat/centerLng、hotel.latlngCoordinator.google、star、matchScore
             await writeFile(p, `#!/bin/sh
 cat <<'JSON'
 {"candidates":[
-  {"type":"hotel","name":"Park Hyatt","hotel":{"id":"h1","name":"Park Hyatt","latitude":22.31,"longitude":114.16}},
-  {"type":"city","name":"大理市","region":{"id":"d1","name":"Dali","latitude":25.58,"longitude":100.21}},
-  {"type":"place","name":"洱海","region":{"id":"r1","name":"Erhai Lake","latitude":25.74,"longitude":100.25}}
+  {"type":"hotel","matchScore":180,"hotel":{"id":"h1","name":{"en":"Park Hyatt","zh":"柏悦酒店"},"star":5,"destinationId":"d1","latlngCoordinator":{"google":{"lat":22.31,"lng":114.16}}}},
+  {"type":"city","matchScore":250,"region":{"id":"d1","name":{"en":"Dali","zh":"大理市"},"countryCode":"CN","coordinates":{"centerLat":25.58,"centerLng":100.21}}},
+  {"type":"place","matchScore":90,"region":{"id":"r1","name":{"zh":"洱海"}},"place":{"latlngCoordinator":{"google":{"lat":25.74,"lng":100.25}}}}
 ]}
 JSON
-`, {
-                mode: 0o755
-            });
-        } else if (behaviour === 'empty') {
+`, { mode: 0o755 });
+        }
+        else if (behaviour === 'echo-args') {
+            // 旗标回归探针:把 "$@" 回显进候选 region.id(anythingSearch 原样透传为 destinationId)
+            await writeFile(p, `#!/bin/sh
+printf '{"candidates":[{"type":"city","region":{"id":"%s"}}]}' "$*"
+`, { mode: 0o755 });
+        }
+        else if (behaviour === 'empty') {
             await writeFile(p, `#!/bin/sh
 cat <<'JSON'
 {"candidates":[]}
 JSON
-`, {
-                mode: 0o755
-            });
-        } else if (behaviour === 'fail') {
+`, { mode: 0o755 });
+        }
+        else if (behaviour === 'fail') {
             await writeFile(p, `#!/bin/sh
 echo 'hotelbe down' >&2
 exit 1
-`, {
-                mode: 0o755
-            });
-        } else {
+`, { mode: 0o755 });
+        }
+        else if (behaviour === 'unknown-command') {
+            // 旧版 CLI(< 2026-09 的 staicli)没有 search anything 子命令时的 commander 原话
+            await writeFile(p, `#!/bin/sh
+echo "error: unknown command 'anything'" >&2
+exit 1
+`, { mode: 0o755 });
+        }
+        else {
+            // hang forever — test will timeout. Spawn on POSIX reacts to AbortSignal
+            // via SIGTERM; SIGKILL is the fallback at +500ms. Some shells (e.g. bash
+            // builtins shelled-out via Bun) cache the child pid briefly, so we give
+            // a generous upper bound in the assertion (note in code for future).
             await writeFile(p, `#!/bin/sh
 echo 'starting' >&2
 while :; do sleep 5; done
-`, {
-                mode: 0o755
-            });
+`, { mode: 0o755 });
         }
         return p;
     }
+    // 1. 真实候选(wire 形状逐字段)
     const ok = await fakeBin('hbcli-ok', 'ok');
-    const r1 = await anythingSearch({
-        keyword: 'Park Hyatt',
-        hbcliBin: ok
-    });
+    const r1 = await anythingSearch({ keyword: '大理', hbcliBin: ok });
     assert.equal(r1.verdict, 'hit');
     assert.equal(r1.hits.length, 3);
     assert.ok(r1.evidence.includes('hbcli-anything@'));
-    console.log(`1. Park Hyatt → hit (${r1.hits.length} candidates) OK`);
+    const [hotelHit, cityHit, placeHit] = r1.hits;
+    assert.equal(hotelHit.type, 'hotel');
+    assert.equal(hotelHit.name, '柏悦酒店', 'hotel i18n name 应 zh 优先');
+    assert.equal(hotelHit.hotelId, 'h1');
+    assert.equal(hotelHit.destinationId, 'd1', 'hotel 候选 destinationId 取所属目的地');
+    assert.equal(hotelHit.star, 5);
+    assert.equal(hotelHit.latitude, 22.31);
+    assert.equal(hotelHit.longitude, 114.16);
+    assert.equal(hotelHit.score, 180);
+    assert.equal(cityHit.type, 'city');
+    assert.equal(cityHit.name, '大理市', 'region i18n name 应 zh 优先');
+    assert.equal(cityHit.destinationId, 'd1');
+    assert.equal(cityHit.latitude, 25.58, 'city 坐标取 region.coordinates.centerLat');
+    assert.equal(cityHit.longitude, 100.21);
+    assert.equal(placeHit.type, 'place');
+    assert.equal(placeHit.name, '洱海');
+    assert.equal(placeHit.latitude, 25.74, 'place 坐标回退 place.latlngCoordinator');
+    console.log('1. 真实候选 wire 形状(hotel/city/place 逐字段)OK');
+    // 2. 旗标回归:--json 必须在子命令前(cli.ts 全局旗标预扫描只认子命令前位置);
+    //    contentType → --content-type;parentDestinationId → --destination-id(上游 CLI 旗标名)
+    const echo = await fakeBin('hbcli-echo-args', 'echo-args');
+    const r2 = await anythingSearch({ keyword: '大理', contentType: 'city', parentDestinationId: 'd1', hbcliBin: echo });
+    assert.equal(r2.verdict, 'hit');
+    assert.equal(r2.hits[0].destinationId, '--json search anything 大理 --content-type city --destination-id d1', 'spawn 旗标形态(--json 前置/--destination-id 映射)应稳定,实际 ' + r2.hits[0].destinationId);
+    console.log('2. 旗标回归(--json 前置 + --destination-id 映射)OK');
+    // 3. 空候选
     const empty = await fakeBin('hbcli-empty', 'empty');
-    const r2 = await anythingSearch({
-        keyword: 'nothing',
-        hbcliBin: empty
-    });
-    assert.equal(r2.verdict, 'miss');
-    assert.equal(r2.hits.length, 0);
-    console.log('2. nothing → miss OK');
+    const r3 = await anythingSearch({ keyword: 'nothing', hbcliBin: empty });
+    assert.equal(r3.verdict, 'miss');
+    assert.equal(r3.hits.length, 0);
+    console.log('3. nothing → miss OK');
+    // 4. exit≠0
     const fail = await fakeBin('hbcli-fail', 'fail');
-    const r3 = await anythingSearch({
-        keyword: 'x',
-        hbcliBin: fail
-    });
-    assert.equal(r3.verdict, 'error');
-    assert.equal(r3.ok, false);
-    assert.match(r3.evidence, /error/);
-    console.log('3. fail → error (降级) OK');
-    const hang = await fakeBin('hbcli-hang', 'hang');
-    const r4 = await anythingSearch({
-        keyword: 'x',
-        hbcliBin: hang,
-        timeoutMs: 800
-    });
-    assert.equal(r4.verdict, 'error', 'timeout 应判 error');
-    console.log(`4. hang/timeout → error OK (latency=${r4.latencyMs}ms)`);
-    const r5 = await anythingSearch({
-        keyword: '   '
-    });
+    const r4 = await anythingSearch({ keyword: 'x', hbcliBin: fail });
+    assert.equal(r4.verdict, 'error');
+    assert.equal(r4.ok, false);
+    assert.match(r4.evidence, /error/);
+    console.log('4. fail → error (降级) OK');
+    // 5. 旧 CLI unknown command → error 带升级指引(issue #195)
+    const old = await fakeBin('hbcli-old', 'unknown-command');
+    const r5 = await anythingSearch({ keyword: 'x', hbcliBin: old });
     assert.equal(r5.verdict, 'error');
-    console.log('5. empty keyword → error OK');
-    console.log('\nANYTHING TESTS: 5/5 OK(hbcli fake + graceful degrade)');
-} finally{
-    await rm(tmp, {
-        recursive: true,
-        force: true
-    });
+    assert.match(r5.error ?? '', /hbcli update|gotry setup/, 'error 应带升级指引,实际 ' + r5.error);
+    assert.match(r5.evidence, /unknown command/, 'evidence 保留上游原话(溯源)');
+    console.log(`5. 旧 CLI unknown command → 升级指引 OK(${r5.error})`);
+    // 6. 超时:fake hang 60s,我们给 800ms 超时,期望 verdict=error
+    //   (latency 断言范围放宽,因为 sandbox node spawn 的 abort 行为不稳定)
+    const hang = await fakeBin('hbcli-hang', 'hang');
+    const r6 = await anythingSearch({ keyword: 'x', hbcliBin: hang, timeoutMs: 800 });
+    assert.equal(r6.verdict, 'error', 'timeout 应判 error');
+    console.log(`6. hang/timeout → error OK (latency=${r6.latencyMs}ms)`);
+    // 7. 空 keyword
+    const r7 = await anythingSearch({ keyword: '   ' });
+    assert.equal(r7.verdict, 'error');
+    console.log('7. empty keyword → error OK');
+    // 8. 缺 hbcli(spawn 失败):用户面必须是人话。这条消息会直接渲染进用户回复
+    //    (loop.ts 的 D-7a PoI 探针),旧实现回落成 `(exit null)` 这类进程噪音
+    //    (2026-09-22 端到端走查在「我订了酒店:The Title East Wing Rawai」上实测到)。
+    const r8 = await anythingSearch({ keyword: 'The Title East Wing Rawai', hbcliBin: join(tmp, 'definitely-missing-hbcli') });
+    assert.equal(r8.verdict, 'error', '缺 hbcli 应判 error 而非抛错');
+    assert.ok(r8.error && r8.error.length > 0, '必须给出原因');
+    assert.ok(!/(exit null|ENOENT|spawn )/i.test(r8.error), `用户面不得出现进程噪音,实得:${r8.error}`);
+    assert.ok(/hbcli/.test(r8.error), `原因须指明是 hbcli,实得:${r8.error}`);
+    assert.ok(r8.evidence.includes('[实时API:hbcli-anything@error@'), '证据链 tag 形态不变');
+    console.log(`8. 缺 hbcli → 人话降级 OK(${r8.error})`);
+    console.log('\nANYTHING TESTS: 8/8 OK(hbcli fake + wire 对齐 + 降级诚实)');
+}
+finally {
+    await rm(tmp, { recursive: true, force: true });
 }
-
-
-//# sourceURL=/Users/bytedance/work/gotry/ts/scripts/anything-tests.ts

package/dist/scripts/artifact-client-contract-tests.js

@@ -0,0 +1,220 @@
+/**
+ * Public Client contract: package export, lazy-CJS loader shape, keyed DSH
+ * registrations, and defensive rendering from the runtime `block` payload.
+ * Browser execution is covered separately by dsh-artifact-web-e2e.ts.
+ */
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+import vm from 'node:vm';
+const ROOT = join(import.meta.dirname, '..', '..');
+const source = readFileSync(join(ROOT, 'client/client.js'), 'utf8');
+const pkg = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8'));
+assert.equal(pkg.exports?.['./client'], './client/client.js');
+assert.equal(pkg.dsh?.client?.platform, 'web');
+assert.ok(pkg.dsh?.client?.inject?.includes('@deepseek-ai/dsh-client-ui-tool'));
+assert.ok(pkg.files?.includes('client/'));
+assert.ok(source.includes('window.__ModuleLoader__.load'));
+assert.ok(source.includes("tool.call.toolview"));
+assert.ok(source.includes("gotry_artifacts_list"));
+assert.ok(source.includes("gotry_artifacts_read"));
+assert.ok(!source.includes('@deepseek-ai/dsh-client-ui-tool/lib/'));
+const registrations = [];
+const context = vm.createContext({
+    window: { __ModuleLoader__: { load: (registration) => registrations.push(registration) } },
+    console,
+});
+new vm.Script(source, { filename: 'client/client.js' }).runInContext(context);
+assert.equal(registrations.length, 1);
+assert.equal(registrations[0].id, '@danceiny/gotry');
+function createElement(type, props, ...children) {
+    return { type, props: props ?? {}, children };
+}
+const fakeReact = {
+    createElement,
+    useState(initial) { return [initial, () => { }]; },
+};
+const clientExports = registrations[0].factory(name => {
+    assert.equal(name, 'react');
+    return fakeReact;
+});
+assert.deepEqual(Object.keys(clientExports), ['apply', 'inject']);
+const slotRegistrations = [];
+const registrationContext = {
+    inject(_deps, callback) { callback(registrationContext); },
+    slots: {
+        inject(_slot, callback) { callback(); },
+        register(definition, view) {
+            slotRegistrations.push({ key: definition.key, view });
+            return () => { };
+        },
+    },
+};
+clientExports.apply(registrationContext);
+assert.deepEqual(slotRegistrations.map(item => item.key), ['gotry_artifacts_list', 'gotry_artifacts_read']);
+assert.equal(slotRegistrations[0].view, slotRegistrations[1].view);
+const view = slotRegistrations[0].view;
+const listTree = view({
+    toolName: 'gotry_artifacts_list',
+    block: { kind: 'tool-result', isError: false, meta: { shape: 'paths', paths: ['/tmp/trip-2027.md'], total: 1, truncated: false }, content: [] },
+});
+assert.equal(listTree.props['data-gotry-artifact-card'], 'list');
+assert.equal(listTree.props['data-gotry-artifact-state'], 'ok');
+const malformedTree = view({ toolName: 'gotry_artifacts_read', block: { kind: 'tool-result', isError: false, meta: { shape: 'bad' }, content: [{ type: 'text', text: 'raw fallback' }] } });
+assert.equal(malformedTree.props['data-gotry-artifact-card'], 'read');
+assert.equal(malformedTree.props['data-gotry-artifact-state'], 'ok');
+const requireRoot = createRequire(join(ROOT, 'package.json'));
+assert.ok(requireRoot.resolve('./client/client.js'));
+// issue #441: an HTML artifact is previewed as source text only. The client half
+// must not gain a raw-HTML injection API or an embedded browsing context.
+for (const banned of ['dangerouslySetInnerHTML', 'innerHTML', 'outerHTML', 'insertAdjacentHTML', 'srcdoc', 'iframe', 'document.write', 'eval(']) {
+    assert.ok(!source.includes(banned), `client bundle must not use ${banned}`);
+}
+const textNodes = [];
+const elementTypes = [];
+const forbiddenProps = [];
+function walkTree(node) {
+    if (typeof node === 'string') {
+        textNodes.push(node);
+        return;
+    }
+    if (Array.isArray(node)) {
+        for (const child of node)
+            walkTree(child);
+        return;
+    }
+    const item = node;
+    if (!item || typeof item !== 'object')
+        return;
+    elementTypes.push(item.type);
+    for (const key of ['dangerouslySetInnerHTML', 'innerHTML', 'outerHTML', 'srcdoc']) {
+        if (key in (item.props ?? {}))
+            forbiddenProps.push(key);
+    }
+    for (const child of item.children ?? [])
+        walkTree(child);
+}
+const hostileLines = [
+    '<script>globalThis.__gotry441Pwned = true</script>',
+    '<img src=x onerror="globalThis.__gotry441Pwned = true">',
+    '<iframe src="https://example.invalid/track"></iframe>',
+    '<a href="javascript:globalThis.__gotry441Pwned=true">点击</a>',
+];
+const hostileTree = view({
+    toolName: 'gotry_artifacts_read',
+    block: {
+        kind: 'tool-result',
+        isError: false,
+        meta: {
+            path: '/tmp/trip-2027.html', offset: 1, totalLines: hostileLines.length, lang: 'html',
+            source: 'cwd', version: 'a1b2c3d4e5f6',
+            lines: hostileLines.map((text, index) => ({ number: index + 1, text })),
+        },
+        content: [],
+    },
+});
+assert.equal(hostileTree.props['data-gotry-artifact-card'], 'read');
+assert.equal(hostileTree.props['data-gotry-artifact-state'], 'ok');
+walkTree(hostileTree);
+assert.deepEqual(forbiddenProps, [], `预览树不得出现 raw HTML 注入 props,实际 ${forbiddenProps.join(',')}`);
+assert.ok(!elementTypes.includes('iframe'), '预览树不得创建 iframe');
+for (const line of hostileLines) {
+    assert.ok(textNodes.includes(line), `HTML 源码行必须以文本节点原样呈现:${line}`);
+}
+function collect(node, out = []) {
+    if (Array.isArray(node)) {
+        for (const child of node)
+            collect(child, out);
+        return out;
+    }
+    const item = node;
+    if (!item || typeof item !== 'object')
+        return out;
+    out.push({ type: item.type, props: item.props ?? {}, children: item.children ?? [] });
+    for (const child of item.children ?? [])
+        collect(child, out);
+    return out;
+}
+function textsOf(node) {
+    const out = [];
+    const visit = (value) => {
+        if (typeof value === 'string') {
+            out.push(value);
+            return;
+        }
+        if (Array.isArray(value)) {
+            for (const child of value)
+                visit(child);
+            return;
+        }
+        const item = value;
+        if (!item || typeof item !== 'object')
+            return;
+        for (const child of item.children ?? [])
+            visit(child);
+    };
+    visit(node.children);
+    return out;
+}
+// HTML list entries are opened through the host's native HTML preview, which is a
+// different action from reading source text: it must be labelled and explained.
+const mixedTree = view({
+    toolName: 'gotry_artifacts_list',
+    block: {
+        kind: 'tool-result', isError: false,
+        meta: { shape: 'paths', paths: ['/tmp/trip-2027.md', '/tmp/trip-2027.html', '/tmp/Trip-2027.HTM'], total: 3, truncated: false },
+        content: [],
+    },
+});
+const buttons = collect(mixedTree).filter(node => node.type === 'button');
+assert.equal(buttons.length, 3, `3 条路径应有 3 个按钮,实际 ${buttons.length}`);
+const mdButton = buttons.find(node => node.props['data-gotry-artifact-path'] === '/tmp/trip-2027.md');
+const htmlButtons = buttons.filter(node => String(node.props['data-gotry-artifact-path']).toLowerCase().endsWith('.htm') ||
+    String(node.props['data-gotry-artifact-path']).toLowerCase().endsWith('.html'));
+assert.equal(htmlButtons.length, 2, `.html 与 .HTM 都应识别为 HTML 预览,实际 ${htmlButtons.length}`);
+assert.equal(mdButton?.props['data-gotry-artifact-open'], 'artifact', 'markdown 打开动作保持原文');
+assert.equal(mdButton?.props['aria-label'], 'Open artifact /tmp/trip-2027.md', 'markdown 可访问标签不变');
+assert.equal(mdButton?.props.title, undefined, 'markdown 不新增提示(行为不变)');
+assert.ok(!textsOf(mdButton).includes('HTML 预览'), 'markdown 条目不显示 HTML 预览徽标');
+for (const button of htmlButtons) {
+    const path = String(button.props['data-gotry-artifact-path']);
+    assert.equal(button.props['data-gotry-artifact-open'], 'html-preview', `HTML 条目应标记为原生预览动作:${path}`);
+    assert.equal(button.props['aria-label'], `Open HTML preview ${path}`, `HTML 条目可访问标签应显式声明 HTML 预览:${path}`);
+    const title = String(button.props.title ?? '');
+    assert.ok(title.includes('脚本') && title.includes('可能'), `提示应说明脚本可能运行:${title}`);
+    assert.ok(!/sandbox|renderer|iframe|宿主|DSH|dsh/i.test(title), `提示不得使用基础设施术语:${title}`);
+    assert.ok(textsOf(button).includes('HTML 预览'), `HTML 条目应有可见的 HTML 预览指示:${path}`);
+}
+// Source read card: HTML is identified as source text, still plain text nodes.
+const htmlSourceTree = view({
+    toolName: 'gotry_artifacts_read',
+    block: {
+        kind: 'tool-result', isError: false,
+        meta: {
+            path: '/tmp/trip-2027.html', offset: 1, totalLines: hostileLines.length, lang: 'html',
+            source: 'cwd', version: 'a1b2c3d4e5f6',
+            lines: hostileLines.map((text, index) => ({ number: index + 1, text })),
+        },
+        content: [],
+    },
+});
+assert.equal(htmlSourceTree.props['data-gotry-artifact-source'], 'html', 'HTML 读卡应显式标注源码来源');
+assert.ok(textsOf(htmlSourceTree).includes('HTML 源码预览（只读文本）'), 'HTML 读卡标题应明确是源码文本');
+const htmlSourceNodes = collect(htmlSourceTree);
+assert.ok(!htmlSourceNodes.some(node => 'dangerouslySetInnerHTML' in node.props || 'innerHTML' in node.props), 'HTML 读卡不得注入原始 HTML');
+assert.ok(htmlSourceNodes.every(node => node.type !== 'iframe'), 'HTML 读卡不得内嵌浏览上下文');
+for (const line of hostileLines) {
+    assert.ok(textsOf({ children: [htmlSourceTree] }).includes(line), `HTML 读卡仍以文本节点逐字呈现:${line}`);
+}
+const mdSourceTree = view({
+    toolName: 'gotry_artifacts_read',
+    block: {
+        kind: 'tool-result', isError: false,
+        meta: { path: '/tmp/trip-2027.md', offset: 1, totalLines: 1, lang: 'markdown', source: 'cwd', version: 'f6e5d4c3b2a1', lines: [{ number: 1, text: '# 行程' }] },
+        content: [],
+    },
+});
+assert.equal(mdSourceTree.props['data-gotry-artifact-source'], undefined, 'markdown 读卡不得被标注为 HTML 源码');
+assert.ok(textsOf(mdSourceTree).includes('产物预览'), 'markdown 读卡标题保持原样');
+console.log('ARTIFACT CLIENT CONTRACT: package export + web manifest + lazy loader + 2 keyed views + malformed fallback + HTML source-as-text + explicit HTML preview action OK');