Agent Carnet 实战指南用 Markdown 笔记本为 Repomix 项目中的 AI 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导读本指南基于 Repomix 仓库内引入的agent-carnet技能.agents/skills/agent-carnet/SKILL.md系统讲解如何在磁盘上维护一个以 Markdown 文件为核心的共享笔记本Agent 跨会话沉淀研究结论、踩坑记录、架构决策与进行中的工作并通过30 天默认寿命 使用即续期的自动回收机制让真正有用的笔记自然存活、过时信息自动进入回收站。读完本指南你将掌握save / find / list / show / used / move / rm的完整命令用法、frontmatter 扩展机制lifespan、keep、meta:以及vocab、hypothesis两类可复用的笔记模式。一、agent-carnet 是什么agent-carnet是一个极简的命令行工具为 AI Agent 提供磁盘上的共享 Markdown 笔记本所有笔记以.carnet/category/slug.md的形式存放在项目目录内天然可被git跟踪、可被任意文本工具检索不依赖任何专有数据库。其核心设计理念是**安全地遗忘safe to forget**每条笔记拥有30 天默认寿命lifespan每次被读取或应用都会重置寿命长期无人使用的笔记会自动漂移到.carnet/.trash/回收站保留 7 天后才被彻底删除因此真正有用的笔记会在反复被引用的过程中持续续命而过期的临时结论则无需人工清理即可自行沉底。在 Repomix 仓库中该技能通过 skills-lock.json 以锁定版本的形式引入来源记录为yamadashy/agent-carnetskillPath 为skills/agent-carnet/SKILL.md并带computedHash内容哈希意味着它随仓库分发给所有协作 Agent保证团队内共享同一套笔记本约定。二、快速参考核心命令一览SKILL.md 给出的日常命令组合如下注意save必须携带--summary与--agent# 保存始终传入 --summary 和 --agent claude-code echo body content | agent-carnet save deps/iconv-issue \ --summary iconv-esm v0.7 types broken — pin to v0.6 \ --agent claude-code \ --tags compat,esm # 召回 agent-carnet find iconv # 搜索摘要不会刷新寿命 agent-carnet list # 按类别分组的总览按 last_used 排序 agent-carnet list --sort use_count # 先展示被实际应用最多的笔记 agent-carnet show deps/iconv-issue # 读取完整内容刷新 last_used弱使用信号 # 标记为已实际应用强使用信号——同时刷新 last_used 并递增 use_count agent-carnet used deps/iconv-issue # 维护 agent-carnet move from to agent-carnet rm path --yes各子命令参数含义子命令作用对寿命/计数的影响save path写入一条笔记内容来自 stdin创建时设置created刷新last_usedsave --update更新已有笔记内容刷新updated仅内容修改find query搜索笔记摘要无任何影响list [category]分类浏览默认按last_used排序无影响show path读取完整笔记正文刷新last_used弱信号used path声明该笔记已被实际应用刷新last_used并递增use_countmove from to移动/重命名笔记无影响rm path --yes删除笔记进入.trash/无影响帮助系统当不确定某个子命令的完整参数集时运行agent-carnet command -h例如agent-carnet save -h、agent-carnet used -h。每个子命令都会打印自己的聚焦帮助——必需参数、可选参数和示例——且不会触发任何文件系统操作可以放心探索。三、使用时机保存、召回与used3.1 何时保存当你在跨会话工作中发现值得沉淀的内容时应当主动保存研究结论——付出了推导成本才得到的发现代码库中不显而易见的模式 / 坑点棘手问题的解决方案架构决策及其背后的推理可能稍后恢复的进行中工作。典型场景调试某个依赖时发现iconv-esm的类型声明损坏将结论pin to v0.6连同证据一起存入deps/iconv-issue下次再遇到同类报错时直接find iconv即可命中。3.2 何时召回在开始相关工作之前或当上下文可能已存在时agent-carnet find topic——快速扫一遍摘要判断是否值得深入agent-carnet list category——浏览某个分类文件夹agent-carnet show path——真正读取正文会重置last_used仅在内容确实重要时使用。注意find与show的定位差异find只扫摘要、不消耗寿命show会续期因此适合确认要读的场景。3.3 何时调用usedused应当在你确认一条笔记真正塑造了你的工作之后调用典型情形包括你应用了笔记中记录的修复且它解决了问题你在重试某个假设前查阅了笔记从而跳过了一条死胡同你在新代码中使用了vocab笔记里的规范命名而不是另造一个名字。used递增use_count——这是一个跨会话存续的持久重要性信号让未来的读者以及agent-carnet list --sort use_count能优先浮出承重性笔记。关键原则阅读不算数。show只是保持笔记存活弱信号used才记录这条笔记因真实理由值得保留强信号。四、硬性规则SKILL.md 明确了以下不可违背的约定--summary是必需的且要写得果断——读者或下一个 Agent仅凭摘要就能决定是否继续深入阅读--agent claude-code是必需的信号差异find不刷新任何字段show刷新last_usedused同时刷新last_used并递增use_countupdated只跟踪内容修改save、save --update与last_used相互独立不是寿命驱动字段30 天过期是自动的——不要手动清理keep: true用于固定永久笔记自动回收每次 CLI 调用都会触发自动清理被删除的笔记在.carnet/.trash/中保留7 天后才被硬删除。五、路径约定笔记路径为category/slug使用 kebab-case小写连字符无前导斜杠不允许..分类即文件夹按需自由新建允许子分类例如deps/esm/iconv-issue完全合法。这一约定使笔记本天然形成可浏览的目录树list category与find的检索范围也因此清晰可控。六、frontmatter 模式CLI 管理的字段与扩展命名空间每条笔记都以 YAML frontmatter 开头。CLI 只管理少量字段其余字段在往返读写中保持不变因此工具和约定可以在其上自由叠加元数据。完整模式见 .agents/skills/agent-carnet/references/frontmatter.md。6.1 Schema 总览--- # CLI 管理保存时提供使用字段由 show / used 更新 summary: one-line decisive description # 必需 agent: claude-code # 必需例如 claude-code, codex, cursor, human created: 2026-05-10 # 首次保存时写入此后不可变 updated: 2026-05-10 # save / save --update 时刷新内容修改 last_used: 2026-05-10 # save / show / used 时刷新驱动过期 use_count: 7 # 仅 used 时递增重要性信号 # 可选CLI 认识 tags: [compat, esm] # 自由标签save 时以逗号分隔传入 related: # 指向的路径或其他 carnet 路径 - src/core/file/encoding.ts - .carnet/deps/iconv-issue.md lifespan: 90d # 覆盖默认 30d接受 30d / 90d / 1y / never keep: true # 固定笔记阻止自动清理忽略 lifespan # 可选CLI 不解释 meta: # 自由扩展命名空间见下文 extension: key: value ---6.2 四个 CLI 管理的日期 / 计数器agent-carnet刻意区分修改与使用使两者可以被独立观察与排序字段由谁刷新含义createdsave仅首次出生日期永不改变updatedsave、save --update最近一次内容修改last_usedsave、show、used最近一次交互驱动过期expiry last_used lifespanuse_count仅used笔记被显式应用的次数参考性重要性信号如前所述show是弱使用信号——把正文拉入上下文已经算作一次使用足以续命但不足以递增use_countused才是强信号。6.3 CLI 管理字段 vs 被保留字段CLI 只会重写它认识的字段summary、agent、created、updated、last_used、use_count、tags、related、lifespan、keep。执行save --update时其余所有顶层 frontmatter 键都会原样往返——包括meta:以及任何外部工具添加的自定义键。这正是扩展模型的基础只要不占用 CLI 管理的名字你的字段就能在每次 CLI 写入后存活。6.4meta:扩展命名空间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-306.5lifespan通过parse-duration解析时长字符串30d、7d、12h——相对时长1y、6mo、2w——更长的单位never——固定笔记等价于keep: true。若keep: true与lifespan: duration同时存在keep: true优先——无论时长如何笔记都不会被自动清理。何时设置lifespan当某类笔记天然需要长于或短于默认 30 天的寿命时例如稳定的架构决策用1y冲刺范围的临时笔记用7d。6.6keepkeep: true将笔记无限期固定不受自动清理影响。要谨慎使用——它会破坏安全地遗忘模型。典型用途不应衰减的项目级参考文档需要长期保留上下文的长期设计决策个人风格或人设persona文件。keep: false与省略keep:等价默认行为。6.7relatedrelated:接受字符串列表无强制格式常见约定项目根相对的文件路径如src/core/file/encoding.ts其他 carnet 路径如.carnet/category/slug.mdURL如问题追踪系统的 issue 链接。CLI 不会校验目标是否存在也不会跟随这些链接——它们是文档性质的引用而非 CLI 会遍历的链接。6.8 不要添加什么顶层status:字段schema 中没有它的位置。若需要调试状态请用tags: [hypothesis:debunked]或meta.hypothesis.status约定为结构化数据新增顶层字段请改用meta.extension.*以便与一切其他扩展组合多行summary:保持单行——列表与搜索 UI 都假定它是单行的。6.9 frontmatter 解析错误若一条 carnet 的 frontmatter 解析失败YAML 非法、分隔符不匹配CLI 会以frontmatter_error退出并指出出错文件。修复方式是直接编辑文件CLI 不会尝试自动修复。七、Cookbook 模式基于标签的可复用约定.agents/skills/agent-carnet/references/cookbook.md 收录了基于标签的组合式约定——无需新命令、无需特殊文件夹全部复用现有 CLI。每种模式通过tags:和可选meta:为 carnet 附加结构供下游工具或未来 Agent 识别。7.1 词汇对齐vocab适用场景多个 Agent或人类 Agent在项目中对同一概念反复发明不同名字——例如staging adapterproxy layerforward middleware都指向同一个模块。模式每个术语一条 carnet打vocab标签。meta.vocab.*子树携带机器可操作的数据规范名 canonical、别名 aliases供其他 Agent 或工具读取正文以叙述形式解释为什么。--- 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.Agent 流程为新概念命名前先扫描是否已有规范名agent-carnet find candidate --in tags agent-carnet find candidate --in body若已存在vocabcarnet采纳该名字在代码、PR 描述、后续 carnet 中使用若某个名字胜出成为规范名按上述约定保存一次并通过related:从相关代码或其他 carnet 引用它其余交给使用即续期机制不断被引用的同义词持续存活无人调用的同义词自动漂移到.trash/。7.2 假设账本hypothesis适用场景长时间的调试会话不断产生死胡同试过 X因 Y 无效而你或下一个 Agent总在重新推导同样的负向知识。向量搜索和CLAUDE.md擅长检索什么有效却不擅长检索什么已经试过且被排除。模式每个假设一条 carnet打hypothesis标签。正文承载实际推理Hypothesis / Tests / Verdictmeta.hypothesis.*携带结构化状态让其他工具或 Agent 无需重读正文即可行动--- summary: iconv-lite v0.7 esm import path — types broken upstream agent: claude-code tags: [hypothesis] related: - issue-url 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. Wait for v0.8 before retrying.Agent 流程探索新理论前先扫描同一区域的历史假设agent-carnet find symptom --in all agent-carnet find library --in tags若存在已被证伪的假设正文里已有结论直接跳过排除某个方向后保存 carnetmeta.hypothesis.status使用以下状态之一pending——正在积极测试confirmed——经受住了检验debunked——已被排除使用即续期把陈旧转化为信号30 天内无人需要的证伪假设沉入.trash/而持续被引用的那些正是承重的不要重试条目。7.3 添加新模式任意新约定都适用同样的形态选一个标签名可选地在meta.your-tag.*下命名空间化结构化数据正文负责其余。CLI 不需要认识该模式——无论 carnet 带什么标签find与show的工作方式完全相同。在本地发明新模式时把它记录在项目自己的 carnet 中例如一个 canonical 名为该模式本身的vocab/条目未来的 Agent 就能像发现任何其他约定一样发现它。八、在 Repomix 仓库中的落位Skill 锁定与打包agent-carnet之所以能稳定地随本仓库分发依赖 Repomix 的 Skill 治理机制skills-lock.json 以 lockfile 形式锁定了每个引入的 Skill记录来源yamadashy/agent-carnet、skillPath为skills/agent-carnet/SKILL.md以及computedHash内容哈希eb9b255f...。任何来源内容的变更都会导致哈希不匹配从而在集成阶段被发现本仓库的 src/core/skill/packSkill.ts 实现了 Skill 打包逻辑生成 SKILL.md 内容时对应第 146 行Generates SKILL.md content from references result and token count会附带精确的 token 计数并对SKILL.md与 references 文件做整体产出第 187 行Generates skill output (SKILL.md and reference files)。从源码结构可以推断SKILL.md 与 references/ 文件是打包输出的核心单元——这也解释了为什么agent-carnet的 SKILL.md 刻意保持精炼日常够用而把vocab/hypothesis模式与 frontmatter 细节放在 references/ 中按需加载避免常驻上下文浪费 token。九、使用建议与注意事项不要按需常驻加载 references/SKILL.md 本身已覆盖日常的 save/find/show/used/move/rm 流程。仅在明确需要 tag 模式vocab、hypothesis时读取 cookbook.md在需要写meta:、设置非平凡lifespan/keep或确认陌生 frontmatter 字段是否会被保留时读取 frontmatter.md不要投机式加载依赖真实的使用信号use_count的价值建立在诚实调用used之上——只有笔记确实改变了你的工作结果时才调用尊重回收机制不要手动清理过期笔记也不要轻易给笔记加keep: true回收机制本身就是信息价值的筛选器路径安全坚持category/slug的 kebab-case、无前导斜杠、无..约定保证笔记本目录树可预测、可浏览。关联文件索引技能主文档 SKILL.md · 模式手册 cookbook.md · frontmatter 参考 frontmatter.md · Skill 锁定 skills-lock.json · Skill 打包实现 packSkill.ts【免费下载链接】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），仅供参考
Agent Carnet 实战指南：用 Markdown 笔记本为 Repomix 项目中的 AI Agent 构建跨会话记忆
Agent Carnet 实战指南用 Markdown 笔记本为 Repomix 项目中的 AI 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导读本指南基于 Repomix 仓库内引入的agent-carnet技能.agents/skills/agent-carnet/SKILL.md系统讲解如何在磁盘上维护一个以 Markdown 文件为核心的共享笔记本Agent 跨会话沉淀研究结论、踩坑记录、架构决策与进行中的工作并通过30 天默认寿命 使用即续期的自动回收机制让真正有用的笔记自然存活、过时信息自动进入回收站。读完本指南你将掌握save / find / list / show / used / move / rm的完整命令用法、frontmatter 扩展机制lifespan、keep、meta:以及vocab、hypothesis两类可复用的笔记模式。一、agent-carnet 是什么agent-carnet是一个极简的命令行工具为 AI Agent 提供磁盘上的共享 Markdown 笔记本所有笔记以.carnet/category/slug.md的形式存放在项目目录内天然可被git跟踪、可被任意文本工具检索不依赖任何专有数据库。其核心设计理念是**安全地遗忘safe to forget**每条笔记拥有30 天默认寿命lifespan每次被读取或应用都会重置寿命长期无人使用的笔记会自动漂移到.carnet/.trash/回收站保留 7 天后才被彻底删除因此真正有用的笔记会在反复被引用的过程中持续续命而过期的临时结论则无需人工清理即可自行沉底。在 Repomix 仓库中该技能通过 skills-lock.json 以锁定版本的形式引入来源记录为yamadashy/agent-carnetskillPath 为skills/agent-carnet/SKILL.md并带computedHash内容哈希意味着它随仓库分发给所有协作 Agent保证团队内共享同一套笔记本约定。二、快速参考核心命令一览SKILL.md 给出的日常命令组合如下注意save必须携带--summary与--agent# 保存始终传入 --summary 和 --agent claude-code echo body content | agent-carnet save deps/iconv-issue \ --summary iconv-esm v0.7 types broken — pin to v0.6 \ --agent claude-code \ --tags compat,esm # 召回 agent-carnet find iconv # 搜索摘要不会刷新寿命 agent-carnet list # 按类别分组的总览按 last_used 排序 agent-carnet list --sort use_count # 先展示被实际应用最多的笔记 agent-carnet show deps/iconv-issue # 读取完整内容刷新 last_used弱使用信号 # 标记为已实际应用强使用信号——同时刷新 last_used 并递增 use_count agent-carnet used deps/iconv-issue # 维护 agent-carnet move from to agent-carnet rm path --yes各子命令参数含义子命令作用对寿命/计数的影响save path写入一条笔记内容来自 stdin创建时设置created刷新last_usedsave --update更新已有笔记内容刷新updated仅内容修改find query搜索笔记摘要无任何影响list [category]分类浏览默认按last_used排序无影响show path读取完整笔记正文刷新last_used弱信号used path声明该笔记已被实际应用刷新last_used并递增use_countmove from to移动/重命名笔记无影响rm path --yes删除笔记进入.trash/无影响帮助系统当不确定某个子命令的完整参数集时运行agent-carnet command -h例如agent-carnet save -h、agent-carnet used -h。每个子命令都会打印自己的聚焦帮助——必需参数、可选参数和示例——且不会触发任何文件系统操作可以放心探索。三、使用时机保存、召回与used3.1 何时保存当你在跨会话工作中发现值得沉淀的内容时应当主动保存研究结论——付出了推导成本才得到的发现代码库中不显而易见的模式 / 坑点棘手问题的解决方案架构决策及其背后的推理可能稍后恢复的进行中工作。典型场景调试某个依赖时发现iconv-esm的类型声明损坏将结论pin to v0.6连同证据一起存入deps/iconv-issue下次再遇到同类报错时直接find iconv即可命中。3.2 何时召回在开始相关工作之前或当上下文可能已存在时agent-carnet find topic——快速扫一遍摘要判断是否值得深入agent-carnet list category——浏览某个分类文件夹agent-carnet show path——真正读取正文会重置last_used仅在内容确实重要时使用。注意find与show的定位差异find只扫摘要、不消耗寿命show会续期因此适合确认要读的场景。3.3 何时调用usedused应当在你确认一条笔记真正塑造了你的工作之后调用典型情形包括你应用了笔记中记录的修复且它解决了问题你在重试某个假设前查阅了笔记从而跳过了一条死胡同你在新代码中使用了vocab笔记里的规范命名而不是另造一个名字。used递增use_count——这是一个跨会话存续的持久重要性信号让未来的读者以及agent-carnet list --sort use_count能优先浮出承重性笔记。关键原则阅读不算数。show只是保持笔记存活弱信号used才记录这条笔记因真实理由值得保留强信号。四、硬性规则SKILL.md 明确了以下不可违背的约定--summary是必需的且要写得果断——读者或下一个 Agent仅凭摘要就能决定是否继续深入阅读--agent claude-code是必需的信号差异find不刷新任何字段show刷新last_usedused同时刷新last_used并递增use_countupdated只跟踪内容修改save、save --update与last_used相互独立不是寿命驱动字段30 天过期是自动的——不要手动清理keep: true用于固定永久笔记自动回收每次 CLI 调用都会触发自动清理被删除的笔记在.carnet/.trash/中保留7 天后才被硬删除。五、路径约定笔记路径为category/slug使用 kebab-case小写连字符无前导斜杠不允许..分类即文件夹按需自由新建允许子分类例如deps/esm/iconv-issue完全合法。这一约定使笔记本天然形成可浏览的目录树list category与find的检索范围也因此清晰可控。六、frontmatter 模式CLI 管理的字段与扩展命名空间每条笔记都以 YAML frontmatter 开头。CLI 只管理少量字段其余字段在往返读写中保持不变因此工具和约定可以在其上自由叠加元数据。完整模式见 .agents/skills/agent-carnet/references/frontmatter.md。6.1 Schema 总览--- # CLI 管理保存时提供使用字段由 show / used 更新 summary: one-line decisive description # 必需 agent: claude-code # 必需例如 claude-code, codex, cursor, human created: 2026-05-10 # 首次保存时写入此后不可变 updated: 2026-05-10 # save / save --update 时刷新内容修改 last_used: 2026-05-10 # save / show / used 时刷新驱动过期 use_count: 7 # 仅 used 时递增重要性信号 # 可选CLI 认识 tags: [compat, esm] # 自由标签save 时以逗号分隔传入 related: # 指向的路径或其他 carnet 路径 - src/core/file/encoding.ts - .carnet/deps/iconv-issue.md lifespan: 90d # 覆盖默认 30d接受 30d / 90d / 1y / never keep: true # 固定笔记阻止自动清理忽略 lifespan # 可选CLI 不解释 meta: # 自由扩展命名空间见下文 extension: key: value ---6.2 四个 CLI 管理的日期 / 计数器agent-carnet刻意区分修改与使用使两者可以被独立观察与排序字段由谁刷新含义createdsave仅首次出生日期永不改变updatedsave、save --update最近一次内容修改last_usedsave、show、used最近一次交互驱动过期expiry last_used lifespanuse_count仅used笔记被显式应用的次数参考性重要性信号如前所述show是弱使用信号——把正文拉入上下文已经算作一次使用足以续命但不足以递增use_countused才是强信号。6.3 CLI 管理字段 vs 被保留字段CLI 只会重写它认识的字段summary、agent、created、updated、last_used、use_count、tags、related、lifespan、keep。执行save --update时其余所有顶层 frontmatter 键都会原样往返——包括meta:以及任何外部工具添加的自定义键。这正是扩展模型的基础只要不占用 CLI 管理的名字你的字段就能在每次 CLI 写入后存活。6.4meta:扩展命名空间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-306.5lifespan通过parse-duration解析时长字符串30d、7d、12h——相对时长1y、6mo、2w——更长的单位never——固定笔记等价于keep: true。若keep: true与lifespan: duration同时存在keep: true优先——无论时长如何笔记都不会被自动清理。何时设置lifespan当某类笔记天然需要长于或短于默认 30 天的寿命时例如稳定的架构决策用1y冲刺范围的临时笔记用7d。6.6keepkeep: true将笔记无限期固定不受自动清理影响。要谨慎使用——它会破坏安全地遗忘模型。典型用途不应衰减的项目级参考文档需要长期保留上下文的长期设计决策个人风格或人设persona文件。keep: false与省略keep:等价默认行为。6.7relatedrelated:接受字符串列表无强制格式常见约定项目根相对的文件路径如src/core/file/encoding.ts其他 carnet 路径如.carnet/category/slug.mdURL如问题追踪系统的 issue 链接。CLI 不会校验目标是否存在也不会跟随这些链接——它们是文档性质的引用而非 CLI 会遍历的链接。6.8 不要添加什么顶层status:字段schema 中没有它的位置。若需要调试状态请用tags: [hypothesis:debunked]或meta.hypothesis.status约定为结构化数据新增顶层字段请改用meta.extension.*以便与一切其他扩展组合多行summary:保持单行——列表与搜索 UI 都假定它是单行的。6.9 frontmatter 解析错误若一条 carnet 的 frontmatter 解析失败YAML 非法、分隔符不匹配CLI 会以frontmatter_error退出并指出出错文件。修复方式是直接编辑文件CLI 不会尝试自动修复。七、Cookbook 模式基于标签的可复用约定.agents/skills/agent-carnet/references/cookbook.md 收录了基于标签的组合式约定——无需新命令、无需特殊文件夹全部复用现有 CLI。每种模式通过tags:和可选meta:为 carnet 附加结构供下游工具或未来 Agent 识别。7.1 词汇对齐vocab适用场景多个 Agent或人类 Agent在项目中对同一概念反复发明不同名字——例如staging adapterproxy layerforward middleware都指向同一个模块。模式每个术语一条 carnet打vocab标签。meta.vocab.*子树携带机器可操作的数据规范名 canonical、别名 aliases供其他 Agent 或工具读取正文以叙述形式解释为什么。--- 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.Agent 流程为新概念命名前先扫描是否已有规范名agent-carnet find candidate --in tags agent-carnet find candidate --in body若已存在vocabcarnet采纳该名字在代码、PR 描述、后续 carnet 中使用若某个名字胜出成为规范名按上述约定保存一次并通过related:从相关代码或其他 carnet 引用它其余交给使用即续期机制不断被引用的同义词持续存活无人调用的同义词自动漂移到.trash/。7.2 假设账本hypothesis适用场景长时间的调试会话不断产生死胡同试过 X因 Y 无效而你或下一个 Agent总在重新推导同样的负向知识。向量搜索和CLAUDE.md擅长检索什么有效却不擅长检索什么已经试过且被排除。模式每个假设一条 carnet打hypothesis标签。正文承载实际推理Hypothesis / Tests / Verdictmeta.hypothesis.*携带结构化状态让其他工具或 Agent 无需重读正文即可行动--- summary: iconv-lite v0.7 esm import path — types broken upstream agent: claude-code tags: [hypothesis] related: - issue-url 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. Wait for v0.8 before retrying.Agent 流程探索新理论前先扫描同一区域的历史假设agent-carnet find symptom --in all agent-carnet find library --in tags若存在已被证伪的假设正文里已有结论直接跳过排除某个方向后保存 carnetmeta.hypothesis.status使用以下状态之一pending——正在积极测试confirmed——经受住了检验debunked——已被排除使用即续期把陈旧转化为信号30 天内无人需要的证伪假设沉入.trash/而持续被引用的那些正是承重的不要重试条目。7.3 添加新模式任意新约定都适用同样的形态选一个标签名可选地在meta.your-tag.*下命名空间化结构化数据正文负责其余。CLI 不需要认识该模式——无论 carnet 带什么标签find与show的工作方式完全相同。在本地发明新模式时把它记录在项目自己的 carnet 中例如一个 canonical 名为该模式本身的vocab/条目未来的 Agent 就能像发现任何其他约定一样发现它。八、在 Repomix 仓库中的落位Skill 锁定与打包agent-carnet之所以能稳定地随本仓库分发依赖 Repomix 的 Skill 治理机制skills-lock.json 以 lockfile 形式锁定了每个引入的 Skill记录来源yamadashy/agent-carnet、skillPath为skills/agent-carnet/SKILL.md以及computedHash内容哈希eb9b255f...。任何来源内容的变更都会导致哈希不匹配从而在集成阶段被发现本仓库的 src/core/skill/packSkill.ts 实现了 Skill 打包逻辑生成 SKILL.md 内容时对应第 146 行Generates SKILL.md content from references result and token count会附带精确的 token 计数并对SKILL.md与 references 文件做整体产出第 187 行Generates skill output (SKILL.md and reference files)。从源码结构可以推断SKILL.md 与 references/ 文件是打包输出的核心单元——这也解释了为什么agent-carnet的 SKILL.md 刻意保持精炼日常够用而把vocab/hypothesis模式与 frontmatter 细节放在 references/ 中按需加载避免常驻上下文浪费 token。九、使用建议与注意事项不要按需常驻加载 references/SKILL.md 本身已覆盖日常的 save/find/show/used/move/rm 流程。仅在明确需要 tag 模式vocab、hypothesis时读取 cookbook.md在需要写meta:、设置非平凡lifespan/keep或确认陌生 frontmatter 字段是否会被保留时读取 frontmatter.md不要投机式加载依赖真实的使用信号use_count的价值建立在诚实调用used之上——只有笔记确实改变了你的工作结果时才调用尊重回收机制不要手动清理过期笔记也不要轻易给笔记加keep: true回收机制本身就是信息价值的筛选器路径安全坚持category/slug的 kebab-case、无前导斜杠、无..约定保证笔记本目录树可预测、可浏览。关联文件索引技能主文档 SKILL.md · 模式手册 cookbook.md · frontmatter 参考 frontmatter.md · Skill 锁定 skills-lock.json · Skill 打包实现 packSkill.ts【免费下载链接】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），仅供参考