从一次模型调用到自进化 Harness：逐步实现自动修复 GitHub Issue Agent

import { readFile } from "node:fs/promises";

type Message = {
  role: "system" | "user";
  content: string;
};

type Issue = {
  number: number;
  title: string;
  body: string;
};

async function callModel(messages: Message[]): Promise<string> {
  const endpoint =
    process.env.MODEL_ENDPOINT ??
    "http://localhost:8000/v1/chat/completions";

  const response = await fetch(endpoint, {
    method: "POST",
    headers: {
      "content-type": "application/json",
      authorization: "Bearer " + (process.env.MODEL_API_KEY ?? ""),
    },
    body: JSON.stringify({
      model: process.env.MODEL_NAME ?? "coding-model",
      temperature: 0,
      messages,
    }),
  });

  if (!response.ok) {
    throw new Error("model request failed: " + response.status);
  }

  const body = (await response.json()) as {
    choices?: Array<{ message?: { content?: unknown } }>;
  };
  const content = body.choices?.[0]?.message?.content;
  if (typeof content !== "string") {
    throw new Error("model response did not contain text");
  }
  return content;
}

async function proposePatch(issue: Issue, repoDir: string): Promise<string> {
  const repositoryContext = [
    "=== src/validate-items.ts ===",
    await readFile(repoDir + "/src/validate-items.ts", "utf8"),
    "=== tests/validate-items.test.ts ===",
    await readFile(repoDir + "/tests/validate-items.test.ts", "utf8"),
  ].join("\n\n");

  return callModel([
    {
      role: "system",
      content: [
        "你是代码修复助手。",
        "根据 Issue 和有限的仓库上下文生成 unified diff。",
        "只返回可以交给 git apply 的补丁，不要解释。",
        "补丁必须包含源代码修改和回归测试。",
      ].join("\n"),
    },
    {
      role: "user",
      content: [
        `Issue #${issue.number}: ${issue.title}`,
        issue.body,
        repositoryContext,
      ].join("\n\n"),
    },
  ]);
}

const proposedPatch = await proposePatch(
  {
    number: 1842,
    title: "空数组输入会让 /v1/items 返回 500",
    body: [
      "预期行为：返回 400，并给出明确的参数错误。",
      "必须补充回归测试。",
    ].join("\n"),
  },
  process.cwd(),
);

console.log(proposedPatch);

const improvedInstructions = [
  "你是代码修复助手。",
  "任何行为修复都必须增加或更新覆盖 Issue 场景的回归测试。",
  "只返回 unified diff；补丁必须同时包含实现修改和测试修改。",
].join("\n");

const improvedContext = [
  "=== repository rules ===",
  await readFile(repoDir + "/CONTRIBUTING.md", "utf8"),
  "=== implementation ===",
  await readFile(repoDir + "/src/validate-items.ts", "utf8"),
  "=== regression tests ===",
  await readFile(repoDir + "/tests/validate-items.test.ts", "utf8"),
  "=== test command ===",
  "pnpm test --filter validate-items",
].join("\n\n");

import { execFile } from "node:child_process";
import { promisify } from "node:util";
import { writeFile } from "node:fs/promises";

const execFileAsync = promisify(execFile);

type CommandResult = {
  ok: boolean;
  stdout: string;
  stderr: string;
  exitCode: number;
};

async function run(
  cwd: string,
  command: string,
  args: string[],
): Promise<CommandResult> {
  try {
    const result = await execFileAsync(command, args, { cwd });
    return {
      ok: true,
      stdout: result.stdout,
      stderr: result.stderr,
      exitCode: 0,
    };
  } catch (error) {
    const failure = error as {
      stdout?: string;
      stderr?: string;
      code?: number;
    };
    return {
      ok: false,
      stdout: failure.stdout ?? "",
      stderr: failure.stderr ?? "",
      exitCode: typeof failure.code === "number" ? failure.code : 1,
    };
  }
}

async function inspectRepository(repoDir: string) {
  const status = await run(repoDir, "git", ["status", "--short"]);
  const candidates = await run(repoDir, "rg", [
    "-n",
    "items|validate",
    "src",
    "tests",
  ]);
  return {
    status,
    candidates,
  };
}

async function applyPatch(repoDir: string, patch: string) {
  const patchFile = repoDir + "/.dsh-issue.patch";
  await writeFile(patchFile, patch, "utf8");
  const result = await run(repoDir, "git", ["apply", patchFile]);
  if (!result.ok) {
    throw new Error("patch did not apply: " + result.stderr);
  }
}

async function readDiff(repoDir: string): Promise<string> {
  const result = await run(repoDir, "git", ["diff", "--"]);
  if (!result.ok) {
    throw new Error("cannot read diff: " + result.stderr);
  }
  return result.stdout;
}

type Approval = "allowed-once" | "rejected" | "cancelled" | "unavailable";

declare function waitForApproval(input: {
  action: "push-and-create-pr";
  summary: string;
}): Promise<Approval>;

declare const github: {
  createPullRequest(input: {
    repository: string;
    head: string;
    base: string;
    title: string;
    body: string;
  }): Promise<string>;
};

async function repairIssue(
  issue: {
    repository: string;
    number: number;
    title: string;
    body: string;
  },
  repoDir: string,
) {
  const branch = "agent/issue-" + issue.number;
  const branchResult = await run(repoDir, "git", ["switch", "-c", branch]);
  if (!branchResult.ok) {
    return { status: "blocked", reason: branchResult.stderr };
  }

  const repository = await inspectRepository(repoDir);
  const diagnosis = await callModel([
    {
      role: "system",
      content: "分析 Issue 和仓库信息，输出根因假设、相关文件和验证命令。",
    },
    {
      role: "user",
      content: JSON.stringify({ issue, repository }),
    },
  ]);

  let patch = await callModel([
    {
      role: "system",
      content: [
        "根据 Issue、仓库检索结果和根因假设生成 unified diff。",
        "必须同时修改实现和回归测试。",
        "只返回补丁。",
      ].join("\n"),
    },
    {
      role: "user",
      content: JSON.stringify({ issue, repository, diagnosis }),
    },
  ]);
  await applyPatch(repoDir, patch);

  let test = await run(repoDir, "pnpm", [
    "test",
    "--",
    "validate-items",
  ]);

  for (let attempt = 1; !test.ok && attempt <= 2; attempt += 1) {
    patch = await callModel([
      {
        role: "system",
        content: "根据失败测试输出生成下一版 unified diff，只返回补丁。",
      },
      {
        role: "user",
        content: JSON.stringify({
          issue,
          previousDiagnosis: diagnosis,
          testOutput: test,
        }),
      },
    ]);
    await applyPatch(repoDir, patch);
    test = await run(repoDir, "pnpm", [
      "test",
      "--",
      "validate-items",
    ]);
  }

  const diff = await readDiff(repoDir);
  if (!test.ok) {
    return {
      status: "blocked",
      reason: "tests failed",
      test,
      diff,
    };
  }
  if (!diff.includes("tests/")) {
    return {
      status: "blocked",
      reason: "no regression test was added",
      test,
      diff,
    };
  }

  const approval = await waitForApproval({
    action: "push-and-create-pr",
    summary: [
      "Issue #" + issue.number,
      "branch: " + branch,
      "tests: passed",
      "changed files include a regression test",
    ].join("\n"),
  });
  if (approval !== "allowed-once") {
    return { status: "waiting-or-rejected", approval, diff };
  }

  const staged = await run(repoDir, "git", ["add", "-A"]);
  if (!staged.ok) return { status: "blocked", reason: staged.stderr };
  const committed = await run(repoDir, "git", [
    "commit",
    "-m",
    "fix: handle empty items for issue " + issue.number,
  ]);
  if (!committed.ok) return { status: "blocked", reason: committed.stderr };

  const pushed = await run(repoDir, "git", [
    "push",
    "--set-upstream",
    "origin",
    branch,
  ]);
  if (!pushed.ok) return { status: "blocked", reason: pushed.stderr };

  const url = await github.createPullRequest({
    repository: issue.repository,
    head: branch,
    base: "main",
    title: "Fix #" + issue.number + ": " + issue.title,
    body: [
      "## Summary",
      diagnosis,
      "",
      "## Tests",
      "pnpm test -- validate-items",
    ].join("\n"),
  });

  return { status: "pull-request-created", url };
}

type CompletionCheck = {
  name: string;
  run: () => Promise<{ ok: boolean; reason?: string }>;
};

const checks: CompletionCheck[] = [
  { name: "tests", run: () => verifyTests(repoDir) },
  { name: "issue-behavior", run: () => verifyIssueBehavior(issue, repoDir) },
  {
    name: "regression-test",
    run: () =>
      isBehaviorIssue(issue)
        ? verifyRegressionTest(issue, repoDir)
        : Promise.resolve({ ok: true }),
  },
];

for (const check of checks) {
  const result = await check.run();
  if (!result.ok) {
    return { status: "blocked", reason: check.name + ": " + result.reason };
  }
}

type ToolCall = {
  id: string;
  name: string;
  arguments: Record<string, unknown>;
};

type LoopMessage = {
  role: "system" | "user" | "assistant" | "tool";
  content: string;
  toolCallId?: string;
  toolCalls?: ToolCall[];
};

type ModelWithToolsResponse = {
  content?: string;
  toolCalls?: ToolCall[];
};

declare function callModelWithTools(input: {
  messages: LoopMessage[];
  tools: Array<{
    name: string;
    description: string;
    inputSchema: Record<string, unknown>;
  }>;
}): Promise<ModelWithToolsResponse>;

declare function readRepository(
  repoDir: string,
  query: string,
): Promise<unknown>;

declare function editRepository(
  repoDir: string,
  patch: string,
): Promise<unknown>;

declare function runRepositoryTests(
  repoDir: string,
  command: string,
): Promise<{ ok: boolean; stdout: string; stderr: string }>;

type Approval = "allowed-once" | "rejected" | "cancelled" | "unavailable";

declare function verifyRegressionTest(input: {
  repoDir: string;
  issue: { title: string; body: string };
}): Promise<boolean>;

declare function requestApproval(input: {
  action: "push-and-create-pr";
  summary: string;
}): Promise<Approval>;

declare function createPullRequest(input: {
  repository: string;
  branch: string;
  title: string;
  body: string;
}): Promise<string>;

const tools = [
  {
    name: "inspect_repository",
    description: "搜索仓库并返回相关文件、Git 状态和项目规则。",
    inputSchema: {
      type: "object",
      properties: { query: { type: "string" } },
      required: ["query"],
    },
  },
  {
    name: "apply_patch",
    description: "在当前隔离工作区应用 unified diff。",
    inputSchema: {
      type: "object",
      properties: { patch: { type: "string" } },
      required: ["patch"],
    },
  },
  {
    name: "run_tests",
    description: "运行与当前 Issue 相关的测试并返回真实退出结果。",
    inputSchema: {
      type: "object",
      properties: { command: { type: "string" } },
      required: ["command"],
    },
  },
  {
    name: "create_pull_request",
    description: "推送分支并创建 Pull Request，需要用户一次性审批。",
    inputSchema: {
      type: "object",
      properties: {
        title: { type: "string" },
        body: { type: "string" },
      },
      required: ["title", "body"],
    },
  },
];

async function runIssueAgent(
  issue: { repository: string; number: number; title: string; body: string },
  repoDir: string,
) {
  const messages: LoopMessage[] = [
    {
      role: "system",
      content: [
        "你负责修复一个 GitHub Issue。",
        "必须检查仓库、修改代码、增加回归测试并运行测试。",
        "只有测试和回归检查完成后，才可以请求创建 PR。",
        "不要把自然语言中的完成声明当作证据。",
      ].join("\n"),
    },
    {
      role: "user",
      content: JSON.stringify(issue),
    },
  ];

  const state = {
    testsPassed: false,
    regressionTestObserved: false,
    pullRequestUrl: undefined as string | undefined,
  };

  for (let step = 0; step < 20; step += 1) {
    const response = await callModelWithTools({ messages, tools });

    if (response.toolCalls && response.toolCalls.length > 0) {
      messages.push({
        role: "assistant",
        content: response.content ?? "",
        toolCalls: response.toolCalls,
      });

      for (const call of response.toolCalls) {
        let result: unknown;
        if (call.name === "inspect_repository") {
          result = await readRepository(
            repoDir,
            String(call.arguments.query ?? ""),
          );
        } else if (call.name === "apply_patch") {
          result = await editRepository(
            repoDir,
            String(call.arguments.patch ?? ""),
          );
        } else if (call.name === "run_tests") {
          const test = await runRepositoryTests(
            repoDir,
            String(call.arguments.command ?? ""),
          );
          state.testsPassed = test.ok;
          state.regressionTestObserved = await verifyRegressionTest({
            repoDir,
            issue,
          });
          result = test;
        } else if (call.name === "create_pull_request") {
          if (!state.testsPassed) {
            result = {
              ok: false,
              error: "cannot create PR before tests pass",
            };
          } else if (!state.regressionTestObserved) {
            result = {
              ok: false,
              error: "cannot create PR without regression-test evidence",
            };
          } else {
            const approval = await requestApproval({
              action: "push-and-create-pr",
              summary: String(call.arguments.title ?? ""),
            });
            if (approval !== "allowed-once") {
              result = { ok: false, error: "approval was not granted" };
            } else {
              state.pullRequestUrl = await createPullRequest({
                repository: issue.repository,
                branch: "agent/issue-" + issue.number,
                title: String(call.arguments.title ?? ""),
                body: String(call.arguments.body ?? ""),
              });
              result = { ok: true, url: state.pullRequestUrl };
            }
          }
        } else {
          result = { ok: false, error: "unknown tool: " + call.name };
        }

        messages.push({
          role: "tool",
          toolCallId: call.id,
          content: JSON.stringify(result),
        });
      }
      continue;
    }

    if (response.content) {
      if (state.pullRequestUrl) {
        return { status: "completed", message: response.content };
      }
      messages.push({
        role: "user",
        content: [
          "任务还没有完成。",
          "必须继续工作，直到获得测试通过、回归测试证据和审批后的 PR URL。",
        ].join("\n"),
      });
    }
  }

  return { status: "budget-exhausted" };
}

function toToolObservation(result: {
  exitCode: number;
  stdout: string;
  stderr: string;
}) {
  return {
    ok: result.exitCode === 0,
    exitCode: result.exitCode,
    stdout: result.stdout.slice(-8000),
    stderr: result.stderr.slice(-8000),
    nextHint:
      result.exitCode === 0
        ? "可以继续检查 Issue 行为。"
        : "先判断失败来自实现、测试命令还是环境，再决定是否重试。",
  };
}

import { createInterface } from "node:readline/promises";
import { stdin as input, stdout as output } from "node:process";
import { query } from "@anthropic-ai/claude-agent-sdk";

const repoDir = process.env.REPOSITORY_DIR ?? process.cwd();

type GithubIssue = {
  number: number;
  title: string;
  body: string;
};

function formatIssue(issue: GithubIssue): string {
  return [`Issue #${issue.number}：${issue.title}`, issue.body].join("\n");
}

const highRiskCommand = /\bgit\s+push\b|\bgh\s+pr\s+create\b/;

async function requestApproval(summary: string): Promise<boolean> {
  const terminal = createInterface({ input, output });
  try {
    const answer = await terminal.question(
      `\n需要审批的操作：${summary}\n输入 y 才允许继续：`,
    );
    return answer.trim().toLowerCase() === "y";
  } finally {
    terminal.close();
  }
}

declare function verifyIssueBeforePublish(input: {
  issue: GithubIssue
  repoDir: string
  command: string
}): Promise<{ ok: boolean; reason?: string }>

async function runIssueFixerAgent(
  issue: GithubIssue,
  repoDir: string,
): Promise<void> {
  for await (const message of query({
    prompt: [
      "你负责在一个隔离的 GitHub 仓库工作区中修复下面的 Issue。",
      formatIssue(issue),
      "先检查仓库规则、实现和现有测试，再定位根因。",
      "修改源代码并补充回归测试，运行与变更相关的测试。",
      "测试和独立验证通过后，才可以请求 git push 和 gh pr create。",
      "不要通过改写命令、脚本或其他工具绕过高风险操作审批。",
    ].join("\n\n"),
    options: {
      cwd: repoDir,
      // 这些工具可自动使用；Bash 留给 canUseTool 做逐次判断。
      allowedTools: ["Read", "Edit", "Glob", "Grep"],
      permissionMode: "default",
      canUseTool: async (toolName, toolInput) => {
        if (toolName === "Bash") {
          const command =
            typeof toolInput.command === "string" ? toolInput.command : "";

          if (highRiskCommand.test(command)) {
            const verdict = await verifyIssueBeforePublish({
              issue,
              repoDir,
              command,
            });
            if (!verdict.ok) {
              return {
                behavior: "deny",
                message: verdict.reason ?? "独立验证没有通过。",
              };
            }

            const approved = await requestApproval(command);
            if (!approved) {
              return {
                behavior: "deny",
                message: "用户没有批准该高风险 Git 操作。",
              };
            }
          }

          return { behavior: "allow", updatedInput: toolInput };
        }

        return {
          behavior: "deny",
          message: `工具 ${toolName} 不在这个任务的允许范围内。`,
        };
      },
    },
  })) {
    if (message.type === "result") {
      console.log(JSON.stringify(message));
    }
  }
}

await runIssueFixerAgent(
  {
    number: 1842,
    title: "空数组输入会让 /v1/items 返回 500",
    body: [
      "预期行为：返回 400，并给出明确的参数错误。",
      "要求：补充覆盖空数组场景的回归测试。",
    ].join("\n"),
  },
  repoDir,
);

// verifier 的实现由 IssueFixer 应用提供：重新运行测试、检查 Issue 行为和
// diff；SDK 的最终文本本身不能作为完成证据。

const message = createUserMessage({
  content: [{ type: 'text', text: '修复 GitHub Issue #1842' }],
  source: { kind: 'user' },
})

agent.followup(message)
await agent.whenIdle()

followup(message) {
  inbox.nextTurn.push(message)
  wakeAgentLoop()
}

await agent.whenIdle()
await ctx.sessions.flush(agent.session)
const events = agent.session.events

async function createIssueFixerRuntime(
  repoDir: string,
  sessionRoot: string,
) {
  const ctx = new Context()

  // 测试支持包安装 LLM、Session、system-prompt、工具注册表和 Agent Registry。
  await mountAgentLoopTestDependencies(ctx, {
    systemPrompt: {
      persona: 'You are an IssueFixer. Verify changes with real tests.',
    },
  })

  // 安装 Agent Loop；agents: [] 表示启动时不创建具体 Agent。
  await ctx.plugin(AgentLoop, { agents: [] })

  // 安装真实模型适配器。
  await ctx.plugin(LlmDeepSeek, {
    models: [{ id: 'deepseek-v4-flash', contextWindow: 128000 }],
  })

  // 安装 Bash 工具需要的本地进程和 Shell 能力。
  await ctx.plugin(LocalSubprocessRuntime)
  await ctx.plugin(BashEnvPlugin)
  await ctx.plugin(LocalBashExecutor, {
    cwd: repoDir,
    timeoutMs: 30_000,
  })
  await ctx.plugin(ToolBash)

  // 生产代码还应在这里安装 GitHub Provider、审批和 IssueFixer 业务插件。
  await ctx.plugin(JsonlSessionPersistence, { root: sessionRoot })
  await ctx.plugin(SessionCheckpointPolicy)

  return ctx
}

type GithubIssue = {
  repository: string
  number: number
  title: string
  body: string
}

function issuePrompt(issue: GithubIssue): string {
  return [
    '你负责修复一个 GitHub Issue。',
    '仓库：' + issue.repository,
    'Issue #' + issue.number + '：' + issue.title,
    issue.body,
    '先检查仓库规则、定位根因，再修改代码和回归测试。',
    '运行相关测试，只有完成验证后才请求创建 PR。',
  ].join('\n\n')
}

async function runIssueFixer(
  ctx: Context,
  issue: GithubIssue,
  repoDir: string,
) {
  const { agent } = await ctx.agents.create({
    sessionId: SessionId('github-issue-' + issue.number),
    meta: { cwd: repoDir },
    agentOptions: {
      provider: 'deepseek-official',
      model: 'deepseek-v4-flash',
    },
  })

  agent.followup(createUserMessage({
    content: [{ type: 'text', text: issuePrompt(issue) }],
    source: { kind: 'user' },
  }))

  await agent.whenIdle()
  await ctx.sessions.flush(agent.session)

  return agent.session.events
}

async function ensureSession(
  sessionId: SessionId,
  cwd: string,
  presetId?: string,
): Promise<Agent> {
  const live = ctx.agents.get(sessionId)
  if (live !== undefined) return live

  const composition = await composeAgent(presetId)

  return (await ctx.agents.create({
    sessionId,
    meta: {
      cwd,
      agentPreset: composition.agentPreset,
    },
    agentOptions: agentOptions(),
    setup: composition.setup,
  })).agent
}

const inspected = await persistence.inspect(sessionId)
const composition = await composeAgent(
  resolveSessionPreset(inspected),
)

const { agent } = await ctx.agents.resume({
  resumeSessionId: sessionId,
  setup: composition.setup,
})

const agent = await agentFor(sessionId)

const message = createUserMessage({
  content,
  source: { kind: 'user', rpcId },
})

agent.followup(message)

const created = await api.sessions.create({
  cwd: '/workspace/example-service',
  agentPreset: 'issue-fixer',
})

await api.sessions.prompt({
  sessionId: created.sessionId,
  mode: 'queue',
  content: [{
    type: 'text',
    text: issuePrompt(issue),
  }],
})

import type { Context } from '@deepseek-ai/cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'
import type {
  PreToolDecision,
  ToolExecution,
} from '@deepseek-ai/dsh-tools'

type GithubIssue = {
  repository: string
  number: number
  title: string
  body: string
}

type IssueFixerConfig = {
  issue: GithubIssue
  repoDir: string
}

type GithubApi = {
  pushAndCreatePullRequest(input: {
    repository: string
    branch: string
    title: string
    body: string
  }): Promise<string>
}

// GithubApi 的 Service Definition/Provider 省略；这里演示 Consumer。
function githubApi(ctx: Context): GithubApi {
  const api = ctx.get('github')
  if (api === undefined) throw new Error('GitHub Provider is not mounted')
  return api as GithubApi
}

export const name = 'issue-fixer-github'
export const inject = ['tools'] as const

export function apply(ctx: Context, config: IssueFixerConfig): void {
  const github = githubApi(ctx)

  ctx.tools.register(defineTool({
    name: 'github_create_pull_request',
    description: '推送已验证的分支并创建 Pull Request。',
    parameters: {
      branch: { type: 'string', required: true },
      title: { type: 'string', required: true },
      body: { type: 'string', required: true },
    },
    output: {
      schema: { type: 'string' },
      render: (_args, url) => [{ type: 'text', text: url }],
    },
    async execute(args) {
      return github.pushAndCreatePullRequest({
        repository: config.issue.repository,
        ...args,
      })
    },
  }))

  ctx.on('tools/pre-execute', async (
    execution: ToolExecution,
    next: () => Promise<PreToolDecision>,
  ): Promise<PreToolDecision> => {
    if (execution.name !== 'github_create_pull_request') {
      return next()
    }

    const verdict = await verifyIssue({
      issue: config.issue,
      repoDir: config.repoDir,
      candidate: execution.arguments,
    })

    if (!verdict.ok) {
      return {
        kind: 'deny',
        reason: verdict.reason ?? '独立验证没有通过。',
      }
    }

    return {
      kind: 'ask',
      reason: '测试和 diff 已通过，准备推送分支并创建 PR。',
    }
  })
}

declare function verifyIssue(input: {
  issue: GithubIssue
  repoDir: string
  candidate: unknown
}): Promise<{ ok: boolean; reason?: string }>

const { agent } = await ctx.agents.create({
  sessionId,
  meta: { cwd: repoDir },
  agentOptions: {
    provider: 'deepseek-official',
    model: 'deepseek-v4-flash',
  },
  setup: async (agentCtx) => {
    await agentCtx.plugin(IssueFixerGithubPlugin, {
      issue,
      repoDir,
    })
  },
})

const presets = ctx.get('agentPresets')
if (presets === undefined) throw new Error('agent preset roster is not mounted')

setup: async (agentCtx) => {
  await presets.mount(agentCtx, 'issue-fixer')
}