DeepSeek Harness：插件化 Agent 运行时

Model + Harness = Agent

┌──────────────────────────────────────────────────────┐
│                   Cordis 微内核                      │
│                                                      │
│  ctx.llm      ctx.tools     ctx.sessions    ctx.fs   │
│    ▲             ▲              ▲             ▲      │
│    │             │              │             │      │
│ ┌──┴───┐     ┌───┴────┐    ┌────┴─────┐  ┌───┴────┐ │
│ │模型适配│     │工具注册表│    │会话日志  │  │沙箱    │ │
│ └──────┘     └────────┘    └──────────┘  └────────┘ │
│                                                      │
│  依赖注入 + 类型化事件 + 可逆副作用 + 热插拔         │
└──────────────────────────────────────────────────────┘

export const inject = ["llm", "tools", "sessions"];

export function apply(ctx: Context, config: Config) {
  // 只有 llm/tools/sessions 三个服务都就绪时，apply 才会被调用
  ctx.tools.register(myTool);
}

export function apply(ctx: Context) {
  const timer = setInterval(tick, 1000);
  ctx.effect(() => () => clearInterval(timer)); // 返回 disposer

  const off = ctx.on("session/event", onEvent);
  ctx.effect(() => off);
}

Service Definition  →  声明接口
        ▲
        │
Service Provider    →  提供一个或多个实现
        ▲
        │
Consumer            →  面向模型的工具（消费方）

// dsh-shell：Definition
export interface ShellService {
  exec(input: {
    command: string;
    cwd: string;
    timeoutMs: number;
    env?: Record<string, string>;
    signal?: AbortSignal;
  }): Promise<{
    exitCode: number;
    stdout: string;
    stderr: string;
    truncated: boolean;
  }>;
}

export const name = "shell";

// dsh-bash-local：Provider
export const inject = ["fs"];
export function apply(ctx: Context) {
  ctx.set("shell", {
    async exec({ command, cwd, timeoutMs, signal }) {
      return runLocal(command, { cwd, timeoutMs, signal });
    },
  });
}

// dsh-tool-bash：Consumer（暴露给模型的工具）
export const inject = ["shell"];
export function apply(ctx: Context) {
  ctx.tools.register({
    name: "bash",
    description: "在沙箱中执行 shell 命令",
    async execute(toolCallId, params, signal) {
      return ctx.shell.exec({ ...params, signal, timeoutMs: 120_000 });
    },
  });
}

用户目标（turn 开始）
   │
   ▼
┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│ 组装上下文   │ →  │ 模型决策     │ →  │ 执行工具     │
│ 系统提示     │    │ 思考/工具调用 │    │ 沙箱/权限    │
│ 会话历史     │    │             │    │ 结果截断     │
└─────────────┘    └──────┬──────┘    └──────┬──────┘
        ▲                  │                  │
        │                  ▼                  ▼
        │           ┌──────────────────────────────┐
        └───────────│ 追加会话事件（turn/step/tool）│
                    └──────────────────────────────┘

type SessionEvent =
  | { type: "turn/started"; turnId: string; input: string; ts: number }
  | {
      type: "step/finished";
      stepId: string;
      output: AssistantOutput;
      ts: number;
    }
  | {
      type: "tool/call";
      toolCallId: string;
      name: string;
      args: unknown;
      ts: number;
    }
  | {
      type: "tool/result";
      toolCallId: string;
      ok: boolean;
      result: unknown;
      ts: number;
    }
  | {
      type: "turn/finished";
      turnId: string;
      reason: "done" | "aborted" | "error";
      ts: number;
    };

type RunState = {
  turnId?: string;
  step: number;
  pendingToolCalls: Map<string, { name: string; args: unknown }>;
  messages: Message[];
  finished: boolean;
};

function fold(events: SessionEvent[]): RunState {
  const s: RunState = {
    step: 0,
    pendingToolCalls: new Map(),
    messages: [],
    finished: false,
  };
  for (const e of events) {
    switch (e.type) {
      case "turn/started":
        s.turnId = e.turnId;
        s.finished = false;
        break;
      case "step/finished":
        s.step += 1;
        s.messages.push(...e.output.messages);
        break;
      case "tool/call":
        s.pendingToolCalls.set(e.toolCallId, { name: e.name, args: e.args });
        break;
      case "tool/result":
        s.pendingToolCalls.delete(e.toolCallId);
        break;
      case "turn/finished":
        s.finished = true;
        break;
    }
  }
  return s;
}

普通模式：
  模型 → 工具 A → 模型 → 工具 B → 模型 → 工具 C → ...

PTC 模式：
  模型 → 生成脚本（调用 A/B/C）→ 沙箱执行 → 返回汇总结果

Profile（企业代码助手）
├── Bundle: base-tools        （read / write / bash / grep）
├── Bundle: deepseek-models   （模型适配器 + 路由）
├── Bundle: sandbox           （执行 Provider）
└── patch: team-frontend.yaml （加前端专属工具、调小上下文预算）

┌──────────────────────────────────────────────┐
│                  Harness                     │
│   循环 / 会话 / 权限 / 沙箱 / 子 Agent 调度   │
│                                              │
│   ┌─────────┐   ┌─────────┐   ┌─────────┐   │
│   │ Prompt  │   │ Skill   │   │   MCP   │   │
│   │ 本次目标 │   │ 方法    │   │ 外部工具 │   │
│   └─────────┘   └─────────┘   └─────────┘   │
└──────────────────────────────────────────────┘

Agent A（沙箱 A）
  └─ 写工作区 /workspace/report.md
       │
       │ 1. stage：临时文件 + sha256 + mediaType
       ▼
  ArtifactService.commit()
       │ 2. 原子写入对象存储（tenant/run 前缀）
       │ 3. 登记 manifest（id/version/lineage/owner/ttl）
       ▼
  对象存储 + 元数据库
       │
       ├─ 同一 run 的下一步：artifact.read(id, offset, length)
       ├─ Agent B（另一个沙箱/进程）：按 id 读取，校验 sha256 与鉴权
       └─ 生命周期任务：TTL / 引用计数 / 合规保留

export type ArtifactManifest = {
  id: string; // 全局唯一，建议带租户前缀
  version: number; // 同一逻辑产物的递增版本
  sha256: string; // 内容寻址，防止就地篡改
  mediaType: string;
  bytes: number;
  visibility: "run" | "tenant" | "public";
  owner: { tenantId: string; userId: string };
  producedBy: {
    sessionId: string;
    turnId?: string;
    toolCallId?: string;
    agentId?: string;
  };
  inputs?: string[]; // 上游产物 id，形成 lineage
  createdAt: string;
  expiresAt?: string;
  labels?: Record<string, string>;
};

async function commitArtifact(input: {
  bytes: Uint8Array;
  mediaType: string;
  visibility: "run" | "tenant" | "public";
  producedBy: ArtifactManifest["producedBy"];
  inputs?: string[];
}): Promise<ArtifactManifest> {
  const sha256 = await hashSha256(input.bytes);
  const id = `art_${sha256.slice(0, 16)}`;
  const key = `${tenantId}/${runId}/${id}`;

  await objectStore.putIfAbsent(key, input.bytes, { checksum: sha256 });
  const manifest = await metaDb.upsertArtifact({
    ...input,
    id,
    sha256,
    key,
    version: 1,
  });
  await eventBus.emit("artifact.committed", {
    id,
    sha256,
    bytes: input.bytes.length,
  });
  return manifest;
}

def handoff(artifact: ArtifactManifest, acceptance: dict) -> dict:
    """跨 Agent 交接：传引用 + 验收契约，不传裸路径。"""
    return {
        "artifact_id": artifact.id,
        "version": artifact.version,
        "sha256": artifact.sha256,
        "media_type": artifact.mediaType,
        "read_with": "artifact.read(id, offset, length)",
        "acceptance": acceptance,  # 例如 {"schema": "report.v2", "must_parse": True}
    }

type Route = {
  provider: string;
  model: string;
  supportsTools: boolean;
  maxContext: number;
  tier: "cheap" | "standard" | "strong";
};

async function callWithFallback(req: ModelRequest, ladder: Route[]) {
  for (const r of ladder) {
    if (!r.supportsTools && req.needsTools) continue;
    if (req.tokens > r.maxContext) continue;
    if (breaker(r).isOpen()) continue;
    try {
      return await llm.complete({
        ...req,
        provider: r.provider,
        model: r.model,
      });
    } catch (e) {
      if (!isRetryable(e)) throw e; // 参数错误不降级，直接暴露
      breaker(r).recordFailure();
      await sleep(backoffWithJitter(r));
    }
  }
  throw new Error("no route available");
}

trace: agent.run
├── span: turn[0]
│   ├── span: step[0]
│   │   ├── generation: model.complete   (model, tokens, cache, finish_reason)
│   │   └── span: tool.bash              (tool.name, call.id, ok, duration)
│   └── span: step[1]
└── span: artifact.commit                (artifact.id, bytes, sha256)

你要解决的是什么？
├─ 单个 Agent 长任务
│   ├─ 要插件化、审计、可回放、私有化  → DeepSeek Harness
│   ├─ 要极小内核、完全掌控上下文      → Pi
│   └─ 要开箱即用的编码体验            → Claude Code / Codex
├─ 多 Agent 业务流程编排
│   ├─ 需要可视化图与 checkpoint       → LangGraph
│   └─ 需要运行时隔离与事件审计        → LangGraph 编排 + Harness 执行
└─ 只是接模型做 Chat                    → 官方 SDK