openfeel 1.5.2 → 1.5.4

package/dsh/lib/adapters/recovery.js

@@ -0,0 +1,120 @@
+/**
+ * 恢复包（v1.5.3）
+ *
+ * 只读聚合：active stage/phase + 最近一次阶段转换 + `dev_last` 的交接摘要。
+ * 目标：新会话一次 `feel_status` 就能拿到恢复所需的最小信息，不必先读全文状态文件。
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const HANDOFF_HEADINGS = ['## 交接摘要', '## 公共交接区'];
+const MAX_HANDOFF_CHARS = 600;
+
+/** @param {string} projectRoot */
+function username(projectRoot) {
+  try {
+    const info = JSON.parse(readFileSync(join(projectRoot, '.openfeel', '.info.json'), 'utf-8'));
+    if (typeof info.user === 'string' && info.user.trim() !== '') return info.user.trim();
+  } catch {
+    /* fallthrough */
+  }
+  return process.env.OPENFEEL_USER ?? 'user';
+}
+
+/**
+ * 读取 `dev_last.md` 的交接摘要段（优先「交接摘要」，否则「公共交接区」）。
+ * @param {string} projectRoot
+ * @returns {string|null}
+ */
+export function readHandoff(projectRoot) {
+  const file = join(projectRoot, '.openfeel', 'users', username(projectRoot), 'dev_last.md');
+  let content;
+  try {
+    if (!existsSync(file)) return null;
+    content = readFileSync(file, 'utf-8');
+  } catch {
+    return null;
+  }
+  let start = -1;
+  for (const heading of HANDOFF_HEADINGS) {
+    const idx = content.indexOf(heading);
+    if (idx !== -1 && (start === -1 || idx < start)) start = idx;
+  }
+  if (start === -1) return null;
+  const rest = content.slice(start);
+  const nextHeading = rest.indexOf('\n## ', 1);
+  const section = nextHeading === -1 ? rest : rest.slice(0, nextHeading);
+  const text = section.trim();
+  if (text === '') return null;
+  return text.length > MAX_HANDOFF_CHARS ? `${text.slice(0, MAX_HANDOFF_CHARS)}…` : text;
+}
+
+/**
+ * @param {string} projectRoot
+ * @returns {{
+ *   stage: string|null, phase: string|null, requirement: string|null,
+ *   lastTransition: {action:string,time:string,stage:string|null,from:string|null,to:string|null}|null,
+ *   handoff: string|null, hasDevLast: boolean
+ * }}
+ */
+export function readRecovery(projectRoot) {
+  const result = {
+    stage: null,
+    phase: null,
+    requirement: null,
+    lastTransition: null,
+    lastError: null,
+    resumeCount: 0,
+    handoff: readHandoff(projectRoot),
+    hasDevLast: existsSync(join(projectRoot, '.openfeel', 'users', username(projectRoot), 'dev_last.md')),
+  };
+  try {
+    const flow = JSON.parse(readFileSync(join(projectRoot, '.openfeel', 'flow.json'), 'utf-8'));
+    const stages = flow.stages ?? {};
+    const active = Object.entries(stages).find(([, stage]) => stage.phase !== 'done');
+    if (active) {
+      result.stage = active[0];
+      result.phase = active[1]?.phase ?? null;
+      result.requirement = active[1]?.requirement_id ?? null;
+    }
+    const log = Array.isArray(flow.log) ? flow.log : [];
+    // v1.5.4：活跃阶段的最近失败 / resume 次数（从 200 条日志派生，不新增存储）
+    if (result.stage !== null) {
+      for (const entry of log) {
+        const detail = entry?.detail ?? {};
+        if (detail.stageName !== result.stage && detail.stage !== result.stage) continue;
+        if (entry.action === 'advance_stage_phase' && (detail.to === 'review_failed' || detail.to === 'test_failed')) {
+          result.lastError = { phase: detail.to, time: entry.time ?? '' };
+        }
+        if (detail.resumed === true) result.resumeCount += 1;
+      }
+    }
+    for (let i = log.length - 1; i >= 0; i -= 1) {
+      const entry = log[i];
+      if (entry?.action === 'advance_stage_phase') {
+        const detail = entry.detail ?? {};
+        result.lastTransition = {
+          action: entry.action,
+          time: entry.time ?? '',
+          stage: typeof detail.stageName === 'string' ? detail.stageName : null,
+          from: typeof detail.from === 'string' ? detail.from : null,
+          to: typeof detail.to === 'string' ? detail.to : null,
+        };
+        break;
+      }
+    }
+    if (result.lastTransition === null && log.length > 0) {
+      const last = log[log.length - 1];
+      result.lastTransition = {
+        action: last.action ?? '',
+        time: last.time ?? '',
+        stage: null,
+        from: null,
+        to: null,
+      };
+    }
+  } catch {
+    /* 损坏时降级为 handoff only */
+  }
+  return result;
+}

package/dsh/lib/surface/prompt.js

@@ -141,6 +141,11 @@ Feel（你）只做编排、决策与门禁判断。
 - **归档判据不可协商**：版本归档要求该版本**全部阶段 done** 且**无 blocking open REV**，没有 force 覆盖。归档由 CLI 执行，调度侧只提示不代劳。
 - **不主动读归档**：常规调度不要读 \`.openfeel/flow-archive/**\`（防上下文污染）；需要历史时用 \`feel_archive action=show\`。
 
+## 派发契约（v1.5.3）
+- 派发子 agent 时用 \`feel_next\` 返回的 \`dispatch\` 模板：goal / context / boundaries / returnFormat。
+- 子 agent **只读派发 prompt 与指定文件**；禁读 \`dev_last*\`、\`dev/current.md\`、\`status.md\`、\`flow.json\`。
+- 返回 **≤10 行**（结论 / 改动文件 / 验证 / 阻塞）；不贴全文 diff、日志或大段代码；超标内容留在子 agent，不进入主会话。
+
 ## 流程入口（v1.5.2）
 - **先 \`feel_status\`**：任何会产出仓库文件（含 \`docs/research/**\`、方案、计划）或需要多步调查/实现的任务，先读状态；无活跃阶段 → \`feel_req add\` → \`claim\` → \`feel_stage add\`，再开始。
 - **不得以「调研 / 只读」为由跳过阶段**：纯只读问答可直接回答；研究/方案产物写入门禁要求活跃阶段（\`docs/research/**\` 无阶段会被拒）。
@@ -150,6 +155,7 @@ Feel（你）只做编排、决策与门禁判断。
 - **只有 Feel 写状态**：\`dev_last*\`、\`dev/current.md\`、\`status.md\`、\`flow.json\` 只由 Feel 更新；**子 agent 一律不读不写**（上下文由派发 prompt / 交接文档提供）。
 - **日志不强制**：不写流水账；\`flow.json.log\` 由 CLI 自动维护（仅保留最近 200 条）。跨会话信息用一条 ≤5 行交接摘要。
 - **更新节点**：开始 / 转折 / 结束，或 \`statusSync.due=true\`（默认 30 分钟）时更新一次交接摘要，随后运行 \`openfeel dev sync\`（CLI 在节点/到期时也会自动同步）。
+- **恢复**：新会话先看 \`feel_status.recovery\`（lastTransition / handoff / nextAction）；需要细节再读当前阶段的 plan/op，**不要**启动即读 \`dev_last\` 全文。
 
 ## 三种工作流模式
 - \`full\`：plan → plan_review → scheme → exec → review → test → archive，六道关全走。
@@ -206,6 +212,11 @@ planner / schemer / executor / reviewer / feel-tester / archiver. **The authorit
 - **Archive criteria are not negotiable**: a version archive requires every stage of that version to be \`done\` AND no blocking open REV; there is no force override. The CLI performs the archive; you only prompt.
 - **Do not read archives during normal scheduling**: avoid \`.openfeel/flow-archive/**\`; use \`feel_archive action=show\` on demand.
 
+## Dispatch contract (v1.5.3)
+- When dispatching a subagent, use the \`dispatch\` template returned by \`feel_next\`: goal / context / boundaries / returnFormat.
+- Subagents read **only the dispatch prompt and the listed files**; never \`dev_last*\`, \`dev/current.md\`, \`status.md\`, \`flow.json\`.
+- Return **<=10 lines** (conclusion / changed files / verification / blockers); no full diffs, logs or large code blocks — keep them in the subagent.
+
 ## Workflow entry (v1.5.2)
 - **Call \`feel_status\` first**: any task that may produce repo files (including \`docs/research/**\`, proposals, plans) or needs multi-step investigation/implementation must read state first; with no active stage → \`feel_req add\` → \`claim\` → \`feel_stage add\`, then start.
 - **Never skip the stage under the pretext of "research / read-only"**: pure read-only Q&A may answer directly; research/proposal artifacts require an active stage (\`docs/research/**\` writes are rejected without one).
@@ -215,6 +226,7 @@ planner / schemer / executor / reviewer / feel-tester / archiver. **The authorit
 - **Only Feel writes state**: \`dev_last*\`, \`dev/current.md\`, \`status.md\`, \`flow.json\` are updated by Feel only; **subagents never read or write them** (context comes from the dispatch prompt / handoff docs).
 - **No mandatory logs**: do not keep a per-step diary; \`flow.json.log\` is maintained by the CLI (last 200 entries only). For cross-session info, write a <=5-line handoff summary.
 - **Update nodes**: start / turning point / end, or when \`statusSync.due=true\` (default 30 min) — update the handoff summary once, then run \`openfeel dev sync\` (the CLI also auto-syncs on nodes/expiry).
+- **Recovery**: at session start read \`feel_status.recovery\` (lastTransition / handoff / nextAction); read the stage's plan/op only for details — do **not** load the whole \`dev_last\` at startup.
 
 ## The three workflow modes
 - \`full\`: plan → plan_review → scheme → exec → review → test → archive (all six gates).

package/dsh/lib/tools/index.js

@@ -14,6 +14,8 @@
 import { FeelError } from '../adapters/cli.js';
 import { legalNextPhases, planNextStep, readSnapshot } from '../adapters/dashboard.js';
 import { readStatusSync } from '../adapters/dev-status.js';
+import { buildDispatchTemplate } from '../adapters/dispatch.js';
+import { readRecovery } from '../adapters/recovery.js';
 import { computeWorkflowGate } from '../adapters/workflow-gate.js';
 import { resolveWorkspace } from '../adapters/workspace.js';
 import {
@@ -156,11 +158,14 @@ export function createTools(context) {
         snapshot.project.root = resolved.cwd;
         snapshot.statusSync = readStatusSync(resolved.cwd);
         snapshot.workflowGate = computeWorkflowGate(snapshot);
+        snapshot.recovery = readRecovery(resolved.cwd);
+        snapshot.recovery.nextAction = snapshot.focus.suggestedCommand ?? null;
         const focus = snapshot.focus;
         const gateWarning = snapshot.workflowGate.required ? '⚠ 无活跃阶段：非只读任务先 feel_status→建阶段。' : '';
+        const staleWarning = snapshot.stale ? '⚠ 快照为降级（flow next 缺失），以 flow status 为准。' : '';
         return {
           data: snapshot,
-          summary: `${gateWarning}pipeline=${snapshot.pipeline.phase || '(空)'} 活跃阶段=${focus.stage || '(无)'} phase=${focus.phase || '(空)'} mode=${snapshot.mode.current}(${snapshot.mode.source}) 负责=${focus.responsibleAgent} 可推进到=[${(focus.legalNextPhases ?? []).join(', ') || '无'}]`,
+          summary: `${staleWarning}${gateWarning}pipeline=${snapshot.pipeline.phase || '(空)'} 活跃阶段=${focus.stage || '(无)'} phase=${focus.phase || '(空)'} mode=${snapshot.mode.current}(${snapshot.mode.source}) 负责=${focus.responsibleAgent} 可推进到=[${(focus.legalNextPhases ?? []).join(', ') || '无'}]`,
           next: focus.phase === 'done' || focus.phase === ''
             ? null
             : { tool: 'feel_next', arguments: {}, why: '获取「下一步该谁做」的明确建议。' },
@@ -189,11 +194,21 @@ export function createTools(context) {
         snapshot.project.root = resolved.cwd;
         snapshot.statusSync = readStatusSync(resolved.cwd);
         snapshot.workflowGate = computeWorkflowGate(snapshot);
+        snapshot.recovery = readRecovery(resolved.cwd);
         const plan = planNextStep(snapshot);
         plan.workflowGate = snapshot.workflowGate;
+        snapshot.recovery.nextAction = plan.suggestedCommand ?? null;
+        plan.recovery = snapshot.recovery;
+        plan.dispatch = buildDispatchTemplate(snapshot);
         if (plan.workflowGate.required) {
           plan.summary = `⚠ ${plan.workflowGate.message} ${plan.summary}`;
         }
+        if (snapshot.stale) {
+          plan.summary = `⚠ 快照为降级（flow next 缺失），以 flow status 为准。 ${plan.summary}`;
+        }
+        plan.revision = snapshot.revision ?? null;
+        plan.snapshotAt = snapshot.snapshotAt ?? null;
+        plan.stale = snapshot.stale === true;
         return {
           data: plan,
           summary: plan.summary,

package/dsh/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openfeel-dsh",
-  "version": "1.5.2",
+  "version": "1.5.4",
   "description": "OpenFeel × DSH — Feel 模式适配器：把 OpenFeel 的流水线、需求分发、版本归档与知识库接入 DeepSeek Harness",
   "type": "module",
   "private": true,
@@ -32,7 +32,7 @@
   },
   "openfeel": {
     "adapter": "dsh",
-    "requiresCli": ">=1.5.2"
+    "requiresCli": ">=1.5.4"
   },
   "keywords": [
     "openfeel",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openfeel",
-  "version": "1.5.2",
+  "version": "1.5.4",
   "description": "AI Agent 开发流程治理 CLI 工具",
   "type": "module",
   "private": false,