Obinit

Obinit

把项目接入“仓库规则 + 项目内 memory + Obsidian 项目上下文”。新项目可创建完整规则源；成熟项目只加索引和 memory 协议，不替代已有 AGENTS.md / CLAUDE.md。

默认遵循用户或项目既有语言偏好。当前模板使用简体中文，fork 可替换 templates/、README 和 manifest 文案；路径、命令、包名和英文专有名词保持原样。

运行时假设

• 仓库内写入只依赖文件系统和 node；scripts/inspect-project.mjs 需要可用的 node，不可用时改为手工读取入口文件和 memory 文件判断模式。
• git 可选：inspect-project.mjs 在非 git 目录回退到当前目录作为项目根，不报错。
• Obsidian 同步需要桌面端已打开目标 vault 且 obsidian CLI 可用；CLI 不可用或无法解析 vault 本地路径时，只完成仓库内文件写入，把未完成的 Obsidian 同步项列为待确认，不退回 CLI mutation。

快速流程

1. 确定项目根目录：优先 git root，否则当前目录。
2. 运行或等价执行 scripts/inspect-project.mjs 判断模式：

node <skill>/scripts/inspect-project.mjs <project-root>

3. 读取 AGENTS.md、CLAUDE.md、.agents/instructions.md、README.md 和 package metadata；对 docs/ 只检查 docs 顶层信号和索引。
4. 只在 allowlist 内创建或更新：AGENTS.md、CLAUDE.md、.agents/、docs/adr/，以及 .gitignore 的 .agents/scratch/ 条目。
5. 选择模板、合并已有内容、写入项目 memory。
6. 按 references/obsidian-sync.md 的 vault 文件写入契约创建或更新 Agent/Projects/<project>.md。
7. 读回更新过的项目文件；完成后必须读回 Obsidian 项目笔记。

初始化模式选择

先按 references/init-modes.md 处理分支和冲突。

重复运行模式先按 references/memory-upgrade.md 逐节对比模板与现有文件，报告差异并等用户确认，不自动改写。

成熟项目接入模式下，AGENTS.md / CLAUDE.md 仍是项目/工具指南事实源。索引型 .agents/instructions.md 只记录 memory 协议、Obsidian 项目笔记路径、源文件链接和写入边界。

不要把 AGENTS.md / CLAUDE.md 的长内容完整复制进 .agents/instructions.md。

默认不递归读取 docs/。只列出 docs 顶层目录和读取已存在的索引文件，例如 docs/README.md、docs/index.md、docs/adr/README.md；设计/计划文档只读取 .agents/active.md 指向的具体文件或用户指定的文件，不按工具路径批量读取。

发现规则冲突、入口文件语义冲突或目录用途不一致时，停止写入冲突文件并列出待确认项；无冲突的 allowlist 文件可以继续创建。

入口文件保护

处理 AGENTS.md、CLAUDE.md 前先读 references/entry-file-policy.md。

• 文件不存在或为空：可用 templates/agent-entry.md 创建。
• 已有非空入口文件只追加符合语言偏好的入口段。
• 已有等价 .agents/instructions.md 指针：不修改。
• 不得用 templates/agent-entry.md 整体替换已有非空入口文件。
• 除非用户明确说“覆盖”“重写”或指定替换文件，否则不要压缩、重排或删除已有入口内容。

Memory Bank

项目内 memory 规则见 references/memory-bank.md。

默认文件：

.agents/instructions.md
.agents/active.md
.agents/progress.md
.agents/lessons.md
.agents/archive/
.agents/scratch/
docs/adr/

更新时机：

• 任务开始时在 .agents/handoffs/ 创建自己的交接文件；.agents/active.md 是派生视图，由 $obclose 重建。
• 完成实质任务或复杂任务暂停时按 $obclose 收尾。
• 重要里程碑追加 .agents/progress.md。
• 可跨任务复用的坑和规则写入 .agents/lessons.md。
• 当状态已由权威状态载体记录时（git commit、tag、PR、CI/CD、release、artifact、ADR、migration、issue/ticket、runbook），.agents/active.md / .agents/progress.md 只记录下一次 agent 需要接手的未完成事项、不在权威载体中的决策背景、阻塞或人工确认点；不记录短暂中间态，已完成状态在最终回复说明。
• .agents/archive/ 保存过长 progress.md 的历史归档，应提交；它不是临时草稿。
• 长期技术决策写入 docs/adr/。
• 项目内既有的设计/计划文档（无论由哪个工具生成）保留原文件，memory 只链接；obinit 不创建、不改写、不按工具路径批量读取它们。
• 临时调查草稿写入 .agents/scratch/；运行日志、缓存和生成物不要放进 agent memory。

Obsidian 同步

Obsidian 只作为跨会话上下文和公共知识入口，不作为源码、构建、测试、部署或运行时依赖。细节见 references/obsidian-sync.md。

• 项目笔记默认路径：Agent/Projects/<project>.md。
• 公共知识默认路径：Agent/Knowledge/。
• 公共知识发现入口：Agent/Knowledge/_catalog.md。它是已沉淀公共知识的事实来源，不存在或不命中时不要凭空假设。
• 文档默认路径：Agent/Documents/。
• 文档目录入口：Agent/Documents/_catalog.md。它是人类可读文档目录和显式读取入口，只有用户明确指定、任务明确涉及文档主题，或执行 $obdoc / $obcurate 文档流程时读取。
• 重复运行时也要检查 Obsidian 项目笔记。
• Obsidian 项目笔记存在但内容过期时，按当前模式幂等更新。
• Obsidian 项目笔记的相关知识只记录真实查阅或明确相关的公共知识笔记；不要预填通用示例链接。
• Obsidian 项目笔记是干净索引，只写真实链接、真实状态和真实记录；省略空章节，不写 暂无 或“需要时补充”。
• 相关知识、决策、开放问题、常用命令 只有有真实内容时才写入；初始化模式和 $obinit 接入记录写入 当前状态 或 Agent 记录，不写入决策。
• 完成后必须读回 Obsidian 项目笔记。

任务开始或遇到相关问题时，不凭空假设哪些领域已有公共知识。只有用户明确要求、Agent/Knowledge/_catalog.md 的 terms / aliases 命中任务关键词，或风险较高且关键词明确时，才在 Agent/Knowledge/ 做有限关键词定向搜索；只有命中相关笔记后才明确读取并使用。读取 Knowledge catalog 命中项时看 kind 和 use_as：kind: knowledge / use_as: rule、checklist 或 heuristic 这类公共经验可以作为规则、检查清单或启发式判断。Agent/Documents/_catalog.md 是文档目录；只有用户明确指定、任务明确涉及文档主题，或执行文档整理时才读取。不要全量自动加载公共知识，不扫描整个 vault。

项目相关知识回写

项目相关知识按 unknown / candidate / confirmed 三档渐进回写；判定信号、写入位置和幂等维护规则见 references/obsidian-sync.md。只回写链接和简短使用语义，不复制公共知识正文。

模板

优先使用本 skill 的模板：

如果目标文件已有非空内容，先读取并合并；只有用户明确要求替换时才整体覆盖。

调用方式

常规使用：

$obinit

或：

使用 obinit 初始化当前项目。

只有偏离默认行为时才补充说明，例如指定项目名、指定 Obsidian vault、跳过 Claude 入口或允许覆盖已有文件。