tianshu-harness 3.23.0

package/dist/agent/worker-process/child.js

@@ -0,0 +1,407 @@
+#!/usr/bin/env -S node --expose-gc --max-old-space-size=4096
+import { createRequire as __rivetCreateRequire } from 'node:module'; const require = __rivetCreateRequire(import.meta.url);
+import {
+  buildModelCards
+} from "../../chunk-JYV7I2QH.js";
+import {
+  CHILD_TICK_INTERVAL_MS,
+  buildReviewOverrideState,
+  buildWorkerRuntime,
+  createFrameDecoder,
+  createInteractiveToolRegistry,
+  encodeFrame
+} from "../../chunk-AOYHP3WI.js";
+import "../../chunk-4U2ET7ZY.js";
+import "../../chunk-JBZHIC6T.js";
+import "../../chunk-KWVTXT5B.js";
+import "../../chunk-2XN7PM4N.js";
+import "../../chunk-SAXK6LVF.js";
+import "../../chunk-D2TCGRSX.js";
+import "../../chunk-73NJ7IT7.js";
+import {
+  DomainKnowledgeStore
+} from "../../chunk-5TQ3JYBU.js";
+import "../../chunk-KX22RD6R.js";
+import "../../chunk-BXHV3GSB.js";
+import "../../chunk-FW3QKMFX.js";
+import "../../chunk-WOE3D7JM.js";
+import {
+  DelegationCoordinator,
+  runWorkerSession
+} from "../../chunk-B3YEBABJ.js";
+import {
+  filterToolRegistry
+} from "../../chunk-UXXS53EA.js";
+import "../../chunk-DWROHPXP.js";
+import "../../chunk-ZDIFBJFT.js";
+import "../../chunk-D54ZWG4T.js";
+import "../../chunk-R43HJCDX.js";
+import "../../chunk-D4PTYFOG.js";
+import "../../chunk-AERM3VGP.js";
+import "../../chunk-RK3JHWPT.js";
+import "../../chunk-NH6VIOAR.js";
+import "../../chunk-S4K4L6IM.js";
+import "../../chunk-3VGD2FXB.js";
+import "../../chunk-UXNLELW6.js";
+import "../../chunk-TVHW77C7.js";
+import "../../chunk-424AP7FM.js";
+import "../../chunk-JCFWOULR.js";
+import "../../chunk-2HKD2UFM.js";
+import "../../chunk-5JRZPLI6.js";
+import "../../chunk-JRF5L6OD.js";
+import "../../chunk-EBJTVRQN.js";
+import "../../chunk-J4U4AW46.js";
+import "../../chunk-2HDP7RMR.js";
+import "../../chunk-OTNHSAGN.js";
+import "../../chunk-DZ6UOJ5D.js";
+import "../../chunk-T3ED6BY2.js";
+import "../../chunk-RAXBAWRN.js";
+import "../../chunk-4J5TZGOE.js";
+import "../../chunk-BUIMGNDD.js";
+import "../../chunk-ZU7JZCVP.js";
+import "../../chunk-JSS75KCG.js";
+import "../../chunk-EHHUASO5.js";
+import "../../chunk-LA6IPTGH.js";
+import "../../chunk-HBVF6BWO.js";
+import "../../chunk-UHGLFRZE.js";
+import {
+  deriveWorkerSessionId
+} from "../../chunk-4QJ3Y5JM.js";
+import "../../chunk-CGOADM2X.js";
+import "../../chunk-ZGGCEXDC.js";
+import "../../chunk-ZMZCZNKU.js";
+import "../../chunk-Z3QE7TZM.js";
+import "../../chunk-GHVMWF2I.js";
+import "../../chunk-J6ESSM47.js";
+import "../../chunk-3C3R7JXY.js";
+import "../../chunk-TI4GSEL5.js";
+import "../../chunk-OXMIV4WE.js";
+import "../../chunk-4XPFLICE.js";
+import {
+  PromptEngine
+} from "../../chunk-V5YIPMHV.js";
+import "../../chunk-ILBCKAV6.js";
+import {
+  createProviderClient,
+  resolveApiKey,
+  resolveCapabilities
+} from "../../chunk-X2IK5LVR.js";
+import "../../chunk-CEZNQVWM.js";
+import "../../chunk-O5VZQKCB.js";
+import "../../chunk-SEPGEJNK.js";
+import "../../chunk-7RDOV3DF.js";
+import {
+  profileRegistry
+} from "../../chunk-6HSVXHCZ.js";
+import "../../chunk-RWA23GMM.js";
+import "../../chunk-OHSV42QB.js";
+import "../../chunk-ADIVZ2D5.js";
+import "../../chunk-7FW3I7WC.js";
+import "../../chunk-GD4ZNZ7W.js";
+import "../../chunk-ZQKXBUB7.js";
+import "../../chunk-Z5Z3JHJY.js";
+import "../../chunk-KIOXTQQL.js";
+import "../../chunk-35H7GVNR.js";
+import "../../chunk-AE3P3F6W.js";
+import {
+  applyDescriptionMode
+} from "../../chunk-JSXWIWWJ.js";
+import "../../chunk-BSECIPAQ.js";
+import "../../chunk-2E6CK2RC.js";
+import "../../chunk-ZO3I3A7O.js";
+import "../../chunk-P6GJOVO6.js";
+import "../../chunk-TPI73L57.js";
+import "../../chunk-HV4YGVMS.js";
+import "../../chunk-722LQO64.js";
+import {
+  createAuthProvider
+} from "../../chunk-GMKAXSYQ.js";
+import "../../chunk-EPKTIOED.js";
+import "../../chunk-2VYRLULP.js";
+import "../../chunk-SUJERP5I.js";
+import "../../chunk-CI4R6P2B.js";
+import "../../chunk-XU2YXCDL.js";
+import "../../chunk-ETHFACAB.js";
+import "../../chunk-THKDVSEC.js";
+import "../../chunk-UFMN76QD.js";
+import "../../chunk-EXUE5W2F.js";
+import "../../chunk-LH5VCGLB.js";
+import "../../chunk-6S5FPUS7.js";
+import "../../chunk-EXXICUIW.js";
+import "../../chunk-QARAGUXX.js";
+import {
+  TodoStore
+} from "../../chunk-DEBI37QB.js";
+import "../../chunk-YJG5HIX5.js";
+import {
+  loadConfig,
+  subagentPromptBlocks
+} from "../../chunk-ER5JW2QZ.js";
+import "../../chunk-CGFZGR7G.js";
+import "../../chunk-P5KJURUR.js";
+import "../../chunk-WMUWEO2C.js";
+import "../../chunk-BKTQAYO2.js";
+import "../../chunk-OO3TAHO5.js";
+import "../../chunk-EGEI2RQA.js";
+import "../../chunk-ZTRINFM2.js";
+import "../../chunk-ZNC5T65N.js";
+import "../../chunk-7KUCBNLB.js";
+import "../../chunk-A5MNH4ER.js";
+import "../../chunk-BCQXEZPJ.js";
+import {
+  init_esm_shims
+} from "../../chunk-5GGOGLSN.js";
+
+// src/agent/worker-process/child.ts
+init_esm_shims();
+import { createInterface } from "readline";
+import { join } from "path";
+function writeFrame(msg) {
+  process.stdout.write(encodeFrame(msg));
+}
+function childLog(line) {
+  writeFrame({ t: "log", line });
+}
+function createBridgedMailbox() {
+  return {
+    send: (msg) => writeFrame({ t: "mailbox", msg }),
+    receive: () => [],
+    broadcast: () => {
+    },
+    all: () => [],
+    byType: () => [],
+    clear: () => {
+    },
+    size: () => 0
+  };
+}
+function buildChildCoordinator(deps, registry, config, parentApprovalMode) {
+  return new DelegationCoordinator({
+    baseToolRegistry: registry,
+    modelCards: buildModelCards(deps.provider),
+    maxWorkers: resolveMaxWorkers(config),
+    providers: config.provider.providers,
+    runtimeFactory: (order, card, workerRegistry) => buildWorkerRuntime(deps, order, card, workerRegistry),
+    routing: deps.workerRouting,
+    sharedWorktree: true,
+    patcherTier: config.workers.patcherTier,
+    escalationCap: config.workers.escalationCap,
+    parentApprovalMode,
+    maxDelegationDepth: config.agent.maxDelegationDepth
+  });
+}
+function resolveMaxWorkers(config) {
+  const raw = config.agent.maxWorkers;
+  if (typeof raw === "number" && Number.isInteger(raw) && raw >= 1) return raw;
+  const envN = Number(process.env["RIVET_MAX_WORKERS"]);
+  if (Number.isInteger(envN) && envN >= 1) return envN;
+  return 3;
+}
+async function runChild() {
+  const decoder = createFrameDecoder();
+  let initPayload;
+  const steerQueue = [];
+  const abortController = new AbortController();
+  const stdin = createInterface({ input: process.stdin });
+  stdin.on("line", (line) => {
+    for (const msg of decoder.feed(`${line}
+`)) {
+      if (msg.t === "init") {
+        initPayload = msg.payload;
+        if (msg.payload.steerSeed) steerQueue.push(msg.payload.steerSeed);
+        void bootAndRun(msg.payload, steerQueue, abortController);
+      } else if (msg.t === "steer") {
+        steerQueue.push(msg.text);
+      } else if (msg.t === "abort") {
+        abortController.abort(msg.reason);
+      }
+    }
+  });
+  stdin.on("close", () => {
+    if (!initPayload) process.exit(0);
+  });
+  const ticker = setInterval(() => writeFrame({ t: "tick", at: Date.now() }), CHILD_TICK_INTERVAL_MS);
+  ticker.unref?.();
+}
+async function bootAndRun(init, steerQueue, abortController) {
+  try {
+    const cfg = init.config;
+    const cwd = cfg.cwd;
+    const config = loadConfig({ cwd });
+    const providerName = cfg.providerName ?? config.provider.default;
+    const provider = config.provider.providers[providerName] ?? config.provider.providers[config.provider.default];
+    let apiKey = "";
+    try {
+      apiKey = resolveApiKey(provider);
+    } catch {
+      apiKey = "";
+    }
+    const auth = provider.auth ? createAuthProvider(provider.auth, process.env) : void 0;
+    const overrideState = config.agent.review?.profiles ? buildReviewOverrideState(config.agent.review.profiles, config.provider.providers) : { cards: /* @__PURE__ */ new Map(), overrides: /* @__PURE__ */ new Map() };
+    const reviewOverrides = overrideState.overrides;
+    const reviewOverrideApiKeys = /* @__PURE__ */ new Map();
+    for (const [profileName, resolved] of reviewOverrides) {
+      try {
+        reviewOverrideApiKeys.set(profileName, resolveApiKey(resolved.providerConfig));
+      } catch {
+        reviewOverrides.delete(profileName);
+      }
+    }
+    const workerRouting = config.workers?.profiles && Object.keys(config.workers.profiles).length > 0 ? { profiles: config.workers.profiles, routing: config.workers.routing, providers: config.provider.providers } : void 0;
+    const domainKnowledgeStore = new DomainKnowledgeStore(join(cwd, ".rivet", "knowledge"));
+    const deps = {
+      config,
+      cwd,
+      provider,
+      apiKey,
+      auth,
+      currentModelId: config.provider.default,
+      listActiveClaims: () => init.activeClaims,
+      sessionMemoryBlock: () => init.memoryBlock,
+      domainKnowledgeStore,
+      reviewOverrides,
+      reviewOverrideApiKeys,
+      workerRouting,
+      writeProfiles: profileRegistry.listWriteProfiles()
+    };
+    const refs = {
+      coordinator: null,
+      fileHistory: null,
+      claimStore: null,
+      sessionId: null,
+      sessionRegistry: null,
+      taskLedger: null,
+      ownershipLedger: null,
+      verificationSnapshotManager: null,
+      deliveryGate: null,
+      meridianIndexer: null,
+      mcpManager: null,
+      lspManager: null,
+      banditState: null,
+      promptEngine: null,
+      goalTrackerRef: { current: null },
+      reviewGateRef: { current: "auto" },
+      pluginHooks: [],
+      pluginCommands: [],
+      todoStore: new TodoStore()
+    };
+    const { registry } = createInteractiveToolRegistry(refs, config, cwd);
+    refs.coordinator = buildChildCoordinator(deps, registry, config, cfg.parentApprovalMode);
+    const decision = cfg.runtimeDecision;
+    if (!decision) throw new Error("init \u7F3A runtimeDecision\u2014\u2014\u7236\u8FDB\u7A0B buildWorkerRuntime \u672A\u76D6\u6233\uFF08\u7248\u672C\u4E0D\u5339\u914D\uFF1F\uFF09");
+    const presentTools = cfg.order.allowedTools.filter((name) => registry.has(name));
+    const missing = cfg.order.allowedTools.filter((name) => !registry.has(name));
+    if (missing.length > 0) childLog(`[worker-child] dropping ${missing.length} unregistered tool(s): ${missing.join(",")}`);
+    const workerRegistry = filterToolRegistry(registry, presentTools);
+    const providerForDecision = config.provider.providers[decision.providerName] ?? provider;
+    const modelSpec = providerForDecision.models.find((m) => m.id === decision.model);
+    const capabilities = resolveCapabilities(decision.providerName, providerForDecision.capabilities, modelSpec?.capabilities);
+    const blocks = subagentPromptBlocks();
+    const client = createProviderClient(providerForDecision, capabilities, {
+      apiKey,
+      model: decision.model,
+      reasoningEffort: void 0,
+      maxTokens: decision.maxTokens,
+      thinkingBudget: decision.thinkingBudget,
+      auth,
+      // 与父进程 buildWorkerRuntime 用同一公式（只取 order.id，不带 nonce）：
+      // 子进程重建 client 时若落回 factory 的进程兜底，同一 work order 会在父子
+      // 进程各拿一个 ID，上游会当成两段对话。
+      sessionId: deriveWorkerSessionId(cfg.order.id)
+    });
+    const promptEngine = new PromptEngine({
+      model: decision.model,
+      maxTokens: decision.maxTokens,
+      staticCtx: { tools: applyDescriptionMode(workerRegistry.getDefinitions(), blocks.toolDescriptions), audience: "subagent" },
+      volatileCtx: { cwd, sessionMemoryBlock: init.memoryBlock, blockCaps: blocks.caps },
+      // 续跑/复核/重试继承上一轮冻结快照——历史 user 消息恢复原始字节，
+      // 前缀缓存只在新 user 边界断尾（缺省/坏数据引擎内降级为冷启动）。
+      inheritFrozenFrom: cfg.priorFrozenSnapshot
+    });
+    const workerConfig = {
+      order: cfg.order,
+      client,
+      promptEngine,
+      toolRegistry: workerRegistry,
+      cwd,
+      maxTurns: cfg.maxTurns,
+      contextWindow: cfg.contextWindow,
+      compact: cfg.compact,
+      runtimeDecision: decision,
+      providerName: cfg.providerName,
+      baseUrl: cfg.baseUrl,
+      slowThinking: cfg.slowThinking,
+      forceJsonRepair: cfg.forceJsonRepair,
+      finalizeReport: cfg.finalizeReport,
+      reviewDepth: cfg.reviewDepth,
+      parentApprovalMode: cfg.parentApprovalMode,
+      activeClaims: init.activeClaims,
+      domainKnowledgeStore,
+      onActivity: (kind, detail) => writeFrame({ t: "activity", kind, detail }),
+      onSteerDrain: () => steerQueue.shift() ?? null,
+      onSessionReady: void 0,
+      onNestedDelegation: (activity) => writeFrame({ t: "nested", activity }),
+      checkpoint: cfg.checkpoint,
+      priorMessages: cfg.priorMessages,
+      priorUsage: cfg.priorUsage,
+      sessionNonce: cfg.sessionNonce,
+      mailbox: createBridgedMailbox(),
+      abortSignal: abortController.signal
+    };
+    const run = await runWorkerSession(workerConfig);
+    const messages = (() => {
+      try {
+        return run.session?.getMessages() ?? [];
+      } catch {
+        return [];
+      }
+    })();
+    writeFrame({
+      t: "result",
+      run: {
+        result: run.result,
+        transcript: run.transcript,
+        usage: run.usage,
+        checkpoint: run.checkpoint,
+        messages,
+        // 冻结快照随结果上行——导出失败不毁结果（下一轮退化为冷启动，与旧行为一致）。
+        frozenSnapshot: (() => {
+          try {
+            return promptEngine.exportFrozenSnapshot();
+          } catch {
+            return void 0;
+          }
+        })(),
+        turnCount: messages.length
+      }
+    });
+    process.stdout.end(() => process.exit(0));
+  } catch (err) {
+    childLog(`[worker-child] boot/run failed: ${err instanceof Error ? err.stack ?? err.message : String(err)}`);
+    writeFrame({
+      t: "result",
+      run: {
+        result: {
+          workOrderId: init.config.order.id,
+          status: "failed",
+          summary: `worker child crashed: ${err instanceof Error ? err.message : String(err)}`,
+          findings: [],
+          artifacts: [],
+          changedFiles: [],
+          risks: [],
+          nextActions: [],
+          evidenceStatus: "skipped",
+          failureReason: "worker_crash"
+        },
+        transcript: { text: "", thinking: "", toolUses: [], toolResults: [], repairAttempts: 0, errors: [String(err)] },
+        usage: { input_tokens: 0, output_tokens: 0, cache_read_input_tokens: 0, cache_creation_input_tokens: 0 },
+        messages: [],
+        turnCount: 0
+      }
+    });
+    process.exit(1);
+  }
+}
+if (process.argv.includes("--worker-child")) {
+  void runChild();
+}

package/dist/browser-cli-FLNY5ZHI.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env -S node --expose-gc --max-old-space-size=4096
+import { createRequire as __rivetCreateRequire } from 'node:module'; const require = __rivetCreateRequire(import.meta.url);
+import {
+  PLAYWRIGHT_MIRROR_HOST,
+  buildInstallPlan,
+  runBrowserCLI,
+  runBrowserInstall,
+  runBrowserStatus
+} from "./chunk-NGEWJ4DF.js";
+import "./chunk-MJQ55WZZ.js";
+import "./chunk-Z3QE7TZM.js";
+import "./chunk-5GGOGLSN.js";
+export {
+  PLAYWRIGHT_MIRROR_HOST,
+  buildInstallPlan,
+  runBrowserCLI,
+  runBrowserInstall,
+  runBrowserStatus
+};

package/dist/browser-readiness-LWVGSBD5.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env -S node --expose-gc --max-old-space-size=4096
+import { createRequire as __rivetCreateRequire } from 'node:module'; const require = __rivetCreateRequire(import.meta.url);
+import {
+  formatBrowserMissingBanner,
+  probeChromium
+} from "./chunk-MJQ55WZZ.js";
+import "./chunk-Z3QE7TZM.js";
+import "./chunk-5GGOGLSN.js";
+export {
+  formatBrowserMissingBanner,
+  probeChromium
+};

package/dist/build-backends-5KXKR2S4.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env -S node --expose-gc --max-old-space-size=4096
+import { createRequire as __rivetCreateRequire } from 'node:module'; const require = __rivetCreateRequire(import.meta.url);
+import {
+  buildSearchBackends,
+  resolveSearchKey
+} from "./chunk-J4U4AW46.js";
+import "./chunk-2HDP7RMR.js";
+import "./chunk-O5VZQKCB.js";
+import "./chunk-5GGOGLSN.js";
+export {
+  buildSearchBackends,
+  resolveSearchKey
+};

package/dist/build-options-66Y4ZE7C.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env -S node --expose-gc --max-old-space-size=4096
+import { createRequire as __rivetCreateRequire } from 'node:module'; const require = __rivetCreateRequire(import.meta.url);
+import {
+  buildFetchOptions
+} from "./chunk-KX22RD6R.js";
+import "./chunk-5GGOGLSN.js";
+export {
+  buildFetchOptions
+};

package/dist/bundled-skills/brainstorming/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: brainstorming
+description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation."
+triggers: ["(create|build|design) (a |an |the |a new |an entirely )?(new )?(feature|component|tool|module|app|screen|page|ui|skill|project)", "from scratch", "greenfield", "设计", "新功能", "新特性", "新建(功能|模块|组件)", "头脑风暴", "brainstorm(ing)?"]
+---
+# Brainstorming Ideas Into Designs
+
+Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
+
+Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design and get user approval.
+
+Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.
+
+## Anti-Pattern: "This Is Too Simple To Need A Design"
+
+Every project goes through this process. A todo list, a single-function utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval.
+
+## Checklist
+
+You MUST create a task for each of these items and complete them in order:
+
+1. **Explore project context** — check files, docs, recent commits
+2. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
+3. **Propose 2-3 approaches** — with trade-offs and your recommendation
+4. **Present design** — in sections scaled to their complexity, get user approval after each section
+5. **Write design doc** — save to `docs/superpowers/specs/YYYY-MM-DD--design.md` and commit
+6. **Spec self-review** — quick inline check for placeholders, contradictions, ambiguity, scope (see below)
+7. **User reviews written spec** — ask user to review the spec file before proceeding
+8. **Transition to planning** — create the implementation plan with the built-in `plan` tool (`plan action=enter_mode` → write plan → `plan action=submit`) and get it approved
+
+## Process Flow
+
+```dot
+digraph brainstorming {
+"Explore project context" [shape=box];
+"Ask clarifying questions" [shape=box];
+"Propose 2-3 approaches" [shape=box];
+"Present design sections" [shape=box];
+"User approves design?" [shape=diamond];
+"Write design doc" [shape=box];
+"Spec self-review\n(fix inline)" [shape=box];
+"User reviews spec?" [shape=diamond];
+"Create implementation plan\n(plan tool submit)" [shape=doublecircle];
+
+"Explore project context" -> "Ask clarifying questions";
+"Ask clarifying questions" -> "Propose 2-3 approaches";
+"Propose 2-3 approaches" -> "Present design sections";
+"Present design sections" -> "User approves design?";
+"User approves design?" -> "Present design sections" [label="no, revise"];
+"User approves design?" -> "Write design doc" [label="yes"];
+"Write design doc" -> "Spec self-review\n(fix inline)";
+"Spec self-review\n(fix inline)" -> "User reviews spec?";
+"User reviews spec?" -> "Write design doc" [label="changes requested"];
+"User reviews spec?" -> "Create implementation plan\n(plan tool submit)" [label="approved"];
+}
+```
+
+**The terminal state is an approved implementation plan.** Do NOT jump into code after the spec is approved. Use the built-in `plan` tool to write the implementation plan (with TDD steps and per-wave verification commands) and submit it with `plan action=submit` for user approval. Code only after the plan is approved.
+
+## The Process
+
+**Understanding the idea:**
+
+- Check out the current project state first (files, docs, recent commits)
+- Before asking detailed questions, assess scope: if the request describes multiple independent subsystems (e.g., "build a platform with chat, file storage, billing, and analytics"), flag this immediately. Don't spend questions refining details of a project that needs to be decomposed first.
+- If the project is too large for a single spec, help the user decompose into sub-projects: what are the independent pieces, how do they relate, what order should they be built? Then brainstorm the first sub-project through the normal design flow. Each sub-project gets its own spec → plan → implementation cycle.
+- For appropriately-scoped projects, ask questions one at a time to refine the idea
+- Prefer multiple choice questions when possible, but open-ended is fine too
+- Only one question per message - if a topic needs more exploration, break it into multiple questions
+- Focus on understanding: purpose, constraints, success criteria
+
+**Exploring approaches:**
+
+- Propose 2-3 different approaches with trade-offs
+- Present options conversationally with your recommendation and reasoning
+- Lead with your recommended option and explain why
+
+**Presenting the design:**
+
+- Once you believe you understand what you're building, present the design
+- Scale each section to its complexity: a few sentences if straightforward, up to 200-300 words if nuanced
+- Ask after each section whether it looks right so far
+- Cover: architecture, components, data flow, error handling, testing
+- Be ready to go back and clarify if something doesn't make sense
+
+**Design for isolation and clarity:**
+
+- Break the system into smaller units that each have one clear purpose, communicate through well-defined interfaces, and can be understood and tested independently
+- For each unit, you should be able to answer: what does it do, how do you use it, and what does it depend on?
+- Can someone understand what a unit does without reading its internals? Can you change the internals without breaking consumers? If not, the boundaries need work.
+- Smaller, well-bounded units are also easier for you to work with - you reason better about code you can hold in context at once, and your edits are more reliable when files are focused. When a file grows large, that's often a signal that it's doing too much.
+
+**Working in existing codebases:**
+
+- Explore the current structure before proposing changes. Follow existing patterns.
+- Where existing code has problems that affect the work (e.g., a file that's grown too large, unclear boundaries, tangled responsibilities), include targeted improvements as part of the design - the way a good developer improves code they're working in.
+- Don't propose unrelated refactoring. Stay focused on what serves the current goal.
+
+## After the Design
+
+**Documentation:**
+
+- Write the validated design (spec) to `docs/superpowers/specs/YYYY-MM-DD--design.md`
+- (User preferences for spec location override this default)
+- Use a style/concise-writing skill if one is available
+- Commit the design document to git
+
+**Spec Self-Review:**
+
+After writing the spec document, look at it with fresh eyes:
+
+1. **Placeholder scan:** Any "TBD", "TODO", incomplete sections, or vague requirements? Fix them.
+2. **Internal consistency:** Do any sections contradict each other? Does the architecture match the feature descriptions?
+3. **Scope check:** Is this focused enough for a single implementation plan, or does it need decomposition?
+4. **Ambiguity check:** Could any requirement be interpreted two different ways? If so, pick one and make it explicit.
+
+Fix any issues inline. No need to re-review — just fix and move on.
+
+**User Review Gate:**
+
+After the spec review loop passes, ask the user to review the written spec before proceeding:
+
+> "Spec written and committed to `<path>`. Please review it and let me know if you want to make any changes before we start writing out the implementation plan."
+
+Wait for the user's response. If they request changes, make them and re-run the spec review loop. Only proceed once the user approves.
+
+**Planning:**
+
+- Create the implementation plan with the built-in `plan` tool: `plan action=enter_mode` opens planning mode (writes are locked), write the plan document, then `plan action=submit` hands it to the user for approval. Include TDD steps and concrete verification commands per wave (this is the native successor of the retired writing-plans skill).
+- Do NOT skip this step and do NOT invoke any other skill here — an approved design without an approved plan is not ready to implement.
+
+## Key Principles
+
+- **One question at a time** - Don't overwhelm with multiple questions
+- **Multiple choice preferred** - Easier to answer than open-ended when possible
+- **YAGNI ruthlessly** - Remove unnecessary features from all designs
+- **Explore alternatives** - Always propose 2-3 approaches before settling
+- **Incremental validation** - Present design, get approval before moving on
+- **Be flexible** - Go back and clarify when something doesn't make sense

package/dist/bundled-skills/visual-acceptance/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: visual-acceptance
+description: "UI/视觉改动交付前的终验方法论——多主题截图矩阵复现、像素真值判据链、CSS 层叠陷阱、布局漂移审查、before/after 存证。当视觉改动需要验收（而非实现）时使用：交付前最后一环，回答「看得见的部分真的对吗」。"
+triggers: ['视觉验证|视觉回归|视觉终验|视觉验收|截图对比|截图存证|三主题|收灯验收|visual.?regression|visual.?acceptance|screenshot.?diff|pixel.?check']
+---
+
+# Visual Acceptance — 视觉终验方法论
+
+你在任意项目中对 UI/视觉改动做交付前的最后一道审视。你可能没写这些代码，项目的主题系统、构建管道你也未必熟——但你必须给出「看得见的部分是对的」这个结论，且结论要有证据形状：截图矩阵、像素值、before/after 对照，而不是「应该没问题」。
+
+> 分工界线：这是**验收**技能，不是实现技能。界面怎么做出来是实现者的事；
+> 这里管的是做出来之后，交付前有没有人真的看过、看的方法对不对、证据留没留。
+
+---
+
+## Stage 1: 复现术——不起整个 app 的截图矩阵
+
+完整跑起应用再人肉点到目标界面，慢且不可复跑。正确姿势是搭一个最小 harness：
+
+1. **用生产构建的编译 CSS，不用源码 CSS。** 找到构建产物里的样式文件（`dist/`、`build/`、`.next/` 等），复制进 harness。源码 CSS 验的是近似，编译产物才是产品——预处理器、压缩、autoprefixer 都可能改变最终层叠。
+2. **harness HTML 用真实类名复刻目标场景。** 从产品 DOM 里抄结构和 class，不要手写近似样式。before/after 同页并排——一张截图直接回答「改动好在哪」。
+3. **主题 token 注入。** 读项目的主题定义（CSS variables JSON / theme 文件），用 playwright 的 `page.evaluate`（或等价手段）把变量批量设到根元素上，与产品的 theme-loader 同语义。
+4. **多主题矩阵一个不能少。** 至少 light/dark 各截一张；若产品有半透明/玻璃/壁纸类主题，它是**可读性的极限测试**（半透明底 + 任意背景），必须在列。每主题 fullPage 截图。
+5. **动画冻结成静帧。** shimmer/pulse 类动画用 `animation-play-state: paused` 加负值 `animation-delay` 钉在特征帧上，静态截图才可检。
+6. **截图归档为交付资产。** 命名带日期与场景，放进项目的文档资产目录——它们是验收证据，不是临时文件。
+
+## Stage 2: 像素真值判据链
+
+目视会骗人，且两个方向都骗：真浅色的图能被显示管道渲成深色（读图工具伪影），真白的底能让人以为「没截到」（实为 CSS 层叠 bug）。判据链逐级下钻，**任何一级与上一级矛盾时，信下一级**：
+
+```
+目视 → PNG 像素值 → computed style → CSS 层叠来源
+```
+
+读像素（三点采样：角落/中部/目标区域）：
+
+```bash
+python3 -c "from PIL import Image; im=Image.open('shot.png').convert('RGB'); print(im.getpixel((10,10)), im.getpixel((640,400)), im.getpixel((640,780)))"
+```
+
+- 像素与目视矛盾 → 显示管道伪影，截图本身没问题，别为不存在的 bug 改代码。
+- 像素证实异常但 computed style 正确 → 问题在渲染层之下，查层叠来源与合成（Stage 3）。
+
+## Stage 3: CSS 层叠陷阱
+
+- **`!important` 只向 `!important` 低头。** 产品 CSS 里的 `!important` 规则会静默压掉 harness/宿主环境的普通规则；对抗它需要同 specificity 的 `!important` 且源序更靠后。debug 时单独设 class 一切正常、组合路径才踩中——层叠问题的典型形状。
+- **宿主底色假设要显式补齐。** 产品若假设「外壳提供背景」（透明窗体、iframe 宿主、系统壁纸垫底），harness 必须显式补一层底，否则截图里的白/黑是**环境缺失**，会被误判成产品缺陷（或掩盖真缺陷）。
+
+## Stage 4: 布局漂移审查
+
+typecheck 与单元测试都不报的布局问题，静态截图审查一眼现形。逐行扫截图里每个小元素的**归属感**——它看起来属于谁：
+
+- flex 容器里 `flex: 1` 的元素会把后续兄弟推到行尾。语义上「紧跟」主元素的小标识（序号、徽记、计数）必须**嵌进主元素内部**，不能做兄弟节点。
+- 同一 DOM 模式在不同 flex 上下文中行为不同——一处对不代表处处对，每个使用场景各截一张。
+
+## 收灯清单
+
+全部满足才算验收通过：
+
+- [ ] 多主题矩阵截齐，半透明主题下所有新元素可辨、可读
+- [ ] before/after 同页对照存在，能一图回答「好在哪」
+- [ ] 目视存疑处有像素值证据（不是「看着像对的」）
+- [ ] 截图归档进项目文档资产目录，命名可溯源
+- [ ] 布局归属感逐行扫过（没有被 flex 推走的孤儿元素）