ZacharyZhang-NY/AgentCompany
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity
Files
8b0b06f765cc3efcf2ff6f5b58f0b7b41e353cd1
AgentCompany/docs/proposals/C7-prompt-builder-conditional-assembly.md
T

12 KiB
Raw Blame History

Proposal C7: prompt-builder 按 role 条件拼装 + token 预算守门

来源：问题.md C7（行 202-215）、附录 C（行 395）、附录 H（行 574-577） 状态：proposed（待 B5 + C4 完成后实施） 提出：Roundtable 2026-04-20（Linus + Karpathy + Steve Jobs） Owner: TBD 估计工时：2 周 Blocking dependencies：B5（eval harness）、C4（initial-user-turn 精简）

问题陈述

src/main/prompt-builder/system-prompt.ts 共 262 行，无条件拼装：

  • 15 个 SOP（prompt-builder/sops/*.md）
  • 11 个 API 文档（prompt-builder/api-docs/*.md）
  • 5 个 CEO 模式片段（prompt-builder/ceo-modes/*.md）
  • 7 个部门指南（prompt-builder/department-guidelines/*.md）
  • Operating instructions (CEO / non-CEO 分支)
  • Capability registry
  • Skill injection

问题细节：

  1. 无条件拼接：一个 customer_support IC 也会收到全 15 个 SOP（包括 engineering / legal / finance 类）
  2. 版本无治理：每个 SOP/api-doc 的 git blame 是唯一变更记录，没有 version frontmatter
  3. 无 token 预算守门：prompt 本身可能吃掉 20-30k input tokens；compactor 还没开始就先把 budget 吃大半
  4. A/B 实验无法做：改一个 SOP 的某句话无法 attribute 到具体行为变化
  5. Cache invalidation 代价高：Anthropic prompt caching 对稳定前缀敏感——262 行拼装每改一次就 cache miss 一次

根因分析

Karpathy 视角：prompt 越长越脆。

长 prompt 的三个问题：

  1. Relevance dilution：LLM 注意力机制对 prompt 中后段的 attention 权重递减（lost-in-the-middle 现象）。全塞 33 个 markdown 文件反而让关键信号被淹没。
  2. Cross-contamination：legal SOP 的措辞会影响 engineering agent 的输出风格（比如加 disclaimers）；这不是我们想要的。
  3. Evaluation intractability：33 个片段两两组合有 1000+ 种可能影响；改一个不知道动了哪。

Linus 视角补充：当前架构假设"一个 prompt 适配所有 agent"。这和 AppDatabase pass-through 是同构的问题——用一个巨大的 god object 替代多个专用对象。正确做法是按 role 产出不同 prompt。

另一个层面的问题：没有 budget。prompt-builder 的输出长度是"算出来多少就多少"，caller 无法预判。20k / 30k / 50k token 的 prompt 走 Anthropic 都能跑，但 cost 和 latency 完全不同，而且 compactor（B3 未修时）行为也会随 prompt 长度变化。

设计方案

核心原则

  1. 按 role 条件拼装：每个 agent 只看到自己需要的
  2. 显式 budget：prompt > threshold 直接 fail fast
  3. 片段版本化：每个 markdown 带 frontmatter version: X
  4. Cache-friendly layering：稳定前缀（不变的 operating instructions）+ 动态后缀（per-turn context）显式分离

片段分类表

片段类型 何时包含 共享度
Core operating instructions 总是 所有 agent
CEO operating instructions agent.role === "ceo" CEO only
CEO mode（team-building/awaiting-*/operating） CEO + 当前 phase CEO only
Department guidelines 按 agent.department 同部门
SOPs 按"与 agent 能力相关" 有限子集
API docs 按 connector 可用性 动态
Capability registry 总是 所有 agent
Skill injection（pi 的 progressive disclosure） 总是 所有 agent

新 API 结构

// src/main/prompt-builder/index.ts（重写）
export function buildSystemPrompt(ctx: PromptContext): string {
  const sections = resolveSections(ctx);  // 新增
  const parts = sections.map((s) => renderSection(s, ctx));
  const prompt = parts.join("\n\n");
  enforceBudget(prompt, ctx);  // 新增
  return prompt;
}

interface SectionRef {
  id: string;        // "sop.task-delegation" | "department.engineering" | ...
  version: string;   // 从 markdown frontmatter
  required: boolean; // 不满足 required 则 fail
}

function resolveSections(ctx: PromptContext): SectionRef[] {
  const sections: SectionRef[] = [
    { id: "core.operating-instructions", version: "1.0", required: true },
    { id: "core.capability-registry", version: "1.0", required: true },
  ];

  if (ctx.agent.role === "ceo") {
    sections.push({ id: "ceo.operating-instructions", version: "1.0", required: true });
    sections.push({ id: `ceo.mode.${ctx.ceoMode}`, version: "1.0", required: true });
  }

  if (ctx.agent.department) {
    sections.push({ id: `department.${ctx.agent.department}`, version: "1.0", required: true });
  }

  for (const sop of resolveRelevantSops(ctx)) {
    sections.push({ id: `sop.${sop.slug}`, version: sop.version, required: false });
  }

  // API docs 仅当对应 connector ready 时
  for (const connector of ctx.allConnectors ?? []) {
    if (connector.status === "ready") {
      sections.push({ id: `api-docs.${connector.id}`, version: "1.0", required: false });
    }
  }

  return sections;
}

SOP 相关性规则

替代"全塞"的朴素规则：

  1. SOP 有 tags frontmatter：tags: [task, delegation, messaging]
  2. Agent role / department 决定关注 tag 集合：
    • CEO → 全 tag
    • Engineering dept → [task, code, review]
    • Customer support → [task, messaging, escalation]
  3. Loader 根据 tag 交集筛选

Markdown 示例：

---
id: sop.task-delegation
version: 1.2
tags: [task, delegation]
---
# Task delegation SOP
...

Token 预算守门

// src/main/prompt-builder/budget.ts
const BUDGET_THRESHOLDS = {
  warn: 8_000,    // 超过 warn 打 telemetry
  error: 16_000,  // 超过 error 直接抛
};

function enforceBudget(prompt: string, ctx: PromptContext): void {
  const tokens = estimateTokensPrecise(prompt, ctx.locale);  // 用 tiktoken 精确计算（C3 的 scope）
  recordMetric("prompt.tokens", tokens, { role: ctx.agent.role, companyId: ctx.companyId });
  if (tokens > BUDGET_THRESHOLDS.error) {
    throw new PromptBudgetError(`System prompt ${tokens} tokens exceeds ${BUDGET_THRESHOLDS.error}`);
  }
  if (tokens > BUDGET_THRESHOLDS.warn) {
    logger.warn("prompt.budget.warn", { tokens, threshold: BUDGET_THRESHOLDS.warn });
  }
}

Let it crash 原则：超预算直接 throw，不做"自动裁剪"——因为自动裁剪会悄悄改行为。

Cache-friendly layering

当前 buildTaskPrompt（prompt-builder/index.ts:48-）已经把 system prompt（cacheable）和 per-turn context（non-cacheable）分开，这是对的。C7 保留这个分层，进一步：

  • system prompt 内部按 stability 排序：[core → role → department → SOPs → skills]（稳定度递减）
  • Anthropic cache_control breakpoint 标在 core + role + department 之后

A/B harness（可选阶段）

SOP 片段支持 variant：

---
id: sop.task-delegation
version: 1.2
variants:
  - id: default
    weight: 50
  - id: concise
    weight: 50
    path: ./task-delegation.concise.md
---

Loader 按 companyId hash 稳定分配到一个 variant，eval harness（B5）可以对比两个 variant 的行为差异。

Migration 计划

  1. Phase 0（前置）：B5 eval harness 就绪 + C4 initial-user-turn 精简完成
  2. Phase 1（3 天）：给所有 markdown 片段加 frontmatter（id / version / tags），loader 支持读取
  3. Phase 2（1 周）：实现 resolveSections + renderSection，行为上保持与当前一致（所有 section 都包含），新旧切换走 feature flag
  4. Phase 3（3 天）：按 role 开始差异化加载——CEO 仍看全量，非 CEO 开始按 tag 过滤
  5. Phase 4（3 天）：加 budget enforcement，先 warn-only 跑一周观测分布
  6. Phase 5（持续）：A/B harness + per-company variant 分配

风险与回滚

风险 触发条件 回滚方法
漏包含 SOP 导致 agent 行为退化 tag 过滤规则太严 eval 发现 → 回到"全量包含" flag → 修 tag 规则
Budget error 触发生产崩 某 company 的 connector 数量极端 阶段 4 warn-only 期间监测 p99；超限前调高或加裁剪
Markdown frontmatter 格式错 作者漏写 version Loader 启动时校验所有片段，任何格式错直接 fail
Cache invalidation 增多 稳定前缀拆得太细 监控 cache hit 率，必要时合并片段

验证标准

前置：B5 必须就绪。

  1. 行为 eval：对比 5 种 agent role × 3 种 trigger 下的 tool call 序列，新旧方案一致
  2. Prompt 长度：非 CEO agent 的 system prompt 长度降低 40%+
  3. Cache hit rate：观察 Anthropic cache hit rate，降低 <5%（cache 友好）
  4. Budget 分布：99% 的 prompt 在 warn 阈值内
  5. A/B pilot：至少一个 SOP 有 variant，eval 可观测两个 variant 的行为差异

不在范围

  • 不改 SOP 内容：只是让加载条件化 + 版本化，具体文字不动（那是 Owner 业务的事）
  • 不做 AI-driven prompt optimization：prompt 片段仍是人写的 markdown
  • 不改 pi 的 prompt 结构：本项目只控制自己注入到 pi 的 systemPrompt，pi 内部行为不动
  • 不做 per-agent fine-grained prompt：按 role / department 分组即可，不做 per-agent 定制
  • 不动 token 精确化（C3 的 scope）：本 proposal 可先用近似估算，C3 完成后自动精确

参考文件清单

  • src/main/prompt-builder/system-prompt.ts:1-262（主拼装函数）
  • src/main/prompt-builder/sops/*.md（15 个 SOP）
  • src/main/prompt-builder/api-docs/*.md（11 个 API 文档）
  • src/main/prompt-builder/ceo-modes/*.md（5 个 CEO 模式）
  • src/main/prompt-builder/department-guidelines/*.md（7 个部门指南）
  • src/main/prompt-builder/operating-instructions.ts + operating-instructions-ceo.ts
  • src/main/prompt-builder/capability-registry.ts
  • src/main/prompt-builder/skill-injection.ts
  • src/main/prompt-builder/index.ts（入口 + per-turn 拼装）

附：为什么现在做

prompt caching 的经济账：Anthropic cache 5 分钟 TTL，稳定前缀每 miss 一次多付 ~30% cost。262 行拼装每天被改几次就是每天多付 30% × N 次。这是隐性 recurring cost，估算 company 规模一大、agent 数量一多，年度多付上万美元（有具体数值可做 cost model，不在本 proposal 范围）。

更重要的是：有了条件拼装 + version frontmatter，AI coding agent 改 prompt 时可以 diff 到具体片段——而不是在 262 行大 blob 里大海捞针。这直接降低 team 改 prompt 的心理门槛，促进迭代。

附：gating matrix

Gate 条件 放行判断人
G1 B5 eval harness + C4 完成 Karpathy
G2 所有 markdown 片段加了 frontmatter Owner
G3 resolveSections 函数覆盖 CEO / 非 CEO / 所有 department Owner
G4 Budget enforcement warn 阈值下 95% prompt 不触发 Karpathy
G5 A/B variant 第一个实验跑出 eval 差异数据 Karpathy

附：markdown frontmatter schema

export const SopFrontmatterSchema = z.object({
  id: z.string().regex(/^sop\.[a-z-]+$/),
  version: z.string().regex(/^\d+\.\d+$/),
  tags: z.array(z.string()).min(1),
  locale: z.enum(["en", "zh"]).default("en"),
  variants: z.array(z.object({
    id: z.string(),
    weight: z.number().min(0).max(100),
    path: z.string().optional(),
  })).optional(),
});

Build 时校验所有 markdown 符合 schema；不符合直接 fail。

附：SOP tag 分类体系（初版草案）

Tag 含义 关联 role
task 任务管理相关 所有
delegation 分派相关 CEO, 管理层
code 代码相关 engineering
review 审查相关 所有 reviewer
messaging 消息沟通 所有
escalation 升级相关 所有
finance 财务相关 finance, CEO
legal 法务相关 legal, CEO
marketing 营销相关 marketing
customer 客户交互 support, sales

规则：SOP 至少有 1 个 tag，agent 根据 role 计算 relevant tag 集合。

Reference in new issue View Git Blame Copy Permalink