zettelkasten-second-memory AGENTS.md

Zettelkasten Project Guidelines

系统版本信息（每次思考必须考虑）

• OpenClaw 版本: 2026.4.24 / 2026.6.x（兼容 >= 2026.4.23）
• Zettelkasten 插件版本: v1.0.0-beta.8
• Skill 版本: v1.0.0-beta.8
• Hermes Agent: v0.17.0+（实验性支持）
• Node 要求: >= 22.14.0（node:sqlite 需要 Node 22+）

兼容性保障索引

所有兼容性相关决策、已知坑、版本矩阵、测试命令都记录在 docs/COMPATIBILITY.md。 每次修改兼容性相关代码前，先更新该文档。

OpenClaw 2026.6.x 兼容性变更

2026.6.x 引入了基于 contracts.tools 的插件工具契约：

1. 插件 manifest 必须声明 contracts.tools（已在 src/plugin/openclaw.plugin.json 中补齐全部 zk_* 工具名）。未声明时，运行时 api.registerTool(...) 会被拒绝，agent 看不到任何 zk 工具。
2. 工具 allowlist 仍通过 tools.alsoAllow 配置，但推荐使用插件 ID 或 group:plugins：
   • 2026.4.x：tools.alsoAllow: ["zettelkasten"]
   • 2026.6.x+：tools.alsoAllow: ["group:plugins"] 或 ["zettelkasten"]（两者在 manifest 声明 contracts 后都会被正确展开为具体工具）
3. systemPromptOverride 已移除：2026.6.x+ 不再接受 agents.defaults.systemPromptOverride，Skill 通过 skills.load.extraDirs 正常加载即可。
4. 修改 manifest 后需要刷新插件索引：

   openclaw plugins registry --refresh
   openclaw gateway restart
   

OpenClaw 2026.4.24 配置字段备忘

常见错误	正确字段
agents.default	agents.defaults
agents.defaults.systemPrompt	agents.defaults.systemPromptOverride
agents.defaults.skills 填文件路径	agents.defaults.skills 填 skill ID（如 ["zettelkasten-brain"]）

⚠️ 关键配置（部署时必须检查）

1. 插件工具暴露 — tools.alsoAllow 应包含 "zettelkasten"：

   {
     "tools": {
       "profile": "coding",
       "alsoAllow": ["zettelkasten"]
     }
   }
   

   否则 agent 无法调用 zk_search_notes 等 MCP 工具。

   ⚠️ 注意: alsoAllow 中不要放入 Skill ID（如 "zettelkasten-brain"）。alsoAllow 只接受 Tool Name（以 zk_ 为前缀的工具名，如 "zk_search_notes"、"zk_create_note" 等）。放入 Skill ID 会导致 OpenClaw Gateway 工具策略验证失败，引发崩溃-重启循环（BUG-001）。

2. systemPromptOverride — 不支持 file: 前缀，需直接填入文本内容：

   # 错误
   openclaw config set agents.defaults.systemPromptOverride "file:..."
   
   # 正确：直接写入文本（或通过脚本读取文件内容后设置）