@mortiseai/stem 0.0.1

package/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Support. While redistributing the Work or
+      Derivative Works thereof, You may choose to offer, and charge a
+      fee for, acceptance of support, warranty, indemnity, or other
+      liability obligations and/or rights consistent with this License.
+      However, in accepting such obligations, You may act only on Your
+      own behalf and on Your sole responsibility, not on behalf of any
+      other Contributor, and only if You agree to indemnify, defend,
+      and hold each Contributor harmless for any liability incurred by,
+      or claims asserted against, such Contributor by reason of your
+      accepting any such warranty or support.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2025 MortiseAI
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,328 @@
+# @mortiseai/stem
+
+> **Stem** — MortiseAI 构建的 Self-Evolving AI Agent,基于 **MSCE**(MSC Engine)的自我进化智能体
+
+核心三种业务模式(详见[「业务模式」](#业务模式--agent----coding----fde)):
+
+- **Agent 模式** — 面向通用智能体形态,默认模式,当前唯一开放。启动:`stem` / `stem --agent`;核心能力:业务图谱记忆
+- **Coding 模式** — 面向编码工作流的形态(暂未开放)。启动:`stem --coding`;核心能力:业务图谱记忆,基于 MortiseAI Spec Code Engine 编码
+- **FDE 模式** — 面向企业交付场景的形态(暂未开放)。启动:`stem --fde`;核心能力:业务图谱记忆,私有图谱记忆,基于 MortiseAI Spec Code Engine 编码
+
+---
+
+## 项目状态
+
+**Phase 0 · 脚手架骨架**(当前阶段)
+- ✅ 项目结构、构建链、NPM 发布配置就绪
+- ✅ `stem` 可直接启动,终端渲染 Welcome 屏
+- ⬜ MSC Engine 集成(Phase 1+)
+- ⬜ Claude API / 工具 / 命令 / 远程 / 多 Agent(Phase 1-5)
+
+架构设计与完整路线图见 [`ARCHITECTURE.md`](./ARCHITECTURE.md)。
+
+---
+
+## 快速开始
+
+### 前置依赖
+- Node.js >= 22
+- Bun https://bun.sh/ 开发模式 & 构建需要
+
+### npm 安装(发布后)
+```bash
+npm install -g @mortiseai/stem
+stem
+```
+macOS / Linux / Windows 均可,仅需 Node >= 22,无需 bun。
+
+### 开发模式
+```bash
+bun install
+bun run dev                  # bun 直跑源码
+STEM_DEV=1 ./bin/stem.mjs    # 等效:强制启动器走源码(忽略已构建的 dist)
+```
+
+### 构建并运行
+```bash
+bun run build
+./dist/cli.mjs
+# 或通过 Node 启动器(自动选 dist,并加载仓库根 .env)
+./bin/stem.mjs
+```
+
+### 退出
+在 Welcome 屏按 **q** · **Esc** · 或 **Ctrl+C**。
+
+---
+
+## 启动方式与命令行参数
+
+### 常用启动示例
+
+```bash
+stem                                    # 默认:agent 模式 · llms.json default 模型 · 系统语言
+stem --lang en                          # 英文界面
+stem --model BaiLian:glm-5.2            # 会话默认模型(platform:model 完整引用)
+stem --model glm-5.2                    # 裸模型 id(目录唯一命中,否则落默认平台)
+stem --lang ja --model BaiLian:glm-5.2  # 组合使用
+stem --resume <sessionId>               # 恢复历史会话(续写同一份会话日志)
+echo "一句话问答" | stem --bare          # SIMPLE 模式:stdin → 单次回答(non-TTY)
+```
+
+### 运行形态总览
+
+| 形态 | 启动方式 | 说明 |
+|---|---|---|
+| TUI 交互(默认) | `stem` | Welcome + Repl 全功能终端界面 |
+| SIMPLE | `stem --bare` | TTY 下裸 prompt 简化 REPL;non-TTY + stdin pipe 走单次问答链路 |
+| 无头(SDK 桥) | `stem --sdk-url ws://…` | 不渲染 TUI,WebSocket NDJSON 全双工驱动,见下节 |
+| WS telemetry tap | `stem --telemetry-url ws://…` | TUI 正常交互,遥测帧单向推给外部 WS 观察端,见下节 |
+| MCP stdio server | `./dist/mcp.mjs` | 把 stem 工具集暴露为 MCP server(stdio JSON-RPC),供其他 LLM 客户端接入 |
+| 后台 daemon | `./dist/daemon.mjs [run\|status]` | 无 UI 常驻容器;`status` 输出一行 JSON 状态;SIGTERM/SIGINT 优雅退出 |
+
+MCP / daemon 是独立构建产物(`bun run build:mcp` / `bun run build:daemon`),与 TUI 共用同一 MSC 容器逻辑。
+
+### 无头模式(headless SDK 桥)· `--sdk-url`
+
+被 sidecar server(FastAPI / desktop server 等)spawn,协议为 **WebSocket 上的 NDJSON**(每帧单行 JSON),与 Claude Code SDK stream-json 消息同构;内部与 TUI 走完全相同的 MSC agent loop:
+
+```bash
+stem --sdk-url ws://127.0.0.1:8123/ws/<sid>                  # headless 全双工
+stem --sdk-url ws://127.0.0.1:8123/ws/<sid> --sdk-telemetry  # 追加 telemetry 观测帧(默认关)
+```
+
+- 下行帧:`system`(init:model / tools / slash_commands / workflows / permissionMode)、`stream_event`(Anthropic streaming 同构)、`result`、`control_request`(权限卡)、`command_result` / `workflow_result` / `telemetry_event`
+- 上行帧:`user`(消息,入队串行)、`control_request`(interrupt / set_permission_mode)、`control_response`(权限裁决)、`command`(slash 命令)、`workflow`(直接触发 workflow,不经 LLM)
+- 会话生命周期 = 连接生命周期:ws 断开 → 容器销毁 + `exit 0`
+- `--sdk-telemetry`(或 env `STEM_TELEMETRY=1`)开启八源观测帧(tool/hook/mcp/subagent/workflow/skill/command/plugin)
+
+人工驱动与协议细节:`bun scripts/ws-manual-server.ts --spawn`(交互式驱动器)· 协议文档 [`docs/sdk-telemetry-protocol.md`](./docs/sdk-telemetry-protocol.md) · 全量测试手册 [`stem_cli_test/ws/Stem-WS.md`](./stem_cli_test/ws/Stem-WS.md)。
+
+### WebSocket telemetry tap · `--telemetry-url`
+
+与无头模式不同,tap 是 **TUI 共存**的单向观测通道:TUI 正常渲染交互,telemetry 帧单向推给外部 WS 观察端;忽略一切下行帧,断开只记日志、不影响 TUI、不重连。env `STEM_TELEMETRY_WS` 兜底。
+
+```bash
+stem --telemetry-url ws://127.0.0.1:8123/ws/manual
+```
+
+### 语言 · `--lang`
+
+`--lang <zh|en|ja|ko>`(或 `--lang=zh`)。缺省时按优先级回退:
+
+1. `--lang` flag
+2. env `STEM_DEF_LANGUAGE`(shell export 或 `.mstem/settings.local.json` 的 `env` 段,见「运行时开关」)
+3. POSIX env `LC_ALL` / `LC_MESSAGES` / `LANG`(前缀匹配)
+4. 默认 `zh`
+
+### 模型 · `--model`
+
+`--model <ref>`(或 `--model=<ref>`)设置**会话级默认模型**,不落盘:
+
+- ref 形式:`platform:model`(如 `BaiLian:glm-5.2`,平台名做存在性校验,打错立即报错退出并列出已知平台)或裸模型 id(目录唯一命中,否则落默认平台,不做白名单)
+- 平台与模型目录来自 `.mstem/llms.json`(见下节)
+- 解析优先级:`/fast` 开启 > **`--model` 启动参数** > `/model` 会话内持久设置 > env `STEM_DEF_LLM_MODEL` > `llms.json` `default` > 首平台首模型
+- 会话内用 `/model` 显式切换/重置会覆盖启动参数;`/model current` 可查看当前模型与来源
+
+### 模型目录 · `.mstem/llms.json`
+
+多平台 LLM 目录,搜索顺序:`$STEM_LLMS_PATH` → `<cwd>/.mstem/llms.json` → `~/.mstem/llms.json`。
+
+- `protocol`:`anthropic`(`/v1/messages`)或 `openai`(`/chat/completions`)
+- `apiKeyEnv`:密钥所在 env 变量名,缺省 `STEM_LLM_<平台大写>_API_KEY`;也可写 `apiKey` 字段(值为全大写下划线视为 env 变量名,否则视为密钥字面量)
+- `authHeader`:缺省 anthropic → `x-api-key`、openai → `bearer`
+- `context`:支持 `'200k'` / `'1M'` / 数字;`pricing` 单位 USD/1M tokens(供 `/cost` 分账)
+- `vision`:该模型是否支持图片理解(布尔);未声明视为能力未知
+- `default`:全局默认模型;`roles.fast`:`/fast` 快速模式用的模型
+
+完整示例:
+
+```json
+{
+  "platforms": {
+    "anthropic": {
+      "protocol": "anthropic",
+      "baseUrl": "https://api.anthropic.com",
+      "apiKeyEnv": "STEM_LLM_ANTHROPIC_API_KEY",
+      "models": {
+        "claude-sonnet-4-6": { "context": "200k" },
+        "claude-haiku-4-5": { "context": "200k" }
+      }
+    },
+    "bailian": {
+      "protocol": "anthropic",
+      "baseUrl": "https://token-plan.cn-beijing.maas.aliyuncs.com/apps/anthropic",
+      "apiKeyEnv": "STEM_LLM_BAILIAN_API_KEY",
+      "authHeader": "bearer",
+      "models": {
+        "qwen3.8-max-preview": {
+          "context": "1M",
+          "vision": true,
+          "pricing": { "input": 1.3, "output": 7.8, "cacheRead": 0.26, "cacheWrite": 0 }
+        }
+      }
+    },
+    "minimax": {
+      "protocol": "anthropic",
+      "baseUrl": "https://api.minimax.io/anthropic",
+      "apiKeyEnv": "STEM_LLM_MINIMAX_API_KEY",
+      "authHeader": "bearer",
+      "models": {
+        "MiniMax-M2.7": { "context": "200k" },
+        "MiniMax-M2.7-highspeed": { "context": "200k" }
+      }
+    },
+    "deepseek": {
+      "protocol": "openai",
+      "baseUrl": "https://api.deepseek.com",
+      "apiKeyEnv": "STEM_LLM_DEEPSEEK_API_KEY",
+      "models": {
+        "deepseek-chat": { "context": "128k" }
+      }
+    }
+  },
+  "default": "bailian:qwen3.8-max-preview",
+  "roles": {
+    "fast": "minimax:MiniMax-M2.7-highspeed"
+  }
+}
+```
+
+### 业务模式 · `--agent` / `--coding` / `--fde`
+
+Stem 的三种核心业务模式:
+
+| 模式 | 启动命令 | 状态 | 说明 | 核心能力 |
+|---|---|---|---|---|
+| Agent | `stem` / `stem --agent` | ✅ 开放(默认) | 面向通用智能体形态 | 业务图谱记忆 |
+| Coding | `stem --coding` | ⬜ 暂未开放 | 面向编码工作流的形态 | 业务图谱记忆 · 基于 MortiseAI Spec Code Engine 编码 |
+| FDE | `stem --fde` | ⬜ 暂未开放 | 面向企业交付场景的形态 | 业务图谱记忆 · 私有图谱记忆 · 基于 MortiseAI Spec Code Engine 编码 |
+
+三选一布尔开关,缺省回退 env `STEM_DEF_MODE`,默认 `agent`。显式请求 `--coding` / `--fde` 会拒绝启动并提示(不做静默回退)。
+
+### 会话 · `--resume`
+
+`--resume <id>` / `-r <id>` / `--resume=<id>`:恢复指定会话(退出提示里有 `--resume <id>` 可直接复制),复用原会话日志文件续写。
+
+### 图片粘贴 · 图文混合理解(macOS)
+
+对齐 Claude Code:剪贴板里有图片(如 Cmd+Shift+Ctrl+4 截图)时按 **Ctrl+V**,输入框插入 `[Image #N]` 占位;提交后文本与图片按占位位置交错组成混合消息发给模型。模型也可以直接 `Read` 图片文件(png/jpg/gif/webp)"看到"内容。
+
+- 依赖模型能力位:`llms.json` 模型条目的 `vision` 字段。`vision: false` 的模型粘贴时直接拦截提示;粘贴后切到不支持的模型,发送前自动剥离图片并提示「已省略 N 张图片」。
+- 剪贴板读取优先用 `pngpaste`(brew 可选安装,更快),否则走系统 `osascript` — 首次调用可能弹 macOS 自动化权限框,拒绝后图片粘贴不可用(等同剪贴板无图)。
+- 超限图片(>5MB 或长边 >8000px)自动用系统 `sips` 缩放到长边 1568px。
+- 已知限制:`--resume` 恢复的历史会话中图片不回灌,模型只见 `[Image #N]` 字面。
+
+### 其他参数
+
+| 参数 | 说明 |
+|---|---|
+| `--bare` | SIMPLE 模式(见「运行形态总览」) |
+| `--plugin-dir <dir>` | 会话级插件根,可重复传入(相对路径按真实调用目录解析) |
+| `--sdk-url` / `--sdk-telemetry` / `--telemetry-url` | 无头 SDK 桥 / 观测帧 / TUI tap(见上文两节) |
+| `--worktree`/`-w` + `--tmux` | git worktree + tmux 并排会话(需 git 仓库) |
+| `--update` / `--upgrade` | 自更新 |
+| `--version`/`-v` · `--help`/`-h` | 版本 / 完整参数帮助 |
+
+完整参数清单以 `stem --help` 输出为准。
+
+### 运行时开关 · `.mstem/settings.local.json` 的 `env` 段
+
+CLI 的全部运行时开关统一放 settings 级联的 **`env` 段**(不再使用 `.env`):
+入口启动时把 `env` 对象逐 key 注入 `process.env`,**仅补缺不覆盖** — shell
+显式 `export` 的同名变量仍最优先(CI/测试钩子用,如 `STEM_LLMS_PATH` /
+`STEM_SETTINGS_PATH`)。
+
+层级(高层同 key 覆盖低层):
+
+1. `<cwd>/.mstem/settings.local.json` — 个人项目级(应 gitignore)
+2. `<cwd>/.mstem/settings.json` — 团队项目级(随仓库提交)
+3. `~/.mstem.json` — 用户全局
+
+示例 `.mstem/settings.local.json`:
+
+```json
+{
+  "env": {
+    "STEM_DEF_LANGUAGE": "zh",
+    "STEM_API_RETRY_INTERVAL_MS": "3000",
+    "STEM_DEBUG": "1",
+    "STEM_LOOP_CRON_ENABLED": "1"
+  }
+}
+```
+
+常用开关一览(全部可放 `env` 段,也可 shell export 临时覆盖):
+
+| 变量 | 作用 |
+|---|---|
+| `STEM_DEF_LANGUAGE` | 界面语言 `zh\|en\|ja\|ko`(`--lang` 的兜底) |
+| `STEM_DEF_MODE` | 业务模式(`--agent` 等的兜底) |
+| `STEM_DEF_LLM_MODEL` | 模型引用(优先级低于 `--model` 与 `/model`) |
+| `STEM_DEBUG` | `1` = 渲染 tool-use/tool-result 调试卡片 + Debug banner |
+| `STEM_API_RETRY_INTERVAL_MS` | LLM 网络错误重试间隔(默认 60000,最多 10 次) |
+| `STEM_API_TIMEOUT_MS` | LLM 请求全局超时(平台未配 `timeoutMs` 时生效,默认 600000) |
+| `STEM_PERMISSION_MODE` | 工具权限模式 `default\|allow\|plan\|bypassPermissions\|...` |
+| `STEM_LOOP_CRON_ENABLED` | `1` = 开启 `/loop` 后台 cron(默认关,opt-in 安全门) |
+| `STEM_HUD_SHOW_USAGE` / `STEM_HUD_SHOW_WEEK` | HUD 用量行 / 本周行显示开关 |
+| `STEM_WEBSEARCH_ENABLED` / `STEM_WEBSEARCH_PROVIDER` | web_search 总开关 / provider(`auto\|duckduckgo\|brave-web`) |
+| `STEM_TELEMETRY` | `1` = 无头模式开启 telemetry 观测帧(`--sdk-telemetry` 的 env 形式) |
+| `STEM_TELEMETRY_WS` | telemetry WS tap 地址 |
+
+---
+
+## 发布到 NPM
+
+```bash
+bun run build           # 生成 dist/cli.mjs
+npm pack                # 本地产出 tarball,检查清单
+# → tar -tf *.tgz 应含 bin/ dist/ preload.ts README.md LICENSE
+
+npm publish --access public    # 实际发布
+```
+
+`prepublishOnly` 会在发布前自动触发一次 `bun run build`。
+
+---
+
+## 目录结构速览
+
+```
+mortise_ai_cli_project/
+├── bin/stem.mjs          # Node 跨平台启动器(对标 mai-cc-cli/bin/mai-cli)
+├── src/
+│   ├── entry/               # CLI / MCP / Daemon 入口
+│   ├── ui/                  # Phase 0 纯 Ink 组件(Welcome/Logo)
+│   ├── msc-base/            # MSC Engine CLI 侧基建(Phase 1+ 填充)
+│   ├── msc-core/            # 跨模块通用能力
+│   └── msc-project/         # 业务 Module 骨架(shell/core-engine/tools/services/commands/remote/swarm/extension/daemon/boot)
+├── scripts/build-cli.ts
+├── preload.ts
+├── bunfig.toml
+├── tsconfig.json
+├── package.json
+├── LICENSE                  # Apache-2.0
+└── ARCHITECTURE.md          # ★ mai-cc-cli → MSC Module 完整映射
+```
+
+详细设计见 [ARCHITECTURE.md](./ARCHITECTURE.md)。
+
+---
+
+## 技术栈
+
+| 维度 | 选择 |
+|---|---|
+| 语言 | TypeScript 5(严格模式 + 装饰器) |
+| 开发运行时 | Bun |
+| 发行格式 | ESM 单文件 bundle,Node >= 22 |
+| UI | Ink 6 + React 19 |
+| 架构引擎 | `@mortiseai/mai_msc_engine_ts_module@^0.0.3` |
+| 许可证 | Apache-2.0 |
+
+---
+
+## 开发约定
+
+见 [`AGENTS.md`](./AGENTS.md) 和 [`ARCHITECTURE.md`](./ARCHITECTURE.md) 的「开发约定」章节。
+

package/bin/stem.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+// 跨平台启动器(macOS / Linux / Windows):npm 全局安装经 cmd-shim / 软链均可调用。
+// 语义对齐旧 bin/stem bash 版:CALLER_DIR 透传、.env 仅补缺不覆盖、STEM_DEV 走 bun 源码。
+import { existsSync, realpathSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { devNull } from 'node:os'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { spawnSync } from 'node:child_process'
+
+// realpath:npm link / 全局 bin 软链下定位真实包根,而非软链父目录。
+const selfPath = realpathSync(fileURLToPath(import.meta.url))
+const rootDir = dirname(dirname(selfPath))
+
+process.env.CALLER_DIR ||= process.cwd()
+
+const envFile = join(rootDir, '.env')
+const skipDotenv = process.env.STEM_SKIP_DOTENV === '1'
+// loadEnvFile 与 node --env-file 同语义:已有环境变量优先,仅补缺。
+if (!skipDotenv && existsSync(envFile)) {
+  process.loadEnvFile(envFile)
+}
+
+const distEntry = join(rootDir, 'dist', 'cli.mjs')
+if (process.env.STEM_DEV !== '1' && existsSync(distEntry)) {
+  await import(pathToFileURL(distEntry).href)
+} else {
+  // dev 模式:bun 直跑源码。bun 会自动加载 cwd 下的 .env,跳过时显式指向空设备。
+  const envFlag = skipDotenv
+    ? [`--env-file=${devNull}`]
+    : existsSync(envFile)
+      ? ['--env-file=.env']
+      : []
+  const result = spawnSync(
+    'bun',
+    [...envFlag, './src/stem-entry/stem-entry-cli.tsx', ...process.argv.slice(2)],
+    { cwd: rootDir, stdio: 'inherit' },
+  )
+  if (result.error && result.error.code === 'ENOENT') {
+    // i18n: 启动器双语(CLI 还没起来,无法走 JS catalog)
+    const locale = (process.env.STEM_LOCALE ?? process.env.LANG ?? 'zh').toLowerCase()
+    console.error(
+      locale.startsWith('en')
+        ? "stem: dist/cli.mjs not found and 'bun' is not on PATH.\n" +
+          "Run 'bun run build' in the repo, or install bun (https://bun.sh) to use dev mode."
+        : 'stem: 未找到 dist/cli.mjs,且 PATH 中没有 \'bun\'。\n' +
+          "请在仓库根目录执行 'bun run build',或安装 bun (https://bun.sh) 以使用 dev 模式。",
+    )
+    process.exit(1)
+  }
+  process.exit(result.status ?? 1)
+}