DitingAgent

DitingAgent 是一个鸿蒙性能 Trace 分析 MCP server。它不内置模型，也不运行自己的 Agent；模型、推理循环和工具选择由宿主 Agent（DeepSeek Harness、Claude Code、Codex 等）提供，DitingAgent 负责：

• 把 HTrace 转成可查询的 SQLite；
• 通过 MCP 暴露有界、只读的取证工具；
• 用确定性规则校验宿主提交的分析结论；
• 渲染可追溯的 HTML 报告；
• 导出/导入/比较 Evidence bundle；
• 在授权时抓取设备 Trace 和执行 UI 动作。

Host Agent (model + loop)
        │  MCP stdio
        ▼
DitingAgent
  ├─ session / evidence / bundle
  ├─ session / evidence / unknown / lease / handoff
  ├─ provider registry: auto / htrace / perf-data
  ├─ HTrace → Trace Streamer → SQLite
  ├─ deterministic preflight / validation / report
  └─ hdc / hiprofiler / UI actions

安装

uv sync --extra mcp

只需要 MCP 依赖；不需要任何模型 API Key 或内置 Agent 配置。

快速开始

npx

# 首次运行会在 ~/.cache/diting-agent/venv 创建 Python 环境
npx diting-agents --version

# 先看计划；终端里会要求确认，确认后自动验证
npx diting-agents@latest setup --client dsh

# CI/非交互
npx diting-agents setup --client dsh --yes

# 直接启动 MCP
npx diting-agents mcp --workspace .diting/sessions --enable-device

要求 Node.js 18+、Python 3.12+。可用环境变量覆盖：

DITING_AGENT_HOME   npx 缓存/venv 根目录
DITING_PYTHON       指定 Python 3.12+ 解释器
DITING_UV           指定 uv（优先于 pip）
DITING_AGENT_BIN    直接指定已安装的 diting-agent

包没有强制 postinstall；首次执行时才创建环境。当前仓库可用 npx --package . diting-agents ... 验证本地包。

更新与版本

# 检查 npm latest 和本地版本
diting-agent update --check

# 执行更新（repo 模式使用 git pull + uv sync）
diting-agent update --yes

npx 首次执行会优先使用 Python 3.12+/uv；没有系统 Python 时，如果 uv 可用，会用 uv 创建 Python 3.12 环境。Windows 还会尝试 py -3.13 / py -3.12。缓存的 venv 带 npm 包版本标记，升级包后会自动重建。

仓库内四条版本号必须一致：

python3 scripts/check_versions.py

注册到宿主

# DeepSeek Harness：写用户级 ~/.dsh/cordis.patch.yml 的托管块
diting-agent setup --client dsh

# 同时启用设备工具（需要 hdc）
diting-agent setup --client dsh \
  --device \
  --hdc /path/to/hdc

# 不传 --client：自动选择已注册客户端；没有则选择已检测客户端
diting-agent setup --detect
diting-agent setup
diting-agent setup --client dsh --client codex --client qwen_code --yes
diting-agent setup --client all --yes

# setup 默认同时安装匹配 skills；也可单独安装共享 skills
# diting-agent setup --client dsh --yes
diting-agent install-skills

# 生成 MCP tool catalog（可提交/对比）
diting-agent catalog --device --output mcp-catalog-device.json
diting-agent catalog --schema-profile compact --output mcp-catalog-compact.json

setup 默认会同时把捆绑 skills 安装到共享 ~/.agents/skills， 并为选中的客户端安装到各自的 skills 目录（Codex、Claude Code、Cursor、 Qwen Code、OpenCode、Kimi、Qoder、ZCode、Trae）； --no-skills 可关闭，--force-skills 可覆盖冲突。

重载宿主 MCP 后即可使用。

直接启动 MCP server

diting-agent mcp \
  --workspace .diting/sessions \
  --enable-device \
  --hdc /path/to/hdc

健康检查

diting-agent doctor
diting-agent doctor --json

MCP 工具面

默认 37 个工具；加 --enable-device 后 55 个。

类别	工具
会话	open_trace、close_trace、list_traces
分析	begin_analysis、submit_analysis_result、render_report
证据	list_evidence、get_evidence
bundle	export_bundle、import_bundle、compare_bundles
unknown	record_unknown、update_unknown、list_unknowns、verify_unknown
handoff	snapshot_session、resume_session、load_handoff
Trace 取证	16 个：进程/CPU/内存/IO、帧、冷启动、响应、完成、Perf、线程、SQL
设备/环境	18 个：设备、截图、动作、拉取、环境、安装、抓取、应用包、.so、ELF、HAP 提取、Ability、清数据、签名、构建、打包、安装、卸载

tools/list 是静态的，先看工具不需要打开 Trace。Trace 工具只有打开会话后才出现在 available_tools 中。

工具契约与注册按 domain 分层：

contracts/            输入 schema、TraceToolSpec、ToolCatalog
mcp/registration/     session / analysis / evidence / trace / device
tools/trace_handlers/  core / startup / completion / frames / perf / domains
mcp/catalog.py        确定性 catalog + digest
mcp-catalog*.json     生成的 full / compact / device catalog

分析流程

宿主 Agent 的典型循环：

open_trace
  → begin_analysis(scenario_type, scenario, symptom, ...)
  → inspect_*（按需、有界）
  → submit_analysis_result(draft)
  → render_report
  → export_bundle（可选，用于交接/审计）

submit_analysis_result 之后当前分析的 registry 会 seal，不能继续取证；要换假设时重新 begin_analysis，旧 Evidence 仍保留在会话里。

Evidence bundle

export_bundle(path)       # 当前会话完整 Evidence + unknowns + digest
import_bundle(path)       # 校验 digest/target SHA-256 后合并；不执行内容
compare_bundles(left,right)

bundle 是证据快照，不是报告；compare_bundles 只比较记录成员，缺失记录不证明行为等价。

设备与采集

capture_trace 支持：

ui        ftrace + hiperf（默认）
startup   ftrace(ability/app/sched)
memory    ftrace + memory-plugin
io        ftrace(disk/mmc/pagecache) + diskio-plugin
network   ftrace + network-plugin
full      ftrace + memory/diskio/cpu/network/hiperf
perf      ftrace + hiperf

示例：

{
  "preset": "memory",
  "duration_ms": 5000,
  "steps": [
    {"type": "force_stop", "bundle": "com.example.app"},
    {"type": "launch_app", "bundle": "com.example.app", "ability": "EntryAbility"},
    {"type": "wait_for", "element_text": "首页", "timeout_ms": 5000}
  ],
  "open_trace": true
}

设备动作会真实修改设备；act、force_stop、launch_app 需要显式授权。

支持的问题类型

cold-start          应用启动到首帧
response-latency    点击或输入到第一帧有效反馈
completion-latency  点击或输入到动作完全完成
frame-jank          帧率下降、慢帧、丢帧和卡顿

CPU、调度、锁、IPC、同步 I/O、任务队列、渲染和内存/IO 是根因或领域证据，不是独立问题类型。inspect_cpu / inspect_memory / inspect_io 提供能力门控的域摘要；内存泄漏、GC 压力和 OOM 仍需要分配/GC 专门数据。

输出

分析目录通常包含：

run.json
analysis-checkpoint.json
findings.json
evidence.json
unknowns.json
agent-log.jsonl
validation.json
report.html

• report.html：给人看的完整报告
• findings.json：语义结论与 Evidence ID
• evidence.json / unknowns.json：证据与未知项
• validation.json：确定性校验
• agent-log.jsonl：工具调用审计

依赖与环境

• Python 3.12+
• MCP extra：uv sync --extra mcp
• Trace Streamer：仓库内 vendor/trace_streamer/
• 设备工具：hdc；可选 Command Line Tools 托管安装：

diting-agent env status
diting-agent env install --archive <zip> --yes
diting-agent env uninstall

没有内置模型配置；不需要 .env 中的 API Key。

测试

uv run pytest
# 或
PYTHONPATH=src .venv/bin/python -m pytest

文档

• MCP server
• 设备工具
• 架构
• 会话层
• Tool contract