docs: add Prerequisites section, DingTalk contact, and DCO signoff rule#8
docs: add Prerequisites section, DingTalk contact, and DCO signoff rule#8
Conversation
- README/docs index (en+zh): document the one-time AliyunAgentRunSuperAgentRole authorization link and the AliyunAgentRunFullAccess AccessKey requirement, plus a console pointer for users wanting more than the QuickStart flow - super-agent command pages (en+zh): add a heads-up linking to Prerequisites - README community section: surface the 函数计算 AgentRun 客户群 DingTalk group number 134570017218 - error handling: extend auth-error pattern matching (AccessDenied, NoPermission, AliyunAgentRunSuperAgentRole, EntityNotExist.Role) and emit a structured `hint` field pointing to the README Prerequisites anchor Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Signed-off-by: Sodawyx <sodawyx@126.com>
Document the existing DCO signoff requirement (git commit -s) under a new "Commit Requirements" section so contributors and AI assistants don't push unsigned commits and have to re-create them. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Signed-off-by: Sodawyx <sodawyx@126.com>
There was a problem hiding this comment.
Pull request overview
Adds clearer onboarding prerequisites and community contact info to the docs/READMEs, and improves CLI auth/permission error handling by emitting a structured hint field that points users to the prerequisites.
Changes:
- Document two one-time
super-agentprerequisites (RAM role authorization +AliyunAgentRunFullAccess) across README and bilingual docs, plus a console link for the full AgentRun experience. - Add DingTalk community group info (EN/ZH READMEs) and codify DCO sign-off requirements in
AGENTS.md. - Extend
_utils.error.handle_errorsand_utils.output.echo_errorto include an optionalhintin stderr JSON, with unit tests for new patterns/behavior.
Reviewed changes
Copilot reviewed 11 out of 11 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/unit/test_output.py | Verifies echo_error omits hint by default and includes it when provided. |
| tests/unit/test_error.py | Adds parametrized coverage for new auth/permission error patterns and hint emission. |
| src/agentrun_cli/_utils/output.py | Extends echo_error() to accept optional hint and serialize it into stderr JSON. |
| src/agentrun_cli/_utils/error.py | Adds prerequisites hint constant + broadens auth detection to include more permission/role patterns. |
| docs/zh/super-agent.md | Adds a prerequisites heads-up before running super-agent commands. |
| docs/zh/index.md | Adds “前置准备” section documenting the two one-time setup steps + console link. |
| docs/en/super-agent.md | Adds a prerequisites heads-up before running super-agent commands. |
| docs/en/index.md | Adds “Prerequisites” section documenting the two one-time setup steps + console link. |
| README_zh.md | Adds prerequisites section + community (DingTalk) section. |
| README.md | Adds prerequisites section + community (DingTalk) section. |
| AGENTS.md | Adds “Commit Requirements” section documenting DCO Signed-off-by requirement. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| > [前置准备](./index.md#前置准备) 中的两项一次性配置 —— | ||
| > 授权 `AliyunAgentRunSuperAgentRole` 角色,并给 AccessKey 挂载 | ||
| > `AliyunAgentRunFullAccess` 系统策略。任一项缺失都会以退出码 `3` | ||
| > (`AccessDenied`)失败。 |
There was a problem hiding this comment.
这里写“退出码 3(AccessDenied)失败”,但代码现在也会把 NoPermission / EntityNotExist.Role 等权限/角色相关报错归类为退出码 3。建议改成不强绑定 AccessDenied 文案(例如“退出码 3(权限/认证错误)”)。
| > (`AccessDenied`)失败。 | |
| > (权限/认证错误)失败。 |
| payload — used to surface Prerequisites links on permission failures. | ||
| """ | ||
| payload: dict = {"error": error_type, "message": message} | ||
| if hint: |
There was a problem hiding this comment.
echo_error only includes the hint field when hint is truthy. The docstring says the field is included when hint is provided, so passing an empty string (or other falsy but intentional value) would silently drop the field. Consider checking hint is not None instead of truthiness so the behavior matches the API contract.
| if hint: | |
| if hint is not None: |
| if any(pattern in msg for pattern in _AUTH_PATTERNS): | ||
| echo_error("AuthenticationFailed", msg, hint=PREREQUISITES_HINT) | ||
| sys.exit(EXIT_AUTH_ERROR) |
There was a problem hiding this comment.
The prerequisites hint is currently emitted for all _AUTH_PATTERNS, including InvalidAccessKey and SignatureDoesNotMatch. Those cases are not addressed by authorizing the RAM role / attaching AliyunAgentRunFullAccess, so the hint can be misleading. Consider splitting patterns into (a) auth classification patterns and (b) permission/role prerequisite patterns, and only attach PREREQUISITES_HINT for the latter while still exiting with EXIT_AUTH_ERROR for the former.
| > one-time setup steps in [Prerequisites](./index.md#prerequisites) — the | ||
| > `AliyunAgentRunSuperAgentRole` authorization and the | ||
| > `AliyunAgentRunFullAccess` policy on your AccessKey. Missing either one | ||
| > surfaces as exit code `3` (`AccessDenied`). |
There was a problem hiding this comment.
This note says missing prerequisites surfaces as exit code 3 (AccessDenied), but the code now also treats other permission/role messages (e.g. NoPermission, EntityNotExist.Role) as exit code 3. Consider rewording to avoid implying the stderr message is always AccessDenied (e.g. “exit code 3 (authentication/permission error)”).
| > surfaces as exit code `3` (`AccessDenied`). | |
| > surfaces as exit code `3` (authentication/permission error). |
Summary
README.md,README_zh.md,docs/{en,zh}/index.md, and a heads-up ondocs/{en,zh}/super-agent.mddocumenting the two one-time setup steps users must complete before anyar super-agentcommand works:AliyunAgentRunSuperAgentRoleRAM service role via the RAM authorization linkAliyunAgentRunFullAccessto the AccessKey configured viaar config set134570017218._utils/error.handle_errorsto recognize more permission/role error patterns (AccessDenied,NoPermission,AliyunAgentRunSuperAgentRole,EntityNotExist.Role) and emit a structuredhintfield in the stderr JSON pointing back to the README Prerequisites anchor — so users hitting auth errors are nudged straight to the fix.AGENTS.md: codify the existing DCOSigned-off-byrequirement under a new "Commit Requirements" section so future contributors / AI assistants don't push unsigned commits.Test plan
pytest --cov=agentrun_cli --cov-fail-under=95— 364 passed, coverage 95.19% (gate ≥95%);_utils/error.pyand_utils/output.pyat 100%.hintfield onecho_error.SuperAgentCustomRoletemplate page.🤖 Generated with Claude Code