Repomix 中的 Agent Carnet 标签模式实战：用 `tags` + `meta` 为智能体共享笔记建立可机器读取的结构

Repomix 中的 Agent Carnet 标签模式实战用tagsmeta为智能体共享笔记建立可机器读取的结构【免费下载链接】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 仓库内.agents/skills/agent-carnet技能体系中的 Cookbook 模式文档系统讲解如何在现有agent-carnetCLI 之上仅用tags:与可选的meta:命名空间为每一条共享 Markdown 笔记carnet附加结构化信息让下游工具与其他智能体能够识别、检索并复用这些约定。读者将掌握「词汇对齐」vocab与「假设台账」hypothesis两套标准模式的具体写法、配套的 Agent 操作流程以及如何扩展出自己的新模式。背景agent-carnet 是什么在深入 Cookbook 模式之前需要先交代它赖以存在的载体。.agents/skills/agent-carnet/SKILL.md定义了一个名为agent-carnet的小型 CLI它在磁盘上的.carnet/category/slug.md路径下维护一份共享的 Markdown 笔记本。笔记默认拥有 30 天生命周期每次被读取或应用都会重置有用的笔记存活下来陈旧的笔记自动漂移到.trash/。这一设计在仓库中由 skills-lock.json 以「锁定技能」的形式被引用source: yamadashy/agent-carnet与contextual-commit一同作为 Repomix 开发流程中智能体协作的配套约定。SKILL.md 明确说明日常记笔记只需要基础 SKILL.md无需阅读 references只有当你准备使用或被人问及基于标签的模式如tags: [vocab]表示项目术语、tags: [hypothesis]表示调试死胡同时才读取references/cookbook.md本篇文章的主体。Cookbook 文档开篇即点明核心理念这些是基于标签的约定与现有 CLI 组合使用——不需要新命令不需要特殊文件夹。每个模式用tags:和可选的meta:给 carnet 附加额外结构供下游工具或未来智能体识别。这意味着模式层的扩展成本为零CLI 对标签一无所知find与show对任何标签的处理方式完全一致。模式一词汇对齐tags: [vocab]适用场景当多个智能体或一个人加一个智能体在同一个项目中不断为同一概念发明不同的名字时使用。文档给出的例子非常典型staging adapterproxy layerforward middleware这三个词实际指的是同一个模块——位于POST /v1/stage之前的薄代理层。术语分裂会导致检索失效、代码注释混乱、智能体之间互相无法理解。模式结构模式约定每个术语一条 carnet打上vocab标签。meta.vocab.*子树承载机器可读的数据canonical name、aliases正文则以叙述形式解释「为什么叫这个名字」。--- summary: staging adapter — the thin proxy in front of POST /v1/stage agent: claude-code tags: [vocab] related: - .carnet/vocab/payload-envelope.md - src/staging/adapter.ts meta: vocab: canonical: staging adapter aliases: - proxy layer - forward middleware - request shim --- # staging adapter ## Definition The thin proxy that fronts the production gateway and reshapes incoming requests into the payload-envelope format. Nothing more. ## Why this name proxy is overloaded; middleware collides with the Express concept. staging adapter leaves no doubt about which layer is meant.注意这个示例同时展示了meta:与related:的组合用法结构化别名数据放在meta.vocab.*而指向真实代码文件src/staging/adapter.ts与其他 carnet 的关联则放在related:。Agent 操作流程文档给出了三步标准流程命名新概念前先扫描既有规范名agent-carnet find candidate --in tags agent-carnet find candidate --in body如果已存在 vocab carnet就采纳那个名字——在代码中、PR 描述中、后续 carnet 中统一使用。当某个名字胜出成为规范名时按上述约定保存一次并通过related:从相关代码或其它 carnet 引用它。Refresh-on-use使用即刷新完成其余工作持续被引用的同义词保持存活无人调用的条目会自动漂移到.trash/。从源码结构看这一步的机制与 SKILL.md 中描述的 30 天生命周期与last_used刷新逻辑一致——find不产生任何信号只有show弱信号与used强信号会驱动存活状态。也就是说「一个术语是否仍然被使用」本身就被内建为一种自动化的淘汰机制。模式二假设台账tags: [hypothesis]适用场景当长时间调试不断产生死胡同试了 X因为 Y 没成功而你或下一个智能体反复推导出同样的「负面知识」时使用。文档敏锐地指出了现有工具的能力边界向量搜索和CLAUDE.md擅长扫描什么有效它们不擅长回答什么已经试过并排除了。这正是假设台账的价值所在把「被否定过的路径」沉淀为可检索、可执行的负知识。模式结构约定每条假设一条 carnet打上hypothesis标签。正文承载实际推理过程Hypothesis / Tests / Verdict 三节meta.hypothesis.*承载结构化状态让其它工具或智能体无需重读正文即可判断。--- summary: iconv-lite v0.7 esm import path — types broken upstream agent: claude-code tags: [hypothesis] related: - https://github.com/pillarjs/iconv-lite/issues/363 meta: hypothesis: status: debunked last_tested: 2026-04-30 --- ## Hypothesis Switching to esm imports should let us run iconv-lite on Node 22 (v0.7 advertises ESM support). ## Tests 1. npm install iconv-lite0.7.1 → type error (Cannot find module declaration). 2. Set tsconfig.moduleResolution to bundler → same error. 3. Inspected v0.7.1 source → broken package.json#exports types. ## Verdict Pin to v0.6.3. The whole v0.7 series is broken upstream (Issue #363). Wait for v0.8 before retrying.状态机pending / confirmed / debunkedmeta.hypothesis.status只允许三个取值构成一个简洁的状态机状态含义何时设置pending正在积极测试中假设提出、尚未验证confirmed假设成立测试通过结论有效debunked已被排除测试证伪记录负面结论Agent 操作流程探索新理论前先扫描同区域的历史假设agent-carnet find symptom --in all agent-carnet find library --in tags如果存在已被 debunked 的假设正文里已有结论——直接跳过不要重蹈覆辙。排除某个可能性后保存 carnet并使用上述三个状态之一。Refresh-on-use 把陈旧性转化为信号一条 30 天内无人需要的 debunked 假设会掉入.trash/而那些持续被引用的条目恰恰就是项目里「承重墙级别」的不要重试清单。这个模式的价值在于负面知识的生命周期由使用频率自动管理——真正重要的死路会被反复引用而长存无关紧要的死路则自然消亡不会无限堆积。扩展机制如何添加新模式文档最后给出了一套通用的扩展方法论值得完整记录同样的形状适用于任何新约定。选一个标签名可选地在meta.你的标签.*下命名空间化结构化数据剩下的交给正文。CLI 不需要知道这个模式——无论 carnet 携带什么标签find和show的工作方式都一样。具体步骤选一个标签名如tags: [decision]、tags: [retro]为约定命名。可选在meta.你的标签.*下放置结构化数据供工具与其它智能体机器可读。正文用叙述形式承载人类可读的内容。把新模式记录在项目自己的 carnet 中——例如写一条vocab/条目其 canonical name 就是模式本身的名字。这样未来智能体可以用发现任何其它约定的同样方式发现这条新约定。这种「自举」式文档策略是整套体系的关键设计模式本身的发现机制不依赖任何特殊注册表而是复用 vocab 模式让新模式也变成一条可被find命中的普通 carnet。与 frontmatter 体系的配合Cookbook 中的meta:用法与同目录下的 references/frontmatter.md 构成了完整的扩展模型两者需对照阅读CLI 只重写它认识的字段summary、agent、created、updated、last_used、use_count、tags、related、lifespan、keep。在save --update时其它所有顶层 frontmatter 键都会被原样往返保留——包括meta:以及外部工具添加的任何自定义键。meta:是有意设计给 CLI 不解释、但下游消费者可以行动的结构化数据区Obsidian 插件、同级智能体、你自己的脚本、本 Cookbook 中的模式。命名空间约定meta.vocab.*、meta.hypothesis.*、meta.你的标签.*避免独立扩展之间的键冲突。值保持原始类型字符串、数字、字符串列表更复杂的内容应放正文供人类阅读。CLI 暂时没有--meta标志设置或修改meta:的方法是save后直接编辑 carnet 文件或由工具写文件下一次 CLI 写入save --update、touch、show会保留这些编辑。对前端字段而言frontmatter.md 还补充了关键的边界约束——顶层不要加status:schema 中没有它的位置应改用tags: [hypothesis:debunked]或meta.hypothesis.status不要为结构化数据新增顶层字段summary:必须保持单行。实战总结什么时候用哪个模式结合 SKILL.md 的「When to read references」指引可以给出如下决策矩阵场景使用模式核心动作多智能体对同一概念各说各话vocab词汇对齐find candidate --in tags查重 → 保存规范名 →related:关联代码调试反复撞上同一堵墙hypothesis假设台账find symptom --in all查史 → 排除后按三态保存 → 让 Refresh-on-use 自动淘汰需要自定义新约定通用扩展选标签名 → 可选meta.tag.*→ 自举记录到项目 carnet需要给笔记设非默认寿命直接使用 frontmatter编辑lifespan30d/1y/never或keep: true钉住两套模式共同印证了 Cookbook 的核心设计哲学给智能体协作建立约定不一定要改工具改动数据的形状就够了。tags:提供可检索的分类维度meta:提供可执行的机器语义正文保留人类可读的推理——三者分层各司其职且完全建立在现有 CLI 之上。【免费下载链接】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），仅供参考