From cf381532297c1a9f81e6b83664671d94cf19a5b0 Mon Sep 17 00:00:00 2001 From: YiJie Date: Sat, 19 Sep 2026 23:02:06 +0800 Subject: [PATCH] docs: prepare agent trace 0.1.1 release --- AGENTS.md | 17 +++++++ README.md | 121 ++++++++++++++++++-------------------------- README.zh-Hans.md | 96 ++++++++++++++--------------------- cordisx.plugin.json | 2 +- package-lock.json | 4 +- package.json | 2 +- 6 files changed, 108 insertions(+), 134 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index c7d4d70..f37a5d4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,3 +9,20 @@ - Do not add compatibility shims during the current design-validation phase. - The package currently keeps the existing product identifiers, but no API or configuration compatibility is implied by that naming. + +## Development and release + +- Requires Node.js 22 or newer. Install with `npm ci`. +- Run `npm run check`, `npm pack --dry-run`, and `git diff --check` before a + checkpoint commit. `npm run check` includes typecheck, build, tests, source + lint, format verification, and the package dry run. +- The public README is for installation and use. Keep architecture checkpoints, + source layout, build details, test commands, contribution steps, and release + operations here or in an indexed maintainer guide. +- Releases use a GitHub prerelease, not npm. Build the exact merged main commit, + create the private package tarball with `npm pack`, publish it as + `cordisx-agent-trace-showcase-.tgz` with `SHA256SUMS`, and verify both + assets by downloading and hashing them. Do not publish until the package + descriptor, package version, README version, tag, and archive all agree. +- Marketplace artifact URLs and SHA-256 digests are updated by the Marketplace + owner after the release. Do not copy an older Official or Certified record. diff --git a/README.md b/README.md index 7199255..b62de29 100644 --- a/README.md +++ b/README.md @@ -1,91 +1,66 @@ # CordisX Agent Trace Showcase -Agent Trace Showcase is an independent, read-only CordisX plugin repository. -It owns the Timeline business projection and body composition; the Host owns -session chrome, route behavior, shared controls, accessibility, permission UI, -and native lifecycle authority. +Agent Trace Showcase adds a read-only Timeline for one Agent session. It is +useful when you need to inspect durable session events, lifecycle transitions, +tool activity, approvals, and the exact entity definition recorded with the +session without giving the plugin control over that session. -The Timeline consumes the public Agent/Session Runtime contract. It reports an -honest empty unavailable state whenever the Host does not provide the -permission-scoped Session service. +## Install -## API checkpoint +Plugin ID: `agent-trace-showcase`. Current release: `0.1.1`. -The Agent/Session Runtime ownership model is: +The CordisX Community Marketplace feed is not a trust root and must already be +configured and enabled before `--source` can select it: -- a Host-private Session authority owns one append-only `SessionEvent` log; -- the public plugin seam is a permission-scoped, read-only `ctx.sessions` - service for immutable Session snapshots and post-commit event subscription; -- `ctx.agents` owns create/resume/get and returns public live Agent handles; -- `ctx.approvals` owns approval requests and decisions; -- environment composition and transport bindings remain Host-private and do - not change plugin contracts, permissions, or Session facts. - -The contracts are `@cordisx/protocol/sessions/v1` and the additive -`EntityDefinitionBoundSessionEvent` from `@cordisx/protocol/entities/v1` at -Protocol main commit `c96c290697f9e802a68c6d3bb094fd27d8d00d1e`. -The Timeline reads a fixed Session snapshot, pages through its immutable -watermark, then follows the atomic replay/live subscription. Subscription -termination clears the view and reports the terminal code. - -For an entity-backed Session, `entity/definition-bound` is the durable source -of the exact historical definition identity, digest, and definition bytes. -The Timeline projects that persisted binding and never queries `ctx.entities` -or relabels prior Session history from the latest local entity revision. - -The plugin consumes no alternate event service, Host-private import, unsafe -cast, raw bridge, adapter, or second ledger. - -The v5 runtime manifest declares optional `sessions.get`, `sessions.read`, and -`sessions.subscribe` capabilities. Each is bound to the active -`session.timeline` route's exact `:sessionId`; no empty or wildcard scope is -accepted. - -## Host-owned UI +```sh +FEED_URL=https://raw.githubusercontent.com/cordisx/marketplace/main/marketplace.json +npx cordisx@beta source add "$FEED_URL" --yes +npx cordisx@beta plugin install agent-trace-showcase --source "$FEED_URL" --version 0.1.1 +``` -The plugin registers structured route, page, and session-header-action -descriptors. Its React contribution renders only the Timeline business body -using `cordisx/ui`. It does not import TDesign, copy Host chrome or tabs, query -Host-private selectors, or mutate Host DOM. +Skip `source add` when that exact feed is already enabled. For another profile, +add the same `--profile ` argument to both commands. `--yes` confirms +the source change only; it does not approve plugin permissions. The install +command becomes available after the Marketplace entry lists the `0.1.1` +artifact. Until then, download the release archive and `SHA256SUMS` from the +[GitHub release](https://github.com/cordisx/plugin-agent-trace/releases/tag/v0.1.1). -## Session facts +## Use -Agent Trace reads only `SessionEvent` facts from `ctx.sessions`. Immutable -history and post-commit updates are two views of the same Session authority. -If the service, exact route permission, Session, read, or subscription is -unavailable, the Timeline shows no rows and never falls back to another source. +Open an Agent session in CordisX, then use the session Timeline action. The page +shows the immutable history available for the active `session.timeline` route +and follows new committed events. It never creates, edits, resumes, or cancels +Agent work. ## Configuration -| Setting | Default | Values | Meaning | -| -------------------- | ------- | ------ | ------------------------------------------------- | -| `timelineWindowSize` | `500` | 50-500 | Bound the in-memory and rendered Timeline window. | +`timelineWindowSize` limits the in-memory and rendered event window. The default +is `500`; accepted values are `50` through `500`. Configuration applies after a +plugin restart. -Configuration applies on restart so the owning Cordis fiber replaces page -state cleanly. Page unmount and plugin deactivation own their disposers. +## Permissions and limits -## Development and packaging +The plugin requests optional, route-scoped `sessions.get`, `sessions.read`, and +`sessions.subscribe` access for the exact active session ID. Data is retained +only for the current runtime and is not transferred externally. -The plugin-owned brand artwork is `assets/agent-trace.png` (256 × 256). The -module exports the public `CordisXPluginBrandIcon` declaration as `icon`; Host -plugin lists render its inline PNG without a network request. Run -`npm run icon:generate` after replacing the asset; `npm run check` verifies that -the generated declaration still matches. The package includes both the source -PNG and its compiled declaration. Session actions keep their Host semantic icons. +If the Host service, exact route permission, session, read operation, or +subscription is unavailable, the Timeline stays empty and reports the +unavailable state. It does not fall back to another event source, query mutable +entity state, or reconstruct missing history. -Distribution remains source-based `explicit-local-v1` at the canonical GitHub -repository; this private package has no npm publication or release-tag workflow. -The tracked PNG can be referenced by a commit-pinned raw GitHub URL for catalogs. +## Troubleshooting -```sh -npm ci -npm run check -``` +- **Install cannot find version `0.1.1`:** confirm the Marketplace feed entry + has been updated with the release artifact; `--source` does not register or + repair a feed. +- **Timeline is empty:** open it from a concrete Agent session and review the + three session permissions in CordisX plugin settings. +- **Timeline stops updating:** reopen the session route. A terminal subscription + code is shown instead of silently switching data sources. + +## License -`npm run check` runs typecheck, build, focused tests, and -`npm pack --dry-run`. `cordisx.plugin.json` is the immutable package manifest. -The Protocol dependency is pinned to an exact remotely resolvable main commit. -The entity-backed Host runtime is formally available at CordisX main commit -`ff9cf8b1ba4e4caffa23abbd767dbba0b8884c8a`; Chatroom's entity-backed consumer -is at `dc1d672b93e6b6a3a29961561546957d66955a1a`. The package remains private -until real-App integration verification is complete. +See [LICENSE](LICENSE) and [legal](legal/) for the package and dependency terms. +Maintainer setup, checks, packaging, and release instructions are in +[AGENTS.md](AGENTS.md). diff --git a/README.zh-Hans.md b/README.zh-Hans.md index 6c71665..d1667ee 100644 --- a/README.zh-Hans.md +++ b/README.zh-Hans.md @@ -1,75 +1,57 @@ # CordisX Agent Trace Showcase -插件品牌图为 `assets/agent-trace.png`（256 × 256），通过公开的 -`CordisXPluginBrandIcon` 顶层 `icon` 导出供 Host 插件列表使用，运行时无需请求网络。 -替换图片后运行 `npm run icon:generate`；`npm run check` 会检查生成声明与 PNG -是否一致。包内同时保留原始 PNG 和编译后的声明，会话操作继续使用 Host 语义图标。 +Agent Trace Showcase 为单个 Agent 会话提供只读 Timeline。它适合查看持久化的 +会话事件、生命周期变化、工具活动、审批，以及会话记录的精确 Entity 定义；插件 +不会获得控制该会话的能力。 -分发方式保持为正式 GitHub 仓库上的 `explicit-local-v1` 源码安装；当前私有包没有 npm -发布或 release-tag 工作流。商店可引用固定 commit 的原始 PNG URL。 +## 安装 -Agent Trace Showcase 是独立、只读的 CordisX 插件仓库。插件只负责 Timeline -业务投影与正文组合；会话 chrome、路由行为、共享控件、无障碍、权限 UI 与 -native lifecycle authority 均由 Host 负责。 +插件 ID：`agent-trace-showcase`。当前版本：`0.1.1`。 -Timeline 只消费公开 Agent/Session Runtime 契约。Host 未提供受权限约束的 -Session 服务时，Timeline 会保持空数据并明确显示 unavailable。 +CordisX Community Marketplace feed 不是 trust root，且必须先配置并启用， +`--source` 才能选择它： -## API checkpoint - -Agent/Session Runtime 的 ownership model 如下： +```sh +FEED_URL=https://raw.githubusercontent.com/cordisx/marketplace/main/marketplace.json +npx cordisx@beta source add "$FEED_URL" --yes +npx cordisx@beta plugin install agent-trace-showcase --source "$FEED_URL" --version 0.1.1 +``` -- Host-private Session authority 唯一拥有 append-only `SessionEvent` log； -- 插件只通过受权限约束、只读的 `ctx.sessions` 获取不可变 Session snapshot - 与 post-commit event subscription； -- `ctx.agents` 负责 create/resume/get，并返回公开 live Agent handle； -- `ctx.approvals` 负责 approval request 与 decision； -- 环境组合和 transport binding 均为 Host-private，不改变插件契约、权限或 - Session 事实。 +若该 feed 已启用，可跳过 `source add`。使用其他 profile 时，两条命令都要添加 +相同的 `--profile `。`--yes` 只确认来源变更，不会批准插件权限。 +Marketplace 条目列出 `0.1.1` artifact 后，安装命令才可用；在此之前，可从 +[GitHub Release](https://github.com/cordisx/plugin-agent-trace/releases/tag/v0.1.1) +下载压缩包与 `SHA256SUMS`。 -正式契约是 Protocol main commit -`c96c290697f9e802a68c6d3bb094fd27d8d00d1e` 的 -`@cordisx/protocol/sessions/v1`，以及 -`@cordisx/protocol/entities/v1` 中增量定义的 -`EntityDefinitionBoundSessionEvent`。Timeline 先读取固定 Session snapshot， -分页读取 immutable watermark，再接续 atomic replay/live subscription；订阅 -终止时会清空视图并报告 terminal code。 +## 使用 -对 entity-backed Session，`entity/definition-bound` 是历史定义 identity、 -digest 与 definition bytes 的唯一持久事实。Timeline 只投影该 Session 事件中 -持久化的 binding，绝不查询 `ctx.entities`，也不按最新 local entity revision -重标历史。 +在 CordisX 中打开一个 Agent 会话，然后使用会话 Timeline 操作。页面读取当前 +`session.timeline` 路由允许访问的不可变历史，并跟随新提交的事件。它不会创建、 +修改、恢复或取消 Agent 工作。 -插件不消费替代 event service，也不使用 Host-private import、unsafe cast、 -raw bridge、额外 adapter 或第二 ledger。 +## 配置 -v5 runtime manifest 对 `sessions.get`、`sessions.read`、 -`sessions.subscribe` 分别声明 optional capability，并全部绑定到当前 -`session.timeline` 路由的精确 `:sessionId`；空 scope 和 wildcard 均不允许。 +`timelineWindowSize` 限制内存中和页面上保留的事件数量，默认值为 `500`，可选范围 +为 `50` 到 `500`。配置在插件重启后生效。 -## Host-owned UI +## 权限与限制 -插件注册结构化 route、page 与 session-header action 描述，并仅用 `cordisx/ui` -渲染 Timeline 业务正文。它不导入 TDesign，不复制 Host chrome/tab，不查询 -Host-private selector，也不修改 Host DOM。 +插件为当前路由中的精确 Session ID 请求可选的 `sessions.get`、`sessions.read` 和 +`sessions.subscribe` 权限。数据只在当前运行期内使用，不会传输到外部。 -## Session 事实 +Host 服务、精确路由权限、Session、读取或订阅不可用时，Timeline 会保持为空并 +显示不可用原因，不会切换到其他事件来源、查询可变 Entity 状态或补造缺失历史。 -Agent Trace 只读取 `ctx.sessions` 的 `SessionEvent` 事实。immutable history 与 -post-commit update 是同一 Session authority 的两个视图。service、精确路由 -权限、Session、read 或 subscription 任一不可用时都保持空数据，且不 -fallback 到其他来源。 +## 排错 -## 验证与打包 +- **找不到 `0.1.1`：**确认 Marketplace feed 已加入该版本 artifact；`--source` + 不会注册或修复 feed。 +- **Timeline 为空：**从具体 Agent 会话打开 Timeline，并在插件设置中检查三项 + Session 权限。 +- **Timeline 停止更新：**重新打开会话路由。插件会显示终止原因，不会静默切换 + 数据源。 -```sh -npm ci -npm run check -``` +## 许可证 -`npm run check` 包含 typecheck、build、focused tests 与 -`npm pack --dry-run`。Protocol dependency 精确 pin 到可从远端解析的 main -commit。entity-backed Host Runtime 已在 CordisX main commit -`ff9cf8b1ba4e4caffa23abbd767dbba0b8884c8a` 正式提供；Chatroom 的 entity-backed -消费已在 main commit `dc1d672b93e6b6a3a29961561546957d66955a1a` -落地。真实 App 集成验证闭合前，package 保持 private。 +包与依赖条款见 [LICENSE](LICENSE) 和 [legal](legal/)。维护者的环境、检查、打包与 +发布说明见 [AGENTS.md](AGENTS.md)。 diff --git a/cordisx.plugin.json b/cordisx.plugin.json index 4859bd4..75ca6a6 100644 --- a/cordisx.plugin.json +++ b/cordisx.plugin.json @@ -2,7 +2,7 @@ "$schema": "https://raw.githubusercontent.com/cordisx/cordisx-protocol/main/schemas/plugin-package.v4.schema.json", "schemaVersion": 4, "id": "agent-trace-showcase", - "version": "0.1.0", + "version": "0.1.1", "entry": "./dist/index.js", "readme": "./README.md", "canonicalSource": "https://github.com/cordisx/plugin-agent-trace", diff --git a/package-lock.json b/package-lock.json index 454cd34..fcde2e6 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@cordisx/agent-trace-showcase", - "version": "0.1.0", + "version": "0.1.1", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@cordisx/agent-trace-showcase", - "version": "0.1.0", + "version": "0.1.1", "license": "AGPL-3.0-or-later", "dependencies": { "@deepseek-ai/cordis": "4.0.1", diff --git a/package.json b/package.json index bcc1353..aa2b334 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@cordisx/agent-trace-showcase", - "version": "0.1.0", + "version": "0.1.1", "private": true, "description": "Read-only CordisX Agent Trace Timeline plugin", "license": "AGPL-3.0-or-later",