From 49ab53ea0da025f5994d8da7ebb1e2277b37d892 Mon Sep 17 00:00:00 2001 From: liyuan Date: Fri, 21 Aug 2026 14:29:05 +0800 Subject: [PATCH] =?UTF-8?q?=E8=AF=84=E5=AE=A1=E9=97=AE=E9=A2=98=E4=BF=AE?= =?UTF-8?q?=E5=A4=8D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../doc-read-public-and-history-version.md | 6 ++++-- internal/cli/param_aliases_generated.go | 2 +- internal/shortcut/doc/content_shortcuts.go | 20 +++++++++++-------- internal/shortcut/doc/doc_shortcuts_test.go | 11 +++++----- skills/multi/dingtalk-doc/references/doc.md | 2 +- .../dingtalk-doc/references/doc/doc-read.md | 6 +++--- 6 files changed, 27 insertions(+), 20 deletions(-) diff --git a/.changes/doc-read-public-and-history-version.md b/.changes/doc-read-public-and-history-version.md index 95dec203..b04e979d 100644 --- a/.changes/doc-read-public-and-history-version.md +++ b/.changes/doc-read-public-and-history-version.md @@ -7,5 +7,7 @@ category: Added and `historyVersion` (read content as of a listed historical version; `0` denotes the document's initial version) parameters on the markdown, JSONML, and scope read paths via `--password` / `--version`; `dws doc +fetch` gains - `--password` and replaces its previous hard rejection of `--revision` with - validated forwarding to `get_document_content.historyVersion`. + `--password` and `--version` with the same `historyVersion` forwarding, while + `--revision` stays rejected with explicit guidance: revision is the document + edit revision returned by JSONML reads for `+update --expected-revision` + conditional writes, not a historical version number. diff --git a/internal/cli/param_aliases_generated.go b/internal/cli/param_aliases_generated.go index f5dcc0c1..4451679c 100644 --- a/internal/cli/param_aliases_generated.go +++ b/internal/cli/param_aliases_generated.go @@ -3765,7 +3765,7 @@ var generatedParamAliases = []ParamAliasEntry{ "start-block": "start-block-id", "url": "node", }, - Blocked: []string{"comment-id", "comment-key", "content-format", "dentry-id", "doc-format", "folder", "folder-id", "id", "job-id", "name", "parent-id", "range", "role", "space-id", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"comment-id", "comment-key", "content-format", "dentry-id", "doc-format", "folder", "folder-id", "id", "job-id", "name", "parent-id", "range", "role", "space-id", "task-id", "template-id", "workspace", "workspace-id"}, Ambiguous: []string{"block-id"}, }, { diff --git a/internal/shortcut/doc/content_shortcuts.go b/internal/shortcut/doc/content_shortcuts.go index 00c55b47..72d071da 100644 --- a/internal/shortcut/doc/content_shortcuts.go +++ b/internal/shortcut/doc/content_shortcuts.go @@ -176,17 +176,17 @@ var Fetch = shortcut.Shortcut{ Command: "+fetch", Product: productDoc, Description: "读取完整或局部文档内容，并按 detail 控制保真度", - Intent: "当用户要按 node/URL 直接读取在线文字文档，或只知道唯一标题并希望一次完成解析和读取时使用；支持 outline/range/section/keyword/tags 局部内容用于精确编辑和评论；互联网公开文档（含密码保护）用 --password 提供访问密码，读历史版本用 --revision 指定版本号（0 表示初始版本）。", + Intent: "当用户要按 node/URL 直接读取在线文字文档，或只知道唯一标题并希望一次完成解析和读取时使用；支持 outline/range/section/keyword/tags 局部内容用于精确编辑和评论；互联网公开文档（含密码保护）用 --password 提供访问密码，读历史版本用 --version 指定版本号（0 表示初始版本）。", Risk: shortcut.RiskRead, Safety: contract.SafetySpec{Effect: "read", Risk: "low", Confirmation: "not_required", Idempotency: "idempotent"}, Contract: docContract( "+fetch", "读取完整或局部文档内容，并按 detail 控制保真度", - "当用户要按 node/URL 直接读取在线文字文档，或只知道唯一标题并希望一次完成解析和读取时使用；支持 outline/range/section/keyword/tags 局部内容用于精确编辑和评论；互联网公开文档（含密码保护）用 --password 提供访问密码，读历史版本用 --revision 指定版本号（0 表示初始版本）。", + "当用户要按 node/URL 直接读取在线文字文档，或只知道唯一标题并希望一次完成解析和读取时使用；支持 outline/range/section/keyword/tags 局部内容用于精确编辑和评论；互联网公开文档（含密码保护）用 --password 提供访问密码，读历史版本用 --version 指定版本号（0 表示初始版本）。", []string{`dws doc +fetch --node `, `dws doc +fetch --query "项目周报" --scope keyword --keyword "结论"`}, contract.ParamDecl{Name: "node", Property: "nodeId"}, contract.ParamDecl{Name: "query", Property: "keyword"}, contract.ParamDecl{Name: "password", Property: "password"}, - contract.ParamDecl{Name: "revision", Property: "historyVersion"}, + contract.ParamDecl{Name: "version", Property: "historyVersion"}, ), Flags: []shortcut.Flag{ {Name: "node", Type: shortcut.FlagString, Desc: "文档 ID 或 URL；" + fetchTargetConstraint}, @@ -201,12 +201,16 @@ var Fetch = shortcut.Shortcut{ {Name: "context-after", Type: shortcut.FlagInt, Desc: "关键词命中后的上下文字符数"}, {Name: "max-depth", Type: shortcut.FlagInt, Desc: "outline/section 最大深度"}, {Name: "password", Type: shortcut.FlagString, Desc: "互联网公开文档开启密码保护时的访问密码；普通文档无需传入"}, - {Name: "revision", Type: shortcut.FlagInt, Desc: "读取指定历史版本(版本号从 doc +version-list 获取, 0 表示初始版本, 需要文档编辑权限)；缺省读最新版"}, + {Name: "revision", Type: shortcut.FlagInt, Desc: "不支持；revision 是文档编辑版本号（JSONML 读取响应返回、供 +update --expected-revision 条件写使用），不是历史版本号"}, + {Name: "version", Type: shortcut.FlagInt, Desc: "读取指定历史版本(版本号从 doc +version-list 获取, 0 表示初始版本, 需要文档编辑权限)；缺省读最新版"}, }, Tips: []string{`dws doc +fetch --node `, `dws doc +fetch --query "项目周报" --scope keyword --keyword "结论"`}, Validate: func(rt *shortcut.RuntimeContext) error { - if rt.Changed("revision") && rt.Int("revision") < 0 { - return apperrors.NewValidation("--revision 必须为非负整数历史版本号（0 表示初始版本，从 doc +version-list 获取）") + if rt.Changed("revision") { + return apperrors.NewValidation("--revision 不支持：revision 是文档编辑版本号（doc read --content-format jsonml 响应返回，供 doc +update --expected-revision 条件写使用），不是历史版本号；读历史版本请用 --version") + } + if rt.Changed("version") && rt.Int("version") < 0 { + return apperrors.NewValidation("--version 必须为非负整数历史版本号（0 表示初始版本，从 doc +version-list 获取）") } if rt.Str("scope") == "keyword" && rt.Str("keyword") == "" { return apperrors.NewValidation("--scope keyword 时必须提供 --keyword") @@ -243,8 +247,8 @@ var Fetch = shortcut.Shortcut{ if rt.Changed("max-depth") { params["maxDepth"] = rt.Int("max-depth") } - if rt.Changed("revision") { - params["historyVersion"] = rt.Int("revision") + if rt.Changed("version") { + params["historyVersion"] = rt.Int("version") } if value := rt.Str("password"); value != "" { params["password"] = value diff --git a/internal/shortcut/doc/doc_shortcuts_test.go b/internal/shortcut/doc/doc_shortcuts_test.go index 1206bd10..975ece10 100644 --- a/internal/shortcut/doc/doc_shortcuts_test.go +++ b/internal/shortcut/doc/doc_shortcuts_test.go @@ -1072,7 +1072,8 @@ func TestCrossPlatformCoverageDocContentValidationAndPureHelpers(t *testing.T) { {Create, []string{"--name", "n", "--content", `{}`, "--doc-format", "jsonml"}}, {Create, []string{"--name", "n", "--content", `[]`, "--doc-format", "jsonml"}}, {Create, []string{"--name", "n", "--content", `[["p",{},"x"]]`, "--doc-format", "jsonml"}}, - {Fetch, []string{"--node", "n", "--revision", "-2"}}, + {Fetch, []string{"--node", "n", "--revision", "7"}}, + {Fetch, []string{"--node", "n", "--version", "-2"}}, {Fetch, []string{"--node", "n", "--scope", "keyword"}}, {Update, []string{"--node", "n"}}, {Update, []string{"--command", "append", "--content", "x", "--yes"}}, @@ -1104,7 +1105,7 @@ func TestCrossPlatformCoverageDocContentValidationAndPureHelpers(t *testing.T) { } fetchAccess := &docCoverageCaller{} - if err := runDocCoverage(t, Fetch, fetchAccess, "--node", "n", "--revision", "7", "--password", "pw"); err != nil { + if err := runDocCoverage(t, Fetch, fetchAccess, "--node", "n", "--version", "7", "--password", "pw"); err != nil { t.Fatalf("fetch with access params failed: %v", err) } if len(fetchAccess.history) != 1 || @@ -1115,13 +1116,13 @@ func TestCrossPlatformCoverageDocContentValidationAndPureHelpers(t *testing.T) { } fetchZero := &docCoverageCaller{} - if err := runDocCoverage(t, Fetch, fetchZero, "--node", "n", "--revision", "0"); err != nil { - t.Fatalf("fetch with zero revision failed: %v", err) + if err := runDocCoverage(t, Fetch, fetchZero, "--node", "n", "--version", "0"); err != nil { + t.Fatalf("fetch with zero version failed: %v", err) } if len(fetchZero.history) != 1 || fetchZero.history[0].tool != "get_document_content" || fetchZero.history[0].params["historyVersion"] != 0 { - t.Fatalf("fetch zero revision (initial version) was not forwarded: %#v", fetchZero.history) + t.Fatalf("fetch zero version (initial version) was not forwarded: %#v", fetchZero.history) } for _, value := range []any{ diff --git a/skills/multi/dingtalk-doc/references/doc.md b/skills/multi/dingtalk-doc/references/doc.md index 9c7ed952..6ec6b8bf 100644 --- a/skills/multi/dingtalk-doc/references/doc.md +++ b/skills/multi/dingtalk-doc/references/doc.md @@ -48,7 +48,7 @@ dws doc +version-revert --node --version --format json `+version-save/list/revert` 分别用于快照、浏览和恢复，命中后直接执行，不预读 Help。`+history-*` 仅兼容已有调用，不用于新的 Agent 选路。重要内容更新优先使用 `+checkpoint-update`，不要手工编排保存、写入和回读。回滚必须确认，以 leaf Schema 与 Runtime gate 为准。 -只读某个历史版本的内容而不回滚时，用 `dws doc +fetch --node --revision `（版本号同样来自 `+version-list`，`0` 表示初始版本，需要文档编辑权限）；不要为了看历史内容而执行回滚。互联网公开文档（含密码保护）的读取见 [doc-read.md](doc/doc-read.md) 的 `--password`。 +只读某个历史版本的内容时，用 `dws doc +fetch --node --version `（版本号同样来自 `+version-list`，`0` 表示初始版本，需要文档编辑权限）；整体恢复到历史版本才用 `+version-revert`（危险操作，需确认）。互联网公开文档（含密码保护）的读取见 [doc-read.md](doc/doc-read.md) 的 `--password`。 ## 权限与分享 diff --git a/skills/multi/dingtalk-doc/references/doc/doc-read.md b/skills/multi/dingtalk-doc/references/doc/doc-read.md index 2fe6b330..93b9bae6 100644 --- a/skills/multi/dingtalk-doc/references/doc/doc-read.md +++ b/skills/multi/dingtalk-doc/references/doc/doc-read.md @@ -6,7 +6,7 @@ dws doc +fetch --node --format json dws doc +fetch --query "项目周报" --scope keyword --keyword "结论" --format json dws doc +fetch --node --password --format json -dws doc +fetch --node --revision --format json +dws doc +fetch --node --version --format json ``` - 已知 ID 或 URL：传 `--node`。 @@ -17,9 +17,9 @@ dws doc +fetch --node --revision --format json ## 互联网公开文档与历史版本 - **互联网公开文档**：公开链接直接传 `--node`；文档开启了密码保护时，通过 `--password ` 提供访问密码，普通文档无需传入。密码只进入读取请求，不会回显在读取结果里（`--dry-run` 预览会包含所传参数，注意输出环境）。 -- **历史版本**：`--revision ` 读取指定历史版本内容；版本号从 `dws doc +version-list` 获取，`0` 表示文档初始版本，需要文档编辑权限（EDITOR 及以上）；缺省读最新版。 +- **历史版本**：`--version ` 读取指定历史版本内容；版本号从 `dws doc +version-list` 获取，`0` 表示文档初始版本，需要文档编辑权限（EDITOR 及以上）；缺省读最新版。注意区分：`revision` 是文档编辑版本号（JSONML 读取响应返回、供 `+update --expected-revision` 条件写使用），不是历史版本号，`+fetch` 不支持 `--revision`。 - **跨组织文档**：非互联网公开的跨组织文档，`+fetch` 整体被组织边界拦截（提示「不支持跨组织访问数据」），最新版与历史版本内容都读不到；互联网公开（含密码）文档的 `+fetch` 不受影响，但 `+version-list` 与写操作仍会被拦截，版本号无法从列表获取。 -- 只要看历史内容、不打算恢复时用 `--revision`；要把文档整体恢复到历史版本才用 `+version-revert`（危险操作，需确认）。 +- 只要看历史内容、不打算恢复时用 `--version`；要把文档整体恢复到历史版本才用 `+version-revert`（危险操作，需确认）。 ## 局部读取