ae-things

Workspace Things

Use ae-cli things to operate on things in the currently explicitly specified TE space. First read CLI reference, do not guess IDs, and do not automatically select another space.

When to Create a Thing

Decide for yourself whether to create one; do not wait for an explicit instruction like "create a thing for me". Personal spaces and shared spaces are treated the same.

Create directly when any of the following signals appear; no need to ask first:

• An assignment of responsibilities appears, i.e., "who does what", for example "have A sort out X, B sort out Y".
• A deliverable to be produced appears along with an intent to advance, for example "produce a final plan", "proceed at this cadence", "arrange it".
• A commitment, to-do, next step, milestone, or multi-phase plan appears.
• The user is restating something already settled and pointing to subsequent execution.

Do not create in the following cases:

• Pure informational Q&A, concept explanations, or chitchat.
• Still comparing options, hypothetical reasoning, or the user explicitly says "let's not decide yet".
• Duplicate check hits an existing synonymous thing—point out that it exists; do not create a duplicate.
• The user has said not to create one.

When uncertain, list the proposed items (title, owner, description points) in the reply and ask the user to confirm in one go. It is not allowed to do nothing and just hand back the assignment formatted as a list.

Order of Actions When Creating

1. Confirm that a clear AgentSpace is bound; if not bound, do not create.
2. members retrieve the member list and map the names mentioned in the conversation to member IDs. If there is exactly one match, use it directly as --assignee-id; if there are 0 or multiple matches, leave the thing's owner blank (the server defaults to the current user) and name the pending confirmation in the reply.
3. list --query or options --query for duplicate checking.
4. For each create: the title should state the deliverable rather than restate the original words; the description should clearly state the objective and acceptance points, with --command-id to ensure retry idempotency.
5. When needed, use conversation bind to bind a primary thing, or link-conversation to create an ordinary reference.
6. In the reply, report the created thing numbers, titles, and owners, as well as which owners are pending confirmation.

Granularity: create things by the unit of "independently deliverable and independently ownable". There are no sub-things or groupings; do not try to create a hierarchy. For example, "A, B, and C each sort out one part, then combine into one overall plan" corresponds to 4 things, not 1, and not one per sentence.

Authorization Boundaries

Autonomous execution: create new things; add the first record for a thing you just created yourself.

For things the user has authorized to advance/complete: directly append or update the corresponding progress, and automatically associate the delivery attachments involved this time, then complete publishing and read-back as described in the next section. Personal and shared spaces are the same, and publishing still passes --confirm-share; delivering an authorized thing includes sharing these delivery files to the space where the thing is located.

Rewriting other existing things, changing owners, archiving/restoring, unbinding, and permanent deletion still require explicit authorization; historical binding itself is not authorization. Do not automatically send messages or create scheduled tasks.

Deliver attachment closure

When appending/updating progress, check the files actually delivered this time one by one:

1. Use asset available to look up files in this space and go through all pages. Registered files are associated by assetId, and unregistered files are associated by the returned relative path.
2. For new files that have not yet entered the space, use asset publish: for artifacts not registered in this round, use --conversation-id --run-id --source-path; for existing artifacts, use --artifact-id or --file-token. Save an independent commandId for each file, and reuse it as-is on retry.
3. linked:false indicates published but not associated; use only the returned assetId to supplement asset link, and do not copy again. Publish only the files delivered this time, not temporary files or the entire session directory.
4. asset list --id read back, verify that each attachment exists and availability=available, then read back the progress record. Only when both succeed, report "progress and attachments have been updated"; on failure, clearly distinguish published, associated, and pending recovery.

Attachments use the above file association interface; local path text links cannot replace attachments, and merely copying files does not count as completing delivery. For complete parameters, see the CLI reference.

Current session binding and execution snapshot

Use the binding declaration frozen for this round to determine the default matter for this round. Before executing, reviewing, summarizing, or updating the current matter, read this execution snapshot according to the readCommand in the declaration; ordinary chat does not require reading it. Switching or unbinding during a run only immediately changes the session ownership; this round (including waiting, recovery, and retries) still uses the original snapshot; if there was originally no matter, this round continues to have no default matter, and only the next new Run uses the latest binding. When the user explicitly specifies another matter, still read and operate according to permissions, and do not mistake the session's latest ownership for this round's snapshot.

When the user explicitly requests binding the current conversation to a matter, after uniquely locating the target, execute conversation bind, then use conversation primary to read back and confirm; if matters with the same name cannot be uniquely determined, ask the user. On success, state "bound; the matter context takes effect from the next round". Unbinding must also be confirmed by reading back. Do not treat an ordinary reference to link-conversation as a substitute for successful primary matter binding; if the interface fails, explain truthfully and do not bypass permissions.

context --id <thing-id> --run-id <run-id> returns the business text and version at the time the execution was accepted. When the latest facts or the version before writing are needed, additionally read the real-time context without --run-id , and clearly distinguish the collection time from the snapshot version. When reading fails, disclose the missing information, do not guess from the title, and do not automatically switch to reading real-time data. For the specific contract, see CLI reference。

• Fields are title, description, tags, status, owner, and collaborators. Status is open/paused/done; archiving and restoring are independent actions. Description is required for creation; if owner is omitted at creation, it defaults to yourself, and explicit null is rejected.
• Use members/options to query members and matter candidates; creation, editing, and collaborator management follow server-side permissions. Before modifying, read the latest version; after 409, compare changes and do not merely replace the version number.
• Records use url/note/progress; when the type is omitted, the server saves a single HTTP(S) URL as a link, and others as notes. To update progress, use entry append --type progress; to modify a record, use entry update and expected-updated-at, supporting modifying the title, type, or body separately; --clear-title clears the title.
• To organize a matter from session messages, use from-message, providing the verified conversation-id/message-id and confirmed body; judge whether it should be organized according to the creation signals above, and do not require the user to explicitly name this command. Present inferred content as a suggestion in the session first; do not use the deleted persistent draft modification command.
• Primary matters use conversation primary/bind/unbind, ordinary references use link-conversation, and conversations query associations. Association does not change conversation privacy or permissions.
• Use progress records for milestone results; for handovers, use notes to clearly state completed content, evidence, and next steps. The owner and collaborators are the only personnel collaboration relationship; do not additionally claim.
• Files use asset available/list/link/unlink/publish, following the authorization boundary above and the delivery attachment closed loop; unlinking does not delete the file.
• For permanent deletion, first read the latest version, explain that it is irreversible and the conversation/file retention boundary, and after explicit confirmation use delete --confirm-delete --yes. When there is a run conflict, wait; do not automatically terminate the run.
• Specific modifications that have already been explicitly authorized are executed directly without asking again.

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

Review uses ae-things-review, periodic summaries use ae-things-progress. Both summarize based on the complete collected facts, preserving the boundaries of unread files, truncation, and non-transactional collection.

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.