@easytwin/devkit

EasyTwin 第三方应用开发工具集的核心包:lib(函数库)与 bin(easytwin 命令)双导出,供人类与 AI agent(如 Cursor / Claude Code / Codex)共同使用。设计蓝图见仓库根 AGENTS.md。

安装

npm i -g @easytwin/devkit   # 全局安装 CLI

也可作为库安装:npm i @easytwin/devkit。

命令

| 命令 | 行为 | | --- | --- | | easytwin init | 交互式生成 .easytwin/easytwin.config.json,并将凭据与 .easytwin/scenes/ 追加进 .gitignore(无则创建) | | easytwin scene list | 列出凭据可见的场景,并把摘要写入 .easytwin/easytwin.config.json.scenes | | easytwin scene pull <id> [--out <path>] | 拉取场景 JSON:写入 .easytwin/scenes/<id>.scene.json;--out 再额外写一份 | | easytwin scene inspect <id> [--name] [--type] | 只读本地快照,打印对象树(id/name/type);超过 200 节点截断 | | easytwin upload [dir] | 对照远端全量对齐工作区(缺省 cwd;跳过插件产物) | | easytwin skills sync [--target cursor\|claude\|codex\|all] | 同步 skills 到用户项目,缺省 all |

配置

.easytwin/easytwin.config.json(项目级):

{
  "appId": "必填",
  "appSecret": "必填",
  "env": "可选,prod=正式 / test=测试,缺省 prod",
  "baseUrl": "可选,缺省按 env 选官方域名",
  "ossUrl": "可选,缺省官方 OSS",
  "scenes": "可选,由 scene list 写入的场景摘要"
}

环境变量 EASYTWIN_APP_ID / EASYTWIN_APP_SECRET / EASYTWIN_BASE_URL / EASYTWIN_ENV / EASYTWIN_OSS_URL 优先于文件。请求带 x-app-id(App ID)与 x-app-secret(App Secret),不走 OP 网关。官方 API:正式 http://saas-twin.k8s.dtstack.cn/、测试 http://172.16.125.3:10100/,缺省按 env 选择。官方 OSS 资产根:https://dt-easyv-test.oss-cn-hangzhou.aliyuncs.com/,供 twin runtime 加载 webp/draco/组件脚本。runtime 类型:env=prod 用正式桶 https://dt-easyv-prod.oss-cn-hangzhou.aliyuncs.com/easytwin/system/libs/runtime/types/,其余用测试桶同路径。文件含密钥,永不入库(init 会处理 gitignore)。

skills

六件套(easytwin-render / -core / -develop / -bootstrap / -scene / -upload)随包分发,通过 easytwin skills sync 显式写入 Cursor(.cursor/skills/)、Claude Code(.claude/skills/)与 Codex(AGENTS.md 标记段),重复执行幂等。

发布到 npm

# 1. 登录(写入 ~/.npmrc 的 npmjs token;CI 用 NPM_TOKEN 环境变量)
npm login --registry https://registry.npmjs.org/

# 2. 确认发布产物应包含 dist/ 与 skills/
npm pack --dry-run

# 3. 升版本
npm version patch|minor|major

# 4. 发布(必须先升版本:同版本已在 npm 上会被跳过,提示 There are no new packages that should be published)
# 在仓库根目录用 run,不要直接 pnpm publish(那是工作区递归发布内置命令)
pnpm run publish

• scoped 包需 publishConfig.access 为 public,已配置;
• 本机默认 registry 是 npmmirror,publishConfig.registry 已固定为官方 npmjs;
• pnpm run publish 只在本次进程清掉 proxy / HTTP_PROXY,不改 ~/.npmrc;Clash 日常代理可保持 http://127.0.0.1:7890;
• 包名是否被占用可用 npm view @easytwin/devkit 确认;
• repository 目前指向内网 GitLab,公网发布前建议改为公开地址(可选)。

开发

pnpm install
pnpm -r build
pnpm -r test

已知外部输入(TODO)

渲染 API 文档与 d.ts 仍未到位,skills 中以 TODO(外部输入) 标记,不臆造。场景列表/拉取与工作区代码上传已按内部 swagger(SDK 应用场景 / SDK 应用代码)落地;官方 API 域名、官方 OSS 与场景 JSON 格式已定(见上)。