### Install WxEcho using npm

Source: https://github.com/chang-xinhai/wxecho/blob/main/README_en.md

Install the WxEcho package globally using npm. This is the recommended method for quick setup.

```bash
npm install -g wxecho
```

--------------------------------

### Build WxEcho from Source

Source: https://github.com/chang-xinhai/wxecho/blob/main/README_en.md

Manually clone the repository, install dependencies, and build the project. This method is useful for development or if npm installation fails.

```bash
git clone https://github.com/chang-xinhai/WxEcho.git
cd WxEcho
npm install && npm run build
```

--------------------------------

### Log Work Example: Planned Task

Source: https://github.com/chang-xinhai/wxecho/blob/main/AGENTS.md

Example of using the log_work.sh script to log a planned task for the WxEcho project.

```bash
~/bin/log_work.sh \
  --actor claude \
  --status planned \
  --summary "设计 WxEcho 聊天年度报告功能架构" \
  --paths "landing/src/components/ chat-stat-api/" \
  --commands "" \
  --artifacts "" \
  --blockers "需先确认数据模型和 API 接口设计" \
  --next "调研 WeChat 表情包/聊天数据可视化方案"

```

--------------------------------

### Log Work Example: In Progress Task

Source: https://github.com/chang-xinhai/wxecho/blob/main/AGENTS.md

Example of using the log_work.sh script to log an in-progress task for the WxEcho project.

```bash
~/bin/log_work.sh \
  --actor claude \
  --status in_progress \
  --summary "实现年度聊天报告 React 组件" \
  --paths "landing/src/components/AnnualReport.tsx" \
  --commands "npm run dev" \
  --artifacts "~/agents/handoffs/runtime_logs/annual_report_dev.log" \
  --blockers "none" \
  --next "对接后端 API 获取统计数据"

```

--------------------------------

### Verify WxEcho CLI Installation

Source: https://github.com/chang-xinhai/wxecho/blob/main/AGENTS.md

Checks if the WxEcho CLI has been installed correctly by displaying its version.

```bash
# Verify installation
wxecho --version
```

--------------------------------

### Get WxEcho CLI Help

Source: https://github.com/chang-xinhai/wxecho/blob/main/AGENTS.md

Displays help information for the WxEcho CLI. Use `--help` with specific commands for detailed usage.

```bash
# View all available commands
wxecho --help

# View help for a specific command
wxecho export --help
wxecho decrypt --help
wxecho keys --help
```

--------------------------------

### Image CDN Usage Example

Source: https://github.com/chang-xinhai/wxecho/blob/main/AGENTS.md

Demonstrates the correct usage of raw.githubusercontent.com for loading images in Markdown, ensuring faster and global accessibility.

```markdown
<!-- 正确：使用 raw.githubusercontent.com -->
<img src="https://raw.githubusercontent.com/chang-xinhai/WxEcho/main/landing/public/screenshot.png" />

<!-- 错误：使用第三方 OSS 或其他 CDN（访问慢） -->
<img src="https://xxx.aliyuncs.com/xxx.png" />
```

--------------------------------

### Log Work Example: Done Task

Source: https://github.com/chang-xinhai/wxecho/blob/main/AGENTS.md

Example of using the log_work.sh script to log a completed task for the WxEcho project.

```bash
~/bin/log_work.sh \
  --actor claude \
  --status done \
  --summary "完成 AnnualReport 组件 v0.1，支持消息数/词云/最活跃联系人" \
  --paths "landing/src/components/AnnualReport.tsx landing/src/styles/index.css" \
  --commands "npm run build:landing" \
  --artifacts "dist/landing/annual_report.js" \
  --blockers "none" \
  --next "添加暗模式适配和动画效果"

```

--------------------------------

### Version Update Example in Markdown Table

Source: https://github.com/chang-xinhai/wxecho/blob/main/AGENTS.md

Illustrates the correct format for updating version information in a Markdown table, ensuring new versions are appended below existing ones.

```markdown
| 微信版本 | 状态 |
|----------|------|
| 4.x（最新测试：4.1.8.106） | ✅ 已测试 |
| 4.1.5.240 | ✅ 已测试 |
```

--------------------------------

### Update WxEcho CLI to Latest Version

Source: https://github.com/chang-xinhai/wxecho/blob/main/AGENTS.md

Updates the globally installed WxEcho CLI to the most recent version.

```bash
# Update to the latest version
npm update -g @walkerch/wxecho
```

--------------------------------

### Agent Task Initiation Flow

Source: https://github.com/chang-xinhai/wxecho/blob/main/AGENTS.md

Steps for initiating a task as an agent, including creating a brief, logging work, executing tasks, and updating the worklog.

```markdown
1. **创建 brief** → `~/agents/briefs/<task-name>.md`，写清楚目标、约束、验收标准
2. **创建 worklog 入口** → 用 `log_work.sh` 记录 planned 状态
3. **执行工作** → 结果写入 `~/agents/handoffs/` 或 `~/agents/scratch/`
4. **完成后更新 worklog** → 状态改为 done，summary 写明成果
5. **如有需要** → 将可复用知识沉淀到 `~/agents/context/`，将最终报告放入 `~/agents/reports/`
```

--------------------------------

### Check Environment Dependencies

Source: https://github.com/chang-xinhai/wxecho/blob/main/AGENTS.md

Verifies if all necessary environment dependencies for WxEcho are met.

```bash
# Check if environment dependencies are met
wxecho doctor
```

--------------------------------

### WxEcho Project File Structure

Source: https://github.com/chang-xinhai/wxecho/blob/main/AGENTS.md

Overview of the WxEcho project's directory layout, detailing the purpose of each main directory and key files.

```tree
WxEcho/
├── bin/                        # CLI launcher script（npm 全局安装后为 wxecho 命令入口）
├── src/                        # TypeScript CLI 源码
│   ├── cli.ts                  # 主入口（Commander.js）
│   ├── commands/
│   │   ├── export.ts           # wxecho export — 列出/导出聊天记录
│   │   ├── decrypt.ts          # wxecho decrypt — 解密数据库
│   │   └── keys.ts             # wxecho keys — 从微信进程提取密钥
│   └── utils/
│       ├── doctor.ts            # wxecho doctor — 环境依赖检测
│       ├── decrypt_db.ts        # wxecho decrypt — SQLCipher 解密（TypeScript/Node.js crypto）
│       └── python.ts            # Python 子进程封装（用于 export）
├── py/                         # Python 核心逻辑
│   ├── config.py               # 配置加载与自动检测
│   ├── export_chat.py           # 聊天记录导出（TXT/CSV/JSON）
│   ├── key_utils.py             # 密钥文件处理
│   ├── find_all_keys_macos.c    # C 内存扫描器源码
│   ├── find_all_keys_macos      # 编译后的二进制（Apple Silicon only）
│   ├── decrypted/               # 解密后数据库输出目录（gitignored）
│   └── exported/                # 导出文件输出目录（gitignored）
├── landing/                     # React landing page
│   ├── src/
│   │   ├── App.tsx
│   │   ├── components/           # Hero / Features / Steps / Footer
│   │   └── styles/index.css     # WeChat 绿色主题，亮/暗模式
│   ├── public/
│   ├── index.html
│   ├── package.json
│   └── vite.config.ts
├── scripts/
│   ├── build-cli.ts             # esbuild CLI 打包脚本
│   └── postinstall.sh           # npm install 后自动安装 Python 依赖 + 编译 C 扫描器
├── dist/                        # 构建产物
│   ├── cli.js
│   └── landing/
├── package.json                 # npm 包配置（name: @walkerch/wxecho, version: 1.0.0）
├── tsconfig.json
└── README.md
```

--------------------------------

### Check Environment Dependencies

Source: https://github.com/chang-xinhai/wxecho/blob/main/README_zh.md

Run 'wxecho doctor' to check if all necessary environment dependencies are met for WxEcho to function correctly.

```bash
wxecho doctor
```

--------------------------------

### Npm Scripts for WxEcho

Source: https://github.com/chang-xinhai/wxecho/blob/main/AGENTS.md

Common npm scripts available in the root of the WxEcho project for building the CLI, landing page, and performing type checks.

```bash
npm run build        # 构建 CLI → dist/cli.js
npm run build:landing # 构建 landing page → dist/landing/
npm run build:all    # 同时构建 CLI + landing
npm run dev          # 直接用 tsx 运行 CLI（无需 build）
npm run typecheck    # TypeScript 类型检查
```

--------------------------------

### C Compiler Path and Sysroot Configuration

Source: https://github.com/chang-xinhai/wxecho/blob/main/AGENTS.md

Shows how to correctly invoke the C compiler (`clang`) on macOS, including specifying the system root path (`-isysroot`) which is necessary for it to find standard header files. It also addresses potential issues with symlinks.

```typescript
const sysroot = execSync('xcrun --show-sdk-path', { encoding: 'utf8' }).trim();
spawn('clang', ['-isysroot', sysroot, '-O2', '-o', outFile, srcFile, '-framework', 'Foundation']);

// To resolve potential symlink issues with 'cc':
// const realCcPath = fs.realpathSync(await findCc());
// spawn(realCcPath, ...)
```

--------------------------------

### Agent Workflow Directory Structure

Source: https://github.com/chang-xinhai/wxecho/blob/main/AGENTS.md

Standard directory structure for agent work products, located in `~/agents/`. This includes briefs, handoffs, reports, context, and scratch directories.

```tree
~/agents/
├── briefs/           # 任务简报（本次会话要做什么）
├── handoffs/         # 中间态笔记、可续记的上下文
│   ├── WORKLOG.md    # 核心工作日志（必须）
│   └── runtime_logs/ # 运行时日志目录（必须）
├── reports/          # 最终报告
├── context/          # 可复用上下文文档
└── scratch/          # Agent 一次性输出（用完即弃）
```

--------------------------------

### Extract Database Keys

Source: https://github.com/chang-xinhai/wxecho/blob/main/README_en.md

Execute the 'wxecho keys' command to extract encryption keys from the running WeChat process. These keys are necessary for decrypting the chat databases.

```bash
wxecho keys
```

--------------------------------

### Specify Output Directory for Export

Source: https://github.com/chang-xinhai/wxecho/blob/main/README_zh.md

Use the '-o' or '--output' option to specify a custom directory for the exported chat logs. If not specified, a default directory will be used.

```bash
wxecho export -o /path/to/output
```

--------------------------------

### Correct Environment Variable Passing in Bash

Source: https://github.com/chang-xinhai/wxecho/blob/main/AGENTS.md

Demonstrates the correct method for passing environment variables to a Node.js process using `exec` in bash. Incorrectly formatted commands can lead to the variable not being set in the child process.

```bash
# Incorrect: Second line is a separate statement, does not affect exec's environment
# exec node "$PKG_ROOT/dist/cli.js" "$@" \
#   WXECHO_ROOT="$PKG_ROOT"

# Correct: Uses 'env' to set the variable for the executed command
exec env WXECHO_ROOT="$PKG_ROOT" node "$PKG_ROOT/dist/cli.js" "$@"
```

--------------------------------

### Commit Message for Syncing NPM Version

Source: https://github.com/chang-xinhai/wxecho/blob/main/AGENTS.md

Use this commit message format after successfully publishing a new npm version and updating documentation.

```bash
git add <updated files>
git commit -m "docs: sync npm version info to vX.Y.Z"
git push
```

--------------------------------

### List All Conversations for Export

Source: https://github.com/chang-xinhai/wxecho/blob/main/README_en.md

Execute 'wxecho export -l' to list all available conversations. This command helps identify the exact names or identifiers for exporting specific chat histories.

```bash
wxecho export -l
```

--------------------------------

### Perform WeChat Re-signing (Remove Hardened Runtime)

Source: https://github.com/chang-xinhai/wxecho/blob/main/AGENTS.md

This command is used to re-sign the WeChat application on macOS, which is often necessary for the WxEcho tool to function correctly. Ensure WeChat is completely closed before executing.

```bash
# 1. Ensure WeChat is completely exited
# 2. Execute re-signing (remove Hardened Runtime)
sudo codesign --force --deep --sign - /Applications/WeChat.app

# 3. Re-open WeChat and log in
```

--------------------------------

### Python sys.platform Values for Cross-Platform Code

Source: https://github.com/chang-xinhai/wxecho/blob/main/AGENTS.md

Highlights the value of `sys.platform` on macOS ('darwin') and contrasts it with Linux ('linux'). This is crucial for writing cross-platform compatible code, as macOS does not fall under the 'linux' or 'posix' assumptions in some libraries.

```python
# In Python, platform.system() on macOS returns 'Darwin'.
# _SYSTEM = platform.system().lower() # This will be 'darwin'
# _auto_detect_db_dir_linux() only handles _SYSTEM == "linux".
# Therefore, macOS cases must be handled explicitly.
```

--------------------------------

### List Top N Chat Sessions

Source: https://github.com/chang-xinhai/wxecho/blob/main/README_zh.md

List the top N most recent or active chat sessions using the '--top' option. The default value is 20.

```bash
wxecho export --top 10
```

--------------------------------

### Agent Worklog Entry Format

Source: https://github.com/chang-xinhai/wxecho/blob/main/AGENTS.md

Required format for entries in the WORKLOG.md file, including timestamp, actor, status, summary, paths, commands, artifacts, blockers, and next steps.

```markdown
### <UTC ISO 8601 时间戳> | <actor> | <status>
- Summary: <一句话描述>
- Paths: <涉及的本仓库路径，如有>
- Commands: <执行的命令，如有>
- Artifacts: <生成的产物路径，如有>
- Blockers: <阻塞因素，如有>
- Next: <下一步计划>
```

--------------------------------

### Export Chat History by Name

Source: https://github.com/chang-xinhai/wxecho/blob/main/README_zh.md

Export chat history for a specific contact by providing their name or remark using the 'wxecho export -n "<name>"' command.

```bash
wxecho export -n "张三"
```

--------------------------------

### Decrypt WeChat Databases

Source: https://github.com/chang-xinhai/wxecho/blob/main/AGENTS.md

Decrypts WeChat databases using the keys generated by the `wxecho keys` command. The `all_keys.json` file must be present.

```bash
# Decrypt WeChat databases (using all_keys.json)
wxecho decrypt

# Decrypted databases will be in the py/decrypted/ directory
```

--------------------------------

### Decrypt WeChat Databases

Source: https://github.com/chang-xinhai/wxecho/blob/main/README_en.md

Run the 'wxecho decrypt' command to decrypt the local WeChat databases using the extracted keys. This process converts the encrypted databases into a usable SQLite format.

```bash
wxecho decrypt
```

--------------------------------

### Set HOME Environment Variable with Sudo

Source: https://github.com/chang-xinhai/wxecho/blob/main/AGENTS.md

When spawning a child process with sudo in Node.js, the HOME environment variable can be reset. This snippet shows how to explicitly pass the real home directory to the child process to avoid issues.

```typescript
const realHome = os.userInfo().homedir; // 不受 sudo 影响
spawn('sudo', [binaryPath], {
  env: { ...process.env, HOME: realHome, SUDO_USER: path.basename(realHome) }
});
```

--------------------------------

### Re-sign WeChat Application

Source: https://github.com/chang-xinhai/wxecho/blob/main/README_en.md

Re-sign the WeChat application to allow WxEcho to access its memory for key extraction. This is a required step before running WxEcho commands.

```bash
sudo codesign --force --deep --sign - /Applications/WeChat.app
```

--------------------------------

### Export Chat History by Name

Source: https://github.com/chang-xinhai/wxecho/blob/main/README_en.md

Use the 'wxecho export' command to export chat history. Specify a contact's name using the '-n' flag for targeted export.

```bash
wxecho export -n "John Doe"
```

--------------------------------

### macOS WeChat Database Path

Source: https://github.com/chang-xinhai/wxecho/blob/main/AGENTS.md

Specifies the correct directory path for WeChat databases on macOS, which differs from default assumptions and requires specific handling in cross-platform code.

```plaintext
~/Library/Containers/com.tencent.xinWeChat/Data/Documents/xwechat_files/<account>/db_storage/
```

--------------------------------

### Export Chat History by Username

Source: https://github.com/chang-xinhai/wxecho/blob/main/README_zh.md

Export chat history by matching the exact WeChat ID (wxid) of a contact using the 'wxecho export -u <wxid>' option.

```bash
wxecho export -u <wxid>
```

--------------------------------

### Log Work Script

Source: https://github.com/chang-xinhai/wxecho/blob/main/AGENTS.md

A Bash script to log work activities, including status, summary, paths, commands, artifacts, blockers, and next steps. It appends entries to a WORKLOG.md file.

```bash
#!/usr/bin/env bash
set -euo pipefail

WORKLOG="${WORKLOG_PATH:-$HOME/agents/handoffs/WORKLOG.md}"
ACTOR="${WORKLOG_ACTOR:-${USER:-unknown}}"

while [[ $# -gt 0 ]]; do
  case "$1" in
    --actor)    ACTOR="$2";    shift 2 ;;
    --status)   STATUS="$2";   shift 2 ;;
    --summary)  SUMMARY="$2";  shift 2 ;;
    --paths)    PATHS="$2";    shift 2 ;;
    --commands) COMMANDS="$2"; shift 2 ;;
    --artifacts) ARTIFACTS="$2"; shift 2 ;;
    --blockers) BLOCKERS="$2"; shift 2 ;;
    --next)     NEXT_STEP="$2"; shift 2 ;;
    -h|--help)  printf 'Usage: log_work.sh [--actor A] [--status S] [--summary T] [--paths P] [--commands C] [--artifacts A] [--blockers B] [--next N]\n'; exit 0 ;;
    *)          printf 'Unknown arg: %s\n' "$1" >&2; exit 1 ;;
  esac
done

case "$STATUS" in
  planned|in_progress|blocked|done|cancelled) ;; 
  *) printf 'Invalid --status\n' >&2; exit 1 ;;
esac
[[ -z "$SUMMARY" ]] && printf 'Missing --summary\n' >&2 && exit 1

timestamp="$(date -u +'%Y-%m-%dT%H:%M:%SZ')"
mkdir -p "$(dirname "$WORKLOG")" "$HOME/agents/handoffs/runtime_logs"

cat >> "$WORKLOG" <<EOF

### ${timestamp} | ${ACTOR} | ${STATUS}
- Summary: ${SUMMARY}
- Paths: ${PATHS}
- Commands: ${COMMANDS}
- Artifacts: ${ARTIFACTS}
- Blockers: ${BLOCKERS}
- Next: ${NEXT_STEP}
EOF

```

--------------------------------

### Specify Current User's WeChat ID

Source: https://github.com/chang-xinhai/wxecho/blob/main/README_zh.md

Manually set your own WeChat ID using '--my-wxid' if automatic detection fails. This can be useful in multi-account scenarios.

```bash
wxecho export --my-wxid <your_wxid>
```

--------------------------------

### Extract WeChat Decryption Keys

Source: https://github.com/chang-xinhai/wxecho/blob/main/AGENTS.md

Extracts all necessary decryption keys from the WeChat application. Ensure WeChat is running and you are logged in before executing this command.

```bash
# Ensure WeChat is running and logged in
wxecho keys

# Outputs all_keys.json, containing decryption keys for all databases
```

--------------------------------

### Disable System Integrity Protection (SIP) on macOS

Source: https://github.com/chang-xinhai/wxecho/blob/main/AGENTS.md

This is an alternative to re-signing WeChat if re-signing fails or is undesirable. Disabling SIP reduces system security. This process requires restarting your Mac into recovery mode.

```bash
# 1. Enter Recovery Mode: Restart Mac, hold Command + R
# 2. Open Terminal (Utilities -> Terminal)
# 3. Execute SIP disable command
csrutil disable

# 4. Restart Mac into normal mode
# 5. Verify SIP status
csrutil status
# Should display "System Integrity Protection status: disabled."

# 6. Proceed with key extraction (no re-signing needed)
wxecho keys

# Note: Disabling SIP reduces system security. To re-enable SIP: restart into recovery mode, execute csrutil enable.
```

--------------------------------

### Commander.js Action Handler 'this' Binding

Source: https://github.com/chang-xinhai/wxecho/blob/main/AGENTS.md

Illustrates the correct way to bind `this` within a Commander.js action handler. In v12, `this` refers to the Command object, and the first argument is the positional argument.

```typescript
// Incorrect
// export function runExport(cmd: Command) {
//   cmd.opts(); // TypeError: opts of undefined
// }

// Correct
export function runExport(this: Command, name: string | undefined) {
  this.opts(); // OK
}
```

--------------------------------

### Export WeChat Chat History

Source: https://github.com/chang-xinhai/wxecho/blob/main/AGENTS.md

Exports chat history from WeChat. Various options are available for listing, filtering, and specifying output.

```bash
# List all conversations (sorted by message count, top 20 by default)
wxecho export -l

# List top N conversations
wxecho export -l --top 50

# Export by fuzzy nickname search
wxecho export -n "张三"

# Specify output directory
wxecho export -n "张三" -o ~/Downloads/mychat

# Exact match by username
wxecho export -u wxid_xxxxx

# Specify your own WeChat ID (to display your nickname)
wxecho export -n "张三" --my-wxid your_wxid
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.