Obsidian 仓库工程化（免 GUI 装插件 + 看板 + 日记）

为什么这么做：Obsidian 的社区插件不需要在界面里点安装。文件到位 + 配置到位，重启即生效。
比让用户"自己点安装"少五步，也不会被"受限模式"卡住。

一、核心原理

插件生效只需要两样：

1. <vault>/.obsidian/plugins/<plugin-id>/ 下有 main.js + manifest.json + styles.css
2. <vault>/.obsidian/community-plugins.json 里列出 <plugin-id>

配套：
- 日记模板 + 存储位置 → .obsidian/daily-notes.json
- 模板文件夹 → .obsidian/templates.json

> ⚠️ community-plugins.json 里写的是 manifest.json 的 id 字段，不是目录名。多数情况两者相同，但别想当然。

二、步骤

1. 先读仓库现状（别猜）

cat "<vault>/.obsidian/core-plugins.json"       # 哪些核心插件开着（templates / daily-notes / bases…）
cat "<vault>/.obsidian/community-plugins.json"  # 已有哪些社区插件（不存在 = 受限模式可能还开着）
cat "<vault>/.obsidian/app.json"
cat "<vault>/.obsidian/templates.json"

2. 查插件最新版

api.github.com 一般能直连（和 github.com 不同，后者常被封）：

curl -sL "https://api.github.com/repos/<owner>/<repo>/releases/latest" -o p.json

常见插件：

> manifest.json 里的 version 常常比 release tag 旧（发布脚本没同步），不影响加载，别当成下载错误。

3. 下载（这一步最容易失败）

用 scripts/install_plugin.sh，它带重试 + 尺寸校验。

• 可用镜像：https://ghproxy.net/（首选）、https://cdn.gh-proxy.com/
• 必须带重试：curl -o 单次下大文件会被静默截断——实测 2.32 MB 的 main.js 只下到 1.66 MB，而 curl 返回码仍是 0，不报错。
• 下完必须校验（两样都做）：
  1. manifest.json 能 json 解析、id 字段对得上
  2. node --check main.js 通过（说明文件完整可解析）

4. 启用插件

写 <vault>/.obsidian/community-plugins.json：

[
  "dataview",
  "obsidian-tasks-plugin"
]

这个文件存在本身就表示受限模式已关闭。

5. 设默认仓库

配置文件位置：
- Windows：%APPDATA%\obsidian\obsidian.json
- macOS：~/Library/Application Support/obsidian/obsidian.json

格式：

{"vaults":{"<16位id>":{"path":"D:\\path\\to\\vault","ts":<毫秒时间戳>,"open":true}}}

只留一个 vault 条目 = 用户想开别的都开不了，等价于「默认仓库」。比找"默认仓库"设置项靠谱。

> ⚠️ 必须先彻底关掉 Obsidian 再改。否则它退出时会把内存里的旧状态写回，覆盖你的修改。

6. 验证（必做）

顺序：关进程 → 改配置 → 重启 → 验证

• 读窗口标题：应包含 vault 名（例：知识库 - Obsidian 1.13.7）
• 读 <appdata>/obsidian/obsidian.log 尾部，确认 0 条 error
• 检查 community-plugins.json 是否被 Obsidian 保留（被清空 = 插件没被接受）

> ⚠️ Electron(Chromium) 窗口截图在很多环境抓不到（GDI BitBlt / PrintWindow 只能得到背景色或空白）。
> 用「窗口枚举 + 标题」当证据，不要交空白图。

三、Dataview 查询模板（直接抄）

全库未完成待办（排除模板/归档噪音）

```dataview
TASK
WHERE !completed
  AND !contains(file.path, "模板")
  AND !contains(file.path, "归档")
GROUP BY file.link
```

按 frontmatter 字段分组统计

```dataview
TABLE WITHOUT ID 篇 AS 篇, length(rows) AS 未完成条数
FROM "某个目录"
WHERE 状态 != "初稿完成"
GROUP BY 篇
```

规则：永远同时给原生兜底

Obsidian 内置搜索支持 task-todo:（查全库未完成任务）、task-done:。
在 Dataview 代码块旁边写一句「插件没启用就用 task-todo: 搜」，用户不至于抓瞎。

四、日记模板配置

templates.json：

{"folder":"模板"}

daily-notes.json：

{"folder":"10-日记","template":"模板/每日日记","format":"YYYY-MM-DD","autorun":false}

模板文件里用核心 Templates 语法：{{date:YYYY-MM-DD}}、{{date:dddd}}。
用户入口：Ctrl+P → 「日记：打开今天的日记」。

五、坑清单（都是实打实踩过的）

1. curl -o 下大文件静默截断 → 必须重试 + 尺寸校验，别信返回码。
2. 改配置前没关 Obsidian → 改动被覆盖，白干。
3. Git Bash 的 /d/... 路径不能传给 Python open() → 用 D:\...。
4. Python 生成中文 Markdown 时引号会打架："""...""" 定界符内若内容以 " 结尾，会产生 4 个连续引号导致 unterminated string literal。
   - 对策：长中文文本一律用 ''' 定界符。
   - 另外：每个 dict 赋值结尾不要跟逗号，否则语句变成 1 元 tuple（报错 not enough values to unpack）。
5. 文件名清洗不要直接删非法字符 —— 会把 "明前""雨前" 变成 明前雨前。正确做法是从笔记 H1 标题反推文件名，引号转全角成对 “”，/ → 、。

💳 付费能力（Pay Skill）

本 Skill 的基础能力永久免费：插件预装与看板搭建（本地）。

仅「插件模板增强包」为按次付费（0.5 元/次）——付费购买的是服务端下发的方法论资产（插件配置模板库、日记模板库），不是算力。

> 重要：本 Skill 不自建、不部署任何大模型。付费项所需的算力由用户自带（BYOK）或本机提供；用户自带算力同样支付 0.5 元——因为买的是方法论，不是算力。

计费范围

支付依赖（支付宝 AI 按量付费官方能力）

买家侧依赖安装（运行环境尚无时执行一次）：

npx -y @alipay/agent-payment@latest install

> 本 Skill 不自行实现付款流程、不做任何签名与密钥处理。付款、收银与签名全部交给支付宝官方能力完成。

支付流程（Agent 自动执行）

服务端为已通过线上验证的支付宝 AI 按量付费（A2M 402）服务 https://chayuntang-skills.app.workbuddy.host/api/resource（单价以服务端下发的 402 账单为准）。

第一步  取账单（probe）：未付款请求资源，服务端返回 HTTP 402 + Payment-Needed 头
        python scripts/pay_client.py --info
        → 解析出账单 { out_trade_no, amount, currency, goods_name, service_id }

第二步  收银（pay）：向用户明示金额并取得同意后，由官方买家能力收银
        alipay-bot 402-buyer-pay \
          --resource-url "https://chayuntang-skills.app.workbuddy.host/api/resource?skill=obsidian-vault-bootstrap&feature=default" \
          --intent-summary "给Obsidian仓库预装插件与看板"
        → 用户完成支付后取得 Payment-Proof 凭证
        ⚠️ 必须先向用户明示金额、取得同意后再继续
        ⚠️ 意图摘要必须写清原始业务目的，保留用户最初想做的事

第三步  取回资源（complete）：携带凭证重试，服务端验付并下发内容、发送履约回执
        python scripts/pay_client.py --payment-proof "<Payment-Proof>"
        → 服务端验付通过后返回付费内容，HTTP 2xx 即履约 ack（履约确认完成）

Agent 注意事项：

1. 三步复用同一个原始请求（URL、feature、必要请求头保持一致），付款后不重新下单；
2. 需要支付时以退出码 2 退出，并在 stdout 输出账单 JSON（含 bill、next_action）；
3. 支付状态不明时先查单（官方 alipay-bot 402-query-payment-status），不重复付款、不追加独立回执；
4. 履约回执失败时服务端重试同一订单并保持幂等，不因回执失败要求用户重新付款；
5. 验付失败（凭证无效或过期）时服务端不交付资源，本 Skill 自动降级为免费基础能力继续工作，不让用户走死路。

付费改造自查（对齐 SkillHub 支付宝付费改造规范）

协议与字段细节见 references/payskill/A2M-402-支付协议说明.md，官方支付能力用法见 references/payskill/官方支付能力说明.md。