docs: redesign V2 user documentation and interactive examples

Author: rockyshi1993

README.md

@@ -13,6 +13,8 @@
 | 独立MCP服务 | intent-runtime-mcp --config <绝对路径.mjs> |
 | 已有MCP tools | /mcp的createIntentMcpAdapter，SDK继续管理传输与原路由 |
 
+先按你的任务选入口，无需先了解 host/executor。Node.js 与 executor MCP 使用你配置的模型；Codex host 复用当前模型。远程 HTTP 由你的已有 MCP 服务承载 Adapter，独立命令提供 stdio。
+
 要求Node.js≥20.0.0、ESM、schema-dsl@3.0.4。本文对应V2；截至2026-10-15，npm latest为1.0.2，V2尚未发行。先按[安装与版本](https://devcodex-labs.github.io/intent-runtime/guide/installation.html)构建并安装V2的tgz。结果/baseline的schemaVersion为2.0-draft.6，与npm版本不同。
 
 ## 在应用中调用
@@ -74,6 +76,8 @@ intent-runtime clean --host codex
 
 基础无Schema示例见[快速开始](https://devcodex-labs.github.io/intent-runtime/guide/quick-start.html)，读取目标、约束与字段见[结果指南](https://devcodex-labs.github.io/intent-runtime/guide/results.html)。
 
+响应中的正向要求在 constraints，交付物在 expectedOutput；没有独立 requirements 副本。根级 complete 仍可能伴随无效字段，使用参数前检查对应 fieldResults 与 issues。固定的完整输入、Schema、多轮材料和结果可在[响应场景目录](https://devcodex-labs.github.io/intent-runtime/api/response.html#完整场景与多轮材料)下载。
+
 ## 使用文档
 
 - [快速开始](https://devcodex-labs.github.io/intent-runtime/guide/quick-start.html)与[配置参考](https://devcodex-labs.github.io/intent-runtime/guide/configuration.html)

examples/README.md

@@ -5,6 +5,7 @@
 | 文件 | 用途 | 前置条件 |
 |---|---|---|
 | api/basic.mjs | 无Schema的基础目标与约束识别 | 项目安装运行库，环境INTENT_API_KEY/INTENT_MODEL |
+| api/native-response.mjs | 默认完整 Native 响应，与响应参考使用同一调用 | 项目安装运行库，环境INTENT_API_KEY/INTENT_MODEL |
 | api/multi-turn.mjs | 完整VIP Schema与三轮失效/修正 | 项目安装运行库，环境INTENT_API_KEY/INTENT_MODEL |
 | api/parse.mjs | API识别与所属字段消费 | 项目安装运行库/schema-dsl，环境INTENT_API_KEY/INTENT_MODEL |
 | custom-executor.ts | 自有模型网关适配 | ESM TypeScript项目，网关符合示例请求/回复协议 |

examples/api/native-response.mjs

@@ -0,0 +1,18 @@
+import {Intent, IntentError} from '@devcodex/intent-runtime';
+import {createApiExecutor} from '@devcodex/intent-runtime/adapters/api';
+
+const apiKey = process.env.INTENT_API_KEY, model = process.env.INTENT_MODEL;
+if (!apiKey || !model) throw new Error('Set INTENT_API_KEY and INTENT_MODEL in your environment.');
+const intent = new Intent({
+  language: 'zh-CN',
+  executor: createApiExecutor({provider: 'openai', apiKey, model}),
+  schema: {type: 'object', properties: {orderId: {type: 'string', pattern: '^[0-9]+$'}}},
+});
+try {
+  const result = await intent.parse({input: '查询订单000123，不要取消订单', fields: ['orderId']});
+  console.log(JSON.stringify(result, null, 2));
+} catch (error) {
+  if (!(error instanceof IntentError)) throw error;
+  console.error(JSON.stringify(error.toJSON()));
+  process.exitCode = 1;
+} finally {await intent.dispose();}

scripts/check-doc-examples.mjs

@@ -3,11 +3,16 @@ import {cp, mkdir, mkdtemp, readFile, readdir, writeFile} from 'node:fs/promises
 import path from 'node:path';
 import {spawnSync} from 'node:child_process';
 import {fileURLToPath, pathToFileURL} from 'node:url';
+import {checkResultLinks} from './documentation/result-check.mjs';
 
 const repo = fileURLToPath(new URL('../', import.meta.url));
 const [consumer, tarball] = process.argv.slice(2);
 if (!consumer || !path.isAbsolute(consumer) || consumer.startsWith(repo)) throw new Error('Provide an external installed consumer directory.');
 const work = await mkdtemp(path.join(consumer, 'documentation-'));
+// Generated fixtures must still be reproducible through the installed core.
+// A shape-only check cannot establish field ownership or withdrawal identity.
+const generated = spawnSync(process.execPath, [path.join(repo, 'scripts/generate-doc-scenarios.mjs'), consumer], {encoding: 'utf8'});
+if (generated.status !== 0) throw new Error(generated.stdout + generated.stderr);
 const examples = path.join(work, 'examples');
 await cp(path.join(repo, 'examples'), examples, {recursive: true});
 function run(command, args, overrides = {}) {
@@ -25,11 +30,6 @@ const {StdioClientTransport} = await import(pathToFileURL(path.join(consumer, 'n
 const {INTENT_RESULT_SCHEMA} = await import(pathToFileURL(path.join(consumer, 'node_modules/@devcodex/intent-runtime/dist/index.js')).href);
 const {Validator} = await import(pathToFileURL(path.join(consumer, 'node_modules/schema-dsl/dist/pure.cjs')).href);
 const validator = new Validator({logger: false, strict: false, useDefaults: false, coerceTypes: false, removeAdditional: false, allErrors: true});
-function pointer(root, text) {
-  assert(text === '' || text.startsWith('/'));
-  assert(!/~(?![01])/u.test(text));
-  return text === '' ? root : text.slice(1).split('/').map(s => s.replace(/~1/g, '/').replace(/~0/g, '~')).reduce((value, key) => {assert(value !== null && typeof value === 'object' && Object.hasOwn(value, key), text); return value[key];}, root);
-}
 let resultExamples = 0;
 for (const stem of ['order', 'clarification']) {
   const input = JSON.parse(await readFile(path.join(repo, 'website/content/public/examples/' + stem + '-request.json'), 'utf8'));
@@ -41,24 +41,7 @@ for (const stem of ['order', 'clarification']) {
   const instanceConfig = input.config.instances[input.request.instance ?? names[0]];
   assert(instanceConfig);
   const materials = {...instanceConfig, ...input.request};
-  function sources(value) {
-    if (!value || typeof value !== 'object') return;
-    if ('root' in value && 'pointer' in value) {
-      assert(Object.hasOwn(materials, value.root));
-      const source = pointer(materials[value.root], value.pointer);
-      if (value.quote !== undefined) assert((typeof source === 'string' ? source : JSON.stringify(source)).includes(value.quote));
-    }
-    for (const child of Object.values(value)) sources(child);
-  }
-  sources(result);
-  const ids = new Set();
-  function add(value) {assert(!ids.has(value.id)); ids.add(value.id);}
-  function intents(nodes) {for (const node of nodes) {add(node); node.constraints.forEach(add); const local = new Set(); for (const ref of node.references) {assert(!local.has(ref.id)); local.add(ref.id);} intents(node.children);}}
-  intents(result.effective.intents);
-  result.effective.constraints.forEach(add); result.effective.relations.forEach(add); result.issues.forEach(add);
-  for (const change of result.turn.changes) {if (change.target.kind !== 'unresolved') assert(ids.has(change.target.id)); if (change.conditionId) assert(ids.has(change.conditionId));}
-  for (const id of result.turn.intentIds) assert(ids.has(id));
-  for (const entry of result.evidence ?? []) pointer(result, entry.target);
+  checkResultLinks(result, materials);
   resultExamples++;
 }
 validator.clearCache();
@@ -139,7 +122,7 @@ globalThis.fetch=async function(url,options){
  Object.assign(c.nodes[0],{domain:'订单',action:'查询',target:'订单000123',goal:'查询订单000123'});
  c.observations=[];
  const observation=(field,value)=>({ownerKey:'order',container:'inputs',field,presence:'known',withdrawn:false,valueJson:JSON.stringify(value),rawText:null,sources:[src],semantic:null});
- if(request.input.includes('不取消订单')){
+ if(/不(?:要)?取消订单/.test(request.input)){
   c.constraints=[{key:'no-cancel',priorRef:null,ownerKey:'order',scope:'intent',referenceKey:null,kind:'prohibition',text:'不取消订单',expressionJson:null,sources:[src]}];
   c.changes.push({operation:'add',effect:'applied',targetKind:'constraint',targetKey:'no-cancel',conditionKey:null,description:'保留禁止取消约束',sources:[src],deltaHints:[]});
  }
@@ -159,13 +142,13 @@ globalThis.fetch=async function(url,options){
 };
 `);
 const runnableExamples = [];
-for (const name of ['basic', 'parse', 'multi-turn']) {
+for (const name of ['basic', 'parse', 'multi-turn', 'native-response']) {
   const trace = path.join(work, name + '-results.json');
   const env = {INTENT_API_KEY: 'controlled-test-only', INTENT_MODEL: 'controlled-language-reply', INTENT_DOC_TRACE: trace, INTENT_DOC_FAILURE: ''};
   run(process.execPath, ['--import', pathToFileURL(preload).href, path.join(examples, 'api', name + '.mjs')], env);
   const results = JSON.parse(await readFile(trace, 'utf8')).map(record => record.result);
   if (name === 'basic') {assert.equal(results.length, 1); assert.equal(results[0].fieldResults.length, 0); assert.equal(results[0].effective.intents[0].constraints[0].kind, 'prohibition');}
-  if (name === 'parse') assert.equal(results[0].effective.intents[0].inputs.orderId, '000123');
+  if (name === 'parse' || name === 'native-response') assert.equal(results[0].effective.intents[0].inputs.orderId, '000123');
   if (name === 'multi-turn') {
     assert.equal(results.length, 3);
     const [first, second, third] = results;
@@ -182,4 +165,4 @@ for (const name of ['basic', 'parse', 'multi-turn']) {
   runnableExamples.push({name, actualCoreResults: results.length, authenticationFailureHandled: true});
 }
 await writeFile(path.join(work, 'verification.json'), JSON.stringify({node: process.version, syntaxFiles, customExecutorStrictTypes: true, resultExamples, protocolRecords, globalMaintenance, runnableExamples, realProviderCalls: 0, scope: 'User documentation installation/configuration/SDK examples and static result fixtures; not model semantic acceptance.'}, null, 2) + '\n');
-console.log('User examples verified: ' + syntaxFiles + ' ESM files, strict custom executor, ' + resultExamples + ' full responses, 3 actual SDK protocols, 3 runnable API examples and auth failure branches, ' + (tarball ? 'isolated global setup/doctor/clean' : 'no new global install') + '.');
+console.log('User examples verified: ' + syntaxFiles + ' ESM files, strict custom executor, ' + resultExamples + ' full responses, 3 actual SDK protocols, 4 runnable API examples and auth failure branches, ' + (tarball ? 'isolated global setup/doctor/clean' : 'no new global install') + '.');

scripts/documentation/result-check.mjs

@@ -0,0 +1,78 @@
+import assert from 'node:assert/strict';
+
+export function pointer(root, text) {
+  assert(typeof text === 'string' && (text === '' || text.startsWith('/')), 'Expected JSON Pointer: ' + text);
+  assert(!/~(?![01])/u.test(text), 'Invalid pointer escape: ' + text);
+  return text === '' ? root : text.slice(1).split('/').map(s => s.replace(/~1/g, '/').replace(/~0/g, '~')).reduce((value, key) => {
+    assert(value !== null && typeof value === 'object' && Object.hasOwn(value, key), text);
+    return value[key];
+  }, root);
+}
+
+function identities(snapshot, unique = false) {
+  const sets = {intent: new Set(), constraint: new Set(), relation: new Set()};
+  const all = new Set();
+  const add = (kind, value) => {
+    assert(typeof value.id === 'string');
+    if (unique) assert(!all.has(value.id), 'Duplicate identity: ' + value.id);
+    all.add(value.id); sets[kind].add(value.id);
+  };
+  function visit(nodes) {for (const node of nodes ?? []) {
+    add('intent', node); node.constraints?.forEach(c => add('constraint', c));
+    const refs = new Set();
+    for (const ref of node.references ?? []) {assert(!refs.has(ref.id)); refs.add(ref.id);}
+    visit(node.children);
+  }}
+  visit(snapshot?.intents);
+  snapshot?.constraints?.forEach(c => add('constraint', c));
+  snapshot?.relations?.forEach(r => add('relation', r));
+  return sets;
+}
+
+// Documentation fixture checks, not an alternative public business Validator.
+// Prior withdrawal examples carry an explicit baseline snapshot. Arbitrary
+// Context strings are not treated as permission to reference any old ID.
+export function checkResultLinks(result, materials) {
+  const current = identities(result.effective, true), prior = identities(materials.baseline);
+  const all = new Set(Object.values(current).flatMap(set => [...set]));
+  for (const issue of result.issues ?? []) {assert(!all.has(issue.id), 'Duplicate issue identity'); all.add(issue.id);}
+  for (const change of result.turn.changes) {
+    if (change.target.kind !== 'unresolved') {
+      const {kind, id} = change.target;
+      assert(current[kind], 'Unknown target kind');
+      if (change.operation === 'withdraw' && change.effect === 'applied') {
+        assert(!current[kind].has(id) && prior[kind].has(id), 'Withdrawal must reference a supplied prior ' + kind);
+      } else assert(current[kind].has(id), 'Target must be a current ' + kind);
+    }
+    if (change.conditionId !== undefined) assert(current.constraint.has(change.conditionId), 'conditionId must be a current constraint');
+  }
+  for (const id of result.turn.intentIds) assert(current.intent.has(id), 'turn.intentIds must reference current intents');
+  for (const relation of result.effective.relations) assert(current.intent.has(relation.fromId) && current.intent.has(relation.toId));
+  for (const entry of [...result.evidence ?? [], ...result.inferences]) pointer(result, entry.target);
+  function sources(value) {
+    if (!value || typeof value !== 'object') return;
+    if ('root' in value && 'pointer' in value) {
+      assert(Object.hasOwn(materials, value.root), 'Missing source root: ' + value.root);
+      const source = pointer(materials[value.root], value.pointer);
+      if (value.quote !== undefined) assert((typeof source === 'string' ? source : JSON.stringify(source)).includes(value.quote));
+    }
+    for (const child of Object.values(value)) sources(child);
+  }
+  sources(result);
+}
+
+// Runtime IDs are opaque. Canonical names make fixed documentation readable;
+// the same replacement is applied to requests, baselines and results together.
+export function readableIds(value) {
+  const mapping = new Map(), counts = new Map();
+  return JSON.parse(JSON.stringify(value, (_key, item) => {
+    if (typeof item !== 'string') return item;
+    return item.replace(/(?:intent|constraint|relation|reference)-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi, id => {
+      if (!mapping.has(id)) {
+        const kind = id.slice(0, id.indexOf('-')), index = (counts.get(kind) ?? 0) + 1;
+        counts.set(kind, index); mapping.set(id, kind + '-' + index);
+      }
+      return mapping.get(id);
+    });
+  }));
+}

scripts/documentation/result-check.test.mjs

@@ -0,0 +1,26 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {checkResultLinks, pointer, readableIds} from './result-check.mjs';
+
+const old = {id: 'old', constraints: [], references: [], children: []};
+const materials = {input: '撤回旧请求', baseline: {intents: [old], constraints: [], relations: []}};
+function withdrawn() {return {turn: {intentIds: [], changes: [{operation: 'withdraw', effect: 'applied', target: {kind: 'intent', id: 'old'}}]}, effective: {intents: [], constraints: [], relations: []}, inferences: []};}
+test('withdrawal may reference a baseline intent absent from effective', () => checkResultLinks(withdrawn(), materials));
+test('derived issue IDs and nested baseline references use the same readable ID', () => {
+  const id = 'intent-c7135d1a-ad05-4894-a974-07b2fb6dac12';
+  assert.deepEqual(readableIds({id, issue: 'understanding-' + id, baseline: {id}, orderId: '000123'}), {id: 'intent-1', issue: 'understanding-intent-1', baseline: {id: 'intent-1'}, orderId: '000123'});
+});
+test('invented prior IDs remain invalid', () => {const r = withdrawn(); r.turn.changes[0].target.id = 'invented'; assert.throws(() => checkResultLinks(r, materials), /supplied prior/);});
+test('a prior intent cannot authorize a constraint target', () => {const r = withdrawn(); r.turn.changes[0].target.kind = 'constraint'; assert.throws(() => checkResultLinks(r, materials), /supplied prior/);});
+test('arbitrary Context strings do not authorize prior IDs', () => assert.throws(() => checkResultLinks(withdrawn(), {input: '撤回', context: {note: 'old'}}), /supplied prior/));
+test('a condition must reference a current constraint, not an intent', () => {
+  const r = withdrawn(); r.effective.intents = [old]; r.turn.intentIds = ['old'];
+  r.turn.changes = [{operation: 'withdraw', effect: 'conditional', target: {kind: 'intent', id: 'old'}, conditionId: 'old'}];
+  assert.throws(() => checkResultLinks(r, materials), /current constraint/);
+});
+test('pointer preserves empty names and escaped keys and rejects malformed paths', () => {
+  assert.equal(pointer({meta: {'': 1}}, '/meta/'), 1);
+  assert.equal(pointer({'a/b': {'~': 2}}, '/a~1b/~0'), 2);
+  assert.throws(() => pointer({}, '/a~2b'), /escape/);
+  assert.throws(() => pointer({}, 'orders/1/amount'), /JSON Pointer/);
+});