Learn DeepSeek Harness

核心模式 (Core Pattern)

所有 AI 编程 Agent 共享同一个循环：调用模型、执行工具、回传结果。生产级系统（包括 DeepSeek Harness）都会在这个循环上叠加策略、权限、记忆和生命周期层，但循环本身始终不变。

agent_loop.mjs：

// 用 DeepSeek 的 OpenAI 兼容 API 实现最小 agent 循环
const API = "https://api.deepseek.com/chat/completions";

async function agentLoop(messages, tools) {
  while (true) {
    const res = await fetch(API, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${process.env.DEEPSEEK_API_KEY}`,
      },
      body: JSON.stringify({ model: "deepseek-chat", messages, tools }),
    });
    const data = await res.json();
    const msg = data.choices[0].message;
    messages.push(msg); // 模型回答进入历史

    // 模型不调用工具 → 结束
    if (!msg.tool_calls) return;

    // 模型调用工具 → 逐个执行、回传结果
    for (const call of msg.tool_calls) {
      const result = await execute(call.function.name, JSON.parse(call.function.arguments));
      messages.push({ role: "tool", tool_call_id: call.id, content: String(result) });
    }
  }
}

消息增长：每轮循环，messages 数组都会追加模型回答和工具结果。

这是唯一的核心。 后面 19 课都在这 30 行循环上叠加机制，循环本身始终不变。

学习路径 (Learning Path)

20 个渐进式课程，从最小循环到完整多 Agent Harness。每一课只加一个机制。

架构层次 (Architecture Layers)

五个正交关注点组合成完整的 Agent：

版本对比

20 个版本，每次只加一个机制。对照看一遍，整个 Harness 的演进一目了然。

工具与执行

规划与控制

记忆管理

并发与调度

多 Agent 平台

下一步：跑真实的 DeepSeek Harness

课程写完了，现在去用真的。

安装与运行

从 npm（需要 Node.js）：

npx @deepseek-ai/dsh web

默认在 http://127.0.0.1:3080 打开 Web UI（更完整的指南见 docs/user/guide/index.md）。

从源码运行（本仓库）：

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

配置 DeepSeek API 密钥（DEEPSEEK_API_KEY），然后新建会话，让 Agent 做一件多步任务。

阅读建议

• 先跑 dsh web 体验一遍完整产品，再回头对照本课程的机制图；
• 想扩展能力 → 读 docs/cookbook/adding-a-tool.md（加一个工具的完整流程）与 docs/cookbook/adding-a-package.md（加一个包的流程）；
• 想深入架构 → 读 docs/architecture.md（改动 packages/ 前的必读）与 docs/cordis-primer.md（Cordis 入门）；
• 想看每个包的契约 → 读各包的 README（本课程每课的"深入 DSH 源码"都给出了路径）。

本课程的三个心智模型

1. 一个循环：所有 Agent 都是 while true——调用模型、执行工具、回传结果。其余一切都是环绕它的策略与生命周期。
2. 事件日志是记忆：一切状态（todo、计划、目标、调度、会话历史）都长在追加式事件日志上，视图是派生的。Model-visible ⟺ logged。
3. 能力缝：Service Definition / Provider / Consumer 三角。接口稳定，后端可换——工具、子代理、沙箱、模型、web、技能，全都一样。

记住这三条，你就拥有了阅读任何 Agent Harness（包括 DSH 源码）的地图。

本课程基于 DeepSeek Harness 仓库当前状态编写。DeepSeek Harness 处于开发者预览阶段，接口可能随迭代变化；机制与设计意图不变。