Communitygithub.com

mwpryer/asnx

⚡ 面向 Agent 的 Asana CLI,支持模式自省。

asnx 是什么?

`asnx` 是一个为 AI Agent 设计的 Asana 命令行工具。它通过统一的 `asnx <entity> <action>` 命令结构,简化了与 Asana API 的交互,并内置模式自省功能,帮助用户和 AI 快速发现可用的实体与操作。该工具支持环境变量 `ASANA_TOKEN` 或命名账户的令牌认证,输入可采用独立的参数标志或原始 JSON 体,输出则返回统一的 JSON 信封,包含 `meta` 元数据(如命令名、状态码、分页偏移量)和 `data` 数据载荷。`asnx` 还提供 `--dry-run` 预览写入、`--opt-fields` 精简 GET 响应、手动分页、以及针对常见陷阱(如 `start_on` 与 `due_on` 的关系、`tasks duplicate` 的继承限制等)的明确规则,使其非常适合在 Cursor、Claude Code 等 Agent 平台上自动化管理 Asana 项目、任务和工作流。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add mwpryer/asnx

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

asnx: Asana CLI

asnx <entity> <action> [<gid>] [--flags...]

CLI 始终保持扁平结构:asnx <entity> <action>。子资源和动词操作保持显式,例如 asnx tasks subtasks、asnx tasks create-subtasks 和 asnx tasks add-followers。

使用 asnx describe [<entity> [<action>]] 进行模式自省。

认证

优先级:--account <name> > ASANA_TOKEN 环境变量 > 单一已存储账户。

asnx auth status 会验证已解析的令牌是否有效;用于诊断 401 错误。

输入

写入操作接受单个参数标志或原始 JSON 体。如果同时指定,--json 优先级更高。

asnx tasks create --json '{"name":"bugfix","projects":["def"]}'

--json 只接受原始请求字段,不包含完整的 Asana { "data": ... } 封装。

输出

成功执行的命令会输出包含 meta 和 data 的 JSON 信封:

{
  "meta": {
    "command": "tasks.list",
    "status": 200,
    "nextPage": null
  },
  "data": [ ... ]
}
  • meta.command 始终是 entity.action(一个点),例如 tasks.list、tasks.subtasks 或 project-briefs.create-for-project。
  • data 是解包后的 Asana 载荷:单个资源为对象,列表为数组。
  • meta.nextPage 是分页偏移量(字符串)或 null。将其作为 --offset 传递。

错误信息输出到 stderr,格式为 {"error":{"status":...,"message":...,"help":...}}。对于本地错误(用法、传输),status 为 null。发生错误时退出码始终为 1。

规则

  • 在发送写入操作前,使用 --dry-run 进行预览。
  • 在 GET 请求中使用 --opt-fields 以保持响应小巧。
  • 分页是手动的:检查 meta.nextPage,并作为 --offset 传递。
  • 不要猜测 GID,先进行查询。从 asnx workspaces list 开始,然后例如 asnx tasks search <workspace-gid> --text "bugfix"。
  • 如果实体命令返回未知,说明模式缓存缺失:运行 asnx schema update。
  • 带点的 Asana 过滤器在 CLI 中保持带点形式,例如 --projects.any 或 --due-on.before。

注意事项

  • start_on 需要 due_on:始终一起发送。
  • me 是位置参数 GID 的别名,不是动作。使用 users get me,而不是 users me。
  • tasks for-project 默认返回所有任务,包括已完成的。要仅获取未完成的任务,请传递 --completed-since <最近的时间戳>(例如当前时间);Asana 随后会返回在该时间之后未完成或已完成的任务。
  • tasks duplicate 和 projects duplicate 不会复制所有关联。重复的任务默认没有项目成员资格(projects: []),除非你传递 --include 指定要复制的元素,例如 --include projects,subtasks,assignee。
  • stories for-task 和 stories for-goal 同时返回评论和系统事件。评论是那些 "type": "comment" 的条目;需要在客户端过滤。
  • tasks search 是最终一致性的。请使用 tasks get 或 tasks for-project 验证最近的写入,而非 search。
  • attachments create 在 Asana 端是多部分上传,此 CLI 仅支持 JSON;该动作会显示但始终失败。请使用原始 API 进行文件上传。
  • project-briefs create-for-project 可能会拒绝纯 --text,提示“Rich text should be wrapped in tag.”。如果发生这种情况,请使用 --html-text '<body>...</body>' 重试。
  • <entity> remove-members --members me(适用于组合、项目、目标、团队)会撤销你自己的访问权限。

相关技能