@shulex/cxclawctl 0.1.2 → 0.1.4

package/README.md

@@ -1,6 +1,6 @@
 # CXClaw
 
-CXClaw 是 Solvea 内部使用的 Codex 插件。它把原 CXClaw 的业务能力带到本地 Codex：Codex 负责理解任务和编排步骤，`cxclaw` CLI 负责登录、选择租户、调用业务接口、执行现有 Python 脚本和直查 SLS。
+CXClaw 是 Solvea 内部使用的 Codex 插件。它把原 CXClaw 的业务能力带到本地 Codex：Codex 负责理解任务和编排步骤，`cxclaw` CLI 负责登录、选择租户、调用业务接口、执行本地工作流和直查 SLS。所有业务代码统一使用 TypeScript，Skills 只描述流程并调用 CLI。
 
 插件不启动本地 MCP，也不依赖 `solvea-kit`。`shulex-cloud` 只提供钉钉授权、租户授权、服务配置和短期凭据；具体业务操作由本机 CLI 执行。
 
@@ -20,17 +20,9 @@ CXClaw 是 Solvea 内部使用的 Codex 插件。它把原 CXClaw 的业务能
 
 - Codex CLI
 - Node.js 22 或更高版本，包含 `npm` 和 `npx`
-- Python 3.12
-- `requirements-cli.txt` 中锁定的 Python 依赖
 - 可用的系统安全凭据库：macOS Keychain、Windows Credential Manager 或 Linux Secret Service
 
-安装 Python 依赖：
-
-```bash
-python3.12 -m pip install -r requirements-cli.txt
-```
-
-CXClaw 不会回退使用其他 Python 大版本。Linux 没有 Secret Service 时会拒绝保存登录信息，不会把凭据写入明文文件。
+Linux 没有 Secret Service 时会拒绝保存登录信息，不会把凭据写入明文文件。
 
 ## 安装
 
@@ -64,6 +56,8 @@ npx --yes @shulex/cxclawctl@latest setup \
 
 可用通道为 `stable`、`canary` 和 `dev`。内部日常使用请选择 `stable`。
 
+安装后的 Skills 不直接调用 npm `latest`。插件内的 `plugin-cli.mjs` 会读取插件清单版本，并调用完全相同版本的 `@shulex/cxclawctl`，避免新 CLI 与旧 Skills 混用。README 中的 `@latest` 命令只用于首次安装、人工诊断和更新入口。
+
 ## 选择环境和租户
 
 测试环境使用 `--env test`，生产环境使用 `--env prod`。环境由每次租户选择明确指定，不从租户名称推断。
@@ -89,13 +83,17 @@ npx --yes @shulex/cxclawctl@latest tenant clear
 ```bash
 # 查看版本和能力清单
 npx --yes @shulex/cxclawctl@latest version
+npx --yes @shulex/cxclawctl@latest version --json
 npx --yes @shulex/cxclawctl@latest capabilities
 
-# 调用只读业务命令
-npx --yes @shulex/cxclawctl@latest api get-agent --id 456 --pretty
+# 调用只读业务命令；业务命令统一使用“资源 + 动作”两层结构
+npx --yes @shulex/cxclawctl@latest agent get --id 456 --pretty
+npx --yes @shulex/cxclawctl@latest intent list --pretty
 
-# 执行插件内 Python 脚本
-npx --yes @shulex/cxclawctl@latest script skills/poc/scripts/plan.py --init
+# 使用 TypeScript CLI 执行本地工作流
+npx --yes @shulex/cxclawctl@latest poc plan --init
+npx --yes @shulex/cxclawctl@latest kb-builder crawl --url https://docs.example.com
+npx --yes @shulex/cxclawctl@latest solvea-desk fetch-tickets --task-id demo
 
 # 直接从本机查询 SLS；from/to 使用 Unix 秒级时间戳
 npx --yes @shulex/cxclawctl@latest sls query \
@@ -114,12 +112,12 @@ npx --yes @shulex/cxclawctl@latest auth logout
 写操作必须先预览，再由用户明确确认。确认凭证通过 stdin 传入，不能写进命令参数、文件或日志。
 
 ```bash
-npx --yes @shulex/cxclawctl@latest api update-agent \
+npx --yes @shulex/cxclawctl@latest agent update \
   --data-file update.json \
   --phase preview \
   --pretty
 
-printf '%s' "$CONFIRMATION_TOKEN" | npx --yes @shulex/cxclawctl@latest api update-agent \
+printf '%s' "$CONFIRMATION_TOKEN" | npx --yes @shulex/cxclawctl@latest agent update \
   --data-file update.json \
   --phase commit \
   --confirmation-token-stdin \
@@ -129,7 +127,7 @@ printf '%s' "$CONFIRMATION_TOKEN" | npx --yes @shulex/cxclawctl@latest api updat
 
 ## 更新
 
-CLI 使用 `npx --yes @shulex/cxclawctl@latest` 运行，每次启动都会使用 npm 上的最新稳定版本。Skills 由 Codex Git Marketplace 更新：
+自动更新以 Git Marketplace 中的插件版本为准。更新任务先刷新当前配置的 `stable`、`canary` 或 `dev` Marketplace，再重新安装已启用的 CXClaw 插件；新版插件中的 `plugin-cli.mjs` 随后调用同版本 npm CLI：
 
 ```bash
 npx --yes @shulex/cxclawctl@latest update
@@ -141,14 +139,16 @@ npx --yes @shulex/cxclawctl@latest update
 npx --yes @shulex/cxclawctl@latest update --install-scheduler
 ```
 
-更新完成后，新建 Codex 会话或重启 Codex，让新版 Skills 生效。
+更新任务使用安装时解析出的 Node.js 和 npm 绝对路径，避免 macOS LaunchAgent 等后台环境找不到 `npx`。更新后还会确认对应 npm CLI 版本已经公开可下载；检查失败时命令报错，不把不完整更新报告为成功。
+
+更新完成后，新建 Codex 会话或重启 Codex，让新版 Skills 生效。已经运行中的会话继续使用启动时加载的旧版 Skills。
 
 ## 安全边界
 
 - 登录信息只保存在操作系统安全凭据库。
 - SLS 长期 AK/SK 不下发到客户端；CLI 每次查询只申请短期只读 STS，并直接连接阿里云 SLS。
 - 客户端提供的 `tenantId`、`accountId` 和环境值不能直接作为授权依据，服务端签发的租户上下文才是最终权限边界。
-- 业务 token 不输出到终端或日志，只通过受控的子进程环境传给本地业务脚本。
+- 业务 token 不输出到终端或日志，只在请求对象的生命周期内传给 CLI 的 HTTP client。
 - `main` 分支只用于开发；员工使用由发布流程推进的 `marketplace/stable`、`marketplace/canary` 或 `marketplace/dev`。
 
 ## 本地开发
@@ -174,7 +174,7 @@ node bin/cxclawctl.mjs version
 修改 Skills 或业务 command 后，重新生成并校验能力清单：
 
 ```bash
-python3 scripts/check_capabilities.py --write
+bun run check:capabilities -- --write
 bun run check:capabilities
 ```
 
@@ -221,9 +221,12 @@ cxclaw-codex-plugin.zip
 ```text
 .agents/plugins/marketplace.json  Git Marketplace 清单
 .codex-plugin/plugin.json         Codex 插件清单
+plugin-cli.mjs                    将插件固定到同版本 npm CLI
 bin/cxclawctl.mjs                 npm CLI 入口
-src/                              TypeScript CLI 实现
-skills/                           CXClaw Skills 和 Python 业务脚本
+src/                              TypeScript CLI 和业务工作流实现
+skills/                           Marketplace Skills、reference 和静态资源
 capabilities.lock.json            Skills 与业务 command 能力映射
 scripts/                          能力校验和发布打包脚本
 ```
+
+npm 包只包含 CLI 运行时代码；`SKILL.md`、reference 文档和静态资源只通过 Git Marketplace 分发，不在 npm 中重复打包。