feat: 收录应用开发发布技能与双语示例 (#214)

## 中文

新增按需调用的内置技能 `app-developer`（应用开发与发布）：中英正文、sidecar、MIT 许可、静态与服务两个通用工作台示例，以及作者接口与分发参考，并登记进 `builtin-skills.json`。作者管理优先使用 AppManage 的有限动作，执行前须通过 `authoring_capabilities` 确认 `app-authoring-v1`，能力不可用时停止受影响的操作；外部 Node/Docker 运行时、托管、Git 服务与数据库的条款和可能费用已在发现文案、compatibility 与正文披露。另将 dev-environment-setup 探测参考中的三处用户 home 示例改为通用路径。

与 #220、#212 合入后的 main 解决 manifest 冲突：技能总数 144，市场版本 1.5.13。验证：catalog 与 i18n 校验 0 errors / 106 warnings（含新技能尚未 ref-bound review 的治理提醒），translate --check 与 git diff --check 通过；远端 validate、translate、CodeQL 通过。Copilot 因额度用尽未能审查。

## English

Add the on-demand builtin `app-developer` skill (application development and publishing): English/Chinese bodies, sidecar, MIT license, static and service workbench examples, plus authoring-interface and distribution references, registered in `builtin-skills.json`. Authoring prefers AppManage's finite actions and must confirm `app-authoring-v1` through `authoring_capabilities` first, stopping affected operations when the capability is unavailable. External Node/Docker runtime, hosting, Git service and database terms and possible costs are disclosed. Three user-home examples in the dev-environment-setup probe reference are neutralized.

The manifest conflict with main after #220 and #212 is resolved: 144 skills, market version 1.5.13. Catalog and i18n validation report 0 errors with 106 warnings (including the new skill's pending ref-bound review notice); translate --check and git diff --check pass; remote validate, translate and CodeQL passed. Copilot could not review because of its quota limit.

skills/app-developer/references/authoring-api.zh-CN.md

@@ -0,0 +1,76 @@
+# 作者接口与交付材料
+
+本文是未发行候选协议的知识材料。中文权威接口正文位于主仓 `docs/功能/市场系统/API/应用开发发布接口.md`；该路径与外仓 PR 不声明在线文档、客户端或官方 seed 已更新。每次先读取实际 capability 结果和当前 Schema。
+
+Agent 使用原 `AppManage` 的有限作者动作，直接进入已有 release、preview、runtime 或 Docker owner。原 ToolExecutor 调用源、真实 Run/用户/Agent/宿主、材料读取根、当前策略与审批在效果边界重新核验。参数不自报 owner，也不获得平台管理凭据。以下动作可按目标组合，表格不是固定开发步骤。
+
+| AppManage action | 参数包络 | 返回事实 |
+|---|---|---|
+| `authoring_capabilities` | 无额外参数 | `capabilities` 的实际 features/policy/hostInstanceId 和当前 Agent 可读的 `fileRoots` 与已登记的 `registryTargetIds`；不授上传或文件写权限 |
+| `read_draft` | `file_ref: FileResourceRef` | 从真实授权文件读取并核验的 `draft: AppDraftRef` |
+| `prepare_release` | `release_request: AppReleasePrepareRequest` | owned candidate、真实 payload/descriptor 摘要、当前 expectedRevision |
+| `commit_release` | `release_request: AppReleaseCommitRequest` | 唯一 writer CAS 保存；activation 与保存分别核验 |
+| `lookup_release_submission` | `installation_id`、原 `submission_id` | 原提交 committed/absent/unknown，不换 ID 重装 |
+| `preview_list` | 无额外参数 | 当前 owner 的实际 previews |
+| `preview_read` | `draft_id` | 原草稿的当前预览与 revision |
+| `preview_prepare` | `owner_request: AppPreviewRequest` | snapshot/live、实际 revision、隔离 runtime |
+| `preview_end` | `owner_request:{draftId,expectedRevision}` | 只结束该原预览，保留 Task 和开发材料 |
+| `runtime_read` | `installation_id`、可选 `entrypoint_id` | 精确实例入口的当前运行状态 |
+| `runtime_start` | `installation_id` | 原执行 owner 当前再审批后的实际启动结果 |
+| `runtime_stop` | `installation_id` | 原执行 owner 当前再审批后的实际停止结果 |
+| `runtime_enroll` | `owner_request:{prepareRef,installationId,terminalId,endpoint:{port,identityPath},startupPolicy}` | 原真实已接纳命令的固定 native 执行合同 |
+| `development_enroll` | `owner_request:{prepareRef,draft,terminalId,endpoint:{port,identityPath}}` | 原授权可变源码的 development-only 合同，只用于 live 预览 |
+| `docker_prepare` | `owner_request: DockerPrepareEnrollmentInput` | 私有短期 CID/env 文件与实际 create 命令，不执行 Docker 命令 |
+| `docker_enroll` | `owner_request:{enrollmentRef,terminalId}` | 真实 daemon/CID/RepoDigest/挂载/端口执行合同，不以 CLI 退出代替健康 |
+| `release_history` | `installation_id` | 保存材料历史，不假称数据备份 |
+| `export_release` | `owner_request: AppReleaseExportRequest`；可另给顶层 `export_file_ref` 与 `expected_absent:true` 或 `expected_etag` | exportRef、archiveDigest、releaseDigest、实际 files/size；显式导出时 archiveFile 包含真实 ZIP fileRef/sha256/size/etag/replayed，不上传 |
+| `distribution_prepare` | `owner_request: AppDistributionPrepareRequest`（exportRef、registryRepoId、source、metadata） | 从真实 export 与 capability 中的目录目标生成三文件草稿，未上传/未提交 |
+
+例如能力调用为 `AppManage({action:'authoring_capabilities'})`。读草稿使用 `action:'read_draft'` 与返回的授权根对应的 `file_ref`；发布准备/提交分别使用 `release_request`，预览/运行纳管/导出使用 `owner_request`。这些包络不是互换字段，原工具及内部 owner 仍逐个严格核验完整 DTO。
+
+`prepare_release` 的 AppReleasePrepareRequest 包含 `mutationId`、已授权 `materialRoot: FileResourceRef`、`manifestPath`、可选 expectedReleaseDigest、`target:{appId,installationId,deviceId,sourceId}`。FileResourceRef 的 schemaVersion/instanceId/agentId/rootId/path 来自真实 fileRoots 与本次材料；path 是授权根内相对路径，不能复制别的宿主/Agent/root。首次个人 sourceId 为服务约定的 `user-managed`，不能用名字冒充目录身份。
+
+`commit_release` 使用原 prepareRef、expectedRevision（首次为 none，更新取原安装修订）、稳定 submissionId、完整 material（已解析的 ApplicationInstallationRequest）。登记失败先用 lookup_release_submission 查同安装同提交，不重新复制/启动软件。只读动作不触发修改审批；修改动作继续沿原工具审批和最终材料/调用身份复验。调用取消的短授权不保存为长期运行权限，已接纳的后台工作与 owned 临时预览补偿分别按其原 owner 管理。
+
+`AppDraftRef` 文件有 `schemaVersion:1`、稳定 draftId/appId、实际授权 `workdir`、绝对 planPath、真实 `source:{agentId,sessionId}`，可选 targetInstallationId/baselineReleaseDigest。文件引用从当前请求或授权读取工具取得。preview_prepare 用原 draft、mode、expectedRevision，snapshot 还给 release；结束只传原 draftId/revision，不能猜最近草稿或 borrowed 正式作用域。
+
+release 采用 `schemaVersion:1` / `canonicalization: app-release-c14n-v1`，包括 definition、delivery、files、source、supportedPlatforms、requiredCapabilities。files 的 role 为 definition/ui/runtime/dependency/documentation/license/evidence/data-contract；路径为包内规范 POSIX。definition 文件必须与 manifest.definition 一致。`app-release.json` 本身不放入 files，不能让摘要自引用。
+
+web-bundle.delivery.entrypoints 固定 `{entrypointId,path,spaFallback?}`；native-app 保存 runtimeInstructionsPath；docker-app 同时必填 imageRefs，逐项固定显式注册表/repository@sha256，不附登录凭据；实际仍由原容器 owner 拉取、执行和身份核验。缺容器环境或 adapter 时明确不可用。平台不解释说明为命令 DSL。source 是实际 Git 完整 commit 或工作树内容 sha256；supportedPlatforms 为 darwin/win32/linux/web。最低客户端是 minimumClientVersion，实际能力仍从握手确认。
+
+数据合同声明 formatVersion、readableVersions、writableVersions、有限 files key/path/maxBytes/contentType 和 uninstallRetention: retain。备份/迁移/恢复说明引用必须在 payload 白名单中；说明不授权自动执行，安装历史不代表真实数据备份。
+
+动态 Node 示例的 `/.desirecore-app-identity` 返回当前 TaskHost 注入的 proof/releaseDigest/scopeId/runtimeGeneration；proof 仅用于本次运行身份握手，不当应用 API token，不写日志。`AppManage.runtime_enroll` 使用已 prepare 的材料、installationId、真实 terminalId、endpoint.port/identityPath 与 startupPolicy。服务固定原执行合同后，原 Bash 显式停原命令，正式 commit 后由原 owner 启动新代际再核验。具体环境、执行审批和数据根均由实际 owner 决定。
+
+原执行命令的初始默认端口写成 `PORT="${PORT:-32000}" node runtime/server.mjs`，其中默认端口需实际可用。重启仍执行原真实 argv，Harness 注入的 preview PORT 不能被写死赋值盖掉。若应用后端需要数据，APP_DATA_DIR 也用已授权 seed 根作为初次默认，后续严格使用 owner 注入的独立根；不可将 seed/candidate 数据自动迁入正式实例。
+
+Docker prepare 的 owner_request 为 `{prepareRef,installationId,endpoint:{port,containerPort,identityPath},startupPolicy}`，可提议清单内 imageRef、容器 commandArgs/entrypoint、materialMountPath/dataMountPath；这些不是执行授权。使用返回的实际 command/cwd 沿原获审批 Bash/TaskHost 执行，拿真实 terminalId 与 enrollmentRef 用 docker_enroll 登记。当前 adapter 只接本地 Linux daemon 上该已核验的固定单容器形态；其他环境/挂载/服务编排保持原 owner 并报告原因，不自动安装 Docker、pull 镜像或修改用户容器。RepoDigest 与 Image ID 分别验证；冷重连核读真实 StartedAt，CID 不存在或结果 unknown 时不补建第二实例。
+
+## 平台 HTTP 管理消费者
+
+HTTP 接口保留给平台 UI 或具有合法管理凭据的消费者，普通 HttpRequest 不自动注入实例凭据。Agent 缺少对应原工具能力时说明不可用，不读取实例 token、不改 Origin 绕过 401，也不把凭据交网页。HTTP 返回包络与原 AppManage 结果各按实际合同读取。
+
+| 平台接口 | 用途 |
+|---|---|
+| `GET /api/apps/capabilities`、`POST /api/apps/authoring/drafts/read` | 平台能力与草稿读取 |
+| `POST /api/apps/releases/prepare`、`commit` | 固定材料与个人发布 |
+| `POST /api/apps/authoring/previews`、`:draftId/end` | 平台预览和结束 |
+| `POST /api/apps/runtime/contracts`、`development-contracts` | 平台 native/源码纳管 |
+| `POST /api/apps/runtime/docker/enrollments/prepare`、`enroll` | 平台 Docker 纳管 |
+| `POST /api/apps/runtime/:installationId/start`、`stop` | 平台正式启动/停止 |
+| `POST /api/apps/releases/export`、export 返回的 `downloadPath` | 生成归档和下载原始 ZIP 字节 |
+| `POST /api/apps/distribution/prepare` | 读取真实 exportRef 生成 Registry 三文件，未上传/未提交 |
+
+downloadPath 仍是平台管理下载路径，不授予网页或普通 HTTP 工具访问。Agent 需要实际 ZIP 时，在 export_release 顶层另给 export_file_ref：使用当前 Agent 原写权限内的 FileResourceRef 目标，path 为该根内相对路径；不能把服务 exports 私有目录挂成工作根。首次给 expected_absent:true，覆盖已有文件给原 expected_etag，两者不能同时提供。返回 archiveFile={fileRef,sha256,size,etag,replayed}，sha256/size 必须等于 export 的 archiveDigest/size；这才是可交原授权上传工具的实际文件。只读 fileRoots 不授写权限。响应丢失保持相同目标/条件/完整正文，已有同一固定字节可重放，其他内容必须按实际 ETag 决定，不能盲覆盖。
+
+目录草稿用原 AppManage.distribution_prepare，完整 AppDistributionPrepareRequest 放在 owner_request；registryRepoId 从 authoring_capabilities.registryTargetIds 选本次真实目标，不自报 sourceId 或构造连接。source 指向用户已实际上传并核验的不可变来源，sha256 等于 archiveDigest。返回 draft 三文件及 mapping/facts；upload 仍为 unverified，catalog 仍为 not-submitted，sourceAcl 仍为 source-admin-managed。写入目录仓库、提交 PR、目录准入和第二用户获取各由原工具取得实际回执；没有目标或来源连接时说明不可用。
+
+## 网页协作合同
+
+网页工作查询使用原 `{agentId,clientRequestId}`，SDK 不猜最近的 Agent。controlWork 当前只允许原 snapshot.availableActions 中的 abort。readWork.resources 的 `{locator}` 由实际 Run/Task 成果 owner 返回，`openResource({locator})` 回 navigation-requested 不保证文件正文已打开；不要把调用者任意 FileRef、Task ID 或 URL 变成果授权。
+
+设备视图偏好需 manifest.viewStateContract `{schemaVersion:1,keys,maxBytes,formatVersion?}` 与用户 saveViewState grant。connect.viewStates 为 array；device 项带 revision，deviceViewState 为 available（formatVersion/maxBytes）或 unavailable（reason）。默认 memory；显式 device 请求包含 schemaVersion/key/state/persistence/expectedRevision/mutationId，保持同正文同 ID 重试。设备偏好与业务数据、跨设备同步和数据备份是不同事实，preview 不借用正式 device 项。
+
+Web 最终接纳沿可信聊天传输。实际部署需 owner 提供 TLS/domain/DNS/authority port，可信 shell 取得 web-host ticket 并显式 bootstrapSdk；页面不持平台 token，不伪造 native physical intent，不选择管理上游。未支持的 navigate、未配置的 Web 来源或未授权能力分别说明实际 reason。
+
+长期 Web 呈现通过宿主 SDK 的有限同 session 续期维持。SDK connect 先确认原 parent 的当前呈现，再使用同应用来源的空 POST keepalive；它不执行业务命令、不扩权，不为已换版、已撤销或失效的页面延长会话。不要自行复制 ticket、cookie 或平台凭据来修复过期页。

skills/app-developer/references/distribution.zh-CN.md

@@ -0,0 +1,15 @@
+# 固定应用版本分发
+
+1. 确认用户要分发的精确版本、真实目标仓库/Registry、公共或私有范围、实际登录连接和材料许可。生成文件、个人发布或已有预览都不是上传授权；既有会话中的明确分发授权直接沿用。
+2. 用原 AppManage 的 export_release 动作，从 prepareRef，或 installationId + expectedRevision 导出；完整 AppReleaseExportRequest 放在 owner_request。`paths` 必须显式覆盖全部 payload + app-release.json；不包含服务物化 descriptor、owner 标记、个人数据和秘密。需要实际 ZIP 时，另在顶层给 export_file_ref（当前 Agent 原写权限目录的目标 FileResourceRef）与 expected_absent:true 或原 expected_etag；不能同时给两个条件或覆盖未知文件。核验响应的 files/size 和 archiveFile 的实际 fileRef/sha256/size/etag/replayed，sha256/size 必须等于 export 的 archiveDigest/size。读能力返回的 fileRoots 不授写权限；响应丢失保持同一目标、条件与完整正文恢复。downloadPath 是平台管理消费者路径，普通 HttpRequest 不自动注入凭据。
+3. 将真实 archiveFile.fileRef 交原实际授权上传工具；GitHub Release 上传此 ZIP 后，核读真实下载地址、固定 commit 和原始字节摘要；Gitea 私有仓库可提交 `releases/<version>.zip`，取得完整 commit 与该路径。可变 tag/latest 只作展示，必须解析到固定引用。没有真实来源回执就报告“制品已生成，尚未上传”。
+4. 使用原 AppManage 的 distribution_prepare 动作，owner_request 为 AppDistributionPrepareRequest：`exportRef`、从 authoring_capabilities.registryTargetIds 选择的真实 registryRepoId、`source:{kind:'release'|'git',url,ref,sha256,path?}` 和实际 metadata。目录目标列表是配置事实，不授予源端上传权限；普通模型不读取实例 token 或改 Origin 绕过认证。git 必须给固定包路径，sha256 必须等于导出 archiveDigest。产品 ID/名称/版本/入口不由 metadata 另填。
+5. metadata 包含 author/description/tags/category/license/redistribution/availability/requiredClientVersion，以及实际维护者、品牌和复核材料。证据不足保留 listing-only；不要填不存在的审核者、认证、发布时间或平台验收。已复核的许可证路径应来自同一 release 的 license role 文件。
+6. 返回的是 `entries/<id>/manifest.json`、`catalog-metadata.v1.json`、`install.md` 内容和摘要。mapping 关联目标 sourceId、逻辑 ID、releaseDigest 与 archiveDigest，descriptor 安装时按真实来源物化。将三文件写入实际授权的目录仓库后审阅 diff，通过其原治理提交 PR；不能自动合并或说目录已开放。
+7. 查询真实目录可获取状态与目标客户端握手，再由第二用户/设备沿原 acquisition/app-install-manager 路径安装并核验。两来源同名不共享实例或数据；目录更新仅给更新候选，不改原安装快照。
+
+候选 Registry 4.3 Schema 与客户端 reader 必须先分别 review；正式 Registry seed 只指已合入的受审提交。候选 reader 仅在明确受信的非官方测试来源开放，正式条目等待客户端能力发行，不能借 10.0.180 字符串跳过 app-authoring-v1。
+
+私有源使用 `access: private` 的真实 Registry 连接，只读登记端点、不转公开镜像；认证失败拒绝新获取。字段不是 ACL，GitHub/Gitea 管理员仍负责实际成员权限。平台团队成员移除不自动改变源端 ACL，不能宣称已撤销。已下载字节不能收回，本机数据不自动删除。
+
+离线可继续使用已核验的本地固定版本，远端依赖如实不可用；离线不能产生新的来源上传成功。目录撤回阻止新获取并保留理由，不自动卸载已安装应用。临时导出不修改当前个人发布，取消分发保留原工作台。