feat(app-dev): audit app.manifest.json as die-level onboarding blocker and document dual manifest submit channels — app center wizard import consumes the same repo manifest via the same submit pipeline (same validation, 202 review for governance fields); checklist A1 gains rationale and remediation; troubleshooting tables gain wizard-import failure row
This commit is contained in:
sunjunzhao committed
1 parent
a10d01a44b
commit
444f20c319
4 files changed
+7
-3
No files matched your search
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: app-dev
|
||||
description: 在独立仓库按 TickShield（刻盾云）平台契约开发、审查、发布生态应用（micro/service）：listingKey 四位一体、app.manifest.json、tickshield-node-runtime 基础镜像、@aigrego/guard 四道闸与 tenant_id 租户隔离、micro 前端 portal-sdk 宿主桥、release-cli 发布与商店上架部署。凡用户要求「开发一个平台应用 / 新建 app / 写个 micro 应用 / 做个像 secret-manager / demo-app 那样的应用 / 在门户里加个自己的应用 / 接入 TickShield / 上架应用到商店 / 审查这个 app 能不能部署到平台 / 帮我看看接入还缺什么」，或带着 注册不上去 / 401 missing app credentials / 心跳 404 / host must equal listingKey / 四道闸 403 / 跨租户数据串了 / image registry not registered / invalid manifest skipped / 应用装上了但 /svc 不通 / PROD 白屏 CSP 报错 等症状，或提到 listingKey / app.manifest.json / 四道闸 / TDT / tenant_id / portal-sdk / release-cli / tickshield-node-runtime 时，务必使用本 skill——即使用户没说「应用接入」四个字。Use whenever the user develops, scaffolds, audits, onboards, publishes or deploys a TickShield platform app (micro or service) from an independent repository. 边界：非平台场景的通用 Dockerfile 选型评审用 runtime-image；通用 Gitea Actions 工作流规范用 gitea-actions；CI 工作流的发布 job 改造/新建发布工作流用 app-publish；git 提交推送与日报用 push-and-report；平台基座本身（portal/gateway/packages/* 控制面）的开发不归本 skill。
|
||||
description: 在独立仓库按 TickShield（刻盾云）平台契约开发、审查、发布生态应用（micro/service）：listingKey 四位一体、app.manifest.json、tickshield-node-runtime 基础镜像、@aigrego/guard 四道闸与 tenant_id 租户隔离、micro 前端 portal-sdk 宿主桥、release-cli 发布与商店上架部署。凡用户要求「开发一个平台应用 / 新建 app / 写个 micro 应用 / 做个像 secret-manager / demo-app 那样的应用 / 在门户里加个自己的应用 / 接入 TickShield / 上架应用到商店 / 审查这个 app 能不能部署到平台 / 帮我看看接入还缺什么」，或带着 注册不上去 / 401 missing app credentials / 心跳 404 / host must equal listingKey / 四道闸 403 / 跨租户数据串了 / image registry not registered / invalid manifest skipped / 应用中心导入失败 / 应用装上了但 /svc 不通 / PROD 白屏 CSP 报错 等症状，或提到 listingKey / app.manifest.json / 四道闸 / TDT / tenant_id / portal-sdk / release-cli / tickshield-node-runtime 时，务必使用本 skill——即使用户没说「应用接入」四个字。Use whenever the user develops, scaffolds, audits, onboards, publishes or deploys a TickShield platform app (micro or service) from an independent repository. 边界：非平台场景的通用 Dockerfile 选型评审用 runtime-image；通用 Gitea Actions 工作流规范用 gitea-actions；CI 工作流的发布 job 改造/新建发布工作流用 app-publish；git 提交推送与日报用 push-and-report；平台基座本身（portal/gateway/packages/* 控制面）的开发不归本 skill。
|
||||
---
|
||||
|
||||
# app-dev — TickShield 生态应用开发规范（独立仓库 → 可直接部署上架）
|
||||
@@ -38,7 +38,7 @@ TickShield 生态应用的交付物只有两样：**镜像 + `app.manifest.json`
|
||||
|
||||
## 第 0 步：备料分流
|
||||
|
||||
1. 看仓库根：无 `app.manifest.json` 且无 `Dockerfile` → 新建模式；否则 → 审查模式。
|
||||
1. 看仓库根：无 `app.manifest.json` 且无 `Dockerfile` → 新建模式；否则 → 审查模式。**审查模式第一项先查 `app.manifest.json` 在不在**：它是平台基座接入应用的配置，`aigrego-release` 与 console「应用中心」向导导入两条上架路径消费的都是仓库里这份文件——缺失 = 接入阻断（die 级首要修复项），照 `references/templates/` 按应用类型补一份，不是可选项。
|
||||
2. 新建模式采集四要素（上表）。listingKey 必须用户亲口确认——它是**四位一体** key（== TDT `aud` == 容器名 == Docker 网络别名 == scope 命名空间），全局唯一、**不可变更**，改 key 等于换应用。
|
||||
3. scopes 约定 `<listingKey>.<action>`（如 `my-app.read`/`my-app.write`），格式 `^[a-z0-9][a-z0-9_-]*(\.[a-z0-9][a-z0-9_-]*)+$`（至少两段）。
|
||||
|
||||
@@ -104,6 +104,7 @@ aigrego-release publish --manifest app.manifest.json [--image <ref>] [--store] [
|
||||
# micro 前端产物：aigrego-release publish --dist <dir>（包根必须直接含 index.html）
|
||||
```
|
||||
|
||||
- **manifest 进平台是双通道、同一份文件**：CLI `publish --manifest`（上）或平台侧 console「应用中心」按向导导入——同一条 submit 管道（同一套校验、治理字段变更同样 202 进审核队列）。不管走哪条，仓库里的 `app.manifest.json` 都必须最新且合法；走手动通道时把这份文件交付给平台管理员。
|
||||
- 治理字段（`scopes`/`aclManifest`/`exchangeTargets`/`dependencies`）变更 → 202 进审核队列（exit 0 但**不生效**），批准前不影响已安装租户；首个版本直接生效。
|
||||
- 商店上架/授权/安装/启停/卸载是平台侧 console 动作；镜像 host 必须在 registries 白名单（空表=全拒）。
|
||||
- 输出「待平台侧操作」清单：auto_publish 开关、registries 登记、治理审核批准、授权安装——这些 Agent 做不到，不绕道不假装完成。
|
||||
@@ -160,6 +161,7 @@ fail-fast 分级：①②③④⑤⑥违反 = **die**（拦死，无绕过口）
|
||||
| 心跳 404 | 实例行丢失（被清理） | 正常自愈信号，重走 register（基础镜像已内置） |
|
||||
| 心跳 409 | 管理面停服 | 保持心跳等恢复，**不要重注册** |
|
||||
| 部署后应用没注册且无报错 | ScanManifests 对非法 manifest 静默跳过 | 看 portal 日志 `invalid manifest, skipped`，对照校验表修 |
|
||||
| 应用中心向导导入失败/应用未出现 | manifest 缺失或字段非法（向导与 submit 同一套校验） | 先跑 check-app.sh，按 checklist A 节修齐再导入 |
|
||||
| `/svc/<key>/...` 401 | TDT aud ≠ 路径 key / 过期 / 签名错 | 令牌 `aud` 必须等于目标 listingKey |
|
||||
| 403 `gate=scope/role/acl` | 四道闸各自语义（非 identity 全 403） | 对照 claims.scopes/role/permissions 与路由 spec |
|
||||
| 安装 op failed（30s 未自注册） | 镜像没内嵌注册循环/凭证未注入 | 必须 `FROM tickshield-node-runtime:base` |
|
||||
|
||||
@@ -6,7 +6,7 @@
|
||||
|
||||
| # | 项 | 档 | 验证方法 |
|
||||
|---|---|---|---|
|
||||
| A1 | `app.manifest.json` 在仓库根 | die `[S]` | 文件存在 |
|
||||
| A1 | `app.manifest.json` 在仓库根且内容最新——平台基座接入配置，`aigrego-release` 与应用中心向导导入两条上架路径都消费这份文件；缺失照 `references/templates/` 按类型补齐 | die `[S]` | 文件存在 |
|
||||
| A2 | `listingKey` 过 `^[a-z0-9][a-z0-9-]{0,62}$`，全局唯一，用户已确认不再变 | die `[S]` | 正则 + 用户确认记录 |
|
||||
| A3 | `version` 严格 semver | die `[S]` | 正则 |
|
||||
| A4 | `type` ∈ `micro`/`service`（缺省=service） | die `[S]` | 取值 |
|
||||
|
||||
@@ -51,6 +51,7 @@ curl -sSL https://code.innev.cn/images/tickshield-dist/raw/branch/main/cli/aigre
|
||||
|
||||
状态机 `draft → published → installed → active`。开发者交付物 = **镜像 + manifest**；注册/上架/授权/安装/启停/卸载全部由平台在 console「应用市场」完成（租户侧注册/安装/卸载端点已下线）。
|
||||
|
||||
- **manifest 进平台双通道**：`publish --manifest`（CLI/CI）；或平台侧 console「应用中心」按向导导入 `app.manifest.json`——同一条 submit 管道：同一套校验、治理字段变更同样 202 进审核队列；两条路消费的都是应用仓库里这份文件
|
||||
- **上架双通道**：平台管理员 console 操作；或应用凭证 + auto_publish（`publish --store`）
|
||||
- **授权即安装**：授权变更自动建/停 `app_installs` 行；收权停用（数据保留）；卸载回 published，安装行保留
|
||||
- **FR-101 registries 表即白名单**：安装按镜像 host 精确匹配 registries 行，未登记一律 403；**空表 = 全拒**（安全默认）。host 归一对齐 docker 语义：首段含 `.`/`:` 或为 `localhost` → 首段即 host；否则归一 `docker.io`
|
||||
|
||||
@@ -75,6 +75,7 @@ die 消息统一三段式：是什么 + 为什么（后果） + 怎么办/绕过
|
||||
|
||||
| 症状 | 原因 | 怎么办 |
|
||||
|---|---|---|
|
||||
| 应用中心向导导入失败 / 导入后应用未出现 | manifest 缺失或字段非法（向导与 submit 同一套校验） | 先跑 check-app.sh，按 checklist A 节修齐再导入 |
|
||||
| publish 403（凭证没错） | `--key` 与凭证 listingKey 不一致；或 `--store` 时 auto_publish 未开 | 应用只能操作自己；找平台管理员开 auto_publish |
|
||||
| publish 返回 202 但「没生效」 | 治理字段变更进审核队列 | 这是设计——等平台管理员批准，或 `--wait` 轮询 |
|
||||
| 409 已上架 | `--store` 重复上架 | 视为跳过（幂等） |
|
||||
|
||||
Reference in new issue
Block a user