duoduo-admin

Duoduo 管理

对于尚未对 duoduo 建立清晰认知的用户，请将此技能作为主机模式的入口点。

从探索开始

1. 使用 duoduo daemon status 确认守护进程正在运行。
2. 进行持久性更改前，先读取 duoduo daemon config。将该输出视为路径和当前设置的准确信息来源。
3. 如果守护进程未运行，请从这里开始处理。如果机器尚未完成初始化，请说明用户必须先完成 duoduo 初始化。
4. 如果用户表示某项功能无法正常运行，先判断问题属于本地配置错误、操作失误、渠道／插件设置错误，还是可能的 duoduo 产品缺陷。

用主机模式的术语解释 Duoduo

说明要具体，并以文件系统为先。

• 初始化后，stdio 是默认的直接操作界面。
• duoduo daemon ... 用于管理长期运行的运行时进程。
• duoduo channel ... 用于管理可安装的外部渠道插件。
• ~/.config/duoduo/.env 是持久化的主机模式设置文件。
• kernel/config/<kind>.md 存储每种渠道类型的默认设置和提示词。
• var/channels/<channel_id>/descriptor.md 存储每个渠道实例的覆盖设置和实例提示词。
• 主机守护进程是脱离终端运行的后台进程。仅更新软件包文件不会替换正在运行的进程。
• 从同一个实际工作区路径重新打开 duoduo，会重新连接到同一个 stdio 会话密钥，而不是创建全新的对话界面。

如果用户需要更全面地了解这些界面如何协同工作，请阅读 references/host-mode-map.md。

升级和重启

“有更新吗？”→检查以下两项：

duoduo --version
npm view @openduo/duoduo version

如果 duoduo --version 没有打印版本，而是因守护进程 WebSocket 错误退出，那么答案是有更新：截至 v0.8.1（含）在内的所有构建版本都有此缺陷，升级即可修复。同时，从 duoduo daemon status 获取已安装的版本——它会报告相同的版本号，而且不会经过出错的路径。

标准升级方式（适用于同一主版本内的小版本升级）：

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

较新的构建版本可将这两个步骤合并为一个命令；该命令还会安装到正在运行的二进制文件所属的前缀中（单独运行 npm install -g 可能无法做到这一点）、自行提供重启原因，并对新守护进程执行健康检查：

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

应通过 CLI 本身检查是否支持，而不是根据版本号判断——当存在此功能时，duoduo --help 会在升级命令行中列出 --wake。旧版本的 duoduo upgrade 只接受版本号，且不具备上述功能；此时请使用两条命令的形式。

重启很重要，因为守护进程是脱离终端运行的后台进程——安装较新的 CLI 软件包不会热切换守护进程。

**这些技能不属于升级内容。**它们来自 GitHub 仓库，而非 npm 软件包，因此两种升级方式都不会更新这些技能，升级后你仍会用旧说明操作新 CLI。每当版本发生变化时，请主动提出刷新这些技能：

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

请先征求同意，不要静默执行。关于非交互式环境和 SSH 的注意事项，请参阅 references/upgrade-playbook.md。

重启后，-r 参数指定的原因会发送给每个被唤醒的会话。如果没有该参数，轮次被重启中断的会话就无法知道对话为何会在句中停止，通常会认为是有人打断了它。如果某个会话正在等待回答，请添加 --wake <session-or-alias>（可重复使用）——该会话不会自行恢复。即使调用方是即将重启的守护进程内部的会话，也同样如此：唤醒请求由重启操作本身携带，因此即使调用方进程随旧守护进程一起终止，唤醒请求仍会保留。

跨越重大边界（包括 v0.5）

当升级跨越行为边界时（v0.5 新增了飞书主会话语义和 DM 的新信任模型），请遵循完整的操作手册，而不是上面的单行命令：

阅读 references/upgrade-playbook.md。

若要收集操作手册分支判断所需的信息，请运行预检：

bash scripts/v05-upgrade-preflight.sh

该脚本会输出 Markdown，列出已安装的版本、守护进程状态、频道清单、飞书环境变量键和描述符形状，然后建议采用分支 B / C / D 之一。它是加速工具，并非必经步骤：如果脚本无法运行，或环境情况特殊，操作手册的步骤 1 后备方案会逐一列出脚本执行的所有探测命令，供 Agent 手动重现。

你应该了解的自动化接口

当 Agent 和自动化程序与 duoduo 交互时，这些接口很重要； 直接交互使用 duoduo 则无需任何接口。

• duoduo onboard：专用子命令，用于运行向导 并退出（不会进入聊天 REPL）。这是任何自动化程序或 Agent 调用时的正确 入口点。在非 TTY 环境中，它会从环境变量读取答案（至少需要 ALADUO_RUNTIME_MODE、ALADUO_CLAUDE_AUTH_SOURCE），而不是 提示用户输入。如果缺少这些变量，它会以代码 2 退出，并在 stderr 上打印完整的环境变量配置说明—— 将该说明转发给调用方，而不要自行猜测。
• DUODUO_NODE_BIN 环境变量：设置后，duoduo bash 包装器 会使用该绝对路径，而不是通过 PATH 查找 node。 当调用方环境会重置 PATH 时，请使用此变量（例如 Agent 启动时的 bash -lc，或自带私有 Node 运行时的 GUI 管理器）。 完整原因请参阅 openduo/duoduo#50。
• 用户可见的排空错误：当守护进程的内部 SDK 轮次失败时（最常见的情况是：第三方兼容端点 不接受 Claude Code 当前的线路格式），用户会看到一条以 [duoduo:drain-error] 为前缀的文本回复， 而不是一片沉默。该消息包含原始错误，并建议将 DISABLE_ADAPTIVE=1 DISABLE_THINKING=1 DISABLE_INTERLEAVED_THINKING=1 MAX_THINKING_TOKENS=0 写入 ~/.config/duoduo/.env，作为常见解决方法。
• duoduo session archive <session_key>：一次调用即可归档某个会话的所有 持久化产物 （会话目录、入口快照、发件箱记录、通道描述符）。“归档”是字面意义上的归档——不会删除任何内容，所有内容 都会移至 var/<kind>-archive/，操作员可以将其 mv 回来。 如果目标会话有正在运行的 Agent，则会拒绝执行；请先通过 /cancel 取消。 当仪表板显示某个本不应再存在的会话时（例如通道重置后），或者你想只为某个特定会话 重置环境而不影响运行时的其余部分时，应使用此工具。 duoduo-channel-admin 中的 reset-feishu-session.sh 脚本会调用此 CLI；如果需要按通道批量归档， 可将该脚本作为示例阅读。
• 运行时选择：Claude、Codex、Grok 和 Pi 是并列的 运行时。未声明运行时时，默认使用 Claude；如果声明了 duoduo 不认识的运行时，则会拒绝执行，不会改用备用运行时。Codex 和 Grok（runtime: codex|grok，或 ALADUO_DEFAULT_RUNTIME）不会静默回退到 Claude——请安装 CLI 并登录；如果运行时不可用，系统会拒绝执行该轮；修复后重新发送消息 即可。Pi 随 duoduo 一同提供（无需安装，始终可用），同样不会静默回退： 每个 pi 会话都需要一个模型指针（通过作业 frontmatter、/model 或分区 frontmatter 指定 provider/modelId），若缺少模型指针，则会给出可采取措施的错误。 仅在有意更改全局默认值时，才使用 ALADUO_DEFAULT_RUNTIME=codex、=grok 或 =pi。会话绑定到拥有其对话的运行时：仅更改运行时会导致会话的下一轮被拒绝。请先使用 /clear，再更改运行时——参阅 duoduo-runtime-admin 中的“切换会话的运行时”。
• Stdio 输出缓冲：终端 UI 会更妥善地缓冲助手文本，因此状态和工具的渲染不会那么明显地与助手文本交错。请将其视为 UX 修复，而非协议更改。

查找问题并升级处理

当用户报告错误或异常行为时：

1. 重现问题，或至少准确复述症状。
2. 使用尽可能少但足以解决问题的命令检查实时状态，通常包括 duoduo daemon status、duoduo daemon config、duoduo daemon logs，以及 相关的 duoduo channel ... status/logs。
3. 区分本地配置错误和可能的产品缺陷。
4. 如果看起来是 duoduo 的错误或文档缺漏，准备一份可公开发布的问题摘要，提交到 openduo/duoduo。

如果用户想提交问题或让你准备问题报告，请阅读 references/issue-reporting.md。

路由请求

• 安装频道、管理频道生命周期、配置飞书，或更改频道提示词／工作区： 阅读 ../duoduo-channel-admin/SKILL.md， 并由该工作流负责具体实施。
• 运行时标志，例如 Codex、调试日志、遥测、运行频率或守护进程诊断： 阅读 ../duoduo-runtime-admin/SKILL.md， 并由该工作流负责具体实施。
• 已确认、应公开升级处理的错误报告或文档缺漏： 使用 references/issue-reporting.md。
• 混合或含糊的请求： 先解释机制，再进行范围最小的具体更改。

操作规则

• 优先检查实时状态，而非依赖默认值。断言系统的配置情况前，先查看实际的守护进程配置、实际文件和实际频道列表。
• 编辑 ~/.config/duoduo/.env 后，告知用户运行 duoduo daemon restart -r "changed <setting>"，除非用户明确要求只编辑、不重启。切勿建议直接运行 restart——说明原因才能让被中断的会话知道发生了什么。
• 用户要求“了解 duoduo”时，请从文件、命令和生命周期的角度作答，而非使用抽象的架构术语。
• 不要声称可以将原始 Git 仓库安装为频道插件。Duoduo 的频道安装程序接受 npm 包规格（无需标志）或本地 .tgz 压缩包（需要显式使用 --from-path 标志）。