ishenwei/nexus
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update nexus: fix conflicts and sync local changes

Browse Source
This commit is contained in:
Shen Wei
2026-04-26 12:06:50 +08:00
parent 191797c01b
commit f09834b5a5
2443 changed files with 254323 additions and 255154 deletions
Download Patch File Download Diff File Expand all files Collapse all files

414
openclaw/xingyao/documentation/OPENCLAW-CONFIG.md
View File

@@ -1,207 +1,207 @@
---
title: OpenClaw 完整配置文档
source:
author: shenwei
published:
created:
description:
tags: []
---
# OpenClaw 完整配置文档
> 最后更新: 2026-03-15 20:30
---
## 1. 概览
- **版本**: 2026.3.13
- **Gateway 状态**: 运行中 (pid 30771)
- **Gateway 端口**: 18789
- **绑定地址**: 127.0.0.1 (loopback)
- **配置文件**: ~/.openclaw/openclaw.json
---
## 2. Agent 列表
| Agent ID | 名称 | Workspace | 模型 | 路由规则 |
|----------|------|-----------|------|----------|
| main | (默认) | ~/.openclaw/workspace | MiniMax-M2.5 | 0 (默认) |
| xinghui | 星辉 | ~/.openclaw/workspace-agent-xinghui | MiniMax-M2.5 | 1 (telegram bot1) |
| xingyao | 星曜 | ~/.openclaw/workspace-agent-xingyao | MiniMax-M2.5 | 1 (telegram bot2) |
### 2.1 路由绑定 (Bindings)
| Agent | 匹配条件 |
|-------|----------|
| xinghui | channel: telegram, accountId: bot1 |
| xingyao | channel: telegram, accountId: bot2 |
---
## 3. Workspace 目录
| Workspace | 路径 | 说明 |
|-----------|------|------|
| main | ~/.openclaw/workspace | 默认工作空间 |
| xinghui | ~/.openclaw/workspace-agent-xinghui | 星辉工作空间 |
| xingyao | ~/.openclaw/workspace-agent-xingyao | 星曜工作空间 |
---
## 4. 可用模型 (Models)
### 4.1 MiniMax Portal
| 模型 ID | 名称 | 上下文窗口 | 最大输出 | 思考模式 |
|---------|------|-----------|---------|----------|
| MiniMax-M2.5 | MiniMax M2.5 | 200K | 8192 | 否 |
| MiniMax-M2.5-highspeed | MiniMax M2.5 Highspeed | 200K | 8192 | 是 |
| MiniMax-M2.5-Lightning | MiniMax M2.5 Lightning | 200K | 8192 | 是 |
### 4.2 DeepSeek (自定义 Provider)
| 模型 ID | 名称 | 上下文窗口 | 最大输出 |
|---------|------|-----------|---------|
| deepseek-reasoner | deepseek-reasoner | 16K | 4096 |
| deepseek-chat | deepseek-chat | 16K | 4096 |
### 4.3 默认模型配置
- **主模型**: minimax-portal/MiniMax-M2.5
- **备用模型**:
1. custom-api-deepseek-reasoner/deepseek-reasoner
2. custom-api-deepseek-chat/deepseek-chat
3. minimax-portal/MiniMax-M2.5-highspeed
4. minimax-portal/MiniMax-M2.5-Lightning
---
## 5. 频道 (Channels)
### 5.1 Telegram 配置
| Account | Bot Token | DM策略 | 群组策略 | 状态 |
|---------|-----------|--------|----------|------|
| default | 8414432613:AAG9hvKfILGSsbc1EMEZW1QVym9Quc5aHWk | pairing | open | 已配置 |
| bot1 | 8709222939:AAEfvZrvvU5vZFsmacsR5nmpkJ2Jb5JgfRg | pairing | allowlist | 已配置 |
| bot2 | 8414432613:AAG9hvKfILGSsbc1EMEZW1QVym9Quc5aHWk | pairing | allowlist | 已配置 |
### 5.2 全局 Telegram 配置
- **全局代理**: http://127.0.0.1:10808 (科学上网)
- **群组策略**: allowlist (⚠️ 需配置 groupAllowFrom)
- **流式传输**: partial
### 5.3 待修复问题
⚠️ **警告**: 以下 account 的 groupPolicy 是 allowlist，但 groupAllowFrom 为空，会导致群消息被静默丢弃：
- channels.telegram (全局)
- channels.telegram.accounts.bot1
- channels.telegram.accounts.bot2
**解决方案**: 添加 sender IDs 到 groupAllowFrom，或将 groupPolicy 改为 "open"
---
## 6. 已安装技能 (Skills)
| 技能名称 | 路径 | 状态 |
|----------|------|------|
| accli | ~/.openclaw/skills/accli | ✅ 已安装 |
| apple-notes | ~/.openclaw/skills/apple-notes | ✅ 已安装 |
| apple-reminders | ~/.openclaw/skills/apple-reminders | ✅ 已安装 |
| gog | ~/.openclaw/skills/gog | ✅ 已安装 |
| ontology | ~/.openclaw/skills/ontology | ✅ 已安装 |
| self-improving-agent | ~/.openclaw/skills/self-improving-agent | ✅ 已安装 |
---
## 7. 认证 (Auth)
### 7.1 Auth Providers
| Provider | 模式 | 说明 |
|----------|------|------|
| minimax-portal | oauth | MiniMax OAuth 认证 |
---
## 8. Gateway 配置
| 配置项 | 值 |
|--------|-----|
| 端口 | 18789 |
| 模式 | local |
| 绑定 | loopback (127.0.0.1) |
| 认证模式 | token |
| Tailscale | off |
### 8.1 禁止命令 (Deny Commands)
以下命令在节点上被禁止执行：
- camera.snap
- camera.clip
- screen.record
- contacts.add
- calendar.add
- reminders.add
- sms.send
---
## 9. 插件 (Plugins)
| 插件 | 状态 |
|------|------|
| telegram | ✅ 启用 |
| minimax-portal-auth | ✅ 启用 |
---
## 10. 文件结构
```
~/.openclaw/
├── openclaw.json # 主配置文件
├── agents/ # Agent 目录
│ ├── main/agent/
│ ├── xinghui/agent/
│ └── xingyao/agent/
├── workspace/ # main 工作空间
├── workspace-agent-xinghui/ # 星辉工作空间
├── workspace-agent-xingyao/ # 星曜工作空间
├── skills/ # 已安装技能
├── credentials/ # 凭证存储
├── devices/ # 设备配置
├── cron/ # 定时任务
├── logs/ # 日志文件
└── telegram/ # Telegram 数据
```
---
## 11. 常用命令
```bash
# 查看所有 Agent
openclaw agents list
# 查看 Agent 绑定
openclaw agents list --bindings
# 查看频道状态
openclaw channels list
# 查看 Gateway 状态
openclaw gateway status
# 重新启动 Gateway
openclaw gateway restart
```
---
*文档生成时间: 2026-03-15 20:30*
---
title: OpenClaw 完整配置文档
source:
author: shenwei
published:
created:
description:
tags: []
---
# OpenClaw 完整配置文档
> 最后更新: 2026-03-15 20:30
---
## 1. 概览
- **版本**: 2026.3.13
- **Gateway 状态**: 运行中 (pid 30771)
- **Gateway 端口**: 18789
- **绑定地址**: 127.0.0.1 (loopback)
- **配置文件**: ~/.openclaw/openclaw.json
---
## 2. Agent 列表
| Agent ID | 名称 | Workspace | 模型 | 路由规则 |
|----------|------|-----------|------|----------|
| main | (默认) | ~/.openclaw/workspace | MiniMax-M2.5 | 0 (默认) |
| xinghui | 星辉 | ~/.openclaw/workspace-agent-xinghui | MiniMax-M2.5 | 1 (telegram bot1) |
| xingyao | 星曜 | ~/.openclaw/workspace-agent-xingyao | MiniMax-M2.5 | 1 (telegram bot2) |
### 2.1 路由绑定 (Bindings)
| Agent | 匹配条件 |
|-------|----------|
| xinghui | channel: telegram, accountId: bot1 |
| xingyao | channel: telegram, accountId: bot2 |
---
## 3. Workspace 目录
| Workspace | 路径 | 说明 |
|-----------|------|------|
| main | ~/.openclaw/workspace | 默认工作空间 |
| xinghui | ~/.openclaw/workspace-agent-xinghui | 星辉工作空间 |
| xingyao | ~/.openclaw/workspace-agent-xingyao | 星曜工作空间 |
---
## 4. 可用模型 (Models)
### 4.1 MiniMax Portal
| 模型 ID | 名称 | 上下文窗口 | 最大输出 | 思考模式 |
|---------|------|-----------|---------|----------|
| MiniMax-M2.5 | MiniMax M2.5 | 200K | 8192 | 否 |
| MiniMax-M2.5-highspeed | MiniMax M2.5 Highspeed | 200K | 8192 | 是 |
| MiniMax-M2.5-Lightning | MiniMax M2.5 Lightning | 200K | 8192 | 是 |
### 4.2 DeepSeek (自定义 Provider)
| 模型 ID | 名称 | 上下文窗口 | 最大输出 |
|---------|------|-----------|---------|
| deepseek-reasoner | deepseek-reasoner | 16K | 4096 |
| deepseek-chat | deepseek-chat | 16K | 4096 |
### 4.3 默认模型配置
- **主模型**: minimax-portal/MiniMax-M2.5
- **备用模型**:
1. custom-api-deepseek-reasoner/deepseek-reasoner
2. custom-api-deepseek-chat/deepseek-chat
3. minimax-portal/MiniMax-M2.5-highspeed
4. minimax-portal/MiniMax-M2.5-Lightning
---
## 5. 频道 (Channels)
### 5.1 Telegram 配置
| Account | Bot Token | DM策略 | 群组策略 | 状态 |
|---------|-----------|--------|----------|------|
| default | 8414432613:AAG9hvKfILGSsbc1EMEZW1QVym9Quc5aHWk | pairing | open | 已配置 |
| bot1 | 8709222939:AAEfvZrvvU5vZFsmacsR5nmpkJ2Jb5JgfRg | pairing | allowlist | 已配置 |
| bot2 | 8414432613:AAG9hvKfILGSsbc1EMEZW1QVym9Quc5aHWk | pairing | allowlist | 已配置 |
### 5.2 全局 Telegram 配置
- **全局代理**: http://127.0.0.1:10808 (科学上网)
- **群组策略**: allowlist (⚠️ 需配置 groupAllowFrom)
- **流式传输**: partial
### 5.3 待修复问题
⚠️ **警告**: 以下 account 的 groupPolicy 是 allowlist，但 groupAllowFrom 为空，会导致群消息被静默丢弃：
- channels.telegram (全局)
- channels.telegram.accounts.bot1
- channels.telegram.accounts.bot2
**解决方案**: 添加 sender IDs 到 groupAllowFrom，或将 groupPolicy 改为 "open"
---
## 6. 已安装技能 (Skills)
| 技能名称 | 路径 | 状态 |
|----------|------|------|
| accli | ~/.openclaw/skills/accli | ✅ 已安装 |
| apple-notes | ~/.openclaw/skills/apple-notes | ✅ 已安装 |
| apple-reminders | ~/.openclaw/skills/apple-reminders | ✅ 已安装 |
| gog | ~/.openclaw/skills/gog | ✅ 已安装 |
| ontology | ~/.openclaw/skills/ontology | ✅ 已安装 |
| self-improving-agent | ~/.openclaw/skills/self-improving-agent | ✅ 已安装 |
---
## 7. 认证 (Auth)
### 7.1 Auth Providers
| Provider | 模式 | 说明 |
|----------|------|------|
| minimax-portal | oauth | MiniMax OAuth 认证 |
---
## 8. Gateway 配置
| 配置项 | 值 |
|--------|-----|
| 端口 | 18789 |
| 模式 | local |
| 绑定 | loopback (127.0.0.1) |
| 认证模式 | token |
| Tailscale | off |
### 8.1 禁止命令 (Deny Commands)
以下命令在节点上被禁止执行：
- camera.snap
- camera.clip
- screen.record
- contacts.add
- calendar.add
- reminders.add
- sms.send
---
## 9. 插件 (Plugins)
| 插件 | 状态 |
|------|------|
| telegram | ✅ 启用 |
| minimax-portal-auth | ✅ 启用 |
---
## 10. 文件结构
```
~/.openclaw/
├── openclaw.json # 主配置文件
├── agents/ # Agent 目录
│ ├── main/agent/
│ ├── xinghui/agent/
│ └── xingyao/agent/
├── workspace/ # main 工作空间
├── workspace-agent-xinghui/ # 星辉工作空间
├── workspace-agent-xingyao/ # 星曜工作空间
├── skills/ # 已安装技能
├── credentials/ # 凭证存储
├── devices/ # 设备配置
├── cron/ # 定时任务
├── logs/ # 日志文件
└── telegram/ # Telegram 数据
```
---
## 11. 常用命令
```bash
# 查看所有 Agent
openclaw agents list
# 查看 Agent 绑定
openclaw agents list --bindings
# 查看频道状态
openclaw channels list
# 查看 Gateway 状态
openclaw gateway status
# 重新启动 Gateway
openclaw gateway restart
```
---
*文档生成时间: 2026-03-15 20:30*

322
openclaw/xingyao/documentation/README.md
View File

@@ -1,162 +1,162 @@
---
title: 管理系统目录结构
source:
author: shenwei
published:
created:
description:
tags: []
---
# 管理系统目录结构
## 🏗️ 目录组织
这个目录用于组织和管理不同类型的系统管理工具和配置。
## 📁 目录结构
```
managed-systems/
├── README.md # 本文件
├── docker-management/ # Docker容器管理
│ ├── docker-apps.yaml # 应用映射配置
│ ├── docker-config-editor.sh # 配置编辑工具
│ ├── DOCKER_CONFIG_EDITOR_GUIDE.md # 配置编辑指南
│ └── docker-command-processor.md # 自然语言指令处理器
├── ssh-management/ # SSH连接管理（预留）
├── monitoring-management/ # 监控系统管理（预留）
└── documentation/ # 文档和指南（预留）
```
## 🎯 设计理念
### 1. 模块化组织
- 每个系统类型有独立的目录
- 相关工具和配置放在一起
- 便于扩展和维护
### 2. 清晰的命名
- 目录名：`[系统类型]-management`
- 文件名：描述性名称，易于理解
- 扩展名：表明文件类型和用途
### 3. 可扩展性
- 预留目录用于未来扩展
- 标准化的文件结构
- 易于添加新的管理系统
## 🚀 当前实现
### Docker管理系统
**位置**: `docker-management/`
**功能**:
1. **应用发现和映射** (`docker-apps.yaml`)
- 记录所有服务器上的Docker应用
- 包含路径、服务器、描述信息
2. **配置编辑工具** (`docker-config-editor.sh`)
- 安全地编辑docker-compose.yml文件
- 自动备份和验证
- 支持查看、备份、验证、重启操作
3. **使用指南** (`DOCKER_CONFIG_EDITOR_GUIDE.md`)
- 详细的工作流程说明
- 安全编辑步骤
- 故障排除指南
4. **自然语言接口** (`docker-command-processor.md`)
- 理解自然语言指令
- 映射到具体命令执行
## 🔄 工作流程
### Docker管理流程
```
1. 指令解析 → 2. 配置查找 → 3. 命令执行 → 4. 结果反馈
```
### 安全编辑流程
```
1. 查看当前配置 → 2. 创建备份 → 3. 编辑文件 → 4. 验证格式 → 5. 重启应用
```
## 📋 服务器配置
### 服务器路径映射
| 服务器 | Docker路径 | 应用示例 |
|--------|------------|----------|
| ubuntu1 | `/home/shenwei/Docker/` | portainer, rsshub, it-tools |
| ubuntu2 | `/home/shenwei/docker/` | cloudflared, uptime-kuma |
| NAS | `/volume1/docker/` | navidrome, mysql80 |
### 应用统计
- **总服务器**: 3台
- **总应用**: 16个
- **最后扫描**: 2026-03-13
## 🔮 未来扩展
### 计划中的管理系统
1. **SSH管理系统**
- SSH连接配置管理
- 密钥管理和轮换
- 连接测试和监控
2. **监控管理系统**
- Prometheus配置管理
- Grafana仪表板管理
- 告警规则配置
3. **备份管理系统**
- 备份策略配置
- 备份计划管理
- 恢复测试流程
### 通用模式
每个管理系统遵循相似的模式：
1. 配置发现和映射
2. 安全操作工具
3. 使用指南文档
4. 自然语言接口
## 📝 维护指南
### 添加新系统
1. 创建新目录：`[系统名]-management/`
2. 添加配置文件、工具、文档
3. 更新本README文件
4. 测试功能完整性
### 更新现有系统
1. 在相应目录中更新文件
2. 更新版本和日期信息
3. 测试向后兼容性
4. 更新相关文档
### 备份策略
- 重要配置文件定期备份
- 工具脚本版本控制
- 文档更新记录
## 🏆 最佳实践
### 文件命名
- 使用小写字母和连字符
- 描述性文件名
- 一致的扩展名
### 文档标准
- 每个目录有README文件
- 工具脚本有使用说明
- 配置文件有注释说明
### 安全考虑
- 敏感信息不存储在配置文件中
- 操作前备份重要文件
- 验证操作结果
## 📊 版本信息
- **创建时间**: 2026-03-13
- **最后更新**: 2026-03-13
- **版本**: 1.0.0
---
title: 管理系统目录结构
source:
author: shenwei
published:
created:
description:
tags: []
---
# 管理系统目录结构
## 🏗️ 目录组织
这个目录用于组织和管理不同类型的系统管理工具和配置。
## 📁 目录结构
```
managed-systems/
├── README.md # 本文件
├── docker-management/ # Docker容器管理
│ ├── docker-apps.yaml # 应用映射配置
│ ├── docker-config-editor.sh # 配置编辑工具
│ ├── DOCKER_CONFIG_EDITOR_GUIDE.md # 配置编辑指南
│ └── docker-command-processor.md # 自然语言指令处理器
├── ssh-management/ # SSH连接管理（预留）
├── monitoring-management/ # 监控系统管理（预留）
└── documentation/ # 文档和指南（预留）
```
## 🎯 设计理念
### 1. 模块化组织
- 每个系统类型有独立的目录
- 相关工具和配置放在一起
- 便于扩展和维护
### 2. 清晰的命名
- 目录名：`[系统类型]-management`
- 文件名：描述性名称，易于理解
- 扩展名：表明文件类型和用途
### 3. 可扩展性
- 预留目录用于未来扩展
- 标准化的文件结构
- 易于添加新的管理系统
## 🚀 当前实现
### Docker管理系统
**位置**: `docker-management/`
**功能**:
1. **应用发现和映射** (`docker-apps.yaml`)
- 记录所有服务器上的Docker应用
- 包含路径、服务器、描述信息
2. **配置编辑工具** (`docker-config-editor.sh`)
- 安全地编辑docker-compose.yml文件
- 自动备份和验证
- 支持查看、备份、验证、重启操作
3. **使用指南** (`DOCKER_CONFIG_EDITOR_GUIDE.md`)
- 详细的工作流程说明
- 安全编辑步骤
- 故障排除指南
4. **自然语言接口** (`docker-command-processor.md`)
- 理解自然语言指令
- 映射到具体命令执行
## 🔄 工作流程
### Docker管理流程
```
1. 指令解析 → 2. 配置查找 → 3. 命令执行 → 4. 结果反馈
```
### 安全编辑流程
```
1. 查看当前配置 → 2. 创建备份 → 3. 编辑文件 → 4. 验证格式 → 5. 重启应用
```
## 📋 服务器配置
### 服务器路径映射
| 服务器 | Docker路径 | 应用示例 |
|--------|------------|----------|
| ubuntu1 | `/home/shenwei/Docker/` | portainer, rsshub, it-tools |
| ubuntu2 | `/home/shenwei/docker/` | cloudflared, uptime-kuma |
| NAS | `/volume1/docker/` | navidrome, mysql80 |
### 应用统计
- **总服务器**: 3台
- **总应用**: 16个
- **最后扫描**: 2026-03-13
## 🔮 未来扩展
### 计划中的管理系统
1. **SSH管理系统**
- SSH连接配置管理
- 密钥管理和轮换
- 连接测试和监控
2. **监控管理系统**
- Prometheus配置管理
- Grafana仪表板管理
- 告警规则配置
3. **备份管理系统**
- 备份策略配置
- 备份计划管理
- 恢复测试流程
### 通用模式
每个管理系统遵循相似的模式：
1. 配置发现和映射
2. 安全操作工具
3. 使用指南文档
4. 自然语言接口
## 📝 维护指南
### 添加新系统
1. 创建新目录：`[系统名]-management/`
2. 添加配置文件、工具、文档
3. 更新本README文件
4. 测试功能完整性
### 更新现有系统
1. 在相应目录中更新文件
2. 更新版本和日期信息
3. 测试向后兼容性
4. 更新相关文档
### 备份策略
- 重要配置文件定期备份
- 工具脚本版本控制
- 文档更新记录
## 🏆 最佳实践
### 文件命名
- 使用小写字母和连字符
- 描述性文件名
- 一致的扩展名
### 文档标准
- 每个目录有README文件
- 工具脚本有使用说明
- 配置文件有注释说明
### 安全考虑
- 敏感信息不存储在配置文件中
- 操作前备份重要文件
- 验证操作结果
## 📊 版本信息
- **创建时间**: 2026-03-13
- **最后更新**: 2026-03-13
- **版本**: 1.0.0
- **维护者**: 星曜 (OpenClaw助手)

624
openclaw/xingyao/documentation/file-editing-best-practices.md
View File

@@ -1,313 +1,313 @@
# 文件编辑最佳实践指南
## 📋 概述
本文档总结了在OpenClaw环境中安全、可靠地编辑文件的最佳实践，基于今天（2026-03-13）多次编辑失败的经验教训。
## 🎯 核心原则
### 1. 安全第一
- **备份优先**：编辑前必须备份
- **最小修改**：只修改必要的部分
- **可回滚**：确保可以恢复到之前状态
### 2. 可靠性优先
- **验证匹配**：编辑前验证文本存在
- **逐步操作**：小步修改，逐步验证
- **错误处理**：准备好失败处理方案
### 3. 效率兼顾
- **选择正确工具**：根据场景选择`edit`或`write`
- **自动化重复操作**：创建脚本处理常见编辑
- **文档化流程**：记录成功的工作流程
## 🛠️ 工具选择指南
### 何时使用 `edit` 工具
**适用场景**：
- 小范围、精确的文本替换
- 配置文件中的特定值修改
- 模板文件中的变量替换
**使用条件**：
- 能100%确定匹配文本
- 文件内容在编辑期间不会变化
- 不需要改变文件格式
**示例**：
```bash
# 修改配置文件中的端口号
edit config.yaml "port: 8080" "port: 9090"
```
### 何时使用 `write` 工具
**适用场景**：
- 创建新文件
- 完全重写文件
- 大范围内容修改
- 格式标准化
**优势**：
- 避免匹配问题
- 确保格式一致
- 简单可靠
**示例**：
```bash
# 重新创建配置文件
write config.yaml "完整的配置文件内容"
```
## 📝 标准编辑流程
### 步骤1：准备工作
```bash
# 1.1 备份原文件
cp file.md file.md.$(date +%Y%m%d_%H%M%S).backup
# 1.2 检查文件状态
ls -la file.md
file file.md # 检查文件类型
# 1.3 查看精确内容
cat -A file.md | head -20 # 查看包括特殊字符
```
### 步骤2：验证匹配
```bash
# 2.1 检查要编辑的文本是否存在
grep -n "要匹配的文本" file.md
# 2.2 检查匹配次数（应该是1次）
grep -c "要匹配的文本" file.md
# 2.3 查看上下文
grep -A2 -B2 "要匹配的文本" file.md | cat -A
```
### 步骤3：执行编辑
```bash
# 3.1 小范围编辑（推荐）
edit file.md "精确匹配的文本" "新的文本"
# 3.2 或重新创建文件
write file.md "完整的新内容"
```
### 步骤4：验证结果
```bash
# 4.1 检查文件完整性
ls -la file.md # 文件大小合理
head -5 file.md # 内容开头正确
# 4.2 验证关键内容存在
grep "关键内容" file.md
# 4.3 与备份比较
diff file.md.backup file.md | head -20
```
### 步骤5：清理和记录
```bash
# 5.1 记录编辑操作
echo "$(date): 编辑file.md - 修改了X处" >> edit-log.md
# 5.2 清理临时备份（可选）---
title: 文件编辑最佳实践指南
author: shenwei
---
---
title: 文件编辑最佳实践指南
source:
author: shenwei
published:
created:
description:
tags: []
---
# rm file.md.backup # 确认无误后再删除
```
## 🔧 高级技巧
### 处理换行符问题
```bash
# 检测换行符类型
file file.md
# 输出: ASCII text 或 ASCII text, with CRLF line terminators
# 转换为Unix换行符
sed -i 's/\r$//' file.md
# 转换为DOS换行符
sed -i 's/$/\r/' file.md
```
### 处理空格和制表符
```bash
# 查看不可见字符
cat -A file.md | grep -n "要编辑的行"
# 标准化空格（制表符转空格）
expand -t 4 file.md > file.md.new && mv file.md.new file.md
# 标准化制表符（空格转制表符）
unexpand -t 4 file.md > file.md.new && mv file.md.new file.md
```
### 使用脚本自动化
```bash
#!/bin/bash
# safe-edit.sh - 安全的文件编辑脚本
FILE="$1"
OLD_TEXT="$2"
NEW_TEXT="$3"
# 备份
BACKUP="${FILE}.backup.$(date +%s)"
cp "$FILE" "$BACKUP"
# 验证匹配
MATCH_COUNT=$(grep -c "$OLD_TEXT" "$FILE")
if [ "$MATCH_COUNT" -eq 0 ]; then
echo "错误：未找到匹配文本"
exit 1
elif [ "$MATCH_COUNT" -gt 1 ]; then
echo "警告：找到 $MATCH_COUNT 处匹配，可能不精确"
fi
# 执行编辑
edit "$FILE" "$OLD_TEXT" "$NEW_TEXT"
# 验证结果
if [ $? -eq 0 ]; then
echo "✅ 编辑成功"
# 可选：清理备份
# rm "$BACKUP"
else
echo "❌ 编辑失败，恢复备份"
cp "$BACKUP" "$FILE"
exit 1
fi
```
## ⚠️ 常见问题与解决方案
### 问题1：`edit`工具失败
**症状**：`Edit: in ... failed`
**原因**：文本不匹配（换行符、空格、内容变化）
**解决**：
1. 使用`write`重新创建文件
2. 或使用更精确的匹配文本
3. 或先备份再尝试
### 问题2：权限不足
**症状**：`Permission denied`
**原因**：文件权限设置
**解决**：
```bash
# 检查权限
ls -la file.md
# 临时修改权限（谨慎使用）
chmod +w file.md
# 编辑后恢复权限
chmod 644 file.md
```
### 问题3：文件被锁定
**症状**：`Resource busy` 或编辑后内容恢复
**原因**：其他进程正在使用文件
**解决**：
```bash
# 检查哪个进程在使用
lsof file.md
# 等待或停止相关进程
# 或复制到临时文件编辑
cp file.md file.md.tmp
edit file.md.tmp "old" "new"
mv file.md.tmp file.md
```
## 📊 编辑策略选择矩阵
| 场景 | 推荐工具 | 备份策略 | 验证级别 |
|------|----------|----------|----------|
| 小修改 | `edit` | 自动备份 | 中等 |
| 大修改 | `write` | 手动备份 | 高 |
| 关键文件 | `write` + 版本控制 | 多重备份 | 最高 |
| 模板文件 | 模板系统 | 版本控制 | 中等 |
| 批量编辑 | 脚本 | 完整备份 | 高 |
## 🎓 经验教训
### 从今天错误中学到的
1. **不要假设文件内容**：总是先验证
2. **换行符是隐形杀手**：使用`cat -A`查看
3. **备份是救命稻草**：今天备份救了两次
4. **简单往往更好**：`write`比`edit`更可靠
### 成功模式
1. **测试驱动编辑**：先在小文件测试
2. **增量修改**：一次只改一处
3. **即时验证**：编辑后立即检查
4. **文档记录**：记录什么方法有效
## 🔮 未来改进方向
### 工具增强
1. **智能`edit`工具**：支持模糊匹配
2. **编辑预览**：显示编辑前后的差异
3. **批量操作**：支持多文件同时编辑
4. **版本集成**：与Git等版本控制系统集成
### 流程优化
1. **标准化编辑模板**：创建可重用的编辑脚本
2. **编辑审计日志**：记录所有编辑操作
3. **自动恢复系统**：失败时自动回滚
4. **协作编辑支持**：多用户安全编辑
### 培训和教育
1. **新手指南**：文件编辑入门教程
2. **案例研究**：成功和失败的编辑案例
3. **最佳实践库**：收集和分享有效方法
4. **社区贡献**：鼓励用户分享技巧
## ✅ 检查清单
### 编辑前检查
- [ ] 文件已备份
- [ ] 权限正确
- [ ] 内容已验证
- [ ] 匹配文本精确
- [ ] 有回滚计划
### 编辑后检查
- [ ] 文件大小合理
- [ ] 关键内容存在
- [ ] 格式正确
- [ ] 备份可恢复
- [ ] 记录编辑操作
## 📞 支持资源
### 内部文档
- `file-editing-best-practices.md`（本文档）
- `learnings/2026-03-14-file-edit-failure.md`（错误分析）
- `scripts/safe-edit.sh`（安全编辑脚本）
### 外部参考
- OpenClaw文档：文件操作工具
- Unix文本处理工具手册
- 版本控制系统最佳实践
---
**版本**: 1.0
**创建日期**: 2026-03-14
**最后更新**: 2026-03-14 00:25 GMT+8
**作者**: 星曜 (OpenClaw助手)
# 文件编辑最佳实践指南
## 📋 概述
本文档总结了在OpenClaw环境中安全、可靠地编辑文件的最佳实践，基于今天（2026-03-13）多次编辑失败的经验教训。
## 🎯 核心原则
### 1. 安全第一
- **备份优先**：编辑前必须备份
- **最小修改**：只修改必要的部分
- **可回滚**：确保可以恢复到之前状态
### 2. 可靠性优先
- **验证匹配**：编辑前验证文本存在
- **逐步操作**：小步修改，逐步验证
- **错误处理**：准备好失败处理方案
### 3. 效率兼顾
- **选择正确工具**：根据场景选择`edit`或`write`
- **自动化重复操作**：创建脚本处理常见编辑
- **文档化流程**：记录成功的工作流程
## 🛠️ 工具选择指南
### 何时使用 `edit` 工具
**适用场景**：
- 小范围、精确的文本替换
- 配置文件中的特定值修改
- 模板文件中的变量替换
**使用条件**：
- 能100%确定匹配文本
- 文件内容在编辑期间不会变化
- 不需要改变文件格式
**示例**：
```bash
# 修改配置文件中的端口号
edit config.yaml "port: 8080" "port: 9090"
```
### 何时使用 `write` 工具
**适用场景**：
- 创建新文件
- 完全重写文件
- 大范围内容修改
- 格式标准化
**优势**：
- 避免匹配问题
- 确保格式一致
- 简单可靠
**示例**：
```bash
# 重新创建配置文件
write config.yaml "完整的配置文件内容"
```
## 📝 标准编辑流程
### 步骤1：准备工作
```bash
# 1.1 备份原文件
cp file.md file.md.$(date +%Y%m%d_%H%M%S).backup
# 1.2 检查文件状态
ls -la file.md
file file.md # 检查文件类型
# 1.3 查看精确内容
cat -A file.md | head -20 # 查看包括特殊字符
```
### 步骤2：验证匹配
```bash
# 2.1 检查要编辑的文本是否存在
grep -n "要匹配的文本" file.md
# 2.2 检查匹配次数（应该是1次）
grep -c "要匹配的文本" file.md
# 2.3 查看上下文
grep -A2 -B2 "要匹配的文本" file.md | cat -A
```
### 步骤3：执行编辑
```bash
# 3.1 小范围编辑（推荐）
edit file.md "精确匹配的文本" "新的文本"
# 3.2 或重新创建文件
write file.md "完整的新内容"
```
### 步骤4：验证结果
```bash
# 4.1 检查文件完整性
ls -la file.md # 文件大小合理
head -5 file.md # 内容开头正确
# 4.2 验证关键内容存在
grep "关键内容" file.md
# 4.3 与备份比较
diff file.md.backup file.md | head -20
```
### 步骤5：清理和记录
```bash
# 5.1 记录编辑操作
echo "$(date): 编辑file.md - 修改了X处" >> edit-log.md
# 5.2 清理临时备份（可选）---
title: 文件编辑最佳实践指南
author: shenwei
---
---
title: 文件编辑最佳实践指南
source:
author: shenwei
published:
created:
description:
tags: []
---
# rm file.md.backup # 确认无误后再删除
```
## 🔧 高级技巧
### 处理换行符问题
```bash
# 检测换行符类型
file file.md
# 输出: ASCII text 或 ASCII text, with CRLF line terminators
# 转换为Unix换行符
sed -i 's/\r$//' file.md
# 转换为DOS换行符
sed -i 's/$/\r/' file.md
```
### 处理空格和制表符
```bash
# 查看不可见字符
cat -A file.md | grep -n "要编辑的行"
# 标准化空格（制表符转空格）
expand -t 4 file.md > file.md.new && mv file.md.new file.md
# 标准化制表符（空格转制表符）
unexpand -t 4 file.md > file.md.new && mv file.md.new file.md
```
### 使用脚本自动化
```bash
#!/bin/bash
# safe-edit.sh - 安全的文件编辑脚本
FILE="$1"
OLD_TEXT="$2"
NEW_TEXT="$3"
# 备份
BACKUP="${FILE}.backup.$(date +%s)"
cp "$FILE" "$BACKUP"
# 验证匹配
MATCH_COUNT=$(grep -c "$OLD_TEXT" "$FILE")
if [ "$MATCH_COUNT" -eq 0 ]; then
echo "错误：未找到匹配文本"
exit 1
elif [ "$MATCH_COUNT" -gt 1 ]; then
echo "警告：找到 $MATCH_COUNT 处匹配，可能不精确"
fi
# 执行编辑
edit "$FILE" "$OLD_TEXT" "$NEW_TEXT"
# 验证结果
if [ $? -eq 0 ]; then
echo "✅ 编辑成功"
# 可选：清理备份
# rm "$BACKUP"
else
echo "❌ 编辑失败，恢复备份"
cp "$BACKUP" "$FILE"
exit 1
fi
```
## ⚠️ 常见问题与解决方案
### 问题1：`edit`工具失败
**症状**：`Edit: in ... failed`
**原因**：文本不匹配（换行符、空格、内容变化）
**解决**：
1. 使用`write`重新创建文件
2. 或使用更精确的匹配文本
3. 或先备份再尝试
### 问题2：权限不足
**症状**：`Permission denied`
**原因**：文件权限设置
**解决**：
```bash
# 检查权限
ls -la file.md
# 临时修改权限（谨慎使用）
chmod +w file.md
# 编辑后恢复权限
chmod 644 file.md
```
### 问题3：文件被锁定
**症状**：`Resource busy` 或编辑后内容恢复
**原因**：其他进程正在使用文件
**解决**：
```bash
# 检查哪个进程在使用
lsof file.md
# 等待或停止相关进程
# 或复制到临时文件编辑
cp file.md file.md.tmp
edit file.md.tmp "old" "new"
mv file.md.tmp file.md
```
## 📊 编辑策略选择矩阵
| 场景 | 推荐工具 | 备份策略 | 验证级别 |
|------|----------|----------|----------|
| 小修改 | `edit` | 自动备份 | 中等 |
| 大修改 | `write` | 手动备份 | 高 |
| 关键文件 | `write` + 版本控制 | 多重备份 | 最高 |
| 模板文件 | 模板系统 | 版本控制 | 中等 |
| 批量编辑 | 脚本 | 完整备份 | 高 |
## 🎓 经验教训
### 从今天错误中学到的
1. **不要假设文件内容**：总是先验证
2. **换行符是隐形杀手**：使用`cat -A`查看
3. **备份是救命稻草**：今天备份救了两次
4. **简单往往更好**：`write`比`edit`更可靠
### 成功模式
1. **测试驱动编辑**：先在小文件测试
2. **增量修改**：一次只改一处
3. **即时验证**：编辑后立即检查
4. **文档记录**：记录什么方法有效
## 🔮 未来改进方向
### 工具增强
1. **智能`edit`工具**：支持模糊匹配
2. **编辑预览**：显示编辑前后的差异
3. **批量操作**：支持多文件同时编辑
4. **版本集成**：与Git等版本控制系统集成
### 流程优化
1. **标准化编辑模板**：创建可重用的编辑脚本
2. **编辑审计日志**：记录所有编辑操作
3. **自动恢复系统**：失败时自动回滚
4. **协作编辑支持**：多用户安全编辑
### 培训和教育
1. **新手指南**：文件编辑入门教程
2. **案例研究**：成功和失败的编辑案例
3. **最佳实践库**：收集和分享有效方法
4. **社区贡献**：鼓励用户分享技巧
## ✅ 检查清单
### 编辑前检查
- [ ] 文件已备份
- [ ] 权限正确
- [ ] 内容已验证
- [ ] 匹配文本精确
- [ ] 有回滚计划
### 编辑后检查
- [ ] 文件大小合理
- [ ] 关键内容存在
- [ ] 格式正确
- [ ] 备份可恢复
- [ ] 记录编辑操作
## 📞 支持资源
### 内部文档
- `file-editing-best-practices.md`（本文档）
- `learnings/2026-03-14-file-edit-failure.md`（错误分析）
- `scripts/safe-edit.sh`（安全编辑脚本）
### 外部参考
- OpenClaw文档：文件操作工具
- Unix文本处理工具手册
- 版本控制系统最佳实践
---
**版本**: 1.0
**创建日期**: 2026-03-14
**最后更新**: 2026-03-14 00:25 GMT+8
**作者**: 星曜 (OpenClaw助手)
**状态**: ✅ 生效中