# Claude Code 上下文省 token 工作流落地方案 ## 背景问题 截图里的失败不是单次工具报错，而是会话已经背了过多原始资料、读取记录和中间推理。Claude Code 报出： ```text Input tokens exceed the configured limit of 272000 tokens. ``` 这说明继续在同一会话里点“继续”，大概率还是会失败。技能包需要把“长任务上下文”从聊天窗口里搬到文件和工具里，让 Claude 每轮只读取必要的轻量状态，而不是反复读取所有原始图片、Excel、长 Markdown 和完整历史对话。 ## 落地目标 给 `claude-code-voc-intelligence` 增加一套“省 token 长任务工作流”，用于真实采集任务文档、小红书样本整理、客户素材归档、批量图片/Excel/文本分析等场景。 目标效果： - 用户可以把大量资料放到工作区，Claude 不会一次读完全部文件。 - 每轮最多处理 1 个样本单元，例如 `XHS-001_1`。 - 每个样本单元处理完后，必须写入中间摘要文件。 - 后续会话只读取任务状态、中间摘要和下一个样本单元，不重复读取原始大文件。 - 上下文不足时，技能包能主动生成交接摘要，并提示新会话如何继续。 - 最终报告由多个中间摘要汇总而来，而不是由一个超长会话硬扛到底。 ## 核心设计 采用“原始资料 -> 文件清单 -> 样本单元摘要 -> 总控任务状态 -> 最终报告”的流水线。 ```mermaid 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` 技能包内： ```text 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 ``` 安装到工作区后，运行时在客户项目里生成： ```text .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 直接递归读取全部内容。 建议实现： ```text mcp/src/features/context-budget/file-manifest.js ``` 输入保持简单： ```json { "rootDir": "docs/真实采集任务文档", "taskName": "小红书真实采集任务文档" } ``` 输出内容： - 文件路径 - 文件类型 - 文件大小 - 修改时间 - 所属样本单元推断，例如 `XHS-001_1` - 是否疑似大文件 - 是否建议脚本预处理 不在第一步读取图片正文、Excel 全量内容或长 Markdown 全文。 ### 2. 样本单元识别器 作用：把 `01-06`、`XHS-001_1`、`XHS-008_8` 这类目录识别成可独立处理的样本单元。 建议规则： - 优先识别 `XHS-\d+(_\d+)?` - 其次识别一级/二级目录名 - 允许用户在状态文件里手动修正单元关系 - 每个单元包含：截图、笔记正文、评论、Excel 行、人工备注、校验材料 输出： ```text outputs/voc-context/sample-units.json ``` 示例字段： ```json { "unitId": "XHS-001_1", "status": "pending", "files": [], "summaryPath": "outputs/voc-context/unit-summaries/XHS-001_1.md", "estimatedRisk": "large-image-set" } ``` ### 3. 单元摘要生成器 作用：每轮只处理一个样本单元，并把结果写成结构化摘要。 建议实现： ```text mcp/src/features/context-budget/sample-units.js ``` 摘要模板： ```markdown # XHS-001_1 样本摘要 ## 已读取资料 ## 账号/笔记信息 ## 小红书趋势关键词 ## 用户评论与真实顾虑 ## 可验证话题方向 ## 博主真实度/商业痕迹判断 ## 证据片段 ## 待复核问题 ## 不要重复读取的原始文件 ``` 约束： - 单元摘要控制在 800-1500 字。 - 摘要必须引用文件名，但不要复制大段原文。 - 图片只记录观察结论、截图编号和需要复核的位置。 - Excel 只读取表头、关键列、与当前单元相关的行。 ### 4. 任务状态与检查点 作用：让新会话知道任务做到哪里，不靠历史聊天。 建议实现： ```text mcp/src/features/context-budget/checkpoint.js ``` 生成两个文件： ```text .claude/task-state/voc-context-state.json .claude/task-state/voc-context-state.md ``` 状态内容： - 当前目标 - 已完成样本单元 - 正在处理的样本单元 - 待处理样本单元 - 已生成摘要文件 - 禁止重复读取的原始目录 - 下一步只允许读取哪些文件 - 汇总报告缺口 `voc-context-state.md` 要给人看，`voc-context-state.json` 给工具读。 ### 5. 新会话交接摘要 作用：上下文过大时，直接停止扩读，生成新会话启动提示。 建议实现： ```text mcp/src/features/context-budget/handoff.js ``` 生成： ```text .claude/task-state/handoff.md ``` 内容模板： ```markdown # 新会话交接摘要 ## 当前任务 ## 已完成 ## 不要重新读取 ## 新会话只读取 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` 用途：初始化长任务，扫描目录，生成文件清单、样本单元和任务状态。 输入： ```json { "rootDir": "docs/真实采集任务文档", "taskName": "小红书真实采集任务文档" } ``` 输出： - `assistantMessage`：告诉用户识别出多少样本单元，建议先处理哪个。 - `data.statePath` - `data.sampleUnitsPath` - `nextActions` ### `voc_context_next_unit` 用途：读取任务状态，返回下一轮应该处理的单元和允许读取的文件清单。 输入： ```json { "statePath": ".claude/task-state/voc-context-state.json" } ``` 输出： - 下一单元 ID - 允许读取的文件 - 禁止读取的文件 - 摘要写入路径 ### `voc_context_checkpoint` 用途：处理完一个样本单元后，写入摘要、更新任务状态、生成必要的 handoff。 输入： ```json { "unitId": "XHS-001_1", "summary": "本轮摘要正文", "status": "completed" } ``` 输出： - 更新后的进度 - 下一个单元 - 新会话启动提示 ## CLI 命令设计 为了兼容 Claude Code 工具不可用或客户只会终端的情况，也建议在 `claude-voc` CLI 增加同款命令： ```powershell 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 协议”： ```markdown ## 长任务省 token 协议 - 如果用户要求处理多个样本目录、批量图片、Excel 或长文档，不要一次读取全部资料。 - 先调用/执行 context prepare，生成文件清单、样本单元和任务状态。 - 每轮最多处理 1 个样本单元。 - 每处理完一个样本单元，必须写入 unit summary，并更新 task-state。 - 后续汇总只能优先读取 unit summary，不重复读取原始大文件。 - 当上下文明显变大、用户说继续多次、或任务超过 3 个样本单元时，先生成 handoff，再建议开新会话。 - 新会话只读取 handoff、task-state、sample-units 和必要的 unit summary。 ``` ## 面向用户的话术 当用户给了大批资料时，Claude 应该这样说： ```text 资料比较多，我会按省上下文方式处理：先建立文件清单和样本单元索引，然后每轮只处理一个样本单元。每个单元处理完都会写入摘要，后续汇总只读摘要，不重复读取原始大文件。 我先处理 XHS-001_1，处理完会停下来给你确认。 ``` 当上下文不足时： ```text 当前会话已经接近上下文上限。我已经把进度写入 .claude/task-state/handoff.md。 建议新开一个 Claude Code 会话，并只让它读取 handoff、task-state 和已生成的 unit summary，不要重新读取所有原始图片和 Excel。 ``` 新会话启动 Prompt： ```text 继续处理小红书真实采集任务文档，但请控制上下文。 先只读取： 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：增加文件预处理能力 按优先级实现： 1. Markdown/TXT 分章节摘要。 2. Excel 只提取 sheet 名、列名、前 N 行和命中当前样本 ID 的行。 3. 图片只提取路径、大小、尺寸、所属样本，不直接 OCR 全图。 4. 后续如需要，再接 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/.md`。 - `task-state.md` 能清楚显示已完成、待处理和下一步。 - 新会话只读 handoff 和摘要，也能继续下一单元。 体验验收： - 不再出现“继续”后反复超 token。 - 不让用户理解复杂参数。 - 不把 JSON 调试信息直接甩给用户。 - 不要求用户手动整理 01-06 到 XHS-001 的映射，工具能先自动推断，必要时再让用户确认。 安全验收： - 不把 VOC token、npm token 写入状态文件、摘要文件或报告。 - `.claude/task-state` 可以进入工作区，但任何 `.env.local`、`.npmrc` 不进入 git。 ## 推荐优先落地顺序 建议先做 P0 + P1。 原因： - 这两个阶段能直接解决截图里的核心问题。 - 不需要马上引入 Excel/OCR 复杂依赖。 - 不改变小红书采集接口入参。 - 后续再把工具挂到 MCP，风险更小。 第一轮实施后，真实工作流会变成： ```text 用户给大资料目录 -> Claude 调 context prepare -> 生成样本单元 -> Claude 只处理 XHS-001_1 -> 写摘要和 checkpoint -> 用户确认 -> 下一轮处理 XHS-002_1 -> 最后汇总所有 unit summary ``` 这套方案和当前小红书趋势情报官并不冲突。它是给“资料很多、任务很长、需要跨会话完成”的场景加一层上下文管理能力。