test-action 仓库 README 编写规范
本文档定义
test-action仓库下所有子插件 README 的强制结构、章节顺序、必填元素与可选元素，供插件作者与文档维护者参考。平台定位：本仓库所有 Action 运行于 GitCode Actions。规范以 GitCode 平台的官方文档与本仓库的实践为主，GitHub Actions 作为风格参考。
GitCode 平台关键约束（贯穿全文，证据见附录 A）：
- 运行时仅支持
node16；- 平台内置变量为
ATOMGIT_*系列（无GITHUB_*）；- 事件上下文前缀为
atomgit.*（无github.*）；- 步骤摘要写入
$ATOMGIT_STEP_SUMMARY（未设置时回退控制台）；- OIDC 联邦需显式声明
permissions: id-token: write。版本：v1.0 — 初始版本。
1. 适用范围
- 强制：仓库根
README.md下所有<plugin>/README.md。 - 建议：
workflow-example/*.yml等示例文件保持与本规范一致的注释风格。 - 非适用：根
README.md本身（属"总览文档"，按其现有结构维护）。
2. 模板总览（GitCode 视角）
每个插件 README 须按以下章节顺序编写（章节标题统一使用中文 + 英文括注双语）：
# <plugin-name>
<!-- 一句话 slogan（HTML 注释保留可机器解析的简介） -->
<一句话 slogan>
<!-- Badges 区（GitCode Marketplace 风格） -->
---
## 核心特性 (Features)
## 快速上手 (Quick Start)
## 输入参数 (Inputs)
## 输出参数 (Outputs)
## 如何使用输出参数（可选）
## 权限要求 (Permissions)
## 贡献与本地调试 (Contributing & Debugging)
## 开源协议 (License)
固定 7 个常驻章节（核心特性 / 快速上手 / 输入参数 / 输出参数 / 权限要求 / 贡献与本地调试 / 开源协议）；如何使用输出参数 为条件推荐章节（有输出时出现）；其他可选章节（前置条件 / 使用约束 / 环境变量依赖 / 上下游串联 / 最新动态）按需插入到合理位置。其中最新动态 (What's New) 须放在 Badges 区之后、## 核心特性 之前。
编辑语言：
章节标题：统一使用简体中文 + 英文括注双语
章节内容：使用简体中文
3. 章节定义
3.1 标题（必填）
- 标题文本 = 插件目录名，一字不差（小写、连字符）。
- 仅 1 级标题，不带版本号、不带 Emoji。
3.2 Slogan 与 HTML 注释（必填）
-
顶部用 HTML 注释包住一句话 slogan，便于机器解析：
<!-- 简短的一句话介绍该 Action 的核心功能 --> 一个用于在 pytest 流水线中<动词><做什么>的 GitCode Actions 插件。 -
slogan 要求：动词开头；以 "GitCode Actions 插件" 结尾（明确平台归属）。
3.3 Badges 区（推荐）
-
用 HTML 注释引导，紧跟 slogan 之后：
<!-- 放置 GitCode Marketplace / CI 专属的 Badges --> [](https://gitcode.com) [](https://gitcode.com) -
须使用 Markdown 链接语法 +
shields.io风格徽章。 -
Badges 链接域名推荐
gitcode.com，与平台归属一致。 -
至少 1 个 Badge；推荐 2 个（Marketplace + CI）。
-
Badges 与下一章节之间用
---分隔。
3.4 核心特性 (Features)（必填）
- 使用 项目符号列表，每条特性独立一行。
- 每条特性以
* **加粗关键词**：展开说明开头。 - 推荐 3–5 条；按"自动化程度 → 可定制 → 性能/安全 → 平台兼容"排列。
- 必须明确：
- 运行时：
node16（GitCode 平台限制）。 uses路径：<owner>/<repo>/<plugin-dir>@<tag>（下文示例使用@v1.0.0示例，请按最新标签替换）。
- 运行时：
3.4.1 GitCode 平台专属声明（必填）
独立一条 Feature，必须包含：
- **GitCode 原生**：运行于 [GitCode Actions](https://docs.gitcode.com/docs/help/home/org_project/pipeline/writing-pipelines/)，使用 `ATOMGIT_*` 环境变量、`atomgit.*` 上下文与 `$ATOMGIT_STEP_SUMMARY`，遵循 GitCode 平台约束。
3.4.2 推荐补充特性（按插件特性选填）
- OBS 集成（适用时）：通过
@openlibing/huaweicloud-oidc-clientSDK 完成 OIDC 联邦认证。 - GitCode PR 联动（适用时）：通过
${{ atomgit.repository }}#${{ atomgit.event.pull_request.number }}获取 PR 上下文。 - Python wheel 内嵌（适用时）：在 Node 运行时内下载并安装 Python wheel，避免依赖 Docker/Python 运行时。
3.5 快速上手 (Quick Start)（必填）
- 段落开头用一句话说明使用步骤，明确告诉用户在哪个路径创建哪个文件。
- 推荐路径：
.gitcode/workflows/。 - 必须先
actions/checkout再调用本插件（保持官方示例顺序）。 - yaml 代码块须可直接复制运行：变量、缩进、引号、tag 一致。
- 敏感值用
${{ secrets.* }}占位，禁止写真实密钥。 - 推荐 1–2 个示例：
- 最小可运行示例：只用本插件自身参数。
- 典型场景示例：与上下游插件串联（推荐串联本仓库其他 Action）。
3.6 输入参数 (Inputs)（必填）
Markdown 表格，4 列：
| 参数名称 | 是否必填 | 默认值 | 描述说明 |
|---|---|---|---|
<input-name> |
是 / 否 | <default> 或 无 |
一句话 + 校验规则摘要 |
约束：
- 参数名使用反引号包裹。
- 是否必填列用
:---:居中；必填时加粗为**是**。 - 默认值列：必填参数无默认值时填
无。 - 描述列：含数据类型（如"正整数""JSON 字符串"）、取值范围/枚举、长度上限、协议要求（如"HTTPS"）。
3.7 输出参数 (Outputs)（必填）
Markdown 表格，3 列（含类型列）：
| 输出名称 | 类型 | 描述说明 |
|---|---|---|
<output-name> |
<type> |
一句话 + 数据来源（如"取自 output.json 的 TestCaseOBSUrl"） |
类型列可选值：string / number / boolean / object / array。
无输出时保留表头并填"无"。
3.8 如何使用输出参数（可选，有输出时推荐）
- 单独的二级或三级子节。
- 必须演示：
- 调用插件时指定
id: <step-id>。 - 后续 Step 通过
${{ steps.<step-id>.outputs.<output-name> }}引用。
- 调用插件时指定
- 标题示例：
### 如何使用输出参数示例。
3.9 权限要求 (Permissions)（条件必填）
-
触发条件：插件依赖 OIDC 联邦、推送代码、读写 Release 等特权操作。
-
必须以独立
##章节出现，不与"前置条件"混用。 -
必须包含
permissions:代码块，逐条注释每个权限的作用：permissions: contents: write # 需要写入 Release 信息 pull-requests: read id-token: write # 必须声明此权限，否则无法申请 GitCode OIDC ID Token -
GitCode 上必须显式声明
id-token: write才能使用 OIDC。
3.10 贡献与本地调试 (Contributing & Debugging)（推荐）
-
段落引导本地修改/调试步骤。
-
必须包含 Node.js Action 打包要点：
1. 克隆仓库并安装依赖：`npm install` 2. 打包生成分发文件：`npm run bundle`（确保 `dist/index.js` 被正确打包） 3. 提交 PR 前请确保通过本地测试。 -
Python wheel 插件可补充虚拟环境与 wheel 构建步骤。
-
推荐在此章节说明 提交 PR 前应通过的检查（链接到 §7 CI 校验）。
3.10.1 GitCode 平台特性验证清单（提 PR 前）
本地调试通过不等于平台可用，须在真实 GitCode 流水线上验证以下平台专属能力：
3.11 开源协议 (License)（可选但推荐）
-
开源仓库强烈建议声明：
## 开源协议 (License) [MIT](LICENSE) © [你的名字 / 你的组织] -
链接到仓库根
LICENSE文件或上游许可证。
4. 可选章节
下列章节按需插入到合适位置；不在 §2 主链中，但允许扩展。
4.1 前置条件
- 触发条件：插件依赖外部服务（OBS、调度器、APIG 网关）且不涉及权限声明。
- 每条前置条件单列，加
**加粗关键词**前缀。 - 若涉及
permissions:声明，改用 §3.9 权限要求章节。
4.2 使用约束
- 触发条件：有校验/安全/平台约束（路径安全、网络白名单、文件名规则、并发覆盖、镜像源）。
- 每条独立一行，便于自动化校验脚本解析。
- 推荐格式：
- **<类别>**：<具体约束>。
4.3 环境变量依赖（GitCode 视角）
- 触发条件：依赖 GitCode 内置变量（
ATOMGIT_*、$ATOMGIT_STEP_SUMMARY）或插件自定义环境变量（如通过secrets.*注入的GITCODE_TOKEN）。 - Markdown 列表：
<VARIABLE_NAME>（必需/可选）：<用途> + 缺失时行为。 - 已在 §3.4.1 GitCode 平台专属声明 中声明过的变量，此处可省略，避免重复。
- 列出平台变量时使用 GitCode 命名（如
ATOMGIT_JOB_RUN_ID）。
4.4 上下游串联
- 触发条件：与其他插件/平台强耦合时出现。
- 简短段落 + 列表：
- 上游：
<plugin>如何衔接（引用哪个 output）。 - 下游：
<plugin>如何衔接（提供哪个 input）。
- 上游：
- 推荐串联本仓库其他 Action（如
pytest-orch→test-result-display、metadata-collect→upload-reports）。
4.5 最新动态 (What's New)
-
触发条件：当前大版本有用户可见的新特性或不向后兼容的变更时出现。
-
位置：放在 Badges 区之后、
## 核心特性之前（参考actions/checkout/setup-node/cache）。 -
内容聚焦当前大版本，不罗列完整历史（完整 release notes 放 GitCode Releases）：
## 最新动态 (What's New) **v<X.Y>** — <一句话概述该版本重点>： - <用户可见的新特性或破坏性变更 1> - <用户可见的新特性或破坏性变更 2> > [!IMPORTANT] > <若有破坏性变更，在此醒目提示用户需要做的适配动作> -
仅记录用户可见的新特性与破坏性变更；不记录 bugfix / 重构 / 内部依赖升级。
-
破坏性变更须用
> [!IMPORTANT]提示块醒目标出，并说明用户需要的适配动作。
5. 章节必要性矩阵
| 章节 | 是否必填 | 触发条件 |
|---|---|---|
| 标题 + slogan + HTML 注释 | 必填 | — |
| Badges 区 | 推荐 | — |
| 核心特性 (Features) | 必填 | — |
| 快速上手 (Quick Start) | 必填 | — |
| 输入参数 (Inputs) | 必填 | — |
| 输出参数 (Outputs) | 必填 | — |
| 如何使用输出参数 | 推荐 | 有输出时 |
| 权限要求 (Permissions) | 条件必填 | 涉及权限/OIDC |
| 贡献与本地调试 (Contributing & Debugging) | 推荐 | — |
| 开源协议 (License) | 可选 | 开源仓库推荐 |
| 前置条件 | 条件必填 | 外部依赖（非权限） |
| 使用约束 | 条件必填 | 有校验/安全/平台约束 |
| 环境变量依赖 | 条件必填 | 依赖 GitCode 内置变量 |
| 上下游串联 | 条件必填 | 与其他插件强耦合 |
| 最新动态 (What's New) | 条件必填 | 当前大版本有新特性/破坏性变更（位于核心特性之前） |
6. README 自检清单
7. 自动化校验建议（Roadmap）
建议在 CI 中加入以下检查：
markdown-link-check：校验所有内部链接可达。markdownlint：校验标题层级、代码块、表格格式。- README 结构 lint（自研）：解析
##章节顺序，匹配本规范 §2 的模板顺序。 - HTML 注释 lint：确保每个 README 顶部存在
<!-- slogan -->注释。 - Emoji 前缀 lint：确保每个
##章节标题不含 Emoji 前缀（与本规范 §2 模板一致）。 uses:tag 检查：禁止示例中出现过期 tag。- GitCode 命名 lint（关键）：扫描 README，禁止出现
github.*/GITHUB_TOKEN/$GITHUB_STEP_SUMMARY等 GitHub 专属标识，强制使用ATOMGIT_*/atomgit.*。 - OIDC 权限 lint：若插件用到 OBS / 外部凭证上传，README 的"权限要求"章节必须说明需要用户在工作流（
.gitcode/workflows/*.yml）中配置permissions:代码块并声明id-token: write。
8. 模板示例（可直接复制）
# <plugin-name>
<!-- 简短的一句话介绍该 Action 的核心功能 -->
一个用于在 pytest 流水线中<动词><做什么>的 GitCode Actions 插件。
<!-- 放置 GitCode Marketplace / CI 专属的 Badges -->
[](https://gitcode.com)
[](https://gitcode.com)
---
## 最新动态 (What's New)
**v<X.Y>** — <一句话概述该版本重点>：
- <用户可见的新特性或破坏性变更 1>
- <用户可见的新特性或破坏性变更 2>
> [!IMPORTANT]
> <若有破坏性变更，在此醒目提示用户需要做的适配动作>
## 核心特性 (Features)
- **全自动运行**：基于 Commit 自动归类变更，无需手动干预。
- **高可定制性**：支持自定义模板、标签过滤。
- **轻量快速**：基于 Node.js 构建，秒级完成执行。
- **GitCode 原生**：运行于 [GitCode Actions](https://docs.gitcode.com/docs/help/home/org_project/pipeline/writing-pipelines/)，使用 `ATOMGIT_*` 环境变量、`atomgit.*` 上下文与 `$ATOMGIT_STEP_SUMMARY`，遵循 GitCode 平台约束。
## 快速上手 (Quick Start)
在你的项目的 `.gitcode/workflows/` 目录下创建一个 `.yml` 文件，并添加以下配置：
```yaml
name: Run Plugin
on:
push:
branches:
- main
jobs:
build:
runs-on: ubuntu-latest
steps:
# Step 1: 必须先拉取你的代码仓库
- name: Checkout code
uses: actions/checkout@v4
# Step 2: 使用本 Action
- name: Run Plugin Action
uses: <owner>/<repo>/<plugin-dir>@v1.0.0
with:
<input-name>: <value>
```
输入参数 (Inputs)
| 参数名称 | 是否必填 | 默认值 | 描述说明 |
|---|---|---|---|
<input-name> |
是 | 无 | 用于调用 的权限 Token，通常传入 ${{ secrets.<SECRET_NAME> }}。 |
<input-optional> |
否 | '<default>' |
自定义配置文件的存放路径。 |
输出参数 (Outputs)
| 输出名称 | 类型 | 描述说明 |
|---|---|---|
<output-name> |
string |
最终生成的版本号（例如 v1.2.3）。 |
如何使用输出参数示例：
- name: Run Plugin Action
id: plugin # 注意：这里必须指定 id
uses: <owner>/<repo>/<plugin-dir>@v1.0.0
- name: Send Notification
run: echo "结果 ${{ steps.plugin.outputs.<output-name> }} 已就绪！"
权限要求 (Permissions)
为了让此 Action 正常工作，流水线需要具备以下权限：
permissions:
contents: read # 需要读取仓库内容
id-token: write # 必须声明此权限，否则无法申请 GitCode OIDC ID Token
贡献与本地调试 (Contributing & Debugging)
如果你想本地修改或调试这个 Action：
- 克隆仓库并安装依赖：
npm install - 打包生成分发文件：
npm run bundle（确保dist/index.js被正确打包） - 提交 PR 前请确保通过本地测试，并按仓库 CI 配置完成自动化校验（含 GitCode 命名 lint）。
开源协议 (License)
MIT © [你的名字 / 你的组织]
---
## 9. 变更记录
| 版本 | 日期 | 变更 |
| ---- | --- | ---------------- |
| v1.0 | — | 建立插件 README 编写规范 |
---
# 附录 A：参考链接
> 本附录集中罗列规范中引用的外部文档与典型示例。所有外部链接作为**兼容性参考**，不替代本规范；所有 GitCode 平台字段以本仓库 README 实证为准。
## A.1 GitCode Actions 官方文档
| 主题 | 链接 |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| AtomGit Action 产品总览 | https://docs.gitcode.com/docs/help/home/org_project/pipeline/overview/ |
| 工作流文件位置与 YAML 基本结构 | https://docs.gitcode.com/docs/help/home/org_project/pipeline/writing-pipelines/workflow-file-location-structure/ |
| 插件运行时环境变量 | https://docs.gitcode.com/docs/help/home/org_project/pipeline/action-development/runtime-environment-variables |
| 变量、密钥、上下文与表达式 | https://docs.gitcode.com/docs/help/home/org_project/pipeline/core-concepts/variables-secrets-context-expressions |
| Token 权限与最小授权（含 `permissions`） | https://docs.gitcode.com/docs/help/home/org_project/pipeline/security-permissions/token-permissions |
| 插件打包与发布 | https://docs.gitcode.com/docs/help/home/org_project/pipeline/action-development/plugin-packaging |
## A.2 GitHub Actions 参考文档
> 仅作为字段命名、章节风格、`action.yml` 元数据语义的参考。**本仓库不依赖 GitHub 平台能力**。
| 主题 | 链接 |
| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| GitHub Actions 总览 | https://docs.github.com/en/actions |
| Metadata syntax for GitHub Actions（`action.yml` 字段定义） | https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions |
| 创建 JavaScript Action（含 README 章节要求） | https://docs.github.com/en/actions/creating-actions/creating-a-javascript-action |
| `README.md` 在 Marketplace 的渲染要求 | https://docs.github.com/en/actions/sharing-automations/creating-actions/publishing-actions-in-github-marketplace |
| 典型示例：`actions/checkout` README | https://github.com/actions/checkout/blob/main/README.md |
| 典型示例：`actions/setup-node` README | https://github.com/actions/setup-node/blob/main/README.md |
| 典型示例：`actions/cache` README | https://github.com/actions/cache/blob/main/README.md |
| 典型示例：`actions/labeler` README | https://github.com/actions/labeler/blob/main/README.md |
| 典型示例：`github/codeql-action` README | https://github.com/github/codeql-action/blob/main/README.md |