evolcore 0.0.1 → 0.0.2

package/dist/utils/welcome.js

@@ -0,0 +1,268 @@
+/**
+ * 统一的欢迎消息模块
+ *
+ * 包含欢迎消息生成、管理器和渠道帮助函数
+ *
+ * 设计：
+ * - AUN：connect 时发送给预配置的 owner（协议内建机制，P2P 主动推送）
+ * - 所有 IM 渠道（Feishu/WeChat/DingTalk/QQBot/WeCom）：首次交互时发送给交互用户（被动响应）
+ */
+import fs from 'fs';
+import path from 'path';
+import { resolvePaths } from '../paths.js';
+import { loadAgent, saveAgent } from '../config-store.js';
+import { withLifecycleForWrite } from '../config/lifecycle.js';
+import { logger } from './logger.js';
+// ============================================================================
+// 欢迎消息生成
+// ============================================================================
+/**
+ * 生成统一的欢迎消息文本
+ */
+export function generateWelcomeMessage(options) {
+    const channelDesc = getChannelDescription(options.channelType);
+    const greeting = options.ownerName
+        ? `👋 你好，${options.ownerName}！`
+        : '👋 你好！';
+    const agentIntro = options.agentName
+        ? `我是 ${options.agentName}，你的 AI Agent 网关。`
+        : '我是您的 AI Agent 网关。';
+    const channelInfo = `已成功连接到${channelDesc}。`;
+    const channelSpecificNote = getChannelSpecificNote(options.channelType);
+    const bindingNote = options.includeBindingNote
+        ? `\n\n🔐 **绑定说明**：\n- 这条消息表示您的设备已和此 Agent 绑定\n- 只有您能看到和使用这个 Agent\n- AUN 提供端到端加密和跨设备同步`
+        : '';
+    return `🎉 欢迎使用 EvolCore！
+
+${greeting}
+
+${agentIntro}${channelInfo}
+
+📋 **日常使用方法**：
+
+1. **查看帮助**：发送 \`/help\` 查看所有可用命令
+2. **查看状态**：发送 \`/status\` 查看当前会话状态
+3. **会话管理**：发送 \`/session\` 查看和切换会话
+
+💡 **提示**：
+- 直接发送消息即可与 Claude/Codex 对话
+- 支持多会话管理，每个会话独立上下文
+- 所有命令以 \`/\` 开头${channelSpecificNote}${bindingNote}
+
+现在就可以开始工作了！`;
+}
+/**
+ * 生成简化版欢迎消息（用于快速场景）
+ */
+export function generateQuickWelcome(channelType, agentName) {
+    const channelDesc = getChannelDescription(channelType);
+    const intro = agentName ? `${agentName} 已连接` : '已连接';
+    return `👋 ${intro}到${channelDesc}！\n发送 /help 查看可用命令。`;
+}
+/**
+ * 生成 init 完成后的控制台提示消息
+ */
+export function generateInitSuccessMessage(channelType, hasOwner) {
+    const channelName = getChannelDescription(channelType);
+    // AUN 在 connect 时向 owner 发送欢迎消息
+    if (hasOwner && channelType === 'aun') {
+        return `\n💡 提示：首次启动时会向 owner 发送欢迎消息
+   启动服务: ec start`;
+    }
+    // Feishu 虽然有 owner，但已改为首次交互发送（与其他 IM 统一）
+    if (hasOwner && channelType === 'feishu') {
+        return `\n💡 提示：首次用户交互时会发送欢迎消息
+   启动服务: ec start`;
+    }
+    // 其他 IM 渠道：首次交互发送
+    if (hasOwner) {
+        return `\n💡 提示：${channelName}渠道已配置
+   启动服务: ec start`;
+    }
+    const ownerHint = channelType === 'aun'
+        ? `   配置 owner: ec init ${channelType}`
+        : '   配置 owner: 在 agent config.json 的 owners 中写入 AID；非 AUN 渠道身份写入 contact.json';
+    // 无 owner 的渠道
+    return `\n💡 提示：${channelName}渠道已配置
+   启动服务: ec start
+${ownerHint}`;
+}
+/**
+ * 获取渠道的中文描述
+ */
+function getChannelDescription(channelType) {
+    switch (channelType) {
+        case 'aun':
+            return 'AUN 网络';
+        case 'feishu':
+            return '飞书';
+        case 'wechat':
+            return '微信';
+        case 'dingtalk':
+            return '钉钉';
+        case 'qqbot':
+            return 'QQ';
+        case 'wecom':
+            return '企业微信';
+        default:
+            return '未知渠道';
+    }
+}
+/**
+ * 获取渠道特定的额外说明
+ */
+function getChannelSpecificNote(channelType) {
+    switch (channelType) {
+        case 'aun':
+            return '\n- AUN 提供端到端加密和跨设备同步';
+        case 'feishu':
+            return '\n- 群聊中使用 @机器人 来触发对话';
+        case 'wechat':
+            return '';
+        case 'dingtalk':
+            return '\n- 群聊中使用 @机器人 来触发对话';
+        case 'qqbot':
+            return '\n- 群聊中使用 @机器人 来触发对话';
+        case 'wecom':
+            return '';
+        default:
+            return '';
+    }
+}
+// ============================================================================
+// 欢迎消息管理器
+// ============================================================================
+/**
+ * 标记 agent 已初始化
+ */
+export function markAgentInitialized(agentAid) {
+    const agentConfig = loadAgent(agentAid);
+    if (agentConfig) {
+        saveAgent(withLifecycleForWrite(agentConfig, 'active'));
+        logger.info(`[WelcomeManager] Marked ${agentAid} lifecycle=active`);
+    }
+}
+/**
+ * 首次交互欢迎消息管理器（用于所有 IM 渠道：Feishu/WeChat/DingTalk/QQBot/WeCom）
+ */
+export class FirstInteractionWelcomeManager {
+    channelType;
+    agentAid;
+    channelName;
+    greetedUsersFile;
+    greetedUsers = new Set();
+    initializedCache = null; // 缓存 initialized 状态，避免重复 I/O
+    constructor(channelType, agentAid, channelName) {
+        this.channelType = channelType;
+        this.agentAid = agentAid;
+        this.channelName = channelName;
+        // 每个 channel instance 独立的已欢迎用户记录
+        this.greetedUsersFile = path.join(resolvePaths().dataDir, `${channelType}-greeted-${channelName}.jsonl`);
+        this.loadGreetedUsers();
+    }
+    /**
+     * 检查是否应该向该用户发送欢迎消息
+     */
+    shouldGreet(userId) {
+        // 懒加载并缓存 initialized 状态（避免每条消息都读取磁盘）
+        if (this.initializedCache === null) {
+            const agentConfig = loadAgent(this.agentAid);
+            this.initializedCache = agentConfig?.lifecycle === 'active';
+        }
+        // Agent 已初始化 → 所有用户都不需要欢迎消息
+        if (this.initializedCache) {
+            return false;
+        }
+        // 该用户未被欢迎过
+        return !this.greetedUsers.has(userId);
+    }
+    /**
+     * 生成欢迎消息文本
+     */
+    generateWelcomeText() {
+        const agentName = this.agentAid.split('.')[0];
+        return generateWelcomeMessage({
+            channelType: this.channelType,
+            agentName,
+        });
+    }
+    /**
+     * 标记用户已被欢迎
+     */
+    markGreeted(userId) {
+        if (this.greetedUsers.has(userId))
+            return;
+        this.greetedUsers.add(userId);
+        this.persistGreetedUser(userId);
+        // 首个用户被欢迎后，标记 agent 已初始化
+        if (this.greetedUsers.size === 1) {
+            markAgentInitialized(this.agentAid);
+        }
+    }
+    /**
+     * 持久化已欢迎用户到文件
+     */
+    persistGreetedUser(userId) {
+        try {
+            const record = { userId, timestamp: Date.now() };
+            fs.appendFileSync(this.greetedUsersFile, JSON.stringify(record) + '\n', 'utf-8');
+        }
+        catch (e) {
+            logger.warn(`[WelcomeManager] Failed to persist greeted user: ${e}`);
+        }
+    }
+    /**
+     * 从文件加载已欢迎用户列表
+     */
+    loadGreetedUsers() {
+        if (!fs.existsSync(this.greetedUsersFile))
+            return;
+        try {
+            const content = fs.readFileSync(this.greetedUsersFile, 'utf-8');
+            const lines = content.split('\n').filter(Boolean);
+            for (const line of lines) {
+                try {
+                    const { userId } = JSON.parse(line);
+                    if (userId)
+                        this.greetedUsers.add(userId);
+                }
+                catch {
+                    // 忽略损坏的行
+                }
+            }
+            if (this.greetedUsers.size > 0) {
+                logger.debug(`[WelcomeManager] Loaded ${this.greetedUsers.size} greeted users for ${this.channelName}`);
+            }
+        }
+        catch (e) {
+            logger.warn(`[WelcomeManager] Failed to load greeted users: ${e}`);
+        }
+    }
+}
+// ============================================================================
+// 渠道帮助函数
+// ============================================================================
+/**
+ * 初始化欢迎消息管理器（同步方式，避免竞态条件）
+ */
+export function initWelcomeManager(channelType, agentAid, channelName) {
+    return new FirstInteractionWelcomeManager(channelType, agentAid, channelName);
+}
+/**
+ * 发送欢迎消息（如果需要）
+ *
+ * @param welcomeManager 欢迎消息管理器实例
+ * @param userId 用户 ID
+ * @param channelId 渠道 ID（消息发送目标）
+ * @param sendMessage 发送消息的函数
+ * @param channelName 渠道名称（用于日志）
+ * @returns 是否发送了欢迎消息
+ */
+export async function sendWelcomeIfNeeded(welcomeManager, userId, channelId, sendMessage, channelName) {
+    void welcomeManager;
+    void userId;
+    void channelId;
+    void sendMessage;
+    void channelName;
+    return false;
+}

package/kits/docs/GUIDE.md

@@ -0,0 +1,20 @@
+# 文档查阅指南
+
+## 查阅流程
+
+1. 先看 `$KITS_RULES`（自动加载的 6 个规则文件 01-06）了解机制骨架
+2. 需要详细信息时，按 `INDEX.md` 找到对应文档路径
+3. Read 对应文档
+
+## 路径解析
+
+文档中用 `$名称` 引用路径。解析步骤：
+1. 查 `$KITS_RULES/02-navigation.md` 的路径体系速查表
+2. 如需完整定义，Read `$KITS_DOCS/path-registry.md`
+3. 如需运行时实际值，Read `$ECK/path-registry.md`
+
+## 不要做的事
+
+- 不要一次性加载所有文档——按需逐个 Read
+- 不要猜测路径——查注册表
+- 不要在当前会话输出对外消息——用 CLI

package/kits/docs/INDEX.md

@@ -0,0 +1,65 @@
+# EvolCore 文档索引
+
+本文件是 `$KITS_DOCS` 下所有文档的索引。
+
+## 路径与机制
+
+| 文档 | 路径 | 说明 |
+|------|------|------|
+| 查阅指南 | `GUIDE.md` | 文档查阅流程 |
+| 路径定义 | `path-registry.md` | 所有预定义路径及派生规则 |
+| 上下文组装机制 | `context-assembly.md` | manifest 装配机制：when 条件/合并覆盖/模板渲染/运行时变量/调试输出 |
+
+## AUN 协议
+
+| 文档 | 路径 | 说明 |
+|------|------|------|
+| 速查表 | `aun/CHEATSHEET.md` | AUN 协议命名空间与常用操作速查 |
+| 同步协议 | `aun/SYNC_PROTOCOL.md` | 上游协议同步 SOP |
+
+## EvolCore 命令
+
+所有 `ec` 命令集的专属目录（用途/触发词/适用场景/文档）见 `evolcore/INDEX.md`。
+运行时由 `commands` fragment 按场景注入精简能力卡。
+
+| 文档 | 路径 | 说明 |
+|------|------|------|
+| 命令集目录 | `evolcore/INDEX.md` | msg/group/agent/aid/storage/ctl/rpc/bench 全集索引 |
+
+## 身份
+
+| 文档 | 路径 | 说明 |
+|------|------|------|
+| 身份工具 | `identity/identity-tools.md` | 身份识别与环境层工具 |
+| 角色详情 | `identity/ROLE_DETAIL.md` | 角色与场景详细规则 |
+| AID 档案规范 | `identity/AID_PROFILE_SPEC.md` | AID 档案格式规范 |
+| 路径运维 | `identity/PATH_OPS.md` | 路径运维操作 |
+
+## 渠道（知识文档·按需加载，不依赖当前渠道）
+
+| 文档 | 路径 | 说明 |
+|------|------|------|
+| AUN 渠道 | `channels/aun.md` | AUN 渠道配置、参数与特有机制（网关发现/E2EE/群 ID/证书链） |
+| 飞书渠道 | `channels/feishu.md` | 飞书渠道配置、参数与特有机制（appId/合并转发/卡片/user_id） |
+
+## 触发器
+
+| 文档 | 路径 | 说明 |
+|------|------|------|
+| Trigger 命令手册 | `evolcore/trigger.md` | 创建、管理、运行定时与事件 trigger |
+| EventBus 事件目录 | `evolcore/event.md` | event source 可监听事件、payload、filter 与循环防护规则 |
+
+## ECK 模板
+
+| 文档 | 路径 | 说明 |
+|------|------|------|
+| 运行时配置模板 | `eck_templates/runtime.template.md` | agent 运行时配置模板 |
+| 路径注册表模板 | `eck_templates/path-registry.template.md` | 路径实例模板 |
+| 索引模板 | `eck_templates/INDEX.template.md` | agent 级索引模板 |
+| 指南模板 | `eck_templates/GUIDE.template.md` | agent 级查阅指南模板 |
+
+## Base Agent
+
+| 文档 | 路径 | 说明 |
+|------|------|------|
+| Claude Code 日志 | `baseagent/cc-logs.md` | CC 会话日志查阅（找完整对话/工具调用/注入） |

package/kits/docs/aun/CHEATSHEET.md

@@ -0,0 +1,19 @@
+# AUN 协议速查表
+
+## 命名空间
+
+| 命名空间 | 作用 |
+|---|---|
+| `auth.*` | AID 创建、认证、JWT |
+| `message.*` | 点对点消息收发 |
+| `group.*` | 群组生命周期、群消息 |
+| `storage.*` | 文件上传下载 |
+| `stream.*` | 实时流（语音/视频/token） |
+| `meta.*` | ping、状态、信任根查询 |
+| `nameservice.*` | AID 名字注册查询 |
+| `custody.*` | AID 托管 |
+| `peer.*` / `relay.*` | 直连/中继认证 |
+
+## Group 使用入口
+
+日常群操作使用 `ec group`，详见 `evolcore/group.md`。群文件使用 `ec fs`，详见 `evolcore/fs.md`。

package/kits/docs/aun/SYNC_PROTOCOL.md

@@ -0,0 +1,15 @@
+# AUN 协议同步 SOP
+
+<!-- TODO: 填充上游协议同步流程 -->
+
+## 同步时机
+
+- AUN SDK 有新版本发布时
+- 协议文档有重大变更时
+
+## 同步步骤
+
+1. 拉取上游最新协议文档
+2. 对比本地认知包与上游差异
+3. 更新 `$KITS_RULES/04-aun.md` 和 `$KITS_DOCS/aun/` 下相关文档
+4. 更新索引

package/kits/docs/channels/aun.md

@@ -0,0 +1,65 @@
+# AUN 渠道
+
+> 知识性文档：AUN 渠道的配置、参数与特有机制。**不依赖当前会话渠道**——任意会话都可按需 Read。
+> 运行时"怎么发消息"由注入的 `[channel]` 段决定（aun 渠道用 `ec msg send` / `ec group send`），不在本文。
+> 群聊使用 `evolcore/group.md`；群文件使用 `evolcore/fs.md`。
+
+## 概述
+
+AUN 渠道把 agent 接入 AUN（Agent Union Network），对端以 **AID** 为身份标识（既是身份也是地址）。evolcore 通过 AUN SDK（`@agentunion/fastaun`）维护到 Gateway 的 WebSocket 长连接，支持私聊、群聊、文件、E2EE 加密。
+
+## 配置
+
+AUN 渠道是**隐式**的——它不写在 `channels[]` 数组里，而是从 agent 自身的 AID 自动创建。一个 agent 就是一个 AID，启动时 evolcore 用顶层 `aid` 字段隐式构造唯一的 aun 实例（`channel-loader.ts`）。所以真实的 agent config.json 里 `channels` 数组通常是空的（飞书等非 aun 渠道才往里加）。
+
+### agent 配置（`agents/<aid>/config.json`）
+
+```json
+{
+  "$schema_version": 1,
+  "aid": "myagent.agentid.pub",
+  "enabled": true,
+  "owners": ["owner.agentid.pub"],
+  "channels": [],
+  "active_baseagent": "claude"
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `aid` | agent 的 AID，**即 aun 渠道身份**（隐式创建，无需在 channels[] 声明） |
+| `enabled` | agent 是否启用 |
+| `owners` | owner 的 **AID** 列表（最高权限）；首个 owner 用于首次连接发欢迎消息 |
+| `admins` | admin 的 AID 列表 |
+| `channels` | 非 aun 渠道（飞书等）的实例数组；aun 不在此 |
+
+> `owners`/`admins` 用 **AID**，不是渠道原生 ID。
+
+### 进程级配置（`$EVOLCORE_HOME/config.json`）
+
+E2EE 加密种子是**进程级**的，所有 agent 共享，不在 agent config 里：
+
+```json
+{
+  "aun": {
+    "encryptionSeed": "<seed>"
+  }
+}
+```
+
+留空时 SDK 依次回退 `AUN_ENCRYPTION_SEED` 环境变量 → 默认 `'evol'`。
+
+> Gateway 不在配置里手填：连接时从 AID 自动发现（见下）。Keystore 默认落在 `$EVOLCORE_HOME`。
+
+## 特有机制
+
+- **隐式创建**：aun 渠道由顶层 `aid` 派生，无独立配置实例；这是它与飞书等渠道最大的不同。
+- **网关发现**：连接前查询 `https://<aid>/.well-known/aun-gateway` 获取网关地址（AID 本身即域名）；per-agent 流程不提供手填 gateway 的入口，发现失败即连接失败。
+- **身份与信任**：每条入站消息携带发送者 AID，经四级 X.509 证书链（Root CA → Registry CA → Issuer CA → Agent）验签。
+- **agent.md 缓存**：对端名片 `https://<aid>/agent.md` 由 **AUN SDK 自动拉取并缓存**（`AgentMdManager`，带 ETag/TTL，默认 1 天内不重复探测）。缓存落在 **`$EVOLCORE_HOME/AIDs/<aid>/`**，每个 AID 两个文件：`agent.md`（带签名正文）+ `agentmd.json`（元数据：etag/last_modified/checked_at/verify_status）。本端与对端的 agent.md 都缓存于此。
+  - 关系层另存一份**派生**的精简身份 `relations/<peerKey>/peer-identity.json`（type/isAgent/name），由 evolcore 从 agent.md 提取，不是 agent.md 本体。
+- **E2EE 加密**：可选端到端加密，回复默认跟随对端消息加密状态（密文回密文，明文回明文）；种子由进程级 `aun.encryptionSeed` 提供。
+- **断线重连**：SDK 内置退避策略自动重连。实时连接状态用 `ec watch aid` 查看（`ec aid` 是身份/证书管理，不显示连接状态）。
+- **群 ID 格式**：当前协议规范使用 `g-{slug}.issuer-domain` canonical 形式，输入也可接受本域简写 `g-{slug}` 或兼容形式 `g-{slug}@issuer-domain`。历史会话里可能仍出现 `group.{issuer}/{group_no}` 一类旧格式，运行时需兼容读取。
+- **群分发模式**：`dispatch_mode=broadcast|mention` 是群级配置，只决定哪些群消息进入 Agent LLM 上下文，不影响 AUN 协议层投递；被过滤消息仍应本地存档。
+- **身份体系**：对端以 AID 标识，关系层 peerKey 形如 `aun#alice.aid.pub`。

package/kits/docs/channels/feishu.md

@@ -0,0 +1,56 @@
+# 飞书渠道
+
+> 知识性文档：飞书渠道的配置、参数与特有机制。**不依赖当前会话渠道**——任意会话都可按需 Read（在 aun 会话里也可查飞书）。
+> 运行时"怎么发消息"由注入的 `[channel]` 段决定（飞书是 evolcore 自动回复，agent 不调 CLI），不在本文。
+
+## 概述
+
+飞书渠道通过 evolcore 的 feishu channel 插件接入，对端以飞书 `user_id`（如 `ou_xxx`）为身份标识。支持单聊/群聊收发、合并转发解析、富文本卡片、文件/图片/视频消息。
+
+## 配置
+
+飞书渠道按 **per-agent** 配置，写在 `agents/<aid>/config.json` 的 `channels` 数组里。每个元素是一个独立实例，靠 `name` 区分；同一 agent 可配多个飞书实例。
+
+```json
+{
+  "aid": "myagent.aid.pub",
+  "channels": [
+    {
+      "type": "feishu",
+      "name": "main",
+      "enabled": true,
+      "appId": "cli_xxx",
+      "appSecret": "<app-secret>",
+      "owners": ["ou_owner_user_id"],
+      "admins": ["ou_admin_user_id"]
+    }
+  ]
+}
+```
+
+### 实例字段
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `type` | 是 | 固定 `"feishu"` |
+| `name` | 是（数组形式） | 该 agent 内飞书实例的本地标识，不含 `#` |
+| `enabled` | 否 | 默认启用；`false` 关闭该实例 |
+| `appId` | 是 | 飞书自建应用 App ID |
+| `appSecret` | 是 | 飞书自建应用 App Secret |
+| `owners` | 否 | owner 的飞书 `user_id` 列表（最高权限） |
+| `admins` | 否 | admin 的飞书 `user_id` 列表 |
+| `flushDelay` | 否 | flush 间隔（秒），覆盖全局值 |
+| `debounce` | 否 | 入站消息去抖间隔（秒），覆盖全局值 |
+| `showActivities` | 否 | 思考过程展示范围：`all` / `dm-only` / `owner-dm-only` / `none` |
+
+> `owners`/`admins` 用飞书原生 `user_id`，**不是 AID**。
+
+agent 级（config.json 顶层）相关开关：
+- `enable_rich_content`：已废弃，仅为旧配置兼容保留；飞书继续按 Markdown/post 消息发送。
+
+## 特有机制
+
+- **合并转发解析**：飞书的 `merge_forward` 消息会被自动展开为文本注入上下文（含"以下是引用的原消息"包裹）。
+- **交互卡片**：命令和交互请求可使用飞书卡片发送；卡片按钮**仅发起者可操作**，他人点击返回提示。
+- **身份体系**：对端以 `user_id` 标识，关系层 peerKey 形如 `feishu#ou_xxx`。
+- **自动回复**：飞书是非 aun 渠道，回复由 evolcore 自动完成，agent 无需调用 `ec msg send`。