AI PASSPORT//
EN

使用指南 / 09

用 DeepSeek Harness 创造 AI Passport 玩法

安装 DeepSeek 开源的 Agent 工作台，把玩法项目加入工作区，从一条提示词开始完成开发与构建。

01

认识 DeepSeek Harness

DeepSeek Harness 是 DeepSeek 开源的 Agent 工作台，可以作为桌面应用使用。它能在本地工作区里阅读代码、修改文件、运行命令，并通过插件扩展能力。目前处于预览版阶段。

  • 开发方：DeepSeek（深度求索）
  • 支持系统：macOS（Apple 芯片），Windows 64 位
  • 使用前提：DeepSeek 账号，或 DeepSeek 开放平台的 API Key；预览版功能可能变化
  • 本教程使用的版本：0.2.1-rc.5
提示
验证环境：macOS 26.6（Apple 芯片），2026 年 10 月 30 日实际安装并完成本教程的示例任务。
02

下载并安装 DeepSeek Harness

从官方网站下载安装包：deepseek.com/harness。请只使用官方渠道，不要安装来源不明的打包版本。

DeepSeek Harness 官网下载页
从 deepseek.com/harness 下载桌面应用
  • 在官网点击「下载 macOS 版」；Windows 用户从下拉菜单选择 Windows 版
  • macOS：打开 .dmg，把 DeepSeek Harness 拖进「应用程序」文件夹
  • Windows：运行 .exe 安装程序，按向导完成安装
03

登录并确认模型

首次打开会显示欢迎页，可以选择「Sign in」登录 DeepSeek 账号，或选择「Add API Key」使用 DeepSeek 开放平台的 API Key。进入会话页后，在输入框附近确认模型和权限模式。本教程使用 DeepSeek-V4.1-Flash（High），权限为「Workspace Write」（只允许修改当前工作区）。

DeepSeek Harness 新会话界面
新会话界面：上方选择工作区和模式，下方是权限和模型
DeepSeek Harness 模型与思考强度菜单
在输入框右下角确认模型和思考强度
04

打开 AI Passport 项目

点击「Choose workspace」，选择「Add workspace…」，在文件选择窗口中打开 AI Passport 项目文件夹，然后在这个工作区里新建会话。

DeepSeek Harness 已选择 deepseek-passport 工作区
工作区切换为 AI Passport 项目文件夹
提示
可以先在终端运行 git clone https://gitee.com/FoloToy/ai-passport.git 把项目下载到本地；也可以选一个空文件夹，让 Agent 按提示词自己下载项目。
05

发送开发提示词

新建一个会话，把下面的提示词复制到输入框，把【填写应用需求】换成你想做的玩法，再发送。本教程的示例需求如下：

发送给 Agent 的提示词
请基于完整项目 https://gitee.com/FoloToy/ai-passport 开发；本地已有项目则复用。
先读 AGENTS.md 和 docs/README.md，按需查阅相关文档、硬件接口及示例，自行准备环境并安装项目要求的 Skill。
保留已有修改，新建分支开发。复用 BSP，重新设计应用界面，不照搬 demo；中文界面检查字体覆盖。关键需求不明确时询问，其余自主完成。
运行项目验证，交付可从 0x0 刷写的合并固件，说明测试结果与未验证项。完成后主动询问是否刷机测试，未经确认不烧录。
在 DeepSeek Harness 输入框中粘贴开发提示词
粘贴提示词并填好玩法需求
  • 一个番茄钟：开机进入 25 分钟专注倒计时；确定键开始 / 暂停，上下键在未开始时把时长调整为 5–60 分钟（每次 5 分钟）；倒计时结束时屏幕醒目提示并播放提示音，按确定键回到初始状态
06

让 DeepSeek Harness 完成开发与构建

DeepSeek Harness 会先安装并校验项目要求的 5 个 passport Skill，阅读 AGENTS.md 和相关文档，再新建 feature/pomodoro-timer 分支、编写代码并运行项目自带的验证脚本。会话下方会显示步骤数和用量，点击「Trajectory」可以查看每一步执行的命令。

DeepSeek Harness 正在运行命令
Agent 开始阅读项目并运行命令
提示
第一次运行时 Agent 会安装项目要求的 Skill，并检查或准备 ESP-IDF 构建环境，耗时较长。看到构建成功和固件路径之前，不要认为任务已经完成。
07

查看结果

本次示例用时约 24 分钟。DeepSeek Harness 报告构建和电脑端测试全部通过，新增了倒计时状态机测试和中文字形覆盖测试，并交付合并固件 build/FoloToy-AI-Passport-full.bin（893,104 字节，从 0x0 写入），同时附上 SHA-256 校验值。

DeepSeek Harness 报告构建通过并给出合并固件
测试结果、合并固件文件名、大小、SHA-256 和写入偏移 0x0
DeepSeek Harness 改动文件列表与审阅面板
在审阅面板逐个查看改动的文件
  • 点击「Edited 21 files」或右侧审阅面板，可以逐个查看改动的文件和差异
  • 报告中的「未验证」列出了必须在设备上确认的内容：中文显示效果、按键、提示音、电量显示和长时间运行
  • Agent 用「Ask question」卡片询问是否刷机时，默认选项可能是「刷机测试」。设备没准备好时，请改选「暂不刷机」再提交
08

安装到 AI Passport 并验证

打开本地玩法安装工具，选择 Agent 交付的合并固件（从 0x0 写入的 .bin 文件），用支持数据传输的 USB-C 线连接 AI Passport 并开始安装。完成后设备自动重启，逐项检查屏幕、按键和声音。

  • 安装新玩法会覆盖设备当前的全部内容；之后可以随时恢复默认固件
  • 安装过程中不要拔线或关闭页面
  • 把与预期不一致的画面和按键表现描述给 Agent，让它继续修改并重新构建
09

常见问题

使用 DeepSeek Harness 开发 AI Passport 玩法时，可能遇到以下情况：

  • 预览版界面或功能与本教程不同：以官网和应用内说明为准
  • 首次打开停在欢迎页：选择「Sign in」登录，或选择「Add API Key」填入自己的 API Key；API Key 只填在应用里，不要发到会话中
  • 构建环境缺失：让 Agent 按项目文档准备 ESP-IDF 5.5.3；已经安装过时，可以提示它通过 IDF_PYTHON_ENV_PATH 使用现有的 Python 环境
  • macOS 上提示链接器不支持 --gc-sections：这是项目主机测试在 macOS 上的已知差异，Agent 会改用 -dead_strip 继续测试，不影响固件构建
  • 请从 deepseek.com 下载，网络上有不少非官方打包的同名桌面版