evolcore 0.0.3 → 0.0.5

package/MIGRATION-0.5.0.md

@@ -1,378 +0,0 @@
-# Evolcore 0.5.0 迁移指南
-
-> 版本：0.5.0
-> 发布日期：2026-06-19
-> 重大变更：配置系统 v3 重构 + 类型系统简化
-
----
-
-## 概述
-
-0.5.0 版本对配置系统进行了重大重构，主要变更：
-
-1. **删除 behavior.json** - 所有参数统一在 config.json
-2. **删除 BehaviorConfig 类型** - 统一使用 AgentConfig/EffectiveAgentConfig
-3. **删除 MergedAgentConfig 类型** - 统一使用 EffectiveAgentConfig
-4. **简化覆盖链** - defaults → agent/config → relation/config
-
----
-
-## 破坏性变更
-
-### 1. behavior.json 已删除
-
-**变更说明**：
-- ❌ 不再有 `agents/<aid>/behavior.json`
-- ❌ 不再有 `agents/<aid>/relations/<peerKey>/preferences.json`
-- ✅ 所有参数统一在 `config.json`
-
-**迁移步骤**：
-
-#### 如果你有自定义的 behavior.json：
-
-**原文件结构**：
-```
-agents/mybot.agent/
-├── config.json       # 身份、凭证、渠道
-└── behavior.json     # 模型、对话模式、权限
-```
-
-**新文件结构**：
-```
-agents/mybot.agent/
-└── config.json       # 所有参数统一
-```
-
-**手动合并示例**：
-
-```json
-// 原 config.json（身份信息）
-{
-  "aid": "mybot.agent",
-  "owners": ["admin.user"],
-  "channels": [...]
-}
-
-// 原 behavior.json（行为参数）
-{
-  "active_baseagent": "claude",
-  "baseagents": {
-    "claude": { "model": "opus-4.8", "effort": "high" }
-  },
-  "chatmode": { "private": "proactive" }
-}
-
-// 合并后的 config.json
-{
-  "aid": "mybot.agent",
-  "owners": ["admin.user"],
-  "channels": [...],
-  "active_baseagent": "claude",
-  "baseagents": {
-    "claude": { "model": "opus-4.8", "effort": "high" }
-  },
-  "chatmode": { "private": "proactive" }
-}
-```
-
-**自动迁移**：
-- 启动时会自动检测并合并 behavior.json 到 config.json
-- 迁移后 behavior.json 会被重命名为 `.migrated-to-config`
-
-#### 如果你有关系级 preferences.json：
-
-**原路径**：`agents/<aid>/relations/<peerKey>/preferences.json`
-
-**新路径**：`agents/<aid>/relations/<peerKey>/config.json`
-
-**迁移**：
-- 自动迁移，将 preferences.json 合并到 config.json
-- 原文件重命名为 `.migrated-to-config`
-
----
-
-### 2. BehaviorConfig 类型已删除
-
-**变更说明**：
-- ❌ `BehaviorConfig` 接口已删除
-- ✅ 使用 `AgentConfig`（存储层）或 `EffectiveAgentConfig`（运行时）
-
-**如果你的代码引用了 BehaviorConfig**：
-
-```typescript
-// ❌ 旧代码
-import type { BehaviorConfig } from 'evolcore/types';
-
-function updateBehavior(config: BehaviorConfig) {
-  // ...
-}
-
-// ✅ 新代码（完整配置）
-import type { AgentConfig } from 'evolcore/types';
-
-function updateBehavior(config: AgentConfig) {
-  // ...
-}
-
-// ✅ 新代码（只需要部分字段）
-import type { AgentConfig } from 'evolcore/types';
-
-function updateBehavior(config: Partial<AgentConfig>) {
-  // ...
-}
-
-// ✅ 新代码（运行时合并结果）
-import type { EffectiveAgentConfig } from 'evolcore/types';
-
-function getBehavior(): EffectiveAgentConfig {
-  // ...
-}
-```
-
-**常见场景替换表**：
-
-| 原用途 | 旧类型 | 新类型 |
-|--------|--------|--------|
-| 读取 agent 配置 | `BehaviorConfig` | `AgentConfig` |
-| 读取关系级配置 | `BehaviorConfig` | `RelationConfig` |
-| 运行时合并结果 | `BehaviorConfig` | `EffectiveAgentConfig` |
-| 部分配置更新 | `Partial<BehaviorConfig>` | `Partial<AgentConfig>` |
-| 只需要特定字段 | `Pick<BehaviorConfig, 'model' \| 'chatmode'>` | `Pick<AgentConfig, 'model' \| 'chatmode'>` |
-
----
-
-### 3. MergedAgentConfig 类型已删除
-
-**变更说明**：
-- ❌ `MergedAgentConfig` 类型已删除
-- ✅ 使用 `EffectiveAgentConfig`
-
-**如果你的代码引用了 MergedAgentConfig**：
-
-```typescript
-// ❌ 旧代码
-import type { MergedAgentConfig } from 'evolcore/types';
-
-function processConfig(config: MergedAgentConfig) {
-  // ...
-}
-
-// ✅ 新代码
-import type { EffectiveAgentConfig } from 'evolcore/types';
-
-function processConfig(config: EffectiveAgentConfig) {
-  // ...
-}
-```
-
-**说明**：
-- `MergedAgentConfig` 曾是 `AgentConfig & BehaviorConfig` 的合并类型
-- v3 重构后简化为 `EffectiveAgentConfig` 的别名
-- 现在直接使用 `EffectiveAgentConfig` 更清晰
-
----
-
-### 4. mergeForAgent() 已弃用
-
-**变更说明**：
-- ⚠️ `mergeForAgent()` 标记为 `@deprecated`
-- ✅ 使用 `ConfigManager.resolveEffective()`
-
-**如果你的代码调用了 mergeForAgent**：
-
-```typescript
-// ❌ 旧代码
-import { mergeForAgent, loadAgent, loadDefaults } from 'evolcore';
-
-const agent = loadAgent('mybot.agent');
-const defaults = loadDefaults();
-const merged = mergeForAgent(agent, defaults);
-
-// ✅ 新代码
-import { resolveEffective } from 'evolcore/config/config-manager';
-
-const effective = resolveEffective({ self: 'mybot.agent' });
-```
-
-**说明**：
-- `mergeForAgent()` 仍可用但已弃用，计划 v2.2 删除
-- `resolveEffective()` 是唯一的合并入口，支持完整覆盖链
-
----
-
-## 新功能
-
-### 1. 统一的配置覆盖链
-
-**覆盖链（优先级从低到高）**：
-```
-defaults → agent/config → relation/config
-```
-
-**示例**：
-
-```typescript
-import { resolveEffective } from 'evolcore/config/config-manager';
-
-// Agent 级配置
-const agentConfig = resolveEffective({ 
-  self: 'mybot.agent' 
-});
-
-// 关系级配置（针对特定用户）
-const relationConfig = resolveEffective({ 
-  self: 'mybot.agent',
-  peerKey: 'user123.user@channel'
-});
-```
-
-### 2. 角色级覆盖（新增）
-
-**在 config.json 中定义角色**：
-
-```json
-{
-  "aid": "mybot.agent",
-  "active_baseagent": "claude",
-  "baseagents": {
-    "claude": { "model": "sonnet-4.6" }
-  },
-  "roles": {
-    "power-user": {
-      "baseagents": {
-        "claude": { "model": "opus-4.8", "effort": "high" }
-      },
-      "permissionMode": "owner"
-    }
-  }
-}
-```
-
-**运行时解析**：
-
-```typescript
-import { resolveEffective } from 'evolcore/config/config-manager';
-
-// 普通用户
-const normalConfig = resolveEffective({ 
-  self: 'mybot.agent',
-  peerKey: 'user1.user@channel'
-});
-// → model: "sonnet-4.6"
-
-// Power user
-const powerConfig = resolveEffective({ 
-  self: 'mybot.agent',
-  peerKey: 'user2.user@channel',
-  role: 'power-user'
-});
-// → model: "opus-4.8", effort: "high"
-```
-
----
-
-## 非破坏性变更
-
-### 1. 配置文件格式兼容
-
-**旧格式仍然支持**：
-- 如果只有 config.json（身份字段），仍然有效
-- 如果有 behavior.json，会自动合并
-- 如果有 preferences.json，会自动迁移
-
-### 2. API 保持兼容
-
-**这些函数签名未变**：
-- `loadAgent(aid)` - 返回 AgentConfig
-- `loadDefaults()` - 返回 DefaultsConfig
-- `loadAllAgents()` - 返回 AgentConfig[]
-
-**这些属性未变**：
-- `EvolAgent.config` - 返回运行时配置（类型从 MergedAgentConfig 改为 EffectiveAgentConfig，字段不变）
-- `AgentInfo.config` - 同上
-
----
-
-## 检查清单
-
-迁移到 0.5.0 时，检查以下内容：
-
-### 配置文件
-
-- [ ] 确认 behavior.json 已自动合并到 config.json
-- [ ] 确认 preferences.json 已自动迁移到 config.json
-- [ ] 检查 config.json 是否包含所有必要字段
-
-### TypeScript 代码
-
-- [ ] 将 `BehaviorConfig` 替换为 `AgentConfig` 或 `EffectiveAgentConfig`
-- [ ] 将 `MergedAgentConfig` 替换为 `EffectiveAgentConfig`
-- [ ] 将 `mergeForAgent()` 替换为 `resolveEffective()`
-- [ ] 运行 TypeScript 编译检查类型错误
-
-### 运行时测试
-
-- [ ] 启动 agent，确认配置正确加载
-- [ ] 测试模型切换功能
-- [ ] 测试对话模式切换
-- [ ] 测试关系级配置覆盖
-
----
-
-## 常见问题
-
-### Q1: 我的 behavior.json 会丢失吗？
-
-**A**: 不会。
-- 自动迁移会合并到 config.json
-- 原 behavior.json 重命名为 `.migrated-to-config`
-- 如果合并失败，会保留原文件并记录错误日志
-
-### Q2: 我需要手动更新配置文件吗？
-
-**A**: 不需要。
-- 启动时自动检测并迁移
-- 迁移成功后自动保存
-- 只需确认迁移日志无错误
-
-### Q3: 类型错误如何修复？
-
-**A**: 按上述替换表修改：
-```typescript
-// BehaviorConfig → AgentConfig / EffectiveAgentConfig
-// MergedAgentConfig → EffectiveAgentConfig
-```
-
-### Q4: mergeForAgent() 什么时候会删除？
-
-**A**: 计划 v2.2 删除。
-- 当前版本仍可用（已弃用）
-- 建议尽快迁移到 `resolveEffective()`
-
-### Q5: 如何回退到旧版本？
-
-**A**: 
-```bash
-npm install evolcore@0.4.x
-```
-- 如果已迁移，需要手动还原配置文件
-- 建议迁移前备份 agents/ 目录
-
----
-
-## 获取帮助
-
-如果遇到迁移问题：
-
-1. **查看日志**：`~/.evolcore/logs/boot.log`
-2. **查看文档**：`docs/config/`
-3. **提交 Issue**：https://github.com/your-org/evolcore/issues
-
----
-
-## 相关文档
-
-- [配置系统概览](docs/config/01-overview.md)
-- [合并规则](docs/config/02-merge-rules.md)
-- [配置 Schema](docs/config/03-schema.md)
-- [BehaviorConfig 删除报告](docs/config/behaviorconfig-mergedconfig-removal-completion.md)

package/ROLE_ACCESS_CONTROL.md

@@ -1,174 +0,0 @@
-# 角色访问控制功能实现总结
-
-## 新增功能
-
-### 1. 默认角色 (defaultRole)
-- **位置**: 全局配置 (`roles.json` 顶层字段)
-- **默认值**: `'anonymous'`
-- **语义**: 对端 AID 首次访问时，若不在 `owners/admins/members` 名单中，使用此角色作为兜底
-- **UI**: ecweb 角色定义页面顶部下拉选择器，change 时自动保存
-
-### 2. 是否允许访问 (allowAccess)
-- **位置**: 每个角色定义的顶层字段 (与 `description`/`permissions` 同级)
-- **默认值**:
-  - `anonymous`: `false` (拒绝访问)
-  - 其他角色 (`owner/admin/member/guest`): `true` (允许访问)
-- **语义**: 当角色的 `allowAccess=false` 时，该角色用户访问 agent 会被直接拦截
-- **拦截行为**: 返回系统错误消息 "暂无权限访问本 agent，请联系 agent 管理员授权访问"
-- **UI**: ecweb 角色编辑/新建弹窗中，描述下方的下拉选择器 (允许 true / 拒绝 false)
-
-## 实现架构
-
-### Backend 改动
-
-#### 1. Schema 升级 (v1 → v2)
-- `kits/schemas/roles.schema.2.json` — 新增 `defaultRole` (top-level) 和 `allowAccess` (per-role)
-- `kits/schemas/_meta.json` — currentVersion 更新为 2
-- **迁移逻辑** (`src/config/config-manager.ts`):
-  - `migrateRolesV1toV2()` — 直接升版本号，新字段由 merge 时从 builtin 补全 (overlay 模式)
-
-#### 2. 类型定义 (`src/types.ts`)
-```typescript
-export interface RolesConfig {
-  $schema_version: number;
-  defaultRole?: string;  // 新增
-  roles: Record<string, RoleDefinition>;
-}
-
-export interface RoleDefinition {
-  description: string;
-  allowAccess?: boolean;  // 新增
-  permissions: Record<string, FieldPermission>;
-}
-```
-
-#### 3. 内置配置 (`src/config/roles.ts`)
-- `getBuiltinRolesConfig()` 升级为 `$schema_version: 2`
-- 添加 `defaultRole: 'anonymous'`
-- 每个角色添加 `allowAccess` 字段 (owner/admin/member/guest 为 `true`, anonymous 为 `false`)
-
-#### 4. 角色解析器 (`src/config/role-resolver.ts`)
-- `resolveUserRole()` 返回类型改为 `string` (支持自定义角色名)
-- 移除 `isAuthenticated()` 判断，改为直接使用 `getDefaultRole()` 作为兜底
-- **新增** `getDefaultRole()` — 从 roles.json 读取 `defaultRole` 字段
-- **新增** `checkRoleAccess(role: string): boolean` — 读取该角色的 `allowAccess` 配置
-
-#### 5. 合并/Diff 逻辑 (`src/config/roles-merge.ts`)
-- `mergeRolesConfig()` — 合并 `defaultRole` (overlay 优先) 和每个角色的 `allowAccess`
-- `diffRolesConfig()` — 比对 `defaultRole` 和 `allowAccess`，仅写入改动
-
-#### 6. 访问控制拦截 (`src/core/message/response-engine.ts`)
-- `processMessage()` 入口处，在 `resolveSession()` 之后立即检查
-- 调用 `checkRoleAccess(userRole)`，为 `false` 时:
-  1. 记录 warn 日志
-  2. 通过 `adapter.send()` 回复 `system.error` 类型消息
-  3. `return` 终止处理，不进入后续流程
-
-### Frontend 改动 (ecweb)
-
-#### 1. HTML 结构 (`ecweb/src/static/index.html`)
-- 新增 `.role-default-selector` 区块 (在 header 和 grid 之间)
-- 包含 `<select id="default-role-select">` 和提示文案
-
-#### 2. JavaScript (`ecweb/src/static/app.js`)
-- `renderRoleDefinitions()` — 调用 `renderDefaultRoleSelector(data)` 填充下拉框
-- **新增** `renderDefaultRoleSelector()`:
-  - 填充所有角色为选项
-  - 绑定 `onchange` 事件 → 读取完整配置 → 更新 `defaultRole` → PUT 写回
-- `showRoleEditModal()` / `showNewRoleModal()` — 在 description 后添加 `allowAccess` 下拉
-- `saveRoleEdit()` — 收集 `allowAccess` 值 (转为真布尔), 写入 `updates` 对象
-
-#### 3. CSS (`ecweb/src/static/style.css`)
-- 新增 `.role-default-selector` / `.role-default-label` 样式
-- 原有按钮样式已是黑边框黑字 (`var(--fg)` / `var(--border)`)，无需修改
-
-## 配置示例
-
-### roles.json (用户 overlay)
-```json
-{
-  "$schema_version": 2,
-  "defaultRole": "guest",
-  "roles": {
-    "anonymous": {
-      "description": "匿名用户，完全未认证，极度受限",
-      "allowAccess": false
-    },
-    "guest": {
-      "description": "访客，只读权限，有身份但未授权",
-      "allowAccess": true
-    }
-  }
-}
-```
-
-### 内置基线 (builtin)
-```javascript
-{
-  $schema_version: 2,
-  defaultRole: 'anonymous',
-  roles: {
-    owner: { allowAccess: true, ... },
-    admin: { allowAccess: true, ... },
-    member: { allowAccess: true, ... },
-    guest: { allowAccess: true, ... },
-    anonymous: { allowAccess: false, ... }
-  }
-}
-```
-
-## 升级路径
-
-1. **v1 → v2 自动迁移**:
-   - 读取 v1 roles.json 时，`migrateRolesV1toV2()` 自动升版本号
-   - `defaultRole` 和 `allowAccess` 字段从 builtin 继承 (overlay 为空时)
-   - 原有用户改动 (permissions/description) 完整保留
-
-2. **向后兼容**:
-   - `defaultRole` 缺失时默认 `'anonymous'` (原有行为)
-   - `allowAccess` 缺失时默认 `true` (除 anonymous 为 `false`)
-   - 旧代码不读这两个字段时，功能降级但不报错
-
-## 测试要点
-
-1. **默认角色生效**:
-   - 清空某 agent 的 owners/admins/members
-   - 对端 AID 访问时，角色应为 `roles.json` 中的 `defaultRole`
-
-2. **访问控制拦截**:
-   - 设置某角色 `allowAccess: false`
-   - 将用户加入该角色 (如 guest)
-   - 用户访问时应收到 "暂无权限" 系统错误，后续流程不触发
-
-3. **ecweb UI**:
-   - 默认角色下拉能正常切换并保存
-   - 编辑角色时，`allowAccess` 下拉能正确读取/保存
-   - 保存按钮为黑边框黑字 (非白色)
-
-4. **Schema 迁移**:
-   - 备份旧 roles.json (v1)
-   - 启动新版本，读取时自动升级为 v2
-   - 原有改动不丢失，新字段从 builtin 补全
-
-## 文件清单
-
-### Backend
-- `kits/schemas/roles.schema.2.json` (新增)
-- `kits/schemas/_meta.json` (修改 - 版本号)
-- `src/types.ts` (修改 - RolesConfig/RoleDefinition)
-- `src/config/roles.ts` (修改 - builtin 配置)
-- `src/config/role-resolver.ts` (修改 - 添加 checkRoleAccess)
-- `src/config/roles-merge.ts` (修改 - merge/diff 逻辑)
-- `src/config/config-manager.ts` (修改 - 迁移函数)
-- `src/core/message/response-engine.ts` (修改 - 访问拦截)
-
-### Frontend (ecweb)
-- `ecweb/src/static/index.html` (修改 - 默认角色选择器)
-- `ecweb/src/static/app.js` (修改 - render/save 逻辑)
-- `ecweb/src/static/style.css` (修改 - 样式)
-
----
-
-**实现完成时间**: 2026-06-25  
-**Schema 版本**: roles v2  
-**向后兼容**: ✅ (v1 自动迁移，字段缺失时使用默认值)

package/dist/channels/contact-bind-code.js

@@ -1,134 +0,0 @@
-import { randomInt } from 'crypto';
-import { isValidAid } from '../aun/aid/validation.js';
-import { bindContactAlias } from '../config/contact-book.js';
-export const CONTACT_BIND_CODE_TTL_MS = 10 * 60 * 1000;
-export const CONTACT_BIND_MAX_FAILED_ATTEMPTS = 5;
-/** In-memory, one-time channel identity proof used before writing a Contact alias. */
-export class ContactBindCodeRegistry {
-    options;
-    pending = new Map();
-    constructor(options) {
-        this.options = options;
-    }
-    register(req) {
-        const selfAid = String(req.selfAid || '').trim();
-        const channelName = String(req.channelName || '').trim();
-        const primaryId = String(req.primaryId || '').trim();
-        const now = req.now ?? Date.now();
-        const code = req.code ? String(req.code).trim() : generateBindCode();
-        if (!isValidAid(selfAid))
-            return { ok: false, error: `invalid selfAid: ${req.selfAid}` };
-        if (!channelName)
-            return { ok: false, error: 'missing channelName' };
-        if (!isValidAid(primaryId))
-            return { ok: false, error: `invalid primaryId: ${req.primaryId}` };
-        if (!/^\d{6}$/.test(code))
-            return { ok: false, error: 'binding code must be 6 digits' };
-        const key = pendingBindKey(selfAid, channelName);
-        const replaced = this.pending.has(key);
-        const item = {
-            selfAid,
-            channelName,
-            primaryId,
-            code,
-            createdAt: now,
-            expiresAt: now + CONTACT_BIND_CODE_TTL_MS,
-            failedAttempts: 0,
-            maxFailedAttempts: CONTACT_BIND_MAX_FAILED_ATTEMPTS,
-        };
-        this.pending.set(key, item);
-        return { ok: true, code, expiresAt: item.expiresAt, replaced };
-    }
-    handle(ctx) {
-        if (ctx.channelType !== this.options.channelType)
-            return { handled: false };
-        const selfAid = String(ctx.selfAid || '').trim();
-        const channelName = String(ctx.channelName || '').trim();
-        if (!selfAid || !channelName)
-            return { handled: false };
-        const key = pendingBindKey(selfAid, channelName);
-        const item = this.pending.get(key);
-        if (!item)
-            return { handled: false };
-        const now = ctx.now ?? Date.now();
-        if (now >= item.expiresAt) {
-            this.pending.delete(key);
-            return {
-                handled: true,
-                status: 'expired',
-                remainingAttempts: 0,
-                reply: `${this.options.displayName}身份绑定码已超时，本次绑定失败。请重新执行 ${this.options.initCommand} 并再次绑定。`,
-            };
-        }
-        if (ctx.chatType !== 'private')
-            return { handled: false };
-        const input = String(ctx.content ?? '').trim();
-        if (!/^\d{6}$/.test(input)) {
-            return {
-                handled: true,
-                status: 'format',
-                reply: '请直接发送 6 位数字绑定码。',
-                remainingAttempts: item.maxFailedAttempts - item.failedAttempts,
-            };
-        }
-        if (input !== item.code) {
-            item.failedAttempts += 1;
-            const remaining = Math.max(0, item.maxFailedAttempts - item.failedAttempts);
-            if (remaining === 0) {
-                this.pending.delete(key);
-                return {
-                    handled: true,
-                    status: 'failed',
-                    remainingAttempts: 0,
-                    reply: `绑定码无效，本次${this.options.displayName}身份绑定失败。请重新执行 ${this.options.initCommand} 并再次绑定。`,
-                };
-            }
-            return {
-                handled: true,
-                status: 'wrong-code',
-                remainingAttempts: remaining,
-                reply: '绑定码错误，请重新发送 6 位数字绑定码。',
-            };
-        }
-        const actorId = String(ctx.actorId || '').trim();
-        if (!actorId) {
-            return {
-                handled: true,
-                status: 'missing-actor',
-                remainingAttempts: item.maxFailedAttempts - item.failedAttempts,
-                reply: `无法识别当前${this.options.displayName}发送者身份，未建立绑定。请重新发送绑定码或重新执行绑定流程。`,
-            };
-        }
-        try {
-            bindContactAlias(item.selfAid, item.primaryId, this.options.channelType, actorId, item.channelName);
-            this.pending.delete(key);
-            return {
-                handled: true,
-                status: 'bound',
-                reply: `${this.options.displayName}身份绑定成功：${item.channelName}:${encodeURIComponent(actorId)} -> ${item.primaryId}`,
-            };
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            return {
-                handled: true,
-                status: 'write-failed',
-                remainingAttempts: item.maxFailedAttempts - item.failedAttempts,
-                reply: `${this.options.displayName}身份绑定写入失败：${message}`,
-            };
-        }
-    }
-    get(selfAid, channelName) {
-        const item = this.pending.get(pendingBindKey(selfAid, channelName));
-        return item ? { ...item } : null;
-    }
-    clear() {
-        this.pending.clear();
-    }
-}
-function generateBindCode() {
-    return String(randomInt(0, 1_000_000)).padStart(6, '0');
-}
-function pendingBindKey(selfAid, channelName) {
-    return `${String(selfAid || '').trim()}\u0000${String(channelName || '').trim()}`;
-}