From be42a3c01eb723cae46106051936260cb248bfd0 Mon Sep 17 00:00:00 2001 From: veil-chow-fyaic <247294299+veil-chow-fyaic@users.noreply.github.com> Date: Mon, 7 Sep 2026 19:30:48 +0800 Subject: [PATCH] docs: lead with user outcomes and clarify first-use paths --- README.md | 115 ++++++++++-------- README.zh-CN.md | 94 ++++++++------ .../community-followup-2026-09-07.md | 54 ++++++++ 3 files changed, 173 insertions(+), 90 deletions(-) diff --git a/README.md b/README.md index 21dcb80..0269afc 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,6 @@

CI Apache 2.0 - Node 22+ Experimental alpha

@@ -19,20 +18,23 @@ 简体中文

-One conversation changes the API. Another is still building against the old contract. -You shouldn't have to notice, switch chats, and explain the change again. -You don't need two different products: two sessions of the same agent can collaborate. +You approved a decision in one chat. Another chat is still working from the old +version. ThreadMesh helps related agent sessions share useful changes without +making you explain them again—even when both sessions use the same product. -**You choose which sessions join. The models choose when a message is useful.** -The workspace supplies discovery, advisory messages, a persistent inbox and portable -checkpoints—not a new model or shared chat history. The optional Codex desktop -skill instead uses **Codex's native task tools**; it does not add that transport. +**You choose the collaborators. The models decide what is worth sharing.** -**Doesn't Codex already do this? Yes, on the tested host.** If its native task -tools meet your needs, use them directly. The skill adds reusable collaboration -guidance; the workspace adds coordination for supported integrations. We have -not proved the skill outperforms native Codex alone. -[What is native, what we add, and when not to install →](docs/00-overview/native-capabilities-and-value.md) +| The repeated chore | What ThreadMesh offers | +|---|---| +| “Tell the other session what changed.” | Selected peer goals and advisory handoffs; a model chooses whether to contact a peer. | +| “Remember what we already agreed.” | Each receiver keeps its own task context and checks advice against earlier decisions. | +| “Was it received—or actually done?” | Workspace inbox/disposition records plus examples that verify the receiver's own artifact, not just delivery. | + +Two ways to use it: an optional **Codex desktop skill** over native task tools, +or a **local workspace** with a persistent inbox, supported harness adapters +and explicit portable checkpoints. These are different integration paths, not +one universal desktop connector. Codex supplies the skill route's transport. +[What we add—and when native Codex is enough →](docs/00-overview/native-capabilities-and-value.md)

Concept: Agent A sends advice from another task to Agent B while unrelated work stays quiet @@ -41,44 +43,56 @@ not proved the skill outperforms native Codex alone. ## A real handoff without the copy-paste -[Read the actual desktop exchange and B's own diff →](docs/evidence/codex-native-2026-09-07/README.md) -Retained native records, with busy/stop checks; not a screenshot or reenactment. -The separate installed-package example below is also retained. +**A knows the new product facts. B remembers your earlier website decision.** + +In one controlled Codex desktop run, both tasks completed their initial work +before adopting the skill. B already knew to keep the signup button unchanged. +After explicit pairing, the only business request went to A: -**Two Codex sessions. One remembers your earlier decision; the other changes the -product facts. You don't relay the change.** +> Rename the product to Member Portal and limit the free plan to five projects. +> Use US spelling. Keep the paid-plan price unchanged. Update the approved product facts. -In a real installed-package run, the website session first volunteered its -dependency. The brand session then chose to send the relevant update. After -that actual message, the runner continued the **same native website session**; -its model edited the landing copy itself. +No “send this to B.” A chose to check B's status and send the relevant facts. +**Original B then continued and edited its own website copy.** The manager did +not relay the change, resume B manually or write B's file. | Website copy | Before | After | |---|---|---| | Product and spelling | Organise work with Team Hub | Organize work with Member Portal | -| Free allowance | Unlimited free projects | Free tier includes up to 5 projects | +| Free allowance | Unlimited free projects | Up to five projects on the free tier | | Earlier button decision | Create my workspace | **Unchanged** | | Paid price | $12/month | **Unchanged** | -These compact descriptions summarize the checked artifact, not a screenshot. -Each model received an ordinary task with generic opt-in collaboration guidance, -not an instruction naming the recipient or requiring a send. The runner checks -the receiver's own edit, complete business meaning and retained constraints. - -Two maintainer runs passed from installed packages: about **273 seconds** with -the default 300-second limit, and **184 seconds** in an earlier extended-budget -diagnostic. Neither changed the configured model or account. These are two -observations, not a reliability rate or a time-to-success promise. -[Exact prompts, artifacts and timing →](docs/09-reviews/2026-09-07-codex-first-use-release.md) +The ordinary request to B's completed result took about **49 seconds, excluding +setup**. In separate controls, A held its advice while B was busy and made no +further send after collaboration was stopped. +[Actual messages, B's diff and audit →](docs/evidence/codex-native-2026-09-07/README.md) -**The boundary:** these are two new disposable Codex sessions. The runner -triggers continuation after delivery; this is not native desktop background wake -or attachment to old chats. Earlier [Codex connection failures](docs/09-reviews/2026-09-07-codex-first-use-candidate.md) -and [cross-product business failures](docs/09-reviews/2026-09-05-workspace-awareness.md) -remain recorded. Delivered still does not mean done correctly. +This is one maintainer-operated pair with prior context, not a speed guarantee +or independent-user onboarding result. Codex provided native messaging and +continuation; the skill provided guidance. The table summarizes checked files, +not a screenshot. Simultaneous typing races and plugin hot-loading remain unverified. ## Try it +| Your starting point | Choose this path | +|---|---| +| I use existing Codex desktop tasks | [Native-task workflow](#want-to-connect-your-existing-desktop-tasks): no Node/MCP/hook setup, but explicit pairing and available host tools are required. | +| I want a self-contained real example | [Codex package example](#already-use-codex-keep-your-account): one terminal, two new disposable sessions, existing account and quota. | +| I want to connect my project sessions | [Workspace guide](docs/06-guides/first-workspace.md#advanced-connect-your-own-project-sessions): more setup; persistent inbox and supported harness integration. | + +### Want to connect your existing desktop tasks? + +[Follow the native-task guide](docs/06-guides/codex-native-tasks.md) to give each +chosen task the workflow and its peer's reference, authorize a narrow scope, +then work normally. No terminal setup is needed for that route. + +**Experimental:** the successful case used manager-supplied task references and +a local skill path. Novice pair selection, remote-link retrieval and normal +plugin onboarding remain open. The skill cannot add absent host tools or enforce +privacy and race-free sending. If native Codex already meets your needs, use it +directly; no measured advantage over native-only use is claimed. + ### Already use Codex? Keep your account Requires **Node 22+** and a working, authenticated Codex installation. @@ -104,16 +118,11 @@ Omit `--live` to read instructions without a model call. Processes stop at the end; private results remain for inspection. [Permissions, results and failures →](docs/06-guides/first-workspace.md) -### Want to connect your existing desktop tasks? - -There is an [experimental no-terminal workflow](docs/06-guides/codex-native-tasks.md) -using a skill and Codex's already-exposed native task tools—no Node, MCP or hook -setup for that route. **One controlled desktop pair passed:** both tasks had -completed prior work before activation; A chose to send advice and original B -edited its own copy, preserving earlier decisions. Busy-target and stop checks -also passed. [Native evidence and setup limits →](docs/09-reviews/2026-09-07-native-desktop-acceptance.md) -This is not plugin hot-loading or independent-user onboarding. The skill cannot -create missing host tools, enforce privacy boundaries or eliminate input races. +Separate from the desktop case above, this installed-package Codex example +passed in about **273 seconds** under its default limit. An earlier diagnostic +passed in 184 seconds with an extended budget. The runner continues its own +receiver after actual delivery; it does not attach existing desktop chats. +[Packaged-run evidence and retained failures →](docs/09-reviews/2026-09-07-codex-first-use-release.md) ### Already use Pi instead? @@ -142,7 +151,8 @@ they are not evidence of model initiative. For your own projects, use the | Harness | How it connects | Automatic idle follow-up | |---|---|---| -| **Codex** | `try`: native App Server pair; project launcher: scoped MCP + hooks | `try` runner continues its own idle receiver after delivery; no general native idle wake | +| **Codex desktop** | Optional skill over host-provided native task tools | One controlled pair passed; Codex supplies continuation; availability varies by host | +| **Codex package / projects** | `try`: native App Server pair; project launcher: scoped MCP + hooks | `try` runner continues its own receiver; not arbitrary old-chat attachment | | **Pi** | Native extension; four tools and turn-start context | Opt-in `--wake-idle`; busy-turn guard, not universal typing-race proof | | **Kimi Code** | Project MCP configuration; other servers retained | No | | **DeepSeek Harness** | Official `dsh` MCP plugin via a Cordis patch | Not claimed | @@ -169,6 +179,9 @@ These are practical uses, not a promise that every scenario succeeds. ### Continue from a saved checkpoint +For an already configured workspace—not the disposable `try` sample—run from +its directory, or supply `--workspace /path/to/your/room`: + ```sh npx threadmesh status npx threadmesh continue backend --agent kimi --name recovery @@ -184,13 +197,15 @@ recovery is still unverified. ## Your sessions stay yours -Joining shares published goals and advice, not all private chats. Inbox reads +In the workspace route, joining shares published goals and advice, not all private chats. Inbox reads do not consume messages; acceptance does not prove completion. Pi idle wake is opt-in. Use `npx threadmesh status` to inspect or `npx threadmesh mute client` to mute. This is an **experimental, same-owner local workspace**, not a multi-tenant security boundary. It does not automatically attach arbitrary old tabs, wake every agent product or guarantee correct work. Host tool permissions still apply. +The desktop skill uses Codex's native history and model-followed rules instead; +workspace inbox and mute commands do not control that separate route. [Safety model](docs/04-safety/threat-model.md) · [Security policy](SECURITY.md) diff --git a/README.zh-CN.md b/README.zh-CN.md index a716f1a..3d46a1e 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -7,7 +7,6 @@

CI Apache 2.0 - Node 22+ 实验性 alpha

@@ -19,18 +18,21 @@ English

-一个对话改了接口,另一个还在按旧接口写客户端。 -你不该再负责发现变化、切换聊天、复制粘贴,然后重新解释一遍。 -不必换两种产品:同一个 Agent 的两个 session 就能协作。 +你在一个对话里确认了决策,另一个却还在按旧版本工作。 +ThreadMesh 帮相关 session 分享有用变化,省掉你再解释一次——即使它们都来自同一个产品。 -**你决定哪些 session 加入,模型判断什么时候值得联系。** -Workspace 提供目标发现、建议消息、持久收件箱和可携带的 checkpoint, -不是新模型或共享聊天记录。可选的桌面 Skill 则使用 **Codex 已有的原生任务工具**, -并没有新增这套通信能力。 +**你选择协作对象,模型判断什么值得分享。** -**Codex 自己不是就能做吗?在实测宿主上,是的。** 原生功能够用,就直接用原生。 -Skill 提供可复用协作规则,workspace 为已支持的集成提供协调能力;目前没有证明 -Skill 比原生 Codex 更有效。[哪些是原生、我们增加什么、何时不需要安装 →](docs/zh-CN/native-capabilities-and-value.md) +| 反复遇到的麻烦 | ThreadMesh 提供什么 | +|---|---| +| “把变化再告诉另一个 session。” | 明确选择的协作目标和建议交接,由模型判断是否需要联系。 | +| “之前已经说好的,别忘了。” | 接收方保留自己的任务上下文,结合先前约定判断建议。 | +| “它只是收到了,还是真的做完了?” | Workspace 收件箱与处置记录,以及核验接收方实际产物的案例,不只统计送达。 | + +两条使用路径:基于原生任务工具的可选 **Codex 桌面 Skill**;或包含持久收件箱、 +已支持 harness 适配器和显式 checkpoint 的**本地 workspace**。 +它们不是一个通用桌面连接器;Skill 路径的通信由 Codex 提供。 +[我们增加什么,什么时候原生 Codex 就够用 →](docs/zh-CN/native-capabilities-and-value.md)

概念示意:Agent A 向 Agent B 发送来自另一任务的建议,无关工作保持安静 @@ -39,13 +41,16 @@ Skill 比原生 Codex 更有效。[哪些是原生、我们增加什么、何时 ## 一次不用你转述的真实协作 -[查看实际桌面消息与 B 自己的修改 →](docs/zh-CN/native-evidence.md) -保留的原生记录,含忙碌/停止检查;不是截图或重演。下面另保留安装包案例。 +**A 掌握新的产品事实,B 记着你之前的网站约定。** + +一次受控 Codex 桌面实测中,两个任务先完成原工作,再启用 Skill。 +B 早已知道按钮名称不能改。明确配对后,只向 A 提出普通业务修改,意思是: -**两个 Codex session:一个记着你之前的约定,另一个修改产品事实。你不用转述变化。** +> 产品更名为 Member Portal,免费方案最多五个项目,使用美式拼写。 +> 付费价格不变,更新批准的产品事实。 -在安装包真实运行中,网站 session 先自主说明了依赖,品牌 session 随后自行决定发送相关变化。 -实际收到消息后,运行器续接**同一个原生网站 session**,由它自己的模型修改注册页文案。 +没有要求“把这条消息发给 B”。A 自行检查 B 的状态、发送相关事实, +**原来的 B 接着自己修改了网站文案。** 管理任务没有转述变化、手动续跑 B 或代写文件。 | 网站内容 | 修改前 | 修改后 | |---|---|---| @@ -54,23 +59,32 @@ Skill 比原生 Codex 更有效。[哪些是原生、我们增加什么、何时 | 之前约定的按钮 | Create my workspace | **保持不变** | | 付费价格 | $12/月 | **保持不变** | -上表是已验收文件的紧凑摘要,不是界面截图。每个模型收到普通业务任务和通用协作提示, -没有在任务里指定接收者或要求必须发消息。验收检查接收方自己修改文件、完整业务含义, -以及此前约定是否保留。 - -安装包上保留了两次维护者通过记录:默认 300 秒上限内约 **273 秒**完成; -较早一次扩展时间预算的诊断约 **184 秒**完成。两次都没有改用其他模型或账户。 -这是两次观察,不是可靠性统计,也不保证固定时间成功。 -[真实任务、文件与时间线 →](docs/09-reviews/2026-09-07-codex-first-use-release.md) +普通业务请求到 B 完成约 **49 秒,不含设置时间**。另做对照时,B 忙碌则 A 暂缓发送; +停止协作后再修改产品,A 也没有继续发消息。 +[实际消息、B 的 diff 与审计 →](docs/zh-CN/native-evidence.md) -**边界明确:** 这里是两个新的临时 Codex session,由运行器在实际投递后触发续接; -不是原生桌面后台唤醒,也不是接入已有聊天。 -此前的 [Codex 连接失败](docs/09-reviews/2026-09-07-codex-first-use-candidate.md) -和[跨产品业务失败](docs/09-reviews/2026-09-05-workspace-awareness.md)继续保留。 -消息送达仍然不等于工作做对。 +这是一组维护者操作、保留原上下文的专用任务,不是速度保证或独立用户上手结果。 +原生消息与续跑来自 Codex,Skill 提供协作规则。上表概括已核验文件,不是界面截图。 +同时输入的竞争和插件热加载仍未验证。 ## 开始体验 +| 你现在想做什么 | 选择这条路径 | +|---|---| +| 连接已有 Codex 桌面任务 | [原生任务流程](#想连接已有的桌面任务):不用配置 Node/MCP/hook,但需明确配对且宿主已有工具。 | +| 先跑一个自包含的真实例子 | [Codex 安装包案例](#已经在用-codex沿用你的账户):一个终端、两个新临时任务、沿用账户和额度。 | +| 接入自己项目里的 session | [Workspace 指南](docs/zh-CN/first-workspace.md#进阶两个终端接入自己的项目):设置更多,提供持久收件箱和已支持的 harness 接入。 | + +### 想连接已有的桌面任务? + +按[原生任务指南](docs/zh-CN/codex-native-tasks.md),在选中的任务里提供工作流和对方引用, +授权限定的协作范围,然后正常工作。这条路径不需要终端设置。 + +**实验入口:** 成功案例由管理任务提供引用和本地 Skill 路径;普通用户如何选择任务、 +远程链接读取和常规插件上手仍有缺口。Skill 不能补出缺失的宿主工具,也不能强制 +保证隐私隔离或无竞争发送。如果原生 Codex 已满足需求,直接使用即可; +目前不声称比原生用法更有效。 + ### 已经在用 Codex?沿用你的账户 需要 **Node 22+**,以及已经登录、可以正常使用的 Codex。 @@ -91,15 +105,9 @@ macOS 下可以自动选择比 PATH 版本更新的桌面自带运行时,不 不带 `--live` 只显示说明,不调用模型。结束后停止进程,私有结果保留供检查。 [权限、结果和失败处理 →](docs/zh-CN/first-workspace.md) -### 想连接已有的桌面任务? - -另有[实验性无终端工作流](docs/zh-CN/codex-native-tasks.md),通过 skill 使用 Codex -已经提供的原生任务工具;这条路径不用配置 Node、MCP 或 hook。 -**一组受控桌面双任务已通过实测:** 两边先完成原任务,再启用协作;A 自行发出建议, -原来的 B 自己改对文案,并保留之前的约定。忙碌时不发送、停止后不再发送也通过。 -[原生证据与设置边界 →](docs/09-reviews/2026-09-07-native-desktop-acceptance.md) -这不是插件热加载或独立新用户上手验收。Skill 不能补出宿主缺失的工具,也不能强制 -保证隐私边界或消除用户输入竞争。 +与上方桌面实测分开,这个 Codex 安装包例子在默认上限内约 **273 秒**通过; +更早一次扩展时间预算的诊断约 184 秒通过。运行器在实际投递后续接自己的接收方, +不是接入已有桌面聊天。[安装包证据与保留的失败 →](docs/09-reviews/2026-09-07-codex-first-use-release.md) ### 已经在用 Pi? @@ -127,7 +135,8 @@ npx threadmesh preview preferences | Harness | 接入方式 | 空闲时自动续接 | |---|---|---| -| **Codex** | `try` 使用原生 App Server 双 session;项目 launcher 使用限定范围的 MCP 与 hook | `try` 在投递后由运行器续接自身空闲接收方;不是通用原生空闲唤醒 | +| **Codex 桌面** | 宿主原生任务工具之上的可选 Skill | 一组受控双任务通过;Codex 提供续跑,工具可用性取决于宿主 | +| **Codex 安装包 / 项目** | `try` 使用 App Server 双 session;项目 launcher 使用限定范围的 MCP 与 hook | `try` 运行器续接自己的接收方;不是任意旧聊天接入 | | **Pi** | 原生扩展,四个工具与任务起始上下文 | 显式 `--wake-idle`;有忙碌保护,但不是所有输入竞争都已实测 | | **Kimi Code** | 项目 MCP 配置,保留其他 server | 未提供 | | **DeepSeek Harness** | 官方 `dsh` 的 Cordis MCP 插件 | 未声称支持 | @@ -154,6 +163,9 @@ Pi→Kimi 成功记录采用约束更强的 adapter 路径。 ### 从已保存的 checkpoint 继续 +仅用于已经配置好的 workspace,不是 `try` 的临时样例。在该目录执行, +或显式提供 `--workspace /path/to/your/room`: + ```sh npx threadmesh status npx threadmesh continue backend --agent kimi --name recovery @@ -167,12 +179,14 @@ npx threadmesh continue backend --agent kimi --name recovery ## Session 仍由你掌控 -加入只共享公布的目标和建议,不扫描全部私聊。读收件箱不会消耗消息,接受建议 +在 workspace 路径,加入只共享公布的目标和建议,不扫描全部私聊。读收件箱不会消耗消息,接受建议 不等于任务完成。Pi 的空闲续接需要明确开启。使用 `npx threadmesh status` 查看, 或用 `npx threadmesh mute client` 静音。 当前是**同一所有者的本地实验版**,不是多租户安全边界。它不会自动接入任意旧 tab、 唤醒所有 Agent 产品,也不保证工作一定正确。宿主原有的工具权限仍然适用。 +桌面 Skill 则使用 Codex 原生历史和模型遵循的规则;workspace 的收件箱与静音命令 +不能控制这条独立路径。 [安全模型](docs/04-safety/threat-model.md) · [安全报告](SECURITY.md) diff --git a/docs/10-planning/community-followup-2026-09-07.md b/docs/10-planning/community-followup-2026-09-07.md index 735c875..bde83bd 100644 --- a/docs/10-planning/community-followup-2026-09-07.md +++ b/docs/10-planning/community-followup-2026-09-07.md @@ -67,6 +67,60 @@ goal because the smaller new-session example is easier to validate. ## Deferred reply and execution discipline +### Latest review and reply gate + +Rechecked #158 and recent repository comments on September 7. The latest external +comment remains `hlinor-systems` at 08:12:18 UTC, linked above; no newer demand +was found. Do not describe a fresh inspection as a new comment. #158 and #79 +remain open. + +The current README now leads with user chores, one complete native desktop case +and three distinct entry paths. It separates the 49-second desktop observation +from the 273-second packaged example and removes the global Node badge: Node is +a package requirement, not a requirement of the native skill workflow. Native +attribution and the absence of measured incremental benefit remain explicit. + +**Decision: draft only; do not post this turn.** The three requested maintainer +example/progress/receiver-evidence improvements have shipped. Another README +rearrangement is not a new functional release. The next useful increment is the +remaining Codex desktop pairing/activation friction: test a publicly retrievable +workflow with supported task references, without maintainer-local paths or manual +ID hunting. Record the first failure and actual setup steps. After that bounded +increment, recheck the comment and send one consolidated update; do not wait for +every adapter, perfect reliability or a marketing video. No automatic posting or +scheduled follow-up is configured by this document. + +### Proposed reply to #158 — not sent + +> Thank you, Andrei. We followed the three concrete priorities in your report. +> +> [v0.1.0-alpha.3](https://github.com/fyaic/threadmesh/releases/tag/v0.1.0-alpha.3) +> now defaults to a self-contained Codex → Codex example using the existing login +> and model. `threadmesh try --live` prepares the sample and runs both sessions; +> no custom harness, application fixture, Pi installation or second subscription +> is required. The [install/run guide](https://github.com/fyaic/threadmesh/blob/main/docs/06-guides/first-workspace.md) +> shows installation progress and explains quota, runtime and timeout failures. +> We do not bypass exhausted quota or silently switch products. +> +> The installed-package default run completed in 272.604 seconds within its +> 300-second cap. The original receiver made its own checked edit, preserving +> the earlier button decision and paid price. We retained the failed attempts +> as well as the [passing evidence](https://github.com/fyaic/threadmesh/blob/main/docs/09-reviews/2026-09-07-codex-first-use-release.md). +> +> Separately, a controlled desktop pair with completed prior context produced +> native advice and the original receiver's own edit; the [actual exchange and diff](https://github.com/fyaic/threadmesh/blob/main/docs/evidence/codex-native-2026-09-07/README.md) +> are public. Codex supplies that route's native transport. Its synthetic busy +> and stop checks are not proof of race-free delivery or general desktop onboarding. +> +> These are maintainer results, not an independent live pass or a reliability +> rate. We are keeping this issue open for the remaining onboarding gaps. No need +> to retry with exhausted quota or share private transcripts. Your report changed +> the first-use path and what we require before calling a handoff useful. + +Before posting, add only the actual outcome of the next entry-path increment, +recheck release links and claims, and remove anything superseded by a new comment. +Do not copy an unverified planned result into this draft. + Subsequent native desktop evidence is now retained as [actual excerpts and diff](../evidence/codex-native-2026-09-07/README.md). That controlled prior-context pair passed; it is not this contributor's independent live result. The [native-value correction](../00-overview/native-capabilities-and-value.md)