51 lines
3.8 KiB
Markdown
51 lines
3.8 KiB
Markdown
# 任务上下文预算
|
||
|
||
完整治理流程见 [`CONTEXT_GOVERNANCE.md`](CONTEXT_GOVERNANCE.md)；本页只保留机器需要的预算和索引契约。
|
||
|
||
本项目把“能否持续执行”定义为可检查的输入预算，而不是依赖执行者自行控制阅读量。每轮领取任务只加载一个最小上下文包：
|
||
|
||
1. `docs/EXECUTION_QUEUE.md`：当前指针和规则，最多 4 KiB。
|
||
2. `docs/tasks/<task>.md`：一个行为的任务卡，最多 8 KiB。
|
||
3. `tests/golden/<parent>/manifest.json`：只取 parent、runtime、artifact hash、`nextTask`，最多 24 KiB。
|
||
4. `docs/status/<parent>.md`：只取上一任务的证据摘要，最多 6 KiB。
|
||
|
||
四份输入和证据内容最多占 2,476 tokens；另有 1,024 tokens 保留给打印任务包自身的 JSON 外壳，
|
||
因此模型实际输入仍不超过 3,500 tokens。实现代码、长日志、完整路线图和 parity ledger 只按任务卡列出的路径追加读取；它们不是默认上下文。
|
||
|
||
任务上下文生成器在生成 `inputPaths` 时还会前置执行证据筛选：最多 12 个证据路径，证据文件总计最多
|
||
8 KiB，并从扣除 1,024-token 打印外壳和四份基础文档后的剩余空间中选择。超限、缺失、越界或不可审计路径不会进入读取清单，
|
||
而会写入 `inputSelection.excluded[]`，其中 `reason` 是稳定的机器可读排除原因；治理门会校验所选路径、字节总数和排除审计。
|
||
|
||
默认 `print-task-context` 只输出紧凑任务包；完整选择审计仍写入 `task-context.json`，不会重复进入模型输入。
|
||
如果紧凑包自身超过预留外壳预算，`print-task-context` 会在 stdout 写入任何 JSON 前失败，避免超大包进入远程传输。
|
||
|
||
全量 gap 计划 `tests/golden/M15-03A/next-task-plan.json` 约 6.8 MiB，只能由盘点/生成门读取，禁止作为任务上下文打开。`task-index.json` 保存源计划 hash 和每条记录的偏移，`task-catalog.jsonl` 保存一行一个任务；`task-context` 只随机读取当前任务的一行。索引缺失、源 hash 漂移或 catalog 损坏会直接失败，不能回退加载整份计划。
|
||
|
||
## 机器门禁
|
||
|
||
```bash
|
||
npm --prefix web run test:task-context
|
||
npm --prefix web run test:context-governance
|
||
node tools/web/generate-task-index.mjs
|
||
node tools/web/check-task-index.mjs
|
||
node tools/web/generate-task-card.mjs --task <task-id>
|
||
node tools/web/print-task-context.mjs
|
||
node tools/web/print-task-context.mjs --task <task-id>
|
||
node tools/web/check-task-context.mjs --task <task-id> --write
|
||
node tools/web/check-context-governance.mjs
|
||
```
|
||
|
||
`check-task-context` 会确认队列指针、parent manifest、任务卡/索引、命令入口和预算一致。失败时不能领取任务，也不能手工修改 `nextTask`。索引只由计划生成门更新，执行任务不得手工编辑 catalog 或 offset。
|
||
|
||
推进到新任务时，若 `docs/tasks/<task>.md` 不存在，先运行 `generate-task-card.mjs --task <task-id>`；它只从 catalog 的一条记录生成一张短卡，生成后再运行 `check-task-context`。禁止为了生成一张卡读取完整 plan。
|
||
|
||
## 文档分层
|
||
|
||
- 当前执行：`EXECUTION_QUEUE.md`、当前任务卡、parent `manifest.json`、parent `status`。
|
||
- 机器索引：`tests/golden/M15-03A/task-index.json`、`task-catalog.jsonl`；仅由工具读取，不是执行者要通读的文档。
|
||
- 稳定契约：`WEB_BLENDER_MODELER_V1_SCOPE.md`、协议/schema、工具入口。
|
||
- 背景规划：`CURRENT_EXECUTION_PLAN.md`、`PROJECT_STATUS_AND_NEXT_WORK.md`、完整 parity/WBS 计划。
|
||
- 历史证据：`docs/status/` 其余文件、`tests/golden/` 其余构件、`test-results/`。
|
||
|
||
背景和历史文档不得在任务卡中复制；需要时只引用一个小节或一个具体构件。若文字与机器 manifest 冲突，以命令输出和 manifest 为准。
|