frontend-project-context 1.8.0 → 1.10.0

package/src/project-context/work-view.mjs

@@ -0,0 +1,135 @@
+import { canonicalJson, prettyCanonicalJson } from "./canonical-json.mjs";
+import { fail } from "./errors.mjs";
+import { validateWorkView } from "./work-view-schema.mjs";
+
+export const WORK_VIEW_MAX_BYTES = 1024 * 1024;
+const priority = { policy: 0, "validation-description": 1, fact: 2, reference: 3 };
+const intentNames = { investigate: "调查", design: "设计", implement: "实施" };
+const ranked = (items) => [...items].sort((a, b) => priority[a.kind] - priority[b.kind] || a.id.localeCompare(b.id));
+const excerpt = (value, limit = 240) => {
+  const text = typeof value === "string" ? value : JSON.stringify(value);
+  return text.length <= limit ? text : `${text.slice(0, limit)}…（预览省略，须消费完整内容）`;
+};
+const progress = (record) => record ? { revision: record.revision, identity: "host-reported", ...structuredClone(record.progress) } : null;
+
+function constraints(items) {
+  return ranked(items).slice(0, 5).map((x) => ({ text: excerpt(`${x.statement}；内容：${JSON.stringify(x.value)}`), itemIds: [x.id], scope: x.scope }));
+}
+
+function issue(gap, record) {
+  const object = gap.path ?? gap.evidenceId ?? gap.requirementId ?? gap.decisionId ?? gap.id;
+  const descriptions = {
+    "required-not-read": ["Host", `还需读取 ${object} 并核对当前内容。`, "读取该文件后提交本次消费声明。"],
+    "context-not-consumed": ["Host", "当前 Context 尚未提交本次消费声明。", "实际阅读 required、判断 conditional，并核对任务证据后复查。"],
+    "requirements-not-consumed": ["Host", "声明没有绑定当前需求与依据。", "核对最新需求摘要并重新消费；不要求用户重述未变需求。"],
+    "consumption-task-mismatch": ["Host", "消费声明不属于当前任务。", "使用当前任务身份重新消费。"],
+    "evidence-missing": ["Host", `任务依据 ${object} 缺失。`, "在授权范围内定位具体依据；无法找到时报告缺口。"],
+    "evidence-changed": ["Host", `任务依据 ${object} 已变化。`, "读取并比较最新内容；必要的业务决定变化才请人确认。"],
+    "decision-open": ["用户", record?.decisions.find((x) => x.id === gap.decisionId)?.question ?? `决定 ${object} 尚未确认。`, "回答该具体问题；Host 不推断确认值。"],
+    "read-target-needs-file-scope": ["Host", `${object} 是目录，不能作为已读文件。`, "在 targetRoot 内收窄到实际文件并重新交接。"],
+    "target-path-not-yet-known": ["Host", "目标路径尚未锁定。", "消费项目范围 Context，在 targetRoot 内有限定位，再提交完整最小文件集合。"],
+    "project-needs-governance": ["维护者", "项目来源、批准或入口需要维护，当前交接保持阻断。", "运行 sync，审查并处理精确维护项，恢复 clean 后继续。"],
+    "work-view-budget-exceeded": ["Host", "工作交付超过上限，完整内容未交付。", "收窄具体目标或证据；概览枚举过大时提供明确 taskId。无新事实不重复重试。"],
+  };
+  const [actor, explanation, nextStep] = descriptions[gap.code] ?? ["Host", `${gap.code}：${object}`, "核对该对象和原始缺口；不能忽略后开工。"];
+  return { code: gap.code, object, explanation, actor, nextStep };
+}
+
+function presentation(base, context, record) {
+  const items = context?.items ?? [];
+  const issues = (base.gaps ?? base.findingCodes?.map((code) => ({ id: code, code })) ?? []).map((x) => issue(x, record));
+  const active = base.tasks?.filter((x) => x.lifecycle === "active") ?? [];
+  const questions = base.questions?.filter((x) => x.blockingNow).map((x) => ({ decisionId: x.id, question: x.question })) ?? [];
+  const basis = record ? [
+    ...record.requirements.map((x) => ({ text: excerpt(x.text), requirementIds: [x.id], evidenceIds: x.evidenceIds })),
+    ...record.decisions.filter((x) => x.status === "confirmed").map((x) => ({ text: excerpt(`${x.question}：${x.value}`), decisionIds: [x.id], evidenceIds: x.evidenceIds })),
+  ] : [];
+  let nextStep;
+  if (base.kind === "project-brief") {
+    nextStep = base.connection === "not-connected" ? "Host 先读取包内 instructions，按唯一初始化指引接入。" : base.connection !== "available" ? "维护者按项目 findings 处理治理或入口问题。" : active.length ? "直接点名任务标题继续，或描述新需求；有歧义时只核对一次选择。" : "直接描述要改的现象或功能，给出现有设计，或请求只读盘点。";
+  } else {
+    nextStep = base.gate.status === "not-applicable" ? "该任务已结束；可查看历史，不自动恢复实施。" : base.gate.status === "hold" ? (issues[0]?.nextStep ?? base.gate.instruction) : `Host 核对当前用户授权后继续${intentNames[base.intent]}；门禁不授予权限。`;
+  }
+  return {
+    headline: record ? `任务「${excerpt(base.taskIdentity.title)}」：当前${intentNames[base.intent]}；${base.gate.status === "hold" ? "需处理缺口" : base.gate.status === "not-applicable" ? "已结束" : "当前上下文就绪"}。` : `项目「${excerpt(base.project?.name ?? "未接入")}」：${base.connection === "available" ? "规则可用，目前没有选定开发任务" : "需要接入或维护"}。`,
+    constraints: constraints(items), remainingConstraints: Math.max(0, items.length - 5),
+    basis: basis.slice(0, 3), remainingBasis: Math.max(0, basis.length - 3),
+    progress: progress(record), issues, questions, nextStep,
+  };
+}
+
+function measure(value) {
+  for (let i = 0; i < 8; i += 1) {
+    const bytes = Buffer.byteLength(prettyCanonicalJson(value));
+    if (bytes === value.delivery.bytes) return bytes;
+    value.delivery.bytes = bytes;
+  }
+  fail("work-view-budget-exceeded", "cannot stabilize output byte count", { exitCode: 1 });
+}
+
+export function finalizeWorkView(value) {
+  value.delivery.bytes = 0;
+  if (measure(value) > WORK_VIEW_MAX_BYTES) {
+    const gap = { id: "delivery:budget", code: "work-view-budget-exceeded" };
+    value.context = null;
+    value.delivery = { status: "withheld", reasonCodes: [gap.code], bytes: 0, maxBytes: WORK_VIEW_MAX_BYTES };
+    if (value.kind === "task-handoff-result") {
+      value.taskSnapshot = null;
+      value.gaps = [gap]; value.questions = []; value.itemIds = []; value.scopeCoverage = [];
+      value.requiredTargets = []; value.conditionalTargets = []; value.evidenceResults = [];
+      if (value.taskStatus !== "inactive" && value.taskStatus !== "blocked") value.taskStatus = "needs-evidence";
+      value.gate = { ...value.gate, status: value.taskStatus === "inactive" ? "not-applicable" : "hold", reasonIds: [gap.id], instruction: "完整内容未交付，收窄目标后重新交接。" };
+      value.nextAction = "narrow-work-view-targets";
+    } else {
+      value.tasks = []; value.overview = { items: [], scopeSummary: [], limitations: [gap.code] };
+      value.findingCodes = [...new Set([...value.findingCodes, gap.code])]; value.nextAction = "provide-exact-task-id-or-narrow-context";
+    }
+    value.presentation = { headline: "完整工作内容未交付，当前不能据此开始任务。", constraints: [], remainingConstraints: 0, basis: [], remainingBasis: 0, progress: null, issues: [issue(gap)], questions: [], nextStep: issue(gap).nextStep };
+    if (measure(value) > WORK_VIEW_MAX_BYTES) fail("work-view-budget-exceeded", "metadata also exceeds output budget; provide a smaller explicit task record", { exitCode: 1 });
+  }
+  return validateWorkView(value);
+}
+
+export function taskWorkView(base, context, record) {
+  const evidenceMap = new Map(base.evidenceResults.map((x) => [x.id, x.status]));
+  const taskSnapshot = record ? {
+    origin: structuredClone(record.origin), scope: structuredClone(record.scope),
+    requirements: structuredClone(record.requirements), decisions: structuredClone(record.decisions),
+    evidence: record.evidence.map((x) => ({ ...structuredClone(x), status: evidenceMap.get(x.id) ?? "not-checked" })),
+    progress: progress(record),
+  } : null;
+  return finalizeWorkView({ ...base, schemaVersion: 2, context, taskSnapshot, presentation: presentation(base, context, record), delivery: { status: context ? "ready" : "withheld", reasonCodes: context ? [] : base.gaps.map((x) => x.code), bytes: 0, maxBytes: WORK_VIEW_MAX_BYTES } });
+}
+
+export function projectWorkView(base, context, items) {
+  const scopeMap = new Map();
+  for (const x of items) {
+    const key = canonicalJson(x.scope);
+    if (!scopeMap.has(key)) scopeMap.set(key, { scope: structuredClone(x.scope), items: 0 });
+    scopeMap.get(key).items += 1;
+  }
+  const cards = ranked(items).slice(0, 5).map((x) => ({ id: x.id, kind: x.kind, subject: x.subject, statement: x.statement, value: structuredClone(x.value), scope: structuredClone(x.scope), sourceIds: [...x.sources].sort() }));
+  const limitations = context ? [...new Set(context.gaps.map((x) => x.code).filter((x) => x !== "target-path-not-yet-known"))] : [...base.findingCodes];
+  return finalizeWorkView({ ...base, schemaVersion: 2, context, overview: { items: cards, scopeSummary: [...scopeMap.values()].sort((a, b) => canonicalJson(a.scope).localeCompare(canonicalJson(b.scope))), limitations }, presentation: presentation(base, context), delivery: { status: context ? "ready" : "withheld", reasonCodes: context ? [] : base.findingCodes, bytes: 0, maxBytes: WORK_VIEW_MAX_BYTES } });
+}
+
+export function renderWorkView(value) {
+  const p = value.presentation;
+  const lines = [p.headline];
+  if (value.kind !== "project-brief" && p.constraints.length) lines.push("本次可追溯规则：", ...p.constraints.map((x) => `- ${x.text}`));
+  if (value.kind !== "project-brief" && p.remainingConstraints) lines.push(`还有 ${p.remainingConstraints} 条，请消费完整 Context。`);
+  if (p.basis.length) lines.push("当前依据：", ...p.basis.map((x) => `- ${x.text}`));
+  if (p.remainingBasis) lines.push(`还有 ${p.remainingBasis} 条依据，请查看完整 taskSnapshot。`);
+  if (p.progress) lines.push("进度（Host 记录）：", ...p.progress.completed.map((x) => `- 已完成：${excerpt(x)}`), ...p.progress.remaining.map((x) => `- 剩余：${excerpt(x)}`));
+  if (value.kind === "project-brief") {
+    if (value.overview.items.length) lines.push("已批准知识预览（按声明范围适用）：", ...value.overview.items.map((x) => `- [${x.scope.kind}${x.scope.path ? `：${x.scope.path}` : ""}] ${excerpt(`${x.statement}；内容：${JSON.stringify(x.value)}`)}`));
+    if (value.overview.scopeSummary.length) lines.push("已声明范围：", ...value.overview.scopeSummary.map((x) => `- ${x.scope.kind}${x.scope.path ? `：${x.scope.path}` : ""}，${x.items} 条；仅说明注册范围。`));
+    const active = value.tasks.filter((x) => x.lifecycle === "active");
+    if (active.length) lines.push("活动任务：", ...active.map((x) => `- ${excerpt(x.title)} (${x.taskId})；下一步：${excerpt(x.progressSummary.nextAction)}`));
+    if (value.overview.limitations.length) lines.push(`覆盖提示：${value.overview.limitations.join("、")}；未声明业务语义完整。`);
+  }
+  if (p.issues.length) lines.push("当前缺口：", ...p.issues.map((x) => `- ${x.actor}：${excerpt(x.explanation)}`));
+  if (p.questions.length) lines.push("需要决定：", ...p.questions.map((x) => `- ${excerpt(x.question)}`));
+  lines.push(`下一步：${p.nextStep}`);
+  return `${lines.join("\n")}\n`;
+}