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 full 或 make 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 动态库或项目内空数据库作为默认可复制配置。
文档至少应包含:
- 默认最小运行与完整能力运行的能力矩阵;
- Generation、Embedding、数据库、Vec1、Scheduler 和 Dashboard 环境变量分组;
- Scope ID 的来源、显式覆盖方式和跨宿主一致性要求;
- 从加载环境变量、启动 Server 到
doctor、ready、capabilities、Memory flush 的完整命令;
- 预期输出、数据位置、停止方式和常见故障排查;
- 明确说明没有 Vec1 时仍可使用 SQLite FTS,但不会启用 vector/hybrid 搜索;
- 不把 API Key、连接凭据或其他敏感信息写入文档示例或 Memory。
验收标准:读者只依赖该指南和项目仓库中的示例,就能启动一套配置明确、可验证、不会误连空库的完整能力运行环境,并能判断每项能力是否真正 ready。
Feature description
新增一份完整能力运行指南,说明如何在不改变默认最小启动行为的前提下,配置并启动一个功能完整的 PowerContext Server。
文档应覆盖 Generation、Embedding、Scheduler、SQLite Vec1、Dashboard、Scope ID、数据库路径和宿主集成之间的关系,并提供一套可复制的配置与验证流程。
Problem and proposed solution
当前的
powercontext server run可以在没有推理服务和向量扩展的情况下启动,因此适合最小体验,但很多能力默认处于关闭或降级状态。用户需要自行从安装、配置、推理、向量索引和集成文档中拼接出一套完整运行方式,容易遇到以下问题:建议新增一篇 how-to 文档,并提供一份不包含密钥、明确标注可选 Vec1 路径和模型占位符的完整配置示例。文档应将运行方式命名为“完整能力运行”或
full-capability runtime,而不是修改默认启动命令或引入--profile full。Alternatives considered
powercontext server run,自动开启所有能力:会引入模型费用、动态库和外部服务依赖,不适合作为默认行为;--profile full或make 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 动态库或项目内空数据库作为默认可复制配置。文档至少应包含:
doctor、ready、capabilities、Memory flush 的完整命令;验收标准:读者只依赖该指南和项目仓库中的示例,就能启动一套配置明确、可验证、不会误连空库的完整能力运行环境,并能判断每项能力是否真正 ready。