Skip to content

docs: add a full-capability runtime setup guide #1333

Description

@happy-v587

Feature description

新增一份完整能力运行指南,说明如何在不改变默认最小启动行为的前提下,配置并启动一个功能完整的 PowerContext Server。

文档应覆盖 Generation、Embedding、Scheduler、SQLite Vec1、Dashboard、Scope ID、数据库路径和宿主集成之间的关系,并提供一套可复制的配置与验证流程。

Problem and proposed solution

当前的 powercontext server run 可以在没有推理服务和向量扩展的情况下启动,因此适合最小体验,但很多能力默认处于关闭或降级状态。用户需要自行从安装、配置、推理、向量索引和集成文档中拼接出一套完整运行方式,容易遇到以下问题:

  • 未配置 Generation model,Source 无法自动提取为 Memory;
  • 未配置 Embedding model、Profile ID 和 dimension,无法使用 Embedding;
  • Vec1 路径不存在或版本不兼容时,Server 会在启动阶段失败;
  • 数据库路径被示例配置覆盖后,可能误连到空数据库;
  • Server scope、Dashboard scope 和 Codex/OpenCode 等宿主 scope 不一致时,看不到预期数据;
  • Scheduler、Dashboard 和 MCP 的启用状态不容易确认。

建议新增一篇 how-to 文档,并提供一份不包含密钥、明确标注可选 Vec1 路径和模型占位符的完整配置示例。文档应将运行方式命名为“完整能力运行”或 full-capability runtime,而不是修改默认启动命令或引入 --profile full

Alternatives considered

  • 继续让用户分别阅读安装、配置、推理和集成文档:信息已存在,但缺少端到端路径;
  • 修改默认 powercontext server run,自动开启所有能力:会引入模型费用、动态库和外部服务依赖,不适合作为默认行为;
  • 增加 --profile fullmake server-full:可以后续讨论,但本 Issue 首先聚焦文档和规范配置示例。

Additional context

建议产出:

  • docs/zh/docs/how-to/full-capability-runtime.md
  • docs/en/docs/how-to/full-capability-runtime.md
  • zensical.toml 的 Get started / 开始使用导航中加入入口;
  • 必要时调整 .env.example,避免把不存在的 Vec1 动态库或项目内空数据库作为默认可复制配置。

文档至少应包含:

  1. 默认最小运行与完整能力运行的能力矩阵;
  2. Generation、Embedding、数据库、Vec1、Scheduler 和 Dashboard 环境变量分组;
  3. Scope ID 的来源、显式覆盖方式和跨宿主一致性要求;
  4. 从加载环境变量、启动 Server 到 doctorreadycapabilities、Memory flush 的完整命令;
  5. 预期输出、数据位置、停止方式和常见故障排查;
  6. 明确说明没有 Vec1 时仍可使用 SQLite FTS,但不会启用 vector/hybrid 搜索;
  7. 不把 API Key、连接凭据或其他敏感信息写入文档示例或 Memory。

验收标准:读者只依赖该指南和项目仓库中的示例,就能启动一套配置明确、可验证、不会误连空库的完整能力运行环境,并能判断每项能力是否真正 ready。

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

Status
Todo

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions