openxiangda 2.0.0-alpha.99 → 2.0.0

package/documentation/reference/mcp.md

@@ -0,0 +1,649 @@
+# MCP 配置与工具参考
+
+> 工具说明和输入参数从当前 MCP 注册表生成。
+
+## 连接项目
+
+MCP 使用项目锁定的根包；在客户端配置下列 stdio 启动参数，把路径换成真实工作区的绝对路径：
+
+```json
+{
+  "command": "pnpm",
+  "args": ["--dir", "/绝对路径/应用", "exec", "openxiangda", "--mcp-stdio", "--cwd", "/绝对路径/应用"]
+}
+```
+
+客户端负责启动进程。登录、创建应用和长期运行的 dev 服务使用 [CLI](./cli.md)。依赖升级后重启 MCP 进程。首先读取 workspace_context，再按任务读取 docs_read 和相关契约。MCP 不自动部署；在用户已授权范围内执行修改，无需重复确认。
+
+## 读取资源
+
+- `openxiangda://workspace/context`
+- `openxiangda://workspace/contracts`
+- `openxiangda://workspace/appspec`
+- `openxiangda://platform/capabilities`
+- `openxiangda://deployments/latest`
+- `openxiangda://environments`
+- `openxiangda://docs/index`
+
+资料目录返回当前版本、摘要、主题 URI 和章节 ID；读取 `openxiangda://docs/{topic}` 得到中文 Markdown 正文。只需一个章节时使用 docs_read 的 section。资料只来自同版本根包的固定目录，不接受任意文件路径或网络 URL。
+
+## 结果与失败处理
+
+工具返回相同内容的 structuredContent 与文本结果，包含 ok、operation、data 和适用的 diagnostics/nextActions。业务失败设置 isError=true；按错误码、定位和平台 recovery 决定下一步。工具协议错误同样停止当前操作。check_app 会生成文件并运行检查、测试、构建；失败后未执行的阶段标记 skipped。deploy_app 已包含完整检查，生产晋级必须传入成功的测试 DeploymentRun ID，不重新构建。详见 [校验](../testing.md)与[部署](../delivery.md)。
+
+## authorization_status
+
+核验平台授权。只读核验明确指定站点的当前授权；不依赖工作区，不启动登录、刷新凭据或修改绑定。authorized 不代表应用管理权限。
+
+- 只读：是
+- 可替换文件或改变远端状态：否
+- 幂等：否
+
+输入参数：
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "baseUrl": {
+      "type": "string",
+      "minLength": 1,
+      "description": "明确指定目标平台地址"
+    }
+  },
+  "required": [
+    "baseUrl"
+  ],
+  "additionalProperties": false
+}
+```
+
+## workspace_context
+
+查看工作区。首先读取当前项目、工具链版本和绑定，不运行构建或创建远端对象。
+
+- 只读：是
+- 可替换文件或改变远端状态：否
+- 幂等：否
+
+输入参数：
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {}
+}
+```
+
+## contract_describe
+
+查看应用契约。默认返回有界索引；用 selector 读取模型、流程、能力，或 navigation/permissions。菜单建议只复制一次，运行时不自动应用。
+
+- 只读：是
+- 可替换文件或改变远端状态：否
+- 幂等：否
+
+输入参数：
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "selector": {
+      "description": "index、navigation、permissions、all 或索引给出的选择器",
+      "type": "string",
+      "maxLength": 200
+    },
+    "offset": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991
+    },
+    "limit": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 100
+    }
+  },
+  "additionalProperties": false
+}
+```
+
+## appspec_context
+
+读取需求与设计。读取设计索引、稳定 ID 正文与引用闭包、开工和测试发布缺口；设计基线确认后制定实施计划，生产晋级核对原测试版本实际验收。
+
+- 只读：是
+- 可替换文件或改变远端状态：否
+- 幂等：否
+
+输入参数：
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "selector": {
+      "description": "能力、变更、ADR 或 DES-* 设计的稳定 ID",
+      "type": "string",
+      "minLength": 1
+    },
+    "historyOffset": {
+      "default": 0,
+      "description": "历史索引偏移，每页 50 条",
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991
+    }
+  }
+}
+```
+
+## appspec_verify
+
+核对业务验收报告。读取成功测试运行与 Git 中的真实验收报告，核对版本绑定、场景结果和性能证据；不自动编造或执行验收。
+
+- 只读：是
+- 可替换文件或改变远端状态：否
+- 幂等：否
+
+输入参数：
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "deploymentId": {
+      "type": "string",
+      "minLength": 1
+    },
+    "evidencePath": {
+      "description": "appspec/verification/*.json；省略时按运行 ID 读取",
+      "type": "string"
+    }
+  },
+  "required": [
+    "deploymentId"
+  ]
+}
+```
+
+## docs_read
+
+读取中文使用资料。不传 topic 返回当前版本的主题和章节目录；传 topic/section 读取对应正文。
+
+- 只读：是
+- 可替换文件或改变远端状态：否
+- 幂等：否
+
+输入参数：
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "topic": {
+      "description": "主题目录中的 ID",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 80
+    },
+    "section": {
+      "description": "主题章节目录中的 ID",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 200
+    }
+  },
+  "additionalProperties": false
+}
+```
+
+## administration_context
+
+查看应用管理入口。读取当前用户可用的管理能力和入口；不修改角色或成员。
+
+- 只读：是
+- 可替换文件或改变远端状态：否
+- 幂等：否
+
+输入参数：
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "environment": {
+      "default": "test",
+      "description": "目标环境；默认 test，production 必须明确选择",
+      "type": "string",
+      "enum": [
+        "test",
+        "production"
+      ]
+    }
+  }
+}
+```
+
+## workflow_node_configurations
+
+查看流程有效参数。修改已部署流程前，读取管理员维护的节点配置。已有任务和后续节点进入使用各自适用版本。
+
+- 只读：是
+- 可替换文件或改变远端状态：否
+- 幂等：否
+
+输入参数：
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "environment": {
+      "default": "test",
+      "description": "目标环境；默认 test，production 必须明确选择",
+      "type": "string",
+      "enum": [
+        "test",
+        "production"
+      ]
+    },
+    "workflowCode": {
+      "type": "string",
+      "minLength": 1,
+      "description": "流程声明中的 code"
+    }
+  },
+  "required": [
+    "workflowCode"
+  ]
+}
+```
+
+## check_app
+
+检查完整应用。先在本地完成完整配置校验，默认核对平台同源规则与只读环境条件，再生成、静态检查、测试和构建。local 仅用于本地或 CI 验证，不证明目标环境可部署；正式 deploy 始终预检平台。会写本地文件，前置失败即停止。
+
+- 只读：否
+- 可替换文件或改变远端状态：是
+- 幂等：否
+
+输入参数：
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "environment": {
+      "default": "test",
+      "description": "目标环境；默认 test，production 必须明确选择",
+      "type": "string",
+      "enum": [
+        "test",
+        "production"
+      ]
+    },
+    "local": {
+      "default": false,
+      "description": "仅本地完整检查；结果 validationScope=local，不核对现场条件",
+      "type": "boolean"
+    }
+  }
+}
+```
+
+## deployment_plan
+
+预览应用发布。只读预览测试部署的运行配额，或指定测试版本的生产晋级；返回容量与缺口，不构建、上传或提交运行。
+
+- 只读：是
+- 可替换文件或改变远端状态：否
+- 幂等：否
+
+输入参数：
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "environment": {
+      "default": "test",
+      "description": "目标环境；默认 test，production 必须明确选择",
+      "type": "string",
+      "enum": [
+        "test",
+        "production"
+      ]
+    },
+    "from": {
+      "description": "production 必填：成功测试 DeploymentRun ID；test 不接受",
+      "type": "string",
+      "minLength": 1
+    },
+    "deploymentStrategy": {
+      "description": "仅 TEST；显式 maintenance-replace 允许停机替换并由平台处理失败恢复，默认 rolling",
+      "type": "string",
+      "enum": [
+        "rolling",
+        "maintenance-replace"
+      ]
+    },
+    "environmentId": {
+      "description": "测试环境 ID，通常由平台绑定确定",
+      "type": "string"
+    },
+    "idempotencyKey": {
+      "description": "测试部署幂等键，省略时由包摘要派生",
+      "type": "string"
+    },
+    "wait": {
+      "default": true,
+      "description": "默认跟踪平台运行至完成，最多 15 分钟；false 只提交，随后必须查询状态",
+      "type": "boolean"
+    }
+  },
+  "additionalProperties": false
+}
+```
+
+## environment_status
+
+查看环境状态。读取已配置环境、运行状态与当前不可变版本。
+
+- 只读：是
+- 可替换文件或改变远端状态：否
+- 幂等：否
+
+输入参数：
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {}
+}
+```
+
+## start_environment
+
+启动应用环境。在用户已授权范围内，从当前不可变版本恢复运行。
+
+- 只读：否
+- 可替换文件或改变远端状态：是
+- 幂等：是
+
+输入参数：
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "environment": {
+      "default": "test",
+      "description": "目标环境；默认 test，production 必须明确选择",
+      "type": "string",
+      "enum": [
+        "test",
+        "production"
+      ]
+    },
+    "idempotencyKey": {
+      "description": "相同操作重试时保持不变",
+      "type": "string",
+      "minLength": 1
+    }
+  },
+  "additionalProperties": false
+}
+```
+
+## stop_environment
+
+暂停应用环境。在用户已授权范围内停止运行，保留数据和配置。
+
+- 只读：否
+- 可替换文件或改变远端状态：是
+- 幂等：是
+
+输入参数：
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "environment": {
+      "default": "test",
+      "description": "目标环境；默认 test，production 必须明确选择",
+      "type": "string",
+      "enum": [
+        "test",
+        "production"
+      ]
+    },
+    "idempotencyKey": {
+      "description": "相同操作重试时保持不变",
+      "type": "string",
+      "minLength": 1
+    }
+  },
+  "additionalProperties": false
+}
+```
+
+## deploy_app
+
+部署或晋级应用。test 包含检查、按需后端镜像构建、密封和提交；production 必须用 from 复用成功测试版本。已有明确授权无需再次确认。默认持续报告进度并等待平台部署完成，真实业务验收另行执行。观察中断后继续查询原运行。
+
+- 只读：否
+- 可替换文件或改变远端状态：是
+- 幂等：是
+
+输入参数：
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "environment": {
+      "default": "test",
+      "description": "目标环境；默认 test，production 必须明确选择",
+      "type": "string",
+      "enum": [
+        "test",
+        "production"
+      ]
+    },
+    "from": {
+      "description": "production 必填：成功测试 DeploymentRun ID；test 不接受",
+      "type": "string",
+      "minLength": 1
+    },
+    "deploymentStrategy": {
+      "description": "仅 TEST；显式 maintenance-replace 允许停机替换并由平台处理失败恢复，默认 rolling",
+      "type": "string",
+      "enum": [
+        "rolling",
+        "maintenance-replace"
+      ]
+    },
+    "environmentId": {
+      "description": "测试环境 ID，通常由平台绑定确定",
+      "type": "string"
+    },
+    "idempotencyKey": {
+      "description": "测试部署幂等键，省略时由包摘要派生",
+      "type": "string"
+    },
+    "wait": {
+      "default": true,
+      "description": "默认跟踪平台运行至完成，最多 15 分钟；false 只提交，随后必须查询状态",
+      "type": "boolean"
+    }
+  },
+  "additionalProperties": false
+}
+```
+
+## deployment_status
+
+查询部署状态。查询指定或最近部署，平台状态和恢复决定是权威；watch 跟踪原运行，不重新构建或部署。
+
+- 只读：是
+- 可替换文件或改变远端状态：否
+- 幂等：否
+
+输入参数：
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "deploymentId": {
+      "description": "省略时查询最近部署",
+      "type": "string",
+      "minLength": 1
+    },
+    "watch": {
+      "default": false,
+      "description": "持续跟踪原运行至结束，最多 15 分钟",
+      "type": "boolean"
+    }
+  }
+}
+```
+
+## deployment_logs
+
+读取部署日志。读取检查点、首个和最近失败、候选状态与恢复下一步。
+
+- 只读：是
+- 可替换文件或改变远端状态：否
+- 幂等：否
+
+输入参数：
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "deploymentId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "平台返回的 DeploymentRun ID"
+    }
+  },
+  "required": [
+    "deploymentId"
+  ],
+  "additionalProperties": false
+}
+```
+
+## cancel_deployment
+
+取消未激活部署。仅在用户授权且平台 recovery.cancelAllowed 为真时取消；激活后的运行不能取消。
+
+- 只读：否
+- 可替换文件或改变远端状态：是
+- 幂等：是
+
+输入参数：
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "deploymentId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "平台返回的 DeploymentRun ID"
+    }
+  },
+  "required": [
+    "deploymentId"
+  ],
+  "additionalProperties": false
+}
+```
+
+## retry_deployment
+
+重试可恢复部署。在用户授权范围内按平台 recovery.nextCommand 重试原运行；不创建新的候选绕过失败。
+
+- 只读：否
+- 可替换文件或改变远端状态：是
+- 幂等：是
+
+输入参数：
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "deploymentId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "平台返回的 DeploymentRun ID"
+    }
+  },
+  "required": [
+    "deploymentId"
+  ],
+  "additionalProperties": false
+}
+```
+
+## rollback_app
+
+回滚应用版本。在用户授权范围内回滚到指定历史 AppVersion；版本回滚不承诺撤销业务数据写入。
+
+- 只读：否
+- 可替换文件或改变远端状态：是
+- 幂等：是
+
+输入参数：
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "environment": {
+      "default": "test",
+      "description": "目标环境；默认 test，production 必须明确选择",
+      "type": "string",
+      "enum": [
+        "test",
+        "production"
+      ]
+    },
+    "appVersionId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "已知历史 AppVersion ID"
+    }
+  },
+  "required": [
+    "appVersionId"
+  ],
+  "additionalProperties": false
+}
+```

package/documentation/testing.md

@@ -0,0 +1,63 @@
+# 检查与真实业务验收
+
+## 统一检查 {#check}
+
+```bash
+pnpm openxiangda check --json
+```
+
+CI、离线开发或尚未发布的候选包使用 `pnpm openxiangda check --local --json`，MCP 对应 `check_app.local=true`。它仍执行完整纯规则、生成、静态检查、测试与构建，但不请求平台；结果明确为 `validationScope: local`，不能证明现场权限、密钥和模型兼容。默认 check 仍预检目标，正式 deploy 始终执行现场预检，不提供跳过参数。
+
+默认目标为测试环境。CLI 与 MCP `check_app` 使用同一执行器：先在本地完成配置和完整契约校验，再核对目标平台的校验实现与只读环境条件，随后生成文件、执行静态检查、测试和构建。明确检查生产目标时指定 `--environment production`。
+
+结果中的 AppSpec/lifecycle 单独列出需求与设计缺口；普通 check 可以继续验证尚未完成的实现。正式测试发布前核对总纲、关联变更、权限、性能预算和 AC 计划，测试部署之后再执行真实角色验收。生产晋级按 [AppSpec 报告](./appspec.md)核对指定测试版本的实际结果。
+
+本地与平台使用同一份纯校验规则，并核对实现摘要和配置投影摘要。必需登录提供方、目标环境的密钥可用性、已有模型的物理字段约束和应用管理权限会在构建前检查；预检不读取密钥明文、不创建物理表、不修改环境。现场变化仍由平台在真正执行时复核。
+
+检查会写本地生成结果并按需初始化后端，不是只读操作。前置阶段失败后，下游阶段标为 skipped，不继续构建或上传。保留错误码、pointer、details 和下一步，修正原因后重试。
+
+源码、锁文件、依赖安装状态、工具链、构建环境和输出摘要均未变化时，检查自动复用已通过的 check/test/build，并在阶段结果标记 `reused: true`。目标平台的权限、密钥和模型条件每次重新预检。检查期间输入发生变化会停止并要求重新检查。缓存只保存摘要；缺少锁文件、外部本地依赖、符号链接、文件过多或无法核对时执行完整检查。手工修改 node_modules 不属于受支持的依赖管理方式，应修改依赖声明并重新安装。
+
+成功检查返回 `sealedArtifact.state: check-did-not-seal`、`sealed: false`、`usableForDeploy: false`。旧 AppPackage 不是当前检查结果。要发布测试环境可直接运行 deploy，它已包含完整检查；不要连续重复执行 check、test 和 build。
+
+## 按变化范围验收 {#acceptance}
+
+应用测试归当前项目维护。模板不限制页面数量、源文件数、总行数、业务类名或登录布局；初始模板与通用组件的模拟响应回归由工具链发行门禁维护。类型、声明、构建制品和实际运行性能仍需按各自规则验证，源码行数不能替代性能测量。
+
+Web 默认保留开发服务回环访问检查。按需 Nest 使用 `tsx --test` 发现项目中的业务测试；没有用例时只有零项测试，不能当成业务已验收。浏览器目录 `apps/web/e2e/` 起初只有编写说明，添加本应用的 `*.spec.ts` 后运行 `pnpm test:e2e`；真实角色验收绑定 AppSpec 和指定测试版本。
+
+修改资源时验证声明、PC/移动字段语义及受影响的新增、详情、修改、删除、筛选、导出和版本冲突。用允许角色验证成功，用禁止角色验证页面、操作、行和字段边界；存储值及审计应符合声明。平台内部的数据库和性能回归由平台维护者负责，应用不重复搭建平台数据库测试。
+
+只改文案时验证受影响页面。复杂事务、并发和值转换使用聚焦测试。浏览器验收实际操作并检查错误，不能用模拟响应或空页面加载代替真实角色验收。
+
+匿名访问另验证续填、上传、校验、幂等提交、own.list/own.read；另一浏览器应无法获取前一浏览器的记录。工作流按已启用功能检查发起、处理、历史详情和消息跳转，不为未启用通道增加测试负担。
+
+## 可选临时身份 {#temporary-identities}
+
+需要平台协助创建真实测试身份时，使用短期本地计划：
+
+```json
+{
+  "schemaVersion": "openxiangda.preproduction-acceptance-plan/v2",
+  "environmentKey": "preproduction",
+  "expiresInMinutes": 240,
+  "actors": [
+    { "key": "allowed", "roleCodes": ["resource_admin"] },
+    { "key": "denied", "roleCodes": ["resource_viewer"] }
+  ]
+}
+```
+
+```bash
+pnpm openxiangda accept --plan .openxiangda/acceptance-plan.json --json
+```
+
+示例角色需替换为应用实际角色。计划和返回的一次性登录链接不提交仓库。accept 不自动部署，也不是 check/deploy 的必填步骤；未运行应明确注明。
+
+## 记录结果 {#evidence}
+
+记录源码/包版本、AppVersion、环境、角色、预期及实际结果、必要请求标识。区分本地检查、分发安装、部署激活与业务验收。某项未执行时说明原因，不将其写成通过。
+
+## 并发执行
+
+同一工作区的公共 check 和测试 deploy 共享本地互斥锁，前一个命令结束后才能启动下一个。出现 WORKSPACE_OPERATION_BUSY 时等待当前进程完成；异常退出时先确认锁中进程已经退出，再移除提示中的锁文件。锁只保护工具执行，不阻止编辑器修改源码；检查和部署期间应暂停其他写入。平台部署状态仍以 status/logs 为准。