# @atomist/automation-client 中文文档 规范地址：https://npmcn.com/package/%40atomist/automation-client/ 版本：1\.8\.3-1\.8-fixes\.20230418232200 npm 元数据更新时间：2023-04-18T21:23:05.114Z 中文译文更新时间：2026-11-07T03:36:40.517Z 软件包许可：SEE LICENSE IN LICENSE 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40atomist/automation-client 原文对照：https://npmcn.com/package/%40atomist/automation-client/?lang=original 项目主页：https://github.com/atomist/automation-client#readme 源码仓库：https://github.com/atomist/automation-client ## 关键信息（来自 npm 元数据） - 包体积（解压后）：4.6 MB，1040 个文件 - 模块格式：CommonJS - TypeScript 类型：包内自带 - Node.js 要求：\>=8\.2\.0 - 运行依赖：106 个 - 首次发布：2017-09-19T13:49:17.245Z - 最新版本发布：2023-04-18T21:23:04.893Z - 近 30 天下载量：10188（2026-10-07 至 2026-11-05，npm 官方下载统计） - 已发布版本数：1350（近 12 个月 0 个） ## 中文简介 用于软件低级客户端的原子论 API ## 安装 ```sh npm install @atomist/automation-client ``` 也可以使用：`pnpm add @atomist/automation-client`、`yarn add @atomist/automation-client`、`bun add @atomist/automation-client` ## README # @atomist/automation-客户端 [![atomist sdm goals](http://badge.atomist.com/T29E48P34/atomist/automation-client-ts/bdaca35b-0cb1-4fbf-8596-a27777b46974)](https://app.atomist.com/workspace/T29E48P34) [![npm version](https://img.shields.io/npm/v/@atomist/automation-client.svg)](https://www.npmjs.com/package/@atomist/automation-client) [节点](https://nodejs.org/ "Node.js") 模块 [`@atomist/automation-client`](https://www.npmjs.com/package/@atomist/automation-client) 用于创建原子主义开发自动化。 开发自动化采取以下形式: - Bot 命令 - 使用 _命令处理器_ - 对事件的反应 - 使用 _事件处理器_ 自动 当事情发生时采取行动 就像有人评论一个问题, 发生 - Ingestors - 定义您自己的自定义事件,然后可以接受 行动 自动化客户端提供运行客户端的能力 连接到 Atomist API 以便它能够接收命令并按命令行事 事件. 见 [原子论.com](https://atomist.com/ "Atomist - Development Automation") 财务报告和审定财务报表 [docs.atomist.com (中文(中国大陆) )](https://docs.atomist.com/ "Atomist Documentation") 为了更多 详细信息. ## 概念 Atomist是一种服务和API,它能够实现开发自动化. 这个 原子学服务建立并维持一个重要事物的模型 给您的开发团队。 然后可以使用出箱自动化 或者用这个模型来建造自己的自动化设备. 更多信息请改为 [概念](https://npmcn.com/package/%40atomist/automation-client/docs/Concepts.md)。 。 。 . ## 开始 请安装 [节点.js](https://nodejs.org/ "Node.js")。验证正确的版本是 已安装, 请运行 : ``` $ node -v v8.4.0 $ npm -v 5.4.1 ``` ### 使用 `automation-client` 模块 要开始在您的 Node.js 应用程序中使用此模块, 您必须在其中添加一个依赖性 `package.json` 运行以下命令: ``` $ npm install @atomist/automation-client --save ``` 您可以在 [https://atomist.github.io/automation-client-ts/ 页面存档备份,存于互联网档案馆](https://atomist.github.io/automation-client-ts/) 。 。 。 . ### 从样本开始 我们还提供一个工作项目,提供一些基本的自动化设备,可以用来快速启动. 存储器 处于 [原子学家/自溶-种子](https://github.com/atomist/automation-seed-ts)。 。 。 . 要开始运行以下命令: ``` $ git clone git@github.com:atomist/automation-seed-ts.git $ cd automation-seed-ts $ npm install ``` 见 [自动种子 Ts 读取](https://github.com/atomist/automation-seed-ts#readme) 为进一步 说明. ## 执行自动化 ### 命令处理器 命令是可以通过Chat bot,卷曲或网络接口被引用的自动化. 要创建命令,请查看以下实例: ```typescript import { CommandHandler, Parameter} from "@atomist/automation-client/decorators"; import { HandleCommand, HandlerContext, HandlerResult } from "@atomist/automation-client/Handlers"; @CommandHandler("Sends a hello back to the client", "hello world") // ^ -- defines the command to trigger // " this handler from the bot export class HelloWorld implements HandleCommand { // ^ -- a command handler implements the HandleCommand // interface @Parameter({ pattern: /^.*$/, required: true }) // ^ ^ ^ -- parameters can be marked required or optional // ^ ^ -- the parameter can be validated against a RegExp pattern // ^ -- this defines a user-provided parameter named 'name' public name: string; public handle(ctx: HandlerContext): Promise { // ^ ^ -- HandlerContext provides access to a 'MessageClient' for sending // ^ messages to the bot as well as a 'GraphClient' to query your // ^ data using GraphQL // ^ -- this method is the body of the handler and where the actual code goes return ctx.messageClient.respond(`Hello ${this.name}`) // ^ -- Calling 'respond' on the 'MessageClient' will // send a message back to wherever that command // is invoked from (eg. a DM with @atomist in Slack) .then(() => { return Promise.resolve({ code: 0 }); // ^ -- Command handlers are expected to return a // 'Promise' of type 'HandlerResult' which // just defines a return code. Nonzero // return codes indicate errors. }); } } ``` 上述宣布一个简单的机器人命令,可以通过 `@atomist hello world`。命令需要一个 调用参数 `name`。处理器将发出简单的问候信息. 详情请参见 [命令处理器](https://npmcn.com/package/%40atomist/automation-client/docs/CommandHandlers.md)。 。 。 . ### 事件处理器 事件处理器是允许根据已注册的GraphQL订阅处理事件的自动化设备. 要创建事件处理器,请查看以下实例: ```typescript import { EventFired, EventHandler, HandleEvent, HandlerContext, HandlerResult } from "@atomist/automation-client/Handlers"; @EventHandler("Notify channel on new issue", `subscription HelloIssue { Issue { number title repo { channels { name } } } }`) // ^ -- This is GraphQL subscription you want // to match to trigger your handler. // Queries can also be externalized. export class HelloIssue implements HandleEvent { // ^ -- an event handler implements the 'HandleEvent' // interface public handle(e: EventFired, ctx: HandlerContext): Promise { // ^ ^ -- 'HandlerContext' gives access to // ^ 'MessageClient' and 'GraphClient' // ^ -- 'EventFired' gives you access to the data that matched the // subscription. Since GraphQL queries return JSON it is very easy // to work with the data in JavaScript/TypeScript return Promise.all(e.data.Issue.map(i => ctx.messageClient.addressChannels(`Got a new issue \`${i.number}# ${i.title}\``, // ^ -- besides responding, you can address users and // channels in Slack by using the respective methods // on 'MessageClient' i.repo.channels.map(c => c.name)))) // ^ -- in our correlated data model, repositories can be mapped to // channels in a chat team. This will effectively send a message // into each mapped channel .then(() => { return Promise.resolve({ code: 0 }); // ^ -- Event handlers are expected to return a // 'HandlerResult'. Nonzero code indicate // error occurred }); } } ``` 此事件处理器注册 GraphQL 订阅 `Issue` 类型。 打开 `Issue` 处理器将发生的事件 向关联的懒人团队发送简单信息. 详情请参见 [事件处理器](https://npmcn.com/package/%40atomist/automation-client/docs/EventHandlers.md)。 。 。 . ### 登记处理器 为了在自动化客户端注册您的处理器, 请创建一个名为“ 自动化客户端” 的文件 `atomist.config.ts` 设置 内容如下: ```typescript import { Configuration } from "@atomist/automation-client/configuration"; import { HelloWorld } from "./commands/HelloWorld"; import { HelloIssue } from "./events/HelloIssue"; export const configuration: Configuration = { // ^ -- 'Configuration' defines all configuration options name: "your_module_name", // ^ -- each automation-client should have a unique name version: "0.0.1", // ^ -- and a semver version teamIds: ["T29E48P34"], // ^ -- the ids of your chat teams which you can get by running '@atomist pwd' // leave empty to use your user defaults saved by atomist-config commands: [ // ^ -- register all your command handlers () => new HelloWorld(), ], events: [ () => new HelloIssue(), ], // ^ -- the same for event handlers token: process.env.GITHUB_TOKEN || "34563sdf......................wq455eze", // ^ -- configure a GitHub personal access token with read:org scope; this is used to // authenticate the automation-client with Atomist to make sure the client should // be granted access to the ingested data and chat team; leave null/undefined // to use your user default saved by atomist-config }; ``` 此文件允许您注册您的处理器, 并为您的自动化客户指定名称和版本 . ## 运行自动化客户端 有几种方式可以运行您的自动化客户端,并让它连接到Atomist API. ### 本地运行 要在当地启动客户端 并让客户端听 即将到来的事件,只是运行: ``` $ atomist start ``` ### 推向云铸 准备您的自动化客户端运行于任何 Cloud Foundry 请确保您有关于 云铸造厂和你有 云铸造厂CLI, 配置和登录 . 首先,你需要创建一个 `manifest.yml` 在您的节点根中 项目。 将以下最小内容放入文件 : ``` applications: - name: YOUR_APP_NAME command: $(npm bin)/atomist-client memory: 128M buildpack: https://github.com/cloudfoundry/nodejs-buildpack env: GITHUB_TOKEN: SUPPRESS_NO_CONFIG_WARNING: true ``` 有其他推荐的方法 让你的 `GITHUB_TOKEN` 输入您的自动化客户实例 . 看看这个 [`cfenv`](https://www.npmjs.com/package/cfenv) 比如说 下一个请添加 `"engines"` 顶级条目 `package.json` 类似如下: ```javascript "engines": { "node": "8.x.x", "npm": "5.x.x" } ``` 现在你准备好 `cf push` 您的自动化服务器到 Cloud Foundry : ``` $ cf push ``` ## REST APIs 软件 当开始的时候 `automation-client` 暴露出一些可以通过HTTP访问的端点. ### 认证 端点由HTTP Basic Auth或以符号为基础的认证保护. 启动客户端时,你会看到 下列格式的日志消息: ``` 2017-09-20T08:22:32.789Z - info : Auto-generated credentials for web endpoints are user 'admin' and password '4d6390d1-de5c-6764-a078-7308503ddba5' ``` 默认情况下,自动化客户端自动生成一些您使用的证书 。 要配置您的证书, 请更改 `atomist.config.ts` 并将以下一节列入: ```typescript export const configuration: Configuration = { ... http: { enabled: true, auth: { basic: { enabled: true, username: "some user", password: "some password", }, }, }, }; ``` ### 终点 #### 获取管理端点 | 路径 | 说明 | | --- | --- | | `/metrics` | 披露指挥、事件处理者处决的衡量标准 | | `/health` | 显示自动化客户端健康信息的端点 | | `/registration` | 所有可用的自动化元数据 | | `/info` | 披露关于此自动化客户端的信息 | | `/log/commands` | 运行命令处理器的所有请求 | | `/log/events` | 事件处理者的所有新事件 | | `/log/messages` | 所有由处理器发送的信件 | 举例来说,这里有一个命令来获取当前衡量标准: ``` $ curl -X GET \ http://localhost:2866/metrics \ -H 'authorization: Bearer 34563sdf......................wq455eze"' \ -H 'content-type: application/json' ``` 上述端点均为HTTP GET并每次默认获取无记名和基本认证. 详情见下文: 认证. #### 引用命令处理器 可通过具有下列有效载荷的HTTP POST来援引指令处理器: ``` $ curl -X POST \ http://localhost:2866/command \ -H 'content-type: application/json' \ -H 'authorization: Bearer 34563sdf......................wq455eze"' -d '{ "parameters": [{ "name": "name", "value": "cd" }], "mapped_parameters": [{ "name": "sender", "value": "kipz" },{ "name": "userName", "value": "cd" }], "secrets": [{ "uri": "github://user_token?scopes=repo", "value":"4...d" }], "command": "HelloWorld", "correlation_id": "6cb72bf7-77b4-4939-b892-00000701fa53", "team": { "id": "T1L0VDKJP", "name": "Atomist QA" }, "api_version": "1" }' ``` ## 支助 一般性支持问题应在缔约方会议 `#support` 我们社区Slack团队的频道 时间 [原子主义-社区. slack.com](https://join.atomist.com/ "Atomist Community Slack")。 。 。 . 如果你发现问题,请创建 [问题](https://github.com/atomist/automation-client-ts/issues)。 。 。 . ## 发展 您需要安装 [节点](https://nodejs.org/ "Node.js") 建造和测试这个项目. 要运行测试, 请将 GITHUB TOKEN 定义为任何可重传访问的有效符号 。 测试 将创建和删除仓库. 定义 GITHUB VISibility = public,如果您想要这些是公开的;默认是私有的. 如果你不支付私人的回购,就会得到422的回放. ### 构建和测试 | 命令 | 原因 | | --- | --- | | `npm install` | 安装所有需要的软件包 | | `npm run build` | 插入、编译和测试 | | `npm start` | 启动原子主义自动化客户端 | | `npm run autostart` | 运行客户端, 当文件更改时刷新 | | `npm run lint` | 运行 tslint 对 TypeScript | | `npm run compile` | 将全部类型脚本编译为 JavaScript | | `npm test` | 运行测试,确保一切正常运行 | | `npm run autotest` | 持续运行测试 | | `npm run clean` | 删除已编译的 JavaScript 文件并构建目录 | ### 释放 为了创造项目的新发布,我们按下原子主义生命周期消息的按钮 在 #自定义客户端- ts [频道](https://atomist-community.slack.com/messages/C74J6MFL0/) 在原子主义社区Slack. * * * 创建于 [原子学家](https://atomist.com/ "Atomist - Development Automation")。 。 。 . 需要帮忙吗? [加入我们的黑队](https://join.atomist.com/ "Atomist Community Slack")。 。 。 . ## 常见问题 ### @atomist/automation-client 是什么？ 用于软件低级客户端的原子论 API ### 如何安装 @atomist/automation-client？ 在项目目录运行 npm install @atomist/automation-client，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 atm-command、atm-git-info、atm-gql-gen、atm-start、atm-start-dev，可以用 npx atm-command 直接运行。 ### @atomist/automation-client 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @atomist/automation-client 支持 ESM 还是 CommonJS？ 以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。 ### @atomist/automation-client 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=8\.2\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @atomist/automation-client 可以商用吗？ @atomist/automation-client 使用 SEE LICENSE IN LICENSE 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。 ### @atomist/automation-client 的下载量有多少？ 根据 npm 官方下载统计，@atomist/automation-client 在 2026/10/07 – 2026/11/05 这 30 天内被下载 10,188 次，日均约 340 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @atomist/automation-client 还在维护吗？ 最新版本 1\.8\.3-1\.8-fixes\.20230418232200 发布于 2023/04/19（3 年前）；至今共发布 1350 个版本，其中过去 12 个月发布了 0 个；首次发布于 2017/09/19。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。