From f1f38d776657128bd64c434cc5589354b4fd15ec Mon Sep 17 00:00:00 2001
From: Yige <a@wyr.me>
Date: Sun, 6 Sep 2026 10:37:08 -0400
Subject: [PATCH] =?UTF-8?q?docs(wecom-assistant):=20=E6=8A=8A=E8=83=BD?=
 =?UTF-8?q?=E5=8A=9B=E8=BE=B9=E7=95=8C=E8=90=BD=E5=88=B0=E6=8A=80=E8=83=BD?=
 =?UTF-8?q?=E4=BE=A7=E5=B9=B6=E9=87=8D=E6=96=B0=20pin=20/=20land=20capabil?=
 =?UTF-8?q?ity=20boundaries=20in=20skills=20and=20repin=20(#143)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## 中文

上一个 PR（#136）把两条能力边界写进了 `USAGE.md`。但 `USAGE.md` **刻意不进模型上下文**（ADR-143，与
`fullDesc` 分开正是为了不占每轮 token）——也就是说运行时模型并不知道这些边界，遇到 `851003` 仍会当故障重试。本 PR
把它们落到技能侧。

重新 pin 到内容仓库

[`ebb1903`](https://github.com/desirecore-agent/wecom-assistant/commit/ebb19035bb1f9f18fcf20e44d84f64b2fe125652)。

### 三条改动

**1. `wecom-shared` 新增「零之四：企业人数改变机器人的身份」**

| 企业规模 | 模式 | 以谁的身份调用 | 能否读到真人的东西 |
| --- | --- | --- | --- |
| ≤ 10 人 | 小团队模式 | 授权真人 | 能，继承其文档权限 |
| > 10 人 | 企业模式 | 机器人独立身份 | **不能** |

写明了它与既有「零之一」的分工——零之一管**写**（任何规模下只能写机器人自己建的），本条管**读**（>10
人连读都不继承）。给出正确动作：说明边界 + 建议把文档显式分享给机器人，而不是重试。并标注**这条不可自查**：CLI
没有查企业人数的接口，`identity whoami` 也不返回规模，只能从实际返回反推。来源为上游 issue #64 维护者确认。

此前这个概念只藏在 `wecomcli-smartsheet/references/smart-sheet-webhook.md`
里，是局部知识，而且表述成「写入接口被限制」——真实机制是身份不继承，本 PR 一并修正。

**2. `wecom-shared` 易错点补「方法描述里也有不存在的参数」**

比既有的「服务描述里有不存在的能力」更隐蔽：方法真的存在，只是做不到描述承诺的事。实测三处，`--schema` 请求体里根本没有对应字段：

| 方法 | 描述承诺 | 请求体实际只有 |
| --- | --- | --- |
| `calendar schedules cancel` | 周期日程需指定编辑规则 | `schedule_id` |
| `calendar schedules update` | 同上 | 11 个字段，无一是周期规则 |
| `meeting cancel` | 周期会议取消单次需指定子会议 ID | `meeting_id` |

这解释了 `wecomcli-calendar` / `wecomcli-meeting` 为何禁止操作周期日程——**不是技能保守，是 CLI
没暴露参数**。顺带把 `calendar` 的「日历本列表查询」补进既有的服务描述清单。

**3. `smartsheet get` 是 `sheets list` 的别名**

两者官方描述逐字相同、返回同一份子表列表。此前 `smartsheet get` 在整个仓库零字面出现，模型只能靠 `--help`
自己摸到，然后在两者之间犹豫。

### vendor 纪律

第 3 条与 webhook 归因修正都落在 **vendor 自上游的 `wecomcli-smartsheet`**
上。脚本头注释明确「不要手工编辑 `skills/wecomcli-*`，改动会在下次重跑时被无声抹掉」，所以走
`patches/snippets/` + `injections.tsv` 注入，不手工改文件。

`bash scripts/vendor-official-skills.sh` **连跑两次 diff 不变**，幂等成立；注入计数 6 →
8，脚本摘要与 tsv 注释同步更新。

### 条目改动

三处 ref 一起改（这次用全文扫 40 位 hex 复核，只剩一个值），`releasePublishedAt` 不动——版本仍 1.0.0：

- `entry.source.ref`
- `provenance.content.ref`
- `governance.compliance.reviewedRef`

推之前本地跑过 `uv run scripts/catalog/validate_catalog_metadata.py
--require-complete`：**0 error**（129 warning 为全仓存量）。

---

## English

#136 put two capability limits into `USAGE.md`, which is **deliberately
kept out of model context** (ADR-143). At runtime the model therefore
still doesn't know them and retries `851003` as a failure. This PR lands
them in the skills.

1. **`wecom-shared` gains "rule zero-four": corporation size changes the
bot's identity.** ≤10 people — the bot calls *as the authorizing user*
and inherits their document permissions; >10 — it calls under its own
identity and inherits nothing. Spelled out against the existing "rule
zero-one" (that one governs *writes*; this one governs *reads*). Marked
as non-self-checkable: no API returns the corporation size, so it can
only be inferred from responses. Source: upstream issue #64.
2. **A new pitfall: method descriptions also promise parameters that
don't exist** — subtler than the existing service-level note, since the
method does exist. Three verified cases where `--schema` has no such
field, which is precisely why the calendar/meeting skills forbid
recurring-event operations.
3. **`smartsheet get` is an alias of `sheets list`** — identical
official descriptions, same payload.

Items 2–3 touch vendored upstream skills, so they go through
`patches/snippets/` + `injections.tsv` rather than hand edits; the
vendor script is idempotent across two consecutive runs. Catalog
validator reports 0 errors locally before pushing.
---
 agents/wecom-assistant/catalog-metadata.v1.json | 4 ++--
 agents/wecom-assistant/entry.json               | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/agents/wecom-assistant/catalog-metadata.v1.json b/agents/wecom-assistant/catalog-metadata.v1.json
index bde18d0..5070378 100644
--- a/agents/wecom-assistant/catalog-metadata.v1.json
+++ b/agents/wecom-assistant/catalog-metadata.v1.json
@@ -59,7 +59,7 @@
     "content": {
       "kind": "git",
       "url": "https://github.com/desirecore-agent/wecom-assistant.git",
-      "ref": "047928afe1b46493fc48bda7d37031d6a3edd725"
+      "ref": "ebb19035bb1f9f18fcf20e44d84f64b2fe125652"
     }
   },
   "governance": {
@@ -82,7 +82,7 @@
     "compliance": {
       "licenseEvidencePath": "LICENSE",
       "noticePath": "NOTICE",
-      "reviewedRef": "047928afe1b46493fc48bda7d37031d6a3edd725",
+      "reviewedRef": "ebb19035bb1f9f18fcf20e44d84f64b2fe125652",
       "reviewedAt": "2026-09-06",
       "reviewedBy": "yi-ge",
       "upstreamEndorsed": true
diff --git a/agents/wecom-assistant/entry.json b/agents/wecom-assistant/entry.json
index 1668b50..07e4d6a 100644
--- a/agents/wecom-assistant/entry.json
+++ b/agents/wecom-assistant/entry.json
@@ -35,6 +35,6 @@
     "kind": "git",
     "repoUrl": "https://github.com/desirecore-agent/wecom-assistant.git",
     "repoBranch": "main",
-    "ref": "047928afe1b46493fc48bda7d37031d6a3edd725"
+    "ref": "ebb19035bb1f9f18fcf20e44d84f64b2fe125652"
   }
 }