基于 Deepseek Harness 开发 agent 笔记

weixin_42019995

260人浏览 · 2026-08-24 08:51:32

weixin_42019995 · 2026-08-24 08:51:32 发布

基于 Deepseek Harness 开发 agent 笔记

适用环境：AutoDL Linux 实例（本项目路径 /root/autodl-tmp/embody_dsh_agent）
前置：你已在 embody_model_eval 的 chat 页能用 DeepSeek 聊天
目标：让大模型不只是回复文字，而是作为 Agent 调用 Skill、执行 bash、改文件

先搞懂：Chat 和 Agent 差在哪
整体架构一张图
环境准备（从零开始）
第一次跑通：验证 Agent + Skill
Skill 是怎么被 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-sdk（Python）                               │
│  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_KEY`
`config/agent-with-skills.cordis.yml`	Agent 能力组合（模型、工具、skill 开关）
`.dsh/skills/`	技能目录（与 Cursor `SKILL.md` 格式兼容）
`sessions/`	每次对话的 JSONL 日志
`scripts/run_agent.py`	命令行跑单次任务

3. 环境准备（从零开始）

若项目已在机器上建好、.venv 已存在，可从 步骤 3.3 开始。

3.1 进入项目目录

cd /root/autodl-tmp/embody_dsh_agent
ls -la

应能看到：config/、.dsh/、scripts/、requirements.txt、README.md。

3.2 创建 Python 虚拟环境并安装依赖

python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -r requirements.txt

安装内容：

deepseek-harness-sdk：Python 调用接口
deepseek-harness-runtime-bin：内置 Agent 运行时（不需要再 npm install）

验证：

python -c "from deepseek_harness import DeepSeekHarness; print('SDK OK')"

3.3 配置 API Key

cp .env.example .env
nano .env   # 或 vim / 在 IDE 里编辑

最少要填一行：

DEEPSEEK_API_KEY=sk-你的真实key

说明：

与 embody_model_eval chat 页用的是同一套 DeepSeek key，可以复用
不要把 .env 提交到 git（已在 .gitignore 里）

可选配置：

DSH_MODEL=deepseek-chat          # 模型名，按你账号支持的填
# DEEPSEEK_BASE_URL=https://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/

执行：

bash scripts/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 + Skill

4.1 激活环境

cd /root/autodl-tmp/embody_dsh_agent
source .venv/bin/activate

以后每次新开终端都要 source .venv/bin/activate。

4.2 跑最简单的 smoke test

python 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 可能会：

调用 bash（date、echo 等）
或用编辑器写文件
最后用文字告诉你结果

检查：

cat workspace/hello.txt

4.4 跑一个带 Skill 的任务

python scripts/run_agent.py \
  "先加载 hik_report skill，然后按该 skill 的风格，写一段 200 字左右的评测报告摘要（虚构数据即可）。"

模型应先 skill(name="hik_report") 加载技能正文，再按技能要求写作。

4.5 查看会话日志（可选）

每次任务会在 sessions/ 下写 JSONL：

find sessions -name 'session.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 — 报告文风、总结与汇报注解

（正文：具体写作规则、流程、示例）

name：kebab-case 标识，模型用这个名字调用
description：出现在 skill 目录里，帮模型判断「该不该用这个 skill」
正文：加载后模型遵循的详细指令

5.2 DSH 从哪里扫描 Skill

Harness 会扫描（按优先级合并）：

路径	含义
`<项目根>/.dsh/skills/`	本项目用的目录
`<项目根>/.agents/skills/`	备选
`~/skills`（DSH 用户目录）	用户级

重要： 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(name="hik_report")
4. Harness 从磁盘读取 SKILL.md 全文 → 返回给模型
5. 模型按技能指令继续（可能再调 bash、编辑器等）

6. 常用操作手册

6.1 命令行跑任务（最常用）

source .venv/bin/activate
python scripts/run_agent.py "你的自然语言任务"

或简写：

bash scripts/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-demo

6.3 指定模型

python scripts/run_agent.py "你好" --model deepseek-chat

或在 .env 里设 DSH_MODEL=deepseek-chat。

6.4 重新同步 Skill

bash scripts/link-skills.sh
ls .dsh/skills/

6.5 清空某次会话（重新开始）

删掉对应 session 目录即可：

rm -rf sessions/*my-demo*

7. HTTP 桥接：给 chat 页或其他前端用

若希望别的程序（例如 embody 的 web 前端）把用户输入交给 Agent：

7.1 启动桥接服务

source .venv/bin/activate
python scripts/bridge_server.py --host 127.0.0.1 --port 8790

保持终端运行；或后台：

nohup python scripts/bridge_server.py --port 8790 > bridge.log 2>&1 &

7.2 健康检查

curl -s http://127.0.0.1:8790/health
# {"ok": true, "service": "embody-dsh-agent"}

7.3 发送任务

curl -s http://127.0.0.1:8790/agent/run \
  -H 'Content-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 调用

import requests

r = requests.post(
    "http://127.0.0.1:8790/agent/run",
    json={"message": "总结 README.md", "sessionId": "py-001"},
    timeout=600,
)
print(r.json()["reply"])

8. 自己写一个 Skill

8.1 最小示例

mkdir -p .dsh/skills/my-eval-skill
nano .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-skill"

8.3 从 embody_model_eval 复用 Skill

把 skill 放在 embody_model_eval/agent_skills/你的skill名/SKILL.md，然后：

bash scripts/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 配置里增加模式选项「Agent（DSH）」

方案 B：chat 页按钮「交给 Agent 执行」

普通消息仍走 /api/chat（快、便宜）
用户点「执行」时，把最后一条用户消息或整段对话摘要 POST 到 bridge

数据流（对接后）

浏览器 chat 页
    → embody agent_server (/api/chat, mode=dsh_agent)
        → bridge_server (:8790/agent/run)
            → DeepSeekHarness
                → 工具 + Skill
    ← reply 显示在聊天气泡里

10. 排错指南

问题：提示 `set DEEPSEEK_API_KEY`

# 检查 .env
grep DEEPSEEK_API_KEY .env
# 或临时导出
export DEEPSEEK_API_KEY=sk-xxx

问题：模型说「没有看到任何 skill」

原因： 工作目录不是项目根，找不到 .dsh/skills。

解决： 使用默认 run_agent.py（cwd=项目根），或确认：

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-chat）

11. 安全与权限说明

当前 agent-with-skills.cordis.yml 中：

sandbox-policy:
  config:
    mode: danger-full-access

含义：Agent 可以在工作区内执行 bash、改文件，能力接近本机用户。

建议：

仅在可信环境使用
敏感目录不要放进 workspace 或 cwd
不要让 Agent 处理含密钥的文件
生产环境可改为更严格的 sandbox（需改 cordis 配置）

项目自带 skill embody-eval-helper 也写了安全规则：优先只读命令、不打印 API key。

12. 进阶：改 Agent 能力（cordis 配置）

文件：config/agent-with-skills.cordis.yml

已启用的能力

插件	能力
`dsh-llm-deepseek`	调 DeepSeek API
`dsh-skill` + `dsh-skill-filesystem` + `dsh-tool-skill`	Skill 体系
`dsh-tool-bash-persistent`	持久 bash（跨轮保留环境）
`dsh-tool-str-replace-editor`	字符串替换式文件编辑
`dsh-session-persistence-jsonl`	会话落盘

改系统人设

环境变量：

export DSH_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_agent
source .venv/bin/activate
python scripts/run_agent.py "你的任务"

# 同步 skill
bash scripts/link-skills.sh

# 启动 HTTP 桥接
python scripts/bridge_server.py --port 8790

# 健康检查
curl -s http://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

乐奇 Rokid 开放社区

更多推荐

AR 智能眼镜并不是简单地在眼前放一块屏幕，而是把**摄像头、传感器、计算机视觉、空间定位、语音交互和云端服务**连接起来

乐奇 Rokid 开放社区

让界面替我“摇“一次：一个AR祈愿智能体的AIUI实践

乐奇 Rokid 开放社区

智能眼镜市场全景解析：从技术演进到产业格局

本文系统梳理智能眼镜市场，涵盖产品形态、技术演进、市场规模、产业链结构及竞争格局。指出智能眼镜正从音频交互向AR显示与空间计算演进，受AI大模型、供应链成熟与生态延伸驱动，呈现分层发展态势。虽面临场景刚需不足、续航重量矛盾与隐私挑战，但B端应用先行、AI原生设计与标准完善将推动行业迈向规模化渗透，未来需关注核心技术突破与真实使用数据。

乐奇 Rokid 开放社区

所有评论(0)

查看更多评论

weixin_42019995

@weixin_42019995

已为社区贡献4条内容

基于 Deepseek Harness 开发 agent 笔记

weixin_42019995

基于 Deepseek Harness 开发 agent 笔记

目录

1. 先搞懂：Chat 和 Agent 差在哪

你现在有的（embody_model_eval /chat）

新项目做的（embody_dsh_agent）

一句话对比

2. 整体架构一张图

3. 环境准备（从零开始）

3.1 进入项目目录

3.2 创建 Python 虚拟环境并安装依赖

3.3 配置 API Key

3.4 链接 Skill 目录

3.5 为什么不用 npx @deepseek-ai/dsh？

4. 第一次跑通：验证 Agent + Skill

4.1 激活环境

4.2 跑最简单的 smoke test

4.3 跑一个「真干活」的任务

4.4 跑一个带 Skill 的任务

4.5 查看会话日志（可选）

5. Skill 是怎么被 Agent 用上的

5.1 Skill 文件长什么样

5.2 DSH 从哪里扫描 Skill

5.3 被动注入 vs 主动调用

5.4 模型调用 Skill 的流程（简化）

6. 常用操作手册

6.1 命令行跑任务（最常用）

6.2 指定会话 ID（多轮连续对话）

6.3 指定模型

6.4 重新同步 Skill

6.5 清空某次会话（重新开始）

7. HTTP 桥接：给 chat 页或其他前端用

7.1 启动桥接服务

7.2 健康检查

7.3 发送任务

7.4 用 Python 调用

8. 自己写一个 Skill

8.1 最小示例

8.2 验证新 Skill 是否被识别

8.3 从 embody_model_eval 复用 Skill

9. 与 embody_model_eval 对接思路

方案 A：加新模式（推荐）

方案 B：chat 页按钮「交给 Agent 执行」

数据流（对接后）

10. 排错指南

问题：提示 set DEEPSEEK_API_KEY

问题：模型说「没有看到任何 skill」

问题：TransportClosedError / plugin tree failed to load

问题：npx @deepseek-ai/dsh 被 Killed

问题：Agent 很慢或超时

问题：API 401 / 模型不存在

11. 安全与权限说明

12. 进阶：改 Agent 能力（cordis 配置）

已启用的能力

改系统人设

关闭 Skill（调试用）

参考文档

附录 A：一键命令备忘

附录 B：目录清单（核对用）

附录 C：学习路径建议

所有评论(0)

温馨提示：您尚未绑定手机号

weixin_42019995

你现在有的（embody_model_eval `/chat`）

3.5 为什么不用 `npx @deepseek-ai/dsh`？

问题：提示 `set DEEPSEEK_API_KEY`

问题：`TransportClosedError` / `plugin tree failed to load`

问题：`npx @deepseek-ai/dsh` 被 Killed