cancanneed 0.1.0

package/README.md

@@ -0,0 +1,97 @@
+# cancanneed — 代码仓库压缩骨架提取器
+
+~2K tokens 看清一个项目的全貌。基于 [codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp) 的知识图谱，
+一次查询提取语言分布、入口函数、高扇入热点、调用链路、分层聚类、复杂度热点。
+
+## 一条命令安装
+
+**npx（推荐，无需 clone）:**
+```bash
+npx cancanneed /path/to/project
+```
+
+**Hermes Agent:**
+```bash
+cp ~/cancanneed/hermes_adapter.py ~/hermes-agent/tools/ && hermes # /reset
+```
+
+**Claude Code / Codex CLI:**
+直接走 codebase-memory-mcp MCP server，然后用 `cancanneed.py` CLI：
+```bash
+# 先装 CBM (如果还没有)
+curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash
+
+# 索引 + 骨架
+git clone https://github.com/user/repo /tmp/repo
+codebase-memory-mcp cli index_repository '{"repo_path":"/tmp/repo","mode":"fast"}' --json
+python3 ~/cancanneed/cancanneed.py /tmp/repo
+```
+
+**CLI 直接使用（任何 agent，零依赖）:**
+```bash
+python3 ~/cancanneed/cancanneed.py /path/to/project        # 自动索引 + 骨架
+python3 ~/cancanneed/cancanneed.py project-name             # 已有索引的项目
+python3 ~/cancanneed/cancanneed.py                          # 列出所有可用项目
+python3 ~/cancanneed/cancanneed.py --json /path/to/project  # JSON 输出
+python3 ~/cancanneed/cancanneed.py --skill                  # 输出 SKILL.md
+```
+
+## 前置条件
+
+- Python 3.9+
+- [codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp) 二进制（用于首次索引）
+  - macOS: `brew install deusdata/codebase-memory-mcp/codebase-memory-mcp`
+  - 或: `curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash`
+- 首次索引需要 10-60s，后续对同一目录秒级返回（增量索引）
+
+## 输出示例
+
+```
+project: Users-lyx-ai-runtime-trace
+root: /Users/lyx/ai-runtime-trace
+indexed: 2026-07-11T02:54:07Z
+nodes: 2255, edges: 4486
+
+languages: Python 62, Markdown 57, YAML 21, Bash 11
+
+entry points:
+  hermes_flow/cli/analyze.py:main
+  experiments/agent-pool/cli.py:main
+  ...
+
+routes: ANY /api/admin/agents, ANY /api/admin/skills
+
+hotspots:
+  connect (56 in) -- hermes_flow/storage.py
+  span (22 in) -- hermes_flow/trace.py
+  ...
+
+layers:
+  core: storage(55 in), schemas(23 in), trace(30 in)
+  entry: agent-pool, cli, observer, tools
+  ...
+
+complexity:
+  flow_init -- O(n^5) (hermes_flow/tools.py)
+  validate_flow -- O(n^4) (hermes_flow/flow_loader.py)
+
+call chains:
+  main -> run_benchmark -> run_agent_session_simulated -> span
+  main -> _find_runs_dir -> get_runs_dir -> get_project_root
+```
+
+(~2500 chars / ~600 tokens)
+
+## 项目结构
+
+```
+~/cancanneed/
+  cancanneed.py        # 核心模块 (纯 Python, 零依赖)
+  hermes_adapter.py    # Hermes Agent 适配器 (复制到 ~/hermes-agent/tools/)
+  skills/SKILL.md      # Hermes skill
+  README.md            # 本文件
+```
+
+## License
+
+MIT

package/cancanneed.py

@@ -0,0 +1,427 @@
+#!/usr/bin/env python3
+"""cancanneed — codebase skeleton extractor.
+
+Extracts ~2K token compressed architectural skeleton from
+codebase-memory-mcp SQLite graph DB. Two modes:
+  repo_path: auto-index via CBM binary, then extract
+  project:   read pre-indexed DB directly
+"""
+
+import json, os, re, sqlite3, subprocess, sys
+from collections import Counter, defaultdict
+
+CACHE_DIR = os.path.expanduser("~/.cache/codebase-memory-mcp")
+
+def _find_cbm_binary():
+    for p in [
+        os.path.expanduser("~/.local/bin/codebase-memory-mcp"),
+        os.path.expanduser("~/.hermes/bin/codebase-memory-mcp"),
+        "/usr/local/bin/codebase-memory-mcp",
+    ]:
+        if os.path.isfile(p) and os.access(p, os.X_OK):
+            return p
+    return None
+
+def _cbm_project_name(repo_path):
+    name = repo_path.strip("/").replace("/", "-").replace(":", "-")
+    name = re.sub(r"-+", "-", name)
+    return re.sub(r"^-", "", name)
+
+def _ensure_indexed(repo_path):
+    cbm = _find_cbm_binary()
+    if not cbm:
+        return None, "CBM binary not found. Install codebase-memory-mcp first."
+    repo_path = os.path.abspath(repo_path)
+    if not os.path.isdir(repo_path):
+        return None, "Not a directory: %s" % repo_path
+    pname = _cbm_project_name(repo_path)
+    db_path = os.path.join(CACHE_DIR, pname + ".db")
+    if os.path.isfile(db_path):
+        return db_path, None
+    print("cancanneed: indexing %s ..." % repo_path, file=sys.stderr)
+    try:
+        cmd = [cbm, "cli", "index_repository",
+               json.dumps({"repo_path": repo_path, "mode": "fast"}), "--json"]
+        proc = subprocess.run(cmd, capture_output=True, text=True, timeout=600)
+        if proc.returncode != 0:
+            return None, "CBM index failed (%d): %s" % (proc.returncode, proc.stderr[:200])
+        if not os.path.isfile(db_path):
+            return None, "CBM finished but .db not generated"
+        return db_path, None
+    except subprocess.TimeoutExpired:
+        return None, "CBM index timeout"
+    except Exception as e:
+        return None, "CBM error: %s" % str(e)
+
+_EXT_LANG = {
+    ".py": "Python", ".js": "JavaScript", ".ts": "TypeScript", ".tsx": "TSX",
+    ".go": "Go", ".java": "Java", ".kt": "Kotlin", ".scala": "Scala",
+    ".rs": "Rust", ".c": "C", ".h": "C/C++", ".cpp": "C++", ".cc": "C++",
+    ".hpp": "C++", ".cxx": "C++", ".cs": "C#", ".php": "PHP", ".rb": "Ruby",
+    ".swift": "Swift", ".dart": "Dart", ".lua": "Lua", ".sh": "Bash",
+    ".bash": "Bash", ".zsh": "Bash", ".pl": "Perl", ".r": "R",
+    ".ex": "Elixir", ".exs": "Elixir", ".erl": "Erlang", ".hs": "Haskell",
+    ".clj": "Clojure", ".cljs": "Clojure", ".cljc": "Clojure",
+    ".el": "Emacs Lisp", ".scm": "Scheme", ".lisp": "Common Lisp",
+    ".jl": "Julia", ".nim": "Nim", ".cr": "Crystal", ".d": "D",
+    ".gradle": "Gradle", ".groovy": "Groovy", ".yaml": "YAML", ".yml": "YAML",
+    ".json": "JSON", ".toml": "TOML", ".xml": "XML", ".sql": "SQL",
+    ".html": "HTML", ".css": "CSS", ".scss": "SCSS", ".less": "LESS",
+    ".dockerfile": "Dockerfile", ".tf": "Terraform", ".hcl": "HCL",
+    ".vue": "Vue", ".svelte": "Svelte", ".astro": "Astro",
+    ".md": "Markdown", ".rst": "reStructuredText",
+    ".vim": "Vim Script", ".nix": "Nix", ".zig": "Zig",
+    ".elm": "Elm", ".purs": "PureScript", ".f90": "Fortran",
+    ".f": "Fortran", ".cbl": "COBOL", ".pas": "Pascal",
+    ".proto": "Protobuf", ".thrift": "Thrift",
+    ".cu": "CUDA", ".glsl": "GLSL", ".v": "Verilog", ".sv": "SystemVerilog",
+    ".sol": "Solidity", ".move": "Move", ".gleam": "Gleam",
+}
+_SPECIAL_FILENAMES = {
+    "Dockerfile": "Dockerfile", "Makefile": "Makefile", "CMakeLists.txt": "CMake",
+    "go.mod": "Go Module", "go.sum": "Go Module", "BUILD": "Starlark",
+    "WORKSPACE": "Starlark", ".env": "DotEnv", ".gitignore": "Git Ignore",
+    "requirements.txt": "Python Requirements", "package.json": "NPM Manifest",
+    "tsconfig.json": "TS Config", "Cargo.toml": "Cargo Manifest",
+    "pyproject.toml": "Python Project",
+}
+MIN_INDEGREE = 3
+
+def _detect_language(fp):
+    b = os.path.basename(fp)
+    if b in _SPECIAL_FILENAMES:
+        return _SPECIAL_FILENAMES[b]
+    if b.startswith(".env."):
+        return "DotEnv"
+    return _EXT_LANG.get(os.path.splitext(b)[1])
+
+def _qn_to_package(qn):
+    if not qn: return ""
+    parts = qn.split(".")
+    if len(parts) >= 4: return parts[2][:256]
+    if len(parts) >= 2: return parts[1][:256]
+    return ""
+
+def _qn_to_module(qn):
+    if not qn: return ""
+    parts = qn.split(".")
+    return parts[1] if len(parts) >= 2 else ""
+
+def _classify_layer(fi, fo, has_routes, has_entry):
+    if has_entry and fo > 0 and fi == 0: return ("entry", "has entry points, only outbound")
+    if has_routes: return ("api", "has HTTP routes")
+    if fi > fo and fi > MIN_INDEGREE: return ("core", "high fan-in (%d in, %d out)" % (fi, fo))
+    if fo == 0 and fi > 0: return ("leaf", "only inbound, no outbound")
+    if fi == 0 and fo > 0: return ("entry", "only outbound calls")
+    return ("internal", "fan-in=%d, fan-out=%d" % (fi, fo))
+
+def _find_db(project):
+    if os.path.isfile(project): return project, None
+    name = project if project.endswith(".db") else project + ".db"
+    path = os.path.join(CACHE_DIR, name)
+    if os.path.isfile(path): return path, None
+    hits = [f for f in os.listdir(CACHE_DIR) if f.endswith(".db") and project in f]
+    if len(hits) == 1: return os.path.join(CACHE_DIR, hits[0]), None
+    if len(hits) > 1: return None, "multiple matches: %s" % hits
+    return None, "DB not found: %s" % project
+
+def _list_projects():
+    dbs = sorted(f for f in os.listdir(CACHE_DIR) if f.endswith(".db") and f != "_config.db")
+    if not dbs: return "No .db files in %s" % CACHE_DIR
+    return "Available projects:\n" + "\n".join(
+        "  %s (%.1f MB)" % (d[:-3], os.path.getsize(os.path.join(CACHE_DIR, d))/1e6)
+        for d in dbs)
+
+def _extract_call_chains(conn, max_chains=8, max_depth=5):
+    entries = conn.execute(
+        "SELECT id,name FROM nodes WHERE json_extract(properties,'$.is_entry_point')=1 "
+        "AND (json_extract(properties,'$.is_test') IS NULL OR json_extract(properties,'$.is_test')!=1) "
+        "AND file_path NOT LIKE '%test%' LIMIT 15").fetchall()
+    if not entries:
+        entries = conn.execute(
+            "SELECT n.id,n.name FROM nodes n JOIN edges e ON e.source_id=n.id AND e.type='CALLS' "
+            "WHERE n.label IN ('Function','Method') AND (json_extract(n.properties,'$.is_test') IS NULL "
+            "OR json_extract(n.properties,'$.is_test')!=1) AND n.file_path NOT LIKE '%test%' "
+            "GROUP BY n.id ORDER BY COUNT(*) DESC LIMIT 10").fetchall()
+    if not entries: return []
+
+    hotspot_ids = set(r[0] for r in conn.execute(
+        "SELECT n.id FROM nodes n JOIN edges e ON e.target_id=n.id AND e.type='CALLS' "
+        "WHERE n.label IN ('Function','Method') AND (json_extract(n.properties,'$.is_test') IS NULL "
+        "OR json_extract(n.properties,'$.is_test')!=1) GROUP BY n.id HAVING COUNT(*)>=5").fetchall())
+
+    id_to_name = dict((r[0], r[1]) for r in conn.execute(
+        "SELECT id,name FROM nodes WHERE label IN ('Function','Method')").fetchall())
+
+    callees_of = defaultdict(list); callers_of = defaultdict(list)
+    for r in conn.execute("SELECT source_id,target_id FROM edges WHERE type='CALLS'").fetchall():
+        callees_of[r[0]].append(r[1]); callers_of[r[1]].append(r[0])
+
+    all_chains = []; seen = set()
+    for eid, ename in entries:
+        stack = [(eid, [ename], 0)]
+        while stack:
+            nid, path, hc = stack.pop()
+            if len(path) >= max_depth:
+                if len(path) >= 3 and path[-1] not in seen:
+                    seen.add(path[-1]); all_chains.append((path, hc))
+                continue
+            cands = [c for c in callees_of.get(nid, []) if id_to_name.get(c, "") not in path]
+            cands.sort(key=lambda c: len(callers_of.get(c, [])), reverse=True)
+            if not cands:
+                if len(path) >= 2 and path[-1] not in seen:
+                    seen.add(path[-1]); all_chains.append((path, hc))
+                continue
+            for c in cands[:4]:
+                cname = id_to_name.get(c, ""); new_hc = hc + (1 if c in hotspot_ids else 0)
+                if cname: stack.append((c, path + [cname], new_hc))
+    all_chains.sort(key=lambda x: (x[1], len(x[0])), reverse=True)
+    return [c for c, _ in all_chains[:max_chains]]
+
+def _extract_data_flow(conn):
+    sections = []
+    cfg_rows = conn.execute(
+        "SELECT n1.name,n2.name FROM edges e JOIN nodes n1 ON e.source_id=n1.id "
+        "JOIN nodes n2 ON e.target_id=n2.id WHERE e.type='CONFIGURES' ORDER BY e.id LIMIT 20").fetchall()
+    if cfg_rows:
+        env_rdrs = defaultdict(list)
+        for fn,env in cfg_rows: env_rdrs[env].append(fn)
+        cfg_lines = ["%s -> %s" % (e, ", ".join(r[:5])) for e, r in sorted(env_rdrs.items())]
+        sections.append(("config", cfg_lines[:8]))
+
+    write_rows = conn.execute(
+        "SELECT e.target_id,COUNT(*),n2.name FROM edges e JOIN nodes n2 ON e.target_id=n2.id "
+        "WHERE e.type='WRITES' GROUP BY e.target_id HAVING COUNT(*)>=2 ORDER BY COUNT(*) DESC LIMIT 10").fetchall()
+    write_lines = []
+    for tid,cnt,vname in write_rows:
+        writers = [r[0] for r in conn.execute(
+            "SELECT n1.name FROM edges e JOIN nodes n1 ON e.source_id=n1.id "
+            "WHERE e.type='WRITES' AND e.target_id=? LIMIT 5", (tid,)).fetchall()]
+        readers = [r[0] for r in conn.execute(
+            "SELECT n1.name FROM edges e JOIN nodes n1 ON e.source_id=n1.id "
+            "WHERE e.type='USAGE' AND e.target_id=? LIMIT 5", (tid,)).fetchall()]
+        if writers and readers:
+            write_lines.append("%s: w<-%s, r->%s" % (vname, ",".join(writers), ",".join(readers)))
+    if write_lines: sections.append(("state vars", write_lines[:5]))
+
+    grpc_rows = conn.execute(
+        "SELECT n1.name,n2.name,json_extract(e.properties,'$.confidence') FROM edges e "
+        "JOIN nodes n1 ON e.source_id=n1.id JOIN nodes n2 ON e.target_id=n2.id "
+        "WHERE e.type='GRPC_CALLS' AND (json_extract(e.properties,'$.confidence') IS NULL "
+        "OR CAST(json_extract(e.properties,'$.confidence') AS REAL)>=0.8) ORDER BY e.id LIMIT 10").fetchall()
+    if grpc_rows:
+        grpc_lines = ["%s -> %s (gRPC)" % (c, t.split("/")[-1] if "/" in t else t) for c,t,_ in grpc_rows]
+        sections.append(("cross-service", grpc_lines))
+    return sections
+
+def _run_skeleton(db_path, max_tokens=3000, include_data_flow=False):
+    uri = "file:%s?immutable=1" % db_path
+    conn = sqlite3.connect(uri, uri=True)
+    conn.row_factory = sqlite3.Row; lines = []
+
+    row = conn.execute("SELECT name,root_path,indexed_at FROM projects LIMIT 1").fetchone()
+    if not row: return "DB empty"
+    project = row["name"]
+    lines.extend(["project: %s" % project, "root: %s" % row["root_path"],
+                  "indexed: %s" % row["indexed_at"],
+                  "nodes: %d, edges: %d" % (conn.execute("SELECT COUNT(*) FROM nodes").fetchone()[0],
+                                           conn.execute("SELECT COUNT(*) FROM edges").fetchone()[0]), ""])
+
+    # languages
+    counts = Counter()
+    for r in conn.execute("SELECT file_path FROM nodes WHERE label='File'").fetchall():
+        l = _detect_language(r[0])
+        if l: counts[l] += 1
+    if counts:
+        ls = ", ".join("%s %d" % x for x in counts.most_common(5))
+        lines.append("languages: %s\n" % ls)
+
+    # entry points
+    rows = conn.execute(
+        "SELECT name,file_path FROM nodes WHERE json_extract(properties,'$.is_entry_point')=1 "
+        "AND (json_extract(properties,'$.is_test') IS NULL OR json_extract(properties,'$.is_test')!=1) "
+        "AND file_path NOT LIKE '%test%' LIMIT 20").fetchall()
+    if rows:
+        lines.append("entry points:")
+        for nm, fp in rows[:8]: lines.append("  %s:%s" % (fp, nm))
+        if len(rows) > 8: lines.append("  ... (%d total)" % len(rows))
+        lines.append("")
+
+    # routes
+    rows = conn.execute("SELECT name,properties FROM nodes WHERE label='Route' LIMIT 20").fetchall()
+    if rows:
+        rts = []
+        for r in rows:
+            props = json.loads(r[1] or "{}"); path = r[0]
+            if "/" not in path or len(path) > 60:
+                path = path.rsplit("/", 1)[-1]
+                if len(path) > 60: path = "..." + path[-57:]
+            rts.append("%s %s" % (props.get("method", "ANY"), path))
+        lines.append("routes: %s\n" % ", ".join(rts[:10]))
+
+    # hotspots
+    rows = conn.execute(
+        "SELECT n.name,n.file_path,COUNT(*) FROM nodes n JOIN edges e ON e.target_id=n.id AND e.type='CALLS' "
+        "WHERE n.label IN ('Function','Method') AND (json_extract(n.properties,'$.is_test') IS NULL "
+        "OR json_extract(n.properties,'$.is_test')!=1) AND n.file_path NOT LIKE '%test%' "
+        "GROUP BY n.id ORDER BY COUNT(*) DESC LIMIT 10").fetchall()
+    if rows:
+        lines.append("hotspots:")
+        for nm, fp, cnt in rows: lines.append("  %s (%d in) -- %s" % (nm, cnt, fp))
+        lines.append("")
+
+    # boundaries
+    id_to_pkg = {}
+    for r in conn.execute("SELECT id,qualified_name,file_path FROM nodes "
+                          "WHERE label IN ('Function','Method','Class')").fetchall():
+        pkg = _qn_to_package(r[1]) or os.path.dirname(r[2] or "").replace("/", ".") or "(root)"
+        id_to_pkg[r[0]] = pkg
+    cross = Counter()
+    for r in conn.execute("SELECT source_id,target_id FROM edges WHERE type='CALLS'").fetchall():
+        s = id_to_pkg.get(r[0], ""); t = id_to_pkg.get(r[1], "")
+        if s and t and s != t: cross[(s, t)] += 1
+    if cross:
+        lines.append("cross-pkg calls (top):")
+        for (s, t), c in cross.most_common(5): lines.append("  %s->%s (%d)" % (s, t, c))
+        lines.append("")
+
+    # layers
+    if cross:
+        fi_d = defaultdict(int); fo_d = defaultdict(int); pkgs = set()
+        for (s, t), c in cross.items(): fo_d[s] += c; fi_d[t] += c; pkgs.add(s); pkgs.add(t)
+        rp = {_qn_to_package(r[0]) for r in conn.execute(
+            "SELECT qualified_name FROM nodes WHERE label='Route'").fetchall()}
+        ep = {_qn_to_package(r[0]) for r in conn.execute(
+            "SELECT qualified_name FROM nodes WHERE json_extract(properties,'$.is_entry_point')=1").fetchall()}
+        by_l = defaultdict(list)
+        for p in sorted(pkgs):
+            fi = fi_d[p]; fo = fo_d[p]; ly, _ = _classify_layer(fi, fo, p in rp, p in ep)
+            by_l[ly].append("%s(%d in)" % (p, fi) if fi else p)
+        if by_l:
+            lines.append("layers:")
+            for ln in ("core", "api", "entry", "leaf", "internal"):
+                if ln not in by_l: continue
+                shown = by_l[ln][:8]; lines.append("  %s: %s" % (ln, ", ".join(shown)))
+                if len(by_l[ln]) > 8: lines.append("  ... (%d total)" % len(by_l[ln]))
+            lines.append("")
+
+    # packages
+    pkg_c = Counter()
+    for r in conn.execute("SELECT qualified_name FROM nodes "
+                          "WHERE label IN ('Function','Method','Class','Variable')").fetchall():
+        mod = _qn_to_module(r[0])
+        if mod: pkg_c[mod] += 1
+    if pkg_c:
+        lines.append("top-level modules: %s\n" % ", ".join("%s(%d)" % x for x in pkg_c.most_common(8)))
+
+    # top dirs
+    tds = set()
+    for r in conn.execute("SELECT file_path FROM nodes WHERE label='File'").fetchall():
+        if r[0]: tds.add(r[0].split("/")[0])
+    if tds:
+        lines.append("top dirs: %s\n" % ", ".join(sorted(tds)[:15]))
+
+    # clusters (simplified)
+    rows = conn.execute("SELECT id,qualified_name FROM nodes "
+                        "WHERE label IN ('Function','Method','Class')").fetchall()
+    if len(rows) >= 20:
+        id2m = {}; mm = defaultdict(list)
+        for r in rows: m = _qn_to_module(r[1]) or "(root)"; id2m[r[0]] = m; mm[m].append(r[0])
+        intra = defaultdict(int); tot = defaultdict(int)
+        for r in conn.execute("SELECT source_id,target_id FROM edges WHERE type='CALLS'").fetchall():
+            sm = id2m.get(r[0]); tm = id2m.get(r[1])
+            if sm and tm: tot[sm] += 1; intra[sm] = intra.get(sm, 0) + 1 if sm == tm else intra.get(sm, 0)
+        cls = []
+        for i, (m, mems) in enumerate(sorted(mm.items(), key=lambda x: -len(x[1]))):
+            if len(mems) < 5: continue
+            cls.append((i+1, m, len(mems), intra[m] / max(tot[m], 1)))
+            if len(cls) >= 5: break
+        if cls:
+            lines.append("clusters:")
+            for c1, c2, c3, c4 in cls:
+                lines.append("  C%d: %s (%d, cohesion %.2f)" % (c1, c2, c3, c4))
+            lines.append("")
+
+    # complexity
+    rows = conn.execute(
+        "SELECT name,file_path,properties FROM nodes WHERE label IN ('Function','Method') "
+        "AND (json_extract(properties,'$.is_test') IS NULL OR json_extract(properties,'$.is_test')!=1) "
+        "ORDER BY json_extract(properties,'$.transitive_loop_depth') DESC LIMIT 20").fetchall()
+    cx = []
+    for r in rows:
+        p = json.loads(r[2] or "{}"); tld = p.get("transitive_loop_depth", 0)
+        lsl = p.get("linear_scan_in_loop", 0); rec = p.get("recursive", False)
+        if tld >= 2 or lsl > 0 or rec: cx.append((r[0], r[1], tld, lsl, rec))
+    if cx:
+        lines.append("complexity:")
+        for name, fp, tld, lsl, rec in cx[:5]:
+            desc = []; tld >= 2 and desc.append("O(n^%d)" % tld)
+            lsl > 0 and desc.append("scan-in-loop x%d" % lsl); rec and desc.append("recursive")
+            lines.append("  %s -- %s (%s)" % (name, ", ".join(desc), fp))
+        lines.append("")
+
+    # call chains
+    chains = _extract_call_chains(conn)
+    if chains:
+        lines.append("call chains:")
+        for c in chains: lines.append("  " + " -> ".join(c))
+        lines.append("")
+
+    # data flow
+    if include_data_flow:
+        df = _extract_data_flow(conn)
+        if df:
+            lines.append("data flow:")
+            for title, slines in df:
+                lines.append("  [%s]" % title)
+                for l in slines: lines.append("  %s" % l)
+            lines.append("")
+
+    conn.close()
+    out = "\n".join(lines); max_chars = max_tokens * 4
+    return out[:max_chars] + "\n... (truncated)" if len(out) > max_chars else out
+
+CBM_SKELETON_SCHEMA = {
+    "name": "cancanneed",
+    "description": "Extract compressed skeleton (~2K tokens) from codebase graph DB.",
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "repo_path": {"type": "string", "description": "Absolute path to source directory"},
+            "project": {"type": "string", "description": "Project name or .db path"},
+            "max_tokens": {"type": "integer", "description": "Token cap. Default 3000.", "default": 3000},
+            "include_data_flow": {"type": "boolean", "description": "Include data flow chains.", "default": False},
+        },
+    },
+}
+
+def run(repo_path=None, project=None, max_tokens=3000, include_data_flow=False):
+    if repo_path:
+        db, err = _ensure_indexed(repo_path)
+        return (None, err) if err else (_run_skeleton(db, max_tokens, include_data_flow), None)
+    if project:
+        db, err = _find_db(project)
+        return (None, err) if err else (_run_skeleton(db, max_tokens, include_data_flow), None)
+    return None, _list_projects()
+
+def _skill_md():
+    try: return open(os.path.join(os.path.dirname(__file__), "skills", "SKILL.md")).read()
+    except Exception: return "# cancanneed\n\nSKILL.md not found."
+
+def main():
+    args = [a for a in sys.argv[1:] if a not in ("--json", "--skill")]
+    json_out = "--json" in sys.argv; skill_out = "--skill" in sys.argv
+    if skill_out: print(_skill_md()); return
+    arg = args[0] if args else ""
+    rp = pr = None
+    if arg and (arg.startswith("/") or arg.startswith("~") or arg.startswith(".")): rp = os.path.expanduser(arg)
+    elif arg: pr = arg
+    skel, err = run(repo_path=rp, project=pr)
+    if json_out:
+        print(json.dumps({"error": err} if err else {"skeleton": skel}, ensure_ascii=False))
+    else:
+        if err: print(err, file=sys.stderr); sys.exit(1)
+        else: print(skel)
+
+if __name__ == "__main__":
+    main()

package/cancanneed.sh

@@ -0,0 +1,5 @@
+#!/bin/sh
+# cancanneed npx wrapper — delegates to python3 cancanneed.py
+DIR=$(cd "$(dirname "$0")" && pwd)
+PY=${PYTHON:-python3}
+exec "$PY" "$DIR/cancanneed.py" "$@"

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "cancanneed",
+  "version": "0.1.0",
+  "description": "代码仓库压缩骨架提取器 — ~2K tokens 看清项目全貌",
+  "bin": {
+    "cancanneed": "./cancanneed.sh"
+  },
+  "files": [
+    "cancanneed.py",
+    "cancanneed.sh",
+    "skills/SKILL.md",
+    "README.md"
+  ],
+  "keywords": ["codebase", "skeleton", "architecture", "agent", "cbm"],
+  "license": "MIT"
+}

package/skills/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: cancanneed
+description: 从代码仓库提取压缩骨架供 agent 上下文注入。调用 cancanneed 工具一步获得项目全貌。
+---
+
+# cancanneed
+
+Agent 接手新项目时，调用 `cancanneed` 一次性拿到项目骨架，
+不必反复 `search_graph` → `trace_path` 试错。
+
+## 何时使用
+
+- Agent 首次进入一个新代码仓库
+- 需要快速了解项目模块结构、依赖关系
+- 评估修改某个函数的影响面前，需要全局视野
+- 任何需要"这个项目长什么样"的时刻
+
+## 用法
+
+两个模式：
+
+**repo_path** — 传源码目录，自动索引后提取（首次 10-60s，后续秒级）：
+
+```
+cancanneed(repo_path="/path/to/project")
+```
+
+**project** — 传已索引的项目名或 .db 路径，直接读 DB：
+
+```
+cancanneed(project="ai-runtime-trace")
+```
+
+不传参列出所有可用项目：
+
+```
+cancanneed()
+```
+
+可选参数：`max_tokens`（默认 3000），`include_data_flow`（默认 false，开启后追加数据透传链路）。
+
+## 会收到什么
+
+约 ~2K tokens 的压缩骨架文本，包含：
+
+- 语言分布（文件数统计）
+- 入口函数（is_entry_point）
+- HTTP 路由
+- 高扇入热点 top 10（被调用最多的函数）
+- 跨包调用边界 top 5
+- 分层（core/api/entry/leaf/internal）
+- 模块聚类 + 内聚度
+- 复杂度热点（O(n^k) 风险函数）
+- 主调用链路（从入口函数沿 CALLS 边做 5 跳 DFS）
+- 可选：数据透传链路（配置传播、状态变量、跨服务调用）
+
+拿到骨架后，agent 无需反复试错即可定位到要改的文件和函数。深入细节时再按需查代码。
+
+## 前置条件
+
+项目已用 codebase-memory-mcp 索引（大多数项目由 MCP 自动索引）。
+`repo_path` 模式会自动触发首次索引。