tasks-axi

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

tasks-axi

Agent ergonomic task & backlog manager for the current workspace. Prefer this over hand-editing backlog.md for task state, dependency, or hold changes.

You do not need tasks-axi installed globally - invoke it with

npx -y tasks-axi <command>

. If tasks-axi output shows a follow-up command starting with

tasks-axi

, run it as

npx -y tasks-axi ...

instead.

tasks-axi operates on a hand-editable

backlog.md

in the current workspace (or the path set in

.tasks.toml

). It edits the file in place with a byte-exact round-trip, so the human-readable backlog stays the source of truth.

面向当前工作区的Agent友好型任务与待办事项管理器。在修改任务状态、依赖关系或暂停设置时，优先使用该工具而非手动编辑backlog.md。

无需全局安装tasks-axi——使用

npx -y tasks-axi <command>

即可调用。如果tasks-axi的输出显示后续命令以

tasks-axi

开头，请改为运行

npx -y tasks-axi ...

。

tasks-axi操作当前工作区中可手动编辑的

backlog.md

文件（或

.tasks.toml

中设置的路径）。它会在原文件中进行字节级精确的往返编辑，因此人类可读的待办事项始终是可信数据源。

When to use

使用场景

Use tasks-axi whenever a task touches the backlog: filing or dispatching work, moving a task through queued -> in flight -> done, recording a PR url or report path on completion, tracking blocked-by dependencies, pausing dispatch with structured holds, finding dispatchable ready work or intentionally held work, or trimming the Done list.

只要涉及待办事项的操作都可使用tasks-axi：提交或分派工作、将任务从已排队→进行中→已完成、完成时记录PR链接或报告路径、跟踪依赖阻塞、通过结构化暂停暂停分派、查找可就绪的可分派工作或有意暂停的工作，或清理已完成任务列表。

Workflow

工作流程

Run
```
npx -y tasks-axi
```
with no arguments for a dashboard of the current backlog - in flight work, queued work with blockers, and suggested next commands.

Drill in verb-first:

list

show <id>

ready

, then mutate with

add

start

done

block

unblock

hold

unhold

update

The long notes never appear in
```
list
```
; run
```
show <id> --full
```
to read a task's complete body before replacing it.
```
add
```
takes a caller-supplied id (the join key), e.g.
```
tasks-axi add fm-x "title" --kind ship --repo firstmate --start
```
; or pass
```
--mint
```
to generate a slug-xx id from the title.
```
done <id> --pr <url>
```
(or
```
--report <path>
```
) closes a task, records the link, and prunes the Done list (archived, never deleted). Then
```
ready
```
shows work it unblocked.
```
hold <id> --reason "<text>"
```
pauses dispatch without prose parsing;
```
ready
```
excludes active holds by default, and
```
ready --include-held
```
shows a separate held group. Use
```
--until YYYY-MM-DD
```
for a date gate that becomes inactive on and after that date.
Human-readable responses include contextual next-step hints under
```
help:
```
when there is a useful follow-up - follow them.
```
--json
```
mutation responses skip
```
help:
```
and return the deterministic result object instead.

不带参数运行
```
npx -y tasks-axi
```
，查看当前待办事项的仪表盘——包括进行中的工作、存在阻塞的排队工作，以及建议的后续命令。
以动词优先深入操作：
```
list
```
、
```
show <id>
```
、
```
ready
```
，然后通过
```
add
```
、
```
start
```
、
```
done
```
、
```
block
```
/
```
unblock
```
、
```
hold
```
/
```
unhold
```
、
```
update
```
进行修改。
长注释不会出现在
```
list
```
结果中；在替换任务内容前，运行
```
show <id> --full
```
查看任务的完整内容。
```
add
```
命令接受调用者提供的id（关联键），例如
```
tasks-axi add fm-x "title" --kind ship --repo firstmate --start
```
；或传入
```
--mint
```
参数，根据标题生成slug-xx格式的id。
```
done <id> --pr <url>
```
（或
```
--report <path>
```
）会关闭任务、记录链接，并清理已完成任务列表（归档，永不删除）。之后运行
```
ready
```
可查看该任务解锁的工作。
```
hold <id> --reason "<text>"
```
可暂停任务分派，无需解析文本内容；默认情况下
```
ready
```
会排除处于活动暂停状态的任务，而
```
ready --include-held
```
会单独显示暂停的任务组。使用
```
--until YYYY-MM-DD
```
设置日期限制，该限制在指定日期及之后失效。
人类可读的响应中，当存在有用的后续操作时，会在
```
help:
```
下显示上下文相关的下一步提示——请遵循这些提示。
```
--json
```
参数的修改响应会跳过
```
help:
```
，返回确定性的结果对象。

Commands

命令

commands[19]:
  (none)=dashboard, add, list, show, start, done, reopen, update, rm, block, unblock, hold, unhold, ready, public-followup, mv, prune, render, setup

Run

npx -y tasks-axi --help

for global flags, or

npx -y tasks-axi <command> --help

for per-command usage.

commands[19]:
  (none)=dashboard, add, list, show, start, done, reopen, update, rm, block, unblock, hold, unhold, ready, public-followup, mv, prune, render, setup

运行

npx -y tasks-axi --help

查看全局标志，或运行

npx -y tasks-axi <command> --help

查看各命令的使用说明。

Tips

提示

Output is TOON-encoded and token-efficient; the long task body is truncated by default - the whole point is that
```
list
```
stays cheap. Use
```
--full
```
only when you need the complete notes.
Every write leads with an
```
ok:
```
line confirming the write result, including the resulting task state when the command changes one (e.g.
```
ok: start <id> -> In flight
```
,
```
ok: done <id> -> Done (pr <url>)
```
,
```
ok: render -> normalized <n>
```
), then state-aware next-step hints. Mutations are idempotent and add
```
already: true
```
on a no-op; re-running is safe.
Pass
```
--json
```
to any mutation (
```
add
```
,
```
start
```
,
```
done
```
,
```
reopen
```
,
```
update
```
,
```
rm
```
,
```
block
```
,
```
unblock
```
,
```
hold
```
,
```
unhold
```
,
```
mv
```
,
```
prune
```
,
```
render
```
) for a machine-readable result object (
```
{ "ok": true, "action": ..., "task": { ... } }
```
or operation-specific result fields) instead of TOON - confirm a write deterministically without a follow-up read.
```
block <id> --by <other>
```
and
```
unblock
```
manage the dependency graph;
```
hold <id> --reason "<text>" [--until YYYY-MM-DD]
```
and
```
unhold
```
manage structured dispatch pauses;
```
ready
```
lists only queued work with no unresolved blocker and no active hold.

Filter

list

with

--state

--repo

--kind

--blocked

--limit

, and add columns with

--fields a,b,c

. Use

list --state held

--fields held,hold_reason,hold_kind,hold_until

when scanning active hold state.

Existing prose markers such as
```
HELD
```
,
```
PARKED
```
,
```
DEFERRED
```
,
```
CAPTAIN-DECISION
```
, and
```
do not dispatch
```
stay prose until intentionally migrated. Preserve the original prose as the hold reason, then choose
```
captain
```
,
```
parked
```
,
```
future
```
,
```
load
```
, or
```
external
```
only when the text supports that bucket.
Note writes are inspect-then-update: run
```
show <id> --full
```
, then replace the curated current body with
```
update <id> --body "<text>"
```
or
```
--body-file <path>
```
. Add
```
--archive-body
```
to preserve the superseded body in
```
note-archive.md
```
;
```
--title "<text>"
```
replaces the title;
```
render
```
normalizes the file;
```
mv <id> [<id>...] --to <path>
```
moves one or more tasks to another backlog in one atomic transaction - pass a whole connected set (a blocker and its dependents) to move it together and preserve its
```
blocked-by
```
links and reason strings; moves that would strand an endpoint are refused.
Free-form (no-id) backlog lines are preserved verbatim and are never modified.

输出采用TOON编码，且令牌效率高；默认情况下任务的长内容会被截断——这样设计的核心是让
```
list
```
操作保持轻量化。仅在需要查看完整注释时使用
```
--full
```
参数。
每次写入操作都会以
```
ok:
```
行开头，确认写入结果，包括命令修改后的任务状态（例如
```
ok: start <id> -> In flight
```
、
```
ok: done <id> -> Done (pr <url>)
```
、
```
ok: render -> normalized <n>
```
），然后显示基于状态的下一步提示。修改操作具有幂等性，无操作时会添加
```
already: true
```
；重复运行是安全的。
对任何修改操作（
```
add
```
、
```
start
```
、
```
done
```
、
```
reopen
```
、
```
update
```
、
```
rm
```
、
```
block
```
、
```
unblock
```
、
```
hold
```
、
```
unhold
```
、
```
mv
```
、
```
prune
```
、
```
render
```
）传入
```
--json
```
参数，可获得机器可读的结果对象（
```
{ "ok": true, "action": ..., "task": { ... } }
```
或特定操作的结果字段），而非TOON格式——无需后续读取即可确定性地确认写入操作。
```
block <id> --by <other>
```
和
```
unblock
```
用于管理依赖图；
```
hold <id> --reason "<text>" [--until YYYY-MM-DD]
```
和
```
unhold
```
用于管理结构化的分派暂停；
```
ready
```
仅列出无未解决阻塞且无活动暂停的排队工作。

使用

--state

、

--repo

、

--kind

、

--blocked

、

--limit

过滤

list

结果，并使用

--fields a,b,c

添加列。查看活动暂停状态时，使用

list --state held

或

--fields held,hold_reason,hold_kind,hold_until

。

现有的文本标记（如
```
HELD
```
、
```
PARKED
```
、
```
DEFERRED
```
、
```
CAPTAIN-DECISION
```
和
```
do not dispatch
```
）会保留为文本，直到有意迁移。将原始文本保留为暂停原因，仅当文本支持对应分类时，才选择
```
captain
```
、
```
parked
```
、
```
future
```
、
```
load
```
或
```
external
```
分类。
注释写入采用先检查后更新的方式：运行
```
show <id> --full
```
，然后使用
```
update <id> --body "<text>"
```
或
```
--body-file <path>
```
替换整理后的当前内容。添加
```
--archive-body
```
参数可将被替换的内容保存到
```
note-archive.md
```
中；
```
--title "<text>"
```
用于替换标题；
```
render
```
用于规范化文件；
```
mv <id> [<id>...] --to <path>
```
可将一个或多个任务原子性地移动到另一个待办事项文件中——需传入完整的关联集合（阻塞项及其依赖项），以保持其
```
blocked-by
```
链接和原因字符串；会拒绝导致端点孤立的移动操作。
自由格式（无id）的待办事项行会被原样保留，且永远不会被修改。