Agent Skill 执行上下文记忆机制：用 Hook 与 Skill Registry 落地可复现配置

1. 多轮执行里Skill 为什么总是“失忆”Agent Skill 执行上下文说白了就是技能在跑的时候必须知道的那点事当前走到第几步、上一步产出了什么、有没有遗留问题没处理完。它跟 Skill 本身是两码事——Skill 是“怎么做”上下文记忆是“做过什么”。你写一个SKILL.md里面全是标准操作流程但它天生无状态跑完就忘下次再触发同一个技能它压根不知道上次停在哪。这个痛点在我本地 AI 编码工具链里特别明显。举个真实场景我有个技能负责扫代码仓库里的敏感配置第一轮扫出 272 条白名单记录、1632 条违规其中两条待处理问题sudo -i没进白名单、密码明文。结果第二轮我让它“继续处理上次的问题”它一脸茫然重新全量扫一遍脏数据又写了一遍报告里还多出一份重复的飞书文档。这就是典型的上下文丢失——重试造成脏数据多轮任务串不起来。为什么需要记忆机制三个价值上下文延续同一个 Skill 多次调用能引用之前的结论和数据个性化适配你习惯的报告格式、白名单规则记一次就不用反复交代状态追踪一个完整任务往往分多轮先查日志、再分析、再写报告记忆负责把这些步骤串成一条线。这篇就围绕两个落地角度拆Hook 拦截和 Skill Registry 注册。前者需要内核支持在技能激活/退出时自动跑脚本后者最轻量维护一个状态文件立刻能做。我会给出可复制的settings.json/config.toml骨架加上 TaoToken 统一 Key 的接入片段最后带你触发一次跨轮 Skill 调用确认上下文真的被读写。2. 前置准备TaoToken 统一 Key 与本地工具链在动手改配置之前先把模型接入这层理顺。本地 AI 编码工具链通常要配多个模型的 KeyClaude、GPT 各一套管理起来烦。TaoToken 的作用就是把这些统一成一个 KeyOpenAI 兼容接口改个base_url就能切模型省得每个工具单独维护凭证。你需要准备的东西不多一个 TaoToken 账号、一个 API Key、本地已经装好的编码工具比如支持 Skill 的 Agent 框架。Key 的获取路径是控制台里的 API Keys 页面生成后复制出来注意别提交到 Git。接入地址分两个别搞混用途地址官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 基址https://taotoken.net/apiAPI 基址不加 UTM 参数直接填到工具的base_url里。模型名按你实际要用的填比如claude-sonnet-4-20250514这类具体以控制台模型列表为准。注意Key 只存在本地环境变量或工具的加密配置里不要硬编码进SKILL.md或提交到仓库。后面配置片段里我用${TAOTOKEN_API_KEY}占位。如果你还没生成 Key先去控制台建一个已经有的话直接进下一节。接入文档在 https://taotoken.net/doc 可以对照参数。3. 可复制配置settings.json 与 config.toml 骨架这一节给两套骨架一套是 Skill Registry 的状态文件加工具配置一套是 Hook 系统的 frontmatter 加内核配置。你按自己工具链支持的程度选两个可以叠加用。3.1 Skill Registry 状态文件在 workspace 根目录建skills/registry.json结构如下。每个技能一个 key记录上次运行时间、总次数、上次结果摘要、以及待处理的活跃上下文{ my-skill-name: { last_run: 2026-07-01T19:00:0008:00, total_runs: 6, last_result: { records: 2011, users: 24, violations: 1632, top_risk_users: [you.wangmsxf.com, ke.peng01], feishu_doc: https://feishu.cn/docx/IXfcdCGczoz1ZyxnRG4cTJbEnE3 }, active_context: { pending_issues: [sudo -i not in whitelist, password plaintext], whitelist_count: 272 } } }然后在SKILL.md里加两个步骤执行前读、执行后写。这是最轻量的做法不需要内核改一行代码# 执行前 ### 1. 加载技能上下文 读取 skills/registry.json 中对应技能的 active_context 了解上次遗留的问题和状态把 pending_issues 注入本轮任务。 # 执行后 ### 8. 保存技能上下文 将本次运行结果摘要更新到 skills/registry.json 保留 pending_issues 供下次引用更新 last_run 和 total_runs。3.2 工具侧 settings.json如果你的工具读settings.json把 TaoToken 接入和 Skill 目录配进去{ model: { provider: openai-compatible, base_url: https://taotoken.net/api, api_key: ${TAOTOKEN_API_KEY}, model_name: claude-sonnet-4-20250514 }, skills: { registry_path: ./skills/registry.json, auto_load_context: true, auto_save_context: true } }auto_load_context和auto_save_context打开后框架会在技能激活时自动读 registry、退出时自动写回省得你在SKILL.md里手写步骤。3.3 Hook 系统 config.tomlHook 需要内核支持借鉴 Claude Code 的onActivate/onDeactivate思路。先在SKILL.md的 frontmatter 里声明钩子--- name: my-skill-name context: fork hooks: onActivate: scripts/pre-flight.sh onDeactivate: scripts/post-flight.sh onActivateSubagent: true ---再在config.toml里配内核行为[skill.hooks] enabled true parse_frontmatter true middleware skill-match-layer [skill.hooks.on_activate] run_in_subagent true timeout_seconds 30 [skill.hooks.on_deactivate] write_registry true release_temp true内核实现思路是解析SKILL.md的 frontmatter发现hooks字段后在技能匹配层加一个中间件。onActivate在技能激活时自动执行预置脚本做环境校验、数据准备、记录 traceonDeactivate在技能完成后执行清理写结果、释放临时资源、更新 registry。context: fork配合onActivateSubagent让钩子在隔离子 agent 里跑不污染主会话。pre-flight.sh和post-flight.sh两个脚本骨架#!/usr/bin/env bash # scripts/pre-flight.sh set -euo pipefail REGISTRYskills/registry.json SKILL_NAMEmy-skill-name echo [pre-flight] loading context for ${SKILL_NAME} jq -r --arg s $SKILL_NAME .[$s].active_context.pending_issues[]? $REGISTRY \ | while read -r issue; do echo pending: $issue; done#!/usr/bin/env bash # scripts/post-flight.sh set -euo pipefail REGISTRYskills/registry.json SKILL_NAMEmy-skill-name NOW$(date -Iseconds) jq --arg s $SKILL_NAME --arg t $NOW \ .[$s].last_run $t | .[$s].total_runs 1 $REGISTRY tmp.json \ mv tmp.json $REGISTRY echo [post-flight] registry updated at ${NOW}提示jq是处理 JSON 状态文件最顺手的工具macOS 用brew install jqLinux 用包管理器装。脚本记得chmod x。4. 验证触发一次跨轮 Skill 调用配置写完得验证上下文真的被读写。我试过的验证流程分三步你照着走一遍就能确认。第一步确认 registry 初始状态。跑一次技能前先看active_context里有没有遗留问题jq .my-skill-name.active_context skills/registry.json预期输出类似{ pending_issues: [sudo -i not in whitelist, password plaintext], whitelist_count: 272 }第二步触发技能让它读上下文。在对话里输入“继续处理上次遗留的问题”观察日志里有没有[pre-flight] loading context和pending: sudo -i not in whitelist。如果 Hook 生效这两行会出现在技能激活的瞬间。第三步技能跑完后检查 registry 是否被写回。last_run应该更新成当前时间total_runs加一jq .my-skill-name | {last_run, total_runs} skills/registry.json成功结果长这样{ last_run: 2026-07-01T19:32:1108:00, total_runs: 7 }如果total_runs从 6 变成 7last_run是刚才的时间说明跨轮上下文读写链路通了。再触发一次看它能不能引用上一轮的pending_issues而不是重新全量扫能引用就说明记忆机制真正落地了。5. 本篇常见错排查registry.json 没更新先确认auto_save_context或post-flight.sh有没有真的执行。手动跑一遍bash scripts/post-flight.sh看有没有报错。常见原因是脚本没有执行权限或者jq没装。Hook 不触发检查SKILL.mdfrontmatter 的hooks字段缩进对不对YAML 对空格敏感。再看config.toml里enabled true有没有漏。如果内核版本不支持 frontmatter 解析parse_frontmatter打开也没用得升级内核。上下文串了技能多个技能共用一个 registry 时key 写错就会读到别人的active_context。确认SKILL_NAME变量和 registry 里的 key 完全一致大小写都算。TaoToken 请求 401base_url填成https://taotoken.net/api别多加斜杠或路径。Key 从环境变量读确认echo $TAOTOKEN_API_KEY有值。模型名写错也会报错对照控制台模型列表核对。子 agent 里钩子不跑context: fork和onActivateSubagent: true要同时开。只开 fork 不开 subagent钩子还在主会话跑隔离没生效。pending_issues 越积越多这是设计问题不是 bug。每次处理完的问题要从pending_issues里移除否则下次还会被注入。在post-flight.sh里加一段过滤逻辑把已解决的 issue 删掉。6. 接入与排障入口上面这套配置跑通后模型接入这层如果还有问题直接去 API Keys 页面重新生成一个 Key 对照测试https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite参数对不上、报错看不懂接入文档里有完整的字段说明和示例https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite想先验证模型本身通不通不进编码工具直接在模型对话里发一条测试请求最快https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite如果你是要长期跑编码任务、Agent 多轮调用频繁Coding Plan 比按次调用更划算配置方式在控制台里https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite最后补一句实操经验registry 文件别放在会被 Git 追踪的目录里加进.gitignore。状态文件是运行时产物提交上去每次 diff 都变团队协作时容易冲突。我一般放./skills/.runtime/registry.json整个.runtime目录忽略掉。