Claude code学习5 动态prompt的组装1

const dynamicSections = [
  systemPromptSection("session_guidance", () => getSessionSpecificGuidanceSection(enabledTools, skillToolCommands)),
  systemPromptSection("memory", () => loadMemoryPrompt()),
  systemPromptSection("ant_model_override", () => getAntModelOverrideSection()),
  systemPromptSection("env_info_simple", () => computeSimpleEnvInfo(model, additionalWorkingDirectories)),
  systemPromptSection("language", () => getLanguageSection(settings.language)),
  systemPromptSection("output_style", () => getOutputStyleSection(outputStyleConfig)),
  // When delta enabled, instructions are announced via persisted
  // mcp_instructions_delta attachments (attachments.ts) instead of this
  // per-turn recompute, which busts the prompt cache on late MCP connect.
  // Gate check inside compute (not selecting between section variants)
  // so a mid-session gate flip doesn't read a stale cached value.
  DANGEROUS_uncachedSystemPromptSection(
    "mcp_instructions",
    () => (isMcpInstructionsDeltaEnabled() ? null : getMcpInstructionsSection(mcpClients)),
    "MCP servers connect/disconnect between turns"
  ),
  systemPromptSection("scratchpad", () => getScratchpadInstructions()),
  systemPromptSection("frc", () => getFunctionResultClearingSection(model)),
  systemPromptSection("summarize_tool_results", () => SUMMARIZE_TOOL_RESULTS_SECTION),
  // Numeric length anchors — research shows ~1.2% output token reduction vs
  // qualitative "be concise". Ant-only to measure quality impact first.
  ...(process.env.USER_TYPE === "ant"
    ? [
        systemPromptSection(
          "numeric_length_anchors",
          () =>
            "Length limits: keep text between tool calls to \u226425 words. Keep final responses to \u2264100 words unless the task requires more detail."
        ),
      ]
    : []),
  ...(feature("TOKEN_BUDGET")
    ? [
        // Cached unconditionally — the "When the user specifies..." phrasing
        // makes it a no-op with no budget active. Was DANGEROUS_uncached
        // (toggled on getCurrentTurnTokenBudget()), busting ~20K tokens per
        // budget flip. Not moved to a tail attachment: first-response and
        // budget-continuation paths don't see attachments (#21577).
        systemPromptSection(
          "token_budget",
          () =>
            'When the user specifies a token target (e.g., "+500k", "spend 2M tokens", "use 1B tokens"), your output token count will be shown each turn. Keep working until you approach the target \u2014 plan your work to fill it productively. The target is a hard minimum, not a suggestion. If you stop early, the system will automatically continue you.'
        ),
      ]
    : []),
  ...(feature("KAIROS") || feature("KAIROS_BRIEF") ? [systemPromptSection("brief", () => getBriefSection())] : []),
];

/**
 * Create a memoized system prompt section.
 * Computed once, cached until /clear or /compact.
 */
export function systemPromptSection(name: string, compute: ComputeFn): SystemPromptSection {
  return { name, compute, cacheBreak: false };
}

/**
 * Create a volatile system prompt section that recomputes every turn.
 * This WILL break the prompt cache when the value changes.
 * Requires a reason explaining why cache-breaking is necessary.
 */
export function DANGEROUS_uncachedSystemPromptSection(name: string, compute: ComputeFn, _reason: string): SystemPromptSection {
  return { name, compute, cacheBreak: true };
}

export async function resolveSystemPromptSections(sections: SystemPromptSection[]): Promise<(string | null)[]> {
  const cache = getSystemPromptSectionCache();

  return Promise.all(
    sections.map(async (s) => {
      if (!s.cacheBreak && cache.has(s.name)) {
        return cache.get(s.name) ?? null;
      }
      const value = await s.compute();
      setSystemPromptSectionCacheEntry(s.name, value);
      return value;
    })
  );
}

function getSessionSpecificGuidanceSection(enabledTools: Set<string>, skillToolCommands: Command[]): string | null {
  const hasAskUserQuestionTool = enabledTools.has(ASK_USER_QUESTION_TOOL_NAME);
  const hasSkills = skillToolCommands.length > 0 && enabledTools.has(SKILL_TOOL_NAME);
  const hasAgentTool = enabledTools.has(AGENT_TOOL_NAME);
  const searchTools = hasEmbeddedSearchTools() ? `\`find\` or \`grep\` via the ${BASH_TOOL_NAME} tool` : `the ${GLOB_TOOL_NAME} or ${GREP_TOOL_NAME}`;

  const items = [
    hasAskUserQuestionTool
      ? `If you do not understand why the user has denied a tool call, use the ${ASK_USER_QUESTION_TOOL_NAME} to ask them.`
      : null,
    getIsNonInteractiveSession()
      ? null
      : `If you need the user to run a shell command themselves (e.g., an interactive login like \`gcloud auth login\`), suggest they type \`! <command>\` in the prompt — the \`!\` prefix runs the command in this session so its output lands directly in the conversation.`,
    // isForkSubagentEnabled() reads getIsNonInteractiveSession() — must be
    // post-boundary or it fragments the static prefix on session type.
    hasAgentTool ? getAgentToolSection() : null,
    ...(hasAgentTool && areExplorePlanAgentsEnabled() && !isForkSubagentEnabled()
      ? [
          `For simple, directed codebase searches (e.g. for a specific file/class/function) use ${searchTools} directly.`,
          `For broader codebase exploration and deep research, use the ${AGENT_TOOL_NAME} tool with subagent_type=${EXPLORE_AGENT.agentType}. This is slower than using ${searchTools} directly, so use this only when a simple, directed search proves to be insufficient or when your task will clearly require more than ${EXPLORE_AGENT_MIN_QUERIES} queries.`,
        ]
      : []),
    hasSkills
      ? `/<skill-name> (e.g., /commit) is shorthand for users to invoke a user-invocable skill. When executed, the skill gets expanded to a full prompt. Use the ${SKILL_TOOL_NAME} tool to execute them. IMPORTANT: Only use ${SKILL_TOOL_NAME} for skills listed in its user-invocable skills section - do not guess or use built-in CLI commands.`
      : null,
    DISCOVER_SKILLS_TOOL_NAME !== null && hasSkills && enabledTools.has(DISCOVER_SKILLS_TOOL_NAME) ? getDiscoverSkillsGuidance() : null,
    hasAgentTool &&
    feature("VERIFICATION_AGENT") &&
    // 3P default: false — verification agent is ant-only A/B
    getFeatureValue_CACHED_MAY_BE_STALE("tengu_hive_evidence", false)
      ? `The contract: when non-trivial implementation happens on your turn, independent adversarial verification must happen before you report completion \u2014 regardless of who did the implementing (you directly, a fork you spawned, or a subagent). You are the one reporting to the user; you own the gate. Non-trivial means: 3+ file edits, backend/API changes, or infrastructure changes. Spawn the ${AGENT_TOOL_NAME} tool with subagent_type="${VERIFICATION_AGENT_TYPE}". Your own checks, caveats, and a fork's self-checks do NOT substitute \u2014 only the verifier assigns a verdict; you cannot self-assign PARTIAL. Pass the original user request, all files changed (by anyone), the approach, and the plan file path if applicable. Flag concerns if you have them but do NOT share test results or claim things work. On FAIL: fix, resume the verifier with its findings plus your fix, repeat until PASS. On PASS: spot-check it \u2014 re-run 2-3 commands from its report, confirm every PASS has a Command run block with output that matches your re-run. If any PASS lacks a command block or diverges, resume the verifier with the specifics. On PARTIAL (from the verifier): report what passed and what could not be verified.`
      : null,
  ].filter((item) => item !== null);

  if (items.length === 0) return null;
  return ["# Session-specific guidance", ...prependBullets(items)].join("\n");
}

// isForkSubagentEnabled() reads getIsNonInteractiveSession() — must be
// post-boundary or it fragments the static prefix on session type.
function getAgentToolSection(): string {
  return isForkSubagentEnabled()
    ? `Calling ${AGENT_TOOL_NAME} without a subagent_type creates a fork, which runs in the background and keeps its tool output out of your context \u2014 so you can keep chatting with the user while it works. Reach for it when research or multi-step implementation work would otherwise fill your context with raw output you won't need again. **If you ARE the fork** \u2014 execute directly; do not re-delegate.`
    : `Use the ${AGENT_TOOL_NAME} tool with specialized agents when the task at hand matches the agent's description. Subagents are valuable for parallelizing independent queries or for protecting the main context window from excessive results, but they should not be used excessively when not needed. Importantly, avoid duplicating work that subagents are already doing - if you delegate research to a subagent, do not also perform the same searches yourself.`;
}

/**
 * Load the unified memory prompt for inclusion in the system prompt.
 * Dispatches based on which memory systems are enabled:
 *   - auto + team: combined prompt (both directories)
 *   - auto only: memory lines (single directory)
 * Team memory requires auto memory (enforced by isTeamMemoryEnabled), so
 * there is no team-only branch.
 *
 * Returns null when auto memory is disabled.
 */
export async function loadMemoryPrompt(): Promise<string | null> {
  const autoEnabled = isAutoMemoryEnabled();

  const skipIndex = getFeatureValue_CACHED_MAY_BE_STALE("tengu_moth_copse", false);

  // KAIROS daily-log mode takes precedence over TEAMMEM: the append-only
  // log paradigm does not compose with team sync (which expects a shared
  // MEMORY.md that both sides read + write). Gating on `autoEnabled` here
  // means the !autoEnabled case falls through to the tengu_memdir_disabled
  // telemetry block below, matching the non-KAIROS path.
  if (feature("KAIROS") && autoEnabled && getKairosActive()) {
    logMemoryDirCounts(getAutoMemPath(), {
      memory_type: "auto" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
    });
    return buildAssistantDailyLogPrompt(skipIndex);
  }

  // Cowork injects memory-policy text via env var; thread into all builders.
  const coworkExtraGuidelines = process.env.CLAUDE_COWORK_MEMORY_EXTRA_GUIDELINES;
  const extraGuidelines = coworkExtraGuidelines && coworkExtraGuidelines.trim().length > 0 ? [coworkExtraGuidelines] : undefined;

  if (feature("TEAMMEM")) {
    if (teamMemPaths!.isTeamMemoryEnabled()) {
      const autoDir = getAutoMemPath();
      const teamDir = teamMemPaths!.getTeamMemPath();
      // Harness guarantees these directories exist so the model can write
      // without checking. The prompt text reflects this ("already exists").
      // Only creating teamDir is sufficient: getTeamMemPath() is defined as
      // join(getAutoMemPath(), 'team'), so recursive mkdir of the team dir
      // creates the auto dir as a side effect. If the team dir ever moves
      // out from under the auto dir, add a second ensureMemoryDirExists call
      // for autoDir here.
      await ensureMemoryDirExists(teamDir);
      logMemoryDirCounts(autoDir, {
        memory_type: "auto" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
      });
      logMemoryDirCounts(teamDir, {
        memory_type: "team" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
      });
      return teamMemPrompts!.buildCombinedMemoryPrompt(extraGuidelines, skipIndex);
    }
  }

  if (autoEnabled) {
    const autoDir = getAutoMemPath();
    // Harness guarantees the directory exists so the model can write without
    // checking. The prompt text reflects this ("already exists").
    await ensureMemoryDirExists(autoDir);
    logMemoryDirCounts(autoDir, {
      memory_type: "auto" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
    });
    return buildMemoryLines("auto memory", autoDir, extraGuidelines, skipIndex).join("\n");
  }

  logEvent("tengu_memdir_disabled", {
    disabled_by_env_var: isEnvTruthy(process.env.CLAUDE_CODE_DISABLE_AUTO_MEMORY),
    disabled_by_setting: !isEnvTruthy(process.env.CLAUDE_CODE_DISABLE_AUTO_MEMORY) && getInitialSettings().autoMemoryEnabled === false,
  });
  // Gate on the GB flag directly, not isTeamMemoryEnabled() — that function
  // checks isAutoMemoryEnabled() first, which is definitionally false in this
  // branch. We want "was this user in the team-memory cohort at all."
  if (getFeatureValue_CACHED_MAY_BE_STALE("tengu_herring_clock", false)) {
    logEvent("tengu_team_memdir_disabled", {});
  }
  return null;
}

~/.claude/projects/<sanitized-git-root>/memory/
├── MEMORY.md                  ← 索引文件（每次对话都加载到上下文）
├── user_role.md               ← 记忆文件：带 YAML frontmatter
├── feedback_testing.md
├── project_auth_rewrite.md
└── reference_linear_ingest.md

export const MEMORY_FRONTMATTER_EXAMPLE: readonly string[] = [
  "```markdown",
  "---",
  "name: ",
  "description: ",
  `type: }`,
  "---",
  "",
  "",
  "```",
];

export function buildMemoryLines(displayName: string, memoryDir: string, extraGuidelines?: string[], skipIndex = false): string[] {
  const howToSave = skipIndex
    ? [
        "## How to save memories",
        "",
        "Write each memory to its own file (e.g., `user_role.md`, `feedback_testing.md`) using this frontmatter format:",
        "",
        ...MEMORY_FRONTMATTER_EXAMPLE,
        "",
        "- Keep the name, description, and type fields in memory files up-to-date with the content",
        "- Organize memory semantically by topic, not chronologically",
        "- Update or remove memories that turn out to be wrong or outdated",
        "- Do not write duplicate memories. First check if there is an existing memory you can update before writing a new one.",
      ]
    : [
        "## How to save memories",
        "",
        "Saving a memory is a two-step process:",
        "",
        "**Step 1** — write the memory to its own file (e.g., `user_role.md`, `feedback_testing.md`) using this frontmatter format:",
        "",
        ...MEMORY_FRONTMATTER_EXAMPLE,
        "",
        `**Step 2** — add a pointer to that file in \`${ENTRYPOINT_NAME}\`. \`${ENTRYPOINT_NAME}\` is an index, not a memory — each entry should be one line, under ~150 characters: \`- [Title](file.md) — one-line hook\`. It has no frontmatter. Never write memory content directly into \`${ENTRYPOINT_NAME}\`.`,
        "",
        `- \`${ENTRYPOINT_NAME}\` is always loaded into your conversation context — lines after ${MAX_ENTRYPOINT_LINES} will be truncated, so keep the index concise`,
        "- Keep the name, description, and type fields in memory files up-to-date with the content",
        "- Organize memory semantically by topic, not chronologically",
        "- Update or remove memories that turn out to be wrong or outdated",
        "- Do not write duplicate memories. First check if there is an existing memory you can update before writing a new one.",
      ];

  const lines: string[] = [
    `# ${displayName}`,
    "",
    `You have a persistent, file-based memory system at \`${memoryDir}\`. ${DIR_EXISTS_GUIDANCE}`,
    "",
    "You should build up this memory system over time so that future conversations can have a complete picture of who the user is, how they'd like to collaborate with you, what behaviors to avoid or repeat, and the context behind the work the user gives you.",
    "",
    "If the user explicitly asks you to remember something, save it immediately as whichever type fits best. If they ask you to forget something, find and remove the relevant entry.",
    "",
    ...TYPES_SECTION_INDIVIDUAL,
    ...WHAT_NOT_TO_SAVE_SECTION,
    "",
    ...howToSave,
    "",
    ...WHEN_TO_ACCESS_SECTION,
    "",
    ...TRUSTING_RECALL_SECTION,
    "",
    "## Memory and other forms of persistence",
    "Memory is one of several persistence mechanisms available to you as you assist the user in a given conversation. The distinction is often that memory can be recalled in future conversations and should not be used for persisting information that is only useful within the scope of the current conversation.",
    "- When to use or update a plan instead of memory: If you are about to start a non-trivial implementation task and would like to reach alignment with the user on your approach you should use a Plan rather than saving this information to memory. Similarly, if you already have a plan within the conversation and you have changed your approach persist that change by updating the plan rather than saving a memory.",
    "- When to use or update tasks instead of memory: When you need to break your work in current conversation into discrete steps or keep track of your progress use tasks instead of saving to memory. Tasks are great for persisting information about the work that needs to be done in the current conversation, but memory should be reserved for information that will be useful in future conversations.",
    "",
    ...(extraGuidelines ?? []),
    "",
  ];

  lines.push(...buildSearchingPastContextSection(memoryDir));

  return lines;
}