openxiangda 2.0.0-alpha.98 → 2.0.0

package/skills/openxiangda-v2/references/interaction-patterns.md

@@ -0,0 +1,56 @@
+# 页面交互模式与体验评审
+
+按实际角色和任务选择下面的标准起点，并在 AppSpec 页面设计中记录适用范围、差异和验收。模式是设计建议，不是额外运行库；控件、导航、权限和数据继续消费[平台前端](frontend.md)、[字段组件](field-components.md)和[数据权限](data-authz.md)。
+
+## 标准管理页面 {#admin}
+
+适用于管理员维护独立业务对象。显式选择 CRUD 视图，沿用 Field Kit、Ant Design 与组件默认外观。页面优先呈现标题、主要新建入口、常用筛选、列表与行操作；复杂筛选按需展开。列按办理任务选择，记录默认排序、分页上限、空值/长文显示与操作条件。辅助模型无需独立导航。
+
+列表进入详情再返回时明确关键词、筛选、页码、选择范围与位置是否保留；批量操作说明当前页/已选记录范围，确认内容包含实际对象及影响。新建和编辑复用字段规则，失败定位到字段并保留其他输入。删除只在业务明确需要时提供，由服务端权限和业务约束最终裁定。
+
+标准 CRUD 自带的状态可引用共用设计；页面仍需说明角色、数据范围、可见字段、业务校验及差异。AC 至少按实际维护任务验证列表到详情返回、成功写入、禁止写入和适用校验。
+
+## PC 用户任务页面 {#pc-task}
+
+适用于申请、办理和跨模型任务。先给当前任务与下一步，按使用频率和决策顺序安排信息，不把所有底表铺成菜单。列表、详情和办理页按任务分开；同页编辑/提交/成功等状态在同一 PageSpec 中记录。
+
+为每个入口写清直接链接、前置条件、返回位置与成功出口。可编辑区域和只读依据区分，主操作有具体业务动词；确认步骤仅用于需要复核的信息和后果。页面动作对应一个明确的业务契约，提交结果未知时查询原结果，不以新随机幂等键重提。
+
+## 移动用户页面 {#mobile-task}
+
+使用有作用域的 `openxiangda/mobile` 与平台字段组件。根据现场任务独立组织首页、列表、详情和填写顺序；不把宽表格缩小后当作移动设计。确定常用入口、任务卡片上的必要信息、主动作、导航返回与输入退出规则。
+
+逐页检查触摸目标、键盘遮挡、焦点、滚动、安全区和长标题；筛选抽屉的应用/取消含义明确。网络慢时保留输入并阻止误操作，失败后给恢复入口。图片先缩略图、原图按需，附件展示大小限制、进度和失败原因。设计写明目标尺寸和渠道，真实验收在目标端走完主要任务。
+
+## 匿名表单与本人记录 {#public-form}
+
+外部无平台账号的人使用[匿名公开访问](public-access.md)，不建 guest 角色或开放普通 Data API。设计说明公开入口、收集目的、必填/可选信息、附件规则、提交后结果和本人记录的能力范围。
+
+明确同浏览器续填/本人访问的边界与凭证丢失后的实际行为，不承诺跨设备找回能力。所有权由平台填写；前端不接受用户指定其他人的身份。公开页面状态、校验、结果未知与安全提示按所消费契约设计，不虚构额外隐私同意或注册步骤。
+
+## 审批与办理详情 {#workflow}
+
+复用[标准流程、待办和通知](workflow-events.md)。详情优先显示当前状态、业务摘要、当前任务及历史；只提供当前用户被授权的操作。区分申请人、办理人和旁观者看到的字段、意见与动作，写清退回可编辑范围、撤回条件、转交等已启用能力。
+
+快速重复点击、任务已被他人处理和响应中断要有具体结果与恢复方式。通知详情跳转回标准目标，不复制流程状态或另做审批授权。AC 用真实角色覆盖主流程、退回/拒绝及越权反例。
+
+## 每页交互规格检查 {#page-review}
+
+把下表应用到每个实际页面。共用行为引用一个权威设计，页面写差异；不适用时说明业务理由，不为凑表增加功能。
+
+| 维度 | 编码前的具体决定 |
+| --- | --- |
+| 任务与入口 | 稳定页面 ID，REQ/旅程、角色和目标；入口、直链、返回及成功出口 |
+| 信息与字段 | 区域优先级、默认排序/筛选；标签、帮助、默认值、必填、联动、可编辑条件、校验时机和提示位置 |
+| 操作与反馈 | 主次操作、触发条件、文案、隐藏/禁用依据、复核内容、成功反馈和后续动作 |
+| 页面状态 | 初次加载/刷新、正常、首次空数据、筛选无结果、无权限、请求错误和重试 |
+| 写入与恢复 | 未保存、提交中、成功、明确失败、结果未知、他人修改冲突；输入保留与草稿边界 |
+| 数据边界 | 空值、长文本、最大条目、分页、批量选择范围；附件类型/大小/失败及重试 |
+| 权限与多端 | 页面/动作/行/字段、多角色并集；PC 批量与移动任务差异、键盘焦点、触摸和返回 |
+| 原型与验收 | 所选标准模式或原型位置、适用状态；对应 AC、角色、输入条件、操作和可观察结果 |
+
+## 评审与验证尺度 {#evaluation}
+
+先用用户能理解的方式走一遍“从哪里进来、看到什么、怎样完成、出错怎么恢复”，再核对规则、数据与权限的一致性。原型允许样例数据，必须标注；只有效果图不能证明任务可完成。选定标准模式也需完成本应用的逐页差异设计。
+
+实现后用实际界面验证任务成功率和明显阻碍，至少覆盖已纳入范围的角色、入口、重要状态和目标端。记录结果未知、重复操作和并发冲突的服务端读回，不只看 toast；性能记录数据量和请求链路。构建通过、HTTP 200、截图数量或检查表填满均不代替真实业务验收。

package/skills/openxiangda-v2/references/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
+}
+```