dsh 识图功能调试记录
我将根据这份 session.jsonl.md 对话日志，为你全面统计和分析整场对话中 AI 助手（Agent）使用的所有工具、调用次数、以及每个命令的详细作用。
通过这份分析，你能清晰看到一个 AI 编码助手是如何通过组合使用各种工具，完成「调研 → 分析 → 修改配置 → 验证 → 交付文档」这一整套复杂任务的。
一、工具使用总览
整场对话共涉及 8 种不同的工具，累计调用次数为 70 次（统计了所有被记录的工具调用，包括部分工具因错误重试的情况）。
工具调用次数统计表
工具名称 调用次数 核心用途
bash 47 次 执行 Shell 命令，是使用最频繁的工具，用于文件查看、进程检查、网络探测、YAML 解析等
edit 7 次 编辑配置文件（cordis.patch.yml），是完成配置修改的核心工具
read 4 次 读取文件内容（如配置文件、源代码），用于调研
write 1 次 创建新的 Markdown 文档（使用说明）
skill 2 次 加载技能（dsh-archive-agent-notes, knowly-clipboard）
ask_user_question 1 次 向用户提问以确认关键决策（识图模式选择）
vision_describe 2 次 调用视觉模型识别图片内容，验证识图链路
vision_activate 1 次 挂载视觉工具，使 vision_describe 等可用
read_image 2 次 尝试读取图片（但因模型不支持而失败，用于验证）
todo_write 1 次 更新任务清单，记录工作进度
注：部分工具（如 read_image）虽然调用失败，但仍记录了调用动作，因此纳入统计。
二、各工具详细命令与作用解析
- bash 工具（47 次）
bash 是 Agent 的“万能手”，用来执行系统命令。以下是按功能分类的典型命令及其作用：
(1) 文件/目录查看
命令示例 作用
pwd && ls -la 查看当前工作目录及文件列表，确认环境
ls -la .dsh-vision-router/ 查看视觉路由插件的目录内容
find . -maxdepth 3 -name "*.yml" 查找配置文件，定位 YAML 文件
stat -f "inode: %i" ~/.dsh/profiles/web/cordis.patch.yml 获取文件的 inode（唯一ID），用于对比进程加载的文件是否是最新版本
cat ~/.dsh/settings.yaml 读取用户级配置文件，查看模型和 provider 设置
cat /tmp/dsh-web-restart.log 查看 DSH Web 服务重启日志，确认重启时间
(2) 进程与端口检查
命令示例 作用
lsof -nP -iTCP:3080 查看 3080 端口被哪个进程监听，获取 PID
lsof -p 29495 列出进程 29495 打开的所有文件，用于确认它加载了哪些配置文件，并与磁盘 inode 对比
ps aux grep node
lsof -a -p 29495 -d cwd 查看进程的工作目录
(3) 网络与端口探测
命令示例 作用
lsof -nP -i@127.0.0.1 列出本机所有监听端口，检查是否有额外管理端口
lsof -nP -iTCP -sTCP:LISTEN 筛选所有监听中的 TCP 端口，用于发现 DSH 可能暴露的 API
(4) YAML / JSON 解析与校验
命令示例 作用
node -e "const fs=require('fs'); const YAML=require('yaml'); ..." 使用 Node.js 解析 YAML 文件，验证 cordis.patch.yml 语法和结构是否正确
python3 -c "import json; ..." 解析 usage.json，查看模型调用统计
(5) 直接 API 测试（识图链路验证）
命令示例 作用
curl -X POST https://opencode.ai/zen/go/v1/chat/completions ... 测试 opencode-go 模型是否支持 image_url，结果报错，证实其为纯文本
curl -X POST https://token.sensenova.cn/v1/chat/completions ... 测试 sensenova 模型是否支持图像输入，成功返回，证明其可用
(6) 工具/脚本查找与执行
命令示例 作用
which knowly 查找 knowly 命令路径，确认其已安装
find ~/ -iname "knowly" 查找所有含 knowly 的文件，定位上传脚本
python3 ~/.pi/agent/skills/knowly-clipboard/scripts/clipboard.py upload ... 执行 knowly 上传脚本，将使用说明文档上传到远程剪贴板服务
(7) 文件备份
命令示例 作用
cp ~/.dsh/profiles/web/cordis.patch.yml ~/.dsh/profiles/web/cordis.patch.yml.bak.$(date ...) 修改配置前进行备份，但此操作被沙箱拒绝，需升级权限
- edit 工具（7 次）
用于精确修改文件内容，是完成配置优化的核心工具。
调用次数 目标文件 修改内容 作用
第 1 次（失败） ~/.dsh/profiles/web/cordis.patch.yml 将注释和 httpProviders 替换为包含 providers 的新配置 在配置中新增视觉链（providers），使整轮识图优先使用 sensenova
第 2 次（失败） 同上 同样的修改，但因权限不足失败 触发权限升级请求
第 3 次（成功） 同上 同样的修改，带上 sandbox_permissions: danger-full-access 获得用户授权后成功写入新配置
第 4 次（失败） 同上 再次修改，加入 wrappedProviders 配置 显式包装 opencode-go 模型，使其也能出现在模型选择器中
第 5 次（成功） 同上 同上，同样使用高权限 第二次修改成功，最终配置包含 providers, httpProviders, wrappedProviders
- read 工具（4 次）
用于只读查看文件内容，与 cat 作用类似，但通过 DSH 的文件系统 API 实现。
调用次数 目标文件 作用
1 ~/.dsh/profiles/web/cordis.patch.yml 读取当前配置，了解 httpProviders 的现状
2 同上 修改前再次读取，确认 old_string 能精确匹配
3 同上（修改后） 验证修改后的文件内容是否正确
4 /Users/ygs/.dsh/profiles/web/cordis.patch.yml 再次读取，确认 inode 和内容
- write 工具（1 次）
用于创建或完全覆盖一个文件。
调用次数 目标文件 内容 作用
1 DSH识图模型配置使用说明.md 整个 Markdown 文档内容 生成一份完整的使用说明文档，涵盖目标配置、模型能力表、配置文件结构、两条识图路径、验证方法、常见问题等六大块
- skill 工具（2 次）
用于加载技能（Skill），技能是预先编写好的专业指令集，能扩展 Agent 的能力。
调用次数 技能名 作用
1 dsh-archive-agent-notes 加载 Agent Note 归档技能（但在本次对话中未真正执行，只是加载）
2 knowly-clipboard 加载 knowly 远程剪贴板技能，该技能描述了如何上传文件到 Knowly，为后续上传做准备
- ask_user_question 工具（1 次）
用于在关键决策点向用户提问，获取用户的明确选择。
调用次数 问题内容 选项 作用
1 “图片轮的识图方式目前有两条实现路径，你希望用哪种？” ① 整轮自动切识图模型（推荐） ② 工具优先 确认用户希望使用“整轮自动切”还是“工具优先”模式，用户选择了前者，Agent 据此调整配置中的 routing 参数
- vision_describe 工具（2 次）
用于调用视觉模型识别图片内容，是验证识图链路是否生效的终端测试工具。
调用次数 图片路径 问题 结果
1 card_show.html-shot-700x900.png “这张截图里主要展示了什么界面？概括要点。” 失败，因为当前模型是 deepseek-v4-flash，不支持图像输入，报错“unknown tool”或模型不支持
2 card_saltlake-crop-60-60-1020-900.png “这张卡片上主要有哪些元素？概括内容，回答 JSON。” 成功，返回了结构化 JSON，描述卡片内容（“暮色如酒，盐湖微醺”等），证明识图链路已走通，且使用的是 sensenova 模型
- vision_activate 工具（1 次）
用于手动挂载视觉工具。在正常图片轮中会自动挂载，但为了在纯文本轮中调用 vision_describe，需要主动激活。
调用次数 参数 作用
1 {}（无参数） 将 vision_describe, vision_ground, vision_crop 等全套视觉工具挂载到当前会话中，使其可被调用
- read_image 工具（2 次）
用于尝试直接读取图片文件，但前提是当前模型必须声明支持图像输入。
调用次数 图片路径 结果 意义
1 card_saltlake-crop...png 报错：“model 'deepseek-v4-flash' does not declare image input” 证明了文字轮模型确实不支持识图，间接验证了配置中 deepseek-v4-flash 为纯文本，符合预期
2 同上 同样报错 再次确认，强化证据
- todo_write 工具（1 次）
用于更新任务清单，帮助 Agent 追踪多步骤工作的进度。
调用次数 任务列表 作用
1 ① 撰写 DSH 识图模型配置使用说明 Markdown（in_progress） ② 上传使用说明到 Knowly（pending） 记录当前工作状态，为后续上传做准备
后一次更新 将两个任务状态都改为 completed 标记任务完成，整理工作成果
三、高频命令背后的“组合拳”思路
通过分析这些工具调用，我们可以还原 Agent 解决“识图模型配置优化”这一任务的典型工作流：
- 调研阶段：
· 使用 bash + cat/ls 查看现有配置文件（settings.yaml, cordis.patch.yml）
· 使用 bash + find/grep 在源码中搜索 vision 相关实现
· 使用 bash + curl 直接测试模型 API，验证 deepseek 和 sensenova 的能力差异 - 方案设计阶段：
· 通过 read 读取 cordis.patch.yml，了解当前 httpProviders 配置
· 分析源码后确定需要修改 providers（视觉链）和 wrappedProviders（包装） - 修改与验证阶段：
· 使用 edit 修改配置文件（遇到权限不足时，配合 ask_user_question 获取用户授权）
· 使用 bash + lsof 检查进程是否加载了新配置（通过 inode 对比）
· 使用 bash + ps/lsof 确认进程 PID 变化（重启后旧进程消失，新进程出现） - 端到端测试阶段：
· 调用 vision_activate 挂载视觉工具
· 调用 vision_describe 识别图片，确认走的是 sensenova 链路
· 调用 read_image 触发错误，确认文字轮确实为纯文本 - 交付阶段：
· 使用 write 生成使用说明文档
· 使用 bash + python3 执行 knowly 上传脚本，将文档发布到远程存储
四、学习要点
通过这份对话记录，你可以学到：
· 组合工具解决问题：一个复杂任务需要多种工具配合（如 lsof + stat + edit 协同完成配置修改与验证）。
· 系统化调试思维：从“调研现状”→“设计方案”→“小步修改”→“逐步验证”→“端到端测试”的闭环。
· 权限管理：当工具因沙箱限制失败时，Agent 能够识别并请求升级权限（danger-full-access）。
· 用户交互：在关键决策点（如识图模式选择）主动询问，而非擅自决定。
· 验证驱动开发：每一步修改后都通过命令（如查看 inode、测试 API）验证生效，而非靠猜测。