hukair-codetalk 0.3.1__py3-none-any.whl

codetalk/__init__.py

@@ -0,0 +1,7 @@
+"""codetalk — local-first code decision provenance (zero-LLM grounding)."""
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("hukair-codetalk")
+except PackageNotFoundError:        # 源码树未安装时回退,不崩
+    __version__ = "0.3.1"

codetalk/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

codetalk/adr_export.py

@@ -0,0 +1,137 @@
+"""ADR 导出(零 LLM):把一段代码的真实决策史确定性渲染成 MADR / Nygard / CycloneDX。
+
+区别于手写 ADR 生态(adr-tools / Log4brains / pyadr 全手写、无一从 git 自动挖):codetalk 从
+真实 commit/决策**自动**导出,「来源」段附真实 commit SHA + 逐字原话(可核验,非 LLM 反推)——
+「别人要你手写 ADR,codetalk 从真实记录自动导出且逐字接地」。复用 blame.collect_segments;
+纯字符串拼接、零 LLM、不触网、出口脱敏、绝不崩。
+
+cyclonedx 格式输出 CycloneDX 1.5 base schema 子集(bomFormat/specVersion/components),
+让决策史能接进 AIBOM 生态(CISA/G7 SBOM for AI、CycloneDX AI 扩展)。timestamp 取最新
+commit 时间保证 reproducible(同输入同输出),不假装符合 modelCard/formulation 等 AI 专门段
+——codetalk 跟踪的是代码决策不是模型,硬塞会编造。
+"""
+import json
+import sys
+import uuid
+from pathlib import Path
+
+from .config import redact_data, redact_secrets
+
+FORMATS = ("madr", "nygard", "cyclonedx")
+
+
+def _bullets(items):
+    uniq = [str(x) for x in dict.fromkeys(items) if str(x).strip()]
+    return ["- " + x for x in uniq] or ["-(未记)"]
+
+
+def _to_cyclonedx(target, segments):
+    """CycloneDX 1.5 base schema 子集——每个 commit 一个 component,逐字保留决策原话。
+    serialNumber/timestamp 据 target+segments 哈希确定性生成,同输入字节级 reproducible。"""
+    latest_ts = ""
+    for s in reversed(segments):
+        if s.get("date"):
+            latest_ts = s["date"]
+            break
+    # uuid5(确定性:同输入同 UUID,仍字节级 reproducible)且是合法 RFC-4122 v5——
+    # 裸 sha256 切片虽过 CycloneDX 宽松 regex,但 version/variant nibble 不合规,严格校验会拒。
+    seed = target + "|" + "|".join(s.get("sha", "") for s in segments)
+    serial = f"urn:uuid:{uuid.uuid5(uuid.NAMESPACE_URL, seed)}"
+    components = []
+    for s in segments:
+        props = []
+        for d in (s.get("decisions") or []):
+            props.append({"name": "codetalk:decision", "value": d})
+        for r in (s.get("rejected") or []):
+            props.append({"name": "codetalk:rejected", "value": r})
+        for r in (s.get("risks") or []):
+            props.append({"name": "codetalk:risk", "value": r})
+        components.append({
+            "type": "data", "bom-ref": s.get("sha", ""),
+            "name": s.get("subject", "") or target,
+            "description": s.get("why") or "",
+            "properties": props,
+        })
+    bom = {
+        "bomFormat": "CycloneDX", "specVersion": "1.5",
+        "serialNumber": serial, "version": 1,
+        "metadata": {
+            "timestamp": latest_ts,
+            # 1.5 非废弃 tools 形态:{components:[...]};legacy tool[] 不允许 description
+            # 字段(additionalProperties:false),用 component 形态既携带 description 又过官方 schema
+            "tools": {"components": [
+                {"type": "application", "name": "codetalk",
+                 "description": "zero-LLM commit decision provenance"}]},
+            "component": {"type": "application", "name": target},
+        },
+        "components": components,
+    }
+    # 脱敏在 json.dumps 之前(对原始字符串叶子,见 redact_data 注释):dumps 转义引号会
+    # 让 key="value" 形式 secret 漏过 redact_secrets;故 redact 结构而非序列化后文本
+    return json.dumps(redact_data(bom), ensure_ascii=False, indent=2)
+
+
+def to_adr(target, segments, fmt="madr"):
+    """segments(旧→新,blame.collect_segments 输出)→ 一份 markdown ADR(或 JSON BOM)。零 LLM、落地前脱敏。"""
+    if fmt == "cyclonedx":
+        return _to_cyclonedx(target, segments)
+    whys = [s["why"] for s in segments if s.get("why")]
+    decisions = [d for s in segments for d in (s.get("decisions") or [])]
+    rejected = [r for s in segments for r in (s.get("rejected") or [])]
+    risks = [r for s in segments for r in (s.get("risks") or [])]
+    title = (segments[-1].get("subject") if segments else "") or target
+    context = whys or ["(无叙事;先跑 codetalk digest / enrich 富集)"]
+    # 被否决备选 = ADR 的「Considered Options」本源;仅在有否决记录时出该段(不撑空节)
+    considered = (["", "## Considered Options(被否决的备选)", *_bullets(rejected)]
+                  if rejected else [])
+    if fmt == "nygard":
+        body = ["# " + title, "", "## Status", "accepted", "",
+                "## Context", *context, "",
+                "## Decision", *_bullets(decisions), *considered, "",
+                "## Consequences", *_bullets(risks)]
+    else:                                         # MADR(默认)
+        body = ["# " + title, "", "- Status: accepted", "",
+                "## Context and Problem Statement", *context, "",
+                "## Decision Outcome", *_bullets(decisions), *considered, "",
+                "## Consequences", *_bullets(risks)]
+    body += ["", "## 来源(真实 commit,逐字可核验)", f"_目标:{target}_"]
+    for s in segments:                            # 每个 commit 的 SHA + 逐字决策/否决原话锚点
+        body.append(f"- [{s['sha'][:7]}] {(s.get('date') or '')[:10]} {s.get('subject', '')}")
+        for d in (s.get("decisions") or []):
+            body.append(f"    · {d}")
+        for r in (s.get("rejected") or []):
+            body.append(f"    · (否决){r}")
+    return redact_secrets("\n".join(body))
+
+
+def export(project, target, fmt="madr", vault=None):
+    """CLI 入口:collect_segments → to_adr → 返回 (输出/写盘提示, error)。零 LLM、不触网。"""
+    from .blame import _parse_target, collect_segments
+    from .cache import Cache
+    from .config import CACHE_DB_PATH, load_config
+    pp = Path(project).resolve()
+    file, start, end = _parse_target(target)
+    cache = Cache(CACHE_DB_PATH)
+    try:
+        segs = collect_segments(cache, pp, file, start, end)
+    finally:
+        cache.close()
+    if not segs:
+        return None, f"{file} 没有可用的提交历史,无从导出 ADR。"
+    out = to_adr(target, segs, fmt=fmt)
+    if vault:
+        from . import report
+        path = report.write_report(load_config()["vault_path"], pp.name,
+                                   "adr-" + file.replace("/", "_"), out)
+        return f"ADR 已写入:{path}", None
+    return out, None
+
+
+def adr_export_cmd(args):
+    """零 LLM:某段代码真实决策史 → MADR/Nygard markdown,逐字引真实 commit。"""
+    out, err = export(args.project, args.target, fmt=args.format, vault=args.vault)
+    if err:
+        print(f"错误:{err}", file=sys.stderr)
+        return 2
+    print(out)
+    return 0

codetalk/agent_seed.md

@@ -0,0 +1,18 @@
+<!-- codetalk-agent-seed -->
+## codetalk 决策捕获(AI coding agent 必读)
+
+每次 `git commit`,在 commit message 正文按下面格式留下这次改动的**关键决策与推导**,
+供 codetalk 作为决策记录长期分析(ask / graph / digest 据此接地,免得日后从 diff 反推)。保持精炼:
+每条一行、总共几行即可,别写长文。**行首精确、区分大小写**。
+
+- `Vibe-Decision: <做了什么决定;为什么这么选>` —— 一个关键决策一行,可多条
+- `Vibe-Rejected: <认真考虑过但放弃的备选 + 为何弃>` —— 被否决方案一条一行,可多条;
+  这是 diff 结构性取不到的 **why-NOT**,`blame` 会在你日后改到该处时独立标出「否决备选(曾放弃)」,
+  防你/AI **重引入**已否决方案(codetalk 护城河:对抗 AI 反推式编造被否决备选)
+- `Vibe-Watch: <没把握、需日后验证的点>` —— 风险 / 待验证,可多条
+
+例:
+
+    Vibe-Decision: 用 --no-merges 跳合并 —— 叙事只要功能提交
+    Vibe-Rejected: --first-parent —— 保留合并气泡、丢功能提交,叙事更差
+    Vibe-Watch: 空提交尾部 NUL subject 未处理,罕见暂不管

codetalk/align.py

@@ -0,0 +1,42 @@
+"""Soft session-commit alignment: time window + file-path overlap."""
+from datetime import timedelta
+from pathlib import Path
+
+TIME_SLACK = timedelta(minutes=30)
+
+
+def _relative_files(session, project_root):
+    """Session file paths are absolute; map them into the repo, drop the rest."""
+    rel = set()
+    for path in session["files_written"]:
+        try:
+            rel.add(str(Path(path).relative_to(project_root)))
+        except ValueError:
+            continue
+    return rel
+
+
+def align(commits, sessions, project_path):
+    """Attach matches=[{session, overlap, confidence}] to every commit.
+
+    high = commit falls in the session's time window AND touches shared
+    files; low = only one signal. Target is soft 80% accuracy by design.
+    """
+    project_root = Path(project_path).resolve()
+    session_files = [(s, _relative_files(s, project_root)) for s in sessions]
+    for commit in commits:
+        matches = []
+        for session, files in session_files:
+            in_window = bool(
+                session["start"] and session["end"]
+                and session["start"] - TIME_SLACK <= commit["date"]
+                <= session["end"] + TIME_SLACK)
+            overlap = sorted(files & set(commit["files"]))
+            if not in_window and not overlap:
+                continue
+            confidence = "high" if (in_window and overlap) else "low"
+            matches.append({"session": session, "overlap": overlap,
+                            "confidence": confidence})
+        matches.sort(key=lambda m: (m["confidence"] != "high", -len(m["overlap"])))
+        commit["matches"] = matches
+    return commits

codetalk/ask.py

@@ -0,0 +1,278 @@
+"""单代码 AI 提问:接项目记忆对一段代码作接地回答。
+
+write-time 捕获(commit trailer 面包屑)+ read-time 廉价检索(git log -L → 已缓存
+叙事 + 面包屑 → 一次轻 LLM)。无 key/失败时降级为打印该代码的原始决策史,绝不崩。
+"""
+import hashlib
+import json
+import sys
+from pathlib import Path
+
+from . import grounding_render as gr
+from .cache import Cache
+from .config import CACHE_DB_PATH, load_config, redact_data, redact_secrets
+from .gitlog import (line_log, file_log, merge_breadcrumbs, parse_target,
+                     commit_meta)
+from .llm import LLMClient, LLMError
+from .prompts import ASK_SCHEMA, ASK_SYSTEM_PROMPT
+
+EXCERPT = 200
+CONTEXT_BUDGET = 6000
+_parse_target = parse_target          # 与 blame 同口径,搬到 gitlog 共享
+
+
+def _since_args(since):
+    """把 --since 的值分类成 git log 的范围 token(确定性检索,不引向量库):
+    含 '..' → 当 commit 范围(如 abc..def)直接作 rev arg;否则当日期 → --since=<值>。
+    None/空 → 无范围([]),退化为全历史检索。"""
+    since = (since or "").strip()
+    if not since:
+        return []
+    if ".." in since:
+        return [since]
+    return [f"--since={since}"]
+
+
+def _retrieve(project_path, file, start, end, cache, since=None):
+    """→ (context_str, shas oldest-first, code_state, evidence, test_refs, pr_refs)。
+    无历史时 context_str 为 ''。code_state = 命中行最新 commit SHA,进缓存键 →
+    代码一变旧答案自然失效。evidence = 命中 SHA narrative 的原话锚点汇总;
+    pr_refs = 命中 narrative 的 PR 讨论汇总(按 number 去重);旧缓存无键 .get 兼容。
+    since:把检索从空间(文件:行)再叠一层时间范围(日期/commit 范围),确定性过滤。"""
+    extra = _since_args(since)
+    if start is not None:
+        shas, err = line_log(project_path, file, start, end, extra=extra)
+        if err:                       # 行级失败 → 文件级降级
+            shas, _ = file_log(project_path, file, extra=extra)
+    else:
+        shas, _ = file_log(project_path, file, extra=extra)
+    blocks, evidence, test_refs, pr_refs = [], [], [], []
+    _seen_ev, _seen_test, _seen_pr = set(), set(), set()
+    for sha in shas:
+        narrative = cache.get_narrative(sha) or {}
+        decs, risks, rejected = merge_breadcrumbs(narrative, project_path, sha)
+        for ev in narrative.get("evidence") or []:    # 原话锚点,按 (session_id, ts) 去重
+            sid = ev.get("session_id")
+            key_ev = (sid, ev.get("ts")) if sid else str(ev)
+            if key_ev not in _seen_ev:
+                _seen_ev.add(key_ev)
+                evidence.append(ev)
+        for tr in narrative.get("test_refs") or []:   # 本地测试接地源,按 path 去重
+            if tr.get("path") not in _seen_test:
+                _seen_test.add(tr.get("path"))
+                test_refs.append(tr)
+        for pr in narrative.get("pr_refs") or []:     # PR 讨论接地源,按 number 去重
+            if pr.get("number") not in _seen_pr:
+                _seen_pr.add(pr.get("number"))
+                pr_refs.append(pr)
+        # subject 兜底:无叙事无面包屑时也不只剩光秃 [sha](对齐 blame,冷启动可读)
+        _date, subject = commit_meta(project_path, sha)
+        parts = [f"[{sha[:7]}]" + (f" {subject}" if subject else "")]
+        if narrative.get("why"):
+            parts.append("意图:" + narrative["why"][:EXCERPT])
+        if decs:
+            parts.append("决策:" + ";".join(decs)[:EXCERPT])
+        if rejected:
+            parts.append("否决备选:" + ";".join(rejected)[:EXCERPT])
+        if risks:
+            parts.append("风险/待验证:" + ";".join(risks)[:EXCERPT])
+        blocks.append(" / ".join(parts))
+    # 单点脱敏在原始拼接文本上(非 JSON/LLM 编码后):context 由 commit body 面包屑直接拼成,
+    # 未经 cache 脱敏。一处脱敏堵三个出口——MCP JSON(_json_text dumps 前)、CLI 降级 stdout、
+    # 送外部 LLM 的 prompt(_ask_prompt→narrate,唯一出网例外也须先脱敏)。
+    context = redact_secrets("\n".join(blocks)[:CONTEXT_BUDGET])
+    code_state = shas[-1] if shas else ""
+    return context, shas, code_state, evidence, test_refs, pr_refs
+
+
+def _verify_cited(cited, shas):
+    """只保留能对上检索集合里真实 commit 的引用(双向前缀匹配),丢掉模型自造的 SHA。
+    守『引用可点验证』:LLM 自报但不在检索证据里的 SHA 一律不外露、不落缓存。"""
+    real = [str(s) for s in (shas or [])]
+    return [str(c) for c in cited
+            if any(r == str(c) or r.startswith(str(c)) or str(c).startswith(r)
+                   for r in real)]
+
+
+def _ask_prompt(context, question):
+    return ("材料(这段代码相关 commit 的叙事与决策面包屑,旧→新):\n"
+            f"{context}\n\n问题:{question}\n"
+            "只据材料回答;材料不足就说『材料不足』。")
+
+
+def _format(payload):
+    cited = "、".join(payload.get("cited_shas") or []) or "(无)"
+    out = payload.get("answer", "")
+    if payload.get("unsure"):
+        out += f"\n\n[不确定] {payload['unsure']}"
+    return f"{out}\n\n据此回答的 commit:{cited}"
+
+
+def format_evidence(evidence):
+    """把原话锚点渲染成「原话佐证(可自行核验)」块,供 LLM 答案旁对照(对抗反推式编造)。
+    每条列 source·session 短id·ts + 原话/AI 陈述片段;支撑全为 low 时加置信度警示。
+    无 evidence → 返回 ''(调用方不追加该块,旧缓存无键经上游 .get 兼容)。脱敏在上游已做。"""
+    if not evidence:
+        return ""
+    lines = [gr.EVIDENCE_TITLE]
+    for ev in evidence:
+        sid = (ev.get("session_id") or "")[:7]
+        head = f"- [{ev.get('source', '?')}·{sid}·{ev.get('ts', '')}" \
+               f"·{ev.get('confidence', '?')}]"
+        lines.append(head)
+        for p in ev.get("prompts") or []:
+            lines.append(f"  原话:{p}")
+        for e in ev.get("excerpts") or []:
+            lines.append(f"  AI:{e}")
+    if gr.evidence_low_confidence(evidence):
+        lines.append(gr.EVIDENCE_LOW_WARN)
+    return "\n".join(lines)
+
+
+def format_test_refs(test_refs):
+    """「相关测试(从测试场景反推设计)」块:列相关测试文件 + 用例名,供用户反推设计。
+    无 → ''(调用方不追加)。对位用户1「看测试用例反推设计」(问卷一 Q3)。"""
+    if not test_refs:
+        return ""
+    lines = [gr.TEST_REFS_TITLE]
+    for tr in test_refs:
+        names = "、".join(tr.get("names") or []) or "(无显式 test_ 用例)"
+        lines.append(f"- {tr.get('path', '')} — {names}")
+    return "\n".join(lines)
+
+
+def format_pr_refs(pr_refs):
+    """「相关 PR 讨论(当初的需求背景)」块:列 #N title — snippet,供反推需求背景。
+    无 → ''(调用方不追加)。对位用户1「看 PR 描述找需求背景」(问卷一 Q3,最强 why 源)。"""
+    if not pr_refs:
+        return ""
+    lines = [gr.PR_REFS_TITLE]
+    for pr in pr_refs:
+        lines.append(f"- #{pr.get('number')} {pr.get('title', '')} — "
+                     f"{pr.get('snippet', '')}")
+    return "\n".join(lines)
+
+
+def _with_evidence(text, evidence, test_refs=(), pr_refs=()):
+    for block in (format_evidence(evidence), format_test_refs(test_refs),
+                  format_pr_refs(pr_refs)):
+        if block:
+            text = f"{text}\n\n{block}"
+    return text
+
+
+def _json_text(mode, target, question, shas, payload=None, context=None):
+    """组装 agent 可读的结构化结果(与 agent-seed 写时捕获配成读写闭环)。
+    llm/cache:带 LLM payload(answer/cited_shas/unsure);degraded:无 LLM,
+    给出确定性检索结果(context 原始决策史 + shas),降级也不崩。
+    context 已在 _retrieve 脱敏;此处再 redact_data 兜底(结构叶子,dumps 前)防遗漏出口。"""
+    obj = {"mode": mode, "target": target, "question": question,
+           "shas": list(shas or [])}
+    if payload is not None:
+        obj["answer"] = payload.get("answer", "")
+        obj["cited_shas"] = list(payload.get("cited_shas") or [])
+        obj["unsure"] = payload.get("unsure", "")
+    if context is not None:
+        obj["context"] = context
+    return json.dumps(redact_data(obj), ensure_ascii=False, indent=2)
+
+
+def _write_note(vault_path, project, target, question, payload):
+    vault = Path(vault_path).expanduser()
+    vault.mkdir(parents=True, exist_ok=True)
+    slug = hashlib.sha256(f"{target}|{question}".encode()).hexdigest()[:8]
+    note = f"# 提问:{target}\n\n> {question}\n\n{_format(payload)}\n"
+    (vault / f"{project}-ask-{slug}.md").write_text(
+        redact_secrets(note), encoding="utf-8")
+
+
+def answer_question(cache, llm, project_path, project, target, question,
+                    vault_path=None, since=None, as_json=False):
+    """核心:解析→检索→(命中缓存/无 key 降级/调 LLM)→脱敏缓存→(可选)写笔记。
+    返回 (text, error_or_None)。llm=None 表示无 key,降级打印原始决策史。
+    since:把检索叠一层时间范围;as_json:text 改为 agent 可读的结构化 JSON。"""
+    question = redact_secrets(question)   # 用户原始输入:在所有出口(json/note/prompt)前单点脱敏
+    file, start, end = _parse_target(target)
+    context, shas, code_state, evidence, test_refs, pr_refs = _retrieve(
+        project_path, file, start, end, cache, since=since)
+    if not context:
+        return None, f"{file} 没有可用的提交历史,无从回答。"
+    key = "ask:" + hashlib.sha256(
+        f"{file}|{start}-{end}|{question}|{code_state}|{since or ''}".encode()
+    ).hexdigest()[:40]
+    cached = cache.get_narrative(key)
+    if cached:
+        _log_usage(project_path, "cache", llm)
+        if as_json:
+            return _json_text("cache", target, question, shas,
+                              payload=cached), None
+        return _with_evidence(_format(cached), evidence, test_refs, pr_refs), None
+    if llm is None:                       # 无 API key:降级到原始决策史
+        _log_usage(project_path, "degraded", llm)
+        if as_json:
+            return _json_text("degraded", target, question, shas,
+                              context=context), None
+        return _with_evidence(
+            "(未配置 LLM,以下为这段代码的原始决策史)\n" + context,
+            evidence, test_refs, pr_refs), None
+    try:
+        raw = llm.narrate(_ask_prompt(context, question),
+                          schema=ASK_SCHEMA, system=ASK_SYSTEM_PROMPT)
+    except LLMError:
+        _log_usage(project_path, "degraded", llm)
+        if as_json:
+            return _json_text("degraded", target, question, shas,
+                              context=context), None
+        return _with_evidence(
+            "(LLM 调用失败,以下为原始决策史)\n" + context,
+            evidence, test_refs, pr_refs), None
+    payload = {
+        "answer": redact_secrets(str(raw.get("answer", ""))),
+        "cited_shas": _verify_cited(raw.get("cited_shas") or [], shas),
+        "unsure": redact_secrets(str(raw.get("unsure", ""))),
+    }
+    cache.put_narrative(key, project, llm.model, payload)
+    _log_usage(project_path, "llm", llm)
+    if vault_path:
+        _write_note(vault_path, project, target, question, payload)
+    if as_json:
+        return _json_text("llm", target, question, shas, payload=payload), None
+    return _with_evidence(_format(payload), evidence, test_refs, pr_refs), None
+
+
+def _log_usage(project_path, mode, llm):
+    """记一行 ask 用量(mode=cache/degraded/llm;带 LLM token 省额)。写失败不影响主流程。"""
+    from . import report
+    stats = getattr(llm, "stats", {}) if llm else {}
+    report.append_usage({
+        "command": "ask", "project": str(project_path), "mode": mode,
+        "llm_calls": stats.get("calls", 0),
+        "tokens_in": stats.get("input_tokens", 0),
+        "tokens_out": stats.get("output_tokens", 0),
+        "cache_hit_tokens": stats.get("cache_hit_tokens", 0),
+    })
+
+
+def ask(project_path, target, question, vault=None, since=None, as_json=False,
+        no_llm=False):
+    """CLI 入口:装配 cache/llm,转 answer_question,打印,返回退出码。"""
+    cfg = load_config()
+    if vault:
+        cfg["vault_path"] = vault
+    if no_llm:
+        cfg["no_llm"] = True              # 硬关 LLM → 下方 LLMClient 抛 LLMError → 降级确定性
+    pp = Path(project_path).resolve()
+    cache = Cache(CACHE_DB_PATH)
+    try:
+        llm = LLMClient(cfg)
+    except LLMError:
+        llm = None                        # 无 key → 降级,不报错退出
+    text, err = answer_question(cache, llm, pp, pp.name, target, question,
+                                cfg["vault_path"] if vault else None,
+                                since=since, as_json=as_json)
+    cache.close()
+    if err:
+        print(f"错误:{err}", file=sys.stderr)
+        return 2
+    print(text)
+    return 0

codetalk/blame.py

@@ -0,0 +1,170 @@
+"""blame:零-LLM 行级决策溯源 —— ask 的确定性孪生。
+
+给定文件(可选行范围),用 git 行历史(line_log,行级失败降级文件级)找出触达这些
+行的 commit,映射到已缓存叙事 + Vibe-Decision 面包屑,确定性打印每段决策史
+(SHA·日期·subject·decisions)。ask 用 LLM 综合,blame 只如实罗列;无 key 也能用。
+"""
+import json
+import sys
+from pathlib import Path
+
+from . import grounding_render as gr
+from .cache import Cache
+from .config import CACHE_DB_PATH, redact_data, redact_secrets
+from .gitlog import (commit_body, commit_meta, file_log, line_log,
+                     parse_breadcrumbs, parse_rejected, parse_target)
+
+_parse_target = parse_target          # 与 ask 同口径,搬到 gitlog 共享
+
+
+def segment_has_why(seg):
+    """该段是否带 authored why(narrative why / decisions / 否决备选 / evidence 任一)。
+    Vibe-Watch(risks)是前瞻预测、非『为什么这么写』,不计(与 grounding_hitrate/recall 同口径)。"""
+    return bool((seg.get("why") or "").strip() or seg.get("decisions")
+                or seg.get("rejected") or seg.get("evidence"))
+
+
+def _resolve_shas(project_path, file, start, end):
+    """→ (shas 旧→新, precision)。precision 是**确定性溯源准度**信号、非语义对错:
+    line=行级精确命中;file=行级失败或无范围→文件级降级(可能含本块外历史);none=无任何历史。"""
+    if start is not None:
+        shas, err = line_log(project_path, file, start, end)
+        if not err:
+            return shas, ("line" if shas else "none")
+        shas, _ = file_log(project_path, file)        # 行级失败 → 文件级降级
+        return shas, ("file" if shas else "none")
+    shas, _ = file_log(project_path, file)
+    return shas, ("file" if shas else "none")
+
+
+def _build_segments(cache, project_path, shas):
+    """shas → 每 commit 一段(旧→新),含 sha/date/subject/why/decisions/risks/evidence/refs。
+    每段 decisions = 缓存叙事决策 ∪ 面包屑(去重,缓存已折入不重复)。"""
+    segments = []
+    for sha in shas:
+        narrative = cache.get_narrative(sha) or {}
+        body = commit_body(project_path, sha)
+        authored_decisions, authored_risks = parse_breadcrumbs(body)
+        authored_rejected = parse_rejected(body)
+        generated_decisions = narrative.get("decisions") or []
+        generated_rejected = narrative.get("rejected") or []
+        decs = list(dict.fromkeys(generated_decisions + authored_decisions))
+        risks = list(dict.fromkeys(
+            (narrative.get("risks") or []) + authored_risks))
+        rejected = list(dict.fromkeys(generated_rejected + authored_rejected))
+        date_iso, subject = commit_meta(project_path, sha)
+        segments.append({
+            "sha": sha, "date": date_iso, "subject": subject,
+            "why": narrative.get("why") or "",
+            "decisions": decs, "risks": risks, "rejected": rejected,
+            "authored_decisions": authored_decisions,
+            "authored_rejected": authored_rejected,
+            "generated_decisions": [d for d in generated_decisions
+                                    if d not in authored_decisions],
+            "generated_rejected": [r for r in generated_rejected
+                                   if r not in authored_rejected],
+            "evidence": narrative.get("evidence") or [],  # 旧缓存无键 .get 兼容
+            "test_refs": narrative.get("test_refs") or [],
+            "pr_refs": narrative.get("pr_refs") or [],
+        })
+    return segments
+
+
+def collect_segments(cache, project_path, file, start, end):
+    """→ 触达这些行的每个 commit 一段(旧→新)。行级失败降级文件级。
+    (契约不变:adr_export/review/retrieval/mcp_server/blame 五处依赖此签名与行为;
+    需溯源准度信号时用 collect_graded。)"""
+    shas, _ = _resolve_shas(project_path, file, start, end)
+    return _build_segments(cache, project_path, shas)
+
+
+def collect_graded(cache, project_path, file, start, end):
+    """同 collect_segments,但额外返回溯源精度 → (segments, precision)。
+    供 review 诚实标注每块『这块溯源有多准』(行级精确 / 文件级降级 / 无据),非判 why 对错。"""
+    shas, precision = _resolve_shas(project_path, file, start, end)
+    return _build_segments(cache, project_path, shas), precision
+
+
+def _emit_evidence(lines, evidence):
+    """把该段原话锚点确定性追加进输出(零 LLM):source·短id·ts + 原话/AI 片段;
+    支撑全为 low 时加置信度警示。无 evidence 不输出块。脱敏已在 enrich 上游做。"""
+    if not evidence:
+        return
+    lines.append("  " + gr.EVIDENCE_TITLE)
+    for ev in evidence:
+        sid = (ev.get("session_id") or "")[:7]
+        lines.append(f"    [{ev.get('source', '?')}·{sid}·{ev.get('ts', '')}"
+                     f"·{ev.get('confidence', '?')}]")
+        for p in ev.get("prompts") or []:
+            lines.append(f"      原话:{p}")
+        for e in ev.get("excerpts") or []:
+            lines.append(f"      AI:{e}")
+    if gr.evidence_low_confidence(evidence):
+        lines.append("    " + gr.EVIDENCE_LOW_WARN)
+
+
+def _emit_test_refs(lines, test_refs):
+    """「相关测试(从测试场景反推设计)」确定性追加(零 LLM)。无则不输出。"""
+    if not test_refs:
+        return
+    lines.append("  " + gr.TEST_REFS_TITLE)
+    for tr in test_refs:
+        names = "、".join(tr.get("names") or []) or "(无显式 test_ 用例)"
+        lines.append(f"    {tr.get('path', '')} — {names}")
+
+
+def _emit_pr_refs(lines, pr_refs):
+    """「相关 PR 讨论(当初的需求背景)」确定性追加(零 LLM)。无则不输出。"""
+    if not pr_refs:
+        return
+    lines.append("  " + gr.PR_REFS_TITLE)
+    for pr in pr_refs:
+        lines.append(f"    #{pr.get('number')} {pr.get('title', '')} — "
+                     f"{pr.get('snippet', '')}")
+
+
+def _format(file, start, end, segments):
+    span = f"{file}:{start}-{end}" if start is not None else file
+    lines = [f"# blame {span}(旧→新,共 {len(segments)} 个 commit 触达)\n"]
+    for seg in segments:
+        date = (seg["date"] or "")[:10]    # 仅日期部分
+        lines.append(f"[{seg['sha'][:7]}] {date} {seg['subject']}")
+        if seg["why"]:
+            lines.append(f"  意图:{seg['why']}")
+        for dec in seg["decisions"]:
+            lines.append(f"  决策:{dec}")
+        for rej in seg.get("rejected") or []:        # 否决备选:diff 取不到的 why-NOT,防重引入
+            lines.append(f"  否决备选(曾放弃):{rej}")
+        for risk in seg["risks"]:
+            lines.append(f"  待验证:{risk}")
+        _emit_evidence(lines, seg.get("evidence") or [])
+        _emit_test_refs(lines, seg.get("test_refs") or [])
+        _emit_pr_refs(lines, seg.get("pr_refs") or [])
+        lines.append("")
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def blame(project_path, target, json_output=False):
+    """CLI 入口:解析→收集→确定性打印,返回退出码。零 LLM,无 key 也能用。"""
+    file, start, end = _parse_target(target)
+    pp = Path(project_path).resolve()
+    cache = Cache(CACHE_DB_PATH)
+    segments = collect_segments(cache, pp, file, start, end)
+    cache.close()
+    if not segments:
+        print(f"错误:{file} 没有可用的提交历史,无从溯源。", file=sys.stderr)
+        return 2
+    if json_output:
+        # 脱敏在 json.dumps 之前(对原始字符串叶子):dumps 会把 " 转义,
+        # 若先 dumps 后 redact,key="value" 形式 secret 会因引号转义漏网(见 redact_data 注释)
+        print(json.dumps(redact_data(segments), ensure_ascii=False), end="")
+    else:
+        print(redact_secrets(_format(file, start, end, segments)), end="")
+        # 冷启动 on-ramp:全是裸 subject(无 why/决策/面包屑)时,别让陌生人以为=git log。
+        # 末行(stderr,不污染管道)指下一步:富集或装面包屑捕捉。
+        if not any(segment_has_why(s) for s in segments):
+            print("\n提示:该文件暂无决策记录(仅 commit 标题)。跑 `codetalk enrich .` "
+                  "查看计划,确认后加 `--allow-remote`;或 `codetalk install-agent-seed .` "
+                  "让 AI 提交时留 why。",
+                  file=sys.stderr)
+    return 0