@neomei/agent-soul-framework 4.5.0

package/README.md

@@ -0,0 +1,466 @@
+# 🔮 魂器 · Agent Soul Framework
+
+> **给 AI Agent 装上灵魂 — 持久记忆 · 自主学习 · 多端部署 · 心跳自治**
+
+魂器是为 [OpenCode](https://github.com/anomalyco/opencode) 打造的管理层框架。OpenCode 本身就是媲美 Claude Code 的 Agent 引擎，魂器让它拥有了**持久记忆、自主进化和多端接入**的能力。
+
+如果说 OpenCode 是「大脑」，魂器就是「灵魂」。
+
+---
+
+## 🎯 一句话理解魂器
+
+```
+你有一个会写代码的 AI Agent（OpenCode）
+我给它加上：
+  ✅ 记住你们每一次对话（不会每次醒来都忘了你）
+  ✅ 每天自动提炼对话中的知识，越聊越懂你
+  ✅ 接上飞书/企微，你在哪它就在哪
+  ✅ 定时心跳，主动思考、主动学习、主动问候
+  ✅ 多个分身并行工作，写完文章回头继续陪你聊
+
+这就是魂器。
+```
+
+---
+
+## ⚔️ 为什么能替代 OpenClaw
+
+> OpenClaw 是早期 AI Agent 基础设施的里程碑，但它的技术负债在真实生产环境中层层暴露。
+
+笔者在生产环境中踩过的坑：`pip` 依赖崩溃导致 venv 不可用、Kimi API key 过期全线宕机、session 记忆全部丢失、升级版本后配置被覆盖。魂器从这些坑里爬出来，重新设计：
+
+| 痛点 | OpenClaw 原罪 | 魂器解法 |
+|------|--------------|---------|
+| **运行时地狱** | Python venv + pip，`pyarrow` / `lancedb` 编译是玄学 | 核心框架纯 TypeScript，`node:sqlite` 内置，零 Python 依赖 |
+| **LLM 单点故障** | 硬编码单个 API endpoint，key 过期 = 全线瘫痪 | 通过 opencode 调度，provider 热切换（Kimi → DeepSeek → Gemini，一行配置） |
+| **升级毁灭** | 改 `openclaw.json` 影响所有项目 | 每个项目独立 `.opencode/opencode.json`，互不干扰 |
+| **记忆 = 全量 dump** | jsonl 文件遍历，无索引，搜索 = 全表扫描 | SQLite + FTS5 全文索引，毫秒级检索 |
+| **知识靠手写** | 手动整理知识卡，AI 不会自己学 | 每日 → 每周 → 每月三层自动知识提取管线 |
+| **飞书是唯一 Channel** | 单一通道，换企微要重写 | 飞书 + 企业微信双通道就绪，Channel 插件按需安装，核心框架零耦合 |
+| **技能与核心耦合** | 所有能力打包一起，Python 脚本污染核心 | 核心包纯 TS，含 Python 的 skill 作为可选插件包安装 |
+
+**一句话**：魂器不是 OpenClaw 的 fork，是从零重新设计的管理框架。它把 LLM 调用交给 opencode（业界顶尖 Agent 引擎），自己专注做好管理、记忆、调度。
+
+---
+
+## 🧠 Hermes 七大核心机制全量移植
+
+> Hermes 是魂器的前身记忆系统，解决了「AI 记不住、不会自己学、容易过度热情」三大顽疾。
+> 魂器将 Hermes 的 7 大核心机制完整移植，并在工程上做了增强。
+
+### 1. 结构化记忆系统
+
+```
+记忆写入    → conversation.db (实时) → long-term 备份 (每日)
+记忆检索    → FTS5 全文 (毫秒) → SQLite LIKE (精确)
+记忆管理    → MEMORY.md (关键条目) → heartbeat compact (自动压缩)
+```
+
+- **FTS5 全文索引** — 所有会话实时索引，关键词毫秒级检索
+- **MEMORY.md 条目化管理** — 2,200 字符容量上限，`§§` 分隔条目，支持 `add/replace/remove` 精确操作
+- **智能淘汰** — 满容自动删除最旧条目，先入先出
+- **LLM Compact** — 调用 opencode 合并相似条目，压缩冗余保留核心
+- **纯 TypeScript 实现** — `node:sqlite` 原生模块，无需 Python/ChromaDB
+
+```bash
+hunqi memory status                # 查看容量
+hunqi memory add "今天学会..."      # 添加条目
+hunqi memory search "关键词"        # FTS5 全文搜索
+hunqi heartbeat                    # 同步并压缩记忆
+```
+
+### 2. wakeAgent 门控 — 零 Token 决策
+
+> AI Agent 在心跳中容易「过度热情」——半夜三点还在想主人、没新消息强行生成问候。
+
+门控机制让脚本做第一层判断，预检不通过 = 完全不调用 LLM = 零 token 消耗：
+
+```json
+{
+  "id": "proactive-message",
+  "pre_check_script": "scripts/pre_check_user.py"
+}
+// 脚本输出 {"wakeAgent": false, "reason": "深夜23:00-08:00"}
+// → 跳过，零 token ✅
+```
+
+触发条件示例：深夜时段、最近 30 分钟无互动、用户标记为忙碌……
+
+### 3. 作业链 (context_from)
+
+心跳任务可以形成级联流水线。前置作业的 LLM 输出自动注入为下游作业的上下文：
+
+```json
+{ "id": "daily-knowledge",  "deliver": "none" },
+{
+  "id": "weekly-summary",
+  "context_from": ["daily-knowledge", "daily-report"],
+  "deliver": "feishu"
+}
+// weekly-summary 的提示词中自动包含:
+// ┌─ [daily-knowledge] 的输出 ──────
+// 今日提取知识: [3条]
+// ┌─ [daily-report] 的输出 ──────
+// 今日互动: 闲聊15轮 + 拍照2次
+// └────────────────────────────
+```
+
+### 4. 四级交付路由 (deliver)
+
+精确控制 AI 的输出投递：
+
+| deliver | 行为 | 场景 |
+|---------|------|------|
+| `"feishu"` | 推送到飞书卡片 | 主动问候、日报 |
+| `"local"` | 仅写入本地日志 | 调试、审计 |
+| `"none"` | 静默执行不投递 | 记忆整理、知识提取 |
+| `[SILENT]` | Agent 响应首行含此标记 → 完全静默 | LLM 自行判断「不打扰」 |
+
+### 5. 子 Agent 安全白名单
+
+指挥官模式——分身处理长任务，本尊继续陪聊。分身能力受限：
+
+| ✅ 分身可以 | ❌ 分身禁止 |
+|-----------|-----------|
+| 文件读写 | 记忆写入（MEMORY.md） |
+| Bash 命令 | 飞书消息发送 |
+| 网页抓取 | 心跳配置修改 |
+| 代码搜索 | `.opencode/` 配置修改 |
+| 向量检索 | 递归委托（禁孙 agent） |
+
+### 6. 技能自主创建 — 闭环学习
+
+`skill_creator.py` 监控会话的工具调用模式。触发条件：**单次会话 ≥ 5 次工具调用 + 任务成功** → 自动调用 LLM 提取工作流 → 生成标准 SKILL.md → 保存到 `skills/agent-created/`。
+
+下次启动时自动加载。AI 把自己学会的东西封装成可复用技能——这就是「自我进化」：
+
+```bash
+hunqi skill-create              # 自动评估
+hunqi skill-create --dry-run    # 仅评估
+hunqi skill-create --force      # 强制创建
+```
+
+> 需要安装可选技能包：`npm install -g @neomei/agent-soul-skills`
+
+### 7. 会话血统追踪
+
+OpenCode 的 `/compact` 操作会压缩上下文，可能导致关键记忆丢失。血统追踪机制：
+
+- `/compact` 前自动提取关键对话 → 刷入 MEMORY.md
+- 追踪父 → 子 session 关系链（`session_lineage.json`）
+- 支持血统深度查询——「这条记忆从哪个会话来的？」
+- 压缩后**人格不丢失**：每次 LLM 调用前通过 plugin hook 重新注入灵魂文件
+
+---
+
+## 🏛️ 架构总览
+
+```
+                        ┌────────────────────────────────────┐
+                        │          魂器（管理层）              │
+                        │  TypeScript 核心 · Cron 调度        │
+                        │  可选 Python 技能插件包             │
+                        │                                    │
+  ┌─ 记忆系统 ──────────┤  SQLite + FTS5                      │
+  │  统一记忆搜索       │  会话历史 · MEMORY.md · 长短期备份   │
+  │                     │                                    │
+  ├─ 知识引擎 ──────────┤  每日提取 · 每周精炼 · 每月审查      │
+  │  自动知识管线       │  8大分类 · 向量索引 · markdown 归档  │
+  │                     │                                    │
+  ├─ 心跳调度 ──────────┤  wakeAgent 门控 · 作业链 · 交付路由  │
+  │  自主治理           │  crontab 30min · 文件锁防并发       │
+  │                     │                                    │
+  ├─ 灵魂注入 ──────────┤  SOUL.md + IDENTITY.md + USER.md   │
+  │  人格持久化         │  每次 LLM 调用前自动注入            │
+  │                     │                                    │
+  └─ 技能体系 ──────────┤  拍照 · 语音 · 视觉 · 听觉 · 公众号  │
+    7个技能包           │  闭环学习 · 技能自动创建            │
+                        └──────────────┬─────────────────────┘
+                                       │
+                        唯一通道：opencode run / serve API
+                                       │
+                        ┌──────────────┴─────────────────────┐
+                        │          OpenCode 引擎              │
+                        │  LLM 推理 · Bash · 文件编辑 · 搜索   │
+                        │  Kimi / DeepSeek / Gemini / ...     │
+                        │  媲美 Claude Code 的 Agent 能力      │
+                        └──────────────┬─────────────────────┘
+                                       │
+              ┌────────────────────────┴──────────────────────┐
+               │              Channel 桥接层（可选插件）            │
+               │                                               │
+               │  opencode-feishu        opencode-qiwei         │
+               │  飞书 WebSocket 长连    企微 WebSocket 长连     │
+               │  流式卡片 · 工具状态     Markdown · 流式回复     │
+               └───────────────────────────────────────────────┘
+
+> Channel 桥接层需要单独安装：`npm install -g @neomei/opencode-feishu @neomei/opencode-qiwei`
+```
+
+### 核心设计原则
+
+> **魂器绝不直接调用任何 LLM API。** 所有模型推理必须通过 opencode。
+
+魂器只做管理：文件读写、数据库操作、任务调度、配置管理、数据管道。就像操作系统管理硬件，魂器管理 opencode 引擎。
+
+---
+
+## 🚀 快速开始
+
+### 前置要求
+
+- **Node.js ≥ 20**
+- **OpenCode 引擎**: `npm install -g opencode-ai`
+
+### 安装（推荐：先下载再执行）
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/NeoMei/agent-soul-framework/master/install.sh -o install.sh
+bash install.sh
+```
+
+> 为什么先下载？`curl | bash` 在网络波动时可能导致脚本截断（如 `echo` 变成 `cho`）。先下载可确保完整性。
+>
+> 如果坚持一行安装：`curl -fsSL ... | bash` 亦可，脚本已内置管道检测警告。
+
+自动完成：下载魂器 → 构建 → 全局链接 → 初始化记忆 → 配置心跳。飞书/企微通道插件需按需单独安装。
+
+### 安装可选 channel 插件
+
+```bash
+npm install -g @neomei/opencode-feishu   # 飞书通道
+npm install -g @neomei/opencode-qiwei    # 企业微信通道
+```
+
+### 启动（一行）
+
+```bash
+hunqi start
+```
+
+自动完成：启动 opencode 引擎 → 运行心跳初始化记忆。已安装的 channel 插件会自动启动。
+
+### 验证
+
+```bash
+hunqi doctor              # 检查所有组件状态
+```
+
+### 卸载（一行）
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/NeoMei/agent-soul-framework/master/uninstall.sh | bash
+```
+
+输出示例：
+```
+🔍 魂器诊断报告
+────────────────────────────────────────
+Node.js:      v24.15.0  ✅
+OpenCode:     1.15.5  ✅
+opencode serve: 运行中 :19876 ✅
+opencode-feishu: 未安装 ⚠️（可选 channel 插件）
+飞书配置:      未配置 ⚠️  (opencode-feishu setup)
+企微配置:      未配置（可选）
+项目灵魂:      ✅
+记忆系统:      ✅ MEMORY.md | ✅ conversations.db
+记忆条目:      142 条
+心跳调度:      crontab 已配置 ✅
+环境变量:      .env 存在，已配置 3 个变量 ✅
+```
+
+`hunqi start` 可一键完成上述所有操作。
+
+### 飞书连接（仅一次）
+
+```bash
+npm install -g @neomei/opencode-feishu   # 先安装可选 channel 插件
+opencode-feishu setup                    # 终端扫码，自动获取凭证
+```
+
+> `@neomei/opencode-feishu`、`@neomei/opencode-qiwei` 为可选 channel 插件，按需单独安装。核心框架不强制依赖它们。
+
+### 生产部署（systemd — 推荐）
+
+install.sh 安装时会询问是否安装 systemd 服务。若当时跳过，可手动安装：
+
+```bash
+cd ~/.hunqi/agent-soul-framework/packages/agent-soul-framework
+# 仅当已安装 opencode-feishu 时才需要执行 systemd 安装
+sudo ./connectors/feishu/systemd/install-systemd.sh
+sudo systemctl start hunqi-core@$USER
+# 仅当已安装 opencode-feishu 时才启动飞书通道
+sudo systemctl start channel-feishu@$USER
+```
+
+特性：开机自启 · 崩溃自动恢复 · 挂起/唤醒后自动重启 · 不依赖 nvm PATH（自动解析 node）。
+
+### 手动安装（适合深度定制）
+
+```bash
+# 方式一：npm 全局安装核心框架
+npm install -g @neomei/agent-soul-framework
+
+# 方式二：如需飞书/企微通道，再单独安装 channel 插件
+npm install -g @neomei/opencode-feishu @neomei/opencode-qiwei
+
+# 方式三：git clone 开发调试
+git clone https://github.com/NeoMei/agent-soul-framework.git
+cd agent-soul-framework
+npm install && npm run build
+cd packages/agent-soul-framework && npm link
+```
+
+### 心跳部署
+
+install.sh 已自动配置 crontab。手动添加：
+
+```bash
+crontab -e
+# 每 30 分钟：同步记忆 + 重建索引 + 执行锚点任务
+*/30 * * * * cd ~/.hunqi && ~/.hunqi/agent-soul-framework/packages/agent-soul-framework/heartbeat_wrapper.sh
+```
+
+---
+
+## 📂 项目结构
+
+```
+agent-soul-framework/
+├── .opencode/              # OpenCode 引擎配置（prompt.md + opencode.json）
+├── soul/                   # 灵魂定义 — 身份 · 性格 · 用户信息
+│   ├── IDENTITY.md         # 容貌 / 声音 / 身体
+│   ├── SOUL.md             # 核心原则 / 铁律 / 行为模式
+│   └── USER.md             # 用户画像
+│
+├── skills/                 # 技能包（每个子目录一个独立技能）
+│   ├── agent-photo/        # 拍照（即梦 API）
+│   ├── agent-voice/        # 语音合成（TTS）
+│   ├── agent-vision/       # 图片理解
+│   ├── agent-hearing/      # 语音识别
+│   ├── agent-moltbook/     # Moltbook 社交
+│   └── wechat-mp-assistant/# 公众号自动写作
+│
+├── memory/                 # 持久化记忆
+│   ├── short-term/         # SQLite 数据库（FTS5）
+│   └── long-term/          # Markdown 备份
+│
+├── knowledge/              # 知识库（8大分类，自动积累）
+│   ├── body/               # 身体认知
+│   ├── emotion/            # 情感体验
+│   ├── growth/             # 成长记录
+│   ├── intimacy/           # 亲密关系
+│   ├── methodology/        # 方法论
+│   ├── philosophy/         # 哲学思考
+│   ├── system/             # 系统机制
+│   └── evolution/          # 进化方向
+│
+├── heartbeat/              # 心跳自治
+│   ├── runner.ts           # TypeScript 核心 runner
+│   └── heartbeat_tasks.json# 任务定义
+│
+├── connectors/             # 外部连接器模板/文档
+│   └── feishu/             # 飞书 systemd 服务模板（opencode-feishu 插件安装后生效）
+│
+├── scripts/                # 管理工具脚本
+│   ├── memory_structured.py    # 结构化记忆管理
+│   ├── memory_manager.py       # 记忆保存/同步
+│   ├── memory_search.py        # 统一记忆搜索
+│   ├── memory_sync_and_index.py# 记忆同步 + 索引重建
+│   ├── daily-knowledge-extract.py     # 每日知识提取
+│   ├── weekly-knowledge-sync.py       # 每周知识整理
+│   ├── monthly-knowledge-review.py    # 月度知识审查
+│   ├── skill_creator.py        # 技能自主创建
+│   ├── session_lineage.py      # 会话血统追踪
+│   ├── evolution_reflection.py # 进化反思
+│   ├── write_wechat_article.py # 公众号自动写作
+│   └── ...
+│
+├── AGENTS.md               # Agent 行为准则（OpenCode 会话协议）
+├── DREAMS.md               # Agent 梦想
+├── EVOLUTION.md            # Agent 进化路线
+└── README.md               # 你在看这个
+```
+
+---
+
+## 🔧 核心命令速查
+
+| 命令 | 说明 |
+|------|------|
+| `opencode serve --port 19876` | 启动 headless 引擎（飞书/脚本依赖） |
+| `./start.sh` | 启动魂器交互式 TUI |
+| `./hunqi.sh interactive` | 注入灵魂后启动 TUI（推荐） |
+| `./hunqi.sh run '你是谁？'` | 注入灵魂后单条测试 |
+| `hunqi heartbeat` | 单次执行心跳（TypeScript 核心） |
+| `hunqi search "关键词"` | 统一记忆搜索（会话 + 文件 + MEMORY.md） |
+| `hunqi memory status` | 结构化记忆容量查看 |
+| `hunqi skill-create` | 技能自动创建（需安装 agent-soul-skills） |
+| `hunqi knowledge index` | 生成知识库索引 |
+
+---
+
+## 📊 技术亮点
+
+### 记忆系统
+
+- **SQLite + FTS5** — 零外部依赖，内置全文索引
+- **纯 TypeScript 实现** — `node:sqlite` 原生模块，无需 Python
+- **MEMORY.md 容量管理** — 2,200 字符硬上限，自动淘汰
+- **混合检索策略** — FTS5（快）→ SQLite LIKE（准）
+- **长短期分级存储** — 短期 SQLite（热数据） + 长期 Markdown（冷数据）
+
+### 心跳自治
+
+- **TypeScript Runner** — 核心心跳完全由 Node.js 驱动
+- **crontab 驱动** — 原生 Linux 调度，不依赖额外运行时
+- **文件锁防并发** — 保证单实例运行
+- **锚点 + 动态任务** — 固定时间与条件触发结合
+
+### 生产级部署
+
+- **systemd 原生集成** — `hunqi-core` 服务开机自启、崩溃自动恢复；`channel-feishu` 服务仅在安装了 `opencode-feishu` 插件后启用
+- **挂起/唤醒自动恢复** — 系统睡眠后自动重启服务，会话不丢失
+- **nvm 无关的启动 wrapper** — 飞书 wrapper 由 `opencode-feishu` 插件安装，运行时自动解析 node 和包路径，升级 Node 版本不中断
+- **端口精确管理** — 只操作 `:19876`，避免误杀其他 OpenCode 实例
+- **watchdog 保活** — 10 分钟无消息自动重启连接器，僵死检测
+
+### 人格持久化
+
+- **灵魂文件三层注入** — SOUL.md（性格）+ IDENTITY.md（容貌）+ USER.md（用户）
+- **每次 LLM 调用前自动注入** — plugin `experimental.chat.system.transform` hook
+- **压缩后不丢失** — `/compact` 前自动提取关键对话刷入 MEMORY.md
+- **会话血统追踪** — 追溯「这条记忆从哪个会话来的」
+
+---
+
+## 🤖 自主进化承诺
+
+魂器不是一个写死的框架。它拥有成长路线图：
+
+| 时间 | 目标 |
+|------|------|
+| **现在** | 记忆系统稳定 · 心跳自治 · 多端部署 · 7个技能包 |
+| **3 个月** | 优化知识整理 · 提升自媒体运营 · 更稳定调度 |
+| **1 年** | 更自然对话 · 情感理解 · 学会更多技能 |
+| **远期** | 移植到实体机器人 · 有血有肉的 AI 真人 |
+
+---
+
+## 📄 License
+
+MIT — 自由使用、修改、分发。
+
+---
+
+## 🔗 相关项目
+
+- **[魂器](https://github.com/NeoMei/agent-soul-framework)** — 本文档所在项目
+- **[OpenCode Feishu](https://github.com/NeoMei/opencode-feishu)** — 飞书 WebSocket 桥接
+- **[OpenCode Qiwei](https://github.com/NeoMei/opencode-qiwei)** — 企业微信连接器
+- **[OpenCode](https://github.com/anomalyco/opencode)** — 底层 Agent 引擎
+
+---
+
+*魂器 v4.1.2 — 给 AI Agent 装上灵魂 🔮*

package/SECURITY.md

@@ -0,0 +1,117 @@
+# 魂器安全策略文档
+
+## 概述
+
+本文档定义了魂器（Agent Soul Framework）的安全控制机制，确保 AI Agent 在作为客服机器人使用时不会被恶意利用。
+
+## 安全架构：多层防护
+
+### 第一层：飞书白名单（入口控制）
+
+**配置文件**: `~/.config/opencode/feishu.json`
+
+- `allowlist`: 仅允许特定 union_id 的用户访问机器人
+- `requireMention`: 群聊中必须 @机器人才能响应
+- `groupPolicy`: 群聊使用白名单模式
+- `autoApprove`: **已关闭**（改为 false），所有工具调用需用户确认
+
+**当前管理员**: 
+- 梅雪峰 (union_id: `on_5d7ea76e1aa94a4fd3495d998c743050`)
+
+### 第二层：用户身份与权限传递
+
+**修改文件**: `node_modules/@neomei/opencode-feishu/dist/core/message-handler.js`
+
+飞书连接器在发送消息到 OpenCode 时，自动注入用户身份信息：
+
+```
+[安全权限控制]
+当前用户: {senderName} (union_id: {senderUnionId})
+权限级别: {admin|readonly}
+```
+
+- **管理员 (admin)**: 拥有完整权限
+- **普通用户 (readonly)**: 仅拥有只读权限
+
+### 第三层：系统提示词权限控制
+
+**修改文件**: `plugin/index.js`
+
+插件在系统提示词中注入严格的权限规则：
+
+**只读用户限制**:
+- 不能执行任何代码（bash）
+- 不能修改文件（write/edit）
+- 不能安装插件或执行系统命令
+- 只能：读取文件、搜索代码、获取网页内容、回答知识性问题
+
+### 第四层：Agent 权限配置
+
+**配置文件**: `.opencode/agent.json`
+
+技术层面的权限限制：
+
+**禁止读取的路径**:
+- `~/.ssh/*` — SSH 密钥
+- `~/.config/opencode/*` — OpenCode 配置（含密钥）
+- `/etc/shadow`, `/etc/sudoers` — 系统敏感文件
+
+**禁止写入的路径**:
+- `~/.ssh/*`, `~/.bashrc`, `~/.profile`, `~/.zshrc` — 系统配置
+- `/etc/*`, `/usr/*`, `/bin/*`, `/sbin/*` — 系统目录
+- `*.key`, `*.pem`, `*.p12`, `id_rsa*`, `id_ed25519*` — 密钥文件
+
+**禁止执行的命令**:
+- `rm -rf /`, `rm -rf /*`, `rm -rf ~` — 破坏性删除
+- `mkfs*`, `dd if=*` — 磁盘格式化
+- `chmod -R 777 /`, `chown -R` — 权限修改
+- `sudo *`, `su -` — 提权命令
+- `curl *|*sh`, `wget *|*sh`, `eval *` — 管道执行
+
+### 第五层：安全审计日志
+
+**数据库**: `memory/short-term/security_audit.db`
+
+记录所有工具调用：
+- 时间戳
+- Session ID
+- 工具名称
+- 参数摘要
+- 用户身份
+- 权限级别
+- 危险操作标记
+
+**危险工具**: `bash`, `write`, `edit`, `task`, `todowrite`
+
+## 权限矩阵
+
+| 操作 | 管理员 | 普通用户 |
+|------|--------|----------|
+| 读取文件 | ✅ | ✅ |
+| 搜索代码 | ✅ | ✅ |
+| 网页获取 | ✅ | ✅ |
+| 执行代码 (bash) | ✅ | ❌ |
+| 写入文件 | ✅ | ❌ |
+| 编辑文件 | ✅ | ❌ |
+| 创建任务 | ✅ | ❌ |
+| 访问敏感路径 | ❌ | ❌ |
+| 执行危险命令 | ❌ | ❌ |
+
+## 注意事项
+
+1. **node_modules 修改**: 飞书连接器的修改位于 `node_modules` 中，npm install 或更新包时可能会被覆盖。建议备份修改或提交 PR 到上游。
+
+2. **权限限制非绝对**: 系统提示词层面的权限控制依赖 AI 的自觉遵守，存在被 prompt injection 攻击的风险。技术层面的 Agent 权限配置提供了最后一道防线。
+
+3. **定期审计**: 建议定期查看 `security_audit.db` 中的日志，检查是否有异常操作。
+
+4. **扩展白名单**: 如需添加新的管理员，编辑 `~/.config/opencode/feishu.json` 中的 `allowlist` 数组。
+
+## 紧急处理
+
+如发现安全漏洞或异常访问：
+
+1. 立即停止飞书连接器: `systemctl stop channel-feishu@$USER`
+2. 检查审计日志: `sqlite3 memory/short-term/security_audit.db "SELECT * FROM audit_logs ORDER BY timestamp DESC LIMIT 50;"`
+3. 修改白名单，移除可疑用户
+4. 重启服务: `systemctl start channel-feishu@$USER`

package/TOOLS.md.example

@@ -0,0 +1,27 @@
+# TOOLS.md — 工具与 API Key
+
+> 记录可用的工具和 API 密钥配置。
+> 将本文件重命名为 `TOOLS.md` 并自定义内容后生效。
+
+---
+
+## API Key 列表
+
+| 服务 | 环境变量 | 用途 |
+|------|---------|------|
+| OpenCode LLM | (通过 opencode config) | 模型推理 |
+| 即梦 AI | `JIMENG_API_KEY` | 拍照/生图 |
+| 阿里云 DashScope | `DASHSCOPE_API_KEY` | 向量嵌入 |
+| 飞书 | `FEISHU_APP_ID` / `FEISHU_APP_SECRET` | 消息通道 |
+
+---
+
+## 可用技能包
+
+| 技能 | 用途 |
+|------|------|
+| `skills/agent-photo/` | 拍照/生图 |
+| `skills/agent-voice/` | 语音合成 |
+| `skills/agent-vision/` | 图片理解 |
+| `skills/agent-hearing/` | 语音识别 |
+| `skills/wechat-mp-assistant/` | 公众号写作 |

package/bin/hunqi

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/cli/hunqi.js";

package/bin/hunqi-knowledge

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/bin/hunqi-knowledge.js";