@sushanglewis/lincoln 1.6.3 → 1.8.0

package/framework/scripts/lincoln_index.py

@@ -26,6 +26,7 @@ sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
 from scripts.lincoln_paths import STATE_FILENAME, is_process_state_path
 
 PACKAGE_DATA_FILENAME = "assets/js/package-data.js"
+ARCHIVE_NAV_GROUP = "归档"
 VERSION_COMMENT_RE = re.compile(r"<!--\s*version:\s*(v\d+\.\d+)\s*-->", re.IGNORECASE)
 STATUS_COMMENT_RE = re.compile(r"<!--\s*status:\s*(\w+)\s*-->", re.IGNORECASE)
 LIST_META_KEYS = ("doc-fields", "doc-stories", "doc-rules", "doc-boundaries", "doc-exceptions", "doc-refs")
@@ -183,11 +184,13 @@ def build_package_data(
         if not entry.get("uid"):
             meta_warnings.append(f"{rel}: missing <meta name=\"doc-uid\"> or <meta name=\"page-uid\">")
         group_name = entry.get("group") or entry.get("nav_group") or "Docs"
+        archived = group_name == ARCHIVE_NAV_GROUP
         groups.setdefault(group_name, []).append(
             {
                 "path": rel,
                 "label": entry.get("nav_label") or entry.get("label") or entry.get("title") or Path(rel).stem,
                 "title": entry.get("title") or Path(rel).stem,
+                "archived": archived,
                 "version": entry.get("version"),
                 "status": entry.get("status", ""),
                 "stage": entry.get("stage", ""),
@@ -210,7 +213,11 @@ def build_package_data(
         for warning in meta_warnings:
             print(f"  - {warning}", file=sys.stderr)
 
-    nav = [{"group": g, "items": items} for g, items in groups.items()]
+    # Archive groups render last and collapsed in the portal.
+    nav = (
+        [{"group": g, "items": items} for g, items in groups.items() if g != ARCHIVE_NAV_GROUP]
+        + [{"group": g, "items": items} for g, items in groups.items() if g == ARCHIVE_NAV_GROUP]
+    )
 
     return {
         "process_slug": process_slug,

package/framework/scripts/lincoln_mr_mine.py

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+"""Lincoln MR / PR knowledge miner.
+
+Extracts decision-related review comments from a merged pull request and writes
+structured decision notes to the issue work package. These notes stay in
+issue-<N>/docs/decisions/ until the sync-knowledge stage promotes them to
+knowledge/.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+DECISION_KEYWORDS = ["decision", "decided", "agreed", "rejected", "note:", "approve", "approved"]
+
+
+def _run_gh(args: list[str]) -> dict[str, Any] | list[Any]:
+    """Call the gh CLI and return parsed JSON."""
+    cmd = ["gh", *args]
+    result = subprocess.run(cmd, capture_output=True, text=True, check=False)
+    if result.returncode != 0:
+        raise RuntimeError(result.stderr.strip() or "gh CLI failed")
+    return json.loads(result.stdout or "[]")
+
+
+def _extract_decision_snippets(text: str) -> list[str]:
+    """Pull decision-oriented sentences or paragraphs from a comment body."""
+    if not text:
+        return []
+    snippets = []
+    for paragraph in re.split(r"\n\s*\n", text.strip()):
+        paragraph = paragraph.strip()
+        if not paragraph:
+            continue
+        lowered = paragraph.lower()
+        if any(keyword in lowered for keyword in DECISION_KEYWORDS):
+            snippets.append(paragraph)
+    return snippets
+
+
+def _sanitize_filename(text: str) -> str:
+    """Reduce a comment snippet to a safe filename slug."""
+    text = text.lower()
+    text = re.sub(r"[^a-z0-9]+", "-", text)
+    text = text.strip("-")
+    return text[:60]
+
+
+def mine_pr_decisions(
+    owner: str,
+    repo: str,
+    pr_number: int,
+    issue_number: int | None = None,
+    output_dir: Path | None = None,
+) -> list[Path]:
+    """Mine decision comments from a PR and write them to the issue package."""
+    if output_dir is None:
+        if issue_number is None:
+            raise ValueError("issue_number or output_dir is required")
+        output_dir = Path(f"issue-{issue_number}") / "docs" / "decisions"
+    output_dir = Path(output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    comments = _run_gh(
+        ["api", f"repos/{owner}/{repo}/pulls/{pr_number}/comments"]
+    )
+    review_comments = _run_gh(
+        ["api", f"repos/{owner}/{repo}/pulls/{pr_number}/reviews"]
+    )
+
+    if isinstance(comments, dict):
+        comments = [comments]
+    if isinstance(review_comments, dict):
+        review_comments = [review_comments]
+
+    all_comments = list(comments) + list(review_comments)
+
+    written: list[Path] = []
+    seen: set[str] = set()
+
+    for comment in all_comments:
+        body = comment.get("body") or ""
+        snippets = _extract_decision_snippets(body)
+        for snippet in snippets:
+            if snippet in seen:
+                continue
+            seen.add(snippet)
+            slug = _sanitize_filename(snippet)
+            filename = f"pr-{pr_number}-{slug}.md"
+            path = output_dir / filename
+            if path.exists():
+                continue
+
+            content = f"""# PR {pr_number} Decision Note
+
+**Source:** {owner}/{repo}#{pr_number}
+**Author:** {comment.get('author', {}).get('login', 'unknown')}
+**Created:** {comment.get('createdAt', 'unknown')}
+**Comment ID:** {comment.get('id', 'unknown')}
+
+## Snippet
+
+{snippet}
+
+## Keywords
+
+{', '.join(DECISION_KEYWORDS)}
+
+---
+*Auto-generated by scripts/lincoln_mr_mine.py*
+"""
+            path.write_text(content, encoding="utf-8")
+            written.append(path)
+
+    return written
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Mine PR review decisions")
+    parser.add_argument("--owner", required=True)
+    parser.add_argument("--repo", required=True)
+    parser.add_argument("--pr", type=int, required=True)
+    parser.add_argument("--issue", type=int, default=None)
+    parser.add_argument("--output-dir", type=Path, default=None)
+    args = parser.parse_args(argv)
+
+    paths = mine_pr_decisions(
+        owner=args.owner,
+        repo=args.repo,
+        pr_number=args.pr,
+        issue_number=args.issue,
+        output_dir=args.output_dir,
+    )
+    for path in paths:
+        print(path)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/framework/scripts/lincoln_recall.py

@@ -0,0 +1,142 @@
+#!/usr/bin/env python3
+"""Lincoln recall precheck.
+
+Given a task description, scores knowledge base documents by keyword overlap
+(and optionally by embedding similarity) and returns the top-K matches.
+Designed to be called from on-session-start.sh before injecting context.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+DEFAULT_KNOWLEDGE_DIR = "knowledge"
+DEFAULT_TOP_K = 5
+
+
+def _tokenize(text: str) -> set[str]:
+    """Extract lowercase alphanumeric tokens."""
+    return set(re.findall(r"[a-zA-Z0-9一-鿿]+", text.lower()))
+
+
+def _load_documents(knowledge_dir: Path) -> list[dict[str, Any]]:
+    docs: list[dict[str, Any]] = []
+    if not knowledge_dir.exists():
+        return docs
+    for path in sorted(knowledge_dir.rglob("*.md")):
+        try:
+            text = path.read_text(encoding="utf-8")
+            docs.append(
+                {
+                    "path": str(path.relative_to(knowledge_dir)),
+                    "tokens": _tokenize(text),
+                    "title": path.stem,
+                    "_text": text[:2000],
+                }
+            )
+        except Exception:
+            continue
+    return docs
+
+
+def _score_by_keywords(query_tokens: set[str], doc: dict[str, Any]) -> float:
+    if not query_tokens:
+        return 0.0
+    doc_tokens = doc["tokens"]
+    if not doc_tokens:
+        return 0.0
+    overlap = len(query_tokens & doc_tokens)
+    return overlap / max(len(query_tokens), len(doc_tokens))
+
+
+def _try_embedding_score(query: str, docs: list[dict[str, Any]]) -> list[float] | None:
+    """Attempt embedding-based scoring if sentence-transformers is installed."""
+    try:
+        from sentence_transformers import SentenceTransformer, util  # type: ignore
+
+        model = SentenceTransformer("all-MiniLM-L6-v2")
+        query_embedding = model.encode(query, convert_to_tensor=True)
+        doc_texts = [doc.get("_text", "") for doc in docs]
+        doc_embeddings = model.encode(doc_texts, convert_to_tensor=True)
+        scores = util.cos_sim(query_embedding, doc_embeddings)[0].tolist()
+        return list(scores)
+    except Exception:
+        return None
+
+
+def recall(
+    query: str,
+    knowledge_dir: Path | None = None,
+    top_k: int = DEFAULT_TOP_K,
+    use_embedding: bool = True,
+) -> dict[str, Any]:
+    """Return top-K knowledge documents for a query."""
+    knowledge_dir = knowledge_dir or Path(DEFAULT_KNOWLEDGE_DIR)
+    docs = _load_documents(knowledge_dir)
+    query_tokens = _tokenize(query)
+
+    if use_embedding:
+        embedding_scores = _try_embedding_score(query, docs)
+    else:
+        embedding_scores = None
+
+    results = []
+    for idx, doc in enumerate(docs):
+        keyword_score = _score_by_keywords(query_tokens, doc)
+        if embedding_scores is not None:
+            score = 0.5 * keyword_score + 0.5 * embedding_scores[idx]
+        else:
+            score = keyword_score
+        results.append(
+            {
+                "path": doc["path"],
+                "title": doc["title"],
+                "score": round(score, 4),
+                "method": "embedding+keywords" if embedding_scores else "keywords",
+            }
+        )
+
+    results.sort(key=lambda r: r["score"], reverse=True)
+    return {
+        "query": query,
+        "top_k": top_k,
+        "docs": [r for r in results[:top_k] if r["score"] > 0],
+        "method": "embedding+keywords" if embedding_scores else "keywords",
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Recall relevant knowledge documents")
+    parser.add_argument("--query", required=True)
+    parser.add_argument("--knowledge-dir", type=Path, default=None)
+    parser.add_argument("--top-k", type=int, default=DEFAULT_TOP_K)
+    parser.add_argument("--format", choices=["json", "markdown"], default="json")
+    parser.add_argument("--no-embedding", action="store_true", default=False)
+    args = parser.parse_args(argv)
+
+    result = recall(
+        query=args.query,
+        knowledge_dir=args.knowledge_dir,
+        top_k=args.top_k,
+        use_embedding=not args.no_embedding,
+    )
+
+    if args.format == "json":
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    else:
+        print(f"# 相关知识（{result['method']}）\n")
+        if result["docs"]:
+            for doc in result["docs"]:
+                print(f"- [{doc['title']}]({doc['path']}) — score {doc['score']}")
+        else:
+            print("_未找到相关知识。_")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/framework/scripts/lincoln_trace.py

@@ -31,7 +31,7 @@ from scripts.lincoln_paths import (  # noqa: E402
     process_package_root,
 )
 
-TRACE_SCHEMA_VERSION = "1.0.0"
+TRACE_SCHEMA_VERSION = "2.0.0"
 
 # Tools whose invocations are not traced to avoid recursion or noise.
 NO_TRACE_TOOLS = {"Read", "Grep", "Glob"}
@@ -46,6 +46,26 @@ TASK_TOOLS = frozenset({
     "TaskStop",
 })
 
+# All valid trace categories. Tool categories are auto-derived; lifecycle categories
+# are written explicitly by stage_loader and hooks.
+VALID_CATEGORIES = frozenset({
+    "tool",
+    "skill",
+    "agent",
+    "read",
+    "write",
+    "edit",
+    "bash",
+    "task",
+    "mcp",
+    "handoff",
+    "other",
+    "stage_lifecycle",
+    "gate",
+    "session",
+    "condensation",
+})
+
 # Maximum length stored for a Bash command summary in the trace entry.
 COMMAND_SUMMARY_MAX_LEN = 500
 
@@ -202,6 +222,11 @@ def _resolve_trace_file(state: dict[str, Any] | None, state_path: Path | None) -
     return trace_dir / "lc-trace.jsonl"
 
 
+def get_trace_file(state: dict[str, Any] | None = None, state_path: Path | None = None) -> Path:
+    """Public accessor for the resolved trace file path."""
+    return _resolve_trace_file(state, state_path)
+
+
 def _get_run_id(state: dict[str, Any] | None, run_id: str | None) -> str:
     if run_id:
         return run_id
@@ -250,12 +275,26 @@ def _build_trace_target(tool: str, args_summary: dict[str, Any]) -> str:
     return str(args_summary.get("path", args_summary.get("name", "")))
 
 
+def _get_node_id(state: dict[str, Any] | None, node_id: str | None) -> str | None:
+    if node_id:
+        return node_id
+    if state:
+        current_run = state.get("current_run", {})
+        # Find the in_progress node for the current stage.
+        current_stage = current_run.get("current_stage", "")
+        for node in state.get("nodes", []):
+            if node.get("stage_id") == current_stage and node.get("status") == "in_progress":
+                return str(node.get("node_id", "")) or None
+    return None
+
+
 def _build_trace_entry(
     tool: str,
     args_summary: dict[str, Any],
     exit_code: int,
     run_id: str,
     stage: str,
+    node_id: str | None = None,
 ) -> dict[str, Any]:
     return {
         "schema_version": TRACE_SCHEMA_VERSION,
@@ -263,6 +302,7 @@ def _build_trace_entry(
         "timestamp": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
         "run_id": run_id,
         "stage": stage,
+        "node_id": node_id,
         "tool": tool,
         "category": categorize_tool(tool),
         "target": _build_trace_target(tool, args_summary),
@@ -290,8 +330,9 @@ def append_trace_entry(
     exit_code: int,
     stage: str | None = None,
     run_id: str | None = None,
+    node_id: str | None = None,
 ) -> Path | None:
-    """Append a single trace entry to the appropriate JSONL file.
+    """Append a single trace entry for a tool invocation.
 
     The write is atomic with respect to other processes on the same host: the
     file is locked while appending, so concurrent parent and child agents do
@@ -303,9 +344,84 @@ def append_trace_entry(
     state = _load_state(state_path)
     resolved_run_id = _get_run_id(state, run_id)
     resolved_stage = _get_stage(state, stage)
+    resolved_node_id = _get_node_id(state, node_id)
     trace_file = _resolve_trace_file(state, state_path)
     args_summary = redact_args(tool, _safe_json_loads(args))
-    entry = _build_trace_entry(tool, args_summary, exit_code, resolved_run_id, resolved_stage)
+    entry = _build_trace_entry(
+        tool, args_summary, exit_code, resolved_run_id, resolved_stage, resolved_node_id
+    )
+    _append_trace_line(trace_file, entry)
+    return trace_file
+
+
+def append_event_entry(
+    state_path: Path | None,
+    category: str,
+    payload: dict[str, Any],
+    stage: str | None = None,
+    run_id: str | None = None,
+    node_id: str | None = None,
+) -> Path | None:
+    """Append a non-tool lifecycle event to the trace.
+
+    Categories must be one of VALID_CATEGORIES. The payload is stored under
+    ``args_summary`` for backward compatibility with existing readers.
+    """
+    if category not in VALID_CATEGORIES:
+        raise ValueError(f"Invalid trace category: {category!r}")
+
+    state = _load_state(state_path)
+    resolved_run_id = _get_run_id(state, run_id)
+    resolved_stage = _get_stage(state, stage)
+    resolved_node_id = _get_node_id(state, node_id)
+    trace_file = _resolve_trace_file(state, state_path)
+
+    entry: dict[str, Any] = {
+        "schema_version": TRACE_SCHEMA_VERSION,
+        "sequence_id": generate_sequence_id(),
+        "timestamp": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "run_id": resolved_run_id,
+        "stage": resolved_stage,
+        "node_id": resolved_node_id,
+        "tool": "",
+        "category": category,
+        "target": str(payload.get("event_type", payload.get("type", "")))[:200],
+        "exit_code": int(payload.get("exit_code", 0)),
+        "args_summary": payload,
+    }
+    _append_trace_line(trace_file, entry)
+    return trace_file
+
+
+def append_event_to_file(
+    trace_file: Path,
+    category: str,
+    payload: dict[str, Any],
+    stage: str | None = None,
+    run_id: str | None = None,
+    node_id: str | None = None,
+) -> Path:
+    """Append a non-tool lifecycle event to an explicit trace file path.
+
+    This variant is useful when the caller has already resolved the trace file
+    (e.g. the condenser) and wants to avoid re-resolving it from state.
+    """
+    if category not in VALID_CATEGORIES:
+        raise ValueError(f"Invalid trace category: {category!r}")
+
+    entry: dict[str, Any] = {
+        "schema_version": TRACE_SCHEMA_VERSION,
+        "sequence_id": generate_sequence_id(),
+        "timestamp": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "run_id": run_id or "unknown",
+        "stage": stage or "unknown",
+        "node_id": node_id or "unknown",
+        "tool": "",
+        "category": category,
+        "target": str(payload.get("event_type", payload.get("type", "")))[:200],
+        "exit_code": int(payload.get("exit_code", 0)),
+        "args_summary": payload,
+    }
     _append_trace_line(trace_file, entry)
     return trace_file