save_research

Save structured research results as a knowledge card in the local knowledge base.

The answer_json must conform to schemas/answer.schema.json: { "answer": "detailed answer text", "supporting_claims": [{"claim": "...", "evidence_ids": ["..."], "confidence": "high|medium|low"}], "inferences": ["..."], "uncertainty": ["..."], "missing_evidence": ["..."], "suggested_next_steps": ["..."], "sources": ["https://example.com/source1", "https://example.com/source2"], "visual_aids": [{"type": "mermaid|image_url|image_path", "content": "...", "caption": "...", "alt_text": "..."}] }

IMPORTANT quality requirements:

• The "answer" field MUST be at least 200 characters of substantive content.

• You MUST include at least 1 supporting_claim with evidence_ids and confidence.

• Each claim text MUST be at least 20 characters — vague one-word claims are rejected.

• DO NOT create cards with empty supporting_claims — every card needs evidence-backed claims.

• Aim for 3+ supporting claims, inferences, uncertainty, and suggested_next_steps for high-quality cards.

• DO NOT use this tool for trivial facts or one-sentence answers — those are not worth persisting.

• ALWAYS include a "sources" array with the URLs you referenced during research. These are written to the card's frontmatter source_refs for provenance tracking.

• evidence_ids in supporting_claims SHOULD cite the source URL (from "sources") — the card renders them as clickable [host](url) source links. Opaque ids like "s1" stay as bare text and lose the link.

• For first-hand depth: call fetch_url on key sources BEFORE writing the answer, so it cites concrete numbers/mechanisms from the actual page (not memory). fetch_url also archives a local snapshot (knowledge/_snapshots/) so dead links stay traceable. save_research best-effort snapshots any listed sources in the background even without an explicit fetch_url.

• When language="zh" (default), the entire answer field MUST be written in Chinese (中文). When language="en", write in English.

When to include visual_aids (auto-judge by topic):

• Processes / workflows / data flow → mermaid flowchart or sequence diagram

• Architecture / system design → mermaid graph or class diagram

• Comparisons or hierarchies → mermaid diagram or table

• Spatial / geometric concepts → image_url or mermaid

• Pure definitions or simple facts → omit visual_aids

When sources contain useful images (charts, diagrams, figures):

• If a source page has a relevant diagram/chart with clear explanatory value, include it as visual_aids with type "image_url" and the image's absolute URL

• Judge relevance: prefer diagrams explaining mechanisms, architecture overviews, comparison charts, result plots — skip decorative screenshots or generic stock photos

• Always provide a descriptive caption explaining what the image shows

For method/procedural content (how-to, implementation, deployment, etc.), also include:

• expected_output: Description of what a successful result looks like — output format, shape, key metrics, or acceptance criteria. Synthesize from the answer if sources don't explicitly provide this.

• example: A minimal worked example (sample input → processing steps → expected output). Construct synthetically based on the answer if sources lack one. Write '[insufficient data — needs supplementation]' only if impossible to construct.

Visual aids placement (optional after_section field):

• "answer" — insert after the main answer paragraph (default for architecture/pipeline diagrams)

• "supporting_claims" — insert after claims (default for evidence figures/charts)

• "inferences", "uncertainty", "missing_evidence", "suggested_next_steps" — after respective sections

• Omit after_section to place at the end of the card (backward compatible)