FinClaw V1 Task Packet Context Budget Schema

状态：Accepted Initial Protocol / V1 task packet 必须遵守的 context 预算字段标准 日期：2026-05-16 项目：FinClaw 文档级别：项目级方法论协议 上游协议：v1-multi-agent-execution-protocol.md 配套协议：v1-handoff-anchor-template.md

1. Purpose

本文件定义 V1 工程化期间所有 task packet（含 sub-packet）必须包含的 context budget 字段。该字段让 Agent 在启动前就能：

• 准确估算输入上下文 token 消耗；
• 选择必读 vs 可选阅读文档（节省 70-90% context）；
• 判断单次 Agent 闭环能否完成本 packet；
• 决定是否需要进一步切片。

2. Required Frontmatter Extension

每个 task packet（含 sub-packet）的 YAML frontmatter 必须包含 context_budget 段：

---
document_id: <packet-id>
type: task-packet | sub-packet
status: pending | active | done | partial | blocked
scope: finclaw
lane: engineering | product | controller | reference
parent_packet: <only for sub-packet>
created: <date>
updated: <date>

context_budget:
  estimated_input_tokens: <integer>
  estimated_tool_call_overhead: <integer>
  estimated_output_tokens: <integer>
  total_budget: <integer>
  budget_zone: green | yellow | red
  must_read:
    - path: <relative-path>
      sections: [<§ list>] | "full"
      tokens: <integer>
    - ...
  reference_only:
    - path: <relative-path>
      sections: [<§ list>] | "full"
      tokens: <integer>
    - ...
  produces:
    handoff_anchor_path: <治理库路径>
    artifacts: [<list of files>]
---

3. Field Definitions

3.1 estimated_input_tokens

所有 must_read 文档 + 本 packet 自己内容的 token 总数。

• 估算方式：粗略采用 wc -c / 3.5（中文）或 wc -w * 1.3（英文）；
• 不需要精确，但应在 ±20% 内；
• 涵盖：system prompt（默认 ~5K）+ skill/advisor 指令（按使用情况估）+ must_read 文档。

3.2 estimated_tool_call_overhead

预计本 packet 执行期间所有 tool_use 调用结果累积的 token 数。

经验估算：

Packet 类型	tool_call_overhead 估算
纯设计文档撰写	5-10K
设计文档撰写 + 少量代码 review	10-20K
工程实现（含多次 Read / Edit / 测试）	20-50K
大型 refactor / migration	50-80K

3.3 estimated_output_tokens

预计 Agent 最终产出的 token 数。

经验估算：

产出类型	output_tokens
决策记录 / 短 anchor	1-3K
单个设计文档	5-15K
Sub-packet 完成报告 + 代码	8-25K
大型重构 PR	15-40K

3.4 total_budget

total_budget = estimated_input_tokens
             + estimated_tool_call_overhead
             + estimated_output_tokens

3.5 budget_zone

根据 v1-multi-agent-execution-protocol.md §3 Sweet Spot Targets 分级：

Zone	total_budget	含义	动作
green	≤ 60K	安全区，Agent 单次会话可完成	直接执行
yellow	60K-100K	警戒区，可执行但有 attention dilution 风险	优先优化 must_read 切片；如无法降低则可执行
red	> 100K	超限区	必须进一步切片为 sub-packet

3.6 must_read

执行本 packet 必须载入的文档集合。

• path：相对治理库或工程仓库的路径；
• sections：明确的 section 列表（如 ["§3", "§5.2"]）；或 "full"（仅当文档整体短小时）；
• tokens：该 section / 文档的 token 数。

关键原则：宁可少 must_read 一些，让 Agent 在执行中按需加载，也不要把「以防万一」的文档放进 must_read。

3.7 reference_only

Agent 可以按需加载的文档。

• 不计入 estimated_input_tokens；
• Agent 自行判断是否需要在执行过程中读；
• 如果某 reference_only 文档在 ≥ 80% 的同类 packet 中都被 agent 主动加载，下次更新时应该提升到 must_read。

3.8 produces

本 packet 闭环完成时必须产出的物件。

• handoff_anchor_path：hand-off anchor 文档的治理库路径；
• artifacts：本 packet 产出的代码 / 文档 / 配置等文件清单。

4. Section Navigation in Reference Documents

为了让 task packet 能精确引用文档的某个 section，所有 V1 大设计文档（v1-prd.md、v1-product-object-and-schema-design.md 等）的 frontmatter 必须新增 section_navigation 段。

4.1 Section Navigation Schema

section_navigation:
  total_tokens: <integer>
  read_strategy: |
    <一段简短说明：什么 packet 需要全文读，什么 packet 只读特定 section>
  sections:
    - id: "§1"
      title: "Purpose"
      tokens: <integer>
      dependencies: []
      must_read_for: [<packet-id list>]
    - id: "§2"
      title: "Scope"
      tokens: <integer>
      dependencies: ["§1"]
      must_read_for: [<packet-id list>]
    - id: "§3"
      title: "Core Objects"
      tokens: <integer>
      dependencies: ["§1", "§2"]
      must_read_for: [<packet-id list>]

4.2 Dependencies 字段

某个 section 的 dependencies 列出理解该 section 所必需的其他 section。

如果 packet 引用了 §3，则 Agent 必须同时载入 §1, §2, §3。

这避免「引用了结论 section 但漏读前提 section」导致 agent 误解。

4.3 Token 估算工具

V1 工程化期间使用以下简化估算：

def estimate_tokens(text: str) -> int:
    chinese_chars = sum(1 for c in text if '\u4e00' <= c <= '\u9fff')
    other_chars = len(text) - chinese_chars
    return chinese_chars + other_chars // 4

（中文按 1 char ≈ 1 token，其他文本按 ~4 chars ≈ 1 token。）

后续可替换为 tiktoken / model-specific tokenizer。

5. Sub-Packet Decomposition Rules

当某个 task packet 的 total_budget 落在 red zone（> 100K），必须切片为 sub-packet。

5.1 切片原则

原则	描述
单一职责	每个 sub-packet 完成一件可独立验证的事
文件隔离	不同 sub-packet 不应改同一文件的同一区域
顺序明确	如有依赖，sub-packet 应有明确 sequence 编号
Hand-off 完备	每个 sub-packet 必须有自己的 handoff anchor

5.2 切片命名

v1-engineering-implementation-task-packet.md           (parent / index)
  ├─ v1-eng-impl-sub-1-profile-consent.md             (sub-packet 1)
  ├─ v1-eng-impl-sub-2-sensitive-input-handling.md
  ├─ v1-eng-impl-sub-3-training-asset-candidate.md
  └─ ...

Sub-packet 文件名前缀使用 parent packet 的 packet-id 缩写 + sub-<N>-<topic>。

5.3 Parent Packet 简化

切片后，parent packet 退化为「index packet」：

• 保留：acceptance_criteria、依赖关系图、整体 timeline；
• 移除：详细子任务（移到 sub-packet）；
• 新增：sub-packet 列表 + 顺序 + 当前状态。

6. Example: Engineering Implementation Packet

以下展示一个完整的 sub-packet frontmatter 示例（节选）：

---
document_id: v1-eng-impl-sub-1-profile-consent
type: sub-packet
status: pending
scope: finclaw
lane: engineering
parent_packet: v1-engineering-implementation-task-packet
created: 2026-05-16
updated: 2026-05-16

context_budget:
  estimated_input_tokens: 22_000
  estimated_tool_call_overhead: 15_000
  estimated_output_tokens: 8_000
  total_budget: 45_000
  budget_zone: green
  must_read:
    - path: design/v1/v1-prd.md
      sections: ["§5.7"]
      tokens: 1_200
    - path: design/v1/v1-product-object-and-schema-design.md
      sections: ["§4 ProfileConsent"]
      tokens: 2_800
    - path: design/v1/v1-governance-engineering-alignment.md
      sections: ["§AL-1"]
      tokens: 1_500
    - path: design/v1/v1-engineering-kickoff-decisions.md
      sections: ["§3 D-12"]
      tokens: 800
  reference_only:
    - path: design/v1/v1-ui-prototype-and-design-system.md
      sections: ["full"]
      tokens: 12_000
  produces:
    handoff_anchor_path: handoff-anchors/v1-eng-impl-sub-1-profile-consent.yaml
    artifacts:
      - /Users/mlabs/Programs/CurvatureLabs/finclaw/server/agent/models.py (add ProfileConsent)
      - /Users/mlabs/Programs/CurvatureLabs/finclaw/web/src/domains/onboarding/ProfileConsentDialog.tsx
      - /Users/mlabs/Programs/CurvatureLabs/finclaw/server/tests/test_profile_consent.py
---

7. Validation Checklist for New Packets

写新 packet（含 sub-packet）时按以下 checklist 自查：

• frontmatter 含完整 context_budget 段
• must_read 中每份文档都标注了 section（不是 "full"，除非 < 3K）
• total_budget 落在 green 或 yellow zone（否则需切片）
• produces 中声明了 hand-off anchor 路径
• produces.artifacts 列出了所有预计产出文件
• 不引用尚未存在的 section（如新设计文档的 section）
• sub-packet 时，parent_packet 字段填写正确

8. Migration Path for Existing Packets

现有 6 份 task packet（治理库 design/task-packets/）需要在阶段 0 完成 migration：

Packet	切片建议	优先级
v1-product-object-and-schema-design-task-packet	已 done；只补 anchor	低
v1-user-journey-and-interaction-flow-task-packet	已 done；只补 anchor	低
v1-engineering-implementation-task-packet	切为 ~8 个 sub-packet（按 AL-1 ~ AL-11 切）	高
v1-skills-domain-knowledge-review-task-packet	切为 Phase 1 自查 + Phase 2 外部评审两个 sub-packet	中
v1-human-experience-trial-execution-task-packet	切为 cohort 招募（已简化）+ 内测执行两个 sub-packet	中
v1-commercial-signal-instrumentation-task-packet	切为 schema + 工程 + 隐私复核三个 sub-packet	中

9. Open Items

• estimate_tokens 函数当前是估算工具；生产使用需替换为 tiktoken / model tokenizer；
• Section navigation 标注是手工的；未来可考虑工具自动生成；
• Sub-packet 之间的依赖图当前在 parent packet 中文字描述，未结构化。

10. References

• v1-multi-agent-execution-protocol.md；
• v1-handoff-anchor-template.md；
• v1-engineering-kickoff-decisions.md。