siyuan-plugins-mcp-sisyphus: Instructions file for Codex

SiYuan MCP Sisyphus —— AI 编码代理项目指南

本文档面向 AI 编码代理。阅读者应对本项目一无所知，所有信息均基于实际代码与配置，不假设、不泛化。

---

项目概述

SiYuan MCP Sisyphus 是 SiYuan Note（思源笔记）的插件 + 独立 CLI 工具，让 AI Agent 能够通过两种接口安全地操作思源笔记：

1. MCP Server 插件：作为 SiYuan 插件运行，对外暴露 MCP（Model Context Protocol）服务。AI 客户端（Claude Desktop、Cursor、Cherry Studio 等）通过 HTTP 或 stdio 连接。
2. 独立 CLI siyuan-sisyphus：发布到 npm 的包名 siyuan-sisyphus，安装后提供 siyuan-sisyphus / siyuan 命令。直接通过思源 HTTP API 执行单次操作后退出，无需 MCP 客户端。

两种接口共享同一套底层能力，覆盖思源绝大部分功能：笔记本管理、文档操作、块级读写、属性视图（数据库）、搜索、标签、文件资源、闪卡、系统接口等。聚合工具类别和静态 action 清单以 src/core/config.ts 的 TOOL_CATEGORIES 与 ACTIONS_BY_CATEGORY 为唯一事实来源；extension 还可按官方注册表发现动态 action。

• 仓库地址：https://github.com/yangtaihong59/siyuan-plugins-mcp-sisyphus
• 作者：Taihong Yang
• 许可证：MIT
• 当前版本：0.6.1（根 package.json 与 plugin.json 同步）

---

技术栈

层级	技术
语言	TypeScript 5.1+
构建工具	Vite 5.2+（多 target 构建）
UI 框架	Svelte 4（插件设置面板、桌面悬浮宠物组件）
校验	Zod 4（action 参数校验）
MCP SDK	@modelcontextprotocol/{server,client,core,node} ^2.0.0
测试	Vitest 1.6+（Node 环境）
文档	VitePress 1.6+（docs/ 双语站点）
包管理	pnpm（推荐）

关键约束：

• 所有产物为 CommonJS (CJS)。
• 插件在 Electron 渲染进程以 CJS 运行；MCP Server 以 Node 进程运行；CLI 为自包含 CJS bundle。
• 必须兼容远程场景：任何读写操作都经过思源 HTTP API（http://127.0.0.1:6806 或用户配置地址），禁止直接访问本地文件系统。特许例外仅有两处：① CLI 自身配置（~/.siyuan-sisyphus/config.json）；② 上传/下载/导出类 action（如 upload_asset、export_resources），因 SiYuan API 不支持流式二进制传输，必须通过本地文件系统中转。

---

项目结构

siyuan-plugins-mcp-sisyphus/
├── src/
│   ├── index.ts                 # 插件入口（SiYuan Plugin 基类）
│   ├── server-launcher.ts       # HttpServerLauncher：在插件进程内 spawn mcp-server.cjs 子进程
│   ├── index.scss               # 插件全局样式（几乎为空）
│   │
│   ├── api/                     # 思源 HTTP API 封装层
│   │   ├── client.ts            # SiYuanClient：fetch 封装、token 注入、超时控制
│   │   ├── notebook.ts          # /api/notebook/*
│   │   ├── document.ts          # /api/filetree/* 与文档相关
│   │   ├── block.ts             # /api/block/*
│   │   ├── av.ts                # /api/av/*（attribute view / 数据库）
│   │   ├── search.ts            # /api/search/*、/api/query/sql
│   │   ├── file.ts              # /api/file/*、/api/export/*、/api/asset/*
│   │   ├── system.ts            # /api/system/*
│   │   ├── tag.ts               # /api/tag/*
│   │   ├── flashcard.ts         # /api/riff/*
│   │   └── transaction.ts       # /api/transaction 批量操作
│   │
│   ├── core/                    # MCP 服务器核心与工具元数据
│   │   ├── server.ts            # MCP Server 入口：createSiYuanServer()、startMcpServer()
│   │   ├── http-transport.ts    # HTTP MCP 2026 无状态 + legacy 有会话双协议传输
│   │   ├── tool-registry.ts     # TOOL_REGISTRY：聚合工具注册表
│   │   ├── tool-lifecycle.ts    # 工具调用生命周期：analytics、telemetry、token 计数、错误包装
│   │   ├── config.ts            # ToolConfig 类型、默认值、配置迁移（扁平 → 嵌套）、危险动作定义
│   │   ├── permissions.ts       # PermissionManager：笔记本级权限（rwd/rw/r/none）
│   │   ├── types.ts             # 所有 action 的 Zod schema 定义
│   │   ├── resources.ts         # MCP Resources：help 文档资源路由
│   │   ├── help.ts              # 各工具的帮助文案与提示
│   │   ├── normalize.ts         # 请求参数归一化（类型短码展开、sortBy 别名等）
│   │   ├── analytics.ts         # 调用统计与洞察数据聚合
│   │   ├── telemetry.ts         # 调用事件遥测上报
│   │   ├── token-usage.ts       # 请求/响应近似 token 计算
│   │   ├── puppy-state.ts       # 桌面悬浮宠物（ToolPuppy）状态管理
│   │   ├── server-instructions.ts # 服务端 instructions 文本构建
│   │   └── runtime.ts           # 运行时环境检测（isPluginMode 等）
│   │
│   ├── tools/                   # 聚合工具的实现
│   │   ├── index.ts             # barrel export：统一导出所有工具模块
│   │   ├── internal/            # 工具层共享基础设施（非独立工具）
│   │   │   ├── define-tool.ts   # defineTool() 工厂：统一工具定义模式
│   │   │   ├── shared.ts        # 聚合工具公共函数：schema 构建、结果包装、分页、错误翻译
│   │   │   ├── context.ts       # 工具上下文辅助（权限校验、子文档查询等）
│   │   │   ├── errorTranslation.ts # 思源错误码 → 用户友好文案
│   │   │   ├── ui-refresh.ts    # 触发思源 UI 刷新（所有模式默认开启）
│   │   │   ├── help-render.ts   # help action 输出渲染
│   │   │   ├── schema-analyzer.ts # schema 分析与描述裁剪
│   │   │   └── helpers/         # 跨工具小型 helper，如 notebookName 补全
│   │   ├── notebook/            # notebook 工具（index.ts + handlers.ts）
│   │   ├── document/            # document 工具
│   │   ├── block/               # block 工具
│   │   ├── av/                  # av（数据库）工具
│   │   ├── search/              # search 工具（含 sql-builder、permission-filter）
│   │   ├── file/                # file 工具
│   │   ├── tag/                 # tag 工具
│   │   ├── system/              # system 工具
│   │   ├── flashcard/           # flashcard 工具
│   │   └── mascot/              # mascot（吉祥物余额）工具
│   │
│   ├── cli/                     # 独立 CLI 源码（被 cli Vite target 打包）
│   │   ├── index.ts             # CLI 入口：命令分发（dispatch/list/help/init/config/version）
│   │   ├── dispatch.ts          # 核心转发：调 TOOL_REGISTRY[tool].callTool()
│   │   ├── args.ts              # 顶层参数解析：支持 kebab/camel/snake flag 混用
│   │   ├── flag-mapper.ts       # 基于 inputSchema 做 flag → 参数映射与类型强转
│   │   ├── render.ts            # 人类可读渲染 / --json 紧凑输出 / ANSI 颜色 / 交互式分页
│   │   ├── list-help.ts         # list 与 help 子命令实现
│   │   ├── config.ts            # 配置读写（~/.siyuan-sisyphus/config.json）
│   │   ├── config-command.ts    # config 子命令：多 profile 管理（list/get/set/use）
│   │   ├── init.ts              # 交互式初始化
│   │   ├── plugin-check.ts      # 插件在线检测
│   │   └── runtime.ts           # CLI 运行时环境检测
│   │
│   ├── ui/                      # Svelte UI 与设置面板
│   │   ├── components/          # 桌面悬浮宠物组件与行为逻辑
│   │   ├── setting/             # 插件设置面板
│   │   └── shared/              # UI 共享组件
│   │
│   ├── shared/                  # 跨层通用工具库
│   │   ├── error.ts             # 错误处理辅助
│   │   ├── promise-pool.ts      # 并发池
│   │   └── invocation-format.ts # 调用格式化
│   │
│   ├── types/
│   │   ├── index.d.ts           # 思源常用数据结构（Block、Notebook 等）
│   │   └── api.d.ts             # API 响应类型定义
│   │
│   └── presentation/            # 展示层辅助
│       └── invocation-format.ts # 调用格式化
│
├── cli/                         # 独立 npm 子包（发布为 `siyuan-sisyphus`）
│   ├── package.json             # 子包元数据（version 与根包独立，bin 指向 dist/cli.cjs）
│   ├── README.md / README_zh_CN.md
│   └── dist/                    # CLI 构建产物 cli.cjs（自包含，无外部依赖）
│
├── tests/                       # 测试套件
│   ├── setup.ts                 # Vitest 全局 setup：fetch mock 恢复、vi.restoreAllMocks
│   ├── unit/                    # 单元测试（按 src 目录结构镜像）
│   ├── integration/             # 集成测试（HTTP 并发、端到端 MCP、server 启动）
│   ├── smoke/                   # 冒烟测试（需真实思源实例）
│   ├── mocks/siyuan.ts          # `siyuan` 模块 mock（用于 vitest alias）
│   └── helpers/                 # 测试辅助函数
│
├── docs/                        # VitePress 文档站点（双语：en / zh）
│   ├── .vitepress/config.ts     # VitePress 配置
│   ├── en/                      # 英文文档
│   └── zh/                      # 中文文档
│
├── scripts/                     # 构建与开发辅助脚本
│   ├── make_dev_link.js         # 创建 dev 目录到思源插件目录的符号链接
│   ├── make_install.js          # 构建后安装到思源插件目录
│   ├── update_version.js        # 同步 version 到 plugin.json 与 cli/package.json
│   ├── analyze-description-tokens.ts # 工具描述 token 分析
│   └── repro-index-error*.cjs   # 索引问题复现脚本
│
├── public/i18n/                 # 国际化源文件（JSON 格式，build 时自动复制到 dist）
│   ├── en_US.json
│   └── zh_CN.json
│
├── dist/                        # 生产构建输出（自动生成）
├── dev/                         # 我测试时插件实际上运行的输出，开发模式输出（pnpm dev 时生成）
│
├── package.json                 # 根包（插件本体）
├── plugin.json                  # 思源插件元数据
├── vite.config.ts               # Vite 多入口配置（renderer / server / cli）
├── vitest.config.ts             # Vitest 测试配置
├── tsconfig.json                # TypeScript 配置（strict: false，路径别名 @/*）
├── svelte.config.js             # Svelte 配置（vitePreprocess，压制 a11y 警告）
└── yaml-plugin.js               # 自定义 Vite 插件：YAML i18n → JSON 转换