xuanandshangguanxuan.sgx
da2522c8ca
* feat(pat): A-core minimum viable loop for host-owned PAT
Enables third-party agents to integrate PAT via the smallest possible
contract surface. The flow a host needs to ship end-to-end:
1. Export DINGTALK_DWS_AGENTCODE in the spawned shell.
2. Run any `dws ...` business command.
3. On PAT hit, CLI exits with code 4 and writes a single-line stderr
JSON following docs/pat/contract.md §2.
4. Host parses the JSON and invokes `dws pat chmod <scope>...
--agentCode ... --grant-type ...` to grant.
5. Host replays the original command.
This PR intentionally ships ONLY the chmod path plus the host-owned
switch; the async flow (apply / status / scopes + authRequestId
registry + PAT_SCOPE_AUTH_REQUIRED active-request branch) lands in a
follow-up stacked PR (A-ext).
Scope of A-core:
- Host-owned PAT trigger: auth.HostOwnsPATFlow() keyed exclusively on
DINGTALK_DWS_AGENTCODE (DINGTALK_AGENT / DWS_CHANNEL / claw-type do
NOT participate).
- claw-type: hard-wired to "openClaw" in pkg/edition/default.go
MergeHeaders hook, matching historical main behavior and decoupled
from DINGTALK_AGENT.
- dws pat chmod: factory-built (newChmodCommand) so the PAT subcommand
tree has no shared package-level caller.
- stderr JSON classifier: internal/errors/pat.go covers PAT_NO_PERMISSION
/ PAT_LOW_RISK / PAT_MEDIUM_RISK / PAT_HIGH_RISK / PAT_SCOPE_*
selectors and fills data.hostControl for host consumption.
- Env contract: DINGTALK_SESSION_ID / DINGTALK_TRACE_ID /
DINGTALK_MESSAGE_ID carry HTTP trace headers (Chain B);
DWS_SESSION_ID (+ REWIND_SESSION_ID alias) is the lone fallback for
`dws pat chmod --session-id` (Chain A). The two chains are
independent; aliases do not cross-pollinate.
- Docs: docs/pat/{README,contract,host-integration}.md + refreshed
docs/architecture.md "PAT Architecture" chapter + docs/reference.md
PAT section. error-catalog.md folded into contract.md §6.
- Tests: host-owned signal, stderr contract, classifier, chmod factory,
retry / poll loop for the CLI-owned chmod path.
Compatibility: no breaking changes on main. All non-PAT commands are
untouched.
Follow-up PRs (in order):
- codex/pat-ext : dws pat apply / status / scopes + AsyncRegistry.
- codex/pat-oss-refactor (aka PR B) : oauth_helpers / secure_store
refactors split out per code review.
Made-with: Cursor
* fix(pat): unify host-owned stderr contract
* revert: drop PAT docs and changelog from pat core PR
* fix(pat): pin behavior auth endpoint
* fix(pat): recognize legacy tool miss
* fix(pat): fallback on gateway diagnostics
* fix(pat): treat authorization uri as opaque
* fix(pat): accept result envelope in device-flow polling
* feat(pat): add browser policy and poll compatibility
* fix(pat): keep CLI and host PAT contracts separate
* test(pat): isolate opaque uri retry env
* fix(pat): harden PAT result routing
* fix(pat): harden host-owned flow and runtime fallback
* fix(pat): preserve chmod failure on empty grant result
* refactor(pat): drop dead doc anchors, dedupe stderr injection helpers
Address two reviewer findings on top of the PAT-core series.
Fix:
- chmod: resolveSessionIDFromEnv silently selects DWS_SESSION_ID; drop
the slog.Warn that emitted both raw session ids into stderr /
~/.dws/logs.
- Remove every docs/pat/contract.md / error-catalog.md /
host-integration.md anchor from comments, help, and tests; those
files were never added by this branch. Comments are now self-contained
or point to docs/reference.md where applicable.
Refactor:
- internal/errors/pat.go: extract lookupCodeIn so getPATErrorCode and
getDWSGatewayErrorCode share one traversal; have ClassifyPatAuthCheck
delegate to getPATErrorCode instead of repeating the enum walk.
- internal/errors/pat.go + internal/app/pat_auth_retry.go: extract
ApplyHostMutations as the single injection point for data.hostControl
+ data.openBrowser; cleanPATJSON and enrichPATErrorForHostControl now
share it so the two stderr-JSON write paths cannot drift.
- internal/app/pat_auth_retry.go: drop buildPATScopeHostJSON and
buildHostControlState dead 1-line wrappers.
- internal/pat/chmod.go: drop unused patApply/Status/Scopes constants;
derive legacyToolArgs from toolArgs by clone + scopes->scope rename so
the two payloads stay in lock-step on every other field.
Net 15 files, +176 / -193. Verification:
env -u DINGTALK_DWS_AGENTCODE go test \
./internal/errors ./internal/auth ./internal/pat ./test/unit
env -u DINGTALK_DWS_AGENTCODE go test ./internal/app \
-run 'Test(IsPat|ExtractPat|PrintPat|PollPat|HandlePat|RetryWithPat|EnrichPAT|BuildPAT|DirectRuntime|ResolveIdentityHeaders)'
env -u DINGTALK_DWS_AGENTCODE go test -race \
./internal/pat ./internal/errors ./test/unit
env -u DINGTALK_DWS_AGENTCODE go test -race ./internal/app \
-run 'Test(HandlePat|RetryWithPat|EnrichPAT|BuildPAT|ResolveIdentityHeaders|DirectRuntime)'
go vet ./... && go build ./...
All green.
Made-with: Cursor
---------
Co-authored-by: shangguanxuan.sgx <shangguanxuan.sgx@alibaba-inc.com>
103 lines
4.6 KiB
Markdown
103 lines
4.6 KiB
Markdown
# Reference / 参考手册
|
||
|
||
## Environment Variables / 环境变量
|
||
|
||
| Variable | Purpose / 用途 |
|
||
|---------|---------|
|
||
| `DWS_CONFIG_DIR` | Override default config directory / 覆盖默认配置目录 |
|
||
| `DWS_SERVERS_URL` | Point discovery at a custom server registry endpoint / 将服务发现指向自定义端点 |
|
||
| `DWS_CLIENT_ID` | OAuth client ID (DingTalk AppKey) |
|
||
| `DWS_CLIENT_SECRET` | OAuth client secret (DingTalk AppSecret) |
|
||
| `DWS_TRUSTED_DOMAINS` | Comma-separated trusted domains for bearer token (default: `*.dingtalk.com`). `*` for dev only / Bearer token 允许发送的域名白名单，默认 `*.dingtalk.com`，仅开发环境可设为 `*` |
|
||
| `DWS_ALLOW_HTTP_ENDPOINTS` | Set `1` to allow HTTP for loopback during dev / 设为 `1` 允许回环地址 HTTP，仅用于开发调试 |
|
||
|
||
## Exit Codes / 退出码
|
||
|
||
| Code | Category | Description / 描述 |
|
||
|------|----------|-------------|
|
||
| 0 | Success | Command completed successfully / 命令执行成功 |
|
||
| 1 | API | MCP tool call or upstream API failure / MCP 工具调用或上游 API 失败 |
|
||
| 2 | Auth | Authentication or authorization failure / 身份认证或授权失败 |
|
||
| 3 | Validation | Invalid input, flags, or parameter schema mismatch / 输入参数校验失败 |
|
||
| 4 | PAT | PAT authorization interception; stderr carries raw machine-readable PAT JSON / PAT 授权拦截；stderr 返回原始机器可解析 JSON |
|
||
| 5 | Internal | Unexpected internal error / 未预期的内部错误 |
|
||
| 6 | Discovery | Server discovery, cache, or protocol negotiation failure / 服务发现、缓存或协议协商失败 |
|
||
|
||
With `-f json`, error responses include structured payloads: `category`, `reason`, `hint`, `actions`.
|
||
|
||
使用 `-f json` 时，错误响应包含结构化字段：`category`、`reason`、`hint`、`actions`。
|
||
|
||
## Output Formats / 输出格式
|
||
|
||
```bash
|
||
dws contact user search --keyword "Alice" -f table # Table (default, human-friendly / 表格，默认)
|
||
dws contact user search --keyword "Alice" -f json # JSON (for agents and piping / 适合 agent)
|
||
dws contact user search --keyword "Alice" -f raw # Raw API response / 原始响应
|
||
dws schema -f pretty ding.send_ding_message # Pretty (ANSI-colored, schema-aware / 彩色分区，专为 schema 设计)
|
||
```
|
||
|
||
## Dry Run / 试运行
|
||
|
||
```bash
|
||
dws todo task list --dry-run # Preview MCP call without executing / 预览但不执行
|
||
```
|
||
|
||
## Output to File / 输出到文件
|
||
|
||
```bash
|
||
dws contact user search --keyword "Alice" -o result.json
|
||
```
|
||
|
||
## Schema Introspection / Schema 查询
|
||
|
||
`dws schema` 查询已发现的 MCP 产品和工具元数据。不带参数列出所有产品，带路径输出单个工具的完整 schema。
|
||
|
||
### 路径写法
|
||
|
||
```bash
|
||
dws schema # 列出所有产品 + 工具名
|
||
dws schema ding.send_ding_message # canonical: product.rpc_name
|
||
dws schema ding.message.send # CLI 点路径: product.group.cli_name
|
||
dws schema "ding message send" # CLI 空格路径（同上）
|
||
dws schema --cli-path "ding message send" # 显式 flag（脚本友好，免转义）
|
||
dws schema -f pretty ding.send_ding_message # ANSI 着色分区展示（人肉查看最舒服）
|
||
```
|
||
|
||
Canonical 路径先匹配；落空后走 CLI 路径（product → group.. → cli_name）。
|
||
|
||
### 单工具输出字段
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| `name` / `cli_name` / `canonical_path` | MCP RPC 名 / CLI 叶子名 / `product.rpc_name` |
|
||
| `group` | CLI 父级 group 路径（dot-separated） |
|
||
| `title` / `description` | 工具名/说明（overlay 优先） |
|
||
| `parameters` / `required` | MCP 输入 JSON Schema 的 properties / required |
|
||
| `output_schema` | MCP 输出 Schema（上游下发时才有） |
|
||
| `sensitive` | 敏感写操作，需 `--yes` 确认 |
|
||
| `annotations.destructive_hint` | 对齐 MCP 2025+ annotations，目前从 `sensitive` 映射 |
|
||
| `flag_overlay[param]` | CLI 层对 MCP 参数的改写：`alias` / `transform` / `transform_args` / `env_default` / `default` / `hidden` |
|
||
|
||
**调试 `--flag` 行为的第一站**是 `flag_overlay` —— 比如 `--users 0232...` 能不能直接用，看 `receiverUserIdList.transform == "csv_to_array"` 即可判断。
|
||
|
||
### 筛选输出
|
||
|
||
```bash
|
||
dws schema ding.send_ding_message --jq '.tool.flag_overlay' # 只看 overlay
|
||
dws schema --jq '.products[] | {id, count: (.tools|length)}' # 各产品工具数
|
||
dws schema aitable.delete_base --jq '.tool.annotations' # 敏感操作提示
|
||
```
|
||
|
||
## Shell Completion / 自动补全
|
||
|
||
```bash
|
||
# Bash
|
||
dws completion bash > /etc/bash_completion.d/dws
|
||
|
||
# Zsh
|
||
dws completion zsh > "${fpath[1]}/_dws"
|
||
|
||
# Fish
|
||
dws completion fish > ~/.config/fish/completions/dws.fish
|
||
```
|