manastone-diag 2.2.1

Offline fault diagnosis assistant for the AgiBot X2 Ultra humanoid robot

manastone-diag

Offline fault diagnosis assistant for the AgiBot X2 Ultra humanoid robot — drop in a log package, describe the symptom, and get a three-round reviewed diagnosis report. Every verified case feeds an experience library that makes the next diagnosis better.

Docs: Quickstart · Spec · 中文文档 · Changelog · Sources

---

What it does

A humanoid robot falls over in the field. Someone hands you a 1 GB tar of logs. manastone-diag turns that into a diagnosis:

1. Ingest — log_ingestor streams .log / .yaml / .json / .mcap / .atop files into a compact structured event stream (privacy-stripped,

   1 GB safe).

2. Match — fault_library matches symptoms and log keywords against 11 fault rules (Chinese + English), and runs temporal causal inference over the event timeline (6 causal rules).
3. Review — an LLM agent walks you through a three-round review (data collection → analysis → report), pausing for your confirmation at each round.
4. Learn — every diagnosis is archived; field verification feedback updates the experience library (sharded storage, WAL-protected; measured: 15 ms in-process search over 5,000 entries).

The heavy lifting is deterministic Python — the LLM orchestrates and explains. Everything runs locally; no network access is required for diagnosis.

Quick start

Install from PyPI (tools only — no bundled examples or agent assets):

pip install manastone-diag
manastone-diag-verify   # optional: run bundled verification

For the full repository (sample incidents, examples/, and .pi/ agent setup):

git clone https://github.com/zengury/manastone-diag.git
cd manastone-diag
pip install -r requirements.txt

# Sanity check (should end with all green)
python3 tools/verify_all.py

# Try the bundled sample incident (a stand-mode fall)
python3 tools/log_ingestor.py examples/sample-incident --robot agibot_x2 --output /tmp/diag-out

Five-minute walkthrough with the sample incident: docs/QUICKSTART.md.

Running with an LLM agent

The project is agent-framework-agnostic: the assets are the knowledge base (knowledge/), the tool chain (tools/), and the diagnosis playbook (AGENTS.md). Any coding-agent framework that reads project instructions and can run shell commands works:

• pi — ./install.sh installs pi and a manastone-diag launcher; .pi/ ships skill files and the system prompt.
• Others (Hermes, Claude Code, …) — point the agent at the repo root; AGENTS.md contains the full three-round diagnosis procedure.

Data sources

Source	Formats	Notes
Text logs	.log (incl. sliced .log_N), .txt	fall detection, mode switches, fault codes
ROS2 bags	.mcap	sensor/joint time series; joint asymmetry analysis
Config / state dumps	.yaml, .json	status snapshots, hardware config
System monitor	.atop	CPU/memory (requires atop, via WSL on Windows)

Knowledge base

knowledge/ ships 8 YAML files: 11 fault rules with repair guidance, 12 keyword-match entries (Chinese + English), 10 log event patterns, 6 temporal causal rules, plus hardware/interface ontologies and a capability-boundary list documenting known platform blind spots.

All numbers above are enforced by CI against the actual YAML contents.

Multi-user / shared experience

Set MANASTONE_DATA_DIR to a shared folder to pool the experience library across a team, or import a colleague's data folder with python3 tools/experience_manager.py import <path> (GUI: tools/import_tool.py).

Scope and boundaries

• Offline by design. Diagnosis consumes exported log packages only. The tool does not connect to robots, and it contains no code from the (private) Manastone runtime kernel. The only sanctioned online interface is the runtime's public ledger read API — unused in this version. See SOURCES.md.
• Robot-specific knowledge currently targets the AgiBot X2 Ultra. The schema and pipeline are robot-agnostic; see docs/SPEC.md to add another robot.

License

Licensed under the Apache License, Version 2.0 (Apache-2.0).

Copyright 2026 zengury. Modifications in v2.x (MCAP joint parsing, experience shards, archive dashboard) by thomastang237.