@succsoft/succapp 5.0.0 → 5.0.2

package/README.md

@@ -1,10 +1,59 @@
 # SuccApp
 
-**SuccApp**是SuccBI配套的一个集成二次开发环境，可以方便的进行扩展开发、脚本二次开发：
+SuccApp 是面向低代码项目交付、二次开发和 AI 辅助开发的配套工具。
 
-1. 方便快速开发、发布、测试SuccBI的扩展
-2. 方便进行应用脚本开发，包括前端脚本和后端脚本
-3. 一些比较大的二次开发项目希望将所有元数据，包括脚本等等都能进行`git`版本管理
-4. 对元数据文件进行批量查找和替换等操作
+SuccApp helps teams work with low-code metadata as local files.
 
-更多帮助见[SuccBI产品手册](https://docs.succbi.com/dev/ide/)。
+它提供 SuccApp CLI 和 SuccApp for VS Code 两个入口，用于管理本地 SuccApp 工作区、连接服务器、同步元数据文件、检查差异、编辑脚本和辅助团队协作。
+
+SuccApp 的核心思路是把页面、仪表板、报表、数据模型、程序流、脚本、主题和配置等元数据保存为本地文件。项目成员和 AI Agent 可以在本地修改这些文件，再通过 SuccApp CLI 或 SuccApp for VS Code 查看差异、拉取服务器变化、推送到测试环境，并按团队流程提交 Git 和发布生产。
+
+## SuccApp CLI / 命令行工具
+
+SuccApp CLI 面向终端、脚本和 AI Agent，命令名为 `succapp`。它适合初始化工作区、连接服务器、查询状态、查看 diff、拉取和推送元数据、读取文件历史、解析页面地址、查询数据库结构，并用 `--json` 输出结构化结果。
+
+Install:
+
+```bash
+npm install -g @succsoft/succapp
+```
+
+Verify:
+
+```bash
+succapp --version
+succapp --help
+```
+
+常用起步命令：
+
+```bash
+succapp workspace init --server=<server-url>
+succapp auth login <server-url>
+succapp workspace project clone <project>
+succapp workspace status --json
+succapp workspace file diff <path>
+succapp workspace push <path>
+```
+
+`auth login` 使用默认登录方式，会打开浏览器完成 OAuth2 授权；无法自动打开浏览器时，按命令输出的授权地址在浏览器中完成登录即可。PAT 仅作为受限环境下的显式备用方式，不作为推荐登录路径。
+
+其中 `workspace push` 会写入服务器。推送前应先检查差异；生产服务器必须按团队发布流程确认。
+
+## SuccApp for VS Code / VS Code 工具
+
+SuccApp for VS Code 面向人工检查和交互式开发。它提供服务器视图、Changes 视图、文件历史、diff、脚本编辑、远端文件打开和 Git 协作入口，适合项目成员查看 AI 修改结果、处理冲突和执行需要人工确认的同步操作。
+
+在线安装时，在 VS Code 扩展视图搜索 `SuccApp` 并安装。离线环境可以使用与当前版本匹配的 `.vsix` 安装包：
+
+```bash
+code --install-extension succapp-for-vscode-版本号.vsix
+```
+
+## 文档
+
+更多使用说明见产品手册：
+
+- [AI 低代码开发](https://docs.succbi.com/v5/dev/ai-building)
+- [SuccApp CLI](https://docs.succbi.com/v5/dev/ai-building/cli)
+- [SuccApp for VS Code](https://docs.succbi.com/v5/dev/ai-building/vscode)