siyuan-sisyphus 0.2.6 → 0.2.10

package/README.md

@@ -6,7 +6,9 @@
 
 Direct command-line control for [SiYuan Note](https://b3log.org/siyuan). Think of it like `obsidian-cli` but for SiYuan — every MCP tool (fs, block, document, notebook, av, search, tag, file, timeline, system, flashcard, extension, mascot, feedback) is exposed as a subcommand you can call directly from a shell.
 
-> **Latest:** `v0.2.6` exposes the expanded guarded AV, snapshot, image-audit, image-reading, extension-diagnostic, and link-resolution workflows, and preserves mixed text/image results in JSON output. Thanks to [@LoneFireBlossom](https://github.com/LoneFireBlossom) for [PR #48](https://github.com/yangtaihong59/siyuan-plugins-mcp-sisyphus/pull/48) and PRs #50–#56, [@ray24777](https://github.com/ray24777) for [PR #57](https://github.com/yangtaihong59/siyuan-plugins-mcp-sisyphus/pull/57), and [@adminclaw](https://github.com/adminclaw) for [PR #58](https://github.com/yangtaihong59/siyuan-plugins-mcp-sisyphus/pull/58).
+> **Latest:** `v0.2.10` fixes false readback failures after document deletion and misleading asset-reference errors, and includes the shared tool-help improvements.
+
+> **v0.2.6:** `v0.2.6` exposes the expanded guarded AV, snapshot, image-audit, image-reading, extension-diagnostic, and link-resolution workflows, and preserves mixed text/image results in JSON output. Thanks to [@LoneFireBlossom](https://github.com/LoneFireBlossom) for [PR #48](https://github.com/yangtaihong59/siyuan-plugins-mcp-sisyphus/pull/48) and PRs #50–#56, [@ray24777](https://github.com/ray24777) for [PR #57](https://github.com/yangtaihong59/siyuan-plugins-mcp-sisyphus/pull/57), and [@adminclaw](https://github.com/adminclaw) for [PR #58](https://github.com/yangtaihong59/siyuan-plugins-mcp-sisyphus/pull/58).
 
 > **For AI models and coding agents:** before doing any SiYuan work with this CLI, run `siyuan-sisyphus skill install` first. The bundled skills provide the task-specific operating rules for safe search, reading, editing, export, database, tag, flashcard, timeline, and system workflows.
 
@@ -27,10 +29,16 @@ siyuan-sisyphus search fulltext --query "keyword" --page-size 10 --json | jq '.d
 
 ## Strict safe writes
 
-Strict safe writes are enabled by default in the plugin under Settings → MCP → Settings & Debug. Mutation commands first run the action with `validateOnly=true`, then submit a fresh UUIDv7 `requestId` and the returned `expected*Hash`. The returned value is a temporary in-memory lease credential, normally beginning with four hexadecimal characters; it is never used as a 16-bit state comparison because the HTTP coordinator resolves it to the leased full SHA-256 and compares that full hash with a fresh read before writing.
+Strict safe writes are enabled by default in the plugin under Settings → MCP → Settings & Debug. Mutation commands first run the action with `validateOnly=true`, then copy the server-issued `requestId` and the returned `expected*Hash` (when present) unchanged; additive actions also require preflight to obtain a request ID. The returned value is a temporary in-memory lease credential, normally beginning with four hexadecimal characters; it is never used as a 16-bit state comparison because the HTTP coordinator resolves it to the leased full SHA-256 and compares that full hash with a fresh read before writing.
 
 Keep the plugin-hosted MCP HTTP server enabled while using strict CLI mutations. The CLI forwards these writes to that single coordinator so CLI, stdio, and HTTP do not create independent lease pools. Expired, consumed, or restart-invalidated leases require a new preflight. Turning strict writes off restores the legacy direct-call contract without hash concurrency checks, request idempotency, or post-write verification.
 
+Request IDs and state credentials start at four hexadecimal characters. Copy them completely; do not generate or truncate them. Upgrade the plugin to v0.6.9 alongside this CLI and obtain fresh preflight credentials. The legacy AV `id` input remains accepted with a deprecation warning; use `avID` for new calls.
+
+`feedback.submit` is an external operation: after user authorization, submit business parameters directly without `validateOnly`, `requestId`, or hash credentials. A mistaken preflight sends nothing and returns a hint. Feedback does not provide strict state verification or idempotent replay; do not automatically retry an unknown outcome.
+
+Clients without MCP Resources can run `siyuan-sisyphus av help --topic ai-layout-guide` for the complete layout guide.
+
 ## Install
 
 ```bash
@@ -79,6 +87,7 @@ siyuan-sisyphus list [tool]                          List tools or a tool's acti
 siyuan-sisyphus help <tool> [action]                 Detailed help for a tool or action
 siyuan-sisyphus init                                 Interactive config setup
 siyuan-sisyphus config list|get|set|use ...          Manage saved SiYuan profiles
+siyuan-sisyphus instances                            List running local SiYuan kernel APIs
 siyuan-sisyphus skill list|read|install [--bundle cli|mcp|all]
                                                      Inspect or install agent skills
 siyuan-sisyphus --help | -h                          Top-level help
@@ -215,6 +224,16 @@ If you already used the older config path `~/.siyuan-mcp/config.json`, the CLI s
 
 The CLI respects the same plugin UI configuration as MCP clients: disabled tools/actions are hidden from `list`/`help` and cannot be executed. Notebook-level permissions are also enforced by reading the same `/data/storage/petal/...` configuration through the API.
 
+## File transfer with the kernel endpoint
+
+With the kernel coordinator enabled, `file upload_asset --local-file-path ...` automatically stages bytes before strict preflight/commit. Copy the issued requestId and expectedSourceHash from `--validate-only`. Uploads are capped at 10 MiB and staged for 10 minutes. Preflight also returns uploadSource for replay without reading a local file; supply exactly one source. Changed files require new preflight.
+
+`file export_resources --paths-json '["assets/example.png"]' --output-path ./export.zip` and `file extract_doc --id <document-ID> --output-dir ./exports` download and save locally, reporting SHA-256. Existing destinations are refused and siblings preserved. Exports remain external side effects without strict write guarantees; validateOnly does not execute.
+
+Kernel delegation supports cooperative Ctrl-C cancellation: stop before commit; once commit starts, wait for its real outcome. Downloads stream to disk with incremental SHA-256 and clean partial output on cancellation/failure (512 MiB export limit; 120 seconds per file). Uploads reuse matching kernel-verified staging via fingerprint lookup.
+
+Kernel delegation assigns a transport taskId. On a lost response, the CLI queries that task’s short-lived cached result without repeating the business call. If recovery is unavailable, outcome_unknown includes taskId; reconcile using the original business requestId. Ordinary kernel read actions have an aggregate budget of 128 API calls / 8 MiB; narrow queries or use smaller pages when read_budget_exceeded is returned.
+
 ## License
 
 MIT © Taihong Yang