@aliyunrds/ctxdb 1.0.8-beta.3 → 1.0.8

package/README.md

@@ -17,9 +17,100 @@ Config and logs live under `~/.ctxdb/`. `~/.ctxdb/ctxdb.json` is one file, but r
 
 ## Install
 
+### Public Device Flow login (requires the enabled Core/API phase 2 service)
+
+```sh
+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; `--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}]`) 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.
+
 ### Internal browser-login distribution
 
-The same source also builds `@ali/ctxdb-internal`. That artifact alone
+The same source also builds `@ali/ctxdb-internal`. Its existing prototype
 adds `ctxdb login --server <url>`, `ctxdb login --device-code`, `ctxdb logout`,
 and `ctxdb auth status`. The default login uses a browser loopback callback;
 `--device-code` supports remote or headless terminals. Both methods discover a
@@ -36,16 +127,16 @@ credential overrides the API key and DATA URL in the existing v2
 three while `ctxdb logout` rejects the two credential overrides, so command
 output cannot disagree with subsequent DATA requests. Re-login replaces the
 active connection and revokes the previous key after setup succeeds. The
-public `@aliyunrds/ctxdb` build does not contain or advertise these commands and
-continues to use `ctxdb setup` and the v2 config exactly as before. Build the
+public `@aliyunrds/ctxdb` build uses the distinct Device Flow implementation above and
+continues to support API-key setup. It never reads the internal credential store. Build the
 internal staging package with `pnpm build:internal`.
 
 The distinction is a compile-time distribution manifest, not a runtime
 environment-variable or file-existence check. The `public` manifest disables
-`interactiveLogin` and `managedCredentials`; the `internal` manifest enables
-both. The CLI hooks and the separately bundled OpenCode plugin receive the
+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
@@ -166,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
@@ -281,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
 
@@ -305,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,
@@ -342,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
@@ -349,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>
@@ -399,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.
@@ -408,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
@@ -447,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
@@ -567,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,
@@ -607,7 +809,7 @@ Field reference:
 
 Env-var overrides apply to the selected agent config (env wins): `CTXDB_AGENT` / `CTXDB_ACCESS_TOKEN` / `CTXDB_API_KEY` / `CTXDB_BASE_URL` / `CTXDB_USER_ID` / `CTXDB_AGENT_ID` / `CTXDB_APP_ID`. The internal login command additionally reads `CTXDB_LOGIN_SERVER` as its provider-neutral login endpoint. The last two default to unset — the request body omits `agent_id`/`app_id` entirely; set them only when you want per-agent / per-app scope isolation on the server.
 
-Downstream Agent hosts can set `CTXDB_ACCESS_TOKEN` to send `Authorization: Bearer <token>` to the Data API. It is runtime-only, never written to `~/.ctxdb/ctxdb.json`, and takes precedence over an API key for CLI, process hooks, and the in-process OpenCode plugin; a rejected token does not fall back to the API key. `ctxdb setup` remains API-key-only and never persists or validates an access token.
+Downstream Agent hosts can set `CTXDB_ACCESS_TOKEN` to send `Authorization: Bearer <token>` to the Data API. It is runtime-only, never written to `~/.ctxdb/ctxdb.json`, and takes precedence over a managed session or API key for CLI, process hooks, and OpenCode; a rejected token does not fall back to another credential. `ctxdb setup` can use a managed reference or an environment AT for validation, but never persists the AT. An environment-only credential must remain available to the Agent runtime after setup.
 
 Hook/plugin escape hatch: set `CTXDB_SKIP_HOOKS=TRUE` on the agent process to make all ctxdb hook entrypoints exit immediately before reading config or calling the API. Direct `ctxdb memory` / `ctxdb kb` / `ctxdb setup` CLI commands are unchanged.
 
@@ -702,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 对应读取。