@harmonyos-arkts/d2h 0.1.19 → 0.1.21

package/opencode/interactive-tools/core.ts

@@ -0,0 +1,242 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+
+export type Step = 'environment' | 'architecture' | 'scope' | 'report';
+export interface Choice { id: string; label: string; detail: string; selected?: boolean; featureId?: string }
+export interface Check { label: string; status: 'ready' | 'missing' | 'unverified'; detail: string }
+export interface Workflow {
+  schema: 'd2h-interactive-workflow/v1';
+  title: string;
+  demo: boolean;
+  checks: Check[];
+  architectures: Choice[];
+  scopes: Choice[];
+  report: string;
+  baseline: { featureHash: string; planHash: string; candidate: string; eventSequence: number };
+  target?: 'mvp' | 'core' | 'full' | null;
+  userPriorities?: Record<string, 'must' | 'normal' | 'later'>;
+}
+export interface Interaction {
+  schema: 'd2h-interaction/v1'; id: string; projectRoot: string; sessionId: string; messageId: string;
+  workflowPath: string; revision: string; step: Step; createdAt: string; expiresAt: string; workflow: Workflow;
+}
+export interface Decision {
+  schema: 'd2h-interaction-result/v1'; requestId: string; sessionId: string; revision: string;
+  action: 'accept' | 'cancel'; selected: string[]; reason: string; submittedAt: string;
+}
+const steps: Step[] = ['environment', 'architecture', 'scope', 'report'];
+export const stepLabels: Record<Step, string> = {
+  environment: '确认环境', architecture: '选择架构', scope: '选择实施范围', report: '查看报告',
+};
+export function digest(value: string): string { return createHash('sha256').update(value).digest('hex'); }
+function assert(condition: unknown, message: string): asserts condition { if (!condition) { throw new Error(message); } }
+function plainFile(file: string): string {
+  const stat = fs.lstatSync(file);
+  assert(stat.isFile() && !stat.isSymbolicLink() && stat.size <= 1024 * 1024, '文件必须是小于 1 MiB 的普通文件');
+  return fs.readFileSync(file, 'utf8');
+}
+export function readWorkflow(file: string): Workflow {
+  const data = JSON.parse(plainFile(file)) as Workflow;
+  assert(data.schema === 'd2h-interactive-workflow/v1' && typeof data.title === 'string' && typeof data.demo === 'boolean', '无效的工作流');
+  assert(Array.isArray(data.checks) && data.checks.every(c => typeof c.label === 'string' && typeof c.detail === 'string' && ['ready', 'missing', 'unverified'].includes(c.status)), '无效的环境检查');
+  for (const choices of [data.architectures, data.scopes]) {
+    assert(Array.isArray(choices) && choices.length > 0 && choices.length <= 200, '选项必须为 1–200 项');
+    assert(choices.every(c => typeof c.id === 'string' && /^[\w.-]+$/.test(c.id) && typeof c.label === 'string' && typeof c.detail === 'string'), '无效的选项');
+    assert(new Set(choices.map(c => c.id)).size === choices.length, '选项 ID 重复');
+  }
+  assert(typeof data.report === 'string' && data.baseline && typeof data.baseline.featureHash === 'string' && typeof data.baseline.planHash === 'string' && typeof data.baseline.candidate === 'string' && Number.isSafeInteger(data.baseline.eventSequence), '缺少报告或基线身份');
+  assert(data.scopes.every(c => typeof c.featureId === 'string' && /^[\w.-]+$/.test(c.featureId)), '范围选项缺少 featureId');
+  return data;
+}
+export function interactionRoot(project: string): string {
+  const root = fs.realpathSync(project);
+  return path.join(path.dirname(root), `${path.basename(root)}-migration`, '.migration', 'interactions');
+}
+function requestDirectory(project: string, id: string): string {
+  assert(/^[a-f0-9-]{36}$/.test(id), '无效的请求 ID');
+  const root = interactionRoot(project);
+  const migration = path.dirname(path.dirname(root));
+  for (let ancestor = root; ancestor !== path.dirname(migration); ancestor = path.dirname(ancestor)) {
+    if (fs.existsSync(ancestor)) { assert(fs.realpathSync(ancestor) === ancestor, '交互目录不能通过符号链接重定向'); }
+  }
+  const dir = path.join(root, id);
+  if (fs.existsSync(dir)) {
+    assert(!fs.lstatSync(dir).isSymbolicLink() && fs.realpathSync(dir) === dir, '交互目录不能通过符号链接重定向');
+  }
+  return dir;
+}
+function writeExclusive(file: string, value: unknown): void {
+  const temp = `${file}.${randomUUID()}.tmp`;
+  fs.writeFileSync(temp, JSON.stringify(value, null, 2), { mode: 0o600, flag: 'wx' });
+  try { fs.linkSync(temp, file); } finally { fs.unlinkSync(temp); }
+}
+export interface InteractionCapability {
+  supported: boolean; fallback: 'conversation'; reason: 'host_ready' | 'host_unavailable';
+}
+const hostTtlMs = 10_000;
+function hostDirectory(project: string): string {
+  requestDirectory(project, '00000000-0000-0000-0000-000000000000');
+  const dir = path.join(interactionRoot(project), '.hosts');
+  if (fs.existsSync(dir)) { assert(fs.realpathSync(dir) === dir, '界面能力目录不能通过符号链接重定向'); }
+  return dir;
+}
+/** A UI adapter advertises only sessions it can currently present. Never a user decision. */
+export function registerInteractionHost(project: string, sessionId: string) {
+  assert(sessionId.length > 0, '缺少界面会话');
+  const dir = hostDirectory(project);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const file = path.join(dir, randomUUID() + '.json');
+  const heartbeat = () => {
+    assert(hostDirectory(project) === dir, '界面能力目录发生变化');
+    const temp = file + '.tmp';
+    fs.writeFileSync(temp, JSON.stringify({ schema: 'd2h-interaction-host/v1',
+      projectRoot: fs.realpathSync(project), sessionId, steps, updatedAt: Date.now() }), { mode: 0o600, flag: 'wx' });
+    fs.renameSync(temp, file);
+  };
+  heartbeat();
+  return { heartbeat, dispose: () => {
+    try { hostDirectory(project); fs.rmSync(file, { force: true }); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') { throw error; } }
+  } };
+}
+export function interactionCapability(project: string, sessionId: string, step?: Step): InteractionCapability {
+  try {
+    const dir = hostDirectory(project), now = Date.now();
+    const supported = fs.readdirSync(dir).some(name => {
+      if (!/^[a-f0-9-]{36}\.json$/.test(name)) { return false; }
+      try {
+        const host = JSON.parse(plainFile(path.join(dir, name)));
+        return host.schema === 'd2h-interaction-host/v1' && host.projectRoot === fs.realpathSync(project)
+          && host.sessionId === sessionId && Number.isFinite(host.updatedAt)
+          && now >= host.updatedAt && now - host.updatedAt < hostTtlMs
+          && Array.isArray(host.steps) && (step ? host.steps.includes(step) : steps.every(s => host.steps.includes(s)));
+      } catch { return false; }
+    });
+    return { supported, fallback: 'conversation', reason: supported ? 'host_ready' : 'host_unavailable' };
+  } catch { return { supported: false, fallback: 'conversation', reason: 'host_unavailable' }; }
+}
+export class InteractionHostUnavailable extends Error {}
+/** Guard the tool itself as well as offering a separate capability query. */
+export async function requestInteraction(project: string, workflowPath: string, sessionId: string,
+  messageId: string, step: Step, signal?: AbortSignal,
+  onRequest?: (request: Interaction) => void) {
+  const capability = interactionCapability(project, sessionId, step);
+  if (!capability.supported) { return { status: 'unsupported' as const, ...capability }; }
+  const request = createInteraction(project, workflowPath, sessionId, messageId, step);
+  onRequest?.(request);
+  try { return { status: 'completed' as const, request, decision: await waitForDecision(request, signal, true) }; }
+  catch (error) {
+    if (!(error instanceof InteractionHostUnavailable)) { throw error; }
+    return { status: 'unsupported' as const, supported: false, fallback: 'conversation' as const, reason: 'host_unavailable' as const, requestId: request.id };
+  }
+}
+export function createInteraction(project: string, workflowPath: string, sessionId: string, messageId: string, step: Step, ttlMs = 30 * 60_000): Interaction {
+  assert(steps.includes(step) && sessionId.length > 0 && ttlMs > 0, '无效的会话或步骤');
+  assert(path.isAbsolute(workflowPath), '工作流路径必须为绝对路径');
+  const projectRoot = fs.realpathSync(project);
+  const workflow = readWorkflow(workflowPath);
+  const id = randomUUID();
+  const dir = requestDirectory(projectRoot, id);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  requestDirectory(projectRoot, id);
+  const request: Interaction = {
+    schema: 'd2h-interaction/v1', id, projectRoot, sessionId, messageId, step,
+    workflowPath: path.resolve(workflowPath), revision: digest(plainFile(workflowPath)), workflow,
+    createdAt: new Date().toISOString(), expiresAt: new Date(Date.now() + ttlMs).toISOString(),
+  };
+  writeExclusive(path.join(dir, 'request.json'), request);
+  return request;
+}
+export function readInteraction(project: string, id: string): Interaction {
+  const data = JSON.parse(plainFile(path.join(requestDirectory(project, id), 'request.json'))) as Interaction;
+  assert(data.schema === 'd2h-interaction/v1' && data.id === id && data.projectRoot === fs.realpathSync(project) && steps.includes(data.step), '请求身份不匹配');
+  return data;
+}
+export function listInteractions(project: string): Interaction[] {
+  const root = interactionRoot(project);
+  if (!fs.existsSync(root)) { return []; }
+  return fs.readdirSync(root).filter(id => /^[a-f0-9-]{36}$/.test(id)).flatMap(id => {
+    try { return [readInteraction(project, id)]; } catch { return []; }
+  }).sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+}
+export function readDecision(request: Interaction): Decision | undefined {
+  const file = path.join(requestDirectory(request.projectRoot, request.id), 'result.json');
+  if (!fs.existsSync(file)) { return undefined; }
+  const result = JSON.parse(plainFile(file)) as Decision;
+  assert(result.schema === 'd2h-interaction-result/v1' && result.requestId === request.id && result.sessionId === request.sessionId && result.revision === request.revision, '结果不属于当前请求');
+  validateDecision(request, result.action, result.selected, result.reason);
+  return result;
+}
+function validateDecision(request: Interaction, action: string, selected: string[], reason: string): void {
+  assert(['accept', 'cancel'].includes(action) && typeof reason === 'string' && reason.length <= 4000, '无效的提交');
+  assert(Array.isArray(selected) && selected.every(id => typeof id === 'string') && new Set(selected).size === selected.length, '无效的选择');
+  if (action === 'cancel') { assert(selected.length === 0, '取消不能携带选择'); return; }
+  if (request.step === 'environment') {
+    assert(selected.length === 0 && request.workflow.checks.every(c => c.status === 'ready'), '环境仍有缺失或未验证项，不能确认通过');
+  } else if (request.step === 'architecture' || request.step === 'scope') {
+    const choices = request.step === 'architecture' ? request.workflow.architectures : request.workflow.scopes;
+    assert(selected.length > 0 && selected.every(id => choices.some(c => c.id === id)), '选择为空或包含未知项');
+    assert(request.step !== 'architecture' || selected.length === 1, '架构必须单选');
+    assert(request.step !== 'scope' || reason.trim().length > 0, '范围确认需要填写原因');
+  } else { assert(selected.length === 0, '报告确认不接受范围项'); }
+}
+export function submitDecision(project: string, id: string, revision: string, action: 'accept' | 'cancel', selected: string[], reason: string): Decision {
+  const request = readInteraction(project, id);
+  assert(request.revision === revision, '请求版本不匹配');
+  if (action === 'accept') { assert(digest(plainFile(request.workflowPath)) === revision, '输入版本已变化，请取消本次请求并重新发起'); }
+  assert(Date.now() < Date.parse(request.expiresAt), '请求已过期，请重新发起');
+  assert(!fs.existsSync(path.join(requestDirectory(project, id), 'aborted.json')), '原工具已经取消');
+  validateDecision(request, action, selected, reason);
+  const result: Decision = { schema: 'd2h-interaction-result/v1', requestId: id, sessionId: request.sessionId, revision, action, selected, reason, submittedAt: new Date().toISOString() };
+  writeExclusive(path.join(requestDirectory(project, id), 'result.json'), result);
+  return result;
+}
+export function interactionStatus(request: Interaction): string {
+  const dir = requestDirectory(request.projectRoot, request.id);
+  if (fs.existsSync(path.join(dir, 'aborted.json'))) {
+    return JSON.parse(plainFile(path.join(dir, 'aborted.json'))).reason === 'expired' ? '已过期' : '已取消';
+  }
+  const result = readDecision(request);
+  if (result) { return result.action === 'accept' ? '已提交' : '已取消'; }
+  if (Date.now() >= Date.parse(request.expiresAt)) { return '已过期'; }
+  return '等待确认';
+}
+export function isWaitingForInteraction(project: string, sessionId: string): boolean {
+  try { return listInteractions(project).some(request => request.sessionId === sessionId && interactionStatus(request) === '等待确认'); }
+  catch { return false; }
+}
+export async function waitForDecision(request: Interaction, signal?: AbortSignal, requireHost = false): Promise<Decision> {
+  for (;;) {
+    if (signal?.aborted || Date.now() >= Date.parse(request.expiresAt)) {
+      const file = path.join(requestDirectory(request.projectRoot, request.id), 'aborted.json');
+      if (!fs.existsSync(file)) { writeExclusive(file, { reason: signal?.aborted ? 'tool_cancelled' : 'expired' }); }
+      throw new Error(signal?.aborted ? '交互已取消' : '交互已过期');
+    }
+    const result = readDecision(request);
+    if (result) {
+      if (result.action === 'accept') { assert(digest(plainFile(request.workflowPath)) === request.revision, '工具恢复前输入版本发生变化'); }
+      return result;
+    }
+    if (requireHost && !interactionCapability(request.projectRoot, request.sessionId, request.step).supported) {
+      const file = path.join(requestDirectory(request.projectRoot, request.id), 'aborted.json');
+      if (!fs.existsSync(file)) { writeExclusive(file, { reason: 'host_unavailable' }); }
+      throw new InteractionHostUnavailable('界面不可用，请回到原会话询问；未记录用户同意');
+    }
+    await new Promise(resolve => setTimeout(resolve, 250));
+  }
+}
+export function scopeChange(request: Interaction, decision: Decision): object {
+  assert(request.step === 'scope' && decision.action === 'accept', '不是已提交的范围请求');
+  return {
+    schema: 'd2h-scope-change-request/v1',
+    feature_hash: request.workflow.baseline.featureHash,
+    plan_hash: request.workflow.baseline.planHash,
+    candidate: request.workflow.baseline.candidate,
+    event_sequence: request.workflow.baseline.eventSequence,
+    target: request.workflow.target ?? null,
+    scope_refs: decision.selected.map(id => ({ feature_id: request.workflow.scopes.find(c => c.id === id)!.featureId, scope_id: id })),
+    user_priorities: request.workflow.userPriorities ?? {},
+    reason: decision.reason,
+  };
+}

package/opencode/interactive-tools/demo-workflow.ts

@@ -0,0 +1,55 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createInteraction, waitForDecision, scopeChange } from './core.ts';
+import type { Decision, Workflow } from './core.ts';
+
+export const demoWorkflow: Workflow = {
+  schema: 'd2h-interactive-workflow/v1', demo: true, title: '迁移规划演示 · 启动 → 基本登录 → 主页面雏形',
+  checks: [
+    { label: '开发运行时', status: 'ready', detail: '演示 fixture：Node / Python / Git 已准备。实际工具须读取真实检查报告。' },
+    { label: 'HarmonyOS 工具链', status: 'ready', detail: '演示 fixture：不代表 SDK、签名、编译或设备已验证。' },
+    { label: '本轮执行边界', status: 'ready', detail: '仅收集用户决策、形成范围草稿；不进入目标应用开发。' },
+  ],
+  architectures: [
+    { id: 'native-arkts', label: '原生 ArkTS + 平台适配', detail: '界面按鸿蒙范式实现，Native 库与绑定层单独评估。', selected: true },
+    { id: 'retain-native', label: '保留可复用 Native 核心', detail: 'UI 使用 ArkTS；复用核心前必须验证构建、平台依赖及 N-API 边界。' },
+  ],
+  scopes: [
+    { id: 'startup', featureId: 'feature-startup', label: '启动与路由', detail: '启动到可交互首屏。', selected: true },
+    { id: 'login-basic', featureId: 'feature-login', label: '基本登录', detail: '完成进入主页面所需的最小登录路径。', selected: true },
+    { id: 'home-shell', featureId: 'feature-home', label: '主页面雏形', detail: '尽早形成导航和核心内容骨架，不等待完整登录体系。', selected: true },
+    { id: 'login-complete', featureId: 'feature-login', label: '完整账号体系', detail: '多种登录、找回密码等，默认延期。' },
+  ],
+  baseline: { featureHash: 'demo-features-v1', planHash: 'demo-plan-v1', candidate: 'demo-only', eventSequence: 0 },
+  target: 'mvp', userPriorities: { 'feature-startup': 'normal', 'feature-login': 'normal', 'feature-home': 'must' },
+  report: '本次仅验证交互流程。\n\n用户决策将返回原工具调用；没有生成应用源码，没有执行构建或设备验收。\n\n范围草稿需经主 Agent 校验、修订上游和 reconcile 后才算应用成功。',
+};
+
+export function demoReport(results: Decision[]): string {
+  const architecture = results.find(result => result.selected.some(id => demoWorkflow.architectures.some(c => c.id === id)));
+  const scope = results.find(result => result.selected.some(id => demoWorkflow.scopes.some(c => c.id === id)));
+  return `交互决策摘要（演示）\n\n架构：${demoWorkflow.architectures.find(c => architecture?.selected.includes(c.id))?.label ?? '未确认'}\n实施范围：${demoWorkflow.scopes.filter(c => scope?.selected.includes(c.id)).map(c => c.label).join(' → ')}\n选择原因：${scope?.reason ?? ''}\n\n${demoWorkflow.report}`;
+}
+
+export async function runDemo(project: string, sessionId: string, signal?: AbortSignal, onStep?: (message: string) => void): Promise<Decision[]> {
+  const file = path.join(project, 'd2h-interaction-demo.json');
+  if (fs.existsSync(file)) { throw new Error('演示输入已存在，请使用新的演示目录，避免覆盖'); }
+  fs.mkdirSync(project, { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(demoWorkflow, null, 2), { flag: 'wx' });
+  const results: Decision[] = [];
+  for (const step of ['environment', 'architecture', 'scope', 'report'] as const) {
+    onStep?.(`等待用户：${step}`);
+    const request = createInteraction(project, file, sessionId, 'demo-driver', step);
+    const result = await waitForDecision(request, signal);
+    results.push(result);
+    if (step === 'scope' && result.action === 'accept') {
+      fs.writeFileSync(path.join(project, 'scope-draft.json'), JSON.stringify(scopeChange(request, result), null, 2));
+      fs.writeFileSync(file, JSON.stringify({ ...demoWorkflow, report: demoReport(results) }, null, 2));
+    }
+    if (result.action === 'cancel') { onStep?.('用户取消，流程停止'); return results; }
+    onStep?.(`已收到用户结果，原流程继续：${step}`);
+  }
+  fs.writeFileSync(path.join(project, 'interaction-results.json'), JSON.stringify(results, null, 2));
+  onStep?.('四步交互完成；未执行迁移或验收');
+  return results;
+}

package/opencode/interactive-tools/demo.mjs

@@ -0,0 +1,37 @@
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { randomBytes } from 'node:crypto';
+import { listInteractions, interactionStatus, submitDecision } from '../../dist/opencode/interactive-tools/core.js';
+import { interactionHtml } from '../../dist/opencode/interactive-tools/panel.js';
+import { runDemo } from '../../dist/opencode/interactive-tools/demo-workflow.js';
+
+const root = path.dirname(fileURLToPath(import.meta.url));
+const project = path.resolve(process.argv[2] || path.join(root, '../../../validation/interactive-tools-mvp', `browser-${Date.now()}`));
+fs.mkdirSync(project, { recursive: true });
+const port = Number(process.env.D2H_PREVIEW_PORT || 4318);
+const origin = `http://127.0.0.1:${port}`;
+const controller = new AbortController();
+const server = http.createServer(async (req, res) => {
+  res.setHeader('Cache-Control', 'no-store');
+  res.setHeader('X-Content-Type-Options', 'nosniff');
+  if (req.headers.host !== `127.0.0.1:${port}` || (req.headers.origin && req.headers.origin !== origin)) { res.writeHead(403).end(); return; }
+  try {
+    if (req.method === 'GET' && req.url === '/') { res.setHeader('Content-Type', 'text/html; charset=utf-8'); res.end(interactionHtml(randomBytes(18).toString('base64'))); }
+    else if (req.method === 'GET' && req.url === '/snapshot') { res.setHeader('Content-Type', 'application/json'); res.end(JSON.stringify({ type: 'snapshot', items: listInteractions(project).map(request => ({ request, status: interactionStatus(request) })) })); }
+    else if (req.method === 'POST' && req.url === '/action') {
+      if (req.headers.origin !== origin || req.headers['content-type'] !== 'application/json') { res.writeHead(403).end(); return; }
+      let body = ''; for await (const chunk of req) { body += chunk; if (body.length > 64 * 1024) { throw Error('请求过大'); } }
+      const message = JSON.parse(body);
+      if (message.type === 'submit') { submitDecision(project, message.id, message.revision, message.action, message.selected, message.reason); }
+      else if (message.type !== 'ready') { throw Error('未知动作'); }
+      res.setHeader('Content-Type', 'application/json'); res.end('{}');
+    } else { res.writeHead(404).end(); }
+  } catch (error) { res.writeHead(400, { 'Content-Type': 'application/json' }).end(JSON.stringify({ error: String(error.message) })); }
+});
+server.listen(port, '127.0.0.1', () => {
+  console.log(`d2h 交互 MVP：${origin}\n演示目录：${project}\n这是工具等待/返回的本地驱动，没有调用模型。`);
+  void runDemo(project, 'demo-browser-no-model', controller.signal, console.log).catch(error => console.error(error.message));
+});
+for (const signal of ['SIGINT', 'SIGTERM']) { process.on(signal, () => { controller.abort(); server.close(); }); }