cortico-world-workbuddy 0.1.7 → 0.3.0

package/scripts/build-web.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+/**
+ * 重建 `dist/webui.js`（面板产物）。
+ *
+ * 为什么不用 `esbuild` 直接当 script：`prepack` 会在别人机器上跑，
+ * 那里可能没有 `npm install` 过（没有 node_modules/esbuild），直接调 `esbuild` 会
+ * `'esbuild' is not recognized`，整条 `npm pack` 就失败了。
+ *
+ * 解析顺序：
+ *   1. 本包的 devDependency（`node_modules/esbuild`，版本由 lock 固定，CI 用这个）；
+ *   2. 宿主 Coopanion 自带的那份（`--config.strict-dep-builds` 之外的本机兜底）；
+ *   3. 都没有：`dist/webui.js` 已存在就警告并退出 0（产物已随包提交），否则报错。
+ *
+ * `--strict`：找不到 esbuild 时**不允许**沿用旧产物（返回 1）。
+ * `prepack` 走 strict —— 否则没装依赖的机器会静默把过期 dist 发布出去（审查报告第 6 条）。
+ *
+ * 用法：node scripts/build-web.mjs [--verbose] [--strict]
+ */
+
+import { existsSync, mkdirSync, readFileSync as readTextSync, statSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const pkgDir = fileURLToPath(new URL('..', import.meta.url));
+const verbose = process.argv.includes('--verbose');
+const strict = process.argv.includes('--strict');
+const entry = join(pkgDir, 'src', 'webui', 'client.js');
+const outfile = join(pkgDir, 'dist', 'webui.js');
+const args = [entry, '--bundle', '--format=esm', `--outfile=${outfile}`, '--log-level=warning'];
+
+/**
+ * 宿主 Coopanion 的 app 目录（只用来兜底取它自带的 esbuild）。
+ * 按「存在 build/console/index.html」判定，探测失败返回空串。
+ */
+function hostAppRoot() {
+  const local = process.env.LOCALAPPDATA || '';
+  const candidates = [
+    local && join(local, 'Programs', 'Coopanion', 'resources', 'app'),
+    process.env.ProgramFiles && join(process.env.ProgramFiles, 'Coopanion', 'resources', 'app'),
+    process.env['ProgramFiles(x86)'] && join(process.env['ProgramFiles(x86)'], 'Coopanion', 'resources', 'app'),
+  ].filter(Boolean);
+  return candidates.find((dir) => existsSync(join(dir, 'build', 'console', 'index.html'))) ?? '';
+}
+
+/** 找到可用的 esbuild 启动脚本（bin/esbuild 是 JS 包装，用 node 跑）。 */
+function resolveEsbuild() {
+  const require = createRequire(import.meta.url);
+  const candidates = [];
+  try {
+    candidates.push(require.resolve('esbuild/bin/esbuild'));
+  } catch {
+    /* 本地没装 devDependencies，走宿主兜底 */
+  }
+  const appRoot = process.env.COOPANION_APP_ROOT || hostAppRoot();
+  if (appRoot) candidates.push(join(appRoot, 'node_modules', 'esbuild', 'bin', 'esbuild'));
+
+  for (const bin of candidates) {
+    if (!existsSync(bin)) continue;
+    // 版本号在同一目录的 package.json 里
+    let version = 'unknown';
+    try {
+      version = JSON.parse(readTextSync(join(dirname(bin), '..', 'package.json'), 'utf8')).version;
+    } catch {
+      /* 版本读不到不影响构建 */
+    }
+    return { bin, version };
+  }
+  return null;
+}
+
+const found = resolveEsbuild();
+if (!found) {
+  console.error('✗ 找不到 esbuild（本地 devDependencies 与宿主都没装）。');
+  console.error('  先跑一次 `npm ci`（有 lockfile，锁的是 devDependency 的 esbuild）再重试。');
+  if (!existsSync(outfile)) process.exit(1);
+  if (strict) {
+    console.error('✗ --strict：拒绝沿用已有的 dist/webui.js（可能是过期产物）。');
+    process.exit(1);
+  }
+  console.warn('! 非 strict 模式：沿用已有的 dist/webui.js（本地开发可以，发布不行）。');
+  process.exit(0);
+}
+
+if (verbose) console.log(`· esbuild ${found.version}：${found.bin}`);
+mkdirSync(join(pkgDir, 'dist'), { recursive: true });
+const result = spawnSync(process.execPath, [found.bin, ...args], { cwd: pkgDir, encoding: 'utf8' });
+if (result.stdout) process.stdout.write(result.stdout);
+if (result.stderr) process.stderr.write(result.stderr);
+if (result.status !== 0) {
+  console.error(`✗ esbuild 失败（退出码 ${result.status}）`);
+  process.exit(1);
+}
+
+const size = statSync(outfile).size;
+console.log(`✓ dist/webui.js 已重建（esbuild ${found.version}，${size} 字节）`);

package/scripts/contract.mjs

@@ -0,0 +1,342 @@
+#!/usr/bin/env node
+/**
+ * 契约测试：不依赖 Coopanion 宿主，纯 Node 就能跑。
+ *
+ * 覆盖审查报告里「看起来对、其实悄悄失效」的那一类问题——静态清单与源码是否一致、
+ * 促销时间判定、安全清单分层、账本字段名，以及复检报告点名「没有回归断言」的那些行为：
+ * 哨兵语义、计费域选择、429 软硬区分、面板方法白名单、账本并发、SSE 尾行 flush、启动兜底。
+ *
+ * 用法：
+ *   node scripts/contract.mjs            # 全部断言
+ *   node scripts/contract.mjs --verbose  # 逐条打印
+ */
+
+import { createServer } from 'node:http';
+import { existsSync, mkdtempSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+import { buildDescribe, renderDescribe } from './gen-describe.mjs';
+import { WB_DEFAULTS } from '../src/config.js';
+import { attachPromos, parsePromos, priceViewOf } from '../src/promo.js';
+import { classifyModel, CAUTION_MODEL_IDS, SAFE_MODEL_IDS } from '../src/safety.js';
+import { UsageLedger, dayKey, summarize } from '../src/usage.js';
+import { classifyHttpFailure, WbUpstream } from '../src/upstream.js';
+import { PANEL_METHODS, TOKEN_AUTO, TOKEN_CLEARED, WorkBuddyWorld } from '../src/world.js';
+
+const pkgDir = fileURLToPath(new URL('..', import.meta.url));
+const verbose = process.argv.includes('--verbose');
+
+let passed = 0;
+const failures = [];
+
+function ok(condition, label, detail) {
+  if (condition) {
+    passed += 1;
+    if (verbose) console.log(`  ✓ ${label}`);
+    return;
+  }
+  const text = detail === undefined ? label : `${label}（实际：${JSON.stringify(detail)}）`;
+  failures.push(text);
+  if (verbose || failures.length <= 5) console.error(`  ✗ ${text}`);
+}
+
+function readJson(name) {
+  return JSON.parse(readFileSync(join(pkgDir, name), 'utf8'));
+}
+
+const pkg = readJson('package.json');
+const describe = readJson('describe.json');
+
+/* ---------------------------------------------------------------- 静态清单 */
+
+console.log('· 清单与源码一致性');
+ok(
+  renderDescribe(buildDescribe()) === readFileSync(join(pkgDir, 'describe.json'), 'utf8'),
+  'describe.json 与 WB_TOOL_DECLS / ENV_PROMPT.md 一致（跑 node scripts/gen-describe.mjs 可修）',
+);
+
+const changelog = readFileSync(join(pkgDir, 'CHANGELOG.md'), 'utf8');
+ok(
+  new RegExp(`^## ${pkg.version.replace(/\./g, '\\.')}$`, 'm').test(changelog),
+  `CHANGELOG.md 里有 ## ${pkg.version} 段落`,
+);
+
+ok(pkg.cortico?.kind === 'world', 'cortico.kind = world');
+ok(typeof pkg.cortico?.api === 'number', 'cortico.api 是数字（宿主按它判断兼容）');
+ok(Array.isArray(pkg.cortico?.tags), 'cortico.tags 是数组（市场会渲染标签）');
+ok(Array.isArray(pkg.cortico?.os) && pkg.cortico.os.includes('win32'), 'cortico.os 明确声明 win32');
+
+for (const rel of ['src/index.js', pkg.cortico.describe, pkg.cortico.icon, pkg.cortico.webUiClient, pkg.cortico.webUiStyle]) {
+  ok(existsSync(join(pkgDir, rel)), `文件存在：${rel}`);
+}
+
+ok(!existsSync(join(pkgDir, 'ENV_PROMPT.md')), '包里没有那份旧的根 ENV_PROMPT.md（真正模板在 src/）');
+for (const need of ['src', 'dist', 'assets', 'scripts', 'describe.json', 'README.md', 'CHANGELOG.md']) {
+  ok((pkg.files ?? []).includes(need), `files 覆盖 ${need}`);
+}
+
+/* ------------------------------------------- 环境提示词占位符 ↔ envPromptVars */
+
+console.log('· 环境提示词变量');
+const worldSource = readFileSync(join(pkgDir, 'src/world.js'), 'utf8');
+const declared = new Set([...worldSource.matchAll(/'(workbuddy\.[A-Za-z]+)':/g)].map((m) => m[1]));
+const used = new Set([...describe.envPrompt.matchAll(/\{\{(workbuddy\.[A-Za-z]+)\}\}/g)].map((m) => m[1]));
+const missing = [...used].filter((name) => !declared.has(name));
+ok(missing.length === 0, 'envPrompt 里每个 {{workbuddy.x}} 都有对应变量', missing);
+ok(used.size >= 8, `envPrompt 用到了 ${used.size} 个变量`);
+
+const toolNames = describe.tools.map((t) => t.name).sort();
+ok(
+  toolNames.join(',') === ['wb_chat', 'wb_credits', 'wb_list_models', 'wb_select_model'].join(','),
+  'describe.tools 名字齐全',
+);
+ok(
+  describe.tools.every((t) => Array.isArray(t.tags) && t.parameters?.type === 'object'),
+  '每个工具都有 tags 与 object 参数',
+);
+
+/* ------------------------------------------------------------------- 促销 */
+
+console.log('· 促销与倍率');
+const NOW = Date.parse('2026-11-03T23:30:00+08:00');
+const promotions = [
+  {
+    id: 'night',
+    kind: 'discount',
+    enabled: true,
+    priority: 100,
+    modelIds: ['glm-5.2'],
+    discount: { discountedCredits: '0.50x', factor: 0.5, displayMode: 'strikethrough' },
+    schedule: { timezone: 'Asia/Shanghai', daily: [{ start: '23:00', end: '7:50' }] },
+  },
+  {
+    id: 'badge-only',
+    kind: 'discount',
+    enabled: true,
+    priority: 500,
+    modelIds: ['glm-5.2'],
+    badge: { label: '白天徽标' },
+    schedule: { timezone: 'Asia/Shanghai', daily: [{ start: '00:00', end: '23:59' }] },
+  },
+  {
+    id: 'expired',
+    kind: 'discount',
+    enabled: true,
+    priority: 900,
+    modelIds: ['glm-5.2'],
+    discount: { discountedCredits: '0x', displayMode: 'replace' },
+    schedule: { timezone: 'Asia/Shanghai', validUntil: '2020-01-01T00:00:00Z' },
+  },
+  {
+    id: 'numeric',
+    kind: 'discount',
+    enabled: true,
+    priority: 60,
+    modelIds: ['hy3'],
+    discount: { discountedCredits: '0.25x', displayMode: 'replace' },
+    schedule: { timezone: 'Asia/Shanghai', validUntil: 1893456000 },
+  },
+  {
+    id: 'bad-zone',
+    kind: 'discount',
+    enabled: true,
+    priority: 40,
+    modelIds: ['hunyuan-chat'],
+    discount: { discountedCredits: '0.10x', displayMode: 'replace' },
+    schedule: { timezone: 'Not/AZone', daily: [{ start: '00:00', end: '23:59' }] },
+  },
+];
+const promos = parsePromos(promotions, []);
+const models = attachPromos(
+  [
+    { id: 'glm-5.2', credits: 'x0.79' },
+    { id: 'hy3', credits: 'x0' },
+    { id: 'hunyuan-chat', credits: 'x0.30' },
+  ],
+  promos,
+);
+
+const night = priceViewOf(models[0], NOW);
+ok(night.promoId === 'night', '夜里挑的是真正改价的那条促销（不是优先级更高的徽标项）', night.promoId);
+ok(night.effective === 0.5, '夜里生效倍率 = 0.5', night.effective);
+ok(night.base === 0.79, '目录倍率 x0.79 解析正确', night.base);
+ok(night.windowText === '23:00–07:50', '时段文案', night.windowText);
+ok(night.discounted === true, 'discounted 标记为真');
+
+const noon = priceViewOf(models[0], Date.parse('2026-11-03T12:00:00+08:00'));
+ok(noon.effective === 0.79, '白天不打折', noon.effective);
+ok(noon.promoId === undefined || noon.promoId === null, '白天不挂促销 id（过期那条与徽标条都不该改价）', noon.promoId);
+
+const numeric = priceViewOf(models[1], NOW);
+ok(numeric.promoId === 'numeric', '数字时间戳（Unix 秒）的有效期被识别', numeric.promoId);
+
+const badZone = priceViewOf(models[2], NOW);
+ok(badZone.promoId === 'bad-zone', '非法时区退回 UTC 后窗口仍生效', badZone.promoId);
+
+/* ------------------------------------------------------------------- 安全 */
+
+console.log('· 安全清单');
+ok(SAFE_MODEL_IDS.includes('hy4-preview'), 'hy4-preview 在安全清单里');
+ok(CAUTION_MODEL_IDS.includes('hy4-preview'), 'hy4-preview 标为谨慎档');
+
+const hy4 = classifyModel('hy4-preview', { id: 'hy4-preview' });
+ok(hy4.allow === true && hy4.caution === true, 'hy4-preview 可调用但带谨慎提示', hy4);
+
+const lite = classifyModel('wb-lite', { id: 'wb-lite', disabled: true });
+ok(lite.tier === 'disabled' && lite.allow === false, '目录标 disabled 的模型被拒绝', lite.tier);
+
+const alias = classifyModel('auto', { id: 'auto' });
+ok(alias.tier === 'alias' && alias.allow === false, '内部别名被拒绝', alias.tier);
+
+const media = classifyModel('hunyuan-image-alpha', { id: 'hunyuan-image-alpha' });
+ok(media.tier === 'media' && media.allow === false, '媒体模型被拒绝', media.tier);
+
+const retired = classifyModel('glm-4.6', { id: 'glm-4.6' });
+ok(retired.tier === 'retired' && retired.allow === false, '已下架模型被拒绝', retired.tier);
+
+const unknown = classifyModel('totally-new-model', { id: 'totally-new-model' });
+ok(unknown.allow === false, '未知模型默认不放行', unknown.allow);
+
+/* ------------------------------------------------------------------- 账本 */
+
+console.log('· 用量账本');
+const nowMs = Date.parse('2026-11-03T10:00:00+08:00');
+const records = [
+  { ts: nowMs - 3600e3, model: 'deepseek-v4.1-flash', ok: true, promptTokens: 15, completionTokens: 4, totalTokens: 19, credit: 0, multiplier: 0.11 },
+  { ts: nowMs - 3 * 864e5, model: 'glm-5.2', ok: true, promptTokens: 100, completionTokens: 50, totalTokens: 150, credit: 1.25, multiplier: 0.5 },
+  { ts: nowMs - 40 * 864e5, model: 'hy3', ok: false, promptTokens: 0, completionTokens: 0, totalTokens: 0, credit: 0 },
+];
+const summary = summarize(records, nowMs, { days: 30 });
+ok(summary.totals.today.calls === 1, '今天只统计今天那条', summary.totals.today.calls);
+ok(summary.totals.week.calls === 2, '近 7 天含 3 天前那条', summary.totals.week.calls);
+ok(summary.totals.month.calls === 2, '近 30 天不含 40 天前那条', summary.totals.month.calls);
+ok(summary.totals.all.calls === 3, '全部含失败那条', summary.totals.all.calls);
+ok(summary.totals.month.failed === 0, '近 30 天没有失败', summary.totals.month.failed);
+ok(summary.recent[0].total === 19, '最近记录按时间倒序取到最新那条（total=19，不是最旧那条）', summary.recent[0].total);
+ok(
+  summary.recent.every((r) => 'total' in r && 'prompt' in r && 'completion' in r),
+  '最近记录的字段名是 total/prompt/completion（面板按这三个名字读）',
+);
+ok(summary.byModel[0].model === 'glm-5.2', '按模型聚合按积分降序', summary.byModel.map((m) => m.model));
+
+/* --------------------------------------------------------------- 回归防线 */
+
+console.log('· 回归防线（复检报告第 9 条点名缺断言的行为）');
+
+// 哨兵：wb-cleared 表示用户登出，wb-auto 表示「允许自动发现」
+ok(TOKEN_CLEARED === 'wb-cleared' && TOKEN_AUTO === 'wb-auto', '两个凭据哨兵的取值稳定', [TOKEN_CLEARED, TOKEN_AUTO]);
+
+const emptyCredDir = mkdtempSync(join(tmpdir(), 'wb-cred-'));
+
+/** 造一个最小 World：只喂 loadTokens 需要的东西，避免碰真机凭据。 */
+function makeWorld(secretValue) {
+  const ctx = {
+    id: 'workbuddy',
+    cfg: { ...WB_DEFAULTS, credentialsDir: emptyCredDir, model: 'deepseek-v4.1-flash' },
+    timezone: 'Asia/Shanghai',
+    botName: 'Coo',
+    botDir: emptyCredDir,
+    packageDir: pkgDir,
+    dataDir: mkdtempSync(join(tmpdir(), 'wb-data-')),
+    repoRoot: pkgDir,
+    secret: () => secretValue,
+    storeSecret: () => {},
+    persist: () => {},
+    restart: async () => {},
+  };
+  return new WorkBuddyWorld({ ctx });
+}
+
+const signedOutWorld = makeWorld(TOKEN_CLEARED);
+await signedOutWorld.loadTokens();
+ok(signedOutWorld.tokens === null, 'wb-cleared：不读数据目录凭据', signedOutWorld.tokens);
+ok(/已登出|重新探测/.test(String(signedOutWorld.lastError ?? '')), 'wb-cleared：提示用户已登出（可重新探测）', signedOutWorld.lastError);
+
+const autoWorld = makeWorld(TOKEN_AUTO);
+await autoWorld.loadTokens();
+ok(autoWorld.tokens === null, 'wb-auto：空目录下没有可用凭据', autoWorld.tokens);
+ok(
+  !/已登出/.test(String(autoWorld.lastError ?? '')),
+  'wb-auto：不会把自己判成「已登出」（否则 rediscover 后重启又变未登录）',
+  autoWorld.lastError,
+);
+
+// 计费域：按区域，不按 baseUrl 猜；自定义 baseUrl 时跟着走同一出口
+const cnUp = new WbUpstream({ baseUrl: 'https://copilot.tencent.com', region: 'cn' });
+ok(cnUp.billingUrl('/x').startsWith('https://www.codebuddy.cn'), 'cn 计费域是 www.codebuddy.cn', cnUp.billingUrl('/x'));
+const globalUp = new WbUpstream({ baseUrl: 'https://www.workbuddy.ai', region: 'global' });
+ok(globalUp.billingUrl('/x').startsWith('https://www.workbuddy.ai'), 'global 计费域是 www.workbuddy.ai', globalUp.billingUrl('/x'));
+const proxyUp = new WbUpstream({ baseUrl: 'https://proxy.example.com', region: 'cn' });
+ok(proxyUp.billingUrl('/x') === 'https://proxy.example.com/x', '自定义 baseUrl 时计费走同一出口', proxyUp.billingUrl('/x'));
+
+// 429 的软/硬区分
+ok(classifyHttpFailure(429, '额度不足，请充值') === 'hard_credit', '429 + 额度文案 → hard_credit', classifyHttpFailure(429, '额度不足，请充值'));
+ok(classifyHttpFailure(429, 'too many requests') === 'soft_rate', '429 普通限流 → soft_rate', classifyHttpFailure(429, 'too many requests'));
+
+// 面板方法白名单
+ok(
+  Array.isArray(PANEL_METHODS.account) && PANEL_METHODS.account.includes('setToken'),
+  '账号面板允许 setToken',
+);
+ok(!PANEL_METHODS.usage.includes('setToken'), '用量面板不能间接写密钥库（白名单生效）');
+ok(
+  !PANEL_METHODS.priority.includes('host') && !PANEL_METHODS.priority.includes('repair'),
+  '0.3.0 删掉主页注入后，priority 面板不再有 host/repair',
+  PANEL_METHODS.priority,
+);
+
+// 账本并发：append 与 prune 串行，不互相覆盖
+const ledger = new UsageLedger({ dataDir: mkdtempSync(join(tmpdir(), 'wb-ledger-')), log: { warn: () => {} } });
+await Promise.all(
+  Array.from({ length: 30 }, (_, i) =>
+    ledger.append({ ts: Date.now() - i * 1000, model: 'deepseek-v4.1-flash', ok: true, promptTokens: 1, completionTokens: 1, totalTokens: 2, credit: 0 }),
+  ),
+);
+await ledger.prune(Date.now());
+const kept = await ledger.readAll();
+ok(kept.length === 30, '并发 append + prune 后一条都没丢', kept.length);
+
+// 「今天」按本地日期算，不是 UTC
+ok(/getFullYear/.test(readFileSync(join(pkgDir, 'src', 'usage.js'), 'utf8')), 'dayKey 用本地日期字段（getFullYear），不用 toISOString');
+const localDay = dayKey(Date.parse('2026-11-03T12:00:00+08:00'));
+ok(/^\d{4}-\d{2}-\d{2}$/.test(localDay), 'dayKey 输出 YYYY-MM-DD', localDay);
+
+// SSE：最后一段 data 没有换行时也要把 usage 处理掉（否则积分恒 0）
+const sseServer = createServer((req, res) => {
+  res.writeHead(200, { 'Content-Type': 'text/event-stream' });
+  res.write('data: {"code":0,"choices":[{"delta":{"content":"嗨"}}]}\n\n');
+  // 末尾故意不带换行：老实现会把这段丢掉
+  res.write('data: {"code":0,"choices":[{"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":7,"completion_tokens":3,"total_tokens":10,"credit":0.02}}');
+  res.end();
+});
+await new Promise((resolve) => sseServer.listen(0, '127.0.0.1', resolve));
+const sseUrl = `http://127.0.0.1:${sseServer.address().port}`;
+const sseUp = new WbUpstream({ baseUrl: sseUrl, region: 'cn' });
+const chatOut = await sseUp.chat({ accessToken: 'test-token' }, { model: 'deepseek-v4.1-flash', messages: [{ role: 'user', content: 'hi' }], maxTokens: 64 }, () => {});
+sseServer.close();
+ok(chatOut.text === '嗨', 'SSE 正文拼接正确', chatOut.text);
+ok(chatOut.usage?.totalTokens === 10, 'SSE 尾行（无换行）里的 usage 被解析', chatOut.usage);
+ok(chatOut.credit === 0.02, 'SSE 尾行里的 credit 被解析', chatOut.credit);
+
+// start() 兜底：pushEvent 失败也不能把 started 卡住（否则四盏灯永远「正在读取登录态…」）
+const startWorld = makeWorld(TOKEN_CLEARED);
+const failingHost = {
+  log: { info: () => {}, warn: () => {}, error: () => {} },
+  pushEvent: () => Promise.reject(new Error('boom')),
+};
+await startWorld.start(failingHost);
+ok(startWorld.started === true, 'pushEvent 抛错时 start() 仍标记 started（灯态不卡住）');
+await startWorld.stop();
+
+/* ------------------------------------------------------------------- 结果 */
+
+console.log('');
+if (failures.length === 0) {
+  console.log(`✓ contract 通过：${passed} 条断言`);
+  process.exit(0);
+}
+console.error(`✗ contract 失败：${failures.length} 条（通过 ${passed} 条）`);
+for (const f of failures.slice(0, 20)) console.error(`  - ${f}`);
+process.exit(1);

package/scripts/gen-describe.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+/**
+ * 生成 `describe.json`。
+ *
+ * 为什么需要它：`describe.json` 是给市场/宿主看的清单，`WB_TOOL_DECLS` 是运行时真正注册的
+ * 工具声明。两份各写各的，于是 0.1.7 里 `wb_chat` / `wb_credits` 的描述已经对不上了。
+ * 这里把 `describe.json` 变成生成物：
+ *
+ *   - 工具名 / 描述 / 参数 / tags：来自 `src/world.js` 的 `WB_TOOL_DECLS`（唯一来源）；
+ *   - 中英摘要：本文件里的 `SUMMARIES`（市场展示用的短句，源码里没有这个概念）；
+ *   - 事件：本文件里的 `EVENTS`；
+ *   - 环境提示词：`src/ENV_PROMPT.md` 全文。
+ *
+ * 用法：
+ *   node scripts/gen-describe.mjs           # 写回 describe.json
+ *   node scripts/gen-describe.mjs --check   # 只比对，不一致退出码 1
+ */
+
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { WB_TOOL_DECLS } from '../src/world.js';
+
+const pkgDir = fileURLToPath(new URL('..', import.meta.url));
+
+/** 市场列表里显示的一两句摘要（describe.json 的 summary 字段）。 */
+const SUMMARIES = {
+  wb_list_models: {
+    zh: '列出 WorkBuddy 公开对话模型（安全清单）及各自的积分倍率、上下文与推理档；all=true 时附上被排除的项与原因。',
+    en: 'Lists the safe WorkBuddy chat models with multiplier, context and reasoning efforts; all=true also lists excluded ones with reasons.',
+  },
+  wb_select_model: {
+    zh: '选择 wb_chat 默认使用的 WorkBuddy 模型，选择会持久保存。',
+    en: 'Selects the default WorkBuddy model for wb_chat; the choice persists across restarts.',
+  },
+  wb_chat: {
+    zh: '向当前选中的 WorkBuddy 模型发一句单轮提问并取回答，会消耗用户自己的 WorkBuddy 积分。',
+    en: "Asks the selected WorkBuddy model a single-turn question; spends the user's own WorkBuddy credits.",
+  },
+  wb_credits: {
+    zh: '读取当前 WorkBuddy 账号的剩余积分与各积分包的已用/剩余（只读）。',
+    en: 'Shows remaining WorkBuddy credits and per-package usage (read-only).',
+  },
+};
+
+const EVENTS = [
+  {
+    type: 'workbuddy.started',
+    description: {
+      zh: 'World 挂载完成，报告登录态与目录概况。',
+      en: 'The World was mounted; reports sign-in and catalog status.',
+    },
+  },
+];
+
+/** 由源码生成 describe.json 的对象。 */
+export function buildDescribe() {
+  const envPrompt = readFileSync(join(pkgDir, 'src', 'ENV_PROMPT.md'), 'utf8').replace(/\s+$/, '');
+  return {
+    tools: WB_TOOL_DECLS.map((decl) => ({
+      name: decl.name,
+      description: decl.description,
+      summary: SUMMARIES[decl.name] ?? { zh: decl.name, en: decl.name },
+      tags: [...(decl.tags ?? [])],
+      parameters: decl.parameters,
+    })),
+    events: EVENTS,
+    envPrompt,
+  };
+}
+
+/** 便于测试：把对象序列化成写入文件时的文本。 */
+export function renderDescribe(obj = buildDescribe()) {
+  return `${JSON.stringify(obj, null, 2)}\n`;
+}
+
+const isMain = process.argv[1] !== undefined && resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url));
+if (isMain) {
+  const target = join(pkgDir, 'describe.json');
+  const next = renderDescribe();
+  if (process.argv.includes('--check')) {
+    let current = '';
+    try {
+      current = readFileSync(target, 'utf8');
+    } catch {
+      current = '';
+    }
+    if (current !== next) {
+      console.error('✗ describe.json 与源码不一致；跑 `node scripts/gen-describe.mjs` 重新生成。');
+      process.exit(1);
+    }
+    console.log('✓ describe.json 与源码一致');
+  } else {
+    writeFileSync(target, next, 'utf8');
+    console.log(`✓ 已生成 describe.json（tools ${WB_TOOL_DECLS.length} 个）`);
+  }
+}

package/scripts/lib/app-root.mjs

@@ -0,0 +1,41 @@
+/**
+ * 找 Coopanion 的 `resources/app` 目录（脚本共用）。
+ *
+ * 0.3.0 删掉了 `src/host.js`（不再注入宿主文件），但自检、UI 验证、构建脚本仍然需要
+ * 「宿主装在哪」这一个信息，所以把它单独抽成脚本侧的探测，扩展运行时不再依赖它。
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+/**
+ * @param {{ packageDir?: string }} [opts]
+ * @returns {string} app 目录绝对路径；找不到返回空串
+ */
+export function findAppRoot(opts = {}) {
+  const candidates = [];
+
+  const fromEnv = process.env.COOPANION_APP_ROOT;
+  if (fromEnv) candidates.push(fromEnv);
+
+  // data-location.json 里记着 data 目录，app 在它旁边的 resources/app
+  const localApp = process.env.LOCALAPPDATA;
+  if (localApp) {
+    const dataLocation = join(localApp, 'Coopanion', 'data-location.json');
+    if (existsSync(dataLocation)) {
+      try {
+        const data = JSON.parse(readFileSync(dataLocation, 'utf8')).data;
+        if (typeof data === 'string' && data) candidates.push(join(dirname(data), 'resources', 'app'));
+      } catch {
+        /* 读不出来就走下面的默认位置 */
+      }
+    }
+    candidates.push(join(localApp, 'Programs', 'Coopanion', 'resources', 'app'));
+  }
+
+  for (const base of [process.env.ProgramFiles, process.env['ProgramFiles(x86)']]) {
+    if (base) candidates.push(join(base, 'Coopanion', 'resources', 'app'));
+  }
+
+  return candidates.find((dir) => existsSync(join(dir, 'build', 'console', 'index.html'))) ?? '';
+}