# Hunjing 文档

> 文档状态：完整 1.0 目标设计。仓库尚无对应实现，所有 TODO 完成并通过发布门前不得表述为正式 1.0。

## 阅读顺序

1. [产品定义与边界](product/product-definition.md)
2. [产品宪章](product/product-charter.md)
3. [完整 1.0 范围与发布门](product/complete-1.0-scope.md)
4. [指标与反指标](product/metrics-and-anti-metrics.md)
5. [参考项目研究](research/reference-projects.md)
6. [灵台引擎研究](research/lingtai-native-engine.md)
7. [系统架构](architecture/system-architecture.md)
8. [Agent 运行时](architecture/agent-runtime.md)
9. [插件系统](architecture/plugin-system.md)
10. [灵台引擎架构](architecture/lingtai-engine.md)
11. [媒体与设备架构](architecture/media-and-device-architecture.md)
12. [社区、协作与市场架构](architecture/community-and-marketplace.md)
13. [前端富内容实时渲染](architecture/frontend-content-rendering.md)
14. [数据架构](architecture/data-architecture.md)
15. [记忆与知识架构](architecture/memory-and-knowledge.md)
16. [中国古代神话与道家文化语言体系](product/cultural-language.md)
17. [协议与稳定标识](contracts/README.md)
18. [API 总体约定](contracts/api-conventions.md)
19. [Hunjing Native API](contracts/native-api.md)
20. [模型网关兼容 API](contracts/gateway-compatible-api.md)
21. [实时 API 与 Webhook](contracts/realtime-and-webhooks.md)
22. [内部端口、事件与插件协议](contracts/internal-api.md)
23. [统一富内容与流式协议](contracts/content-blocks-and-streaming.md)
24. [Lingtai C ABI](contracts/lingtai-ffi.md)
25. [Lingtai Service](contracts/lingtai-service.md)
26. [1.0 API 表面总表](contracts/api-surface.md)
27. [HTTP 与事件契约](contracts/http-and-events.md)
28. [运行观测契约](contracts/run-observability.md)
29. [安全与诊断访问](security/security-and-diagnostics.md)
30. [架构决策](decisions/README.md)
31. [1.0 实施 TODO](delivery/implementation-roadmap.md)
32. [设计阶段交接文档](delivery/handoff.md)

## 文档分类

| 目录 | 职责 | 不承载 |
| --- | --- | --- |
| `product/` | 1.0 用户、范围、验收和 2.0 边界 | 代码结构和供应商细节 |
| `research/` | 外部证据、采纳与拒绝理由 | 项目契约 |
| `architecture/` | 组件、运行时、媒体、生态、数据与扩展边界 | 稳定枚举值 |
| `contracts/` | ID、字段、请求头、事件和错误 | 产品愿景 |
| `security/` | 信任边界、授权、交易、内容治理和诊断访问 | 普通功能说明 |
| `decisions/` | 已作出的重大取舍及后果 | 教程 |
| `delivery/` | 1.0 工作包 TODO、验收证据、统一发布门和阶段交接 | 2.0 实现计划 |

## 事实优先级

```mermaid
flowchart LR
  P[产品定义] --> D[架构决策]
  D --> C[契约]
  C --> I[实现]
  I --> T[测试与运行证据]
```

发生冲突时，上游定义约束下游；运行事实不能被文档否认。实现与文档不同时先记录偏差，再决定修正文档还是实现。

## 1.0 维护规则

- 稳定 ID、枚举、事件名、请求头和错误码只在 `contracts/` 定义。
- 架构文档引用契约名，不复制完整值集。
- 外部项目只提供证据和模式，不自动成为运行依赖。
- Mermaid 使用短标签和标准图类型，不嵌入主题样式。
- 新文档必须从本索引可达；删除文档必须同步入口。
- Native Message、社区内容和 Agent 输出使用统一类型化 ContentBlock；Markdown 内嵌 Mermaid/数学/代码在服务端规范化，前端按分级实时策略安全渲染。
- 产品界面采用完整双层文化体系；稳定工程契约保持中性英文值。
- 文档 TODO 是 1.0 必做项；正式实现不得用 TODO、`pass`、省略或假数据占位。
- 完整 3D 建模器、LLM 直接改模和物理设备控制属于已确认的 2.0 边界，其他已列能力不得静默移出 1.0。