duoduo-admin

Duoduo Admin

Use this skill as the host-mode entrypoint for users who do not yet have a clear mental model of duoduo.

Start With Discovery

1. Confirm the daemon is up with duoduo daemon status.
2. Read duoduo daemon config before making persistent changes. Treat that output as the source of truth for paths and active settings.
3. If the daemon is down, start there. If the machine is not onboarded yet, explain that the user must finish duoduo onboarding first.
4. If the user says something is broken, first decide whether it is local misconfiguration, operator error, channel/plugin setup error, or a likely duoduo product bug.

Explain Duoduo In Host-Mode Terms

Keep the explanation concrete and filesystem-first.

• stdio is the default direct operator surface after onboarding.
• duoduo daemon ... manages the long-lived runtime process.
• duoduo channel ... manages installable external channel plugins.
• ~/.config/duoduo/.env is the persistent host-mode settings file.
• kernel/config/<kind>.md stores per-channel-kind defaults and kind prompts.
• var/channels/<channel_id>/descriptor.md stores per-channel-instance overrides and instance prompts.
• The host daemon is a detached background process. Updating package files alone does not replace the running process.
• Re-opening duoduo from the same real workspace path re-attaches the same stdio session key instead of creating a brand-new conversation surface.

Read references/host-mode-map.md when the user needs a fuller explanation of how these surfaces fit together.

Upgrade And Restart

"Is there an update?" → check both:

duoduo --version
npm view @openduo/duoduo version

If duoduo --version exits with a daemon WebSocket error instead of printing a version, the answer is yes: that failure is a bug in every build up to and including v0.8.1, and upgrading fixes it. Take the installed version from duoduo daemon status meanwhile — it reports the same number and does not go through the path that fails.

Standard upgrade path (works for minor bumps within the same major):

npm install -g @openduo/duoduo@latest
duoduo daemon restart -r "upgraded @openduo/duoduo to <version>"

Newer builds collapse both steps into one command that also installs into the prefix owning the running binary (which a bare npm install -g may not), supplies the restart reason itself, and health-checks the new daemon:

duoduo upgrade [version] [--wake <session-or-alias>]

Check availability from the CLI itself rather than from a version number — duoduo --help lists --wake on the upgrade line exactly when this behavior is present. Older builds have a duoduo upgrade that takes only a version and does none of the above; on those, use the two-command form.

The restart matters because the daemon is a detached background process — installing a newer CLI package does not hot-swap it.

These skills are not part of the upgrade. They ship from the GitHub repo, not the npm package, so both upgrade paths leave them untouched and you are left operating a new CLI from old instructions. Whenever the version changes, offer to refresh them:

npx -y skills add https://github.com/openduo/duoduo --global --all

Offer — do not do it silently. See references/upgrade-playbook.md for the non-interactive/SSH caveats.

The -r reason is delivered to every session woken after the restart. Without it, a session whose turn the restart cut off has no way to know why its conversation stopped mid-sentence, and will typically conclude a person interrupted it. If a session was waiting on an answer, add --wake <session-or-alias> (repeatable) — it will not resume on its own. This holds even when the caller is a session inside the daemon being restarted: the wake is carried by the restart itself, so it survives the caller's own process dying with the old daemon.

Crossing major boundaries (including v0.5)

When the upgrade crosses a behavioral boundary (v0.5 added Feishu main-session semantics and a new trust model for DMs), follow the full playbook instead of the one-liner above:

Read references/upgrade-playbook.md.

To collect the facts the playbook branches on, run the preflight:

bash scripts/v05-upgrade-preflight.sh

The script outputs markdown listing the installed version, daemon status, channel inventory, Feishu env keys, and descriptor shapes, then recommends one of Branch B / C / D. It is an accelerator, not a required path: if the script fails to run or the environment is unusual, the playbook's Step 1 fallback enumerates every probe the script performs as an individual command so the agent can reproduce it by hand.

Automation surfaces you should know about

These surfaces matter when agents and automation talk to duoduo; bare duoduo interactive use works without any of them.

• duoduo onboard: dedicated subcommand that runs the wizard and exits (never drops into the chat REPL). This is the correct entrypoint for any automation or agent call. In non-TTY contexts it reads its answers from env vars (at minimum ALADUO_RUNTIME_MODE, ALADUO_CLAUDE_AUTH_SOURCE) instead of prompting. If those are missing, it exits with code 2 and prints the full env-var recipe on stderr — forward that recipe to the caller rather than guessing.
• DUODUO_NODE_BIN env: when set, the duoduo bash wrapper uses that absolute path instead of resolving node via PATH. Use this when a caller environment resets PATH (bash -lc in agent spawn, GUI managers shipping a private Node runtime, etc.). See openduo/duoduo#50 for the full rationale.
• User-visible drain errors: when the daemon's internal SDK turn fails (most commonly: third-party compatible endpoints that don't accept Claude Code's current wire schema), the user sees a text reply prefixed with [duoduo:drain-error] instead of silence. The message carries the original error and suggests DISABLE_ADAPTIVE=1 DISABLE_THINKING=1 DISABLE_INTERLEAVED_THINKING=1 MAX_THINKING_TOKENS=0 in ~/.config/duoduo/.env as the common workaround.
• duoduo session archive <session_key>: archives every durable artifact of one session in one call (session dir, ingress snapshots, outbox records, channel descriptor). "Archive" literally — nothing is deleted, everything moves to var/<kind>-archive/ where the operator can mv it back. Refuses when the target has a live actor; cancel it first via /cancel. This is the right tool when the dashboard shows a session that should no longer exist (e.g. after a channel reset) or when you want a clean slate for one specific session without touching the rest of the runtime. The reset-feishu-session.sh script in duoduo-channel-admin drives this CLI; read that script as a worked example if you need to batch-archive per channel.
• Runtime selection: Claude, Codex, Grok, and Pi are peer runtimes. Claude is the default when no runtime is declared; a declared runtime duoduo does not know is refused, not replaced by a fallback. Codex and Grok (runtime: codex|grok, or ALADUO_DEFAULT_RUNTIME) have no silent Claude fallback — install the CLI and log in; an unavailable runtime refuses the turn, and sending the message again after fixing it is enough. Pi ships inside duoduo (nothing to install, always available) with the same no-silent-fallback posture: every pi session needs a model pointer (provider/modelId via job frontmatter, /model, or partition frontmatter) and fails actionably without one. Use ALADUO_DEFAULT_RUNTIME=codex, =grok, or =pi only for an intentional global default change. A session is bound to the runtime that owns its conversation: changing only the runtime refuses the session's next turn. Switch with /clear first, then the runtime change — see "Switching a session's runtime" in duoduo-runtime-admin.
• Stdio output buffering: the terminal UI buffers assistant text more cleanly so status/tool rendering does not interleave as visibly with assistant prose. Treat this as a UX fix, not a protocol change.

Find Problems And Escalate

When the user is reporting a bug or unexpected behavior:

1. Reproduce or at least restate the exact symptom.
2. Inspect the live state with the smallest useful commands, usually duoduo daemon status, duoduo daemon config, duoduo daemon logs, and any relevant duoduo channel ... status/logs.
3. Separate local setup mistakes from probable product defects.
4. If it looks like a duoduo bug or docs gap, prepare a public-safe issue summary for openduo/duoduo.

Read references/issue-reporting.md when the user wants to file an issue or asks you to prepare one.

Route The Request

• Channel installation, channel lifecycle, Feishu setup, or channel prompt/workspace changes: read ../duoduo-channel-admin/SKILL.md and let that workflow own the implementation.
• Runtime flags such as Codex, debug logs, telemetry, cadence, or daemon diagnostics: read ../duoduo-runtime-admin/SKILL.md and let that workflow own the implementation.
• Confirmed bug report or docs gap that should be escalated publicly: use references/issue-reporting.md.
• Mixed or vague requests: explain the mechanism first, then move into the smallest concrete change.

Operating Rules

• Prefer live inspection over defaults. Use the actual daemon config, actual files, and actual channel list before claiming how the system is set up.
• After editing ~/.config/duoduo/.env, tell the user to run duoduo daemon restart -r "changed <setting>" unless they explicitly asked for an edit-only change. Never suggest a bare restart — the reason is what tells the interrupted sessions what happened to them.
• When the user asks to "understand duoduo", answer in terms of files, commands, and lifecycle rather than abstract architecture jargon.
• Do not pretend a raw Git repository can be installed as a channel plugin. Duoduo's channel installer accepts npm package specs (no flag) or local .tgz tarballs (which require the explicit --from-path flag).