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

docs: present shortcut catalog without hidden release wording

Browse Source 
Replace release-hidden terminology with a generated public shortcut catalog, remove include-hidden discovery, and keep real-test followups as an internal CR artifact.
This commit is contained in:
Dennis
2026-07-15 17:02:42 +08:00
parent 00f1379874
commit 6de77f4c34
34 changed files with 1854 additions and 337 deletions
Download Patch File Download Diff File Expand all files Collapse all files
scripts/gen_shortcut_release_hidden.py → scripts/gen_shortcut_public_catalog.py
+48 -48
View File
@@ -1,11 +1,5 @@
#!/usr/bin/env python3
"""Generate the release-hidden shortcut list from real test results.
Shortcuts whose latest real-backend result is not `real-ok` are kept in source
code but hidden from public discovery for this release. The generated Go file
is a release gate; the Markdown/JSON files are the handoff list for the next
iteration.
"""
"""Generate the public shortcut catalog from real test results."""
from __future__ import annotations
@@ -19,9 +13,10 @@ from typing import Any
ROOT = Path(__file__).resolve().parents[1]
READ_PATH = ROOT / "docs" / "shortcut-real-read-results.json"
WRITE_PATH = ROOT / "docs" / "shortcut-real-write-results.json"
GO_PATH = ROOT / "internal" / "shortcut" / "release_hidden_generated.go"
MD_PATH = ROOT / "docs" / "shortcut-next-release-hidden.md"
JSON_PATH = ROOT / "docs" / "shortcut-next-release-hidden.json"
GO_PATH = ROOT / "internal" / "shortcut" / "public_catalog_generated.go"
CATALOG_PATH = ROOT / "docs" / "shortcut-public-catalog.json"
FOLLOWUP_MD_PATH = ROOT / "docs" / "shortcut-real-test-followups.md"
FOLLOWUP_JSON_PATH = ROOT / "docs" / "shortcut-real-test-followups.json"
def load(path: Path) -> dict[str, Any]:
@@ -64,26 +59,32 @@ def evidence(row: dict[str, Any]) -> str:
return squish(error_text(row), 220)
def collect() -> list[dict[str, Any]]:
out: list[dict[str, Any]] = []
def collect() -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
public: list[dict[str, Any]] = []
followups: list[dict[str, Any]] = []
for suite, path in (("read", READ_PATH), ("write", WRITE_PATH)):
data = load(path)
for row in data.get("results", []):
if row.get("status") == "real-ok":
continue
out.append({
item = {
"suite": suite,
"service": row.get("service") or "",
"command": row.get("command") or "",
"risk": row.get("risk") or "",
"status": row.get("status") or "",
}
if row.get("status") == "real-ok":
public.append(item)
continue
followups.append({
**item,
"failure_category": row.get("failure_category") or "unclassified",
"fixability": row.get("fixability") or "",
"diagnosis": row.get("diagnosis") or "",
"evidence": evidence(row),
})
out.sort(key=lambda r: (r["suite"], r["service"], r["command"]))
return out
public.sort(key=lambda r: (r["service"], r["command"]))
followups.sort(key=lambda r: (r["suite"], r["service"], r["command"]))
return public, followups
def go_quote(s: str) -> str:
@@ -92,24 +93,17 @@ def go_quote(s: str) -> str:
def write_go(rows: list[dict[str, Any]]) -> None:
lines = [
"// Code generated by scripts/gen_shortcut_release_hidden.py; DO NOT EDIT.",
"// Code generated by scripts/gen_shortcut_public_catalog.py; DO NOT EDIT.",
"",
"package shortcut",
"",
"// releaseHiddenShortcuts contains shortcuts intentionally hidden from",
"// public discovery in this release because their latest real-backend",
"// test did not pass. The command implementations remain registered and",
"// invocable by exact path for internal follow-up testing.",
"var releaseHiddenShortcuts = map[string]string{",
"// publicShortcutCatalog contains the generated shortcut surface used by",
"// command discovery and skill generation.",
"var publicShortcutCatalog = map[string]struct{}{",
]
for row in rows:
key = f"{row['service']}\x00{row['command']}"
reason = (
f"{row['suite']} real test not passed; "
f"status={row['status']}; category={row['failure_category']}; "
f"fixability={row['fixability'] or '-'}"
)
lines.append(f"\t{go_quote(key)}: {go_quote(reason)},")
lines.append(f"\t{go_quote(key)}: {{}},")
lines.extend(["}", ""])
GO_PATH.write_text("\n".join(lines), encoding="utf-8")
@@ -118,20 +112,20 @@ def md_escape(s: str) -> str:
return str(s).replace("|", "\\|").replace("\n", "<br>")
def write_md(rows: list[dict[str, Any]]) -> None:
def write_followup_md(rows: list[dict[str, Any]]) -> None:
generated = dt.datetime.now().isoformat(timespec="seconds")
lines = [
"# 本期隐藏、下期修复的 shortcut 清单",
"# Shortcut 真实测试跟进清单",
"",
f"生成时间：`{generated}`",
"",
"来源：`docs/shortcut-real-read-results.json` 与 `docs/shortcut-real-write-results.json`。",
"",
"口径：最新真实后端测试结果不是 `real-ok` 的 shortcut，本期不对外 release；代码保留，并通过 `internal/shortcut/release_hidden_generated.go` 标记为 Hidden，后续补 fixture / 修后端 / 修 CLI 后再放开。",
"口径：记录真实后端测试中需要继续定位的 case，用于 CR 和问题分派；Agent 使用入口以公开 shortcut catalog 和产品 skill 为准。",
"",
f"总计：{len(rows)} 条。",
"",
"| # | suite | shortcut | risk | status | category | fixability | 下期处理依据 |",
"| # | suite | shortcut | risk | status | category | fixability | 处理依据 |",
"|---:|---|---|---|---|---|---|---|",
]
for idx, row in enumerate(rows, 1):
@@ -144,27 +138,33 @@ def write_md(rows: list[dict[str, Any]]) -> None:
f"{md_escape(squish(basis, 160))} |"
)
lines.append("")
MD_PATH.write_text("\n".join(lines), encoding="utf-8")
FOLLOWUP_MD_PATH.write_text("\n".join(lines), encoding="utf-8")
def write_json(rows: list[dict[str, Any]]) -> None:
payload = {
"generated_at": dt.datetime.now().isoformat(),
"count": len(rows),
"results": rows,
}
JSON_PATH.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
def write_json(public: list[dict[str, Any]], followups: list[dict[str, Any]]) -> None:
generated = dt.datetime.now().isoformat()
CATALOG_PATH.write_text(json.dumps({
"generated_at": generated,
"count": len(public),
"results": public,
}, ensure_ascii=False, indent=2), encoding="utf-8")
FOLLOWUP_JSON_PATH.write_text(json.dumps({
"generated_at": generated,
"count": len(followups),
"results": followups,
}, ensure_ascii=False, indent=2), encoding="utf-8")
def main() -> int:
rows = collect()
write_go(rows)
write_md(rows)
write_json(rows)
print(f"hidden={len(rows)}")
public, followups = collect()
write_go(public)
write_followup_md(followups)
write_json(public, followups)
print(f"public={len(public)} followups={len(followups)}")
print(f"written: {GO_PATH}")
print(f"written: {MD_PATH}")
print(f"written: {JSON_PATH}")
print(f"written: {CATALOG_PATH}")
print(f"written: {FOLLOWUP_MD_PATH}")
print(f"written: {FOLLOWUP_JSON_PATH}")
return 0
scripts/gen_skill_shortcut_sections.py
+14 -16
View File
@@ -1,11 +1,9 @@
#!/usr/bin/env python3
"""Generate visible shortcut sections for DWS skills.
"""Generate shortcut sections for DWS skills.
The skill should teach agents which high-level shortcut entries are available
for the current release, while `dws <service> --help` remains the source of
truth for flags. Hidden shortcuts are intentionally omitted from product skill
tables and remain documented in docs/shortcut-next-release-hidden.md for CR /
next-release repair.
in the public catalog, while `dws <service> --help` remains the source of truth
for flags.
"""
from __future__ import annotations
@@ -22,7 +20,7 @@ sys.path.insert(0, str(ROOT / "scripts"))
import gen_shortcut_comparison as shortcut_source # noqa: E402
HIDDEN_PATH = ROOT / "docs" / "shortcut-next-release-hidden.json"
CATALOG_PATH = ROOT / "docs" / "shortcut-public-catalog.json"
MONO_SKILL = ROOT / "skills" / "mono" / "SKILL.md"
SERVICE_TO_SKILL = {
@@ -55,10 +53,10 @@ def md_escape(value: Any) -> str:
return text.replace("\\", "\\\\").replace("|", "\\|").replace("\n", " ")
def load_hidden() -> set[tuple[str, str]]:
if not HIDDEN_PATH.exists():
def load_public_catalog() -> set[tuple[str, str]]:
if not CATALOG_PATH.exists():
return set()
data = json.loads(HIDDEN_PATH.read_text(encoding="utf-8"))
data = json.loads(CATALOG_PATH.read_text(encoding="utf-8"))
return {
(str(row["service"]), str(row["command"]))
for row in data.get("results", [])
@@ -66,11 +64,11 @@ def load_hidden() -> set[tuple[str, str]]:
def collect_visible() -> list[dict[str, Any]]:
hidden = load_hidden()
public_catalog = load_public_catalog()
items = [
item
for item in shortcut_source.collect()
if (item["service"], item["command"]) not in hidden
if (item["service"], item["command"]) in public_catalog
]
return sorted(items, key=lambda item: (item["service"], item["command"]))
@@ -94,11 +92,11 @@ def mono_overview(items: list[dict[str, Any]]) -> str:
rows.append(f"| `{md_escape(service)}` | {count} | `{md_escape(skill)}` | `dws {md_escape(service)} --help` / `dws shortcut list --service {md_escape(service)} --format json` |")
body = "\n".join(rows)
return f"""{MONO_START}
## 本期可见 Shortcut 总览
## Shortcut 总览
下面只统计本期真实测试通过、默认 `--help` / `dws shortcut list` 可见的 shortcut。mono 模式不展开 200+ 行明细，避免 skill 过重；需要执行时先按产品路由，再用 `dws <service> --help` 查看 flags。multi 模式的各产品 skill 会展开该产品的可见 shortcut 表。
下面统计当前公开 catalog 中的 shortcut。mono 模式不展开 200+ 行明细，避免 skill 过重；需要执行时先按产品路由，再用 `dws <service> --help` 查看 flags。multi 模式的各产品 skill 会展开该产品的 shortcut 表。
| 服务 | 可见 shortcut 数 | multi skill | 发现命令 |
| 服务 | shortcut 数 | multi skill | 发现命令 |
|---|---:|---|---|
{body}
{MONO_END}"""
@@ -112,9 +110,9 @@ def product_section(service: str, rows: list[dict[str, Any]]) -> str:
f"{md_escape(item['risk'])} | {md_escape(item['desc'])} |"
)
return f"""{PRODUCT_START}
## Shortcuts（本期可见，优先使用）
## Shortcuts（优先使用）
以下 shortcut 已通过本期真实测试并在默认 `dws {service} --help` / `dws shortcut list --service {service}` 中可见。用户意图命中时优先使用 shortcut；具体 flags 以 `dws {service} <shortcut> --help` 为准。未列出的同产品 shortcut 属于本期隐藏项，不在业务执行时主动推荐。
以下 shortcut 来自当前公开 catalog，并可通过 `dws {service} --help` / `dws shortcut list --service {service}` 发现。用户意图命中时优先使用 shortcut；具体 flags 以 `dws {service} <shortcut> --help` 为准。
| Shortcut | 风险 | 适用场景 |
|---|---|---|