7.5 KiB
Python SDK 示例
English | 中文
基于唯一应用启动器 dsh 的可运行 Python SDK 示例。Python 客户端负责 JSON-RPC stdio；所选 profile 负责 agent（智能体）组合、持久化、执行策略与插件。
运行极简 agent
安装 deepseek-harness-sdk、导出模型凭据，然后提供隔离的 Harness home 与 workspace：
export DEEPSEEK_API_KEY=sk-your-key-here
python python/sdk/examples/minimal.py \
--dsh-home /absolute/path/to/example-dsh-home \
--workspace /absolute/path/to/disposable-workspace \
--session-id example-001 \
"Inspect the repository and fix the failing tests."
如需使用兼容代理，请设置 DEEPSEEK_BASE_URL；可通过 DSH_MODEL 设置脚本的默认模型，通过 DSH_SYSTEM_PROMPT 指定部署角色设定。--model 是唯一运行时模型选择，不要求匹配的环境变量；--profile 可以选择另一个提供 SDK 服务的 profile。所选 home 保存生成的 sdk-minimal profile，并在 sessions/ 下保存未压缩 JSONL 会话日志；脚本绝不会隐式读取 ~/.dsh。
随附的 @deepseek-ai/dsh-sdk-minimal 组合包 是该模式完整且显式的 Cordis 配置树。它只暴露：
- Linux／macOS 上所有者作用域内的持久
bash，或 Windows 上的pwsh - 配合支持图片输入的模型读取 PNG/JPEG/WebP/GIF 文件的
read_image - 查询或修改 Session 目录的
working_directory
该组合包不包含 dsh-base，因此每一个新增配置项都是显式 profile 变更。运行时上下文、文本文件工具、本地指令发现、设置、托管凭据、遥测、Web 工具、subagent 与完整默认工具清单均不存在。配置树保留 SDK 启动与 JSON-RPC 服务、一个由环境配置的 DeepSeek 适配器、本地执行和 JSONL 持久化。自动上下文压缩通过额外模型请求生成较早历史的摘要，同时保留完整日志。这个最小组合将不支持的斜杠输入保留在普通提示词路径上。
持久 PTY 可以修改运行时进程可访问的任何路径，因此只应在一次性 checkout 或容器中使用。
压缩完整 SDK Session
压缩示例使用完整 sdk profile。它将所选工作区的 README.md 读入 Session.run() 输入，通过同一方法执行 /compact，随后使用保留的上下文继续提问。模型凭据和 DSH_MODEL 默认值与极简示例一致，并且要求显式指定 home：
python python/sdk/examples/compact.py \
--dsh-home /absolute/path/to/compact-dsh-home \
--workspace /absolute/path/to/disposable-workspace
脚本对提示词和命令均打印 RunResult.final_response。不成功的 finish_reason 会停止示例。完成和错误行为见运行文本与命令；minimal.py 使用同一个 run() 入口，能力由所选 profile 提供。
修改 Session 权限
权限示例以 workspace-write 为默认值启动完整 sdk profile，发送 /permission <preset>，随后在同一个 Session 中运行普通文本。请显式指定 preset：
python python/sdk/examples/permission.py \
--dsh-home /absolute/path/to/permission-dsh-home \
--workspace /absolute/path/to/disposable-workspace \
--preset read-only
命令会修改 Session 的策略，而打印出的启动设置仍为 workspace-write。后续输入使用 Session 的当前策略。裸 /permission 是普通文本，未知 preset 返回命令错误。结果和状态语义见运行文本与命令。
审查计划
计划示例 通过 run() 发送 /plan <task>，并在这次调用中保持 Session 通知订阅和问答处理器运行，直到计划活动结束。输入 a 批准、k 提供反馈、d 关闭；取消或作答前遇到 EOF 会关闭审查。批准后模型可以从后续步骤开始实施，因此应选择隔离的工作区。
python python/sdk/examples/plan.py \
--dsh-home /absolute/path/to/plan-dsh-home \
--workspace /absolute/path/to/disposable-workspace \
"Plan the requested change and present it for review."
原生计划通过 exit_plan_mode 携带，而不是写入工作区文档。权限仍为 workspace-write。关闭审查会保留计划模式并结束当前轮次。示例通过 run() 等待，并报告根轮次截断或失败；问答回调独立于协议读取线程。等待输入时也可以通过 Ctrl+C 结束示例。
管道答案使用父进程的 stdin 编码，后续行保留给后续问题。UTF-16 和 UTF-32 输入须明确指定小端或大端编码。EOF 处截断的字符会作为输入错误报告。
运行目标
目标示例 提交 /goal <objective>，打印目标变化和助手回复，并在终态目标事件后等待最后的回复。示例使用完整 SDK profile 和 workspace-write 权限。
python python/sdk/examples/goal.py \
--dsh-home /absolute/path/to/goal-dsh-home \
--workspace /absolute/path/to/disposable-workspace \
"Calculate 17 * 19, verify the result, and complete the goal without changing files."
--timeout-seconds 必须是有限正数，用于限制首次命令等待及之后的观察时间，默认为 300 秒。超时会报告失败并关闭运行时，不会将目标标记为完成。恢复会话后可查看持久化目标，再显式恢复执行。run() 包含自动轮次及最后回复。
通过审批管理完整 profile 的插件
manage_plugins.py 先显式下载可选创作运行时，再以 workspace-write 权限和 stdio 审批启动完整 sdk profile。它显示每次请求的操作，只有输入 y 才批准一次，其他回答均拒绝。准备好的 Node/pnpm 可在没有系统 pnpm 时执行包操作。下载该载荷也会准备其中的 Python 库和 Office skills。
python python/sdk/examples/manage_plugins.py \
--dsh-home /absolute/path/to/example-dsh-home \
--workspace /absolute/path/to/disposable-workspace \
"Install and enable the bundle at /absolute/path/to/my-plugin-bundle."
当前进程保留原有插件。收到 restart-required 后，使用相同 home 重新运行示例以加载已保存的配置。删除仍被当前启动组合使用的组合包，需要先停止该运行时，再使用 dsh plugin。
添加插件
对同一个显式 home 使用运行时 wheel 包提供的 dsh 命令，以进行持久 profile 变更：
export DSH_HOME=/absolute/path/to/example-dsh-home
dsh plugin --profile sdk-minimal add file:/absolute/path/to/my-plugin-bundle
在该命令中使用 sdk-minimal 可扩展本示例，使用 sdk 则扩展基于完整 base 的 SDK profile。Python 调用也可以在 patches=(...) 中传入更多绝对 patch 路径；后面的文件优先。所选 profile 必须保留 @deepseek-ai/dsh-sdk-app 或另一个 JSON-RPC server 配置项。该示例不接受完整 Cordis 文件或任意进程 argv。
同一个运行时 wheel 包还打包了供直接 CLI（命令行界面）使用的 web profile 及其前端产物：dsh web 会启动这个独立应用。Python SDK 客户端不能选择 web，因为其中没有 JSON-RPC 服务器配置项。
另见 Python SDK 教程 与 SDK 参考。