@xluos/dev-assets-cli 0.3.1 → 0.4.0

package/README.md

@@ -13,6 +13,18 @@ This repository packages a small skill suite for one job: keep development memor
 Detailed guide:
 
 - [docs/dev-asset-skill-suite-guide.md](docs/dev-asset-skill-suite-guide.md)
+- [docs/workspace-mode.md](docs/workspace-mode.md) — multi-repo workspace mode (new)
+
+## Workspace Mode
+
+When cwd is not itself a git repo but its first-level subdirectories are (a "workspace" layout hosting multiple cloned repos), the suite switches to **workspace mode** automatically:
+
+- `SessionStart`: injects full memory for the **primary repo** (from env `DEV_ASSETS_PRIMARY_REPO`, basename) plus a brief overview of the other repos; when no primary is set, all repos get the brief form.
+- `Stop` / `SessionEnd`: records HEAD for every repo in the workspace (idempotent).
+- `PreCompact`: refreshes working-tree navigation for every repo (Claude only).
+- `dev-assets-sync` / `-context` / `-update`: pass `--repo <basename>` explicitly, or rely on `DEV_ASSETS_PRIMARY_REPO` for the default target.
+
+Single-repo cwd behavior is unchanged. See [docs/workspace-mode.md](docs/workspace-mode.md) for the full design.
 
 ## Install with `npx skills`
 

package/lib/dev_asset_common.py

@@ -162,7 +162,34 @@ def detect_repo_identity(repo_root):
     }
 
 
+def _resolve_workspace_repo(repo):
+    """If `repo` points to a workspace root (cwd is not a git repo, but first-level
+    subdirs are), redirect to the primary repo via `DEV_ASSETS_PRIMARY_REPO` env.
+    Single-repo case returns `repo` unchanged. Raises in workspace mode when
+    primary is unset or does not match an existing subdir, so callers see a
+    clear error instead of git failing later.
+    """
+    if not detect_workspace_mode(repo):
+        return repo
+    primary = os.environ.get("DEV_ASSETS_PRIMARY_REPO", "").strip()
+    repos_in_ws = list_repos_in_workspace(repo)
+    names = [p.name for p in repos_in_ws]
+    if not primary:
+        raise RuntimeError(
+            f"workspace mode detected at '{repo}': pass --repo <basename> explicitly "
+            f"(one of: {names}) or set DEV_ASSETS_PRIMARY_REPO env."
+        )
+    match = next((p for p in repos_in_ws if p.name == primary), None)
+    if match is None:
+        raise RuntimeError(
+            f"workspace mode: DEV_ASSETS_PRIMARY_REPO='{primary}' not found in '{repo}'. "
+            f"Available: {names}."
+        )
+    return str(match)
+
+
 def get_branch_paths(repo, context_dir=None, branch=None):
+    repo = _resolve_workspace_repo(repo)
     repo_root = detect_repo_root(repo)
     branch_name = branch or detect_branch(repo_root)
     branch_key = sanitize_branch_name(branch_name)
@@ -173,6 +200,53 @@ def get_branch_paths(repo, context_dir=None, branch=None):
     return repo_root, branch_name, branch_key, storage_root, identity["repo_key"], repo_dir, branch_dir
 
 
+def detect_workspace_mode(cwd=None):
+    """Return True iff cwd is not inside any git repo yet has first-level
+    subdirectories that are git repos. Purely additive — existing single-repo
+    behavior (cwd inside a git repo) returns False.
+    """
+    base = Path(cwd or ".").resolve()
+    if not base.exists() or not base.is_dir():
+        return False
+    probe = run_git(["rev-parse", "--show-toplevel"], cwd=base, check=False)
+    if probe.returncode == 0 and probe.stdout.strip():
+        return False
+    return bool(list_repos_in_workspace(base))
+
+
+def list_repos_in_workspace(cwd=None):
+    """First-level subdirectories of cwd that are git repos. Sorted by name.
+    Returns [] when cwd has none or isn't readable. `.git` may be a dir or a
+    file (worktree pointer); both count.
+    """
+    base = Path(cwd or ".").resolve()
+    repos = []
+    try:
+        entries = sorted(base.iterdir(), key=lambda p: p.name)
+    except (OSError, PermissionError):
+        return []
+    for entry in entries:
+        if not entry.is_dir():
+            continue
+        if (entry / ".git").exists():
+            repos.append(entry)
+    return repos
+
+
+def get_all_branch_paths(cwd=None, context_dir=None):
+    """Batch variant of get_branch_paths() for every repo under a workspace cwd.
+    Repos with detached HEAD or other resolution errors are skipped silently.
+    Returns [] when not in workspace mode.
+    """
+    result = []
+    for repo_path in list_repos_in_workspace(cwd):
+        try:
+            result.append(get_branch_paths(str(repo_path), context_dir=context_dir))
+        except Exception:
+            continue
+    return result
+
+
 def asset_paths(repo_dir, branch_dir):
     repo_memory_dir = repo_dir / "repo"
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xluos/dev-assets-cli",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "CLI for dev-assets hooks and repo-local setup",
   "license": "MIT",
   "scripts": {

package/scripts/hooks/_common.py

@@ -14,17 +14,26 @@ LIB_ROOT = PACKAGE_ROOT / "lib"
 if str(LIB_ROOT) not in sys.path:
     sys.path.insert(0, str(LIB_ROOT))
 
-from dev_asset_common import AUTO_END, AUTO_START, PLACEHOLDER_MARKERS, asset_paths, get_branch_paths
+from dev_asset_common import (
+    AUTO_END,
+    AUTO_START,
+    PLACEHOLDER_MARKERS,
+    asset_paths,
+    detect_workspace_mode,
+    get_branch_paths,
+    list_repos_in_workspace,
+)
 
 
 CONTEXT_SCRIPT = PACKAGE_ROOT / "skills" / "dev-assets-context" / "scripts" / "dev_asset_context.py"
 SYNC_SCRIPT = PACKAGE_ROOT / "skills" / "dev-assets-sync" / "scripts" / "dev_asset_sync.py"
 
 
-def run_python(script_path, *args):
+def run_python(script_path, *args, cwd=None):
+    work_cwd = cwd if cwd is not None else REPO_ROOT
     result = subprocess.run(
         ["python3", str(script_path), *args],
-        cwd=REPO_ROOT,
+        cwd=work_cwd,
         check=False,
         capture_output=True,
         text=True,
@@ -38,10 +47,12 @@ def log(message):
     print(message, file=sys.stderr)
 
 
-def resolve_assets():
-    repo_root, branch_name, branch_key, storage_root, repo_key, repo_dir, branch_dir = get_branch_paths(str(REPO_ROOT))
+def resolve_assets_for(repo_root):
+    """Resolve asset paths for an explicit repo root (workspace-mode friendly)."""
+    repo_root_str = str(repo_root)
+    root, branch_name, branch_key, storage_root, repo_key, repo_dir, branch_dir = get_branch_paths(repo_root_str)
     return {
-        "repo_root": repo_root,
+        "repo_root": root,
         "branch_name": branch_name,
         "branch_key": branch_key,
         "storage_root": storage_root,
@@ -52,6 +63,24 @@ def resolve_assets():
     }
 
 
+def resolve_assets():
+    return resolve_assets_for(REPO_ROOT)
+
+
+def is_workspace_mode():
+    return detect_workspace_mode(str(REPO_ROOT))
+
+
+def list_workspace_repos():
+    return list_repos_in_workspace(str(REPO_ROOT))
+
+
+def primary_repo_name():
+    """Basename of the focus repo from env; None if unset."""
+    value = os.environ.get("DEV_ASSETS_PRIMARY_REPO", "").strip()
+    return value or None
+
+
 def strip_managed_markers(text):
     return text.replace(AUTO_START, "").replace(AUTO_END, "").replace("_尚未同步_", "").strip()
 
@@ -87,54 +116,192 @@ def compact_body(text, max_lines=8, max_chars=700):
     return compacted
 
 
+def sync_context_for(repo_root):
+    return json.loads(
+        run_python(CONTEXT_SCRIPT, "sync", "--repo", str(repo_root), cwd=str(repo_root))
+    )
+
+
+def sync_working_tree_for(repo_root):
+    return json.loads(
+        run_python(SYNC_SCRIPT, "sync-working-tree", "--repo", str(repo_root), cwd=str(repo_root))
+    )
+
+
+def record_head_for(repo_root):
+    return json.loads(
+        run_python(SYNC_SCRIPT, "record-head", "--repo", str(repo_root), cwd=str(repo_root))
+    )
+
+
 def maybe_sync_context():
-    return json.loads(run_python(CONTEXT_SCRIPT, "sync", "--repo", str(REPO_ROOT)))
+    return sync_context_for(REPO_ROOT)
 
 
 def maybe_sync_working_tree():
-    return json.loads(run_python(SYNC_SCRIPT, "sync-working-tree", "--repo", str(REPO_ROOT)))
+    return sync_working_tree_for(REPO_ROOT)
 
 
 def maybe_record_head():
-    return json.loads(run_python(SYNC_SCRIPT, "record-head", "--repo", str(REPO_ROOT)))
+    return record_head_for(REPO_ROOT)
 
 
-def build_session_start_context():
-    assets = resolve_assets()
+_FULL_SECTION_KEYS = (
+    ("overview", "当前目标"),
+    ("overview", "范围边界"),
+    ("overview", "当前阶段"),
+    ("overview", "关键约束"),
+    ("development", "建议优先查看的目录"),
+    ("development", "当前进展"),
+    ("development", "阻塞与注意点"),
+    ("development", "下一步"),
+    ("context", "当前有效上下文"),
+    ("context", "关键决策与原因"),
+    ("context", "后续继续前要注意"),
+    ("repo_overview", "长期目标与边界"),
+    ("repo_overview", "仓库级关键约束"),
+    ("repo_sources", "共享入口"),
+)
+
+_BRIEF_SECTION_KEYS = (
+    ("overview", "当前目标"),
+    ("overview", "当前阶段"),
+    ("development", "当前进展"),
+    ("development", "下一步"),
+)
+
+
+def _extract_sections(paths, keys):
+    out = []
+    for file_key, title in keys:
+        body = extract_section(paths[file_key], title)
+        out.append((title, body))
+    return out
+
+
+def _build_context_from_assets(assets, *, full=True, heading=None):
     if not assets["branch_dir"].exists():
-        return (
-            "当前仓库尚未初始化 dev-assets 分支记忆。\n"
-            "如果这是需要跨会话继续的开发线，请先使用 `dev-assets-setup` 建立 repo+branch 存储。"
+        if heading is None:
+            return (
+                "当前仓库尚未初始化 dev-assets 分支记忆。\n"
+                "如果这是需要跨会话继续的开发线，请先使用 `dev-assets-setup` 建立 repo+branch 存储。"
+            )
+        return None
+
+    paths = assets["paths"]
+    keys = _FULL_SECTION_KEYS if full else _BRIEF_SECTION_KEYS
+    sections = _extract_sections(paths, keys)
+    max_lines, max_chars = (8, 700) if full else (3, 200)
+
+    parts = []
+    if heading is None:
+        parts.append(
+            f"已加载 dev-assets：repo `{assets['repo_key']}`，branch `{assets['branch_name']}`。"
         )
+        parts.append(f"主存储目录：`{assets['branch_dir']}`")
+    else:
+        parts.append(heading)
+    for title, body in sections:
+        if body:
+            parts.append(f"{title}:\n{compact_body(body, max_lines=max_lines, max_chars=max_chars)}")
+    return "\n\n".join(parts)
+
 
+def build_session_start_context():
+    assets = resolve_assets()
     try:
         maybe_sync_context()
     except Exception as exc:
         log(f"[dev-assets][SessionStart] refresh skipped: {exc}")
+    return _build_context_from_assets(assets, full=True)
 
-    paths = assets["paths"]
-    sections = [
-        ("当前目标", extract_section(paths["overview"], "当前目标")),
-        ("范围边界", extract_section(paths["overview"], "范围边界")),
-        ("当前阶段", extract_section(paths["overview"], "当前阶段")),
-        ("关键约束", extract_section(paths["overview"], "关键约束")),
-        ("建议优先查看的目录", extract_section(paths["development"], "建议优先查看的目录")),
-        ("当前进展", extract_section(paths["development"], "当前进展")),
-        ("阻塞与注意点", extract_section(paths["development"], "阻塞与注意点")),
-        ("下一步", extract_section(paths["development"], "下一步")),
-        ("当前有效上下文", extract_section(paths["context"], "当前有效上下文")),
-        ("关键决策与原因", extract_section(paths["context"], "关键决策与原因")),
-        ("后续继续前要注意", extract_section(paths["context"], "后续继续前要注意")),
-        ("仓库级长期目标与边界", extract_section(paths["repo_overview"], "长期目标与边界")),
-        ("仓库级关键约束", extract_section(paths["repo_overview"], "仓库级关键约束")),
-        ("共享入口", extract_section(paths["repo_sources"], "共享入口")),
-    ]
 
-    parts = [
-        f"已加载 dev-assets：repo `{assets['repo_key']}`，branch `{assets['branch_name']}`。",
-        f"主存储目录：`{assets['branch_dir']}`",
+def build_context_for_repo(repo_path, *, full=True, is_primary=False):
+    """Build a per-repo context block for workspace-mode SessionStart injection.
+    Returns None when the repo has no initialized branch memory or resolution fails.
+    """
+    try:
+        assets = resolve_assets_for(repo_path)
+    except Exception as exc:
+        log(f"[dev-assets] resolve failed for {Path(repo_path).name}: {exc}")
+        return None
+    try:
+        sync_context_for(repo_path)
+    except Exception as exc:
+        log(f"[dev-assets] context sync skipped for {Path(repo_path).name}: {exc}")
+    tag = "[PRIMARY] " if is_primary else ""
+    heading = (
+        f"## {tag}`{Path(repo_path).name}` — repo `{assets['repo_key']}`, branch `{assets['branch_name']}`"
+    )
+    return _build_context_from_assets(assets, full=full, heading=heading)
+
+
+def build_workspace_start_context():
+    """SessionStart context for workspace mode. Primary repo gets full memory;
+    others get a brief overview only. Returns None if no initialized repos.
+    """
+    repos = list_workspace_repos()
+    if not repos:
+        return None
+    primary = primary_repo_name()
+    primary_hit = False
+    sections = []
+    for repo_path in repos:
+        is_primary = (primary is None) or (repo_path.name == primary)
+        if is_primary:
+            primary_hit = True
+        ctx = build_context_for_repo(repo_path, full=is_primary, is_primary=is_primary)
+        if ctx:
+            sections.append(ctx)
+    if not sections:
+        return None
+    header_parts = [
+        f"已加载 dev-assets workspace 模式：共 {len(repos)} 个仓库 @ `{REPO_ROOT}`"
     ]
-    for title, body in sections:
-        if body:
-            parts.append(f"{title}:\n{compact_body(body)}")
-    return "\n\n".join(parts)
+    if primary:
+        status = "命中" if primary_hit else "未在 workspace 中找到,全部按完整模式注入"
+        header_parts.append(f"Primary 仓库提示：`{primary}` ({status})")
+    header = "\n".join(header_parts)
+    return header + "\n\n---\n\n" + "\n\n---\n\n".join(sections)
+
+
+def record_head_all_repos():
+    """Stop/SessionEnd hook helper for workspace mode. Iterates all repos; logs per-repo
+    outcome; swallows per-repo failures.
+    """
+    results = []
+    for repo_path in list_workspace_repos():
+        try:
+            assets = resolve_assets_for(repo_path)
+            if not assets["branch_dir"].exists():
+                log(f"[dev-assets] {repo_path.name}: branch memory not initialized, skip")
+                continue
+            payload = record_head_for(repo_path)
+            log(
+                f"[dev-assets] {repo_path.name}: recorded HEAD "
+                f"{payload.get('last_seen_head')} for {payload.get('branch')}"
+            )
+            results.append((repo_path.name, payload))
+        except Exception as exc:
+            log(f"[dev-assets] {repo_path.name}: record-head skipped: {exc}")
+    return results
+
+
+def sync_working_tree_all_repos():
+    """PreCompact hook helper for workspace mode. Iterates all repos."""
+    results = []
+    for repo_path in list_workspace_repos():
+        try:
+            assets = resolve_assets_for(repo_path)
+            if not assets["branch_dir"].exists():
+                log(f"[dev-assets] {repo_path.name}: branch memory not initialized, skip")
+                continue
+            payload = sync_working_tree_for(repo_path)
+            log(
+                f"[dev-assets] {repo_path.name}: refreshed working-tree navigation for "
+                f"{payload.get('branch')} ({payload.get('files_considered')} files)"
+            )
+            results.append((repo_path.name, payload))
+        except Exception as exc:
+            log(f"[dev-assets] {repo_path.name}: working-tree sync skipped: {exc}")
+    return results

package/scripts/hooks/pre_compact.py

@@ -1,10 +1,21 @@
 #!/usr/bin/env python3
 
-from _common import log, maybe_sync_working_tree, resolve_assets
+from _common import (
+    is_workspace_mode,
+    log,
+    maybe_sync_working_tree,
+    resolve_assets,
+    sync_working_tree_all_repos,
+)
 
 
 def main():
     try:
+        if is_workspace_mode():
+            results = sync_working_tree_all_repos()
+            if not results:
+                log("[dev-assets][PreCompact] workspace mode: no initialized repos refreshed")
+            return 0
         assets = resolve_assets()
         if not assets["branch_dir"].exists():
             log("[dev-assets][PreCompact] branch memory not initialized, skip")

package/scripts/hooks/session_end.py

@@ -1,10 +1,21 @@
 #!/usr/bin/env python3
 
-from _common import log, maybe_record_head, resolve_assets
+from _common import (
+    is_workspace_mode,
+    log,
+    maybe_record_head,
+    record_head_all_repos,
+    resolve_assets,
+)
 
 
 def main():
     try:
+        if is_workspace_mode():
+            results = record_head_all_repos()
+            if not results:
+                log("[dev-assets][SessionEnd] workspace mode: no initialized repos finalized")
+            return 0
         assets = resolve_assets()
         if not assets["branch_dir"].exists():
             log("[dev-assets][SessionEnd] branch memory not initialized, skip")

package/scripts/hooks/session_start.py

@@ -3,12 +3,26 @@
 import json
 import sys
 
-from _common import build_session_start_context, log
+from _common import (
+    build_session_start_context,
+    build_workspace_start_context,
+    is_workspace_mode,
+    log,
+)
+
+
+def _resolve_context():
+    if is_workspace_mode():
+        ctx = build_workspace_start_context()
+        if ctx:
+            return ctx
+        return "dev-assets workspace 模式：当前 workspace 下未发现已初始化的仓库记忆。"
+    return build_session_start_context()
 
 
 def main():
     try:
-        additional_context = build_session_start_context()
+        additional_context = _resolve_context()
         payload = {
             "hookSpecificOutput": {
                 "hookEventName": "SessionStart",

package/scripts/hooks/stop.py

@@ -1,10 +1,21 @@
 #!/usr/bin/env python3
 
-from _common import log, maybe_record_head, resolve_assets
+from _common import (
+    is_workspace_mode,
+    log,
+    maybe_record_head,
+    record_head_all_repos,
+    resolve_assets,
+)
 
 
 def main():
     try:
+        if is_workspace_mode():
+            results = record_head_all_repos()
+            if not results:
+                log("[dev-assets][Stop] workspace mode: no initialized repos recorded")
+            return 0
         assets = resolve_assets()
         if not assets["branch_dir"].exists():
             log("[dev-assets][Stop] branch memory not initialized, skip")

package/skills/dev-assets-context/SKILL.md

@@ -7,6 +7,8 @@ description: Use when starting work in any Git repository conversation on an exi
 
 把当前仓库的 branch 记忆作为默认上下文入口恢复出来；repo 共享层只在需要时补读。
 
+**Workspace mode：** cwd 是多 repo workspace 时，SessionStart 已自动注入 primary 仓库的完整记忆 + 其他仓库的简短概览。当需要切换焦点到非 primary 仓库补读完整记忆时，向脚本传递 `--repo <basename>` 明确指定。
+
 **Announce at start:** 用一句简短的话说明将先恢复当前 branch 记忆，再按需补读 repo 共享记忆。
 
 ## Workflow

package/skills/dev-assets-setup/SKILL.md

@@ -7,6 +7,8 @@ description: Use when a branch starts a new requirement stream or when the curre
 
 为当前 Git 仓库初始化用户目录下的 repo+branch 开发记忆骨架，并在初始化后主动向用户收集最小但关键的资料。
 
+**Workspace mode：** 初始化始终针对单个仓库。cwd 是多 repo workspace 时，必须通过 `--repo <basename>` 明确指定目标仓库，每个新仓库分别调用一次；绝不做批量自动初始化，避免用户意外污染不相关的仓库。
+
 **Announce at start:** 用一句简短的话说明将先初始化当前仓库的 repo+branch 记忆目录。
 
 ## Workflow

package/skills/dev-assets-sync/SKILL.md

@@ -7,6 +7,8 @@ description: Use when the current conversation reaches a commit-related checkpoi
 
 在提交相关检查点，或在当前对话已经形成需要跨会话保留的稳定结论时，把这次会话结束后仍然有价值的信息同步到当前 branch 记忆，并顺带刷新 repo 共享层的轻量元信息。
 
+**Workspace mode：** 当 cwd 是 workspace 根（不是 git repo，但一级子目录中有多个 git repo）时：向脚本传递 `--repo <basename>` 明确指定目标仓库；若未指定且 `DEV_ASSETS_PRIMARY_REPO` env 已设置，会默认落到 primary 仓库。跨仓库 sync 需要为每个仓库各调用一次。
+
 **Announce at start:** 用一句简短的话说明将先沉淀本次检查点留下的关键信息。
 
 ## Workflow

package/skills/dev-assets-update/SKILL.md

@@ -7,6 +7,8 @@ description: Use when current development memory needs to be corrected, rewritte
 
 把当前对话中已经形成且需要保留的新理解，改写到 branch 或 repo 共享层的开发记忆里，而不是只留在对话中。
 
+**Workspace mode：** cwd 是多 repo workspace 时，改写需要通过 `--repo <basename>` 明确目标仓库；未指定且 `DEV_ASSETS_PRIMARY_REPO` env 已设置则落到 primary 仓库。改写不跨仓库合并。
+
 **Announce at start:** 用一句简短的话说明将先重写相关 section，而不是继续追加历史。
 
 ## Trigger Hints