prompt-contract 0.2.0

package/packages/cli/test/spike-0.test.js

@@ -0,0 +1,260 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  captureSelectedText,
+  validatePasteBackDryRun,
+  buildCompatibilityReport,
+  DEFAULT_SPIKE_THRESHOLDS,
+  isPlainTextClipboardInfo,
+  runSpike0,
+} from '../src/spike-0.js';
+
+function context(overrides = {}) {
+  return {
+    processName: 'Google Chrome',
+    bundleId: 'com.google.Chrome',
+    pid: 123,
+    windowTitle: 'Prompt test',
+    focus: {
+      role: 'AXTextField',
+      subrole: 'AXStandardWindow',
+      identifier: 'prompt-input',
+      title: '',
+      description: 'Prompt input',
+    },
+    ...overrides,
+  };
+}
+
+function fakeAdapter({
+  clipboard = 'keep this clipboard',
+  selectedText = 'selected prompt',
+  contexts = [context(), context(), context()],
+  copyError,
+  clipboardCheckError,
+} = {}) {
+  const state = { clipboard, events: [], contexts: [...contexts] };
+  return {
+    state,
+    async readClipboard() {
+      state.events.push('readClipboard');
+      return state.clipboard;
+    },
+    async checkClipboardRestorable() {
+      state.events.push('checkClipboardRestorable');
+      if (clipboardCheckError) throw clipboardCheckError;
+    },
+    async writeClipboard(value) {
+      state.events.push(['writeClipboard', value]);
+      state.clipboard = value;
+    },
+    async copySelection() {
+      state.events.push('copySelection');
+      if (copyError) throw copyError;
+      state.clipboard = selectedText;
+    },
+    async getFocusIdentity() {
+      state.events.push('getFocusIdentity');
+      return state.contexts.shift() || context();
+    },
+    async sleep() {
+      state.events.push('sleep');
+    },
+  };
+}
+
+test('captureSelectedText restores the original clipboard after a successful copy', async () => {
+  const adapter = fakeAdapter();
+
+  const result = await captureSelectedText(adapter, { settleMs: 0 });
+
+  assert.equal(result.selectedText, 'selected prompt');
+  assert.equal(result.selectedTextLength, 15);
+  assert.equal(result.clipboardRestored, true);
+  assert.equal(result.userTextMutated, false);
+  assert.equal(adapter.state.clipboard, 'keep this clipboard');
+  assert.deepEqual(adapter.state.events, [
+    'readClipboard',
+    'checkClipboardRestorable',
+    'getFocusIdentity',
+    'copySelection',
+    'sleep',
+    'readClipboard',
+    'getFocusIdentity',
+    ['writeClipboard', 'keep this clipboard'],
+    'readClipboard',
+  ]);
+});
+
+test('captureSelectedText restores the clipboard when copy fails', async () => {
+  const adapter = fakeAdapter({ copyError: new Error('Accessibility denied') });
+
+  const result = await captureSelectedText(adapter, { settleMs: 0 });
+
+  assert.equal(result.selectedText, null);
+  assert.equal(result.clipboardRestored, true);
+  assert.equal(result.userTextMutated, false);
+  assert.match(result.error, /Accessibility denied/);
+  assert.equal(adapter.state.clipboard, 'keep this clipboard');
+  assert.equal(adapter.state.events.some((event) => Array.isArray(event) && event[0] === 'writeClipboard'), true);
+});
+
+test('captureSelectedText refuses an unsupported clipboard without rewriting it', async () => {
+  const adapter = fakeAdapter({ clipboardCheckError: new Error('clipboard_not_plain_text') });
+
+  const result = await captureSelectedText(adapter, { settleMs: 0 });
+
+  assert.equal(result.selectedText, null);
+  assert.match(result.error, /clipboard_not_plain_text/);
+  assert.equal(result.clipboardRestored, false);
+  assert.equal(result.clipboardUntouched, true);
+  assert.equal(adapter.state.clipboard, 'keep this clipboard');
+  assert.equal(adapter.state.events.includes('copySelection'), false);
+  assert.equal(adapter.state.events.some((event) => Array.isArray(event) && event[0] === 'writeClipboard'), false);
+});
+
+test('isPlainTextClipboardInfo accepts text-only pasteboards and rejects rich types', () => {
+  assert.equal(
+    isPlainTextClipboardInfo('«class utf8», 0, «class ut16», 2, string, 0, Unicode text, 0'),
+    true,
+  );
+  assert.equal(
+    isPlainTextClipboardInfo('«class utf8», 4, «class HTML», 128'),
+    false,
+  );
+});
+
+test('runSpike0 supports a setup delay before each target without changing capture semantics', async () => {
+  const adapter = fakeAdapter();
+  const announcements = [];
+
+  await runSpike0({
+    adapter,
+    targets: ['Chrome'],
+    iterations: 1,
+    setupDelayMs: 25,
+    interactive: false,
+    announce: (message) => announcements.push(message),
+    now: () => new Date('2026-09-07T00:00:00.000Z'),
+  });
+
+  assert.deepEqual(announcements, ['Focus Chrome and select text now; capture starts after the setup delay.']);
+  assert.equal(adapter.state.events[0], 'sleep');
+  assert.equal(adapter.state.events.includes('copySelection'), true);
+});
+
+test('validatePasteBackDryRun checks focus stability without issuing paste', async () => {
+  const adapter = fakeAdapter();
+  const before = context();
+
+  const result = await validatePasteBackDryRun(adapter, {
+    capturedContext: before,
+    selectedText: 'selected prompt',
+    pauseMs: 0,
+  });
+
+  assert.equal(result.mode, 'dry-run');
+  assert.equal(result.executed, false);
+  assert.equal(result.wouldPasteBack, true);
+  assert.equal(result.userTextMutated, false);
+  assert.equal(adapter.state.events.includes('pasteSelection'), false);
+});
+
+test('validatePasteBackDryRun rejects focus drift without changing user text', async () => {
+  const adapter = fakeAdapter({ contexts: [context({ pid: 456, windowTitle: 'Other app' })] });
+
+  const result = await validatePasteBackDryRun(adapter, {
+    capturedContext: context(),
+    selectedText: 'selected prompt',
+    pauseMs: 0,
+  });
+
+  assert.equal(result.wouldPasteBack, false);
+  assert.equal(result.reason, 'focus_drift');
+  assert.equal(result.executed, false);
+  assert.equal(result.userTextMutated, false);
+});
+
+test('validatePasteBackDryRun tolerates a transiently unavailable window title', async () => {
+  const adapter = fakeAdapter({ contexts: [context({ windowTitle: '' })] });
+
+  const result = await validatePasteBackDryRun(adapter, {
+    capturedContext: context(),
+    selectedText: 'selected prompt',
+    pauseMs: 0,
+  });
+
+  assert.equal(result.wouldPasteBack, true);
+  assert.equal(result.focusStable, true);
+  assert.equal(result.executed, false);
+});
+
+test('buildCompatibilityReport applies the Spike-0 cohort thresholds', () => {
+  const runs = [];
+  for (const target of ['Chrome', 'PyCharm', 'iTerm']) {
+    for (let iteration = 1; iteration <= 20; iteration++) {
+      runs.push({
+        target,
+        iteration,
+        capture: {
+          selectedTextCaptured: true,
+          clipboardRestored: true,
+          clipboardRestoreVerified: true,
+          focusRecorded: true,
+        },
+        pasteBack: { mode: 'dry-run', wouldPasteBack: true, contextAtValidation: {} },
+        safety: { userTextMutated: false, pasteCommandSent: false },
+      });
+    }
+  }
+
+  const report = buildCompatibilityReport({
+    runs,
+    targets: ['Chrome', 'PyCharm', 'iTerm'],
+    thresholds: DEFAULT_SPIKE_THRESHOLDS,
+    platformInfo: { os: 'darwin', arch: 'arm64' },
+    startedAt: '2026-09-07T00:00:00.000Z',
+    finishedAt: '2026-09-07T00:00:01.000Z',
+  });
+
+  assert.equal(report.schemaVersion, 'prompt-contract/spike-0.v1');
+  assert.equal(report.mode, 'dry-run');
+  assert.equal(report.summary.captureSuccessRate, 1);
+  assert.equal(report.summary.clipboardRestoreSuccessRate, 1);
+  assert.equal(report.decision.pass, true);
+  assert.equal(report.decision.watchGate, 'closed');
+});
+
+test('buildCompatibilityReport fails below the combined capture threshold', () => {
+  const runs = [];
+  for (const target of ['Chrome', 'PyCharm', 'iTerm']) {
+    for (let iteration = 1; iteration <= 20; iteration++) {
+      const failed = target === 'iTerm' && iteration <= 7;
+      runs.push({
+        target,
+        iteration,
+        capture: {
+          selectedTextCaptured: !failed,
+          clipboardRestored: true,
+          clipboardRestoreVerified: true,
+          focusRecorded: true,
+        },
+        pasteBack: { mode: 'dry-run', wouldPasteBack: !failed, contextAtValidation: {} },
+        safety: { userTextMutated: false, pasteCommandSent: false },
+      });
+    }
+  }
+
+  const report = buildCompatibilityReport({
+    runs,
+    targets: ['Chrome', 'PyCharm', 'iTerm'],
+    thresholds: DEFAULT_SPIKE_THRESHOLDS,
+    platformInfo: { os: 'darwin', arch: 'arm64' },
+    startedAt: '2026-09-07T00:00:00.000Z',
+    finishedAt: '2026-09-07T00:00:01.000Z',
+  });
+
+  assert.equal(report.summary.captureSuccessRate, 0.8833);
+  assert.equal(report.decision.pass, false);
+  assert.match(report.decision.reasons.join(' '), /dry-run paste-back/);
+});

package/packages/core/bench/bench.js

@@ -0,0 +1,48 @@
+/**
+ * Engine overhead benchmark — the part of the latency budget we own (PRD §5.3/§7.6).
+ * The model TTFT is external and dominates end-to-end latency; this proves the engine adds
+ * effectively nothing on top (budget: P50 < 5ms, in practice microseconds).
+ */
+import { assembleMessages } from '../src/pipeline.js';
+import { postprocess } from '../src/clean.js';
+import { checkRules } from '../src/rules.js';
+
+const PROFILE = { name: 'coding-agent', maxChars: 800, body: 'You rewrite vague requests for a coding assistant. '.repeat(4) };
+const INPUTS = [
+  '帮我做一个展示我家狗的网站',
+  'A website for my dog',
+  'explain this code',
+  '把这份周报改正式一点',
+  '一只在雪地里的柴犬'
+];
+const OUTPUT = '做一个展示宠物的小型网站：包含照片画廊、简介页与动态页，导航保持单层，暂不需要评论功能。';
+
+const N = 20000;
+const times = [];
+// warmup
+for (let i = 0; i < 500; i++) {
+  const { system, user } = assembleMessages(INPUTS[i % INPUTS.length], { profile: PROFILE, strength: 'standard' });
+  postprocess(system + user, 800);
+}
+for (let i = 0; i < N; i++) {
+  const t0 = performance.now();
+  const { system, user } = assembleMessages(INPUTS[i % INPUTS.length], { profile: PROFILE, strength: 'standard' });
+  const cleaned = postprocess(`“${OUTPUT}”`, 800);
+  checkRules(INPUTS[i % INPUTS.length], cleaned, { maxChars: 800 });
+  if (system.length === 0 || user.length === 0) throw new Error('assembly broke');
+  times.push(performance.now() - t0);
+}
+times.sort((a, b) => a - b);
+const p50 = times[Math.floor(N * 0.5)];
+const p95 = times[Math.floor(N * 0.95)];
+const mean = times.reduce((a, b) => a + b, 0) / N;
+
+console.log(`engine overhead per enhancement (assemble + clean + rules), n=${N}`);
+console.log(`  P50: ${p50.toFixed(3)}ms`);
+console.log(`  P95: ${p95.toFixed(3)}ms`);
+console.log(`  mean: ${mean.toFixed(3)}ms`);
+if (p50 >= 5) {
+  console.error('BUDGET VIOLATION: P50 must stay under 5ms');
+  process.exit(1);
+}
+console.log('budget check: PASS (P50 < 5ms)');

package/packages/core/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@prompt-contract/core",
+  "version": "0.1.0",
+  "description": "PromptContract engine — profile assembly, single-shot LLM call contract, deterministic cleaning and rule assertions. Zero runtime dependencies, browser-safe.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "exports": {
+    ".": "./src/index.js",
+    "./node": "./src/node.js"
+  }
+}

package/packages/core/src/clean.js

@@ -0,0 +1,58 @@
+/**
+ * Deterministic post-processing of LLM output — the layer WorkBuddy calls "清洗" (PRD §1.2).
+ * No LLM output reaches a user surface without passing through here.
+ */
+
+const QUOTE_PAIRS = [
+  ['"', '"'], ["'", "'"],
+  ['\u201c', '\u201d'], // “ ”
+  ['\u2018', '\u2019'], // ‘ ’
+  ['\u00ab', '\u00bb'], // « »
+  ['\u300c', '\u300d']  // 「 」
+];
+
+/** Remove wrapping quote pairs, repeatedly (WorkBuddy stripWrappingQuotes, generalized). */
+export function stripWrappingQuotes(t) {
+  let prev;
+  do {
+    prev = t;
+    t = t.trim();
+    for (const [open, close] of QUOTE_PAIRS) {
+      if (t.length >= 2 && t.startsWith(open) && t.endsWith(close)) {
+        t = t.slice(1, -1).trim();
+        break;
+      }
+    }
+  } while (t !== prev);
+  return t;
+}
+
+/** Strip markdown code fences (hard constraint #2: no fences in output). */
+export function stripFences(t) {
+  const fenced = t.match(/^\s*```[\w+-]*\s*\r?\n([\s\S]*?)\r?\n?```\s*$/);
+  if (fenced) return fenced[1];
+  return t.replace(/^\s*```[\w+-]*\s*\r?\n?/, '').replace(/\r?\n?```\s*$/, '');
+}
+
+/**
+ * Clamp to maxChars at a sentence boundary; never leave a dangling list marker or trailing colon
+ * (hard constraint #3). Counts code points, not UTF-16 units.
+ */
+export function clampChars(t, maxChars) {
+  const chars = [...t];
+  if (chars.length <= maxChars) return t;
+  const cut = chars.slice(0, maxChars).join('');
+  const sentence = cut.match(/[\s\S]*[.!?。！？；;\n]/);
+  let out = (sentence ? sentence[0] : cut).replace(/([-*+]+|[:：])\s*$/, '').trimEnd();
+  if (!out) out = cut.trimEnd();
+  return out;
+}
+
+export function postprocess(raw, maxChars) {
+  let t = String(raw ?? '');
+  t = stripFences(t);
+  t = stripWrappingQuotes(t);
+  t = t.trim();
+  if (!t) return null; // caller maps to llm_error (WorkBuddy: empty result → llm_error)
+  return clampChars(t, maxChars);
+}

package/packages/core/src/errors.js

@@ -0,0 +1,26 @@
+/** Structured error codes — stable public contract across all shells (CLI/MCP/playground). PRD §1.2/§5.2. */
+export const CODES = {
+  EMPTY_INPUT: 'empty_input',
+  PROVIDER_UNAVAILABLE: 'provider_unavailable',
+  LLM_ERROR: 'llm_error',
+  ABORTED: 'aborted',
+  CONFIG: 'config_error',
+  PROFILE_NOT_FOUND: 'profile_not_found'
+};
+
+export class PromptContractError extends Error {
+  constructor(code, message, { cause } = {}) {
+    super(message || code, { cause });
+    this.name = 'PromptContractError';
+    this.code = code;
+  }
+}
+
+/** Normalize any thrown value into a PromptContractError with a stable code (ADR-017 semantics: abort is fast, result is dropped). */
+export function normalizeError(err) {
+  if (err instanceof PromptContractError) return err;
+  if (err && (err.name === 'AbortError' || err.name === 'TimeoutError' || err.code === 'ABORT_ERR')) {
+    return new PromptContractError(CODES.ABORTED, 'aborted by caller', { cause: err });
+  }
+  return new PromptContractError(CODES.PROVIDER_UNAVAILABLE, err?.message || 'unexpected error', { cause: err });
+}

package/packages/core/src/index.js

@@ -0,0 +1,10 @@
+/**
+ * Browser-safe public API of the engine. Node-only extras (fs profile loading, config resolution)
+ * live in ./node.js so this file can be imported directly by the playground.
+ */
+export { CODES, PromptContractError, normalizeError } from './errors.js';
+export { detectScriptName } from './lang.js';
+export { stripWrappingQuotes, stripFences, clampChars, postprocess } from './clean.js';
+export { checkRules } from './rules.js';
+export { parseProfile, parseYamlLite } from './profile.js';
+export { enhance, assembleMessages, hardConstraints, STRENGTHS } from './pipeline.js';

package/packages/core/src/lang.js

@@ -0,0 +1,37 @@
+/**
+ * Script-level language detection (heuristic, zero-cost — PRD §5.2: no extra LLM call).
+ * Used for meta info and the `lang-consistency` rule assertion, not for prompt injection.
+ */
+
+const SCRIPT_TESTS = [
+  ['kana', /[\u3040-\u309f\u30a0-\u30ff]/],
+  ['hangul', /[\uac00-\ud7af\u1100-\u11ff]/],
+  ['han', /[\u4e00-\u9fff\u3400-\u4dbf\uf900-\ufaff]/],
+  ['cyrillic', /[\u0400-\u04ff]/],
+  ['arabic', /[\u0600-\u06ff]/],
+  ['devanagari', /[\u0900-\u097f]/],
+  ['thai', /[\u0e00-\u0e7f]/],
+  ['hebrew', /[\u0590-\u05ff]/],
+  ['greek', /[\u0370-\u03ff]/]
+];
+
+/**
+ * Return the dominant script name of `text`.
+ * Kana beats han on purpose: Japanese text mixes both, so any kana presence means Japanese;
+ * Chinese input has no kana, which makes zh↔ja confusion detectable by the lang-consistency rule.
+ */
+export function detectScriptName(text) {
+  if (!text) return 'latin';
+  const counts = { kana: 0, hangul: 0, han: 0, cyrillic: 0, arabic: 0, devanagari: 0, thai: 0, hebrew: 0, greek: 0 };
+  for (const ch of text) {
+    for (const [name, re] of SCRIPT_TESTS) {
+      if (re.test(ch)) { counts[name]++; break; }
+    }
+  }
+  if (counts.kana > 0) return 'japanese';
+  let best = null, bestN = 0;
+  for (const [name] of SCRIPT_TESTS) {
+    if (counts[name] > bestN) { best = name; bestN = counts[name]; }
+  }
+  return best || 'latin';
+}

package/packages/core/src/node.js

@@ -0,0 +1,83 @@
+/**
+ * Node-only helpers: profile directory loading and provider/config resolution.
+ * Keeps src/index.js browser-safe for the playground (PRD §5.4: BYOK, key never leaves the machine).
+ */
+import { readdirSync, readFileSync, existsSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+import { parseProfile } from './profile.js';
+import { PromptContractError, CODES } from './errors.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/** Locate the built-in profiles/ directory (repo root) from wherever the caller lives. */
+export function resolveProfilesDir(explicit) {
+  const candidates = [];
+  if (explicit) candidates.push(resolve(explicit));
+  for (const start of [process.cwd(), __dirname]) {
+    let dir = start;
+    for (let i = 0; i < 6; i++) {
+      candidates.push(join(dir, 'profiles'));
+      const parent = dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+  }
+  for (const c of candidates) {
+    try {
+      if (statSync(c).isDirectory()) return c;
+    } catch { /* keep probing */ }
+  }
+  return null;
+}
+
+export function loadProfiles(explicitDir) {
+  const dir = resolveProfilesDir(explicitDir);
+  if (!dir) throw new PromptContractError(CODES.CONFIG, 'profiles directory not found (looked from cwd and package upward)');
+  const profiles = [];
+  for (const f of readdirSync(dir).sort()) {
+    if (!f.endsWith('.md')) continue;
+    profiles.push(parseProfile(readFileSync(join(dir, f), 'utf8'), { path: join(dir, f) }));
+  }
+  if (profiles.length === 0) throw new PromptContractError(CODES.CONFIG, `no .md profiles found in ${dir}`);
+  return profiles;
+}
+
+export function loadProfile(name, explicitDir) {
+  const profiles = loadProfiles(explicitDir);
+  const found = profiles.find((p) => p.name === name);
+  if (!found) {
+    throw new PromptContractError(CODES.PROFILE_NOT_FOUND, `unknown profile "${name}" (available: ${profiles.map((p) => p.name).join(', ')})`);
+  }
+  return found;
+}
+
+/**
+ * Config resolution order: explicit flags > env (PB_*) > config file (CONTRACT_CONFIG or ~/.prompt-contract/config.json).
+ * Defaults follow PRD §3.2: local Ollama if nothing else is configured (privacy-first).
+ * `flags.configPath` / `CONTRACT_CONFIG` exist so tests and embedded shells can isolate the file source.
+ */
+export function resolveConfig(flags = {}) {
+  const cfgPath = flags.configPath ?? process.env.CONTRACT_CONFIG ?? join(homedir(), '.prompt-contract', 'config.json');
+  let file = {};
+  try {
+    if (existsSync(cfgPath)) file = JSON.parse(readFileSync(cfgPath, 'utf8'));
+  } catch (err) {
+    throw new PromptContractError(CODES.CONFIG, `invalid config at ${cfgPath}: ${err.message}`);
+  }
+  const pick = (...sources) => { for (const s of sources) if (s !== undefined && s !== null && s !== '') return s; return undefined; };
+
+  const provider = pick(flags.provider, process.env.CONTRACT_PROVIDER, file.provider, guessProvider(flags.baseUrl ?? process.env.CONTRACT_BASE_URL ?? file.baseUrl), 'openai');
+  const baseUrl = String(pick(flags.baseUrl, process.env.CONTRACT_BASE_URL, file.baseUrl, provider === 'ollama' ? 'http://localhost:11434' : 'https://api.openai.com/v1')).replace(/\/+$/, '');
+  const apiKey = pick(flags.apiKey, process.env.CONTRACT_API_KEY, file.apiKey, provider === 'ollama' ? 'ollama' : undefined);
+  const model = pick(flags.model, process.env.CONTRACT_MODEL, file.model, provider === 'ollama' ? 'qwen3:4b' : 'gpt-4o-mini');
+  if (!apiKey) throw new PromptContractError(CODES.CONFIG, `no API key: set CONTRACT_API_KEY, --api-key, or ~/.prompt-contract/config.json (or use --provider ollama)`);
+  return { provider, baseUrl, apiKey, model };
+}
+
+function guessProvider(baseUrl) {
+  if (baseUrl && /:11434/.test(baseUrl)) return 'ollama';
+  return undefined;
+}

package/packages/core/src/pipeline.js

@@ -0,0 +1,84 @@
+/**
+ * Core pipeline: assemble (profile + hard constraints + strength + context) → single LLM call
+ * → deterministic postprocess. No middleware, no queues, no cache (PRD §7.6 / decision D8).
+ */
+import { PromptContractError, CODES, normalizeError } from './errors.js';
+import { detectScriptName } from './lang.js';
+import { postprocess } from './clean.js';
+
+export const STRENGTHS = {
+  polish: 'POLISH: The input is already adequate. Fix only wording, grammar, and clarity. Preserve its structure and length. Do not add new content.',
+  standard: 'STANDARD: Make a substantive enhancement — clarify the task, its scope, constraints, and the expected output, while preserving the original intent.',
+  expand: 'EXPAND: Turn the input into a structured task specification — goal, scope, explicit constraints, acceptance criteria, and edge cases. Stay realistic; do not invent features.'
+};
+
+/** Hard constraints appended to every request — mirror of eval/rules.js (PRD appendix: 共用同一份规格). */
+export function hardConstraints({ maxChars, strength }) {
+  return [
+    'HARD CONSTRAINTS:',
+    '1. LANGUAGE: Respond strictly in the same language as USER INPUT. Never output language labels or meta commentary about the language.',
+    '2. OUTPUT ONLY THE ENHANCED PROMPT TEXT — no explanations, no preface, no markdown fences, no quotes around the whole text.',
+    `3. Keep it under ${maxChars} characters, complete and concise; never end with a dangling list item or a trailing colon.`,
+    '4. EXPAND, DO NOT ANSWER: never answer the request, never ask the user questions, never request code snippets; focus on WHAT is wanted, not HOW.',
+    '5. If the input is already clear and specific, only lightly polish it.',
+    '6. Do not invent facts and do not add requirements, features, or technologies the input does not mention.'
+  ].join('\n');
+}
+
+/** Assemble the two-message request. Exported for tests and the MCP zero-key prompt mode. */
+export function assembleMessages(text, { profile, strength = 'standard', context, maxChars } = {}) {
+  const chars = maxChars ?? profile?.maxChars ?? 800;
+  const strengthName = STRENGTHS[strength] ? strength : 'standard';
+  const parts = [];
+  if (profile?.body) parts.push(profile.body.trim());
+  parts.push(hardConstraints({ maxChars: chars, strength }));
+  parts.push(`STRENGTH MODE: ${STRENGTHS[strengthName]}`);
+  const system = parts.join('\n\n');
+
+  let user = `USER INPUT:\n${text}`;
+  if (context && String(context).trim()) user += `\n\nCONTEXT (background information, do not enhance this part):\n${String(context).trim()}`;
+  return { system, user, strength: strengthName, maxChars: chars };
+}
+
+/**
+ * @param {string} text raw user prompt
+ * @param {object} opts { profile, provider, model, strength, context, maxChars, signal, timeoutMs, onDelta }
+ * @returns {Promise<{text, original, meta}>}
+ */
+export async function enhance(text, opts = {}) {
+  if (!text || !String(text).trim()) throw new PromptContractError(CODES.EMPTY_INPUT, 'empty input');
+  if (!opts.provider || typeof opts.provider.complete !== 'function') {
+    throw new PromptContractError(CODES.CONFIG, 'no provider configured');
+  }
+  const { system, user, strength, maxChars } = assembleMessages(text, opts);
+  const started = performance.now();
+  let raw;
+  try {
+    const res = await opts.provider.complete({
+      system,
+      user,
+      model: opts.model,
+      signal: opts.signal,
+      onDelta: opts.onDelta,
+      maxTokens: Math.ceil(maxChars * 1.2), // CJK ≈ 1 token/char worst case
+      timeoutMs: opts.timeoutMs ?? 30000
+    });
+    raw = res?.text ?? '';
+  } catch (err) {
+    throw normalizeError(err);
+  }
+  const cleaned = postprocess(raw, maxChars);
+  if (cleaned === null) throw new PromptContractError(CODES.LLM_ERROR, 'provider returned an empty result');
+  return {
+    text: cleaned,
+    original: text,
+    meta: {
+      profile: opts.profile?.name ?? null,
+      strength,
+      model: opts.model ?? null,
+      script: detectScriptName(cleaned),
+      chars: [...cleaned].length,
+      ms: Math.round(performance.now() - started)
+    }
+  };
+}

package/packages/core/src/profile.js

@@ -0,0 +1,50 @@
+/**
+ * Profile format: Markdown + minimal frontmatter — community-contribution surface (PRD §3.2: "PR 即贡献").
+ * YAML subset only: `key: value` scalars (string/number/bool) and `key:` + indented `- item` lists.
+ */
+import { PromptContractError, CODES } from './errors.js';
+
+export function parseYamlLite(src) {
+  const out = {};
+  let currentListKey = null;
+  for (const rawLine of src.split(/\r?\n/)) {
+    if (!rawLine.trim() || rawLine.trim().startsWith('#')) continue;
+    const listItem = rawLine.match(/^\s+-\s+(.*)$/);
+    if (listItem) {
+      if (!currentListKey) throw new PromptContractError(CODES.CONFIG, `list item without a parent key: "${rawLine.trim()}"`);
+      out[currentListKey].push(coerce(listItem[1].trim()));
+      continue;
+    }
+    const kv = rawLine.match(/^([A-Za-z_][\w-]*):\s*(.*)$/);
+    if (!kv) throw new PromptContractError(CODES.CONFIG, `unparsable frontmatter line: "${rawLine.trim()}"`);
+    const [, key, value] = kv;
+    currentListKey = null;
+    if (value === '') { out[key] = []; currentListKey = key; } else { out[key] = coerce(value.trim()); }
+  }
+  return out;
+}
+
+function coerce(v) {
+  if (/^(true|false)$/.test(v)) return v === 'true';
+  if (/^-?\d+$/.test(v)) return parseInt(v, 10);
+  if (/^-?\d+\.\d+$/.test(v)) return parseFloat(v, 10);
+  if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) return v.slice(1, -1);
+  return v;
+}
+
+export function parseProfile(markdown, { path } = {}) {
+  const m = String(markdown).match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (!m) throw new PromptContractError(CODES.CONFIG, `profile${path ? ` ${path}` : ''}: missing frontmatter block`);
+  const meta = parseYamlLite(m[1]);
+  if (!meta.name || typeof meta.name !== 'string') {
+    throw new PromptContractError(CODES.CONFIG, `profile${path ? ` ${path}` : ''}: frontmatter must declare a string "name"`);
+  }
+  return {
+    name: meta.name,
+    domain: typeof meta.domain === 'string' ? meta.domain : '',
+    maxChars: Number.isFinite(meta.maxChars) && meta.maxChars > 0 ? meta.maxChars : 800,
+    noUnmentionedTech: meta.noUnmentionedTech !== false,
+    body: m[2].trim(),
+    path
+  };
+}