@kyun.si/agent2cursor 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.1 — 2026-10-28
+
+- Ship the reviewed English and Chinese READMEs in the npm package, including global installation, one-off npx usage, Claude/Codex/mixed conversion, generated-project validation and the SDK playground command.
+- Clarify language options, the fixed Chinese demos, copied script paths, current verification counts and historical model-run evidence.
+- Report converter version 0.1.1 in the CLI. Migration behavior and the pinned target SDK 0.3.0 are unchanged; generated projects and demos keep their own initial package versions.
+- Preserve the version-bound npm 0.1.0 publication receipt separately.
+
+## 0.1.0 — 2026-10-28
+
+- First public npm release as `@kyun.si/agent2cursor`, providing the `agent2cursor` command for Claude Code/Codex subagents and Agent Skills to Cursor Agent SDK projects.

package/CONTRIBUTING.md

@@ -0,0 +1,92 @@
+# Contributing and Maintainer Guide
+
+This document covers local development, verification workflows, demo regeneration, and repository safety rules for `agent2cursor`. For user-facing usage and migration behavior, see [README.md](README.md) ([中文说明](README.zh-CN.md)).
+
+## Prerequisites
+
+- **Node.js `>=22.13`** (enforced at CLI startup and in `package.json`).
+- **npm** (used with `package-lock.json`).
+
+Offline unit tests and fixture conversions do not require a Cursor account or network access.
+
+## Project Naming
+
+The public npm package is `@kyun.si/agent2cursor`. Use `agent2cursor` for the executable, generated-code notices, demo names, and repository links. The source workspace keeps `private: true`; the consumer archive omits it. The old executable name is not installed as an alias. Demo workspace snapshots use `.agent2cursor/pr-review.json`, disabled script stubs return `AGENT2CURSOR_STUB_DISABLED`, and the optional merge gate uses `AGENT2CURSOR_ALLOW_MERGE` (disabled by default).
+
+Historical evaluation reports and hash-bound evidence retain the names and paths used by those runs. Do not rewrite them to imply the current sources were evaluated.
+
+## Build and Unit Tests
+
+Run the TypeScript compiler and the automated tests before delivering changes:
+
+```bash
+npm ci --ignore-scripts
+npm run check
+```
+
+Individual scripts defined in [package.json](package.json):
+
+| Command | Purpose |
+| --- | --- |
+| `npm run build` | Compile TypeScript (`src/` to `dist/`) via `tsc` |
+| `npm test` | Run the test suite (`tsx --test test/*.test.ts`) |
+| `npm run check` | Run `npm run build && npm test` |
+| `npm run dev -- <args>` | Run `src/cli.ts` directly via `tsx` |
+| `npm run test:sdk` | Run structural SDK verification via `scripts/verify-sdk.mjs` |
+
+## Structural SDK Verification (`.validation/`)
+
+SDK integration tests install `@grok/agent-sdk@0.3.0` into the gitignored `.validation/` directory and invoke only its public CLI (`validate`, `info`, `eval --list`), followed by strict TypeScript typechecking on generated projects:
+
+```bash
+npm run build
+npm install --prefix .validation --ignore-scripts --no-audit --no-fund @grok/agent-sdk@0.3.0
+npm run test:sdk
+```
+
+Never vendor SDK source code or bundled SDK documentation into the repository.
+
+Generated projects live in system temporary directories outside this checkout. The check verifies default conversion and a failing `doctor` before installing each project's own dependencies without lifecycle scripts, then runs validation, strict TypeScript and eval discovery. Do not generate these projects under `.validation/`: its dependencies would mask first-run failures. Sanitized evidence stays in `.validation/acceptance-*/`.
+
+## Regenerating Demos
+
+The two demos ([demos/full-send](demos/full-send) and [demos/pr-review](demos/pr-review)) are generated from the pinned [t3dotgg/tstack](https://github.com/t3dotgg/tstack) MIT snapshot in [fixtures/tstack](fixtures/tstack) (`7de017b3fc9d50c03cf3ecb98fb71e0ca65a78bd`) and templates in `scripts/demo-templates/`:
+
+```bash
+node scripts/build-demos.mjs
+```
+
+After regenerating demos, run `npm run check` to verify that provenance hashes, license files (`LICENSE-tstack`), and channel/snapshot templates remain in sync.
+
+## npm Release
+
+The public GitHub repository and the npm registry are separate destinations. Keep the source workspace private to npm with `private: true`. `pack:local` builds a clean consumer archive named `kyun.si-agent2cursor-<version>.tgz` under `.validation/npm-release/`, with the scoped package name, public access, the official registry, and the source Git revision. The archive contains the explicit `files` allowlist and omits development dependencies and lifecycle scripts.
+
+```bash
+npm run check
+npm run pack:local
+npm run verify:package
+npm run publish:npm -- --dry-run
+npm run publish:npm
+```
+
+Before the real publish, install the archive into an independent consumer and verify the actual `agent2cursor` executable, conversion, demos, and doctor. `publish:npm` verifies the recorded source hashes, Git revision, archive size and SHA-256, and publishes that same archive without repacking. Any changed input requires rebuilding and rechecking. Login and two-factor authentication stay in npm's own flow; no credentials belong in source or evidence.
+
+CI uses `verify:package` to check the archive without publishing. npm rejects publishing an existing version even with `--dry-run`; after a version is released, bump the version before preparing its successor. Published bytes remain bound to the `sourceRevision` in the publication receipt.
+
+After publication, read the registry metadata and download its tarball anonymously. Verify SHA-256 and registry integrity against the candidate, then install `@kyun.si/agent2cursor@<version>` from the public registry into a clean consumer and repeat the CLI checks. Record the public metadata and verification results in `npm-publication.json`. Do not claim publication before this readback succeeds.
+
+## Evaluation Evidence
+
+Keep tests, demo eval suites and source fixtures with the implementation. [evaluation/README.md](evaluation/README.md) indexes the independent evaluation; `docs/evidence/` contains bounded, portable summaries. Local raw runs, generated projects and deployment workspaces are ignored. Preserve those artifacts locally when they are needed for an audit; do not stage them with a blanket `git add`.
+
+The maintained demo projects live only in `demos/`. Create personal deployment copies outside the repository or in the ignored `deployments/` directory. The README animation retains its editable source under `docs/demo-video/` and final media under `docs/assets/`.
+
+## Repository Rules and Safety Invariants
+
+1. **Account for every source field.** Every YAML frontmatter, Codex agent TOML, and `agents/openai.yaml` field path must appear in `MIGRATION.zh-CN.md` / `MIGRATION.en.md` as `mapped`, `degraded`, or `dropped`.
+2. **Never silently expand permissions.** Do not claim a root `tools` allowlist isolates `task` subagents, and never describe an agent with `shell` enabled as read-only.
+3. **Keep script tools disabled by default.** Source scripts under `skills/*/scripts/*` are copied without execution bits, and generated `bot/tools/*.ts` wrappers must remain disabled stubs (`AGENT2CURSOR_STUB_DISABLED`) until an operator implements a typed JSON stdin/stdout contract.
+4. **Safe filesystem handling.** Conversion must never execute source scripts, overwrite existing output directories, traverse symlinks, or read/copy credential files (`.env`, `.npmrc`, private keys, or sensitive YAML keys).
+5. **Keep evidence levels separate.** Do not conflate unit tests or `agent-sdk validate` / `eval --list` with live model execution, real GitHub webhook delivery, hosted deployment, or npm publication. See [docs/acceptance.md](docs/acceptance.md) and [docs/upstream-verification.md](docs/upstream-verification.md).
+6. **Credential-safe diagnostics.** Never write raw process `argv`, environment dumps, authentication files, or unfiltered runtime logs into diagnostics, tests, or committed evidence files.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eason Yang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,231 @@
-# Temporary Holding Version
+# agent2cursor
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Convert existing Claude Code and Codex subagents and Agent Skills into editable [Cursor Agent SDK](https://cursor.com/docs/agent-sdk) (`@grok/agent-sdk`) TypeScript projects, with routing eval scaffolds and a field-by-field migration report.
+
+[中文说明](README.zh-CN.md) · **0.1.1** · [MIT License](LICENSE) · Node **>=22.13** · Targets **`@grok/agent-sdk@0.3.0`**
+
+![Converting Claude subagents and skills into an Agent SDK project with a field-by-field migration report](docs/assets/agent2cursor-demo.gif)
+
+If you already wrote subagents in `.claude/agents/*.md` or `.codex/agents/*.toml`, or skill folders containing `SKILL.md` (including [t3dotgg/tstack](https://github.com/t3dotgg/tstack) workflows), `agent2cursor` turns those loose files into a standalone Cursor Agent SDK project. It generates editable source files, a per-field migration report, and initial routing evals—it does **not** migrate underlying models or chat history, and it does **not** guarantee preserved runtime behavior or subagent permission boundaries.
+
+```text
+.claude/agents/code-reviewer.md → bot/subagents/code-reviewer/{agent.ts,instructions.md}
+.codex/agents/reviewer.toml     → bot/subagents/<name>/{agent.ts,instructions.md}
+skills/<name>/SKILL.md          → bot/skills/<name>/SKILL.md
+skills/*/scripts/*              → bot/tools/*.ts (disabled JSON adapter stubs)
+source fields + routing checks  → MIGRATION.zh-CN.md (or .en.md) + evals/*.eval.ts
+```
+
+## Install and use
+
+Requires **Node.js >=22.13** and npm. The npm package is **`@kyun.si/agent2cursor`**; its command is **`agent2cursor`**. The examples below pin **0.1.1**. See [npm releases](https://www.npmjs.com/package/@kyun.si/agent2cursor) and the [version-bound publication receipt](https://github.com/mreasonyang/agent2cursor/blob/main/npm-publication.json) for published artifacts and installation verification.
+
+Run the input commands from the project containing your agents or skills. Choose either global installation or one-off `npx` usage below; both create the same SDK project.
+
+### Global installation
+
+```bash
+npm install --global @kyun.si/agent2cursor@0.1.1
+agent2cursor --help
+agent2cursor inspect .claude/agents --lang en
+agent2cursor convert .claude/agents --out ./my-agent --lang en
+```
+
+### Without global installation
+
+```bash
+npx --yes @kyun.si/agent2cursor@0.1.1 inspect .claude/agents --lang en
+npx --yes @kyun.si/agent2cursor@0.1.1 convert .claude/agents --out ./my-agent --lang en
+```
+
+Pass only paths that exist. Claude Code skills can be supplied as `.claude/skills`, or as an individual directory containing `SKILL.md`. A standalone agent file, an agent directory, or a skill directory can be used alone; multiple inputs can be combined. See [Codex inputs](#convert-codex-assets) below. The default report language is Chinese; these English examples select `--lang en` explicitly. Source instructions are preserved rather than translated.
+
+`inspect` writes nothing. `convert` creates a **new** output directory and refuses to overwrite an existing path. Review `my-agent/MIGRATION.en.md` and the generated `bot/` sources. Conversion does not install the target SDK or start a model. A fresh output normally reports `dependencies-missing` until its own dependencies are installed; this is not a successful SDK validation.
+
+### Validate and run the generated project
+
+From the directory where you created `my-agent`:
+
+```bash
+cd my-agent
+npm install
+npm run validate
+npx agent-sdk eval --dir . --list
+npx --yes @kyun.si/agent2cursor@0.1.1 doctor --dir .
+```
+
+These are structural checks and eval discovery; they do not run the model evals. The converter and generated SDK project have separate dependencies, so installing `agent2cursor` globally does not replace `npm install` inside `my-agent`.
+
+After reviewing the migration report, permissions, model selection, and disabled script stubs, you can optionally run a real model from the **generated project directory**:
+
+```bash
+npx agent-sdk login
+npm run dev -- --web
+```
+
+`npm run dev -- --web` starts the SDK development server and opens its playground. Send a request in the playground to invoke a model. Live execution requires a Cursor account with the appropriate model access. `--lang` selects generated instructions, reports, and eval prompts; it does not translate your original agents or skills.
+
+- **SDK package name:** [Official Cursor Agent SDK docs](https://cursor.com/docs/agent-sdk) specify **`@grok/agent-sdk`** (formerly `@cursor/bdk`). Generated `package.json` pins it to `0.3.0` and declares `zod` `^3.25.0`; see [upstream verification](docs/upstream-verification.md).
+- **Account requirements:** conversion and post-install structural checks (`inspect`, `convert`, `doctor`, `agent-sdk validate`, `agent-sdk eval --list`) need no Cursor login. `agent-sdk dev`, `agent-sdk run`, and actual model evals need login and model access. Optional `agent-sdk deploy` also needs hosting-enabled account/team and repository permissions.
+
+`convert` and `demo` exit 0 after writing output when dependencies are missing; `validation.status` is `dependencies-missing`, so validation has not run. After installing the output's dependencies, `doctor` exits 0 only when validation passes. A real validation failure makes `convert` / `demo` exit 1 even though their output has already been written. The converter never installs dependencies automatically.
+
+## Try the repository fixtures (optional)
+
+The npm package includes the two demos but **does not include `fixtures/`, the converter's `src/` directory, or its development toolchain**. To run the repository examples, use a separate source checkout:
+
+```bash
+git clone https://github.com/mreasonyang/agent2cursor.git
+cd agent2cursor
+npm ci --ignore-scripts
+npm run build
+
+node dist/cli.js inspect ./fixtures/claude ./fixtures/tstack/skills/full-send --with-deps --lang en
+node dist/cli.js convert ./fixtures/claude ./fixtures/tstack/skills/full-send \
+  --with-deps --lang en --out ../agent2cursor-fixture
+```
+
+On this fixture input, the converter generates **28 files**: 4 subagents, 5 skills (including 4 `tstack` dependencies), and 1 disabled script-tool stub. The report is `../agent2cursor-fixture/MIGRATION.en.md`. The output directory must not already exist; choose a different `--out` path when repeating the example. Apply the validation steps above inside `agent2cursor-fixture` after reviewing its report. These samples demonstrate conversion and structural checks, not preserved runtime permissions or live-model behavior.
+
+## Convert Codex assets
+
+Using the installed command (or replacing `agent2cursor` with `npx --yes @kyun.si/agent2cursor@0.1.1`), pass project or personal agent directories, a standalone TOML file, and/or skill directories. The mixed-input example is an alternative; pass only paths that exist:
+
+```bash
+agent2cursor inspect .codex/agents .agents/skills --lang en
+agent2cursor convert .codex/agents .agents/skills --out ./my-codex-agent --lang en
+# Optional: combine Claude, Codex, and skills
+agent2cursor convert .claude/agents .codex/agents .agents/skills --out ./mixed-agent --lang en
+```
+
+Use only paths that exist; either input can be used alone. Personal standalone agents under `~/.codex/agents` are also accepted. A project root discovers these agent trees and skill folders, while unrelated TOML files are ignored.
+
+| Codex input | Conversion |
+| --- | --- |
+| Standalone `name`, `description`, `developer_instructions` | Required non-empty strings; generates subagent ID, delegation description, and the parsed instruction text. Invalid files fail explicitly. |
+| `model` | Inherits the target parent by default. Use `--model-map source-id=target-id` or `--keep-model`; availability is not established by validation. |
+| `model_reasoning_effort`, `model_reasoning_summary`, `model_verbosity` | Reported as dropped; model-ID mapping does not migrate these parameters. |
+| `features.*`, `skills.*` | Reported as degraded; per-agent capability and skill restrictions are not enforced. Referenced skill paths are not read. |
+| Parent settings, including sandbox, approval, provider, and MCP | Not imported. These do not override the parent in a standalone Codex agent either. Configure the target environment explicitly. |
+| `agents/openai.yaml` | Copied unchanged. A valid `interface.default_prompt` becomes an eval trigger; every UI, policy, dependency, and unknown field receives a migration entry. Invocation policy is not enforced and MCP dependencies are not connected. |
+
+This supports **standalone Codex TOML agents → Cursor Agent SDK**, not whole-session migration or output for Codex. Parent `config.toml`, `AGENTS.md`, credentials, and legacy `[agents.<name>] config_file` declarations are not imported. Inherited instructions, tools, and skills must be reviewed separately. Codex tool references receive suggestions without automatic prompt rewriting. See the [Codex fixtures](fixtures/codex) and [verified scope](docs/upstream-verification.md#codex-input-adapter-2026-10-28).
+
+## When to Use agent2cursor
+
+`@grok/agent-sdk` already supports native skills and plugins. Choose the lightest path that fits your assets:
+
+| Approach | When to use it |
+| --- | --- |
+| Copy `SKILL.md` directly | You only have compatible `SKILL.md` directories and do not need subagent conversion, script stubs, or a migration report |
+| SDK `cursorPlugin()` | You have a Cursor/Claude plugin manifest and runtime mounting is enough |
+| `agent-sdk init --from automation:` / `migrate` | You are migrating a Cursor Automation or upgrading an older SDK project |
+| **`agent2cursor`** | You hold loose Claude `.md` / Codex `.toml` agents, skill directories, or `tstack` workflows and want editable SDK source, field-by-field loss accounting, foreign-tool warnings, disabled script stubs, and routing eval scaffolds |
+
+## What Gets Migrated (Example: `code-reviewer`)
+
+Given [`fixtures/claude/agents/code-reviewer.md`](fixtures/claude/agents/code-reviewer.md):
+
+```markdown
+---
+name: code-reviewer
+description: Review changed code for defects, maintainability, and missing verification.
+tools: Read, Grep, Glob
+model: sonnet
+---
+Review the changed code. Prioritize concrete defects and cite the affected file and line.
+Do not edit files. Explain what was verified and what remains uncertain.
+```
+
+`agent2cursor convert` emits `bot/subagents/code-reviewer/agent.ts`, writes the prompt body to `bot/subagents/code-reviewer/instructions.md`, and logs every frontmatter field in `MIGRATION.zh-CN.md` (or `MIGRATION.en.md`):
+
+```ts
+// bot/subagents/code-reviewer/agent.ts
+// Generated by agent2cursor. Review the migration report before running.
+import { defineAgent } from "@grok/agent-sdk";
+
+export default defineAgent({
+  description: "Review changed code for defects, maintainability, and missing verification.",
+  // TODO(agent2cursor): tools: Security boundary lost: task children retain the harness task-tool toolset; do not assume root allowlists constrain them. Reference name mapping (read, grep, glob). For enforced read-only access use separate agents or disable task and constrain execution separately; shell can write.
+  // TODO(agent2cursor): model: Omitted model to inherit the parent model; use --model-map to select a target model explicitly.
+});
+```
+
+<details>
+<summary><strong>Field-by-field disposition reference</strong></summary>
+
+| Source asset or field | SDK output location | Disposition | Behavior |
+| --- | --- | --- | --- |
+| Subagent `name` | `bot/subagents/<id>/` | `✅ Mapped` / `⚠️ Degraded` | `✅` when already a valid slug; `⚠️` when normalized or derived from the filename |
+| Subagent `description` | `bot/subagents/<id>/agent.ts` | `✅ Mapped` / `⚠️ Degraded` | `✅` when non-empty; `⚠️` with a generated placeholder when missing or blank |
+| Subagent Markdown body | `bot/subagents/<id>/instructions.md` | `✅ Mapped` / `⚠️ Degraded` | Unchanged bodies are mapped; appending a shared-skill preload hint is explicitly reported as degraded, with the original text retained |
+| Subagent `model` | `bot/subagents/<id>/agent.ts` | `✅ Mapped` / `⚠️ Degraded` | `inherit` is omitted (`✅`). Other IDs (`sonnet`, `opus`, `haiku`) are omitted by default (`⚠️`) to inherit the parent model unless mapped with `--model-map` (`✅`) or kept with `--keep-model` (`⚠️`) |
+| Subagent `tools` / `disallowedTools` | `MIGRATION.*.md` + `TODO(agent2cursor)` | `⚠️ Degraded` | Per-subagent tool lists are unsupported in SDK `0.3.0`; `task` children retain the harness `task` toolset |
+| Subagent `skills` | `bot/instructions.md` + `instructions.md` | `⚠️ Degraded` | Emits shared-skill loading hints (no native per-subagent preloading) |
+| `permissionMode`, `hooks`, `mcpServers`, `memory`, unknown agent fields | `MIGRATION.*.md` + `TODO(agent2cursor)` | `❌ Dropped` | No verified 1:1 SDK equivalent; documented in the report for manual implementation |
+| `SKILL.md` + supporting files | `bot/skills/<id>/**` | `✅ Mapped` / `⚠️ Degraded` | Keeps body, supporting files, and extra frontmatter (`license`, `metadata.*`); `name`/`description` degrade to `⚠️` if normalized/missing, and `allowed-tools` is marked `⚠️` |
+| `skills/*/agents/openai.yaml` | Copied metadata + `evals/skills.eval.ts` | `✅ Mapped` / `⚠️ Degraded` | Valid `interface.default_prompt` becomes an eval trigger; UI, invocation policy, tool dependencies, and unknown fields are reported individually as metadata without SDK runtime semantics |
+| `skills/*/scripts/*` | `bot/skills/<id>/scripts/*` + `bot/tools/<script>.ts` | `⚠️ Degraded` | Copies script without executable bits and emits a disabled `execution: "agent"` stub (`AGENT2CURSOR_STUB_DISABLED`) |
+
+</details>
+
+## CLI Reference
+
+| Command or flag | Description |
+| --- | --- |
+| `convert <input...>` | Convert Claude `.md` / standalone Codex `.toml` files, `.claude/agents/` / `.codex/agents/` trees, skill directories, or a `tstack` repo into a new SDK project |
+| `inspect <input...>` | Print the migration report (or `--json` summary) without writing files |
+| `demo <full-send\|pr-review>` | Export one of the two adapted `tstack` demo projects (`--out <dir>`, `--json`, `--no-validate`) |
+| `doctor [--dir <project>]` | Check Node `>=22.13` and run `agent-sdk validate` with credential-safe diagnostic summaries |
+| `--out <dir>` | New output directory for `convert` (default `./my-agent`; never overwrites existing paths) |
+| `--name <name>` | Generated agent name (`1–64` lowercase letters, digits, `-`, or `_`, starting with a letter or digit; default `converted-agent`) |
+| `--lang <zh\|en>` | `convert` / `inspect` output language (default `zh`); selects generated instructions, eval prompts, and report filename. Does not translate source text or the built-in demos |
+| `--with-deps` | Include sibling skills required by the `tstack` dependency graph |
+| `--model-map <map>` | Map source models explicitly, e.g. `--model-map sonnet=<account-verified-id>` (verify ID availability on your account) |
+| `--keep-model` | Keep unverified source model IDs as-is instead of omitting them to inherit |
+| `--root-tools <list>` | Explicit root allowlist (`read,grep,glob,ls,shell,edit,task,delete`); omitting preserves SDK defaults |
+| `--dry-run` / `--no-validate` / `--json` | Plan `convert` without writing files / skip `agent-sdk validate` / print machine-readable JSON |
+
+## Included Demos
+
+Both demos are adapted in Chinese from a pinned [t3dotgg/tstack](https://github.com/t3dotgg/tstack) MIT snapshot (`7de017b3fc9d50c03cf3ecb98fb71e0ca65a78bd`) and include `LICENSE-tstack` and `TSTACK-PROVENANCE.json`. They are included in the npm package and require no source checkout. Export either into a new directory:
+
+```bash
+agent2cursor demo full-send --out ./full-send-agent
+agent2cursor demo pr-review --out ./pr-review-agent
+```
+
+Use the same `npx --yes @kyun.si/agent2cursor@0.1.1` prefix if you chose the one-off route. The demos remain Chinese workflows; `demo` does not accept `--lang`. After export, run `npm install` and `npm run validate` inside the chosen demo directory.
+
+- **`full-send` ([operation guide](demos/full-send/README.md)):** five skills (`full-send`, `sol-loop`, `file-pr`, `babysit-pr`, `leaving-pr-comments`), a `reviewer` subagent, a one-shot read-only `pr_wait` snapshot tool (no polling), a disabled `pr_wait_script` stub alongside the retained Python `pr-wait` script, and a gated `merge_pr` tool. Its root tools exclude `shell`, so **it prepares local edits and a PR draft and stops before publishing or merging**—automatic test execution, `git push`, and PR creation are not implemented. `merge_pr` is off by default and requires `AGENT2CURSOR_ALLOW_MERGE=1`, human approval, a matching configured GitHub session, an open/non-draft/clean PR, and the exact current head SHA (eval sessions cannot merge).
+- **`pr-review` ([operation guide](demos/pr-review/README.md)):** `council` and `leaving-pr-comments` with three reviewer subagents (`reviewer-a`, `reviewer-b`, `reviewer-c`). All three inherit the same parent model, outputting a Chinese `Council review` table and an explicit notice that the review uses three perspectives on one model rather than three separate model providers. Its root tools are read/search/delegate only, and its authored tools never post comments or edit PR descriptions.
+
+Both demos disable their GitHub channel until `bot/lib/settings.ts` replaces `"OWNER/REPO"`. Even after configuring a repository, automatic reply comments, reactions, and `@mention` triggers remain disabled. `pr-review` pre-fetches a bounded, revision-checked diff snapshot on the host side before the sandboxed model turn; direct `pr_wait` calls from inside a sandboxed model turn remain unverified.
+
+## Limitations and Verification Status
+
+The [independent evaluation](evaluation/README.md) covers the corrected converter and revised routing evals. Earlier demo model runs and the signed PR replay were recorded before the rename from `cc2agent`; their [original evidence](docs/evidence/online-2026-10-27.json) retains its source hashes. These are separate runs, with their respective scope preserved.
+
+- **Tool-name scan coverage:** a fixed, case-sensitive identifier list detects `WebFetch`, `WebSearch`, `AskUserQuestion`, `request_user_input`, `delegate_task`, `orchestrator_capabilities`, `watch_pull_request`, `unwatch_pull_request`, and `Monitor` in bodies and supporting Markdown. Matches may include instructions prohibiting a call; absence of a match does not establish compatibility. Source prompts are not rewritten.
+- **Root allowlists do not isolate subagents:** `--root-tools` restricts the root agent only. In `@grok/agent-sdk@0.3.0`, `task` subagents retain the harness `task` toolset. Never assume a root allowlist makes child agents read-only, and never treat `shell` as read-only (it can write files and run arbitrary commands).
+- **Script tools are disabled stubs:** conversion never executes source scripts. Generated `bot/tools/*.ts` wrappers return `AGENT2CURSOR_STUB_DISABLED` until an operator audits the copied source in `bot/skills/<id>/scripts/*`, implements the JSON stdin/stdout contract, and enables `shell`.
+- **Input/output guard coverage:** conversion refuses to overwrite existing output directories, rejects symlinks, caps output at 128 MiB, skips or rejects known credential paths (`.env`, `.npmrc`, private key files), and rejects sensitive YAML/TOML keys (`token`, `apiKey`, `secret`). Parser diagnostics never echo source values. It does not scan arbitrary prose or binary attachments for secrets.
+
+**Verification summary (each evidence level is tracked separately):**
+
+| Evidence level | Status | What is and is not proven |
+| --- | --- | --- |
+| npm release & installation | **Tracked per version** | The [publication receipt](https://github.com/mreasonyang/agent2cursor/blob/main/npm-publication.json) records the exact published version, archive hash, anonymous installation, pinned/default `npx`, mixed conversion, both demo exports, and doctor checks. Historical receipts are retained separately |
+| Offline tests & SDK structure | **PASS — 74 tests** | Node 22.13 / 24 CI passed. Claude, Codex, tstack, full-send, and pr-review generated projects passed SDK structure checks, strict TypeScript and eval discovery with independent dependencies. `eval --list` proves discovery, not live execution. [CI](https://github.com/mreasonyang/agent2cursor/actions/workflows/check.yml) |
+| Independent conversion and routing evaluation | **PASS** (bounded dataset) | 24/24 normal conversions and post-install validations; revised generated routing evals passed 41/41 across 30 projects. Three real tasks, each repeated three times, matched direct-copy/plugin baselines. [Counts and source hashes](docs/evidence/independent-evaluation.json) |
+| Live model runs | **Historical PASS** (narrow cases) | Official `agent-sdk login` succeeded. `migration-smoke` passed (**1 case / 2 assertions**: `succeeded`, `loadedSkill`). `pr-review` council inline diff passed (**1 case / 9 assertions**, same model / 3 perspectives). `full-send` local `run` loaded the skill with 1 read call and 0 writes/execs/merges |
+| GitHub PR replay | **Historical PASS** (local replay) | [Historical test PR #1](https://github.com/mreasonyang/agent2cursor/pull/1) passed via HMAC-signed **local replay** (bounded snapshot + 3 reviewer delegates + Chinese table; 0 tool errors, 0 writes/execs, 0 GitHub comments/reactions/reviews; PR closed unmerged). Not a live hosted webhook delivery |
+| Cloud hosting | **Not run / On hold** | The last recorded `agent-sdk deploy --dry-run` stopped because the test account had no default team configured. Hosted deployment has not been completed; no verified deployment URL is available |
+
+The historical model and PR replay runs were not rerun for the Codex adapter, npm publication, or this documentation audit. These checks do not prove average model quality, multi-provider routing, or child-agent tool isolation. Full records: [acceptance results](docs/acceptance.md) · [upstream verification](docs/upstream-verification.md) · [sanitized online evidence](docs/evidence/online-2026-10-27.json) · [official example provenance](docs/official-examples.provenance.json).
+
+## Contributing and License
+
+Maintainer commands (`npm run check`, `npm run test:sdk`, `node scripts/build-demos.mjs`) and safety invariants are in [CONTRIBUTING.md](CONTRIBUTING.md). The source workspace keeps `private: true` to npm; `pack:local` creates a separate public archive. GitHub is public. Both language READMEs ship inside the npm package. Version `0.1.1` includes the reviewed installation and usage instructions; [CHANGELOG.md](CHANGELOG.md) records the documentation update.
+
+`agent2cursor` is MIT-licensed (`Copyright (c) 2026 Eason Yang`, [LICENSE](LICENSE)). The pinned snapshot in [`fixtures/tstack`](fixtures/tstack) ([`PROVENANCE.json`](fixtures/tstack/PROVENANCE.json)) and the adapted demos derive from [t3dotgg/tstack](https://github.com/t3dotgg/tstack), `Copyright (c) 2026 Theo Browne`, under the MIT license ([`fixtures/tstack/LICENSE`](fixtures/tstack/LICENSE) and `LICENSE-tstack`); recognized `tstack` inputs must retain this MIT notice. `@grok/agent-sdk@0.3.0` is a proprietary dependency (no SDK source or docs are vendored here). Not affiliated with or endorsed by Theo Browne, T3, Anthropic, Cursor, Anysphere, or xAI. See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

package/README.zh-CN.md

@@ -0,0 +1,231 @@
+# agent2cursor
+
+把已写好的 Claude Code / Codex 子代理（subagents）与 Agent Skills 整理成可编辑的 [Cursor Agent SDK](https://cursor.com/docs/agent-sdk)（`@grok/agent-sdk`）TypeScript 项目，同时生成路由评测（eval）骨架和逐字段迁移报告。
+
+[English](README.md) · **0.1.1** · [MIT 许可证](LICENSE) · Node **>=22.13** · 适配 **`@grok/agent-sdk@0.3.0`**
+
+![将 Claude 子代理与 Skills 转换为 Agent SDK 项目并生成逐字段迁移报告](docs/assets/agent2cursor-demo.gif)
+
+如果你手里已经有写好的 `.claude/agents/*.md` 或 `.codex/agents/*.toml` 子代理，或存放在目录中的 `SKILL.md` 技能文件（包括 [t3dotgg/tstack](https://github.com/t3dotgg/tstack) 这类工作流），`agent2cursor` 可以把这些散装资产整理成独立的 Cursor Agent SDK 项目。它产出可编辑源码、逐字段去向报告和初始路由 eval——**不会**迁移底层模型本身或聊天历史，也**不会**自动保证运行时行为或子代理权限边界与源平台等价。
+
+```text
+.claude/agents/code-reviewer.md → bot/subagents/code-reviewer/{agent.ts,instructions.md}
+.codex/agents/reviewer.toml     → bot/subagents/<name>/{agent.ts,instructions.md}
+skills/<name>/SKILL.md          → bot/skills/<name>/SKILL.md
+skills/*/scripts/*              → bot/tools/*.ts（默认禁用的 JSON 适配存根）
+源配置字段 + 路由检查             → MIGRATION.zh-CN.md（或 .en.md）+ evals/*.eval.ts
+```
+
+## 安装与使用
+
+需要 **Node.js >=22.13** 和 npm。npm 包名为 **`@kyun.si/agent2cursor`**，命令为 **`agent2cursor`**。以下示例固定使用 **0.1.1**。[npm 发行信息](https://www.npmjs.com/package/@kyun.si/agent2cursor)与[版本绑定的发布回执](https://github.com/mreasonyang/agent2cursor/blob/main/npm-publication.json)记录了公开归档及独立安装验证结果。
+
+请在存放子代理或 skill 的项目目录运行输入命令。下面的全局安装和一次性 `npx` 用法任选一种，两种方式生成相同的 SDK 项目。
+
+### 全局安装
+
+```bash
+npm install --global @kyun.si/agent2cursor@0.1.1
+agent2cursor --help
+agent2cursor inspect .claude/agents --lang zh
+agent2cursor convert .claude/agents --out ./my-agent --lang zh
+```
+
+### 不全局安装
+
+```bash
+npx --yes @kyun.si/agent2cursor@0.1.1 inspect .claude/agents --lang zh
+npx --yes @kyun.si/agent2cursor@0.1.1 convert .claude/agents --out ./my-agent --lang zh
+```
+
+只传实际存在的路径。Claude Code skills 可传 `.claude/skills`，也可传包含 `SKILL.md` 的单个目录。单个代理文件、代理目录或 skill 目录都可单独使用，也可组合多个输入；Codex 用法见下文的[转换 Codex 资产](#转换-codex-资产)。报告语言默认中文，这里的示例显式使用 `--lang zh`；原始指令保留原文，不会翻译。
+
+`inspect` 不写文件。`convert` 创建**新的输出目录**，已有路径会被拒绝覆盖。先检查 `my-agent/MIGRATION.zh-CN.md` 和生成的 `bot/` 源码。转换不会安装目标 SDK，也不会启动模型。全新输出在安装自身依赖前通常显示 `dependencies-missing`；这不代表 SDK 校验成功。
+
+### 校验和运行生成项目
+
+从刚才创建 `my-agent` 的目录继续：
+
+```bash
+cd my-agent
+npm install
+npm run validate
+npx agent-sdk eval --dir . --list
+npx --yes @kyun.si/agent2cursor@0.1.1 doctor --dir .
+```
+
+这些步骤只做结构校验和 eval 发现，不执行模型 eval。转换器和生成的 SDK 项目分别管理依赖，因此全局安装 `agent2cursor` 不能替代在 `my-agent` 内运行 `npm install`。
+
+检查迁移报告、权限、模型选择和默认禁用的脚本存根后，可以在**生成项目目录**中选择运行真实模型：
+
+```bash
+npx agent-sdk login
+npm run dev -- --web
+```
+
+`npm run dev -- --web` 启动 SDK 开发服务器并打开 playground，在其中发送请求才会调用模型。真实运行需要 Cursor 账号及对应模型访问权限。`--lang` 只选择生成的说明、报告和 eval 提示词语言，不会翻译原有代理或 skill。
+
+- **SDK 真实包名：** [Cursor Agent SDK 官方文档](https://cursor.com/docs/agent-sdk)指定的包名为 **`@grok/agent-sdk`**（旧称 `@cursor/bdk`）。生成的 `package.json` 将其锁定为 `0.3.0`，并声明 `zod` 为 `^3.25.0`；详见[上游核实说明](docs/upstream-verification.md)。
+- **账号要求：** 转换及安装依赖后的结构检查（`inspect`、`convert`、`doctor`、`agent-sdk validate`、`agent-sdk eval --list`）无需 Cursor 登录。`agent-sdk dev`、`agent-sdk run` 和实际模型 eval 需要登录及模型权限。可选的 `agent-sdk deploy` 还需要已开通 hosting 的账号／团队与仓库权限。
+
+`convert` / `demo` 在依赖缺失、但输出已写入时退出 0，`validation.status` 为 `dependencies-missing`，此时尚未执行校验。安装输出项目的依赖后，`doctor` 仅在校验通过时退出 0。实际校验失败会使 `convert` / `demo` 退出 1，但输出文件已经写入。转换器不会自动安装依赖。
+
+## 试用仓库样本（可选）
+
+npm 包包含两个 demo，**不包含 `fixtures/`、转换器的 `src/` 目录或其开发工具链**。要运行仓库样本，请单独克隆源码：
+
+```bash
+git clone https://github.com/mreasonyang/agent2cursor.git
+cd agent2cursor
+npm ci --ignore-scripts
+npm run build
+
+node dist/cli.js inspect ./fixtures/claude ./fixtures/tstack/skills/full-send --with-deps --lang zh
+node dist/cli.js convert ./fixtures/claude ./fixtures/tstack/skills/full-send \
+  --with-deps --lang zh --out ../agent2cursor-fixture
+```
+
+这组样本生成 **28 个文件**：4 个子代理、5 个 skill（含 4 个 `tstack` 依赖）和 1 个禁用脚本工具存根，报告位于 `../agent2cursor-fixture/MIGRATION.zh-CN.md`。输出目录必须尚不存在；重跑时请选择其他 `--out` 路径。审查报告后，可在 `agent2cursor-fixture` 中执行上文的校验步骤。这些样本只演示转换与结构检查，不证明运行时权限保留或真实模型行为等价。
+
+## 转换 Codex 资产
+
+使用已安装的命令（也可把 `agent2cursor` 替换为 `npx --yes @kyun.si/agent2cursor@0.1.1`），传入项目或个人子代理目录、单个 TOML 文件及 skill 目录。混合输入是另一种用法；只传实际存在的路径：
+
+```bash
+agent2cursor inspect .codex/agents .agents/skills --lang zh
+agent2cursor convert .codex/agents .agents/skills --out ./my-codex-agent --lang zh
+# 可选：混合 Claude、Codex 与 skills
+agent2cursor convert .claude/agents .codex/agents .agents/skills --out ./mixed-agent --lang zh
+```
+
+只传实际存在的路径，子代理和 skill 可以单独转换。个人独立子代理目录 `~/.codex/agents` 也支持。传入项目根目录时会发现这些子代理树和 skill 目录，无关 TOML 文件不会被当作子代理。
+
+| Codex 输入 | 转换方式 |
+| --- | --- |
+| 独立 TOML 的 `name`、`description`、`developer_instructions` | 必须是非空字符串；分别生成子代理 ID、委派描述和解析后的指令文本。格式不合要求时明确报错。 |
+| `model` | 默认省略，继承目标父代理模型；支持 `--model-map 源ID=目标ID` 与 `--keep-model`，校验不证明模型可调用。 |
+| `model_reasoning_effort`、`model_reasoning_summary`、`model_verbosity` | 逐字段标为丢弃；模型 ID 映射不包含这些参数。 |
+| `features.*`、`skills.*` | 逐字段标为降级，子代理能力与 skill 限制未生效；不会读取其中引用的 skill 路径。 |
+| sandbox、approval、provider、MCP 等父会话配置 | 不导入；这些字段在 Codex 独立子代理中也不能覆盖父会话。需人工设置目标运行环境。 |
+| `agents/openai.yaml` | 文件原样保留；有效的 `interface.default_prompt` 用于 eval。UI、调用策略、工具依赖及未知字段逐项说明，调用限制不生效，MCP 不自动连接。 |
+
+当前支持的是 **Codex 独立 TOML 子代理 → Cursor Agent SDK**。不转换整个会话，也不输出 Codex 配置；父级 `config.toml`、`AGENTS.md`、凭证和旧式 `[agents.<name>] config_file` 声明不会导入。继承的指令、工具与 skills 需要另行审核。Codex 专用工具名会给出迁移提示，不自动改写原文。见 [Codex 样例](fixtures/codex) 与[核实范围](docs/upstream-verification.md#codex-input-adapter-2026-10-28)。
+
+## 适用场景与官方方案对比
+
+`@grok/agent-sdk` 已原生支持直接加载 `SKILL.md` 和挂载插件，可按手头资产选择最简方案：
+
+| 方案 | 适用情况 |
+| --- | --- |
+| 直接复制 `SKILL.md` | 只有现成兼容的 `SKILL.md` 目录，不需要转换子代理、脚本存根或生成逐字段迁移报告 |
+| SDK `cursorPlugin()` | 已有带清单（manifest）的 Cursor / Claude 插件，只需运行时挂载 |
+| `agent-sdk init --from automation:` / `migrate` | 从 Cursor Automation 迁移，或升级旧版 SDK 项目 |
+| **`agent2cursor`** | 手头有散装 Claude `.md` / Codex `.toml` 子代理、多技能目录或 `tstack` 工作流，希望导出为可编辑的 SDK 源码、获得逐字段损失清单、异构工具警告、禁用脚本存根与路由 eval 骨架 |
+
+## 转换前后实例与字段去向（`code-reviewer`）
+
+以仓库自带的 [`fixtures/claude/agents/code-reviewer.md`](fixtures/claude/agents/code-reviewer.md) 为例：
+
+```markdown
+---
+name: code-reviewer
+description: Review changed code for defects, maintainability, and missing verification.
+tools: Read, Grep, Glob
+model: sonnet
+---
+Review the changed code. Prioritize concrete defects and cite the affected file and line.
+Do not edit files. Explain what was verified and what remains uncertain.
+```
+
+`agent2cursor convert` 会生成 `bot/subagents/code-reviewer/agent.ts`，把提示词正文写入 `bot/subagents/code-reviewer/instructions.md`，并在 `MIGRATION.zh-CN.md`（或 `MIGRATION.en.md`）逐项记录每个 frontmatter 字段的结论：
+
+```ts
+// bot/subagents/code-reviewer/agent.ts
+// Generated by agent2cursor. Review the migration report before running.
+import { defineAgent } from "@grok/agent-sdk";
+
+export default defineAgent({
+  description: "Review changed code for defects, maintainability, and missing verification.",
+  // TODO(agent2cursor): tools: 危险：子代理工具限制未生效，task 子代理保留 harness 自己的工具集；不能假定根白名单会约束子代理。工具名参考映射 (read, grep, glob)；若必须强制只读，需使用独立代理或禁用 task，并另行约束执行环境；shell 可写入。
+  // TODO(agent2cursor): model: 已省略 model，继承父代理模型；使用 --model-map 显式指定目标模型。
+});
+```
+
+<details>
+<summary><strong>逐类输入与 frontmatter 字段去向表</strong></summary>
+
+| 源文件或字段 | SDK 输出位置 | 迁移结论 | 处理方式 |
+| --- | --- | --- | --- |
+| 子代理 `name` | `bot/subagents/<id>/` | `✅ 已映射` / `⚠️ 降级` | 已是合法目录 ID 时为 `✅`；发生字符规范化或缺失回退为文件名时为 `⚠️` |
+| 子代理 `description` | `bot/subagents/<id>/agent.ts` | `✅ 已映射` / `⚠️ 降级` | 非空有效时为 `✅`；缺失或空白时生成占位描述并标为 `⚠️` |
+| 子代理 Markdown 正文 | `bot/subagents/<id>/instructions.md` | `✅ 已映射` / `⚠️ 降级` | 正文未变化时标为已映射；追加共享技能预加载提示时明确标为降级，并说明保留原文、末尾追加提示 |
+| 子代理 `model` | `bot/subagents/<id>/agent.ts` | `✅ 已映射` / `⚠️ 降级` | `inherit` 直接省略（`✅`）；`sonnet`、`opus`、`haiku` 等默认省略以继承父模型（`⚠️`），除非用 `--model-map` 显式映射（`✅`）或用 `--keep-model` 原样保留（`⚠️`） |
+| 子代理 `tools` / `disallowedTools` | `MIGRATION.*.md` + `TODO(agent2cursor)` | `⚠️ 降级` | SDK `0.3.0` 不支持子代理级工具限制，`task` 子代理仍使用 harness `task` 工具集 |
+| 子代理 `skills` | `bot/instructions.md` + `instructions.md` | `⚠️ 降级` | 生成共享 skill 加载提示（无原生子代理独立预加载机制） |
+| `permissionMode`、`hooks`、`mcpServers`、`memory` 及未知代理字段 | `MIGRATION.*.md` + `TODO(agent2cursor)` | `❌ 丢弃` | 目标 SDK 无已核实的等价字段，在报告中列出供人工补齐 |
+| `SKILL.md` 及附属文件 | `bot/skills/<id>/**` | `✅ 已映射` / `⚠️ 降级` | 保留正文、附属文件与额外 frontmatter（`license`、`metadata.*`）；`name`/`description` 被规范化或缺失时标为 `⚠️`，`allowed-tools` 标为 `⚠️` |
+| `skills/*/agents/openai.yaml` | 原样元数据文件 + `evals/skills.eval.ts` | `✅ 已映射` / `⚠️ 降级` | 有效 `interface.default_prompt` 用作 eval 触发词；UI、调用策略、工具依赖及未知字段逐项报告，仅保留元数据不代表 SDK 支持其运行时语义 |
+| `skills/*/scripts/*` | `bot/skills/<id>/scripts/*` + `bot/tools/<script>.ts` | `⚠️ 降级` | 复制脚本内容（去除可执行位），并在 `bot/tools/` 生成默认禁用的 `execution: "agent"` 存根（`AGENT2CURSOR_STUB_DISABLED`） |
+
+</details>
+
+## 命令行参考
+
+| 命令或参数 | 说明 |
+| --- | --- |
+| `convert <input...>` | 将 Claude `.md` / Codex 独立 `.toml`、`.claude/agents/` / `.codex/agents/`、skill 目录或 `tstack` 仓库转换为新的 SDK 项目 |
+| `inspect <input...>` | 仅输出迁移报告（或 `--json` 摘要），不写入任何文件 |
+| `demo <full-send\|pr-review>` | 导出内置的两个 `tstack` 改编示例项目（支持 `--out <dir>`、`--json`、`--no-validate`） |
+| `doctor [--dir <project>]` | 检查 Node `>=22.13` 并调用 `agent-sdk validate` 输出脱敏诊断摘要 |
+| `--out <dir>` | `convert` 的新输出目录（默认 `./my-agent`；路径已存在时拒绝覆盖） |
+| `--name <name>` | 生成的代理名称（`1–64` 位小写字母、数字、`-` 或 `_`，以字母或数字开头，默认 `converted-agent`） |
+| `--lang <zh\|en>` | `convert` / `inspect` 输出语言（默认 `zh`），选择生成的说明、eval 提示词和报告文件名；不翻译源文本或内置示例 |
+| `--with-deps` | 按 `tstack` 依赖图自动补齐同级目录中被依赖的关联技能 |
+| `--model-map <map>` | 显式映射模型 ID，如 `--model-map sonnet=<已核实模型ID>`（需用自己的账号核实可用性） |
+| `--keep-model` | 原样保留未验证的源模型 ID，而不是省略以继承父模型 |
+| `--root-tools <list>` | 显式设置根代理工具白名单（`read,grep,glob,ls,shell,edit,task,delete`）；不传则使用 SDK 默认值 |
+| `--dry-run` / `--no-validate` / `--json` | 仅计算生成计划不写文件 / 跳过 `agent-sdk validate` / 输出机器可读 JSON |
+
+## 内置示例（Demos）
+
+两个示例均基于 [t3dotgg/tstack](https://github.com/t3dotgg/tstack) 固定 MIT 快照（`7de017b3fc9d50c03cf3ecb98fb71e0ca65a78bd`）改编为中文工作流，附带 `LICENSE-tstack` 与 `TSTACK-PROVENANCE.json`。npm 包已包含这两个示例，无需克隆源码。分别导出到新目录：
+
+```bash
+agent2cursor demo full-send --out ./full-send-agent
+agent2cursor demo pr-review --out ./pr-review-agent
+```
+
+使用一次性方式时，把命令前缀换成 `npx --yes @kyun.si/agent2cursor@0.1.1`。示例固定为中文工作流，`demo` 不接受 `--lang`。导出后进入所选示例目录，运行 `npm install` 和 `npm run validate`。
+
+- **`full-send`（[操作说明](demos/full-send/README.md)）：** 含 5 个技能（`full-send`、`sol-loop`、`file-pr`、`babysit-pr`、`leaving-pr-comments`）、1 个 `reviewer` 子代理、做一次只读快照且不轮询的 `pr_wait` 工具、默认禁用的 `pr_wait_script` 存根（保留原版 Python `pr-wait` 供审阅），以及带门禁的 `merge_pr` 工具。根代理不含 `shell`，因此**默认只完成本地代码修改、评审并输出 PR 草稿，在发布和合并前停止**——未实现自动跑测试、`git push` 和创建 PR。`merge_pr` 默认关闭，必须同时满足 `AGENT2CURSOR_ALLOW_MERGE=1`、人工批准本次调用、匹配已配置 GitHub 仓库会话、PR 处于 open/非 draft/clean 状态且 `expectedHead` 精确匹配当前 head SHA（eval 会话禁止合并）。
+- **`pr-review`（[操作说明](demos/pr-review/README.md)）：** 含 `council` 与 `leaving-pr-comments` 技能及 3 个评审子代理（`reviewer-a`、`reviewer-b`、`reviewer-c`）。三个子代理继承同一父模型，输出中文 `Council review` 评分表，并明确声明当前是同一模型的三种视角而非三家模型厂商。根代理仅保留只读搜索与委派工具，不提供发评论或改 PR 描述的工具。
+
+两个示例在 `bot/lib/settings.ts` 保持默认 `"OWNER/REPO"` 时完全禁用 GitHub channel；配置实际仓库后也显式关闭自动回复评论、reaction 和 `@mention` 触发。`pr-review` 在服务端预先拉取并校验有界 diff 快照供沙箱内模型读取；而在沙箱模型回合中直接调用 `pr_wait` 仍未通过验收。
+
+## 核心限制与验收状态
+
+[独立评测](evaluation/README.md)覆盖修复后的转换器与新版路由 eval。较早的 demo 真实模型与 PR 签名回放结果来自更名之前（原名 `cc2agent`），[原始证据](docs/evidence/online-2026-10-27.json)保留对应源码哈希；不同轮次的结果与验证范围分别记录。
+
+- **工具名扫描范围：** 固定名单区分大小写检测正文和附属 Markdown 中的 `WebFetch`、`WebSearch`、`AskUserQuestion`、`request_user_input`、`delegate_task`、`orchestrator_capabilities`、`watch_pull_request`、`unwatch_pull_request`、`Monitor`。命中可能来自禁止调用的说明；未命中不代表工具兼容，不改写源提示词。
+- **根代理工具白名单不等于子代理隔离：** `--root-tools` 仅约束根代理。`@grok/agent-sdk@0.3.0` 的 `task` 子代理仍保有 harness 自身的 `task` 工具集，不能把根白名单当作子代理只读的证明；同时任何启用 `shell` 的配置都能写文件和执行任意命令，绝非只读。
+- **脚本工具默认是禁用存根：** 转换过程绝不执行输入脚本。生成的 `bot/tools/*.ts` 固定返回 `AGENT2CURSOR_STUB_DISABLED`，需操作员审查复制到 `bot/skills/<id>/scripts/*` 的原脚本、实现 JSON stdin/stdout 契约并开启 `shell` 后才能启用。
+- **输入与输出防护范围：** 转换器拒绝覆盖已有输出目录、拒绝符号链接、限制单次生成体积上限为 128 MiB，跳过或拒绝已知凭据路径（`.env`、`.npmrc`、私钥文件），并拒绝敏感 YAML/TOML 键名（`token`、`apiKey`、`secret`），解析错误不回显源值；它不会对任意正文段落或二进制附件做全量秘密扫描。
+
+**当前验收状态摘要（各证据层级严格区分）：**
+
+| 证据层级 | 状态 | 已验证范围与未覆盖边界 |
+| --- | --- | --- |
+| npm 发布与安装 | **按版本记录** | [发布回执](https://github.com/mreasonyang/agent2cursor/blob/main/npm-publication.json)绑定实际版本和归档哈希，并记录匿名安装、固定版本／默认 `npx`、混合转换、两个 demo 导出及 doctor 检查；历史回执单独保留 |
+| 离线单测与结构校验 | **PASS — 74 项测试** | Node 22.13 / 24 CI 通过。Claude、Codex、tstack、full-send 和 pr-review 五类生成项目安装独立依赖后，通过 SDK 结构检查、严格 TypeScript 和 eval 发现；`eval --list` 不代表真实执行通过。[CI](https://github.com/mreasonyang/agent2cursor/actions/workflows/check.yml) |
+| 独立转换与路由评测 | **PASS**（限定数据集） | 正常转换及安装后校验 24/24；新版自动路由 eval 在 30 个项目中 41/41 通过。3 个真实任务各重复 3 次，与直接复制/插件对照打平。[计数与源码哈希](docs/evidence/independent-evaluation.json) |
+| 真实模型运行 | **历史 PASS**（窄用例） | 已完成官方 `agent-sdk login`。`migration-smoke` 通过（**1 条用例 / 2 个断言**：`succeeded`、`loadedSkill`）；`pr-review` 内联 diff 评审通过（**1 条用例 / 9 个断言**，同模型 3 视角）；`full-send` 本地 `run` 完成 1 次 skill 读取，0 次写入/执行/合并 |
+| GitHub PR 回放 | **历史 PASS**（本地回放） | [历史测试 PR #1](https://github.com/mreasonyang/agent2cursor/pull/1) 经 HMAC 签名**本地回放**通过（有界快照 + 3 次子代理委派 + 中文评分表；0 工具错误、0 写入/执行、0 GitHub 评论/reaction/review；测试 PR 已关闭且未合并）。不等于线上托管 webhook 投递 |
+| 云端托管 | **未运行 / 暂缓** | 最近一轮记录中，测试账号缺少默认团队（`no default team`），`agent-sdk deploy --dry-run` 在前置条件处停止。托管部署尚未完成，没有经过验证的部署 URL |
+
+历史模型运行与 PR 回放没有因 Codex 适配、npm 发布或本次文档核对而重跑。上述单点结果不证明任意输入下的平均模型质量、多厂商路由或子代理运行时隔离。完整记录见：[验收记录](docs/acceptance.md) · [上游核实说明](docs/upstream-verification.md) · [脱敏线上证据](docs/evidence/online-2026-10-27.json) · [官方示例来源记录](docs/official-examples.provenance.json)。
+
+## 开发维护与许可证
+
+维护者自检命令（`npm run check`、`npm run test:sdk`、`node scripts/build-demos.mjs`）与仓库安全守则见 [CONTRIBUTING.md](CONTRIBUTING.md)。源码工程保留面向 npm 的 `private: true`，`pack:local` 另行生成公开归档；GitHub 仓库已公开。npm 包内同时包含两份语言文档。`0.1.1` 包含已核对的安装与使用说明，文档更新记录见 [CHANGELOG.md](CHANGELOG.md)。
+
+`agent2cursor` 采用 [MIT 许可证](LICENSE)（`Copyright (c) 2026 Eason Yang`）。[`fixtures/tstack`](fixtures/tstack)（[`PROVENANCE.json`](fixtures/tstack/PROVENANCE.json)）中的固定快照与两个改编示例源自 [t3dotgg/tstack](https://github.com/t3dotgg/tstack)，`Copyright (c) 2026 Theo Browne`，采用 MIT 许可（保存在 [`fixtures/tstack/LICENSE`](fixtures/tstack/LICENSE) 与 `LICENSE-tstack` 中）；被识别的 `tstack` 输入源必须保留该 MIT 声明。`@grok/agent-sdk@0.3.0` 是专有依赖（本仓库不内置或再分发其源码与文档）。本项目与 Theo Browne、T3、Anthropic、Cursor、Anysphere 或 xAI 无官方关联或背书。详见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。