Skip to content

Latest commit

 

History

History
73 lines (53 loc) · 5.88 KB

task-context.md

File metadata and controls

73 lines (53 loc) · 5.88 KB

按任务选择预算内上下文

v0.5.0 起提供 plan_task_context SDK 与同名 MCP 工具,v0.6.0 接入浏览器工作台。v0.7.0 增加 CLI 单次和 JSONL 入口,并提供通用请求配置。调用方列出必选文件和带优先级的候选文件,获得一份不超过 maxTokens 的完整上下文,以及独立的选择审计。

多个任务共享同一份上下文,相同路径只读取、纳入一次。调用方应先为 system 消息、工具定义、会话历史、审计和预计模型输出预留空间,再设置上下文预算。计数器固定为 o200k_base;其他模型的实际计数可能不同。

SDK 调用

在 async fn 中使用已有 Options 和可复用的 Runtime:

let spec = @repomix.TaskContextSpec::from_json({
  "maxTokens": 12000,
  "tasks": [{
    "id": "review-config",
    "required": [{ "path": "src/config/types.mbt", "mode": "full" }],
    "optional": [
      { "path": "src/config/cli.mbt", "mode": "either", "priority": 90 },
      { "path": "src/config/config_test.mbt", "mode": "full", "priority": 70 },
    ],
  }],
})
let result = @repomix.plan_task_context(options, runtime, spec)
// result.text 仅在 complete / with_omissions 时包含可交付正文。
// result.tokens / bytes 是该完整字符串的精确成本。
// result.audit_text 单独返回;audit_tokens / audit_bytes 单独计数。

SDK 返回内存结果,不写文件。现有 pack 的输出后预算检查及 pack_volumes 的逐卷预算行为保持不变。MCP 的资源读取、主机上限与缓存规则见 MCP 指南。

参数与选择顺序

字段 规则
maxTokens 必填,1–2,147,483,647 的整数;MCP 还受启动时的 max_tokens 限制
tasks 1–16 个任务;id 唯一、非空、不含 NUL,最多 64 UTF-8 bytes
required 可省略;条目为 path 与 mode: full / skeleton
optional 可省略;另支持 mode: either 和 priority: 0–100,默认优先级 0
maxReadBytes 1–16,777,216,默认 16 MiB;与 host 总读取上限取较小值
maxAttempts 2–256,默认 256;包含必选文档计数和最后一次核对

所有层级拒绝未知字段。单个 required/optional 数组最多 128 项,所有任务合并后最多 128 个不同路径;每路径最多 4,096 UTF-8 bytes,整个规范化 JSON 描述最多 1 MiB。

路径使用根目录相对的 / 拼写,禁止绝对路径、空组件、.、..、反斜线、冒号与 NUL;通配符字符按文件名原样匹配,不展开。host 的 include、ignore、file_paths、输出排除、单文件及总读取限制继续生效。

  1. 合并相同路径:任一任务将其设为必选,它就成为全局必选;表示强度为 full > skeleton > either;可选优先级取最高值。host keep_full_patterns 始终优先。
  2. 读取并扫描所有必选内容,再渲染完整文档。必选内容不可用或整文超限时立即返回失败。
  3. 按优先级从高到低、相同优先级按路径 UTF-8 字节序尝试可选文件。either 先试全文,超限后再试骨架;单个已读快照不会因换表示重新读取或扫描。
  4. 每次尝试都计数完整渲染字符串,包含任务引用、目录、模板、行号和启用的元数据。拒绝本次候选后继续尝试后续候选;不依赖单文件 token 相加或 BPE 单调性。
  5. 返回前再计数最终字符串。候选选择是确定性的有界贪心,不保证全局最优覆盖。

skeleton 复用已有 AST 压缩;不支持的语言、解析失败或没有单文件 token 收益时保留全文,并在审计中记录实际表示与回退原因。全文回退仍须满足完整文档预算。任务 mode 决定逐文件表示,不依赖 host compress 开关。

当前入口只处理本地文件,不接受远程来源、Git 附加段、自动分卷、原 token_budget 或关闭文件正文展示的 host 配置。这些配置产生 ConfigurationError。host 模板和四种现有输出格式均可使用。

结果与安全边界

status 含义
complete 全部候选已纳入,所有必选要求满足
with_omissions 必选要求满足,可选内容因过滤、安全、预算或工作上限而省略
required_unavailable 必选文件被排除、缺失、无法读取,或必选阶段触及读取上限;无正文
required_over_budget 必选内容连同模板和包装超限;无正文,审计保留该次整文 token 数

空的必选集合仍有模板与任务概览成本,也可能 required_over_budget。失败结果的 tokens 和 bytes 为 0;过预算的测量值在 audit.requiredDocumentTokens 中。

审计逐路径列出是否选择、原因、是否完成安全扫描、实际表示和回退原因,逐任务列出必选满足情况;还记录实际原始读取 bytes、尝试读取数和整文计数次数。它不包含源码正文、密钥匹配文本或绝对根目录。审计中的路径与任务 ID 来自请求,调用方也应按自身隐私要求处理。

正文扫描先于压缩。默认命中秘密的必选文件使整个计划失败,可选文件则被排除;任务描述或模板命中秘密时抛出安全错误。主机显式关闭扫描时,结果标为 security: disabled。扫描是启发式检测,见 安全边界。

读取器为判断是否超过限额最多额外探测一个字节,因此 readBytes 可能等于有效上限加 1。可选阶段触及读取/尝试上限后停止扩展;尚未评估的候选标为 not_evaluated_read_limit 或 not_evaluated_attempt_limit,不会标为已扫描。安全的已选文档经最后核对后仍可返回。

取消在读取和规划步骤之间传播;单次同步扫描、AST 与整文编码不能被步骤间轮询抢占。工作上限不是 RSS 配额,也不计调用方的模型消息或 MCP 外层包装。