diff --git a/README.md b/README.md index 1209488..2ba66f2 100644 --- a/README.md +++ b/README.md @@ -1,299 +1,179 @@ # Moss -**Moss is an open, robotics-aware terminal agent and embeddable agent runtime developed by 地瓜机器人 (D-Robotics).** Run `moss` and start working immediately on the built-in D-Robotics model gateway — no model API key and no forced login. When you want your own model, billing, data boundary, or private gateway, point Moss at any OpenAI-compatible endpoint or Anthropic without changing the agent. +**English** · [简体中文](README.zh-CN.md) -`moss` is the primary command. `dmoss` remains a compatible alias for existing users and scripts. +**A robotics-aware terminal agent that runs out of the box — and an embeddable agent runtime you can build on.** Made by 地瓜机器人 (D-Robotics). -

- Moss terminal startup demo -

+Run `moss`, ask a question, get to work. No API key, no forced login — the first launch already talks to the built-in D-Robotics gateway. When you want your own model, billing, or private endpoint, point Moss at any OpenAI-compatible or Anthropic provider without changing the agent. `/connect` an RDK board and the whole session moves onto the device over SSH. + +> `moss` is the primary command; `dmoss` stays as a compatible alias.

- Moss board connection and image attachment demo + Moss terminal startup demo

## Quick Start ```bash -npm i -g @rdk-moss/agent@latest +npm i -g @rdk-moss/agent@latest # Node 22.16+ moss ``` -The npm package is `@rdk-moss/agent`; the command is `moss`. Node 22.16 or newer is required. The first launch works out of the box on the built-in gateway — ask it something and it answers. `moss auth login` is optional and only links a D-Robotics developer community account. - -You can also run Moss without entering the interactive UI: +The first launch works immediately on the built-in gateway — ask it something and it answers. No key, no login required. ```bash moss "check disk usage on this project" # one-shot: answer and exit echo "list the failing tests" | moss # piped stdin -moss -m qwen-plus "summarize @README.md" # override the model for one run; @path attaches a file +moss -m qwen-plus "summarize @README.md" # override the model; @path attaches a file ``` -Update anytime with `npm i -g @rdk-moss/agent@latest`, or `/upgrade` from inside Moss. +Update with `npm i -g @rdk-moss/agent@latest`, or `/upgrade` from inside Moss. ## Why Moss -Moss gives you the familiar terminal-agent loop from Claude Code and Codex with a different ownership model: +The familiar Claude Code / Codex terminal loop, with a different ownership model: -- **Use it immediately** — the built-in D-Robotics gateway works with no model key and no forced community login. -- **Bring your own model** — DeepSeek, Qwen, any OpenAI-compatible gateway, Anthropic, or a self-hosted endpoint. Switching providers never changes the agent. -- **Work with robots and edge devices** — `/connect ` puts the whole session on an RDK board over SSH, with diagnostics and ROS2 tools, then `/disconnect` restores local tools. -- **Survive long, interruptible work** — sessions are saved as you go, a working-context checkpoint tracks the active task, and `moss resume`/`--continue` pick the task back up instead of restarting it. -- **Stay honest about evidence** — Moss is prompted to separate verified facts, inferences, and assumptions, to report when CodeGraph or device access is unavailable, and to never claim a result it did not verify. -- **Embed it in your own product** — Moss is a runtime with public contracts and npm packages, not only a closed standalone app. +- **Zero-setup start** — built-in D-Robotics gateway, no model key, no forced login. +- **Bring your own model** — DeepSeek, Qwen, OpenAI-compatible, Anthropic, or self-hosted. Switching providers never changes the agent. +- **Robot- and board-native** — `/connect ` runs the session on an RDK board over SSH with diagnostics and ROS2 tools; teach it the whole RDK stack with [device-knowledge](#give-moss-rdk-board-skills) skills. +- **Survives long, interruptible work** — sessions auto-save, a working-context checkpoint tracks the active task, and `moss resume` picks it back up instead of restarting. +- **Honest by design** — separates verified facts from inference, reports when a capability is unavailable, and never claims a result it did not check. +- **Embeddable** — a runtime with public contracts and npm packages, not only a standalone app. -If that direction is useful, star the repo to follow the open runtime, fork it to build your own host, and open issues for model providers, board workflows, or host-adapter gaps you want Moss to support. +## Everyday Use -## Moss Vs Claude Code And Codex +Start Moss in a project, then drive it in plain language. Type `/help` for the full command list; the ones you will use most: -| Capability | Moss | Claude Code | Codex | -| --- | --- | --- | --- | -| Interactive terminal agent | `moss` (`dmoss` alias) | yes | yes | -| Default first run | Built-in D-Robotics gateway, no model key or forced login | Anthropic account | OpenAI account | -| Bring your own model | OpenAI-compatible, Anthropic, private gateways, self-hosted models | Anthropic path | OpenAI path | -| Robotics / board workflows | First-class RDK board connect, SSH, diagnostics, ROS2 tools | general developer agent | general developer agent | -| Embedding model | Public Host Adapter contract and npm packages | standalone product | standalone product | -| Product control | Host owns UI, tools, storage, approvals, credentials, telemetry | vendor-owned app | vendor-owned app | +| Command | Purpose | +| --- | --- | +| `/status` · `/model` | Show model/login/workspace/board state · switch the active model | +| `/connect ` · `/disconnect` | Enter / leave board mode for an RDK device | +| `/resume [key\|--last]` · `/sessions` | Switch into a saved conversation · list them | +| `/goal ` | Run until a goal condition is met (goal runner) | +| `/attach ` · `/diff` · `/review` | Attach an image/file · show changes · review them for bugs | +| `/skills` · `/memory` · `/mcp` · `/doctor` | Inspect skills · memory · MCP servers · health-check the run | +| `/compact` · `/clear` · `/yolo` | Compress history · new conversation · full-power session (`/yolo off` reverts) | -Claude Code and Codex are excellent polished standalone assistants. Moss is for people who want that style of agent while also owning the runtime, model route, device tools, and product integration surface. +Press **Shift+Tab** to cycle interaction modes: `plan` (read-only), `default` (per-call approval), `accept-edits` (auto-approve workspace writes). Attach context inline with an `@path` reference (`summarize @README.md`) or `/attach ./screenshot.png`; images go to vision-capable models, text files become prompt context. -## A Five-Minute Tour +## Connect An RDK Board -1. Open a project and start Moss: +`/connect` inside a live session — no restart needed: - ```bash - cd my-project - moss - ``` +

+ Moss board connection and image attachment demo +

-2. Ask for a read-only orientation, then check the runtime state: +```text +/connect 192.168.1.10 --user root +/connect ubuntu@192.168.1.10 --port 2222 --key ~/.ssh/id_rsa +Check camera, ROS2 nodes, disk space, and device health. +``` - ```text - Inspect this repo and tell me the build, test, and release path. - /status - /model - ``` +`/connect` verifies SSH reachability and credentials before enabling device tools; if the probe fails it reports why and the tools stay disabled (`--no-verify` skips the probe). After a verified connect the session enters **board mode**: the default tools (`exec`, `read_file`, `write_file`, `edit_file`, `list_directory`, `search_files`, …) run on the board over SSH, and ROS2 (`ros2_topic_list`, `ros2_node_list`, `ros2_service_call`, `ros2_launch`, …) plus `device_*` diagnostics become available, honoring the board's `ROS_DOMAIN_ID`. Leave with `/disconnect` (or Ctrl+D on an empty prompt) to restore local tools exactly as they were; `--hybrid` keeps local tools and only adds the `device_*` / `ros2_*` ones. The host keeps control of SSH credentials, approval policy, and protected paths. -3. Attach context (drag a path in, or use `/attach`); on the macOS TUI you can copy a screenshot and press `Ctrl+V`: +### Give Moss RDK Board Skills - ```text - /attach ./screenshot.png - What is wrong in this UI? - ``` +On (or connected to) an RDK board, Moss is most useful when it knows the RDK stack. The open [**device-knowledge**](https://github.com/D-Robotics/device-knowledge) pack is a set of `SKILL.md` files Moss loads directly — point it at the pack and Moss applies that knowledge while operating the board: -4. Give Moss a concrete task. It asks before file writes, commands, and external actions unless you choose a more autonomous policy: +| Skill | What it unlocks | +| --- | --- | +| `rdk-device` | Model-deploy loop (`.pt`/`.onnx` → `.bin` BPU toolchain), first-boot networking, camera / vision inference | +| `rdk-ros` | TROS/ROS2 setup, `ros2` commands, node troubleshooting, stereo-depth / Livox nodes | +| `rdk-peripheral-cookbook` | GPIO / I2C / SPI / UART, PWM servos, motors, LED / WS2812, audio (ALSA), `libgpiod` | +| `rdk-board-knowledge` | Board-baseline checks, error diagnosis, a 55-entry fault lookup | +| `rdk-hardware` · `rdk-ecosystem` | 40-pin GPIO, camera, BPU pipeline, thermal, networking · RDK lineup, model feasibility, cross-platform compare | +| `jetson-knowledge` · `rpi-knowledge` · `rk-knowledge` | Equivalent packs for Jetson, Raspberry Pi, and Rockchip RK3588 | - ```text - Fix the failing test, explain the root cause, and run the narrowest verification. - ``` +Load the pack any one of these ways, then run `/skills` to confirm: -## Interactive Commands +```bash +# 1. Clone into a default skill root (auto-scanned, no config): +git clone https://github.com/D-Robotics/device-knowledge ~/.agents/skills/device-knowledge -Inside a session, type `/help` for the full list. The commands you will use most: +# 2. Or point your Moss config at the pack's skills/ directory: +# add to your moss config.json → "skills": { "extraRoots": ["/path/to/device-knowledge/skills"] } -| Command | Purpose | -| --- | --- | -| `/status` | Model, login, workspace, board target, and tool state | -| `/model` · `/models` | Switch the active model, or list models for the provider | -| `/sessions` · `/resume [key\|--last]` | List saved conversations, and switch into one | -| `/connect ` · `/disconnect` | Enter / leave board mode for an RDK device | -| `/goal ` | Run until a goal condition is met (goal runner) | -| `/compact` | Compress older history into a summary to free context | -| `/attach ` | Attach an image or text file to the next prompt | -| `/diff` · `/review` | Show working-tree changes, or review them for bugs/safety | -| `/mcp` · `/doctor` | Inspect MCP servers, or health-check the session | -| `/memory` · `/skills` | Show stored long-term memory, or available/learned skills | -| `/yolo` | Grant full power for this session — no per-call approval (`/yolo off` reverts) | -| `/clear` | Start a new conversation (clears the context window) | +# 3. Or just run Moss from inside a checkout — its skills/ folder is auto-discovered. +``` -You can also press **Shift+Tab** to cycle the interaction mode (see [Automation And Safety](#automation-and-safety)). +The skills are knowledge and instructions, not board binaries: they make Moss act correctly on the device, while the host still owns credentials and approvals. ## Long-Running Tasks And Resume -Moss is built to survive long, interruptible work rather than restart from zero. - -Every plain `moss` launch is a new saved conversation. Pick history back up only when you ask: +Every plain `moss` launch is a new saved conversation; you pick history back up only when you ask: ```bash -moss resume --last # continue the most recent saved session -moss resume --session # continue a specific session +moss resume --last # continue the most recent session moss --session work # continue or create a named session moss --continue "keep going" # one-shot that auto-resumes the latest session -moss fork --last # branch a copy of a session without touching the original +moss fork --last # branch a copy without touching the original ``` -Use `/sessions` to list saved conversations and `/resume [key|--last]` to switch into one without leaving Moss. The session pickers show a title derived from the first message, so a saved session is recognizable instead of a bare `cli-` key. - -Within a run, Moss keeps a working-context checkpoint of the active task — goal, completed and pending steps, important paths, and recent tool findings. If a run is interrupted — a tool-loop guard fires, a tool errors, or the turn budget is reached — the task is marked **resumable** instead of lost, the CLI tells you it stopped before finishing and how to continue, and the saved context is re-injected on the next turn. Saying `continue` / `继续` (or running `/goal`) resumes from that checkpoint and avoids repeating finished steps rather than starting over. Compaction preserves the goal and pending steps, so long tasks keep their thread even after older history is summarized. - -For multi-step work you can also hand Moss an explicit goal and let it drive: +Within a run, Moss keeps a working-context checkpoint of the active task (goal, done/pending steps, key paths, recent findings). If a run is interrupted — a tool-loop guard fires, a tool errors, or the turn budget is reached — the task is marked **resumable** instead of lost: the CLI tells you it stopped early and how to continue, and saying `continue` / `继续` (or `/goal`) resumes from the checkpoint instead of repeating finished steps. Compaction preserves the goal and pending steps, so long tasks keep their thread. ```text /goal migrate this repo to the new package name and verify the build ``` -The goal runner keeps working until the goal is completed, blocked, cleared, or stopped. Per-request tool-loop budgets are opt-in host/user limits. - -## Connect An RDK Board - -Use `/connect` inside a live session; no restart is required: - -```text -/connect 192.168.1.10 --user root -/connect ubuntu@192.168.1.10 --port 2222 --key ~/.ssh/id_rsa -/status -Check camera, ROS2 nodes, disk space, and device health. -``` - -`/connect` verifies SSH reachability and credentials before enabling device tools; if the probe fails it reports why and the tools stay disabled. Pass `--no-verify` to register tools without probing (e.g. a board that is about to boot). - -After a verified connect the session enters **board mode**: the default tools (`exec`, `read_file`, `write_file`, `edit_file`, `list_directory`, `search_files`, `search_code`, `move_file`) run on the board over SSH, so working in Moss feels like running it on the board itself. ROS2 tools (`ros2_topic_list`, `ros2_topic_echo`, `ros2_node_list`, `ros2_service_call`, `ros2_launch`, …) and `device_*` diagnostics become available, and honor the board's `ROS_DOMAIN_ID` when one is configured. Leave board mode with `/disconnect` or Ctrl+D on an empty prompt — local tools are restored exactly as they were. Pass `--hybrid` to keep the local tools and only add the `device_*` / `ros2_*` tools alongside. - -The host still controls SSH credentials, approval policy, protected paths, and available device tools. Device and ROS tools require host-side `ssh`/`sshpass` and execute Linux commands on the remote device rather than on your workstation. - -## Attach Images And Files - -```text -/attach ./screenshot.png -/attach ./camera-frame.jpg -/attach ./error.log -Explain what you see and propose the next debug step. -``` - -Images (`png`, `jpg`, `jpeg`, `gif`, `webp`) are sent as model image blocks when the active provider/model supports vision. Text files are inserted as prompt context. Use `/attach list` to review pending attachments and `/attach clear` to discard them. In a prompt, an `@path` reference (`summarize @README.md`) attaches that file inline. +The goal runner keeps working until the goal is completed, blocked, cleared, or stopped. ## Use Your Own Model -The built-in D-Robotics gateway is for instant first use. Configure your own provider when you need your own account, billing, private gateway, data-local deployment, or a self-hosted model. Your model config always overrides the built-in gateway. +The built-in gateway is for instant first use; configure your own provider when you need your own account, billing, private gateway, or a self-hosted model. Your config always overrides the gateway. ```bash -moss setup # interactive: choose provider + model, paste the API key (hidden) +moss setup # interactive: choose provider + model, paste the key (hidden) moss auth status # show the resolved provider/model/key source ``` -Supported providers are `deepseek`, `qwen`, `openai`, `anthropic`, and `openai-compatible`. A private OpenAI-compatible gateway: +Supported providers: `deepseek`, `qwen`, `openai`, `anthropic`, `openai-compatible`. For a private gateway: ```bash moss config set provider openai-compatible moss config set model -moss config set baseUrl https://llm.example.com -moss setup # stores the API key (hidden prompt) -moss +moss config set baseUrl https://llm.example.com # API root, not /chat/completions +moss setup # stores the key (hidden prompt) ``` -Model settings (provider, model, baseUrl, API key) live in moss config only. Environment variables such as `DEEPSEEK_API_KEY`, `OPENAI_API_KEY`, or `DMOSS_PROVIDER` are deliberately ignored — a key exported for another tool will never silently change which provider Moss talks to. `moss doctor` lists any such leftover variables under `env ignored`. - -`baseUrl` is the API root, not the full chat endpoint — do not include `/chat/completions`. Both `https://llm.example.com` and `https://llm.example.com/v1` are accepted; Moss calls `/v1/chat/completions` for OpenAI-compatible providers, and rejects a malformed base URL at set time instead of failing on the first call. - -Configuration priority is: CLI flags and `-c key=value` > project `.moss/config.json` > `moss config` / `moss setup` > built-in gateway. For scripts and CI, prefer an explicit config file over env vars: `moss --config-file /path/to/config.json` (JSON with `provider` / `model` / `baseUrl` / `apiKey`). - -Inside Moss, use `/model` to list models from the active provider, choose by number, or type `/model ` for a custom model. +Model settings live in moss config only — environment variables like `OPENAI_API_KEY` or `DMOSS_PROVIDER` are deliberately ignored so a key exported for another tool never silently changes your provider (`moss doctor` lists any such leftovers). Priority: CLI flags / `-c key=value` > project `.moss/config.json` > `moss config` / `moss setup` > built-in gateway. Inside Moss, `/model` lists provider models or sets a custom one. ## Automation And Safety -For unattended benchmark or CI runs, choose an explicit approval policy before starting: +Moss asks before file writes, commands, and external actions unless you choose a more autonomous policy. Interactively, **Shift+Tab** cycles `plan` / `default` / `accept-edits`, and `/yolo` grants a full-power session (`/yolo off` reverts). For unattended starts, set the policy up front: ```bash -DMOSS_CLI_AUTO_APPROVE=1 moss --workspace-write "write and verify the tool" -# or persist a broader local policy: -moss config set profile autonomous +moss --ask-for-approval workspace-write "write and verify the tool" +DMOSS_CLI_AUTO_APPROVE=1 moss -p "run the benchmark" ``` -`DMOSS_CLI_AUTO_APPROVE=1` only approves tools that pass the active safety policy. It does not bypass `--read-only`, `deniedTools`, protected paths, the dangerous-command floor, or workspace sandbox checks. For browser-driven real websites, use `--full-access` because `web_browser_control` is classified as an external interaction. In a headless (`-p` / piped / non-TTY) run, auto-approved mutating tools leave a one-line `[approval]` audit note on stderr so the run stays observable. - -Interactively you have three modes, toggled with **Shift+Tab**: `plan` (read-only — Moss proposes a plan but makes no changes), `default` (normal per-call approval), and `accept-edits` (auto-approve workspace writes). `/yolo` grants a full-power session with no per-call prompts for this run (`/yolo off` reverts). For unattended starts you can set the policy up front with `--ask-for-approval ` where `` is `never`, `prompt`, `on-request`, `read-only`, `workspace-write`, or `full-access`; an unknown value is rejected rather than silently ignored. None of these bypass `--read-only`, `deniedTools`, protected paths, or the dangerous-command floor. +`--ask-for-approval` accepts `never`, `prompt`, `on-request`, `read-only`, `workspace-write`, and `full-access`; an unknown value is rejected, not ignored. None of these — nor `DMOSS_CLI_AUTO_APPROVE=1` — bypass `--read-only`, `deniedTools`, protected paths, or the dangerous-command floor. Device mutations (reboot, on-device `rm`, `ros2_service_call`, …) are never blanket-trusted: "always" approves only the current call. Scope trust per tool with `moss config set trustedTools/deniedTools `. In a headless run, auto-approved mutating tools leave a one-line `[approval]` audit note on stderr. -Trust can be scoped per tool with `moss config set trustedTools ` and `deniedTools ` (name or glob). A broad wildcard such as `*` is flagged when you set it, because it auto-approves every tool. Device mutations (reboot, restart, on-device `rm`, `ros2_service_call`, …) are never blanket-trusted: answering "always" approves only the current call, and the next device command still prompts. +Run `moss doctor` to health-check Node, version, auth, provider/model, workspace, safety policy, and MCP in one report; it exits non-zero on a real failure, so it works as a CI gate. -Moss exposes two browser tools when a local Chrome/Chromium executable is available: `web_browser_fetch` for read-only JavaScript-rendered pages and `web_browser_control` for approved browser workflows. `@rdk-moss/agent` uses `puppeteer-core`, so it does not download a browser during install. If auto-discovery cannot find one, set `export DMOSS_BROWSER_EXECUTABLE="/path/to/chrome-or-chromium"`. +## Skills, Memory & MCP -## MCP Servers +Moss discovers `SKILL.md` files under `.moss/skills/`, `~/.agents/skills`, and configured `skills.extraRoots` (see [board skills](#give-moss-rdk-board-skills)). Built-in workflow skills cover methodical building, debugging, test-driven changes, and migration safety; the `install_skill` tool can author a new workspace skill through the normal approval policy, and good runs crystallize into candidates you review with `/skills`. Long-term memory works through `memory_read`/`memory_write`/`memory_delete`, and Moss auto-loads `USER.md`, `MEMORY.md`, and `AGENTS.md` from the workspace root (`/memory` to inspect). -Moss can load tools from [Model Context Protocol](https://modelcontextprotocol.io) servers. Register them without editing JSON: +Load tools from [Model Context Protocol](https://modelcontextprotocol.io) servers without editing JSON: ```bash moss mcp add fs npx -y @modelcontextprotocol/server-filesystem /data -moss mcp add ros-docs node ./mcp/ros-docs.js --env ROS_DISTRO=humble moss mcp list -moss mcp remove fs -moss config set mcp.enabled true # enable MCP servers from config +moss config set mcp.enabled true ``` -Inside a session, `/mcp` shows configured servers, their connection status, and tool counts. A server whose connection fails is reported rather than silently dropped. The server config lives next to your Moss config (default `~/.config/dmoss/mcp.json`); override the path with `moss config set mcp.configPath ` or `DMOSS_MCP_CONFIG`. - -## Skills And Memory - -Moss discovers `SKILL.md` files under `.moss/skills/`, `.moss/agent/skills/`, legacy `skills/` and `agent/skills/`, and configured extra skill directories. Built-in workflow skills cover methodical building, debugging, test-driven changes, migration safety, and CodeGraph navigation when available. Moss can install a new workspace skill itself through the `install_skill` tool, which writes a frontmatter-backed `SKILL.md` under `.moss/skills//SKILL.md` as a workspace write that goes through the normal approval policy. Successful runs can also crystallize into skill candidates you review with `/skills` and promote or discard. - -Long-term memory is available through `memory_read` / `memory_write` / `memory_delete`, and Moss auto-loads workspace context from `USER.md`, `MEMORY.md`, and `AGENTS.md` at the workspace root. Use `/memory` to see stored memories. +`/mcp` shows configured servers, connection status, and tool counts; a server that fails to connect is reported, not silently dropped. -## Honest Runtime Behavior +## Embed Moss In Your Product -Moss tells the model what is actually available in the current run before it starts working: - -- The system prompt includes the registered tool names for this run, so Moss should not invent tool names or claim unavailable capabilities. -- CodeGraph guidance is conditional: if `codegraph_*` tools are registered, Moss can prefer structural navigation; otherwise it says CodeGraph is unavailable and falls back to `search_code`, `search_files`, `list_directory`, and `read_file`. -- The behavior contract asks Moss to be 实事求是: separate verified facts from inference and assumptions, report missing evidence, and never claim a result — "connected", "launched", "opened", "done" — without an actual check behind it. Moss does not spawn a desktop GUI app to "open a terminal"; it already runs inside one. - -## Troubleshooting - -Run `moss doctor` to health-check Node, version, auth, provider/model, workspace, runtime dir, safety policy, and MCP in one report. It exits non-zero on a real failure, so it works as a CI health gate. Inside a session, `/doctor` runs the same check for the live run and `/mcp` shows MCP status. `moss config validate` checks config files and surfaces audit warnings. - -## Build With Moss - -Only using the CLI? You can stop here. - -Building a product or service that embeds Moss? Scaffold a host project: +Only using the CLI? You can stop here. Building a product that embeds Moss? Scaffold a host: ```bash npx create-dmoss-app my-host ``` -Embed into an existing product host by installing the packages, registering providers / tools / storage / approval gates / event sinks, publishing a `MossHostRuntimeManifest`, and running `evaluateMossHostCompatibility()` in CI. This is useful when you want Moss inside your own IDE, robot console, browser app, desktop app, or device platform instead of only as the `moss` terminal command — see [Integrating Moss Into A Host](#integrating-moss-into-a-host). - -## Repository Scope - -This repository contains the parts of Moss that can be maintained independently from a product shell. - -| Package | Role | -| --- | --- | -| `@rdk-moss/core` | Public contracts, platform extension types, Host Adapter contract, and robotics prompts | -| `@rdk-moss/agent` | Agent runtime, tool loop, context management, safety helpers, skills, and provider adapters | -| `@rdk-moss/memory` | Context-aware memory selection and memory draft helpers | -| `@rdk-moss/skills` | Skill learning, validation, scoring, and promotion helpers | -| `@rdk-moss/teaching` | Teach-while-solve annotations and tool digest helpers | -| `create-dmoss-app` | Minimal project scaffolding for external Moss users | - -Product hosts are outside this repository. - -## Architecture - -If you only use `moss`, you can skip this section. It exists for teams that embed Moss into a larger product. - -Moss is split around a narrow host boundary: - -```text -Product host - - model keys and provider configuration - - UI, native shell, persistence, telemetry - - local workspace and device access - - product tools and external channels - - domain knowledge packages - | - | Host Adapter manifest + runtime injection - v -Moss packages - - agent loop and tool execution pipeline - - context, memory, skills, and teaching primitives - - host-neutral safety helpers - - public extension contracts -``` - -The agent runtime should not import product code. Product hosts inject concrete providers, tools, storage, approval handling, knowledge modules, and event transports. - -## Host Adapter Contract - -The public contract lives in: +Moss is split around a narrow host boundary: the host owns model keys, UI, storage, telemetry, device access, product tools, and knowledge packages; Moss owns the agent loop, tool pipeline, context/memory/skills primitives, and host-neutral safety. A host registers its providers/tools/storage/approval gates/event sinks, publishes a `MossHostRuntimeManifest`, and runs `evaluateMossHostCompatibility()` in CI before adopting a release. ```ts import { @@ -303,97 +183,29 @@ import { } from '@rdk-moss/core/contracts/host-adapter'; ``` -A host declares its id/name/version, the Moss package versions it consumes, capabilities such as `llm_provider`, `tool_registry`, `approval_gate`, `event_sink`, `memory`, `knowledge`, `device_runtime`, and `channel_runtime`, the provider families it supplies, tool names and permission boundaries, and event schemas and knowledge modules. Moss releases use `evaluateMossHostCompatibility()` to decide whether a host can consume the release unchanged. - -Read the detailed contract guide: - -- [`docs/host-adapter-contract.md`](docs/host-adapter-contract.md) - -## Project Goal And Roadmap - -Moss is being developed as a robotics-grade, host-neutral agent runtime. The roadmap defines the north star, non-goals, six-month target, and phase plan: - -- [`docs/roadmap.md`](docs/roadmap.md) - -## Maintainer Guides - -These documents are durable project manuals, not session notes: - -- [`AGENTS.md`](AGENTS.md): agent working rules, architecture-review discipline, CodeGraph usage, and bug-fix checklists for this repository. -- [`ARCHITECTURE_ASSESSMENT.md`](ARCHITECTURE_ASSESSMENT.md): current architecture findings, rejected hypotheses, and "do not change" decisions. -- [`CLEAN_CODE_ASSESSMENT.md`](CLEAN_CODE_ASSESSMENT.md): code quality review and cleanup guidance. -- [`docs/host-adapter-contract.md`](docs/host-adapter-contract.md): Host Adapter contract guide. -- [`docs/tool-runtime.md`](docs/tool-runtime.md): tool execution pipeline, ownership boundaries, hooks, approval, timeout, and guard limits. -- [`docs/tool-side-effect-idempotency-rfc.md`](docs/tool-side-effect-idempotency-rfc.md): RFC for in-flight deduplication of non-idempotent tools. -- [`docs/release-checklist.md`](docs/release-checklist.md): release validation and host update checklist. - -Historical phase notes such as [`docs/goals-phase-5.md`](docs/goals-phase-5.md) and [`docs/goals-phase-6.md`](docs/goals-phase-6.md) explain why the current contracts and tests exist, but the roadmap and release checklist are the source of truth for new work. - -## Architecture Review Discipline - -Do not turn open-ended reviews into endless issue lists. A candidate issue is worth fixing only when it blocks a committed goal, a real host path, safety, data correctness, resource lifecycle, or a contract that downstream users rely on. Style concerns, framework feature comparisons, and speculative future abstractions should be recorded as observations or rejected explicitly. - -Before changing architecture, preserve this loop: - -1. Generate hypotheses from the actual code and active host workflows. -2. Try to falsify each hypothesis by reading source, checking callers, tracing runtime flow, or running a focused test. -3. Fix bugs with declare + enforce + test. Existing tests are regression checks; the fix still needs a test that would have failed before the change. -4. Document "do not touch" conclusions when a suspicion is falsified, so future reviews do not re-litigate the same point. - -## What Does Not Belong In Moss - -Keep product-specific code in the host repository. Do not add: - -- Product-host `server/**`, `src/**`, or native-shell code. -- Product configuration defaults, local sessions, logs, or generated desktop artifacts. -- Supabase keys, model keys, image provider keys, device passwords, SSH credentials, or user account details. -- Host-owned integrations such as board deployment, external chat channels, desktop IPC, native packaging, or product settings UI. -- Built `dist/` directories as tracked source. - -RDK-specific domain knowledge may live in a separate optional package. The Moss core packages should stay useful to other robotics or device-product hosts. +| Package | Role | +| --- | --- | +| `@rdk-moss/core` | Public contracts, platform extension types, Host Adapter contract, robotics prompts | +| `@rdk-moss/agent` | Agent runtime, tool loop, context management, safety, skills, provider adapters | +| `@rdk-moss/memory` · `@rdk-moss/skills` · `@rdk-moss/teaching` | Memory selection · skill learning · teach-while-solve annotations | +| `create-dmoss-app` | Minimal project scaffolding for external hosts | -## Development +See the [Host Adapter contract guide](docs/host-adapter-contract.md) for the full surface and version policy. -Use Node 22.16 or newer for this workspace. Moss is verified on Ubuntu, macOS, and Windows in CI. +## For Maintainers & Contributors -```sh +```bash npm install -npm run verify +npm run verify # OSS-boundary + hygiene checks, build, typecheck, lint, tests (Ubuntu/macOS/Windows in CI) ``` -`npm run verify` runs open-source boundary checks, workspace hygiene checks (Node engine consistency, package test scripts, and local Markdown links), workspace builds, typechecks, and package tests. The boundary check can be run directly with `npm run check:boundaries`. +Durable project manuals (not session notes): -## Integrating Moss Into A Host - -1. Install or vendor the relevant Moss packages. -2. Keep credentials and product-specific defaults in the host. -3. Register host providers, tools, storage, approval gates, and event sinks with the agent runtime. -4. Publish a `MossHostRuntimeManifest` from the host adapter. -5. Run `evaluateMossHostCompatibility()` in CI before adopting a new Moss release. - -For a downstream product host, the host adapter lives in that host repository and should be validated by its own Moss upgrade flow. - -## Version Policy - -Moss follows semver for the public package surface. - -- Patch releases fix bugs or improve internals without requiring host adapter changes. -- Minor releases may add optional fields, optional capabilities, or new helper APIs. Existing hosts should continue to work. -- Major releases may change required Host Adapter fields or required capabilities. Hosts must update their adapter before adopting the release. - -For downstream product hosts, a Moss patch or minor update should normally be a submodule/package update plus validation. Adapter changes are required only when `MOSS_HOST_ADAPTER_CONTRACT_VERSION` changes incompatibly or a release declares new required host capabilities, event schemas, or provider families. - -## Release Checklist - -Every Moss release must pass the release checklist: - -- [`docs/release-checklist.md`](docs/release-checklist.md) - -At minimum, maintainers run: - -```bash -npm run verify -npm run smoke:moss-cli -``` +- [`AGENTS.md`](AGENTS.md) — agent working rules, architecture-review discipline, CodeGraph usage, bug-fix checklists. +- [`docs/roadmap.md`](docs/roadmap.md) — north star, non-goals, and phase plan. +- [`docs/host-adapter-contract.md`](docs/host-adapter-contract.md) — Host Adapter contract guide and version policy. +- [`docs/tool-runtime.md`](docs/tool-runtime.md) — tool execution pipeline, approval, timeout, and guard limits. +- [`docs/release-checklist.md`](docs/release-checklist.md) — release validation and host-update checklist. +- [`ARCHITECTURE_ASSESSMENT.md`](ARCHITECTURE_ASSESSMENT.md) — architecture findings, rejected hypotheses, and "do not change" decisions. -If the release is intended for a downstream host, update its Moss dependency or vendored subtree and run the host upgrade verification there. +Keep product-specific code (native shells, product config/secrets, board deployment, packaging) in host repositories — the Moss core packages stay useful to any robotics or device-product host. Moss follows semver for its public package surface; a patch/minor update should be a dependency bump plus validation, and adapter changes are required only when `MOSS_HOST_ADAPTER_CONTRACT_VERSION` changes incompatibly. diff --git a/README.zh-CN.md b/README.zh-CN.md new file mode 100644 index 0000000..1fb9828 --- /dev/null +++ b/README.zh-CN.md @@ -0,0 +1,211 @@ +# Moss + +[English](README.md) · **简体中文** + +**一个开箱即用、面向机器人的终端 Agent，同时也是可嵌入的 Agent 运行时。** 由 地瓜机器人 (D-Robotics) 打造。 + +运行 `moss`，提问，开干。无需 API Key、无需强制登录——首次启动就已接入内置的 D-Robotics 网关。想用自己的模型、计费或私有端点时，把 Moss 指向任意 OpenAI 兼容或 Anthropic 服务即可，Agent 本身不变。`/connect` 一块 RDK 开发板，整个会话就通过 SSH 搬到板子上运行。 + +> `moss` 是主命令；`dmoss` 作为兼容别名保留。 + +

+ Moss 终端启动演示 +

+ +## 快速开始 + +```bash +npm i -g @rdk-moss/agent@latest # 需要 Node 22.16+ +moss +``` + +首次启动即可在内置网关上工作——直接提问就有回答，无需 Key、无需登录。 + +```bash +moss "看看这个项目的磁盘占用" # 一次性：回答后退出 +echo "列出失败的测试" | moss # 管道 stdin +moss -m qwen-plus "总结 @README.md" # 临时覆盖模型；@路径 可附加文件 +``` + +随时用 `npm i -g @rdk-moss/agent@latest` 更新，或在 Moss 内输入 `/upgrade`。 + +## 为什么选 Moss + +还是你熟悉的 Claude Code / Codex 终端循环，但所有权模型不同： + +- **零配置起步**——内置 D-Robotics 网关，无需模型 Key，无需强制登录。 +- **自带模型** ——DeepSeek、Qwen、任意 OpenAI 兼容网关、Anthropic 或自托管模型。切换服务商从不改变 Agent。 +- **原生面向机器人与开发板**——`/connect ` 让会话通过 SSH 跑在 RDK 板上，带诊断与 ROS2 工具；再用 [device-knowledge](https://github.com/D-Robotics/device-knowledge) 的 Skill 把整套 RDK 知识教给它。 +- **扛得住长程、可中断的任务**——会话自动保存，工作上下文检查点记录当前任务，`moss resume` 接着干而不是从零重来。 +- **诚实可信**——区分已验证事实、推断与假设，能力不可用时如实上报，从不声称未经检查的结果。 +- **可嵌入**——它是带公开契约和 npm 包的运行时，而不仅是一个独立 App。 + +## 日常使用 + +在项目里启动 Moss，然后用自然语言驱动它。输入 `/help` 查看完整命令；最常用的几个： + +| 命令 | 作用 | +| --- | --- | +| `/status` · `/model` | 显示模型/登录/工作区/板端状态 · 切换当前模型 | +| `/connect ` · `/disconnect` | 进入 / 离开 RDK 设备的板端模式 | +| `/resume [key\|--last]` · `/sessions` | 切换到某个已保存会话 · 列出会话 | +| `/goal <条件>` | 持续运行直到达成目标条件（goal runner） | +| `/attach <路径>` · `/diff` · `/review` | 附加图片/文件 · 查看改动 · 审查改动找 bug | +| `/skills` · `/memory` · `/mcp` · `/doctor` | 查看技能 · 记忆 · MCP 服务 · 体检本次运行 | +| `/compact` · `/clear` · `/yolo` | 压缩历史 · 新会话 · 全权会话（`/yolo off` 撤销） | + +按 **Shift+Tab** 在交互模式间循环：`plan`（只读）、`default`（逐次审批）、`accept-edits`（自动批准工作区写入）。用 `@路径` 内联附加上下文（`总结 @README.md`），或 `/attach ./screenshot.png`；图片发给支持视觉的模型，文本文件作为提示上下文。 + +## 连接 RDK 开发板 + +在活动会话里直接 `/connect`，无需重启： + +

+ Moss 板连接与图片附加演示 +

+ +```text +/connect 192.168.1.10 --user root +/connect ubuntu@192.168.1.10 --port 2222 --key ~/.ssh/id_rsa +检查摄像头、ROS2 节点、磁盘空间和设备健康状况。 +``` + +`/connect` 会先验证 SSH 可达性与凭据，再启用设备工具；探测失败会说明原因，工具保持禁用（`--no-verify` 跳过探测）。验证通过后会话进入**板端模式（board mode）**：默认工具（`exec`、`read_file`、`write_file`、`edit_file`、`list_directory`、`search_files` 等）通过 SSH 在板上执行，ROS2（`ros2_topic_list`、`ros2_node_list`、`ros2_service_call`、`ros2_launch` 等）与 `device_*` 诊断工具同时可用，并遵循板子配置的 `ROS_DOMAIN_ID`。用 `/disconnect`（或空提示符下 Ctrl+D）退出，本地工具原样恢复；`--hybrid` 则保留本地工具、只额外加上 `device_*` / `ros2_*`。SSH 凭据、审批策略与受保护路径始终由宿主掌控。 + +### 给 Moss 装上 RDK 板端 Skill + +在 RDK 板上（或连接到板子时），Moss 懂 RDK 这套栈才最好用。开源的 [**device-knowledge**](https://github.com/D-Robotics/device-knowledge) 知识包就是一组 `SKILL.md`，Moss 可直接加载——指向它，Moss 操作板子时就会应用这些知识： + +| Skill | 解锁什么 | +| --- | --- | +| `rdk-device` | 模型部署闭环（`.pt`/`.onnx` → `.bin` BPU 工具链）、首次开箱联网、摄像头/视觉推理 | +| `rdk-ros` | TROS/ROS2 环境初始化、`ros2` 命令、节点排障、双目深度/Livox 节点 | +| `rdk-peripheral-cookbook` | GPIO/I2C/SPI/UART、PWM 舵机、电机、LED/WS2812、音频（ALSA）、`libgpiod` | +| `rdk-board-knowledge` | 板型基线确认、报错诊断、55 条故障速查 | +| `rdk-hardware` · `rdk-ecosystem` | 40PIN GPIO、摄像头、BPU 流水线、散热、网络 · RDK 选型、模型可行性、跨平台对比 | +| `jetson-knowledge` · `rpi-knowledge` · `rk-knowledge` | Jetson、树莓派、Rockchip RK3588 的对应知识包 | + +以下任一方式加载，然后用 `/skills` 确认： + +```bash +# 1. 克隆到默认技能根目录（自动扫描，无需配置）： +git clone https://github.com/D-Robotics/device-knowledge ~/.agents/skills/device-knowledge + +# 2. 或在 Moss 配置里指向知识包的 skills/ 目录： +# 在 moss config.json 中加入 → "skills": { "extraRoots": ["/path/to/device-knowledge/skills"] } + +# 3. 或直接在某个 checkout 内运行 Moss——它的 skills/ 目录会被自动发现。 +``` + +这些 Skill 是知识与指令，不是板端二进制：它们让 Moss 在设备上行为正确，而凭据与审批仍归宿主所有。 + +## 长程任务与续跑 + +每次普通 `moss` 启动都是一个新的已保存会话；只有你主动要求时才会接续历史： + +```bash +moss resume --last # 继续最近一次会话 +moss --session work # 继续或创建一个命名会话 +moss --continue "接着干" # 一次性运行，自动续上最近会话 +moss fork --last # 复制一个分支，不影响原会话 +``` + +运行过程中，Moss 维护当前任务的工作上下文检查点（目标、已完成/待办步骤、关键路径、近期发现）。一旦运行被打断——工具循环守卫触发、工具报错、或回合预算用尽——任务会被标记为**可续跑（resumable）**而非丢失：CLI 会告诉你它提前停了、以及如何继续，说 `continue` / `继续`（或 `/goal`）就从检查点续跑、不重复已完成的步骤。压缩历史时会保留目标与待办步骤，长任务因此不断线。 + +```text +/goal 把这个仓库迁移到新包名并验证构建 +``` + +goal runner 会一直工作，直到目标完成、受阻、被清除或被停止。 + +## 使用你自己的模型 + +内置网关用于即时上手；当你需要自己的账号、计费、私有网关或自托管模型时，再配置自己的服务商。你的配置始终覆盖内置网关。 + +```bash +moss setup # 交互式：选服务商 + 模型，粘贴 Key（隐藏输入） +moss auth status # 显示解析出的服务商/模型/Key 来源 +``` + +支持的服务商：`deepseek`、`qwen`、`openai`、`anthropic`、`openai-compatible`。私有网关示例： + +```bash +moss config set provider openai-compatible +moss config set model <你的模型> +moss config set baseUrl https://llm.example.com # API 根地址，不要带 /chat/completions +moss setup # 存储 Key（隐藏输入） +``` + +模型设置只存在 moss 配置里——`OPENAI_API_KEY`、`DMOSS_PROVIDER` 等环境变量被刻意忽略，这样为别的工具导出的 Key 不会悄悄改变你的服务商（`moss doctor` 会列出这类残留变量）。优先级：CLI 参数 / `-c key=value` > 项目 `.moss/config.json` > `moss config` / `moss setup` > 内置网关。在 Moss 内用 `/model` 列出服务商模型或设置自定义模型。 + +## 自动化与安全 + +除非你选择更自主的策略，Moss 在文件写入、执行命令和外部动作前都会询问。交互式下，**Shift+Tab** 循环 `plan` / `default` / `accept-edits`，`/yolo` 授予全权会话（`/yolo off` 撤销）。无人值守启动时可预先设定策略： + +```bash +moss --ask-for-approval workspace-write "编写并验证这个工具" +DMOSS_CLI_AUTO_APPROVE=1 moss -p "跑一遍基准测试" +``` + +`--ask-for-approval` 接受 `never`、`prompt`、`on-request`、`read-only`、`workspace-write`、`full-access`；未知值会被拒绝而非忽略。它们——以及 `DMOSS_CLI_AUTO_APPROVE=1`——都不会绕过 `--read-only`、`deniedTools`、受保护路径或危险命令底线。设备类变更（重启、板端 `rm`、`ros2_service_call` 等）从不被一揽子信任：选"总是"只批准当前这一次。用 `moss config set trustedTools/deniedTools ` 按工具细分信任。无头运行中，被自动批准的变更类工具会在 stderr 留下一行 `[approval]` 审计记录。 + +运行 `moss doctor` 一次性体检 Node、版本、认证、服务商/模型、工作区、安全策略和 MCP；真正失败时退出码非零，可作为 CI 闸门。 + +## 技能、记忆与 MCP + +Moss 会发现 `.moss/skills/`、`~/.agents/skills` 以及配置的 `skills.extraRoots` 下的 `SKILL.md`（见上文板端 Skill 一节）。内置工作流技能涵盖方法化构建、调试、测试驱动改动与迁移安全；`install_skill` 工具可经正常审批策略创建新的工作区技能，优质运行会沉淀为候选技能、用 `/skills` 审阅。长期记忆通过 `memory_read`/`memory_write`/`memory_delete` 工作，Moss 还会自动加载工作区根目录的 `USER.md`、`MEMORY.md`、`AGENTS.md`（用 `/memory` 查看）。 + +无需编辑 JSON 即可从 [Model Context Protocol](https://modelcontextprotocol.io) 服务加载工具： + +```bash +moss mcp add fs npx -y @modelcontextprotocol/server-filesystem /data +moss mcp list +moss config set mcp.enabled true +``` + +`/mcp` 显示已配置的服务、连接状态与工具数量；连接失败的服务会被上报，而不是悄悄丢弃。 + +## 把 Moss 嵌入你的产品 + +只用 CLI？读到这里就够了。要做一个嵌入 Moss 的产品？脚手架生成一个宿主： + +```bash +npx create-dmoss-app my-host +``` + +Moss 围绕一条狭窄的宿主边界拆分：宿主拥有模型 Key、UI、存储、遥测、设备访问、产品工具与知识包；Moss 拥有 Agent 循环、工具流水线、上下文/记忆/技能原语，以及宿主中立的安全机制。宿主注册自己的 服务商/工具/存储/审批闸门/事件接收端，发布一个 `MossHostRuntimeManifest`，并在采用新版本前于 CI 跑 `evaluateMossHostCompatibility()`。 + +```ts +import { + MOSS_HOST_ADAPTER_CONTRACT_VERSION, + evaluateMossHostCompatibility, + type MossHostRuntimeManifest, +} from '@rdk-moss/core/contracts/host-adapter'; +``` + +| 包 | 角色 | +| --- | --- | +| `@rdk-moss/core` | 公开契约、平台扩展类型、Host Adapter 契约、机器人提示词 | +| `@rdk-moss/agent` | Agent 运行时、工具循环、上下文管理、安全、技能、服务商适配 | +| `@rdk-moss/memory` · `@rdk-moss/skills` · `@rdk-moss/teaching` | 记忆选择 · 技能学习 · 边解边教标注 | +| `create-dmoss-app` | 面向外部宿主的最小项目脚手架 | + +完整接口面与版本策略见 [Host Adapter 契约指南](docs/host-adapter-contract.md)。 + +## 给维护者与贡献者 + +```bash +npm install +npm run verify # OSS 边界 + 卫生检查、构建、类型检查、lint、测试（CI 覆盖 Ubuntu/macOS/Windows） +``` + +长期项目手册（非会话笔记）： + +- [`AGENTS.md`](AGENTS.md) —— Agent 工作规则、架构评审纪律、CodeGraph 用法、缺陷修复清单。 +- [`docs/roadmap.md`](docs/roadmap.md) —— 北极星、非目标与阶段计划。 +- [`docs/host-adapter-contract.md`](docs/host-adapter-contract.md) —— Host Adapter 契约指南与版本策略。 +- [`docs/tool-runtime.md`](docs/tool-runtime.md) —— 工具执行流水线、审批、超时与守卫上限。 +- [`docs/release-checklist.md`](docs/release-checklist.md) —— 发布验证与宿主更新清单。 +- [`ARCHITECTURE_ASSESSMENT.md`](ARCHITECTURE_ASSESSMENT.md) —— 架构结论、被否决的假设、"不要改动"的决定。 + +把产品专属代码（原生外壳、产品配置/密钥、板端部署、打包）留在宿主仓库——Moss 核心包要对任何机器人或设备产品宿主都通用。Moss 对其公开包面遵循 semver；patch/minor 更新应当只是一次依赖升级加验证，只有当 `MOSS_HOST_ADAPTER_CONTRACT_VERSION` 不兼容变更时才需要改适配器。 diff --git a/packages/dmoss-agent/README.md b/packages/dmoss-agent/README.md index 235c4e3..4112b15 100644 --- a/packages/dmoss-agent/README.md +++ b/packages/dmoss-agent/README.md @@ -1,367 +1,89 @@ # @rdk-moss/agent -> **Moss is a ready-to-use terminal agent and embeddable robotics agent runtime developed by 地瓜机器人 (D-Robotics).** -> Install `moss` and start with the built-in D-Robotics model gateway; community login is optional. Switch to your own OpenAI-compatible, Anthropic, private, or self-hosted model whenever you want. +**English** · [简体中文](README.zh-CN.md) -The project is **Moss**. The npm package is **`@rdk-moss/agent`**. The primary CLI command is **`moss`**. `dmoss` remains a compatible alias for existing users and scripts. +> **The Moss agent runtime.** Install `moss` to use the terminal agent, or `npm install` to embed a robotics-aware agent — tool loop, context governance, safety hooks, sessions, and pluggable knowledge — inside your own product. + +Made by 地瓜机器人 (D-Robotics). The project is **Moss**; the package is **`@rdk-moss/agent`**; the CLI is **`moss`** (`dmoss` is a compatible alias).

npm node >= 22.16 MIT - tests provider-agnostic

-```bash -npm i -g @rdk-moss/agent@latest -moss -``` -

Moss terminal startup demo

-

- Moss board connection and image attachment demo -

- -## Why Moss? - -Moss gives you the familiar terminal-agent workflow of Claude Code and Codex, but keeps the runtime open, provider-flexible, and device-aware: - -- **Built-in first run** - the D-Robotics gateway works without a model API key or forced community login. -- **Bring your own model** - DeepSeek, Qwen, OpenAI-compatible gateways, Anthropic, or self-hosted endpoints. -- **RDK board workflows** - `/connect ` enables board SSH, diagnostics, and ROS2 tooling inside a live session. -- **Embeddable runtime** - use the Host Adapter contract to put Moss inside your own IDE, robot console, desktop app, or device platform. -- **Evidence-first behavior** - Moss is instructed to separate verified facts, inferences, and assumptions, and to say when evidence or runtime capabilities are unavailable. -- **Self-installing workspace skills** - Moss can use the approved `install_skill` tool to write reusable `SKILL.md` workflows into `.moss/skills/`. -- **Goal-runner CLI** - `/goal ` keeps the interactive CLI working across turns until the goal is completed, blocked, cleared, or stopped. -- **Agent primitives included** - goals, compaction, sessions, attachments, MCP, skills, sub-agents, safety hooks, and tool execution. - -If that ownership model matters to you, star the repo, fork it for your host, and open issues for providers, boards, or workflows you want Moss to cover next. +This package is two things in one: -## Moss Vs Claude Code And Codex +- **A terminal agent** — `npm i -g @rdk-moss/agent`, run `moss`, work immediately on the built-in D-Robotics gateway (no model key, no forced login). +- **An embeddable runtime** — `npm install @rdk-moss/agent @rdk-moss/core`, then drive `DmossAgent` from your own host with your providers, tools, storage, and approval policy. -| Capability | Moss | Claude Code | Codex | -| --- | --- | --- | --- | -| Interactive terminal agent | `moss` (`dmoss` alias) | yes | yes | -| Default first run | Built-in D-Robotics gateway, no model key or forced login | Anthropic account | OpenAI account | -| Bring your own model | OpenAI-compatible, Anthropic, private gateways, self-hosted models | limited to Anthropic path | limited to OpenAI path | -| Robotics / board workflows | RDK board connect, SSH, diagnostics, ROS2 tool path | general developer agent | general developer agent | -| Embedding model | Public Host Adapter contract and npm packages | standalone product | standalone product | -| Product control | Host owns UI, tools, storage, approvals, credentials, telemetry | vendor-owned app | vendor-owned app | - -Claude Code and Codex are excellent polished standalone assistants. Moss is for teams who want that style of agent while also owning the model route, device tools, product integration, and extension surface. - -## Open-source scope (the harness) - -**D-Moss is not “just an LLM wrapper”.** These packages ship a **reusable robotics Agent harness**: the tool loop, context governance (pruning / compaction), safety and approval hooks, session persistence, structured errors and retries, and pluggable `KnowledgeModule`s — so your application can focus on devices, UX, and policies. - -| In `@rdk-moss/core` + `@rdk-moss/agent` | Outside the stable `@rdk-moss/*` API (host / product) | -|-----------------------------------|-----------------------------------------------------| -| Contracts, `DmossAgent`, `ToolRegistry`, hooks | HTTP/Socket APIs, desktop UI, SSH | -| Pruning, compaction, token budgeting | Your own installers, fleet routing, dashboards | -| `LLMProvider` (host implements; **recommended minimum integration**) | Your model transport (REST, WebSocket, local inference, etc.) | -| Optional `PiAiLLMProvider` (pi-ai-compatible stream bridge → `LLMProvider`) | Use only if you already build on pi-ai-style streams; otherwise skip in **your** code | -| Safety helpers, protected paths (host registers paths) | Concrete device tools and deployment scripts | -| Default robotics/domain prompts from `@rdk-moss/core` (tunable via `DmossAgent` config) | Product-specific prompts wired in `server/dmoss/*` (host) | -| Goal Mode runtime: goal state, agent methods, prompt injection | CLI slash commands, UI controls, approval policy, background execution | -| Observability helpers for tracing, usage logging, and redaction via `@rdk-moss/agent/observability` | Host-owned telemetry pipeline and exporters | -| Mesh event bus and orchestration helpers via `@rdk-moss/agent/mesh` | Ad hoc text parsing for child runs and peer events | - -The open-source boundary is clean: `packages/dmoss/` + `packages/dmoss-agent/` in this monorepo are the stable public packages. Anything a host application builds on top (HTTP servers, desktop shells, SSH bridges, etc.) is the host's concern and not part of this package's public API. - -**Docs:** [`API.md`](./API.md) · [`CHANGELOG.md`](./CHANGELOG.md) - -### LLM integration: minimal path vs optional `pi-ai` - -- **What you must implement:** `LLMProvider` — the only contract `DmossAgent` needs to call a model. **For the smallest integration surface and full control over HTTP/SDKs**, implement it yourself (often with **`fetch()` only**; no Anthropic/OpenAI SDK required). See the `LLMProvider` section in [`API.md`](./API.md) for the interface and a minimal implementation pattern. -- **What is optional:** **`PiAiLLMProvider`** — a convenience adapter for hosts that already use pi-ai-compatible streaming. You do **not** need to use it to ship a product on `@rdk-moss/agent`. -- **npm note:** `@rdk-moss/agent` no longer installs the deprecated pi-ai package family. The adapter keeps local compatibility types, so new installs avoid the old transitive warning chain while hosts can still supply a compatible stream function. +> **Not just an LLM wrapper.** The harness owns the tool loop, context pruning/compaction, safety/approval hooks, session persistence, structured errors and retries, and pluggable `KnowledgeModule`s — so your application can focus on devices, UX, and policy. The stable public surface is `packages/dmoss/` + `packages/dmoss-agent/`; everything a host builds on top (HTTP servers, desktop shells, SSH bridges) stays outside this package's API. ## Install -Requires **Node >= 22.16**. - -### Use The CLI +Requires **Node ≥ 22.16**. ```bash -npm i -g @rdk-moss/agent@latest -moss -``` - -`moss` uses the built-in D-Robotics model gateway, so first use does **not** require a model API key or forced community login. Run `moss auth login` only when you want to link a D-Robotics developer community account. Run `moss setup` when you want your own provider, account, private gateway, or self-hosted OpenAI-compatible model. - -Each plain `moss` launch starts a **new saved conversation**. Continue previous history only when you ask for it: - -```bash -moss resume --last -moss resume --session -moss --session -``` - -### Embed The Runtime - -```bash -npm install @rdk-moss/agent@latest @rdk-moss/core@latest -``` - -Use this path when you are building a product host and want to supply your own UI, providers, tools, storage, approval gates, credentials, device access, and telemetry. - -## Five-Minute CLI Tutorial - -1. Start in a project: - - ```bash - cd my-project - moss - ``` - -2. Ask for orientation: - - ```text - Inspect this repo and tell me the build, test, and release path. - ``` - -3. Check active state: - - ```text - /status - /model - ``` - -4. Attach context: - - ```text - /attach ./screenshot.png - /attach ./error.log - What is the likely issue? - ``` - - In the full macOS TUI, copy a screenshot and press `Ctrl+V`; Moss attaches it as `[Image #1]` for the next prompt. - -5. Run a real task: - - ```text - Fix the failing test, explain the root cause, and run the narrowest verification. - ``` - -Interactive Moss asks before file writes, commands, and external actions unless you explicitly choose a more autonomous approval profile. - -## Honest Runtime Capabilities - -Each CLI run injects a compact runtime capability layer into the system prompt: - -- Registered tool names for this run, so the model can use real tool names instead of guessing. -- MCP and CodeGraph status based on the tools that actually registered. CodeGraph is only recommended when `codegraph_*` tools are present; otherwise Moss must report it as unavailable and use available fallbacks like `search_code`, `search_files`, `list_directory`, and `read_file`. -- An explicit 实事求是 behavior contract: separate verified facts, reasonable inferences, and unverified assumptions; say when evidence is missing; do not fill unknown gaps just to sound confident. - -## Skills - -Moss scans `SKILL.md` files from `.moss/skills/`, `.moss/agent/skills/`, legacy `skills/` and `agent/skills/`, and configured extra directories. Built-in skills cover methodical building, systematic debugging, test-driven changes, migration safety, and CodeGraph navigation when available. - -Moss can install a workspace skill through the `install_skill` tool. It writes `.moss/skills//SKILL.md`, refuses path traversal, does not overwrite by default, and is classified as a workspace write so normal approval rules apply. - -Example: - -```text -Install the workflow we just used as a reusable Moss skill named truth-check. +npm i -g @rdk-moss/agent@latest # CLI +# or +npm install @rdk-moss/agent@latest @rdk-moss/core@latest # embed ``` -## Use Your Own Model - -The built-in gateway is for immediate first use. Configure your own model when you need your own account, billing, private gateway, data-local deployment, or a self-hosted endpoint. Your local model config overrides the built-in gateway. - -Guided setup: +## Use The CLI ```bash -moss setup -moss auth status +moss # interactive TUI on the built-in gateway +moss "check disk usage" # one-shot +moss setup # configure your own provider / model / key ``` -Model settings (provider, model, baseUrl, API key) live in moss config only. Environment variables such as `DEEPSEEK_API_KEY`, `OPENAI_API_KEY`, or `DMOSS_PROVIDER` are deliberately ignored — a key exported for another tool never silently changes which provider Moss talks to. `moss doctor` lists any such leftover variables under `env ignored`. - -Private OpenAI-compatible gateway: +The full CLI guide — model setup, board connect, long-running tasks, automation, safety, and skills — lives in the [project README](../../README.md). The essentials: ```bash -moss config set provider openai-compatible -moss config set model -moss config set baseUrl https://llm.example.com -moss setup # stores the API key (hidden prompt) -moss auth status -moss +moss resume --last # continue the most recent saved session +moss --session work # continue or create a named session +moss doctor # health-check config, auth, workspace, board, MCP (non-zero exit on failure) +moss mcp add fs npx -y @modelcontextprotocol/server-filesystem /data ``` -For scripts and CI, provide a config file instead of env vars: `moss --config-file /path/to/config.json` (JSON with `provider` / `model` / `baseUrl` / `apiKey`). +`/connect ` puts a live session onto an RDK board over SSH (board mode: device + ROS2 tools), and `/disconnect` restores local tools. On an RDK board, teach Moss the whole stack with the [device-knowledge](https://github.com/D-Robotics/device-knowledge) skill pack — see [Give Moss RDK Board Skills](../../README.md#give-moss-rdk-board-skills). -`baseUrl` is the API root, not the full chat endpoint. Do not include `/chat/completions`. Both `https://llm.example.com` and `https://llm.example.com/v1` are accepted; Moss calls `/v1/chat/completions` for OpenAI-compatible providers. +Most-used in-session commands (type `/help` for all): -Configuration priority is: CLI flags and `-c key=value` > project `.moss/config.json` > `moss config` / `moss setup` > built-in gateway. - -Inside Moss, use `/model` to list models from the active provider when available, choose by number, or type `/model ` for a custom model. - -## Connect An RDK Board - -```text -/connect 192.168.1.10 --user root -/connect ubuntu@192.168.1.10 --port 2222 --key ~/.ssh/id_rsa -/connect 192.168.1.10 --password -/status -Check camera, ROS2 nodes, disk space, and device health. -``` - -`/connect` verifies SSH reachability and credentials before enabling device tools — if the probe fails, it reports why (unreachable host, wrong port, auth failure) and the tools stay disabled. Pass `--no-verify` to skip the probe and register tools anyway (e.g. for a board that is about to boot). Credentials default to `DMOSS_DEVICE_USER` / `DMOSS_DEVICE_PORT` / `DMOSS_DEVICE_KEY` / `DMOSS_DEVICE_PASSWORD` when flags are omitted; prefer `--key` or the env vars over typing `--password` so secrets stay out of the session transcript. - -After a verified connect the session enters **board mode**: the default tools (`exec`, `read_file`, `write_file`, `edit_file`, `list_directory`, `search_files`, `search_code`, `move_file`) operate on the board over SSH, so working in moss feels like running it on the board itself. Writes are atomic and byte-count verified. Leave board mode with `/disconnect` or Ctrl+D on an empty prompt — the local tools are restored exactly as they were. Pass `--hybrid` to keep the local tools and only add the `device_*`/`ros2_*` tools alongside (the pre-board-mode behavior). - -`/connect` is session-scoped and does not require restarting Moss. The host still owns SSH credentials, protected paths, approval policy, and the concrete device tools that are exposed. - -## Attach Images And Files - -```text -/attach ./screenshot.png -/attach ./camera-frame.jpg -/attach ./notes.txt -Explain what you see and propose the next debug step. ``` - -Images (`png`, `jpg`, `jpeg`, `gif`, `webp`) are sent as model image blocks when the active provider/model supports vision. Text files are inserted as prompt context. Use `/attach list` to review pending attachments and `/attach clear` to discard them before sending. - -## Useful CLI Commands - +/status /model model, workspace, device, and tool state · choose models +/connect /disconnect connect an RDK board and enter board mode · leave it +/sessions /resume list saved conversations · switch into one ([key|--last]) +/goal /compact /attach goal runner · compress history · attach an image/file +/mcp /doctor /diff /yolo MCP status · health-check · changes · full-power session ``` -moss open the interactive TUI -moss "prompt" run a one-shot prompt -moss auth login optional: link a D-Robotics developer community account -moss auth status show community login and provider/model/key source -moss setup configure your own provider/model/API key -moss doctor health-check config, auth, workspace, board, and MCP (non-zero exit on failure) -moss resume --last continue the most recent saved session (fork --last branches a copy) -moss mcp add [args...] register an MCP server without editing JSON (mcp list / mcp remove) -moss config --help show configuration commands -moss --help show the focused CLI help -moss --help --all show the complete CLI reference -``` - -Inside Moss: - -``` -/status view model, workspace, device, and tool state -/model list or choose active models -/goal show or manage the active goal runner -/compact compress older conversation history into a summary -/attach attach an image or text file to the next prompt -/connect connect an RDK board and enter board mode (/disconnect to leave) -/sessions list saved conversations (use /resume to switch into one) -/resume switch this session to a saved conversation ([key|--last]) -/mcp show configured MCP servers, status, and tool counts -/doctor health-check model, egress, board, MCP, and config in this session -/yolo grant full power for this session — no per-call approval (/yolo off reverts) -/diff show git working-tree changes -/auth login optional: link a D-Robotics developer community account -/help show focused command help -``` - -Advanced commands such as `/status --verbose`, `/context`, `/rewind`, `/tools`, `/permissions`, and `/memory` still work, but stay out of the default menu so the first screen remains usable. -### Custom Slash Commands +## Embed The Runtime -Define your own `/command` by dropping a Markdown file in either location (the -Claude Code / codex convention): - -- `.moss/commands/.md` — project commands, shareable via git -- `/commands/.md` — personal, available in every workspace - -The file body becomes the prompt when you run `/`. Optional frontmatter -sets a help description; `$ARGUMENTS` and `$1`..`$9` interpolate what you typed -after the command (bare args are appended when neither is referenced). - -```markdown ---- -description: Diagnose the connected board -argument-hint: [topic] ---- -Check the board's CPU, memory, temperature, and ROS2 topics. Focus on $1. -``` - -Then `/` shows up in the slash menu and `/help`, expands the body, and -runs it. A custom file can never shadow a built-in command — built-ins win. - -## Automation And Browser Tools - -```bash -DMOSS_CLI_AUTO_APPROVE=1 moss --workspace-write "write and verify the tool" -# or persist a broader local policy: -moss config set profile autonomous -``` - -`DMOSS_CLI_AUTO_APPROVE=1` only approves tools allowed by the active safety policy. It does not bypass `--read-only`, `deniedTools`, protected paths, or workspace sandbox checks. Browser workflows such as real checkout/add-to-cart testing use `web_browser_control`, which is an external interaction and needs `--full-access` plus approval. - -For long-running CLI work, `/goal ` starts an active goal runner. Moss keeps taking bounded turns until it can mark the goal completed, mark it blocked, you clear it with `/goal clear`, or you stop the run. Hidden tool-loop count limits are off by default; hosts or users can still opt into explicit budgets with `DMOSS_TOOL_LOOP_IDENTICAL_LIMIT`, `DMOSS_TOOL_LOOP_SINGLE_TOOL_LIMIT`, `DMOSS_TOOL_LOOP_TOTAL_LIMIT`, `DMOSS_TOOL_LOOP_FAILURE_LIMIT`, or per-call `maxToolCalls`. - -`@rdk-moss/agent` includes `web_browser_fetch` and `web_browser_control` through `puppeteer-core`. It does not download a browser at install time. If Chrome or Chromium is not auto-discovered, configure the executable: - -```bash -export DMOSS_BROWSER_EXECUTABLE="/path/to/chrome-or-chromium" -``` - -## Maintainer Tarball Smoke - -From the monorepo root: - -```bash -npm run smoke:moss-cli -``` - -The smoke script builds the workspace, packs the current `@rdk-moss/core`, `@rdk-moss/memory`, `@rdk-moss/skills`, and `@rdk-moss/agent` tarballs, installs them into a temporary project, checks the `moss` / `dmoss` / `dmoss-agent` bins, verifies packaged GIF and zero-config assets, blocks deprecated install warnings, and opens the TUI through a PTY when available. - -## From Source - -```bash -git clone -cd -npm install -npm run build -w @rdk-moss/agent -# A source checkout does not include the private npm zero-config gateway file. -# Configure your own model/provider, or set DMOSS_ZERO_CONFIG_DEFAULT_FILE for packaging tests. -node packages/dmoss-agent/dist/cli.js setup -node packages/dmoss-agent/dist/cli.js -node packages/dmoss-agent/dist/cli.js "check disk usage on /" -``` - -`setup` writes `~/.config/dmoss/config.json` with `0600` permissions and supports Aliyun/Qwen, OpenAI, Anthropic, and OpenAI-compatible providers. Your config overrides the built-in gateway. Config and keys can also come from environment variables, so secrets do not need to be written to disk. - -`apply_patch` accepts Moss' structured patch format, not a raw `git apply` unified diff. Multi-file patches are supported, but each operation must be inside the documented `*** Begin Patch` / `*** Add File` / `*** Update File` / `*** Delete File` / `*** End Patch` blocks. - -All flags also have env-var equivalents for logging and color control, including `DMOSS_LOG_LEVEL`, `DMOSS_LOG_JSON=1`, `DMOSS_NO_COLOR=1`, and `DMOSS_NO_UPDATE_CHECK=1`. - -## Embed Moss In A Host +Implement one interface — `LLMProvider` — and drive the agent. For the smallest surface and full control, implement it yourself with `fetch()` only (no Anthropic/OpenAI SDK required); `PiAiLLMProvider` is an optional convenience bridge for hosts already on pi-ai-style streams. ```typescript import { DmossAgent, InMemorySessionStore } from '@rdk-moss/agent'; -import type { LLMProvider, AgentHooks } from '@rdk-moss/agent'; +import type { LLMProvider } from '@rdk-moss/agent'; -// 1. Implement your LLM provider (Anthropic, OpenAI, etc.) -const myProvider: LLMProvider = { /* ... */ }; +const myProvider: LLMProvider = { /* call your model (fetch is enough) */ }; -// 2. Create the agent const agent = new DmossAgent({ llmProvider: myProvider, sessionStore: new InMemorySessionStore(), model: 'claude-sonnet-4-20250514', hooks: { - onBeforeToolExec: async (req) => ({ approved: true }), - onStream: (event) => console.log(event), + onBeforeToolExec: async (req) => ({ approved: true }), // your approval policy + onToolResult: (call, result) => auditLog(call, result), }, }); -// 3. Register knowledge for your hardware -import type { KnowledgeModule } from '@rdk-moss/core'; -const myKnowledge: KnowledgeModule = { /* ... */ }; -agent.registerKnowledge(myKnowledge); - -// 4. Register tools +// Register tools and hardware knowledge for your platform. agent.tools.register({ name: 'device_exec', description: 'Execute a command on the connected device', @@ -369,195 +91,77 @@ agent.tools.register({ execute: async (input) => { /* ... */ }, }); -// 5. Chat -const result = await agent.chat('session-1', 'Check the camera status', { - platform: 'my-board-v1', -}); +const result = await agent.chat('session-1', 'Check the camera status', { platform: 'my-board-v1' }); console.log(result.response); ``` -## Architecture - -``` -@rdk-moss/core → Contracts (KnowledgeModule, PlatformExtension, VendorPlugin, etc.) -@rdk-moss/agent → Runtime (this package) - ├── DmossAgent — Central orchestrator (chat loop, tool execution, hooks) - ├── ToolRegistry — Pluggable tool registration and discovery - ├── Knowledge Registry — Domain knowledge aggregation from all modules - ├── Extension System — Platform extension lifecycle management - ├── Safety — Secret sanitization, dangerous command detection - ├── Skills — SKILL.md scanning and matching - ├── Session — JSONL session persistence + in-memory option - ├── Goal Mode — Session-backed thread goals for prompt context - ├── Context — Pruning, compaction, token estimation - ├── Provider — Error classification, retry with exponential backoff - ├── Prompts — Robotics engineering prompts, telemetry - └── Utils — Stream smoother, trace logging, abort signals -``` - -## Public API - -### Core - -| Export | Type | Description | -|--------|------|-------------| -| `DmossAgent` | class | Central agent orchestrator | -| `ToolRegistry` | class | Register/discover/group tools | -| `InMemorySessionStore` | class | Built-in session store | -| `SkillRegistry` | class | SKILL.md scanner | - -### Interfaces (implement these in your host) - -| Interface | Description | -|-----------|-------------| -| `LLMProvider` | Abstract LLM interaction (Anthropic, OpenAI, etc.) | -| `SessionStore` | Session persistence (file, database, in-memory) | -| `AgentHooks` | Lifecycle hooks (approval, events, context enrichment) | - -### Types - -| Type | Description | -|------|-------------| -| `Tool` | Tool definition with inputSchema and execute | -| `ToolContext` | Execution context (workspace, session, abort) | -| `ToolCall` / `ToolResult` | Tool invocation and response | -| `LLMMessage` / `LLMContentBlock` | LLM message types | -| `ChannelSafetyResult` | Command safety check result | -| `SkillMeta` | Skill metadata | -| `GoalState` | Thread goal with objective, status, and timestamps | -| `GoalStatus` | Goal lifecycle status (`active`, `paused`, `completed`, `blocked`) | - -### Runtime capabilities - -| Capability | Description | -|------------|-------------| -| Goal Mode | `DmossAgent` can set, view, pause, resume, complete, block, and clear a session goal, then inject active or paused goal context into the system prompt | - -### Functions - -| Function | Description | -|----------|-------------| -| `registerKnowledgeModule()` | Register a hardware knowledge module | -| `findModuleForPlatform()` | Find knowledge for a specific platform | -| `getAllDeviceProfiles()` | Aggregate all device profiles | -| `buildRoboticsEngineeringPrompt()` | Generic robotics system prompt | -| `sanitizeSecrets()` | Mask API keys in text | -| `isCommandDangerous()` | Check shell commands for safety | - -## Streaming API - -For real-time UI integration, use `streamChat()` which yields events as they occur: +For real-time UIs, stream events instead: ```typescript for await (const event of agent.streamChat('session-1', 'Check camera')) { - switch (event.type) { - case 'text_delta': - process.stdout.write(event.delta); - break; - case 'tool_start': - console.log(`Running tool: ${event.toolName}`); - break; - case 'tool_end': - console.log(`Tool ${event.toolName}: ${event.isError ? 'FAILED' : 'OK'}`); - break; - case 'done': - console.log(`\nCompleted: ${event.result.toolCalls.length} tool calls`); - break; - } + if (event.type === 'text_delta') process.stdout.write(event.delta); + if (event.type === 'tool_start') console.log(`tool: ${event.toolName}`); + if (event.type === 'done') console.log(`\n${event.result.toolCalls.length} tool calls`); } ``` -## Hooks System - -```typescript -const hooks: AgentHooks = { - // Tool approval (block dangerous operations) - onBeforeToolExec: async (req) => { - if (isDangerous(req.input)) return { approved: false, reason: 'Blocked' }; - return { approved: true }; - }, - // Audit logging - onToolResult: (call, result) => auditLog(call, result), - // Raw provider stream telemetry. For product UI text, consume streamChat() events. - onStream: (event) => console.debug('provider stream', event.type), - // Error handling - onError: async (err, ctx) => isRetryable(err), - // Inject host-specific context - enrichToolContext: (ctx, key) => ({ ...ctx, deviceId: getDevice(key) }), -}; -``` - -## Goal Mode +### Key API surface -D-Moss provides **thread-level goal tracking** in the runtime and an active goal runner in the bundled CLI. The runtime stores one goal per session in the configured `SessionStore` and injects active or paused goal context into the system prompt during chat turns. The `moss` TUI builds on that state: `/goal ` schedules follow-up turns until the goal is completed, blocked, cleared, or stopped. +| Implement in your host | Purpose | +| --- | --- | +| `LLMProvider` | The only contract `DmossAgent` needs to call a model | +| `SessionStore` | Session persistence (file, database, in-memory) | +| `AgentHooks` | Lifecycle hooks: approval, audit, events, context enrichment | +| `KnowledgeModule` (`@rdk-moss/core`) | Device profiles, prompts, command patterns, and failure hints for a hardware platform | -For host integrations that want a thin command router, `@rdk-moss/agent/goal` exposes a stable `/goal` adapter with `isGoalCommand()`, `parseGoalCommand()`, `executeGoalCommand()`, and `handleGoalCommand()`. Results are structured, so hosts can echo `message` now and map `action`/`event` into UI or observability later. +| Use from the runtime | Purpose | +| --- | --- | +| `DmossAgent` | Central orchestrator: chat loop, tool execution, hooks, goal state | +| `ToolRegistry` | Register / discover / group tools | +| `InMemorySessionStore` | Built-in session store | +| `SkillRegistry` | `SKILL.md` scanner | -```typescript -// Host sets the goal; the runtime stores it in session state. -await agent.setGoal('session-1', 'Migrate CI pipeline to GitHub Actions'); +`DmossAgent` also tracks one **goal** per session (`setGoal` / `pauseGoal` / `completeGoal` / `blockGoal` / `clearGoal`) and injects it into the system prompt; the `moss` CLI builds its `/goal` runner on that state. Subpath entries `@rdk-moss/agent/goal`, `/observability`, and `/mesh` expose the goal adapter, tracing/redaction helpers, and the mesh event bus. -const goal = await agent.getGoal('session-1'); - -// Host controls the lifecycle. -await agent.pauseGoal('session-1', 'waiting for reviewer feedback'); -await agent.resumeGoal('session-1'); -await agent.completeGoal('session-1', 'verified in CI'); -// Or: await agent.blockGoal('session-1', 'blocked on missing credentials'); -await agent.clearGoal('session-1'); -``` +The full public surface — every type, event, and import recommendation — is documented in [`API.md`](./API.md), with extended patterns in [`USAGE.md`](./USAGE.md). -Goals are bound to the exact `sessionKey` passed in by the host. Subagents, mesh peer queries, and external channel sessions should use their own session keys unless the host explicitly wants goal inheritance. Hosts own product behavior around this API: routing, UI controls, approval workflows, and any background execution loop. The bundled CLI provides one such loop, while `DmossAgent` itself stores the goal and surfaces it to the model as runtime guidance. +## Honest Runtime Behavior -## Adding a New Hardware Platform +Each run injects a compact capability layer into the system prompt: the tool names actually registered for this run (so the model uses real tools, not guesses), MCP/CodeGraph status from what registered (CodeGraph is only recommended when `codegraph_*` tools are present), and a 实事求是 behavior contract — separate verified facts from inference and assumptions, say when evidence is missing, and never claim a result without a check behind it. -Implement the `KnowledgeModule` interface from `@rdk-moss/core` for your hardware platform. +## Configure Your Own Model -```typescript -import type { KnowledgeModule } from '@rdk-moss/core'; - -const jetsonKnowledge: KnowledgeModule = { - id: 'jetson', - name: 'NVIDIA Jetson', - version: '1.0.0', - description: 'Jetson developer kit knowledge', - platforms: ['jetson-nano', 'jetson-orin'], - getDeviceProfiles: () => ({ /* ... */ }), - getDocIndex: () => [], - getPromptFragments: () => [{ id: 'cuda-tips', /* ... */ }], - getCommandPatterns: () => [{ pattern: /tegrastats/i, /* ... */ }], - getFailureHints: () => [{ errorPattern: /CUDA out of memory/i, /* ... */ }], - getEcosystemPrompt: () => '## NVIDIA Jetson\n...', -}; - -agent.registerKnowledge(jetsonKnowledge); +```bash +moss config set provider openai-compatible +moss config set model +moss config set baseUrl https://llm.example.com # API root, not /chat/completions +moss setup # stores the key (hidden prompt) ``` -## Known Limitations +Supported: `deepseek`, `qwen`, `openai`, `anthropic`, `openai-compatible`. Settings live in moss config only — env vars like `OPENAI_API_KEY` / `DMOSS_PROVIDER` are deliberately ignored so a key exported for another tool never silently switches your provider (`moss doctor` lists leftovers). For scripts/CI, pass `moss --config-file /path/to/config.json`. Priority: CLI flags / `-c key=value` > project `.moss/config.json` > `moss config` > built-in gateway. -- **`LLMProvider` vs pi-ai-style streams:** The harness is built around **`LLMProvider`**. **`PiAiLLMProvider` is optional** — use it only if you want the pre-built compatibility bridge; otherwise prefer a **self-hosted `LLMProvider`** for minimal behavioral dependency (see [`API.md`](./API.md) for the interface). -- **Robotics prompt injected by default**: `DmossAgent.buildSystemPrompt()` includes the robotics engineering prompt from `@rdk-moss/core` unless opted out. Non-robotics hosts can set `domainPrompt: false` to skip it, or provide a custom `domainPrompt: () => string` to replace it with domain-specific guidance. -- **Vendor plugin callbacks**: new hosts should call `agent.extensions.setVendorPluginCallbacks()` before `agent.extensions.apply()` to keep vendor plugins scoped to one agent. Legacy hosts may still use the process-scoped `setVendorPluginCallbacks()` / `applyPlatformExtension()` wrappers during migration. -- **Publishing**: The Moss stack is prepared as publishable npm workspaces. Before a release, run `npm run verify` from the repo root; it covers OSS boundary checks, workspace hygiene, workspace builds, typechecks, and package tests. Use the release checklist for host consumption validation. +## From Source -## Documentation +```bash +git clone https://github.com/D-Robotics/moss && cd moss +npm install +npm run build -w @rdk-moss/agent +node packages/dmoss-agent/dist/cli.js # A source checkout omits the private zero-config gateway; run `setup` or set your own provider. +``` -- [API.md](./API.md) — stable public API surface, event model, and import recommendations -- [USAGE.md](./USAGE.md) — extended usage examples and host integration patterns -- [CONTRIBUTING.md](./CONTRIBUTING.md) — package-specific contribution guide -- [SECURITY.md](./SECURITY.md) — vulnerability reporting and security scope +Maintainers validate a release with `npm run verify` (OSS-boundary + hygiene checks, build, typecheck, lint, tests) and `npm run smoke:moss-cli` (packs the tarballs, installs into a temp project, and checks the bins and packaged assets). ## API Stability -The stable open-source surface of `@rdk-moss/agent` is the package export map defined in `package.json` and documented in [API.md](./API.md). - -Host-level routes and product integrations belong to the embedding application and should not be treated as the public API of this package. +The stable surface is the export map in `package.json`, documented in [`API.md`](./API.md). Host-level routes and product integrations belong to the embedding application, not this package's public API. Exports marked `/** @internal */` are implementation details — not semver-protected, and may change in any release. Prefer the documented surface in [`API.md`](./API.md). -### `@internal` symbols - -Some exports are marked with `/** @internal */` JSDoc comments. These are **implementation details** that are exported only for internal use within the `@rdk-moss/*` package family. They are **not part of the stable public API** and may change or be removed in any release (including patch releases) without notice or migration path. +## Documentation -If you depend on an `@internal` symbol, you are opting out of semver protections. Prefer the documented public API surface in [API.md](./API.md). +- [`API.md`](./API.md) — stable public API, event model, import recommendations +- [`USAGE.md`](./USAGE.md) — extended usage and host-integration patterns +- [`CONTRIBUTING.md`](./CONTRIBUTING.md) — package contribution guide +- [`SECURITY.md`](./SECURITY.md) — vulnerability reporting and security scope +- [`CHANGELOG.md`](./CHANGELOG.md) — release history ## License diff --git a/packages/dmoss-agent/README.zh-CN.md b/packages/dmoss-agent/README.zh-CN.md new file mode 100644 index 0000000..db3dfe6 --- /dev/null +++ b/packages/dmoss-agent/README.zh-CN.md @@ -0,0 +1,168 @@ +# @rdk-moss/agent + +[English](README.md) · **简体中文** + +> **Moss Agent 运行时。** 安装 `moss` 即可使用终端 Agent，或 `npm install` 把一个面向机器人的 Agent——工具循环、上下文治理、安全钩子、会话、可插拔知识——嵌入你自己的产品。 + +由 地瓜机器人 (D-Robotics) 打造。项目是 **Moss**；包是 **`@rdk-moss/agent`**；CLI 是 **`moss`**（`dmoss` 为兼容别名）。 + +

+ npm + node >= 22.16 + MIT + provider-agnostic +

+ +

+ Moss 终端启动演示 +

+ +这个包同时是两样东西： + +- **一个终端 Agent**——`npm i -g @rdk-moss/agent`，运行 `moss`，在内置 D-Robotics 网关上即刻开干（无需模型 Key、无需强制登录）。 +- **一个可嵌入运行时**——`npm install @rdk-moss/agent @rdk-moss/core`，然后用你自己的 服务商、工具、存储与审批策略驱动 `DmossAgent`。 + +> **不只是 LLM 包装。** 这套 harness 拥有工具循环、上下文裁剪/压缩、安全/审批钩子、会话持久化、结构化错误与重试，以及可插拔的 `KnowledgeModule`——让你的应用专注于设备、UX 与策略。稳定公开面是 `packages/dmoss/` + `packages/dmoss-agent/`；宿主在其上构建的一切（HTTP 服务、桌面外壳、SSH 桥接）都在本包 API 之外。 + +## 安装 + +需要 **Node ≥ 22.16**。 + +```bash +npm i -g @rdk-moss/agent@latest # CLI +# 或 +npm install @rdk-moss/agent@latest @rdk-moss/core@latest # 嵌入 +``` + +## 使用 CLI + +```bash +moss # 内置网关上的交互式 TUI +moss "看看磁盘占用" # 一次性 +moss setup # 配置自己的 服务商 / 模型 / Key +``` + +完整 CLI 指南——模型配置、连接开发板、长程任务、自动化、安全与技能——见[项目 README](../../README.zh-CN.md)。核心几条： + +```bash +moss resume --last # 继续最近一次已保存会话 +moss --session work # 继续或创建命名会话 +moss doctor # 体检配置、认证、工作区、开发板、MCP（失败时退出码非零） +moss mcp add fs npx -y @modelcontextprotocol/server-filesystem /data +``` + +`/connect ` 通过 SSH 把活动会话搬到 RDK 板上（板端模式：设备 + ROS2 工具），`/disconnect` 恢复本地工具。在 RDK 板上，用 [device-knowledge](https://github.com/D-Robotics/device-knowledge) 知识包把整套栈教给 Moss——见[给 Moss 装上 RDK 板端 Skill](../../README.zh-CN.md#给-moss-装上-rdk-板端-skill)。 + +最常用的会话内命令（输入 `/help` 查看全部）： + +``` +/status /model 模型、工作区、设备与工具状态 · 选择模型 +/connect /disconnect 连接 RDK 板并进入板端模式 · 退出 +/sessions /resume 列出已保存会话 · 切换进某个会话（[key|--last]） +/goal /compact /attach 目标运行器 · 压缩历史 · 附加图片/文件 +/mcp /doctor /diff /yolo MCP 状态 · 体检 · 改动 · 全权会话 +``` + +## 嵌入运行时 + +只需实现一个接口——`LLMProvider`——即可驱动 Agent。为了最小接口面与完全掌控，可只用 `fetch()` 自己实现（无需 Anthropic/OpenAI SDK）；`PiAiLLMProvider` 是给已使用 pi-ai 风格流的宿主的可选便利桥接。 + +```typescript +import { DmossAgent, InMemorySessionStore } from '@rdk-moss/agent'; +import type { LLMProvider } from '@rdk-moss/agent'; + +const myProvider: LLMProvider = { /* 调用你的模型（fetch 足矣） */ }; + +const agent = new DmossAgent({ + llmProvider: myProvider, + sessionStore: new InMemorySessionStore(), + model: 'claude-sonnet-4-20250514', + hooks: { + onBeforeToolExec: async (req) => ({ approved: true }), // 你的审批策略 + onToolResult: (call, result) => auditLog(call, result), + }, +}); + +// 为你的平台注册工具与硬件知识。 +agent.tools.register({ + name: 'device_exec', + description: 'Execute a command on the connected device', + inputSchema: { type: 'object', properties: { command: { type: 'string' } }, required: ['command'] }, + execute: async (input) => { /* ... */ }, +}); + +const result = await agent.chat('session-1', 'Check the camera status', { platform: 'my-board-v1' }); +console.log(result.response); +``` + +实时 UI 则改用流式事件： + +```typescript +for await (const event of agent.streamChat('session-1', 'Check camera')) { + if (event.type === 'text_delta') process.stdout.write(event.delta); + if (event.type === 'tool_start') console.log(`tool: ${event.toolName}`); + if (event.type === 'done') console.log(`\n${event.result.toolCalls.length} tool calls`); +} +``` + +### 核心 API 面 + +| 在宿主中实现 | 作用 | +| --- | --- | +| `LLMProvider` | `DmossAgent` 调用模型唯一需要的契约 | +| `SessionStore` | 会话持久化（文件、数据库、内存） | +| `AgentHooks` | 生命周期钩子：审批、审计、事件、上下文增强 | +| `KnowledgeModule`（`@rdk-moss/core`） | 某硬件平台的设备画像、提示词、命令模式与故障提示 | + +| 从运行时取用 | 作用 | +| --- | --- | +| `DmossAgent` | 中枢编排器：对话循环、工具执行、钩子、目标状态 | +| `ToolRegistry` | 注册 / 发现 / 分组工具 | +| `InMemorySessionStore` | 内置会话存储 | +| `SkillRegistry` | `SKILL.md` 扫描器 | + +`DmossAgent` 还为每个会话跟踪一个**目标**（`setGoal` / `pauseGoal` / `completeGoal` / `blockGoal` / `clearGoal`）并注入系统提示；`moss` CLI 的 `/goal` 运行器就建立在该状态上。子路径 `@rdk-moss/agent/goal`、`/observability`、`/mesh` 分别暴露目标适配器、追踪/脱敏辅助与 mesh 事件总线。 + +完整公开面——每个类型、事件与导入建议——见 [`API.md`](./API.md)，扩展用法见 [`USAGE.md`](./USAGE.md)。 + +## 诚实的运行时行为 + +每次运行都会向系统提示注入一层精简的能力声明：本次实际注册的工具名（让模型用真实工具而非猜测）、按实际注册情况得出的 MCP/CodeGraph 状态（仅当存在 `codegraph_*` 工具时才推荐 CodeGraph），以及一份实事求是的行为契约——区分已验证事实、推断与假设，证据缺失时如实说明，绝不在没有检查支撑时声称结果。 + +## 配置你自己的模型 + +```bash +moss config set provider openai-compatible +moss config set model <你的模型> +moss config set baseUrl https://llm.example.com # API 根地址，不要带 /chat/completions +moss setup # 存储 Key（隐藏输入） +``` + +支持：`deepseek`、`qwen`、`openai`、`anthropic`、`openai-compatible`。设置只存在 moss 配置里——`OPENAI_API_KEY` / `DMOSS_PROVIDER` 等环境变量被刻意忽略，这样为别的工具导出的 Key 不会悄悄切换你的服务商（`moss doctor` 会列出残留）。脚本/CI 用 `moss --config-file /path/to/config.json`。优先级：CLI 参数 / `-c key=value` > 项目 `.moss/config.json` > `moss config` > 内置网关。 + +## 从源码运行 + +```bash +git clone https://github.com/D-Robotics/moss && cd moss +npm install +npm run build -w @rdk-moss/agent +node packages/dmoss-agent/dist/cli.js # 源码 checkout 不含私有的零配置网关文件；请运行 `setup` 或设置自己的服务商。 +``` + +维护者用 `npm run verify`（OSS 边界 + 卫生检查、构建、类型检查、lint、测试）与 `npm run smoke:moss-cli`（打包 tarball、装入临时项目、检查 bin 与打包资源）验证发布。 + +## API 稳定性 + +稳定面是 `package.json` 的导出映射，记录于 [`API.md`](./API.md)。宿主级路由与产品集成属于嵌入应用，不属于本包公开 API。标注 `/** @internal */` 的导出是实现细节——不受 semver 保护，任意版本都可能变更。请优先使用 [`API.md`](./API.md) 中记录的接口面。 + +## 文档 + +- [`API.md`](./API.md) —— 稳定公开 API、事件模型、导入建议 +- [`USAGE.md`](./USAGE.md) —— 扩展用法与宿主集成模式 +- [`CONTRIBUTING.md`](./CONTRIBUTING.md) —— 本包贡献指南 +- [`SECURITY.md`](./SECURITY.md) —— 漏洞报告与安全范围 +- [`CHANGELOG.md`](./CHANGELOG.md) —— 发布历史 + +## 许可证 + +[MIT](./LICENSE) diff --git a/packages/dmoss-agent/package.json b/packages/dmoss-agent/package.json index 1ba2eaa..5d67848 100644 --- a/packages/dmoss-agent/package.json +++ b/packages/dmoss-agent/package.json @@ -101,6 +101,7 @@ "src", "zero-config-default.json", "README.md", + "README.zh-CN.md", "USAGE.md", "API.md", "CONTRIBUTING.md",