From b37ebb3db17c2870625ee484f334bf609882a902 Mon Sep 17 00:00:00 2001 From: zhi Date: Thu, 5 Mar 2026 09:38:38 +0000 Subject: [PATCH] docs: add bilingual README with language switcher - Update README.md to English version with language navigation - Add README.zh-CN.md for Simplified Chinese - Add language switcher links in both files --- README.md | 103 ++++++++++++++++++++---------------- README.zh-CN.md | 138 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 195 insertions(+), 46 deletions(-) create mode 100644 README.zh-CN.md diff --git a/README.md b/README.md index 11cf0dd..a0510a2 100644 --- a/README.md +++ b/README.md @@ -1,41 +1,47 @@ +
+ +[English](README.md) | [简体中文](README.zh-CN.md) + +
+ # PaddedCell -OpenClaw 插件：安全密码管理 + 安全执行 + 安全重启 +OpenClaw plugin for secure password management, safe command execution, and coordinated agent restart. -## 功能模块 +## Features -### 1. pass_mgr - 密码管理二进制 (Go) +### 1. pass_mgr - Password Manager Binary (Go) -使用 AES-256-GCM 加密，每个 agent 基于公私钥进行加/解密。 +AES-256-GCM encryption, per-agent key-based encryption/decryption. ```bash -# 初始化 +# Initialize pass_mgr admin init [--key-path ] -# 获取密码 +# Get password pass_mgr get [--username] -# 生成密码 (agent 可用) +# Generate password (agent can use) pass_mgr generate [--username ] -# 设置密码 (仅人类) +# Set password (human only) pass_mgr set [--username ] -# 删除密码 +# Delete password pass_mgr unset -# 轮换密码 +# Rotate password pass_mgr rotate ``` -**安全特性：** -- Agent 无法执行 `set` 操作（通过环境变量检测） -- 未初始化前所有操作报错 -- Admin 密码泄露检测（监控 message/tool calling） +**Security Features:** +- Agents cannot execute `set` (detected via environment variables) +- All operations fail before initialization +- Admin password leak detection (monitors messages/tool calls) -### 2. pcexec - 安全执行工具 (TypeScript) +### 2. pcexec - Safe Execution Tool (TypeScript) -与 OpenClaw 原生 exec 接口一致，自动处理 pass_mgr get 并脱敏输出。 +Compatible with OpenClaw native exec interface, automatically handles `pass_mgr get` and sanitizes output. ```typescript import { pcexec } from 'pcexec'; @@ -44,47 +50,47 @@ const result = await pcexec('echo $(pass_mgr get mypassword)', { cwd: '/workspace', timeout: 30000, }); -// result.stdout 中密码会被替换为 ###### +// Passwords in result.stdout will be replaced with ###### ``` -### 3. safe-restart - 安全重启模块 (TypeScript) +### 3. safe-restart - Safe Restart Module (TypeScript) -提供 agent 状态管理和协调重启。 +Provides agent state management and coordinated restart. -**Agent 状态：** -- `idle` - 空闲 -- `busy` - 处理消息中 -- `focus` - 专注模式（工作流） -- `freeze` - 冻结（不接受新消息） -- `pre-freeze` - 准备冻结 -- `pre-freeze-focus` - 准备冻结（专注模式） +**Agent States:** +- `idle` - Idle +- `busy` - Processing messages +- `focus` - Focus mode (workflow) +- `freeze` - Frozen (not accepting new messages) +- `pre-freeze` - Preparing to freeze +- `pre-freeze-focus` - Preparing to freeze (focus mode) -**API：** -- `POST /query-restart` - 查询重启就绪状态 -- `POST /restart-result` - 报告重启结果 -- `GET /status` - 获取所有状态 +**APIs:** +- `POST /query-restart` - Query restart readiness +- `POST /restart-result` - Report restart result +- `GET /status` - Get all statuses -**Slash 命令：** +**Slash Commands:** ``` /padded-cell-ctrl status /padded-cell-ctrl enable pass-mgr|safe-restart /padded-cell-ctrl disable pass-mgr|safe-restart ``` -## 目录结构 +## Project Structure ``` PaddedCell/ -├── pass_mgr/ # Go 密码管理二进制 +├── pass_mgr/ # Go password manager binary │ ├── src/ │ │ └── main.go │ └── go.mod -├── pcexec/ # TypeScript 安全执行工具 +├── pcexec/ # TypeScript safe execution tool │ ├── src/ │ │ └── index.ts │ ├── package.json │ └── tsconfig.json -├── safe-restart/ # TypeScript 安全重启模块 +├── safe-restart/ # TypeScript safe restart module │ ├── src/ │ │ ├── index.ts │ │ ├── status-manager.ts @@ -93,35 +99,40 @@ PaddedCell/ │ │ └── slash-commands.ts │ ├── package.json │ └── tsconfig.json -├── docs/ # 文档 -├── PROJECT_PLAN.md # 项目计划 -├── AGENT_TASKS.md # 任务清单 -└── README.md +├── docs/ # Documentation +├── PROJECT_PLAN.md # Project plan +├── AGENT_TASKS.md # Task list +├── README.md # This file (English) +└── README.zh-CN.md # Chinese version ``` -## 开发 +## Development ```bash # Clone git clone https://git.hangman-lab.top/nav/PaddedCell.git cd PaddedCell -# Build pass_mgr (需要 Go) +# Build pass_mgr (requires Go) cd pass_mgr go build -o pass_mgr src/main.go -# Build pcexec (需要 Node.js) +# Build pcexec (requires Node.js) cd ../pcexec npm install npm run build -# Build safe-restart (需要 Node.js) +# Build safe-restart (requires Node.js) cd ../safe-restart npm install npm run build ``` -## 开发分支 +## Branches -- `main` - 主分支 -- `dev/zhi` - 当前开发分支 +- `main` - Main branch +- `dev/zhi` - Development branch + +## License + +MIT diff --git a/README.zh-CN.md b/README.zh-CN.md new file mode 100644 index 0000000..8cfa4ee --- /dev/null +++ b/README.zh-CN.md @@ -0,0 +1,138 @@ +
+ +[English](README.md) | [简体中文](README.zh-CN.md) + +
+ +# PaddedCell + +OpenClaw 插件：安全密码管理 + 安全执行 + 安全重启 + +## 功能模块 + +### 1. pass_mgr - 密码管理二进制 (Go) + +使用 AES-256-GCM 加密，每个 agent 基于公私钥进行加/解密。 + +```bash +# 初始化 +pass_mgr admin init [--key-path ] + +# 获取密码 +pass_mgr get [--username] + +# 生成密码 (agent 可用) +pass_mgr generate [--username ] + +# 设置密码 (仅人类) +pass_mgr set [--username ] + +# 删除密码 +pass_mgr unset + +# 轮换密码 +pass_mgr rotate +``` + +**安全特性：** +- Agent 无法执行 `set` 操作（通过环境变量检测） +- 未初始化前所有操作报错 +- Admin 密码泄露检测（监控 message/tool calling） + +### 2. pcexec - 安全执行工具 (TypeScript) + +与 OpenClaw 原生 exec 接口一致，自动处理 pass_mgr get 并脱敏输出。 + +```typescript +import { pcexec } from 'pcexec'; + +const result = await pcexec('echo $(pass_mgr get mypassword)', { + cwd: '/workspace', + timeout: 30000, +}); +// result.stdout 中密码会被替换为 ###### +``` + +### 3. safe-restart - 安全重启模块 (TypeScript) + +提供 agent 状态管理和协调重启。 + +**Agent 状态：** +- `idle` - 空闲 +- `busy` - 处理消息中 +- `focus` - 专注模式（工作流） +- `freeze` - 冻结（不接受新消息） +- `pre-freeze` - 准备冻结 +- `pre-freeze-focus` - 准备冻结（专注模式） + +**API：** +- `POST /query-restart` - 查询重启就绪状态 +- `POST /restart-result` - 报告重启结果 +- `GET /status` - 获取所有状态 + +**Slash 命令：** +``` +/padded-cell-ctrl status +/padded-cell-ctrl enable pass-mgr|safe-restart +/padded-cell-ctrl disable pass-mgr|safe-restart +``` + +## 项目结构 + +``` +PaddedCell/ +├── pass_mgr/ # Go 密码管理二进制 +│ ├── src/ +│ │ └── main.go +│ └── go.mod +├── pcexec/ # TypeScript 安全执行工具 +│ ├── src/ +│ │ └── index.ts +│ ├── package.json +│ └── tsconfig.json +├── safe-restart/ # TypeScript 安全重启模块 +│ ├── src/ +│ │ ├── index.ts +│ │ ├── status-manager.ts +│ │ ├── api.ts +│ │ ├── safe-restart.ts +│ │ └── slash-commands.ts +│ ├── package.json +│ └── tsconfig.json +├── docs/ # 文档 +├── PROJECT_PLAN.md # 项目计划 +├── AGENT_TASKS.md # 任务清单 +├── README.md # 英文版本 +└── README.zh-CN.md # 本文档 (简体中文) +``` + +## 开发 + +```bash +# Clone +git clone https://git.hangman-lab.top/nav/PaddedCell.git +cd PaddedCell + +# Build pass_mgr (需要 Go) +cd pass_mgr +go build -o pass_mgr src/main.go + +# Build pcexec (需要 Node.js) +cd ../pcexec +npm install +npm run build + +# Build safe-restart (需要 Node.js) +cd ../safe-restart +npm install +npm run build +``` + +## 分支 + +- `main` - 主分支 +- `dev/zhi` - 开发分支 + +## 许可证 + +MIT