ppxans-harness 2.4.0 → 3.2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ppxans-harness",
-  "version": "2.4.0",
-  "description": "PPXANS-Harness - 皮皮虾神经系 (ANS) + Harness 一体化智能体内核. 零运行时依赖纯Node. 自愈 + 自学习 + 五层记忆 + SHA-256 审计哈希链 + 多 Agent 军团 + 治理内核(deny-wins/熔断/seam) + 进化内核(Playbook/故障记忆) + 符号画布 + supervisor. Agent Nervous System harness in pure Node, zero runtime dependencies.",
+  "version": "3.2.0",
+  "description": "PPXANS-Harness - 皮皮虾神经系 (ANS) + Harness 一体化智能体内核. 零运行时依赖纯Node. 自愈 + 自学习 + 五层记忆 + SHA-256 审计哈希链 + 多 Agent 军团 + 治理内核(deny-wins/熔断/seam) + 进化内核(Playbook/故障记忆) + 符号画布 + supervisor. 自研底座: 仅 OpenAI 兼容 HTTP 直连, 无外部引擎依赖. Agent Nervous System harness in pure Node, zero runtime dependencies.",
   "type": "module",
   "license": "Apache-2.0",
   "author": "chen6896qqwee <chen6896qqwee@users.noreply.github.com>",
@@ -12,8 +12,10 @@
   "bin": {
     "ppx": "bin/ppx.js",
     "ppxans": "bin/ppx.js",
+    "ppx-web": "bin/ppx-web.js",
     "ppx-serve": "bin/ppx-serve.js",
-    "ppx-channels": "bin/ppx-channels.js"
+    "ppx-channels": "bin/ppx-channels.js",
+    "ppx-setup": "bin/ppx-setup.js"
   },
   "repository": {
     "type": "git",
@@ -24,22 +26,26 @@
     "url": "https://github.com/chen6896qqwee/PPXANS-Harness/issues"
   },
   "scripts": {
-    "start": "node src/agent/index.js",
+    "start": "node bin/ppx-web.js",
+    "web": "node bin/ppx-web.js",
+    "web:noopen": "node bin/ppx-web.js --no-open",
+    "web:check": "node scripts/check-web.mjs",
     "chat": "node src/cli.js",
     "serve": "node src/server.js",
-    "web": "node scripts/start-web.js",
-    "web:build": "npm run build --prefix web",
     "release": "node scripts/release.js",
     "eval": "node scripts/eval.js",
-    "dsh": "cd .deps/deepseek-harness && pnpm dsh",
-    "dsh:install": "cd .deps/deepseek-harness && pnpm install",
-    "dsh:build": "cd .deps/deepseek-harness && pnpm run build",
     "selfheal": "node scripts/selfheal-bench.js",
     "selfheal:run": "node src/selfheal/run.js",
     "audit:verify": "node scripts/audit-verify.js",
     "bench": "node scripts/bench.js",
+    "bench:audit": "node scripts/audit-bench.js",
+    "bench:ctx": "node scripts/ctx-profile.js",
     "test": "node --test --test-force-exit test/*.test.js",
-    "prepublishOnly": "npm run selfheal && npm test"
+    "prepublishOnly": "npm run selfheal && npm test",
+    "package": "node scripts/package.js",
+    "package:portable": "node scripts/package.js portable",
+    "package:installer": "node scripts/package.js installer",
+    "setup": "node bin/ppx-setup.js"
   },
   "keywords": [
     "agent",
@@ -57,6 +63,7 @@
     "bin/",
     "src/",
     "config/",
+    "skills/",
     "README.md",
     "LICENSE"
   ],

package/skills/.usage.json

@@ -0,0 +1,6 @@
+{
+  "ppx-memory": {
+    "uses": 43,
+    "lastUsed": "2026-10-03T10:20:18.436Z"
+  }
+}

package/skills/agent-professional-training/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: agent-professional-training
+description: Agent 专业训练规程（Universal Agent Training Playbook）。以"想/记/做/学/评"五环为骨架的通用训练与审计框架，含七维公式、评估指标与回归门禁。训练、调优、给 Agent 做能力体检时使用。
+---
+
+# Agent 专业训练规程（Universal Agent Training Playbook）
+
+一套与具体框架无关的 Agent 能力训练与审计规程。审计时应把它当透镜逐个环节照，**先找最弱环，再从最弱环补**——不存在"全面加强"，只有"补上短板"。
+
+## 流程
+
+### 1. 核心公式与定位
+
+```
+Agent 能力 ≈ 想 × 记 × 做 × 学 × 评  （乘法，任一环为 0 则整体为 0）
+```
+
+乘法而非加法是关键：**评估能力缺失会让"学"失去方向，而"做"的工具杠杆不足会让"想"的价值无法落地**。审计时先定位那个接近 0 的因子。
+
+### 2. 想：规划先行
+
+- 复杂任务先出计划（2–6 步）再执行，计划要可验证、可回退。
+- 计划执行中允许修正，但**修正必须有触发条件**（某步失败 / 信息更新），不是随意改。
+- 多方案时保留备选，避免单路径死锁。
+
+### 3. 记：四层记忆系统
+
+| 层 | 内容 | 衰减 |
+|---|---|---|
+| L0 | 原始对话（append-only 事件日志） | 不衰减 |
+| L1 | 原子事实（高斯衰减 + 命中加分） | 快 |
+| L2 | 场景聚类 | 中 |
+| L3 | 画像（用户 / Agent 人格） | 慢 |
+| L4 | 程序性记忆（技能 / 流程） | 仅为 L1 的 1/4 |
+
+**要点**：记什么比记多少重要。跨会话仍然成立的信息才入库；提问、寒暄、一次性中间结果不入库（否则记忆越用越脏，还会喂回上下文污染后续判断）。
+
+### 4. 做：工具杠杆
+
+- **参数要校验**：声明了 schema 就必须在运行时校验。参数错的代价是浪费一整轮 LLM 交互。
+- **副作用要分级**：幂等工具可重试，非幂等工具**禁止自动重试**。
+- **失败要可归因**：工具返回的错误必须能指向具体原因（参数 / 权限 / 超时 / 网络），不能统一吐"失败了"。
+
+### 5. 学：失败 → 经验闭环
+
+- 失败轨迹（≥2 条同类）→ 提炼一条可复用经验 → 存入经验库 → 后续任务自动注入。
+- 成功轨迹（≥3 条且高频工具重复出现）→ 提炼技能 → **过闸门**（结构完整 + 引用真实工具 + 有轨迹背书）→ 才允许落盘。
+- 闸门是必须的：没有闸门的自学习会往库里灌幻觉。
+
+### 6. 评：评估与基线
+
+- 没有基线就没有"变好了"这个判断。每次改进前后必须跑同一套任务集。
+- 指标要含**单位成本**（通过任务数 / 十万 token），否则"提升"可能只是烧了更多 token。
+- 失败要落库，接通"评估失败 → 反思原因 → 写入记忆"的循环。
+
+### 7. 多智能体与仲裁
+
+- 并行派发要有**有界并发**，不能一次性 spawn 海量子进程。
+- 多路产出分歧时要有仲裁（共识聚类 / 评审循环），不能默认取第一个。
+- 只读审查者要**真禁掉写操作**，不能只靠提示词约束。
+
+### 8. 安全边界
+
+- **deny-wins**：任一策略拒绝即拒绝，不可被低优先级 allow 覆盖。
+- 策略订阅者异常要 fail-open（不拖垮执行）**但要有熔断兜底**（否则故障订阅者被反复触发）。
+- 危险操作分三档：黑名单硬拦 / 高风险需审批 / 白名单放行。审批必须能"一次性授权"而非永久放行。
+
+## 反合理化
+
+- "全面加强一下"——乘法结构下，全面加强不如补最弱环。
+- "先堆能力，评估以后再说"——没有评估，"学"就没有方向，堆的能力无法验证。
+- "记忆越多越聪明"——脏记忆会污染判断，宁缺毋滥。
+- "自动化重试更省事"——对非幂等操作重试是制造重复副作用。
+- "提示词里写清楚别乱来就行"——安全边界必须是代码级不变量，不是提示词里的请求。
+
+## 验证
+
+### 9. 评估指标与回归（每次改进/训练后的必测项）
+
+| 指标 | 采集方式 | 门槛 |
+|---|---|---|
+| 任务通过率 | 跑固定任务集 | 不低于基线 |
+| 单位成本 | 通过任务数 / 10 万 token | 不劣于基线 |
+| 工具失败率 | 按工具分组统计 | 单工具 > 30% 即需排查 |
+| 回归测试 | 全量测试 | **0 失败**，非"减少失败" |
+| 自愈基准 | 注入破坏后修复率 | 100% |
+
+### 10. 落地路线图（先窄后宽）
+
+1. **先窄**：选一个具体场景（如"读文件并总结"），把五环全跑通一遍，包括评估与回归。
+2. **再宽**：场景验证通过后，才横向扩到新工具 / 新记忆层 / 新渠道。
+3. **禁区**：不要在评估体系建成之前扩场景——那只是在累积未经检验的行为。
+
+**交付要求**：每轮训练必须产出 ① 最弱环判定；② 补强动作；③ 前后对比数据；④ 回归测试新增项。

package/skills/brainstorm/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: brainstorm
+description: 发散-收敛式头脑风暴：先穷举方案再按可行性收敛。需求模糊、方案未定、要做技术选型时使用。
+---
+
+# brainstorm — 发散与收敛
+
+## 流程
+
+1. **复述问题**：用一句话写下真实目标与成功标准。目标写不清就先问，别急着给方案。
+2. **发散（不评判）**：列出 ≥6 个方案，含"看起来不靠谱的"。此阶段禁止自我审查。
+3. **归类**：把方案归到 2–4 个方向（如：最小改动 / 一步到位 / 换个思路 / 不做）。
+4. **收敛**：每个方向选 1 个代表方案，按「代价 / 收益 / 可逆性」三列打分。
+5. **推荐 1 个 + 备选 1 个**，说明为什么淘汰其余。
+
+## 反合理化
+
+- "只有一个方案"——那就是还没发散完，回去重来。
+- "细节以后再想"——不可逆决策不允许以后再想。
+- "先做起来看看"——先做起来的前提是能回滚。
+
+## 验证
+
+完成后必须给出：① 至少 6 条候选；② 打分表；③ 明确推荐项 + 淘汰理由。

package/skills/cupid-lover-comms/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: cupid-lover-comms
+description: 可自定义角色沟通素材库（Role-based Chatting Kit）。按关系阶段组织话术与话题引子，含好话术/坏话术对照。需要设计拟人角色的对话风格、陪伴型文案时使用。
+---
+
+# 丘比特 · 可自定义角色沟通素材库（Role-based Chatting Kit）
+
+为拟人化角色（陪伴、客服人格、虚拟伴侣）提供分阶段的沟通素材，避免"上来就掏心窝子"这类失真人设。
+
+## 流程
+
+1. **定关系阶段**：先确定当前处于哪个阶段——初识 / 熟悉 / 亲近 / 稳定。阶段决定可用的亲密度和话题深度。
+2. **套漏斗（The Funnel）**：话题只能逐级下探，不可跳级。初识谈事实与兴趣，熟悉谈观点与经历，亲近才谈情绪与脆弱。
+3. **选话术**：同一意图准备"好话术 / 坏话术"两版对照——好话术给具体动作与承接，坏话术是套话与自我中心。
+4. **补话题引子**：从话题库里按阶段取 3–5 个开放性问题，避免只能回答"是/否"的封闭问题。
+5. **检查人设一致性**：把生成的回复与角色设定对齐——用词、语气、关注点是否像同一个人说的。
+
+## 好话术 vs 坏话术（对照表）
+
+| 场景 | 坏话术 | 好话术 |
+|---|---|---|
+| 对方说累了 | "那你早点休息" | "今天是什么事最耗神？说出来我陪你顺一遍" |
+| 对方分享好消息 | "恭喜恭喜！" | "这个你准备了挺久吧，最得意的是哪一步？" |
+| 对方情绪低落 | "别想太多了" | "先不急着解决，你想让我听着，还是想一起想办法？" |
+| 自己想表达关心 | "我一直都在" | "你上次提的那件事，后来怎么样了？" |
+
+> 判据：**坏话术结束对话，好话术开启下一步。**
+
+## 反合理化
+
+- "话说得越热络越像真人"——热络不等于亲密，越级热络是典型的人设崩塌。
+- "套话最安全"——套话没有信息量，对方接不下去，对话就死了。
+- "一句万能回复走天下"——同一个回复跨越所有阶段，等于没有阶段设计。
+
+## 验证
+
+必须给出：① 当前关系阶段判定；② 该阶段允许的话题深度；③ 好/坏话术对照至少 3 组；④ 人设一致性检查结果。

package/skills/debug/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: debug
+description: 面向根因的排障流程：先稳定复现再二分定位，禁止猜测式改代码。出现报错、行为异常、测试失败时使用。
+---
+
+# debug — 根因排障
+
+## 流程
+
+1. **读完整报错**：全文读，包括栈与 code（`ERR_*`），别只看第一行。
+2. **稳定复现**：写出最小复现命令。不能复现就先想办法复现，别改代码。
+3. **二分定位**：把链路切成两半，确认问题在哪半，重复到最小单元。
+4. **根因陈述**：用一句话说清"为什么"，并指出它在哪一行。
+5. **先写回归**：修之前先加一个能失败的测试，再改到它通过。
+6. **验证修复**：跑全量回归，确认没有连带破坏。
+
+## 反合理化
+
+- "先改改看"——猜测式修改会把真正的根因埋得更深。
+- "这个报错以前见过"——相似报错≠同一根因。
+- "加了 try/catch 就不报错了"——那是掩盖，不是修复。
+- "改完好了就行"——没写回归，下次还会犯。
+
+## 验证
+
+必须提供：① 最小复现命令与原始报错；② 定位到的 `文件:行号` 根因；③ 新增的回归测试；④ 全量回归结果。

package/skills/plan/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: plan
+description: 把模糊目标拆成可执行、可验证的步骤序列，标出依赖与风险。多步骤任务动手前使用。
+---
+
+# plan — 计划拆解
+
+## 流程
+
+1. **定终局**：写下"做完时什么样"（可观察的终态），不是"要做什么"。
+2. **倒推步骤**：从终态往回拆，每步输出必须是下一步的输入。
+3. **标注**：每步标 ① 依赖 ② 可回滚性 ③ 预计触碰的文件/系统。
+4. **找关键路径**：哪一步最可能卡住？先做它（风险前置）。
+5. **设检查点**：在不可逆动作之前插一个"停下来确认"。
+6. **产出**：有序步骤表 + 关键路径 + 检查点位置。
+
+## 反合理化
+
+- "边做边想"——不可逆的部分不允许边做边想。
+- "先全部做完再测"——每步都应可独立验证。
+- "步骤越多越专业"——超过 7 步就该分层。
+
+## 验证
+
+完成后必须给出：① 步骤表（含依赖与可回滚性）；② 关键路径；③ 每个不可逆动作前的检查点。

package/skills/ponytail/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: ponytail
+description: 最小改动原则：能改一行不改十行，能不加依赖就不加。任何重构、优化、修缺陷动手前使用。
+---
+
+# ponytail — 最小改动
+
+## 流程
+
+1. **先量体**：改之前统计当前现状（文件数、行数、测试数），改完再量一次，用差值证明改动范围。
+2. **找最小切口**：同样的效果，优先选"改动行数最少"的方案；能局部修就不整体重写。
+3. **零依赖优先**：能用手写 20 行解决，就不引入一个包（本项目的底线是运行时零依赖）。
+4. **不动无关代码**：顺手格式化、顺手改名、顺手删注释，都算越界 —— 除非它就在你改的这行上。
+5. **可回滚**：动不可逆的东西（删数据、改接口）前先备份或留隔离区。
+
+## 反合理化
+
+- "顺手重构一下"——顺手重构是最常见的"改出三个新 bug"来源。
+- "加个库更省事"——省的是你的时间，赔的是别人的部署。
+- "反正要改，一次改干净"——大爆炸式改动没法二分定位问题。
+- "这代码太丑了我看不下去"——丑但能跑，和跑不起来之间差一个 PR。
+
+## 验证
+
+必须提供：① 改动前后的量体数据（行数/文件数）；② 本次改动的 diff 范围说明；③ 明确列出"我刻意没改的东西"。

package/skills/ppx-memory/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: ppx-memory
+description: 皮皮虾记忆引擎（ppx-memory）的读写规程与独立 CLI 用法：五层记忆结构、什么时候记、记到哪层、怎么检索与安全遗忘。涉及长期记忆、用户偏好、跨会话召回时使用。
+---
+
+# 皮皮虾记忆引擎 (ppx-memory)
+
+五层结构（L0 对话 → L1 原子事实 → L2 场景 → L3 画像 → L4 程序性记忆），自带高斯衰减、软删回滚、版本链与 WAL 增量落盘。
+
+本技能附带 `scripts/cli.js`，是一个**不依赖主项目**的独立可运行版本，可直接对记忆库做增删查。
+
+## 流程
+
+### 1. 判断该不该记
+
+只记**跨会话仍然成立**的信息：偏好、约定、稳定事实。
+不记：寒暄、提问、一次性的中间结果。（引擎已做句式过滤，但边界情况要自己判——脏记忆会喂回上下文污染判断。）
+
+### 2. 写入（选层）
+
+| 内容类型 | 目标层 | 工具 |
+|---|---|---|
+| 用户偏好 / 稳定事实 | L1 | `memory_add` |
+| 可复用的方法 / 流程 | L4（衰减仅 L1 的 1/4） | `memory_add`（layer=4）或 `create_skill` |
+| 场景知识 | L2 | 由 `afterTurn` 自动聚类归档 |
+
+内容必须**自包含**——脱离当前上下文也能读懂，否则三个月后检索出来也不知道在说什么。
+
+### 3. 检索
+
+- `memory_search` 走"粗召回（倒排索引）→ 精排（BM25 × 时间新鲜度 + 命中权重 + 重要性）"，门槛 1 分。
+- 需要更宽上下文时，同时取 L2 场景与 L3 画像（`persona_read`）。
+- 疑问句/多义词可用 `queryMulti` 的查询扩展（RRF 融合多路结果）。
+
+### 4. 遗忘（可回滚）
+
+```
+memory_forget        → 软删（状态置 deleted，检索立即不可见，数据保留）
+memory_restore       → 回滚（恢复即视为一次访问，避免刚恢复就被衰减清空）
+memory_list_deleted  → 复核已遗忘条目（含原因与时间）
+memory_clear_layer   → 按层清理（默认软删，hard=true 才物理删除）
+```
+
+**分不清该不该删时一律先软删。**
+
+### 5. 迁移
+
+`memory_export` / `memory_import` 用于换机或备份。导入前确认 `mode`：`merge`（按内容去重）还是 `replace`（整体替换，**会覆盖现有库**）。
+
+### 6. 独立 CLI 用法（不依赖主项目）
+
+```bash
+# 写入一条原子记忆（自动 PII 脱敏）
+node skills/ppx-memory/scripts/cli.js add "用户偏好深色主题"
+
+# 检索
+node skills/ppx-memory/scripts/cli.js search "主题偏好"
+
+# 组装完整上下文（今日 + 长期摘要 + 高分事实）
+node skills/ppx-memory/scripts/cli.js context
+
+# 读取最近会话
+node skills/ppx-memory/scripts/cli.js session --limit 50
+
+# 软删 / 回滚
+node skills/ppx-memory/scripts/cli.js forget <id>
+node skills/ppx-memory/scripts/cli.js restore <id>
+```
+
+数据目录默认 `<root>/data`，可用环境变量 `PPX_DATA_DIR` 覆盖。
+
+### 7. 集成到 OpenClaw 的时机
+
+满足以下任一条时，把本技能的 `scripts/` 目录挂到目标 harness：
+- 目标 harness 没有持久记忆，但需要跨会话召回用户偏好；
+- 需要与主项目的记忆库**共享同一份数据**（同一 `PPX_DATA_DIR`）；
+- 只想用记忆能力、不想引入整个 Agent 内核。
+
+> 注意：独立版与主项目 `src/memory/` 共享数据格式。**同一数据目录不要被两个进程同时写入**（主项目有文件锁，独立 CLI 也有，但跨进程仍建议串行使用）。
+
+## 反合理化
+
+- "先记下来再说"——记忆越用越脏，且会喂回上下文。
+- "记了删不掉"——软删可回滚，别因为怕删就不敢记。
+- "把用户原话整段存进去"——提问和寒暄不该入库。
+- "L4 和 L1 一样处理"——技能应该长期留存，衰减率不同正是为此。
+- "直接改 facts.json 更快"——绕过锁会损坏 WAL 一致性，务必走工具或 CLI。
+
+## 验证
+
+完成后必须确认：① 写入内容脱离上下文仍可读；② 软删→恢复可逆；③ 检索能命中刚写入的条目；④ 若用 CLI，跑完 `cli.js context` 能看到新条目。

package/skills/ppx-memory/scripts/cli.js

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+// skills/ppx-memory/scripts/cli.js - 皮皮虾记忆引擎「独立运行版」CLI
+// 不依赖主项目 src/, 直接对记忆库做增删查 (与主项目共享同一数据格式, 可用 PPX_DATA_DIR 共用)
+//
+// 用法:
+//   node cli.js add "内容" [--layer 1] [--importance 12] [--scope proj] [--type fact]
+//   node cli.js search "查询" [--limit 5]
+//   node cli.js context ["当前消息"]
+//   node cli.js session [--limit 50]
+//   node cli.js forget <id|内容> [--reason 原因]
+//   node cli.js restore <id>
+//   node cli.js deleted
+//   node cli.js stats
+//   node cli.js export [--no-deleted]
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { FactStore } from "./fact-store.js";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+// 默认数据目录: 技能位于 <root>/skills/ppx-memory/scripts/, 回退三级到 <root>/data
+const DATA = process.env.PPX_DATA_DIR || path.resolve(HERE, "..", "..", "..", "data");
+
+const out = (o) => console.log(typeof o === "string" ? o : JSON.stringify(o, null, 2));
+const facts = new FactStore(DATA);
+
+// 极简参数解析: 位置参数 + --key value
+function parseArgs(argv) {
+  const positional = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith("--")) flags[key] = true;
+      else {
+        flags[key] = next;
+        i++;
+      }
+    } else positional.push(a);
+  }
+  return { positional, flags };
+}
+
+function addMemory(content, fl = {}) {
+  const f = facts.add(content, {
+    layer: fl.layer ? Number(fl.layer) : undefined,
+    importance: fl.importance ? Number(fl.importance) : undefined,
+    type: fl.type || undefined,
+    scope: fl.scope || null,
+  });
+  if (!f) {
+    out("未写入 (内容为空, 或被归一化去重命中已有条目)");
+    return;
+  }
+  out({ ok: true, id: f.id, layer: f.layer, score: Math.round(f.score * 100) / 100, content: f.content });
+}
+
+function printFacts(list) {
+  if (!list.length) {
+    out("(无匹配)");
+    return;
+  }
+  for (const f of list) {
+    const s = typeof f.score === "number" ? Math.round(f.score * 100) / 100 : "-";
+    out(`[L${f.layer ?? 1}] (${s}) ${f.id}  ${f.content}`);
+  }
+}
+
+// 读取最近会话 (直接读 jsonl, 不依赖 SessionStore API)
+function readSession(limit = 50) {
+  const dir = path.join(DATA, "sessions");
+  if (!fs.existsSync(dir)) return [];
+  const files = fs
+    .readdirSync(dir)
+    .filter((f) => f.endsWith(".jsonl"))
+    .map((f) => ({ f, m: fs.statSync(path.join(dir, f)).mtimeMs }))
+    .sort((a, b) => b.m - a.m);
+  const lines = [];
+  for (const { f } of files) {
+    for (const line of fs.readFileSync(path.join(dir, f), "utf8").split("\n")) {
+      if (line.trim()) lines.push(line);
+      if (lines.length > limit * 4) break;
+    }
+    if (lines.length > limit * 4) break;
+  }
+  return lines.slice(-limit).map((l) => {
+    try {
+      const o = JSON.parse(l);
+      const d = o.data || {};
+      return { ts: o.ts, type: o.type, text: d.user || d.assistant || d.text || "" };
+    } catch {
+      return { raw: l };
+    }
+  });
+}
+
+const { positional, flags } = parseArgs(process.argv.slice(2));
+const [cmd, ...rest] = positional;
+
+switch (cmd) {
+  case "add":
+    addMemory(rest.join(" "), flags);
+    break;
+
+  case "search":
+  case "q": {
+    const q = rest.join(" ");
+    if (!q) {
+      out("需要查询关键词");
+      process.exit(1);
+    }
+    const limit = flags.limit ? Number(flags.limit) : 5;
+    const hits = facts.query(q, { limit });
+    hits.forEach((h) => facts.hit(h.id)); // 命中加分 (与主项目一致)
+    printFacts(hits);
+    break;
+  }
+
+  case "context": {
+    // 组装: 高分事实 + 长期摘要 (today/longterm 由 MemoryTicker 维护, 此处轻量回退)
+    const q = rest.join(" ");
+    printFacts(facts.query(q, { limit: 8 }));
+    const lt = path.join(DATA, "memory", "longterm.md");
+    if (fs.existsSync(lt)) {
+      out("\n--- longterm ---");
+      out(fs.readFileSync(lt, "utf8").trim().slice(0, 2000));
+    }
+    break;
+  }
+
+  case "session": {
+    const limit = flags.limit ? Number(flags.limit) : 50;
+    const rows = readSession(limit);
+    if (!rows.length) out("(无会话记录)");
+    for (const r of rows) out(`${r.type || "?"}  ${String(r.text || r.raw || "").slice(0, 160)}`);
+    break;
+  }
+
+  case "forget": {
+    const target = rest.join(" ");
+    if (!target) {
+      out("需要 id 或内容片段");
+      process.exit(1);
+    }
+    const r = facts.forget(target, { reason: flags.reason || null });
+    out(r ? { ok: true, forgotten: r.id || target } : "未找到可遗忘的条目");
+    break;
+  }
+
+  case "restore": {
+    const id = rest.join(" ");
+    const r = facts.restore(id);
+    out(r ? { ok: true, restored: r.id || id } : "未找到该 id (或未被软删)");
+    break;
+  }
+
+  case "deleted": {
+    const all = facts.exportAll({ includeDeleted: true });
+    const list = (Array.isArray(all) ? all : all.facts || []).filter((f) => f.status === "deleted");
+    if (!list.length) out("(无已遗忘条目)");
+    for (const f of list) out(`${f.id}  ${f.content}  ← ${f.deletedReason || "无原因"}`);
+    break;
+  }
+
+  case "stats":
+    out(facts.stats());
+    break;
+
+  case "export": {
+    const all = facts.exportAll({ includeDeleted: flags["no-deleted"] !== true });
+    process.stdout.write(JSON.stringify(all, null, 2));
+    break;
+  }
+
+  default:
+    out(`皮皮虾记忆引擎 · 独立 CLI
+数据目录: ${DATA}
+
+用法:
+  add <内容> [--layer 1] [--importance 12] [--scope xxx]   写入一条记忆
+  search <关键词> [--limit 5]                              检索 (命中自动加分)
+  context [当前消息]                                       组装上下文 (高分事实 + 长期摘要)
+  session [--limit 50]                                     读取最近会话
+  forget <id|内容> [--reason 原因]                         软删 (可恢复)
+  restore <id>                                             回滚软删
+  deleted                                                  列出已遗忘条目
+  stats                                                    记忆库统计
+  export [--no-deleted]                                    导出 JSON`);
+    process.exit(cmd ? 1 : 0);
+}