chenxin/hunjing
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
42513d13c65f5601de9f10606f111e8eff423860
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

12 KiB
Raw Blame History

参考项目研究与采纳结论

研究日期：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 的采纳设计见记忆与知识架构。

来源：

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 进程内实现已成为可测量瓶颈。

来源：

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 后重新生成另一份内容。

官方资料：

Reference in new issue View Git Blame Copy Permalink