dev-memory-cli 0.18.3 → 0.20.0

package/README.md

@@ -6,18 +6,19 @@
 
 ![套件总览](docs/diagrams/overview.png)
 
-## v2 架构：4 个 Skill + branch CLI
+## v2 架构：5 个 Skill + branch CLI
 
-v2 把旧的 sync + update 合并成统一的 capture，并把 setup 从前置门禁改为 merge 动作、加 lazy init、加 v1→v2 自动迁移。0.16 起取消 `using-dev-memory` 路由总入口；0.17 起再取消 `dev-memory-context` 读取 skill —— SessionStart hook 注入末尾直接列出权威记忆文件的绝对路径，AI 需要详情时 Read 对应文件即可，不再需要 skill 中转。当前套件 4 个 skill（全部偏写入 / 流程 / 整理）。
+v2 把旧的 sync + update 合并成统一的 capture，并把 setup 从前置门禁改为 merge 动作、加 lazy init、加 v1→v2 自动迁移。0.16 起取消 `using-dev-memory` 路由总入口；0.17 起取消旧 `dev-memory-context` 读取 skill；现在补回更窄的 `dev-memory-read` 主动读取入口：它只负责精确定位当前 repo+branch 的权威记忆文件和关键词检索，不做 context 注入，也不写入。当前套件 5 个 skill（1 个读取入口 + 4 个写入 / 流程 / 整理入口）。
 
 | Skill | 定位 | 典型触发 |
 | --- | --- | --- |
+| `dev-memory-read` | **主动读取入口**：定位当前 repo+branch 记忆目录、关键词搜索、返回可直接 Read 的文件路径 | 用户说"重新读一下记忆 / 之前记的 todo / 按记忆最新口径"，或 agent 需要主动查记忆 |
 | `dev-memory-capture` | **统一写入入口**（合并 sync + update） | 本轮产生稳定结论 / checkpoint / 用户手动记一笔 / 改写旧条目 |
 | `dev-memory-setup` | 整理 unsorted.md + 补元信息 + 标 setup_completed（不再是前置门禁） | unsorted.md 累积、用户明确说"整理一下" |
 | `dev-memory-tidy` | **定期校准入口**：已结构化条目漂移时（陈旧 / 重复 / 模板残留），agent 聚合 proposal → 浏览器审 → apply 落盘 + 自动备份 | 用户说"整理一下记忆 / 清下过期的 / 看看哪些还成立" |
 | `dev-memory-graduate` | 分支收尾：从 pending-promotion 提炼上提 + 归档 branch | 用户显式说"归档 / 分支收尾 / merge 完清一下" |
 
-> 读取路径：SessionStart hook 自动注入 progress / risks / decisions 等摘要 + 完整文件路径；后续直接 Read 文件，或跑 CLI `dev-memory-cli context show` / `context sync` 拿 paths / 重新刷新（命令保留，只是不再以 skill 形式暴露）。
+> 读取路径：SessionStart hook 自动注入 progress / risks / decisions 等摘要 + 完整文件路径；用户或 agent 主动要求重新查记忆时，走 `dev-memory-read` / `dev-memory-cli read show|search`。`context show` / `context sync` 仍保留给 hook 和脚本场景。
 
 详细设计与语义见：
 
@@ -28,6 +29,17 @@ v2 把旧的 sync + update 合并成统一的 capture，并把 setup 从前置
 
 v2 里 capture 写入永远先 lazy init（骨架不存在就自动建），不再需要前置 setup。setup 的新职责：扫 `unsorted.md` 把未分类条目按用户选择 merge 到 decisions/progress/risks/glossary，再标 `manifest.setup_completed = true`。setup 之前 / 之后的区别是 capture 的 heuristic 兜底策略：之前"不确定 → unsorted"，之后"不确定 → progress"。
 
+### 主动读取：dev-memory-read
+
+`dev-memory-read` 是只读 skill，避免 agent 在错误目录里盲搜。它不 lazy-init，不迁移，不写任何记忆文件。
+
+```bash
+dev-memory-cli read show --repo <repo-path>
+dev-memory-cli read search --repo <repo-path> --query "作者信息" --query "头像"
+```
+
+`read show` 输出 `repo_dir`、`branch_dir`、`recommended_read_order`、`existing_branches`；`read search` 默认只查当前 branch + repo 共享层，需要扩大范围时再显式传 `--scope all-branches` 或 `--scope archived`。这能覆盖“当前分支记忆没命中，但旧分支/归档里可能有之前 TODO”的场景，同时不会扫描整个 `~/.dev-memory`。
+
 ### Capture 的写入路由
 
 ![capture 写入流程](docs/diagrams/capture.png)
@@ -301,7 +313,8 @@ CLI 暴露的子命令：
 | 安装助手 | `dev-memory-cli install-hooks <codex\|claude\|--all>` | 把 hook 模板合并到目标配置 |
 | 浏览器 UI | `dev-memory-cli ui [--port N] [--read-only]` | 启动本地浏览器界面看/编辑记忆 |
 | 分支生命周期 | `dev-memory-cli branch [list\|inspect\|rename\|fork\|delete\|init]` | 分支记忆迁移 / 副本 / 重置（无参数 = 交互式 type-ahead）|
-| Skill 工作流（agent 在 SKILL.md 里调用，也能手动跑）| `dev-memory-cli capture <record\|rewrite-entry\|delete-entry\|apply-summary-output\|show\|suggest-kind\|...>` | 统一写入入口（含 dedup、结构化 patch executor） |
+| Skill 工作流（agent 在 SKILL.md 里调用，也能手动跑）| `dev-memory-cli read <show\|search>` | 主动读取入口：精确定位当前 repo+branch 记忆路径，按关键词只搜当前 repo 的记忆 |
+| | `dev-memory-cli capture <record\|rewrite-entry\|delete-entry\|apply-summary-output\|show\|suggest-kind\|...>` | 统一写入入口（含 dedup、结构化 patch executor） |
 | | `dev-memory-cli setup <init\|merge-unsorted\|mark-completed>` | 整理 unsorted |
 | | `dev-memory-cli tidy <prepare\|apply>` | 浏览器化的批量 review + 落盘（0.18 起含 annotated md + delete-block）|
 | | `dev-memory-cli graduate <dry-run\|apply\|index>` | 分支归档 + 跨分支知识上提 |
@@ -320,6 +333,7 @@ hooks/
   README.md
 lib/                         # 所有 Python 业务逻辑都集中在这里（npm 包发布时随包带）
   dev_memory_common.py        # 共享公共库（path 解析、template、git facts、merge helpers ...）
+  dev_memory_read.py          # `dev-memory-cli read` 子命令实现（只读定位 + 搜索）
   dev_memory_context.py       # `dev-memory-cli context` 子命令实现
   dev_memory_capture.py       # `dev-memory-cli capture` 子命令实现
   dev_memory_setup.py         # `dev-memory-cli setup` 子命令实现
@@ -334,6 +348,7 @@ scripts/
   install_suite.py           # 本地开发用的 symlink 安装器
   npm/                       # 打包 check/build 助手
 skills/                      # SKILL.md + agents/openai.yaml + references/ 三件套；不再带 scripts/
+  dev-memory-read/
   dev-memory-capture/
   dev-memory-setup/
   dev-memory-tidy/

package/bin/dev-memory.js

@@ -285,6 +285,7 @@ function commandUi(_positional, options) {
 // Their CLIs (subcommands, flags) are owned by argparse on the Python
 // side, so we deliberately bypass parseArgs and forward raw argv.
 const PY_SUBCOMMAND_SCRIPTS = {
+  read: "dev_memory_read.py",
   context: "dev_memory_context.py",
   capture: "dev_memory_capture.py",
   setup: "dev_memory_setup.py",
@@ -616,6 +617,7 @@ function printHelp() {
   dev-memory-cli install-hooks <codex|claude> [--repo PATH] [--global]
   dev-memory-cli install-hooks --all [--repo PATH] [--global]
   dev-memory-cli ui [--port N] [--host HOST] [--no-open] [--read-only]
+  dev-memory-cli read <show|search> [...]
   dev-memory-cli context <show|...> [...]
   dev-memory-cli capture <record|show|sync-working-tree|record-head|suggest-kind|classify> [...]
   dev-memory-cli setup <init|merge-unsorted|mark-completed> [...]

package/lib/dev_memory_capture.py

@@ -162,6 +162,20 @@ SUPERSEDES_KEYWORDS = (
 _SIM_PREVIEW_LEN = 80
 
 
+def _int_env(name, default):
+    value = os.environ.get(name, "").strip()
+    if not value:
+        return default
+    try:
+        return int(value)
+    except ValueError:
+        return default
+
+
+_REPO_SHARED_MAX_ENTRIES = _int_env("DEV_MEMORY_REPO_SHARED_MAX_ENTRIES", 20)
+_REPO_SHARED_MAX_ENTRY_CHARS = _int_env("DEV_MEMORY_REPO_SHARED_MAX_ENTRY_CHARS", 260)
+
+
 def _first_nonempty_line(text):
     """Return the first non-blank line of `text`, stripped. Empty string if
     `text` is all blank. Used as the comparison anchor for similarity_check
@@ -677,11 +691,8 @@ KIND_MAP = {
     "glossary": {"file": "glossary", "section": "当前有效上下文", "default_mode": "append"},
     "source": {"file": "glossary", "section": "分支源资料入口", "default_mode": "append"},
     # snapshot (section always reflects the latest state; new write replaces)
-    "progress": {"file": "progress", "section": "当前进展", "default_mode": "upsert"},
-    "next": {"file": "progress", "section": "下一步", "default_mode": "upsert"},
     "overview": {"file": "overview", "section": "当前目标", "default_mode": "upsert"},
     "scope": {"file": "overview", "section": "范围边界", "default_mode": "upsert"},
-    "stage": {"file": "overview", "section": "当前阶段", "default_mode": "upsert"},
     "constraint": {"file": "overview", "section": "关键约束", "default_mode": "upsert"},
     # repo-shared: decisions/context/source accumulate, overview/constraint snapshot
     "shared-decision": {"file": "repo_decisions", "section": "跨分支通用决策", "default_mode": "append"},
@@ -689,6 +700,8 @@ KIND_MAP = {
     "shared-source": {"file": "repo_glossary", "section": "共享入口", "default_mode": "append"},
     "shared-overview": {"file": "repo_overview", "section": "长期目标与边界", "default_mode": "upsert"},
     "shared-constraint": {"file": "repo_overview", "section": "仓库级关键约束", "default_mode": "upsert"},
+    # semantic file map: agent outputs merged mapping each session
+    "filemap": {"file": "progress", "section": "功能文件索引", "default_mode": "upsert"},
     # fallback bins always accumulate
     "unsorted": {"file": "unsorted", "section": "待分类", "default_mode": "append"},
     "pending": {"file": "pending_promotion", "section": "候选条目", "default_mode": "append"},
@@ -840,9 +853,6 @@ def _finalize_worktree_writeback(ctx, repo_root, repo_key, storage_root):
 # same kind; that's fine — the write layer upserts.
 SESSION_PAYLOAD_MAP = [
     ("overview_summary", "overview", None),
-    ("implementation_notes", "progress", None),
-    ("changes", "progress", None),
-    ("next_steps", "next", None),
     ("risks", "risk", None),
     ("memory", "glossary", None),
     ("context_updates", "glossary", None),
@@ -854,10 +864,7 @@ SESSION_PAYLOAD_MAP = [
     ("source_updates", "shared-source", None),
 ]
 
-SESSION_DIRECT_PAYLOAD_MAP = [
-    ("progress", "progress"),
-    ("next", "next"),
-]
+SESSION_DIRECT_PAYLOAD_MAP = []
 
 SESSION_EXTRA_PAYLOAD_MAP = [
     ("glossary", "glossary", None),
@@ -899,6 +906,110 @@ def decision_body(item):
     return "\n".join(parts)
 
 
+def compact_decision_body(item):
+    """Render a repo-shared decision as one short bullet.
+
+    Branch decisions can afford reason/impact substructure because they are
+    read on demand. Repo shared decisions are injected into every branch, so
+    each item must be a compact standalone rule.
+    """
+    summary = _decision_summary(item)
+    if not isinstance(item, dict):
+        return f"- {summary}"
+    extras = []
+    reason = str(item.get("reason") or "").strip()
+    impact = str(item.get("impact") or "").strip()
+    if reason:
+        extras.append(f"原因: {reason}")
+    if impact:
+        extras.append(f"适用: {impact}")
+    suffix = f"（{'；'.join(extras)}）" if extras else ""
+    return f"- {summary}{suffix}"
+
+
+def _compact_repo_shared_entry(entry, max_chars):
+    text = (entry or "").strip()
+    if not text:
+        return ""
+    if len(text) <= max_chars:
+        return text
+    first = _strip_bullet_prefix(_first_nonempty_line(text))
+    if len(first) > max_chars:
+        first = first[: max_chars - 1].rstrip() + "…"
+    return f"- {first}"
+
+
+def _prune_repo_shared_section(path, section_title, *, max_entries, max_entry_chars):
+    if max_entries <= 0:
+        return None
+    content = path.read_text(encoding="utf-8") if path.exists() else ""
+    prefix, sections = split_sections(content)
+    changed = False
+    updated = []
+    result = None
+    for existing_title, existing_body in sections:
+        if existing_title.strip() != section_title.strip():
+            updated.append((existing_title, existing_body))
+            continue
+        entries = [entry for _idx, entry in _section_top_level_entries(existing_body)]
+        if not entries:
+            updated.append((existing_title, existing_body))
+            continue
+        kept = entries[-max_entries:]
+        compacted = [_compact_repo_shared_entry(entry, max_entry_chars) for entry in kept]
+        compacted = [entry for entry in compacted if entry]
+        new_body = "\n\n".join(compacted)
+        pruned_count = max(0, len(entries) - len(kept))
+        if new_body.strip() != existing_body.strip():
+            changed = True
+        result = {
+            "file": "repo/decisions.md" if path.name == "decisions.md" else "repo/glossary.md",
+            "section": existing_title,
+            "mode": "prune",
+            "before": len(entries),
+            "after": len(compacted),
+            "pruned": pruned_count,
+            "max_entries": max_entries,
+            "max_entry_chars": max_entry_chars,
+        }
+        updated.append((existing_title, new_body))
+    if not changed:
+        return None
+    path.write_text(join_sections(prefix, updated), encoding="utf-8")
+    return result
+
+
+def prune_repo_shared_memory(paths, *, max_entries=None, max_entry_chars=None):
+    """Keep repo-shared memory small enough for SessionStart injection.
+
+    This is intentionally deterministic and conservative: newest entries win,
+    each entry is capped to its leading claim, and only repo shared sections are
+    touched. Deeper semantic cleanup still belongs to tidy/graduate.
+    """
+    max_entries = _REPO_SHARED_MAX_ENTRIES if max_entries is None else max_entries
+    max_entry_chars = _REPO_SHARED_MAX_ENTRY_CHARS if max_entry_chars is None else max_entry_chars
+    targets = (
+        ("repo_decisions", "跨分支通用决策"),
+        ("repo_glossary", "长期有效背景"),
+        ("repo_glossary", "共享入口"),
+        ("repo_glossary", "共享注意点"),
+    )
+    touched = []
+    for file_key, section in targets:
+        path = paths.get(file_key)
+        if not path:
+            continue
+        rec = _prune_repo_shared_section(
+            path,
+            section,
+            max_entries=max_entries,
+            max_entry_chars=max_entry_chars,
+        )
+        if rec:
+            touched.append(rec)
+    return touched
+
+
 # ---------------------------------------------------------------------------
 # Write primitives
 # ---------------------------------------------------------------------------
@@ -1222,7 +1333,7 @@ def command_record(args):
         shared_decision_payload_items = [
             item for item in (payload.get("shared_decisions") or []) if _decision_summary(item)
         ]
-        shared_decision_items = [decision_body(item) for item in shared_decision_payload_items]
+        shared_decision_items = [compact_decision_body(item) for item in shared_decision_payload_items]
         if shared_decision_items:
             body = "\n\n".join(shared_decision_items)
             rec = _write_or_block("shared-decision", body, source_label="payload[shared_decisions]")
@@ -1550,8 +1661,6 @@ def command_apply_summary_output(args):
 
     # Convenience summary-output fields. These mirror --summary-json but keep
     # execution in code instead of making the agent compose CLI calls.
-    add_write("progress", payload.get("progress"), source="progress")
-    add_write("next", payload.get("next"), source="next")
     for item in payload.get("decisions") or []:
         add_write("decision", _decision_content(item), source="decisions")
     for item in payload.get("risks") or []:
@@ -1559,12 +1668,27 @@ def command_apply_summary_output(args):
     for item in payload.get("glossary") or []:
         add_write("glossary", item, source="glossary")
     for item in payload.get("shared_decisions") or []:
-        add_write("shared-decision", _decision_content(item), source="shared_decisions")
+        add_write("shared-decision", compact_decision_body(item), source="shared_decisions")
     for item in payload.get("shared_context") or []:
         add_write("shared-context", item, source="shared_context")
     for item in payload.get("shared_sources") or []:
         add_write("shared-source", item, source="shared_sources")
 
+    file_map = payload.get("file_map")
+    if isinstance(file_map, list) and file_map:
+        lines = []
+        for entry in file_map:
+            if not isinstance(entry, dict):
+                continue
+            label = entry.get("label", "").strip()
+            paths_val = entry.get("paths") or ([entry["path"]] if entry.get("path") else [])
+            if not label or not paths_val:
+                continue
+            joined = ", ".join(f"`{p}`" for p in paths_val)
+            lines.append(f"- {label}: {joined}")
+        if lines:
+            add_write("filemap", "\n".join(lines), source="file_map")
+
     # Explicit patch operations.
     for item in payload.get("upserts") or []:
         add_write(item.get("kind"), item.get("content"), mode_override="upsert", source="upserts")
@@ -1593,6 +1717,21 @@ def command_apply_summary_output(args):
             "reason": item.get("reason"),
         })
 
+    pruned = prune_repo_shared_memory(paths)
+    if pruned:
+        touched.extend(pruned)
+        for rec in pruned:
+            actions.append({
+                "op": "prune-repo-shared",
+                "file": rec["file"],
+                "section": rec["section"],
+                "before": rec["before"],
+                "after": rec["after"],
+                "pruned": rec["pruned"],
+                "max_entries": rec["max_entries"],
+                "max_entry_chars": rec["max_entry_chars"],
+            })
+
     updated_at = now_iso()
 
     if touched:

package/lib/dev_memory_common.py

@@ -581,7 +581,6 @@ def template_overview(branch_name):
             ("分支", f"- {branch_name}"),
             ("当前目标", "- 待补充"),
             ("范围边界", "- 待补充"),
-            ("当前阶段", "- 待补充"),
             ("关键约束", "- 待补充"),
         ],
     )
@@ -599,12 +598,10 @@ def template_decisions(branch_name):
 
 def template_progress(branch_name):
     return render_title_doc(
-        "当前进展",
+        "自动索引",
         [
             ("分支", f"- {branch_name}"),
             ("建议优先查看的目录", "- 待刷新"),
-            ("当前进展", "- 待补充"),
-            ("下一步", "- 待补充"),
             (
                 "自动同步区",
                 "本区由 `dev-memory-cli capture sync-working-tree` / SessionStart hook 自动刷新，请不要手工编辑。\n\n"
@@ -684,11 +681,9 @@ def template_repo_log(repo_name):
 
 def template_progress_no_git(project_name):
     return render_title_doc(
-        "当前进展（no-git 模式）",
+        "自动索引（no-git 模式）",
         [
             ("项目", f"- {project_name}"),
-            ("当前进展", "- 待补充"),
-            ("下一步", "- 待补充"),
             (
                 "自动同步区",
                 "本区由 capture / context 刷新。no-git 模式下无 git facts，保持最小骨架。\n\n"
@@ -950,6 +945,8 @@ def migrate_v1_to_v2_branch(branch_dir, branch_name):
     written = []
 
     progress_sections = list(merged_buckets.get("progress", []))
+    progress_sections = [(t, b) for t, b in progress_sections
+                         if t not in ("当前进展", "下一步")]
     if auto_block is not None:
         progress_sections.append((
             "自动同步区",
@@ -959,7 +956,7 @@ def migrate_v1_to_v2_branch(branch_dir, branch_name):
     if progress_sections:
         target = branch_dir / "progress.md"
         target.write_text(
-            render_title_doc("当前进展", [header] + progress_sections),
+            render_title_doc("自动索引", [header] + progress_sections),
             encoding="utf-8",
         )
         written.append("progress.md")
@@ -1243,7 +1240,6 @@ _CLASSIFY_PATTERNS = [
     ("decision", re.compile(r"结论[:：]|决[定议][:：]|不再|改为|采用|废弃|选择.+?不选|abandoned|adopt")),
     ("risk", re.compile(r"阻塞|注意|坑|失败|风险|卡住|gotcha|caveat|warning")),
     ("glossary", re.compile(r"即[:：]|\s即\s|指的是|对应|链接|https?://|api\s*=|缩写|术语|简称|别名")),
-    ("progress", re.compile(r"当前|已完成|下一步|commit|提交|实现|进展|todo|wip")),
 ]
 
 
@@ -1337,13 +1333,38 @@ def summarize_scopes(paths):
     return [{"scope": scope, "files": count} for scope, count in sorted(counter.items())]
 
 
+_FOCUS_EXCLUDED_PREFIXES = (
+    ".claude/", ".vscode/", ".idea/", ".git/",
+    "node_modules/", "__pycache__/", ".venv/",
+)
+
+_FOCUS_EXCLUDED_ROOT_FILES = {
+    "go.mod", "go.sum", "go.work", "go.work.sum",
+    "package.json", "package-lock.json", "pnpm-lock.yaml", "bun.lockb",
+    "tsconfig.json", "tsconfig.base.json",
+    "main.go", "main.py",
+    ".gitignore", ".editorconfig", ".prettierrc",
+    "skills-lock.json", "eden.monorepo.json",
+    "Makefile", "Dockerfile",
+}
+
+
+def _should_exclude_path(path_str):
+    if any(path_str.startswith(prefix) or path_str == prefix.rstrip("/")
+           for prefix in _FOCUS_EXCLUDED_PREFIXES):
+        return True
+    if "/" not in path_str and path_str in _FOCUS_EXCLUDED_ROOT_FILES:
+        return True
+    return False
+
+
 def _initial_parent(path_str):
-    """File path → its immediate parent directory key. Files at repo root use
-    their own file path as the focus key instead of '.', everything else uses
-    the POSIX-style parent dir string."""
+    """File path → its immediate parent directory key. Root-level files map to
+    None (skipped by callers) since individual files are not useful focus
+    directories."""
     parent = Path(path_str).parent
     if str(parent) in ("", "."):
-        return Path(path_str).as_posix()
+        return None
     return parent.as_posix()
 
 
@@ -1360,6 +1381,27 @@ def _rolled_up(key):
     return Path(key).parent.as_posix()
 
 
+def _dedup_parent_child(dirs):
+    """Remove wider parents when a more specific child exists."""
+    result = []
+    for d in dirs:
+        if any(other != d and other.startswith(d + "/") for other in dirs):
+            continue
+        result.append(d)
+    return result
+
+
+def _drop_low_weight(ranked):
+    """Drop weight-1 entries when higher-weight entries exist, since a single
+    file change doesn't carry meaningful focus signal."""
+    if not ranked:
+        return ranked
+    max_weight = ranked[0][1]
+    if max_weight < 3:
+        return ranked
+    return [(k, w) for k, w in ranked if w >= 2]
+
+
 def summarize_focus_areas(paths, limit=None):
     """Cluster changed-file paths into ≤ `limit` focus directories.
 
@@ -1374,7 +1416,14 @@ def summarize_focus_areas(paths, limit=None):
     """
     if limit is None:
         limit = FOCUS_AREA_LIMIT
-    buckets = Counter(_initial_parent(p) for p in paths)
+    filtered = [p for p in paths if not _should_exclude_path(p)]
+    buckets = Counter()
+    for p in filtered:
+        key = _initial_parent(p)
+        if key is not None:
+            buckets[key] += 1
+    if not buckets:
+        return []
     while len(buckets) > limit:
         proposals = {}  # rolled_key -> [sum_count, [original_keys...]]
         for key, count in buckets.items():
@@ -1395,7 +1444,9 @@ def summarize_focus_areas(paths, limit=None):
             buckets.pop(k)
         buckets[winner_key] = buckets.get(winner_key, 0) + winner_count
     ranked = sorted(buckets.items(), key=lambda kv: (-kv[1], kv[0]))
-    return [k for k, _ in ranked[:limit]]
+    ranked = _drop_low_weight(ranked)
+    result = [k for k, _ in ranked[:limit]]
+    return _dedup_parent_child(result)
 
 
 # Number of recent commits whose touched files contribute to the "focus area"
@@ -1480,6 +1531,8 @@ def merged_focus_areas(new_paths, existing, limit=None):
     """
     if limit is None:
         limit = FOCUS_AREA_LIMIT
+    existing = [d for d in existing
+                if "/" in d and not _should_exclude_path(d)]
     if not existing:
         return summarize_focus_areas(new_paths, limit=limit)
 
@@ -1530,7 +1583,9 @@ def merged_focus_areas(new_paths, existing, limit=None):
 
     new_buckets = Counter()
     for p in uncovered:
-        new_buckets[_initial_parent(p)] += 1
+        key = _initial_parent(p)
+        if key is not None and not _should_exclude_path(p):
+            new_buckets[key] += 1
 
     while len(new_buckets) > remaining_budget:
         proposals = {}
@@ -1595,7 +1650,9 @@ def merged_focus_areas(new_paths, existing, limit=None):
         seen.add(d)
         selected.append((d, weight))
     selected.sort(key=lambda kv: (-kv[1], kv[0]))
-    return [d for d, _ in selected[:limit]]
+    selected = _drop_low_weight(selected)
+    result = [d for d, _ in selected[:limit]]
+    return _dedup_parent_child(result)
 
 
 def build_auto_block(facts):

package/lib/dev_memory_context.py

@@ -103,6 +103,33 @@ def command_sync(args):
     print(json.dumps(payload, ensure_ascii=False, indent=2))
 
 
+def command_injection_preview(args):
+    """Render the SessionStart injection context for a given repo_key + branch,
+    without needing an actual git working tree. Used by the UI panel."""
+    sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "scripts" / "hooks"))
+    from _common import _build_context_from_assets  # noqa: E402
+    from dev_memory_common import asset_paths as _asset_paths  # noqa: E402
+
+    storage_root = Path(args.context_dir) if args.context_dir else Path.home() / ".dev-memory" / "repos"
+    repo_dir = storage_root / args.repo_key
+    branch_dir = repo_dir / "branches" / args.branch.replace("/", "__")
+
+    if not branch_dir.exists():
+        print(json.dumps({"error": f"branch dir not found: {branch_dir}"}, ensure_ascii=False))
+        return 1
+
+    paths = _asset_paths(repo_dir, branch_dir)
+    assets = {
+        "repo_dir": repo_dir,
+        "branch_dir": branch_dir,
+        "branch_name": args.branch,
+        "paths": paths,
+    }
+    context = _build_context_from_assets(assets, full=True)
+    print(json.dumps({"context": context or ""}, ensure_ascii=False))
+    return 0
+
+
 def main():
     parser = argparse.ArgumentParser(description="Read or refresh repo+branch development assets.")
     subparsers = parser.add_subparsers(dest="command", required=True)
@@ -113,12 +140,19 @@ def main():
         sub.add_argument("--context-dir", help="User-home storage root. Defaults to ~/.dev-memory/repos")
         sub.add_argument("--branch", help="Branch name. Defaults to the current checked-out branch")
 
+    preview_sub = subparsers.add_parser("injection-preview")
+    preview_sub.add_argument("--repo-key", required=True, help="Repo key (directory name under storage root)")
+    preview_sub.add_argument("--branch", required=True, help="Branch name (original, with slashes)")
+    preview_sub.add_argument("--context-dir", help="Storage root. Defaults to ~/.dev-memory/repos")
+
     args = parser.parse_args()
     try:
         if args.command == "show":
             command_show(args)
-        else:
+        elif args.command == "sync":
             command_sync(args)
+        elif args.command == "injection-preview":
+            return command_injection_preview(args)
     except Exception as exc:
         print(f"ERROR: {exc}", file=sys.stderr)
         return 1

package/lib/dev_memory_read.py

@@ -0,0 +1,317 @@
+#!/usr/bin/env python3
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from dev_memory_common import (  # noqa: E402
+    DEV_MEMORY_ID_FILE,
+    LEGACY_ID_FILE,
+    MANAGED_FILES,
+    asset_paths,
+    detect_no_git_mode,
+    get_branch_paths,
+    read_json,
+)
+
+
+BRANCH_FILE_KEYS = (
+    "overview",
+    "progress",
+    "decisions",
+    "risks",
+    "glossary",
+    "unsorted",
+    "pending_promotion",
+    "log",
+    "manifest",
+)
+
+REPO_FILE_KEYS = (
+    "repo_overview",
+    "repo_decisions",
+    "repo_glossary",
+    "repo_log",
+    "repo_manifest",
+)
+
+READ_ORDER = (
+    "glossary",
+    "decisions",
+    "risks",
+    "overview",
+    "repo_decisions",
+    "repo_glossary",
+    "repo_overview",
+    "unsorted",
+    "pending_promotion",
+    "log",
+)
+
+
+def _resolve_paths(repo, context_dir=None, branch=None):
+    repo_path = Path(repo).expanduser().resolve()
+    if detect_no_git_mode(repo_path) and not (
+        (repo_path / DEV_MEMORY_ID_FILE).exists()
+        or (repo_path / LEGACY_ID_FILE).exists()
+    ):
+        raise RuntimeError(
+            "no-git memory is not initialized; read refuses to create a .dev-memory-id. "
+            "Initialize by writing via capture/setup first, or pass a Git repo path."
+        )
+    repo_root, branch_name, branch_key, storage_root, repo_key, repo_dir, branch_dir = get_branch_paths(
+        repo, context_dir, branch
+    )
+    paths = asset_paths(repo_dir, branch_dir)
+    return {
+        "repo_root": repo_root,
+        "branch_name": branch_name,
+        "branch_key": branch_key,
+        "storage_root": storage_root,
+        "repo_key": repo_key,
+        "repo_dir": repo_dir,
+        "branch_dir": branch_dir,
+        "paths": paths,
+    }
+
+
+def _existing_branch_dirs(repo_dir):
+    branches_dir = repo_dir / "branches"
+    if not branches_dir.exists():
+        return []
+    result = []
+    for path in sorted(branches_dir.iterdir(), key=lambda p: p.name):
+        if not path.is_dir() or path.name == "_archived":
+            continue
+        manifest = read_json(path / "manifest.json")
+        result.append(
+            {
+                "branch_key": path.name,
+                "branch": manifest.get("branch") or path.name.replace("__", "/"),
+                "path": str(path),
+            }
+        )
+    return result
+
+
+def _existing_files(paths, keys):
+    files = {}
+    for key in keys:
+        path = paths[key]
+        files[key] = {
+            "path": str(path),
+            "exists": path.exists(),
+        }
+    return files
+
+
+def _memory_files_for_dir(memory_dir):
+    for file_name in MANAGED_FILES:
+        path = memory_dir / file_name
+        if path.exists() and path.is_file():
+            yield path
+
+
+def _dedupe_paths(paths):
+    seen = set()
+    result = []
+    for path in paths:
+        resolved = path.resolve()
+        if resolved in seen:
+            continue
+        seen.add(resolved)
+        result.append(path)
+    return result
+
+
+def _scope_files(resolved, scope):
+    paths = resolved["paths"]
+    repo_dir = resolved["repo_dir"]
+    branch_dir = resolved["branch_dir"]
+    files = []
+
+    if scope in ("branch", "current"):
+        files.extend(paths[key] for key in BRANCH_FILE_KEYS)
+    if scope in ("repo", "current"):
+        files.extend(paths[key] for key in REPO_FILE_KEYS)
+    if scope == "all-branches":
+        files.extend(paths[key] for key in REPO_FILE_KEYS)
+        branches_dir = repo_dir / "branches"
+        if branches_dir.exists():
+            for child in sorted(branches_dir.iterdir(), key=lambda p: p.name):
+                if child.is_dir() and child.name != "_archived":
+                    files.extend(_memory_files_for_dir(child))
+    if scope == "archived":
+        archived_dir = repo_dir / "branches" / "_archived"
+        if archived_dir.exists():
+            for child in sorted(archived_dir.iterdir(), key=lambda p: p.name):
+                if child.is_dir():
+                    files.extend(_memory_files_for_dir(child))
+    if scope == "all":
+        files.extend(paths[key] for key in REPO_FILE_KEYS)
+        branches_dir = repo_dir / "branches"
+        if branches_dir.exists():
+            for child in sorted(branches_dir.rglob("*"), key=lambda p: p.as_posix()):
+                if child.is_dir() and child.name != "_archived":
+                    files.extend(_memory_files_for_dir(child))
+
+    return [p for p in _dedupe_paths(files) if p.exists() and p.is_file()]
+
+
+def _make_matchers(queries, *, regex=False, case_sensitive=False):
+    if not queries:
+        raise ValueError("pass at least one --query")
+    if regex:
+        flags = 0 if case_sensitive else re.IGNORECASE
+        return [(q, re.compile(q, flags)) for q in queries]
+    if case_sensitive:
+        return [(q, q) for q in queries]
+    return [(q, q.lower()) for q in queries]
+
+
+def _line_matches(line, matchers, *, regex=False, case_sensitive=False):
+    haystack = line if case_sensitive else line.lower()
+    matched = []
+    for raw, matcher in matchers:
+        if regex:
+            if matcher.search(line):
+                matched.append(raw)
+        elif matcher in haystack:
+            matched.append(raw)
+    return matched
+
+
+def _context_lines(lines, line_no, radius):
+    if radius <= 0:
+        return []
+    start = max(1, line_no - radius)
+    end = min(len(lines), line_no + radius)
+    result = []
+    for current in range(start, end + 1):
+        if current == line_no:
+            continue
+        result.append({"line": current, "text": lines[current - 1]})
+    return result
+
+
+def command_show(args):
+    resolved = _resolve_paths(args.repo, args.context_dir, args.branch)
+    paths = resolved["paths"]
+    payload = {
+        "repo_root": str(resolved["repo_root"]),
+        "repo_key": resolved["repo_key"],
+        "branch": resolved["branch_name"],
+        "branch_key": resolved["branch_key"],
+        "storage_root": str(resolved["storage_root"]),
+        "repo_dir": str(resolved["repo_dir"]),
+        "branch_dir": str(resolved["branch_dir"]),
+        "repo_exists": resolved["repo_dir"].exists(),
+        "branch_exists": resolved["branch_dir"].exists(),
+        "recommended_read_order": [
+            {"key": key, "path": str(paths[key]), "exists": paths[key].exists()}
+            for key in READ_ORDER
+            if key in paths
+        ],
+        "branch_files": _existing_files(paths, BRANCH_FILE_KEYS),
+        "repo_files": _existing_files(paths, REPO_FILE_KEYS),
+        "existing_branches": _existing_branch_dirs(resolved["repo_dir"]),
+    }
+    print(json.dumps(payload, ensure_ascii=False, indent=2))
+
+
+def command_search(args):
+    resolved = _resolve_paths(args.repo, args.context_dir, args.branch)
+    matchers = _make_matchers(args.query, regex=args.regex, case_sensitive=args.case_sensitive)
+    files = _scope_files(resolved, args.scope)
+    hits = []
+
+    for path in files:
+        try:
+            lines = path.read_text(encoding="utf-8").splitlines()
+        except UnicodeDecodeError:
+            continue
+        for idx, line in enumerate(lines, start=1):
+            matched_queries = _line_matches(
+                line,
+                matchers,
+                regex=args.regex,
+                case_sensitive=args.case_sensitive,
+            )
+            if not matched_queries:
+                continue
+            hits.append(
+                {
+                    "path": str(path),
+                    "line": idx,
+                    "text": line,
+                    "matched_queries": matched_queries,
+                    "context": _context_lines(lines, idx, args.context_lines),
+                }
+            )
+            if len(hits) >= args.max_hits:
+                break
+        if len(hits) >= args.max_hits:
+            break
+
+    payload = {
+        "repo_root": str(resolved["repo_root"]),
+        "repo_key": resolved["repo_key"],
+        "branch": resolved["branch_name"],
+        "branch_key": resolved["branch_key"],
+        "repo_dir": str(resolved["repo_dir"]),
+        "branch_dir": str(resolved["branch_dir"]),
+        "scope": args.scope,
+        "queries": args.query,
+        "regex": args.regex,
+        "searched_files": [str(p) for p in files],
+        "hit_count": len(hits),
+        "hits": hits,
+    }
+    print(json.dumps(payload, ensure_ascii=False, indent=2))
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Locate and search dev-memory files for the current repo/branch without scanning global memory."
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    show = subparsers.add_parser("show", help="Show authoritative memory paths for a repo/branch.")
+    show.add_argument("--repo", default=".", help="Path inside the target Git repository")
+    show.add_argument("--context-dir", help="User-home storage root. Defaults to ~/.dev-memory/repos")
+    show.add_argument("--branch", help="Branch name. Defaults to the current checked-out branch")
+
+    search = subparsers.add_parser("search", help="Search memory files under the resolved repo memory directory.")
+    search.add_argument("--repo", default=".", help="Path inside the target Git repository")
+    search.add_argument("--context-dir", help="User-home storage root. Defaults to ~/.dev-memory/repos")
+    search.add_argument("--branch", help="Branch name. Defaults to the current checked-out branch")
+    search.add_argument(
+        "--scope",
+        choices=("current", "branch", "repo", "all-branches", "archived", "all"),
+        default="current",
+        help="Which memory files to search. Defaults to current branch + repo shared layer.",
+    )
+    search.add_argument("--query", action="append", required=True, help="Literal query. Repeat for OR matching.")
+    search.add_argument("--regex", action="store_true", help="Treat --query values as Python regex patterns.")
+    search.add_argument("--case-sensitive", action="store_true")
+    search.add_argument("--context-lines", type=int, default=1, help="Neighboring lines to include around each hit.")
+    search.add_argument("--max-hits", type=int, default=80)
+
+    args = parser.parse_args()
+    try:
+        if args.command == "show":
+            command_show(args)
+        else:
+            command_search(args)
+    except Exception as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/lib/dev_memory_setup.py

@@ -102,8 +102,6 @@ def command_init(args):
 
 _SETUP_KIND_TO_TARGET = {
     "decision": ("decisions", "关键决策与原因"),
-    "progress": ("progress", "当前进展"),
-    "next": ("progress", "下一步"),
     "risk": ("risks", "阻塞与注意点"),
     "glossary": ("glossary", "当前有效上下文"),
     "source": ("glossary", "分支源资料入口"),

package/lib/ui-app.html

@@ -840,6 +840,10 @@ function renderContent() {
     content.appendChild(bs);
   }
 
+  var previewBtn = el("button", { class: "icon-btn", style: "margin-bottom: 16px;" }, "👁 注入预览");
+  previewBtn.onclick = function () { openInjectionPreview(repo.key, cur.name); };
+  content.appendChild(previewBtn);
+
   var branchMdFiles = cur.files.filter(function (f) { return f.name.endsWith(".md"); });
   if (branchMdFiles.length === 0) {
     content.appendChild(el("div", { class: "empty-state" }, "该分支暂无记忆文件"));
@@ -989,6 +993,43 @@ function closeModal() {
   modalState.editing = false;
 }
 
+function openInjectionPreview(repoKey, branchName) {
+  modalState.relPath = null;
+  modalState.text = "";
+  modalState.editing = false;
+  q("#modalTitle").textContent = "注入预览 — " + branchName;
+  q("#modalEdit").hidden = true;
+  q("#modalSave").hidden = true;
+  q("#modalCancel").hidden = true;
+  setModalStatus("");
+  var body = q("#modalBody");
+  body.innerHTML = "";
+  body.appendChild(el("span", { class: "loading" }, "生成注入预览…"));
+  q("#modal").classList.add("open");
+
+  fetch("/api/injection-preview?repo=" + encodeURIComponent(repoKey) + "&branch=" + encodeURIComponent(branchName))
+    .then(function (r) { return r.json(); })
+    .then(function (data) {
+      body.innerHTML = "";
+      if (data.error) {
+        body.appendChild(el("pre", { class: "raw" }, "错误：" + data.error));
+        return;
+      }
+      var text = data.context || "(空)";
+      var pre = document.createElement("pre");
+      pre.className = "raw";
+      pre.style.whiteSpace = "pre-wrap";
+      pre.style.wordBreak = "break-word";
+      pre.textContent = text;
+      body.appendChild(pre);
+      setModalStatus(text.length + " 字符", "success");
+    })
+    .catch(function (err) {
+      body.innerHTML = "";
+      body.appendChild(el("pre", { class: "raw" }, "请求失败：" + err.message));
+    });
+}
+
 function loadTree() {
   q("#meta").textContent = "加载中…";
   q("#repoList").innerHTML = '<div class="loading">加载中…</div>';

package/lib/ui-server.js

@@ -201,6 +201,42 @@ function writeFileSafely(fullPath, content) {
   };
 }
 
+const CONTEXT_SCRIPT = path.join(__dirname, "dev_memory_context.py");
+
+function runInjectionPreview(repoKey, branch) {
+  return new Promise((resolve, reject) => {
+    const args = [
+      CONTEXT_SCRIPT,
+      "injection-preview",
+      "--repo-key", repoKey,
+      "--branch", branch,
+      "--context-dir", getStorageRoot(),
+    ];
+    const child = spawn(process.env.DEV_MEMORY_PYTHON || "python3", args, {
+      cwd: __dirname,
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: 15000,
+    });
+    const chunks = [];
+    child.stdout.on("data", (d) => chunks.push(d));
+    let stderr = "";
+    child.stderr.on("data", (d) => { stderr += d.toString(); });
+    child.on("close", (code) => {
+      const stdout = Buffer.concat(chunks).toString("utf8");
+      if (code !== 0) {
+        reject(new Error(stderr || `exit ${code}`));
+        return;
+      }
+      try {
+        resolve(JSON.parse(stdout));
+      } catch (e) {
+        reject(new Error(`invalid JSON: ${e.message}`));
+      }
+    });
+    child.on("error", reject);
+  });
+}
+
 function readAppHtml() {
   return fs.readFileSync(APP_HTML_PATH, "utf8");
 }
@@ -263,6 +299,23 @@ function start({ host = "127.0.0.1", port = 0, openBrowserFlag = true, readOnly
       res.end(JSON.stringify(tree));
       return;
     }
+    if (url.pathname === "/api/injection-preview" && isRead) {
+      const repoKey = url.searchParams.get("repo") || "";
+      const branch = url.searchParams.get("branch") || "";
+      if (!repoKey || !branch) {
+        res.writeHead(400, { "content-type": "application/json; charset=utf-8" });
+        res.end(JSON.stringify({ error: "repo and branch required" }));
+        return;
+      }
+      runInjectionPreview(repoKey, branch).then((data) => {
+        res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+        res.end(JSON.stringify(data));
+      }).catch((err) => {
+        res.writeHead(500, { "content-type": "application/json; charset=utf-8" });
+        res.end(JSON.stringify({ error: err.message }));
+      });
+      return;
+    }
     if (url.pathname === "/api/file" && isRead) {
       const rel = url.searchParams.get("path") || "";
       const full = resolveSafePath(rel);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dev-memory-cli",
-  "version": "0.18.3",
+  "version": "0.20.0",
   "description": "CLI for dev-memory hooks and repo-local setup (formerly @xluos/dev-assets-cli)",
   "license": "MIT",
   "repository": {

package/scripts/hooks/_common.py

@@ -200,6 +200,27 @@ def extract_section(path, title):
     return None if is_placeholder(body) else body
 
 
+def extract_repo_file_body(path):
+    """Extract full body of a repo-level file, skipping the H1 title and
+    ``## 仓库`` metadata section. Placeholder-only sections within the file
+    are dropped individually so that real content in sibling sections is
+    preserved. Returns None when nothing substantive remains."""
+    if not path.exists():
+        return None
+    content = path.read_text(encoding="utf-8")
+    content = re.sub(r"^## 仓库\n\n.*?(?=^## |\Z)", "", content, count=1,
+                     flags=re.MULTILINE | re.DOTALL)
+    content = re.sub(r"^# .+\n*", "", content, count=1)
+    sections = re.split(r"(?=^## )", content, flags=re.MULTILINE)
+    kept = []
+    for sec in sections:
+        sec_body = strip_managed_markers(sec).strip()
+        if sec_body and not is_placeholder(sec_body):
+            kept.append(sec_body)
+    body = "\n\n".join(kept).strip()
+    return body or None
+
+
 def compact_body(text, max_lines=8, max_chars=700):
     """Compact a section body. Returns (compacted_text, was_truncated). The
     caller uses `was_truncated` to decide whether to append a "see full file"
@@ -320,28 +341,24 @@ def maybe_record_head():
 # "后续继续前要注意"; decisions.md carries "关键决策与原因"; glossary.md carries
 # "当前有效上下文".
 _FULL_SECTION_KEYS = (
+    ("progress", "功能文件索引"),
     ("progress", "建议优先查看的目录"),
+    ("repo_decisions", None),
+    ("repo_glossary", None),
+    ("glossary", "分支源资料入口"),
     ("overview", "当前目标"),
     ("overview", "范围边界"),
-    ("overview", "当前阶段"),
     ("overview", "关键约束"),
-    ("progress", "当前进展"),
-    ("risks", "阻塞与注意点"),
-    ("progress", "下一步"),
+    ("repo_overview", None),
     ("glossary", "当前有效上下文"),
+    ("risks", "阻塞与注意点"),
     ("decisions", "关键决策与原因"),
     ("risks", "后续继续前要注意"),
-    ("repo_overview", "长期目标与边界"),
-    ("repo_overview", "仓库级关键约束"),
-    ("repo_decisions", "跨分支通用决策"),
-    ("repo_glossary", "共享入口"),
 )
 
 _BRIEF_SECTION_KEYS = (
     ("overview", "当前目标"),
-    ("overview", "当前阶段"),
-    ("progress", "当前进展"),
-    ("progress", "下一步"),
+    ("glossary", "当前有效上下文"),
 )
 
 
@@ -351,17 +368,48 @@ _RECENT_FIRST_SECTIONS = {
     ("risks", "后续继续前要注意"),
     ("glossary", "当前有效上下文"),
     ("glossary", "分支源资料入口"),
-    ("repo_decisions", "跨分支通用决策"),
-    ("repo_glossary", "长期有效背景"),
-    ("repo_glossary", "共享入口"),
 }
 
+_BRANCH_REFERENCE_SECTIONS = {
+    ("glossary", "当前有效上下文"),
+    ("glossary", "分支源资料入口"),
+    ("progress", "功能文件索引"),
+}
+_BRANCH_REF_MAX_LINES = 128
+_BRANCH_REF_MAX_CHARS = 12000
+
+_REPO_LEVEL_KEYS = {
+    "repo_overview",
+    "repo_decisions",
+    "repo_glossary",
+    "repo_log",
+}
+_REPO_DISPLAY_TITLES = {
+    "repo_overview": "仓库概览",
+    "repo_decisions": "跨分支通用决策",
+    "repo_glossary": "仓库共享术语与入口",
+}
+_HIGH_PRIORITY_WRAPPERS = {
+    ("progress", "功能文件索引"): "file_map",
+    ("progress", "建议优先查看的目录"): "read_first_dirs",
+    ("repo_decisions", None): "shared_decisions",
+    ("repo_glossary", None): "long_term_context",
+}
+_REPO_MAX_LINES = 32
+_REPO_MAX_CHARS = 3000
+
 
 def _extract_sections(paths, keys):
     out = []
     for file_key, title in keys:
-        body = extract_section(paths[file_key], title)
-        out.append((title, body, file_key))
+        if title is None:
+            body = extract_repo_file_body(paths[file_key])
+            display_title = _REPO_DISPLAY_TITLES.get(file_key, paths[file_key].stem)
+        else:
+            body = extract_section(paths[file_key], title)
+            display_title = title
+        wrapper = _HIGH_PRIORITY_WRAPPERS.get((file_key, title))
+        out.append((display_title, body, file_key, title, wrapper))
     return out
 
 
@@ -396,14 +444,25 @@ def _build_context_from_assets(assets, *, full=True, heading=None):
     # the footer's directory header (.../branches/<branch>/).
 
     any_truncated = False
-    for title, body, file_key in sections:
+    for title, body, file_key, source_title, wrapper in sections:
         if not body:
             continue
-        if (file_key, title) in _RECENT_FIRST_SECTIONS:
-            compacted, truncated = compact_recent_body(body, max_lines=max_lines, max_chars=max_chars)
+        if full and file_key in _REPO_LEVEL_KEYS:
+            eff_lines, eff_chars = _REPO_MAX_LINES, _REPO_MAX_CHARS
+        elif full and (file_key, source_title) in _BRANCH_REFERENCE_SECTIONS:
+            eff_lines, eff_chars = _BRANCH_REF_MAX_LINES, _BRANCH_REF_MAX_CHARS
+        else:
+            eff_lines, eff_chars = max_lines, max_chars
+        if (file_key, source_title) in _RECENT_FIRST_SECTIONS:
+            compacted, truncated = compact_recent_body(body, max_lines=eff_lines, max_chars=eff_chars)
+        else:
+            compacted, truncated = compact_body(body, max_lines=eff_lines, max_chars=eff_chars)
+        if wrapper:
+            block = f"<{wrapper}>\n{compacted}\n</{wrapper}>"
+        elif full and file_key in _REPO_LEVEL_KEYS:
+            block = compacted
         else:
-            compacted, truncated = compact_body(body, max_lines=max_lines, max_chars=max_chars)
-        block = f"{title}:\n{compacted}"
+            block = f"{title}:\n{compacted}"
         if truncated:
             file_path = paths.get(file_key)
             if file_path is not None:
@@ -825,31 +884,47 @@ transcript 过滤（extract-core 已执行；这里是核对规则）：
 
 写入原则：
 - 先结合现有记忆判断每条信息是新增、改写、删除/归档还是跳过。
-- 已完成且不再影响后续工作的状态，不要追加成“已完成 XXX”；应覆盖 progress/next，或通过 rewrite-entry/tidy 删除旧条目。
+- 已完成且不再影响后续工作的状态，不要追加——通过 rewrite-entry/tidy 删除旧条目。
 - 旧结论失效时优先 rewrite-entry 或 tidy 删除，不要追加一条相反结论让两条并存。
-- progress / next 是当前态，用 upsert 语义；decision / risk / glossary 是累计条目，但也要避免重复。
+- decision / risk / glossary 是累计条目，注意避免重复。
 - 只在确有新增或更新时写入。没有有效新增时只输出 `skip_reason`，代码会把 job 标记为 skipped。
+- 不要写”当前进展”、”下一步”、”当前阶段”等时效性状态——这些天然会过期；记忆应聚焦稳定的决策、约束、上下文和参考信息。
+
+repo 共享层淘汰规则：
+- `shared_decisions` / `shared_context` / `shared_sources` 是跨分支长期记忆，不是会话归档，也不是分支任务备忘。
+- 只有“以后所有分支都需要优先知道”的规则、背景、入口才写 shared；普通业务细节、一次性调试结论、某分支当前状态写 branch 层或跳过。
+- repo 共享层默认只保留最重要的少量条目（约 10-20 条）；新增 shared 前先看 existing_memory，若旧条目已过时、重复、太长，优先输出 `rewrites` / `deletes` 压缩旧内容。
+- `shared_decisions` 的 summary 必须是一条短完整规则；除非必要，不要填 reason/impact。不要把“结论/原因/影响范围”拆成三条长期条目。
+- `shared_context` / `shared_sources` 每条尽量不超过 1 句；不要把交接说明、模块清单、会议纪要整段塞入 repo 共享层。
+- 代码落盘后还会自动对 repo shared section 做确定性修剪：保留最近约 20 条，单条过长会压成首句。因此你应主动写得精炼，避免重要信息被截断。
+
+file_map（功能文件索引）：
+- 用途：让后续 agent 听到”改下操作弹窗”就能直接定位文件，不用搜索。
+- 每条 label 是业务语义名（页面/弹窗/侧拉/组件/表单等），paths 是对应文件的仓库相对路径。
+- 粒度到组件/功能即可，不要写具体逻辑，agent 定位到文件后自己读。
+- 增量 merge：读 existing_memory 里已有的功能文件索引，结合本次会话改动判断——新涉及的组件加入、已有条目路径变了就更新、描述不准的修正、分支里已删除的组件移除。
+- 输出合并后的**完整映射**（不是增量 diff），代码侧直接覆盖整个 section。
+- 没有文件变更或映射无变化时省略此字段。
 
 输出要求：
 - 只输出一个 summary-output JSON 对象，不要输出 markdown fence、解释文字或命令。
 - summary-output 格式：
   {{
-    "title": "简短标题",
-    "progress": "当前进展，覆盖 progress.md 的当前进展 section",
-    "next": "下一步，覆盖 progress.md 的下一步 section",
-    "decisions": [{{"summary": "结论", "reason": "为什么", "impact": "影响范围"}}],
-    "risks": ["风险/坑/阻塞"],
-    "glossary": ["术语/上下文/命令/外部系统入口"],
-    "shared_decisions": [{{"summary": "跨分支规则", "reason": "为什么", "impact": "适用范围"}}],
-    "shared_context": ["仓库级长期背景"],
-    "shared_sources": ["仓库级共享入口"],
-    "upserts": [{{"kind": "progress", "content": "显式覆盖某个 kind"}}],
-    "appends": [{{"kind": "decision", "content": "显式追加某个 kind"}}],
-    "rewrites": [{{"id": "decisions::0::2", "content": "新条目", "reason": "旧结论失效"}}],
-    "deletes": [{{"id": "risks::0::1", "reason": "风险已解除"}}],
-    "skip_reason": "没有新增有效内容"
+    “title”: “简短标题”,
+    “file_map”: [{{“label”: “功能/组件名”, “paths”: [“相对路径”]}}],
+    “decisions”: [{{“summary”: “结论”, “reason”: “为什么”, “impact”: “影响范围”}}],
+    “risks”: [“风险/坑/阻塞”],
+    “glossary”: [“术语/上下文/命令/外部系统入口”],
+    “shared_decisions”: [{{“summary”: “短句跨分支规则”}}],
+    “shared_context”: [“一句话仓库级长期背景”],
+    “shared_sources”: [“一句话仓库级共享入口”],
+    “upserts”: [{{“kind”: “overview”, “content”: “覆盖某个 kind”}}],
+    “appends”: [{{“kind”: “decision”, “content”: “追加某个 kind”}}],
+    “rewrites”: [{{“id”: “decisions::0::2”, “content”: “新条目”, “reason”: “旧结论失效”}}],
+    “deletes”: [{{“id”: “risks::0::1”, “reason”: “风险已解除”}}],
+    “skip_reason”: “没有新增有效内容”
   }}
-- 字段可省略；不要输出空字段。若只更新 progress/next，只传这两个字段即可。
+- 字段可省略；不要输出空字段。
 - 发现旧条目需要改写/删除时，不要追加矛盾条目。优先在 summary-output 的 rewrites/deletes 中表达。
 - 不要调用任何 dev-memory-cli 命令；代码会校验 JSON、落盘、处理 dedup，并移动 job。
 
@@ -860,13 +935,57 @@ SUMMARY_INPUT_JSON:
 """
 
 
+def _is_pid_alive(pid):
+    try:
+        os.kill(pid, 0)
+        return True
+    except (OSError, ProcessLookupError):
+        return False
+
+
+def _check_worker_lock(queue_dir, job_id):
+    """Return True if a live worker already holds the lock for this job."""
+    lock_path = Path(queue_dir) / "locks" / f"{job_id}.lock"
+    if not lock_path.exists():
+        return False
+    try:
+        content = lock_path.read_text(encoding="utf-8").strip()
+        pid = int(content)
+        if _is_pid_alive(pid):
+            return True
+        lock_path.unlink(missing_ok=True)
+    except (ValueError, OSError):
+        lock_path.unlink(missing_ok=True)
+    return False
+
+
+def _is_job_already_terminal(queue_dir, job_id):
+    """Return the terminal state if this job is already done/skipped, else None."""
+    for state in ("done", "skipped"):
+        if (Path(queue_dir) / state / f"{job_id}.json").exists():
+            return state
+    return None
+
+
 def maybe_start_summary_agent(job_path, queue_dir=None, job_id=None):
     if os.environ.get("DEV_MEMORY_DISABLE_SESSION_SUMMARY_AGENT", "").strip():
         return None
     command = session_summary_command()
     if not command:
         return None
-    summary_session_id = f"dev-memory-summary-{job_id or Path(job_path).stem}"
+    effective_queue_dir = queue_dir or Path(job_path).parent.parent
+    effective_job_id = job_id or Path(job_path).stem
+
+    terminal = _is_job_already_terminal(effective_queue_dir, effective_job_id)
+    if terminal:
+        log(f"[dev-memory] summary agent skipped: job {effective_job_id} already {terminal}")
+        return None
+
+    if _check_worker_lock(effective_queue_dir, effective_job_id):
+        log(f"[dev-memory] summary agent skipped: worker already running for {effective_job_id}")
+        return None
+
+    summary_session_id = f"dev-memory-summary-{effective_job_id}"
     log_path = None
     if queue_dir is not None and job_id:
         runs_dir = Path(queue_dir) / "runs"
@@ -879,9 +998,9 @@ def maybe_start_summary_agent(job_path, queue_dir=None, job_id=None):
         "--job",
         str(job_path),
         "--queue-dir",
-        str(queue_dir or Path(job_path).parent.parent),
+        str(effective_queue_dir),
         "--job-id",
-        str(job_id or Path(job_path).stem),
+        str(effective_job_id),
         "--agent-command",
         command,
         "--summary-session-id",

package/suite-manifest.json

@@ -1,6 +1,7 @@
 {
   "suite_name": "dev-memory-skill-suite",
   "skills": [
+    "dev-memory-read",
     "dev-memory-setup",
     "dev-memory-capture",
     "dev-memory-graduate",