docs: add command framework comparison (DWS vs lark-cli vs GWS)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs/command-framework-comparison.md

@@ -0,0 +1,235 @@
+# 命令框架对比：DWS cmdcore vs lark-cli vs GWS
+
+本文档对比 DWS（钉钉工作区 CLI）、lark-cli（飞书 CLI）和 GWS（Google Workspace CLI / gcloud）三套命令框架的设计差异。
+
+## 总览对比
+
+| 维度 | DWS (cmdcore) | lark-cli | GWS (gcloud) |
+|------|---------------|----------|--------------|
+| 语言 | Go | Go | Python (gcloud) / Go (部分) |
+| CLI 框架 | cobra | cobra | argparse + calliope |
+| 调用底座 | MCP JSON-RPC | Lark REST SDK (`CallAPITyped`) | Google API Client |
+| 命令层次 | 2 层：LeafSpec + Shortcut | 3 层：Shortcuts + API Commands + Raw API | 2 层：surface commands + raw |
+| Schema 来源 | 代码声明投影 | 代码声明 + 运行时 introspection | API Discovery 文档自动生成 |
+| Agent 适配 | 内建 (dws.schema.*) | 内建 (--print-schema) | 外挂 (MCP adapter) |
+
+## 架构对比
+
+### DWS cmdcore
+
+```
+CommandSpec (声明) → NewCommand() → cobra.Command
+     │
+     ├── Risk enum (运行时确认)
+     ├── Safety enum (Schema 元数据)
+     ├── FlagSpec[] (参数 + 回退链 + 绑定)
+     ├── Constraint[] (互斥/至少一个)
+     ├── SchemaDecl (Agent Selection/Safety/DryRun/Interface)
+     │
+     └── Invoke / Orchestrate / RunE (执行)
+```
+
+**核心特点**：
+- 声明与执行严格分离
+- Risk（运行时）和 Safety（Schema）独立枚举
+- 有效值回退链：flag → alias → env → default
+- 框架统一校验、装配、确认、投影
+- Schema 从代码声明直接投影，无外部 hint 文件
+
+### lark-cli
+
+```
+Shortcut (声明) → runner.Mount() → cobra.Command
+     │
+     ├── Risk string (确认行为)
+     ├── Scopes / ConditionalScopes (OAuth 权限)
+     ├── Flag[] (参数 + Enum + Input sources)
+     ├── AuthTypes (user/bot)
+     │
+     ├── DryRun hook → DryRunAPI
+     ├── Validate hook
+     └── Execute hook → RuntimeContext → CallAPITyped
+```
+
+**核心特点**：
+- Execute 内直接调 REST API (`CallAPITyped`)
+- DryRun 是独立 hook（返回结构化 API 计划）
+- 内建 OAuth scope 声明与预检
+- `--print-schema --flag-name` 运行时 introspection
+- 无 Schema 投影层，Agent 通过 introspection 动态发现
+
+### GWS (gcloud 风格)
+
+```
+API Discovery → 代码生成 → surface command
+     │
+     ├── arguments (从 JSON Schema 自动生成)
+     ├── request/response 映射
+     └── 自定义 action hook (少量)
+```
+
+**核心特点**：
+- Schema-first：从 API Discovery 文档自动生成命令
+- 参数直接映射 API 字段（flat schema）
+- 人工 surface command 是 thin wrapper
+- Agent 适配通过 MCP 外部 adapter
+
+## 核心设计差异
+
+### 1. 声明粒度
+
+| 能力 | DWS cmdcore | lark-cli | GWS |
+|------|-------------|----------|-----|
+| 参数别名 + 环境变量回退 | ✅ FlagSpec.Aliases + EnvVar | ❌ 无 | ❌ 无 |
+| 声明式约束 (互斥/至少一个) | ✅ Constraint[] | ❌ 只有 Validate hook | ✅ argparse group |
+| Risk/Safety 分离 | ✅ 两个独立枚举 | ❌ 只有 Risk | ❌ 无 |
+| Schema 投影 (Agent metadata) | ✅ SchemaDecl 内建 | ⚠️ 运行时 introspection | ❌ 外挂 |
+| 参数绑定 (flag name → API key) | ✅ FlagSpec.Bind | ❌ 手写 | ✅ 自动映射 |
+| ConstParams (固定载荷) | ✅ | ❌ 手写在 Execute | ✅ 隐式 |
+| 确认门顺序可配 (ConfirmFirst) | ✅ | ❌ 固定顺序 | ❌ 无确认机制 |
+
+### 2. 执行模型
+
+| 维度 | DWS cmdcore | lark-cli | GWS |
+|------|-------------|----------|-----|
+| 参数装配 | 框架自动 (BuildArgs) | 手写 (`runtime.Str()/Bool()`) | 自动映射 |
+| 派发方式 | Invoke(ctx, toolArgs) | Execute(ctx, runtime) | 自动调用 |
+| 多步编排 | Orchestrate(ctx) | Execute 内链式 CallAPITyped | 不支持 |
+| DryRun | 框架统一 (--dry-run flag) | 独立 DryRun hook 返回 API 计划 | 部分命令支持 |
+| 错误分类 | apperrors 类型化 | errs.Problem 类型化 | HTTP status 映射 |
+
+### 3. Agent 适配
+
+| 维度 | DWS cmdcore | lark-cli | GWS |
+|------|-------------|----------|-----|
+| 工具发现 | `dws schema --all` (静态 catalog) | `--print-schema` (运行时) | API Discovery |
+| 选择指引 | SelectionDecl (UseWhen/AvoidWhen) | Description + Tips | 无 |
+| 安全声明 | Safety enum + SafetyDecl | Risk string | 无 |
+| dry-run 能力声明 | DryRunDecl (reviewed) | DryRun hook 存在性 | 无 |
+| 接口模式 | InterfaceDecl (local/pinned/composite) | 隐式 (全部 REST) | 隐式 (全部 REST) |
+
+### 4. Schema 生命周期
+
+```
+DWS:      代码声明 → code review → cobra annotation → catalog/metadata JSON
+          (单一数据源，构建时验证完整性)
+
+lark-cli: 代码声明 → 运行时 introspection → Agent 动态发现
+          (无离线 catalog，Agent 必须执行命令才能发现)
+
+GWS:      API Discovery JSON → 代码生成 → surface command
+          (Schema-first，但命令行体验受限于 API 形状)
+```
+
+## 设计哲学对比
+
+### DWS cmdcore 的选择
+
+| 选择 | 理由 | 对比 |
+|------|------|------|
+| 框架装配参数 | 消除 N 个命令各写一份 toolArgs 装配 | lark-cli 每个 Execute 手动取 flag 值 |
+| Risk + Safety 分离 | 运行时行为与 Schema 元数据独立演进 | lark-cli 只有 Risk 一个维度 |
+| 声明式约束 | 构建时校验合法性 + 投影到 Schema + 渲染帮助 | lark-cli 约束隐藏在 Validate 逻辑里 |
+| Schema 构建时投影 | 离线 catalog 支持 Agent 批量发现 | lark-cli 需要逐个命令 introspection |
+| 有效值回退链 | flag → alias → env 统一语义 | lark-cli 别名是独立 Flag 手动关联 |
+| ConfirmFirst | 精确建模遗留语义 | lark-cli 确认始终在 Execute 内 |
+
+### lark-cli 的选择
+
+| 选择 | 理由 | 对比 |
+|------|------|------|
+| 直连 REST API | 精确控制请求/响应，可处理分页/重试 | DWS 通过 MCP 间接调用 |
+| DryRun 返回 API 计划 | Agent 可预览将要发出的真实 HTTP 请求 | DWS dry-run 只展示参数 |
+| OAuth scope 声明 | 框架预检权限，失败提前 | DWS 依赖 MCP 层鉴权 |
+| `--print-schema` introspection | 运行时发现，无需维护离线 catalog | DWS 需要 re-generate |
+| Input sources (file/@path/stdin) | 丰富的输入方式声明 | DWS 无此抽象 |
+| PrintFlagSchema | 单 flag 级别的 JSON Schema 暴露 | DWS 只在 catalog 级别 |
+
+### GWS (gcloud) 的选择
+
+| 选择 | 理由 | 对比 |
+|------|------|------|
+| API Discovery 驱动 | 一份 Schema 生成所有：SDK/CLI/文档 | DWS/lark 手写 |
+| Flat parameter 映射 | API 字段 = CLI flag，零转换 | DWS 需要 Bind 映射 |
+| 无 shortcut 层 | API 粒度即用户粒度 | DWS/lark 有精选层 |
+
+## 代码量对比
+
+| 框架 | 核心框架代码 | 单命令声明开销 | 备注 |
+|------|-------------|---------------|------|
+| DWS cmdcore | ~1400 行 (cmdcore.go + schema_decl.go) | ~20-30 行 (纯声明) | 框架重、单命令轻 |
+| lark-cli | ~800 行 (runner.go + types.go + common.go) | ~50-150 行 (声明 + Execute 逻辑) | 框架轻、单命令重 |
+| GWS gcloud | ~5000+ 行 (calliope 框架) | ~10 行 (多数自动生成) | 框架最重、单命令最轻 |
+
+## DWS 命令声明示例 vs lark-cli
+
+### DWS (cmdcore / LeafSpec)
+
+```go
+NewLeafCommand(LeafSpec{
+    Use:    "create",
+    Short:  "创建应用",
+    Tool:   "create_dev_app",
+    Risk:   LeafRiskHighWrite,
+    Safety: LeafSafetyHighWrite,
+    ConfirmFirst: true,
+    Flags: []LeafFlag{
+        {Name: "name", Usage: "应用名称", Bind: "name",
+         Trim: true, Required: true, RequiredHint: "--name 为必填"},
+    },
+    Schema: LeafSchema{
+        Description: "创建开放平台企业内部应用",
+        DryRun:    &LeafDryRunDecl{PreviewKind: "invocation"},
+        Interface: &LeafInterfaceDecl{Mode: "composite", Availability: "available"},
+        Selection: LeafSelectionDecl{
+            AgentSummary: "创建钉钉开放平台应用",
+            UseWhen:      []string{"需要新建企业内部应用"},
+            AvoidWhen:    []string{"应用已存在时用 update"},
+            Examples:     []string{`dws dev app create --name "Bot" --dry-run`},
+        },
+    },
+    Call: devAppCall(runner),
+})
+```
+
+### lark-cli (Shortcut)
+
+```go
+var CalendarCreate = common.Shortcut{
+    Service:     "calendar",
+    Command:     "+create",
+    Description: "Create a new calendar event",
+    Risk:        "write",
+    Scopes:      []string{"calendar:calendar"},
+    Flags: []common.Flag{
+        {Name: "summary", Desc: "Event title", Required: true},
+        {Name: "start", Desc: "Start time (RFC3339)", Required: true},
+        {Name: "end", Desc: "End time (RFC3339)", Required: true},
+        {Name: "attendees", Type: "string_slice", Desc: "Attendee emails"},
+    },
+    DryRun: func(ctx context.Context, rt *common.RuntimeContext) *common.DryRunAPI {
+        return &common.DryRunAPI{
+            Method: "POST",
+            Path:   "/open-apis/calendar/v4/calendars/{id}/events",
+            Body:   buildEventBody(rt),
+        }
+    },
+    Execute: func(ctx context.Context, rt *common.RuntimeContext) error {
+        body := buildEventBody(rt)
+        data, err := rt.CallAPITyped("POST",
+            "/open-apis/calendar/v4/calendars/{id}/events", nil, body)
+        if err != nil { return err }
+        return rt.Output(data)
+    },
+}
+```
+
+## 适用场景总结
+
+| 场景 | 最适合 | 原因 |
+|------|--------|------|
+| MCP 后端 + Agent Schema 投影 | **DWS cmdcore** | 内建 Schema 声明、Safety 分级、离线 catalog |
+| REST API 直连 + OAuth scope 管理 | **lark-cli** | CallAPITyped + scope 预检 + DryRun API 计划 |
+| API-first 大规模 surface 生成 | **GWS gcloud** | Discovery 驱动，一份 Schema 生成一切 |
+| 多步编排 (跨服务链式调用) | **lark-cli** / DWS Orchestrate | lark 的 CallAPITyped 链式 + DWS 的 Orchestrate |
+| 遗留系统迁移 (保持行为等价) | **DWS cmdcore** | ConfirmFirst + 回退链 + catalog 漂移门禁 |