Tolaria 的 agent-docs/all.md面向 AI Agent 的本地文档包如何生成、随包分发并被消费【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolariaall.md是 Tolaria 桌面应用内嵌的“AI Agent 文档包”中的全量文档文件它把 Tolaria 公共文档站的近五十篇 Markdown 按固定顺序拼接成一份单文件知识语料随安装包分发供 Claude Code、Codex 等 CLI 编码 Agent 在本地检索 Tolaria 的产品行为。读完本文你将掌握这套“站点 Markdown → 构建脚本 → Tauri 资源 → Agent 系统提示词”的完整链路并理解 Tolaria 本地优先local-first文档体系所承载的核心知识模型。一、all.md 是什么一份拼接而成的公共文档语料该文件位于 all.md本身不是手工维护的文档而是由构建脚本从 site 目录Tolaria 的 VitePress 公共文档源生成的产物。它的存在目的写在生成脚本的索引文件描述里“all public docs concatenated for fast full-context reads”——把全部公共文档拼成一个文件让 Agent 可以一次性读入完整上下文。页面格式文件中每一篇源文档都被包装成统一的三段式结构用空行分隔的---水平线彼此隔开# 页面标题 Source: 仓库内相对路径如 start/first-launch.md URL: 文档站路由如 /start/first-launch 剥离 frontmatter 后的正文这个格式由生成脚本的formatDoc函数产生见 build-agent-docs.mjs标题取正文第一个#一级标题路径记录的是site/下的相对位置URL 则把路径中的index.md和.md后缀去掉后转成站点路由。Agent 拿到这份语料后既可以用标题快速定位主题也能通过Source行回溯到仓库中的原始文档文件。需要注意的一个细节脚本只剥离 YAML frontmatter 和::: v-pre容器标记并不处理 VitePress 组件。因此文件开头对应首页的 Index 一节里仍保留着LaringHome /之类的组件占位——这从侧面说明all.md是“原样拼接 轻度清洗”而非重新排版。章节顺序与知识地图当前检出的all.md共包含首页 Index 一节加 47 篇文档按构建脚本声明的sectionOrder组织为六大区build-agent-docs.mjs 中start → concepts → guides → templates → reference → troubleshooting的固定顺序区内按文件名字典序排序。各节承载的核心内容如下start上手四篇First Launch首次启动让用户三选一克隆 Getting Started 示例库 / 打开已有本地库 / 新建空库示例库克隆后会主动断开远端保证可随意编辑应用级设置窗口大小、缩放、最近库列表存在本机笔记、类型定义、保存视图全部留在用户选择的库文件夹。Getting Started Vault公共示例库展示 frontmatter、类型Note/Project/Person/Topic、wikilink、关系字段、富文本块、可折叠区、公式与跨笔记引用的表格、vault 表达式驱动的 HTML 仪表盘、独立 HTML 报告以及本地 Git 仓库等约定并说明AGENTS.md是库内 AI 指引的权威文件、CLAUDE.md仅作兼容垫片。InstallmacOS 为主力平台Apple Silicon 与 Intel 均有产物提供 Homebrew caskWindows 与 Linux 为“受支持、早期”阶段Linux 行为依赖发行版的 WebKitGTK 与输入法集成。Open or Create a Vault库就是一个磁盘文件夹可打开 Obsidian 风格库、纯 Markdown 文件夹或 Git 仓库多库可同时注册并通过Use multiple vaults at the same time进入统一图谱Git 是推荐而非必需。concepts十一个核心概念Vaults文件系统是唯一事实源应用状态与缓存都由文件派生文档用一张表划清了“随库走”的状态类型图标与颜色、保存视图、置顶属性、关系约定、库内 AI 指引文件与“随应用走”的状态编辑器缩放、窗口大小、最近库列表、本地缓存、AI 目标选择。Notes笔记 Markdown 文件 可选 YAML frontmatter第一个 H1 是主标题标题与文件名解耦。Typestype:字段决定笔记类型类型不从文件夹位置推断类型文档type: Type控制侧边栏分组、图标、颜色、顺序、置顶属性与新笔记模板。Relationships任何包含 wikilink 的 frontmatter 字段都会动态成为关系字段默认支持belongs_to、has、related_to且默认关系有自动计算的逆关系。Propertiestype/status/url/date等建议属性之外下划线前缀的字段_icon、_color、_order、_sidebar_label、_width、_pinned_properties、_list_properties_display等是系统属性保持纯文本但隐藏于常规属性编辑。Spreadsheets_display: sheet的笔记以 CSV 风格正文 _sheetYAML 元数据存储公式由 IronCalc 求值并扩展了[[note]].A1、[[note]].property、[[note]].2三类 vault 感知引用。AI两条路径——带工具的 CLI 编码 AgentVault Safe / Power User 两种权限模式与纯聊天的直接模型目标本地 Ollama/LM Studio 或托管 API外部工具通过 MCP 服务器读写库。GitTolaria 作为轻量 Git 客户端提供整库与单笔记的历史、diff、提交、拉取、推送、冲突处理库可以是父仓库中的子文件夹此时提交边界仍锁定在库文件内。Editor富文本编辑器块、斜杠菜单、可折叠标题、callout、Mermaid、LaTeX 数学、沙盒 HTML 块、tldraw 白板与 raw Markdown 模式写回同一个文件。Files and Media粘贴的图片落入attachments/网页粘贴会后台导入公网图片HTML/PDF/媒体在应用内预览。Inbox捕获与整理分离的可选工作流。guides十六篇操作指南创建/打开库、Capture a Note、组织 Inbox、Create Types、Build Custom Views支持all/any嵌套条件与自然语言相对日期、Manage Git Manually or with AutoGit空闲后自动提交推送的检查点、Configure AI ModelsAPI key 可存本机、读环境变量或不使用、Connect a Git Remote依赖系统 Git 认证推荐 SSH/gh CLI/凭据助手、Use the AI、Use the Command PaletteCmdK/CtrlK、Use HTML Blocksheight、scriptssandboxed、json(...)、Use Media Previews、Use the Rich EditorEsc选中块、CmdEnter折叠标题、highlight、Use Spreadsheets、Use the Table of Contents、Use Wikilinks。templatesPortent 一篇Portent 是面向工作/个人知识库的开放规范模板定义 PORTProject/Operation/Responsibility/Task可操作型与 ENTPEvent/Note/Topic/Person知识记录型八类默认类型、belongs_to/related_to两个默认关系以及“捕获 → 组织 → 归档”的生命周期生成脚本明确要求 Agent 在用户询问“如何改进知识库”时把它当作 Tolaria 的默认最佳实践模型。reference十一篇参考手册File Layout根目录扁平放置笔记views/存保存视图、attachments/存附件、Frontmatter Fields完整字段语义表、Keyboard Shortcuts全局与富编辑器两套快捷键表如Cmd\切换 raw 模式、CmdShiftI切换属性面板、Release ChannelsStable 手动晋级、Alpha 跟随 main 分支推送更新元数据分别位于/stable/latest.json与/alpha/latest.json、Spreadsheet File FormatCSV 正文规则、_sheet元数据全部字段、数字格式码、Markdown 样式导入规则、Spreadsheet Formulas基础语法表、195 个函数的自动补全目录、跨表引用语义、Supported Platforms、Vault Expressions{{...}}表达式、格式化助手、json(...)结构化输出、View Filters、Contribute与Docs Maintenance。troubleshooting五篇AI Agent 未安装桌面应用PATH与交互式 shell 不同、Git 认证失败、模型供应商连接失败、同步冲突处理流程、库无法加载检查文件夹权限、git status、执行Reload Vault。二、生成管线scripts/build-agent-docs.mjs整份语料由 build-agent-docs.mjs 一次性重建。触发入口有两处见 package.jsonagent-docs: node scripts/build-agent-docs.mjs, docs:build: pnpm agent-docs vitepress build site以及 tauri.conf.json 中的桌面构建前置命令pnpm build pnpm bundle-mcp pnpm agent-docs——即每次打桌面包之前文档包都会从最新站点源码重新生成保证安装包内的 Agent 语料与发布版文档严格同步。关键处理步骤脚本的main函数build-agent-docs.mjs按以下顺序工作遍历收集listMarkdownFiles递归扫描site/跳过.vitepress、public、node_modules、.DS_Store只取.md文件并统一为 POSIX 风格路径。清洗正文stripFrontmatter移除开头的 YAML 块stripVPreContainers逐行剥离 VitePress 的::: v-pre起止标记避免文档站渲染指令混入 Agent 语料。提取标题firstHeading取正文第一个#标题取不到时回退为文件名 slug 的首字母大写形式titleFromSlug。排序sortDocs先按sectionOrder的节内优先级再按文件名字典序这正是all.md中“start 在前、troubleshooting 在后”的来源。路由推导docUrl将路径换算成文档站路由例如reference/spreadsheet-format.md→/reference/spreadsheet-format。拼接输出所有文档经formatDoc包装后以\n\n---\n\n连接写入all.md同一份文档还会被拆写为pages/原路径的逐页文件与按节聚合的section.md束文件。同批生成的配套产物all.md并非孤本。脚本还会生成ARCHITECTURE.md 对此有完整描述AGENTS.md面向 Agent 的使用指引明确“先读活动库的AGENTS.md了解库内约定再读本目录index.md获取文档地图最后用 ripgrep 检索具体主题”并规定“库级约定以库的AGENTS.md为准Tolaria 产品行为以本包为准”。index.md带目录链接的文档地图同样内置了 Portent 最佳实践的提示。search-index.json每篇文档的title、path、url、section与全部二/三级标题元数据供快速路由。pages/与section.md逐页与分节两种粒度的切片服务于“按主题精读”而非全量加载的检索方式。all.md在这套产物中的定位因此很清晰它是全量单文件语料适合 Agent 一次读入index.mdpages/则适合“先定位、后精读”的低成本路径。三、分发与运行期解析从资源打包到系统提示词Tauri 资源打包tauri.conf.json 声明了资源映射resources/agent-docs/**/*: agent-docs/构建时整个目录被放进应用包运行期以agent-docs/前缀存在于安装资源的根下。路径解析安装产物优先仓库回退Rust 侧的get_agent_docs_path命令ai.rs维护两个候选路径依次探测哪个目录下存在index.mdTauriBaseDirectory::Resource解析出的安装资源目录桌面构建的正式路径CARGO_MANIFEST_DIR/resources/agent-docs——即仓库内目录作为开发模式的回退。若两者都不含index.md返回“Tolaria agent docs are not bundled in this build.”错误。移动端构建走#[cfg(mobile)]分支直接返回“Bundled agent docs are only available in the desktop app.”——该文档包是桌面端专属能力这与 CLI Agent 仅在桌面端可用ai.rs 中移动端stream_ai_agent返回错误保持一致。前端通过 agentDocsPath.ts 调用该命令并做模块级缓存首次成功解析后不再重复走 IPC失败则缓存为空值后续 Agent 运行时拿到的路径要么是有效目录、要么干脆不提供文档指引。四、消费端系统提示词如何指挥 Agent 使用这份语料真正把all.md变成“Agent 能用的知识”的是 ai-agent.ts 中的buildAgentSystemPrompt。其中agentDocsInstructionsai-agent.ts注入的指引要点包括优先级做库特定假设前先读活动库的AGENTS.md涉及 Tolaria 产品行为、工作流或用户问“Tolaria 怎么用”时去检索内嵌文档目录并明确“Prefer bundled docs over guesses for Tolaria behavior”优先信文档而不是靠猜。检索方式随权限模式变化Power User 模式下非 Pi 代理提示词写的是 “Start withpath/index.md, then useripgrepover that folder”Vault Safe 模式没有 shell则改为“使用可用的文件与搜索工具”。这解释了为什么文档包要同时提供index.md目录、search-index.json元数据与all.md全量三种粒度的检索载体。Portent 定向当用户询问如何改进知识库结构、类型划分、关系建模时提示词明确要求读取path/pages/templates/portent.md并结合 types/relationships/properties/Inbox/archive/custom views 概念——与 all.md 中 templates 一节的内容精确对应。权限边界系统提示同时声明 Vault Safe 模式禁用 shell/git/脚本执行只允许文件、搜索、编辑与 MCP 工具多库激活时则逐条列出各库根路径并要求 MCP 调用显式传库路径。配合docs/ABSTRACTIONS.md的描述可以推断出完整消费链getAgentDocsPath()在每次 Agent 运行前缓存路径 →buildAgentSystemPrompt把路径拼进系统提示 → CLI Agent 在自己进程中用 ripgrep 或文件工具按需读取index.md、pages/或整份all.md。五、边界、限制与适用前提生成时机all.md只在构建链beforeBuildCommand或手动pnpm agent-docs时重建它是发布时刻的文档快照若只改了site/文档而未重新构建安装包内的语料不会更新。平台边界仅桌面构建内嵌该目录移动端 stub 直接报错ai.rs且移动端同样不支持 CLI Agent 流。开发回退仓库回退路径依赖CARGO_MANIFEST_DIR只在index.md存在时生效all.md缺失但index.md存在的目录会被选中因此“最小可用形态”是index.mdpages/all.md属于锦上添花的全量语料。知识权威性分层生成脚本写入AGENTS.md的规则是“库级AGENTS.md管库内约定本包管 Tolaria 产品行为”all.md里的内容应视为 Tolaria 官方产品行为事实源而不是用户库的私有约定。站点结构假设脚本按“一级目录即文档节”的约定分节sectionForFile取路径首段并预留了download、releases两个节位当前site/中不存在对应目录故all.md实际只含六个文档节。小结src-tauri/resources/agent-docs/all.md的价值在于把 Tolaria 的整套用户文档——从本地优先的库模型、frontmatter 类型与关系约定到表格存储、vault 表达式、快捷键与故障排查——压进一个可被 CLI Agent 一次性读入或按主题精检的纯文本文件并通过构建脚本、Tauri 资源映射与系统提示词三层机制使“文档随包走、知识随 Agent 走”成为确定行为。对扩展者而言这条site/ → build-agent-docs.mjs → 安装包资源 → buildAgentSystemPrompt的管线是一个“让桌面应用内嵌 AI 语料且保证版本一致”的可复用范式。【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考