metame-cli 1.4.34 → 1.5.1

package/scripts/distill.js

@@ -3,7 +3,7 @@
 /**
  * MetaMe Passive Distiller
  *
- * Reads raw signal buffer, calls Claude (haiku, non-interactive)
+ * Reads raw signal buffer, calls Claude (configured distill model, non-interactive)
  * to extract persistent preferences/identity, merges into profile.
  *
  * Runs automatically before each MetaMe session launch.
@@ -15,11 +15,14 @@ const os = require('os');
 const { callHaiku, buildDistillEnv } = require('./providers');
 
 const HOME = os.homedir();
+const METAME_DIR = path.join(HOME, '.metame');
 const BUFFER_FILE = path.join(HOME, '.metame', 'raw_signals.jsonl');
 const BRAIN_FILE = path.join(HOME, '.claude_profile.yaml');
 const LOCK_FILE = path.join(HOME, '.metame', 'distill.lock');
+const MEMORY_DIR = path.join(METAME_DIR, 'memory');
+const POSTMORTEM_DIR = path.join(MEMORY_DIR, 'postmortems');
 
-const { hasKey, isLocked, getTier, getWritableKeysForPrompt, estimateTokens, TOKEN_BUDGET } = require('./schema');
+const { hasKey, isLocked, getTier, getDefinition, getWritableKeysForPrompt, estimateTokens, TOKEN_BUDGET } = require('./schema');
 const { loadPending, savePending, upsertPending, getPromotable, removePromoted, expireStale } = require('./pending-traits');
 const { writeBrainFileSafe, normalizeProjectPath, deriveProjectInfo } = require('./utils');
 
@@ -37,6 +40,248 @@ try {
   distillEnv = buildDistillEnv();
 } catch { /* providers not configured — use defaults */ }
 
+const COMPETENCE_SCORE = {
+  beginner: 1,
+  intermediate: 2,
+  expert: 3,
+};
+
+function normalizeCompetenceLevel(level) {
+  const v = String(level || '').trim().toLowerCase();
+  if (v === 'beginner' || v === 'intermediate' || v === 'expert') return v;
+  return null;
+}
+
+function normalizeDomainName(domain) {
+  const raw = String(domain || '').trim();
+  if (!raw) return '';
+  return raw.replace(/\s+/g, ' ').slice(0, 40);
+}
+
+function mergeCompetenceMap(currentMap, competenceSignals) {
+  const next = {
+    ...(currentMap && typeof currentMap === 'object' && !Array.isArray(currentMap) ? currentMap : {}),
+  };
+  const signals = Array.isArray(competenceSignals) ? competenceSignals : [];
+  let changed = false;
+
+  for (const signal of signals) {
+    const domain = normalizeDomainName(signal && signal.domain);
+    const level = normalizeCompetenceLevel(signal && signal.level);
+    if (!domain || !level) continue;
+
+    const oldLevel = normalizeCompetenceLevel(next[domain]);
+    if (!oldLevel) {
+      next[domain] = level;
+      changed = true;
+      continue;
+    }
+
+    const oldScore = COMPETENCE_SCORE[oldLevel] || 0;
+    const newScore = COMPETENCE_SCORE[level] || 0;
+    if (newScore >= oldScore) {
+      if (newScore > oldScore) {
+        next[domain] = level;
+        changed = true;
+      }
+      continue;
+    }
+
+    // Downgrade is only allowed with explicit downgrade evidence.
+    const downgradeEvidence = String(signal && signal.downgrade_evidence ? signal.downgrade_evidence : '').trim();
+    if (downgradeEvidence) {
+      next[domain] = level;
+      changed = true;
+    }
+  }
+
+  const entries = Object.entries(next);
+  if (entries.length <= 20) return { map: next, changed };
+
+  // Keep top-20 by level score to avoid unbounded growth.
+  entries.sort((a, b) => (COMPETENCE_SCORE[b[1]] || 0) - (COMPETENCE_SCORE[a[1]] || 0));
+  const compact = Object.fromEntries(entries.slice(0, 20));
+  return { map: compact, changed: true };
+}
+
+function sanitizeSlug(input, fallback = 'session') {
+  const v = String(input || '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9\u4e00-\u9fff_-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+  if (!v) return fallback;
+  return v.slice(0, 48);
+}
+
+function stripMd(text) {
+  return String(text || '').replace(/[#*_`>\[\]\(\)]/g, ' ').replace(/\s+/g, ' ').trim();
+}
+
+function appendPostmortemSkillSignal(skillName, skeleton, reasons, filePath) {
+  let skillEvolution = null;
+  try { skillEvolution = require('./skill-evolution'); } catch { /* optional */ }
+  if (!skillEvolution || typeof skillEvolution.appendSkillSignal !== 'function') return;
+  const name = String(skillName || '').trim();
+  if (!name) return;
+  try {
+    skillEvolution.appendSkillSignal({
+      ts: new Date().toISOString(),
+      type: 'postmortem_lesson',
+      prompt: skeleton && skeleton.intent ? skeleton.intent : '',
+      output: `postmortem:${name}`,
+      error: null,
+      skills_invoked: [name],
+      has_tool_failure: Number(skeleton && skeleton.tool_error_count) > 0,
+      tool_usage: [],
+      files_modified: [],
+      cwd: skeleton && skeleton.project_path ? skeleton.project_path : '',
+      metadata: {
+        source: 'distill-postmortem',
+        reasons,
+        postmortem_file: filePath,
+      },
+    });
+  } catch { /* non-fatal */ }
+}
+
+async function maybeGeneratePostmortemArtifact(skeleton, sessionPath) {
+  if (!sessionAnalytics || !skeleton || !sessionPath) return null;
+  const detector = sessionAnalytics.detectSignificantSession;
+  if (typeof detector !== 'function') return null;
+
+  const sig = detector(skeleton);
+  if (!sig || !sig.significant) return null;
+
+  let evidence = null;
+  try {
+    if (typeof sessionAnalytics.extractEvidence === 'function') {
+      evidence = sessionAnalytics.extractEvidence(sessionPath, 3200);
+    }
+  } catch { /* non-fatal */ }
+
+  const promptInput = JSON.stringify({
+    skeleton: {
+      session_id: skeleton.session_id,
+      duration_min: skeleton.duration_min,
+      tool_error_count: skeleton.tool_error_count,
+      retry_sequences: skeleton.retry_sequences,
+      git_diff_lines: skeleton.git_diff_lines,
+      error_recovered: skeleton.error_recovered,
+      intent: skeleton.intent,
+      project: skeleton.project,
+      project_id: skeleton.project_id,
+    },
+    reasons: sig.reasons,
+    evidence,
+  }, null, 2).slice(0, 5200);
+
+  const pmPrompt = `你是工程复盘助手。根据会话骨架和证据生成一份简洁 postmortem。
+
+输入(JSON):
+${promptInput}
+
+输出 JSON：
+{
+  "title":"简短标题",
+  "problem":"遇到的问题（1句）",
+  "root_cause":"根因（1句）",
+  "fix":"修复方案（1句）",
+  "lesson":"可复用教训（1句）",
+  "skill":"可选，若明显涉及某技能则写 skill 名，否则空字符串"
+}
+
+规则：
+- 只基于输入，不要虚构
+- 每个字段 20-180 字
+- 只输出 JSON`;
+
+  let raw = '';
+  try {
+    raw = await callHaiku(pmPrompt, distillEnv, 60000);
+  } catch {
+    return null;
+  }
+
+  let parsed = null;
+  try {
+    const cleaned = String(raw).replace(/```json\n?/g, '').replace(/```\n?/g, '').trim();
+    parsed = JSON.parse(cleaned);
+  } catch {
+    return null;
+  }
+
+  const title = String(parsed && parsed.title ? parsed.title : '').trim();
+  const problem = String(parsed && parsed.problem ? parsed.problem : '').trim();
+  const rootCause = String(parsed && parsed.root_cause ? parsed.root_cause : '').trim();
+  const fix = String(parsed && parsed.fix ? parsed.fix : '').trim();
+  const lesson = String(parsed && parsed.lesson ? parsed.lesson : '').trim();
+  if (!title || !problem || !rootCause || !fix || !lesson) return null;
+
+  fs.mkdirSync(POSTMORTEM_DIR, { recursive: true });
+  const day = new Date().toISOString().slice(0, 10);
+  const topicSlug = sanitizeSlug(skeleton.intent || title, `session-${String(skeleton.session_id || '').slice(0, 8)}`);
+  const filePath = path.join(POSTMORTEM_DIR, `${day}-${topicSlug}.md`);
+  const markdown = [
+    `# ${title}`,
+    '',
+    `- date: ${day}`,
+    `- session_id: ${skeleton.session_id || 'unknown'}`,
+    `- project: ${skeleton.project || 'unknown'}`,
+    `- project_id: ${skeleton.project_id || 'unknown'}`,
+    `- reasons: ${(sig.reasons || []).join(', ') || 'n/a'}`,
+    '',
+    '## 问题',
+    problem,
+    '',
+    '## 根因',
+    rootCause,
+    '',
+    '## 解法',
+    fix,
+    '',
+    '## 教训',
+    lesson,
+    '',
+  ].join('\n');
+  fs.writeFileSync(filePath, markdown, 'utf8');
+
+  let memory = null;
+  try {
+    memory = require('./memory');
+  } catch { /* optional */ }
+
+  if (memory && typeof memory.saveFacts === 'function') {
+    const value = stripMd(`问题:${problem} 根因:${rootCause} 解法:${fix} 教训:${lesson}`).slice(0, 280);
+    if (value.length >= 20) {
+      const entityProject = sanitizeSlug(skeleton.project || 'unknown', 'unknown');
+      const fallbackScope = skeleton.session_id
+        ? `sess_${String(skeleton.session_id).replace(/[^a-zA-Z0-9_-]/g, '').slice(0, 24)}`
+        : null;
+      try {
+        memory.saveFacts(
+          skeleton.session_id || `pm-${Date.now()}`,
+          skeleton.project || 'unknown',
+          [{
+            entity: `postmortem.${entityProject}`,
+            relation: 'bug_lesson',
+            value,
+            confidence: 'high',
+            tags: ['postmortem'],
+          }],
+          { scope: skeleton.project_id || fallbackScope }
+        );
+      } catch { /* non-fatal */ }
+    }
+    try { memory.close(); } catch { /* non-fatal */ }
+  }
+
+  appendPostmortemSkillSignal(parsed && parsed.skill, skeleton, sig.reasons || [], filePath);
+
+  return { file: filePath, reasons: sig.reasons || [] };
+}
+
 function selectSignalBatch(lines) {
   const parsed = [];
   for (const rawLine of lines) {
@@ -176,6 +421,7 @@ async function distill() {
     let sessionContext = '';
     let skeleton = null;
     let sessionSummary = null;
+    let targetSessionPath = null;
     if (sessionAnalytics) {
       try {
         let targetSession = null;
@@ -189,6 +435,7 @@ async function distill() {
         }
         if (targetSession) {
           skeleton = sessionAnalytics.extractSkeleton(targetSession.path);
+          targetSessionPath = targetSession.path;
           sessionContext = sessionAnalytics.formatForPrompt(skeleton);
           // For long sessions, extract pivot points
           sessionSummary = sessionAnalytics.summarizeSession(skeleton, targetSession.path);
@@ -364,11 +611,16 @@ BEHAVIORAL ANALYSIS — _behavior block (always output, use null if insufficient
   friction: []                   # max 3 keywords describing pain points
   goal_alignment: aligned | partial | drifted | null
   drift_note: "max 30 char explanation" or null
+  competence_signals:            # optional, max 5
+    - domain: "领域名"
+      level: beginner | intermediate | expert
+      evidence: "触发证据"
+      downgrade_evidence: "只有在明确降级时填写，否则省略"
 ${sessionContext ? '\nHint: high tool_calls + routine messages → zone likely higher. If DECLARED_GOALS exist, assess goal_alignment.' : ''}
 OUTPUT — respond with ONLY a YAML code block. If nothing worth saving AND no behavior: respond with exactly NO_UPDATE.
 Do NOT repeat existing unchanged values.`;
 
-    // 6. Call Claude in print mode with haiku (+ provider env for relay support)
+    // 6. Call Claude in print mode with configured distill model (+ provider env for relay support)
     let result;
     try {
       result = await callHaiku(distillPrompt, distillEnv, 60000);
@@ -384,9 +636,23 @@ Do NOT repeat existing unchanged values.`;
 
     // 7. Parse result
     if (!result || result === 'NO_UPDATE') {
+      if (skeleton && sessionAnalytics) {
+        try { sessionAnalytics.markAnalyzed(skeleton.session_id); } catch { /* non-fatal */ }
+      }
       ackSignals = true;
       finalize();
-      return { updated: false, behavior: null, summary: `Analyzed ${signals.length} messages — no persistent insights found.` };
+      let postmortem = null;
+      try {
+        postmortem = await maybeGeneratePostmortemArtifact(skeleton, targetSessionPath);
+      } catch { /* non-fatal */ }
+      return {
+        updated: false,
+        behavior: null,
+        skeleton,
+        postmortem,
+        signalCount: signals.length,
+        summary: `Analyzed ${signals.length} messages — no persistent insights found.`,
+      };
     }
 
     // Extract YAML block from response — require explicit code block, no fallback
@@ -420,22 +686,13 @@ Do NOT repeat existing unchanged values.`;
 
       // Schema whitelist filter: drop any keys not in schema or locked
       const filtered = filterBySchema(updates);
-      if (Object.keys(filtered).length === 0 && !behavior) {
+      const extractedFieldCount = Object.keys(filtered).length;
+      if (extractedFieldCount === 0 && !behavior) {
         ackSignals = true;
         finalize();
         return { updated: false, behavior: null, summary: `Analyzed ${signals.length} messages — all extracted fields rejected by schema.` };
       }
 
-      // If only behavior detected but no profile updates
-      if (Object.keys(filtered).length === 0 && behavior) {
-        ackSignals = true;
-        finalize();
-        if (skeleton && sessionAnalytics) {
-          try { sessionAnalytics.markAnalyzed(skeleton.session_id); } catch { }
-        }
-        return { updated: false, behavior, skeleton, signalCount: signals.length, summary: `Analyzed ${signals.length} messages — behavior logged, no profile changes.` };
-      }
-
       const profile = yaml.load(fs.readFileSync(BRAIN_FILE, 'utf8')) || {};
 
       // Read raw content to find locked lines and comments
@@ -451,13 +708,44 @@ Do NOT repeat existing unchanged values.`;
       const merged = strategicMerge(profile, filtered, lockedKeys, pendingTraits, confidenceMap, sourceMap);
       savePending(pendingTraits);
 
+      // Merge competence signals into user_competence_map (upgrade by default).
+      const competenceSignals = Array.isArray(behavior && behavior.competence_signals)
+        ? behavior.competence_signals
+        : [];
+      const mergedCompetence = mergeCompetenceMap(merged.user_competence_map, competenceSignals);
+      if (mergedCompetence.changed) {
+        merged.user_competence_map = mergedCompetence.map;
+      }
+
+      if (extractedFieldCount === 0 && !mergedCompetence.changed) {
+        if (skeleton && sessionAnalytics) {
+          try { sessionAnalytics.markAnalyzed(skeleton.session_id); } catch { }
+        }
+        ackSignals = true;
+        finalize();
+        let postmortem = null;
+        try {
+          postmortem = await maybeGeneratePostmortemArtifact(skeleton, targetSessionPath);
+        } catch { /* non-fatal */ }
+        return {
+          updated: false,
+          behavior,
+          skeleton,
+          postmortem,
+          signalCount: signals.length,
+          summary: `Analyzed ${signals.length} messages — behavior logged, no profile changes.`,
+        };
+      }
+
       // Add distillation log entry (keep last 10, compact format)
       if (!merged.evolution) merged.evolution = {};
       if (!merged.evolution.auto_distill) merged.evolution.auto_distill = [];
+      const changedFields = Object.keys(filtered);
+      if (mergedCompetence.changed) changedFields.push('user_competence_map');
       merged.evolution.auto_distill.push({
         ts: new Date().toISOString(),
         signals: signals.length,
-        fields: Object.keys(filtered).join(', ')
+        fields: changedFields.join(', ')
       });
       // Cap at 10 entries
       if (merged.evolution.auto_distill.length > 10) {
@@ -507,13 +795,19 @@ Do NOT repeat existing unchanged values.`;
 
       ackSignals = true;
       finalize();
+      let postmortem = null;
+      try {
+        postmortem = await maybeGeneratePostmortemArtifact(skeleton, targetSessionPath);
+      } catch { /* non-fatal */ }
+      const absorbedCount = changedFields.length;
       return {
         updated: true,
         behavior,
         skeleton,
         sessionSummary,
+        postmortem,
         signalCount: signals.length,
-        summary: `${Object.keys(filtered).length} new trait${Object.keys(filtered).length > 1 ? 's' : ''} absorbed. (${tokens} tokens)`
+        summary: `${absorbedCount} new trait${absorbedCount > 1 ? 's' : ''} absorbed. (${tokens} tokens)`
       };
 
     } catch (err) {
@@ -1077,7 +1371,18 @@ If no clear patterns found: respond with exactly NO_PATTERNS`;
 }
 
 // Export for use in index.js
-module.exports = { distill, writeSessionLog, bootstrapSessionLog, detectPatterns };
+module.exports = {
+  distill,
+  writeSessionLog,
+  bootstrapSessionLog,
+  detectPatterns,
+  _private: {
+    mergeCompetenceMap,
+    normalizeCompetenceLevel,
+    normalizeDomainName,
+    sanitizeSlug,
+  },
+};
 
 // Also allow direct execution
 if (require.main === module) {
@@ -1104,5 +1409,9 @@ if (require.main === module) {
     } else {
       console.log(`💤 ${result.summary}`);
     }
+    // Report estimated token usage for daemon budget tracking
+    // Each callHaiku invocation ~2k-5k tokens; estimate from signal count + result size
+    const estTokens = Math.ceil(((result.signalCount || 1) * 500) + ((result.summary || '').length / 4));
+    console.log(`__TOKENS__:${estTokens}`);
   })();
 }

package/scripts/docs/agent-guide.md

@@ -16,6 +16,15 @@
 在手机端（飞书/Telegram），直接说即可，daemon 会自动处理：
 > 创建一个 Agent，目录是 ~/projects/my-bot
 
+引擎选择（手机端自然语言）：
+- 默认不写引擎时，使用 Claude（配置里不落 `engine` 字段）
+- 句子里带 `codex` 关键词时，自动写入 `engine: codex`
+
+示例：
+> 创建一个 codex agent，目录是 ~/projects/reviewer
+
+> 用 codex 建一个代码审查 agent，目录 ~/projects/pr-review
+
 在桌面 Claude Code 终端，需要手动操作：
 1. 创建项目目录和 CLAUDE.md（角色定义）
 2. 编辑 `~/.metame/daemon.yaml`，在 `projects` 下新增：
@@ -48,3 +57,6 @@
 ## 注意事项
 - 专属群（chat_agent_map 中的群）永远绑定同一个 Agent，不能通过昵称切换
 - 新群必须发 `/activate` 才能使用，未授权群会提示"此群未授权"
+- Codex 当前限制（MVP）：`/sessions` 列表暂只展示 Claude 本地会话，Codex 会话暂不可见
+- Codex 当前限制（MVP）：`/compact` 暂不支持，请继续在同一会话中对话
+- 需要定位脚本入口、升级步骤或文件落点时，先看 `~/.metame/docs/pointer-map.md`

package/scripts/docs/maintenance-manual.md

@@ -0,0 +1,155 @@
+# MetaMe 维护手册（Claude/Codex 双引擎）
+
+> 适用范围：`scripts/daemon.js` 后台 daemon 链路（飞书/Telegram 路由、会话执行、Agent 绑定）。
+
+## 1. 引擎路由规则
+
+### 手机端（daemon 生效）
+
+- 路由入口：`chat_agent_map -> project -> project.engine`
+- `project.engine` 可选值：`claude`（默认）/`codex`
+- 未配置 `engine` 时等价 `claude`
+
+示例：
+
+```yaml
+projects:
+  reviewer:
+    name: "Reviewer"
+    cwd: "~/AGI/MetaMe"
+    engine: codex
+
+feishu:
+  chat_agent_map:
+    "oc_xxx": "reviewer"
+```
+
+### 电脑端（CLI）
+
+- Claude 入口：`metame`（等价启动 Claude + MetaMe 初始化）
+- Codex 入口：`metame codex [args]`
+- 也可直接用原生命令：`claude` / `codex`
+
+## 2. Agent 创建与引擎写入
+
+- 默认创建 Agent：不写 `engine` 字段（保持兼容）
+- 创建语句中包含 `codex` 关键词：写入 `engine: codex`
+- 绑定语句包含 `codex` 时同样支持写入 `engine: codex`
+
+示例：
+
+- `创建一个 codex agent，目录是 ~/projects/reviewer`
+- `用 codex 建个代码审查 agent，目录 ~/projects/pr-review`
+
+## 3. 会话与执行规则
+
+- 引擎 runtime 工厂：`scripts/daemon-engine-runtime.js`
+- 会话执行入口：`scripts/daemon-claude-engine.js`（Claude/Codex 共用）
+- Session 回写：`patchSessionSerialized()` 串行化，避免 thread.started 竞态覆盖
+
+### Codex 会话策略
+
+- 首轮：`codex exec --json -`
+- 续轮：`codex exec resume <thread_id> --json -`
+- `resume` 失败自动重试：同一 `chatId` 在 10 分钟内最多 1 次
+- 收到新 `thread_id` 时自动迁移 session id
+
+## 4. 命令行为差异
+
+- `/stop`：引擎中性，按 `activeProcesses.killSignal` 停止
+- `/compact`：
+  - Claude 会话：正常压缩
+  - Codex 会话：返回“暂不支持，请继续同会话”
+- `/engine`：
+  - 查询当前默认引擎：`/engine`
+  - 切换默认引擎：`/engine claude` 或 `/engine codex`
+- `/distill-model`：
+  - 查询当前蒸馏模型：`/distill-model`
+  - 设置蒸馏模型：`/distill-model gpt-5.1-codex-mini`
+  - 也支持严格自然语言：`把蒸馏模型改成 5.1mini`
+- `/doctor`：
+  - 同时检查 Claude/Codex CLI 可用性
+  - 仅在“当前默认引擎对应 CLI 不可用”时判为故障
+  - 自定义 provider 下允许任意合法模型名（不再强制 sonnet/opus/haiku）
+
+## 5. Agent Soul 身份层
+
+- 集中存储：`~/.metame/agents/<agent_id>/`（soul.md、memory-snapshot.md、agent.yaml）
+- 项目视图：`<cwd>/SOUL.md`、`<cwd>/MEMORY.md` 是指向集中存储的链接
+- Claude：`@SOUL.md` 写入 CLAUDE.md 头部，CLI 每次 session 自动加载（引用式，改源文件立即生效）
+- Codex：每次新 session 合并 CLAUDE.md + SOUL.md 写入 `<cwd>/AGENTS.md`（快照式，需新 session 生效）
+- 老项目迁移：`/agent soul repair` 幂等补建 soul 层
+- 注意：Windows 上 copy 模式的 SOUL.md 不会自动同步源文件变更，需 `/agent soul repair` 刷新
+
+## 6. 运行时文件与状态
+
+- 配置：`~/.metame/daemon.yaml`
+- daemon 状态：`~/.metame/daemon_state.json`
+- 活跃子进程：`~/.metame/active_agent_pids.json`
+- 热重载备份：`~/.metame/.last-good/`（daemon 稳定运行 60s 后自动备份）
+- 崩溃计数：`~/.metame/.crash-count`（连续 2 次快速崩溃触发自动恢复）
+
+## 7. 热重载安全机制（三层防护）
+
+1. **部署前预检**（`index.js`）：`node -c` 语法检查所有 `.js`，不通过则拒绝部署到 `~/.metame/`
+2. **重启前预检**（`daemon-runtime-lifecycle.js`）：daemon.js 变更触发重启前再次语法校验，不通过则阻止重启并通知 admin
+3. **崩溃循环自愈**：连续 2 次在 30s 内崩溃 → 自动从 `.last-good/` 恢复 → 通知 admin
+
+## 8. 常见故障排查
+
+### Codex 认证失败
+
+症状：返回 `AUTH_REQUIRED`
+
+处理：
+
+1. 执行 `codex login`
+2. 或配置 `OPENAI_API_KEY`
+3. 重新发送同一条消息
+
+### Codex 频率限制
+
+症状：返回 `RATE_LIMIT`
+
+处理：
+
+1. 等待限流窗口恢复
+2. 降低并发或切回 Claude 路由
+
+### 会话续接异常
+
+症状：Codex `resume` 报错后反复失败
+
+处理：
+
+1. daemon 已自动做一次 fresh `exec` 重试
+2. 若仍失败，手动 `/new` 新开会话
+3. 检查 `~/.metame/active_agent_pids.json` 是否残留异常进程
+
+## 9. 双平台/双引擎维护矩阵
+
+### 统一维护（改一处即可）
+- agent-layer.js / daemon-agent-tools.js / daemon-agent-commands.js / daemon-user-acl.js
+- ENGINE_MODEL_CONFIG（daemon-engine-runtime.js 集中管理）
+- daemon-runtime-lifecycle.js 的语法检查和备份机制
+
+### 需分别维护（有平台/引擎特殊分支）
+
+| 模块 | 差异点 | 注意事项 |
+|------|--------|----------|
+| platform.js `killProcessTree` | POSIX: `kill(-pid)` / Windows: `taskkill /T /F` | 所有进程杀死调用点应统一使用此函数 |
+| daemon-engine-runtime.js `resolveBinary` | macOS: `which` + homebrew / Windows: `where` + `.cmd` | 新增引擎需两端测试 |
+| daemon-engine-runtime.js `buildArgs` | Claude: `--resume`/`--continue` / Codex: `exec resume`，Codex resume 不能传权限 flag | 改参数结构时两端验证 |
+| daemon-claude-engine.js Soul 注入 | Claude: `@SOUL.md` import（引用式）/ Codex: AGENTS.md 合并写入（快照式） | 改 soul 加载方式需两端测试 |
+| agent-layer.js `createLinkOrMirror` | macOS: symlink / Windows: hardlink → copy 降级 | copy 模式不会自动同步源文件变更 |
+| daemon.js `spawnReplacementDaemon` | POSIX: `detached: true` / Windows: `detached: false` | 改 spawn 参数时注意平台分支 |
+| NL Mac 控制（command-router） | macOS only，`process.platform === 'darwin'` 守卫 | Windows 天然跳过 |
+
+## 10. 变更后维护动作
+
+1. `npm test`
+2. `npm run sync:plugin`
+3. 更新文档：
+   - `scripts/docs/pointer-map.md`
+   - `README.md`
+   - `README中文版.md`