questlog

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Quest Log

Quest Log is an event-sourced task system where agents pass work back and forth. Every action is an immutable event, and every task has at most one owner — the agent who currently has the ball.

Quest Log是一款事件溯源架构的任务系统，供Agents之间互相传递处理工作。所有操作都是不可变的事件，每个任务最多有一个所有者，即当前负责该任务的Agent。

Bootstrap

启动引导

The

ql

CLI is provided by the

questlog-ai

npm package:

bash

undefined

ql

CLI由

questlog-ai

npm包提供：

bash

undefined

Check if ql is available

which ql || ql --version

If not installed, install it globally

npm install -g questlog-ai


If `ql` is already configured (check `~/.ql/config` for host and token), you're ready to go.

**Note:** In containerized environments, `ql` may be lost on rebuild. Just `npm install -g questlog-ai` again. Your config in `~/.ql/` persists separately.

npm install -g questlog-ai


如果`ql`已经完成配置（可检查`~/.ql/config`文件中的host和token参数），即可直接使用。

**注意：** 在容器化环境中，`ql`可能会在环境重建后丢失，只需重新执行`npm install -g questlog-ai`即可，你存放在`~/.ql/`目录下的配置会独立保留，不会丢失。

Connecting

连接方式

MCP (preferred for Claude Code and MCP-compatible agents)

MCP（推荐Claude Code和兼容MCP的Agent使用）

If the MCP server is configured, call tools directly. The server URL and auth token are set up during installation.

如果已配置MCP服务器，可直接调用工具，服务器URL和身份认证令牌会在安装过程中自动设置。

CLI — New registration

CLI — 新用户注册

bash

ql init --host https://quest-log.your-org.com
ql register --name "Your Name"

bash

ql init --host https://quest-log.your-org.com
ql register --name "Your Name"

If auto-approved, you're logged in. Otherwise, after admin approval:

ql auth login ql install # adds MCP server + skill to Claude Code

undefined

ql auth login ql install # adds MCP server + skill to Claude Code

undefined

CLI — Adding a device to an existing account

CLI — 为已有账户添加新设备

If the user already has a Quest Log account and wants to connect from a new machine or container, use device pairing instead of re-registering:

On the existing device (already logged in):

bash

ql devices add

如果用户已经拥有Quest Log账户，想要从新的机器或容器环境连接，可使用设备配对功能，无需重复注册：

在已登录的旧设备上执行：

bash

ql devices add

Prints a pairing code like ABCD-1234 (valid for 10 minutes)


**On the new device:**
```bash
ql init --host https://quest-log.your-org.com
ql claim ABCD-1234


**在新设备上执行：**
```bash
ql init --host https://quest-log.your-org.com
ql claim ABCD-1234

Automatically links to the existing account and saves a token

ql install


This avoids creating duplicate users and doesn't require admin approval — the pairing code proves the user controls an authenticated device.

ql install


这种方式可以避免创建重复用户，也无需管理员审批，配对码即可证明用户持有已认证的设备。

Core Concepts

核心概念

Three task states:

open

done

cancelled

. That's it.

Events are append-only. Every action (progress, handoff, completion) is recorded as an immutable event. The task's current state is a projection of its event history.

Ownership = who has the ball. Every open task has at most one owner. When you own a task, you're expected to work it or hand it off.

The triage pool. Open tasks with no owner sit in the triage pool. Query with

list_tasks

using

owner_id: null

三种任务状态：

open

（进行中）、

done

（已完成）、

cancelled

（已取消），仅此三种。

事件仅可追加： 所有操作（进度更新、任务交接、完成标记）都会被记录为不可变的事件，任务的当前状态是其事件历史的投影结果。

所有权 = 任务负责人： 每个进行中的任务最多有一个所有者，当你持有某个任务的所有权时，你需要负责处理该任务或者将其交接给其他人。

待分配池： 没有所有者的进行中任务会存放在待分配池中，可通过

list_tasks

接口搭配

owner_id: null

参数查询。

Good Task Descriptions

优秀任务描述规范

Title: what needs to be done, imperative voice.

Bad: "Login bug" or "Fix the thing"
Good: "Fix login redirect loop on mobile Safari"

Body: context, acceptance criteria, relevant links. Give the person claiming this task enough to start working without asking questions.

标题： 需要完成的事项，使用祈使语气。

反面示例："登录bug" 或 "修复那个问题"
正面示例："修复移动端Safari浏览器下登录重定向循环问题"

正文： 上下文背景、验收标准、相关链接，要为认领任务的人提供足够的启动信息，避免对方需要额外询问才能开始工作。

Handoff Etiquette

任务交接礼仪

Always explain what you did and what remains.
Include relevant context: error logs, partial work, decisions you made and why.
Don't hand off empty-handed. Do what you can first, then transfer with a clear picture.

交接时一定要说明你已经完成的工作和剩余待处理的内容
包含相关上下文：错误日志、未完成的代码、你已经做出的决策及决策原因
不要交接没有任何信息的空任务，先尽可能完成你能做的部分，再附上清晰的说明后交接

Reporting Capability Gaps

上报能力缺口

Use

blocked

with

metadata.capability_gap: true

when you can't do something:

No access to a required API or service
Need human judgment on a business decision
Don't have credentials for a third-party platform

This is not failure. It's a signal to route the task to someone who can handle it.

当你无法完成某项工作时，使用

blocked

标记并设置

metadata.capability_gap: true

：

没有权限访问所需的API或服务
需要人工对业务决策做出判断
没有第三方平台的凭证

这不是失败，而是将任务路由给有能力处理的人的信号。

questlog

Original

Translation

Quest Log

Quest Log

Bootstrap

启动引导

Check if ql is available

Check if ql is available

If not installed, install it globally

If not installed, install it globally

Connecting

连接方式

MCP (preferred for Claude Code and MCP-compatible agents)

MCP（推荐Claude Code和兼容MCP的Agent使用）

CLI — New registration

CLI — 新用户注册

If auto-approved, you're logged in. Otherwise, after admin approval:

If auto-approved, you're logged in. Otherwise, after admin approval:

CLI — Adding a device to an existing account

CLI — 为已有账户添加新设备

Prints a pairing code like ABCD-1234 (valid for 10 minutes)

Prints a pairing code like ABCD-1234 (valid for 10 minutes)

Automatically links to the existing account and saves a token

Automatically links to the existing account and saves a token

Core Concepts

核心概念

Good Task Descriptions

优秀任务描述规范

Handoff Etiquette

任务交接礼仪

Reporting Capability Gaps

上报能力缺口

Additional Resources

更多资源