research-assistant 0.1.0

package/src/research_assistant/installer.py

@@ -0,0 +1,270 @@
+"""managed 文件安装器（因家异构，ADR-0008 / D7）。
+
+- SKILL.md（bundled asset）相对通用，装各家 skill 目录。
+- researcher agent 定义因家而异：Claude/Cursor=md+frontmatter、Codex=toml、Hermes=无（融入 skill）。
+- 附带复制 MV3 扩展到 ~/.research-assistant/extension/（供用户在浏览器加载一次）。
+
+幂等：重复 install 覆盖；status 对比 installed 与 bundled 内容判定 missing/stale/up-to-date/extra。
+"""
+
+from __future__ import annotations
+
+import os
+from importlib import resources
+from pathlib import Path
+from typing import Any
+
+from .errors import ResearchAssistantError
+from .targets import AGENT_NAME, ALL_FAMILIES, SKILL_NAME, Family
+
+_ASSET_ROOT = ("assets",)
+_PERSONA_RESOURCE = ("assets", "researcher_persona.md")
+_SKILL_RESOURCE = ("assets", "skills", SKILL_NAME, "SKILL.md")
+
+
+# ---------------------------------------------------------------------------
+# asset 读取
+# ---------------------------------------------------------------------------
+
+
+def _read_text(resource_path: tuple[str, ...]) -> str:
+    """优先 importlib.resources（打包后），失败回退文件系统（dev 从 src 运行）。"""
+    try:
+        root = resources.files("research_assistant")
+        for part in resource_path:
+            root = root.joinpath(part)
+        return root.read_text(encoding="utf-8")
+    except Exception:
+        fs_root = Path(__file__).resolve().parents[1]
+        p = fs_root.joinpath(*resource_path)
+        return p.read_text(encoding="utf-8")
+
+
+def persona_text() -> str:
+    return _read_text(_PERSONA_RESOURCE)
+
+
+def skill_text() -> str:
+    return _read_text(_SKILL_RESOURCE)
+
+
+def extension_source_dir() -> Path:
+    """MV3 扩展源目录（bundled）。优先 importlib.resources，回退文件系统。"""
+    try:
+        from importlib import resources
+
+        root = resources.files("research_assistant").joinpath("loginstate", "extension")
+        if root.is_dir():
+            with resources.as_file(root) as p:
+                return Path(p)
+    except Exception:
+        pass
+    fs_root = Path(__file__).resolve().parent  # src/research_assistant/
+    p = fs_root / "loginstate" / "extension"
+    if p.is_dir():
+        return p
+    raise ResearchAssistantError("MV3 扩展源未找到（loginstate/extension 缺失）")
+
+
+# ---------------------------------------------------------------------------
+# 因家生成 agent 定义
+# ---------------------------------------------------------------------------
+
+
+def generate_agent(family: Family) -> str | None:
+    """按家生成 researcher agent 定义内容；Hermes 返回 None（无独立文件）。"""
+    persona = persona_text()
+    if family.agent_format == "none":
+        return None
+    if family.agent_format == "toml":
+        return _generate_codex_toml(persona)
+    return _generate_agent_md(family, persona)
+
+
+def _frontmatter_line(value: Any) -> str:
+    if isinstance(value, str) and ("\n" in value or ":" in value):
+        # 多行/含冒号的值用引号包裹并转义内部引号（不用 f-string 内反斜杠，兼容 3.10）
+        escaped = value.replace('"', '\\"')
+        return '"' + escaped + '"'
+    return str(value)
+
+
+def _generate_agent_md(family: Family, persona: str) -> str:
+    fields: dict[str, Any] = {
+        "name": AGENT_NAME,
+        "description": (
+            "Use this sub-agent for research that needs external information (web search, docs, "
+            "page fetching). It runs in isolation and returns only a summary; the full report is on disk."
+        ),
+    }
+    fields.update(family.md_fields)
+    fm_lines = ["---"]
+    for k, v in fields.items():
+        fm_lines.append(f"{k}: {_frontmatter_line(v)}")
+    fm_lines.append("---")
+    fm_lines.append("")
+    return "\n".join(fm_lines) + persona
+
+
+def _generate_codex_toml(persona: str) -> str:
+    # Codex AgentRoleToml schema（openai/codex 源码确认，deepwiki 2026-07）：
+    # 顶层合法字段：name / description / developer_instructions / model / nickname_candidates / config_file。
+    # sandbox 经子表配置（[sandbox_workspace_write]），mcp_servers 属 config.toml 顶层 [mcp_servers] 表——
+    # 二者均非 agent 文件顶层字段。此前误写的 sandbox_mode / mcp_servers 顶层键已移除，避免 codex 解析告警。
+    # model 省略 → 继承 codex 全局 model 配置（不写非法的 "inherit" 字面值）。
+    # developer_instructions 用三引号 toml 字符串承载 persona。
+    return (
+        f'name = "{AGENT_NAME}"\n'
+        f'description = "Research sub-agent: web search, docs, page fetch. Runs in isolation, returns summary only."\n'
+        f'developer_instructions = """\n{persona.strip()}\n"""\n'
+    )
+
+
+def skill_for_family(family: Family) -> str:
+    """SKILL.md 内容。Hermes 把 researcher 人设融入（ADR-0008 D7）。"""
+    base = skill_text()
+    if family.name == "hermes":
+        # Hermes 无独立 agent 文件，把 persona 附到 skill 末尾
+        return base.rstrip() + "\n\n## researcher persona (runtime delegation)\n\n" + persona_text().strip() + "\n"
+    return base
+
+
+# ---------------------------------------------------------------------------
+# 路径解析
+# ---------------------------------------------------------------------------
+
+
+def _home(root: str | Path | None) -> Path:
+    if root:
+        return Path(root).expanduser()
+    return Path.home()
+
+
+def skill_path(family: Family, root: str | Path | None = None) -> Path:
+    return _home(root) / family.skill_relative / "SKILL.md"
+
+
+def agent_path(family: Family, root: str | Path | None = None) -> Path | None:
+    if family.agent_relative is None:
+        return None
+    return _home(root) / family.agent_relative
+
+
+# ---------------------------------------------------------------------------
+# install / status / update
+# ---------------------------------------------------------------------------
+
+
+def install(families: list[str], *, root: str | Path | None = None) -> dict[str, Any]:
+    home = _home(root)
+    installed: list[dict[str, Any]] = []
+    failed: list[dict[str, str]] = []
+    for fname in families:
+        family = ALL_FAMILIES[fname]
+        try:
+            sp = skill_path(family, home)
+            sp.parent.mkdir(parents=True, exist_ok=True)
+            sp.write_text(skill_for_family(family), encoding="utf-8")
+            entry: dict[str, Any] = {
+                "family": fname,
+                "skill_path": str(sp),
+            }
+            ap = agent_path(family, home)
+            if ap is not None:
+                ap.parent.mkdir(parents=True, exist_ok=True)
+                ap.write_text(generate_agent(family) or "", encoding="utf-8")
+                entry["agent_path"] = str(ap)
+                entry["agent_format"] = family.agent_format
+            else:
+                entry["agent_path"] = None
+                entry["agent_format"] = "none"
+            installed.append(entry)
+        except OSError as e:
+            failed.append({"family": fname, "error": str(e)})
+
+    # 附带复制 MV3 扩展（登录态层，ADR-0006）
+    extension_copied = False
+    extension_dest = None
+    try:
+        extension_dest = _copy_extension()
+        extension_copied = True
+    except Exception as e:
+        failed.append({"family": "extension", "error": str(e)})
+
+    return {
+        "root": str(home),
+        "installed": installed,
+        "failed": failed,
+        "extension_copied": extension_copied,
+        "extension_path": str(extension_dest) if extension_dest else None,
+    }
+
+
+def status(families: list[str], *, root: str | Path | None = None) -> dict[str, Any]:
+    home = _home(root)
+    out: list[dict[str, Any]] = []
+    for fname in families:
+        family = ALL_FAMILIES[fname]
+        item = _status_family(family, home)
+        item["family"] = fname
+        out.append(item)
+    counts: dict[str, int] = {}
+    for it in out:
+        s = it["skill_status"]
+        counts[s] = counts.get(s, 0) + 1
+    return {"root": str(home), "targets": out, "status_counts": counts}
+
+
+def update(families: list[str], *, root: str | Path | None = None) -> dict[str, Any]:
+    return install(families, root=root)
+
+
+def _status_family(family: Family, home: Path) -> dict[str, Any]:
+    sp = skill_path(family, home)
+    bundled_skill = skill_for_family(family)
+    skill_status = _compare(sp, bundled_skill)
+    result: dict[str, Any] = {
+        "skill_path": str(sp),
+        "skill_status": skill_status,
+    }
+    ap = agent_path(family, home)
+    if ap is not None:
+        bundled_agent = generate_agent(family) or ""
+        result["agent_path"] = str(ap)
+        result["agent_status"] = _compare(ap, bundled_agent)
+    else:
+        result["agent_path"] = None
+        result["agent_status"] = "none"
+    return result
+
+
+def _compare(path: Path, bundled: str) -> str:
+    """对比 installed 与 bundled：missing/stale/up-to-date/extra。"""
+    if not path.exists():
+        return "missing"
+    try:
+        installed = path.read_text(encoding="utf-8")
+    except OSError:
+        return "missing"
+    if installed == bundled:
+        return "up-to-date"
+    return "stale"
+
+
+# ---------------------------------------------------------------------------
+# 扩展复制
+# ---------------------------------------------------------------------------
+
+
+def _copy_extension() -> Path:
+    """把 bundled MV3 扩展复制到 ~/.research-assistant/extension/。"""
+    import shutil
+
+    from . import config as config_mod
+
+    src = extension_source_dir()
+    dest = config_mod.config_dir() / "extension"
+    if dest.exists():
+        shutil.rmtree(dest)
+    shutil.copytree(src, dest)
+    return dest

package/src/research_assistant/locate/__init__.py

@@ -0,0 +1,5 @@
+"""locate 包：锚点法速览预筛。"""
+
+from .engine import Anchor, locate
+
+__all__ = ["Anchor", "locate"]

package/src/research_assistant/locate/engine.py

@@ -0,0 +1,289 @@
+"""locate 包：锚点法速览预筛（PM §4.3 / ADR locate 非强制）。
+
+锚点法：模型输出原文里实际存在的一句话（quote）+ 相关度；行号由代码字符串匹配算出
+（模型擅长找关键句、代码擅长计数）。行号一律基于已落盘 md 副本（稳定性，基线 §7.4）。
+
+流程：
+    读 md → 切块（paragraph / lines 窗口）→ 高并发小模型批量打分（输出 quote+relevance XML）
+    → 代码匹配 quote 到行号区间 → top N + 周边 K 行 context
+"""
+
+from __future__ import annotations
+
+import asyncio
+import re
+import xml.etree.ElementTree as ET
+from dataclasses import dataclass
+from typing import Any
+
+from ..config import Config
+from ..providers import openai_compat
+
+
+@dataclass
+class Chunk:
+    text: str
+    line_start: int  # 1-based
+    line_end: int  # 1-based
+
+
+@dataclass
+class Anchor:
+    quote: str
+    line_start: int
+    line_end: int
+    scope: str
+    context: str
+    relevance: float
+
+
+def chunk_md(text: str, scope: str, window: int = 40) -> list[Chunk]:
+    """把 md 文本切成块。scope=paragraph 按空行分段；scope=lines 按固定行窗口。"""
+    lines = text.splitlines()
+    if scope == "lines":
+        chunks: list[Chunk] = []
+        i = 0
+        while i < len(lines):
+            block = lines[i : i + window]
+            if any(s.strip() for s in block):
+                chunks.append(Chunk("\n".join(block), i + 1, i + len(block)))
+            i += window
+        return chunks
+    # paragraph：按空行分段，记录行号
+    chunks: list[Chunk] = []
+    start = 0
+    buf: list[str] = []
+    for idx, line in enumerate(lines):
+        if line.strip() == "":
+            if any(s.strip() for s in buf):
+                chunks.append(Chunk("\n".join(buf), start + 1, start + len(buf)))
+            buf = []
+            start = idx + 1
+        else:
+            if not buf:
+                start = idx
+            buf.append(line)
+    if any(s.strip() for s in buf):
+        chunks.append(Chunk("\n".join(buf), start + 1, start + len(buf)))
+    return chunks
+
+
+_PROMPT_SYSTEM = (
+    "You locate the most relevant passage in a text chunk for a given question. "
+    "If (and only if) the chunk contains content relevant to the question, output an XML <anchor> with:\n"
+    "  <quote>: an EXACT, verbatim sentence or phrase COPIED from the chunk (do not paraphrase).\n"
+    "  <relevance>: a float 0.0-1.0.\n"
+    "If the chunk is irrelevant, output <anchors></anchors> with nothing inside. "
+    "Output ONLY the XML, no prose."
+)
+
+
+def _build_user(query: str, chunk_text: str) -> str:
+    return (
+        f"Question: {query}\n\n"
+        f"Chunk:\n\"\"\"\n{chunk_text}\n\"\"\"\n\n"
+        f"Output the <anchors> XML now."
+    )
+
+
+_ANCHOR_RE = re.compile(r"<anchor>(.*?)</anchor>", re.DOTALL)
+_QUOTE_RE = re.compile(r"<quote>(.*?)</quote>", re.DOTALL)
+_REL_RE = re.compile(r"<relevance>(.*?)</relevance>", re.DOTALL)
+
+
+def parse_anchors_xml(content: str) -> list[tuple[str, float]]:
+    """从模型输出解析 (quote, relevance) 列表（容忍外层包裹的非 XML 文本）。"""
+    results: list[tuple[str, float]] = []
+    for m in _ANCHOR_RE.finditer(content):
+        block = m.group(1)
+        q = _QUOTE_RE.search(block)
+        r = _REL_RE.search(block)
+        if not q:
+            continue
+        quote = _decode_xml_text(q.group(1)).strip()
+        if not quote:
+            continue
+        rel = 0.5
+        if r:
+            try:
+                rel = float(_decode_xml_text(r.group(1)).strip())
+            except ValueError:
+                rel = 0.5
+        results.append((quote, max(0.0, min(1.0, rel))))
+    # 兜底：用 ElementTree 再试一次（模型偶尔回合法 XML）
+    if not results:
+        try:
+            root = ET.fromstring(content.strip())
+            for a in root.iter("anchor"):
+                q = a.findtext("quote")
+                r = a.findtext("relevance")
+                if q and q.strip():
+                    try:
+                        rel = float(r) if r else 0.5
+                    except ValueError:
+                        rel = 0.5
+                    results.append((q.strip(), max(0.0, min(1.0, rel))))
+        except ET.ParseError:
+            pass
+    return results
+
+
+def _decode_xml_text(s: str) -> str:
+    return (
+        s.replace("&lt;", "<")
+        .replace("&gt;", ">")
+        .replace("&amp;", "&")
+        .replace("&quot;", '"')
+        .replace("&apos;", "'")
+    )
+
+
+def _normalize_ws(s: str) -> str:
+    return " ".join(s.split())
+
+
+def find_quote_lines(full_text: str, quote: str) -> tuple[int, int] | None:
+    """在全文中定位 quote 的行号区间（1-based）。归一化空白后做子串匹配。
+
+    模型可能微调标点/空白，故采用归一化匹配；找不到返回 None。
+    """
+    norm_quote = _normalize_ws(quote)
+    if not norm_quote:
+        return None
+    # 取 quote 的特征前缀/后缀（避免模型夹带多余字）
+    lines = full_text.splitlines()
+    norm_lines = [_normalize_ws(l) for l in lines]
+    joined = "\n".join(norm_lines)
+
+    # 直接整体匹配
+    pos = _fuzzy_find(joined, norm_quote)
+    if pos is None:
+        # 退化为首句匹配（取 quote 第一个句子）
+        first_sentence = re.split(r"(?<=[。.!？?])\s", norm_quote)
+        probe = first_sentence[0] if first_sentence else norm_quote[:60]
+        if len(probe) < 8:
+            return None
+        pos = _fuzzy_find(joined, probe)
+        if pos is None:
+            return None
+    # 把字符偏移映射回行号（基于 joined 的换行结构）
+    return _offset_to_lines(joined, pos, norm_quote)
+
+
+def _fuzzy_find(haystack: str, needle: str) -> int | None:
+    """在归一化文本里找 needle；先精确，失败则用最长 token 序列近似。"""
+    idx = haystack.find(needle)
+    if idx >= 0:
+        return idx
+    # 容忍 needle 中间多了少量字符：取首尾各 ~20 字符做定位
+    if len(needle) > 40:
+        head, tail = needle[:20], needle[-20:]
+        hi = haystack.find(head)
+        if hi >= 0:
+            tj = haystack.find(tail, hi)
+            if tj >= 0:
+                return hi
+    return None
+
+
+def _offset_to_lines(joined: str, pos: int, needle: str) -> tuple[int, int]:
+    """joined 是 '\\n'.join(norm_lines)；把 [pos, pos+len) 映射到 1-based 行号。"""
+    # 计算每行起始偏移
+    line_starts = [0]
+    for i, ch in enumerate(joined):
+        if ch == "\n":
+            line_starts.append(i + 1)
+    end = min(pos + len(needle), len(joined))
+    start_line = _bisect_line(line_starts, pos)
+    end_line = _bisect_line(line_starts, max(pos, end - 1))
+    return start_line + 1, end_line + 1
+
+
+def _bisect_line(line_starts: list[int], offset: int) -> int:
+    # 最大 i 使 line_starts[i] <= offset
+    import bisect
+
+    return bisect.bisect_right(line_starts, offset) - 1
+
+
+def build_context(lines: list[str], line_start: int, line_end: int, k: int) -> str:
+    """取 [line_start, line_end] 周围各 K 行的上下文文本。"""
+    lo = max(1, line_start - k)
+    hi = min(len(lines), line_end + k)
+    return "\n".join(lines[lo - 1 : hi])
+
+
+async def locate(
+    config: Config,
+    md_text: str,
+    query: str,
+    *,
+    scope: str = "paragraph",
+    top: int = 5,
+    context_k: int = 3,
+    concurrency: int | None = None,
+) -> list[Anchor]:
+    """主入口：对 md_text 跑锚点定位，返回 top N anchors（按 relevance 降序）。"""
+    if concurrency is None:
+        loc_cfg = config.provider("locate")
+        concurrency = loc_cfg.concurrency if loc_cfg else 8
+
+    chunks = chunk_md(md_text, scope)
+    if not chunks:
+        return []
+
+    sem = asyncio.Semaphore(max(1, concurrency))
+
+    async def score_one(chunk: Chunk) -> list[tuple[str, float, Chunk]]:
+        async with sem:
+            resp = await openai_compat.chat_completion(
+                config,
+                [
+                    {"role": "system", "content": _PROMPT_SYSTEM},
+                    {"role": "user", "content": _build_user(query, chunk.text)},
+                ],
+                provider_type="locate",
+                temperature=0.0,
+            )
+            msg = openai_compat.extract_message(resp)
+            content = openai_compat.strip_think(msg.get("content") or "")
+            if isinstance(content, list):
+                content = "\n".join(seg.get("text", "") for seg in content if isinstance(seg, dict))
+            parsed = parse_anchors_xml(content)
+            return [(q, r, chunk) for q, r in parsed]
+
+    batch_results = await asyncio.gather(*[score_one(c) for c in chunks], return_exceptions=True)
+
+    lines = md_text.splitlines()
+    anchors: list[Anchor] = []
+    for res in batch_results:
+        if isinstance(res, Exception):
+            continue
+        for quote, rel, chunk in res:
+            span = find_quote_lines(md_text, quote)
+            if span is None:
+                # 退回 chunk 自身范围（行号稳定性优先用全文匹配，失败才回退）
+                ls, le = chunk.line_start, chunk.line_end
+            else:
+                ls, le = span
+            anchors.append(
+                Anchor(
+                    quote=quote,
+                    line_start=ls,
+                    line_end=le,
+                    scope=scope,
+                    context=build_context(lines, ls, le, context_k),
+                    relevance=rel,
+                )
+            )
+
+    # 去重（相同行区间）+ 排序 + top N
+    seen: set[tuple[int, int]] = set()
+    unique: list[Anchor] = []
+    for a in sorted(anchors, key=lambda x: x.relevance, reverse=True):
+        key = (a.line_start, a.line_end)
+        if key in seen:
+            continue
+        seen.add(key)
+        unique.append(a)
+    return unique[:top]

package/src/research_assistant/loginstate/__init__.py

@@ -0,0 +1,10 @@
+"""登录态层（ADR-0006）：内嵌 cdt 扩展桥。
+
+- MV3 扩展（bundled，装在用户日常浏览器）用 chrome.cookies 读明文 cookie（绕 ABE）→ 推 daemon。
+- cookie daemon（Python 移植自 cdt）缓存并暴露 /cookies。
+- fetch 启动时取 cookie，add_cookies 注入隔离 profile（避 lock）。
+"""
+
+from .daemonctl import daemon_status, ensure_daemon, get_cookies, to_playwright_cookies
+
+__all__ = ["daemon_status", "ensure_daemon", "get_cookies", "to_playwright_cookies"]