# Changelog

All notable changes to this project will be documented in this file.

The format is inspired by [Keep a Changelog](https://keepachangelog.com/) and this project follows [Semantic Versioning](https://semver.org/).

## [Unreleased]

## [1.0.66] - 2026-10-28

本版本将已交付的 `v1.0.66-beta.2` 晋级正式版，汇总两个 beta 的改进，并纳入下方列出的 beta 后变更。

### Changed

- 汇总 beta 改进：新增第三方 OIDC 登录、Provider Hook、分步换票及应用与来源隔离的凭证刷新；登录错误保留公开错误码和 Trace ID，并过滤凭证与内部诊断。核心已提供 Hook，真实 SDK 适配由 overlay 接入。
- 汇总 beta 修复：文档创建移除与文档名重复的首个 Markdown H1；安装器在缺失可用 Skill 时明确失败；Gitee 补同步包含 OpenHarmony 归档。

- **Pi 接入说明** — 补齐已有 Pi 适配器的配置、模型选择、会话隔离与重置、工具权限、文本回退及音视频限制说明；按实际参数解释 ask 模式，不引入新运行时行为。
- **数字员工类型迁移** — 本次包含 `open_code → qwenwork` 的破坏性输入变更，脚本及返回值消费者须同步调整；分发前仍需独立核实公共服务的新旧客户端兼容行为，CI 通过不代表服务端已兼容。

### Changes since `v1.0.66-beta.2`

### Added

- **AI Table advanced permission role members** — adds role member append/replace, role copy, and effective user-role query commands with validated member payloads and unified Agent output.

- 表单分享更新按 MCP 回读的权限、匿名、查看范围、通知、时间及封面配置校验终态；已回读值矛盾时返回部分失败，旧服务端缺失字段或缺少资源对应证明时继续明确标记未验证。

- 补齐表单分享 get/update 的返回 Schema，并在结果中保留历史成员身份不可用的安全提示。修正表单列表中 UUID 和候选链接的 Help/Skill 说明。

- 对齐 MCP 表单分支的封面可信域名、端口及 URL 格式限制；保留已上传封面的结构化恢复 ID，并兼容非指定成员模式清空授权后的空字符串回读。催填 Help/Schema/Skill 统一使用当前组织 userId，由 MCP 复用身份转换并兼容历史 uid；提示结果不明时不自动重发，兼容不依赖旧客户端升级。

本地封面上传成功后配置更新失败时，整条命令禁止自动重试并清除重试时间建议，保留错误分类、原始诊断和资源恢复 ID，避免重复上传。

回执中的 enabled 与 status 相互矛盾时返回不可自动重放的部分失败，避免将关闭或受处罚的状态误标为已验证成功。

正数提交上限回读为 0（不限制）时按终态不一致处理；仅显式清除上限才接受 0。分享链接读取复用分享配置查询的只读退避重试，读取成功后只生成一次链接和二维码。

- `chat list-all-conversations` 新增显式 `--page-all` 自动翻页，并支持页数、条数和页间等待边界；默认单页行为保持不变。

- 新增 `dws mcp market search`：按名称关键词搜索钉钉 MCP 市场，返回 `mcpId`、名称、描述、服务名、提供方、是否官方和是否收费，可直接衔接 `dws mcp published tools <mcpId>` 与 `dws mcp url get <mcpId>`。支持 `--limit` 单页数量与 `--cursor` 续页；只覆盖已上架市场的 MCP，企业内发布但未上架市场的 MCP 不在结果中。

- Add independent mind-map creation and topic list/create/update/delete with reviewed OpenNodes input, unified results, and separate routing from blank wiki files and minutes mind maps.
- Add group-number join requests and invitation-link group lookup/join with explicit pending results and invitation credential redaction.
- Add application scope get/set and preserve failure, pending and unknown outcomes in application lifecycle results; success guidance never executes follow-up actions automatically.
- Extend AI Table orchestration with bounded batch reads, build plans, chart templates/layout diagnostics, resumable AI task waits and reports, builtin AI field configuration and field-group operations. Mutations retain explicit verification and recovery facts; unavailable capabilities do not authorize write probes or blind replay.

- 为 Schema string 参数的精确枚举迁移增加独立审批清单与 pending/consumed 生命周期；同一个前置 MR 可提交机制与仍保持 before 的 pending 计划，旧基线仍完整比较产品且不读取新清单，新 checker 仅以空审批补查声明。本次登记四项数字员工枚举迁移供维护者审阅，不修改业务参数、不提交 consumed、不调整历史基线或跳过质量门禁。

### Changed

- **Dangerous command confirmation** (#1096) — `calendar event delete`, `calendar attendee delete`, `calendar room delete`, `chat group members remove`, `minutes replace-text`, and `doc permission update` now require explicit confirmation and publish `high` risk in Schema. Event deletion and minutes text replacement also publish `destructive` effects. Non-interactive scripts must pass `--yes` after obtaining user approval; otherwise these commands return `confirmation_required` without calling the remote service. The mono skill's dangerous-operation table now uses the canonical `calendar attendee delete` path for Schema lookup.

- `dws dingtalk-tag manage create|list|save-draft --type` 使用 `qwenwork` / `local_agent`；Help、Schema、Skill 和示例同步。
- 创建仍须显式选择类型，响应模式默认值、人设保存、发布前更新人校验及本地 Agent 接入逻辑不变。
- 返回值消费者需要识别 `qwenwork`。在分发新 CLI 前，须独立核实公共服务支持新类型以及旧客户端所需的兼容行为；本说明不代表线上部署已完成。
- 更新不传类型保持原值，类型创建后不可切换。`connect --channel opencode` 是本地适配器名称，不属于本次改名。
- 先核实公共服务兼容性，并同步 MCP 工具类型枚举/描述，再使用新 CLI。旧脚本中的 `--type open_code` 需改为 `--type qwenwork`。
- 回滚 CLI 时需一并核对服务端返回契约；本变更不迁移员工数据。
- `manage set-visibility` 在预览和执行前校验 ALL/PARTIAL、PARTIAL 非空目标及 ALL 与指定目标互斥，非法范围不会调用 MCP；合法请求和旧参数别名兼容保持不变。
- `run run-status` 的 Help 与 Skill 按真实返回说明 `result` 为字符串状态文案，程序应使用 `execStatus` 判断执行状态。
- Skill 上传失败保留公开权限管理链接，不再整段误脱敏；其他 URL、签名地址与凭证仍不输出。Skill 更新仅返回裸 `NO_PERMISSION` 时补充条件式权限引导，保留错误码、Trace ID 和退出码，不覆盖服务端具体说明、不重试写操作。

### Fixed

- **npm Skill installation resilience** (#1320, binary-only switch proposed in #1321) — supports `DWS_NO_SKILLS=1` for binary-only installs and keeps an optional user-cache refresh failure from rolling back an otherwise successful CLI and Agent Skill installation.

- **限流错误提示** — 当服务返回 `server_error_code=RATE_LIMIT_ERROR` 时，明确说明当前请求频率过高、本次请求被限流，并引导等待 10 秒后重试；其他错误码保持原有处理。

## [1.0.66-beta.2] - 2026-10-26

### Added

- OIDC 登录错误诊断：`auth provider-login <provider>`、`auth exchange-prepare` 和 `auth token-exchange`
保留 Portal 的公开错误码和 trace ID，并将已定义错误码转换为可读说明。
覆盖配置、事务/state、授权码、身份校验、限流、上游调用和 DWS 会话签发错误。
三个命令均为第三方 IdP 集成入口，不出现在 `dws auth --help` 与 shell 补全中，可显式执行。

- 从 `error.code`、`error.action`、`trace_id` 解析公开诊断；响应体缺失或无效时，
  使用合法的 `X-Dws-Trace-Id`。后端日志专用 `reason` 不进入客户端输出。
- 人类可读错误显示 `Trace ID` 和 `Server Code`。JSON 复用现有字段：
  传统输出为 `error.server_error_code`，统一输出为 `error.upstream_code`，
  两者均提供 `error.trace_id` 和 `error.details.action/http_status/provider`。
- `stop` 提示检查参数/配置或联系管理员；`restart_login` 提示重新登录或重新
  `exchange-prepare` 取码。保持单次请求，不自动重试旧 code/state。
- 保留现有错误分类、退出码和 token 响应格式。只保留 Portal 已定义的固定公开
  message，不回显任意异常正文、内部 reason 或请求凭证；诊断标识限制长度和字符。

验证包含真实本地 HTTP 错误响应、三条命令的 JSON/人类输出、无效响应的 trace 回退、
配置停止与重新登录提示、取消/超时分类、凭证反射过滤及不重试行为。

- OIDC Provider 通过 `edition.Hooks.OIDCProviders` 注册。核心 Hook 已实现；dws-ant 的真实 SDK 适配和注册留待后续接入。

`auth provider-login <provider>` 从 `edition.Hooks.OIDCProviders` 选择授权实现。
该命令为第三方 IdP 集成入口，不出现在 `dws auth --help` 与 shell 补全中，可显式执行。
必填位置参数 `<provider>` 同时传给 transactions 和 exchange 接口。换票请求包含
`provider`、`code`、`state`；显式指定 DWS 应用凭据时再加入 `client_id`、`client_secret`。
核心通过注册项选择授权实现，具体 SDK 由 overlay 提供。
服务地址使用系统统一的 MCP 配置（`mcp_url` 文件或默认地址），登录不修改端点配置。

#### Overlay 接入

公共类型位于 `pkg/edition`，overlay 不需要也不得导入核心的 `internal/auth`。
在已有 `NewHooks()` 中注册名称及授权回调，再沿用启动入口的 `edition.Override(h)`：

```go
h.OIDCProviders = func() []edition.OIDCProvider {
    return []edition.OIDCProvider{
        {
            Name:      "ant",
            Authorize: authorizeWithAntSDK,
        },
    }
}
```

`authorizeWithAntSDK` 的函数签名为：

```go
func(context.Context, edition.OIDCAuthorizationRequest) (edition.OIDCAuthorizationResult, error)
```

蚂蚁适配负责调用自己的 SDK，并把 SDK 实际返回的 `code/state` 转为公共结果类型。
若已有 `AuthorizeOIDC` 使用业务侧 DTO，只在这个回调中转换类型；不用复制核心事务、
换票或保存凭证代码。SDK 初始化与认证发生在回调执行时，注册函数只返回声明。
名称可由 overlay 自定义，但必须满足 `[a-z][a-z0-9_-]{0,63}`，并与 Portal 已配置的
provider 一致。重复名称、空回调、非法名称均为注册错误。

#### 执行边界

1. 核心校验 CLI 参数并选择已注册的回调。
2. 核心向 Portal 创建事务，校验服务端 provider、授权参数与有效期。
3. 核心向回调传入 `authorization_endpoint`、独立的参数 map 及受事务期限约束的 context。
4. SDK 尊重取消与超时，原样使用服务端授权参数并返回实际取得的 `code/state`。
5. 核心验证授权码及原事务 state，再换票、补全身份、保存 DWS profile。

SDK 会话、密码、DWS 换票用的 client secret 和 PKCE verifier 不属于这个回调的输入输出。
错误中不得包含认证材料；核心也不记录 SDK 原始错误文本。授权失败、取消、超时或
state 不匹配不会触发其他 SDK 或 Mock 兜底，也不会换票或保存凭证。

没有注册对应实现时，核心仍先检查 Portal 配置；服务端接受 provider 后返回
`OIDC_SDK_UNAVAILABLE`。Help 和 dry-run 不枚举注册项、不初始化 SDK、不访问网络。
普通 OAuth/PAT 登录和分步 `exchange-prepare` / `token-exchange` 入口保持独立。

#### 联调与依赖更新

核心的 Hook API 提交并推送后，overlay 需要把远程核心依赖更新到包含该 API 的提交，
再编译上述注册代码。只修改另一 Go 包里的同名文件不会替换核心实现。

回归验证覆盖自定义名称和 ant 注册、真实命令入口及凭证保存、非法/重复/缺失注册、
后端拒绝、SDK 错误脱敏、取消/超时、state 篡改、空授权码和 help/dry-run 无副作用。

```bash
DWS_PACKAGE_VERSION=0.0.0-test CGO_ENABLED=0 go test ./pkg/edition ./internal/auth ./internal/app
```

已验证：上述三个包的完整测试、Hook 定向 race 测试、`go vet ./...`、`make build`，
以及构建后二进制的 provider-login help / dry-run。未执行真实蚂蚁网关登录。

- 支持业务分步完成第三方登录：先执行 `dws auth exchange-prepare --provider ant` 获取服务端授权参数，再由业务调用 IdP/SDK 取码，最后执行 `dws auth token-exchange --provider ant --code <code> --state <state>` 换取 DWS Token。

支持 `--code-stdin`、可选且必须成对的 `--client-id/--client-secret`，默认返回现有 TokenData；显式 `--save` 后在线核验完整身份并保存，保留已有默认账号。两个命令均支持 `--dry-run`，服务地址使用系统统一的 MCP 配置（`mcp_url` 文件或默认地址），不修改全局配置；保存 Token 时记录其刷新所用的 Portal 地址。PKCE verifier 始终由服务端保存，换票失败不会自动重试一次性 code/state。

命令沿用统一结果输出。作为第三方 IdP 集成入口，两个命令以 Cobra Hidden 隐藏，不出现在 `dws auth --help` 与 shell 补全中，仍可显式执行；不进入 Agent Schema（Hidden 且无 Contract.Identity），也不再占用 reviewed Schema 排除列表。

macOS 终端按实际文件描述符识别，使用 `select` 等待输入，不依赖 `/dev/tty` 或 `/dev/stdin` 文件名，覆盖 `< /dev/tty` 重定向；以 50ms 周期检查取消，不改变终端模式、不关闭借用句柄。高编号输入使用低编号描述符副本等待，完成后只关闭副本；低编号描述符耗尽时明确报错。

`--code-stdin` 的等待输入和后续换票共享一分钟超时，并响应调用方的取消或更短截止时间。取消、超时错误保留原有身份，不归类为参数错误，也不会继续换票。Unix 标准输入使用可取消的轮询读取，取消后保留原文件描述符；Windows 控制台保留原输入模式，通过原生 API 取消读取，重定向管道则通过关闭来中断。宿主通过 `SetIn` 注入的自定义阻塞输入须支持 `Close` 中断读取（取消时会关闭，正常完成时保留）。无 `Close` 的自定义 Reader 须为非阻塞或自行响应 context。

OIDC 换票响应增加实际 DWS `clientId`（与 IdP 的 `client_id` 不同）。`provider-login` 和 `token-exchange --save` 均保存该应用绑定和原 Portal 地址。默认应用继续由 Portal 托管密钥；显式指定的自定义应用将原始密钥保存到现有安全凭证槽，并与 Token/Profile 写入一起回滚。刷新自定义应用时从该槽读取密钥，发送给原 Portal 的 `/oauth2/refreshToken`，不回退到全局应用、不跟随重定向、不在结果或 app.json 中暴露密钥。未使用 `--save` 的分步换票不写入本地凭证。

需要同步部署 Portal：默认 OIDC 响应返回实际 `clientId`，刷新接口接受可选 `clientSecret`。旧版默认响应缺少应用绑定时，新 CLI 会明确要求更新 Portal；旧的缺失绑定记录需要重新登录。

OIDC 登录持久化时记录 `oidc_provider`，刷新成功继续保留；该本地元数据不加入未保存的 token-exchange 返回值。所有 OIDC 分支只通过该字段识别，不再从 Portal 地址或密钥模式推断登录来源。此前未记录该字段的开发测试凭证不做兼容迁移，需重新登录。

OIDC 刷新前校验原应用、Portal 和登录来源绑定，缺失时直接报错，不使用全局应用或默认端点兜底。刷新失败不读取组织镜像或历史全局凭证，即使同用户、同组织也不能切换应用。被拒绝或失效时提示重新执行 provider-login 或原分步登录流程，自定义应用需沿用原 client-id/client-secret；网络、取消、超时、限流和 5xx 保留原凭证，不强制重新登录。普通 OAuth 既有恢复策略保持不变。

已确认的 `invalidParameter.authCode.notFound` 仍保留脱敏后的错误类型和规范化业务码供分类使用；错误识别不再意味着允许 OIDC 凭证恢复。服务端原始错误文本不进入输出、日志或错误链。

### Fixed

- **Installer skill failures** (#779) — fail explicitly without an installation-success banner when a release archive has no usable skills and no local source is available; also fail when the PowerShell local mono skill directory is missing.

- 修复 Gitee 补同步入口遗漏 OpenHarmony 附件的问题，使已发布稳定版本的完整九项制品能够通过附件清单校验。


## [1.0.66-beta.1] - 2026-10-21

### Fixed

- **Document creation title deduplication** — `dws doc +create` removes a leading Markdown H1 that matches the document name, including names inferred from Markdown, before chunking and readback verification. Different headings, indented code blocks, and JSONML content remain unchanged; inline document content preserves its surrounding whitespace.


## [1.0.65] - 2026-10-20

This release promotes the sealed `v1.0.65-beta.2` contents to stable.

### Changed

- 汇总两个 beta 版本的改进：支持聊天消息内发送本地图片、跨 MCP 委托身份传递，以及数字员工的 A2UI 回复、群聊权限、引用与图片上下文和送达状态反馈。

### Changes since `v1.0.65-beta.2`

### Added

- 数字员工新增 A2UI 回复模式：支持的本地接入先发送占位卡，再将公开进度和最终答案更新到同一卡片。新连接默认使用 A2UI，已有未配置回复模式的连接保持文本回复。
- A2UI 创建和更新命令支持通过 `--content -` 从标准输入读取消息数组，避免长正文占用命令行参数。

- **审批图片上传** — 新增 `oa approval image upload`，校验本地图片并自动压缩超出 2MB 的图片，返回 `mediaIdV2` 供审批图片控件使用；同步修正联系人控件取值格式与部门 ID 核验指引。
- **群公告选项** — 创建和编辑公告支持 `--no-card` 静默发布及 `--must-read` 新人必看；显式传入 `false` 可关闭对应选项。
- **联系人身份查询** — 新增 `contact user get-open-dingtalk-id`（别名 `get-open-id`），按手机号或钉钉号查询 `openDingTalkId`，提供统一结果与 Schema；服务端灰度与频次限制仍适用。
- **登录审批来源** — CLI 授权状态、超级管理员查询及授权申请请求在识别到 Agent 宿主时携带来源标识。

### Changed

- **AI 表格访问密钥** — 标准命令调整为 `dws aitable supabase api-key create/list/revoke`。原 `dws aitable api-key` 三个命令继续兼容，参数、返回结果和权限要求保持不变。

### Fixed

- **Skill setup staging fail-closed** (#1421) — path walks no longer skip read-only sibling directories behind a link entry, and staging identity read failures no longer delete by name or silently degrade to compat install, preventing leftover staging objects and false success reports during `dws skill setup`.

- **Windows Agent skill link readability** (#1425) — uses directory junctions with absolute canonical targets for Agent skill adapters on Windows, upgrades legacy directory symlinks, and validates readability before publication, preventing `EPERM` errors when followed by Node.js and Agent skill loaders.

- **升级版本比较** (#556) — `dws upgrade`、`dws upgrade --check` 和 `dws doctor` 比较版本时按 SemVer 忽略 build metadata（`+...`）。此前当前或远端版本号带 `+` 时，可能把更旧或相同的版本误报为可升级，或漏报真正的新版本。

- Prevent publishing a digital employee draft when its available last-editor identity differs from the current operator, while preserving compatibility for legacy drafts without that identity.
- Describe digital employee create and publish workflows as composite Schema interfaces, and publish the exact-one constraint for Skill updates using `--enabled` or `--file`.


## [1.0.65-beta.2] - 2026-10-15

### Changed

- **数字员工回复复用 chat** — 通用发送与引用回复增加 stdin 正文、投递回执和绑定上下文校验；本地数字员工 worker 使用通用 chat 回传，保留已发布的 `channel reply` / `channel operator-private` 兼容入口，新宿主改用通用 chat，配套 DSH 要求 `chatDelivery=true`，缺失时提示升级；双方须配套升级。
- **A2UI 审批卡片兼容** — 发卡命令支持 `--summary` 自定义聊天预览，满足 DSH 数字员工的卡片能力探测；省略时继续使用原有默认摘要。

local_agent 私聊权限读取 DEAP 已发布可见范围（成员及部门子树）；群聊以已入群为准，不叠加个人可见范围或本地群白名单，并修复空白名单漏订阅群内 @ 消息；群聊仅原生 @ 当前员工才触发，普通消息不进入模型。DSH 按 groupMembershipAccess 能力传递群上下文；其他场景保留本地白名单。DWS/DSH 共用绑定查询判定，固定管理 Profile，查询失败不回退放行。

### Fixed

- **数字员工本地 Agent 状态反馈** (#1475) — 在原消息上显示排队、思考、已完成、失败或待核查状态；执行失败时发送明确提示，正常结束但无回复文字时仅贴“收到”，并将表情更新与正文投递分开记录，避免提前显示完成或因表情失败重复执行。
- **数字员工引用上下文** (#1475) — 本地 Agent 接收引用回复时同时获得被引用的消息内容，避免只能看到当前问题；保留普通输入、会话指令及原有授权范围。
- **数字员工 Codex 本地任务** (#1475) — 修复内置 Codex 误用群聊机器人的附件问答限制，允许按用户请求和现有权限使用本地技能与 CLI，保留沙箱配置，并避免会话恢复失败后静默新建、丢失上下文。
- **数字员工图片输入** (#1475) — 自动下载直发或引用图片并交给本地 Agent，Codex 使用原生图片输入，避免只有 mediaId 无法识别；下载失败明确提示并保留失败状态。

- **数字员工回执查询** — 等待发送回执时，对 `im/query_message_send_status` 返回的结构化错误码 `1001` 重查原发送任务，兼容回执尚未落库的短暂窗口；查询和等待共享最多 2 秒预算，到期报告送达状态未知，不重新发送消息。

- **数字员工自身消息识别** — connect 使用员工自己的登录身份精确解析自身开放 ID，避免发布详情与入站事件的身份作用域不同而产生自回复。旧配置没有员工 Profile 作用域标记时，原生 worker 和 DSH 启动阶段只解析自身一次；失败拒绝启动，不依赖主管、不逐消息查询、不修改原绑定、模型、权限或会话。

- **数字员工平台入站权限** — 正式绑定的 local_agent 直接使用平台保证的私聊投递和群内 @ 权限，不再逐消息查询可见范围、通讯录或部门；其他本地通道保持白名单。旧绑定缺少主管 Profile 也可正常启动，删除仅用于可见范围的主管迁移和启动阻断。新绑定不再写入该历史字段，固定 operator 审批、绑定版本与解绑检查保留。DSH 通过 bindingAccessPolicy 能力读取明确访问策略，需配套新版插件。

- **Windows 图片与卡片契约** — Markdown 本地图片识别盘符路径及标准 file URI；内嵌 A2UI 解释资源在检出时保持 LF，避免摘要因换行转换失配。修正数字员工工作目录、附件及导出路径的跨平台测试夹具。

- **升级下载** — 官方开源版独立安装继续通过 npm 查询版本，改为只下载同版本 GitHub Release 的当前平台归档和技能包，避免下载包含其他平台的完整 npm 包。官方 Release 查询优先使用环境变量或本机 GitHub CLI 已有凭据，无可用凭据时匿名查询；凭据不进入 Registry 或资产下载。强制验证资产大小、SHA256 和二进制版本；失败时不自动回退全包。`--dry-run` 展示预计下载量，`--skip-skills` 省去技能包下载。自定义源和包管理器升级保持原有行为。


## [1.0.65-beta.1] - 2026-10-15

### Added

- **本地图文混排** — `chat message send --content` 和 `chat +messages-send --as user --markdown` 自动上传行内本地图片，保留前后文字；支持预览、内容去重及最多三路并发上传。
- **图文图片上传** — 使用上传返回的 `mediaIdV2` 构建图文消息；缺少 V2 时终止发送，避免使用不符合图片下载接口契约的编号。个人收藏表情保留原有媒体编号选择行为。
- **图文图片编号复用** — 发送时识别裸 V2 图片编号；读取 Markdown 和富文本图片后生成带消息、会话身份的下载参数。
- **图文图片错误提示** — 使用固定诊断区分文件读取、路径校验和上传失败，保留敏感路径保护，并提供对应的处理建议。

- 新增全局隐藏参数 `--delegator-user-id`、`--delegator-corp-id` 和 `--delegator-open-dingtalk-id`。根命令在本次执行作用域持有校验后的不可变身份快照，公共 runner 统一向四个内置 HTTPS MCP 网关透传；旧 helper 丢弃 context 时也能补入身份，无需按业务逐条改造。无效输入整组省略；旧文档委托入口保持兼容，新旧协议禁止混用。实际委托授权依赖网关和业务服务接入。
- 修复 AI 表格主服务、辅助服务、分页、重试、视图更新和工作流发布的上下文传递，保留取消信号；扩展真实命令到 HTTP Header 的回归矩阵，并覆盖串行 root 复用和多个预建 root 的身份隔离。同进程多 root 并发执行不在支持范围，并发调用使用独立 CLI 进程。
- 更新 DWS 业务接入指南：说明公共 runner 覆盖条件、真实命令测试和绕行通道的接入要求；插件、stdio、发现、scoped 换票、独立 published MCP、直接 OpenAPI、文件字节传输及事件长连接继续排除，跨源重定向清理和 UID 发送边界保持不变。

### Fixed

- **媒体下载提示** — `dws chat message download-media` 的 Help 说明返回的下载地址临时有效，提示使用原 mediaId 及消息、会话信息重新下载。


## [1.0.64] - 2026-10-14

本版本将已交付的 `v1.0.64-beta.1` 晋级正式版，汇总该 beta 的变化，并纳入下方列出的 beta 后变更。

### Added

- **Pi Coding Agent 接入** — 新增 `--channel pi`，支持官方 JSON 流式文本、模型覆盖、按会话隔离和重启续聊；ask 模式禁用工具。
- **通讯录好友与事件** — 增加好友列表、申请列表、发送和处理申请、删除好友，以及好友申请和添加事件；统一使用 `openDingTalkId`，提供到 `userId` 的查询入口，补齐昵称、备注、状态和 Agent 使用说明。写操作要求明确确认，删除好友属于高风险操作。
- **OpenHarmony 发布包** — 增加静态自签名的 `openharmony/arm64` 归档和 SHA256，集成 SafeChat 消息加密；npm 与 Homebrew 的平台范围保持原有配置。
- **版本检查与升级提示** — `auth status`、`version` 和 `--version` 提供限时、可缓存、可关闭的更新检查；未知输入优先给出具体纠错建议，仅在缺少明确建议时检查新版，保留原错误类别、退出码和机器输出。

### Changed

- **AI 表格契约与公开同步** — 精确登记 24 项幂等性声明纠正，并限定已审查的公开同步补丁；未登记接口及风险、确认要求和执行效果的兼容保护继续生效。

### Fixed

- **AI 表格写入、等待与筛选** — 保留原始 clientToken，未知写入停止重放并通过只读对账恢复；补齐批次分组与旧回执兼容。建表、建字段提供有时限的结构核对，超时或取消不重复创建；统一查询、批量更新的筛选校验及 Help、Schema、Skill 说明。
- **日历、白板与 AI 卡片** — 修复日历嵌套时区与忙闲字段的写后核验，读回失败时保留写入回执；白板在预览或远端调用前校验 OpenNodes 层级与文本样式。更新 AI 卡片协议索引、兼容预检、预览及业务标识处理，补齐白板和卡片使用说明。
- **升级来源与安装方式** — 开源版默认通过 npm Registry 查询版本；包管理器安装交由对应工具升级，独立二进制校验 npm 包完整性与资产 SHA256 后自更新，无需 npm 或 Node.js。保留备份、回滚和 Skill 更新，修复 npm 强制升级、同版本重装及安装文档中的环境变量传递。

### Changes since `v1.0.64-beta.1`

### Removed

- **Chat Thread** — 下线 `chat thread promote`，历史调用返回 `command_retired`，帮助与 Skill 不再推荐该命令。已有消息转为话题暂无等价替代；新建话题使用 `chat thread send`，回复已有话题使用 `chat thread reply`。

- **招聘产品下线** — 开源版移除 `dws recruit job list`、`get`、`create` 及整个招聘产品域的内置注册、Schema、MCP 端点和 Skill 入口。招聘能力仅在千问办公专属版维护。

### Fixed

- **wget-only install of the latest release** (#1456) — resolving `latest` without curl now requests the GitHub releases URL directly, so wget can read the release tag instead of failing before the download.

- 修正 npm 包的问题反馈、仓库和主页链接，统一指向 `DingTalk-Real-AI/dingtalk-workspace-cli`，避免 `npm bugs` 打开 404 页面。

- **招聘退役兼容检查** — 精确登记已批准的开源招聘产品退役，避免仍含招聘能力的旧稳定版阻塞后续 PR 和发布兼容检查；其他产品和接口的兼容保护保持生效。


## [1.0.64-beta.1] - 2026-10-09

### Added

- **Pi Coding Agent 原生接入** (#1472) — 新增 `--channel pi`，支持官方 JSON 流式文本、模型覆盖、按会话隔离和重启续聊；提供本地官方 CLI 验收，ask 模式禁用工具。

- **Contact friend CLI** — adds `dws contact +friend-list`, `+friend-request-list`, `+friend-request-send`, `+friend-request-accept`, `+friend-request-reject`, and `+friend-remove` shortcuts for the friend-link MCP tools published under `mcpId=2400`. All friend shortcuts accept and return `openDingTalkId` (the open-platform pairwise identifier used in friend event payloads) instead of `dingtalkId`; the write shortcuts require explicit user confirmation (`user_required`), and `+friend-remove` is a high-risk write that must be confirmed before `--yes` is accepted.
- **Contact user lookup by openDingTalkId** — adds `dws contact user get-by-open-dingtalk-id --id <openDingTalkId>` (alias `get-user-by-open-dingtalk-id`) to retrieve a user's `userId` from their openDingTalkId, closing the friend-event-to-userId resolution loop.
- **Friend list projections expose the nickname** — `+friend-list` projects `userProfileModel.nick` (friend nickname) alongside the reviewed `alias` (friend remark name) and the friend-operation `status` (1=added, 0=removed); `+friend-request-list` projects the requester `nick` and documents the status enum for agent translation. Both list schemas mark `openDingTalkId` as the internal identifier required for follow-up operations: always returned, displayed only when the user needs to act on it.
- **Personal friend events** — registers two personal event keys for subscription and flattened projection: `user_contact_friend_request_received` (src/dest openDingTalkId, remark, source, apply time) and `user_contact_friend_added` (friend openDingTalkId, friend name, establish time, direction active/passive). Payloads without the required identity fields, or with an unknown direction, fail closed instead of projecting an empty result.
- **Friend shortcuts join the public catalog** — registers the six friend shortcuts in `semantic_catalog_contact.json` (reviewed, public) and regenerates `docs/shortcut-public-catalog.json` plus `internal/shortcut/public_catalog_generated.go`, so they are visible to agents instead of hidden.
- **Contact skill documents the friend surface** — `skills/multi/dingtalk-contact/SKILL.md` gains a friend SOP, intent-table rows, and VISIBLE_SHORTCUTS entries; `references/contact.md` gains the friend command reference (risk levels, openDingTalkId identity-key rules, pagination semantics, `+friend-remove` confirmation policy) and the `get-by-open-dingtalk-id` command section, so AI agents can discover and route friend intents.

- **OpenHarmony build, self-signer, and release** — builds a static self-signed `openharmony/arm64` package (pure-Go signer `cmd/binary-sign-tool`, deterministic archive) and publishes `dws-openharmony-arm64.tar.gz` with its SHA-256 in every beta and stable GitHub Release, verified on a HarmonyOS PC, with SafeChat message crypto linked through the pinned OpenHarmony NDK (static cgo build, OpenSSL notice in NOTICE), while keeping runtime payloads, npm, and Homebrew unchanged.

- **版本检查** — `auth status`、`version` 和 `--version` 显示当前版本与更新检查结果，支持限时查询、缓存、只读模式和关闭检查；开源版默认通过 npm Registry 查询，减少对 GitHub API 限额的依赖，无需安装 npm。
- **未知命令升级提示** — 已有具体拼写候选、人工路径或参数纠正、已知处理方案时保留原 hint，不发起版本网络检查。没有明确建议、只有通用帮助指引的未知输入才限时检查新版，并在有更新时附加升级建议，保留错误类别、退出码和机器输出格式；不据此判定该命令一定存在于新版。

### Changed

- **AI 表格契约迁移** — 精确登记 24 项幂等性声明纠正，继续拒绝未登记路径以及夹带风险、确认要求或执行效果变化。
- **公开同步准入** — 为已审查的 AI 表格同步 PR 登记固定来源和完整文件补丁，仅允许该批准内容；其他 AI PR 的文件数量和保护目录规则保持原样。

### Fixed

- **AI 表格写入与对账** — 保留调用方的原始 clientToken，写入结果未知时停止自动重放，并通过只读对账恢复；补齐批次分组与旧回执兼容。
- **AI 表格创建后等待** — 建表、建字段支持有时限的只读结构核对；等待超时或取消不会再次创建对象。
- **AI 表格筛选与发现** — 查询和批量更新共用筛选校验，统一 Help、Schema 与 mono/multi Skill 的参数和安全说明。
- **安装文档** — 修正 mono 模式和 Gitee 镜像安装示例中的环境变量传递。

- **日历写后核验** — 按真实嵌套字段校验时区与忙闲状态；读回失败时保留成功写回执并阻止自动重放。
- **白板内容校验** — 在预览、生成 SVG 或远端调用前校验 OpenNodes 字段层级和文本样式，并补齐独立白板与文档内嵌白板的路由说明。
- **AI 卡片协议与预览** — 更新 explain 索引与兼容性预检，保持更新状态并使用服务端返回的业务标识；同步组件、模式和示例说明。

- **升级来源** — 开源版的 `upgrade --check`、`--list` 和指定版本查询默认使用 npm Registry，避免依赖 GitHub REST API 的匿名请求额度；保留显式配置的 GitHub 镜像和仓库。
- **升级方式** — npm、pnpm、Homebrew 安装交由对应包管理器升级；独立二进制直接下载 npm 发布包，校验包完整性和平台资产 SHA256 后自更新，无需 npm 或 Node.js。保留原生安装的备份、回滚与技能包更新。
- **强制升级** — npm 全局和局部安装均转发 `--force`；同版本重装保留 `npm rebuild`，重跑安装脚本恢复包内二进制。


## [1.0.63] - 2026-10-03

本版本将已交付的 `v1.0.63-beta.3` 晋级正式版，汇总本版本线三个 beta 的变化，并纳入下方列出的 beta 后变更。

### Added

- **数字员工** — 新增管理、能力资源、运行追踪、员工身份登录与本地 Agent/DSH 接入；支持草稿、发布、Skill ZIP 上传与员工域 MCP 配置，使用 `agentUuid` / `userId` 身份契约。草稿配置与发布分别执行，事件连接状态区分 IPC、Agent 初始化和实际传输就绪。
- **通讯录与邮箱查人** — 支持通过 dingtalkId 查询 userId，通过企业邮箱单个或批量查询员工；批量查询分别保留已成功、未找到、失败与未知结果，避免把未确认结果报告为未找到。
- **考勤审批与鉴权快照** — 增加审批时长计算、出差/外出配套日程校验及复杂加班设置查询；`auth status --readonly` 提供不联网、不刷新、不写凭据的本地状态快照。
- **等待能力** — 框架增加声明式轮询、事件与自动回退等待；声明支持的命令提供 `--wait` / `--wait-timeout`，超时保留 `pending` 与最后观察状态，事件与轮询共用截止时间。
- **白板与 AI 表格恢复** — 增加白板 SVG 预览、差异确认、个人/团队及模板中心模板；AI 表格提供只读写入结果查询及保留原 clientToken 的不确定写入恢复路径。

### Changed

- **Schema 与启动性能** — 每次执行保持完整 Cobra 命令树，减少元数据和初始化分配；支持平台在安装或首次使用时从本机声明生成身份及经过认证的持久缓存。缓存缺失或损坏时修复，运行时插件场景由隔离子进程完成缓存构建与修复。
- **消息读取与国际登录** — 智能消息读取在策略允许时解密第三方加密消息，保留逐项解密台账；MCP 与输出投影保留大整数精度。国际登录默认使用英文，国内登录沿用现有语言设置。
- **数字员工参数与文档** — 主程序类型统一使用 `--type`，可见范围使用 `--user-ids`，保留历史参数兼容；支持可选创建提示词、发布本地员工前按需初始化提示词，以及草稿文本的空值校验。更新 OA TableField 二维数组示例、Devapp/Devdoc 流程及文档列表路由。
- **参数错误** — 框架统一参数校验的错误分类与退出码，保留业务错误及取消/超时的原有语义。
- **AI 搜问证据** — 丰富搜索结果的证据与解析详情，使用说明要求先核对证据再给出结论或交接后续操作。

### Fixed

- **跨平台发布** — 修复 Windows SafeChat CGO 运行库崩溃，以及 Darwin amd64 产物被 dyld 拒绝启动的问题；Darwin 构建固定 macOS 11.0 最低目标，签名资产验收检查 `SG_READ_ONLY` 并实际启动可执行的 Darwin 产物。
- **AI 表格回执与分页** — 表单分享按返回身份、显式请求字段和 CP 同步状态验证结果；未完整确认时保留部分失败证据。未知写入不重放创建；失效游标丢弃旧快照结果，复合流程停止后续写入。配套恢复接口仍依赖对应 MCP 服务与网关部署。
- **登录恢复** — 缺失 DEK 或旧密文不匹配时允许重新登录，取得新凭据后才替换目标；登录中的临时身份查询立即使用本次 MCP 端点覆盖，保留刷新及暂时 Keychain 故障的保护。
- **消息与事件** — 修复单聊引用回复的误拒绝，保留 OA 审批事件业务字段；个人 Stream 正确响应系统控制帧，数字员工连接沿用事件来源默认规则，改进重连及 Windows 正常停止判断。
- **文件与凭据边界** — 数字员工 Skill ZIP 使用同一已打开句柄完成校验与上传，防止路径替换；补充失败清理、绑定回执和日志脱敏验证。

### Removed

- **旧合同审查入口** — 隐藏历史 `contract review benefit|create|analysis|result` 命令并标记不可用；保留历史参数入口，但以 `command_retired` 拒绝执行，不再调用旧 MCP。

### Changes since `v1.0.63-beta.3`

### Added

- Add `dws aicard explain <name>`, `lint`, and `preview`. The embedded DingTalk A2UI protocol supports native offline lookup and structural validation without Python. Preview validates a complete new-card file and sends it to the current user's direct chat; dry-run does not send. Include the DWS authoring Skill and report request acceptance separately from client-rendering evidence.

- **Drive & Wiki set-share-scope** — add `dws drive permission set-share-scope` and `dws wiki permission set-share-scope` for managing node-level and workspace-level share visibility (PRIVATE / ORGANIZATION / PUBLIC) with partial-update semantics, role control, partner inclusion, organization search/recommend toggles, password protection and expiration (drive node only).

- **OA 审批模板创建与更新命令** — 新增 `dws oa approval template create`（`oa/create_process_template`）与 `dws oa approval template update`（`oa/update_process_template`），均为企业钉钉管理员能力。两者支持逐项参数模式（`create` 必填 `--name`、`--schema-content`；`update` 必填 `--process-code`、`--name`、`--schema-content`、`--process-config`），也支持 `--from-document` 传入完整 JSON 文档的绝对路径整体配置，两种模式互斥；`--schema-content`、`--process-config` 等对象参数以 JSON 字符串发送给 MCP，`--plugin-configs`、`--visible-range`、`--manager-user-ids` 以数组发送，均支持直接 JSON、`@文件` 与 `-` 标准输入。CLI 侧做本地校验：`schemaContent` 控件 `props.id` 唯一性检查（递归进 `children` 嵌套控件）与 `processConfig` 结构校验，并解析 MCP 返回的 `810001`（同名模板冲突）/`810002`（模板数量超限）拒绝码为失败输出而非静默重试；`--dry-run` 仅做本地校验并展示请求参数（`executed=false`），成功统一由 `data.processCode` 返回模板编码。构造 `processConfig` 时若未显式指定审批人类型，审批节点默认使用**部门主管**（`target_management`）而非直属主管。**Skill 文档**：新增 `oa-template-write.md`（从 `oa.md` 拆分模板写入路由，渐进披露）与连接器审批人规则 `target_connect_approval.md`，并补充 50+ 个控件 schema、流程节点、选人规则子文档；`oa.md` 增加模板管理路由条目、`process-nodes.md` 增加连接器审批人条目、`SKILL.md` 引用 `oa-template-write.md`。**验证状态**：变更代码含完整单测（含 `schema_oa_template_contract_test.go` Schema 契约测试）与 `mono-multi-coverage.yaml` 的 `oa-template-write` 注册；模板名称是否可用、数量是否超限由创建 MCP 校验，dry-run 不能证明名称可用，建议创建/更新后再用 `template detail` 核对实际状态。

- **AI 表格访问密钥** — 新增 SQL Sheet API Key 的创建、查询和撤销命令，以及对应的 Agent 使用说明；完整凭据仅创建时返回，创建结果未知时先查询状态。

### Changed

- Git hooks 改为通过 `make setup-hooks` 显式启用，提交前仅检查暂存区格式与空白，不修改工作区。
- 发布辅助脚本在退出时可靠清理临时目录和锁，并为下载增加有界重试、超时和阶段诊断。

### Fixed

- 固定 AI 卡片协议 JSON 的 Git 检出换行为 LF，修复 Windows 自动转换 CRLF 后协议哈希校验失败、卡片查询和校验命令无法使用的问题。

- 修复 Windows 鉴权文件替换遇到短暂文件占用时的失败，保留旧文件并对受限错误执行有界重试。
- 修复 Linux Skill 安装期间的目录身份校验，固定目录句柄并在结束后释放。
- 修复产品命令根名称与产品 ID 不一致时的 Schema 缓存定位。
- AI 听记整包导出支持服务端明确成功的空摘要，仍保留分析等待器的严格判断。
- 钉钉招聘创建职位时正确处理校园招聘默认值，并保留 Connector 返回的业务错误信息。

### Security

- **Password argv sanitization** — add `--password` to the timing/perf report sensitive-flag allowlist so `SanitizeCommand` redacts it in both `--password <value>` and `--password=<value>` forms. This also fixes a pre-existing plaintext leak where `dws drive publish set --password …` wrote the raw secret into the `DWS_PERF_REPORT` argv record. The `drive permission set-share-scope --dry-run` preview now masks the password value as `***` while still emitting `requirePassword`; real calls keep sending the correct secret and no business RPC is issued during preview.


## [1.0.63-beta.3] - 2026-09-23

### Fixed

- **darwin/amd64 release asset fails to launch** (#1441) — the CGO cross-link defaulted the x86_64 deployment target to macOS 10.13, so ld64 emitted `__DATA_CONST` without `SG_READ_ONLY` and current dyld aborts the binary before `main()`. Release builds now pin `MACOSX_DEPLOYMENT_TARGET=11.0` (matching the arm64 floor), and the signed-artifact verification statically checks the `SG_READ_ONLY` flag and launches every Darwin asset it can execute before publication.


## [1.0.63-beta.2] - 2026-09-22

### Changed

- Standardize `dingtalk-tag manage create/list/save-draft` on `--type` and `set-visibility` on `--user-ids`, keeping help and Skill guidance focused on canonical flags while preserving existing script compatibility and MCP field mappings.
- Document `set-visibility` in both mono and multi Skill references, including ALL/PARTIAL scopes, full replacement semantics, omitted-list clearing, the userId-to-staffIds mapping, and confirmation requirements.
- Send only supported fields in publish requests and keep compatibility handling silent in both preview and execution.

### Fixed

- Accept optional `--prompt` when creating digital employees. Save custom prompts in the new draft, default omitted prompts only for `local_agent`, and remind other supported types to configure a prompt before publishing without blocking draft creation.
- Include prompt initialization in dry-run previews and retain the created employee ID with recovery guidance if subsequent draft initialization fails.

- Initialize a missing platform prompt before publishing a local_agent employee, preserving existing prompts and stopping publication when draft lookup or initialization fails. Dry-run retains its request preview contract and includes the conditional steps without remote calls.
- Reject explicitly empty or whitespace-only save-draft text fields in both preview and execution, while preserving omitted fields. Clarify the coordinated server contracts for no-op draft saves and draft/published snapshot responses.


## [1.0.63-beta.1] - 2026-09-22

### Added

- **Attendance approval helpers** — adds shortcuts to calculate attendance approval duration, validate travel/out-of-office companion schedules, and query employees' effective complex overtime settings. Proposed overtime durations (total and per-day detail entries) must be finite positive numbers matched to the requested duration unit, and numeric detail-list work dates must be 13-digit millisecond timestamps; anything else is rejected before the server call. Flag help publishes each custom constraint's decision facts so the delivered schema keeps the validation contract visible to agents, and the detail-list help matches the two-stage workflow (second-stage input; the first stage omits it to obtain the server's per-day skeleton).

- **Auth status read-only snapshot** — `dws auth status --readonly` observes the local credential snapshot without the authentication lock, network validation, refresh, migration, or credential writes, keeping the same output fields as normal status and reporting inconclusive local state through explicit `reason` codes instead of a confirmed logout.

- **Contact user lookup by dingtalkId** — adds `dws contact user get-by-dingtalk-id --id <dingtalkId>` (alias `search-dingtalk`) to retrieve a user's `userId` from their dingtalkId.

- **数字员工管理与能力资源** — 新增 `dws dingtalk-tag manage`、`capability`、`run`，覆盖创建、草稿保存、发布、查询、Skill ZIP 上传、员工域 MCP 创建与运行追踪；统一 `agentUuid`，支持双响应模式与 `open_code` / `local_agent` 类型。MCP 创建自动追加草稿依赖配套服务端，不自动发布；Skill/MCP 选择支持省略保留、空数组清空和非空数组替换。
- **员工身份登录** — `manage login` 串联授权码申请、换票、在线身份核验和精确 Profile 保存/刷新，保持主管当前 Profile；补充外部 `auth exchange`，不在普通输出中返回授权码或 Token。
- **本地 Agent 接入** — `dingtalk-tag connect` 支持本地 Agent Adapter 与 DSH，提供员工隔离的事件处理、生命周期、设备绑定及失败恢复；仅登录员工身份使用 `manage login`。同步 Help、Schema、mono/multi Skill 与必要接口文档。

- 统一 `dingtalk-tag manage` 的 `agentUuid` / `userId` 用户契约：创建时部门可省略，草稿按字段更新并分开 Skill/MCP 输入，本地头像可安全上传且不暴露临时凭证。
- 直属上级的输入与输出统一使用 `supervisorUserId`；HSF 历史字段名仅保留在 MCP 映射边界内部。
- 头像统一使用 `avatarUrl`；`--avatar-url` 同时支持公网 HTTP(S) 与本地图片，本地文件复用 Skill 上传封装并自动回写。
- 创建、更新的主程序类型映射到 MCP `digitalTagEmployeeProfile.type`；列表筛选仍使用顶层 `type`。CLI 保留 `--main-program-type`，详情查询改为 `--snapshot draft|published` 并发送 `snapshot`，兼容旧 `--type` 别名。
- 创建时响应模式缺省或为空，默认发送 `mention_only`；更新未传则保留原值，显式响应模式不会被默认值覆盖。发布前的完整配置由服务端校验。
- 登录/连接使用已发布详情的 `profile.corpId/userId`，不再要求旧 `robotUid/staffId` 字段；换票后仍在线核验身份，再保存精确 Profile。
- MCP 创建/替换配置的帮助、Schema 与技能示例明确要求显式填写 `configString.mcpServers.<名称>.type`（`streamable-http` 或 `sse`），避免只有 URL 时服务端校验失败。
- 创建数字员工必须显式指定 `--main-program-type open_code|local_agent`，DWS 本地拒绝缺失或空值，帮助/Schema/调用说明同步标为必填；更新不传仍保留原值。

- **Mail employee lookup by corporate email** — adds `mail user get --org-email`
  and `mail user batch-get --org-emails`, with Schemas for
  `mail.get_user_by_org_email` and `mail.batch_get_users_by_org_emails`.
  Batch lookup accepts 1–100 addresses before deduplication and returns matched
  employees plus `notFoundOrgEmails`. Both declare required input mappings,
  read-only safety, and result fields, and use platform-injected operator and
  organization identity.
  Direct single lookup validates the employee result and declared field types
  before reporting success, while retaining null/omitted not-found results and
  exact integer IDs. This check does not reject a batch because one item is bad.
- **Mail batch partial results** — preserves confirmed employee and not-found
  results when individual inputs or response records fail. Partial output
  separates `succeeded`, `failed` and `unknown` entries (exit code 7). An explicit
  server rejection of an invalid batch address falls back to at most 100
  deduplicated single-address lookups, including errors classified by the
  runtime transport; global authentication, permission and
  connection failures do not trigger that fallback. Unconfirmed results are
  never reported as not-found.
  Address-validation fallback recognizes the live service code `1001` as well
  as `SYSTEM_ERROR`; unrelated errors with either code remain failures.
  During fallback, global failures retain their original classification and
  exit status, with confirmed progress in structured error
  `details.partialResult`. Cancellation and raw PAT authorization errors are
  returned to the framework unchanged instead of becoming partial success.
  Agent guidance requires reading confirmed members from `succeeded` even on
  exit code 7, continuing authorized follow-up work with them and reporting
  unmatched, failed and unknown addresses.
- **Large integer output precision** — preserves integer IDs beyond the exact
  `float64` range when decoding MCP text responses and through `--jq`, `--fields`
  and formatted output.
- **International login is English-first** — `dws auth login --intl` now renders
  its terminal copy, the DingTalk authorization page (`lang=en-US`) and the
  callback success page in English without requiring `DWS_LANG=en`. A locale
  inherited from `LANG` no longer forces Chinese output; set `DWS_LANG=zh`
  explicitly to keep the Chinese copy. Domestic (`.com`) login keeps following
  `DWS_LANG`/`LANG` as before.

- **Wait framework capability** — adds the reviewed `Contract.Wait`
  declaration (`contract.WaitSpec`) with three execution modes: `poll`
  (cadence-poll the leaf's `WaitPoll` hook), `event` (consume the leaf's
  `WaitEvents` push stream, correlate events to the accepted resource via
  `match_field`/`resource_query`, apply the same terminal map), and `auto`
  (event first, fall back to polling when the stream ends or the
  subscription fails — one deadline spans both phases). Declared commands
  must use the `ResultInvoke` dispatcher; mode and hooks are paired at
  construction (poll↔WaitPoll, event↔WaitEvents, auto↔both; surplus hooks
  are rejected too). Declared commands register `--wait` /
  `--wait-timeout` (framework-owned flags that never enter MCP toolArgs);
  undeclared commands reject the flags as unknown. The wait phase closes
  the unified envelope exactly once: terminal success → `success`,
  terminal failure → `failure` with new wire-stable `error.type: "wait"`
  (exit code 8), timeout → `pending` with `meta.operation.timed_out: true`
  and the last observed state (exit 0). Deadline exhaustion during a poll,
  during event consumption, or between polls always closes as timed-out
  pending, never as a poll/stream failure; a correlated event with an
  unknown status fails closed exactly like a poll. The pairing also closes
  the overlay path: `AttachContract` / Tier2 metadata attaches cannot
  publish a wait declaration (no hooks, no flags, no wait phase behind
  it) — only the managed `New` construction can. At Schema assembly every
  `poll_command` is resolved against the bound registry and must name a
  delivered, agent-visible read command, so the declared manual resume
  path cannot drift from the command tree. The capability is
  projected into the Schema catalog (`wait` key) alongside `dry_run`. No
  business command declares it yet; approval/export/batch adoption lands
  separately.

### Changed

- **Smart chat read shortcuts** (`+chat-messages`, `+at-me`, `+search-msg`, `+thread-replies`) now decrypt third-party encrypted (SafeChat) message ciphertext before projection when the message crypto policy allows it. Message projections gain `contentDecrypted`, `cryptoLayer`, and `dingKeyVersion` (when > 0), and payloads gain an additive decrypt ledger (`decryptCandidateCount`, `decryptAllowedCount`, `decryptedCount`, `decryptFailedCount`, `decryptFailures[]`). Single-item failures land in the ledger with `partial: true` and never change the command exit code. Policy-off keeps the ciphertext and records one `policy_disabled` failure per candidate, so the additive ledger appears with `decryptFailedCount >= 1` and the existing `partial` field can flip to `true`; only stub builds and `--dry-run` short-circuit the decrypt pipeline and keep output byte-identical to the previous behavior.
- **`intField` in the message crypto module now accepts `json.Number`**, so `keyVersion` fields surfaced as JSON numbers by the MCP runtime are parsed instead of being silently dropped. The atomic chat read path may now emit `dingKeyVersion` on decrypted message projections (additive and within the existing result contract). Parsing `ttlSeconds` the same way means the crypto policy cache now honors the server-provided TTL: atomic reads fetch the policy once per conversation within the TTL window instead of once per message.

- Introduce Schema delivery inside the existing Schema command of the single `dws` executable. Production does not produce or embed Schema identity at compile or release time. On supported ends (darwin/linux/windows amd64/arm64) each machine generates identity from live declarations at install or first `dws schema`, writes authenticated protobuf shards under the shared or user cache directory, and later hits verify digests then read those shards. Miss or corruption repairs from live assembly; when the shared cache exists but cannot be locked for repair (typically root-owned read-only), the repair falls back to the per-user cache and later processes reuse it. Empty local identity generates then uses the cache; it is not a permanent live-only mode. When plugins or other runtime extensions change the command surface, cache assembly and repair are delegated to an isolated child process using the pristine pre-registration environment, keeping persistent cache active without inheriting plugin runtime side effects. Plugin commands never enter the Schema surface, cached or live. The POSIX installer only advertises a cross-user shared cache when the warmed artifacts are root-owned, matching the runtime's shared-path ownership rule; a cache warmed by an ordinary user under a writable custom root is reported as installing-user-only instead.
- Keep one complete Cobra tree for every public invocation. Compact typed metadata and shared builders reduce complete-tree allocations; process argv does not select a product factory or a utility-only tree.
- Reduce temporary allocations during Schema validation and command initialization.
- Normative notes live in `docs/rfc-schema-runtime-cache.md` only; no sibling plan/design/performance pages are kept.

### Removed

- **Retire legacy contract review CLI leaves** — hide `dws contract review benefit|create|analysis|result` from help and mark their Agent Schema availability `unavailable`. The commands remain as hidden historical argv stubs and fail closed with `command_retired` without calling legacy review MCP tools. The `review` group stays visible because hiding it is not in the consumed ledger. Ledger `schema_availability_hardening` entries are consumed.

### Fixed

- **OA TableField examples** (#1347) — correct mono and multi skill examples to encode detail rows as a two-dimensional array of `name`/`value` objects, and clarify that both creation modes preserve the serialized value without converting row objects.

- **Persistent Schema cache with plugins** (#1400) — delegates Schema cache assembly and repair to an isolated child process when plugins are present, keeping persistent cache active without inheriting plugin runtime side effects.

- **AI Table form sharing** now exposes server-returned `shareFormUuid`, status, and cover through shared structured result contracts for atomic commands and shortcuts; updates also publish `cpSynced`. Agent guidance requires confirming CP synchronization before reporting the sharing workflow as complete. Readback and CP projection remain the server's responsibility; DWS does not issue a second view update or construct cover URLs.
- Atomic and shortcut updates now share strict terminal validation. Missing or invalid required fields, including `cpSynced=false`, produce `partial_failure` (exit 7), preserve the remote response and mark remote execution as started without retrying the write. Result Schema documents both verified success and partial-stage evidence. Usage guidance distinguishes supplied IDs from placeholders and preserves the shortcut JSON flag.
- Terminal validation binds `baseId`, `tableId`, and `viewId` to the original request before accepting CP synchronization. A complete response for a different form is still `partial_failure`, even with `cpSynced=true`; both command entries retain the raw response and never replay or compensate the write.
- Terminal validation also compares the explicitly requested `enabled`, `formName`, and `formDesc` against the echoed readback, so a response reporting different values is `partial_failure` rather than success. Requested properties the helper never echoes cannot be proven, so verified success reports `verified=false` and lists them in `unverified` instead of implying they took effect.
- All four form-share Result Schemas accept their real dry-run request previews, including the optional shortcut `dry_run` marker. Preview success never implies remote execution or CP synchronization; assembled-leaf regression tests validate real envelopes against both full and compact JSON Schemas.
- Skill discovery preserves the requested atomic/shortcut entry for result reviews instead of substituting usage Help. Interpretation selects the actual result branch and does not invent required fields or copy Schema evidence into malformed samples.

- Recovery reviews preserve the target named in the original user request before Skill loading. Agent-authored Skill arguments cannot turn a background write into an additional contract-review target; this scope boundary is visible in discovery metadata as well as the loaded body. Synthetic JSON receipt reviews also load the product Skill: prohibiting online business operations does not skip local contract discovery or permit generic guesses about product-specific fields.

- **AI Table write recovery**: `+table-copy` and `+record-batch-create` now generate one UUID v4 `clientToken` per create batch, submit it once, and reconcile uncertain receipts through MCP `get_record_write_result`. A fully recovered ID set is independently checked against record values before continuing. Unknown or partial results preserve the token/IDs and stop without replaying creation. The new read-only `+record-write-result` command exposes the recovery path in Help and Schema.
- **AI field readiness**: `+field-create` recognizes MCP `CREATE_FIELD_READBACK_PENDING`, keeps the created IDs, and uses the existing bounded exact-ID readback/resume path. `+field-run-ai` requires readable `aiConfig` before mutation and reports `submitted` only for complete per-field task receipts; submission is not computation completion.
- **Review follow-up**: duplicate-token errors and explicit `get_record_write_result` recovery hints no longer count as input rejections, even with `retryable=false`. They use the original token for read-only reconciliation and value verification; ordinary input rejections still stop immediately.
- **Recovery evidence**: unknown creates without returned IDs do not advertise known effects. The read-only reconciliation command includes its Intent, and its Result Schema distinguishes verified `applied` results from dry-run previews and rejects unknown or incomplete success objects.
- **Pagination recovery**: record queries classify business errors before accepting an empty terminal page. Invalidated cursors discard accumulated records and continuation tokens, return non-retryable restart guidance, and stop composite workflows before further writes.
- **Agent recovery guidance**: the Shortcut Schema and mono/multi pagination references distinguish invalid snapshots from ordinary resumable failures; stale snapshots must discard prior rows and cursors, never deduplicate and concatenate pages across snapshots or replay a composite write.
- **Pagination review boundary**: mono/multi references separate a concise, complete recovery assessment from operational query recipes. Unknown or incomplete writes remain read-only until reconciled; comparing query results is not permission to infer missing records or propose incremental create/backfill.
- **Focused recovery discovery**: field-create Help/Schema explains `CREATE_FIELD_READBACK_PENDING` and bounded same-ID verification. Result-only reviews stay on the requested recovery command instead of expanding to its upstream write command or inferring unpublished Result fields from repeated discovery.
- **Skill loading and routing**: keep the AITable skill description focused on capability selection, with execution examples in the loaded body. Contract reviews preserve the requested command identity and query only that command, without treating background writes as additional discovery targets. Regression tests enforce this metadata/body boundary and all four exact form-share review routes.
- **Recovery review clarity**: lead with the requested read-only next step and safety decision, distinguishing local contract discovery from unverified remote state. When no command is requested, answer all safety questions up front—write replay, retained/discarded results, and read-only recovery prerequisites—before detailed explanation. Unknown or incomplete results retain the original Base/Table/token reconciliation route instead of switching to full-table queries. Reconciliation Schema explicitly treats records missing from the returned ID set as unverified, never as a count-based backfill plan.
- Deployment dependency: the paired MCP branch must be deployed and the new read-only tool registered in the gateway. No `lippi-doc-notable` changes are included. Local mock/contract tests do not establish live service readiness; real-environment evaluation remains a separate deployment check.

- 登录过程中使用临时 Token 补全身份时，立即应用本次登录的 MCP 端点覆盖，包括国内及国际预发；不再等待登录成功后的 `mcp_url` 持久化。显式产品端点、第三方地址和插件所属路由保持原值，查询不读取旧 Profile。

- Windows 原生覆盖率作业的总时限从 20 分钟调整为 30 分钟，为完整测试批次、工具链准备和产物上传保留余量，避免接近 20 分钟的运行被取消。测试范围、单批测试超时、100% 变更代码覆盖率门禁及汇总依赖检查保持原有要求。

- **DEK missing relogin** — Allow reauthorization when the local login encryption key is missing. Keep old ciphertext until a fresh credential is available, then replace only the login write targets and create a new encryption key as needed. Refresh and transient Keychain failures retain their existing protection.

- 数字员工 Skill 创建和更新使用同一个已打开的文件完成 ZIP 校验与流式上传，避免校验后重新打开路径时把替换文件或符号链接目标上传。上传仅读取校验时的文件大小，句柄在操作结束（包括 dry-run 和失败）后关闭。
- 补充普通文件替换和符号链接替换的 create/update 回归测试，保留打开前对命名管道等特殊文件的拒绝；增加 `dingtalk_tag.skill_package_validated`、`dingtalk_tag.file_upload` 本地诊断事件，仅记录大小、阶段、接口路径、成功状态与耗时，不记录本地路径、文件内容、身份或凭据。

- 修正数字员工接入的事件传输就绪判断：使用上游真实状态并报告断线重连，区分 IPC、Agent 初始化和事件连接；DSH 状态交叉验证同一员工的 Event Bus，旧版或未知连接不再报告传输就绪。
- 数字员工本地 Agent 不再固定指定事件来源为 `digital_employee`，改为沿用 Event 默认规则：优先读取 `DWS_STREAM_SOURCE_ID`，未设置时开源版使用 `open`；升级后需重启员工 worker 生效。
- 个人 Stream 正确响应系统 ping/disconnect，不将系统控制帧投递为业务消息；订阅查询兼容 `items`/`list` 及字符串/整数时间戳。
- 修正 Windows 下正常停止可能被误报为消费者异常退出，以及损坏的任务/绑定目录被误当作不存在的问题；补充跨平台身份、绑定回执、上传失败、重试隔离和日志脱敏回归测试。

- **单聊引用回复** — 会话信息明确返回 `singleChat: true` 时，即使省略群聊话题开关，也能正常引用回复；保留会话身份、响应有效性及话题标记校验。

- **OA approval event fields** — preserve `staff_id`, `activity_id`, `corp_id`, and `business_id` from the business payload in `event consume --flatten` for all seven OA approval events, and expose `cc_time` for approval instance CC events. Optional fields remain omitted when absent; an explicitly provided zero `cc_time` is preserved.

- **Legacy token pre-login recovery** — Allow OAuth, device, auth-code, PAT, and `--token` reauthorization to start when the legacy `auth-token` ciphertext has a confirmed DEK mismatch. The old ciphertext remains untouched until fresh credentials are available, then only the login's target slots are replaced; transient and unclassified Keychain failures still fail closed.

- **Windows cgo 崩溃**：重新编译 Windows amd64/arm64 预编译 `libsafechat.a`（消除 legacy `_vsnprintf`/`__imp__*` dllimport 引用），并移除已无必要的 `msvcrt_compat_windows.c` 旧 CRT 桥接层，修复官方发布包在 Windows 上初始化 safechat（cgo）即崩溃的问题。

- Root help renders the live complete Cobra tree, so explicitly registered supplement-backed commands stay visible alongside products and utilities. There is no separate declaration-derived help snapshot.

- **Command validation errors** — report framework-owned parameter failures consistently as validation errors with exit code 3, while preserving API errors, explicit exit codes, cancellation, and deadlines.
- **Parent and proxy flags** — route parent traversal and wiki proxy parse failures through the same validation boundary and preserve target command hints.

- **Required flag wording** — framework-prepared commands now report `missing required flag(s): --name` instead of Cobra’s `required flag(s) "name" not set`. The original Cobra error remains available as the cause.

- **Generated commands** — normalize native validation failures in lazily created help/completion commands, and remove duplicate required/group checks while retaining business hook order.


## [1.0.62] - 2026-09-16

This stable release promotes the sealed `v1.0.62-beta.8` baseline and adds verified AI Table, document, event, calendar, chat, AISearch, and language-default improvements merged afterwards.

### Changes since `v1.0.62-beta.8`

### Added

- Add AI Table shortcuts for exact field/view resolution, bounded record reads and NDJSON export, batch record/field creation with readback and recovery, App pages and widgets, forms, dashboards, aggregation, and attachment downloads. Preserve existing entry points and equivalent aliases; reject incomplete pagination, mismatched write verification, and unverified AI submission receipts instead of reporting success. Downstream capability and permission limitations remain explicit.

- **Doc shortcut workflows** — add local and online document structure checks with `doc +script`, verified standalone media upload with `doc +media-upload`, optional title fallback, and ordered media attachments during document creation.
- **Doc reading and editing** — add direct-folder search filtering, readable date filters, chapter and regex block-context reads, document comments, and verified same-document block copying and range editing while preserving existing commands and aliases. Range edits remain sequential, not atomic.
- **Doc media controls** — add clipboard image input, attachment preview/summary selection, vertical cover positioning, persistent preview output, and explicit download overwrite; fix tag filtering and keep upload progress off JSON stdout.
- **Doc download confirmation** — use `doc +download-overwrite --source media|cover` for confirmed replacement of local files. Existing media, preview, and cover downloads retain their no-clobber behavior and safety contracts; preserve the preview output shorthand `-o`.
- **Create with media confirmation** — use `doc +create-with-media --media-files` to create a document and upload local images or attachments after confirmation. Plain `doc +create` retains its published behavior and does not accept media uploads.

### Changed

- **AITable query routing** (#1342) — clarifies routing among raw record queries, server-side statistics, PostgreSQL analysis, and full data export.

- **默认界面语言** — 未设置语言或语言值不受支持时，默认使用简体中文；保留 `DWS_LANG` 优先于 `LANG` 的解析顺序及显式英文设置。

### Fixed

- **Personal events** now obtain managed AppKey metadata when it is missing locally in open-source normal mode, without requiring an AppSecret or changing saved credentials. Existing application identities retain precedence, background listeners reuse the resolved AppKey, and metadata failures report actionable retryability.

- Clarify AISearch evidence checks for time, identity, relevance, uniqueness, and same-condition handoffs to native products.

- Guide newly shared AI Table forms to pass their known title through `--form-name`; require usage-only Agent answers to perform exactly one safe leaf discovery query, then lead with a complete command or an explicit placeholder template without guessing missing IDs, and state that omitted share settings stay unchanged without claiming execution; reject undeclared record-comment rich-content fields before invoking MCP; preserve actionable comment visibility errors; and move AI Table comments, record ID pagination, entity search, and PSQL machine output onto reviewed unified result contracts whose dry-run previews satisfy the published Result Schema and whose comment pagination guidance reads continuation state from `meta.pagination`.

- **Calendar invitation receipts** — fixes false `readback_attendee_missing` failures from `calendar +invite` and `calendar +book --with` when participant responses omit user IDs and display names differ from directory names. Invitations require an explicit successful write receipt and report `verified=false`; `+invite` adds `acknowledged=true`, while `+book --with` adds `attendeesAcknowledged=true` and retains event readback through `eventVerified=true`.

- **Chat rich-text links** — preserve link-item URL targets alongside their labels in message projections, including links without labels.


## [1.0.62-beta.8] - 2026-09-11

### Added

- **OA approval template management** (#1346) — add
  `dws oa approval template list` and `detail --template-code <code>` for
  querying manageable approval templates, form schemas, and process
  configuration.

- **Interactive card callback events** ([Aone 86136546](https://project.aone.alibaba-inc.com/v2/project/2125919/req/86136546)) — `dws event consume user_card_action_triggered` reuses the personal-event subscription lifecycle with the same empty-object filter rule as IM/OA. Its flattened schema describes typed answers and questions under `payload.body.actionData.context`, business/conversation/operator fields under `payload.body`, and millisecond timestamps while preserving unknown fields for forward compatibility.

- **AI 表格记录评论** — 新增评论的分页查询、创建、回复、完整更新和删除命令，支持纯文本、@人员及已上传图片。

- **Calendar event options** — adds `--is-all-day` and `--add-online-meeting` to `calendar event create` and `update`, with omission-preserving boolean updates. Explicit all-day state changes require both start and end values, validated as dates or timezone-bearing date-times for the selected state.

- **A2UI card options** — adds optional `--a2ui-annotations` JSON object arrays to card creation and updates, and `--support-forward` to creation (defaults to false).

- **Public Agent Skills CLI** — `npx skills add DingTalk-Real-AI/dingtalk-workspace-cli -g` installs the per-product `dingtalk-*` skills after confirming the skills, target directories, and existing same-named content handling. The all-in-one mono `dws` skill is marked `metadata.internal: true` so it is not a default installable skill. `dws skill setup` remains the China / upgrade / ownership path.

- **Schema 时间格式声明** — 支持字符串参数以 `anyOf` 声明多个格式，并为日历创建/更新的 `date-time` 到 `date`/`date-time` 扩展及全天状态条件必填提供精确、基线持有的迁移校验；其他格式和条件必填变更仍被拦截。

- **Standalone whiteboard export** — adds `whiteboard export` and `whiteboard export-get`
  to download PNG/PDF exports. Both commands support request-only dry-run previews.
  Signed URL query strings do not affect filenames; downloads validate their file
  signatures before atomic publication and never overwrite existing files. Failed
  tasks retain recovery instructions with the job ID, format, and output directory.
  Downloads enforce HTTPS/443 public network targets on redirects and actual
  connections, with a 512 MiB limit for both declared and streamed response sizes.

### Changed

- **AI Table CLI safety and compatibility** — adds safe entity resolution for view filters, strengthens dashboard, workflow, import, record, and table validation, supports the latest Base copy and share-form protocols, and aligns Runtime Schema and Skill guidance with observable MCP behavior.

- Update the embedded CLI telemetry SDK to v0.4.0 and send completed command events from a bounded background process, preserving existing telemetry fields and keeping network waits out of command execution.

- Update the embedded runtime SDK to 20260909 and remove auxiliary ps files from builds and runtime extraction, reducing single-binary package size.
- Refresh the macOS universal runtime library while retaining the 1 MiB payload slot and using the payload digest to upgrade existing installations of the same resource version.

### Fixed

- **Direct-runtime MCP endpoint resolution** (#1331) — restore the
  environment-aware `mcpdev` endpoint so `dws dev mcp` commands reach the
  backend instead of failing locally with `endpoint_not_resolved`.

- Automatic pagination now preserves cancellation when the page-delay timer and
  context cancellation become ready together, rather than randomly continuing.

- **OA approval list response types** (#1351) — normalize `success` to a
  boolean and numeric error codes to `errorCode` for pending, submitted, and
  copied approval lists while preserving business data and diagnostics.

- Preserve optional `--source-config` for AI Table datasource updates: read and reuse the complete existing configuration when omitted, and stop before updating if the read cannot provide a valid configuration.

- **AI Table capability routing** — isolates concurrent multi-profile discovery so each `tools/list` request uses the selected account without changing the process-wide profile.

- Include the available runtime context in manual OAuth and device authorization links, including `--no-browser`, so copied links match browser authorization. Display device links outside a frame to keep long URLs copyable on narrow terminals.
- Stop adding the CLI locale as a `lang` query parameter to browser, manual, and reauthorization login links.

- **Chat read completeness contracts** — makes conversation and message reads distinguish normal bounded truncation from terminal pagination, projection, enrichment, and resource-download failures. Incomplete reads retain their canonical partial result and typed retry diagnostics, while newly declared Result and pagination contracts remain in byte-compatible dual validation before activation.
- **Chat routing and bounded discovery** — distinguishes conversation categories from real chat groups, aligns reviewed Shortcut owners with runtime selection and references, and steers agents toward narrow leaf Schema before a single exact Help fallback.
- **Public Schema constraint closure** — normalizes reviewed hidden aliases to their public parameters and rejects constraints that cannot be represented without exposing hidden runtime inputs.

- **Drive and Wiki agent workflows** — align pagination, confirmation, target verification, recovery receipts, and Reference routing with runtime behavior.

- Stop implicit HTTP retries of MCP tool invocations after gateway or connection failures, preventing duplicate datasource updates and other remote writes. Discovery and explicit read/reconciliation retry policies retain their existing behavior.

- **Minutes artifact evidence** — distinguish empty action items, unsupported responses and speaker-task terminal states; preserve list display metadata and complete upload/permission preview options.
- **Minutes export and delivery** — remove signed credentials from exported text, keep partial results explicit, and align time conversion, pagination, permissions and cross-product report guidance with verified runtime behavior.

- Fix the Windows whiteboard export test to compare decoded JSON paths, and run platform app coverage tests in fresh batches while retaining the full test selection, cross-package instrumentation, and coverage gate.

### Security

- **AI 表格文件导入** (#1349) — 将上传白名单收紧为服务配置的精确 OSS Bucket 主机与导入对象路径，拒绝同区域其他 Bucket、区域根域和路径式 Bucket URL；复用公网传输 IP 策略，在上传前阻止共享地址段、保留地址及特殊 IPv6 目标。


## [1.0.62-beta.7] - 2026-09-09

### Added

- **Chat active conversations** — adds `dws chat +active-conversations --start <time>` to auto-page cross-conversation messages and return deduplicated conversation summaries with stable name fields, latest-message time, and completeness metadata. Query boundaries use whole seconds: explicit nonzero fractional seconds are rejected, and the default end is rounded down to exclude the current unfinished second. The effective end must be later than the start and remains fixed across pages, results, and continuation; latest-message timestamps retain millisecond precision. Returned messages are filtered to the fixed `[start,end)` window before aggregation; pages with no matching messages still follow server pagination. Pagination waits 200ms between pages by default; later-page failures preserve completed summaries and a continuation cursor as `partial_failure` (exit 7). Resume with the original time window, page size, and profile, then merge batches by conversation ID.

- **Chat shortcut 对齐与查询校验** — 补充兼容别名、创建默认值、消息上下文定位、文本与 Thread 回复、筛选排序及分页控制，保留原入口；共享消息富化并严格区分空集合、不完整结果与失败，增加资源分段重试、版本校验和原子落盘。下游尚未支持或未实测的身份、消息类型与权限范围单独列明。

- **Contact invite/apply administration** — adds `dws contact exclusive-account
  disable|enable` for enterprise-account status, a `dws contact org`
  invite/apply group (`invite-switch`, `invite-audit`, `invite-info`,
  `invite-list`, `apply-list`, `apply-approve`, `apply-reject`, `apply-block`,
  `apply-remove`), and `dws contact dept invite-audit` for department-level
  join-request auditing.

- **Standalone whiteboards** — adds OpenNodes-based `whiteboard create-with-content` and extends
  the existing `whiteboard query` / `whiteboard update` entry points to operate
  on standalone boards when `--part-id` is omitted, while preserving the
  document-embedded flow when it is explicitly supplied. Standalone reads
  decode the service `resultJson`, and writes enforce revision and stable
  request-ID guards with compatible receipt validation and same-type read-back.

### Changed

- **CLI auth apply pending page** (#1285) — the browser apply flow now lands on a
  dedicated approval-pending page that polls and auto-redirects after approval;
  duplicate apply requests are idempotent, and all local callback pages and API
  responses are served with `Cache-Control: no-store` to avoid stale state after
  a page refresh.
- **CLI access denial copy** (#1285) — terminal denial reasons are now split by
  whether the path is applyable. `cli_not_enabled` keeps the apply flow and shows
  a personal-scope message ("you do not yet have CLI data access") with the
  approver picker relabeled to "select approver"; the inline success message was
  replaced by a redirect to the pending page. The non-applyable `user_forbidden`
  and `user_not_allowed` reasons now share a single consolidated terminal message
  ("this organization has not enabled CLI data access") across the browser page and
  both login transports (OAuth browser flow and device flow).

- **Chat recent conversations** — makes `--start` optional for `dws chat +recent-conversations`. Omission selects the 24 hours before the effective `--end`; omitting both boundaries selects the latest 24 hours ending at the current time rounded down to a whole second. Explicit `--start` retains the existing time formats, whole-second validation, and blank-input rejection. Both effective boundaries stay fixed across pagination and are returned in the result. Non-initial `--cursor` requests must explicitly reuse the previous `--start` and `--end` to preserve the original query window.

- **Chat recent conversations** — makes `dws chat +recent-conversations` the preferred entry and retains `+active-conversations` as a hidden executable compatibility entry sharing the same implementation, without deprecation warnings in execution, Help, or Schema. Public Help, Schema primary CLI paths/examples, and Mono/Multi Skills recommend the new name; the stable Schema identity `chat.shortcut_active_conversations` and old CLI-path lookup remain supported. Query windows, pagination, and result semantics are unchanged by this rename.

- **Runtime context** — Refresh the embedded payload to `20260908`, verify and materialize owned resources beside the resolved executable with cache fallback, and attach the process context to browser login URLs while keeping terminal links and diagnostics redacted.

### Removed

- **移除顶层 `dws safechat` 命令（破坏性变更）** — 删除 `dws safechat selftest` 与 `dws safechat decrypt`。这两个命令在 `1.0.62-beta.3` (#1051) 交付，但只在显式 `-tags safechat` 的源码构建中存在：官方 Release 一直是 `CGO_ENABLED=0`，stub 的 `newSafeChatCommand()` 返回 `nil`，因此官方二进制从未包含该命令，受影响的只有自行打 tag 构建并升级的用户。SafeChat 现在是 `internal/msgcrypto` 的内部后端，仅通过聊天消息加解密路径暴露，不再提供独立顶层命令。
- **迁移方式** — `dws safechat decrypt` 的等价入口是 `dws chat crypto decrypt`，它走同一套 SafeChat 后端并按策略解密。`dws safechat selftest`（真实取码与密钥获取的端到端自检）没有等价命令；需要验证后端可用性时改用 `dws chat crypto decrypt` 对一条真实密文做一次解密。

### Fixed

- **Contact apply-list safety semantics** — `dws contact org apply-list` marks
  unread join applications as read on the server; its schema safety effect is
  now declared as `write` (risk stays `low`, confirmation stays
  `not_required`) and the selection guidance discloses the read-marking side
  effect so Agents no longer treat it as a pure read.

- **Contact apply-remove safety semantics** — `dws contact org apply-remove`
  deletes organization join application records irreversibly; its schema safety
  effect is now declared as `destructive` (risk `high`, confirmation
  `user_required`) and the selection guidance discloses that the deletion is
  not recoverable so Agents no longer treat it as an ordinary write.

- **Contact org list pagination contract** — `dws contact org invite-list` and
  `dws contact org apply-list` now declare the unified cursor Pagination contract
  (`cursor` parameter, `meta.pagination` metadata) and their result data schemas
  no longer leak `hasMore`/`nextCursor`. Runtime responses project the server-side
  cursor fields into `meta.pagination` so Agents can resume paging from the
  standard contract.

- **Chat recent conversations pagination** — adds a shared `--total-timeout` budget (default 300 seconds, range 1–3600) across all requests, retries and page delays in one invocation. A timeout preserves validated pages in the partial-failure result and returns the failed page's input cursor. Cursor continuation remains caller-managed: reuse the same profile, time window and page size, and merge batches by conversation ID. Progress is not persisted to disk; forcibly terminated queries must be restarted.

- **Chat conversation categories** — treat `im/list_conversations_by_category` as the declared single-response interface when its explicit conversation array contains no pagination signal, while continuing to fail closed on partial or non-resumable pagination metadata. `+category-list-conversations` and `+feed-group-query-item` now publish the resolved pagination mode and source-exhaustion facts instead of rejecting every live response that omits `hasMore`.

- **SafeChat 默认构建与官方产物** — 支持平台的 CGO 构建无需额外 build tag
  即包含 SafeChat 后端，官方六平台 Release 固定使用可校验的交叉编译工具链并拒绝
  发布 CGO-disabled stub 二进制。
- 本地 `make build` / `make rebuild` 默认启用 CGO，并保留显式
  `CGO_ENABLED=0` 的 stub 构建选择。
- Linux 官方构建显式使用 glibc 2.17 链接目标，并校验 ELF 符号版本，
  防止交叉编译镜像升级隐式提高 Linux 系统要求。
- `install.sh` / `install-event.sh` / `install-devapp.sh` 在下载前识别 musl
  发行版（如 Alpine）并明确中止。Linux 产物依赖 glibc 动态加载器，此前这类环境
  会安装成功但连 `dws version` 都无法启动。判定以 `ldd --version` 为准，musl
  加载器文件只在 `ldd` 不报版本时兜底（Alpine 的 BusyBox `ldd` 仅转发给加载器），
  因此额外安装了 `musl` / `musl-tools` 的 glibc 发行版不会被误拒。
- SafeChat cipher 关闭时会等待进行中的加解密结束，不再与 `Close` 并发访问
  vendor client 的初始化状态（`go test -race` 下可复现的数据竞态）。

- **Schema 向后兼容检查** — 允许删除 `require_one_of` 必填组，以支持具备默认值或可自动解析参数的命令；保留新增约束、互斥、参数类型和身份安全检查，并通过基线拥有的两阶段评审机制交付。

- **Skill setup source resolution** — accepts an extracted `dws-skills.zip`
  root for `--source` / `DWS_SKILL_SOURCE`, selects its `mono` or `multi`
  subtree by mode, and no longer mistakes the compatibility `mono` directory
  for a single MultiSkill.


## [1.0.62-beta.6] - 2026-09-08

### Added

- **AI 表格 PostgreSQL 只读查询** — 新增 `dws aitable psql`，支持发现逻辑表和列类型，并执行只读 `SELECT`，包括同一 Base 内的多表 JOIN。

- **Native Markdown themes** — adds `--theme` to `markdown create` and
  `markdown overwrite`, preserving existing Front Matter while safely writing
  the selected we-markdown theme into a private upload copy.

### Fixed

- **AI 表格应用模式输入校验错误分类** (#1314) — 将 icon、background、config、layout 等字段的校验失败从 `internal` 错误和退出码 `5` 修正为 `validation` 错误和退出码 `3`；校验仍在 MCP 调用前完成。


## [1.0.62-beta.5] - 2026-09-07

### Added

- **AI 表格应用模式命令** (#1264) — 新增 `dws aitable app` 及 `page`/`widget` 子命令，支持 App 获取与更新、页面和 Widget 的创建、查询、更新、删除与排序。

- **文档块批量删除** — `doc block delete` 的 `--block-id` 支持逗号分隔一次删除多个块
  （单次最多 50 个）。采用尽力而为语义：单个 blockId 未找到不阻塞其余块的删除，
  未找到的在 `notFoundBlockIds` 中列出；仅当全部未找到时整体失败。

### Fixed

- **markdown @人 写后回读误报** — 写入含 `[@姓名](alidocs-mcp://doc/mention?openDingTalkId=…)` 的 markdown 时，`doc +create` 与 `doc +update --command append|overwrite` 会以 `doc_write_verification_failed` 报错，而内容其实已正确写入。原因是写后回读把写入原文与服务端改写后的正文比对，而服务端会把该私有协议改写成钉钉个人资料链接。现在写后回读改为**按位置配对**：只有预期正文中写了 mention 私有协议的那个位置，才允许回读侧是个人资料链接；其余链接——包括作者自己写的普通个人资料链接——仍保留完整目标并严格比对。显示文本与节点顺序照旧参与比对，漏写、改标签或顺序错乱依旧判定失败。原子命令 `doc update` 无写后回读，行为不变。
- **@人 目标身份不再被隐含声明为已验证** — 回读能证明 mention 链接落在作者写的位置、显示文本未变，但证明不了它解析到了哪个人：`openDingTalkId` 与改写后的 `staffId` 是不同值且无本地映射。含 mention 的写入结果因此在与 `verified` 同级处声明作用域：`verificationScope="partial"`、`unverified=["mention_targets"]`，verify 步骤状态由 `success` 降为 `partial` 并带 `scope="partial"`（只按 `steps[].status` 推进、不认识 scope 字段的既有消费者因此也不会再把它读成完整核验成功），另有 `verification.mentionTargetsVerified=false` 与一条说明性 warning，并把 `verified` 置为 `false`（操作本身仍 `status=success`）：回读无法确定 @ 到了谁，就不宣称已验证。另有 `unverifiableLocally=["mention_targets"]` 表明该缺口不是"还没查"而是"回读查不出来"，重读文档不会得到新信息。warning 只透两条事实：@人链接指向的具体人员需用户自行核对，正文其余部分（含该链接的位置与显示文本）均已通过回读校验。不含 mention 的写入输出完全不变。

- **Chat message decrypt fallback** — skips crypto policy lookups and decrypt failure ledger fields on chat read paths when the DWS binary does not include the SafeChat backend, while preserving policy-driven decryption after `chat message list --page-all` aggregates its pages.

- **AI Table view OR filters** — allows `aitable view update filter` to persist
  a single top-level `or` group while preserving flat-array AND behavior,
  rejecting nested logical groups, and verifying equivalent service readback
  shapes.

- **OA 空页分页兼容** — 待审批、已处理和已发起审批列表兼容成功响应中 `values:[]` 省略 `hasMore` 的终页编码，避免空列表误报 `missing_pagination`；保留显式分页值及业务状态、数组结构和其他接口的严格校验。

- **自动合并**：修复 Reviewer Router 将可合并但显示 `blocked` 的 PR 持续跳过的问题；恢复 App 的同步合并尝试，并继续由 GitHub 强制执行审批和必需 CI 检查。

- **Schema compatibility checks** — accept a new `require_one_of` group when a historical unconditional required parameter without a default already guarantees a supplied member. Other incompatible parameter changes remain rejected; CLI runtime behavior is unchanged.


## [1.0.62-beta.4] - 2026-09-04

### Fixed

- **Release dependency checksums** (#1288) — removes stale module checksum records so release validation remains reproducible after `go mod tidy`.


## [1.0.62-beta.3] - 2026-09-04

### Added

- **SafeChat message encryption/decryption** (#1051) — `dws safechat` commands enable AnHeng SafeDing (安恒密盾) message encryption and decryption. Available only in builds with `-tags safechat` (requires CGO and platform-specific static libraries). Commands include `safechat selftest` for end-to-end self-check (real authCode fetch and key retrieval) and `safechat decrypt` to decrypt ciphertext messages. The PR also adds `internal/msgcrypto` package with cipher operations, vendorAuthCode portal integration, and key server client supporting both in-memory and file-based keystores with 0600 permissions on Unix and warning logs on Windows.

- **Chat third-party message decrypt** (#1150) — adds policy-driven Ding + SafeChat message decryption for core chat read paths, explicit `dws chat crypto decrypt` diagnostics, and IM MCP wiring for policy lookup plus Ding batch decrypt. Outbound send encryption and `dws chat crypto encrypt` are intentionally not enabled in this PR.

- **html fetch / create / overwrite / patch** — full native `.html` / `.htm` file support in DingPan or the doc space, mirroring the markdown domain. `create` accepts a literal string, `@file`, stdin (`-`), or an existing local HTML file via `--file`. `fetch` downloads and prints the remote content (optional sanitized `--output`). `overwrite` replaces the whole file with before/after preview on command-level `--dry-run`; `patch` applies literal or RE2 replacements with zero-match never writing and an empty result aborting. Routing matches the markdown leaves: explicit `--space-id` / `--workspace`, auto domain probe, `--folder` read-only probe on create. Drive uploads submit the `text/html` MIME type. Implemented on a shared textfile engine extracted from the markdown leaves (pure refactor, behavior unchanged).

### Changed

- **Bounded CI app race fan-out** (#1278) — keeps all nine reviewed
  `internal/app` race-test partitions process-isolated while balancing them
  across three physical jobs, reducing focused and full-suite runner demand by
  six jobs without weakening partition coverage or increasing the 20-minute
  job limit.

- **Chat Shortcut-first discovery** — prioritizes Featured Shortcuts in
  `dws chat --help`, keeps the complete canonical Shortcut catalog discoverable,
  and points overlapping atomic command help to the reviewed Shortcut owner.

### Fixed

- **`aitable record query --all`** (#1016) — an empty final page that omits the `records` key now ends pagination normally instead of failing with `query_records response is missing records`.

- **Post-merge CI admission reuse** — reuses exact successful full-suite
  PR evidence for tree-identical protected-main merges and promotes the
  verified coverage artifact to the merge SHA cache, reducing duplicate runner
  work without adding jobs or weakening required contexts.

- **Chat role and category routing** — resolves natural group names before group-role operations, aligns role assignment guidance with required non-empty role IDs, and publishes a compact shortcut-first category workflow to reduce Help and Catalog discovery without dropping result, safety, or identity constraints.

- **Contract command safety and Skill routing** — Contract destructive operations (`archive`, `subject delete`, `subject batch-delete`, `project delete`, and `account delete`) now require explicit user confirmation (`--yes`) before executing, with Schema Safety `confirmation=user_required`. Batch project/subject deletion rejects empty parsed ID lists, subject deletion enforces the 1000-ID service limit, and required project/subject pagination rejects non-positive values before calling MCP. Account-list execution-time filters are documented consistently as ISO-8601 CLI inputs converted to MCP milliseconds. Legal smart-contract guidance is delivered through `dingtalk-misc` instead of a standalone first-level Skill, and the retired `edu-contact` endpoint is no longer registered as a supplement server.

- **Coverage baseline reliability** — balances the existing app test
  partitions across the current coverage runners and reuses the same bounded
  path for trusted cold-cache recovery, avoiding the long-lived app test
  process without adding CI matrix jobs.

- **Dlink target routing** — teaches Doc, Drive, Sheet, AITable, shared URL
  routing, and the `doc info` Schema to resolve shortcut targets through
  `linkSourceInfo` for content operations while preserving the top-level node
  for explicit shortcut-entry management.

- **Main integration reliability** — keeps main and release multi-profile E2E
  validation focused on the isolated profile chain while existing CI shards own
  the complete Go regressions, avoiding the long-lived runner shutdown window
  without adding CI jobs.

- **Minutes permission sharing** — adds `--member-staff-ids` to
  `minutes permission add` and `minutes +share`, preserving leading-zero staff
  IDs while keeping `--member-uids` for DingTalk UIDs.

- **Reviewer Router reconciliation** — keeps blocked, conflicting, draft, and
  otherwise unproven merge candidates retriable without letting one expected
  not-ready PR fail the repository-wide reconciliation batch.

### Security

- **Published MCP invocation** (#1261) - validates fresh bounded input schemas,
  restricts endpoint trust and redirects, and prevents automatic call replay.


## [1.0.62-beta.2] - 2026-09-02

### Added

- **Chat A2UI cards** (#1140) — adds `chat message send-a2ui-card` and
  `chat message update-a2ui-card` as dedicated A2UI commands while preserving
  the existing streaming card commands. A2UI content is delivered as a JSON
  string array, and update status accepts enum names plus compatible numbers
  1-9. The streaming update status flag is published as a string while
  preserving its numeric 1-5 inputs and integer RPC payload.

## [1.0.62-beta.1] - 2026-09-01

### Added

- **Runtime request context** (#1221) — packages an optional runtime payload, reports redacted readiness in `dws doctor`, and attaches compact context metadata to supported business requests.

- **hrbrain talent-pool save** — creates or updates a talent pool. Omit `--pool-code` to create a new pool (only `--pool-name` is required) or pass `--pool-code` to update an existing one; optional `--pool-desc`, `--rule-json` (auto in/out rule, validated as a JSON object), and `--pool-tags` (validated as a non-empty JSON array) are forwarded to the `create_or_update_pool` MCP tool. The write is gated by a confirmation prompt (`--yes` to skip).
- **hrbrain talent-pool move-members** — batch-moves staff into or out of a talent pool via the `entering_or_leaving_pool` MCP tool. Requires `--pool-code`, `--opt-type` (`ENTERING`/`LEAVING`), and `--staff-ids` (comma-separated work numbers), with an optional `--remark`. The write is gated by a confirmation prompt (`--yes` to skip).

### Changed

- **Single-executable runtime payload** (#1233) — bundles the platform payload into `dws`, removes the sidecar tree from new archives and installers, and retains sidecar discovery for existing installations.

### Fixed

- **Chat atomic message results** — normalizes message fields across atomic list and search commands, keeps nested search results aligned with top-level messages, and exposes stable send-status workflow references without removing raw response fields.

- **IM message AI provenance** — preserves the lower `messageAiSendFlag` value across message search, list, mget, @-mention, Pin, quoted-message, forwarded-message, and thread-reply projections.


## [1.0.61] - 2026-08-31

This release promotes the sealed `v1.0.61-beta.3` contents to stable.

### Changed

- **Agent-ready command contracts** — expands reviewed Help, Schema, safety,
  selection, result, pagination, and recovery guidance across the CLI, and
  moves static MCP authoring and published-tool invocation onto explicit
  `dws dev mcp` and `dws mcp published` command surfaces.

- **Collaboration and event workflows** — adds Chat Thread promotion,
  conversation-file upload, bounded message pagination, safer quoted replies,
  DingTalk task lifecycle events, and VoIP invite event consumption.

- **Document and data operations** — broadens Sheet batch and CSV controls,
  strengthens AI Table routing and composite verification, hardens Drive and
  Wiki shortcuts, and adds safer delegated authorization plus URL-only,
  optional-output, overwrite-protected, and concurrent-writer-safe downloads.

- **Organization and automation commands** — adds contact label and custom
  field management, tightens attendance date handling and DingTalk task
  workflows, and improves login, Windows Skill installation, and executable
  doctor recovery guidance.

- **Runtime and connector reliability** — preserves compatible document,
  Markdown, chat, and shortcut result shapes while improving DING, Whiteboard,
  Qoder Stream, and cross-product verification and failure evidence.

### Changes since `v1.0.61-beta.3`

### Added

- **Chat conversation-file upload** — adds `chat conversation-file upload` for local files, returning reusable `dentryId` and `spaceId` without sending a chat message while leaving the retired `chat file upload` path unchanged.

- **Chat message list page-all** — `dws chat message list` now accepts `--page-all` to iterate the time-boundary pagination automatically and return one merged `messages` array (with `pagesFetched`, `stopReason`, `nextPage`, and per-page failure diagnostics). `--page-limit` (default 50), `--max-items`, and `--page-delay` tune the sweep; without `--page-all` the command keeps its exact single-page behavior.

- **Delegation auth capability options** — when `--principal-user-id` is set, the per-tool `check_capability` verification now carries a tool-specific `options` payload so the server can authorize the exact operation. `create` sends the create action parameters (name/type/target folder or workspace), `upload`/`get_file_upload_info` send the upload action parameters (file name and size), `import`/`create_import_session` send the target node together with file name, suffix, and size, `copy`/`move` send the resolved source node, permission management sends the target members, and `drive publish` (`set_file_publish`) sends the share-scope target (`shareScopeSetParam`) so making a file internet-public (WEB) is pre-checked. Tools without a mapping continue to check without an `options` key.
- **Permission target members mapping** — permission-management delegation checks normalize both the new structured member format and the legacy `--users` list. Legacy user ids are converted into the structured target-member shape using the current logged-in enterprise corpId (resolved through the `$corpId` runtime default), keeping old and new invocations equivalent.
- **Import and upload dry-run delegation parity** — `doc import` and `doc upload` now run the delegation pre-check on their dry-run previews, matching the execution path. A dry-run combined with `--principal-user-id` is verified against the command's real first delegated call (`create_import_session` / `get_file_upload_info`) before any preview is rendered, and a denied principal blocks the preview.
- **Import target folder node resolution** — `extractNodeId` now recognizes `targetFolderId` (the key `doc import --folder` uses to carry its destination), so folder-targeted imports resolve a node id and are gated correctly. `copy`/`move` remain unaffected because an explicit `nodeId` still takes precedence over the folder keys.

- **Drive download URL-only mode** — `dws drive download` and `dws drive download-version` accept `--url-only`, a non-downloading mode that returns the temporary signed download URL and required request headers (`downloadUrl`/`headers`, plus optional `fileName`/`fileSize`/`version`) without writing any file locally; the caller (Agent runtime / external system) performs the download itself. Signed URLs keep literal `&` separators in JSON output so they are copy-paste usable. `--url-only` is mutually exclusive with `--output`/`--overwrite`/`--part-size`/`--parallel`/`--no-resume` (explicit combinations fail fast) and stays effective through the `download --version N` compatibility routing.

### Changed

- **Drive download optional output** — `dws drive download` and `dws drive download-version` no longer require `--output`: when omitted, files are saved to the current directory with the filename inferred from the response `fileName` (falling back to the download URL); explicit `--output` behavior (file path or directory) is unchanged.

- **Drive download overwrite guard** — `dws drive download` and `dws drive download-version` now reject downloads when the target file already exists, returning a structured `INPUT_FILE_ALREADY_EXISTS` error with recovery guidance; pass `--overwrite` to proceed. Re-running the same download used to silently overwrite the existing file. The guard is enforced both before the transfer starts and atomically at publish time (no-replace link), so a file that appears during a long download is never silently overwritten. Resume artifacts (`.dwspart`/`.dwspart.meta`) are not treated as conflicts.

### Fixed

- **AI Table composite verification** — accepts the service's real `newRecordIds`, view-filter, and workflow-detail response shapes, and retries only idempotent table-copy read-backs so delayed visibility no longer reports a false partial success.
- **Workflow deployment status reporting** — replaces `resolved.enable` with `resolved.enableRequested`; `verification.running` now reports the workflow's observed remote state instead of mirroring whether `--enable` was requested.

- **Chat message reply** (#1210) — allows personal and bot quoted replies in ordinary groups when conversation metadata omits `convThreadEnabled`, using the matching group search `channel=false` as positive evidence while continuing to block topic-circle targets.

- **DING failure handling and resource identity** — stop when robot credentials are missing or the selected robot is invalid, and preserve source message IDs separately from DING IDs. Recall accepts opaque server-returned DING IDs without guessing resource type from their prefixes; callers check identity provenance in the receipt.
- **Whiteboard verification and recovery** — validate connector payloads locally, normalize numeric coordinate comparisons, return compact successful update receipts, and preserve committed-write evidence on readback failure without recommending duplicate append operations.
- **DING and Whiteboard guidance** — align mono/multi references, clarify product ownership, and reduce redundant discovery and readback without dropping business information.

- **Drive download concurrent-writer safety** — `dws drive download` and `dws drive download-version` no longer risk publishing corrupted mixed content when two processes download to the same target concurrently. Streamed (non-ranged) downloads now write to a uniquely created temp file in the target directory instead of the shared `<target>.dwspart`, so concurrent writers can no longer truncate each other. Ranged/resume downloads keep the fixed `.dwspart` path (required for checkpoint reuse) and take a cross-process lock (`<target>.dwspart.lock`): a second concurrent writer fails fast with holder diagnostics (pid/host/start time) instead of interleaving writes; the atomic no-replace publish still guards the final target either way.

- **Drive shortcut verification** — adds bounded automatic pagination for list, search, and recent results, preserves existing data fields alongside unified pagination metadata, identifies pagination failures by their actual operation, rejects metadata-only statistics, and preserves committed resource evidence when create or upload read-back names differ.

- **Qoder Stream replies** (#1217) — sends Qoder CLI user messages as typed text-content blocks and surfaces `errors[]` from failed stream results, preventing successful DingTalk delivery from degrading into “本地 agent 无文本输出”.

- **Drive and Wiki shortcut verification** — supports workspace-targeted file uploads and strengthens space-type, pagination, node create/copy/move, and imported-name evidence.
- Workspace uploads now include the final file name and size in the initial credential request so upload-specific authorization can reject the operation before any file bytes are transferred.


## [1.0.61-beta.3] - 2026-08-30

### Added

- **Static MCP development and invocation** — moves MCP authoring under `dws dev mcp` and adds reviewed `dws mcp published` commands for inspecting and invoking published tools without dynamic command injection or credential-bearing endpoint caches.

- **DingTalk task personal lifecycle events** — adds personal Stream subscriptions for task creation, updates, and deletion, with catalog discovery for task events, validated creator/executor/participant role filters, typed flattened payloads, multi-event consumption, and documented DWS-to-task HSF backend routing.

- **VoIP call invite events** — adds `user_voip_call_receive_invite` support to `dws event consume`, including event discovery, Schema, validation, flattened NDJSON output, and mono/multi Skill guidance.

### Fixed

- **AITable routing and composite recovery** — tighten view-filter and reference guidance, recognize reviewed empty-query responses, and make Base copy target validation, rename recovery, and read-back verification deterministic.

## [1.0.61-beta.2] - 2026-08-28

### Added

- **Chat emotion favorite local image** (#85955640) — `dws chat emotion favorite` now accepts `--file-path` for a local image (jpg/jpeg/png/gif/webp/bmp, up to 10MB) as an alternative to `--media-id`; the CLI validates the file locally, uploads it through `dingtalk-file/upload_media` (bizType=chat_emoticon), and reuses the existing favorite flow with the returned mediaId (mediaIdV1 preferred, falling back to mediaIdV2). `--media-id` behavior is unchanged.

- **Contact label management** — adds `dws contact label update`, `dws contact label delete`, `dws contact label add-members`, `dws contact label remove-members`, and `dws contact label update-member-scope` to modify, delete, add/remove members, and adjust member scope for contact labels (roles). Also updates `dws contact label create` to require an explicit `--type role|group`: `--type role` requires `--parent-id` with a real label group ID; `--type group` creates a root-level label group and must omit `--parent-id` (the CLI passes `parentId=-1`).
- **Contact custom field management** — adds `dws contact ext-field create`, `dws contact ext-field update`, and `dws contact ext-field delete` to manage organization custom employee fields (`add_org_ext_attrs`, `update_org_ext_attrs`, `remove_org_ext_attrs`).

### Changed

- **DingTalk task workflows** — adds strict write receipts and read-back verification,
  executable parameter constraints, local dry-run plans for write shortcuts, bounded
  list scripts, and per-item verification ledgers for batch creation.

### Fixed

- **Beta shortcut response contracts** (#1167) — fixes HRbrain talent-pool business-page parsing and Mail template draft-mode input, while keeping OA form listing and other incompletely proven operations fail-closed.

- **Doc output compatibility** — preserves the empty pagination failure ledger and lets completed import recovery report an unverified result when the original target is unavailable.

- **Markdown routing and diff guidance** — makes `markdown create --folder`
  detect the Drive or Doc destination before upload, clarifies `markdown diff`
  parameter validation, and improves mono/multi Agent routing.

- **Chat message list result fields** — keeps `result.messages[]` aligned with the top-level `messages[]`, including the stable `messageId` used by edit and recall, while preserving legacy message fields.


## [1.0.61-beta.1] - 2026-08-28

### Added

- **Chat Thread** — adds `chat thread promote` to upgrade an existing group message into a Thread root message.

- **Sheet batch operations** — expands `sheet batch-update` from 16 to 39 CLI operations, adds strict validation for the new P0/P1 inputs, preserves server-generated create IDs in `results[].data`, and JSON-encodes translated operations locally so nested number/boolean values survive the MCP transport.
- **Sheet batch dimension coordinates** — makes `delete-dimension` and `move-dimension` accept the same public coordinates as their standalone commands (1-based row numbers or column letters) and translates them locally to the batch API's 0-based indexes.

- **Sheet CSV type control** — adds `sheet csv-put --auto-convert=false` (and the matching batch input) to preserve every non-formula CSV field as text while keeping fields beginning with `=` as formulas.

### Changed

- **Agent-friendly Help (Aone 85675069)** — adds a root Agent Quickstart and Safety model, renders complete Safety plus reviewed command-selection guidance on every Agent-visible leaf, and links service/leaf Help to the corresponding embedded DWS Skill and stable deep documentation.

### Fixed

- **Attendance schedule date ranges** (#1154) — sends `attendance schedule get`
  date ranges as upstream datetime strings, expands date-only inputs to full-day
  boundaries, and rejects reversed ranges before calling the service.

- **Login with unreadable token slots** (#1172) — after a fresh OAuth, device, PAT, or `--token` login, legacy global, identity, and organization token slots whose ciphertext no longer decrypts with the current data-encryption key are removed so the new credential can be persisted instead of stranding a completed login at the write preflight.

- **Windows Skill installation** (#1177) — stops the PowerShell installer from
  rejecting a correct multi/mono Skill publication when the staged copy and the
  destination carry different inherited Windows ACLs, and makes the transaction
  record its published paths before verifying them so a failed publication is
  rolled back instead of leaving the original Skill stranded in
  `~/.dws/skill-backups`.

- **Error-to-doctor recovery guidance** — links authentication and network
  failures to the executable `dws doctor` human entry or `dws doctor --json`
  Agent entry across legacy JSON, unified-envelope, shortcut, and multi-profile
  errors, while keeping permission, validation, confirmation, and upstream
  business errors on their more specific recovery paths.


## [1.0.60] - 2026-08-27

This release promotes the sealed `v1.0.60-beta.3` contents to stable.

### Changed

- **Document, Drive, and Sheet workflows** — adds Drive quota, task polling,
  export, permission, comment, public-link, history-version, revision, floating
  image, and delegated-access workflows; hardens document import, large
  Markdown writes, download handling, and readback verification.

- **Collaboration and automation commands** — adds dedicated Chat Thread
  commands, AITable datasource management, Agoal scorecard search, OA approval
  attachment upload, and reviewed Whiteboard workflows.

- **Agent-safe CLI contracts** (#1161) — publishes stricter pagination, result,
  confirmation, routing, and error contracts across report, Sheet, Minutes,
  AiSearch, Contact, Task, Wiki, and document commands, plus reviewed argument
  aliases for Agoal, DevApp, AITable, and Chat shortcuts.

- **DWS OpenAPI escape hatch** — supports file-backed parameters and request
  bodies, multipart uploads, pagination, and bounded binary downloads while
  tightening redirect, credential-pair, Keychain migration, and error-handling
  behavior.

- **Supported command surface** — removes the retired Education and College
  vendor extensions and improves command typo guidance, fork admission, and
  Reviewer Router merge recovery without weakening protected-main checks.

### Changes since `v1.0.60-beta.3`

### Added

- **Drive local-file comments** (#1151) — adds the complete global comment
  lifecycle for Drive files through the shared document comment service,
  including `create-v2`, `list-v2`, reply, update, delete, batch query,
  direct-reply listing, resolve, restore, and reaction replies. The existing
  `create` and `list` leaves retain their legacy behavior and output contract
  with deprecation guidance for an explicit migration.
- **Markdown comment reads** (#1151) — adds comment listing for native Markdown
  files with global, inline, resolution-status, and cursor filters, and exposes
  direct-reply listing across the shared Doc and Sheet comment lifecycle.

- **Chat Thread commands** — adds thirteen `chat thread` leaves for topic-circle creation, Thread publishing, reading, replying, forwarding, recall, emoji reactions, and text emotions. Parameters keep the original `chat group` / `chat message` names, including `--conversation-id`, `--topic-id`, and the existing forward flags.

- **Doc-business delegation auth** — the `drive`, `doc`, `sheet`, `wiki`, and `markdown` command groups now accept a persistent `--principal-user-id` flag. When set, the first invocation of each doc-business tool key per node within a session is gated by a `check_capability` verification on behalf of the principal; granting the capability is an out-of-band action the principal completes on the server side, and the CLI never calls `grant_capability`. A denied check surfaces the server's denial message and blocks the original call.
- **Dry-run consistency** — `checkCapability` now executes in dry-run mode as well, ensuring preview and execution behaviors are consistent. In dry-run, the check routes through the `ReadTool` channel (real network request) instead of `CallTool` (which would go through EchoRunner and always deny).
- **Dry-run pre-check in helpers** — dry-run mode now invokes the delegation auth validator before rendering the preview, ensuring commands that would be denied at execution time are also blocked at preview time.
- **Local rejection for node-less commands** — commands that lack a node identifier (e.g. search/list/create without nodeId) now return a clear client-side error (`DELEGATION_AUTH_NOT_SUPPORTED`, exit code 3) when `--principal-user-id` is set, instead of forwarding an incomplete request to the server.
- **Concurrency safety** — the per-session `checked` map in the delegation auth decorator is now protected by a `sync.Mutex`, preventing data races under concurrent tool invocations.
- **Markdown dry-run parity** — the `markdown` fetch/create/overwrite/patch/diff commands now run the same `check_capability` delegation gate on their dry-run previews as `doc`/`drive` do; a dry-run combined with `--principal-user-id` is verified against the command's real first delegated call before any preview is rendered, and a denied principal blocks the preview.

### Changed

- **Report latest lookup** — scans bounded, strictly advancing outbox pages, reconciles duplicate IDs, and reads back the uniquely newest report instead of failing on the first continuation page.
- **Sheet create-with-data result** — returns the already probed `sheetId` at the top level while preserving legacy `.result.nodeId` and outer `requestId`, avoids repeating the sheet-list probe, keeps the main-compatible single readback check, and reports post-create partial/unknown state without unsafe whole-workflow retries.
- **Sheet workflow routing** — distinguishes local analysis from Excel-to-online import, exposes template discovery and apply routes, and preserves the full data-validation tri-state contract.
- **Received-report helper and routing** — restores same-profile sender resolution before inbox filtering, keeps Mono and Multi helpers identical, uses bounded complete pagination, renders epoch timestamps in the Shanghai timezone, fails closed instead of returning incomplete data, and keeps midnight query windows valid.

### Fixed

- **Minutes pagination results** (#1112) — publishes list, search, and transcript continuation and exhaustion evidence through the unified `meta.pagination` envelope, while keeping business-scope completeness separate from endpoint exhaustion.

- **Chat Thread create result** — returns the created group's `openConversationId` and omits internal `openCid` / `cid` fields, matching `chat group create --thread`.

- **Doc agent routing and import defaults** — aligns document and drive Skill
  guidance with the executable CLI contract, preserves structured heading and
  attachment routes, publishes required shortcut arguments, and resolves the
  current profile's default document target before an import is submitted.

- **Reviewer Router preflight** — defers App-owned merge attempts while GitHub reports transiently unknown mergeability, avoiding false reconciliation failures without weakening approval or required-check enforcement.


## [1.0.60-beta.3] - 2026-08-26

### Added

- **Drive sync batch 2** (#1086) — Five synchronized enhancements aligned with closed-source MR 28427926 / 28769810 / 28967420 / 28972632:
  - **drive quota + quota apps** (#573): `drive quota` queries enterprise storage (org/app/space levels); `drive quota apps` lists application storage usage with pagination and sorting
  - **drive task get + copy/move auto-polling** (#543, #496): unified `drive task get --type <export|import|copy|move> --id <taskId>` queries async task status via `query_task` (drive MCP); `drive copy/move` now auto-poll `query_task` when server returns `taskId` and print normalized `TaskResult` JSON on completion
  - **drive export** (#593): universal export command supporting all doc types (adoc/axls/appt) with auto-format detection, progressive-backoff polling, and optional `--async` mode; `drive export get` queries export task status
  - **publish set password/expire-days** (#584): `drive publish set` accepts `--password` (4-char alphanumeric, empty to clear) and `--expire-days` (N=days, 0=permanent); client-side validation of --permission/--password/--expire-days runs before the confirmation gate
  - **doc-whiteboard.md** (#571): added `skills/mono/references/products/doc/doc-whiteboard.md` documenting whiteboard card insertion, deletion, and post-insert verification workflow

### Changed

- **Download host trust policy** — retires the static DingTalk/OSS download
  host allowlist, the dial-time public-IP refusal, and the IP-literal
  refusal from both the shared local download path (`drive +download`,
  `drive +version-download`, doc/minutes artifact downloads) and the chat
  message-resource path (`chat +messages-resource-download`,
  `--download-resources`). Download URLs only require HTTPS without userinfo
  and accept non-default HTTPS ports, because every dimension of a
  dedicated-deployment storage endpoint — custom domain, port, and network
  location — is decided by the customer deployment and cannot be enumerated
  or configured client-side. Verified on a dedicated deployment whose
  storage domain resolves to a customer-intranet address. Downloads align
  with the official GUI client, which applies no client-side SSRF
  interception: download URLs only ever come from authenticated service
  responses (no command accepts a user-supplied URL), TLS hostname
  verification pins the connection to the requested host, redirects are
  re-validated per hop, and service credential headers are stripped once a
  redirect leaves the original origin.
- **Upload host trust unchanged** — upload target URLs (`drive +upload`,
  minutes audio upload) keep the pre-existing public DingTalk/OSS trusted
  host requirement through a dedicated upload validator, so removing the
  download allowlist does not widen where local file bytes can be sent;
  the validator also keeps the pre-existing default-port-only HTTPS rule
  (DingTalk/OSS upload endpoints always serve on 443, so non-default ports
  accepted for dedicated-deployment downloads stay anomalous for uploads).
  Download credential headers are issued together with the download URL by
  the same authenticated service response and follow it as-is on the first
  request; redirects leaving the original host still strip them.

- **report entry submit requires recipients** — `dws report entry submit`（及废弃别名 `dws report create`）的 `--to-user-ids` 从可选提升为必填：无接收人的日志提交在服务端仍返回成功，但日志对任何接收人都不可见。openAPI `create_report` 的 `toUserIds` 参数保持可选不动，规则仅在 dws CLI 侧收紧——Cobra required 拦截未传场景，RunE 内对空值/纯分隔符（如 `--to-user-ids ","`）同样 fail-closed 拒绝。修复 [#85724185](https://project.aone.alibaba-inc.com/v2/project/2170318/bug/85724185)。

### Removed

- **Education and college vendor extensions removed** — removes `dws edu-contact`, `dws edu-group`, `dws edu-app`, `dws edu-familygroup`, and `dws college-contact` from the CLI, Schema, bundled Skills, and open-edition MCP endpoint registry. Future DWS packages no longer expose these five command surfaces.

### Fixed

- **Pull request CI scheduling** — stops metadata-only auto-merge enable and disable events from restarting the complete admission graph for an unchanged commit, while the base-owned Reviewer Router continues to enforce merge authority.

- **Command typo guidance** — returns a validation error with up to three nearest command suggestions and the parent `--help` entry instead of printing the full command list.

- **Document shortcut reliability** — adds bounded pagination for document and template listings, supports verified paragraph or heading insertion before a reference block, tolerates service-only Markdown layout normalization during write verification, and resolves and verifies the default “My Documents” import target.

- **Fork pull-request admission** — keeps the read-only Reviewer Router identity check fail-closed while allowing external contributors' CI to use the reviewed public App slug when GitHub withholds repository variables.

- **Markdown append chunking rewritten around safe split positions** — long markdown is now split so that every chunk is a complete, self-contained top-level block sequence, which is what `update_document mode=append` requires: the server inserts a brand new structure per call and cannot continue the previous one. Split points are chosen strictly by how much they change the rendered document — fully safe boundaries (blank lines, block starts that interrupt a paragraph) before boundaries that need repair (a table's rows now carry a re-emitted header and delimiter row; a fenced code block is closed and reopened with its original marker and info string) before boundaries that merely restructure (long paragraphs, list items) before a hard character cut. Within a tier the latest boundary in the window wins, since all chunks land in the same document. Every boundary that changes the rendered structure is reported in a new `degradations` field instead of being applied silently.
- **Fixed markdown chunking dropping a newline** — the previous splitter rebuilt block text from lines and lost one `\n` whenever the content's last line began a heading, table or code fence, so `"para\n# Title"` was written as `"para# Title"` and the heading stopped being a heading. Roughly one in five randomly generated documents was affected. The new splitter slices by offset and never rebuilds text, making content preservation structural.
- **Fixed oversized tables and code blocks being cut mid-cell and mid-fence** — the hard-split path never received the block type, so it cut at arbitrary character boundaries despite claiming to preserve table and code block integrity.
- **Fixed readback verification comparing against content the server never receives** — `doc +create` / `doc +update` verified the readback against the raw input, so any repaired boundary (and, previously, any paragraph split) failed verification on large documents. Verification now compares against the document the chunk plan says the server should hold.
- **Unified four markdown write paths onto one splitter** — `doc create` / `doc update`, `doc +create` / `doc +update` and `doc +checkpoint-update` now share `helpers.SplitMarkdownForAppend` and one limit constant (30000 runes), replacing two independent implementations plus one path that never chunked at all. `doc +checkpoint-update` accepts `@file` and stdin content, so oversized input was reachable there while the equivalent `doc +update` chunked. `doc +doc-append` takes `--text` from argv only and now rejects oversized input with a pointer to `doc +update` rather than sending one oversized call.
- **`doc update --index` now fails closed when the content requires chunking** — each chunk creates an unpredictable number of blocks, so the insertion point for later chunks is unknowable; the flag was previously accepted and silently ignored.

- **Reviewer Router recovery** — keeps exact App-owned PRs that are behind `main` retriable when GitHub reports the protected merge denial as `Resource not accessible by integration`, while preserving every other 403 as a hard failure.

- **Reviewer Router merge authority** — moves fail-closed writer-rule and auto-merge ownership validation into the trusted base-owned Router before App credentials are read, preparing metadata-only auto-merge changes to stop restarting the full CI suite without weakening protected-main admission or exact-SHA cache production.

- **Reviewer Router merge recovery** — retries exact App-owned merge intents through a SHA-bound synchronous merge after GitHub has enforced approval and nine GitHub Actions source-bound required checks.

### Security

- **DWS OpenAPI escape hatch** ([Aone #84603971](https://project.aone.alibaba-inc.com/v2/project/2125919/req/84603971)) — Preserves the existing `dws api <METHOD> <PATH>` command, five HTTP methods, flags and defaults, App Token cache, new/legacy host token injection, raw successful JSON, and paginated page arrays. Adds `--params/--data @file`, single-file streaming `--file [field=]path` multipart requests, camelCase pagination fields, and official `open.dingtalk.com/llms.txt` discovery guidance in the misc and mono Skills. Resolves Client ID and Client Secret only as a complete flag, environment, or app-config pair; one-shot Raw API flag/environment credentials remain ephemeral, while successful custom-app OAuth login persists its exact pair. Migrates plaintext and legacy `client-secret:<clientID>` values to `appsecret:<clientID>` after the canonical reference is durably stored, and fails closed on conflicting values. Dry-run no longer requires credentials and still performs no Keychain, deferred-file, or network access. Pagination now fails closed instead of returning partial pages, and rejects ambiguous continuation request keys. Non-2xx OpenAPI errors expose top-level `code` and request ID details without treating a successful payload's business `code` field as an error. Security tightening rejects HTTP, non-443 ports, cross-origin or HTTPS-downgrade redirects, sanitizes server-provided download filenames, bounds JSON/error bodies, and atomically streams binary downloads through a temporary file.


## [1.0.60-beta.2] - 2026-08-24

### Added

- **Drive permission get-setting** (#1056) — adds `dws drive permission get-setting --node <ID>` to inspect a document-space node's permission settings (permission mode, share scope, and permission policies) in one call.

- **Whiteboard shortcuts** (#1082) — adds strict query and confirmed update workflows with stable-target receipts and exact readback verification.
- **Sheet shortcut hardening** (#1082) — makes worksheet listing and cell-range reads fail closed on malformed, ambiguous, or truncated responses, publishes a closed reviewed output shape, and preserves non-executing `--dry-run` previews for range reads.

- **Permission and member list pagination** (#1085) — `drive/doc permission
  list` and `wiki member list` now accept `--next-token` to follow the
  server-side cursor (output carries `totalCount`/`hasMore`/`nextToken`) and
  map `--limit` to `pageSize` capped at 50 instead of the rejected `maxResults
  200` path; `permission add/update/remove` and `wiki member add/update/remove`
  additionally accept a `--members` JSON array covering USER/DEPT/CONVERSATION/TAG
  grantee types. The optional `--notify` defaults to `false` and is omitted from
  the server request unless passed explicitly, so member grants no longer notify
  recipients by default. These commands also declare cursor pagination
  (`next-token`) in the Agent schema contract, mirroring the internal CLI parity
  change. Because a single batch remove can revoke access for up to 30
  USER/DEPT/CONVERSATION/TAG members — where departments, chats, and role
  groups can indirectly affect many more users — `drive/doc permission
  remove` and `wiki member remove` now declare
  `confirmation=user_required` and gate the actual tool call behind user
  confirmation (`--yes`, an interactive yes, or `--dry-run` preview); their
  confirmation-gate failure now also passes through verbatim instead of being
  reclassified as a permission-denied or unclassified error.

- **Agoal scorecard search-entities** — `dws agoal scorecard search-entities` searches scorecard metrics and key items by keyword, returning matching entity info (scorecard ID, entity ID, entity type, title, owning team) with optional `--page`/`--page-size` pagination.

- **AITable datasource shortcuts** — adds 7 shortcuts for datasource sync management (`+datasource-create`, `+datasource-update`, `+datasource-sync`, `+datasource-sync-status`, `+datasource-get-config`, `+datasource-list-sources`, `+datasource-get-fields`) and updates the `dingtalk-aitable` skill with routing rules and a new `aitable-datasource.md` reference guide.

- **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.

- **Edu & College vendor extensions** — adds five hidden vendor extension commands for education scenarios: `dws edu-contact` (school/class/family/teacher contact management), `dws edu-group` (student/class group lifecycle), `dws edu-app` (homework, notices, report cards, diplomas, class circles), `dws edu-familygroup` (family group management, child binding, app permissions), and `dws college-contact` (university dept/employee/alumni/graduate management). All route to dedicated MCP servers via `callMCPToolOnServer`.

- **OA approval attachment upload** — `dws oa approval attachment upload --file <path>` uploads a local file as an approval attachment in one command: it initializes the upload credential (MCP `oa/init_attachment_upload_info`), HTTP PUTs the file to OSS, then commits it (MCP `oa/commit_attachment_upload_info`). `--file-name` defaults to the file's base name and `--md5` is auto-computed when omitted.

- **Sheet revision changesets** — adds read-only commands for querying the current workbook revision and reviewing Agent-readable changes between revisions, with guidance for distinguishing revisions from saved history versions and safely selecting rollback targets.

- **Sheet floating images** — supports creating or replacing a floating image directly from a local file with `create-float-image --file` and `update-float-image --file`, while retaining the existing `--src` workflow.

### Changed

- **AiSearch and Contact shortcuts** (#1083) — adds strict people search and reviewed unified results; people results must use the live-reviewed `person` source, and exact mobile lookups normalize accepted formatting before calling the dedicated mobile interface. Agent/public discovery keeps `contact +list-roles`, `contact +list-roster-fields`, `contact +get-roster`, and incomplete Live routes unavailable rather than publishing ambiguous results, while the historical Contact CLI commands retain legacy MCP execution and real error propagation. The legacy role-list projection preserves the service's reviewed null placeholder without exposing that ambiguous row through Agent Result contracts.

- **Permission error guidance and error rendering** (#1085) —
  permission-denied responses now exit with the `AUTH_PERMISSION_DENIED` code
  instead of a generic business-error rendering; document/wiki-specific errors
  (the drive-specific codes `forbidden.accessDenied` / `forbidden.no.auth`,
  or the role-threshold wording like
  “需要您具备 MANAGER 及以上角色”) carry apply-permission guidance
  (`dws drive permission apply-info` / `dws drive permission apply`), while
  permission failures carrying only generic code names (`FORBIDDEN`,
  `NO_PERMISSION` — also returned by attendance and event-subscription tools)
  or other products' wording keep their product-specific or
  product-neutral suggestion instead of a misleading document-permission hint;
  member-validation failures such as
  “用户不存在/不属于当前组织” are classified as tool errors with a
  `--members`-with-`corpId` suggestion instead of a misleading
  resource-not-found error; business error output now surfaces the backend
  message with `code`/`logId` appended for traceability; and the
  `update_permission` / `remove_permission` / `update_member` /
  `remove_member` tools — whose servers return a literal `null` on successful
  no-payload writes — now render `{}` so downstream JSON consumers do not fail
  parsing `null`; other tools keep raw `null` output unchanged.

### Fixed

- **Legacy global slot recovery** — recovers a rejected identity refresh from the legacy global keychain slot when the organization mirror is absent, with strict corp/user matching so blank-user legacy tokens only recover for single-account organizations.


## [1.0.60-beta.1] - 2026-08-21

### Changed

- **OA, DING, and Report shortcuts** — hardens response, identity, pagination, and confirmation contracts; publishes verified form search, receiver status, and report read workflows while withholding shortcuts that lack trustworthy downstream evidence.

- **Stable release sealing** — directly preparing a stable release now renders and archives release fragments merged after its beta baseline, avoiding a forced extra beta solely to consume pending notes.

### Fixed

- **Calendar empty windows** (#1074) — returns a legitimate empty result when the service emits its exact exhausted empty-event sentinel.
- **Task update verification** (#1074) — compares due-time readback as exact milliseconds so committed updates are no longer reported as failures.
- **Comment reaction validation** (#1074) — narrows accepted reaction input to reviewed DingTalk emoji names and rejects Unicode emoji and unsupported names such as `like` and `heart` before the RPC.

- **OAuth refresh falls back to the organization mirror** — when the server rejects the
  current identity's `refresh_token` with the reviewed `invalidParameter.authCode.notFound`
  business code, `dws` now retries once with the still-valid token mirrored in the same
  organization's slot (same corp, matching or backfilled user identity) before giving up,
  and writes the rotated credential back to both the identity and the organization slots so
  the fallback stays usable on later refreshes. Transient failures and direct-mode HTTP
  rejections without a reviewed business code do not trigger the fallback.


## [1.0.59] - 2026-08-20

This release promotes the sealed `v1.0.59-beta.5` contents to stable.

### Changed

- **Chat personal emotions** — adds commands to list, send, and favorite the current user's personal favorite emotions.

- **Minutes, DingTalk tasks, and Wiki parameter aliases** — adds reviewed parameter-name normalization, ambiguity guards, and end-to-end payload coverage.

- **Shortcut functional workflows** — fixes Drive preview accuracy, AITable write verification and deletion accounting, Wiki feeds, and false-success handling across task, Contact, Minutes, and Wiki operations.

## [1.0.59-beta.5] - 2026-08-20

### Added

- **Chat personal emotions** — adds `chat emotion list`, `chat emotion send`, and `chat emotion favorite` for current-user personal favorite emotion listing, sending, and favoriting.

- **Minutes, DingTalk tasks, and Wiki parameter aliases** — adds reviewed parameter-name normalization, ambiguity guards, and end-to-end payload coverage for the three products.

### Fixed

- **Shortcut functional workflows** (#1050) — fixes truthful Drive push/sync previews, strict AITable write verification and deletion accounting, lossless Wiki feeds, and false-success handling across task, Contact, Minutes, and Wiki operations.


## [1.0.59-beta.4] - 2026-08-20

### Added

- **招聘职位管理** (#976) — 新增招聘职位列表、详情查询和职位创建命令。

- **OA admin approval query** — `oa approval list-by-admin` queries approval instances of a template with admin scope, with simple flags and an advanced `--request` mode; `startTime`/`endTime` use `yyyy-MM-dd HH:mm:ss` strings per the 2026-08 MCP contract update (ISO-8601 flag inputs auto-convert), and pageSize/time format are validated client-side with localized errors.

### Changed

- **Attendance and Mail Shortcuts** (#1045) — publishes only capabilities with
  strict response, identity, pagination, and real-data verification while
  retaining historical CLI discovery and argument compatibility for commands
  that remain unavailable to agents. Mailbox auto-resolution now accepts both
  reviewed string and object response shapes, and Attendance date ranges cover
  the complete requested end date without dropping cross-midnight punches whose
  actual check time is inside the requested range. The schedule query remains
  CLI-compatible but is withheld from the Agent catalog because its downstream
  service returns a successful process exit with a null body for both populated
  and empty ranges.

- **Chat group roles** (#1058) — exposes the single-value `--role-id` flag for assigning one custom group role while preserving hidden `--role-ids` compatibility.

- **CLI compatibility governance** — adds a reviewed two-stage path for hiding retained legacy commands or optional `NoOpt=true` boolean flags from Help and Schema when their activated capability moves to a dedicated command, with legacy-leaf, complete parameter/constant mapping, durable runtime constant evidence, protected framework bridges, dry-run preservation, parameter-collision, and fail-closed required-parameter checks.

### Fixed

- **Canonical Agent Skills** (#996) — installs bundled DWS Skills once under `~/.agents/skills`, migrates duplicate Agent copies, and matches the upstream 76-Agent registry across Go, npm, Shell, and PowerShell. Non-universal Agents use directory links — junctions on Windows from the npm and PowerShell installers, symbolic links from `dws upgrade` / `dws skill setup` — with a safe copy fallback when link creation is unavailable (including Windows without Developer Mode); custom/XDG homes and OpenClaw legacy aliases are preserved. Upgrades now back up and restore Skills safely across external volumes by staging, lexically copying links (including dangling links), verifying contents, and deleting the source only after publication succeeds. Atomic no-replace publication and identity-checked quarantine rollback preserve concurrent user changes instead of overwriting or recursively deleting them; filesystems that reject the no-replace flag (NFS, FUSE, overlayfs) keep the no-clobber contract by holding the claimed destination for the entire transaction — renaming over the claim where the platform permits it, otherwise moving the source children into it — instead of unlinking the claim and retrying a plain rename, which opened a window where a concurrent directory could be overwritten. A degraded child-move that cannot consume the emptied source shell fails the publication loudly with the destination retained, so a failed move never silently discards staging data. When the fresh mkdir-claim identity captured by the child-move fallback — dev:ino on POSIX, the volume file ID on Windows — no longer matches the destination, the publication reports `ErrSkillPathPublicationUncertain` and keeps the destination: the object may belong to a concurrent writer, and the mono/multi upgrade copy fallbacks as well as `dws skill setup` honor the sentinel by surfacing the state instead of retrying over (and displacing) it. npm same-volume and cross-volume moves, PowerShell recoverably moves, and npm canonical-link / copied-set confirmation follow the same occupy-then-confirm contract. Same-volume publication and restore use a no-replace primitive (mkdir-claim plus child move, symlink-at-dest, or hard-link plus retract) so a dest that becomes occupied after any pre-check is refused instead of replaced. A rollback that has already quarantined dest re-checks identity in quarantine and restores an unmatched object onto dest with that same no-replace publish, so dest is not left empty with the concurrent object hidden unless the restore itself fails (then both locations are named). The npm installer now proves ownership at dest (inode, device, fingerprint) before any quarantine rename, matching Go: a concurrent replacement is left on the original path, and only a post-quarantine identity change is restored with no-replace. Go identity proofs report a stable file identity on every platform — dev:ino on Linux and macOS, the volume file ID on Windows — with the post-publish content fingerprint as the backstop against inode recycling; Shell copied-set rollback proves dest first with inode, child names, and a recursive content digest (sorted paths, mode bits, file hashes, link targets) for the same reason, so an in-place content edit after publish is preserved rather than retracted as this transaction's object. The npm installer's mono and multi set copy publication claims the destination with an atomic mkdir before moving the staged children into it, and canonical link publication creates the symlink or junction directly at the destination, so a concurrently created file, symlink, or directory is refused atomically instead of being replaced by Node's replacing rename or linked into by `ln -P` on POSIX or Windows. The standalone event/devapp copy publishers use the same mkdir claim instead of `mv`ing a staging directory onto dest. Shell copied-set and link rollback claim dest into quarantine before deleting, so a concurrent writer's file, symlink, or directory is renamed back instead of being deleted by a path-blind `rm` after an inode pre-check. Because that degraded publication has no atomic no-clobber primitive for a link, `dws skill setup` falls back to a direct copy when a link fails to *publish* as well as when it fails to stage, so non-universal Agents are still configured on those filesystems — except when the failure reports the uncertain sentinel, which retains the destination for manual inspection instead of retrying over it. Failing to retire an obsolete Agent copy is now a warning rather than an install failure. Every install surface prunes `~/.dws/skill-backups` to the newest 5 batches from earlier runs while never deleting a backup taken by the run in progress, so a migration that retires more than 5 batches stays reversible; stamp roots created before the ownership marker existed are preserved rather than pruned. Standalone installers verify every downloaded release asset against `checksums.txt`, and the npm engine declaration now reflects the actual Node 16.7+ API floor.

- **Chat user mentions** — preserves literal `<@openDingTalkId>` tokens in current-user Markdown messages and rejects mismatches between message-body mentions and mention flags before sending.
- **Chat direct media** — uses the IM upload target field for current-user direct file, audio, and video uploads, then uses the Chat receiver field for final message delivery.


## [1.0.59-beta.3] - 2026-08-19

### Added

- **Robot group reference replies** (#928) — `chat message send-by-bot` supports paired `--reply` and `--ref-sender` flags for Markdown replies that quote an existing group message.

- **AI Table server-side statistics** — adds `dws aitable record stats` for
  ungrouped record-set metrics through `query_records_stats`, plus `dws aitable
  record group-stats` for grouped, distinct, and advanced aggregation through
  `query_stats`; both commands validate their JSON aggregation contracts before
  dispatch.

- **Calendar event share-info** (#980) — adds `dws calendar event share-info` to fetch a calendar event's share info (title, organizer, location, join info) for sharing with others; supports `--calendar-id` and `--language`.

- **Calendar and To-do Shortcut workflows** — aligns 47 public task-oriented
  entries with lark-cli where the DingTalk backend supports equivalent
  semantics, rejects malformed or missing collections instead of returning
  false empty success, preserves truthful pagination, and requires stable
  identifiers plus read-back or explicit terminal receipts for writes. Adds
  deterministic contract coverage, a PII-safe live E2E runner, and a sanitized
  capability review with documented platform boundaries.

- **Doc and Sheet comment lifecycle commands** — adds `comment batch-query`,
  `comment resolve`, `comment restore`, and the lightweight
  `comment react-reply` to both `dws doc` and `dws sheet`. The two domains share
  the same `doc-comment` MCP capabilities; batch queries preserve input order
  for repeated `topicId:commentKey` references, while reaction replies require
  DingTalk reaction names such as `憨笑` or `鼓掌` rather than raw Unicode emoji.

- **Sheet SourceRange dropdowns** — supports range-backed dropdowns across direct, cell, and batch write paths, with structured readback for valid and invalid references. Batch `set-dropdown` now rejects unsupported top-level `colors` / `source-colors`; Inline colors belong in `options[].color`, while SourceRange color writes remain unsupported.
- **Sheet read completion metadata** — documents and preserves returned ranges, truncation reasons, and partial-read status for large range and CSV reads.

### Changed

- **AI Table parameter aliases** — accepts reviewed equivalent spellings for Base, table, workflow, search, pagination, and description parameters while keeping role-changing or semantically ambiguous inputs blocked.

- **Doc/drive description scope** — restates the `dingtalk-doc` description as document-entity-and-content operations with an explicit exclusion list, and narrows `dingtalk-drive` to file-level management of DingTalk documents, so first-round Agent selection separates content work from file management without changing CLI behavior.

### Fixed

- **Aitable pagination and Minutes unshare verification** (#1006) — keeps
  record queries on the service's 20-record page boundary so multi-page reads
  and mutation readbacks no longer report false retryable failures, preserves
  `totalCount` when supplied, validates `--dry-run` plans before transport,
  follows active deletion readback continuations before proving absence, and
  rejects Minutes unshare success until the listening note exists and the
  service acknowledges the exact task and member targets.

- **Document write verification** (#960) — avoids false partial-success results when normalized Markdown, paginated blocks, inline images, or version reverts are confirmed by server readback. Document reverts and media inserts now require explicit readback evidence and report partial success when the server cannot prove the requested result.

- **Chat sender identity guards** — preserves unverified mixed sender inputs after exact message `senderId` matches and aligns `--sender-query` Skill guidance with fail-closed Runtime behavior.

- **Windows event bus lifecycle** — start event consumers without unsupported inherited file descriptors, stop buses through local IPC with a termination fallback, and preserve subscription cleanup when startup fails.


## [1.0.59-beta.2] - 2026-08-17

### Added

- **Privacy-safe CLI telemetry** (#1009) — reports reviewed command outcomes and profile identity dimensions while excluding command arguments, output, paths, device fingerprints, and automatic system dimensions; `DO_NOT_TRACK=1` disables reporting.

- **Feedback survey entry in root help** (#1019) — `dws --help` now closes with a Feedback section linking the user-experience survey form.

- **Wiki Shortcut workflows** — publishes 20 reviewed space, member, node, and
  activity shortcuts with strict collection validation, cursor handling,
  write-terminal evidence, safe read-backs where the backend supports them,
  task-oriented routing, and documented backend
  boundaries.

### Changed

- **Chat IM ID flags** (#954) — standardizes chat command entry points on `--conversation-id` for conversation IDs and `--message-id` for message IDs, so help, Schema, and Agent recommendations use the same canonical flags.
- **Legacy chat flag compatibility** (#954) — keeps older chat IM ID flags such as `--group`, `--id`, `--chat`, `--open-conversation-id`, `--msg-id`, and `--open-message-id` working as compatibility aliases where applicable, while hiding migrated aliases from recommended help and Schema surfaces.
- **Chat group bots target flag** (#954) — keeps `dws chat group bots` on the visible `--group` flag; this command does not register `--group-name`, and `--group` accepts either an openConversationId or a uniquely resolved group name.

- **Faster Schema Catalog assembly** — projects typed values into payload JSON
  without re-running a validation scan over documents `json.Marshal` has just
  produced, cutting roughly a third of the projection work across the full tool
  set. Untrusted JSON input keeps its existing validation.

### Fixed

- **Chat card update evidence** — distinguishes an accepted update request from an independently verified visible update, preserving the real `bizId` and warning callers not to repeat an unverified write.
- **Chat command guidance** — splits message and group references by task and explains that `--from` is ambiguous between sender and time-range intent.


## [1.0.59-beta.1] - 2026-08-14

### Added

- **Drive list type/time filtering** (#942) — `dws drive list` gains `--type
  file|folder`, `--start`, and `--end` for client-side filtering by node type
  and modification time on both the pan and workspace routes. Filtering runs
  a bounded full scan of the target directory (2000-entry cap, reported via
  `truncated=true`), composes with `--latest`/`--pattern`/`--depth`, and is
  mutually exclusive with `--versions`/`--cursor`/`--order-by`/`--order`/
  `--limit`. Time values accept relative forms (`24h`/`7d`/`2w`), RFC 3339,
  zone-less ISO 8601 (Asia/Shanghai), or a plain date.

- **Drive folder synchronization** — adds `dws drive status`, `dws drive pull`,
  `dws drive push`, and `dws drive sync` for file-level comparison and transfer
  between a local folder and a Drive folder. Differences come from exact MD5 by
  default or from modification time with `--quick`; `status` is read-only, `pull`
  and `push` are one-directional with `--if-exists skip|smart|overwrite`, and
  `sync` is bidirectional with `--on-conflict remote-wins|local-wins|keep-both|ask`.
  Only regular files are transferred — online documents and shortcuts are skipped,
  neither side deletes extra files, downloads are staged through a temporary file
  and committed with an atomic rename, and remote names that would escape
  `--local-folder` are reported as failures instead of being written. Every command
  prints a structured summary on stdout and exits non-zero when any item fails.

- **International DingTalk region support** — adds `.io` login and MCP routing, pre-release endpoint overrides, and profile-aware gateway selection while preserving the existing `.com` flow.

### Changed

- **Chat identity routing** — validates explicit `openDingTalkId` inputs and improves name, `userId`, and `openDingTalkId` routing for message shortcuts.

### Fixed

- **Drive `--latest` refuses incomplete Top-N** (#899) — `dws drive list --latest` used to
  exit 0 with a "Top-N" computed over a partially scanned tree whenever a directory read
  failed mid-recursion (permission denied, API error), letting an incomplete set pose as the
  globally newest files. Truncation at the 2000-item scan cap and mid-recursion directory
  failures now both fail closed (`LATEST_SCAN_TRUNCATED` / `LATEST_SCAN_INCOMPLETE`), report
  the first failing folder with its depth and reason, and emit a recovery command that
  reproduces the original candidate set — query domain, `--folder`, `--pattern`, `--type`,
  `--start` and `--end` are all carried over. On POSIX shells each user-supplied value is
  quoted so a URL query string or a shell metacharacter cannot change how the copied command
  parses. On Windows no quoting form is safe for both `cmd.exe` and PowerShell, so values
  containing metacharacters are not inlined at all: the command carries a placeholder and the
  original value is shown on a separate line marked as data rather than an executable command.
  Unrecoverable errors under `--latest` return the root cause instead of a partial result.
  Remote-controlled folder names and server error text are stripped of ANSI escapes and
  control characters before they reach the plain-text stderr message. The internal `sortTime`
  sort key no longer leaks into `drive list --depth` output on any path.

- **Drive list pattern filtering** (#942) — `dws drive list --pattern` on the
  single-layer pan route now filters the returned page by name pattern; the
  flag was previously accepted but silently ignored.

- **Drive list `--type folder --latest` composition** (#942) — `--latest` now
  ranks the filtered entries (folders included when `--type folder` is set)
  instead of unconditionally dropping folders, so the documented combination
  returns the most recently modified folders rather than an empty list.

- **Chat message time defaults** (#973) — default omitted `chat message list-all` time bounds in `Asia/Shanghai` when emitting timezone-less `yyyy-MM-dd HH:mm:ss` values, matching parsing semantics and rejecting reversed windows.

- **Doc and Drive parameter aliases** — normalizes reviewed identifier, pagination, path, version, and role synonyms while blocking ambiguous values before dispatch.


## [1.0.58] - 2026-08-13

This release promotes the sealed `v1.0.58-beta.6` contents to stable.

### Changed

- **Expanded collaborative workflows** — adds full AI Table, Sheet, Minutes,
  approval-event, Drive-comment, document export, and CSV workflow support,
  including safer validation, explicit confirmation for writes, and
  machine-readable completion receipts.
- **More capable Chat operations** — adds robot image/file messages, toolbar
  management, streaming-card mentions, automatic pagination controls, and
  clearer post-send ID, Markdown-image, paging, and result-shape guidance.
- **Reliable Agent and CLI contracts** — expands Agent-visible Chat and
  Minutes commands, aligns bundled skills, improves schema/result envelopes,
  and hardens parameter, pagination, runtime-token, and write-result
  verification so ambiguous or incomplete operations fail closed.
- **Multi-skill install and upgrade** — makes the multi-skill layout the
  default for fresh installs and upgrades while preserving an explicit legacy
  mono option.
- **Safer release delivery** — strengthens release-equivalent compatibility,
  sealing, package verification, and evaluation-dispatch checks for more
  reliable cross-platform releases.

## [1.0.58-beta.6] - 2026-08-13

### Fixed

- **npm package verification for multi-skill installs** (#991) — aligns the
  release verifier with the installer’s concrete Agent skill-root selection,
  preventing valid multi-skill package layouts from failing release delivery.

### Changed

- **Release-seal CI classification** (#987) — recognizes the reviewed
  CHANGELOG-and-fragment archival shape while retaining release-contract and
  lifecycle validation, reducing unrelated CI work for release-seal PRs.

## [1.0.58-beta.5] - 2026-08-13

### Added

- **Agent version and extended context passthrough** (Aone 85384225) — adds
  validated `DWS_AGENT_VER` and sensitive JSON `DWS_AGENT_EXT` metadata to
  ordinary non-plugin MCP requests without forwarding it to A2A, OAuth,
  Discovery, or third-party plugins.

- **Drive file comments** (#961) — adds `dws drive comment list` and `dws drive comment create` for comments on ordinary preview files.

- **Chat automatic pagination controls** (#970) — adds bounded `--max-items` and cancellable `--page-delay` support to the core IM list shortcuts, with safe continuation metadata and truncation reporting.

### Changed

- **Chat message send help** - Clarifies Markdown image syntax for inline mixed text and images.

- **Doc/drive/wiki routing descriptions** — clarifies the document-space container-vs-content boundary across the doc, drive, and wiki skill descriptions for more predictable first-round Agent selection, without changing CLI behavior.


## [1.0.58-beta.4] - 2026-08-12

### Added

- **Multi-skill installation and upgrade** — fresh installs, `dws skill setup`,
  and `dws upgrade` now use the multi-skill layout by default. Existing mono
  installations migrate during upgrade; mono remains an explicit legacy option.
- **Native streaming-card mentions** — `dws chat message send-card` now accepts
  `--at-open-dingtalk-ids` and `--at-all` for group cards and forwards them to
  `create_and_send_card`, matching the existing shortcut behavior without
  changing single-chat card creation.
- **Expanded Minutes workflows** — 27 public Minutes shortcuts now cover
  upload, download, export, recording, analysis, sharing, and recovery flows;
  every write command keeps an explicit confirmation requirement.
- **Chat command discovery** — 30 existing typed Chat commands are now
  available in the runtime Schema and Agent catalog, with sensitive writes
  carrying their required confirmation metadata.

### Changed

- **Chat read results** — typed commands and shortcuts now expose a consistent
  top-level `messages` list with stable `messageId` and `text` fields while
  retaining existing response envelopes and fields.
- **Wiki feed results** — Wiki feed list output now formats time fields and
  trims excess fields. Its `--limit` default is 10 and maximum is 20.
- **Developer command results** — the `dev` and selected `devapp` commands now
  use the unified result envelope for consistent success, pending, partial,
  and failure reporting.
- **Evaluation dispatch hardening** — `/eval` now uses a verifiable polling
  relay instead of direct access from the hosted runner, binding the workflow,
  comment, PR head, parameters, and result provenance.

### Fixed

- **Streaming-card update acknowledgement** — accepts the pre-production
  `success: true` response from `update_streaming_card` as affirmative write
  evidence while preserving explicit negative, conflicting, and bizId-drift
  failures, so Agents do not repeat an update that the service already applied.
- **Text input bounds** — literal input, stdin, and `@file` inputs now all
  enforce the same byte limit; file reads validate the opened descriptor and
  cannot exceed the limit after a path replacement or file growth.
- **Evaluation PR comments** — restores `/eval` PR conversation comments with
  the least required pull-request write permission and actionable GitHub 403
  diagnostics.

## [1.0.58-beta.3] - 2026-08-11

### Added

- **Aitable workflow execution and history** — adds `dws aitable workflow run` for confirmed asynchronous execution of scheduled or record-triggered workflows, plus `dws aitable workflow history` for status-, time-, and page-filtered execution records. The commands map directly to `aitable/run_workflow` and `aitable/get_flow_record_list`, validate trigger-specific arguments locally, and document the `executionId` / `instanceId` correlation.
- **Streaming-card mentions** — `chat +messages-send-card` now accepts
  `--at-open-dingtalk-ids` and `--at-all` for group cards, passing mention
  targets to the initial card-creation request and prepending its returned
  `atTag` to the automatic streaming update.
- **Personal OA approval events** — personal event consumers now support task
  creation, completion, redirection, instance start, termination, and
  completion events, with typed output and matching usage documentation.

### Fixed

- **Machine-readable export and download receipts** — `dws doc export`,
  `dws drive download`, and `dws drive download --version` now keep progress
  logs on stderr under `--format json` and emit one JSON result on stdout after
  a successful local write. The result includes the saved path and byte size;
  document exports additionally report the node, requested format, job/task
  ID, and final status.
- **IM search and card-write safety** — conversation-scoped search now fails
  closed when the target cannot be verified, and streaming-card updates require
  business evidence rather than a transport-only success response.
- **Document shortcut reliability** — document write, readback verification,
  pagination, template/version discovery, export, media, and local-file
  workflows now preserve compatibility while rejecting ambiguous write results.
- **Event runtime-token handoff** — personal `event consume`, `status`,
  `stop`, and `+listen-im` honor the root `--token` without falling back to a
  stale OAuth profile. Detached buses negotiate an owner-only, memory-only IPC
  credential channel; tokens are never placed in child argv, environment,
  profiles, logs, or run-state files.

### Changed

- **Minutes `permission apply --policy` type** — `--policy` is now declared as
  an `int` flag and its required check uses `Flags().Changed`, matching the
  numeric-parameter convention. `--help` reports `int` instead of `string`;
  accepted values (2/3/4) and gateway behavior are unchanged.
- **Minutes skill references** — document `permission apply` in both Minutes
  skill references: list it in the command trees, describe its policy values and
  how it differs from `permission add`, and add its intent routing.
- **Chat paging guidance** — typed chat message commands now document
  `--page-all`, aggregate result shapes, and cursor behavior in CLI Help and
  Agent selection examples.
- **Calendar skill parity** — mono and multi Calendar references are aligned to
  prevent documentation drift without changing CLI behavior.
- **Release engineering** — CI now shards helper-package changes through the
  full race suite, widens a flaky stdio idempotency test budget, governs exact
  reviewed CLI/Schema type migrations, and lets authorized maintainers trigger
  internal MCP evaluation with a reviewed `/eval` PR comment.

## [1.0.58-beta.2] - 2026-08-10

### Added

- **`dws sheet create-with-data`（新命令）** — 建表并写入初始数据与样式：`--values`（二维数组写默认表）/ `--sheets`（typed table 多工作表，二者必须给一个）/ `--styles`（`cell_styles` / `row_sizes` / `col_sizes` / `cell_merges`，顶层键对齐飞书 snake_case、列表项内字段兼容 camelCase）。所有结构、字段类型与枚举在创建文档之前校验，非法配置不会留下白建的空文档：`--sheets` 按 `table_put` 的输入契约逐字段校验（`columns` 必填且列名非空不重复、`data` 为二维且行宽与 `columns` 一致、单元格仅限字符串/数字/布尔/null、`dtypes`/`formats` 的键须是列名、`mode`/`header`/`allowOverwrite`/`startCell` 类型与取值、单表 30000 单元格上限），并拒绝未知键、snake_case 变体、`{"sheets":"bad"}` 这类畸形包装与 `sheetId`（服务端会静默丢弃写错的键，导致"只写了表头却报成功"的静默丢数据）；`--values` 校验单元格为标量并受 30000 单元格 / 2000000 字符上限约束；`--styles` 的顶层键与列表项内字段同样拒绝未知键，避免样式只应用一半。写入后回读校验按 `startCell` / `header` / `mode` 推算的首个预期非空单元格，而非固定 A1。该命令是多步编排（建文档 → 探活 → 定位默认工作表 → 写数据 → 回读 → 可选样式），因此如实声明为独立叶子 `sheet.create_with_data` + `interface_mode: composite`（附评审 reason，按契约不带 `interface_ref`）；**`dws sheet create` 保持原样不变**——仍是一次 `create_workspace_sheet` 直连（`interface_mode: mcp`），不新增 flag，避免让 Schema 消费者把编排步骤的参数误当成该 RPC 的入参。
- **`dws sheet export-csv`（新命令）** — 同步导出单个工作表为 RFC4180 CSV，支持 `--sheet-id` 选表、`--range` 限定范围、`--value-render-option` 选取值模式；`--output` 落盘（为目录时按 `sheet-export.csv` 命名，落盘走 `AtomicWrite` 原子替换，写入失败时已有文件保持原样；父目录不存在按错误处理，不会自动创建），不传则把纯 CSV 打到 stdout（警告只走 stderr）。数据超出单次读取上限时默认报错、既不输出也不写文件，需 `--allow-truncated` 显式接受不完整结果。响应缺 `csv` 字段或类型不对一律报错，不会用 0 字节覆盖已有文件。该分支读的是 `get_range_as_csv`、与 xlsx 的异步导出任务毫无关系，因此独立成叶子 `sheet.export_csv` 并如实声明 `interface_mode: mcp` + `interface_ref: get_range_as_csv`；**`dws sheet export` 保持原样不变**——仍只导 xlsx（`interface_ref: submit_export_job`），flag 面仍是 `--node` / `--output`，csv 专属 flag 不会出现在它上面（此前挂在同一条命令上时，漏写 `--export-format csv` 会让 `--range` 被静默丢弃而导出整篇工作簿）。
- **`sheet update-dimension --size-type`** — `pixel` / `standard`（恢复默认行高列宽）/ `auto`（按内容自适应行高，仅 ROWS）。
- **`sheet replace --match-formula`** — 在公式文本中查找替换。
- **`sheet range set-style` 扩展样式维度** — 新增 `--font-style`（斜体）/ `--font-line`（下划线、删除线）/ `--font-family` / `--border-styles-json`（四边边框；每条边只接受 `style` / `color`，未知键与非字符串 `color` 直接报错，不再静默忽略而画出无颜色的边框，`set-style` / `batch-set-style` / `create-with-data --styles` 三条路径同源校验）。
- **`sheet range batch-set-style --ranges`** — 一组样式刷多个带工作表前缀的区域，组装为一次原子 `batch_update`。

### Changed

- **Chat message post-send ID handoff** (#897) — CLI Help and bundled Skills
  now document the `send` → `query-send-status` → `edit`/`recall` workflow,
  so callers can reuse returned task, message, and conversation IDs instead
  of searching message history by content.
- **Sheet mono/multi Skill alignment** — replaces the oversized mono Sheet
  reference with the progressive routing layout, aligns all 20 Sheet topic
  references across the mono and multi bundles, and adds a content-policy guard
  that prevents the paired topic trees from drifting again.
- **`sheet range set-style` 后端切换为 `set_cell_range`** — 样式统一走 cellStyles 路径（仅设样式、保留原值），这是斜体/下划线删除线/字体族/边框唯一可用的通道。`interface_ref` 由 `update_range` 变为 `set_cell_range`，12 个样式 flag 改为 reviewed mapping exclusion。CLI 用法向后兼容、无 flag 删除；schema-compatibility 经 reviewed 豁免判定为兼容（0 changed fields）。
- **`sheet range batch-set-style` 改为单次原子提交** — 由本地循环多次 `update_range` 改为一次 `batch_update`，任一项失败默认整批回滚；`--continue-on-error` 由本地控制改为透传服务端。新增批量上限：最多 100 个区域且累计不超过 200000 个单元格。
- **`sheet range batch-clear` / `batch-set-style` 的 `--ranges` 拒绝空白工作表前缀**（用户可见行为变更）— 此前只按原始串里 `!` 的位置判断，`" !A1:B2"` 修剪后工作表名成了空串，操作却照样带着 `sheetId: ""` 提交：服务端要么让整批 `batch_update` 失败，要么更糟——落到默认工作表而不是用户指定的那张表，且命令报成功。现在工作表名与范围都必须在修剪之后仍非空，否则在发起任何请求之前报错。`batch-set-style --batch` 的纯空白 `sheetId` / `range` 同样拒绝（此前只挡空字符串）；`--batch` 下发仍用原值不替用户修剪，因为 `sheetId` 可以是允许带首尾空格的工作表**名**。两条 `--ranges` 路径现在共用同一个拆分器。
- **`sheet insert-dimension` / `delete-dimension` / `update-dimension` 的 `--length` 严格校验**（用户可见行为变更）— 解析由 `fmt.Sscanf("%d")` 改为 `strconv.Atoi`。此前只消费前缀数字，`--length 2x` / `3foo` 会被静默当成 `2` / `3` 并对错误的行列数执行操作（删除方向不可回滚）；现在整个值必须是合法正整数，否则报错「`--length` 必须为正整数（>= 1）」且不发起任何请求。**升级影响**：原先依赖这种宽松解析、在传畸形 `--length` 的脚本会开始报错，请把参数修正为纯数字。合法数字值行为不变，上限仍为 5000。`add-dimension` 的 `--length` 是 `Int` 类型 flag，一直由 cobra 严格校验，不受影响。
- **CLI 接口兼容门禁支持 reviewed flag 类型豁免**（无用户可见变更）— `authoritative-interface-integrity` 与 `check-command-compatibility.sh` 此前一律拒绝历史命令的 flag 类型变更，即使新类型只是把同一套校验从 RunE 前移到解析期，也没有任何评审通道。现在两道门禁各带一张精确豁免表：命令路径 + flag 名 + 旧类型 → 新类型四元组全等才命中、方向敏感（`string`→`int` 与 `int`→`string` 是两个不同的键，只有被评审的方向可用），且仅当该 flag 的其他契约（shorthand / required / hidden / no-opt / scope）纹丝不动时才放行，因此豁免夹带不了别的破坏。首条也是目前唯一一条登记的是 `dws minutes permission apply --policy` 的 `string` → `int`（配合 #912）：旧实现在 RunE 里做 `strconv.ParseInt(v, 10, 64)` 再校验 `[2,4]`，新实现由 pflag 以 `strconv.ParseInt(s, 0, 64)` 解析后仍校验 `[2,4]`，**历史上能成功的调用集是新调用集的子集**（base 0 额外接受 `0x3` 这类写法，只放宽不收紧），非法值依然失败、只是报错文案与时机前移；flag 默认值由 `""` 变 `"0"` 是类型的必然结果，两道门禁都不比较默认值，且该 flag 必须显式给出、默认值不可达。两张表必须逐字一致并有守卫测试锚定漂移——重复是被迫的而非选择：`check-authoritative-interface-baselines.sh` 会把整个 `scripts/policy/interface-baseline` 目录复制进检出历史版本的 worktree 再编译，那份拷贝不能 import 本分支新增的包。
- **Schema 兼容门禁支持 reviewed 参数类型豁免**（无用户可见变更）— 接上一条。`schema-compatibility` 是同一个 `Interface Integrity` job 里排在两道 CLI 接口门禁之后的第三道检查，此前也一律拒绝已发布参数的 `type` 变更。由于前两道先失败、`set -e` 让它从未在 CI 上暴露，上一条豁免只解决了三分之二。现在 `checkParameterCompatibility` 也带一张精确豁免表：`<product>/<tool id>` + 参数名 + 旧类型 + 新类型四元组全等才命中、方向敏感，且仅当该参数**除 `type` 外的全部已发布字段逐字段相等**时才放行。这里刻意用相等性比较而非「没有产生其他兼容性错误」：放宽 `required` / `cli_required`、清空 `required_when`、扩宽 `enum`、清空 `interface_type`、经 reviewed mapping exclusion 清空 `property`——这些变化单独看都是兼容的、根本不产生错误，若以错误列表代替相等性检查，它们就能搭着一次已评审的类型迁移一起蒙混过关。结构体整体比较还意味着将来给 `parameterSchema` 新增字段时会自动纳入守卫，而不是悄悄放宽每一条既有条目。唯一条目是 `minutes/minutes.apply_minutes_permission` 的 `policy` 由 `"string"` 迁移到 `"integer"`（配合 #912）：该 `type` 由 Cobra flag 类型投影而来（provenance `cobra_flag_type`），描述的是 CLI 如何接受取值；消费方据此拼装的是命令行，而 `--policy 4` 在两种声明下是同一个 argv，加引号的 `--policy "4"` 到 pflag 仍是 4，RunE 也仍校验 `[2,4]`——而且该参数映射的 property `policyId` 一直以数字上报，新声明比旧声明更贴近真实请求。表里的类型值必须是 `schemaType` 实际产出的带引号形态（`"string"` 而非裸 `string`），守卫测试用 `schemaType` 复算并校验类型名属于 JSON Schema 的封闭取值集合——`reviewedInterfaceRefRedirect` 曾因键的书写形态错误两次静默失效，这里不重犯。

### Fixed

- **Event runtime-token handoff** — personal `event consume`, `status`, `stop`, and `+listen-im` now honor the existing root `--token` instead of falling back to a stale local OAuth profile. Detached personal-event buses negotiate the credential only after an additive capability handshake, receive and rotate it through owner-only local IPC, and keep it in memory; the token is never forwarded through child argv, environment variables, profiles, logs, or run-state files. Existing OAuth and multi-profile behavior is unchanged when `--token` is absent. A new client refuses to send a runtime token to an older bus and leaves its existing consumers and subscriptions untouched; the recovery message asks users to inspect `event status --as user`, preview `event stop --as user --all --dry-run`, and explicitly confirm `event stop --as user --all --yes` before retrying.

## [1.0.58-beta.1] - 2026-08-07

### Added

- **Robot image and file messages** (#867) — `dws chat message send-by-bot`
  now supports image URLs and local-file uploads through explicit message
  types, while retaining Markdown as the default and preserving its existing
  title and text requirements.
- **Conversation shortcut-bar management** (#877) — adds `dws chat toolbar`
  commands to list, add, hide, sort, and manage custom conversation shortcuts,
  with validation and confirmation for destructive removal.
- **Complete AI Table Shortcut surface** (#901) — makes all 92 supported
  AI Table Shortcuts discoverable through Runtime Schema and adds reliable
  Base, table, record, attachment, view, dashboard, and workflow operations
  with explicit confirmation and result-verification semantics for writes.

### Changed

- **Doc import upload fallback** — `dws doc import` no longer fails on file
  formats outside the conversion whitelist (html, pdf, zip, extensionless,
  and any future format): it now hands the file to the document-space upload
  chain (the same primitive as `dws drive upload --workspace`), stores the
  original file at the requested `--folder`/`--workspace` target, and prints
  an explicit stderr notice with the supported-format list and the
  convert-to-md alternative. The fallback shares the import file checks
  (20MB cap, empty-file guard), keeps `--format json` / `--dry-run` output as
  a single JSON document, and marks the machine-readable result with
  `fallback: "upload"` and `converted: false` so agents never mistake the
  stored file for a converted online document. The fallback fails closed
  unless the commit response parses as JSON and carries a file identity
  (exposed as `dentry_id`); empty or unverifiable responses surface as
  errors instead of fabricated success. Importable formats and
  `dws sheet import` validation are unchanged.
- **IM natural-target and history alignment** — Chat shortcuts can resolve natural user/group targets before execution, and message-history workflows expose bounded time ranges, ordering, explicit all-page controls, continuation ledgers, safe local export, and thread-reply pagination without treating empty or incomplete reads as successful results. Bundled mono/multi Skills and intent routing now describe the same executable surface.
- **Sheet CSV formula writes** — `dws sheet csv-put` and batch `csv-put` now expose the service contract that CSV fields beginning with `=` are written as formulas. Prefix the field with an apostrophe to write literal text beginning with `=`; CSV content continues to pass through unchanged.
- **Release-equivalent PR compatibility gate** (#889) — pull-request
  admission now runs command-surface compatibility checks against the current
  release baseline before code reaches `main`.
- **Reviewer routing governance** (#903) — updates the Reviewer Router pool
  used for new ready PRs while retaining the existing current-head review and
  required-check gates.

### Fixed

- **Fail-closed IM pagination and audit evidence** — `+chat-messages`, `+search-msg`, `+thread-replies`, `+at-me`, `+my-groups`, conversation lists, and favorites preserve partial-read failures, reject missing or stalled continuation state, deduplicate page boundaries, and publish completion evidence. The live-audit regression suite now rejects empty projections and incomplete reads instead of promoting them to passing results.
- **Sheet formula verification** (#873) — `dws sheet formula-verify` now calls
  the registered remote tool name `verify_formula`; the previous
  `formula_verify` name failed at gateway dispatch.
- **CLI and parameter recovery boundaries** (#864) — command and parameter
  recovery now fail closed when an Agent-provided path or flag cannot be
  reconciled with the executable CLI surface, reducing unsafe hallucinated
  retries.

## [1.0.57-beta.4] - 2026-08-06

### Added

- **Expanded open CLI workflows** (#887) — adds calendar event-instance
  queries, Drive latest-file selection, Markdown diff, Mail calendar/export/
  share-to-chat workflows, and Minutes hot-word, permission, and audio-memo
  operations, with matching Schema and cross-platform coverage.

### Changed

- **Multi-skill framework alignment** (#887) — folds long-tail skills into
  `dingtalk-misc`, renames the shared package to `dingtalk-shared`, removes
  stale Preview guidance, and reorganizes shared recipes and routing for more
  predictable Agent selection.
- **Bounded Agent Schema delivery** (#887) — keeps compact and wire projections
  focused on executable contract facts, retires stale MCP metadata candidates,
  and teaches Agents to prefer `dws schema --compact` for bounded context.

### Deprecated

- **Recovery and discovery-cache compatibility surfaces** (#887) — keeps
  visible Deprecated `dws recovery` and `dws cache` compatibility stubs while
  retiring their former recovery engine and dynamic discovery-cache behavior.
  Recovery plan/execute/finalize now return an explicit “不再支持” notice, and
  Skills no longer teach either retired workflow.

### Fixed

- **Mail share-to-chat confirmation** (#887) — requires explicit confirmation
  before the first remote write, while preserving the confirmed sign-retry
  flow and covering both direct-success and retry responses.

## [1.0.57] - 2026-08-06

This stable release promotes the fully delivered `v1.0.57-beta.4` baseline.
It includes the v1.0.57 beta-line command-contract, document, chat, OA, Wiki,
and compatibility improvements, plus the multi-skill framework alignment and
expanded calendar, Drive, Markdown, Mail, and Minutes workflows validated in
the final prerelease.

- **Promote v1.0.57-beta.4** — publishes the final validated prerelease
  baseline as stable `v1.0.57` without adding post-beta product changes.

## [1.0.57-beta.3] - 2026-08-06

### Added

- **Reviewed document shortcuts** (#880) — adds public document shortcuts for
  safe local downloads, content and history, review, media and style, and
  document access/sharing workflows, while retaining reviewed compatibility
  identities and confirmation safeguards for writes.
- **Mentions in chat replies** (#881) — `chat message reply` now supports
  `--at-open-dingtalk-ids` and `--at-all`, forwarding reply mention fields and
  adding any required mention placeholders without changing existing send
  behavior.

## [1.0.57-beta.2] - 2026-08-05

### Fixed

- **Stable Chat command compatibility** (#876) — restores the hidden migration
  entries for `chat send`, `chat history`, and their `im` aliases, preserving
  the v1.0.56 command surface while directing callers to the supported
  `chat message send/list` commands. Legacy flags now reach the same migration
  hints instead of failing during flag parsing.
- **Drive download cancellation-test stability** (#876) — replaces a
  timing-sensitive worker-cancellation coverage test with a deterministic seam,
  reducing flaky CI without changing download behavior.

## [1.0.57-beta.1] - 2026-08-05

This beta starts the v1.0.57 line on top of v1.0.56. It packages the unified
command-contract and runtime Schema architecture, complete Multi IM Chat
coverage, document whiteboard and OA approval workflows, Wiki activity feeds,
and compatibility and CI reliability fixes.

### Added

- **Contact personal-status updates** (#872) — adds `contact user update-ownness`
  (alias `set-ownness`) for updating a user's personal status text. The write
  operation maps reviewed `userId` and `ownnessText` parameters to the service
  contract and requires confirmation unless `--yes` is explicitly supplied.
- **Document whiteboard workflows** (#861) — adds `doc whiteboard insert`,
  `whiteboard query/update`, and `doc media upload`. These commands support
  confirmed document-embedded whiteboard creation and updates, structured
  OpenNodes reads, and preparation of node-bound Vector/SVG resources.
- **Complete Multi IM Chat coverage** (#860) — hardens deterministic group and
  stable-ID resolution, sending, querying, downloading, pagination, and JSON
  export. The remaining reviewed Chat Shortcuts enter Schema coverage, with
  destructive delete and clear operations aligned to confirmation gates.
- **OA approval form workflows** (#853) — adds OA form-schema lookup,
  process forecast, and confirmed approval-instance creation, supporting both
  simple flags and complete `--request` payloads.
- **Wiki activity-feed queries** (#862) — adds `wiki feed list` to retrieve
  workspace document activity, with cursor paging and optional file exclusion.

### Changed

- **Unified command and Schema contract framework** (#830) — Leaf commands and
  Shortcuts now use the shared typed `corecmd` base for flags, constraints,
  confirmation, Help, and runtime Schema projection. Schema delivery assembles
  from leaf Contract declarations at runtime; the retired hint overlays,
  pinned MCP metadata, and committed Catalog artifacts are no longer delivery
  authorities.
- **Faster macOS CI without reducing native coverage** (#857) — narrows the
  macOS race suite to Keychain, codesign, and Darwin-only tests while adding a
  reachability contract that prevents native-only tests from being silently
  excluded.

### Fixed

- **Chat media-download JSON compatibility** (#854) — restores parseable
  `success`, `downloadUrl`, and `output` fields for
  `chat message download-media --format json` after a successful download,
  without progress output corrupting JSON stdout.

### Added

- **Document-embedded whiteboard workflows** — adds `doc whiteboard insert` for confirmed creation and part-ID verification, `whiteboard query/update` for structured OpenNodes reads and confirmed writes, and `doc media upload` for preparing node-bound Vector/SVG resources. The public adapter uses an explicit helper-only whiteboard endpoint, validates update envelopes locally, decodes `resultJson`, and publishes the full command, Schema, Skill, and safety contract migrated from `dws-wukong@e2da8ab947c6`.
- **Robot image and file messages** — extends `chat message send-by-bot` with public image URL delivery through `--msg-type image --image-url` and local-file upload/send through `--msg-type file --file-path`, while preserving Markdown as the default message type.

### Changed

- **Chat reply mentions** — `dws chat message reply` can @ specified group members with `--at-open-dingtalk-ids` or @ everyone with `--at-all`, forwarding the existing `send_personal_message` mention fields and automatically adding missing current-user `<@id>` / `<@all>` placeholders.
- **Pinned MCP metadata retired** — deletes `internal/cli/schema_mcp_metadata.json` and removes its embed/loader/fallback role from Schema assembly. Catalog now assembles from Contract/ParamDecl/Interface + Cobra only; `make fetch-mcp-metadata` remains an optional diagnostic dump under `artifacts/` and refuses the retired pin path. Policy bans the pin from reappearing.
- **MCP service review retired** — deletes `schema_mcp_service_review.json` and removes its policy jq / outputguard / test disposition gate (`notify` → `out_of_surface`, snapshot hash pin). No replacement ledger.
- **Hints retired; ContractDecl is the leaf Schema source** (#830) — `schema_hints/`, Manual/Schema hint overlays, and `schema_agent_metadata/` delivery are removed. Selection, safety, parameters, and interface facts declare on ProductDecl / leaf `Contract` (`corecmd.ContractDecl` + `contract.ParamDecl` / `Safety`). Authoring renamed `SchemaDecl` → `ContractDecl`; nested fields reuse `contract.*` directly.
- **Contract package seam** (#830) — types / ProductDecl live under `internal/corecmd/contract` (DTO only). Annotate writers live in `internal/corecmd/runtimeannotate`; Cobra-keyed ContractFinal store + Register live in `internal/corecmd/contractfinal`; homology gates in `internal/cli/homology`. All packages import `corecmd/*` directly; the former `cli/runtimeannotate` / `cli/contractfinal` shim packages are removed, and the `cli` root keeps only package-local aliases (`runtime_schema_seam.go`). Catalog/`ResolveMeta` stay on the `cli` delivery root. `internal/corecmd` must not import any `internal/cli` package.
- **CommandMeta cache for ResolveMeta** — production `ResolveMeta` / leaf `--help` Safety project from the runtime-assembled `SchemaRegistry` into a `map[cli_path]CommandMeta` installed during `deliverySchemaCatalog` sync.Once. Steady-state lookups are O(1); full Catalog wire maps stay deferred. Registry `Source` stamps `runtime-assembled`.

### Fixed

- **Fail-closed IM pagination and audit evidence** — `+chat-messages`, `+search-msg`, `+thread-replies`, `+at-me`, `+my-groups`, conversation lists, and favorites preserve partial-read failures, reject missing or stalled continuation state, deduplicate page boundaries, and publish completion evidence. The live-audit regression suite now rejects empty projections and incomplete reads instead of promoting them to passing results.
- **Unified command safety and Shortcut runtime (H0)** — Shortcut leaves now execute through `corecmd.New`, sharing the same typed Safety confirmation gate as Leaf commands. EOF / closed stdin returns `confirmation_required`, and interactive `no` returns the existing non-zero cancellation validation error instead of reporting success for an operation that did not run. Pass `--yes` or `--dry-run` to skip the prompt.
- **Constraint "provided" for `at_least_one` / `exactly_one` (H0)** — a flag set to an empty string (`--flag ""`) no longer counts as provided; previously bare Cobra `Changed` satisfied the constraint. Pass a non-blank value for a member of the group.
- **Chat media download JSON compatibility** — `dws chat message download-media --format json` once again returns a clean `{success, downloadUrl, output}` result after the file is saved, preserving the temporary URL and resolved local path without progress text corrupting JSON stdout.

## [1.0.56] - 2026-08-04

This stable release promotes the fully delivered `v1.0.56-beta.4` baseline.
It includes PR #852's resilient multipart Drive download implementation,
together with the v1.0.56 beta-line command, Schema, Skill, and runtime
improvements already validated through the prerelease channel.

### Added

- **Resilient multipart Drive downloads** (#852) — `drive download` and
  `drive download-version` support parallel chunk transfer, Range probing,
  fingerprint-validated checkpoint resume, automatic 401/403 credential
  refresh, and graceful interruption with checkpoint preservation.

## [1.0.56-beta.4] - 2026-08-04

This beta adds PR #852 on top of v1.0.56-beta.3. It makes Drive downloads
resilient for large files through parallel transfer, validated resumable
checkpoints, and automatic credential refresh.

### Added

- **Multipart Drive downloads** (#852) — adds `--part-size`, `--parallel`, and
  `--no-resume` to `drive download` and `drive download-version`. Files above
  the part-size threshold use a Range probe and parallel chunks, resume from a
  fingerprint-validated checkpoint, refresh credentials on 401/403, and keep
  the checkpoint when Ctrl+C interrupts a transfer.

## [1.0.56-beta.3] - 2026-08-03

This beta adds PRs #846 and #851 on top of v1.0.56-beta.2. It adds a
service-provided Aitable workflow-editing reference command and makes local
event-bus IPC reliable on shared filesystems by placing Unix sockets in a
validated private runtime directory.

### Added

- **Aitable workflow editing reference** (#851) — adds `dws aitable workflow edit-example`, a parameter-free read command that returns the service-provided workflow editing documentation and `workflow-dsl/v1` examples through `aitable/edit_workflow_example`.

### Fixed

- **Event bus sockets on shared filesystems** (#846) — Unix event buses now place their local IPC socket in a private per-user runtime directory (`XDG_RUNTIME_DIR` when available, otherwise a `0700` per-UID directory under the system temporary directory) while retaining locks, metadata, logs, and subscription state in the configured Workdir. Listener and dial paths validate directory ownership and permissions before use. This prevents `dws event consume` from failing with `bind: errno 524` when `~/.dws` is hosted on NFS, CSI, FUSE, or another filesystem that does not support Unix Domain Sockets without exposing the socket directly in a shared `/tmp` root. When `XDG_RUNTIME_DIR` is unavailable, the per-UID directory name is deterministic: ownership validation prevents endpoint hijacking, but another local user can pre-create the directory to deny service; multi-user deployments should provide a private `XDG_RUNTIME_DIR`.

## [1.0.56-beta.2] - 2026-07-30

This beta adds PRs #831 and #835 on top of v1.0.56-beta.1. It separates
Agent Product observability and IM display identity from the stable
edition-owned PAT and routing identity, and reduces common-path Skill context
loading without changing the public command or Runtime Schema surface.

### Changed

- **Agent Product identity separation** (#831) — sends `DWS_AGENT_PRODUCT` through the new `x-dws-agent-product` observability Header and uses a valid non-empty value for the IM `clawType` display label whenever `--ai-tag` is enabled. Because `--ai-tag` defaults to `true`, callers that set `DWS_AGENT_PRODUCT` change the displayed label by default. With `--ai-tag=false`, native `chat message send` / `reply` calls preserve their existing wire shape by sending an empty IM `clawType`, while shortcut calls omit the argument. Unset or empty Product values omit the Header and preserve the active edition's IM display default.
- **Agent Host dimension convention** (#831) — new integrations should send the runtime form (`cloud` or `desktop`) through `DWS_AGENT_HOST` and report the product separately through `DWS_AGENT_PRODUCT`. Legacy combined labels such as `qwenwork_cloud` remain syntactically valid for compatibility.
- **Reduced common-path Skill context** (#835) — keeps the complete 97-command Chat Shortcut inventory in Runtime Catalog and leaf Schema while routing common intents through compact Skill tables and references. When an exact command path is already known, the mono Skill no longer requires eager loading of a complete product reference. The generated Skill policy now detects drift, forced full-reference loading, and context-budget regressions; the common Chat plus shared activation estimate drops from 7,301 to 4,771 `o200k_base` tokens without changing the 845-tool Schema surface.

### Fixed

- **Stable PAT/routing identity** (#831) — restores the CLI-emitted open-source HTTP `claw-type` and PAT `hostControl.clawType` to the edition-fixed `openClaw` value. `DWS_AGENT_PRODUCT` no longer changes those wire values, and the client continues to derive PAT, authentication, routing, and Discovery behaviour from the existing independent signals.
- **Portable generated Skill validation** (#835) — resolves the mono Skill name by scanning upward from the generated target, keeping `--check` independent of the repository checkout path and preventing false drift failures when an ancestor directory resembles a Skill name.

## [1.0.56-beta.1] - 2026-07-30

This beta starts the v1.0.56 line on top of v1.0.55 and packages PRs #817,
#806, and #834, together with release-validation fixes #838 and #839. It closes
the remaining Agent-visible IM shortcut gaps, introduces reviewed
command-scoped parameter normalization without guessing business identifiers
or values, and prevents deterministic personal-event subscription failures
from becoming unbounded retry storms.

### Added

- **Complete IM shortcut workflows** (#817) — publishes the previously excluded `+chat-messages`, `+messages-send`, `+messages-send-card`, `+search-msg`, and `+thread-replies` shortcuts in Runtime Schema. Unified send, streaming-card delivery, advanced search, thread replies, and opt-in resource downloads now share reviewed parameters, selection guidance, and runtime-aligned safety semantics.
- **Reviewed parameter concept normalization** (#806) — adds a closed parameter-concept dictionary and generated command-level alias table, covering reviewed IM synonyms while preserving the boundaries between group, conversation, user, open-user, cursor, and paging identifiers.

### Fixed

- **Message delivery and resource handling** (#817) — resolves direct recipients through exact contact search, preserves rich and nested message resources, avoids same-name download overwrites, and prevents read shortcuts from silently returning empty results on non-interactive input.
- **Parameter parsing safety** (#806) — rejects ambiguous, blocked, or conflicting aliases before dispatch, normalizes explicit boolean values such as `--dry-run false`, and keeps internal pre-parse handler details out of user-visible errors.
- **Personal-event subscription retry safety** (#834) — adds cross-process attempt claims, deterministic backoff and jitter, `Retry-After` handling, terminal holds, compare-and-swap completion, and fail-closed state handling across all public personal-event subscriptions, preventing deterministic failures from causing unbounded callback retries.
- **Scoped CI and release validation reliability** (#838, #839) — keeps scoped coverage aligned with intentionally skipped supporting profiles, gives focused race and Multi-profile E2E suites enough time for the current `internal/app` workload, and preserves hidden E2E diagnostics on failure.

## [1.0.55-beta.8] - 2026-07-30

This beta revalidates the `v1.0.55-beta.7` product baseline through a complete
guarded release delivery. It carries no new product-facing command behavior;
the new version is required because the published beta.7 artifacts succeeded
on GitHub, npm, and Homebrew, but its enabled optional Gitee mirror failed and
left that Release run ineligible for stable promotion.

### Changed

- **Complete promotion evidence** — republishes the validated v1.0.55 command, Runtime Schema, Skill, authentication, and projection changes with the optional Gitee upload fallback disabled, so the release can produce one successful auditable delivery proof before stable promotion.

## [1.0.55] - 2026-07-30

This release promotes the validated `v1.0.55-beta.8` baseline to stable. It
expands the public Workspace command surface and personal event consumption,
makes the full built-in shortcut catalog available to Agents, and hardens
multi-account routing, authentication compatibility, command safety, and
response projection across the CLI.

### Added

- **Broader Workspace command surface** (#621, #676) — adds roughly 30 reviewed Drive, Doc, Sheet, and Chat leaf commands synchronized from Wukong, including Drive version and permission operations, document styling, Sheet comment/version/formula verification, and in-place text-emotion updates. A reusable declarative `LeafSpec` framework now delivers command identity, safety, selection, and guarded Help metadata consistently.
- **Complete Agent-visible shortcut delivery** (#802, #815) — publishes all 210 built-in shortcuts as reviewed Runtime Schema leaves across 16 products, including 88 validated Chat shortcuts, with executable paths, parameters, constraints, selection guidance, dry-run capabilities, and runtime-aligned confirmation semantics.
- **Expanded enterprise and event capabilities** (#790) — adds the HR Brain talent-pool, employee-profile, and structured-search command families; `dws mcp url get` resolves MCP Market endpoints; personal event consumption supports eight additional IM event keys, multi-key consumers, and targeted shutdown.
- **Agent integration identity** (#804, #816) — adds validated `DWS_AGENT_HOST` and `DWS_AGENT_PRODUCT` labels for observability and product attribution while keeping them separate from authentication and authorization.

### Changed

- **Progressive multi-Skill guidance and account safety** (#621, #821) — reorganizes bundled product guidance for progressive discovery and restores the mandatory rule that Agents must not guess an account when a multi-account organization has no unique current default.
- **Supported Chat file delivery** — retires the legacy AppKey/AppSecret-backed `chat media upload` command from discovery and routes local files through `chat message send --msg-type file --file-path`, while callers with an existing media ID can continue sending images directly.
- **Guarded release delivery** (#791) — strengthens immutable GitHub, npm, Homebrew, optional mirror, recovery, and version-allocation checks while keeping beta and stable publication role-gated and auditable.

### Fixed

- **Shortcut and message projection correctness** (#706, #783, #795) — prevents successful read shortcuts from silently projecting non-empty backend responses to empty results, renders rich, forwarded, and encrypted message forms safely, and fixes group-bot, bot-search, mail-thread, media-ID alias, and Todo paging response handling.
- **Command contract edge cases** (#803) — makes approval revocation and document rollback honor dry-run before confirmation or preflight, fixes Drive and Doc rename semantics, restores Drive-specific metadata, and validates Todo reminder rules.
- **Authentication and external-contact compatibility** (#756, #757) — migrates legacy global and organization-scoped credentials without cross-account token borrowing, preserves contacts that expose only `openDingTalkId`, and aligns message-resource flags with message-list output fields.

## [1.0.55-beta.7] - 2026-07-29

This beta supersedes the unpublished `v1.0.55-beta.6` candidate and packages
PRs #621, #676, #757, #815, #816, and #821. It restores the mandatory
multi-account safety rule caught by the sealed-release E2E gate while retaining
the reviewed Wukong capability and multi-Skill synchronization, declarative
command and Schema delivery, hardened Chat shortcuts, external contact
resolution, and Agent product identity on top of the `v1.0.55-beta.5` baseline.

### Added

- **Wukong capability and multi-Skill synchronization** (#621) — ports roughly 30 reviewed leaf commands into the open-source CLI across Drive, Doc, Sheet, and Chat, including in-place text-emotion updates, Drive version and permission operations, document styling, and Sheet comment/version/formula verification. The bundled multi-Skill framework is reorganized into progressive product references and routing guidance while retaining current open-source command, response, safety, and Runtime Schema contracts.
- **Declarative leaf commands and unified metadata delivery** (#676) — adds the reusable `LeafSpec` command framework and migrates 27 DevApp commands without changing their paths or flags. Runtime consumers now resolve identity, safety, and selection through one embedded Catalog-backed API, and guarded Help output publishes the command's safety/confirmation annotation.
- **Agent product identity** (#816) — adds the optional `DWS_AGENT_PRODUCT` override for the existing HTTP `claw-type` header while preserving each edition's default when unset. Product and runtime labels are caller-declared signals, not authentication credentials; services must validate supported values and must not grant access solely from them. The override does not change the separate IM message-display `clawType` parameter controlled by the edition and `--ai-tag`.

### Changed

- **Reviewed Chat shortcut delivery** (#815) — publishes 88 currently available Chat shortcuts after real-business validation, keeps three confirmed lower-service failures unavailable, strengthens semantic availability and dry-run contracts, and adds safe message-resource download plus group-member listing. Conversation filtering, IM routing/reporting, and member mute resolution are aligned with the validated backend identities.
- **Agent identity label hardening** (#816) — limits `DWS_AGENT_PRODUCT` and `DWS_AGENT_HOST` to 64 ASCII bytes, trims only surrounding ASCII spaces and tabs, and rejects other control or Unicode whitespace. QwenWork integrations should report the two dimensions separately as `DWS_AGENT_PRODUCT=qwenwork` plus `DWS_AGENT_HOST=cloud` or `desktop`; previously used combined Host labels such as `qwenwork_cloud` remain syntactically valid for compatibility.

### Fixed

- **External-contact and message-resource chaining** (#757) — the shared name-to-ID resolver keeps external or cross-organization contacts that expose only `openDingTalkId`, applies reviewed display-name fallbacks, and preserves organization-only filtering for commands that require `userId`. `chat +messages-resource-url` now accepts `--msg-id` and `--open-message-id` as aliases for `--message-id`, matching message-list response fields.
- **Multi-account Skill safety contract** (#821) — restores the mandatory rule that an Agent must never choose the first, most recently logged-in, or most recently used account when an organization has multiple accounts without one unique `isOrgCurrent=true` default. A PR-level embedded-Skill regression test now catches removal before the full sealed-release E2E gate.

## [1.0.55-beta.6] - 2026-07-29

This beta packages PRs #621, #676, #757, #815, and #816, validating the Wukong
capability and multi-Skill synchronization, declarative command and Schema
delivery, hardened Chat shortcuts, external contact resolution, and Agent
product identity on top of the `v1.0.55-beta.5` baseline.

### Added

- **Wukong capability and multi-Skill synchronization** (#621) — ports roughly 30 reviewed leaf commands into the open-source CLI across Drive, Doc, Sheet, and Chat, including in-place text-emotion updates, Drive version and permission operations, document styling, and Sheet comment/version/formula verification. The bundled multi-Skill framework is reorganized into progressive product references and routing guidance while retaining current open-source command, response, safety, and Runtime Schema contracts.
- **Declarative leaf commands and unified metadata delivery** (#676) — adds the reusable `LeafSpec` command framework and migrates 27 DevApp commands without changing their paths or flags. Runtime consumers now resolve identity, safety, and selection through one embedded Catalog-backed API, and guarded Help output publishes the command's safety/confirmation annotation.
- **Agent product identity** (#816) — adds the optional `DWS_AGENT_PRODUCT` override for the existing HTTP `claw-type` header while preserving each edition's default when unset. Product and runtime labels are caller-declared signals, not authentication credentials; services must validate supported values and must not grant access solely from them. The override does not change the separate IM message-display `clawType` parameter controlled by the edition and `--ai-tag`.

### Changed

- **Reviewed Chat shortcut delivery** (#815) — publishes 88 currently available Chat shortcuts after real-business validation, keeps three confirmed lower-service failures unavailable, strengthens semantic availability and dry-run contracts, and adds safe message-resource download plus group-member listing. Conversation filtering, IM routing/reporting, and member mute resolution are aligned with the validated backend identities.
- **Agent identity label hardening** (#816) — limits `DWS_AGENT_PRODUCT` and `DWS_AGENT_HOST` to 64 ASCII bytes, trims only surrounding ASCII spaces and tabs, and rejects other control or Unicode whitespace. QwenWork integrations should report the two dimensions separately as `DWS_AGENT_PRODUCT=qwenwork` plus `DWS_AGENT_HOST=cloud` or `desktop`; previously used combined Host labels such as `qwenwork_cloud` remain syntactically valid for compatibility.

### Fixed

- **External-contact and message-resource chaining** (#757) — the shared name-to-ID resolver keeps external or cross-organization contacts that expose only `openDingTalkId`, applies reviewed display-name fallbacks, and preserves organization-only filtering for commands that require `userId`. `chat +messages-resource-url` now accepts `--msg-id` and `--open-message-id` as aliases for `--message-id`, matching message-list response fields.

## [1.0.55-beta.5] - 2026-07-28

This beta validates expanded personal event consumption, complete Agent-visible
Runtime Schema coverage for all 210 built-in shortcuts, Agent host
observability, and hardened document, Drive, approval, and Todo command
contracts on top of the `v1.0.55-beta.4` baseline.

### Added

- **Expanded personal event consumption** (#790) — adds eight IM personal event keys, supports subscribing to and consuming multiple event keys in one `dws event consume` invocation, and adds targeted local-consumer shutdown when a subscription is stopped so other consumers can continue on the shared event bus.
- **Shortcut Runtime Schema delivery** (#802) — publishes all 210 public built-in shortcuts as reviewed Agent-visible leaf tools across 16 product groups, with stable canonical identities, executable `+shortcut` CLI paths, parameter and cross-parameter constraints, selection guidance, interface metadata, and runtime-aligned safety/confirmation semantics. `dws shortcut list` remains the lightweight batch-discovery view, while leaf Schema now carries the complete Agent contract; declared string-slice defaults are also preserved consistently in Cobra and Schema.
- **Agent host observability** (#804) — accepts an optional, validated `DWS_AGENT_HOST` label and sends it as `x-dws-agent-host` for logs and BI only; invalid values fail before CLI network activity, and the label never participates in authentication or routing.

### Fixed

- **Command contract edge cases** (#803) — approval revocation and document-version rollback now honor `--dry-run` before confirmation or remote preflight; `drive rename` removes only a suffix matching the node's current extension to avoid duplicate extensions while `doc rename` preserves the caller's exact display name; `doc info` keeps its stable MCP contract while `drive info` restores Drive-only metadata such as a non-null `fileSize`; and Todo reminder writes now reject invalid rule JSON while Help, Schema, and Skills distinguish a due time from an independently unreadable reminder rule.

## [1.0.55-beta.4] - 2026-07-27

This beta validates the shortcut projection fixes for group bots, bot search,
and mail threads, together with hardened release delivery to Gitee and npm on
top of the `v1.0.55-beta.3` baseline.

### Fixed

- **Shortcut projection fixes** (#795) — `chat +chat-bots` no longer projects a non-empty `list_group_bots` response to an empty list, `+bot-find` recognizes the `search_bots` response shape (`result.bots` entries with `botOpenDingTalkId`), and mail thread listings keep `lastUpdated` when the backend returns `lastModifiedDateTime`.

### Changed

- **Hardened release delivery** — the Gitee mirror workflow can synchronize a specific release's assets on demand, release lookup tolerates Gitee's HTTP 200 null-body response for missing releases, npm dist-tag verification waits through slow registry CDN propagation with incremental backoff, and beta/stable release operations are role-enforced (#791).

## [1.0.55-beta.3] - 2026-07-24

This beta validates the HR Brain command surface, smoother guarded release
automation, and deterministic Markdown test coverage on top of the
`v1.0.55-beta.2` baseline.

### Added

- **HR Brain (`dws hrbrain`) command surface** — adds 11 commands across three groups: `talent-pool list/detail/employees` for talent pool browsing, `profile metadata/query/labels/career/performance` for employee profile data, and `search employees/employees-structured/fields` for basic and advanced (rule-based) people search. Ships with bundled mono/multi Skill guidance (`dingtalk-hrbrain`, `cli_version: ">=1.0.54"`); `search employees-structured` validates `--origin-json` as a JSON object and `--fields` as a JSON array before dispatch.

### Changed

- **Smoother guarded releases** — publishes verified stable and beta Homebrew Formula updates directly from the release workflow, retries transient tag-ref visibility failures, lets an exact same-run retry reuse its sealed tag, and allows machine-verified rebuild recovery without a separate approval wait.

### Fixed

- **Deterministic Markdown coverage** — replaces timing-dependent temporary-file deletion tests with synchronized file-stat failures so release admission no longer flakes on scheduler timing.

### Changed

- **Faster guarded releases** — trusts an independently revalidated, exact `CHANGELOG.md`-only successor of an already admitted `main` commit, runs cloud planning alongside governance, and executes sealed-release automation, compatibility, and multi-profile validation in parallel with artifact compilation. Normal cloud publication no longer requires an unshareable local packaging preflight.
- **Scoped document reads and group mentions** — `doc read --content-format jsonml` can return `outline`, `range`, `section`, or custom-tag fragments with depth and block-boundary controls; document comment create, reply, and update can mention groups through `--mentioned-open-conversation-id`.
- **Drive overwrite uploads** — `drive upload --node <fileId>` can replace an existing Drive or document-space file, is mutually exclusive with `--folder`, supports dry-run, and requires confirmation before writing.
- **Chat nickname clearing and cross-organization todos** — omitting `--nick` from `chat group update-nick` now clears the current user's group nickname, while `todo task list --query-all` queries todos across organizations.

### Fixed

- **Legacy authentication compatibility** (#756) — migrates pre-v1.0.53 global and organization-scoped login state into the identity-aware token store, including all legacy organizations, while keeping unresolved accounts isolated from exact `corpId:userId` credentials so external or no-directory identities can complete login without borrowing another user's token.

## [1.0.55-beta.1] - 2026-07-23

This beta validates MCP Market URL resolution, the supported Wukong local-file
send path after retiring the legacy credential-based media upload command from
discovery, and reliable message-read rendering for rich content, forwarded
records, encrypted messages, and media-download ID aliases.

### Added

- **MCP URL resolution** — adds `dws mcp url get <mcpId>` for resolving a DingTalk MCP Market ID to the current user and organization scoped Streamable HTTP URL, while keeping the helper-only `mcp-meta` endpoint out of the public product command surface.

### Changed

- **Chat local-file sending** — hides the open-source-only `chat media upload` compatibility command from Help, Schema, and bundled Skills, and removes its legacy AppKey/AppSecret OAPI path. Historical argv still receives an actionable migration error. Send local images and files through `chat message send --msg-type file --file-path`; callers that already hold a mediaId may continue to use `--msg-type image --media-id`.

### Fixed

- **Shortcut projection silent-empty returns** (#783) — a batch of read shortcuts returned an empty list with exit 0 and no error envelope even when the underlying MCP tool returned data, so agents misread "no data". The projection resolvers now probe the real container keys (`processCodeList`, `values`, `wikiSpaces`, `itemList`, `groupList`, `recentItems`, `emailAccounts`, `deptUserList`, `labelUserList`, `roles`, `report_list`, and the grouped `get_org_labels` `labels[]`), unwrap items nested under a VO wrapper (`shiftVO` / `entityVO` / `userInfo`), and `todo +created-todos` uses the shared pager (`pageSize=20`) because the backend silently returns an empty page for `pageSize>20`. Affects contact/oa/wiki/drive/minutes/calendar/attendance/chat/report/smart shortcuts, each with a guard test asserting the real response shape projects non-empty. `scripts/shortcut_real_result.py` also gains an upper-vs-lower layer comparison so an exit-0 empty projection over a non-empty backend is scored as `projection-data-loss` in the real read-audit path rather than `real-ok`.
- **Message-read shortcut projection** (#706) — the message-list shortcuts (`chat +chat-messages` / `+messages-list` / `+messages-list-direct` / `+at-me` / `+search-msg` / `+thread-replies`) now render card and out-of-office rich-content JSON as readable text (without ever rewriting ordinary text that merely embeds a JSON fragment), expand a forwarded chat record's nested `forwardMessages` instead of collapsing to a "[卡片]" summary, and mark undecryptable encrypted card messages as `[加密消息]`; the speaker is read from the bare `sender` key, nested `{name:…}` sender objects yield their display name, and the literal string `"null"` is treated as absent. Shared projection helpers now live in `internal/shortcut/chatmsg`. `chat message download-media` also gains `--msg-id` / `--open-message-id` aliases for its `--message-id` flag so agents copying the `openMessageId`/`msgId` output field no longer hit "unknown flag".

## [1.0.54] - 2026-07-21

This release promotes the validated `v1.0.54-beta.2` baseline to stable. It restores the default transport envelope for personal event output with opt-in flattening, plus Schema CLI path and plugin overlay compatibility fixes.

### Changed

- **Personal event output compatibility** (#743) — `event consume` once again preserves the transport envelope by default for `ndjson`/`json`/`pretty`, while retaining the existing `compact` processor. New Agent workflows opt into the event-specific top-level DTO with `--flatten`, which is mutually exclusive with `-f raw` and `--debug-raw-events`; `event schema --flatten` describes that DTO, while the default schema describes `type/event_type/data/headers` and points to `.data | fromjson`.

### Fixed

- **Schema CLI path compatibility** (#738) — user-facing Schema lookups once again accept space-, dot-, and slash-separated CLI paths without weakening strict canonical identity resolution.
- **Plugin CLI overlays** (#701) — installed plugins register their manifest-authored command trees again for HTTP and stdio servers, and a plugin may now replace a hidden compatibility fallback (for example `conference`) instead of being skipped as a distribution conflict.

## [1.0.54-beta.2] - 2026-07-21

This beta revalidates the same `v1.0.54-beta.1` source through the cloud release path with a sealed `OSS-Mirror: deferred` policy, because the manually tagged `v1.0.54-beta.1` push run failed on the unavailable OSS mirror channel after GitHub and npm delivery.

### Changed

- **Release delivery only** — no source changes since `v1.0.54-beta.1`; see that section for the user-visible changes under validation (#743, #738, #701).

## [1.0.54-beta.1] - 2026-07-21

This beta validates the restored default transport envelope for personal event output with opt-in flattening, plus Schema CLI path and plugin overlay compatibility fixes, on top of the validated `v1.0.53-beta.7` baseline.

### Changed

- **Personal event output compatibility** (#743) — `event consume` once again preserves the transport envelope by default for `ndjson`/`json`/`pretty`, while retaining the existing `compact` processor. New Agent workflows opt into the event-specific top-level DTO with `--flatten`, which is mutually exclusive with `-f raw` and `--debug-raw-events`; `event schema --flatten` describes that DTO, while the default schema describes `type/event_type/data/headers` and points to `.data | fromjson`.

### Fixed

- **Schema CLI path compatibility** (#738) — user-facing Schema lookups once again accept space-, dot-, and slash-separated CLI paths without weakening strict canonical identity resolution.
- **Plugin CLI overlays** (#701) — installed plugins register their manifest-authored command trees again for HTTP and stdio servers, and a plugin may now replace a hidden compatibility fallback (for example `conference`) instead of being skipped as a distribution conflict.

## [1.0.53] - 2026-07-21

This release promotes the validated `v1.0.53-beta.7` baseline to stable. It adds enterprise onboarding, declarative shortcuts, Sheet/Aitable writes, multi-account profiles, and broader personal IM events, while hardening authentication and the guarded release path.

### Added

- **Enterprise and office command coverage** — adds enterprise creation, employee invitation, and account provisioning commands; 366 declarative service shortcuts; Sheet import commands; and Aitable workflow create/update support with reviewed Schema contracts.
- **Multiple accounts in one DingTalk organization** — profiles can distinguish accounts by organization and user, select them explicitly, and log out one account or an entire organization without overwriting another account's credentials.
- **Expanded personal IM event subscriptions** (#651) — adds read-receipt, recall, and reaction events for one-to-one and group chats, plus specified-sender subscriptions by staff ID or OpenDingTalk ID.
- **Official multi-platform Homebrew channel** — ships separate stable and keg-only beta Formulae for macOS and Linux across amd64 and arm64, with isolated update PRs.

### Changed

- **Personal event output contract** (#651) — `event consume` now emits event-specific top-level structured fields; scripts that consumed the former transport envelope must use the flat fields or select `-f raw`, while `--debug-raw-events` retains the diagnostic envelope.
- **Guarded release lifecycle** — beta/stable publication now uses explicit promotion, immutable delivery proofs, protected recovery, and tag-bound optional OSS policy; an unprovisioned OSS mirror is sealed as `deferred` so GitHub, npm, and Homebrew are not blocked.
- **Relaxed stable promotion contract** (#729) — a stable release still requires a delivered, non-withdrawn beta baseline in its commit history, but no longer requires a byte-identical tree with that beta; reviewed commits merged to `main` after the beta can now ship in the stable release. Local releases now accept any sealed commit contained in `main` history and push only the release tag, so `main` is never frozen during the beta-to-stable window.

### Fixed

- **Authentication and credential reliability** — organization-policy denials stop before mutation or polling, long-running clients reload and refresh access tokens consistently, concurrent credential writes are atomic, and Windows portable-auth commands fail before reading or writing unsupported credential bundles.
- **Command validation and compatibility** — invalid Sheet/task targets fail locally, IM shortcuts preserve AI-tag and alias compatibility, and Aitable import uploads require and forward a positive file size.
- **Release publication reliability** — GitHub draft publication is bound to one verified release ID and exact assets, preflight uses isolated installer worktrees, guarded local tags remain compatible, cloud planning fingerprints the actual allocated release refs, and npm channel verification waits for bounded registry propagation without moving tags.
- **Package-manager version verification** (#735) — npm-vendored, Homebrew-installed, and packaged release binaries are now verified by searching their raw bytes for the injected version marker, so a correctly versioned stable binary is no longer rejected when the short version marker coalesces with adjacent printable linker metadata; incorrect or missing markers still fail closed.

## [1.0.53-beta.7] - 2026-07-21

This beta validates bounded npm channel verification after registry publication.

### Fixed

- **npm dist-tag eventual consistency** — Release delivery now tolerates a briefly stale `latest` or `beta` read after publishing by retrying only when npm reports a valid older version. Registry errors, invalid or incomparable tags, and channels that never converge still fail closed without moving any tag during verification.

## [1.0.53-beta.6] - 2026-07-21

This beta validates guarded local release compatibility and tag-bound OSS deferral so an unprovisioned mirror cannot block the primary release channels.

### Changed

- **Tag-bound optional OSS release mirror** — Official cloud Release runs no longer block GitHub, npm, and Homebrew delivery when an OSS bucket has not been provisioned. Cloud tags immutably record `OSS-Mirror: enabled|deferred`; publication, repair, and withdrawal consume that sealed policy instead of the current repository variable. Enabled releases remain fail-closed, while deferred releases skip the nonexistent channel and cannot be backfilled without a future audited repair proof.

### Fixed

- **Guarded local release compatibility** — The tag-push Release workflow now accepts the `Channel`-only annotated tags created by the guarded local release entry while continuing to reject any partial cloud-only seal metadata.
- **Cloud release tag allocation fingerprint** — Release planning now fingerprints the actual `v*` and `withdrawn/v*` refs fetched from GitHub, matching the seal job's API view instead of hashing an empty non-wildcard ref prefix and rejecting every publish before tag creation.

## [1.0.53-beta.5] - 2026-07-21

This beta validates long-running access-token recovery and the faster, recoverable guarded release path introduced after v1.0.53-beta.4.

### Changed

- **Fast guarded beta and stable releases** — successful local release checks now leave a six-hour proof bound to the exact version, commit, repository identity, remote `main`, and stable baseline, so the subsequent guarded `--publish` invocation revalidates authority without repeating tests and packaging. A default-branch governance smoke uses the same dedicated immutable-release credential as the tag workflow before any tag is allocated.
- **Protected existing-tag recovery** — `dws-release recover <version>` can resume a failed, unpublished annotated tag through the normal contract, build, Developer ID signing, immutable GitHub Release, Homebrew, npm, and OSS jobs. Recovery requires the exact tag object, peeled commit, failed tag-push run, typed version confirmation, and the protected `release-recovery` environment; successful runs are accepted as future beta/stable delivery evidence.

### Fixed

- **Long-running event authentication recovery** — personal and portal event streams resolve the current access token for every ticket request, refresh a server-rejected token with compare-and-refresh semantics, and reconnect with backoff when refresh is temporarily blocked by network failures, rate limits, or 5xx responses.
- **Consistent access-token caching and errors** — runtime, recovery, Skill, PAT polling, and personal/portal event clients now resolve user access tokens through one expiry- and publication-aware manager, so long-running processes reload rotated credentials while keychain, refresh, parse, permission, and cancellation failures remain observable instead of being collapsed into “not authenticated.”
- **Tag-push GitHub Release publication** — Draft publication now locks one GitHub Release database ID, verifies its exact tag, channel, notes, recovery marker, asset set, and uploaded bytes, then publishes and rechecks that same ID as immutable. Recovery runs use the trusted default-branch release helpers instead of the sealed tag's historical scripts, fixing the Draft-only `GET /releases/tags/{tag}` 404 without allowing the release identity to drift during recovery.
- **Release preflight reliability** — source-mode installer tests now use isolated temporary checkouts and HOME directories instead of overwriting and deleting the real repository `dws` binary, release preflight explicitly rebuilds before policy checks, and the full-suite runner gives the growing script package a non-flaky five-minute per-suite budget.

## [1.0.53-beta.4] - 2026-07-17

This beta validates the expanded personal IM event subscriptions and the flattened `event consume` structured output introduced after v1.0.53-beta.3.

### Added

- **Expanded personal IM event subscriptions** (#651) — adds one-to-one and group events for message read receipts, recalls, and reactions; publishes the specified-sender receive event; and lets one-to-one/sender subscriptions target either a staff `--user` or an `--open-dingtalk-id`. Event Schema now exposes these alternatives through machine-readable parameter constraints.

### Changed

- **Personal event structured output is now flat** (#651) — `event consume` projects NDJSON/JSON/pretty/compact output into event-specific top-level DTOs, so consumers read fields such as `content`, `sender`, and `conversation_id` directly instead of parsing `.data | fromjson`. This is a breaking change for scripts using the former transport envelope; the original server payload remains available through `-f raw`, while `--debug-raw-events` preserves the full diagnostic envelope.

## [1.0.53-beta.3] - 2026-07-17

This beta validates multi-account profile support and the post-v1.0.53-beta.2 compatibility fixes for Windows portable authentication, IM shortcuts, and Aitable import uploads.

### Added

- **Multiple accounts in one DingTalk organization** — profiles are keyed by `corpId:userId`, `--profile` accepts organization IDs/names plus user IDs/names, and organization-only selection uses its explicitly remembered current account or asks for an exact account when ambiguous.

### Changed

- **Profile-scoped logout and consistent token storage** — `dws auth logout --profile` can remove one account or every account in an organization, while identity token slots remain the source of truth and legacy organization/global mirrors stay compatible without overwriting newer account credentials.

### Fixed

- **Windows portable-auth contract** — `dws auth export` and `dws auth import` now fail early without reading credentials, bundles, or writing files instead of claiming portable-bundle support for DPAPI-protected HKCU Registry credentials.
- **IM shortcut message tags and compatibility aliases** (#646) — IM send shortcuts now add the same AI-sent marker as `chat message send` by default, support `--ai-tag=false` to opt out, and preserve compatible search, conversation-ID, and page-size aliases.
- **Aitable import upload file-size validation** (#654) — `dws aitable import upload` and `dws aitable +import-upload` now require a positive `--file-size` and always send it to the upload-preparation API, preventing invalid requests without the actual file size.

## [1.0.53-beta.2] - 2026-07-16

This beta validates the accumulated post-v1.0.52 command surface, release automation, and runtime hardening changes, including enterprise contact onboarding, declarative shortcuts, Sheet/Aitable writes, multi-platform Homebrew formulas, and credential and target-validation fixes.

### Added

- **Contact enterprise onboarding commands** — adds `contact org create`, `contact user invite`, and `contact account create` for creating a DingTalk enterprise, inviting an employee by mobile, and provisioning an enterprise login account, with reviewed Schema contracts and mono/multi Skill routing.
- **Declarative shortcut commands** (#592) — adds 366 `dws <service> +<command>` shortcuts across 16 services, including one-to-one MCP wrappers and multi-step smart workflows. Shortcuts publish stable Agent-visible contracts with named flags, validation and confirmation metadata, dry-run protection for writes, catalog/help routing, and optional local YAML extensions and usage recording.
- **Sheet imports and Aitable workflow writes** (#624) — adds `dws sheet import` / `sheet import create` for converting local xlsx/xls files into new online sheets, `sheet import get` for polling import tasks, and `dws aitable workflow create/update` for applying validated `workflow-dsl/v1` definitions, with matching reviewed Agent Schema and bundled Skill guidance.
- **Official multi-platform Homebrew channel** — stable `Formula/dingtalk-workspace-cli.rb` and keg-only `Formula/dingtalk-workspace-cli-beta.rb` live in this repository and select signed macOS Intel/Apple Silicon or Linux amd64/arm64 artifacts at install time. Stable and beta releases open isolated Formula update PRs after final artifact signing, so beta never replaces the stable Formula. Agent Skills stay under `pkgshare` without mutating the user's home directory, and both tracks are covered by the six-channel post-release verifier.

### Changed

- **Guarded prerelease and stable automation** — adds the guided `dws-release` entry for one-command CHANGELOG preparation, validation-only and annotated-tag publication flows; promotes only an explicitly validated beta; verifies command-tree compatibility and all six packaged binaries; and serializes immutable GitHub Release, npm channel, OSS, Homebrew, and optional Gitee delivery with fail-closed recovery checks.
- **Reviewed historical release recovery proofs** — release preflight can recognize an explicitly pinned successful recovery delivery for a historical stable tag while still rejecting arbitrary workflow dispatches, mismatched commits, and incomplete release, signing, or publication jobs.

### Fixed

- **PAT organization-policy denials stop immediately** — `PAT_ORG_POLICY_DENIED` now remains terminal even if a backend also returns `flowId`, authorization URLs, or client credentials; the CLI does not mutate process credentials, open a browser, poll, or retry until an organization administrator changes the policy.
- **Sheet and task invalid-target failures** — `sheet range read/get` now rejects a null cell-info response instead of printing `null` and exiting successfully, while task completion and attachment listing verify that a task exists before calling lenient backend endpoints. Attachment listing is also published through Runtime Schema for schema-first Agent discovery.
- **Concurrent credential writes and reentrant CLI execution** — secure-token writers now use isolated, exclusive temporary files before atomic replacement so concurrent processes cannot remove each other's in-flight data, and repeated in-process CLI runs close the previous file logger before replacing it instead of retaining the prior log-file handle.

## [1.0.52] - 2026-07-14

This release seals the `v1.0.52` line with personal event subscriptions, a deterministic 22-product Agent command catalog, local user-operation auditing, expanded Open product commands, safer macOS credentials and release signing, and more reliable Connect and IM delivery.

### Added

- **Personal event subscriptions** (#589) — adds `dws event list/schema/consume/status/stop` for user @ mentions, selected one-to-one chats, and selected group chats. `consume` can create or reuse a personal subscription, multiple local consumers share one bus while keeping outputs isolated by event type and subscription, and the mono/multi event Skills ship with the binary.
- **Open product command capabilities** (#608) — adds Sheet table, pivot-table, and gridline commands; Chat message favorites; Drive statistics and shortcuts; and Doc comment update/delete, with matching mono/multi Skill documentation and command-contract coverage.
- **Local user-operation audit log** (#555) — operations executed through `dws` now produce redacted daily JSONL records with actor, command and endpoint, result or error category, duration, CLI/platform metadata, and a SHA-256 previous-hash chain for tamper evidence. Writers coordinate through a cross-process file lock and rotate logs safely; `dws audit tail` inspects recent records, `dws audit export` emits date-filtered JSONL or CSV, and `dws audit verify` reports the first broken link in a file's hash chain.
- **Stable Agent command catalog** (#598) — `dws schema` now ships a deterministic 22-product / 564-tool catalog generated from the executable Cobra tree, with progressive product/group/leaf queries, complete parameter contracts, reviewed command identity and aliases, safety/confirmation metadata, field provenance, and final-delivery completeness/drift gates. The catalog is embedded at build time and does not require runtime MCP `tools/list` discovery.
- **Reviewed Schema for local commands** (#598, #609) — `event consume/list/schema/status/stop` and `audit export/tail/verify` enter the reviewed `CommandRegistry`, bind to the real Cobra tree at generation time, and ship through the same typed `ToolSpec` and embedded Catalog path as public MCP-backed commands. Leaf, group, product, and `--all` queries are projections of that single delivered model.
- **Safe macOS Keychain → file-DEK migration** (#597) — `dws auth migrate-keychain --to file-dek` preflights every legacy/profile auth entry before rewriting, ignores unrelated application secrets, supports side-effect-free `--dry-run`, requires explicit `--yes`, and lets sandboxed and normal processes share an existing login without exposing tokens.

### Changed

- **`event consume` AI-subprocess contract** (#609) — emits a fixed ready line and a final controlled-exit summary, supports parent-pipe stdin EOF as graceful shutdown, forwards `--profile` to the detached bus, surfaces bus startup errors, and cleans up subscriptions according to ownership so orchestrators can drive event streams without sleeps or leaked server-side subscriptions.
- **Wukong IM read-result parity** (#618) — `chat message list` preserves quoted merged-forward and image context; message-search entitlement failures retain the server-provided friendly hint and action URL; and `ding message list` exposes each DING's content alongside its ID and status.
- **Developer ID signing for official macOS archives** (#605) — official releases now require both Darwin archives to be signed with the configured Apple Developer ID certificate, timestamp, and hardened runtime. The release job validates credentials and signatures and fails closed instead of silently publishing ad-hoc-signed official binaries.

### Fixed

- **Smart-category mappings and runtime network diagnostics** (#591) — `chat category create-smart` now maps category names, group-name keywords, and member OpenDingTalk IDs to the live MCP contract, rejects blank or empty supplied values locally, and reports runtime `tools/call` connection failures as actionable API/network errors instead of internal discovery failures.
- **Connect daemon restart lifecycle** (#599) — pins the Stream SDK reconnect-race fix, snapshots the running executable before detaching, uses a real 30-second keepalive, and manages each worker as its own Unix process group so launcher cleanup or worker panics no longer cause restart loops or orphan local-agent processes.
- **Complex Connect messages and attachments** (#606, #612) — rich-text messages retain all embedded pictures in order, queued turns keep every pending attachment, and unknown or future callback shapes reach each Agent backend with their message type and raw JSON instead of being discarded. Attachment recovery is locator-based, nested `chatRecord` pictures/audio/video/files can be recovered from message APIs after Stream ACK, and OpenCode uses a full-duration storyboard for large videos to avoid base64 OOMs while preserving the original download for the turn.
- **macOS auth survives Keychain mode changes** (#597) — credential reads try existing compatible DEKs without creating key material, updates preserve the DEK that decrypted existing ciphertext, unreadable slots fail closed before token exchange, profile slots use the canonical auth backend, and `auth status` reports ciphertext/key mismatches instead of treating them as ordinary logout. Dedicated macOS race and Windows DPAPI coverage protect the cross-platform paths.

## [1.0.51] - 2026-07-10

This release promotes the sealed `v1.0.51-beta.1` contents to stable. It syncs the hardcoded Wukong command surface, prevents `dev connect` conversations from blocking on messages received mid-turn, and makes local credential failures diagnosable without mutating key material.

### Added

- **Agoal product commands** (#585) — adds `dws agoal` strategy, contract, scorecard, user-objective, report, and objective-template command groups, together with static routing and the bundled mono/multi Agoal skills.
- **Wukong chat command parity** (#585) — adds `chat group notice create|edit|get|list`, `group share-invite`, `text translate`, `category create-smart`, and `message list-emotion-replies`.
- **Wukong document import commands** (#585) — adds `doc import` for starting imports and `doc import get` for querying import tasks.
- **Wukong mail command parity** (#585) — adds mailbox profile, message batch-get, sent-message recall and recall-detail, auto-reply update, plus allow-list and block-list management.
- **Wukong sheet grouping commands** (#585) — adds `sheet group-dimension` and `sheet ungroup-dimension` for whole-row or whole-column ranges.
- **Keychain health diagnostics** (#578) — `dws doctor` now includes a keychain check, while `dws auth status` distinguishes ordinary logged-out state from `keychain_unavailable` and `dek_missing` failures and returns remediation hints in table and JSON output.

### Changed

- **`dws pat chmod` defaults to permanent grants** (#584) — running `dws pat chmod <scope>` without `--grant-type` now requests a `permanent` grant instead of `session`, aligning the direct CLI path with the recommend-authorization helper. Session grants remain available by passing `--grant-type session --session-id <id>`.
- **The `dev connect --channel gemini` path now uses the Gemini `generateContent` API** (#587) — configure it with `GEMINI_API_KEY` or `GOOGLE_API_KEY`, optionally override the compatible endpoint with `GEMINI_API_BASE_URL` or `GOOGLE_GEMINI_API_BASE_URL`, and select a model with `--agent-model` or `GEMINI_MODEL`; a local `gemini` executable is no longer required.

### Fixed

- **Non-blocking `dev connect` turn scheduling** (#587) — stream and `@`-poll callbacks no longer wait for the active turn to finish. Turns stay serialized per conversation, messages received mid-turn are coalesced into one pending follow-up, and different conversations can continue in parallel.
- **Connect agent recovery and headless execution** (#587) — stale addressable sessions retry once with a fresh session, unsupported Qoder control requests receive an immediate response instead of hanging, OpenCode and bypass-mode channels receive non-interactive permission settings, and backend/API failures are no longer posted as successful assistant replies.
- **Side-effect-free credential reads** (#578) — keychain reads inspect encrypted credential data before looking up the DEK and never generate a replacement key on a read path. Missing DEKs and unavailable macOS Keychains are surfaced as explicit diagnostic failures instead of silently mutating credential state.

## [1.0.50] - 2026-07-08

This release fixes a long-standing gap where the global `--jq` / `--fields` output filters were silently ignored on product commands, lands a JSON-mode output path for the sheet batch-style command, and aligns the bundled skill surface with the real command semantics uncovered by the round-2 real-machine QA sweep.

### Fixed

- **Global `--jq` / `--fields` are honored on product commands** (#575) — `Formatter.PrintJSON` / `PrintJSONUnescaped` now route through `output.WriteFiltered` when either flag is set, so product commands accept the same filters that `dws api` has always supported. The tool-caller adapter exposes `Fields()` / `JQ()` so helpers can read the flags without re-parsing.
- **`skill setup --dry-run` is a no-op preview** (#575) — it now prints what would be written without touching the skill directory, the registry, or the agent config. Help text and docs are updated to match.
- **Skill docs alignment to the real command surface** (#575) — per-product references and the cross-product intent guide clarify that `--fields` projects top-level / list keys only (use `--jq` for nested paths); `minutes_extract_todos.py`, `calendar_free_slot_finder.py`, `chat_export_messages.py` / `chat_history_with_user.py`, and `contact_dept_members.py` are rewritten against the current response shapes; `aisearch` / `aitable` / `attendance` / `calendar` / `chat` / `contact` / `dev` / `doc` / `doc-comment` / `doc-file-ops` / `doc-list` / `doc-search` / `drive` / `mail` / `minutes` / `oa` / `sheet` / `sheet-export` / `url-patterns` / `best_practices/lite-recipes.md` / `global-reference.md` / `intent-guide.md` are re-synced; the QA voice ("真机" phrasing) and environment-specific quirks stated as absolute rules are removed from the docs.

### Changed

- **`sheet range batch-set-style` emits per-row JSON in JSON mode** (#575) — when `--format json` is set, each update is reported as `{index, sheetId, range, ok, error}` instead of only the final aggregate, so callers can programmatically track partial failures under `--continue-on-error`.
- **Command-merge helpers exported** — `pkg/cmdutil.LeafMerge*` and the provenance helpers are now public so downstream command trees can reuse the same merge semantics.

## [1.0.49] - 2026-07-08

This release lands a full real-machine QA sweep across the CLI, helper scripts, and skill docs (#572), and hardens the release pipeline so npm publishing can no longer be blocked by Gitee mirror issues (#570).

### Fixed

- **Real-machine QA fixes across CLI commands** (#572) — `aitable chart/dashboard share update --enabled` now takes a string so `--enabled false` disables; `chat conversation-info --user` resolves openDingTalkId and registers `--id/--conversation-id/--chat` aliases; `chat list-all-conversations --limit` is capped at 100 and rejects larger values; custom-robot webhook failures surface `errcode` instead of masquerading as success; `contact` registers `--dept/--depts` as the primary flags so the documented spelling actually works; `sheet media-upload` and `sheet export` emit clean JSON under `--format json` (progress lines no longer leak); `wiki node create --type` enum is corrected (drops unsupported `asheet`, adds `axls/able/appt/adraw/amind`); `ding message list --type` defaults to `ALL` since the server rejects empty type.
- **Helper script fixes (mono and multi)** (#572) — aitable import/export flag names and the tableId regex (7-char default tables were rejected); mail search `--limit`, contact dept response keys (`deptList`/`deptUserList`) and `userInfo` nesting; `attendance_my_record` whoami compatibility; `calendar_schedule_meeting` event-id unwrapping; `drive_tree_list` recursion via `fileId`; report scripts migrated off the deprecated `report list`/`report detail`.
- **Skill docs sync (mono and multi)** (#572) — command indexes, flag names, enums, return-structure keys and cross-product intent routing are re-aligned to real-machine behavior across all products. Genuinely server-side limitations (permission gates, org-level restrictions, unregistered tool keys) are annotated instead of code-patched, and the cross-cutting hazards (`success` always true, `--jq`/`--fields` currently no-op) are documented.

### Changed

- **Release pipeline unblocks npm publish from Gitee mirror** (#570) — the Release workflow now publishes to npm before touching the Gitee mirror, so Gitee upload issues cannot block `npm/latest`. GitHub→Gitee attachment upload is disabled by default (unreliable from US runners) and only runs when `ENABLE_GITEE_UPLOAD_FALLBACK=true`; the legacy upload fallback path is guarded with timeout and retry so it fails fast when re-enabled.
- **Repair modes for release republish** (#570) — the Release workflow gains a repair input and a standalone npm-only repair workflow, used to republish an existing release to npm without re-running the full pipeline.

## [1.0.48] - 2026-07-07

This release promotes the sealed **remove-discovery delivery** from the beta line to the stable `v1.0.48` package. It removes dynamic service discovery from the open-edition runtime, keeps legacy CLI compatibility aliases, syncs the open command/help/skill surface with the dws-wukong baseline, and includes the `dev connect` default-yolo behavior on the stable upgrade track.

### Changed

- **Remove-discovery delivery is now formal/stable** — the beta validation line is ready to cut as `v1.0.48`; normal stable channels (`dws upgrade`, GitHub `releases/latest`, install scripts, and npm `latest`) should receive this release after the official tag is published.
- **Static endpoint runtime sealed for stable delivery** — the open edition no longer depends on dynamic service discovery at runtime, while preserving legacy command compatibility aliases and the synced help/skill surface from the beta.
- **`contact label` is restored as real wukong-compatible functionality** — `dws contact label list/get/list-members` now call `get_org_labels`, `search_label_by_name`, and `get_label_members_by_labelId`; `contact role` remains an alias, and the common top-level compatibility entries (`contact search/find/list/get/self/me/whoami/get-self`) now dispatch to real user/dept/label tools where unambiguous.
- **Skill docs match the sealed command surface** — contact docs again describe the real `contact label` three-step role lookup flow; video-conference start/invite/share flows remain explicitly unsupported and point users to the DingTalk client.

### Fixed

- **`calendar event list --dry-run` no longer executes the real list call** — the sorted event-list wrapper now respects dry-run and prints the `list_calendar_events` preview instead of calling the backend.
- **`chat file upload` is downlined** — the hidden compatibility entry now returns a clear downline message and never calls `chat/upload_conversation_file_by_url`; the supported file path remains `chat message send --msg-type file --file-path`.
- **Optional plugin version validation no longer pollutes every command** — incompatible local plugins such as conference are skipped at debug level during command-tree construction instead of printing a WARN on unrelated commands.
- **PR #45 review follow-ups are folded into the release** — doc version rollback pagination now unwraps nested result/content/data envelopes for `nextCursor`, mail helper scripts handle `{result:{emailAccounts:[...]}}`, and the generated attendance `.xlsx` fixture is removed from the skill scripts.

### Tests

- **Command-surface regression tests** — root-command tests now cover real `contact label`/`role` dry-runs, hidden top-level contact compatibility entries, `chat file upload` downline behavior, and `calendar event list --dry-run`.
- **Release hygiene tests** — skill markdown policy still blocks unsupported conference routes, plugin loader tests assert optional validation failures stay quiet at WARN level, and doc version cursor extraction has nested-envelope coverage.
## [1.0.47] - 2026-07-05

This release adds **connector supervision & health monitoring** (`dev connect list/status/restart/stop`) and fixes **bot-to-bot @-mention** delivery end-to-end.

### Added

- **`dev connect list`** — PM2-style colored table enumerating all local connectors with state (healthy / degraded / down / not_running), PID, channel, and uptime.
- **`dev connect status`** — panel view with heartbeat, last recv timestamp, session webhook age, and `--json` for external monitoring.
- **`dev connect restart`** — restarts a daemon via persisted `daemon-state.json` (unified-app-id credential fetch, no local secret storage).
- **`dev connect stop`** — graceful SIGTERM shutdown releasing the single-instance lock and Stream connection.
- **Health watchdog** — background goroutine writes `heartbeat.json`; `status`/`list` derive state from heartbeat freshness + process liveness + pid-reuse detection.
- **`--alwayson` flag** — opt-in auto-restart: supervisor relaunches the worker on crash (requires `--daemon`).
- **`--notify-staff-id`** — state-change notifications (start / stop / crash) sent as DingTalk messages to the specified staffId.
- **`--unified-app-id` credential flow for `dev connect`** — fetches clientId/clientSecret at startup via `dev app credentials get`, keeping secrets off the command line and out of `daemon-state.json`.
- **API-sent file download** (`feat(connect): download API-sent files via storage v2 API`) — file messages sent via `dws chat message send --msg-type file --dentry-id --space-id` are now downloaded by the connector through the storage v2 `getDownloadInfo` API (dentryId + spaceId → presigned URL → local temp file), so file-based Q&A works regardless of how the file was sent.
- **`--at-open-dingtalk-ids` for `chat message send-by-bot`** — @-mention bots or cross-org users by openDingTalkId in group messages.

### Fixed

- **Bot-to-bot @-mention send side** — `atOpendingtalkIds` (the server's lowercase spelling) is now used instead of the camelCase `atOpenDingTalkIds` which was silently ignored. The unnecessary `openDingTalkId → userId` reverse lookup (always failed for bots) is removed; the id is forwarded verbatim.
- **Bot-to-bot @-mention receive side** — `interactiveCard` messages (how DingTalk delivers a bot @-mentioning another bot) are now parsed: `extractInteractiveCardText` flattens `cardContent[].children[].value` leaves and strips the leading @-mention by leaf boundary. The `emotion/reply` reaction (which 500s on bot-sent cards) is skipped for `interactiveCard` turns.
- **Markdown/richText body extraction** — `extractCallbackText` gains a `cardContent` fallback so structured-text messages are no longer silently dropped.
- **Send-by-bot @ chip rendering** — `<@id>` placeholders in the markdown body are rewritten to `@id` for both userIds and openDingTalkIds so the mention chip renders in all cases.
- **Connector retry on transient network errors** — `sendBySession` retries on transient failures instead of dropping the reply.
- **Orphan worker cleanup & watchdog deadlock** — stale workers from a crashed supervisor are detected and cleaned; a channel-capacity fix prevents the watchdog from blocking.
- **Idle connector false-down** — heartbeat ticker now advances `updatedUnix` so a connector with no inbound traffic is not marked degraded.
- **FD limit check** — `checkFDLimit` split into platform files for Windows cross-compilation.
- **Default agent timeout removed** — no timeout by default (was incorrectly defaulting to a low value).
- **keepAlive shortened to 30 µs** — aligns with Stream SDK expectations; adds `ulimit` check for multi-agent stability.

## [1.0.46] - 2026-07-01

### Fixed

- **PAT agentCode grants no longer split from follow-up command checks** (`internal/auth/agent_code_detect.go`, `internal/app/runner.go`, `internal/pat/chmod_test.go`) — explicit `DINGTALK_DWS_AGENTCODE` declarations are now forwarded verbatim as the common cross-host contract, and unknown hosts no longer synthesize `custom` into `x-dingtalk-dws-agent-code` / `x-dws-agent-instance-id`. `pat chmod --agentCode` remains the highest-priority grant target and still wins over the env fallback.

## [1.0.45] - 2026-06-29

This release adds **multi-organization (profile) support** (#500): `dws` can stay logged in to several DingTalk organizations at once and switch between them, while staying fully backward/forward compatible with the previous single-org token. A profile is one logged-in organization (corp); the current profile decides which org a command runs against. The release also hardens the new credential store for concurrency and corruption recovery, documents the capability in both the mono and multi skill sets, and flips `--ai-tag` on by default so messages sent through `dws` carry the DingTalk 「通过AI发送」 badge (#524).

### Added

- **Multi-organization login & `profile` management** (`internal/auth/profiles.go`, `internal/app/profile_command.go`) — `dws auth login` against a new organization adds a profile (the first login becomes the primary); `dws profile list` shows logged-in orgs with primary / current markers, status and validity; `dws profile switch <name|corpId|->` persistently switches the default org (`-` toggles back to the previous one, no-arg opens a TUI selector on a terminal); `dws profile use` is an alias of `switch`. `dws auth status [--profile <name>]` reports a specific profile. Credentials are stored per organization in keychain slots keyed by corpId (`auth-token:<corpId>`), with a plaintext `profiles.json` registry holding only metadata and the primary/current/previous pointers (no tokens).
- **Global `--profile <name|corpId>` flag** — run a single command against a specific organization without changing the default (one-shot; does not move currentProfile). Cross-org reads are orchestrated by the agent (list profiles → query each with `--profile` → merge); there is intentionally no built-in `--all-orgs`.
- **Backward / forward compatibility with the legacy single token slot** — a pre-existing single-slot token is migrated into `auth-token:<corpId>` and marked primary on first multi-profile use; the current (or primary) profile's token is mirrored back into the legacy slot so older binaries and the embedded host keep working. `profiles.json` is additive and ignored by older versions.
- **`dingtalk-profile` and `dws-shared` skills + multi-org documentation** (`skills/`) — a standalone `dingtalk-profile` skill plus a new `dws-shared` skill that carries auth, global flags and the multi-org rule, so every multi-mode product skill's PREREQUISITE resolves and all read/search skills inherit cross-org behavior. The mono skill gains a "multi-org / profile" section, trigger conditions, a decision-tree entry and a corrected logout danger note. Multi-mode install now always ships `dws-shared` even when `--skill` / `--exclude` narrows the set.

### Changed

- **`--ai-tag` now defaults on — DingTalk 「通过AI发送」 badge for dws-sent messages** (`internal/helpers/chat.go`, #524) — `chat message send` / `reply` flip the `--ai-tag` default from false to true, attaching the AI `clawType` by default so messages sent through `dws` (and by AI agents) transparently carry the 「通过AI发送」 badge; pass `--ai-tag=false` to send as the user with no badge.
- **Concurrency-safe, self-healing `profiles.json`** (`internal/auth/profiles.go`, `internal/auth/token.go`) — every read-modify-write on `profiles.json` and the legacy mirror is serialized under the existing dual-layer (process + cross-process) lock, split into public (locking) entry points and lock-free `*Locked` variants so the non-reentrant lock is never re-acquired (the refresh path and the load-path migration use the lock-free savers). `profiles.json` and the token marker are written via per-write random temp names + atomic rename so concurrent writers can no longer corrupt a fixed `.tmp`. An unparseable `profiles.json` is quarantined (`*.corrupt-*`) and rebuilt empty so the CLI self-heals; `auth reset` / `logout` proceed even when it cannot be read and sweep the quarantined files.

### Fixed

- **No silent fallback to a different org's token** (`internal/auth/token.go`) — when the resolved current/primary profile's keychain slot fails to read and no `--profile` was given, the loader now only falls back to the legacy single slot if it belongs to the same organization; otherwise it surfaces the error instead of acting as a different org.
- **Legacy mirror no longer wiped on a transient keychain read error** (`internal/auth/profiles.go`) — `SyncLegacyTokenMirror` distinguishes "token genuinely absent" from "keychain momentarily unreadable" and keeps the existing mirror in the latter case, so a host app's login state is not dropped by a transient failure.

## [1.0.44] - 2026-06-28

This release hardens the dynamic-command surface and finishes the dws-wukong parity pass for structured input. Phantom override commands whose backing MCP tool isn't deployed are hidden from `--help`; `report entry submit` reads `--contents-file` / stdin natively; structured JSON flags accept `@file` / `@-`; and `sheet range update` / `range read` now accept the same plain shapes wukong does (scalar cells, flat `values`, null-clears-cell, a `--hyperlinks` flag). On the wukong01 sandbox this lifts the full open-edition cli_to_mcp pass rate from 77.6% to 95.5% (sheet 28.5% → 99.8%, report → 100%); the remaining failures are account / org / out-of-scope, not CLI defects.

### Added

- **`dingtalk-dev` skill: image-upload → `mediaId` recipe + per-resource command discovery** (`skills/multi/dingtalk-dev/references/`) — documents how to obtain a `mediaId` for app / robot icons via the DingTalk OpenAPI (`credentials get` → `gettoken` → `/media/upload?type=image` → `--icon-media-id` → read back), since the dev command set has no upload command; and adds a "discovering commands" block to all 10 product refs pointing at each group's `--help` and `dws schema dev.app.<group>.<method>` (`dws schema dev.connect` for connect), so agents inspect commands instead of relying on memory.
- **`report entry submit --contents-file <path>` / `--contents -` (stdin) read natively** (#514, `internal/compat/report_hooks.go`) — the envelope publishes `entry submit` (MCP `create_report`) with a `--contents` (json_parse, required) flag plus a sibling `--contents-file` that had no transform / mapsTo, so a `--contents-file`-only submit silently sent `contents: [null]` and the report failed (only inline `--contents` worked, which is why `report create` succeeded while `report entry submit --contents-file` did not). A build-time compat hook now resolves the file / stdin natively (10MB cap, UTF-8 check, wukong priority `--contents-file` > `--contents -` > inline) and relaxes the individual `required` on `--contents` into a `contents` / `contents-file` one-of group. No discovery-config change needed.
- **`@file` / `@-` input for structured JSON flags** (`internal/compat/transform.go`) — `json_parse` / `json_parse_strict` now expand a leading `@` before parsing (`@-` reads stdin, `@<path>` reads a file), so long / complex payloads (many records, big 2D cell ranges, filter criteria) skip shell-quoting hell. A JSON / YAML value never starts with `@`, so the sentinel is unambiguous; the error hint that already advertised `@path/to/file.json` is now truthful. `sheet`'s shared `sheetParseJSONFlag` routes through `cli.ResolveInputSource` so the same support reaches `--values` / `--criteria` / `--sort-keys`.
- **`sheet range update --hyperlinks`** (`internal/helpers/sheet.go`) — a wukong-shaped 2D hyperlink grid (`[[{"type":"path","link":"...","text":"..."}]]`) overlaid onto the cells grid as each cell's `hyperlink` field; `--values` or `--hyperlinks` is now required (at least one).

### Changed

- **Phantom override commands hidden from `--help`** (#515, `internal/compat/dynamic_commands.go`) — override leaves whose backing MCP tool isn't actually deployed used to render in `dws <svc> --help` and then fail at invocation with *tool not found*. A tool-existence guard now hides them, and command groups left empty by the hidden leaves are collapsed, so `--help` reflects only invokable commands. Skill references are re-aligned to the real CLI surface (phantom commands dropped; role/duty "who is responsible" queries routed to `aisearch`, not `contact`).
- **`sheet range update` accepts scalar cells; `sheet range read` projects a flat `values`; `--values '[[null]]'` clears a cell** (`internal/helpers/sheet.go`, `internal/helpers/sheet_cell_validation.go`) — dws-wukong parity. `range update` (set_cell_range) auto-wraps a scalar cell (string / number / bool) into `{type:text,text:"..."}` instead of rejecting it, so the plain `[["姓名","部门"]]` shape that `sheet append` and wukong's update_range accept now works; a null cell clears content (matching wukong); `{}` still means keep-original. `range read` (get_cell_infos) now also exposes a flat `values` 2D array next to the rich `cells` payload, matching wukong's get_range shape without dropping cell styles.
- **report skill aligned to `entry submit` / `inbox list` / `outbox list`** (`skills/multi/dingtalk-report/`, `skills/mono/references/intent-guide.md`) — the multi skill tree was two versions behind and still taught the deprecated flat aliases (`report create` / `sent` / `list` / `detail` / `stats`) and falsely claimed `report inbox` was unimplemented. Re-aligned to the canonical resource.verb commands consistently (old aliases still execute with a stderr deprecation notice).

## [1.0.43] - 2026-06-26

This release aligns the open edition's CLI surface with **dws-wukong** across the communication domain (chat / mail / minutes / todo / calendar / contact / aisearch / live / report / ding) and the structured-office domain (aitable / sheet / drive / wiki / doc), and switches the discovery version code from `bamboo` to `cedar` so the aligned command tree is served from its own discovery config.

### Added

- **`calendar book get|search` and `calendar acl list`** (cedar discovery overrides) — query a specific calendar (primary via `--id primary`), fuzzy-search calendars by name, and list a calendar's access-control entries. Maps to the calendar MCP `get_calendar` / `search_calendar` / `list_acls` tools.
- **`calendar attendee list|add|delete`** (`internal/helpers/calendar_commands.go`) — manage event participants under the wukong-aligned `attendee` naming (equivalent to the legacy `participant` group; calls `get/add/remove_calendar_participant`).
- **`minutes tag list` and `minutes tag query --tag-id`** — list a user's AI-minutes tags and query minutes by tag (`query_user_tag_list` / `query_minutes_by_tag_id`).
- **`minutes list mine|shared|all`** (`internal/helpers/minutes_commands.go`) — list own / shared / all minutes with renamed output fields.
- **`mail folder create|update|delete`, `mail template create|list|get|update|delete`, `mail contact create|list|update|batch-delete`, and `mail message list`** — full mail folder / message-template / contact CRUD plus folder-scoped message listing.
- **`chat file upload`** (`internal/helpers/chat_file.go`) — upload a local file (init/PUT/commit) or a remote URL to a conversation's file space.
- **`todo task add-attachment`** (`internal/helpers/todo_commands.go`) — attach a local file to a todo (multi-step upload).
- **aitable extensions** (`internal/helpers/aitable_extra.go`) — advanced permission / roles, view sub-commands (lock / duplicate / frozen-cols / row-height / fill-color-rule / card / timebar), section node management, workflow enable/disable, record `upsert` / `share-url` / `history-list` / primary-doc, and field search-options. Helper tools route to the hardcoded `aitable-helper` supplement endpoint.
- **sheet, drive, wiki, doc helper coverage** synced from dws-wukong (`internal/helpers/sheet.go`, `drive.go`, `wiki.go`, `doc.go`).

### Changed

- **Discovery version code `bamboo` → `cedar`** (`internal/market/registry.go`; `discoveryAPIPath = "/cli/discovery/apis/cedar"`) — version codes step by first letter (bamboo → cedar → …); `cedar` carries the dws-wukong alignment. Older binaries keep reading `bamboo`, so the change is isolated to this release line. All test/mock/generator fixtures updated to the cedar path.
- **CLI output envelope aligned with wukong for cross-edition parity** (`internal/app/runner.go`, `internal/compat/registry.go`) — dry-run prints a `DRY-RUN Arguments:` line, successful results carry `success: true`, missing-required-flag wording is unified to `missing required flag(s): --x`, and OutputTransform applies to the response content layer.
- **New flag transforms** (`internal/compat/transform.go`) — `parse_bool` (explicit boolean strings so `--flag false` is honoured) and `attendance_class_check_time` (`HH:mm` → UTC+8 milliseconds for shift check-times).
- **`--calendar-id` accepted on calendar event / participant / room / attachment commands** so calendars other than the primary can be targeted.

### Fixed

- **Client-side validation** for calendar recurrence completeness and attendance schedule / class / group inputs, surfacing input errors before they reach the server.

## [1.0.42] - 2026-06-25

This release rounds out `dws dev connect` — bridge a DingTalk robot to your local AI (Claude Code / Codex / opencode / Qoder / …): a generic `custom` channel for any headless CLI tool, in-chat `/new` / `/clear` session commands aligned to each agent's real session op, and a fix for long opencode turns being cut at 30 seconds.

### Added

- **`dws devapp robot connect` — generic `custom` channel for self-built / unsupported AI tools** (issue #37; `internal/helpers/devapp_connect.go`, `internal/helpers/connect_stream.go`) — a new `--agent-cmd "<command>"` flag (and `custom` channel) lets the bot forward to any headless AI CLI that takes a question as its trailing argument and prints the answer to stdout, so tools that aren't built-in (e.g. 网易有道龙虾 LobsterAI) or self-built agents can be onboarded without code changes. `--agent-cmd` forces the `custom` channel unless `--channel` is set explicitly; detection also falls back to `custom` when `DWS_AGENT_CMD` is present.

### Changed

- **`robot connect` now hints how to match terminal answer quality** (issue #39; `internal/helpers/devapp_connect.go`) — when neither a work dir nor a knowledge source is configured, the connector prints a one-time note that the bot runs in a clean temp dir without local project context, pointing at `--agent-workdir` / `--knowledge-dir` / `--knowledge-source` / `--agent-model`. The robot quickstart gains matching FAQ entries, plus a clarification that step 3 (`robot connect`) produces no approval ticket (issue #19).

- **`robot connect` session commands `/new` vs `/clear` now use each channel's real session op** (PR #20; `internal/helpers/connect_opencode.go`, `internal/helpers/connect_stream.go`) — `/new` (and `/start`, `/reset`) opens a fresh session and leaves the previous one intact (resumable where the agent supports it); `/clear` actively disposes the current session through the agent's real delete primitive — opencode issues `DELETE /session/:id`. Channels whose agent exposes no delete in the mode DWS drives it (Codex app-server, Qoder stream, Claude-family exec) fall back to a reset, so `/clear` behaves like `/new` there. Previously both commands only dropped the local `conversationId → sessionId` mapping, so the two were indistinguishable and opencode sessions were never disposed (they leaked).

### Fixed

- **`robot connect` no longer aborts long opencode turns at 30 seconds** (PR #19; `internal/helpers/connect_opencode.go`) — the shared opencode HTTP client hard-coded a 30s `Timeout` that covered every request, including `POST /session/{id}/message`, so a long agent turn (e.g. a multi-minute research report) was killed mid-flight with `context deadline exceeded (Client.Timeout exceeded while awaiting headers)` even though the per-turn budget (`DWS_AGENT_TIMEOUT_MS`, default 300s) was far larger. The client-level deadline is removed so the per-request ctx governs the round-trip; only the `/global/health` probe keeps a short 10s timeout so startup detection stays snappy.

## [1.0.41] - 2026-06-24

This release makes the installers work from mainland China out of the box (no env var) and keeps the Gitee mirror in sync automatically.

### Added

- **Auto-fallback to the Gitee mirror when GitHub is unreachable** (#492; `scripts/install.sh`, `scripts/install.ps1`, `scripts/install-skills.sh`) — the installers probe GitHub Releases on startup and, when it is unreachable (typical in mainland China), automatically resolve the version and download every asset (binary, `checksums.txt`, `dws-skills.zip`) from the Gitee mirror instead. A plain `curl … | sh` now works in China with no `DWS_GITEE_REPO` needed. Explicit `DWS_GITEE_REPO` still wins, `DWS_NO_FALLBACK=1` forces GitHub, and local source-checkout installs skip the probe.

### Changed

- **CI mirrors repo code to Gitee automatically** (#493; `.github/workflows/mirror-to-gitee.yml`) — the mirror workflow now pushes `main` + tags to the Gitee mirror over HTTPS using `GITEE_TOKEN` (no SSH key), on every push to `main` and every tag, keeping the Gitee `raw/main` install scripts and tags in sync without any manual `git push`. Gated on `GITEE_TOKEN`; skips cleanly when unset.

## [1.0.40] - 2026-06-24

This release adds China-accessible install mirrors so the CLI installs reliably from mainland China, where GitHub raw + Releases are slow or fail.

### Added

- **China mirror via Gitee + npmmirror** (#486; `scripts/install.sh`, `scripts/install.ps1`, `scripts/install-skills.sh`, `scripts/release/sync-to-gitee.sh`, `.github/workflows/release.yml`, `.github/workflows/mirror-to-gitee.yml`) — an opt-in `DWS_GITEE_REPO` env var makes all three installers resolve the latest version and every release asset (binary, `checksums.txt`, `dws-skills.zip`) from the Gitee OpenAPI v5 instead of GitHub; with it unset, installation defaults to GitHub (fully backward compatible). The release pipeline mirrors release attachments to the matching Gitee release after each tag (gated on `GITEE_TOKEN`/`GITEE_REPO`), and a hub-mirror workflow keeps the repo code in sync (gated on `GITEE_PRIVATE_KEY`). README documents three China install channels: Gitee raw script, Gitee release binaries, and the npm package via `registry.npmmirror.com`.
- **Skills embedded in the binary** (#488; `skills_embed.go`, `internal/app/skill_setup.go`, `internal/app/skill_setup_embed.go`) — the `skills/` tree (mono + multi) is embedded into the `dws` binary via `go:embed` and `dws skill setup` defaults to the embedded copy, refreshing the installed skill instead of silently reusing a stale copy probed from the current working directory — so skills install offline with no separate download.

## [1.0.39] - 2026-06-18

This release makes the AI-sent indicator opt-in. 1.0.38 unconditionally tagged every user-identity send/reply with the edition claw identity, so the IM server rendered a "Send from AI" badge under every message — and on the open edition a stale hardcoded value even leaked the Wukong-branded label (「悟空AI发送」) to external users. The badge is now off by default and shown only when the caller explicitly asks for it.

### Added

- **`--ai-tag` opt-in flag for `chat message send` / `chat message reply`** (#477; `internal/helpers/chat.go`) — by default no `clawType` tool argument is attached, so delivered messages carry no "Send from AI" badge. Passing `--ai-tag` attaches `edition.ClawType()` so the IM server renders the badge (open edition `openClaw` → 「通过AI发送」; the wukong overlay sets its own value → 「悟空AI发送」). Covers the text/Markdown, rich-media, and `--user`/`--open-dingtalk-id` direct send paths plus `reply`. Bot (`send-by-bot`) and webhook sends are intentionally untouched — they already render as bot messages. The badge is opt-in so dws does not brand every message a user sends.

### Fixed

- **`dws chat message reply` no longer leaks the Wukong AI label on the open edition** (#475, fixes #474; `internal/helpers/chat.go`, `pkg/edition/edition.go`) — the reply path hardcoded `clawType: "wukong"`, so open-source quoted replies were tagged 「悟空AI发送」 by the IM server, leaking Wukong branding to external users (reported by an external customer integrating via openclaw). The value now derives from the edition via the new `edition.ClawType()` accessor (open → `DefaultOSSClawType` = `openClaw`), and — together with #477 — is only attached when `--ai-tag` is passed. The earlier fix existed on a branch (PR #450) but was never merged to main; #475 cherry-picked it.

## [1.0.38] - 2026-06-16

This release adds client-side agent attribution for usage stats, fixes two commands that silently misbehaved (`dws sheet export` hanging, `dws upgrade --dry-run` actually upgrading), hardens the document write path against server-rejected characters, and makes the long-broken `--no-browser` login flag actually work.

### Added

- **Client-side `agent_code` detection + per-channel agent instance id for usage stats** (#467; `internal/auth/agent_code_detect.go`, `internal/auth/identity.go`, `docs/agent-code.md`) — every MCP request now carries `x-dingtalk-dws-agent-code` (which agent host is driving dws — e.g. `claudecode` / `codex` / `qoder` / `cursor` / `hermes` / `openclaw`, falling back to `custom`), `x-dws-agent-instance-id` (a per-machine×channel id, `dwsa_<base62(sha256(machineId|agent_code))>`), the existing machine-level `x-dws-agent-id`, and `X-Cli-Version`. Detection is a confidence ladder, each signature verified on real hosts / official docs (never guessed; anything unrecognized resolves to `custom`): T0 explicit `DINGTALK_DWS_AGENTCODE`, T1 per-agent env signatures, T2 `VSCODE_BRAND` covering the whole VS Code fork family, T3 the macOS `__CFBundleIdentifier` map, T4 `custom`. `identity.json` migrates v1 → v2 transparently and keeps `x-dws-agent-id` machine-level for continuity. **Trust boundary:** `agent_code` and both ids are client self-reported and forgeable — they are for stats / observability only and must not be used for auth, authorization, rate-limiting, billing, or revocation. Server-side gateway work (header passthrough allowlist + logging the fields into the warehouse) is required before the data lands and is tracked separately.

### Fixed

- **`dws sheet export` no longer hangs for the full ~5-minute poll timeout** (#462; `internal/compat/pipeline.go`) — the pipeline poll loop compared the API status against `pollUntilValue` with case-sensitive `==`, but the API returns `"success"` while the pipeline config declares `"SUCCESS"`, so the match never fired and the loop spun until timeout. Switched to `strings.EqualFold`, aligning with the case-insensitive `normalizeAsyncStatus` helper already used for `doc export` / `aitable export`.
- **`dws upgrade --dry-run` now previews instead of performing a real upgrade** (#416, fixes #364; `internal/app/upgrade.go`) — `newUpgradeCommand` registered no `--dry-run` flag and never read the global persistent one, so `--dry-run` fell through and ran a real, irreversible upgrade (download + binary replace), directly contradicting the flag's documented `预览操作内容，不实际执行` contract. It now resolves the target release and platform asset (so "already latest" / "no build for this platform" is still surfaced), prints the 1–5 steps it *would* perform via the side-effect-free `writeDryRunPlan`, and returns before any backup / download / replace. Covered by `TestWriteDryRunPlan_*` and an updated help test.
- **`dws doc create` / `dws doc update` strip server-rejected characters instead of failing** (#465; `internal/helpers/doc.go`, `internal/helpers/doc_jsonml.go`) — the Markdown write path sent raw content straight through, and the dangerous-Unicode strip only ran on the JSONML branch, so content carrying C0 control characters (anything `< 0x20` except `\t` / `\n`), DEL (`0x7F`), or zero-width / line-separator codepoints (`U+200D`, `U+2028`, `U+2029`) — common in LLM-generated or copy-pasted text — was rejected by the server-side `RejectControlChars` validator and the command failed. `stripDocDangerousUnicode` is renamed to `stripDocInputUnsafe`, extended to match the authoritative `apiclient.rejectDangerousChars` set, and applied on both the Markdown and JSONML node write paths. Tab and newline are preserved. Ported from dws-wukong.
- **`dws auth login --no-browser` is now honored** (#365; `internal/app/auth_command.go`, `internal/auth/device_flow.go`, `internal/auth/oauth_provider.go`) — the flag was already defined (and hidden) but never wired to the login providers, so the browser always opened regardless. The value is now passed into `DeviceFlowProvider.NoBrowser` / `OAuthProvider.NoBrowser` and gates the `openBrowser` call; the flag is also unhidden so headless / remote sessions can discover it.

## [1.0.37] - 2026-06-11

This release realigns the npm channel and hardens PAT batch grants. Background on the npm realignment: 1.0.36 was re-cut on GitHub on 2026-06-11 to fold in the canonical-tree poisoned-cache guard (#454), but the npm registry permanently forbids republishing a version number, so the npm package stayed on the original, unguarded cut. 1.0.37 is therefore the first version where **every** distribution channel — GitHub releases, `dws upgrade`, the install scripts, and npm — ships the same guarded build. If you installed 1.0.36 from npm, upgrade to this version.

### Fixed

- **PAT batch grants carry the agent identity and require explicit confirmation** (#455; `internal/pat/chmod.go`, `internal/auth/channel.go`, `internal/app/runner.go`) — an explicit `--agentCode` flag or the `DINGTALK_DWS_AGENTCODE` env var is now carried into PAT batch plan/grant arguments instead of being dropped, and a missing agentCode is forwarded as absent so the PAT core can apply the server-side default rather than failing. Batch grants now refuse to execute without an explicit `--yes` (dry-run and single-scope grants keep their existing behavior), closing the gap where a multi-scope grant could fire without a deliberate confirmation. Only the canonical env name `DINGTALK_DWS_AGENTCODE` is recognized; draft/reversed spellings from earlier iterations are ignored. Verified against prepub: dry-run, single grant, flag-priority grant, and batch grant all resolve the target agentCode, with the granted rows confirmed server-side. Tests: `internal/pat/chmod_test.go`, `internal/pat/browser_policy_test.go`, `test/unit/pat_host_owned_signal_test.go`.

## [1.0.36] - 2026-06-10

This release closes out the poisoned-discovery-cache lock-out for good, with four layers of defense landing together. The lock-out class (seen again on 2026-06-09 as `chat_permission_grant flag redefined: params`): the dynamic command tree is built from cached discovery data **before** Cobra dispatches any command, so a pflag panic fed by a poisoned cache aborted *every* invocation — including `dws cache refresh` and `dws upgrade`, the very commands that could repair it. Now: (1) any panic during the build is recovered instead of crashing (#447), (2) the four known envelope shapes that made pflag panic are skipped at registration so they never fire (#449), (3) when an unknown panic class does fire, the CLI quarantines the poisoned cache and rebuilds itself from a fresh fetch — and `dws upgrade` clears the discovery caches after every binary swap, so simply getting this version onto a machine is enough to escape, no manual cache surgery (#452), and (4) the same guards now also cover the canonical `dws mcp` tree, which is built even earlier and sat outside all three defenses as originally cut (#454 — this release was re-cut on 2026-06-11 to include it; verified against the preserved real poisoned cache from the 2026-05-25 incident). Also in this release: `dws devdoc` gains RAG-backed Open Platform doc search and a new error-diagnosis command (#434), and `dws doc create` stops producing documents with two identical titles (#448).

**Escaping a locked-out older binary**: a binary ≤1.0.35 bricked by a poisoned cache cannot run `dws upgrade`. Either bypass the cache for one invocation with `DWS_CACHE_DIR=$(mktemp -d) dws upgrade`, or delete `~/.dws/cache/<partition>/tools/` by hand, or reinstall via the install script. Once 1.0.36 is on the machine this never needs doing again.

### Added

- **`dws devdoc` — RAG-backed Open Platform doc search and error diagnosis** (#434; `internal/helpers/devdoc.go`, `internal/transport/client.go`) — `dws devdoc article search` now routes to the upstream `search_open_platform_docs_rag` tool, returning structured RAG/reference payloads (the CLI stays a thin invoker; no extra AI analysis layer). New `dws devdoc error diagnose` (alias `troubleshoot`) routes to `search_open_error_code_rag` for diagnosing DingTalk Open Platform API errors, with `--request-id` (hidden `--trace-id` kept for compatibility), `--error-code`, `--error-message`, `--api`, `--context`, `--query`, `--page`, `--size`. Transport-side: query parameters required by DingTalk MCP gateway URLs are preserved on the wire but their values are redacted from debug logs. Default MCP / skill hosts stay on production `https://mcp.dingtalk.com` (prepub remains runtime-configurable). Skill docs (mono + multi `dingtalk-devdoc`) and `docs/command-index.md` updated alongside.

### Fixed

- **CLI no longer bricks when the dynamic command build panics — degrades to built-in commands** (#447; `internal/app/legacy.go`) — `buildEnvelopeCommandsSafe` wraps the envelope-driven build in a local `recover()`. On panic the CLI logs it, prints a stderr hint, and falls back to the hardcoded helper commands, so `auth` / `cache` / `doctor` / `version` / `upgrade` and the helpers stay alive and `dws cache refresh` can rebuild the poisoned cache. Before this, the only recovery from the pre-1.0.32 lock-out class was manually deleting cache files; the duplicate-flag class itself had been fixed at the builder level, but any *future* panic class in the cache-driven build would have bricked the CLI again. Tests: `TestNewLegacyPublicCommandsPanicFallsBackToHelpers`, `TestNewLegacyPublicCommandsNoPanicKeepsDynamicPath`.
- **Envelope-driven flag registration no longer panics on the four known malformed-envelope shapes** (#449; `internal/compat/registry.go`) — while reproducing the lock-out byte-for-byte, four envelope shapes were found still forwarded to pflag calls that panic, each bricking every invocation: a flag named `params` / `json` colliding with the reserved payload flags (the original `flag redefined: params` — earlier dedup fixes covered the alias list and Detail-schema path but not the primary name); two bindings resolving to the same long flag name across bindings; two flags claiming the same shorthand; and a multi-character shorthand. Two small guards applied at every registration site (`ApplyBindings`, `registerPositionalAliasFlags`): `canRegisterFlag` skips duplicate/reserved long names (the value stays reachable via `--params`), and `safeShorthand` drops an invalid or already-taken shorthand while keeping the long flag. The trailing `--json` / `--params` registration is now idempotent. Defense in depth with #447: the escape hatch should never trigger for these known vectors. Test: `TestBuildDynamicCommandsSurvivesMalformedFlagEnvelope` (5 table-driven vectors).
- **Poisoned discovery cache now self-heals: quarantine + rebuild on panic, and `dws upgrade` clears discovery caches** (#452; `internal/app/legacy.go`, `internal/app/upgrade.go`, `internal/cache/store.go`) — #447's recovery is upgraded from "degrade and ask the user to run `dws cache refresh`" to a two-stage self-heal: on the first build panic the partition's discovery cache is moved aside to `<partition>.quarantined` (kept on disk for inspection; a previous quarantine is replaced so nothing accumulates — new `Store.QuarantinePartition`) and the build retried once against a fresh fetch. If the retry succeeds the user gets the full dynamic command tree with zero manual steps; only a second panic (remote envelope itself still poisoned, or offline) degrades to helper commands with the `cache refresh` hint. Additionally `dws upgrade` purges discovery-derived caches (`market` / `tools` / `detail` across all partitions — new `Store.PurgeDiscoveryData`) after a successful binary swap, leaving the co-located `downloads/` cache untouched, so an upgraded binary always rebuilds its command tree from fresh data instead of inheriting snapshots written by the old version. Tests: `internal/cache/store_quarantine_test.go`, rewritten `internal/app/legacy_panic_fallback_test.go` (self-heal success, double-panic degradation, no-cache no-op, happy path).
- **Canonical `dws mcp` tree no longer escapes the poisoned-cache guards** (#454; `internal/cli/canonical.go`, `internal/app/root.go`) — the canonical tree is assembled from cached catalog data *before* the legacy command build, so a pflag panic there — a tool schema property named after the reserved `--params` flag, exactly what the 2026-05-25 incident cache contained — bypassed #447/#449/#452 entirely and still bricked every invocation, including on this release as originally cut. Two layers, mirroring the existing guards: `applyFlagSpecs` skips reserved (`--json`/`--params`), duplicate, and alias-colliding flag names and sanitizes shorthands (`canRegisterToolFlag` / `safeToolShorthand`; a skipped property stays reachable through the reserved JSON payload flags), and `newMCPCommand` wraps the build in the #452 recover → quarantine → retry-once → degrade-to-stub sequence. Verified against the preserved real poisoned cache: the original cut locks out on `--version` / `cache refresh` / `doctor`; this build self-heals on first run and `cache refresh` clears the poison. Tests: `internal/cli/canonical_flag_guard_test.go` (4 cases), `internal/app/canonical_panic_fallback_test.go` (4 cases mirroring the legacy fallback suite).
- **`dws doc create` no longer produces a document with two identical headings** (#448; `internal/helpers/doc.go`) — the platform renders the document name as the page title, and LLM agents habitually repeat `# <title>` as the markdown body's first line despite the skill docs saying not to, so duplicate-heading documents kept appearing. The `doc create` helper (which wins the envelope merge via `preferLegacyLeaf`) now strips a leading ATX H1 whose text exactly equals `--name` (trimmed, case-insensitive) before forwarding to `create_document`, printing a stderr note so agents learn the convention. Deliberately conservative: only an exact match is removed (`# 背景` stays), ATX closing hashes are handled without over-trimming names ending in `#` (e.g. `C#`), H2+/setext headings are never touched, and a body that is nothing but the duplicate H1 omits the `markdown` param instead of sending an empty string. JSONML bodies are out of scope. Tests: `TestStripLeadingDuplicateTitleHeading` (9 cases) plus three end-to-end cobra tests asserting the exact `markdown` param sent.

## [1.0.35] - 2026-06-08

### Fixed

- **`chat message send` @-mentions not rendered in group / direct chat** (#433, `internal/helpers/chat.go`) — when sending a group message or an openDingTalkId direct message (`send_personal_message`) as the current user, the `content` body was packed with `json.Marshal`, whose default HTML escaping turns the `<` `>` in `<@openDingTalkId>` / `<@all>` into `<` `>`. The DingTalk client renders @-mentions by matching the **literal** `<@...>` token, so after escaping the match fails and the mention shows as plain text — while the API still returns `success`, masking the bug. Fix: add `marshalMessageContent`, which serializes `{title,text}` with `json.Encoder` + `SetEscapeHTML(false)`; both the group and openDingTalkId-direct `send_personal_message` paths now use it, preserving the literal `<@...>`. Added regression test `TestChatMessageSendContentNotHTMLEscaped` asserting the content keeps the literal token and is never HTML-escaped. Verified on a real device: `@someone` and `@all` both render as clickable blue mentions.
- **`chat` skill docs & scripts aligned to direct-chat `list-direct`** (#424) — `chat message list` now supports group chats only (`--user` / `--open-dingtalk-id` removed); reading a direct chat moves to the dedicated `list-direct` command, but the skill docs and scripts still taught `chat message list --user`, which now errors with `unknown flag: --user`, also breaking `chat_history_with_user.py` (listed as the "preferred" way to query direct chats). This update: `skills/{mono,multi/dingtalk-chat}/references/products/chat.md` switches `message list` to group-only and documents the new `list-direct` command, syncing the intent routing / key-distinction / context-passing tables / caveats; `skills/mono/references/best_practices/01-messaging.md` changes query-private-chat from `list --user` to `list-direct` (the multi version was already updated); `chat_history_with_user.py` (mono + multi) now calls `list-direct` and fixes response parsing (unwraps `result.messages`, aligns `createTime/content/sender` fields — it previously crashed on `'str' object has no attribute 'get'`). Direct-chat sending still uses `chat message send --user` (since v1.0.34 the direct-send rpc is folded into the `send` command; there is no separate `send-direct`). Docs/scripts only; no change to CLI binary behavior.
- **`pat chmod` batch authorization did not pass through `agentCode`** (#414, `internal/pat/chmod.go`) — the batch plan / grant paths (`buildBatchPlanArgs` / `batchArgs`) previously carried `agentCode` only in the single-grant `toolArgs`; batch calls omitted it, so a batch authorization with an explicit `agentCode` was processed under the default agent. Fix: the batch plan / grant args now also carry `agentCode`, matching the single-grant path.
- **`pat` JSON output escaped the authorization URL into an unreadable form** (#401, `internal/pat`) — the authorization URL attached to PAT error messages, after default HTML escaping, turned `&` into `&`, breaking the link when copied / recognized on mobile. Fix: the PAT error-enrichment JSON output now uses `SetEscapeHTML(false)` (scoped to PAT JSON only), preserving the readable `&` separators.

## [1.0.34] - 2026-06-03

### Changed

- **Service discovery path now carries a version-coded segment** (`internal/market/registry.go`) — the server-list endpoint moves from `/cli/discovery/apis` to `/cli/discovery/apis/bamboo`. The path is now a single `discoveryAPIPath` constant so future version bumps touch one place. Only the path changes; the MCP base host stays on production `https://mcp.dingtalk.com` and the auth / skill / doctor endpoints are untouched. Discovery via the edition `DiscoveryURL` hook (full-URL `FetchServersFromURL`) is unaffected. Server side must serve the new path.

### Removed

- **`dws aiapp` — AI application product taken offline** — removed the `aiapp` product surface (`create` / `query` / `modify`) from the CLI: deleted `internal/helpers/aiapp.go`, dropped it from the generator coverage targets and `knownRegistryProducts`, removed the `aiapp` skill references (mono `references/products/aiapp.md` + `dingtalk-aiapp` multi skill), and unpublished the `aiapp` server from the service-discovery envelope. Product count drops from 19 to 18.

## [1.0.33] - 2026-06-02

This release merges the multi-contributor `pre-mcp-discovery` feature branch into `main` as a single squash (#391), bringing a large batch of new product surface — full DingTalk **docs** (`doc`), **knowledge base** (`wiki`), **AI app** (`aiapp`), AI-table **forms** + **import/export**, and reworked **mail** / **todo** / **report** command trees — while keeping service discovery pinned to production `https://mcp.dingtalk.com` (the branch's `pre-mcp.dingtalk.com` endpoint change was deliberately excluded; the four host constants in `skill_command.go` / `auth/endpoints.go` / `cli/loader.go` / `market/registry.go` stay on prod). It also folds in the portable auth bundle (`dws auth export` / `import`, #357) and PAT batch authorization (#389).

### Added

- **`dws doc` — full DingTalk document command family** (#387, #362, #388, #390; `internal/helpers/doc.go`, `internal/helpers/doc_jsonml.go`, `internal/helpers/docjsonml/`) — search / list / info / read / create / update / upload / download / copy / move / rename, plus `file`, `folder`, `block`-level editing and `comment` (list / create / reply / create-inline). Authoring supports both DocxXML and a JSONML format with a v2 schema validator (`docjsonml/jsonml-schema-v2.json` + `doc_jsonml_validate_v2.go`). Document export and OA alignment land here.
- **`dws wiki` — knowledge base management** (`internal/helpers/wiki.go`, `internal/helpers/wiki_proxy.go`) — knowledge space `create` / `get` / `list` / `search` and member `add` / `list` / `update`, routed through a wiki proxy server.
- **`dws aiapp` — AI application lifecycle** (`internal/helpers/aiapp.go`) — `create` (with prompt / attachments / skills), `query` by task ID, `modify` by thread ID.
- **`dws aitable` forms + import/export** (`internal/helpers/aitable_form.go`, `internal/helpers/aitable_export_import.go`) — datasheet form management and full record import/export, the latter driven through the async-task helper for large datasets.
- **Reworked `chat` / `report` / `todo` / `contact` / `mail` command trees aligned to the Wukong baseline** (#355; `internal/compat/mail_hooks.go`, `internal/compat/todo_hooks.go`, `internal/helpers/report_readable.go`) — mail and todo gain dedicated compat hooks; `report` gains a human-readable rendering path alongside the raw JSON, plus deprecation shims for the old report shape.
- **`dws auth export` / `dws auth import`** (#357) — portable auth bundle for migrating Linux sandbox credentials. Exports the encrypted keychain (`~/.local/share/dws-cli`, including `auth-token.enc` and `dek`) plus required `~/.dws` config so refresh tokens survive import; copying only `app.json` leaves access tokens expiring after ~2 hours. Supports `-o` / `-i` tar.gz paths and `--base64` for copy/paste between sandboxes. `dws auth status` now shows refresh-token validity in table output.
- **Async-task and paging infrastructure** (`pkg/asynctask/`, `pkg/paging/`) — shared helpers underpinning long-running operations (e.g. aitable import/export, doc export) and cursor/page traversal.

### Changed

- **`envelope` now registers `cli.Aliases` as cobra aliases** (#391) — discovery-generated commands expose their declared aliases natively in the command tree, with accompanying command-structure and JSON-parsing cleanups.
- **Breaking: `dws pat chmod` prints a compact authorization summary by default, and gains batch authorization flows** (#389; `internal/pat/chmod.go`) — scripts that parse the raw MCP JSON from stdout must now pass `--format json` or `--verbose` to keep the machine-readable payload; the default summary keeps grant status, agentCode, grantType, scope counts, and a next-action hint. New batch grant/plan flows (`pat.batch_grant` / `pat.batch_plan`) authorize multiple products in one session, fall back to the legacy single-grant path when the server reports `PAT_BATCH_AUTH_UNSUPPORTED`, use the server's default `agentCode` when none is given, and surface per-tool authorization metadata for grant planning.
- **Skill packs synced to the Wukong-aligned content** across attendance / calendar / minutes / oa / sheet and others (#391).

## [1.0.32] - 2026-05-25

Two user-visible regressions resolved plus two AI-agent discoverability fixes. `dws drive upload` was returning `HTTP 403 SignatureDoesNotMatch` for any file whose MIME detects to a non-empty value — basically every real file — because the helper added a client-side `Content-Type` fallback whenever `drive.get_upload_info` returned an empty headers map. DingTalk drive's OSS presigned PUT URLs are signed against an empty `Content-Type` at signing time, so any client-supplied header makes the signature OSS recomputes diverge from the server-signed one, and the PUT is rejected (#347). On Apple Silicon, `dws upgrade` was aborting at the "解压并验证" step with `signal: killed` because GoReleaser cross-compiles `darwin/arm64` binaries on `ubuntu-latest` with no codesign step, and macOS 11+ `amfid` SIGKILLs unsigned arm64 binaries on first exec (#339) — the release pipeline now ad-hoc signs every darwin tarball, and the upgrade client self-heals if it ever encounters an unsigned binary again. On the AI-agent discoverability side, `dws aitable attachment upload-file` (the one-shot prepare + PUT + commit composite) is no longer hidden from `--help` — agents that only browse the command tree were getting stuck at the prepare-only `attachment upload` step, which returns an upload URL + fileToken but doesn't actually upload. And `dws --help` itself now surfaces the missing-command upgrade hint that the custom `renderRootHelp` had been silently dropping from cobra's `root.Long`.

### Added

- **`dws aitable attachment upload-file` is now visible in `dws aitable attachment --help`** (#347, `internal/helpers/aitable.go`) — the hardcoded one-shot composite (prepare + HTTP PUT + commit, returns `fileToken` directly) was previously marked `Hidden:true` and only reachable by agents that read `skills/references/products/aitable.md`. Agents that only discover commands via `--help` were getting stuck at the sibling envelope-generated `attachment upload` (prepare-only): they'd receive `uploadUrl` + `fileToken`, have no idea how to consume the URL, and either write the URL into the attachment field as if it were a token (wrong shape — the field expects `[{"fileToken":"ft_xxx"}]`) or fall back to "please use the UI" messages, which made `dws` look broken even though the capability was fully implemented. Unhiding mirrors the discoverability pattern `lark-cli base +record-upload-attachment` already follows. `Short` is tightened to explicitly mention the 3 steps it bundles; `Long` calls out the prepare-only sibling and recommends `upload-file` as the default for AI agents. The sibling `attachment upload` (prepare-only) keeps its envelope-generated registration but gets a new `Long` that states it is only step 1 of a 3-step flow, lists what an agent must do after (HTTP PUT to `uploadUrl`, then write `[{"fileToken":"ft_xxx"}]` into the attachment field), and points to `upload-file` as the recommended one-shot alternative. `TestAITableUploadFileCommandIsDiscoverable` in `internal/helpers/aitable_upload_file_test.go` guards against re-introducing `Hidden:true`.
- **`dws --help` root output now surfaces the `dws upgrade` hint when no listed command fits** (#347, `internal/app/root.go` + `internal/app/root_help.go`) — `root.Long` is set to `"提示: 如果遇到能力缺失、命令报错、新功能未注册、或无法完成任务, 请先用 'dws upgrade' 升级到最新版本后再试. 钉钉 OpenAPI 和 dws CLI 持续迭代, 新能力和 bugfix 会先在新版本上线."`. The custom `renderRootHelp` (which replaces cobra's default template to render the services / utilities sections) had been silently dropping `root.Long`; restoring it costs one `Fprintln` after the command list, separated by a blank line. The natural failure mode for both agents and users staring at `dws --help` is to give up or hack around when none of the listed commands fit — but in many cases the right action is simply `dws upgrade`, because new capabilities and bugfixes ship continuously and a missing command is usually a stale-binary issue. `TestRenderRootHelpIncludesLong` in `internal/app/visibility_test.go` uses a sentinel `Long` string and asserts the rendered output contains it verbatim, so any future rewrite of the help renderer that drops `Long` fails this test immediately.

### Fixed

- **`dws drive upload` no longer fails with `HTTP 403 SignatureDoesNotMatch` on any non-empty MIME type** (#347, `internal/helpers/drive.go`) — `httpPutDriveFile` was setting `req.Header["Content-Type"] = fallbackMIME` whenever the prepare_upload response returned an empty headers map. DingTalk drive's OSS presigned URLs sign `StringToSign` against an empty `Content-Type` at signing time, so any client-side header makes the signature OSS recomputes at PUT time differ from the server's presignature, and the upload is rejected with `403 SignatureDoesNotMatch`. This broke every `dws drive upload` for any file whose MIME detects to a non-empty value (`image/png`, `application/pdf`, every common binary) — i.e. essentially every real upload. Fix: drop the `hasContentType` / `fallbackMIME` path entirely, trust the server's headers map as authoritative; empty map means "no client-side headers needed", do not infer. `httpPutDriveFile`'s signature loses the `fallbackMIME` parameter. Manual verification: `curl -X PUT -H "Content-Type:" --data-binary @file <same-presigned-url>` returns `HTTP 200`, proving the only difference was the client-side `Content-Type`. `TestHttpPutDriveFile_NoContentTypeWhenServerHeadersEmpty` guards the empty-map path; `TestHttpPutDriveFile_PassthroughServerHeaders` guards that server-provided `Content-Type` / `x-oss-*` headers are forwarded verbatim. Important: `internal/helpers/aitable.go`'s `upload-file` helper deliberately keeps its `Set("Content-Type", mimeType)` call — its OSS endpoint uses a different signing mode (server includes the client-declared MIME in the signature, verified across 12 file types — all succeed). The two helpers must not be unified without re-validating both endpoints.
- **`dws upgrade` no longer dies with `signal: killed` on Apple Silicon after fetching the new binary** (#339) — GoReleaser cross-compiles `darwin/arm64` binaries on `ubuntu-latest` with no codesign step, and macOS 11+ on Apple Silicon requires at least an ad-hoc signature on every arm64 binary; `amfid` SIGKILLs unsigned arm64 binaries on first exec, which the upgrade client surfaces as `signal: killed` and aborts at the "解压并验证" step. Two layers of fix:
  - **Release-side ad-hoc signing** (`scripts/release/post-goreleaser.sh` + `.github/workflows/release.yml`) — after GoReleaser produces the per-platform tarballs, `post-goreleaser.sh` unpacks each `dws-darwin-*.tar.gz`, applies an ad-hoc signature (`codesign --force --sign -` locally, `rcodesign` in CI), deterministically repacks the tarball, and rewrites the matching line in `checksums.txt` so the checksum stays consistent with the resigned tarball. `release.yml` installs `rcodesign 0.27.0` before GoReleaser runs. Every 1.0.32+ tarball ships signed; the install regression is fixed at the source.
  - **Client-side self-heal in `validateNewBinary`** (`internal/app/upgrade.go`) — when running the freshly-extracted binary returns `signal: killed` on darwin, the validator retries once after running `codesign --force --sign -` on the binary and clearing the `com.apple.quarantine` xattr. This keeps `dws upgrade` working even if a future release ever skips the signing step again, and covers users upgrading from older unsigned binaries. `internal/app/upgrade_test.go` (+80 lines) covers the retry path end-to-end: a stripped binary exits 137 on first exec, `validateNewBinary` recovers via ad-hoc sign + xattr clear, the final binary shows `Signature=adhoc` and runs.

## [1.0.31] - 2026-05-21

Closes the last drive-surface gap with the Wukong edition: `dws drive upload` lands as a single-shot composite (`drive.get_upload_info` → HTTP PUT to OSS → `drive.commit_upload`) so a local file reaches DingTalk drive in one CLI invocation, no manual three-step orchestration. Two more drive commands — `dws drive list-spaces` (list visible drive spaces) and `dws drive delete` (delete a drive file, routed via `serverOverride` to the doc MCP server) — ship via the portal envelope; `dws cache refresh` once to pick them up. Companion skill docs teach the agent to recognise dingpan URLs of the form `alidocs.dingtalk.com/document/edit?dentryKey=…` / `…/document/preview?dentryKey=…` and pass the whole URL through to `--node` instead of trying to extract `dentryKey` by hand (the server interprets `dentryKey` and a bare `nodeId` differently — manual extraction was failing).

### Added

- **`dws drive upload --file <path> [--folder <dentryUuid>] [--space-id <id>] [--file-name <name>] [--mime-type <type>]`** (#335, see `internal/helpers/drive.go`) — composite leaf that runs the full three-step upload internally:
  1. `drive.get_upload_info` — fetch the OSS-signed `resourceUrl` + `uploadId` + per-URL headers.
  2. HTTP `PUT` the file binary to OSS (10-minute timeout, attaches every header returned by step 1).
  3. `drive.commit_upload` — register the new file under the target space / folder.

  `--dry-run` prints the three step invocations as a single JSON payload without making any network calls. `--file -` is rejected on purpose: this is a local-path upload, not stdin streaming. `--folder` only accepts a `dentryUuid`; pure-numeric values are rejected up front (`validateDriveParentID`) so callers don't accidentally pass a chat-link `dentryId` (a different ID namespace) where the drive API expects a `dentryUuid`. Response normalisation handles all the wrapper shapes the upstream returns — `content` / `result` envelopes, `resourceUrls[]` arrays, and the flat `resourceUrl` / `uploadUrl` fallbacks — so the composite produces a stable JSON shape regardless of which path the upstream takes. The helper only registers `upload`; the existing six envelope-generated leaves (`list` / `info` / `download` / `mkdir` / `upload-info` / `commit`) keep flowing through dynamic discovery unchanged. `pickCommands.MergeHardcodedLeaves` guarantees dynamic leaves win on collision, so this helper only fills the upload gap.
- **`dws drive list-spaces` and `dws drive delete` (envelope rollout)** (#335, ships via portal envelope) — `list_spaces` registers as a plain `cliName` alias on the existing drive MCP server; `delete_document` registers with `serverOverride: doc` so the call routes to the doc MCP server (which owns the delete API), surfacing under the drive command tree for ergonomics. **Existing users must run `dws cache refresh` once** to pick up these two new leaves; no binary upgrade is required for them, but they pair naturally with the v1.0.31 client that ships `upload`.
- **`skills/references/url-patterns.md`** (#335) — single authority for dispatching `alidocs.dingtalk.com` URLs across doc / sheet / wiki. Five-way split: `/i/p/<token>` short links → expand via `doc info`; `/i/nodes/<id>` node URLs → probe with `doc info` and route by `contentType` / `extension` / `nodeType`; `/spreadsheetv2/...` → `sheet`; `/document/edit|preview?dentryKey=<key>` (dingpan format) → pass the whole URL to `--node`, do not strip `dentryKey` by hand; `/i/share/...` (read-only share) → use the `read_url` fallback. The "URL precheck" Step 0 in `skills/SKILL.md` now redirects every URL-bearing prompt through this dispatcher before the agent picks a product.

### Changed

- **`skills/references/products/doc.md` — `--node` accepts dingpan URLs end-to-end** (#335) — `dws doc info` / `dws doc read` examples gain two extra rows showing `--node "https://alidocs.dingtalk.com/document/edit?dentryKey=<KEY>"` and `…/preview?dentryKey=<KEY>` as first-class `--node` inputs. The "URL recognition & DOC_ID extraction" table adds the `document/edit|preview?dentryKey=<key>` row, and the extraction rules are split into three explicit clauses so the agent stops manually pulling `dentryKey` out of the URL and feeding it as a bare `nodeId` (which the server rejects). The "nodeId dual-format note" upgrades to "nodeId multi-format note" with four equivalent `--node` input shapes side by side.

## [1.0.30] - 2026-05-19

Aligns the open-source CLI with the IM envelope and schema-pipeline plumbing the Wukong edition has been running in pre-prod, plus three user-visible quality-of-life fixes. The most visible one: chat-bot webhook payloads carrying literal Chinese mentions (`@所有人 周报来了` / `@张三 看一下`) no longer fail with `file not found` — `@` is only treated as the `@<filename>` file-injection prefix when followed by an ASCII path-shaped character. The `chat` command tree is refactored to lean on the service-discovery envelope: thin wrappers (`chat search`, `chat group rename`, `chat group members list/add/remove/add-bot`, `chat bot search`) move out of the hardcoded helper and become envelope-generated dynamic commands; the helper keeps only the chat commands with real business logic (intelligent routing, current-user resolution, response normalization, stdin/@file input). A new `dws chat message reply` joins the existing `send` / `send-by-bot` / `recall-by-bot` / `send-by-webhook` family. Underneath: `transform: invert_bool` lets envelopes flip boolean semantics between CLI surface and MCP body (e.g. `--off` ↔ `mute=true`); the pipeline executor fail-fast on upstream `content.errorCode` instead of polling forever; service-discovery dedup keeps two envelope entries that share an MCP endpoint but declare different `cli.id` as separate descriptors (so the `bot-root` / `bot-message` / `bot-group` trio fronting one MCP server stays as three distinct CLI command roots); and `dws chat` no longer nests as `dws chat chat` when two envelope servers both declare the same top-level command name.

### Added

- **`transform: invert_bool` for envelope flag overrides** (#317, see `internal/compat/transform.go`) — flips a boolean at send time. Strings `true`/`1`/`yes`/`on` → `false`; `false`/`0`/`no`/`off`/`""` → `true`. Used when the CLI surface and the MCP body have opposite semantics — e.g. envelope declares `--off` on the CLI but the MCP parameter is `mute=true` for "muted". The framework flips at send time so the envelope keeps the natural CLI verb without forcing every caller to remember the inverted mapping. Coverage in `internal/compat/transform_test.go`.
- **`dws chat message reply`** (#317, see `internal/helpers/chat.go`) — reply to a chat message. Sits alongside `send` / `send-by-bot` / `recall-by-bot` / `send-by-webhook` under `dws chat message`.

### Changed

- **`chat` command tree refactored to lean on the service-discovery envelope** (#317, commit `6be1247`) — `internal/helpers/chat.go` now only carries the chat commands that need real business logic on top of the raw MCP call: `chat message send` (current-user resolution + symmetric direct/group title validation), `chat message send-by-bot` / `recall-by-bot` / `send-by-webhook` (bot routing + stdin/@file input), and `chat group create` (response normalization). The thin wrappers — `chat search`, `chat group rename`, `chat group members list/add/remove/add-bot`, `chat bot search` — are now produced by the envelope as dynamic commands. Net diff in the helper: `+358 / -71` overall (re-aligning to envelope-owned chat structure), and `chat_test.go` drops 71 lines of test-stubs the dynamic path covers natively. Every previously documented chat command keeps the same flag set and the same MCP tool routing — the surface is just sourced differently.
- **Pipeline executor fail-fast on `content.errorCode`** (#317, see `internal/compat/pipeline.go`) — when an upstream tool returns a non-empty `content.errorCode`, `executePipelineCall` raises a validation error immediately with the upstream `errorMessage` instead of proceeding into the poll/download phase. Pre-execution cobra validation (`MarkFlagRequired`) only checks that a flag was set, not that its value was non-empty — so a `--required-flag ""` reaches the upstream tool and the upstream rejects with `errorCode`. Without the short-circuit the pipeline kept polling for a task ID that would never exist, either spinning to `PollTimeout` or burning through retries with no actionable error. Exit code 2 (validation), same as any other CLI-layer pre-flight rejection.
- **Service-discovery dedup keys now include `cli.id`** (#317, see `internal/market/registry.go`) — `NormalizeServers` used to dedup envelope entries by endpoint alone (and by `displayName` in the second pass), which collapsed envelope entries that intentionally split one MCP endpoint into multiple CLI command trees. The `bot-root` / `bot-message` / `bot-group` trio all front the same `.../server/4717...` MCP endpoint and share the displayName `机器人消息`, but each declares a distinct `cli.id` and a distinct CLI command root; the old dedup kept only the last-write and dropped two of them. The dedup key now appends `#<cli.id>` when present, falling back to endpoint / name when absent so historical envelopes without `cli.id` keep their existing behaviour. Coverage in `internal/market/registry_test.go`.

### Fixed

- **`@<text>` injection no longer eats Chinese mentions like `@所有人` / `@张三`** (#317, see `internal/cli/stdin.go`) — `ReadFileArg` and `ResolveInputSource` used to treat *any* value starting with `@` as the `@<filename>` injection syntax. Chat-bot webhook payloads commonly contain literal mentions, so `dws chat message send-by-bot --text "@所有人 周报"` was failing with `file not found: 所有人 周报` before the message reached the API. The new `looksLikeFilePath` heuristic accepts `@` followed by an ASCII path-prefix character (`A-Z` / `a-z` / `0-9` / `.` / `/` / `~` / `_` / `-`), or `@-` for stdin, and passes the value through unchanged otherwise. `@A 但接下来都是中文@测试` *does* still attempt a file lookup because the rune right after `@` is ASCII — this matches the documented `@<path>` prefix shape. The historical "bare `@` is an error" behaviour is preserved. Coverage in `internal/cli/stdin_test.go::TestReadFileArgChineseAtMention`.
- **`dws chat` no longer nests as `dws chat chat` when two envelope servers contribute the same top-level command** (#317, see `internal/compat/dynamic_commands.go`) — `BuildDynamicCommands` used to overwrite `topLevel[name]` on the second contribution and rely on `attachOrMerge` later, which then attached the *whole* incoming command (named `chat`) under the existing root, producing `dws chat chat <leaf>`. The new `mergeSubcommandsInto` moves the second contribution's *children* under the first root and drops the duplicate wrapper, so e.g. `group-chat` + `im` envelopes that both declare `cli.command: chat` produce a single flat `dws chat` subtree.
- **Multi-server tool-name authority correction in the runtime runner** (#317, see `internal/app/runner.go` + `internal/app/direct_runtime.go`) — when two envelope servers share the same `cli.command`, the per-product endpoint map `endpoints[cmd]` in `registerDynamicServer` is second-writer-wins, and `catalog.FindProduct` may return the wrong server's endpoint for a tool whose real owner is the *other* server. `runtimeRunner.Run` now cross-checks the canonical tool→endpoint map exposed by the new `directRuntimeToolEndpoint`: when the per-tool endpoint exists and differs from the per-product endpoint the catalog returned, the tool-owner endpoint wins. Pairs with the registry dedup change above so the routing matches the dedup result.

## [1.0.29] - 2026-05-17

Three discovery-envelope products land on the open-source surface — `aiapp` (AI applications), `live` (DingTalk live streaming), and `aisearch` (enterprise people search) — closing the gap with the Wukong edition's product list. The `aisearch` envelope ships rich model-tolerance affordances (short flags, flag aliases, subcommand aliases) so AI agents that hallucinate keyword synonyms (`--query` / `--name` / `--q` / `--text` / `--find`) or alias subcommands (`search` / `find` / `query` / `user` / `people` / ...) still route to the canonical `person` tool instead of erroring out. To support that final fragment of agent tolerance, `internal/compat/registry.go` relaxes the envelope-generated leaf command's `Args` validator from `cobra.NoArgs` to `cobra.ArbitraryArgs` — restoring cobra's own default (`legacyArgs` returns nil for leaves) so trailing positional words are silently ignored. Plus the previously-shipped credential-isolation fix.

### Added

- **`dws aiapp` / `dws live` / `dws aisearch` — three new products discovered via envelope** (no public issue; pre-Diamond rollout) — open-source `dws` now exposes:
  - **`dws aiapp`** — AI application lifecycle: `create --prompt <p> [--attachments <json>] [--skills <csv>]` / `query --task-id <id>` / `modify --prompt <p> --thread-id <id> [--skills <csv>]`. Backed by upstream `create_ai_app` / `query_ai_app` / `modify_ai_app` MCP tools.
  - **`dws live stream list`** — list my DingTalk live streams. Backed by upstream `get_my_lives`.
  - **`dws aisearch person`** — enterprise people search by keyword + multi-dimension filter. Dimensions: `all` (default) / `name` / `department` / `position` / `duty` / `supervisor` / `subordinate` / `phone` / `jobNumber` — multiple comma-separated (`--dimension name,department`). Backed by upstream `enterprise_person_search`.
  - The `aisearch` envelope additionally registers `-w` / `-d` short flags (keyword / dimension); hidden flag aliases `--query` / `--name` / `--q` / `--text` / `--find` all routing to `keyword`; and cobra subcommand aliases `search` / `find` / `query` / `user` / `people` / `search-person` / `search-user` / `user-search` / `lookup` / `ask` / `contact` all routing to `person`. This closes the F-class model-tolerance regression cases in `dws-wukong/auto-test/cli_to_mcp/testcases/aisearch/test_90_aisearch_param_regression.py` (50/50 pass for aiapp + live + aisearch on the pre-mcp build).
  - **Users must run `dws cache refresh` once** to pick up the new envelopes; no binary upgrade is required, but pairs naturally with the v1.0.29 client (see Fixed below for the envelope-leaf-Args change).

### Fixed

- **Envelope-generated leaf commands now tolerate trailing positional args** (#306, no public issue) — `NewDirectCommand` in `internal/compat/registry.go` was hard-coding `cobra.NoArgs` for leaves without positional bindings (`totalMax == 0`). This is stricter than cobra's own `legacyArgs` (cobra `args.go:30-32` returns `nil` for any command without subcommands), and surfaced as `unknown command "<word>" for "<leaf>"` whenever an AI agent passed trailing positional words after a leaf — e.g. `dws aisearch person search --keyword "张"` or `dws aisearch person user search --keyword "张"`. Switching the `totalMax == 0` branch (and the initial value) from `cobra.NoArgs` to `cobra.ArbitraryArgs` restores cobra's natural leaf behavior: trailing positional args are silently ignored. Existing positional-binding paths (`MinimumNArgs` / `RangeArgs` / `MaximumNArgs`) are unchanged. Verified against `dws-wukong/auto-test/cli_to_mcp/testcases` — aiapp (9/9) + live (3/3) + aisearch (38/38) = **50/50** pass, vs 48/50 before this patch.

### Security

- **App credential files are partitioned by edition to prevent cross-edition credential leakage** (#300, no public issue; found during internal review) — different `dws` editions sharing the same config directory previously read and wrote the same `app.json`. A sibling edition that pinned its OAuth client ID could persist that ID through the shared post-login path, and the open-source build could later adopt it from the same file. Open-source/empty edition keeps the legacy `app.json` path for compatibility; sibling editions now use `app-<edition>.json`, matching the existing cache partitioning strategy. This prevents new cross-edition app credential writes and reads from colliding. After a sibling edition saves its new partitioned file, it also best-effort removes a legacy `~/.dws/app.json` only when that file's `clientId` matches the sibling edition being saved; a different, unparsable, or otherwise unowned `app.json` is left untouched to avoid deleting open-source credentials. If you previously ran multiple editions in one shared `~/.dws`, remove any confirmed-stale orphan manually with `rm ~/.dws/app.json` after verifying it is not the open-source credential file you still need.

## [1.0.28] - 2026-05-14

A single symmetric follow-up to 1.0.26's #250: `dws chat message send --group <cid>` now refuses an empty `--title` at the CLI layer instead of letting the call fall through to the API and surface a misleading `发群服务窗会话消息失败` error. No other behaviour changes.

### Fixed

- **`dws chat message send` rejects missing `--title` on group messages** (#294, completes #250) — `send_message_as_user`'s schema marks `title` as required (just like `send_direct_message_as_user`), but `buildChatMessageSendInvocation` only had the pre-validation on the direct-message branches. Group sends without a title were falling through to the API and returning the same misleading `发群服务窗会话消息失败` that #250 already fixed for direct messages. The check now covers both branches: missing `--title` on `--group` returns `--title is required for group messages (--group)` with exit code 2; missing on `--user` / `--open-dingtalk-id` keeps the original `--title is required for direct messages (--user / --open-dingtalk-id)`. The `Long` help, `--title` flag description, the first `Example`, and `skills/references/products/chat.md` (including the drive→chat workflow example) are realigned to "title is required for both direct and group messages" — the docs previously contradicted themselves (the prose said 群聊可选 while the flag listing said 必填). `internal/helpers/chat_test.go` adds a `group-without-title` rejection case; the existing `group` / `positional-text` success cases now pass `--title` to stay aligned with the new validation. No API request shape change — the server has always required `title`; the CLI now matches.

## [1.0.27] - 2026-05-14

Two user-visible fixes plus the schema primitive they're built on. `dws doc update` now reads Markdown from a file or stdin, so long / multi-line / table-heavy content no longer gets mangled by shell escaping; `dws sheet find --query` stops returning `unknown flag` on the open-source build, restoring copy-paste from internal wukong docs. Underneath, schema/discovery envelopes get a generic `file_read` transform and a `CLIFlagOverride.MapsTo` field that lets two sibling CLI flags route into the same MCP parameter slot. Also suppresses a noisy WARN on normal stdio-plugin shutdown.

### Added

- **`file_read` transform + `CLIFlagOverride.MapsTo` field** (#291, closes #277 #278 #282 #288) — discovery envelopes can now declare a path-typed CLI flag that performs the "file path → file contents string" conversion client-side before the value reaches the upstream MCP parameter.
  - `transform: "file_read"` (`internal/compat/transform.go`) — reads the file at the flag's value with UTF-8 validation; `-` means stdin. Any IO / encoding failure is surfaced as a validation error (exit 2), distinct from the generic transient-failure path (exit 1).
  - `CLIFlagOverride.MapsTo` (`internal/market/registry.go`) — redirects the flag's final value (post-transform or literal) into a named MCP parameter slot instead of the default `params[propertyName]`. This lets a single MCP parameter (e.g. `markdown`) be fed by two sibling CLI flags — a literal `--content` and a file-reading `--content-file` — paired with the existing tool-level `MutuallyExclusive` / `RequireOneOf` to express "exclusive, at least one".
  - Wired into the `internal/compat/dynamic_commands.go` normalizer via a separate `mapsToRoutes` collection + routing pass; empty `MapsTo` preserves the legacy `params[propertyName] = value` semantics, so every pre-existing dynamic_commands test passes unchanged. Pre-prod end-to-end verified across 6 cases (see PR #291's Validation table).
- **`dws doc update --content-file <path>` (envelope rollout)** — fixes "long Markdown can't reach the doc". The old command only accepted `--content "..."`, so long / multi-line / table-heavy Markdown got mangled by shell escaping and AI agents writing >2KB of content were stuck. The envelope now maps both `--content` (literal) and `--content-file` (`file_read` transform) to the `markdown` parameter, makes them mutually exclusive via cobra's `MarkFlagsMutuallyExclusive`, and requires at least one via `RequireOneOf`. `--content-file -` reads from stdin, so `cat long.md | dws doc update --content-file -` works directly. **Existing users must run `dws cache refresh` once** to pick up the new envelope.
- **`dws sheet find --query` hidden alias (envelope rollout)** — fixes "unknown flag when copy-pasting commands across editions". Users copying `dws sheet find --query "..."` from internal wukong docs onto open-source `dws` got `unknown flag: --query`, because the open-source primary flag is named `--find`. The envelope now registers `--query` as a hidden alias of `--find` via `CLIFlagOverride.Aliases` (the field shipped in 1.0.26) — it doesn't show up in `--help`, but accepts values and writes to the same MCP parameter. `--find` behaviour is unchanged. Also requires `dws cache refresh` once.

### Fixed

- **Noisy `failed to stop stdio client: exit status 1` WARN on normal stdio-plugin shutdown** (#285) — when `Stop()` explicitly `Kill`s the subprocess, the non-zero exit code returned by `cmd.Wait()` is expected behaviour, but it was being propagated as an error and logged to stderr on every CLI exit, polluting agent log parsing. `Stop()` now returns `nil` after Kill + Wait; the error path is reserved for "process exited on its own with non-zero" (e.g. stdin close without an explicit Kill). `internal/transport/stdio.go` + `stdio_integration_test.go` assert "Stop() returns nil after kill".

## [1.0.26] - 2026-05-12

Platform-stability round: Windows PAT-auth browser opener no longer truncates URLs at `&userCode=`, macOS sandbox hosts get an opt-in keychain fallback, and `dws doc download` rejects `axls` nodes before requesting `drive:download` consent. Two new global output formats `-f ndjson` and `-f csv` (matching `larksuite/cli`) land as first-class citizens with real-traffic-verified list detection. The `dws doc comment *` regression tracked in #240 is also resolved — fix is in the market metadata, users just need `dws cache refresh` once.

### Added

- **`-f ndjson` and `-f csv` global output formats** (#259, closes #252) — `ndjson` emits one compact JSON record per line (works straight with `jq -c` / `while read` / log pipelines); `csv` goes through `encoding/csv` (RFC-4180 — quoting, embedded newlines, CJK all handled by stdlib) and reuses the existing `-f table` column resolver (`normalizePayload` / `unwrapPrimaryObject` / `extractRowsFromMap` / `rowsFromSlice` / `formatValue`) so table and csv stay visually aligned. After a 7-product real-traffic sweep (contact / chat / doc / mail / todo / minutes / schema), the `preferredListKeys` whitelist was extended to cover the actual DingTalk envelope shapes — `contact user search` (`result`), `chat search` (`result.value`), `doc search` (`documents`), `mail mailbox list` (`emailAccounts`), `todo task list` (`result.todoCards`) — so these commands now degrade into a proper row stream instead of collapsing to a single-line `key,value` blob. Lives in `internal/output/ndjson.go` + `internal/output/csv.go`; `--format` help in `internal/app/flags.go` now lists `ndjson|csv` alongside `json|table|raw|pretty`.

### Changed

- **Sticky flag splitting is now schema-aware** (#272) — PreParse `StickyHandler` 此前会把任何前缀命中已知 flag 的 `--flagsuffix` 一律切成 `--flag suffix`，于是 `--starttime20260507` 这类拼错被静默改写成 `--start time20260507`，把假值传到下游。新行为按 flag 的 pflag 类型 / JSON Schema `format` / `enum` 校验 suffix 是否像合法 value（共享逻辑见 `pkg/cmdutil/sticky_suffix.go`），不像就保留原 token 让 cobra 报 `unknown flag`。slice/array/object 类型的 flag 永不切分。首 rune 读取使用 `utf8.DecodeRuneInString`，对中文等多字节 value 安全。

### Added

- **`available_flags` field on unknown-flag errors** (#272) — `dws -f json` 的 unknown-flag 错误体里新增 `available_flags`（已排序、过滤掉 hidden 与内部 `json` / `params`），方便 agent 不解析 `--help` 就能恢复。Human-readable 输出会附 `Flags: ...` 行，截断在 200 字节内。

### Fixed

- **`dws chat message send` 单聊缺 `--title` 时前置校验** (#250) — 单聊（`--user` / `--open-dingtalk-id`）的底层工具 `send_direct_message_as_user` 在 API 层强制要求 title，缺失时返回误导性的 `发群服务窗会话消息失败`。CLI 现在在 `buildChatMessageSendInvocation` 里前置校验，直接返回 `--title is required for direct messages (--user / --open-dingtalk-id)`；同时把 `Long` help、`--title` flag 描述、Example 和 `skills/references/products/chat.md` 全部对齐为「单聊必填，群聊可选」。群聊行为不变。
- **PAT auth URLs were truncated on Windows browser open** (#242, fixes #230) — `cmd /c start <url>` on Windows interprets `&` as a command separator, so PAT URLs containing `&userCode=...` were silently chopped before the userCode segment, and the browser landed on a 0-permission DingTalk page. The retry opener now uses `rundll32 url.dll,FileProtocolHandler`, which passes the URL through verbatim. The PAT response also exposes a copy-safe `data.authorizationUrl` (in addition to the service-provided `data.uri`, which is preserved as-is), and human-readable PAT output prints `PAT_AUTHORIZATION_URL=<full-url>` on its own line so OpenClaw-style host wrappers that swallow or reformat stderr can still capture the full link. Legacy DingTalk hash-route shapes (`https://open-dev.dingtalk.com/fe/old#%2FpersonalAuthorization%3FflowId=...%26userCode=...`) are normalised back into the working `/fe/old?hash=...#/personalAuthorization?...&userCode=...` form. Regression tests cover the issue-shaped URLs (encoded hash, fragment, `&userCode`) plus the OpenClaw malformed-hash variant.
- **`dws doc download` triggered `drive:download` PAT consent for unsupported axls nodes** (#268, fixes #190) — added a `get_document_info` preflight before `download_file`, so online-sheet (`axls`) nodes are rejected locally with guidance to use sheet range tools instead. The preflight reads `extension` from deterministic response paths (no recursive payload scan) and routes its own PAT errors back through `handlePatAuthCheck`, preserving device-flow / host-owned PAT behaviour. Costs one extra MCP roundtrip per `doc download` — deliberate, so the unsupported path fails before consent. Lives in `internal/app/doc_download_preflight.go`; coverage in `internal/app/runner_test.go`.
- **macOS sandbox hosts (Codex App etc.) couldn't read/write tokens via Keychain** (#267, fixes #214) — sandboxed macOS environments intercept `security` / Keychain APIs, so every token operation failed. New opt-in `DWS_DISABLE_KEYCHAIN=1` switches macOS to the same file-DEK path Linux uses (DEK at `~/Library/Application Support/dws-cli/dek`, mode `0600`), bypassing the system Keychain. Default behaviour is unchanged — fallback is strictly opt-in because file-DEK is a weaker trust model than Keychain-managed storage (DEK file sits next to ciphertext in the same directory). The Darwin / Linux file-DEK implementation is now shared in `internal/keychain/file_dek.go` (Linux path deduplicated by ~40 lines). Documented in `docs/reference.md` (中英) with the security tradeoff spelt out so users make the choice explicitly.
- **`dws doc comment {list,create,create-inline,reply}` returned `PARAM_ERROR - 未找到指定工具`** (fixes #240, also #234) — the four comment tools used to live on an independent `doc-comment` MCP server. After the Portal merged comment functionality into the `doc` server descriptor, the runtime `tools/list` on the merged `doc` server didn't include them, so every `dws doc comment *` call returned the "tool not found" PARAM_ERROR. The market metadata for the `doc` server now declares `serverOverride: "doc-comment"` on all four comment `toolOverrides`, so the existing CLI routing path sends `dws doc comment *` to the still-running `doc-comment` MCP server (which has the tools). No CLI code change was required, but **existing users must run `dws cache refresh` once** to pick up the updated descriptor — without that, the stale local market cache keeps pointing the call at the merged `doc` server and the error persists. Verified post-refresh: dry-run resolves to `https://mcp-gw.dingtalk.com/server/doc-comment` with tool `list_comments`, real calls return normal business responses (e.g. legitimate cross-org authz errors) instead of `未找到指定工具`.

## [1.0.25] - 2026-05-11

Two generic envelope-schema enhancements that close gaps the `cli_to_mcp` test suite kept surfacing — both product-agnostic, no hardcoded helper commands. Plus missing skill references for the already-registered `sheet` and `wiki` products are now shipped.

### Added

- **`sheet` (在线电子表格) skill reference + product-overview entry** — the `sheet` product registers **34 envelope tools** covering worksheet CRUD (`create` / `new` / `list` / `info` / `copy_sheet` / `update_sheet`), range read/write (`range read` / `range update` / `append`), dimension ops (`add-dimension` / `insert-dimension` / `delete-dimension` / `move-dimension` / `update-dimension`), merge (`merge-cells` / `unmerge-cells`), find/replace (`find` / `replace`), filter views (`filter-view {create, list, update, delete, update-criteria, delete-criteria}`), sheet-level filters (`create_filter` / `get_filter` / `update_filter` / `delete_filter` / `set_filter_criteria` / `clear_filter_criteria` / `sort_filter`), image write (`write-image`), and async export (`submit_export_job` + `query_export_job`). These were live in the envelope but `skills/references/products/sheet.md` had not shipped and `skills/SKILL.md` 产品总览 didn't list `sheet`, so agents had no reference to consult and were skipping it during intent routing. This release adds the doc, registers `sheet` in 产品总览 + 意图判断决策树, extends `description` to include 在线电子表格, adds a Sheet row to `README.md` / `README_zh.md` "Key Services", and notes the v1.0.25 reality on naming (about a third of `sheet` tools still expose snake_case cli_names pending `CLIAliases` (#246) rollout) and on export (no consolidated `dws sheet export` exists in v1.0.25 — `submit_export_job` + `query_export_job` are the atomic primitives; Pipeline (#247) provides the future plumbing).
- **`wiki` (知识库) skill reference + product-overview entry** — the wiki product's 7 envelope tools (`wiki.create_wikiSpace`, `wiki.get_wikiSpace`, `wiki.list_wikiSpaces`, `wiki.search_wikiSpaces`, `wiki.add_member`, `wiki.list_member`, `wiki.update_member`, surfaced as `dws wiki space create / get / list / search` and `dws wiki member add / list / update`) have been registered for a while, but no `skills/references/products/wiki.md` shipped with them, so agents had no per-command reference to consult. This release adds the reference doc, registers `wiki` in `skills/SKILL.md`'s 产品总览 table and 意图判断决策树, mentions 知识库 in the skill `description` frontmatter, adds a Wiki row to `README.md` / `README_zh.md` "Key Services", and removes `wiki` from the "Coming soon" callout (which was now stale).
- **`CLIToolOverride.CLIAliases` envelope field** (#246) — lets a single MCP tool register additional cobra command aliases via envelope JSON (e.g. `range read` also accepts `range get`, `member list` accepts `member ls`). Plumbed through the existing `Route.Aliases → cobra.Command.Aliases` path; sibling conflicts are silently dropped by cobra. Lives in `internal/market/registry.go` + `internal/compat/dynamic_commands.go`.
- **`json_parse_strict` transform** (#246) — strict-JSON variant of `json_parse` that does **not** fall back to YAML. Use when the upstream tool requires a structured array/object and silently coercing a malformed input to a scalar string would mask a real user error (observed: `filter-view --criteria 'NOT_VALID_JSON'` was being accepted and quietly creating an empty-criteria view). In `internal/compat/transform.go`.
- **`CLIToolOverride.Pipeline` + pipeline executor** (#247) — a single CLI command can now orchestrate an ordered sequence of MCP tool calls plus optional HTTP-download sinks, declared entirely in envelope JSON. Motivating use case: the "submit-job → poll-status → download-result" pattern (e.g. sheet export) that previously required per-product hardcoded helpers.
  - `PipelineStep` supports `type:"call"` (with optional `PollUntilField` / `PollUntilValue` / `PollIntervalSec` / `PollTimeoutSec` for polling loops) and `type:"download"` (resolves `DownloadURLField`, HTTP GETs the body, writes to the path from `OutputFlag`, infers filename for directory paths).
  - Template language: `$flag.<name>` resolves a user CLI flag by alias; `$step.<idx>.<dotPath>` walks a prior step's response (works through wrapped MCP envelopes); literals pass through.
  - `CLIFlagOverride.PipelineLocal` marks a flag as CLI-side only so `CollectBindings` skips it (value never reaches MCP params); the pipeline executor still reads it via `extractFlagValuesByAlias`.
  - Download step emits machine-parseable plain-text lines (`jobId: <id>\n`, `downloadUrl: <url>\n`) alongside the standard JSON envelope, so shell pipelines and regex-based tests can extract key values without JSON parsing.

## [1.0.24] - 2026-05-09

Three small but user-visible safety/usability changes: the embedded distribution now refuses to self-upgrade, the `dws auth login` help text finally matches the actual default flow (loopback, not device), and the release workflow gains a manual fallback trigger.

### Changed

- **`dws upgrade` is blocked in embedded distributions** (#248) — when the CLI is shipped as an embedded asset (e.g. inside another product), `dws upgrade` would happily overwrite the host-managed binary. The upgrade entry point now detects the embedded build flag and exits early with a clear message; covered by `internal/app/upgrade_embedded_guard_test.go`.

### Docs

- **`dws auth login` help text reflects the real default** (#238, fixes #226) — the long help previously claimed "OAuth 设备流 (默认)", but the actual default starts a 127.0.0.1 loopback listener and only switches to device flow when `--device` is passed. SSH-into-headless-Linux users following the old text hit a dead end (remote-side 127.0.0.1 is unreachable from the local browser). Help and two `flagErrorWithSuggestions` messages in `root.go` are realigned: each method is named after its real flag (`OAuth Loopback 流 (默认)` / `OAuth 设备流 (--device)` / `直接提供 Token (--token)`), with an explicit `--device` example for SSH/headless. No behaviour change.

### CI

- **`workflow_dispatch` trigger added to release workflow as a fallback** (#261) — GitHub occasionally drops tag-push events; the release job can now be re-run manually against any tag ref without having to delete and re-push the tag.

## [1.0.23] - 2026-05-08

A single fix for HTTP proxy support across the CLI's custom HTTP transports. No behaviour changes elsewhere.

### Fixed

- **`HTTP_PROXY` / `HTTPS_PROXY` environment variables silently ignored by all custom transports** (#237, fixes #236) — the three custom `http.Transport` instances built by the CLI (`internal/transport/client.go` MCP transport, `internal/apiclient/client.go` DingTalk OpenAPI client, `internal/app/legacy.go` IPv4-forcing registry client) all set `DialContext` / `TLSClientConfig` / timeouts but omitted the `Proxy` field. Per Go's `net/http` contract, a non-nil Transport without an explicit `Proxy` means "no proxy" — env vars are silently ignored, breaking sandboxed or air-gapped deployments that route outbound through `HTTP_PROXY` / `HTTPS_PROXY`. All three transports now set `Proxy: http.ProxyFromEnvironment`.

### Tests

- Per-package regression test that pointer-compares the Transport's `Proxy` func against `http.ProxyFromEnvironment`, avoiding flakiness from Go's `envProxyOnce` memoisation when running alongside tests that read proxy env early. (#237)

## [1.0.22] - 2026-05-07

Two release-blocking bug fixes: `dws attendance summary` now exposes the server-required `--stats-type` flag (without it, every call returned C0002), and the install scripts finally populate `~/.hermes/skills/dws/` for users who already have Hermes.

### Fixed

- **`dws attendance summary` returned C0002 (统计类型错误) on every call** (#228, fixes #227) — the DingTalk MCP tool `get_attendance_summary` requires `statsType` at the business layer even though the schema marks it optional. The CLI did not expose any way to set it, so the command was 100% unusable. A new `--stats-type` flag (`week` / `month`) is now plumbed through to `QueryUserAttendVO.statsType`; the flag is documented as required in the long help, flag description, and `skills/references/products/attendance.md`.
- **Install scripts skipped `.hermes/skills/` when populating skill directories** (#221, fixes #188) — the `AGENT_DIRS` lists across `build/npm/install.js`, `scripts/install.sh`, `scripts/install.ps1`, `scripts/install-skills.sh` and the four upgrade-path mirrors (8 sources total once review feedback was addressed) did not include `.hermes/skills`, so users with Hermes installed were not getting `~/.hermes/skills/dws/` populated automatically. The existing parent-directory gate keeps this zero-side-effect for users without Hermes.

### Tests

- New `--stats-type` regression coverage in `test/cli_compat/attendance_test.go` — verifies `statsType` is written to `QueryUserAttendVO` when set to `month` or `week`, and is omitted when not provided. (#228)

## [1.0.21] - 2026-05-05

A single critical routing fix for `dws drive` commands. No new commands or behaviour changes elsewhere.

### Fixed

- **`dws drive mkdir` / `dws drive download` silently routed to the doc MCP server** (#220, fixes #219) — when two MCP servers register tools with the same name (e.g. both `drive` and `doc` expose `create_folder`), the tool-level endpoint map used last-writer-wins, so drive-side calls landed on the doc endpoint and returned mock-shaped responses (`success: true` with a fake `folderId`) without actually creating anything. `directRuntimeEndpoint` now resolves product-level first when the caller already knows the productID, and only falls back to the tool-level lookup when productID is empty. The wrong-server collision and the resulting "succeeded but didn't" behaviour are gone.

## [1.0.20] - 2026-05-04

Documentation polish and a login regression fix. No behaviour changes outside the login MCP refresh path.

### Fixed

- **Login no longer reuses stale `clientId` from an old MCP cache** (#213) — `dws login` now unconditionally re-fetches the MCP descriptor, so a previously cached client id can't keep producing auth errors after the server rotates it.

### Docs

- **`dws chat message list` pagination** (#218, fixes #195) — clarifies that `nextCursor` is opaque and must be passed back as `--cursor` exactly; warns against parsing or reusing it as an offset.
- **`dws contact search` examples** (#209) — switched from the removed `--keyword` flag to the current `--query`.
- **`dws todo` help text** (#205) — expanded field semantics so MCP wrappers generate accurate schemas.
- **`dws chat message send-by-bot` and `dws report create` help** (#217, #106, #107) — `--robot-code` / `--title` / `--text` now carry the `(必填)` marker; `report create --contents` documents the `key=field_name` requirement and rewrites examples as a `template detail → create` two-step pipeline.
- **CHANGELOG backfill for 1.0.19** (#204).

## [1.0.19] - 2026-04-30

Discovery hardening for edition overlays: `edition.SupplementServers` / `FallbackServers` hooks now consistently surface through the **runtime catalog loader**, not just the static command tree, so overlay products that live outside the Portal envelope (e.g. Wukong gray-release `conference`) resolve an endpoint on both the cold-cache and tool-not-in-catalog paths. Ships with per-edition cache partitioning to stop cross-edition disk-cache leakage, plus a small todo fix.

### Added

- **`pkg/config.EditionPartition(name)`** (#197) — returns the cache partition key for a given edition. Open-source core (`""` / `"open"`) keeps using `DefaultPartition` (`default/default`); every other edition gets its own namespace (`<edition>/default`), preventing cross-edition data leakage in the shared `~/.dws` disk cache. Lives in `pkg/config` as a leaf helper so `internal/cli`, `internal/app`, and `internal/cache` can all call it without risking import cycles.
- **`internal/editionmerge` shared package** (#197) — single source of truth for converting `edition.ServerInfo` into `market.ServerDescriptor` (`ToDescriptor`) and for merging `SupplementServers` / `FallbackServers` into a descriptor list. Both `internal/cli` (command tree) and `internal/app` (runtime catalog) now apply the edition hooks against the same discovery pipeline.

### Changed

- **`EnvironmentLoader.loadFromCache` honors `SupplementServers` even on empty registry** (#197) — when the Portal registry cache is missing or empty, the catalog loader still materialises the edition's `SupplementServers` as endpoint-only `discovery.RuntimeServer` entries (source: `edition_supplement`), so hardcoded overlay commands for supplement-only products can still resolve an endpoint via the catalog path. Previously `loadFromCache` short-circuited to an empty catalog whenever the registry snapshot was empty, silently dropping gray-release products.
- **Cache loader switches from `DefaultPartition` to `EditionPartition(edition.Get().Name)`** (#197) — the runtime catalog, registry snapshot, and tools snapshot are now partitioned per edition instead of all editions sharing `default/default`.
- **`loadFromCache` appends supplement servers alongside fresh-cache servers** (#197) — supplement entries whose `CLI.ID` / `Key` are already present in the cached registry are skipped, so the hook never shadows Portal-published servers; only new products are added.
- **`runtimeRunner.Run` falls through to `directRuntimeEndpoint` for supplement products** (#197) — when the catalog contains the product (e.g. supplied by `SupplementServers`) but the specific tool is not declared, the runner now trusts `directRuntimeEndpoint` to resolve a working endpoint for the tool before returning the explicit catalog-miss error. Supplement entries intentionally carry no tool list, so this is the path that makes overlay-only tools executable.
- **Legacy `mergeSupplementServers` / `fallbackToDescriptors` moved out of `internal/app/legacy.go`** (#197) — relocated into `internal/editionmerge` and reused by the catalog loader, eliminating the duplicate `edition.ServerInfo → market.ServerDescriptor` logic that previously only ran on the static command-tree path.

### Fixed

- **`dws todo task get` returns empty** (#202) — the helper was calling `query_todo_detail`, which is not a valid MCP tool and returns empty. Switched to `get_todo_detail` as declared in `discovery.json`, restoring correct task-detail behaviour.
- **Conference and other Wukong gray-release products miss endpoint on cold cache** (#197) — products registered only via `edition.SupplementServers` (not yet in the Portal envelope) now resolve an endpoint through the catalog path in both cold-start and tool-not-declared scenarios.

### Tests

- `internal/editionmerge/merge_test.go` — descriptor conversion + supplement/fallback merge semantics.
- `internal/cli/loader_partition_test.go` + `loader_supplement_test.go` — edition-partitioned cache reads and supplement hook surfacing from `loadFromCache` (including empty-registry cold path and existing-ID deduplication).
- `internal/app/legacy_wukong_partition_e2e_test.go` — end-to-end cache partition isolation for the Wukong edition.
- `internal/app/runner_supplement_fallback_test.go` — runner falls through to `directRuntimeEndpoint` when the tool isn't declared by a supplement-sourced catalog entry.
- `pkg/config/constants_test.go` — `EditionPartition` name handling (`""`, `"open"`, custom edition).

### Docs

- **CHANGELOG v1.0.18 rewrite** (#193) — previous release notes expanded to call out the PAT host-owned A-core flow, exit-code contract change (auth `4`, Discovery/cache/protocol `6`), `dws pat chmod` / `pat browser-policy` entry points, stderr-JSON classifier updates, and host-control metadata injection.

## [1.0.18] - 2026-04-28

Raw DingTalk OpenAPI access lands as a new `dws api` surface for both `api.dingtalk.com` and `oapi.dingtalk.com`, backed by app-level token caching and guarded host allowlists. PAT enters the host-owned **A-core** loop: agent hosts can own authorization UI through `DINGTALK_DWS_AGENTCODE`, parse single-line stderr JSON, call `dws pat chmod`, and replay the original command. Chat helper regressions are fixed, skill references are brought back in line with shipped commands, and the v1.0.17 Mail release notes are backfilled into README / CHANGELOG.

### Breaking

- **PAT exit-code contract** (#142) — PAT authorization interceptions now use exit code `4`; Discovery, cache, and protocol negotiation failures now use exit code `6`. Downstream scripts that previously treated `4` as Discovery must update their handling.

### Added

- **`dws api` raw DingTalk OpenAPI command** (#184) — direct DingTalk OpenAPI calls without writing an MCP wrapper first. Supports `GET` / `POST` / `PUT` / `PATCH` / `DELETE`, JSON `--params` / `--data`, stdin input, dry-run previews, `--jq`, field selection, `--page-all`, `--page-limit`, `--page-delay`, and `--base-url`.
- **Dual-form OpenAPI routing** (#184) — `api.dingtalk.com` requests use the `x-acs-dingtalk-access-token` header; `oapi.dingtalk.com` requests use the legacy `access_token` query parameter. The raw API client validates the target host before attaching credentials.
- **App-level token cache for raw API** (#184) — custom-app credentials now fetch app access tokens from the unified OAuth endpoint, cache them while valid, and refresh them before expiry. The same token provider works for new-style and legacy OpenAPI calls.
- **Host-owned PAT A-core flow** (#142) — when `DINGTALK_DWS_AGENTCODE` is set, PAT hits return `exit=4` plus single-line stderr JSON; the host renders authorization UI, calls `dws pat chmod <scope>...`, and replays the original command.
- **`dws pat chmod` authorization entry point** (#142) — grants scopes with `--agentCode`, `--grant-type`, and session fallback support; `DINGTALK_DWS_AGENTCODE` can supply the agent code when the flag is omitted.
- **PAT browser-open policy** (#142) — `dws pat browser-policy --enabled <true|false> [--agentCode <id>]` controls whether the CLI may open a browser, independently from `--format` output mode.

### Changed

- **README raw API guide** (#184) — English and Chinese READMEs now document custom-app prerequisites, api/oapi examples, auto-pagination, dry-run, jq filtering, security properties, and the new Raw API service-table row.
- **Raw API token retrieval path** (#184) — token lookup now goes through a single app-token interface; stale auth-refresh retry helpers were removed from the raw API path.
- **PAT stderr JSON classifier** (#142) — recognizes `code`, `errorCode`, and `error_code`, including `PAT_NO_PERMISSION`, risk-tier PAT errors, `PAT_SCOPE_AUTH_REQUIRED`, and `AGENT_CODE_NOT_EXISTS`.
- **Host-control metadata injection** (#142) — classifier and active-retry paths now share one mutation point for `data.hostControl` and `data.openBrowser`, keeping host-facing JSON shapes aligned.
- **Open-edition routing signals** (#142) — open edition pins `claw-type: openClaw`; `DINGTALK_AGENT`, `DWS_CHANNEL`, and host-owned PAT detection are kept as independent signals.
- **Behavior authorization endpoint fallback** (#142) — the PAT runtime can resolve the built-in behavior-authorization MCP endpoint before discovery data is available.
- **v1.0.17 documentation backfill** (#181) — the previous release notes and README service table now explicitly include the shipped Mail product, update the total to **163 commands across 14 products**, and remove Mail from "Coming soon".

### Fixed

- **CLI auth-denial attribution** — local CLI authorization denials are attributed to the channel before falling back to user-scope classification, avoiding user-scope misclassification for channel-level auth failures.
- **Opaque authorization URLs** (#182, #142) — PAT authorization links are preserved verbatim, including query/hash/fragment content required by the server.
- **Polling compatibility** (#182, #142) — device-flow result envelopes and no-`flowId` device-code fallback remain supported, with guarded debug output and envelope priority.
- **Group chat @-mentions restored** (#180) — `dws chat message send --group ...` again accepts and forwards `--at-users`, `--at-all`, and `--at-mobiles`; those flags are rejected outside group-chat mode so single-chat sends cannot silently drop @-mention intent.
- **Explicit members-list command restored** (#180) — `dws chat group members list --id <openConversationId>` is reachable after the helper/dynamic merge path changed. `cmdutil.MergeHardcodedLeaves` now honors higher-priority helper groups when a dynamic envelope contributes a leaf at the same path.
- **Skill reference command names** (#186) — `simple.md` now uses shipped OA command names (`list-pending`, `list-initiated`), removes a non-existent devdoc `search-error` command, and marks `workbench.md` as Draft because workbench commands are not available in the runtime.
- **Empty grant result handling** (#142) — `dws pat chmod` now returns an explicit error instead of treating `{"Content": null}` as success.
- **Session-id log safety** (#142) — raw `DWS_SESSION_ID` / `REWIND_SESSION_ID` values are no longer logged when the two env vars disagree.

### Tests

- Added raw API coverage for request validation, api/oapi routing, token management, pagination, response handling, dry-run output, JSON parsing, stdin handling, and command wiring. (#184)
- Added chat/cmdutil regression tests for group @-mention forwarding, single-chat rejection, `members list`, helper-vs-envelope shape mismatch, and merge-priority behavior. (#180)
- Added PAT contract coverage for host-owned signal selection, single-line stderr JSON, chmod env fallback and legacy alias fallback, browser policy, direct-runtime PAT endpoint fallback, and retry/poll behavior. (#142)
- Coverage badge refreshed after the post-v1.0.17 CI runs.

## [1.0.17] - 2026-04-27

New **Mail** product surface (mailbox list, KQL message search, message get, send) brings runtime command count to **163 across 14 products**. Plugin command-tree visibility hardening: stdio plugins shipping CLI overlays no longer wait on subprocess discovery to surface their commands, and overlay-registered plugin products are no longer hidden by edition `VisibleProducts` whitelists. Chat docs clarify that `--title` is required on `dws chat message send`.

### Added

- **`mail` product** (#167) — new top-level service for DingTalk Mail. Four leaf commands across two subgroups:
  - `dws mail mailbox list` — list mailbox addresses available to the current user (`list_user_mailboxes`)
  - `dws mail message search` — KQL search across folders / sender / date / attachments / read-state (`search_emails`); supports `--cursor` pagination
  - `dws mail message get` — fetch full message body + headers + attachments by message ID (`get_email_by_message_id`)
  - `dws mail message send` — send email to one or more recipients (`send_email`)
  - Skill reference at `skills/references/products/mail.md` registered in `skills/SKILL.md` master index and intent decision tree
- **Stdio plugin overlay-first command registration** (#179) — when a stdio plugin's `overlay.json` declares `toolOverrides`, command trees are built from manifest metadata synchronously at startup, no subprocess `Initialize` / `tools/list` handshake required. Previously, slow or failing subprocesses left plugin commands invisible in `dws --help`. Background discovery still runs to refresh the warm cache for richer flag types on subsequent startups.

### Changed

- **`hideNonDirectRuntimeCommands` / `visibleMCPRootCommands` / `visibleUtilityRootCommands`** (#179) — refactored to share a single `resolveVisibleProducts()` helper that **unions** the edition's `VisibleProducts` hook with `DirectRuntimeProductIDs()`, so plugins registered via `AppendDynamicServer` stay visible in `dws --help` even when an edition installs a static product whitelist. Previously the hook fully replaced the dynamic registry, silently hiding plugin commands.
- **`dws chat message send` documentation clarifies `--title` is required** (#174) — the helper command short text and the chat skill reference now state explicitly that `--title` is mandatory for both group and single-chat sends, matching the runtime validation.
- **`buildStdioCommands` refactored to share helpers with the overlay-first path** (#179) — overlay parsing (`resolveStdioOverlay`) and tools→DetailTool conversion (`toolsToDetails`) extracted as package-level helpers; the legacy discovery-first stdio path now delegates to them, eliminating duplicated overlay JSON / cache-snapshot logic.

### Fixed

- **Negative-cache poisoning guard for stdio plugin discovery** (#179) — `refreshStdioToolsCache` now skips `SaveTools` entirely when discovery returns an empty tool list (transient failure, subprocess not ready, RPC timeout), so a single bad refresh cannot overwrite a previously-good cache and degrade flag enrichment on the next startup.

### Tests

- 6 new test cases in `internal/app/plugin_stdio_overlay_test.go` and `internal/app/visibility_test.go` cover overlay-first registration without discovery, warm-cache flag enrichment from `InputSchema`, fallback when overlays lack `toolOverrides`, the cache-poisoning guard, and integration cases for plugin visibility under restrictive `VisibleProducts` whitelists.
- Coverage 49.8% → 52.8%.

## [1.0.16] - 2026-04-24

Discovery service abstraction with schema v3 extensions, open-edition helper-subtree restoration, and a defensive device-flow login reset.

### Added

- **`internal/discovery` service abstraction** (#156) — encapsulates market registry fetch, MCP runtime negotiation (`initialize → tools/list → detail` merge), and multi-level cache fallback. `EnvironmentLoader` now does cache-first startup, with degraded-mode reasons (`unauthenticated` / `market_unreachable` / `runtime_all_failed`) and `UpdatedAt`-based selective re-discovery.
- **Schema v3 extensions** (#156) — positional parameters with typed coercion, `Example` on `--help`, flag `Default` / `RuntimeDefault` (with `$currentUserId` / `$now` etc.), `BodyWrapper`, `MutuallyExclusive` / `RequireOneOf` flag groups, `OmitWhen`, explicit `Type` override, and detail-schema `default` propagation.
- **`dws chat message send` destination-flag routing** (#170) — open edition gains a hardcoded helper that dispatches by `--group` (→ `send_message_as_user`) vs `--user` / `--open-dingtalk-id` (→ `send_direct_message_as_user`), mirroring the closed-source overlay so single-chat sends finally work end-to-end.

### Changed

- **`pickCommands` → `cmdutil.MergeHardcodedLeaves`** (#169) — when a top-level product name collides between the dynamic overlay and a helper subtree, helper-only siblings are grafted into the dynamic tree instead of dropped. Restores `dws chat message send-by-bot` / `recall-by-bot` / `send-by-webhook` and `dws chat group members add-bot`, which had silently vanished from the open edition.
- **`OverridePriority` / `MergeHardcodedLeaves` promoted into `pkg/cmdutil`** (#170) — single source of truth for the merge layer; hardcoded leaves can opt into overriding the dynamic envelope via a strictly higher priority.

### Fixed

- **Device flow defensively resets credentials before login** (#157) — `--device` login now clears stale credential state and re-fetches `clientID` from the MCP server, regardless of what previous login methods (OAuth scan, PAT) left in `app.json`. Fixes the case where a prior OAuth login made `--device` fall back to direct mode and demand `clientSecret`.

## [1.0.15] - 2026-04-23

Compat layer gains **subcommand merging** under shared parents so multiple server entries can contribute into the same `dws <parent> <branch>` subtree without producing duplicate `--help` rows. Ships with a fresh auto-generated command index doc, a README sync to **159 commands across 13 products**, and a wide-ranging flag-naming cleanup that standardises CLI flags across chat, calendar, drive, minutes, contact, and devdoc commands.

### Added

- **`internal/compat` subcommand merging via `attachOrMerge`** — when two or more server entries attach to the same parent (e.g. `parent: "chat"`) and their `cli.command` collides with an existing subcommand in the parent's tree, the new subcommand's children are merged recursively into the existing one instead of creating a duplicate sibling. Leaf-name collisions resolve first-wins. Fixes the "double `group` / `message` rows in `dws chat --help`" symptom when bot capabilities are distributed across `chat.group.members` and `chat.message`.
- **`docs/command-index.md`** — a single, English, auto-generated listing of every runtime command the `dws` CLI exposes under the pre environment (159 total). Each entry carries a description and a "when to use" column aimed at AI agents. Replaces the earlier `command-index.pre.*` / `command-index.full.*` ad-hoc snapshots.

### Changed

- **README Key Services table** (`README.md` + `README_zh.md`) fully synced to the shipped command surface:
  - `Chat`: 20 → **23** (bot capabilities merged in; new `list-all` / `list-focused` / `list-unread-conversations` / `conversation-info` exposed)
  - `Calendar`: 13 → **14**
  - `AI Tables`: 37 → **41** (chart / dashboard public-share config rows)
  - `Doc`: 16 → **21** (comment subtree + `file create`)
  - `Minutes`: 22 → **19** (single-tool `record`, `list query`, `list-by-keyword-range` pruned)
  - New `Drive` row (6 commands) — promoted out of "Coming soon"
  - `Workbench` row and standalone `Bot` row removed
  - Total revised to **159 commands across 13 products**
- **Quick Start** expanded to 7 examples covering `doc`, `minutes`, `drive` in addition to `contact`, `calendar`, `todo`
- **Coming soon** trimmed to 5: `mail`, `conference`, `aiapp`, `live`, `wiki`
- **Reference & Docs** section now leads with a pointer to the new `docs/command-index.md`
- **Flag naming cleanup** — CLI flags across chat, calendar, drive, minutes, contact, and devdoc have been standardised so the names users type match the product-skill documentation. Notable flags:
  - `dws contact user search` / `dws contact dept search` / `dws devdoc article search` now take `--query` (previously `--keyword`)
  - `dws chat message list` / `dws chat message search` / `dws chat message list-mentions` / `dws chat conversation-info` / `dws chat message send` now take `--group` for the target conversation (previously `--id`) and `--open-dingtalk-id` (previously `--open-id`)
  - `dws chat message list-by-sender` now takes `--sender-user-id` / `--sender-open-dingtalk-id` (previously `--user` / `--open-id`)
  - `dws chat message list-topic-replies` now takes `--group` / `--topic-id` / `--limit` / `--time` (previously `--id` / `--topic` / `--size` / `--start`)
  - `dws chat search-common` now takes `--match-mode` (previously `--mode`)
  - `dws drive list` now takes `--max` / `--thumbnail` (previously `--max-results` / `--with-thumbnail`)
  - `dws calendar event suggest` now takes `--users` / `--duration` / `--timezone` (previously `--attendee-user-ids` / `--duration-minutes` / `--time-zone`)
  - `dws minutes list mine` / `dws minutes list shared` now take `--max` (previously `--max-results`) and gain `--query` / `--start` / `--end`
  - `dws minutes list all` no longer exposes the legacy `--__scope__` internal alias
- **Flag coverage additions** — `dws calendar event create` / `update` gain `--attendees`, `--open-dingtalk-ids`, `--timezone`; `dws chat message send` gains file-message flags (`--dentry-id`, `--file-name`, `--file-size`, `--file-type`, `--media-id`, `--msg-type`, `--space-id`) plus `--open-dingtalk-id` / `--user`; `dws chat message list` gains `--open-dingtalk-id` / `--user`; `dws aitable table delete` gains `--reason`; `dws calendar participant add` gains `--optional`; `dws todo task create` gains `--recurrence`.

### Tests

- 3 new unit tests in `internal/compat/dynamic_commands_test.go`:
  - `TestBuildDynamicCommands_ParentMergeSameName` — two servers with identical `command` + `parent` collapse into a single merged subcommand
  - `TestBuildDynamicCommands_ParentMergeRecursive` — recursive merge through nested groups (e.g. `chat.group.members`)
  - `TestBuildDynamicCommands_ParentMergeLeafCollision` — identical leaf paths resolve first-wins without producing duplicates

## [1.0.14] - 2026-04-22

Docs-only re-tag of v1.0.13. The single commit (#153) backfills the v1.0.13 release notes after the binary was already published; no functional or CLI surface change.

## [1.0.13] - 2026-04-22

IM / Messaging capability expansion: the `chat` (aka `im`) product surface grows from "group + bot messaging" into a full conversational layer — user-identity messaging, message reading & search, personal messages, topic replies, mentions, focused contacts, unread/top/common conversations, org-wide group creation, and first-class bot lifecycle.

### Added

- **`dws im` alias** — `dws im` is now registered as an alias of `dws chat` for intent clarity
- **User-identity messaging** (`chat message send`) — send group or 1-on-1 messages as the current user
  - Recipient selection is mutually exclusive: `--group <openConversationId>` / `--user <userId>` / `--open-dingtalk-id <openDingTalkId>`
  - Markdown text via `--text` (or positional arg), optional `--title`
  - Group-only: `--at-all` to @everyone, `--at-users` for per-member @mentions
  - Image messages via `--media-id` (obtained from `dt_media_upload`)
- **Personal messages** (`chat message send-personal`) — sensitive personal-channel send (⚠️ destructive/dangerous op, requires confirmation)
- **Conversation read paths**:
  - `chat message list` — pull group / 1-on-1 conversation messages
  - `chat message list-all` — pull all conversations for the current user in a time range
  - `chat message list-topic-replies` — pull group topic reply threads
  - `chat message list-by-sender` — messages by a specific sender
  - `chat message list-mentions` — messages where the current user was @-mentioned
  - `chat message list-focused` — messages from focused / starred contacts
  - `chat message list-unread-conversations` — unread conversation list
  - `chat message search` — keyword search across conversations
  - `chat message info` — conversation metadata
  - `chat list-top-conversations` — pinned conversation list
- **Group creation & discovery**:
  - `chat group create-org` — create an organization-wide group
  - `chat search-common` — search groups shared with a nickname list (`--nicks`, `--match-mode AND|OR`, cursor-based pagination)
- **Bot lifecycle**:
  - `chat bot create` — create an enterprise bot
  - `chat bot search-groups` — search the groups a bot is present in

### Changed

- **`chat` skill reference** (`skills/references/products/chat.md`, #148) restructured into three sub-groups — `group` (9) / `message` (15) / `bot` (3) — with refreshed intent-routing table, workflow examples, and context-passing rules aligned with `dws-service-endpoints.json` (16 new group-chat tool overrides + 2 new bot tool overrides)
- **README Key Services** sync:
  - `Chat` row: 10 → 20 commands; subcommand tags expanded to `message` `group` `search` `list-top-conversations`
  - `Bot` row: 6 → 7 commands; subcommand tags expanded with `create` `search-groups`
  - Total raised to **152 commands across 14 products**

## [1.0.12] - 2026-04-21

Product-surface expansion: first-class `doc` (DingTalk Docs) and `minutes` (AI Minutes) skill references, refreshed `aitable` guide aligned with the shipped binary (including dashboard / chart / export), and a README sync that brings the full command catalog to **141 commands across 14 products**.

### Added

- **`doc` skill reference** (`skills/references/products/doc.md`) — 16-command coverage of DingTalk Docs:
  - Discovery: `search`, `list`, `info`, `read`
  - Authoring: `create`, `update`, `folder create`
  - Files: `upload`, `download`
  - Block-level editing: block `query`, `insert`, `update`, `delete`
  - Comments: `comment list`, `create`, `reply`
  - URL → `doc_id` extraction rules and nodeId dual-format notes
- **`minutes` skill reference** (`skills/references/products/minutes.md`) — coverage of AI Minutes:
  - Lists: personal / shared-with-me / all-accessible
  - Content: basic info, AI summary, keywords, transcription, extracted todos, batch detail
  - Editing: title update
  - Recording control: start, pause, resume, stop
- **SKILL.md routing**:
  - Product overview table rows for `doc` and `minutes`
  - Intent decision tree routes — `钉钉文档/云文档/知识库/块级编辑/文档评论` → `doc`; `听记/AI听记/会议纪要/转写/摘要/思维导图/发言人/热词` → `minutes`
  - Danger-op table entries: `doc delete`, `doc block delete`
  - `aitable` description completed with the `附件` (attachment) group
- **`aitable` skill enhancements**:
  - `field create` single-field mode (`--name` / `--type` / `--config`) with examples
  - `base get` URL → `baseId` quick-tip
  - Dedicated "URL → baseId 提取" chapter
  - "`--filters` 筛选语法排错与使用规范" chapter
  - "相关产品" cross-link section pointing to `doc`
  - **"复杂操作" chapter** (#141) — dashboard / chart workflow (with two-call sequencing and `chart share get` vs `dashboard share get` error semantics) and two-stage `export data` polling (`scope=all/table/view` parameter constraints)
- **README Key Services sync** (#140):
  - New rows: `doc` (16 commands), `minutes` (22 commands — adds `hot-word`, `mind-graph`, `replace-text`, `speaker`, `upload` subgroups)
  - `aitable` expanded from 20 → 37 commands; surfaces `chart`, `dashboard`, `export`, `import`, `view` subgroups
  - Total command count updated from **86 → 141 across 14 products**
  - "Coming soon" list drops `doc` and `minutes`

### Changed

- `aitable record query` docs rename `--keyword` → `--query` to match the shipped binary
- `aitable record query` docs clarify `--sort` direction semantics (avoids misuse of `order`)
- `aitable base list` guidance strengthened — "only for recent browsing; use `base search` for lookups"; intent decision prioritizes `base search` for base discovery

## [1.0.11] - 2026-04-20

Plugin subsystem hardening: faster cold startup, cleaner lifecycle, stricter isolation, and polished UX for PAT / i18n / error routing.

### Added

- `feat: supports claw-like products` — overlay path for Claw-style embedded editions
- `feat(plugin): inject user identity (UserID, CorpID) into stdio plugin subprocesses`
- `feat(auth): improve login UX for terminal auth denial cases` — clearer messaging + retry affordance
- `feat: PAT scope error visualization and auto-retry with authorization polling` (#113)
  - Human-readable error output (lark-cli style) with type/message/hint/authorization command
  - JSON payload also available via `--format json`
  - Auto-retry once the user completes scope authorization

### Changed

- `perf(plugin): serve plugin MCP tool list from disk cache on startup` — hot path skips Initialize+ListTools when snapshot exists
- `perf(plugin): parallelize all plugin discovery and tighten cold timeouts` — HTTP cold budget 4s → 700ms (auth) / 500ms (plain); stdio and HTTP fan out concurrently
- `perf(plugin): share cache.Store across discovery` — single `*cache.Store` above the fan-out instead of per-goroutine instances
- `refactor(plugin): remove default/managed plugin privileged mechanism` (#124) — third-party plugins install on an equal footing via `dws plugin install`
- `refactor(plugin): purge removed plugin settings instead of merely disabling` — `RemovePlugin` now deletes `EnabledPlugins` and `PluginConfigs` entries

### Fixed

- `fix(transport): cap plugin MCP startup at ~4s when endpoints are unreachable` (#119) — eliminates the 10s `dws --help` stall caused by compounding transport timeouts
- `fix(plugin): stop stdio child processes on exit and before removal` — no more orphaned plugin subprocesses
- `fix(pat): avoid shared PAT command state in root registration` (#129)
- `fix: -f json 模式下错误 JSON 从 stdout 改为输出到 stderr` (#133) — restores CI stderr-based failure assertions
- `fix(cli): localize plugin/help command strings via i18n` (#118, #134) — zh locale now shows consistent Chinese `--help`; wraps plugin module, help command, and OAuth client-id/secret flag descriptions
- `chore: remove workspace and bundled artifacts` (#127) — clean local-only repository leftovers

## [1.0.9] - 2026-04-16

Plugin system launch + execution-pipeline overhaul. This is the largest release since 1.0.0: third-party MCP servers become first-class commands, the command pipeline grows to five stages, and the edition overlay gains the hooks needed for embedded hosts.

### Added

#### Plugin system (new)

- `plugin` command family: `install`, `list`, `info`, `enable`, `disable`, `remove`, `create`, `dev`, `config set/get/list/unset`
- Plugin manifest parsing/validation, managed/user directory-based identity
- MCP server conversion and injection into the dynamic routing registry
- Pipeline hook adapter for shell-based hooks
- Stdio transport: subprocess lifecycle, `DWS_PLUGIN_ROOT` / `DWS_PLUGIN_DATA` variable expansion
- Stdio server tools automatically registered as CLI subcommands (e.g. `dws hello greet --name Peter`)
- Streamable-HTTP MCP tool discovery via `registerHTTPServer`
- Updater: managed plugin update check on CLI startup (10 s timeout, best-effort)
- `dws plugin create` scaffold (plugin.json, SKILL.md, hooks.json); `dws plugin dev` source-dir registration without copy
- `SyncSkills` — copies plugin skills to agent directories on startup
- **Auth Token Registry**: per-server HTTP headers declared in `plugin.json` for third-party MCP servers (e.g. Alibaba Cloud Bailian) independent from DingTalk OAuth
- **Persistent plugin config** (`dws plugin config ...`): values persisted to `~/.dws/settings.json`, auto-injected as env vars; `${KEY}` in `plugin.json` resolves without manual `export`
- **Build lifecycle**: `build` field compiles stdio servers to native binaries at install time
- **Command-name conflict protection**: reserved built-in names (`auth`, `plugin`, `cache`, …) and plugin-vs-plugin duplicate detection
- Parallel service discovery (`sync.WaitGroup`) — startup reduced from sequential `N*10s` to parallel `max(10s)`

#### Core commands & diagnostics

- `dws doctor` — one-stop environment/auth/network diagnostics
- `dws config list` — centralized view of scattered configuration
- Structured perf tracing (upgraded from debug tool to diagnostics output)
- `feat(skill): restore find/get for legacy skill market API` — `skill find`, `skill get`; `skill add` still uses aihub download

#### Edition / overlay hooks

- `edition.Hooks.SaveToken` / `LoadToken` / `DeleteToken` — delegate token persistence with keychain fallback
- `edition.Hooks.AuthClientID` / `AuthClientFromMCP` — overlay can override the OAuth client ID and route auth through MCP endpoints
- `edition.Hooks.AfterPersistentPreRun` — wire non-MCP clients (e.g. A2A gateway) after root setup
- `edition.Hooks.ClassifyToolResult` — custom MCP result classification before the default business-error detection
- Token marker file (`token.json`) for embedded hosts to detect auth state without keychain access
- `pkg/runtimetoken.ResolveAccessToken` mirroring MCP auth resolution; MCP identity headers exported via `pkg/cli` for auxiliary HTTP transports
- `ExitCoder` interface — edition-specific errors carry custom exit codes
- `RawStderrError` interface — errors that bypass CLI formatting and emit raw stderr (for desktop runtimes)

### Changed

- **Command execution pipeline: 3 → 5 stages** (`Register → PreParse → PostParse → PreRequest → PostResponse`)
- `feat(schema): return structured degraded errors instead of silent empty catalog` — new `CatalogDegraded` error with reasons `unauthenticated` / `market_unreachable` / `runtime_all_failed`; auth pre-check short-circuits doomed MCP connections
- `refactor(auth): unify auxiliary token resolution with MCP cached path` — shared `resolveAccessTokenFromDir`; overlays reuse the process-level token cache
- `feat(plugin): improve CLI overlay resolution and plugin install robustness`
  - `plugin.json` `cli` field now accepts a file path (e.g. `"cli": "overlay.json"`) in addition to inline JSON
  - `description` field on `CLIToolOverride` for static fallback when MCP `tools/list` is unavailable
  - Windows install uses `cmd /C` instead of `sh -c` for build commands

### Fixed

- `fix(plugin): harden plugin system security boundaries`
  - Reject `file://` / local paths in git URLs; allow only `https` / `ssh`
  - Reject symlink entries during ZIP extraction (path-traversal defense)
  - `build.output` must be a relative path within the plugin directory
  - Reject absolute paths in stdio command declarations
  - Block dangerous env var names (`PATH`, `LD_PRELOAD`, …) from plugin config injection
- `fix(plugin): schema flag params, HTTP tool discovery, and integration tests`
- `fix(plugin): skip min version check in dev mode`

## [1.0.8] - 2026-04-07

AITable command surface expansion, installer alignment with npm conventions, and execution-timeout hardening.

### Added

- **AITable static helper commands** (20 commands in total) replacing dynamic routing:
  - `base`: `list`, `search`, `get`, `create`, `update`
  - `table`: `get`, `create`, `update`
  - `field`: `get`, `create`, `update`
  - `record`: `query`, `create`, `update`
  - `template`: `search`
  - `attachment`: `upload`
- `feat(install): align skill dirs with npm and add OpenClaw` — skill install paths follow npm conventions; OpenClaw added to supported agents
- Label rendering optimization for AITable records (`to #73551688`)
- README: npm install method documented
- README: note that `dws upgrade` requires v1.0.7+

### Changed

- `perf: optimize command timeout handling, instrumentation, and diagnostics`

## [1.0.7] - 2026-04-02

Self-upgrade, edition overlay foundation, and fail-closed auth enforcement.

### Added

- **`dws upgrade`** — self-upgrade via GitHub Releases; atomic replace; cross-platform (macOS/Linux/Windows)
- `feat: edition layer for Wukong overlay` — build-time edition hook lets downstream overlays customize auth UX, config dir, static server list, visible products, and extra root commands
  - `pkg/edition` defaults + `pkg/editiontest` contract tests
  - `Makefile` target `edition-test`; CI job `edition-tests`
  - Static server injection skips market discovery when configured
  - Deduplicates top-level commands so overlay wins
  - `hideNonDirectRuntimeCommands` respects edition `VisibleProducts`
  - Gated `auth login` subcommand + hints for embedded editions
  - Optional token auto-purge; edition `ConfigDir` override
- `dws version` — human-readable multi-line output plus JSON with edition, architecture, build, commit
- Tag reporting for case suites (`to #73551688`)
- `feat(auth): unify MCP retry constant and add retry to remaining endpoints`

### Changed

- `style(auth): redesign OAuth authorization pages UI`

### Fixed

- `fix(auth): switch CLI auth check from fail-open to fail-closed`
  - When `/cli/cliAuthEnabled` is unreachable (network error/timeout/5xx), OAuth callback now routes to the permission request page instead of silently marking "enabled"
  - Device Flow blocks login and asks the user to verify network connectivity
  - `CheckCLIAuthEnabled` retries with backoff (3 attempts, 0s/1s/2s) to tolerate transient issues

## [1.0.6] - 2026-04-01

Error diagnostics overhaul, destructive-command confirmation, and credential auto-persistence.

### Added

- **Interactive confirmation for destructive dynamic commands** — prompts before delete/remove operations unless `--yes` is set
- **Enhanced error diagnostics**
  - `ServerDiagnostics` struct extracts `trace_id`, `server_error_code`, `technical_detail`, `server_retryable` from MCP responses
  - Pulls diagnostics from JSON-RPC `error.data`, tool call result content, and HTTP headers (`X-Trace-Id`, `X-Request-Id`, `x-dingtalk-trace-id`)
  - Three verbosity levels for `PrintHuman`: Normal (trace ID + server code), Verbose (+ technical detail), Debug (+ RPC code / operation / reason)
  - Local logging now includes sanitized request body, response body on error, retry attempts, and classification events
  - `TruncateBody` / `SanitizeArguments` / `RedactHeaders` helpers with sensitive-key substring detection
- **Auth credential persistence**
  - `feat(auth): enhance device flow with CLI auth check and admin guidance`
  - `feat(auth): persist OAuth credentials for reliable token refresh`
  - `feat(auth): persist client credentials and optimize keychain access` — auto-persist `--client-id` / `--client-secret`; keychain credential cache to avoid repeated reads; enhanced logout cleans `app.json` + keychain secrets + `token.json`
- `add report helper with flexible date parsing and defaults`
- `feat: to #73551688 支持消息通知`
- README: Official App mode (recommended, direct login without creating an app) + Custom App mode; admin guide for enabling CLI access

### Changed

- Getting Started simplified with inline login commands; whitelist references removed from the IMPORTANT banner
- Version bump documentation updated to v1.0.5 internal; co-creation group QR code refreshed

### Fixed

- `fix: resolve verbosity flag lookup, FileLogger lazy binding, and business error logging`
  - `resolveVerbosity` uses `cmd.Flags()` instead of `PersistentFlags()` so subcommands inherit `--verbose` / `--debug`
  - `FileLogger` lazy-binds in `executeInvocation` (after `configureLogLevel` init)
  - Business errors (HTTP 200 + `success=false`) now written to the file logger for offline diagnosis
- OAuth callback race condition (write response before sending code)
- `import path for errors package in skill_command.go`

## [1.0.4] - 2026-03-30

Token-refresh reliability and onboarding clarity.

### Added

- `feat(auth): persist client credentials for token refresh` — `--client-id` / `--client-secret` are stored for automatic refresh after expiration; client secret lives in the system Keychain with a file reference
- README onboarding flow rewrite with step-by-step first-time setup and more realistic examples
- Agent skill reference polish: clearer examples, updated intent routing patterns, expanded `simple.md` onboarding, cross-skill reference fixes

## [1.0.3] - 2026-03-29

Filtering power, schema rendering, and a native `todo` command family.

### Added

- **Nested / array-indexed output filtering**
  - `--fields` now accepts dot-notation (e.g. `--fields response.content`) and array index access (e.g. `response.items[0]`)
  - New field-path parser with recursive extraction logic
- **`schema` command enhancements**
  - Table format output for human consumption
  - Product-level endpoint loading in the CLI loader
  - Schema-text rendering wired into the runner output pipeline
- **`todo` task helper family** — static `create` / `update` / `done` / `get` / `delete` with `preferLegacyLeaf` replacing dynamic commands
  - MCP tool alignment: `create_personal_todo`, `update_todo_task`, `update_todo_done_status`, `query_todo_detail`, `delete_todo`
  - ISO-8601 due-time parsing
  - Hidden title aliases and delete confirmation
  - Priority field on `todo` helper
  - Expanded zh / en i18n coverage (fixes `en.json` spacing/wording issues)
- README restructured with collapsible feature sections

## [1.0.2] - 2026-03-29

Deep workspace tooling upgrade: pipeline-based input correction, output filtering, enhanced stdin handling, and multi-endpoint routing.

### Added

- Pipeline engine (`internal/pipeline`) for pre-parse and post-parse input correction
  - `AliasHandler`: normalises model-generated flag casing (e.g. `--userId` → `--user-id`)
  - `StickyHandler`: splits glued flag values (e.g. `--limit100` → `--limit 100`)
  - `ParamNameHandler`: fixes near-miss flag typos (e.g. `--limt` → `--limit`)
  - `ParamValueHandler`: normalises structured parameter values after parsing
- Output filtering via `--fields` and `--jq` global flags (`internal/output/filter.go`)
  - `--fields`: comma-separated field selection for top-level keys (case-insensitive)
  - `--jq`: jq expression filtering powered by `gojq` library
- `StdinGuard` for safe single-read stdin across multiple flags in one invocation
- `ResolveInputSource` unified resolver supporting `@file`, `@-` (explicit stdin), and implicit pipe fallback
- `@file` / `@-` syntax support for all string-typed override flags in tool commands
- Chat helper support for `@file` input to read message content from files
- Tool-level endpoint routing (`dynamicToolEndpoints`) for multi-endpoint products
- Comprehensive test suites for pipeline handlers, stdin guard, canonical commands, and chat input

### Changed

- `directRuntimeEndpoint` now accepts tool name for finer-grained endpoint resolution
- `collectOverrides` resolves `@file` / `@-` for all string-typed flags
- `NewRootCommand` refactored to `NewRootCommandWithEngine` with optional pipeline engine
- `schema` command no longer hidden (visible in help output)
- Default output format changed from `table` to `json`

## [1.0.1] - 2026-03-28

Backward-compatible feature and security update after the initial 1.0.0 release.

### Added

- JSON output support for `dws auth login` and `dws auth status`
- Cross-platform keychain-backed secure storage and migration helpers
- Atomic file write helpers to avoid partial config and download writes
- Stronger path and input validation helpers for local file operations
- Install-script coverage for local-source installs

### Changed

- Improved `auth login` help text, hidden compatibility flags, and interactive UX
- Added root-level flag suggestions for common compatibility mistakes such as `--json` and legacy auth flags
- Updated AITable upload parsing to accept nested `content` payloads
- Refreshed bundled skills metadata for the new CLI version

## [1.0.0] - 2026-03-27

First public release of DingTalk Workspace CLI.

### Core

- Discovery-driven CLI pipeline: Market → Discovery → IR → CLI → Transport
- MCP JSON-RPC transport with retries, auth injection, and response size limits
- Disk-based discovery cache with TTL and stale-fallback for offline resilience
- OAuth device flow authentication with PBKDF2 + AES-256-GCM encrypted token storage
- Structured output formats: JSON, table, raw
- Global flags: `--format`, `--verbose`, `--debug`, `--dry-run`, `--yes`, `--timeout`
- Exit codes with structured error payloads (category, reason, hint, actions)

### Supported Services

- **aitable** — AI table: bases, tables, fields, records, templates
- **approval** — Approval processes, forms, instances
- **attendance** — Attendance records, shifts, statistics
- **calendar** — Events, participants, meeting rooms, free-busy
- **chat** — Bot messaging (group/batch), webhook, bot management
- **contact** — Users, departments, org structure
- **devdoc** — Open platform docs search
- **ding** — DING messages: send, recall
- **report** — Reports, templates, statistics
- **todo** — Task management: create, update, complete, delete
- **workbench** — Workbench app query

### Agent Skills

- Bundled `SKILL.md` with product reference docs, intent routing guide, error codes, and batch scripts
- One-line installer for macOS / Linux / Windows
- Skills installed to `~/.agents/skills/dws` (home) or `./.agents/skills/dws` (project)

### Packaging

- Pre-built binaries for macOS (arm64/amd64), Linux (arm64/amd64), Windows (amd64)
- One-line install scripts (`install.sh`, `install.ps1`)
- Project-level skill installer (`install-skills.sh`)
- Shell completion: Bash, Zsh, Fish