chenxin/hunjing
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
dfce60f7db0cd8e47ac05aed64e40a588849de2c
hunjing/docs/research/reference-projects.md
T
chenxin 42513d13c6 📝 docs: 建立魂镜完整 1.0 设计文档体系 
- 产品层：产品宪章与永久禁域、产品定义、完整 1.0 范围与发布门、道家文化语言体系、指标与反指标
- 研究层：参考项目研究（deepseek-harness、pi、MemOS、模型网关）、灵台原生引擎研究（业界原生引擎架构理念与道家文化出处）
- 架构层：系统、Agent 运行时（周天体系）、插件系统、灵台引擎（C++ 双形态）、媒体与设备、社区协作市场、前端富内容渲染、数据、记忆与知识
- 契约层：协议与稳定标识、API 总体约定、Native API、兼容网关、实时与 Webhook、内部端口、统一 ContentBlock 与流式（含分支对话交互态）、灵台 C ABI 与 gRPC Service、API 表面、HTTP 与事件、运行观测
- 决策：ADR-001 至 ADR-023（模块化单体、每 attempt 持久化、候选记忆、OAuth 2.1、灵台引擎、双形态部署、大周天演化、宪章、三界作用域、私箧与保全态、叩心、周天统一等）
- 交付：WP-01 至 WP-15 实施 TODO 与设计阶段交接文档
- 工程：AGENTS.md 工程规则（含 C++/灵台规范）、CLAUDE.md 引用、.gitignore
2026-09-09 21:07:14 +08:00

158 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 参考项目研究与采纳结论
> 研究日期：2026-09-02 至 2026-09-03。外部仓库会变化；下列 commit 用于固定研究证据，不表示运行依赖。
## 1. 结论
- 可以参考 deepseek-harness 的“一切皆插件”，但准确边界应是：**所有可扩展能力皆插件，不是所有系统职责皆插件。**
- Core 必须保留最小、不可替换的安全和一致性职责：身份、授权、租户隔离、审批、事务、审计、插件加载验证和执行中止。
- 1.0 业务核心采用模块化单体，不复制参考项目源码；同时完整实现双轨插件 Runtime、Registry、开发 SDK 和插件市场。
- 只有 bundled Core plugin 可进主进程；第三方本地代码插件进入独立进程或容器，声明式/远程插件默认受限。
- 角色卡只作为导入材料；记忆、身份和会话运行记录分别建模。
- 模型网关职责必须在 1.0 完整实现；先作为明确模块交付，是否物理拆为独立 Go 服务由扩缩容、故障域和区域路由需求决定。
## 2. DeepSeek Harness 与 pi
### 2.1 DeepSeek Harness
研究基线：`dd6322d604e00eec1ba5e0c8541159906a21094a`；研究时最新：`4e84901e6471b79ec0338099867ebb4606d12bb5`。
可采纳证据：
- `docs/architecture.zh.md`：Cordis 插件提供 service、typed event 和 reversible effect；model adapter、tool registry、session log 与 agent loop 都能由插件贡献。
- `packages/core/session/src/types.ts`：Session 使用类型化事件表达 turn、assistant message、tool call/result 和 request header。
- `packages/extensions/cordis-host-runner/src/registry.ts`、`lifecycle.ts`：插件、Package、Run 有独立生命周期；注册和 effect 可撤销；加载失败清理已创建资源。
- `packages/sandbox/sandbox/src/index.ts`：无可用隔离后端时 fail closed，禁止静默退化为未隔离执行。
- `packages/subagent/subagent/src/child-agent.ts`：子 Agent 有深度上限，工具过滤、沙箱和审批策略只能收窄。
不照搬：
- Cordis 作为整个产品内核会引入高学习成本；本项目只吸收生命周期、依赖声明、可撤销注册和事件机制。
- `node:vm` 不是安全隔离；参考项目源码也明确其 closure 仍可逃逸。未可信插件必须进独立进程/容器或远程协议。
- Profile/Bundle/Patch 的完整配置层不是 1.0 必需形态；插件 Manifest、安装配置、权限授予和 Run Snapshot 已覆盖当前需求。
来源：<https://github.com/deepseek-ai/deepseek-harness>
### 2.2 pi
研究 commit：`96317e50b8d6e7f6d0e47fd29122baf1461c00f5`。
可采纳证据：
- `packages/coding-agent/src/core/extensions/loader.ts`：发现、加载、初始化、提交/丢弃和 runtime invalidation 分离。
- `docs/extensions.md`：扩展可贡献 events、tools、commands；session replacement 会 shutdown、reload、rebind、start。
- 项目本地扩展具有完整系统权限，只应在可信项目中启用；扩展异常记录后不必拖垮整个 Agent，但工具调用错误应 fail safe。
不照搬：
- 1.0 不从项目目录隐式加载任意代码；安装必须经过 Registry/本地包校验和明确权限确认。
- UI 扩展进入 1.0，但使用声明式组件或隔离消息协议；快捷键和命令只有插件真实声明时注册，不作为所有插件的强制样板。
来源：<https://github.com/earendil-works/pi>
## 3. 角色与记忆项目
| 项目 | 采纳 | 不采纳 |
| --- | --- | --- |
| SillyTavern | 角色卡、角色/聊天/Persona/全局 Lore 作用域、Lorebook 触发与预算 | 角色卡等同身份；聊天向量等同长期记忆 |
| Memory-Palace | L0/L1/L2 派生链、写入审查、快照、版本、衰减候选、混合检索 | 将其直接作为完整角色或会话系统 |
| nocturne_memory | Namespace、Boot Context、版本链和人工清理 | 删除访问路径却保留正文仍称“永久删除” |
| TencentDB-Agent-Memory | Conversation→Atomic Memory→Scenario→Profile 分层；Team/Agent/User/Session 作用域 | Profile 等同角色人格；仅靠作用域字段替代鉴权 |
| mem0 | `user_id`/`agent_id`/`run_id` 过滤、过期和 History API | 把通用 Memory API 当作事实源或完整审计 |
| MemOS | 类型化可检查记忆、来源链、快速摄取后异步精炼、后台整理、基于已召回 ID 的纠正和公开评测框架 | MemCube 等同授权域；原地更新权威记忆；开放 metadata 代替契约；把 KV cache、隐藏状态或权重适配当作 1.0 权威记忆 |
| Artemis / NagaAgent | 角色配置与任务 Agent 分离、结构化事实抽取、SSE 工具循环 | 任务清理等同记忆删除；文件复制等同身份迁移 |
### MemOS
研究基线：`28dfb4e7d3adad1c93fd5574675f913921367d36`；许可证：Apache-2.0。
可采纳证据：
- `docs/en/open_source/home/architecture.md`：MOS、MemCube、Memory 与 Scheduler 分层；文本记忆可编辑、可追踪，官方建议从 GeneralTextMemory 起步，再按实测引入图或激活记忆。
- `src/memos/memories/textual/item.py`：`SourceMessage` 保存消息、文档、文件和图像来源；文本记忆区分状态、版本、历史、置信度、会话和显式/隐式偏好。
- `docs/en/open_source/modules/mem_reader.md`：Fast 模式先规范化、切片和索引，Fine 模式再用模型提取；支持后台从原始快照精炼为结构化记忆。
- `docs/en/open_source/modules/mem_scheduler.md`：摄取、整理、偏好和反馈是异步任务，并记录队列、延迟、容量和操作日志。
- `docs/en/open_source/modules/mem_feedback.md`：纠正优先携带上一轮已召回 Memory ID，以降低重新搜索误改；旧内容归档并保留版本关系。
- `evaluation/`：以 LoCoMo、LongMemEval 等数据集比较长对话、时间和长期记忆能力，证明记忆系统必须有独立评测，而不能只验证向量查询成功。
不照搬：
- MemCube 的 user/cube 关系不足以表达 Hunjing 的 Personal Domain、Character、Workspace、发布与财务授权，不能成为本项目权限模型。
- `BaseTextMemory.update()` 和部分实现的原地更新不满足 Hunjing 的不可变 MemoryVersion 与 ETag 并发要求。
- `TextualMemoryMetadata(extra="allow")` 适合研究框架扩展，不适合作为公开稳定契约；Hunjing 新字段必须进入 OpenAPI/Schema。
- MemOS 的 UserManager 运行时 `create_all`、同步 I/O 和本地 root 用户初始化不进入生产身份边界。
- MemOS 的 WorkingMemory 特殊检索路径不能作为隔离范例；Hunjing 的临时上下文同样必须校验 Personal Domain/Workspace、Character、Conversation、Branch 与 Run。
- MemOS 当前认证可由环境变量默认关闭，并使用内部 Header/共享秘密判断服务身份；Hunjing 不允许整体关闭认证，也不以用户可提交 Header 代替 workload identity/mTLS。
- Activation/KV-cache 与 Parametric/LoRA memory 是模型运行优化或权重适配；1.0 不把它们称为用户可携、可纠正的权威长期记忆。
- 外部 benchmark 宣传分数不作为 Hunjing 发布证据；必须固定数据集、版本、模型、检索配置和自有安全测试。
Hunjing 的采纳设计见[记忆与知识架构](../architecture/memory-and-knowledge.md)。
来源：
- <https://github.com/SillyTavern/SillyTavern>
- <https://github.com/AGI-is-going-to-arrive/Memory-Palace>
- <https://github.com/Dataojitori/nocturne_memory>
- <https://github.com/TencentCloud/TencentDB-Agent-Memory>
- <https://github.com/mem0ai/mem0>
- <https://github.com/MemTensor/MemOS>
- <https://github.com/momori777/Artemis>
- <https://github.com/RTGS2017/NagaAgent>
## 4. 模型网关项目
aiway、octopus、new-api、metapi、axonhub 与 lens 共同证明了网关的成熟需求：供应商适配、逻辑模型、端点池、密钥、限流、用量、计费、流式转发和管理面。Hunjing 只采用这些职责，不复制任何一个项目的全部管理模型。
可追溯证据：
- aiway 的 `docs/gateway/{auth,monitoring,security}.md` 与 `gateway/src/handler/{auth,logger,response,routing}.rs` 分离认证、日志、响应和路由。
- octopus 的 `internal/relay/{protocol,route,upstream,handler}.go` 与 `internal/server/` 展示协议、路由、上游和 API 边界。
- new-api 的 `middleware/request-id.go`、`model/log.go`、`controller/audit.go`、`relay/helper/price.go` 覆盖 request ID、usage log、操作审计、缓存计价与预扣；它没有替代 W3C Trace Context。
- metapi 的 `src/server/proxy-core/providers/headerUtils.ts`、`orchestration/upstreamRequest.ts`、`conductor/retryPolicy.ts` 展示 Header、上游请求和重试职责。
- axonhub 的 `docs/en/getting-started/request-processing.md`、`guides/tracing.md`、`guides/cost-tracking.md` 明确 Request/Trace/Thread 层次、缓存 token、价格版本和可关闭正文存储。
1.0 必须实现至少 OpenAI-compatible 与 Anthropic Messages 两类协议、逻辑模型路由、流式、usage、成本、BYOK 和端点治理。以下条件决定是否把已完成的网关模块物理拆成独立服务，而不是决定能力是否进入 1.0：
- 三个以上运行服务都需要模型调用；
- 网关和业务 API 需要独立扩缩容；
- BYOK、费率、端点健康或区域路由成为独立运营职责；
- Python 进程内实现已成为可测量瓶颈。
来源：
- <https://github.com/xgpxg/aiway>
- <https://github.com/bestruirui/octopus>
- <https://github.com/QuantumNous/new-api>
- <https://github.com/cita-777/metapi>
- <https://github.com/looplj/axonhub>
- <https://github.com/dyedd/lens>
## 5. 标准与官方资料
- HTTP 字段名大小写不敏感；未知字段通常由代理转发，除非明确阻止：RFC 9110 §§5.1–5.3。
- 新私有字段不使用 `X-` 前缀：RFC 6648 §3。
- Bearer token 通过 `Authorization` 和 TLS 传输，不放 URI query：RFC 6750 §§2.1、2.3、5.3。
- 分布式追踪使用 W3C `traceparent` / `tracestate`；其中不得放 PII 或业务秘密。`baggage` 只能传播低敏、低基数上下文，不能作为授权来源。
- OpenTelemetry 的 GenAI 语义约定可用于统一 Provider、模型、操作、token 和 finish reason 的 Span 属性；业务 Run/Turn ID 仍由本项目契约定义。
- Claude Prompt Cache 是严格前缀匹配，顺序为 `tools → system → messages`；usage 分开返回未缓存输入、缓存创建和缓存读取 token。
- Claude client tool 以 `tool_use.id` 与 `tool_result.tool_use_id` 关联；并行调用的结果应在一个用户消息中返回。
- OpenAI Responses/Chat 与 Anthropic Messages 的 usage 形状不同：OpenAI 可在 `input_tokens_details.cached_tokens` 报告缓存读取，Anthropic 使用 `cache_creation_input_tokens` 与 `cache_read_input_tokens`。Adapter 必须标准化但保留 `usage_source`，不能假设两者语义完全相同。
- OpenAI 返回 `x-request-id`，并允许客户端提供 `X-Client-Request-Id`；Anthropic 返回 `request-id`，错误体带 `request_id`。这些是上游请求标识，不替代本地 `Hunjing-Request-ID` 或 `traceparent`。
- 流式连接可能在 HTTP 200 后产生错误；首个用户可见流事件发出后，不允许静默切换 Provider 后重新生成另一份内容。
官方资料：
- <https://platform.openai.com/docs/api-reference>
- <https://platform.openai.com/docs/api-reference/responses>
- <https://platform.openai.com/docs/guides/prompt-caching>
- <https://platform.claude.com/docs/en/build-with-claude/prompt-caching>
- <https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview>
- <https://platform.claude.com/docs/en/api/errors>
- <https://www.w3.org/TR/trace-context/>
- <https://www.w3.org/TR/baggage/>
- <https://opentelemetry.io/docs/specs/semconv/registry/attributes/gen-ai/>
- <https://opentelemetry.io/docs/specs/semconv/http/http-spans/>
- <https://opentelemetry.io/docs/specs/semconv/url/>
- <https://datatracker.ietf.org/doc/rfc6648/>
- <https://datatracker.ietf.org/doc/rfc6750/>
Reference in new issue View Git Blame Copy Permalink