@ia-ccun/code-agent-claw 0.0.1

package/.claude/plan/aicode-ui-npm.md

@@ -0,0 +1,477 @@
+# Implementation Plan: aicode-ui NPM 项目重构
+
+## 概述
+
+本规划将现有的 Spring Boot 2.7.18 + Java 11 后端项目重构为 Node.js/npm 项目，使用 Express + WebSocket 实现相同的功能。重构后的项目将支持 `aicode-ui` 命令行启动，用户安装后可直接运行并访问 Anthropic 风格的 AI Agent 控制台界面。
+
+**npm 包名**: `@ia-ccun/aicode-ui`
+
+**重要特性**: 前端可视化配置，用户可自行配置 piagent 参数后初始化 RPC 模式 agent
+
+### 现有架构（Spring Boot）
+
+```
+                    +-------------------+
+                    |   Spring Boot    |
+                    |   后端 (Java)    |
+                    +--------+----------+
+                             |
+              +--------------+--------------+
+              |                              |
+         REST API                      WebSocket
+         /api/aicode/*                      /ws/agent
+              |                              |
+              +--------------+---------------+
+                             |
+                    +--------v---------+
+                    |  aicode 子进程   |
+                    |  (stdin/stdout)  |
+                    |  JSONL 协议      |
+                    +------------------+
+```
+
+### 核心 API 端点
+
+| 端点 | 方法 | 功能 |
+|------|------|------|
+| `/api/aicode/config` | GET | 获取当前配置 |
+| `/api/aicode/config` | POST | 保存配置并初始化 agent |
+| `/api/aicode/prompt` | POST | 发送提示 |
+| `/api/aicode/steer` | POST | 发送引导消息（中断当前操作）|
+| `/api/aicode/follow-up` | POST | 发送后续消息 |
+| `/api/aicode/abort` | POST | 中止当前操作 |
+| `/api/aicode/new-session` | POST | 创建新会话 |
+| `/api/aicode/health` | GET | 健康检查 |
+| `/api/aicode/status` | GET | 获取 agent 状态（未初始化/运行中/已停止）|
+
+### 核心服务组件（Java）
+
+- **PiAgentRpcService**: 负责启动和管理 aicode 子进程，通过 JSONL 协议通信
+- **PiAgentController**: REST API 控制器
+- **PiAgentWebSocketHandler**: WebSocket 处理器，实时推送 Agent 事件
+- **PiAgentProperties**: 配置属性类
+
+### 现有配置（application.yml）
+
+```yaml
+server.port: 8080
+pi.agent.enabled: true
+pi.agent.command: /Users/xujianjiang/npm-global/bin/aicode
+pi.agent.provider: minimax-custom
+pi.agent.model: MiniMax-M2.5
+pi.agent.session-dir: ${user.home}/.aicode-cli/agent/sessions
+pi.agent.working-dir: ${user.home}/.aicode-cli
+```
+
+---
+
+## 1. 项目结构设计
+
+### 目标结构
+
+```
+aicode-ui/
+├── bin/
+│   └── cli.js                 # CLI 入口点（npm bin）
+├── src/
+│   ├── index.ts               # 主入口文件
+│   ├── config.ts              # 配置定义和加载
+│   ├── server/
+│   │   ├── index.ts           # Express 服务器
+│   │   ├── routes.ts          # REST API 路由
+│   │   └── websocket.ts       # WebSocket 处理
+│   ├── services/
+│   │   └── agent-rpc.ts       # aicode 子进程管理（核心）
+│   ├── types/
+│   │   └── index.ts           # TypeScript 类型定义
+│   └── utils/
+│       └── logger.ts          # 日志工具
+├── public/
+│   ├── index-v3.html          # 前端主页面
+│   ├── index.html             # 前端入口
+│   ├── juejin.css             # 样式文件
+│   └── aicode.svg             # 图标
+├── config/
+│   └── default.json           # 默认配置
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+### 目录说明
+
+| 目录 | 说明 |
+|------|------|
+| `bin/cli.js` | CLI 入口，用户执行 `aicode-ui` 时调用 |
+| `src/server/` | Express 服务器相关代码 |
+| `src/services/agent-rpc.ts` | 核心服务：启动和管理 aicode 子进程 |
+| `public/` | 静态前端文件（从 backend-app 复制）|
+
+---
+
+## 2. 技术选型说明
+
+### 核心技术栈
+
+| 技术 | 版本 | 用途 |
+|------|------|------|
+| Node.js | >= 18.0.0 | 运行时 |
+| TypeScript | ^5.0.0 | 开发语言 |
+| Express | ^4.18.0 | HTTP 服务器 |
+| ws | ^8.14.0 | WebSocket 实现 |
+| conf | ^12.0.0 | 配置管理 |
+| commander | ^11.0.0 | CLI 参数解析 |
+| pino | ^8.0.0 | 日志库 |
+| strip-ansi | ^6.0.0 | ANSI 颜色码清理 |
+
+### 技术选型理由
+
+1. **Express**: 成熟稳定，轻量级，易于实现 REST API
+2. **ws**: 高性能原生 WebSocket 实现，比 Socket.io 更轻量
+3. **commander**: Node.js 标准 CLI 框架
+4. **conf**: 跨平台配置管理，支持环境变量覆盖
+5. **pino**: 高性能 JSON 日志库
+
+---
+
+## 3. 功能模块划分
+
+### 模块 1: CLI 入口（bin/cli.js）
+
+**功能**:
+- 解析命令行参数（端口、配置路径等）
+- 启动服务器
+- 处理信号（SIGINT/SIGTERM）优雅关闭
+
+**关键代码结构**:
+```typescript
+// 伪代码
+program
+  .name('aicode-ui')
+  .option('-p, --port <port>', '服务器端口', '8080')
+  .option('-c, --command <path>', 'aicode 命令路径')
+  .option('--config <path>', '配置文件路径')
+  .action(startServer);
+
+program.parse(process.argv);
+```
+
+### 模块 2: 配置管理（src/config.ts）
+
+**功能**:
+- 加载默认配置
+- 支持配置文件（JSON/YAML）
+- 支持环境变量覆盖
+- 支持命令行参数
+
+**配置项**:
+```typescript
+interface Config {
+  server: {
+    port: number;
+    host: string;
+  };
+  agent: {
+    enabled: boolean;
+    command: string;
+    provider: string;
+    model: string;
+    sessionDir: string;
+    workingDir: string;
+  };
+  logging: {
+    level: string;
+  };
+}
+```
+
+### 模块 3: aicode 子进程管理（src/services/agent-rpc.ts）
+
+**功能**:
+- 启动/重启 aicode 子进程
+- JSONL 协议通信（发送命令、接收事件）
+- 命令队列和 Future 模式
+- 进程健康检查和自动重启
+- 事件回调注册
+
+### 模块 4: REST API（src/server/routes.ts）
+
+**功能**:
+- `/api/aicode/config` - 获取/保存配置（保存配置并触发初始化）
+- `/api/aicode/status` - 获取 agent 状态
+- `/api/aicode/health` - 健康检查
+- `/api/aicode/prompt` - 发送提示
+- `/api/aicode/steer` - 发送引导消息
+- `/api/aicode/follow-up` - 发送后续消息
+- `/api/aicode/abort` - 中止操作
+- `/api/aicode/new-session` - 创建新会话
+
+**动态配置流程**:
+1. 前端 POST `/api/aicode/config` 提交配置
+2. 后端保存配置到 `~/.aicode-ui/config.json`
+3. 后端检查 aicode 命令是否存在
+4. 启动 aicode 子进程（RPC 模式）
+5. 返回初始化结果
+
+### 模块 5: WebSocket 处理（src/server/websocket.ts）
+
+**功能**:
+- 管理 WebSocket 连接
+- 广播 Agent 事件到前端
+- 支持 text_delta、agent_end 等事件类型
+
+### 模块 6: 前端配置界面
+
+**功能**:
+- 配置表单（aicode 命令路径、provider、model、session-dir、working-dir）
+- 配置持久化（保存到配置文件）
+- 初始化按钮：保存配置后启动 aicode 子进程
+- 连接状态显示
+
+**配置项**:
+| 配置项 | 说明 | 默认值 |
+|--------|------|--------|
+| command | aicode 命令路径 | aicode |
+| provider | LLM Provider | minimax-custom |
+| model | 模型名称 | MiniMax-M2.5 |
+| noSession | 无会话模式 | true |
+| sessionDir | 会话目录 | ~/.aicode-cli/agent/sessions |
+| workingDir | 工作目录 | ~/.aicode-cli |
+
+**后端启动参数** (从 Java 版本移植):
+```
+aicode --mode rpc --provider <provider> --model <model> --session-dir <sessionDir>
+```
+
+**前端页面结构**:
+- 首次访问显示配置弹窗
+- 配置保存后显示主界面
+- 支持随时打开设置修改配置
+
+---
+
+## 4. 实施步骤
+
+### Phase 1: 项目初始化
+
+#### 步骤 1.1: 创建项目结构
+- 初始化 npm 项目
+- 安装依赖
+- 创建 TypeScript 配置
+- 创建目录结构
+
+**package.json**:
+```json
+{
+  "name": "@ia-ccun/aicode-ui",
+  "version": "1.0.0",
+  "description": "AICode Agent WebUI - Node.js version",
+  "main": "dist/index.js",
+  "bin": {
+    "aicode-ui": "./bin/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "ts-node src/index.ts"
+  },
+  "dependencies": {
+    "commander": "^11.0.0",
+    "conf": "^12.0.0",
+    "express": "^4.18.0",
+    "pino": "^8.0.0",
+    "strip-ansi": "^6.0.0",
+    "ws": "^8.14.0"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.0",
+    "@types/node": "^20.0.0",
+    "@types/ws": "^8.5.0",
+    "ts-node": "^10.9.0",
+    "typescript": "^5.0.0"
+  },
+  "preferGlobal": true
+}
+```
+
+#### 步骤 1.2: 配置管理
+- 创建默认配置文件
+- 实现配置加载逻辑
+
+---
+
+### Phase 2: 核心服务开发
+
+#### 步骤 2.1: aicode 子进程管理服务
+- 实现子进程启动
+- 实现 JSONL 协议通信
+- 实现命令发送和响应处理
+- 实现事件解析和回调
+
+核心逻辑移植自 `PiAgentRpcService.java`
+
+---
+
+### Phase 3: 服务器和 API
+
+#### 步骤 3.1: Express 服务器
+- 创建 Express 应用
+- 配置静态文件服务
+- 配置中间件
+
+#### 步骤 3.2: REST API 路由
+- 实现所有 API 端点
+
+#### 步骤 3.3: WebSocket 处理
+- 实现事件广播
+
+---
+
+### Phase 4: 前端集成
+
+#### 步骤 4.1: 复制前端文件
+- 从 backend-app 复制前端文件到 public 目录
+
+**源文件**:
+- `/backend-app/src/main/resources/static/index-v3.html` -> `public/index-v3.html`
+- `/backend-app/src/main/resources/static/index.html` -> `public/index.html`
+- `/backend-app/src/main/resources/static/juejin.css` -> `public/juejin.css`
+- `/backend-app/src/main/resources/static/aicode.svg` -> `public/aicode.svg`
+
+---
+
+### Phase 5: CLI 入口和打包
+
+#### 步骤 5.1: 创建 CLI 入口
+- 创建 bin/cli.js
+
+#### 步骤 5.2: 配置 package.json
+- 设置 bin 入口
+- 添加构建脚本
+
+---
+
+## 5. 验收标准
+
+### 5.1 安装验收
+
+- [ ] 执行 `npm install -g @ia-ccun/aicode-ui` 成功安装
+- [ ] `aicode-ui` 命令可用
+- [ ] 无安装错误
+
+### 5.2 启动验收
+
+- [ ] 执行 `aicode-ui` 成功启动服务器
+- [ ] 服务器默认监听 8080 端口
+- [ ] 访问 `http://localhost:8080/index-v3.html` 可打开前端页面
+- [ ] 首次访问显示配置弹窗
+- [ ] 健康检查 `http://localhost:8080/api/aicode/health` 返回正确状态
+
+### 5.2.1 配置功能验收
+
+- [ ] 前端配置表单可填写：command、provider、model、noSession、sessionDir、workingDir
+- [ ] 点击"初始化"按钮后保存配置并启动 aicode 子进程
+- [ ] 配置持久化到 `~/.aicode-ui/config.json`
+- [ ] 再次访问时自动加载已有配置
+- [ ] 支持随时修改配置并重新初始化
+
+### 5.3 功能验收
+
+- [ ] **发送提示**: POST `/api/aicode/prompt` 成功发送消息给 aicode
+- [ ] **接收事件**: WebSocket 正常接收 aicode 事件（message_update, agent_end 等）
+- [ ] **中断操作**: POST `/api/aicode/steer` 可中断当前操作
+- [ ] **后续消息**: POST `/api/aicode/follow-up` 可发送后续消息
+- [ ] **中止操作**: POST `/api/aicode/abort` 可中止当前操作
+- [ ] **新会话**: POST `/api/aicode/new-session` 可创建新会话
+
+### 5.4 配置验收
+
+- [ ] 配置文件 `~/.aicode-ui/config.json` 可正常加载
+- [ ] 环境变量覆盖配置生效（如 `AICODE_UI_PORT=9000`）
+- [ ] 命令行参数覆盖配置生效（如 `aicode-ui --port 9000`）
+
+### 5.5 稳定性验收
+
+- [ ] aicode 子进程异常退出后自动重启
+- [ ] 关闭服务器时子进程正确清理
+- [ ] 长时间运行无内存泄漏
+
+### 5.6 兼容性验收
+
+- [ ] Node.js 18+ 环境可正常运行
+- [ ] Windows/macOS/Linux 平台可正常运行
+
+### 5.7 发布验收
+
+- [ ] 成功发布到 npm: `@ia-ccun/aicode-ui`
+- [ ] 从 npm 安装后命令可用
+
+---
+
+## 6. 风险与缓解措施
+
+### 风险 1: 子进程通信协议兼容性
+
+**描述**: aicode 命令的 `--mode rpc` 输出格式可能与 Java 版本解析逻辑不完全兼容
+
+**缓解措施**:
+- 详细测试不同类型的 JSONL 事件
+- 添加协议解析调试日志
+- 预留配置项调整解析逻辑
+
+### 风险 2: 前端 API 地址
+
+**描述**: 复制的前端文件中的 API 地址可能使用硬编码
+
+**缓解措施**:
+- 使用相对路径 `/api/...` 和 WebSocket `ws://localhost:port/ws/agent`
+
+### 风险 3: 配置路径兼容性
+
+**描述**: Windows 和 macOS/Linux 的路径格式不同
+
+**缓解措施**:
+- 使用 Node.js 的 `path` 模块处理路径
+- 配置默认路径使用 `os.homedir()`
+
+---
+
+## 7. 实施顺序总结
+
+```
+Phase 1: 项目初始化
+  1.1 创建项目结构和 package.json
+  1.2 配置管理
+
+Phase 2: 核心服务开发
+  2.1 aicode 子进程管理服务（最重要）
+
+Phase 3: 服务器和 API
+  3.1 Express 服务器
+  3.2 REST API 路由
+  3.3 WebSocket 处理
+
+Phase 4: 前端集成
+  4.1 复制前端文件
+
+Phase 5: CLI 入口和打包
+  5.1 创建 CLI 入口
+  5.2 配置 package.json
+
+Phase 6: 发布
+  6.1 发布到 npm (@ia-ccun/aicode-ui)
+```
+
+---
+
+## 相关文件路径
+
+**原始项目（Java）**:
+- `/Users/xujianjiang/IdeaProjects/code-agent-cli/backend-app/src/main/java/com/aicode/piagent/service/PiAgentRpcService.java`
+- `/Users/xujianjiang/IdeaProjects/code-agent-cli/backend-app/src/main/java/com/aicode/piagent/controller/PiAgentController.java`
+- `/Users/xujianjiang/IdeaProjects/code-agent-cli/backend-app/src/main/resources/application.yml`
+- `/Users/xujianjiang/IdeaProjects/code-agent-cli/backend-app/src/main/resources/static/index-v3.html`
+
+**新项目（目标）**:
+- `/Users/xujianjiang/IdeaProjects/code-agent-cli/inner-claw-webui/`
+- **npm 包名**: `@ia-ccun/aicode-ui`

package/README.md

@@ -0,0 +1,108 @@
+# Code Agent Claw WebUI
+
+可视化界面，让你可以用浏览器配置和管理 Code Agent。
+
+## 什么是 Code Agent Claw WebUI
+
+这是一个运行在浏览器中的可视化控制台，用于：
+- **配置 Agent**：设置模型、提供商、工作目录等参数
+- **发送指令**：通过图形界面发送提示、引导或后续消息
+- **实时交互**：查看 Agent 的实时响应和状态
+- **会话管理**：创建和管理多个对话会话
+
+## 安装步骤
+
+### 1. 安装 Node.js
+
+确保你的系统已安装 Node.js 20.0 或更高版本：
+
+```bash
+node --version
+```
+
+如未安装，请访问 [nodejs.org](https://nodejs.org/) 下载安装。
+
+### 2. 全局安装
+
+```bash
+npm i -g @ia-ccun/code-agent-claw
+```
+
+### 3. 启动服务
+
+```bash
+aicode-claw
+```
+
+启动成功后，终端会显示：
+
+```
+Server started: http://localhost:8081
+WebUI:          http://localhost:8081/index.html
+```
+
+### 4. 打开浏览器访问
+
+在浏览器中打开 http://localhost:8081 即可看到控制台界面。
+
+## 首次配置
+
+首次使用时，需要完成以下配置：
+
+### 配置说明
+
+> 💡 **提示**：Provider 和 Model 的可用选项可以参考 `~/.aicode-cli/agent/models.json` 文件。
+
+| 配置项 | 说明 | 示例值 |
+|--------|------|--------|
+| **Command** | aicode 命令的路径 | `aicode` 或完整路径 |
+| **Provider** | LLM 服务提供商 | `minimax-custom` |
+| **Model** | 使用的模型名称 | `MiniMax-M2.5` |
+| **Working Dir** | Agent 工作目录 | `~/.aicode-cli` |
+| **Session Dir** | 会话保存目录 | `~/.aicode-cli/agent/sessions` |
+
+### 配置步骤
+
+1. 在 Web 界面左侧的「配置面板」中填写上述信息
+2. 点击「初始化」按钮
+3. 等待 Agent 启动，状态指示器变绿即表示成功
+
+## 使用指南
+
+### 发送提示
+
+在底部输入框中输入你的问题或指令，点击发送或按 Enter 提交。Agent 会实时返回响应。
+
+### 使用引导消息
+
+点击「Steer」按钮发送引导消息，用于调整 Agent 的行为或方向。
+
+### 后续对话
+
+在对话过程中，可以使用「Follow Up」发送后续补充信息。
+
+### 中止操作
+
+如果 Agent 响应时间过长，点击「Abort」按钮中止当前操作。
+
+### 创建新会话
+
+点击「New Session」创建全新对话，会清除当前上下文。
+
+## 常见问题
+
+**Q: 启动后提示 "aicode command not found"**
+
+A: 确保已将 aicode CLI 安装到系统路径中，或在配置中填写完整路径。
+
+**Q: 状态一直显示 "未连接"**
+
+A: 检查配置是否正确填写，然后点击「初始化」按钮启动 Agent。
+
+**Q: 如何修改端口号？**
+
+A: 可以通过环境变量 `AICODE_UI_PORT` 修改，或直接修改 `config/default.json`。
+
+## 技术支持
+
+如遇问题，可查看终端日志获取详细错误信息。

package/bin/cli.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+
+const { spawn } = require('child_process');
+const path = require('path');
+
+const distPath = path.join(__dirname, '..', 'dist', 'index.js');
+
+const child = spawn('node', [distPath], {
+  stdio: 'inherit',
+  cwd: process.cwd(),
+  env: process.env
+});
+
+child.on('exit', (code) => {
+  process.exit(code || 0);
+});

package/config/default.json

@@ -0,0 +1,18 @@
+{
+  "server": {
+    "port": 8081,
+    "host": "0.0.0.0"
+  },
+  "agent": {
+    "enabled": false,
+    "command": "aicode",
+    "provider": "minimax-custom",
+    "model": "MiniMax-M2.5",
+    "noSession": true,
+    "sessionDir": "~/.aicode-cli/agent/sessions",
+    "workingDir": "~/.aicode-cli"
+  },
+  "logging": {
+    "level": "info"
+  }
+}

package/dist/config.d.ts

@@ -0,0 +1,22 @@
+import { Config, AgentConfig } from './types';
+/**
+ * 自动检测 aicode 命令路径
+ */
+export declare function findAicodeCommand(): string;
+/**
+ * 加载配置
+ */
+export declare function loadConfig(): Config;
+/**
+ * 保存配置到用户目录
+ */
+export declare function saveUserConfig(agentConfig: AgentConfig): void;
+/**
+ * 获取用户配置路径
+ */
+export declare function getUserConfigPath(): string;
+/**
+ * 获取当前配置（仅返回 agent 部分）
+ */
+export declare function getAgentConfig(): AgentConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,MAAM,EAAE,WAAW,EAA+B,MAAM,SAAS,CAAC;AAG3E;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAqD1C;AAkCD;;GAEG;AACH,wBAAgB,UAAU,IAAI,MAAM,CA0DnC;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI,CA+B7D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AA+BD;;GAEG;AACH,wBAAgB,cAAc,IAAI,WAAW,CAG5C"}