Skip to content

refactor: modularize context pipeline and unify system prompt architecture#48

Merged
ztygod merged 2 commits into
mainfrom
feat/context-refactor
Jul 19, 2026
Merged

refactor: modularize context pipeline and unify system prompt architecture#48
ztygod merged 2 commits into
mainfrom
feat/context-refactor

Conversation

@ztygod

@ztygod ztygod commented Jul 19, 2026

Copy link
Copy Markdown
Owner

背景

原有 Context 系统混合了承载上下文收集、Transcript 投影、预算压缩和 Prompt 拼装等职责。同时,System Prompt 分散定义在配置加载、Runtime、Local CLI 和 ContextManager 中,存在来源不唯一、覆盖规则不明确的问题。

主要改动

Context 架构拆分

将 Context 模块整理为四个清晰层次:

  • collector:收集 Memory、Workspace Profile、User Context 和 Context Provider。
  • transcript:维护合法 tool exchange,保留最近完整调用,并归档旧工具结果。
  • budget:负责优先级、Token 预算、压缩决策、压缩和截断。
  • assembly:负责 Context 格式化和最终 LLM Messages 拼装。

同时:

  • 保留 ContextManager 作为 Agent Runtime facade。
  • 删除历史 ContextEnginebuildRuntimeContext 和重复 formatting/compression 兼容层。
  • 引入 ContextDocumentBudgetedContextTranscriptProjection 和 retention/source 类型。
  • 保持 Agent loop、tool calling 顺序和现有压缩行为不变。

统一 System Prompt

新增版本化的 SystemPromptService,并将内置 Prompt 集中到唯一来源。

标准 Prompt 包含:

  • Agent 身份与目标
  • 指令优先级
  • 工作流程
  • 工具使用原则
  • 修改质量要求
  • 验证要求
  • 安全边界
  • Ask/Edit 模式规则
  • 最终回复规范

核心 Prompt 不允许被外部整体替换。

配置 API 调整

移除:

  • runtime.systemPrompt
  • run.input.systemPrompt
  • DEFAULT_SYSTEM_PROMPT
  • CLI_MARKDOWN_OUTPUT_INSTRUCTIONS

新增:

runtime.systemInstructions: string[];
run.input.systemInstructions?: readonly string[];

配置和单次运行只能追加补充指令。旧 systemPrompt 配置会被明确拒绝。

Context 与 Prompt 解耦

  • ContextDocument 不再包含 System Prompt。
  • Context Collector 不再接收或处理 Prompt。
  • System Prompt 每个 run 只解析一次。
  • Prompt 不参与 Context 压缩或截断。
  • PromptAssembler 只负责组合版本化 Prompt、Runtime Context 和 Transcript。

可观测性

Context diagnostics 新增:

  • systemPromptVersion
  • systemPromptTokens
  • systemPromptSectionTokens

Breaking Changes

  • 删除 runtime.systemPrompt
  • 删除 AgentRunInput.systemPrompt
  • 删除历史 ContextEnginebuildRuntimeContext 导出。
  • 配置文件需要迁移至:
[runtime]
systemInstructions = [
  "Prefer functional TypeScript.",
  "Do not modify generated files."
]

验证

已通过:

  • TypeScript typecheck
  • 全量单元测试
  • ESLint
  • Prettier check
  • 项目构建
  • API Extractor
  • Git diff whitespace check

@ztygod
ztygod merged commit c944dc2 into main Jul 19, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant