Skip to content

docs: add Prerequisites section, DingTalk contact, and DCO signoff rule#8

Merged
Sodawyx merged 2 commits intomainfrom
docs/prerequisites-and-contact
Apr 25, 2026
Merged

docs: add Prerequisites section, DingTalk contact, and DCO signoff rule#8
Sodawyx merged 2 commits intomainfrom
docs/prerequisites-and-contact

Conversation

@Sodawyx
Copy link
Copy Markdown
Contributor

@Sodawyx Sodawyx commented Apr 25, 2026

Summary

  • Add a Prerequisites section to README.md, README_zh.md, docs/{en,zh}/index.md, and a heads-up on docs/{en,zh}/super-agent.md documenting the two one-time setup steps users must complete before any ar super-agent command works:
    • authorize the AliyunAgentRunSuperAgentRole RAM service role via the RAM authorization link
    • grant AliyunAgentRunFullAccess to the AccessKey configured via ar config set
  • Tell users explicitly that the CLI focuses on the QuickStart conversational flow; for the full experience, point them to the Function Compute AgentRun console (https://functionai.console.aliyun.com/cn-hangzhou/agent/).
  • Add a Community / 社区 section with the 函数计算 AgentRun 客户群 DingTalk group number 134570017218.
  • Extend _utils/error.handle_errors to recognize more permission/role error patterns (AccessDenied, NoPermission, AliyunAgentRunSuperAgentRole, EntityNotExist.Role) and emit a structured hint field 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 DCO Signed-off-by requirement 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.py and _utils/output.py at 100%.
  • New unit tests cover the four new auth-error patterns (parametrized) and the optional hint field on echo_error.
  • Manually verified bilingual parity: README ↔ README_zh, docs/en ↔ docs/zh.
  • Reviewer to click the RAM authorization link and confirm it lands on the expected SuperAgentCustomRole template page.

🤖 Generated with Claude Code

Sodawyx and others added 2 commits April 25, 2026 16:44
- 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>
Copilot AI review requested due to automatic review settings April 25, 2026 09:07
@Sodawyx Sodawyx merged commit e2677ed into main Apr 25, 2026
17 checks passed
Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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-agent prerequisites (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_errors and _utils.output.echo_error to include an optional hint in 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.

Comment thread docs/zh/super-agent.md
> [前置准备](./index.md#前置准备) 中的两项一次性配置 ——
> 授权 `AliyunAgentRunSuperAgentRole` 角色,并给 AccessKey 挂载
> `AliyunAgentRunFullAccess` 系统策略。任一项缺失都会以退出码 `3`
> (`AccessDenied`)失败。
Copy link

Copilot AI Apr 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

这里写“退出码 3AccessDenied)失败”,但代码现在也会把 NoPermission / EntityNotExist.Role 等权限/角色相关报错归类为退出码 3。建议改成不强绑定 AccessDenied 文案(例如“退出码 3(权限/认证错误)”)。

Suggested change
> `AccessDenied`)失败。
> 权限/认证错误)失败。

Copilot uses AI. Check for mistakes.
payload — used to surface Prerequisites links on permission failures.
"""
payload: dict = {"error": error_type, "message": message}
if hint:
Copy link

Copilot AI Apr 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
if hint:
if hint is not None:

Copilot uses AI. Check for mistakes.
Comment on lines +72 to 74
if any(pattern in msg for pattern in _AUTH_PATTERNS):
echo_error("AuthenticationFailed", msg, hint=PREREQUISITES_HINT)
sys.exit(EXIT_AUTH_ERROR)
Copy link

Copilot AI Apr 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copilot uses AI. Check for mistakes.
Comment thread docs/en/super-agent.md
> 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`).
Copy link

Copilot AI Apr 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)”).

Suggested change
> surfaces as exit code `3` (`AccessDenied`).
> surfaces as exit code `3` (authentication/permission error).

Copilot uses AI. Check for mistakes.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants