From 5c7ccbd79ba7c31655b3aa5900f23e340830e2bf Mon Sep 17 00:00:00 2001 From: chenncy <120267911+chenncy@users.noreply.github.com> Date: Tue, 1 Sep 2026 19:13:24 +0800 Subject: [PATCH] docs: finalize documentation classification and reference guides --- docs/en/docs/explanation/core-concepts.md | 8 +- .../experience-and-skill-lifecycle.md | 6 +- .../en/docs/explanation/memory-and-handoff.md | 2 +- .../how-to/configure-agent-skill-targets.md | 39 ++++++ docs/en/docs/how-to/configure-claude-code.md | 2 +- docs/en/docs/how-to/configure-codex.md | 4 +- docs/en/docs/how-to/configure-hermes.md | 2 +- .../how-to/configure-server-environment.md | 41 +++++++ .../en/docs/how-to/configure-vector-search.md | 38 ++++++ docs/en/docs/how-to/deploy-server.md | 3 +- docs/en/docs/index.md | 11 +- docs/en/docs/reference/configuration.md | 116 +++--------------- docs/en/docs/reference/http-api.md | 16 ++- docs/en/docs/reference/interfaces.md | 103 +++------------- docs/zh/docs/explanation/core-concepts.md | 6 +- .../experience-and-skill-lifecycle.md | 6 +- .../zh/docs/explanation/memory-and-handoff.md | 2 +- .../how-to/configure-agent-skill-targets.md | 38 ++++++ .../how-to/configure-server-environment.md | 38 ++++++ .../zh/docs/how-to/configure-vector-search.md | 38 ++++++ docs/zh/docs/how-to/deploy-server.md | 2 +- docs/zh/docs/index.md | 11 +- docs/zh/docs/reference/configuration.md | 100 ++------------- docs/zh/docs/reference/http-api.md | 13 +- docs/zh/docs/reference/interfaces.md | 90 ++------------ zensical.toml | 30 +++-- 26 files changed, 367 insertions(+), 398 deletions(-) create mode 100644 docs/en/docs/how-to/configure-agent-skill-targets.md create mode 100644 docs/en/docs/how-to/configure-server-environment.md create mode 100644 docs/en/docs/how-to/configure-vector-search.md create mode 100644 docs/zh/docs/how-to/configure-agent-skill-targets.md create mode 100644 docs/zh/docs/how-to/configure-server-environment.md create mode 100644 docs/zh/docs/how-to/configure-vector-search.md diff --git a/docs/en/docs/explanation/core-concepts.md b/docs/en/docs/explanation/core-concepts.md index 4ed93065d..c5c5b9ee7 100644 --- a/docs/en/docs/explanation/core-concepts.md +++ b/docs/en/docs/explanation/core-concepts.md @@ -55,7 +55,7 @@ apply after another writer changes the proposal. Approval writes an immutable Artifact Revision and returns its exact `result_artifact`. Rejection records a decision reason without creating an Artifact. Both decisions are terminal. See -[Review Candidates](../how-to/review-candidates.md) for the procedure. +[Review Candidates](/en/docs/how-to/review-candidates/) for the procedure. ## Experience and Skill have different availability @@ -89,7 +89,7 @@ inspected boundary and returns a temporary Prepared Handoff. Committing a Handof the user wants a milestone. The receiver resolves the Handoff and records an Acknowledgement; a Task Outcome preserves the final status and checks as Source evidence. -The [Handoff Report](../how-to/use-handoff-report.md) projects current Handoff Revisions for inspection and export. The +The [Handoff Report](/en/docs/how-to/use-handoff-report/) projects current Handoff Revisions for inspection and export. The current scope report does not yet include Activity events or period comparison, and it does not rewrite Memory or the underlying Handoff history. @@ -103,6 +103,6 @@ Model generation, human Review, and execution authority remain separate. A model approve an Artifact Revision, and export can create a host-local copy. None of those steps grants an Agent permission to execute instructions. -Use [Interfaces](../reference/interfaces.md) for current surface availability and -[Configuration](../reference/configuration.md) for exact settings and defaults. RFCs record design decisions and may +Use [Interfaces](/en/docs/reference/interfaces/) for current surface availability and +[Configuration](/en/docs/reference/configuration/) for exact settings and defaults. RFCs record design decisions and may not describe the current implementation. diff --git a/docs/en/docs/explanation/experience-and-skill-lifecycle.md b/docs/en/docs/explanation/experience-and-skill-lifecycle.md index 1f42e0a18..1886ce87c 100644 --- a/docs/en/docs/explanation/experience-and-skill-lifecycle.md +++ b/docs/en/docs/explanation/experience-and-skill-lifecycle.md @@ -66,6 +66,6 @@ approval reports a conflict. The reviewer must inspect the new head before decid Earlier approved Revisions remain available for exact reads. An exported Skill directory is only a copy of one exact Revision; the managed Artifact remains the content authority. -Use [Review Candidates](../how-to/review-candidates.md) for the review procedure, -[Create and review an Experience](../how-to/create-and-review-experience.md) for Experience operations, and -[Create and export a managed Skill](../how-to/create-and-export-skill.md) for Skill operations. +Use [Review Candidates](/en/docs/how-to/review-candidates/) for the review procedure, +[Create and review an Experience](/en/docs/how-to/create-and-review-experience/) for Experience operations, and +[Create and export a managed Skill](/en/docs/how-to/create-and-export-skill/) for Skill operations. diff --git a/docs/en/docs/explanation/memory-and-handoff.md b/docs/en/docs/explanation/memory-and-handoff.md index 46842382c..ceeea93b5 100644 --- a/docs/en/docs/explanation/memory-and-handoff.md +++ b/docs/en/docs/explanation/memory-and-handoff.md @@ -37,4 +37,4 @@ explicitly asks to retain a milestone. | Retain a verified Handoff milestone for long-term reuse | Commit the Handoff on user request, or save it as Memory | Never store secrets, access tokens, or other sensitive information in either. For the Handoff procedure, see -[Hand off work in Codex](../how-to/handoff-with-codex.md). +[Hand off work in Codex](/en/docs/how-to/handoff-with-codex/). diff --git a/docs/en/docs/how-to/configure-agent-skill-targets.md b/docs/en/docs/how-to/configure-agent-skill-targets.md new file mode 100644 index 000000000..9d88a95e2 --- /dev/null +++ b/docs/en/docs/how-to/configure-agent-skill-targets.md @@ -0,0 +1,39 @@ +--- +title: Configure Agent Skill targets +description: Register explicit local Codex or Claude Code Skill directories for discovery and managed publication. +--- + +# Configure Agent Skill targets + +Register a local target before scanning external Skills or publishing an approved managed Skill from the Server UI. + +## 1. Set the target configuration + +```bash +export POWERCONTEXT_SERVER_EXTERNAL_SKILLS='{ + "host_id": "workstation-1", + "targets": [ + { + "target_id": "codex-project", + "agent_kind": "codex", + "installation_scope": "project", + "path": "/srv/project/.agents/skills", + "allow_managed_publish": true + } + ] +}' +``` + +Use one unique `target_id` per directory. `agent_kind` is `codex` or `claude_code`; `installation_scope` is `user`, +`project`, or `plugin`. For Claude Code, use its Skill directory, for example `/srv/project/.claude/skills`. + +## 2. Restart and inspect + +Restart the Server, then use the Skills Library or the external Skill commands to scan the configured scope. The Server +only scans immediate package directories under listed targets. It does not infer a home directory or install a package. + +`allow_managed_publish` is `false` by default. Set it to `true` only for a target where the authenticated Server may +publish an approved managed Skill. Publication cannot select an arbitrary path or overwrite a foreign or modified +package. + +For the configuration schema and compatibility form, see [Configuration](/en/docs/reference/configuration/). diff --git a/docs/en/docs/how-to/configure-claude-code.md b/docs/en/docs/how-to/configure-claude-code.md index cded5130e..9d95f001c 100644 --- a/docs/en/docs/how-to/configure-claude-code.md +++ b/docs/en/docs/how-to/configure-claude-code.md @@ -129,7 +129,7 @@ local project path. normal interactive use. The timeout and flush controls are listed in the -[configuration reference](../reference/configuration.md#claude-code-plugin). They apply to the Hook process; the MCP +[configuration reference](/en/docs/reference/configuration/#claude-code-plugin). They apply to the Hook process; the MCP client remains managed by Claude Code. ## Connect an authenticated Server diff --git a/docs/en/docs/how-to/configure-codex.md b/docs/en/docs/how-to/configure-codex.md index cb473c8b9..38226c4aa 100644 --- a/docs/en/docs/how-to/configure-codex.md +++ b/docs/en/docs/how-to/configure-codex.md @@ -67,8 +67,8 @@ instructions before acting on them. Memory stores durable, reusable decisions, constraints, and state. A Handoff temporarily transfers the current task to another task, session, or model. It must be explicitly prepared, inspected, and delivered, rather than substituted with -a few Memory entries. Read [Memory and Handoff](../explanation/memory-and-handoff.md) for the boundary and -[Hand off work in Codex](handoff-with-codex.md) for the procedure. +a few Memory entries. Read [Memory and Handoff](/en/docs/explanation/memory-and-handoff/) for the boundary and +[Hand off work in Codex](/en/docs/how-to/handoff-with-codex/) for the procedure. ## Control prompt capture diff --git a/docs/en/docs/how-to/configure-hermes.md b/docs/en/docs/how-to/configure-hermes.md index aaaa7afbf..32ad8698a 100644 --- a/docs/en/docs/how-to/configure-hermes.md +++ b/docs/en/docs/how-to/configure-hermes.md @@ -83,7 +83,7 @@ the file: | `POWERCONTEXT_HERMES_WORKSTREAM` | Read the shared Git-private Workstream binding; enabled by default | Let the Hermes wizard store authorization in its protected `.env` secret store; do not put the token in -`config.json`. Use plain HTTP only for a loopback Server. See [Deploy the Server](deploy-server.md) before connecting +`config.json`. Use plain HTTP only for a loopback Server. See [Deploy the Server](/en/docs/how-to/deploy-server/) before connecting to a remote deployment. Evaluation traces contain prompts and recalled context; keep them local and protect them as sensitive data. diff --git a/docs/en/docs/how-to/configure-server-environment.md b/docs/en/docs/how-to/configure-server-environment.md new file mode 100644 index 000000000..c2f85fabe --- /dev/null +++ b/docs/en/docs/how-to/configure-server-environment.md @@ -0,0 +1,41 @@ +--- +title: Configure a Server environment +description: Generate, inspect, validate, and run PowerContext from an explicit environment file. +--- + +# Configure a Server environment + +Use an explicit environment file when the Server needs inference, scheduling, storage, or deployment settings. + +## 1. Generate the file + +```bash +powercontext config init --output .env +``` + +The guided command writes a private file with mode `0600`. Enter provider credentials through your environment or +secret manager, not in command-line arguments. + +## 2. Inspect and validate it + +```bash +powercontext config show --env-file .env +powercontext config validate --env-file .env +``` + +`config show` redacts recognized credentials. Validation checks the document and the selected model settings without +printing secrets. + +## 3. Run the same configuration + +```bash +powercontext server run --env-file .env +``` + +Values in the file override same-named process values. Inherited `POWERCONTEXT_SERVER_*` values missing from the file +are ignored, so validation and launch use the same Server settings. + +The Server starts with the configured capabilities. Use `powercontext ready` and `powercontext capabilities` to check +its readiness and enabled features. + +For every variable, default, and precedence rule, see [Configuration](../reference/configuration.md). diff --git a/docs/en/docs/how-to/configure-vector-search.md b/docs/en/docs/how-to/configure-vector-search.md new file mode 100644 index 000000000..d433ddaa6 --- /dev/null +++ b/docs/en/docs/how-to/configure-vector-search.md @@ -0,0 +1,38 @@ +--- +title: Configure vector search +description: Enable embedding-backed vector and hybrid Memory search, then verify the Runtime capability. +--- + +# Configure vector search + +Vector search needs an embedding model, a stable profile ID, and the model's output dimension. + +## 1. Set one embedding profile + +```bash +export POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_MODEL=provider:embedding-model +export POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_PROFILE_ID=embedding-model-v1 +export POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_DIMENSION=1024 +``` + +Replace the example values with one supported provider model, a profile ID you keep stable for that model, and its +documented output dimension. `POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_NORMALIZATION` defaults to `unit`. + +## 2. Start the Server + +```bash +powercontext server run +``` + +With SQLite, PowerContext loads the bundled sqlite-vec extension when it opens the database. Startup fails if the +installed extension is incompatible with the platform or SQLite build. + +## 3. Verify the capability + +```bash +powercontext capabilities +``` + +The result reports the enabled search modes. Without an embedding profile, SQLite full-text search remains available. + +For timeouts, batch size, storage settings, and exact defaults, see [Configuration](../reference/configuration.md). diff --git a/docs/en/docs/how-to/deploy-server.md b/docs/en/docs/how-to/deploy-server.md index 52e8dc669..465357fa5 100644 --- a/docs/en/docs/how-to/deploy-server.md +++ b/docs/en/docs/how-to/deploy-server.md @@ -96,7 +96,8 @@ docker run --rm \ ``` Clients then send `Authorization: Bearer `. The liveness and readiness endpoints remain public so an -orchestrator can probe them. API, MCP, metrics, OpenAPI, and interactive API documentation require authentication. +orchestrator can probe them. API, MCP, metrics, and `/openapi.json` require authentication. The `/docs` shell remains +public, but requests made from the interactive reference require authentication. The Server's web-page shells and static assets remain public so they can show a sign-in form; they do not return protected data without the token. Open the Dashboard, Skills, Review, or Handoff Report page and enter the same token there. It remains in the current browser tab's session storage rather than being added to the URL. diff --git a/docs/en/docs/index.md b/docs/en/docs/index.md index 328f017ef..36eff1f29 100644 --- a/docs/en/docs/index.md +++ b/docs/en/docs/index.md @@ -4,7 +4,7 @@ title: Choose an Agent or API and complete the first loop description: Add the HTTP Memory API to an existing AI application, or configure an Agent and verify Memory and Handoff. page_type: docs-overview overview: - intro: If you are new to PowerContext, choose the entry that matches your application. Use HTTP directly from an existing AI application, or start with the Agent quickstart for Codex, Claude Code, OpenCode, and other hosts. + intro: Choose a tutorial to learn one complete path, a how-to guide to finish a specific task, an explanation to understand system behavior, or a reference page to look up current contracts and settings. sections: - title: Recommended learning path description: Complete a local API or Agent loop first, then connect another host or adopt the complete work workflow. @@ -63,6 +63,15 @@ overview: - title: Configuration description: Set storage, providers, interfaces, and runtime behavior. href: en/docs/reference/configuration/ + - title: Configure a Server environment + description: Generate one explicit environment file, validate it, and start the Server with the same settings. + href: en/docs/how-to/configure-server-environment/ + - title: Configure vector search + description: Set an embedding profile and confirm that vector and hybrid search are available. + href: en/docs/how-to/configure-vector-search/ + - title: Configure Agent Skill targets + description: Register local Codex or Claude Code Skill directories for discovery and managed publication. + href: en/docs/how-to/configure-agent-skill-targets/ - title: Deploy the Server description: Run a persistent Server with health checks, authentication, and a safe network boundary. href: en/docs/how-to/deploy-server/ diff --git a/docs/en/docs/reference/configuration.md b/docs/en/docs/reference/configuration.md index c0ee374e0..6899b91dd 100644 --- a/docs/en/docs/reference/configuration.md +++ b/docs/en/docs/reference/configuration.md @@ -6,26 +6,13 @@ description: PowerContext paths, Server, Client, inference, and Agent integratio # Configuration PowerContext reads configuration from environment variables when each process starts. The CLI does not search for a -`.env` file automatically. Export values in the shell, have the service manager or container supply them, or pass an -explicit file to a command that accepts `--env-file`. An Agent host may load its own environment file according to -that host's rules. +`.env` file automatically. A command that accepts `--env-file` reads only the values in that file for Server settings; +values in the file override same-named process values. Agent hosts can load their own environment files according to +their host-specific rules. -## Explicit environment files - -Create a guided configuration, inspect it without printing credentials, and validate it before launch: - -```bash -powercontext config init --output .env -powercontext config show --env-file .env -powercontext config validate --env-file .env -powercontext server run --env-file .env -``` - -`config init` writes the file with mode `0600`. When `server run` receives `--env-file`, assignments in that file -override same-named process values. Inherited `POWERCONTEXT_SERVER_*` values that are missing from the file are -ignored, so validation and launch use the same Server configuration. `config show` redacts recognized and -generator-recorded credentials; still treat the file itself as a secret-bearing deployment artifact. See the -[Full-capability Quick Start](../how-to/full-capability-runtime.md) for the guided setup and verification flow. +For the configuration-file workflow, including generation, redacted inspection, validation, and launch, see +[Configure a Server environment](../how-to/configure-server-environment.md). Treat every environment file as a +secret-bearing deployment artifact. ## User data @@ -114,15 +101,6 @@ Handoff Report is independently enabled by default at `/handoff-reports`. When n it shows a data-free template preview. See [Use Handoff Report](../how-to/use-handoff-report.md) for scope discovery, inspection, Revision writes, and export. -Example with a controlled SQLite path and scheduled extraction: - -```bash -export POWERCONTEXT_SERVER_DATABASE_URL=sqlite+aiosqlite:////srv/powercontext/runtime.db -export POWERCONTEXT_SERVER_RUNTIME_SCHEDULE_SECONDS=30 -export POWERCONTEXT_SERVER_INFERENCE_GENERATION_MODEL=provider:model-name -powercontext server run -``` - Provider credentials, such as `OPENAI_API_KEY`, are read by the configured inference provider. Do not place secrets in command-line arguments, documentation, or Memory. Replace `provider:model-name` with a model identifier supported by Pydantic AI. Scheduled extraction requires both a generation model and @@ -170,15 +148,8 @@ The same configured generation model gates explicit Experience generation, manag and external Skill import or fork. Without it, these operations return a capability error before persisting a Candidate. Candidate Review, exact reads, and external Skill scan/list/resolve continue to work. -Experience incubation is a separate APScheduler job with its own persisted Source cursor. Enable it with: - -```bash -export POWERCONTEXT_SERVER_RUNTIME_EXPERIENCE_SCHEDULE_SECONDS=30 -export POWERCONTEXT_SERVER_INFERENCE_GENERATION_MODEL=provider:model-name -powercontext server run -``` - -Each activation inspects a fixed window of at most 32 Sources and exposes only Content Sources whose metadata contains +Experience incubation is a separate APScheduler job with its own persisted Source cursor. Each activation inspects a +fixed window of at most 32 Sources and exposes only Content Sources whose metadata contains `"kind": "task-outcome"` to the model. It creates pending Experience Candidates in the Review Inbox; it does not approve them, place them in PreparedContext, create a managed Skill, export it to an Agent target, or execute anything. The Memory and Experience jobs share the APScheduler sidecar under `POWERCONTEXT_HOME`, but keep independent job @@ -187,29 +158,9 @@ See [Create and review an Experience](../how-to/create-and-review-experience.md) ### Agent Skill targets -Configure Codex and Claude Code host-local targets as one JSON value: - -```bash -export POWERCONTEXT_SERVER_EXTERNAL_SKILLS='{ - "host_id": "workstation-1", - "targets": [ - { - "target_id": "codex-project", - "agent_kind": "codex", - "installation_scope": "project", - "path": "/srv/project/.agents/skills", - "allow_managed_publish": true - }, - { - "target_id": "claude-project", - "agent_kind": "claude_code", - "installation_scope": "project", - "path": "/srv/project/.claude/skills", - "allow_managed_publish": true - } - ] -}' -``` +`POWERCONTEXT_SERVER_EXTERNAL_SKILLS` is a JSON object containing one local host identity and explicit Codex or Claude +Code Skill targets. For its JSON shape and verification steps, see +[Configure Agent Skill targets](../how-to/configure-agent-skill-targets.md). Target IDs must be unique. `agent_kind` supports `codex` and `claude_code`; installation scopes are `user`, `project`, and `plugin`. PowerContext scans only the immediate Skill package directories under these explicit targets; it does not @@ -239,46 +190,13 @@ export POWERCONTEXT_SERVER_DATABASE_URL="$OCEANBASE_URL" The URL must use the `mysql+aoceanbase` driver, include an explicit port and database, and set `charset=utf8mb4`. The tenant must use MySQL compatibility mode. -### Embeddings - -Embedding search is enabled only when all three identity fields are set: - -```bash -export POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_MODEL=provider:embedding-model -export POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_PROFILE_ID=embedding-model-v1 -export POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_DIMENSION=1024 -``` - -Replace the example values with the selected provider model, a stable profile ID, and that model's dimension. - -Optional settings are `POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_NORMALIZATION` and -`POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_TIMEOUT_SECONDS`. - -Embedding normalization defaults to `unit`. - -### SQLite vector search - -SQLite vector and hybrid search use [sqlite-vec](https://alexgarcia.xyz/sqlite-vec/), which is bundled with the -`powercontext[builtin]` dependency set. Configure the complete embedding profile; no extension path is needed: - -```bash -export POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_MODEL=provider:embedding-model -export POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_PROFILE_ID=embedding-model-v1 -export POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_DIMENSION=1024 -export POWERCONTEXT_SERVER_DATABASE_URL=sqlite+aiosqlite:////srv/powercontext/powercontext.db -powercontext server run -``` - -PowerContext loads and probes the bundled extension when the Server opens the database. Startup fails if the package -does not contain a library compatible with the current platform or SQLite build. - -In another terminal, confirm that the initialized runtime reports vector and hybrid search: - -```bash -powercontext capabilities -``` +### Embeddings and SQLite vector search -SQLite full-text search remains available when no embedding model is configured. +Vector search requires all three embedding identity variables: model, stable profile ID, and positive dimension. +Normalization defaults to `unit`; timeout and batch size are optional controls. SQLite vector and hybrid search use the +bundled sqlite-vec extension. The Server probes it when opening the database, and startup fails if the installed library +is incompatible with the platform or SQLite build. Full-text search remains available without an embedding profile. +For configuration and capability verification, see [Configure vector search](../how-to/configure-vector-search.md). ## CLI Server connection diff --git a/docs/en/docs/reference/http-api.md b/docs/en/docs/reference/http-api.md index 645461b17..54ee9a866 100644 --- a/docs/en/docs/reference/http-api.md +++ b/docs/en/docs/reference/http-api.md @@ -14,18 +14,16 @@ error-semantics reference. ## Discover the contract -With a local unauthenticated Server running, open: - -- `/docs` for interactive Swagger UI; -- `/redoc` for ReDoc; -- `/openapi.json` for the contract served by that process. +With a local unauthenticated Server running, open `/docs` for the interactive Scalar API reference or +`/openapi.json` for the contract served by that process. The checked-in source of truth is [`openapi/powercontext.yaml`](https://github.com/oceanbase/powercontext/blob/master/openapi/powercontext.yaml). -Use it when generating a client or reviewing every request and response field. When Server authentication is enabled, -the three discovery routes require the same bearer token as other protected routes. A browser address bar cannot add -that header: use a trusted proxy or browser setup that injects it, or download `/openapi.json` with an authenticated -command after setting the variables below. Never put the token in the URL. +Use it when generating a client or reviewing every request and response field. `/docs` remains public when Server +authentication is enabled so it can render the reference; requests made from it still require authentication. +`/openapi.json` requires the bearer token. A browser address bar cannot add that header, so use a trusted proxy or +browser setup that injects it, or download `/openapi.json` with an authenticated command. Never put the token in the +URL. ## Authenticate requests diff --git a/docs/en/docs/reference/interfaces.md b/docs/en/docs/reference/interfaces.md index 495c939de..f9eb3e8e7 100644 --- a/docs/en/docs/reference/interfaces.md +++ b/docs/en/docs/reference/interfaces.md @@ -24,7 +24,7 @@ All remote interfaces operate on the same Server and persistent Artifact storage | Python Client SDK | Typed asynchronous calls to a running Server | [Install the client role](../how-to/install-and-run.md#install-a-python-role) | | Core SDK | In-process Source, Artifact, Trigger, and composition contracts | [Python API reference](/en/modules/) | | HTTP | Service integration from any language | [HTTP API](http-api.md) | -| MCP | Agent tools for Memory and work continuity | Enabled by the Server at `/mcp` | +| MCP | Curated Agent tools for Source capture, Memory, work continuity, reports, and Candidate Review | Enabled by the Server at `/mcp` | ## Codex plugin @@ -34,53 +34,16 @@ perform explicit operations. The plugin never starts or embeds the Server. ## Work continuity -The Server exposes one high-level loop across HTTP, the Python Client, and MCP: +HTTP, the Python Client, and MCP expose Work Contract creation, Handoff preparation and continuation, acknowledgement, +and Task Outcome recording. A Prepared Handoff is temporary; `commit_handoff` creates a durable Revision. An +acknowledgement can select a prepared or exact Handoff, but `handoff_receipt_ref` accepts only an accepted exact Receipt +for a committed Revision. Claims and checks can be `declared` or `verified` with exact same-scope citations. These +records never grant identity, tool, or execution authority. -```text -create_work_contract - -> work - -> handoff_current_work - -> continue_handoff + acknowledge_handoff - -> record_task_outcome -``` - -`create_work_contract` records the objective, scope, completion criteria, authority notes, and consequential open -questions for newly delegated work. `handoff_current_work` captures caller-inspected state and returns a temporary -Prepared Handoff; it does not publish a milestone. Call `commit_handoff` separately when the user wants a durable -milestone. - -The receiver calls `continue_handoff` with a prepared, exact, or latest selection. When starting from latest, the -returned exact Revision is shown and inspected before acknowledgement. `acknowledge_handoff` accepts prepared or exact, -never latest. It refuses acceptance when any Handoff evidence is unavailable or when live-state, capability, and -authorization are not all `confirmed`. A receiver can instead record `needs_clarification` or `declined`. The receipt -and its three confirmations are untrusted observations; they grant no identity, tool, or execution authority. - -`record_task_outcome` preserves `succeeded`, `partial`, `blocked`, `failed`, `cancelled`, or `unknown` and exact check -states. To cover a committed Handoff result, `handoff_receipt_ref` identifies the active accepted exact Receipt; an -unlinked Outcome in the same scope does not cover it. The operation stores a `task-outcome` Source that existing -Experience incubation can inspect, but does not generate or approve an Experience by itself. Integrations call it only -at a real completion or interruption boundary, not solely because a prompt, Stop event, or Session ended. - -Claims and checks are either `declared` with no evidence or `verified` with exact same-scope citations. A readable -citation proves identity and availability, not freshness. Current instructions, live workspace state, capabilities, -and authorization still take precedence over all Work and Handoff records. - -For the complete Codex transfer and acknowledgement workflow, see -[Hand off work in Codex](../how-to/handoff-with-codex.md). - -Handoff Report lists scopes that contain a committed Handoff, and `get_handoff_report` requires `scope_id`. -`project_id` remains deprecated wire-compatibility input and is ignored during report generation. Each returned -Workstream projection includes `handoff_revision_count`, `handoff_history_truncated`, and `handoff_history`, with at -most the latest 20 Revision summaries through the frozen selection. For the web workflow, see -[Use Handoff Report](../how-to/use-handoff-report.md). - -The current scope report returns no Activity events, reports `activity_coverage=not_configured`, and has no period -comparison. Period input is normalized but does not filter Activity. The HTTP and Python Client Markdown operations -remain available without a token when Server authentication is disabled; the current browser download and background -refresh controls require a stored bearer token. - -The Codex scope resolver can bind the current Git workspace once to a fixed Workstream scope. That binding takes -precedence over Git remote and path derivation, but remains below explicit scope configuration. +The Handoff Report API lists scopes containing committed Handoffs and requires `scope_id`; its deprecated `project_id` +input is ignored while generating a scope report. Scope reports currently return no Activity events and no period +comparison. See [Hand off work in Codex](../how-to/handoff-with-codex.md) for the workflow and +[Use Handoff Report](../how-to/use-handoff-report.md) for the report UI. ## DeepSeek Harness plugin @@ -185,42 +148,10 @@ automatically includes the target in Artifact evidence. Managed Skill revision a ## Python Client SDK -Use the Client SDK when the Server owns persistence: - -```python -import asyncio - -from powercontext.http import PrepareContextRequest, RememberMemoryRequest, SearchMemoryRequest -from powercontext.client import PowerContextClient - - -async def main() -> None: - async with PowerContextClient("http://127.0.0.1:8000") as client: - await client.remember_memory( - RememberMemoryRequest( - scope_id="project:example", - kind="decision", - text="Keep the public API asynchronous.", - ) - ) - result = await client.search_memory( - SearchMemoryRequest( - scope_id="project:example", - query="public API", - ) - ) - print([hit.text for hit in result.hits]) - prepared = await client.prepare_context( - PrepareContextRequest(scope_id="project:example", query="public API") - ) - print(prepared.content) - - -asyncio.run(main()) -``` - -Mutation responses include an exact citation. Pass that citation back when revising, retiring, or reading an immutable -entry version. +`PowerContextClient` is the typed asynchronous HTTP client for a Server-owned deployment. Its request and response +models are exported from `powercontext.http`. Mutation responses include exact citations, which callers pass when a +later request revises, retires, or reads an immutable entry version. See the +[HTTP API lifecycle tutorial](../tutorials/api-quickstart.md) for a runnable client flow. The Client also exposes `generate_experience`, `propose_experience`, `get_experience`, `generate_skill`, `propose_skill`, `get_skill`, `scan_external_skills`, `list_external_skills`, `resolve_external_skill`, @@ -315,9 +246,9 @@ See [HTTP API](http-api.md) for authentication, curl examples, operation groups, contract. The Server publishes a Scalar API reference at `/docs`, its OpenAPI document at `/openapi.json`, readiness at `/health/ready`, capabilities at `/v1/capabilities`, and Streamable HTTP MCP at `/mcp` by default. The Scalar reference remains public when bearer authentication is enabled, but the operations it describes retain their normal authentication -requirements. HTTP is the complete application contract. MCP is a curated agent-facing projection of Memory and -Candidate Review operations. The five Candidate Review operations use the same validation, `expected_version` -concurrency checks, and approval transaction over HTTP and MCP. +requirements. HTTP is the complete application contract. MCP is a curated Agent-facing projection of Source capture, +Memory maintenance, work continuity, scope Handoff Report lookup, and Candidate Review. The five Candidate Review +operations use the same validation, `expected_version` concurrency checks, and approval transaction over HTTP and MCP. Readiness is `ready` with HTTP 200 when all checks pass, `degraded` with HTTP 200 when only configured inference checks fail, and `not_ready` with HTTP 503 when the Runtime or database fails. Dependency checks use `ready`, `unavailable`, `timeout`, or `misconfigured`; an intentionally unbound Runtime reports `not_ready` for the `runtime` check. diff --git a/docs/zh/docs/explanation/core-concepts.md b/docs/zh/docs/explanation/core-concepts.md index 2b63b6c53..655a8cb31 100644 --- a/docs/zh/docs/explanation/core-concepts.md +++ b/docs/zh/docs/explanation/core-concepts.md @@ -49,7 +49,7 @@ proposal version 和对应的精确证据。Review 写操作使用 `expected_ver 静默作用于旧内容。 批准会写入不可变 Artifact Revision，并返回精确的 `result_artifact`。拒绝只记录 decision reason，不创建 Artifact。 -两种决定都是终态。操作步骤见[审核 Candidate](../how-to/review-candidates.md)。 +两种决定都是终态。操作步骤见[审核 Candidate](/zh/docs/how-to/review-candidates/)。 ## Experience 和 Skill 的可用方式不同 @@ -80,7 +80,7 @@ Work Contract 将目标和完成边界保存为 Source 证据。`handoff_current Handoff。只有用户需要保留里程碑时，commit Handoff 才创建长期 Revision。接收方解析 Handoff 并记录 Acknowledgement；Task Outcome 将最终状态和检查结果保存为 Source 证据。 -[Handoff Report](../how-to/use-handoff-report.md) 将当前 Handoff Revision 投影为可检查、可导出的视图。当前 scope +[Handoff Report](/zh/docs/how-to/use-handoff-report/) 将当前 Handoff Revision 投影为可检查、可导出的视图。当前 scope report 尚不包含 Activity event 或 period comparison，也不会改写 Memory 或底层 Handoff history。 ## 各接口暴露同一个 Server 的不同部分 @@ -91,5 +91,5 @@ HTTP 是完整的远程应用契约，Python Client 提供类型化访问，MCP 模型生成、人工 Review 和执行权限彼此独立。模型可以提出内容，Review 可以批准 Artifact Revision，导出可以创建 host-local 副本；这些步骤都不会授予 Agent 执行 instructions 的权限。 -当前接口可用范围见[接口](../reference/interfaces.md)，精确设置和默认值见[配置](../reference/configuration.md)。RFC 记录 +当前接口可用范围见[接口](/zh/docs/reference/interfaces/)，精确设置和默认值见[配置](/zh/docs/reference/configuration/)。RFC 记录 设计决策，可能与当前实现不同。 diff --git a/docs/zh/docs/explanation/experience-and-skill-lifecycle.md b/docs/zh/docs/explanation/experience-and-skill-lifecycle.md index 2f1873ad1..7f44204c2 100644 --- a/docs/zh/docs/explanation/experience-and-skill-lifecycle.md +++ b/docs/zh/docs/explanation/experience-and-skill-lifecycle.md @@ -61,6 +61,6 @@ Managed Skill 包含名称、用于发现的描述、instructions、validation c 更早的 approved Revision 仍可被精确读取。导出的 Skill 目录只是某个精确 Revision 的副本，managed Artifact 始终是内容 权威。 -审核步骤见[审核 Candidate](../how-to/review-candidates.md)，Experience 操作见 -[创建并审核 Experience](../how-to/create-and-review-experience.md)，Skill 操作见 -[创建并导出 managed Skill](../how-to/create-and-export-skill.md)。 +审核步骤见[审核 Candidate](/zh/docs/how-to/review-candidates/)，Experience 操作见 +[创建并审核 Experience](/zh/docs/how-to/create-and-review-experience/)，Skill 操作见 +[创建并导出 managed Skill](/zh/docs/how-to/create-and-export-skill/)。 diff --git a/docs/zh/docs/explanation/memory-and-handoff.md b/docs/zh/docs/explanation/memory-and-handoff.md index a20421998..d82c7f58d 100644 --- a/docs/zh/docs/explanation/memory-and-handoff.md +++ b/docs/zh/docs/explanation/memory-and-handoff.md @@ -32,4 +32,4 @@ Draft 和 Prepared Handoff 默认不是长期项目知识。只有用户明确 | 保存已经验证、需要长期复用的交接里程碑 | 经用户要求提交 Handoff，或保存为 Memory | 无论使用哪一种，都不要存储密钥、访问令牌或其他敏感信息。使用 Handoff 的具体步骤见 -[在 Codex 中交接工作](../how-to/handoff-with-codex.md)。 +[在 Codex 中交接工作](/zh/docs/how-to/handoff-with-codex/)。 diff --git a/docs/zh/docs/how-to/configure-agent-skill-targets.md b/docs/zh/docs/how-to/configure-agent-skill-targets.md new file mode 100644 index 000000000..c7e60ed4a --- /dev/null +++ b/docs/zh/docs/how-to/configure-agent-skill-targets.md @@ -0,0 +1,38 @@ +--- +title: 配置 Agent Skill target +description: 注册显式的本地 Codex 或 Claude Code Skill 目录，用于发现和 managed publication。 +--- + +# 配置 Agent Skill target + +在扫描 external Skill，或从 Server UI 发布 approved managed Skill 前，先注册本地 target。 + +## 1. 设置 target 配置 + +```bash +export POWERCONTEXT_SERVER_EXTERNAL_SKILLS='{ + "host_id": "workstation-1", + "targets": [ + { + "target_id": "codex-project", + "agent_kind": "codex", + "installation_scope": "project", + "path": "/srv/project/.agents/skills", + "allow_managed_publish": true + } + ] +}' +``` + +每个目录使用唯一的 `target_id`。`agent_kind` 为 `codex` 或 `claude_code`；`installation_scope` 为 `user`、`project` +或 `plugin`。Claude Code 使用其 Skill 目录，例如 `/srv/project/.claude/skills`。 + +## 2. 重启并检查 + +重启 Server 后，在 Skills Library 中或使用 external Skill command 扫描已配置的 scope。Server 只扫描列出的 target +下的直接 package 目录，不会推断 home 目录或安装 package。 + +`allow_managed_publish` 默认是 `false`。只在允许 authenticated Server 发布 approved managed Skill 的 target 上将其设为 +`true`。发布不能选择任意路径，也不会覆盖外部或已被修改的 package。 + +配置 schema 和兼容格式见[配置](/zh/docs/reference/configuration/)。 diff --git a/docs/zh/docs/how-to/configure-server-environment.md b/docs/zh/docs/how-to/configure-server-environment.md new file mode 100644 index 000000000..6e8f690bd --- /dev/null +++ b/docs/zh/docs/how-to/configure-server-environment.md @@ -0,0 +1,38 @@ +--- +title: 配置 Server 环境 +description: 通过显式环境文件生成、检查、校验并运行 PowerContext。 +--- + +# 配置 Server 环境 + +当 Server 需要推理、调度、存储或部署设置时，使用显式环境文件。 + +## 1. 生成文件 + +```bash +powercontext config init --output .env +``` + +引导式命令会以 `0600` 权限写入私有文件。通过环境或 secret manager 提供 provider 凭据，不要把它们写入命令行参数。 + +## 2. 检查并校验 + +```bash +powercontext config show --env-file .env +powercontext config validate --env-file .env +``` + +`config show` 会隐藏已识别的凭据。校验会检查文件和所选 model 设置，但不会输出机密。 + +## 3. 使用同一份配置启动 + +```bash +powercontext server run --env-file .env +``` + +文件中的值会覆盖同名进程变量。文件中没有的继承 `POWERCONTEXT_SERVER_*` 变量会被忽略，因此校验和启动使用同一份 +Server 设置。 + +Server 会按配置启动对应能力。使用 `powercontext ready` 和 `powercontext capabilities` 查看就绪状态和已启用功能。 + +全部变量、默认值和优先级规则见[配置](../reference/configuration.md)。 diff --git a/docs/zh/docs/how-to/configure-vector-search.md b/docs/zh/docs/how-to/configure-vector-search.md new file mode 100644 index 000000000..cc24fb706 --- /dev/null +++ b/docs/zh/docs/how-to/configure-vector-search.md @@ -0,0 +1,38 @@ +--- +title: 配置向量检索 +description: 启用基于 embedding 的 vector 和 hybrid Memory 检索，并验证 Runtime capability。 +--- + +# 配置向量检索 + +向量检索需要 embedding model、稳定的 profile ID 和该模型的输出 dimension。 + +## 1. 设置一份 embedding profile + +```bash +export POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_MODEL=provider:embedding-model +export POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_PROFILE_ID=embedding-model-v1 +export POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_DIMENSION=1024 +``` + +将示例值替换为一个受支持的 provider model、该模型保持稳定的 profile ID，以及其文档给出的输出 dimension。 +`POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_NORMALIZATION` 默认值为 `unit`。 + +## 2. 启动 Server + +```bash +powercontext server run +``` + +使用 SQLite 时，PowerContext 会在打开数据库时加载内置 sqlite-vec extension。extension 与当前 platform 或 SQLite build +不兼容时，启动会失败。 + +## 3. 验证 capability + +```bash +powercontext capabilities +``` + +结果会报告已启用的 search mode。未配置 embedding profile 时，SQLite full-text search 仍可使用。 + +timeout、batch size、storage 设置和准确默认值见[配置](../reference/configuration.md)。 diff --git a/docs/zh/docs/how-to/deploy-server.md b/docs/zh/docs/how-to/deploy-server.md index 892e58565..4a3341621 100644 --- a/docs/zh/docs/how-to/deploy-server.md +++ b/docs/zh/docs/how-to/deploy-server.md @@ -94,7 +94,7 @@ docker run --rm \ ``` 此后客户端需要发送 `Authorization: Bearer `。liveness 和 readiness endpoint 保持公开，便于编排系统探测； -API、MCP、metrics、OpenAPI 和交互式 API 文档都需要鉴权。 +API、MCP、metrics 和 `/openapi.json` 需要鉴权。`/docs` 页面外壳保持公开，但在交互式参考页中发起的请求仍需鉴权。 Server 的网页外壳和静态资源仍保持公开，以便显示登录表单；未提供 token 时不会返回受保护数据。打开 Dashboard、 Skills、Review 或 Handoff Report 页面后，在表单中输入同一个 token。浏览器会把它保存在当前标签页的 session storage 中，而不是加入 URL。 diff --git a/docs/zh/docs/index.md b/docs/zh/docs/index.md index b70c2c6a3..4fc0b9d63 100644 --- a/docs/zh/docs/index.md +++ b/docs/zh/docs/index.md @@ -4,7 +4,7 @@ title: 选择 Agent 或 API，跑通第一个闭环 description: 为现有 AI 应用接入 HTTP Memory API，或为选定 Agent 配置集成并验证 Memory 与 Handoff。 page_type: docs-overview overview: - intro: 第一次使用时，先选择自己的入口。已有 AI 应用可以直接使用 HTTP API；使用 Codex、Claude Code、OpenCode 等 Host 时，从 Agent 分步入门开始。 + intro: 选择教程学习一条完整路径，选择操作指南完成具体任务，选择原理说明理解系统行为，或选择参考页查询当前契约和设置。 sections: - title: 推荐学习路径 description: 先通过 API 或 Agent 跑通本地闭环，再按需要接入其他 Host 或更完整的工作流程。 @@ -63,6 +63,15 @@ overview: - title: 配置 description: 设置存储、provider、接口和运行行为。 href: zh/docs/reference/configuration/ + - title: 配置 Server 环境 + description: 生成一份显式环境文件，完成校验，并用相同设置启动 Server。 + href: zh/docs/how-to/configure-server-environment/ + - title: 配置向量检索 + description: 设置 embedding profile，并确认 vector 和 hybrid search 是否可用。 + href: zh/docs/how-to/configure-vector-search/ + - title: 配置 Agent Skill target + description: 注册本地 Codex 或 Claude Code Skill 目录，用于发现和 managed publication。 + href: zh/docs/how-to/configure-agent-skill-targets/ - title: 部署 Server description: 使用持久化数据、健康检查、鉴权和安全网络边界运行 Server。 href: zh/docs/how-to/deploy-server/ diff --git a/docs/zh/docs/reference/configuration.md b/docs/zh/docs/reference/configuration.md index e7c6d3c4c..16185dc94 100644 --- a/docs/zh/docs/reference/configuration.md +++ b/docs/zh/docs/reference/configuration.md @@ -5,24 +5,11 @@ description: PowerContext 路径、Server、Client、推理和 Agent 集成环 # 配置 -PowerContext 进程启动时从环境变量读取配置。CLI 不会自动搜索 `.env` 文件；请在 shell 中导出变量、由服务管理器 -或容器提供，或者向支持 `--env-file` 的命令显式传入文件。Agent 宿主可能会按照自身规则加载自己的环境文件。 +PowerContext 进程启动时从环境变量读取配置。CLI 不会自动搜索 `.env` 文件。接受 `--env-file` 的命令只从该文件读取 +Server 设置，文件中的赋值会覆盖进程中的同名值。Agent 宿主可按自身规则加载环境文件。 -## 显式环境文件 - -通过引导生成配置，在不显示凭据的情况下检查内容，并在启动前完成校验： - -```bash -powercontext config init --output .env -powercontext config show --env-file .env -powercontext config validate --env-file .env -powercontext server run --env-file .env -``` - -`config init` 会以 `0600` 权限写入文件。`server run` 收到 `--env-file` 后，文件中的赋值会覆盖进程中的同名值； -文件中不存在的旧 `POWERCONTEXT_SERVER_*` 进程变量会被忽略，因此校验和启动使用同一份 Server 配置。 -`config show` 会隐藏已识别及生成器记录的凭据，但仍应把原文件当作可能含有秘密的部署文件保护。完整的引导与验证流程见 -[完整功能 Quick Start](../how-to/full-capability-runtime.md)。 +生成、脱敏查看、校验和启动配置文件的完整流程见[配置 Server 环境](../how-to/configure-server-environment.md)。所有环境 +文件都应视为包含机密的部署产物。 ## 用户数据 @@ -161,15 +148,7 @@ search request 最终 `limit` 的结果。它不会修改已存储 Memory 或索 external Skill import/fork。未配置模型时，这些 operation 会在持久化 Candidate 前返回 capability error； Candidate Review、exact read 和 external Skill scan/list/resolve 仍可使用。 -Experience 孵化使用独立的 APScheduler job 和持久化 Source cursor，可通过以下配置启用： - -```bash -export POWERCONTEXT_SERVER_RUNTIME_EXPERIENCE_SCHEDULE_SECONDS=30 -export POWERCONTEXT_SERVER_INFERENCE_GENERATION_MODEL=provider:model-name -powercontext server run -``` - -每次 activation 固定检查最多 32 条 Source，并且只把 metadata 包含 `"kind": "task-outcome"` 的 Content Source +Experience 孵化使用独立的 APScheduler job 和持久化 Source cursor。每次 activation 固定检查最多 32 条 Source，并且只把 metadata 包含 `"kind": "task-outcome"` 的 Content Source 暴露给模型。该 job 会在 Review Inbox 中创建 pending Experience Candidate；它不会自动批准、进入 PreparedContext、创建 managed Skill、将它导出到 Agent target 或执行任何内容。Memory 和 Experience job 共用 `POWERCONTEXT_HOME` 下的 APScheduler sidecar，但拥有独立的 job identity 和业务 cursor；取消其中一个 interval @@ -178,29 +157,8 @@ PreparedContext、创建 managed Skill、将它导出到 Agent target 或执行 ### Agent Skill 目标 -通过一个 JSON 值配置 Codex 和 Claude Code 的 host-local target： - -```bash -export POWERCONTEXT_SERVER_EXTERNAL_SKILLS='{ - "host_id": "workstation-1", - "targets": [ - { - "target_id": "codex-project", - "agent_kind": "codex", - "installation_scope": "project", - "path": "/srv/project/.agents/skills", - "allow_managed_publish": true - }, - { - "target_id": "claude-project", - "agent_kind": "claude_code", - "installation_scope": "project", - "path": "/srv/project/.claude/skills", - "allow_managed_publish": true - } - ] -}' -``` +`POWERCONTEXT_SERVER_EXTERNAL_SKILLS` 是包含一个本地 host identity 和显式 Codex 或 Claude Code Skill target 的 JSON +对象。JSON 结构和验证步骤见[配置 Agent Skill target](../how-to/configure-agent-skill-targets.md)。 每个 target ID 必须唯一；`agent_kind` 支持 `codex` 和 `claude_code`，installation scope 支持 `user`、`project` 和 `plugin`。PowerContext 只扫描这些显式 target 的直接 Skill package 子目录，不会推断 home 目录、安装 package @@ -228,46 +186,12 @@ export POWERCONTEXT_SERVER_DATABASE_URL="$OCEANBASE_URL" URL 必须使用 `mysql+aoceanbase` driver，包含明确的端口和数据库，并设置 `charset=utf8mb4`。对应 tenant 必须使用 MySQL 兼容模式。 -### Embedding - -只有同时设置以下三个标识字段，才会启用 embedding 检索： - -```bash -export POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_MODEL=provider:embedding-model -export POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_PROFILE_ID=embedding-model-v1 -export POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_DIMENSION=1024 -``` - -请把示例值替换为所选 provider model、稳定的 profile ID，以及该模型的 dimension。 - -可选设置包括 `POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_NORMALIZATION` 和 -`POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_TIMEOUT_SECONDS`。 - -Embedding normalization 默认为 `unit`。 - -### SQLite 向量检索 - -SQLite vector 和 hybrid search 使用 [sqlite-vec](https://alexgarcia.xyz/sqlite-vec/)，它已包含在 -`powercontext[builtin]` 依赖中。只需配置完整的 embedding profile，无需配置 extension 路径： - -```bash -export POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_MODEL=provider:embedding-model -export POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_PROFILE_ID=embedding-model-v1 -export POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_DIMENSION=1024 -export POWERCONTEXT_SERVER_DATABASE_URL=sqlite+aiosqlite:////srv/powercontext/powercontext.db -powercontext server run -``` - -Server 打开数据库时，PowerContext 会加载并探测捆绑的 extension；如果当前 platform 或 SQLite build 与 package -中的 library 不兼容，启动会失败。 - -在另一个终端确认初始化后的 Runtime 已报告 vector 和 hybrid search： - -```bash -powercontext capabilities -``` +### Embedding 与 SQLite 向量检索 -没有配置 embedding model 时，SQLite full-text search 仍然可用。 +Vector search 需要全部三个 embedding identity 变量：model、稳定 profile ID 和正数 dimension。normalization 默认 +为 `unit`；timeout 和 batch size 是可选控制项。SQLite vector 和 hybrid search 使用内置 sqlite-vec extension。Server +打开数据库时会探测它，已安装的 library 与 platform 或 SQLite build 不兼容时启动会失败。没有 embedding profile 时， +full-text search 仍可用。配置和 capability 验证步骤见[配置向量检索](../how-to/configure-vector-search.md)。 ## CLI Server 连接 diff --git a/docs/zh/docs/reference/http-api.md b/docs/zh/docs/reference/http-api.md index 3121392dc..30e3e8ff8 100644 --- a/docs/zh/docs/reference/http-api.md +++ b/docs/zh/docs/reference/http-api.md @@ -12,17 +12,14 @@ HTTP API 是访问 PowerContext Server 的语言无关接口。默认 base URL ## 查看契约 -本地未启用鉴权的 Server 运行后，可以打开： - -- `/docs`：交互式 Swagger UI； -- `/redoc`：ReDoc； -- `/openapi.json`：该进程实际提供的契约。 +本地未启用鉴权的 Server 运行后，可以打开 `/docs` 查看交互式 Scalar API 参考，或打开 `/openapi.json` 获取该进程实际提供的 +契约。 仓库中的契约源文件是 [`openapi/powercontext.yaml`](https://github.com/oceanbase/powercontext/blob/master/openapi/powercontext.yaml)。 -生成客户端或检查全部请求、响应字段时以它为准。启用 Server 鉴权后，这三个发现路由与其他受保护路由一样需要 Bearer -token。浏览器地址栏无法添加该 header；应使用可信的代理或浏览器配置注入 header，或者设置下方变量后，通过带鉴权的 -命令下载 `/openapi.json`。不要把 token 放进 URL。 +生成客户端或检查全部请求、响应字段时以它为准。启用 Server 鉴权后，`/docs` 仍保持公开以渲染参考页，但在其中发起的 +请求仍需鉴权。`/openapi.json` 需要 Bearer token。浏览器地址栏无法添加该 header；应使用可信的代理或浏览器配置注入 +header，或者通过带鉴权的命令下载 `/openapi.json`。不要把 token 放进 URL。 ## 请求鉴权 diff --git a/docs/zh/docs/reference/interfaces.md b/docs/zh/docs/reference/interfaces.md index 7455389ee..f84abe0e6 100644 --- a/docs/zh/docs/reference/interfaces.md +++ b/docs/zh/docs/reference/interfaces.md @@ -24,7 +24,7 @@ description: 在 Agent 集成、CLI、Python SDK、HTTP 和 MCP 之间选择。 | Python Client SDK | 对运行中的 Server 发起类型化异步调用 | [安装 Client role](../how-to/install-and-run.md) | | Core SDK | 进程内 Source、Artifact、Trigger 和组合契约 | [Python API 参考](/zh/modules/) | | HTTP | 从任意语言集成服务 | [HTTP API](http-api.md) | -| MCP | 面向 Agent 的 Memory 与工作连续性工具 | Server 在 `/mcp` 启用 | +| MCP | 面向 Agent 的 Source 采集、Memory、工作连续性、报告和 Candidate Review 精选工具 | Server 在 `/mcp` 启用 | ## Codex 插件 @@ -33,46 +33,14 @@ project-context skill 指导 Codex 何时检索、记忆、修订、停用、委 ## 工作连续性 -Server 通过 HTTP、Python Client 和 MCP 暴露同一个高层闭环： +HTTP、Python Client 和 MCP 都提供 Work Contract 创建、Handoff 准备和继续、acknowledgement 与 Task Outcome 记录。 +Prepared Handoff 是临时内容，`commit_handoff` 才会创建持久 Revision。acknowledgement 可选择 prepared 或 exact Handoff， +但 `handoff_receipt_ref` 只能引用 committed Revision 对应的 accepted exact Receipt。claim 和 check 可以是 `declared`， +也可以是带有 exact same-scope citation 的 `verified`。这些 record 不会授予身份、工具或执行权限。 -```text -create_work_contract - -> 推进工作 - -> handoff_current_work - -> continue_handoff + acknowledge_handoff - -> record_task_outcome -``` - -`create_work_contract` 为新委托记录目标、范围、完成标准、授权说明和关键待决问题。`handoff_current_work` 采集调用方已 -检查的当前状态并返回临时 Prepared Handoff；它不会发布里程碑。只有用户需要持久化里程碑时，才另行调用 -`commit_handoff`。 - -接收方先用 prepared、exact 或 latest selection 调用 `continue_handoff`；如果从 latest 开始，必须把返回的 exact Revision -展示并检查后再记录回执。`acknowledge_handoff` 只接受 prepared 或 exact，不接受 latest。任一 Handoff evidence 不可用， -或 live-state、capability、authorization 没有全部确认为 `confirmed` 时，都会拒绝 accepted。接收方也可以记录 -`needs_clarification` 或 `declined`。回执及三项确认只记录不可信观察，不能授予身份、工具或执行权限。 - -`record_task_outcome` 原样保留 `succeeded`、`partial`、`blocked`、`failed`、`cancelled` 或 `unknown`，以及精确检查 -状态。需要关闭 committed Handoff 结果时，`handoff_receipt_ref` 必须引用当前 accepted exact Receipt；同 scope 中无关联的 -Outcome 不会覆盖它。该 operation 保存现有 Experience 孵化可读取的 `task-outcome` Source，但不会自行生成或批准 -Experience。Integration 只应在真实完成或中断边界调用它，不能仅因 Prompt、Stop 或 Session 结束而调用。 - -Claim 和 check 要么是没有 evidence 的 `declared`，要么是拥有同 scope 精确 citation 的 `verified`。Citation 可读只证明 -身份和可用性，不证明事实仍然新鲜。当前指令、实时 workspace、能力和授权始终优先于 Work 与 Handoff 记录。 - -完整 Codex 转交和接收确认流程见[在 Codex 中交接工作](../how-to/handoff-with-codex.md)。 - -Handoff Report 会列出包含 committed Handoff 的 scope，`get_handoff_report` 要求提供 `scope_id`。`project_id` 仅作为 -deprecated wire-compatibility input 保留，生成报告时会被忽略。每个返回的 Workstream projection 包含 -`handoff_revision_count`、`handoff_history_truncated` 和 `handoff_history`，最多返回 frozen selection 之前最近 20 个 -Revision 摘要。Web 操作见[使用 Handoff Report](../how-to/use-handoff-report.md)。 - -当前 scope report 不返回 Activity event，`activity_coverage=not_configured`，并且没有 period comparison。Period -输入只会被规范化，不会筛选 Activity。Server 未启用鉴权时，HTTP 和 Python Client 的 Markdown operation 仍可不带 -token 使用；当前浏览器下载和后台刷新控件要求已保存的 Bearer token。 - -Codex scope resolver 支持把当前 Git 工作区一次绑定到固定 Workstream scope，绑定优先于 Git remote 和路径推导，但低于 -显式 scope 配置。 +Handoff Report API 列出含 committed Handoff 的 scope，并要求 `scope_id`；已废弃的 `project_id` input 在生成 scope report +时会被忽略。scope report 当前不返回 Activity event，也不提供 period comparison。workflow 见 +[在 Codex 中交接工作](../how-to/handoff-with-codex.md)，报告 UI 见[使用 Handoff Report](../how-to/use-handoff-report.md)。 ## DeepSeek Harness 插件 @@ -168,41 +136,9 @@ Generation 和 revision 命令通过可重复的 `--source-ref TYPE/ID` 与 ## Python Client SDK -由 Server 管理持久化时，使用 Client SDK： - -```python -import asyncio - -from powercontext.http import PrepareContextRequest, RememberMemoryRequest, SearchMemoryRequest -from powercontext.client import PowerContextClient - - -async def main() -> None: - async with PowerContextClient("http://127.0.0.1:8000") as client: - await client.remember_memory( - RememberMemoryRequest( - scope_id="project:example", - kind="decision", - text="保持公开 API 异步化。", - ) - ) - result = await client.search_memory( - SearchMemoryRequest( - scope_id="project:example", - query="公开 API", - ) - ) - print([hit.text for hit in result.hits]) - prepared = await client.prepare_context( - PrepareContextRequest(scope_id="project:example", query="公开 API") - ) - print(prepared.content) - - -asyncio.run(main()) -``` - -变更操作的响应包含精确 citation。修订、停用或读取不可变条目版本时，应把该 citation 传回 Server。 +`PowerContextClient` 是面向 Server-owned deployment 的 typed asynchronous HTTP client。其 request 和 response model +从 `powercontext.http` 导出。Mutation response 包含 exact citation，后续修订、停用或读取某个不可变 entry version 时需传回 +该 citation。可运行的 Client 流程见[HTTP API 生命周期教程](../tutorials/api-quickstart.md)。 Client 还提供 `generate_experience`、`propose_experience`、`get_experience`、`generate_skill`、 `propose_skill`、`get_skill`、`scan_external_skills`、`list_external_skills`、 @@ -291,8 +227,8 @@ Discovery 不进入 Review。显式调用 `import_external_skill` 并提供精 Scalar API reference，在 `/openapi.json` 提供 OpenAPI 文档，在 `/health/ready` 提供就绪检查，在 `/v1/capabilities` 提供能力信息，并默认在 `/mcp` 提供 Streamable HTTP MCP。启用 Bearer authentication 后， Scalar reference 仍可公开访问，但其中描述的 operation 继续遵守各自的认证要求。HTTP 是完整应用契约，MCP 是 -面向 Agent 的 Memory 与 Candidate Review operation 子集。五个 Candidate Review operation 通过 HTTP 和 MCP -使用相同的 validation、`expected_version` 并发校验和 approval transaction。Experience/Skill generation、 +面向 Agent 的 Source 采集、Memory 维护、工作连续性、scope Handoff Report 查询和 Candidate Review 精选子集。五个 +Candidate Review operation 通过 HTTP 和 MCP 使用相同的 validation、`expected_version` 并发校验和 approval transaction。Experience/Skill generation、 exact read、external Registry operation 和低阶 proposal operation 仍只通过 HTTP 提供。 所有检查通过时 readiness 为 HTTP 200 的 `ready`；只有已配置的推理检查失败时为 HTTP 200 的 `degraded`； Runtime 或数据库失败时为 HTTP 503 的 `not_ready`。依赖检查使用 `ready`、`unavailable`、`timeout` 或 diff --git a/zensical.toml b/zensical.toml index 529538266..60dda89fa 100644 --- a/zensical.toml +++ b/zensical.toml @@ -12,17 +12,19 @@ nav = [ { "English" = [ { "Home" = "en/index.md" }, { "Docs" = [ - { "Get started" = [ + { "Tutorials" = [ { "Overview" = "en/docs/index.md" }, { "HTTP API lifecycle tutorial" = "en/docs/tutorials/api-quickstart.md" }, { "Agent step-by-step quickstart" = "en/docs/tutorials/agent-quickstart.md" }, { "Complete Codex tutorial" = "en/docs/tutorials/codex-quickstart.md" }, + ] }, + { "How-to guides" = [ { "Install and run" = "en/docs/how-to/install-and-run.md" }, { "Full-capability Quick Start" = "en/docs/how-to/full-capability-runtime.md" }, + { "Configure a Server environment" = "en/docs/how-to/configure-server-environment.md" }, { "Deploy the Server" = "en/docs/how-to/deploy-server.md" }, - { "Core concepts" = "en/docs/explanation/core-concepts.md" }, - { "Memory and Handoff" = "en/docs/explanation/memory-and-handoff.md" }, - { "Experience and Skill lifecycle" = "en/docs/explanation/experience-and-skill-lifecycle.md" }, + { "Configure vector search" = "en/docs/how-to/configure-vector-search.md" }, + { "Configure Agent Skill targets" = "en/docs/how-to/configure-agent-skill-targets.md" }, { "Hand off work in Codex" = "en/docs/how-to/handoff-with-codex.md" }, { "Use Handoff Report" = "en/docs/how-to/use-handoff-report.md" }, { "Review Candidates" = "en/docs/how-to/review-candidates.md" }, @@ -30,6 +32,11 @@ nav = [ { "Create and export a managed Skill" = "en/docs/how-to/create-and-export-skill.md" }, { "Troubleshoot" = "en/docs/how-to/troubleshoot.md" }, ] }, + { "Explanation" = [ + { "Core concepts" = "en/docs/explanation/core-concepts.md" }, + { "Memory and Handoff" = "en/docs/explanation/memory-and-handoff.md" }, + { "Experience and Skill lifecycle" = "en/docs/explanation/experience-and-skill-lifecycle.md" }, + ] }, { "Integrations" = [ { "Configure Codex" = "en/docs/how-to/configure-codex.md" }, { "Configure Claude Code" = "en/docs/how-to/configure-claude-code.md" }, @@ -99,17 +106,19 @@ nav = [ { "中文" = [ { "首页" = "zh/index.md" }, { "文档" = [ - { "开始使用" = [ + { "教程" = [ { "概览" = "zh/docs/index.md" }, { "HTTP API 生命周期教程" = "zh/docs/tutorials/api-quickstart.md" }, { "Agent 分步入门" = "zh/docs/tutorials/agent-quickstart.md" }, { "Codex 完整教程" = "zh/docs/tutorials/codex-quickstart.md" }, + ] }, + { "操作指南" = [ { "安装和运行" = "zh/docs/how-to/install-and-run.md" }, { "完整功能 Quick Start" = "zh/docs/how-to/full-capability-runtime.md" }, + { "配置 Server 环境" = "zh/docs/how-to/configure-server-environment.md" }, { "部署 Server" = "zh/docs/how-to/deploy-server.md" }, - { "核心概念" = "zh/docs/explanation/core-concepts.md" }, - { "理解 Memory 和 Handoff" = "zh/docs/explanation/memory-and-handoff.md" }, - { "Experience 与 Skill 生命周期" = "zh/docs/explanation/experience-and-skill-lifecycle.md" }, + { "配置向量检索" = "zh/docs/how-to/configure-vector-search.md" }, + { "配置 Agent Skill target" = "zh/docs/how-to/configure-agent-skill-targets.md" }, { "在 Codex 中交接工作" = "zh/docs/how-to/handoff-with-codex.md" }, { "使用 Handoff Report" = "zh/docs/how-to/use-handoff-report.md" }, { "审核 Candidate" = "zh/docs/how-to/review-candidates.md" }, @@ -117,6 +126,11 @@ nav = [ { "创建并导出 managed Skill" = "zh/docs/how-to/create-and-export-skill.md" }, { "排查问题" = "zh/docs/how-to/troubleshoot.md" }, ] }, + { "原理说明" = [ + { "核心概念" = "zh/docs/explanation/core-concepts.md" }, + { "理解 Memory 和 Handoff" = "zh/docs/explanation/memory-and-handoff.md" }, + { "Experience 与 Skill 生命周期" = "zh/docs/explanation/experience-and-skill-lifecycle.md" }, + ] }, { "集成方式" = [ { "配置 Codex" = "zh/docs/how-to/configure-codex.md" }, { "配置 Claude Code" = "zh/docs/how-to/configure-claude-code.md" },