Repomix 内嵌 Agent Carnet 技能：Carnet Frontmatter 结构与字段生命周期全解析-北京尧图网络

Repomix 内嵌 Agent Carnet 技能Carnet Frontmatter 结构与字段生命周期全解析【免费下载链接】repomix Repomix is a powerful tool that packs your entire repository into a single, AI-friendly file. Perfect for when you need to feed your codebase to Large Language Models (LLMs) or other AI tools like Claude, ChatGPT, DeepSeek, Perplexity, Gemini, Gemma, Llama, Grok, and more.项目地址: https://gitcode.com/GitHub_Trending/rep/repomix本篇文章以 Repomix 仓库内嵌的 agent-carnet 技能参考文档 frontmatter.md 为主体系统讲解 CarnetMarkdown 笔记本条目的 YAML frontmatter 契约CLI 托管字段与保留字段如何划分、四个时间/计数器字段的生命周期语义、meta:扩展命名空间如何与下游工具协作以及lifespan、keep、related等字段的准确用法。读完本文你将能安全地读写任何 Carnet 的 frontmatter、判断陌生字段在 CLI 写入后是否存活并为自己的工具或约定设计可组合的元数据扩展。Carnet 与 Frontmatter 的定位agent-carnet 是一个极简 CLI 工具在磁盘上以.carnet/category/slug.md的形式维护一个共享的 Markdown 笔记本条目默认拥有 30 天生命周期每次被读取或应用都会重置真正有用的笔记得以存活过时的笔记自动漂移到.trash/目录。在本仓库中该技能被放在 .agents/skills/agent-carnet/ 目录下包含 SKILL 主文件 SKILL.md、cookbook 模式参考 cookbook.md 和本文的主角 frontmatter 参考 frontmatter.md。每一个 Carnet 都以 YAML frontmatter 开头。CLI 自己只管理一小部分字段其余字段在往返读写时原封不动地保留因此工具和约定可以在其上叠加额外的元数据。这正是整个扩展模型的地基只要你不触碰 CLI 托管的命名空间你的自定义字段就能在每一次 CLI 写入后存活。frontmatter.md 开篇明确了这份参考文档的使用时机当你准备写入或读取meta:命名空间、设置非平凡的lifespan/keep、或者怀疑某个陌生 frontmatter 字段能否在 CLI 写入后存活时就应该阅读它。SKILL.md 也给出了同样的指引——日常记笔记只需要 SKILL 主文件即可参考文件不是常驻上下文不应被投机性地加载。Frontmatter Schema 总览Carnet 的 frontmatter 完整 schema 如下字段按CLI 托管、可选但 CLI 已知、CLI 不感知透明保留三类组织--- # CLI-managed (you provide these on save; usage fields update via show / used) summary: one-line decisive description # required agent: claude-code # required (e.g. claude-code, codex, cursor, human) created: 2026-05-10 # set on first save, immutable thereafter updated: 2026-05-10 # bumped on save / save --update (content modification) last_used: 2026-05-10 # bumped on save / show / used (drives expiry) use_count: 7 # incremented on used only (importance signal) # Optional, CLI-known tags: [compat, esm] # free-form labels; comma-separated on save related: # paths or other carnet paths this entry points at - src/core/file/encoding.ts - .carnet/deps/iconv-issue.md lifespan: 90d # override default 30d; accepts 30d / 90d / 1y / never keep: true # pin against auto-prune (lifespan ignored) # Optional, CLI-opaque meta: # free-form extension namespace; see meta: below extension: key: value ---关键字段的语义逐条展开summary必填一行决定性的描述。SKILL.md 强调必须果断、有决断力——单独阅读 summary 就应该让下一位读者或下一个 Agent判断是否值得继续读正文。agent必填记录该 Carnet 所属的 Agent 身份例如claude-code、codex、cursor、human。created首次save时写入之后不可变相当于条目的出生日期。updated仅在内容被修改时save/save --update递增与使用情况完全解耦。last_used任何交互save/show/used都会刷新直接驱动过期判定。use_count只在显式调用used时递增是条目的重要性信号。tags自由标签save时以逗号分隔传入如--tags compat,esm。related指向源码路径或其他 Carnet 路径的关联列表。lifespan覆盖默认 30 天生命周期的时长字符串。keep将条目永久钉住使其免于自动清理。meta:完全自由形态的扩展命名空间CLI 不解释、不透传修改但会原样保留。四个 CLI 托管的时间与计数器字段agent-carnet刻意将**修改modification与使用usage**分离让两者可以被独立观测和排序。四个字段的精确语义如下字段由谁触发更新含义createdsave仅首次出生日期。永不改变。updatedsave、save --update最近一次内容修改。last_usedsave、show、used最近一次交互。驱动过期expiry last_used lifespan。use_countused仅此一个命令Carnet 被显式应用的次数。参考信号重要性。这里蕴含着两档使用信号的区分show是弱使用信号把正文拉入上下文就足以维持生命周期存活刷新last_used但不会递增use_count。used是强使用信号在 Carnet真正塑造了你的工作之后才应调用——例如你应用了其中记录的修复并解决了 bug、在重试某个假设前查阅了 Carnet 从而跳过了一条死胡同、或者在写新代码时采用了vocabCarnet 中的规范命名而非自己另造一个。used会同时递增last_used与use_count。use_count是一个跨会话存续的持久化重要性信号agent-carnet list --sort use_count可以让承重笔记浮到最前。对应命令示例agent-carnet show deps/iconv-issue # 读取全文刷新 last_used弱信号 agent-carnet used deps/iconv-issue # 标记为实际应用刷新 last_used 并递增 use_countupdated只追踪内容修改独立于last_used不是生命周期过期的驱动者——这是新手最容易混淆的一点。CLI 托管字段与保留字段扩展模型的基石CLI 只会重写它认识的字段完整清单为summary、agent、created、updated、last_used、use_count、tags、related、lifespan、keep。在save --update时其他所有顶层 frontmatter 键都会被原样往返保留——包括meta:以及任何外部工具添加的自定义键。这意味着扩展模型的规则非常简单只要你不占用 CLI 托管的字段名你的字段就能在每一次 CLI 写入后存活。这一定位也解释了为什么不应往顶层塞入新的结构化字段顶层是 CLI 的领地任何新的顶层键都冒着与未来 CLI 版本冲突的风险而meta.extension.*是专门为此预留的扩展地带。meta: 扩展命名空间meta:是存放结构化数据的刻意设计——CLI 自身不解释这些数据但下游消费者可以基于它们行动一个 Obsidian 插件、一个兄弟 Agent、你自己的脚本或者 cookbook 中的模式约定。使用约定有三条按约定名对键命名空间化使用meta.vocab.*、meta.hypothesis.*、meta.your-tag.*这样的前缀避免不同独立扩展之间发生碰撞。值尽量保持原始类型字符串、数字、字符串列表。任何更复杂的内容应该放进正文——那里才是人类真正会阅读的地方。CLI 目前没有--meta标志要设置或修改meta:需要在save之后直接编辑 Carnet 文件或让你的工具直接写文件。下一次 CLI 写入save --update、touch、show都会保留你的编辑。从其他工具读取meta:用任何 YAML frontmatter 解析器解析文件即可如gray-matter或js-yaml配合手动 frontmatter 切分。CLI 在读取侧不强求任何特定工具链。按约定分类的两个典型示例meta: vocab: canonical: staging adapter aliases: [proxy layer, forward middleware]meta: hypothesis: status: debunked # pending | confirmed | debunked last_tested: 2026-04-30这两个示例并非孤立存在——仓库中的 cookbook.md 给出了它们背后的完整模式。以vocab词汇对齐模式为例当多个 Agent或人与 Agent 协作为同一概念不断发明不同名称时staging adapter vs proxy layer vs forward middleware 指向同一个模块就为一个术语建一个带tags: [vocab]的 Carnetmeta.vocab.*存放机器可操作的数据canonical 名称、别名正文用叙述形式解释为什么叫这个名字。hypothesis假设账本模式则用于调试中反复产生的死胡同知识每个假设一个带tags: [hypothesis]的 Carnet正文承载推理过程Hypothesis / Tests / Verdictmeta.hypothesis.status以pending/confirmed/debunked三种状态承载结构化判定让其他工具无需重读正文即可行动。这正是 frontmatter 扩展模型与 cookbook 模式组合的价值CLI 完全不需要认识某个模式find和show对携带任何标签的 Carnet 都以同样的方式工作。lifespan自定义生命周期时长lifespan接受经由parse-duration解析的时长字符串30d、7d、12h—— 相对时长1y、6mo、2w—— 更长的单位never—— 钉住并免于自动清理等价于keep: true。当keep: true与lifespan: duration同时存在时keep: true胜出——无论时长是多少该 Carnet 都不会被自动清理。设置lifespan的适当时机是某一类笔记天然比默认的 30 天活得更久或更短。例如稳定的架构决策笔记可以设1y而冲刺sprint范围的笔记设7d。过期公式为expiry last_used lifespan因此lifespan需要配合使用频率来理解一个被频繁show/used的条目即便lifespan很短也会因last_used持续刷新而存活。keep将条目永久钉住keep: true将 Carnet 无限期钉住使其免于自动清理。它应当被谨慎使用——因为它会破坏可以放心遗忘safe to forget的模型。典型的适用场景项目级参考文档不应随时间衰减需要无限期保留上下文的长周期设计决策个人风格或人设persona文件。keep: false与省略keep:默认值完全等价。related关联引用related:接受字符串列表没有强制格式。常见约定有三种相对于项目根目录的文件路径如src/core/file/encoding.ts其他 Carnet 路径如.carnet/category/slug.mdURL如指向上游 issue 的地址。需要特别注意的是CLI不校验这些目标是否存在也不会跟随它们。它们只是文档性质的关联说明而非 CLI 会遍历的链接。这也意味着在related中写错路径不会导致任何报错写对路径则能帮助后续读者或 Agent快速跳转到相关代码与相关笔记。不要向 frontmatter 添加什么为了保持 schema 的稳定与可组合性参考文档明确列出了三类禁区不要在顶层添加status:字段schema 中没有它的位置。如果需要调试状态用tags: [hypothesis:debunked]或meta.hypothesis.status约定来表达。不要为结构化数据新增顶层字段请使用meta.extension.*这样它才能与所有其他扩展组合共存。不要让summary:换行保持在一行内——列表与搜索界面都假设 summary 是单行的。这三条规则的共同出发点与CLI 托管 vs 保留字段一脉相承顶层空间留给 CLI 与稳定的核心语义一切可变的、约定化的结构化数据都归入meta:命名空间。Frontmatter 解析错误的处理如果某个 Carnet 的 frontmatter 解析失败YAML 非法、分隔符不匹配CLI 会以frontmatter_error退出并指出出错的文件。处理方式很明确直接编辑该文件修复问题CLI不会尝试自动修复。也就是说frontmatter 的语法正确性是用户的职责CLI 只在检测到错误时给出明确信号绝不越权改写。这与CLI 只重写它认识的字段的设计哲学完全一致——宁可报错也不做可能产生破坏的自动修复。在仓库中的定位与配套资料在本仓库中agent-carnet 以 GitHub skill 的形式被锁定skills-lock.json 记录其来源为yamadashy/agent-carnet仓库的skills/agent-carnet/SKILL.md并带有内容哈希校验。它被安装于 .agents/skills/agent-carnet/ 目录属于项目为 Agent 协作准备的一等公民资产。与此参考文件配套的资料包括SKILL.md日常使用的完整指南包含save/find/list/show/used/move/rm全部子命令的速查、何时保存、何时召回、硬性规则如--summary必填、--agent claude-code必填、30 天过期自动执行且无需手动清理、被删条目先进入.carnet/.trash/保留 7 天后再硬删除以及category/slug的路径约定kebab-case、无前导斜杠、无..、允许子分类如deps/esm/iconv-issue。当你不确定某个子命令的完整参数集时运行agent-carnet command -h即可查看聚焦的帮助信息。cookbook.md基于标签tags:与meta:组合的进阶模式包括vocab词汇对齐与hypothesis假设账本两大完整模式以及新增模式的通用方法——选定一个标签名、可选地在meta.your-tag.*下命名空间化结构化数据、让正文承担其余解释CLI 无需感知模式本身。发明新模式时建议把模式自身记录在项目的 Carnet如一个 canonical 名称即为该模式的vocab/条目中让未来的 Agent 能以发现其他约定的同样方式发现它。本文档 frontmatter.mdfrontmatter 契约的权威参考按 SKILL.md 的指引仅在确实需要读写meta:、设置非平凡lifespan/keep或怀疑陌生字段存活问题时才读取。实战速查把本文的全部要点压缩成一张可直接照做的清单保存时永远提供必填项agent-carnet save category/slug --summary ... --agent claude-code可追加--tags a,b。想改meta:先save再直接编辑文件下一次任何 CLI 写入都会保留你的修改。想让某类笔记活得更久lifespan: 1y架构决策或lifespan: 7d冲刺笔记想永久钉住用keep: true两者冲突时keep优先。给related:填项目相对路径或其他.carnet/...路径CLI 不校验、不跟随纯文档性质。使用show维持生命、用used标记重要性——只有used递增use_count。结构化扩展数据一律放meta.your-tag.*值保持原始类型绝不新增顶层字段、绝不添加顶层status:、绝不让summary换行。frontmatter 解析失败时以frontmatter_error退出并指明文件直接手工修复CLI 不做自动修复。遵循这份契约Carnet 既是 Agent 与人类共享的可遗忘笔记本也是一个可被任意下游工具安全扩展的开放数据结构。【免费下载链接】repomix Repomix is a powerful tool that packs your entire repository into a single, AI-friendly file. Perfect for when you need to feed your codebase to Large Language Models (LLMs) or other AI tools like Claude, ChatGPT, DeepSeek, Perplexity, Gemini, Gemma, Llama, Grok, and more.项目地址: https://gitcode.com/GitHub_Trending/rep/repomix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Repomix 内嵌 Agent Carnet 技能：Carnet Frontmatter 结构与字段生命周期全解析

相关推荐

区块链技术演进与2026年五大高潜力应用领域

微波笔记：射频工程师的结构化设计日志方法

C++解释器模式实现与性能优化指南

更多资讯

业务架构是什么？大白话讲透实战认知框架

CodeScope Cypher 查询模式实战：用知识图谱深挖代码调用链、演化史与架构风险

Metabase Cloud 实例怎么配置自定义域名？

研究设计定了之后，Academic Research Skills 如何帮你选对 EQUATOR 报告指南（PRISMA/CONSORT/STROBE/CARE 等）？

YOLOv5+CRNN中文车牌识别：从数据准备到端到端部署

N2高频语法与词汇辨析：备考突破指南

今日更新

Linux 内核 ARM 虚拟内存布局全解析：从 4GB 地址空间划分到源码级验证

AIGC降重工具测评与教育应用指南

数据容灾核心指标与实战方案解析

本周精选

超人会飞不算本事：系统稳定依赖清晰规则与边界设计

超人VS蜘蛛侠：拆解超级IP的影响力与传播方法论

基于CNN的调制信号识别：MATLAB实现时频图分类实战

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？