@kyun.si/agent2cursor 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/CONTRIBUTING.md +3 -0
  3. package/README.md +76 -48
  4. package/README.zh-CN.md +75 -47
  5. package/dist/cli.js +1 -1
  6. package/docs/acceptance.md +19 -3
  7. package/docs/evidence/npm-publication-0.1.0.json +46 -0
  8. package/docs/evidence/readme-audit-2026-10-28.json +248 -0
  9. package/package.json +2 -2
package/CHANGELOG.md ADDED
@@ -0,0 +1,12 @@
1
+ # Changelog
2
+
3
+ ## 0.1.1 — 2026-10-28
4
+
5
+ - 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.
6
+ - Clarify language options, the fixed Chinese demos, copied script paths, current verification counts and historical model-run evidence.
7
+ - 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.
8
+ - Preserve the version-bound npm 0.1.0 publication receipt separately.
9
+
10
+ ## 0.1.0 — 2026-10-28
11
+
12
+ - 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 CHANGED
@@ -65,12 +65,15 @@ The public GitHub repository and the npm registry are separate destinations. Kee
65
65
  ```bash
66
66
  npm run check
67
67
  npm run pack:local
68
+ npm run verify:package
68
69
  npm run publish:npm -- --dry-run
69
70
  npm run publish:npm
70
71
  ```
71
72
 
72
73
  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.
73
74
 
75
+ 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.
76
+
74
77
  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.
75
78
 
76
79
  ## Evaluation Evidence
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  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.
4
4
 
5
- [中文说明](README.zh-CN.md) · **0.1.0** · [MIT License](LICENSE) · Node **>=22.13** · Targets **`@grok/agent-sdk@0.3.0`**
5
+ [中文说明](README.zh-CN.md) · **0.1.1** · [MIT License](LICENSE) · Node **>=22.13** · Targets **`@grok/agent-sdk@0.3.0`**
6
6
 
7
7
  ![Converting Claude subagents and skills into an Agent SDK project with a field-by-field migration report](docs/assets/agent2cursor-demo.gif)
8
8
 
@@ -16,66 +16,86 @@ skills/*/scripts/* → bot/tools/*.ts (disabled JSON adapter stubs)
16
16
  source fields + routing checks → MIGRATION.zh-CN.md (or .en.md) + evals/*.eval.ts
17
17
  ```
18
18
 
19
- ## Quickstart
19
+ ## Install and use
20
20
 
21
- The npm package name is **`@kyun.si/agent2cursor`**; the executable is **`agent2cursor`**:
21
+ 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.
22
+
23
+ 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.
24
+
25
+ ### Global installation
22
26
 
23
27
  ```bash
24
- npx --yes @kyun.si/agent2cursor@0.1.0 --help
25
- npm install --global @kyun.si/agent2cursor@0.1.0
26
- agent2cursor inspect .claude/agents
27
- agent2cursor convert .claude/agents --out ./my-agent
28
+ npm install --global @kyun.si/agent2cursor@0.1.1
29
+ agent2cursor --help
30
+ agent2cursor inspect .claude/agents --lang en
31
+ agent2cursor convert .claude/agents --out ./my-agent --lang en
28
32
  ```
29
33
 
30
- Pass paths that exist on your machine. Codex inputs can use `.codex/agents` and `.agents/skills`; Claude and Codex inputs can also be combined. Conversion is local and does not require a Cursor account.
31
-
32
- To try the included [`fixtures/`](fixtures/claude) instead, build from a source checkout:
34
+ ### Without global installation
33
35
 
34
36
  ```bash
35
- npm ci --ignore-scripts
36
- npm run build
37
-
38
- # Inspect or convert the checked-in Claude subagents + tstack full-send skill closure
39
- node dist/cli.js inspect ./fixtures/claude ./fixtures/tstack/skills/full-send --with-deps --lang en
40
- node dist/cli.js convert ./fixtures/claude ./fixtures/tstack/skills/full-send \
41
- --with-deps --lang en --out /tmp/my-agent
37
+ npx --yes @kyun.si/agent2cursor@0.1.1 inspect .claude/agents --lang en
38
+ npx --yes @kyun.si/agent2cursor@0.1.1 convert .claude/agents --out ./my-agent --lang en
42
39
  ```
43
40
 
44
- ```text
45
- ⚠️ Source subagent restrictions are not enforced (4 affected): tools / disallowedTools / permissionMode were not migrated. SDK validation does not establish read-only access; --root-tools sets only the root allowlist.
46
- agent2cursor v0.1.0 → @grok/agent-sdk 0.3.0
47
- Scanned: 4 agents, 5 skills, 1 script stubs
48
- ...
41
+ 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.
42
+
43
+ `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.
44
+
45
+ ### Validate and run the generated project
46
+
47
+ From the directory where you created `my-agent`:
48
+
49
+ ```bash
50
+ cd my-agent
51
+ npm install
52
+ npm run validate
53
+ npx agent-sdk eval --dir . --list
54
+ npx --yes @kyun.si/agent2cursor@0.1.1 doctor --dir .
49
55
  ```
50
56
 
51
- On this fixture input (4 subagents, 5 skills including 4 `tstack` dependencies, and 1 script stub), `agent2cursor` writes **28 files** and lists migration concerns in `/tmp/my-agent/MIGRATION.en.md`. Exact concern counts and `Validation` status depend on your inputs, flags, and installed dependencies (`dependencies-missing` is expected before installing dependencies in `/tmp/my-agent`).
57
+ 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`.
52
58
 
53
- To install the SDK inside the generated project and run structural checks from this checkout:
59
+ After reviewing the migration report, permissions, model selection, and disabled script stubs, you can optionally run a real model from the **generated project directory**:
54
60
 
55
61
  ```bash
56
- (cd /tmp/my-agent && npm install && npx agent-sdk validate --dir . && npx agent-sdk eval --dir . --list)
57
- node dist/cli.js doctor --dir /tmp/my-agent
62
+ npx agent-sdk login
63
+ npm run dev -- --web
58
64
  ```
59
65
 
60
- Maintainers build the public archive with `npm run pack:local` and publish that exact verified archive with `npm run publish:npm`; see [CONTRIBUTING.md](CONTRIBUTING.md#npm-release). The source workspace keeps `private: true`; the public archive omits that field.
66
+ `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.
67
+
68
+ - **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).
69
+ - **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.
61
70
 
62
- - **SDK package name:** [Official Cursor Agent SDK docs](https://cursor.com/docs/agent-sdk) specify **`@grok/agent-sdk`** (formerly `@cursor/bdk`). Do not substitute `@cursor/agent-sdk` from older blog posts; see [upstream verification](docs/upstream-verification.md). Generated `package.json` pins `@grok/agent-sdk` to `0.3.0` and declares `zod` `^3.25.0`.
63
- - **Account requirements by step:**
64
- 1. **Offline conversion & structural checks** (`convert`, `inspect`, `doctor`, `agent-sdk validate`, `agent-sdk eval --list`) require **no** Cursor account or API key.
65
- 2. **Live model execution** (`agent-sdk dev`, `agent-sdk run`, live `agent-sdk eval`) requires `agent-sdk login` and model access on your Cursor account.
66
- 3. **Cloud hosting** (`agent-sdk deploy`) is optional and requires an account/team with hosting enabled and repository permissions.
71
+ `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.
67
72
 
68
- `convert` and `demo` exit 0 when files are written but declared SDK or `zod` dependencies are missing: `validation.status` is `dependencies-missing`, with the missing package names. Validation has not run. Install dependencies and run `agent2cursor doctor --dir <project>`; `doctor` exits nonzero until validation passes. Actual validation errors still make conversion exit 1. Dependencies are never installed automatically.
73
+ ## Try the repository fixtures (optional)
74
+
75
+ 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:
76
+
77
+ ```bash
78
+ git clone https://github.com/mreasonyang/agent2cursor.git
79
+ cd agent2cursor
80
+ npm ci --ignore-scripts
81
+ npm run build
82
+
83
+ node dist/cli.js inspect ./fixtures/claude ./fixtures/tstack/skills/full-send --with-deps --lang en
84
+ node dist/cli.js convert ./fixtures/claude ./fixtures/tstack/skills/full-send \
85
+ --with-deps --lang en --out ../agent2cursor-fixture
86
+ ```
87
+
88
+ 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.
69
89
 
70
90
  ## Convert Codex assets
71
91
 
72
- After building the checkout, pass project or personal agent directories, a standalone TOML file, and/or skill directories. Claude and Codex inputs can be mixed in one conversion:
92
+ 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:
73
93
 
74
94
  ```bash
75
- node dist/cli.js inspect .codex/agents .agents/skills --lang en
76
- node dist/cli.js convert .codex/agents .agents/skills --out ./my-codex-agent --lang en
77
- # Included synthetic example: no Codex installation or account required
78
- node dist/cli.js convert fixtures/codex/project --out /tmp/codex-example --lang en
95
+ agent2cursor inspect .codex/agents .agents/skills --lang en
96
+ agent2cursor convert .codex/agents .agents/skills --out ./my-codex-agent --lang en
97
+ # Optional: combine Claude, Codex, and skills
98
+ agent2cursor convert .claude/agents .codex/agents .agents/skills --out ./mixed-agent --lang en
79
99
  ```
80
100
 
81
101
  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.
@@ -159,7 +179,7 @@ export default defineAgent({
159
179
  | `doctor [--dir <project>]` | Check Node `>=22.13` and run `agent-sdk validate` with credential-safe diagnostic summaries |
160
180
  | `--out <dir>` | New output directory for `convert` (default `./my-agent`; never overwrites existing paths) |
161
181
  | `--name <name>` | Generated agent name (`1–64` lowercase letters, digits, `-`, or `_`, starting with a letter or digit; default `converted-agent`) |
162
- | `--lang <zh\|en>` | Language for generated instructions, eval prompts, and `MIGRATION.zh-CN.md` / `MIGRATION.en.md` (default `zh`) |
182
+ | `--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 |
163
183
  | `--with-deps` | Include sibling skills required by the `tstack` dependency graph |
164
184
  | `--model-map <map>` | Map source models explicitly, e.g. `--model-map sonnet=<account-verified-id>` (verify ID availability on your account) |
165
185
  | `--keep-model` | Keep unverified source model IDs as-is instead of omitting them to inherit |
@@ -168,7 +188,14 @@ export default defineAgent({
168
188
 
169
189
  ## Included Demos
170
190
 
171
- 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`. Export them with `node dist/cli.js demo <full-send|pr-review> --out <dir>`:
191
+ 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:
192
+
193
+ ```bash
194
+ agent2cursor demo full-send --out ./full-send-agent
195
+ agent2cursor demo pr-review --out ./pr-review-agent
196
+ ```
197
+
198
+ 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.
172
199
 
173
200
  - **`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).
174
201
  - **`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.
@@ -181,23 +208,24 @@ The [independent evaluation](evaluation/README.md) covers the corrected converte
181
208
 
182
209
  - **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.
183
210
  - **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).
184
- - **Script tools are disabled stubs:** conversion never executes source scripts. Generated `bot/tools/*.ts` wrappers return `AGENT2CURSOR_STUB_DISABLED` until an operator audits `.cursor/skills/<id>/scripts/*`, implements the JSON stdin/stdout contract, and enables `shell`.
185
- - **Scoped input/output guards:** 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.
211
+ - **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`.
212
+ - **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.
186
213
 
187
214
  **Verification summary (each evidence level is tracked separately):**
188
215
 
189
216
  | Evidence level | Status | What is and is not proven |
190
217
  | --- | --- | --- |
191
- | Offline tests & SDK structure | **PASS** (existing evidence) | 59 local tests passed before repository cleanup. Generated projects passed SDK `validate` / `info` / `eval --list` and strict `tsc`, with their own dependencies installed in independent temporary directories. `eval --list` proves case discovery only. Cleanup did not rerun these suites |
218
+ | 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 |
219
+ | 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) |
192
220
  | 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) |
193
- | Live model runs | **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 |
194
- | GitHub PR replay | **PASS** (local replay) | [Private 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 |
195
- | Cloud hosting | **Not run / On hold** | `agent-sdk deploy --dry-run` stopped because the test account has no default team configured; no hosted deployment or URL exists |
221
+ | 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 |
222
+ | 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 |
223
+ | 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 |
196
224
 
197
- 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).
225
+ 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).
198
226
 
199
227
  ## Contributing and License
200
228
 
201
- Maintainer commands (`npm run check`, `npm run test:sdk`, `node scripts/build-demos.mjs`) and safety invariants are in [CONTRIBUTING.md](CONTRIBUTING.md).
229
+ 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.
202
230
 
203
231
  `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 CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  把已写好的 Claude Code / Codex 子代理（subagents）与 Agent Skills 整理成可编辑的 [Cursor Agent SDK](https://cursor.com/docs/agent-sdk)（`@grok/agent-sdk`）TypeScript 项目，同时生成路由评测（eval）骨架和逐字段迁移报告。
4
4
 
5
- [English](README.md) · **0.1.0** · [MIT 许可证](LICENSE) · Node **>=22.13** · 适配 **`@grok/agent-sdk@0.3.0`**
5
+ [English](README.md) · **0.1.1** · [MIT 许可证](LICENSE) · Node **>=22.13** · 适配 **`@grok/agent-sdk@0.3.0`**
6
6
 
7
7
  ![将 Claude 子代理与 Skills 转换为 Agent SDK 项目并生成逐字段迁移报告](docs/assets/agent2cursor-demo.gif)
8
8
 
@@ -16,66 +16,86 @@ skills/*/scripts/* → bot/tools/*.ts（默认禁用的 JSON 适配
16
16
  源配置字段 + 路由检查 → MIGRATION.zh-CN.md（或 .en.md）+ evals/*.eval.ts
17
17
  ```
18
18
 
19
- ## 快速试用
19
+ ## 安装与使用
20
20
 
21
- npm 包名为 **`@kyun.si/agent2cursor`**，安装后的命令为 **`agent2cursor`**：
21
+ 需要 **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)记录了公开归档及独立安装验证结果。
22
+
23
+ 请在存放子代理或 skill 的项目目录运行输入命令。下面的全局安装和一次性 `npx` 用法任选一种，两种方式生成相同的 SDK 项目。
24
+
25
+ ### 全局安装
22
26
 
23
27
  ```bash
24
- npx --yes @kyun.si/agent2cursor@0.1.0 --help
25
- npm install --global @kyun.si/agent2cursor@0.1.0
26
- agent2cursor inspect .claude/agents
27
- agent2cursor convert .claude/agents --out ./my-agent
28
+ npm install --global @kyun.si/agent2cursor@0.1.1
29
+ agent2cursor --help
30
+ agent2cursor inspect .claude/agents --lang zh
31
+ agent2cursor convert .claude/agents --out ./my-agent --lang zh
28
32
  ```
29
33
 
30
- 只传机器上实际存在的路径。Codex 输入可以使用 `.codex/agents` 和 `.agents/skills`，也可混合 Claude 与 Codex 输入。转换在本地执行，不需要 Cursor 账号。
31
-
32
- 若要试用仓库内置的 [`fixtures/`](fixtures/claude) 样本，请从源码目录编译：
34
+ ### 不全局安装
33
35
 
34
36
  ```bash
35
- npm ci --ignore-scripts
36
- npm run build
37
-
38
- # 预览或转换仓库自带的 Claude 子代理 + tstack full-send 技能闭包（默认生成中文报告）
39
- node dist/cli.js inspect ./fixtures/claude ./fixtures/tstack/skills/full-send --with-deps
40
- node dist/cli.js convert ./fixtures/claude ./fixtures/tstack/skills/full-send \
41
- --with-deps --out /tmp/my-agent
37
+ npx --yes @kyun.si/agent2cursor@0.1.1 inspect .claude/agents --lang zh
38
+ npx --yes @kyun.si/agent2cursor@0.1.1 convert .claude/agents --out ./my-agent --lang zh
42
39
  ```
43
40
 
44
- ```text
45
- ⚠️ 子代理限制未生效（4 个）：源 tools / disallowedTools / permissionMode 未迁移。SDK 校验通过不代表只读；--root-tools 只设置根代理白名单。
46
- agent2cursor v0.1.0 → @grok/agent-sdk 0.3.0
47
- 扫描: 4 agents, 5 skills, 1 script stubs
48
- ...
41
+ 只传实际存在的路径。Claude Code skills 可传 `.claude/skills`，也可传包含 `SKILL.md` 的单个目录。单个代理文件、代理目录或 skill 目录都可单独使用，也可组合多个输入；Codex 用法见下文的[转换 Codex 资产](#转换-codex-资产)。报告语言默认中文，这里的示例显式使用 `--lang zh`；原始指令保留原文，不会翻译。
42
+
43
+ `inspect` 不写文件。`convert` 创建**新的输出目录**，已有路径会被拒绝覆盖。先检查 `my-agent/MIGRATION.zh-CN.md` 和生成的 `bot/` 源码。转换不会安装目标 SDK，也不会启动模型。全新输出在安装自身依赖前通常显示 `dependencies-missing`；这不代表 SDK 校验成功。
44
+
45
+ ### 校验和运行生成项目
46
+
47
+ 从刚才创建 `my-agent` 的目录继续：
48
+
49
+ ```bash
50
+ cd my-agent
51
+ npm install
52
+ npm run validate
53
+ npx agent-sdk eval --dir . --list
54
+ npx --yes @kyun.si/agent2cursor@0.1.1 doctor --dir .
49
55
  ```
50
56
 
51
- 在这组内置样本输入下（4 个子代理、5 个 skill 含 4 个 `tstack` 依赖、1 个脚本存根），`agent2cursor` 会生成 **28 个文件**，并在 `/tmp/my-agent/MIGRATION.zh-CN.md` 逐项记录迁移提醒。具体提醒数与 `自检`（`Validation`）状态会随输入资产、参数及已安装依赖而变化（在 `/tmp/my-agent` 安装依赖前显示 `dependencies-missing` 属正常现象）。
57
+ 这些步骤只做结构校验和 eval 发现，不执行模型 eval。转换器和生成的 SDK 项目分别管理依赖，因此全局安装 `agent2cursor` 不能替代在 `my-agent` 内运行 `npm install`。
52
58
 
53
- 保持当前仓库目录不变，直接为生成项目安装依赖并运行结构校验与 `doctor`：
59
+ 检查迁移报告、权限、模型选择和默认禁用的脚本存根后，可以在**生成项目目录**中选择运行真实模型：
54
60
 
55
61
  ```bash
56
- (cd /tmp/my-agent && npm install && npx agent-sdk validate --dir . && npx agent-sdk eval --dir . --list)
57
- node dist/cli.js doctor --dir /tmp/my-agent
62
+ npx agent-sdk login
63
+ npm run dev -- --web
58
64
  ```
59
65
 
60
- 维护者用 `npm run pack:local` 构建公开归档，再用 `npm run publish:npm` 发布已经验证的同一归档；见 [CONTRIBUTING.md](CONTRIBUTING.md#npm-release)。源码工程保留 `private: true`，公开归档不包含这个字段。
66
+ `npm run dev -- --web` 启动 SDK 开发服务器并打开 playground，在其中发送请求才会调用模型。真实运行需要 Cursor 账号及对应模型访问权限。`--lang` 只选择生成的说明、报告和 eval 提示词语言，不会翻译原有代理或 skill。
67
+
68
+ - **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)。
69
+ - **账号要求：** 转换及安装依赖后的结构检查（`inspect`、`convert`、`doctor`、`agent-sdk validate`、`agent-sdk eval --list`）无需 Cursor 登录。`agent-sdk dev`、`agent-sdk run` 和实际模型 eval 需要登录及模型权限。可选的 `agent-sdk deploy` 还需要已开通 hosting 的账号／团队与仓库权限。
61
70
 
62
- - **SDK 真实包名：** [Cursor Agent SDK 官方文档](https://cursor.com/docs/agent-sdk)指定的包名为 **`@grok/agent-sdk`**（旧称 `@cursor/bdk`），请勿使用早期公告中的 `@cursor/agent-sdk`；详见[上游核实说明](docs/upstream-verification.md)。生成的 `package.json` 将 `@grok/agent-sdk` 锁定为 `0.3.0`，并声明 `zod` 为 `^3.25.0`。
63
- - **不同步骤的账号与权限要求：**
64
- 1. **离线转换与结构校验**（`convert`、`inspect`、`doctor`、`agent-sdk validate`、`agent-sdk eval --list`）：无需登录 Cursor 账号或配置 API Key。
65
- 2. **调用真实模型运行**（`agent-sdk dev`、`agent-sdk run`、实际执行 `agent-sdk eval`）：需先运行 `agent-sdk login` 登录，且账号具备对应模型访问权限。
66
- 3. **云端托管部署**（`agent-sdk deploy`）：可选步骤，需账号所属团队已开通 hosting 权限并授权对应仓库。
71
+ `convert` / `demo` 在依赖缺失、但输出已写入时退出 0，`validation.status` 为 `dependencies-missing`，此时尚未执行校验。安装输出项目的依赖后，`doctor` 仅在校验通过时退出 0。实际校验失败会使 `convert` / `demo` 退出 1，但输出文件已经写入。转换器不会自动安装依赖。
67
72
 
68
- `convert` / `demo` 在工程已写出、但缺少声明的 SDK 或 `zod` 依赖时退出 0，`validation.status` 为 `dependencies-missing`，并列出缺失包名；这时尚未执行校验。安装依赖后运行 `agent2cursor doctor --dir <project>`，`doctor` 在校验通过前仍返回非零。真实校验错误仍使转换退出 1；转换器不会自动安装依赖。
73
+ ## 试用仓库样本（可选）
74
+
75
+ npm 包包含两个 demo，**不包含 `fixtures/`、转换器的 `src/` 目录或其开发工具链**。要运行仓库样本，请单独克隆源码：
76
+
77
+ ```bash
78
+ git clone https://github.com/mreasonyang/agent2cursor.git
79
+ cd agent2cursor
80
+ npm ci --ignore-scripts
81
+ npm run build
82
+
83
+ node dist/cli.js inspect ./fixtures/claude ./fixtures/tstack/skills/full-send --with-deps --lang zh
84
+ node dist/cli.js convert ./fixtures/claude ./fixtures/tstack/skills/full-send \
85
+ --with-deps --lang zh --out ../agent2cursor-fixture
86
+ ```
87
+
88
+ 这组样本生成 **28 个文件**：4 个子代理、5 个 skill（含 4 个 `tstack` 依赖）和 1 个禁用脚本工具存根，报告位于 `../agent2cursor-fixture/MIGRATION.zh-CN.md`。输出目录必须尚不存在；重跑时请选择其他 `--out` 路径。审查报告后，可在 `agent2cursor-fixture` 中执行上文的校验步骤。这些样本只演示转换与结构检查，不证明运行时权限保留或真实模型行为等价。
69
89
 
70
90
  ## 转换 Codex 资产
71
91
 
72
- 完成本地构建后，可以传入项目或个人子代理目录、单个 TOML 文件，以及 skill 目录；也可以与 Claude 输入一起转换：
92
+ 使用已安装的命令（也可把 `agent2cursor` 替换为 `npx --yes @kyun.si/agent2cursor@0.1.1`），传入项目或个人子代理目录、单个 TOML 文件及 skill 目录。混合输入是另一种用法；只传实际存在的路径：
73
93
 
74
94
  ```bash
75
- node dist/cli.js inspect .codex/agents .agents/skills
76
- node dist/cli.js convert .codex/agents .agents/skills --out ./my-codex-agent
77
- # 仓库内的合成示例，无需安装 Codex 或登录账号
78
- node dist/cli.js convert fixtures/codex/project --out /tmp/codex-example
95
+ agent2cursor inspect .codex/agents .agents/skills --lang zh
96
+ agent2cursor convert .codex/agents .agents/skills --out ./my-codex-agent --lang zh
97
+ # 可选：混合 Claude、Codex 与 skills
98
+ agent2cursor convert .claude/agents .codex/agents .agents/skills --out ./mixed-agent --lang zh
79
99
  ```
80
100
 
81
101
  只传实际存在的路径，子代理和 skill 可以单独转换。个人独立子代理目录 `~/.codex/agents` 也支持。传入项目根目录时会发现这些子代理树和 skill 目录，无关 TOML 文件不会被当作子代理。
@@ -159,7 +179,7 @@ export default defineAgent({
159
179
  | `doctor [--dir <project>]` | 检查 Node `>=22.13` 并调用 `agent-sdk validate` 输出脱敏诊断摘要 |
160
180
  | `--out <dir>` | `convert` 的新输出目录（默认 `./my-agent`；路径已存在时拒绝覆盖） |
161
181
  | `--name <name>` | 生成的代理名称（`1–64` 位小写字母、数字、`-` 或 `_`，以字母或数字开头，默认 `converted-agent`） |
162
- | `--lang <zh\|en>` | 生成的说明书、eval 提示词与 `MIGRATION.zh-CN.md` / `MIGRATION.en.md` 语言（默认 `zh`） |
182
+ | `--lang <zh\|en>` | `convert` / `inspect` 输出语言（默认 `zh`），选择生成的说明、eval 提示词和报告文件名；不翻译源文本或内置示例 |
163
183
  | `--with-deps` | 按 `tstack` 依赖图自动补齐同级目录中被依赖的关联技能 |
164
184
  | `--model-map <map>` | 显式映射模型 ID，如 `--model-map sonnet=<已核实模型ID>`（需用自己的账号核实可用性） |
165
185
  | `--keep-model` | 原样保留未验证的源模型 ID，而不是省略以继承父模型 |
@@ -168,7 +188,14 @@ export default defineAgent({
168
188
 
169
189
  ## 内置示例（Demos）
170
190
 
171
- 两个示例均基于 [t3dotgg/tstack](https://github.com/t3dotgg/tstack) 固定 MIT 快照（`7de017b3fc9d50c03cf3ecb98fb71e0ca65a78bd`）改编为中文工作流，附带 `LICENSE-tstack` 与 `TSTACK-PROVENANCE.json`。可通过 `node dist/cli.js demo <full-send|pr-review> --out <dir>` 导出：
191
+ 两个示例均基于 [t3dotgg/tstack](https://github.com/t3dotgg/tstack) 固定 MIT 快照（`7de017b3fc9d50c03cf3ecb98fb71e0ca65a78bd`）改编为中文工作流，附带 `LICENSE-tstack` 与 `TSTACK-PROVENANCE.json`。npm 包已包含这两个示例，无需克隆源码。分别导出到新目录：
192
+
193
+ ```bash
194
+ agent2cursor demo full-send --out ./full-send-agent
195
+ agent2cursor demo pr-review --out ./pr-review-agent
196
+ ```
197
+
198
+ 使用一次性方式时，把命令前缀换成 `npx --yes @kyun.si/agent2cursor@0.1.1`。示例固定为中文工作流，`demo` 不接受 `--lang`。导出后进入所选示例目录，运行 `npm install` 和 `npm run validate`。
172
199
 
173
200
  - **`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 会话禁止合并）。
174
201
  - **`pr-review`（[操作说明](demos/pr-review/README.md)）：** 含 `council` 与 `leaving-pr-comments` 技能及 3 个评审子代理（`reviewer-a`、`reviewer-b`、`reviewer-c`）。三个子代理继承同一父模型，输出中文 `Council review` 评分表，并明确声明当前是同一模型的三种视角而非三家模型厂商。根代理仅保留只读搜索与委派工具，不提供发评论或改 PR 描述的工具。
@@ -181,23 +208,24 @@ export default defineAgent({
181
208
 
182
209
  - **工具名扫描范围：** 固定名单区分大小写检测正文和附属 Markdown 中的 `WebFetch`、`WebSearch`、`AskUserQuestion`、`request_user_input`、`delegate_task`、`orchestrator_capabilities`、`watch_pull_request`、`unwatch_pull_request`、`Monitor`。命中可能来自禁止调用的说明；未命中不代表工具兼容，不改写源提示词。
183
210
  - **根代理工具白名单不等于子代理隔离：** `--root-tools` 仅约束根代理。`@grok/agent-sdk@0.3.0` 的 `task` 子代理仍保有 harness 自身的 `task` 工具集，不能把根白名单当作子代理只读的证明；同时任何启用 `shell` 的配置都能写文件和执行任意命令，绝非只读。
184
- - **脚本工具默认是禁用存根：** 转换过程绝不执行输入脚本。生成的 `bot/tools/*.ts` 固定返回 `AGENT2CURSOR_STUB_DISABLED`，需操作员审查 `.cursor/skills/<id>/scripts/*` 中的原脚本、实现 JSON stdin/stdout 契约并开启 `shell` 后才能启用。
211
+ - **脚本工具默认是禁用存根：** 转换过程绝不执行输入脚本。生成的 `bot/tools/*.ts` 固定返回 `AGENT2CURSOR_STUB_DISABLED`，需操作员审查复制到 `bot/skills/<id>/scripts/*` 的原脚本、实现 JSON stdin/stdout 契约并开启 `shell` 后才能启用。
185
212
  - **输入与输出防护范围：** 转换器拒绝覆盖已有输出目录、拒绝符号链接、限制单次生成体积上限为 128 MiB，跳过或拒绝已知凭据路径（`.env`、`.npmrc`、私钥文件），并拒绝敏感 YAML/TOML 键名（`token`、`apiKey`、`secret`），解析错误不回显源值；它不会对任意正文段落或二进制附件做全量秘密扫描。
186
213
 
187
214
  **当前验收状态摘要（各证据层级严格区分）：**
188
215
 
189
216
  | 证据层级 | 状态 | 已验证范围与未覆盖边界 |
190
217
  | --- | --- | --- |
191
- | 离线单测与结构校验 | **PASS**（已有证据） | 仓库清理前 59 项本地测试通过。生成项目在独立临时目录中安装自身依赖，通过 SDK `validate` / `info` / `eval --list` 及严格 `tsc`。`eval --list` 仅证明发现用例；本次清理未重跑这些测试 |
218
+ | npm 发布与安装 | **按版本记录** | [发布回执](https://github.com/mreasonyang/agent2cursor/blob/main/npm-publication.json)绑定实际版本和归档哈希，并记录匿名安装、固定版本／默认 `npx`、混合转换、两个 demo 导出及 doctor 检查；历史回执单独保留 |
219
+ | 离线单测与结构校验 | **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) |
192
220
  | 独立转换与路由评测 | **PASS**（限定数据集） | 正常转换及安装后校验 24/24；新版自动路由 eval 在 30 个项目中 41/41 通过。3 个真实任务各重复 3 次，与直接复制/插件对照打平。[计数与源码哈希](docs/evidence/independent-evaluation.json) |
193
- | 真实模型运行 | **PASS**（窄用例） | 已完成官方 `agent-sdk login`。`migration-smoke` 通过（**1 条用例 / 2 个断言**：`succeeded`、`loadedSkill`）；`pr-review` 内联 diff 评审通过（**1 条用例 / 9 个断言**，同模型 3 视角）；`full-send` 本地 `run` 完成 1 次 skill 读取，0 次写入/执行/合并 |
194
- | GitHub PR 回放 | **PASS**（本地回放） | [私有测试 PR #1](https://github.com/mreasonyang/agent2cursor/pull/1) 经 HMAC 签名**本地回放**通过（有界快照 + 3 次子代理委派 + 中文评分表；0 工具错误、0 写入/执行、0 GitHub 评论/reaction/review；测试 PR 已关闭且未合并）。不等于线上托管 webhook 投递 |
195
- | 云端托管 | **未运行 / 暂缓** | 测试账号未配置默认团队（`no default team`），`agent-sdk deploy --dry-run` 在前置条件处停止，未执行实际部署，无部署 URL |
221
+ | 真实模型运行 | **历史 PASS**（窄用例） | 已完成官方 `agent-sdk login`。`migration-smoke` 通过（**1 条用例 / 2 个断言**：`succeeded`、`loadedSkill`）；`pr-review` 内联 diff 评审通过（**1 条用例 / 9 个断言**，同模型 3 视角）；`full-send` 本地 `run` 完成 1 次 skill 读取，0 次写入/执行/合并 |
222
+ | GitHub PR 回放 | **历史 PASS**（本地回放） | [历史测试 PR #1](https://github.com/mreasonyang/agent2cursor/pull/1) 经 HMAC 签名**本地回放**通过（有界快照 + 3 次子代理委派 + 中文评分表；0 工具错误、0 写入/执行、0 GitHub 评论/reaction/review；测试 PR 已关闭且未合并）。不等于线上托管 webhook 投递 |
223
+ | 云端托管 | **未运行 / 暂缓** | 最近一轮记录中，测试账号缺少默认团队（`no default team`），`agent-sdk deploy --dry-run` 在前置条件处停止。托管部署尚未完成，没有经过验证的部署 URL |
196
224
 
197
- 上述单点结果不证明任意输入下的平均模型质量、多厂商路由或子代理运行时隔离。完整记录见：[验收记录](docs/acceptance.md) · [上游核实说明](docs/upstream-verification.md) · [脱敏线上证据](docs/evidence/online-2026-10-27.json) · [官方示例来源记录](docs/official-examples.provenance.json)。
225
+ 历史模型运行与 PR 回放没有因 Codex 适配、npm 发布或本次文档核对而重跑。上述单点结果不证明任意输入下的平均模型质量、多厂商路由或子代理运行时隔离。完整记录见：[验收记录](docs/acceptance.md) · [上游核实说明](docs/upstream-verification.md) · [脱敏线上证据](docs/evidence/online-2026-10-27.json) · [官方示例来源记录](docs/official-examples.provenance.json)。
198
226
 
199
227
  ## 开发维护与许可证
200
228
 
201
- 维护者自检命令（`npm run check`、`npm run test:sdk`、`node scripts/build-demos.mjs`）与仓库安全守则见 [CONTRIBUTING.md](CONTRIBUTING.md)。
229
+ 维护者自检命令（`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)。
202
230
 
203
231
  `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)。
package/dist/cli.js CHANGED
@@ -10,7 +10,7 @@ import { SDK_VERSION } from "./ir.js";
10
10
  import { validateProject, findSdk, supportedNode, validationMessage } from "./validate.js";
11
11
  import { permissionWarning } from "./mapping/permissions.js";
12
12
  import { updateProjectReport, writeProject } from "./write.js";
13
- const VERSION = "0.1.0";
13
+ const VERSION = "0.1.1";
14
14
  const program = new Command().name("agent2cursor").description("Claude Code / Codex agents / Agent Skills → editable Cursor Agent SDK projects with migration reports").version(VERSION);
15
15
  const legalTools = new Set(["read", "grep", "glob", "ls", "shell", "edit", "task", "delete"]);
16
16
  function options(raw) {
package/docs/acceptance.md CHANGED
@@ -1,8 +1,8 @@
1
1
  # agent2cursor 验收记录
2
2
 
3
- 更新日期：2026-10-28。版本：`0.1.0`。目标 SDK：`@grok/agent-sdk@0.3.0`。用户已确定项目名为 `agent2cursor`。
3
+ 更新日期：2026-10-28。版本：`0.1.1`。目标 SDK：`@grok/agent-sdk@0.3.0`。用户已确定项目名为 `agent2cursor`。
4
4
 
5
- 当前用户决定（2026-10-28）：GitHub 仓库 `mreasonyang/agent2cursor` 公开，并授权将 `@kyun.si/agent2cursor@0.1.0` 发布到 npm。根 package.json 保持 `private: true`，单独构建公开消费者归档；安装后的命令仍为 `agent2cursor`。npm 发布结果单独验证。
5
+ 当前用户决定（2026-10-28）：GitHub 仓库 `mreasonyang/agent2cursor` 公开，已完成 npm 0.1.0 发布，并授权用 `@kyun.si/agent2cursor@0.1.1` 同步安装包内的双语文档。根 package.json 保持 `private: true`，单独构建公开消费者归档；安装后的命令仍为 `agent2cursor`。npm 发布结果单独验证。
6
6
 
7
7
  ## agent2cursor 更名（2026-10-28）
8
8
 
@@ -16,12 +16,28 @@
16
16
 
17
17
  `npm pack` 产物为 `agent2cursor-0.1.0.tgz`，在仓库外的干净 consumer 安装后验证了真实 `agent2cursor` bin 的帮助、版本、混合 Claude/Codex/skill 转换、两个 demo 和缺依赖时的 doctor 状态；运行源码与输出不再含旧项目标识。README 动图重新渲染为 960×540、10 fps、14 秒（140 帧），并核对海报画面和 [SOURCE.json](demo-video/SOURCE.json) 的新哈希。GitHub 仓库与 origin、本地目录均已更名，更名当时仍为私有；该轮没有发布到 npm。
18
18
 
19
+ ## npm 0.1.0 公开发布（2026-10-28）
20
+
21
+ `@kyun.si/agent2cursor@0.1.0` 已发布到 npm 官方 registry。发布源码为 `b0e30fa5eb85d479e3ab64ee8ebd022061160a4a`，该提交的 Node 22.13 / 24 测试、打包预演和五类 SDK 集成 CI 全部通过。[0.1.0 发布回执](evidence/npm-publication-0.1.0.json)绑定该源提交和实际发布归档，后续文档及发布工具调整不改写这份已发布的包。
22
+
23
+ 通过匿名版本接口读回 registry 元数据并下载公开 tarball，字节数（573541）、SHA-256 和 registry SHA-512 integrity 与发布候选完全一致。在仓库外使用空的用户/全局 npm 配置、新缓存，实际从 registry 安装；真实 bin 的帮助和版本通过。另用独立空目录验证固定 `0.1.0` 的 `npx --help` 和默认 `latest` 的 `npx --version`，实际均为 `0.1.0`。
24
+
25
+ 公开安装产物完成 Claude / Codex / full-send skill 混合输入的 inspect 与 convert（6 个子代理、6 个 skill、4 个依赖、1 个禁用脚本存根），两个 demo 导出正常。doctor 在依赖缺失时明确失败，安装生成工程自身依赖后通过 SDK 结构自检。包内无 `private`、开发依赖或生命周期脚本。本次发布未执行真实模型或托管部署。
26
+
27
+ GitHub 仓库已改为 public，并通过无认证 API 请求确认匿名访问返回 200。
28
+
29
+ ## 双语 README 核对（2026-10-28）
30
+
31
+ 按公开 `@kyun.si/agent2cursor@0.1.0` 实测两份 README 的安装和使用路径，40 次命令检查通过。使用空的用户／全局 npm 配置、独立缓存和隔离全局 prefix，完成中英文的全局安装与 npx、Claude / Codex / 混合转换、两个 demo 导出，以及生成工程自身的 `npm install`、结构校验、eval 发现和 doctor。克隆公开仓库后执行 `npm ci`、构建和样本转换，每种语言均生成 28 个文件。7 个 shell 代码块除语言参数外完全一致，本地 Markdown 链接均有效。
32
+
33
+ 已修正安装后与源码命令混用、npx 仅展示帮助、SDK 校验及启动步骤不完整、旧测试数量、历史模型／PR 回放标签和脚本审查目录。`npm run dev -- --web` 经 SDK 0.3.0 的公开 CLI 帮助核对；本轮没有登录 Cursor 或运行真实模型、eval、部署。74 项项目测试通过，证据及最终 README 哈希见 [文档核对回执](evidence/readme-audit-2026-10-28.json)。npm 0.1.0 归档内文档保留发布快照，本轮不改写已发布归档。
34
+
19
35
  ## 已验证
20
36
 
21
37
  | 项目 | 结果 | 证据边界 |
22
38
  | --- | --- | --- |
23
39
  | TypeScript 构建 | PASS | 本次本机 Node 26.11.0 与生成项目严格类型检查通过；历史私有 CI Node 22.13 / 24 已通过，当前提交 CI 见工作流 |
24
- | 自动测试 | PASS，73 项 | 2026-10-28 重跑 npm run check；新增 Codex TOML、混合输入、逐字段元数据、权限提示、敏感字段拒绝、解析错误不回显及打包前 CLI 回归 |
40
+ | 自动测试 | PASS，74 项 | 2026-10-28 发布源码和后续 CI 通过；包含 Codex TOML、混合输入、逐字段元数据、权限提示、引用 skill 不加载、敏感字段拒绝、解析错误不回显及 CLI 回归。下文 Codex 初轮的 73 项保留为历史记录 |
25
41
  | Codex 转换 | PASS，2 个子代理、1 个 skill | 合成 TOML 与 openai.yaml 样例；配置发现、类型检查与 SDK 结构校验通过，未跑真实模型 |
26
42
  | 四类 Claude 示例 | PASS，4 个子代理 | 独立编写的官方示例模式 fixture；不是官方示例逐字副本 |
27
43
  | 官方原始示例 | PASS，4 个子代理，零诊断 | 从官方 Markdown 下载并提取 code-reviewer/debugger/data-scientist/db-reader，在忽略目录转换；不把官方原文作为 fixture 再分发，哈希见 official-examples.provenance.json |
package/docs/evidence/npm-publication-0.1.0.json ADDED
@@ -0,0 +1,46 @@
1
+ {
2
+ "verifiedAt": "2026-10-28T07:08:02.624501+00:00",
3
+ "name": "@kyun.si/agent2cursor",
4
+ "version": "0.1.0",
5
+ "registry": "https://registry.npmjs.org/",
6
+ "sourceRevision": "b0e30fa5eb85d479e3ab64ee8ebd022061160a4a",
7
+ "publicationExitCode": 0,
8
+ "distTag": "latest",
9
+ "latestVersionVerifiedBy": "npx @kyun.si/agent2cursor --version in an empty directory and fresh cache",
10
+ "tarball": "https://registry.npmjs.org/@kyun.si/agent2cursor/-/agent2cursor-0.1.0.tgz",
11
+ "integrity": "sha512-vYcNz181tue/3szNeKjarOjU8ah9aEo2zODqnwEQtyiUlvMHWkNz4Uo3sDFhSrQNWgeizYJbzuLtNQbElH8jmA==",
12
+ "shasum": "e907056c24f7ec2b0290fc6c67b0468c36f62e8d",
13
+ "bytes": 573541,
14
+ "sha256": "caaf9f021033b47c664bb940ee36dfb2d7dce4fc8fcbf5f762dc98d13e00a94b",
15
+ "registryBytesMatchCandidate": true,
16
+ "anonymousRegistryReadback": true,
17
+ "verification": {
18
+ "cleanRegistryInstall": true,
19
+ "emptyUserAndGlobalConfig": true,
20
+ "cliHelpAndVersion": true,
21
+ "npxPinnedHelp": true,
22
+ "npxLatestVersion": "0.1.0",
23
+ "mixedInspectAndConvert": {
24
+ "agents": 6,
25
+ "skills": 6,
26
+ "dependencies": 4,
27
+ "scripts": 1
28
+ },
29
+ "demos": [
30
+ "full-send",
31
+ "pr-review"
32
+ ],
33
+ "doctorBeforeInstall": "dependencies-missing",
34
+ "doctorAfterInstall": "passed"
35
+ },
36
+ "ci": {
37
+ "url": "https://github.com/mreasonyang/agent2cursor/actions/runs/40645554908",
38
+ "conclusion": "success"
39
+ },
40
+ "github": {
41
+ "url": "https://github.com/mreasonyang/agent2cursor",
42
+ "visibility": "public"
43
+ },
44
+ "liveModelRun": "not-run-for-publication",
45
+ "deployment": "not-run"
46
+ }
package/docs/evidence/readme-audit-2026-10-28.json ADDED
@@ -0,0 +1,248 @@
1
+ {
2
+ "verifiedAt": "2026-10-28T07:29:04.620950+00:00",
3
+ "package": "@kyun.si/agent2cursor@0.1.0",
4
+ "npmConfiguration": "empty user/global configuration; isolated global prefix and cache",
5
+ "scenarios": [
6
+ {
7
+ "language": "en",
8
+ "globalAndNpx": "passed",
9
+ "codexAndMixedInputs": "passed",
10
+ "generatedInstallValidateEvalDiscoveryDoctor": "passed",
11
+ "demosExported": 2
12
+ },
13
+ {
14
+ "language": "zh",
15
+ "globalAndNpx": "passed",
16
+ "codexAndMixedInputs": "passed",
17
+ "generatedInstallValidateEvalDiscoveryDoctor": "passed",
18
+ "demosExported": 2
19
+ }
20
+ ],
21
+ "sourceFixtureFilesPerLanguage": 28,
22
+ "sourceFixtureCounts": {
23
+ "agents": 4,
24
+ "skills": 5,
25
+ "dependencies": 4,
26
+ "scripts": 1
27
+ },
28
+ "bilingualBashBlockParity": true,
29
+ "localMarkdownLinks": "passed",
30
+ "liveModelExecution": "not-run; login/dev syntax checked with --help only",
31
+ "cloudDeployment": "not-run",
32
+ "checks": [
33
+ {
34
+ "check": "isolated-global-install",
35
+ "exitCode": 0,
36
+ "expectedExitCode": 0
37
+ },
38
+ {
39
+ "check": "global-help",
40
+ "exitCode": 0,
41
+ "expectedExitCode": 0
42
+ },
43
+ {
44
+ "check": "global-version",
45
+ "exitCode": 0,
46
+ "expectedExitCode": 0
47
+ },
48
+ {
49
+ "check": "global-inspect-en",
50
+ "exitCode": 0,
51
+ "expectedExitCode": 0
52
+ },
53
+ {
54
+ "check": "global-convert-en",
55
+ "exitCode": 0,
56
+ "expectedExitCode": 0
57
+ },
58
+ {
59
+ "check": "doctor-before-install-en",
60
+ "exitCode": 1,
61
+ "expectedExitCode": 1
62
+ },
63
+ {
64
+ "check": "generated-npm-install-en",
65
+ "exitCode": 0,
66
+ "expectedExitCode": 0
67
+ },
68
+ {
69
+ "check": "generated-validate-en",
70
+ "exitCode": 0,
71
+ "expectedExitCode": 0
72
+ },
73
+ {
74
+ "check": "generated-eval-list-en",
75
+ "exitCode": 0,
76
+ "expectedExitCode": 0
77
+ },
78
+ {
79
+ "check": "npx-doctor-after-install-en",
80
+ "exitCode": 0,
81
+ "expectedExitCode": 0
82
+ },
83
+ {
84
+ "check": "sdk-login-help-only-en",
85
+ "exitCode": 0,
86
+ "expectedExitCode": 0
87
+ },
88
+ {
89
+ "check": "sdk-dev-help-only-en",
90
+ "exitCode": 0,
91
+ "expectedExitCode": 0
92
+ },
93
+ {
94
+ "check": "codex-convert-en",
95
+ "exitCode": 0,
96
+ "expectedExitCode": 0
97
+ },
98
+ {
99
+ "check": "mixed-convert-en",
100
+ "exitCode": 0,
101
+ "expectedExitCode": 0
102
+ },
103
+ {
104
+ "check": "demo-export-full-send-en",
105
+ "exitCode": 0,
106
+ "expectedExitCode": 0
107
+ },
108
+ {
109
+ "check": "demo-export-pr-review-en",
110
+ "exitCode": 0,
111
+ "expectedExitCode": 0
112
+ },
113
+ {
114
+ "check": "npx-inspect-en",
115
+ "exitCode": 0,
116
+ "expectedExitCode": 0
117
+ },
118
+ {
119
+ "check": "npx-convert-en",
120
+ "exitCode": 0,
121
+ "expectedExitCode": 0
122
+ },
123
+ {
124
+ "check": "global-inspect-zh",
125
+ "exitCode": 0,
126
+ "expectedExitCode": 0
127
+ },
128
+ {
129
+ "check": "global-convert-zh",
130
+ "exitCode": 0,
131
+ "expectedExitCode": 0
132
+ },
133
+ {
134
+ "check": "doctor-before-install-zh",
135
+ "exitCode": 1,
136
+ "expectedExitCode": 1
137
+ },
138
+ {
139
+ "check": "generated-npm-install-zh",
140
+ "exitCode": 0,
141
+ "expectedExitCode": 0
142
+ },
143
+ {
144
+ "check": "generated-validate-zh",
145
+ "exitCode": 0,
146
+ "expectedExitCode": 0
147
+ },
148
+ {
149
+ "check": "generated-eval-list-zh",
150
+ "exitCode": 0,
151
+ "expectedExitCode": 0
152
+ },
153
+ {
154
+ "check": "npx-doctor-after-install-zh",
155
+ "exitCode": 0,
156
+ "expectedExitCode": 0
157
+ },
158
+ {
159
+ "check": "sdk-login-help-only-zh",
160
+ "exitCode": 0,
161
+ "expectedExitCode": 0
162
+ },
163
+ {
164
+ "check": "sdk-dev-help-only-zh",
165
+ "exitCode": 0,
166
+ "expectedExitCode": 0
167
+ },
168
+ {
169
+ "check": "codex-convert-zh",
170
+ "exitCode": 0,
171
+ "expectedExitCode": 0
172
+ },
173
+ {
174
+ "check": "mixed-convert-zh",
175
+ "exitCode": 0,
176
+ "expectedExitCode": 0
177
+ },
178
+ {
179
+ "check": "demo-export-full-send-zh",
180
+ "exitCode": 0,
181
+ "expectedExitCode": 0
182
+ },
183
+ {
184
+ "check": "demo-export-pr-review-zh",
185
+ "exitCode": 0,
186
+ "expectedExitCode": 0
187
+ },
188
+ {
189
+ "check": "npx-inspect-zh",
190
+ "exitCode": 0,
191
+ "expectedExitCode": 0
192
+ },
193
+ {
194
+ "check": "npx-convert-zh",
195
+ "exitCode": 0,
196
+ "expectedExitCode": 0
197
+ },
198
+ {
199
+ "check": "public-source-clone",
200
+ "exitCode": 0,
201
+ "expectedExitCode": 0
202
+ },
203
+ {
204
+ "check": "source-npm-ci",
205
+ "exitCode": 0,
206
+ "expectedExitCode": 0
207
+ },
208
+ {
209
+ "check": "source-build",
210
+ "exitCode": 0,
211
+ "expectedExitCode": 0
212
+ },
213
+ {
214
+ "check": "source-inspect-en",
215
+ "exitCode": 0,
216
+ "expectedExitCode": 0
217
+ },
218
+ {
219
+ "check": "source-fixture-convert-en",
220
+ "exitCode": 0,
221
+ "expectedExitCode": 0
222
+ },
223
+ {
224
+ "check": "source-inspect-zh",
225
+ "exitCode": 0,
226
+ "expectedExitCode": 0
227
+ },
228
+ {
229
+ "check": "source-fixture-convert-zh",
230
+ "exitCode": 0,
231
+ "expectedExitCode": 0
232
+ }
233
+ ],
234
+ "readmeSha256": {
235
+ "README.md": "cc6504f9b04496e5b0ab973baa6bfea241242a9d74a1785185a1e1fa13aee723",
236
+ "README.zh-CN.md": "b12e203c116366cf840a7ab9599f417bfd565d5d53da34af3af9bf91e8bae132"
237
+ },
238
+ "sourceRevisionBase": "02999e9ec55ee27bfb02cad35f7e2da2e3cbcd71",
239
+ "publishedPackageSourceRevision": "b0e30fa5eb85d479e3ab64ee8ebd022061160a4a",
240
+ "unitTests": {
241
+ "command": "npm run check",
242
+ "passed": 74,
243
+ "failed": 0
244
+ },
245
+ "sdkDevWebFlagVerified": true,
246
+ "publishedArchiveReadmes": "immutable 0.1.0 release snapshots; current GitHub READMEs are corrected",
247
+ "productRuntimeCodeChanged": false
248
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kyun.si/agent2cursor",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "Convert Claude Code and Codex agents and skills into editable Cursor Agent SDK projects, with field-by-field migration reports.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -28,5 +28,5 @@
28
28
  "bugs": {
29
29
  "url": "https://github.com/mreasonyang/agent2cursor/issues"
30
30
  },
31
- "gitHead": "b0e30fa5eb85d479e3ab64ee8ebd022061160a4a"
31
+ "gitHead": "06d5907667631b2c68eee7f7741f9a131c2f229f"
32
32
  }