context-mode 强制路由规则解析：在 Kiro 上守护 AI 编码 Agent 的上下文窗口

context-mode 强制路由规则解析在 Kiro 上守护 AI 编码 Agent 的上下文窗口【免费下载链接】context-modeContext window optimization for AI coding agents. Sandboxes tool output (98% reduction), persists session memory, and enforces routing across 17 platforms via MCP hooks.项目地址: https://gitcode.com/GitHub_Trending/cl/context-mode导读configs/kiro/KIRO.md是 context-mode 为 Kiro 平台IDE/CLI准备的强制路由规则文件它规定了 Agent 在 Kiro 上必须遵循的工具调用纪律未加路由的原始命令可能一次性向上下文窗口倾倒约 56 KB 数据而本规则把分析从读取中剥离出来用沙箱工具只把最终答案送进上下文。读完本文你将掌握 KIRO.md 的完整规则体系Think in Code、BLOCKED/REDIRECTED 清单、五级工具选择层级、并发批处理与记忆检索约定并理解它在仓库中对应的适配器与 Hook 实现原理可直接把该文件部署到~/.kiro/steering/中获得确定性注入。为什么 Kiro 需要强制路由规则AI 编码 Agent 的上下文窗口是有限资源。每一次工具调用的原始输出——命令回显、HTTP 响应体、搜索结果、文件全文——都会完整进入对话记忆并在会话剩余时间里持续占用推理容量。在 Kiro 上一次未路由的命令输出可以膨胀到约56 KB多次累积就会让窗口迅速被噪声填满模型在关键决策点反而看不清真正重要的内容。KIRO.md 的定位正是解决这个问题的强制纪律文件MANDATORY routing rules。它通过与 context-mode 的 MCP 工具集配合把「分析数据」的职责从 Agent 的上下文窗口转移到沙箱进程原始字节留在沙箱里只有console.log()的派生结果进入对话。从源码看这个文件的部署方式由适配器直接支持src/adapters/kiro/index.ts的getInstructionFiles()返回[KIRO.md]getRoutingInstructions()则从仓库configs/kiro/KIRO.md读取该文件全文作为默认路由指令KiroAdapter的注释明确说明用户可以把该文件复制到.kiro/steering/以选择确定性注入deterministic injection。Think in Code强制分析纪律KIRO.md 开篇第一条硬性规则凡是分析/计数/过滤/比较/搜索/解析/转换数据必须写代码通过context-mode/ctx_execute(language, code)完成只用console.log()输出答案。不要直接把原始数据读进上下文。核心思想是PROGRAM the analysis, not COMPUTE it——用程序做分析而不是把数据读进来人工计算。规范要求使用纯 JavaScript仅限 Node.js 内置模块fs、path、child_process必须try/catch正确处理null/undefined一条脚本可以替代十次工具调用。这一规则在运行时被注入到每次会话的指令块中。hooks/routing-block.mjs的createRoutingBlock()生成的priority_instructions中写有同样表述Every byte a tool returns enters your conversation memory and costs reasoning capacity for the rest of the session并把 Think-in-Code 定义为最高优先级指令。在 Kiro 上工具名的命名空间由 hooks/core/tool-naming.mjs 统一管理Kiro 的 MCP 工具以context-mode/tool形式呈现见TOOL_PREFIXES[kiro]这也是整个 KIRO.md 中所有context-mode/ctx_*工具名的来源。BLOCKED被拦截、禁止重试的操作KIRO.md 明确列出了一类不要尝试重试也无用的操作它们会被 PreToolUse Hook 直接拦截操作替代方案Shellcurl/wgetcontext-mode/ctx_fetch_and_index(url, source)或context-mode/ctx_execute(language: javascript, code: const r await fetch(...))内联 HTTPfetch(http、requests.get(、requests.post(、http.get(、http.request(context-mode/ctx_execute(language, code)——只有 stdout 进入上下文直接 Web 抓取context-mode/ctx_fetch_and_index(url, source)后接context-mode/ctx_search(queries)这些拦截不是文档纸面声明而是路由层的真实行为。在 hooks/core/routing.mjs 中可以看到实现细节检测先剥离引号内内容以避免误报如gh issue edit --body text with curl in itIssue #63再匹配(^|\s||\||\;)(curl|wget)\s模式对 curl/wget 采取允许静默文件下载、拦截 stdout 洪泛策略Issue #166——只有非静默缺少-s/--silent、-q/--quiet的 stdout 输出才会被重定向被拦时返回的引导消息会明确建议改用ctx_execute或ctx_fetch_and_index并注明二者都具备完整网络访问能力遇到瞬时 DNS 错误EAI_AGAIN、ETIMEDOUT、ENETUNREACH可重试同一次调用。拦截语义在 Kiro 上通过退出码落地pretooluse.mjs中deny分支向 stderr 写入原因并以退出码 2 结束blockallow则以退出码 0 放行stdout 内容注入 Agent 上下文。REDIRECTED被引导进入沙箱的操作第二类操作不会直接报错但会被重定向到沙箱工具取决于 Agent 的使用意图Shell输出 20 行——Shell 仅保留给git、mkdir、rm、mv、cd、ls、npm install、pip install。其余场景应使用context-mode/ctx_batch_execute(commands, queries)或context-mode/ctx_execute(language: javascript, code: ...)只有当代码确实匹配宿主 shell 时才用language: shell。路由块中的when_not_to_use给出了精确判据意图处理输出过滤/计数/解析/聚合→ 用批处理或沙箱执行意图观察固定短输出clean tree 上的git status、whoami、pwd或变更状态git、mkdir、rm、mv、导航→ 继续用 Shell。fs_read / read用于分析——读取是为了编辑→ fs_read 正确读取是为了分析/探索/总结→ 用context-mode/ctx_execute_file(path, language, code)。原因很实际编辑工具需要在上下文里匹配精确字节而分析只需要结论。routing-block.mjs的createReadGuidance()把这句话做成了一条在读取工具被调用时注入的轻量提示context_guidancetip。grep / search结果过大——用context-mode/ctx_execute(language: javascript, code: ...)在沙箱里做可移植的过滤与计数。createGrepGuidance()提示当要计数、过滤或聚合匹配结果而非抽查一条时把搜索放进沙箱执行原始匹配列表留在沙箱只有派生答案进入上下文language: shell仅在代码匹配宿主 shell 时使用Windows 用 PowerShellUnix 用 POSIX shell。五级工具选择层级KIRO.md 给出了一套优先级明确的工具选择流程对应注入指令块中的tool_selection_hierarchyMEMORY记忆context-mode/ctx_search(sort: timeline)—— 恢复会话后先查历史上下文再决定是否询问用户GATHER收集context-mode/ctx_batch_execute(commands, queries)—— 一次并行运行所有命令、自动建立索引并返回搜索结果一次调用替代 30 次每个命令形如{label: header, command: ...}label 会成为 FTS5 分块标题描述性 label 能改善后续检索质量FOLLOW-UP追问context-mode/ctx_search(queries: [q1, q2, ...])—— 把所有问题放进数组一次调用默认相关性模式排名流水线按查询逐个执行往返开销只付一次PROCESSING处理context-mode/ctx_execute(language, code)或context-mode/ctx_execute_file(path, language, code)—— 沙箱内执行只有 stdout 进入上下文WEB网络context-mode/ctx_fetch_and_index(url, source)后接context-mode/ctx_search(queries)—— 原始 HTML 永远不进入上下文INDEX索引context-mode/ctx_index(content, source)—— 把内容存入 FTS5 供后续检索。这六步文档编号 0–5构成了完整的先查记忆 → 批量收集 → 批量追问 → 沙箱处理 → 网络检索 → 主动建索引闭环几乎覆盖了 Agent 在真实开发会话中的全部数据消费路径。并行 I/O 批处理与并发度控制多 URL 抓取或多 API 调用场景下KIRO.md 要求始终携带concurrency: N1–8context-mode/ctx_batch_execute(commands: [3 network commands], concurrency: 5)—— 适用于 gh、curl、dig、docker inspect、多区域云查询context-mode/ctx_fetch_and_index(requests: [{url, source}, ...], concurrency: 5)—— 多 URL 批量抓取。并发度的选择原则非常具体I/O 密集型网络调用、API 查询→ 用4–8CPU 密集型npm test、build、lint或共享状态的命令端口、锁文件、同一仓库写入→ 保持1GitHub API 速率限制gh调用并发上限为4。这一规则的价值在于把批处理工具从能用提升到用得对并行度太低浪费往返太高则踩 API 限流或造成端口/锁冲突。输出规范与会话连续性输出Output产物代码、配置、PRD 等必须写入文件绝不内联输出返回时只给文件路径 一行描述。同时为search(source: label)提供描述性 source 标签让后续检索能按来源过滤。这正是路由块中artifact_policy的表述Write artifacts to files. Return only: file path 1-line description。会话连续性Session Continuity技能、角色与决策在整个会话期间持续有效不能随对话增长而丢弃。不过路由块的session_continuity对这一点做了更精细的限定早前捕获的技能/角色/决策是记忆辅助而非常设命令用户的最新消息始终优先如果捕获的指令与当前请求冲突以用户为准——过去的措辞不约束你。Memory先搜索再提问会话历史是持久化且可检索的。恢复会话后KIRO.md 要求先搜索再问用户需求命令我们之前决定了什么context-mode/ctx_search(queries: [decision], source: decision, sort: timeline)存在哪些约束context-mode/ctx_search(queries: [constraint], source: constraint)明确禁止问我们之前在做什么——先搜。若搜索返回 0 条结果才按全新会话处理。这个机制在运行时由agentspawn.mjs落地当事件源为compact或resume时Hook 会加载 SessionDB、读取该会话的持久化事件写入事件文件并追加buildSessionDirective(source, eventMeta, toolNamer)生成的会话恢复指令startup时会清理过期会话cleanupOldSessions(7)并建立新的 session 记录。ctx 命令表KIRO.md 内嵌了一套可直接对用户使用的命令表全部通过 MCP 工具实现命令行为ctx stats调用statsMCP 工具原样显示完整输出ctx doctor调用doctorMCP 工具执行返回的 shell 命令以清单形式展示ctx upgrade调用upgradeMCP 工具执行返回的 shell 命令以清单形式展示ctx purge调用purgeMCP 工具并传confirm: true清空知识库前给出警告特别约定执行/clear或/compact之后知识库与会话统计被保留如需全新开始使用ctx purge。路由块中的ctx_commands还补充了命令变体与行为细节如ctx-stats、/ctx-stats、context savings 问题均触发 stats并规定/clear、/compact后应告知用户context-mode knowledge base preserved. Usectx purgeto start fresh。仓库中的实现适配器、Hook 与配置文件适配器与平台能力Kiro 的支持由 src/adapters/kiro/index.ts 中的KiroAdapter实现其关键平台事实Hook 范式json-stdioHook 注册在 Agent 配置文件~/.kiro/agents/name.json的hooks键下配置~/.kiro/settings/mcp.jsonJSON 格式MCP 通过其中的mcpServers完整支持Hook 退出码0allow2block能力边界canModifyArgs: false——Kiro CLI 只用退出码无法修改工具输入因此路由的modify分支在pretooluse.mjs中会把更新后的命令拆出提示文本写入 stderr 并以退出码 2 拒绝deny with redirect message会话目录~/.kiro/context-mode/sessions/路由文件KIRO.md。测试 tests/adapters/kiro.test.ts 验证了这些契约agentSpawn被映射为 SessionStartsupports sessionStart via agentSpawn、parsePreToolUseInput解析execute_bash工具名、generateHookConfig生成的 matcher 同时包含execute_bash与context-mode/ctx_execute、HOOK_SCRIPTS将agentSpawn映射到agentspawn.mjs。Hook 类型与匹配器src/adapters/kiro/hooks.ts 定义了四种 Hook 类型preToolUse、postToolUse、agentSpawn、userPromptSubmit分别映射到hooks/kiro/下的pretooluse.mjs、posttooluse.mjs、agentspawn.mjs、userpromptsubmit.mjs。PreToolUse 的匹配器数组PRE_TOOL_USE_MATCHERS包括execute_bash、fs_read、context-mode/ctx_execute、context-mode/ctx_execute_file、context-mode/ctx_batch_execute以及一个特殊的外部 MCP 路由匹配器(?!context-mode/)。这个负向前瞻模式针对 Issue #529Kiro 的 MCP 工具在线路上形如server/tool该模式会对任何非 context-mode 前缀的外部 MCP 工具如 slack / telegram / gdrive / notion 类触发 PreToolUse——否则这些服务器返回的大体积负载频道历史、文件内容、搜索结果会绕过路由提示、在 PostToolUse 阶段为时已晚地涌入上下文窗口。routing.mjs的isExternalMcpTool也相应扩展识别server/前缀形状。示例配置文件仓库提供了可直接对照的完整配置configs/kiro/agent.jsonAgent 配置文件示例preToolUse使用管道符合并的匹配器含外部 MCP 负向前瞻postToolUse用*全匹配命令为context-mode hook kiro pretooluse/posttooluseconfigs/kiro/mcp.jsonMCP 注册示例把context-mode服务器指向command: context-mode。各 Hook 脚本职责agentspawn.mjsKiro 的agentSpawn等价于 Claude Code 的 SessionStart在 Agent 加载时触发一次负责注入路由块createRoutingBlock其中工具名经由createToolNamer(kiro)生成context-mode/ctx_*形式以及恢复/压缩场景下的会话恢复指令输出形状为{ hookSpecificOutput: { hookEventName: agentSpawn, additionalContext } }pretooluse.mjs调用routePreToolUse(tool, toolInput, projectDir, kiro, sessionId)得到决策按deny退出码 2 stderr 原因、modifyKiro 无法改输入 → 拆出提示文本后以退出码 2 拒绝、contextstdout 注入附加上下文退出码 0、askKiro 无 ask 概念 → 直接放行分发posttooluse.mjs非阻塞的会话事件捕获注释明确要求必须在 20ms 内完成——不联网、不调 LLM只做 SQLite 写入extractEvents从工具名/输入/响应中抽取事件后经attributeAndInsertEvents落库userpromptsubmit.mjs捕获用户提示用于连续性自动跳过task-notification、system-reminder、context_guidance、tool-result等系统消息其余提示作为user_prompt事件入库并做项目归属解析。安装与使用前提要将这套规则投入 Kiro 环境前提是完成 context-mode 在 Kiro 上的安装与注册配置示例见上文两个文件将 context-mode 注册到 Kiro 的 MCP 配置~/.kiro/settings/mcp.json的mcpServers命令为context-mode使context-mode/ctx_*工具可用在~/.kiro/agents/name.json的hooks下配置preToolUse、postToolUse、agentSpawn、userPromptSubmitagentSpawn与preToolUse为必需项postToolUse与userPromptSubmit为可选项见hooks.ts的REQUIRED_HOOKS/OPTIONAL_HOOKS可选把本文件复制到.kiro/steering/启用确定性注入Hook 未配置时KiroAdapter.validateHooks()会给出context-mode upgrade的修复提示checkPluginRegistration()则检查 MCP 注册状态。完成上述部署后Kiro 上的 Agent 将在每次启动时收到路由指令块遵循本文所述的强制规则原始输出留在沙箱只有派生答案进入上下文窗口。【免费下载链接】context-modeContext window optimization for AI coding agents. Sandboxes tool output (98% reduction), persists session memory, and enforces routing across 17 platforms via MCP hooks.项目地址: https://gitcode.com/GitHub_Trending/cl/context-mode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考