任务分解与规划

export interface AcceptanceCriterion {  id: string;  description: string;  status: "unverified" | "passed" | "failed";  evidence?: string;}export interface PlanStep {  id: string;  title: string;  status: "pending" | "in_progress" | "completed" | "blocked";  dependsOn: string[];  completionEvidence: string;  evidence: string[];}export interface TaskPlan {  version: number;  goal: string;  acceptanceCriteria: AcceptanceCriterion[];  steps: PlanStep[];  revisionReason?: string;}export interface AgentState {  // 保留上一章的 runId、task、messages、contextSources 等字段  plan?: TaskPlan | undefined;  activeStepId?: string | undefined;  planHistory: Array<{    version: number;    reason: string;    changedAt: string;  }>;}export interface ContextKindMap {  task_plan: true;}

export interface PlanDraft {  acceptanceCriteria: Array<{ id: string; description: string }>;  steps: Array<{    id: string;    title: string;    dependsOn: string[];    completionEvidence: string;  }>;}export interface Planner {  create(input: {    goal: string;    context: string;    availableTools: string[];  }): Promise<PlanDraft>;  revise(input: {    current: TaskPlan;    reason: ReplanReason;    observations: string[];  }): Promise<PlanDraft>;  evaluate(input: {    step: PlanStep;    observations: string[];  }): Promise<{    completed: boolean;    evidence: string[];    passedCriteria: string[];    replanReason?: ReplanReason;  }>;}function isRecord(value: unknown): value is Record<string, unknown> {  return typeof value === "object" && value !== null && !Array.isArray(value);}function isAcceptanceCriterion(  value: unknown,): value is PlanDraft["acceptanceCriteria"][number] {  return (    isRecord(value) &&    typeof value.id === "string" &&    value.id.length > 0 &&    typeof value.description === "string" &&    value.description.length > 0  );}function isDraftStep(value: unknown): value is PlanDraft["steps"][number] {  return (    isRecord(value) &&    typeof value.id === "string" &&    value.id.length > 0 &&    typeof value.title === "string" &&    value.title.length > 0 &&    Array.isArray(value.dependsOn) &&    value.dependsOn.every((dependency) => typeof dependency === "string") &&    typeof value.completionEvidence === "string" &&    value.completionEvidence.length > 0  );}export function validatePlan(candidate: unknown): asserts candidate is PlanDraft {  if (!isRecord(candidate)) throw new Error("plan must be an object");  const { acceptanceCriteria, steps } = candidate;  if (!Array.isArray(acceptanceCriteria) || acceptanceCriteria.length === 0) {    throw new Error("plan requires at least one acceptance criterion");  }  if (!Array.isArray(steps) || steps.length === 0) {    throw new Error("plan requires at least one step");  }  if (!acceptanceCriteria.every(isAcceptanceCriterion)) {    throw new Error("invalid acceptance criterion");  }  if (!steps.every(isDraftStep)) throw new Error("invalid plan step");  const criterionIds = acceptanceCriteria.map((criterion) => criterion.id);  if (new Set(criterionIds).size !== criterionIds.length) {    throw new Error("duplicate acceptance criterion id");  }  const ids = steps.map((step) => step.id);  if (new Set(ids).size !== ids.length) throw new Error("duplicate step id");  const knownIds = new Set(ids);  for (const step of steps) {    if (step.dependsOn.some((dependency) => !knownIds.has(dependency))) {      throw new Error(`unknown dependency in step: ${step.id}`);    }  }  const visiting = new Set<string>();  const visited = new Set<string>();  const byId = new Map(steps.map((step) => [step.id, step]));  const visit = (id: string): void => {    if (visiting.has(id)) throw new Error("plan contains a dependency cycle");    if (visited.has(id)) return;    visiting.add(id);    for (const dependency of byId.get(id)?.dependsOn ?? []) visit(dependency);    visiting.delete(id);    visited.add(id);  };  for (const id of ids) visit(id);}export async function createInitialPlan(  goal: string,  context: string,  tools: string[],  planner: Pick<Planner, "create">,): Promise<TaskPlan> {  const draft = await planner.create({ goal, context, availableTools: tools });  validatePlan(draft);  return {    version: 1,    goal,    acceptanceCriteria: draft.acceptanceCriteria.map((criterion) => ({      ...criterion,      status: "unverified",    })),    steps: draft.steps.map((step) => ({      ...step,      status: "pending",      evidence: [],    })),  };}export function createModelPlanCreator(model: Model): Pick<Planner, "create"> {  return {    async create(input) {      const raw = await model.generate({        instructions: [          "You create short, executable plans for repository tasks.",          "Return one JSON object and no Markdown fences or commentary.",          "Use exactly this shape:",          '{"acceptanceCriteria":[{"id":"...","description":"..."}],',          '"steps":[{"id":"...","title":"...","dependsOn":[],',          '"completionEvidence":"..."}]}',          "Every step must be possible with the declared tools.",          "Every completionEvidence must describe observable evidence.",        ].join("\n"),        input: [{ role: "user", content: JSON.stringify(input) }],      });      let candidate: unknown;      try {        candidate = JSON.parse(raw);      } catch {        throw new Error("planner returned invalid JSON");      }      validatePlan(candidate);      return candidate;    },  };}

function updateStep(  plan: TaskPlan,  stepId: string,  update: (step: PlanStep) => PlanStep,): TaskPlan {  const step = plan.steps.find((candidate) => candidate.id === stepId);  if (!step) throw new Error(`unknown plan step: ${stepId}`);  return {    ...plan,    steps: plan.steps.map((candidate) =>      candidate.id === stepId ? update(candidate) : candidate,    ),  };}export function selectNextStep(plan: TaskPlan): PlanStep | undefined {  const completed = new Set(    plan.steps.filter((step) => step.status === "completed").map((step) => step.id),  );  return plan.steps.find(    (step) =>      step.status === "pending" &&      step.dependsOn.every((dependency) => completed.has(dependency)),  );}export function startStep(plan: TaskPlan, stepId: string): TaskPlan {  if (plan.steps.some((step) => step.status === "in_progress")) {    throw new Error("another plan step is already in progress");  }  const selected = selectNextStep(plan);  if (selected?.id !== stepId) throw new Error("step is not ready");  return updateStep(plan, stepId, (step) => ({ ...step, status: "in_progress" }));}export function completeStep(  plan: TaskPlan,  stepId: string,  evidence: string,): TaskPlan {  if (!evidence.trim()) throw new Error("completion evidence is required");  return updateStep(plan, stepId, (step) => {    if (step.status !== "in_progress") throw new Error("step is not in progress");    return { ...step, status: "completed", evidence: [...step.evidence, evidence] };  });}export function allCriteriaPassed(plan: TaskPlan): boolean {  return plan.acceptanceCriteria.every((criterion) => criterion.status === "passed");}

export type ReplanReason =  | "new_constraint"  | "failed_assumption"  | "repeated_tool_failure"  | "no_ready_step";export function shouldReplan(input: {  userChangedGoal: boolean;  failedAssumption: boolean;  consecutiveToolFailures: number;  plan: TaskPlan;}): ReplanReason | undefined {  if (input.userChangedGoal) return "new_constraint";  if (input.failedAssumption) return "failed_assumption";  if (input.consecutiveToolFailures >= 2) return "repeated_tool_failure";  const unfinished = input.plan.steps.some(    (step) => step.status === "pending" || step.status === "in_progress",  );  const active = input.plan.steps.some((step) => step.status === "in_progress");  if (unfinished && !active && !selectNextStep(input.plan)) return "no_ready_step";  return undefined;}export function reconcilePlan(  current: TaskPlan,  draft: PlanDraft,  reason: ReplanReason,): TaskPlan {  validatePlan(draft);  const completedSteps = new Map(    current.steps      .filter((step) => step.status === "completed")      .map((step): [string, PlanStep] => [step.id, step]),  );  const arraysEqual = (left: string[], right: string[]): boolean =>    left.length === right.length && left.every((value, index) => value === right[index]);  const sameStepContract = (previous: PlanStep, next: PlanDraft["steps"][number]): boolean =>    previous.title === next.title &&    previous.completionEvidence === next.completionEvidence &&    arraysEqual(previous.dependsOn, next.dependsOn);  const sameCriterionContract = (    previous: AcceptanceCriterion,    next: PlanDraft["acceptanceCriteria"][number],  ): boolean => previous.description === next.description;  return {    version: current.version + 1,    goal: current.goal,    revisionReason: reason,    acceptanceCriteria: draft.acceptanceCriteria.map((criterion): AcceptanceCriterion => {      const previous = current.acceptanceCriteria.find(        (candidate) => candidate.id === criterion.id,      );      const canReuse = previous && sameCriterionContract(previous, criterion);      return {        ...criterion,        status: canReuse ? previous.status : "unverified",        ...(canReuse && previous.evidence ? { evidence: previous.evidence } : {}),      };    }),    steps: draft.steps.map((step): PlanStep => {      const completed = completedSteps.get(step.id);      return completed && sameStepContract(completed, step)        ? completed        : { ...step, status: "pending", evidence: [] };    }),  };}

INITIALIZE task stateCREATE and validate initial planWHILE run is active  REPLAN only when shouldReplan(...) returns a reason  SELECT the next dependency-ready step  ASSEMBLE goal + acceptance criteria + plan summary + active step + context  DECIDE one model turn  IF tool calls exist    ACT and collect observations    REDUCE observations into step progress    COMPLETE the step only when its required evidence exists    CONTINUE the loop  IF final text exists    COMPLETE only when every step is completed and allCriteriaPassed(plan) is true    OTHERWISE continue with the first unverified criterion  STOP on cancellation, budget exhaustion, invalid output, or unrecoverable block

export function planAsContextSource(  plan: TaskPlan,  activeStep: PlanStep | undefined,): ContextSource {  return {    id: `plan:${plan.version}`,    kind: "task_plan",    label: activeStep ? `active step: ${activeStep.id}` : "current plan",    content: JSON.stringify({      goal: plan.goal,      acceptanceCriteria: plan.acceptanceCriteria,      steps: plan.steps,      activeStepId: activeStep?.id,    }),    priority: 99,  };}

export function assertEvidenceComesFromObservations(  evidence: string[],  observations: string[],): void {  if (evidence.some((item) => !observations.includes(item))) {    throw new Error("planner returned evidence outside current observations");  }}export function applyCriterionEvidence(  plan: TaskPlan,  passedCriterionIds: string[],  observations: string[],): TaskPlan {  const passed = new Set(passedCriterionIds);  for (const id of passed) {    if (!plan.acceptanceCriteria.some((criterion) => criterion.id === id)) {      throw new Error(`unknown acceptance criterion: ${id}`);    }  }  return {    ...plan,    acceptanceCriteria: plan.acceptanceCriteria.map((criterion) =>      passed.has(criterion.id)        ? { ...criterion, status: "passed", evidence: observations.join("\n") }        : criterion,    ),  };}

import { describe, expect, it } from "vitest";import {  allCriteriaPassed,  completeStep,  reconcilePlan,  selectNextStep,  shouldReplan,  startStep,} from "../src/plan.js";import { validatePlan } from "../src/planner.js";import type { AcceptanceCriterion, PlanStep, TaskPlan } from "../src/types.js";function createPlanFixture(): TaskPlan {  return {    version: 1,    goal: "修复登录失败并运行测试",    acceptanceCriteria: [      {        id: "login-test-passes",        description: "登录测试通过",        status: "unverified",      },    ],    steps: [      {        id: "reproduce",        title: "复现登录失败",        status: "pending",        dependsOn: [],        completionEvidence: "保存失败测试输出",        evidence: [],      },      {        id: "diagnose",        title: "定位失败原因",        status: "pending",        dependsOn: ["reproduce"],        completionEvidence: "记录根因和相关代码位置",        evidence: [],      },    ],  };}describe("plan state machine", () => {  it("rejects a step whose dependency is unfinished", () => {    const plan = createPlanFixture();    expect(selectNextStep(plan)?.id).toBe("reproduce");    expect(() => startStep(plan, "diagnose")).toThrow("step is not ready");  });  it("prevents two steps from running at once", () => {    const running = startStep(createPlanFixture(), "reproduce");    expect(() => startStep(running, "diagnose")).toThrow(      "another plan step is already in progress",    );  });  it("requires evidence before completing a step", () => {    const running = startStep(createPlanFixture(), "reproduce");    expect(() => completeStep(running, "reproduce", "   ")).toThrow(      "completion evidence is required",    );  });  it("replans after repeated tool failures", () => {    expect(      shouldReplan({        userChangedGoal: false,        failedAssumption: false,        consecutiveToolFailures: 2,        plan: createPlanFixture(),      }),    ).toBe("repeated_tool_failure");  });  it("preserves completed work when replanning", () => {    const running = startStep(createPlanFixture(), "reproduce");    const completed = completeStep(      running,      "reproduce",      "login.test.ts fails with 401",    );    const revised = reconcilePlan(      completed,      {        acceptanceCriteria: [          { id: "login-test-passes", description: "登录测试通过" },        ],        steps: [          {            id: "reproduce",            title: "复现登录失败",            dependsOn: [],            completionEvidence: "保存失败测试输出",          },          {            id: "diagnose",            title: "检查认证服务返回值",            dependsOn: ["reproduce"],            completionEvidence: "记录根因和相关代码位置",          },        ],      },      "failed_assumption",    );    expect(revised.version).toBe(2);    expect(revised.goal).toBe(completed.goal);    expect(revised.steps[0]).toMatchObject({      id: "reproduce",      status: "completed",      evidence: ["login.test.ts fails with 401"],    });  });  it("invalidates completed work when the step contract changes", () => {    const running = startStep(createPlanFixture(), "reproduce");    const completed = completeStep(running, "reproduce", "saved failure output");    const revised = reconcilePlan(      completed,      {        acceptanceCriteria: [{ id: "login-test-passes", description: "登录测试通过" }],        steps: [          {            id: "reproduce",            title: "复现并定位登录失败",            dependsOn: [],            completionEvidence: "保存失败测试输出与根因",          },        ],      },      "failed_assumption",    );    expect(revised.steps[0]).toMatchObject({ status: "pending", evidence: [] });  });  it("invalidates passed criteria when their description changes", () => {    const current = createPlanFixture();    const criterion = current.acceptanceCriteria[0];    if (!criterion) throw new Error("fixture criterion missing");    current.acceptanceCriteria[0] = {      ...criterion,      status: "passed",      evidence: "old evidence",    };    const revised = reconcilePlan(      current,      {        acceptanceCriteria: [          { id: "login-test-passes", description: "登录和登出测试都通过" },        ],        steps: current.steps,      },      "new_constraint",    );    expect(revised.acceptanceCriteria[0]).toEqual({      id: "login-test-passes",      description: "登录和登出测试都通过",      status: "unverified",    });  });  it("rejects duplicate acceptance criterion ids", () => {    expect(() =>      validatePlan({        acceptanceCriteria: [          { id: "same", description: "first" },          { id: "same", description: "second" },        ],        steps: [          { id: "inspect", title: "Inspect", dependsOn: [], completionEvidence: "output" },        ],      }),    ).toThrow("duplicate acceptance criterion id");  });  it("rejects early completion while criteria remain unverified", () => {    const plan = createPlanFixture();    const unverified: TaskPlan = {      ...plan,      steps: plan.steps.map(        (step): PlanStep => ({ ...step, status: "completed" }),      ),    };    expect(allCriteriaPassed(unverified)).toBe(false);    const verified: TaskPlan = {      ...unverified,      acceptanceCriteria: unverified.acceptanceCriteria.map(        (criterion): AcceptanceCriterion => ({          ...criterion,          status: "passed",          evidence: "login.test.ts passed",        }),      ),    };    expect(allCriteriaPassed(verified)).toBe(true);  });});

import { createModel } from "./model-factory.js";import { createInitialPlan, createModelPlanCreator } from "./planner.js";const goal = process.argv.slice(2).join(" ").trim();if (!goal) throw new Error("请提供要规划的任务");const offlineDraft = {  acceptanceCriteria: [    { id: "name-success", description: "--name Lin 输出 Lin" },    { id: "name-missing", description: "缺少参数值时清晰失败" },    { id: "cli-regression", description: "现有 CLI 行为保持通过" },  ],  steps: [    {      id: "inspect",      title: "读取 CLI、测试和 package.json",      dependsOn: [],      completionEvidence: "取得三个文件的 read_file observation",    },    {      id: "implement",      title: "修改 CLI 并补充成功与错误测试",      dependsOn: ["inspect"],      completionEvidence: "实现与测试文件产生受控补丁",    },    {      id: "validate",      title: "运行最窄相关测试",      dependsOn: ["implement"],      completionEvidence: "当前 revision 的 CLI 测试通过",    },  ],};const model = createModel([JSON.stringify(offlineDraft)]);const planner = createModelPlanCreator(model);const plan = await createInitialPlan(  goal,  "当前入口是 src/index.ts，现有测试是 tests/cli.test.ts。",  ["read_file", "apply_patch", "run_command"],  planner,);console.log(JSON.stringify({ goal, plan }, null, 2));

pnpm dev -- "给示例 CLI 增加 --name 参数并补充测试"MODEL_MODE=openai pnpm dev -- "给示例 CLI 增加 --name 参数并补充测试"