企业官网建设流程全解析

claude-obsidian 领域 Vault 脚手架剖析：六种 Scaffold Profile、不变量与事务化应用流程

【免费下载链接】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 Karpathy's LLM Wiki pattern.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-obsidian

在 claude-obsidian 中，把一个知识库 Vault 从"能用"变成"贴合你的领域"，靠的不是临时改目录，而是一套称为领域脚手架（domain-specific scaffold profiles）的机制：在既有 Vault 基线之上，用一笔可审查、可回滚的操作级事务，为网站内容、软件仓库、业务项目、个人知识库、研究或书籍课程等六类领域追加文件夹、页面类型与索引小节。读完本文，你将掌握六类脚手架 Profile 各自的推荐路由与页面属性约定、所有 Profile 必须遵守的六项不变量、Profile 的标准应用流程，以及背后wiki/路由校验、dry-run/apply 两段式事务等源码级机制。

什么是领域脚手架 Profile：基线优先，Profile 只是增量

skills/wiki/references/modes.md的第一句话就划定了边界：必须先完成基线 Vault 的初始化（init）或接管（adopt），Profile 才在其之上生效。Profile 的作用是在"一笔经过审查的事务"（one inspected transaction）中追加文件夹、页面类型和索引小节；它不替代所选定的组织方法论（generic、lyt、para或zettelkasten四种 mode），也不会重写既有笔记和已有路由。

这一点在 skills/wiki/SKILL.md 中被固化为编排规则：当用户要求"领域专属脚手架"时，必须先建立基线，再读取 skills/wiki/references/modes.md，然后把追加的页面与配置起草为一个操作级事务，并且明确禁止用宿主 Write/Edit 工具或 Obsidian transport 直接改动 Vault 文件。换言之，Profile 是方法论（mode）之上的领域化增量层：mode 决定"source/entity/concept 该落到哪个目录"，Profile 决定"这个领域还需要哪些额外的目录与页面类型"。

从源码结构看，这套"增量不改存量"的约定有明确实现支撑：

• mode 配置保存在 Vault 内的.vault-meta/mode.json。核心 CLI 的_load_mode_document（见 claude_obsidian/cli.py）读取时采用深拷贝默认配置再逐节合并的策略——文件缺失时回落到generic默认值，文件存在时只合并用户已配置的部分，因此"保留既有自定义路由设置"不是口头承诺，而是合并逻辑的自然结果。
• 路由器脚本 scripts/wiki-mode.py 对缺失配置同样回落到generic（"No skill needs to special-case the missing-config path"），但对损坏的配置则 fail closed（退出码 5），拒绝悄悄用 Generic 顶替用户配置。这一点在 skills/wiki-mode/SKILL.md 中也被写成硬性规则："never silently substitute Generic for corrupt user configuration"。

六项不变量：任何 Profile 都不许破坏的底线

原文档列出了所有 Profile 必须保持的不变量（invariants），这是判断一次脚手架改动是否"合法"的验收清单：

第二条不变量有直接的源码约束。claude_obsidian/mode_config.py 中的validate_wiki_route要求任何被路由的页面路径：不能是绝对路径、不能含../.段、第一级目录必须是wiki、扩展名必须是.md。也就是说，无论 Profile 建议了wiki/pages/还是wiki/modules/，最终落盘路径都必须通过这条wiki/限定校验。同理，validate_wiki_folder（同文件 L27-L48）要求自定义目录键必须以/结尾、以wiki/为根、不含反斜杠与控制字符——Profile 中追加的目录如果不符合规范，配置加载阶段就会直接报错。

六种 Profile：推荐路由、页面属性与领域约束

以下六节逐条继承原文档对每种 Profile 的约定，并补充路由层可核对的事实。

网站或内容系统（Website or content system）

• 推荐路由：wiki/pages/、wiki/structure/、wiki/audits/、wiki/keywords/、wiki/entities/。
• 有用的页面属性：来源 URL、生命周期状态、规范 URL（canonical URL）、最后核验日期、内链计数。
• 领域约束：爬虫与数据分析导出（crawl / analytics exports）一律当作source对待；没有当前证据时，不得断言"已被实时收录"或"HTTP 状态是某某"。

这类 Profile 的核心纪律是"证据时效性"：页面属性里的last verified字段本质上就是提醒——爬取快照会过期，任何关于线上状态的陈述都必须绑定一个可回指的来源记录。这与项目整体的 provenance 原则一致（见 skills/wiki/references/provenance.md）：证据不支持的主张保持"unsupported"，绝不虚构来源、引用或日期。

软件仓库（Software repository）

• 推荐路由：wiki/modules/、wiki/components/、wiki/decisions/、wiki/dependencies/、wiki/flows/。
• 必须记录：仓库相对路径（repository-relative paths）、用途、状态、依赖关系，以及来自代码、测试、issue 或一手文档的证据。
• 领域约束：生成的架构页面必须区分"观察到的行为"与"推断"。

这条约束可以直接映射到本仓库自身的工程实践：从源码结构看，claude-obsidian 对"事实边界"的执行方式正是如此——例如 scripts/wiki-mode.py 的注释区分了"读取时非破坏性的归一化"与"经审查的mode set事务才持久化"，即行为（读取输出被归一化）与设计意图（磁盘上的旧值由后续事务升级）分开陈述。对维护软件仓库知识库的人来说，把"读代码看到的"与"推测的"在页面中分栏书写，是这类 Profile 最有价值的习惯。

业务或项目（Business or project）

• 推荐路由：wiki/stakeholders/、wiki/decisions/、wiki/deliverables/、wiki/intel/、wiki/meetings/。
• 必须记录：决策日期、负责人、状态、理由、来源记录。
• 领域约束：相互矛盾的回忆要作为有争议的证词（contested evidence）保留，而不是重写历史。

"不重写历史"与项目的账本设计同源：evidence/claim ledgers 是 append 性质的记录层，决策页面的状态变更应体现在新记录中，旧记录仍可作为当时认知的证据被检索到。

个人知识库（Personal knowledge vault）

• 推荐路由：wiki/goals/、wiki/learning/、wiki/people/、wiki/areas/、wiki/resources/。
• 领域约束：默认只做本地处理；在捕获消息、健康、财务、关系或语音数据之前，先确认隐私与保留策略；用户只要求保存一条洞见时，不要把整段对话存下来。

注意wiki/areas/、wiki/resources/与 PARA mode 的areas_folder（wiki/areas/）、resources_folder（wiki/resources/）在默认配置中是同一组目录（见 scripts/wiki-mode.py 的DEFAULT_CONFIG）。这意味着选择 PARA 方法论的个人 Vault 天然与"个人知识库"Profile 的路由兼容——Profile 增量叠加在 mode 路由之上，二者目录重合时不会产生冲突，这正是"Profile 不替代 mode"设计的实际收益。

研究（Research）

• 推荐路由：wiki/papers/、wiki/concepts/、wiki/entities/、wiki/syntheses/、wiki/gaps/。
• 必须跟踪：在 ledgers 中记录主张支持度（claim support）、矛盾、权威性、独立性、新鲜度与风险。
• 领域约束：论文摘要（paper summary）从属于被捕获的论文本身，不会自动为其主张背书。

"摘要不背书"对应的正是wiki/meta/ledgers/账本中 claim 与 evidence 的分离：摘要页是二级衍生内容，其claims的 support 状态必须由 ledger 独立评估。wiki/gaps/路由则提示研究型 Vault 把"未解问题"当作一类正式页面来管理，而不是散落在笔记边角。

书籍或课程伴侣（Book or course companion）

• 推荐路由：wiki/chapters/、wiki/concepts/、wiki/people/、wiki/exercises/、wiki/reflections/。
• 领域约束：只捕获用户有权存储的内容；优先写带来源链接的精简笔记，而不是复现受版权保护的章节或完整讲义。

这类 Profile 的取舍标准是"派生内容的授权与版权边界"：wiki/reflections/（个人反思）通常比wiki/chapters/（章节级摘录）安全得多，原文档把"concise source-linked notes"置于"reproducing copyrighted chapters"之前，就是在给出这个优先级。

应用 Profile：六步流程与事务核心

原文档给出的应用流程（Applying a profile）是全文最可操作的部分，共六步，完整继承如下：

1. 检视当前的 methodology 与代表性笔记；
2. 起草folder/page/property 映射，并识别命名冲突；
3. 展示拟议路径与任何 schema 追加项；
4. 通过事务核心一次性应用已批准的追加项；
5. 运行确定性 lint，报告未解决的发现（findings）；
6. 让真实使用决定后续精化，而不是预先搭建空的目录层级。

每一步都能在仓库中找到对应机制：

第 1 步（检视 mode）。读取当前方法论与路由配置的标准方式是：

python3 scripts/claude-obsidian.py mode get --vault <vault>

该命令输出合并后的完整 mode 文档（schema_version、mode、configured_at与四种 mode 的目录配置）。实现上它调用command_mode_get（claude_obsidian/cli.py），配置解析与scripts/wiki-mode.py的load_config使用同一套默认值与校验，保证 CLI 与路由助手看到的世界一致。

第 3 步（展示拟议路径）。Profile 起草阶段可以借助路由器做只读预览，--mode参数允许在不写mode.json的情况下预览某个 mode 下的目标：

python3 scripts/wiki-mode.py --vault <vault> route concept "Example concept" --mode lyt

路由器对名称做了双重净化：safe_name剥离路径分隔符、空字节与控制字符（防止../逃逸），slugify把任意连续的非字符合并成单个连字符（v1.8 launch! prep?→v1-8-launch-prep，且保留 CJK 等 Unicode 字字符）。文件名分量整体被限制在255 个 UTF-8 字节以内，超长标题会被截断并追加确定性 SHA-256 哈希后缀，避免两个长标题因前缀相同而静默撞名（scripts/wiki-mode.py）。这些测试在 tests/test_wiki_mode.py 中有系统性覆盖，包括test_routes_bound_portable_component_bytes（255 字节上限）、test_route_path_blocks_traversal_for_generic_entity_and_concept（路径穿越拦截）等用例。路由器输出只是提案：必须把它当作 vault 相对路径做校验，并把最终选定的路径写进操作预览。

第 4 步（一次事务应用）。这是 Profile 流程的心脏，机制与mode set完全同构。以核心 CLI 为例，mode set的 dry-run/apply 两段式为：

# 第一段：dry-run，输出完整事务计划与 approved_plan_sha256 python3 scripts/claude-obsidian.py mode set para --vault <vault> \ --generated-at <ISO-UTC> --operation-id mode-reviewed # 第二段：携带审查过的计划哈希，真正应用 python3 scripts/claude-obsidian.py mode set para --vault <vault> \ --generated-at <ISO-UTC> --operation-id mode-reviewed \ --approved-plan-sha256 <reviewed-sha256> --apply

兼容包装脚本行为一致（scripts/setup-mode.sh）：

bash scripts/setup-mode.sh --vault <vault> --mode para bash scripts/setup-mode.sh --vault <vault> --mode para \ --generated-at <ISO-UTC> --approved-plan-sha256 <reviewed-sha256> --apply

源码层面，command_mode_set（claude_obsidian/cli.py）构造一个claude-obsidian.transaction.v1bundle：写入目标被限定为.vault-meta/mode.json单一路径，bundle 携带expected_hashes（旧文件哈希，实现乐观并发控制）与内容sha256。不带--apply时只输出claude-obsidian.mode-plan.v1的 dry-run 计划；带--apply时由_require_approved_operation校验审查哈希后才落盘。Profile 的"一笔事务"要求就是把多个目录/页面/索引改动装进同一个 bundle，而不是逐条零散写入——这与 skills/wiki/references/operation-transactions.md 定义的"一个逻辑操作产生一个可检查、可恢复的事务 bundle"契约一致。

第 5 步（确定性 lint）。应用后运行 lint 引擎对 Vault 做确定性检查（如 claude_obsidian/lint_engine.py 与对应测试 tests/test_lint_engine.py），并把未解决项如实报告，而不是静默忽略。

第 6 步（让使用驱动精化）。Profile 明确反对"预建空层级"：六类 Profile 给的是suggestedroutes，目录在第一次真实写入时由事务创建。这保证了 Vault 不出现大量空文件夹污染 Obsidian 文件树，也符合基线"non-destructive、不隐式 seed 文件夹"的语义（setup-mode.sh的 usage 注释即声明 "This command never moves existing notes or seeds folders implicitly"）。

与方法论 Mode 的协作：Profile 之上的路由层

理解 Profile 与 mode 的分层后，可以完整描述一次"领域 Vault 落地"的调用链：

1. init/adopt建立基线（确定性 setup 命令，同样默认 dry-run，见 skills/wiki/SKILL.md 的 Set up a vault 一节）；
2. mode get/wiki-mode.py route提供只读路由预览，路由助手按 mode 分发内容类型——可路由类型包括source、entity、concept、session、question，以及遗留别名research（等价于concept，保持既有落点不变；见 claude_obsidian/page_schema.py 的LEGACY_TYPE_ALIASES与 tests/test_wiki_mode.py 的test_legacy_research_alias_keeps_its_exact_destinations用例）；
3. Profile 增量以单个事务 bundle追加领域路由与页面类型；
4. lint 收口，未决项如实报告。

需要强调的边界（原文档与文档体系反复出现）：

• mode 只影响未来路由：mode set不创建文件夹、不移动笔记、不改写链接、不迁移旧内容；批量重组是独立的迁移工程，需要完整移动映射、链接改写计划、期望哈希、冲突处理、回滚方案与显式用户批准——"never make it a side effect ofmode set"（见 docs/methodology-modes-guide.md）。
• mode 是组织元数据，不是证据：某条笔记所在的文件夹不会提升它的权威性、新鲜度或可信度。这一条对 Profile 同样适用——wiki/decisions/里的页面不会因为放在"决策"目录就自动获得更高置信度，置信度永远由 ledger 决定。
• Zettelkasten ID 的规范格式为YYYYMMDDHHMMSSffffff-UUID4HEX（UTC 微秒前缀 + UUIDv4 随机数，保证时间可排序且跨进程抗碰撞，实现见 scripts/wiki-mode.py）。遗留的"仅时间戳"id_format会在读输出和下一次经审查的mode set事务中被归一化，但既有文件名绝不会被重命名。

小结：一份可直接执行的验收清单

把 skills/wiki/references/modes.md 落地时，建议按以下清单逐项核对：

1. 基线是否已通过init/adopt建立（.raw/不可变来源、wiki/生成知识、wiki/index.md/log.md/hot.md生命周期页面、wiki/meta/ledgers/账本四件套齐备）；
2. 所选 Profile 的推荐路由是否全部位于wiki/子树下（可通过validate_wiki_route等价校验或路由预览命令验证）；
3. 领域必备属性（来源 URL、决策负责人、claim 支持度等）是否进入了页面 frontmatter 草案；
4. 追加项是否被打包为一个claude-obsidian.transaction.v1bundle，且 dry-run 的approved_plan_sha256在应用前经过人工审查；
5. 应用后是否运行了确定性 lint，未决发现是否被如实报告；
6. 是否避免了预建空目录，把精化留给真实使用。

这套机制的设计取向很清楚：领域化是"增量 + 审查 + 事务 + 验证"的组合，任何一步越界（拆散事务、隐式迁移、绕过审查哈希、未经批准引入外部能力）都会破坏 Vault 作为"用户拥有的纯 Markdown 知识图谱"的可恢复性。

参考路径索引

【免费下载链接】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 Karpathy's LLM Wiki pattern.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-obsidian