@superpms/memory-cli 0.1.2 → 0.1.4

package/README.md

@@ -1,54 +1,504 @@
-# @superpms/memory-cli
+# `@superpms/memory-cli`
 
-Memory system CLI — manage global layer, will sync, vendor distribution, and Cloud Brain integration.
+`memory` 是 memory system 的命令行工具，用来连接 Cloud Brain、初始化项目、同步 `vendor` 与 `will`，以及管理项目内的 `skill` 和缓存。
 
-## Install
+## 功能概览
+
+- 登录或注册 Cloud Brain 账号
+- 在当前目录初始化 memory 项目骨架
+- 从 Cloud Brain 拉取最新 `vendor`
+- 将项目中的 `will` 发布到 Cloud Brain，或从 Cloud Brain 拉回本地
+- 订阅他人的 `will` 并拉取订阅内容
+- 查看和卸载项目 `skill`
+- 查看和清理项目缓存
+
+## 环境要求
+
+- Node.js `>= 18`
+
+## 安装
 
 ```bash
 npm install -g @superpms/memory-cli
 ```
 
-## Quick Start
+安装后可直接使用：
 
 ```bash
-# Initialize global layer
-memory init --global
+memory --help
+```
+
+## 核心概念
+
+### 1. Cloud Brain
+
+Cloud Brain 是远程服务，负责保存：
+
+- 用户账号与 API Key
+- 用户 `will`
+- 订阅关系
+- `vendor` 发布记录
+
+### 2. memory 项目
+
+CLI 会把“存在 `memory/start.md` 的目录”识别为 memory 项目根目录。
+
+初始化后的关键目录通常包括：
+
+```text
+your-project/
+├─ memory/
+│  ├─ start.md
+│  ├─ vendor/
+│  └─ will/current/
+└─ .memory/
+   └─ .project/
+      ├─ config/
+      ├─ cache/
+      ├─ global/
+      └─ skills/
+```
+
+### 3. 凭证文件
+
+CLI 会把登录信息保存在本地：
+
+- 默认路径：`~/.memory-cli/credentials.json`
+- 可通过环境变量 `MEMORY_CREDENTIALS_DIR` 自定义目录
+
+凭证中只保存：
+
+- `api_endpoint`
+- `api_key`
+- `user_id`
+- `will_id`
+
+## 快速开始
+
+### 1. 注册或登录
+
+首次连接远程 Cloud Brain 时，建议显式传入 `--endpoint`：
+
+```bash
+memory login register --endpoint=https://memory-brain.dev
+memory login --endpoint=https://memory-brain.dev
+```
+
+注意：
+
+- 登录和注册都要求使用邮箱格式账号
+- 交互式提示现在会要求输入 `Email`
+- 如果本地已经保存过 endpoint，后续可直接执行 `memory login`
+- 如果没有显式指定且本地也没有保存 endpoint，CLI 会回退到 `http://localhost:3900`
+
+### 2. 初始化项目
+
+在你的项目根目录执行：
 
-# Check status
+```bash
+memory init
+```
+
+它会执行这些动作：
+
+- 从 Cloud Brain 下载最新 `vendor`
+- 从模板或最小骨架初始化项目结构
+- 从 Cloud Brain 拉取当前用户的 `will`
+
+如果当前目录已经是 memory 项目，CLI 会直接提示并退出，不会重复初始化。
+
+### 3. 查看当前状态
+
+```bash
 memory status
+memory login status
+memory version
+```
+
+## 登录与账号
+
+### 注册
+
+```bash
+memory login register --endpoint=https://memory-brain.dev
+```
+
+交互式输入：
+
+- `Email`
+- `Password`
+- `Display name (optional)`
+
+注册成功后，CLI 会把返回的：
+
+- API Key
+- 用户 ID
+- 默认 `will` ID
+- endpoint
+
+一起写入本地凭证。
+
+### 登录
+
+```bash
+memory login --endpoint=<endpoint-url>
+```
+
+交互式输入：
+
+- `Email`
+- `Password`
+
+### 查看登录状态
+
+```bash
+memory login status
+```
+
+会显示：
+
+- 当前登录用户
+- 默认 `will` ID
+- 订阅者数量
+- 当前使用的 Cloud Brain endpoint
+
+### 退出登录
+
+```bash
+memory login logout
+```
+
+退出后会清空本地 `api_key`、`user_id`、`will_id`，但会保留已经保存的 `api_endpoint`。
+
+## 项目初始化与更新
+
+### 初始化项目
+
+```bash
+memory init
+```
+
+前置条件：
+
+- 已登录 Cloud Brain
+- 当前目录还不是 memory 项目
+
+### 更新 `vendor`
+
+```bash
+memory update
+```
+
+作用：
+
+- 从 Cloud Brain 下载最新 `vendor`
+- 写入当前项目的 `memory/vendor/`
+
+前置条件：
+
+- 已登录
+- 当前目录在 memory 项目内
+
+## `will` 命令
+
+### 发布当前项目的 will
+
+```bash
+memory will publish
+```
+
+作用：
+
+- 读取当前项目 `memory/will/current/`
+- 上传到 Cloud Brain
+
+### 从 Cloud Brain 拉取自己的 will
+
+```bash
+memory will pull
+```
+
+### 查看 will 状态
+
+```bash
+memory will status
+```
+
+显示：
+
+- 本地 `will` 目录是否存在
+- 关键 will 文件数量
+- 当前是否已连接云端
+
+### 查看云端版本历史
+
+```bash
+memory will versions
+```
+
+### 设置可见性
+
+```bash
+memory will visibility private
+memory will visibility public
+memory will visibility unlisted
+```
+
+### 订阅别人的 will
+
+```bash
+memory will subscribe <will_id>
+memory will subscribe <will_id> --dimensions=02,03
+memory will subscribe <will_id> --dimensions 02,03
+```
+
+### 查看我的订阅
+
+```bash
+memory will subscriptions
+```
+
+### 查看谁订阅了我
 
-# Sync will
-memory will push    # project → global
-memory will pull    # global → project
+```bash
+memory will subscribers
+```
+
+### 取消订阅
+
+```bash
+memory will unsubscribe <will_id>
+```
+
+### 拉取订阅内容
+
+```bash
+memory will sub-pull <will_id>
+```
+
+拉取结果会写入：
+
+```text
+.memory/.project/subscriptions/<will_id>/
+```
+
+其中包含：
+
+- 订阅到的文件
+- `manifest.json`
 
-# Update vendor
-memory update              # global → current project
-memory update --cloud      # Cloud Brain → global → project
-memory update --cloud --all  # → all registered projects
+### 兼容别名
 
-# Cloud Brain
-memory login
+下面两个旧命令仍然兼容：
+
+```bash
+memory will cloud-push
+memory will cloud-pull
+```
+
+它们分别等价于：
+
+```bash
+memory will publish
+memory will pull
+```
+
+## `vendor` 命令
+
+### 发布当前项目的 vendor
+
+```bash
 memory vendor publish --version=1.0.0
+```
+
+说明：
+
+- 从当前项目的 `memory/vendor/` 收集文件
+- 上传到 Cloud Brain
+- 需要已登录
+- 远端接口要求管理员权限
+
+如果未传 `--version`，CLI 会尝试读取：
+
+```text
+memory/vendor/version.json
+```
+
+### 查看最新发布版本
+
+```bash
+memory vendor latest
+```
+
+### 查看发布历史
+
+```bash
+memory vendor changelog
+```
+
+### 下载 `vendor`
+
+下载最新版本：
+
+```bash
 memory vendor download
 ```
 
-## Commands
+下载指定版本：
+
+```bash
+memory vendor download --version=1.0.0
+```
+
+## `skill` 命令
+
+### 列出可见 skill
+
+```bash
+memory skill list
+```
+
+会列出两类：
+
+- `memory/vendor/skills` 下的系统 skill
+- `.memory/.project/skills` 下的项目 skill
+
+### 卸载项目 skill
+
+```bash
+memory skill uninstall <skill-name>
+```
+
+只会删除项目级 skill，不会改动 `vendor` 内置 skill。
+
+## `cache` 命令
+
+### 查看缓存状态
+
+```bash
+memory cache status
+```
+
+会统计 `.memory/.project/cache/` 下各缓存目录的：
+
+- 文件数量
+- 占用空间
+
+### 清理旧缓存
+
+默认清理 30 天前的条目：
+
+```bash
+memory cache clean
+```
+
+指定保留时间：
+
+```bash
+memory cache clean --older-than=7
+memory cache clean --older-than=30
+```
+
+当前实现会按“天数”解析这个值。
+
+## `status` 与 `version`
+
+### 查看整体状态
+
+```bash
+memory status
+```
+
+会显示：
+
+- 当前 Cloud Brain 是否已配置
+- 当前用户 ID
+- 当前是否位于 memory 项目内
+- 项目中的 `vendor` / `will` 是否存在
+
+### 查看 CLI 与 vendor 版本
+
+```bash
+memory version
+```
+
+会显示：
+
+- CLI 版本号
+- 当前项目内 `vendor/version.json` 中的版本信息
+
+## 命令速查
+
+| 命令 | 说明 |
+| --- | --- |
+| `memory init` | 初始化当前项目的 memory 结构 |
+| `memory login` | 登录 Cloud Brain |
+| `memory login register` | 注册新账号 |
+| `memory login status` | 查看登录状态 |
+| `memory login logout` | 清空登录态 |
+| `memory update` | 下载最新 `vendor` 到当前项目 |
+| `memory will publish` | 发布当前项目的 `will` |
+| `memory will pull` | 从云端拉取自己的 `will` |
+| `memory will status` | 查看本地 `will` 状态 |
+| `memory will versions` | 查看云端 `will` 版本历史 |
+| `memory will visibility <v>` | 设置 `will` 可见性 |
+| `memory will subscribe <id>` | 订阅他人的 `will` |
+| `memory will unsubscribe <id>` | 取消订阅 |
+| `memory will subscriptions` | 查看我的订阅 |
+| `memory will subscribers` | 查看谁订阅了我 |
+| `memory will sub-pull <id>` | 拉取订阅内容 |
+| `memory vendor publish --version=x.y.z` | 发布当前项目的 `vendor` |
+| `memory vendor latest` | 查看云端最新 `vendor` |
+| `memory vendor changelog` | 查看发布历史 |
+| `memory vendor download [--version=x.y.z]` | 下载 `vendor` |
+| `memory skill list` | 查看系统和项目 `skill` |
+| `memory skill uninstall <name>` | 删除项目级 `skill` |
+| `memory cache status` | 查看缓存状态 |
+| `memory cache clean [--older-than=N]` | 清理旧缓存 |
+| `memory status` | 查看整体状态 |
+| `memory version` | 查看 CLI 与当前项目 vendor 版本 |
+
+## 常见问题
+
+### 1. `Not logged in. Run "memory login" first.`
+
+说明当前本地没有有效的 `api_key` 或 `api_endpoint`。
+
+先执行：
+
+```bash
+memory login --endpoint=https://your-cloud-brain.example.com
+```
+
+### 2. `Not in a memory project. Run "memory init" first.`
+
+说明当前目录及其父目录中都没有：
+
+```text
+memory/start.md
+```
+
+请切到正确项目目录，或先执行：
+
+```bash
+memory init
+```
+
+### 3. 登录时报 `ENOTFOUND`
+
+这通常不是 CLI 逻辑问题，而是当前机器 DNS 无法解析你的 Cloud Brain 域名。
+
+可以优先检查：
+
+```bash
+nslookup your-domain.example.com
+```
+
+### 4. 为什么第一次登录建议带 `--endpoint`
 
-| Command | Description |
-|---------|-------------|
-| `init --global` | Initialize global memory layer |
-| `login` | Authenticate with Cloud Brain |
-| `status` | Show current project memory status |
-| `will <push\|pull\|sync\|broadcast>` | Will synchronization |
-| `will <cloud-push\|cloud-pull>` | Cloud will sync |
-| `update [--cloud] [--all]` | Vendor distribution |
-| `vendor <publish\|latest\|changelog\|download>` | Cloud vendor management |
-| `skill <list\|promote\|demote>` | Skill layer management |
-| `cache <status\|clean>` | Cache management |
-| `projects` | List registered projects |
-| `version` | Show version info |
+因为首次登录前，本地还没有保存 Cloud Brain 地址。显式传入 `--endpoint` 可以确保登录请求直接打到正确的远端服务。
 
-## Requirements
+## 版本信息
 
-- Node.js >= 18
-- No external dependencies
+- 当前包版本见 [package.json](./package.json)
+- 当前实现基于 `memory/cli/commands/` 下实际命令行为编写

package/commands/init.mjs

@@ -128,7 +128,6 @@ function bootstrapFromTemplates(root, templatesDir) {
   const agentEntryMap = {
     'CLAUDE.md':     join(root, 'CLAUDE.md'),
     'AGENTS.md':     join(root, 'AGENTS.md'),
-    'Agent.md':      join(root, 'Agent.md'),
     '.cursorrules':  join(root, '.cursorrules'),
   };
   for (const [tplName, destPath] of Object.entries(agentEntryMap)) {

package/commands/login.mjs

@@ -26,7 +26,7 @@ export default async function login(args) {
 async function handleLogin(args) {
   const endpoint = args.find((a) => a.startsWith('--endpoint='))?.split('=')[1];
 
-  const username = await prompt('Username: ');
+  const username = await prompt('Email: ');
   const password = await prompt('Password: ');
 
   try {
@@ -43,7 +43,7 @@ async function handleLogin(args) {
 async function handleRegister(args) {
   const endpoint = args.find((a) => a.startsWith('--endpoint='))?.split('=')[1];
 
-  const username = await prompt('Username: ');
+  const username = await prompt('Email: ');
   const password = await prompt('Password: ');
   const displayName = await prompt('Display name (optional): ');
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superpms/memory-cli",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "CLI for memory system — global layer, will sync, vendor updates",
   "type": "module",
   "bin": {