@usercase/mcp 0.0.0-stage → 0.2.1-next.0

package/src/run/answer.js

@@ -0,0 +1,94 @@
+"use strict";
+/**
+ * 카드가 떴을 때 그 사람이 어떻게 하는가 — AI 에 보낼 글과 받을 모양.
+ *
+ * **선택지를 보기 전에 "이 사람이 굳이 답할 사람인가"(bothered) 부터 정한다.**
+ * 이 단계가 없으면 전원이 성실하게 답한다(2026-09-17: 방문 150번에 닫기 9번).
+ * 답할 비율은 지시하지 않는다 — 사람과 그 순간에서 나오게 두고 결과 비율은 보기만 한다.
+ *
+ * 의존성 없음. 프롬프트 글은 ../prompts/answer.md.
+ */
+const fs = require("fs");
+const path = require("path");
+
+const PROMPT_FILE = path.join(__dirname, "..", "prompts", "answer.md");
+
+const DECISION_SCHEMA = {
+  type: "object",
+  properties: {
+    bothered: { type: "boolean" },
+    botheredWhy: { type: "string" },
+    action: { type: "string", enum: ["choose", "other", "close"] },
+    choiceIndex: { type: "integer" },
+    otherText: { type: "string" },
+    why: { type: "string" },
+  },
+  // 순서가 곧 판단 순서다. bothered 를 먼저 쓰게 한다
+  required: ["bothered", "botheredWhy", "action", "choiceIndex", "otherText", "why"],
+};
+
+function systemPrompt() {
+  return fs.readFileSync(PROMPT_FILE, "utf8");
+}
+
+/**
+ * @param person    가상 사용자 (people.js PERSON_FIELDS)
+ * @param siteAbout 사이트가 어떤 곳인지
+ * @param pathText  이번 방문에서 한 일(영어)
+ * @param screen    카드가 뜬 순간 페이지 글자
+ * @param card      { question, choices }
+ * @param seen      도중에 거쳐 간 페이지들 [{url, text}] — 카드가 뜬 페이지만으로 모자랄 때
+ */
+function buildMessage(person, siteAbout, pathText, screen, card, seen = []) {
+  const earlier = seen.flatMap((x) => [`## Page they opened earlier in this visit (${x.url})`, "```", x.text, "```", ""]);
+  return [
+    "## Website",
+    siteAbout,
+    "",
+    "## The person",
+    `- device: ${person.device}`,
+    `- background: ${person.background}`,
+    `- goal for this visit: ${person.goal}`,
+    `- state right now: ${person.moment ?? "(not given)"}`,
+    `- takes in a page by: ${person.attention ?? "reads"}`,
+    `- survey cards that pop up: ${{ ignores: "usually ignores them", willing: "is usually happy to answer them" }[person.surveyHabit] || "sometimes answers them"}`,
+    `- types: ${person.writing ?? "careful"}`,
+    "",
+    "## What they did in this visit",
+    pathText,
+    "",
+    ...earlier,
+    "## Page text when the card appeared",
+    "```",
+    screen,
+    "```",
+    "",
+    "## The card",
+    `Question: ${card.question}`,
+    // 자유 입력 질문은 선택지가 없다. 자기 말로 쓰거나 닫거나뿐이다
+    ...(card.choices.length
+      ? [
+          "Options:",
+          ...card.choices.map((c, i) => `[${i}] ${c}`),
+          "The card also has a box to type an answer of their own, and a close button.",
+        ]
+      : [
+          "This card has no options — only a box to type an answer in their own words, and a close button.",
+          'When they answer, `action` is "other" and the words go in `otherText`.',
+        ]),
+  ].join("\n");
+}
+
+/** AI 가 준 결정을 실제 조작으로. 범위 밖 번호·빈 글은 닫기로 본다 */
+function toAction(decision, card) {
+  if (!decision.bothered) return { kind: "close", reason: "not_bothered" };
+  if (decision.action === "choose" && decision.choiceIndex >= 0 && decision.choiceIndex < card.choices.length) {
+    return { kind: "choose", index: decision.choiceIndex };
+  }
+  if (decision.action === "other" && decision.otherText.trim()) {
+    return { kind: "other", text: decision.otherText.trim().slice(0, 300) };
+  }
+  return { kind: "close", reason: decision.action === "close" ? "closed" : `invalid_${decision.action}` };
+}
+
+module.exports = { DECISION_SCHEMA, PROMPT_FILE, systemPrompt, buildMessage, toAction };

package/src/run/diag.js

@@ -0,0 +1,64 @@
+"use strict";
+/**
+ * 진단 — 가상 사용자가 사이트에서 **하지 못한 것**을 모아 어닝버드 서버로 보낸다. 도구를 고치려고 받는다.
+ *
+ * 사이트마다 다른 이유로 막힌다(회전 배너를 밀 수 없어서, 화면 밖으로 잘려서, 덮개 때문에 …).
+ * bluetags 하나로는 다 못 찾는다(10/15 — 스와이프가 없어서 배너 끝 카드를 못 눌렀다).
+ *
+ * **사이트 글자·주소·입력값은 보내지 않는다.** 실패의 종류와 요소의 생김새(태그·역할·아이콘인지·회전 배너 안인지·
+ * 고정 위치인지·대화상자 안인지·크기)만. 고객 방문 기록(/agent/visits)과 따로 간다.
+ * 기본으로 켜져 있고 USERCASE_DIAGNOSTICS=off 로 끈다. API 키가 있을 때만 간다(키가 프로젝트를 정한다).
+ */
+
+const OFF = /^(0|off|false|no)$/i;
+const enabled = () => !OFF.test(String(process.env.USERCASE_DIAGNOSTICS || "").trim());
+
+/** 방문자에게 간 말 → 실패 종류. 도구가 만든 말이라 사이트 글자는 섞이지 않는다 */
+function kindOf(skipped) {
+  const s = String(skipped || "");
+  if (/cut off at the edge|off the edge of the screen/.test(s)) return "cut_off";
+  if (/survey card is on top/.test(s)) return "covered_by_card";
+  if (/on top of it/.test(s)) return "covered";
+  if (/greyed out/.test(s)) return "disabled";
+  if (/not visible on the screen/.test(s)) return "not_visible";
+  if (/no longer there/.test(s)) return "stale";
+  if (/get into that field/.test(s)) return "field_unreachable";
+  if (/nothing happened when you clicked/.test(s)) return "no_effect";
+  if (/not on the screen/.test(s)) return "bad_index";
+  return null; // 정책으로 막은 것(결제·로그아웃 등)은 도구 실패가 아니다
+}
+
+/** 요소의 생김새 — 글자 없이. 페이지 안에서 돈다 */
+async function shapeOf(el) {
+  if (!el) return null;
+  return el
+    .evaluate((n) => {
+      const r = n.getBoundingClientRect();
+      let carousel = false;
+      let fixed = false;
+      let dialog = false;
+      for (let p = n, d = 0; p && p !== document.body && d < 25; p = p.parentElement, d++) {
+        const cs = getComputedStyle(p);
+        if (cs.overflowX !== "visible" && p.scrollWidth > p.clientWidth + 2) carousel = true;
+        if (cs.position === "fixed" || cs.position === "sticky") fixed = true;
+        if (p.matches('[role="dialog"],[role="alertdialog"],dialog,[aria-modal="true"]')) dialog = true;
+      }
+      let react = false;
+      for (const k in n) if (k.startsWith("__reactProps") && n[k] && typeof n[k].onClick === "function") react = true;
+      return {
+        tag: n.tagName.toLowerCase(),
+        role: n.getAttribute("role") || undefined,
+        icon: !(n.innerText || "").trim(),
+        svg: n.tagName.toLowerCase() === "svg" || !!n.querySelector("svg"),
+        carousel,
+        fixed,
+        dialog,
+        react,
+        w: Math.round(r.width),
+        h: Math.round(r.height),
+      };
+    })
+    .catch(() => null);
+}
+
+module.exports = { enabled, kindOf, shapeOf };

package/src/run/entry.js

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * 어디로 들어오나 — 유입.
+ *
+ * 전원이 홈에서 시작하면 사람 같지 않다. 실제로는 검색 결과나 공유된 링크를 타고
+ * 상세 페이지에 바로 떨어지는 방문이 많고, 그런 방문은 한 쪽만 보고 나간다.
+ * 들어오는 자리가 다르면 다니는 길도, 뜨는 질문도 달라진다.
+ *
+ * 어떻게 들어왔는지는 **그 사람 설정**(arrival)에서 나온다. 우리가 비율을 정하지 않는다 —
+ * MCP 로 팔 때는 고객이 "우리 유입은 대개 검색" 처럼 준다.
+ *
+ * 의존성 없음.
+ */
+
+/** 사람이 말한 유입 → 어디로 떨어지고 어디서 왔다고 할 것인가 */
+const REFERRERS = {
+  search: "https://www.google.com/",
+  social: "https://t.co/",
+  shared: "",
+  direct: "",
+};
+
+/** 사이트 안 링크를 모은다. 홈에 걸린 것만 봐도 그 사이트가 뭘 밀고 있는지 나온다 */
+async function collectLinks(page, site) {
+  await page.goto(site + "/", { waitUntil: "domcontentloaded" });
+  await page.waitForTimeout(1500);
+  const links = await page
+    .evaluate(() =>
+      [
+        ...new Set(
+          Array.from(document.querySelectorAll('a[href^="/"]'))
+            .map((a) => a.getAttribute("href"))
+            .filter((h) => h && h !== "/" && !h.startsWith("//")),
+        ),
+      ].slice(0, 200),
+    )
+    .catch(() => []);
+  // 링크 글자도 같이 — 착지 화면을 고를 때 주소만 보면 무슨 글인지 모른다(10/15 실험실: Azuki 인 줄 알았던 카드가 다른 프로젝트였다)
+  const text = await page
+    .evaluate(() => {
+      const out = {};
+      for (const a of document.querySelectorAll('a[href^="/"]')) {
+        const h = a.getAttribute("href");
+        const t = (a.innerText || a.getAttribute("aria-label") || "").replace(/\s+/g, " ").trim();
+        if (h && t && !out[h]) out[h] = t.slice(0, 60);
+      }
+      return out;
+    })
+    .catch(() => ({}));
+  Object.defineProperty(links, "text", { value: text, enumerable: false });
+  return links;
+}
+
+/**
+ * 이 사람이 이번에 어디로 들어오나.
+ * @param person  arrival: "search" | "social" | "shared" | "direct" (없으면 direct)
+ * @param links   collectLinks 로 모은 사이트 안 경로들
+ */
+function chooseEntry(person, links, rnd = Math.random) {
+  const arrival = person.arrival ?? "direct";
+  // 캐스팅 때 정한 착지 화면. 검색한 사람은 그 글로, 즐겨찾기한 사람은 그 화면으로 — 무작위 상세로 떨어뜨리면
+  // "Uniswap 지갑" 을 찾던 사람이 엉뚱한 프로젝트 화면에서 시작해 방문 앞부분을 수습에 썼다(10/14 실험실)
+  if (typeof person.landing === "string" && person.landing.startsWith("/")) {
+    return { path: person.landing, referer: REFERRERS[arrival] ?? "", how: arrival };
+  }
+  const deep = links.filter((h) => (h.match(/\//g) || []).length >= 2);
+  const pick = (list) => (list.length ? list[Math.floor(rnd() * list.length)] : "/");
+
+  // 검색·공유로 온 사람은 그 글 하나를 보러 온 것이다 — 목록이 아니라 상세로 떨어진다
+  if (arrival === "search" || arrival === "social" || arrival === "shared") {
+    return { path: pick(deep.length ? deep : links), referer: REFERRERS[arrival], how: arrival };
+  }
+  return { path: "/", referer: "", how: "direct" };
+}
+
+module.exports = { REFERRERS, collectLinks, chooseEntry };

package/src/run/runner.js

@@ -0,0 +1,205 @@
+"use strict";
+/**
+ * 가상 사용자 여러 명을 돌린다 — MCP 의 `run_visits` 가 이걸 부른다.
+ *
+ * 한 명의 한 방문은 `visit.js`, 여기는 그 바깥: 브라우저 하나, 동시 몇 명, 누가 어디로 들어오나, 막히면 멈추기.
+ *
+ * - **막히면 멈춘다.** 차단 판정이 나면 남은 사람을 돌리지 않는다. 같은 벽에 계속 부딪히면 사이트에 더 수상해 보이고 비용만 든다
+ * - **차단 화면에서는 AI 를 부르지 않는다.** 전에는 막힌 화면을 AI 에 보여주고 "떠남" 을 고르게 했다(9/21, 한 번에 8천 토큰)
+ * - 동시 실행은 최대 5. 같은 사이트를 짧은 시간에 되풀이하면 쓰로틀링에 걸린다(9/21 사람인)
+ *
+ * Playwright 와 AI(`ask`)는 받아 쓴다.
+ */
+
+const persona = require("../persona/persona.js");
+const { personKey } = require("../persona/people.js");
+const { runVisit } = require("./visit.js");
+const entry = require("./entry.js");
+const { createGuard } = require("../browser/guard.js");
+const policyMod = require("../browser/policy.js");
+const { loadRobots } = require("../browser/robots.js");
+const { launchBrowser, openVisit } = require("../browser/open.js");
+const { createBlockWatch, describeBlock } = require("../browser/blocked.js");
+const { sleep, agentKey, AGENT_HEADER, KEY_HEADER, uaWith } = require("../browser/card.js");
+
+const MAX_CONCURRENCY = 5;
+
+/** SDK 가 응답에 실어 보낼 그 사람. 닫고 나가도 남아야 해서 방문 내내 붙어 있다 */
+const personaCard = (p) => ({
+  id: p.id,
+  device: p.device,
+  background: p.background,
+  goal: p.goal,
+  moment: p.moment,
+  attention: p.attention,
+  surveyHabit: p.surveyHabit,
+  writing: p.writing,
+  traits: p.traits,
+  path: "free exploration",
+});
+
+/**
+ * @param playwright   require("playwright")
+ * @param site         고객 사이트 주소
+ * @param siteAbout    사이트 한 줄 설명(영어, AI 에 간다)
+ * @param people       돌릴 사람들. 순서대로 쓴다
+ * @param ask          (system, schema, text) => JSON
+ * @param inject       { project, sdkSrc, serverOrigin } — 로컬 SDK 를 심을 때
+ * @param onVisit      방문 하나가 끝날 때마다 (row, person)
+ * @param log          사람이 읽을 한 줄
+ */
+function createRun({
+  playwright,
+  site,
+  siteAbout,
+  people,
+  ask,
+  agent = "qa-explore",
+  concurrency = 3,
+  stepCap = 40,
+  inject = null,
+  blockTrackers = true,
+  allowWritePaths = [],
+  /** 고객이 정한 금지 구역(browser/policy.js). 기본값은 사이트에 흔적을 남기는 조작을 막는다 */
+  policy = policyMod.load(process.env.USERCASE_POLICY || null),
+  headed = false,
+  storageState = undefined,
+  onVisit = () => {},
+  log = () => {},
+} = {}) {
+  site = site.replace(/\/$/, "");
+  const origin = new URL(site).origin;
+  // robots 는 브라우저를 띄울 때 읽는다(네트워크). 함수로 넘겨 읽히는 대로 반영되게
+  let robots = null;
+  const guard = createGuard({ site, inject, blockTrackers, allowWritePaths, policy, robots: () => robots });
+  // 실행 전체에서 하나 — **반복되는지**가 "막혔나" 판단의 핵심이다
+  const blockWatch = createBlockWatch();
+  const queue = [...people];
+  const rows = [];
+  const state = { status: "starting", stopped: null, total: people.length, done: 0, running: [] };
+  let browser = null;
+
+  async function visitOnce(p, links) {
+    const traits = persona.coerceTraits(p.traits, personKey(p)).traits;
+    const rhythm = new persona.Rhythm({ traits, visits: 1, device: p.device, source: p.traits ? "given" : "seed", seed: persona.seedOf(personKey(p)) });
+    // 이번 방문을 몇 쪽이나 볼지는 그 사람이 정한다(튕김·훑기·깊게). 우리가 자르지 않는다
+    const shape = persona.drawShape(Math.random, traits, persona.familiarityOf(1));
+    const ctx = await openVisit(browser, playwright.devices, { agent, site, guard, device: p.device, persona: personaCard(p), storageState });
+    const page = await ctx.newPage();
+    blockWatch.watch(page, origin);
+    const row = { person: p.id, device: p.device, goal: p.goal, shape, at: new Date().toISOString() };
+    const startedAt = Date.now();
+    try {
+      // 어디로 들어오나. 검색·공유로 온 사람은 목록이 아니라 그 글에 바로 떨어진다
+      const how = entry.chooseEntry(p, links);
+      row.entry = how;
+      await page.goto(site + how.path, { waitUntil: "domcontentloaded", referer: how.referer || undefined });
+      // 차단 페이지는 정상 응답으로 와서 goto 가 성공한다. 화면을 보고 가린다
+      const blockedPage = blockWatch.notePage({
+        title: await page.title().catch(() => ""),
+        text: await page.evaluate(() => (document.body || {}).innerText || "").catch(() => ""),
+        path: how.path,
+      });
+      if (blockedPage) {
+        row.blocked = true;
+        row.steps = [];
+        log(`   ${p.id.padEnd(5)} 차단 화면 — 걷지 않는다`);
+      } else {
+        const out = await runVisit(page, p, {
+          siteAbout,
+          ask,
+          rhythm,
+          shape,
+          maxStepsCap: stepCap,
+          policy,
+          log: (line) => log(`   ${p.id.padEnd(5)} ${line}`),
+        });
+        row.steps = out.steps;
+        row.pages = [...new Set(out.steps.map((s) => s.path))];
+        row.card = out.card;
+      }
+    } catch (e) {
+      row.error = String(e.message).split("\n")[0].slice(0, 160);
+    }
+    row.ms = Date.now() - startedAt;
+    await sleep(1500);
+    await ctx.close();
+    return row;
+  }
+
+  async function run() {
+    browser = await launchBrowser(playwright, { headed, localSdk: !!inject && /localhost|127\.0\.0\.1/.test(inject.sdkSrc) });
+    // 사이트가 적어 둔 robots.txt 를 먼저 읽는다. 우리가 보내는 첫 요청이라 여기서부터 자기를 밝힌다
+    const key = agentKey();
+    robots = await loadRobots(site, {
+      headers: { [AGENT_HEADER]: agent, "User-Agent": uaWith(agent, "Mozilla/5.0 (compatible)"), ...(key ? { [KEY_HEADER]: key } : {}) },
+    });
+    log(robots.describe());
+    try {
+      // 사이트 안 링크를 한 번 모은다. 검색·공유로 들어오는 사람이 떨어질 자리다.
+      // 이것도 고객 사이트 방문이다 — 같은 순서로 열어 가상 사용자로 밝힌다
+      const scout = await openVisit(browser, playwright.devices, { agent, site, guard, debugCards: false, storageState });
+      const scoutPage = await scout.newPage();
+      blockWatch.watch(scoutPage, origin);
+      const links = await entry.collectLinks(scoutPage, site).catch(() => []);
+      blockWatch.notePage({ title: await scoutPage.title().catch(() => ""), text: await scoutPage.evaluate(() => (document.body || {}).innerText || "").catch(() => ""), path: "/" });
+      await scout.close();
+      log(`사이트 안 링크 ${links.length}개 — 유입 후보`);
+      state.status = "running";
+
+      const workers = Array.from({ length: Math.max(1, Math.min(concurrency, MAX_CONCURRENCY, queue.length)) }, async () => {
+        for (let p = queue.shift(); p; p = queue.shift()) {
+          if (state.stopped) break;
+          // 이미 막혔으면 더 두드리지 않는다
+          if (blockWatch.verdict()) {
+            state.stopped = state.stopped || "blocked";
+            break;
+          }
+          log(`\n▶ ${p.id} (${p.device}) — ${p.goal}`);
+          state.running.push(p.id);
+          const row = await visitOnce(p, links);
+          state.running = state.running.filter((n) => n !== p.id);
+          rows.push(row);
+          state.done++;
+          onVisit(row, p);
+          log(
+            `   ✔ ${state.done}/${state.total} · ${row.shape.kind}(${row.shape.screens}쪽) · ${row.entry?.how ?? "?"} → ${row.entry?.path ?? "/"} · 걸음 ${row.steps?.length ?? 0} · ${Math.round((row.ms ?? 0) / 1000)}초 · 카드 ${row.card ? row.card.result : row.blocked ? "차단" : "안 뜸"}`,
+          );
+        }
+      });
+      await Promise.all(workers);
+    } finally {
+      await browser.close().catch(() => {});
+    }
+    state.status = state.stopped ? "stopped" : "done";
+    return result();
+  }
+
+  function result() {
+    const blocked = blockWatch.verdict();
+    return {
+      status: state.status,
+      stopped: state.stopped,
+      total: state.total,
+      done: state.done,
+      running: [...state.running],
+      rows: [...rows],
+      blocked,
+      blockedText: blocked ? describeBlock(blocked) : null,
+      guarded: guard.summary(),
+    };
+  }
+
+  return {
+    /** 끝까지 돈다. 결과를 돌려준다 */
+    run,
+    /** 지금 상태. 도는 중에도 부를 수 있다(MCP get_run) */
+    status: result,
+    /** 남은 사람을 안 돌린다. 지금 걷는 사람은 그 방문을 마친다 */
+    stop(reason = "stopped") {
+      state.stopped = reason;
+    },
+  };
+}
+
+module.exports = { createRun, MAX_CONCURRENCY };