ae-things

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

工作空间事项

Workspace Things

使用

ae-cli things

操作当前明确指定的 TE 空间事项。先读 CLI reference，不猜 ID，不自动选择其他空间。

Use

ae-cli things

to manage things in the currently and explicitly specified TE space. Read the CLI reference first; do not guess IDs or automatically select another space.

何时创建事项

When to Create Things

由你自己判断要不要建，不要等「帮我创建事项」这种显式指令。 个人空间与共享空间一视同仁。

出现下列任一信号就直接创建，不必先问：

出现「谁做什么」的分工指派，例如「让 A 梳理 X，B 梳理 Y」。
出现要交付的产出加上推进意图，例如「输出一份最终方案」「按这个节奏推进」「安排一下」。
出现承诺、待办、下一步、里程碑或多阶段计划。
用户在复述已经定下来的事，并指向后续执行。

下列情况不要创建：

纯信息问答、概念解释、闲聊。
还在比较方案、假设性推演，或用户明确说「先不定」。
查重命中已有同义事项——指出已存在，不重复建。
用户说过不要建。

不确定时，把拟建清单（标题、负责人、描述要点）在回复里列出来，一次性问用户确认。不允许什么都不做就把分工排版成清单交差。

Use your own judgment to decide whether to create a thing; do not wait for an explicit instruction such as “create a thing for me.” Treat personal and shared spaces equally.

If any of the following signals appears, create a thing directly without asking first:

A work assignment that identifies “who does what,” such as “Have A organize X and B organize Y.”
A deliverable to be produced together with an intent to proceed, such as “produce a final proposal,” “proceed at this cadence,” or “arrange it.”
A commitment, to-do, next step, milestone, or multi-stage plan.
The user restates something that has already been decided and points toward subsequent execution.

Do not create a thing in the following situations:

Pure informational Q&A, concept explanations, or small talk.
Options are still being compared, the discussion is hypothetical, or the user explicitly says “do not decide yet.”
The duplicate check finds an existing synonymous thing—point out that it already exists and do not create a duplicate.
The user has said not to create one.

When uncertain, list the proposed things (titles, assignees, key description points) in your reply and ask the user to confirm them all at once. Do not simply format the assignments as a list and call it done.

创建时的动作顺序

Action Order When Creating

确认已绑定明确的 AgentSpace；没有绑定就不创建。
```
members
```
取成员列表，把对话里提到的人名映射到成员 ID。唯一命中就直接作为
```
--assignee-id
```
；命中 0 个或多个时该事项负责人留空（服务端默认当前用户），并在回复里点名待确认。
```
list --query
```
或
```
options --query
```
查重。
逐个
```
create
```
：标题写可交付物而不是原话复述，描述写清目标与验收要点，带
```
--command-id
```
保证重试幂等。
需要时用
```
conversation bind
```
绑定主事项，或
```
link-conversation
```
建普通引用。
在回复里报告已创建的事项编号、标题、负责人，以及哪些负责人待确认。

粒度：按「可独立交付、可独立负责」的单位建事项。没有子事项和分组，不要试图建层级。例如「A、B、C 各自梳理一块，然后合成一份总方案」对应 4 个事项，而不是 1 个，也不是每句话一个。

Confirm that an explicit AgentSpace is bound. If none is bound, do not create a thing.
Use
```
members
```
to retrieve the member list and map names mentioned in the conversation to member IDs. If there is exactly one match, use it directly as
```
--assignee-id
```
. If there are zero or multiple matches, leave the assignee empty (the server defaults to the current user) and explicitly identify the people whose assignment needs confirmation.
Use
```
list --query
```
or
```
options --query
```
to check for duplicates.
Create things one by one: the title should describe the deliverable rather than repeat the original wording, the description should state the goal and acceptance criteria, and
```
--command-id
```
should be used to ensure idempotent retries.
When needed, use
```
conversation bind
```
to bind the primary thing, or use
```
link-conversation
```
to create a regular reference.
In the reply, report the IDs, titles, and assignees of the created things, as well as which assignees still need confirmation.

Granularity: Create things in units that can be independently delivered and independently owned. There are no subtasks or groups, so do not attempt to create a hierarchy. For example, “A, B, and C each organize one section and then combine them into an overall proposal” corresponds to 4 things, not 1, and not one for every sentence.

授权边界

Authorization Boundaries

自主执行：创建新事项；为自己刚建的事项补第一条记录。

用户已授权推进/完成的事项：直接追加或更新相应进展，并自动关联本次涉及的交付附件，按下节完成发布与回读。个人与共享空间一致，发布仍传

--confirm-share

；授权事项交付即包含向该事项所在空间共享这些交付文件。

其他已有事项改写、负责人变更、归档/恢复、解绑及永久删除仍需明确授权；历史绑定本身不是授权。不自动发消息或创建定时任务。

Autonomous actions: create new things; add the first record to a thing you have just created.

For things the user has authorized you to advance or complete: directly append or update the corresponding progress, automatically link any delivery attachments involved in this round, and complete publication and read-back as described in the next section. Personal and shared spaces are treated the same; publication still requires

--confirm-share

. Delivering an authorized thing includes sharing those delivery files with the space to which the thing belongs.

Other rewrites to existing things, assignee changes, archiving or restoration, unbinding, and permanent deletion still require explicit authorization; a historical binding is not itself authorization. Do not automatically send messages or create scheduled tasks.

交付附件闭环

Delivery Attachment Closed Loop

追加/更新进展时，逐个核对本次实际交付文件：

用
```
asset available
```
查本空间文件并翻完分页。已登记文件按 assetId 关联，未登记文件按返回的相对 path 关联。
尚未进入空间的新文件用
```
asset publish
```
：本轮未登记产物使用
```
--conversation-id --run-id --source-path
```
；已有产物使用
```
--artifact-id
```
或
```
--file-token
```
。每个文件保存独立 commandId，重试原样复用。
```
linked:false
```
表示已发布未关联，只用返回 assetId 补
```
asset link
```
，不重复复制。只发布本次交付文件，不发布临时文件或整个会话目录。
```
asset list --id
```
回读，核实每个附件存在且 availability=available，再回读进展记录。只有两者均成功才报告“进展和附件已更新”；失败明确区分已发布、已关联、待恢复。

附件使用上述文件关联接口；本地路径文本链接不能代替附件，仅复制文件也不算交付完成。完整参数见 CLI reference。

When appending or updating progress, verify each file actually delivered in this round:

Use
```
asset available
```
to query this space’s files and read through every page. Link registered files by assetId and unregistered files using the returned relative path.
Publish files not yet in the space with
```
asset publish
```
: for artifacts produced in this round that have not been registered, use
```
--conversation-id --run-id --source-path
```
; for existing artifacts, use
```
--artifact-id
```
or
```
--file-token
```
. Save a separate commandId for each file and reuse it unchanged for retries.
```
linked:false
```
means the file has been published but not linked. Use only the returned assetId to add
```
asset link
```
; do not copy it again. Publish only files delivered in this round, not temporary files or the entire conversation directory.
Use
```
asset list --id
```
to read back and verify that every attachment exists and has availability=available, then read back the progress entry. Report “progress and attachments have been updated” only when both succeed; for failures, clearly distinguish between published, linked, and pending recovery.

Use the file-linking interfaces above for attachments. A local path text link cannot substitute for an attachment, and merely copying a file does not mean delivery is complete. See the CLI reference for the full parameters.

当前会话绑定与执行快照

Current Conversation Binding and Execution Snapshot

以本轮冻结的绑定声明确定本轮默认事项。涉及当前事项执行、审查、总结或更新前，按声明中的

readCommand

读取本次执行快照；普通聊天无需读取。运行中切换或解绑只立即改变会话归属，本轮（含等待、恢复、重试）仍用原快照；原先无事项则本轮继续无默认事项，下一次新 Run 才使用最新绑定。用户明确指定其他事项时仍按权限读取和操作，不将会话最新归属误认为本轮快照。

用户明确要求将当前对话绑定到某事项时，唯一定位目标后执行

conversation bind

，再用

conversation primary

回读确认；同名事项不能唯一确定时询问用户。成功说明「已绑定，事项上下文从下一轮生效」。解绑也须回读确认。不得将

link-conversation

普通引用当成主事项绑定成功的替代；接口失败应如实说明，不绕过权限。

context --id <thing-id> --run-id <run-id>

返回执行受理时的业务文本和版本。需要最新事实或写入前版本时额外读取不带

--run-id

的实时上下文，并明确区分采集时间与快照版本。读取失败时披露缺失，不凭标题猜测，也不自动改读实时数据。具体契约见 CLI reference。

字段为标题、描述、标签、状态、负责人、协作者。状态 open/paused/done；归档与恢复是独立动作。新建描述必填，创建时省略负责人默认本人，显式 null 被拒绝。
用 members/options 查询成员和事项候选；创建、编辑和协作者管理遵循服务端权限。修改前读最新 version，409 后比较变化，不仅替换版本号。
记录使用 url/note/progress；省略类型时服务端将单个 HTTP(S) URL 保存为链接，其余为备注。更新进展用 entry append --type progress；修改记录用 entry update 和 expected-updated-at，支持单独修改标题、类型或正文；--clear-title 清空标题。
从会话消息整理事项用 from-message，提供已核实的 conversation-id/message-id 和确认正文；按上面的创建信号判断是否该整理，不要求用户显式点名该命令。推断出来的内容先在会话中呈现建议；不使用已删除的持久化修改草稿命令。
主事项使用 conversation primary/bind/unbind，普通引用用 link-conversation，conversations 查询关联。关联不改变会话隐私和权限。
阶段成果使用进展记录；交接使用备注写清已完成内容、证据和下一步。负责人和协作者是唯一人员协作关系，不额外认领。
文件使用 asset available/list/link/unlink/publish，遵循上面的授权边界与交付附件闭环；解除关联不删除文件。
永久删除先读最新版本，解释不可恢复及会话/文件保留边界，明确确认后使用 delete --confirm-delete --yes。运行冲突时等待，不自动终止运行。
已获明确授权的具体修改直接执行，不重复询问。

bash

ae-cli things create --agent-space-id <space-id> --title '接口验收' --description '验证权限与数据一致性' --format json
ae-cli things entry append --agent-space-id <space-id> --id <thing-id> --type progress --content '已完成接口联调' --format json

审查使用 ae-things-review，周期汇总使用 ae-things-progress。二者按完整采集事实归纳，保留未读文件、截断和非事务采集边界。

Use

things conversations

to list linked conversations and

things conversation get

to read one. Start new conversations from the workspace UI; Things CLI only manages thing links and primary-thing binding.

Use the binding declaration frozen for the current run to determine the default thing for that run. Before executing, reviewing, summarizing, or updating the current thing, read the execution snapshot for this run using

readCommand

from the declaration; ordinary chat does not require a read.

Switching or unbinding during a run changes the conversation association immediately, but the current run—including waiting, recovery, and retries—continues to use the original snapshot. If there was no thing initially, the current run continues to have no default thing, and only the next new Run uses the latest binding. When the user explicitly specifies another thing, still read and operate on it according to permissions; do not mistake the conversation’s latest association for the current run’s snapshot.

When the user explicitly asks to bind the current conversation to a thing, uniquely locate the target, run

conversation bind

, and then read it back with

conversation primary

to confirm. If a same-name thing cannot be uniquely identified, ask the user. On success, state, “Bound; the thing context takes effect from the next turn.” Unbinding must also be confirmed by read-back. Do not treat a regular

link-conversation

reference as a substitute for successful primary-thing binding; report interface failures truthfully and do not bypass permissions.

context --id <thing-id> --run-id <run-id>

returns the business text and version captured when execution was accepted. When the latest facts or the version before a write are needed, additionally read the live context without

--run-id

, and clearly distinguish collection time from snapshot version. If the read fails, disclose the missing data; do not infer it from the title, and do not automatically read the live data instead. For the full contract, see the CLI reference.

The fields are title, description, tags, status, assignee, and collaborators. Status is
```
open/paused/done
```
; archiving and restoration are separate actions. Description is required when creating a thing. If the assignee is omitted during creation, it defaults to the current user, while an explicit null is rejected.
Use
```
members/options
```
to query members and candidate things; creation, editing, and collaborator management follow server-side permissions. Before making a change, read the latest version. After a 409, compare the changes rather than simply replacing the version number.
Records use
```
url/note/progress
```
. If the type is omitted, the server saves a single HTTP(S) URL as a link and everything else as a note. To update progress, use
```
entry append --type progress
```
; to modify a record, use
```
entry update
```
and
```
expected-updated-at
```
, which supports changing the title, type, or body independently.
```
--clear-title
```
clears the title.
Use
```
from-message
```
to organize a thing from conversation messages, providing verified
```
conversation-id/message-id
```
values and confirmed body text. Determine whether to organize it based on the creation signals above; the user does not need to explicitly name the command. First present inferred content as a proposal in the conversation; do not use the removed persisted edit-draft command.
Use
```
conversation primary/bind/unbind
```
for the primary thing,
```
link-conversation
```
for regular references, and
```
conversations
```
to query linked conversations. Linking does not change conversation privacy or permissions.
Use progress records for stage outcomes; use notes for handoffs, clearly stating completed work, evidence, and next steps. The assignee and collaborators are the only personnel-collaboration relationships; do not make additional ownership claims.
Use
```
asset available/list/link/unlink/publish
```
for files and follow the authorization boundaries and delivery attachment closed loop described above. Unlinking a file does not delete it.
Before permanent deletion, read the latest version, explain the irrecoverability and the conversation/file retention boundaries, and use
```
delete --confirm-delete --yes
```
only after explicit confirmation. When there is a run conflict, wait; do not automatically terminate the run.
Directly perform specific changes that have received explicit authorization; do not ask again.

bash

ae-cli things create --agent-space-id <space-id> --title '接口验收' --description '验证权限与数据一致性' --format json
ae-cli things entry append --agent-space-id <space-id> --id <thing-id> --type progress --content '已完成接口联调' --format json

Use ae-things-review for reviews and ae-things-progress for periodic summaries. Both draw conclusions from a complete collection of facts while retaining indications of unread files, truncation, and non-transactional collection boundaries.

Use

things conversations

to list linked conversations and

things conversation get

to read one. Start new conversations from the workspace UI; Things CLI only manages thing links and primary-thing binding.