feat: add skill-midway package and installers (#4549)

* add skill-midway package and installers

* docs: 更新文档编辑链接和新增技能包博客

更新 Docusaurus 配置中文档的编辑 URL 指向 v4-next 分支，确保贡献者能正确提交更改到对应版本分支。新增技能包 @midwayjs/skill-midway 的介绍博客，详细说明其安装和使用方法，以帮助开发者利用 AI 工具提升 Midway 开发体验。

* chore: 将 @midwayjs/skill-midway 添加到强制发布列表

更新 lerna 配置，在 version 命令的 forcePublish 数组中新增 @midwayjs/skill-midway 包，以确保其在发布时版本号被强制更新。

* fix: 修复错误输出时堆栈与消息的括号优先级问题

* style(skill-midway): 格式化代码以符合项目代码风格

- 在 package.json 中添加 `lint` 脚本以检查代码风格
- 调整多行语句的括号和运算符换行以保持一致性
- 统一字符串模板和 YAML 前导符的引号使用
- 重构长行代码以提高可读性

Author: czy88840616

.gitignore

@@ -22,6 +22,8 @@ midway_benchmark_app
 .env
 docs-api
 site/changelog
+site/.midway-skill
+packages/skill-midway/bundle
 .changelog
 **/test/*.txt
 .audit

lerna.json

@@ -23,7 +23,10 @@
       ]
     },
     "version": {
-      "forcePublish": "@midwayjs/version"
+      "forcePublish": [
+        "@midwayjs/version",
+        "@midwayjs/skill-midway"
+      ]
     }
   },
   "changelog": {

openspec/changes/add-midway-agent-knowledge/design.md

@@ -0,0 +1,213 @@
+## Context
+Midway 主仓已经具备构建 agent 知识层的核心原材料：
+
+- `site/docs` 与 `site/versioned_docs`：教程、组件、扩展、迁移文档
+- `site/versions.json` 与 Docusaurus 当前版本配置：版本边界
+- `api-typedoc.json`：结构化 API 符号与源码链接
+- `CHANGELOG.md`：版本演进
+- `packages/mcp`：Midway 自身的 MCP 承载能力
+- `@signalwire/docusaurus-plugin-llms-txt`：面向 LLM 的文本出口
+
+当前缺口不在“有没有内容”，而在“有没有适合 agent 稳定查询的数据契约”。
+
+## Goals / Non-Goals
+
+- Goals:
+  - 产出一套官方、版本化、可结构化查询的知识快照
+  - 同时覆盖文档、API 符号、包维度和 changelog 语义
+  - 为 skill、`@midwayjs/skill-midway`、MCP 提供统一数据源，而不是各自抓站点
+  - 保持中英文信息与版本命中关系
+  - 把“最新”明确落在当前文档版本与生成时间上
+
+- Non-Goals:
+  - 不在本 change 中实现向量搜索或复杂排序系统
+  - 不让 skill 文件承载大量领域正文
+  - 不把 consumer 绑定为单一命令行工具或单一 MCP 实现
+  - 不引入非官方内容源
+
+## Architecture Overview
+
+整体分为 4 层：
+
+### 1. Source Collection Layer
+输入源：
+
+- `site/docs/**`
+- `site/i18n/en/docusaurus-plugin-content-docs/current/**`
+- `site/versioned_docs/version-*/**`
+- `site/.docusaurus/api-typedoc-default.json` 或对应 versioned `api-typedoc.json`
+- `site/versions.json`
+- `CHANGELOG.md`
+- 相关 `packages/*/package.json`
+
+该层只负责收集，不负责面向 consumer 的查询逻辑。
+
+### 2. Normalization Layer
+将多源内容转换为稳定记录：
+
+- `DocRecord`
+- `ApiRecord`
+- `PackageRecord`
+- `ChangelogRecord`
+- `VersionRecord`
+
+每条记录至少包含：
+
+- `id`
+- `kind`
+- `version`
+- `locale`
+- `title`
+- `summary`
+- `sourcePath`
+- `sourceUrl`
+
+其中 API 记录额外包含：
+
+- `packageName`
+- `symbolName`
+- `symbolKind`
+- `qualifiedName`
+- `since`
+- `deprecated`
+
+### 3. Bundle Distribution Layer
+知识快照输出为 transport-neutral bundle，建议拆分为：
+
+```text
+midway-skill/
+  manifest.json
+  versions/
+    4.0.0/
+      docs.json
+      api.json
+      packages.json
+      changelog.json
+    3.0.0/
+      docs.json
+      api.json
+      packages.json
+      changelog.json
+```
+
+其中 `manifest.json` 提供：
+
+- 当前版本
+- 历史版本列表
+- 生成时间
+- 支持的 locale
+- 每个 bundle 文件的路径与摘要
+
+### 4. Consumer Layer
+官方只冻结查询契约，不冻结唯一 transport。典型 consumer：
+
+- 官方 skill
+- `@midwayjs/skill-midway`
+- 基于 `packages/mcp` 的参考 knowledge server
+- 站点调试工具页
+
+## Query Contract
+
+consumer 侧必须至少支持以下查询语义：
+
+1. `resolveVersion(target)`
+   - 输入：`current`、显式 semver、`latest`
+   - 输出：`resolvedVersion`、`matchType`
+
+2. `lookupDocs({ query, version, locale })`
+   - 按主题、标题、slug、标题层级匹配文档
+
+3. `lookupApi({ symbol, packageName?, version })`
+   - 按导出名、限定名、包名查 API
+
+4. `lookupPackages({ query, version })`
+   - 按包名、关键词、分类查 Midway 包
+
+5. `lookupChangelog({ fromVersion, toVersion?, packageName? })`
+   - 返回变更条目和关联版本范围
+
+所有查询返回都必须带：
+
+- `resolvedVersion`
+- `sourceKind`
+- `sourcePath`
+- `sourceUrl`
+- `confidence` 或 `matchType`
+
+## Skill Design
+
+官方 skill 只定义 SOP，不直接复制知识正文。
+
+最小要求：
+
+1. 触发范围
+   - Midway 框架、包、装饰器、配置、生命周期、命令行工具、MCP、部署、迁移相关问题
+
+2. 默认流程
+   - 先解析版本
+   - 再查 knowledge bundle
+   - 命中不足时回退到官方文档页面或源码位置
+
+3. 输出约束
+   - 必须说明命中的 Midway 版本
+   - 必须优先引用官方来源
+   - 推断内容要显式标注是推断
+
+## Versioning Strategy
+
+- `current` 对应站点当前文档版本标签
+- 历史版本来自 `site/versions.json`
+- 查询显式版本时优先 exact match
+- 无 exact match 时可回退到“同 major 下最近的已发布快照”，并向 consumer 暴露 `fallback=true`
+
+## Freshness Strategy
+
+知识快照生成应与文档/API 构建绑定，而不是独立手工维护。
+
+最低要求：
+
+- 文档构建时生成当前版本 bundle
+- 版本化文档构建时保留历史 bundle
+- 生成产物记录 `generatedAt`
+- CI 对以下情况给出失败信号：
+  - 当前文档存在但当前 bundle 缺失
+  - 当前 API typedoc 存在但 API bundle 缺失
+  - 版本清单与 bundle 目录不一致
+
+## Decisions
+
+- Decision: 先做 bundle，再做 transport
+  - 原因：`@midwayjs/skill-midway`、MCP、skill 共享同一份数据契约，避免重复抓取和重复解析。
+
+- Decision: 以 docs + typedoc 为双主源
+  - 原因：Midway 的“怎么用”主要在 docs，“能调什么”主要在 typedoc，两者缺一不可。
+
+- Decision: `latest` 不直接指 npm registry
+  - 原因：对 agent 来说，最可信的“最新”应是当前站点发布并完成 bundle 生成的版本，而不是尚未同步文档的包版本。
+
+- Decision: skill 与数据分离
+  - 原因：skill 的职责是强制 agent 查询官方源，而不是变成另一本维护成本极高的手册。
+
+## Risks / Trade-offs
+
+- 风险：docs 与 typedoc 的版本边界不完全一致
+  - Mitigation：manifest 中显式记录每个 version 的 docs/api 可用性
+
+- 风险：历史版本文档结构差异较大，归一化复杂
+  - Mitigation：先定义最小公共字段，保留 `rawSourcePath` 作为兜底
+
+- 风险：consumer 直接依赖站点内部生成文件路径，导致后续改动成本高
+  - Mitigation：consumer 只依赖 manifest 和 bundle contract，不依赖 Docusaurus 内部目录细节
+
+## Migration Plan
+
+1. 在 `site` 构建链路中加入 knowledge bundle 生成
+2. 为当前版本与历史版本产出统一 manifest
+3. 增加官方 skill 文件
+4. 由 `@midwayjs/skill-midway` 与 MCP 等 consumer 消费该 bundle，而不是自行爬站点
+
+## Open Questions
+
+- 官方 skill 最终是保留在主仓，还是镜像发布到独立 skill 仓库？
+- bundle 是直接随站点静态文件发布，还是同步发布一个轻量 npm 数据包（首选名 `@midwayjs/skill-midway`）？
+- `lookupDocs` 是否需要在第一阶段支持全文倒排索引，还是先以标题/slug/heading 命中为主？

openspec/changes/add-midway-agent-knowledge/proposal.md

@@ -0,0 +1,59 @@
+# Change: 提供 Midway 官方 Agent Knowledge Bundle 与 Skill
+
+## Why
+当前 Midway 已经同时拥有三类对 agent 很有价值的官方信息源：
+
+- `site/docs` 与 `site/versioned_docs` 中的版本化文档
+- Docusaurus/TypeDoc 生成的 API 元数据（如 `api-typedoc.json`）
+- `CHANGELOG.md`、包清单、MCP 能力等运行时与发布信息
+
+但这些内容仍然主要面向人类页面浏览，缺少一个“可版本化、可结构化、可被 agent 直接消费”的官方知识层。结果是：
+
+1. agent 容易只基于记忆回答，无法稳定对齐 Midway 最新版本能力；
+2. MCP、skill、LLM 文档入口与潜在命令行消费者之间没有统一的数据契约；
+3. 文档更新后，即使站点已同步，agent 侧也没有官方“最新快照”可以消费。
+
+`ant-design/antd-skill` 的有效点不在单个 `SKILL.md`，而在于“skill 只负责 SOP，真实数据由结构化 provider 提供”。Midway 也需要一套同类但更适合自身仓库结构的官方方案。
+
+## What Changes
+- 新增 capability：`agent-knowledge`
+- 定义 Midway 官方 `Agent Knowledge Bundle`，从文档、TypeDoc API、版本信息、changelog 和包元数据生成结构化快照
+- 定义版本解析与回退规则，使 consumer 可以稳定查询 `current`、显式版本和历史版本
+- 定义 transport-neutral 查询契约，供未来的 `@midwayjs/skill-midway`、MCP server、站点调试页和其他 agent 工具共同消费
+- 定义 Midway 官方 skill 的最小 SOP：何时触发、先查什么、如何引用版本和来源、何时回退到站点页面
+- 定义更新与发布流程，确保文档/API 更新后知识快照同步刷新，而不是长期漂移
+
+## Design Direction
+本 change 只冻结设计，不直接开始实现。整体方向如下：
+
+1. **数据归一化优先**
+   - 不手写知识库正文；
+   - 直接复用 `site/docs`、`site/versioned_docs/*`、`api-typedoc.json`、`versions.json`、`CHANGELOG.md` 等已有官方资产。
+
+2. **传输层后置**
+   - 先统一 bundle 契约，再由 `@midwayjs/skill-midway`、MCP、静态文件或其他运行时去消费；
+   - 避免把知识格式与某个单独工具强耦合。
+
+3. **版本感知为第一原则**
+   - `current` 代表站点当前版本；
+   - 历史版本沿用 `site/versions.json`；
+   - 查询时必须返回“命中版本”与“是否回退”。
+
+4. **skill 只做行为编排**
+   - `SKILL.md` 不承载大量知识正文；
+   - 由 skill 强制 agent 在 Midway 问题上优先查询官方 knowledge provider。
+
+## Impact
+- Affected specs: `agent-knowledge`（新增）
+- Affected code（实施阶段预期）:
+  - `site/` 下文档构建与生成脚本
+  - `site/docusaurus.config.js` 相关知识输出挂钩
+  - `packages/mcp/*` 的参考接入方式或示例
+  - Midway 官方 skill 文件及其分发脚本/目录
+  - `@midwayjs/skill-midway` 包及其他 consumer 对该 bundle 的消费逻辑
+
+## Scope Boundaries
+- 本提案不要求在当前仓库里实现完整搜索引擎。
+- 本提案不要求立即实现完整命令行工具；首选官方包名为 `@midwayjs/skill-midway`，而不是新的 `cli` 包。
+- 本提案不要求改变现有 Docusaurus 页面结构或 Typedoc 页面路由。
+- 本提案不纳入社区博客、第三方教程、Issue/Discussion 等非官方内容。

openspec/changes/add-midway-agent-knowledge/specs/agent-knowledge/spec.md

@@ -0,0 +1,89 @@
+## ADDED Requirements
+
+### Requirement: Versioned Official Knowledge Snapshots
+系统 SHALL 从 Midway 官方文档与 API 资产生成可版本化的 agent knowledge snapshots。
+
+#### Scenario: 生成当前版本知识快照
+- **WHEN** 站点构建当前文档版本
+- **THEN** 系统生成对应当前版本的 knowledge snapshot
+- **AND** snapshot 记录生成时间、版本号和可用数据切片
+
+#### Scenario: 保留历史版本知识快照
+- **WHEN** 仓库存在 `site/versioned_docs` 中的历史版本文档
+- **THEN** 系统为这些历史版本生成或保留对应 knowledge snapshot
+- **AND** consumer 可按显式版本查询这些快照
+
+### Requirement: Unified Docs And API Knowledge Contract
+系统 SHALL 将文档、API 符号、包信息与 changelog 统一到同一知识契约中，而不是由 consumer 分别抓取不同源。
+
+#### Scenario: 文档页被归一化为稳定记录
+- **WHEN** 系统处理 Midway 官方文档页面
+- **THEN** 每个页面至少包含稳定 `id`、标题、版本、locale、来源路径和来源 URL
+- **AND** consumer 无需理解 Docusaurus 内部文件结构即可消费
+
+#### Scenario: API 符号被归一化为稳定记录
+- **WHEN** 系统处理 TypeDoc 生成的 API 元数据
+- **THEN** 每个 API 记录至少包含包名、符号名、符号类型、版本和来源信息
+- **AND** consumer 可按符号名或包名稳定查询
+
+#### Scenario: Changelog 与包信息进入统一知识层
+- **WHEN** 系统处理 changelog 与包元数据
+- **THEN** consumer 可通过同一知识契约查询版本变更与相关包信息
+- **AND** 不要求 consumer 额外解析 `CHANGELOG.md` 或多个 `package.json`
+
+### Requirement: Version-aware Query Resolution
+系统 SHALL 提供明确的版本解析与回退语义，避免 agent 在“当前版本”和“历史版本”之间混淆。
+
+#### Scenario: 查询显式版本命中对应快照
+- **WHEN** consumer 传入一个存在的显式 Midway 版本
+- **THEN** 系统返回该版本的知识快照结果
+- **AND** 响应包含 `resolvedVersion`
+
+#### Scenario: 查询不存在的精确版本时允许安全回退
+- **WHEN** consumer 传入一个不存在的显式版本
+- **THEN** 系统可回退到同 major 下最近的已发布快照
+- **AND** 响应必须标明发生了回退而不是伪装成 exact match
+
+#### Scenario: 查询 current 或 latest
+- **WHEN** consumer 传入 `current` 或 `latest`
+- **THEN** 系统解析到当前官方文档版本
+- **AND** 不直接以外部 registry 中的最新包版本替代文档版本
+
+### Requirement: Transport-neutral Consumer Contract
+系统 SHALL 定义不绑定特定 transport 的查询契约，以便 skill、`@midwayjs/skill-midway`、MCP 等 consumer 共用同一数据源。
+
+#### Scenario: `@midwayjs/skill-midway` 复用统一查询契约
+- **WHEN** 官方 `@midwayjs/skill-midway` 包消费 Midway knowledge
+- **THEN** 该包通过统一查询契约访问 snapshot
+- **AND** 不需要自行重新解析站点页面
+
+#### Scenario: MCP consumer 复用统一查询契约
+- **WHEN** 基于 Midway 的 MCP server 提供文档/API 查询能力
+- **THEN** 它复用同一知识契约
+- **AND** 不引入独立的第二套知识格式
+
+### Requirement: Official Agent Skill Workflow
+系统 SHALL 提供 Midway 官方 skill，用于约束 agent 在 Midway 相关任务中优先查询官方 knowledge provider。
+
+#### Scenario: 处理 Midway 技术问题时优先查官方 knowledge
+- **WHEN** agent 接到 Midway 框架、包、装饰器、配置、迁移或 MCP 相关任务
+- **THEN** 官方 skill 指导 agent 优先查询 knowledge provider
+- **AND** 不应在可查询时仅依赖记忆回答
+
+#### Scenario: 输出带版本与来源
+- **WHEN** agent 使用官方 knowledge provider 回答 Midway 问题
+- **THEN** 输出包含命中的 Midway 版本与官方来源
+- **AND** 推断内容必须与直接来源区分
+
+### Requirement: Freshness And Release Guard
+系统 SHALL 将知识快照更新纳入文档/API 发布流程，避免官方文档与 agent 知识层长期漂移。
+
+#### Scenario: 当前文档更新时同步刷新 snapshot
+- **WHEN** 当前版本文档或 API 元数据发生变化
+- **THEN** 知识快照在构建或发布流程中同步刷新
+- **AND** 新 snapshot 的生成时间可被 consumer 感知
+
+#### Scenario: 关键快照缺失时阻断发布
+- **WHEN** 当前版本存在官方 docs 或 API 资产但对应 snapshot 缺失
+- **THEN** CI 或发布流程给出失败信号
+- **AND** 不允许静默发布不完整的 knowledge bundle