feat: 史官 agentic loop + read/update profile 工具 (#45)

* feat(historian): 史官支持 read_profile/update_profile 工具，改为 agentic loop

- 新增 read_profile 工具，可读取任意 entity_type:entity_id 的侧写
- update_profile 工具新增 entity_type/entity_id 参数
- _merge_profile_target 改为最多 100 轮 agentic loop，LLM 自主决策读写
- 抽取 _write_profile 辅助方法
- 提示词去掉预注入 current_profile，改为要求先调 read_profile 再修改

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs: 更新项目描述，突出认知记忆架构与 WebUI

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(historian): 修复 update_profile 验证缺失、名称回退丢失与空 summary 终止问题

- update_profile 新增 entity_type/entity_id 合法性校验（含 isalnum 防路径穿越）
- 名称回退补充读取现有 profile frontmatter，避免覆写为 UID/GID 占位符
- 空 summary 时改为 done=False，允许 LLM 看到错误后重试

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(historian): 补全 read_profile 验证、移除 done=False 覆盖、删除死代码

- read_profile 补充 isalnum() 校验，与 update_profile 对齐
- 空 summary 时移除显式 done=False，避免覆盖同批次先前的 done=True
- 删除不再使用的 _resolve_profile_name 方法

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(historian): 修复跨实体写入时 preferred_name 错误兜底

写入非目标实体时不再使用 target 的 preferred_name，
改为读取该实体现有 profile 的 frontmatter name 作为回退

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(historian): 提示词说明 update_profile 调用后流程立即终止

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(historian): name_hint 优先于 llm_name，恢复名称锁定保护

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: 69gg

README.md

@@ -3,7 +3,7 @@
     <td width="70%" valign="top">
       <div align="center">
         <h1>Undefined</h1>
-        <em>A high-performance, highly scalable QQ group and private chat robot based on a self-developed architecture.</em>
+        <em>QQ bot platform with cognitive memory architecture and multi-agent Skills, via OneBot V11.</em>
         <br/><br/>
         <a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.11--3.13-blue.svg" alt="Python"></a>
         <a href="https://docs.astral.sh/uv/"><img src="https://img.shields.io/badge/uv-auto%20python%20manager-6a5acd.svg" alt="uv"></a>
@@ -14,7 +14,7 @@
       </div>
       <h3>项目简介</h3>
       <p>
-        <strong>Undefined</strong> 是一个功能强大的 QQ 机器人平台，采用全新的 <strong>自研 Skills</strong> 架构。基于现代 Python 异步技术栈构建，它不仅提供基础的对话能力，更通过内置的多个智能 Agent 实现代码分析、网络搜索、娱乐互动等多模态能力，具备创新的<strong>无阻塞认知记忆系统</strong>。
+        <strong>Undefined</strong> 是一个基于 Python 异步架构的高性能 QQ 机器人平台，搭载<strong>认知记忆架构</strong>，采用自研 <strong>Skills</strong> 系统，内置多个智能 Agent，支持代码分析、网络搜索、娱乐互动等多模态能力，并提供 <strong>WebUI</strong> 在线管理。
       </p>
     </td>
     <td width="30%">

pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "Undefined-bot"
-version = "3.0.3"
-description = "A high-performance, highly scalable QQ group and private chat robot based on a self-developed architecture."
+version = "3.1.0"
+description = "QQ bot platform with cognitive memory architecture and multi-agent Skills, via OneBot V11."
 readme = "README.md"
 authors = [
   { name = "Null", email = "pylindex@qq.com"  }

res/prompts/historian_profile_merge.md

@@ -6,6 +6,11 @@
 3. 当新信息不稳定、一次性、无法确认长期性时，必须跳过更新（`skip=true`）。
 4. 不得输出或暗示其他实体侧写内容。
 
+工具使用规则（严格执行）：
+- **修改任何侧写前，必须先调用 `read_profile` 查看其当前内容**，确认已读取后再决定是否调用 `update_profile`。
+- 可以调用 `read_profile` 查看任意实体的侧写（不限于目标实体）。
+- 只允许通过 `update_profile` 工具写入侧写，禁止输出普通文本内容。
+
 目标实体：
 - entity_type: {target_entity_type}
 - entity_id: {target_entity_id}
@@ -29,9 +34,6 @@
 - 最近消息参考:
 {recent_messages}
 
-当前侧写：
-{current_profile}
-
 该实体的历史事件（供参考，帮助你判断哪些特征应保留）：
 {historical_events}
 
@@ -42,28 +44,30 @@
 {observations}
 
 要求：
-1. 保留现有稳定特征，整合新信息；参考历史事件判断现有特征是否仍然成立，避免因本轮未提及而误删长期稳定特征
-2. 矛盾时以新信息为准
-3. tags 只写"这个实体**是什么**"（身份/角色/核心领域），不写"聊过什么话题"；最多 10 个，话题级细节已在 summary 中覆盖。若现有 tags 不符合此规范（数量过多或含话题标签），直接按规范重写，不必保留旧 tags
-4. 保持简洁，只记录长期稳定的特征
-5. 侧写是“稳定画像”，不是“事件流水账”
-6. 若 `current_profile` 本身不符合以上规范，可直接整体重写为合规版本（不必保留其原有写法）
+1. **先调用 `read_profile` 读取目标实体的当前侧写**，再决定如何更新
+2. 保留现有稳定特征，整合新信息；参考历史事件判断现有特征是否仍然成立，避免因本轮未提及而误删长期稳定特征
+3. 矛盾时以新信息为准
+4. tags 只写"这个实体**是什么**"（身份/角色/核心领域），不写"聊过什么话题"；最多 10 个，话题级细节已在 summary 中覆盖。若现有 tags 不符合此规范（数量过多或含话题标签），直接按规范重写，不必保留旧 tags
+5. 保持简洁，只记录长期稳定的特征
+6. 侧写是"稳定画像"，不是"事件流水账"
+7. 若 `current_profile` 本身不符合以上规范，可直接整体重写为合规版本（不必保留其原有写法）
 
 严禁写入以下内容（这些属于事件记忆，不应进入侧写）：
 - 某次/近期/今天/昨天的具体经过
 - 具体数字统计（如 token 消耗、日均、高峰值）
 - 具体分支名、提交细节、安装排障步骤、一次性报错
-- “曾讨论/刚确认/近期提及/某次分享”等时序性描述
+- "曾讨论/刚确认/近期提及/某次分享"等时序性描述
 
 若本轮只有事件细节、无法抽象为长期稳定特征，必须 `skip=true`。
 
 `summary` 输出格式约束：
 - 使用 Markdown 项目符号（`- `）输出 4-8 条
-- 每条只写“长期稳定特征/偏好/角色关系/沟通风格”
+- 每条只写"长期稳定特征/偏好/角色关系/沟通风格"
 - 句子短而概括，避免冗长复述
 
 输出规则（调用 `update_profile` 工具）：
-- 若应跳过更新：`skip=true`，并给出 `skip_reason`；`summary` 置空字符串，`tags` 可为空数组。
-- 若执行更新：`skip=false`，返回 `summary` 和 `tags`。
+- 若应跳过更新：`skip=true`，并给出 `skip_reason`；`summary` 置空字符串，`tags` 可为空数组。**调用后流程立即终止，无法再执行任何操作，请确保在此之前已完成所有必要的读取与更新。**
+- 若执行更新：`skip=false`，返回 `summary` 和 `tags`。同样，调用后流程立即终止。
+- `entity_type` 和 `entity_id` 必须与目标实体一致。
 - `name` 使用目标实体的显示名（优先 `{target_display_name}`），不要把 `{target_entity_id}` 当昵称随意改写。
 - 必须通过 `update_profile` 工具返回结构化参数，禁止输出普通文本内容。

src/Undefined/__init__.py

@@ -1,3 +1,3 @@
 """Undefined - A high-performance, highly scalable QQ group and private chat robot based on a self-developed architecture."""
 
-__version__ = "3.0.3"
+__version__ = "3.1.0"