研究代理程序的 CLI
Your agent's next step up. Every session picks up where you left off. Every turn goes higher.
One-line pitch. ascent-research is an incremental research workflow CLI for AI agents: point it at a topic / source tree / Obsidian vault, and it will keep researching across sessions — fetching, citing, diagramming, and accreting a durable wiki you can come back to tomorrow and pick up exactly where you stopped.
ascent-research new "tokio internals 2026" --slug tokio --preset tech
ascent-research add-local ~/tokio/tokio/src/runtime --glob '**/*.rs'
ascent-research loop tokio --provider claude --iterations 12
ascent-research finish tokio --open # coverage -> HTML -> audit
# (next day)
ascent-research resume tokio && ascent-research loop tokio --iterations 8
Bookmark-ready: every session lives as plain files under
~/.actionbook/ascent-research//, so Obsidian, VS Code, grep
and git all work.
A Claude Code or Codex conversation ends. The agent forgets everything. Next week you ask the same question — same search, same fetches, same half-formed understanding.
I built ascent-research because I want my AI agents to get smarter
over time, not reset every session. The on-disk session (session.md,
session.jsonl, wiki/, SCHEMA.md) is the agent's external long-term
memory — survives process death, carries across tool switches, inspectable
and editable by the human. Every loop run isn't "research this topic
from scratch"; it's "continue the research we were doing, check what's
unused from last time, append to the pages you've already written."
The agent-facing surface (actions like write_wiki_page,
append_wiki_page, digest_source) exists specifically so the agent can
accrete rather than overwrite. The infra-enforced rules
(smell test, preserve_diagram_refs, figure-rich contract) exist so this
long-term memory stays clean without human QA every turn.
Whether you use it standalone or as a skill inside a coding-agent instance, the pitch is the same: stop throwing away your agent's research work at the end of every conversation. Keep it on disk. Let the next turn stand on the last one's shoulders.
ascent-research is a CLI that calls an LLM provider (Claude via
cc-sdk, Codex via codex app-server, or fake for tests). Which
process hosts the agent decides the usage shape:
Run the CLI directly; it spawns the provider itself and drives the research loop end-to-end, no outer agent needed. Good for batch / CI / "I just want a report."
ascent-research new "tokio internals" --slug tokio
ascent-research add-local ~/tokio/tokio/src
ascent-research loop tokio --provider claude --iterations 12
ascent-research finish tokio --open
Drop the bundled skill into your Claude Code / Codex config and the outer agent invokes the CLI per-turn as a tool. Good for interactive sessions where you want to mix research with coding / writing work in the same conversation, or want the outer agent to plan the workflow (decide what to ingest, when to query, when to synthesize).
ln -s "$PWD/skills/ascent-research" ~/.claude/skills/ascent-research
# Then in a Claude Code session: /skill:ascent-research
# Or just describe the task — "research tokio's scheduler via source" —
# the skill triggers automatically.
Both modes share the same on-disk session format, so you can start a session in standalone mode and later resume it from inside a Claude Code / Codex instance, or vice versa.
--features provider-opencode-go, set
OPENCODE_API_KEY + ASR_OPENCODE_MODEL, then
ascent-research loop --provider opencode-go.ASR_OPENCODE_PROTOCOL, ASR_OPENCODE_TEMPERATURE,
ASR_OPENCODE_MAX_TOKENS, ASR_OPENCODE_TIMEOUT_MS).ASR_BILINGUAL_PROVIDER=opencode-go for
synthesize --bilingual Chinese translation.--provider still defaults to fake;
opt in to opencode-go explicitly.See CHANGELOG.md for the full design rationale incl. what was
deliberately not adopted from the PR.
XTweet runcode flavor that
waits for article[data-testid="tweet"] (not networkidle), scrolls
with snapshot-collect across virtualized DOM so the main tweet
isn't unmounted out of the result, and reads up to 25 thread articles
with image / video poster URLs inlined as markdown ``.x-tweet-status, x-profile,
x-search-live — explicit kinds for route debugging.md_parser::extract_http_links: markdown image syntax
`` is now correctly excluded from the cited-sources scan,
so embedding pictures of cited tweets no longer trips
sources_hallucinated.Live impact (same URLs, before vs after):
| URL | 0.4.0 | 0.4.1 |
|---|---|---|
x.com//status/ (any) |
162 B chrome | 2-3 KB main tweet + thread + media |
See CHANGELOG.md for full notes and specs/x-com-tweet-runcode-flavor.spec.md
for the design (33 BDD scenarios, lint 100%).
edge.actionbook.dev/mcp + Chrome extension
over WSS). Set ACTIONBOOK_BACKEND=v1-cli to keep the old local-CLI
path — it's a permanent fallback, not slated for removal.add / batch first probes the V2
catalog and seeds matching actions into the session wiki, so the
agent knows what's known about a site before navigating.composite-v1; short-circuits on first part failure with a labelled
composite_failed_part event.actionbook_search,
actionbook_manual, actionbook_run_code.add / batch: --frame-id, --run-code-args,
--reseed, --actionbook-backend.www. ↔ apex equivalence; CJK / UTF-8 docs now pass the
add-local text detector; user --timeout > 60s is no longer
silently truncated by the V2 server's hard cap.See CHANGELOG.md for the full list and docs/rfc/v2-session-export-to-postagent.md
for the cross-tool RFC that didn't ship in this release.
Five properties — each validated end-to-end across four live research sessions (tokio internals, an Obsidian agent-SE series, a mixed online-plus-local AI coding agents comparison, and self-research on this repo):
Inherits the core loop architecture from
karpathy/autoresearch
and pi-autoresearch:
a fresh agent can resume any session from two files —
session.md (human-readable living doc) + session.jsonl
(append-only event log) — even after process death, context reset,
or a week of inactivity. Where the original autoresearch optimizes a
single scalar (training loss, bundle size, test speed) via
edit → benchmark → keep-or-revert, ascent-research generalizes
the same loop grammar to research:
plan → fetch → digest → write_section / write_wiki_page / write_diagram
producing a figure-rich report plus a durable cross-session wiki
instead of a single optimized number.
ascent-research resume picks up exactly where a prior turn
stopped. Wiki pages accrue via append_wiki_page — new findings
grow existing entity pages instead of overwriting them. Coverage
signals (sources_unused, diagrams_referenced, wiki_pages,
wiki_total_bytes) let each loop run know what's still open from
the previous turn, so it continues rather than restarts. One-shot
DR tools can't do this — when they finish, they're done.
add (HTTP via postagent) + add-local (file trees) + browser
fallback (via actionbook browser for JS-heavy pages) all flow
through the same smell-test → event-log → wiki → report path. A
single session can cite GitHub READMEs, arXiv papers, blog posts,
and your private Obsidian notes side-by-side in one wiki page's
sources list — the renderer doesn't care about URL scheme.
Narrative-only output is considered incomplete. The loop's system
prompt carries a non-negotiable FIGURE-RICH CONTRACT: target ≥ 1
hand-drawn SVG per numbered section, bidirectional rule that every
`` markdown reference must have a matching
write_diagram action and vice versa, infra-level guarantee that
section overwrites never drop figures. Every SVG is inline
(no external assets, no screenshots) and the HTML report has a
clickable wiki TOC + EN/ZH bilingual toggle.
Agents can't "just summarize this for me." Every fetch runs through
a smell test at the CLI layer before the LLM sees it; rejections
become typed events. Overwrites preserve figures. Wiki writes are
append-safe. Coverage computes sources_hallucinated (URLs cited
but never fetched) as a report_ready blocker. Every error returns
a machine-readable code (NO_ACTIVE_SESSION, SMELL_REJECTED,
DIAGRAM_OUT_OF_BOUNDS, WIKI_EMPTY, …) so agents route recovery
deterministically without parsing prose.
git clone https://github.com/actionbook/ascent-research
cd ascent-research
# Full build (loop + Claude provider) — what live sessions need
cargo build -p ascent-research --release --features "autoresearch provider-claude provider-codex"
export PATH="$PWD/target/release:$PATH"
ascent-research --help
Alternative feature sets:
# Minimal — no autonomous loop, no LLM
cargo build -p ascent-research --release
# Loop with fake provider only (for scripted tests)
cargo build -p ascent-research --release --features autoresearch
# Loop with Codex instead of Claude
cargo build -p ascent-research --release --features "autoresearch provider-codex"
Prereqs for online ingest: Rust stable (edition 2024),
postagent for HTTP API fetches,
and (for JS-heavy pages) the Actionbook Chrome extension — see below.
Neither is required if you only use add-local.
ascent-research picks between two actionbook backends based on
ACTIONBOOK_BACKEND (default v2-mcp):
| Env value | Path | What's needed |
|---|---|---|
v2-mcp (default) |
Cloud MCP at edge.actionbook.dev/mcp + Actionbook Chrome extension over WSS |
ACTIONBOOK_API_KEY (an ak_* token), Chrome extension installed & signed in |
v1-cli |
Local actionbook CLI subprocess (offline-capable fallback, permanently supported) |
The actionbook binary on PATH, and your Chrome profile reachable by it |
V2 setup:
暂无开放 Issues，或尚未同步最近议题。