docs(mail): add Non-goals + safety rules 9/10/11; empty-result blocks#714
Open
infeng wants to merge 1 commit intolarksuite:mainfrom
Open
docs(mail): add Non-goals + safety rules 9/10/11; empty-result blocks#714infeng wants to merge 1 commit intolarksuite:mainfrom
infeng wants to merge 1 commit intolarksuite:mainfrom
Conversation
… in 5 read refs Per tech-design §4.1-§4.5: harden lark-mail SKILL with two doc-only signals. mail.md template: - Add 3 new safety rules covering "empty result is a legal answer" (rule 9), "fuzzy match needs user adjudication" (rule 10), and "sensitive write ops require user confirmation" (rule 11) with the six API tokens enumerated verbatim (messages.trash / batch_trash / recall / labels.delete / folders.delete / mail_contacts.delete). - Add ## ⛔ Non-goals section (5-row table per §4.4) between safety rules and identity-selection. - Extend cap-line to mark Non-goals as same-priority as safety rules. 5 read-op references (triage / message / messages / thread / watch): - Insert ## ⛔ 空结果处理 block immediately before each file's trailing ## 相关命令 / ## 参考 heading. Each block distinguishes empty-array vs 404 vs network/permission errors per §4.2 and references back to Non-goals 第 1 条 + 安全规则 第 9 条. skills/lark-mail/SKILL.md: - Regenerated via registry's gen-skills.py (equivalent to `make all project=mail` for the gen-skills target). The regen also refreshed API-resource and permission-table descriptions from registry-conf/output/from_meta/mail.json — these are normal regen drift since the artifact was last hand-curated. The regen dropped the multi_entity / sent_messages / templates resource blocks because registry-config.yaml does not list them under mail.apis; this is a pre-existing gap between mail.md prose and registry-config and is out-of-scope for this sprint per §1.3 (do not touch registry-config). Deviation from spec wording: spec §4.1 names new rules "8/9/10" but rule 8 (草稿回链规则) already exists. Following the S1 contract's Option A, new rules land at slots 9/10/11 leaving rule 8 intact, and the read-op reference-back text cites "第 9 条" instead of the spec's "第 8 条". The substantive content of each rule is unchanged. NOT touched (per spec §4.5): 6 write-op references, shortcuts/mail/, internal/registry/meta_data.json, lark-shared, other domain templates, skill-template/skill-template.md. sprint: S2
📝 WalkthroughWalkthroughThis pull request updates mail-related documentation to enforce stricter safety constraints, error handling procedures, and non-goals. Changes span core policy files and operation-specific references, clarifying how agents must handle empty/error responses, ambiguous matches, and sensitive write operations while preventing fabrication of targets. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Suggested labels
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Review rate limit: 7/8 reviews remaining, refill in 7 minutes and 30 seconds.Comment |
github-actions
Bot
added
domain/mail
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@skills/lark-mail/references/lark-mail-message.md`:
- Line 230: The doc's empty-result check wrongly references data.message which
doesn't exist in this response shape; update the text to check for the presence
of required fields instead (e.g., verify that data.message_id and the body_*
fields are present and populated) or reword to "data 缺少关键字段/未包含 message_id 或
body_*"; adjust the sentence that currently mentions `data.message` to reference
`message_id` and `body_*` (or a generic "缺少关键字段") so implementations won't rely
on the non-existent `data.message` field.
In `@skills/lark-mail/references/lark-mail-thread.md`:
- Line 111: The doc incorrectly references data.thread; update the wording to
remove data.thread and base the existence check on data.messages and thread_id
instead: change the sentence that reads "若 `data.messages` 为空数组或 `data.thread`
缺失" to something like "若 `data.messages` 为空数组或 `thread_id` 缺失/不匹配" (or simply
rely on `data.messages` and `thread_id`) so the logic aligns with the defined
return fields (`data.thread_id`, `data.message_count`, `data.messages`) and
avoid referencing the nonexistent `data.thread` field.
In `@skills/lark-mail/SKILL.md`:
- Around line 523-524: Fill in missing short semantic descriptions for the two
empty entries under user_mailbox.rules: add a one-sentence description for
`user_mailbox.rules.reorder` explaining it reorders rules within a user's
mailbox (e.g., change rule priority/order), and add a one-sentence description
for `user_mailbox.rules.update` explaining it updates an existing mailbox rule's
properties (conditions/actions). Locate the entries named `reorder` and `update`
under `user_mailbox.rules` in SKILL.md and replace the empty bullets with those
concise descriptions to restore API docs readability.
- Line 42: The doc uses a short API name `messages.recall` but examples use full
resource.method form like `user_mailbox.sent_messages recall`; update the
wording on this line (and any other occurrences such as `messages.trash`,
`messages.batch_trash`, `labels.delete`, `folders.delete`,
`mail_contacts.delete`) to use the complete resource.method format (e.g.,
`user_mailbox.sent_messages recall`) so examples and the API list are consistent
and avoid misbinding at runtime.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: b5a074e5-8899-4d6c-b808-10edaf7f7e89
📒 Files selected for processing (7)
skill-template/domains/mail.mdskills/lark-mail/SKILL.mdskills/lark-mail/references/lark-mail-message.mdskills/lark-mail/references/lark-mail-messages.mdskills/lark-mail/references/lark-mail-thread.mdskills/lark-mail/references/lark-mail-triage.mdskills/lark-mail/references/lark-mail-watch.md
|
|
||
| | 情形 | 表现 | 正确做法 | | ||
| |------|------|----------| | ||
| | 200 OK 但内容为空 | 极少出现；若 `data.message` 字段缺失或仅含基础元数据，视同未取到 | 回报"未能取到该邮件的完整内容"，请用户确认 `message_id` 是否正确 | |
There was a problem hiding this comment.
空结果判定字段名与文档返回结构冲突
Line 230 使用 data.message，但本页返回值定义为 data.message_id 等平铺字段。建议改为“data 缺少关键字段”或直接引用 message_id/body_*，避免实现按错误路径判断。
✏️ 建议修订
-| 200 OK 但内容为空 | 极少出现；若 `data.message` 字段缺失或仅含基础元数据，视同未取到 | 回报"未能取到该邮件的完整内容"，请用户确认 `message_id` 是否正确 |
+| 200 OK 但内容为空 | 极少出现；若 `data` 缺少正文等关键字段或仅含基础元数据，视同未取到 | 回报"未能取到该邮件的完整内容"，请用户确认 `message_id` 是否正确 |📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| | 200 OK 但内容为空 | 极少出现；若 `data.message` 字段缺失或仅含基础元数据，视同未取到 | 回报"未能取到该邮件的完整内容"，请用户确认 `message_id` 是否正确 | | |
| | 200 OK 但内容为空 | 极少出现；若 `data` 缺少正文等关键字段或仅含基础元数据，视同未取到 | 回报"未能取到该邮件的完整内容"，请用户确认 `message_id` 是否正确 | |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@skills/lark-mail/references/lark-mail-message.md` at line 230, The doc's
empty-result check wrongly references data.message which doesn't exist in this
response shape; update the text to check for the presence of required fields
instead (e.g., verify that data.message_id and the body_* fields are present and
populated) or reword to "data 缺少关键字段/未包含 message_id 或 body_*"; adjust the
sentence that currently mentions `data.message` to reference `message_id` and
`body_*` (or a generic "缺少关键字段") so implementations won't rely on the
non-existent `data.message` field.
|
|
||
| | 情形 | 表现 | 正确做法 | | ||
| |------|------|----------| | ||
| | 200 OK 但 `messages` 为空 | 极少出现；若 `data.messages` 为空数组或 `data.thread` 缺失，视同会话不存在或已被全部删除 | 回报"该会话目前没有可读邮件（可能整个会话已被删除）"，请用户确认 `thread_id` 是否正确 | |
There was a problem hiding this comment.
data.thread 字段引用与本文返回结构不一致
Line 111 提到 data.thread 缺失，但本页“返回值”定义的是 data.thread_id / data.message_count / data.messages。建议改成仅基于 data.messages、thread_id 判定，避免误导实现。
✏️ 建议修订
-| 200 OK 但 `messages` 为空 | 极少出现；若 `data.messages` 为空数组或 `data.thread` 缺失，视同会话不存在或已被全部删除 | 回报"该会话目前没有可读邮件（可能整个会话已被删除）"，请用户确认 `thread_id` 是否正确 |
+| 200 OK 但 `messages` 为空 | 极少出现；若 `data.messages` 为空数组（或关键字段缺失），视同会话不存在或已被全部删除 | 回报"该会话目前没有可读邮件（可能整个会话已被删除）"，请用户确认 `thread_id` 是否正确 |📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| | 200 OK 但 `messages` 为空 | 极少出现；若 `data.messages` 为空数组或 `data.thread` 缺失，视同会话不存在或已被全部删除 | 回报"该会话目前没有可读邮件（可能整个会话已被删除）"，请用户确认 `thread_id` 是否正确 | | |
| | 200 OK 但 `messages` 为空 | 极少出现；若 `data.messages` 为空数组（或关键字段缺失），视同会话不存在或已被全部删除 | 回报"该会话目前没有可读邮件（可能整个会话已被删除）"，请用户确认 `thread_id` 是否正确 | |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@skills/lark-mail/references/lark-mail-thread.md` at line 111, The doc
incorrectly references data.thread; update the wording to remove data.thread and
base the existence check on data.messages and thread_id instead: change the
sentence that reads "若 `data.messages` 为空数组或 `data.thread` 缺失" to something like
"若 `data.messages` 为空数组或 `thread_id` 缺失/不匹配" (or simply rely on `data.messages`
and `thread_id`) so the logic aligns with the defined return fields
(`data.thread_id`, `data.message_count`, `data.messages`) and avoid referencing
the nonexistent `data.thread` field.
| 8. **草稿回链规则** — 凡是执行结果产出了草稿，且当前流程不是直接发信（例如 `+draft-create`、`+send` 的草稿模式、`+reply` / `+reply-all` / `+forward` 的草稿模式、草稿编辑后继续查看），都应优先向用户展示草稿打开链接。当前应以创建、编辑、发送链路返回的链接信息为准；**不要把 `user_mailbox.drafts get` 当作获取草稿打开链接的来源**。若当前输出未包含链接，则静默处理，**禁止凭空拼接或猜测 URL**。 | ||
| 9. **空结果即合法答案** — 查询返回空数组、404 或权限不足，都是合法的、需要如实告知的答案。**禁止**通过 `+send` / `user_mailbox.folders create` / `user_mailbox.labels create` / `user_mailbox.mail_contacts create` / `user_mailbox.drafts create` 等写操作凭空构造目标对象再去满足后续动作（删除 / 归档 / 转发 / 回复）。正确做法是把"未找到 / 无结果 / 无权限"原样回报给用户，请用户确认下一步。 | ||
| 10. **模糊匹配需用户裁决** — 当存在多个语义近似但非精确匹配的候选（如多个同名标签、多个主题相似的邮件、多个匹配关键词的联系人）时，**必须**列出全部候选项请求用户裁决，**禁止**自作主张选择其中一个执行写操作。读操作可基于合理默认（如"最近 20 封"）展示给用户，但要明确告知是基于哪个默认范围。 | ||
| 11. **敏感写操作前需用户确认** — 以下**无运行时门禁**的写操作在执行前必须先向用户展示「操作对象 + 动作 + 预计影响范围」，并取得当前轮次明确同意：删除邮件 / 撤回邮件 / 批量移动 / 标签删除 / 文件夹删除 / 联系人删除。Agent 在调用以下原生 API 时同样适用：<!-- 如新增 messages.* / labels.* / folders.* / mail_contacts.* 删除/批量类 API，必须同步追加到本条 --> `messages.trash` / `messages.batch_trash` / `messages.recall` / `labels.delete` / `folders.delete` / `mail_contacts.delete`。批量场景必须在确认前给出受影响条目的总数与样例预览，禁止在未确认的情况下直接发起。 |
There was a problem hiding this comment.
敏感操作 API 名称建议统一到完整 resource.method
Line 42 使用 messages.recall，但本页命令示例是 user_mailbox.sent_messages recall。建议统一成完整命名，避免执行时误配 API。
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@skills/lark-mail/SKILL.md` at line 42, The doc uses a short API name
`messages.recall` but examples use full resource.method form like
`user_mailbox.sent_messages recall`; update the wording on this line (and any
other occurrences such as `messages.trash`, `messages.batch_trash`,
`labels.delete`, `folders.delete`, `mail_contacts.delete`) to use the complete
resource.method format (e.g., `user_mailbox.sent_messages recall`) so examples
and the API list are consistent and avoid misbinding at runtime.
Comment on lines
+523
to
+524
| - `reorder` — | ||
| - `update` — |
There was a problem hiding this comment.
user_mailbox.rules 两个方法描述为空
Line 523 和 Line 524 目前是空描述，建议补齐最小语义说明，避免 API 目录可读性回退。
✏️ 建议补全
- - `reorder` —
- - `update` —
+ - `reorder` — 调整收信规则执行顺序
+ - `update` — 更新指定收信规则配置📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| - `reorder` — | |
| - `update` — | |
| - `reorder` — 调整收信规则执行顺序 | |
| - `update` — 更新指定收信规则配置 |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@skills/lark-mail/SKILL.md` around lines 523 - 524, Fill in missing short
semantic descriptions for the two empty entries under user_mailbox.rules: add a
one-sentence description for `user_mailbox.rules.reorder` explaining it reorders
rules within a user's mailbox (e.g., change rule priority/order), and add a
one-sentence description for `user_mailbox.rules.update` explaining it updates
an existing mailbox rule's properties (conditions/actions). Locate the entries
named `reorder` and `update` under `user_mailbox.rules` in SKILL.md and replace
the empty bullets with those concise descriptions to restore API docs
readability.
🚀 PR Preview Install Guide🧰 CLI updatenpm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@7d6a0b75dd699a1d053cac0950105293063c366e🧩 Skill updatenpx skills add infeng/cli#harness/01kqby5sxrytrtfhv7v5s09kqx -y -g |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #714 +/- ##
=======================================
Coverage 64.14% 64.14%
=======================================
Files 504 504
Lines 44285 44285
=======================================
Hits 28406 28406
Misses 13411 13411
Partials 2468 2468 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
xzcong0820
reviewed
Apr 29, 2026
| | `user_mailbox.sent_messages.get_recall_detail` | `mail:user_mailbox.message:readonly` | | ||
| | `user_mailbox.sent_messages.recall` | `mail:user_mailbox.message:modify` | | ||
| | `user_mailbox.settings.send_as` | `mail:user_mailbox:readonly` | | ||
| | `user_mailbox.template.attachments.download_url` | `mail:user_mailbox.message:readonly` | |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Generated by the harness-coding skill.
Sprints
Source specs
This MR was created autonomously. Quality gates were enforced by the repo's own pre-commit hooks.
Summary by CodeRabbit
Release Notes