思源受管工作区

通过 SiYuan HTTP API 访问本地思源笔记。使用环境变量配置 endpoint、token 和唯一可写笔记本。

安全边界

• 可以搜索、查看、读取全部思源笔记本。
• 只能写入 managedNotebook，由 SIYUAN_MANAGED_NOTEBOOK_ID 指定。
• 其他 notebook 全部视为 readonly，不能创建、更新、追加、前置追加或删除。
• 所有写入工具必须通过 PermissionGuard 做代码层权限检查。
• 对已有 block/doc 写入前必须实时调用 /api/filetree/getPathByID 反查 notebook；无法判断归属时 fail closed。
• 不能修改 readonly notebook。用户要求修改只读内容时，只能返回修改建议，或复制到 managedNotebook 后再编辑。
• 不能使用 SQL。
• 不能使用 fullTextSearchBlock method=2。
• 不能做笔记本级删除、重命名或配置变更。
• 不能做文档或块移动类操作。
• 删除必须 confirm=true 才真实执行；默认只返回 dry-run 预览。
• token 只能从环境变量读取，不得写入源码、文档示例、测试快照或日志。

工具

只实现以下 WorkBuddy tools：

• siyuan_health_check
• siyuan_list_notebooks
• siyuan_search
• siyuan_read_block
• siyuan_create_doc
• siyuan_update_block
• siyuan_append_block
• siyuan_prepend_block
• siyuan_delete_block
• siyuan_copy_readonly_to_managed

操作规则

读取类工具允许访问所有 notebook。返回结果必须标注 managed | readonly 或 writable | readonly。

创建文档时只使用 SIYUAN_MANAGED_NOTEBOOK_ID，路径必须以 / 开头，禁止 ../ 和 //，同路径已存在时返回 existingDoc，不覆盖。

更新、追加、前置追加和删除 block 前，必须调用 PermissionGuard.assertWritableTarget(id)。该方法必须实时反查 notebook，不能只依赖缓存。

删除工具必须先读取待删除内容和路径用于预览；confirm=false 不调用真实删除接口。

搜索固定使用普通全文搜索模式，禁止切换到危险搜索模式。

错误返回

失败时返回统一结构：

{
  "ok": false,
  "errorCode": "READONLY_NOTEBOOK",
  "message": "该内容所属笔记本为只读范围，Skill 不允许直接修改。",
  "details": {},
  "suggestion": "可以生成修改建议，或复制到 AI 工作台后再编辑。",
  "requestId": "..."
}