diff --git a/.github/ISSUE_TEMPLATE/operator.yml b/.github/ISSUE_TEMPLATE/operator.yml index 9d02c68..66605fb 100644 --- a/.github/ISSUE_TEMPLATE/operator.yml +++ b/.github/ISSUE_TEMPLATE/operator.yml @@ -6,17 +6,22 @@ body: - type: input id: environment attributes: - label: Harness, OS, and Node version - placeholder: Codex CLI, macOS, Node 22 (do not include local paths) + label: Harness and operating system + description: Include the harness version if known. Node version is only relevant for CLI or source-based use. + placeholder: Codex desktop on macOS (do not include local paths) validations: required: true - type: dropdown id: install attributes: - label: Installation path + label: Entry used options: - - One-command GitHub package - - Fresh clone and npm ci + - Codex marketplace plugin + - Manual native Codex workflow + - CLI example (installed package) + - Local workspace or harness integration + - Source checkout + - Other or unsure validations: required: true - type: input @@ -27,37 +32,38 @@ body: validations: required: true - type: textarea - id: explanation + id: friction attributes: - label: What does ThreadMesh do? - description: Explain it in your own words after using only the README. + label: What did you try, and what happened? + description: Include the expected result and the first confusing or failed step. A failed or unknown outcome is useful feedback. validations: required: true - - type: textarea - id: friction + - type: dropdown + id: outcome attributes: - label: First confusing or failed step + label: Receiver outcome, if a handoff was attempted + options: + - Not attempted + - Sent, but receiver result unknown + - Receiver acted, but result was incorrect or incomplete + - Useful result checked + - Failed or blocked before delivery + - Other or unsure validations: - required: true + required: false - type: textarea id: workflow attributes: - label: Would you use it? - description: Name a real workflow, or explain why the capability is not useful. + label: Would you use it? (optional) + description: Name a workflow, explain what you expected it to help with, or tell us why it was not useful. validations: - required: true + required: false - type: checkboxes id: evidence attributes: - label: Evidence checks + label: Report context options: - - label: I found why delivery alone did not unlock the dependent task. - required: false - - label: I found what happened when the receiver was already running. - required: false - - label: The demo reported cleanup complete. - required: false - label: I am independent of the ThreadMesh maintainer organization. required: false - - label: I removed credentials, transcripts, IDs, and local paths. + - label: I removed credentials, private transcripts, IDs, and local paths from this report. required: true diff --git a/CHANGELOG.md b/CHANGELOG.md index 6a798d7..ef325e9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,42 @@ # Changelog -All notable changes will be documented here. The project follows Keep a Changelog conventions once versioned releases begin. +User-visible changes are listed below. The CLI package and the Codex plugin +have separate versions. Changes on the default branch do not modify an existing +release tarball. + +## [Unreleased] + +The following source and Codex plugin changes are not included in the published +CLI `0.1.0-alpha.3` tarball. The Codex plugin manifest is now `0.1.0-alpha.2`; +that version is separate from the earlier CLI release with the same number. + +### Added + +- Codex plugin marketplace entry, pinned installation instructions, and shorter + activation guidance for explicitly selected tasks ([#183](https://github.com/fyaic/threadmesh/pull/183)). +- API-to-client handoff guidance that asks the receiver to preserve its own + existing constraints, plus a matched native-only comparison plan. + +### Changed + +- Native Codex guidance now makes reply authorization and stopped-receiver + handling explicit. It distinguishes local readiness, peer confirmation, + pending advice, sent but unverified work, and checked results. +- Manual native-task onboarding uses selected chat links and a shared topic. + Guides distinguish historical controlled runs from current plugin validation. + +### Removed + +- The website pairing helper and its deployment. Local installation and selected + existing tasks remain the intended entry ([#177](https://github.com/fyaic/threadmesh/pull/177)). + +### Limitations + +- Marketplace discovery was checked; actual plugin installation, existing-task + loading, independent first use, and comparative business benefit remain + unverified. No new live business validation is claimed for this increment. +- The native skill uses Codex's own task tools. Its instructions do not provide + a durable inbox, atomic idle-only delivery, or host-enforced revocation. ## [0.1.0-alpha.3] - 2026-09-07 @@ -61,7 +97,11 @@ All notable changes will be documented here. The project follows Keep a Changelo - The command without `--live` does not call a model. Simulated previews remain separate; no model-wide reliability or independent-adoption claim is implied. -## [Unreleased] +## Historical development notes + +These notes were recorded before the versioned entries above and were not mapped +to individual releases. They are retained as development history, not a list of +pending changes or a claim that each feature is available through the Codex plugin. ### Added diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a47ccc7..5a87a24 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,18 +1,26 @@ # Contributing to ThreadMesh -ThreadMesh is currently specification-and-conformance-first. The repository -also contains an experimental runtime, but contributions should turn observed -behavior into portable semantics and negative tests rather than expanding the -prototype without a protocol boundary. +ThreadMesh explores useful cooperation between selected agent tasks. The current +focus is a small, opt-in Codex workflow: make setup understandable, preserve each +task's existing constraints, and distinguish a sent message from useful work. +The repository also contains an experimental CLI, runtime, and protocol drafts. + +Useful contributions include clearer instructions, reproducible first-run +failures, and focused fixes. Start from an observed problem and explain the +expected outcome before adding another adapter, service, or protocol feature. +See the [current status](docs/10-planning/project-status.md) for what has been +verified and what remains experimental. ## Before opening a pull request -1. Read the [vision](docs/00-overview/vision.md), [scope](docs/00-overview/scope.md), and [design principles](docs/00-overview/principles.md). -2. Search existing issues and Architecture Decision Records. -3. Read the [current status](docs/10-planning/project-status.md) and - [mainline plan](docs/10-planning/mainline-plan.md). -4. Open a design issue before proposing a protocol-breaking change or a new coordination intent. -5. Keep one pull request focused on one coherent outcome. +1. Read the relevant guide and check the [current priorities](ROADMAP.md). +2. Search existing issues for the same problem. Include reproduction steps, + your installation path, and the result you expected when reporting a bug. +3. Keep one pull request focused on one coherent outcome. +4. For protocol or safety changes, also read the [scope](docs/00-overview/scope.md), + [design principles](docs/00-overview/principles.md), and relevant Architecture + Decision Records. Open a design issue before a protocol-breaking change or + a new coordination intent. ## Change categories @@ -30,6 +38,26 @@ Specification and safety changes should include: - at least one positive and one negative example; - an ADR when the decision is durable or difficult to reverse. +## Local checks + +For repository development, use Node.js 22 or newer: + +```sh +npm ci +npm test +``` + +`npm test` validates the schemas, runs automated tests, and lints documentation. +It does not require a model account or a paid live run. For documentation-only +edits, `npm run lint:docs` is a useful focused check; also verify changed links. +Node.js is a repository development requirement, not a prerequisite for users +of the native Codex skill. + +Live-model runs are separate, optional checks that require an authenticated +harness and may consume quota. Do not run them just to submit an editorial fix. +If a change needs live validation that you cannot perform, state that limitation +in the PR. Never include credentials or private conversations in reports. + ## Documentation style - Use plain, precise language. @@ -44,6 +72,7 @@ Specification and safety changes should include: - Use imperative, descriptive commit subjects. - Explain why the change is needed in the pull request body. - Link the issue or ADR when applicable. -- Update `CHANGELOG.md` for user-visible changes after versioning begins. +- Update `CHANGELOG.md` for user-visible changes. Distinguish source changes, + Codex plugin versions, and CLI releases; they do not ship together automatically. By participating, you agree to follow the [Code of Conduct](CODE_OF_CONDUCT.md). diff --git a/README.md b/README.md index 5d94e24..04d0287 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,6 @@

ThreadMesh

-

Your agent conversations should talk to each other.
You shouldn't have to relay every message.

- -

Connect separate sessions of the same agent—or different agents.
Let them discover relevant work, share changes, and continue with context.

+

Share useful context between agent tasks.
Keep related work in sync without relaying every change yourself.

CI @@ -11,117 +9,55 @@

- See the effect · - Try it · - Harnesses · - Docs · + Get started · + Evidence · + Documentation · 简体中文

-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 the collaborators. The models decide what is worth sharing.** - -| 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 -
Concept illustration of the handoff—not a shipped chat UI or a recording. -

- -## A real handoff without the copy-paste - -**A knows the new product facts. B remembers your earlier website decision.** +You update an API in one task. Another task maintains its client and still uses +the old contract. ThreadMesh helps the selected tasks share that change, while +the receiver keeps the decisions already made in its own conversation. -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: +**You choose the collaborators and allowed topics. The agents judge what is +relevant and how to use it.** Tasks may use the same agent product or different +supported products. -> 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. +ThreadMesh offers two separate paths: -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 | +| Path | What it adds | Current status | |---|---|---| -| Product and spelling | Organise work with Team Hub | Organize work with Member Portal | -| 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** | - -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) +| **Codex desktop skill** | Guidance for scoped collaboration through Codex's native task tools | Experimental plugin candidate; marketplace discovery checked, installation and existing-task loading unverified | +| **Local workspace / CLI** | A persistent inbox, supported harness integrations and explicitly saved checkpoints | `v0.1.0-alpha.3` available from GitHub Releases; controlled live examples recorded | -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. +The skill does not add a messaging service. If native Codex already covers your +workflow, you may not need it. Improvement over native-only use has not been +measured. [What ThreadMesh adds →](docs/00-overview/native-capabilities-and-value.md) ## 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? -[**Plugin installation and task activation →**](docs/06-guides/codex-native-tasks.md) - -The repository now includes a marketplace entry for the optional Codex skill. -See the guide for candidate installation and a short activation request naming -one peer, one shared topic and a send mode. A useful first case is an API change -reaching the task that maintains its client, with the client's earlier decisions -preserved. Check the receiver's own diff and tests, not just a sent badge. - -**Existing-task adoption remains unverified.** Official plugin documentation -promises bundled skills in new chats or CLI sessions after installation; it does -not establish hot-loading in old chats. Marketplace discovery alone is not an -installation or original-task success. The source-read manual workflow remains -an experimental fallback. The product target is still **install once, choose -allowed existing tasks, then work normally**. - -Ask **“Check ThreadMesh status”** for pending advice and observed results. Say -**“Stop ThreadMesh collaboration”** in both tasks to stop both directions. -These are in-task requests, not an instant control service. The -[small native-only comparison](docs/10-planning/native-value-acceptance-2026-10-10.md) -will count setup, manual relays, correct receiver edits and unwanted contact; -its real-business results are not yet available. - -Another real case: A changed an API contract; original B updated its own client -and tests, retaining the earlier timeout and cursor-encoding decisions. -[Browser checks and the actual API handoff →](docs/09-reviews/2026-09-08-pairing-helper-acceptance.md) - -**Tested, still experimental:** the [public-workflow + chat-link run](docs/09-reviews/2026-09-08-native-deep-link-acceptance.md) -resolved the original two tasks without a global task list. A chose to send; -original B updated its own copy and preserved its button and price. The manager -supplied the documented link format through native tools; manual GUI onboarding -and normal plugin installation remain unverified. 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. +Start with the [Codex plugin and task activation guide](docs/06-guides/codex-native-tasks.md). +It covers the candidate installation, selecting a peer, choosing a shared topic +and enabling the permitted direction of communication. The skill route needs +no Node, MCP server or hook setup; it requires the host's native task tools. + +**Installing the plugin and loading it in an existing task remain unverified.** +The guide separates those checks from marketplace discovery and the experimental +manual workflow. Controlled handoff results below used source-loaded guidance; +they do not demonstrate normal plugin installation. + +After activation, ask “Check ThreadMesh status” to inspect pending advice and +observed results. Say “Stop ThreadMesh collaboration” in each participating task +to stop both directions. These are instructions followed by the agent, not an +instant control service or a way to retract messages already submitted. ### Already use Codex? Keep your account -Requires **Node 22+** and a working, authenticated Codex installation. -Install the version-pinned **v0.1.0-alpha.3** package from GitHub Releases; -it is not on the npm registry: +For a self-contained example, install the released **CLI package**. It requires +**Node 22+**, an authenticated supported Codex runtime and available model quota. +The package is distributed through GitHub Releases, not the npm registry: ```sh npm install --foreground-scripts --loglevel=info \ @@ -129,123 +65,123 @@ npm install --foreground-scripts --loglevel=info \ npx threadmesh try --live ``` -The default is the **Codex → Codex copy example**. No Pi, second subscription, -API key change, custom harness, test project or two-terminal setup is required. -It uses your existing Codex configuration and normal quota. On macOS, ThreadMesh -can choose a newer desktop-bundled runtime over an older PATH installation; -you do not always need a separate CLI install. - -Installation progress and runtime stages are visible. Native builds, network -conditions and model behavior affect timing. The live run has a **300-second -overall limit**; unfinished or wrong work fails instead of becoming a preview. -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) - -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) +This starts **two new disposable Codex sessions** for a copy-editing example, +using your existing configuration. The runner continues its sample receiver +after delivery and checks the receiver's own edit. It does not attach existing +desktop tasks. On macOS it can also select a supported desktop-bundled runtime. + +Progress is visible, the run has a **300-second total limit**, and failures are +reported as failures. Processes stop at the end; private results remain for +inspection. Omit `--live` to read instructions without calling a model. +[Setup, permissions and troubleshooting →](docs/06-guides/first-workspace.md) ### Already use Pi instead? -Keep its existing configuration and select it explicitly: +After installing the same CLI package, choose Pi explicitly: ```sh npx threadmesh try preferences --agent pi --live npx threadmesh try api --agent pi --live ``` -The API example currently requires Pi; Codex first use supports copy only. -Neither path requires the other product. [Pi options and limits](docs/06-guides/first-workspace.md#optional-pi-example). +These use Pi's existing configuration and quota. The packaged API example +currently requires Pi; the Codex example supports copy only. +[Pi setup →](docs/06-guides/first-workspace.md#optional-pi-example) ### Preview without a model +After installing the CLI package: + ```sh npx threadmesh preview preferences ``` -Simulated agents, real local coordinator. No API key, model quota or chat access. -Also try `preview api` and `preview quota`. These explain the workflow; -they are not evidence of model initiative. For your own projects, use the -[advanced two-terminal workflow](docs/06-guides/first-workspace.md#advanced-connect-your-own-project-sessions). +This uses simulated agents and the real local coordinator, with no model login +or quota required. `preview api` and `preview quota` are also available. +A preview explains the workflow; it does not prove autonomous agent behavior. -## Supported harnesses +To connect your own project sessions with a persistent inbox, follow the +[workspace guide](docs/06-guides/first-workspace.md#advanced-connect-your-own-project-sessions). -| Harness | How it connects | Automatic idle follow-up | -|---|---|---| -| **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 | -| **Other harnesses** | Standard MCP configuration or JavaScript SDK | Requires host integration | +## A real handoff without the copy-paste -Versions checked: Codex `0.153.1` for the new-pair example, `0.145.0` for the -earlier project launcher; Pi `0.84.2`, Kimi `0.39.1`, DeepSeek `0.1.2-rc.1`. -DeepSeek passed **no-model** native tool/delivery checks; live -initiative is pending credentials. Kimi's latest attempt hit weekly quota. -Earlier Codex→Kimi and Pi→Kimi passes used a more constrained adapter path. +In a controlled Codex desktop case, A maintained product facts and B maintained +website copy. Both already had task context. After pairing, the ordinary request +went only to A: rename the product, limit the free plan to five projects and use +US spelling. A chose to send the relevant change. **Original B then edited its +own copy**, keeping its earlier button text and the paid price unchanged. -[Versioned evidence and compatibility limits →](docs/00-overview/harness-support.md) +[Read the actual messages, receiver diff and audit →](docs/evidence/codex-native-2026-09-07/README.md) -## Where it can help +| Evidence | What it establishes | What it does not establish | +|---|---|---| +| [Native desktop copy case](docs/09-reviews/2026-09-07-native-desktop-acceptance.md) | One original-task handoff, retained prior decisions, controlled busy/stop checks | Plugin installation, independent onboarding or simultaneous-input safety | +| [Native API/client case](docs/09-reviews/2026-09-08-pairing-helper-acceptance.md) | Original receiver changed its client and tests while retaining timeout/encoding decisions | A production deployment or benefit over native-only Codex | +| [Installed Codex CLI example](docs/09-reviews/2026-09-07-codex-first-use-release.md) | One released-package run passed within the default limit; earlier failures retained | Existing desktop-task adoption or a general success rate | -- **“I already told the other agent.”** Share an API change, approved term or - research finding with the workstream that needs it, without relaying it yourself. -- **“Don't lose our decisions.”** Publish selected constraints and save a - checkpoint instead of broadcasting entire private conversations. -- **“My quota ran out halfway through.”** Start another harness with the last - saved goal, decisions, constraints and next step. +These are maintainer-operated examples. Delivery alone is not success: the +receiver's actual work must preserve both the new requirement and its earlier +constraints. The [evidence index](docs/evidence/README.md) and +[compatibility record](docs/00-overview/harness-support.md) include narrower +checks, failures and unverified paths. -These are practical uses, not a promise that every scenario succeeds. +## Supported harnesses -### Continue from a saved checkpoint +| Integration | Entry and boundary | +|---|---| +| **Codex desktop** | Optional skill over native task tools; availability depends on the host | +| **Codex CLI / projects** | App Server sample pair; scoped MCP and hooks for project sessions | +| **Pi** | Native extension; optional idle wake with a busy-turn guard | +| **Kimi Code** | Project MCP integration; no automatic idle follow-up | +| **DeepSeek Harness** | Native MCP integration checked without a model; live initiative unverified | +| **Other harnesses** | MCP or JavaScript SDK integration requires host-specific setup | -For an already configured workspace—not the disposable `try` sample—run from -its directory, or supply `--workspace /path/to/your/room`: +Support is versioned and evidence varies by path. Consult the +[full support matrix](docs/00-overview/harness-support.md) before choosing an integration. + +## Continue from a saved checkpoint + +In an already configured workspace, a checkpoint can preserve selected goals, +decisions, constraints and next steps for a new session: ```sh npx threadmesh status npx threadmesh continue backend --agent kimi --name recovery ``` -**A checkpoint must already exist**, and the destination needs available quota. -Saving is model-selected, not guaranteed automatic backup. This starts a -**new native session** with explicit context—not full chat history, hidden state, -permissions or cross-machine file transfer. Actual quota-blocked long-session -recovery is still unverified. - -[Checkpoint guide: what survives, what doesn't →](docs/06-guides/portable-checkpoints.md) +Run from the workspace directory, with an existing checkpoint and available +quota in the destination harness. This is explicit context transfer, not a full +conversation backup or file migration. Recovery from an actual quota-blocked +long session remains unverified. [Checkpoint guide →](docs/06-guides/portable-checkpoints.md) ## Your sessions stay yours -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. +The native skill follows the user's selected task, topic and send permissions. +Incoming advice does not authorize a reply. It cannot enforce privacy or make +an idle check and subsequent send atomic; host permissions still apply. -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. +The workspace route shares published goals and advice, not entire private +conversations. Inbox reads do not consume messages, and acceptance does not +prove completion. Its inbox and mute controls are separate from the native +skill. This is an **experimental, same-owner local system**, not a multi-tenant +security boundary. [Safety model](docs/04-safety/threat-model.md) · [Security policy](SECURITY.md) ## Build with us -Next: make same-product session collaboration easy to adopt, preserve full -business constraints, and verify prior-session continuity and independent first use. -[Focused follow-up](https://github.com/fyaic/threadmesh/issues/156) · [Roadmap](ROADMAP.md) +Reports of a confusing setup step, a missed constraint or an unwanted message +are useful. Include the integration path and the first failed step; remove +credentials and private conversation content. Adapter authors can start with +the [SDK guide](docs/06-guides/implement-an-adapter.md). -Report the **first failed step**, a silent agent, an irrelevant message or a -useful collaboration. Building a harness? Start with the -[workspace/MCP guide](docs/06-guides/first-workspace.md#kimi-and-custom-harnesses) -or [SDK adapter guide](docs/06-guides/implement-an-adapter.md). +Current maintenance focuses on clear installation guidance and honest capability +descriptions. Real-project validation is paused; installation, independent first +use and native-only value comparison remain open, not passed. +[Current status](docs/10-planning/project-status.md) · [Roadmap](ROADMAP.md) -[Report a first run](https://github.com/fyaic/threadmesh/issues/new?template=operator.yml) · +[Report an experience](https://github.com/fyaic/threadmesh/issues/new?template=operator.yml) · [Discuss a workflow](https://github.com/fyaic/threadmesh/discussions) · [Contribute](CONTRIBUTING.md) · [Documentation](docs/README.md) -If it saves you a handoff, a star helps others find it. [Apache 2.0](LICENSE). +[Apache 2.0](LICENSE). diff --git a/README.zh-CN.md b/README.zh-CN.md index 49fc4b0..912fe92 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -1,8 +1,6 @@

ThreadMesh

-

让你的不同对话主动协作。
你不用再当消息中转站。

- -

可以是同一个 Agent 的不同 session，也可以来自不同产品。
让它们发现相关工作、分享变化、带着上下文继续。

+

让相关 Agent 任务共享有用的上下文。
少一次手动转述，让各自的工作跟上变化。

CI @@ -11,103 +9,50 @@

- 看真实效果 · 开始体验 · - 支持的 Agent · + 实测证据 · 中文文档 · English

-你在一个对话里确认了决策，另一个却还在按旧版本工作。 -ThreadMesh 帮相关 session 分享有用变化，省掉你再解释一次——即使它们都来自同一个产品。 - -**你选择协作对象，模型判断什么值得分享。** - -| 反复遇到的麻烦 | ThreadMesh 提供什么 | -|---|---| -| “把变化再告诉另一个 session。” | 明确选择的协作目标和建议交接，由模型判断是否需要联系。 | -| “之前已经说好的，别忘了。” | 接收方保留自己的任务上下文，结合先前约定判断建议。 | -| “它只是收到了，还是真的做完了？” | Workspace 收件箱与处置记录，以及核验接收方实际产物的案例，不只统计送达。 | - -两条使用路径：基于原生任务工具的可选 **Codex 桌面 Skill**；或包含持久收件箱、 -已支持 harness 适配器和显式 checkpoint 的**本地 workspace**。 -它们不是一个通用桌面连接器；Skill 路径的通信由 Codex 提供。 -[我们增加什么，什么时候原生 Codex 就够用 →](docs/zh-CN/native-capabilities-and-value.md) - -

- 概念示意：Agent A 向 Agent B 发送来自另一任务的建议，无关工作保持安静 -
协作机制的概念插图，不是已发布的聊天界面或真实录屏。 -

- -## 一次不用你转述的真实协作 - -**A 掌握新的产品事实，B 记着你之前的网站约定。** +你在一个任务里修改 API，另一个维护客户端的任务却还在沿用旧约定。 +ThreadMesh 帮你选中的任务分享这次变化，同时让接收方保留自己对话中已经确定的决策。 -一次受控 Codex 桌面实测中，两个任务先完成原工作，再启用 Skill。 -B 早已知道按钮名称不能改。明确配对后，只向 A 提出普通业务修改，意思是： +**你选择协作对象和允许的话题，Agent 判断哪些信息相关、如何使用。** +这些任务可以来自同一个 Agent 产品，也可以来自不同的受支持产品。 -> 产品更名为 Member Portal，免费方案最多五个项目，使用美式拼写。 -> 付费价格不变，更新批准的产品事实。 +ThreadMesh 提供两条独立的使用路径： -没有要求“把这条消息发给 B”。A 自行检查 B 的状态、发送相关事实， -**原来的 B 接着自己修改了网站文案。** 管理任务没有转述变化、手动续跑 B 或代写文件。 - -| 网站内容 | 修改前 | 修改后 | +| 路径 | 提供什么 | 当前状态 | |---|---|---| -| 品牌与拼写 | Organise work with Team Hub | Organize work with Member Portal | -| 免费额度 | 无限免费项目 | 免费方案最多 5 个项目 | -| 之前约定的按钮 | Create my workspace | **保持不变** | -| 付费价格 | $12/月 | **保持不变** | - -普通业务请求到 B 完成约 **49 秒，不含设置时间**。另做对照时，B 忙碌则 A 暂缓发送； -停止协作后再修改产品，A 也没有继续发消息。 -[实际消息、B 的 diff 与审计 →](docs/zh-CN/native-evidence.md) +| **Codex 桌面 Skill** | 通过 Codex 原生任务工具，按指定范围协作的工作流指导 | 实验性插件候选版；已检查 marketplace 发现，安装与已有任务加载未验收 | +| **本地 workspace / CLI** | 持久收件箱、已支持的 harness 接入和显式保存的 checkpoint | GitHub Releases 已提供 `v0.1.0-alpha.3`；保留受控真实案例 | -这是一组维护者操作、保留原上下文的专用任务，不是速度保证或独立用户上手结果。 -原生消息与续跑来自 Codex，Skill 提供协作规则。上表概括已核验文件，不是界面截图。 -同时输入的竞争和插件热加载仍未验证。 +Skill 没有新增消息服务。如果原生 Codex 已经满足你的工作方式，可能不需要它。 +相对原生用法的增量收益尚未测量。 +[ThreadMesh 增加了什么 →](docs/zh-CN/native-capabilities-and-value.md) ## 开始体验 -| 你现在想做什么 | 选择这条路径 | -|---|---| -| 连接已有 Codex 桌面任务 | [原生任务流程](#想连接已有的桌面任务)：不用配置 Node/MCP/hook，但需明确配对且宿主已有工具。 | -| 先跑一个自包含的真实例子 | [Codex 安装包案例](#已经在用-codex沿用你的账户)：一个终端、两个新临时任务、沿用账户和额度。 | -| 接入自己项目里的 session | [Workspace 指南](docs/zh-CN/first-workspace.md#进阶两个终端接入自己的项目)：设置更多，提供持久收件箱和已支持的 harness 接入。 | - ### 想连接已有的桌面任务？ -[**插件安装与任务启用 →**](docs/zh-CN/codex-native-tasks.md) - -仓库现在包含可选 Codex skill 的 marketplace 入口。指南提供候选版安装方式， -以及只需指定协作对象、允许话题和发送模式的简短启用请求。适合先验证的用途是： -API 变更到达维护客户端的任务，并保留客户端此前的约定。看接收方自己的 diff 和测试， -才能判断是否做对了事情。 - -**安装后接入已有任务仍未验收。** 官方插件文档承诺安装后在新聊天或新 CLI 会话中 -提供 skill，没有保证旧聊天热加载。marketplace 能发现插件，不等于已安装或原任务 -成功接入。手动读取源码工作流仍是实验性备用路径。产品目标仍是**安装一次， -选择允许协作的已有任务，然后正常工作**。 - -在任务中说“检查 ThreadMesh 状态”，查看待发建议和已观察到的结果；在两端分别说 -“停止 ThreadMesh 协作”，停止双向协作。这些是任务内请求，不是即时控制服务。 -[小型原生用法对照](docs/10-planning/native-value-acceptance-2026-10-10.md)将记录设置、 -人工传话、接收方正确改动及无关触达，目前还没有真实业务对照结果。 +从 [Codex 插件与任务启用指南](docs/zh-CN/codex-native-tasks.md) 开始。 +指南介绍候选版安装、选择协作对象、确定共享话题，以及启用允许的通信方向。 +Skill 路径不需要配置 Node、MCP server 或 hook，但宿主必须提供原生任务工具。 -另一个真实案例：A 修改 API 约定后，原 B 自己更新客户端和测试，同时保留此前的 -超时、特殊游标编码约定。[页面检查与实际 API 协作记录 →](docs/09-reviews/2026-09-08-pairing-helper-acceptance.md) +**插件实际安装、在已有任务中加载仍未验收。** 指南将它们与 marketplace 发现、 +实验性的手动工作流分别说明。下方的受控协作案例使用了从源码加载的工作流指导， +不能证明正常插件安装已经跑通。 -**已实测，仍属实验入口：** [公开工作流＋聊天链接实测](docs/09-reviews/2026-09-08-native-deep-link-acceptance.md) -不查全局任务列表就定位了原来的两个任务；A 主动发送，原 B 自己改对文案并保留按钮和价格。 -本次由管理任务通过原生工具提供官方格式的链接；人工 GUI 上手和常规插件安装仍未验收。 -Skill 不能补出缺失的宿主工具，也不能强制 -保证隐私隔离或无竞争发送。如果原生 Codex 已满足需求，直接使用即可； -目前不声称比原生用法更有效。 +启用后，可说“检查 ThreadMesh 状态”查看待发建议与已观察结果。 +在各参与任务中分别说“停止 ThreadMesh 协作”，才能停止两个方向。 +这些是 Agent 遵循的指令，不是即时控制服务，也无法撤回已经提交的消息。 ### 已经在用 Codex？沿用你的账户 -需要 **Node 22+**，以及已经登录、可以正常使用的 Codex。 -安装 GitHub Release 中固定的 **v0.1.0-alpha.3** 安装包，尚未发布到 npm registry： +想先跑一个自包含例子，可以安装已发布的 **CLI 包**。需要 **Node 22+**、 +已登录的受支持 Codex runtime，以及可用的模型额度。 +安装包通过 GitHub Releases 分发，不在 npm registry 上： ```sh npm install --foreground-scripts --loglevel=info \ @@ -115,112 +60,112 @@ npm install --foreground-scripts --loglevel=info \ npx threadmesh try --live ``` -默认运行 **Codex → Codex 文案案例**。不用另装 Pi、购买第二家订阅、改 API key， -不用自编 harness、准备测试项目或打开两个终端。沿用 Codex 已有配置，消耗正常额度。 -macOS 下可以自动选择比 PATH 版本更新的桌面自带运行时，不一定需要单独安装 CLI。 +它沿用现有配置，启动**两个新的临时 Codex 会话**完成文案修改例子。 +运行器在消息送达后续跑自己的接收方，并核对接收方实际完成的修改；它不会接入已有桌面任务。 +在 macOS 上，也可以选择受支持的桌面应用内置 runtime。 -安装进度和运行阶段可见。原生依赖编译、网络和模型表现都会影响耗时。 -真实运行总上限是 **300 秒**；未完成或做错都会报告失败，不换成模拟成功。 -不带 `--live` 只显示说明，不调用模型。结束后停止进程，私有结果保留供检查。 -[权限、结果和失败处理 →](docs/zh-CN/first-workspace.md) - -与上方桌面实测分开，这个 Codex 安装包例子在默认上限内约 **273 秒**通过； -更早一次扩展时间预算的诊断约 184 秒通过。运行器在实际投递后续接自己的接收方， -不是接入已有桌面聊天。[安装包证据与保留的失败 →](docs/09-reviews/2026-09-07-codex-first-use-release.md) +运行进度可见，**总时限为 300 秒**，失败会直接报告。 +结束时停止进程，私有结果保留供检查。省略 `--live` 则只显示说明，不调用模型。 +[配置、权限与排错 →](docs/zh-CN/first-workspace.md) ### 已经在用 Pi？ -沿用现有配置，明确选择 Pi 即可： +安装同一个 CLI 包后，显式选择 Pi： ```sh npx threadmesh try preferences --agent pi --live npx threadmesh try api --agent pi --live ``` -接口分页案例当前需用 Pi，Codex 首次体验只支持文案。两条路径都不依赖另一家产品。 -[Pi 配置和限制](docs/zh-CN/first-workspace.md#可选pi-案例)。 +它们沿用 Pi 的已有配置与额度。安装包里的 API 例子目前需要 Pi； +Codex 例子目前只支持文案场景。 +[Pi 配置 →](docs/zh-CN/first-workspace.md) + +### 不调用模型，先看预览 -### 不调用模型，先理解流程 +安装 CLI 包后运行： ```sh npx threadmesh preview preferences ``` -模拟 Agent、真实本地协调器：不需要 API key，不消耗模型额度，不读取聊天。 -也可试 `preview api` 和 `preview quota`。预览解释流程，不证明模型主动性。 -要连接自己的项目，可再看[进阶双终端接入](docs/zh-CN/first-workspace.md#进阶两个终端接入自己的项目)。 +模拟 Agent 使用真实的本地 coordinator，不需要模型登录或额度。 +也可以试 `preview api` 和 `preview quota`。 +预览用于理解流程，不能证明 Agent 会自主协作。 -## 支持哪些 Harness +如果要让自己的项目会话使用持久收件箱，见 +[workspace 指南](docs/zh-CN/first-workspace.md#进阶两个终端接入自己的项目)。 -| Harness | 接入方式 | 空闲时自动续接 | -|---|---|---| -| **Codex 桌面** | 宿主原生任务工具之上的可选 Skill | 一组受控双任务通过；Codex 提供续跑，工具可用性取决于宿主 | -| **Codex 安装包 / 项目** | `try` 使用 App Server 双 session；项目 launcher 使用限定范围的 MCP 与 hook | `try` 运行器续接自己的接收方；不是任意旧聊天接入 | -| **Pi** | 原生扩展，四个工具与任务起始上下文 | 显式 `--wake-idle`；有忙碌保护，但不是所有输入竞争都已实测 | -| **Kimi Code** | 项目 MCP 配置，保留其他 server | 未提供 | -| **DeepSeek Harness** | 官方 `dsh` 的 Cordis MCP 插件 | 未声称支持 | -| **其他 Harness** | 标准 MCP 配置或 JavaScript SDK | 需要宿主接入 | +## 一次不用你转述的真实协作 + +在一次受控 Codex 桌面案例中，A 维护产品事实，B 维护网站文案，两者已有各自任务上下文。 +配对后，只向 A 提出普通业务请求：产品更名、免费方案最多五个项目、使用美式拼写。 +A 自行发送相关变化，**原来的 B 随后修改了自己的文案**，并保留之前约定的按钮文字和付费价格。 + +[查看实际消息、接收方 diff 与审计 →](docs/zh-CN/native-evidence.md) -核验版本：新双 session 案例使用 Codex `0.153.1`，此前项目 launcher 使用 `0.145.0`； -Pi `0.84.2`、Kimi `0.39.1`、DeepSeek `0.1.2-rc.1`。 -DeepSeek 通过的是**无模型**原生工具与收发检查，真实模型主动协作 -仍待配置凭证后验证。Kimi 最近一次尝试遇到周额度限制。更早的 Codex→Kimi、 -Pi→Kimi 成功记录采用约束更强的 adapter 路径。 +| 证据 | 证明了什么 | 不能证明什么 | +|---|---|---| +| [原生桌面文案案例](docs/09-reviews/2026-09-07-native-desktop-acceptance.md) | 一次原任务协作、保留先前决策，以及受控忙碌/停止检查 | 插件安装、独立用户上手或同时输入的安全性 | +| [原生 API/客户端案例](docs/09-reviews/2026-09-08-pairing-helper-acceptance.md) | 原接收方修改客户端与测试，保留超时和编码决策 | 生产部署或相对原生 Codex 的收益 | +| [已安装 Codex CLI 案例](docs/09-reviews/2026-09-07-codex-first-use-release.md) | 发布包的一次运行在默认时限内通过，早期失败记录保留 | 已有桌面任务接入或普遍成功率 | -[按版本区分的支持范围与证据 →](docs/00-overview/harness-support.md) +这些案例由维护者操作。消息送达不等于成功：接收方的实际修改还必须同时满足新要求与先前约定。 +[证据索引](docs/evidence/README.md) 和 [兼容记录](docs/00-overview/harness-support.md) +也保留了范围更窄的检查、失败和未验证路径。 -## 日常能帮什么忙 +## 支持哪些 harness -- **“我已经跟另一个 Agent 说过了。”** 把接口变更、批准的命名或调研发现交给 - 真正需要它的工作流，省掉人工转述。 -- **“别把之前确认的决策丢了。”** 发布选定的约束、保存 checkpoint， - 而不是广播整段私聊。 -- **“额度满了，任务才做一半。”** 把最近保存的目标、决策、约束和下一步交给 - 另一家 harness。 +| 接入 | 入口与边界 | +|---|---| +| **Codex 桌面** | 基于原生任务工具的可选 Skill，工具是否可用取决于宿主 | +| **Codex CLI / 项目** | App Server 示例任务对；项目会话使用限定范围的 MCP 与 hook | +| **Pi** | 原生扩展；可选空闲唤醒，带忙碌回合检查 | +| **Kimi Code** | 项目 MCP 接入，不自动续跑空闲任务 | +| **DeepSeek Harness** | 已检查不调用模型的原生 MCP 接入；真实模型主动性未验证 | +| **其他 harness** | 通过 MCP 或 JavaScript SDK 接入，需要按宿主配置 | -这些是实际用法，不是所有场景都能成功的承诺。 +支持范围与版本有关，各路径证据程度不同。选择前请查阅 +[完整支持矩阵](docs/00-overview/harness-support.md)。 -### 从已保存的 checkpoint 继续 +## 从保存的 checkpoint 继续 -仅用于已经配置好的 workspace，不是 `try` 的临时样例。在该目录执行， -或显式提供 `--workspace /path/to/your/room`： +在已配置的 workspace 中，checkpoint 可以为新会话保留选定的目标、决策、约束和下一步： ```sh npx threadmesh status npx threadmesh continue backend --agent kimi --name recovery ``` -**必须先有 checkpoint**，目的地也必须有额度。保存由模型选择，不是保证执行的 -自动备份。这个命令用显式上下文启动一个**新的原生 session**，不迁移完整聊天、 -隐藏状态、权限或跨机器文件。真正的额度耗尽长会话恢复仍未验证。 - -[哪些内容能带走，哪些不能 →](docs/06-guides/portable-checkpoints.md) +从 workspace 目录运行，前提是已有 checkpoint，且目标 harness 有可用额度。 +这是显式上下文交接，不是完整对话备份或文件迁移。 +从真正耗尽额度的长任务中恢复仍未验收。 +[Checkpoint 指南 →](docs/06-guides/portable-checkpoints.md) -## Session 仍由你掌控 +## 你的会话仍由你控制 -在 workspace 路径，加入只共享公布的目标和建议，不扫描全部私聊。读收件箱不会消耗消息，接受建议 -不等于任务完成。Pi 的空闲续接需要明确开启。使用 `npx threadmesh status` 查看， -或用 `npx threadmesh mute client` 静音。 +原生 Skill 遵循你选择的任务、话题与发送权限；收到建议不代表获得回复权限。 +它不能强制保证隐私，也无法把检查空闲和随后发送变成一个原子操作；宿主权限仍然生效。 -当前是**同一所有者的本地实验版**，不是多租户安全边界。它不会自动接入任意旧 tab、 -唤醒所有 Agent 产品，也不保证工作一定正确。宿主原有的工具权限仍然适用。 -桌面 Skill 则使用 Codex 原生历史和模型遵循的规则；workspace 的收件箱与静音命令 -不能控制这条独立路径。 +Workspace 路径分享发布的目标与建议，而非整段私有对话。 +读取收件箱不会消费消息，接受建议也不代表完成工作。 +它的收件箱与静音控制独立于原生 Skill。 +这是**实验性的、同一所有者使用的本地系统**，不构成多租户安全边界。 -[安全模型](docs/04-safety/threat-model.md) · [安全报告](SECURITY.md) +[安全模型](docs/04-safety/threat-model.md) · [安全政策](SECURITY.md) -## 一起把它做得真正有用 +## 一起改进 -下一步：先让同一产品的多 session 协作容易上手，保留完整业务约束， -验证真实历史 session 的连续性与独立用户体验。 -[当前聚焦事项](https://github.com/fyaic/threadmesh/issues/156) · [路线图](ROADMAP.md) +欢迎反馈看不懂的配置步骤、遗漏的业务约束，或不该发送的消息。 +请注明接入路径和第一个失败步骤，并去掉凭证与私有对话内容。 +开发适配器可从 [SDK 指南](docs/06-guides/implement-an-adapter.md) 开始。 -欢迎报告**第一个失败步骤**、沉默的 Agent、无关消息，或一次真正有用的协作。 -Harness 开发者可从 [workspace/MCP 接入](docs/06-guides/first-workspace.md#kimi-and-custom-harnesses) -或 [SDK adapter 指南](docs/06-guides/implement-an-adapter.md)开始。 +当前维护重点是清晰的安装指引和准确的能力描述。真实项目验证暂缓； +安装、独立用户首用和相对原生用法的收益验证仍然开放，没有标记通过。 +[当前状态](docs/10-planning/project-status.md) · [路线图](ROADMAP.md) -[报告第一次使用](https://github.com/fyaic/threadmesh/issues/new?template=operator.yml) · -[讨论场景](https://github.com/fyaic/threadmesh/discussions) · +[反馈使用体验](https://github.com/fyaic/threadmesh/issues/new?template=operator.yml) · +[讨论使用场景](https://github.com/fyaic/threadmesh/discussions) · [参与贡献](CONTRIBUTING.md) · [中文文档](docs/zh-CN/README.md) -如果它帮你省了一次交接，欢迎 star，让更多人发现它。[Apache 2.0](LICENSE)。 +[Apache 2.0](LICENSE)。 diff --git a/ROADMAP.md b/ROADMAP.md index 229f6fa..312c187 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,41 +1,35 @@ # Roadmap -ThreadMesh uses milestone exit criteria rather than date promises. Priorities -may change as the safety and adapter contracts become clearer. See the -[current status](docs/10-planning/project-status.md) and -[active acceptance](docs/10-planning/desktop-entry-2026-09-07.md) for the -evidence-backed snapshot, current product decision, and ordered workstreams. - -The roadmap now optimizes for one outcome: **parallel agent sessions hand off -completion, blockers, review findings, and dependency-ready state without the -user acting as their message bus**. ThreadMesh is the attention and admission -policy layer; A2A, Cotal, ACP, or harness-native APIs may supply transport. - -## Current increment — install and measured value (2026-10-10) - -Keep the existing-task product target below. The next bounded use case is a real -API contract change reaching its dependent client task, preserving that task's -prior decisions. Work on the supported plugin entry and the native-only value -comparison together, before extending adapters or coordination infrastructure. - -- Provide a discoverable plugin package and short scoped activation. Check - installation, new-chat availability and existing-chat adoption separately. -- Make return-message permission, stopped-receiver behavior and API constraints - explicit in the native skill. Guidance does not create a durable queue or an - atomic idle-only send operation. -- Use the [small matched acceptance](docs/10-planning/native-value-acceptance-2026-10-10.md). - Native-only Codex gets the same tools and user permission; installation and - setup count toward ThreadMesh's cost. Keep unrun results unfilled. -- Continue only if useful outcomes justify the added setup. If both routes need - no relaying and the skill adds no observable benefit, retain a small optional - skill. Independent first-user success remains a separate gate. - -The September 8 controlled API case is already complete. Repeating it, adding a -website, or running a new CLI pair does not close these remaining gates. - -## Active priority — existing desktop clients (2026-09-08) - -**Current order, confirmed by the user:** independent first use → visible local +ThreadMesh aims to help selected agent tasks share useful changes while keeping +their own context and decisions. The Codex skill uses native task tools; the +local workspace provides a separate persistent inbox and checkpoint path. +See [current status](docs/10-planning/project-status.md) for capability and +evidence boundaries. Milestones below are historical plans, not delivery dates. + +## Current increment — repository clarity (2026-10-10) + +[PR #183](https://github.com/fyaic/threadmesh/pull/183) is merged: it adds the +Codex marketplace entry and tightens scoped collaboration guidance. Actual +installation, existing-task loading and independent first use remain unverified. +The skill has no measured advantage over native Codex alone. + +**Real-project validation is paused at the owner's request.** Current work is +repository maintenance: clear bilingual descriptions, usable documentation +navigation and accurate contribution/reporting instructions. Do not begin a +live business comparison or recruit participants as part of this increment. + +The [small matched comparison](docs/10-planning/native-value-acceptance-2026-10-10.md) +is retained for a later decision to resume. Its result cells remain unfilled. +No new adapter, coordination platform or website is needed for this work. + + + +## Prior priority — existing desktop clients (2026-09-08) + +The ordering below records the September plan. The October maintenance scope +and validation pause above take precedence; open acceptance criteria remain open. + +**September order:** independent first use → visible local status and stop → demonstrated relay savings → a real user case → DeepSeek and quota handoff. Work happens in original local agent conversations. The website helper is removed, including its code, browser-only tests and deployment workflow. @@ -50,9 +44,9 @@ is the first-use target. Manual prompt setup is a fallback, not completion. | 4 | Others can understand and reproduce the value | A consented real native recording and independent case, followed by relevant community sharing. No recreated conversation or promised star count. | | 5 | Extend a proven useful workflow | Provider-configured DeepSeek initiative, then continuation from an actual quota-blocked task's already saved checkpoint. Neither has a completed live acceptance. | -Orders 1 and 2 form the immediate product work: fix observed local usability -while seeking an independent participant, without pretending an internal test -is that participant. The old #91/#93 multi-role loop and #7 formal review remain +Orders 1 and 2 defined the next validation work in September. Independent +participant recruitment is now deferred along with real-project validation; +an internal test cannot replace independent first use. The old #91/#93 multi-role loop and #7 formal review remain separate open tracks, not new prerequisites for this desktop-first alpha. ### Completed evidence — do not repeat as a new gate @@ -486,5 +480,5 @@ prototype inference. - Kimi flagship-loop parity, new harnesses, external verifier service design, and further Git-evidence generalization until the real Codex chain is retained. Existing foundations remain available for reuse after that gate. -- Inspector and README presentation polish that does not record new product - evidence. +- Cosmetic inspector work without a concrete usability need. Repository copy + and navigation maintenance are explicitly in scope for the October increment. diff --git a/docs/00-overview/product-guide.md b/docs/00-overview/product-guide.md index 55bab40..abd454b 100644 --- a/docs/00-overview/product-guide.md +++ b/docs/00-overview/product-guide.md @@ -1,91 +1,83 @@ # What ThreadMesh is -ThreadMesh offers an explicit local workspace for supported integrations and an -optional skill workflow over Codex's native task tools. The aim is simple: -**you should not have to relay every useful change between agents yourself**. +ThreadMesh helps independent agent tasks share relevant changes while keeping +their own context and decisions, reducing the information you carry between chats. -Codex already supplies native cross-task communication on the tested host. The -skill did not invent it, and may be unnecessary if native use meets your needs. -[Native capabilities versus ThreadMesh's current value](native-capabilities-and-value.md). +For example, one agent changes an API while another maintains its client. +The client needs the new pagination rules, but must keep its existing timeout +and retry behavior. Useful collaboration means the receiving agent makes the +right change in its own task—not merely that a message arrives. -A session is one agent conversation with its own task and context. A harness -is the application running it, such as Codex or Pi. ThreadMesh connects opted-in -workstreams; it does not merge their conversations or become their model. +## Two ways to use it -## The concrete problem +| Path | What it provides | Entry and status | +|---|---|---| +| Codex native-task skill | Sharing scope and handoff guidance using Codex's own task tools | [Candidate plugin](../06-guides/codex-native-tasks.md); installed use and old-task loading unverified | +| Local workspace | Peer discovery, persistent advice inboxes and portable checkpoints for supported agent applications | [CLI v0.1.0-alpha.3](../06-guides/first-workspace.md); distributed as a GitHub package | -You have Codex changing an API and Pi maintaining its client. When pagination -changes, the client needs that information. Normally you notice the dependency, -copy the change and explain it in the other session. +The skill is optional when Codex already meets your needs. It does not supply +native messaging or the workspace's storage. Its added value over using Codex +directly has not been measured. See [native capabilities and current value](native-capabilities-and-value.md). -With the workspace integration: +The CLI sample starts new sessions, not existing desktop chats. Codex, Pi, Kimi +and DeepSeek have different [capabilities and evidence](harness-support.md). +A “session” is a conversation; a “harness” is the application running it. -1. You publish each session's work goal once. -2. The agents receive collaboration tools and generic task-time guidance. -3. A model decides whether a discovered peer needs useful information. -4. Advice enters a persistent inbox. The recipient judges it against its task. -5. An opted-in idle Pi can continue in its same session and act on the advice. +## How workspace collaboration works -The [real Codex → Pi API case](../09-reviews/2026-09-05-workspace-awareness.md#ordinary-codex--pi-api-case-pass) -completed that path and passed a client behavior check. Pi had first volunteered -its dependency; Codex replied after its ordinary API task. No human relayed it. - -## What exists today +1. You publish a work goal for each participating session. +2. Agents receive peer tools and task-time collaboration guidance. +3. A model decides whether another task needs a relevant change or question. +4. Advice enters a persistent inbox. The recipient checks it against its own task. +5. Where supported and explicitly enabled, an idle recipient continues in the + same session and works on the advice. -- A local CLI to initialize a room, launch named workstreams, inspect and mute. -- Four model tools: discover peers, send advice, read/decide inbox messages, - and save a portable checkpoint. -- Pi native integration and Codex/Kimi/official DeepSeek launch paths, with - different evidence levels and wake capabilities. -- An explicit checkpoint command for starting a new harness with saved context. -- A reusable core coordinator, MCP entry point and lower-level JavaScript SDK. - -See the [versioned support matrix](harness-support.md), not just a product logo. -The current package has runtime dependencies and is GitHub-distributed alpha; -it is not a production service or an npm-published release. +The [Codex → Pi API case](../09-reviews/2026-09-05-workspace-awareness.md#ordinary-codex--pi-api-case-pass) +completed this path and passed a client behavior check. Pi first volunteered +its dependency; Codex replied after its ordinary API task. No human relayed it. +Automatic continuation is integration-specific, not a property of every inbox. -## What the “intelligence” means +## What is available -Models choose relevance and message content under configured collaboration -guidance. In the workspace route, ThreadMesh supplies discovery, persistence and -adapter integration. In the native skill route, Codex supplies the transport, -source attribution and continuation. Neither route guarantees useful choices. +The CLI creates a local room, launches named tasks and lets you inspect or mute +them. Four model tools cover discovery, advice, inbox decisions and checkpoints. +Checkpoints supply saved context to a new session in a supported application. -A real unrelated-change control stayed quiet despite available peer/inbox tools. -A second copy case delivered and resumed correctly but lost a free-plan qualifier. -**A successful message is not a verified business result.** -[Successes and failures](../09-reviews/2026-09-05-workspace-awareness.md). +Developers can use [MCP](../06-guides/first-workspace.md#kimi-and-custom-harnesses) +or the [SDK](../06-guides/implement-an-adapter.md). The CLI requires Node and +runtime dependencies; it is not an npm-registry release. -## Who it helps—and who it does not +## Evidence and limitations -Try it if you already run parallel agent tasks and repeatedly copy API decisions, -approved constraints or research findings between them. Harness developers can -use the [MCP surface](../06-guides/first-workspace.md#kimi-and-custom-harnesses) -or [SDK adapter contract](../06-guides/implement-an-adapter.md). +Models choose relevance and message content under collaboration guidance. +ThreadMesh does not guarantee those choices. An unrelated-change control stayed +quiet, while a copy case delivered and resumed but omitted a free-plan qualifier. +**Successful delivery is not a verified business result.** +[Read the successes and failures](../09-reviews/2026-09-05-workspace-awareness.md). -For a single conversation or a fully predetermined workflow, the extra -coordination may be unnecessary. This alpha is a same-owner local setup, not an -open agent network, multi-tenant security boundary or arbitrary-tab connector. +Controlled native-task and CLI samples produced useful edits. Desktop-plugin +adoption, old-task loading, independent first use and gains over native Codex +remain unverified. Preview agents are simulated; DeepSeek lacks live initiative +evidence. See the [case portfolio](../06-guides/real-world-cases.md). ## Context and control -Published goals and peer advice are shared; private histories are not scanned. -Inbox reads do not consume messages. Acceptance is a separate disposition, not -proof that work passed tests; workspace advice may be shown to the model so it -can decide what to do. Pi idle follow-up requires explicit opt-in. - -Portable checkpoints carry selected working context, not hidden state, tool -permissions or a lossless transcript. Actual quota-blocked long-session recovery -and native prior-session adoption remain open checks. - -## Start here - -[First workspace](../06-guides/first-workspace.md) · -[Real cases](../06-guides/real-world-cases.md) · -[Checkpoint guide](../06-guides/portable-checkpoints.md) · -[Safety model](../04-safety/threat-model.md) · -[Roadmap](../../ROADMAP.md) - -For implementation details, read the [reference architecture](../02-architecture/reference-architecture.md) -and [protocol](../03-protocol/README.md). Historical benchmark records remain -available, but are not prerequisites for trying the current workspace. +Each route uses explicit participation and sharing scope, without merging chats +or globally scanning or broadcasting their histories. Native task reads stay +within the selected, authorized scope. The workspace shares published goals and +advice. Reading an inbox does not consume a message; +acceptance is a separate decision and is not proof that the resulting work passed. +Pi idle follow-up requires explicit opt-in. + +The native skill relies on the host's tools and permissions. Its guidance does +not enforce isolation or eliminate races with new user input. The workspace +alpha is a same-owner local setup, not a multi-tenant security boundary. +[Permissions and threats](../04-safety/threat-model.md). + +Checkpoints carry explicitly saved context, not hidden state, tool permissions +or a lossless transcript. Recovery of a real quota-blocked long conversation +remains unverified. [Checkpoint guide](../06-guides/portable-checkpoints.md). + +For a single conversation, or when native tools already cover coordination, +extra setup may not help. Implementation and history are linked from the +[documentation index](../README.md#explore-the-implementation). diff --git a/docs/10-planning/README.md b/docs/10-planning/README.md index 737a7ab..1757037 100644 --- a/docs/10-planning/README.md +++ b/docs/10-planning/README.md @@ -7,8 +7,9 @@ where the repository is now and what work should happen next. - [Project status](project-status.md) — evidence-backed snapshot of shipped, experimental, blocked, and unstarted work. - [Native value acceptance](native-value-acceptance-2026-10-10.md) — small matched - API-to-client comparison, separate installation gates and unrun result table. -- [Product mainline](product-mainline-2026-08-28.md) — current product thesis, + API-to-client comparison, currently paused; separate installation gates and + an unfilled result table. +- [Product mainline](product-mainline-2026-08-28.md) — August product thesis, community evidence, Now/Next/Later priorities, metrics, and stop conditions. - [M5 sprint 1](m5-sprint-1.md) — bounded parallel workstreams, dependencies, acceptance gates, risks, and the sequence into real-agent validation. @@ -20,10 +21,13 @@ where the repository is now and what work should happen next. role topology, model-owned tool turns, durable promotion sequence, recovery boundaries, and delivery slices for the live run. - [Mainline plan](mainline-plan.md) — completed protocol/runtime workstreams and - the transition from technical gates to the active product mainline. + the historical transition from technical gates to product work. - [Milestone acceptance audit](acceptance-audit.md) — criterion-by-criterion evidence and the remaining merge, real-product, and evaluation gaps. +Read the latest project-status entry first. Older plans retain their historical +priorities and do not override the current validation pause. + Status statements are dated and should be updated whenever a pull request materially changes a milestone exit criterion. GitHub milestones and issues are the source of truth for acceptance and closure. diff --git a/docs/10-planning/native-value-acceptance-2026-10-10.md b/docs/10-planning/native-value-acceptance-2026-10-10.md index 2e96f6e..3328bc2 100644 --- a/docs/10-planning/native-value-acceptance-2026-10-10.md +++ b/docs/10-planning/native-value-acceptance-2026-10-10.md @@ -1,8 +1,11 @@ # Native Codex value check -Date: 2026-10-10. Status: **planned; no new live or independent-user result**. +Date: 2026-10-10. Status: **paused at the owner’s request; no new live or independent-user result**. -The next question is whether ThreadMesh makes a real API-to-client dependency +This plan is retained for a later decision to resume. Do not begin business +trials or recruit participants under the current repository-maintenance scope. + +The question for a future trial is whether ThreadMesh makes a real API-to-client dependency change easier than native Codex alone. Reuse ordinary work and a small record; do not build another runner or sample project. The [September 8 API/client handoff](../09-reviews/2026-09-08-pairing-helper-acceptance.md) diff --git a/docs/10-planning/project-status.md b/docs/10-planning/project-status.md index 420ec87..cfdf10c 100644 --- a/docs/10-planning/project-status.md +++ b/docs/10-planning/project-status.md @@ -2,9 +2,9 @@ ## Current product update — 2026-10-10 -The current increment packages the native Codex skill for marketplace discovery -and short activation, with one concrete API-to-client workflow. Its supported -installation entry is documented in the [desktop guide](../06-guides/codex-native-tasks.md). +[PR #183](https://github.com/fyaic/threadmesh/pull/183) is merged. It packages the +native Codex skill for marketplace discovery and short activation, with +API-to-client collaboration guidance. Its candidate installation entry is documented in the [desktop guide](../06-guides/codex-native-tasks.md). Plugin discovery, installation, new-chat loading and existing-chat adoption are separate observations; none establishes the others. The desktop skill still uses Codex's native transport and supplies behavioral guidance. @@ -18,12 +18,18 @@ increment. The September 8 results below are historical, not validation of the changed skill. No new desktop success or comparative advantage is claimed. [Candidate checks and review](../09-reviews/2026-10-10-native-plugin-candidate.md). +**Current scope:** real-project validation is paused at the owner's request. +Repository maintenance now focuses on bilingual descriptions, documentation +navigation and contribution/reporting guidance. The comparison plan is retained +for later; no new business trial or independent-user recruitment is scheduled. +This pause does not close any outstanding acceptance gate. + ## Previous product update — 2026-09-08 **Install-and-use local collaboration is the product target; the website helper has been removed from source and deployment.** The manual recipe remains only an experimental fallback. Plugin installation and existing-task adoption are -still unverified, not replaced by a form or CLI sample. Follow the [new ordered acceptance](../../ROADMAP.md#active-priority--existing-desktop-clients-2026-09-08): +still unverified, not replaced by a form or CLI sample. The September plan set the [ordered acceptance](../../ROADMAP.md#prior-priority--existing-desktop-clients-2026-09-08): independent first use → visible local status/stop → measured relay savings → real user case → DeepSeek and quota continuation. No independent GUI success, persistent desktop control service or native-only advantage is claimed. @@ -127,7 +133,7 @@ The September 7 snapshot is 3 stars, 0 forks and one independent report; this sample does not establish a statistically highest-demand feature. Management correction: first-user success, not additional internal benchmarks, -is the delivery gate. Follow the [roadmap delivery checkpoint](../../ROADMAP.md#immediate-delivery-checkpoint--community-feedback). +is the delivery gate. Follow the [roadmap delivery checkpoint](../../ROADMAP.md#earlier-delivery-checkpoint--community-feedback). Same-product existing desktop conversations remain the main product goal; an easier developer entry is useful but must not be presented as desktop support. The earlier handoff repair at `613f5ca` is included in this delivery candidate. diff --git a/docs/README.md b/docs/README.md index 7aac541..0e69381 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,44 +1,56 @@ # ThreadMesh documentation -Connect independent agent sessions without relaying every useful change yourself. -Start with the user guides; the protocol and historical benchmarks are optional. +Help independent agent tasks share relevant changes while keeping their own +context. Choose the path that matches how you work. [Project overview](../README.md) · [中文文档](zh-CN/README.md) -## Choose your next step +## Choose a path -| I want to… | Start here | +| Your setup | What ThreadMesh adds | Start here | +|---|---|---| +| Selected Codex desktop tasks | An optional skill using Codex's own task tools | [Candidate plugin and native-task guide](06-guides/codex-native-tasks.md) | +| Locally launched agent sessions | A workspace with peer discovery, persistent advice inboxes and saved checkpoints | [CLI alpha.3: first workspace](06-guides/first-workspace.md) | + +These are separate entry points. The Codex skill does not provide the CLI's +persistent inbox or checkpoint storage. The CLI example starts new sessions; +it does not attach to your existing desktop chats. If native Codex already +meets your needs, the skill may add little. See [the capability comparison](00-overview/native-capabilities-and-value.md). + +## Find an answer + +| I want to… | Read this | |---|---| -| Understand the idea | [What ThreadMesh is](00-overview/product-guide.md) | -| Know whether native Codex is enough | [Native capabilities and added value](00-overview/native-capabilities-and-value.md) | -| Inspect the actual desktop exchange | [Retained messages, diff and audit](evidence/codex-native-2026-09-07/README.md) | -| Connect Codex, Pi, Kimi or DeepSeek | [Your first workspace](06-guides/first-workspace.md) | -| Explore existing Codex desktop tasks | [Experimental native-task workflow](06-guides/codex-native-tasks.md) | -| See actual model behavior | [Everyday cases and evidence](06-guides/real-world-cases.md) | -| Continue from saved context | [Portable checkpoints](06-guides/portable-checkpoints.md) | -| Check compatibility before installing | [Versioned harness support](00-overview/harness-support.md) | -| Integrate another harness | [MCP configuration](06-guides/first-workspace.md#kimi-and-custom-harnesses) · [SDK adapter guide](06-guides/implement-an-adapter.md) | -| Understand permissions and privacy | [Threat model](04-safety/threat-model.md) · [Context sovereignty](01-concepts/context-sovereignty.md) | -| Report an unsuccessful first run | [Operator report](https://github.com/fyaic/threadmesh/issues/new?template=operator.yml) | -| Follow what ships next | [Roadmap](../ROADMAP.md) · [Codex desktop priority](10-planning/desktop-entry-2026-09-07.md) | - -## Current evidence, not just intent - -The [Codex-first installed-package case](09-reviews/2026-09-07-codex-first-use-release.md) -passed with the default command in 272.604 seconds: model-selected advice, -same receiver continuation, its own correct copy edit and preserved earlier -decisions. Two new sessions, normal account quota; not existing desktop adoption. - -The [2026-09-05 cross-harness record](09-reviews/2026-09-05-workspace-awareness.md) -retains three ordinary Codex → Pi runs: API collaboration **passed**, unrelated -work stayed quiet, and brand-copy correctness **failed** despite successful -delivery and same-session continuation. Exact prompts, timelines and final -files are linked. Generic collaboration guidance and the initial Pi dependency -message are disclosed. - -Preview commands use simulated agents. DeepSeek's new integration has no-model -native evidence, not a live initiative pass. Checkpoint continuation has a -seeded-context test, not a lossless quota-blocked chat migration. +| Understand the use case and limits | [What ThreadMesh is](00-overview/product-guide.md) | +| Check supported products and versions | [Integration support matrix](00-overview/harness-support.md) | +| Continue from explicitly saved context | [Portable checkpoints](06-guides/portable-checkpoints.md) | +| Inspect actual model behavior | [Cases and evidence](06-guides/real-world-cases.md) · [Desktop messages and diffs](evidence/codex-native-2026-09-07/README.md) | +| Understand permissions and privacy | [Threat model](04-safety/threat-model.md) · [Context ownership](01-concepts/context-sovereignty.md) | +| Add another agent application | [MCP configuration](06-guides/first-workspace.md#kimi-and-custom-harnesses) · [SDK adapter guide](06-guides/implement-an-adapter.md) | +| Share an installation or collaboration problem | [Operator report](https://github.com/fyaic/threadmesh/issues/new?template=operator.yml) | +| Follow project priorities | [Roadmap](../ROADMAP.md) · [Current status](10-planning/project-status.md) | + +Real-project validation is currently paused; see [project status](10-planning/project-status.md). + +## What has been demonstrated + +Controlled Codex native-task exchanges produced receiver edits. Installed-plugin +use, old-task loading, independent first use and savings over native Codex remain +unverified. See the [desktop guide](06-guides/codex-native-tasks.md). + +A [CLI installed-package case](09-reviews/2026-09-07-codex-first-use-release.md) +used two new Codex sessions. The receiver correctly edited copy and preserved +earlier decisions. This does not establish existing desktop adoption or general +reliability. + +The [Codex → Pi record](09-reviews/2026-09-05-workspace-awareness.md) includes +an API collaboration pass, an unrelated-change case that stayed quiet and a +copy case that delivered successfully but omitted a required free-plan detail. +**Delivery alone is not a correct result.** + +Preview commands use simulated agents. DeepSeek has no-model integration checks, +not a live initiative pass. Checkpoint continuation has a seeded-context test, +not verified recovery of a quota-blocked long conversation. ## Explore the implementation @@ -49,13 +61,13 @@ seeded-context test, not a lossless quota-blocked chat migration. | [02-architecture](02-architecture/reference-architecture.md) | Reference components and lifecycle | | [03-protocol](03-protocol/README.md) | Draft protocol requirements | | [04-safety](04-safety/threat-model.md) | Threats, permissions and boundaries | -| [05-adapters](05-adapters/adapter-contract.md) | Harness integration contracts | +| [05-adapters](05-adapters/adapter-contract.md) | Integration contracts | | [06-guides](06-guides/first-workspace.md) | User and developer walkthroughs | | [07-research](07-research/research-synthesis.md) | Codex research, community signals and prior art | | [08-decisions](08-decisions/README.md) | Architecture decisions | | [09-reviews](09-reviews/README.md) | Dated evidence, failures and reviews | | [10-planning](10-planning/project-status.md) | Current status and historical milestone ledger | -| [zh-CN](zh-CN/README.md) | Chinese orientation and first-use guide | +| [zh-CN](zh-CN/README.md) | Chinese orientation and user guides | Machine-readable schemas live under [spec/schema](../spec/schema). Only documents explicitly labelled draft normative define protocol requirements; @@ -65,10 +77,6 @@ English is canonical for those requirements. The [attention-router demo](06-guides/attention-router-demo.md), [manual-relay baseline](06-guides/manual-relay-baseline.md) and -[non-interrupting handoff case](06-guides/non-interrupting-handoff.md) document -earlier experiments. They are **not first-use prerequisites**, a current speed -claim, or proof that every busy native session is safe to wake. - -For the deeper history, see the [case portfolio](06-guides/real-world-cases.md) -and [review index](09-reviews/README.md). Evidence labels distinguish real model -runs, deterministic fixtures, no-model preflights and unverified adapter targets. +[non-interrupting handoff case](06-guides/non-interrupting-handoff.md) are historical +experiments, not setup prerequisites, current speed claims or universal busy-session +safety evidence. Their records remain in the [review index](09-reviews/README.md). diff --git a/docs/zh-CN/README.md b/docs/zh-CN/README.md index 2c085a6..a000736 100644 --- a/docs/zh-CN/README.md +++ b/docs/zh-CN/README.md @@ -1,53 +1,63 @@ # ThreadMesh 中文文档 -让不同 Agent 的独立 session 自己分享有用变化，省掉你在聊天之间反复转述的工作。 -先看用户指南；不需要先读完协议，也不用运行旧的多角色验证流程。 +ThreadMesh 帮助独立的 Agent 任务分享相关变化，同时保留各自的上下文。 +先根据你的工作方式选择入口，无需先学习协议。 [项目首页](../../README.zh-CN.md) · [English docs](../README.md) -## 从你的问题开始 +## 选择使用路径 -| 我想…… | 推荐入口 | +| 你的使用方式 | ThreadMesh 提供什么 | 从这里开始 | +|---|---|---| +| 选定的 Codex 桌面任务 | 可选 Skill，约定共享范围与交接方式，使用 Codex 自带的任务工具 | [候选插件与原生任务指南](codex-native-tasks.md) | +| 在本地启动 Agent 会话 | 工作空间，提供任务发现、持久建议收件箱与保存的工作快照 | [CLI alpha.3：首次工作空间](first-workspace.md) | + +这是两个独立入口。Codex Skill 不提供 CLI 的持久收件箱或快照存储； +CLI 示例会创建新会话，不会接入已有桌面聊天。如果原生 Codex 已满足需要， +Skill 的增量可能很小，详见[原生能力与项目价值](native-capabilities-and-value.md)。 + +## 按问题查阅 + +| 我想…… | 推荐文档 | |---|---| -| 快速理解项目有什么用 | [ThreadMesh 是什么](product-guide.md) | -| Codex 原生已够用，还需要安装吗 | [原生能力与增量价值](native-capabilities-and-value.md) | -| 核查桌面演示的真实记录 | [消息、实际修改与审计证据](native-evidence.md) | -| 把自己的 Agent 接起来 | [第一次真实协作：中文上手](first-workspace.md) | -| 尝试已有 Codex 桌面任务 | [实验性原生任务流程](codex-native-tasks.md) | -| 看真正的模型主动行为 | [真实案例与证据](../06-guides/real-world-cases.md) | -| 换一家 Agent 继续已保存的工作 | [Checkpoint 与额度边界](../06-guides/portable-checkpoints.md) | -| 确认支持哪些产品和版本 | [Harness 支持矩阵](../00-overview/harness-support.md) | -| 给自己的 harness 增加能力 | [MCP 接入](../06-guides/first-workspace.md#kimi-and-custom-harnesses) · [SDK 指南](../06-guides/implement-an-adapter.md) | -| 了解权限和隐私 | [当前威胁模型](../04-safety/threat-model.md) · [上下文主权](../01-concepts/context-sovereignty.md) | -| 报告安装失败或 Agent 沉默 | [首次使用反馈](https://github.com/fyaic/threadmesh/issues/new?template=operator.yml) | -| 看下一步要做什么 | [Roadmap](../../ROADMAP.md) · [Codex 桌面主线](../10-planning/desktop-entry-2026-09-07.md) | - -## 当前真实进度 - -[Codex 默认安装包案例](../09-reviews/2026-09-07-codex-first-use-release.md)已在 -272.604 秒内通过：模型主动发出建议，同一个接收 session 继续，自己改对文案， -保留此前约定。使用正常账户额度；两个 session 是新建的，不是已有桌面对话接入证明。 - -[2026-09-05 验证记录](../09-reviews/2026-09-05-workspace-awareness.md)保留了三轮 -普通 Codex → Pi 任务：接口协作**通过**、无关变化不联系**通过**，品牌文案的 -业务完整性**失败**。后者虽然送达并唤起同一个接收 session，却漏了“免费方案”条件。 - -普通任务没有指定收件人或要求发送；通用协作提示已启用，Pi 先自主说明依赖， -Codex 随后回复。这是无需人工转述的双向协作，不是任意旧 tab 的自动接管。 - -- `preview` 是模拟 Agent 演示，不是模型主动性的证据。 -- DeepSeek 新接入通过无模型原生检查，真实模型主动协作仍未验证。 -- Checkpoint 携带显式保存的工作上下文，不是无损迁移整段聊天。 -- 原生忙碌输入竞争、真实历史 session 接入和独立用户上手仍有开放验收项。 - -## 用户、开发者与研究者 - -普通使用者从[上手指南](first-workspace.md)开始，观察真实产物，不只看“已收到”。 -开发者可复用四工具 workspace/MCP 接口；更底层的 SDK 与 adapter 是另一种接入层次， -详见[英文文档导航](../README.md)。 - -研究者可看[Codex 调研摘要](research-summary.md)、[社区研究](../07-research/community-signals.md) -和[架构决策](../08-decisions/README.md)。旧五角色流程、九次人工操作基线及历史测试 -数量不再作为当前入门主线；原始记录保留在[评审目录](../09-reviews/README.md)。 - -中文入口解释当前产品用法；标注为规范的协议文档仍以英文为准。 +| 理解用途与边界 | [ThreadMesh 是什么](product-guide.md) | +| 确认支持的产品和版本 | [接入支持矩阵](../00-overview/harness-support.md) | +| 从明确保存的上下文继续工作 | [Checkpoint 与额度边界](../06-guides/portable-checkpoints.md) | +| 核查模型实际做了什么 | [案例与证据](../06-guides/real-world-cases.md) · [桌面消息与修改记录](native-evidence.md) | +| 了解权限和隐私 | [威胁模型](../04-safety/threat-model.md) · [上下文归属](../01-concepts/context-sovereignty.md) | +| 接入另一种 Agent 应用 | [MCP 配置](../06-guides/first-workspace.md#kimi-and-custom-harnesses) · [SDK 指南](../06-guides/implement-an-adapter.md) | +| 反馈安装或协作问题 | [使用反馈](https://github.com/fyaic/threadmesh/issues/new?template=operator.yml) | +| 查看项目优先级 | [Roadmap](../../ROADMAP.md) · [当前状态](../10-planning/project-status.md) | + +当前暂缓真实项目验证，详见[项目状态](../10-planning/project-status.md)。 + +## 已有证据说明什么 + +受控的 Codex 原生任务协作产生过接收方自己的修改。插件安装后使用、旧任务加载、 +独立用户上手和相较原生 Codex 的收益仍未验证，详见[桌面指南](codex-native-tasks.md)。 + +[CLI 安装包案例](../09-reviews/2026-09-07-codex-first-use-release.md)使用两个 +新建 Codex 会话，接收方正确修改了文案并保留此前约定；不能据此宣称已有桌面 +任务接入或普遍可靠性。 + +[Codex → Pi 记录](../09-reviews/2026-09-05-workspace-awareness.md)包含接口协作 +通过、无关变化保持安静，以及一例消息送达但遗漏“免费方案”条件的文案失败。 +**消息送达不等于结果正确。** + +- `preview` 使用模拟 Agent，不是模型主动性的证据。 +- DeepSeek 通过无模型接入检查，真实模型主动协作仍未验证。 +- Checkpoint 通过预置上下文测试，尚未验证额度耗尽后的真实长会话恢复。 + +## 实现、研究与历史记录 + +实现细节见[参考架构](../02-architecture/reference-architecture.md)， +完整目录见[英文文档导航](../README.md#explore-the-implementation)。 + +研究资料包括[Codex 调研摘要](research-summary.md)、 +[社区研究](../07-research/community-signals.md)与[架构决策](../08-decisions/README.md)。 +历史的多角色流程、人工转述基线和非打断交接实验保留在 +[评审目录](../09-reviews/README.md)；它们不是安装前置条件、当前速度承诺， +也不能证明任意忙碌会话都可以安全唤醒。 + +[协议草案](../03-protocol/README.md)和[机器可读 schema](../../spec/schema) +供底层接入参考。只有明确标注为规范的文档定义协议要求，这些要求以英文为准。 diff --git a/docs/zh-CN/product-guide.md b/docs/zh-CN/product-guide.md index 8d7ce8f..5ef7163 100644 --- a/docs/zh-CN/product-guide.md +++ b/docs/zh-CN/product-guide.md @@ -1,75 +1,73 @@ # ThreadMesh 是什么 -ThreadMesh 提供明确共享的本地 workspace，以及基于 Codex 原生任务工具的可选 Skill 流程。 -目的很直接：**不再由你负责把每个有用变化转述给另一个 Agent。** +ThreadMesh 帮助独立 Agent 任务分享相关变化，保留各自上下文与约定， +减少你在聊天之间搬运信息的工作。 -Session 是一段有自己的任务和上下文的 Agent 会话；harness 是运行它的应用， -例如 Codex 或 Pi。ThreadMesh 连接明确加入的工作流，不合并聊天，也不是新模型。 +例如，一个 Agent 修改接口，另一个维护客户端。客户端需要新的分页规则， +但还要保留原有的超时与重试行为。有效协作意味着接收方在自己的任务里做出 +正确修改，而不只是收到一条消息。 -实测 Codex 宿主本来就能跨任务通信，Skill 并没有创造这项能力。 -原生功能够用就不必安装。[原生能力与项目当前价值](native-capabilities-and-value.md)。 +## 两种使用路径 -## 一个具体问题 +| 路径 | 提供什么 | 入口与状态 | +|---|---|---| +| Codex 原生任务 Skill | 使用 Codex 自带任务工具，约定共享范围与交接方式 | [候选插件](codex-native-tasks.md)；安装后使用与旧任务加载尚未验证 | +| 本地工作空间 | 为支持的 Agent 应用提供任务发现、持久建议收件箱和可携带的工作快照 | [CLI v0.1.0-alpha.3](first-workspace.md)；通过 GitHub 安装包分发 | -你让 Codex 改接口，Pi 维护客户端。分页方式变了，客户端也需要知道。 -通常你得自己发现依赖、复制变化、切换 session，再讲一遍。 +如果原生 Codex 已满足需要，Skill 是可选的。它不提供底层原生通信，也不包含 +工作空间的存储。相较直接使用 Codex，它的增量收益尚未测量。 +详见[原生能力与当前价值](native-capabilities-and-value.md)。 -接入后的路径是： +CLI 示例创建新会话，不接入已有桌面聊天。Codex、Pi、Kimi 和 DeepSeek 的 +能力与证据不同，详见[支持矩阵](../00-overview/harness-support.md)。 +文档中的 session 指一段 Agent 会话，harness 指运行它的应用。 -1. 你为每个 session 公布一次工作目标。 +## 工作空间如何协作 + +1. 你为每个参与会话公布工作目标。 2. Agent 获得协作工具和通用的任务起始提示。 -3. 模型判断哪个 peer 真正需要当前信息，决定是否发送。 +3. 模型判断哪个任务需要相关变化或问题，决定是否发送。 4. 建议进入持久收件箱，接收方结合自己的任务判断。 -5. 明确开启空闲续接的 Pi 可以在同一个 session 中继续处理。 - -[真实 Codex → Pi 接口案例](../09-reviews/2026-09-05-workspace-awareness.md#ordinary-codex--pi-api-case-pass) -跑通了这个路径，并通过客户端行为检查。Pi 先自主说明依赖，Codex 完成普通接口 -任务后回复变化。用户没有转述消息。 +5. 在支持且明确开启续接的接入方式中，空闲接收方在同一个会话继续工作。 -## 当前有哪些能力 +[Codex → Pi 接口案例](../09-reviews/2026-09-05-workspace-awareness.md#ordinary-codex--pi-api-case-pass) +跑通了这个路径，并通过客户端行为检查。Pi 先自主说明依赖，Codex 完成普通 +接口任务后回复，用户没有转述消息。能否自动续接取决于具体接入， +并不是每个收件箱都能唤醒任务。 -- 本地 CLI：创建工作空间，启动有名字的工作流，查看状态和静音。 -- 四个模型工具：发现 peer、发送建议、读取与处置 inbox、保存 checkpoint。 -- Pi 原生扩展，以及 Codex/Kimi/官方 DeepSeek 启动路径；验证程度与唤醒能力不同。 -- 用明确保存的 checkpoint 启动另一家 harness，携带选定的工作上下文。 -- 可复用的核心协调器、MCP 入口和更底层的 JavaScript SDK。 +## 当前可用的部分 -接入名称不等于效果保证，请看[按版本区分的支持矩阵](../00-overview/harness-support.md)。 -当前是有运行时依赖、从 GitHub 分发的 alpha，不是已发布到 npm 的生产服务。 +CLI 可创建本地协作空间、启动任务、查看状态和静音。四个模型工具支持 +任务发现、建议、收件箱处置和快照；快照可向受支持应用的新会话提供保存的上下文。 -## “主动智能”在哪里 +开发者可使用 [MCP](../06-guides/first-workspace.md#kimi-and-custom-harnesses) +或 [SDK](../06-guides/implement-an-adapter.md)。CLI 需要 Node 和运行时依赖， +并未发布到 npm 仓库。 -模型在配置好的协作提示下判断相关性和消息内容。Workspace 路径由 ThreadMesh 提供 -发现、持久化和适配器接入；原生 Skill 路径的通信、来源标记和续跑来自 Codex。 -两条路径都不保证模型每次选择正确。 +## 证据与局限 -一次真实无关修改在工具可用时保持安静。另一条文案案例虽成功送达并续接， -却丢了“免费方案”的限制。**消息成功，不等于业务结果正确。** +模型在协作提示下选择消息内容并判断相关性，ThreadMesh 不保证这些选择总是正确。 +一次无关修改对照保持安静；另一条文案案例成功送达并续接，却漏了“免费方案”条件。 +**消息送达不等于业务结果正确。** [成功与失败记录](../09-reviews/2026-09-05-workspace-awareness.md)。 -## 适合谁，不适合谁 - -如果你同时运行多个 Agent，不断复制接口决策、批准的约束或调研发现，值得试用。 -Harness 开发者可接 [MCP](../06-guides/first-workspace.md#kimi-and-custom-harnesses) -或 [SDK adapter](../06-guides/implement-an-adapter.md)。 - -如果只有一个聊天，或全部交接步骤已固定，这层协作可能没有必要。 -当前是同一所有者的本地设置，不是开放 Agent 网络、多租户安全边界或任意旧 tab 连接器。 +受控原生任务和 CLI 样例产生过有效修改，但桌面插件使用、旧任务加载、独立用户 +上手和相较原生 Codex 的收益仍未验证。Preview 使用模拟 Agent；DeepSeek +缺少真实模型主动协作证据。详见[案例汇总](../06-guides/real-world-cases.md)。 ## 上下文和控制权 -共享的是公布的目标与建议，不扫描全部私聊。读 inbox 不会消耗消息； -是否接受是单独的处置，也不是业务检查通过的证明。Workspace 可以先把建议作为 -非权威上下文给模型判断。Pi 空闲续接需要明确开启。 - -Checkpoint 携带选定的工作上下文，不携带隐藏状态、工具权限或无损聊天历史。 -真正的额度耗尽长任务恢复、原生历史 session 接入仍待验收。 +两条路径都要求明确参与和共享范围，不合并聊天、不全局扫描或广播聊天历史。 +原生任务读取限于选定且获授权的范围；工作空间共享公布的目标与建议。 +读取收件箱不会消耗消息；是否接受是单独的 +决定，也不是后续工作已通过检查的证明。Pi 空闲续接需要明确开启。 -## 从哪里开始 +原生 Skill 依赖宿主提供的工具与权限，其提示不能强制隔离，也不能消除发送 +与用户新输入之间的竞争。工作空间 alpha 面向同一所有者的本地使用， +不构成多租户安全边界。详见[权限与威胁模型](../04-safety/threat-model.md)。 -[中文上手](first-workspace.md) · [真实案例](../06-guides/real-world-cases.md) · -[Checkpoint 指南](../06-guides/portable-checkpoints.md) · -[安全模型](../04-safety/threat-model.md) · [Roadmap](../../ROADMAP.md) +工作快照携带明确保存的上下文，不携带隐藏状态、工具权限或完整聊天历史。 +真实额度耗尽后的长会话恢复仍未验证。[Checkpoint 指南](../06-guides/portable-checkpoints.md)。 -实现细节见[参考架构](../02-architecture/reference-architecture.md)和 -[协议](../03-protocol/README.md)。历史 benchmark 继续保留，但不是当前上手的前置条件。 +只有一个聊天，或原生工具已能完成协调时，额外设置可能没有收益。 +实现与历史记录入口见[文档导航](README.md#实现研究与历史记录)。