@yottameta/yotta-memory 0.19.0 → 0.20.1

package/install.sh

@@ -1,28 +1,30 @@
 #!/usr/bin/env bash
-# yotta-memory 多智能体安装脚本
+# yotta-memory 多智能体安装脚本（YottaSkills）
 # 用法:
 #   bash install.sh --agent <name>  # 按智能体默认用户级目录安装
 #   bash install.sh --dir <path>    # 装到指定目录（用户改过目录的智能体）
 #   bash install.sh -g              # 装到全部已知智能体用户级目录
-#   bash install.sh                  # 检测并安装到已存在的项目级目录
+#   bash install.sh                 # 检测并安装到已存在的项目级目录
 #   bash install.sh --list          # 列出智能体 -> 默认目录
+#   bash install.sh --dry-run       # 只显示将写入的目标，不写文件
+#   bash install.sh --version       # 显示版本
+#   bash install.sh --help          # 显示帮助
+# 退出码: 0 成功 / 1 安装失败 / 2 用法错误 / 4 目标错误
 set -euo pipefail
 
 SKILL_NAME="yotta-memory"
 SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+_IS_WINDOWS=0
 case "$(uname -s)" in
   MINGW*|MSYS*)
     SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -W)"
+    _IS_WINDOWS=1
     ;;
+  CYGWIN*) _IS_WINDOWS=1 ;;
 esac
 
 # 智能体 -> 用户级默认目录（--agent 装到第一个）
 # .agents/skills 并非通用目录：OpenCode / Cursor / Cline / Amp / Kimi / Gemini CLI / GitHub Copilot 读取。
-# 判断当前环境：Windows Git Bash 用 %USERPROFILE%，Unix 用 ~
-_IS_WINDOWS=0
-case "$(uname -s)" in
-  MINGW*|MSYS*|CYGWIN*) _IS_WINDOWS=1 ;;
-esac
 dirs_for() {
   case "$1" in
     claude)     echo ".claude/skills" ;;
@@ -60,36 +62,153 @@ resolve_user() {
   esac
 }
 
-install_to() {
-  local base="$1"
-  local dest
-  case "$base" in
-    ""|"/") echo "安装失败：拒绝不安全的目标目录：'$base'" >&2; return 1 ;;
+skill_version() {
+  local pkg="$SOURCE_DIR/package.json" v=""
+  [ -f "$pkg" ] || return 0
+  if command -v awk >/dev/null 2>&1; then
+    v="$(awk -F'"' '{for (i=1;i<=NF;i++) if ($i=="version") {print $(i+2); exit}}' "$pkg" 2>/dev/null || true)"
+  fi
+  if [ -z "$v" ]; then
+    v="$(sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$pkg" 2>/dev/null | head -n 1 || true)"
+  fi
+  printf '%s' "$v"
+}
+
+usage() {
+  echo "$SKILL_NAME 安装脚本（YottaSkills）"
+  echo ""
+  echo "用法:"
+  echo "  bash install.sh --agent <name>   按智能体默认用户级目录安装（推荐）"
+  echo "  bash install.sh --dir <path>     装到指定目录（用户改了目录的智能体）"
+  echo "  bash install.sh -g               安装到全部已知智能体用户级目录"
+  echo "  bash install.sh                  安装到检测到的项目级目录"
+  echo ""
+  echo "参数:"
+  echo "  --agent <name>  智能体键名，见 --list"
+  echo "  --dir <path>    自定义技能目录"
+  echo "  -g, --global    安装到全部已知用户级目录"
+  echo "  --list, -l      列出支持的智能体目录"
+  echo "  --dry-run       只显示将写入的目标，不写文件"
+  echo "  --version, -v   显示版本"
+  echo "  --help, -h      显示帮助"
+  echo "  --yes, -y       兼容参数（-g 不再强制要求）"
+  echo ""
+  echo "退出码: 0 成功 / 1 安装失败 / 2 用法错误 / 4 目标错误"
+}
+
+resolve_path() {
+  # 与 SOURCE_DIR 同一风格（Windows Git Bash 用 pwd -W），供路径包含判断使用
+  local p="$1"
+  if [ "$_IS_WINDOWS" = "1" ]; then
+    (cd "$p" 2>/dev/null && pwd -W)
+  else
+    (cd "$p" 2>/dev/null && pwd -P)
+  fi
+}
+
+assert_safe_target() {
+  local dest="$1" src_real dest_real parent
+  src_real="$(resolve_path "$SOURCE_DIR")" || return 0
+  if [ -d "$dest" ]; then
+    dest_real="$(resolve_path "$dest")" || return 0
+  else
+    parent="$(dirname "$dest")"
+    dest_real="$(resolve_path "$parent")" || return 0
+    dest_real="$dest_real/$(basename "$dest")"
+  fi
+  case "$dest_real" in
+    "$src_real"|"$src_real"/*)
+      echo "安装失败：目标目录不能在技能源目录内（防止自装自毁）" >&2
+      return 1
+      ;;
   esac
+  return 0
+}
+
+# 清理旧版安装残留（fail-closed 白名单）：仅在目标目录已存在且含 SKILL.md 时触发；
+# 只删顶层开发项 + 任意层级缓存；不整目录删除、不跟随符号链接。
+DEV_SKIP="package.json package-lock.json bin lib test .github .git .gitignore .npmignore .gitattributes .yotta .tmp install.sh node_modules"
+clean_residue() {
+  local dest="$1" name p
+  [ -d "$dest" ] || return 0
+  [ -f "$dest/SKILL.md" ] || return 0
+  for name in $DEV_SKIP; do
+    p="$dest/$name"
+    [ -L "$p" ] && continue
+    if [ -e "$p" ]; then
+      rm -rf -- "$p"
+      echo "已清理残留: $name"
+    fi
+  done
+  find "$dest" -type d \( -name '__pycache__' -o -name '.pytest_cache' -o -name '.mypy_cache' \) -prune -exec rm -rf -- {} + 2>/dev/null || true
+  find "$dest" -type f \( -name '*.pyc' -o -name '*.pyo' \) -delete 2>/dev/null || true
+}
+
+# 复制技能本体：顶层跳过开发件与运行时不相关目录（嵌套同名保留）；
+# 任意层级跳过缓存（__pycache__ / .pytest_cache / .mypy_cache / *.pyc / *.pyo）。
+copy_tree() {
+  local src="$1" dst="$2" top="$3" entry base
+  mkdir -p "$dst"
+  for entry in "$src"/* "$src"/.[!.]* "$src"/..?*; do
+    [ -e "$entry" ] || [ -L "$entry" ] || continue
+    base="$(basename "$entry")"
+    case "$base" in
+      __pycache__|.pytest_cache|.mypy_cache) continue ;;
+    esac
+    if [ "$top" = "1" ]; then
+      case " $DEV_SKIP " in
+        *" $base "*) continue ;;
+      esac
+    fi
+    if [ -d "$entry" ] && [ ! -L "$entry" ]; then
+      copy_tree "$entry" "$dst/$base" 0 || return 1
+    else
+      case "$base" in
+        *.pyc|*.pyo) continue ;;
+      esac
+      cp -RP "$entry" "$dst/$base" || return 1
+    fi
+  done
+}
+
+install_to() {
+  local base="$1" dry="$2" dest
+  dest="$base/$SKILL_NAME"
   if [ -L "$base" ]; then
-    echo "安装失败：目标目录是符号链接，拒绝跟随：$base" >&2; return 1
+    echo "安装失败：目标目录是符号链接，拒绝跟随：$base" >&2
+    return 1
+  fi
+  if [ -e "$base" ] && [ ! -d "$base" ]; then
+    echo "安装失败：目标路径已存在且不是目录：$base" >&2
+    return 1
   fi
-  mkdir -p "$base"
-  dest="$base/$SKILL_NAME"
   if [ -L "$dest" ]; then
-    echo "安装失败：技能目录是符号链接，拒绝跟随：$dest" >&2; return 1
+    echo "安装失败：技能目录是符号链接，拒绝跟随：$dest" >&2
+    return 1
   fi
   if [ -e "$dest" ] && [ ! -d "$dest" ]; then
-    echo "安装失败：技能路径已存在且不是目录：$dest" >&2; return 1
-  fi
-  mkdir -p "$dest"
-  cp -RP "$SOURCE_DIR/." "$dest/"
-  # 只清理副本内部的开发残留（固定子路径），不做整目录删除、不跟随符号链接
-  if [ -d "$dest/.git" ] && [ ! -L "$dest/.git" ]; then rm -rf "$dest/.git"; fi
-  find "$dest" -type d -name '__pycache__' -prune -exec rm -rf {} + 2>/dev/null || true
-  find "$dest" -type f -name '*.pyc' -delete 2>/dev/null || true
+    echo "安装失败：技能路径已存在且不是目录：$dest" >&2
+    return 1
+  fi
+  assert_safe_target "$dest" || return 1
+  if [ "$dry" = "1" ]; then
+    echo "[dry-run] 将安装到 -> $dest"
+    return 0
+  fi
+  clean_residue "$dest"
+  mkdir -p "$dest" || return 1
+  copy_tree "$SOURCE_DIR" "$dest" 1 || return 1
+  if [ ! -f "$dest/SKILL.md" ]; then
+    echo "安装失败：结果缺少 SKILL.md" >&2
+    return 1
+  fi
   echo "installed -> $dest"
 }
 
 list() {
   echo "智能体 -> 默认技能目录（--agent <name> 装到第一个，用户级）:"
+  local a dirs first
   for a in claude cursor codex gemini goose amp opencode windsurf workbuddy kiro trae trae-cn qwen comate codebuddy kimi agents; do
-    local dirs first
     dirs="$(dirs_for "$a")"
     first="${dirs%% *}"
     case "$first" in
@@ -108,44 +227,101 @@ list() {
 }
 
 main() {
-  local agent="" dir="" global=0 show_list=0
+  local agent="" dir="" global=0 show_list=0 show_help=0 show_version=0 dry=0
   while [ $# -gt 0 ]; do
     case "$1" in
-      --agent) shift; agent="${1:-}" ;;
-      --dir)   shift; dir="${1:-}" ;;
-      -g|--global) global=1 ;;
+      --help|-h) show_help=1 ;;
+      --version|-v) show_version=1 ;;
       --list|-l) show_list=1 ;;
+      -g|--global) global=1 ;;
+      --dry-run) dry=1 ;;
+      --yes|-y) : ;;
+      --agent)
+        shift
+        if [ $# -eq 0 ] || [ -z "${1:-}" ]; then
+          echo "用法错误: --agent 需要一个非空名称" >&2
+          exit 2
+        fi
+        agent="$1"
+        ;;
+      --dir)
+        shift
+        if [ $# -eq 0 ] || [ -z "${1:-}" ]; then
+          echo "用法错误: --dir 需要一个非空路径" >&2
+          exit 2
+        fi
+        dir="$1"
+        ;;
       *) echo "未知参数: $1" >&2; exit 2 ;;
     esac
     shift
   done
 
-  if [ "$show_list" = "1" ]; then list; return; fi
-  if [ -n "$dir" ]; then install_to "$dir"; echo "完成。"; return; fi
+  if [ "$show_help" = "1" ]; then usage; return 0; fi
+  if [ "$show_version" = "1" ]; then
+    local v
+    v="$(skill_version)"
+    if [ -z "$v" ]; then
+      echo "$SKILL_NAME 版本未知（未找到 package.json）" >&2
+      exit 1
+    fi
+    echo "$SKILL_NAME v$v"
+    return 0
+  fi
+  if [ "$show_list" = "1" ]; then list; return 0; fi
+
+  local selected=0
+  [ -n "$dir" ] && selected=$((selected + 1))
+  [ -n "$agent" ] && selected=$((selected + 1))
+  [ "$global" = "1" ] && selected=$((selected + 1))
+  if [ "$selected" -gt 1 ]; then
+    echo "用法错误: --dir / --agent / -g 只能选一个" >&2
+    exit 2
+  fi
+
+  if [ -n "$dir" ]; then
+    install_to "$dir" "$dry" || exit 1
+    [ "$dry" = "1" ] || echo "完成。"
+    return 0
+  fi
   if [ -n "$agent" ]; then
     local dirs first
     if ! dirs="$(dirs_for "$agent")"; then
-      echo "未收录智能体: $agent。请用 --dir <路径> 指定技能目录。" >&2; exit 2
+      echo "未收录智能体: $agent。可用 --list 查看，或 --dir <路径> 指定。" >&2
+      exit 2
     fi
     first="${dirs%% *}"
-    install_to "$(resolve_user "$first")"; echo "完成。"; return
+    install_to "$(resolve_user "$first")" "$dry" || exit 1
+    [ "$dry" = "1" ] || echo "完成。"
+    return 0
   fi
   if [ "$global" = "1" ]; then
-    echo "安装到全部已知智能体用户级目录..."
-    local dirs rel
+    local a dirs rel seen=" "
     for a in claude cursor codex gemini goose amp opencode windsurf workbuddy kiro trae trae-cn qwen comate codebuddy kimi agents; do
-      dirs="$(dirs_for "$a")"
-      for rel in $dirs; do install_to "$(resolve_user "$rel")"; done
+      dirs="$(dirs_for "$a")" || continue
+      for rel in $dirs; do
+        case "$seen" in
+          *" $rel "*) continue ;;
+        esac
+        seen="$seen$rel "
+        install_to "$(resolve_user "$rel")" "$dry" || exit 1
+      done
     done
-    echo "完成。"; return
+    [ "$dry" = "1" ] || echo "完成。"
+    return 0
   fi
   local installed=0 d
   for d in .claude/skills .cursor/skills .codex/skills .config/goose/skills .config/agents/skills .opencode/skills .codeium/windsurf/skills .workbuddy/skills .kiro/skills .traecli/skills .gemini/skills .trae-cn/skills .qwen/skills .comate/skills .codebuddy/skills .kimi/skills .agents/skills; do
-    if [ -d "$d" ]; then install_to "$d"; installed=1; fi
+    if [ -d "$d" ]; then
+      install_to "$d" "$dry" || exit 1
+      installed=1
+    fi
   done
   if [ "$installed" = "0" ]; then
-    echo "未检测到项目级智能体目录。可用 --agent <name> / -g 装到用户级，或 --dir 指定。"
+    echo "目标错误: 未检测到项目级智能体目录。可用 --agent <name> 装到用户级，或用 --dir <路径> 指定目录。" >&2
+    exit 4
   fi
+  [ "$dry" = "1" ] || echo "完成。"
 }
 
 main "$@"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yottameta/yotta-memory",
-  "version": "0.19.0",
+  "version": "0.20.1",
   "description": "Yuanyi (元忆) — boundary-aware, file-based memory for AI agents. File-based, zero-dependency, diff/rollback-able; FACT/PREF/BOUND/COMMIT types (public shared / private isolated), user-level + project-level storage; v0.12 reliability baseline (init guard, trash-based deletion, independent-volume backup/list/doctor/restore, start-of-work doctor, transactional snapshots before destructive writes), v0.10 consolidation (periodic summaries with provenance, near-duplicate auto-merge, per-type decay, batch audit + rollback), v0.9 recall quality + context focus + optional local embedding plugin, plus v0.8 semantic search, feedback loop, self-organization and distillation.",
   "license": "MIT",
   "keywords": [

package/references/provider-protocol.md

@@ -1,8 +1,13 @@
-# 扩展提供方协议 v1（元忆 · capability `memory.hook`）
+# 扩展提供方协议 v1.1（元忆 · capability `memory.hook` / `context.paging`）
 
 元忆可以可选地调用一个由用户显式配置的**本地扩展提供方（provider）**，由它参与「哪些记忆进上下文」。
 未配置提供方时，`context` 的行为与输出与之前完全一致；任何失败都回落到普通记忆，不阻断命令。
 
+本版协议包含两个 capability：
+
+- `memory.hook`：在装配前过滤候选集（`evict` / `selected`）。
+- `context.paging`：在用户显式传 `--budget` 时，对已通过 `memory.hook` 的候选集做排序与分页（`drop` / `order`）。
+
 ## 1. 配置
 
 配置文件：`<YOTTA_PROVIDER_HOME>/provider.json`，默认 `~/.yottameta/provider.json`。
@@ -15,7 +20,7 @@
     {
       "id": "local-provider",
       "version": "0.1.0",
-      "capabilities": ["memory.hook"],
+      "capabilities": ["memory.hook", "context.paging"],
       "command": ["node", "C:/path/to/provider.js"],
       "timeout_ms": 600
     }
@@ -69,7 +74,7 @@
 
 - **`evict`（推荐）**：要从上下文里驱逐的条目清单。每个 `file` 必须出现在本次 `candidates` 中；候选集外的 file 会被丢弃并记入 `dropped`。未见过的条目默认保留 —— 候选很多时也安全。
 - **`selected`（可选白名单）**：仅在 `complete: true` 且本次未 `truncated` 时接受。每个 `file` 必须 ∈ `candidates`；未列入的候选会被驱逐。
-- 元忆侧仍强制执行：BOUND / COMMIT 与身份画像不可驱逐；预算、去重、宽限、章节顺序由引擎决定。
+- 元忆侧仍强制执行：BOUND / COMMIT 与自我接入档案不可驱逐；`## 1. 身份` 段落不受影响，画像中的其它条目随条目一并参与驱逐；预算、去重、宽限、章节顺序由引擎决定。
 
 需要授权或不可用时：
 
@@ -91,7 +96,73 @@
 `context --json` 的 `hook` 块给出 `status` / `provider_id` / `applied` / `evicted` / `dropped` / `note`；
 `context --explain` 的 trace 里追加一行 `[hook] ...`。
 
-## 5. 审计与边界
+## 5. `context.paging`（v1.1 新增）
+
+### 5.1 调用时机
+
+- 仅在用户显式执行 `context` 且传了 `--budget`（大于 0）时调用；不传预算不调用，状态为 `not_requested`。
+- 调用顺序：`memory.hook` 先过滤，`context.paging` 再排序 / 分页。
+- 候选集与 `memory.hook` 同源：权限过滤后、去掉 BOUND / COMMIT / 自我接入档案；最多 500 条。
+- `context.paging` 不能覆盖引擎硬约束：身份段落、自我接入档案、BOUND / COMMIT 不参与；最终字符预算仍由元忆引擎强制。
+
+### 5.2 请求
+
+```json
+{
+  "schema": 1,
+  "capability": "context.paging",
+  "request_id": "<uuid>",
+  "payload": {
+    "agent": "codex",
+    "budget": 4000,
+    "focus": "",
+    "truncated": false,
+    "protected": ["private/codex/prefs/2026-08-25-0001.md"],
+    "sections": {
+      "summary": ["<file>"],
+      "focus": ["<file>"],
+      "corridor": ["<file>"],
+      "high_value": ["<file>"]
+    },
+    "candidates": [
+      {
+        "file": "facts/2026/09/2026-09-29-0001.md",
+        "type": "FACT",
+        "subject": "示例主题",
+        "statement": "示例内容（最多 2000 字）",
+        "created": "2026-09-29",
+        "updated": "2026-09-29",
+        "chars": 128,
+        "baseline_section": "corridor"
+      }
+    ]
+  }
+}
+```
+
+- `sections` 是引擎基线的分段落位，供 provider 参考，不构成约束。
+- `protected` 列出引擎硬保护、不可驱逐的文件（如自我接入档案）。
+
+### 5.3 响应
+
+```json
+{ "ok": true, "capability": "context.paging", "data": {
+  "drop": ["<file>"],
+  "order": ["<file>", "<file>"],
+  "complete": true
+} }
+```
+
+- `drop`：明确分页出去的条目，任意子集，**始终应用**；候选集外文件只记 note，不进入输出。
+- `order`：期望的进入顺序，**仅在 `complete: true` 且本次未 `truncated` 时应用**；未列入的候选按引擎基线顺序补尾，不丢内容。
+- 候选超过 500（`truncated=true`）时只接受 `drop`，`order` 不应用并写入 note。
+
+### 5.4 状态与回落
+
+`context --json` 的 `paging` 块给出 `status` / `provider_id` / `applied` / `dropped` / `ordered` / `truncated` / `budget` / `used` / `note`；
+`context --explain` 的 trace 里追加一行 `[paging] ...`。未配置 / 未声明该 capability 时为 `not_installed`；未传 `--budget` 时为 `not_requested`；授权失败 / 超时 / 非法输出 / 异常均回落普通上下文，不影响既有记忆。
+
+## 6. 审计与边界
 
 - 每次实际调用写一行 `<YOTTA_PROVIDER_HOME>/provider-audit.jsonl`：`ts` / `capability` / `provider_id` / `status` / `duration_ms` / `bytes_out`。
 - 审计**不记录**记忆正文、查询原文或任何 payload 内容。

package/skill-manifest.json

@@ -3,7 +3,7 @@
   "slug": "yotta-memory",
   "name": "元忆",
   "package": "@yottameta/yotta-memory",
-  "version": "0.19.0",
+  "version": "0.20.1",
   "trust": "yottameta",
   "install": {
     "idempotent": true