openxiangda 2.0.1 → 2.1.1

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.
Files changed (12) hide show
  1. package/documentation/delivery.md +6 -0
  2. package/documentation/getting-started.md +81 -4
  3. package/documentation/manifest.json +4 -4
  4. package/documentation/reference/cli.md +1 -0
  5. package/package.json +31 -22
  6. package/releases/2.1.0.json +44 -0
  7. package/releases/2.1.1.json +48 -0
  8. package/skills/manifest.json +1 -1
  9. package/skills/openxiangda-v2/SKILL.md +11 -4
  10. package/skills/openxiangda-v2/references/cli.md +1 -0
  11. package/skills/openxiangda-v2/references/delivery.md +6 -0
  12. package/skills/openxiangda-v2/references/getting-started.md +81 -4
package/documentation/delivery.md CHANGED
@@ -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 秒反馈一次。平台的准备、部署、切换和健康检查状态来自原运行。观察超时或连接中断不会取消部署或重建候选，使用下面的命令继续跟踪：
package/documentation/getting-started.md CHANGED
@@ -11,10 +11,10 @@ OpenXiangda 2.0 默认生成 React 应用和共享契约。普通 CRUD、标准
11
11
  以下命令的版本占位符由随包资料替换为该根包的精确版本。网站源码阅读者应先确认要使用的发行版本。
12
12
 
13
13
  ```bash
14
- pnpm dlx openxiangda@2.0.1 skill install --force
15
- pnpm dlx openxiangda@2.0.1 auth status --base-url <平台地址> --json
16
- pnpm dlx openxiangda@2.0.1 login --base-url https://platform.example.com
17
- pnpm dlx openxiangda@2.0.1 create my-app --base-url https://platform.example.com
14
+ pnpm dlx openxiangda@2.1.1 skill install --force
15
+ pnpm dlx openxiangda@2.1.1 auth status --base-url <平台地址> --json
16
+ pnpm dlx openxiangda@2.1.1 login --base-url https://platform.example.com
17
+ pnpm dlx openxiangda@2.1.1 create my-app --base-url https://platform.example.com
18
18
  cd my-app
19
19
  pnpm openxiangda context --json
20
20
  pnpm openxiangda dev
@@ -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@2.1.1 auth status --base-url <平台> --json
101
+ pnpm dlx openxiangda@2.1.1 source resolve <仓库URL> --base-url <平台> --json
102
+ pnpm dlx openxiangda@2.1.1 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`，它已包含检查、测试和构建；无需再连续重复运行全部脚本。
package/documentation/manifest.json CHANGED
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "schemaVersion": "openxiangda.documentation/v1",
3
- "version": "2.0.1",
3
+ "version": "2.1.1",
4
4
  "topics": [
5
5
  {
6
6
  "id": "getting-started",
7
7
  "title": "安装与开始开发",
8
8
  "file": "getting-started.md",
9
- "sha256": "8821ba34fc5f9f01572178136ae2602db5ee106644b1bd637ca80e065389a41f"
9
+ "sha256": "5e712efa10651fe9b133f9bc0fe3c6af5b8d5ed655ac8c90c53b09c2109081ac"
10
10
  },
11
11
  {
12
12
  "id": "product-design",
@@ -96,7 +96,7 @@
96
96
  "id": "delivery",
97
97
  "title": "部署、生产晋级与恢复",
98
98
  "file": "delivery.md",
99
- "sha256": "361cf6a12a27155647d863b2ac39aeb57b6e6b5454ced6c13d3540891202a4fc"
99
+ "sha256": "30152536bf782d62ba182272086033fa45596e1f9f42eefe59169c9fa25af68f"
100
100
  },
101
101
  {
102
102
  "id": "upgrading",
@@ -108,7 +108,7 @@
108
108
  "id": "cli",
109
109
  "title": "CLI 命令参考",
110
110
  "file": "reference/cli.md",
111
- "sha256": "05005a0fb268af776510128132b984bc88ca20c5232190aa1ee26070bce796d4"
111
+ "sha256": "f17c3f2bb78bb61382f51ba7ab36a89f228f116e1f020b30ad833a0f4a89d57d"
112
112
  },
113
113
  {
114
114
  "id": "mcp",
package/documentation/reference/cli.md CHANGED
@@ -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` | 远端变更 | 按计划准备可选的真实预发验收身份 |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "openxiangda",
3
- "version": "2.0.1",
3
+ "version": "2.1.1",
4
4
  "description": "OpenXiangda 2.0 的统一命令、应用 SDK、MCP 与中文 AI 技能资料。",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -58,13 +58,13 @@
58
58
  "antd-mobile": "5.42.3",
59
59
  "dayjs": "1.11.18",
60
60
  "docx-preview": "0.3.7",
61
- "openxiangda-cli": "2.0.1",
62
- "openxiangda-contracts": "2.0.0",
63
- "openxiangda-devkit-core": "2.0.0",
61
+ "openxiangda-cli": "2.2.0",
62
+ "openxiangda-contracts": "2.2.0",
63
+ "openxiangda-devkit-core": "2.2.0",
64
64
  "openxiangda-legacy": "npm:openxiangda@1.0.268",
65
- "openxiangda-mcp": "2.0.0",
66
- "openxiangda-nest": "2.0.0",
67
- "openxiangda-skill-kit": "2.0.0",
65
+ "openxiangda-mcp": "2.0.2",
66
+ "openxiangda-nest": "2.0.2",
67
+ "openxiangda-skill-kit": "2.0.2",
68
68
  "xlsx": "https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz"
69
69
  },
70
70
  "peerDependencies": {
@@ -130,18 +130,24 @@
130
130
  },
131
131
  "openxiangdaRelease": {
132
132
  "schemaVersion": "openxiangda.release-notes/v1",
133
- "version": "2.0.1",
134
- "title": "OpenXiangda pnpm 工作区识别修复",
133
+ "version": "2.1.1",
134
+ "title": "OpenXiangda 应用源码托管",
135
135
  "status": "reviewed",
136
- "summary": "修复独立安装的统一入口进入 pnpm 工作区时无法找到项目 CLI 的问题，继续严格使用该项目锁定的同代引擎。",
136
+ "summary": "私有化平台通过共享 Forgejo 管理应用源码。创建应用时自动初始化私有仓库并推送代码，应用管理员自动获得仓库管理权限，开发者使用长期 Git 凭据。",
137
137
  "newFeatures": [
138
- "本次为 2.0.0 的修复发布，没有新增应用能力。"
138
+ "既有 PLATFORM_ADMIN 自动获得共享 Git 服务全部已有和新建仓库的管理权限。",
139
+ "source resolve/clone 支持仅凭平台与仓库 URL、使用当前登录态读取源码，不安装或执行应用脚本。",
140
+ "新增 source status、source setup 和 source push 命令，支持初始化恢复和已有工作区接入。",
141
+ "创建应用后自动提交并推送初始源码，通过系统凭据管理器保存个人 Git 凭据。",
142
+ "配套平台支持首次部署前浏览源码及最近提交，并核验部署关联的提交已经推送。"
139
143
  ],
140
144
  "fixes": [
141
- "从 pnpm 符号链接指向的真实包目录解析 openxiangda-cli，避免 WORKSPACE_ENGINE_DEPENDENCY_MISSING。"
145
+ "应用源码可直接保留在平台托管仓库中，减少对开发者个人 Git 服务的依赖。",
146
+ "显式导入保留原 origin 为 external-source，初始化重试保留已有未提交修改，冲突推送不覆盖远端提交。"
142
147
  ],
143
148
  "affectedUsers": [
144
- "使用全局或独立安装的统一入口维护 pnpm 工作区的开发者。"
149
+ "使用 OpenXiangda 2.0 创建应用或接入平台源码仓库的开发者。",
150
+ "维护内部私有化平台和应用管理员权限的平台管理员。"
145
151
  ],
146
152
  "compatibility": {
147
153
  "node": ">=24",
@@ -150,22 +156,25 @@
150
156
  "v2"
151
157
  ],
152
158
  "v1Policy": "V1 应用保持原代际、版本锁定与登录绑定。",
153
- "platformPolicy": "没有新增平台能力要求，部署仍执行目标平台预检。",
154
- "backendBuild": "Nest 镜像继续由开发者电脑上的 Docker 构建。",
159
+ "platformPolicy": "自动源码托管需要匹配的平台后端、管理前端和网关，并配置 OPENXIANGDA_SOURCE_*；未启用的站点保持原创建行为。",
160
+ "gitCredential": "支持 macOS Keychain、Windows Git Credential Manager，以及 Linux 已安装的 Git Credential Manager 或 libsecret。",
155
161
  "releaseChannels": "latest / stable-v2：V2 正式版；legacy-v1：V1 维护版；alpha：预发布。"
156
162
  },
157
163
  "upgradeSteps": [
158
- "在 Node.js 24 环境安装统一入口：npm install -g openxiangda@2.0.1。",
159
- "在项目及其子目录运行 openxiangda version --json，核对工作区代际、项目引擎版本和解析来源。",
160
- "需要更新 V2 项目依赖时运行 openxiangda update install --target workspace，检查锁文件并完成项目验收。"
164
+ "平台管理员配置共享 Forgejo、源码入口和专用凭据派生密钥，部署匹配的平台版本；长期保留密钥及 Git 数据。",
165
+ "在 Node.js 24 环境安装统一入口：npm install -g openxiangda@2.1.1。",
166
+ "更新 V2 工作区工具链；新应用自动接入，已有应用运行 openxiangda source setup --import 接入。",
167
+ "完成修改后运行 openxiangda source push -m 描述，再按现有检查和部署流程交付。"
161
168
  ],
162
169
  "knownLimitations": [
163
- "独立入口更新不会自动升级项目锁定的工具链，也不会迁移 V1 应用。",
164
- "已发布的 2.0.0 保持不可变；本修复不代表平台部署或业务验收已完成。"
170
+ "当前仅同步应用管理员新增授权，不同步撤销或删除。",
171
+ "导入推送当前分支，不自动迁移全部历史分支、标签及 LFS 对象。",
172
+ "制品仍在本地构建；提交存在性核验不构成服务端构建证明。",
173
+ "新源码功能不依赖 Studio；Studio 旧代码移除属于独立后续工作。"
165
174
  ],
166
175
  "issues": [],
167
- "sha256": "6bba13f70a956b58412da587fc9d7b50dd279fea809eae2461dd3515321a83dd",
168
- "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.0.1"
176
+ "sha256": "f7341eb21e1489c684ee03eed31568063dfad01bfe345f914552bd51b7357f84",
177
+ "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.1.1"
169
178
  },
170
179
  "scripts": {
171
180
  "build": "node ../../scripts/prune-package-dist.mjs && tsc -p tsconfig.json && node scripts/copy-assets.mjs",
package/releases/2.1.0.json ADDED
@@ -0,0 +1,44 @@
1
+ {
2
+ "schemaVersion": "openxiangda.release-notes/v1",
3
+ "version": "2.1.0",
4
+ "title": "OpenXiangda 平台托管应用镜像上传",
5
+ "status": "reviewed",
6
+ "summary": "应用 Nest 后端在本机构建为 OCI 镜像后，通过平台登录态分片上传。平台负责应用归属校验、镜像存储和运行时拉取，开发者无需取得平台维护者个人镜像仓库的推送权限。",
7
+ "newFeatures": [
8
+ "发现并优先使用平台 backendImageUpload 能力，导出 linux/amd64 OCI 镜像并上传有界分片。",
9
+ "上传前校验本地镜像大小和摘要，复用已完成的镜像回执，并恢复分片传输中断。"
10
+ ],
11
+ "fixes": [
12
+ "启用平台上传后，应用部署不再依赖开发者对平台维护者镜像仓库的推送权限。",
13
+ "Docker classic image store 不支持 OCI 导出时，返回明确的 builder 配置指引。"
14
+ ],
15
+ "affectedUsers": [
16
+ "声明可选 Nest 后端并通过 CLI 或 MCP 部署的 OpenXiangda 2.0 应用开发者。",
17
+ "维护共享应用运行时及平台镜像存储的平台管理员。"
18
+ ],
19
+ "compatibility": {
20
+ "node": ">=24",
21
+ "workspaceGenerations": [
22
+ "v1",
23
+ "v2"
24
+ ],
25
+ "v1Policy": "V1 应用保持原代际、版本锁定与登录绑定。",
26
+ "platformPolicy": "平台托管上传需要匹配的后端、Registry 和网关发布，并启用 backendImageUpload；旧平台继续使用既有构建合同。",
27
+ "backendBuild": "可选 Nest 后端仍在开发者电脑上使用 Docker Buildx 构建，需要支持 OCI exporter 的 builder。",
28
+ "releaseChannels": "latest / stable-v2：V2 正式版；legacy-v1：V1 维护版；alpha：预发布。"
29
+ },
30
+ "upgradeSteps": [
31
+ "平台管理员先按部署运行手册准备镜像存储与凭据，再部署匹配的后端和网关。",
32
+ "在 Node.js 24 环境安装统一入口：npm install -g openxiangda@2.1.0。",
33
+ "更新 V2 项目锁定的工具链并刷新项目资料，核对平台上传能力后运行项目的 openxiangda deploy。"
34
+ ],
35
+ "knownLimitations": [
36
+ "当前仅支持 linux/amd64 单平台 OCI 镜像；默认单镜像上限为 1Gi，由平台配置控制。",
37
+ "已声明但未启用的平台上传能力会阻止部署，避免回退到个人镜像仓库推送。",
38
+ "镜像保留与垃圾回收由平台运维单独管理；现有版本仍可能需要历史镜像进行部署或回滚。",
39
+ "托管镜像开始使用后，后端回滚必须保留 Registry、持久卷、凭据和网关读取路由。"
40
+ ],
41
+ "issues": [],
42
+ "sha256": "d7f6a21ddc37b3d2439350bf17f5f4575192168944dc33efb15460f7d1854aff",
43
+ "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.1.0"
44
+ }
package/releases/2.1.1.json ADDED
@@ -0,0 +1,48 @@
1
+ {
2
+ "schemaVersion": "openxiangda.release-notes/v1",
3
+ "version": "2.1.1",
4
+ "title": "OpenXiangda 应用源码托管",
5
+ "status": "reviewed",
6
+ "summary": "私有化平台通过共享 Forgejo 管理应用源码。创建应用时自动初始化私有仓库并推送代码，应用管理员自动获得仓库管理权限，开发者使用长期 Git 凭据。",
7
+ "newFeatures": [
8
+ "既有 PLATFORM_ADMIN 自动获得共享 Git 服务全部已有和新建仓库的管理权限。",
9
+ "source resolve/clone 支持仅凭平台与仓库 URL、使用当前登录态读取源码，不安装或执行应用脚本。",
10
+ "新增 source status、source setup 和 source push 命令，支持初始化恢复和已有工作区接入。",
11
+ "创建应用后自动提交并推送初始源码，通过系统凭据管理器保存个人 Git 凭据。",
12
+ "配套平台支持首次部署前浏览源码及最近提交，并核验部署关联的提交已经推送。"
13
+ ],
14
+ "fixes": [
15
+ "应用源码可直接保留在平台托管仓库中，减少对开发者个人 Git 服务的依赖。",
16
+ "显式导入保留原 origin 为 external-source，初始化重试保留已有未提交修改，冲突推送不覆盖远端提交。"
17
+ ],
18
+ "affectedUsers": [
19
+ "使用 OpenXiangda 2.0 创建应用或接入平台源码仓库的开发者。",
20
+ "维护内部私有化平台和应用管理员权限的平台管理员。"
21
+ ],
22
+ "compatibility": {
23
+ "node": ">=24",
24
+ "workspaceGenerations": [
25
+ "v1",
26
+ "v2"
27
+ ],
28
+ "v1Policy": "V1 应用保持原代际、版本锁定与登录绑定。",
29
+ "platformPolicy": "自动源码托管需要匹配的平台后端、管理前端和网关，并配置 OPENXIANGDA_SOURCE_*；未启用的站点保持原创建行为。",
30
+ "gitCredential": "支持 macOS Keychain、Windows Git Credential Manager，以及 Linux 已安装的 Git Credential Manager 或 libsecret。",
31
+ "releaseChannels": "latest / stable-v2：V2 正式版；legacy-v1：V1 维护版；alpha：预发布。"
32
+ },
33
+ "upgradeSteps": [
34
+ "平台管理员配置共享 Forgejo、源码入口和专用凭据派生密钥，部署匹配的平台版本；长期保留密钥及 Git 数据。",
35
+ "在 Node.js 24 环境安装统一入口：npm install -g openxiangda@2.1.1。",
36
+ "更新 V2 工作区工具链；新应用自动接入，已有应用运行 openxiangda source setup --import 接入。",
37
+ "完成修改后运行 openxiangda source push -m 描述，再按现有检查和部署流程交付。"
38
+ ],
39
+ "knownLimitations": [
40
+ "当前仅同步应用管理员新增授权，不同步撤销或删除。",
41
+ "导入推送当前分支，不自动迁移全部历史分支、标签及 LFS 对象。",
42
+ "制品仍在本地构建；提交存在性核验不构成服务端构建证明。",
43
+ "新源码功能不依赖 Studio；Studio 旧代码移除属于独立后续工作。"
44
+ ],
45
+ "issues": [],
46
+ "sha256": "f7341eb21e1489c684ee03eed31568063dfad01bfe345f914552bd51b7357f84",
47
+ "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.1.1"
48
+ }
package/skills/manifest.json CHANGED
@@ -4,7 +4,7 @@
4
4
  {
5
5
  "name": "openxiangda-v2",
6
6
  "description": "使用 OpenXiangda 2.0 从模糊业务想法、已有资料或具体变更出发，通过对话发现模块、完成详细产品设计，再开发、检查和交付应用。维护 1.x 应用时使用对应的 1.x 技能。",
7
- "sha256": "ed347cba6d08ce24ac83ecac078b579aa9b9f02088b7a0a99327a5ba3556f1cf"
7
+ "sha256": "1c60318522970b4531455012d7a85b968bdae19c0b96e7c6a5ff53c1f6ebd981"
8
8
  }
9
9
  ]
10
10
  }
package/skills/openxiangda-v2/SKILL.md CHANGED
@@ -18,10 +18,10 @@ description: 使用 OpenXiangda 2.0 从模糊业务想法、已有资料或具
18
18
  未创建工作区时使用本 Skill 随根包发布的精确版本：
19
19
 
20
20
  ```bash
21
- pnpm dlx openxiangda@2.0.1 auth status --base-url <平台地址> --json
22
- pnpm dlx openxiangda@2.0.1 login --base-url <平台地址>
23
- pnpm dlx openxiangda@2.0.1 create <应用目录> --base-url <同一平台地址>
24
- pnpm dlx openxiangda@2.0.1 skill install --force
21
+ pnpm dlx openxiangda@2.1.1 auth status --base-url <平台地址> --json
22
+ pnpm dlx openxiangda@2.1.1 login --base-url <平台地址>
23
+ pnpm dlx openxiangda@2.1.1 create <应用目录> --base-url <同一平台地址>
24
+ pnpm dlx openxiangda@2.1.1 skill install --force
25
25
  ```
26
26
 
27
27
  创建前把产品要求的目标平台明确带入命令，不从旧登录态推断站点。已有工作区从原绑定恢复，平台不一致时先解决登录与目标，不改 link 文件跨站创建。
@@ -35,6 +35,7 @@ pnpm dlx openxiangda@2.0.1 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 连接。
package/skills/openxiangda-v2/references/cli.md CHANGED
@@ -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` | 远端变更 | 按计划准备可选的真实预发验收身份 |
package/skills/openxiangda-v2/references/delivery.md CHANGED
@@ -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 秒反馈一次。平台的准备、部署、切换和健康检查状态来自原运行。观察超时或连接中断不会取消部署或重建候选，使用下面的命令继续跟踪：
package/skills/openxiangda-v2/references/getting-started.md CHANGED
@@ -11,10 +11,10 @@ OpenXiangda 2.0 默认生成 React 应用和共享契约。普通 CRUD、标准
11
11
  以下命令的版本占位符由随包资料替换为该根包的精确版本。网站源码阅读者应先确认要使用的发行版本。
12
12
 
13
13
  ```bash
14
- pnpm dlx openxiangda@2.0.1 skill install --force
15
- pnpm dlx openxiangda@2.0.1 auth status --base-url <平台地址> --json
16
- pnpm dlx openxiangda@2.0.1 login --base-url https://platform.example.com
17
- pnpm dlx openxiangda@2.0.1 create my-app --base-url https://platform.example.com
14
+ pnpm dlx openxiangda@2.1.1 skill install --force
15
+ pnpm dlx openxiangda@2.1.1 auth status --base-url <平台地址> --json
16
+ pnpm dlx openxiangda@2.1.1 login --base-url https://platform.example.com
17
+ pnpm dlx openxiangda@2.1.1 create my-app --base-url https://platform.example.com
18
18
  cd my-app
19
19
  pnpm openxiangda context --json
20
20
  pnpm openxiangda dev
@@ -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@2.1.1 auth status --base-url <平台> --json
101
+ pnpm dlx openxiangda@2.1.1 source resolve <仓库URL> --base-url <平台> --json
102
+ pnpm dlx openxiangda@2.1.1 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`，它已包含检查、测试和构建；无需再连续重复运行全部脚本。