@miracleplus/mplus 0.1.3 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miracleplus/mplus",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "奇绩创坛命令行工具（mplus CLI）",
   "keywords": [
     "miracleplus",
@@ -12,15 +12,20 @@
     "mplus": "./bin/mplus.js"
   },
   "main": "./dist/index.js",
+  "readme": "README.npm.md",
   "files": [
     "dist",
-    "bin"
+    "bin",
+    "skills",
+    "scripts/postinstall-skills.js",
+    "README.npm.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json && node scripts/postbuild.js",
     "build:dev": "tsc && node scripts/postbuild.js",
     "obfuscate": "node scripts/obfuscate.js",
     "prepublishOnly": "npm run clean && npm run build && npm run obfuscate",
+    "postinstall": "node scripts/postinstall-skills.js",
     "dev": "tsc --watch",
     "start": "node dist/index.js",
     "clean": "rm -rf dist"

package/scripts/postinstall-skills.js

@@ -0,0 +1,49 @@
+/**
+ * postinstall hook — 自动将 skills 安装到 ~/.agents/skills/
+ * npm install -g @miracleplus/mplus 时自动执行
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const skillsSource = path.resolve(__dirname, '..', 'skills');
+const skillsTarget = path.join(os.homedir(), '.agents', 'skills');
+
+function copyDirSync(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDirSync(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+// 静默执行：失败不阻塞安装
+try {
+  if (!fs.existsSync(skillsSource)) {
+    // 开发环境或 skills 目录未打包，跳过
+    process.exit(0);
+  }
+
+  const skillDirs = fs.readdirSync(skillsSource, { withFileTypes: true })
+    .filter((d) => d.isDirectory());
+
+  if (skillDirs.length === 0) {
+    process.exit(0);
+  }
+
+  for (const dir of skillDirs) {
+    copyDirSync(path.join(skillsSource, dir.name), path.join(skillsTarget, dir.name));
+  }
+
+  console.log(`mplus: ✓ ${skillDirs.length} AI skills installed to ${skillsTarget}`);
+} catch (err) {
+  // 静默失败，不阻塞 npm install
+  // 用户可以后续手动执行 mplus install-skills
+}

package/skills/mplus-admission/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: mplus-admission
+version: 0.1.0
+description: "奇绩创坛 Admission 数据查询：查询创业项目（startup_projects）的申请材料和面试材料，支持按批次、补充材料等条件过滤。当用户需要查看、搜索、分析创业项目申请数据时使用。"
+metadata:
+  requires:
+    bins: ["mplus"]
+---
+
+# admission
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../mplus-shared/SKILL.md`](../mplus-shared/SKILL.md)，其中包含认证、错误处理等共享知识**
+
+## 核心概念
+
+- **startup_project**: 创业项目记录，包含申请材料（application_content）和面试材料（interview_content）
+- **batch**: 加速营批次，每期一个批次名（如 "S24"、"W25"）
+- **addition**: 补充材料标记，表示该记录是否为补充提交的材料
+
+## 资源关系
+
+```
+Batch (batch_name)
+└── StartupProject (project_id)
+    ├── application_content (申请材料，可能为 null)
+    ├── interview_content (面试材料，可能为 null)
+    └── addition (是否补充材料)
+```
+
+## 认证要求
+
+admission 命令使用 OAuth 认证（非 API Key），需要先执行 `mplus login` 完成授权。
+
+支持 `--session` 参数切换不同的 OAuth session。
+
+## 命令速查
+
+| 命令 | 说明 | 参考文档 |
+|------|------|---------|
+| `mplus admission startup-projects list` | 查询项目列表，支持过滤和分页 | [references/admission-startup-projects-list.md](references/admission-startup-projects-list.md) |
+| `mplus admission startup-projects get <id>` | 查询单个项目详情 | [references/admission-startup-projects-get.md](references/admission-startup-projects-get.md) |
+
+## AI 使用建议
+
+1. **先查列表再取详情**：不确定 project_id 时，先用 `list` 命令查找，再用 `get` 获取完整内容
+2. **始终加 `--json`**：需要解析数据时必须使用 JSON 格式，默认文本格式会截断材料内容（只显示长度）
+3. **分页策略**：先不带过滤条件查看 `total`，了解数据规模后再决定是否需要翻页或加过滤条件
+4. **批次过滤**：如果用户提到具体批次（如 "S24 的项目"），使用 `--batch-name` 过滤
+5. **补充材料**：`--addition true` 只返回补充提交的记录，`--addition false` 只返回初始提交

package/skills/mplus-admission/references/admission-startup-projects-get.md

@@ -0,0 +1,91 @@
+# admission startup-projects get
+
+> **前置条件：** 先用 Read 工具读取 [`../mplus-shared/SKILL.md`](../../mplus-shared/SKILL.md) 了解认证和全局参数。
+
+查询单个 startup_project 的详细信息。
+
+对应命令：`mplus admission startup-projects get <project_id>`（内部调用 `GET /admission/api/v1/startup-projects/:project_id`，通过 API Gateway）。
+
+## 命令示例
+
+```bash
+# 查询单个项目（默认只看初始提交）
+mplus admission startup-projects get proj_abc123
+
+# JSON 格式输出（AI Agent 推荐）
+mplus admission startup-projects get proj_abc123 --json
+
+# 查看补充材料版本
+mplus admission startup-projects get proj_abc123 --addition true --json
+
+# 使用指定 OAuth session
+mplus admission startup-projects get proj_abc123 --session work --json
+```
+
+## 参数
+
+| 参数 | 必填 | 类型 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `<project_id>` | **是** | string (位置参数) | — | 项目唯一标识 |
+| `--addition <bool>` | 否 | string | `"false"` | 是否查看补充材料版本：`true` 返回补充提交，`false` 返回初始提交 |
+| `--session <name>` | 否 | string | `"default"` | OAuth session 名称 |
+| `--json` | 否 | boolean | `false` | 以 JSON 格式输出完整响应 |
+
+> **`--addition` 取值规则**：接受 `true`/`1`/`yes`/`y` 或 `false`/`0`/`no`/`n`（不区分大小写）。其他值会报错。
+
+## 返回字段
+
+### JSON 格式（`--json`）
+
+```json
+{
+  "project_id": "proj_abc123",
+  "batch_name": "S24",
+  "application_content": "完整的申请材料文本...",
+  "interview_content": "完整的面试材料文本...",
+  "addition": false
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `project_id` | string | 项目唯一标识 |
+| `batch_name` | string | 所属批次名 |
+| `application_content` | string \| null | 申请材料全文（可能为 null，表示未提交） |
+| `interview_content` | string \| null | 面试材料全文（可能为 null，表示未提交） |
+| `addition` | boolean | 是否为补充材料 |
+
+### 默认文本格式
+
+```
+项目 ID：proj_abc123
+批次：S24
+补充材料：否
+申请材料长度：3456
+面试材料长度：2100
+```
+
+> 文本格式只显示材料长度，不显示实际内容。需要完整内容必须加 `--json`。
+
+## 常见错误
+
+| 现象 | 原因 | 解决方案 |
+|------|------|---------|
+| `OAuth 鉴权失败，请运行 mplus login 重新登录` | token 过期且刷新失败 | 执行 `mplus login` |
+| `未找到 OAuth session，请先运行 mplus login` | 从未登录 | 执行 `mplus login` |
+| `--addition 只能是 true 或 false` | `--addition` 传了非法值 | 使用 `true`/`false`/`1`/`0`/`yes`/`no` |
+| `资源不存在` | project_id 不存在，或该 addition 状态下无记录 | 确认 project_id 正确；尝试切换 `--addition` 值 |
+| `你没有访问该资源的权限` | 当前用户无 admission 数据权限 | 确认账户权限 |
+
+## AI 使用建议
+
+1. **获取完整材料**：必须加 `--json`，否则只能看到材料长度
+2. **初始 vs 补充材料**：同一个 project_id 可能有两个版本——初始提交（`--addition false`，默认）和补充提交（`--addition true`）。如果用户要看"最新材料"或"补充材料"，记得切换 `--addition`
+3. **project_id 来源**：通常从 `admission startup-projects list` 的结果中获取
+4. **材料为 null**：表示该阶段材料尚未提交，不是错误
+
+## 参考
+
+- [mplus-admission](../SKILL.md) — admission 领域概览
+- [mplus-shared](../../mplus-shared/SKILL.md) — 认证和全局参数
+- [admission-startup-projects-list](admission-startup-projects-list.md) — 查询项目列表

package/skills/mplus-admission/references/admission-startup-projects-list.md

@@ -0,0 +1,150 @@
+# admission startup-projects list
+
+> **前置条件：** 先用 Read 工具读取 [`../mplus-shared/SKILL.md`](../../mplus-shared/SKILL.md) 了解认证和全局参数。
+
+查询 startup_projects 列表，支持按批次、补充材料、项目 ID 过滤，支持分页。
+
+对应命令：`mplus admission startup-projects list`（内部调用 `GET /admission/api/v1/startup-projects`，通过 API Gateway）。
+
+## 命令示例
+
+```bash
+# 查询所有项目（默认第 1 页，每页 20 条）
+mplus admission startup-projects list
+
+# JSON 格式输出（AI Agent 推荐）
+mplus admission startup-projects list --json
+
+# 按批次过滤
+mplus admission startup-projects list --batch-name "S24"
+
+# 只看补充材料
+mplus admission startup-projects list --addition true
+
+# 只看初始提交
+mplus admission startup-projects list --addition false
+
+# 按项目 ID 精确查询
+mplus admission startup-projects list --project-id "proj_abc123"
+
+# 分页：第 2 页，每页 50 条
+mplus admission startup-projects list --page 2 --page-size 50
+
+# 组合过滤 + 分页 + JSON
+mplus admission startup-projects list --batch-name "W25" --addition false --page 1 --page-size 10 --json
+
+# 使用指定 OAuth session
+mplus admission startup-projects list --session work --json
+```
+
+## 参数
+
+| 参数 | 必填 | 类型 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `--batch-name <name>` | 否 | string | — | 按批次名过滤（精确匹配，如 `"S24"`、`"W25"`） |
+| `--addition <bool>` | 否 | string | — | 按补充材料过滤：`true` 只返回补充提交，`false` 只返回初始提交 |
+| `--project-id <id>` | 否 | string | — | 按 project_id 精确过滤 |
+| `--page <number>` | 否 | string | `"1"` | 页码，从 1 开始 |
+| `--page-size <number>` | 否 | string | `"20"` | 每页数量 |
+| `--session <name>` | 否 | string | `"default"` | OAuth session 名称 |
+| `--json` | 否 | boolean | `false` | 以 JSON 格式输出完整响应 |
+
+> **`--addition` 取值规则**：接受 `true`/`1`/`yes`/`y` 或 `false`/`0`/`no`/`n`（不区分大小写）。其他值会报错。
+
+## 返回字段
+
+### JSON 格式（`--json`）
+
+```json
+{
+  "total": 156,
+  "page": 1,
+  "page_size": 20,
+  "items": [
+    {
+      "project_id": "proj_abc123",
+      "batch_name": "S24",
+      "application_content": "完整的申请材料文本...",
+      "interview_content": "完整的面试材料文本...",
+      "addition": false
+    }
+  ]
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `total` | number | 符合条件的总记录数 |
+| `page` | number | 当前页码 |
+| `page_size` | number | 每页数量 |
+| `items` | array | 项目列表 |
+| `items[].project_id` | string | 项目唯一标识 |
+| `items[].batch_name` | string | 所属批次名 |
+| `items[].application_content` | string \| null | 申请材料全文（可能为 null） |
+| `items[].interview_content` | string \| null | 面试材料全文（可能为 null） |
+| `items[].addition` | boolean | 是否为补充材料 |
+
+### 默认文本格式
+
+文本格式只显示摘要信息（材料长度而非全文）：
+
+```
+共 156 条，当前第 1 页，每页 20 条
+
+项目 ID：proj_abc123
+批次：S24
+补充材料：否
+申请材料长度：3456
+面试材料长度：2100
+
+项目 ID：proj_def456
+批次：S24
+补充材料：是
+申请材料长度：0
+面试材料长度：1800
+```
+
+## 分页
+
+服务端分页，通过 `--page` 和 `--page-size` 控制：
+
+- `total` 表示符合过滤条件的总记录数
+- 总页数 = `Math.ceil(total / page_size)`
+- 翻页：递增 `--page` 值
+
+```bash
+# 第 1 页
+mplus admission startup-projects list --json --page 1 --page-size 20
+
+# 第 2 页
+mplus admission startup-projects list --json --page 2 --page-size 20
+
+# 第 3 页
+mplus admission startup-projects list --json --page 3 --page-size 20
+```
+
+**判断是否还有下一页**：当 `page * page_size < total` 时，还有更多数据。
+
+## 常见错误
+
+| 现象 | 原因 | 解决方案 |
+|------|------|---------|
+| `OAuth 鉴权失败，请运行 mplus login 重新登录` | token 过期且刷新失败 | 执行 `mplus login` |
+| `未找到 OAuth session，请先运行 mplus login` | 从未登录 | 执行 `mplus login` |
+| `--addition 只能是 true 或 false` | `--addition` 传了非法值 | 使用 `true`/`false`/`1`/`0`/`yes`/`no` |
+| `你没有访问该资源的权限` | 当前用户无 admission 数据权限 | 确认账户权限 |
+| `资源不存在` | API 路径错误或服务未部署 | 检查 API Gateway 状态 |
+
+## AI 使用建议
+
+1. **获取完整材料内容**：必须加 `--json`。默认文本格式只显示材料长度（字符数），不显示实际内容
+2. **大批量数据**：先查一次不带过滤条件看 `total`，再决定分页策略。如果 total 很大，优先加过滤条件缩小范围
+3. **查找特定项目**：如果知道 project_id，直接用 `--project-id` 过滤（或用 `get` 子命令）
+4. **批次名格式**：通常为 `S24`、`W25` 这样的格式（S=Summer, W=Winter + 年份后两位），精确匹配
+5. **材料为 null 的情况**：`application_content` 或 `interview_content` 为 null 表示该阶段材料尚未提交
+
+## 参考
+
+- [mplus-admission](../SKILL.md) — admission 领域概览
+- [mplus-shared](../../mplus-shared/SKILL.md) — 认证和全局参数
+- [admission-startup-projects-get](admission-startup-projects-get.md) — 查询单个项目

package/skills/mplus-shared/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: mplus-shared
+version: 0.1.0
+description: "奇绩创坛 CLI 共享基础：OAuth 登录、session 管理、全局参数、错误处理。当用户首次使用 mplus CLI、需要登录授权、遇到鉴权错误、或切换 session 时触发。"
+metadata:
+  requires:
+    bins: ["mplus"]
+---
+
+# mplus CLI 共享规则
+
+本技能指导你如何通过 mplus CLI 操作奇绩创坛平台资源。
+
+## 认证方式
+
+mplus CLI 的 admission 相关命令使用 **OAuth Authorization Code + PKCE** 认证，通过 API Gateway (`https://api-gateway.miracleplus.com`) 访问后端服务。
+
+### 登录
+
+```bash
+# 默认登录（自动打开浏览器）
+mplus login
+
+# 指定 session 名称（支持多账户）
+mplus login --session work
+
+# 不自动打开浏览器（手动复制链接）
+mplus login --no-open
+```
+
+登录流程：
+1. CLI 启动本地 HTTP 服务器（端口 8765）
+2. 打开浏览器跳转到 MP OAuth 授权页面
+3. 用户在浏览器中完成授权
+4. CLI 自动接收回调，换取 access token
+5. Token 保存到本地 session
+
+### Session 管理
+
+支持多个 OAuth session 并存，通过 `--session` 切换：
+
+```bash
+# 使用默认 session
+mplus admission startup-projects list
+
+# 使用指定 session
+mplus admission startup-projects list --session work
+```
+
+### Token 自动刷新
+
+- access token 过期前 60 秒自动使用 refresh_token 刷新
+- 如果 refresh_token 也失效，需要重新 `mplus login`
+
+## 全局输出格式
+
+所有数据命令支持 `--json` 标志：
+
+| 模式 | 说明 |
+|------|------|
+| 默认 | 人类友好的格式化文本输出 |
+| `--json` | 完整 JSON 响应（2 空格缩进） |
+
+**AI Agent 建议**：需要解析数据时始终使用 `--json`，默认文本格式仅供人类阅读。
+
+## 错误处理
+
+所有错误输出到 stderr，格式为 `错误：<message>`，进程退出码为 1。
+
+| 错误消息 | 原因 | 解决方案 |
+|---------|------|---------|
+| `OAuth 鉴权失败，请运行 mplus login 重新登录` | access token 无效或过期且刷新失败 | 执行 `mplus login` 重新授权 |
+| `未找到 OAuth session，请先运行 mplus login` | 从未登录或 session 不存在 | 执行 `mplus login --session <name>` |
+| `你没有访问该资源的权限` | 当前用户无权限 | 确认账户权限 |
+| `网络错误，无法连接 API Gateway` | 网络不通 | 检查网络连接 |
+| `服务器错误，请稍后重试` | 后端 5xx | 等待后重试 |
+
+## Agent 代理发起登录
+
+当你作为 AI Agent 帮用户登录时：
+
+1. 使用 background 方式执行 `mplus login`（该命令会阻塞等待浏览器回调）
+2. 从输出中提取授权 URL 发给用户
+3. 等待用户在浏览器中完成授权
+4. 命令自动完成，session 已保存
+
+```bash
+# background 执行，提取 URL 给用户
+mplus login --session default
+```
+
+## 安全规则
+
+- **禁止**将 access_token / refresh_token 输出到终端明文
+- 写入/删除操作前确认用户意图
+- 使用 `--json` 获取结构化数据，避免解析文本格式出错