Add proposals for deferred root-cause refactors (B2/B4/C1/C2/C4/C7/M2/M5/M7-M12)

This commit is contained in:
ZacharyZhang-NY committed 2026-04-20 10:53:16 -04:00
1 parent 77076e7b29
commit 06d58d9fd6
15 files changed
+3660

No files matched your search

@@ -0,0 +1,280 @@
# 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 结构
```ts
// 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 示例:
```md
---
id: sop.task-delegation
version: 1.2
tags: [task, delegation]
---
# Task delegation SOP
...
```
### Token 预算守门
```ts
// 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:
```md
---
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
```ts
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 集合。