安装 DitingAgent，
接入宿主 Agent。 Install DitingAgent
and connect a host agent.

前置条件Requirements

Windows、macOS 和 Linux 都使用同一条 npx 命令；不需要全局安装。Windows, macOS, and Linux use the same npx entry; no global install is needed.

运行 npx 入口Run the npx entry

npx diting-agents@latest --version 首次会创建 Python 环境并安装运行依赖；不需要克隆仓库。 npx diting-agents@latest --version creates a Python environment and installs the runtime dependencies on first use. No repository clone is required.

npx diting-agents@latest --version

注册到 宿主Register with an host

setup --detect 先列出本机检测到的宿主，再选择对应客户端写入配置。支持 dsh、codex、claude_code、cursor、qwen_code、opencode、kimi、qoder、zcode、trae；--client generic 可输出 JSON。 setup --detect lists detected hosts, then writes the matching client config. Supported clients include dsh, codex, claude_code, cursor, qwen_code, opencode, kimi, qoder, zcode, and trae; --client generic prints JSON.

# detect hosts, then register the matching client
npx diting-agents@latest setup --detect
npx diting-agents@latest setup --client dsh --yes --allow-root ~/traces

# multiple hosts, or a generic JSON config
npx diting-agents@latest setup --client dsh --client codex --yes
npx diting-agents@latest setup --client generic

写入后重启宿主或重载宿主插件。移除托管块使用 setup --client dsh --uninstall --yes，其他配置保持不变。Restart the host or reload the host plugin after writing. Remove the managed block with setup --client dsh --uninstall --yes; other config is left unchanged.

可选：运行 npx diting-agents@latest install-skills --yes，把场景方法论和工作流 Skill 安装到共享的 ~/.agents/skills。Optional: run npx diting-agents@latest install-skills --yes to install scenario methodology and workflow skills into the shared ~/.agents/skills.

健康检查Health check

doctor 是只读检查，验证 Node.js/Python、运行依赖、启动命令、托管配置、技能安装和工作目录。需要设备时把 hdc 路径一起传入。 doctor is read-only and checks Node.js/Python, the runtime dependency, launcher, managed config, skill installation, and workspace. Pass the hdc path when using device tools.

npx diting-agents@latest doctor
npx diting-agents@latest doctor --json

# with a device
npx diting-agents@latest doctor --hdc /path/to/hdc

调试启动（可选）Debug start (optional)

日常分析由宿主自动启动 server。只有在调试连接或自定义客户端时，才需要手动运行 stdio server；指定 workspace 和可读取的 Trace 根目录。 The host starts the server automatically for normal analysis. Use a manual stdio server only for connection debugging or a custom client; specify a workspace and readable trace roots.

npx diting-agents@latest mcp \
  --workspace .diting/sessions \
  --allow-root ~/traces

--allow-root 限制 open_trace 可读取的目录；省略表示不限制。单次结果默认内联 64KB，超出后保留 Evidence ID。--allow-root limits directories that open_trace can read; omitting it leaves the path unrestricted. Inline results default to 64KB; larger results stay available by Evidence ID.

设备与构建工具Device and build tools

设备与构建工具默认关闭，需要 --enable-device；共 18 个工具。先检查或安装 Command Line Tools ↗，再注册带 hdc 的设备配置。开启后 Agent 可以构建、签名、安装并启动应用，再抓 Trace；act 和 install_app 会真实修改设备。 Device and build tools are off by default and require --enable-device. Check or install Command Line Tools ↗, then register a device-enabled config. Once enabled, the agent can build, sign, install, and launch the app before capturing a trace; act and install_app really change the device.

npx diting-agents@latest env status
npx diting-agents@latest env install \
  --archive ~/Downloads/commandline-tools.zip --yes

npx diting-agents@latest setup --client dsh \
  --device --hdc /path/to/hdc --yes
npx diting-agents@latest doctor --hdc /path/to/hdc

npx diting-agents@latest mcp \
  --workspace .diting/sessions \
  --allow-root ~/traces \
  --enable-device --hdc /path/to/hdc

build_app/package_app 需要 hvigorw 与 Java；sign_app 需要 keystore、证书和 profile；install_environment 的 URL 安装必须提供 SHA-256。设备动作会修改设备状态。详细约束见 工具页 和 权限边界。build_app/package_app need hvigorw and Java; sign_app needs a keystore, certificate, and profile; install_environment URL installs require a SHA-256. Device actions change device state. See the tools page and integration boundaries for details.