claude-obsidian 的 ZCode 主机集成AGENTS.md 契约、用户级技能安装与 Vault 事务边界【免费下载链接】claude-obsidianSelf-organizing AI second brain for Obsidian Claude Code. Drop any source and Claude reads, links, and files it into one connected knowledge graph of plain Markdown you own. AI note-taking, personal knowledge management (PKM), and an open-source Notion alternative. Based on Karpathys LLM Wiki pattern.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-obsidianZCODE.md 是 claude-obsidian 仓库中面向 ZCode 这一 Agent 主机的接入说明文档它规定了 ZCode 如何复用仓库的中立契约AGENTS.md、如何通过一次性安装命令把全部 15 个 Agent Skills 发布到用户级目录~/.zcode/skills/以及 ZCode 会话在操作知识库vault时必须遵守的产品/数据边界与共享事务协议。读完本文你可以独立完成 ZCode 环境下的技能发现安装含 dry-run 预览与冲突处理、正确解析并选定用户 vault并按claude-obsidian.transaction.v1事务协议安全地执行共享变更。ZCODE.md 的文档定位一份“主机适配层”契约ZCODE.md 篇幅不长但它承担的是一个明确的角色主机适配层声明。claude-obsidian 同时支持多个 Agent 宿主仓库中还有 GEMINI.md 等结构相同的兄弟文档每个宿主文档都不重复定义产品行为而是做三件事声明中立契约的唯一来源Read AGENTS.md as the canonical host-neutral contract——所有跨宿主一致的行为规则只定义在 AGENTS.md 里指明可移植代码的落点技能在skills/name/SKILL.md可移植核心在claude_obsidian/标准库实现无第三方依赖给出该宿主特有的发现机制与安装命令。从仓库结构看这种分层是刻意设计的AGENTS.md 开头即声明 host hooks never define knowledge behavior宿主钩子从不定义知识行为即宿主适配文档ZCODE.md只解决宿主如何找到并调用的问题调用之后做什么完全由中立契约和可移植核心决定。ZCode 的原生发现机制AGENTS.md 与用户级技能目录ZCODE.md 指出 ZCode 有两条原生的发现路径因此不需要镜像规则文件no mirrored rules file is needed规则文件ZCode 原生地在 workspace 与 user 两个作用域读取AGENTS.md。这意味着同一份中立契约无需为 ZCode 复制一份zcode-rules.md之类的变体技能文件用户级技能在~/.zcode/skills/skill-name/SKILL.md被自动发现。仓库内置的 15 个技能wiki、save、wiki-ingest、wiki-query、wiki-lint等核心工作流以及autoresearch、canvas、wiki-retrieve等扩展全部位于 skills/ 目录下每个技能只使用可移植的 Agent Skills frontmatter 子集——恰好是name和description两个字段这与 AGENTS.md 中 Canonical skills 一节的约束一致。用户级而非项目级安装带来的直接收益是每个 ZCode 工作区都可以直接调用这些技能无需逐项目配置。这是 ZCODE.md 与 Cursor/Windsurf 等需要--workspace指向项目目录的主机在安装语义上的关键区别。安装技能到 ZCodesetup-multi-agent.sh 的两段式流程ZCODE.md 给出的安装命令是标准的先预览、后应用两段式bash scripts/setup-multi-agent.sh --host zcode bash scripts/setup-multi-agent.sh --host zcode --apply第一条命令只预览将要创建的符号链接第二条命令才真正落盘。结合 scripts/setup-multi-agent.sh 的源码这套流程的完整参数与安全语义如下参数与模式脚本支持的模式与目标主机为Usage: scripts/setup-multi-agent.sh [--check|--dry-run|--apply] [--host codex|opencode|gemini|zcode|cursor|windsurf|all] [--workspace PATH]--dry-run默认仅输出PLANNED host destination计划结尾提示 Dry run only. Repeat with --apply to create the planned links.不做任何写入--check与 dry-run 相同但以退出码 1 表示存在待安装项适合放进 CI 或 Agent 自检流程--apply实际执行创建符号链接输出CREATED--host zcodeZCode 是显式 opt-in 主机。不指定--host时脚本默认只安装 Codex、OpenCode、Gemini 三家见脚本第 50–52 行的默认主机展开逻辑--workspace PATH仅 Cursor/Windsurf 必需它们安装到workspace/.host/skills/ZCode 固定安装到$HOME/.zcode/skills脚本中destination_root$HOME/.zcode/skills见 setup-multi-agent.sh。安全语义绝不覆盖、冲突即失败脚本头注释即声明 Install portable skill links without overwriting existing host configuration。其inspect_link函数实现了严格的冲突判定setup-multi-agent.sh目标路径已是符号链接且指向本仓库对应技能目录 → 输出READY幂等成功目标路径是指向别处的符号链接或目标已存在为普通文件/目录 → 输出CONFLICT ...保留原文件整体退出码置为 2不存在任何目标 →dry-run下计划、apply下mkdir -p父目录后ln -s创建。这些行为不是口头约定而是有隔离式hermetic测试锁定的实现事实。tests/test_setup_multi_agent.py 通过重写HOME环境变量在临时目录中执行真实脚本test_zcode_host_installs_global_links--apply --host zcode后断言~/.zcode/skills/下恰好是 15 个符号链接、每个链接的resolve()都指回仓库skills/name/且默认主机如~/.agents/skills未被顺带安装重复执行时 15 个链接全部报告READY证明幂等test_zcode_host_conflict_is_preserved预先在~/.zcode/skills/wiki/放入用户自有文件后执行--apply断言退出码为 2、用户文件原样保留preserve内容未变同时其余 14 个技能仍正常安装——即单点冲突不会阻塞其余链接但会让本次运行以失败码收场。工作区主机为何多一层 symlink 防护对 Cursor/Windsurf 这类安装到工作区内的主机脚本还实现了父目录符号链接逃逸检查若workspace/.host或其父级是符号链接apply也会被拒绝parent is a symlink退出码 2见 test_workspace_parent_symlinks_cannot_redirect_apply。ZCode 安装目标在$HOME下不经过这层工作区禁闭逻辑但该机制说明了这个安装器的整体安全基调任何可能把写入重定向到预期路径之外的结构一律 fail-closed。产品源与用户 Vault 的边界先解析、后读取ZCODE.md 明确警告This repository is product source, not the default user vault。仓库是产品源代码不是默认的用户知识库。这条边界有三层落地vault 的形态按 AGENTS.md用户 vault 是包含.claude-obsidian.json、wiki/和.raw/的目录可变状态永远属于那里仓库根部的wiki/、.raw/、.vault-meta/是贡献者状态被排除在公开发布物之外templates/vault/才是可分发的种子模板新建/接管走 dry-run-first 命令ZCODE.md 要求用 dry-run 优先的init命令创建独立 vault或用adopt接管既有 vault。对应的确定性命令见 skills/wiki/SKILL.md 的完整示例为python3 $CORE init /absolute/path/to/vault \ --generated-at ISO-UTC --operation-id init-reviewed python3 $CORE init /absolute/path/to/vault \ --generated-at ISO-UTC --operation-id init-reviewed \ --approved-plan-sha256 reviewed-sha256 --apply第一条输出初始化计划initialization-plan.v1只有人工审查过计划摘要后第二条才携带--approved-plan-sha256真正执行。adopt对既有 vault 走同样的计划 → 审查 → 应用路径见 claude_obsidian/cli.py 中command_init/command_adopt解析顺序 fail-closedZCODE.md 要求在读取wiki/hot.md或运行任何技能之前先解析 vault。这一顺序在源码中由resolve_vault_root精确实现claude_obsidian/paths.py优先级为显式--vault→ 环境变量CLAUDE_OBSIDIAN_VAULT→ 向上查找最近的.claude-obsidian.json工作区配置 → 当前目录及其祖先中无歧义的已初始化 vault。任何一步失败都抛出VaultSelectionError如VAULT_NOT_FOUNDno vault selected; pass --vault or set CLAUDE_OBSIDIAN_VAULT即选不出 vault 就拒绝工作而不是回退到产品仓库自身。同文件的assert_not_plugin_tree还会显式拒绝把可变 vault 状态写入已安装的产品树内PLUGIN_ROOT_IS_NOT_VAULT从机制上堵死在插件缓存里误建 vault的错误。wiki/hot.md本身按 AGENTS.md 的 vault 约定是有界最近上下文绝非转录若要把它注入会话上下文还需要用户显式设置CLAUDE_OBSIDIAN_SESSION_CONTEXT1作为同意信号且工作区外的 vault 必须同时给出精确的CLAUDE_OBSIDIAN_SESSION_CONTEXT_VAULT路径——绝不允许自动设置。共享变更协议一个经过审查的事务 bundleZCODE.md 对 ZCode 会话的变更纪律表述为所有共享变更使用唯一一个经过审查的claude-obsidian.transaction.v1bundle并行工作者只产出草稿禁止直接共享写、自动提交和已弃用的按文件锁助手远程出站remote egress与破坏性操作需要用户明确同意。这些约束在可移植核心中都有对应的实现实体bundle 模式名claude_obsidian/transaction.py第 41 行定义BUNDLE_SCHEMA claude-obsidian.transaction.v1与 ZCODE.md 中的字符串逐字一致操作类型即权限边界同一模块的OPERATION_TYPES声明了base、save、ingest、autoresearch、lint-fix、capture、generic等类型源码注释强调 an operation type is an authority boundary, not merely an audit label——每种类型能写的路径域是声明式的.raw/原始载荷是 create-only仅可创建实现上通过_WIKI_ONLY_OPERATIONS、_WIKI_AND_RAW_OPERATIONS等集合把权限域钉死实现层面为何不是原子文件系统操作transaction.py 的模块注释解释了设计动机——多文件更新在常见文件系统上不可能真正原子因此提供一套诚实的更强契约进程持有的变更锁、前置哈希precondition SHA-256、持久日志journal、逐文件原子替换临时文件 os.replace 父目录 fsync见_atomic_vault_write以及针对整个操作的确定性回滚/恢复审查摘要与冲突语义claude_obsidian/cli.py 中transaction apply缺少--approved-plan-sha256会直接报错 transaction apply requires --approved-plan-sha256 from transaction inspect若重新生成的事务与已审查计划不一致则报 the regenerated transaction differs from the reviewed plan。运行期发现目标文件在审查后已被改动时抛出TransactionConflict其退出码固定为 75transaction.py与临时/可重试错误区分开规模上限单事务单文件上限 64 MiB、总量 128 MiB、写操作数 1024MAX_TRANSACTION_*常量组transaction.py防止事务日志本身成为不可控状态。弃用的按文件锁助手指scripts/wiki-lock.sh——它在仓库中仍然存在并有配套测试 tests/test_wiki_lock.sh 验证其行为但 AGENTS.md 的 Mutation protocol 明确将其列为不得再使用的历史方案transaction.v1bundle 是唯一的共享变更通道。端到端工作流小结把 ZCODE.md 的条款串起来一个 ZCode 会话操作 claude-obsidian 知识库的完整合规流程是阶段动作依据1. 一次性安装bash scripts/setup-multi-agent.sh --host zcode预览确认后加--apply把 15 个技能符号链接到~/.zcode/skills/ZCODE.md、setup-multi-agent.sh2. 读取契约ZCode 原生读取AGENTS.mdworkspace/user 作用域无需镜像规则文件ZCODE.md、AGENTS.md3. 解析 vault按--vault→CLAUDE_OBSIDIAN_VAULT→ 最近.claude-obsidian.json→ cwd 祖先发现选不出即失败新库先init、老库adopt均 dry-run-firstpaths.py、skills/wiki/SKILL.md4. 加载上下文vault 解析成功后才静默读取wiki/hot.md注入会话需显式环境变量同意AGENTS.md5. 执行变更并行工作者只产草稿 → 合并为单个claude-obsidian.transaction.v1bundle →transaction inspect审查 → 带--approved-plan-sha256应用 → 汇报操作 ID 与精确变更路径transaction.py、cli.py6. 高风险动作远程出站、破坏性修复、规范研究合并一律要求用户明确同意ZCODE.md、AGENTS.md最后一点与发布流程相关AGENTS.md 的 Verification 一节要求行为变更后运行make test覆盖全部 Python/shell 测试套件与产品、能力、包、钩子、清单契约见 Makefile且任何 Agent 未经所有者批准不得推送、打标签或发布版本——这也解释了为什么 ZCODE.md 的同意门槛从文件安装到 vault 写入再到远程出站是一以贯之的。【免费下载链接】claude-obsidianSelf-organizing AI second brain for Obsidian Claude Code. Drop any source and Claude reads, links, and files it into one connected knowledge graph of plain Markdown you own. AI note-taking, personal knowledge management (PKM), and an open-source Notion alternative. Based on Karpathys LLM Wiki pattern.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-obsidian创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考