Dev/michaelhu

.github/pull_request_template.md

@@ -0,0 +1,23 @@
+## Summary
+
+- [ ] 简述本次改动目标与范围
+
+## Changes
+
+- [ ] 列出核心改动点（代码/文档/配置）
+
+## Verification
+
+- [ ] 本地验证步骤已执行（请附关键命令/结果）
+
+## WS/TaskBus Contract Checklist（必填）
+
+- [ ] 本次是否涉及 WS/TaskBus（topic、publish/register、envelope、鉴权、tenant/trace）？
+- [ ] 若涉及，是否同步更新主契约：`specs/004-eventbus-message-fabric/spec.md`
+- [ ] 若涉及 WS 传输，是否同步更新：`specs/023-websocket-notify/spec.md` 与 `specs/023-websocket-notify/contracts/http-openapi.yaml`
+- [ ] 是否运行一致性检查：`bash scripts/specs/check_ws_taskbus_contracts.sh`
+
+## Risks
+
+- [ ] 已评估兼容性/回滚影响
+

.github/workflows/web-admin-api-response-shape.yml

@@ -0,0 +1,43 @@
+name: Web Admin API Response Shape
+
+on:
+  pull_request:
+    paths:
+      - 'web-admin/app/**'
+      - 'web-admin/scripts/check-api-response-shape.mjs'
+      - 'web-admin/package.json'
+      - '.github/workflows/web-admin-api-response-shape.yml'
+  push:
+    branches:
+      - main
+    paths:
+      - 'web-admin/app/**'
+      - 'web-admin/scripts/check-api-response-shape.mjs'
+      - 'web-admin/package.json'
+      - '.github/workflows/web-admin-api-response-shape.yml'
+
+jobs:
+  response-shape-check:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: web-admin
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: web-admin/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Check API response shape
+        run: npm run check:api-response-shape
+
+      - name: Build web-admin
+        run: npm run build

.github/workflows/ws-taskbus-doc-consistency.yml

@@ -0,0 +1,35 @@
+name: WS TaskBus Doc Consistency
+
+on:
+  pull_request:
+    paths:
+      - 'specs/004-eventbus-message-fabric/**'
+      - 'specs/023-websocket-notify/**'
+      - 'scripts/specs/check_ws_taskbus_contracts.sh'
+      - '.github/workflows/ws-taskbus-doc-consistency.yml'
+  push:
+    branches:
+      - main
+    paths:
+      - 'specs/004-eventbus-message-fabric/**'
+      - 'specs/023-websocket-notify/**'
+      - 'scripts/specs/check_ws_taskbus_contracts.sh'
+      - '.github/workflows/ws-taskbus-doc-consistency.yml'
+
+jobs:
+  doc-consistency:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install ripgrep
+        run: |
+          if ! command -v rg >/dev/null 2>&1; then
+            sudo apt-get update
+            sudo apt-get install -y ripgrep
+          fi
+
+      - name: Run WS/TaskBus contract consistency check
+        run: bash scripts/specs/check_ws_taskbus_contracts.sh
+

.gitignore

@@ -54,6 +54,7 @@ backend/etc/config.yaml
 # PowerX plugin runtime（整目录忽略）
 backend/plugins/
 backend/.gopath
+backend/.gotmp
 
 # Ignore compiled binary files and specific app directories
 # Binary file 'app' (compiled executable)
@@ -87,3 +88,5 @@ storage/
 .claude
 
 tmp
+backend/reports/
+reports/

.specify/memory/api-naming.md

@@ -0,0 +1,132 @@
+# PowerX API 命名与访问规范（全局）
+
+> 本文件定义 PowerX 平台所有 HTTP API 的路径前缀、用途边界、版本策略、鉴权与命名风格。适用于 CoreX 底座、插件框架、插件业务服务。
+
+## 1. 路径前缀与用途边界
+
+### 1.1 公共访问域（对外/客户端）
+
+- **/api/v1/**：对外开放的稳定 API（OpenAPI 可暴露）
+  - 典型对象：租户端、开放平台、第三方客户端
+  - 版本语义：语义化版本 v1 / v2
+
+- **/api/**：兼容入口（老路径或内部自用），可作为路由代理或重定向到 /api/v1
+  - 若 /api/v1 存在同名路径，优先迁移到 /api/v1
+
+> **注意：APIPrefix 可配置**（`cfg.Server.APIPrefix`）。本文档使用 `/api` 作为默认示例，实际运行路径为 `<APIPrefix>/...`，常见取值：`/api` 或 `/api/v1`。
+
+### 1.2 管理/后台域（管理端/控制台）
+
+- **/api/v1/admin/**：管理端 API（带管理权限）
+  - 典型对象：管理控制台、运营/内部管理系统
+  - 必须带授权 token
+
+### 1.3 内部/宿主域（仅内部使用）
+
+- **<APIPrefix>/internal/**：宿主/插件内部调用入口（不对公网开放）
+  - 典型对象：PowerXPlugin Framework、CLI、宿主内部服务
+  - **必须最小化暴露，不写入公开 OpenAPI**
+  - 允许与 /api/v1 同时存在，但用途必须明确区分
+
+> 说明：已有历史文档/实现中使用 `/internal/*` 或 `/api/internal/*`，统一向 `/api/internal/*` 对齐。
+
+---
+
+## 2. 版本策略
+
+- 稳定对外接口必须挂在 `/api/v1`，有破坏性变更时升级 `/api/v2`
+- `/api/internal` 不承诺稳定版本，但变更需记录在变更日志
+- `/api` 仅作为兼容入口或内部路由代理，不建议新功能落地
+
+---
+
+## 3. 鉴权与租户透传
+
+- **所有 `/api/v1/admin` 与 `/api/internal` 必须鉴权**
+- 租户信息必须通过 token（JWT claims）或 `tenant_uuid` 字段解析，不接受遗留租户头注入。
+- 内部接口也需 tenant 校验，禁止跨租户调用
+
+---
+
+## 4. 命名风格
+
+### 4.1 资源命名
+
+- REST 资源采用名词复数：
+  - `/api/v1/admin/agents`
+  - `/api/v1/admin/knowledge-spaces`
+
+### 4.1.1 插件相关命名
+
+- 管理端插件资源：`/api/v1/admin/plugins/*`
+  - 示例：`/api/v1/admin/plugins`、`/api/v1/admin/plugins/:id`
+- 宿主内部插件资源：`/api/internal/plugins/*`
+  - 示例：`/api/internal/plugins/local/reload`、`/api/internal/plugins/environments/check`
+- 插件发布/治理内部分发：`/api/internal/version/*`、`/api/internal/notify/*`
+- 宿主模式插件前端入口（反代）：`/_p/<pluginId>/admin/<path>`
+  - 示例：`/_p/com.powerx.helloworld/admin/intro`
+- 宿主模式插件后端 API（反代）：`/_p/<pluginId>/api/<path>`
+  - 示例：`/_p/com.powerx.helloworld/api/healthz`
+
+### 4.2 行为/动作
+
+- 动作用 **子路径** 或 **操作端点**：
+  - `/api/v1/admin/agents/:id/activate`
+  - `<APIPrefix>/internal/ws-bus/publish`
+
+### 4.3 异步任务
+
+- 提交任务：`POST /.../tasks`
+- 查询任务：`GET /.../tasks/:taskId`
+
+---
+
+## 5. OpenAPI / 合同要求
+
+- `/api/v1` 与 `/api/v1/admin` 必须有 OpenAPI 文档
+- `/api/internal` 默认不在公开 OpenAPI 中暴露
+- 任何新增对外接口必须更新 specs/contracts
+
+---
+
+## 6. 日志 / 追踪 / 审计
+
+- 对外与管理接口必须具备 trace_id
+- `/api/internal` 必须记录 tenant/topic/trace_id（若涉及事件）
+
+---
+
+## 7. 示例
+
+### 7.1 对外 API
+
+```
+GET /api/v1/knowledge-spaces
+```
+
+### 7.2 管理端 API
+
+```
+POST /api/v1/admin/agents/test/connection
+```
+
+### 7.3 内部 API
+
+```
+POST <APIPrefix>/internal/ws-bus/publish
+```
+
+### 7.4 插件相关 API
+
+```
+GET /api/v1/admin/plugins
+POST /api/internal/plugins/local/reload
+GET /_p/<pluginId>/admin/
+GET /_p/<pluginId>/api/healthz
+```
+
+---
+
+## 8. 变更记录
+
+- 2026-02-03：首次定义 `/api/internal` 作为宿主/插件内部 API 前缀

.specify/memory/constitution.md

@@ -6,12 +6,14 @@ manifest: .specify/memory/manifest.yaml
 use:
   - "@dev-crud-http"
   - "@dev-crud-grpc"
+  - "@api-naming"
 
 # ③ 指南文件（用于 /plan 语义扩展）
 include:
   - dev_crud_http_guides.md
   - dev_crud_grpc_guides.md
   - dev_sts_guides.md
+  - api-naming.md
 
 # ④ Ruleset Paths（显式暴露以便 Runner 能读取）
 rulesets:
@@ -63,6 +65,7 @@ If a runner does not natively support `manifest.yaml`, it must treat this sectio
 > 领域实体说明，因为gorm即定义了model，也可以作为领域的实体使用，不需要反复定义，所以基本上都是在pkg/corex/db/persistence/model/...
 
 - **工具复用（新增）**：凡属通用的转换/JSON/随机/字符串处理等辅助函数，必须集中在 `backend/pkg/utils` 对应模块（如 `xform.go`、`json.go`、`xfind.go` 等），严禁在业务目录重复定义；如遇缺失，应先扩展 utils 模块，再在业务代码中引用。
+- **配置文件保护（新增）**：未经用户明确允许，不得修改 `backend/etc/config.yaml`（包括创建、覆盖或清空）。
 - **命名规范（新增）**：CoreX 域目录名称一律使用 `snake_case`，以 `capability_registry`、`media_storage` 为例；禁止拼接式命名如 `capabilityregistry`，确保与 Go 包名区分且在跨语言环境保持一致。
 - **Go 包别名/调用命名**：引用 `capability_registry` 等多词包时，import alias、局部变量与导出符号统一使用小驼峰（如 `capabilityRegistry`、`capRegPolicy`），避免 `capregpolicy`、`capabilityregistry` 这类连续小写写法。示例：`capabilityRegistry "github.com/ArtisanCloud/PowerX/internal/service/capability_registry/registry"`，通过 `capabilityRegistry.Migrate()`、`capRegPolicy.Register()` 等方式调用以保持可读性。
 - **数据访问角色划分（新增）**：`repository` 负责具体持久化实现（GORM/SQL/Redis/MinIO 等），需落在 `pkg/corex/db/persistence/repository/**` 并处理事务/SQL；`interface` 用于 service 层声明所需的数据契约，便于替换实现、注入缓存/内存替身与编写单元测试。Service/handler/任务脚本必须依赖这些接口而非具体 repository，实现切换仅在依赖注入层完成，且 repository 内禁止承载业务逻辑。
@@ -247,6 +250,7 @@ Any plan missing the above gates is **invalid** and fails constitutional complia
 - `pkg/event_bus` 定位为**基础设施层**的发布/订阅抽象（`Publish`、`Subscribe`、`Close`），负责把事件从发布方送到订阅方，不包含主题治理、ACL、重试、死信或回放等业务语义。
 - `internal/service/event_fabric/*` 是**领域编排层**，需在 CoreX 事件骨干中完成 Topic 目录、租户 ACL、可靠投递、DLQ、回放、审计等用例，并可组合底层 `pkg/event_bus` 等设施。
 - 任何计划/实现不得混淆两者职责：领域服务依赖或扩展基础设施，但禁止在基础设施层堆叠领域逻辑，也不得绕过领域服务直接宣称满足事件骨干需求。
+- **实时状态更新强制规范**：Web 管理端涉及任务状态、回放状态、队列执行进度等“实时数据”时，必须走 WebSocket/SSE 推送链路；禁止在页面实现定时轮询（polling）作为主方案。若推送链路不可用，只允许短时人工诊断接口，不得固化为前端常驻轮询逻辑。
 
 ---
 

.specify/memory/dev_crud_grpc_guides.md

@@ -66,7 +66,7 @@ internal/transport/grpc/
 
 ### 5.1 绑定/校验
 
-* **tenant 提取**：优先读 `RequestContext.tenant_id`，其次从 Metadata 头 `x-powerx-tenant-id|tenant-id|x-tenant-id` 兜底。
+* **tenant 提取**：优先读 `RequestContext.tenant_id`，其次仅从 Metadata `tenant-id` 兜底（不接受任何 `x-powerx-*` 遗留租户头）。
   你的 `tenantIDFrom()` 已经实现这一落地逻辑。
 * **分页映射**：`PageRequest(offset,page_size)` → `(page,size)` 的换算统一用工具函数（如 `pageFrom()`）。
 * **错误回包**：Meta 中返回 `code/message/request_id`，与你的 `okMeta/badMeta` 一致（见 `member_handler.go`/`team_handler.go` 调用）。
@@ -140,4 +140,3 @@ internal/transport/grpc/
 * [ ] **与 HTTP 等价**：同一用例在 HTTP 与 gRPC 的语义、错误、分页完全可对照。
 
 ---
-

.specify/memory/manifest.yaml

@@ -40,9 +40,14 @@ aliases:
       - dev_crud_http_guides.md
       - dev_crud_grpc_guides.md
       - dev_sts_guides.md
+      - api-naming.md
     rulesets:
       - rulesets/crud_http.yaml
       - rulesets/crud_grpc.yaml
       - rulesets/sts.yaml
       # 以及两边共用/各自特有的明细 ruleset
 
+  # API 命名规范（单独引用也可）
+  api-naming:
+    include:
+      - api-naming.md

.specify/memory/rulesets/crud/frontend/nuxt_components.yaml

@@ -38,6 +38,9 @@ nuxt_ui:
     preferUModal: true
     paddingClass: "p-4 sm:p-5"
     width: "max-w-3xl w-full"
+    notes:
+      - 如需更宽的编辑表单，可覆盖 `ui.content`（例如 `'max-w-6xl w-[90vw] mx-auto'`）而不是直接设置 inline 样式，保持组件一致性。
+      - 需要弹层交互的表单/内容必须放在 UModal 的 `#body` 内，由 `v-model:open` 控制显隐；不要把表单直接渲染在页面上再“看起来像弹层”。
     close:
       useCloseProp: true
       preventClose: true

AGENTS.md

@@ -5,6 +5,8 @@ Auto-generated from all feature plans. Last updated: 2025-11-05
 ## Active Technologies
 - Go 1.24（backend 单体，Buf toolchain） + Gin HTTP 栈、google.golang.org/grpc、Buf、GORM、Redis、PostgreSQL、EventBus、OpenTelemetry、px-plugin CLI (007-integration-gateway-and-mcp)
 - PostgreSQL（CapabilityRecord, CapabilitySyncJob, InvocationTrace）、Redis（Capability cache、ToolStore、RateLimit、SelectorPolicySnapshot）、MinIO/S3（插件 workflow/composite 资产引用，仅存 URI） (007-integration-gateway-and-mcp)
+- Go 1.24（backend），Node 20 + Nuxt 4（web-admin） + Gin HTTP 栈、gorilla/websocket、Pinia、Nuxt UI (012-websocket-docs-plan)
+- PostgreSQL（ai_model_profiles/knowledge_*），Redis（现有队列/缓存） (012-websocket-docs-plan)
 
 - Go 1.24（backend），Node 20（Web Admin 热更新面板），Go 1.21（px-plugin CLI） + Gin HTTP 栈、google.golang.org/grpc、Buf toolchain、GORM + PostgreSQL、Redis（队列与 Feature Flag）、MinIO/S3 SDK（离线包存储）、OpenTelemetry + Prometheus Exporter、PowerX CLI (`powerx`, `px-plugin`) (001-install-plugin-pxp)
 - Go 1.24 (backend services, CLIs), Node 20 (validation scripts), Go 1.21 (px-plugin CLI) + Gin HTTP stack, google.golang.org/grpc, Buf toolchain, GORM + PostgreSQL, Redis, MinIO/S3 SDK, OpenTelemetry + Prometheus exporters (010-agent-model-setting)
@@ -36,10 +38,10 @@ tests/
 Go 1.24（backend），Node 20（Web Admin 热更新面板），Go 1.21（px-plugin CLI）: Follow standard conventions
 
 ## Recent Changes
+- 012-websocket-docs-plan: Added Go 1.24（backend），Node 20 + Nuxt 4（web-admin） + Gin HTTP 栈、gorilla/websocket、Pinia、Nuxt UI
 - 007-integration-gateway-and-mcp: Added Go 1.24（backend 单体，Buf toolchain） + Gin HTTP 栈、google.golang.org/grpc、Buf、GORM、Redis、PostgreSQL、EventBus、OpenTelemetry、px-plugin CLI
 - 007-integration-gateway-and-mcp: Added [if applicable, e.g., PostgreSQL, CoreData, files or N/A]
 
-- 011-docs-use-cases: Added Go 1.24 (backend services, CLIs); Node 20 + Nuxt 4 (Vue 3 Web Admin) + Gin HTTP stack, google.golang.org/grpc (Buf toolchain), GORM, Redis, PostgreSQL, MinIO/S3 SDK, OpenTelemetry, PowerX CLI, Nuxt 4, Vue 3, Pinia, Nuxt UI, VueUse, Playwright, Vites
 
 <!-- MANUAL ADDITIONS START -->
 Always respond in Chinese-simplified

README.md

@@ -112,6 +112,7 @@ PowerX 内置四类前端壳，共享 **统一契约**，SDK 自动生成，支
 - **🛠️ [运维手册](https://powerx.artisan-cloud.com/operations)** - 监控、备份、升级
 - **📘 [Knowledge Space Quickstart](specs/011-knowledge-space/quickstart.md)** - 端到端创建/入库/融合/反馈示例
 - **🧯 [Knowledge Space Runbook](docs/guides/knowledge_space/runbook.md)** - 入库/融合/反馈故障处理与脚本
+- **🧭 [Knowledge Space UI Guide](docs/guides/knowledge_space/ui_guide.md)** - 管理台界面操作（含“场景→策略包/Corpus Check/OCR 提示/Playground”）
 - **📊 [Perf & Resiliency Validation](docs/guides/knowledge_space/perf_validation.md)** - 压测/降级/反馈风暴验证
 - **✅ [Smoke Checklist](docs/guides/knowledge_space/smoke_checklist.md)** - 发布前的冒烟检查表