github/dingtalk-workspace-cli
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #1078 from liyuan333/feat/doc-read-public-and-history-version

Browse Source 
feat(doc): read password-protected public docs and historical versions
This commit is contained in:
github-actions[bot]
2026-08-21 17:19:39 +08:00
committed by GitHub
parent 35c6fd95e1 8312c4f30e
commit 74b7690cbb
13 changed files with 243 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.changes/doc-read-public-and-history-version.md
+13
View File
@@ -0,0 +1,13 @@
---
category: Added
---
- **Doc public-link and historical-version reads** — `dws doc read` forwards
the reviewed `password` (internet-public documents with password protection)
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 `--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.
internal/cli/param_aliases_generated.go
+2 -2
View File
@@ -4243,7 +4243,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"},
},
{
@@ -4859,7 +4859,7 @@ var generatedParamAliases = []ParamAliasEntry{
"output-path": "output",
"save-path": "output",
},
Blocked: []string{"before-block-id", "comment-id", "comment-key", "content-file", "dentry-id", "file", "file-path", "folder", "folder-id", "job-id", "name", "parent-block-id", "parent-id", "ref-block-id", "reference-block-id", "revision", "role", "space-id", "task-id", "template-id", "version", "workspace", "workspace-id"},
Blocked: []string{"before-block-id", "comment-id", "comment-key", "content-file", "dentry-id", "file", "file-path", "folder", "folder-id", "job-id", "name", "parent-block-id", "parent-id", "ref-block-id", "reference-block-id", "revision", "role", "space-id", "task-id", "template-id", "workspace", "workspace-id"},
Ambiguous: []string{"block-id"},
},
{
internal/cli/schema_catalog_test.go
+10 -1
View File
@@ -301,7 +301,7 @@ func TestDeliveryCatalogDocReadParamDeclsMatchMergeBaseContract(t *testing.T) {
t.Fatalf("doc read --content-format required = %#v, want false", contentFormat["required"])
}
for _, flagName := range []string{"scope", "tags", "max-depth", "start-block-id", "end-block-id"} {
for _, flagName := range []string{"scope", "tags", "max-depth", "start-block-id", "end-block-id", "version", "password"} {
if parameters[flagName]["required"] != false {
t.Fatalf("doc read --%s required = %#v, want false", flagName, parameters[flagName]["required"])
}
@@ -315,6 +315,15 @@ func TestDeliveryCatalogDocReadParamDeclsMatchMergeBaseContract(t *testing.T) {
if parameters["max-depth"]["type"] != "integer" {
t.Fatalf("doc read --max-depth type = %#v, want integer", parameters["max-depth"]["type"])
}
if got := parameters["version"]["property"]; got != "historyVersion" {
t.Fatalf("doc read --version property = %#v, want historyVersion", got)
}
if parameters["version"]["type"] != "integer" {
t.Fatalf("doc read --version type = %#v, want integer", parameters["version"]["type"])
}
if got := parameters["password"]["property"]; got != "password" {
t.Fatalf("doc read --password property = %#v, want password", got)
}
}
func TestDeliveryCatalogDocCommentParamDeclsMatchMergeBaseContract(t *testing.T) {
internal/helpers/doc.go
+48 -10
View File
@@ -1429,9 +1429,14 @@ func newDocCommand() *cobra.Command {
readCmd := &cobra.Command{
Use: "read",
Short: "读取文档内容 (Markdown)",
Long: `获取文档内容，以 Markdown 格式返回。支持传入文档 URL 或 ID。`,
Long: `获取文档内容，以 Markdown 格式返回。支持传入文档 URL 或 ID。
互联网公开文档（含开启密码保护的）可传入公开链接；设置了访问密码时通过 --password 提供。
--version 读取指定历史版本内容（版本号从 dws doc version list 获取，0 表示文档初始版本，需要文档编辑权限）；缺省读最新版。`,
Example: ` dws doc read --node DOC_ID
dws doc read --node "https://alidocs.dingtalk.com/i/nodes/<DOC_UUID>"`,
dws doc read --node "https://alidocs.dingtalk.com/i/nodes/<DOC_UUID>"
dws doc read --node PUBLIC_URL --password <ACCESS_PASSWORD>
dws doc read --node DOC_ID --version 3`,
RunE: func(cmd *cobra.Command, args []string) error {
nodeID, err := mustFlagOrFallback(cmd, "node", "url", "id", "node-id", "doc-id", "file-id")
if err != nil {
@@ -1441,6 +1446,15 @@ func newDocCommand() *cobra.Command {
"dws doc read --node DOC_ID --content-format jsonml"); err != nil {
return err
}
password, _ := cmd.Flags().GetString("password")
historyVersion := 0
historyVersionSet := cmd.Flags().Changed("version")
if historyVersionSet {
historyVersion, _ = cmd.Flags().GetInt("version")
if historyVersion < 0 {
return fmt.Errorf("--version 必须为非负整数历史版本号（0 表示初始版本，版本号从 dws doc version list 获取），当前值: %d", historyVersion)
}
}
format, _ := cmd.Flags().GetString("content-format")
scope, _ := cmd.Flags().GetString("scope")
tags, _ := cmd.Flags().GetString("tags")
@@ -1481,15 +1495,18 @@ func newDocCommand() *cobra.Command {
startBlockID,
endBlockID,
outputPath,
password,
historyVersion,
historyVersionSet,
)
}
if format == "jsonml" {
outputPath, _ := cmd.Flags().GetString("output")
return runDocReadJsonML(cmd, nodeID, outputPath)
return runDocReadJsonML(nodeID, outputPath, password, historyVersion, historyVersionSet)
}
return callMCPTool("get_document_content", map[string]any{
"nodeId": nodeID,
})
toolArgs := map[string]any{"nodeId": nodeID}
applyDocReadAccessParams(toolArgs, password, historyVersion, historyVersionSet)
return callMCPTool("get_document_content", toolArgs)
},
}
DeclareLeafMetadata(readCmd, LeafSpec{
@@ -1516,6 +1533,8 @@ func newDocCommand() *cobra.Command {
UseWhen: []string{
"用户要读取钉钉在线文字文档(adoc)正文（Markdown）时",
"用户直接粘贴文档 URL 且无其他指令时（默认读内容）",
"互联网公开文档（含设置密码保护的公开链接）时配合 --password 提供访问密码",
"要读取指定历史版本内容时用 --version（版本号来自 doc version list，0 表示初始版本，需要编辑权限）",
"只需标题大纲、指定块区间/单块或特定 JSONML tags 时使用 --content-format jsonml 与 --scope",
},
AvoidWhen: []string{
@@ -1533,9 +1552,11 @@ func newDocCommand() *cobra.Command {
{Name: "content-format", Property: "format", Required: boolPtr(false)},
{Name: "end-block-id", Required: boolPtr(false)},
{Name: "max-depth", Required: boolPtr(false), InterfaceType: "integer"},
{Name: "password", Property: "password", Required: boolPtr(false)},
{Name: "scope", Required: boolPtr(false)},
{Name: "start-block-id", Required: boolPtr(false), RequiredWhen: "--scope=range or --scope=section"},
{Name: "tags", Required: boolPtr(false), RequiredWhen: "--scope=tags"},
{Name: "version", Property: "historyVersion", Required: boolPtr(false), InterfaceType: "integer"},
},
},
})
@@ -2680,6 +2701,8 @@ WARNING: --mode overwrite 为破坏性写入，会清空原文档全部内容。
readCmd.Flags().Int("max-depth", 0, "筛选遍历最大深度, 0 表示不限(仅 --scope 时生效)")
readCmd.Flags().String("start-block-id", "", "range/section 起始块 ID(节点 uuid); scope=range/section 时必填")
readCmd.Flags().String("end-block-id", "", "range 结束块 ID(节点 uuid); \"-1\"或空=到文档末尾(仅 scope=range 生效)")
readCmd.Flags().String("password", "", "互联网公开文档开启密码保护时的访问密码；普通文档无需传入")
readCmd.Flags().Int("version", 0, "读取指定历史版本内容(版本号从 doc version list 获取, 0 表示初始版本, 需要文档编辑权限)；缺省读最新版")
cli.AnnotateRuntimeFlagEnum(readCmd, "scope", "outline", "range", "section", "tags")
cli.AnnotateRuntimeFlagRequiredWhen(readCmd, "tags", "--scope=tags")
cli.AnnotateRuntimeFlagRequiredWhen(readCmd, "start-block-id", "--scope=range or --scope=section")
@@ -4752,16 +4775,30 @@ func wrapDocDeprecatedToTarget(cmd *cobra.Command, targetCmd string) {
}
}
// applyDocReadAccessParams 把 doc read 的访问参数（互联网公开文档密码、历史版本号）
// 附加到 get_document_content 请求上；空密码或未显式设置版本时不发送对应字段，
// 显式 --version 0 表示读取文档初始版本。
func applyDocReadAccessParams(args map[string]any, password string, historyVersion int, historyVersionSet bool) {
if password != "" {
args["password"] = password
}
if historyVersionSet && historyVersion >= 0 {
args["historyVersion"] = historyVersion
}
}
// resolveContentFromFlags 从 --content-file / --content-path / --content / --markdown 获取文档内容。
// 优先级：--content-file/--content-path > --content > --markdown（已弃用别名，向后兼容）。
func runDocReadJsonML(_ *cobra.Command, nodeID string, outputPath string) error {
func runDocReadJsonML(nodeID, outputPath, password string, historyVersion int, historyVersionSet bool) error {
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
defer cancel()
resultText, err := callMCPToolReturnText(ctx, "get_document_content", map[string]any{
toolArgs := map[string]any{
"nodeId": nodeID,
"format": "jsonml",
})
}
applyDocReadAccessParams(toolArgs, password, historyVersion, historyVersionSet)
resultText, err := callMCPToolReturnText(ctx, "get_document_content", toolArgs)
if err != nil {
return err
}
@@ -4813,7 +4850,7 @@ func runDocReadJsonML(_ *cobra.Command, nodeID string, outputPath string) error
// runDocReadScope calls get_document_content with JSONML filtering parameters
// and preserves the returned read-only fragment container.
func runDocReadScope(nodeID, scope, tags string, maxDepth int, maxDepthSet bool, startBlockID, endBlockID, outputPath string) error {
func runDocReadScope(nodeID, scope, tags string, maxDepth int, maxDepthSet bool, startBlockID, endBlockID, outputPath, password string, historyVersion int, historyVersionSet bool) error {
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
defer cancel()
@@ -4833,6 +4870,7 @@ func runDocReadScope(nodeID, scope, tags string, maxDepth int, maxDepthSet bool,
if endBlockID != "" && scope == "range" {
args["endBlockId"] = endBlockID
}
applyDocReadAccessParams(args, password, historyVersion, historyVersionSet)
resultText, err := callMCPToolReturnTextOnServer(ctx, "doc", "get_document_content", args)
if err != nil {
internal/helpers/doc_coverage_more_test.go
+1 -1
View File
@@ -144,7 +144,7 @@ func TestCrossPlatformCoverageRunDocReadJSONMLCoverage(t *testing.T) {
t.Run(tc.name, func(t *testing.T) {
caller := &scriptedToolCaller{steps: []scriptedToolStep{tc.step}}
installScriptedCaller(t, caller)
err := runDocReadJsonML(&cobra.Command{}, "node", tc.output)
err := runDocReadJsonML("node", tc.output, "", 0, false)
if tc.wantFail && err == nil {
t.Fatal("expected failure")
}
internal/helpers/doc_read_scope_test.go
+95 -5
View File
@@ -77,7 +77,7 @@ func TestCrossPlatformCoverageDocReadScopeFlagsAndValidation(t *testing.T) {
if err != nil || len(remaining) != 0 {
t.Fatalf("find read: remaining=%v err=%v", remaining, err)
}
for _, name := range []string{"scope", "tags", "max-depth", "start-block-id", "end-block-id"} {
for _, name := range []string{"scope", "tags", "max-depth", "start-block-id", "end-block-id", "password", "version"} {
if read.Flags().Lookup(name) == nil {
t.Fatalf("doc read missing --%s", name)
}
@@ -249,7 +249,7 @@ func TestCrossPlatformCoverageRunDocReadScopeResponseBranches(t *testing.T) {
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
output := installDocReadScopeCaller(t, tt.caller)
err := runDocReadScope("doc-1", "", "", 0, false, "", "ignored", tt.output)
err := runDocReadScope("doc-1", "", "", 0, false, "", "ignored", tt.output, "", 0, false)
if tt.wantErr != "" {
if err == nil || !strings.Contains(err.Error(), tt.wantErr) {
t.Fatalf("error = %v, want %q", err, tt.wantErr)
@@ -277,7 +277,7 @@ func TestCrossPlatformCoverageRunDocReadScopeResponseBranches(t *testing.T) {
caller := &docReadScopeCaller{text: `{"jsonml":"[\"fragment\",{}]"}`}
stdout := installDocReadScopeCaller(t, caller)
outputPath := filepath.Join(t.TempDir(), "fragment.json")
if err := runDocReadScope("doc-1", "outline", "", 0, false, "", "", outputPath); err != nil {
if err := runDocReadScope("doc-1", "outline", "", 0, false, "", "", outputPath, "", 0, false); err != nil {
t.Fatalf("runDocReadScope: %v", err)
}
var receipt map[string]any
@@ -292,7 +292,7 @@ func TestCrossPlatformCoverageRunDocReadScopeResponseBranches(t *testing.T) {
t.Run("human output reports missing fragment", func(t *testing.T) {
caller := &docReadScopeCaller{text: `{}`, format: "raw"}
stdout := installDocReadScopeCaller(t, caller)
if err := runDocReadScope("doc-1", "", "", 0, false, "", "", ""); err != nil {
if err := runDocReadScope("doc-1", "", "", 0, false, "", "", "", "", 0, false); err != nil {
t.Fatalf("runDocReadScope: %v", err)
}
if !strings.Contains(stdout.String(), "未匹配到节点") {
@@ -304,7 +304,7 @@ func TestCrossPlatformCoverageRunDocReadScopeResponseBranches(t *testing.T) {
caller := &docReadScopeCaller{text: `{"jsonml":"[\"fragment\",{}]"}`, format: "raw"}
stdout := installDocReadScopeCaller(t, caller)
outputPath := filepath.Join(t.TempDir(), "fragment.json")
if err := runDocReadScope("doc-1", "outline", "", 0, false, "", "", outputPath); err != nil {
if err := runDocReadScope("doc-1", "outline", "", 0, false, "", "", outputPath, "", 0, false); err != nil {
t.Fatalf("runDocReadScope: %v", err)
}
if !strings.Contains(stdout.String(), "JSONML fragment 已写入 "+outputPath) {
@@ -312,3 +312,93 @@ func TestCrossPlatformCoverageRunDocReadScopeResponseBranches(t *testing.T) {
}
})
}
// TestCrossPlatformCoverageDocReadAccessParamsForwarding 验证 doc read 三条读取路径
// 都把 --password / --version 透传到 get_document_content，且非法版本号在
// 本地校验阶段被拒绝、不产生远端调用。
func TestCrossPlatformCoverageDocReadAccessParamsForwarding(t *testing.T) {
t.Run("markdown path forwards password and history version", func(t *testing.T) {
caller := &docReadScopeCaller{text: `{"markdown":"body"}`}
if err := executeDocReadScopeCommand(t, caller, "read", "--node", "doc-1", "--password", "pw", "--version", "7"); err != nil {
t.Fatalf("execute: %v", err)
}
if len(caller.calls) != 1 {
t.Fatalf("calls = %d, want 1", len(caller.calls))
}
want := map[string]any{"nodeId": "doc-1", "password": "pw", "historyVersion": 7}
if caller.calls[0].tool != "get_document_content" || !reflect.DeepEqual(caller.calls[0].args, want) {
t.Fatalf("call = %#v, want get_document_content %#v", caller.calls[0], want)
}
})
t.Run("jsonml path forwards password and history version", func(t *testing.T) {
caller := &docReadScopeCaller{text: `{"jsonml":"[\"root\",{}]","revision":7}`}
if err := executeDocReadScopeCommand(t, caller, "read", "--node", "doc-1", "--content-format", "jsonml", "--password", "pw", "--version", "7"); err != nil {
t.Fatalf("execute: %v", err)
}
if len(caller.calls) != 1 {
t.Fatalf("calls = %d, want 1", len(caller.calls))
}
want := map[string]any{"nodeId": "doc-1", "format": "jsonml", "password": "pw", "historyVersion": 7}
if caller.calls[0].tool != "get_document_content" || !reflect.DeepEqual(caller.calls[0].args, want) {
t.Fatalf("call = %#v, want get_document_content %#v", caller.calls[0], want)
}
})
t.Run("scope path forwards password and history version", func(t *testing.T) {
caller := &docReadScopeCaller{text: `{"jsonml":"[\"fragment\",{},[\"h1\",{},\"t\"]]"}`}
if err := executeDocReadScopeCommand(t, caller,
"read", "--node", "doc-1", "--content-format", "jsonml", "--scope", "outline",
"--password", "pw", "--version", "7"); err != nil {
t.Fatalf("execute: %v", err)
}
if len(caller.calls) != 1 {
t.Fatalf("calls = %d, want 1", len(caller.calls))
}
want := map[string]any{"nodeId": "doc-1", "format": "jsonml", "scope": "outline", "password": "pw", "historyVersion": 7}
if caller.calls[0].tool != "get_document_content" || !reflect.DeepEqual(caller.calls[0].args, want) {
t.Fatalf("call = %#v, want get_document_content %#v", caller.calls[0], want)
}
})
t.Run("negative history version is rejected locally", func(t *testing.T) {
for _, raw := range []string{"-1", "-3"} {
caller := &docReadScopeCaller{}
err := executeDocReadScopeCommand(t, caller, "read", "--node", "doc-1", "--version", raw)
if err == nil || !strings.Contains(err.Error(), "--version 必须为非负整数") {
t.Fatalf("--version %s error = %v, want invalid --version", raw, err)
}
if len(caller.calls) != 0 {
t.Fatalf("--version %s produced %d remote calls, want 0", raw, len(caller.calls))
}
}
})
t.Run("explicit zero history version forwards initial version", func(t *testing.T) {
caller := &docReadScopeCaller{text: `{"markdown":"body"}`}
if err := executeDocReadScopeCommand(t, caller, "read", "--node", "doc-1", "--version", "0"); err != nil {
t.Fatalf("execute: %v", err)
}
if len(caller.calls) != 1 {
t.Fatalf("calls = %d, want 1", len(caller.calls))
}
want := map[string]any{"nodeId": "doc-1", "historyVersion": 0}
if caller.calls[0].tool != "get_document_content" || !reflect.DeepEqual(caller.calls[0].args, want) {
t.Fatalf("call = %#v, want get_document_content %#v", caller.calls[0], want)
}
})
t.Run("unset history version is not forwarded", func(t *testing.T) {
caller := &docReadScopeCaller{text: `{"markdown":"body"}`}
if err := executeDocReadScopeCommand(t, caller, "read", "--node", "doc-1"); err != nil {
t.Fatalf("execute: %v", err)
}
if len(caller.calls) != 1 {
t.Fatalf("calls = %d, want 1", len(caller.calls))
}
want := map[string]any{"nodeId": "doc-1"}
if caller.calls[0].tool != "get_document_content" || !reflect.DeepEqual(caller.calls[0].args, want) {
t.Fatalf("call = %#v, want get_document_content %#v", caller.calls[0], want)
}
})
}
internal/helpers/http_coverage_more_test.go
+3 -3
View File
@@ -147,9 +147,9 @@ func TestCrossPlatformCoverageRunDocReadJsonMLCoverage(t *testing.T) {
`{"jsonml":"{\"type\":\"doc\"}","revision":"bad"}`,
} {
caller.result = &edition.ToolResult{Content: []edition.ContentBlock{{Type: "text", Text: text}}}
_ = runDocReadJsonML(nil, "node", "")
_ = runDocReadJsonML("node", "", "", 0, false)
}
caller.result = &edition.ToolResult{Content: []edition.ContentBlock{{Type: "text", Text: `{"jsonml":"{\"type\":\"doc\"}"}`}}}
_ = runDocReadJsonML(nil, "node", filepath.Join(t.TempDir(), "out.json"))
_ = runDocReadJsonML(nil, "node", filepath.Join(t.TempDir(), "missing", "out.json"))
_ = runDocReadJsonML("node", filepath.Join(t.TempDir(), "out.json"), "", 0, false)
_ = runDocReadJsonML("node", filepath.Join(t.TempDir(), "missing", "out.json"), "pw", 3, true)
}
internal/shortcut/doc/content_shortcuts.go
+17 -4
View File
@@ -176,15 +176,17 @@ var Fetch = shortcut.Shortcut{
Command: "+fetch",
Product: productDoc,
Description: "读取完整或局部文档内容，并按 detail 控制保真度",
Intent: "当用户要按 node/URL 直接读取在线文字文档，或只知道唯一标题并希望一次完成解析和读取时使用；支持 outline/range/section/keyword/tags 局部内容用于精确编辑和评论。",
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 局部内容用于精确编辑和评论。",
"当用户要按 node/URL 直接读取在线文字文档，或只知道唯一标题并希望一次完成解析和读取时使用；支持 outline/range/section/keyword/tags 局部内容用于精确编辑和评论；互联网公开文档（含密码保护）用 --password 提供访问密码，读历史版本用 --version 指定版本号（0 表示初始版本）。",
[]string{`dws doc +fetch --node <DOC_ID>`, `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: "version", Property: "historyVersion"},
),
Flags: []shortcut.Flag{
{Name: "node", Type: shortcut.FlagString, Desc: "文档 ID 或 URL；" + fetchTargetConstraint},
@@ -198,12 +200,17 @@ var Fetch = shortcut.Shortcut{
{Name: "context-before", Type: shortcut.FlagInt, Desc: "关键词命中前的上下文字符数"},
{Name: "context-after", Type: shortcut.FlagInt, Desc: "关键词命中后的上下文字符数"},
{Name: "max-depth", Type: shortcut.FlagInt, Desc: "outline/section 最大深度"},
{Name: "revision", Type: shortcut.FlagInt, Desc: "只接受当前最新版；历史 revision 暂不支持"},
{Name: "password", Type: shortcut.FlagString, Desc: "互联网公开文档开启密码保护时的访问密码；普通文档无需传入"},
{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 <DOC_ID>`, `dws doc +fetch --query "项目周报" --scope keyword --keyword "结论"`},
Validate: func(rt *shortcut.RuntimeContext) error {
if rt.Changed("revision") {
return apperrors.NewValidation("HISTORICAL_READ_UNSUPPORTED: 当前接口不能读取指定历史 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")
@@ -240,6 +247,12 @@ var Fetch = shortcut.Shortcut{
if rt.Changed("max-depth") {
params["maxDepth"] = rt.Int("max-depth")
}
if rt.Changed("version") {
params["historyVersion"] = rt.Int("version")
}
if value := rt.Str("password"); value != "" {
params["password"] = value
}
data, err := rt.CallMCPData(productDoc, "get_document_content", params)
if err != nil {
return err
internal/shortcut/doc/doc_shortcuts_test.go
+23 -1
View File
@@ -1097,7 +1097,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", "1"}},
{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"}},
@@ -1128,6 +1129,27 @@ func TestCrossPlatformCoverageDocContentValidationAndPureHelpers(t *testing.T) {
t.Fatalf("expected revision was not forwarded atomically: %#v", revision.history)
}
fetchAccess := &docCoverageCaller{}
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 ||
fetchAccess.history[0].tool != "get_document_content" ||
fetchAccess.history[0].params["historyVersion"] != 7 ||
fetchAccess.history[0].params["password"] != "pw" {
t.Fatalf("fetch access params were not forwarded: %#v", fetchAccess.history)
}
fetchZero := &docCoverageCaller{}
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 version (initial version) was not forwarded: %#v", fetchZero.history)
}
for _, value := range []any{
map[string]any{"revision": 2.5}, map[string]any{"revision": json.Number("bad")}, map[string]any{"revision": "bad"},
map[string]any{"data": []any{map[string]any{"versionNumber": "3"}}}, []any{map[string]any{"version": 4.0}}, "none",
skills/mono/references/products/doc.md
+5 -1
View File
@@ -55,6 +55,8 @@ Example:
dws doc read --node "https://alidocs.dingtalk.com/document/edit?dentryKey=<DENTRY_KEY>"
dws doc read --node "https://alidocs.dingtalk.com/document/preview?dentryKey=<DENTRY_KEY>"
dws doc read --node <DOC_ID> --content-format jsonml --scope outline
dws doc read --node <PUBLIC_URL> --password <ACCESS_PASSWORD>
dws doc read --node <DOC_ID> --version 3
Flags:
--node string 文档 ID 或 URL (必填)
--content-format string 输出格式: markdown / jsonml
@@ -63,9 +65,11 @@ Flags:
--max-depth int 筛选遍历最大深度，0 表示不限
--start-block-id string range / section 起始块 UUID
--end-block-id string range 结束块 UUID
--password string 互联网公开文档密码保护时的访问密码
--version int 读取指定历史版本（版本号从 doc version list 获取，0 表示初始版本）；缺省读最新版
```
`--scope` 只适用于 `--content-format jsonml`，用于按大纲、块区间、单块子树或自定义 tag 局部读取。筛选结果是虚拟 JSONML fragment，只能剥壳后消费 children，不得把 fragment 容器整体写回。完整规则见 [`doc-read.md`](./doc/doc-read.md)。
`--scope` 只适用于 `--content-format jsonml`，用于按大纲、块区间、单块子树或自定义 tag 局部读取。筛选结果是虚拟 JSONML fragment，只能剥壳后消费 children，不得把 fragment 容器整体写回。互联网公开文档（含密码保护）用 `--password`；读取历史版本内容用 `--version`（版本号来自 `dws doc version list`，0 表示初始版本，需要编辑权限）。完整规则见 [`doc-read.md`](./doc/doc-read.md)。
### 创建文档
```
skills/mono/references/products/doc/doc-read.md
+15
View File
@@ -25,6 +25,8 @@ Flags:
--max-depth int 筛选遍历最大深度，0 表示不限
--start-block-id string range / section 起始块 UUID
--end-block-id string range 结束块 UUID；空或 "-1" 表示到文档末尾
--password string 互联网公开文档开启密码保护时的访问密码；普通文档无需传入
--version int 读取指定历史版本内容（版本号从 doc version list 获取，0 表示初始版本，需要文档编辑权限）；缺省读最新版
```
## 关键说明
@@ -33,6 +35,13 @@ Flags:
- 返回的 Markdown 中，附件以 OSS 临时下载链接形式给出（如 `https://alidocs2.oss-cn-zhangjiakou.aliyuncs.com/res/.../att/<resourceId>.ext?Expires=...`），**链接会过期**。链接过期后从 URL 路径中提取 `<resourceId>`（即 `/att/` 后、扩展名前的 UUID 部分），用 `media download --node <DOC_ID> --resource-id <resourceId>` 重新获取下载链接。
- `--content-format jsonml` 返回完整 JSONML 结构（含 `revision`），用于无损读改写；可直接配合 [`doc-update.md`](./doc-update.md) 的 `--content-format jsonml --content-file` 写回。`revision` 仅在并发敏感场景下需要透传给 update 触发并发检查（详见下方）。
## 互联网公开文档与历史版本
- **互联网公开文档**：公开链接直接传 `--node`；文档开启了密码保护时，通过 `--password <ACCESS_PASSWORD>` 提供访问密码，普通文档无需传入。密码只进入读取请求，不会回显在读取结果里（`--dry-run` 预览会包含所传参数，注意输出环境）。
- **历史版本**：`--version <N>` 读取指定历史版本内容（Markdown / JSONML / scope 均可组合）；版本号从 `dws doc version list` 或 `dws doc +version-list` 获取，`0` 表示文档初始版本；需要文档编辑权限（EDITOR 及以上），缺省读最新版。
- **跨组织文档**：非互联网公开的跨组织文档，`doc read` 整体被组织边界拦截（提示「不支持跨组织访问数据」），最新版与历史版本内容都读不到（`doc info` 仍可用）；互联网公开（含密码）文档的 `doc read` 不受影响，但 `doc version list` / `+version-list` 与写操作仍会被拦截，版本号无法从列表获取。
- 只要看历史内容、不打算恢复时用 `--version`；要把文档整体恢复到历史版本才用 `doc version revert`（危险操作，需确认）。
## content-format=jsonml 输出
输出 JSON 对象，包含 `revision`（版本号）和 `jsonml`（JSONML body 数组）：
@@ -92,6 +101,12 @@ dws doc read --node <DOC_ID> --format json
# alidocs URL 直传
dws doc read --node "https://alidocs.dingtalk.com/i/nodes/<DOC_UUID>" --format json
# 互联网公开文档（含密码保护）
dws doc read --node <PUBLIC_URL> --password <ACCESS_PASSWORD> --format json
# 读取历史版本（版本号来自 dws doc version list）
dws doc read --node <DOC_ID> --version 3 --format json
# JSONML 完整结构 → 文件（无损改写前置）
dws doc read --node <DOC_ID> --content-format jsonml --output /tmp/doc.json
# 之后修改 /tmp/doc.json 中的 jsonml 数组，再用：
skills/multi/dingtalk-doc/references/doc.md
+2
View File
@@ -52,6 +52,8 @@ dws doc +version-revert --node <DOC_ID> --version <N> --format json
`+version-save/list/revert` 分别用于快照、浏览和恢复，命中后直接执行，不预读 Help。`+history-*` 仅兼容已有调用，不用于新的 Agent 选路。重要内容更新优先使用 `+checkpoint-update`，不要手工编排保存、写入和回读。回滚必须确认，以 leaf Schema 与 Runtime gate 为准。
只读某个历史版本的内容时，用 `dws doc +fetch --node <DOC_ID> --version <N>`（版本号同样来自 `+version-list`，`0` 表示初始版本，需要文档编辑权限）；整体恢复到历史版本才用 `+version-revert`（危险操作，需确认）。互联网公开文档（含密码保护）的读取见 [doc-read.md](doc/doc-read.md) 的 `--password`。
## 权限与分享
- 查询或聚合权限：`+inspect --include-permissions`。
skills/multi/dingtalk-doc/references/doc/doc-read.md
+9
View File
@@ -5,6 +5,8 @@
```bash
dws doc +fetch --node <DOC_ID_OR_URL> --format json
dws doc +fetch --query "项目周报" --scope keyword --keyword "结论" --format json
dws doc +fetch --node <PUBLIC_URL> --password <ACCESS_PASSWORD> --format json
dws doc +fetch --node <DOC_ID> --version <VERSION> --format json
```
- 已知 ID 或 URL：传 `--node`。
@@ -12,6 +14,13 @@ dws doc +fetch --query "项目周报" --scope keyword --keyword "结论" --forma
- `--node` 与 `--query` 必须且只能提供一个。
- 默认 `--detail simple --scope full`，适合普通阅读，避免加载不必要的 JSONML。
## 互联网公开文档与历史版本
- **互联网公开文档**：公开链接直接传 `--node`；文档开启了密码保护时，通过 `--password <ACCESS_PASSWORD>` 提供访问密码，普通文档无需传入。密码只进入读取请求，不会回显在读取结果里（`--dry-run` 预览会包含所传参数，注意输出环境）。
- **历史版本**：`--version <N>` 读取指定历史版本内容；版本号从 `dws doc +version-list` 获取，`0` 表示文档初始版本，需要文档编辑权限（EDITOR 及以上）；缺省读最新版。注意区分：`revision` 是文档编辑版本号（JSONML 读取响应返回、供 `+update --expected-revision` 条件写使用），不是历史版本号，`+fetch` 不支持 `--revision`。
- **跨组织文档**：非互联网公开的跨组织文档，`+fetch` 整体被组织边界拦截（提示「不支持跨组织访问数据」），最新版与历史版本内容都读不到；互联网公开（含密码）文档的 `+fetch` 不受影响，但 `+version-list` 与写操作仍会被拦截，版本号无法从列表获取。
- 只要看历史内容、不打算恢复时用 `--version`；要把文档整体恢复到历史版本才用 `+version-revert`（危险操作，需确认）。
## 局部读取
```bash