基于 Deepseek Harness 开发 agent 笔记适用环境AutoDL Linux 实例本项目路径/root/autodl-tmp/embody_dsh_agent前置你已在embody_model_eval的 chat 页能用 DeepSeek 聊天目标让大模型不只是回复文字而是作为Agent调用 Skill、执行 bash、改文件目录先搞懂Chat 和 Agent 差在哪整体架构一张图环境准备从零开始第一次跑通验证 Agent SkillSkill 是怎么被 Agent 用上的常用操作手册HTTP 桥接给 chat 页或其他前端用自己写一个 Skill与 embody_model_eval 对接思路排错指南安全与权限说明进阶改 Agent 能力cordis 配置1. 先搞懂Chat 和 Agent 差在哪你现在有的embody_model_eval/chat用户输入 → agent_server.py → DeepSeek API/chat/completions→ 一段文字回复Skill 是整段塞进 system prompt的模型只能「读说明书」不能主动翻页模型不能跑命令、不能改文件、不能多轮调工具适合问答、润色、草稿新项目做的embody_dsh_agent用户输入 → DeepSeek Harness Agent 循环 ↓ 模型决定要调 skill 工具要跑 bash要改文件 ↓ 执行工具 → 把结果喂回模型 → 继续推理 → 最终回复Skill 在.dsh/skills/目录模型通过skill工具按需加载自带bash、文件编辑等工具适合自动写报告、查目录、改脚本、跑 pipeline 相关任务一句话对比Chat 页embody_dsh_agent本质聊天补全智能体Skill被动注入主动调用能干活吗不能能2. 整体架构一张图┌─────────────────────────────────────────────────────────────┐ │ 你CLI / HTTP / 未来的 chat 页 │ └──────────────────────────┬──────────────────────────────────┘ │ 自然语言任务 ▼ ┌─────────────────────────────────────────────────────────────┐ │ scripts/run_agent.py 或 scripts/bridge_server.py │ │ Python 薄封装层 │ └──────────────────────────┬──────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ deepseek-harness-sdkPython │ │ DeepSeekHarness.run(你的任务) │ └──────────────────────────┬──────────────────────────────────┘ │ JSON-RPC stdio ▼ ┌─────────────────────────────────────────────────────────────┐ │ 内置 runtime 可执行文件无需单独装 Node │ │ 读取 config/agent-with-skills.cordis.yml 决定装哪些插件 │ └──────────────────────────┬──────────────────────────────────┘ │ ┌─────────────────┼─────────────────┐ ▼ ▼ ▼ DeepSeek API skill 工具 bash / 编辑器 │ │ │ │ ▼ │ │ .dsh/skills/*.md │ │ SKILL.md 技能库 │ └─────────────────┴─────────────────┘ │ ▼ sessions/*.jsonl 会话日志可复盘关键文件文件作用.env放DEEPSEEK_API_KEYconfig/agent-with-skills.cordis.ymlAgent 能力组合模型、工具、skill 开关.dsh/skills/技能目录与 CursorSKILL.md格式兼容sessions/每次对话的 JSONL 日志scripts/run_agent.py命令行跑单次任务3. 环境准备从零开始若项目已在机器上建好、.venv已存在可从步骤 3.3开始。3.1 进入项目目录cd/root/autodl-tmp/embody_dsh_agentls-la应能看到config/、.dsh/、scripts/、requirements.txt、README.md。3.2 创建 Python 虚拟环境并安装依赖python3-mvenv .venvsource.venv/bin/activate pipinstall-Upip pipinstall-rrequirements.txt安装内容deepseek-harness-sdkPython 调用接口deepseek-harness-runtime-bin内置 Agent 运行时不需要再npm install验证python-cfrom deepseek_harness import DeepSeekHarness; print(SDK OK)3.3 配置 API Keycp.env.example .envnano.env# 或 vim / 在 IDE 里编辑最少要填一行DEEPSEEK_API_KEYsk-你的真实key说明与embody_model_evalchat 页用的是同一套 DeepSeek key可以复用不要把.env提交到 git已在.gitignore里可选配置DSH_MODELdeepseek-chat# 模型名按你账号支持的填# DEEPSEEK_BASE_URLhttps://api.deepseek.com/v1 # 一般不用改3.4 链接 Skill 目录项目已自带scripts/link-skills.sh会把以下来源的 skill软链接到.dsh/skills/../embody_model_eval/agent_skills/如hik_report、md-to-docx-report~/.cursor/skills/~/.cursor/skills-cursor/执行bashscripts/link-skills.sh检查ls.dsh/skills/# 应看到 hik_report、embody-eval-helper、sdk 等每增加新 skill 后重新跑一遍link-skills.sh即可。3.5 为什么不用npx deepseek-ai/dsh官方也支持npx deepseek-ai/dsh web但在当前 AutoDL 实例上npm install/npx拉包时容易被系统OOM kill内存峰值过高。因此本项目选用Python SDK 内置 runtime功能等价更稳。4. 第一次跑通验证 Agent Skill4.1 激活环境cd/root/autodl-tmp/embody_dsh_agentsource.venv/bin/activate以后每次新开终端都要source .venv/bin/activate。4.2 跑最简单的 smoke testpython scripts/run_agent.py\只回复一句话列出 catalog 里能看到的 skill 名称不要执行 bash。预期结果终端打印一行文字列出多个 skill 名例如catalog 里能看到的 skill 有autodl-disk-cleanup、embody-eval-helper、hik_report、md-to-docx-report、sdk ...这说明DeepSeek API 通了Harness runtime 起来了Skill 注册表能被模型通过skill工具读到4.3 跑一个「真干活」的任务python scripts/run_agent.py\在 workspace 目录创建一个 hello.txt内容是今天的日期然后告诉我文件路径。Agent 可能会调用 bashdate、echo等或用编辑器写文件最后用文字告诉你结果检查catworkspace/hello.txt4.4 跑一个带 Skill 的任务python scripts/run_agent.py\先加载 hik_report skill然后按该 skill 的风格写一段 200 字左右的评测报告摘要虚构数据即可。模型应先skill(namehik_report)加载技能正文再按技能要求写作。4.5 查看会话日志可选每次任务会在sessions/下写 JSONLfindsessions-namesession.jsonl|tail-3# 用编辑器打开最新的可看到模型请求、工具调用、assistant 消息5. Skill 是怎么被 Agent 用上的5.1 Skill 文件长什么样与 Cursor 完全一致例如.dsh/skills/hik_report/SKILL.md--- name: hik_report description: Guide Chinese technical report writing... --- # hik_report — 报告文风、总结与汇报注解 正文具体写作规则、流程、示例namekebab-case 标识模型用这个名字调用description出现在 skill 目录里帮模型判断「该不该用这个 skill」正文加载后模型遵循的详细指令5.2 DSH 从哪里扫描 SkillHarness 会扫描按优先级合并路径含义项目根/.dsh/skills/本项目用的目录项目根/.agents/skills/备选~/skillsDSH 用户目录用户级重要run_agent.py的默认工作目录是项目根/root/autodl-tmp/embody_dsh_agent不是workspace/子目录。如果把 cwd 设成子目录.dsh/skills会找不到模型会说「没有看到任何 skill」——这是已踩过的坑。5.3 被动注入 vs 主动调用方式embody chat 页embody_dsh_agent机制把 SKILL.md 全文拼进 system prompt模型调用skill工具优点实现简单省 token、按需加载、可多 skill 组合缺点技能多时 prompt 爆炸需要 Harness 运行时5.4 模型调用 Skill 的流程简化1. Agent 启动 → 向模型展示 skill 目录只有 name description不含正文 2. 用户任务来了 → 模型判断需要 hik_report 3. 模型调用 skill(namehik_report) 4. Harness 从磁盘读取 SKILL.md 全文 → 返回给模型 5. 模型按技能指令继续可能再调 bash、编辑器等6. 常用操作手册6.1 命令行跑任务最常用source.venv/bin/activate python scripts/run_agent.py你的自然语言任务或简写bashscripts/agent.sh你的自然语言任务6.2 指定会话 ID多轮连续对话同一个session-id会保留上下文和 bash 状态# 第一轮python scripts/run_agent.py记住数字 42--session-id my-demo# 第二轮接着聊python scripts/run_agent.py我刚才让你记住的数字是多少--session-id my-demo6.3 指定模型python scripts/run_agent.py你好--modeldeepseek-chat或在.env里设DSH_MODELdeepseek-chat。6.4 重新同步 Skillbashscripts/link-skills.shls.dsh/skills/6.5 清空某次会话重新开始删掉对应 session 目录即可rm-rfsessions/*my-demo*7. HTTP 桥接给 chat 页或其他前端用若希望别的程序例如 embody 的 web 前端把用户输入交给 Agent7.1 启动桥接服务source.venv/bin/activate python scripts/bridge_server.py--host127.0.0.1--port8790保持终端运行或后台nohuppython scripts/bridge_server.py--port8790bridge.log217.2 健康检查curl-shttp://127.0.0.1:8790/health# {ok: true, service: embody-dsh-agent}7.3 发送任务curl-shttp://127.0.0.1:8790/agent/run\-HContent-Type: application/json\-d{ message: 列出 embody-eval-helper skill 的用途, sessionId: web-user-001 }返回 JSON 示例{ok:true,reply:embody-eval-helper 用于……,sessionId:web-user-001,finishReason:...}7.4 用 Python 调用importrequests rrequests.post(http://127.0.0.1:8790/agent/run,json{message:总结 README.md,sessionId:py-001},timeout600,)print(r.json()[reply])8. 自己写一个 Skill8.1 最小示例mkdir-p.dsh/skills/my-eval-skillnano.dsh/skills/my-eval-skill/SKILL.md内容--- name: my-eval-skill description: 当用户要求汇总评测指标、对比模型结果时使用。 --- # my-eval-skill ## 步骤 1. 先问清楚指标名称成功率、延迟、吞吐等 2. 输出 Markdown 表格 3. 最后给 3 条结论建议无需link-skills.sh已在.dsh/skills下。8.2 验证新 Skill 是否被识别python scripts/run_agent.py\列出 catalog 里的 skill确认包含 my-eval-skill8.3 从 embody_model_eval 复用 Skill把 skill 放在embody_model_eval/agent_skills/你的skill名/SKILL.md然后bashscripts/link-skills.sh两边共用一套 skill 仓库chat 页被动注入和 dsh agent主动调用都能用。9. 与 embody_model_eval 对接思路当前 chat 页POST /api/chat走的是 OpenAI 补全。要改成 Agent推荐两步方案 A加新模式推荐先常驻桥接python scripts/bridge_server.py --port 8790在embody_model_eval/scripts/agent_server.py的run_chat()里增加mode dsh_agent把message、sessionId转发到http://127.0.0.1:8790/agent/run把返回的reply填进现有 chat 响应格式前端 chat 配置里增加模式选项「AgentDSH」方案 Bchat 页按钮「交给 Agent 执行」普通消息仍走/api/chat快、便宜用户点「执行」时把最后一条用户消息或整段对话摘要POST 到 bridge数据流对接后浏览器 chat 页 → embody agent_server (/api/chat, modedsh_agent) → bridge_server (:8790/agent/run) → DeepSeekHarness → 工具 Skill ← reply 显示在聊天气泡里10. 排错指南问题提示set DEEPSEEK_API_KEY# 检查 .envgrepDEEPSEEK_API_KEY .env# 或临时导出exportDEEPSEEK_API_KEYsk-xxx问题模型说「没有看到任何 skill」原因工作目录不是项目根找不到.dsh/skills。解决使用默认run_agent.pycwd项目根或确认ls/root/autodl-tmp/embody_dsh_agent/.dsh/skills/问题TransportClosedError/plugin tree failed to load原因config/agent-with-skills.cordis.yml里某个字段类型不对Harness 校验很严。解决对照仓库里已验证的配置不要随意把workspaceContext: true或toolBash: true写成布尔值——很多字段要对象或false。问题npx deepseek-ai/dsh被 Killed原因本机 npm 拉包内存峰值过高。解决继续用 Python SDK 路径不要强行走 npx。问题Agent 很慢或超时复杂任务会多轮调工具正常需几十秒到数分钟bridge 默认无短超时前端调用时自行设timeout如 600 秒看sessions/.../session.jsonl定位卡在哪一步问题API 401 / 模型不存在检查 key 是否有效、余额是否充足DSH_MODEL改成你账号支持的名称如deepseek-chat11. 安全与权限说明当前agent-with-skills.cordis.yml中sandbox-policy:config:mode:danger-full-access含义Agent 可以在工作区内执行 bash、改文件能力接近本机用户。建议仅在可信环境使用敏感目录不要放进 workspace 或 cwd不要让 Agent 处理含密钥的文件生产环境可改为更严格的 sandbox需改 cordis 配置项目自带 skillembody-eval-helper也写了安全规则优先只读命令、不打印 API key。12. 进阶改 Agent 能力cordis 配置文件config/agent-with-skills.cordis.yml已启用的能力插件能力dsh-llm-deepseek调 DeepSeek APIdsh-skilldsh-skill-filesystemdsh-tool-skillSkill 体系dsh-tool-bash-persistent持久 bash跨轮保留环境dsh-tool-str-replace-editor字符串替换式文件编辑dsh-session-persistence-jsonl会话落盘改系统人设环境变量exportDSH_SYSTEM_PROMPT你是 embody 评测助手优先使用 skill 工具。python scripts/run_agent.py你好或改 cordis 里agent-spine.config.persona。关闭 Skill调试用把skills.enabled改为false并注释掉 skill 相关三个插件行。参考文档DeepSeek Harness Skills 参考Python SDK 指南本仓库examples/jsonrpc-agent/minimal.cordis.yml上游示例附录 A一键命令备忘# 日常三连cd/root/autodl-tmp/embody_dsh_agentsource.venv/bin/activate python scripts/run_agent.py你的任务# 同步 skillbashscripts/link-skills.sh# 启动 HTTP 桥接python scripts/bridge_server.py--port8790# 健康检查curl-shttp://127.0.0.1:8790/health附录 B目录清单核对用embody_dsh_agent/ ├── .dsh/skills/ # Skill 库软链接 自建 ├── .env # API Key自建勿提交 ├── .env.example ├── .venv/ # Python 虚拟环境 ├── config/ │ └── agent-with-skills.cordis.yml ├── docs/ │ └── 手把手教学笔记.md # 本文 ├── scripts/ │ ├── agent.sh │ ├── bridge_server.py │ ├── link-skills.sh │ ├── run_agent.py │ ├── run-dsh.sh # 可选 npx 路径 │ ├── run-headless.sh │ └── run-web.sh ├── sessions/ # 会话 JSONL ├── workspace/ # 可选产出目录 ├── requirements.txt └── README.md附录 C学习路径建议第 1 天跑通 4.2 smoke test理解 Chat vs Agent第 2 天用 4.3、4.4 让 Agent 写文件、用 hik_report第 3 天读sessions/.../session.jsonl看工具调用链第 4 天自己写一个 skill并link-skills.sh第 5 天启动 bridge用 curl 模拟前端对接文档版本2026-08-23对应项目路径/root/autodl-tmp/embody_dsh_agent