openxiangda-skill-kit 2.0.0 → 2.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "openxiangda-skill-kit",
|
|
3
|
-
"version": "2.0.
|
|
3
|
+
"version": "2.0.2",
|
|
4
4
|
"description": "OpenXiangda 2.0 中文 AI 技能的校验、分发与安装。",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -17,7 +17,7 @@
|
|
|
17
17
|
"README.md"
|
|
18
18
|
],
|
|
19
19
|
"dependencies": {
|
|
20
|
-
"openxiangda-devkit-core": "2.
|
|
20
|
+
"openxiangda-devkit-core": "2.2.0"
|
|
21
21
|
},
|
|
22
22
|
"devDependencies": {
|
|
23
23
|
"tsx": "4.23.12",
|
package/skills/manifest.json
CHANGED
|
@@ -3,8 +3,8 @@
|
|
|
3
3
|
"skills": [
|
|
4
4
|
{
|
|
5
5
|
"name": "openxiangda-v2",
|
|
6
|
-
"description": "使用 OpenXiangda 2.0
|
|
7
|
-
"sha256": "
|
|
6
|
+
"description": "使用 OpenXiangda 2.0 从模糊业务想法、已有资料或具体变更出发，通过对话发现模块、完成详细产品设计，再开发、检查和交付应用。维护 1.x 应用时使用对应的 1.x 技能。",
|
|
7
|
+
"sha256": "65277e1488c828317a85ac547e565878c5347f3a15aca05d1c9dfa1120b64e3d"
|
|
8
8
|
}
|
|
9
9
|
]
|
|
10
10
|
}
|
|
@@ -35,6 +35,7 @@ pnpm dlx openxiangda@__OPENXIANGDA_VERSION__ skill install --force
|
|
|
35
35
|
| 任务 | 参考 |
|
|
36
36
|
| --- | --- |
|
|
37
37
|
| 安装、登录、创建、连接开发 | [开始开发](references/getting-started.md) |
|
|
38
|
+
| 源码仓库、换电脑、旧项目导入、提交推送与重试 | [应用源码](references/getting-started.md#应用源码)；先用 `source status` 读取实际绑定 |
|
|
38
39
|
| 模糊想法、模块发现、PRD、权限与架构设计 | [产品设计](references/product-design.md)、[交互模式](references/interaction-patterns.md) |
|
|
39
40
|
| 理解需求与选择能力 | [开发流程](references/development.md)、[架构](references/concepts.md) |
|
|
40
41
|
| 模型、CRUD、字段与移动表单 | [业务模块](references/application-foundation.md)、[字段](references/field-components.md) |
|
|
@@ -77,6 +78,12 @@ pnpm exec openxiangda --mcp-stdio --cwd <workspace>
|
|
|
77
78
|
|
|
78
79
|
开发开始先同步绑定仓库的远端默认主分支。开发完成包括源码、生成契约与必要记录的提交、推送和主线整合；发布从干净且同步的主分支冻结候选。任务分支已推送不代表进入主线。同一工作区保持一个写者，不覆盖其他会话未提交内容。日常 dev/check 可验证未提交源码。
|
|
79
80
|
|
|
81
|
+
平台启用源码托管时，create 自动建仓并首次推送。后续每轮开发完成使用 `pnpm openxiangda source push -m "变更说明"` 提交并推送；已有提交可省略 `-m`。新电脑或初始化中断使用 `source setup`，迁入外部仓库使用 `source setup --import` 并保留原远端。凭据只存入系统凭据管理器，不手写进 URL 或项目文件；冲突按正常 Git 合并处理，不强推覆盖。
|
|
82
|
+
|
|
83
|
+
已有项目先执行 `source status`；仓库绑定和地址以平台返回为准，不猜测地址或另建个人仓库。提交前检查 Git 差异；`source push -m` 会提交所有未忽略更改，存在其他任务改动时应只提交本轮文件，再不带 `-m` 推送。源码操作使用 CLI，当前没有独立的 source MCP 工具。凭据配置成功后无需每轮重新配置；托管未启用或权限不足时保留原工作区并报告具体原因。
|
|
84
|
+
|
|
85
|
+
支持排查只有平台地址和仓库 URL 时，先运行 `source resolve <仓库URL> --base-url <平台> --json`，再用 `source clone <仓库URL> <新目录> --base-url <平台> --json` 获取源码，可选 `--branch`。无需预先创建工作区，不猜 appCode，不安装或运行应用脚本；使用当前平台登录账号与系统 Git 凭据。平台既有 `PLATFORM_ADMIN` 可管理共享服务全部仓库，应用管理员只管理对应应用仓库。完整契约见[应用源码](references/getting-started.md#应用源码)。
|
|
86
|
+
|
|
80
87
|
只验证时运行 check/check_app；授权部署时直接 deploy/deploy_app，它已经包含检查并默认跟踪平台完成，长步骤持续反馈阶段和耗时。生产显式复用成功测试运行。观察中断用 status <运行ID> --watch 或 deployment_status.watch 继续查询原运行。登录、创建及长期 dev 使用 CLI/终端，分别记录本地验证、部署激活和真实业务验收。
|
|
81
88
|
|
|
82
89
|
失败保留错误码、指针与原候选。结果不确定先查平台，不生成新的随机幂等键掩盖原运行；仅执行平台允许的恢复。升级项目后刷新资料并重启旧 MCP 连接。
|
|
@@ -9,6 +9,7 @@
|
|
|
9
9
|
| `pnpm openxiangda docs` | 只读 | 按主题和章节读取当前版本中文资料 |
|
|
10
10
|
| `pnpm openxiangda admin` | 只读 | 只读查看应用管理能力和流程节点运行配置 |
|
|
11
11
|
| `pnpm openxiangda create` | 远端变更 | 创建、绑定并初始化应用 |
|
|
12
|
+
| `pnpm openxiangda source` | 远端变更 | 配置应用源码仓库、查看状态或提交推送 |
|
|
12
13
|
| `pnpm openxiangda dev` | 本地写入 | 连接平台测试数据启动本地 Web，按需启动 Nest |
|
|
13
14
|
| `pnpm openxiangda check` | 本地写入 | 生成契约并在目标平台预检后执行检查、测试和构建 |
|
|
14
15
|
| `pnpm openxiangda accept` | 远端变更 | 按计划准备可选的真实预发验收身份 |
|
|
@@ -4,6 +4,10 @@
|
|
|
4
4
|
|
|
5
5
|
## 测试部署
|
|
6
6
|
|
|
7
|
+
托管源码应用通过 `pnpm openxiangda source push -m "本轮变更说明"` 完成提交与推送。
|
|
8
|
+
发布系统在平台绑定仓库中核验精确源码提交，并沿用 AppVersion 的源码和制品摘要关联。
|
|
9
|
+
本地构建仍是当前交付方式；源码提交存在不等于平台已独立验证制品由该提交构建。
|
|
10
|
+
|
|
7
11
|
发布前，先将本轮源码、生成契约及必要记录合入并推送仓库的远端默认主分支，然后从干净且同步的主分支工作区发布。工具从 origin 的远端 HEAD 识别主分支，不把任务分支的 upstream 当作主线。未提交、未推送、未合并或落后主线的问题会在构建和上传前返回；工具不会自动合并分支或覆盖其他会话的改动。
|
|
8
12
|
|
|
9
13
|
开发开始时先同步主线并读取项目现状，开发完成包括提交、推送与主线整合。每个工作区保持一个写者；需要并行时使用独立目录并明确各任务范围。日常 dev/check 仍可验证未提交源码。没有 Git 远端的项目应先建立并绑定仓库再发布。
|
|
@@ -21,6 +25,8 @@ pnpm openxiangda logs <deployment-id> --json
|
|
|
21
25
|
|
|
22
26
|
默认目标为 `test`，平台内部标识为 `preproduction`。只读预览不生成构建产物、不上传制品、不提交 DeploymentRun；因此预览成功不能证明代码已通过检查。正式检查使用本地完整校验，再通过目标平台的 `configurationCompatibility` 核对同源规则、密钥、已有物理模型和登录提供方等只读条件；失败时停止后续步骤。只有启用了自定义 Nest 后端的应用才需要构建后端镜像及对应 Docker 环境。
|
|
23
27
|
|
|
28
|
+
平台启用镜像上传后，`deploy` 在本机用 Docker Buildx 导出 OCI 镜像，再使用当前平台登录态分片上传。开发者只需应用部署权限，无需登录平台管理员的镜像仓库或取得推送凭据。已完成的镜像层按摘要复用，中断后重新执行同一条部署命令可恢复上传；平台核验镜像完整性后才进入应用发布。尚未升级的旧平台保留其原镜像构建合同；新平台已声明上传能力但未启用时，命令会明确报告平台配置缺失。
|
|
29
|
+
|
|
24
30
|
生成的不可变 AppVersion 绑定前端、可选后端、配置契约和制品摘要。默认提交后持续跟踪同一运行，直到平台成功、失败或取消，最多观察 15 分钟。`--no-wait` 只提交，适用于已有状态跟踪器的自动化；此时返回运行 ID 不代表部署完成。
|
|
25
31
|
|
|
26
32
|
构建、上传及平台执行都会显示当前阶段和耗时，长步骤每 10 秒反馈一次。平台的准备、部署、切换和健康检查状态来自原运行。观察超时或连接中断不会取消部署或重建候选，使用下面的命令继续跟踪：
|
|
@@ -47,6 +47,83 @@ AppSpec 随开发持续维护：测试发布前补齐总纲、关联变更与验
|
|
|
47
47
|
|
|
48
48
|
纯 CRUD 修改优先使用标准模型、字段和页面；跨模型事务或外部副作用再选择后端。角色、行和字段权限在平台执行。详见[开发流程](development.md)、[模型与标准 CRUD](application-foundation.md)和[按需后端](backend.md)。
|
|
49
49
|
|
|
50
|
+
## 应用源码
|
|
51
|
+
|
|
52
|
+
平台启用源码托管后，`create` 自动建立应用私有仓库、配置长期 Git 凭据并推送首次提交。
|
|
53
|
+
应用管理员自动拥有对应仓库管理员权限；无需注册另一套账号。凭据存入系统凭据管理器，
|
|
54
|
+
macOS 使用 Keychain，Windows 使用 Git Credential Manager，Linux 使用已安装的
|
|
55
|
+
Git Credential Manager 或 libsecret。新电脑首次使用需重新执行源码配置。
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
pnpm openxiangda source status
|
|
59
|
+
pnpm openxiangda source setup
|
|
60
|
+
pnpm openxiangda source push -m "完成本轮应用开发"
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
创建或推送中断后，在原目录重试。已有外部仓库使用 `source setup --import`，原 `origin`
|
|
64
|
+
保留为 `external-source`；当前分支的历史随推送保留，不执行强推，也不自动合并冲突。
|
|
65
|
+
其他分支、标签和 Git LFS 对象需按实际迁移范围另外推送。`source push` 省略 `-m` 时只推送
|
|
66
|
+
已有提交；带 `-m` 时提交当前所有未忽略更改。源码入口位于平台应用运营的“应用源码”。
|
|
67
|
+
|
|
68
|
+
| 当前场景 | 执行方式 |
|
|
69
|
+
| --- | --- |
|
|
70
|
+
| 新应用 | 正常执行 `create`，平台启用后自动建仓、配置凭据和首次推送 |
|
|
71
|
+
| 已有项目首次交接给另一个 AI | 先读 `context --json` 和 `source status`，沿用项目绑定与版本 |
|
|
72
|
+
| 换电脑或初始化中断 | 在应用目录执行 `pnpm openxiangda source setup`；已有提交及未提交修改会保留 |
|
|
73
|
+
| 从个人远端迁入 | 明确迁入后运行 `source setup --import`，原远端保留为 `external-source` |
|
|
74
|
+
| 本轮修改完成 | 检查差异后运行 `source push -m "AppSpec: <本轮变更ID> 变更说明"`；多个任务共享目录时先精确提交本轮文件，再不带 `-m` 推送 |
|
|
75
|
+
| 准备部署 | 先把本轮提交合入并推送远端默认分支，再从干净且同步的主分支执行 `deploy` |
|
|
76
|
+
|
|
77
|
+
新仓库默认使用 `main`；导入时，尚无默认分支的空仓库会采用当前分支（例如 `master`）。
|
|
78
|
+
已有远端默认分支不会因在任务分支运行 setup 而改变。源码操作使用 CLI/终端；
|
|
79
|
+
MCP 的 `docs_read` 可以读取本说明，当前没有独立的源码操作 MCP 工具。
|
|
80
|
+
|
|
81
|
+
| 错误或状态 | 处理 |
|
|
82
|
+
| --- | --- |
|
|
83
|
+
| `enabled: false` | 平台尚未启用托管，沿用当前工作区；由平台管理员配置后再接入 |
|
|
84
|
+
| `APPLICATION_SOURCE_ORIGIN_CONFLICT` | 核实平台绑定和现有 origin；仅在明确迁入时使用 `--import` |
|
|
85
|
+
| `APPLICATION_SOURCE_CREDENTIAL_HELPER_REQUIRED` / `APPLICATION_SOURCE_CREDENTIAL_NOT_STORED` | 安装或解锁系统凭据管理器，再重试 setup；不把密码写入 URL、项目或明文凭据文件 |
|
|
86
|
+
| 403 / 应用管理权限不足 | 核对当前平台账号及应用管理员资格；由已有应用管理员添加权限 |
|
|
87
|
+
| `APPLICATION_SOURCE_PROVIDER_UNAVAILABLE` / `APPLICATION_SOURCE_PROVIDER_FAILED` | 保留原应用和目录，待 Git 服务恢复后重试同一操作 |
|
|
88
|
+
| 推送被拒绝或主线已前进 | 先 fetch 并查看差异，按项目规则合并解决冲突后重试，不强推覆盖 |
|
|
89
|
+
| `APPLICATION_SOURCE_COMMIT_NOT_PUSHED` | 在绑定仓库推送原提交，核对 source status 和远端 SHA 后重试部署 |
|
|
90
|
+
|
|
91
|
+
应用创建人和新增应用管理员拥有对应仓库管理权限，不需要另行维护 Git 角色。
|
|
92
|
+
本期不自动同步权限撤销或删除。不要向应用开发者索要 Forgejo 平台管理员 Token；
|
|
93
|
+
个人凭据由已登录的平台账号获取，配置成功后可长期复用。
|
|
94
|
+
|
|
95
|
+
### 从平台和仓库 URL 获取源码
|
|
96
|
+
|
|
97
|
+
无需本地工作区，使用本 Skill 随包精确版本或已安装的对应 CLI：
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
pnpm dlx openxiangda@__OPENXIANGDA_VERSION__ auth status --base-url <平台> --json
|
|
101
|
+
pnpm dlx openxiangda@__OPENXIANGDA_VERSION__ source resolve <仓库URL> --base-url <平台> --json
|
|
102
|
+
pnpm dlx openxiangda@__OPENXIANGDA_VERSION__ source clone <仓库URL> <新目录> --base-url <平台> --json
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
登录缺失或站点不匹配时，先按该平台执行 login。resolve 根据平台已经登记的绑定返回
|
|
106
|
+
`appCode/name/repository`，不猜应用代码；clone 使用当前账号配置长期凭据后检出源码，
|
|
107
|
+
返回 `root/baseUrl/appCode/repository/branch/commit`。`--branch <分支>` 可指定分支，
|
|
108
|
+
省略时使用 Forgejo 实际默认分支。目标目录必须不存在；失败时保留目录供检查。
|
|
109
|
+
克隆不会加载应用配置、安装依赖、执行应用脚本或递归拉取子模块，并禁用 checkout hooks
|
|
110
|
+
和全局过滤器；需要 LFS 内容时在审查后单独处理。
|
|
111
|
+
|
|
112
|
+
既有 `PLATFORM_ADMIN` 平台管理员映射为共享 Forgejo 管理员，可完整管理已有及以后创建的
|
|
113
|
+
全部仓库，不受应用创建人或应用成员登记限制。平台应用管理员保持对应仓库管理权限。
|
|
114
|
+
该规则没有新增平台角色，也不扩展普通应用成员的权限。
|
|
115
|
+
|
|
116
|
+
正式 API 均位于平台 `/service/openxiangda-api/v2` 下，使用现有登录态：
|
|
117
|
+
|
|
118
|
+
| API | 请求及响应 data |
|
|
119
|
+
| --- | --- |
|
|
120
|
+
| `GET /application-source/resolve?repository=<编码后的仓库URL>` | 接受平台登记的 cloneUrl 或 webUrl，返回 `{ appCode, name, repository }`；不返回凭据 |
|
|
121
|
+
| `POST /application-source/credential` | JSON `{ "repository": "仓库URL" }`，返回 `{ appCode, repository, username, password, name, email }`，响应 `Cache-Control: no-store` |
|
|
122
|
+
| `POST /application-source/administrators/reconcile` | 仅平台管理员；同步已有 PLATFORM_ADMIN 到 Git，返回 `{ synchronized }`，不返回凭据 |
|
|
123
|
+
|
|
124
|
+
使用 CLI 时无需自行调用凭据 API；支持工具不得记录其响应或另建身份体系。
|
|
125
|
+
未登记的外部仓库先在原工作区执行 `source setup --import`，再使用平台返回的仓库 URL。
|
|
126
|
+
|
|
50
127
|
## 检查与交付 {#delivery}
|
|
51
128
|
|
|
52
129
|
只检查时运行 `pnpm openxiangda check`。需要部署测试环境时直接运行 `pnpm openxiangda deploy`，它已包含检查、测试和构建；无需再连续重复运行全部脚本。
|