linco-connect 1.0.0

package/README.md

@@ -0,0 +1,426 @@
+# linco
+
+Linco / Linco 对接 Claude Code 和 Codex 的本机 Agent 连接器。
+
+它运行在用户自己的电脑上，负责把 Linco IM 服务端的消息转发给本机 Agent CLI，并把 Agent 的回复、工具调用、权限确认、附件和生成文件回传给 IM。仓库内置的 Web 页面只是本地自测页面，不是正式 IM 前端。
+
+## 定位
+
+- 本插件是**本机 Agent 连接器**，不是鉴权服务，也不是托管式多租户服务。
+- Linco IM 服务端负责校验连接 query 中的 `token=appId:appSecret`。
+- 插件连接 IM 时会把本机配置的 `appId/appSecret` 拼成单个 `token` 查询参数传给服务端。
+- IM WebSocket 地址由代码内置，并按 Agent 类型区分：
+
+```text
+Claude Code: wss://chat.ddjf.info/socket/ai/claude
+Codex:       wss://chat.ddjf.info/socket/ai/codex
+```
+
+普通用户初始化时不需要填写 `wsUrl`，私有化部署可在 `.linco/config.json` 中覆盖。
+
+## 功能特性
+
+- npm CLI 安装和启动：支持 `linco init/start/stop/doctor`，可用 `start --daemon` 后台运行。
+- 远端 IM 默认按配置连接，用户只需配置 `appId/appSecret`。
+- 本地测试页的模拟前端 IM 默认不连接：需要本地页面联调时需显式添加 `--local-im` 或 `--mock-im`。
+- 内置 Linco IM WebSocket 地址：用户只需配置 `appId/appSecret`，插件会在连接时拼成 `token=appId:appSecret`。
+- 多 Agent 连接：一个进程可同时连接 Claude Code 和 Codex 对应的 Linco 端点。
+- 本地自测页面：用于调试本机 Agent 桥接能力。
+- 本地访问 token：首次启动自动生成 `localToken`，保护本地测试页和本地 WebSocket。
+- Claude Code 流式桥接：使用 `stream-json` 输入/输出格式实时推送回复。
+- Codex 桥接：第一版使用系统安装的 `codex exec --json`，沿用系统 Codex 登录和配置。
+- 会话隔离：每个 Agent 和远端 session 都创建独立 session、workspace、attachments、outbox。
+- Markdown 展示：支持 GFM Markdown、代码块、表格、引用和安全链接。
+- 工具调用展示：Agent 工具输入、输出和错误以可折叠卡片展示。
+- 权限确认：Agent 请求工具权限时可在前端批准或拒绝。
+- 附件上传：支持普通文件和图片；图片作为多模态内容发送，普通文件保存为本地路径引用。
+- 图片粘贴：支持从剪贴板粘贴图片。
+- 文件下发：Agent 生成文件放入 outbox 后，前端自动展示下载/预览卡片。
+- 斜杠命令：内置 `/help`、`/pwd`、`/cd`、`/new`、`/stop`、`/base`、`/status`、`/list`。
+- Windows Git Bash 检测：Windows 下自动查找 Git Bash，也可手动指定。
+
+## 前置条件
+
+- Node.js 18+
+- 已安装 Claude Code CLI，终端可执行 `claude`
+- Claude Code 已完成登录或 API Key 配置
+- 如需启用 Codex：已安装 Codex CLI，终端可执行 `codex`，并已完成系统 Codex 登录或配置
+- Windows 用户建议安装 Git for Windows
+
+## 安装
+
+开发源码运行：
+
+```bash
+npm install
+npm start
+```
+
+作为 npm CLI 使用时：
+
+```bash
+npm install -g linco
+linco init --token "appId:appSecret" --agent claude
+linco doctor
+linco start
+# 后台运行
+linco start --daemon
+# 停止后台服务
+linco stop
+```
+
+本地开发也可以用：
+
+```bash
+node bin/linco.js init --token "appId:appSecret" --agent claude
+node bin/linco.js doctor
+node bin/linco.js start
+```
+
+## 初始化配置
+
+推荐方式：
+
+```bash
+linco init --token "appId:appSecret" --agent claude
+```
+
+可选参数：
+
+```bash
+linco init \
+  --token "appId:appSecret" \
+  --agent claude \
+  --account default \
+  --force
+```
+
+说明：
+
+- `--token` 格式为 `appId:appSecret`。
+- `--agent` 必填，指定 Agent 类型（如 `claude` 或 `codex`）。
+- token 按第一个冒号切分，所以 `appSecret` 内部可以包含冒号。
+- `--force` 用于覆盖已有账号配置。
+- 初始化不会询问或写入 `wsUrl`。
+- 多次执行 `init` 并传入不同 `--agent` 可在同一账号下启用多个 Agent。
+
+## 配置文件
+
+配置统一保存在用户主目录下的 `.linco` 根目录：
+
+```text
+~/.linco/config.json
+```
+
+Windows 示例：
+
+```text
+C:\Users\<用户名>\.linco\config.json
+```
+
+示例结构：
+
+```json
+{
+  "localWeb": {
+    "token": "auto-generated-local-token"
+  },
+  "defaultChannel": "linco",
+  "defaultAccount": "default",
+  "channels": {
+    "linco": {
+      "accounts": {
+        "default": {
+          "appId": "your-app-id",
+          "appSecret": "your-app-secret"
+        }
+      }
+    }
+  }
+}
+```
+
+配置含义：
+
+- `localWeb.token`：本地测试页访问 token，首次启动或初始化时自动生成。
+- `defaultAccount`：默认账号名。
+- `appId/appSecret`：本机保存的 Linco 应用凭证；插件连接 Linco IM 时会拼成 query 参数 `token=appId:appSecret`。
+- `agents.claude` / `agents.codex`：按 Agent 配置启用状态、CLI 命令和可选私有化 `wsUrl` 覆盖。
+
+默认不需要把内置 `wsUrl` 写入配置文件。启用 Codex 的最小配置示例：
+
+```json
+{
+  "agents": {
+    "codex": {
+      "enabled": true,
+      "bin": "codex"
+    }
+  }
+}
+```
+
+私有化部署可覆盖某个 Agent 的连接地址：
+
+```json
+{
+  "agents": {
+    "codex": {
+      "enabled": true,
+      "bin": "codex",
+      "wsUrl": "wss://example.internal/socket/ai/codex"
+    }
+  }
+}
+```
+
+## 启动
+
+默认启动本地服务，并按配置连接远端 IM；本地测试页不会自动连接模拟前端 IM：
+
+```bash
+linco start
+```
+
+需要使用本地测试页模拟前端 IM 时，显式启用：
+
+```bash
+linco start --local-im
+# 等价写法
+linco start --mock-im
+```
+
+后台启动：
+
+```bash
+linco start --daemon
+```
+
+后台启动并启用本地模拟前端 IM：
+
+```bash
+linco start --daemon --local-im
+```
+
+停止后台服务：
+
+```bash
+linco stop
+```
+
+后台模式会把 PID 和日志写入：
+
+```text
+~/.linco/linco.pid
+~/.linco/logs/daemon.out.log
+~/.linco/logs/daemon.err.log
+```
+
+启动后终端会输出本地测试页地址，例如：
+
+```text
+本地测试页: http://127.0.0.1:3000/?localToken=xxxx
+```
+
+请使用这条带 `localToken` 的地址打开测试页面。直接访问 `http://127.0.0.1:3000` 会被拒绝。
+
+源码开发时也可以继续使用：
+
+```bash
+npm start
+```
+
+源码开发后台运行：
+
+```bash
+npm start -- --daemon
+```
+
+## 环境检查
+
+```bash
+linco doctor
+```
+
+会检查：
+
+- Node.js 版本
+- 配置文件是否存在
+- `appId/appSecret` 是否已配置为 Linco token 来源
+- 本地测试 token 是否已生成
+- 已启用 Agent 的 CLI 是否可用
+- Windows Git Bash 是否可用
+- `Linco Home`、sessions 目录是否可写
+
+`doctor` 不会请求真实 IM 服务端做鉴权；`token=appId:appSecret` 的鉴权由 Linco IM 服务端负责。
+
+## 本地自测页面
+
+本地页面仅用于开发和自测：
+
+- 页面通过本机 WebSocket 连接当前插件服务。
+- 页面不会直接连接供应商 IM WebSocket。
+- 页面需要 `localToken` 才能访问。
+- 页面可测试消息、附件、工具调用、权限确认和 outbox 文件下发。
+
+## 附件上传
+
+默认限制：
+
+- 单次最多 50 个附件
+- 单文件最大 50 MB
+- 单次附件总大小最大 250 MB
+- 默认拦截可执行文件和高风险脚本扩展名，例如 `.exe`、`.bat`、`.cmd`、`.ps1`、`.dll`
+
+图片附件会直接作为当前 Agent 的多模态图片输入；Codex 当前会降级为文本占位提示。普通文件会保存到当前 session 的附件目录，并把本地路径附加给 Agent。
+
+## Agent 生成文件下发
+
+每个 session 都有独立 outbox 目录。Agent 如果需要把文件发给用户，应保存或复制到该目录。服务端会自动扫描新文件并推送到前端显示。
+
+可通过本地命令查看路径：
+
+```text
+/base
+```
+
+输出中会包含：
+
+```text
+附件目录: .../attachments
+outbox 目录: .../outbox
+```
+
+## 斜杠命令
+
+| 命令 | 说明 |
+| --- | --- |
+| `/help` | 显示可用命令和附件说明 |
+| `/commands` | 显示本地命令和当前 Agent 原生命令说明 |
+| `/status` | 显示当前会话状态 |
+| `/pwd` | 显示当前工作目录 |
+| `/cd` | 列出当前目录内容 |
+| `/cd <路径>` | 切换工作目录，并开启新的 Agent 会话 |
+| `/new` | 开启新 Agent 会话，清除上下文 |
+| `/stop` | 停止当前 Agent 进程，下次消息尝试恢复当前会话 |
+| `/base` | 显示 Linco 运行目录、附件目录和 outbox 目录 |
+| `/list` | 列出当前 IM 会话最近 10 条 Agent Session 历史 |
+| `/list <条数>` | 按指定条数列出最近的 Agent Session 历史 |
+
+除上述本地命令外，其他 `/xxx` 会透传给当前 Agent CLI。
+
+## 常用环境变量
+
+| 变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `PORT` | `3000` | 本地 HTTP 服务端口 |
+| `HOST` | `127.0.0.1` | 本地 HTTP 服务监听地址 |
+| `CLAUDE_BIN` | `claude` | Claude Code CLI 命令或路径 |
+| `CODEX_BIN` | `codex` | Codex CLI 命令或路径 |
+| `LINCO_CLAUDE_ENABLED` | 无配置文件时为启用 | 是否启用 Claude 连接器 |
+| `LINCO_CODEX_ENABLED` | `false` | 是否启用 Codex 连接器 |
+| `LINCO_CLAUDE_WS_URL` | `wss://chat.ddjf.info/socket/ai/claude` | Claude 端点覆盖 |
+| `LINCO_CODEX_WS_URL` | `wss://chat.ddjf.info/socket/ai/codex` | Codex 端点覆盖 |
+| `LINCO_LOCAL_AGENT` | `claude` | 本地测试页默认使用的 Agent |
+| `CLAUDE_SYSTEM_PROMPT` | 内置中文 Markdown 输出提示词 | 附加给 Claude 的系统提示词 |
+| `CLAUDE_CODE_GIT_BASH_PATH` | 自动检测 | Windows 下 Git Bash 路径 |
+| `MAX_WS_PAYLOAD_BYTES` | `367001600` | WebSocket 最大消息体大小 |
+| `MAX_ATTACHMENT_COUNT` | `50` | 单次最大附件数量 |
+| `MAX_ATTACHMENT_BYTES` | `52428800` | 单附件大小限制 |
+| `MAX_TOTAL_ATTACHMENT_BYTES` | `262144000` | 单次附件总大小限制 |
+| `MAX_OUTGOING_ATTACHMENT_BYTES` | `52428800` | outbox 单文件下发大小限制 |
+| `MAX_MESSAGE_QUEUE` | `10` | Claude 忙碌时的最大排队消息数 |
+| `ATTACHMENTS_DIR_NAME` | `attachments` | session 运行目录下的附件目录名 |
+| `OUTBOX_DIR_NAME` | `outbox` | session 运行目录下的下发目录名 |
+| `ALLOW_UNSAFE_ATTACHMENTS` | `0` | 设置为 `1` 时允许上传默认拦截的高风险扩展名 |
+| `UNSAFE_ATTACHMENT_EXTENSIONS` | 内置扩展名列表 | 逗号分隔的高风险扩展名列表 |
+| `LINCO_CHANNEL` | `linco` | 选择配置文件中的 IM 渠道 |
+| `LINCO_ACCOUNT` | `default` | 选择配置文件中的 IM 账号 |
+| `LINCO_TOKEN` | 空 | `appId:appSecret` 简写形式；连接 Linco 时作为 query 参数 `token` 发送 |
+| `LINCO_APP_ID` | 配置文件值 | Linco IM 应用 ID |
+| `LINCO_APP_SECRET` | 配置文件值 | Linco IM 应用密钥 |
+| `LINCO_AGENT_ID` | `main` | Linco 连接器标识，可由配置文件或环境变量指定 |
+| `LINCO_WS_URL` | `wss://chat.ddjf.info/socket/ai/claude` | Claude 旧版端点覆盖，普通用户不需要配置 |
+| `LINCO_HOME` | `~/.linco` | 运行数据根目录 |
+| `LINCO_SESSIONS_DIR` | `~/.linco/sessions` | session 数据目录 |
+| `CLAUDE_GRACEFUL_SHUTDOWN_MS` | `3000` | Claude 进程优雅关闭时间 |
+
+## 运行目录
+
+默认目录结构：
+
+```text
+~/.linco/
+├── config.json
+├── claude/
+│   └── sessions/
+│       └── sid_xxxxxxxx/
+│           ├── session.json
+│           ├── workspace/
+│           ├── attachments/
+│           └── outbox/
+└── codex/
+    └── sessions/
+        └── sid_xxxxxxxx/
+            ├── session.json
+            ├── workspace/
+            ├── attachments/
+            └── outbox/
+```
+
+说明：
+
+- `config.json` 保存用户配置和本地测试 token。
+- `claude/sessions/` 和 `codex/sessions/` 分别保存对应 Agent 的会话元数据、工作目录、上传附件和下发文件。
+- `attachments/` 保存用户上传的普通文件。
+- `outbox/` 用于 Agent 生成文件并自动下发给前端。
+- Codex 默认使用系统安装时的认证和配置，不会创建项目托管的 `codex-home`。
+
+## 安全注意事项
+
+- 默认只监听 `127.0.0.1`，不建议直接暴露到公网。
+- 本地测试页受 `localToken` 保护，请不要把带 token 的 URL 发给不可信的人。
+- `appSecret` 保存在本机 `~/.linco/config.json`，请保护好用户电脑和配置文件。
+- 插件不负责校验 `token=appId:appSecret`；真实鉴权由 Linco IM 服务端完成。
+- Agent 的工具权限请求会转发给前端确认，但最终权限边界仍取决于本机 Agent 配置和用户批准。
+- 危险命令检测只是基础提示，不应视为完整沙箱或安全隔离机制。
+- 上传附件会落盘到本机，请不要上传或下发不应保存在本机的敏感文件。
+
+## 项目结构
+
+```text
+.
+├── bin/
+│   └── linco.js          # npm CLI 入口
+├── public/
+│   └── index.html                 # 本地自测页面
+├── src/
+│   ├── agentRunner.js             # Agent 运行器门面
+│   ├── agents/                    # Claude/Codex Provider
+│   ├── attachmentHandler.js       # 上传附件保存、校验和 Agent 输入构造
+│   ├── claudeRunner.js            # Claude Code 子进程、stream-json 解析、权限处理
+│   ├── config.js                  # 配置文件、环境变量和 Git Bash 检测
+│   ├── danger.js                  # 高风险命令文本检测
+│   ├── httpStatic.js              # 静态文件、本地 client config 和 outbox 下载接口
+│   ├── localAuth.js               # 本地测试 token 生成和校验
+│   ├── outgoingAttachmentHandler.js # outbox 扫描和附件下发
+│   ├── protocol.js                # WebSocket 消息封装
+│   ├── serverApp.js               # 可复用服务启动入口
+│   ├── session.js                 # session 状态和 Agent 进程清理
+│   ├── slashCommands.js           # /help、/cd、/new 等斜杠命令
+│   └── wsServer.js                # WebSocket 连接、消息分发和 session 生命周期
+├── server.js                      # 兼容 npm start 的入口
+├── package.json
+└── package-lock.json
+```
+
+## 开发命令
+
+```bash
+npm install
+npm start
+node bin/linco.js --help
+node bin/linco.js doctor
+```
+
+当前项目没有配置测试、lint 或构建脚本。