msdevflow 0.7.4 → 0.7.6

package/README.md

@@ -1,6 +1,6 @@
 # msdevflow
 
-`msdevflow` 是一个用于 GitCode 的 Agent Skill，可以把已授权的 Issue 安全推进到代码实现、普通 PR、CI、检视意见闭环和最终合入，也可以通过显式 `action` 只执行其中一个能力。正式支持 Claude Code、Codex 和 OpenCode；Trae 的 Skills 安装与兼容机制尚未完成可靠验证，因此当前不宣称支持。
+`msdevflow` npm 包提供一套 GitCode Agent Skills：`msd` 核心可以把已授权的 Issue 安全推进到代码实现、普通 PR、CI、检视意见闭环和最终合入，十个 `msd-<action>` 薄路由入口用于在输入阶段发现并运行单项能力。正式支持 Claude Code、Codex 和 OpenCode；Trae 的 Skills 安装与兼容机制尚未完成可靠验证，因此当前不宣称支持。
 
 ## 安装
 
@@ -9,7 +9,7 @@
 - Claude Code、Codex 或 OpenCode 中至少一个；
 - Node.js `>=18` 和 npm；
 - Git；
-- Python `>=3.10` 和 pip；
+- Python `>=3.10`，且标准库 `venv` 模块可用；
 - GitCode 账号；
 - Chrome 或 Edge（推荐，用于 openLiBing OAuth）。
 
@@ -29,9 +29,9 @@ npx msdevflow@latest setup
 
 `setup` 默认检测 PATH 中的 Claude Code、Codex 和 OpenCode，展示完整计划并在确认后：
 
-1. 把同一份 `msdevflow` skill 原子安装或更新到所需目标；
+1. 把一个 `msd` 核心和十个 `msd-<action>` 路由器作为整套事务原子安装或更新到所需目标；
 2. 安装或升级官方 `@gitcode-cli/cli@latest`；
-3. 安装受审的 Python Playwright 依赖；
+3. 创建或修复 msdevflow 受管 Python venv，并在其中安装受审的 Playwright 依赖；
 4. 验收 Issue、PR、结构化评论、行内评论、JSON、显式仓库和正文文件等 CLI 能力；
 5. GitCode CLI 未认证时打开官方 Token 创建页面，并让 CLI 自己的终端提示接收 Token。
 
@@ -47,15 +47,17 @@ npx msdevflow setup --dry-run --targets all
 安装目录映射：
 
 ```text
-Claude Code                 -> ~/.claude/skills/msdevflow
-Codex                       -> ~/.agents/skills/msdevflow
-仅 OpenCode                 -> ~/.agents/skills/msdevflow
-OpenCode + Claude Code      -> 复用 ~/.claude/skills/msdevflow
-OpenCode + Codex            -> 复用 ~/.agents/skills/msdevflow
-Claude Code + Codex         -> 两个受管副本
-三者同时安装                -> 两个受管副本，并提示 OpenCode 可从两处发现同名 skill
+Claude Code                 -> ~/.claude/skills/{msd,msd-*}
+Codex                       -> ~/.agents/skills/{msd,msd-*}
+仅 OpenCode                 -> ~/.agents/skills/{msd,msd-*}
+OpenCode + Claude Code      -> 复用 Claude 目标
+OpenCode + Codex            -> 复用 Agent Skills 目标
+Claude Code + Codex         -> 两套受管副本
+三者同时安装                -> 两套受管副本，并提示 OpenCode 双路径发现
 ```
 
+每个物理目标都包含完整套件，薄路由器不复制核心业务规则。已有 entry 只有在 manifest 精确匹配自身名称时才允许更新；由旧版包管理的 `msdevflow` 目录会在新套件全部验证后安全迁移，来源不明的目录、文件或符号链接会阻断安装。
+
 自定义目录：
 
 ```bash
@@ -65,29 +67,24 @@ npx msdevflow setup --agents-skills-dir "<shared-agent-skills-directory>"
 
 `--skills-dir` 未配合 `--targets` 使用时保留旧语义，只安装 Claude Code 目标。没有检测到客户端时，交互运行会要求选择目标；非交互运行必须提供 `--targets`。安装完成后重启或重新加载对应客户端。如果机器已有 Python 版本的 `gitcode`，setup 会保留它，并为 npm CLI 创建 `gitcode-npm` 命令；否则使用 `gitcode`。
 
-## 运行与 action 菜单
+setup 在所有平台使用独立受管 venv，不向系统 Python 安装包：
 
-从目标仓库目录启动客户端并提交 `msdevflow`：
+```text
+Windows:     %LOCALAPPDATA%\msdevflow\python
+macOS/Linux: ${XDG_DATA_HOME:-$HOME/.local/share}/msdevflow/python
+```
 
-- Claude Code：输入并提交 `/msdevflow`；
-- Codex：使用 `$msdevflow` 或从 `/skills` 选择后提交；
-- OpenCode：打开 `/skills`，选择 `msdevflow`，再提交插入的 `/msdevflow`。`@` 用于文件、reference 或 agent，不用于选择 Skill。
+可用 `MSDEVFLOW_PYTHON_DIR` 覆盖，值必须是绝对路径或以 `~` 开头；setup 与后续 action 必须使用同一配置。`venv` 属于 CPython 标准库，但精简发行版可能未安装；Debian/Ubuntu 通常需要用户自行安装 `python3-venv`。setup 不执行 sudo，不回退到全局 pip，也不使用 `--break-system-packages`。Windows 官方 Python 和 Homebrew Python 通常已包含 `venv`。
 
-没有字面量 `action=<name>` 时，Agent 会先通过宿主原生单选工具显示分级菜单，选择前不会探测仓库或访问 GitCode：
+## 运行与 action 补全
 
-```text
-选择运行方式
-├─ 完整端到端流程
-├─ 作者工作流
-│  ├─ Issue 管理 -> discover | create-issue | issue
-│  ├─ 开发与交付 -> develop | pr | ci
-│  └─ PR 后续 -> feedback | merge
-└─ 独立工具 -> openlibing-auth | code-review
-```
+从目标仓库目录启动客户端。直接调用核心 `msd` 会运行完整作者 E2E：
 
-Claude Code 使用 `AskUserQuestion`，Codex 使用 `request_user_input`，OpenCode 使用 `question`。每次只显示当前层且不超过 3 项；工具不可用或处于非交互模式时，Agent 只输出当前层编号选项并等待回复，不自行选择默认项。
+- Claude Code：输入并提交 `/msd`；
+- Codex：使用 `$msd` 或从 `/skills` 选择；
+- OpenCode：打开 `/skills`，选择 `msd`，再提交插入的 `/msd`。`@` 用于文件、reference 或 agent，不用于选择 Skill。
 
-选择“完整端到端流程”后，才会运行：
+核心流程为：
 
 ```text
 Issue 发现/核验
@@ -102,9 +99,9 @@ Issue 发现/核验
 -> 远端回读 PR 已 merged
 ```
 
-调用正文可预先提供 Issue/PR URL、仓库路径、canonical、source 和模式；菜单选择后这些参数会保留。即使正文写明“运行完整 E2E”或某个具体任务，只要没有字面量 `action=<name>`，仍从顶层菜单开始。
+调用正文可提供 Issue/PR URL、仓库路径、canonical、source 和模式。核心 `msd` 不显示运行时 Question 菜单。
 
-这是可暂停、可恢复的流程。外部检视或审批有新进展后，可再次提交 `/msdevflow` 和 PR 信息，并在菜单中选择“完整端到端流程”：
+这是可暂停、可恢复的流程。外部检视或审批有新进展后，可再次提交 `/msd` 和 PR 信息：
 
 ```text
 恢复 https://gitcode.com/<canonical-owner>/<repo>/pulls/<number> 的完整作者 E2E。
@@ -116,7 +113,7 @@ source：<your-account>/<repo>
 
 ## 独立 action
 
-显式提供 `action=<name>` 时，只运行该 action，完成后立即停止；前置条件不足时不会隐式补跑上游流程。
+Claude Code/OpenCode 输入 `/msd-`、Codex 输入 `$msd-` 即可筛选十个独立入口。每个入口只运行对应 action，完成后立即停止；前置条件不足时不会隐式补跑上游流程。`/msd action=<name>` 和 `$msd action=<name>` 仍是兼容调用，但参数本身不提供跨客户端枚举补全。
 
 | action | 用途 | 完成状态或结果 |
 |---|---|---|
@@ -134,19 +131,19 @@ source：<your-account>/<repo>
 示例：
 
 ```text
-/msdevflow action=create-issue
+/msd-create-issue
 在 Ascend/example 提一个 bug：升级后首次启动失败……
 使用 guided 模式，确认完整预览后再创建。
 ```
 
 ```text
-/msdevflow action=ci
+/msd-ci
 PR：https://gitcode.com/Ascend/example/pulls/456
 本地仓库：D:\work\example
 ```
 
 ```text
-/msdevflow action=code-review
+/msd-code-review
 PR：https://gitcode.com/Ascend/example/pulls/789
 ```
 
@@ -188,17 +185,19 @@ Agent 写入的 PR/Issue 正文、评论和 discussion 回复末尾会附加：
 
 ## 常见阻塞
 
-### 客户端找不到 `msdevflow`
+### 客户端找不到 `msd` 或 `msd-<action>`
 
-按目标确认至少一个受支持的 manifest 存在，然后重启或重新加载客户端：
+按目标确认核心和相应路由器的 manifest 都存在，然后重启或重新加载客户端：
 
 ```text
-Claude Code: ~/.claude/skills/msdevflow/SKILL.md
-Codex:       ~/.agents/skills/msdevflow/SKILL.md
+Claude Code: ~/.claude/skills/msd/SKILL.md
+             ~/.claude/skills/msd-<action>/SKILL.md
+Codex:       ~/.agents/skills/msd/SKILL.md
+             ~/.agents/skills/msd-<action>/SKILL.md
 OpenCode:    上述任一路径（按 setup 计划）
 ```
 
-可运行 `npx msdevflow setup --dry-run --targets <clients>` 检查目标映射。
+Claude Code/OpenCode 可输入 `/msd-` 筛选 action；Codex 使用 `$msd-`。可运行 `npx msdevflow setup --dry-run --targets <clients>` 检查目标映射。
 
 ### `blocked: bootstrap-required`
 
@@ -229,4 +228,4 @@ npx msdevflow setup
 
 ## 详细文档
 
-完整 action、恢复、模板、CI、review、UTF-8 和安全契约见 [`skill/msdevflow/README.md`](skill/msdevflow/README.md)。
+完整 action、恢复、模板、CI、review、UTF-8 和安全契约见 [`skill/msd/README.md`](skill/msd/README.md)。