From aedbcb6b54b13ce74c501b8098019e832a310dc2 Mon Sep 17 00:00:00 2001 From: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com> Date: Tue, 3 Nov 2026 13:46:20 +0800 Subject: [PATCH] docs(site): scope P0 repairs and clarify deployment choices Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com> --- docs/skillhub/en/faq.md | 2 +- docs/skillhub/faq.md | 2 +- .../repair-online-documentation/design.md | 21 +++++++++ .../repair-online-documentation/proposal.md | 31 +++++++++++++ .../documentation-factual-accuracy/spec.md | 43 +++++++++++++++++++ .../repair-online-documentation/tasks.md | 23 ++++++++++ 6 files changed, 120 insertions(+), 2 deletions(-) create mode 100644 openspec/changes/repair-online-documentation/design.md create mode 100644 openspec/changes/repair-online-documentation/proposal.md create mode 100644 openspec/changes/repair-online-documentation/specs/documentation-factual-accuracy/spec.md create mode 100644 openspec/changes/repair-online-documentation/tasks.md diff --git a/docs/skillhub/en/faq.md b/docs/skillhub/en/faq.md index 2163835a5..78ad13374 100644 --- a/docs/skillhub/en/faq.md +++ b/docs/skillhub/en/faq.md @@ -69,7 +69,7 @@ A: Select the namespace in the UI. To install with the CLI, use `skillhub instal ## Q: What is the recommended deployment method? Can I pull the images and deploy manually? -A: Official runtime scripts, release Compose, and Kubernetes/Helm are supported. Choose one and retain its configuration and data directories. See [Docker deployment](./guide/deployment.md) and [Kubernetes](./guide/kubernetes.md). Running an application image alone does not configure its database, Redis, storage, authentication, or proxy. +A: Choose the runtime script, release Compose, Kubernetes Kustomize, or the Helm Chart. The script and Compose paths are covered by [Docker deployment](./guide/deployment.html). Kustomize uses `deploy/k8s`; follow [Kubernetes deployment](./guide/kubernetes.html). Helm uses the separate `charts/skillhub` directory and values; follow the [Chart README (Chinese)](https://github.com/iflytek/skillhub/blob/main/charts/skillhub/README.md). Do not mix configuration or upgrade commands between the two Kubernetes paths. Preserve the configuration and data directory for the selected path. Starting an application image alone does not verify database, Redis, storage, authentication, or proxy behavior. ## Q: What Kubernetes version does the Kubernetes deployment require? diff --git a/docs/skillhub/faq.md b/docs/skillhub/faq.md index 61e508b29..5c2d3b71a 100644 --- a/docs/skillhub/faq.md +++ b/docs/skillhub/faq.md @@ -69,7 +69,7 @@ A: 在网页中选择命名空间；CLI 安装可使用 `skillhub install @team/ ## Q: 推荐的部署方式是什么？可以自己拉镜像手动部署吗？ -A: 支持官方 runtime 脚本、release Compose 和 Kubernetes/Helm。选择一种方式并保留对应的配置与数据目录，参见 [Docker 部署](./guide/deployment.md) 和 [Kubernetes 部署](./guide/kubernetes.md)。手动部署需要正确配置数据库、Redis、存储、认证和代理，不能只启动应用镜像。 +A: 可选 runtime 脚本、release Compose、Kubernetes Kustomize 或 Helm Chart。脚本与 Compose 见 [Docker 部署](./guide/deployment.html)；Kustomize 的工作目录是 `deploy/k8s`，见 [Kubernetes 部署](./guide/kubernetes.html)；Helm 使用独立的 `charts/skillhub` 和 values，见 [Chart README](https://github.com/iflytek/skillhub/blob/main/charts/skillhub/README.md)。两种 Kubernetes 路径不能混用配置或升级命令。部署前须选定一条路径，保留对应配置和数据目录；仅启动应用镜像不能证明数据库、Redis、存储、认证和代理可用。 ## Q: 用 Kubernetes 部署对集群版本有要求吗？ diff --git a/openspec/changes/repair-online-documentation/design.md b/openspec/changes/repair-online-documentation/design.md new file mode 100644 index 000000000..26f676248 --- /dev/null +++ b/openspec/changes/repair-online-documentation/design.md @@ -0,0 +1,21 @@ +## Context + +审计基线为 2026-11-02 全站渲染快照。源码基线为包含 #1037/#1048 的 main。2026-11-03 最新公开 Release 为 [v0.2.25](https://github.com/iflytek/skillhub/releases/tag/v0.2.25)，不得将 main 已合并能力写成所有已发布实例均可用。 + +## Decisions + +- 以 Controller、DTO、领域枚举/策略、CLI 命令和实际部署配置为事实源；每项新增技术说明给出对应稳定源码路径。 +- 保持单一职责：第一批只修 P0，保留后续 IA/旧模板重构待办，不边修边移动目录。 +- 状态按实际对象及字段解释。审计提到的枚举须重新核对；例如审核动作不代表必定存在同名任务枚举，头像可能包含多个状态维度。 +- 权限表按空间类型、状态和身份展开，不把平台角色等同空间角色；后端返回的能力与业务前置仍须明确解释。 +- Scanner 默认值与部署覆盖值放同一单元。诊断仅列目标变量，不输出整份环境、Secret 或含凭据的渲染清单。 +- 操作示例标注工作目录、权限、可观察结果与失败下一步；坐标及域名为明确占位。 +- 新内容按用户 C/D 约束写作；不以凑字数、套用失败模板或夸大保障代替必要事实。已有其他批缺口不得伪装为已完成。 + +## Validation + +按 P0 编号记录来源、变更及验收。先核对相对路径和自动锚点，再运行仓库既有 VitePress 构建；用真实 Chromium 检查更改页面、表格、亮暗主题和 390px 布局。文档预览独立于应用服务。独立 Review 复核所有新增权限、状态、接口和配置断言。 + +## Deferred + +A2 的 29 项导航不是本 PR 的发布承诺；P1/P2、D10 全页深度改造与 A7 全站条件另批交付。架构方案中的“不记录 trace”等断言必须先核对现有可观测性能力，不作为本 PR 事实写入。 diff --git a/openspec/changes/repair-online-documentation/proposal.md b/openspec/changes/repair-online-documentation/proposal.md new file mode 100644 index 000000000..d2dd4912c --- /dev/null +++ b/openspec/changes/repair-online-documentation/proposal.md @@ -0,0 +1,31 @@ +## Why + +2026-11-02 在线文档审计指出部署路径、状态对象、权限前置及排障动作不完整。审计只核对了渲染页面，不能直接作为接口或默认值事实。2026-11-03 维护者授权按审计约束修复并另建 PR；最新基线已经包含 PR #1037 和 #1048。 + +## What Changes + +本 PR 只交付 A6 第一批 P0-1 至 P0-9：逐项对照实际源码，修正中英文部署路径、独立状态对象、命名空间创建及治理权限、扫描默认值与禁用后果、可执行诊断、创作草稿契约和快速开始失败处理。 + +保持既有路由、菜单顺序、接口、角色、发布和审核行为不变。中文改动与英文同批更新。新增站内链接使用相对 `.html` 路径，源码依据链接稳定的 `main` 文件。 + +## Delivery Sequence + +1. 本 PR：P0 事实与可执行性修复。 +2. 后续独立 PR：旧模板页与简介/快速开始深度改造。 +3. 后续独立 PR：公共概念、权限、状态、部署选型和任务链路的信息架构重构。 +4. 后续独立 PR：其余页面、FAQ 迁移和接口参考补齐。 +5. 最后批次：全站双语、导航、元数据及排版一致性复核。 + +不跨批混合发布。每批中文和英文必须同步，第五批不作为拖延翻译的理由。本批检查适用的增量条款；后续批的既有缺口保持未完成，不宣称全站 C10 或 A7 已通过。 + +## Capabilities + +### New Capabilities +- `documentation-factual-accuracy`: 面向读者的源码可追溯、双语一致且可操作的文档说明。 + +### Modified Capabilities +无产品能力变化。纠正文档以描述实现，不修改实现以适配审计假设。 + +## Impact + +仅文档和 OpenSpec 记录。无需应用镜像、数据库迁移或真实业务部署。验证包括来源核对、文档构建、链接/锚点及中英页面/亮暗主题/移动宽度浏览器检查；PR CI 和独立 Review 单独记录。 diff --git a/openspec/changes/repair-online-documentation/specs/documentation-factual-accuracy/spec.md b/openspec/changes/repair-online-documentation/specs/documentation-factual-accuracy/spec.md new file mode 100644 index 000000000..45b7d8d63 --- /dev/null +++ b/openspec/changes/repair-online-documentation/specs/documentation-factual-accuracy/spec.md @@ -0,0 +1,43 @@ +## ADDED Requirements + +### Requirement: Describe verified deployment and scanning behavior +The documentation SHALL distinguish independent Kustomize and Helm deployment paths, co-locate application defaults with deployment overrides, and explain the actual consequences of disabling scanning. + +#### Scenario: Select a Kubernetes deployment path +- **WHEN** a deployment operator opens the guide or FAQ +- **THEN** Kustomize and Helm are identified as independent paths with their correct configuration sources +- **AND** a rendering prerequisite is not presented as real-cluster validation + +#### Scenario: Diagnose a scanner problem +- **WHEN** an operator follows a diagnostic action +- **THEN** the action specifies its working context, a real command or UI location, expected observation and failure direction +- **AND** it does not print credentials or instruct destructive retries + +### Requirement: Keep state and permission objects distinct +The documentation SHALL use actual enums, API fields and policy conditions rather than borrowing labels across review tasks, skill versions, bundle operations or avatar processing. + +#### Scenario: Decide whether a namespace operation is available +- **WHEN** an operator reads creation or governance instructions +- **THEN** platform and namespace roles are distinguished and the type/state/action prerequisites are explicit +- **AND** the instructions do not grant capabilities absent from the server + +### Requirement: Explain complete authoring and first-use actions +The documentation SHALL explain implemented authoring draft endpoints and their relationship to upload, validation, submission and published versions; quickstart failures SHALL provide an immediate verifiable action. + +#### Scenario: Submit an authoring draft +- **WHEN** an author follows the documented draft path +- **THEN** method/path, authorization, required input and resulting object are grounded in actual code +- **AND** structure validation is distinguished from scanning, review and publication + +#### Scenario: First installation fails +- **WHEN** a reader selects a quickstart failure row +- **THEN** it includes a local check, observable result and next step before any reference link + +### Requirement: Deliver bilingual staged documentation +Each batch SHALL preserve existing routes and product behavior, synchronize Chinese and English, and validate affected content without claiming deferred site-wide criteria are complete. + +#### Scenario: Complete the first documentation batch +- **WHEN** the P0 correction PR is delivered +- **THEN** P0-1 through P0-9 have explicit source and verification records +- **AND** document build, links and browser checks are reported separately from application runtime tests +- **AND** later depth and navigation work remains explicitly pending diff --git a/openspec/changes/repair-online-documentation/tasks.md b/openspec/changes/repair-online-documentation/tasks.md new file mode 100644 index 000000000..c77af46e7 --- /dev/null +++ b/openspec/changes/repair-online-documentation/tasks.md @@ -0,0 +1,23 @@ +## 1. 第一批：事实与可执行性 +- [ ] P0-1 核对 Kustomize / Helm 独立路径，统一入口/正文/FAQ，中英同步。 +- [ ] P0-2 四类状态对象按真实字段和枚举解释，消除审核动作与版本状态混用。 +- [ ] P0-3 命名空间创建步骤写明平台角色前置。 +- [ ] P0-4 Scanner 默认值与部署覆盖值同格列出。 +- [ ] P0-5 禁用扫描的上传/发布后果明确且符合代码。 +- [ ] P0-6 Scanner 诊断有命令、预期值和失败处理，不回显凭据。 +- [ ] P0-7 命名空间治理的状态/身份/动作矩阵和前置条件准确。 +- [ ] P0-8 创作草稿 API、校验/提交/发布对象关系与 ZIP 路径明确。 +- [ ] P0-9 快速开始失败表提供就地动作与完成判断，不用纯跳转替代。 + +## 2. 本批验收 +- [ ] 源码对照、双语和术语检查。 +- [ ] 相对链接/锚点、OpenSpec 和 VitePress 构建。 +- [ ] 浏览器核对更改页面、亮暗主题与移动宽度。 +- [ ] 一次集中独立 Review，修复阻断问题。 +- [ ] Draft PR 更新为可审查状态，附本批覆盖与后续未完成范围；不自动合并。 + +## 3. 后续批次（本 PR 不交付） +- [ ] A6 第二批：深度基准样本与旧模板退场。 +- [ ] A6 第三批：公共知识层、链路页及导航重构。 +- [ ] A6 第四批：其余页面与 FAQ/接口参考补齐。 +- [ ] A6 第五批：全站双语/元数据/排版复核。