@thinkingai/ae-cli 1.0.22 → 1.0.27

package/skills/ae-engage/references/save-task.md

@@ -0,0 +1,304 @@
+# ae-engage `+save_task`
+
+Create or update a Hermes task draft.
+
+Mapped command: `ae-cli engage +save_task`
+
+This command is the final write step. Do not use it as the first step in task construction.
+
+Recommended workflow:
+
+1. `ae-cli engage +channel_list --project_id <projectId>`
+2. `ae-cli engage +build_task_save_guide --project_id <projectId> --req '{...}'`
+3. If the guide indicates QP-derived fields are needed, call:
+
+```bash
+ae-cli analysis_audience +get_cluster_definition_schema --cluster_type condition
+```
+
+4. Build the final grouped `req`
+5. `ae-cli engage +save_task --project_id <projectId> --req '{...}'`
+
+The audience schema query is not a fixed preflight step. Call it only when the guide indicates that you must construct:
+
+- `targetConfig.qp`
+- `triggerConfig.triggerRule`
+- `clientConfig.clientQp`
+- `completionIndicatorDef.event`
+
+For the full guide contract, request format, return sections, and handoff usage, read:
+
+- `references/build-task-save-guide.md`
+
+---
+
+## 1. General Principles
+
+`+save_task` accepts only the final grouped draft-save payload that Hermes can validate and persist.
+
+The command supports two modes:
+
+- create mode: omit `req.taskId`
+- update mode: include `req.taskId` for an existing draft task
+
+Regardless of mode, this tool only saves a draft:
+
+- it does not submit approval
+- it does not start sending
+- it does not register or start trigger execution
+
+The CLI call shape is:
+
+```bash
+ae-cli engage +save_task --project_id <projectId> --req '<req-json>'
+```
+
+Notes:
+
+- `projectId` is injected into top-level `req` by the CLI
+- if the caller also passes `req.projectId`, the outer `--project_id` wins
+- the whole `req` must be a JSON object, not a stringified JSON string
+- for update mode, Hermes only allows modifying draft tasks
+- in update mode, omitted fields are backfilled from the existing draft before validation, so partial draft updates are allowed
+
+---
+
+## 2. Required Workflow
+
+### 2.1 Query Real Channels First
+
+Run:
+
+```bash
+ae-cli engage +channel_list --project_id <projectId>
+```
+
+Purpose:
+
+- get the real project channel list
+- resolve the real `channelId`
+- confirm the final `channelType`
+
+Never invent a `channelId`.
+
+### 2.2 Build the Scenario Guide
+
+Run:
+
+```bash
+ae-cli engage +build_task_save_guide --project_id <projectId> --req '{...}'
+```
+
+Use the guide to determine:
+
+- required grouped blocks
+- required fields for the current trigger and audience mode
+- unsupported combinations
+- correct content schema
+- current handoff template
+- whether the current payload is already close to submit-ready
+
+### 2.3 Query Audience Condition Schema Only When Needed
+
+If the guide indicates that QP-derived fields are needed, run:
+
+```bash
+ae-cli analysis_audience +get_cluster_definition_schema --cluster_type condition
+```
+
+Use the returned schema to build:
+
+- `targetConfig.qp`
+- `triggerConfig.triggerRule`
+- `clientConfig.clientQp`
+- `completionIndicatorDef.event`
+
+Do not call this command by default for every task. It is conditional, not mandatory.
+
+### 2.4 Build Final `req` and Save
+
+Only after the above steps should you construct the final grouped `req` and submit it with `+save_task`.
+
+---
+
+## 3. Final `req` Shape
+
+The final object passed to `--req` should have this grouped shape:
+
+```json
+{
+  "taskId": "<string, optional>",
+  "baseInfo": {},
+  "channelConfig": {},
+  "targetConfig": {},
+  "triggerConfig": {},
+  "controlConfig": {},
+  "expConfig": {},
+  "activityConfig": {},
+  "clientConfig": {}
+}
+```
+
+Top-level notes:
+
+- `taskId` is used only in update mode
+- `baseInfo` / `channelConfig` / `targetConfig` / `triggerConfig` / `controlConfig` are the main blocks
+- optional blocks should usually be omitted rather than filled with invented values
+- use `build_task_save_guide` output as the source of truth for the current scenario
+
+---
+
+## 4. How To Build Major Blocks
+
+### 4.1 `taskId`
+
+Use `taskId` only when you are updating an existing draft task.
+
+- create mode: omit `taskId`
+- update mode: include `taskId`
+- update mode can send only the fields that need changing
+- update mode still fails if the referenced task is not in draft status
+
+### 4.2 `channelConfig`
+
+Core fields:
+
+- `channelType`
+- `channelId`
+- `groupContentList`
+- optional `channelTemplateId`
+
+Rules:
+
+- derive `channelType` and `channelId` from real channel metadata
+- do not guess template IDs
+- `groupContentList` maximum size is `5`
+- `occasionKeys` are parsed from content automatically and are not accepted as input
+
+Content guidance:
+
+- do not invent channel-specific payload structures from memory
+- use `fieldRules.channelContentSchema` from `build_task_save_guide`
+- take valid keys, expected item shape, and examples from the guide
+- when schema fields include `paramType`, copy it exactly
+- do not use free-form content items such as `{"text":"..."}` as the primary pattern
+
+### 4.3 `targetConfig`
+
+Use the guide to decide which audience shape applies:
+
+- `targetClusterType=1`: custom audience, requires `qp`
+- `targetClusterType=2`: existing cluster, requires `clusterKey`
+- `targetClusterType=3`: all users, forbids both `qp` and `clusterKey`
+
+If `qp` is required, construct it from:
+
+```bash
+ae-cli analysis_audience +get_cluster_definition_schema --cluster_type condition
+```
+
+### 4.4 `triggerConfig`
+
+Use the guide to determine the current trigger rule set:
+
+- `triggerType=0`: requires `triggerTime`
+- `triggerType=1`: requires `startDate`, `endDate`, `triggerCrontab`
+- `triggerType=2`: manual, no `triggerRule`
+- `triggerType=3/4/5`: requires `triggerRule`
+
+Rules:
+
+- `triggerType=6` is not supported
+- use the guide for cron format and wrong-example checks
+- if `triggerRule` is needed, build it from:
+
+```bash
+ae-cli analysis_audience +get_cluster_definition_schema --cluster_type condition
+```
+
+### 4.5 `controlConfig`
+
+Minimum required field:
+
+- `completionIndicatorDef`
+
+When the guide points to event-based completion or experiment-driven main-goal rules, use:
+
+```bash
+ae-cli analysis_audience +get_cluster_definition_schema --cluster_type condition
+```
+
+to build `completionIndicatorDef.event`.
+
+Important constraints that still apply:
+
+- `doNotDisturb.enableDoNotDisturb=true` requires `startTime` and `endTime` in `HH:mm`
+- `pushDelay.enablePushDelay=true` requires valid `delayType`, and its dependent fields must match the selected mode
+- `pushDelay.delayType=1` is only valid for `client_push`
+- `pushDelay.delayUnit` must stay within `week`, `day`, `hour`, `minute`, `second`
+- `timeoutControl.enableTimeoutControl=true` requires valid `time` and `unit`
+- `timeoutControl.unit` must stay within `day`, `hour`, `minute`
+
+### 4.6 `clientConfig`
+
+Use this block only when client-side conditions are needed.
+
+If `clientConfig.clientQp` is required, build it from:
+
+```bash
+ae-cli analysis_audience +get_cluster_definition_schema --cluster_type condition
+```
+
+Only call that schema query when the guide explicitly shows that the field is needed.
+
+---
+
+## 5. Final Self-Check Before `+save_task`
+
+Before submission, verify:
+
+1. `channelId` comes from a real channel query.
+2. `build_task_save_guide` has already been called for the current scenario or partial draft.
+3. `fieldRules.channelContentSchema` was used as the source of truth for content structure.
+4. Any required QP-derived fields were built from `ae-cli analysis_audience +get_cluster_definition_schema --cluster_type condition`.
+5. `targetClusterType` matches the presence or absence of `clusterKey` / `qp`.
+6. `triggerType` matches the provided scheduling or event fields.
+7. `completionIndicatorDef` is present and structurally valid for the current scenario.
+8. `taskId` is omitted for create mode and present only for updating a draft.
+9. No unsupported `triggerType=6` is used.
+10. No placeholder IDs or fabricated resource names remain in the request.
+
+---
+
+## 6. Standard Example Flow
+
+Use this style of workflow, rather than jumping directly to `+save_task`:
+
+```bash
+ae-cli engage +channel_list --project_id 1
+ae-cli engage +build_task_save_guide --project_id 1 --req '{"context":{"triggerType":2,"channelId":"channel_123"}}'
+ae-cli engage +save_task --project_id 1 --req '{...final grouped req...}'
+```
+
+If the guide indicates QP-derived fields are needed, insert:
+
+```bash
+ae-cli analysis_audience +get_cluster_definition_schema --cluster_type condition
+```
+
+before building the final `req`.
+
+---
+
+## 7. Safety Constraints
+
+This command is a write operation.
+
+- Do not treat `save_task` as “submit and launch task”
+- Do not bypass `build_task_save_guide`
+- Do not pass the whole `req` as a JSON string
+- Do not use `triggerType=6`
+- Do not invent `channelId`, `clusterKey`, audience definitions, or content keys
+- Do not use `taskId` for a non-draft task
+- Do not pass `occasionKeys`; Hermes derives them from content
+- Do not call the audience schema query as a reflex; call it only when guide output says QP-derived fields are needed

package/skills/ae-kb/SKILL.md

@@ -0,0 +1,283 @@
+---
+name: ae-kb
+version: 1.0.0
+description: "AE/TE knowledge base CLI manual for creating, querying, deterministic index/grep/read retrieval, checking status, uploading, compiling, schema generation, URL sources, source deletion, and knowledge base deletion. Use when the user asks to manage TE/AE/ThinkingEngine knowledge bases, upload documents or URLs to a knowledge base, query knowledge, inspect knowledge base indexes, search knowledge base pages, read a specific knowledge base page, check knowledge base status, generate schemas, compile knowledge, remove sources, or delete a knowledge base. Must use ae-cli kb commands and must not guess knowledge base names, scopes, page paths, source display names, JSON payload shapes, or URL formats."
+---
+
+# ae-kb
+
+AE CLI (`ae-cli`) knowledge base commands are invoked through:
+
+```bash
+ae-cli kb +<command> [options]
+```
+
+## Global Rules
+
+- Use this skill for TE/AE knowledge base tasks: create, query, inspect indexes, grep pages, read pages, check status, upload sources, add URL sources, generate schema, compile, remove source files, and delete knowledge bases.
+- Read operations can run directly after required inputs are known. Write operations require explicit user intent and normally keep the confirmation prompt unless the user asks to bypass it.
+- Prefer `--dry-run` before destructive or broad writes when the user has not already validated the target.
+- Do not invent knowledge base names, scopes, source display names, or JSON payloads. Ask the user or query known context when values are missing.
+- JSON flags must be valid JSON strings, usually wrapped in single quotes in shell commands.
+- Successful commands return JSON by default. Use `--format table` only when a table is easier for a human to scan.
+- For external-agent retrieval, prefer the deterministic flow `+index` -> `+grep` -> `+read`: inspect navigation, locate candidate pages, then open the exact page or line window.
+
+## Commands
+
+| Command | Risk | Purpose |
+|---|---:|---|
+| `+query` | read | Query one or more knowledge bases with a natural-language question. |
+| `+index` | read | List accessible knowledge bases and their `index.md` navigation maps. |
+| `+grep` | read | Keyword-search knowledge base pages and return matched lines with context. |
+| `+read` | read | Read a full knowledge base page or a line window. |
+| `+new` | write | Create a new personal or company knowledge base. |
+| `+add` | write | Upload local files, a non-recursive directory, or HTTP(S) pages converted to markdown. |
+| `+url` | write | Upload a URL source directly with optional display name and parsing instruction. |
+| `+schema` | write | Generate the compile schema for a knowledge base. |
+| `+compile` | write | Compile a knowledge base in incremental or full mode. |
+| `+status` | read | Query the current status of a knowledge base. |
+| `+rm-source` | write | Delete one source file from a knowledge base by display name. |
+| `+remove` | write | Delete an entire knowledge base. |
+
+## Common Workflows
+
+### Create a Knowledge Base
+
+Use `+new` with name. `--scope` is optional and defaults to `company`; valid scopes are `personal` and `company`.
+
+```bash
+ae-cli kb +new \
+  --scope company \
+  --name engineering-handbook \
+  --description "Engineering handbook" \
+  --tags '["engineering","handbook"]'
+```
+
+Optional fields:
+
+- `--scope`: scope, defaults to `company`.
+- `--description`: description, up to 200 characters.
+- `--tags`: JSON array, max 2 tags, each up to 15 characters.
+- `--project-id`: optional project ID to bind.
+- `--project-name`: optional project display name.
+
+### Upload Files or Directories
+
+Use `+add` when sources are local files, local directories, or pages that should be fetched and converted to markdown before upload.
+
+```bash
+ae-cli kb +add \
+  --name engineering-handbook \
+  --files '["./README.md","./docs","https://example.com/guide"]'
+```
+
+Input rules:
+
+- `--files` must be a JSON array of strings.
+- Local directory reading is non-recursive.
+- URL entries must start with `http://` or `https://`.
+- Supported extensions include markdown/text, office documents, PDFs, spreadsheets, presentations, and common images. Local files are uploaded as multipart file blobs; HTTP(S) pages are fetched and converted to markdown before upload.
+- Duplicate filenames are automatically suffixed as `name-1.ext`, `name-2.ext`, etc.
+
+### Add a URL Source
+
+Use `+url` when adding one URL source and optionally passing a display name or parsing instruction.
+
+```bash
+ae-cli kb +url \
+  --name engineering-handbook \
+  --url https://example.com/guide \
+  --display-name guide \
+  --parse-instruction "Keep headings and code blocks"
+```
+
+`--url` must be `http(s)`.
+
+### Generate Schema and Compile
+
+Generate the schema first when the knowledge base needs a compile schema.
+
+```bash
+ae-cli kb +schema --name engineering-handbook
+```
+
+Use `--force` only to recover a stuck `generating` status. Use `--model` only when the user provides the model display name.
+
+Compile after sources and schema are ready:
+
+```bash
+ae-cli kb +compile --name engineering-handbook --mode incremental
+```
+
+Valid compile modes are `incremental` and `full`; default is `incremental`.
+
+### Check Knowledge Base Status
+
+Use `+status` to inspect the current status of a knowledge base.
+
+```bash
+ae-cli kb +status --name engineering-handbook
+```
+
+### Query Knowledge
+
+Use `+query` with a natural-language question and a JSON array of source refs.
+
+```bash
+ae-cli kb +query \
+  --query "How do we release a dashboard?" \
+  --sources '[{"scope":"company","name":"engineering-handbook"}]'
+```
+
+`--sources` entries require:
+
+- `scope`: knowledge base scope such as `personal` or `company`.
+- `name`: knowledge base name.
+
+### Explore Knowledge Base Pages
+
+Use the deterministic retrieval primitives when an agent needs to explore knowledge base content like a code repository. These endpoints do not call an LLM on the server side.
+
+Start with `+index` to see accessible knowledge bases and navigation maps:
+
+```bash
+ae-cli kb +index \
+  --sources '[{"scope":"company","name":"engineering-handbook"}]'
+```
+
+Then use `+grep` to locate likely pages and line numbers:
+
+```bash
+ae-cli kb +grep \
+  --query "sandbox configuration" \
+  --sources '[{"scope":"company","name":"engineering-handbook"}]' \
+  --top-k 10
+```
+
+Finally use `+read` to open the exact page, optionally with a line window:
+
+```bash
+ae-cli kb +read \
+  --source '{"scope":"company","name":"engineering-handbook"}' \
+  --path "wiki/sandbox.md" \
+  --offset 1 \
+  --limit 200
+```
+
+Retrieval rules:
+
+- `+index` accepts optional `--sources` and `--locale`; omit `--sources` to list all accessible knowledge bases.
+- `+grep` requires `--query` / `-q`; optional `--sources`, `--top-k` (1-50, default 10), and `--locale`.
+- `+read` requires `--source` pointing to exactly one knowledge base and `--path` relative to the knowledge base root; optional `--offset`, `--limit` (1-2000), and `--locale`.
+- Do not guess a `--path`; get it from `+index` or `+grep` results.
+
+### Remove One Source
+
+Use `+rm-source` only when the source display name is known exactly.
+
+```bash
+ae-cli kb +rm-source \
+  --name engineering-handbook \
+  --display-name kb-1780046712-guide.md
+```
+
+If the user only gives a loose source name, do not guess. Ask for the exact uploaded display name.
+
+### Delete a Knowledge Base
+
+Use `+remove` for deleting the entire knowledge base. Confirm the target name with the user if there is any ambiguity.
+
+```bash
+ae-cli kb +remove --name engineering-handbook
+```
+
+## Command Reference
+
+### `+query`
+
+```bash
+ae-cli kb +query --query "<question>" --sources '[{"scope":"company","name":"kb-name"}]'
+```
+
+- `--query`, alias `-q`: required natural-language question.
+- `--sources`: required JSON array of knowledge base refs.
+
+### `+index`
+
+```bash
+ae-cli kb +index [--sources '[{"scope":"company","name":"kb-name"}]'] [--locale zh|en|ja|ko]
+```
+
+- `--sources`: optional JSON array of knowledge base refs. Omit to list all accessible knowledge bases.
+- `--locale`: optional locale: `zh`, `en`, `ja`, or `ko`.
+
+### `+grep`
+
+```bash
+ae-cli kb +grep --query "<keywords>" [--sources '[{"scope":"company","name":"kb-name"}]'] [--top-k 10] [--locale zh|en|ja|ko]
+```
+
+- `--query`, alias `-q`: required keywords to search across knowledge bases.
+- `--sources`: optional JSON array of knowledge base refs. Omit to search all accessible knowledge bases.
+- `--top-k`: optional max number of hits, 1-50, default 10.
+- `--locale`: optional locale: `zh`, `en`, `ja`, or `ko`.
+
+### `+read`
+
+```bash
+ae-cli kb +read --source '{"scope":"company","name":"kb-name"}' --path "index.md" [--offset 1] [--limit 200] [--locale zh|en|ja|ko]
+```
+
+- `--source`: required JSON object pointing to exactly one knowledge base.
+- `--path`: required page path relative to the knowledge base root, such as `index.md` or `wiki/concepts/data-model.md`.
+- `--offset`: optional 1-based start line.
+- `--limit`: optional max line count, 1-2000.
+- `--locale`: optional locale: `zh`, `en`, `ja`, or `ko`.
+
+### `+new`
+
+```bash
+ae-cli kb +new --name "<name>" [--scope personal|company] [--description "..."] [--tags '["t1","t2"]'] [--project-id "..."] [--project-name "..."]
+```
+
+### `+add`
+
+```bash
+ae-cli kb +add --name "<name>" --files '["./a.md","./docs","https://example.com/page"]'
+```
+
+### `+url`
+
+```bash
+ae-cli kb +url --name "<name>" --url "https://example.com/page" [--display-name "..."] [--parse-instruction "..."]
+```
+
+### `+schema`
+
+```bash
+ae-cli kb +schema --name "<name>" [--force] [--model "<model displayName>"]
+```
+
+### `+compile`
+
+```bash
+ae-cli kb +compile --name "<name>" [--mode incremental|full]
+```
+
+### `+status`
+
+```bash
+ae-cli kb +status --name "<name>"
+```
+
+### `+rm-source`
+
+```bash
+ae-cli kb +rm-source --name "<name>" --display-name "<uploaded source display name>"
+```
+
+### `+remove`
+
+```bash
+ae-cli kb +remove --name "<name>"
+```