From 5b8c7a3ef3719e43bff3be1d50720ea975892948 Mon Sep 17 00:00:00 2001 From: AskaEth Date: Wed, 7 Oct 2026 14:09:01 +0800 Subject: [PATCH] =?UTF-8?q?docs(=E6=9E=B6=E6=9E=84):=20=E6=BE=84=E6=B8=85?= =?UTF-8?q?=E5=8D=95=E7=AB=AF=E5=8F=A3=E7=BA=A2=E7=BA=BF=E5=8F=AA=E7=BA=A6?= =?UTF-8?q?=E6=9D=9F=E6=A1=86=E6=9E=B6=E8=87=AA=E8=BA=AB=EF=BC=8C=E6=89=A9?= =?UTF-8?q?=E5=B1=95=E6=8F=92=E4=BB=B6=E5=8F=AF=E5=BC=80=E7=AB=AF=E5=8F=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 主人 2026-10-07 口径补充：原先把这条红线读成「任何组件都不许开端口」过宽了。 - AGENTS.md §9：红线加限定语（只约束 Cyrene 框架自身）；qq-obv11 那条已登记 例外升格为一般规则的实例；新增插件开端口的四条护栏（显式配置 / 默认绑 127.0.0.1 / 日志与审计 / 不得绕过身份判定）—— 护栏由主代理拟，待主人逐条确认 - Docs/api-client.md v0.88：澄清「插件监听端口不在契约范围内」；零破坏性变更， 无新端点 / 无新帧 / 无字段形状变化，路由计数不变（14 + 25 + 40 = 79） - README.md：用户侧表述同步 DevDocs 侧同步（不进 git）：design/13 §0、design/09 §5、design/08 §4、恢复提示词红线节。 --- AGENTS.md | 6 ++++-- Docs/api-client.md | 16 +++++++++++++--- README.md | 2 +- 3 files changed, 18 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index c80032a..d81e45c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -36,8 +36,10 @@ - 目的：防主会话上下文超限触发压缩；压缩后靠本文件 + `DevDocs/工作小结/00-当前态.md` 恢复锚点，继续当监工。 ## 9. 全球红线（跨里程碑，必须遵守；违反即架构偏离） -- **单二进制、单端口 `:8080`、零跨进程 IPC**：模块间同步走**进程内接口 + 依赖注入**（直接方法调用），异步走**进程内 `bus`**；**不另开监听端口、不 HTTP 互调**。 - - ♢ **已登记例外（主人 2026-10-04 裁决）**：`qq-obv11` 渠道的 **OneBot 反连（server）模式**需要独立 `net.Listen` 端口 —— **仅限该渠道的 server 模式**，且端口必须由配置**显式给出**（`listen_addr`），**不得默认开启**；其余渠道/模式一律不得新开监听端口。规格见 `design/08 §4`、`design/13 §0`。 +- **单二进制、单端口 `:8080`、零跨进程 IPC**（🔴 **本条约束的是 Cyrene 框架自身，不约束扩展插件**）：框架模块间同步走**进程内接口 + 依赖注入**（直接方法调用），异步走**进程内 `bus`**；**框架自身不另开监听端口、不 HTTP 互调**。 + - 🆕 **2026-10-07 主人口径补充（原「豁免」升格为一般规则）**：**扩展插件不受本条约束** —— `plugins/` 下的渠道适配器与工具、MCP server、以及插件自己拉起的本地伴随进程/服务，**可以开自己的监听端口、可以有自己的进程形态**。这**不是「例外」，是插件的正当能力**；原先只为 `qq-obv11` 登记的那条例外，**随之由「例外」变为本条一般规则的一个实例**（该渠道规格仍见 `design/08 §4`）。 + - 🔴 **插件开端口的四条护栏**（主代理拟的落地口径，**待主人逐条确认**）：① 端口/地址**必须由配置显式给出**，**不得默认开启、不得写死**；② **默认绑 `127.0.0.1`**，要对外暴露必须由 `.env` 显式决定（与框架暴露面同一套口径）；③ **必须登记日志来源与审计**（谁开的、绑在哪）；④ **端口不得成为绕过身份/权限判定的入口** —— actor 元数据 + 白名单 + 策略引擎仍是唯一判据，端口不是后门。 + - 「**零跨进程 IPC**」的原意**仍然有效**：**框架内部模块**不得为解耦而拆成多进程/多服务、不得 HTTP 硬编码 URL 互调（详见 `DevDocs/00-overview.md`）。**框架与插件之间的边界通信不在本条约束内**；但框架**不得**因此把自身模块拆出去变成插件。 - **身份识别靠 channel 层强类型 `actor` 元数据 + 策略引擎**，**绝不靠提示词/LLM 判断**（主人/群聊/陌生人判定与权限永远由 actor 元数据 + 白名单 + policy engine 决定）。 - **人格 = 身份**（**不限制能力**）；**行为模式 = 呈现**（≠边界，可热切换、不构成能力边界）；**能力全局全能**；**前端（Web）是第一公民**。 - **IM 是镜像**：只 chat 文本，Web 不回流 IM；输出一律 chat 文本。 diff --git a/Docs/api-client.md b/Docs/api-client.md index 83d305e..6d14e83 100644 --- a/Docs/api-client.md +++ b/Docs/api-client.md @@ -1,6 +1,6 @@ # Cyrene v2 客户端 API 契约 -> **契约版本：`v0.87`**（上一版 `v0.86`，其条目见 §6；`v0.85` / `v0.84` / `v0.83` / `v0.82` / `v0.81` / `v0.80` / `v0.79` / `v0.78` / `v0.77` / `v0.76` / `v0.75` / `v0.74` / `v0.73` / `v0.72` / `v0.71` 及更早见本文件 §6，`v0.67` 及更早的基线已归档、只读：`Docs/archive/api-client.v0.65.md`）。 +> **契约版本：`v0.88`**（上一版 `v0.87`，其条目见 §6；`v0.86` / `v0.85` / `v0.84` / `v0.83` / `v0.82` / `v0.81` / `v0.80` / `v0.79` / `v0.78` / `v0.77` / `v0.76` / `v0.75` / `v0.74` / `v0.73` / `v0.72` / `v0.71` 及更早见本文件 §6，`v0.67` 及更早的基线已归档、只读：`Docs/archive/api-client.v0.65.md`）。 > **读者**：Web 前端 / 移动端原生客户端（含 Android）/ IM 桥接等**跨平台客户端开发者**。 > **唯一真源 = 当前代码**（`internal/services/gateway/*` 等）。本文档由代码逐条核对得出；与代码不符时**以代码为准**，并回改本文档。 > **旧的超详细版已归档、只读**：`Docs/archive/api-client.v0.65.md`（412 KB，含 v0.28→v0.65 全部历史条目）与 `Docs/archive/api-reference.v0.65.md`（170 KB，后端全量字段级文档）。归档的原因是**结构性臃肿 + 历史条目并列 + 长期漂移**；本文档**不复制**那段历史，需要考古时去归档。 @@ -50,7 +50,7 @@ ### 0.1 基址与版本 - **Base URL**：`http://:`。`PORT` 默认 **8080**（`env:"PORT" default:"8080"`）；生产一般经反代/HTTPS，运行实例可能自定义端口。 -- **唯一对外端口**：单二进制、单端口（运行实例实测 `:10942`）。REST、WS、管理 API、静态资源**全在同一端口**；不另有监听端口（唯一登记例外：`qq-obv11` 渠道 OneBot 反连 server 模式，见 design/08 §4，与客户端契约无关）。 +- **框架唯一对外端口**：单二进制、单端口（运行实例实测 `:10942`）。REST、WS、管理 API、静态资源**全在同一端口**。🆕 **2026-10-07 口径补充（v0.88）**：这条「单端口」约束**只约束 Cyrene 框架自身**；**扩展插件**（渠道适配器 / 工具 / MCP server / 插件自拉的本地伴随服务）**可以开自己的监听端口、可以有自己的进程形态** —— 那些端口**不在本契约范围内**（客户端一律只连这一个网关端口）。原「`qq-obv11` 渠道 OneBot 反连 server 模式」那条例外随之**由「例外」升格为一般规则的实例**（见 `design/08 §4`）。 - **版本前缀**： - 用户侧 REST：`/api/v1/{resource}` - 管理侧 REST：`/api/v1/admin/*` @@ -1487,7 +1487,17 @@ curl -s -X POST -H "X-API-Key: $KEY" \ > 只保留最近若干版（**v0.60 起**）；更早的全部历史见归档 `Docs/archive/api-client.v0.65.md` §5（v0.28 → v0.59）。 > 每版一句话 + 三档标注。**三档定义见 [§0.4](#04-三档标注惯例)。** -### v0.87（当前契约版本） +### v0.88（当前契约版本） + +**「单端口红线的适用范围澄清」版 —— 不改任何端点 / 帧 / 字段，只澄清一个边界**（依据：主人 2026-10-07 口径补充「关于不允许开新端口的红线，我加一个补充。那是对 cyrene 框架自身的约束，而不是扩展插件的。」） + +- 🔴 **澄清内容**：「单二进制、单端口、零跨进程 IPC」这条红线**只约束 Cyrene 框架自身** —— 框架不另开监听端口、不 HTTP 互调（§0.1 已更新措辞为「**框架**唯一对外端口」）。 +- **扩展插件不受该约束**：`plugins/` 下的渠道适配器与工具、MCP server、以及插件自己拉起的本地伴随进程/服务，**可以开自己的监听端口、可以有自己的进程形态**。**那些端口不在本契约范围内** —— **客户端一律只连这一个网关端口**，不得假定能从插件端口取到任何契约面。 +- 原「`qq-obv11` 渠道 OneBot 反连 server 模式」那条例外**由「例外」升格为一般规则的实例**（规格仍见 `design/08 §4`）。 +- **插件端口的四条护栏**（主代理拟，**待主人逐条确认**）：① 端口/地址必须由配置**显式给出**，不得默认开启、不得写死；② **默认绑 `127.0.0.1`**，要对外暴露必须由 `.env` 显式决定；③ 必须**登记日志来源与审计**；④ 端口**不得成为绕过身份/权限判定的入口**。 +- **兼容性**：**零破坏性变更** —— 无新端点、无新帧、无字段形状变化、**§2.0 路由计数不变**（`14 + 25 + 40 = 79`）。唯一对客户端的要求是：**别把「插件监听端口」当成契约面**（此前也从未有过这种端口与契约的关联）。 + +### v0.87 **「搜索 provider 扩到八家」版 —— 名单扩充，端点形状与错误码一字未改**（切片 `agent-389`，本次提交；依据：主人「我看之前不是走有头CDP扒了好几家搜索提供商的接口方式在本地参考文档吗？为什么不都做一下适配？」+「优先只做国内能用到的几家」。） diff --git a/README.md b/README.md index 50a2e1d..686005b 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ ### ✅ 已实现 -- **单二进制、进程内协作** — 所有服务同进程打包，仅网关一个对外端口（默认 `:8080`）；模块间走进程内接口 + 事件总线，**零跨进程 IPC**。唯一登记例外：`qq-obv11` 渠道的 OneBot 反连（server）模式可开监听端口，且**必须由配置显式给出 `listen_addr`**，不默认开 +- **单二进制、进程内协作** — **框架**的所有服务同进程打包、**框架**仅网关一个对外端口（默认 `:8080`）；框架模块间走进程内接口 + 事件总线，**零跨进程 IPC**。🔴 **2026-10-07 口径补充：该红线只约束框架自身，不约束扩展插件** —— `plugins/` 下的渠道适配器与工具、MCP server、以及插件自己拉起的本地伴随服务**可以开自己的监听端口、可以有自己的进程形态**（原「`qq-obv11` 反连 server 模式」那条例外随之升格为一般规则的实例）。插件端口仍须：**由配置显式给出**、**默认绑 `127.0.0.1`**、**登记日志与审计**、**不得绕过身份判定** - **人格化陪伴** — 多人格（`configs/personas/*.yaml`）/ 情绪状态机 / 好感度；**人格 = 身份**（不限制能力）、per-persona 记忆隔离、能力全局共享 - **通用 Agent 运行时** — 多供应商 LLM（per-role 路由 + 降级：主 → 备 → 本地，本地级默认关）、工具调用（**8 轮上限**）、流式输出、子代理编排（生命周期 / 结果合并 / 并行上限 / 超时 / 防失控）、会话持久化 + 主·次级会话、上下文压缩（预算按模型窗口推导） - **记忆系统** — **三类作用域隔离**（用户习惯全局共享 / 角色日常他角色只读 / 项目人人读写 + 项目索引分层）、相关性 + 最近度检索、衰减、溯源、RAG；**LLM 异步提取**（每轮落定后后台提取，手工提取兜底）；**定期记忆整理**（低峰后台任务，只产候选建议、绝不自动改写）；**入库前审查**（D3：新记忆落库前先判定 merge / modify / create / skip，软合并可 `revert` 回滚）