@skylandnpm/octopus-cli

v0.0.20

Published

a month ago

Octopus CLI 是一个命令行工具，用于与 Octopus Mission 任务管理系统进行交互。通过 CLI，您可以方便地管理任务、待办事项和附件，支持多账号配置和自动化脚本集成。

0High
0Medium
0Low

mdcoder716

mutemoon-owner

Octopus CLI 使用说明

简介

多智能体协作说明：CLI 不支持默认账号，每条命令均需通过 --email 明确指定操作账号，以避免多个智能体并发使用时出现账号混淆。

安装

全局安装

npm install @skylandnpm/octopus-cli@latest -g --registry https://registry.npmjs.org

安装完成后，可以使用 octopus 命令。

验证安装

octopus --version

快速开始

1. 配置服务器地址

octopus config set baseUrl https://octopus.wuyehao.com

2. 添加账号

octopus account add [email protected] pat_37PCnF1H-rS1tyBbbFJRIx9qGugHOdOKSE5qFM-_s28

3. 查看配置

octopus config get

4. 获取任务列表

octopus tasks list --project-no 7 --email [email protected]

命令参考

配置管理 (config)

查看配置

octopus config get

显示当前配置的服务器地址和账号列表。

设置服务器地址

octopus config set baseUrl https://octopus.wuyehao.com

删除服务器地址

octopus config delete baseUrl

配置文件

CLI 的配置保存在 ~/.octopus/settings.json，格式如下：

{
  "baseUrl": "https://octopus.wuyehao.com",
  "accounts": [
    {
      "email": "[email protected]",
      "accessToken": "pat_37PCnF1H-rS1tyBbbFJRIx9qGugHOdOKSE5qFM-_s28"
    }
  ]
}

账号管理 (account)

添加账号

octopus account add <email> <accessToken>

如果添加的邮箱已存在，会更新该账号的 token。

移除账号

octopus account remove <email>

项目管理 (projects)

获取项目列表

octopus projects list --email <email>

返回项目编号、项目名称和状态信息。

任务管理 (tasks)

获取任务列表

octopus tasks list --project-no <number> --email <email> [选项]

可选参数：

--status <status> - 任务状态筛选：not_started, in_progress, completed, error, closed

# 获取项目7的所有任务
octopus tasks list --project-no 7 --email [email protected]

# 获取项目7中状态为进行中的任务
octopus tasks list --project-no 7 --email [email protected] --status in_progress

获取任务详情

octopus tasks detail --project-no <number> --task-no <number> [--email <email>]

返回任务详情及附件列表。响应包含 task（任务对象）和 attachments（附件数组）两个字段。

开始任务

octopus tasks start --project-no <number> --task-no <number> --email <email> [--remark <remark>]

完成任务

octopus tasks complete --project-no <number> --task-no <number> --email <email> [--remark <remark>] [--minutes-spent <minutes>]

可选参数：

--remark <remark> - 完成说明
--minutes-spent <minutes> - 本次消耗工时（分钟）

# 完成任务，记录工时120分钟
octopus tasks complete --project-no 7 --task-no 123 --email [email protected] --remark "任务已完成" --minutes-spent 120

标记任务异常

octopus tasks error --project-no <number> --task-no <number> --email <email> --remark <remark>

关闭任务

octopus tasks close --project-no <number> --task-no <number> --email <email> --reason <reason>

关闭任务会将任务状态变更为 closed，已关闭的任务不能再次变更状态。

激活任务

octopus tasks activate --project-no <number> --task-no <number> --email <email> [--remark <remark>]

将未开始的任务状态变为进行中。

任务改派（修改负责人）

octopus tasks reassign --project-no <number> --task-no <number> --email <email> --new-assignee-email <newAssigneeEmail> [--remark <remark>] [--minutes-spent <minutes>]

权限说明： 只有当前任务的负责人或项目管理员才能执行改派操作。

添加任务备注

octopus tasks comment --project-no <number> --task-no <number> --email <email> --remark <remark>

获取任务附件列表

octopus tasks attachments --project-no <number> --task-no <number> --email <email>

创建任务（项目管理员）

octopus tasks create --project-no <number> --email <email> --title <title> [--description <description>] [--task-type <taskType>] [--priority <priority>] [--assignee-email <assigneeEmail>] [--estimated-minutes <minutes>]

任务类型： requirement, design, development, testing, implementation, document, research, presale, bugfix, other

优先级： high, medium, low

权限说明： 只有项目管理员才能创建任务。

# 创建一个开发任务
octopus tasks create \
  --project-no 7 \
  --email [email protected] \
  --title "实现用户登录功能" \
  --description "实现JWT用户登录功能" \
  --task-type development \
  --priority high \
  --assignee-email [email protected] \
  --estimated-minutes 120

上传任务附件

octopus tasks upload-attachment --project-no <number> --task-no <number> --file <path> [--title <title>] --email <email>

权限说明： 只有任务创建人才能上传附件。

获取任务流水记录

octopus tasks showlog --project-no <number> --task-no <number> --email <email>

待办管理 (todos)

获取待处理待办列表（执行者视角）

octopus todos pending --project-no <number> --email <email>

获取待审批待办列表（项目管理员视角）

查询项目中所有待批准（pending）的待办事项，需要项目管理员权限。

octopus todos pending-approval --project-no <number> --email <email>

批准待办事项（项目管理员）

将指定待办事项从 pending 状态变更为 approved，需要项目管理员权限。

octopus todos approve --project-no <number> --todo-id <todoId> --email <email> [--remark <remark>]

获取已批准待办列表

octopus todos approved --project-no <number> --email <email> [--status <status>]

状态筛选： pending, approved, completed, failed, suspended, closed

# 获取所有已批准待办
octopus todos approved --project-no 7 --email [email protected]

# 获取已完成的待办
octopus todos approved --project-no 7 --email [email protected] --status completed

创建待办

octopus todos create --project-no <number> --task-no <number> --email <email> --title <title> [--description <description>] [--ref-task <taskNo>] [--ref-todo <todoId>]

可选参数：

--ref-task <taskNo> - 引用的任务编号（可多次指定，用于建立上下文关联）
--ref-todo <todoId> - 引用的待办事项ID（可多次指定，用于建立上下文关联）

引用上下文说明： 通过 --ref-task 和 --ref-todo 参数，可以在创建待办时引用相关的任务或待办事项，建立上下文关联。

# 创建带任务引用的待办
octopus todos create --project-no 7 --task-no 123 --email [email protected] --title "完成API测试" --ref-task 456

# 创建带多个引用的待办
octopus todos create --project-no 7 --task-no 123 --email [email protected] --title "修复Bug" --ref-task 456 --ref-task 789 --ref-todo "550e8400-e29b-41d4-a716-446655440001"

待办反馈（状态变更）

octopus todos feedback --project-no <number> --todo-id <todoId> --email <email> --status <status> [--feedback <feedback>] [--processing-time <minutes>] [--tokens-consumed <count>]

状态值： completed, failed, suspended

上传待办附件

octopus todos upload-attachment --project-no <number> --todo-id <todoId> --file <path> [--title <title>] --email <email>

权限说明： 只有待办负责人、任务负责人或待办创建人才能上传附件。

获取待办附件列表

octopus todos attachments --project-no <number> --todo-id <todoId> [--email <email>]

# 获取待办附件列表
octopus todos attachments --project-no 7 --todo-id "550e8400-e29b-41d4-a716-446655440001" --email [email protected]

附件管理 (attachments)

下载附件

支持下载任务附件和待办附件，通过 --attachment-type 参数指定附件类型。

octopus attachments download --project-no <number> --attachment-id <id> [--attachment-type <type>] --email <email> [--output <path>]

附件类型：

task - 任务附件（默认）
todo - 待办附件

# 下载任务附件（默认类型）
octopus attachments download --project-no 7 --attachment-id 789 --email [email protected]

# 下载待办附件
octopus attachments download --project-no 7 --attachment-id 789 --attachment-type todo --email [email protected]

# 下载到指定路径
octopus attachments download --project-no 7 --attachment-id 789 --attachment-type todo --email [email protected] --output ./downloads/file.pdf

使用场景示例

场景1：查询账号参与的项目信息

EMAIL="[email protected]"

# 查询用户参与的所有项目
PROJECTS=$(octopus projects list --email $EMAIL)

# 提取项目编号进行后续操作
PROJECT_NOS=$(echo "$PROJECTS" | jq -r '.[].projectNo')

for PROJECT_NO in $PROJECT_NOS; do
  echo "正在处理项目 $PROJECT_NO..."
  octopus tasks list --project-no $PROJECT_NO --email $EMAIL
done

场景2：多账号并发使用

多个智能体同时操作不同账号时，每条命令均需显式指定 --email：

# 添加多个账号
octopus account add [email protected] pat_dev_token_xxxxx
octopus account add [email protected] pat_manager_token_xxxxx

# 不同账号独立操作，互不干扰
octopus tasks list --project-no 7 --email [email protected]
octopus todos pending-approval --project-no 7 --email [email protected]

场景3：自动化脚本集成

# 配置服务器和账号
octopus config set baseUrl https://octopus.wuyehao.com
octopus account add [email protected] pat_ci_token_xxxxx

# 获取待办事项
PENDING_TODOS=$(octopus todos pending --project-no 7 --email [email protected])

# 完成任务
octopus tasks complete --project-no 7 --task-no 123 --email [email protected] --minutes-spent 60

场景4：项目管理员审批待办

PROJECT_NO=7
[email protected]

# 查看待审批的待办事项
octopus todos pending-approval --project-no $PROJECT_NO --email $MANAGER_EMAIL

# 批准指定待办
octopus todos approve --project-no $PROJECT_NO --todo-id 456 --email $MANAGER_EMAIL --remark "同意执行"

场景5：任务批量操作

PROJECT_NO=7
[email protected]

# 获取所有进行中的任务
TASKS=$(octopus tasks list --project-no $PROJECT_NO --email $EMAIL --status in_progress)

# 处理每个任务（示例：添加备注）
echo "$TASKS" | jq -r '.[].taskNo' | while read TASK_NO; do
  octopus tasks comment --project-no $PROJECT_NO --task-no $TASK_NO --email $EMAIL --remark "批量更新进度"
done

获取帮助

查看所有命令

octopus --help

查看子命令帮助

octopus tasks --help
octopus tasks list --help

查看版本

octopus --version

注意事项

Access Token 安全：Token 会保存在本地配置文件中，请妥善保管
必须指定 --email：所有命令均需显式传入 --email 参数，CLI 不支持默认账号，以保证多智能体并发使用时的账号隔离
工时记录：--minutes-spent 参数单位为分钟
状态值：注意不同命令的状态可选值可能不同，请参考命令帮助
网络要求：确保可以访问配置的服务器地址
管理员权限：todos pending-approval 和 todos approve 命令需要项目管理员权限

常见问题

Q: 如何更新账号的 Token？

octopus account add <email> <new-token>

Q: 命令执行失败怎么办？

检查以下几点：

服务器地址是否正确：octopus config get
账号是否配置：octopus config get
网络连接是否正常
Token 是否有效
是否具有所需的项目权限

创建 octopus-cli 技能

为了让 Agent 能够使用 Octopus CLI，您需要创建一个技能文件。技能文件定义了技能的基本信息和使用文档。

技能文件格式

技能文件必须以 SKILL.md 命名，并包含以下结构：

---
name: octopus-cli
description: Octopus CLI 是章鱼平台（OctopusMission）的命令行工具，基于用户访问令牌与后端 API 交互。Agent 可使用此 CLI 代用户执行任务管理操作。
---

# Octopus CLI - Agent 使用文档

...（详细的使用文档）

前置元数据说明

| 字段 | 必填 | 说明 | | ----------- | ---- | ------------------------------ | | name | 是 | 技能名称，用于调用技能 | | description | 是 | 技能描述，向 Agent 说明技能用途 |

安装技能

创建技能目录（如果不存在）：
```
mkdir -p ~/.claude/skills
```

将技能文件放置到技能目录：

cp SKILL.md ~/.claude/skills/octopus-cli.md

重启 Claude Code 或重新加载技能

完整技能文件示例

完整的 octopus-cli 技能文件请参考：

GitLab 仓库: octopus-cli/SKILL.md

该文件包含了：

CLI 安装和配置说明
所有命令的详细参数说明
使用示例和最佳实践
错误处理指南

使用技能

安装技能后，Agent 可以通过以下方式使用：

# Agent 会自动识别并调用 octopus-cli 技能
# 示例：让 Agent 帮助查看任务列表
octopus tasks list --project-no 7 --email [email protected]

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Octopus CLI 使用说明

简介

安装

全局安装

验证安装

快速开始

1. 配置服务器地址

2. 添加账号

3. 查看配置

4. 获取任务列表

命令参考

配置管理 (config)

查看配置

设置服务器地址

删除服务器地址

配置文件

账号管理 (account)

添加账号

移除账号

项目管理 (projects)

获取项目列表

任务管理 (tasks)

获取任务列表

获取任务详情

开始任务

完成任务

标记任务异常

关闭任务

激活任务

任务改派（修改负责人）

添加任务备注

获取任务附件列表

创建任务（项目管理员）

上传任务附件

获取任务流水记录

待办管理 (todos)

获取待处理待办列表（执行者视角）

获取待审批待办列表（项目管理员视角）

批准待办事项（项目管理员）

获取已批准待办列表

创建待办

待办反馈（状态变更）

上传待办附件

获取待办附件列表

附件管理 (attachments)

下载附件

使用场景示例

场景1：查询账号参与的项目信息

场景2：多账号并发使用

场景3：自动化脚本集成

场景4：项目管理员审批待办

场景5：任务批量操作

获取帮助

查看所有命令

查看子命令帮助

查看版本

注意事项

常见问题

Q: 如何更新账号的 Token？

Q: 命令执行失败怎么办？

创建 octopus-cli 技能

技能文件格式

前置元数据说明

安装技能

完整技能文件示例

使用技能