@zmice/zc 0.2.1 → 0.2.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zmice
+
+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,68 +1,151 @@
 # @zmice/zc
 
-`@zmice/zc` 是 AI Coding Toolkit 的统一入口 CLI。
+`@zmice/zc` 是 zc AI Coding Toolkit 的统一入口 CLI，也是当前仓库唯一对外发布的 npm 包。
+
+相关入口：
+
+- 源码仓库：<https://github.com/zmice/zc-ai-coding-toolkit>
+- 问题反馈：<https://github.com/zmice/zc-ai-coding-toolkit/issues>
+- Qwen 扩展仓库：<https://github.com/zmice/zc-qwen-extension>
+
+如果你是从 npm 页面进入，先记住这件事：
+
+- `zc` 不是单个平台插件
+- 它是一个统一入口安装器
+- 用来给 Codex、Claude Code、OpenCode、Qwen 安装、更新、诊断和导出结构化 AI 编码内容
+
+## 最短路径
+
+```bash
+npm install -g @zmice/zc
+zc platform install codex --global
+zc platform status codex --global --json
+```
+
+如果你想装到别的平台，把 `codex` 换成：
+
+- `claude`
+- `opencode`
+- `qwen`
+
+如果你只是想安装和更新平台内容，优先看：
+
+- `安装`
+- `平台安装模型`
+- `命名空间适配`
+- `高频用法`
+
+它负责：
 
-它负责两类稳定能力：
 - runtime：启动单工人或团队协作运行时
-- product commands：查询 `toolkit` 内容、生成/安装 `platform` 产物
+- toolkit：查询 skills / commands / agents
+- platform：生成、安装、更新和检查平台产物
+
+它不负责：
 
-它**不负责**仓库治理型事务。像 upstream 审阅、snapshot、report、导入提案这类能力，统一通过根级脚本：
+- 上游治理型仓库事务
+- `references` 的快照、审阅和导入提案
+
+这些仓库级事务统一通过：
 
 ```bash
 pnpm upstream -- <subcommand>
 ```
 
-## 适用场景
+## 支持的平台
+
+| 平台 | 当前安装形态 | 统一入口适配 |
+| --- | --- | --- |
+| Codex | `AGENTS.md` + `skills/` | `zc:start -> $zc-start` |
+| Claude Code | `CLAUDE.md` + `commands/` + `agents/` | `zc:start -> /zc-start` |
+| OpenCode | `AGENTS.md` + `commands/` + `skills/` + `agents/` | `zc:start -> /zc-start` |
+| Qwen | `QWEN.md` + extension 目录 | `zc:start -> zc:start` |
 
-你通常会在下面几种情况下使用 `zc`：
-- 想直接启动一个 AI CLI 工人执行任务：`zc run`
-- 想启动一组 worker 并做任务编排：`zc team ...`
-- 想查询 toolkit 里的 skills / commands / agents：`zc toolkit ...`
-- 想把内容安装到 Codex / Qoder / Qwen：`zc platform ...`
+用户级 Qwen 安装默认会优先走官方扩展链：
 
-## 快速开始
+- 安装源：`https://github.com/zmice/zc-qwen-extension.git`
+- 安装方式：`qwen extensions install`
+- 更新方式：`qwen extensions update zc-toolkit`
 
-在仓库内开发：
+## 参考边界
+
+`zc` 不直接提供 upstream 治理命令，但它的命令面和安装行为会持续对齐平台官方能力与成熟社区实践。
+
+CLI 侧当前重点参考：
+
+- `oh-my-codex`
+- Codex 官方 `AGENTS.md` / skills 文档
+- Claude Code 官方 memory / slash commands / sub-agents 文档
+- OpenCode 官方 rules / commands / skills / agents 文档
+- Qwen 官方 extensions / skills / `qwen extensions` 文档
+
+也就是说：
+
+- 内容参考上游的治理在 `references/`
+- CLI 只吸收与命令体验、安装语义、平台适配直接相关的部分
+
+仓库级 upstream 治理由下面入口承担：
 
 ```bash
-pnpm install
-pnpm build
-node apps/cli/dist/cli/index.js --help
+pnpm upstream -- <subcommand>
 ```
 
-本地开发态安装到本机全局命令：
+## 安装
+
+### npm 全局安装
 
 ```bash
-pnpm install
-pnpm build
-pnpm --dir apps/cli link --global
+npm install -g @zmice/zc
 zc --help
 ```
 
-安装公开发布包：
+### 仓库内构建运行
 
 ```bash
-npm install -g @zmice/zc
-zc --help
+pnpm install
+pnpm build
+node apps/cli/dist/cli/index.js --help
 ```
 
-更新时重复执行：
+### 仓库开发态 link
 
 ```bash
+pnpm setup
 pnpm install
 pnpm build
 pnpm --dir apps/cli link --global
+zc --help
 ```
 
-如果使用 registry 安装：
+如果 `pnpm --dir apps/cli link --global` 报：
+
+- `ERR_PNPM_NO_GLOBAL_BIN_DIR`
+
+说明是 pnpm 环境未初始化，不是 `zc` 构建问题。
+
+## 使用者与维护者
+
+### 普通使用者
+
+最常见的是这条循环：
 
 ```bash
-npm install -g @zmice/zc@latest
+zc platform where codex --global --json
+zc platform install codex --global
+zc platform status codex --global --json
+zc platform update codex --global --plan --json
 ```
 
-完整安装、更新、平台内容安装说明见：
+### 仓库维护者
 
-- [`docs/usage-guide.md`](../docs/usage-guide.md)
+如果你在维护 monorepo 本身，更常用的是：
+
+```bash
+pnpm install
+pnpm --dir apps/cli build
+pnpm --dir apps/cli test
+pnpm verify
+```
 
 ## 命令分层
 
@@ -82,72 +165,176 @@ npm install -g @zmice/zc@latest
 - `zc toolkit recommend <query>`
 
 `<query>` 同时支持：
+
 - 完整资产 ID，例如 `command:build`
 - 唯一名称，例如 `build`
 
 ### Platform
 
-- `zc platform generate <qwen|codex|qoder>`
-- `zc platform install <qwen|codex|qoder>`
-- `zc platform status <qwen|codex|qoder>`
-- `zc platform update <qwen|codex|qoder>`
-- `zc platform where <qwen|codex|qoder>`
+- `zc platform generate <qwen|codex|claude|opencode>`
+- `zc platform install <qwen|codex|claude|opencode>`
+- `zc platform status <qwen|codex|claude|opencode>`
+- `zc platform update <qwen|codex|claude|opencode>`
+- `zc platform uninstall <qwen|codex|claude|opencode>`
+- `zc platform repair <qwen|codex|claude|opencode>`
+- `zc platform doctor <qwen|codex|claude|opencode>`
+- `zc platform where <qwen|codex|claude|opencode>`
+
+常用参数：
 
-常用安装目标参数：
 - `--project`
 - `--global`
 - `--dir <path>`
-
-常用输出参数：
 - `--plan`
 - `--json`
 - `--force`
 
+## 命名空间适配
+
+`toolkit` 里的内容使用统一语义名，例如：
+
+- `zc:start`
+- `zc:product-analysis`
+- `zc:sdd-tdd`
+- `zc:quality-review`
+
+安装到不同平台后，不会强行保留同一种触发形式，而是按平台能力做适配：
+
+- Codex
+  - 统一语义通过 `$zc-*` skill 承接
+  - 例如：`zc:start -> $zc-start`
+- Claude Code
+  - 统一语义通过 `/zc-*` command 承接
+  - 例如：`zc:start -> /zc-start`
+- OpenCode
+  - 统一语义通过 `/zc-*` command 承接
+  - 例如：`zc:start -> /zc-start`
+- Qwen
+  - 统一语义通过 `zc:*` namespaced command 承接
+  - 例如：`zc:start -> zc:start`
+
+这样做的目的只有一个：
+
+- 避免和平台内置命令、社区插件或未来扩展发生冲突
+
+## 平台安装模型
+
+### Codex
+
+- 项目级：`AGENTS.md`
+- 用户级 / 自定义目录：
+  - `AGENTS.md`
+  - `skills/zc-<command>/SKILL.md`
+  - `skills/zc-<skill>/SKILL.md`
+
+### Claude Code
+
+- 项目级：
+  - `CLAUDE.md`
+  - `.claude/commands`
+  - `.claude/agents`
+- 用户级 / 自定义目录：
+  - `CLAUDE.md`
+  - `commands`
+  - `agents`
+
+### OpenCode
+
+- 项目级：
+  - `AGENTS.md`
+  - `.opencode/commands`
+  - `.opencode/skills`
+  - `.opencode/agents`
+- 用户级 / 自定义目录：
+  - `AGENTS.md`
+  - `commands`
+  - `skills`
+  - `agents`
+
+### Qwen
+
+- 项目级：
+  - `.qwen/extensions/zc-toolkit/`
+- 用户级 / 自定义目录：
+  - `extensions/zc-toolkit/`
+- 用户级默认优先通过官方 `qwen extensions` 管理
+- 默认安装源：
+  - `https://github.com/zmice/zc-qwen-extension.git`
+- 默认更新方式：
+  - `qwen extensions update zc-toolkit`
+
 ## 高频用法
 
 ```bash
 # toolkit
 zc toolkit lint --json
-zc toolkit show build
+zc toolkit show command:start
 zc toolkit search review
 zc toolkit recommend build
 
 # platform
-zc platform generate qwen --plan --json
-zc platform install codex --plan --json
-zc platform install qoder
+zc platform where codex --global --json
 zc platform install codex --global
 zc platform status codex --global --json
+
+zc platform install claude --global
+zc platform install opencode --global
+zc platform install qwen --global
+zc platform status qwen --global --json
+zc platform generate qwen --bundle release-bundle --dir /tmp/zc-toolkit
+zc platform doctor codex --global --json
+zc platform repair qwen --global --json
+zc platform uninstall opencode --global --plan --json
+```
+
+如果你主要是把 `zc` 当安装器使用，最常见的循环是：
+
+```bash
+# 看平台默认安装位置
+zc platform where codex --global --json
+
+# 安装或更新平台内容
+zc platform install codex --global
 zc platform update codex --global --plan --json
-zc platform where qoder --global --json
+
+# 检查当前状态
+zc platform status codex --global --json
+
+# 诊断、修复、卸载
+zc platform doctor codex --global --json
+zc platform repair codex --global --plan --json
+zc platform uninstall codex --global --plan --json
+```
+
+如果你要把 Qwen 扩展作为独立目录导出，而不是直接安装到本机，可以使用：
+
+```bash
+zc platform generate qwen --bundle release-bundle --dir /tmp/zc-toolkit
 ```
 
 ## 设计边界
 
-- `zc` 发现并消费 `packages/toolkit/src/content`，但不拥有 prompt 内容
-- `zc` 调用 `packages/platform-*` 完成平台产物生成和安装
-- `zc` 不承载仓库内 upstream 治理命令
-- `zc` 的公开命令面只保留实际产品能力，不保留历史重复入口
-- 公开发布时只发布 `@zmice/zc`；内部 `toolkit/platform-*` 能力会随 `zc` 一起打包
+- `command:start` 和 `command:product-analysis` 目前是 toolkit 内容入口，不是 CLI 子命令
+- `sdd-tdd` 在内容层里属于 `full-delivery` workflow，而不是统一任务分诊入口
+- `zc` 只承载已经落地的产品命令，不把内容层 canonical command 直接暴露成 CLI
 
-## 开发者入口
+## 开发
+
+常改位置：
 
-如果你要修改 `zc` 本身，优先看：
 - `apps/cli/src/cli/`
 - `apps/cli/src/runtime/`
 - `apps/cli/src/team/`
+- `apps/cli/src/utils/`
 
-尤其常改的命令文件：
-- `apps/cli/src/cli/index.ts`
-- `apps/cli/src/cli/toolkit.ts`
-- `apps/cli/src/cli/platform.ts`
-- `apps/cli/src/cli/team.ts`
-- `apps/cli/src/cli/run.ts`
-
-## 开发与验证
+## 验证
 
 ```bash
 pnpm --dir apps/cli test
 pnpm --dir apps/cli build
 pnpm --dir apps/cli verify
 ```
+
+更完整的使用说明见：
+
+- [../../docs/usage-guide.md](../../docs/usage-guide.md)