Skip to content

AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He

feat(topic-research): import retained pages as text evidence

hugohe319c35a857584
diff --git a/skills/ppt-master/scripts/image_search.py b/skills/ppt-master/scripts/image_search.py
index f8d30d51..5c633800 100644
--- a/skills/ppt-master/scripts/image_search.py
+++ b/skills/ppt-master/scripts/image_search.py
@@ -1523,7 +1523,7 @@ def fetch_url_replace(
min_width: int = 1200,
min_height: int = 800,
) -> int:
- """Download a user-supplied image URL into the target and record it.
+ """Download a directly selected image URL into the target and record it.
The model-agnostic manual path: when an automated best match is not
suitable (or the running model cannot see images at all), a human finds a
@@ -1602,7 +1602,7 @@ def fetch_url_replace(
"author": "",
"source_page_url": url,
"download_url": url,
- "license_name": "unverified — user-supplied URL",
+ "license_name": "unverified — direct URL",
"license_url": "",
"license_tier": "manual",
"attribution_required": False,
@@ -1611,7 +1611,7 @@ def fetch_url_replace(
"attribution_text": "",
"status": "manual",
"note": (
- "Manually supplied image URL; verifying usage rights is the user's "
+ "Direct image URL; verifying usage rights is the user's "
"responsibility."
),
}
@@ -2339,7 +2339,7 @@ def build_parser() -> argparse.ArgumentParser:
default=None,
metavar="URL",
help=(
- "Manual replacement: download a user-supplied image URL into "
+ "Manual replacement: download a directly selected image URL into "
"--filename and record it (license marked 'manual'). Works without "
"a multimodal model. Example: --from-url https://… --filename team.jpg -o images/"
),
diff --git a/skills/ppt-master/scripts/project_management/cli.py b/skills/ppt-master/scripts/project_management/cli.py
index dc2b0f7b..19b3a4ba 100644
--- a/skills/ppt-master/scripts/project_management/cli.py
+++ b/skills/ppt-master/scripts/project_management/cli.py
@@ -218,6 +218,33 @@ def _has_usable_import(summary: dict[str, list[str]]) -> bool:
)
+def _research_source_urls(path: Path) -> list[str]:
+ """Return unique source URLs from a v1 topic-research provenance file."""
+ if not path.is_file() or not path.name.endswith(".facts.json"):
+ return []
+ try:
+ payload = json.loads(path.read_text(encoding="utf-8"))
+ except (OSError, json.JSONDecodeError) as exc:
+ raise RuntimeError(f"Fact provenance is unreadable: {path} ({exc})") from exc
+ if not isinstance(payload, dict):
+ raise RuntimeError(f"Fact provenance must be a JSON object: {path}")
+ if payload.get("schema") != "ppt-master.fact-provenance.v1":
+ return []
+ facts = payload.get("facts")
+ if not isinstance(facts, list):
+ raise RuntimeError(f"Fact provenance facts must be an array: {path}")
+ urls: list[str] = []
+ for index, fact in enumerate(facts):
+ if not isinstance(fact, dict) or not is_url(str(fact.get("source_url", ""))):
+ raise RuntimeError(
+ f"Fact provenance facts[{index}] has no valid source_url: {path}"
+ )
+ url = fact["source_url"]
+ if url not in urls:
+ urls.append(url)
+ return urls
+
+
class ProjectManager:
"""Create, inspect, validate, and populate project folders."""
@@ -448,11 +475,18 @@ class ProjectManager:
)
self._run_tool(route.command)
- def _import_url(self, url: str, markdown_path: Path) -> None:
+ def _import_url(
+ self,
+ url: str,
+ markdown_path: Path,
+ *,
+ download_images: bool = True,
+ ) -> None:
route = build_conversion_command(
url,
markdown_path,
forced_type="web",
+ extra_args=[] if download_images else ["--no-images"],
)
self._run_tool(route.command)
@@ -760,6 +794,9 @@ class ProjectManager:
"assets": [],
"images": [],
"analysis": [],
+ "research_sources_expected": [],
+ "research_sources_imported": [],
+ "research_sources_failed": [],
"notes": [],
"skipped": [],
}
@@ -786,6 +823,20 @@ class ProjectManager:
continue
expanded_items.append(item)
+ research_urls: list[str] = []
+ for item in expanded_items:
+ if is_url(item):
+ continue
+ for url in _research_source_urls(Path(item).expanduser()):
+ if url not in research_urls:
+ research_urls.append(url)
+ summary["research_sources_expected"] = research_urls.copy()
+ explicit_urls = {item for item in expanded_items if is_url(item)}
+ expanded_items.extend(url for url in research_urls if url not in explicit_urls)
+ research_url_set = set(research_urls)
+ text_only_research_urls = research_url_set - explicit_urls
+ imported_research_urls: set[str] = set()
+
explicit_markdown_stems = {
Path(item).stem
for item in expanded_items
@@ -801,7 +852,11 @@ class ProjectManager:
sources_dir / f"{derive_url_basename(item)}.md"
)
try:
- self._import_url(item, markdown_path)
+ self._import_url(
+ item,
+ markdown_path,
+ download_images=item not in text_only_research_urls,
+ )
except Exception as exc: # pragma: no cover - summary path
archived = self._archive_url_record(sources_dir, item)
summary["url_records"].append(str(archived))
@@ -816,7 +871,10 @@ class ProjectManager:
continue
summary["markdown"].append(str(markdown_path))
- self._propagate_companion_image_assets(markdown_path, project_dir)
+ if item in research_url_set:
+ imported_research_urls.add(item)
+ if item not in text_only_research_urls:
+ self._propagate_companion_image_assets(markdown_path, project_dir)
continue
source_path = Path(item)
@@ -996,6 +1054,13 @@ class ProjectManager:
else:
summary["notes"].append(f"{item}: archived only, no automatic conversion")
+ summary["research_sources_imported"] = [
+ url for url in research_urls if url in imported_research_urls
+ ]
+ summary["research_sources_failed"] = [
+ url for url in research_urls if url not in imported_research_urls
+ ]
+
# Cleanup: only a projects-local source directory may be removed after
# its files move into the target project. Every other location is copied
# and remains untouched, even when the caller passes --move.
@@ -1195,8 +1260,15 @@ def main(argv: list[str] | None = None) -> int:
copy=args.copy,
)
has_usable_import = _has_usable_import(summary)
- if has_usable_import:
+ import_complete = has_usable_import and not summary["research_sources_failed"]
+ if import_complete:
print(f"[OK] Imported sources into: {args.project_path}")
+ elif has_usable_import:
+ print(
+ f"[ERROR] Topic-research source import is incomplete: "
+ f"{args.project_path}",
+ file=sys.stderr,
+ )
else:
print(
f"[ERROR] No usable sources imported into: {args.project_path}",
@@ -1226,6 +1298,11 @@ def main(argv: list[str] | None = None) -> int:
print("\nAnalysis artifacts:")
for item in summary["analysis"]:
print(f" - {item}")
+ if summary["research_sources_expected"]:
+ print("\nTopic-research source reconciliation:")
+ print(f" expected: {len(summary['research_sources_expected'])}")
+ print(f" imported: {len(summary['research_sources_imported'])}")
+ print(f" failed: {len(summary['research_sources_failed'])}")
if summary["notes"]:
print("\nNotes:")
for item in summary["notes"]:
@@ -1234,7 +1311,7 @@ def main(argv: list[str] | None = None) -> int:
print("\nSkipped:")
for item in summary["skipped"]:
print(f" - {item}")
- return 0 if has_usable_import else 1
+ return 0 if import_complete else 1
if args.command == "scaffold-spec":
artifact_path = manager.scaffold_artifact(args.project_path, "design_spec")
diff --git a/skills/ppt-master/scripts/source_to_md/web_to_md.py b/skills/ppt-master/scripts/source_to_md/web_to_md.py
index b000933c..b74fe511 100644
--- a/skills/ppt-master/scripts/source_to_md/web_to_md.py
+++ b/skills/ppt-master/scripts/source_to_md/web_to_md.py
@@ -303,6 +303,39 @@ def build_image_filename(abs_url: str, seq: int, content_type: str | None = None
return f"{stem}{ext}"
+def resolve_content_image_url(img: Tag, page_url: str) -> str | None:
+ """Resolve one content image, preferring real lazy-load URLs."""
+ candidates = [
+ img.get("data-src"),
+ img.get("data-original"),
+ img.get("data-lazy-src"),
+ img.get("data-actualsrc"),
+ img.get("src"),
+ ]
+ for value in candidates:
+ if not isinstance(value, str):
+ continue
+ src = value.strip()
+ if not src or src.startswith(("data:", "javascript:", "blob:", "#")):
+ continue
+ resolved = urljoin(page_url, src)
+ parsed = urlparse(resolved)
+ if parsed.scheme in {"http", "https"} and parsed.netloc:
+ img["src"] = resolved
+ return resolved
+ return None
+
+
+def rewrite_images_to_remote_urls(content_element: Tag | None, page_url: str) -> int:
+ """Retain remote image links without downloading image bytes."""
+ if content_element is None:
+ return 0
+ return sum(
+ resolve_content_image_url(img, page_url) is not None
+ for img in content_element.find_all("img")
+ )
+
+
def download_and_rewrite_images(
content_element: Tag | None,
page_url: str,
@@ -322,27 +355,9 @@ def download_and_rewrite_images(
saved = 0
for idx, img in enumerate(images):
- # Prefer lazy-load attributes — WeChat, Zhihu, and many CMSes keep the
- # real image URL in data-src / data-original / data-lazy-src, with
- # `src` pointing at a 1x1 placeholder or a template literal.
- candidates = [
- img.get("data-src"),
- img.get("data-original"),
- img.get("data-lazy-src"),
- img.get("data-actualsrc"),
- img.get("src"),
- ]
- src = next((s for s in candidates
- if s and not s.startswith("data:")
- and s.startswith(("http://", "https://", "//", "/"))), None)
- if not src:
+ abs_url = resolve_content_image_url(img, page_url)
+ if abs_url is None:
continue
-
- # Promote the chosen URL into the element's src so downstream rewrite
- # (which matches on src) can retarget it to the local file.
- img["src"] = src
-
- abs_url = urljoin(page_url, src)
content_type = ""
converted_from = ""
if abs_url in downloaded:
@@ -808,7 +823,12 @@ def simple_html_to_markdown_traversal(soup: Tag | BeautifulSoup | None) -> str:
return md or ""
-def process_url(url: str, output_file: str | None = None) -> tuple[bool, str, str | None, str | None]:
+def process_url(
+ url: str,
+ output_file: str | None = None,
+ *,
+ download_images: bool = True,
+) -> tuple[bool, str, str | None, str | None]:
"""Fetch, convert, and save one web page as Markdown.
Returns (success, url, error, output_path). output_path is the actual saved
@@ -844,8 +864,12 @@ def process_url(url: str, output_file: str | None = None) -> tuple[bool, str, st
content_div = find_main_content(soup)
# Download images and rewrite src before markdown conversion
- image_count = download_and_rewrite_images(
- content_div, url, image_dir, rel_image_prefix)
+ image_count = 0
+ if download_images:
+ image_count = download_and_rewrite_images(
+ content_div, url, image_dir, rel_image_prefix)
+ else:
+ rewrite_images_to_remote_urls(content_div, url)
if image_count:
print(f" [OK] Images: {image_count} saved to {image_dir}")
@@ -883,7 +907,7 @@ def process_url(url: str, output_file: str | None = None) -> tuple[bool, str, st
markdown_path=output_path,
converter="web_to_md.py",
conversion_type="web",
- asset_dir=image_dir,
+ asset_dir=image_dir if image_count else None,
)
print(f" [OK] Saved: {output_path}")
@@ -925,6 +949,11 @@ def main(argv: list[str] | None = None) -> int:
"--emit-result",
help="On success, write the saved output path as JSON to this file "
"(single-URL dispatcher use, so a title-named file can be located)")
+ parser.add_argument(
+ "--no-images",
+ action="store_true",
+ help="Keep remote image links without downloading image files",
+ )
args = parser.parse_args(argv)
@@ -957,7 +986,11 @@ def main(argv: list[str] | None = None) -> int:
for i, url in enumerate(targets):
# Allow specific output file only if 1 URL
out = args.output if (len(targets) == 1 and args.output) else None
- success, url, err, out_path = process_url(url, out)
+ success, url, err, out_path = process_url(
+ url,
+ out,
+ download_images=not args.no_images,
+ )
results.append((success, url, err))
if args.emit_result and success and out_path:
_write_emit_result(args.emit_result, url, out_path)