@aliyunrds/ctxdb 1.0.8-beta.4 → 1.0.8

package/README.md

@@ -20,32 +20,90 @@ Config and logs live under `~/.ctxdb/`. `~/.ctxdb/ctxdb.json` is one file, but r
 ### Public Device Flow login (requires the enabled Core/API phase 2 service)
 
 ```sh
-ctxdb login --agent qoder --server https://<core-host> --no-browser
-# Complete the displayed user code through the console/independent POP test client.
-ctxdb auth status --agent qoder --json
-ctxdb setup --agent qoder
-ctxdb logout --agent qoder --json
+ctxdb login --agent codex
+# Authorize in the console; this command also installs hooks/skills and validates the connection.
+# To share one login across several Agents instead:
+ctxdb login --base-url https://<core-host> --no-browser
+# Complete the displayed user code through the console/independent POP client.
+ctxdb setup --agent codex
+ctxdb setup --agent opencode
+ctxdb auth status --all --json
+# Explicitly choose another identity for one Agent:
+ctxdb login --agent codex --base-url https://<core-host>
+ctxdb setup --agent codex --login default
+ctxdb auth unbind --agent codex
+ctxdb logout --login default --yes --json
 ```
 
-Public login uses Core Device Flow only; it never calls POP, starts a localhost callback,
-or uses the internal login server. `--device-code` explicitly selects the same default flow.
-Device Flow always uses `default`, following the current Member permissions and resource ACLs.
-`login` does not accept `--scope`; creation and approval do not send a scope selector.
-Login does not install hooks/skills. Run setup separately for each selected Agent.
-
-Each profile contains only an `oauth_credential_ref`; AT/RT live in owner-only files under
-`~/.ctxdb/oauth-credentials/`. `CTXDB_CONFIG_PATH` can select an isolated configuration file;
-the OAuth directory is its sibling. CLI, Hooks and OpenCode share a cross-process, single-flight
-refresh implementation. A lost refresh response or crashed refresh requires a new login, not
-a retry of the old RT. Managed failure/logout never falls back to an API key or another profile.
-Re-login replaces only the selected profile; logout reports remote-revoke failure separately.
-AT/RT must not be copied into Agent/Skill configuration or handed to a sandbox.
-
+Public login uses Core Device Flow; `--device-code` selects the same default flow.
+The scope is always `default`, following current Member permissions and resource ACLs;
+`--scope` is not accepted. Login for a non-default Agent also runs setup, using the endpoint
+selected by that login. Default login and `--login` reauthorization only manage authentication.
+If setup fails, login exits nonzero with `authenticated: true` and setup diagnostics; the saved
+session remains available for `ctxdb setup --agent <name>` to retry. Hermes approval requirements
+remain explicit, and successful setup includes the usual host restart/trust reminders.
+Ordinary setup preserves
+existing authentication and binds the default login only for an Agent without an authentication
+choice. Without `--base-url`, setup resets the selected credential's DATA endpoint to
+`https://api.cn-hangzhou.agentcontext.aliyuncs.com`, including existing keys and logins.
+All Agents sharing that login use its updated endpoint. `setup --all` applies the same policy to detected Agents.
+An explicit invalid `--base-url` (including a missing or empty value) fails before configuration
+changes and suggests the current production URL; it never acts like an omitted option.
+
+New credentials share `credentials.json` version 2. Every record has exactly
+`kind`, `payload`, and `metadata`; kinds are `api-key` and `oauth-session`.
+`payload` contains only the API Key or AT/RT. Service addresses, identity, scope,
+expiry and lifecycle fields live in `metadata` and remain validated atomically
+with the credential. Uncertain refreshes retain metadata with an empty payload; retired logins are deleted.
+Agent API keys use `credential_ref`, and shared sessions use
+`access_credential -> logins.<ID>.credential_ref`. New login IDs use the creating Agent
+and eight random hexadecimal characters (for example, `default-e0c3f323` or `codex-a71e900a`).
+Sharing and reauthorizing the same login keep its ID. Ownership, state and revision live in
+metadata. Referenced credentials also own their service address: Agent sections no longer
+write `base_url`. Leftover config addresses cannot redirect a referenced credential; explicit
+address overrides must match its metadata. Legacy config keys and environment credentials
+keep their existing address selection. No new secrets are written to `ctxdb.json` and no OAuth directory is created.
+Released internal v1 credentials and legacy config API keys remain readable without
+migration on ordinary reads. Unreleased OAuth-directory test sessions require login again.
+See [unified credential storage and compatibility](../../docs/unified-credentials.md).
+
+CLI, hooks and OpenCode use shared authentication resolution and one cross-process refresh lock.
+Unbind only removes a local binding. `logout --agent` detaches that Agent, retaining the
+session while another Agent uses it; the last logout deletes its login and credential records
+and revokes the remote session. `logout --login` explicitly logs out all sharing Agents. Reauthorizing
+default or `login --login <ID>` updates all Agents still sharing that login. Independent
+`login --agent <name>` creates a new record and retires the previous session if it has no users.
+Successful login and logout also collect historical unreferenced login records.
+Logout performs this collection even when the selected Agent has no current login; unconfirmed
+remote cleanup returns a failure status while active shared sessions and API keys are preserved.
+Changes affecting other Agents list them and require confirmation (`--yes` for non-interactive execution).
+Failed/ambiguous refresh, damaged references, origin mismatch and revoked sessions never fall back
+to an older key or another login. Runtime environment credentials keep their original priority
+and are not persisted; explicit auth switches reject masking environment overrides before writing.
+
+Upgrade the CLI and the actual hooks/plugin artifacts together before enabling sharing.
+New CLI reading old v2 configuration is supported; old CLI reading shared-login configuration is not.
+See [共享登录、完整命令与兼容契约](../../docs/cli-shared-login.md) for migration and concurrency details.
+
+The production Core origin `https://api.cn-hangzhou.agentcontext.aliyuncs.com` defaults to the console page
+`https://rdsnext.console.aliyun.com/contextDbCliAuthorization/cn-hangzhou`. CLI appends the current
+`user_code`; the console route uses the fixed `cn-hangzhou` region.
+Ordinary DATA requests and artifact-only `upgrade` keep the configured origin, without endpoint fallback.
+`setup` and every `login`, including reauthorization, use the default production origin unless
+`--base-url` is supplied. Relogin no longer inherits the previous session's origin.
+Explicitly selecting the legacy Core origin `https://context-database.aliyuncs.com` keeps the same console mapping.
+Use `--base-url` to select the Core service and `--login-url` to supply the HTTPS console page
+for this invocation. The latter does not change the service origin or persist a console mapping.
+The legacy `--server` alias for `--base-url` remains accepted; do not pass both.
 The optional sibling `device-environments.json` (`version: 1`, `environments: [{core_url,
-authorization_url}]`) maps a Core origin to a deployment-approved HTTPS console page.
-CLI appends only `user_code` to that locally configured URL. There is no server discovery or
-invented default console page. Without a mapping, the code can be used with the independent POP
-test client. This phase never opens a browser automatically; `--no-browser` is supported.
+authorization_url}]`) overrides the console page for an exactly matching Core origin.
+The page must use HTTPS without credentials, query parameters or a fragment. Unmatched entries
+retain the production default. Preproduction and custom Core origins have no built-in console
+mapping: tests pass `--base-url` and `--login-url` explicitly, or use the code with the independent POP test client.
+Console page priority is `--login-url`, then the local mapping, then the production default.
+URLs never come from server discovery. When a console URL is available, login opens the default
+browser and keeps polling. It always prints the URL and code; if opening fails, use that URL
+manually. Pass `--no-browser` to print the link without opening a browser.
 
 POSIX uses private files/directories; Windows validates an owner-only ACL using local PowerShell.
 Native Windows acceptance remains separate from the macOS local test record.
@@ -78,7 +136,7 @@ environment-variable or file-existence check. The `public` manifest disables
 internal-protocol flags `interactiveLogin` and `managedCredentials`, and enables `deviceFlow`;
 the `internal` manifest enables the former two and disables `deviceFlow`. The CLI hooks and the separately bundled OpenCode plugin receive the
 same manifest, so installing a public build on a machine that happens to have
-`~/.ctxdb/credentials.json` does not make that build consume the file.
+`~/.ctxdb/credentials.json` does not make the public build consume the internal active record.
 
 Internal users install the package from Ali NPM. The internal version is
 managed independently in `internal-release.json`; it does not inherit the
@@ -199,7 +257,7 @@ ctxdb setup --agent hermes --api-key ctxdb-...
 # Detect and configure every supported Agent already used on this host.
 ctxdb setup --all --api-key ctxdb-...
 
-# --base-url defaults to https://context-database.aliyuncs.com (public prod).
+# --base-url defaults to https://api.cn-hangzhou.agentcontext.aliyuncs.com (public prod).
 #   Pass --base-url <host> only if you target a different deployment
 #   (e.g., a pre / staging host, or a self-hosted instance).
 # --user-id  defaults to "default". Pass --user-id <bucket> only if you
@@ -314,12 +372,15 @@ For **hermes**, `ctxdb setup --agent hermes` writes two shell hooks under `~/.he
 
 `ctxdb` ships grouped non-interactive commands:
 
-- **Top-level**: `setup` / `status` / `ping` / `debug` / `uninstall` / `update` (`upgrade` alias)
+- **Top-level**: `setup` / `status` / `ping` / `debug` / `uninstall` / `upgrade` (`update` alias)
 - **Memory**: `memory add|search|list|get|update|delete`, plus the `memory promotion` subgroup (记忆成文): `memory promotion generate|list|get|approve|reject|batch-action|batch-delete|resolve-doubts` and the `memory promotion template list|create|get|update|delete|set-default|clear-default` / `memory promotion settings get|update` sub-subgroups
-- **KB**: `kb upload-text|upload-file|update-text|update-file|list|documents-list|document-get|search`, plus the `kb review` subgroup: `kb review list|get|action|resolve-conflicts|batch-action|batch-delete|delete`, `kb review template list|create|update|delete|get|set-default|clear-default`, `kb review settings get|update`
-
+- **KB**: `kb create|upload-text|upload-file|update-text|update-file|list|documents-list|document-get|search|entities|entity-get|entity-chunks|relations`, plus the `kb review` subgroup: `kb review list|get|action|resolve-conflicts|batch-action|batch-delete|delete`, `kb review template list|create|update|delete|get|set-default|clear-default`, `kb review settings get|update`
 
-See `ctxdb --help`.
+Help is progressive: `ctxdb --help` lists command domains, group help such as
+`ctxdb kb --help` lists direct subcommands, and a leaf such as
+`ctxdb kb search --help` provides its complete arguments, constraints, output
+modes, and examples. Agents can use `ctxdb help --all` for a bounded command
+index or `ctxdb help kb search --json` for versioned structured discovery.
 
 ### Debug control and recall replay
 
@@ -338,7 +399,8 @@ Agent resolution follows the rest of the CLI: explicit `--agent`, then
 only `agents.<name>.debug`, makes no network request, and does not reinstall
 hooks, plugins, or skills. It requires that profile to already exist.
 
-The only official-production URL currently allowlisted is exactly
+The official-production URL allowlist contains
+`https://api.cn-hangzhou.agentcontext.aliyuncs.com` and the legacy
 `https://context-database.aliyuncs.com` (a trailing slash is equivalent).
 Policy is evaluated after profile/default inheritance and `CTXDB_BASE_URL`.
 Any other complete URL—including pre-production domains, numeric IPs,
@@ -375,6 +437,14 @@ fact-extraction). Use it when the user explicitly asks for a verbatim
 memory ("记住 / 请记忆 / 原文记下"); without `--no-infer` the server may
 rewrite, merge, or skip details.
 
+`memory add [<text>] --image=<local-path>` adds an image-backed memory.
+Repeat `--image` to attach multiple PNG, JPEG, or WebP files; text is optional
+when at least one image is present. Image requests require inference, so they
+cannot be combined with `--no-infer`. The command prints the server's
+`PENDING` response and `event_id` immediately and does not poll for completion.
+Recall remains text-based because the service converts image observations into
+text facts.
+
 ### Memory promotion (记忆成文)
 
 The promotion commands live under the Memory group (`ctxdb memory promotion ...`) and cover the server's memory promotion pipeline: turn
@@ -382,7 +452,7 @@ accumulated memories into reviewed knowledge-base documents.
 
 ```sh
 # Task lifecycle
-ctxdb memory promotion generate "<topic>" [--knowledge-base-id=<kb-id>]
+ctxdb memory promotion generate "<topic>" [--knowledge-base-id=<kb-id>] [--wait|--no-wait]
 ctxdb memory promotion list [--status=pending_review] [--page=N] [--page-size=N] \
                      [--sort-by=quality_score] [--sort-order=asc|desc]
 ctxdb memory promotion get <promotion-id>
@@ -432,6 +502,42 @@ Notes:
 
 ### KB create/update completion mode
 
+Knowledge-base lifecycle commands use the same Data API credential:
+
+```sh
+ctxdb kb create <kb-name> [--description=<desc>] [--graph-enabled|--no-graph-enabled] [--review-enabled|--no-review-enabled]
+ctxdb kb get (--id=<kb-id> | --name=<kb-name>)
+ctxdb kb update <kb-id> [--name=<new-name>] [--description=<desc>] [--graph-enabled|--no-graph-enabled] [--review-enabled|--no-review-enabled]
+ctxdb kb delete (--id=<kb-id> | --name=<kb-name>)
+```
+
+`ctxdb kb list` defaults to the compact management fields needed to identify,
+sort, and inspect each knowledge base. Pass `--raw` only when the complete
+server rows, including large configuration and entity fields, are required.
+
+`get` and `delete` require exactly one locator. `update` requires the canonical
+knowledge-base ID and at least one mutable field.
+
+Knowledge-base permissions use the same DATA API credential and server-side
+authorization. Resolve a KB name with `kb get --name=...`, then use its ID:
+
+```sh
+ctxdb kb acl subjects <kb-id> [--principal-type=member|group] [--principal-status=active|disabled] [--page=N] [--page-size=N] --json
+ctxdb kb acl list <kb-id> [--principal-type=member|group] [--principal-id=<id>] [--permission=read|write|kb_manage] [--page=N] [--page-size=N] --json
+ctxdb kb acl set <kb-id> --principal-type=member --principal-id=<member-id> --permission=read --json
+ctxdb kb acl delete <acl-id> --json
+```
+
+`subjects` retains the API's effective permission, source, direct grant, and
+available-action fields; `list` returns explicit ACL grants. Both retain pagination
+metadata (default page 1, page size 100). Page through the returned total for a
+complete result. `set` changes one direct grant; members accept `read`, `write`,
+or `kb_manage`, while groups accept only `read` or `write`. `delete` removes only
+the specified ACL ID, so inherited access may remain; read `subjects` again to
+verify the effective result. All commands accept `--raw` for the original envelope.
+Writes require advanced permission mode and appropriate server-side authority;
+the CLI propagates a refusal without enabling the mode or using another identity.
+
 `kb upload-text`, `kb upload-file`, `kb update-text`, and `kb update-file`
 return as soon as the service accepts the document. The returned document may still have
 `ingest_status: "processing"`; acceptance does not mean ingestion succeeded.
@@ -441,6 +547,14 @@ return as soon as the service accepts the document. The returned document may st
 - Existing `--no-wait` calls remain valid and behave like the new default.
 - `--wait` and `--no-wait` cannot be combined.
 
+With `--wait`, the CLI writes one `document_accepted` JSON receipt to stderr
+before polling, containing the returned `document_id`, `knowledge_base_id` (when
+available), and `ingest_status`. This is acceptance, not proof of completed
+ingestion. Keep stderr separate when parsing the final stdout JSON. If the wait
+is interrupted, query the receipt's ID and current logical document before
+deciding whether another write is necessary; an older ID may still expose an
+older version's chunks. The receipt contains no document body or credentials.
+
 Scripts that relied on implicit terminal polling must migrate to:
 
 ```sh
@@ -480,6 +594,61 @@ Every successful update returns the canonical `document.id` and
 same-content updates may reuse it. Callers must retain the returned ID for the
 next update; `--wait` also polls the returned ID/KB pair rather than caller input.
 
+### Knowledge graph read commands
+
+`kb entities` / `kb entity-get` / `kb entity-chunks` / `kb relations` cover the
+four knowledge-graph read DATA APIs (`GET /v1/knowledge/entities`,
+`/v1/knowledge/entities/detail`, `/v1/knowledge/entities/chunks`,
+`/v1/knowledge/entity-relations`). They give agents real entity navigation
+instead of re-querying `kb search` with rewritten keywords. Every command
+accepts `--agent` (`CTXDB_AGENT`) and `--json`, and follows the three-tier
+projection (`kb search` discipline): default prints a minimal agent view,
+`--verbose` adds provenance/alias fields, `--raw` ships the server response
+verbatim (Box envelope included for `entity-get`). Value validation (mode
+enum, page-size clamps, the 20-id cap, the limit range) belongs to the
+kernel — its 400s are surfaced, never swallowed or preempted; missing
+required flags or malformed integers print usage and exit 2 before any
+request is sent.
+
+```sh
+# List / search entities. No keyword = paginated list; keyword enters name
+# search and --mode picks the matching rule (exact | fuzzy | semantic).
+ctxdb kb entities [--kb=<kb-id>] [--page=N] [--page-size=N]
+ctxdb kb entities "graph rag" --kb=<kb-id> --mode=semantic
+
+# Single entity detail — both locators required; full untruncated
+# source_document_ids + aliases.
+ctxdb kb entity-get --kb=<kb-id> --entity-id=<id>
+
+# Source-chunk evidence behind up to 20 entities (limit 1..200, default 20).
+ctxdb kb entity-chunks --kb=<kb-id> --entity-ids=<id1>,<id2> [--limit=N]
+
+# Relations. The two entity filters are NOT aliases:
+#   --entity-id=X     → 1-hop expansion, EITHER endpoint matches X
+#   --entity-ids=A,B  → induced subgraph, BOTH endpoints must be in the set
+ctxdb kb relations --kb=<kb-id> --entity-id=<id>
+ctxdb kb relations --kb=<kb-id> --entity-ids=<a>,<b> [--relation-type=<t>] \
+  [--page=N] [--page-size=N] [--max-nodes=N] [--max-edges=N]
+```
+
+Output semantics worth knowing:
+
+- List responses (`entities` / `relations`) carry `total` + `page` +
+  `page_size`; there is no `truncated` flag on these endpoints.
+- Under `--mode=semantic`, `total` is the size of the bounded candidate pool,
+  **not** the full match count.
+- In entity list items, `source_document_ids` is truncated (20 max) —
+  `source_document_count` is the truth; fetch `entity-get` for full
+  provenance.
+- `entity-chunks` carries `total`, `candidate_total` and `truncated` so you
+  can tell "that's all the evidence" from "the limit budget ran out".
+  Entities that don't exist or have no provenance are silently skipped —
+  partial hits are normal batch behavior.
+- `relations --verbose` adds `nodes[]`: the hydrated endpoint entities with
+  their `(knowledge_base_id, entity_id)` locator pairs. `nodes` may be
+  incomplete by design (deleted endpoints are omitted); relation items always
+  keep denormalized endpoint names.
+
 ### Knowledge review commands
 
 `kb review` covers the Knowledge Review DATA APIs: review-queue handling
@@ -600,7 +769,7 @@ Lives at `~/.ctxdb/ctxdb.json` (co-located with logs at `~/.ctxdb/logs/`). Schem
   "agents": {
     "qoder": {
       "api_key": "ctxdb-...",
-      "base_url": "https://context-database.aliyuncs.com",
+      "base_url": "https://api.cn-hangzhou.agentcontext.aliyuncs.com",
       "user_id": "default",
       "auto_capture": true,
       "auto_recall": true,
@@ -735,3 +904,7 @@ Maintainer-facing docs (source layout, dev/test workflows, server-config archive
 ## License
 
 Apache-2.0
+
+上传时可用 `ctxdb kb upload-text` 或 `ctxdb kb upload-file` 的 `--review-enabled` / `--no-review-enabled` 覆盖本次文档评审开关；不传时沿用服务端默认，不修改知识库策略。两标志互斥，分片上传保留同一选择。上传回执不代表评审或入库完成，应查询实际状态。
+
+`memory get <fact-id> --verbose` 通过原生 Fact 详情接口读取状态、关联实体 ID、来源及参考/记录时间；默认 `memory get` 的 mem0 输出保持兼容。召回统计可从同一身份的 `memory list` 中按 ID 对应读取。