Claude Code 上下文省 token 工作流落地方案

背景问题

截图里的失败不是单次工具报错，而是会话已经背了过多原始资料、读取记录和中间推理。Claude Code 报出：

Input tokens exceed the configured limit of 272000 tokens.

这说明继续在同一会话里点“继续”，大概率还是会失败。技能包需要把“长任务上下文”从聊天窗口里搬到文件和工具里，让 Claude 每轮只读取必要的轻量状态，而不是反复读取所有原始图片、Excel、长 Markdown 和完整历史对话。

落地目标

给 claude-code-voc-intelligence 增加一套“省 token 长任务工作流”，用于真实采集任务文档、小红书样本整理、客户素材归档、批量图片/Excel/文本分析等场景。

目标效果：

用户可以把大量资料放到工作区，Claude 不会一次读完全部文件。
每轮最多处理 1 个样本单元，例如 XHS-001_1。
每个样本单元处理完后，必须写入中间摘要文件。
后续会话只读取任务状态、中间摘要和下一个样本单元，不重复读取原始大文件。
上下文不足时，技能包能主动生成交接摘要，并提示新会话如何继续。
最终报告由多个中间摘要汇总而来，而不是由一个超长会话硬扛到底。

核心设计

采用“原始资料 -> 文件清单 -> 样本单元摘要 -> 总控任务状态 -> 最终报告”的流水线。

flowchart TD
  A["原始资料目录"] --> B["context scan 文件清单"]
  B --> C["sample units 样本单元索引"]
  C --> D["每轮只处理 1 个样本单元"]
  D --> E["unit summary 中间摘要"]
  E --> F["task-state 当前进度"]
  F --> G["handoff 新会话交接摘要"]
  E --> H["final report 汇总文档"]

关键原则：

聊天上下文只放“当前要判断的内容”。
大文件只让脚本读取，Claude 只读脚本生成的轻量摘要。
任务进度写入文件，不依赖会话记忆。
新会话从 task-state 恢复，而不是从聊天历史恢复。

需要新增的文件结构

建议先落在 claude-code-voc-intelligence 技能包内：

claude-code-voc-intelligence/
  docs/
    context-budget-implementation-plan.md
  skills/xiaohongshu-trend-intelligence/references/
    context-budget-workflow.md
  mcp/src/features/context-budget/
    file-manifest.js
    sample-units.js
    checkpoint.js
    handoff.js
  mcp/src/tools/
    context-budget-run.js
  scripts/
    smoke-context-budget.js

安装到工作区后，运行时在客户项目里生成：

.claude/task-state/
  voc-context-state.md
  voc-context-state.json
  handoff.md

outputs/voc-context/
  file-manifest.json
  sample-units.json
  unit-summaries/
    XHS-001_1.md
    XHS-002_1.md
  final/
    真实采集任务文档.md

技术实现模块

1. 文件清单扫描器

作用：先建立资料目录的轻量索引，避免 Claude 直接递归读取全部内容。

建议实现：

mcp/src/features/context-budget/file-manifest.js

输入保持简单：

{
  "rootDir": "docs/真实采集任务文档",
  "taskName": "小红书真实采集任务文档"
}

输出内容：

文件路径
文件类型
文件大小
修改时间
所属样本单元推断，例如 XHS-001_1
是否疑似大文件
是否建议脚本预处理

不在第一步读取图片正文、Excel 全量内容或长 Markdown 全文。

2. 样本单元识别器

作用：把 01-06、XHS-001_1、XHS-008_8 这类目录识别成可独立处理的样本单元。

建议规则：

优先识别 XHS-\d+(_\d+)?
其次识别一级/二级目录名
允许用户在状态文件里手动修正单元关系
每个单元包含：截图、笔记正文、评论、Excel 行、人工备注、校验材料

输出：

outputs/voc-context/sample-units.json

示例字段：

{
  "unitId": "XHS-001_1",
  "status": "pending",
  "files": [],
  "summaryPath": "outputs/voc-context/unit-summaries/XHS-001_1.md",
  "estimatedRisk": "large-image-set"
}

3. 单元摘要生成器

作用：每轮只处理一个样本单元，并把结果写成结构化摘要。

建议实现：

mcp/src/features/context-budget/sample-units.js

摘要模板：

# XHS-001_1 样本摘要

## 已读取资料

## 账号/笔记信息

## 小红书趋势关键词

## 用户评论与真实顾虑

## 可验证话题方向

## 博主真实度/商业痕迹判断

## 证据片段

## 待复核问题

## 不要重复读取的原始文件

约束：

单元摘要控制在 800-1500 字。
摘要必须引用文件名，但不要复制大段原文。
图片只记录观察结论、截图编号和需要复核的位置。
Excel 只读取表头、关键列、与当前单元相关的行。

4. 任务状态与检查点

作用：让新会话知道任务做到哪里，不靠历史聊天。

建议实现：

mcp/src/features/context-budget/checkpoint.js

生成两个文件：

.claude/task-state/voc-context-state.json
.claude/task-state/voc-context-state.md

状态内容：

当前目标
已完成样本单元
正在处理的样本单元
待处理样本单元
已生成摘要文件
禁止重复读取的原始目录
下一步只允许读取哪些文件
汇总报告缺口

voc-context-state.md 要给人看，voc-context-state.json 给工具读。

5. 新会话交接摘要

作用：上下文过大时，直接停止扩读，生成新会话启动提示。

建议实现：

mcp/src/features/context-budget/handoff.js

生成：

.claude/task-state/handoff.md

内容模板：

# 新会话交接摘要

## 当前任务

## 已完成

## 不要重新读取

## 新会话只读取

1. .claude/task-state/voc-context-state.md
2. outputs/voc-context/sample-units.json
3. outputs/voc-context/unit-summaries/

## 下一步

只处理 XHS-002_1，完成后写入对应摘要并停止。

## 可直接复制给 Claude Code 的 Prompt

需要新增的 MCP 工具

建议在 mcp/src/server.js 增加三个工具。入参保持简单，避免让用户理解技术参数。

`voc_context_prepare`

用途：初始化长任务，扫描目录，生成文件清单、样本单元和任务状态。

输入：

{
  "rootDir": "docs/真实采集任务文档",
  "taskName": "小红书真实采集任务文档"
}

输出：

assistantMessage：告诉用户识别出多少样本单元，建议先处理哪个。
data.statePath
data.sampleUnitsPath
nextActions

`voc_context_next_unit`

用途：读取任务状态，返回下一轮应该处理的单元和允许读取的文件清单。

输入：

{
  "statePath": ".claude/task-state/voc-context-state.json"
}

输出：

下一单元 ID
允许读取的文件
禁止读取的文件
摘要写入路径

`voc_context_checkpoint`

用途：处理完一个样本单元后，写入摘要、更新任务状态、生成必要的 handoff。

输入：

{
  "unitId": "XHS-001_1",
  "summary": "本轮摘要正文",
  "status": "completed"
}

输出：

更新后的进度
下一个单元
新会话启动提示

CLI 命令设计

为了兼容 Claude Code 工具不可用或客户只会终端的情况，也建议在 claude-voc CLI 增加同款命令：

claude-voc context prepare --root "docs/真实采集任务文档" --task "小红书真实采集任务文档"
claude-voc context next
claude-voc context checkpoint --unit XHS-001_1 --summary "outputs/voc-context/unit-summaries/XHS-001_1.md"
claude-voc context handoff

客户不需要主动使用这些命令，但 Claude Code 可以通过 Bash 调用，作为稳定兜底。

Skill 文档需要加的规则

在 skills/xiaohongshu-trend-intelligence/SKILL.md 增加“长任务省 token 协议”：

## 长任务省 token 协议

- 如果用户要求处理多个样本目录、批量图片、Excel 或长文档，不要一次读取全部资料。
- 先调用/执行 context prepare，生成文件清单、样本单元和任务状态。
- 每轮最多处理 1 个样本单元。
- 每处理完一个样本单元，必须写入 unit summary，并更新 task-state。
- 后续汇总只能优先读取 unit summary，不重复读取原始大文件。
- 当上下文明显变大、用户说继续多次、或任务超过 3 个样本单元时，先生成 handoff，再建议开新会话。
- 新会话只读取 handoff、task-state、sample-units 和必要的 unit summary。

面向用户的话术

当用户给了大批资料时，Claude 应该这样说：

资料比较多，我会按省上下文方式处理：先建立文件清单和样本单元索引，然后每轮只处理一个样本单元。每个单元处理完都会写入摘要，后续汇总只读摘要，不重复读取原始大文件。

我先处理 XHS-001_1，处理完会停下来给你确认。

当上下文不足时：

当前会话已经接近上下文上限。我已经把进度写入 .claude/task-state/handoff.md。

建议新开一个 Claude Code 会话，并只让它读取 handoff、task-state 和已生成的 unit summary，不要重新读取所有原始图片和 Excel。

新会话启动 Prompt：

继续处理小红书真实采集任务文档，但请控制上下文。

先只读取：
1. .claude/task-state/handoff.md
2. .claude/task-state/voc-context-state.md
3. outputs/voc-context/sample-units.json
4. 已生成的 unit summary

不要重新读取所有 XHS 原始图片、Excel、长文档。
请先告诉我当前进度、缺什么、下一步只处理哪个样本单元。
每次最多处理一个样本单元，处理完写入对应摘要文件后停止。

分阶段实施计划

P0：先用规则和文档止血

改动：

新增 references/context-budget-workflow.md
在 SKILL.md 引用省 token 协议
在 customer-quickstart.md 或 demo-runbook.md 补充大资料处理话术

收益：不改代码也能显著降低 Claude 一次性读取全部文件的概率。

P1：实现本地文件清单和任务状态

改动：

新增 context-budget-run.js
支持 prepare、next、checkpoint、handoff
写入 .claude/task-state 和 outputs/voc-context

收益：长任务可以跨会话续跑。

P2：接入 MCP 工具

改动：

在 server.js 注册 voc_context_prepare
注册 voc_context_next_unit
注册 voc_context_checkpoint
smoke 测试覆盖工具返回的 assistantMessage

收益：Claude Code 插件里可以直接调用工具，不必靠手写 Bash。

P3：增加文件预处理能力

按优先级实现：

Markdown/TXT 分章节摘要。
Excel 只提取 sheet 名、列名、前 N 行和命中当前样本 ID 的行。
图片只提取路径、大小、尺寸、所属样本，不直接 OCR 全图。
后续如需要，再接 OCR 或视觉模型，但必须按单元处理。

如果引入依赖，建议：

Excel：xlsx
图片尺寸：image-size

第一版也可以先不加依赖，只做路径、大小、扩展名和目录归属。

P4：打包和发布

改动：

package.json 增加 smoke 脚本
scripts/smoke-package.js 增加 context workflow 检查
npm run claude-voc:npm-pack
npm run claude-voc:build
升级 npm 版本并发布

验收标准

功能验收：

给一个包含 6 个样本单元、图片、Excel、长文档的目录，prepare 后能生成 sample-units.json。
Claude 第一轮只处理 1 个样本单元。
处理完会生成 unit-summaries/<unitId>.md。
task-state.md 能清楚显示已完成、待处理和下一步。
新会话只读 handoff 和摘要，也能继续下一单元。

体验验收：

不再出现“继续”后反复超 token。
不让用户理解复杂参数。
不把 JSON 调试信息直接甩给用户。
不要求用户手动整理 01-06 到 XHS-001 的映射，工具能先自动推断，必要时再让用户确认。

安全验收：

不把 VOC token、npm token 写入状态文件、摘要文件或报告。
.claude/task-state 可以进入工作区，但任何 .env.local、.npmrc 不进入 git。

context-budget-implementation-plan.md 13 KB

Geçmiş Ham

Claude Code 上下文省 token 工作流落地方案

背景问题

落地目标

核心设计

需要新增的文件结构

技术实现模块

1. 文件清单扫描器

2. 样本单元识别器

3. 单元摘要生成器

4. 任务状态与检查点

5. 新会话交接摘要

需要新增的 MCP 工具

`voc_context_prepare`

`voc_context_next_unit`

`voc_context_checkpoint`

CLI 命令设计

Skill 文档需要加的规则

面向用户的话术

分阶段实施计划

P0：先用规则和文档止血

P1：实现本地文件清单和任务状态

P2：接入 MCP 工具

P3：增加文件预处理能力

P4：打包和发布

验收标准

推荐优先落地顺序

context-budget-implementation-plan.md 13 KB Geçmiş Ham

Claude Code 上下文省 token 工作流落地方案

背景问题

落地目标

核心设计

需要新增的文件结构

技术实现模块

1. 文件清单扫描器

2. 样本单元识别器

3. 单元摘要生成器

4. 任务状态与检查点

5. 新会话交接摘要

需要新增的 MCP 工具

voc_context_prepare

voc_context_next_unit

voc_context_checkpoint

CLI 命令设计

Skill 文档需要加的规则

面向用户的话术

分阶段实施计划

P0：先用规则和文档止血

P1：实现本地文件清单和任务状态

P2：接入 MCP 工具

P3：增加文件预处理能力

P4：打包和发布

验收标准

推荐优先落地顺序

context-budget-implementation-plan.md 13 KB

Geçmiş Ham

`voc_context_prepare`

`voc_context_next_unit`

`voc_context_checkpoint`