# 网页作品

`finctx artifacts` 用于发现公开组件资料、在本机构建作品、上传两个 ZIP、查看私有版本、取回源码以及明确发布或回滚。公开目录匿名读取，其余作者管理使用主站管理接口；均不使用数据接口地址 `FINCTX_BASE_URL`，也不另记一次数据调用。查看者运行作品时仍选择自己的 Key，按原数据 API 的权限和计量规则取数。

CLI `0.3.16` 使用官网固定工具包 `0.7.3`，生成运行 SDK `0.7.3` 的 QuickJS／Remote DOM 作品。作者程序在 QuickJS 中执行，可信查看器负责展示与取数。工具下载或本机检查未完成时，命令会停止；服务端另行检查源码和运行包。

## 先发现固定组件和版本资料

```bash
finctx artifacts widgets
finctx artifacts widget get --id finctx.table --version 1.2.0
finctx artifacts widget get --id finctx.kline --version 1.2.0
finctx artifacts widget get --id finctx.metric-card --version 1.2.0
finctx artifacts widget get --id finctx.security-selector --version 1.2.0
finctx artifacts widget get --id finctx.chart --version 1.2.0
```

这两个命令只做公开 GET，沿用 `--platform-origin` 的管理站点地址解析，但不读取或发送 Key、Cookie、网站 Session或本机持久凭据；不接受 `--key`。列表无分页，不加 `--limit`。未知组件或不支持版本保留服务器404及 `ARTIFACT_WIDGET_NOT_FOUND`，不自动换版本、重试或改用别的来源。

列表返回 `{items:[{id,version,title,summary,import_path}]}`。固定版本详情保留同五项，以及 `propsSchema`、`types`、`events`、`data_format`、`theme`、`licenses`、`examples`。`propsSchema` 是可序列化输入的 JSON Schema；函数签名和事件以 `types/events` 的固定说明为准，不能执行JSON中的函数字符串。每个示例为 `{title,source,sha256}`，其中 `source` 是官方 TSX 或 Vue SFC 原文，`sha256` 对应该原文准确UTF-8字节。

CLI按原JSON展示这些资料，不执行示例、不安装或抓取 `import_path`。生成页面时先核对具体版本的类型、数据口径、许可和示例，再用平台已提供的固定工具构建；读取目录本身不证明相应组件已经部署或可由当前工具导入。`0.6.1` 工具把五种组件的 React／Vue 入口解析到受限运行时适配，公开 props 与固定组件身份为 `1.2.0`。K线使用平台提供的 KLineChart 引擎，基础图为原生 SVG；宿主组件实现不进入作者程序。

`1.2.0` 详情保留 React 的 `import_path: finctx-artifacts/widgets/<leaf>`；Vue 必须使用详情中明确列出的 `finctx-artifacts/vue/widgets/<leaf>`，其中 leaf 为 `kline/table/metric-card/security-selector/chart`。两种入口沿用相同数据与 `on*` 函数 props，Vue 示例用 `v-bind` 传入，不另加 `v-model` 或另一套 emits。新包仅声明实际使用的 `1.2.0` 组件。历史目录资料保留原件，不构成新包的旧版本兼容入口。

组件只消费页面提供的数据与状态并发送交互事件，不接Key、不自行请求数据或补历史。表格的排序／筛选／分页由页面或原接口处理，不能把当前一页排序称作全量排序。K线输入固定为UTC毫秒；源时间、数值精度、时区和周期由页面按真实API明确适配，不把缺失OHLC或成交量补零。

指标卡显示页面已经格式化的精确文本，不自行计算涨跌。证券选择器保留页面受控值；选择不在当前候选页时显示说明，不擅自选首项或清空；查询只由用户明确动作触发，非全空白query原样交给页面，Widget不拥有证券搜索客户端。基础图表使用有序分类和有限数值，null表示缺口；不为复用K线引擎捏造时间或OHLC，不自动采样、截断、取数或新增资源上限。字段与回调以固定版本目录的实际类型为准。

## 构建并打包

```bash
finctx artifacts pack --source-dir ./作品源码 --config artifact.json --out ./本次打包结果
# build 是同一构建与打包流程：
finctx artifacts build --source-dir ./作品源码 --config artifact.json --out ./另一新目录
```

`--source-dir` 明确选择整个源码目录；`--config` 为该目录内的配置文件，相对路径以源码目录为准；`--out` 必须是源码目录之外尚不存在的新目录，父目录须已存在。配置保留必填的 `title`、`mode`（`static` 或 `dynamic`）、`framework`（`react` 或 `vue`）和项目内源入口 `entry`，不自动补标题或猜测模式。

Vue 的入口可为普通 `.vue` 单文件组件（SFC），或默认导出组件的 `.ts/.js`。SFC 模板和 JS／TS script 或 script setup 在本机预编译，沿受控项目内源码引用，不在运行时编译模板。仅使用已验收的元素和样式属性；作者 CSS、SFC style、额外资源、Vue JSX、预处理器、自定义 block、Custom Element／Vapor、SSR／Nuxt不在当前支持范围，遇到时明确停止构建，不静默丢弃。作者无需新增构建配置，服务器不执行作者构建。

工具读取实际文件，输出 `sourceFiles` 和 `excludedFiles`（路径与原因），供作者检查。`.git`、`node_modules`、已知凭据文件与构建输出不上传；危险链接、路径越界和歧义名称明确拒绝，不偷偷改名。不要把凭据或私人数据放进作者明确发布的静态内容。依赖与锁文件用于追踪，不能证明运行产物必然来自该源码。

`pack` 使用本机已安装的 Chrome、Chromium 或 Edge 在隔离查看器中运行刚编译的作品。首屏组件被拒绝时，标准错误包含组件、超限数量或缺失参数，且不写出上传包。修正后重新打包。首屏未覆盖的数据和交互在私有预览中以作者身份复测，确认通过后再交付预览链接。

输出目录包含：

- `source.zip`：作者实际选择的源码。
- `runtime.zip`：唯一作者文本 `program.js`、构建生成的 `manifest.json` 和 `THIRD_PARTY_NOTICES.txt`，没有 HTML 运行入口。
- `upload.json`：两个 ZIP 的原字节摘要、大小与源码及运行文件清单。

CLI 只从固定 `https://finctx.cn/sdk/artifacts/0.6.1/finctx-artifacts-0.6.1.tgz` 与其 `.sha256` 读取工具，不提供版本／URL 选择或失败换源。核对摘要后安装工具，用随包 `scripts/pack-artifact.mjs` 构建，不从 npm 获取同名工具包。CLI 核对摘要后，在 `~/.finctx/private/` 的独立目录安装工具自身锁定的依赖；随包 `npm-shrinkwrap.json` 原字节复制为 `package-lock.json`，兼容 npm11/12，执行 `npm ci --ignore-scripts --omit=dev`。不安装作者项目，不加载作者 `.npmrc`、npm 脚本或 Node 注入环境。安装依赖仍需要访问依赖注册表，不宣称整个构建过程离线。成功清理工具暂存；失败报告具体暂存位置。

新包的运行清单固定为 `schema_version: 2`、`execution_format: "quickjs-remotedom-v1"`、`entry: "program.js"`、`sdk_version: "0.6.1"`、`protocol_version: 1`；外层 `upload.json` 仍为 schema 1。`files` 恰记录程序和许可证的原字节摘要／长度，`runtime_sha256` 标识程序原字节而非 ZIP。实际保留的组件记为 `1.2.0`，依赖按 bundle 真正保留的模块记录，平台 guest、WASM 和宿主组件不混入作者依赖。未知格式、旧 HTML 包或旧 SDK 不自动转换，也不生成另一条运行方式。

## 创建、上传与固化分开执行

```bash
finctx artifacts create --title "价格比较" --mode dynamic
finctx artifacts upload --artifact-id <作品UUID> --package-dir ./本次打包结果
finctx artifacts status --upload-id <上传UUID>
finctx artifacts finalize --upload-id <上传UUID>
```

上传前向标准错误输出实际源码文件集合，核对归档和逐文件摘要，再执行版本化本机检查。`upload.json` 以严格校验后保存的原字节作为 `application/json` 正文发送，`manifest_sha256` 对应同一原件；不重新序列化成另一份等价 JSON。两个 ZIP 也发送同一快照，扫描后磁盘文件变化不会替换该次上传内容。未明确通过不会创建上传或发送 ZIP；没有跳过检查的命令行开关。输出 JSON 保留在标准输出。需要补传时沿用原打包目录和上传编号：

```bash
finctx artifacts upload --upload-id <原上传UUID> --package-dir ./原打包结果
```

只上传不等于公开；`finalize` 将已校验包固化为作者私有版本，其返回的作者预览链接仍要求原主站作者登录。服务端扫描状态、协议和上线状态决定版本何时可预览或公开，不因返回一个链接就声称验收通过。版本资料使用固定 `execution_format: "quickjs-remotedom-v1"` 与服务端派生的站内 `program_url`，程序 GET 为完整原字节 `application/octet-stream` 下载附件。可信查看器先核对版本、地址、摘要与 UTF-8，再交给固定 QuickJS；直接程序地址不是原生脚本或 iframe 执行入口。远程 MCP 不能读取本机目录或替本机 CLI 发送文件。

本机检查使用与后端同源的规则和扫描器 `1.2.0`，送检源码的全部普通成员及 `runtime/program.js`；Vue SFC 的 script、style及模板表达式均按对应语法检查，无法完整检查的语法返回 error，不当作不适用后放行。运行清单和许可证仍完整核对 ZIP 与摘要，但不计为文本检查。敏感词尚无词表时报告 `not_configured`，不冒称敏感词检查通过。发现只包含规则、相对路径和行列，不输出匹配的代码、URL或凭据。它是有限文本检查，不证明任意程序没有隐藏行为。

本机未通过时，标准错误输出的 `local_scan` 报告供作者查看。`rejected` 表示已确认命中，即使其它内容未能完整检查也保留这个结论；`error` 表示没有已确认命中但检查未完成。`files_checked` 是已尝试检查的适用文件数，不承诺拒绝结果已完整检查所有内容。

云端的版本扫描报告由作者 Key 查询：

```bash
finctx artifacts status --artifact-id <作品UUID> --revision-id <版本UUID>
```

版本编号与 `--upload-id` 两种输入互斥。未完成、拒绝或没有报告都不能当作通过；服务端拒绝公开时保留原错误码、说明与请求编号。

## 在作品中持续接收事件和消息

`finctx-artifacts/sdk` 的 `createArtifactClient()` 在隔离作品中提供 `request()`、`subscribe()` 和 `connectWebSocket()`。CLI 负责打包与作者管理；后两个方法由浏览器 SDK 经可信查看器调用，不是 CLI 子命令，也不让作者代码直接访问网络或取得 Key。平台运行能力不可用时会明确报告原因，不切回作者原生执行。

`await client.subscribe({api_id, path, query?, headers?}, {signal?})` 和 `await client.connectWebSocket({api_id, path, query?}, {signal?})` 均返回判别联合：

- `ok: false`：`response` 为原接口的 `HttpResult`，保留状态、头、完整有界正文及请求编号。网关 `401` 不表示网站 Session 已退出。
- `ok: true`：保留 `status`、`headers`、`request_id`，并提供 `close()`、`closed`；SSE 使用 `events`，WS 使用 `messages`，均按 `for await` 顺序消费。页面卸载、切换筛选或不再需要时，调用 `close()`、取消传入的 `AbortSignal`，或在销毁整个客户端时调用 `client.dispose()`。

以下 `apiId` 必须来自已发现的实际 SSE 产品，`snapshotRevision` 必须来自页面先前以相同筛选读取的 HTTP 基线；`onEvent` 和 `onHttpFailure` 是页面自己的展示逻辑：

```ts
const controller = new AbortController();
const stream = await client.subscribe({
  api_id: apiId,
  path: "/v1/tracer/newsflash/events",
  query: new URLSearchParams({ baseline_revision: String(snapshotRevision) }).toString(),
}, { signal: controller.signal });
if (!stream.ok) {
  onHttpFailure(stream.response);
} else {
  try {
    for await (const event of stream.events) onEvent(event.event, event.data);
  } finally {
    stream.close();
  }
}
```

SSE 项为 `{event, data, id?, retry?}`；`data` 是原业务文本，按原接口需要解析 JSON。`id` 和十进制毫秒字符串 `retry` 仅在上游实际声明时出现，SDK 不据此自动重连。两类 Tracer 的业务 `revision` 不是 SSE `id`；收到 `refresh` 后先按相同筛选重新读取 HTTP 基线，再由页面明确开始新订阅。媒体路径为 `/v1/tracer/library/media/events`，还须保留原接口的 `platform` 与实际筛选；不要套用快讯的业务字段。

WS 的 `messages` 项为 `{type: "text", data: string}` 或 `{type: "binary", data: ArrayBuffer}`，不把二进制转换成 Base64。成功建连后，按所选产品契约 `await stream.send(stringOrArrayBuffer)`；一次只允许一个尚未完成的发送，并发发送明确报忙。完成只表示上游有界转发接受了消息，不表示业务执行成功。快讯 `/api/wd/ws/newsflash` 的订阅仍使用原业务 `cursor/limit/keyword/min_importance`：`limit` 省略或 `null` 保留历史全集，`0` 不补历史，`1..50` 限制补取，不擅自补默认值。

两类连接均不自动重连或重复发送。`closed` 总是 resolve，`reason` 为 `eof/cancelled/closed/error`；WS 关闭还可能保留原 `code/message/was_clean/source`，错误可能附安全 `error`。异步迭代及建立连接仍可能抛错，页面应展示实际原因并结束消费，不把本地取消或业务拒绝改成重新登录或自动重试。

## 查看版本和维护源码

```bash
finctx artifacts list --limit 20
finctx artifacts get --artifact-id <作品UUID>
finctx artifacts revisions --artifact-id <作品UUID> --limit 20
finctx artifacts source pull --artifact-id <作品UUID> --revision-id <版本UUID> --out ./新源码目录
```

列表返回服务端的 `next_cursor`；继续分页传 `--cursor`，不把一页结果当成全部。`get` 返回的 `publication_generation` 是本次读取时的发布状态号。源码下载通过作者 Key 鉴权，校验原 ZIP 摘要后仅恢复到新目录，不执行安装或源码；已有目录不会覆盖。路径无法在当前文件系统安全恢复时明确失败，不改写文件名。

## 显式发布或回滚

```bash
finctx artifacts publish --artifact-id <作品UUID> --revision-id <新版本UUID> \
  --expected-generation <读取时状态号> --idempotency-key <本次固定操作编号> --summary "更新说明"
finctx artifacts rollback --artifact-id <作品UUID> --revision-id <历史版本UUID> \
  --expected-generation <读取时状态号> --idempotency-key <另一次固定操作编号> --summary "回滚说明"
```

两个命令都要求显式状态号和幂等键；CLI 不会先读取一个新状态号再自动覆盖别人刚发布的版本。并发冲突时重新检查远端作品与本次改动，再决定下一步。网络失败造成结果未知时保存原作品、版本、操作内容和幂等键，先查询作品或版本状态；需要重放同一操作时沿用同一内容与幂等键。CLI 不自动重发发布，也不把发布失败改成回滚。

## 作者认证与测试地址

管理命令复用已配置的 FinCtx API Key，通过 `Authorization: Bearer` 发送；不发送 Cookie，不伪造浏览器 Origin，不把 Key 写进 ZIP、URL或输出。每次管理请求都由服务端重新校验凭证、作者归属和作品状态。

默认地址为 `https://finctx.cn`。必要时使用仅当次生效的 `--platform-origin <HTTPS origin>`；本机测试只允许明确的 `http://127.0.0.1:<port>` 或 `http://localhost:<port>`。拒绝凭据、路径、查询、片段和重定向，不新增环境变量或持久配置。普通本地页面不能靠这个参数共享主站 host-only Cookie；动态预览使用主站作者链接或完整同源测试站点，不复制网站 Cookie/Key 给作者代码。


## 标准界面与作者升级

新建作品使用工具包0.7.0与组件1.2.0。证券选择器通过onRefresh、busy（search或refresh）、status与error负责搜索、清空、刷新、候选面板和反馈排布；作品只传数据及回调，不再另写“当前选择/未选择”、刷新按钮或重复状态段落。行情刷新与股票查询是不同的业务请求，应各自绑定真实接口，不能把搜索当刷新。请求期间保留原结果，不清空页面，不自动重复取数。

五种组件提供完整蓝灰样式、深浅主题、44px操作区、轻蓝键盘焦点和移动布局；appearance允许accent/background/text/border的#RRGGBB颜色与0..24px圆角，除此以外不接收任意CSS或URL。指标卡每行两张、等高；图表随内容撑开，仅表格/密集图形必要时横向滚动。平台已经显示作品名称，内容不要再显示同名标题。

账号菜单“我的作品”进入/app/artifacts，列出本人作品。公开浏览统一/artifacts/<作品ID>/，不包含版本号；历史预览仅作者可见。每个作品只有一个当前公开版本，旧公开路径返回当前作品入口，程序和数据也核验当前指针。

组件更新不直接修改已有作品。作者访问详情后确认“升级组件”，服务端复制原源码与程序，生成绑定新组件的私有预览并重新安全检查；作者检查预览后手动公开。升级不会改变原公开状态。旧作品自己写的业务布局仍属于原程序；标准组件升级不会擅自重写业务代码，新页面必须使用完整标准接口。
