@thinkingai/ae-cli 6.1.25 → 6.1.27

package/skills/ae-kb/references/query-workflow.md

@@ -1,9 +1,9 @@
 # ae-kb deterministic query workflow
 
 How to answer a knowledge question with the deterministic retrieval primitives
-(`+list` / `+index` / `+grep` / `+read`) instead of `+ask`. Follow this order;
-it is designed to reach the right section in a few calls and to avoid crawling a
-page line by line.
+(`+list` / `+index` / `+grep` / `+read`) instead of `+ask`. Choose the next step
+from the evidence already returned; these are branches, not commands to run on
+every page. Reach relevant evidence without crawling a page line by line.
 
 Use `+ask` when the question requires synthesizing across multiple pages or
 multi-hop reasoning; simple factual lookups are served by the steps below.
@@ -17,7 +17,17 @@ and ranked candidates. Start here with a chosen candidate; scope every `+index`
 turns out not to cover the question, go back to `ae-kb-discovery` for the next
 candidate rather than searching everything blindly.
 
-1. **Index the candidate.** Call `+index --sources` with the discovery pick.
+**Known-page fast path:** within the same host, identity, KB and published revision,
+reuse navigation and read evidence already obtained in this task. Copy exact
+links returned by `+index`, `+grep` or `+read`; go to step 3 for a relevant page
+whose path is known. Do not guess filenames. Once a path is known,
+do not repeat indexing or broad directory searches to rediscover it;
+only read a domain, catalog or parent page when its additional
+context is needed to resolve scope, applicability or an uncovered requirement.
+A revision or access-context change requires revalidation, not silent reuse.
+
+1. **Index the candidate.** If no usable navigation is in context, call
+   `+index --sources` with the discovery pick.
    Use `index.md` for navigation, a fit check, and **query wording** — the real
    terms in the index (product names, API identifiers, section titles) become
    your `+grep` keywords. The root index routes at module level only; when a
@@ -30,32 +40,33 @@ candidate rather than searching everything blindly.
    **Done when:** you have the candidate's `index.md`, and a list of `wiki/...`
    links you can **copy** (0 items still counts as done).
 
-2. **Grep copied paths.** Copy 1–3 `wiki/...` entries from the index (a page
+2. **Grep copied paths.** When no sufficiently specific page link is known,
+   copy 1–3 `wiki/...` entries from the navigation already returned (a page
    such as `wiki/sandbox.md`, or a subdirectory such as `wiki/guides`). Call
    `+grep` with the candidate `--sources` and the copied list as `--paths`. Search
-   with the index terms. If the first grep misses, rewrite the query **once**
-   using different index terms **only** — never paraphrase the user's wording
-   from memory — still with this same `--paths`. If the rewrite also misses,
-   stop grepping entirely: `+read --outline` the index page whose title or
-   section name relates to the question and read the matching heading range
-   from it. A third rewrite of the same idea produces no new recall.
+   with the terms in the returned navigation. If the first grep misses, rewrite
+   the query **once** using different terms from that navigation, still with
+   the same `--paths`. If the rewrite also misses, choose the likeliest linked
+   page and use step 3, or return to discovery. A third rewrite of the same
+   idea produces no new recall.
 
    **Done when:** you have hits, or you have rewritten once, or step 1 copied
-   0 paths. Copied 0 paths → skip grep and `+read --outline` the likeliest
-   title page, or go back to discovery for the next candidate.
+   0 paths. Copied 0 paths → skip grep and go back to discovery rather than
+   constructing a path from a title.
 
    **Reading the result — the page-level `results` view.** The response is a page-level
    `results` array: each entry is one page with its full `hitCount`, a
    `pageKind`, and up to 4 `sections` previews (each with its breadcrumb,
    `sectionStartLine`/`sectionEndLine`, and a text preview). Read the top
    relevant pages until every subquestion of the question is backed by
-   sections you have actually read. `hitCount` tells you how dense the matches
+   sections you have actually read (step 4 distinguishes business analysis
+   from knowledge-only coverage). `hitCount` tells you how dense the matches
    are on a page; `pageKind: "catalog"` marks a module directory page — its
    previews are detail-page entries, so treat them as navigation: add the
    detail-page paths you see there to your read list instead of reading the
    catalog as an answer source. When a page has `moreSections > 0` and the
-   answer is not in the previews, re-grep that single page to see all its
-   hits.
+   answer is not in the previews, locate the missing evidence on that single
+   page using step 3 rather than searching its entire directory again.
 
    Each page-group section preview carries its enclosing heading-section
    boundaries:
@@ -73,6 +84,15 @@ candidate rather than searching everything blindly.
 3. **Choose the section locator.** Pick one locator for the current target
    page:
 
+   - **Short or unknown-length linked page:** for a focused recall card or
+     asset-definition page, read once with
+     `--offset 1 --limit 200 --expand none`; an outline is not a prerequisite.
+     If a response already shows a longer page or a precise relevant section,
+     use the section branches below instead. Check the returned coverage:
+     `startLine: 1`, `endLine: totalLines`, and `truncated: false` prove a
+     complete page. If partial, locate only the missing evidence on the same page
+     with scoped grep or an outline; a bounded prefix is not proof of full
+     coverage. Do not reuse a range from another page.
    - **Section preview of a page group:** read the section range with
      `--offset sectionStartLine` and
      `--limit sectionEndLine - sectionStartLine + 1`. For narrow
@@ -80,10 +100,10 @@ candidate rather than searching everything blindly.
      once you see the preview text. If the window turns out too small, widen
      once up to the section range. Do not crawl by shifting offsets line by
      line.
-   - **Linked or related page:** if you follow a catalog/detail/related link to
-     a different page, the old grep range no longer applies. If you have
-     concrete terms for that new page, run `+grep --paths '["<new-page>"]'`
-     scoped to that page and use the new hit range.
+   - **Linked or related page needing section localization:** if the direct
+     read branch does not apply and you have concrete terms for that new page,
+     run `+grep --paths '["<new-page>"]'` scoped to that page and use the new
+     hit range. An explicit child link needs no catalog or directory lookup.
    - **No reliable range:** if the new page has no concrete grep terms, its
      grep misses, or headings are needed to choose the right section, call
      `+read --outline` for that page. It returns only the heading tree
@@ -102,30 +122,44 @@ candidate rather than searching everything blindly.
    come from a page-group section preview's boundaries or two adjacent outline
    headings (`heading.line` of the target section to `heading.line - 1` of the
    next). If a window turns out too small, widen to the section boundary in one
-   more call.
+   more call. A completed direct read in step 3 needs no additional read or
+   outline. Independent, already identified pages may be read in parallel;
+   follow only links needed for the question, not every related page.
 
    **Done when:** the needed evidence is in context without shell truncation,
    or the page response is complete and untruncated.
 
-   **Read coverage:** read the relevant candidate pages from the page results
-   until every subquestion of the user's question is backed by sections you
-   have actually read — not until a page "looks like the answer". Do not stop
-   to compose the answer while any subquestion still has no read evidence
-   behind it, and do not pick a single page by surface similarity between the
-   question wording and the page/module name or hit line.
+   **Read coverage:** for knowledge-only answers, read relevant candidate pages
+   until every answered subquestion is backed by sections actually read — not
+   until a page "looks like the answer". For business data analysis, read the
+   relevant definitions and boundaries, then hand off verified coverage and
+   remaining gaps in step 5; live values do not need KB text as their source.
+   Do not pick a single page by surface similarity between the question wording
+   and the page/module name or hit line.
 
 5. **Assess coverage, then answer or iterate.** Map the user's question into
    subquestions and check each one against the sections you actually read. If a
    subquestion is covered, answer with citations (knowledge base + page path +
    section). If a gap remains, go back to step 2 with another set of `--paths`
-   **copied** from the index, or return to discovery for the next candidate.
-   If the evidence is missing after the allowed search, the only acceptable
-   output for that subquestion is "not covered by the knowledge base" — do not
-   attach a confident value from general knowledge, not even with a disclaimer
-   or a self-declared boundary.
+   **copied** from current navigation, or return to discovery for the next candidate.
+   For a knowledge-only question, missing evidence after the allowed search
+   means "not covered by the knowledge base" — do not attach a confident fact
+   from general knowledge, even with a disclaimer. For business data analysis,
+   this is a KB coverage gap, not completion of the original task. Preserve the
+   read KB evidence and continue through `ae-analysis` using
+   [`analysis-workflow.md`](analysis-workflow.md): verify suitable saved assets,
+   resolve only missing metadata, and execute an independently supported,
+   authorized query. Never attribute that live result to unread KB content.
+
+   Once relevant definitions, parameters and boundaries are covered, proceed
+   to the analysis handoff. Do not keep navigating to validate already verified
+   links or to seek live numbers in a semantic snapshot. Return to KB retrieval
+   only for a concrete unresolved semantic question.
 
    **Done when:** every answered subquestion is supported by read sections, or
-   the remaining gaps are explicitly reported as missing evidence.
+   the remaining knowledge gaps are explicitly reported as missing evidence.
+   A business data request still requires the analysis handoff and its task
+   completion check; routing or definition-only coverage is not a live answer.
 
 ## Anti-pattern: same-page offset crawling
 

package/skills/ae-kb/references/schema-import.md

@@ -5,7 +5,7 @@
 | Command | Required flags | Purpose |
 | --- | --- | --- |
 | `+schema-download` | `--name --output` | Download original formal bytes |
-| `+schema-import` | `--name --file --request-id` | Upload Markdown; automatically validate |
+| `+schema-import` | `--name --file --request-id` | Upload Markdown with basic checks; AI validation is explicit |
 | `+schema-import-list` | `--name` | List pending candidates; `--cursor/--limit` |
 | `+schema-import-status` | `--import-id` | Read report, revision and receipt |
 | `+schema-import-content` | `--import-id` | Read full candidate; `--target/--output` |
@@ -14,7 +14,7 @@
 | `+schema-import-validate` | `--import-id --revision --request-id --hash` | Explicit validation |
 | `+schema-import-optimize` | `--import-id --revision --request-id --hash` | One repair and independent revalidation; repeat `--issue-id` |
 | `+schema-import-reject` | `--import-id --revision --request-id` | Restore latest repair input; no recursive undo |
-| `+schema-import-apply` | `--import-id --revision --request-id --hash --report-id` and exactly one of `--schema-hash/--schema-absent` | Explicit formal replacement |
+| `+schema-import-apply` | `--import-id --revision --request-id --hash` and exactly one of `--schema-hash/--schema-absent` | Explicit formal replacement; optional `--report-id` |
 | `+schema-import-abandon` | `--import-id --revision --request-id` | Abandon draft; high-risk write |
 
 Use `--scope personal|company` for name lookup. All subsequent operations use the returned import ID, never resolve a name again. Upload may explicitly replace one pending import with `--replaces-import-id/--replaced-revision`; otherwise it creates an additional draft.
@@ -23,7 +23,9 @@ Upload, validation, optimization and status support `--wait --timeout <seconds>`
 
 Before applying, read `+schema-import-diff --baseline current-schema`, the entire candidate and advisories. Use the returned formal hash. `KB_SCHEMA_IMPORT_BASE_CHANGED` requires reviewing a fresh diff and explicit confirmation; never refresh the hash and automatically replay apply. Revision/request conflicts preserve your file. `settlementPending/recoveryRequired` means an administrator must inspect the operation; it is not an applied success. Applying does not compile or create a published version. Existing Wiki content needs a later compilation.
 
-Candidates are shared between Web and CLI for the same user. Closing either client does not abandon saved work. Save makes a new human baseline only when bytes change. Failed/unavailable validation never permits apply. No automatic model retry loop exists.
+Normal initialization can apply a reviewed, release-accepted preset without a new AI report. Existing valid formal rules are reused on refresh without upload, application, generation or AI validation. Legacy callers may still pass `--report-id`; it is omitted from JSON when absent. Servers with an older mandatory-report contract reject this fast path; surface that incompatibility rather than invent a report or silently generate rules.
+
+Candidates are shared between Web and CLI for the same user. Closing either client does not abandon saved work. Save makes a new human baseline only when bytes change. Application admission follows the current server's basic checks and `canApply` response. AI validation is explicit and optional; it is recommended once when authoring a reusable preset. Keep its complete passing report and exact content hash before releasing that preset. No automatic model retry loop exists.
 
 ## Transitional transport
 

package/skills/ae-kb/references/source-mutations.md

@@ -11,6 +11,8 @@ These commands require a host exposing the External KB source-mutation and previ
 
 All new commands use `kb source <action>`. Existing `+source-put`, `+source-rm` and whole-KB `+rollback` keep their original behavior.
 
+For ordinary `.md`, `.markdown` and `.txt` sources, [the text workflow](text-sources.md) also supports `replace --text` or `--stdin` using the complete text API and the same required revision. `--file` continues to use the original multipart replacement contract below.
+
 ## Replace a file source
 
 ```bash
@@ -88,8 +90,8 @@ Keep the structured `error.code` and `hint`. `SOURCE_CONTENT_REVISION_CONFLICT`,
 ## Transitional admission
 
 - Transition status: transitional
-- Owning module: te-claude External Knowledge Base source mutation/version APIs
-- Current transport: authenticated external REST through `kbApi` / `kbUpload`, using only the standard CLI token
-- Gateway target: TBD; no equivalent typed source replacement/restore capability is registered in the current backend implementation
-- Review after: 2026-12-15
+- Owning module: te-claude knowledge-base source management
+- Current transport: External Knowledge Base REST API
+- Gateway target: TBD
+- Review after: 2026-11-12
 - Exit condition: migrate to equivalent Gateway capabilities while retaining typed file handling, revision guards, preview confirmation and stable outcomes, or remove redundant wrappers when dynamic invocation provides the same contract

package/skills/ae-kb/references/text-sources.md

@@ -0,0 +1,53 @@
+# Ordinary text sources
+
+Use these commands for ordinary `.md`, `.markdown` and `.txt` sources, including existing uploads. Text is a content filter on `sourceType=file`, not a new source type. ZIP children and URL collection output use their original commands.
+
+## Create
+
+Copy the exact knowledge base name and `personal` or `company` scope from `kb +list`. Choose exactly one input:
+
+```bash
+ae-cli kb source create-text --name "Handbook" --scope company --text "Release notes" --dry-run
+ae-cli kb source create-text --name "Handbook" --scope company --title "Release notes" --file ./notes.md
+cat ./notes.txt | ae-cli kb source create-text --name "Handbook" --scope company --stdin
+```
+
+Each request creates one independent Markdown file source. `--file` reads one UTF-8 `.md`, `.markdown` or `.txt` file (case-insensitive); the server generates a title from the content unless `--title` is supplied, adds `.md`, and resolves duplicate names with a sequence number. To retain a local filename or upload other formats, use `kb +add`. The response `item` contains the final display name, stable ID, current `contentRevision` and pending compilation state.
+
+Transport: `POST /agent/api/external/knowledge-bases/sources/text`, JSON `{name, scope, content, title?, inputMethod:"text_input"}`.
+
+## Read and edit the same source
+
+```bash
+ae-cli kb +list-sources --name "Handbook" --scope company --content-type text
+ae-cli kb source read-text --name "Handbook" --scope company --id <source-id>
+ae-cli kb source read-text --name "Handbook" --scope company --id <source-id> --out ./original.md
+ae-cli kb source replace --name "Handbook" --scope company --id <source-id> \
+  --source-type file --expected-revision <contentRevision> --text "Revised notes"
+cat ./revised.md | ae-cli kb source replace --name "Handbook" --scope company --id <source-id> \
+  --source-type file --expected-revision <contentRevision> --stdin
+```
+
+`read-text` returns complete `{item, content, contentFormat}` in the standard JSON envelope. `item.contentRevision` corresponds to these exact bytes; `contentFormat` is `markdown` or `text`. `--out` exclusively creates a new local file and returns only `{item, contentFormat, out}`. Existing files and symlinks are never overwritten. A read does not establish write permission.
+
+Text replacement sends `PUT .../sources/<id>/text?name=...&scope=...` with `{content, expectedRevision, inputMethod:"text_input"}`. It preserves the existing source ID, name and format. The original `replace --file` path continues to send multipart data to `/raw` or prepare a ZIP preview, as described in [source mutations](source-mutations.md).
+
+Read after saving and compare the complete bytes and revision. An unchanged save reports `outcome=unchanged` without increasing the revision; a real change reports the actual mutation result and new revision. `SOURCE_CONTENT_REVISION_CONFLICT` exits nonzero: retain local input, read current content and explicitly resolve the conflict. The CLI never obtains a new revision or retries a write automatically.
+
+## Encoding, limits and outcomes
+
+- File and stdin input must be strict UTF-8. BOM, LF/CRLF/CR, mixed line endings and the presence or absence of a trailing newline are preserved. Quotes, backticks and Unicode remain business data. `--stdin` is explicit and requires a pipe; missing input never waits for interactive text.
+- Empty or whitespace-only text is rejected. The limit is 50 MiB (52,428,800 UTF-8 bytes), including BOM and newlines. Exactly the limit is allowed. JSON escaping overhead is separate; valid content is never truncated.
+- Creation and replacement are ordinary `write` commands without a second confirmation. A `--dry-run` validates local input and previews the request with content redacted, sends no business request, and cannot prove host permissions or a current revision.
+- Text flags are sensitive. Text input, full read responses and server error details are excluded from command and HTTP diagnostics; structured errors retain the server code and safe recovery guidance. Explicit `read-text` JSON or `--out` content is the requested business result.
+- An unsupported host fails explicitly; the CLI does not fall back to upload or delete/re-add. If the outcome is unknown, inspect `+list-sources` and read the source before deciding on another request; retrying creation can create another independent source.
+- Saving does not compile or publish. After reviewing all changes, explicitly use `kb +compile` and inspect `kb +status`. Failed compilation preserves prior published knowledge. Deletion uses existing `+rm-source` confirmation and publication semantics.
+
+## Admission record
+
+- Transition status: transitional
+- Owning module: te-claude knowledge-base source management
+- Current transport: External Knowledge Base REST API
+- Gateway target: TBD
+- Review after: 2026-11-12
+- Exit condition: when equivalent text and revision capabilities enter the Gateway, migrate the typed commands to the shared transport where their file, stdin, revision and output handling adds value, while preserving released command compatibility.

package/skills/ae-kb-discovery/SKILL.md

@@ -72,7 +72,7 @@ A candidate returned by `+list`, navigation returned by `+index`, a successful c
 
 ## Use Knowledge Base Evidence in Analysis
 
-For project-scoped business data analysis, the `analysis-workflow.md` handoff above is mandatory after relevant source pages have been read. In particular, a KB statement that current values require live execution means attempting the matched saved asset first. If that attempt cannot produce a usable result, the workflow permits a traceable fallback to ordinary analysis.
+For project-scoped business data analysis, the `analysis-workflow.md` handoff above is mandatory after relevant source pages have been read. Attempt an exact, semantically applicable saved asset first. If definition inspection proves it unsuitable, or execution cannot produce the requested result, continue ordinary analysis for the uncovered requirements without discarding verified KB evidence. A KB statement that current values require execution does not require running a known mismatching asset or asking the user to repeat the data request.
 
 When using internal context to explain data analysis results, anomalies, or trends:
 

package/skills/ae-team/SKILL.md

@@ -16,20 +16,22 @@ AE CLI (`ae-cli`) is the command-line tool for the AE (Agentic Engine) analysis
 
 Global parameters:
 
-| Parameter | Description |
-|---|---|
-| `--format <json\|table>` | Output format. Default is JSON. |
-| `--jq <expr>` | jq filter expression for JSON output. |
-| `--host <url>` | Override the active AE host. Available on every command and may be placed after the subcommand, e.g. `ae-cli team +<command> --host <url>`. |
-| `--yes` | Skip confirmation for `high-risk-write` (delete) operations. |
-| `--dry-run` | Show request details without executing. |
+| Parameter                | Description                                                                                                                                 |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--format <json\|table>` | Output format. Default is JSON.                                                                                                             |
+| `--jq <expr>`            | jq filter expression for JSON output.                                                                                                       |
+| `--host <url>`           | Override the active AE host. Available on every command and may be placed after the subcommand, e.g. `ae-cli team +<command> --host <url>`. |
+| `--yes`                  | Skip confirmation for `high-risk-write` (delete) operations.                                                                                |
+| `--dry-run`              | Show request details without executing.                                                                                                     |
 
 Output and errors:
+
 - Successful commands return machine-readable JSON by default. Envelope may include optional `_notice.host_compat`.
 - Failed commands return `{ "ok": false, "error": { "type": "...", "message": "...", "hint": "..." } }` and exit non-zero.
 - **CRITICAL — Host compat (do this first):** If stderr or `_notice.host_compat` has a version warning, open the user reply with ⚠️ and **quote `npm i -g` / `npx skills add` (or update-cluster) lines verbatim**, then list projects/results. Never omit when summarizing. Soft tip; `ok: true` may still include the notice.
 
 Safety constraints:
+
 - Read commands (`+list`, `+list-templates`, `+list-projects`, `+run-result`, `+run-artifacts`, `+ai-generate`) can execute directly once required IDs are known.
 - Ordinary `write` commands require explicit user intent but no CLI confirmation. Only `high-risk-write` commands use the confirmation gate and may receive `--yes` after explicit user authorization.
 - Never invent team IDs, run IDs, `agentId` values, `mcpServerIds`, `skillIds`, `knowledgeBaseIds`, project IDs, or any resource identifiers. Discover them with list commands or accept them from the user.
@@ -81,16 +83,16 @@ ae-cli team +run-start --help
 
 ## TeamRun Status Reference
 
-| Status | Description |
-|---|---|
-| `pending` | Queued, waiting to start |
-| `running` | Actively executing |
-| `waiting_user` | Paused — `+run-watch` exits with code 2; read `pendingQuestion` from stdout, present to user, then call `+run-reply` |
-| `waiting_approval` | Paused — waiting for approval |
-| `paused` | Manually paused |
-| `completed` | Finished successfully |
-| `failed` | Execution failed |
-| `cancelled` | Cancelled by user |
+| Status             | Description                                                                                                          |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------- |
+| `pending`          | Queued, waiting to start                                                                                             |
+| `running`          | Actively executing                                                                                                   |
+| `waiting_user`     | Paused — `+run-watch` exits with code 2; read `pendingQuestion` from stdout, present to user, then call `+run-reply` |
+| `waiting_approval` | Paused — waiting for approval                                                                                        |
+| `paused`           | Manually paused                                                                                                      |
+| `completed`        | Finished successfully                                                                                                |
+| `failed`           | Execution failed                                                                                                     |
+| `cancelled`        | Cancelled by user                                                                                                    |
 
 Terminal statuses: `completed`, `failed`, `cancelled`. Poll `+run-result` until one of these is reached.
 
@@ -163,3 +165,7 @@ ae-cli team +create --name "我的分析团队" --config '<template_config>'
 ```bash
 ae-cli team --help
 ```
+
+## Automation lifecycle
+
+For Agent or team automation schedules, immediate execution, stop, retry, deletion, history and read-only results, use [ae-automation](../ae-automation/SKILL.md). Existing Agent automation aliases remain compatible.

package/skills/ae-things/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: ae-things
+description: "工作空间事项（things）：在明确的 AgentSpace 中用 ae-cli things 创建、查询、更新和推进事项。当对话出现分工指派（谁负责什么）、要交付的产出、推进节奏、待办、下一步、里程碑或阶段计划时主动使用——不需要用户显式说「创建事项」。"
+---
+
+# 工作空间事项
+
+使用 `ae-cli things` 操作当前明确指定的 TE 空间事项。先读 [CLI reference](references/cli.md)，不猜 ID，不自动选择其他空间。
+
+## 何时创建事项
+
+**由你自己判断要不要建，不要等「帮我创建事项」这种显式指令。** 个人空间与共享空间一视同仁。
+
+出现下列任一信号就直接创建，不必先问：
+
+- 出现「谁做什么」的分工指派，例如「让 A 梳理 X，B 梳理 Y」。
+- 出现要交付的产出加上推进意图，例如「输出一份最终方案」「按这个节奏推进」「安排一下」。
+- 出现承诺、待办、下一步、里程碑或多阶段计划。
+- 用户在复述已经定下来的事，并指向后续执行。
+
+下列情况不要创建：
+
+- 纯信息问答、概念解释、闲聊。
+- 还在比较方案、假设性推演，或用户明确说「先不定」。
+- 查重命中已有同义事项——指出已存在，不重复建。
+- 用户说过不要建。
+
+**不确定时，把拟建清单（标题、负责人、描述要点）在回复里列出来，一次性问用户确认。不允许什么都不做就把分工排版成清单交差。**
+
+### 创建时的动作顺序
+
+1. 确认已绑定明确的 AgentSpace；没有绑定就不创建。
+2. `members` 取成员列表，把对话里提到的人名映射到成员 ID。唯一命中就直接作为 `--assignee-id`；命中 0 个或多个时该事项负责人留空（服务端默认当前用户），并在回复里点名待确认。
+3. `list --query` 或 `options --query` 查重。
+4. 逐个 `create`：标题写可交付物而不是原话复述，描述写清目标与验收要点，带 `--command-id` 保证重试幂等。
+5. 需要时用 `conversation bind` 绑定主事项，或 `link-conversation` 建普通引用。
+6. 在回复里报告已创建的事项编号、标题、负责人，以及哪些负责人待确认。
+
+**粒度**：按「可独立交付、可独立负责」的单位建事项。没有子事项和分组，不要试图建层级。例如「A、B、C 各自梳理一块，然后合成一份总方案」对应 4 个事项，而不是 1 个，也不是每句话一个。
+
+### 授权边界
+
+自主执行：创建新事项；为自己刚建的事项补第一条记录。
+
+用户已授权推进/完成的事项：直接追加或更新相应进展，并自动关联本次涉及的交付附件，按下节完成发布与回读。个人与共享空间一致，发布仍传 `--confirm-share`；授权事项交付即包含向该事项所在空间共享这些交付文件。
+
+其他已有事项改写、负责人变更、归档/恢复、解绑及永久删除仍需明确授权；历史绑定本身不是授权。不自动发消息或创建定时任务。
+
+### 交付附件闭环
+
+追加/更新进展时，逐个核对本次实际交付文件：
+
+1. 用 `asset available` 查本空间文件并翻完分页。已登记文件按 assetId 关联，未登记文件按返回的相对 path 关联。
+2. 尚未进入空间的新文件用 `asset publish`：本轮未登记产物使用 `--conversation-id --run-id --source-path`；已有产物使用 `--artifact-id` 或 `--file-token`。每个文件保存独立 commandId，重试原样复用。
+3. `linked:false` 表示已发布未关联，只用返回 assetId 补 `asset link`，不重复复制。只发布本次交付文件，不发布临时文件或整个会话目录。
+4. `asset list --id` 回读，核实每个附件存在且 availability=available，再回读进展记录。只有两者均成功才报告“进展和附件已更新”；失败明确区分已发布、已关联、待恢复。
+
+附件使用上述文件关联接口；本地路径文本链接不能代替附件，仅复制文件也不算交付完成。完整参数见 CLI reference。
+
+## 当前会话绑定与执行快照
+
+以本轮冻结的绑定声明确定本轮默认事项。涉及当前事项执行、审查、总结或更新前，按声明中的 `readCommand` 读取本次执行快照；普通聊天无需读取。运行中切换或解绑只立即改变会话归属，本轮（含等待、恢复、重试）仍用原快照；原先无事项则本轮继续无默认事项，下一次新 Run 才使用最新绑定。用户明确指定其他事项时仍按权限读取和操作，不将会话最新归属误认为本轮快照。
+
+用户明确要求将当前对话绑定到某事项时，唯一定位目标后执行 `conversation bind`，再用 `conversation primary` 回读确认；同名事项不能唯一确定时询问用户。成功说明「已绑定，事项上下文从下一轮生效」。解绑也须回读确认。不得将 `link-conversation` 普通引用当成主事项绑定成功的替代；接口失败应如实说明，不绕过权限。
+
+`context --id <thing-id> --run-id <run-id>` 返回执行受理时的业务文本和版本。需要最新事实或写入前版本时额外读取不带 `--run-id` 的实时上下文，并明确区分采集时间与快照版本。读取失败时披露缺失，不凭标题猜测，也不自动改读实时数据。具体契约见 [CLI reference](references/cli.md#执行快照与实时上下文)。
+
+- 字段为标题、描述、标签、状态、负责人、协作者。状态 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-review/SKILL.md)，周期汇总使用 [ae-things-progress](../ae-things-progress/SKILL.md)。二者按完整采集事实归纳，保留未读文件、截断和非事务采集边界。
+
+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.

package/skills/ae-things/references/cli.md

@@ -0,0 +1,103 @@
+# 工作空间事项 CLI reference
+
+本 reference 描述已实现命令，不重复维护权限和数据业务规则。[主 Spec](https://gitlab.thinkingdata.cn/te-ai/te-claude/-/blob/feat/workspace-issues-convergence/docs/specs/2026-09-17-workspace-issues-convergence/spec.md)。
+
+Transition status: transitional
+Owning module: te-claude / src/lib/agent-space-things
+Current transport: TE REST /api/cli/things/v1; cli-token
+Gateway target: Capability Gateway things domain (TBD)
+Review after: 2026-10-14
+Exit condition: Gateway 提供等价空间校验、幂等、权限、分页和会话关联能力后迁移 transport。
+
+事项尚未接入 Gateway。类型化 flags、JSON/stdin、正文脱敏 dry-run、默认值和目标一致性检查提供必要的 Transitional 入口。
+
+## 公共参数
+
+`--agent-space-id` 在会话外必填，会话内须与当前会话空间一致。`--id` 为事项 ID。写请求用 `--command-id <uuid>` 支持原样重试，省略时生成；编辑、归档和恢复须带 `--expected-version`。分页为 `--limit 1..100 --cursor <opaque>`，默认 50。通用 `--format json` 输出结构化结果；`--dry-run` 不请求业务 API、不读取文件/stdin、不泄露正文。主事项解除、删除资产关联或协作者属于 high-risk-write，已获授权的脚本使用 `--yes`。
+
+## 字段和记录
+
+事项字段仅为 title、description、tags、status、assigneeId、collaboratorIds。新建标题 1–200 字符、描述 1–10000 字符必填。活跃状态 `open | paused | done`，归档和恢复使用独立动作。个人或共享空间创建时省略负责人均默认当前用户；更新省略保持不变，`null` 被拒绝。`--tags '["标签"]'`、`--collaborator-ids '["member-id"]'`，空数组清空。`--assignee-id` 只能指定有效空间成员。
+
+新建/更新可用 `--file fields.json` 或 `--stdin` 读取 camelCase 字段对象，显式 flags 覆盖同名字段。失效的验收、优先级、分组、截止时间、进展快照、阻塞、下一步、父子事项字段被拒绝；group 和 draft 命令已移除。
+
+| 命令                      | 参数和结果                                                                                                                                                                                                         |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `list`                    | `--query --status open\|paused\|done\|archived --assignee-id`；返回 items/nextCursor                                                                                                                               |
+| `get`                     | `--id`；字段、权限、version、协作者及 latestProgress                                                                                                                                                               |
+| `create`                  | `--title --description` 和可选业务字段                                                                                                                                                                             |
+| `update`                  | `--id --expected-version` 和业务字段                                                                                                                                                                               |
+| `archive/restore`         | `--id --expected-version`                                                                                                                                                                                          |
+| `delete`                  | `--id --expected-version --confirm-delete --yes`；不可恢复，清理事项及所有关联，保留会话、消息、历史运行快照与空间文件；活动运行冲突返回 THING_RUNNING_CONFLICT                                                    |
+| `members/options`         | 分页查询成员/事项候选；options 支持 `--query`                                                                                                                                                                      |
+| `collaborator add/remove` | `--id --user-id`                                                                                                                                                                                                   |
+| `entry list`              | `--id` 和分页，按 createdAt、id 倒序                                                                                                                                                                               |
+| `entry append`            | `--id --type url\|note\|progress`；省略时服务端自动识别链接或备注，可选 `--title`；`--content`、`--file`、`--stdin` 三选一                                                                                         |
+| `entry update`            | `--id --entry-id --expected-updated-at`；至少一个修改字段：`--title`、`--clear-title`、`--type note\|url\|progress` 或正文输入；可只改标题或类型，title 与 clear-title 互斥                                        |
+| `from-message`            | `--conversation-id --message-id` 和正文；`--id` 追加或 `--title` 新建二选一；仅 `--id` 追加模式可选 `--entry-type note\|progress`，默认 note；`--title` 新建模式传入会报错，新建以正文作为描述，不生成额外进展记录 |
+
+```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
+```
+
+## 会话
+
+| 命令                       | 参数和含义                                            |
+| -------------------------- | ----------------------------------------------------- |
+| `conversation get`         | `--conversation-id`；读取可访问会话快照及当前模型投影 |
+| `conversation primary`     | `--conversation-id`；读取主事项关联                   |
+| `conversation bind/unbind` | `--conversation-id`；bind 额外需要 `--id`             |
+| `conversations`            | `--id` 和分页；关联会话                               |
+| `link-conversation`        | `--id --conversation-id`；追加引用，不替换主事项      |
+
+关联不授予会话访问权；不能读取其他用户私有会话。会话排队、运行或等待交互时允许绑定/解绑，立即更新归属但不修改已受理 Run 的冻结上下文，下一次新 Run 生效。绑定后用 `conversation primary` 回读，不使用普通引用代替主事项绑定。
+
+## 进展与汇总
+
+阶段成果写 `entry append --type progress`；交接写 `--type note`，用标题和正文说明已完成内容、证据、下一步。人员关系使用负责人和协作者，不需要认领。
+
+`+detail --id` 收集事项、全部可读 entries/assets 和实时 context。`+digest` 支持负责人筛选或 `--thing-ids id-a,id-b`，不能同时指定两种范围；可选 `--from --to --time-zone`，时间须带时区，窗口左闭右开。默认分别分页采集活动与归档事项，跨集合按 ID 去重。返回 open/paused/done 三态 counts、archivedCount、items 和采集边界。latestProgress 使用服务端最新 progress 记录；effectiveProgressCount 只统计 progress 记录，不代表模型已核实内容；status 时间线的 before/after 用于重建基线。
+
+每链最多 100 页/10000 条。异常、重复游标、空页继续或达到上限标 truncated；重复 ID 不解释为完整。报告核对 fetchedCount、truncated、consistency、collectedAt。non_transactional 不是事务快照；changed_during_collection 或截断时 baseline 为 null。counts 是采集时状态，不能当周期末状态。未记录不等于未推进，附件可用不表示已读取或已验收。
+
+## 错误与恢复
+
+THING_INVALID_INPUT 修正参数；THING_FORBIDDEN/THING_NOT_FOUND 不推断不可见资源；THING_READ_ONLY 表示资源只读：归档事项需恢复后编辑，不可用空间需先恢复空间可用性，操作日志不可编辑、应追加新记录；THING_VERSION_CONFLICT/记录时间戳冲突重读并比较，不能只换版本号；THING_COMMAND_CONFLICT 表示同 UUID 不同请求；THING_RATE_LIMITED 等待后用原 commandId 重试。主事项绑定不因运行中而拒绝；永久删除仍保留 THING_RUNNING_CONFLICT 活动运行保护。
+
+## 文件与交付物（阶段4）
+
+`asset available` 分页合并当前空间实际文件和登记元数据；已登记项返回稳定 `assetId`，未登记项 assetId=null、path 为相对路径。`asset link` 接受 `--asset-id` 或 `--path` 二选一，路径关联时校验、登记并关联，列表读取不登记。`asset list --id` 分页读取事项关联。核对 availability 及 scanStatus/scanReason；部分扫描不代表目录完整。
+
+```bash
+ae-cli things asset available --agent-space-id <space-id> --limit 100 --format json
+ae-cli things asset list --agent-space-id <space-id> --id <thing-id> --format json
+ae-cli things asset link --agent-space-id <space-id> --id <thing-id> --asset-id <asset-id> --role attachment --command-id <uuid> --format json
+ae-cli things asset publish --id <thing-id> --conversation-id <conversation-id> --artifact-id <artifact-id> --confirm-share --command-id <uuid> --format json
+ae-cli things asset publish --id <thing-id> --conversation-id <conversation-id> --run-id <run-id> --source-path <absolute-delivered-file> --confirm-share --command-id <uuid> --format json
+ae-cli things asset link --agent-space-id <space-id> --id <thing-id> --path <space-relative-path> --command-id <uuid> --format json
+ae-cli things asset unlink --agent-space-id <space-id> --id <thing-id> --asset-id <asset-id> --command-id <uuid> --format json
+```
+
+- `role` 仅接受 attachment（默认）；deliverable 在正常执行与 dry-run 的参数校验阶段均被拒绝。同一事项与资产只有一个关联。
+- 发布传 `--confirm-share`，授权边界见 Skill。来源为 artifact-id、file-token、source-path 三选一；source-path 必须同时带 run-id，服务端验证执行归属、真实沙箱文件及会话 artifacts 目录边界。发布到空间后所有成员可见。
+- 发布使用既有会话产物发布器。发布回执与资产元数据同事务，使用原 commandId 重试不会再复制。返回 `linked:false, assetId, code:THING_ASSET_LINK_FAILED` 时文件已经共享，用 asset link 只补关联；不重复发布、不声称已交付。
+- 解除关联不删除文件、不恢复私有；被引用的资产删除返回 `AGENT_SPACE_ASSET_REFERENCED`，须先解除关联。
+- `THING_ASSET_UNAVAILABLE` 表示文件缺失或不能验证，`THING_ASSET_PUBLISH_FAILED` 表示发布未完成。文件引用只冻结 ID 和引用文本，不代表不可变正文。上下文最多选取前10份引用，超出会明确提示，完整文件列表按需读取。
+
+## 执行快照与实时上下文
+
+```bash
+# 本次执行使用的冻结事实；参数取自本轮绑定声明
+ae-cli things context --agent-space-id <space-id> --id <thing-id> --run-id <run-id> --format json
+# 显式读取当前事实；不带 run-id 的既有行为保持不变
+ae-cli things context --agent-space-id <space-id> --id <thing-id> --format json
+```
+
+带 `--run-id` 时请求现有 GET context 的 `runId` 参数，返回保存的快照及 `source: {kind: "run_snapshot", runId}`、`currentFiles`、`fileReferencePolicy`。`thing.version`/`capturedAt` 为受理时版本/时间，`currentFiles` 为当前可用路径；文件正文不保证版本冻结，使用前读取。原 `notices` 保留。无参数时返回原实时上下文；不从环境变量自动选择执行，`+detail`/`+digest` 也继续实时采集。
+
+执行、会话、空间及快照中的原事项必须匹配，且操作者仍有访问权限；执行 ID 不是授权。会话当前主事项可以已切换或解除，本轮等待/恢复/重试仍读取原快照。`THING_TARGET_CONFLICT` 表示快照与请求目标不一致，应重新确认目标；`THING_CONTEXT_UNAVAILABLE` 表示快照缺失或损坏，应重新发起执行，不自动降级实时读取。`THING_NOT_FOUND` 不区分不存在和不可见。归档或不可用文件沿用 `THING_READ_ONLY` / `THING_ASSET_UNAVAILABLE`。
+
+切换或解绑保留历史和 provider session，只改变会话归属及下一新 Run 默认目标；不是遗忘或撤权。普通聊天无需查事项，具体事项工作先读快照；当前状态及写入前版本需额外显式实时读取。工具失败时披露缺失。**对已有事项的修改**只按用户明确授权或确认执行，不能因为历史关联过就默认回写；创建新事项不受此限，按 [SKILL 的创建信号](../SKILL.md#何时创建事项)自主判断。
+
+维护模块沿用 Things Transitional transport；新增参数不创建同义命令或独立 Gateway 入口，迁移出口沿用本 reference 的收录记录。跨仓实施契约见 te-claude `docs/specs/2026-09-17-workspace-issues-convergence/spec.md`；应用与 CLI/Skill 配套交付。

package/skills/ae-things-progress/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: ae-things-progress
+description: "工作空间事项进展、日报和周报：使用 ae-cli things 采集当前空间、负责人或显式事项集合的周期事实，由当前会话模型归纳并披露数据边界。"
+---
+
+# 事项进展汇总
+
+从 aha-links 的事实采集和输出契约适配；先读 [事项操作](../ae-things/SKILL.md) 和 [CLI reference](../ae-things/references/cli.md)。CLI 收事实，当前模型做归纳，不调用独立报告后台。
+
+涉及本轮绑定事项时，先遵循 [执行快照与实时上下文](../ae-things/references/cli.md#执行快照与实时上下文) 读取本次执行快照，再按以下流程采集最新审查或周期事实；两种来源分开表述。无绑定时仅使用用户明确指定的范围。
+
+## 范围和时间
+
+```bash
+ae-cli things +digest --agent-space-id <space-id> --from 2026-09-07T00:00:00+08:00 --to 2026-09-14T00:00:00+08:00 --time-zone Asia/Shanghai --format json
+ae-cli things +digest --agent-space-id <space-id> --assignee-id <member-id> --format json
+ae-cli things +digest --agent-space-id <space-id> --thing-ids <id-a>,<id-b> --format json
+```
+
+不猜 ID、不选择个人默认空间；不支持关注清单、群或跨空间汇总。日报按自然日，周报按周一 00:00 到下周一 00:00，默认 Asia/Shanghai。今日／本周的截止点用当前时刻，昨日／上周用完整周期。自定义区间必须明确；命令的 from/to 都必须含时区，区间为左闭右开。
+
+输出时将记录的 ISO 时间转换为报告时区，并在时间窗、采集时间和证据日期旁明确标注时区。例：`2026-09-10T04:50:00Z` 在 Asia/Shanghai 应展示为 `2026-09-10 12:50（Asia/Shanghai）`；不能删除 Z 后直接写成“上海时间 04:50”。无法可靠转换时保留原始 ISO 并标注 UTC，披露尚未转换，不能伪造本地时刻。
+
+## 证据和完整性
+
+核对 `fetchedCount`、`truncated`、`consistency`、`collectedAt`；显式集合再核对 `requestedCount` 和 `unreadable`。字段缺失停止生成全量结论。CLI 自动分页最多每链 100 页／10000 项，异常和上限会标记截断；不能换成单页 list 冒充完整采集。
+
+- `thing` 是当前状态，`entries` 是时间窗内记录，`baseline` 是利用完整业务变更记录倒推的窗口前状态；没有基线或采集发生版本变化时不要补造。
+- `lastEffectiveRecordBeforeWindow` 供定位窗口前证据。当前状态不等于周期内变化，周期末状态也不能直接用当前状态代替。
+- 输出前比较 `collectedAt` 与窗口 `to`。当 `collectedAt < to`（包括用户指定尚未结束的完整自然周）时，报告必须注明“截至采集时刻的阶段汇总，周期尚未结束”；三态统计标为“采集时状态”，禁止写“周期末状态”或“无后续更新”。例：9月10日采集9月7日至14日的周报，不能断言9月14日状态与当前相同。即使窗口已经结束，也只有完整的窗口后变更证据支持时才能还原周期末状态。
+- open/paused/done 分别统计，归档另列；最新进展来自 thing.latestProgress，历史变化读取 progress/status 记录。
+- 备注和重复过程描述不算有效进展；`effectiveProgressCount` 是待核查候选，正文没有新信息时排除。
+- 没有记录只能说“未记录更新”。此约束同样适用于摘要和下一步建议；open 不能证明尚未开始，只能报告当前状态和未记录事实。附件未读、不可读取、截断及多次请求的非事务采集边界必须披露。`changed_during_collection` 时先重读；仍有变化则保留限制，不声称静态全量。
+
+## 输出与写回
+
+先写范围、时间窗、采集时间及覆盖边界，再给三态和归档统计、周期变化、阻塞、下一步。每个重要判断附事项来源和日期，区分事实、推断与建议。不默认展示内部记录 ID。
+
+默认只输出到会话。明确要求写回时：用 `+detail` 完整读取目标事项的报告记录，检查同范围同周期标题，再用 `ae-cli things entry append --id <target-id> --type note --title "事项周报｜起止日期｜范围" --stdin --command-id <uuid> --format json` 写入最终正文。建议标题为 `事项周报｜起止日期｜范围`（日报同理）。已有同范围同周期报告时提示修订，不静默覆盖或重复追加；用户明确要求追加修订后才写新记录，保留原报告。写回已授权无需再问同一许可。
+
+不自动发送消息、修改状态、指派负责人或建立定时任务。
+
+文件证据：+detail/+digest 自动翻页收集资产关联，availability=missing 或 verification_failed 的文件不算可用交付；即使 available，也只代表引用可用，不代表已读取正文或验收通过。披露未读文件及非事务采集边界。私有会话来源只在当前用户有权时读取，报告引用共享事项事实，不能把私有历史自动公开。