openfeel 1.3.2 → 1.3.4

package/dsh/lib/guard.js

@@ -14,8 +14,8 @@
  * @module openfeel-dsh/guard
  */
 
-import { readFileSync, statSync } from 'node:fs';
-import { basename, join, resolve } from 'node:path';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { basename, extname, join, resolve } from 'node:path';
 
 import { isProjectWorkspace, OPENFEEL_DIR } from './adapters/workspace.js';
 
@@ -40,6 +40,35 @@ export function normalizeForComparison(value, platform = process.platform) {
   return platform === 'win32' || platform === 'darwin' ? value.toLowerCase() : value;
 }
 
+/** 文档/笔记类扩展名（写门禁按产物类型分层：doc/note 不绑相位）。 */
+export const DOC_EXTENSIONS = Object.freeze(['.md', '.mdx', '.txt', '.rst', '.adoc']);
+
+/**
+ * 是否为文档/笔记类目标（P0-4）：扩展名命中，或位于**工作区根级 `docs/`** 下。
+ * v1.3.3 复核：`docs` 必须直接位于会话工作区下（`src/docs/x.ts` 不算文档，防源码借名绕过相位门）。
+ * 仅用于「放行 doc/note」；源代码仍按 `exec_running` 严格判定。
+ * @param {string} absolute 已归一化绝对路径
+ * @param {string} cwd 已归一化工作区
+ * @returns {boolean}
+ */
+function isDocPath(absolute, cwd) {
+  if (DOC_EXTENSIONS.includes(extname(absolute).toLowerCase())) return true;
+  const docsRoot = normalizeTarget(cwd, 'docs');
+  return absolute === docsRoot
+    || absolute.startsWith(`${docsRoot}\\`)
+    || absolute.startsWith(`${docsRoot}/`);
+}
+
+/**
+ * 是否位于工作区内（bootstrap 例外边界；防 `..`/绝对路径写出工作区）。
+ * @param {string} absolute 已归一化绝对路径
+ * @param {string} cwd 已归一化工作区
+ * @returns {boolean}
+ */
+function isUnderWorkspace(absolute, cwd) {
+  return absolute === cwd || absolute.startsWith(`${cwd}\\`) || absolute.startsWith(`${cwd}/`);
+}
+
 /** flow.json 读取缓存（path → { mtimeMs, size, value }）。 */
 const flowCache = new Map();
 
@@ -120,22 +149,32 @@ function extractPatchText(args) {
 }
 
 /**
- * 解析 apply_patch 的全部目标路径。
+ * 解析 apply_patch 的全部目标路径与变更类型。
  *
  * 只认 patch 头，避免正文里出现 `.openfeel/` 被误判。支持：
  * - `*** Update File:`, `*** Add File:`, `*** Delete File:`
  * - `*** Move to:`（要求同块 `*** Update File:` 源，否则拒绝）
  * - `--- a/path`, `+++ b/path`；忽略 `/dev/null`
  *
+ * 返回 `entries`（路径 + kind）供 bootstrap 例外判定「是否纯新增」：
+ * kind ∈ `add | update | delete | move`；同一路径出现多种 kind 时从严记 `update`。
+ *
  * @param {string} patch
- * @returns {{ ok: true, paths: string[] } | { ok: false, reason: string }}
+ * @returns {{ ok: true, paths: string[], entries: Array<{ path: string, kind: string }> } | { ok: false, reason: string }}
  */
 export function parsePatchTargets(patch) {
   const paths = [];
+  const kinds = new Map();
   const seen = new Set();
-  const add = (raw) => {
+  const add = (raw, kind) => {
     const value = cleanPatchPath(raw);
     if (value === '' || value === '/dev/null') return;
+    const prev = kinds.get(value);
+    if (prev === undefined) {
+      kinds.set(value, kind);
+    } else if (prev !== kind) {
+      kinds.set(value, 'update'); // 同路径混合 kind → 从严（bootstrap 例外不成立）
+    }
     if (seen.has(value)) return;
     seen.add(value);
     paths.push(value);
@@ -147,19 +186,19 @@ export function parsePatchTargets(patch) {
     const update = /^\*\*\* Update File:\s*(.+?)\s*$/.exec(line);
     if (update !== null) {
       currentBlock = 'update';
-      add(update[1]);
+      add(update[1], 'update');
       continue;
     }
     const addFile = /^\*\*\* Add File:\s*(.+?)\s*$/.exec(line);
     if (addFile !== null) {
       currentBlock = 'add';
-      add(addFile[1]);
+      add(addFile[1], 'add');
       continue;
     }
     const deleteFile = /^\*\*\* Delete File:\s*(.+?)\s*$/.exec(line);
     if (deleteFile !== null) {
       currentBlock = 'delete';
-      add(deleteFile[1]);
+      add(deleteFile[1], 'delete');
       continue;
     }
     const move = /^\*\*\* Move to:\s*(.+?)\s*$/.exec(line);
@@ -167,7 +206,7 @@ export function parsePatchTargets(patch) {
       if (currentBlock !== 'update') {
         return { ok: false, reason: '*** Move to: 缺少同块 *** Update File: 源路径' };
       }
-      add(move[1]);
+      add(move[1], 'move');
       continue;
     }
     if (/^\*\*\* (?:Begin|End) Patch/.test(line)) {
@@ -175,13 +214,13 @@ export function parsePatchTargets(patch) {
       continue;
     }
     const diff = /^(?:---|\+\+\+) [ab]\/(.+?)\s*$/.exec(line);
-    if (diff !== null) add(diff[1]);
+    if (diff !== null) add(diff[1], 'update');
   }
 
   if (paths.length === 0) {
     return { ok: false, reason: '无法从 patch 头确定目标路径' };
   }
-  return { ok: true, paths };
+  return { ok: true, paths, entries: paths.map((path) => ({ path, kind: kinds.get(path) })) };
 }
 
 /**
@@ -253,6 +292,8 @@ export function createOpenFeelGuard(options = {}) {
   const fallbackCwd = typeof options.cwd === 'string' && options.cwd !== '' ? options.cwd : undefined;
 
   const t = (zh, en) => (english ? en : zh);
+  /** bootstrap 例外提示去重（按工作区路径）。 */
+  const bootstrapHinted = new Set();
 
   if (enforce === 'off') {
     // 完全关闭：连 flow.json/status.md 也不拦。
@@ -270,6 +311,7 @@ export function createOpenFeelGuard(options = {}) {
     const normalizedCwd = normalizeForComparison(resolvedCwd);
 
     let rawTargets;
+    let patchEntries = null;
     if (name === 'apply_patch') {
       const patch = extractPatchText(execution?.arguments);
       if (patch === undefined) {
@@ -286,6 +328,7 @@ export function createOpenFeelGuard(options = {}) {
         );
       }
       rawTargets = parsed.paths;
+      patchEntries = parsed.entries;
     } else {
       rawTargets = extractArgumentPaths(execution?.arguments);
       if (rawTargets.length === 0) {
@@ -297,6 +340,7 @@ export function createOpenFeelGuard(options = {}) {
     }
 
     const targets = rawTargets.map((target) => normalizeTarget(resolvedCwd, target));
+    const allDoc = targets.every((target) => isDocPath(target, normalizedCwd));
 
     // 受保护路径：guard 启用时始终拒绝（enforce=off 已提前返回）。
     if (targets.some((target) => isProtectedPath(target, normalizedCwd))) {
@@ -309,6 +353,25 @@ export function createOpenFeelGuard(options = {}) {
     const initialized = isProjectWorkspace(resolvedCwd);
     if (!initialized) {
       if (enforce === 'always') {
+        // P0-1 bootstrap 例外：空工作区 + 全部为「新增文件」→ 放行（最高风险等级不成立）。
+        // apply_patch 额外要求全部 block 为 `*** Add File:`（Update/Delete/Move/混合一律从严）。
+        // `.openfeel/**` 不适用：流程产物仍要求先 init（B8）。
+        const allNew = targets.every((target) => !existsSync(target));
+        const anyInternal = targets.some((target) => isUnderOpenFeel(target, normalizedCwd));
+        const allInside = targets.every((target) => isUnderWorkspace(target, normalizedCwd));
+        const addOnly = patchEntries === null || patchEntries.every((entry) => entry.kind === 'add');
+        if (allNew && addOnly && !anyInternal && allInside) {
+          if (!bootstrapHinted.has(normalizedCwd)) {
+            bootstrapHinted.add(normalizedCwd);
+            process.stderr.write(
+              `${t(
+                'OpenFeel 写入门禁：[bootstrap] 工作区尚未初始化，已放行本次新增文件；建议稍后运行 `openfeel init` 补账本。',
+                'OpenFeel write guard: [bootstrap] workspace not initialized; this new-file write was allowed. Run `openfeel init` later to record it.',
+              )}\n`,
+            );
+          }
+          return undefined;
+        }
         return t(
           'OpenFeel 写入门禁：当前工作区尚未初始化 OpenFeel（无 `.openfeel/`）。请先运行 `openfeel init` 并建立需求/阶段；或让用户把 profile 的 `enforce` 改为 `project` / `off`。',
           'OpenFeel write guard: this workspace is not OpenFeel-initialized (no `.openfeel/`). Run `openfeel init` and create a requirement/stage first; or ask the user to set `enforce` to `project` / `off`.',
@@ -331,6 +394,8 @@ export function createOpenFeelGuard(options = {}) {
     const active = activeStages(flow.value);
     if (active.length === 0) {
       if (allowGeneral && hasGeneralRequirement(flow.value)) return undefined;
+      // P0-4：doc/note 类产物不要求活跃阶段（收口后仍可写文档）；混合目标从严。
+      if (allDoc) return undefined;
       return t(
         'OpenFeel 写入门禁：当前无活跃阶段，不能修改源码/文档。请先 feel_req add → claim → feel_stage add 建立阶段。',
         'OpenFeel write guard: no active stage, so source/docs are read-only. Create a stage via feel_req add → claim → feel_stage add.',
@@ -338,6 +403,8 @@ export function createOpenFeelGuard(options = {}) {
     }
 
     if (active.some((stage) => stage.phase === 'exec_running')) return undefined;
+    // P0-4：非 exec 相位仍允许 doc/note（研究记录、设计文档等）；代码仍严格。
+    if (allDoc) return undefined;
 
     const summary = active
       .map((stage) => `${stage.id ?? '(unknown)'}=${stage.phase ?? '(unknown)'}`)

package/dsh/lib/index.js

@@ -22,8 +22,13 @@
  * @module openfeel-dsh
  */
 
+import { readFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
 import { FeelCli } from './adapters/cli.js';
 import { resolveWorkspace } from './adapters/workspace.js';
+import { writeHostMarker } from './adapters/host-state.js';
 import { createOpenFeelGuard } from './guard.js';
 import { createFeelCommandHandler } from './surface/command.js';
 import { FEEL_PROMPT_NAME, FEEL_PROMPT_ORDER, renderBootstrapPrompt, renderFeelPrompt } from './surface/prompt.js';
@@ -110,6 +115,22 @@ function currentAgent(ctx) {
  */
 export function apply(ctx, rawConfig) {
   const config = normalizeConfig(rawConfig);
+
+  // v1.3.4：记录「本宿主实际加载的适配器指纹」，供 `openfeel setup --check` 区分
+  // 「文件旧」与「文件已新但宿主未重启」。best-effort：失败不影响挂载。
+  try {
+    const adapterRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+    let adapterVersion = '0.0.0';
+    try {
+      const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf-8'));
+      if (typeof pkg.version === 'string' && pkg.version !== '') adapterVersion = pkg.version;
+    } catch {
+      /* package.json 不可读时保持占位版本 */
+    }
+    writeHostMarker({ adapterRoot, version: adapterVersion });
+  } catch {
+    /* 标记写入失败 → CLI check 会提示 restart-required，可操作，不阻塞 */
+  }
   const log = typeof ctx.logger === 'function'
     ? ctx.logger('openfeel-dsh')
     : {

package/dsh/lib/tools/index.js

@@ -207,9 +207,9 @@ export function createTools(context) {
         '操作。',
         { required: true },
       ),
-      stage: string('阶段 ID（advance/retry 必需；phases/mode 可选用于按阶段派生模式）。'),
+      stage: string('阶段 ID（advance/retry 必需；review_add 与 op 二选一；phases/mode 可选用于按阶段派生模式）。'),
       to: stringEnum(PHASES, 'advance 的目标相位。'),
-      op: string('操作 ID（如 v1.2.1-stage-93.op-001）。'),
+      op: string('操作 ID（如 v1.2.1-stage-93.op-001）；review_add 与 stage 二选一。'),
       force: boolean('advance 时跳过相位合法性与跳跃检查（不能绕过 blocking REV 门）。'),
       dry_run: boolean('仅校验/预览，不写盘。'),
       review_tier: stringEnum(TIERS, '审查档位：full=零裁剪 / lean=裁 scheme_review / skip=再裁 plan_review。缺省不裁剪（=full）。'),
@@ -294,7 +294,12 @@ export function createTools(context) {
         }
         case 'review_add': {
           const argv = ['flow', 'review', 'add'];
-          pushOption(argv, '--op', args.op);
+          // v1.3.4：op / stage 二选一透传（fast 无 op 场景必须能挂阶段级 REV）
+          if (!args.op && !args.stage) {
+            throw new FeelError('review_add 需要 op 或 stage 之一', { kind: 'usage', code: 'FEEL_BAD_USAGE' });
+          }
+          if (args.op) pushOption(argv, '--op', args.op);
+          else pushOption(argv, '--stage', args.stage);
           pushOption(argv, '--title', requireArg(args, 'title', action));
           pushOption(argv, '--auto-fix', args.auto_fix);
           if (args.blocking !== undefined) argv.push('--blocking', args.blocking === true ? 'true' : 'false');

package/dsh/lib/tools/shared.js

@@ -188,26 +188,40 @@ export function toWireEnvelope(action, payload) {
 }
 
 /**
- * 安全序列化：处理循环引用与不可序列化值，永不抛错。
+ * 安全序列化：只对**真环**（祖先路径上出现过的对象）写 `[循环引用]`；
+ * 同一对象的**重复引用**（DAG，如 focus.deps 与 stages[i].deps 指向同一数组）正常复制（P1-2）。
+ * 兼处理 BigInt / 不可序列化值，永不抛错。
  * @param {unknown} value
  * @returns {string}
  */
 export function stringifySafe(value) {
   try {
-    /** @type {WeakSet<object>} */
-    const seen = new WeakSet();
-    return JSON.stringify(
-      value,
-      (_key, item) => {
-        if (typeof item === 'object' && item !== null) {
-          if (seen.has(item)) return '[循环引用]';
-          seen.add(item);
+    /**
+     * @param {unknown} item
+     * @param {WeakSet<object>} ancestors
+     * @returns {unknown}
+     */
+    const clone = (item, ancestors) => {
+      if (typeof item === 'bigint') return item.toString();
+      if (typeof item === 'function' || typeof item === 'symbol') return undefined;
+      if (typeof item !== 'object' || item === null) return item;
+      // 保留 Date / URL 等自带 toJSON 的语义（与 JSON.stringify 一致）
+      if (typeof item.toJSON === 'function') return item.toJSON();
+      if (ancestors.has(item)) return '[循环引用]';
+      ancestors.add(item);
+      let out;
+      if (Array.isArray(item)) {
+        out = item.map((entry) => clone(entry, ancestors));
+      } else {
+        out = {};
+        for (const [key, entry] of Object.entries(item)) {
+          out[key] = clone(entry, ancestors);
         }
-        if (typeof item === 'bigint') return item.toString();
-        return item;
-      },
-      2,
-    );
+      }
+      ancestors.delete(item);
+      return out;
+    };
+    return JSON.stringify(clone(value, new WeakSet()), null, 2);
   } catch {
     return String(value);
   }

package/dsh/package.json

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

package/package.json

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