# @ai-partner-x/aiko-studio-cli

Aiko Studio 平台 CLI 工具 — 查询项目类型、配置单元，读取文档内容作为 AI 上下文。

内置 AI Skills，可显式安装到 Cursor、Claude Code、Codex 等 AI agents。

## 安装

```bash
npm install -g @ai-partner-x/aiko-studio-cli
```

需要 Node.js >= 18。

## 快速开始

```bash
# 1. 登录（默认连接生产环境）
studio-cli login

# 2. 安装 AI Skills 到你的 IDE
studio-cli install-skills

# 3. 查看项目文档
studio-cli project-docs list --project-id <id>
```

## 环境

| 环境 | 地址 | 命令 |
|---|---|---|
| production（默认） | https://studio.aiko.geekstorm.com.cn | `studio-cli login` |
| local | http://localhost:8080 | `studio-cli login --env local` |
| 自定义 | 任意 URL | `studio-cli login --api-base <url>` |

## 命令一览

| 命令 | 说明 |
|---|---|
| `login` | 浏览器登录授权 |
| `install-skills` | 安装 AI Skills 到 Cursor / Claude Code / Codex 等 |
| `config` | 配置管理（init / show / reset） |
| `project-types` | 项目类型查询（list / get） |
| `config-units` | 配置单元查询（list / get / full） |
| `project-docs` | 项目文档读取（list / chapters / read） |
| `uuid` | 生成 UUID |
| `schema` | 获取 OpenAPI spec |

## 项目文档读取

```bash
# 列出项目下的文档（含文档类型）
studio-cli project-docs list --project-id <pid>

# 查看文档章节树
studio-cli project-docs chapters --project-id <pid> --doc-id <did>

# 读取文档内容（默认输出 Markdown）
studio-cli project-docs read --project-id <pid> --doc-id <did>

# 读取指定章节
studio-cli project-docs read --project-id <pid> --doc-id <did> --chapter-id <cid>

# 按章节标题读取
studio-cli project-docs read --project-id <pid> --doc-id <did> --chapter-title "1. 产品架构"

# 获取大内容（如交互原型）
studio-cli project-docs read --project-id <pid> --doc-id <did> --chapter-id <cid> --binding 交互原型

# 导出 PRD 给 AI IDE 使用的本地上下文包
studio-cli project-docs export-context --project-id <pid> --doc-id <prd-doc-id>
```

### 交互原型与动态章节

`project-docs read` 会按工作台同样的方式读取文档：

- 先读取文档详情中的章节模板与静态 sections
- 再读取当前文档实例绑定的实体数据
- 对动态章节（如 PRD 的功能模块、功能规格）进行展开
- 对 `交互原型` 这类大内容不直接内联到 Markdown，而是在输出中写入检索命令

默认 Markdown 中会看到类似内容：

```markdown
##### 交互原型

> 内容较大，已省略。需要查看时请执行：
> `studio-cli project-docs read --project-id <pid> --doc-id <did> --chapter-id <cid> --binding 交互原型`
```

执行提示命令后：

- 如果原型内容本身是 HTML，直接输出 HTML
- 如果原型内容是链接，CLI 会拉取链接内容并输出 HTML
- 同源链接会携带 `X-API-Key`，外部链接不会携带 API Key

### 输出格式

| 选项 | 说明 |
|---|---|
| （默认） | 清洁 Markdown，大内容（交互原型）替换为检索命令 |
| `--format json` | JSON 信封格式 |
| `--context-only` | 纯 Markdown 文本（等同默认，适合管道） |
| `--for-context` | JSON 信封 + 嵌入 contextText 字段 |
| `--raw` | 原始 API 响应 |

### 导出 AI IDE 上下文包

`project-docs export-context` 会把指定 PRD 导出到 `.aiko-studio/`，供 Cursor、Claude Code、Codex 等 AI IDE 读取：

```bash
studio-cli project-docs export-context \
  --project-id <pid> \
  --doc-id <prd-doc-id> \
  --output .aiko-studio
```

生成内容包括：

- `.aiko-studio/AGENTS.md`：跨 AI IDE 的读取与计划规则，作为默认主入口
- `.aiko-studio/spec.md`：开发任务主入口，告诉 AI 读取顺序和关键链接
- `.aiko-studio/tasks.md`：从 PRD 派生的可实施任务地图，避免一次性实现整个 PRD
- `.aiko-studio/implementation-map.md`：任务到 PRD 章节、BRD 摘要、原型资产的映射
- `.aiko-studio/llms.txt` / `.aiko-studio/llms-full.md`：通用 agent 上下文索引
- `.aiko-studio/context/<project-id>/<doc-id>/manifest.json`：机器可读索引
- `.aiko-studio/context/<project-id>/<doc-id>/relationships.json`：文档、章节、原型资产关系
- `.aiko-studio/context/<project-id>/<doc-id>/assets/prototypes/`：交互原型 HTML 文件

推荐让 AI 先读取 `.aiko-studio/AGENTS.md`，再从 `tasks.md` 选择一个任务，并按 `implementation-map.md` 只加载相关章节和原型。

常用选项：

```bash
--include-prereqs summary|full|none   # 默认 summary
--prototype file|inline|skip          # 默认 file
--force                               # 覆盖已有导出
--format json                         # 输出导出摘要 JSON
```

## 本地开发与测试

开发 `studio-cli` 时，建议使用本地入口运行，避免误用全局已安装版本：

```bash
cd studio-cli

# 使用本地代码读取文档上下文
node bin/studio-cli.js project-docs read \
  --project-id <pid> \
  --doc-id <did> \
  --context-only

# 使用本地代码读取某个原型 HTML
node bin/studio-cli.js project-docs read \
  --project-id <pid> \
  --doc-id <did> \
  --chapter-id <cid> \
  --binding 交互原型
```

本次 `project-docs` 相关实现覆盖了这些场景：

- `read --raw` 输出原始文档详情 JSON
- `read --context-only` 展开实体数据中的动态章节
- `交互原型` 在 Markdown 中输出检索命令
- `read --binding 交互原型` 支持直接 HTML 和链接拉取 HTML

运行测试：

```bash
npm test
```

## AI Skills

内置两个 AI Skills，用于 AI 辅助开发：

| Skill | 说明 |
|---|---|
| `studio-config-units` | 生成和管理配置单元定义（实体、文档类型、编排规则） |
| `studio-project-doc-context` | 读取项目文档内容作为 AI 上下文（PRD、BRD、设计文档） |

```bash
# 交互式选择要安装的 skill 和 agent
studio-cli install-skills

# 非交互安装到指定 AI agent
studio-cli install-skills --agent cursor

# 安装到多个指定 agent
studio-cli install-skills --agent cursor,claude-code

# 明确安装到所有支持的 agent
studio-cli install-skills --agent '*'

# 仅查看可用 skills
studio-cli install-skills --list
```

不带参数时会进入交互式选择流程；脚本化安装时使用 `--agent` 明确目标。

## 配置

配置文件存储在 `~/.studio-ai/config.json`。

```bash
# 手动配置
studio-cli config init

# 查看当前配置
studio-cli config show

# 重置配置
studio-cli config reset
```

## License

MIT