litloop 1.18.3__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (176) hide show
  1. litloop/__init__.py +89 -0
  2. litloop/__main__.py +6 -0
  3. litloop/_source_hygiene.py +158 -0
  4. litloop/agents/__init__.py +13 -0
  5. litloop/agents/client.py +164 -0
  6. litloop/agents/runner.py +123 -0
  7. litloop/agents/system.py +54 -0
  8. litloop/agents/tools.py +142 -0
  9. litloop/app_server.py +8 -0
  10. litloop/browser/__init__.py +1 -0
  11. litloop/browser/backend.py +1009 -0
  12. litloop/browser/camofox_api.py +368 -0
  13. litloop/browser/chrome_copy.py +136 -0
  14. litloop/browser/cloakbrowser_compat.py +72 -0
  15. litloop/browser/cookies.py +347 -0
  16. litloop/browser/engine.py +965 -0
  17. litloop/browser/login.py +636 -0
  18. litloop/browser/pdf.py +263 -0
  19. litloop/browser/profile_health.py +167 -0
  20. litloop/browser/runtime.py +210 -0
  21. litloop/cache.py +104 -0
  22. litloop/citations/__init__.py +1 -0
  23. litloop/citations/bib_import.py +102 -0
  24. litloop/citations/bibtex_crossref.py +143 -0
  25. litloop/citations/formats.py +225 -0
  26. litloop/citations/paper_list.py +200 -0
  27. litloop/citations/session_export.py +94 -0
  28. litloop/cli/__init__.py +12 -0
  29. litloop/cli/_utils.py +267 -0
  30. litloop/cli/commands.py +1098 -0
  31. litloop/cli/doctor.py +141 -0
  32. litloop/cli/main.py +1173 -0
  33. litloop/cli/web.py +190 -0
  34. litloop/config.py +413 -0
  35. litloop/data/VARCON-LICENSE.txt +62 -0
  36. litloop/data/elements.tsv +119 -0
  37. litloop/data/institutional_identity_policy.json +165 -0
  38. litloop/data/publisher_access_catalog.json +969 -0
  39. litloop/data/publisher_carsi.json +105 -0
  40. litloop/data/spelling_search.tsv.gz +0 -0
  41. litloop/data/spelling_us.tsv.gz +0 -0
  42. litloop/data/webvpn.dat +0 -0
  43. litloop/data/webvpn.json +603 -0
  44. litloop/db.py +1922 -0
  45. litloop/deps.py +128 -0
  46. litloop/desktop/__init__.py +1 -0
  47. litloop/desktop/agent_runner.py +537 -0
  48. litloop/desktop/download_jobs.py +571 -0
  49. litloop/desktop/error_text.py +192 -0
  50. litloop/desktop/server.py +999 -0
  51. litloop/desktop/settings.py +552 -0
  52. litloop/desktop/translate.py +103 -0
  53. litloop/diagnostics.py +126 -0
  54. litloop/download/__init__.py +1 -0
  55. litloop/download/doi_check.py +44 -0
  56. litloop/download/fetcher.py +975 -0
  57. litloop/download/markdown.py +130 -0
  58. litloop/download/pdf.py +454 -0
  59. litloop/download/pipeline.py +1166 -0
  60. litloop/download/progress.py +312 -0
  61. litloop/download/rename.py +211 -0
  62. litloop/extractors/__init__.py +0 -0
  63. litloop/extractors/html_extractor.py +31 -0
  64. litloop/extractors/pdf_extractor.py +151 -0
  65. litloop/extractors/publisher_adapters/__init__.py +0 -0
  66. litloop/extractors/publisher_adapters/acs.py +167 -0
  67. litloop/extractors/publisher_adapters/elsevier.py +178 -0
  68. litloop/extractors/publisher_adapters/generic.py +191 -0
  69. litloop/extractors/publisher_adapters/nature.py +204 -0
  70. litloop/extractors/publisher_adapters/rsc.py +154 -0
  71. litloop/extractors/publisher_adapters/tandfonline.py +154 -0
  72. litloop/extractors/publisher_adapters/wiley.py +160 -0
  73. litloop/http_utils.py +57 -0
  74. litloop/identifiers.py +134 -0
  75. litloop/institutional/__init__.py +1 -0
  76. litloop/institutional/auth.py +576 -0
  77. litloop/institutional/carsi_login.py +569 -0
  78. litloop/institutional/config_adapter.py +63 -0
  79. litloop/institutional/proxy_check.py +98 -0
  80. litloop/institutional/remote_assist.py +274 -0
  81. litloop/institutional/schools.py +102 -0
  82. litloop/institutional/session_heal.py +73 -0
  83. litloop/institutional/session_store.py +105 -0
  84. litloop/log.py +47 -0
  85. litloop/models.py +269 -0
  86. litloop/network.py +417 -0
  87. litloop/optional.py +310 -0
  88. litloop/publishers/__init__.py +1 -0
  89. litloop/publishers/access.py +232 -0
  90. litloop/publishers/pdf_router.py +451 -0
  91. litloop/publishers/profiles.py +899 -0
  92. litloop/publishers/strategies/__init__.py +122 -0
  93. litloop/publishers/strategies/_core.py +2340 -0
  94. litloop/publishers/strategies/_elsevier_api.py +578 -0
  95. litloop/publishers/strategies/acm.py +27 -0
  96. litloop/publishers/strategies/acs.py +42 -0
  97. litloop/publishers/strategies/aip.py +27 -0
  98. litloop/publishers/strategies/aps.py +29 -0
  99. litloop/publishers/strategies/asce.py +28 -0
  100. litloop/publishers/strategies/base.py +108 -0
  101. litloop/publishers/strategies/copernicus.py +24 -0
  102. litloop/publishers/strategies/elsevier.py +66 -0
  103. litloop/publishers/strategies/generic.py +39 -0
  104. litloop/publishers/strategies/ieee.py +28 -0
  105. litloop/publishers/strategies/iop.py +27 -0
  106. litloop/publishers/strategies/nature.py +27 -0
  107. litloop/publishers/strategies/oxford.py +27 -0
  108. litloop/publishers/strategies/registry.py +83 -0
  109. litloop/publishers/strategies/royalsociety.py +28 -0
  110. litloop/publishers/strategies/rsc.py +27 -0
  111. litloop/publishers/strategies/sage.py +30 -0
  112. litloop/publishers/strategies/science.py +27 -0
  113. litloop/publishers/strategies/springer.py +34 -0
  114. litloop/publishers/strategies/tandfonline.py +32 -0
  115. litloop/publishers/strategies/wiley.py +32 -0
  116. litloop/publishers/supplementary.py +219 -0
  117. litloop/quota.py +202 -0
  118. litloop/search/__init__.py +1 -0
  119. litloop/search/abstracts.py +291 -0
  120. litloop/search/deep.py +1216 -0
  121. litloop/search/quick.py +1102 -0
  122. litloop/search/scansci_find.py +410 -0
  123. litloop/search/screening.py +225 -0
  124. litloop/search/title_to_doi.py +163 -0
  125. litloop/search/watches.py +124 -0
  126. litloop/server.py +1731 -0
  127. litloop/sources/__init__.py +1339 -0
  128. litloop/sources/_batch.py +529 -0
  129. litloop/sources/_index.py +221 -0
  130. litloop/sources/_routes.py +290 -0
  131. litloop/sources/altcha.py +90 -0
  132. litloop/sources/arxiv.py +45 -0
  133. litloop/sources/attempt.py +91 -0
  134. litloop/sources/carsi.py +74 -0
  135. litloop/sources/core_api.py +46 -0
  136. litloop/sources/crossref.py +162 -0
  137. litloop/sources/elsevier_api.py +620 -0
  138. litloop/sources/elsevier_check.py +274 -0
  139. litloop/sources/europepmc.py +81 -0
  140. litloop/sources/ezproxy.py +317 -0
  141. litloop/sources/instsci.py +1295 -0
  142. litloop/sources/libgen.py +116 -0
  143. litloop/sources/nature.py +39 -0
  144. litloop/sources/oa_discovery.py +135 -0
  145. litloop/sources/openaire.py +122 -0
  146. litloop/sources/openalex.py +100 -0
  147. litloop/sources/publishers.py +684 -0
  148. litloop/sources/sage_cn.py +139 -0
  149. litloop/sources/scibban.py +10 -0
  150. litloop/sources/scihub.py +1379 -0
  151. litloop/sources/scihub_domains.py +203 -0
  152. litloop/sources/scihub_speed.py +187 -0
  153. litloop/sources/scoring.py +250 -0
  154. litloop/sources/semantic_scholar.py +146 -0
  155. litloop/sources/springer_tdm.py +172 -0
  156. litloop/sources/unpaywall.py +116 -0
  157. litloop/sources/vpnsci.py +38 -0
  158. litloop/store.py +264 -0
  159. litloop/templates/index.html +347 -0
  160. litloop/terms/__init__.py +1 -0
  161. litloop/terms/glossary.py +422 -0
  162. litloop/terms/spelling.py +89 -0
  163. litloop/terms/text.py +106 -0
  164. litloop/tor/__init__.py +1 -0
  165. litloop/tor/embedded.py +371 -0
  166. litloop/tor/proxy.py +110 -0
  167. litloop/updates.py +148 -0
  168. litloop/zotero/__init__.py +1 -0
  169. litloop/zotero/bridge.py +309 -0
  170. litloop/zotero/client.py +317 -0
  171. litloop-1.18.3.dist-info/METADATA +347 -0
  172. litloop-1.18.3.dist-info/RECORD +176 -0
  173. litloop-1.18.3.dist-info/WHEEL +5 -0
  174. litloop-1.18.3.dist-info/entry_points.txt +2 -0
  175. litloop-1.18.3.dist-info/licenses/LICENSE +197 -0
  176. litloop-1.18.3.dist-info/top_level.txt +1 -0
litloop/deps.py ADDED
@@ -0,0 +1,128 @@
1
+ """Dependency checking and graceful degradation."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import importlib
6
+ from typing import Any
7
+
8
+ from .log import get_logger
9
+
10
+ log = get_logger()
11
+
12
+ # Core dependencies (required)
13
+ CORE_DEPS = {
14
+ "requests": "HTTP client",
15
+ "bs4": "HTML parsing (beautifulsoup4)",
16
+ "mcp": "MCP protocol",
17
+ "typer": "CLI framework",
18
+ "uvicorn": "ASGI server",
19
+ "fastapi": "Web UI / HTTP transport",
20
+ "jinja2": "Web UI templates",
21
+ "pymupdf": "PDF text extraction (PyMuPDF)",
22
+ }
23
+
24
+ # Optional dependencies
25
+ OPTIONAL_DEPS = {
26
+ "socks": "SOCKS proxy support (requests[socks])",
27
+ "Crypto": "WebVPN AES encryption (pycryptodome)",
28
+ "patchright": "Stealth browser backend (default; open-source Playwright fork)",
29
+ "cloakbrowser": "Stealth browser backend (fallback; free tier pinned to Chromium 146)",
30
+ }
31
+
32
+ _feature_status: dict[str, bool] = {}
33
+
34
+
35
+ def check_dependency(module_name: str) -> bool:
36
+ """Check if a Python module is available."""
37
+ try:
38
+ importlib.import_module(module_name)
39
+ return True
40
+ except ImportError:
41
+ return False
42
+
43
+
44
+ def check_all() -> dict[str, dict[str, Any]]:
45
+ """Check all dependencies and return status report."""
46
+ result = {"core": {}, "optional": {}}
47
+
48
+ for module, desc in CORE_DEPS.items():
49
+ available = check_dependency(module)
50
+ result["core"][module] = {
51
+ "available": available,
52
+ "description": desc,
53
+ "required": True,
54
+ }
55
+
56
+ for module, desc in OPTIONAL_DEPS.items():
57
+ available = check_dependency(module)
58
+ result["optional"][module] = {
59
+ "available": available,
60
+ "description": desc,
61
+ "required": False,
62
+ }
63
+
64
+ return result
65
+
66
+
67
+ def is_feature_available(feature: str) -> bool:
68
+ """Check if a feature's dependencies are met."""
69
+ if feature in _feature_status:
70
+ return _feature_status[feature]
71
+
72
+ feature_deps = {
73
+ "socks_proxy": ["socks"],
74
+ "instsci": ["Crypto", "cloakbrowser"],
75
+ "html_parse": ["bs4"],
76
+ }
77
+
78
+ deps = feature_deps.get(feature, [])
79
+ available = all(check_dependency(d) for d in deps)
80
+ _feature_status[feature] = available
81
+ return available
82
+
83
+
84
+ def warn_missing(feature: str, module: str) -> None:
85
+ """Log a warning when an optional dependency is missing."""
86
+ log.warning(f"Feature '{feature}' disabled: install '{module}' to enable")
87
+
88
+
89
+ def print_status() -> None:
90
+ """Print dependency status to stderr."""
91
+ report = check_all()
92
+
93
+ log.info("=== Dependency Status ===")
94
+
95
+ all_ok = True
96
+ for module, info in report["core"].items():
97
+ status = "OK" if info["available"] else "MISSING"
98
+ if not info["available"]:
99
+ all_ok = False
100
+ log.info(f" [{status}] {module} - {info['description']}")
101
+
102
+ if not all_ok:
103
+ log.warning("Some core dependencies are missing! Install with: pip install litloop")
104
+
105
+ has_optional = False
106
+ for module, info in report["optional"].items():
107
+ if info["available"]:
108
+ status = "OK"
109
+ else:
110
+ status = "optional"
111
+ has_optional = True
112
+ log.info(f" [{status}] {module} - {info['description']}")
113
+
114
+ # cloakbrowser iterates on anti-detection patches fast; flag stale installs
115
+ # so users know to upgrade even when the package is present.
116
+ if report["optional"].get("cloakbrowser", {}).get("available"):
117
+ try:
118
+ from .cli import _cloakbrowser_version_status
119
+ cb_status, cb_detail = _cloakbrowser_version_status()
120
+ if cb_status == "outdated":
121
+ log.warning(f" [STALE] cloakbrowser {cb_detail}")
122
+ except Exception:
123
+ pass
124
+
125
+ if has_optional:
126
+ log.info(" Install optional deps: pip install litloop[fast,vpnsci]")
127
+
128
+ log.info("========================")
@@ -0,0 +1 @@
1
+ """Desktop application backend, settings, and agent runner."""
@@ -0,0 +1,537 @@
1
+ """Searches started from the desktop app: the form becomes a message to the agent.
2
+
3
+ The app does what the user would do in a chat: it sends the question, the
4
+ criteria, the year and journal filters, the seeds and the scale to the agent
5
+ (``agent_command``, Claude Code's ``claude -p`` by default), which runs the
6
+ usual LitLoop workflow with the litloop tools and saves a screening session.
7
+ One run at a time. Each run is ``agent_runs/<id>.json`` (status, what the agent
8
+ is doing, the screening session it saved) plus the agent's raw output in
9
+ ``agent_runs/<id>.log``.
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ import json
15
+ import os
16
+ import re
17
+ import shlex
18
+ import shutil
19
+ import subprocess
20
+ import threading
21
+ import time
22
+ from datetime import datetime
23
+ from pathlib import Path
24
+ from typing import Any
25
+
26
+ from .. import config as _config
27
+ from .. import db, store
28
+
29
+ # What the agent tells the app, by tool: shown under the run as it works.
30
+ _TOOL_TEXT = {
31
+ "litloop_search": "正在检索",
32
+ "litloop_deep_search": "正在深度检索",
33
+ "litloop_screening": "正在保存评分",
34
+ "litloop_find": "正在查找文献",
35
+ "litloop_config": "正在读取设置",
36
+ "litloop_diagnostics": "正在检测设置",
37
+ }
38
+ _SESSION_RE = re.compile(r'"session"\s*:\s*"([^"]+)"')
39
+ _LOCK = threading.Lock()
40
+ _DONE: set[str] = set() # builtin runs whose final state is written
41
+ _PROCS: dict[str, subprocess.Popen] = {}
42
+ _CANCELLED: set[str] = set()
43
+ _SESSION_TOOLS = frozenset({"litloop_screening", "litloop_deep_search"})
44
+ # Backend B runs in a thread of this process instead of a child process.
45
+ _BUILTIN: dict[str, threading.Thread] = {}
46
+ _STOP: dict[str, threading.Event] = {}
47
+ _BUILTIN_TOOLS = {
48
+ "search": "正在检索",
49
+ "deep_search_start": "深度检索:正在构建候选池",
50
+ "deep_search_rate": "深度检索:正在保存本批评分",
51
+ "deep_search_next": "深度检索:正在生成下一批",
52
+ "deep_search_status": "深度检索:正在查看进度",
53
+ "screening_save": "正在保存评分",
54
+ }
55
+
56
+
57
+ class _Cancelled(Exception):
58
+ pass
59
+
60
+
61
+ def runs_dir() -> Path:
62
+ return _config.DATA_DIR / "agent_runs"
63
+
64
+
65
+ def _path(run: str) -> Path:
66
+ if not re.fullmatch(r"[0-9-]+", run):
67
+ raise ValueError("无法打开检索:编号不正确")
68
+ return runs_dir() / f"{run}.json"
69
+
70
+
71
+ def _lines(text: str) -> list[str]:
72
+ return [s.strip() for s in re.split(r"[\n;;]+", text or "") if s.strip()]
73
+
74
+
75
+ def build_prompt(form: dict[str, Any], skill: bool = True) -> str:
76
+ """The message the user would have typed, from the app's form.
77
+
78
+ ``skill=False`` is for the built-in agent: it is told what to do by the system
79
+ prompt in ``litloop.agents.system`` instead of by a skill it cannot read.
80
+ """
81
+ question = str(form.get("question") or "").strip()
82
+ if not question:
83
+ raise ValueError("填写检索问题")
84
+ deep = form.get("mode") == "deep"
85
+ parts = [f"{'用 litloop 技能' if skill else ''}{'做深度检索' if deep else '快速查找文献'}:{question}"]
86
+ criteria = _lines(str(form.get("criteria") or ""))
87
+ if criteria:
88
+ parts.append("纳入标准(按这些判断,不要改):\n" + "\n".join(f"- {c}" for c in criteria))
89
+ else:
90
+ parts.append("纳入标准由你按问题拟定 2–5 条,保存时写进 criteria。")
91
+ y0, y1 = form.get("year_from"), form.get("year_to")
92
+ if y0 or y1:
93
+ parts.append(f"年份:{y0 or '不限'}–{y1 or '至今'}。")
94
+ rank = []
95
+ if form.get("max_cas_zone"):
96
+ rank.append(f"中科院分区 {form['max_cas_zone']} 区及以上(max_cas_zone={form['max_cas_zone']})")
97
+ if form.get("max_jcr_quartile"):
98
+ rank.append(f"JCR Q{form['max_jcr_quartile']} 及以上(max_jcr_quartile={form['max_jcr_quartile']})")
99
+ if form.get("exclude_warning"):
100
+ rank.append("排除预警期刊(exclude_warning=true)")
101
+ if rank:
102
+ parts.append("期刊要求:" + ";".join(rank) + "。")
103
+ seeds = _lines(str(form.get("seeds") or "").replace(",", "\n").replace(",", "\n"))
104
+ if seeds:
105
+ parts.append("种子文献:" + "、".join(seeds))
106
+ if form.get("seed_collection"):
107
+ parts.append(f"Zotero 分类「{form['seed_collection']}」里的文献也作种子(seed_collection)。")
108
+ if deep:
109
+ batches = int(form.get("batches") or 0)
110
+ parts.append(
111
+ f"每批逐篇评分后取下一批,{'最多 ' + str(batches) + ' 批,' if batches else ''}"
112
+ "返回 stop_suggested=true 时停止。")
113
+ else:
114
+ parts.append(f"返回约 {int(form.get('limit') or 20)} 篇,逐篇评分后保存。")
115
+ parts.append(
116
+ "这是从 LitLoop 桌面 app 发起的任务,用户不在对话里:不要提问、不要等确认,"
117
+ "需要用户决定的事写进最后的汇报;不要下载、不要推送 Zotero。"
118
+ "结束时用两三句中文汇报筛选会话名、篇数和各相关度数量。")
119
+ return "\n\n".join(parts)
120
+
121
+
122
+ def _command() -> list[str]:
123
+ cfg = _config.load_config()
124
+ cmd = str(cfg.get("agent_command") or "claude").strip()
125
+ exe = shutil.which(cmd) or cmd
126
+ # Windows paths keep their backslashes; quotes only group words.
127
+ args = [a.strip('"') for a in shlex.split(str(cfg.get("agent_args") or ""), posix=os.name != "nt")]
128
+ return [exe, *args]
129
+
130
+
131
+ def _backend() -> str:
132
+ """Which backend runs a search started here: the agent command or a model API."""
133
+ return "builtin" if str(_config.load_config().get("agent_backend") or "") == "builtin" else "command"
134
+
135
+
136
+ def _write(run: str, data: dict[str, Any]) -> None:
137
+ store.write_json(_path(run), {k: v for k, v in data.items() if not k.startswith("_")}, indent=1)
138
+
139
+
140
+ def get(run: str) -> dict[str, Any] | None:
141
+ p = _path(run)
142
+ if not p.exists():
143
+ return None
144
+ d = store.read_json(p)
145
+ if d.get("state") == "running" and not _alive(run):
146
+ # The reader may have caught the file just before the run wrote its
147
+ # final state; if the run is gone now, look once more before calling it
148
+ # interrupted.
149
+ d = store.read_json(p)
150
+ if d.get("state") == "running":
151
+ d["state"] = "interrupted" # the app was closed while it ran
152
+ return d
153
+
154
+
155
+ def _alive(run: str) -> bool:
156
+ with _LOCK:
157
+ return run in _PROCS or run in _BUILTIN or run in _DONE
158
+
159
+
160
+ def list_runs(limit: int = 20) -> list[dict[str, Any]]:
161
+ out = []
162
+ for p in sorted(runs_dir().glob("*.json"), reverse=True)[:limit]:
163
+ d = get(p.stem)
164
+ if d:
165
+ d.pop("events", None)
166
+ out.append(d)
167
+ return out
168
+
169
+
170
+ def running() -> str | None:
171
+ with _LOCK:
172
+ for r, p in _PROCS.items():
173
+ if p.poll() is None:
174
+ return r
175
+ return next((r for r, t in _BUILTIN.items() if t.is_alive() and r not in _DONE), None)
176
+
177
+
178
+ def _new_run_id() -> str:
179
+ base = datetime.now().strftime("%Y%m%d-%H%M%S")
180
+ run = base
181
+ idx = 2
182
+ while _path(run).exists():
183
+ run = f"{base}-{idx}"
184
+ idx += 1
185
+ return run
186
+
187
+
188
+ def build_resume_prompt(session: str, *, batches: int = 0, skill: bool = True) -> str:
189
+ """Build the prompt to resume an interrupted or paused deep-search session.
190
+
191
+ Reads only the small screening record and optional summary; never reads the
192
+ (potentially huge) candidate pool file (docs/APP_DATA.md).
193
+ """
194
+ from ..search import deep as deep_search, screening
195
+
196
+ if not deep_search.has_pool(session):
197
+ raise ValueError("无法继续检索:这不是深度检索会话")
198
+ record = screening.load(session)
199
+ summary = db.load_summary(session)
200
+
201
+ question = str(record.get("question") or "").strip()
202
+ head = f"{'用 litloop 技能' if skill else ''}继续深度检索会话 {session}" + (f":{question}" if question else "")
203
+ parts = [head]
204
+ criteria = [str(c).strip() for c in (record.get("criteria") or []) if str(c).strip()]
205
+ if criteria:
206
+ parts.append("纳入标准(按这些判断,不要改):\n" + "\n".join(f"- {c}" for c in criteria))
207
+ if isinstance(summary, dict):
208
+ screened = int(summary.get("screened") or 0)
209
+ pool_size = int(summary.get("pool") or 0)
210
+ done_batches = len(summary.get("batches") or [])
211
+ parts.append(f"已有进度:已生成 {done_batches} 批,已评分 {screened}/{pool_size} 篇。")
212
+ else:
213
+ parts.append("上次检索在生成首批结果前中断,候选池基础记录已保存。")
214
+ limit_note = f"本次最多再筛 {int(batches)} 批," if batches else ""
215
+ if skill:
216
+ parts.append(
217
+ f"不要重新调用 litloop_deep_search(action='start')。请从这个会话接着做:"
218
+ f"先调用 litloop_deep_search(action='status', session={session!r}) 查看进度与 unrated;"
219
+ f"如果 unrated 非空,先按编号用 action='rate' 评完并保存,再调用 action='next' 继续生成并筛选下一批,"
220
+ f"{limit_note}返回 stop_suggested=true 时停止。"
221
+ )
222
+ else:
223
+ parts.append(
224
+ f"不要重新调用 deep_search_start。请从这个会话接着做:"
225
+ f"先调用 deep_search_status(session={session!r}) 查看进度与 unrated;"
226
+ f"如果 unrated 非空,先按编号用 deep_search_rate 评完并保存,再调用 deep_search_next(session={session!r}) 继续生成并筛选下一批,"
227
+ f"{limit_note}返回 stop_suggested=true 时停止。"
228
+ )
229
+ parts.append(
230
+ "这是从 LitLoop 桌面 app 发起的任务,用户不在对话里:不要提问、不要等确认,"
231
+ "需要用户决定的事写进最后的汇报;不要下载、不要推送 Zotero。"
232
+ "结束时用两三句中文汇报筛选会话名、总篇数和各相关度数量。"
233
+ )
234
+ return "\n\n".join(parts)
235
+
236
+
237
+ def _launch(run: str, data: dict[str, Any], prompt: str, builtin: bool) -> dict[str, Any]:
238
+ _write(run, data)
239
+ if builtin:
240
+ if not str(_config.load_config().get("builtin_agent_model") or "").strip():
241
+ data.update(state="failed", doing=None,
242
+ error="无法开始检索:还没有填内置 Agent 的模型名。在「设置 → 内置 Agent」里填写")
243
+ _write(run, data)
244
+ return data
245
+ thread = threading.Thread(target=_run_builtin, args=(run, data, prompt), daemon=True)
246
+ with _LOCK:
247
+ _BUILTIN[run] = thread
248
+ thread.start()
249
+ return data
250
+ cmd = _command()
251
+ try:
252
+ proc = subprocess.Popen(
253
+ cmd, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
254
+ cwd=str(Path.home()), env={**os.environ, "PYTHONUTF8": "1"},
255
+ creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0))
256
+ except OSError:
257
+ data.update(state="failed", doing=None, error=f"无法启动 Agent({cmd[0]})。在「设置 → Agent」中检查 Agent 命令")
258
+ _write(run, data)
259
+ return data
260
+ with _LOCK:
261
+ _PROCS[run] = proc
262
+ threading.Thread(target=_follow, args=(run, proc, prompt, data), daemon=True).start()
263
+ return data
264
+
265
+
266
+ def start(form: dict[str, Any]) -> dict[str, Any]:
267
+ builtin = _backend() == "builtin"
268
+ prompt = build_prompt(form, skill=not builtin)
269
+ if running():
270
+ raise RuntimeError("已有检索在进行,完成或取消后再开始新的检索")
271
+ run = _new_run_id()
272
+ runs_dir().mkdir(parents=True, exist_ok=True)
273
+ data = {"run": run, "state": "running", "started": datetime.now().isoformat(timespec="seconds"),
274
+ "question": str(form.get("question")).strip(), "mode": form.get("mode") or "quick",
275
+ "form": form, "prompt": prompt, "doing": "正在启动 Agent", "events": [],
276
+ "session": None, "agent_session": None, "result": None, "error": None}
277
+ return _launch(run, data, prompt, builtin)
278
+
279
+
280
+ def resume(session: str, *, batches: int = 0) -> dict[str, Any]:
281
+ builtin = _backend() == "builtin"
282
+ prompt = build_resume_prompt(session, batches=batches, skill=not builtin)
283
+ if running():
284
+ raise RuntimeError("已有检索在进行,完成或取消后再开始新的检索")
285
+ from ..search import screening
286
+ record = screening.load(session)
287
+ run = _new_run_id()
288
+ runs_dir().mkdir(parents=True, exist_ok=True)
289
+ question = str(record.get("question") or "").strip() or session
290
+ data = {"run": run, "state": "running", "started": datetime.now().isoformat(timespec="seconds"),
291
+ "question": question, "mode": "deep",
292
+ "form": {"question": question, "mode": "deep", "batches": int(batches or 0), "session": session},
293
+ "prompt": prompt, "doing": "正在继续深度检索", "events": [],
294
+ "session": session, "resumed_from": session, "agent_session": None,
295
+ "result": None, "error": None}
296
+ return _launch(run, data, prompt, builtin)
297
+
298
+
299
+ def _event(data: dict[str, Any], text: str) -> None:
300
+ data["events"].append({"t": datetime.now().strftime("%H:%M:%S"), "text": text})
301
+ data["events"] = data["events"][-200:]
302
+
303
+
304
+ def _read(data: dict[str, Any], line: str) -> None:
305
+ """One line of ``--output-format stream-json``; other output is kept in the log only."""
306
+ try:
307
+ msg = json.loads(line)
308
+ except ValueError:
309
+ return
310
+ kind = msg.get("type")
311
+ if kind == "system" and msg.get("session_id"):
312
+ data["agent_session"] = msg["session_id"]
313
+ for c in ((msg.get("message") or {}).get("content") or []) if kind in ("assistant", "user") else []:
314
+ if not isinstance(c, dict):
315
+ continue
316
+ if c.get("type") == "tool_use":
317
+ name = str(c.get("name") or "").split("__")[-1]
318
+ data["_last_tool"] = name
319
+ if c.get("id"):
320
+ data.setdefault("_tools", {})[c["id"]] = name
321
+ action = (c.get("input") or {}).get("action")
322
+ text = _TOOL_TEXT.get(name, f"正在调用 {name}")
323
+ if name == "litloop_deep_search" and action:
324
+ text = {"start": "深度检索:正在构建候选池", "rate": "深度检索:正在保存本批评分",
325
+ "next": "深度检索:正在生成下一批", "status": "深度检索:正在查看进度"}.get(action, text)
326
+ data["doing"] = text
327
+ _event(data, text)
328
+ elif c.get("type") == "tool_result":
329
+ body = c.get("content")
330
+ body = body if isinstance(body, str) else " ".join(
331
+ x.get("text", "") for x in body or [] if isinstance(x, dict))
332
+ tool_id = c.get("tool_use_id")
333
+ tool = (data.get("_tools") or {}).get(tool_id) if tool_id else None
334
+ if not tool:
335
+ tool = data.get("_last_tool")
336
+ session = _session_from(tool, body or "")
337
+ if session:
338
+ data["session"] = session
339
+ elif c.get("type") == "text" and kind == "assistant" and c.get("text", "").strip():
340
+ data["doing"] = "Agent 正在评分"
341
+ if kind == "result":
342
+ data["result"] = str(msg.get("result") or "").strip() or None
343
+ if msg.get("is_error"):
344
+ data["error"] = data["result"] or "无法完成检索:Agent 出错"
345
+ if re.search(r"authenticat|log ?in|OAuth", data["error"], re.I):
346
+ cmd = _config.load_config().get("agent_command") or "claude"
347
+ data["error"] = f"无法完成检索:Agent 未登录。在终端运行 {cmd} 登录后重试"
348
+ data["result"] = None
349
+ data["cost_usd"] = msg.get("total_cost_usd")
350
+
351
+
352
+ def _session_from(tool: str | None, body: str) -> str | None:
353
+ """The screening session a LitLoop tool reported: its JSON "session" field.
354
+
355
+ Only litloop_screening and litloop_deep_search name the session the app
356
+ opens; a session-like string in another tool's output (a web page, a
357
+ file the agent read) is not it (code review, 2026-10-18)."""
358
+ if tool not in _SESSION_TOOLS:
359
+ return None
360
+ try:
361
+ obj = json.loads(body)
362
+ except ValueError:
363
+ obj = None
364
+ if isinstance(obj, dict) and isinstance(obj.get("session"), str) and obj["session"]:
365
+ return obj["session"]
366
+ m = _SESSION_RE.search(body) # a result wrapped in text around the JSON
367
+ return m.group(1) if m else None
368
+
369
+
370
+ def _idle_minutes() -> float:
371
+ raw = _config.load_config().get("agent_idle_minutes", 15)
372
+ if isinstance(raw, bool):
373
+ return 15.0
374
+ try:
375
+ val = float(raw)
376
+ except (TypeError, ValueError):
377
+ return 15.0
378
+ if val < 0:
379
+ return 15.0
380
+ return val
381
+
382
+
383
+ def _watch_idle(run: str, proc: subprocess.Popen, data: dict[str, Any], seen: list[float], limit_minutes: float | None = None) -> None:
384
+ """Stop an agent that has printed nothing for agent_idle_minutes (it hung,
385
+ or waits on a prompt nobody sees); the run would otherwise stay "running"."""
386
+ minutes = _idle_minutes() if limit_minutes is None else limit_minutes
387
+ if minutes <= 0:
388
+ return
389
+ limit = minutes * 60
390
+ while proc.poll() is None:
391
+ time.sleep(min(5.0, max(0.2, limit / 4)))
392
+ if time.time() - seen[0] > limit and proc.poll() is None:
393
+ data["error"] = f"检索已停止:Agent 超过 {limit / 60:.0f} 分钟没有输出"
394
+ _kill(proc)
395
+ return
396
+
397
+
398
+ def _kill(proc: subprocess.Popen) -> None:
399
+ if os.name == "nt": # the agent's own tool servers go with it
400
+ subprocess.run(["taskkill", "/T", "/F", "/PID", str(proc.pid)], capture_output=True,
401
+ creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0))
402
+ else:
403
+ proc.terminate()
404
+
405
+
406
+ def _follow(run: str, proc: subprocess.Popen, prompt: str, data: dict[str, Any]) -> None:
407
+ log = _path(run).with_suffix(".log")
408
+ last = 0.0
409
+ seen = [time.time()] # when the agent last printed anything
410
+ idle = _idle_minutes()
411
+ if idle > 0:
412
+ threading.Thread(target=_watch_idle, args=(run, proc, data, seen, idle), daemon=True).start()
413
+ try:
414
+ assert proc.stdin and proc.stdout
415
+ proc.stdin.write(prompt.encode("utf-8"))
416
+ proc.stdin.close()
417
+ with log.open("ab") as fh:
418
+ for raw in proc.stdout:
419
+ seen[0] = time.time()
420
+ fh.write(raw)
421
+ _read(data, raw.decode("utf-8", errors="replace").strip())
422
+ if time.time() - last > 1.0:
423
+ _write(run, data)
424
+ last = time.time()
425
+ code = proc.wait()
426
+ if run in _CANCELLED:
427
+ data["state"] = "cancelled"
428
+ else:
429
+ ok = code == 0 and not data.get("error")
430
+ data["state"] = "done" if ok else "failed"
431
+ if not ok and not data.get("error"):
432
+ data["error"] = f"无法完成检索:Agent 异常退出(退出码 {code})。详情已写入日志"
433
+ except Exception as e:
434
+ data.update(state="failed", error=str(e))
435
+ finally:
436
+ data["doing"] = None
437
+ data.pop("_tools", None)
438
+ data.pop("_last_tool", None)
439
+ data["finished"] = datetime.now().isoformat(timespec="seconds")
440
+ _write(run, data)
441
+ with _LOCK:
442
+ _PROCS.pop(run, None)
443
+ _CANCELLED.discard(run)
444
+
445
+
446
+ def _session_of(result: Any) -> str | None:
447
+ """The screening session a built-in tool reported (deep search or screening save)."""
448
+ if isinstance(result, dict):
449
+ obj: Any = result
450
+ else:
451
+ try:
452
+ obj = json.loads(str(result or ""))
453
+ except ValueError:
454
+ return None
455
+ if isinstance(obj, dict):
456
+ for key in ("session", "id"):
457
+ value = obj.get(key)
458
+ if isinstance(value, str) and value:
459
+ return value
460
+ return None
461
+
462
+
463
+ def _run_builtin(run: str, data: dict[str, Any], prompt: str) -> None:
464
+ """Backend B: this process asks the model and runs the tools itself."""
465
+ stop = threading.Event()
466
+ with _LOCK:
467
+ _STOP[run] = stop
468
+ last = [0.0]
469
+
470
+ def on_event(kind: str, ev: dict[str, Any]) -> None:
471
+ if stop.is_set():
472
+ raise _Cancelled()
473
+ if kind == "tool":
474
+ name = str(ev.get("name") or "")
475
+ data["doing"] = _BUILTIN_TOOLS.get(name, f"正在调用 {name}")
476
+ _event(data, data["doing"])
477
+ elif kind == "result":
478
+ session = _session_of(ev.get("result"))
479
+ if session:
480
+ data["session"] = session
481
+ elif kind == "error":
482
+ _event(data, f"{ev.get('name')} 出错:{str(ev.get('detail') or '')[:200]}")
483
+ elif kind == "text":
484
+ data["doing"] = "正在整理结论"
485
+ if time.time() - last[0] > 1.0: # the app polls this file
486
+ _write(run, data)
487
+ last[0] = time.time()
488
+
489
+ try:
490
+ from ..agents import FUNCTIONS, TOOLS, run_task
491
+ from ..agents.system import system_prompt
492
+
493
+ form = data.get("form") or {}
494
+ deep = form.get("mode") == "deep"
495
+ batches = int(form.get("batches") or 0) or 5
496
+ # One batch costs a rate + a next call; building the pool and the final
497
+ # answer need a few more (2026-11-06: the old flat 8 stopped deep runs).
498
+ steps = min(4 + 2 * batches, 24) if deep else 8
499
+ out = run_task(prompt, TOOLS, functions=FUNCTIONS, system=system_prompt(),
500
+ max_steps=steps, on_event=on_event)
501
+ data["result"] = str(out.get("text") or "").strip() or None
502
+ data["state"] = "cancelled" if stop.is_set() else "done"
503
+ except _Cancelled:
504
+ data["state"] = "cancelled"
505
+ except Exception as e:
506
+ data.update(state="failed", error=f"无法完成检索:{type(e).__name__}: {e}")
507
+ finally:
508
+ data["doing"] = None
509
+ data["finished"] = datetime.now().isoformat(timespec="seconds")
510
+ # Mark it finished before the last write: whoever reads the finished
511
+ # state may start the next run at once, while this thread is still
512
+ # alive for a moment and must not count as running.
513
+ with _LOCK:
514
+ _DONE.add(run)
515
+ _write(run, data)
516
+ with _LOCK:
517
+ _BUILTIN.pop(run, None)
518
+ _STOP.pop(run, None)
519
+ _CANCELLED.discard(run)
520
+ _DONE.discard(run)
521
+
522
+
523
+ def cancel(run: str) -> bool:
524
+ with _LOCK:
525
+ proc = _PROCS.get(run)
526
+ thread = _BUILTIN.get(run)
527
+ stop = _STOP.get(run)
528
+ if thread is not None and thread.is_alive():
529
+ _CANCELLED.add(run)
530
+ if stop is not None:
531
+ stop.set() # the loop checks it before the next step
532
+ return True
533
+ if not proc or proc.poll() is not None:
534
+ return False
535
+ _CANCELLED.add(run)
536
+ _kill(proc)
537
+ return True