From 444f20c3195ae6abef16e1c7bceae6f8be512482 Mon Sep 17 00:00:00 2001 From: sunjunzhao Date: Mon, 19 Oct 2026 17:22:18 +0800 Subject: [PATCH] =?UTF-8?q?feat(app-dev):=20audit=20app.manifest.json=20as?= =?UTF-8?q?=20die-level=20onboarding=20blocker=20and=20document=20dual=20m?= =?UTF-8?q?anifest=20submit=20channels=20=E2=80=94=20app=20center=20wizard?= =?UTF-8?q?=20import=20consumes=20the=20same=20repo=20manifest=20via=20the?= =?UTF-8?q?=20same=20submit=20pipeline=20(same=20validation,=20202=20revie?= =?UTF-8?q?w=20for=20governance=20fields);=20checklist=20A1=20gains=20rati?= =?UTF-8?q?onale=20and=20remediation;=20troubleshooting=20tables=20gain=20?= =?UTF-8?q?wizard-import=20failure=20row?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- skills/app-dev/SKILL.md | 6 ++++-- skills/app-dev/references/checklist.md | 2 +- skills/app-dev/references/publish-deploy.md | 1 + skills/app-dev/references/troubleshooting.md | 1 + 4 files changed, 7 insertions(+), 3 deletions(-) diff --git a/skills/app-dev/SKILL.md b/skills/app-dev/SKILL.md index 7385383..7bcc7f3 100644 --- a/skills/app-dev/SKILL.md +++ b/skills/app-dev/SKILL.md @@ -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 约定 `.`（如 `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 ] [--store] [ # micro 前端产物：aigrego-release publish --dist （包根必须直接含 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//...` 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` | diff --git a/skills/app-dev/references/checklist.md b/skills/app-dev/references/checklist.md index 822d32e..d0cfadd 100644 --- a/skills/app-dev/references/checklist.md +++ b/skills/app-dev/references/checklist.md @@ -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]` | 取值 | diff --git a/skills/app-dev/references/publish-deploy.md b/skills/app-dev/references/publish-deploy.md index 5308c35..3979e9a 100644 --- a/skills/app-dev/references/publish-deploy.md +++ b/skills/app-dev/references/publish-deploy.md @@ -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` diff --git a/skills/app-dev/references/troubleshooting.md b/skills/app-dev/references/troubleshooting.md index 43e4b22..9f8f86e 100644 --- a/skills/app-dev/references/troubleshooting.md +++ b/skills/app-dev/references/troubleshooting.md @@ -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` 重复上架 | 视为跳过（幂等） |